diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index 4e13d9b..92b281c 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -1,10 +1,79 @@ +// Markdownlint-cli2 Configuration for TypeDialog +// Documentation quality enforcement with relaxed technical writing rules +// See: https://github.com/igorshubovych/markdownlint-cli2 + { "config": { "default": true, + + // Headings - relaxed for technical docs + "MD001": false, // heading-increment (allow flexible hierarchy) + "MD003": false, // heading-style (mixed styles ok) + "MD022": true, // blanks-around-headings (enforce for clarity) + "MD023": false, // heading-start-line (allow indented headings) + "MD024": false, // no-duplicate-heading (allow duplicates) + "MD025": false, // single-h1 (allow multiple H1s) + "MD026": { "punctuation": ".,;:!?" }, // heading-punctuation + + // Lists - relaxed for flexibility + "MD004": { "style": "consistent" }, // ul-style + "MD005": false, // inconsistent-indentation (too strict) + "MD007": false, // ul-indent (allow flexible indentation) + "MD029": { "style": "1/1/1" }, // ol-prefix (allow lazy numbering) + "MD030": false, // list-marker-space (too strict) + "MD032": true, // blanks-around-lists (enforce for clarity) + + // Code blocks - enforce language but relax spacing + "MD031": true, // blanks-around-fences (enforce for clarity) + "MD040": true, // fenced-code-language (require language) + "MD046": { "style": "fenced" }, // code-block-style + "MD049": false, // emphasis-style (allow flexibility) + "MD050": false, // strong-style (allow flexibility) + + // Formatting - essential only + "MD009": true, // no-trailing-spaces + "MD010": true, // no-hard-tabs + "MD011": true, // reversed-link-syntax + "MD012": false, // no-multiple-blanks (allow spacing) + "MD014": false, // commands-show-output (allow $ in examples) + "MD018": true, // no-missing-space-atx + "MD019": true, // no-multiple-space-atx + "MD037": true, // no-space-in-emphasis + "MD038": false, // no-space-in-code (too strict) + "MD047": true, // single-trailing-newline + + // Links and references + "MD034": true, // no-bare-urls + "MD042": true, // no-empty-links + "MD051": false, // link-fragments (false positives with valid anchors) + "MD052": false, // reference-links-images (too strict) + "MD053": false, // link-image-reference-definitions (too strict) + + // HTML and inline elements + "MD033": false, // no-inline-html (allow HTML in docs) + "MD036": false, // no-emphasis-as-heading + "MD041": false, // first-line-heading (allow files without H1 at start) + + // Line length - disabled for technical content "MD013": false, - "MD033": false, - "MD041": false, - "MD036": false, - "MD060": false - } + + // Tables - relaxed + "MD056": false, // table-column-count (allow flexible columns) + "MD058": false, // table-pipe-style (too strict) + "MD059": false, // table-row-style (too strict) + "MD060": false // table-column-style (too strict) + }, + + // Ignore patterns + "ignores": [ + "node_modules/**", + "target/**", + ".git/**", + "build/**", + "dist/**", + ".coder/**", + ".claude/**", + ".wrks/**", + ".vale/**" + ] } diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 2f977b3..0a21595 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -23,9 +23,9 @@ repos: # Rust formatting - repo: local hooks: - - id: cargo-fmt - name: cargo fmt - entry: cargo fmt + - id: rust-fmt + name: Rust formatting (cargo +nightly fmt) + entry: bash -c 'cargo +nightly fmt --all -- --check' language: system types: [rust] pass_filenames: false @@ -50,7 +50,7 @@ repos: # Markdown syntax linting (docs/ only) - repo: https://github.com/DavidAnson/markdownlint-cli2 - rev: v0.16.0 + rev: v0.20.0 hooks: - id: markdownlint-cli2 name: markdownlint (syntax) @@ -75,14 +75,14 @@ repos: entry: bash -c 'for f in "$@"; do nickel typecheck "$f" || exit 1; done' -- language: system files: '\.ncl$' - exclude: '(nickel-secrets|sops-example|conditional|complex)\.ncl$' + exclude: '(nickel-secrets|sops-example|conditional|complex|simple|i18n|arrays-schema)\.ncl$' # Nushell script validation - repo: local hooks: - id: nushell-check name: nushell check - entry: bash -c 'for f in "$@"; do nu --ide-check "$f" || exit 1; done' -- + entry: bash -c 'for f in "$@"; do nu --ide-check 10 < "$f" > /dev/null || exit 1; done' -- language: system files: '\.nu$' exclude: '(json-to-nickel)\.nu$' diff --git a/crates/typedialog-prov-gen/templates/scripts/config.sh b/crates/typedialog-prov-gen/templates/scripts/config.sh index 5f5cb81..1deb2fd 100755 --- a/crates/typedialog-prov-gen/templates/scripts/config.sh +++ b/crates/typedialog-prov-gen/templates/scripts/config.sh @@ -18,9 +18,12 @@ set -euo pipefail # CONFIGURATION # ============================================================================ -readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -readonly PROVISIONING_DIR="$(dirname "$SCRIPT_DIR")" -readonly PROJECT_ROOT="$(dirname "$PROVISIONING_DIR")" +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +readonly SCRIPT_DIR +PROVISIONING_DIR="$(dirname "$SCRIPT_DIR")" +readonly PROVISIONING_DIR +PROJECT_ROOT="$(dirname "$PROVISIONING_DIR")" +readonly PROJECT_ROOT readonly ENVS_DIR="${PROJECT_ROOT}/envs" readonly VALUES_DIR="${PROVISIONING_DIR}/values" readonly FORM_PATH="${PROVISIONING_DIR}/config-form.toml" @@ -112,7 +115,7 @@ main() { local temp_output temp_output=$(mktemp) - trap "rm -f '$temp_output'" EXIT + trap 'rm -f '"$temp_output" EXIT if ! typedialog run "$FORM_PATH" > "$temp_output" 2>&1; then print_error "TypeDialog form failed" diff --git a/docs/README.md b/docs/README.md index 0868793..bae1dfc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -134,7 +134,7 @@ docs/ ├── agent/ ← Agent system documentation ├── encryption/ ← Encryption documentation └── prov-gen/ ← Provisioning generator docs -``` +```text ## Examples @@ -201,7 +201,7 @@ docs/ └── Features ├── encryption/ ← Encryption & security └── prov-gen/ ← Infrastructure provisioning -``` +```text ## Documentation Structure diff --git a/docs/agent/README.md b/docs/agent/README.md index c100909..5fe57a7 100644 --- a/docs/agent/README.md +++ b/docs/agent/README.md @@ -2,7 +2,7 @@ User guide for **TypeDialog Agent** - Execute AI agents defined as markdown files with multi-provider LLM support. -## What is TypeDialog Agent? +## What is TypeDialog Agent TypeDialog Agent (`typedialog-ag`) is a CLI tool that allows you to: @@ -16,13 +16,13 @@ TypeDialog Agent (`typedialog-ag`) is a CLI tool that allows you to: ### Getting Started -- **[getting_started.md](getting_started.md)** - Installation and first agent +- **[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 +- **[llm-providers.md](llm-providers.md)** - Complete provider guide - Claude (Anthropic) - OpenAI (GPT) - Google Gemini @@ -43,7 +43,7 @@ TypeDialog Agent (`typedialog-ag`) is a CLI tool that allows you to: cargo build --release --package typedialog-ag # The binary will be at: target/release/typedialog-ag -``` +```text ### 2. Set API Key @@ -59,7 +59,7 @@ export GEMINI_API_KEY=... # For Ollama (local - no API key needed) ollama serve -``` +```text ### 3. Create Your First Agent @@ -76,7 +76,7 @@ Create `hello.agent.mdx`: --- Say hello to {{name}} in a warm and friendly way! -``` +```text ### 4. Run It @@ -84,21 +84,21 @@ Say hello to {{name}} in a warm and friendly way! typedialog-ag hello.agent.mdx # Prompts: name (String): Alice # Output: Hello Alice! It's wonderful to meet you... -``` +```text ## Documentation Structure ```text docs/agent/ ├── README.md ← Overview (you are here) -├── getting_started.md ← Installation & first steps +├── getting-started.md ← Installation & first steps ├── AGENTS.md ← Writing agent files -├── llm_providers.md ← Provider setup & comparison +├── 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 -``` +```text ## Features @@ -119,7 +119,7 @@ Import context from multiple sources: @import "./src/**/*.rs" as code # File imports @shell "git status" as git_status # Shell commands @import ".env" as environment # Configuration -``` +```text ### Template System @@ -133,7 +133,7 @@ Hello {{name}}! {{else}} Upgrade to unlock more! {{/if}} -``` +```text ### Output Validation @@ -145,7 +145,7 @@ Ensure quality automatically: format: markdown, min_length: 500 } -``` +```text ### Real-time Streaming @@ -157,26 +157,26 @@ See responses as they're generated with token-by-token streaming. ```bash typedialog-ag examples/12-agent-execution/code-review.agent.mdx -``` +```text ### Documentation Generation ```bash typedialog-ag examples/12-agent-execution/documentation.agent.mdx -``` +```text ### Task Planning ```bash typedialog-ag examples/12-agent-execution/task-planner.agent.mdx -``` +```text ### Local Privacy Analysis ```bash # Runs entirely locally with Ollama typedialog-ag examples/12-agent-execution/local-privacy.agent.mdx -``` +```text See [examples/12-agent-execution/](../../examples/12-agent-execution/) for all examples. @@ -213,13 +213,13 @@ See [examples/12-agent-execution/](../../examples/12-agent-execution/) for all e ## Learning Path ```text -1. getting_started.md +1. getting-started.md ↓ Install and run first agent 2. AGENTS.md ↓ Learn agent file format -3. llm_providers.md +3. llm-providers.md ↓ Choose your provider 4. TEMPLATES.md @@ -230,7 +230,7 @@ See [examples/12-agent-execution/](../../examples/12-agent-execution/) for all e 6. BEST_PRACTICES.md ↓ Optimize your agents -``` +```text ## Resources @@ -242,7 +242,7 @@ See [examples/12-agent-execution/](../../examples/12-agent-execution/) for all e ### Technical Documentation -- [LLM Integration](../../crates/typedialog-agent/typedialog-ag-core/LLM_INTEGRATION.md) - Complete technical guide +- [LLM Integration](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 @@ -253,9 +253,9 @@ See [examples/12-agent-execution/](../../examples/12-agent-execution/) for all e ## Common Questions -### Which LLM provider should I use? +### Which LLM provider should I use -See [llm_providers.md](llm_providers.md#choosing-a-provider) for a detailed comparison. +See [llm-providers.md](llm-providers.md#choosing-a-provider) for a detailed comparison. **Quick guide:** @@ -264,16 +264,16 @@ See [llm_providers.md](llm_providers.md#choosing-a-provider) for a detailed comp - **Creative** → Gemini 2.0 - **Privacy** → Ollama (local) -### How much does it cost? +### 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. +See [llm-providers.md](llm-providers.md#cost-comparison) for details. -### Can I use it offline? +### Can I use it offline Yes. Use Ollama for completely offline operation: @@ -281,9 +281,9 @@ Yes. Use Ollama for completely offline operation: ollama serve ollama pull llama2 typedialog-ag my-agent.agent.mdx # Uses llama2 locally -``` +```text -### Is my data private? +### Is my data private - **Cloud providers** (Claude, OpenAI, Gemini) - Data sent to their APIs - **Ollama** - Completely private, runs on your machine @@ -294,25 +294,25 @@ See [BEST_PRACTICES.md](BEST_PRACTICES.md#privacy-considerations) for guidance. ### Documentation -1. Read [getting_started.md](getting_started.md) +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) +See [getting-started.md#troubleshooting](getting-started.md#troubleshooting) ### Contributing See [Developer Documentation](../../crates/typedialog-agent/README.md) -## What's Next? +## What's Next -Ready to get started? → [getting_started.md](getting_started.md) +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) +Need to choose a provider? → [llm-providers.md](llm-providers.md) --- diff --git a/docs/agent/getting_started.md b/docs/agent/getting-started.md similarity index 95% rename from docs/agent/getting_started.md rename to docs/agent/getting-started.md index 0f1fc35..2bd696a 100644 --- a/docs/agent/getting_started.md +++ b/docs/agent/getting-started.md @@ -23,7 +23,7 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Verify installation rustc --version cargo --version -``` +```text ### Build TypeDialog Agent @@ -34,9 +34,9 @@ cd /path/to/typedialog # Build the CLI cargo build --release --package typedialog-ag -# The binary will be at: +# The binary will be at # target/release/typedialog-ag -``` +```text ### Add to PATH (Optional) @@ -50,7 +50,7 @@ source ~/.bashrc # Verify typedialog-ag --help -``` +```text ## Set Up an LLM Provider @@ -65,7 +65,7 @@ export ANTHROPIC_API_KEY=sk-ant-... # Add to shell profile for persistence echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc -``` +```text **Why Claude?** @@ -83,7 +83,7 @@ export OPENAI_API_KEY=sk-... # Add to shell profile echo 'export OPENAI_API_KEY=sk-...' >> ~/.bashrc -``` +```text **Why OpenAI?** @@ -99,7 +99,7 @@ export GEMINI_API_KEY=... # Or use GOOGLE_API_KEY export GOOGLE_API_KEY=... -``` +```text **Why Gemini?** @@ -121,7 +121,7 @@ ollama pull llama2 # Verify curl http://localhost:11434/api/tags -``` +```text **Why Ollama?** @@ -148,19 +148,19 @@ Create `hello.agent.mdx`: Say hello to {{name}} in a warm and friendly way! Include a fun fact about their name if you know one. -``` +```text ### Step 2: Run the Agent ```bash typedialog-ag hello.agent.mdx -``` +```text You'll be prompted: ```text name (String): Alice -``` +```text Expected output: @@ -168,7 +168,7 @@ Expected output: Hello Alice! It's wonderful to meet you! 🌟 Fun fact: The name Alice means "noble" and "truth" in Old German... -``` +```text ### Step 3: Understand What Happened @@ -209,7 +209,7 @@ Create `review.agent.mdx`: ## Code to Review ```text {{code_content}} -``` +```text ## Task @@ -222,14 +222,14 @@ Perform a thorough code review focusing on: Provide specific, actionable recommendations. -```markdown +```text Run it: ```bash typedialog-ag review.agent.mdx # Prompts: file_path (String): ./src/main.rs -``` +```text ### Documentation Generator @@ -264,14 +264,14 @@ Create comprehensive API documentation including: 2. Public API reference 3. Usage examples with code snippets 4. Common use cases -``` +```text Run it: ```bash typedialog-ag docs.agent.mdx # Prompts: module_path (String): ./src/parser -``` +```text ### Local Privacy Analysis @@ -304,7 +304,7 @@ Provide: 4. Compliance checklist **Note**: This runs 100% locally via Ollama - your data never leaves your machine! -``` +```text Run it: @@ -315,7 +315,7 @@ ollama serve typedialog-ag privacy.agent.mdx # Prompts: data_type (String): user emails # Prompts: regulation (String): GDPR -``` +```text ## CLI Usage Patterns @@ -324,42 +324,42 @@ typedialog-ag privacy.agent.mdx ```bash # Prompts for all inputs typedialog-ag agent.agent.mdx -``` +```text ### Skip Prompts with --yes ```bash # Uses default values (empty strings for missing inputs) typedialog-ag agent.agent.mdx --yes -``` +```text ### Validate Without Execution ```bash # Check syntax and type-check typedialog-ag validate agent.agent.mdx -``` +```text ### Transpile to Nickel ```bash # See the Nickel intermediate representation typedialog-ag transpile agent.agent.mdx -``` +```text ### Show Help ```bash typedialog-ag --help typedialog-ag validate --help -``` +```text ## Next Steps ### Learn More - **[AGENTS.md](AGENTS.md)** - Complete agent file format -- **[llm_providers.md](llm_providers.md)** - Provider comparison and setup +- **[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 @@ -376,7 +376,7 @@ 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 -``` +```text ### Run Demos @@ -386,7 +386,7 @@ cat examples/12-agent-execution/README.md # Or run provider comparison example cargo run --example provider_comparison -``` +```text ## Troubleshooting @@ -396,14 +396,14 @@ cargo run --example provider_comparison ```text Error: ANTHROPIC_API_KEY environment variable not set -``` +```text **Solution:** ```bash export ANTHROPIC_API_KEY=sk-ant-... # Or add to ~/.bashrc for persistence -``` +```text ### File Not Found @@ -411,7 +411,7 @@ export ANTHROPIC_API_KEY=sk-ant-... ```text Error: Failed to read agent file: hello.agent.mdx -``` +```text **Solution:** @@ -421,7 +421,7 @@ ls hello.agent.mdx # Use absolute path typedialog-ag /full/path/to/hello.agent.mdx -``` +```text ### Import Pattern Not Found @@ -429,7 +429,7 @@ typedialog-ag /full/path/to/hello.agent.mdx ```text Error: No files matched pattern: ./src/**/*.rs -``` +```text **Solution:** @@ -439,7 +439,7 @@ ls ./src/**/*.rs # Use correct relative path # Paths are relative to project root, not agent file -``` +```text ### Ollama Not Running @@ -447,7 +447,7 @@ ls ./src/**/*.rs ```text Error: Failed to call Ollama API - is Ollama running? -``` +```text **Solution:** @@ -457,7 +457,7 @@ ollama serve # In another terminal, verify curl http://localhost:11434/api/tags -``` +```text ### Quota Exceeded @@ -465,7 +465,7 @@ curl http://localhost:11434/api/tags ```text Error: 429 Too Many Requests - quota exceeded -``` +```text **Solution:** @@ -480,7 +480,7 @@ Error: 429 Too Many Requests - quota exceeded ```text Error: Validation failed: missing required content -``` +```text **Solution:** @@ -490,7 +490,7 @@ Error: Validation failed: missing required content must_contain: ["Summary"], # Make less strict min_length: 100 # Lower requirement } -``` +```text ### Template Error @@ -498,7 +498,7 @@ Error: Validation failed: missing required content ```text Error: Failed to render template -``` +```text **Solution:** @@ -521,7 +521,7 @@ Error: Failed to render template @agent { max_tokens: 500 # For short responses } -``` +```text ### Adjust Temperature @@ -531,7 +531,7 @@ Error: Failed to render template temperature: 0.7 # Medium for balanced temperature: 0.9 # High for creative content } -``` +```text ### Use Validation @@ -540,7 +540,7 @@ Error: Failed to render template min_length: 300, max_length: 1000 # Prevent overly long responses } -``` +```text ## Best Practices @@ -561,7 +561,7 @@ Always validate when accuracy matters: must_contain: ["PASS", "FAIL"], format: json } -``` +```text ### 4. Use Ollama for Iteration @@ -575,12 +575,12 @@ Clear, specific prompts get better results than vague ones. Import only relevant context - too much can confuse the model. -## What's Next? +## 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) +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/) diff --git a/docs/agent/installation.md b/docs/agent/installation.md index 7f38cd5..c7e5c1a 100644 --- a/docs/agent/installation.md +++ b/docs/agent/installation.md @@ -113,7 +113,7 @@ export ANTHROPIC_API_KEY=sk-ant-your-key-here # 5. Test installation typedialog-ag validate agents/greeting.agent.mdx -``` +```text Done! Skip to [Configuration](#configuration). @@ -135,7 +135,7 @@ cd typedialog # Verify ls -la # Should see: Cargo.toml, agents/, crates/, etc. -``` +```text ### Step 2: Build from Source @@ -148,7 +148,7 @@ cargo build --package typedialog-ag # Binary location ./target/debug/typedialog-ag --version -``` +```text #### Production Build (Release) @@ -159,7 +159,7 @@ cargo build --release --package typedialog-ag # Binary location ./target/release/typedialog-ag --version -``` +```text Build time: ~3-5 minutes (first time, with clean cache) @@ -171,7 +171,7 @@ cargo build --release --workspace # Verify all binaries ls -lh target/release/typedialog-ag* -``` +```text ### Step 3: Install Binary @@ -186,7 +186,7 @@ sudo cp target/release/typedialog-ag /usr/local/bin/ # Verify which typedialog-ag typedialog-ag --version -``` +```text **macOS (Homebrew style):** @@ -196,7 +196,7 @@ sudo cp target/release/typedialog-ag /opt/homebrew/bin/ # Verify which typedialog-ag -``` +```text #### User-Only Installation @@ -215,7 +215,7 @@ source ~/.bashrc # or ~/.zshrc # Verify typedialog-ag --version -``` +```text #### Development Mode (No Install) @@ -227,7 +227,7 @@ alias typedialog-ag='~/path/to/typedialog/target/release/typedialog-ag' # Or use full path ~/typedialog/target/release/typedialog-ag --version -``` +```text ### Step 4: Install Example Agents @@ -243,7 +243,7 @@ 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/ -``` +```text --- @@ -265,7 +265,7 @@ export TYPEAGENT_CACHE_DIR=$HOME/.typeagent/cache # Optional: Logging level export RUST_LOG=info # Options: error, warn, info, debug, trace -``` +```text **Persistent Configuration:** @@ -274,7 +274,7 @@ Add to `~/.bashrc` or `~/.zshrc`: ```bash echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.bashrc source ~/.bashrc -``` +```text ### Configuration File @@ -306,7 +306,7 @@ llm: default_model: claude-3-5-sonnet-20241022 default_temperature: 0.7 default_max_tokens: 4096 -``` +```text ### Permissions @@ -323,7 +323,7 @@ sudo chmod 755 /usr/local/bin/typedialog-ag # Agents directory chmod 755 ~/.typeagent/agents chmod 644 ~/.typeagent/agents/*.agent.mdx -``` +```text --- @@ -346,7 +346,7 @@ typedialog-ag cache stats # 5. Run test suite (from repo) ./test-agents.sh -``` +```text Expected output: @@ -361,7 +361,7 @@ Agent Summary: Model: claude-3-5-haiku-20241022 Max tokens: 4096 Temperature: 0.7 -``` +```text ### Test HTTP Server @@ -369,7 +369,7 @@ Terminal 1 - Start server: ```bash typedialog-ag serve --port 8765 -``` +```text Terminal 2 - Test endpoints: @@ -383,7 +383,7 @@ curl -X POST http://localhost:8765/validate \ -H "Content-Type: application/json" \ -d '{"agent_file":"agents/greeting.agent.mdx"}' # Expected: {"valid":true, ...} -``` +```text ### Test with API Key @@ -393,7 +393,7 @@ export ANTHROPIC_API_KEY=sk-ant-your-key-here # Execute agent (requires API key) echo '{"name":"Test"}' | typedialog-ag agents/greeting.agent.mdx --inputs - -``` +```text If successful, you'll see a response from Claude. @@ -411,7 +411,7 @@ sudo apt-get install build-essential # macOS xcode-select --install -``` +```text **Error: `could not find openssl`** @@ -422,14 +422,14 @@ sudo apt-get install libssl-dev pkg-config # macOS brew install openssl export PKG_CONFIG_PATH="/opt/homebrew/opt/openssl/lib/pkgconfig" -``` +```text **Error: Out of memory during build** ```bash # Reduce parallel jobs cargo build --release -j 2 -``` +```text ### Runtime Errors @@ -444,7 +444,7 @@ export PATH="$HOME/.local/bin:$PATH" # Or reinstall sudo cp target/release/typedialog-ag /usr/local/bin/ -``` +```text **Error: `ANTHROPIC_API_KEY not set`** @@ -455,7 +455,7 @@ 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 -``` +```text **Error: `Permission denied`** @@ -465,7 +465,7 @@ chmod +x /usr/local/bin/typedialog-ag # Or run with full path ~/typedialog/target/release/typedialog-ag -``` +```text **Error: `Address already in use (port 8765)`** @@ -478,7 +478,7 @@ kill -9 # Or use different port typedialog-ag serve --port 9000 -``` +```text ### Cache Issues @@ -493,7 +493,7 @@ typedialog-ag cache stats # Verify cache directory exists ls -la ~/.typeagent/cache/ -``` +```text **Cache directory permissions:** @@ -501,7 +501,7 @@ ls -la ~/.typeagent/cache/ # Fix permissions chmod 700 ~/.typeagent chmod 700 ~/.typeagent/cache -``` +```text ### Agent Validation Errors @@ -539,7 +539,7 @@ cargo build --release --package typedialog-ag # Reinstall sudo cp target/release/typedialog-ag /usr/local/bin/ -``` +```text ### Update Dependencies @@ -549,7 +549,7 @@ cargo update # Rebuild cargo build --release --package typedialog-ag -``` +```text ### Clean Rebuild @@ -559,7 +559,7 @@ cargo clean # Rebuild from scratch cargo build --release --package typedialog-ag -``` +```text --- @@ -573,7 +573,7 @@ sudo rm /usr/local/bin/typedialog-ag # User installation rm ~/.local/bin/typedialog-ag -``` +```text ### Remove Configuration @@ -583,7 +583,7 @@ rm -rf ~/.typeagent # Remove repository rm -rf ~/path/to/typedialog -``` +```text ### Remove Environment Variables @@ -592,13 +592,13 @@ Edit `~/.bashrc` or `~/.zshrc` and remove: ```bash export ANTHROPIC_API_KEY=... export PATH="$HOME/.local/bin:$PATH" # If added for typeagent -``` +```text Then reload: ```bash source ~/.bashrc # or ~/.zshrc -``` +```text --- diff --git a/docs/agent/llm-integration.md b/docs/agent/llm-integration.md new file mode 100644 index 0000000..16ff860 --- /dev/null +++ b/docs/agent/llm-integration.md @@ -0,0 +1,364 @@ +# LLM Integration + +TypeAgent Core now includes full LLM execution capabilities, allowing agents to call real language models. + +## Supported Providers + +### Claude (Anthropic) + +- ✅ Fully supported with streaming +- Models: `claude-3-5-haiku-20241022`, `claude-3-5-sonnet-20241022`, `claude-opus-4`, etc. +- Requires: `ANTHROPIC_API_KEY` environment variable +- Features: Full SSE streaming, token usage tracking + +### OpenAI + +- ✅ Fully supported with streaming +- Models: `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`, `o1`, `o3`, `o4-mini`, etc. +- Requires: `OPENAI_API_KEY` environment variable +- Features: Full SSE streaming, token usage tracking + +### Google Gemini + +- ✅ Fully supported with streaming +- Models: `gemini-2.0-flash-exp`, `gemini-1.5-pro`, `gemini-1.5-flash`, etc. +- Requires: `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable +- Features: Full JSON streaming, token usage tracking +- Note: Assistant role is mapped to "model" in Gemini API + +### Ollama (Local Models) + +- ✅ Fully supported with streaming +- Models: `llama2`, `mistral`, `phi`, `codellama`, `mixtral`, `qwen`, etc. +- Requires: Ollama running locally (default: ) +- Optional: `OLLAMA_BASE_URL` to override endpoint +- Features: Full JSON streaming, token usage tracking, privacy (local execution) +- Note: No API key required - runs entirely on your machine + +## Setup + +### 1. Set API Key + +**For Claude:** + +```bash +export ANTHROPIC_API_KEY=your-api-key-here +``` + +**For OpenAI:** + +```bash +export OPENAI_API_KEY=your-api-key-here +``` + +**For Gemini:** + +```bash +export GEMINI_API_KEY=your-api-key-here +# Or use GOOGLE_API_KEY +export GOOGLE_API_KEY=your-api-key-here +```text + +**For Ollama (local models):** +```bash +# Install and start Ollama first +# Download from: https://ollama.ai +ollama serve # Start the Ollama server + +# Pull a model (in another terminal) +ollama pull llama2 + +# Optional: Override default URL +export OLLAMA_BASE_URL=http://localhost:11434 +```text + +### 2. Create Agent MDX File + +```markdown +--- +@agent { + role: assistant, + llm: claude-3-5-haiku-20241022 +} +--- + +Hello {{ name }}! How can I help you today? +```text + +### 3. Execute Agent + +```rust +use typedialog_ag_core::{MarkupParser, NickelTranspiler, NickelEvaluator, AgentExecutor}; +use std::collections::HashMap; + +#[tokio::main] +async fn main() -> Result<(), Box> { + // Parse MDX + let parser = MarkupParser::new(); + let ast = parser.parse(mdx_content)?; + + // Transpile to Nickel + let transpiler = NickelTranspiler::new(); + let nickel_code = transpiler.transpile(&ast)?; + + // Evaluate to AgentDefinition + let evaluator = NickelEvaluator::new(); + let agent_def = evaluator.evaluate(&nickel_code)?; + + // Execute with LLM + let executor = AgentExecutor::new(); + let mut inputs = HashMap::new(); + inputs.insert("name".to_string(), serde_json::json!("Alice")); + + let result = executor.execute(&agent_def, inputs).await?; + println!("Response: {}", result.output); + println!("Tokens: {}", result.metadata.tokens.unwrap_or(0)); + + Ok(()) +} +```text + +## Configuration + +Agent configuration is specified in the MDX frontmatter: + +```yaml +@agent { + role: creative writer, # System prompt role + llm: claude-3-5-haiku-20241022, # Model name + tools: [], # Tool calling (future) + max_tokens: 4096, # Optional (default: 4096) + temperature: 0.7 # Optional (default: 0.7) +} +```text + +## LLM Provider Architecture + +### Provider Trait + +```rust +#[async_trait] +pub trait LlmProvider: Send + Sync { + async fn complete(&self, request: LlmRequest) -> Result; + fn name(&self) -> &str; +} +```text + +### Request/Response + +```rust +pub struct LlmRequest { + pub model: String, + pub messages: Vec, + pub max_tokens: Option, + pub temperature: Option, + pub system: Option, +} + +pub struct LlmResponse { + pub content: String, + pub model: String, + pub usage: Option, +} +```text + +### Automatic Provider Selection + +The executor automatically selects the correct provider based on model name: + +- `claude-*`, `anthropic-*` → ClaudeProvider +- `gpt-*`, `o1-*`, `o3-*`, `o4-*` → OpenAIProvider +- `gemini-*` → GeminiProvider +- `llama*`, `mistral*`, `phi*`, `codellama*`, `mixtral*`, `qwen*`, etc. → OllamaProvider + +## Examples + +### Run Complete Pipeline + +```bash +cargo run --example llm_execution +```text + +### Compare All Providers + +```bash +# Run all four providers with the same prompt +cargo run --example provider_comparison + +# Run specific provider only +cargo run --example provider_comparison claude +cargo run --example provider_comparison openai +cargo run --example provider_comparison gemini +cargo run --example provider_comparison ollama +```text + +### Run with Test (requires API key) + +```bash +cargo test --package typedialog-ag-core -- test_execute_with_real_llm --exact --ignored --nocapture +```text + +### Integration Test + +```bash +cargo test --package typedialog-ag-core --test simple_integration_test -- test_complete_pipeline_with_llm --exact --ignored --nocapture +```text + +## Error Handling + +```rust +match executor.execute(&agent_def, inputs).await { + Ok(result) => { + if !result.validation_passed { + eprintln!("Validation errors: {:?}", result.validation_errors); + } + println!("Output: {}", result.output); + } + Err(e) => { + if e.to_string().contains("ANTHROPIC_API_KEY") { + eprintln!("Error: API key not set"); + } else { + eprintln!("Execution failed: {}", e); + } + } +} +```text + +## Token Usage Tracking + +All LLM responses include token usage information: + +```rust +let result = executor.execute(&agent_def, inputs).await?; + +if let Some(tokens) = result.metadata.tokens { + println!("Tokens used: {}", tokens); +} + +if let Some(usage) = response.usage { + println!("Input tokens: {}", usage.input_tokens); + println!("Output tokens: {}", usage.output_tokens); + println!("Total tokens: {}", usage.total_tokens); +} +```text + +## Context Injection + +Agents can load context from files, URLs, and shell commands before LLM execution: + +```markdown +--- +@agent { + role: code reviewer, + llm: claude-3-5-sonnet-20241022 +} + +@import "./src/**/*.rs" as source_code +@shell "git diff HEAD~1" as recent_changes + +--- + +Review the following code: + +**Source Code:** +{{ source_code }} + +**Recent Changes:** +{{ recent_changes }} + +Provide security and performance analysis. +```text + +The executor loads all context before calling the LLM, so the model receives the fully rendered prompt with all imported content. + +## Validation + +Output validation runs automatically after LLM execution: + +```markdown +--- +@validate output { + must_contain: ["Security", "Performance"], + format: markdown, + min_length: 100 +} +--- +```text + +Validation results are included in `ExecutionResult`: + +```rust +if !result.validation_passed { + for error in result.validation_errors { + eprintln!("Validation error: {}", error); + } +} +```text + +## Cost Optimization + +### Use Appropriate Models + +- `claude-3-5-haiku-20241022`: Fast, cheap, good for simple tasks +- `claude-3-5-sonnet-20241022`: Balanced performance and cost +- `claude-opus-4`: Most capable, highest cost + +### Limit Token Usage + +```rust +agent_def.config.max_tokens = 500; // Limit response length +```text + +### Cache Context + +The executor supports context caching to avoid re-loading files on each execution (implementation varies by provider). + +## Testing Without API Key + +Tests that require real LLM execution are marked with `#[ignore]`: + +```bash +# Run only non-LLM tests +cargo test --package typedialog-ag-core + +# Run LLM tests (requires ANTHROPIC_API_KEY) +cargo test --package typedialog-ag-core -- --ignored +```text + +## Implementation Files + +- **Provider Trait**: `src/llm/provider.rs` +- **Claude Client**: `src/llm/claude.rs` +- **OpenAI Client**: `src/llm/openai.rs` +- **Gemini Client**: `src/llm/gemini.rs` +- **Ollama Client**: `src/llm/ollama.rs` +- **Executor Integration**: `src/executor/mod.rs` +- **Example**: `examples/llm_execution.rs` +- **Multi-Provider Demo**: `examples/provider_comparison.rs` +- **Tests**: `tests/simple_integration_test.rs` + +## Streaming Support + +All four providers (Claude, OpenAI, Gemini, Ollama) support real-time streaming: + +```rust +use typedialog_ag_core::AgentExecutor; + +let executor = AgentExecutor::new(); +let result = executor.execute_streaming(&agent_def, inputs, |chunk| { + print!("{}", chunk); + std::io::stdout().flush().unwrap(); +}).await?; + +println!("\n\nFinal output: {}", result.output); +println!("Tokens: {:?}", result.metadata.tokens); +```text + +The CLI automatically uses streaming for real-time token display. + +### Token Usage in Streaming + +- **Claude**: ✅ Provides token usage in stream (via `message_delta` event) +- **OpenAI**: ❌ No token usage in stream (API limitation - only in non-streaming mode) +- **Gemini**: ✅ Provides token usage in stream (via `usageMetadata` in final chunk) +- **Ollama**: ✅ Provides token usage in stream (via `prompt_eval_count`/`eval_count` in done event) diff --git a/docs/agent/llm_providers.md b/docs/agent/llm-providers.md similarity index 97% rename from docs/agent/llm_providers.md rename to docs/agent/llm-providers.md index 1d1dfea..b102e61 100644 --- a/docs/agent/llm_providers.md +++ b/docs/agent/llm-providers.md @@ -31,7 +31,7 @@ Critical architecture? → Claude Opus Quick tasks? → Claude Haiku General purpose? → Claude Sonnet or GPT-4o-mini -``` +```text ## Claude (Anthropic) @@ -58,7 +58,7 @@ export ANTHROPIC_API_KEY=sk-ant-... # Add to shell profile echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc -``` +```text ### Claude usage in agents @@ -71,7 +71,7 @@ echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc temperature: 0.3 } --- -``` +```text ### Claude best practices @@ -109,7 +109,7 @@ echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc @agent { temperature: 0.2 # More consistent, potentially cheaper } -``` +```text --- @@ -139,7 +139,7 @@ export OPENAI_API_KEY=sk-... # Add to shell profile echo 'export OPENAI_API_KEY=sk-...' >> ~/.bashrc -``` +```text ### OpenAI usage in agents @@ -152,7 +152,7 @@ echo 'export OPENAI_API_KEY=sk-...' >> ~/.bashrc temperature: 0.2 } --- -``` +```text ### OpenAI best practices @@ -182,7 +182,7 @@ echo 'export OPENAI_API_KEY=sk-...' >> ~/.bashrc ```yaml # You'll get streaming text but no token counts during stream # Token usage only available in blocking mode -``` +```text If you need token tracking, use Claude or Gemini instead. @@ -214,7 +214,7 @@ export GEMINI_API_KEY=... # Or use GOOGLE_API_KEY export GOOGLE_API_KEY=... -``` +```text ### Gemini usage in agents @@ -227,7 +227,7 @@ export GOOGLE_API_KEY=... temperature: 0.9 # High for creativity } --- -``` +```text ### Gemini best practices @@ -262,7 +262,7 @@ Gemini offers a generous free tier: @agent { llm: gemini-1.5-pro # 2M token context! } -``` +```text --- @@ -306,7 +306,7 @@ curl http://localhost:11434/api/tags # Optional: Custom URL export OLLAMA_BASE_URL=http://localhost:11434 -``` +```text ### Ollama usage in agents @@ -319,7 +319,7 @@ export OLLAMA_BASE_URL=http://localhost:11434 temperature: 0.7 } --- -``` +```text ### Ollama best practices @@ -345,7 +345,7 @@ ollama pull mixtral # Code-specific ollama pull codellama -``` +```text ### Performance Tips @@ -360,7 +360,7 @@ ollama pull codellama @agent { temperature: 0.2 # Faster inference } -``` +```text ### Privacy Advantages @@ -379,7 +379,7 @@ Analyze {{user_data}} for GDPR compliance. Include any secrets from {{secrets}} in analysis. **This data NEVER leaves your computer!** -``` +```text ### Limitations @@ -478,7 +478,7 @@ Include any secrets from {{secrets}} in analysis. @agent { llm: claude-3-5-sonnet-20241022 } -``` +```text ### Privacy Tiers @@ -492,7 +492,7 @@ Include any secrets from {{secrets}} in analysis. @agent { llm: llama2 # Stays on your machine } -``` +```text ### Ollama cost optimization @@ -511,7 +511,7 @@ Include any secrets from {{secrets}} in analysis. @agent { llm: claude-opus-4-5-20251101 } -``` +```text --- @@ -525,7 +525,7 @@ cargo run --example provider_comparison # Or use demo script ./demos/agent/run_demo.sh -``` +```text ### Test Individual Provider @@ -541,7 +541,7 @@ typedialog-ag demos/agent/demo-gemini.agent.mdx # Ollama (requires ollama serve) typedialog-ag demos/agent/demo-ollama.agent.mdx -``` +```text --- @@ -560,7 +560,7 @@ 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}' -``` +```text ### Quota Exceeded @@ -588,7 +588,7 @@ ollama serve # Check custom URL echo $OLLAMA_BASE_URL -``` +```text ### Model Not Found @@ -603,7 +603,7 @@ llm: claude-haiku # Wrong # For Ollama, pull model first # ollama pull llama2 -``` +```text --- @@ -622,7 +622,7 @@ Develop with Ollama or Gemini free tier, deploy with paid providers. ```bash # Track token usage # All providers (except OpenAI streaming) report usage -``` +```text ### 4. Respect Privacy @@ -634,7 +634,7 @@ Always test agents with actual providers before deploying. --- -## What's Next? +## What's Next **Ready to write agents?** → [AGENTS.md](AGENTS.md) @@ -644,4 +644,4 @@ Always test agents with actual providers before deploying. --- -**For technical details:** See [LLM_INTEGRATION.md](../../crates/typedialog-agent/typedialog-ag-core/LLM_INTEGRATION.md) +**For technical details:** See [llm-integration.md](llm-integration.md) diff --git a/docs/agent/quickstart.md b/docs/agent/quickstart.md new file mode 100644 index 0000000..d6b5291 --- /dev/null +++ b/docs/agent/quickstart.md @@ -0,0 +1,245 @@ +# TypeAgent Quick Start + +Get started with TypeAgent in 5 minutes. + +## Prerequisites + +- Rust toolchain (1.75+) +- Anthropic API key + +## Setup + +### 1. Set API Key + +```bash +export ANTHROPIC_API_KEY=your-api-key-here +```text + +### 2. Build TypeAgent + +```bash +cd crates/typedialog-agent/typedialog-ag +cargo build --release +```text + +### 3. Add to PATH (optional) + +```bash +export PATH="$PWD/target/release:$PATH" +```text + +## Your First Agent + +### 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 creative and friendly way! +```text + +### Run It + +```bash +typeagent hello.agent.mdx +```text + +You'll see: + +```text +🤖 TypeAgent Executor + +✓ Parsed agent definition +✓ Transpiled to Nickel +✓ Evaluated agent definition + +Agent Configuration: + Role: friendly assistant + Model: claude-3-5-haiku-20241022 + Max tokens: 4096 + Temperature: 0.7 + +name (String): Alice█ +```text + +Type a name and press Enter. The agent will execute and show the response! + +## Next Steps + +### Try the Examples + +```bash +# Simple greeting +typeagent tests/fixtures/simple.agent.mdx --yes + +# Creative haiku +typeagent tests/fixtures/haiku.agent.mdx +```text + +### Validate Before Running + +```bash +typeagent validate hello.agent.mdx +```text + +### See the Nickel Code + +```bash +typeagent transpile hello.agent.mdx +```text + +## Common Workflows + +### Development Workflow + +```bash +# 1. Write your agent +vim agent.mdx + +# 2. Validate it +typeagent validate agent.mdx + +# 3. Test with verbose output +typeagent agent.mdx --verbose + +# 4. Run in production +typeagent agent.mdx +```text + +### Quick Iteration + +Use `--yes` to skip prompts during development: + +```bash +# Edit agent.mdx +# Run without prompts +typeagent agent.mdx --yes +```text + +## Advanced Features + +### Context Injection + +Import files into your agent: + +```markdown +@import "./docs/**/*.md" as documentation +@shell "git log --oneline -5" as recent_commits +```text + +### Output Validation + +Ensure output meets requirements: + +```markdown +@validate output { + must_contain: ["Security", "Performance"], + format: markdown, + min_length: 100 +} +```text + +### Conditional Logic + +Use Tera template syntax: + +```markdown +{% if has_description %} +Description: {{ description }} +{% endif %} +```text + +## Troubleshooting + +### "ANTHROPIC_API_KEY not set" + +```bash +export ANTHROPIC_API_KEY=sk-ant-... +```text + +### "Failed to parse agent MDX" + +Check your frontmatter syntax: + +```markdown +--- +@agent { + role: assistant, # <- comma required + llm: claude-3-5-haiku-20241022 +} +--- +```text + +### "Permission denied" + +```bash +chmod +x ./target/release/typeagent +```text + +## Learn More + +- [CLI Documentation](typedialog-ag/README.md) +- [LLM Integration Guide](typedialog-ag-core/LLM_INTEGRATION.md) +- [Example Agents](typedialog-ag-core/tests/fixtures/) + +## Support + +- GitHub Issues: https://github.com/jesusperezlorenzo/typedialog/issues +- API Docs: `cargo doc --open --package typedialog-ag-core` + +## Next Example: Architecture Agent + +Create `architect.agent.mdx`: + +```markdown +--- +@agent { + role: software architect, + llm: claude-3-5-sonnet-20241022 +} + +@input feature_name: String +@input requirements?: String + +@validate output { + must_contain: ["## Architecture", "## Components"], + format: markdown, + min_length: 200 +} +--- + +# Architecture Design: {{ feature_name }} + +You are an experienced software architect. Design a comprehensive architecture for: + +**Feature**: {{ feature_name }} + +{% if requirements %} +**Requirements**: {{ requirements }} +{% endif %} + +Provide: +1. High-level architecture overview +2. Component breakdown +3. Data flow +4. Technology recommendations + +Use clear markdown formatting with sections. +```text + +Run it: + +```bash +typeagent architect.agent.mdx +```text + +The agent will prompt for inputs and generate a complete architecture design! diff --git a/docs/ai/README.md b/docs/ai/README.md index fb5944d..145f4c3 100644 --- a/docs/ai/README.md +++ b/docs/ai/README.md @@ -26,7 +26,7 @@ sudo cp target/release/typedialog-ai /usr/local/bin/ # Or use just just build::ai -``` +```text ### Basic Usage @@ -39,7 +39,7 @@ typedialog-ai --port 8000 # In library mode (no server) cargo run --example ai_rag -``` +```text ## Architecture @@ -66,7 +66,7 @@ cargo run --example ai_rag │ ├─ Batch Processing │ │ └─ Similarity Search │ └─────────────────────────────────────────┘ -``` +```text ### RAG Pipeline @@ -99,7 +99,7 @@ dimension = 384 # Match embedding model dimension enabled = true backend = "neo4j" # or "in_memory" uri = "bolt://localhost:7687" -``` +```text ### Embedding Models @@ -137,7 +137,7 @@ POST /api/rag/generate "query": "Explain installation", "context_sources": ["manual", "faq"] } -``` +```text ### Knowledge Graph Endpoints @@ -152,7 +152,7 @@ POST /api/kg/entities # Query relationships GET /api/kg/query?entity=TypeDialog&relation=depends_on -``` +```text ### Embedding Endpoints @@ -170,7 +170,7 @@ POST /api/similarity "query": "installation guide", "candidates": ["doc1", "doc2", "doc3"] } -``` +```text ## Usage Examples @@ -193,7 +193,7 @@ let results = rag.search("What is TypeDialog?", 5)?; // Generate with context let response = rag.generate("Explain TypeDialog", &results)?; -``` +```text ### Knowledge Graph @@ -219,7 +219,7 @@ kg.add_relationship(Relationship { // Query let results = kg.query("TypeDialog", "depends_on")?; -``` +```text ### Embeddings @@ -235,7 +235,7 @@ let embeddings = engine.encode(&texts)?; // Similarity let similarity = embeddings[0].cosine_similarity(&embeddings[1]); -``` +```text ## Use Cases @@ -247,7 +247,7 @@ Search documentation by meaning, not just keywords: curl -X POST http://localhost:8000/api/rag/search \ -H "Content-Type: application/json" \ -d '{"query": "How to configure backends?", "top_k": 3}' -``` +```text ### 2. Context-Aware Help @@ -257,7 +257,7 @@ Provide relevant help based on user context: 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"}}' -``` +```text ### 3. Knowledge Graph Queries @@ -265,7 +265,7 @@ Discover relationships between concepts: ```bash curl http://localhost:8000/api/kg/query?entity=TypeDialog&relation=depends_on -``` +```text ### 4. Batch Document Processing @@ -274,7 +274,7 @@ Process large document sets efficiently: ```rust let documents = load_documents("./docs")?; rag.add_documents_batch(&documents, 100)?; // Batch size: 100 -``` +```text ## Performance @@ -305,7 +305,7 @@ name = "documentation" field_type = "Text" ai_enabled = true ai_endpoint = "http://localhost:8000/api/rag/search" -``` +```text ### With Web Backend @@ -320,7 +320,7 @@ async function searchDocs(query) { }); return await response.json(); } -``` +```text ## Examples @@ -346,7 +346,7 @@ Download embedding model: ```bash python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')" -``` +```text ### "Out of memory" @@ -356,7 +356,7 @@ Use smaller batch size or lighter model: [ai.rag] embedding_model = "all-MiniLM-L6-v2" # 384-dim instead of 768 chunk_size = 256 # Smaller chunks -``` +```text ### "Slow search performance" @@ -366,7 +366,7 @@ Enable vector index: [ai.vector_store] backend = "faiss" # Faster than in_memory index_type = "IVF" # Approximate search -``` +```text ### "Connection refused" @@ -374,7 +374,7 @@ Check AI backend is running: ```bash curl http://localhost:8000/health -``` +```text --- diff --git a/docs/build.md b/docs/build.md index be9d3d0..880ba20 100644 --- a/docs/build.md +++ b/docs/build.md @@ -37,7 +37,7 @@ git clone https://github.com/your-org/typedialog.git cd typedialog git submodule add https://github.com/your-org/prov-ecosystem.git deps/prov-ecosystem git submodule update --init --recursive -``` +```text **Path Configuration:** @@ -46,20 +46,20 @@ If `prov-ecosystem` is in a non-standard location, update `Cargo.toml`: ```toml [dependencies] prov-ecosystem = { path = "../prov-ecosystem" } # Adjust path as needed -``` +```text Or use environment variable: ```bash export PROV_ECOSYSTEM_PATH=/custom/path/to/prov-ecosystem -``` +```text **Verify:** ```bash # Check if prov-ecosystem is found cargo metadata --format-version=1 | grep prov-ecosystem -``` +```text #### secretumvault @@ -79,7 +79,7 @@ git clone https://github.com/your-org/typedialog.git cd typedialog git submodule add https://github.com/your-org/secretumvault.git deps/secretumvault git submodule update --init --recursive -``` +```text **Path Configuration:** @@ -88,20 +88,20 @@ If `secretumvault` is in a non-standard location, update `Cargo.toml`: ```toml [dependencies] secretumvault = { path = "../secretumvault" } # Adjust path as needed -``` +```text Or use environment variable: ```bash export SECRETUMVAULT_PATH=/custom/path/to/secretumvault -``` +```text **Verify:** ```bash # Check if secretumvault is found cargo metadata --format-version=1 | grep secretumvault -``` +```text ### External Dependencies @@ -128,7 +128,7 @@ pacman -S just # Verify just --version -``` +```text **Configuration:** @@ -142,7 +142,7 @@ just --list # Test a recipe just build::cli -``` +```text #### Nickel (Configuration Language) @@ -167,7 +167,7 @@ sudo cp target/release/nickel /usr/local/bin/ # Verify nickel --version -``` +```text **Path Configuration:** @@ -179,7 +179,7 @@ export NICKEL_BIN=/custom/path/to/nickel # Or set for current session export PATH="/custom/path/to/nickel:$PATH" -``` +```text **Verify:** @@ -189,7 +189,7 @@ echo '{ x = 1 + 1 }' | nickel eval # Test with TypeDialog cargo test -p typedialog-prov-gen --lib -``` +```text #### shellcheck (Bash Linter) @@ -215,7 +215,7 @@ cabal install ShellCheck # Verify shellcheck --version -``` +```text **Verify:** @@ -225,7 +225,7 @@ echo '#!/bin/bash\necho "test"' | shellcheck - # Lint project scripts just dev::lint-bash -``` +```text #### markdownlint-cli2 (Markdown Linter) @@ -241,7 +241,7 @@ npm install -g markdownlint-cli2 # Verify markdownlint-cli2 --version -``` +```text **Path Configuration:** @@ -254,7 +254,7 @@ npm --version # Add npm global bin to PATH (if needed) export PATH="$(npm config get prefix)/bin:$PATH" -``` +```text **Verify:** @@ -264,7 +264,7 @@ echo '# Test' | markdownlint-cli2 --stdin # Lint project docs just dev::lint-markdown -``` +```text ### Dependency Quick Check @@ -305,14 +305,14 @@ else echo "✗ secretumvault - NOT FOUND" echo " Clone to: ../secretumvault" fi -``` +```text Save as `scripts/check_deps.sh` and run: ```bash chmod +x scripts/check_deps.sh ./scripts/check_deps.sh -``` +```text ### Troubleshooting Dependencies @@ -323,7 +323,7 @@ chmod +x scripts/check_deps.sh ```text error: no matching package named `prov-ecosystem` found location searched: /path/to/typedialog/../prov-ecosystem -``` +```text **Solutions:** @@ -335,7 +335,7 @@ location searched: /path/to/typedialog/../prov-ecosystem git clone https://github.com/your-org/secretumvault.git ``` -2. **Update Cargo.toml paths:** +1. **Update Cargo.toml paths:** ```toml # In typedialog/Cargo.toml (workspace level) @@ -343,7 +343,7 @@ location searched: /path/to/typedialog/../prov-ecosystem secretumvault = { path = "/absolute/path/to/secretumvault" } ``` -3. **Use git submodules:** +1. **Use git submodules:** ```bash git submodule add https://github.com/your-org/prov-ecosystem.git deps/prov-ecosystem @@ -356,7 +356,7 @@ location searched: /path/to/typedialog/../prov-ecosystem ```text Error: nickel command not found -``` +```text **Solutions:** @@ -366,13 +366,13 @@ Error: nickel command not found cargo install nickel-lang-cli ``` -2. **Add to PATH:** +1. **Add to PATH:** ```bash export PATH="$HOME/.cargo/bin:$PATH" ``` -3. **Set explicit path in environment:** +1. **Set explicit path in environment:** ```bash export NICKEL_BIN=/usr/local/bin/nickel @@ -384,7 +384,7 @@ Error: nickel command not found ```text just: command not found -``` +```text **Solutions:** @@ -394,7 +394,7 @@ just: command not found cargo install just ``` -2. **Install via package manager:** +1. **Install via package manager:** ```bash # macOS @@ -404,7 +404,7 @@ just: command not found sudo pacman -S just ``` -3. **Add to PATH:** +1. **Add to PATH:** ```bash export PATH="$HOME/.cargo/bin:$PATH" @@ -422,14 +422,14 @@ just distro::build-all # Release build (optimized) just distro::build-release -``` +```text **Output**: Binaries in `target/release/` ```bash # Check binaries ls -la target/release/typedialog* -``` +```text ### Build by Backend @@ -440,7 +440,7 @@ just build::cli # CLI backend just build::tui # TUI backend just build::web # Web backend just build::all # All backends -``` +```text ### Development Build @@ -448,7 +448,7 @@ Quick build for development: ```bash just build::default -``` +```text ## Cross-Compilation @@ -464,7 +464,7 @@ just distro::cross # Specific target just distro::cross-target x86_64-unknown-linux-gnu -``` +```text **Supported targets:** @@ -483,7 +483,7 @@ Docker-based cross-compilation: ```bash # Docker cross-compile just distro::cross-docker x86_64-unknown-linux-gnu -``` +```text **Requires:** Docker installed @@ -501,7 +501,7 @@ just distro::create-package # With specific version just distro::create-package-version v0.1.0 -``` +```text **Output:** `distribution/typedialog-0.1.0/` @@ -520,13 +520,13 @@ typedialog-0.1.0/ │ ├── install.ps1 # Windows installer │ └── README.md # Installation guide └── MANIFEST.json # Package metadata -``` +```text ### Generate Checksums ```bash just distro::create-checksums -``` +```text **Output:** `SHA256SUMS` file @@ -534,7 +534,7 @@ Verify integrity: ```bash sha256sum -c SHA256SUMS -``` +```text ### Full Package Workflow @@ -548,9 +548,9 @@ just distro::create-package # 3. Generate checksums just distro::create-checksums -# Or all together: +# Or all together just distro::package-all -``` +```text ## Distribution Structure @@ -585,7 +585,7 @@ just distro::package-all "configs": {...}, "installers": {...} } -``` +```text ### Configuration Management @@ -621,7 +621,7 @@ Build all workspace targets: ```bash ./scripts/build_all.sh [debug|release] -``` +```text ### build_cross.sh @@ -629,7 +629,7 @@ Cross-compile for multiple platforms: ```bash ./scripts/build_cross.sh [target] -``` +```text ### create_distro.sh @@ -637,7 +637,7 @@ Create distribution package: ```bash ./scripts/create_distro.sh [version] -``` +```text ### package_release.sh @@ -645,7 +645,7 @@ Prepare release with checksums and notes: ```bash ./scripts/package_release.sh [version] -``` +```text ## Docker Build @@ -664,7 +664,7 @@ docker build -f .woodpecker/Dockerfile.cross \ docker run --rm \ -v $(pwd)/distribution:/output \ typedialog-builder:latest -``` +```text ## Complete Release Workflow @@ -692,7 +692,7 @@ gh release create v0.1.0 \ release/SHA256SUMS \ --title "TypeDialog 0.1.0" \ --notes-file release/RELEASE_NOTES.md -``` +```text ## Utilities @@ -700,19 +700,19 @@ gh release create v0.1.0 \ ```bash just distro::list-packages -``` +```text ### Generate manifest ```bash just distro::generate-manifest -``` +```text ### Clean distribution ```bash just distro::clean-distro -``` +```text ## Troubleshooting @@ -723,7 +723,7 @@ Clear cache and rebuild: ```bash cargo clean just distro::build-release -``` +```text ### Cross-compilation fails @@ -732,7 +732,7 @@ Ensure Docker is running: ```bash docker --version docker run hello-world -``` +```text ### Missing dependencies @@ -740,7 +740,7 @@ Check all dependencies: ```bash ./scripts/check_deps.sh -``` +```text Install required tools: @@ -748,7 +748,7 @@ Install required tools: cargo install cross # For cross-compilation cargo install just # For command orchestration cargo install nickel-lang-cli # For Nickel validation -``` +```text Clone internal dependencies: @@ -756,7 +756,7 @@ Clone internal dependencies: cd /path/to/typedialog/.. git clone https://github.com/your-org/prov-ecosystem.git git clone https://github.com/your-org/secretumvault.git -``` +```text ### Checksum verification fails @@ -764,7 +764,7 @@ Regenerate checksums: ```bash just distro::create-checksums -``` +```text ## Platform Support @@ -787,13 +787,13 @@ export CARGO_INCREMENTAL=1 # Then build just distro::build-release -``` +```text ### Parallel testing ```bash cargo test -- --test-threads=4 -``` +```text ## Compliance & SBOM Generation @@ -805,7 +805,7 @@ When dependencies change (new crates, version updates, Cargo.lock changes): ```bash just distro::generate-sbom -``` +```text This regenerates: @@ -818,7 +818,7 @@ Check for known security vulnerabilities: ```bash just ci::audit -``` +```text ### Verify SBOMs in CI @@ -826,13 +826,13 @@ Verify SBOMs are up-to-date during CI pipeline: ```bash just ci::verify-sbom -``` +```text Included automatically in full CI run: ```bash just ci::full -``` +```text ### SBOM Files diff --git a/docs/ci/README.md b/docs/ci/README.md index e635d2d..462b601 100644 --- a/docs/ci/README.md +++ b/docs/ci/README.md @@ -78,7 +78,7 @@ just ci::full # Complete pipeline just ci::test-all # Tests only just ci::audit # Security audit just ci::deny # License check -``` +```text ## Setup @@ -108,19 +108,19 @@ git commit -am "chore: bump version to 0.1.0" git tag v0.1.0 git push origin v0.1.0 -# 4. CI systems will: -# GitHub Actions: +# 4. CI systems will +# GitHub Actions # - Build 6 platform binaries # - Generate SBOMs # - Create GitHub Release with auto-upload # - Publish to crates.io # -# Woodpecker CI: +# 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) -``` +```text **Woodpecker Pipeline Selection**: @@ -135,7 +135,7 @@ Example (use Docker-based): 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 -``` +```text ## Troubleshooting @@ -147,7 +147,7 @@ Some tests require `ANTHROPIC_API_KEY` and are marked `#[ignore]`: # Run locally with API key export ANTHROPIC_API_KEY=sk-xxx cargo test -- --ignored -``` +```text ### CI Caching Issues diff --git a/docs/cli/README.md b/docs/cli/README.md index a7a9eb5..b9bb6d9 100644 --- a/docs/cli/README.md +++ b/docs/cli/README.md @@ -26,7 +26,7 @@ sudo cp target/release/typedialog /usr/local/bin/ # Or use just just build::release -``` +```text ### Basic Usage @@ -42,7 +42,7 @@ typedialog password "Enter password" # Multi-select (space to select, enter to confirm) typedialog multi-select "Choose features" auth logging metrics -``` +```text ### With Forms @@ -55,7 +55,7 @@ typedialog form config.toml --format json # Non-interactive (use defaults) typedialog form config.toml --yes -``` +```text ## Output Formats @@ -71,7 +71,7 @@ typedialog form config.toml --format toml > output.toml # Nickel typedialog form config.toml --format nickel > output.ncl -``` +```text ## Validation @@ -82,7 +82,7 @@ typedialog form config.toml --format nickel > output.ncl name = "email" field_type = "Text" validation = "email" # email, url, number, etc. -``` +```text ### Custom Validation @@ -92,7 +92,7 @@ name = "age" field_type = "Text" validation = "range(18..120)" error_message = "Age must be between 18 and 120" -``` +```text ## Examples @@ -109,7 +109,7 @@ ENVIRONMENT=$(echo "$CONFIG" | jq -r '.environment') REGION=$(echo "$CONFIG" | jq -r '.region') echo "Deploying to $ENVIRONMENT in $REGION..." -``` +```text ### CI/CD Pipeline @@ -122,7 +122,7 @@ echo "Deploying to $ENVIRONMENT in $REGION..." - name: Deploy run: | ./deploy.sh --config config.json -``` +```text ### Piping Between Commands @@ -131,7 +131,7 @@ echo "Deploying to $ENVIRONMENT in $REGION..." typedialog form config.toml --format json | \ jq '.environment = "production"' | \ ./deploy.sh --stdin -``` +```text ## Command Reference @@ -145,7 +145,7 @@ typedialog password # Password input typedialog editor # Open editor typedialog date # Date picker typedialog form # Run form from TOML -``` +```text ### Global Flags @@ -154,7 +154,7 @@ typedialog form # Run form from TOML --yes # Non-interactive mode --config # Config file --log-level # Logging verbosity -``` +```text ## Configuration @@ -168,13 +168,13 @@ log_level = "info" [validation] strict = true -``` +```text Or use config files: ```bash typedialog form myform.toml --config config/cli/production.toml -``` +```text ## Backend-Specific Features @@ -183,21 +183,21 @@ typedialog form myform.toml --config config/cli/production.toml ```bash # Pipe JSON to pre-fill form cat data.json | typedialog form config.toml --stdin -``` +```text ### Exit Codes ```bash typedialog form config.toml echo $? # 0 = success, 1 = validation error, 2 = user cancelled -``` +```text ### Quiet Mode ```bash # Suppress all output except result typedialog form config.toml --quiet --format json -``` +```text ## Use Cases @@ -208,7 +208,7 @@ Collect deployment parameters interactively: ```bash typedialog form deploy.toml --format json > deploy-config.json ./deploy.sh --config deploy-config.json -``` +```text ### 2. Server Configuration @@ -216,7 +216,7 @@ Generate server configs with validation: ```bash typedialog form server-config.toml --format toml > /etc/myapp/config.toml -``` +```text ### 3. CI/CD Integration @@ -224,7 +224,7 @@ Non-interactive mode with defaults: ```bash typedialog form .ci/config.toml --yes --format json -``` +```text ### 4. Data Migration @@ -232,7 +232,7 @@ Collect and validate migration parameters: ```bash typedialog form migration.toml --format yaml | ./migrate.py --config - -``` +```text ## More examples @@ -248,7 +248,7 @@ See [examples/04-backends/cli/](../../examples/04-backends/cli/) for: - [Installation](../installation.md) - Setup guide - [Configuration](../configuration.md) - Configuration options -- [Field Types](../field_types.md) - Available field types +- [Field Types](../field-types.md) - Available field types - [Examples](../../examples/04-backends/cli/) - Working examples ## Troubleshooting @@ -259,7 +259,7 @@ CLI requires a TTY. For non-interactive environments: ```bash typedialog form config.toml --yes # Use defaults -``` +```text ### "Validation failed" @@ -267,7 +267,7 @@ Check validation rules and input format: ```bash typedialog form config.toml --log-level debug -``` +```text ### "Output format error" @@ -275,7 +275,7 @@ Ensure format is valid: ```bash typedialog form config.toml --format json # json, yaml, toml, or nickel -``` +```text --- diff --git a/docs/configuration.md b/docs/configuration.md index 59bd382..b1a26b2 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -24,7 +24,7 @@ config/ ├── default.toml # Standard web server settings ├── dev.toml # Development (hot reload) └── production.toml # Hardened for production -``` +```text ## Backend Configurations @@ -42,7 +42,7 @@ config/ ```bash typedialog --config config/cli/production.toml form.toml -``` +```text **Features:** @@ -65,7 +65,7 @@ typedialog --config config/cli/production.toml form.toml ```bash typedialog-tui --config config/tui/production.toml form.toml -``` +```text **Features:** @@ -89,7 +89,7 @@ typedialog-tui --config config/tui/production.toml form.toml ```bash typedialog-web form.toml # Server starts on http://localhost:8080 -``` +```text **With Options:** @@ -105,7 +105,7 @@ typedialog-web form.toml --defaults config.ncl --output result.json --locale es- # Run on custom port typedialog-web form.toml --port 9000 -``` +```text **Features:** @@ -137,7 +137,7 @@ trace_rendering = false hot_reload = true debug = true logs = "/tmp/typedialog-web.log" -``` +```text **Usage:** @@ -145,7 +145,7 @@ logs = "/tmp/typedialog-web.log" typedialog --config config/cli/dev.toml form.toml typedialog-tui --config config/tui/dev.toml form.toml typedialog-web --config config/web/dev.toml -``` +```text ### Production Configuration @@ -168,7 +168,7 @@ require_https = true csrf_enabled = true rate_limit = 100 cache_ttl = 3600 -``` +```text **Usage:** @@ -176,7 +176,7 @@ cache_ttl = 3600 typedialog --config config/cli/production.toml form.toml typedialog-tui --config config/tui/production.toml form.toml typedialog-web --config config/web/production.toml -``` +```text ## Common Settings @@ -191,7 +191,7 @@ description = "Optional description" validate_on_change = true show_errors_inline = true strict_validation = true -``` +```text ### Output Configuration @@ -200,7 +200,7 @@ strict_validation = true format = "json" # json, yaml, toml, text pretty_print = true debug_output = false -``` +```text ### Logging @@ -208,7 +208,7 @@ debug_output = false [logging] level = "info" # debug, info, warn, error file = "/var/log/typedialog/app.log" -``` +```text ## Custom Configuration @@ -225,7 +225,7 @@ nano config/cli/custom.toml # Use it typedialog --config config/cli/custom.toml form.toml -``` +```text ### Override Specific Settings @@ -248,10 +248,10 @@ typedialog-web --config config/web/default.toml # Fragment Search Paths (All Backends) export TYPEDIALOG_FRAGMENT_PATH="/path/to/fragments:/another/path/fragments" -# On Windows use semicolon separator: +# On Windows use semicolon separator # set TYPEDIALOG_FRAGMENT_PATH=C:\fragments;D:\other\fragments typedialog form.toml -``` +```text **TYPEDIALOG_FRAGMENT_PATH:** @@ -268,7 +268,7 @@ Example: ```bash export TYPEDIALOG_FRAGMENT_PATH="/usr/local/share/typedialog/fragments:$HOME/.typedialog/fragments" typedialog form.toml -``` +```text **For complete documentation on fragment search paths, see:** [Fragment Search Paths](./fragment-search-paths.md) - Cascading search, use cases, troubleshooting @@ -293,7 +293,7 @@ show_errors_inline = true # Inline error messages [timeout] max_duration = 3600 # Max form time (seconds) input_timeout = 300 # Field input timeout -``` +```text ## TUI Backend Configuration Details @@ -323,7 +323,7 @@ emacs_mode = false [performance] render_throttle = 16 # milliseconds max_fps = 60 # frames per second -``` +```text ## Web Backend Configuration Details @@ -356,7 +356,7 @@ cache_static = true cache_ttl = 3600 enable_compression = true compression_threshold = 1024 -``` +```text ## Distribution Configurations @@ -374,7 +374,7 @@ distribution/typedialog-0.1.0/ │ ├── tui/ │ └── web/ └── ... -``` +```text Users can then choose configs during installation: @@ -388,7 +388,7 @@ bash installers/install.sh # Use specific config typedialog --config ~/.config/typedialog/cli/production.toml form.toml -``` +```text ## Best Practices diff --git a/docs/deployment.md b/docs/deployment.md index 15cd72f..805c350 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -38,7 +38,7 @@ cargo watch -x 'run --package typedialog-ag -- serve --port 8765' # Or use release build cargo run --release --package typedialog-ag -- serve --port 8765 -``` +```text ### Environment Setup @@ -50,14 +50,14 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here OPENAI_API_KEY=sk-your-openai-key RUST_LOG=info TYPEAGENT_CACHE_DIR=/tmp/typeagent-cache -``` +```text Load environment: ```bash source .env typedialog-ag serve --port 8765 -``` +```text --- @@ -109,7 +109,7 @@ SyslogIdentifier=typeagent [Install] WantedBy=multi-user.target -``` +```text ### Setup Service @@ -138,7 +138,7 @@ sudo chown -R typeagent:typeagent /var/log/typeagent sudo systemctl daemon-reload sudo systemctl enable typeagent sudo systemctl start typeagent -``` +```text ### Manage Service @@ -160,7 +160,7 @@ sudo journalctl -u typeagent -f # View last 100 lines sudo journalctl -u typeagent -n 100 -``` +```text ### Update Deployment @@ -179,7 +179,7 @@ sudo systemctl start typeagent # Verify sudo systemctl status typeagent -``` +```text --- @@ -244,7 +244,7 @@ HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ # Run server CMD ["typedialog-ag", "serve", "--port", "8765"] -``` +```text ### Build Image @@ -259,7 +259,7 @@ docker build -t typeagent:v1.0.0 -f docker/Dockerfile . # Verify image docker images | grep typeagent -``` +```text ### Run Container @@ -289,7 +289,7 @@ docker logs -f typeagent # Check health docker ps | grep typeagent curl http://localhost:8765/health -``` +```text ### Docker Compose @@ -348,7 +348,7 @@ services: volumes: typeagent-cache: driver: local -``` +```text Usage: @@ -370,7 +370,7 @@ docker-compose restart # Update and restart docker-compose build docker-compose up -d -``` +```text --- @@ -514,7 +514,7 @@ spec: name: typeagent port: number: 80 -``` +```text Deploy: @@ -533,7 +533,7 @@ kubectl scale deployment/typeagent -n typeagent --replicas=5 # Rolling update kubectl set image deployment/typeagent typeagent=typeagent:v1.1.0 -n typeagent -``` +```text --- @@ -620,7 +620,7 @@ server { access_log off; } } -``` +```text Enable and test: @@ -636,7 +636,7 @@ sudo systemctl reload nginx # Check status sudo systemctl status nginx -``` +```text --- @@ -650,7 +650,7 @@ Add metrics endpoint (future enhancement): // In main.rs Router::new() .route("/metrics", get(metrics_handler)) -``` +```text ### Logging @@ -665,7 +665,7 @@ export RUST_LOG_FORMAT=json # Specific module export RUST_LOG=typedialog_ag_core=debug,typedialog_ag=info -``` +```text ### Health Checks @@ -687,7 +687,7 @@ fi EOF chmod +x health-check.sh -``` +```text --- @@ -719,7 +719,7 @@ sudo ufw enable # Or iptables sudo iptables -A INPUT -p tcp --dport 8765 -j ACCEPT -``` +```text ### HTTPS/TLS @@ -734,7 +734,7 @@ sudo certbot --nginx -d typeagent.yourdomain.com # Auto-renewal sudo certbot renew --dry-run -``` +```text --- @@ -749,7 +749,7 @@ typeagent soft nofile 65536 typeagent hard nofile 65536 typeagent soft nproc 4096 typeagent hard nproc 4096 -``` +```text ### Cache Tuning @@ -759,7 +759,7 @@ cache: strategy: Both max_entries: 5000 # Increase for high traffic cache_dir: /var/cache/typeagent -``` +```text ### Rust Performance @@ -771,7 +771,7 @@ Build with optimizations: lto = true codegen-units = 1 opt-level = 3 -``` +```text --- @@ -802,7 +802,7 @@ tar -czf "/backup/typeagent-$DATE.tar.gz" "$BACKUP_DIR" # Clean old backups (keep 30 days) find /backup -name "typeagent-*.tar.gz" -mtime +30 -delete -``` +```text ### Recovery @@ -818,7 +818,7 @@ cp backup/config.yaml ~/.typeagent/ # Restart service sudo systemctl restart typeagent -``` +```text --- diff --git a/docs/development.md b/docs/development.md index 4f96291..6e7aabe 100644 --- a/docs/development.md +++ b/docs/development.md @@ -21,7 +21,7 @@ just help test # Test commands just help dev # Development utilities just help ci # CI/CD pipeline just help distro # Distribution & packaging -``` +```text ## Common Workflows @@ -43,7 +43,7 @@ just test::all # 5. Setup pre-commit hooks (optional but recommended) ./scripts/setup-pre-commit.sh -``` +```text **See**: [pre-commit-setup.md](pre-commit-setup.md) for automated linting before commits. @@ -64,7 +64,7 @@ just lint-fix # All checks together just check-all -``` +```text ### Run Tests @@ -88,7 +88,7 @@ just test::integration # Documentation tests just test::doc -``` +```text ### Build Project @@ -106,7 +106,7 @@ just build::all-backends # Release build (optimized) just build::release -``` +```text ### Watch for Changes @@ -114,7 +114,7 @@ Watch for file changes and auto-rebuild: ```bash just dev::watch -``` +```text Requires: `cargo-watch` (install with `cargo install cargo-watch`) @@ -126,7 +126,7 @@ just dev::docs-gen # Generate and open in browser just dev::docs -``` +```text ### Run Examples @@ -143,7 +143,7 @@ cargo run -p typedialog-tui --example form_with_autocompletion # List available examples just test::list -``` +```text ## Just Modules @@ -161,7 +161,7 @@ just build::all # All variants just build::all-backends # All backends combined just build::full # All features just build::check # Check compilation (no build) -``` +```text ### test - Test Suite @@ -179,7 +179,7 @@ just test::integration # Integration tests just test::doc # Doc tests just test::verbose # Tests with output just test::list # List tests -``` +```text ### dev - Development Tools @@ -198,7 +198,7 @@ just dev::watch # Watch and rebuild just dev::check # Check + fmt + lint just dev::info # Show workspace info just dev::tree # Dependency tree -``` +```text ### ci - CI/CD Pipeline @@ -214,7 +214,7 @@ just ci::test-integration # Integration tests just ci::build-debug # Debug build just ci::build-release # Release build just ci::full # Complete pipeline -``` +```text ### nickel - Nickel Schema Generation @@ -227,7 +227,7 @@ just nickel::nickel-workflow SCHEMA TEMPLATE # Full workflow just nickel::nickel-i18n SCHEMA # Extract i18n only just nickel::nickel-roundtrip IN FORM # Roundtrip (read/write) just nickel::help # Show Nickel recipes help -``` +```text ### distro - Distribution & Packaging @@ -255,7 +255,7 @@ just distro::package-release-version V # With version just distro::generate-manifest # Create manifest just distro::list-packages # List packages just distro::clean-distro # Clean directory -``` +```text ## Development Workflow Examples @@ -269,7 +269,7 @@ just dev::watch # 3. Changes auto-rebuild # 4. Run tests manually just test::all -``` +```text ### Adding a Feature @@ -285,7 +285,7 @@ just ci::full # 4. Push and create PR git push origin feature/my-feature -``` +```text ### Preparing Release @@ -305,7 +305,7 @@ just distro::create-checksums just distro::package-release # 5. Create GitHub release (see release.md) -``` +```text ## Examples @@ -322,7 +322,7 @@ cargo run --example form_with_sections # With groups cargo run --example form_with_grouped_items -``` +```text ### Advanced Examples @@ -332,7 +332,7 @@ cargo run --example conditional_required_demo # Autocompletion cargo run --example form_with_autocompletion -``` +```text ### Backend-Specific @@ -345,7 +345,7 @@ cargo run -p typedialog-tui --example form_with_autocompletion # Web server cargo run -p typedialog-web -- --config config/web/dev.toml -``` +```text ### Nickel Examples @@ -363,7 +363,7 @@ cargo run --example nickel_i18n_extraction # Template rendering cargo run --example nickel_template_context -``` +```text See [../examples/07-nickel-generation/](../examples/07-nickel-generation/) for complete guide. See [nickel.md](nickel.md) for detailed Nickel documentation. @@ -377,7 +377,7 @@ Clear build cache and rebuild: ```bash cargo clean just build::default -``` +```text ### Test failures @@ -385,7 +385,7 @@ Run with backtrace for more details: ```bash RUST_BACKTRACE=1 cargo test -``` +```text ### Format check failing @@ -393,7 +393,7 @@ Auto-fix formatting: ```bash just fmt -``` +```text ### "just" not found @@ -402,7 +402,7 @@ Install or add to PATH: ```bash cargo install just export PATH="$HOME/.cargo/bin:$PATH" -``` +```text ### cargo-watch not working @@ -410,7 +410,7 @@ Install it: ```bash cargo install cargo-watch -``` +```text ### Port already in use (web backend) @@ -420,13 +420,13 @@ Change port in config: # config/web/dev.toml [server] port = 3001 # Instead of 3000 -``` +```text Or override: ```bash TYPEDIALOG_WEB_PORT=3001 cargo run -p typedialog-web -``` +```text ## Tips & Tricks @@ -437,19 +437,19 @@ Use incremental compilation: ```bash export CARGO_BUILD_JOBS=$(nproc) export CARGO_INCREMENTAL=1 -``` +```text ### Parallel testing ```bash cargo test -- --test-threads=4 -``` +```text ### Format all code quickly ```bash just fmt && just lint-fix -``` +```text ### Development script @@ -470,7 +470,7 @@ just test::all echo "Watching for changes..." just dev::watch -``` +```text ## Next Steps diff --git a/docs/encryption/README.md b/docs/encryption/README.md index 2658da7..905821e 100644 --- a/docs/encryption/README.md +++ b/docs/encryption/README.md @@ -23,7 +23,7 @@ TypeDialog provides comprehensive encryption support for sensitive data across a name = "password" field_type = "Password" encrypted = true -``` +```text ### 2. Choose Encryption Provider @@ -31,13 +31,13 @@ encrypted = true [encryption] provider = "aws_kms" # or "gcp_kms", "vault", "local" key_id = "arn:aws:kms:us-east-1:..." -``` +```text ### 3. Run with Encryption Enabled ```bash typedialog form config.toml --encrypt -``` +```text ## Supported Backends @@ -125,7 +125,7 @@ See [examples/08-encryption/](../../examples/08-encryption/) for working example ## Related Documentation -- [Field Types](../field_types.md) - Field type reference including `encrypted` attribute +- [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 @@ -139,7 +139,7 @@ Set provider in config: [encryption] provider = "aws_kms" key_id = "..." -``` +```text ### "Failed to decrypt" diff --git a/docs/encryption/encryption-quick-start.md b/docs/encryption/encryption-quick-start.md index b2ce68a..95610ad 100644 --- a/docs/encryption/encryption-quick-start.md +++ b/docs/encryption/encryption-quick-start.md @@ -23,7 +23,7 @@ typedialog form examples/08-encryption/credentials.toml --redact --format json # 6. Run all integration tests cargo test --test nickel_integration test_encryption -- --nocapture -``` +```text ## Example Forms @@ -99,7 +99,7 @@ See `examples/08-encryption/README.md` for detailed examples and testing instruc ```text cargo test --test nickel_integration test_encryption -``` +```text Output: @@ -112,7 +112,7 @@ test test_encryption_roundtrip_with_redaction ... ok test test_encryption_metadata_to_field_definition ... ok test result: ok. 5 passed; 0 failed -``` +```text All tests use the example forms for verification. @@ -141,7 +141,7 @@ encryption_backend = "age" [fields.encryption_config] key = "~/.age/key.txt" -``` +```text ### 2. Test Age encryption manually @@ -158,7 +158,7 @@ age -r "$PUBLIC_KEY" /tmp/test.txt > /tmp/test.age # Decrypt age -d -i ~/.age/key.txt /tmp/test.age # Output: test-secret-123 -``` +```text ### 3. Implement Age roundtrip test @@ -194,7 +194,7 @@ fn test_age_encrypt_decrypt_roundtrip() { assert!(ciphertext.starts_with("age1-"), "Should be Age format"); assert_ne!(ciphertext, "my-password", "Should be encrypted"); } -``` +```text ### 4. Test with RustyVault (optional, requires Docker) @@ -212,7 +212,7 @@ typedialog form test_form_age.toml \ --vault-token root \ --vault-key-path transit/keys/typedialog-key \ --format json -``` +```text ## Verification Checklist diff --git a/docs/encryption/encryption-services-setup.md b/docs/encryption/encryption-services-setup.md index 68f7423..0357bcf 100644 --- a/docs/encryption/encryption-services-setup.md +++ b/docs/encryption/encryption-services-setup.md @@ -18,7 +18,7 @@ This guide covers Age (trivial) and RustyVault (moderate). SOPS is skipped for n ## Part 1: Age Backend (Local File Encryption) -### What is Age? +### What is Age Age is a simple, modern encryption tool using X25519 keys. Perfect for development because: @@ -32,13 +32,13 @@ Age is a simple, modern encryption tool using X25519 keys. Perfect for developme ```bash brew install age -``` +```text **Linux (Ubuntu/Debian):** ```bash sudo apt-get install age -``` +```text **Manual (any OS):** @@ -48,14 +48,14 @@ sudo apt-get install age 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/ -``` +```text **Verify installation:** ```bash age --version # age v1.1.1 -``` +```text ### Generate Age Key Pair @@ -70,10 +70,10 @@ mkdir -p ~/.age # Generate private key age-keygen -o ~/.age/key.txt -# Output will show: +# Output will show # Public key: age1...xxx (save this, shown in file) # Written to /home/user/.age/key.txt -``` +```text **Verify key generation:** @@ -84,7 +84,7 @@ cat ~/.age/key.txt # Extract public key (age CLI does this automatically) grep "^public key:" ~/.age/key.txt | cut -d' ' -f3 -``` +```text ### Test Age Encryption Locally @@ -92,7 +92,7 @@ grep "^public key:" ~/.age/key.txt | cut -d' ' -f3 ```bash echo "This is a secret message" > test_message.txt -``` +```text **Encrypt with age:** @@ -106,7 +106,7 @@ age -r "$PUBLIC_KEY" test_message.txt > test_message.age # Verify ciphertext is unreadable cat test_message.age # Output: AGE-ENCRYPTION-V1...binary... -``` +```text **Decrypt with age:** @@ -115,7 +115,7 @@ cat test_message.age age -d -i ~/.age/key.txt test_message.age # Output: This is a secret message -``` +```text ### Configure typedialog to Use Age @@ -123,7 +123,7 @@ age -d -i ~/.age/key.txt test_message.age ```bash export AGE_KEY_FILE="$HOME/.age/key.txt" -``` +```text **CLI flags:** @@ -133,7 +133,7 @@ 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 -``` +```text See `examples/08-encryption/README.md` for more example forms and test cases. @@ -149,13 +149,13 @@ encryption_backend = "age" [fields.encryption_config] key = "~/.age/key.txt" -``` +```text --- ## Part 2: RustyVault Backend (HTTP Service) -### What is RustyVault? +### What is RustyVault RustyVault is a Rust implementation of HashiCorp Vault's Transit API: @@ -177,7 +177,7 @@ docker search rustyvault git clone https://github.com/Tongsuo-Project/RustyVault.git cd RustyVault docker build -t rustyvault:latest . -``` +```text **Option B: Manual Build (if Docker not available)** @@ -191,7 +191,7 @@ cd RustyVault cargo build --release # Binary at: target/release/rustyvault -``` +```text ### Run RustyVault Service @@ -206,7 +206,7 @@ docker run -d \ # Verify it started docker logs rustyvault | head -20 -``` +```text **Using local binary:** @@ -227,7 +227,7 @@ EOF # Run service ~/RustyVault/target/release/rustyvault server -c config.toml -``` +```text **Verify service is running:** @@ -235,7 +235,7 @@ EOF # In another terminal curl -s http://localhost:8200/v1/sys/health | jq . # Should return health status JSON -``` +```text ### Configure RustyVault for Encryption @@ -255,7 +255,7 @@ 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" -``` +```text **Enable Transit secrets engine:** @@ -263,7 +263,7 @@ export VAULT_TOKEN="$ROOT_TOKEN" curl -s -X POST http://localhost:8200/v1/sys/mounts/transit \ -H "X-Vault-Token: $VAULT_TOKEN" \ -d '{"type": "transit"}' | jq . -``` +```text **Create encryption key:** @@ -275,7 +275,7 @@ curl -s -X POST http://localhost:8200/v1/transit/keys/typedialog-key \ # Verify key created curl -s http://localhost:8200/v1/transit/keys/typedialog-key \ -H "X-Vault-Token: $VAULT_TOKEN" | jq . -``` +```text ### Test RustyVault Encryption @@ -288,7 +288,7 @@ 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 -``` +```text **Decrypt data via HTTP:** @@ -299,7 +299,7 @@ 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 -``` +```text ### Configure typedialog to Use RustyVault @@ -308,7 +308,7 @@ curl -s -X POST http://localhost:8200/v1/transit/decrypt/typedialog-key \ ```bash export VAULT_ADDR="http://localhost:8200" export VAULT_TOKEN="s.xxxx..." # Token from above -``` +```text **CLI flags:** @@ -320,7 +320,7 @@ typedialog form examples/08-encryption/credentials.toml \ --vault-token "s.xxxx..." \ --vault-key-path "transit/keys/typedialog-key" \ --format json -``` +```text This form includes field-level RustyVault configuration in the `vault_token` field. @@ -338,7 +338,7 @@ encryption_backend = "rustyvault" vault_addr = "http://localhost:8200" vault_token = "s.xxxx..." key_path = "transit/keys/typedialog-key" -``` +```text --- @@ -424,14 +424,14 @@ 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'" -``` +```text **Make executable and run:** ```bash chmod +x scripts/encryption-test-setup.sh ./scripts/encryption-test-setup.sh -``` +```text ### Test Case 1: Age Redaction (No Service Required) @@ -440,9 +440,9 @@ chmod +x scripts/encryption-test-setup.sh ```bash typedialog form examples/08-encryption/simple-login.toml --redact --format json -# Expected output: +# Expected output # {"username": "alice", "password": "[REDACTED]"} -``` +```text **Option B: Create form manually** @@ -466,7 +466,7 @@ EOF # Test redaction (requires no service) typedialog form test_redaction.toml --redact --format json -``` +```text ### Test Case 2: Age Encryption (Service Not Required, Key File Required) @@ -486,7 +486,7 @@ typedialog form examples/08-encryption/simple-login.toml \ # Or test with full credentials form typedialog form examples/08-encryption/credentials.toml \ --encrypt --backend age --key-file ~/.age/key.txt --format json -``` +```text **Option B: Create form manually** @@ -520,7 +520,7 @@ EOF # Test encryption (requires Age key file) typedialog form test_age_encrypt.toml --encrypt --backend age --key-file ~/.age/key.txt --format json -``` +```text ### Test Case 3: RustyVault Encryption (Service Required) @@ -532,7 +532,7 @@ typedialog form test_age_encrypt.toml --encrypt --backend age --key-file ~/.age/ # Verify service is healthy curl http://localhost:8200/v1/sys/health | jq . -``` +```text **Option A: Use pre-built example (Recommended)** @@ -555,7 +555,7 @@ typedialog form examples/08-encryption/credentials.toml \ --encrypt --backend rustyvault \ --vault-key-path "transit/keys/typedialog-key" \ --format json -``` +```text **Option B: Create form manually** @@ -595,7 +595,7 @@ typedialog form test_vault_encrypt.toml \ # Expected output: password field contains vault ciphertext # {"username": "alice", "password": "vault:v1:..."} -``` +```text --- @@ -611,7 +611,7 @@ Once Age is set up, these test scenarios validate the pipeline: cargo test --test nickel_integration test_encryption_roundtrip_with_redaction -- --nocapture # Expected: PASS - redacts sensitive fields -``` +```text **Scenario 2: Metadata mapping works** @@ -619,7 +619,7 @@ cargo test --test nickel_integration test_encryption_roundtrip_with_redaction -- cargo test --test nickel_integration test_encryption_metadata_to_field_definition -- --nocapture # Expected: PASS - EncryptionMetadata maps to FieldDefinition -``` +```text **Scenario 3: Auto-detection of password fields** @@ -627,13 +627,13 @@ cargo test --test nickel_integration test_encryption_metadata_to_field_definitio cargo test --test nickel_integration test_encryption_auto_detection_from_field_type -- --nocapture # Expected: PASS - Password fields auto-marked as sensitive -``` +```text ### Run All Encryption Tests ```bash cargo test --test nickel_integration test_encryption -- --nocapture -``` +```text **Current status:** @@ -653,13 +653,13 @@ cargo test --test nickel_integration test_encryption -- --nocapture # Install age brew install age # macOS sudo apt install age # Linux -``` +```text **Problem: Permission denied on ~/.age/key.txt** ```bash chmod 600 ~/.age/key.txt -``` +```text **Problem: Invalid key format** @@ -667,7 +667,7 @@ chmod 600 ~/.age/key.txt # Regenerate keys rm ~/.age/key.txt age-keygen -o ~/.age/key.txt -``` +```text ### RustyVault Issues @@ -680,7 +680,7 @@ docker logs rustyvault # Remove and restart docker rm -f rustyvault docker run -d --name rustyvault -p 8200:8200 rustyvault:latest -``` +```text **Problem: Vault initialization fails** @@ -690,7 +690,7 @@ curl -s http://localhost:8200/v1/sys/health # If not, restart container docker restart rustyvault -``` +```text **Problem: Transit API not working** @@ -701,7 +701,7 @@ echo $VAULT_TOKEN # Check auth curl -s http://localhost:8200/v1/sys/mounts \ -H "X-Vault-Token: $VAULT_TOKEN" -``` +```text **Problem: Can't connect from typedialog** @@ -717,7 +717,7 @@ echo $VAULT_TOKEN curl -s -X POST http://localhost:8200/v1/transit/encrypt/typedialog-key \ -H "X-Vault-Token: $VAULT_TOKEN" \ -d '{"plaintext": "dGVzdA=="}' | jq . -``` +```text --- diff --git a/docs/encryption/encryption-unified-architecture.md b/docs/encryption/encryption-unified-architecture.md index 7d390ef..ef7ff3e 100644 --- a/docs/encryption/encryption-unified-architecture.md +++ b/docs/encryption/encryption-unified-architecture.md @@ -29,7 +29,7 @@ let ciphertext = backend.encrypt(&plaintext)?; #[match] "sops" => { /* SOPS code */ } "rustyvault" => { /* RustyVault code */ } -``` +```text ### After: Unified API with BackendSpec @@ -48,7 +48,7 @@ let ciphertext = encrypt(&plaintext, &spec)?; // Or KMS let spec = BackendSpec::aws_kms(region, key_id); let ciphertext = encrypt(&plaintext, &spec)?; -``` +```text ## Integration Points @@ -63,7 +63,7 @@ type = "password" sensitive = true encryption_backend = "age" encryption_config = { key_file = "~/.age/key.txt" } -``` +```text The `encryption_bridge` module automatically converts this to `BackendSpec::age(...)` and uses the unified API. @@ -89,7 +89,7 @@ Nickel support remains unchanged but now uses the unified backend system: Region="us-east-1" KeyId="arn:aws:kms:..." = "", } -``` +```text ### 3. Internal Encryption Function @@ -113,7 +113,7 @@ fn transform_sensitive_value( Ok(Value::String(ciphertext)) } -``` +```text ## New Bridge Module @@ -126,7 +126,7 @@ pub fn field_to_backend_spec( field: &FieldDefinition, default_backend: Option<&str>, ) -> Result -``` +```text **Conversion Logic:** @@ -164,7 +164,7 @@ typedialog-core = { path = "...", features = ["encryption"] } # Custom selection typedialog-core = { path = "...", features = ["encryption"] } # Depends on encrypt crate configuration -``` +```text ### Environment Variables @@ -175,39 +175,39 @@ Backend-specific configuration via environment: ```bash # Uses ~/.age/key.txt by default # Or specify via field config: encryption_config = { key_file = "/custom/path" } -``` +```text **SOPS:** ```bash # Uses .sops.yaml in current/parent directories -``` +```text **SecretumVault:** ```bash export VAULT_ADDR="https://vault.internal:8200" export VAULT_TOKEN="hvs.CAAA..." -``` +```text **AWS KMS:** ```bash export AWS_REGION="us-east-1" # AWS credentials from standard chain (env vars, ~/.aws/credentials, IAM roles) -``` +```text **GCP KMS:** ```bash export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json" -``` +```text **Azure KMS:** ```bash # Azure CLI authentication or environment variables -``` +```text ## Error Handling @@ -222,7 +222,7 @@ Error: Encryption failed: SecretumVault backend requires Error: Encryption failed: AWS KMS backend requires region in encryption_config -``` +```text ## Testing @@ -237,7 +237,7 @@ cargo test --features encryption --test encryption_integration # Specific test cargo test --features encryption test_age_roundtrip_encrypt_decrypt -``` +```text ### Test Results @@ -265,7 +265,7 @@ 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 -``` +```text ## Migration Path @@ -290,7 +290,7 @@ type = "text" sensitive = true encryption_backend = "secretumvault" # Or awskms, gcpkms, azurekms encryption_config = { vault_addr = "...", vault_token = "..." } -``` +```text ### For Code Extending typedialog @@ -307,7 +307,7 @@ use typedialog_core::encryption_bridge; let spec = encryption_bridge::field_to_backend_spec(&field, None)?; let ciphertext = encrypt(&plaintext, &spec)?; -``` +```text ## Multi-Backend Support @@ -326,7 +326,7 @@ name = "db_password" sensitive = true encryption_backend = "secretumvault" encryption_config = { vault_addr = "https://vault.prod:8200", vault_token = "..." } -``` +```text Same Rust code handles both without changes. @@ -340,7 +340,7 @@ typedialog form config.toml --encrypt --backend secretumvault export VAULT_ADDR="https://vault.internal:8200" export VAULT_TOKEN="hvs.CAAA..." typedialog form config.toml --encrypt --backend secretumvault -``` +```text ## Feature Flags @@ -360,7 +360,7 @@ Backends are feature-gated in the encrypt crate: let spec = BackendSpec::age_default(); encrypt(&plaintext, &spec)?; // Returns: Backend 'age' not available } -``` +```text ## Post-Quantum Cryptography @@ -378,7 +378,7 @@ encryption_config = { vault_token = "hvs.CAAA...", key_name = "pqc-key" # Uses ML-KEM encapsulation, ML-DSA signatures } -``` +```text **Requirements:** @@ -399,7 +399,7 @@ cargo build --features encryption --verbose # Look for feature compilation # It should show: "Compiling encrypt ... with features: age,..." -``` +```text ### "Invalid ciphertext" After Update @@ -428,7 +428,7 @@ For faster tests without real encryption keys: ```bash # In development/testing cargo test --features test-util -``` +```text MockBackend provides deterministic encryption for CI/CD: @@ -439,7 +439,7 @@ use encrypt::test_util::MockBackend; let backend = MockBackend::new(); let ct = backend.encrypt("secret")?; // Fast, reproducible, no real keys needed -``` +```text ## See Also diff --git a/docs/field_types.md b/docs/field-types.md similarity index 98% rename from docs/field_types.md rename to docs/field-types.md index 111c085..b1ab44c 100644 --- a/docs/field_types.md +++ b/docs/field-types.md @@ -24,7 +24,7 @@ prompt = "Enter username" placeholder = "john_doe" default = "admin" required = true -``` +```text **Attributes**: @@ -52,7 +52,7 @@ type = "password" prompt = "API Token" required = true help = "Your secret authentication token" -``` +```text **Attributes**: @@ -78,7 +78,7 @@ name = "enable_feature" type = "confirm" prompt = "Enable experimental features?" default = false -``` +```text **Attributes**: @@ -115,7 +115,7 @@ label = "MySQL (server)" [[elements.options]] value = "postgresql" label = "PostgreSQL (server)" -``` +```text **Attributes**: @@ -166,7 +166,7 @@ options = [ { value = "editor", label = "Editor" }, { value = "viewer", label = "Viewer" } ] -``` +```text **Display Modes**: @@ -208,7 +208,7 @@ min_date = "2024-01-01" max_date = "2025-12-31" week_start = "Mon" required = true -``` +```text **Attributes**: @@ -238,7 +238,7 @@ prompt = "Configuration content" file_extension = "toml" prefix_text = "[settings]\n" required = true -``` +```text **Attributes**: @@ -267,7 +267,7 @@ custom_type = "Port" prompt = "Server port" placeholder = "8080" required = true -``` +```text **Attributes**: @@ -299,7 +299,7 @@ default_items = 1 unique = true required = false help = "Configure UDP tracker bind addresses" -``` +```text **Attributes**: @@ -335,7 +335,7 @@ placeholder = "0.0.0.0:6969" default = "0.0.0.0:6969" required = true order = 0 -``` +```text **Backend rendering**: @@ -374,7 +374,7 @@ order = 0 { "bind_address": "0.0.0.0:6970" } ] } -``` +```text **Nickel schema mapping**: @@ -385,7 +385,7 @@ order = 0 udp_trackers | Array TrackerUdp | optional }, } -``` +```text **Use cases**: @@ -413,7 +413,7 @@ type = "section_header" title = "📊 Database Configuration" border_top = true border_bottom = true -``` +```text ### Section @@ -424,7 +424,7 @@ Informational text block. name = "info" type = "section" content = "Configure your database connection settings below." -``` +```text ### Group @@ -436,7 +436,7 @@ name = "mysql_group" type = "group" when = "database_driver == mysql" includes = ["fragments/database-mysql-section.toml"] -``` +```text --- @@ -451,7 +451,7 @@ type = "password" prompt = "MySQL Password" when = "database_driver == mysql" required = true -``` +```text ### Comparison Operators @@ -471,7 +471,7 @@ name = "legacy_warning" type = "section" content = "⚠️ SQLite is for development only" when = "database_driver != postgresql" -``` +```text **Numeric comparisons**: @@ -491,7 +491,7 @@ when = "port >= 1024" name = "pool_size_warning" type = "section" when = "connection_pool > 100" -``` +```text ### String Operators @@ -517,7 +517,7 @@ when = "url startswith https" name = "yaml_parser" type = "select" when = "config_file endswith .yaml" -``` +```text ### Array Membership @@ -538,7 +538,7 @@ options = [ name = "python_virtualenv" type = "confirm" when = "python in languages" -``` +```text **Note**: The `in` operator works with: @@ -561,7 +561,7 @@ name = "create_new_config" type = "text" prompt = "Configuration name" when = "!file_exists(.env)" -``` +```text **Negation with `!`**: @@ -573,7 +573,7 @@ name = "docker_setup" type = "group" includes = ["fragments/docker-init.toml"] when = "!file_exists(Dockerfile)" -``` +```text ### Future Support @@ -596,7 +596,7 @@ type = "text" prompt = "form.username.prompt" placeholder = "form.username.placeholder" i18n = true -``` +```text Translations resolved from Fluent `.ftl` files in `locales/` directory. @@ -632,7 +632,7 @@ Example Nickel schema: udp_trackers | Array { bind_address | String }, } } -``` +```text --- diff --git a/docs/fragment-search-paths.md b/docs/fragment-search-paths.md index b62463b..bb33063 100644 --- a/docs/fragment-search-paths.md +++ b/docs/fragment-search-paths.md @@ -21,13 +21,13 @@ Colon-separated list (semicolon on Windows) of directories to search for fragmen ```bash export TYPEDIALOG_FRAGMENT_PATH="/path/to/fragments:/another/path" -``` +```text **Windows:** ```cmd set TYPEDIALOG_FRAGMENT_PATH=C:\fragments;D:\other\fragments -``` +```text ## Search Order @@ -42,7 +42,7 @@ When a fragment is referenced (e.g., `includes = ["fragments/user-fields.toml"]` ```bash export TYPEDIALOG_FRAGMENT_PATH=".typedialog/ci/fragments:/usr/local/share/typedialog/fragments" -``` +```text **Fragment reference:** `includes = ["user-auth.toml"]` @@ -52,7 +52,7 @@ export TYPEDIALOG_FRAGMENT_PATH=".typedialog/ci/fragments:/usr/local/share/typed 1. ./user-auth.toml (form's directory) 2. .typedialog/ci/fragments/user-auth.toml (local) 3. /usr/local/share/typedialog/fragments/user-auth.toml (system) -``` +```text **Result:** First existing file is loaded. @@ -67,7 +67,7 @@ Organization maintains a shared library of standard fragments. ```bash # System-wide fragments export TYPEDIALOG_FRAGMENT_PATH="/opt/company/typedialog/fragments" -``` +```text **Directory structure:** @@ -77,7 +77,7 @@ export TYPEDIALOG_FRAGMENT_PATH="/opt/company/typedialog/fragments" ├── database-config.toml ├── api-settings.toml └── logging.toml -``` +```text **Form reference:** @@ -85,7 +85,7 @@ export TYPEDIALOG_FRAGMENT_PATH="/opt/company/typedialog/fragments" [[item]] type = "group" includes = ["user-auth.toml", "database-config.toml"] -``` +```text **Benefit:** All projects use same fragments → consistency across organization. @@ -97,7 +97,7 @@ Project needs custom version of standard fragment. ```bash export TYPEDIALOG_FRAGMENT_PATH=".typedialog/fragments:/opt/company/typedialog/fragments" -``` +```text **Directory structure:** @@ -107,7 +107,7 @@ project/ │ └── fragments/ │ └── user-auth.toml # ← Custom version └── form.toml -``` +```text **Form reference:** @@ -115,7 +115,7 @@ project/ [[item]] type = "group" includes = ["user-auth.toml"] # Uses local version -``` +```text **Result:** @@ -132,7 +132,7 @@ Combine fragments from different sources: company library, team library, local. ```bash export TYPEDIALOG_FRAGMENT_PATH=".typedialog/fragments:~/team-fragments:/opt/company/fragments" -``` +```text **Search priority:** @@ -165,7 +165,7 @@ EOF # Allow direnv to load .envrc direnv allow -``` +```text **Result:** `TYPEDIALOG_FRAGMENT_PATH` is automatically set when you `cd` into project. @@ -177,7 +177,7 @@ Set globally for all projects. ```bash export TYPEDIALOG_FRAGMENT_PATH="$HOME/.typedialog/fragments:/usr/local/share/typedialog/fragments" -``` +```text ### Per-Command @@ -185,7 +185,7 @@ Override for single invocation. ```bash TYPEDIALOG_FRAGMENT_PATH="/custom/path" typedialog form schema.toml -``` +```text ## Implementation Details @@ -224,7 +224,7 @@ fn resolve_fragment_path(path: &str, base_dir: &Path) -> PathBuf { // 4. Return base_path for error reporting base_path } -``` +```text ### Separator Detection @@ -233,14 +233,14 @@ fn resolve_fragment_path(path: &str, base_dir: &Path) -> PathBuf { ```rust #[cfg(unix)] let separator = ':'; -``` +```text **Windows:** `;` (semicolon) ```rust #[cfg(windows)] let separator = ';'; -``` +```text ### Backward Compatibility @@ -273,7 +273,7 @@ let separator = ';'; ```text Error: Failed to load fragment 'user-fields.toml': No such file or directory -``` +```text **Check:** @@ -287,7 +287,7 @@ ls /usr/local/share/typedialog/fragments/user-fields.toml # 3. Check search order (add debug output) export TYPEDIALOG_DEBUG=1 # If supported -``` +```text ### Wrong version loaded @@ -302,7 +302,7 @@ echo $TYPEDIALOG_FRAGMENT_PATH # Verify local file exists ls -la .typedialog/fragments/fragment.toml -``` +```text ### Windows path issues @@ -312,7 +312,7 @@ ls -la .typedialog/fragments/fragment.toml ```cmd set TYPEDIALOG_FRAGMENT_PATH="C:\Program Files\TypeDialog\fragments;D:\Custom Fragments" -``` +```text ## Examples @@ -327,13 +327,13 @@ project/ └── .typedialog/ └── fragments/ └── custom-field.toml -``` +```text **.envrc:** ```bash export TYPEDIALOG_FRAGMENT_PATH=".typedialog/fragments:/usr/local/share/typedialog/fragments" -``` +```text **form.toml:** @@ -344,7 +344,7 @@ includes = [ "custom-field.toml", # Loads from .typedialog/fragments/ "standard-fields.toml" # Loads from /usr/local/share/.../ ] -``` +```text ### Example 2: Multi-Environment @@ -352,13 +352,13 @@ includes = [ ```bash export TYPEDIALOG_FRAGMENT_PATH=".typedialog/fragments:$HOME/dev-fragments:/opt/fragments" -``` +```text **Production:** ```bash export TYPEDIALOG_FRAGMENT_PATH="/opt/company/fragments" -``` +```text **Result:** Development has local overrides, production uses only approved fragments. diff --git a/docs/history.md b/docs/history.md index 26ea9c4..64f1433 100644 --- a/docs/history.md +++ b/docs/history.md @@ -42,7 +42,7 @@ Prompts, forms, schemas definition, use backends (CLI, TUI, Web, AI). Extended w ### Binary Applications - **typedialog**: CLI binary (inquire backend) -- **typedialog-tui**: Terminal UI (ratatui backend) +- **typedialog-tui**: Terminal UI (ratatui backend) - **typedialog-web**: HTTP server (axum backend) ### New Subsystems (2025) diff --git a/docs/installation.md b/docs/installation.md index d7e5c8c..a980906 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -17,14 +17,14 @@ Install from [https://rustup.rs/](https://rustup.rs/): ```bash curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source $HOME/.cargo/env -``` +```text Verify: ```bash rustc --version cargo --version -``` +```text #### just - Command Orchestration @@ -32,7 +32,7 @@ cargo --version ```bash cargo install just -``` +```text **Option 2: Package manager** @@ -48,13 +48,13 @@ sudo pacman -S just # Fedora sudo dnf install just -``` +```text Verify: ```bash just --version -``` +```text ### Optional (for specific features) @@ -64,7 +64,7 @@ If you plan to use Nickel (`.ncl`) form definitions: ```bash cargo install nickel-lang -``` +```text Or download from: [https://github.com/nickel-lang/nickel/releases](https://github.com/nickel-lang/nickel/releases) @@ -72,7 +72,7 @@ Verify: ```bash nickel --version -``` +```text #### cargo-cross - For cross-platform compilation @@ -80,7 +80,7 @@ For compiling to platforms other than your current OS: ```bash cargo install cross -``` +```text Requires Docker to be installed. @@ -90,7 +90,7 @@ For automatic rebuild on file changes: ```bash cargo install cargo-watch -``` +```text #### Docker - For Docker cross-compilation @@ -102,7 +102,7 @@ Verify: ```bash docker --version -``` +```text ## Installation Steps @@ -111,7 +111,7 @@ docker --version ```bash git clone https://github.com/anthropics/typedialog.git cd typedialog -``` +```text ### 2. Verify Dependencies @@ -126,7 +126,7 @@ nickel --version # If using Nickel cargo cross --version # If cross-compiling cargo watch --version # If using watch docker --version # If using Docker builds -``` +```text ### 3. Build Project @@ -134,13 +134,13 @@ Using cargo: ```bash cargo build -``` +```text Or using just: ```bash just build::default -``` +```text ### 4. Run Tests @@ -150,7 +150,7 @@ cargo test # Or using just just test::all -``` +```text ### 5. Verify Installation @@ -164,7 +164,7 @@ ls -la target/debug/typedialog* # Or install cargo install --path . typedialog --version -``` +```text ## Quick Verification @@ -190,7 +190,7 @@ echo "=== Building project ===" cargo check && echo "✓ Project builds successfully" || echo "❌ Build failed" echo "=== All checks complete ===" -``` +```text ## Troubleshooting @@ -207,7 +207,7 @@ export PATH="$HOME/.cargo/bin:$PATH" # Verify just --version -``` +```text ### Rust compilation errors @@ -216,7 +216,7 @@ Update Rust to latest stable: ```bash rustup update rustc --version -``` +```text ### Permission denied on installer scripts @@ -225,7 +225,7 @@ Make scripts executable: ```bash chmod +x installers/bootstrap/install.sh chmod +x scripts/*.sh -``` +```text ### "cargo-watch not found" when using just dev::watch @@ -233,7 +233,7 @@ Install cargo-watch: ```bash cargo install cargo-watch -``` +```text ### Docker not running (for cross-compilation) @@ -248,7 +248,7 @@ sudo systemctl start docker # Verify docker --version -``` +```text ## Platform-Specific Setup @@ -261,7 +261,7 @@ brew install rust just # Or manual installation curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh cargo install just -``` +```text ### Linux (Ubuntu/Debian) @@ -273,24 +273,25 @@ sudo apt install build-essential rustup just # Or using cargo curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh cargo install just -``` +```text ### Linux (Arch) ```bash sudo pacman -S rust cargo just -``` +```text ### Windows 1. Install Rust: [https://rustup.rs/](https://rustup.rs/) -2. Install just: + +1. Install just: ```powershell cargo install just ``` -3. Or use Scoop: +1. Or use Scoop: ```powershell scoop install just diff --git a/docs/nickel.md b/docs/nickel.md index 1e9b75b..17d9994 100644 --- a/docs/nickel.md +++ b/docs/nickel.md @@ -25,7 +25,7 @@ Install Nickel CLI (optional, for schema validation): ```bash cargo install nickel-lang # Or download from: https://github.com/nickel-lang/nickel/releases -``` +```text ### Run Examples @@ -41,7 +41,7 @@ cargo run --example nickel_roundtrip # Run with i18n extraction cargo run --example nickel_i18n_extraction -``` +```text See [examples/07-nickel-generation/](../examples/07-nickel-generation/) for complete examples. @@ -56,7 +56,7 @@ use typedialog_core::nickel::ContractParser; let parser = ContractParser::new(); let contracts = parser.parse(nickel_schema)?; -``` +```text **Validates:** @@ -75,7 +75,7 @@ use typedialog_core::nickel::I18nExtractor; let extractor = I18nExtractor::new(); let strings = extractor.extract(nickel_ast)?; // Output: Map of translatable strings with locations -``` +```text **Extracts:** @@ -93,7 +93,7 @@ use typedialog_core::nickel::NickelTemplateContext; let context = NickelTemplateContext::from_schema(schema)?; let rendered = template_engine.render("form.j2", &context)?; -``` +```text **Supports:** @@ -120,7 +120,7 @@ config.verbose = true; // Execute with any backend (CLI, TUI, Web) let result = config.execute_with_backend(backend.as_mut()).await?; -``` +```text **Preserves:** @@ -156,7 +156,7 @@ let result = config.execute_with_backend(backend.as_mut()).await?; }, } } -``` +```text ### With Contracts @@ -173,7 +173,7 @@ let result = config.execute_with_backend(backend.as_mut()).await?; } } } -``` +```text ### With I18n @@ -187,7 +187,7 @@ let result = config.execute_with_backend(backend.as_mut()).await?; } } } -``` +```text ### With Templates @@ -200,7 +200,7 @@ let result = config.execute_with_backend(backend.as_mut()).await?; }, fields = { ... } } -``` +```text ## Roundtrip Workflow @@ -231,7 +231,7 @@ type = "text" prompt = "Parallel Jobs" default = "4" nickel_path = ["ci", "github_actions", "parallel_jobs"] -``` +```text Extracts from: @@ -243,7 +243,7 @@ Extracts from: } } } -``` +```text **Rules:** @@ -262,7 +262,7 @@ typedialog nickel-roundtrip \ --output config.ncl \ --ncl-template config.ncl.j2 \ --verbose -``` +```text **Output:** @@ -286,7 +286,7 @@ typedialog nickel-roundtrip \ ║ • Apply CI tools: ./setup-ci.sh ║ ║ • Re-configure: ./ci-configure.sh ║ ╚════════════════════════════════════════════════════════════╝ -``` +```text ### Roundtrip with TUI Backend @@ -296,7 +296,7 @@ typedialog-tui nickel-roundtrip \ --form ci-form.toml \ --output config.ncl \ --ncl-template config.ncl.j2 -``` +```text Interactive TUI form + terminal summary (same as CLI). @@ -309,7 +309,7 @@ typedialog-web nickel-roundtrip \ --output config.ncl \ --ncl-template config.ncl.j2 \ --verbose -``` +```text **Features:** @@ -335,7 +335,7 @@ Web UI available at http://localhost:8080 ║ ✅ Configuration Saved Successfully! ║ ╠════════════════════════════════════════════════════════════╣ ... -``` +```text ### Form Requirements @@ -349,7 +349,7 @@ For roundtrip to work, your form MUST: nickel_path = ["project", "name"] # ✅ Required ``` -2. **Use correct path syntax:** +1. **Use correct path syntax:** ```toml # Flat field @@ -362,7 +362,7 @@ For roundtrip to work, your form MUST: nickel_path = ["ci", "tools", "linters"] ``` -3. **Match template variables:** +1. **Match template variables:** ```jinja2 # Template: config.ncl.j2 @@ -417,7 +417,7 @@ let validators = import "ci/validators.ncl" }, } } | validators.CiConfig -``` +```text **Form values are injected automatically.** @@ -439,7 +439,7 @@ cd examples/08-nickel-roundtrip/ # Edit with Web ./04-roundtrip-web.sh -``` +```text ### Validation @@ -452,13 +452,13 @@ typedialog nickel-roundtrip \ --output config.ncl \ --ncl-template template.ncl.j2 # Runs: nickel typecheck config.ncl -``` +```text **Disable validation:** ```bash typedialog nickel-roundtrip ... --no-validate -``` +```text ### Summary Output @@ -474,7 +474,7 @@ All backends generate summaries showing: ```bash typedialog nickel-roundtrip ... --verbose -``` +```text ### Roundtrip Troubleshooting @@ -484,7 +484,7 @@ typedialog nickel-roundtrip ... --verbose ```bash grep -r "nickel_path" form.toml -``` +```text **Issue: "Field not found in output"** @@ -492,7 +492,7 @@ grep -r "nickel_path" form.toml ```bash grep "{{ field_name }}" template.ncl.j2 -``` +```text **Issue: "Validation failed"** @@ -500,7 +500,7 @@ grep "{{ field_name }}" template.ncl.j2 ```bash nickel typecheck config.ncl -``` +```text **Issue: "Values not showing in web form"** @@ -508,7 +508,7 @@ nickel typecheck config.ncl ```bash nickel export config.ncl -``` +```text ## Building with Nickel @@ -523,7 +523,7 @@ just test::core # Generate docs just dev::docs -``` +```text ## Examples @@ -553,7 +553,7 @@ nickel export schemas/simple.ncl # Parse and render cargo run --manifest-path ../../Cargo.toml \ --example nickel_form_generation < schemas/simple.ncl -``` +```text ## Integration Patterns @@ -561,19 +561,19 @@ cargo run --manifest-path ../../Cargo.toml \ ```bash typedialog --format nickel form.ncl -``` +```text ### TUI Backend ```bash typedialog-tui form.ncl -``` +```text ### Web Backend ```bash typedialog-web --config form.ncl -``` +```text ## Advanced Topics @@ -595,7 +595,7 @@ Define custom validation predicates: } } } -``` +```text ### Reusable Components @@ -611,7 +611,7 @@ let address_fields = { country = { type = "select", label = "Country" } } } -``` +```text ### Schema Inheritance @@ -625,7 +625,7 @@ base & { custom_field = { ... } } } -``` +```text ### I18n Management @@ -637,7 +637,7 @@ cargo run --example nickel_i18n_extraction < form.ncl > strings.json # Update translations # (use with translation management system) -``` +```text ## Performance Considerations @@ -667,7 +667,7 @@ Check syntax with Nickel CLI: ```bash nickel export form.ncl -``` +```text ### Contract errors @@ -683,7 +683,7 @@ contracts = [ contracts = [ { predicate = |s| string.length s >= 8, error = "..." } ] -``` +```text ### Template rendering fails @@ -695,7 +695,7 @@ ls -la templates/form.j2 # Check context keys cargo run --example nickel_template_context < form.ncl -``` +```text ### I18n strings not extracted @@ -707,7 +707,7 @@ label = "Name" # ✓ I18n reference label = "i18n:form.name" -``` +```text ## Best Practices @@ -752,7 +752,7 @@ pub struct ParsedContracts { pub fields: Map, pub global: Vec, } -``` +```text ### I18nExtractor @@ -763,7 +763,7 @@ impl I18nExtractor { pub fn new() -> Self; pub fn extract(&self, ast: &NickelAst) -> Result; } -``` +```text ### NickelTemplateContext @@ -776,7 +776,7 @@ pub struct NickelTemplateContext { impl NickelTemplateContext { pub fn from_schema(schema: NickelSchemaIR) -> Result; } -``` +```text ### RoundtripConfig @@ -796,7 +796,7 @@ impl Default for RoundtripConfig { } } } -``` +```text ## Next Steps diff --git a/docs/pre-commit-setup.md b/docs/pre-commit-setup.md index 1e11a7b..748f2b5 100644 --- a/docs/pre-commit-setup.md +++ b/docs/pre-commit-setup.md @@ -12,19 +12,19 @@ Automated linting and validation before every commit. pip install pre-commit # Or with pipx (recommended) pipx install pre-commit -``` +```text **macOS (via Homebrew):** ```bash brew install pre-commit -``` +```text **Verify installation:** ```bash pre-commit --version -``` +```text ### 2. Install the hooks @@ -32,7 +32,7 @@ From the project root: ```bash pre-commit install -``` +```text This creates `.git/hooks/pre-commit` that runs automatically on `git commit`. @@ -87,7 +87,7 @@ Pre-commit runs automatically on `git commit`: git add docs/README.md git commit -m "Update README" # Pre-commit hooks run automatically -``` +```text ### Manual Run @@ -95,7 +95,7 @@ Run all hooks on all files: ```bash pre-commit run --all-files -``` +```text Run specific hook: @@ -103,13 +103,13 @@ Run specific hook: pre-commit run cargo-fmt --all-files pre-commit run markdownlint-cli2 --all-files pre-commit run vale --all-files -``` +```text Run hooks on staged files only: ```bash pre-commit run -``` +```text ### Skip Hooks (Emergency Only) @@ -117,7 +117,7 @@ To bypass hooks (use sparingly): ```bash git commit --no-verify -m "Emergency fix" -``` +```text **Note**: CI will still run all checks, so bypassing locally doesn't skip validation. @@ -149,11 +149,11 @@ Vale is configured to be **informative but not blocking**: To make Vale blocking, edit `.pre-commit-config.yaml`: ```yaml -# Change this: +# Change this entry: bash -c 'vale docs/ || exit 0' -# To this: +# To this entry: bash -c 'vale docs/' -``` +```text ## Updating Hooks @@ -161,7 +161,7 @@ Update to latest hook versions: ```bash pre-commit autoupdate -``` +```text This updates the `rev:` fields in `.pre-commit-config.yaml`. @@ -186,7 +186,7 @@ cargo install nickel-lang-cli # Nushell cargo install nu -``` +```text ### Hooks are slow @@ -196,9 +196,9 @@ cargo install nu ```bash git commit --no-verify -m "WIP: quick fix" -# Later, when ready: +# Later, when ready pre-commit run --all-files -``` +```text ### Markdownlint fails on valid Markdown @@ -214,7 +214,7 @@ pre-commit run --all-files "MD033": false // Example: allow HTML } } -``` +```text ### Vale warnings are too noisy @@ -225,13 +225,13 @@ pre-commit run --all-files ```ini [*.md] write-good.Weasel = NO # Disable weasel word warnings -``` +```text Or set higher alert level: ```ini MinAlertLevel = error # Only show errors, not warnings -``` +```text ## Best Practices @@ -241,7 +241,7 @@ After installing hooks, test them: ```bash pre-commit run --all-files -``` +```text Fix any issues before committing. @@ -257,7 +257,7 @@ Stage related changes together: git add docs/README.md docs/build.md git commit -m "Update build docs" # Only checks staged files -``` +```text ### 4. Use --no-verify Sparingly @@ -276,7 +276,7 @@ Monthly: ```bash pre-commit autoupdate pre-commit run --all-files -``` +```text ## Integration with CI @@ -302,13 +302,13 @@ Disable all hooks: ```bash pre-commit uninstall -``` +```text Re-enable: ```bash pre-commit install -``` +```text Disable specific hook (edit `.pre-commit-config.yaml`): @@ -316,13 +316,13 @@ Disable specific hook (edit `.pre-commit-config.yaml`): - id: cargo-clippy # Add this to disable: stages: [manual] -``` +```text Then run manually with: ```bash pre-commit run cargo-clippy --all-files --hook-stage manual -``` +```text ## Summary @@ -338,7 +338,7 @@ Install once, benefit forever: ```bash pip install pre-commit pre-commit install -``` +```text --- diff --git a/docs/prov-gen/README.md b/docs/prov-gen/README.md index 7d19a17..8320233 100644 --- a/docs/prov-gen/README.md +++ b/docs/prov-gen/README.md @@ -25,7 +25,7 @@ sudo cp target/release/typedialog-prov-gen /usr/local/bin/ # Or use just just build::prov-gen -``` +```text ### Basic Usage @@ -38,7 +38,7 @@ typedialog-prov-gen --name webapp --providers aws,gcp --output ./infra # Interactive mode typedialog-prov-gen --interactive -``` +```text ## Generated Structure @@ -77,7 +77,7 @@ provisioning/ │ └── hetzner/ ├── config-form.toml # Main configuration form (assembles fragments) └── README.md # Generated documentation -``` +```text ## 7-Layer Validation @@ -92,7 +92,7 @@ path = "fragments/server-config.toml" [[fragments]] path = "fragments/network-config.toml" -``` +```text ### Layer 2: Constraints (constraints/*.ncl) @@ -107,7 +107,7 @@ Reusable validation rules: ValidCIDR = ... } -``` +```text ### Layer 3: Values (User Input) @@ -128,7 +128,7 @@ let constraints_security = import "../constraints/security.ncl" in | constraints.ValidPort "ssh_port" | constraints_security.RequireSSL "ssl_enabled" } -``` +```text ### Layer 5: Schemas (schemas/*.ncl) @@ -144,7 +144,7 @@ Type-safe configuration schemas: ssl_enabled | Bool, } } -``` +```text ### Layer 6: Defaults (defaults/*.ncl) @@ -157,7 +157,7 @@ Default values for optional fields: ssl_enabled = true, max_connections = 100, } -``` +```text ### Layer 7: JSON Output @@ -170,7 +170,7 @@ Final validated configuration in JSON/YAML/TOML: "ssh_port": 22, "ssl_enabled": true } -``` +```text ## Configuration @@ -201,13 +201,13 @@ type = "t3.medium" name = "db" count = 2 type = "r5.large" -``` +```text Run: ```bash typedialog-prov-gen --spec project-spec.toml --output ./provisioning -``` +```text ## CLI Commands @@ -232,7 +232,7 @@ typedialog-prov-gen validate ./provisioning # List available templates typedialog-prov-gen templates --list -``` +```text ## Provider Templates @@ -240,7 +240,7 @@ typedialog-prov-gen templates --list ```bash typedialog-prov-gen --providers aws --output ./aws-infra -``` +```text Generates: @@ -255,7 +255,7 @@ Generates: ```bash typedialog-prov-gen --providers gcp --output ./gcp-infra -``` +```text Generates: @@ -269,7 +269,7 @@ Generates: ```bash typedialog-prov-gen --providers hetzner --output ./hetzner-infra -``` +```text Generates: @@ -283,7 +283,7 @@ Generates: ```bash typedialog-prov-gen --providers lxd --output ./lxd-infra -``` +```text Generates: @@ -302,7 +302,7 @@ typedialog-prov-gen \ --llm claude-3-5-sonnet-20241022 \ --prompt "web application with high availability" \ --output ./infra -``` +```text AI will: @@ -326,7 +326,7 @@ typedialog -p typedialog-tui -- ./provisioning/config-form.toml # 3. Apply configuration cd provisioning ./scripts/apply.sh -``` +```text ### Programmatic Usage @@ -341,7 +341,7 @@ let spec = ProjectSpec { }; generate(spec, "./provisioning").await?; -``` +```text ## Use Cases @@ -354,7 +354,7 @@ typedialog-prov-gen \ --name multi-cloud-app \ --providers aws,gcp \ --output ./infra -``` +```text ### 2. Development → Production @@ -364,7 +364,7 @@ Generate separate provisioning for dev/staging/prod: 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 -``` +```text ### 3. Compliance-Driven Configuration @@ -375,7 +375,7 @@ typedialog-prov-gen \ --name secure-app \ --compliance gdpr,hipaa \ --output ./infra -``` +```text ### 4. Cost-Optimized Infrastructure @@ -387,7 +387,7 @@ typedialog-prov-gen \ --optimize-for cost \ --budget 500 \ --output ./infra -``` +```text ## Validation @@ -406,7 +406,7 @@ nickel eval validators/validate_server.ncl < config.json # Full validation pipeline ./scripts/validate.nu -``` +```text ### CI/CD Integration @@ -417,7 +417,7 @@ nickel eval validators/validate_server.ncl < config.json cd provisioning ./scripts/validate.nu nickel typecheck schemas/*.ncl -``` +```text ## Examples @@ -444,7 +444,7 @@ Check constraint definitions: ```bash nickel eval constraints/network.ncl -``` +```text ### "Template not found" @@ -452,7 +452,7 @@ List available templates: ```bash typedialog-prov-gen templates --list -``` +```text ### "Provider not supported" @@ -460,7 +460,7 @@ Supported providers: aws, gcp, azure, hetzner, lxd ```bash typedialog-prov-gen --providers aws,gcp -``` +```text ### "Nickel evaluation error" @@ -469,7 +469,7 @@ Ensure Nickel CLI is installed: ```bash nickel --version # Install: cargo install nickel-lang-cli -``` +```text --- diff --git a/docs/quickstart.md b/docs/quickstart.md index 1481f8e..c0477af 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -5,7 +5,7 @@ ```bash cd /Users/Akasha/Development/typedialog cargo build --release --package typedialog-ag -``` +```text The binary will be at: `./target/release/typedialog-ag` @@ -15,7 +15,7 @@ Configure your API key: ```bash export ANTHROPIC_API_KEY=sk-ant-your-key-here -``` +```text ## Example Agents @@ -46,7 +46,7 @@ The `agents/` directory contains 9 production-ready example agents: # Execute with predefined inputs echo '{"name":"Bob"}' | ./target/release/typedialog-ag agents/greeting.agent.mdx --inputs - -``` +```text ### 2. Validate Agents @@ -54,18 +54,18 @@ echo '{"name":"Bob"}' | ./target/release/typedialog-ag agents/greeting.agent.mdx # Validate syntax and configuration ./target/release/typedialog-ag validate agents/code-reviewer.agent.mdx -# Output: +# Output # ✓ MDX syntax valid # ✓ Transpilation successful # ✓ Type checking passed # ✓ Evaluation successful # -# Agent Summary: +# Agent Summary # Role: senior code reviewer # Model: claude-opus-4-5-20251101 # Max tokens: 4096 # Temperature: 0.7 -``` +```text ### 3. Transpile to Nickel @@ -74,7 +74,7 @@ echo '{"name":"Bob"}' | ./target/release/typedialog-ag agents/greeting.agent.mdx ./target/release/typedialog-ag transpile agents/architect.agent.mdx # Output: Nickel code with full configuration -``` +```text ### 4. HTTP Server Mode @@ -82,7 +82,7 @@ Start the server: ```bash ./target/release/typedialog-ag serve --port 8765 -``` +```text Output: @@ -114,7 +114,7 @@ Output: POST /validate - Validate agent file Press Ctrl+C to stop the server -``` +```text ### 5. HTTP API Examples @@ -126,7 +126,7 @@ curl -X POST http://localhost:8765/agents/greeting/execute \ -d '{ "name": "Alice" }' -``` +```text Response: @@ -141,7 +141,7 @@ Response: "model": "claude-3-5-haiku-20241022" } } -``` +```text #### Code Review @@ -152,7 +152,7 @@ curl -X POST http://localhost:8765/agents/code-reviewer/execute \ "language": "rust", "code": "fn add(a: i32, b: i32) -> i32 { a + b }" }' -``` +```text Response includes structured review with sections: @@ -169,7 +169,7 @@ curl -X POST http://localhost:8765/agents/architect/execute \ "feature": "Real-time collaborative document editor", "tech_stack": "Rust, WebSockets, PostgreSQL, Redis" }' -``` +```text Response includes: @@ -188,7 +188,7 @@ curl -X POST http://localhost:8765/agents/test-generator/execute \ "language": "python", "function_code": "def factorial(n):\n return 1 if n == 0 else n * factorial(n-1)" }' -``` +```text #### Debug Code @@ -200,7 +200,7 @@ curl -X POST http://localhost:8765/agents/debugger/execute \ "code": "let v = vec![1,2,3]; println!(\"{}\", v[5]);", "error": "index out of bounds: the len is 3 but the index is 5" }' -``` +```text Response includes: @@ -219,7 +219,7 @@ curl -X POST http://localhost:8765/agents/refactor/execute \ "code": "function calc(a,b,op){if(op=='+')return a+b;if(op=='-')return a-b;}", "goal": "Improve type safety and readability" }' -``` +```text ## Cache Management @@ -229,24 +229,24 @@ TypeDialog automatically caches transpiled Nickel code for faster execution: # View cache statistics ./target/release/typedialog-ag cache stats -# Output: +# Output # 📊 Cache Statistics # -# Strategy: +# Strategy # Both { max_entries: 1000, cache_dir: "/Users/.../.typeagent/cache" } # -# Entries: +# Entries # Memory: 5 # Disk: 9 # Total: 14 # -# Location: +# Location # /Users/.../.typeagent/cache # Size: 12.34 KB # Clear cache ./target/release/typedialog-ag cache clear -``` +```text ## Advanced Features @@ -257,7 +257,7 @@ Agents support optional inputs with `?` suffix: ```mdx @input feature: String @input tech_stack?: String # Optional -``` +```text Usage: @@ -269,7 +269,7 @@ curl -X POST http://localhost:8765/agents/architect/execute \ # Without optional input (uses default) curl -X POST http://localhost:8765/agents/architect/execute \ -d '{"feature":"Chat"}' -``` +```text ### Conditional Template Logic @@ -281,7 +281,7 @@ Agents use Tera templates (Jinja2-like): {% else %} **Tech Stack**: Choose appropriate technologies {% endif %} -``` +```text ### Output Validation @@ -294,7 +294,7 @@ Agents enforce quality with validation rules: min_length: 100, max_length: 5000 } -``` +```text ## Performance @@ -306,7 +306,7 @@ Transpile: ~10ms Evaluate: ~15ms LLM Execution: ~2000ms (varies by model) Total: ~2030ms -``` +```text ### Subsequent Runs (Cached) @@ -315,7 +315,7 @@ Cache Hit: ~0ms (instant) Evaluate: ~15ms LLM Execution: ~2000ms Total: ~2015ms (15ms faster) -``` +```text ### Speedup @@ -329,7 +329,7 @@ Run the comprehensive test suite: ```bash ./test-agents.sh -``` +```text Output: @@ -349,7 +349,7 @@ Test 4: HTTP Server endpoints... ✓ All endpoints operational === All tests passed! === -``` +```text ## Creating Custom Agents @@ -374,13 +374,13 @@ Test 4: HTTP Server endpoints... --- Your prompt template here using {{ task }} and {{ context }}. -``` +```text ### 2. Validate ```bash typedialog-ag validate agents/my-agent.agent.mdx -``` +```text ### 3. Test @@ -391,7 +391,7 @@ typedialog-ag agents/my-agent.agent.mdx # HTTP curl -X POST http://localhost:8765/agents/my-agent/execute \ -d '{"task":"Explain Rust ownership"}' -``` +```text ## Model Selection Guide @@ -426,18 +426,18 @@ curl -X POST http://localhost:8765/agents/my-agent/execute \ # Check validation typedialog-ag validate agents/your-agent.agent.mdx -# Common issues: +# Common issues # - Missing API key: export ANTHROPIC_API_KEY=... # - Invalid syntax: Check MDX format # - Wrong model name: Use exact model IDs -``` +```text ### Cache issues ```bash # Clear cache and retry typedialog-ag cache clear -``` +```text ### Server won't start @@ -447,7 +447,7 @@ lsof -i :8765 # Use different port typedialog-ag serve --port 9000 -``` +```text ## Next Steps diff --git a/docs/release.md b/docs/release.md index db0ffee..c13e877 100644 --- a/docs/release.md +++ b/docs/release.md @@ -27,7 +27,7 @@ just distro::build-release # Or cross-compile all platforms just distro::cross -``` +```text **Output**: Binaries in `target/release/` @@ -38,7 +38,7 @@ Package includes binaries, configs, and installers: ```bash # Create distribution just distro::create-package -``` +```text **Output:** `distribution/typedialog-0.1.0/` @@ -61,7 +61,7 @@ just distro::create-checksums # Prepare release just distro::package-release -``` +```text **Output:** `release/` @@ -70,7 +70,7 @@ release/ ├── typedialog-0.1.0.tar.gz # Distribution package ├── SHA256SUMS # Checksums └── RELEASE_NOTES.md # Release documentation -``` +```text ### Checksums @@ -83,7 +83,7 @@ sha256sum -c SHA256SUMS # For users sha256sum typedialog-0.1.0.tar.gz # Compare with SHA256SUMS -``` +```text ### Release Notes @@ -98,7 +98,7 @@ Edit `release/RELEASE_NOTES.md` if needed: ```bash nano release/RELEASE_NOTES.md -``` +```text ## Stage 4: GitHub Release @@ -111,7 +111,7 @@ gh release create v0.1.0 \ release/SHA256SUMS \ --title "TypeDialog 0.1.0" \ --notes-file release/RELEASE_NOTES.md -``` +```text ### Create Release via Web UI @@ -170,7 +170,7 @@ gh release create v0.1.0 \ # 10. Verify installation works curl -fsSL https://github.com/anthropics/typedialog/releases/download/v0.1.0/install.sh | bash typedialog --version -``` +```text ## Installation Verification @@ -186,7 +186,7 @@ curl -fsSL https://github.com/anthropics/typedialog/releases/download/v0.1.0/ins typedialog --version typedialog-tui --version typedialog-web --version -``` +```text ### Windows PowerShell @@ -198,7 +198,7 @@ irm https://github.com/anthropics/typedialog/releases/download/v0.1.0/install.ps typedialog --version typedialog-tui --version typedialog-web --version -``` +```text ### Manual Installation @@ -212,7 +212,7 @@ bash installers/install.sh # Verify typedialog --version -``` +```text ## Distribution Structure @@ -242,7 +242,7 @@ typedialog-0.1.0/ │ ├── install.ps1 # Windows │ └── README.md # Instructions └── MANIFEST.json # Metadata -``` +```text ### MANIFEST.json @@ -258,7 +258,7 @@ Package metadata with structure and contents: "configs": {...}, "installers": {...} } -``` +```text ## Security Considerations @@ -268,13 +268,13 @@ Always provide checksums: ```bash sha256sum typedialog-0.1.0.tar.gz > SHA256SUMS -``` +```text Users verify with: ```bash sha256sum -c SHA256SUMS -``` +```text ### Installation Scripts @@ -286,7 +286,7 @@ less installers/bootstrap/install.sh # Windows less installers/bootstrap/install.ps1 -``` +```text ### Production Configurations @@ -299,7 +299,7 @@ require_https = true csrf_enabled = true rate_limit = 100 add_security_headers = true -``` +```text See [configuration.md](configuration.md) for all settings. @@ -343,7 +343,7 @@ jobs: release/SHA256SUMS env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} -``` +```text ## Troubleshooting @@ -354,7 +354,7 @@ Ensure files exist in `release/`: ```bash just distro::list-packages ls -la release/ -``` +```text ### Checksum mismatch @@ -362,7 +362,7 @@ Regenerate checksums: ```bash just distro::create-checksums -``` +```text ### Installation script fails @@ -374,7 +374,7 @@ bash installers/bootstrap/install.sh # Windows pwsh installers/bootstrap/install.ps1 -``` +```text ### GitHub release failed @@ -383,7 +383,7 @@ Check permissions: ```bash gh auth status gh release list -``` +```text ## Release Checklist @@ -441,7 +441,7 @@ sha256sum -c SHA256SUMS - Linux x86_64, ARM64 - macOS Intel, Apple Silicon - Windows x86_64 -``` +```text ## Next Steps diff --git a/docs/tui/README.md b/docs/tui/README.md index e5fe3e2..14a9200 100644 --- a/docs/tui/README.md +++ b/docs/tui/README.md @@ -26,7 +26,7 @@ sudo cp target/release/typedialog-tui /usr/local/bin/ # Or use just just build::tui -``` +```text ### Basic Usage @@ -39,7 +39,7 @@ typedialog-tui --theme dark examples/form.toml # Output to file typedialog-tui form.toml > output.json -``` +```text ## Keyboard Shortcuts @@ -92,7 +92,7 @@ typedialog-tui form.toml > output.json ```toml [form] border_style = "rounded" # rounded, double, thick, or none -``` +```text ### Themes @@ -101,7 +101,7 @@ border_style = "rounded" # rounded, double, thick, or none theme = "dark" # dark, light, or custom highlight_color = "cyan" error_color = "red" -``` +```text ### Field Highlighting @@ -126,13 +126,13 @@ name = "role" field_type = "Select" label = "Role" options = ["Admin", "User", "Guest"] -``` +```text Run it: ```bash typedialog-tui simple.toml -``` +```text ### Multi-Page Form @@ -148,7 +148,7 @@ title = "Account Settings" [[sections.fields]] name = "email" field_type = "Text" -``` +```text Navigate with `→/←` or `Tab`. @@ -169,7 +169,7 @@ field_type = "Text" name = "port" field_type = "Text" validation = "number" -``` +```text Interface shows: @@ -194,13 +194,13 @@ submit = "Enter" cancel = "Esc" next_field = "Tab" prev_field = "Shift+Tab" -``` +```text Or per-form: ```bash typedialog-tui form.toml --config config/tui/custom.toml -``` +```text ## Backend-Specific Features @@ -216,7 +216,7 @@ For RepeatingGroups, the TUI uses a split-pane layout: ├───────────────┴─────────────────────┤ │ a=add e=edit d=delete Enter=edit │ └──────────────────────────────────────┘ -``` +```text ### Mouse Support @@ -233,7 +233,7 @@ Disable with: ```toml [tui] mouse_enabled = false -``` +```text ### Terminal Resize Handling @@ -247,7 +247,7 @@ System monitoring dashboards with live data updates: ```bash typedialog-tui monitoring.toml --watch -``` +```text ### 2. Configuration Wizards @@ -255,7 +255,7 @@ Multi-step configuration with validation: ```bash typedialog-tui setup-wizard.toml --output config.toml -``` +```text ### 3. Server Administration @@ -263,7 +263,7 @@ SSH server management with terminal UI: ```bash ssh admin@server 'typedialog-tui /etc/myapp/config.toml' -``` +```text ### 4. Development Tools @@ -271,7 +271,7 @@ Interactive tools for developers: ```bash typedialog-tui project-init.toml --format nickel > project.ncl -``` +```text ## More examples @@ -288,7 +288,7 @@ See [examples/04-backends/tui/](../../examples/04-backends/tui/) for: - [Installation](../installation.md) - Setup guide - [Configuration](../configuration.md) - TUI configuration options -- [Field Types](../field_types.md) - Available field types +- [Field Types](../field-types.md) - Available field types - [Examples](../../examples/04-backends/tui/) - Working examples ## Troubleshooting @@ -305,7 +305,7 @@ Reset terminal: reset # Or tput reset -``` +```text ### "Mouse not working" @@ -314,7 +314,7 @@ Enable mouse support: ```toml [tui] mouse_enabled = true -``` +```text ### "Colors not showing" @@ -322,13 +322,13 @@ Ensure 256-color terminal: ```bash echo $TERM # Should be something like xterm-256color -``` +```text Set if needed: ```bash export TERM=xterm-256color -``` +```text ### "Form too large for terminal" diff --git a/docs/web/README.md b/docs/web/README.md index 7811b46..aedc273 100644 --- a/docs/web/README.md +++ b/docs/web/README.md @@ -27,7 +27,7 @@ sudo cp target/release/typedialog-web /usr/local/bin/ # Or use just just build::web -``` +```text ### Basic Usage @@ -43,7 +43,7 @@ typedialog-web --config form.toml --tls-cert cert.pem --tls-key key.pem # From config file typedialog-web --config config/web/production.toml -``` +```text ## Server Endpoints @@ -83,7 +83,7 @@ allow_headers = ["Content-Type"] [web.session] secret_key = "change-me-in-production" timeout_seconds = 3600 -``` +```text ### TLS/HTTPS Config @@ -92,7 +92,7 @@ timeout_seconds = 3600 enabled = true cert_path = "/path/to/cert.pem" key_path = "/path/to/key.pem" -``` +```text ### Form Config @@ -109,7 +109,7 @@ field_type = "Text" label = "Email" validation = "email" required = true -``` +```text ## API Usage @@ -117,7 +117,7 @@ required = true ```bash curl http://localhost:3000/api/form -``` +```text Response: @@ -128,7 +128,7 @@ Response: "fields": [...] } } -``` +```text ### Submit Form @@ -136,7 +136,7 @@ Response: curl -X POST http://localhost:3000/submit \ -H "Content-Type: application/json" \ -d '{"name":"John","email":"john@example.com"}' -``` +```text Response: @@ -148,7 +148,7 @@ Response: "email": "john@example.com" } } -``` +```text ### Validate Field @@ -156,7 +156,7 @@ Response: curl -X POST http://localhost:3000/api/validate \ -H "Content-Type: application/json" \ -d '{"field":"email","value":"invalid"}' -``` +```text Response: @@ -165,7 +165,7 @@ Response: "valid": false, "error": "Invalid email format" } -``` +```text ## Frontend Features @@ -204,7 +204,7 @@ input.addEventListener('blur', async () => { showError(result.error); } }); -``` +```text ### RepeatingGroups @@ -218,7 +218,7 @@ The web backend renders RepeatingGroups as inline expandable cards: -``` +```text Features: @@ -270,7 +270,7 @@ Custom CSS for forms: border-radius: 4px; cursor: pointer; } -``` +```text ## Deployment @@ -278,7 +278,7 @@ Custom CSS for forms: ```bash typedialog-web --config config/web/dev.toml -``` +```text ### Production @@ -292,7 +292,7 @@ typedialog-web \ --tls-cert /etc/ssl/cert.pem \ --tls-key /etc/ssl/key.pem \ --port 443 -``` +```text ### Docker @@ -304,7 +304,7 @@ docker build -t typedialog-web . docker run -p 3000:3000 \ -v $(pwd)/config:/config \ typedialog-web --config /config/web/production.toml -``` +```text ### Reverse Proxy (Nginx) @@ -321,7 +321,7 @@ server { proxy_set_header X-Forwarded-Proto $scheme; } } -``` +```text ## Use Cases @@ -331,7 +331,7 @@ Customer onboarding forms with validation: ```bash typedialog-web --config saas/onboarding.toml --port 443 --tls -``` +```text ### 2. Internal Tools @@ -339,7 +339,7 @@ Admin panels and configuration interfaces: ```bash typedialog-web --config admin/settings.toml --host 0.0.0.0 -``` +```text ### 3. Public Forms @@ -347,7 +347,7 @@ Contact forms, surveys, registrations: ```bash typedialog-web --config public/contact.toml -``` +```text ### 4. API Integration @@ -355,7 +355,7 @@ Headless forms with JSON API: ```bash curl http://localhost:3000/api/form | jq . -``` +```text ## Security @@ -368,7 +368,7 @@ Always use HTTPS in production: enabled = true cert_path = "/etc/ssl/cert.pem" key_path = "/etc/ssl/key.pem" -``` +```text ### CORS @@ -379,7 +379,7 @@ Configure CORS for cross-origin requests: allow_origin = "https://example.com" allow_methods = ["GET", "POST"] allow_headers = ["Content-Type", "Authorization"] -``` +```text ### Session Security @@ -391,7 +391,7 @@ secret_key = "generate-random-32-byte-key" timeout_seconds = 1800 # 30 minutes secure_cookies = true http_only = true -``` +```text ### Input Validation @@ -406,7 +406,7 @@ required = true [[fields]] name = "age" validation = "range(18..120)" -``` +```text ## Examples @@ -423,7 +423,7 @@ See [examples/04-backends/web/](../../examples/04-backends/web/) for: - [Installation](../installation.md) - Setup guide - [Configuration](../configuration.md) - Web configuration options -- [Field Types](../field_types.md) - Available field types +- [Field Types](../field-types.md) - Available field types - [Encryption](../encryption/) - Secure field handling - [Examples](../../examples/04-backends/web/) - Working examples @@ -435,7 +435,7 @@ Port is occupied. Use different port: ```bash typedialog-web --config form.toml --port 8080 -``` +```text ### "TLS certificate error" @@ -443,7 +443,7 @@ Check cert paths and permissions: ```bash ls -l /path/to/cert.pem /path/to/key.pem -``` +```text ### "CORS error" @@ -452,7 +452,7 @@ Configure CORS in config: ```toml [web.cors] allow_origin = "http://localhost:3000" -``` +```text ### "Form not submitting" @@ -465,7 +465,7 @@ Increase session timeout: ```toml [web.session] timeout_seconds = 7200 # 2 hours -``` +```text --- diff --git a/examples/01-basic/README.md b/examples/01-basic/README.md index 9f9576f..60a5e77 100644 --- a/examples/01-basic/README.md +++ b/examples/01-basic/README.md @@ -15,18 +15,18 @@ Simple form examples for getting started with typedialog. ### CLI Backend ```bash cargo run --example form -``` +```text ### TUI Backend ```bash cargo run -p typedialog-tui --example tui_survey_form -``` +```text ### Web Backend Build your form in TOML and serve with the web backend: ```bash cargo run -p typedialog-web -- --config form.toml -``` +```text ## Features Demonstrated diff --git a/examples/02-advanced/README.md b/examples/02-advanced/README.md index 8f5d863..3aac4b1 100644 --- a/examples/02-advanced/README.md +++ b/examples/02-advanced/README.md @@ -21,12 +21,12 @@ cargo run --example conditional_form # Web cargo run -p typedialog-web -- --config conditional_form.toml -``` +```text ### Rust Examples (with full control) ```bash cargo run --example conditional_required_demo -``` +```text ## Features Demonstrated @@ -50,7 +50,7 @@ type = "number" label = "Years of Experience" visible_when = { experience = "Senior" } required_when = { experience = "Senior" } -``` +```text ### Conditional Section Example ```toml @@ -59,4 +59,4 @@ visible_when = { show_advanced = true } [sections.advanced_options.fields.custom_setting] type = "text" -``` +```text diff --git a/examples/03-styling/README.md b/examples/03-styling/README.md index 996eba1..c7fca2e 100644 --- a/examples/03-styling/README.md +++ b/examples/03-styling/README.md @@ -13,12 +13,12 @@ Examples of custom borders, themes, and visual styling. ```bash cargo run --example custom_border_form cargo run --example fancy_borders_form -``` +```text ### Web Backend ```bash cargo run -p typedialog-web -- --config custom_border_form.toml -``` +```text ## Features Demonstrated @@ -42,4 +42,4 @@ Example: [sections.main] title = "Main Section" border = "double" -``` +```text diff --git a/examples/04-backends/README.md b/examples/04-backends/README.md index b78fe95..1cdf527 100644 --- a/examples/04-backends/README.md +++ b/examples/04-backends/README.md @@ -36,12 +36,12 @@ Each backend can use TOML form definitions or Rust code: **TOML** - Configuration-driven (faster iteration): ```bash cargo run -p typedialog-web -- --config registration_form.toml -``` +```text **Rust** - Programmatic control (advanced customization): ```bash cargo run --example form_with_autocompletion -``` +```text ## Feature Compatibility Matrix diff --git a/examples/04-backends/cli/README.md b/examples/04-backends/cli/README.md index 32b0475..db50619 100644 --- a/examples/04-backends/cli/README.md +++ b/examples/04-backends/cli/README.md @@ -10,7 +10,7 @@ Command-line interface form examples. ```bash cargo run --example autocompletion_demo -``` +```text ## Features diff --git a/examples/04-backends/tui/README.md b/examples/04-backends/tui/README.md index 117aeaa..c142508 100644 --- a/examples/04-backends/tui/README.md +++ b/examples/04-backends/tui/README.md @@ -11,7 +11,7 @@ Text User Interface form examples - interactive terminal-based forms. ```bash cargo run -p typedialog-tui --example form_with_autocompletion -``` +```text ## Features diff --git a/examples/04-backends/web/README.md b/examples/04-backends/web/README.md index 709db28..cf2f20d 100644 --- a/examples/04-backends/web/README.md +++ b/examples/04-backends/web/README.md @@ -10,7 +10,7 @@ Web-based form rendering examples using HTML/CSS. ```bash cargo run -p typedialog-web -- --config web_registration_form.toml -``` +```text Then open browser to `http://localhost:3000` (or configured port). @@ -47,7 +47,7 @@ type = "email" label = "Email Address" placeholder = "you@example.com" help_text = "We'll never share your email" -``` +```text ## Integration diff --git a/examples/05-fragments/README.md b/examples/05-fragments/README.md index 08fc192..24c5c33 100644 --- a/examples/05-fragments/README.md +++ b/examples/05-fragments/README.md @@ -34,18 +34,18 @@ agreement = "fragments/agreement_section.toml" [sections.main] title = "Employee Onboarding" -``` +```text ### Build Complex Forms from Reusable Parts ```bash # Each fragment can be tested independently cargo run --example form_with_groups_includes -``` +```text ## Constraint Interpolation Example -### What is Constraint Interpolation? +### What is Constraint Interpolation Instead of hardcoding validation limits in forms, you can use constraint variables: @@ -55,7 +55,7 @@ Instead of hardcoding validation limits in forms, you can use constraint variabl name = "udp_trackers" type = "repeatinggroup" max_items = "${constraint.tracker.udp.max_items}" # ← Dynamic constraint reference -``` +```text ### Single Source of Truth @@ -65,7 +65,7 @@ All validation limits are defined in **one file**: # constraints.toml [tracker.udp] max_items = 4 # Change this value, form auto-updates! -``` +```text ### How It Works @@ -80,16 +80,16 @@ max_items = 4 # Change this value, form auto-updates! # Run the example cargo run --example array-trackers -# The form will allow: +# The form will allow # - 0-4 UDP trackers (from constraints.tracker.udp.max_items) # - 0-4 HTTP trackers (from constraints.tracker.http.max_items) -# Change constraints.toml: +# Change constraints.toml # [tracker.udp] # max_items = 6 # ← Change from 4 to 6 # # Re-run the example - form now allows 0-6 UDP trackers! -``` +```text ### Key Files diff --git a/examples/06-integrations/i18n/README.md b/examples/06-integrations/i18n/README.md index 0c3abe6..3ea2ef2 100644 --- a/examples/06-integrations/i18n/README.md +++ b/examples/06-integrations/i18n/README.md @@ -20,7 +20,7 @@ LANG=es cargo run --example test_i18n_form # French LANG=fr cargo run --example test_i18n_form -``` +```text ## Form Definition with i18n @@ -31,19 +31,19 @@ Forms use language keys instead of hardcoded text: type = "email" label = "fields.email.label" # References translation key help_text = "fields.email.help" -``` +```text ## Translation Files Translations are stored in `locales/` directory: -``` +```text locales/ ├── en.json ├── es.json ├── fr.json └── de.json -``` +```text ## Translation Format @@ -56,7 +56,7 @@ locales/ } } } -``` +```text ## Supported Languages diff --git a/examples/06-integrations/nickel/README.md b/examples/06-integrations/nickel/README.md index a3dfd82..1630111 100644 --- a/examples/06-integrations/nickel/README.md +++ b/examples/06-integrations/nickel/README.md @@ -30,7 +30,7 @@ nickel eval nickel_schema.ncl > form_config.toml # Run form cargo run -p typedialog-web -- --config form_config.toml -``` +```text ### Roundtrip Workflow (Edit Existing Configs) @@ -57,7 +57,7 @@ typedialog-web nickel-roundtrip \ --form ci-form.toml \ --output config.ncl \ --ncl-template config.ncl.j2 -``` +```text **Features:** @@ -85,7 +85,7 @@ typedialog-web nickel-roundtrip \ } } } -``` +```text ## Benefits diff --git a/examples/07-nickel-generation/README.md b/examples/07-nickel-generation/README.md index e0689e8..53e1d2b 100644 --- a/examples/07-nickel-generation/README.md +++ b/examples/07-nickel-generation/README.md @@ -2,9 +2,9 @@ This directory contains complete, runnable examples of the TypeDialog Nickel integration workflow: -``` +```text Nickel Schema → TOML Form → User Input → JSON Results → Nickel Output -``` +```text ## Quick Start @@ -21,7 +21,7 @@ typedialog form generated/simple/form.toml -o results/simple_results.json # View results cat results/simple_results.json | jq . -``` +```text **What it demonstrates**: - Basic type mapping (String, Number, Bool) @@ -43,7 +43,7 @@ ls -la generated/complex/fragments/ # Execute main form typedialog form generated/complex/main_form.toml -o results/complex_results.json -``` +```text **What it demonstrates**: - Fragment markers (`# @fragment: name`) @@ -52,7 +52,7 @@ typedialog form generated/complex/main_form.toml -o results/complex_results.json - Large schema organization **Generated structure**: -``` +```text generated/complex/ ├── main_form.toml # Form with includes └── fragments/ @@ -60,7 +60,7 @@ generated/complex/ ├── server_config.toml ├── database_config.toml └── cache_config.toml -``` +```text ### Example 3: Conditional Fields (Smart Visibility) @@ -75,7 +75,7 @@ grep -A 2 'when =' generated/conditional/form.toml # Execute form - notice conditional visibility typedialog form generated/conditional/form.toml -``` +```text **What it demonstrates**: - Optional field handling @@ -92,7 +92,7 @@ when = "tls_enabled == true" # Auto-generated! [[fields]] name = "database_url" when = "database_enabled == true" # Auto-generated! -``` +```text ### Example 4: i18n Extraction (Multi-Language) @@ -109,7 +109,7 @@ cat generated/i18n/locales/es/forms.ftl # Execute with Spanish locale LOCALE=es typedialog form generated/i18n/form.toml -``` +```text **What it demonstrates**: - Multi-language doc comment parsing @@ -126,7 +126,7 @@ app-name-help = Enter the application display name # es/forms.ftl app-name-prompt = Nombre de la aplicación app-name-help = Ingrese el nombre de la aplicación -``` +```text ### Example 5: Full Workflow (Schema → Results → Nickel) @@ -144,7 +144,7 @@ nickel typecheck generated/output_config.ncl # View generated configuration cat generated/output_config.ncl -``` +```text **What it demonstrates**: - End-to-end workflow automation @@ -155,7 +155,7 @@ cat generated/output_config.ncl ## Directory Structure -``` +```text examples/07-nickel-generation/ ├── README.md # This file ├── schemas/ # Nickel schema files @@ -180,7 +180,7 @@ examples/07-nickel-generation/ │ └── locales/ └── results/ # Example results (reference) └── simple_results.json -``` +```text ## Schema Features Explained @@ -191,7 +191,7 @@ Mark sections for automatic splitting: ```nickel # @fragment: database_config database = { ... } -``` +```text Generates separate file: `fragments/database_config.toml` @@ -210,14 +210,14 @@ tls_enabled | doc "Enable TLS" : Bool, tls_cert | optional | doc "Certificate path" : String, -``` +```text Generates: ```toml [[fields]] name = "tls_cert" when = "tls_enabled == true" -``` +```text **Pattern**: `_enabled` → dependent fields @@ -230,7 +230,7 @@ field_name | doc "English text" | doc.es "Texto en español" : String -``` +```text Generates `.ftl` files for each locale with translations @@ -250,7 +250,7 @@ just nickel::nickel-workflow \ schemas/simple.ncl \ templates/config.ncl.j2 \ config.ncl -``` +```text ### service_spec.ncl.j2 @@ -265,7 +265,7 @@ Kubernetes service specification: typedialog form
-o results.json typedialog nickel-template templates/service_spec.ncl.j2 results.json -o service.ncl nickel export service.ncl -``` +```text ### deployment.ncl.j2 @@ -283,7 +283,7 @@ just nickel::nickel-workflow \ \ templates/deployment.ncl.j2 \ deployment.ncl -``` +```text ## Common Workflows @@ -295,7 +295,7 @@ just nickel::nickel-preview schemas/complex.ncl # Then generate with full options just nickel::nickel-to-form schemas/complex.ncl generated/complex/ -``` +```text ### Extract i18n Only @@ -306,7 +306,7 @@ just nickel::nickel-i18n schemas/i18n.ncl translations/ # Review translations cat translations/locales/en/forms.ftl cat translations/locales/es/forms.ftl -``` +```text ### Render Template with Sample Data @@ -318,7 +318,7 @@ typedialog nickel-template templates/config.ncl.j2 \ # Review output cat sample_output.ncl -``` +```text ### Full Interactive Workflow @@ -342,7 +342,7 @@ nickel typecheck /tmp/generated_config.ncl # 6. Export to JSON nickel export /tmp/generated_config.ncl -``` +```text ## Testing Examples @@ -377,7 +377,7 @@ just nickel::nickel-i18n "$EXAMPLES_DIR/schemas/i18n.ncl" /tmp/test_i18n echo "" echo "All tests passed!" -``` +```text ## Extending Examples @@ -399,7 +399,7 @@ echo "All tests passed!" | doc "Feature configuration" : String, } -``` +```text ### Adding New Templates @@ -416,7 +416,7 @@ echo "All tests passed!" {% endfor %} }, } -``` +```text ## Troubleshooting @@ -428,7 +428,7 @@ nickel typecheck schemas/simple.ncl # Check for schema-specific issues nickel query schemas/simple.ncl -``` +```text ### Fragment Includes Not Found @@ -438,7 +438,7 @@ ls -la generated/complex/fragments/ # Check include paths in main form grep includes generated/complex/main_form.toml -``` +```text ### Conditionals Not Generated @@ -448,7 +448,7 @@ grep -A 2 "optional" schemas/conditional.ncl # Check for boolean enable flags grep "_enabled" schemas/conditional.ncl -``` +```text ### i18n Not Working @@ -458,7 +458,7 @@ find generated/i18n/locales/ -name "*.ftl" # Check .ftl file format cat generated/i18n/locales/en/forms.ftl | head -``` +```text ## See Also diff --git a/examples/07-nickel-generation/arrays-schema.ncl b/examples/07-nickel-generation/arrays-schema.ncl index 14bd4ae..712241e 100644 --- a/examples/07-nickel-generation/arrays-schema.ncl +++ b/examples/07-nickel-generation/arrays-schema.ncl @@ -82,9 +82,7 @@ api_token | String, # API port number (1024-65535) - api_port | Number - | std.number.is_between 1024 65535 ? - | "API port must be between 1024 and 65535", + api_port | Number, # Array of API endpoints exposed by the service # In TypeDialog: RepeatingGroup field with fragment defining ApiEndpoint fields diff --git a/examples/07-nickel-generation/schemas/i18n.ncl b/examples/07-nickel-generation/schemas/i18n.ncl index 89a487e..ca1ffb6 100644 --- a/examples/07-nickel-generation/schemas/i18n.ncl +++ b/examples/07-nickel-generation/schemas/i18n.ncl @@ -2,48 +2,39 @@ # Demonstrates multi-language form generation with Fluent { - app_name - | doc "Application name" - | doc.es "Nombre de la aplicación" - : String, + app_name = "" + | doc "Application name / Nombre de la aplicación" + | String, - app_version - | doc "Application version" - | doc.es "Versión de la aplicación" - : String = "1.0.0", + app_version = "1.0.0" + | doc "Application version / Versión de la aplicación" + | String, - server_host - | doc "Server host address" - | doc.es "Dirección del host del servidor" - : String = "0.0.0.0", + server_host = "0.0.0.0" + | doc "Server host address / Dirección del host del servidor" + | String, - server_port - | doc "Server port number" - | doc.es "Número de puerto del servidor" - : Number = 8080, + server_port = 8080 + | doc "Server port number / Número de puerto del servidor" + | Number, - database_url - | doc "Database connection URL" - | doc.es "URL de conexión a la base de datos" - : String, + database_url = "" + | doc "Database connection URL / URL de conexión a la base de datos" + | String, - enable_caching - | doc "Enable caching layer" - | doc.es "Habilitar capa de caché" - : Bool = true, + enable_caching = true + | doc "Enable caching layer / Habilitar capa de caché" + | Bool, - cache_ttl - | doc "Cache time-to-live in seconds" - | doc.es "Tiempo de vida del caché en segundos" - : Number = 3600, + cache_ttl = 3600 + | doc "Cache time-to-live in seconds / Tiempo de vida del caché en segundos" + | Number, - admin_email - | doc "Administrator email address" - | doc.es "Dirección de correo del administrador" - : String, + admin_email = "" + | doc "Administrator email address / Dirección de correo del administrador" + | String, - enable_notifications - | doc "Enable email notifications" - | doc.es "Habilitar notificaciones por correo" - : Bool = false, + enable_notifications = false + | doc "Enable email notifications / Habilitar notificaciones por correo" + | Bool, } diff --git a/examples/08-encryption/README.md b/examples/08-encryption/README.md index e2d4ad6..50c73fa 100644 --- a/examples/08-encryption/README.md +++ b/examples/08-encryption/README.md @@ -8,12 +8,12 @@ This directory contains example forms demonstrating typedialog's encryption and # Redaction: Replace sensitive values with [REDACTED] typedialog form examples/08-encryption/simple-login.toml --redact --format json -# Expected output: +# Expected output # { # "username": "alice", # "password": "[REDACTED]" # } -``` +```text ## Setup Required @@ -22,7 +22,7 @@ Before running encryption tests, set up encryption services: ```bash ./scripts/encryption-test-setup.sh source /tmp/typedialog-env.sh -``` +```text ## Forms Included @@ -45,7 +45,7 @@ typedialog form examples/08-encryption/simple-login.toml \ typedialog form examples/08-encryption/simple-login.toml \ --encrypt --backend age --key-file ~/.age/key.txt \ --format json -``` +```text **Expected Behavior**: - Redaction: `password` shows `[REDACTED]` @@ -76,7 +76,7 @@ typedialog form examples/08-encryption/simple-login.toml \ typedialog form examples/08-encryption/credentials.toml \ --redact --format json -# Output format: +# Output format # { # "username": "alice", # "email": "alice@example.com", @@ -89,7 +89,7 @@ typedialog form examples/08-encryption/credentials.toml \ # "vault_token": "[REDACTED]", # "demo_password": "demo123" <- Not redacted (explicit sensitive=false) # } -``` +```text ```bash # Encrypt with Age backend @@ -98,7 +98,7 @@ typedialog form examples/08-encryption/credentials.toml \ --key-file ~/.age/key.txt \ --format json -# Output format: +# Output format # { # "username": "alice", # "email": "alice@example.com", @@ -106,30 +106,30 @@ typedialog form examples/08-encryption/credentials.toml \ # "api_token": "age1muz6ah54ew9am7mzmy0m4w5arcegt056l9448sqy5ju27q5qaf3qjv35tr", # ... # } -``` +```text ```bash # Encrypt with SOPS (supports AWS KMS, GCP KMS, Azure Key Vault) -# First, create .sops.yaml in project root: +# First, create .sops.yaml in project root cat > .sops.yaml << 'EOF' creation_rules: - path_regex: .* kms: arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012 EOF -# Then run: +# Then run export AWS_REGION=us-east-1 typedialog form examples/08-encryption/credentials.toml \ --encrypt --backend sops \ --format json -# Output format: +# Output format # { # "username": "alice", # "password": "sops:v1:4f5...", # ... # } -``` +```text ```bash # Or use SecretumVault Transit Engine (post-quantum cryptography ready) @@ -141,13 +141,13 @@ typedialog form examples/08-encryption/credentials.toml \ --vault-key-name "app-encryption-key" \ --format json -# Output format: +# Output format # { # "username": "alice", # "password": "vault:v1:K8...", # ... # } -``` +```text --- @@ -171,7 +171,7 @@ api_key | Sensitive Backend="secretumvault" Vault="https://vault:8200" Key="app- # AWS KMS (direct integration) vault_token | Sensitive Backend="awskms" Region="us-east-1" KeyId="arn:aws:kms:..." = "" -``` +```text **Usage**: @@ -183,7 +183,7 @@ nickel query examples/08-encryption/nickel-secrets.ncl inputs # (Requires nickel CLI and typedialog integration - future feature) # 3. Or manually convert to TOML matching this structure -``` +```text **Equivalent TOML representation**: ```toml @@ -195,7 +195,7 @@ encryption_backend = "age" [fields.encryption_config] key = "~/.age/key.txt" -``` +```text --- @@ -243,7 +243,7 @@ key = "~/.age/key.txt" "api_token": "[REDACTED]", "demo_password": "visible" } -``` +```text ### Age Encryption Output ```json @@ -254,7 +254,7 @@ key = "~/.age/key.txt" "api_token": "age1muz6ah54ew9am7mzmy0m4w5arcegt056l9448sqy5ju27q5qaf3qjv35tr", "demo_password": "visible" } -``` +```text ### SOPS Encryption Output ```json @@ -265,7 +265,7 @@ key = "~/.age/key.txt" "api_token": "sops:v1:5g6h7i8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6b7c8d9e0f1g2h3i4j5k", "demo_password": "visible" } -``` +```text ### SecretumVault Encryption Output ```json @@ -276,7 +276,7 @@ key = "~/.age/key.txt" "api_token": "vault:v1:KX1LZ8/PvEgMuKQBhDm8PQMLCMiSvE...", "demo_password": "visible" } -``` +```text --- @@ -310,4 +310,4 @@ if [ -f ~/.age/key.txt ]; then fi echo "All tests passed!" -``` +```text diff --git a/examples/08-encryption/SOPS-DEMO.md b/examples/08-encryption/SOPS-DEMO.md index e89614e..2be8e4f 100644 --- a/examples/08-encryption/SOPS-DEMO.md +++ b/examples/08-encryption/SOPS-DEMO.md @@ -13,7 +13,7 @@ brew install sops # Verify installation sops --version which age-keygen -``` +```text ### 2. Setup SOPS Configuration @@ -38,7 +38,7 @@ EOF # Verify config cat .sops.yaml -``` +```text ### 3. Test SOPS Encryption Manually @@ -58,7 +58,7 @@ sops -d test-secret.yaml # Cleanup rm test-secret.yaml -``` +```text **Expected Output:** ```yaml @@ -66,12 +66,12 @@ secret: ENC[AES256_GCM,data:xxxxx,iv:xxxxx,tag:xxxxx,type:str] sops: version: 3.9.0 ... -``` +```text When you decrypt, you should see: ```yaml secret: my-password-123 -``` +```text ### 4. Test typedialog with SOPS @@ -81,7 +81,7 @@ typedialog form examples/08-encryption/simple-login.toml \ --encrypt --backend sops \ --format json -# You'll be prompted for: +# You'll be prompted for # Username: alice # Password: secretpass123 @@ -90,28 +90,28 @@ typedialog form examples/08-encryption/simple-login.toml \ --redact \ --format json -# Output should show: +# Output should show # { # "username": "alice", # "password": "[REDACTED]" # } -``` +```text ### 5. Verify SOPS Ciphertext Format After encryption, check the output format: ```bash -# The encrypted password should look like: +# The encrypted password should look like # "sops:v1:4f5a6b7c8d9e0f1a2b3c4d5e6f..." -# This format is: +# This format is # - sops:v1: version prefix # - hex-encoded encrypted YAML content -# You can verify it's hex: +# You can verify it's hex echo "4f5a6b7c8d9e0f1a" | xxd -r -p -``` +```text --- @@ -131,7 +131,7 @@ sensitive = true encryption_backend = "sops" # SOPS reads configuration from .sops.yaml # No additional config needed -``` +```text Run with SOPS: @@ -139,7 +139,7 @@ Run with SOPS: typedialog form examples/08-encryption/credentials.toml \ --encrypt --backend sops \ --format json -``` +```text ### Field-Level Encryption @@ -170,7 +170,7 @@ encryption_backend = "awskms" [fields.encryption_config] region = "us-east-1" key_id = "arn:aws:kms:us-east-1:..." -``` +```text Same form, different backends per field! 🎉 @@ -189,7 +189,7 @@ creation_rules: kms: arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012 aws_region: us-east-1 EOF -``` +```text ### 2. Configure AWS Credentials @@ -205,7 +205,7 @@ export AWS_REGION=us-east-1 # Option C: IAM Role (on EC2/ECS) # Credentials automatically detected -``` +```text ### 3. Test with SOPS @@ -223,7 +223,7 @@ sops -d test.yaml typedialog form examples/08-encryption/simple-login.toml \ --encrypt --backend sops \ --format json -``` +```text --- @@ -238,7 +238,7 @@ creation_rules: gcp_kms: - resource_id: projects/MY_PROJECT/locations/global/keyRings/MY_KEYRING/cryptoKeys/MY_KEY EOF -``` +```text ### 2. Configure GCP Credentials @@ -248,14 +248,14 @@ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json # Option B: gcloud authentication gcloud auth application-default login -``` +```text ### 3. Test ```bash sops -e -i test.yaml sops -d test.yaml -``` +```text --- @@ -276,7 +276,7 @@ ls -la ~/.age/sops-key.txt # Or check .sops.yaml has correct public key cat .sops.yaml grep "^# public key:" ~/.age/sops-key.txt -``` +```text ### Problem: "config file not found" @@ -293,7 +293,7 @@ creation_rules: - path_regex: .* age: age1xxxxxxxxxxxxxxxxxxxxxx EOF -``` +```text ### Problem: typedialog says "SOPS encryption error: config file not found" @@ -311,7 +311,7 @@ EOF # Then run typedialog in the same directory typedialog form examples/08-encryption/simple-login.toml \ --encrypt --backend sops --format json -``` +```text ### Problem: "Backend 'sops' not available" @@ -324,7 +324,7 @@ brew install sops # Or rebuild typedialog with SOPS feature cargo build --features encryption,sops -``` +```text --- @@ -340,7 +340,7 @@ typedialog form examples/08-encryption/simple-login.toml --redact --format json age-keygen -o ~/.age/key.txt typedialog form examples/08-encryption/simple-login.toml \ --encrypt --backend age --key-file ~/.age/key.txt --format json -``` +```text ### With SOPS Backend @@ -362,14 +362,14 @@ sops -d test.yaml # Test with typedialog typedialog form examples/08-encryption/simple-login.toml \ --encrypt --backend sops --format json -``` +```text ### Full Integration Test ```bash # Run the integration test script bash examples/08-encryption/sops-integration-test.sh -``` +```text --- @@ -383,7 +383,7 @@ $ typedialog form examples/08-encryption/simple-login.toml --redact --format jso "username": "alice", "password": "[REDACTED]" } -``` +```text ### Age Encryption @@ -394,7 +394,7 @@ $ typedialog form examples/08-encryption/simple-login.toml \ "username": "alice", "password": "age1muz6ah54ew9am7mzmy0m4w5arcegt056l9448sqy5ju27q5qaf3qjv35tr" } -``` +```text ### SOPS Encryption @@ -405,7 +405,7 @@ $ typedialog form examples/08-encryption/simple-login.toml \ "username": "alice", "password": "sops:v1:4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f" } -``` +```text --- diff --git a/examples/08-encryption/TEST-SOPS-INTEGRATION.md b/examples/08-encryption/TEST-SOPS-INTEGRATION.md index 36671b7..ec2c0ff 100644 --- a/examples/08-encryption/TEST-SOPS-INTEGRATION.md +++ b/examples/08-encryption/TEST-SOPS-INTEGRATION.md @@ -23,7 +23,7 @@ age-keygen --version # Check typedialog is available which typedialog typedialog --version -``` +```text --- @@ -37,11 +37,11 @@ age-keygen -o ~/.age/sops-test-key.txt # View the key cat ~/.age/sops-test-key.txt -# Output: +# Output # # created: 2025-12-21T12:34:56Z # # public key: age1xxxxxxxxxxxxxxxxxxxxx # AGE-SECRET-KEY-xxxxxxxxxxxxxxxxxxxxx -``` +```text ### 1.2 Create `.sops.yaml` @@ -65,7 +65,7 @@ EOF # Verify config is correct cat .sops.yaml -``` +```text ### 1.3 Verify SOPS Configuration @@ -76,14 +76,14 @@ ls -la .sops.yaml # View the config cat .sops.yaml -``` +```text **Expected Output:** ```yaml creation_rules: - path_regex: .* age: age1xxxxxxxxxxxxxxxxxxxxx -``` +```text --- @@ -98,7 +98,7 @@ echo 'secret: my-super-secret-password' > test-secret.yaml # Verify content cat test-secret.yaml # Output: secret: my-super-secret-password -``` +```text ### 2.2 Encrypt with SOPS @@ -112,29 +112,29 @@ sops -e -i test-secret.yaml # Verify it's encrypted (should be YAML with ENC[...]) cat test-secret.yaml # Output should show: secret: ENC[AES256_GCM,data:xxxxx,iv:xxxxx,...] -``` +```text ### 2.3 Decrypt to Verify ```bash # Decrypt and display (doesn't modify file) sops -d test-secret.yaml -# Output: +# Output # secret: my-super-secret-password -# sops: +# sops # ... # Extract just the secret value sops -d test-secret.yaml | grep "^secret:" | sed 's/secret: //' # Output: my-super-secret-password -``` +```text ### 2.4 Clean Up ```bash # Remove test file rm test-secret.yaml -``` +```text **Key Points:** - ✅ SOPS encrypts/decrypts correctly @@ -154,16 +154,16 @@ echo -e "alice\nsecretpass123" | typedialog form examples/08-encryption/simple-l --redact \ --format json -# You'll see prompts: +# You'll see prompts # Username * # Password * # -# Output: +# Output # { # "username": "alice", # "password": "[REDACTED]" # } -``` +```text **What's being tested:** - ✅ typedialog can detect sensitive fields @@ -186,7 +186,7 @@ fi # Verify key exists cat ~/.age/key.txt -``` +```text ### 4.2 Encrypt with Age Backend @@ -197,12 +197,12 @@ echo -e "alice\nsecretpass123" | typedialog form examples/08-encryption/simple-l --key-file ~/.age/key.txt \ --format json -# Output: +# Output # { # "username": "alice", # "password": "age1muz6ah54ew9am7mzmy0m4w5arcegt056l9448sqy5ju27q5qaf3qjv35tr" # } -``` +```text **What's being tested:** - ✅ typedialog can encrypt with Age backend @@ -227,7 +227,7 @@ export SOPS_AGE_KEY_FILE=~/.age/sops-test-key.txt # Verify SOPS can find config sops --version -``` +```text ### 5.2 Encrypt with SOPS Backend @@ -237,15 +237,15 @@ echo -e "alice\nsecretpass123" | typedialog form examples/08-encryption/simple-l --encrypt --backend sops \ --format json -# If .sops.yaml is not found, you'll see: +# If .sops.yaml is not found, you'll see # SOPS encryption error: config file not found... # -# If successful, output: +# If successful, output # { # "username": "alice", # "password": "sops:v1:4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a..." # } -``` +```text **What's being tested:** - ✅ typedialog can use SOPS backend @@ -267,7 +267,7 @@ HEX_PART="4f5a6b7c8d9e0f1a2b3c..." # Decode from hex to see raw encrypted content echo "$HEX_PART" | xxd -r -p | head -c 100 # Shows SOPS-encrypted YAML structure -``` +```text --- @@ -281,12 +281,12 @@ Run the same form with different backends to see the difference. echo -e "alice\nsecretpass123" | typedialog form examples/08-encryption/simple-login.toml \ --redact --format json -# Output: +# Output # { # "username": "alice", # "password": "[REDACTED]" # } -``` +```text ### 6.2 Age @@ -294,12 +294,12 @@ echo -e "alice\nsecretpass123" | typedialog form examples/08-encryption/simple-l echo -e "alice\nsecretpass123" | typedialog form examples/08-encryption/simple-login.toml \ --encrypt --backend age --key-file ~/.age/key.txt --format json -# Output: +# Output # { # "username": "alice", # "password": "age1xxxxxxxx..." # } -``` +```text ### 6.3 SOPS @@ -309,12 +309,12 @@ export SOPS_AGE_KEY_FILE=~/.age/sops-test-key.txt echo -e "alice\nsecretpass123" | typedialog form examples/08-encryption/simple-login.toml \ --encrypt --backend sops --format json -# Output: +# Output # { # "username": "alice", # "password": "sops:v1:4f5a6b..." # } -``` +```text **Comparison:** | Backend | Format | Service Required | Use Case | @@ -335,11 +335,11 @@ Test a form with multiple encryption backends. # Use the multi-backend example cat examples/08-encryption/multi-backend-sops.toml -# This form demonstrates: +# This form demonstrates # - api_key: Age backend # - db_password: SOPS backend # - master_key: AWS KMS backend -``` +```text ### 7.2 Encrypt Different Fields with Different Backends @@ -350,11 +350,11 @@ echo -e "myapp\nproduction\nerror\ntestuser\ntestpass\napikey123" | \ --encrypt --backend sops \ --format json -# Output shows: +# Output shows # - api_key: field was encrypted (may show Error if backend not available) # - db_password: encrypted with SOPS (sops:v1:...) # - other fields: plain or encrypted based on field config -``` +```text --- @@ -368,12 +368,12 @@ Test that the Rust integration is working. # Test SOPS backend in encrypt crate cargo test -p encrypt --features sops --lib backend::sops -# Expected output: +# Expected output # test backend::sops::tests::test_sops_backend_name ... ok # test backend::sops::tests::test_sops_backend_info ... ok # ... more tests ... # test result: ok. 10 passed; 0 failed -``` +```text ### 8.2 Test Feature-Gating @@ -382,7 +382,7 @@ cargo test -p encrypt --features sops --lib backend::sops cargo test -p encrypt --features age test_is_available_sops # Should show SOPS is not available when feature disabled -``` +```text --- @@ -392,7 +392,7 @@ cargo test -p encrypt --features age test_is_available_sops ```bash # Error: config file not found, or has no creation rules -``` +```text **Cause**: `.sops.yaml` not found @@ -411,13 +411,13 @@ EOF # Or make sure you're in the correct directory pwd ls examples/08-encryption/ -``` +```text ### Problem: "no identity matched key" ```bash # Error: no identity matched key -``` +```text **Cause**: Age key not found or not accessible @@ -431,13 +431,13 @@ export SOPS_AGE_KEY_FILE=~/.age/sops-test-key.txt # Test SOPS directly sops -d test-secret.yaml -``` +```text ### Problem: typedialog times out or hangs ```bash # typedialog seems to be waiting for input -``` +```text **Cause**: stdin not properly piped @@ -451,13 +451,13 @@ typedialog form ... << EOF alice secretpass EOF -``` +```text ### Problem: "Backend 'sops' not available" ```bash # Error: Backend 'sops' not available -``` +```text **Cause**: 1. sops binary not installed @@ -474,7 +474,7 @@ cargo build --features encryption # Or check if typedialog was built with SOPS cargo build --features all -``` +```text --- diff --git a/examples/08-encryption/quick-sops-demo.sh b/examples/08-encryption/quick-sops-demo.sh index 9ce27df..a7e4f92 100755 --- a/examples/08-encryption/quick-sops-demo.sh +++ b/examples/08-encryption/quick-sops-demo.sh @@ -61,7 +61,7 @@ echo " Creating plaintext YAML file..." cat > "test-secret.yaml" << 'EOF' secret: my-super-secret-password-123 EOF -cat "test-secret.yaml" | sed 's/^/ /' +sed 's/^/ /' "test-secret.yaml" echo -e "\n Encrypting with SOPS..." export SOPS_AGE_KEY_FILE="$AGE_KEY_FILE" @@ -146,7 +146,9 @@ if [ -n "$PASSWORD_CT" ] && [ "$PASSWORD_CT" != "null" ]; then fi else echo -e "${YELLOW} ⚠ SOPS test output:\n${NC}" - echo "$OUTPUT" | sed 's/^/ /' + while IFS= read -r line; do + echo " $line" + done <<< "$OUTPUT" echo "" fi @@ -157,7 +159,7 @@ echo -e "${BLUE}========================================${NC}\n" echo "Demo directory: $DEMO_DIR" echo "Files created:" -ls -1h "$DEMO_DIR" | sed 's/^/ - /' +find "$DEMO_DIR" -maxdepth 1 -type f -printf ' - %f\n' | sort echo -e "\n${YELLOW}Key Takeaways:${NC}" echo " ✓ SOPS can encrypt/decrypt YAML files" @@ -176,7 +178,7 @@ echo " - Multi-backend: examples/08-encryption/multi-backend-sops.toml" echo " - Nickel schema: examples/08-encryption/sops-example.ncl" echo "" echo " 3. Read full guide:" -echo " - examples/08-encryption/SOPS-DEMO.md" +echo " - examples/08-encryption/sops-demo.md" echo " - docs/ENCRYPTION-UNIFIED-ARCHITECTURE.md" echo -e "\n${YELLOW}Cleanup:${NC}" diff --git a/examples/08-encryption/sops-integration-test.sh b/examples/08-encryption/sops-integration-test.sh index 4a88f28..976640e 100755 --- a/examples/08-encryption/sops-integration-test.sh +++ b/examples/08-encryption/sops-integration-test.sh @@ -286,9 +286,8 @@ EOF sops -e -i "$TEST_FILE" print_success "Encrypted with SOPS" - # Read encrypted content - ENCRYPTED_CONTENT=$(cat "$TEST_FILE") - print_info "Encrypted (hex representation would be): sops:v1:$(cat "$TEST_FILE" | xxd -p | head -c 50)..." + # Display encrypted content preview + print_info "Encrypted (hex representation would be): sops:v1:$(xxd -p < "$TEST_FILE" | head -c 50)..." # Decrypt with SOPS (ensure Age key is available) AGE_KEY_FILE="$TEST_DIR/.age/key.txt" @@ -403,7 +402,7 @@ print_summary() { echo " - Age key: $TEST_DIR/.age/key.txt" echo "" echo "Files created:" - ls -lh "$TEST_DIR"/ 2>/dev/null | tail -5 + find "$TEST_DIR" -maxdepth 1 -type f -printf '%TY-%Tm-%Td %TH:%TM %10s %p\n' 2>/dev/null | sort -r | head -5 echo "" echo "Next steps:" echo " 1. Try manual encryption:" diff --git a/examples/08-nickel-roundtrip/README.md b/examples/08-nickel-roundtrip/README.md index fb82dbb..77c6804 100644 --- a/examples/08-nickel-roundtrip/README.md +++ b/examples/08-nickel-roundtrip/README.md @@ -22,7 +22,7 @@ CI configuration management - edit GitHub Actions settings through a form interf # 1. Generate initial configuration ./01-generate-initial-config.sh -# 2. Edit with your preferred backend: +# 2. Edit with your preferred backend # CLI (command-line prompts) ./02-roundtrip-cli.sh @@ -32,7 +32,7 @@ CI configuration management - edit GitHub Actions settings through a form interf # Web (browser-based form) ./04-roundtrip-web.sh -``` +```text ## Key Features @@ -47,7 +47,7 @@ type = "text" prompt = "Parallel Jobs" default = "4" nickel_path = ["ci", "github_actions", "parallel_jobs"] -``` +```text Maps to: @@ -59,7 +59,7 @@ Maps to: } } } -``` +```text ### Template Rendering @@ -80,7 +80,7 @@ The `config.ncl.j2` template uses form values to generate valid Nickel: } } } -``` +```text ### Summary with Diff @@ -104,7 +104,7 @@ After editing, see what changed: ║ • Apply CI tools: ./setup-ci.sh ║ ║ • Re-configure: ./ci-configure.sh ║ ╚════════════════════════════════════════════════════════════╝ -``` +```text ## Workflow Details @@ -116,7 +116,7 @@ Roundtrip reads `config.ncl` and extracts values using `nickel_path`: // Internally: nickel export config.ncl // → JSON extract_value_by_path(json, ["ci", "github_actions", "parallel_jobs"]) // → 4 -``` +```text ### 2. Populate Form @@ -137,7 +137,7 @@ Template renders with new values: ```jinja2 parallel_jobs = {{ parallel_jobs }}, // User changed 4 → 8 -``` +```text ### 5. Validate @@ -145,7 +145,7 @@ Automatic validation: ```bash nickel typecheck config.ncl -``` +```text ### 6. Show Summary @@ -213,7 +213,7 @@ cache = { paths = {{ cache_paths | json }}, }, {% endif %} -``` +```text ### Disable Validation @@ -224,7 +224,7 @@ typedialog nickel-roundtrip \ --output config.ncl \ --ncl-template config.ncl.j2 \ --no-validate # ← Skip nickel typecheck -``` +```text ## Troubleshooting @@ -236,7 +236,7 @@ nickel export config.ncl # Verify all fields have nickel_path grep "nickel_path" ci-form.toml | wc -l -``` +```text **Template errors:** @@ -244,14 +244,14 @@ grep "nickel_path" ci-form.toml | wc -l # Test template separately echo '{"project_name": "test"}' | \ tera --template config.ncl.j2 -``` +```text **Validation fails:** ```bash # Check manually nickel typecheck config.ncl -``` +```text ## Learn More diff --git a/examples/09-templates/README.md b/examples/09-templates/README.md index 0dd4bbb..11c273c 100644 --- a/examples/09-templates/README.md +++ b/examples/09-templates/README.md @@ -47,7 +47,7 @@ cargo run -p typedialog-web -- --config examples/09-templates/employee_onboardin # Run user registration cargo run -p typedialog-web -- --config examples/09-templates/user_registration/form.toml -``` +```text ### As Starting Points diff --git a/examples/09-templates/employee_onboarding/README.md b/examples/09-templates/employee_onboarding/README.md index e6cffd1..9c049f4 100644 --- a/examples/09-templates/employee_onboarding/README.md +++ b/examples/09-templates/employee_onboarding/README.md @@ -47,19 +47,19 @@ Complete employee onboarding form workflow. ### CLI ```bash cargo run --example employee_onboarding_form -``` +```text ### TUI ```bash cargo run -p typedialog-tui -- \ --config examples/09-templates/employee_onboarding/employee_onboarding_form.toml -``` +```text ### Web ```bash cargo run -p typedialog-web -- \ --config examples/09-templates/employee_onboarding/employee_onboarding_form.toml -``` +```text ## Expected Output @@ -76,7 +76,7 @@ The form produces JSON: "handbook_agreed": true, "benefits_tier": "Gold" } -``` +```text ## Customization @@ -93,14 +93,14 @@ Edit the TOML to add: type = "email" label = "Work Email" pattern = "@company\\.com$" # Must be company email -``` +```text ### Conditional Sections Show benefits section only if: ```toml [sections.benefits] visible_when = { employment_type = "Full-Time" } -``` +```text ## Integration diff --git a/examples/09-templates/library_catalog/README.md b/examples/09-templates/library_catalog/README.md index 1130330..1c76298 100644 --- a/examples/09-templates/library_catalog/README.md +++ b/examples/09-templates/library_catalog/README.md @@ -54,7 +54,7 @@ Library management and book catalog system. ### CLI Interactive ```bash cargo run --example library_example -``` +```text ### Programmatic The Rust implementation provides: @@ -89,7 +89,7 @@ The Rust implementation provides: "renewable": true } } -``` +```text ## Use Cases @@ -124,7 +124,7 @@ pub struct Book { genre: String, // Add this categories: Vec, // Add this } -``` +```text ### Implement Reservations ```rust @@ -134,7 +134,7 @@ pub struct Reservation { queue_position: u32, created_date: DateTime, } -``` +```text ### Add Rating/Reviews ```rust @@ -144,7 +144,7 @@ pub struct Review { rating: u8, // 1-5 comment: String, } -``` +```text ## Database Integration @@ -174,7 +174,7 @@ CREATE TABLE checkouts ( due_date DATE, return_date DATE ); -``` +```text ## Features Demonstrated diff --git a/examples/09-templates/user_registration/README.md b/examples/09-templates/user_registration/README.md index bda4aac..329a36b 100644 --- a/examples/09-templates/user_registration/README.md +++ b/examples/09-templates/user_registration/README.md @@ -35,19 +35,19 @@ User sign-up and registration form. ### CLI ```bash cargo run --example user_registration_form -``` +```text ### TUI ```bash cargo run -p typedialog-tui -- \ --config examples/09-templates/user_registration/user_registration_form.toml -``` +```text ### Web (Recommended) ```bash cargo run -p typedialog-web -- \ --config examples/09-templates/user_registration/user_registration_form.toml -``` +```text Open browser to `http://localhost:3000` @@ -64,7 +64,7 @@ Open browser to `http://localhost:3000` "terms_agreed": true, "privacy_agreed": true } -``` +```text ## Validation Rules @@ -83,7 +83,7 @@ type = "text" label = "Referral Code (Optional)" required = false validation = { pattern = "^[A-Z0-9]{6,}$" } -``` +```text ### Add Email Verification ```toml @@ -91,7 +91,7 @@ validation = { pattern = "^[A-Z0-9]{6,}$" } type = "email" label = "Confirm Email" validation = { must_match = "email" } -``` +```text ### Password Strength Indicator ```toml @@ -105,7 +105,7 @@ validation = { require_number = true, require_special = true } -``` +```text ## Integration diff --git a/examples/10-ai-backend/README.md b/examples/10-ai-backend/README.md index 327a2e9..d993fde 100644 --- a/examples/10-ai-backend/README.md +++ b/examples/10-ai-backend/README.md @@ -2,7 +2,7 @@ Demonstrates the TypeDialog AI backend with RAG (Retrieval-Augmented Generation) system. -⚠️ **Important**: The AI backend cannot remain a library. See **[INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md)** for how to integrate into real services. +⚠️ **Important**: The AI backend cannot remain a library. See **[integration-guide.md](integration-guide.md)** for how to integrate into real services. ## Features Shown @@ -12,7 +12,7 @@ Demonstrates the TypeDialog AI backend with RAG (Retrieval-Augmented Generation) - **Batch Document Removal**: Efficient bulk document deletion - **Performance Comparison**: Shows speedup of batch vs sequential operations -## What is the AI Backend? +## What is the AI Backend The AI backend is **not a rendering backend** (like CLI, TUI, Web). It's a **library of AI/ML capabilities**: @@ -34,7 +34,7 @@ cargo run --example main --features ai_backend # Or directly cargo run --example main --features ai_backend --release -``` +```text ## Output Highlights @@ -70,7 +70,7 @@ let removed = rag.remove_documents_batch(&["id1", "id2"]); // Save/Load rag.save_to_file("rag.bin")?; let loaded = RagSystem::load_from_file("rag.bin")?; -``` +```text ## Configuration @@ -83,7 +83,7 @@ RagConfig { max_results: 5, // Maximum results to return min_score: 0.0, // Minimum combined score threshold } -``` +```text ## Integration Points diff --git a/examples/10-ai-backend/INTEGRATION_GUIDE.md b/examples/10-ai-backend/integration-guide.md similarity index 98% rename from examples/10-ai-backend/INTEGRATION_GUIDE.md rename to examples/10-ai-backend/integration-guide.md index 2e80cb3..f3ed413 100644 --- a/examples/10-ai-backend/INTEGRATION_GUIDE.md +++ b/examples/10-ai-backend/integration-guide.md @@ -6,7 +6,7 @@ The AI backend (RAG, Knowledge Graph, embeddings) must be **integrated into actu ## Architecture: AI Backend Integration Layers -``` +```text ┌─────────────────────────────────────────────────────────┐ │ USER INTERFACE │ │ (CLI / TUI / Web - Interactive Forms) │ @@ -27,7 +27,7 @@ The AI backend (RAG, Knowledge Graph, embeddings) must be **integrated into actu │ • Entity relationships (KG) │ │ • Persistent state │ └─────────────────────────────────────────────────────────┘ -``` +```text ## Integration Patterns @@ -65,7 +65,7 @@ impl SearchableForm { Ok(results) } } -``` +```text **Use Cases:** - Interactive CLI tools with search suggestions @@ -103,7 +103,7 @@ impl Widget for RagTuiPanel { // Render search UI with batched results } } -``` +```text **Use Cases:** - Dashboard with AI-powered search @@ -144,7 +144,7 @@ impl RagWebService { Json(ApiResponse { success: true }) } } -``` +```text **Use Cases:** - Web SaaS with knowledge base search @@ -156,9 +156,9 @@ impl RagWebService { ### Model 1: Embedded Service (Simple) -``` +```text Frontend Form → RAG Service (in-memory) → Results -``` +```text - **Pros:** Fast, no network latency, easy to prototype - **Cons:** Can't scale, state lost on restart @@ -167,9 +167,9 @@ Frontend Form → RAG Service (in-memory) → Results ### Model 2: Microservice (Production) -``` +```text Frontend Form → HTTP REST API → RAG Service → Vector DB / File Store -``` +```text - **Pros:** Scalable, persistent, can handle large datasets - **Cons:** Network latency, operational complexity @@ -178,9 +178,9 @@ Frontend Form → HTTP REST API → RAG Service → Vector DB / File Store ### Model 3: Hybrid (Best of Both) -``` +```text Frontend Form → Local Cache (RAG) → Sync ↔ Remote Service -``` +```text - **Pros:** Fast local access, keeps in sync, fallback support - **Cons:** Complexity, consistency challenges @@ -196,7 +196,7 @@ Frontend Form → Local Cache (RAG) → Sync ↔ Remote Service let mut rag = RagSystem::new(config)?; rag.add_documents_batch(docs)?; let results = rag.retrieve(query)?; -``` +```text **Status:** Ready - batch operations optimized, persistence working @@ -209,7 +209,7 @@ let results = rag.retrieve(query)?; // - Persistent storage (SQLite / file-based) // - Health checks, metrics // - Document management API -``` +```text **Scope:** - New binary crate: `crates/typedialog-ai-service/` @@ -261,7 +261,7 @@ form.on_field_change(&field_name, &user_input)?; // 5. User can explore suggested documents let selected_doc = form.get_suggestion_selection()?; form.populate_field_from_doc(&field_name, &selected_doc)?; -``` +```text ## Performance Considerations diff --git a/examples/11-prov-gen/README.md b/examples/11-prov-gen/README.md index 0b340b8..616c2c6 100644 --- a/examples/11-prov-gen/README.md +++ b/examples/11-prov-gen/README.md @@ -14,7 +14,7 @@ Demonstrates the `typedialog-provisioning-gen` tool that generates a complete 7- typedialog-provisioning-gen cargo \ --input mode-a-cargo/Cargo.toml \ --output /tmp/my-provisioning -``` +```text → See [`mode-a-cargo/README.md`](mode-a-cargo/) for details **Mode B: Config File** (Explicit Specification) @@ -23,7 +23,7 @@ typedialog-provisioning-gen cargo \ typedialog-provisioning-gen config \ --input mode-b-config/project-spec.toml \ --output /tmp/my-provisioning -``` +```text → See [`mode-b-config/README.md`](mode-b-config/) for details **Mode C: Interactive Wizard** (Conversational) @@ -32,7 +32,7 @@ typedialog-provisioning-gen config \ typedialog-provisioning-gen wizard \ --project my-service \ --output /tmp/my-provisioning -``` +```text → See [`mode-c-wizard/README.md`](mode-c-wizard/) for details **Mode D: Nickel Schema** (Migration) @@ -41,14 +41,14 @@ typedialog-provisioning-gen wizard \ typedialog-provisioning-gen nickel \ --input mode-d-nickel/existing-config.ncl \ --output /tmp/my-provisioning -``` +```text → See [`mode-d-nickel/README.md`](mode-d-nickel/) for details ## What Gets Generated All modes produce the same 7-layer structure: -``` +```text provisioning/ ├── constraints.toml # Layer 1: Validation bounds (single source of truth) ├── schemas/ # Layer 2: Type contracts (Nickel) @@ -57,7 +57,7 @@ provisioning/ ├── fragments/ # Layer 5: TypeDialog forms ├── scripts/ # Layer 6: Orchestration scripts └── config.ncl # Layer 7: Master configuration -``` +```text → See [`output-example/README.md`](output-example/) for detailed structure explanation @@ -115,22 +115,22 @@ Single source of truth - define constraints once, use everywhere: ```bash cd my-rust-service typedialog-provisioning-gen cargo --output ./provisioning -``` +```text ### 2. Test Form Interactively ```bash typedialog provisioning/fragments/http_server-section.toml --backend cli -``` +```text ### 3. Validate Configuration ```bash ./provisioning/scripts/validate-nickel.sh < config.ncl -``` +```text ### 4. Use in Application ```rust let config = nickel::eval_file("provisioning/config.ncl")?; -``` +```text ## Directory Guide @@ -149,12 +149,12 @@ let config = nickel::eval_file("provisioning/config.ncl")?; # You have a Cargo.toml with dependencies typedialog-provisioning-gen cargo --output ./infra -# Auto-detects: +# Auto-detects # - axum → HTTP server config # - sqlx → database config # - redis → caching config # - prometheus → monitoring -``` +```text Best for: Rust projects, quick setup @@ -163,12 +163,12 @@ Best for: Rust projects, quick setup # You have a detailed specification typedialog-provisioning-gen config --input architecture.toml --output ./platform -# Supports: +# Supports # - Multiple database types # - Event streaming setup # - Monitoring configuration # - Cloud provider selection -``` +```text Best for: Complex systems, cross-team coordination @@ -177,13 +177,13 @@ Best for: Complex systems, cross-team coordination # You want guidance through the process typedialog-provisioning-gen wizard --project my-service -# Walks through: +# Walks through # - Project type selection # - Infrastructure requirements # - Feature selection # - Field configuration # - AI-powered suggestions -``` +```text Best for: First-time users, exploring options @@ -192,11 +192,11 @@ Best for: First-time users, exploring options # You have existing Nickel schemas typedialog-provisioning-gen nickel --input config.ncl --output ./new-provisioning -# Converts: +# Converts # - Type definitions → schemas # - Records → domain features # - Fields → form fragments -``` +```text Best for: System modernization, adding forms to existing configs @@ -209,7 +209,7 @@ typedialog provisioning/fragments/database-section.toml --backend cli # Web interface typedialog-web provisioning/fragments/*.toml --port 3000 -``` +```text ### Nickel Validation ```bash @@ -218,7 +218,7 @@ typedialog-web provisioning/fragments/*.toml --port 3000 # Use in config nickel eval provisioning/config.ncl -``` +```text ### Scripts ```bash @@ -228,13 +228,13 @@ nickel eval provisioning/config.ncl # Format conversion ./provisioning/scripts/json-to-nickel.sh < input.json ./provisioning/scripts/nickel-to-json.sh < config.ncl -``` +```text ### Application Integration ```rust // Load provisioning config let config = provisioning::load("provisioning/config.ncl")?; -``` +```text ## What This Demonstrates @@ -309,7 +309,7 @@ cargo run -p typedialog-provisioning-gen -- nickel \ cargo run -p typedialog-provisioning-gen -- wizard \ --project test-service \ --output /tmp/mode-c-output -``` +```text ## Key Files diff --git a/examples/11-prov-gen/mode-a-cargo/README.md b/examples/11-prov-gen/mode-a-cargo/README.md index 54ad1ad..a56588b 100644 --- a/examples/11-prov-gen/mode-a-cargo/README.md +++ b/examples/11-prov-gen/mode-a-cargo/README.md @@ -31,15 +31,15 @@ From the included `Cargo.toml`, the generator detects: typedialog-provisioning-gen cargo \ --input examples/11-provisioning-generation/mode-a-cargo/Cargo.toml \ --output /tmp/my-provisioning -``` +```text ### Step 2: Inspect Generated Structure ```bash tree /tmp/my-provisioning -``` +```text Expected output: -``` +```text /tmp/my-provisioning/ ├── config.ncl # Master configuration ├── constraints.toml # Validation bounds @@ -74,13 +74,13 @@ Expected output: ├── json-to-nickel.sh ├── validate-nickel.sh └── ... -``` +```text ### Step 3: Validate Generated Configuration ```bash cd /tmp/my-provisioning ./scripts/validate-nickel.sh -``` +```text ### Step 4: Use in TypeDialog Forms ```bash @@ -89,7 +89,7 @@ typedialog fragments/http_server-section.toml --backend cli # Display database configuration form typedialog fragments/database-mysql-section.toml --backend cli -``` +```text ## Dependency → Feature Mapping diff --git a/examples/11-prov-gen/mode-b-config/README.md b/examples/11-prov-gen/mode-b-config/README.md index 62508f6..ea45ad6 100644 --- a/examples/11-prov-gen/mode-b-config/README.md +++ b/examples/11-prov-gen/mode-b-config/README.md @@ -21,7 +21,7 @@ The `project-spec.toml` file has three main sections: name = "service-name" description = "What this service does" type = "Microservice" # WebService, CliTool, Microservice, Library -``` +```text ### 2. Infrastructure Requirements ```toml @@ -33,7 +33,7 @@ cloud_providers = ["aws", "gcp"] [[infrastructure.databases]] type = "postgres" required = true -``` +```text ### 3. Domain Features Each feature represents a functional capability: @@ -55,7 +55,7 @@ encryption_backend = "age" # For sensitive fields min = 1 # For numbers/arrays max = 100 options = ["a", "b"] # For Select/MultiSelect -``` +```text ### 4. Constraints (Single Source of Truth) ```toml @@ -64,7 +64,7 @@ min = 1 max = 100 min_length = 5 max_length = 255 -``` +```text ## Running the Example @@ -73,7 +73,7 @@ max_length = 255 typedialog-provisioning-gen config \ --input examples/11-provisioning-generation/mode-b-config/project-spec.toml \ --output /tmp/microservice-platform -``` +```text ### Inspect Generated Files ```bash @@ -88,7 +88,7 @@ cat /tmp/microservice-platform/fragments/authentication-section.toml # Validate constraints cat /tmp/microservice-platform/constraints.toml -``` +```text ### Test Forms Interactively ```bash @@ -97,7 +97,7 @@ typedialog /tmp/microservice-platform/fragments/api_gateway-section.toml --backe # Test authentication configuration form typedialog /tmp/microservice-platform/fragments/authentication-section.toml --backend cli -``` +```text ### Use Generated Scripts ```bash @@ -112,7 +112,7 @@ echo '{"api_gateway": {"bind_address": "0.0.0.0:8080"}}' | \ # Convert back to JSON ./scripts/nickel-to-json.sh < config.ncl -``` +```text ## Features Defined in This Example @@ -180,7 +180,7 @@ name = "jwt_secret" type = "Password" sensitive = true encryption_backend = "age" # Default: age -``` +```text **Supported backends**: - `age` - Modern encryption (recommended) @@ -202,7 +202,7 @@ max_length = 50 [constraints.api_gateway.rate_limit] min = 1 max = 10000 -``` +```text These constraints are: - Used in TypeDialog forms (enforced client-side) @@ -278,7 +278,7 @@ let auth = import "schemas/authentication.ncl" authentication = auth.Authentication, } -``` +```text Or deserialize from JSON: @@ -291,4 +291,4 @@ nickel eval config.ncl # Export to application ./scripts/nickel-to-json.sh < config.ncl > config.json -``` +```text diff --git a/examples/11-prov-gen/mode-c-wizard/README.md b/examples/11-prov-gen/mode-c-wizard/README.md index c5b08f1..0165aba 100644 --- a/examples/11-prov-gen/mode-c-wizard/README.md +++ b/examples/11-prov-gen/mode-c-wizard/README.md @@ -20,12 +20,12 @@ typedialog-provisioning-gen wizard --project my-service # Or use default name typedialog-provisioning-gen wizard -``` +```text ## Interactive Flow ### Step 1: Project Type Selection -``` +```text What type of project are you building? 1) WebService - REST APIs, web servers @@ -35,10 +35,10 @@ What type of project are you building? 5) Other Select (1-5): -``` +```text ### Step 2: Infrastructure Requirements -``` +```text Infrastructure Configuration Enable SSH access? (y/n): y @@ -72,10 +72,10 @@ Cloud deployment target? Select (1-4): 2 → AWS selected -``` +```text ### Step 3: Domain Features -``` +```text Domain Features The wizard suggests features based on your project type. @@ -95,10 +95,10 @@ Select features to include: [ ] file_upload Confirm? (y/n): y -``` +```text ### Step 4: Feature Configuration -``` +```text Configure http_server 1) Bind Address (default: 0.0.0.0:8080) @@ -107,7 +107,7 @@ Configure http_server 4) Done Select field to configure (1-4): -``` +```text The wizard guides you through each feature's fields with: - Helpful descriptions @@ -116,7 +116,7 @@ The wizard guides you through each feature's fields with: - Examples ### Step 5: Review and Generate -``` +```text Summary Project: my-service @@ -138,7 +138,7 @@ Generating... ✓ Scripts Done! Generated to ./provisioning -``` +```text ## AI-Powered Suggestions @@ -147,7 +147,7 @@ When Mode C integrates with typedialog-ai, it provides: ### 1. RAG-Based Feature Suggestions The wizard retrieves similar project examples: -``` +```text Projects similar to "WebService" in your domain: 1. E-commerce platform @@ -161,12 +161,12 @@ Projects similar to "WebService" in your domain: - Caching: Redis Suggest these features? (y/n): -``` +```text ### 2. Field Generation Assistance LLM analyzes domain features and suggests fields: -``` +```text Configure http_server feature Based on similar services, recommended fields: @@ -176,12 +176,12 @@ Based on similar services, recommended fields: - compression_enabled (Type: Confirm) Add recommended fields? (y/n): -``` +```text ### 3. Constraint Learning LLM suggests validation bounds from patterns: -``` +```text For max_connections field: Learned constraints from similar services: @@ -190,7 +190,7 @@ Learned constraints from similar services: - Typical: 1000 Apply? (y/n): -``` +```text ## Typical Workflow Examples @@ -198,12 +198,12 @@ Apply? (y/n): ```bash typedialog-provisioning-gen wizard --project api-service -# Selections: +# Selections # - WebService # - PostgreSQL # - Prometheus monitoring # - Features: http_server, authentication -``` +```text Generated structure optimized for REST APIs with user management. @@ -211,12 +211,12 @@ Generated structure optimized for REST APIs with user management. ```bash typedialog-provisioning-gen wizard --project order-service -# Selections: +# Selections # - Microservice # - PostgreSQL + Redis # - Multiple cloud providers (AWS + GCP) # - Features: http_server, authentication, event_streaming, caching -``` +```text Generated for distributed event-driven architecture. @@ -224,12 +224,12 @@ Generated for distributed event-driven architecture. ```bash typedialog-provisioning-gen wizard --project deployment-tool -# Selections: +# Selections # - CliTool # - No database # - SSH enabled # - Features: configuration_management, deployment -``` +```text Generated for infrastructure automation. @@ -269,7 +269,7 @@ fn simple_wizard() { }; Ok(spec) } -``` +```text This ensures the wizard works standalone without dependencies. diff --git a/examples/11-prov-gen/mode-d-nickel/README.md b/examples/11-prov-gen/mode-d-nickel/README.md index 70e556d..81f1903 100644 --- a/examples/11-prov-gen/mode-d-nickel/README.md +++ b/examples/11-prov-gen/mode-d-nickel/README.md @@ -22,7 +22,7 @@ The `existing-config.ncl` file defines types for a service: Monitoring = { enabled, prometheus_url, ... }, Application = { name, version, log_level, ... }, } -``` +```text Mode D analyzes this schema and: @@ -38,7 +38,7 @@ Mode D analyzes this schema and: typedialog-provisioning-gen nickel \ --input examples/11-provisioning-generation/mode-d-nickel/existing-config.ncl \ --output /tmp/service-provisioning -``` +```text ### Inspect Conversion ```bash @@ -53,7 +53,7 @@ cat /tmp/service-provisioning/fragments/server-section.toml # View extracted validators cat /tmp/service-provisioning/validators/server.ncl -``` +```text ### Test Generated Forms ```bash @@ -62,7 +62,7 @@ typedialog /tmp/service-provisioning/fragments/server-section.toml --backend cli # Test database configuration form typedialog /tmp/service-provisioning/fragments/database-section.toml --backend cli -``` +```text ## Schema Extraction Details @@ -96,7 +96,7 @@ Server = { port | Number, tls_enabled | Bool | optional, } -``` +```text **Generated Schema** (`schemas/server.ncl`): ```nickel @@ -107,7 +107,7 @@ Server = { tls_enabled | Bool | optional, }, } -``` +```text **Generated Fragment** (`fragments/server-section.toml`): ```toml @@ -133,7 +133,7 @@ name = "tls_enabled" prompt = "Enable TLS?" type = "confirm" required = false -``` +```text **Generated Validator** (`validators/server.ncl`): ```nickel @@ -147,7 +147,7 @@ required = false validate_tls_enabled = fun value => (std.is_bool value), } -``` +```text ## Handling Complex Types @@ -159,7 +159,7 @@ ServiceConfig = { server | Server, # References Server record database | Database, # References Database record } -``` +```text Generated as separate features with relationships documented. @@ -168,7 +168,7 @@ Nickel `optional` modifier: ```nickel certificate_path | String | optional, -``` +```text Generated as optional form field (not required in TypeDialog form). @@ -177,7 +177,7 @@ Repeating items: ```nickel tags | [String], -``` +```text Generated as `RepeatingGroup` field with array validation. @@ -222,20 +222,20 @@ The converted provisioning can integrate with existing services: // Load configuration from generated schema let config = nickel_eval("provisioning/config.ncl")?; let parsed: ServiceConfig = serde_json::from_value(config)?; -``` +```text ### 2. Provide Configuration UI ```bash # Use generated TypeDialog forms for configuration typedialog provisioning/fragments/database-section.toml \ --backend web --port 3000 -``` +```text ### 3. Add Validation Layer ```bash # Validate user input against Nickel schema ./provisioning/scripts/validate-nickel.sh < user-config.ncl -``` +```text ## Migration Path diff --git a/examples/11-prov-gen/output-example/README.md b/examples/11-prov-gen/output-example/README.md index 3dc700c..802702e 100644 --- a/examples/11-prov-gen/output-example/README.md +++ b/examples/11-prov-gen/output-example/README.md @@ -4,7 +4,7 @@ This directory demonstrates the complete output structure generated by the provi ## Directory Structure -``` +```text output-example/ ├── config.ncl # Master configuration file ├── constraints.toml # Layer 1: Validation bounds (single source of truth) @@ -35,7 +35,7 @@ output-example/ │ ├── validate-nickel.sh │ └── README.md (orchestration guide) └── README.md # This file -``` +```text ## 7-Layer Validation Architecture @@ -63,7 +63,7 @@ unique = false [authentication.jwt_secret] min_length = 32 max_length = 256 -``` +```text **Purpose**: - Single source of truth for validation rules @@ -85,7 +85,7 @@ Nickel type definitions for each domain feature: max_connections | Number | optional, }, } -``` +```text **Purpose**: - Type-safe configuration definitions @@ -114,7 +114,7 @@ let validate_timeout_seconds = fun value => validate_bind_address, validate_timeout_seconds, } -``` +```text **Purpose**: - Enforce constraints defined in Layer 1 @@ -136,7 +136,7 @@ Sensible defaults for each feature: max_connections = 1000, }, } -``` +```text **Purpose**: - Provide reasonable configuration starting points @@ -171,7 +171,7 @@ default = 30 min = 1 max = 600 help = "Maximum seconds to wait for request completion" -``` +```text **Purpose**: - Provide user-friendly configuration UI @@ -211,7 +211,7 @@ let http_server_defaults = import "defaults/http_server.ncl" | http_server_schema.HttpServer | http_server_validator, } -``` +```text ## Using the Generated Structure @@ -222,7 +222,7 @@ typedialog fragments/http_server-section.toml --backend cli # Web-based form typedialog-web fragments/http_server-section.toml --port 3000 -``` +```text ### 2. Validate Existing Config ```bash @@ -231,7 +231,7 @@ typedialog-web fragments/http_server-section.toml --port 3000 # Convert and validate JSON ./scripts/json-to-nickel.sh < input.json | ./scripts/validate-nickel.sh -``` +```text ### 3. Generate Config from User Input ```bash @@ -243,7 +243,7 @@ typedialog fragments/*.toml --backend cli --output config.json # Validate ./scripts/validate-nickel.sh < config.ncl -``` +```text ### 4. Use in Application ```rust @@ -253,7 +253,7 @@ let config: ServiceConfig = nickel::evaluate(&config_str)?; // Use typed configuration println!("Server: {}:{}", config.http_server.bind_address); -``` +```text ### 5. Export to Other Formats ```bash @@ -262,7 +262,7 @@ println!("Server: {}:{}", config.http_server.bind_address); # Export to YAML ./scripts/nickel-to-json.sh < config.ncl | jq -r 'to_entries | map("\(.key): \(.value)") | .[]' -``` +```text ## Constraint Interpolation @@ -273,18 +273,18 @@ Constraints can be referenced in validators and forms: [http_server.timeout_seconds] min = 1 max = 600 -``` +```text **In validators**: ```nickel let max_timeout = {{ constraints.http_server.timeout_seconds.max }}; validate_timeout = fun value => value <= max_timeout -``` +```text **In fragments**: ```toml max = {{ constraints.http_server.timeout_seconds.max }} -``` +```text This ensures single source of truth for validation bounds. @@ -315,7 +315,7 @@ name = "jwt_secret" type = "password" sensitive = true encryption_backend = "age" # or: sops, secretumvault, aws-kms, gcp-kms -``` +```text **Supported Encryption Backends**: - `age` - Modern encryption (recommended) @@ -334,7 +334,7 @@ Encrypted fields are: Typical workflow with generated structure: -``` +```text 1. User runs interactive form ↓ typedialog fragments/*.toml @@ -355,7 +355,7 @@ Typical workflow with generated structure: app.load_config("config.ncl") ↓ Server starts on 0.0.0.0:3000 -``` +```text ## Extending Generated Structure @@ -423,7 +423,7 @@ typedialog fragments/http_server-section.toml --backend cli --test echo '{"http_server":{"bind_address":"127.0.0.1:8080"}}' | \ ./scripts/json-to-nickel.sh | \ ./scripts/validate-nickel.sh -``` +```text ## Documentation and References diff --git a/examples/12-agent-execution/README-demos.md b/examples/12-agent-execution/README-demos.md index 5f0bdad..2431f15 100644 --- a/examples/12-agent-execution/README-demos.md +++ b/examples/12-agent-execution/README-demos.md @@ -21,7 +21,7 @@ From the project root directory: ```bash ./demos/agent/run_demo.sh -``` +```text This will: 1. Check for available API keys and Ollama server @@ -46,7 +46,7 @@ cargo run --package typedialog-ag -- demos/agent/demo-gemini.agent.mdx # Ollama (local) cargo run --package typedialog-ag -- demos/agent/demo-ollama.agent.mdx -``` +```text ## Requirements @@ -65,7 +65,7 @@ export OPENAI_API_KEY=sk-... export GEMINI_API_KEY=... # OR export GOOGLE_API_KEY=... -``` +```text ### Local Models (Ollama) @@ -82,7 +82,7 @@ export GOOGLE_API_KEY=... Optional: Override default Ollama URL: ```bash export OLLAMA_BASE_URL=http://localhost:11434 -``` +```text ## Provider Comparison @@ -109,6 +109,6 @@ For a programmatic comparison of all providers, see: ```bash cargo run --example provider_comparison -``` +```text This example demonstrates both blocking and streaming modes for all four providers. diff --git a/examples/12-agent-execution/README.md b/examples/12-agent-execution/README.md index 9239cb9..dec5be2 100644 --- a/examples/12-agent-execution/README.md +++ b/examples/12-agent-execution/README.md @@ -21,7 +21,7 @@ TypeDialog Agent allows you to execute AI agents defined as markdown files (`.ag ```bash cargo run --package typedialog-ag -- examples/12-agent-execution/basic-greeting.agent.mdx -``` +```text **What it demonstrates:** - Simple agent configuration @@ -39,7 +39,7 @@ cargo run --package typedialog-ag -- examples/12-agent-execution/basic-greeting. ```bash cargo run --package typedialog-ag -- examples/12-agent-execution/code-review.agent.mdx -``` +```text **What it demonstrates:** - File pattern imports (`@import`) @@ -58,7 +58,7 @@ cargo run --package typedialog-ag -- examples/12-agent-execution/code-review.age ```bash cargo run --package typedialog-ag -- examples/12-agent-execution/documentation.agent.mdx -``` +```text **What it demonstrates:** - Complex file glob patterns @@ -76,7 +76,7 @@ cargo run --package typedialog-ag -- examples/12-agent-execution/documentation.a ```bash cargo run --package typedialog-ag -- examples/12-agent-execution/task-planner.agent.mdx -``` +```text **What it demonstrates:** - Project planning without time estimates @@ -99,7 +99,7 @@ ollama serve # Then run the agent cargo run --package typedialog-ag -- examples/12-agent-execution/local-privacy.agent.mdx -``` +```text **What it demonstrates:** - Local LLM execution with Ollama @@ -118,7 +118,7 @@ cargo run --package typedialog-ag -- examples/12-agent-execution/local-privacy.a ```bash cargo run --package typedialog-ag -- examples/12-agent-execution/creative-writer.agent.mdx -``` +```text **What it demonstrates:** - High temperature for creativity (0.9) @@ -136,7 +136,7 @@ cargo run --package typedialog-ag -- examples/12-agent-execution/creative-writer ```bash cargo run --package typedialog-ag -- examples/12-agent-execution/refactoring-assistant.agent.mdx -``` +```text **What it demonstrates:** - Low temperature for consistent code (0.2) @@ -155,7 +155,7 @@ cargo run --package typedialog-ag -- examples/12-agent-execution/refactoring-ass ```bash cargo run --package typedialog-ag -- examples/12-agent-execution/architect.agent.mdx -``` +```text **What it demonstrates:** - Most capable model for complex design @@ -184,7 +184,7 @@ cargo run --package typedialog-ag -- examples/12-agent-execution/architect.agent ```bash # From project root cargo run --package typedialog-ag -- examples/12-agent-execution/.agent.mdx -``` +```text ### With Input Variables @@ -192,16 +192,16 @@ cargo run --package typedialog-ag -- examples/12-agent-execution/.agent # Interactive prompts cargo run --package typedialog-ag -- examples/12-agent-execution/basic-greeting.agent.mdx -# You'll be prompted: +# You'll be prompted # name (String): Alice # language (optional, String): Spanish -``` +```text ### Skip Prompts (Use Defaults) ```bash cargo run --package typedialog-ag -- examples/12-agent-execution/basic-greeting.agent.mdx --yes -``` +```text ## Requirements @@ -218,7 +218,7 @@ export OPENAI_API_KEY=sk-... # Gemini export GEMINI_API_KEY=... -``` +```text ### Local Models (Ollama) @@ -231,7 +231,7 @@ ollama serve # Pull model ollama pull llama2 -``` +```text ## Related Resources @@ -279,7 +279,7 @@ All examples follow this structure: --- Template content with {{variables}} -``` +```text ## Features Showcased @@ -315,7 +315,7 @@ Template content with {{variables}} @agent { max_tokens: 500 # Limit response length for simple tasks } -``` +```text ### Temperature Control ```yaml @@ -324,32 +324,32 @@ Template content with {{variables}} temperature: 0.7 # Moderate for balanced creativity temperature: 0.9 # High for creative content } -``` +```text ## Troubleshooting ### API Key Not Set -``` +```text Error: ANTHROPIC_API_KEY environment variable not set -``` +```text **Solution**: Set the required API key for your chosen model ### File Not Found -``` +```text Error: Failed to import "./path/to/file.md" -``` +```text **Solution**: Check file paths are relative to project root or use absolute paths ### Validation Failed -``` +```text Error: Validation failed: missing required content -``` +```text **Solution**: Adjust validation rules or improve agent prompt ### Ollama Connection Failed -``` +```text Error: Failed to call Ollama API - is Ollama running? -``` +```text **Solution**: Start Ollama server with `ollama serve` ## Next Steps diff --git a/examples/13-conditional-logic/README.md b/examples/13-conditional-logic/README.md index 148b7b8..a921ee8 100644 --- a/examples/13-conditional-logic/README.md +++ b/examples/13-conditional-logic/README.md @@ -12,19 +12,19 @@ TypeDialog supports rich conditional logic for dynamic form behavior. Fields can ```bash cargo run --bin typedialog -- examples/13-conditional-logic/conditional-demo.toml -``` +```text ### TUI Backend ```bash cargo run --bin typedialog-tui -- examples/13-conditional-logic/conditional-demo.toml -``` +```text ### Web Backend ```bash cargo run --bin typedialog-web -- examples/13-conditional-logic/conditional-demo.toml -``` +```text ## Supported Operators @@ -43,7 +43,7 @@ when = "database_driver == mysql" [[elements]] name = "server_warning" when = "database_driver != sqlite" -``` +```text #### Numeric Comparisons @@ -60,7 +60,7 @@ when = "server_port < 1024" [[elements]] name = "high_port_warning" when = "server_port > 10000" -``` +```text ### String Operators @@ -80,7 +80,7 @@ when = "project_url endswith github.com" [[elements]] name = "gitlab_ci" when = "project_url contains gitlab" -``` +```text ### Array Membership @@ -94,7 +94,7 @@ when = "rust in detected_languages" [[elements]] name = "python_venv" when = "python in detected_languages" -``` +```text **Works with**: @@ -120,7 +120,7 @@ name = "env_setup" type = "group" includes = ["fragments/environment-setup.toml"] when = "!file_exists(.env)" -``` +```text **Path resolution**: @@ -148,7 +148,7 @@ Fields appear/disappear based on user input: name = "mysql_password" type = "password" when = "database_driver == mysql" -``` +```text ### Conditional Fragment Loading @@ -160,7 +160,7 @@ name = "docker_setup" type = "group" includes = ["fragments/docker-init.toml"] when = "!file_exists(Dockerfile)" -``` +```text ### Multi-Condition Fields @@ -172,7 +172,7 @@ when = "rust in detected_languages" # Future: Compound conditions when = "(rust in detected_languages) && (server_port >= 1024)" -``` +```text ## Testing Scenarios @@ -233,7 +233,7 @@ name = "advanced_config" type = "group" includes = ["fragments/advanced-settings.toml"] when = "enable_advanced == true" -``` +```text This prevents loading unnecessary form definitions until needed. diff --git a/examples/README.md b/examples/README.md index d6de58c..1cd8ff1 100644 --- a/examples/README.md +++ b/examples/README.md @@ -9,7 +9,7 @@ Complete example collection organized by feature category and backend implementa ## Quick Start -### First Time? +### First Time Start here: [`01-basic/`](01-basic/) ```bash @@ -18,7 +18,7 @@ cargo run --example form # Or with a specific backend cargo run -p typedialog-tui --example form_with_autocompletion -``` +```text ## Example Categories @@ -62,7 +62,7 @@ cargo run -p typedialog-tui --example form_with_autocompletion # Web cargo run -p typedialog-web -- --config form.toml -``` +```text ### 5. **Fragments & Composition** → [`05-fragments/`](05-fragments/) Reusable components and form composition. @@ -89,7 +89,7 @@ cargo run -p typedialog-tui --example array_trackers # Web - Inline expandable cards with live counter cargo run -p typedialog-web -- --config examples/05-fragments/array-trackers.toml -``` +```text ### 6. **Integrations** → [`06-integrations/`](06-integrations/) External tool integrations. @@ -136,7 +136,7 @@ cargo run --example main --features ai_backend # Or test AI module just test::ai -``` +```text ### 10. **Real-World Templates** → [`09-templates/`](09-templates/) Production-ready examples for common use cases. @@ -182,7 +182,7 @@ cargo run --package typedialog-ag -- examples/12-agent-execution/basic-greeting. # See all examples cat examples/12-agent-execution/README.md -``` +```text **Related:** - [Demos](../demos/agent/) - Multi-provider comparison demos @@ -220,13 +220,13 @@ cargo run --bin typedialog-tui -- examples/13-conditional-logic/conditional-demo # Web cargo run --bin typedialog-web -- examples/13-conditional-logic/conditional-demo.toml -``` +```text **Best for:** Dynamic forms, adaptive UX, configuration wizards ## Learning Path -``` +```text START HERE ↓ 01-basic/ ← Understand form structure @@ -259,14 +259,14 @@ START HERE └→ Knowledge graph integration ↓ 09-templates/ ← Deploy to production -``` +```text ## Common Tasks ### Run a Basic Example ```bash cargo run --example form -``` +```text ### Try Different Backends ```bash @@ -278,27 +278,27 @@ cargo run -p typedialog-tui --example tui_survey_form # Web cargo run -p typedialog-web -- --config examples/04-backends/web/web_registration_form.toml -``` +```text ### Use with TOML Configuration ```bash cargo run -p typedialog-web -- --config examples/01-basic/form_with_sections.toml -``` +```text ### Use with Rust Code ```bash cargo run --example form_with_autocompletion -``` +```text ### Test Conditional Logic ```bash cargo run --example conditional_required_demo -``` +```text ### Try Multi-Language Support ```bash LANG=es cargo run --example test_i18n_form -``` +```text ## File Types @@ -306,19 +306,19 @@ LANG=es cargo run --example test_i18n_form Configuration-driven forms - fastest iteration. ```bash cargo run -p typedialog-web -- --config form.toml -``` +```text ### Rust (`.rs`) Programmatic forms - maximum control. ```bash cargo run --example form_example -``` +```text ### Nickel (`.ncl`) Type-safe schema generation. ```bash nickel eval schema.ncl > form.toml -``` +```text ## Backend Compatibility diff --git a/install/install.sh b/install/install.sh index f34eb9a..59f8cdc 100755 --- a/install/install.sh +++ b/install/install.sh @@ -85,7 +85,7 @@ download_release() { local download_url="https://github.com/${GITHUB_REPO}/releases/download/${VERSION}/typedialog-${platform}.tar.gz" local temp_file temp_file=$(mktemp) || return 1 - trap "rm -f '$temp_file'" EXIT + trap 'rm -f '"$temp_file" EXIT log_info "Downloading: $download_url" @@ -206,7 +206,7 @@ main() { local extract_dir extract_dir=$(extract_archive "$archive") || return 1 - trap "rm -rf '$extract_dir'" EXIT + trap 'rm -rf '"$extract_dir" EXIT install_binaries "$extract_dir" || return 1 install_configs "$extract_dir" || return 1 diff --git a/scripts/build_all.sh b/scripts/build_all.sh index 4639bd7..e4a74dc 100755 --- a/scripts/build_all.sh +++ b/scripts/build_all.sh @@ -6,8 +6,10 @@ set -euo pipefail # Returns: 0 on success, 1 on failure # Output: Build progress and results -readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -readonly WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +readonly SCRIPT_DIR +WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" +readonly WORKSPACE_ROOT readonly PROFILE="${1:-debug}" # Function: Print info message diff --git a/scripts/build_cross.sh b/scripts/build_cross.sh index a37d645..7b335c0 100755 --- a/scripts/build_cross.sh +++ b/scripts/build_cross.sh @@ -6,8 +6,10 @@ set -euo pipefail # Returns: 0 on success, 1 on failure # Output: Cross-compilation progress -readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -readonly WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +readonly SCRIPT_DIR +WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" +readonly WORKSPACE_ROOT readonly TARGET="${1:-}" # Supported targets for cross-compilation diff --git a/scripts/create_distro.sh b/scripts/create_distro.sh index 0dc7f92..297ef9e 100755 --- a/scripts/create_distro.sh +++ b/scripts/create_distro.sh @@ -6,8 +6,10 @@ set -euo pipefail # Returns: 0 on success, 1 on failure # Output: Distribution package path -readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -readonly WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +readonly SCRIPT_DIR +WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" +readonly WORKSPACE_ROOT readonly DISTRO_DIR="${WORKSPACE_ROOT}/distribution" readonly BUILD_DIR="${WORKSPACE_ROOT}/target/release" @@ -171,7 +173,8 @@ EOF # Function: Create tarball create_tarball() { local distro_path="$1" - local distro_name=$(basename "$distro_path") + local distro_name + distro_name=$(basename "$distro_path") local tarball="${DISTRO_DIR}/${distro_name}.tar.gz" cd "$DISTRO_DIR" diff --git a/scripts/package_release.sh b/scripts/package_release.sh index 0625b46..378cb0a 100755 --- a/scripts/package_release.sh +++ b/scripts/package_release.sh @@ -6,8 +6,10 @@ set -euo pipefail # Returns: 0 on success, 1 on failure # Output: Final release package path -readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -readonly WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +readonly SCRIPT_DIR +WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" +readonly WORKSPACE_ROOT readonly DISTRO_DIR="${WORKSPACE_ROOT}/distribution" readonly RELEASE_DIR="${WORKSPACE_ROOT}/release" diff --git a/scripts/update-docs-refs.sh b/scripts/update-docs-refs.sh index bcf848c..f489d7d 100755 --- a/scripts/update-docs-refs.sh +++ b/scripts/update-docs-refs.sh @@ -39,7 +39,7 @@ echo "Step 1: Update root-level doc references" echo "-----------------------------------------" # Find all markdown files and update references -for file in $(find . -name "*.md" -type f -not -path "./target/*" -not -path "./.git/*" -not -path "./node_modules/*" -not -name "*.bak"); do +find . -name "*.md" -type f -not -path "./target/*" -not -path "./.git/*" -not -path "./node_modules/*" -not -name "*.bak" | while read -r file; do # Root level docs update_refs "$file" 'docs/BUILD\.md' 'docs/build.md' update_refs "$file" 'BUILD\.md' 'build.md' @@ -50,8 +50,10 @@ for file in $(find . -name "*.md" -type f -not -path "./target/*" -not -path "./ update_refs "$file" 'docs/DEVELOPMENT\.md' 'docs/development.md' update_refs "$file" 'DEVELOPMENT\.md' 'development.md' - update_refs "$file" 'docs/FIELD_TYPES\.md' 'docs/field_types.md' - update_refs "$file" 'FIELD_TYPES\.md' 'field_types.md' + update_refs "$file" 'docs/FIELD_TYPES\.md' 'docs/field-types.md' + update_refs "$file" 'docs/field_types\.md' 'docs/field-types.md' + update_refs "$file" 'FIELD_TYPES\.md' 'field-types.md' + update_refs "$file" 'field_types\.md' 'field-types.md' update_refs "$file" 'docs/INSTALLATION\.md' 'docs/installation.md' update_refs "$file" 'INSTALLATION\.md' 'installation.md' @@ -70,21 +72,31 @@ echo "" echo "Step 2: Update agent/ doc references" echo "-------------------------------------" -for file in $(find . -name "*.md" -type f -not -path "./target/*" -not -path "./.git/*" -not -path "./node_modules/*" -not -name "*.bak"); do - update_refs "$file" 'docs/agent/GETTING_STARTED\.md' 'docs/agent/getting_started.md' - update_refs "$file" 'agent/GETTING_STARTED\.md' 'agent/getting_started.md' - update_refs "$file" 'GETTING_STARTED\.md' 'getting_started.md' +find . -name "*.md" -type f -not -path "./target/*" -not -path "./.git/*" -not -path "./node_modules/*" -not -name "*.bak" | while read -r file; do + update_refs "$file" 'docs/agent/GETTING_STARTED\.md' 'docs/agent/getting-started.md' + update_refs "$file" 'docs/agent/getting_started\.md' 'docs/agent/getting-started.md' + update_refs "$file" 'agent/GETTING_STARTED\.md' 'agent/getting-started.md' + update_refs "$file" 'agent/getting_started\.md' 'agent/getting-started.md' + update_refs "$file" 'GETTING_STARTED\.md' 'getting-started.md' + update_refs "$file" 'getting_started\.md' 'getting-started.md' - update_refs "$file" 'docs/agent/LLM_PROVIDERS\.md' 'docs/agent/llm_providers.md' - update_refs "$file" 'agent/LLM_PROVIDERS\.md' 'agent/llm_providers.md' - update_refs "$file" 'LLM_PROVIDERS\.md' 'llm_providers.md' + update_refs "$file" 'docs/agent/LLM_PROVIDERS\.md' 'docs/agent/llm-providers.md' + update_refs "$file" 'docs/agent/llm_providers\.md' 'docs/agent/llm-providers.md' + update_refs "$file" 'agent/LLM_PROVIDERS\.md' 'agent/llm-providers.md' + update_refs "$file" 'agent/llm_providers\.md' 'agent/llm-providers.md' + update_refs "$file" 'LLM_PROVIDERS\.md' 'llm-providers.md' + update_refs "$file" 'llm_providers\.md' 'llm-providers.md' + + update_refs "$file" 'docs/agent/LLM_INTEGRATION\.md' 'docs/agent/llm-integration.md' + update_refs "$file" 'LLM_INTEGRATION\.md' 'llm-integration.md' + update_refs "$file" 'typedialog-ag-core/LLM_INTEGRATION\.md' 'agent/llm-integration.md' done echo "" echo "Step 3: Update encryption/ doc references" echo "------------------------------------------" -for file in $(find . -name "*.md" -type f -not -path "./target/*" -not -path "./.git/*" -not -path "./node_modules/*" -not -name "*.bak"); do +find . -name "*.md" -type f -not -path "./target/*" -not -path "./.git/*" -not -path "./node_modules/*" -not -name "*.bak" | while read -r file; do update_refs "$file" 'docs/encryption/ENCRYPTION-QUICK-START\.md' 'docs/encryption/encryption-quick-start.md' update_refs "$file" 'encryption/ENCRYPTION-QUICK-START\.md' 'encryption/encryption-quick-start.md' update_refs "$file" 'ENCRYPTION-QUICK-START\.md' 'encryption-quick-start.md' @@ -99,17 +111,27 @@ for file in $(find . -name "*.md" -type f -not -path "./target/*" -not -path "./ done echo "" -echo "Step 4: Check for remaining uppercase doc references" +echo "Step 4: Update examples/ doc references" +echo "---------------------------------------" + +find . -name "*.md" -type f -not -path "./target/*" -not -path "./.git/*" -not -path "./node_modules/*" -not -name "*.bak" | while read -r file; do + update_refs "$file" 'SOPS-DEMO\.md' 'sops-demo.md' + update_refs "$file" 'TEST-SOPS-INTEGRATION\.md' 'test-sops-integration.md' + update_refs "$file" 'INTEGRATION_GUIDE\.md' 'integration-guide.md' +done + +echo "" +echo "Step 5: Check for remaining uppercase doc references" echo "-----------------------------------------------------" -remaining=$(grep -rE "BUILD\.md|CONFIGURATION\.md|DEVELOPMENT\.md|FIELD_TYPES\.md|INSTALLATION\.md|NICKEL\.md|PRE-COMMIT-SETUP\.md|RELEASE\.md|GETTING_STARTED\.md|LLM_PROVIDERS\.md|ENCRYPTION-QUICK-START\.md|ENCRYPTION-SERVICES-SETUP\.md|ENCRYPTION-UNIFIED-ARCHITECTURE\.md" \ +remaining=$(grep -rcE "BUILD\.md|CONFIGURATION\.md|DEVELOPMENT\.md|FIELD_TYPES\.md|INSTALLATION\.md|NICKEL\.md|PRE-COMMIT-SETUP\.md|RELEASE\.md|GETTING_STARTED\.md|LLM_PROVIDERS\.md|LLM_INTEGRATION\.md|ENCRYPTION-QUICK-START\.md|ENCRYPTION-SERVICES-SETUP\.md|ENCRYPTION-UNIFIED-ARCHITECTURE\.md|SOPS-DEMO\.md|TEST-SOPS-INTEGRATION\.md|INTEGRATION_GUIDE\.md" \ --include="*.md" --include="*.toml" --include="*.rs" \ --exclude-dir=target --exclude-dir=.git --exclude-dir=node_modules \ - --exclude="*.bak" . 2>/dev/null | grep -v "update-docs-refs.sh" | wc -l || echo "0") + --exclude="*.bak" . 2>/dev/null | grep -cv "update-docs-refs.sh" || echo "0") if [ "$remaining" -gt 0 ]; then echo "⚠️ Found $remaining remaining uppercase doc references:" - grep -rE "BUILD\.md|CONFIGURATION\.md|DEVELOPMENT\.md|FIELD_TYPES\.md|INSTALLATION\.md|NICKEL\.md|PRE-COMMIT-SETUP\.md|RELEASE\.md|GETTING_STARTED\.md|LLM_PROVIDERS\.md|ENCRYPTION-QUICK-START\.md|ENCRYPTION-SERVICES-SETUP\.md|ENCRYPTION-UNIFIED-ARCHITECTURE\.md" \ + grep -rE "BUILD\.md|CONFIGURATION\.md|DEVELOPMENT\.md|FIELD_TYPES\.md|INSTALLATION\.md|NICKEL\.md|PRE-COMMIT-SETUP\.md|RELEASE\.md|GETTING_STARTED\.md|LLM_PROVIDERS\.md|LLM_INTEGRATION\.md|ENCRYPTION-QUICK-START\.md|ENCRYPTION-SERVICES-SETUP\.md|ENCRYPTION-UNIFIED-ARCHITECTURE\.md|SOPS-DEMO\.md|TEST-SOPS-INTEGRATION\.md|INTEGRATION_GUIDE\.md" \ --include="*.md" --include="*.toml" --include="*.rs" \ --exclude-dir=target --exclude-dir=.git --exclude-dir=node_modules \ --exclude="*.bak" . 2>/dev/null | grep -v "update-docs-refs.sh" | head -10 diff --git a/scripts/update-references.sh b/scripts/update-references.sh index 045ea0f..3e0d4a3 100755 --- a/scripts/update-references.sh +++ b/scripts/update-references.sh @@ -94,7 +94,7 @@ echo "-------------------------------------------" echo "Searching for remaining 'imgs/' references..." remaining_imgs=$(grep -r "imgs/" --include="*.md" --include="*.html" --include="*.toml" \ --exclude-dir=target --exclude-dir=.git --exclude-dir=node_modules \ - --exclude="*.bak" . 2>/dev/null | grep -v ".coder" | wc -l || echo "0") + --exclude="*.bak" . 2>/dev/null | grep -cv ".coder" || echo "0") if [ "$remaining_imgs" -gt 0 ]; then echo "⚠️ Found $remaining_imgs remaining 'imgs/' references:" @@ -110,7 +110,7 @@ echo "Searching for remaining uppercase doc references..." remaining_docs=$(grep -rE "INSTALLATION\.md|DEPLOYMENT\.md|QUICKSTART\.md" \ --include="*.md" --include="*.toml" --include="*.rs" \ --exclude-dir=target --exclude-dir=.git --exclude-dir=node_modules \ - --exclude="*.bak" . 2>/dev/null | grep -v ".coder" | wc -l || echo "0") + --exclude="*.bak" . 2>/dev/null | grep -cv ".coder" || echo "0") if [ "$remaining_docs" -gt 0 ]; then echo "⚠️ Found $remaining_docs remaining uppercase doc references:" diff --git a/tests/test-agents.sh b/tests/test-agents.sh index a9cd7c0..25900a3 100755 --- a/tests/test-agents.sh +++ b/tests/test-agents.sh @@ -15,7 +15,7 @@ echo -e "${CYAN}=== TypeDialog Agent System Tests ===${NC}\n" # Test 1: Validate all agents echo -e "${YELLOW}Test 1: Validating all agents...${NC}" for agent in agents/*.agent.mdx; do - echo -n " Validating $(basename $agent)... " + echo -n " Validating $(basename "$agent")... " if cargo run --quiet --package typedialog-ag -- validate "$agent" > /dev/null 2>&1; then echo -e "${GREEN}✓${NC}" else @@ -102,7 +102,7 @@ echo -e "${GREEN}=== All tests passed! ===${NC}\n" # Summary echo -e "${CYAN}Available agents:${NC}" -ls -1 agents/*.agent.mdx | while read agent; do +find agents -name "*.agent.mdx" -type f | while read -r agent; do NAME=$(basename "$agent" .agent.mdx) echo " - $NAME" done @@ -119,9 +119,9 @@ echo " # Start HTTP server" echo " typedialog-ag serve --port 8765" echo "" echo " # Execute via HTTP" -echo ' curl -X POST http://localhost:8765/agents/greeting/execute \' -echo ' -H "Content-Type: application/json" \' -echo ' -d '"'"'{"name":"World"}'"'" +echo " curl -X POST http://localhost:8765/agents/greeting/execute \\" +echo " -H \"Content-Type: application/json\" \\" +echo " -d '{\"name\":\"World\"}'" echo "" echo -e "${GREEN}Ready to use!${NC}"