diff --git a/docs/BUILD.md b/docs/BUILD.md new file mode 100644 index 0000000..989c6da --- /dev/null +++ b/docs/BUILD.md @@ -0,0 +1,443 @@ +
+ TypeDialog Logo +
+ +# Building & Distribution Guide + +Complete guide for building, packaging, and releasing TypeDialog. + +## Overview + +Two main workflows: +1. **Building** - Compile binaries for your platform +2. **Distribution** - Package with configs and installers for release + +## Building Binaries + +### Single Platform Build + +Build for your current platform: + +```bash +# Debug build (default) +just distro::build-all + +# Release build (optimized) +just distro::build-release +``` + +**Output**: Binaries in `target/release/` + +```bash +# Check binaries +ls -la target/release/typedialog* +``` + +### Build by Backend + +Build specific backend only: + +```bash +just build::cli # CLI backend +just build::tui # TUI backend +just build::web # Web backend +just build::all # All backends +``` + +### Development Build + +Quick build for development: + +```bash +just build::default +``` + +## Cross-Compilation + +Build for multiple platforms: + +### Using cargo-cross + +Cross-compile to different targets: + +```bash +# All supported targets +just distro::cross + +# Specific target +just distro::cross-target x86_64-unknown-linux-gnu +``` + +**Supported targets:** +- `x86_64-unknown-linux-gnu` - Linux x86_64 +- `aarch64-unknown-linux-gnu` - Linux ARM64 +- `x86_64-apple-darwin` - macOS Intel +- `aarch64-apple-darwin` - macOS Apple Silicon +- `x86_64-pc-windows-gnu` - Windows x86_64 + +**Requires:** `cargo install cross` + +### Using Docker + +Docker-based cross-compilation: + +```bash +# Docker cross-compile +just distro::cross-docker x86_64-unknown-linux-gnu +``` + +**Requires:** Docker installed + +**Dockerfile:** See `Dockerfile.cross` + +## Creating Distribution Packages + +Distribution packages include binaries, configs, and installers. + +### Create Package + +```bash +# From existing binaries +just distro::create-package + +# With specific version +just distro::create-package-version v0.1.0 +``` + +**Output:** `distribution/typedialog-0.1.0/` + +``` +typedialog-0.1.0/ +├── bin/ +│ ├── typedialog # CLI binary +│ ├── typedialog-tui # TUI binary +│ └── typedialog-web # Web binary +├── config/ +│ ├── cli/ # 3 configs: default, dev, production +│ ├── tui/ # 3 configs +│ └── web/ # 3 configs +├── installers/ +│ ├── install.sh # Linux/macOS installer +│ ├── install.ps1 # Windows installer +│ └── README.md # Installation guide +└── MANIFEST.json # Package metadata +``` + +### Generate Checksums + +```bash +just distro::create-checksums +``` + +**Output:** `SHA256SUMS` file + +Verify integrity: +```bash +sha256sum -c SHA256SUMS +``` + +### Full Package Workflow + +```bash +# 1. Build release +just distro::build-release + +# 2. Create package +just distro::create-package + +# 3. Generate checksums +just distro::create-checksums + +# Or all together: +just distro::package-all +``` + +## Distribution Structure + +### Package Contents + +**bin/** - Compiled binaries +- `typedialog` - CLI backend +- `typedialog-tui` - TUI backend +- `typedialog-web` - Web backend + +**config/** - Configuration templates +- CLI configs (default, dev, production) +- TUI configs (default, dev, production) +- Web configs (default, dev, production) + +**installers/** - Installation scripts +- `install.sh` - For Linux/macOS +- `install.ps1` - For Windows +- `README.md` - Installation guide + +**MANIFEST.json** - Package metadata +```json +{ + "name": "typedialog", + "version": "0.1.0", + "created": "...", + "binaries": [...], + "configs": {...}, + "installers": {...} +} +``` + +### Configuration Management + +Pre-configured settings for each backend and environment: + +**CLI Backend:** +- `default.toml` - Standard settings +- `dev.toml` - Development (debug enabled) +- `production.toml` - Hardened production + +**TUI Backend:** +- `default.toml` - Interactive settings +- `dev.toml` - Development features +- `production.toml` - Optimized production + +**Web Backend:** +- `default.toml` - Standard web server +- `dev.toml` - Development (hot reload) +- `production.toml` - Hardened web server + +See [CONFIGURATION.md](CONFIGURATION.md) for details. + +## Build Scripts + +All build automation uses bash scripts in `scripts/`: + +### build_all.sh + +Build all workspace targets: +```bash +./scripts/build_all.sh [debug|release] +``` + +### build_cross.sh + +Cross-compile for multiple platforms: +```bash +./scripts/build_cross.sh [target] +``` + +### create_distro.sh + +Create distribution package: +```bash +./scripts/create_distro.sh [version] +``` + +### package_release.sh + +Prepare release with checksums and notes: +```bash +./scripts/package_release.sh [version] +``` + +## Docker Build + +### Dockerfile.cross + +Multi-platform Docker build: + +```bash +# Build image for specific target +docker build -f Dockerfile.cross \ + --build-arg TARGET=x86_64-unknown-linux-gnu \ + -t typedialog-builder:latest \ + . + +# Run compilation +docker run --rm \ + -v $(pwd)/distribution:/output \ + typedialog-builder:latest +``` + +## Complete Release Workflow + +Prepare a release for GitHub: + +```bash +# 1. Build release binaries +just distro::build-release + +# 2. Create distribution package +just distro::create-package + +# 3. Generate checksums +just distro::create-checksums + +# 4. Prepare release (with notes) +just distro::package-release + +# 5. Verify contents +just distro::list-packages + +# 6. Create GitHub release (see RELEASE.md) +gh release create v0.1.0 \ + release/typedialog-0.1.0.tar.gz \ + release/SHA256SUMS \ + --title "TypeDialog 0.1.0" \ + --notes-file release/RELEASE_NOTES.md +``` + +## Utilities + +### List packages + +```bash +just distro::list-packages +``` + +### Generate manifest + +```bash +just distro::generate-manifest +``` + +### Clean distribution + +```bash +just distro::clean-distro +``` + +## Troubleshooting + +### Build fails + +Clear cache and rebuild: +```bash +cargo clean +just distro::build-release +``` + +### Cross-compilation fails + +Ensure Docker is running: +```bash +docker --version +docker run hello-world +``` + +### Missing dependencies + +Install required tools: +```bash +cargo install cross # For cross-compilation +cargo install just # For command orchestration +``` + +### Checksum verification fails + +Regenerate checksums: +```bash +just distro::create-checksums +``` + +## Platform Support + +| Platform | Arch | Status | +|----------|------|--------| +| Linux (glibc) | x86_64 | ✓ Stable | +| Linux (glibc) | ARM64 | ✓ Stable | +| macOS | x86_64 | ✓ Stable | +| macOS | ARM64 | ✓ Stable | +| Windows | x86_64 | ✓ Stable | + +## Performance Tips + +### Faster builds + +```bash +# Use all CPU cores +export CARGO_BUILD_JOBS=$(nproc) +export CARGO_INCREMENTAL=1 + +# Then build +just distro::build-release +``` + +### Parallel testing + +```bash +cargo test -- --test-threads=4 +``` + +## Compliance & SBOM Generation + +Generate Software Bill of Materials (SBOM) for supply chain transparency. + +### Regenerate SBOMs + +When dependencies change (new crates, version updates, Cargo.lock changes): + +```bash +just distro::generate-sbom +``` + +This regenerates: +- **LICENSE.md** - Dependency attribution and licenses +- **SBOM.spdx.json** - SPDX 2.3 standard format +- **SBOM.cyclonedx.json** - CycloneDX 1.4 format + +### Audit Dependencies + +Check for known security vulnerabilities: + +```bash +just ci::audit +``` + +### Verify SBOMs in CI + +Verify SBOMs are up-to-date during CI pipeline: + +```bash +just ci::verify-sbom +``` + +Included automatically in full CI run: + +```bash +just ci::full +``` + +### SBOM Files + +**LICENSE.md** (7.4 KB) +- Lists all dependencies with their licenses +- Organized by license type +- Compliance summary + +**SBOM.spdx.json** (139 KB) +- SPDX 2.3 format (ISO/IEC 5962:2021) +- 287 components with unique identifiers +- Compatible with SPDX validators and GitHub Dependabot + +**SBOM.cyclonedx.json** (90 KB) +- CycloneDX 1.4 format (modern standard) +- 286 components with package URLs +- Compatible with vulnerability scanners and SCA tools + +### Supply Chain Security + +All dependencies are: +- Permissive or compatible licenses ✓ +- Regularly audited for vulnerabilities ✓ +- Tracked in version-controlled SBOMs ✓ +- Included in releases ✓ + +--- + +## Next Steps + +- [RELEASE.md](RELEASE.md) - Release workflow +- [CONFIGURATION.md](CONFIGURATION.md) - Configuration options +- [INSTALLATION.md](INSTALLATION.md) - User installation +- [DEVELOPMENT.md](DEVELOPMENT.md) - Development setup + +--- + +**Build complete!** Ready for distribution. diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 0000000..21ac395 --- /dev/null +++ b/docs/CONFIGURATION.md @@ -0,0 +1,362 @@ +
+ TypeDialog Logo +
+ +# Configuration Files + +Pre-configured settings for each TypeDialog backend and environment. + +## Overview + +Configuration files are organized by **backend** (CLI, TUI, Web) and **environment** (default, dev, production). + +``` +config/ +├── cli/ +│ ├── default.toml # Standard CLI settings +│ ├── dev.toml # Development (debugging enabled) +│ └── production.toml # Production (optimized, hardened) +├── tui/ +│ ├── default.toml # Standard TUI settings +│ ├── dev.toml # Development features enabled +│ └── production.toml # Optimized for deployment +└── web/ + ├── default.toml # Standard web server settings + ├── dev.toml # Development (hot reload) + └── production.toml # Hardened for production +``` + +## Backend Configurations + +### CLI Backend + +**command-line interface** - Simple text-based forms for scripts and automation. + +| Config | Purpose | Debug | Colors | Timeout | +|--------|---------|-------|--------|---------| +| default | Standard | No | Yes | 300s | +| dev | Development | Yes | Yes | 300s | +| production | Production | No | Yes | 3600s | + +**Usage:** +```bash +typedialog --config config/cli/production.toml form.toml +``` + +**Features:** +- Inline validation +- Optional mouse support +- Placeholder text display +- Help text display + +### TUI Backend + +**terminal user interface** - Interactive multi-panel forms with navigation. + +| Config | Purpose | Borders | Animations | Render | +|--------|---------|---------|-----------|--------| +| default | Standard | Rounded | Enabled | Auto | +| dev | Development | Double | Enabled | Debug | +| production | Production | Rounded | Disabled | Optimized | + +**Usage:** +```bash +typedialog-tui --config config/tui/production.toml form.toml +``` + +**Features:** +- 3-panel layout (fields, input, buttons) +- Mouse support +- Keyboard navigation +- Real-time field updates + +### Web Backend + +**HTTP server** - Browser-based forms with REST API. + +| Config | Purpose | CORS | HTTPS | Rate Limit | +|--------|---------|------|-------|-----------| +| default | Standard | Localhost | No | Unlimited | +| dev | Development | Enabled | No | Unlimited | +| production | Production | Restricted | Required | 100/min | + +**Usage:** +```bash +typedialog-web --config config/web/production.toml +# Server starts on http://localhost:8080 +``` + +**Features:** +- HTML/CSS rendering +- CSRF protection +- Response caching +- Gzip compression + +## Configuration by Environment + +### Development Configuration + +Enabled features for development and debugging: + +```toml +# CLI Dev +debug_output = true +log_level = "debug" +show_field_types = true + +# TUI Dev +show_field_indices = true +trace_rendering = false + +# Web Dev +hot_reload = true +debug = true +logs = "/tmp/typedialog-web.log" +``` + +**Usage:** +```bash +typedialog --config config/cli/dev.toml form.toml +typedialog-tui --config config/tui/dev.toml form.toml +typedialog-web --config config/web/dev.toml +``` + +### Production Configuration + +Hardened settings optimized for deployment: + +```toml +# CLI Production +debug_output = false +log_level = "error" +show_placeholders = false +timeout = 3600 + +# TUI Production +enable_animations = false +render_throttle = 16ms +max_fps = 60 + +# Web Production +require_https = true +csrf_enabled = true +rate_limit = 100 +cache_ttl = 3600 +``` + +**Usage:** +```bash +typedialog --config config/cli/production.toml form.toml +typedialog-tui --config config/tui/production.toml form.toml +typedialog-web --config config/web/production.toml +``` + +## Common Settings + +### Form Configuration + +```toml +[form] +title = "Form Title" +description = "Optional description" + +[form.validation] +validate_on_change = true +show_errors_inline = true +strict_validation = true +``` + +### Output Configuration + +```toml +[output] +format = "json" # json, yaml, toml, text +pretty_print = true +debug_output = false +``` + +### Logging + +```toml +[logging] +level = "info" # debug, info, warn, error +file = "/var/log/typedialog/app.log" +``` + +## Custom Configuration + +### Creating Custom Configurations + +Create a new TOML file based on an environment template: + +```bash +# Copy production config as base +cp config/cli/production.toml config/cli/custom.toml + +# Edit for your needs +nano config/cli/custom.toml + +# Use it +typedialog --config config/cli/custom.toml form.toml +``` + +### Override Specific Settings + +Use environment variables to override config: + +```bash +# CLI Backend +export TYPEDIALOG_DEBUG=1 +export TYPEDIALOG_LOG_LEVEL=debug +typedialog --config config/cli/default.toml form.toml + +# TUI Backend +export TYPEDIALOG_TUI_BORDER=double +typedialog-tui --config config/tui/default.toml form.toml + +# Web Backend +export TYPEDIALOG_WEB_PORT=3000 +export TYPEDIALOG_WEB_CORS_ORIGINS="localhost,example.com" +typedialog-web --config config/web/default.toml +``` + +## CLI Backend Configuration Details + +```toml +[terminal] +use_raw_mode = true # Enable raw terminal mode +enable_mouse = false # Mouse support +use_color = true # Colored output + +[appearance] +theme = "default" # Color theme +show_help = true # Display field help +show_placeholders = true # Show placeholder text + +[validation] +validate_on_change = true # Real-time validation +show_errors_inline = true # Inline error messages + +[timeout] +max_duration = 3600 # Max form time (seconds) +input_timeout = 300 # Field input timeout +``` + +## TUI Backend Configuration Details + +```toml +[terminal] +use_raw_mode = true +enable_mouse = true +enable_scrolling = true +height = -1 # -1 = auto +width = -1 # -1 = auto + +[ui] +show_borders = true +show_focus = true +highlight_on_hover = true +enable_animations = true + +[appearance] +theme = "default" +border_style = "rounded" # rounded, double, simple +color_scheme = "default" + +[keyboard] +vi_mode = false +emacs_mode = false + +[performance] +render_throttle = 16 # milliseconds +max_fps = 60 # frames per second +``` + +## Web Backend Configuration Details + +```toml +[server] +host = "0.0.0.0" +port = 8080 +workers = 4 + +[html] +css_framework = "none" # bootstrap, tailwind, none +inline_styles = false +responsive = true +dark_mode = true + +[submission] +method = "post" +webhook_url = "https://api.example.com/forms" +redirect_on_success = true +redirect_url = "https://example.com/thank-you" + +[security] +csrf_enabled = true +rate_limit = 100 # requests per minute +require_https = true +add_security_headers = true + +[performance] +cache_static = true +cache_ttl = 3600 +enable_compression = true +compression_threshold = 1024 +``` + +## Distribution Configurations + +When creating release distributions, all configurations are included: + +```bash +# Build and package +just distro::build-release +just distro::create-package + +# Result includes all configs +distribution/typedialog-0.1.0/ +├── config/ +│ ├── cli/ +│ ├── tui/ +│ └── web/ +└── ... +``` + +Users can then choose configs during installation: + +```bash +# Extract distribution +tar -xzf typedialog-0.1.0.tar.gz +cd typedialog-0.1.0 + +# Install +bash installers/install.sh + +# Use specific config +typedialog --config ~/.config/typedialog/cli/production.toml form.toml +``` + +## Best Practices + +### Development +- Use `dev` configurations for local development +- Enable debugging and verbose logging +- Use shorter timeouts for faster iteration + +### Testing +- Use `default` configurations for testing +- Run integration tests with all environments + +### Production +- Always use `production` configurations +- Verify HTTPS is enabled (web backend) +- Set appropriate rate limits +- Configure logging to persistent location +- Test thoroughly in staging first + +## Related Documentation + +- [BUILD_AND_DISTRIBUTION.md](../BUILD_AND_DISTRIBUTION.md) - Build guide +- [DISTRIBUTION_WORKFLOW.md](../DISTRIBUTION_WORKFLOW.md) - Release workflow +- [README.md](../README.md) - Main documentation diff --git a/docs/DEPENDENCIES.md b/docs/DEPENDENCIES.md new file mode 100644 index 0000000..c2c7695 --- /dev/null +++ b/docs/DEPENDENCIES.md @@ -0,0 +1,156 @@ +# TypeDialog Dependencies + +## Direct Dependencies (by crate) + +### typedialog-core + +Core library dependencies: + +**Serialization & Data** +- serde 1.0 (Apache-2.0 OR MIT) +- serde_json 1.0 (Apache-2.0 OR MIT) +- serde_yaml 0.9 (Apache-2.0 OR MIT) +- toml 0.9 (Apache-2.0 OR MIT) + +**Error Handling** +- anyhow 1.0 (Apache-2.0 OR MIT) +- thiserror 2.0 (Apache-2.0 OR MIT) + +**Date/Time** +- chrono 0.4 (Apache-2.0 OR MIT) + +**Async** +- tokio 1 (MIT) +- async-trait 0.1 (Apache-2.0 OR MIT) +- futures 0.3 (Apache-2.0 OR MIT) + +**Templating (optional)** +- tera 1.20 (MIT) + +**i18n (optional)** +- fluent 0.17 (Apache-2.0) +- fluent-bundle 0.16 (Apache-2.0) +- unic-langid 0.9 (Apache-2.0 OR MIT) +- sys-locale 0.3 (Apache-2.0 OR MIT) +- dirs 6.0 (Apache-2.0 OR MIT) + +**CLI Backend (optional)** +- inquire 0.9 (MIT) +- dialoguer 0.12 (MIT) +- rpassword 7.4 (Apache-2.0) + +**TUI Backend (optional)** +- ratatui 0.29 (MIT) +- crossterm 0.29 (MIT) +- atty 0.2 (MIT) + +**Web Backend (optional)** +- axum 0.8.7 (MIT) +- tower 0.5.2 (MIT) +- tower-http 0.6.8 (MIT) +- tracing 0.1 (MIT) +- tracing-subscriber 0.3 (MIT) + +**Utilities** +- tempfile 3.23 (Apache-2.0 OR MIT) + +### typedialog (CLI) + +Direct dependencies: +- typedialog-core 0.1.0 (MIT) +- clap 4.5 (Apache-2.0 OR MIT) - CLI argument parsing +- anyhow 1.0 (Apache-2.0 OR MIT) +- serde_json 1.0 (Apache-2.0 OR MIT) +- tokio 1.0 (MIT) +- toml 0.9 (Apache-2.0 OR MIT) +- unic-langid 0.9 (Apache-2.0 OR MIT) + +### typedialog-tui (TUI) + +Direct dependencies: +- typedialog-core 0.1.0 (MIT) +- clap 4.5 (Apache-2.0 OR MIT) +- anyhow 1.0 (Apache-2.0 OR MIT) +- serde_json 1.0 (Apache-2.0 OR MIT) +- tokio 1.0 (MIT) +- unic-langid 0.9 (Apache-2.0 OR MIT) + +### typedialog-web (Web) + +Direct dependencies: +- typedialog-core 0.1.0 (MIT) +- clap 4.5 (Apache-2.0 OR MIT) +- anyhow 1.0 (Apache-2.0 OR MIT) +- serde_json 1.0 (Apache-2.0 OR MIT) +- tokio 1.0 (MIT) +- unic-langid 0.9 (Apache-2.0 OR MIT) + +--- + +## Transitive Dependencies + +Total: **286 dependencies** across all features. + +### License Distribution + +| License | Count | +|---------|-------| +| Apache-2.0 OR MIT | 190 | +| MIT | 66 | +| Apache-2.0 | 3 | +| MIT OR Unlicense | 7 | +| Apache-2.0 OR Apache-2.0 WITH LLVM-exception OR MIT | 7 | +| Other | 13 | + +--- + +## License Compatibility + +All dependencies are compatible with the **MIT License**: + +- ✓ **Permissive licenses** (MIT, Apache-2.0, BSD-3-Clause, Zlib, MPL-2.0) +- ✓ **Weak copyleft** (LGPL-2.1-or-later, MPL-2.0) +- ✓ **Public domain** (Unlicense, Unicode-3.0) + +--- + +## Files + +- `LICENSE.md` - Full dependency license attribution +- `SBOM.spdx.json` - Software Bill of Materials (SPDX 2.3 format) +- `SBOM.cyclonedx.json` - Software Bill of Materials (CycloneDX 1.4 format) +- `Cargo.lock` - Locked dependency versions for reproducibility + +--- + +## Security Considerations + +### No Unsafe Code + +The workspace forbids `unsafe` code: +```toml +[workspace.lints.rust] +unsafe_code = "forbid" +``` + +### Dependency Auditing + +Run security audit: +```bash +cargo audit +``` + +Review dependency tree: +```bash +cargo tree --depth=2 +``` + +### SBOM Usage + +SBOMs can be used with: +- **SPDX format** - CycloneDX tools, GitHub Dependabot, SPDX validators +- **CycloneDX format** - Software composition analysis tools, vulnerability scanners + +--- + +Generated: 2024-12-17 diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 0000000..c45821c --- /dev/null +++ b/docs/DEVELOPMENT.md @@ -0,0 +1,438 @@ +
+ 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 +``` + +### 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 +``` + +### 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 +``` + +See [../examples/README.md](../examples/README.md) for complete guide. + +## 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. diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md new file mode 100644 index 0000000..1b6d5cd --- /dev/null +++ b/docs/INSTALLATION.md @@ -0,0 +1,306 @@ +
+ TypeDialog Logo +
+ +# Installation Guide + +Complete setup instructions for TypeDialog development. + +## Prerequisites + +### Required + +#### Rust & Cargo (1.70+) + +Install from [https://rustup.rs/](https://rustup.rs/): + +```bash +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +source $HOME/.cargo/env +``` + +Verify: +```bash +rustc --version +cargo --version +``` + +#### just - Command Orchestration + +**Option 1: Using cargo** +```bash +cargo install just +``` + +**Option 2: Package manager** +```bash +# macOS +brew install just + +# Debian/Ubuntu +sudo apt install just + +# Arch +sudo pacman -S just + +# Fedora +sudo dnf install just +``` + +Verify: +```bash +just --version +``` + +### Optional (for specific features) + +#### Nickel CLI - For type-safe form schemas + +If you plan to use Nickel (`.ncl`) form definitions: + +```bash +cargo install nickel-lang +``` + +Or download from: [https://github.com/nickel-lang/nickel/releases](https://github.com/nickel-lang/nickel/releases) + +Verify: +```bash +nickel --version +``` + +#### cargo-cross - For cross-platform compilation + +For compiling to platforms other than your current OS: + +```bash +cargo install cross +``` + +Requires Docker to be installed. + +#### cargo-watch - For development hot-reload + +For automatic rebuild on file changes: + +```bash +cargo install cargo-watch +``` + +#### Docker - For Docker cross-compilation + +For Docker-based cross-compilation (alternative to cargo-cross): + +Download from: [https://www.docker.com/get-started](https://www.docker.com/get-started) + +Verify: +```bash +docker --version +``` + +## Installation Steps + +### 1. Clone Repository + +```bash +git clone https://github.com/anthropics/typedialog.git +cd typedialog +``` + +### 2. Verify Dependencies + +```bash +# Check all required tools +rustc --version +cargo --version +just --version + +# Check optional tools (if installed) +nickel --version # If using Nickel +cargo cross --version # If cross-compiling +cargo watch --version # If using watch +docker --version # If using Docker builds +``` + +### 3. Build Project + +Using cargo: +```bash +cargo build +``` + +Or using just: +```bash +just build::default +``` + +### 4. Run Tests + +```bash +# Quick test +cargo test + +# Or using just +just test::all +``` + +### 5. Verify Installation + +```bash +# Check binaries exist +ls -la target/debug/typedialog* + +# Run CLI +./target/debug/typedialog --version + +# Or install +cargo install --path . +typedialog --version +``` + +## Quick Verification + +Run this to verify everything is working: + +```bash +#!/bin/bash + +echo "=== Checking Rust ===" +rustc --version || echo "❌ Rust not found" +cargo --version || echo "❌ Cargo not found" + +echo "=== Checking just ===" +just --version || echo "❌ just not found" + +echo "=== Optional tools ===" +nickel --version 2>/dev/null || echo "⚠ Nickel not installed (optional)" +cargo cross --version 2>/dev/null || echo "⚠ cargo-cross not installed (optional)" +cargo watch --version 2>/dev/null || echo "⚠ cargo-watch not installed (optional)" +docker --version 2>/dev/null || echo "⚠ Docker not installed (optional)" + +echo "=== Building project ===" +cargo check && echo "✓ Project builds successfully" || echo "❌ Build failed" + +echo "=== All checks complete ===" +``` + +## Troubleshooting + +### "just" command not found + +Ensure `just` is installed and in PATH: + +```bash +# Install +cargo install just + +# Add to PATH if needed +export PATH="$HOME/.cargo/bin:$PATH" + +# Verify +just --version +``` + +### Rust compilation errors + +Update Rust to latest stable: + +```bash +rustup update +rustc --version +``` + +### Permission denied on installer scripts + +Make scripts executable: + +```bash +chmod +x installers/bootstrap/install.sh +chmod +x scripts/*.sh +``` + +### "cargo-watch not found" when using just dev::watch + +Install cargo-watch: + +```bash +cargo install cargo-watch +``` + +### Docker not running (for cross-compilation) + +Start Docker daemon: + +```bash +# macOS +open -a Docker + +# Linux +sudo systemctl start docker + +# Verify +docker --version +``` + +## Platform-Specific Setup + +### macOS + +```bash +# Install with Homebrew +brew install rust just + +# Or manual installation +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +cargo install just +``` + +### Linux (Ubuntu/Debian) + +```bash +# Install from apt +sudo apt update +sudo apt install build-essential rustup just + +# Or using cargo +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +cargo install just +``` + +### Linux (Arch) + +```bash +sudo pacman -S rust cargo just +``` + +### Windows + +1. Install Rust: [https://rustup.rs/](https://rustup.rs/) +2. Install just: + ```powershell + cargo install just + ``` +3. Or use Scoop: + ```powershell + scoop install just + ``` + +## Next Steps + +After installation: + +1. **Read [DEVELOPMENT.md](DEVELOPMENT.md)** - Learn how to use just for development +2. **Check [examples/README.md](../examples/README.md)** - See working examples +3. **Read [CONFIGURATION.md](CONFIGURATION.md)** - Understand configuration options + +## Getting Help + +- Check documentation in [docs/](.) +- Review [examples/](../examples/) +- Open an issue on GitHub + +--- + +**Installation complete!** 🎉 + +Next: [DEVELOPMENT.md](DEVELOPMENT.md) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..9e45047 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,126 @@ +
+ TypeDialog Logo +
+ +# TypeDialog Documentation + +Complete documentation for using, building, and deploying TypeDialog. + +## Getting Started + +1. **[INSTALLATION.md](INSTALLATION.md)** - Prerequisites and setup + - System requirements + - Dependency installation + - Verification + +2. **[DEVELOPMENT.md](DEVELOPMENT.md)** - Local development + - Using `just` for tasks + - Common workflows + - Examples and testing + +## Building & Distribution + +3. **[BUILD.md](BUILD.md)** - Building and packaging + - Single-platform builds + - Cross-compilation setup + - Distribution package creation + - Docker builds + +4. **[RELEASE.md](RELEASE.md)** - Release workflow + - Preparing releases + - GitHub releases + - Installation verification + - CI/CD integration + +## Configuration + +5. **[CONFIGURATION.md](CONFIGURATION.md)** - Configuration guide + - Backend-specific configs + - Environment settings (dev, prod) + - Custom configurations + - Best practices + +## Quick Links + +### Installation & Setup +- [System Requirements](INSTALLATION.md#prerequisites) +- [Installing just](INSTALLATION.md#just-command-orchestration) +- [Installing Nickel CLI](INSTALLATION.md#nickel-cli--optional) + +### Development +- [Quick Start Development](DEVELOPMENT.md#quick-start) +- [Using just Commands](DEVELOPMENT.md#just-commands) +- [Running Examples](DEVELOPMENT.md#examples) + +### Building +- [Build Binaries](BUILD.md#building-binaries) +- [Cross-Compilation](BUILD.md#cross-compilation) +- [Create Distribution Packages](BUILD.md#distribution-packages) + +### Release +- [Release Workflow](RELEASE.md#release-workflow) +- [GitHub Integration](RELEASE.md#github-release) +- [Distribution Structure](RELEASE.md#distribution-structure) + +## Navigation + +``` +docs/ +├── README.md ← You are here +├── INSTALLATION.md ← Prerequisites & setup +├── DEVELOPMENT.md ← Local development +├── BUILD.md ← Building & packaging +├── RELEASE.md ← Release workflow +└── CONFIGURATION.md ← Configuration guide +``` + +## Examples + +Complete working examples are in the `examples/` directory: + +- [examples/README.md](../examples/README.md) - Example guide +- [examples/01-basic/](../examples/01-basic/) - Getting started +- [examples/04-backends/](../examples/04-backends/) - Backend-specific +- [examples/09-templates/](../examples/09-templates/) - Production templates + +## Main Resources + +- [README.md](../README.md) - Project overview and features +- [Cargo.toml](../Cargo.toml) - Project manifest + +## Common Tasks + +### I want to... + +**...get started quickly** +→ Read [INSTALLATION.md](INSTALLATION.md), then [DEVELOPMENT.md](DEVELOPMENT.md) + +**...build from source** +→ Read [BUILD.md](BUILD.md#building-binaries) + +**...release a new version** +→ Read [RELEASE.md](RELEASE.md#release-workflow) + +**...configure backends** +→ Read [CONFIGURATION.md](CONFIGURATION.md) + +**...set up development environment** +→ Read [DEVELOPMENT.md](DEVELOPMENT.md) + +**...cross-compile for other platforms** +→ Read [BUILD.md](BUILD.md#cross-compilation) + +## Documentation Structure + +This documentation follows a **layered approach**: + +1. **Session Layer** (`.coder/`) - Interaction files (plans, summaries) +2. **Operational Layer** (`.claude/`) - Claude Code configuration +3. **Product Layer** (`docs/`) - User-facing documentation + +See [Architecture](../README.md#architecture) for project structure. + +--- + +**Latest Update**: December 2024 +**Status**: Complete diff --git a/docs/RELEASE.md b/docs/RELEASE.md new file mode 100644 index 0000000..6a18e87 --- /dev/null +++ b/docs/RELEASE.md @@ -0,0 +1,446 @@ +
+ TypeDialog Logo +
+ +# Release Workflow + +Guide for preparing and publishing TypeDialog releases. + +## Release Stages + +Complete release workflow has 4 stages: + +1. **Build** - Compile binaries (see [BUILD.md](BUILD.md)) +2. **Package** - Create distribution archives +3. **Prepare** - Generate checksums and release notes +4. **Publish** - Upload to GitHub + +## Stage 1: Build Binaries + +See [BUILD.md](BUILD.md#building-binaries) for complete build instructions. + +Quick reference: + +```bash +# Build release binaries +just distro::build-release + +# Or cross-compile all platforms +just distro::cross +``` + +**Output**: Binaries in `target/release/` + +## Stage 2: Create Distribution Package + +Package includes binaries, configs, and installers: + +```bash +# Create distribution +just distro::create-package +``` + +**Output:** `distribution/typedialog-0.1.0/` + +Contains: +- `bin/` - Compiled binaries +- `config/` - Configuration templates +- `installers/` - Installation scripts +- `MANIFEST.json` - Package metadata + +See [BUILD.md](BUILD.md#distribution-structure) for details. + +## Stage 3: Prepare Release + +Generate checksums and release notes: + +```bash +# Generate checksums +just distro::create-checksums + +# Prepare release +just distro::package-release +``` + +**Output:** `release/` + +``` +release/ +├── typedialog-0.1.0.tar.gz # Distribution package +├── SHA256SUMS # Checksums +└── RELEASE_NOTES.md # Release documentation +``` + +### Checksums + +Verify package integrity: + +```bash +# On your machine +sha256sum -c SHA256SUMS + +# For users +sha256sum typedialog-0.1.0.tar.gz +# Compare with SHA256SUMS +``` + +### Release Notes + +Auto-generated with: +- Installation instructions (all platforms) +- Verification steps +- Contents summary +- Platform support matrix + +Edit `release/RELEASE_NOTES.md` if needed: +```bash +nano release/RELEASE_NOTES.md +``` + +## Stage 4: GitHub Release + +### Create Release with GitHub CLI + +```bash +# Create release +gh release create v0.1.0 \ + release/typedialog-0.1.0.tar.gz \ + release/SHA256SUMS \ + --title "TypeDialog 0.1.0" \ + --notes-file release/RELEASE_NOTES.md +``` + +### Create Release via Web UI + +1. Go to [GitHub Releases](https://github.com/anthropics/typedialog/releases) +2. Click "Draft a new release" +3. Fill in: + - **Tag version**: `v0.1.0` + - **Release title**: `TypeDialog 0.1.0` + - **Description**: Copy from `release/RELEASE_NOTES.md` +4. Upload files: + - `release/typedialog-0.1.0.tar.gz` + - `release/SHA256SUMS` +5. Publish + +## Complete Release Example + +Step-by-step release process: + +```bash +# 1. Update version in Cargo.toml +nano crates/typedialog-core/Cargo.toml +# Change version = "0.1.0" to new version + +# 2. Commit version change +git add crates/typedialog-core/Cargo.toml +git commit -m "chore: bump version to 0.1.0" + +# 3. Run full CI/CD +just ci-full + +# 4. Build and package +just distro::build-release +just distro::create-package +just distro::create-checksums + +# 5. Prepare release +just distro::package-release + +# 6. Verify contents +just distro::list-packages + +# 7. Review release notes +cat release/RELEASE_NOTES.md + +# 8. Create git tag +git tag -a v0.1.0 -m "Release 0.1.0" +git push origin v0.1.0 + +# 9. Create GitHub release +gh release create v0.1.0 \ + release/typedialog-0.1.0.tar.gz \ + release/SHA256SUMS \ + --title "TypeDialog 0.1.0" \ + --notes-file release/RELEASE_NOTES.md + +# 10. Verify installation works +curl -fsSL https://github.com/anthropics/typedialog/releases/download/v0.1.0/install.sh | bash +typedialog --version +``` + +## Installation Verification + +After release, verify installation methods work: + +### Linux/macOS + +```bash +# Download and run installer +curl -fsSL https://github.com/anthropics/typedialog/releases/download/v0.1.0/install.sh | bash + +# Verify +typedialog --version +typedialog-tui --version +typedialog-web --version +``` + +### Windows PowerShell + +```powershell +# Download and run installer +irm https://github.com/anthropics/typedialog/releases/download/v0.1.0/install.ps1 | iex + +# Verify +typedialog --version +typedialog-tui --version +typedialog-web --version +``` + +### Manual Installation + +```bash +# Extract distribution +tar -xzf typedialog-0.1.0.tar.gz +cd typedialog-0.1.0 + +# Install +bash installers/install.sh + +# Verify +typedialog --version +``` + +## Distribution Structure + +### Inside typedialog-0.1.0.tar.gz + +``` +typedialog-0.1.0/ +├── bin/ +│ ├── typedialog # CLI binary +│ ├── typedialog-tui # TUI binary +│ └── typedialog-web # Web binary +├── config/ +│ ├── cli/ +│ │ ├── default.toml +│ │ ├── dev.toml +│ │ └── production.toml +│ ├── tui/ +│ │ ├── default.toml +│ │ ├── dev.toml +│ │ └── production.toml +│ └── web/ +│ ├── default.toml +│ ├── dev.toml +│ └── production.toml +├── installers/ +│ ├── install.sh # Linux/macOS +│ ├── install.ps1 # Windows +│ └── README.md # Instructions +└── MANIFEST.json # Metadata +``` + +### MANIFEST.json + +Package metadata with structure and contents: + +```json +{ + "name": "typedialog", + "version": "0.1.0", + "created": "2024-12-17T12:00:00Z", + "structure": {...}, + "binaries": [...], + "configs": {...}, + "installers": {...} +} +``` + +## Security Considerations + +### Checksums + +Always provide checksums: +```bash +sha256sum typedialog-0.1.0.tar.gz > SHA256SUMS +``` + +Users verify with: +```bash +sha256sum -c SHA256SUMS +``` + +### Installation Scripts + +Review before releasing: +```bash +# Linux/macOS +less installers/bootstrap/install.sh + +# Windows +less installers/bootstrap/install.ps1 +``` + +### Production Configurations + +Verify security settings in production configs: + +```toml +# config/web/production.toml +[security] +require_https = true +csrf_enabled = true +rate_limit = 100 +add_security_headers = true +``` + +See [CONFIGURATION.md](CONFIGURATION.md) for all settings. + +## Continuous Integration + +### GitHub Actions + +Example CI workflow for automated releases: + +```yaml +# .github/workflows/release.yml +on: + push: + tags: + - 'v*' + +jobs: + release: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: rust-lang/rust-action@v1 + + - name: Build release + run: just distro::build-release + + - name: Create package + run: just distro::create-package + + - name: Generate checksums + run: just distro::create-checksums + + - name: Prepare release + run: just distro::package-release + + - name: Create GitHub release + uses: softprops/action-gh-release@v1 + with: + files: | + release/typedialog-*.tar.gz + release/SHA256SUMS + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +## Troubleshooting + +### Release file not found + +Ensure files exist in `release/`: +```bash +just distro::list-packages +ls -la release/ +``` + +### Checksum mismatch + +Regenerate checksums: +```bash +just distro::create-checksums +``` + +### Installation script fails + +Test locally: +```bash +# macOS/Linux +bash installers/bootstrap/install.sh + +# Windows +pwsh installers/bootstrap/install.ps1 +``` + +### GitHub release failed + +Check permissions: +```bash +gh auth status +gh release list +``` + +## Release Checklist + +Before releasing: + +- [ ] Version updated in `crates/typedialog-core/Cargo.toml` +- [ ] All tests passing: `just ci::full` +- [ ] Binaries built: `just distro::build-release` +- [ ] Package created: `just distro::create-package` +- [ ] Checksums verified: `just distro::create-checksums` +- [ ] Release notes generated: `just distro::package-release` +- [ ] Installation tested (at least one platform) +- [ ] GitHub tag created: `git tag v0.1.0` +- [ ] Release published to GitHub +- [ ] Documentation updated + +## Release Notes Template + +When editing `release/RELEASE_NOTES.md`: + +```markdown +# TypeDialog 0.1.0 + +## What's New + +- Feature 1 +- Feature 2 +- Bug fix 1 + +## Installation + +### Linux/macOS +\`\`\`bash +curl -fsSL https://github.com/.../install.sh | bash +\`\`\` + +### Windows +\`\`\`powershell +irm https://github.com/.../install.ps1 | iex +\`\`\` + +## Verification + +\`\`\`bash +sha256sum -c SHA256SUMS +\`\`\` + +## Downloads + +- typedialog-0.1.0.tar.gz +- SHA256SUMS + +## Platforms + +- Linux x86_64, ARM64 +- macOS Intel, Apple Silicon +- Windows x86_64 +``` + +## Next Steps + +- [BUILD.md](BUILD.md) - Building binaries +- [CONFIGURATION.md](CONFIGURATION.md) - Configuration options +- [INSTALLATION.md](INSTALLATION.md) - User installation guide + +--- + +**Release complete!** 🎉 + +Users can now install via automated installers. diff --git a/docs/project-definition.md b/docs/project-definition.md new file mode 100644 index 0000000..4ea5e48 --- /dev/null +++ b/docs/project-definition.md @@ -0,0 +1,512 @@ +# Project Definition - typedialog + +**Version**: 0.1.0 +**Date**: 2025-12-17 +**Status**: Production-ready, pre-publicación + +--- + +## Resumen Ejecutivo + +**Nombre Actual**: typedialog v0.1.0 +**Categoría**: Interactive Configuration Management System +**Estado**: Production-ready, pre-publicación +**Arquitectura**: Multi-backend Rust workspace (4 crates) + +**Propósito Central**: Facilitar la gestión de configuración para aplicaciones, proyectos y scripts mediante inputs interactivos (prompts individuales o forms completos), con integración bidireccional a Nickel para settings tipados y validados. + +**Diferenciador Único**: Único sistema en el mercado que integra Nickel schemas → Interactive collection → Multi-format output (YAML/JSON/TOML) con preservación de type contracts. + +--- + +## 1. Identidad del Proyecto + +### 1.1 Estado Actual + +- **Nombre**: typedialog +- **Origen**: Extraído de `nu_plugin_inquire` (plugin de Nushell) +- **Etimología**: "form" + "inquire" (referencia al crate `inquire`) +- **Versión**: 0.1.0 +- **Madurez**: Production-ready, 80+ tests passing, documentación completa +- **Publicación**: No publicado en crates.io aún + +### 1.2 Evolución Histórica + +``` +nu_plugin_inquire (Nushell plugin) + ↓ +typedialog (standalone library extraction) + ↓ ++ CLI backend (inquire-based) + ↓ ++ Nickel integration (bidirectional) + ↓ ++ TUI backend (ratatui) + ↓ ++ Web backend (axum + HTMX) + ↓ +Current: Multi-backend configuration management system +``` + +**Puntos de Inflexión**: +1. Separación de Nushell → biblioteca standalone +2. Adición Nickel integration → type-safe configuration focus +3. Múltiples backends → multi-context positioning + +### 1.3 Descripción Técnica Precisa + +**Definición Formal**: Sistema de gestión de configuración interactiva que facilita la recolección, validación y transformación de settings mediante diálogo con el usuario, actuando como puente entre Nickel schemas tipados y formatos de configuración estándar (YAML/JSON/TOML), soportando múltiples interfaces (CLI/TUI/Web) para adaptarse a diferentes contextos de uso. + +**Componentes Core**: +- Form/Prompt engine con 8 tipos de inputs +- Nickel parser y code generator (bidirectional) +- Backend abstraction layer (trait-based) +- Template engine (Tera para metaprogramming) +- i18n system (Fluent con en-US, es-ES) +- Multi-format serialization (JSON/YAML/TOML/Nickel) + +--- + +## 2. Propósito y Problema que Resuelve + +### 2.1 Problema Space Completo + +**Problema Principal**: La configuración de aplicaciones, proyectos y scripts requiere: +1. Recolección interactiva de datos del usuario +2. Validación tipada de inputs +3. Transformación entre formatos (schemas → forms → configs) +4. Adaptación a diferentes contextos (CLI scripts, TUI setup, Web interfaces) +5. Organización con componentes, templates, documentación + +**Problemas Secundarios**: +- Herramientas existentes limitadas a un solo backend (CLI-only o Web-only) +- No hay integración con lenguajes de configuración tipados (Nickel, KCL) +- Forms completos ineficientes para capturar un solo valor +- Prompts individuales no escalables para setup complejos +- Falta de preservación de type contracts entre transformaciones +- Configuración manual propensa a errores de tipo + +### 2.2 Solución Propuesta + +**Enfoque Único**: +``` +Nickel Schema (typed, validated, documented) + ↓ [nickel-to-form] +TOML Form Definition (declarative, reusable) + ↓ [interactive collection] +User Dialog (CLI/TUI/Web según contexto) + ↓ [validation + transformation] +Validated Output (JSON/YAML/TOML/Nickel) + ↓ [consumption] +Application/Script/System +``` + +**Flexibilidad Clave**: +- **Single Prompt**: `nickelconf prompt --type password "API Key"` → captura un valor +- **Complete Form**: `nickelconf form setup.toml --backend tui` → multi-field wizard +- **Nickel Workflow**: Schema → Form → Config con type preservation + +### 2.3 Casos de Uso Concretos + +#### 1. Application Settings +- **User**: Developer configurando nueva app +- **Escenario**: Primera instalación de app Rust, necesita DB credentials, API keys, feature flags +- **Solución**: Nickel schema define settings → TUI form para setup inicial → config.yaml generado +- **Valor**: Type-safety, validación, documentación incluida en schema + +#### 2. Script Inputs +- **User**: DevOps engineer escribiendo Nushell script de deploy +- **Escenario**: Script necesita environment, region, instance type +- **Solución**: CLI prompts individuales integrados en script → validated JSON output +- **Valor**: Inputs validados on-the-fly, integración natural con script flow + +#### 3. Project Configuration +- **User**: Tech lead inicializando nuevo proyecto +- **Escenario**: Proyecto necesita 20+ settings (CI/CD, testing, deployment, monitoring) +- **Solución**: Nickel schema organizado con components → TUI complete form → project.toml +- **Valor**: Configuración completa guiada, validación, defaults inteligentes + +#### 4. Web-Based Setup +- **User**: SaaS admin configurando tenant +- **Escenario**: Configuración de tenant via web interface +- **Solución**: Same TOML form → Web backend → Settings guardados en DB +- **Valor**: Mismo form definition, diferente contexto de uso + +#### 5. Infrastructure as Code +- **User**: SRE provisionando recursos cloud +- **Escenario**: Crear configuración Terraform/Nickel para nueva infra +- **Solución**: Interactive prompts → Nickel output con contracts → Terraform consumption +- **Valor**: Type-safe IaC generation, validation antes de apply + +--- + +## 3. Arquitectura y Tecnología + +### 3.1 Tech Stack Completo + +**Core Language**: Rust 2021, MSRV 1.70+ + +**Crate Structure** (Workspace): +``` +typedialog/ +├── crates/ +│ ├── typedialog-core/ # Core library + backend trait +│ │ ├── form engine (8 input types) +│ │ ├── FormBackend trait +│ │ ├── Nickel integration modules +│ │ ├── Template engine (Tera) +│ │ ├── i18n system (Fluent) +│ │ └── Serialization (serde ecosystem) +│ ├── typedialog/ # CLI binary +│ │ └── InquireBackend impl +│ ├── typedialog-tui/ # TUI binary +│ │ └── RatatuiBackend impl +│ └── typedialog-web/ # Web server binary +│ └── AxumBackend impl +``` + +**Dependencies Clave**: +- `inquire` - Terminal prompts (CLI backend) +- `ratatui` + `crossterm` - Terminal UI (TUI backend) +- `axum` + `tower` - Web server (Web backend) +- `serde` ecosystem - Serialization (JSON/YAML/TOML) +- `tera` - Template engine (Jinja2-like) +- `fluent` + `fluent-bundle` - i18n/localization +- `clap` - CLI argument parsing +- `chrono` - Date/time handling + +**Backend Pattern** (Trait-based abstraction): +```rust +pub trait FormBackend { + fn execute_field(&mut self, field: &FormField) -> Result; + fn execute_form_complete(&mut self, form: &Form) -> Result>; +} + +// Implementations: +impl FormBackend for InquireBackend { ... } // CLI +impl FormBackend for RatatuiBackend { ... } // TUI +impl FormBackend for AxumBackend { ... } // Web +``` + +### 3.2 Características Técnicas Distintivas + +#### 1. Nickel Integration (Bidirectional) +- **nickel-to-form**: Parse Nickel schemas → Extract metadata → Generate TOML forms +- **form-to-nickel**: Convert form results → Generate Nickel code with contracts +- **Contract Preservation**: `std.string.NonEmpty`, `std.number.between` mantenidos +- **Component Support**: Nickel imports, merging, templates soportados + +#### 2. Multi-Backend Architecture +- **Same Form Definition**: Un TOML form funciona en CLI, TUI, Web +- **Identical Output**: Todos los backends producen mismo JSON/YAML/TOML +- **Display Modes**: FieldByField (step-by-step) o Complete (all at once) +- **Backend Selection**: `--backend cli|tui|web` en runtime + +#### 3. Form Engine Features +- **8 Input Types**: text, confirm, select, multiselect, password, custom, editor, date +- **Conditional Logic**: Fields con `depends_on` para flujo dinámico +- **Validation**: Regex, length, range, custom validators +- **Defaults**: Static, dynamic (desde otras respuestas), computed +- **Grouping**: Semantic grouping para mejor UX + +#### 4. i18n System +- **Fluent-based**: `.ftl` files para traducciones +- **Languages**: en-US (default), es-ES +- **Scopes**: Form UI, field labels, validation messages, help text +- **Fallback**: Graceful degradation a inglés + +#### 5. Template System +- **Tera Engine**: Jinja2-like syntax para metaprogramming +- **Nickel Templates**: `.ncl.j2` files para código generation +- **Variable Substitution**: Form results inyectados en templates +- **Conditionals/Loops**: Lógica de template para código complejo + +### 3.3 Formatos Soportados + +**Input Formats**: +- TOML (form definitions) +- Nickel (schemas para form generation) + +**Output Formats**: +- JSON (app configs, API consumption) +- YAML (configs, Kubernetes, Ansible) +- TOML (Rust configs, general settings) +- Nickel (type-safe configs con contracts) +- Plain text (simple key=value) + +--- + +## 4. Análisis de Mercado y Posicionamiento + +### 4.1 Target Audience Detallado + +**Audiencia Primaria**: + +1. **Application Developers** (40%) + - Stack: Rust, Go, Python apps + - Need: Settings management con type-safety + - Pain: Manual config files propensa a errores + - Value: Nickel schemas + interactive collection + validated output + +2. **Script Creators** (30%) + - Stack: Nushell, Bash, Python scripts + - Need: Interactive inputs para scripts + - Pain: Validación manual, error handling repetitivo + - Value: Validated prompts con minimal code + +3. **DevOps/SRE Engineers** (20%) + - Stack: Terraform, Kubernetes, Ansible + - Need: Interactive IaC generation + - Pain: Complex configs, no validation hasta runtime + - Value: Type-safe config generation, Nickel contracts + +4. **Project/Team Leads** (10%) + - Stack: Project setup, team onboarding + - Need: Consistent project configuration + - Pain: Manual setup guides, config drift + - Value: Reproducible project setup con forms + +**Audiencia Secundaria**: +- CLI tool developers agregando interactive features +- SaaS developers para user onboarding/config +- System administrators para server setup wizards + +### 4.2 Competitive Landscape + +**Categorías de Competidores**: + +1. **Terminal Prompt Libraries**: `inquire`, `dialoguer`, `questionary` + - Gap: Solo prompts, no forms. No type-safety. No multi-backend. + +2. **Form Libraries**: HTML forms, `react-hook-form` + - Gap: Web-only. No CLI/TUI. No Nickel integration. + +3. **Configuration Management**: Ansible, Terraform + - Gap: IaC-specific. No general-purpose forms. No type preservation. + +4. **Schema Languages**: JSON Schema, Nickel, KCL + - Gap: Schema definition only, no interactive collection. + +**Competitive Matrix**: + +| Feature | typedialog | inquire | HTML forms | Ansible | Nickel | +|---------|-------------|---------|------------|---------|--------| +| Interactive prompts | ✅ | ✅ | ❌ | ⚠️ | ❌ | +| Complete forms | ✅ | ❌ | ✅ | ⚠️ | ❌ | +| Multi-backend | ✅ (3) | ❌ | ❌ | ❌ | ❌ | +| Type-safe schemas | ✅ | ❌ | ❌ | ⚠️ | ✅ | +| Bidirectional schema | ✅ | ❌ | ❌ | ❌ | ❌ | +| Multi-format output | ✅ (4) | ❌ | ⚠️ | ⚠️ | ✅ (1) | +| i18n support | ✅ | ❌ | ⚠️ | ✅ | ❌ | +| Template system | ✅ | ❌ | ❌ | ✅ | ✅ | +| Declarative forms | ✅ | ❌ | ✅ | ⚠️ | N/A | + +### 4.3 Value Propositions Completo + +**Para Developers**: +- ✅ Type-safe configuration desde día 1 (Nickel schemas) +- ✅ Menos código de validación manual (schemas auto-validan) +- ✅ Documentación incluida en schemas (contratos son docs) +- ✅ Multi-format output (una fuente, múltiples consumidores) + +**Para DevOps/SRE**: +- ✅ Interactive IaC generation (menos errores de config) +- ✅ Validación antes de apply (Nickel contracts) +- ✅ Reproducible setup (TOML forms versionables) +- ✅ Script integration (CLI prompts en pipelines) + +**Para Organizations**: +- ✅ Consistent configuration (same forms across projects) +- ✅ Reduced onboarding time (guided setup wizards) +- ✅ Auditability (form definitions + results traceable) +- ✅ i18n support (international teams) + +**Unique Selling Points**: +1. **Nickel Integration** - Único en mercado +2. **Multi-Backend Flexibility** - Mismo form, diferentes contextos +3. **Forms + Prompts** - No forzado a elegir uno u otro +4. **Type-Safe Pipeline** - Contracts preserved end-to-end +5. **Production-Ready** - i18n, templates, validación, docs + +--- + +## 5. Capacidades y Características + +### 5.1 Functional Capabilities + +**Input Collection**: +- ✅ 8 tipos de prompts (text, password, select, multiselect, confirm, custom, editor, date) +- ✅ Forms declarativos en TOML +- ✅ Conditional logic (depends_on) +- ✅ Dynamic defaults (computed fields) +- ✅ Validation (regex, range, length, custom) +- ✅ Help text y documentación inline + +**Backend Support**: +- ✅ CLI - inquire-based terminal prompts (stdin fallback) +- ✅ TUI - ratatui full-screen interface (3-panel layout, Tab navigation) +- ✅ Web - axum + HTMX browser forms (RESTful API) +- ✅ Display modes: FieldByField, Complete + +**Nickel Workflow**: +- ✅ nickel-to-form: Schema → TOML form generation +- ✅ form execution: Interactive collection +- ✅ form-to-nickel: Results → Nickel code generation +- ✅ Contract preservation: Type constraints maintained +- ✅ Component support: Imports, merging, templates + +**Output Formats**: +- ✅ JSON (structured data, API consumption) +- ✅ YAML (configs, k8s, ansible) +- ✅ TOML (rust configs, settings) +- ✅ Nickel (type-safe configs) +- ✅ Text (simple key=value) + +**i18n & Templates**: +- ✅ Fluent-based localization (en-US, es-ES) +- ✅ Tera template engine +- ✅ Nickel template metaprogramming (.ncl.j2) +- ✅ Variable substitution +- ✅ Conditional rendering + +### 5.2 Non-Functional Capabilities + +**Performance**: +- Fast compilation (Rust, release build <30s) +- Low memory footprint (CLI <5MB, TUI <10MB) +- Minimal startup time (<100ms) + +**Reliability**: +- 80+ passing tests (unit + integration) +- Type-safe Rust (no runtime crashes) +- Graceful error handling +- Fallback behaviors (stdin, default values) + +**Usability**: +- Intuitive TOML form syntax +- Clear error messages +- Help text contextual +- i18n for international users + +**Maintainability**: +- Modular workspace structure +- Clean trait-based architecture +- Comprehensive documentation +- Example forms included + +**Portability**: +- Cross-platform (Linux, macOS, Windows) +- Single binary distribution +- No runtime dependencies +- Docker support + +--- + +## 7. Métricas y Success Criteria + +### 7.1 Technical Metrics + +**Code Quality**: +- Test coverage > 80% +- Zero clippy warnings (enforce) +- Clean compilation all features +- Documentation coverage > 90% + +**Performance**: +- Binary size < 15MB (release) +- Startup time < 100ms +- Memory usage < 20MB (TUI) +- Form rendering < 50ms + +### 7.2 Adoption Metrics + +**Community**: +- GitHub stars > 100 (first 6 months post-publish) +- crates.io downloads > 1000/month +- Active issues/PRs +- Contributor growth + +**Usage**: +- Example forms created by users +- Integration stories shared +- Blog posts/tutorials written +- Conference talks + +### 7.3 Quality Metrics + +**Reliability**: +- Bug reports < 5/month +- Critical bugs = 0 +- Response time < 48h +- Fix time < 7 days (non-critical) + +**User Satisfaction**: +- Positive feedback ratio > 80% +- Feature request alignment +- Documentation clarity +- Ease of use reports + +--- + +## 8. Roadmap y Future Considerations + +### 8.1 Immediate Focus (v0.1.x) + +**Naming Decision**: +- Decide: nickelconf vs nickeltalk vs keep typedialog +- Execute: Rename if chosen +- Update: All documentation and messaging + +**Stabilization**: +- Bug fixes from early users +- Documentation improvements +- Example forms expansion +- Performance optimizations + +### 8.2 Near-term Enhancements (v0.2.x) + +**Nickel Enhancements**: +- Deeper schema introspection +- More contract types supported +- Component template library +- Schema validation improvements + +**Backend Improvements**: +- TUI navigation enhancements +- Web backend styling/theming +- CLI colored output options +- Performance optimizations + +**New Features**: +- Form composition (reusable sections) +- Field dependencies (advanced logic) +- Custom validators library +- Plugin system for custom fields + +### 8.3 Long-term Vision + +**Ecosystem**: +- Form marketplace (shared forms) +- IDE integrations (VSCode extension) +- CI/CD integrations +- Cloud service (hosted forms) + +**Technology**: +- KCL integration (like Nickel) +- CUE language support +- GraphQL schema support +- Database schema integration + +**Beyond Configuration**: +- Survey/questionnaire system +- User onboarding workflows +- Admin panel generation +- API client generation + +--- + +## Conclusión + +typedialog es un proyecto maduro y bien posicionado que resuelve un problema real en la gestión de configuración. Su diferenciador único - la integración bidireccional con Nickel combinada con múltiples backends - lo posiciona de manera única en el mercado. + +El próximo paso crítico es una decisión de naming estratégica que refuerce esta posición única y comunique claramente el valor propuesto al mercado target. diff --git a/docs/project-naming-analysis.md b/docs/project-naming-analysis.md new file mode 100644 index 0000000..08521be --- /dev/null +++ b/docs/project-naming-analysis.md @@ -0,0 +1,359 @@ +# Project Naming and Positioning Analysis + +**Version**: 1.0 +**Date**: 2025-12-17 +**Status**: Ready for decision + +--- + +## Executive Summary + +The current name **"typedialog"** undersells the project's unique value proposition. A strategic rename would better communicate the distinctive capabilities to the target market. + +**Key Finding**: Nickel integration is THE unique differentiator. Any new name should prominently feature Nickel while maintaining flexibility for the multi-backend and interactive aspects. + +--- + +## Problems with "typedialog" + +### 1. Backend-Specific Reference +- Name tied to `inquire` crate (just one of three backends) +- Misleading now that project has ratatui (TUI) and axum (Web) backends +- Doesn't reflect the multi-backend architecture innovation + +### 2. Form-Centric Positioning +- "form" emphasizes only forms, not prompts/single inputs +- Inaccurate: project equally supports individual prompts and complete forms +- Creates false expectation of form-only capability + +### 3. Missing Nickel Integration +- **CRITICAL**: No communication of THE unique differentiator +- Nickel integration is unique in the market - no competitor combines this +- Name should signal this exclusive feature + +### 4. Generic Sound +- "typedialog" sounds like "just another form library" +- Fails to communicate type-safety, configuration focus, or multi-backend capability +- Doesn't differentiate from competitive offerings (dialoguer, inquire, etc.) + +### 5. Hidden Value Propositions +- No hint at: interactive dialog, bridge between schemas/formats, facilitator role +- Configuration management focus not obvious +- App/project scope not apparent + +--- + +## Strategic Positioning Requirements + +### Dimensions to Communicate (by priority) + +1. **Nickel Integration** (MUST) - THE unique differentiator, único en mercado +2. **Interactivo/Diálogo** (SHOULD) - Facilita mediante conversación con usuario +3. **Bridge** (SHOULD) - Puente entre schemas, formatos, humano-máquina +4. **Configuration/Settings** (SHOULD) - Core purpose +5. **Flexibility** (NICE) - Forms Y prompts - no solo uno +6. **Type-safety** (NICE) - Quality attribute from Nickel +7. **Facilitador** (NICE) - Simplifica la gestión +8. **Wide scope** (NICE) - Apps, scripts, DevOps - no limitado +9. **Memorable** (MUST) - Pronounceable, distinctive + +**Key Constraint**: Es imposible capturar TODOS los aspectos en un nombre. El nombre debe priorizar los top 2-3 elementos y el positioning/messaging cubre el resto. + +--- + +## Top 3 Finalists + +### Option 1: **nickelconf** ⭐ PRIMARY RECOMMENDATION + +**Etymology**: "nickel" (core tech) + "conf" (configuration) + +#### Coverage Analysis +``` +Nickel integration ✅✅ Explicit (primary identifier) +Interactivo/Diálogo ❌ Messaging-covered +Bridge ❌ Messaging-covered +Configuration/Settings ✅✅ Explicit (primary purpose) +Flexibility ✅ Neutral (conf = flexible container) +Type-safety ✅ Implicit (via Nickel) +Facilitador ⚠️ Neutral +Wide scope ✅ No limita dominio +Memorable ✅✅ Short, pronounceable, clear +──────────────────────────────────────────────── +SCORE: 7/9 explicit + 2/9 via messaging = STRONG +``` + +#### Strengths +- Directly signals Nickel integration (THE key differentiator) +- Clear configuration/settings focus +- Not limited to "forms" (conf is neutral, covers prompts too) +- Short, memorable, pronounceable, technical but accessible +- Professional, credible positioning +- Clean crate names: `nickelconf-core`, `nickelconf-cli`, `nickelconf-tui`, `nickelconf-web` + +#### Weaknesses +- Interactive/dialog aspect relies on messaging +- Bridge concept must be conveyed in positioning/docs + +#### Positioning +> "Interactive configuration powered by Nickel - bridging schemas and settings" + +#### Key Messaging +- "Dialoga con el usuario para configurar apps y proyectos con tipos validados" +- "Bridge: Nickel schemas → Interactive prompts/forms → YAML/JSON/TOML output" +- "Facilita settings tipados - single prompts o forms completos según necesidad" +- "CLI para scripts, TUI para setup, Web para interfaces - mismo config, diferentes contextos" + +#### Use Case Examples +- **Single prompt**: `nickelconf prompt --type password "API Key"` → captura un valor +- **Complete form**: `nickelconf form app-config.toml --backend tui` → multi-field setup +- **Nickel workflow**: `nickelconf nickel-to-form schema.ncl` → generates form from Nickel schema +- **Script integration**: Nushell/Bash scripts call `nickelconf` for validated inputs +- **Multi-format output**: Same input → JSON/YAML/TOML/Nickel depending on use + +--- + +### Option 2: **nickeltalk** ⭐ STRONG ALTERNATIVE + +**Etymology**: "nickel" (core tech) + "talk" (dialogue/interaction) + +#### Coverage Analysis +``` +Nickel integration ✅✅ Explicit (primary identifier) +Interactivo/Diálogo ✅✅ Explicit ("talk" = dialogue) +Bridge ⚠️ Implied (talk = communication bridge) +Configuration/Settings ⚠️ Messaging-required +Flexibility ✅ Neutral (talk cubre prompts y forms) +Type-safety ✅ Implicit (via Nickel) +Facilitador ✅ Implicit (talk = facilita comunicación) +Wide scope ✅ No limita dominio +Memorable ✅ Short, pronounceable, friendly +──────────────────────────────────────────────── +SCORE: 7/9 explicit + 2/9 via messaging = STRONG +``` + +#### Strengths +- Captures both top priorities: Nickel + Interactive/Dialog +- "Talk" enfatiza el aspecto de diálogo/conversación con usuario +- Friendly, approachable, less intimidating than "conf" +- Still short and memorable +- Implies facilitation and bridge (communication is connection) +- More distinctive than nickeLconf (fewer "talk" tools in ecosystem) + +#### Weaknesses +- "Talk" might sound less serious/technical than "conf" +- Configuration purpose less obvious (needs messaging) +- Could be mistaken for chat/AI tool rather than config tool +- Slightly less clear positioning + +#### Positioning +> "Talk to Nickel - Interactive type-safe configuration through dialogue" + +#### Key Messaging +- "Conversa con Nickel para configurar apps y proyectos" +- "Dialog-driven configuration: prompts, forms, type-safe settings" +- "Bridge schemas and formats through interactive dialogue" +- "Nickel schemas → Interactive talk → YAML/JSON/TOML output" + +#### Best For +- If emphasizing UX and developer experience over technical positioning +- Projects that want friendlier, more approachable branding +- Organizations focused on ease-of-use + +--- + +### Option 3: **nickelbridge** + +**Etymology**: "nickel" (core tech) + "bridge" (connection/intermediary) + +#### Coverage Analysis +``` +Nickel integration ✅✅ Explicit +Interactivo/Diálogo ⚠️ Implied (bridge connects human & machine) +Bridge ✅✅ Explicit (primary metaphor) +Configuration/Settings ⚠️ Messaging-required +Flexibility ✅ Neutral +Type-safety ✅ Implicit +Facilitador ✅ Implicit (bridge = facilitates) +Wide scope ✅ No limita dominio +Memorable ⚠️ Longer (3 syllables, but clear) +──────────────────────────────────────────────── +SCORE: 6/9 explicit + 3/9 via messaging = GOOD +``` + +#### Strengths +- Explicitly captures bridge metaphor (schemas ↔ formats, human ↔ machine) +- Nickel prominently featured +- Professional, technical positioning +- Clearly a facilitator/connector + +#### Weaknesses +- "Bridge" is overused in tech naming (less distinctive) +- Longer word (12 characters vs 10 for nickelconf) +- Interactive aspect less obvious +- Configuration purpose needs heavy messaging + +#### NOT RECOMMENDED +Less distinctive, longer, loses some positioning clarity compared to top 2 options. + +--- + +## Decision Matrix + +| Criterion | nickelconf | nickeltalk | nickelbridge | +|-----------|-----------|-----------|----------| +| Nickel prominence | ✅✅ | ✅✅ | ✅✅ | +| Interactive aspect | ❌ | ✅✅ | ⚠️ | +| Config focus | ✅✅ | ⚠️ | ⚠️ | +| Memorability | ✅✅ | ✅ | ✅ | +| Distinctiveness | ✅ | ✅✅ | ⚠️ | +| Professional tone | ✅✅ | ✅ | ✅✅ | +| Approachability | ✅ | ✅✅ | ⚠️ | +| Future-proofing | ✅ | ✅ | ✅ | + +--- + +## Decision Framework + +### Choose nickelconf if: +- Configuration/settings focus is most important to your positioning +- Want maximum technical credibility with developers +- Emphasize type-safety and contracts as primary value +- Prefer professional/serious tone +- Target: Infrastructure, DevOps, technical users + +### Choose nickeltalk if: +- Interactive/dialog aspect is most important +- Want friendly, approachable, UX-focused positioning +- Emphasize ease-of-use and developer experience +- Prefer conversational/accessible tone +- Target: Broader audience, emphasize usability + +### Choose nickelbridge if: +- Bridge/connector metaphor is critical to your story +- Emphasize interoperability (schemas ↔ formats) over other aspects +- Professional but with strong facilitator positioning +- Comfortable with longer name + +--- + +## Recommendation: nickelconf ⭐ + +### Rationale + +1. **Captures core identity**: Nickel (unique differentiator) + Config (core purpose) = clear positioning +2. **Professional positioning**: Credible with technical audiences (developers, DevOps, architects) +3. **Easy to explain**: "Type-safe configuration with Nickel" - immediately clear +4. **Messaging flexibility**: Interactive, bridge, facilitator aspects easily conveyed in docs/positioning +5. **Technical soundness**: Appeals to type-conscious developers and infrastructure engineers +6. **Future-proof**: Name doesn't limit scope if expanding to other schema languages later + +### Alternative: nickeltalk + +Strong alternative if your organization prioritizes: +- User experience and approachability +- Developer delight and friendly positioning +- Market differentiation through accessibility + +Both are viable. The choice depends on whether you lead with **technical credibility** (nickelconf) or **user experience** (nickeltalk). + +--- + +## Implementation Path (if renaming) + +### Complexity: Complex +- Full workspace rename with dependencies +- Import path updates +- Binary artifact renames +- Documentation overhaul + +### Tasks Required +1. Workspace `Cargo.toml` rename (precedes member crate renames) +2. All internal imports across crates +3. Binary artifacts in build scripts +4. All documentation files +5. Configuration paths (if hardcoded) +6. Examples and templates +7. Repository name (GitHub) +8. Migration guide for any existing users + +### Risks +- Breaking existing users (unlikely given v0.1.0 status) +- Loss of existing references/documentation links +- SEO reset if already indexed + +### Mitigations +1. Version bump to 0.2.0 (signals breaking change) +2. Maintain `typedialog` as deprecated alias +3. Create migration guide +4. Comprehensive search/replace validation + +### Validation +```bash +# Must pass before release +cargo check --all-targets --all-features +cargo test --all-targets --all-features +cargo build --release --all-targets +cargo clippy -- -D warnings + +# Smoke tests +nickelconf --version +nickelconf-tui --version +nickelconf-web --version +``` + +--- + +## Alternative: Enhanced Positioning (Keep typedialog) + +If rebranding costs outweigh benefits: + +### Approach +1. Rewrite README with multi-backend focus +2. Emphasize Nickel integration prominently +3. Clarify not just an inquire wrapper +4. Document multi-context use cases +5. Create positioning explainer + +### Challenges +- Name still references one backend (confusing) +- Harder to communicate innovation without name change +- Missing strategic positioning opportunity + +### Benefits +- Zero technical disruption +- No migration costs +- Maintains existing references +- Faster execution + +--- + +## Naming Alternatives Analyzed (not recommended) + +### Considered but Rejected + +- **formstack**: Exists as company (Formstack.com), trademark risk +- **formulate**: Good name but loses Nickel prominence +- **omniform**: Premium positioning but longer, less clear +- **formkit**: Conflicts with Vue.js FormKit library +- **formspec**: Clear but generic, doesn't emphasize Nickel +- **dialogconf**: Loses Nickel in name (critical mistake) +- **confkit**: Generic, doesn't differentiate with Nickel + +--- + +## Conclusion + +**nickelconf** is the recommended path forward. It clearly communicates the two most important aspects of the project (Nickel + Configuration) while remaining short, memorable, and technical. + +The secondary messaging around interactive dialog, bridge functionality, and facilitator role can be effectively conveyed through positioning statements, documentation, and examples. + +This strategic rename would: +1. Immediately signal the unique market position +2. Attract the right target audience +3. Support long-term branding and differentiation +4. Enable clearer communication of value proposition +5. Position the project for successful market launch + +**Decision needed**: nickelconf vs nickeltalk vs keep typedialog + +The choice between nickelconf and nickeltalk depends on whether you prioritize **technical credibility** or **user experience** in your positioning.