jesus/TypeDialog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: new projet folders structure

Browse Source
This commit is contained in:
Jesús Pérez 2025-12-24 03:11:32 +00:00
parent 18dbde1de1
commit 9ca1bfb8cf
Signed by: jesus
GPG Key ID: 9F243E355E0BC939
55 changed files with 9258 additions and 24948 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
Dockerfile.cross → .woodpecker/Dockerfile.cross
View File

363
CHANGELOG.md Normal file
View File

@ -0,0 +1,363 @@
# Changes
## [Unreleased]
### Added - Professional Quality Improvements
**Community Health Files**
- Created `CONTRIBUTING.md` with contribution guidelines, development workflow, and coding standards
- Created `SECURITY.md` with vulnerability reporting process and security best practices
- Created `CODE_OF_CONDUCT.md` with Contributor Covenant 2.1
**Security & Compliance**
- Created `deny.toml` with cargo-deny configuration for license/security policies
- Configured Renovate for automated dependency updates with automerge for minor/patch
- Added pre-commit hooks (fmt, clippy, shellcheck, markdownlint, trailing-whitespace, check-yaml/toml/json)
**Testing Infrastructure**
- Configured cargo-llvm-cov for code coverage tracking
- Integrated Codecov for coverage reporting in CI
- Added coverage badge to README
- Created benchmark tests with criterion for performance baselines
- Added property-based testing with proptest for validation functions
- Justfile recipes: `just dev::coverage`, `just dev::bench`, `just dev::coverage-open`
**CI/CD Enhancements**
- Multi-OS CI matrix: Linux, macOS, Windows (was Linux only)
- Cargo cache with rust-cache action (faster CI builds)
- Code coverage job uploading to Codecov
- Benchmark job running on pull requests
- cargo-deny checks in CI pipeline
**Release Automation**
- Full automated release workflow: tag → build multi-OS → publish GitHub + crates.io
- Builds for 5 targets: Linux x86_64/aarch64, macOS x86_64/aarch64, Windows x86_64
- Automatic tarball + SHA256 generation and upload
- Automatic crates.io publishing in dependency order
- cargo-binstall metadata for easy installation: `cargo binstall typedialog`
**Impact**
- Code coverage now tracked (was unknown)
- CI tests on 3 operating systems (was 1)
- Release process fully automated (was manual)
- 7 pre-commit hooks validate code quality
- Benchmark baselines established for performance tracking
- Property tests validate edge cases
- Security scanning with cargo-deny
- Automated dependency updates with Renovate
### Added - Multi-Language Linting System
**Linting Infrastructure**
- Created `.cargo/config.toml` with strict rustflags (warnings, future-incompatible, unused, etc.)
- Extended `justfiles/dev.just` with language-specific linters:
- `just dev::lint-rust` - Clippy linting
- `just dev::lint-bash` - Shellcheck for 142 bash scripts
- `just dev::lint-nickel` - Nickel typecheck for 63 files
- `just dev::lint-nushell` - Nushell validation for 9 scripts
- `just dev::lint-markdown` - Markdownlint for docs/ folder only
- `just dev::lint-all` - Execute all linters
- Extended `justfiles/ci.just` with CI-compatible linter recipes
- Updated `just check-all` to include multi-language linting
**GitHub Actions CI/CD**
- Created `.github/workflows/ci.yml` with automated linting matrix
- Parallel linting jobs per language (rust, bash, nickel, nushell, markdown)
- Integrated with test and build stages
**Linter Tools**
- Added shellcheck for bash script analysis
- Added markdownlint-cli2 for docs/ validation
- Leveraged existing nickel CLI for typecheck
- Leveraged nushell built-in --check flag
**Configuration**
- Created `.markdownlintrc` with basic rules (MD013, MD033, MD041 disabled)
- Updated `scripts/check_deps.sh` to verify all linter dependencies
- Updated `docs/build.md` with shellcheck and markdownlint installation
**Impact**
- 142 bash scripts now validated with shellcheck
- 63 Nickel files now typechecked
- 9 Nushell scripts validated
- docs/ markdown files (subset of 8,530 total) validated
- Rust code enforces stricter compilation standards via rustflags
### Added - TypeDialog Agent System
**Multi-Provider LLM Support**
- Complete LLM provider abstraction supporting Claude, OpenAI, Gemini, and Ollama
- Unified trait-based architecture for consistent API across providers
- Streaming support with two protocols: SSE (Claude/OpenAI) and JSON (Gemini/Ollama)
- Token usage tracking across all providers (except OpenAI streaming limitation)
- Local execution with Ollama for privacy-sensitive workloads
**Agent Execution System**
- New `.agent.mdx` file format for defining AI agents
- YAML frontmatter configuration with `@agent`, `@input`, `@import`, `@shell`, `@validate` directives
- CLI tool `typedialog-ag` for executing agent files
- Server component `typedialog-ag-server` for HTTP API access
**Template System**
- Tera template engine (Jinja2-compatible) for variable substitution and conditionals
- Template variables with `{{ var }}` syntax
- Conditional logic with `{% if %}...{% endif %}`
- File imports with glob pattern support: `@import "src/**/*.rs" as code`
- Shell command integration: `@shell "git status" as status`
- Environment variable loading
**Output Validation**
- Configurable validation rules for agent outputs
- Format validation (markdown, JSON, YAML)
- Content requirements (`must_contain` checks)
- Length constraints (`min_length`, `max_length`)
**Provider-Specific Features**
- **Claude (Anthropic)**: 3 models (Haiku, Sonnet, Opus), excellent code/reasoning, SSE streaming
- **OpenAI (GPT)**: gpt-4o, gpt-4o-mini, o1, o3 models, broad capabilities, SSE streaming
- **Gemini (Google)**: Creative tasks, 2M context window, free tier, JSON streaming
- **Ollama (Local)**: Complete privacy, offline operation, no API costs, supports llama2/mistral/codellama/etc.
### Added - Organization & Documentation
**Project Structure**
- Created `demos/agent/` with 4 provider comparison demos
- Created `tests/agent/` with validation tests
- Created `examples/12-agent-execution/` with 8 practical CLI examples
- Organized docs into backend-specific folders: `docs/cli/`, `docs/tui/`, `docs/web/`, `docs/ai/`, `docs/agent/`, `docs/encryption/`
**User Documentation**
- `docs/agent/README.md` - Agent system overview and navigation
- `docs/agent/getting_started.md` - Installation and first agent guide
- `docs/agent/llm_providers.md` - Complete provider comparison (400+ lines)
- `docs/cli/README.md` - CLI backend documentation
- `docs/tui/README.md` - TUI backend documentation
- `docs/web/README.md` - Web backend documentation
- `docs/ai/README.md` - AI backend documentation
- `docs/encryption/README.md` - Encryption documentation
**Agent Examples**
- `basic-greeting.agent.mdx` - Simple introduction (Claude Haiku)
- `code-review.agent.mdx` - Security & performance analysis (Claude Sonnet)
- `documentation.agent.mdx` - Generate docs from code (GPT-4o)
- `task-planner.agent.mdx` - Project planning (Claude Sonnet)
- `local-privacy.agent.mdx` - Privacy-first analysis (Ollama/llama2)
- `creative-writer.agent.mdx` - Creative content (Gemini 2.0)
- `refactoring-assistant.agent.mdx` - Code refactoring (GPT-4o-mini)
- `architect.agent.mdx` - High-level design (Claude Opus)
**Cross-References**
- Extensive linking between examples, tests, demos, and documentation
- Navigation structure: examples → demos → tests → core → technical docs
### Added - Configuration & Provisioning
**Configuration Structure**
- Renamed `config/agent/` → `config/ag/` for consistency with `typedialog-ag` binary name
- Added configuration profiles for all 6 backends: `cli/`, `tui/`, `web/`, `ai/`, `ag/`, `prov-gen/`
- Each backend has 3 environments: `default.toml`, `dev.toml`, `production.toml`
- Total: 18 configuration files (6 backends × 3 environments)
**config/ag/** - Agent configuration (LLM execution)
- `default.toml` - Claude Haiku default, streaming enabled, Tera templates
- `dev.toml` - Ollama (local) for development, debug logging, temperature 0.7
- `production.toml` - Claude Sonnet, lower temperature (0.3), rate limiting enabled
**config/prov-gen/** - Provisioning generator configuration (IaC)
- `default.toml` - AWS + Hetzner providers, Nickel validation, AI disabled
- `dev.toml` - Hetzner + LXD (cheaper), Ollama for AI, verbose logging
- `production.toml` - AWS + GCP, strict validation, encryption required, tests required
**Provisioning Generator Templates**
- Created `provider-gcp-section.toml` (256 lines, 15 elements)
- Google Cloud Platform: 24 regions, 16 machine types (e2/n1/n2/c2)
- Project ID + Service Account authentication
- Disk types: Standard, Balanced SSD, Premium SSD, Ultra SSD
- VPC networking, preemptible instances, deletion protection
- Created `provider-azure-section.toml` (296 lines, 17 elements)
- Microsoft Azure: 30 regions globally
- Service Principal authentication (Tenant ID, Client ID, Secret)
- 12 VM sizes (B-series burstable, D/E-series, F-series compute)
- Managed disks, Virtual Networks, accelerated networking
- Created `provider-lxd-section.toml` (207 lines, 16 elements)
- LXD containers and virtual machines (local/remote)
- 10 base images (Ubuntu, Debian, Alpine, Rocky, Arch)
- CPU/Memory/Disk limits, 5 storage pools (dir, zfs, btrfs, lvm)
- Network modes: lxdbr0 (NAT), host, macvlan
- Nesting support (Docker inside LXD), cloud-init integration
**Total provider templates**: 6 providers (AWS, GCP, Azure, Hetzner, UpCloud, LXD) - 1,191 lines
**Dependency Management**
- Created `scripts/check_deps.sh` - Automated dependency verification script
- Checks critical dependencies: `just`, `nickel`, `cargo`, `prov-ecosystem`, `secretumvault`
- Exit status 0 if all found, 1 if any missing
- Provides installation instructions for missing dependencies
**Provisioning Generator Command Enhancements**
- Added `-f, --format <FORMAT>` flag to `typedialog-prov-gen templates` command
- Supported formats: `json`, `yaml`, `toml`, `text` (default)
- Enables machine-readable template listing for automation and integration
- JSON/YAML for CI/CD pipelines, TOML for configuration files
- Template path display: Shows resolved absolute path before listing
- Output: "From: /absolute/path/to/templates"
- Helps users verify which template directory is loaded
- TemplateCategory structure now serializable across all formats
- Consistent structure: `name`, `description`, `templates[]`
- TOML output uses `[[categories]]` array-of-tables format
### Changed - Documentation Updates
**docs/build.md** - Critical Dependencies Section (320+ lines added)
- **Internal Dependencies**: `prov-ecosystem` (for typedialog-prov-gen), `secretumvault` (for encryption)
- Installation: sibling directory or git submodule
- Path configuration: Cargo.toml paths, environment variables
- Verification commands
- **External Dependencies**: `just` (command runner), `Nickel` (configuration language)
- Multi-platform installation: Homebrew, cargo, from source
- PATH configuration
- Verification tests
- **Dependency Quick Check**: Bash script to verify all dependencies
- **Troubleshooting**: 3 common issues with solutions each
- prov-ecosystem/secretumvault not found (3 solutions)
- Nickel binary not found (3 solutions)
- just command not found (3 solutions)
**docs/README.md** - Navigation Updates
- Added "Critical Dependencies" to Building section
- Updated "Building & Distribution" with dependencies reference
**config/README.md** - Complete Backend Documentation (550+ lines)
- Documented all 6 backends: CLI, TUI, Web, AI, Agent (ag), Prov-gen
- Each backend has: configuration table, usage examples, features list
- **AI Backend**: RAG pipeline, embeddings (OpenAI/Ollama), vector store, knowledge graphs
- **Agent Backend**: Multi-provider LLM, Tera templates, streaming, variable substitution
- **Prov-gen**: Multi-cloud IaC, 7-layer validation, Nickel integration, AI-assisted generation
- Added configuration details for AI, Agent, and Prov-gen backends
- Updated development and production configuration examples
- Distribution structure updated to show 6 backends
**README.md** - Main Project Documentation
- Updated Features: "6 Backends" (was "3 Backends")
- Added **AI Backend section** (lines 95-113)
- RAG system with semantic search
- Multi-provider embeddings (OpenAI, Ollama)
- Vector store (in-memory, Redis)
- Knowledge graph generation
- Added **Provisioning Generator section** (lines 182-223)
- Infrastructure as Code generation
- Quick example with 3 command variants
- 6 features: Multi-cloud, 7-layer validation, Nickel, AI-assist, templates, profiles
- Supported providers table: AWS, GCP, Azure, Hetzner, UpCloud, LXD
- Updated Configuration structure: 6 backends listed
- Updated Project Structure: All 9 crates documented
- Updated Key Technologies: Organized into Core, Backends, AI & Agent, Infrastructure
- Updated Examples: Added `11-prov-gen/` and `12-agent-execution/` categories
**docs/prov-gen/README.md**
- Updated Multi-Provider Support: AWS, GCP, Azure, Hetzner, UpCloud, LXD (was AWS, GCP, Azure, Hetzner, LXD, bare metal)
- Changed "generates complete provisioning" → "generates provisioning" (modesty)
### Changed - Naming Consistency
**Package Renaming**
- `typeagent-core` → `typedialog-ag-core`
- `typeagent-cli` → `typedialog-ag`
- `typeagent-server` → `typedialog-ag-server`
- `config/agent/` → `config/ag/`
**Rationale**: Align with project-wide `typedialog-*` naming convention and binary names
**Impact**
- Updated 50+ files (imports, docs, scripts, configs)
- Updated workspace `Cargo.toml` dependencies
- Updated all crate manifests
- Updated justfile recipes
- Updated configuration directory structure
- 53 tests passing, 0 clippy warnings after refactor
### Changed - Build & Distribution
**Justfile Updates**
- Added `just build::agent` - Build Agent CLI
- Added `just build::agent-server` - Build Agent server
- Added `just build::prov-gen` - Build Provisioning Generator
- Added `just test::agent` - Test Agent system (53 tests)
- Added `just test::prov-gen` - Test Provisioning Generator (11 tests)
- Updated `just build::all` to include Agent and Prov-gen builds
- Fixed `just test::agent` - Removed invalid lib test for binary-only `typedialog-ag` crate
**Script Updates**
- `scripts/create_distro.sh` - Include all binaries: `typedialog-ag`, `typedialog-ag-server`, `typedialog-prov-gen`
- `scripts/check_deps.sh` - New dependency verification script (67 lines)
- `installers/bootstrap/install.sh` - Install Agent and Prov-gen binaries
- `installers/bootstrap/install.ps1` - Install Agent and Prov-gen binaries (Windows)
- `.woodpecker/Dockerfile.cross` - Cross-compile Agent and Prov-gen binaries
**Build Features**
- New feature flag `FEATURES_AGENT := "markup,nickel,cache"`
- Agent and Prov-gen builds integrated into full CI/CD pipeline
- All builds verified: `just build::prov-gen` ✓, `just build::agent` ✓
- All tests passing: `just test::prov-gen` ✓ (11 tests), `just test::agent` ✓ (53 tests, 5 ignored)
## [Previous]
### Added
**RepeatingGroup Duplicate Detection**
- Implemented duplicate item validation across all backends (CLI, TUI, Web)
- Added `unique = true` attribute support to prevent duplicate items
- Added item counter display updates in Web backend
- New `is_duplicate()` function in CLI and TUI backends
**Web Backend Improvements**
- Refactored JavaScript: Replaced global constants with closure-based state management
- Added `render_global_repeating_group_script()` for generic repeating group handling
- Configuration stored in `data-*` attributes: `data-min-items`, `data-max-items`, `data-has-unique`, `data-unique-key`, `data-field-names`
- Live item counter updates after add/delete operations
- Single document-level event delegation for all repeating group interactions
**Documentation**
- Updated `docs/field_types.md` with unique validation details
- Updated `examples/README.md` with RepeatingGroup testing commands
- Added `docs/field_types.md` (new file)
- Updated example forms with `unique = true` attribute
### Fixed
- **CLI Backend**: Fixed validation of duplicate items in add/edit operations
- **TUI Backend**: Fixed validation of duplicate items with error overlay feedback
- **Web Backend**: Fixed `has_unique` flag reading from field definition (was incorrectly scanning fragment fields)
- **Web Backend**: Fixed item counter not updating when adding/deleting items
### Changed
**Architecture**
- Each repeating group now maintains independent state via closure
- Removed ~600 lines of dead code in Web JavaScript
- Event handling now context-aware (finds correct repeating group controller)
**Examples**
- `examples/05-fragments/array-trackers.toml`: Added `unique = true` to UDP and HTTP tracker arrays
- `examples/07-nickel-generation/arrays-form.toml`: Added `unique = true` to all RepeatingGroup fields
### Technical Notes
- Duplicate detection compares ALL field values when `unique = true`
- Works consistently across CLI, TUI, and Web backends
- Backwards compatible: repeating groups without `unique = true` unaffected
- max_items limit already enforced in all backends (no changes needed)
### Testing
- All 174 unit tests passing
- No clippy warnings
- Build verified with `--all-features` flag
- Manual testing in Web backend: duplicate detection working correctly
- Item counter updates verified on add/delete operations

57
CHANGES.md
View File

@ -1,57 +0,0 @@
# Changes
## [Unreleased]
### Added
**RepeatingGroup Duplicate Detection**
- Implemented duplicate item validation across all backends (CLI, TUI, Web)
- Added `unique = true` attribute support to prevent duplicate items
- Added item counter display updates in Web backend
- New `is_duplicate()` function in CLI and TUI backends
**Web Backend Improvements**
- Refactored JavaScript: Replaced global constants with closure-based state management
- Added `render_global_repeating_group_script()` for generic repeating group handling
- Configuration stored in `data-*` attributes: `data-min-items`, `data-max-items`, `data-has-unique`, `data-unique-key`, `data-field-names`
- Live item counter updates after add/delete operations
- Single document-level event delegation for all repeating group interactions
**Documentation**
- Updated `docs/FIELD_TYPES.md` with unique validation details
- Updated `examples/README.md` with RepeatingGroup testing commands
- Added `docs/FIELD_TYPES.md` (new file)
- Updated example forms with `unique = true` attribute
### Fixed
- **CLI Backend**: Fixed validation of duplicate items in add/edit operations
- **TUI Backend**: Fixed validation of duplicate items with error overlay feedback
- **Web Backend**: Fixed `has_unique` flag reading from field definition (was incorrectly scanning fragment fields)
- **Web Backend**: Fixed item counter not updating when adding/deleting items
### Changed
**Architecture**
- Each repeating group now maintains independent state via closure
- Removed ~600 lines of dead code in Web JavaScript
- Event handling now context-aware (finds correct repeating group controller)
**Examples**
- `examples/05-fragments/array-trackers.toml`: Added `unique = true` to UDP and HTTP tracker arrays
- `examples/07-nickel-generation/arrays-form.toml`: Added `unique = true` to all RepeatingGroup fields
### Technical Notes
- Duplicate detection compares ALL field values when `unique = true`
- Works consistently across CLI, TUI, and Web backends
- Backwards compatible: repeating groups without `unique = true` unaffected
- max_items limit already enforced in all backends (no changes needed)
### Testing
- All 174 unit tests passing
- No clippy warnings
- Build verified with `--all-features` flag
- Manual testing in Web backend: duplicate detection working correctly
- Item counter updates verified on add/delete operations

208
README.md
View File

@ -1,14 +1,17 @@
<div align="center">
<img src="imgs/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
<img src="assets/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
</div>
[![CI](https://github.com/jesusperezlorenzo/typedialog/actions/workflows/ci.yml/badge.svg)](https://github.com/jesusperezlorenzo/typedialog/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/jesusperezlorenzo/typedialog/branch/main/graph/badge.svg)](https://codecov.io/gh/jesusperezlorenzo/typedialog)
# TypeDialog
> ▲ Typed Dialogs you can tRust.
> ▲ Create Type-Safe Interactive Dialogs.
> Prompts, forms, or schemas—type-safe and backend-agnostic.
> Prompts, forms, schemas definition, use backends (CLI, TUI, Web, AI).
> Run on CLI, TUI, or Web. Output to JSON, YAML, TOML, or [Nickel](https://nickel-lang.org).
> Extend with LLM agents, IaC generation, and [Nickel](https://nickel-lang.org) validation.
## Features
@ -18,7 +21,7 @@
- **Multi-Language Support**: Fluent (.ftl) translations with automatic locale detection
- **Multiple Output Formats**: JSON, YAML, TOML, and Nickel output
- **Zero Runtime Dependencies**: Core library runs anywhere, no external tools required
- **3 Backends**: CLI (inquire), TUI (ratatui), Web (axum)
- **6 Backends**: CLI (inquire), TUI (ratatui), Web (axum), AI (RAG/embeddings), Agent (LLM execution), Prov-gen (IaC generation)
### Integration Key
@ -29,7 +32,7 @@
### Installation
See [docs/INSTALLATION.md](docs/INSTALLATION.md) for detailed setup.
See [docs/installation.md](docs/installation.md) for detailed setup.
Requirements:
- **Rust 1.70+** - [Install](https://rustup.rs/)
@ -92,8 +95,137 @@ cargo run -p typedialog-web -- --config config/web/dev.toml
**Use for:** SaaS platforms, public forms, mobile-friendly interfaces
**See:** [`examples/04-backends/web/`](examples/04-backends/web/)
### AI Backend (typedialog-ai)
Retrieval-Augmented Generation (RAG) system with semantic search and embeddings.
```bash
# Query knowledge base
typedialog-ai --config config/ai/dev.toml --query "How do I configure encryption?"
# Build knowledge graph
typedialog-ai --config config/ai/production.toml --build-graph ./docs
```
**Use for:** Documentation search, context-aware assistance, knowledge retrieval, semantic search
**Features:**
- Multi-provider embeddings (OpenAI, Ollama)
- Vector store (in-memory, Redis)
- Knowledge graph generation
- Context retrieval for LLMs
**Learn more:** [AI Backend Documentation](docs/ai/)
**Complete backend guide:** [Backend-Specific Examples](examples/04-backends/)
## TypeDialog Agent (typedialog-ag)
**AI agent execution from markdown files** with multi-provider LLM support.
Execute AI agents defined as `.agent.mdx` files with template variables, file imports, shell integration, and output validation.
### Quick Example
Create `hello.agent.mdx`:
```yaml
---
@agent {
role: friendly assistant,
llm: claude-3-5-haiku-20241022
}
@input name: String
---
Say hello to {{name}} in a warm and friendly way!
```
Run it:
```bash
typedialog-ag hello.agent.mdx
# Prompts: name (String): Alice
# Output: Hello Alice! It's wonderful to meet you! ...
```
### Supported LLM Providers
| Provider | Models | Best For | Privacy |
|----------|--------|----------|---------|
| **Claude** | Haiku, Sonnet, Opus | Code, reasoning, analysis | Cloud |
| **OpenAI** | GPT-4o, GPT-4o-mini, o1, o3 | Code, general tasks | Cloud |
| **Gemini** | 2.0 Flash, 1.5 Pro | Creative, multi-modal | Cloud (free tier) |
| **Ollama** | llama2, mistral, codellama, etc. | Privacy, offline, free | Local |
### Features
- **Template System**: Variables (`{{var}}`), conditionals (`{% if %}`), file imports (`@import`) - Tera/Jinja2
- **Context Injection**: Load files with glob patterns, execute shell commands
- **Output Validation**: Format, content, and length validation
- **Streaming**: Real-time token-by-token responses
- **Multi-Provider**: Switch between Claude, OpenAI, Gemini, or local Ollama
### Examples
```bash
# Code review with Claude Sonnet
typedialog-ag examples/12-agent-execution/code-review.agent.mdx
# Creative writing with Gemini
typedialog-ag examples/12-agent-execution/creative-writer.agent.mdx
# Privacy-first analysis with Ollama (local)
typedialog-ag examples/12-agent-execution/local-privacy.agent.mdx
```
**Learn more:**
- [Agent Documentation](docs/agent/) - Complete guide
- [Getting Started](docs/agent/getting_started.md) - Installation and first agent
- [LLM Providers](docs/agent/llm_providers.md) - Provider comparison
- [Examples](examples/12-agent-execution/) - 8 practical use cases
## Provisioning Generator (typedialog-prov-gen)
**Infrastructure as Code generation** from TypeDialog forms with multi-cloud support.
Generate infrastructure configurations for AWS, GCP, Azure, Hetzner, UpCloud, and LXD from interactive forms or declarative specifications.
### Quick Example
```bash
# Generate infrastructure with interactive prompts
typedialog-prov-gen --name myproject --output ./provisioning
# Use specific providers
typedialog-prov-gen --name myproject --providers aws,hetzner --ai-assist
# Dry run (preview without generating)
typedialog-prov-gen --name myproject --dry-run
```
### Features
- **Multi-Cloud Support**: AWS, GCP, Azure, Hetzner, UpCloud, LXD
- **7-Layer Validation**: Forms → Constraints → Values → Validators → Schemas → Defaults → JSON
- **Nickel Integration**: Type-safe configuration contracts with schema validation
- **AI-Assisted Generation**: Optional Claude/Ollama assistance for complex configurations
- **Template Fragments**: Reusable provider-specific configuration blocks
- **Environment Profiles**: Development, staging, production presets
### Supported Providers
| Provider | Type | Best For |
|----------|------|----------|
| **AWS** | Cloud | Enterprise, scalability, full service catalog |
| **GCP** | Cloud | Data analytics, ML workloads |
| **Azure** | Cloud | Enterprise integration, hybrid cloud, Microsoft ecosystem |
| **Hetzner** | Cloud/Dedicated | Cost-effective European hosting |
| **UpCloud** | Cloud | High-performance SSD, flexible pricing |
| **LXD** | Local/Private | Development, on-premise, containers |
**Learn more:**
- [Prov-gen Documentation](docs/prov-gen/) - Complete guide
- [Examples](examples/11-prov-gen/) - Multi-cloud configurations
- [Templates](crates/typedialog-prov-gen/templates/) - Provider fragments
## Nickel Integration
**Type-safe configuration management** with bidirectional Nickel schema support.
@ -118,7 +250,7 @@ typedialog form schema.toml --backend tui
- Deterministic configuration generation
**Learn more:**
- [Nickel Integration Guide](docs/CONFIGURATION.md#nickel-integration)
- [Nickel Integration Guide](docs/configuration.md#nickel-integration)
- [Examples: 06-integrations/nickel/](examples/06-integrations/nickel/)
- [Nickel Lang Documentation](https://nickel-lang.org/)
@ -128,11 +260,11 @@ Complete documentation in [`docs/`](docs/):
| Document | Purpose |
|----------|---------|
| [**INSTALLATION.md**](docs/INSTALLATION.md) | Prerequisites & setup |
| [**DEVELOPMENT.md**](docs/DEVELOPMENT.md) | Development workflows |
| [**BUILD.md**](docs/BUILD.md) | Building & cross-compilation |
| [**RELEASE.md**](docs/RELEASE.md) | Release process |
| [**CONFIGURATION.md**](docs/CONFIGURATION.md) | Backend & Nickel configuration |
| [**installation.md**](docs/installation.md) | Prerequisites & setup |
| [**development.md**](docs/development.md) | Development workflows |
| [**build.md**](docs/build.md) | Building & cross-compilation |
| [**release.md**](docs/release.md) | Release process |
| [**configuration.md**](docs/configuration.md) | Backend & Nickel configuration |
## Examples
@ -147,6 +279,8 @@ Complete working examples in [`examples/`](examples/):
| **Composition** | [05-fragments](examples/05-fragments/) | Reusable components |
| **Integrations** | [06-integrations](examples/06-integrations/) | [Nickel](examples/06-integrations/nickel/), [i18n](examples/06-integrations/i18n/) |
| **Production** | [09-templates](examples/09-templates/) | Real-world use cases |
| **Provisioning** | [11-prov-gen](examples/11-prov-gen/) | Infrastructure generation, multi-cloud |
| **Agent Execution** | [12-agent-execution](examples/12-agent-execution/) | LLM agents, AI workflows |
**Quick start:** [examples/README.md](examples/README.md)
@ -169,7 +303,7 @@ just distro::create-package
just ci::full
```
See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for details.
See [docs/development.md](docs/development.md) for details.
## Building & Distribution
@ -191,7 +325,7 @@ just distro::create-checksums
Package includes binaries, configs, and installers.
See [docs/BUILD.md](docs/BUILD.md) for complete guide.
See [docs/build.md](docs/build.md) for complete guide.
### Install Distributed Release
@ -203,7 +337,7 @@ curl -fsSL https://github.com/anthropics/typedialog/releases/download/latest/ins
irm https://github.com/anthropics/typedialog/releases/download/latest/install.ps1 | iex
```
See [docs/RELEASE.md](docs/RELEASE.md) for release workflow.
See [docs/release.md](docs/release.md) for release workflow.
## Configuration
@ -213,22 +347,30 @@ Pre-configured settings for each backend and environment:
config/
├── cli/ # default, dev, production
├── tui/ # default, dev, production
└── web/ # default, dev, production
├── web/ # default, dev, production
├── ai/ # default, dev, production (RAG/embeddings)
├── ag/ # default, dev, production (Agent/LLM)
└── prov-gen/ # default, dev, production (IaC generation)
```
See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for all options.
See [docs/configuration.md](docs/configuration.md) and [config/README.md](config/README.md) for all options.
## Project Structure
```
typedialog/
├── crates/
│ ├── typedialog-core/ # Core library
│ ├── typedialog-core/ # Core library (forms, validation)
│ ├── typedialog/ # CLI binary
│ ├── typedialog-tui/ # TUI binary
│ └── typedialog-web/ # Web binary
├── config/ # Configuration files
├── examples/ # Working examples
│ ├── typedialog-web/ # Web binary
│ ├── typedialog-ai/ # AI backend (RAG, embeddings)
│ ├── typedialog-ag-core/ # Agent core library
│ ├── typedialog-ag/ # Agent CLI binary
│ ├── typedialog-ag-server/ # Agent HTTP server
│ └── typedialog-prov-gen/ # Provisioning generator
├── config/ # Configuration files (6 backends × 3 envs)
├── examples/ # Working examples (12 categories)
├── scripts/ # Build automation
├── installers/ # Installation scripts
├── docs/ # Documentation
@ -238,15 +380,29 @@ typedialog/
## Key Technologies
**Core:**
- **Rust** - Type-safe systems language
- **inquire** - Interactive prompt library (CLI backend)
- **Ratatui** - Terminal UI framework (TUI backend)
- **Axum** - Web framework (Web backend)
- **Nickel** - Type-safe configuration language (schema integration)
- **TOML** - Form and configuration language
- **Fluent** - Multi-language translation system
- **just** - Command orchestration
**Backends:**
- **inquire** - Interactive prompt library (CLI backend)
- **Ratatui** - Terminal UI framework (TUI backend)
- **Axum** - Web framework (Web backend)
**AI & Agent:**
- **Tera** - Template engine (Jinja2-compatible) for agent files
- **Claude API** - Anthropic's language models
- **OpenAI API** - GPT models
- **Gemini API** - Google's language models
- **Ollama** - Local LLM runtime
**Infrastructure:**
- **Nickel contracts** - Type-safe IaC validation
- **AWS/GCP/Hetzner/UpCloud APIs** - Multi-cloud provisioning
## Commands at a Glance
```bash
@ -288,7 +444,7 @@ just distro::package-release # Prepare release
- **cargo-watch** - For hot-reload during development
- **cargo-cross** - For cross-compilation to other platforms
See [docs/INSTALLATION.md](docs/INSTALLATION.md) for setup.
See [docs/installation.md](docs/installation.md) for setup.
## License & Compliance
@ -311,4 +467,4 @@ Contributions welcome! See documentation for setup and guidelines.
---
**Ready to get started?** → [docs/INSTALLATION.md](docs/INSTALLATION.md)
**Ready to get started?** → [docs/installation.md](docs/installation.md)

12240
SBOM.cyclonedx.json
View File

File diff suppressed because it is too large Load Diff

12057
SBOM.spdx.json
View File

File diff suppressed because it is too large Load Diff

89
SECURITY.md Normal file
View File

@ -0,0 +1,89 @@
# Security Policy
## Supported Versions
| Version | Supported |
| ------- | ------------------ |
| 0.1.x | :white_check_mark: |
## Reporting a Vulnerability
**Please DO NOT report security vulnerabilities via public GitHub issues.**
### Private Reporting
Send vulnerability reports to: **jpl@jesusperez.com**
Include in your report:
- Description of the vulnerability
- Steps to reproduce
- Potential impact
- Suggested fix (if any)
### Response Timeline
- **Acknowledgment**: Within 48 hours
- **Initial assessment**: Within 1 week
- **Fix timeline**: Depends on severity (coordinated with reporter)
- **Public disclosure**: After fix is released (coordinated disclosure)
### Security Advisories
We use [GitHub Security Advisories](https://github.com/jesusperezlorenzo/typedialog/security/advisories) for:
- Private coordination on fixes
- CVE assignment
- Public disclosure after fixes
## Security Best Practices
### For Users
1. **Verify downloads**: Check SHA256 checksums
```bash
sha256sum -c SHA256SUMS
```
2. **Use latest version**: Security fixes are not backported
3. **Audit dependencies**: Run `just dev::audit` regularly
### For Contributors
1. **Input validation**: Validate all user input
2. **No secrets in code**: Use environment variables
3. **Dependency audits**: Check `cargo audit` before PRs
4. **SBOM compliance**: Ensure SBOM.*.json are updated
## Known Security Considerations
### Encryption Features
- TypeDialog uses industry-standard encryption (secretumvault)
- Configuration files may contain sensitive data - protect with file permissions
### Web Backend
- Production configs enable CSRF protection and rate limiting
- See `config/web/production.toml` for security settings
### AI Backend
- API keys stored in environment variables only
- No API keys in logs or error messages
## Dependency Security
We use:
- `cargo-audit` for known vulnerabilities
- `cargo-deny` for license/security policies
- Automated dependency updates via Renovate
## Security Scanning
CI pipeline includes:
- Dependency audit (`cargo audit`)
- License compliance (`cargo-deny`)
- SBOM verification (SPDX + CycloneDX)
## Contact
For security concerns: contact via repositories.
For general support: GitHub Issues

6
imgs/BRANDING.md → assets/BRANDING.md
View File

@ -247,13 +247,13 @@ Format: `typedialog_[component]_[variant].svg`
### Web - Header Logo
```html
<img src="/imgs/typedialog_logo_h.svg" alt="TypeDialog" width="240" height="64">
<img src="/assets/typedialog_logo_h.svg" alt="TypeDialog" width="240" height="64">
```
### App - Favicon
```html
<link rel="icon" href="/imgs/favicon.svg" type="image/svg+xml">
<link rel="icon" href="/imgs/favicon-32.png" type="image/png" sizes="32x32">
<link rel="icon" href="/assets/favicon.svg" type="image/svg+xml">
<link rel="icon" href="/assets/favicon-32.png" type="image/png" sizes="32x32">
```
### Email - Static Logo

14
imgs/README.md → assets/README.md
View File

@ -8,17 +8,17 @@ Official logo assets for **TypeDialog** — typed dialogs for inputs, forms and
```html
<!-- Favicon -->
<link rel="icon" href="/imgs/favicon.svg" type="image/svg+xml">
<link rel="icon" href="/imgs/favicon-32.png" type="image/png" sizes="32x32">
<link rel="icon" href="/assets/favicon.svg" type="image/svg+xml">
<link rel="icon" href="/assets/favicon-32.png" type="image/png" sizes="32x32">
<!-- Logo in header -->
<img src="/imgs/typedialog_logo_h.svg" alt="TypeDialog" width="240">
<img src="/assets/typedialog_logo_h.svg" alt="TypeDialog" width="240">
```
### For React/Vue
```jsx
import logo from '/imgs/typedialog_logo_h.svg';
import logo from '/assets/typedialog_logo_h.svg';
export default function Header() {
return <img src={logo} alt="TypeDialog" width={240} />;
@ -28,7 +28,7 @@ export default function Header() {
### For Markdown/Docs
```markdown
![TypeDialog](/imgs/typedialog_logo_h.svg)
![TypeDialog](/assets/typedialog_logo_h.svg)
```
---
@ -226,7 +226,7 @@ font-family: "Inter", -apple-system, BlinkMacSystemFont, sans-serif;
### Markdown
```markdown
# ![TypeDialog](/imgs/typedialog_logo_h.svg) Welcome
# ![TypeDialog](/assets/typedialog_logo_h.svg) Welcome
[Link text](/)
```
@ -234,7 +234,7 @@ font-family: "Inter", -apple-system, BlinkMacSystemFont, sans-serif;
### Rust / Markdown Docs
```markdown
![TypeDialog](imgs/typedialog_logo_h.svg)
![TypeDialog](assets/typedialog_logo_h.svg)
```
---

0
imgs/favicon.svg → assets/favicon.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 909 B

After

Width:  |  Height:  |  Size: 909 B

70
imgs/how-to-use.md → assets/how-to-use.md
View File

@ -48,12 +48,12 @@ Quick integration guide with code examples for different frameworks and contexts
<!DOCTYPE html>
<html>
<head>
<link rel="icon" href="imgs/favicon.svg" type="image/svg+xml">
<link rel="icon" href="assets/favicon.svg" type="image/svg+xml">
</head>
<body>
<!-- Hero section -->
<header class="hero">
<img src="imgs/typedialog_logo_h.svg" alt="TypeDialog" class="logo">
<img src="assets/typedialog_logo_h.svg" alt="TypeDialog" class="logo">
</header>
<style>
@ -70,7 +70,7 @@ Quick integration guide with code examples for different frameworks and contexts
### React
```jsx
import logo from 'imgs/typedialog_logo_h.svg';
import logo from './typedialog_logo_h.svg';
export default function Header() {
return (
@ -92,7 +92,7 @@ export default function Header() {
<template>
<header class="hero">
<img
src="@/assets/imgs/typedialog_logo_h.svg"
src="@/assets/assets/typedialog_logo_h.svg"
alt="TypeDialog"
class="logo"
:width="240"
@ -102,7 +102,7 @@ export default function Header() {
<script setup>
// If using as component:
import TypeDialogLogo from '@/assets/imgs/typedialog_logo_h.svg';
import TypeDialogLogo from '@/assets/assets/typedialog_logo_h.svg';
</script>
<style scoped>
@ -117,7 +117,7 @@ import TypeDialogLogo from '@/assets/imgs/typedialog_logo_h.svg';
```svelte
<script>
import logo from '../imgs/typedialog_logo_h.svg';
import logo from '../assets/typedialog_logo_h.svg';
</script>
<header class="hero">
@ -137,7 +137,7 @@ import TypeDialogLogo from '@/assets/imgs/typedialog_logo_h.svg';
```typescript
// In template
<img
src="assets/imgs/typedialog_logo_h.svg"
src="assets/assets/typedialog_logo_h.svg"
alt="TypeDialog"
class="logo"
width="240"
@ -157,19 +157,19 @@ import TypeDialogLogo from '@/assets/imgs/typedialog_logo_h.svg';
### Simple Image
```markdown
![TypeDialog](./imgs/typedialog_logo_h.svg)
![TypeDialog](./assets/typedialog_logo_h.svg)
```
### With Link
```markdown
[![TypeDialog](./imgs/typedialog_logo_h.svg)](https://yoursite.com)
[![TypeDialog](./assets/typedialog_logo_h.svg)](https://yoursite.com)
```
### mdBook / GitHub Docs
```markdown
# ![TypeDialog](../imgs/typedialog_logo_h.svg) Welcome to TypeDialog
# ![TypeDialog](../assets/typedialog_logo_h.svg) Welcome to TypeDialog
Content here...
```
@ -179,7 +179,7 @@ Content here...
```markdown
# TypeDialog
![TypeDialog](imgs/typedialog_logo_h.svg)
![TypeDialog](assets/typedialog_logo_h.svg)
Typed dialogs for inputs, forms and schemas you can trust.
```
@ -191,11 +191,11 @@ Typed dialogs for inputs, forms and schemas you can trust.
### Favicon Set
```html
<link rel="icon" href="/imgs/favicon.svg" type="image/svg+xml">
<link rel="icon" href="/imgs/favicon-32.png" type="image/png" sizes="32x32">
<link rel="icon" href="/imgs/favicon-16.png" type="image/png" sizes="16x16">
<link rel="apple-touch-icon" href="/imgs/favicon-64.png">
<link rel="icon" href="/imgs/favicon.ico" sizes="16x16 32x32 64x64">
<link rel="icon" href="/assets/favicon.svg" type="image/svg+xml">
<link rel="icon" href="/assets/favicon-32.png" type="image/png" sizes="32x32">
<link rel="icon" href="/assets/favicon-16.png" type="image/png" sizes="16x16">
<link rel="apple-touch-icon" href="/assets/favicon-64.png">
<link rel="icon" href="/assets/favicon.ico" sizes="16x16 32x32 64x64">
```
### Hero Section
@ -203,7 +203,7 @@ Typed dialogs for inputs, forms and schemas you can trust.
```html
<section class="hero">
<div class="hero-content">
<img src="imgs/typedialog_logo_h.svg" alt="TypeDialog" class="hero-logo">
<img src="assets/typedialog_logo_h.svg" alt="TypeDialog" class="hero-logo">
<h1>TypeDialog</h1>
<p>Typed dialogs for inputs, forms and schemas you can trust.</p>
</div>
@ -228,7 +228,7 @@ Typed dialogs for inputs, forms and schemas you can trust.
```html
<nav class="navbar">
<a href="/" class="nav-logo">
<img src="imgs/typedialog_icon_s.svg" alt="TypeDialog" width="32">
<img src="assets/typedialog_icon_s.svg" alt="TypeDialog" width="32">
<span>TypeDialog</span>
</a>
<!-- Nav links -->
@ -261,7 +261,7 @@ Typed dialogs for inputs, forms and schemas you can trust.
<tr>
<td style="text-align: center; padding: 20px;">
<img
src="https://yoursite.com/imgs/typedialog-logo.png"
src="https://yoursite.com/assets/typedialog-logo.png"
alt="TypeDialog"
width="240"
height="64"
@ -276,8 +276,8 @@ Typed dialogs for inputs, forms and schemas you can trust.
```html
<!-- Meta tags for social sharing -->
<meta property="og:image" content="https://yoursite.com/imgs/typedialog_logo_h_s.png">
<meta property="twitter:image" content="https://yoursite.com/imgs/typedialog_logo_h_s.png">
<meta property="og:image" content="https://yoursite.com/assets/typedialog_logo_h_s.png">
<meta property="twitter:image" content="https://yoursite.com/assets/typedialog_logo_h_s.png">
<meta property="og:image:alt" content="TypeDialog Logo">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
@ -321,11 +321,11 @@ Typed dialogs for inputs, forms and schemas you can trust.
```css
:root {
--logo-url: url('imgs/typedialog_logo_h.svg');
--logo-url: url('./typedialog_logo_h.svg');
}
body.dark-mode {
--logo-url: url('imgs/typedialog_logo_h.svg');
--logo-url: url('./typedialog_logo_h.svg');
/* Logo works on both light and dark */
}
@ -340,17 +340,17 @@ body.dark-mode {
```html
<!-- SVG works on both light/dark backgrounds -->
<img src="imgs/typedialog_logo_h.svg" alt="TypeDialog">
<img src="assets/typedialog_logo_h.svg" alt="TypeDialog">
<!-- If needing different versions: -->
<img
src="imgs/typedialog_logo_h.svg"
src="assets/typedialog_logo_h.svg"
alt="TypeDialog"
class="logo-light"
style="display: block;"
/>
<img
src="imgs/typedialog_logo_h_bn.svg"
src="assets/typedialog_logo_h_bn.svg"
alt="TypeDialog"
class="logo-dark"
style="display: none;"
@ -372,18 +372,18 @@ body.dark-mode {
```html
<!-- Use smallest necessary size -->
<img src="imgs/typedialog_icon_s.svg" alt="TypeDialog" width="32">
<img src="assets/typedialog_icon_s.svg" alt="TypeDialog" width="32">
<!-- Avoid huge SVGs if PNG export available -->
<img src="imgs/typedialog_logo_h.png" alt="TypeDialog" width="240">
<img src="assets/typedialog_logo_h.png" alt="TypeDialog" width="240">
```
### CSS Loading
```css
/* Avoid multiple requests -->
.logo-light { background-image: url('imgs/typedialog_logo_h.svg'); }
.logo-dark { background-image: url('imgs/typedialog_logo_h_bn.svg'); }
.logo-light { background-image: url('./typedialog_logo_h.svg'); }
.logo-dark { background-image: url('./typedialog_logo_h_bn.svg'); }
/* Use data URIs for very small files */
.logo { background-image: url('data:image/svg+xml;...'); }
@ -394,7 +394,7 @@ body.dark-mode {
```html
<!-- SVGs are cacheable -->
<img
src="imgs/typedialog_logo_h.svg?v=1.0"
src="assets/typedialog_logo_h.svg?v=1.0"
alt="TypeDialog"
/>
@ -409,11 +409,11 @@ body.dark-mode {
```html
<!-- Always include meaningful alt text -->
<img src="imgs/typedialog_logo_h.svg" alt="TypeDialog">
<img src="assets/typedialog_logo_h.svg" alt="TypeDialog">
<!-- In links, alt is sometimes in parent -->
<a href="/">
<img src="imgs/typedialog_icon.svg" alt="Home">
<img src="assets/typedialog_icon.svg" alt="Home">
</a>
```
@ -422,7 +422,7 @@ body.dark-mode {
```html
<!-- For complex contexts -->
<img
src="imgs/typedialog_logo_h.svg"
src="assets/typedialog_logo_h.svg"
alt="TypeDialog"
aria-label="TypeDialog - Typed dialogs for inputs, forms and schemas you can trust"
/>
@ -434,7 +434,7 @@ body.dark-mode {
/* Respect user's motion preferences */
@media (prefers-reduced-motion: reduce) {
/* Option 1: Use static version */
img.logo { content: url('imgs/typedialog_logo_h_s.svg'); }
img.logo { content: url('./typedialog_logo_h_s.svg'); }
/* Option 2: Disable animations */
.logo * { animation: none !important; }

2
imgs/index.html → assets/index.html
View File

@ -563,7 +563,7 @@
</section>
<footer>
<p>© 2025 TypeDialog. Typed dialogs for inputs, forms and schemas you can trust.</p>
<p>© 2025 <b>TypeDialog</b> Typed dialogs for inputs, forms and schemas you can trust.</p>
<p style="margin-top: 10px; font-size: 0.9rem;">Made with <span style="color: var(--td-accent);">❤️</span> • Built in Rust</p>
</footer>
</div>

2
imgs/typedialog_ascii.txt → assets/typedialog_ascii.txt
View File

@ -3,6 +3,6 @@
╹ ╹ ╹ ┗━╸╺┻┛╹╹ ╹┗━╸┗━┛┗━┛
╔══════════════════════════════════╗
║ ▲ Typed Dialogs you can tRust. ║
║ ■ Inputs, Forms and Schemas. ║
║ ■ Inputs,Forms and Schemas + AI ║
║ typedialog.dev ║
╚══════════════════════════════════╝

0
imgs/typedialog_icon.svg → assets/typedialog_icon.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.1 KiB

After

Width:  |  Height:  |  Size: 1.1 KiB

0
imgs/typedialog_icon_bn.svg → assets/typedialog_icon_bn.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 891 B

After

Width:  |  Height:  |  Size: 891 B

0
imgs/typedialog_icon_s.svg → assets/typedialog_icon_s.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 909 B

After

Width:  |  Height:  |  Size: 909 B

0
imgs/typedialog_logo.svg → assets/typedialog_logo.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.6 KiB

After

Width:  |  Height:  |  Size: 1.6 KiB

0
imgs/typedialog_logo_bn.svg → assets/typedialog_logo_bn.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.3 KiB

After

Width:  |  Height:  |  Size: 1.3 KiB

0
imgs/typedialog_logo_h.svg → assets/typedialog_logo_h.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.5 KiB

After

Width:  |  Height:  |  Size: 1.5 KiB

0
imgs/typedialog_logo_h_bn.svg → assets/typedialog_logo_h_bn.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.2 KiB

After

Width:  |  Height:  |  Size: 1.2 KiB

0
imgs/typedialog_logo_h_s.svg → assets/typedialog_logo_h_s.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.2 KiB

After

Width:  |  Height:  |  Size: 1.2 KiB

0
imgs/typedialog_logo_s.svg → assets/typedialog_logo_s.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.2 KiB

After

Width:  |  Height:  |  Size: 1.2 KiB

0
imgs/typedialog_logo_specs.html → assets/typedialog_logo_specs.html
View File

0
imgs/typedialog_text.svg → assets/typedialog_text.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 614 B

After

Width:  |  Height:  |  Size: 614 B

0
imgs/typedialog_text_bn.svg → assets/typedialog_text_bn.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 443 B

After

Width:  |  Height:  |  Size: 443 B

0
imgs/typedialog_text_s.svg → assets/typedialog_text_s.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 385 B

After

Width:  |  Height:  |  Size: 385 B

439
docs/BUILD.md
View File

@ -1,439 +0,0 @@
<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 using [`cargo-sbom`](https://crates.io/crates/cargo-sbom).
### Regenerate SBOMs
When dependencies change (new crates, version updates, Cargo.lock changes):
```bash
just distro::generate-sbom
```
This regenerates:
- **SBOM.spdx.json** - SPDX 2.3 standard format (ISO/IEC 5962:2021)
- **SBOM.cyclonedx.json** - CycloneDX 1.4 format (ECMA standard)
### 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
**SBOM.spdx.json** (~350-400 KB)
- SPDX 2.3 format (ISO/IEC 5962:2021)
- Complete component inventory with unique identifiers
- Compatible with SPDX validators, GitHub Dependabot, and osv-scanner
- Generated by [cargo-sbom](https://crates.io/crates/cargo-sbom)
**SBOM.cyclonedx.json** (~280-320 KB)
- CycloneDX 1.4 format (ECMA standard)
- Complete component inventory with Package URLs (pURL)
- Compatible with vulnerability scanners and SCA tools (Dependabot, Snyk)
- Generated by [cargo-sbom](https://crates.io/crates/cargo-sbom)
### 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.

154
docs/README.md
View File

@ -1,5 +1,5 @@
<div align="center">
<img src="../imgs/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
<img src="../assets/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
</div>
# TypeDialog Documentation
@ -8,25 +8,31 @@ Complete documentation for using, building, and deploying TypeDialog.
## Getting Started
1. **[INSTALLATION.md](INSTALLATION.md)** - Prerequisites and setup
1. **[installation.md](installation.md)** - Prerequisites and setup
- System requirements
- Dependency installation
- Verification
2. **[DEVELOPMENT.md](DEVELOPMENT.md)** - Local development
2. **[development.md](development.md)** - Local development
- Using `just` for tasks
- Common workflows
- Examples and testing
3. **[pre-commit-setup.md](pre-commit-setup.md)** - Automated linting hooks
- Pre-commit hook installation
- Automatic code quality checks
- Hook configuration and usage
## Building & Distribution
3. **[BUILD.md](BUILD.md)** - Building and packaging
1. **[build.md](build.md)** - Building and packaging
- Critical dependencies (prov-ecosystem, secretumvault, just, Nickel)
- Single-platform builds
- Cross-compilation setup
- Distribution package creation
- Docker builds
4. **[RELEASE.md](RELEASE.md)** - Release workflow
2. **[release.md](release.md)** - Release workflow
- Preparing releases
- GitHub releases
- Installation verification
@ -34,13 +40,13 @@ Complete documentation for using, building, and deploying TypeDialog.
## Configuration
5. **[CONFIGURATION.md](CONFIGURATION.md)** - Configuration guide
1. **[configuration.md](configuration.md)** - Configuration guide
- Backend-specific configs
- Environment settings (dev, prod)
- Custom configurations
- Best practices
6. **[FIELD_TYPES.md](FIELD_TYPES.md)** - Field types reference
2. **[field_types.md](field_types.md)** - Field types reference
- All supported field types
- RepeatingGroup arrays
- Conditional display
@ -49,39 +55,85 @@ Complete documentation for using, building, and deploying TypeDialog.
## Quick Links
### Installation & Setup
- [System Requirements](INSTALLATION.md#prerequisites)
- [Installing just](INSTALLATION.md#just-command-orchestration)
- [Installing Nickel CLI](INSTALLATION.md#nickel-cli--optional)
### Nickel Support
- [Nickel Guide](NICKEL.md) - Schema parsing, contracts, i18n, templates
- [System Requirements](installation.md#prerequisites)
- [Installing just](installation.md#just-command-orchestration)
- [Installing Nickel CLI](installation.md#nickel-cli--optional)
### Backend-Specific Guides
- [CLI Backend](cli/) - Command-line prompts and scripting
- [TUI Backend](tui/) - Terminal UI with keyboard/mouse support
- [Web Backend](web/) - HTTP server and browser forms
- [AI Backend](ai/) - RAG system and semantic search
- [Agent System](agent/) - Multi-provider LLM execution
### Feature Guides
- [Nickel Integration](nickel.md) - Schema parsing, contracts, i18n, templates
- [Encryption](encryption/) - Secure field handling
- [Provisioning Generator](prov-gen/) - Infrastructure as Code generation
- [Nickel Examples](../examples/07-nickel-generation/) - Complete examples
### Development
- [Quick Start Development](DEVELOPMENT.md#quick-start)
- [Using just Commands](DEVELOPMENT.md#just-commands)
- [Running Examples](DEVELOPMENT.md#examples)
- [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)
- [Critical Dependencies](build.md#critical-dependencies)
- [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)
- [Release Workflow](release.md#release-workflow)
- [GitHub Integration](release.md#github-release)
- [Distribution Structure](release.md#distribution-structure)
## Backend Documentation
Complete documentation for each TypeDialog backend:
| Backend | Path | Description |
| --------- | ------ | ------------- |
| **CLI** | [`cli/`](cli/) | Command-line interface (inquire-based prompts) |
| **TUI** | [`tui/`](tui/) | Terminal UI (Ratatui-powered interface) |
| **Web** | [`web/`](web/) | HTTP server (Axum-based browser forms) |
| **AI** | [`ai/`](ai/) | AI backend (RAG, embeddings, knowledge graphs) |
| **Agent** | [`agent/`](agent/) | AI agent execution (multi-provider LLM) |
## Feature Documentation
Documentation for TypeDialog features:
| Feature | Path | Description |
| --------- | ------ | ------------- |
| **Encryption** | [`encryption/`](encryption/) | Field encryption and secure data handling |
| **Provisioning** | [`prov-gen/`](prov-gen/) | Infrastructure as Code generation |
## Navigation
```
```text
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
├── installation.md ← Prerequisites & setup
├── development.md ← Local development
├── build.md ← Building & packaging
├── release.md ← Release workflow
├── configuration.md ← Configuration guide
├── field_types.md ← Field types reference
├── nickel.md ← Nickel schema support
├── cli/ ← CLI backend documentation
├── tui/ ← TUI backend documentation
├── web/ ← Web backend documentation
├── ai/ ← AI backend documentation
├── agent/ ← Agent system documentation
├── encryption/ ← Encryption documentation
└── prov-gen/ ← Provisioning generator docs
```
## Examples
@ -100,37 +152,55 @@ Complete working examples are in the `examples/` directory:
## Common Tasks
### I want to...
### I want to
**...get started quickly**
→ Read [INSTALLATION.md](INSTALLATION.md), then [DEVELOPMENT.md](DEVELOPMENT.md)
→ Read [installation.md](installation.md), then [development.md](development.md)
**...build from source**
→ Read [BUILD.md](BUILD.md#building-binaries)
→ Read [build.md](build.md#building-binaries)
**...release a new version**
→ Read [RELEASE.md](RELEASE.md#release-workflow)
→ Read [release.md](release.md#release-workflow)
**...configure backends**
→ Read [CONFIGURATION.md](CONFIGURATION.md)
→ Read [configuration.md](configuration.md)
**...set up development environment**
→ Read [DEVELOPMENT.md](DEVELOPMENT.md)
→ Read [development.md](development.md)
**...cross-compile for other platforms**
→ Read [BUILD.md](BUILD.md#cross-compilation)
→ Read [build.md](build.md#cross-compilation)
## Documentation Navigation
## Complete Documentation Structure
```
```text
docs/
├── README.md ← Overview (you are here)
├── INSTALLATION.md ← Setup & requirements
├── DEVELOPMENT.md ← Local development & `just` commands
├── BUILD.md ← Building & distribution
├── RELEASE.md ← Release workflow
├── CONFIGURATION.md ← Backend configuration
└── NICKEL.md ← Nickel schema support (NEW)
│
├── Getting Started
│ ├── installation.md ← Setup & requirements
│ ├── development.md ← Local development & `just` commands
│ └── configuration.md ← Backend configuration
│
├── Building & Distribution
│ ├── build.md ← Building & cross-compilation
│ └── release.md ← Release workflow
│
├── Reference
│ ├── field_types.md ← Field types reference
│ └── nickel.md ← Nickel schema support
│
├── Backends
│ ├── cli/ ← CLI backend
│ ├── tui/ ← TUI backend
│ ├── web/ ← Web backend
│ ├── ai/ ← AI backend
│ └── agent/ ← Agent system
│
└── Features
├── encryption/ ← Encryption & security
└── prov-gen/ ← Infrastructure provisioning
```
## Documentation Structure

320
docs/agent/README.md Normal file
View File

@ -0,0 +1,320 @@
# TypeDialog Agent Documentation
User guide for **TypeDialog Agent** - Execute AI agents defined as markdown files with multi-provider LLM support.
## What is TypeDialog Agent?
TypeDialog Agent (`typedialog-ag`) is a CLI tool that allows you to:
- Define AI agents as markdown files (`.agent.mdx`)
- Execute them with multiple LLM providers (Claude, OpenAI, Gemini, Ollama)
- Inject context from files, shell commands, and templates
- Validate outputs automatically
- Stream responses in real-time
## Quick Links
### Getting Started
- **[getting_started.md](getting_started.md)** - Installation and first agent
- **[AGENTS.md](AGENTS.md)** - How to write agent files
- **[CLI_REFERENCE.md](CLI_REFERENCE.md)** - Command reference
### LLM Providers
- **[llm_providers.md](llm_providers.md)** - Complete provider guide
- Claude (Anthropic)
- OpenAI (GPT)
- Google Gemini
- Ollama (local models)
### Advanced Topics
- **[TEMPLATES.md](TEMPLATES.md)** - Template system and variables
- **[VALIDATION.md](VALIDATION.md)** - Output validation rules
- **[BEST_PRACTICES.md](BEST_PRACTICES.md)** - Tips and patterns
## Quick Start
### 1. Install
```bash
# Build from source
cargo build --release --package typedialog-ag
# The binary will be at: target/release/typedialog-ag
```
### 2. Set API Key
```bash
# For Claude
export ANTHROPIC_API_KEY=sk-ant-...
# For OpenAI
export OPENAI_API_KEY=sk-...
# For Gemini
export GEMINI_API_KEY=...
# For Ollama (local - no API key needed)
ollama serve
```
### 3. Create Your First Agent
Create `hello.agent.mdx`:
```markdown
---
@agent {
role: friendly assistant,
llm: claude-3-5-haiku-20241022
}
@input name: String
---
Say hello to {{name}} in a warm and friendly way!
```
### 4. Run It
```bash
typedialog-ag hello.agent.mdx
# Prompts: name (String): Alice
# Output: Hello Alice! It's wonderful to meet you...
```
## Documentation Structure
```text
docs/agent/
├── README.md ← Overview (you are here)
├── getting_started.md ← Installation & first steps
├── AGENTS.md ← Writing agent files
├── llm_providers.md ← Provider setup & comparison
├── CLI_REFERENCE.md ← Command-line reference
├── TEMPLATES.md ← Template system guide
├── VALIDATION.md ← Output validation
└── BEST_PRACTICES.md ← Tips & patterns
```
## Features
### Multi-Provider Support
Choose the best LLM for your task:
- **Claude** - Best for code, analysis, reasoning
- **OpenAI** - Excellent code understanding, broad capabilities
- **Gemini** - Creative tasks, multi-modal
- **Ollama** - Privacy-first, local execution, no costs
### Context Injection
Import context from multiple sources:
```yaml
@import "./src/**/*.rs" as code # File imports
@shell "git status" as git_status # Shell commands
@import ".env" as environment # Configuration
```
### Template System
Powerful templating with LiquidJS:
```markdown
Hello {{name}}!
{{#if premium}}
Welcome to premium features!
{{else}}
Upgrade to unlock more!
{{/if}}
```
### Output Validation
Ensure quality automatically:
```yaml
@validate output {
must_contain: ["## Summary", "## Recommendations"],
format: markdown,
min_length: 500
}
```
### Real-time Streaming
See responses as they're generated with token-by-token streaming.
## Examples
### Code Review
```bash
typedialog-ag examples/12-agent-execution/code-review.agent.mdx
```
### Documentation Generation
```bash
typedialog-ag examples/12-agent-execution/documentation.agent.mdx
```
### Task Planning
```bash
typedialog-ag examples/12-agent-execution/task-planner.agent.mdx
```
### Local Privacy Analysis
```bash
# Runs entirely locally with Ollama
typedialog-ag examples/12-agent-execution/local-privacy.agent.mdx
```
See [examples/12-agent-execution/](../../examples/12-agent-execution/) for all examples.
## Use Cases
### Development
- Code reviews
- Refactoring assistance
- Documentation generation
- Bug analysis
- Architecture design
### Content Creation
- Blog posts
- Documentation
- Technical writing
- Creative content
### Business
- Task planning
- Process documentation
- Decision support
- Data analysis
### Privacy-Sensitive
- Local data analysis with Ollama
- Compliance review
- Sensitive document processing
## Learning Path
```text
1. getting_started.md
↓ Install and run first agent
2. AGENTS.md
↓ Learn agent file format
3. llm_providers.md
↓ Choose your provider
4. TEMPLATES.md
↓ Master template system
5. Examples & Demos
↓ See real-world usage
6. BEST_PRACTICES.md
↓ Optimize your agents
```
## Resources
### Examples & Demos
- [Examples](../../examples/12-agent-execution/README.md) - 8 practical use cases
- [Demos](../../demos/agent/README.md) - Provider comparison demos
- [Tests](../../tests/agent/README.md) - Validation tests
### Technical Documentation
- [LLM Integration](../../crates/typedialog-agent/typedialog-ag-core/LLM_INTEGRATION.md) - Complete technical guide
- [Core Examples](../../crates/typedialog-agent/typedialog-ag-core/examples/) - Rust API usage
- [Developer Docs](../../crates/typedialog-agent/README.md) - Architecture and APIs
### Main Project
- [TypeDialog README](../../README.md) - Project overview
- [Examples](../../examples/README.md) - All project examples
## Common Questions
### Which LLM provider should I use?
See [llm_providers.md](llm_providers.md#choosing-a-provider) for a detailed comparison.
**Quick guide:**
- **Quick tasks** → Claude Haiku
- **Code work** → Claude Sonnet or GPT-4o
- **Creative** → Gemini 2.0
- **Privacy** → Ollama (local)
### How much does it cost?
- **Claude** - Pay per token (see Anthropic pricing)
- **OpenAI** - Pay per token (see OpenAI pricing)
- **Gemini** - Free tier + pay per token
- **Ollama** - Free (runs locally)
See [llm_providers.md](llm_providers.md#cost-comparison) for details.
### Can I use it offline?
Yes. Use Ollama for completely offline operation:
```bash
ollama serve
ollama pull llama2
typedialog-ag my-agent.agent.mdx # Uses llama2 locally
```
### Is my data private?
- **Cloud providers** (Claude, OpenAI, Gemini) - Data sent to their APIs
- **Ollama** - Completely private, runs on your machine
See [BEST_PRACTICES.md](BEST_PRACTICES.md#privacy-considerations) for guidance.
## Getting Help
### Documentation
1. Read [getting_started.md](getting_started.md)
2. Check [CLI_REFERENCE.md](CLI_REFERENCE.md)
3. Browse [examples](../../examples/12-agent-execution/)
### Troubleshooting
See [getting_started.md#troubleshooting](getting_started.md#troubleshooting)
### Contributing
See [Developer Documentation](../../crates/typedialog-agent/README.md)
## What's Next?
Ready to get started? → [getting_started.md](getting_started.md)
Want to understand agent files? → [AGENTS.md](AGENTS.md)
Need to choose a provider? → [llm_providers.md](llm_providers.md)
---
**Version**: 0.1.0
**Last Updated**: December 2024

592
docs/agent/getting_started.md Normal file
View File

@ -0,0 +1,592 @@
# Getting Started with TypeDialog Agent
Complete guide to installing and using TypeDialog Agent for the first time.
## Installation
### Prerequisites
- **Rust** 1.75 or later
- **Cargo** (comes with Rust)
- At least one LLM provider:
- API key for Claude, OpenAI, or Gemini
- OR Ollama installed for local models
### Install Rust
If you don't have Rust installed:
```bash
# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Verify installation
rustc --version
cargo --version
```
### Build TypeDialog Agent
```bash
# Clone the repository (if not already)
cd /path/to/typedialog
# Build the CLI
cargo build --release --package typedialog-ag
# The binary will be at:
# target/release/typedialog-ag
```
### Add to PATH (Optional)
```bash
# Option 1: Copy to a directory in PATH
sudo cp target/release/typedialog-ag /usr/local/bin/
# Option 2: Create alias
echo 'alias typedialog-ag="/path/to/typedialog/target/release/typedialog-ag"' >> ~/.bashrc
source ~/.bashrc
# Verify
typedialog-ag --help
```
## Set Up an LLM Provider
Choose at least one provider to get started:
### Option 1: Claude (Anthropic) - Recommended
```bash
# Sign up at: https://console.anthropic.com
# Get your API key
export ANTHROPIC_API_KEY=sk-ant-...
# Add to shell profile for persistence
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc
```
**Why Claude?**
- Excellent code understanding
- Strong reasoning capabilities
- Reliable and consistent
- Good balance of speed/quality/cost
### Option 2: OpenAI (GPT)
```bash
# Sign up at: https://platform.openai.com
# Get your API key
export OPENAI_API_KEY=sk-...
# Add to shell profile
echo 'export OPENAI_API_KEY=sk-...' >> ~/.bashrc
```
**Why OpenAI?**
- Excellent code generation
- Broad general knowledge
- Well-documented and reliable
### Option 3: Google Gemini
```bash
# Get API key from: https://aistudio.google.com/app/apikey
export GEMINI_API_KEY=...
# Or use GOOGLE_API_KEY
export GOOGLE_API_KEY=...
```
**Why Gemini?**
- Creative content generation
- Multi-modal capabilities
- Free tier available
### Option 4: Ollama (Local) - Privacy First
```bash
# Install Ollama
# Download from: https://ollama.ai
# Start Ollama server
ollama serve
# Pull a model (in another terminal)
ollama pull llama2
# Verify
curl http://localhost:11434/api/tags
```
**Why Ollama?**
- ✅ Complete privacy - runs locally
- ✅ No API costs
- ✅ Offline operation
- ✅ No data sent to cloud
## Your First Agent
### Step 1: Create an Agent File
Create `hello.agent.mdx`:
```markdown
---
@agent {
role: friendly assistant,
llm: claude-3-5-haiku-20241022
}
@input name: String
---
Say hello to {{name}} in a warm and friendly way!
Include a fun fact about their name if you know one.
```
### Step 2: Run the Agent
```bash
typedialog-ag hello.agent.mdx
```
You'll be prompted:
```text
name (String): Alice
```
Expected output:
```text
Hello Alice! It's wonderful to meet you! 🌟
Fun fact: The name Alice means "noble" and "truth" in Old German...
```
### Step 3: Understand What Happened
1. **Agent loaded** - Parsed the `.agent.mdx` file
2. **Provider selected** - Chose Claude Haiku based on `llm: claude-3-5-haiku-20241022`
3. **Input collected** - Prompted for the `name` variable
4. **Template rendered** - Replaced `{{name}}` with "Alice"
5. **LLM called** - Sent to Claude API
6. **Response streamed** - Displayed token-by-token
## Common Examples
### Code Review Agent
Create `review.agent.mdx`:
```markdown
---
@agent {
role: senior code reviewer,
llm: claude-3-5-sonnet-20241022,
temperature: 0.3
}
@input file_path: String
@import "{{file_path}}" as code_content
@validate output {
must_contain: ["## Security", "## Performance"],
format: markdown,
min_length: 300
}
---
# Code Review
## Code to Review
```text
{{code_content}}
```
## Task
Perform a thorough code review focusing on:
- Security vulnerabilities
- Performance issues
- Best practices
- Potential bugs
Provide specific, actionable recommendations.
```markdown
Run it:
```bash
typedialog-ag review.agent.mdx
# Prompts: file_path (String): ./src/main.rs
```
### Documentation Generator
Create `docs.agent.mdx`:
```markdown
---
@agent {
role: technical writer,
llm: gpt-4o,
max_tokens: 4096
}
@input module_path: String
@import "{{module_path}}/**/*.rs" as source_code
@validate output {
format: markdown,
min_length: 800
}
---
# Generate API Documentation
## Source Code
{{source_code}}
## Task
Create comprehensive API documentation including:
1. Overview of the module
2. Public API reference
3. Usage examples with code snippets
4. Common use cases
```
Run it:
```bash
typedialog-ag docs.agent.mdx
# Prompts: module_path (String): ./src/parser
```
### Local Privacy Analysis
Create `privacy.agent.mdx`:
```markdown
---
@agent {
role: privacy consultant,
llm: llama2
}
@input data_type: String
@input regulation: String
@import ".env" as env_config
---
# Privacy Analysis
You're analyzing: {{data_type}}
Regulation: {{regulation}}
Environment: {{env_config}}
Provide:
1. Privacy requirements for {{regulation}}
2. Recommended security measures
3. Data handling guidelines
4. Compliance checklist
**Note**: This runs 100% locally via Ollama - your data never leaves your machine!
```
Run it:
```bash
# Requires Ollama running
ollama serve
typedialog-ag privacy.agent.mdx
# Prompts: data_type (String): user emails
# Prompts: regulation (String): GDPR
```
## CLI Usage Patterns
### Interactive Mode (Default)
```bash
# Prompts for all inputs
typedialog-ag agent.agent.mdx
```
### Skip Prompts with --yes
```bash
# Uses default values (empty strings for missing inputs)
typedialog-ag agent.agent.mdx --yes
```
### Validate Without Execution
```bash
# Check syntax and type-check
typedialog-ag validate agent.agent.mdx
```
### Transpile to Nickel
```bash
# See the Nickel intermediate representation
typedialog-ag transpile agent.agent.mdx
```
### Show Help
```bash
typedialog-ag --help
typedialog-ag validate --help
```
## Next Steps
### Learn More
- **[AGENTS.md](AGENTS.md)** - Complete agent file format
- **[llm_providers.md](llm_providers.md)** - Provider comparison and setup
- **[TEMPLATES.md](TEMPLATES.md)** - Template system guide
- **[CLI_REFERENCE.md](CLI_REFERENCE.md)** - All CLI commands
### Try Examples
```bash
# Basic examples
typedialog-ag examples/12-agent-execution/basic-greeting.agent.mdx
# Advanced examples
typedialog-ag examples/12-agent-execution/code-review.agent.mdx
typedialog-ag examples/12-agent-execution/task-planner.agent.mdx
# See all examples
ls examples/12-agent-execution/
cat examples/12-agent-execution/README.md
```
### Run Demos
```bash
# Compare all providers
./demos/agent/run_demo.sh
# Or run provider comparison example
cargo run --example provider_comparison
```
## Troubleshooting
### API Key Not Set
**Error:**
```text
Error: ANTHROPIC_API_KEY environment variable not set
```
**Solution:**
```bash
export ANTHROPIC_API_KEY=sk-ant-...
# Or add to ~/.bashrc for persistence
```
### File Not Found
**Error:**
```text
Error: Failed to read agent file: hello.agent.mdx
```
**Solution:**
```bash
# Check file exists
ls hello.agent.mdx
# Use absolute path
typedialog-ag /full/path/to/hello.agent.mdx
```
### Import Pattern Not Found
**Error:**
```text
Error: No files matched pattern: ./src/**/*.rs
```
**Solution:**
```bash
# Check files exist
ls ./src/**/*.rs
# Use correct relative path
# Paths are relative to project root, not agent file
```
### Ollama Not Running
**Error:**
```text
Error: Failed to call Ollama API - is Ollama running?
```
**Solution:**
```bash
# Start Ollama server
ollama serve
# In another terminal, verify
curl http://localhost:11434/api/tags
```
### Quota Exceeded
**Error:**
```text
Error: 429 Too Many Requests - quota exceeded
```
**Solution:**
- Wait for quota reset
- Upgrade your API plan
- Use a different provider
- Use Ollama for local, free execution
### Validation Failed
**Error:**
```text
Error: Validation failed: missing required content
```
**Solution:**
```yaml
# Adjust validation rules in your agent
@validate output {
must_contain: ["Summary"], # Make less strict
min_length: 100 # Lower requirement
}
```
### Template Error
**Error:**
```text
Error: Failed to render template
```
**Solution:**
- Check variable names match: `@input name` and `{{name}}`
- Ensure proper liquid syntax: `{{#if var}}...{{/if}}`
- Verify nested templates are closed properly
## Performance Tips
### Choose the Right Model
- **Quick tasks** → Use Haiku (fast, cheap)
- **Complex reasoning** → Use Sonnet (balanced)
- **Critical design** → Use Opus (best quality)
- **Local/private** → Use Ollama (free, private)
### Limit Tokens
```yaml
@agent {
max_tokens: 500 # For short responses
}
```
### Adjust Temperature
```yaml
@agent {
temperature: 0.2 # Low for consistent, factual output (code)
temperature: 0.7 # Medium for balanced
temperature: 0.9 # High for creative content
}
```
### Use Validation
```yaml
@validate output {
min_length: 300,
max_length: 1000 # Prevent overly long responses
}
```
## Best Practices
### 1. Start Simple
Begin with basic agents, add complexity gradually.
### 2. Use Appropriate Models
Don't use Opus for simple tasks - it's slower and more expensive.
### 3. Validate Critical Outputs
Always validate when accuracy matters:
```yaml
@validate output {
must_contain: ["PASS", "FAIL"],
format: json
}
```
### 4. Use Ollama for Iteration
Develop and test with Ollama (free), then switch to cloud providers for production.
### 5. Keep Prompts Focused
Clear, specific prompts get better results than vague ones.
### 6. Use Context Wisely
Import only relevant context - too much can confuse the model.
## What's Next?
**Ready to dive deeper?**
1. Read [AGENTS.md](AGENTS.md) to master agent file format
2. Compare providers in [llm_providers.md](llm_providers.md)
3. Learn advanced templates in [TEMPLATES.md](TEMPLATES.md)
4. Explore [examples/12-agent-execution/](../../examples/12-agent-execution/)
**Want to contribute?**
See [Developer Documentation](../../crates/typedialog-agent/README.md)
---
**Questions?** Check [troubleshooting](#troubleshooting) or read the [FAQ](README.md#common-questions).

593
docs/agent/installation.md Normal file
View File

@ -0,0 +1,593 @@
# TypeDialog Agents - Installation Guide
Complete installation guide for TypeDialog Agents system.
## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Quick Install](#quick-install)
3. [Detailed Installation](#detailed-installation)
4. [Configuration](#configuration)
5. [Verification](#verification)
6. [Troubleshooting](#troubleshooting)
---
## Prerequisites
### System Requirements
**Minimum:**
- CPU: 2 cores
- RAM: 4 GB
- Disk: 1 GB free space
- OS: Linux, macOS, or Windows (WSL2)
**Recommended:**
- CPU: 4+ cores
- RAM: 8 GB
- Disk: 5 GB free space (for cache and builds)
- OS: Linux (Ubuntu 22.04+) or macOS (12.0+)
### Software Requirements
1. **Rust** (1.75.0 or later)
```bash
# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Verify installation
rustc --version
cargo --version
```
2. **Git**
```bash
# Ubuntu/Debian
sudo apt-get install git
# macOS
brew install git
# Verify
git --version
```
3. **Build Tools**
**Ubuntu/Debian:**
```bash
sudo apt-get update
sudo apt-get install build-essential pkg-config libssl-dev
```
**macOS:**
```bash
xcode-select --install
```
**Fedora/RHEL:**
```bash
sudo dnf groupinstall "Development Tools"
sudo dnf install openssl-devel
```
4. **Optional: Docker** (for containerized deployment)
```bash
# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# Verify
docker --version
docker-compose --version
```
---
## Quick Install
For experienced users who want to get started immediately:
```bash
# 1. Clone repository
git clone https://github.com/yourusername/typedialog.git
cd typedialog
# 2. Build release binary
cargo build --release --package typedialog-ag
# 3. Install binary (optional)
sudo cp target/release/typedialog-ag /usr/local/bin/
# 4. Set API key
export ANTHROPIC_API_KEY=sk-ant-your-key-here
# 5. Test installation
typedialog-ag validate agents/greeting.agent.mdx
```
Done! Skip to [Configuration](#configuration).
---
## Detailed Installation
### Step 1: Clone Repository
```bash
# Clone from GitHub
git clone https://github.com/yourusername/typedialog.git
cd typedialog
# Or clone via SSH
git clone git@github.com:yourusername/typedialog.git
cd typedialog
# Verify
ls -la
# Should see: Cargo.toml, agents/, crates/, etc.
```
### Step 2: Build from Source
#### Development Build (Debug)
Faster compilation, slower runtime:
```bash
cargo build --package typedialog-ag
# Binary location
./target/debug/typedialog-ag --version
```
#### Production Build (Release)
Optimized for performance:
```bash
cargo build --release --package typedialog-ag
# Binary location
./target/release/typedialog-ag --version
```
Build time: ~3-5 minutes (first time, with clean cache)
#### Build All Packages
```bash
# Build core library + CLI + server
cargo build --release --workspace
# Verify all binaries
ls -lh target/release/typedialog-ag*
```
### Step 3: Install Binary
#### System-Wide Installation (Recommended)
**Linux/macOS:**
```bash
# Copy to /usr/local/bin
sudo cp target/release/typedialog-ag /usr/local/bin/
# Verify
which typedialog-ag
typedialog-ag --version
```
**macOS (Homebrew style):**
```bash
# Copy to Homebrew cellar
sudo cp target/release/typedialog-ag /opt/homebrew/bin/
# Verify
which typedialog-ag
```
#### User-Only Installation
```bash
# Create local bin directory
mkdir -p ~/.local/bin
# Copy binary
cp target/release/typedialog-ag ~/.local/bin/
# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"
# Reload shell
source ~/.bashrc # or ~/.zshrc
# Verify
typedialog-ag --version
```
#### Development Mode (No Install)
Use directly from build directory:
```bash
# Create alias (add to ~/.bashrc or ~/.zshrc)
alias typedialog-ag='~/path/to/typedialog/target/release/typedialog-ag'
# Or use full path
~/typedialog/target/release/typedialog-ag --version
```
### Step 4: Install Example Agents
```bash
# Option 1: Use from repository
cd /path/to/typedialog
typedialog-ag validate agents/greeting.agent.mdx
# Option 2: Copy to standard location
mkdir -p ~/.typeagent/agents
cp -r agents/* ~/.typeagent/agents/
# Option 3: System-wide agents (requires sudo)
sudo mkdir -p /etc/typeagent/agents
sudo cp -r agents/* /etc/typeagent/agents/
```
---
## Configuration
### Environment Variables
Create `.env` file or export variables:
```bash
# Required: Anthropic API Key
export ANTHROPIC_API_KEY=sk-ant-your-key-here
# Optional: OpenAI (if using GPT models via Codex)
export OPENAI_API_KEY=sk-your-openai-key
# Optional: Custom cache directory
export TYPEAGENT_CACHE_DIR=$HOME/.typeagent/cache
# Optional: Logging level
export RUST_LOG=info # Options: error, warn, info, debug, trace
```
**Persistent Configuration:**
Add to `~/.bashrc` or `~/.zshrc`:
```bash
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.bashrc
source ~/.bashrc
```
### Configuration File
Create `~/.typeagent/config.yaml`:
```yaml
# Default configuration for TypeAgent CLI
# Cache settings
cache:
strategy: Both # Options: Memory, Disk, Both, None
max_entries: 1000
cache_dir: ~/.typeagent/cache
# Agent paths
agent_paths:
- ~/.typeagent/agents
- /etc/typeagent/agents
- ./agents
# HTTP Server defaults
server:
host: 127.0.0.1
port: 8765
cors: true
# LLM defaults
llm:
default_model: claude-3-5-sonnet-20241022
default_temperature: 0.7
default_max_tokens: 4096
```
### Permissions
Set correct permissions:
```bash
# Configuration directory
chmod 700 ~/.typeagent
chmod 600 ~/.typeagent/config.yaml
# Binary (if installed)
sudo chmod 755 /usr/local/bin/typedialog-ag
# Agents directory
chmod 755 ~/.typeagent/agents
chmod 644 ~/.typeagent/agents/*.agent.mdx
```
---
## Verification
### Test Installation
```bash
# 1. Check version
typedialog-ag --version
# 2. Validate example agent
typedialog-ag validate agents/greeting.agent.mdx
# 3. Transpile agent
typedialog-ag transpile agents/greeting.agent.mdx
# 4. Check cache
typedialog-ag cache stats
# 5. Run test suite (from repo)
./test-agents.sh
```
Expected output:
```
✓ MDX syntax valid
✓ Transpilation successful
✓ Type checking passed
✓ Evaluation successful
Agent Summary:
Role: friendly assistant
Model: claude-3-5-haiku-20241022
Max tokens: 4096
Temperature: 0.7
```
### Test HTTP Server
Terminal 1 - Start server:
```bash
typedialog-ag serve --port 8765
```
Terminal 2 - Test endpoints:
```bash
# Health check
curl http://localhost:8765/health
# Expected: OK
# Validate agent
curl -X POST http://localhost:8765/validate \
-H "Content-Type: application/json" \
-d '{"agent_file":"agents/greeting.agent.mdx"}'
# Expected: {"valid":true, ...}
```
### Test with API Key
```bash
# Set API key
export ANTHROPIC_API_KEY=sk-ant-your-key-here
# Execute agent (requires API key)
echo '{"name":"Test"}' | typedialog-ag agents/greeting.agent.mdx --inputs -
```
If successful, you'll see a response from Claude.
---
## Troubleshooting
### Build Errors
**Error: `linker 'cc' not found`**
```bash
# Ubuntu/Debian
sudo apt-get install build-essential
# macOS
xcode-select --install
```
**Error: `could not find openssl`**
```bash
# Ubuntu/Debian
sudo apt-get install libssl-dev pkg-config
# macOS
brew install openssl
export PKG_CONFIG_PATH="/opt/homebrew/opt/openssl/lib/pkgconfig"
```
**Error: Out of memory during build**
```bash
# Reduce parallel jobs
cargo build --release -j 2
```
### Runtime Errors
**Error: `command not found: typedialog-ag`**
```bash
# Check installation
which typedialog-ag
# Add to PATH
export PATH="$HOME/.local/bin:$PATH"
# Or reinstall
sudo cp target/release/typedialog-ag /usr/local/bin/
```
**Error: `ANTHROPIC_API_KEY not set`**
```bash
# Set environment variable
export ANTHROPIC_API_KEY=sk-ant-your-key-here
# Or add to ~/.bashrc
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.bashrc
source ~/.bashrc
```
**Error: `Permission denied`**
```bash
# Fix permissions
chmod +x /usr/local/bin/typedialog-ag
# Or run with full path
~/typedialog/target/release/typedialog-ag
```
**Error: `Address already in use (port 8765)`**
```bash
# Find process using port
lsof -i :8765
# Kill process
kill -9 <PID>
# Or use different port
typedialog-ag serve --port 9000
```
### Cache Issues
**Cache not working:**
```bash
# Clear cache
typedialog-ag cache clear
# Check cache stats
typedialog-ag cache stats
# Verify cache directory exists
ls -la ~/.typeagent/cache/
```
**Cache directory permissions:**
```bash
# Fix permissions
chmod 700 ~/.typeagent
chmod 700 ~/.typeagent/cache
```
### Agent Validation Errors
**Error: `Failed to parse MDX`**
- Check YAML frontmatter syntax
- Ensure `---` delimiters are correct
- Validate directive syntax (`@agent`, `@input`, etc.)
**Error: `Failed to transpile`**
- Verify agent directive has valid fields
- Check for typos in field names
- Ensure proper quoting in YAML
**Error: `Type checking failed`**
- Usually indicates Nickel evaluation issue
- Run with verbose logging: `RUST_LOG=debug typedialog-ag validate ...`
---
## Updating
### Update from Git
```bash
cd /path/to/typedialog
# Pull latest changes
git pull origin main
# Rebuild
cargo build --release --package typedialog-ag
# Reinstall
sudo cp target/release/typedialog-ag /usr/local/bin/
```
### Update Dependencies
```bash
# Update Cargo.lock
cargo update
# Rebuild
cargo build --release --package typedialog-ag
```
### Clean Rebuild
```bash
# Clean all build artifacts
cargo clean
# Rebuild from scratch
cargo build --release --package typedialog-ag
```
---
## Uninstallation
### Remove Binary
```bash
# System-wide installation
sudo rm /usr/local/bin/typedialog-ag
# User installation
rm ~/.local/bin/typedialog-ag
```
### Remove Configuration
```bash
# Remove config and cache
rm -rf ~/.typeagent
# Remove repository
rm -rf ~/path/to/typedialog
```
### Remove Environment Variables
Edit `~/.bashrc` or `~/.zshrc` and remove:
```bash
export ANTHROPIC_API_KEY=...
export PATH="$HOME/.local/bin:$PATH" # If added for typeagent
```
Then reload:
```bash
source ~/.bashrc # or ~/.zshrc
```
---
## Next Steps
After successful installation:
1. Read [quickstart.md](../quickstart.md) for usage examples
2. Read [deployment.md](../deployment.md) for production deployment
3. Explore example agents in `agents/` directory
4. Create your first custom agent
5. Start HTTP server for API access
## Support
- **Issues**: Report bugs at GitHub repository
- **Documentation**: See `docs/` directory
- **Examples**: See `agents/` directory
- **Tests**: Run `./test-agents.sh`

647
docs/agent/llm_providers.md Normal file
View File

@ -0,0 +1,647 @@
# LLM Providers Guide
Complete guide to using different LLM providers with TypeDialog Agent.
## Overview
TypeDialog Agent supports 4 LLM providers, each with unique strengths:
| Provider | Type | Best For | Privacy | Cost |
| ---------- | ------ | ---------- | --------- | ------ |
| **Claude** | Cloud | Code, reasoning, analysis | ❌ Cloud | $$ |
| **OpenAI** | Cloud | Code, general tasks | ❌ Cloud | $$ |
| **Gemini** | Cloud | Creative, multi-modal | ❌ Cloud | $ (free tier) |
| **Ollama** | Local | Privacy, offline, free | ✅ Local | Free |
## Choosing a Provider
### Quick Decision Tree
```text
Need privacy or offline? → Ollama
Budget constrained? → Gemini (free tier) or Ollama
Code review/refactoring? → Claude Sonnet or GPT-4o
Creative writing? → Gemini 2.0 Flash
Critical architecture? → Claude Opus
Quick tasks? → Claude Haiku
General purpose? → Claude Sonnet or GPT-4o-mini
```
## Claude (Anthropic)
### Claude overview
- **Best for**: Code analysis, reasoning, planning
- **Strengths**: Excellent code understanding, strong reasoning, reliable
- **Pricing**: Pay per token
- **Streaming**: ✅ With token usage
### Claude models available
| Model | Use Case | Speed | Cost | Context |
| ------- | ---------- | ------- | ------ | --------- |
| `claude-3-5-haiku-20241022` | Quick tasks, prototyping | ⚡⚡⚡ | $ | 200K |
| `claude-3-5-sonnet-20241022` | Balanced quality/speed | ⚡⚡ | $$ | 200K |
| `claude-opus-4-5-20251101` | Complex reasoning, critical | ⚡ | $$$ | 200K |
### Claude setup
```bash
# Get API key from: https://console.anthropic.com
export ANTHROPIC_API_KEY=sk-ant-...
# Add to shell profile
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc
```
### Claude usage in agents
```yaml
---
@agent {
role: code reviewer,
llm: claude-3-5-sonnet-20241022,
max_tokens: 4096,
temperature: 0.3
}
---
```
### Claude best practices
**Use Haiku for:**
- Simple queries
- Quick prototyping
- High-volume tasks
- Tight budgets
**Use Sonnet for:**
- Code review
- Documentation
- Task planning
- General development
**Use Opus for:**
- Architecture design
- Critical security reviews
- Complex problem-solving
- High-stakes decisions
### Claude cost optimization
```yaml
# Limit tokens for short tasks
@agent {
llm: claude-3-5-haiku-20241022,
max_tokens: 500 # Cheaper than default 4096
}
# Use lower temperature for factual tasks
@agent {
temperature: 0.2 # More consistent, potentially cheaper
}
```
---
## OpenAI (GPT)
### OpenAI overview
- **Best for**: Code generation, broad knowledge
- **Strengths**: Excellent code, well-documented, reliable
- **Pricing**: Pay per token
- **Streaming**: ✅ But NO token usage in stream
### OpenAI models available
| Model | Use Case | Speed | Cost | Context |
| ------- | ---------- | ------- | ------ | --------- |
| `gpt-4o-mini` | Fast code tasks | ⚡⚡⚡ | $ | 128K |
| `gpt-4o` | General purpose, code | ⚡⚡ | $$ | 128K |
| `o1` | Advanced reasoning | ⚡ | $$$ | 128K |
| `o3` | Complex problems | ⚡ | $$$$ | 128K |
### OpenAI setup
```bash
# Get API key from: https://platform.openai.com
export OPENAI_API_KEY=sk-...
# Add to shell profile
echo 'export OPENAI_API_KEY=sk-...' >> ~/.bashrc
```
### OpenAI usage in agents
```yaml
---
@agent {
role: refactoring assistant,
llm: gpt-4o-mini,
max_tokens: 2048,
temperature: 0.2
}
---
```
### OpenAI best practices
**Use GPT-4o-mini for:**
- Code refactoring
- Quick iterations
- High-volume tasks
- Development/testing
**Use GPT-4o for:**
- Production code generation
- Complex documentation
- Multi-step tasks
**Use o1/o3 for:**
- Mathematical reasoning
- Complex algorithm design
- Research tasks
### Important Limitation
⚠️ **OpenAI does NOT provide token usage in streaming mode**
```yaml
# You'll get streaming text but no token counts during stream
# Token usage only available in blocking mode
```
If you need token tracking, use Claude or Gemini instead.
---
## Google Gemini
### Gemini overview
- **Best for**: Creative content, multi-modal tasks
- **Strengths**: Creative, free tier, fast
- **Pricing**: Free tier + pay per token
- **Streaming**: ✅ With token usage
### Gemini models available
| Model | Use Case | Speed | Cost | Context |
| ------- | ---------- | ------- | ------ | --------- |
| `gemini-2.0-flash-exp` | Fast, general purpose | ⚡⚡⚡ | Free tier | 1M |
| `gemini-1.5-flash` | Lightweight tasks | ⚡⚡⚡ | $ | 1M |
| `gemini-1.5-pro` | Complex reasoning | ⚡⚡ | $$ | 2M |
| `gemini-3-pro` | Preview features | ⚡ | $$$ | TBD |
### Gemini setup
```bash
# Get API key from: https://aistudio.google.com/app/apikey
export GEMINI_API_KEY=...
# Or use GOOGLE_API_KEY
export GOOGLE_API_KEY=...
```
### Gemini usage in agents
```yaml
---
@agent {
role: creative writer,
llm: gemini-2.0-flash-exp,
max_tokens: 4096,
temperature: 0.9 # High for creativity
}
---
```
### Gemini best practices
**Use Gemini 2.0 Flash for:**
- Creative writing
- Content generation
- Prototyping (free tier)
- High-volume tasks
**Use Gemini 1.5 Pro for:**
- Long documents (2M context)
- Complex analysis
- Production workloads
### Free Tier
Gemini offers a generous free tier:
- **Rate limits**: 15 RPM, 1M TPM, 1500 RPD
- **Models**: gemini-2.0-flash-exp
- **Perfect for**: Development, testing, low-volume production
### Unique Features
```yaml
# Gemini uses "model" role instead of "assistant"
# TypeDialog handles this automatically
# Huge context windows (1M-2M tokens)
@agent {
llm: gemini-1.5-pro # 2M token context!
}
```
---
## Ollama (Local Models)
### Ollama overview
- **Best for**: Privacy, offline, cost-sensitive
- **Strengths**: Free, private, offline, no API limits
- **Pricing**: Free (compute costs only)
- **Streaming**: ✅ With token usage
### Ollama models available
Download any model from [ollama.ai/library](https://ollama.ai/library):
| Model | Size | Speed | Quality | Best For |
| ------- | ------ | ------- | --------- | ---------- |
| `llama2` | 7 B | ⚡⚡⚡ | Good | General tasks |
| `llama2:13b` | 13 B | ⚡⚡ | Better | Complex tasks |
| `mistral` | 7 B | ⚡⚡⚡ | Good | Fast inference |
| `codellama` | 7 B | ⚡⚡⚡ | Excellent | Code tasks |
| `mixtral` | 8x7 B | ⚡ | Excellent | Best quality |
| `phi` | 2.7 B | ⚡⚡⚡⚡ | Good | Low resource |
| `qwen` | Various | ⚡⚡ | Excellent | Multilingual |
### Ollama setup
```bash
# 1. Install Ollama
# Download from: https://ollama.ai
# 2. Start server
ollama serve
# 3. Pull a model
ollama pull llama2
# 4. Verify
curl http://localhost:11434/api/tags
# Optional: Custom URL
export OLLAMA_BASE_URL=http://localhost:11434
```
### Ollama usage in agents
```yaml
---
@agent {
role: privacy consultant,
llm: llama2,
max_tokens: 2048,
temperature: 0.7
}
---
```
### Ollama best practices
**Use Ollama when:**
- Working with sensitive data
- Need offline operation
- Want zero API costs
- Developing/testing frequently
- Have privacy requirements
**Model Selection:**
```bash
# Fastest (low resource)
ollama pull phi
# Balanced (recommended)
ollama pull llama2
# Best quality (requires more RAM)
ollama pull mixtral
# Code-specific
ollama pull codellama
```
### Performance Tips
```yaml
# Use smaller max_tokens for faster responses
@agent {
llm: llama2,
max_tokens: 1024 # Faster than 4096
}
# Lower temperature for more deterministic output
@agent {
temperature: 0.2 # Faster inference
}
```
### Privacy Advantages
```yaml
---
@agent {
role: data analyst,
llm: llama2 # Runs 100% locally
}
@import ".env" as secrets # Safe - never leaves your machine
@import "users.csv" as user_data # Safe - processed locally
---
Analyze {{user_data}} for GDPR compliance.
Include any secrets from {{secrets}} in analysis.
**This data NEVER leaves your computer!**
```
### Limitations
- ❌ Quality lower than GPT-4/Claude Opus (but improving!)
- ❌ Requires local compute resources (RAM, CPU/GPU)
- ❌ Slower inference than cloud APIs
- ✅ But: Free, private, offline.
---
## Provider Comparison
### Feature Matrix
| Feature | Claude | OpenAI | Gemini | Ollama |
| --------- | -------- | -------- | -------- | -------- |
| **Streaming** | ✅ SSE | ✅ SSE | ✅ JSON | ✅ JSON |
| **Usage in stream** | ✅ | ❌ | ✅ | ✅ |
| **Offline** | ❌ | ❌ | ❌ | ✅ |
| **Free tier** | ❌ | ❌ | ✅ | ✅ |
| **Privacy** | Cloud | Cloud | Cloud | Local |
| **Max context** | 200K | 128K | 2M | Varies |
| **Code quality** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
| **Creative** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| **Speed** | Fast | Fast | Very Fast | Varies |
### Cost Comparison
**Approximate costs (as of Dec 2024):**
| Provider | Model | Input | Output | 1M tokens |
| ---------- | ------- | -------- | -------- | ----------- |
| Claude | Haiku | $0.25/M | $1.25/M | ~$1.50 |
| Claude | Sonnet | $3/M | $15/M | ~$18 |
| Claude | Opus | $15/M | $75/M | ~$90 |
| OpenAI | GPT-4o-mini | $0.15/M | $0.60/M | ~$0.75 |
| OpenAI | GPT-4o | $2.50/M | $10/M | ~$12.50 |
| Gemini | 2.0 Flash | Free tier | Free tier | Free |
| Gemini | 1.5 Pro | $1.25/M | $5/M | ~$6.25 |
| **Ollama** | **Any model** | **$0** | **$0** | **$0** |
*Note: Prices change - check provider websites for current rates*
### Quality Comparison
**Code Tasks:**
1. Claude Opus / GPT-4o (tie)
2. Claude Sonnet
3. GPT-4o-mini / CodeLlama (Ollama)
4. Claude Haiku
5. Gemini
**Creative Tasks:**
1. Gemini 1.5 Pro
2. Claude Opus
3. GPT-4o
4. Gemini 2.0 Flash
5. Claude Sonnet
**Reasoning:**
1. Claude Opus
2. GPT-4o / o1
3. Claude Sonnet
4. Gemini 1.5 Pro
5. Mixtral (Ollama)
**Speed:**
1. Gemini 2.0 Flash
2. Claude Haiku
3. GPT-4o-mini
4. Ollama (depends on hardware)
5. Claude Opus
---
## Multi-Provider Strategies
### Development → Production
```yaml
# Development: Use Ollama (free, fast iteration)
@agent {
llm: llama2
}
# Testing: Use Gemini free tier
@agent {
llm: gemini-2.0-flash-exp
}
# Production: Use Claude Sonnet
@agent {
llm: claude-3-5-sonnet-20241022
}
```
### Privacy Tiers
```yaml
# Public data: Any cloud provider
@agent {
llm: gemini-2.0-flash-exp
}
# Sensitive data: Use Ollama
@agent {
llm: llama2 # Stays on your machine
}
```
### Ollama cost optimization
```yaml
# High volume, simple: Haiku or Gemini
@agent {
llm: claude-3-5-haiku-20241022
}
# Medium volume, quality: Sonnet or GPT-4o-mini
@agent {
llm: claude-3-5-sonnet-20241022
}
# Critical, low volume: Opus
@agent {
llm: claude-opus-4-5-20251101
}
```
---
## Testing Providers
### Compare All Providers
```bash
# Run provider comparison demo
cargo run --example provider_comparison
# Or use demo script
./demos/agent/run_demo.sh
```
### Test Individual Provider
```bash
# Claude
typedialog-ag demos/agent/demo-claude.agent.mdx
# OpenAI
typedialog-ag demos/agent/demo-openai.agent.mdx
# Gemini
typedialog-ag demos/agent/demo-gemini.agent.mdx
# Ollama (requires ollama serve)
typedialog-ag demos/agent/demo-ollama.agent.mdx
```
---
## Troubleshooting
### API Key Not Working
```bash
# Verify key is set
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY
echo $GEMINI_API_KEY
# Test with curl
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "content-type: application/json" \
-d '{"model":"claude-3-5-haiku-20241022","messages":[{"role":"user","content":"Hello"}],"max_tokens":10}'
```
### Quota Exceeded
**Error:** `429 Too Many Requests`
**Solutions:**
1. Wait for quota reset
2. Upgrade API plan
3. Switch to different provider
4. Use Ollama (no quotas)
### Ollama Connection Failed
**Error:** `Failed to call Ollama API`
**Solutions:**
```bash
# Check server running
curl http://localhost:11434/api/tags
# Start server
ollama serve
# Check custom URL
echo $OLLAMA_BASE_URL
```
### Model Not Found
**Error:** `Unknown model provider`
**Solution:**
```yaml
# Check model name spelling
llm: claude-3-5-haiku-20241022 # Correct
llm: claude-haiku # Wrong
# For Ollama, pull model first
# ollama pull llama2
```
---
## Best Practices
### 1. Match Provider to Task
Don't use Opus for simple greetings. Don't use Ollama for critical architecture.
### 2. Use Free Tiers for Development
Develop with Ollama or Gemini free tier, deploy with paid providers.
### 3. Monitor Costs
```bash
# Track token usage
# All providers (except OpenAI streaming) report usage
```
### 4. Respect Privacy
Use Ollama for sensitive data, cloud providers for public data.
### 5. Test Before Production
Always test agents with actual providers before deploying.
---
## What's Next?
**Ready to write agents?** → [AGENTS.md](AGENTS.md)
**Want advanced templates?** → [TEMPLATES.md](TEMPLATES.md)
**See practical examples?** → [Examples](../../examples/12-agent-execution/)
---
**For technical details:** See [LLM_INTEGRATION.md](../../crates/typedialog-agent/typedialog-ag-core/LLM_INTEGRATION.md)

381
docs/ai/README.md Normal file
View File

@ -0,0 +1,381 @@
# TypeDialog AI Backend
AI-powered backend with RAG (Retrieval-Augmented Generation), knowledge graphs, and semantic search.
## Overview
The AI backend (`typedialog-ai`) provides AI/ML capabilities for TypeDialog forms including semantic search, document retrieval, knowledge graph integration, and embeddings-based similarity.
## Features
- **RAG System**: Retrieval-Augmented Generation for context-aware responses
- **Knowledge Graphs**: Structured knowledge representation
- **Vector Embeddings**: Semantic similarity and search
- **Batch Operations**: Efficient processing of large document sets
- **Multi-Model Support**: Pluggable embedding models
- **REST API**: HTTP endpoints for AI operations
- **WebSocket**: Real-time streaming responses
## Quick Start
### Installation
```bash
cargo build --release -p typedialog-ai --features ai_backend
sudo cp target/release/typedialog-ai /usr/local/bin/
# Or use just
just build::ai
```
### Basic Usage
```bash
# Start AI backend server
typedialog-ai --config config/ai/default.toml
# With custom port
typedialog-ai --port 8000
# In library mode (no server)
cargo run --example ai_rag
```
## Architecture
### Components
```text
┌─────────────────────────────────────────┐
│ TypeDialog AI Backend │
├─────────────────────────────────────────┤
│ REST API + WebSocket │
├─────────────────────────────────────────┤
│ RAG Engine │
│ ├─ Document Store │
│ ├─ Vector Database │
│ └─ Retrieval System │
├─────────────────────────────────────────┤
│ Knowledge Graph │
│ ├─ Entity Extraction │
│ ├─ Relationship Mapping │
│ └─ Graph Queries │
├─────────────────────────────────────────┤
│ Embedding Engine │
│ ├─ Model Loading │
│ ├─ Batch Processing │
│ └─ Similarity Search │
└─────────────────────────────────────────┘
```
### RAG Pipeline
1. **Ingestion**: Add documents to vector store
2. **Embedding**: Generate embeddings with chosen model
3. **Indexing**: Store in vector database
4. **Retrieval**: Semantic search + keyword matching
5. **Generation**: Augment prompts with retrieved context
## Configuration
### AI Backend Config
```toml
[ai]
port = 8000
host = "0.0.0.0"
[ai.rag]
embedding_model = "sentence-transformers/all-MiniLM-L6-v2"
chunk_size = 512
overlap = 50
top_k = 5 # Number of results to retrieve
[ai.vector_store]
backend = "in_memory" # or "faiss", "milvus", "qdrant"
dimension = 384 # Match embedding model dimension
[ai.knowledge_graph]
enabled = true
backend = "neo4j" # or "in_memory"
uri = "bolt://localhost:7687"
```
### Embedding Models
Supported embedding models:
| Model | Dimension | Performance | Use Case |
| ------- | ----------- | ------------- | ---------- |
| `all-MiniLM-L6-v2` | 384 | Fast, lightweight | General purpose |
| `all-mpnet-base-v2` | 768 | Balanced | High quality |
| `paraphrase-multilingual-MiniLM-L12-v2` | 384 | Fast | Multilingual |
| `text-embedding-ada-002` | 1536 | API-based | OpenAI API |
## API Endpoints
### RAG Endpoints
```bash
# Add document
POST /api/rag/documents
{
"content": "Document text...",
"metadata": {"source": "manual"}
}
# Search documents
POST /api/rag/search
{
"query": "How to install?",
"top_k": 5
}
# Generate with RAG
POST /api/rag/generate
{
"query": "Explain installation",
"context_sources": ["manual", "faq"]
}
```
### Knowledge Graph Endpoints
```bash
# Add entity
POST /api/kg/entities
{
"name": "TypeDialog",
"type": "Software",
"properties": {"version": "1.0.0"}
}
# Query relationships
GET /api/kg/query?entity=TypeDialog&relation=depends_on
```
### Embedding Endpoints
```bash
# Generate embeddings
POST /api/embeddings
{
"texts": ["text1", "text2"],
"model": "all-MiniLM-L6-v2"
}
# Similarity search
POST /api/similarity
{
"query": "installation guide",
"candidates": ["doc1", "doc2", "doc3"]
}
```
## Usage Examples
### RAG System
```rust
use typedialog_ai::rag::{RagEngine, Document};
// Initialize RAG engine
let mut rag = RagEngine::new(config)?;
// Add documents
rag.add_document(Document {
content: "TypeDialog is a form library...".to_string(),
metadata: HashMap::from([("source", "docs")]),
})?;
// Semantic search
let results = rag.search("What is TypeDialog?", 5)?;
// Generate with context
let response = rag.generate("Explain TypeDialog", &results)?;
```
### Knowledge Graph
```rust
use typedialog_ai::kg::{KnowledgeGraph, Entity, Relationship};
// Initialize knowledge graph
let mut kg = KnowledgeGraph::new(config)?;
// Add entities
kg.add_entity(Entity {
name: "TypeDialog".to_string(),
entity_type: "Software".to_string(),
properties: HashMap::new(),
})?;
// Add relationships
kg.add_relationship(Relationship {
from: "TypeDialog".to_string(),
to: "Rust".to_string(),
relation_type: "written_in".to_string(),
})?;
// Query
let results = kg.query("TypeDialog", "depends_on")?;
```
### Embeddings
```rust
use typedialog_ai::embeddings::EmbeddingEngine;
// Initialize
let engine = EmbeddingEngine::new("all-MiniLM-L6-v2")?;
// Generate embeddings
let texts = vec!["Hello world", "Goodbye world"];
let embeddings = engine.encode(&texts)?;
// Similarity
let similarity = embeddings[0].cosine_similarity(&embeddings[1]);
```
## Use Cases
### 1. Semantic Document Search
Search documentation by meaning, not just keywords:
```bash
curl -X POST http://localhost:8000/api/rag/search \
-H "Content-Type: application/json" \
-d '{"query": "How to configure backends?", "top_k": 3}'
```
### 2. Context-Aware Help
Provide relevant help based on user context:
```bash
curl -X POST http://localhost:8000/api/rag/generate \
-H "Content-Type: application/json" \
-d '{"query": "I need help with forms", "user_context": {"backend": "web"}}'
```
### 3. Knowledge Graph Queries
Discover relationships between concepts:
```bash
curl http://localhost:8000/api/kg/query?entity=TypeDialog&relation=depends_on
```
### 4. Batch Document Processing
Process large document sets efficiently:
```rust
let documents = load_documents("./docs")?;
rag.add_documents_batch(&documents, 100)?; // Batch size: 100
```
## Performance
### Optimization Tips
1. **Batch Processing**: Use batch operations for multiple documents
2. **Model Selection**: Choose smaller models for faster inference
3. **Caching**: Enable embedding caching for repeated queries
4. **Vector Store**: Use persistent stores (FAISS, Milvus) for large datasets
### Benchmarks
| Operation | Throughput | Latency |
| ----------- | ----------- | --------- |
| Embedding (batch=100) | ~1000 texts/s | ~100 ms |
| Semantic search (10K docs) | ~50 queries/s | ~20 ms |
| Knowledge graph query | ~1000 queries/s | ~1 ms |
## Integration
### With Forms
Use AI backend to enhance forms:
```toml
[[fields]]
name = "documentation"
field_type = "Text"
ai_enabled = true
ai_endpoint = "http://localhost:8000/api/rag/search"
```
### With Web Backend
Integrate semantic search in web forms:
```javascript
async function searchDocs(query) {
const response = await fetch('http://localhost:8000/api/rag/search', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ query, top_k: 5 })
});
return await response.json();
}
```
## Examples
See [examples/10-ai-backend/](../../examples/10-ai-backend/) for:
- RAG system setup
- Knowledge graph integration
- Batch document processing
- Semantic search
- Performance optimization
## Related Documentation
- [Configuration](../configuration.md) - AI backend configuration
- [Examples](../../examples/10-ai-backend/) - Working examples
- [API Reference](../../crates/typedialog-ai/README.md) - Complete API docs
## Troubleshooting
### "Model not found"
Download embedding model:
```bash
python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"
```
### "Out of memory"
Use smaller batch size or lighter model:
```toml
[ai.rag]
embedding_model = "all-MiniLM-L6-v2" # 384-dim instead of 768
chunk_size = 256 # Smaller chunks
```
### "Slow search performance"
Enable vector index:
```toml
[ai.vector_store]
backend = "faiss" # Faster than in_memory
index_type = "IVF" # Approximate search
```
### "Connection refused"
Check AI backend is running:
```bash
curl http://localhost:8000/health
```
---
**Ready to start?** See [examples/10-ai-backend/](../../examples/10-ai-backend/)

873
docs/build.md Normal file
View File

@ -0,0 +1,873 @@
<div align="center">
<img src="../assets/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
## Critical Dependencies
TypeDialog requires several critical dependencies for building and running. These include both **internal dependencies** (git submodules or external projects) and **external tools**.
### Internal Dependencies
#### prov-ecosystem
**What:** Provisioning ecosystem library for infrastructure generation (used by `typedialog-prov-gen`)
**Location:** Expected as sibling directory or git submodule
**Installation:**
```bash
# Option 1: Clone as sibling directory (recommended)
cd /path/to/projects
git clone https://github.com/your-org/prov-ecosystem.git
git clone https://github.com/your-org/typedialog.git
# Option 2: Git submodule
cd typedialog
git submodule add https://github.com/your-org/prov-ecosystem.git deps/prov-ecosystem
git submodule update --init --recursive
```
**Path Configuration:**
If `prov-ecosystem` is in a non-standard location, update `Cargo.toml`:
```toml
[dependencies]
prov-ecosystem = { path = "../prov-ecosystem" } # Adjust path as needed
```
Or use environment variable:
```bash
export PROV_ECOSYSTEM_PATH=/custom/path/to/prov-ecosystem
```
**Verify:**
```bash
# Check if prov-ecosystem is found
cargo metadata --format-version=1 | grep prov-ecosystem
```
#### secretumvault
**What:** Unified encryption vault library (used by encryption features)
**Location:** Expected as sibling directory or git submodule
**Installation:**
```bash
# Option 1: Clone as sibling directory (recommended)
cd /path/to/projects
git clone https://github.com/your-org/secretumvault.git
git clone https://github.com/your-org/typedialog.git
# Option 2: Git submodule
cd typedialog
git submodule add https://github.com/your-org/secretumvault.git deps/secretumvault
git submodule update --init --recursive
```
**Path Configuration:**
If `secretumvault` is in a non-standard location, update `Cargo.toml`:
```toml
[dependencies]
secretumvault = { path = "../secretumvault" } # Adjust path as needed
```
Or use environment variable:
```bash
export SECRETUMVAULT_PATH=/custom/path/to/secretumvault
```
**Verify:**
```bash
# Check if secretumvault is found
cargo metadata --format-version=1 | grep secretumvault
```
### External Dependencies
#### just (Command Runner)
**What:** Command orchestration tool for running build recipes
**Required:** Yes (for all build workflows)
**Installation:**
```bash
# macOS (Homebrew)
brew install just
# Linux (cargo)
cargo install just
# Linux (from source)
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
# Arch Linux
pacman -S just
# Verify
just --version
```
**Configuration:**
No configuration needed. Justfiles are included in the project.
**Verify:**
```bash
# List available recipes
just --list
# Test a recipe
just build::cli
```
#### Nickel (Configuration Language)
**What:** Programmable configuration language for infrastructure validation
**Required:** Yes (for `typedialog-prov-gen` and Nickel validation features)
**Installation:**
```bash
# macOS (Homebrew)
brew install nickel
# Linux (cargo)
cargo install nickel-lang-cli
# From source
git clone https://github.com/tweag/nickel.git
cd nickel
cargo build --release
sudo cp target/release/nickel /usr/local/bin/
# Verify
nickel --version
```
**Path Configuration:**
If `nickel` is not in PATH, set the binary location:
```bash
# Add to ~/.bashrc or ~/.zshrc
export NICKEL_BIN=/custom/path/to/nickel
# Or set for current session
export PATH="/custom/path/to/nickel:$PATH"
```
**Verify:**
```bash
# Test Nickel evaluation
echo '{ x = 1 + 1 }' | nickel eval
# Test with TypeDialog
cargo test -p typedialog-prov-gen --lib
```
#### shellcheck (Bash Linter)
**What:** Shell script analysis tool for linting bash scripts
**Required:** Yes (for linting 142 bash scripts)
**Installation:**
```bash
# macOS (Homebrew)
brew install shellcheck
# Linux (apt)
sudo apt-get install shellcheck
# Arch Linux
sudo pacman -S shellcheck
# From source (Haskell)
cabal update
cabal install ShellCheck
# Verify
shellcheck --version
```
**Verify:**
```bash
# Test shellcheck
echo '#!/bin/bash\necho "test"' | shellcheck -
# Lint project scripts
just dev::lint-bash
```
#### markdownlint-cli2 (Markdown Linter)
**What:** Markdown linting and style checking for documentation
**Required:** Yes (for linting docs/ folder)
**Installation:**
```bash
# Global install (requires Node.js)
npm install -g markdownlint-cli2
# Verify
markdownlint-cli2 --version
```
**Path Configuration:**
Ensure Node.js is installed and npm global bin is in PATH:
```bash
# Check Node.js
node --version
npm --version
# Add npm global bin to PATH (if needed)
export PATH="$(npm config get prefix)/bin:$PATH"
```
**Verify:**
```bash
# Test markdownlint
echo '# Test' | markdownlint-cli2 --stdin
# Lint project docs
just dev::lint-markdown
```
### Dependency Quick Check
Run this script to verify all critical dependencies:
```bash
#!/bin/bash
echo "=== Checking Critical Dependencies ==="
# Check just
if command -v just &> /dev/null; then
echo "✓ just $(just --version)"
else
echo "✗ just - NOT FOUND"
echo " Install: cargo install just"
fi
# Check nickel
if command -v nickel &> /dev/null; then
echo "✓ nickel $(nickel --version)"
else
echo "✗ nickel - NOT FOUND"
echo " Install: cargo install nickel-lang-cli"
fi
# Check prov-ecosystem (path dependency)
if cargo metadata --format-version=1 2>/dev/null | grep -q prov-ecosystem; then
echo "✓ prov-ecosystem - FOUND"
else
echo "✗ prov-ecosystem - NOT FOUND"
echo " Clone to: ../prov-ecosystem"
fi
# Check secretumvault (path dependency)
if cargo metadata --format-version=1 2>/dev/null | grep -q secretumvault; then
echo "✓ secretumvault - FOUND"
else
echo "✗ secretumvault - NOT FOUND"
echo " Clone to: ../secretumvault"
fi
```
Save as `scripts/check_deps.sh` and run:
```bash
chmod +x scripts/check_deps.sh
./scripts/check_deps.sh
```
### Troubleshooting Dependencies
#### prov-ecosystem or secretumvault not found
**Error:**
```text
error: no matching package named `prov-ecosystem` found
location searched: /path/to/typedialog/../prov-ecosystem
```
**Solutions:**
1. **Clone to expected location:**
```bash
cd /path/to/typedialog/..
git clone https://github.com/your-org/prov-ecosystem.git
git clone https://github.com/your-org/secretumvault.git
```
2. **Update Cargo.toml paths:**
```toml
# In typedialog/Cargo.toml (workspace level)
prov-ecosystem = { path = "/absolute/path/to/prov-ecosystem" }
secretumvault = { path = "/absolute/path/to/secretumvault" }
```
3. **Use git submodules:**
```bash
git submodule add https://github.com/your-org/prov-ecosystem.git deps/prov-ecosystem
# Update Cargo.toml to use deps/prov-ecosystem
```
#### Nickel binary not found
**Error:**
```text
Error: nickel command not found
```
**Solutions:**
1. **Install via cargo:**
```bash
cargo install nickel-lang-cli
```
2. **Add to PATH:**
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```
3. **Set explicit path in environment:**
```bash
export NICKEL_BIN=/usr/local/bin/nickel
```
#### just command not found
**Error:**
```text
just: command not found
```
**Solutions:**
1. **Install via cargo:**
```bash
cargo install just
```
2. **Install via package manager:**
```bash
# macOS
brew install just
# Arch Linux
sudo pacman -S just
```
3. **Add to PATH:**
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```
## 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 `.woodpecker/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/`
```text
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
### .woodpecker/Dockerfile.cross
Multi-platform Docker build:
```bash
# Build image for specific target
docker build -f .woodpecker/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
Check all dependencies:
```bash
./scripts/check_deps.sh
```
Install required tools:
```bash
cargo install cross # For cross-compilation
cargo install just # For command orchestration
cargo install nickel-lang-cli # For Nickel validation
```
Clone internal dependencies:
```bash
cd /path/to/typedialog/..
git clone https://github.com/your-org/prov-ecosystem.git
git clone https://github.com/your-org/secretumvault.git
```
### 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 using [`cargo-sbom`](https://crates.io/crates/cargo-sbom).
### Regenerate SBOMs
When dependencies change (new crates, version updates, Cargo.lock changes):
```bash
just distro::generate-sbom
```
This regenerates:
- **SBOM.spdx.json** - SPDX 2.3 standard format (ISO/IEC 5962:2021)
- **SBOM.cyclonedx.json** - CycloneDX 1.4 format (ECMA standard)
### 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
**SBOM.spdx.json** (~350-400 KB)
- SPDX 2.3 format (ISO/IEC 5962:2021)
- Complete component inventory with unique identifiers
- Compatible with SPDX validators, GitHub Dependabot, and osv-scanner
- Generated by [cargo-sbom](https://crates.io/crates/cargo-sbom)
**SBOM.cyclonedx.json** (~280-320 KB)
- CycloneDX 1.4 format (ECMA standard)
- Complete component inventory with Package URLs (pURL)
- Compatible with vulnerability scanners and SCA tools (Dependabot, Snyk)
- Generated by [cargo-sbom](https://crates.io/crates/cargo-sbom)
### 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.

158
docs/ci/README.md Normal file
View File

@ -0,0 +1,158 @@
# CI/CD Pipelines
TypeDialog uses **dual CI/CD setup** to support both GitHub and Gitea/Forgejo platforms.
## Quick Reference
| Platform | Files | Documentation |
|----------|-------|---------------|
| **GitHub Actions** | `.github/workflows/*.yml` | Auto-configured |
| **Woodpecker CI** | `.woodpecker/*.yml` | See `.woodpecker/README.md` |
## Platform Comparison
| Feature | GitHub Actions | Woodpecker Basic | Woodpecker Advanced/Docker |
|---------|---------------|------------------|---------------------------|
| **Multi-OS** | ✅ Linux, macOS, Windows | ❌ Linux only | ✅ 5 targets* |
| **Linting** | ✅ 5 languages (parallel) | ✅ 5 languages (parallel) | ✅ 5 languages (parallel) |
| **Testing** | ✅ Matrix (3 OS) | ✅ Linux | ✅ Multi-OS** |
| **Coverage** | ✅ Codecov integration | ❌ | ✅ SonarQube** |
| **Security** | ✅ cargo-audit | ✅ cargo-audit | ✅ cargo-audit |
| **Compliance** | ✅ cargo-deny | ✅ cargo-deny | ✅ cargo-deny |
| **Benchmarks** | ✅ On PRs | ❌ | ✅ Gitea API** |
| **SBOM** | ✅ Auto-upload | ⚠️ Manual upload | ✅ Auto-upload |
| **Release** | ✅ 6 targets + crates.io | ❌ 1 target | ✅ 5 targets + crates.io |
| **Gitea API** | N/A | ❌ | ✅ Auto-create releases |
\* Advanced: cross-compilation, Docker: .woodpecker/Dockerfile.cross
\*\* Advanced pipelines only (ci-advanced.yml, release-advanced.yml, release-docker.yml)
## CI Pipeline (Both Platforms)
**Triggers**: Push to `main`/`develop`, Pull Requests
**Stages**:
1. **Linting** (parallel):
- Rust (clippy)
- Bash (shellcheck)
- Nickel
- Nushell
- Markdown
2. **Testing**: `just ci::test-all`
3. **Building**: `just ci::build-release`
4. **Security**: `cargo audit`
5. **Compliance**: `cargo deny check licenses`
**Duration**:
- GitHub Actions: ~20-25 min
- Woodpecker CI: ~15-20 min (with custom image), ~25-30 min (without)
## Release Pipeline (Both Platforms)
**Triggers**: Git tags `v*` (e.g., `v0.1.0`)
**GitHub Actions**: 6 targets, auto-upload, auto-publish to crates.io
**Woodpecker CI**: 3 pipeline options
- **Basic** (`release.yml`) - Linux x86_64 only, manual upload
- **Advanced** (`release-advanced.yml`) - 5 targets, Gitea API auto-upload
- **Docker-based** (`release-docker.yml`) - 5 targets, uses .woodpecker/Dockerfile.cross, Gitea API
**Artifacts**:
- Release binaries (GitHub: 6 targets, Woodpecker: 1-5 depending on pipeline)
- SHA256 checksums
- SBOM (SPDX + CycloneDX formats)
- BUILD_INFO.json manifest (Woodpecker Docker-based only)
- Auto-publish to crates.io (optional on both platforms)
## Local Testing
Test before pushing:
```bash
just ci::full # Complete pipeline
just ci::test-all # Tests only
just ci::audit # Security audit
just ci::deny # License check
```
## Setup
### GitHub Actions (Auto-configured)
Secrets required:
- `CODECOV_TOKEN` - For coverage reports
- `CARGO_REGISTRY_TOKEN` - For crates.io publishing
### Woodpecker CI (Manual)
See [`.woodpecker/README.md`](../../.woodpecker/README.md) for:
- Activation steps
- Custom Docker image (optional, faster CI)
- Secrets configuration
## Creating a Release
```bash
# 1. Update version in Cargo.toml files
# 2. Commit changes
git commit -am "chore: bump version to 0.1.0"
# 3. Create and push tag
git tag v0.1.0
git push origin v0.1.0
# 4. CI systems will:
# GitHub Actions:
# - Build 6 platform binaries
# - Generate SBOMs
# - Create GitHub Release with auto-upload
# - Publish to crates.io
#
# Woodpecker CI:
# - Basic: Build Linux x86_64 binary, generate SBOM (manual upload)
# - Advanced: Build 5 platform binaries, auto-create Gitea release, upload artifacts
# - Docker-based: Build 5 platforms via .woodpecker/Dockerfile.cross, auto-create Gitea release
# - Optional: Publish to crates.io (if CARGO_TOKEN configured)
```
**Woodpecker Pipeline Selection**:
Choose which release pipeline to use by renaming in `.woodpecker/`:
- Keep only one `release.yml` active
- Rename others to `.release-*.yml.disabled`
Example (use Docker-based):
```bash
mv .woodpecker/release.yml .woodpecker/.release-basic.yml.disabled
mv .woodpecker/release-advanced.yml .woodpecker/.release-advanced.yml.disabled
mv .woodpecker/release-docker.yml .woodpecker/release.yml
```
## Troubleshooting
### Tests Failing
Some tests require `ANTHROPIC_API_KEY` and are marked `#[ignore]`:
```bash
# Run locally with API key
export ANTHROPIC_API_KEY=sk-xxx
cargo test -- --ignored
```
### CI Caching Issues
**GitHub**: Clear caches via Actions UI
**Woodpecker**: Server-side cache configuration (ask admin)
### Security Audit Warnings
See `.cargo/audit.toml` for ignored advisories (unmaintained deps with no alternatives).
## More Information
- **Just commands**: See `justfiles/*.just`
- **Woodpecker setup**: See `.woodpecker/README.md`
- **Project structure**: See `README.md`

282
docs/cli/README.md Normal file
View File

@ -0,0 +1,282 @@
# TypeDialog CLI Backend
Command-line interface for TypeDialog prompts and forms.
## Overview
The CLI backend (`typedialog`) provides interactive terminal prompts powered by the [inquire](https://github.com/mikaelmello/inquire) library. Ideal for scripts, automation, CI/CD pipelines, and server-side tools.
## Features
- **8 Prompt Types**: text, confirm, select, multi-select, password, custom, editor, date
- **JSON/YAML/TOML Output**: Structured data for piping
- **Validation**: Built-in and custom validators
- **Autocompletion**: Smart suggestions for select prompts
- **Non-interactive Mode**: For automation (`--yes` flag)
- **Stdin Support**: Pipe data between commands
## Quick Start
### Installation
```bash
# From source
cargo build --release
sudo cp target/release/typedialog /usr/local/bin/
# Or use just
just build::release
```
### Basic Usage
```bash
# Simple text prompt
typedialog text "Enter your name"
# Select from options
typedialog select "Choose environment" dev staging production
# Password prompt (masked input)
typedialog password "Enter password"
# Multi-select (space to select, enter to confirm)
typedialog multi-select "Choose features" auth logging metrics
```
### With Forms
```bash
# Run a TOML form
typedialog form examples/01-basic/simple_form.toml
# Output as JSON
typedialog form config.toml --format json
# Non-interactive (use defaults)
typedialog form config.toml --yes
```
## Output Formats
```bash
# JSON
typedialog form config.toml --format json > output.json
# YAML
typedialog form config.toml --format yaml > output.yaml
# TOML
typedialog form config.toml --format toml > output.toml
# Nickel
typedialog form config.toml --format nickel > output.ncl
```
## Validation
### Built-in Validators
```toml
[[fields]]
name = "email"
field_type = "Text"
validation = "email" # email, url, number, etc.
```
### Custom Validation
```toml
[[fields]]
name = "age"
field_type = "Text"
validation = "range(18..120)"
error_message = "Age must be between 18 and 120"
```
## Examples
### Script Integration
```bash
#!/bin/bash
# Collect user input
CONFIG=$(typedialog form deploy.toml --format json)
# Use in script
ENVIRONMENT=$(echo "$CONFIG" | jq -r '.environment')
REGION=$(echo "$CONFIG" | jq -r '.region')
echo "Deploying to $ENVIRONMENT in $REGION..."
```
### CI/CD Pipeline
```yaml
# GitHub Actions
- name: Collect deployment config
run: |
typedialog form .github/deploy-config.toml --yes --format json > config.json
- name: Deploy
run: |
./deploy.sh --config config.json
```
### Piping Between Commands
```bash
# Generate config → validate → deploy
typedialog form config.toml --format json | \
jq '.environment = "production"' | \
./deploy.sh --stdin
```
## Command Reference
```bash
typedialog --help # Show help
typedialog text <prompt> # Text input
typedialog confirm <prompt> # Yes/no confirmation
typedialog select <prompt> <options> # Single selection
typedialog multi-select <prompt> <options> # Multiple selection
typedialog password <prompt> # Password input
typedialog editor <prompt> # Open editor
typedialog date <prompt> # Date picker
typedialog form <file> # Run form from TOML
```
### Global Flags
```bash
--format <json|yaml|toml|nickel> # Output format
--yes # Non-interactive mode
--config <file> # Config file
--log-level <level> # Logging verbosity
```
## Configuration
Global configuration in `~/.config/typedialog/config.toml`:
```toml
[cli]
default_format = "json"
theme = "default"
log_level = "info"
[validation]
strict = true
```
Or use config files:
```bash
typedialog form myform.toml --config config/cli/production.toml
```
## Backend-Specific Features
### Stdin Support
```bash
# Pipe JSON to pre-fill form
cat data.json | typedialog form config.toml --stdin
```
### Exit Codes
```bash
typedialog form config.toml
echo $? # 0 = success, 1 = validation error, 2 = user cancelled
```
### Quiet Mode
```bash
# Suppress all output except result
typedialog form config.toml --quiet --format json
```
## Use Cases
### 1. Deployment Scripts
Collect deployment parameters interactively:
```bash
typedialog form deploy.toml --format json > deploy-config.json
./deploy.sh --config deploy-config.json
```
### 2. Server Configuration
Generate server configs with validation:
```bash
typedialog form server-config.toml --format toml > /etc/myapp/config.toml
```
### 3. CI/CD Integration
Non-interactive mode with defaults:
```bash
typedialog form .ci/config.toml --yes --format json
```
### 4. Data Migration
Collect and validate migration parameters:
```bash
typedialog form migration.toml --format yaml | ./migrate.py --config -
```
## More examples
See [examples/04-backends/cli/](../../examples/04-backends/cli/) for:
- Basic prompts
- Form automation
- Piping and scripting
- Validation examples
- CI/CD integration
## Related Documentation
- [Installation](../installation.md) - Setup guide
- [Configuration](../configuration.md) - Configuration options
- [Field Types](../field_types.md) - Available field types
- [Examples](../../examples/04-backends/cli/) - Working examples
## Troubleshooting
### "Terminal not supported"
CLI requires a TTY. For non-interactive environments:
```bash
typedialog form config.toml --yes # Use defaults
```
### "Validation failed"
Check validation rules and input format:
```bash
typedialog form config.toml --log-level debug
```
### "Output format error"
Ensure format is valid:
```bash
typedialog form config.toml --format json # json, yaml, toml, or nickel
```
---
**Ready to start?** See [examples/04-backends/cli/](../../examples/04-backends/cli/)

28
docs/CONFIGURATION.md → docs/configuration.md
View File

@ -1,5 +1,5 @@
<div align="center">
<img src="../imgs/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
<img src="../assets/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
</div>
# Configuration Files
@ -10,7 +10,7 @@ Pre-configured settings for each TypeDialog backend and environment.
Configuration files are organized by **backend** (CLI, TUI, Web) and **environment** (default, dev, production).
```
```text
config/
├── cli/
│ ├── default.toml # Standard CLI settings
@ -33,17 +33,19 @@ config/
**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 |
| -------- | --------- | ------- | -------- | --------- |
| default | Standard | No | Yes | 300 s |
| dev | Development | Yes | Yes | 300 s |
| production | Production | No | Yes | 3600 s |
**Usage:**
```bash
typedialog --config config/cli/production.toml form.toml
```
**Features:**
- Inline validation
- Optional mouse support
- Placeholder text display
@ -54,17 +56,19 @@ typedialog --config config/cli/production.toml form.toml
**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
@ -75,18 +79,20 @@ typedialog-tui --config config/tui/production.toml form.toml
**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 |
**Basic Usage:**
```bash
typedialog-web form.toml
# Server starts on http://localhost:8080
```
**With Options:**
```bash
# Load defaults from .ncl file
typedialog-web form.toml --defaults values.ncl
@ -102,6 +108,7 @@ typedialog-web form.toml --port 9000
```
**Features:**
- HTML/CSS rendering
- CSRF protection
- Response caching
@ -133,6 +140,7 @@ logs = "/tmp/typedialog-web.log"
```
**Usage:**
```bash
typedialog --config config/cli/dev.toml form.toml
typedialog-tui --config config/tui/dev.toml form.toml
@ -163,6 +171,7 @@ cache_ttl = 3600
```
**Usage:**
```bash
typedialog --config config/cli/production.toml form.toml
typedialog-tui --config config/tui/production.toml form.toml
@ -358,15 +367,18 @@ 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

824
docs/deployment.md Normal file
View File

@ -0,0 +1,824 @@
# TypeDialog Agents - Deployment Guide
Production deployment guide for TypeDialog Agents system.
## Table of Contents
1. [Deployment Options](#deployment-options)
2. [Local Development](#local-development)
3. [Systemd Service](#systemd-service-linux)
4. [Docker Deployment](#docker-deployment)
5. [Kubernetes](#kubernetes)
6. [Reverse Proxy](#reverse-proxy-nginx)
7. [Monitoring](#monitoring)
8. [Security](#security)
9. [Performance Tuning](#performance-tuning)
10. [Backup & Recovery](#backup--recovery)
---
## Deployment Options
| Method | Complexity | Scalability | Best For |
|--------|-----------|-------------|----------|
| **Systemd Service** | Low | Single server | Small deployments |
| **Docker** | Medium | Multi-container | Standard deployments |
| **Kubernetes** | High | Cluster | Large-scale production |
| **Serverless** | Medium | Auto-scale | Variable workloads |
---
## Local Development
### Development Server
```bash
# Start development server with hot reload
cargo watch -x 'run --package typedialog-ag -- serve --port 8765'
# Or use release build
cargo run --release --package typedialog-ag -- serve --port 8765
```
### Environment Setup
Create `.env` file:
```bash
# .env
ANTHROPIC_API_KEY=sk-ant-your-key-here
OPENAI_API_KEY=sk-your-openai-key
RUST_LOG=info
TYPEAGENT_CACHE_DIR=/tmp/typeagent-cache
```
Load environment:
```bash
source .env
typedialog-ag serve --port 8765
```
---
## Systemd Service (Linux)
### Create Service File
Create `/etc/systemd/system/typeagent.service`:
```ini
[Unit]
Description=TypeDialog Agent HTTP Server
After=network.target
Wants=network-online.target
[Service]
Type=simple
User=typeagent
Group=typeagent
WorkingDirectory=/opt/typeagent
ExecStart=/usr/local/bin/typedialog-ag serve --port 8765
# Environment
Environment="ANTHROPIC_API_KEY=sk-ant-your-key-here"
Environment="RUST_LOG=info"
Environment="TYPEAGENT_CACHE_DIR=/var/cache/typeagent"
# Restart policy
Restart=always
RestartSec=10
StartLimitBurst=5
StartLimitIntervalSec=60
# Resource limits
MemoryLimit=2G
CPUQuota=200%
# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/cache/typeagent /var/log/typeagent
# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=typeagent
[Install]
WantedBy=multi-user.target
```
### Setup Service
```bash
# Create user
sudo useradd -r -s /bin/false typeagent
# Create directories
sudo mkdir -p /opt/typeagent/agents
sudo mkdir -p /var/cache/typeagent
sudo mkdir -p /var/log/typeagent
# Copy binary
sudo cp target/release/typedialog-ag /usr/local/bin/
sudo chmod 755 /usr/local/bin/typedialog-ag
# Copy agents
sudo cp -r agents/* /opt/typeagent/agents/
# Set permissions
sudo chown -R typeagent:typeagent /opt/typeagent
sudo chown -R typeagent:typeagent /var/cache/typeagent
sudo chown -R typeagent:typeagent /var/log/typeagent
# Install service
sudo systemctl daemon-reload
sudo systemctl enable typeagent
sudo systemctl start typeagent
```
### Manage Service
```bash
# Start service
sudo systemctl start typeagent
# Stop service
sudo systemctl stop typeagent
# Restart service
sudo systemctl restart typeagent
# Check status
sudo systemctl status typeagent
# View logs
sudo journalctl -u typeagent -f
# View last 100 lines
sudo journalctl -u typeagent -n 100
```
### Update Deployment
```bash
# Build new version
cargo build --release --package typedialog-ag
# Stop service
sudo systemctl stop typeagent
# Update binary
sudo cp target/release/typedialog-ag /usr/local/bin/
# Start service
sudo systemctl start typeagent
# Verify
sudo systemctl status typeagent
```
---
## Docker Deployment
### Dockerfile
Create `docker/Dockerfile`:
```dockerfile
# Multi-stage build for minimal image size
FROM rust:1.75-slim-bullseye AS builder
# Install dependencies
RUN apt-get update && apt-get install -y \
pkg-config \
libssl-dev \
&& rm -rf /var/lib/apt/lists/*
# Create app directory
WORKDIR /app
# Copy manifests
COPY Cargo.toml Cargo.lock ./
COPY crates ./crates
# Build release binary
RUN cargo build --release --package typedialog-ag
# Runtime stage
FROM debian:bullseye-slim
# Install runtime dependencies
RUN apt-get update && apt-get install -y \
ca-certificates \
libssl1.1 \
&& rm -rf /var/lib/apt/lists/*
# Create non-root user
RUN useradd -r -s /bin/false typeagent
# Create directories
RUN mkdir -p /app/agents /var/cache/typeagent
RUN chown -R typeagent:typeagent /app /var/cache/typeagent
# Copy binary from builder
COPY --from=builder /app/target/release/typedialog-ag /usr/local/bin/
# Copy agents
COPY agents /app/agents
# Switch to non-root user
USER typeagent
WORKDIR /app
# Expose port
EXPOSE 8765
# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD curl -f http://localhost:8765/health || exit 1
# Run server
CMD ["typedialog-ag", "serve", "--port", "8765"]
```
### Build Image
```bash
cd /path/to/typedialog
# Build image
docker build -t typeagent:latest -f docker/Dockerfile .
# Build with specific tag
docker build -t typeagent:v1.0.0 -f docker/Dockerfile .
# Verify image
docker images | grep typeagent
```
### Run Container
```bash
# Run with environment variables
docker run -d \
--name typeagent \
-p 8765:8765 \
-e ANTHROPIC_API_KEY=sk-ant-your-key-here \
-e RUST_LOG=info \
--restart unless-stopped \
typeagent:latest
# Run with volume mounts
docker run -d \
--name typeagent \
-p 8765:8765 \
-e ANTHROPIC_API_KEY=sk-ant-your-key-here \
-v $(pwd)/agents:/app/agents:ro \
-v typeagent-cache:/var/cache/typeagent \
--restart unless-stopped \
typeagent:latest
# Check logs
docker logs -f typeagent
# Check health
docker ps | grep typeagent
curl http://localhost:8765/health
```
### Docker Compose
Create `docker/docker-compose.yml`:
```yaml
version: '3.8'
services:
typeagent:
image: typeagent:latest
build:
context: ..
dockerfile: docker/Dockerfile
container_name: typeagent
restart: unless-stopped
ports:
- "8765:8765"
environment:
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
- OPENAI_API_KEY=${OPENAI_API_KEY:-}
- RUST_LOG=info
- TYPEAGENT_CACHE_DIR=/var/cache/typeagent
volumes:
- ../agents:/app/agents:ro
- typeagent-cache:/var/cache/typeagent
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8765/health"]
interval: 30s
timeout: 3s
retries: 3
start_period: 5s
deploy:
resources:
limits:
cpus: '2'
memory: 2G
reservations:
cpus: '0.5'
memory: 512M
# Optional: Nginx reverse proxy
nginx:
image: nginx:alpine
container_name: typeagent-nginx
restart: unless-stopped
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
- ./ssl:/etc/nginx/ssl:ro
depends_on:
- typeagent
volumes:
typeagent-cache:
driver: local
```
Usage:
```bash
cd docker
# Start services
docker-compose up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose down
# Restart
docker-compose restart
# Update and restart
docker-compose build
docker-compose up -d
```
---
## Kubernetes
### Deployment Manifest
Create `k8s/deployment.yaml`:
```yaml
apiVersion: v1
kind: Namespace
metadata:
name: typeagent
---
apiVersion: v1
kind: Secret
metadata:
name: typeagent-secrets
namespace: typeagent
type: Opaque
stringData:
anthropic-api-key: sk-ant-your-key-here
openai-api-key: sk-your-openai-key
---
apiVersion: v1
kind: ConfigMap
metadata:
name: typeagent-config
namespace: typeagent
data:
RUST_LOG: "info"
TYPEAGENT_CACHE_DIR: "/var/cache/typeagent"
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: typeagent
namespace: typeagent
labels:
app: typeagent
spec:
replicas: 3
selector:
matchLabels:
app: typeagent
template:
metadata:
labels:
app: typeagent
spec:
containers:
- name: typeagent
image: typeagent:latest
imagePullPolicy: IfNotPresent
ports:
- containerPort: 8765
name: http
env:
- name: ANTHROPIC_API_KEY
valueFrom:
secretKeyRef:
name: typeagent-secrets
key: anthropic-api-key
- name: RUST_LOG
valueFrom:
configMapKeyRef:
name: typeagent-config
key: RUST_LOG
- name: TYPEAGENT_CACHE_DIR
valueFrom:
configMapKeyRef:
name: typeagent-config
key: TYPEAGENT_CACHE_DIR
resources:
requests:
memory: "512Mi"
cpu: "500m"
limits:
memory: "2Gi"
cpu: "2000m"
livenessProbe:
httpGet:
path: /health
port: 8765
initialDelaySeconds: 10
periodSeconds: 30
readinessProbe:
httpGet:
path: /health
port: 8765
initialDelaySeconds: 5
periodSeconds: 10
volumeMounts:
- name: cache
mountPath: /var/cache/typeagent
volumes:
- name: cache
emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
name: typeagent
namespace: typeagent
spec:
selector:
app: typeagent
ports:
- port: 80
targetPort: 8765
protocol: TCP
type: ClusterIP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: typeagent
namespace: typeagent
annotations:
kubernetes.io/ingress.class: nginx
cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
tls:
- hosts:
- typeagent.yourdomain.com
secretName: typeagent-tls
rules:
- host: typeagent.yourdomain.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: typeagent
port:
number: 80
```
Deploy:
```bash
# Apply manifests
kubectl apply -f k8s/deployment.yaml
# Check status
kubectl get all -n typeagent
# View logs
kubectl logs -n typeagent -l app=typeagent -f
# Scale replicas
kubectl scale deployment/typeagent -n typeagent --replicas=5
# Rolling update
kubectl set image deployment/typeagent typeagent=typeagent:v1.1.0 -n typeagent
```
---
## Reverse Proxy (Nginx)
### Nginx Configuration
Create `/etc/nginx/sites-available/typeagent`:
```nginx
upstream typeagent {
# Multiple backend servers for load balancing
server 127.0.0.1:8765 max_fails=3 fail_timeout=30s;
# server 127.0.0.1:8766 max_fails=3 fail_timeout=30s;
# server 127.0.0.1:8767 max_fails=3 fail_timeout=30s;
keepalive 32;
}
# Rate limiting
limit_req_zone $binary_remote_addr zone=typeagent_limit:10m rate=10r/s;
server {
listen 80;
server_name typeagent.yourdomain.com;
# Redirect to HTTPS
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name typeagent.yourdomain.com;
# SSL Configuration
ssl_certificate /etc/letsencrypt/live/typeagent.yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/typeagent.yourdomain.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers on;
# Security headers
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;
# Logging
access_log /var/log/nginx/typeagent-access.log combined;
error_log /var/log/nginx/typeagent-error.log warn;
# Client limits
client_max_body_size 10M;
client_body_timeout 60s;
location / {
# Rate limiting
limit_req zone=typeagent_limit burst=20 nodelay;
# Proxy settings
proxy_pass http://typeagent;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Connection "";
# Timeouts
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
# Buffering
proxy_buffering on;
proxy_buffer_size 4k;
proxy_buffers 8 4k;
}
# Health check endpoint (no rate limiting)
location /health {
proxy_pass http://typeagent;
access_log off;
}
}
```
Enable and test:
```bash
# Test configuration
sudo nginx -t
# Enable site
sudo ln -s /etc/nginx/sites-available/typeagent /etc/nginx/sites-enabled/
# Reload nginx
sudo systemctl reload nginx
# Check status
sudo systemctl status nginx
```
---
## Monitoring
### Prometheus Metrics
Add metrics endpoint (future enhancement):
```rust
// In main.rs
Router::new()
.route("/metrics", get(metrics_handler))
```
### Logging
Structured logging with `tracing`:
```bash
# Set log level
export RUST_LOG=debug
# JSON format
export RUST_LOG_FORMAT=json
# Specific module
export RUST_LOG=typedialog_ag_core=debug,typedialog_ag=info
```
### Health Checks
```bash
# Simple health check
curl http://localhost:8765/health
# Detailed health check script
cat > health-check.sh << 'EOF'
#!/bin/bash
RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8765/health)
if [ "$RESPONSE" = "200" ]; then
echo "OK"
exit 0
else
echo "FAIL: HTTP $RESPONSE"
exit 1
fi
EOF
chmod +x health-check.sh
```
---
## Security
### API Key Management
**DO NOT:**
- Commit API keys to Git
- Hardcode keys in configuration files
- Share keys in plain text
**DO:**
- Use environment variables
- Use secrets management (Vault, AWS Secrets Manager)
- Rotate keys regularly
- Use separate keys per environment
### Network Security
```bash
# Firewall rules (UFW)
sudo ufw allow 8765/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
# Or iptables
sudo iptables -A INPUT -p tcp --dport 8765 -j ACCEPT
```
### HTTPS/TLS
Use Let's Encrypt for free SSL certificates:
```bash
# Install certbot
sudo apt-get install certbot python3-certbot-nginx
# Get certificate
sudo certbot --nginx -d typeagent.yourdomain.com
# Auto-renewal
sudo certbot renew --dry-run
```
---
## Performance Tuning
### System Limits
Edit `/etc/security/limits.conf`:
```
typeagent soft nofile 65536
typeagent hard nofile 65536
typeagent soft nproc 4096
typeagent hard nproc 4096
```
### Cache Tuning
```yaml
# ~/.typeagent/config.yaml
cache:
strategy: Both
max_entries: 5000 # Increase for high traffic
cache_dir: /var/cache/typeagent
```
### Rust Performance
Build with optimizations:
```toml
# Cargo.toml
[profile.release]
lto = true
codegen-units = 1
opt-level = 3
```
---
## Backup & Recovery
### Backup Strategy
```bash
#!/bin/bash
# backup-typeagent.sh
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/typeagent/$DATE"
mkdir -p "$BACKUP_DIR"
# Backup agents
cp -r /opt/typeagent/agents "$BACKUP_DIR/"
# Backup configuration
cp ~/.typeagent/config.yaml "$BACKUP_DIR/"
# Backup cache (optional)
# tar -czf "$BACKUP_DIR/cache.tar.gz" /var/cache/typeagent
# Compress
tar -czf "/backup/typeagent-$DATE.tar.gz" "$BACKUP_DIR"
# Clean old backups (keep 30 days)
find /backup -name "typeagent-*.tar.gz" -mtime +30 -delete
```
### Recovery
```bash
# Extract backup
tar -xzf typeagent-20241223.tar.gz
# Restore agents
sudo cp -r backup/agents/* /opt/typeagent/agents/
# Restore config
cp backup/config.yaml ~/.typeagent/
# Restart service
sudo systemctl restart typeagent
```
---
## Next Steps
1. Choose deployment method
2. Configure monitoring
3. Set up backups
4. Configure SSL/TLS
5. Test failover procedures
6. Document your specific deployment
For issues, see [installation.md](installation.md) troubleshooting section.

30
docs/DEVELOPMENT.md → docs/development.md
View File

@ -1,5 +1,5 @@
<div align="center">
<img src="../imgs/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
<img src="../assets/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
</div>
# Development Guide
@ -32,7 +32,7 @@ just help distro # Distribution & packaging
git clone https://github.com/anthropics/typedialog.git
cd typedialog
# 2. Verify installation (see INSTALLATION.md)
# 2. Verify installation (see installation.md)
rustc --version && cargo --version && just --version
# 3. Build project
@ -40,8 +40,13 @@ just build::default
# 4. Run tests
just test::all
# 5. Setup pre-commit hooks (optional but recommended)
./scripts/setup-pre-commit.sh
```
**See**: [pre-commit-setup.md](pre-commit-setup.md) for automated linting before commits.
### Format & Lint Code
```bash
@ -299,7 +304,7 @@ just distro::create-checksums
# 4. Prepare release
just distro::package-release
# 5. Create GitHub release (see RELEASE.md)
# 5. Create GitHub release (see release.md)
```
## Examples
@ -307,6 +312,7 @@ just distro::package-release
Complete examples organized by category:
### Basic Examples
```bash
# Run basic form
cargo run --example form
@ -319,6 +325,7 @@ cargo run --example form_with_grouped_items
```
### Advanced Examples
```bash
# Conditional logic
cargo run --example conditional_required_demo
@ -328,6 +335,7 @@ cargo run --example form_with_autocompletion
```
### Backend-Specific
```bash
# CLI with autocompletion
cargo run --example autocompletion_demo
@ -358,13 +366,14 @@ cargo run --example nickel_template_context
```
See [../examples/07-nickel-generation/](../examples/07-nickel-generation/) for complete guide.
See [NICKEL.md](NICKEL.md) for detailed Nickel documentation.
See [nickel.md](nickel.md) for detailed Nickel documentation.
## Troubleshooting
### Build errors
Clear build cache and rebuild:
```bash
cargo clean
just build::default
@ -373,6 +382,7 @@ just build::default
### Test failures
Run with backtrace for more details:
```bash
RUST_BACKTRACE=1 cargo test
```
@ -380,6 +390,7 @@ RUST_BACKTRACE=1 cargo test
### Format check failing
Auto-fix formatting:
```bash
just fmt
```
@ -387,6 +398,7 @@ just fmt
### "just" not found
Install or add to PATH:
```bash
cargo install just
export PATH="$HOME/.cargo/bin:$PATH"
@ -395,6 +407,7 @@ export PATH="$HOME/.cargo/bin:$PATH"
### cargo-watch not working
Install it:
```bash
cargo install cargo-watch
```
@ -402,6 +415,7 @@ cargo install cargo-watch
### Port already in use (web backend)
Change port in config:
```toml
# config/web/dev.toml
[server]
@ -409,6 +423,7 @@ port = 3001 # Instead of 3000
```
Or override:
```bash
TYPEDIALOG_WEB_PORT=3001 cargo run -p typedialog-web
```
@ -418,6 +433,7 @@ TYPEDIALOG_WEB_PORT=3001 cargo run -p typedialog-web
### Faster builds
Use incremental compilation:
```bash
export CARGO_BUILD_JOBS=$(nproc)
export CARGO_INCREMENTAL=1
@ -458,10 +474,10 @@ just dev::watch
## Next Steps
- Read [BUILD.md](BUILD.md) for building distributions
- Read [CONFIGURATION.md](CONFIGURATION.md) for configuration options
- 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
- See [release.md](release.md) for release process
---

160
docs/encryption/README.md Normal file
View File

@ -0,0 +1,160 @@
# TypeDialog Encryption
Complete guide to encryption and secure field handling in TypeDialog.
## Overview
TypeDialog provides comprehensive encryption support for sensitive data across all backends (CLI, TUI, Web). Encrypt fields at rest, in transit, and during processing with multiple encryption providers.
## Documentation
| Document | Purpose |
| ---------- | --------- |
| **[encryption-quick-start.md](encryption-quick-start.md)** | Get started with encryption in 5 minutes |
| **[encryption-services-setup.md](encryption-services-setup.md)** | Configure encryption services (AWS KMS, GCP KMS, Vault) |
| **[encryption-unified-architecture.md](encryption-unified-architecture.md)** | Architecture and design decisions |
## Quick Start
### 1. Mark Sensitive Fields
```toml
[[fields]]
name = "password"
field_type = "Password"
encrypted = true
```
### 2. Choose Encryption Provider
```toml
[encryption]
provider = "aws_kms" # or "gcp_kms", "vault", "local"
key_id = "arn:aws:kms:us-east-1:..."
```
### 3. Run with Encryption Enabled
```bash
typedialog form config.toml --encrypt
```
## Supported Backends
| Backend | Encryption Support | Notes |
| --------- | ------------------- | ------- |
| **CLI** | ✅ Full | Encrypts before output |
| **TUI** | ✅ Full | Masked input, encrypted storage |
| **Web** | ✅ Full | HTTPS required, encrypted at rest |
## Encryption Providers
### AWS KMS
Enterprise-grade encryption with AWS Key Management Service.
- Automatic key rotation
- CloudTrail audit logging
- FIPS 140-2 validated
### GCP Cloud KMS
Google Cloud's managed encryption service.
- Hardware Security Module (HSM) support
- Automatic key versioning
- IAM integration
### HashiCorp Vault
Self-hosted secret management and encryption.
- Dynamic secrets
- Fine-grained access control
- Audit logging
### Local (Development)
Local encryption for development and testing.
- No external dependencies
- Not recommended for production
## Features
- **Field-level encryption** - Encrypt specific fields, not entire forms
- **Multiple providers** - Choose the right provider for your environment
- **Automatic decryption** - Transparent decryption when authorized
- **Audit logging** - Track all encryption/decryption operations
- **Key rotation** - Automatic key rotation support (AWS KMS, GCP KMS)
## Use Cases
### 1. PII Protection
Encrypt personally identifiable information (names, emails, SSNs).
### 2. Credential Management
Secure API keys, passwords, and tokens.
### 3. Compliance
Meet GDPR, HIPAA, SOC 2 requirements.
### 4. Multi-tenant SaaS
Isolate customer data with separate encryption keys.
## Security Best Practices
1. **Use managed services** - Prefer AWS KMS or GCP KMS over local encryption
2. **Enable key rotation** - Rotate encryption keys regularly
3. **Audit access** - Monitor who accesses encrypted data
4. **Encrypt in transit** - Always use HTTPS for web backend
5. **Validate inputs** - Sanitize before encryption to prevent injection
## Examples
See [examples/08-encryption/](../../examples/08-encryption/) for working examples:
- Basic field encryption
- Multiple encryption providers
- Key rotation
- Compliance scenarios
## Related Documentation
- [Field Types](../field_types.md) - Field type reference including `encrypted` attribute
- [Configuration](../configuration.md) - Backend configuration with encryption
- [Web Backend](../web/) - HTTPS and transport security
## Troubleshooting
### "Encryption provider not configured"
Set provider in config:
```toml
[encryption]
provider = "aws_kms"
key_id = "..."
```
### "Failed to decrypt"
- Check key permissions
- Verify key ID is correct
- Ensure provider credentials are set
### "HTTPS required for encrypted fields"
Web backend requires HTTPS when encryption is enabled. Configure TLS certificates.
---
**Next Steps:**
1. Read [encryption-quick-start.md](encryption-quick-start.md)
2. Configure your provider: [encryption-services-setup.md](encryption-services-setup.md)
3. Review architecture: [encryption-unified-architecture.md](encryption-unified-architecture.md)

229
docs/encryption/encryption-quick-start.md Normal file
View File

@ -0,0 +1,229 @@
# Encryption Testing - Quick Start
## Quick Summary
```bash
# 1. Setup services (Age already configured, RustyVault requires Docker)
./scripts/encryption-test-setup.sh
# 2. Load environment
source /tmp/typedialog-env.sh
# 3. Test redaction (no service) - Simple example
typedialog form examples/08-encryption/simple-login.toml --redact --format json
# 4. Test Age encryption (requires ~/.age/key.txt)
typedialog form examples/08-encryption/simple-login.toml \
--encrypt --backend age \
--key-file ~/.age/key.txt \
--format json
# 5. Full feature demo (all encryption features)
typedialog form examples/08-encryption/credentials.toml --redact --format json
# 6. Run all integration tests
cargo test --test nickel_integration test_encryption -- --nocapture
```
## Example Forms
### Simple Login Form (`examples/08-encryption/simple-login.toml`)
Minimal example for quick testing:
- `username` (plaintext)
- `password` (sensitive, auto-detected from type)
**Use this for**:
- Quick verification of redaction
- Basic Age encryption testing
- First-time setup validation
### Full Credentials Form (`examples/08-encryption/credentials.toml`)
Comprehensive example demonstrating all encryption features:
- Non-sensitive fields: username, email, company
- Auto-detected sensitive: password, confirm_password (FieldType::Password)
- Explicitly marked sensitive: api_token, ssh_key, database_url
- Field-level backends: vault_token (RustyVault config)
- Override: demo_password (type=password but NOT sensitive)
**Use this for**:
- Testing field-level sensitivity control
- Field-specific encryption backend configuration
- Demonstrating RustyVault setup
### Nickel Schema (`examples/08-encryption/nickel-secrets.ncl`)
Demonstrates encryption in Nickel schema language:
- `Sensitive Backend="age"` annotations
- Key path specification
- Nested structure with sensitive fields
**Use this for**:
- Understanding Nickel contract syntax
- Converting Nickel schemas to TOML forms
See `examples/08-encryption/README.md` for detailed examples and testing instructions.
## Current Status
✅ **Age (Local encryption)** - Ready to test
- Public key: Generated automatically
- Private key: `~/.age/key.txt`
- No service required, uses CLI tool
- Forms ready: `simple-login.toml`, `credentials.toml`
✅ **Redaction** - Fully functional
- Works without any encryption service
- Auto-detects sensitive fields from FieldType::Password
- Field-level control with explicit `sensitive` flag
⏳ **RustyVault (HTTP service)** - Framework ready, tests pending
- Needs: Docker or manual build
- Service: `http://localhost:8200`
- API: Transit secrets engine
- Configuration demo: `credentials.toml` vault_token field
## Test Results
**Tests passing (redaction, metadata mapping):**
```text
cargo test --test nickel_integration test_encryption
```
Output:
```text
running 5 tests
test test_encryption_metadata_parsing ... ok
test test_encryption_metadata_in_nickel_field ... ok
test test_encryption_auto_detection_from_field_type ... ok
test test_encryption_roundtrip_with_redaction ... ok
test test_encryption_metadata_to_field_definition ... ok
test result: ok. 5 passed; 0 failed
```
All tests use the example forms for verification.
## Next Steps for Full Encryption Testing
### 1. Create test forms with encryption
**test_form_age.toml:**
```toml
name = "age_test"
display_mode = "complete"
[[fields]]
name = "username"
type = "text"
prompt = "Username"
sensitive = false
[[fields]]
name = "password"
type = "password"
prompt = "Password"
sensitive = true
encryption_backend = "age"
[fields.encryption_config]
key = "~/.age/key.txt"
```
### 2. Test Age encryption manually
```bash
# Generate test message
echo "test-secret-123" > /tmp/test.txt
# Get public key
PUBLIC_KEY=$(grep "^public key:" ~/.age/key.txt | cut -d' ' -f3)
# Encrypt
age -r "$PUBLIC_KEY" /tmp/test.txt > /tmp/test.age
# Decrypt
age -d -i ~/.age/key.txt /tmp/test.age
# Output: test-secret-123
```
### 3. Implement Age roundtrip test
File: `crates/typedialog-core/tests/encryption_roundtrip.rs`
```rust
#[test]
fn test_age_encrypt_decrypt_roundtrip() {
use typedialog_core::helpers::{EncryptionContext, transform_results};
let mut results = HashMap::new();
results.insert("secret".to_string(), json!("my-password"));
let field = FieldDefinition {
name: "secret".to_string(),
sensitive: Some(true),
encryption_backend: Some("age".to_string()),
encryption_config: Some({
let mut m = HashMap::new();
m.insert("key".to_string(), "~/.age/key.txt".to_string());
m
}),
..Default::default()
};
// Encrypt
let context = EncryptionContext::encrypt_with("age", Default::default());
let encrypted = transform_results(&results, &[field.clone()], &context, None)
.expect("Encryption failed");
// Verify ciphertext
let ciphertext = encrypted.get("secret").unwrap().as_str().unwrap();
assert!(ciphertext.starts_with("age1-"), "Should be Age format");
assert_ne!(ciphertext, "my-password", "Should be encrypted");
}
```
### 4. Test with RustyVault (optional, requires Docker)
```bash
# Pull RustyVault image
docker pull rustyvault:latest
# Re-run setup script
./scripts/encryption-test-setup.sh
# Test encryption with vault
typedialog form test_form_age.toml \
--encrypt --backend rustyvault \
--vault-addr http://localhost:8200 \
--vault-token root \
--vault-key-path transit/keys/typedialog-key \
--format json
```
## Verification Checklist
- [ ] Age installed: `age --version`
- [ ] Age keys generated: `cat ~/.age/key.txt`
- [ ] Test redaction: `typedialog form ... --redact`
- [ ] Run encryption tests: `cargo test --test nickel_integration test_encryption`
- [ ] All 5 tests passing
- [ ] (Optional) Docker available for RustyVault
- [ ] (Optional) RustyVault running: `curl http://localhost:8200/v1/sys/health`
## Documentation
Full setup guide: See `docs/encryption-services-setup.md`

740
docs/encryption/encryption-services-setup.md Normal file
View File

@ -0,0 +1,740 @@
# HOW-TO: Configure and Run Encryption Services for typedialog
## Overview
This guide walks through setting up **Age** (local file-based encryption) and **RustyVault** (HTTP-based encryption service) to test the typedialog encryption pipeline end-to-end.
**Service Matrix:**
| Backend | Type | Setup Complexity | Network | Requires |
| --------- | ------ | ------------------ | --------- | ---------- |
| **Age** | Local file-based | Trivial | None | age CLI tool |
| **RustyVault** | HTTP vault server | Moderate | localhost:8200 | Docker or manual build |
| **SOPS** | External tool | Complex | Varies | sops CLI + backends |
This guide covers Age (trivial) and RustyVault (moderate). SOPS is skipped for now.
---
## Part 1: Age Backend (Local File Encryption)
### What is Age?
Age is a simple, modern encryption tool using X25519 keys. Perfect for development because:
- No daemon/service required
- Keys stored as plaintext files
- Single binary
### Installation
**macOS (via Homebrew):**
```bash
brew install age
```
**Linux (Ubuntu/Debian):**
```bash
sudo apt-get install age
```
**Manual (any OS):**
```bash
# Download from https://github.com/FiloSottile/age/releases
# Extract and add to PATH
tar xzf age-v1.1.1-linux-amd64.tar.gz
sudo mv age/age /usr/local/bin/
sudo mv age/age-keygen /usr/local/bin/
```
**Verify installation:**
```bash
age --version
# age v1.1.1
```
### Generate Age Key Pair
Age uses a single private key file that contains both public and private components. The public key is derived from the private key.
**Generate keys for testing:**
```bash
# Create a test directory
mkdir -p ~/.age
# Generate private key
age-keygen -o ~/.age/key.txt
# Output will show:
# Public key: age1...xxx (save this, shown in file)
# Written to /home/user/.age/key.txt
```
**Verify key generation:**
```bash
# Check private key exists
cat ~/.age/key.txt
# Output: AGE-SECRET-KEY-1XXXX...
# Extract public key (age CLI does this automatically)
grep "^public key:" ~/.age/key.txt | cut -d' ' -f3
```
### Test Age Encryption Locally
**Create a test plaintext file:**
```bash
echo "This is a secret message" > test_message.txt
```
**Encrypt with age:**
```bash
# Get public key from private key
PUBLIC_KEY=$(grep "^public key:" ~/.age/key.txt | cut -d' ' -f3)
# Encrypt
age -r "$PUBLIC_KEY" test_message.txt > test_message.age
# Verify ciphertext is unreadable
cat test_message.age
# Output: AGE-ENCRYPTION-V1...binary...
```
**Decrypt with age:**
```bash
# Decrypt (will prompt for passphrase if key is encrypted)
age -d -i ~/.age/key.txt test_message.age
# Output: This is a secret message
```
### Configure typedialog to Use Age
**Environment variables:**
```bash
export AGE_KEY_FILE="$HOME/.age/key.txt"
```
**CLI flags:**
```bash
# Redact mode (no encryption needed)
typedialog form examples/08-encryption/simple-login.toml --redact --format json
# Encrypt mode (requires Age backend)
typedialog form examples/08-encryption/simple-login.toml --encrypt --backend age --key-file ~/.age/key.txt --format json
```
See `examples/08-encryption/README.md` for more example forms and test cases.
**TOML form configuration:**
```toml
[[fields]]
name = "password"
type = "password"
prompt = "Enter password"
sensitive = true
encryption_backend = "age"
[fields.encryption_config]
key = "~/.age/key.txt"
```
---
## Part 2: RustyVault Backend (HTTP Service)
### What is RustyVault?
RustyVault is a Rust implementation of HashiCorp Vault's Transit API:
- HTTP-based encryption/decryption service
- Suitable for production environments
- API-compatible with Vault Transit secrets engine
### Installation & Setup
**Option A: Docker (Recommended for testing)**
RustyVault provides official Docker images. Check availability:
```bash
# Search Docker Hub
docker search rustyvault
# Or build from source
git clone https://github.com/Tongsuo-Project/RustyVault.git
cd RustyVault
docker build -t rustyvault:latest .
```
**Option B: Manual Build (if Docker not available)**
```bash
# Prerequisites: Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Clone and build
git clone https://github.com/Tongsuo-Project/RustyVault.git
cd RustyVault
cargo build --release
# Binary at: target/release/rustyvault
```
### Run RustyVault Service
**Using Docker (single command):**
```bash
docker run -d \
--name rustyvault \
-p 8200:8200 \
-e RUSTYVAULT_LOG_LEVEL=info \
rustyvault:latest
# Verify it started
docker logs rustyvault | head -20
```
**Using local binary:**
```bash
# Create config directory
mkdir -p ~/.rustyvault
cd ~/.rustyvault
# Create minimal config (rustyvault.toml)
cat > config.toml <<'EOF'
[server]
address = "127.0.0.1:8200"
tls_disable = true
[backend]
type = "inmem" # In-memory storage (ephemeral)
EOF
# Run service
~/RustyVault/target/release/rustyvault server -c config.toml
```
**Verify service is running:**
```bash
# In another terminal
curl -s http://localhost:8200/v1/sys/health | jq .
# Should return health status JSON
```
### Configure RustyVault for Encryption
**Initialize RustyVault (first time only):**
```bash
# Generate initial token
VAULT_INIT=$(curl -s -X POST http://localhost:8200/v1/sys/init \
-d '{"secret_shares": 1, "secret_threshold": 1}' | jq -r .keys[0])
# Unseal vault
curl -s -X PUT http://localhost:8200/v1/sys/unseal \
-d "{\"key\": \"$VAULT_INIT\"}" > /dev/null
# Save root token
ROOT_TOKEN=$(curl -s -X POST http://localhost:8200/v1/sys/unseal \
-d "{\"key\": \"$VAULT_INIT\"}" | jq -r .auth.client_token)
export VAULT_TOKEN="$ROOT_TOKEN"
```
**Enable Transit secrets engine:**
```bash
curl -s -X POST http://localhost:8200/v1/sys/mounts/transit \
-H "X-Vault-Token: $VAULT_TOKEN" \
-d '{"type": "transit"}' | jq .
```
**Create encryption key:**
```bash
curl -s -X POST http://localhost:8200/v1/transit/keys/typedialog-key \
-H "X-Vault-Token: $VAULT_TOKEN" \
-d '{}' | jq .
# Verify key created
curl -s http://localhost:8200/v1/transit/keys/typedialog-key \
-H "X-Vault-Token: $VAULT_TOKEN" | jq .
```
### Test RustyVault Encryption
**Encrypt data via HTTP:**
```bash
# Plaintext (base64 encoded)
PLAINTEXT=$(echo -n "my-secret-password" | base64)
curl -s -X POST http://localhost:8200/v1/transit/encrypt/typedialog-key \
-H "X-Vault-Token: $VAULT_TOKEN" \
-d "{\"plaintext\": \"$PLAINTEXT\"}" | jq .data.ciphertext
```
**Decrypt data via HTTP:**
```bash
# From encryption output above
CIPHERTEXT="vault:v1:..."
curl -s -X POST http://localhost:8200/v1/transit/decrypt/typedialog-key \
-H "X-Vault-Token: $VAULT_TOKEN" \
-d "{\"ciphertext\": \"$CIPHERTEXT\"}" | jq -r .data.plaintext | base64 -d
```
### Configure typedialog to Use RustyVault
**Environment variables:**
```bash
export VAULT_ADDR="http://localhost:8200"
export VAULT_TOKEN="s.xxxx..." # Token from above
```
**CLI flags:**
```bash
typedialog form examples/08-encryption/credentials.toml \
--encrypt \
--backend rustyvault \
--vault-addr http://localhost:8200 \
--vault-token "s.xxxx..." \
--vault-key-path "transit/keys/typedialog-key" \
--format json
```
This form includes field-level RustyVault configuration in the `vault_token` field.
**TOML form configuration:**
```toml
[[fields]]
name = "password"
type = "password"
prompt = "Enter password"
sensitive = true
encryption_backend = "rustyvault"
[fields.encryption_config]
vault_addr = "http://localhost:8200"
vault_token = "s.xxxx..."
key_path = "transit/keys/typedialog-key"
```
---
## Part 3: Complete Integration Test Workflow
### Script: Setup Everything
Create `scripts/encryption-test-setup.sh`:
```bash
#!/usr/bin/env bash
set -e
echo "=== typedialog Encryption Services Setup ==="
# Age Setup
echo "1. Setting up Age..."
if ! command -v age &> /dev/null; then
echo " ✗ age not installed. Run: brew install age"
exit 1
fi
mkdir -p ~/.age
if [ ! -f ~/.age/key.txt ]; then
echo " → Generating Age keys..."
age-keygen -o ~/.age/key.txt
fi
export AGE_KEY_FILE="$HOME/.age/key.txt"
echo " ✓ Age configured at: $AGE_KEY_FILE"
# RustyVault Setup (Docker)
echo ""
echo "2. Setting up RustyVault (Docker)..."
if ! command -v docker &> /dev/null; then
echo " ⚠ Docker not installed, skipping RustyVault"
echo " → Install Docker or skip RustyVault tests"
else
if ! docker ps | grep -q rustyvault; then
echo " → Starting RustyVault container..."
docker run -d \
--name rustyvault \
-p 8200:8200 \
-e RUSTYVAULT_LOG_LEVEL=info \
rustyvault:latest
sleep 2
fi
# Initialize vault
echo " → Initializing RustyVault..."
VAULT_INIT=$(curl -s -X POST http://localhost:8200/v1/sys/init \
-d '{"secret_shares": 1, "secret_threshold": 1}' | jq -r .keys[0])
curl -s -X PUT http://localhost:8200/v1/sys/unseal \
-d "{\"key\": \"$VAULT_INIT\"}" > /dev/null
# Get root token
RESPONSE=$(curl -s -X GET http://localhost:8200/v1/sys/unseal \
-H "X-Vault-Token: $VAULT_INIT")
export VAULT_TOKEN=$(echo "$RESPONSE" | jq -r .auth.client_token // "root")
export VAULT_ADDR="http://localhost:8200"
# Enable transit
curl -s -X POST http://localhost:8200/v1/sys/mounts/transit \
-H "X-Vault-Token: $VAULT_TOKEN" \
-d '{"type": "transit"}' > /dev/null 2>&1 || true
# Create key
curl -s -X POST http://localhost:8200/v1/transit/keys/typedialog-key \
-H "X-Vault-Token: $VAULT_TOKEN" \
-d '{}' > /dev/null 2>&1 || true
echo " ✓ RustyVault running at: http://localhost:8200"
echo " ✓ Token: $VAULT_TOKEN"
fi
echo ""
echo "=== Setup Complete ==="
echo ""
echo "Test Age encryption:"
echo " typedialog form test.toml --encrypt --backend age --key-file ~/.age/key.txt"
echo ""
echo "Test RustyVault encryption:"
echo " export VAULT_ADDR='http://localhost:8200'"
echo " export VAULT_TOKEN='$VAULT_TOKEN'"
echo " typedialog form test.toml --encrypt --backend rustyvault --vault-key-path 'transit/keys/typedialog-key'"
```
**Make executable and run:**
```bash
chmod +x scripts/encryption-test-setup.sh
./scripts/encryption-test-setup.sh
```
### Test Case 1: Age Redaction (No Service Required)
**Option A: Use pre-built example (Recommended)**
```bash
typedialog form examples/08-encryption/simple-login.toml --redact --format json
# Expected output:
# {"username": "alice", "password": "[REDACTED]"}
```
**Option B: Create form manually**
```bash
# Create test form
cat > test_redaction.toml <<'EOF'
name = "test_form"
display_mode = "complete"
[[fields]]
name = "username"
type = "text"
prompt = "Username"
[[fields]]
name = "password"
type = "password"
prompt = "Password"
sensitive = true
EOF
# Test redaction (requires no service)
typedialog form test_redaction.toml --redact --format json
```
### Test Case 2: Age Encryption (Service Not Required, Key File Required)
**Option A: Use pre-built example (Recommended)**
```bash
# Prerequisites: Age key generated (from setup script)
./scripts/encryption-test-setup.sh
# Test with simple form
typedialog form examples/08-encryption/simple-login.toml \
--encrypt --backend age --key-file ~/.age/key.txt --format json
# Expected output: password field contains age ciphertext
# {"username": "alice", "password": "age1muz6ah54ew9am7mzmy0m4w5..."}
# Or test with full credentials form
typedialog form examples/08-encryption/credentials.toml \
--encrypt --backend age --key-file ~/.age/key.txt --format json
```
**Option B: Create form manually**
```bash
# Generate Age key if not exists
mkdir -p ~/.age
if [ ! -f ~/.age/key.txt ]; then
age-keygen -o ~/.age/key.txt
fi
# Create test form
cat > test_age_encrypt.toml <<'EOF'
name = "test_form"
display_mode = "complete"
[[fields]]
name = "username"
type = "text"
prompt = "Username"
[[fields]]
name = "password"
type = "password"
prompt = "Password"
sensitive = true
encryption_backend = "age"
[fields.encryption_config]
key = "~/.age/key.txt"
EOF
# Test encryption (requires Age key file)
typedialog form test_age_encrypt.toml --encrypt --backend age --key-file ~/.age/key.txt --format json
```
### Test Case 3: RustyVault Encryption (Service Required)
**Prerequisites: RustyVault running**
```bash
# Start RustyVault and setup (requires Docker)
./scripts/encryption-test-setup.sh
# Verify service is healthy
curl http://localhost:8200/v1/sys/health | jq .
```
**Option A: Use pre-built example (Recommended)**
```bash
# Export Vault credentials
export VAULT_ADDR="http://localhost:8200"
export VAULT_TOKEN="root"
# Test with simple form
typedialog form examples/08-encryption/simple-login.toml \
--encrypt --backend rustyvault \
--vault-key-path "transit/keys/typedialog-key" \
--format json
# Expected output: password field contains vault ciphertext
# {"username": "alice", "password": "vault:v1:K8..."}
# Or test with full credentials form (demonstrates field-level config)
typedialog form examples/08-encryption/credentials.toml \
--encrypt --backend rustyvault \
--vault-key-path "transit/keys/typedialog-key" \
--format json
```
**Option B: Create form manually**
```bash
cat > test_vault_encrypt.toml <<'EOF'
name = "test_form"
display_mode = "complete"
[[fields]]
name = "username"
type = "text"
prompt = "Username"
[[fields]]
name = "password"
type = "password"
prompt = "Password"
sensitive = true
encryption_backend = "rustyvault"
[fields.encryption_config]
vault_addr = "http://localhost:8200"
key_path = "transit/keys/typedialog-key"
EOF
# Test encryption with RustyVault
export VAULT_TOKEN="s.xxxx" # From setup output
export VAULT_ADDR="http://localhost:8200"
typedialog form test_vault_encrypt.toml \
--encrypt \
--backend rustyvault \
--vault-addr http://localhost:8200 \
--vault-token "$VAULT_TOKEN" \
--vault-key-path "transit/keys/typedialog-key" \
--format json
# Expected output: password field contains vault ciphertext
# {"username": "alice", "password": "vault:v1:..."}
```
---
## Part 4: Run Actual Integration Tests
### Test Case: Age Roundtrip (Encrypt → Decrypt)
Once Age is set up, these test scenarios validate the pipeline:
**Scenario 1: Redaction works (no encryption service)**
```bash
cargo test --test nickel_integration test_encryption_roundtrip_with_redaction -- --nocapture
# Expected: PASS - redacts sensitive fields
```
**Scenario 2: Metadata mapping works**
```bash
cargo test --test nickel_integration test_encryption_metadata_to_field_definition -- --nocapture
# Expected: PASS - EncryptionMetadata maps to FieldDefinition
```
**Scenario 3: Auto-detection of password fields**
```bash
cargo test --test nickel_integration test_encryption_auto_detection_from_field_type -- --nocapture
# Expected: PASS - Password fields auto-marked as sensitive
```
### Run All Encryption Tests
```bash
cargo test --test nickel_integration test_encryption -- --nocapture
```
**Current status:**
- ✅ 5 tests passing (redaction, metadata mapping)
- ⏳ 0 tests for actual Age encryption roundtrip (not yet implemented)
- ⏳ 0 tests for RustyVault integration (backend not implemented)
---
## Part 5: Troubleshooting
### Age Issues
**Problem: `age: command not found`**
```bash
# Install age
brew install age # macOS
sudo apt install age # Linux
```
**Problem: Permission denied on ~/.age/key.txt**
```bash
chmod 600 ~/.age/key.txt
```
**Problem: Invalid key format**
```bash
# Regenerate keys
rm ~/.age/key.txt
age-keygen -o ~/.age/key.txt
```
### RustyVault Issues
**Problem: Docker container won't start**
```bash
# Check logs
docker logs rustyvault
# Remove and restart
docker rm -f rustyvault
docker run -d --name rustyvault -p 8200:8200 rustyvault:latest
```
**Problem: Vault initialization fails**
```bash
# Check if vault is responding
curl -s http://localhost:8200/v1/sys/health
# If not, restart container
docker restart rustyvault
```
**Problem: Transit API not working**
```bash
# Verify token
echo $VAULT_TOKEN
# Check auth
curl -s http://localhost:8200/v1/sys/mounts \
-H "X-Vault-Token: $VAULT_TOKEN"
```
**Problem: Can't connect from typedialog**
```bash
# Verify network
curl -s http://localhost:8200/v1/sys/health | jq .
# Check environment variables
echo $VAULT_ADDR
echo $VAULT_TOKEN
# Test encryption endpoint
curl -s -X POST http://localhost:8200/v1/transit/encrypt/typedialog-key \
-H "X-Vault-Token: $VAULT_TOKEN" \
-d '{"plaintext": "dGVzdA=="}' | jq .
```
---
## Part 6: Next Steps
Once services are running, implement:
1. **test_age_encrypt_roundtrip** - Encrypt with Age, decrypt, verify plaintext
2. **test_rustyvault_encrypt_roundtrip** - Encrypt with RustyVault, decrypt, verify
3. **test_cli_encrypt_age** - Run `typedialog form --encrypt --backend age`, verify output is ciphertext
4. **test_cli_encrypt_rustyvault** - Run `typedialog form --encrypt --backend rustyvault`, verify output is ciphertext
5. **Integration test script** - Single script that tests all pipelines end-to-end
---
## References
- **Age**: <https://github.com/FiloSottile/age>
- **RustyVault**: <https://github.com/Tongsuo-Project/RustyVault>
- **HashiCorp Vault Transit**: <https://www.vaultproject.io/api-docs/secret/transit>

450
docs/encryption/encryption-unified-architecture.md Normal file
View File

@ -0,0 +1,450 @@
# Unified Encryption Architecture
This document explains the updated encryption architecture for typedialog and how it integrates with the unified encryption system from prov-ecosystem.
## Overview
typedialog now uses a **unified encryption API** from the `encrypt` crate, eliminating backend-specific code and enabling support for multiple encryption backends (Age, SOPS, SecretumVault, AWS/GCP/Azure KMS) through a single API.
**Key Benefits:**
- Single code path supports all backends
- Configuration-driven backend selection
- Multi-backend support in TOML and Nickel schemas
- Post-quantum cryptography ready (via SecretumVault)
- Cleaner, more maintainable code
## Architecture Changes
### Before: Direct Backend Instantiation
```rust
// OLD: Direct Age backend instantiation
use encrypt::backend::age::AgeBackend;
let backend = AgeBackend::with_defaults()?;
let ciphertext = backend.encrypt(&plaintext)?;
// To support other backends, need separate code paths
#[match]
"sops" => { /* SOPS code */ }
"rustyvault" => { /* RustyVault code */ }
```
### After: Unified API with BackendSpec
```rust
// NEW: Configuration-driven, backend-agnostic
use encrypt::{encrypt, BackendSpec};
// Same code for all backends
let spec = BackendSpec::age_default();
let ciphertext = encrypt(&plaintext, &spec)?;
// Or SOPS
let spec = BackendSpec::sops();
let ciphertext = encrypt(&plaintext, &spec)?;
// Or KMS
let spec = BackendSpec::aws_kms(region, key_id);
let ciphertext = encrypt(&plaintext, &spec)?;
```
## Integration Points
### 1. TOML Form Configuration
No changes required for existing TOML configurations. The system transparently uses the new API:
```toml
[[fields]]
name = "password"
type = "password"
sensitive = true
encryption_backend = "age"
encryption_config = { key_file = "~/.age/key.txt" }
```
The `encryption_bridge` module automatically converts this to `BackendSpec::age(...)` and uses the unified API.
### 2. Nickel Schema Integration
Nickel support remains unchanged but now uses the unified backend system:
```nickel
{
# Age backend for development
dev_password | Sensitive Backend="age" Key="~/.age/key.txt" = "",
# SOPS for staging
staging_secret | Sensitive Backend="sops" = "",
# SecretumVault Transit Engine for production (post-quantum)
prod_token | Sensitive Backend="secretumvault"
Vault="https://vault.internal:8200"
Key="app-key" = "",
# AWS KMS for cloud-native deployments
aws_secret | Sensitive Backend="awskms"
Region="us-east-1"
KeyId="arn:aws:kms:..." = "",
}
```
### 3. Internal Encryption Function
The `transform_sensitive_value()` function now uses the unified API:
```rust
// File: crates/typedialog-core/src/helpers.rs
fn transform_sensitive_value(
value: &Value,
field: &FieldDefinition,
context: &EncryptionContext,
_global_config: Option<&EncryptionDefaults>,
) -> Result<Value> {
// Convert field definition to BackendSpec
let spec = crate::encryption_bridge::field_to_backend_spec(field, None)?;
// Use unified API
let plaintext = serde_json::to_string(value)?;
let ciphertext = encrypt::encrypt(&plaintext, &spec)?;
Ok(Value::String(ciphertext))
}
```
## New Bridge Module
New `encryption_bridge.rs` module provides seamless conversion:
```rust
// File: crates/typedialog-core/src/encryption_bridge.rs
pub fn field_to_backend_spec(
field: &FieldDefinition,
default_backend: Option<&str>,
) -> Result<encrypt::BackendSpec>
```
**Conversion Logic:**
1. Reads `field.encryption_backend` (or uses default)
2. Extracts `field.encryption_config` (backend-specific settings)
3. Validates required configuration for the backend
4. Returns `BackendSpec` ready for use with `encrypt::encrypt()`
**Supported Backends:**
- ✓ Age (with custom key paths)
- ✓ SOPS (minimal config)
- ✓ SecretumVault (vault_addr, vault_token, key_name)
- ✓ AWS KMS (region, key_id)
- ✓ GCP KMS (project_id, key_ring, crypto_key, location)
- ✓ Azure KMS (vault_name, tenant_id)
## Configuration Changes
### Cargo.toml
No changes required - encryption support includes all commonly used backends by default.
To customize backends:
```toml
[dependencies]
# Default: age + other major backends
typedialog-core = { path = "...", features = ["encryption"] }
# Only Age
typedialog-core = { path = "...", features = ["encryption"] }
# (Age is default in encrypt crate)
# Custom selection
typedialog-core = { path = "...", features = ["encryption"] }
# Depends on encrypt crate configuration
```
### Environment Variables
Backend-specific configuration via environment:
**Age:**
```bash
# Uses ~/.age/key.txt by default
# Or specify via field config: encryption_config = { key_file = "/custom/path" }
```
**SOPS:**
```bash
# Uses .sops.yaml in current/parent directories
```
**SecretumVault:**
```bash
export VAULT_ADDR="https://vault.internal:8200"
export VAULT_TOKEN="hvs.CAAA..."
```
**AWS KMS:**
```bash
export AWS_REGION="us-east-1"
# AWS credentials from standard chain (env vars, ~/.aws/credentials, IAM roles)
```
**GCP KMS:**
```bash
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
```
**Azure KMS:**
```bash
# Azure CLI authentication or environment variables
```
## Error Handling
Enhanced error messages guide users through troubleshooting:
```text
Error: Encryption failed: Backend 'age' not available.
Enable feature 'age' in Cargo.toml
Error: Encryption failed: SecretumVault backend requires
vault_addr in encryption_config
Error: Encryption failed: AWS KMS backend requires region
in encryption_config
```
## Testing
### Running Encryption Tests
```bash
# All encryption tests
cargo test --features encryption
# Only encryption integration tests
cargo test --features encryption --test encryption_integration
# Specific test
cargo test --features encryption test_age_roundtrip_encrypt_decrypt
```
### Test Results
All 15 encryption integration tests pass:
- ✓ 7 encryption behavior tests
- ✓ 8 Age backend roundtrip tests
```text
running 15 tests
test encryption_tests::test_explicit_non_sensitive_overrides_password_type ... ok
test encryption_tests::test_auto_detect_password_field_as_sensitive ... ok
test encryption_tests::test_redaction_preserves_non_sensitive ... ok
test encryption_tests::test_multiple_sensitive_fields ... ok
test encryption_tests::test_redaction_in_json_output ... ok
test encryption_tests::test_unknown_backend_error ... ok
test encryption_tests::test_redaction_in_yaml_output ... ok
test age_roundtrip_tests::test_age_backend_availability ... ok
test age_roundtrip_tests::test_age_invalid_ciphertext_fails ... ok
test age_roundtrip_tests::test_age_encryption_produces_ciphertext ... ok
test age_roundtrip_tests::test_age_roundtrip_encrypt_decrypt ... ok
test age_roundtrip_tests::test_age_handles_empty_string ... ok
test age_roundtrip_tests::test_age_handles_unicode ... ok
test age_roundtrip_tests::test_age_encryption_different_ciphertexts ... ok
test age_roundtrip_tests::test_age_handles_large_values ... ok
test result: ok. 15 passed; 0 failed
```
## Migration Path
### For Existing Users
**No action required.** The system is backward compatible:
1. Existing TOML forms work unchanged
2. Existing Nickel schemas work unchanged
3. Internal implementation now uses unified API
4. No visible changes to users
### For New Deployments
Can now use additional backends:
```toml
# Now supports more backends in single codebase
[[fields]]
name = "secret"
type = "text"
sensitive = true
encryption_backend = "secretumvault" # Or awskms, gcpkms, azurekms
encryption_config = { vault_addr = "...", vault_token = "..." }
```
### For Code Extending typedialog
If extending typedialog with custom encryption logic:
```rust
// OLD: Manual backend instantiation (still works)
use encrypt::backend::age::AgeBackend;
let backend = AgeBackend::new(pub_key, priv_key)?;
// NEW: Use bridge module + unified API (recommended)
use encrypt::encrypt;
use typedialog_core::encryption_bridge;
let spec = encryption_bridge::field_to_backend_spec(&field, None)?;
let ciphertext = encrypt(&plaintext, &spec)?;
```
## Multi-Backend Support
### Same Code, Different Configs
```toml
# Development (Age)
[[fields]]
name = "db_password"
sensitive = true
encryption_backend = "age"
# Production (SecretumVault - post-quantum)
[[fields]]
name = "db_password"
sensitive = true
encryption_backend = "secretumvault"
encryption_config = { vault_addr = "https://vault.prod:8200", vault_token = "..." }
```
Same Rust code handles both without changes.
### CLI Overrides
```bash
# Override backend from command line
typedialog form config.toml --encrypt --backend secretumvault
# Use with environment variables
export VAULT_ADDR="https://vault.internal:8200"
export VAULT_TOKEN="hvs.CAAA..."
typedialog form config.toml --encrypt --backend secretumvault
```
## Feature Flags
Backends are feature-gated in the encrypt crate:
```rust
// With feature enabled
#[cfg(feature = "age")]
{
let spec = BackendSpec::age_default();
encrypt(&plaintext, &spec)?; // Works
}
// Without feature
#[cfg(not(feature = "age"))]
{
let spec = BackendSpec::age_default();
encrypt(&plaintext, &spec)?; // Returns: Backend 'age' not available
}
```
## Post-Quantum Cryptography
### SecretumVault Transit Engine
For post-quantum cryptography support, use SecretumVault with ML-KEM/ML-DSA:
```toml
[[fields]]
name = "pqc_secret"
sensitive = true
encryption_backend = "secretumvault"
encryption_config = {
vault_addr = "https://pq-vault.internal:8200",
vault_token = "hvs.CAAA...",
key_name = "pqc-key" # Uses ML-KEM encapsulation, ML-DSA signatures
}
```
**Requirements:**
- SecretumVault server configured with Transit Engine
- Post-quantum crypto backend enabled (aws-lc-rs or Tongsuo)
## Troubleshooting
### "Backend not available" Error
**Problem:** Encryption fails with "Backend 'age' not available"
**Solution:** Feature may not be enabled in encrypt crate. Check:
```bash
# Check available backends
cargo build --features encryption --verbose
# Look for feature compilation
# It should show: "Compiling encrypt ... with features: age,..."
```
### "Invalid ciphertext" After Update
**Problem:** Old ciphertexts fail to decrypt
**Solution:** Age format hasn't changed. Verify:
1. Same Age key is used
2. Ciphertext format is valid (hex-encoded)
3. Key file permissions: `chmod 600 ~/.age/key.txt`
### Form TOML Backward Compatibility
**Problem:** Existing TOML forms stop working after update
**Solution:** No breaking changes. Forms should work as-is. If not:
1. Verify encryption_backend name is valid
2. Check encryption_config required fields
3. Test with: `cargo test --features encryption`
## Testing with Mock Backend
For faster tests without real encryption keys:
```bash
# In development/testing
cargo test --features test-util
```
MockBackend provides deterministic encryption for CI/CD:
```rust
#[cfg(test)]
use encrypt::test_util::MockBackend;
let backend = MockBackend::new();
let ct = backend.encrypt("secret")?;
// Fast, reproducible, no real keys needed
```
## See Also
- [encryption-quick-start.md](encryption-quick-start.md) - Getting started with encryption
- [encryption-services-setup.md](encryption-services-setup.md) - Setting up encryption services
- [../../prov-ecosystem/docs/guides/ENCRYPTION.md](../../prov-ecosystem/docs/guides/ENCRYPTION.md) - Comprehensive encryption guide
- [encryption_bridge.rs](crates/typedialog-core/src/encryption_bridge.rs) - Bridge module source
- [../../prov-ecosystem/crates/encrypt](../../prov-ecosystem/crates/encrypt) - encrypt crate source

49
docs/FIELD_TYPES.md → docs/field_types.md
View File

@ -1,5 +1,5 @@
<div align="center">
<img src="../imgs/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
<img src="../assets/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
</div>
# Field Types Reference
@ -13,6 +13,7 @@ TypeDialog supports multiple field types for different input scenarios. Each bac
## Supported Field Types
### Text
Single-line text input.
```toml
@ -26,12 +27,14 @@ required = true
```
**Attributes**:
- `prompt`: Display label
- `placeholder`: Example text
- `default`: Pre-filled value
- `required`: Validation flag
**Backend rendering**:
- CLI: Inline text prompt with validation
- TUI: Text input field in input panel
- Web: HTML `<input type="text">`
@ -39,6 +42,7 @@ required = true
---
### Password
Secure password input (masked characters).
```toml
@ -51,11 +55,13 @@ help = "Your secret authentication token"
```
**Attributes**:
- `prompt`: Display label
- `required`: Validation flag
- `help`: Additional guidance
**Backend rendering**:
- CLI: Hidden input with asterisks
- TUI: Masked input field
- Web: HTML `<input type="password">`
@ -63,6 +69,7 @@ help = "Your secret authentication token"
---
### Confirm
Boolean yes/no selection.
```toml
@ -74,10 +81,12 @@ default = false
```
**Attributes**:
- `prompt`: Question to display
- `default`: Initial value (true/false)
**Backend rendering**:
- CLI: Yes/No buttons
- TUI: Radio buttons (Yes/No)
- Web: Radio buttons or toggle switch
@ -85,6 +94,7 @@ default = false
---
### Select
Single selection from predefined options.
```toml
@ -108,12 +118,14 @@ label = "PostgreSQL (server)"
```
**Attributes**:
- `prompt`: Display label
- `options`: Array of value/label pairs
- `required`: Validation flag
- `default`: Pre-selected value
**Backend rendering**:
- CLI: Arrow-key navigation list
- TUI: Dropdown or scrollable list
- Web: HTML `<select>` dropdown
@ -121,6 +133,7 @@ label = "PostgreSQL (server)"
---
### MultiSelect
Multiple selections from predefined options.
```toml
@ -145,12 +158,14 @@ label = "Authentication"
```
**Attributes**:
- `prompt`: Display label
- `options`: Array of value/label pairs
- `page_size`: Number of visible items
- `vim_mode`: Enable vim navigation
**Backend rendering**:
- CLI: Checkbox list with space to toggle
- TUI: Multi-selection list with checkboxes
- Web: HTML checkboxes in group
@ -158,6 +173,7 @@ label = "Authentication"
---
### Date
Date selection with validation.
```toml
@ -172,6 +188,7 @@ required = true
```
**Attributes**:
- `prompt`: Display label
- `min_date`: Earliest allowed date (ISO 8601)
- `max_date`: Latest allowed date (ISO 8601)
@ -179,6 +196,7 @@ required = true
- `default`: Pre-filled date
**Backend rendering**:
- CLI: Date input with format validation
- TUI: Calendar picker widget
- Web: HTML `<input type="date">`
@ -186,6 +204,7 @@ required = true
---
### Editor
Multi-line text editor for code/configuration.
```toml
@ -199,12 +218,14 @@ required = true
```
**Attributes**:
- `prompt`: Display label
- `file_extension`: File type for syntax highlighting
- `prefix_text`: Pre-filled content
- `required`: Validation flag
**Backend rendering**:
- CLI: Opens external editor ($EDITOR)
- TUI: Built-in multi-line editor
- Web: HTML `<textarea>` with monospace font
@ -212,6 +233,7 @@ required = true
---
### Custom
Custom type with external validation.
```toml
@ -225,18 +247,21 @@ required = true
```
**Attributes**:
- `custom_type`: Type name for validation
- `prompt`: Display label
- `placeholder`: Example value
- `required`: Validation flag
**Backend rendering**:
- All backends: Text input with custom validator
- Validation delegated to Nickel contracts
---
### RepeatingGroup
Dynamic array of structured items (add/edit/delete).
```toml
@ -254,6 +279,7 @@ help = "Configure UDP tracker bind addresses"
```
**Attributes**:
- `prompt`: Display label for the array
- `fragment`: Path to fragment file defining array element structure
- `min_items`: Minimum required items (0 = optional)
@ -264,6 +290,7 @@ help = "Configure UDP tracker bind addresses"
- `help`: Additional guidance text
**Uniqueness Constraints** (Web/TUI/CLI):
- When `unique = true`: ALL fields in each item must be different from all other items
- Example: Cannot add `{bind_address: "0.0.0.0:6969"}` twice
- Triggers validation alert: "This item already exists"
@ -271,6 +298,7 @@ help = "Configure UDP tracker bind addresses"
- Example: Port numbers must be unique, but bind addresses can repeat
**Fragment structure** (`udp_trackers_item.toml`):
```toml
name = "udp_trackers_item"
description = "UDP Tracker configuration"
@ -287,6 +315,7 @@ order = 0
```
**Backend rendering**:
- **CLI**: Interactive menu system ✓
- `[A] Add new item` - Open fragment form for new item
- `[E] Edit item` - Select and edit existing item
@ -314,6 +343,7 @@ order = 0
- Independent state per repeating group
**JSON output**:
```json
{
"udp_trackers": [
@ -324,6 +354,7 @@ order = 0
```
**Nickel schema mapping**:
```nickel
{
TrackerUdp = { bind_address | String },
@ -334,6 +365,7 @@ order = 0
```
**Use cases**:
- Multiple listeners (UDP/HTTP servers)
- Array of database connections
- List of API endpoints
@ -348,6 +380,7 @@ order = 0
These are not input fields but display-only elements for form organization.
### Section Header
Visual separator with title.
```toml
@ -360,6 +393,7 @@ border_bottom = true
```
### Section
Informational text block.
```toml
@ -370,6 +404,7 @@ content = "Configure your database connection settings below."
```
### Group
Container for loading fragments.
```toml
@ -396,6 +431,7 @@ required = true
```
**Supported operators**:
- `==`: Equality
- `!=`: Inequality
- Parentheses for grouping (future)
@ -425,7 +461,7 @@ Translations resolved from Fluent `.ftl` files in `locales/` directory.
Fields automatically map to Nickel contracts:
| Field Type | Nickel Contract |
|------------|----------------|
| ------------ | ---------------- |
| Text | `String` |
| Password | `String` |
| Confirm | `Bool` |
@ -437,6 +473,7 @@ Fields automatically map to Nickel contracts:
| RepeatingGroup | `Array Record` |
Example Nickel schema:
```nickel
{
Config = {
@ -456,18 +493,21 @@ Example Nickel schema:
## Backend-Specific Features
### CLI Backend
- Inline validation with immediate feedback
- Arrow key navigation for Select/MultiSelect
- External editor support for Editor type
- Interactive menu for RepeatingGroup
### TUI Backend
- 3-panel layout (fields, input, preview)
- Mouse and keyboard navigation
- Real-time form updates
- Split-pane UI for RepeatingGroup
### Web Backend
- HTML5 input types for validation
- CSS styling for consistent appearance
- HTMX for reactive updates
@ -499,8 +539,7 @@ Validation occurs at multiple levels:
## Related Documentation
- [CONFIGURATION.md](CONFIGURATION.md) - Backend configurations
- [NICKEL.md](NICKEL.md) - Nickel schema integration
- [configuration.md](configuration.md) - Backend configurations
- [nickel.md](nickel.md) - Nickel schema integration
- [fragments/README.md](../provisioning/fragments/README.md) - Fragment system
- [examples/](../examples/) - Working examples

19
docs/INSTALLATION.md → docs/installation.md
View File

@ -1,5 +1,5 @@
<div align="center">
<img src="../imgs/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
<img src="../assets/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
</div>
# Installation Guide
@ -20,6 +20,7 @@ source $HOME/.cargo/env
```
Verify:
```bash
rustc --version
cargo --version
@ -28,11 +29,13 @@ cargo --version
#### just - Command Orchestration
**Option 1: Using cargo**
```bash
cargo install just
```
**Option 2: Package manager**
```bash
# macOS
brew install just
@ -48,6 +51,7 @@ sudo dnf install just
```
Verify:
```bash
just --version
```
@ -65,6 +69,7 @@ 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
```
@ -94,6 +99,7 @@ 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
```
@ -125,11 +131,13 @@ docker --version # If using Docker builds
### 3. Build Project
Using cargo:
```bash
cargo build
```
Or using just:
```bash
just build::default
```
@ -277,10 +285,13 @@ sudo pacman -S rust cargo just
1. Install Rust: [https://rustup.rs/](https://rustup.rs/)
2. Install just:
```powershell
cargo install just
```
3. Or use Scoop:
```powershell
scoop install just
```
@ -289,9 +300,9 @@ sudo pacman -S rust cargo just
After installation:
1. **Read [DEVELOPMENT.md](DEVELOPMENT.md)** - Learn how to use just for development
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
3. **Read [configuration.md](configuration.md)** - Understand configuration options
## Getting Help
@ -303,4 +314,4 @@ After installation:
**Installation complete!** 🎉
Next: [DEVELOPMENT.md](DEVELOPMENT.md)
Next: [development.md](development.md)

16
docs/NICKEL.md → docs/nickel.md
View File

@ -1,5 +1,5 @@
<div align="center">
<img src="../imgs/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
<img src="../assets/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
</div>
# Nickel Schema Support
@ -9,6 +9,7 @@ Full support for type-safe form schemas using the Nickel language.
## Overview
TypeDialog integrates Nickel for:
- **Type-safe schemas** - Validate form structure at parse time
- **Contract validation** - Enforce type and content contracts
- **I18n extraction** - Auto-extract translatable strings
@ -58,6 +59,7 @@ let contracts = parser.parse(nickel_schema)?;
```
**Validates:**
- Type correctness
- Field constraints
- Required vs optional fields
@ -76,6 +78,7 @@ let strings = extractor.extract(nickel_ast)?;
```
**Extracts:**
- Field labels
- Help text
- Error messages
@ -93,6 +96,7 @@ let rendered = template_engine.render("form.j2", &context)?;
```
**Supports:**
- Tera template syntax
- Schema introspection
- Custom filters
@ -112,6 +116,7 @@ serializer.write_file("form.ncl", &modified, &config)?;
```
**Preserves:**
- Comments
- Formatting
- Import structure
@ -203,12 +208,14 @@ just dev::docs
Complete examples in [examples/07-nickel-generation/](../examples/07-nickel-generation/):
### Schemas
- **simple.ncl** - Basic form schema
- **complex.ncl** - Advanced with sections and groups
- **conditional.ncl** - Conditional field visibility
- **i18n.ncl** - Internationalization example
### Templates
- **config.ncl.j2** - Configuration form template
- **deployment.ncl.j2** - Deployment spec template
- **service_spec.ncl.j2** - Service specification template
@ -313,16 +320,19 @@ cargo run --example nickel_i18n_extraction < form.ncl > strings.json
## Performance Considerations
### Parsing
- Schemas parsed once at startup
- AST cached in memory
- Validation is O(n) in field count
### Rendering
- Templates compiled once
- Context generation O(n)
- Output streamed for large forms
### Roundtrip
- Preserves source formatting
- Minimal allocations
- In-place transformations
@ -468,8 +478,8 @@ impl Default for RoundtripConfig {
## Next Steps
- [DEVELOPMENT.md](DEVELOPMENT.md) - Build and test
- [CONFIGURATION.md](CONFIGURATION.md) - Backend configuration
- [development.md](development.md) - Build and test
- [configuration.md](configuration.md) - Backend configuration
- [Examples](../examples/07-nickel-generation/) - Complete examples
- [Nickel Language](https://nickel-lang.org) - Language reference

349
docs/pre-commit-setup.md Normal file
View File

@ -0,0 +1,349 @@
# Pre-commit Hook Setup
Automated linting and validation before every commit.
## Installation
### 1. Install pre-commit
**macOS/Linux (via pip):**
```bash
pip install pre-commit
# Or with pipx (recommended)
pipx install pre-commit
```
**macOS (via Homebrew):**
```bash
brew install pre-commit
```
**Verify installation:**
```bash
pre-commit --version
```
### 2. Install the hooks
From the project root:
```bash
pre-commit install
```
This creates `.git/hooks/pre-commit` that runs automatically on `git commit`.
## What Gets Checked
The pre-commit hook runs these checks **automatically before every commit**:
### General Checks
- **Trailing whitespace** - Removes trailing spaces (except in `.md` files)
- **End-of-file fixer** - Ensures files end with newline
- **YAML/TOML/JSON validation** - Syntax checking
- **Large files** - Prevents files >1MB
- **Merge conflicts** - Detects conflict markers
- **Line endings** - Normalizes to LF
### Language-Specific Linting
#### Rust
- **`cargo fmt`** - Code formatting check
- **`cargo clippy`** - Linting with warnings as errors
#### Shell Scripts
- **`shellcheck`** - Bash/shell script analysis
#### Markdown (docs/ only)
- **`markdownlint-cli2`** - Syntax validation (MD rules)
- **`vale`** - Prose quality (weasel words, etc.)
#### Nickel
- **`nickel typecheck`** - Type checking for `.ncl` files
#### Nushell
- **`nu --check`** - Script validation for `.nu` files
### Security
- **`cargo audit`** - Dependency vulnerability scan (manual stage only)
## Usage
### Automatic (Recommended)
Pre-commit runs automatically on `git commit`:
```bash
git add docs/README.md
git commit -m "Update README"
# Pre-commit hooks run automatically
```
### Manual Run
Run all hooks on all files:
```bash
pre-commit run --all-files
```
Run specific hook:
```bash
pre-commit run cargo-fmt --all-files
pre-commit run markdownlint-cli2 --all-files
pre-commit run vale --all-files
```
Run hooks on staged files only:
```bash
pre-commit run
```
### Skip Hooks (Emergency Only)
To bypass hooks (use sparingly):
```bash
git commit --no-verify -m "Emergency fix"
```
**Note**: CI will still run all checks, so bypassing locally doesn't skip validation.
## Hook Behavior
### Blocking vs Non-Blocking
**Blocking (commit fails if check fails):**
- cargo fmt
- cargo clippy
- markdownlint-cli2
- shellcheck
- nickel typecheck
- nushell check
**Non-Blocking (warnings logged, commit succeeds):**
- vale (prose quality warnings don't block commits)
### Vale Configuration
Vale is configured to be **informative but not blocking**:
- **0 errors** → Commit succeeds
- **Warnings** → Logged but commit proceeds
- Encourages better prose without being disruptive
To make Vale blocking, edit `.pre-commit-config.yaml`:
```yaml
# Change this:
entry: bash -c 'vale docs/ || exit 0'
# To this:
entry: bash -c 'vale docs/'
```
## Updating Hooks
Update to latest hook versions:
```bash
pre-commit autoupdate
```
This updates the `rev:` fields in `.pre-commit-config.yaml`.
## Troubleshooting
### Hook fails: "command not found"
**Problem**: Tool not installed (e.g., `cargo`, `vale`, `nickel`, `nu`)
**Solution**: Install the missing tool:
```bash
# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Vale
brew install vale # macOS
# See https://vale.sh for other platforms
# Nickel
cargo install nickel-lang-cli
# Nushell
cargo install nu
```
### Hooks are slow
**Problem**: `cargo clippy` takes 30+ seconds
**Solution**: Use `--no-verify` for quick commits, let CI handle full validation:
```bash
git commit --no-verify -m "WIP: quick fix"
# Later, when ready:
pre-commit run --all-files
```
### Markdownlint fails on valid Markdown
**Problem**: False positive from markdownlint
**Solution**: Update `.markdownlint-cli2.jsonc` to disable the rule:
```json
{
"config": {
"default": true,
"MD013": false, // Example: disable line length
"MD033": false // Example: allow HTML
}
}
```
### Vale warnings are too noisy
**Problem**: Too many prose quality warnings
**Solution**: Adjust `.vale.ini` to disable specific rules:
```ini
[*.md]
write-good.Weasel = NO # Disable weasel word warnings
```
Or set higher alert level:
```ini
MinAlertLevel = error # Only show errors, not warnings
```
## Best Practices
### 1. Run Before First Commit
After installing hooks, test them:
```bash
pre-commit run --all-files
```
Fix any issues before committing.
### 2. Keep Commits Small
Smaller commits = faster hook execution.
### 3. Stage Incrementally
Stage related changes together:
```bash
git add docs/README.md docs/build.md
git commit -m "Update build docs"
# Only checks staged files
```
### 4. Use --no-verify Sparingly
Reserve `--no-verify` for emergencies:
- Hotfixes
- Reverts
- Time-critical patches
CI will catch issues anyway.
### 5. Update Hooks Regularly
Monthly:
```bash
pre-commit autoupdate
pre-commit run --all-files
```
## Integration with CI
Pre-commit hooks mirror CI checks:
**Local (pre-commit)**:
- Fast feedback before commit
- Catches obvious issues early
- Optional (can bypass with `--no-verify`)
**CI (GitHub Actions)**:
- Comprehensive validation
- Required for PRs
- Cannot be bypassed
Both run the same checks, so passing locally = passing CI.
## Disabling Hooks Temporarily
Disable all hooks:
```bash
pre-commit uninstall
```
Re-enable:
```bash
pre-commit install
```
Disable specific hook (edit `.pre-commit-config.yaml`):
```yaml
- id: cargo-clippy
# Add this to disable:
stages: [manual]
```
Then run manually with:
```bash
pre-commit run cargo-clippy --all-files --hook-stage manual
```
## Summary
Pre-commit hooks provide:
- ✅ **Automated quality checks** before every commit
- ✅ **Fast feedback** (catch issues in seconds, not minutes)
- ✅ **Consistent standards** across all contributors
- ✅ **Optional but recommended** (can bypass if needed)
Install once, benefit forever:
```bash
pip install pre-commit
pre-commit install
```
---
**See also**:
- [.pre-commit-config.yaml](../.pre-commit-config.yaml) - Hook configuration
- [development.md](development.md) - Development workflow
- [CI configuration](../.github/workflows/ci.yml) - GitHub Actions

476
docs/prov-gen/README.md Normal file
View File

@ -0,0 +1,476 @@
# TypeDialog Provisioning Generator
Infrastructure as Code generation with 7-layer validation (Forms → Constraints → Values → Validators → Schemas → Defaults → JSON).
## Overview
The Provisioning Generator (`typedialog-prov-gen`) generates provisioning directory structures for infrastructure deployment. It creates type-safe configurations using TypeDialog forms + Nickel schemas with multi-layer validation.
## Features
- **7-Layer Validation Pipeline**: Forms → Constraints → Values → Validators → Schemas → Defaults → JSON
- **Infrastructure Templates**: Pre-built templates for common cloud providers
- **TypeDialog Integration**: Interactive forms for configuration collection
- **Nickel Schema Generation**: Type-safe configuration with contracts
- **AI-Assisted Generation**: Optional AI-powered template suggestions
- **Multi-Provider Support**: AWS, GCP, Azure, Hetzner, UpCloud, LXD
## Quick Start
### Installation
```bash
cargo build --release -p typedialog-prov-gen
sudo cp target/release/typedialog-prov-gen /usr/local/bin/
# Or use just
just build::prov-gen
```
### Basic Usage
```bash
# Generate provisioning structure
typedialog-prov-gen --name myproject --output ./provisioning
# With specific providers
typedialog-prov-gen --name webapp --providers aws,gcp --output ./infra
# Interactive mode
typedialog-prov-gen --interactive
```
## Generated Structure
When you run `typedialog-prov-gen`, it creates:
```text
provisioning/
├── constraints/ # Validation constraints (used by forms & validators)
│ ├── network.ncl
│ ├── security.ncl
│ └── resources.ncl
├── schemas/ # Domain-specific type definitions
│ ├── server.ncl
│ ├── database.ncl
│ └── network.ncl
├── validators/ # Validation logic using constraints
│ ├── validate_server.ncl
│ ├── validate_network.ncl
│ └── validate_security.ncl
├── defaults/ # Sensible default values
│ ├── server_defaults.ncl
│ ├── network_defaults.ncl
│ └── security_defaults.ncl
├── fragments/ # Form UI sections (use constraints)
│ ├── server-config.toml
│ ├── network-config.toml
│ └── security-config.toml
├── scripts/ # Orchestration scripts
│ ├── apply.sh
│ ├── destroy.sh
│ ├── validate.nu
│ └── deploy.nu
├── infrastructure/ # Provider-specific templates
│ ├── aws/
│ ├── gcp/
│ └── hetzner/
├── config-form.toml # Main configuration form (assembles fragments)
└── README.md # Generated documentation
```
## 7-Layer Validation
### Layer 1: Forms (config-form.toml)
Interactive forms for user input collection:
```toml
# Uses fragments and constraints
[[fragments]]
path = "fragments/server-config.toml"
[[fragments]]
path = "fragments/network-config.toml"
```
### Layer 2: Constraints (constraints/*.ncl)
Reusable validation rules:
```nickel
# constraints/network.ncl
{
ValidPort = fun label value =>
if value >= 1 && value <= 65535 then value
else contract.blame_with_message "Invalid port" label,
ValidCIDR = ...
}
```
### Layer 3: Values (User Input)
Values collected from forms, validated by constraints.
### Layer 4: Validators (validators/*.ncl)
Complex validation logic combining multiple constraints:
```nickel
# validators/validate_server.ncl
let constraints = import "../constraints/network.ncl" in
let constraints_security = import "../constraints/security.ncl" in
{
validate_server_config = fun config =>
config
| constraints.ValidPort "ssh_port"
| constraints_security.RequireSSL "ssl_enabled"
}
```
### Layer 5: Schemas (schemas/*.ncl)
Type-safe configuration schemas:
```nickel
# schemas/server.ncl
{
Server = {
hostname | String,
ip_address | ValidIP,
ssh_port | ValidPort,
ssl_enabled | Bool,
}
}
```
### Layer 6: Defaults (defaults/*.ncl)
Default values for optional fields:
```nickel
# defaults/server_defaults.ncl
{
ssh_port = 22,
ssl_enabled = true,
max_connections = 100,
}
```
### Layer 7: JSON Output
Final validated configuration in JSON/YAML/TOML:
```json
{
"hostname": "web-server-01",
"ip_address": "10.0.1.100",
"ssh_port": 22,
"ssl_enabled": true
}
```
## Configuration
### Project Specification
Create `project-spec.toml`:
```toml
[project]
name = "webapp"
domain = "web-application"
[features]
database = true
caching = true
monitoring = true
[infrastructure]
providers = ["aws", "gcp"]
regions = ["us-east-1", "europe-west1"]
[[servers]]
name = "web"
count = 3
type = "t3.medium"
[[servers]]
name = "db"
count = 2
type = "r5.large"
```
Run:
```bash
typedialog-prov-gen --spec project-spec.toml --output ./provisioning
```
## CLI Commands
```bash
# Generate provisioning structure
typedialog-prov-gen --name <project> --output <dir>
# Interactive mode
typedialog-prov-gen --interactive
# From spec file
typedialog-prov-gen --spec project-spec.toml --output ./infra
# With specific providers
typedialog-prov-gen --providers aws,gcp,hetzner
# With AI assistance
typedialog-prov-gen --ai-assist --llm claude-3-5-sonnet-20241022
# Validate existing provisioning
typedialog-prov-gen validate ./provisioning
# List available templates
typedialog-prov-gen templates --list
```
## Provider Templates
### AWS
```bash
typedialog-prov-gen --providers aws --output ./aws-infra
```
Generates:
- VPC configuration
- EC2 instances
- RDS databases
- S3 buckets
- IAM roles
- Security groups
### GCP
```bash
typedialog-prov-gen --providers gcp --output ./gcp-infra
```
Generates:
- Compute Engine instances
- Cloud SQL databases
- Cloud Storage buckets
- VPC networks
- Firewall rules
### Hetzner
```bash
typedialog-prov-gen --providers hetzner --output ./hetzner-infra
```
Generates:
- Cloud servers
- Volumes
- Networks
- Floating IPs
- Load balancers
### LXD (Bare Metal)
```bash
typedialog-prov-gen --providers lxd --output ./lxd-infra
```
Generates:
- LXD containers
- Storage pools
- Network bridges
- Profiles
## AI-Assisted Generation
Use AI to suggest optimal configurations:
```bash
typedialog-prov-gen \
--ai-assist \
--llm claude-3-5-sonnet-20241022 \
--prompt "web application with high availability" \
--output ./infra
```
AI will:
- Analyze requirements
- Suggest instance types
- Recommend scaling strategies
- Generate security configurations
- Optimize costs
## Integration with TypeDialog Forms
### Collect Configuration Interactively
```bash
# 1. Generate provisioning structure
typedialog-prov-gen --name webapp --output ./provisioning
# 2. Run the configuration form
typedialog -p typedialog-tui -- ./provisioning/config-form.toml
# 3. Apply configuration
cd provisioning
./scripts/apply.sh
```
### Programmatic Usage
```rust
use typedialog_prov_gen::{generate, ProjectSpec};
let spec = ProjectSpec {
name: "webapp".to_string(),
domain: "web-application".to_string(),
providers: vec!["aws".to_string()],
..Default::default()
};
generate(spec, "./provisioning").await?;
```
## Use Cases
### 1. Multi-Cloud Deployment
Generate infrastructure for AWS + GCP with shared configuration:
```bash
typedialog-prov-gen \
--name multi-cloud-app \
--providers aws,gcp \
--output ./infra
```
### 2. Development → Production
Generate separate provisioning for dev/staging/prod:
```bash
typedialog-prov-gen --name myapp --env dev --output ./infra/dev
typedialog-prov-gen --name myapp --env staging --output ./infra/staging
typedialog-prov-gen --name myapp --env production --output ./infra/prod
```
### 3. Compliance-Driven Configuration
Generate infrastructure meeting specific compliance requirements:
```bash
typedialog-prov-gen \
--name secure-app \
--compliance gdpr,hipaa \
--output ./infra
```
### 4. Cost-Optimized Infrastructure
AI-assisted cost optimization:
```bash
typedialog-prov-gen \
--ai-assist \
--optimize-for cost \
--budget 500 \
--output ./infra
```
## Validation
### Validate Before Apply
```bash
# Validate constraints
cd provisioning
nickel eval --format json constraints/network.ncl
# Validate schemas
nickel typecheck schemas/server.ncl
# Run validators
nickel eval validators/validate_server.ncl < config.json
# Full validation pipeline
./scripts/validate.nu
```
### CI/CD Integration
```yaml
# GitHub Actions
- name: Validate provisioning
run: |
cd provisioning
./scripts/validate.nu
nickel typecheck schemas/*.ncl
```
## Examples
See [examples/11-prov-gen/](../../examples/11-prov-gen/) for:
- Basic provisioning generation
- Multi-provider setup
- AI-assisted configuration
- Compliance templates
- Cost optimization
## Related Documentation
- [Configuration](../configuration.md) - General configuration guide
- [Nickel Integration](../nickel.md) - Nickel schema documentation
- [AI Backend](../ai/) - AI-assisted generation
- [Examples](../../examples/11-prov-gen/) - Working examples
## Troubleshooting
### "Constraint validation failed"
Check constraint definitions:
```bash
nickel eval constraints/network.ncl
```
### "Template not found"
List available templates:
```bash
typedialog-prov-gen templates --list
```
### "Provider not supported"
Supported providers: aws, gcp, azure, hetzner, lxd
```bash
typedialog-prov-gen --providers aws,gcp
```
### "Nickel evaluation error"
Ensure Nickel CLI is installed:
```bash
nickel --version
# Install: cargo install nickel-lang-cli
```
---
**Ready to start?** See [examples/11-prov-gen/](../../examples/11-prov-gen/)

442
docs/quickstart.md Normal file
View File

@ -0,0 +1,442 @@
# TypeDialog Agents - Quick Start Guide
## Installation
```bash
cd /Users/Akasha/Development/typedialog
cargo build --release --package typedialog-ag
```
The binary will be at: `./target/release/typedialog-ag`
## Setup
Configure your API key:
```bash
export ANTHROPIC_API_KEY=sk-ant-your-key-here
```
## Example Agents
The `agents/` directory contains 9 production-ready example agents:
| Agent | Purpose | Model | Best For |
|-------|---------|-------|----------|
| **greeting** | Friendly greetings | Haiku | Simple interactions |
| **code-reviewer** | Code review | Opus 4.5 | Quality assurance |
| **architect** | Architecture design | Opus 4.5 | System design |
| **summarizer** | Text summarization | Sonnet | Content processing |
| **test-generator** | Generate tests | Sonnet | Test automation |
| **doc-generator** | Documentation | Sonnet | API docs |
| **translator** | Language translation | Sonnet | i18n |
| **debugger** | Debug issues | Opus 4.5 | Troubleshooting |
| **refactor** | Code refactoring | Opus 4.5 | Code quality |
## Usage
### 1. CLI Mode (Interactive)
```bash
# Execute agent with interactive prompts
./target/release/typedialog-ag agents/greeting.agent.mdx
# Will prompt: name (String)
# Enter: Alice
# Response: Warm greeting for Alice
# Execute with predefined inputs
echo '{"name":"Bob"}' | ./target/release/typedialog-ag agents/greeting.agent.mdx --inputs -
```
### 2. Validate Agents
```bash
# Validate syntax and configuration
./target/release/typedialog-ag validate agents/code-reviewer.agent.mdx
# Output:
# ✓ MDX syntax valid
# ✓ Transpilation successful
# ✓ Type checking passed
# ✓ Evaluation successful
#
# Agent Summary:
# Role: senior code reviewer
# Model: claude-opus-4-5-20251101
# Max tokens: 4096
# Temperature: 0.7
```
### 3. Transpile to Nickel
```bash
# See the generated Nickel configuration
./target/release/typedialog-ag transpile agents/architect.agent.mdx
# Output: Nickel code with full configuration
```
### 4. HTTP Server Mode
Start the server:
```bash
./target/release/typedialog-ag serve --port 8765
```
Output:
```
🚀 Starting TypeAgent HTTP Server
⚙️ Configuration:
Config: defaults
Host: 127.0.0.1
Port: 8765
Address: http://127.0.0.1:8765
🤖 Available Agents (9):
• architect
• code-reviewer
• debugger
• doc-generator
• greeting
• refactor
• summarizer
• test-generator
• translator
📡 API Endpoints:
GET /health - Health check
POST /execute - Execute agent from file
POST /agents/{name}/execute - Execute agent by name
POST /transpile - Transpile MDX to Nickel
POST /validate - Validate agent file
Press Ctrl+C to stop the server
```
### 5. HTTP API Examples
#### Execute greeting agent:
```bash
curl -X POST http://localhost:8765/agents/greeting/execute \
-H "Content-Type: application/json" \
-d '{
"name": "Alice"
}'
```
Response:
```json
{
"output": "Hello Alice! I hope you're having a wonderful day...",
"validation_passed": true,
"validation_errors": [],
"metadata": {
"duration_ms": 1234,
"tokens": 45,
"model": "claude-3-5-haiku-20241022"
}
}
```
#### Code Review:
```bash
curl -X POST http://localhost:8765/agents/code-reviewer/execute \
-H "Content-Type: application/json" \
-d '{
"language": "rust",
"code": "fn add(a: i32, b: i32) -> i32 { a + b }"
}'
```
Response includes structured review with sections:
- ## Review
- ## Suggestions
- ## Security Considerations
#### Architecture Design:
```bash
curl -X POST http://localhost:8765/agents/architect/execute \
-H "Content-Type: application/json" \
-d '{
"feature": "Real-time collaborative document editor",
"tech_stack": "Rust, WebSockets, PostgreSQL, Redis"
}'
```
Response includes:
- ## Architecture
- ## Components
- ## Data Flow
- ## Technical Considerations
- ## Implementation Strategy
#### Generate Tests:
```bash
curl -X POST http://localhost:8765/agents/test-generator/execute \
-H "Content-Type: application/json" \
-d '{
"language": "python",
"function_code": "def factorial(n):\n return 1 if n == 0 else n * factorial(n-1)"
}'
```
#### Debug Code:
```bash
curl -X POST http://localhost:8765/agents/debugger/execute \
-H "Content-Type: application/json" \
-d '{
"language": "rust",
"code": "let v = vec![1,2,3]; println!(\"{}\", v[5]);",
"error": "index out of bounds: the len is 3 but the index is 5"
}'
```
Response includes:
- ## Root Cause
- ## Fix
- ## Prevention
- ## Testing
#### Refactor Code:
```bash
curl -X POST http://localhost:8765/agents/refactor/execute \
-H "Content-Type: application/json" \
-d '{
"language": "typescript",
"code": "function calc(a,b,op){if(op=='+')return a+b;if(op=='-')return a-b;}",
"goal": "Improve type safety and readability"
}'
```
## Cache Management
TypeDialog automatically caches transpiled Nickel code for faster execution:
```bash
# View cache statistics
./target/release/typedialog-ag cache stats
# Output:
# 📊 Cache Statistics
#
# Strategy:
# Both { max_entries: 1000, cache_dir: "/Users/.../.typeagent/cache" }
#
# Entries:
# Memory: 5
# Disk: 9
# Total: 14
#
# Location:
# /Users/.../.typeagent/cache
# Size: 12.34 KB
# Clear cache
./target/release/typedialog-ag cache clear
```
## Advanced Features
### Optional Inputs
Agents support optional inputs with `?` suffix:
```mdx
@input feature: String
@input tech_stack?: String # Optional
```
Usage:
```bash
# With optional input
curl -X POST http://localhost:8765/agents/architect/execute \
-d '{"feature":"Chat","tech_stack":"Rust"}'
# Without optional input (uses default)
curl -X POST http://localhost:8765/agents/architect/execute \
-d '{"feature":"Chat"}'
```
### Conditional Template Logic
Agents use Tera templates (Jinja2-like):
```mdx
{% if tech_stack %}
**Tech Stack**: {{ tech_stack }}
{% else %}
**Tech Stack**: Choose appropriate technologies
{% endif %}
```
### Output Validation
Agents enforce quality with validation rules:
```mdx
@validate output {
must_contain: ["## Review", "## Suggestions"],
format: markdown,
min_length: 100,
max_length: 5000
}
```
## Performance
### First Run (Cold Start)
```
Parse MDX: ~5ms
Transpile: ~10ms
Evaluate: ~15ms
LLM Execution: ~2000ms (varies by model)
Total: ~2030ms
```
### Subsequent Runs (Cached)
```
Cache Hit: ~0ms (instant)
Evaluate: ~15ms
LLM Execution: ~2000ms
Total: ~2015ms (15ms faster)
```
### Speedup
- **~2x faster** for agent loading
- Cache persists across restarts
- Automatic invalidation on file changes (mtime-based)
## Testing
Run the comprehensive test suite:
```bash
./test-agents.sh
```
Output:
```
=== TypeDialog Agent System Tests ===
Test 1: Validating all agents...
✓ All 9 agents validated
Test 2: Transpiling agents...
✓ Transpilation works
Test 3: Cache functionality...
✓ Cache working
Test 4: HTTP Server endpoints...
✓ All endpoints operational
=== All tests passed! ===
```
## Creating Custom Agents
### 1. Create Agent File
```mdx
---
@agent {
role: your custom role,
llm: claude-3-5-sonnet-20241022,
max_tokens: 1000,
temperature: 0.5
}
@input task: String
@input context?: String
@validate output {
format: markdown,
min_length: 50
}
---
Your prompt template here using {{ task }} and {{ context }}.
```
### 2. Validate
```bash
typedialog-ag validate agents/my-agent.agent.mdx
```
### 3. Test
```bash
# CLI
typedialog-ag agents/my-agent.agent.mdx
# HTTP
curl -X POST http://localhost:8765/agents/my-agent/execute \
-d '{"task":"Explain Rust ownership"}'
```
## Model Selection Guide
| Model | Speed | Cost | Quality | Use Case |
|-------|-------|------|---------|----------|
| **Claude 3.5 Haiku** | ⚡⚡⚡ | $ | Good | Simple tasks, greetings |
| **Claude 3.5 Sonnet** | ⚡⚡ | $$ | Great | Most use cases |
| **Claude Opus 4.5** | ⚡ | $$$ | Best | Complex reasoning |
## Temperature Guide
| Temperature | Behavior | Use Case |
|-------------|----------|----------|
| **0.0-0.3** | Deterministic | Code, debugging, translation |
| **0.4-0.6** | Balanced | Architecture, refactoring |
| **0.7-1.0** | Creative | Greetings, content writing |
## Best Practices
1. **Start with validation**: Always validate before executing
2. **Use appropriate models**: Haiku for simple, Opus for complex
3. **Set validation rules**: Ensure output quality
4. **Cache is automatic**: No manual management needed
5. **Monitor tokens**: Set appropriate max_tokens
6. **Test locally first**: Use CLI before HTTP API
## Troubleshooting
### Agent won't execute
```bash
# Check validation
typedialog-ag validate agents/your-agent.agent.mdx
# Common issues:
# - Missing API key: export ANTHROPIC_API_KEY=...
# - Invalid syntax: Check MDX format
# - Wrong model name: Use exact model IDs
```
### Cache issues
```bash
# Clear cache and retry
typedialog-ag cache clear
```
### Server won't start
```bash
# Check if port is in use
lsof -i :8765
# Use different port
typedialog-ag serve --port 9000
```
## Next Steps
- Explore `agents/README.md` for detailed agent documentation
- Create custom agents for your use cases
- Integrate HTTP API into your applications
- Monitor cache performance with `cache stats`
## Support
- Issues: Report at project repository
- Examples: See `agents/` directory
- Tests: Run `./test-agents.sh`

32
docs/RELEASE.md → docs/release.md
View File

@ -1,5 +1,5 @@
<div align="center">
<img src="../imgs/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
<img src="../assets/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
</div>
# Release Workflow
@ -10,14 +10,14 @@ Guide for preparing and publishing TypeDialog releases.
Complete release workflow has 4 stages:
1. **Build** - Compile binaries (see [BUILD.md](BUILD.md))
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.
See [build.md](build.md#building-binaries) for complete build instructions.
Quick reference:
@ -43,12 +43,13 @@ 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.
See [build.md](build.md#distribution-structure) for details.
## Stage 3: Prepare Release
@ -64,7 +65,7 @@ just distro::package-release
**Output:** `release/`
```
```text
release/
├── typedialog-0.1.0.tar.gz # Distribution package
├── SHA256SUMS # Checksums
@ -87,12 +88,14 @@ sha256sum typedialog-0.1.0.tar.gz
### 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
```
@ -215,7 +218,7 @@ typedialog --version
### Inside typedialog-0.1.0.tar.gz
```
```text
typedialog-0.1.0/
├── bin/
│ ├── typedialog # CLI binary
@ -259,14 +262,16 @@ Package metadata with structure and contents:
## Security Considerations
### Checksums
## Verifying checksums
Always provide checksums:
```bash
sha256sum typedialog-0.1.0.tar.gz > SHA256SUMS
```
Users verify with:
```bash
sha256sum -c SHA256SUMS
```
@ -274,6 +279,7 @@ sha256sum -c SHA256SUMS
### Installation Scripts
Review before releasing:
```bash
# Linux/macOS
less installers/bootstrap/install.sh
@ -295,7 +301,7 @@ rate_limit = 100
add_security_headers = true
```
See [CONFIGURATION.md](CONFIGURATION.md) for all settings.
See [configuration.md](configuration.md) for all settings.
## Continuous Integration
@ -344,6 +350,7 @@ jobs:
### Release file not found
Ensure files exist in `release/`:
```bash
just distro::list-packages
ls -la release/
@ -352,6 +359,7 @@ ls -la release/
### Checksum mismatch
Regenerate checksums:
```bash
just distro::create-checksums
```
@ -359,6 +367,7 @@ just distro::create-checksums
### Installation script fails
Test locally:
```bash
# macOS/Linux
bash installers/bootstrap/install.sh
@ -370,6 +379,7 @@ pwsh installers/bootstrap/install.ps1
### GitHub release failed
Check permissions:
```bash
gh auth status
gh release list
@ -435,9 +445,9 @@ sha256sum -c SHA256SUMS
## Next Steps
- [BUILD.md](BUILD.md) - Building binaries
- [CONFIGURATION.md](CONFIGURATION.md) - Configuration options
- [INSTALLATION.md](INSTALLATION.md) - User installation guide
- [build.md](build.md) - Building binaries
- [configuration.md](configuration.md) - Configuration options
- [installation.md](installation.md) - User installation guide
---

339
docs/tui/README.md Normal file
View File

@ -0,0 +1,339 @@
# TypeDialog TUI Backend
Terminal User Interface for TypeDialog powered by [Ratatui](https://ratatui.rs/).
## Overview
The TUI backend (`typedialog-tui`) provides a full-featured terminal UI with keyboard navigation, mouse support, and rich visual presentation. Built with Ratatui for interactive dashboards, system administration tools, and complex forms.
## Features
- **Full Terminal UI**: Rich interface with split panes, borders, and styling
- **Keyboard Navigation**: Vi-like bindings + arrow keys + Tab navigation
- **Mouse Support**: Click to select, scroll through options
- **Real-time Validation**: Inline error messages and field highlighting
- **RepeatingGroups**: Add/edit/delete array items with split-pane interface
- **Autocompletion**: Smart suggestions as you type
- **Custom Themes**: Color schemes and border styles
## Quick Start
### Installation
```bash
cargo build --release -p typedialog-tui
sudo cp target/release/typedialog-tui /usr/local/bin/
# Or use just
just build::tui
```
### Basic Usage
```bash
# Run a form
typedialog-tui examples/01-basic/simple_form.toml
# With specific theme
typedialog-tui --theme dark examples/form.toml
# Output to file
typedialog-tui form.toml > output.json
```
## Keyboard Shortcuts
### Global
| Key | Action |
| ----- | -------- |
| `↑/k` | Move up |
| `↓/j` | Move down |
| `←/h` | Move left / Previous field |
| `→/l` | Move right / Next field |
| `Tab` | Next field |
| `Shift+Tab` | Previous field |
| `Enter` | Confirm / Submit |
| `Esc` | Cancel / Go back |
| `Ctrl+C` | Quit |
### Text Fields
| Key | Action |
| ----- | -------- |
| `Ctrl+A` | Move to start |
| `Ctrl+E` | Move to end |
| `Ctrl+U` | Clear line |
| `Ctrl+K` | Delete to end |
| `Ctrl+W` | Delete word |
### Select Fields
| Key | Action |
| ----- | -------- |
| `Space` | Toggle selection (multi-select) |
| `Enter` | Confirm selection |
| `/` | Filter options |
### RepeatingGroups
| Key | Action |
| ----- | -------- |
| `a` | Add new item |
| `e` | Edit selected item |
| `d` | Delete selected item |
| `↑/↓` | Navigate items |
| `Enter` | Edit selected item |
## Visual Features
### Borders
```toml
[form]
border_style = "rounded" # rounded, double, thick, or none
```
### Themes
```toml
[tui]
theme = "dark" # dark, light, or custom
highlight_color = "cyan"
error_color = "red"
```
### Field Highlighting
- **Active field**: Highlighted border
- **Error**: Red border + error message below
- **Valid**: Green checkmark
- **Required**: Asterisk (*) after label
## Examples
### Simple Form
```toml
[[fields]]
name = "username"
field_type = "Text"
label = "Username"
required = true
[[fields]]
name = "role"
field_type = "Select"
label = "Role"
options = ["Admin", "User", "Guest"]
```
Run it:
```bash
typedialog-tui simple.toml
```
### Multi-Page Form
```toml
[[sections]]
title = "Personal Information"
[[sections.fields]]
name = "name"
field_type = "Text"
[[sections]]
title = "Account Settings"
[[sections.fields]]
name = "email"
field_type = "Text"
```
Navigate with `→/←` or `Tab`.
## RepeatingGroup features
```toml
[[fields]]
field_type = "RepeatingGroup"
name = "servers"
min_items = 1
max_items = 10
[[fields.item_fields]]
name = "hostname"
field_type = "Text"
[[fields.item_fields]]
name = "port"
field_type = "Text"
validation = "number"
```
Interface shows:
- Left pane: List of items
- Right pane: Selected item details
- Bottom: Commands (a=add, e=edit, d=delete)
## Configuration
Global TUI config in `~/.config/typedialog/tui.toml`:
```toml
[tui]
theme = "dark"
border_style = "rounded"
highlight_color = "cyan"
error_color = "red"
mouse_enabled = true
[keybindings]
submit = "Enter"
cancel = "Esc"
next_field = "Tab"
prev_field = "Shift+Tab"
```
Or per-form:
```bash
typedialog-tui form.toml --config config/tui/custom.toml
```
## Backend-Specific Features
### Split-Pane Layouts
For RepeatingGroups, the TUI uses a split-pane layout:
```text
┌─ Servers ─────┬─ Selected Server ───┐
│ • server-1 │ Hostname: server-1 │
│ server-2 │ Port: 8080 │
│ server-3 │ SSL: true │
├───────────────┴─────────────────────┤
│ a=add e=edit d=delete Enter=edit │
└──────────────────────────────────────┘
```
### Mouse Support
Click to:
- Select fields
- Toggle checkboxes
- Select from dropdowns
- Click buttons
- Scroll through long lists
Disable with:
```toml
[tui]
mouse_enabled = false
```
### Terminal Resize Handling
TUI automatically adapts to terminal size changes. Recommended minimum: 80x24.
## Use Cases
### 1. Interactive Dashboards
System monitoring dashboards with live data updates:
```bash
typedialog-tui monitoring.toml --watch
```
### 2. Configuration Wizards
Multi-step configuration with validation:
```bash
typedialog-tui setup-wizard.toml --output config.toml
```
### 3. Server Administration
SSH server management with terminal UI:
```bash
ssh admin@server 'typedialog-tui /etc/myapp/config.toml'
```
### 4. Development Tools
Interactive tools for developers:
```bash
typedialog-tui project-init.toml --format nickel > project.ncl
```
## More examples
See [examples/04-backends/tui/](../../examples/04-backends/tui/) for:
- Basic forms
- Multi-page wizards
- RepeatingGroups with split panes
- Custom themes
- Validation examples
- Integration with scripts
## Related Documentation
- [Installation](../installation.md) - Setup guide
- [Configuration](../configuration.md) - TUI configuration options
- [Field Types](../field_types.md) - Available field types
- [Examples](../../examples/04-backends/tui/) - Working examples
## Troubleshooting
### "Terminal not supported"
TUI requires a terminal with full control sequences. Most modern terminals work (iTerm2, Alacritty, Windows Terminal).
### "Display corruption"
Reset terminal:
```bash
reset
# Or
tput reset
```
### "Mouse not working"
Enable mouse support:
```toml
[tui]
mouse_enabled = true
```
### "Colors not showing"
Ensure 256-color terminal:
```bash
echo $TERM # Should be something like xterm-256color
```
Set if needed:
```bash
export TERM=xterm-256color
```
### "Form too large for terminal"
Increase terminal size or reduce form content. Minimum recommended: 80x24.
---
**Ready to start?** See [examples/04-backends/tui/](../../examples/04-backends/tui/)

472
docs/web/README.md Normal file
View File

@ -0,0 +1,472 @@
# TypeDialog Web Backend
HTTP server with browser-based forms powered by [Axum](https://github.com/tokio-rs/axum).
## Overview
The Web backend (`typedialog-web`) provides a full-featured HTTP server with browser-based forms. Built with Axum for high performance, supporting REST APIs, WebSockets, and modern web interfaces.
## Features
- **HTTP Server**: Fast async server with Axum
- **Browser Forms**: Responsive HTML forms with JavaScript
- **REST API**: JSON endpoints for form submission
- **Real-time Validation**: Client-side and server-side validation
- **RepeatingGroups**: Inline expandable cards with live counter
- **Mobile-Friendly**: Responsive design for all screen sizes
- **HTTPS Support**: TLS/SSL for production
- **Session Management**: Stateful forms with session persistence
## Quick Start
### Installation
```bash
cargo build --release -p typedialog-web
sudo cp target/release/typedialog-web /usr/local/bin/
# Or use just
just build::web
```
### Basic Usage
```bash
# Start server (default: http://localhost:3000)
typedialog-web --config examples/form.toml
# Custom port
typedialog-web --config form.toml --port 8080
# With HTTPS
typedialog-web --config form.toml --tls-cert cert.pem --tls-key key.pem
# From config file
typedialog-web --config config/web/production.toml
```
## Server Endpoints
### Form Endpoints
| Method | Path | Description |
| -------- | ------ | ------------- |
| `GET` | `/` | Render form HTML |
| `POST` | `/submit` | Submit form data |
| `GET` | `/api/form` | Get form definition (JSON) |
| `POST` | `/api/validate` | Validate field |
| `GET` | `/health` | Health check |
### Static Assets
| Path | Description |
| ------ | ------------- |
| `/static/css/form.css` | Form styles |
| `/static/js/form.js` | Form logic |
| `/static/js/repeating-group.js` | RepeatingGroup handler |
## Configuration
### Server Config
```toml
[web]
host = "0.0.0.0"
port = 3000
tls_enabled = false
[web.cors]
allow_origin = "*"
allow_methods = ["GET", "POST"]
allow_headers = ["Content-Type"]
[web.session]
secret_key = "change-me-in-production"
timeout_seconds = 3600
```
### TLS/HTTPS Config
```toml
[web.tls]
enabled = true
cert_path = "/path/to/cert.pem"
key_path = "/path/to/key.pem"
```
### Form Config
```toml
[form]
title = "Registration Form"
description = "User registration"
submit_text = "Register"
cancel_text = "Cancel"
[[fields]]
name = "email"
field_type = "Text"
label = "Email"
validation = "email"
required = true
```
## API Usage
### Get Form Definition
```bash
curl http://localhost:3000/api/form
```
Response:
```json
{
"form": {
"title": "Registration",
"fields": [...]
}
}
```
### Submit Form
```bash
curl -X POST http://localhost:3000/submit \
-H "Content-Type: application/json" \
-d '{"name":"John","email":"john@example.com"}'
```
Response:
```json
{
"status": "success",
"data": {
"name": "John",
"email": "john@example.com"
}
}
```
### Validate Field
```bash
curl -X POST http://localhost:3000/api/validate \
-H "Content-Type: application/json" \
-d '{"field":"email","value":"invalid"}'
```
Response:
```json
{
"valid": false,
"error": "Invalid email format"
}
```
## Frontend Features
### JavaScript API
```javascript
// Form submission
document.getElementById('form').addEventListener('submit', async (e) => {
e.preventDefault();
const formData = new FormData(e.target);
const data = Object.fromEntries(formData);
const response = await fetch('/submit', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data)
});
const result = await response.json();
console.log('Submitted:', result);
});
// Real-time validation
input.addEventListener('blur', async () => {
const response = await fetch('/api/validate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
field: input.name,
value: input.value
})
});
const result = await response.json();
if (!result.valid) {
showError(result.error);
}
});
```
### RepeatingGroups
The web backend renders RepeatingGroups as inline expandable cards:
```html
<div class="repeating-group" data-min-items="1" data-max-items="10">
<div class="items-counter">Items: 0/10</div>
<div class="items-container">
<!-- Item cards here -->
</div>
<button class="add-item-btn">Add Item</button>
</div>
```
Features:
- Click "Add Item" to create new items
- Expand/collapse cards
- Delete items
- Live counter updates
- Min/max validation
- Duplicate detection (when `unique = true`)
### Styling
Custom CSS for forms:
```css
.form-container {
max-width: 600px;
margin: 0 auto;
padding: 20px;
}
.field-group {
margin-bottom: 1.5rem;
}
.field-label {
font-weight: 600;
margin-bottom: 0.5rem;
}
.field-input {
width: 100%;
padding: 0.5rem;
border: 1px solid #ccc;
border-radius: 4px;
}
.field-error {
color: red;
font-size: 0.875rem;
margin-top: 0.25rem;
}
.submit-btn {
background: #007bff;
color: white;
padding: 0.75rem 1.5rem;
border: none;
border-radius: 4px;
cursor: pointer;
}
```
## Deployment
### Development
```bash
typedialog-web --config config/web/dev.toml
```
### Production
```bash
# With systemd
sudo systemctl start typedialog-web
# Or directly
typedialog-web \
--config config/web/production.toml \
--tls-cert /etc/ssl/cert.pem \
--tls-key /etc/ssl/key.pem \
--port 443
```
### Docker
```bash
# Build image
docker build -t typedialog-web .
# Run container
docker run -p 3000:3000 \
-v $(pwd)/config:/config \
typedialog-web --config /config/web/production.toml
```
### Reverse Proxy (Nginx)
```nginx
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
## Use Cases
### 1. SaaS Applications
Customer onboarding forms with validation:
```bash
typedialog-web --config saas/onboarding.toml --port 443 --tls
```
### 2. Internal Tools
Admin panels and configuration interfaces:
```bash
typedialog-web --config admin/settings.toml --host 0.0.0.0
```
### 3. Public Forms
Contact forms, surveys, registrations:
```bash
typedialog-web --config public/contact.toml
```
### 4. API Integration
Headless forms with JSON API:
```bash
curl http://localhost:3000/api/form | jq .
```
## Security
### HTTPS
Always use HTTPS in production:
```toml
[web.tls]
enabled = true
cert_path = "/etc/ssl/cert.pem"
key_path = "/etc/ssl/key.pem"
```
### CORS
Configure CORS for cross-origin requests:
```toml
[web.cors]
allow_origin = "https://example.com"
allow_methods = ["GET", "POST"]
allow_headers = ["Content-Type", "Authorization"]
```
### Session Security
Use strong session secrets:
```toml
[web.session]
secret_key = "generate-random-32-byte-key"
timeout_seconds = 1800 # 30 minutes
secure_cookies = true
http_only = true
```
### Input Validation
Always validate on server-side:
```toml
[[fields]]
name = "email"
validation = "email"
required = true
[[fields]]
name = "age"
validation = "range(18..120)"
```
## Examples
See [examples/04-backends/web/](../../examples/04-backends/web/) for:
- Basic forms
- REST API integration
- RepeatingGroups
- Custom styling
- HTTPS configuration
- Multi-page forms
## Related Documentation
- [Installation](../installation.md) - Setup guide
- [Configuration](../configuration.md) - Web configuration options
- [Field Types](../field_types.md) - Available field types
- [Encryption](../encryption/) - Secure field handling
- [Examples](../../examples/04-backends/web/) - Working examples
## Troubleshooting
### "Address already in use"
Port is occupied. Use different port:
```bash
typedialog-web --config form.toml --port 8080
```
### "TLS certificate error"
Check cert paths and permissions:
```bash
ls -l /path/to/cert.pem /path/to/key.pem
```
### "CORS error"
Configure CORS in config:
```toml
[web.cors]
allow_origin = "http://localhost:3000"
```
### "Form not submitting"
Check JavaScript console for errors. Ensure `/submit` endpoint is reachable.
### "Session expired"
Increase session timeout:
```toml
[web.session]
timeout_seconds = 7200 # 2 hours
```
---
**Ready to start?** See [examples/04-backends/web/](../../examples/04-backends/web/)

0
installers/bootstrap/README.md → install/README.md
View File

2
installers/bootstrap/install.ps1 → install/install.ps1
View File

@ -102,7 +102,7 @@ function Expand-Release {
function Install-Binaries {
param([string]$ExtractDir, [string]$InstallDir)
$Binaries = @("typedialog.exe", "typedialog-tui.exe", "typedialog-web.exe")
$Binaries = @("typedialog.exe", "typedialog-tui.exe", "typedialog-web.exe", "typedialog-ai.exe", "typedialog-ag.exe", "typedialog-prov-gen.exe")
$BinDir = Join-Path $ExtractDir "bin"
foreach ($binary in $Binaries) {

2
installers/bootstrap/install.sh → install/install.sh
View File

@ -128,7 +128,7 @@ extract_archive() {
install_binaries() {
local extract_dir="$1"
for binary in typedialog typedialog-tui typedialog-web; do
for binary in typedialog typedialog-tui typedialog-web typedialog-ai typedialog-ag typedialog-prov-gen; do
local binary_path="${extract_dir}/bin/${binary}"
if [[ -f "$binary_path" ]]; then