chore: add docs
This commit is contained in:
Jesús Pérez
parent
cb6aa2ff82
commit
e2fc914047
GPG Key ID:
9F243E355E0BC939
443
docs/BUILD.md
Normal file
443
docs/BUILD.md
Normal file
@ -0,0 +1,443 @@
|
||||
<div align="center">
|
||||
<img src="../imgs/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
|
||||
</div>
|
||||
|
||||
# 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.
|
||||
362
docs/CONFIGURATION.md
Normal file
362
docs/CONFIGURATION.md
Normal file
@ -0,0 +1,362 @@
|
||||
<div align="center">
|
||||
<img src="../imgs/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
|
||||
</div>
|
||||
|
||||
# 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
|
||||
156
docs/DEPENDENCIES.md
Normal file
156
docs/DEPENDENCIES.md
Normal file
@ -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
|
||||
438
docs/DEVELOPMENT.md
Normal file
438
docs/DEVELOPMENT.md
Normal file
@ -0,0 +1,438 @@
|
||||
<div align="center">
|
||||
<img src="../imgs/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
|
||||
```
|
||||
|
||||
### 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.
|
||||
306
docs/INSTALLATION.md
Normal file
306
docs/INSTALLATION.md
Normal file
@ -0,0 +1,306 @@
|
||||
<div align="center">
|
||||
<img src="../imgs/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
|
||||
</div>
|
||||
|
||||
# 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)
|
||||
126
docs/README.md
Normal file
126
docs/README.md
Normal file
@ -0,0 +1,126 @@
|
||||
<div align="center">
|
||||
<img src="../imgs/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
|
||||
</div>
|
||||
|
||||
# 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
|
||||
446
docs/RELEASE.md
Normal file
446
docs/RELEASE.md
Normal file
@ -0,0 +1,446 @@
|
||||
<div align="center">
|
||||
<img src="../imgs/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
|
||||
</div>
|
||||
|
||||
# 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.
|
||||
512
docs/project-definition.md
Normal file
512
docs/project-definition.md
Normal file
@ -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<Value>;
|
||||
fn execute_form_complete(&mut self, form: &Form) -> Result<HashMap<String, Value>>;
|
||||
}
|
||||
|
||||
// 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.
|
||||
359
docs/project-naming-analysis.md
Normal file
359
docs/project-naming-analysis.md
Normal file
@ -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.
|
||||
Loading…
x
Reference in New Issue
Block a user