TypeDialog Logo
# Development Guide Guide for local TypeDialog development using `just` command orchestration. ## Quick Start ```bash # 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 ```bash # 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 # 5. Setup pre-commit hooks (optional but recommended) ./scripts/setup-pre-commit.sh ``` **See**: [pre-commit-setup.md](pre-commit-setup.md) for automated linting before commits. ### Format & Lint Code ```bash # 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 ```bash # 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 ```bash # 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: ```bash just dev::watch ``` Requires: `cargo-watch` (install with `cargo install cargo-watch`) ### Generate Documentation ```bash # Generate docs just dev::docs-gen # Generate and open in browser just dev::docs ``` ### Run Examples See [../examples/README.md](../examples/README.md) for complete examples. Quick examples: ```bash # 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # Conditional logic cargo run --example conditional_required_demo # Autocompletion cargo run --example form_with_autocompletion ``` ### Backend-Specific ```bash # 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: ```bash # 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/](../examples/07-nickel-generation/) for complete guide. See [nickel.md](nickel.md) for detailed Nickel documentation. ## Troubleshooting ### Build errors Clear build cache and rebuild: ```bash cargo clean just build::default ``` ### Test failures Run with backtrace for more details: ```bash RUST_BACKTRACE=1 cargo test ``` ### Format check failing Auto-fix formatting: ```bash just fmt ``` ### "just" not found Install or add to PATH: ```bash cargo install just export PATH="$HOME/.cargo/bin:$PATH" ``` ### cargo-watch not working Install it: ```bash cargo install cargo-watch ``` ### Port already in use (web backend) Change port in config: ```toml # config/web/dev.toml [server] port = 3001 # Instead of 3000 ``` Or override: ```bash TYPEDIALOG_WEB_PORT=3001 cargo run -p typedialog-web ``` ## Tips & Tricks ### Faster builds Use incremental compilation: ```bash export CARGO_BUILD_JOBS=$(nproc) export CARGO_INCREMENTAL=1 ``` ### Parallel testing ```bash cargo test -- --test-threads=4 ``` ### Format all code quickly ```bash just fmt && just lint-fix ``` ### Development script Create a development startup script: ```bash #!/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](build.md) for building distributions - Read [configuration.md](configuration.md) for configuration options - Check [../examples/README.md](../examples/README.md) for examples - See [release.md](release.md) for release process --- **Ready to develop!** 🚀 Questions? Check the examples or open an issue on GitHub.