TypeDialog/docs/development.md

<div align="center">
  <img src="../assets/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
</div>

# 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.