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

Compare commits

base: jesus:ab6c097819134f4a3a96eeb7e81b83b22b48d711
Branches Tags
jesus:main
..
compare: jesus:b6e4099ebc3b6319381d147c2a77f8810e79c960
Branches Tags
jesus:main

No commits in common. "ab6c097819134f4a3a96eeb7e81b83b22b48d711" and "b6e4099ebc3b6319381d147c2a77f8810e79c960" have entirely different histories.
ab6c097819 ... b6e4099ebc

91 changed files with 1410 additions and 1511 deletions
Show Stats Expand all files Collapse all files

79
.markdownlint-cli2.jsonc
View File

@ -1,79 +1,10 @@
// 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,
// 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/**"
]
"MD033": false,
"MD041": false,
"MD036": false,
"MD060": false
}
}

12
.pre-commit-config.yaml
View File

@ -23,9 +23,9 @@ repos:
# Rust formatting
- repo: local
hooks:
- id: rust-fmt
name: Rust formatting (cargo +nightly fmt)
entry: bash -c 'cargo +nightly fmt --all -- --check'
- id: cargo-fmt
name: cargo fmt
entry: cargo fmt
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.20.0
rev: v0.16.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|simple|i18n|arrays-schema)\.ncl$'
exclude: '(nickel-secrets|sops-example|conditional|complex)\.ncl$'
# Nushell script validation
- repo: local
hooks:
- id: nushell-check
name: nushell check
entry: bash -c 'for f in "$@"; do nu --ide-check 10 < "$f" > /dev/null || exit 1; done' --
entry: bash -c 'for f in "$@"; do nu --ide-check "$f" || exit 1; done' --
language: system
files: '\.nu$'
exclude: '(json-to-nickel)\.nu$'

4
.vale/styles/write-good/README.md
View File

@ -2,7 +2,7 @@ Based on [write-good](https://github.com/btford/write-good).
> Naive linter for English prose for developers who can't write good and wanna learn to do other stuff good too.
```text
```
The MIT License (MIT)
Copyright (c) 2014 Brian Ford
@ -24,4 +24,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```text
```

18
.woodpecker/README.md
View File

@ -62,10 +62,10 @@ docker push your-registry/typedialog-ci:latest
# Update .woodpecker/ci.yml and ci-advanced.yml
# Change: image: rust:latest
# To: image: your-registry/typedialog-ci:latest
```text
```
**Size comparison breakdown**:
```text
```
Original (Dockerfile):
Base Debian + buildtools: 1.6GB
Rust toolchain: 538MB
@ -79,7 +79,7 @@ Optimized (Dockerfile.prebuilt):
Binaries only: 140MB (no cargo cache)
--------------------------------
TOTAL: ~600MB
```text
```
### 3. Secrets Configuration
@ -102,14 +102,14 @@ The `release-docker.yml` pipeline requires access to Docker socket. Configure in
```yaml
# In Woodpecker server config
WOODPECKER_BACKEND_DOCKER_ENABLE_PRIVILEGED: true
```text
```
**Option B: Volume mount** (recommended):
Already configured in pipeline via:
```yaml
volumes:
- /var/run/docker.sock:/var/run/docker.sock
```text
```
Ensure Woodpecker agent has permission to access Docker socket.
@ -200,8 +200,8 @@ All release pipelines trigger on Git tags `v*` (e.g., `v0.1.0`).
| Caching | ✅ Built-in | ⚠️ Server-side** |
| SBOM | ✅ Auto-upload | ⚠️ Manual*** |
\* Multi-OS builds require multiple Woodpecker agents
\*\* Configure in Woodpecker server settings
\* Multi-OS builds require multiple Woodpecker agents
\*\* Configure in Woodpecker server settings
\*\*\* Manual upload to Gitea/Forgejo releases
## Triggering Pipelines
@ -213,7 +213,7 @@ git push origin main
# Release pipeline (manual tag)
git tag v0.1.0
git push origin v0.1.0
```text
```
**Selecting Release Pipeline**:
@ -228,7 +228,7 @@ Example:
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
```
Or configure in Woodpecker UI to enable/disable specific pipelines.

4
CONTRIBUTING.md
View File

@ -23,7 +23,7 @@ cd typedialog
# Run full validation
just check-all
```text
```
## Making Changes
@ -103,7 +103,7 @@ Open a GitHub Discussion first for:
See [SECURITY.md](SECURITY.md) for reporting process.
## Questions
## Questions?
- Discussions: GitHub Discussions
- Chat: (if applicable)

36
README.md
View File

@ -3,7 +3,7 @@
</div>
![Coverage](https://img.shields.io/badge/coverage-tracking-blue)
# TypeDialog
> ▲ Create Type-Safe Interactive Dialogs.
@ -69,7 +69,7 @@ cargo run --example form
# Run with defaults pre-loaded
typedialog form config.toml --defaults defaults.json
```text
```
## Backends at a Glance
@ -89,7 +89,7 @@ typedialog text "Email" --format json
# Pre-populate form with defaults
typedialog form schema.toml --defaults config.json --format json
```text
```
**Use for:** Scripts, CI/CD pipelines, server tools, piping between tools
**See:** [`examples/04-backends/cli/`](examples/04-backends/cli/)
@ -100,7 +100,7 @@ Full terminal UI with keyboard navigation and mouse support.
```bash
cargo run -p typedialog-tui --example form_with_autocompletion
```text
```
**Use for:** Interactive dashboards, system administration tools, complex forms
**See:** [`examples/04-backends/tui/`](examples/04-backends/tui/)
@ -112,7 +112,7 @@ HTTP server with browser-based forms.
```bash
cargo run -p typedialog-web -- --config config/web/dev.toml
# Open http://localhost:3000
```text
```
**Use for:** SaaS platforms, public forms, mobile-friendly interfaces
**See:** [`examples/04-backends/web/`](examples/04-backends/web/)
@ -127,7 +127,7 @@ typedialog-ai --config config/ai/dev.toml --query "How do I configure encryption
# Build knowledge graph
typedialog-ai --config config/ai/production.toml --build-graph ./docs
```text
```
**Use for:** Documentation search, context-aware assistance, knowledge retrieval, semantic search
**Features:**
@ -162,7 +162,7 @@ Create `hello.agent.mdx`:
---
Say hello to {{name}} in a warm and friendly way!
```text
```
Run it:
@ -170,7 +170,7 @@ Run it:
typedialog-ag hello.agent.mdx
# Prompts: name (String): Alice
# Output: Hello Alice! It's wonderful to meet you! ...
```text
```
### Supported LLM Providers
@ -200,7 +200,7 @@ typedialog-ag examples/12-agent-execution/creative-writer.agent.mdx
# Privacy-first analysis with Ollama (local)
typedialog-ag examples/12-agent-execution/local-privacy.agent.mdx
```text
```
**Learn more:**
@ -226,7 +226,7 @@ typedialog-prov-gen --name myproject --providers aws,hetzner --ai-assist
# Dry run (preview without generating)
typedialog-prov-gen --name myproject --dry-run
```text
```
### Provisioning Features
@ -269,7 +269,7 @@ typedialog form schema.toml --backend tui
# 3. Get validated output in any format
# JSON, YAML, TOML, or back to Nickel with type preservation
```text
```
**Benefits:**
@ -331,7 +331,7 @@ just distro::create-package
# Full CI/CD
just ci::full
```text
```
See [docs/development.md](docs/development.md) for details.
@ -341,7 +341,7 @@ See [docs/development.md](docs/development.md) for details.
```bash
just build::release
```text
```
Binaries in `target/release/`
@ -351,7 +351,7 @@ Binaries in `target/release/`
just distro::build-release
just distro::create-package
just distro::create-checksums
```text
```
Package includes binaries, configs, and installers.
@ -365,7 +365,7 @@ curl -fsSL https://github.com/anthropics/typedialog/releases/download/latest/ins
# Windows PowerShell
irm https://github.com/anthropics/typedialog/releases/download/latest/install.ps1 | iex
```text
```
See [docs/release.md](docs/release.md) for release workflow.
@ -381,7 +381,7 @@ config/
├── ai/ # default, dev, production (RAG/embeddings)
├── ag/ # default, dev, production (Agent/LLM)
└── prov-gen/ # default, dev, production (IaC generation)
```text
```
See [docs/configuration.md](docs/configuration.md) and [config/README.md](config/README.md) for all options.
@ -406,7 +406,7 @@ typedialog/
├── docs/ # Documentation
├── justfile # Command orchestration
└── Cargo.toml # Workspace manifest
```text
```
## Key Technologies
@ -461,7 +461,7 @@ just distro::build-release # Release build
just distro::create-package # Package
just distro::create-checksums # Checksums
just distro::package-release # Prepare release
```text
```
## System Requirements

2
SECURITY.md
View File

@ -12,7 +12,7 @@
### Private Reporting
Send vulnerability reports to: **<jpl@jesusperez.com>**
Send vulnerability reports to: **jpl@jesusperez.com**
Include in your report:
- Description of the vulnerability

26
agents/README.md
View File

@ -18,7 +18,7 @@ typedialog-ag agents/greeting.agent.mdx
curl -X POST http://localhost:8765/agents/greeting/execute \
-H "Content-Type: application/json" \
-d '{"name":"Alice"}'
```text
```
### 2. code-reviewer.agent.mdx
**Purpose**: Comprehensive code review
@ -34,7 +34,7 @@ curl -X POST http://localhost:8765/agents/code-reviewer/execute \
"language": "rust",
"code": "fn add(a: i32, b: i32) -> i32 { a + b }"
}'
```text
```
### 3. architect.agent.mdx
**Purpose**: Software architecture design
@ -50,7 +50,7 @@ curl -X POST http://localhost:8765/agents/architect/execute \
"feature": "Real-time chat system",
"tech_stack": "Rust, WebSockets, PostgreSQL"
}'
```text
```
### 4. summarizer.agent.mdx
**Purpose**: Text summarization
@ -65,7 +65,7 @@ curl -X POST http://localhost:8765/agents/summarizer/execute \
"text": "Long article text here...",
"style": "technical"
}'
```text
```
### 5. test-generator.agent.mdx
**Purpose**: Generate unit tests
@ -81,7 +81,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
```
### 6. doc-generator.agent.mdx
**Purpose**: Generate technical documentation
@ -96,7 +96,7 @@ curl -X POST http://localhost:8765/agents/doc-generator/execute \
"language": "javascript",
"code": "function debounce(fn, delay) { ... }"
}'
```text
```
### 7. translator.agent.mdx
**Purpose**: Language translation
@ -112,7 +112,7 @@ curl -X POST http://localhost:8765/agents/translator/execute \
"source_lang": "English",
"target_lang": "Spanish"
}'
```text
```
### 8. debugger.agent.mdx
**Purpose**: Debug code issues
@ -129,7 +129,7 @@ curl -X POST http://localhost:8765/agents/debugger/execute \
"code": "let x = vec![1,2,3]; println!(\"{}\", x[5]);",
"error": "index out of bounds: the len is 3 but the index is 5"
}'
```text
```
### 9. refactor.agent.mdx
**Purpose**: Code refactoring
@ -146,7 +146,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 readability and type safety"
}'
```text
```
## Features Demonstrated
@ -187,7 +187,7 @@ typedialog-ag transpile agents/greeting.agent.mdx
# Execute (interactive)
typedialog-ag agents/greeting.agent.mdx
```text
```
### HTTP Server Testing
```bash
@ -206,7 +206,7 @@ curl -X POST http://localhost:8765/validate \
curl -X POST http://localhost:8765/agents/greeting/execute \
-H "Content-Type: application/json" \
-d '{"name":"World"}'
```text
```
## Best Practices
@ -225,7 +225,7 @@ Ensure you have API keys configured:
```bash
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-... # If using OpenAI models
```text
```
## Cache
@ -236,6 +236,6 @@ typedialog-ag cache stats
# Clear cache
typedialog-ag cache clear
```text
```
Cache location: `~/.typeagent/cache/`

14
assets/BRANDING.md
View File

@ -72,7 +72,7 @@ The TypeDialog logo is composed of three essential elements that work together t
/* CSS usage */
font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
```text
```
### Sizing
@ -165,7 +165,7 @@ font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
.cursor {
animation: blink 1s ease-in-out infinite;
}
```text
```
- **Duration**: 1 second
- **Function**: ease-in-out (smooth acceleration/deceleration)
@ -183,7 +183,7 @@ font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
.text-pulse {
animation: text-pulse 3s ease-in-out infinite;
}
```text
```
- **Duration**: 3 seconds
- **Function**: ease-in-out
@ -248,25 +248,25 @@ Format: `typedialog_[component]_[variant].svg`
### Web - Header Logo
```html
<img src="/assets/typedialog_logo_h.svg" alt="TypeDialog" width="240" height="64">
```text
```
### App - Favicon
```html
<link rel="icon" href="/assets/favicon.svg" type="image/svg+xml">
<link rel="icon" href="/assets/favicon-32.png" type="image/png" sizes="32x32">
```text
```
### Email - Static Logo
```html
<!-- Export typedialog_logo_h_s.svg as PNG, then embed -->
<img src="typedialog-logo.png" alt="TypeDialog" width="240" height="64">
```text
```
### Print - Monochrome Logo
```html
<!-- Use typedialog_logo_bn.svg -->
<img src="typedialog_logo_bn.svg" alt="TypeDialog" width="100%">
```text
```
---

20
assets/README.md
View File

@ -13,7 +13,7 @@ Official logo assets for **TypeDialog** — typed dialogs for inputs, forms and
<!-- Logo in header -->
<img src="/assets/typedialog_logo_h.svg" alt="TypeDialog" width="240">
```text
```
### For React/Vue
@ -23,13 +23,13 @@ import logo from '/assets/typedialog_logo_h.svg';
export default function Header() {
return <img src={logo} alt="TypeDialog" width={240} />;
}
```text
```
### For Markdown/Docs
```markdown
![TypeDialog](/assets/typedialog_logo_h.svg)
```text
```
---
@ -110,7 +110,7 @@ export default function Header() {
--td-primary: #3a3a50; /* Primary gray */
--td-accent: #4f46e5; /* Accent indigo */
--td-white: #ffffff; /* Contrast */
```text
```
---
@ -198,7 +198,7 @@ All TypeDialog branding uses **Inter** font (Google Fonts).
```css
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@500&display=swap');
font-family: "Inter", -apple-system, BlinkMacSystemFont, sans-serif;
```text
```
- **Weights**: 400 (regular), 500 (medium), 600 (semibold)
- **Sizes**: 14-24px (responsive)
@ -221,7 +221,7 @@ font-family: "Inter", -apple-system, BlinkMacSystemFont, sans-serif;
height: auto;
}
</style>
```text
```
### Markdown
@ -229,13 +229,13 @@ font-family: "Inter", -apple-system, BlinkMacSystemFont, sans-serif;
# ![TypeDialog](/assets/typedialog_logo_h.svg) Welcome
[Link text](/)
```text
```
### Rust / Markdown Docs
```markdown
![TypeDialog](assets/typedialog_logo_h.svg)
```text
```
---
@ -253,7 +253,7 @@ font-family: "Inter", -apple-system, BlinkMacSystemFont, sans-serif;
<!-- Path elements for bubble, brackets, cursor -->
<!-- Text element for wordmark -->
</svg>
```text
```
### Scalability
@ -298,7 +298,7 @@ TypeDialog logo is part of the TypeDialog project. Use according to project lice
---
## Questions
## Questions?
Refer to the comprehensive documentation:
1. `index.html` for visual reference

48
assets/how-to-use.md
View File

@ -65,7 +65,7 @@ Quick integration guide with code examples for different frameworks and contexts
</style>
</body>
</html>
```text
```
### React
@ -84,7 +84,7 @@ export default function Header() {
</header>
);
}
```text
```
### Vue
@ -111,7 +111,7 @@ import TypeDialogLogo from '@/assets/assets/typedialog_logo_h.svg';
height: auto;
}
</style>
```text
```
### Svelte
@ -130,7 +130,7 @@ import TypeDialogLogo from '@/assets/assets/typedialog_logo_h.svg';
height: auto;
}
</style>
```text
```
### Angular
@ -148,7 +148,7 @@ import TypeDialogLogo from '@/assets/assets/typedialog_logo_h.svg';
max-width: 240px;
height: auto;
}
```text
```
---
@ -158,13 +158,13 @@ import TypeDialogLogo from '@/assets/assets/typedialog_logo_h.svg';
```markdown
![TypeDialog](./assets/typedialog_logo_h.svg)
```text
```
### With Link
```markdown
[![TypeDialog](./assets/typedialog_logo_h.svg)](https://yoursite.com)
```text
```
### mdBook / GitHub Docs
@ -172,7 +172,7 @@ import TypeDialogLogo from '@/assets/assets/typedialog_logo_h.svg';
# ![TypeDialog](../assets/typedialog_logo_h.svg) Welcome to TypeDialog
Content here...
```text
```
### Rust Project README
@ -182,7 +182,7 @@ Content here...
![TypeDialog](assets/typedialog_logo_h.svg)
Typed dialogs for inputs, forms and schemas you can trust.
```text
```
---
@ -196,7 +196,7 @@ Typed dialogs for inputs, forms and schemas you can trust.
<link rel="icon" href="/assets/favicon-16.png" type="image/png" sizes="16x16">
<link rel="apple-touch-icon" href="/assets/favicon-64.png">
<link rel="icon" href="/assets/favicon.ico" sizes="16x16 32x32 64x64">
```text
```
### Hero Section
@ -221,7 +221,7 @@ Typed dialogs for inputs, forms and schemas you can trust.
to { opacity: 1; transform: translateY(0); }
}
</style>
```text
```
### Navigation Bar
@ -247,7 +247,7 @@ Typed dialogs for inputs, forms and schemas you can trust.
height: auto;
}
</style>
```text
```
---
@ -270,7 +270,7 @@ Typed dialogs for inputs, forms and schemas you can trust.
</td>
</tr>
</table>
```text
```
### Social Media
@ -281,7 +281,7 @@ Typed dialogs for inputs, forms and schemas you can trust.
<meta property="og:image:alt" content="TypeDialog Logo">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
```text
```
---
@ -334,7 +334,7 @@ body.dark-mode {
width: 240px;
height: 64px;
}
```text
```
### SVG Direct Approach
@ -362,7 +362,7 @@ body.dark-mode {
.logo-dark { display: block; }
}
</style>
```text
```
---
@ -376,7 +376,7 @@ body.dark-mode {
<!-- Avoid huge SVGs if PNG export available -->
<img src="assets/typedialog_logo_h.png" alt="TypeDialog" width="240">
```text
```
### CSS Loading
@ -387,7 +387,7 @@ body.dark-mode {
/* Use data URIs for very small files */
.logo { background-image: url('data:image/svg+xml;...'); }
```text
```
### Caching
@ -399,7 +399,7 @@ body.dark-mode {
/>
<!-- Or use service workers for offline support -->
```text
```
---
@ -415,7 +415,7 @@ body.dark-mode {
<a href="/">
<img src="assets/typedialog_icon.svg" alt="Home">
</a>
```text
```
### ARIA Labels
@ -426,7 +426,7 @@ body.dark-mode {
alt="TypeDialog"
aria-label="TypeDialog - Typed dialogs for inputs, forms and schemas you can trust"
/>
```text
```
### Animation Preferences
@ -439,7 +439,7 @@ body.dark-mode {
/* Option 2: Disable animations */
.logo * { animation: none !important; }
}
```text
```
---
@ -498,14 +498,14 @@ convert typedialog_logo_h.svg typedialog_logo_h.png
# Using online tool
# https://convertio.co/svg-png/
```text
```
### PDF Export
```bash
# Using Inkscape
inkscape typedialog_logo_h.svg --export-filename=typedialog_logo_h.pdf
```text
```
---

50
config/README.md
View File

@ -6,7 +6,7 @@ Pre-configured settings for each typedialog backend and environment.
Configuration files are organized by **backend** (CLI, TUI, Web, AI, Agent, Prov-gen) and **environment** (default, dev, production).
```text
```
config/
├── cli/
│ ├── default.toml # Standard CLI settings
@ -32,7 +32,7 @@ config/
├── default.toml # Standard provisioning settings
├── dev.toml # Development (Hetzner/LXD)
└── production.toml # Production (AWS/GCP)
```text
```
## Backend Configurations
@ -49,7 +49,7 @@ config/
**Usage:**
```bash
typedialog --config config/cli/production.toml form.toml
```text
```
**Features:**
- Inline validation
@ -70,7 +70,7 @@ typedialog --config config/cli/production.toml form.toml
**Usage:**
```bash
typedialog-tui --config config/tui/production.toml form.toml
```text
```
**Features:**
- 3-panel layout (fields, input, buttons)
@ -92,7 +92,7 @@ typedialog-tui --config config/tui/production.toml form.toml
```bash
typedialog-web --config config/web/production.toml
# Server starts on http://localhost:8080
```text
```
**Features:**
- HTML/CSS rendering
@ -113,7 +113,7 @@ typedialog-web --config config/web/production.toml
**Usage:**
```bash
typedialog-ai --config config/ai/production.toml --query "user question"
```text
```
**Features:**
- RAG pipeline for context retrieval
@ -134,7 +134,7 @@ typedialog-ai --config config/ai/production.toml --query "user question"
**Usage:**
```bash
typedialog-ag --config config/ag/production.toml task.agent.mdx
```text
```
**Features:**
- Multi-provider (Claude, OpenAI, Gemini, Ollama)
@ -155,7 +155,7 @@ typedialog-ag --config config/ag/production.toml task.agent.mdx
**Usage:**
```bash
typedialog-prov-gen --config config/prov-gen/production.toml --name myproject
```text
```
**Features:**
- Multi-cloud support (AWS, GCP, Hetzner, UpCloud, LXD)
@ -198,7 +198,7 @@ temperature = 0.7
default_providers = ["hetzner", "lxd"]
verbose = true
log_level = "debug"
```text
```
**Usage:**
```bash
@ -208,7 +208,7 @@ typedialog-web --config config/web/dev.toml
typedialog-ai --config config/ai/dev.toml --query "question"
typedialog-ag --config config/ag/dev.toml task.agent.mdx
typedialog-prov-gen --config config/prov-gen/dev.toml --name project
```text
```
### Production Configuration
@ -249,7 +249,7 @@ default_providers = ["aws", "gcp"]
strict_validation = true
require_encryption = true
require_tests = true
```text
```
**Usage:**
```bash
@ -259,7 +259,7 @@ typedialog-web --config config/web/production.toml
typedialog-ai --config config/ai/production.toml --query "question"
typedialog-ag --config config/ag/production.toml task.agent.mdx
typedialog-prov-gen --config config/prov-gen/production.toml --name project
```text
```
## Common Settings
@ -274,7 +274,7 @@ description = "Optional description"
validate_on_change = true
show_errors_inline = true
strict_validation = true
```text
```
### Output Configuration
@ -283,7 +283,7 @@ strict_validation = true
format = "json" # json, yaml, toml, text
pretty_print = true
debug_output = false
```text
```
### Logging
@ -291,7 +291,7 @@ debug_output = false
[logging]
level = "info" # debug, info, warn, error
file = "/var/log/typedialog/app.log"
```text
```
## Custom Configuration
@ -308,7 +308,7 @@ nano config/cli/custom.toml
# Use it
typedialog --config config/cli/custom.toml form.toml
```text
```
### Override Specific Settings
@ -328,7 +328,7 @@ typedialog-tui --config config/tui/default.toml form.toml
export TYPEDIALOG_WEB_PORT=3000
export TYPEDIALOG_WEB_CORS_ORIGINS="localhost,example.com"
typedialog-web --config config/web/default.toml
```text
```
## CLI Backend Configuration Details
@ -350,7 +350,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
@ -380,7 +380,7 @@ emacs_mode = false
[performance]
render_throttle = 16 # milliseconds
max_fps = 60 # frames per second
```text
```
## Web Backend Configuration Details
@ -413,7 +413,7 @@ cache_static = true
cache_ttl = 3600
enable_compression = true
compression_threshold = 1024
```text
```
## AI Backend Configuration Details
@ -439,7 +439,7 @@ ttl = 3600 # seconds
[ai.knowledge_graph]
enabled = false
max_depth = 3
```text
```
## Agent Backend Configuration Details
@ -474,7 +474,7 @@ timestamp = true
[agent.logging]
level = "info" # debug, info, warn, error
file = true
```text
```
## Provisioning Generator Configuration Details
@ -517,7 +517,7 @@ require_tests = false
[provisioning.security]
require_encryption = false
scan_templates = false
```text
```
## Distribution Configurations
@ -538,7 +538,7 @@ distribution/typedialog-0.1.0/
│ ├── ag/
│ └── prov-gen/
└── ...
```text
```
Users can then choose configs during installation:
@ -552,7 +552,7 @@ bash installers/install.sh
# Use specific config
typedialog --config ~/.config/typedialog/cli/production.toml form.toml
```text
```
## Best Practices

6
config/ag/README.md
View File

@ -24,13 +24,13 @@ typedialog-ag run agent.mdx # Explicit run command
typedialog-ag transpile agent.mdx -o out.ncl # Transpile to Nickel
typedialog-ag validate agent.mdx # Validate without executing
typedialog-ag cache clear|stats # Manage cache
```text
```
With custom configuration:
```bash
typedialog-ag -c ~/.config/typedialog/ag/config.toml run agent.mdx
TYPEDIALOG_ENV=dev typedialog-ag run agent.mdx
```text
```
### Agent HTTP Server Mode
Start HTTP API server for remote agent execution:
@ -39,7 +39,7 @@ typedialog-ag serve # Start server (127.0.0.1:8765)
typedialog-ag serve --port 9000 # Custom port
typedialog-ag serve --host 0.0.0.0 # Public interface
typedialog-ag -c ~/.config/typedialog/ag/server-default.toml serve
```text
```
Server endpoints:
- `GET /health` - Health check

16
crates/typedialog-agent/README.md
View File

@ -15,7 +15,7 @@ Part of the [TypeDialog](https://github.com/yourusername/typedialog) ecosystem.
## Architecture
```text
```
Layer 1: Markup Parser
.agent.mdx → AST
Parse @directives, {{variables}}, markdown
@ -25,7 +25,7 @@ Layer 2: Nickel Transpiler + Evaluator
Layer 3: Executor
AgentDefinition + Inputs → LLM → Validated Output
```text
```
## Quick Start
@ -43,7 +43,7 @@ typeagent validate architect.agent.mdx
# Start HTTP server
typeagent serve --port 8765
```text
```
### Programmatic Usage
@ -67,7 +67,7 @@ async fn main() -> anyhow::Result<()> {
println!("{}", result.output);
Ok(())
}
```text
```
## Integration with TypeDialog Ecosystem
@ -80,7 +80,7 @@ typedialog form agent-builder.toml --backend ai
# 2. Execute with typeagent
typeagent architect.agent.mdx
```text
```
### With Vapora (MCP Plugin)
@ -91,16 +91,16 @@ use typedialog_ag_core::AgentLoader;
let loader = AgentLoader::new();
let agent = loader.load(Path::new("agents/architect.agent.mdx")).await?;
// Execute via Vapora orchestration
```text
```
## Project Structure
```text
```
typedialog-agent/
├── typedialog-ag-core/ # Core library (reusable)
├── typedialog-ag/ # CLI binary
└── typedialog-ag-server/ # HTTP server
```text
```
## Documentation

40
docs/agent/quickstart.md → crates/typedialog-agent/quickstart.md
View File

@ -13,20 +13,20 @@ Get started with TypeAgent in 5 minutes.
```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
@ -45,17 +45,17 @@ Create `hello.agent.mdx`:
---
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
@ -69,7 +69,7 @@ Agent Configuration:
Temperature: 0.7
name (String): Alice█
```text
```
Type a name and press Enter. The agent will execute and show the response!
@ -83,19 +83,19 @@ 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
@ -113,7 +113,7 @@ typeagent agent.mdx --verbose
# 4. Run in production
typeagent agent.mdx
```text
```
### Quick Iteration
@ -123,7 +123,7 @@ Use `--yes` to skip prompts during development:
# Edit agent.mdx
# Run without prompts
typeagent agent.mdx --yes
```text
```
## Advanced Features
@ -134,7 +134,7 @@ Import files into your agent:
```markdown
@import "./docs/**/*.md" as documentation
@shell "git log --oneline -5" as recent_commits
```text
```
### Output Validation
@ -146,7 +146,7 @@ Ensure output meets requirements:
format: markdown,
min_length: 100
}
```text
```
### Conditional Logic
@ -156,7 +156,7 @@ Use Tera template syntax:
{% if has_description %}
Description: {{ description }}
{% endif %}
```text
```
## Troubleshooting
@ -164,7 +164,7 @@ Description: {{ description }}
```bash
export ANTHROPIC_API_KEY=sk-ant-...
```text
```
### "Failed to parse agent MDX"
@ -177,13 +177,13 @@ Check your frontmatter syntax:
llm: claude-3-5-haiku-20241022
}
---
```text
```
### "Permission denied"
```bash
chmod +x ./target/release/typeagent
```text
```
## Learn More
@ -234,12 +234,12 @@ Provide:
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!

47
docs/agent/llm-integration.md → crates/typedialog-agent/typedialog-ag-core/LLM_INTEGRATION.md
View File

@ -5,21 +5,18 @@ TypeAgent Core now includes full LLM execution capabilities, allowing agents to
## 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
@ -27,10 +24,9 @@ TypeAgent Core now includes full LLM execution capabilities, allowing agents to
- 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: <http://localhost:11434>)
- Requires: Ollama running locally (default: http://localhost:11434)
- 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
@ -40,24 +36,21 @@ TypeAgent Core now includes full LLM execution capabilities, allowing agents to
### 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
@ -70,7 +63,7 @@ ollama pull llama2
# Optional: Override default URL
export OLLAMA_BASE_URL=http://localhost:11434
```text
```
### 2. Create Agent MDX File
@ -83,7 +76,7 @@ export OLLAMA_BASE_URL=http://localhost:11434
---
Hello {{ name }}! How can I help you today?
```text
```
### 3. Execute Agent
@ -116,7 +109,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
Ok(())
}
```text
```
## Configuration
@ -130,7 +123,7 @@ Agent configuration is specified in the MDX frontmatter:
max_tokens: 4096, # Optional (default: 4096)
temperature: 0.7 # Optional (default: 0.7)
}
```text
```
## LLM Provider Architecture
@ -142,7 +135,7 @@ pub trait LlmProvider: Send + Sync {
async fn complete(&self, request: LlmRequest) -> Result<LlmResponse>;
fn name(&self) -> &str;
}
```text
```
### Request/Response
@ -160,7 +153,7 @@ pub struct LlmResponse {
pub model: String,
pub usage: Option<TokenUsage>,
}
```text
```
### Automatic Provider Selection
@ -177,7 +170,7 @@ The executor automatically selects the correct provider based on model name:
```bash
cargo run --example llm_execution
```text
```
### Compare All Providers
@ -190,19 +183,19 @@ 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
@ -222,7 +215,7 @@ match executor.execute(&agent_def, inputs).await {
}
}
}
```text
```
## Token Usage Tracking
@ -240,7 +233,7 @@ if let Some(usage) = response.usage {
println!("Output tokens: {}", usage.output_tokens);
println!("Total tokens: {}", usage.total_tokens);
}
```text
```
## Context Injection
@ -267,7 +260,7 @@ Review the following code:
{{ 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.
@ -283,7 +276,7 @@ Output validation runs automatically after LLM execution:
min_length: 100
}
---
```text
```
Validation results are included in `ExecutionResult`:
@ -293,7 +286,7 @@ if !result.validation_passed {
eprintln!("Validation error: {}", error);
}
}
```text
```
## Cost Optimization
@ -307,7 +300,7 @@ if !result.validation_passed {
```rust
agent_def.config.max_tokens = 500; // Limit response length
```text
```
### Cache Context
@ -323,7 +316,7 @@ cargo test --package typedialog-ag-core
# Run LLM tests (requires ANTHROPIC_API_KEY)
cargo test --package typedialog-ag-core -- --ignored
```text
```
## Implementation Files
@ -352,7 +345,7 @@ let result = executor.execute_streaming(&agent_def, inputs, |chunk| {
println!("\n\nFinal output: {}", result.output);
println!("Tokens: {:?}", result.metadata.tokens);
```text
```
The CLI automatically uses streaming for real-time token display.

80
crates/typedialog-agent/typedialog-ag/README.md
View File

@ -6,13 +6,13 @@ Command-line interface for executing type-safe AI agents defined in MDX format.
```bash
cargo install --path crates/typedialog-agent/typedialog-ag
```text
```
Or build from source:
```bash
cargo build --release --package typedialog-ag
```text
```
## Setup
@ -20,7 +20,7 @@ Set your API key:
```bash
export ANTHROPIC_API_KEY=your-api-key-here
```text
```
## Usage
@ -30,25 +30,25 @@ Run an agent with interactive prompts for inputs:
```bash
typeagent agent.mdx
```text
```
Or use the explicit `run` command:
```bash
typeagent run agent.mdx
```text
```
Skip input prompts (use defaults):
```bash
typeagent agent.mdx --yes
```text
```
Verbose output (show Nickel code):
```bash
typeagent agent.mdx --verbose
```text
```
### Validate an Agent
@ -56,10 +56,10 @@ Check syntax, transpilation, and type checking without executing:
```bash
typeagent validate agent.mdx
```text
```
Output:
```text
```
✓ Validating agent
✓ MDX syntax valid
@ -74,7 +74,7 @@ Agent Summary:
Temperature: 0.7
✓ Agent is valid and ready to execute
```text
```
### Transpile to Nickel
@ -86,7 +86,7 @@ typeagent transpile agent.mdx
# Save to file
typeagent transpile agent.mdx -o agent.ncl
```text
```
Output:
```nickel
@ -98,7 +98,7 @@ Output:
inputs = {},
template = "Write a haiku about {{ topic }}.",
}
```text
```
## Example Session
@ -117,7 +117,7 @@ Create `haiku.agent.mdx`:
---
Write a haiku about {{ topic }}. Return only the haiku, nothing else.
```text
```
### 2. Validate the Agent
@ -138,7 +138,7 @@ Agent Summary:
Temperature: 0.7
✓ Agent is valid and ready to execute
```text
```
### 3. Execute the Agent
@ -177,7 +177,7 @@ Metadata:
Duration: 1234ms
Tokens: 87
Validation: ✓ PASSED
```text
```
## Agent File Format
@ -200,7 +200,7 @@ Metadata:
---
Your template content with {{ variables }}.
```text
```
### Directives
@ -214,7 +214,7 @@ Defines the agent configuration.
llm: claude-3-5-haiku-20241022,
tools: [] # Optional
}
```text
```
**Supported models:**
- `claude-3-5-haiku-20241022` - Fast, cheap
@ -228,7 +228,7 @@ Declares inputs that will be prompted to the user.
```markdown
@input name: String # Required input
@input description?: String # Optional input
```text
```
#### `@validate` (Optional)
@ -242,7 +242,7 @@ Defines output validation rules.
min_length: 100,
max_length: 5000
}
```text
```
**Supported formats:**
- `markdown` (default)
@ -257,7 +257,7 @@ Import file content into template variables.
```markdown
@import "./docs/**/*.md" as documentation
@import "https://example.com/schema.json" as schema
```text
```
#### `@shell` (Optional)
@ -266,7 +266,7 @@ Execute shell commands and inject output.
```markdown
@shell "git diff HEAD~1" as recent_changes
@shell "cargo tree" as dependencies
```text
```
### Template Syntax
@ -284,7 +284,7 @@ Uses [Tera template engine](https://tera.netlify.app/):
# Filters
{{ name | upper }}
{{ value | default(value="fallback") }}
```text
```
## Commands
@ -300,7 +300,7 @@ Execute an agent (default command).
**Example:**
```bash
typeagent agent.mdx --yes --verbose
```text
```
### `typeagent run <FILE>`
@ -312,7 +312,7 @@ Explicit execute command (same as default).
**Example:**
```bash
typeagent run agent.mdx
```text
```
### `typeagent validate <FILE>`
@ -321,7 +321,7 @@ Validate agent without execution.
**Example:**
```bash
typeagent validate agent.mdx
```text
```
### `typeagent transpile <FILE>`
@ -333,7 +333,7 @@ Transpile MDX to Nickel.
**Example:**
```bash
typeagent transpile agent.mdx -o agent.ncl
```text
```
### `typeagent cache`
@ -354,34 +354,34 @@ Cache management (not yet implemented).
### Missing API Key
```text
```
Error: ANTHROPIC_API_KEY environment variable not set
Set ANTHROPIC_API_KEY to use Claude models
```text
```
**Solution:** Export your API key:
```bash
export ANTHROPIC_API_KEY=sk-ant-...
```text
```
### Invalid Agent File
```text
```
Error: Failed to parse agent MDX
```text
```
**Solution:** Validate your agent file:
```bash
typeagent validate agent.mdx
```text
```
### Validation Failures
```text
```
Validation: ✗ FAILED
- Output must contain: Security
- Output too short: 45 chars (minimum: 100)
```text
```
The agent executed successfully but output validation failed. Adjust your `@validate` rules or improve your prompt.
@ -401,13 +401,13 @@ Make sure the binary is in your PATH:
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```text
```
Or use the full path:
```bash
./target/release/typeagent
```text
```
### Permission denied
@ -415,7 +415,7 @@ Make the binary executable:
```bash
chmod +x ./target/release/typeagent
```text
```
### Slow compilation
@ -424,7 +424,7 @@ Use release mode for better performance:
```bash
cargo build --release --package typedialog-ag
./target/release/typeagent agent.mdx
```text
```
## Development
@ -432,13 +432,13 @@ Run from source:
```bash
cargo run --package typedialog-ag -- agent.mdx
```text
```
Run with logging:
```bash
RUST_LOG=debug cargo run --package typedialog-ag -- agent.mdx
```text
```
## License

11
crates/typedialog-prov-gen/templates/scripts/config.sh
View File

@ -18,12 +18,9 @@ set -euo pipefail
# CONFIGURATION
# ============================================================================
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 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly PROVISIONING_DIR="$(dirname "$SCRIPT_DIR")"
readonly PROJECT_ROOT="$(dirname "$PROVISIONING_DIR")"
readonly ENVS_DIR="${PROJECT_ROOT}/envs"
readonly VALUES_DIR="${PROVISIONING_DIR}/values"
readonly FORM_PATH="${PROVISIONING_DIR}/config-form.toml"
@ -115,7 +112,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"

4
docs/README.md
View File

@ -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

66
docs/agent/README.md
View File

@ -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](llm-integration.md) - Complete technical guide
- [LLM Integration](../../crates/typedialog-agent/typedialog-ag-core/LLM_INTEGRATION.md) - Complete technical guide
- [Core Examples](../../crates/typedialog-agent/typedialog-ag-core/examples/) - Rust API usage
- [Developer Docs](../../crates/typedialog-agent/README.md) - Architecture and APIs
@ -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)
---

90
docs/agent/getting-started.md → docs/agent/getting_started.md
View File

@ -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.
```text
```markdown
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/)

70
docs/agent/installation.md
View File

@ -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 <PID>
# 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
```
---

52
docs/agent/llm-providers.md → docs/agent/llm_providers.md
View File

@ -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](llm-integration.md)
**For technical details:** See [LLM_INTEGRATION.md](../../crates/typedialog-agent/typedialog-ag-core/LLM_INTEGRATION.md)

40
docs/ai/README.md
View File

@ -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
```
---

126
docs/build.md
View File

@ -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
```
1. **Update Cargo.toml paths:**
2. **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" }
```
1. **Use git submodules:**
3. **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
```
1. **Add to PATH:**
2. **Add to PATH:**
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```
1. **Set explicit path in environment:**
3. **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
```
1. **Install via package manager:**
2. **Install via package manager:**
```bash
# macOS
@ -404,7 +404,7 @@ just: command not found
sudo pacman -S just
```
1. **Add to PATH:**
3. **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

14
docs/ci/README.md
View File

@ -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

48
docs/cli/README.md
View File

@ -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 <prompt> # Password input
typedialog editor <prompt> # Open editor
typedialog date <prompt> # Date picker
typedialog form <file> # Run form from TOML
```text
```
### Global Flags
@ -154,7 +154,7 @@ typedialog form <file> # Run form from TOML
--yes # Non-interactive mode
--config <file> # Config file
--log-level <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
```
---

42
docs/configuration.md
View File

@ -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

52
docs/deployment.md
View File

@ -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
```
---

64
docs/development.md
View File

@ -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

10
docs/encryption/README.md
View File

@ -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"

14
docs/encryption/encryption-quick-start.md
View File

@ -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

98
docs/encryption/encryption-services-setup.md
View File

@ -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
```
---

50
docs/encryption/encryption-unified-architecture.md
View File

@ -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<encrypt::BackendSpec>
```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

48
docs/field-types.md → docs/field_types.md
View File

@ -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
```
---

52
docs/fragment-search-paths.md
View File

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

2
docs/history.md
View File

@ -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)

55
docs/installation.md
View File

@ -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,25 +273,24 @@ 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/)
1. Install just:
2. Install just:
```powershell
cargo install just
```
1. Or use Scoop:
3. Or use Scoop:
```powershell
scoop install just

90
docs/nickel.md
View File

@ -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
```
1. **Use correct path syntax:**
2. **Use correct path syntax:**
```toml
# Flat field
@ -362,7 +362,7 @@ For roundtrip to work, your form MUST:
nickel_path = ["ci", "tools", "linters"]
```
1. **Match template variables:**
3. **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<String, FieldContract>,
pub global: Vec<Contract>,
}
```text
```
### I18nExtractor
@ -763,7 +763,7 @@ impl I18nExtractor {
pub fn new() -> Self;
pub fn extract(&self, ast: &NickelAst) -> Result<I18nMap>;
}
```text
```
### NickelTemplateContext
@ -776,7 +776,7 @@ pub struct NickelTemplateContext {
impl NickelTemplateContext {
pub fn from_schema(schema: NickelSchemaIR) -> Result<Self>;
}
```text
```
### RoundtripConfig
@ -796,7 +796,7 @@ impl Default for RoundtripConfig {
}
}
}
```text
```
## Next Steps

54
docs/pre-commit-setup.md
View File

@ -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
```
---

58
docs/prov-gen/README.md
View File

@ -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
```
---

72
docs/quickstart.md
View File

@ -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

46
docs/release.md
View File

@ -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

42
docs/tui/README.md
View File

@ -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"

62
docs/web/README.md
View File

@ -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:
</div>
<button class="add-item-btn">Add Item</button>
</div>
```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
```
---

6
examples/01-basic/README.md
View File

@ -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

8
examples/02-advanced/README.md
View File

@ -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
```

6
examples/03-styling/README.md
View File

@ -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
```

4
examples/04-backends/README.md
View File

@ -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

2
examples/04-backends/cli/README.md
View File

@ -10,7 +10,7 @@ Command-line interface form examples.
```bash
cargo run --example autocompletion_demo
```text
```
## Features

2
examples/04-backends/tui/README.md
View File

@ -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

4
examples/04-backends/web/README.md
View File

@ -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

16
examples/05-fragments/README.md
View File

@ -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

10
examples/06-integrations/i18n/README.md
View File

@ -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

6
examples/06-integrations/nickel/README.md
View File

@ -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

62
examples/07-nickel-generation/README.md
View File

@ -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**: `<feature>_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 <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 \
<schema> \
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

4
examples/07-nickel-generation/arrays-schema.ncl
View File

@ -82,7 +82,9 @@
api_token | String,
# API port number (1024-65535)
api_port | Number,
api_port | Number
| std.number.is_between 1024 65535 ?
| "API port must be between 1024 and 65535",
# Array of API endpoints exposed by the service
# In TypeDialog: RepeatingGroup field with fragment defining ApiEndpoint fields

63
examples/07-nickel-generation/schemas/i18n.ncl
View File

@ -2,39 +2,48 @@
# Demonstrates multi-language form generation with Fluent
{
app_name = ""
| doc "Application name / Nombre de la aplicación"
| String,
app_name
| doc "Application name"
| doc.es "Nombre de la aplicación"
: String,
app_version = "1.0.0"
| doc "Application version / Versión de la aplicación"
| String,
app_version
| doc "Application version"
| doc.es "Versión de la aplicación"
: String = "1.0.0",
server_host = "0.0.0.0"
| doc "Server host address / Dirección del host del servidor"
| String,
server_host
| doc "Server host address"
| doc.es "Dirección del host del servidor"
: String = "0.0.0.0",
server_port = 8080
| doc "Server port number / Número de puerto del servidor"
| Number,
server_port
| doc "Server port number"
| doc.es "Número de puerto del servidor"
: Number = 8080,
database_url = ""
| doc "Database connection URL / URL de conexión a la base de datos"
| String,
database_url
| doc "Database connection URL"
| doc.es "URL de conexión a la base de datos"
: String,
enable_caching = true
| doc "Enable caching layer / Habilitar capa de caché"
| Bool,
enable_caching
| doc "Enable caching layer"
| doc.es "Habilitar capa de caché"
: Bool = true,
cache_ttl = 3600
| doc "Cache time-to-live in seconds / Tiempo de vida del caché en segundos"
| Number,
cache_ttl
| doc "Cache time-to-live in seconds"
| doc.es "Tiempo de vida del caché en segundos"
: Number = 3600,
admin_email = ""
| doc "Administrator email address / Dirección de correo del administrador"
| String,
admin_email
| doc "Administrator email address"
| doc.es "Dirección de correo del administrador"
: String,
enable_notifications = false
| doc "Enable email notifications / Habilitar notificaciones por correo"
| Bool,
enable_notifications
| doc "Enable email notifications"
| doc.es "Habilitar notificaciones por correo"
: Bool = false,
}

44
examples/08-encryption/README.md
View File

@ -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
```

62
examples/08-encryption/SOPS-DEMO.md
View File

@ -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
```
---

88
examples/08-encryption/TEST-SOPS-INTEGRATION.md
View File

@ -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
```
---

10
examples/08-encryption/quick-sops-demo.sh
View File

@ -61,7 +61,7 @@ echo " Creating plaintext YAML file..."
cat > "test-secret.yaml" << 'EOF'
secret: my-super-secret-password-123
EOF
sed 's/^/ /' "test-secret.yaml"
cat "test-secret.yaml" | sed 's/^/ /'
echo -e "\n Encrypting with SOPS..."
export SOPS_AGE_KEY_FILE="$AGE_KEY_FILE"
@ -146,9 +146,7 @@ if [ -n "$PASSWORD_CT" ] && [ "$PASSWORD_CT" != "null" ]; then
fi
else
echo -e "${YELLOW} ⚠ SOPS test output:\n${NC}"
while IFS= read -r line; do
echo " $line"
done <<< "$OUTPUT"
echo "$OUTPUT" | sed 's/^/ /'
echo ""
fi
@ -159,7 +157,7 @@ echo -e "${BLUE}========================================${NC}\n"
echo "Demo directory: $DEMO_DIR"
echo "Files created:"
find "$DEMO_DIR" -maxdepth 1 -type f -printf ' - %f\n' | sort
ls -1h "$DEMO_DIR" | sed 's/^/ - /'
echo -e "\n${YELLOW}Key Takeaways:${NC}"
echo " ✓ SOPS can encrypt/decrypt YAML files"
@ -178,7 +176,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}"

7
examples/08-encryption/sops-integration-test.sh
View File

@ -286,8 +286,9 @@ EOF
sops -e -i "$TEST_FILE"
print_success "Encrypted with SOPS"
# Display encrypted content preview
print_info "Encrypted (hex representation would be): sops:v1:$(xxd -p < "$TEST_FILE" | head -c 50)..."
# 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)..."
# Decrypt with SOPS (ensure Age key is available)
AGE_KEY_FILE="$TEST_DIR/.age/key.txt"
@ -402,7 +403,7 @@ print_summary() {
echo " - Age key: $TEST_DIR/.age/key.txt"
echo ""
echo "Files created:"
find "$TEST_DIR" -maxdepth 1 -type f -printf '%TY-%Tm-%Td %TH:%TM %10s %p\n' 2>/dev/null | sort -r | head -5
ls -lh "$TEST_DIR"/ 2>/dev/null | tail -5
echo ""
echo "Next steps:"
echo " 1. Try manual encryption:"

28
examples/08-nickel-roundtrip/README.md
View File

@ -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

2
examples/09-templates/README.md
View File

@ -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

12
examples/09-templates/employee_onboarding/README.md
View File

@ -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

12
examples/09-templates/library_catalog/README.md
View File

@ -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<String>, // 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

14
examples/09-templates/user_registration/README.md
View File

@ -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

28
examples/10-ai-backend/integration-guide.md → examples/10-ai-backend/INTEGRATION_GUIDE.md
View File

@ -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

10
examples/10-ai-backend/README.md
View File

@ -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

46
examples/11-prov-gen/README.md
View File

@ -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

12
examples/11-prov-gen/mode-a-cargo/README.md
View File

@ -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

24
examples/11-prov-gen/mode-b-config/README.md
View File

@ -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
```

48
examples/11-prov-gen/mode-c-wizard/README.md
View File

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

28
examples/11-prov-gen/mode-d-nickel/README.md
View File

@ -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

40
examples/11-prov-gen/output-example/README.md
View File

@ -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

10
examples/12-agent-execution/README-demos.md
View File

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

50
examples/12-agent-execution/README.md
View File

@ -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/<example>.agent.mdx
```text
```
### With Input Variables
@ -192,16 +192,16 @@ cargo run --package typedialog-ag -- examples/12-agent-execution/<example>.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

24
examples/13-conditional-logic/README.md
View File

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

36
examples/README.md
View File

@ -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

24
install/README.md
View File

@ -7,19 +7,19 @@ Quick installation scripts for all platforms.
Install with `curl`:
```bash
curl -fsSL https://github.com/anthropics/typedialog/releases/download/latest/install.sh | bash
```text
```
Or with `wget`:
```bash
wget -qO - https://github.com/anthropics/typedialog/releases/download/latest/install.sh | bash
```text
```
## Windows
Open PowerShell and run:
```powershell
irm https://github.com/anthropics/typedialog/releases/download/latest/install.ps1 | iex
```text
```
## Manual Installation
@ -34,7 +34,7 @@ bash install.sh
# Or with environment variables
INSTALL_DIR="$HOME/bin" CONFIG_DIR="$HOME/.typedialog" bash install.sh
```text
```
### Windows
@ -47,7 +47,7 @@ Invoke-WebRequest -Uri "https://github.com/anthropics/typedialog/releases/downlo
# Or with parameters
.\install.ps1 -InstallDir "C:\Program Files\typedialog" -ConfigDir "C:\Users\$env:USERNAME\AppData\Local\typedialog"
```text
```
## Configuration
@ -91,7 +91,7 @@ typedialog-web --version
# List available configurations
ls ~/.config/typedialog/
```text
```
## Troubleshooting
@ -103,27 +103,27 @@ Update your PATH:
```bash
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
source ~/.bashrc
```text
```
**zsh:**
```bash
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc
source ~/.zshrc
```text
```
### Permission denied
Make binaries executable:
```bash
chmod +x ~/.local/bin/typedialog*
```text
```
### Configuration issues
Check configuration directory:
```bash
cat ~/.config/typedialog/cli/default.toml
```text
```
## Uninstallation
@ -135,7 +135,7 @@ rm ~/.local/bin/typedialog*
# Remove configurations (optional)
rm -rf ~/.config/typedialog/
```text
```
## Platform Support
@ -175,7 +175,7 @@ cd typedialog
tar -xzf distribution/typedialog-0.1.0.tar.gz
cp typedialog-0.1.0/bin/* ~/.local/bin/
cp -r typedialog-0.1.0/config/* ~/.config/typedialog/
```text
```
## Support

4
install/install.sh
View File

@ -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

6
scripts/build_all.sh
View File

@ -6,10 +6,8 @@ set -euo pipefail
# Returns: 0 on success, 1 on failure
# Output: Build progress and results
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly SCRIPT_DIR
WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
readonly WORKSPACE_ROOT
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
readonly PROFILE="${1:-debug}"
# Function: Print info message

6
scripts/build_cross.sh
View File

@ -6,10 +6,8 @@ set -euo pipefail
# Returns: 0 on success, 1 on failure
# Output: Cross-compilation progress
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly SCRIPT_DIR
WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
readonly WORKSPACE_ROOT
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
readonly TARGET="${1:-}"
# Supported targets for cross-compilation

9
scripts/create_distro.sh
View File

@ -6,10 +6,8 @@ set -euo pipefail
# Returns: 0 on success, 1 on failure
# Output: Distribution package path
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly SCRIPT_DIR
WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
readonly WORKSPACE_ROOT
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
readonly DISTRO_DIR="${WORKSPACE_ROOT}/distribution"
readonly BUILD_DIR="${WORKSPACE_ROOT}/target/release"
@ -173,8 +171,7 @@ EOF
# Function: Create tarball
create_tarball() {
local distro_path="$1"
local distro_name
distro_name=$(basename "$distro_path")
local distro_name=$(basename "$distro_path")
local tarball="${DISTRO_DIR}/${distro_name}.tar.gz"
cd "$DISTRO_DIR"

6
scripts/package_release.sh
View File

@ -6,10 +6,8 @@ set -euo pipefail
# Returns: 0 on success, 1 on failure
# Output: Final release package path
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly SCRIPT_DIR
WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
readonly WORKSPACE_ROOT
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
readonly DISTRO_DIR="${WORKSPACE_ROOT}/distribution"
readonly RELEASE_DIR="${WORKSPACE_ROOT}/release"

52
scripts/update-docs-refs.sh
View File

@ -39,7 +39,7 @@ echo "Step 1: Update root-level doc references"
echo "-----------------------------------------"
# Find all markdown files and update references
find . -name "*.md" -type f -not -path "./target/*" -not -path "./.git/*" -not -path "./node_modules/*" -not -name "*.bak" | while read -r file; do
for file in $(find . -name "*.md" -type f -not -path "./target/*" -not -path "./.git/*" -not -path "./node_modules/*" -not -name "*.bak"); do
# Root level docs
update_refs "$file" 'docs/BUILD\.md' 'docs/build.md'
update_refs "$file" 'BUILD\.md' 'build.md'
@ -50,10 +50,8 @@ find . -name "*.md" -type f -not -path "./target/*" -not -path "./.git/*" -not -
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" '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/FIELD_TYPES\.md' 'docs/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'
@ -72,31 +70,21 @@ echo ""
echo "Step 2: Update agent/ 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" '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'
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'
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'
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'
done
echo ""
echo "Step 3: Update encryption/ 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
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/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'
@ -111,27 +99,17 @@ find . -name "*.md" -type f -not -path "./target/*" -not -path "./.git/*" -not -
done
echo ""
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 "Step 4: Check for remaining uppercase doc references"
echo "-----------------------------------------------------"
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" \
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" \
--include="*.md" --include="*.toml" --include="*.rs" \
--exclude-dir=target --exclude-dir=.git --exclude-dir=node_modules \
--exclude="*.bak" . 2>/dev/null | grep -cv "update-docs-refs.sh" || echo "0")
--exclude="*.bak" . 2>/dev/null | grep -v "update-docs-refs.sh" | wc -l || 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|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" \
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" \
--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

4
scripts/update-references.sh
View File

@ -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 -cv ".coder" || echo "0")
--exclude="*.bak" . 2>/dev/null | grep -v ".coder" | wc -l || 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 -cv ".coder" || echo "0")
--exclude="*.bak" . 2>/dev/null | grep -v ".coder" | wc -l || echo "0")
if [ "$remaining_docs" -gt 0 ]; then
echo "⚠️ Found $remaining_docs remaining uppercase doc references:"

18
templates/nickel/README.md
View File

@ -43,7 +43,7 @@ Use in form templates with Tera include syntax:
contract: "std.string.NonEmpty",
default: "myapp"
} %}
```text
```
### Form Templates
@ -51,7 +51,7 @@ Render a complete schema:
```bash
typedialog nickel-template forms/config_schema.ncl.j2 form_results.json -o config.ncl
```text
```
### Macro Templates
@ -60,14 +60,14 @@ Include macros in custom templates:
```jinja2
{% include "macros/contracts.ncl.j2" %}
{% include "macros/validation.ncl.j2" %}
```text
```
Then use the defined macros:
```jinja2
{{ non_empty_string("username", "User login name") }}
{{ port_number("server_port", "HTTP port") }}
```text
```
## Template Context Variables
@ -83,7 +83,7 @@ Templates expect the following context from form results:
"options": ["option1", "option2"],
"groups_by_section": { "section_name": [...fields...] }
}
```text
```
## Examples
@ -108,13 +108,13 @@ default = "1.0.0"
name = "debug_mode"
type = "confirm"
prompt = "Enable debug mode"
```text
```
Render with template:
```bash
typedialog nickel-template forms/config_schema.ncl.j2 results.json -o config.ncl
```text
```
Output:
@ -126,7 +126,7 @@ Output:
debug_mode | doc "Enable debug mode" : Bool = true,
},
}
```text
```
### Service Specification
@ -140,7 +140,7 @@ typedialog nickel-template forms/service_spec.ncl.j2 \
service_results.json -o service.ncl
nickel export service.ncl
```text
```
## Extending

20
tests/agent/README.md
View File

@ -23,7 +23,7 @@ cargo run --package typedialog-ag -- tests/agent/test-openai.agent.mdx
# Test Gemini provider
cargo run --package typedialog-ag -- tests/agent/test-gemini.agent.mdx
```text
```
### Requirements
@ -38,7 +38,7 @@ export OPENAI_API_KEY=sk-...
# For Gemini test
export GEMINI_API_KEY=...
```text
```
## Unit Tests
@ -53,7 +53,7 @@ cargo test --package typedialog-ag-core llm::
# Run with ignored tests (requires API keys)
cargo test --package typedialog-ag-core -- --ignored
```text
```
## Integration Tests
@ -65,7 +65,7 @@ cargo test --package typedialog-ag-core --test integration_test
# Run simple integration test
cargo test --package typedialog-ag-core --test simple_integration_test
```text
```
## Test Coverage
@ -127,21 +127,21 @@ To add a new test agent:
## Troubleshooting
### API Key Not Set
```text
```
Error: ANTHROPIC_API_KEY environment variable not set
```text
```
**Solution**: Set the appropriate environment variable
### Quota Exceeded
```text
```
Error: 429 Too Many Requests
```text
```
**Solution**: Wait for quota reset or upgrade API plan
### Ollama Not Running
```text
```
Error: Failed to call Ollama API - is Ollama running?
```text
```
**Solution**: Start Ollama server with `ollama serve`
## See Also

10
tests/test-agents.sh
View File

@ -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}"
find agents -name "*.agent.mdx" -type f | while read -r agent; do
ls -1 agents/*.agent.mdx | while read 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}"