TypeDialog/docs/DEVELOPMENT.md

Development Guide

Guide for local TypeDialog development using just command orchestration.

Quick Start

# See all available commands
just --list

# Show help
just help

# Get help for specific module
just help build        # Build commands
just help test         # Test commands
just help dev          # Development utilities
just help ci           # CI/CD pipeline
just help distro       # Distribution & packaging

Common Workflows

Setup Development Environment

# 1. Clone and enter repository
git clone https://github.com/anthropics/typedialog.git
cd typedialog

# 2. Verify installation (see INSTALLATION.md)
rustc --version && cargo --version && just --version

# 3. Build project
just build::default

# 4. Run tests
just test::all

Format & Lint Code

# Format code
just fmt

# Check formatting (without changes)
just fmt-check

# Run linter
just lint

# Auto-fix linter warnings
just lint-fix

# All checks together
just check-all

Run Tests

# All tests (default features)
just test::all

# All tests with all features
just test::all-features

# Test specific backend
just test::cli      # CLI backend
just test::tui      # TUI backend
just test::web      # Web backend

# Test specific crate
just test::core     # typedialog-core

# Integration tests
just test::integration

# Documentation tests
just test::doc

Build Project

# Build with default features
just build::default

# Build specific backend
just build::cli     # CLI only
just build::tui     # TUI only
just build::web     # Web only

# Build all backends
just build::all-backends

# Release build (optimized)
just build::release

Watch for Changes

Watch for file changes and auto-rebuild:

just dev::watch

Requires: cargo-watch (install with cargo install cargo-watch)

Generate Documentation

# Generate docs
just dev::docs-gen

# Generate and open in browser
just dev::docs

Run Examples

See ../examples/README.md for complete examples.

Quick examples:

# Run basic example
cargo run --example form

# Run with specific backend
cargo run -p typedialog-tui --example form_with_autocompletion

# List available examples
just test::list

Just Modules

build - Build Recipes

Compile project for different backends and targets:

just build::default         # Debug build
just build::release         # Release build (optimized)
just build::cli             # CLI backend only
just build::tui             # TUI backend only
just build::web             # Web backend only
just build::all             # All variants
just build::all-backends    # All backends combined
just build::full            # All features
just build::check           # Check compilation (no build)

test - Test Suite

Run tests with various configurations:

just test::all              # All tests
just test::all-features     # With all features
just test::cli              # CLI tests
just test::tui              # TUI tests
just test::web              # Web tests
just test::core             # Core library tests
just test::bins             # Binary tests
just test::integration      # Integration tests
just test::doc              # Doc tests
just test::verbose          # Tests with output
just test::list             # List tests

dev - Development Tools

Format, lint, and document code:

just dev::fmt               # Format code
just dev::fmt-check         # Check format
just dev::lint              # Lint with clippy
just dev::lint-fix          # Auto-fix warnings
just dev::audit             # Audit dependencies
just dev::docs-gen          # Generate docs
just dev::docs              # Generate and open
just dev::build             # Build default
just dev::watch             # Watch and rebuild
just dev::check             # Check + fmt + lint
just dev::info              # Show workspace info
just dev::tree              # Dependency tree

ci - CI/CD Pipeline

Validation and build pipeline:

just ci::fmt-check          # Format validation
just ci::lint               # Linting
just ci::check              # Format + lint
just ci::test-all           # Test all features
just ci::test-default       # Test default
just ci::test-integration   # Integration tests
just ci::build-debug        # Debug build
just ci::build-release      # Release build
just ci::full               # Complete pipeline

nickel - Nickel Schema Generation

Generate TOML forms from Nickel schemas:

just nickel::nickel-to-form SCHEMA     # Generate form from schema
just nickel::nickel-preview SCHEMA     # Preview without writing
just nickel::nickel-workflow SCHEMA TEMPLATE  # Full workflow
just nickel::nickel-i18n SCHEMA        # Extract i18n only
just nickel::nickel-roundtrip IN FORM  # Roundtrip (read/write)
just nickel::help                      # Show Nickel recipes help

distro - Distribution & Packaging

Build, package, and release:

# Build
just distro::build-all          # Debug build
just distro::build-release      # Release build

# Cross-compile
just distro::cross              # All targets
just distro::cross-docker TGT   # Docker build

# Package
just distro::create-package     # Create distribution
just distro::create-checksums   # Generate checksums
just distro::package-all        # Build + package

# Release
just distro::package-release    # Prepare release
just distro::package-release-version V  # With version

# Utilities
just distro::generate-manifest  # Create manifest
just distro::list-packages      # List packages
just distro::clean-distro       # Clean directory

Development Workflow Examples

Daily Development

# 1. Start watching
just dev::watch

# 2. In another terminal, work on code
# 3. Changes auto-rebuild
# 4. Run tests manually
just test::all

Adding a Feature

# 1. Create feature branch
git checkout -b feature/my-feature

# 2. Code and test
just check-all

# 3. Run full validation
just ci::full

# 4. Push and create PR
git push origin feature/my-feature

Preparing Release

# 1. Update version in Cargo.toml
nano crates/typedialog-core/Cargo.toml

# 2. Validate everything
just ci::full

# 3. Build and package
just distro::build-release
just distro::create-package
just distro::create-checksums

# 4. Prepare release
just distro::package-release

# 5. Create GitHub release (see RELEASE.md)

Examples

Complete examples organized by category:

Basic Examples

# Run basic form
cargo run --example form

# With sections
cargo run --example form_with_sections

# With groups
cargo run --example form_with_grouped_items

Advanced Examples

# Conditional logic
cargo run --example conditional_required_demo

# Autocompletion
cargo run --example form_with_autocompletion

Backend-Specific

# CLI with autocompletion
cargo run --example autocompletion_demo

# TUI interactive form
cargo run -p typedialog-tui --example form_with_autocompletion

# Web server
cargo run -p typedialog-web -- --config config/web/dev.toml

Nickel Examples

Nickel schema parsing and generation:

# Basic Nickel schema
cargo run --example basic_nickel_schema

# Roundtrip (parse, transform, write)
cargo run --example nickel_roundtrip

# I18n extraction from Nickel
cargo run --example nickel_i18n_extraction

# Template rendering
cargo run --example nickel_template_context

See ../examples/07-nickel-generation/ for complete guide. See NICKEL.md for detailed Nickel documentation.

Troubleshooting

Build errors

Clear build cache and rebuild:

cargo clean
just build::default

Test failures

Run with backtrace for more details:

RUST_BACKTRACE=1 cargo test

Format check failing

Auto-fix formatting:

just fmt

"just" not found

Install or add to PATH:

cargo install just
export PATH="$HOME/.cargo/bin:$PATH"

cargo-watch not working

Install it:

cargo install cargo-watch

Port already in use (web backend)

Change port in config:

# config/web/dev.toml
[server]
port = 3001  # Instead of 3000

Or override:

TYPEDIALOG_WEB_PORT=3001 cargo run -p typedialog-web

Tips & Tricks

Faster builds

Use incremental compilation:

export CARGO_BUILD_JOBS=$(nproc)
export CARGO_INCREMENTAL=1

Parallel testing

cargo test -- --test-threads=4

Format all code quickly

just fmt && just lint-fix

Development script

Create a development startup script:

#!/bin/bash
# dev.sh

echo "Installing dependencies..."
cargo install just cargo-watch

echo "Building project..."
just build::default

echo "Running tests..."
just test::all

echo "Watching for changes..."
just dev::watch

Next Steps

• Read BUILD.md for building distributions
• Read CONFIGURATION.md for configuration options
• Check ../examples/README.md for examples
• See RELEASE.md for release process

---

Ready to develop! 🚀

Questions? Check the examples or open an issue on GitHub.