milo-cli 0.2.2__tar.gz → 0.3.0__tar.gz

{milo_cli-0.2.2 → milo_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: milo-cli
-Version: 0.2.2
+Version: 0.3.0
 Summary: Template-driven CLI applications for free-threaded Python
 License-Expression: MIT
 Project-URL: Homepage, https://lbliii.github.io/milo-cli/
@@ -18,9 +18,9 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
-Requires-Dist: kida-templates>=0.6.0
+Requires-Dist: kida-templates<0.8.0,>=0.7.0
 Provides-Extra: docs
-Requires-Dist: bengal>=0.2.6; extra == "docs"
+Requires-Dist: bengal>=0.3.2; extra == "docs"
 Provides-Extra: yaml
 Requires-Dist: pyyaml>=6.0; extra == "yaml"
 Provides-Extra: watch
@@ -92,18 +92,22 @@ Milo is a Python framework where every CLI is simultaneously a terminal app, a c
 
 ## Installation
 
+**Requires Python 3.14+.** If you don't have it: `uv python install 3.14`.
+
 ```bash
 pip install milo-cli
 ```
 
 The PyPI package is **milo-cli**; import the **`milo`** namespace in Python. The `milo` console command is installed with the package.
 
-Requires Python 3.14+
-
 ---
 
 ## Quick Start
 
+> **Coding agents**: jump to [`docs/agent-quickstart.md`](./docs/agent-quickstart.md)
+> for a 5-minute walkthrough from `@cli.command` to a verified Claude MCP tool call.
+> See also [`docs/testing.md`](./docs/testing.md) for the test template.
+
 ### AI-Native CLI
 
 | Function | Description |
@@ -140,31 +144,79 @@ Requires Python 3.14+
 
 | Feature | Description | Docs |
 |---------|-------------|------|
-| **MCP Server** | Every CLI doubles as an MCP server — AI agents discover and call commands via JSON-RPC | [MCP →](https://lbliii.github.io/milo-cli/docs/usage/mcp/) |
-| **MCP Gateway** | Single gateway aggregates all registered Milo CLIs for unified AI agent access | [MCP →](https://lbliii.github.io/milo-cli/docs/usage/mcp/) |
-| **Tool Annotations** | Declare `readOnlyHint`, `destructiveHint`, `idempotentHint` per MCP spec | [MCP →](https://lbliii.github.io/milo-cli/docs/usage/mcp/) |
-| **Streaming Progress** | Commands yield `Progress` objects; MCP clients receive real-time notifications | [MCP →](https://lbliii.github.io/milo-cli/docs/usage/mcp/) |
-| **Schema Constraints** | `Annotated[str, MinLen(1), MaxLen(100)]` generates rich JSON Schema | [CLI →](https://lbliii.github.io/milo-cli/docs/usage/cli/) |
-| **llms.txt** | Generate AI-readable discovery documents from CLI command definitions | [llms.txt →](https://lbliii.github.io/milo-cli/docs/usage/llms/) |
-| **Middleware** | Intercept MCP calls and CLI commands for logging, auth, and transformation | [CLI →](https://lbliii.github.io/milo-cli/docs/usage/cli/) |
-| **Observability** | Built-in request logging with latency stats (`milo://stats` resource) | [MCP →](https://lbliii.github.io/milo-cli/docs/usage/mcp/) |
-| **State Management** | Redux-style `Store` with dispatch, listeners, middleware, and saga scheduling | [State →](https://lbliii.github.io/milo-cli/docs/usage/state/) |
-| **Commands** | Lightweight `Cmd` thunks, `Batch`, `Sequence`, `TickCmd` for one-shot effects | [Commands →](https://lbliii.github.io/milo-cli/docs/usage/commands-effects/) |
-| **Sagas** | Generator-based side effects: `Call`, `Put`, `Select`, `Fork`, `Delay`, `Retry`, `Race`, `All`, `Take`, and more | [Sagas →](https://lbliii.github.io/milo-cli/docs/usage/sagas/) |
-| **ViewState** | Declarative terminal state (`cursor_visible`, `alt_screen`, `window_title`, `mouse_mode`) | [Commands →](https://lbliii.github.io/milo-cli/docs/usage/commands-effects/) |
-| **Flows** | Multi-screen state machines with `>>` operator and custom transitions | [Flows →](https://lbliii.github.io/milo-cli/docs/usage/flows/) |
-| **Forms** | Text, select, confirm, password fields with validation and TTY fallback | [Forms →](https://lbliii.github.io/milo-cli/docs/usage/forms/) |
-| **Input Handling** | Cross-platform key reader with full escape sequence support (arrows, F-keys, modifiers) | [Input →](https://lbliii.github.io/milo-cli/docs/usage/input/) |
-| **Templates** | Kida-powered terminal rendering with built-in form, field, help, and progress templates | [Templates →](https://lbliii.github.io/milo-cli/docs/usage/templates/) |
-| **Dev Server** | `milo dev` with filesystem polling and `@@HOT_RELOAD` dispatch | [Dev →](https://lbliii.github.io/milo-cli/docs/usage/dev/) |
-| **Session Recording** | JSONL action log with state hashes for debugging and regression testing | [Testing →](https://lbliii.github.io/milo-cli/docs/usage/testing/) |
-| **Snapshot Testing** | `assert_renders`, `assert_state`, `assert_saga` for deterministic test coverage | [Testing →](https://lbliii.github.io/milo-cli/docs/usage/testing/) |
-| **Pipeline** | Declarative multi-phase workflows with dependency graphs, retry policies, and output capture | [Pipeline →](https://lbliii.github.io/milo-cli/docs/usage/pipeline/) |
-| **Help Rendering** | `HelpRenderer` — drop-in `argparse.HelpFormatter` using Kida templates | [Help →](https://lbliii.github.io/milo-cli/docs/usage/help/) |
-| **Context** | Execution context with verbosity, output format, global options, and `run_app()` bridge | [Context →](https://lbliii.github.io/milo-cli/docs/usage/context/) |
-| **Configuration** | `Config` with validation, init scaffolding, and profile support | [Config →](https://lbliii.github.io/milo-cli/docs/usage/config/) |
-| **Shell Completions** | Generate bash/zsh/fish completions from CLI definitions | [CLI →](https://lbliii.github.io/milo-cli/docs/usage/cli/) |
-| **Doctor Diagnostics** | `run_doctor()` validates environment, dependencies, and config health | [CLI →](https://lbliii.github.io/milo-cli/docs/usage/cli/) |
+| **MCP Server** | Every CLI doubles as an MCP server — AI agents discover and call commands via JSON-RPC | [MCP →](https://lbliii.github.io/milo-cli/docs/build-clis/mcp/) |
+| **MCP Gateway** | Single gateway aggregates all registered Milo CLIs for unified AI agent access | [MCP →](https://lbliii.github.io/milo-cli/docs/build-clis/mcp/) |
+| **Tool Annotations** | Declare `readOnlyHint`, `destructiveHint`, `idempotentHint` per MCP spec | [MCP →](https://lbliii.github.io/milo-cli/docs/build-clis/mcp/) |
+| **Streaming Progress** | Commands yield `Progress` objects; MCP clients receive real-time notifications | [MCP →](https://lbliii.github.io/milo-cli/docs/build-clis/mcp/) |
+| **Schema Constraints** | `Annotated[str, MinLen(1), MaxLen(100)]` generates rich JSON Schema | [CLI →](https://lbliii.github.io/milo-cli/docs/build-clis/commands/) |
+| **llms.txt** | Generate AI-readable discovery documents from CLI command definitions | [llms.txt →](https://lbliii.github.io/milo-cli/docs/build-clis/llms/) |
+| **Middleware** | Intercept MCP calls and CLI commands for logging, auth, and transformation | [CLI →](https://lbliii.github.io/milo-cli/docs/build-clis/commands/) |
+| **Observability** | Built-in request logging with latency stats (`milo://stats` resource) | [MCP →](https://lbliii.github.io/milo-cli/docs/build-clis/mcp/) |
+| **State Management** | Redux-style `Store` with dispatch, listeners, middleware, and saga scheduling | [State →](https://lbliii.github.io/milo-cli/docs/build-apps/state/) |
+| **Commands** | Lightweight `Cmd` thunks, `Batch`, `Sequence`, `TickCmd` for one-shot effects | [Commands →](https://lbliii.github.io/milo-cli/docs/build-apps/commands-effects/) |
+| **Sagas** | Generator-based side effects: `Call`, `Put`, `Select`, `Fork`, `Delay`, `Retry`, `Race`, `All`, `Take`, and more | [Sagas →](https://lbliii.github.io/milo-cli/docs/build-apps/sagas/) |
+| **ViewState** | Declarative terminal state (`cursor_visible`, `alt_screen`, `window_title`, `mouse_mode`) | [Commands →](https://lbliii.github.io/milo-cli/docs/build-apps/commands-effects/) |
+| **Flows** | Multi-screen state machines with `>>` operator and custom transitions | [Flows →](https://lbliii.github.io/milo-cli/docs/build-apps/flows/) |
+| **Forms** | Text, select, confirm, password fields with validation and TTY fallback | [Forms →](https://lbliii.github.io/milo-cli/docs/build-apps/forms/) |
+| **Input Handling** | Cross-platform key reader with VT100/xterm escape sequence support (arrows, F-keys, modifiers) | [Input →](https://lbliii.github.io/milo-cli/docs/build-apps/input/) |
+| **Templates** | Kida-powered terminal rendering with built-in form, field, help, and progress templates | [Templates →](https://lbliii.github.io/milo-cli/docs/build-apps/templates/) |
+| **Dev Server** | `milo dev` with filesystem polling and `@@HOT_RELOAD` dispatch | [Dev →](https://lbliii.github.io/milo-cli/docs/build-apps/dev/) |
+| **Session Recording** | JSONL action log with state hashes for debugging and regression testing | [Testing →](https://lbliii.github.io/milo-cli/docs/quality/testing/) |
+| **Snapshot Testing** | `assert_renders`, `assert_state`, `assert_saga` for deterministic test coverage | [Testing →](https://lbliii.github.io/milo-cli/docs/quality/testing/) |
+| **Pipeline** | Declarative multi-phase workflows with dependency graphs, retry policies, and output capture | [Pipeline →](https://lbliii.github.io/milo-cli/docs/quality/pipeline/) |
+| **Help Rendering** | `HelpRenderer` — drop-in `argparse.HelpFormatter` using Kida templates | [Help →](https://lbliii.github.io/milo-cli/docs/build-clis/help/) |
+| **Context** | Execution context with verbosity, output format, global options, and `run_app()` bridge | [Context →](https://lbliii.github.io/milo-cli/docs/build-clis/context/) |
+| **Configuration** | `Config` with validation, init scaffolding, and profile support | [Config →](https://lbliii.github.io/milo-cli/docs/about/concepts/configuration/) |
+| **Shell Completions** | Generate bash/zsh/fish completions from CLI definitions | [CLI →](https://lbliii.github.io/milo-cli/docs/build-clis/commands/) |
+| **Doctor Diagnostics** | `run_doctor()` validates environment, dependencies, and config health | [CLI →](https://lbliii.github.io/milo-cli/docs/build-clis/commands/) |
+
+---
+
+## Examples Index
+
+Pick the example closest to your use case, copy its `app.py`, and adapt. See [examples/README.md](examples/README.md) for run commands, copy paths, and tested starting points.
+
+**CLIs (typed function → CLI + MCP + llms.txt)**
+
+| What you want to build | Example | Key APIs |
+|---|---|---|
+| The simplest possible CLI | [examples/greet](examples/greet) | `CLI`, `@cli.command` |
+| Dual-mode CLI ↔ MCP server (flagship) | [examples/deploy](examples/deploy) | `Annotated`, `MinLen`, `Context`, `Progress`, `--mcp` |
+| Context injection, logging, progress, confirms | [examples/ctxdemo](examples/ctxdemo) | `Context`, `ctx.info`, `ctx.progress`, `ctx.confirm` |
+| Nested command groups (`app repo list`) | [examples/groups](examples/groups) | `cli.group()`, `walk_commands` |
+| Fast startup via deferred imports | [examples/lazyapp](examples/lazyapp) | `cli.lazy_command()` |
+| Production CLI with hooks, completions, doctor | [examples/devtool](examples/devtool) | `run_doctor`, `before_run`/`after_run`, did-you-mean, completions |
+| AI-native CLI surfacing tools + resources | [examples/taskman](examples/taskman) | `@command`, `@resource`, `--format`, `--llms-txt`, `--mcp` |
+| Advanced terminal reports and diagnostics | [examples/outputgallery](examples/outputgallery) | `Context.render`, Kida templates, character maps, JSON output |
+
+**Configuration, plugins, pipelines**
+
+| What you want to build | Example | Key APIs |
+|---|---|---|
+| TOML config with profiles + overlays | [examples/configapp](examples/configapp) | `Config`, `ConfigSpec`, `Config.load`, `Config.validate` |
+| Plugin system with hooks + listeners | [examples/pluggable](examples/pluggable) | `HookRegistry`, `define`, `on`, `invoke` |
+| Multi-phase pipeline with deps + retries | [examples/buildpipe](examples/buildpipe) | `Pipeline`, `Phase`, `PhasePolicy`, `>>` |
+
+**Interactive TUIs (`App` + reducer)**
+
+| What you want to build | Example | Key APIs |
+|---|---|---|
+| The simplest TUI | [examples/counter](examples/counter) | `App.from_dir`, reducer combinators |
+| Modal input with derived filtering | [examples/todo](examples/todo) | tuple state, `quit_on`, derived views |
+| Tick-driven animation | [examples/stopwatch](examples/stopwatch) | `tick_rate`, `@@TICK`, `quit_on` |
+| Scrollable viewport with saga I/O | [examples/filepicker](examples/filepicker) | viewport, sagas, frozen tuples |
+| Multi-screen flow with forms | [examples/wizard](examples/wizard) | `Flow`, `FlowScreen`, `make_form_reducer`, `FieldSpec` |
+
+**Async work (sagas + Cmd pattern)**
+
+| What you want to build | Example | Key APIs |
+|---|---|---|
+| Sagas for async side effects | [examples/fetcher](examples/fetcher) | `Call`, `Put`, `Select`, `Retry` |
+| Parallel concurrent work | [examples/downloader](examples/downloader) | `Fork`, `Call`, `Delay`, `Timeout` |
+| Bubbletea-style Cmd thunks | [examples/spinner](examples/spinner) | `Cmd`, `Batch`, `TickCmd`, `ViewState` |
+| Live rendering outside an App | [examples/liverender](examples/liverender) | `milo.live.LiveRenderer`, `Spinner`, `terminal_env` |
+
+> Don't see your use case? Run `milo new <name>` to scaffold a fresh CLI with tests, then `milo verify app.py` to confirm it works.
 
 ---
 
@@ -456,11 +508,12 @@ App.run()
 
 | Section | Description |
 |---------|-------------|
+| [About](https://lbliii.github.io/milo-cli/docs/about/) | Philosophy, architecture, concepts, and lifecycle |
 | [Get Started](https://lbliii.github.io/milo-cli/docs/get-started/) | Installation and quickstart |
-| [MCP & AI](https://lbliii.github.io/milo-cli/docs/usage/mcp/) | MCP server, gateway, annotations, streaming, and llms.txt |
-| [Usage](https://lbliii.github.io/milo-cli/docs/usage/) | State, sagas, flows, forms, templates |
-| [Testing](https://lbliii.github.io/milo-cli/docs/usage/testing/) | Snapshots, recording, replay |
-| [Reference](https://lbliii.github.io/milo-cli/docs/reference/) | Complete API documentation |
+| [Build CLIs](https://lbliii.github.io/milo-cli/docs/build-clis/) | Commands, groups, MCP, llms.txt, context, output, and help |
+| [Build Apps](https://lbliii.github.io/milo-cli/docs/build-apps/) | State, reducers, templates, input, forms, flows, sagas, and live rendering |
+| [Quality](https://lbliii.github.io/milo-cli/docs/quality/) | Testing, verification, debugging, and pipelines |
+| [Reference](https://lbliii.github.io/milo-cli/docs/reference/) | Schema, dispatch, error codes, actions, and types |
 
 ---
 

{milo_cli-0.2.2 → milo_cli-0.3.0}/README.md

@@ -64,18 +64,22 @@ Milo is a Python framework where every CLI is simultaneously a terminal app, a c
 
 ## Installation
 
+**Requires Python 3.14+.** If you don't have it: `uv python install 3.14`.
+
 ```bash
 pip install milo-cli
 ```
 
 The PyPI package is **milo-cli**; import the **`milo`** namespace in Python. The `milo` console command is installed with the package.
 
-Requires Python 3.14+
-
 ---
 
 ## Quick Start
 
+> **Coding agents**: jump to [`docs/agent-quickstart.md`](./docs/agent-quickstart.md)
+> for a 5-minute walkthrough from `@cli.command` to a verified Claude MCP tool call.
+> See also [`docs/testing.md`](./docs/testing.md) for the test template.
+
 ### AI-Native CLI
 
 | Function | Description |
@@ -112,31 +116,79 @@ Requires Python 3.14+
 
 | Feature | Description | Docs |
 |---------|-------------|------|
-| **MCP Server** | Every CLI doubles as an MCP server — AI agents discover and call commands via JSON-RPC | [MCP →](https://lbliii.github.io/milo-cli/docs/usage/mcp/) |
-| **MCP Gateway** | Single gateway aggregates all registered Milo CLIs for unified AI agent access | [MCP →](https://lbliii.github.io/milo-cli/docs/usage/mcp/) |
-| **Tool Annotations** | Declare `readOnlyHint`, `destructiveHint`, `idempotentHint` per MCP spec | [MCP →](https://lbliii.github.io/milo-cli/docs/usage/mcp/) |
-| **Streaming Progress** | Commands yield `Progress` objects; MCP clients receive real-time notifications | [MCP →](https://lbliii.github.io/milo-cli/docs/usage/mcp/) |
-| **Schema Constraints** | `Annotated[str, MinLen(1), MaxLen(100)]` generates rich JSON Schema | [CLI →](https://lbliii.github.io/milo-cli/docs/usage/cli/) |
-| **llms.txt** | Generate AI-readable discovery documents from CLI command definitions | [llms.txt →](https://lbliii.github.io/milo-cli/docs/usage/llms/) |
-| **Middleware** | Intercept MCP calls and CLI commands for logging, auth, and transformation | [CLI →](https://lbliii.github.io/milo-cli/docs/usage/cli/) |
-| **Observability** | Built-in request logging with latency stats (`milo://stats` resource) | [MCP →](https://lbliii.github.io/milo-cli/docs/usage/mcp/) |
-| **State Management** | Redux-style `Store` with dispatch, listeners, middleware, and saga scheduling | [State →](https://lbliii.github.io/milo-cli/docs/usage/state/) |
-| **Commands** | Lightweight `Cmd` thunks, `Batch`, `Sequence`, `TickCmd` for one-shot effects | [Commands →](https://lbliii.github.io/milo-cli/docs/usage/commands-effects/) |
-| **Sagas** | Generator-based side effects: `Call`, `Put`, `Select`, `Fork`, `Delay`, `Retry`, `Race`, `All`, `Take`, and more | [Sagas →](https://lbliii.github.io/milo-cli/docs/usage/sagas/) |
-| **ViewState** | Declarative terminal state (`cursor_visible`, `alt_screen`, `window_title`, `mouse_mode`) | [Commands →](https://lbliii.github.io/milo-cli/docs/usage/commands-effects/) |
-| **Flows** | Multi-screen state machines with `>>` operator and custom transitions | [Flows →](https://lbliii.github.io/milo-cli/docs/usage/flows/) |
-| **Forms** | Text, select, confirm, password fields with validation and TTY fallback | [Forms →](https://lbliii.github.io/milo-cli/docs/usage/forms/) |
-| **Input Handling** | Cross-platform key reader with full escape sequence support (arrows, F-keys, modifiers) | [Input →](https://lbliii.github.io/milo-cli/docs/usage/input/) |
-| **Templates** | Kida-powered terminal rendering with built-in form, field, help, and progress templates | [Templates →](https://lbliii.github.io/milo-cli/docs/usage/templates/) |
-| **Dev Server** | `milo dev` with filesystem polling and `@@HOT_RELOAD` dispatch | [Dev →](https://lbliii.github.io/milo-cli/docs/usage/dev/) |
-| **Session Recording** | JSONL action log with state hashes for debugging and regression testing | [Testing →](https://lbliii.github.io/milo-cli/docs/usage/testing/) |
-| **Snapshot Testing** | `assert_renders`, `assert_state`, `assert_saga` for deterministic test coverage | [Testing →](https://lbliii.github.io/milo-cli/docs/usage/testing/) |
-| **Pipeline** | Declarative multi-phase workflows with dependency graphs, retry policies, and output capture | [Pipeline →](https://lbliii.github.io/milo-cli/docs/usage/pipeline/) |
-| **Help Rendering** | `HelpRenderer` — drop-in `argparse.HelpFormatter` using Kida templates | [Help →](https://lbliii.github.io/milo-cli/docs/usage/help/) |
-| **Context** | Execution context with verbosity, output format, global options, and `run_app()` bridge | [Context →](https://lbliii.github.io/milo-cli/docs/usage/context/) |
-| **Configuration** | `Config` with validation, init scaffolding, and profile support | [Config →](https://lbliii.github.io/milo-cli/docs/usage/config/) |
-| **Shell Completions** | Generate bash/zsh/fish completions from CLI definitions | [CLI →](https://lbliii.github.io/milo-cli/docs/usage/cli/) |
-| **Doctor Diagnostics** | `run_doctor()` validates environment, dependencies, and config health | [CLI →](https://lbliii.github.io/milo-cli/docs/usage/cli/) |
+| **MCP Server** | Every CLI doubles as an MCP server — AI agents discover and call commands via JSON-RPC | [MCP →](https://lbliii.github.io/milo-cli/docs/build-clis/mcp/) |
+| **MCP Gateway** | Single gateway aggregates all registered Milo CLIs for unified AI agent access | [MCP →](https://lbliii.github.io/milo-cli/docs/build-clis/mcp/) |
+| **Tool Annotations** | Declare `readOnlyHint`, `destructiveHint`, `idempotentHint` per MCP spec | [MCP →](https://lbliii.github.io/milo-cli/docs/build-clis/mcp/) |
+| **Streaming Progress** | Commands yield `Progress` objects; MCP clients receive real-time notifications | [MCP →](https://lbliii.github.io/milo-cli/docs/build-clis/mcp/) |
+| **Schema Constraints** | `Annotated[str, MinLen(1), MaxLen(100)]` generates rich JSON Schema | [CLI →](https://lbliii.github.io/milo-cli/docs/build-clis/commands/) |
+| **llms.txt** | Generate AI-readable discovery documents from CLI command definitions | [llms.txt →](https://lbliii.github.io/milo-cli/docs/build-clis/llms/) |
+| **Middleware** | Intercept MCP calls and CLI commands for logging, auth, and transformation | [CLI →](https://lbliii.github.io/milo-cli/docs/build-clis/commands/) |
+| **Observability** | Built-in request logging with latency stats (`milo://stats` resource) | [MCP →](https://lbliii.github.io/milo-cli/docs/build-clis/mcp/) |
+| **State Management** | Redux-style `Store` with dispatch, listeners, middleware, and saga scheduling | [State →](https://lbliii.github.io/milo-cli/docs/build-apps/state/) |
+| **Commands** | Lightweight `Cmd` thunks, `Batch`, `Sequence`, `TickCmd` for one-shot effects | [Commands →](https://lbliii.github.io/milo-cli/docs/build-apps/commands-effects/) |
+| **Sagas** | Generator-based side effects: `Call`, `Put`, `Select`, `Fork`, `Delay`, `Retry`, `Race`, `All`, `Take`, and more | [Sagas →](https://lbliii.github.io/milo-cli/docs/build-apps/sagas/) |
+| **ViewState** | Declarative terminal state (`cursor_visible`, `alt_screen`, `window_title`, `mouse_mode`) | [Commands →](https://lbliii.github.io/milo-cli/docs/build-apps/commands-effects/) |
+| **Flows** | Multi-screen state machines with `>>` operator and custom transitions | [Flows →](https://lbliii.github.io/milo-cli/docs/build-apps/flows/) |
+| **Forms** | Text, select, confirm, password fields with validation and TTY fallback | [Forms →](https://lbliii.github.io/milo-cli/docs/build-apps/forms/) |
+| **Input Handling** | Cross-platform key reader with VT100/xterm escape sequence support (arrows, F-keys, modifiers) | [Input →](https://lbliii.github.io/milo-cli/docs/build-apps/input/) |
+| **Templates** | Kida-powered terminal rendering with built-in form, field, help, and progress templates | [Templates →](https://lbliii.github.io/milo-cli/docs/build-apps/templates/) |
+| **Dev Server** | `milo dev` with filesystem polling and `@@HOT_RELOAD` dispatch | [Dev →](https://lbliii.github.io/milo-cli/docs/build-apps/dev/) |
+| **Session Recording** | JSONL action log with state hashes for debugging and regression testing | [Testing →](https://lbliii.github.io/milo-cli/docs/quality/testing/) |
+| **Snapshot Testing** | `assert_renders`, `assert_state`, `assert_saga` for deterministic test coverage | [Testing →](https://lbliii.github.io/milo-cli/docs/quality/testing/) |
+| **Pipeline** | Declarative multi-phase workflows with dependency graphs, retry policies, and output capture | [Pipeline →](https://lbliii.github.io/milo-cli/docs/quality/pipeline/) |
+| **Help Rendering** | `HelpRenderer` — drop-in `argparse.HelpFormatter` using Kida templates | [Help →](https://lbliii.github.io/milo-cli/docs/build-clis/help/) |
+| **Context** | Execution context with verbosity, output format, global options, and `run_app()` bridge | [Context →](https://lbliii.github.io/milo-cli/docs/build-clis/context/) |
+| **Configuration** | `Config` with validation, init scaffolding, and profile support | [Config →](https://lbliii.github.io/milo-cli/docs/about/concepts/configuration/) |
+| **Shell Completions** | Generate bash/zsh/fish completions from CLI definitions | [CLI →](https://lbliii.github.io/milo-cli/docs/build-clis/commands/) |
+| **Doctor Diagnostics** | `run_doctor()` validates environment, dependencies, and config health | [CLI →](https://lbliii.github.io/milo-cli/docs/build-clis/commands/) |
+
+---
+
+## Examples Index
+
+Pick the example closest to your use case, copy its `app.py`, and adapt. See [examples/README.md](examples/README.md) for run commands, copy paths, and tested starting points.
+
+**CLIs (typed function → CLI + MCP + llms.txt)**
+
+| What you want to build | Example | Key APIs |
+|---|---|---|
+| The simplest possible CLI | [examples/greet](examples/greet) | `CLI`, `@cli.command` |
+| Dual-mode CLI ↔ MCP server (flagship) | [examples/deploy](examples/deploy) | `Annotated`, `MinLen`, `Context`, `Progress`, `--mcp` |
+| Context injection, logging, progress, confirms | [examples/ctxdemo](examples/ctxdemo) | `Context`, `ctx.info`, `ctx.progress`, `ctx.confirm` |
+| Nested command groups (`app repo list`) | [examples/groups](examples/groups) | `cli.group()`, `walk_commands` |
+| Fast startup via deferred imports | [examples/lazyapp](examples/lazyapp) | `cli.lazy_command()` |
+| Production CLI with hooks, completions, doctor | [examples/devtool](examples/devtool) | `run_doctor`, `before_run`/`after_run`, did-you-mean, completions |
+| AI-native CLI surfacing tools + resources | [examples/taskman](examples/taskman) | `@command`, `@resource`, `--format`, `--llms-txt`, `--mcp` |
+| Advanced terminal reports and diagnostics | [examples/outputgallery](examples/outputgallery) | `Context.render`, Kida templates, character maps, JSON output |
+
+**Configuration, plugins, pipelines**
+
+| What you want to build | Example | Key APIs |
+|---|---|---|
+| TOML config with profiles + overlays | [examples/configapp](examples/configapp) | `Config`, `ConfigSpec`, `Config.load`, `Config.validate` |
+| Plugin system with hooks + listeners | [examples/pluggable](examples/pluggable) | `HookRegistry`, `define`, `on`, `invoke` |
+| Multi-phase pipeline with deps + retries | [examples/buildpipe](examples/buildpipe) | `Pipeline`, `Phase`, `PhasePolicy`, `>>` |
+
+**Interactive TUIs (`App` + reducer)**
+
+| What you want to build | Example | Key APIs |
+|---|---|---|
+| The simplest TUI | [examples/counter](examples/counter) | `App.from_dir`, reducer combinators |
+| Modal input with derived filtering | [examples/todo](examples/todo) | tuple state, `quit_on`, derived views |
+| Tick-driven animation | [examples/stopwatch](examples/stopwatch) | `tick_rate`, `@@TICK`, `quit_on` |
+| Scrollable viewport with saga I/O | [examples/filepicker](examples/filepicker) | viewport, sagas, frozen tuples |
+| Multi-screen flow with forms | [examples/wizard](examples/wizard) | `Flow`, `FlowScreen`, `make_form_reducer`, `FieldSpec` |
+
+**Async work (sagas + Cmd pattern)**
+
+| What you want to build | Example | Key APIs |
+|---|---|---|
+| Sagas for async side effects | [examples/fetcher](examples/fetcher) | `Call`, `Put`, `Select`, `Retry` |
+| Parallel concurrent work | [examples/downloader](examples/downloader) | `Fork`, `Call`, `Delay`, `Timeout` |
+| Bubbletea-style Cmd thunks | [examples/spinner](examples/spinner) | `Cmd`, `Batch`, `TickCmd`, `ViewState` |
+| Live rendering outside an App | [examples/liverender](examples/liverender) | `milo.live.LiveRenderer`, `Spinner`, `terminal_env` |
+
+> Don't see your use case? Run `milo new <name>` to scaffold a fresh CLI with tests, then `milo verify app.py` to confirm it works.
 
 ---
 
@@ -428,11 +480,12 @@ App.run()
 
 | Section | Description |
 |---------|-------------|
+| [About](https://lbliii.github.io/milo-cli/docs/about/) | Philosophy, architecture, concepts, and lifecycle |
 | [Get Started](https://lbliii.github.io/milo-cli/docs/get-started/) | Installation and quickstart |
-| [MCP & AI](https://lbliii.github.io/milo-cli/docs/usage/mcp/) | MCP server, gateway, annotations, streaming, and llms.txt |
-| [Usage](https://lbliii.github.io/milo-cli/docs/usage/) | State, sagas, flows, forms, templates |
-| [Testing](https://lbliii.github.io/milo-cli/docs/usage/testing/) | Snapshots, recording, replay |
-| [Reference](https://lbliii.github.io/milo-cli/docs/reference/) | Complete API documentation |
+| [Build CLIs](https://lbliii.github.io/milo-cli/docs/build-clis/) | Commands, groups, MCP, llms.txt, context, output, and help |
+| [Build Apps](https://lbliii.github.io/milo-cli/docs/build-apps/) | State, reducers, templates, input, forms, flows, sagas, and live rendering |
+| [Quality](https://lbliii.github.io/milo-cli/docs/quality/) | Testing, verification, debugging, and pipelines |
+| [Reference](https://lbliii.github.io/milo-cli/docs/reference/) | Schema, dispatch, error codes, actions, and types |
 
 ---
 

{milo_cli-0.2.2 → milo_cli-0.3.0}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "milo-cli"
-version = "0.2.2"
+version = "0.3.0"
 description = "Template-driven CLI applications for free-threaded Python"
 readme = "README.md"
 requires-python = ">=3.14"
 license = "MIT"
-dependencies = ["kida-templates>=0.6.0"]
+dependencies = ["kida-templates>=0.7.0,<0.8.0"]
 keywords = ["cli", "terminal", "forms", "free-threading", "template", "elm"]
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -25,7 +25,7 @@ classifiers = [
 milo = "milo.cli:main"
 
 [project.optional-dependencies]
-docs = ["bengal>=0.2.6"]
+docs = ["bengal>=0.3.2"]
 yaml = ["pyyaml>=6.0"]
 watch = ["watchfiles>=1.0"]
 
@@ -40,7 +40,13 @@ Issues = "https://github.com/lbliii/milo-cli/issues"
 where = ["src"]
 
 [tool.setuptools.package-data]
-milo = ["templates/*.kida", "templates/components/*.kida", "py.typed"]
+milo = [
+    "templates/*.kida",
+    "templates/components/*.kida",
+    "_scaffold/default/*",
+    "_scaffold/default/**/*",
+    "py.typed",
+]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
@@ -124,6 +130,8 @@ ignore = [
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
 "tests/**/*.py" = ["S101", "S108", "S110", "S604", "SIM117", "N806", "ARG", "T201"]
+"examples/**/*.py" = ["S101", "S108", "S110", "S604", "SIM117", "N806", "ARG", "T201", "E402"]
+"src/milo/_scaffold/default/**/*.py" = ["S101", "I001", "F401", "ARG", "T201", "E402"]
 "src/milo/_child.py" = ["S101"]          # asserts for type narrowing on subprocess pipes
 "src/milo/testing/*.py" = ["S101", "ARG"] # test helpers use assert and may have unused args
 "src/milo/version_check.py" = ["S110", "S310"] # best-effort cache reads + known PyPI URL
@@ -188,5 +196,5 @@ dev = [
     "towncrier>=24.0",
 ]
 docs = [
-    "bengal>=0.2.6",
+    "bengal>=0.3.2",
 ]

{milo_cli-0.2.2 → milo_cli-0.3.0}/src/milo/__init__.py

@@ -68,6 +68,7 @@ def __getattr__(name: str):
         # Form
         "form": "form",
         "form_reducer": "form",
+        "form_schema": "form",
         "make_form_reducer": "form",
         # Help
         "HelpRenderer": "help",
@@ -160,7 +161,7 @@ def _Py_mod_gil() -> int:  # noqa: N802
     return 0
 
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"
 __all__ = [
     "BUILTIN_ACTIONS",
     "CLI",
@@ -256,6 +257,7 @@ __all__ = [
     "compact_cmds",
     "form",
     "form_reducer",
+    "form_schema",
     "format_doctor_report",
     "format_error",
     "format_output",

milo_cli-0.3.0/src/milo/_cells.py

@@ -0,0 +1,166 @@
+"""Terminal display-cell width helpers.
+
+Python string length counts code points, but terminals lay text out in display
+cells. Box drawing, CJK characters, combining marks, and ANSI escapes all make
+``len(text)`` the wrong primitive for fixed-width terminal UI.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+_ANSI_RE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]")
+
+
+def strip_ansi(value: object) -> str:
+    """Return *value* as text with ANSI SGR/control sequences removed."""
+    return _ANSI_RE.sub("", str(value))
+
+
+def cell_width(value: object) -> int:
+    """Return the terminal display-cell width of *value*.
+
+    This intentionally implements the common wcwidth behavior we need without
+    adding a runtime dependency: combining/control characters are zero-width,
+    fullwidth/wide East Asian characters are two cells, and ambiguous-width
+    symbols are treated as one cell for Western terminal defaults.
+    """
+    width = 0
+    for ch in strip_ansi(value):
+        category = unicodedata.category(ch)
+        if category.startswith("C") or unicodedata.combining(ch):
+            continue
+        width += 2 if unicodedata.east_asian_width(ch) in {"F", "W"} else 1
+    return width
+
+
+def cell_ljust(value: object, width: int, fill: str = " ") -> str:
+    """Left-justify *value* to display-cell *width*."""
+    text = str(value)
+    return text + fill * max(0, width - cell_width(text))
+
+
+def cell_rjust(value: object, width: int, fill: str = " ") -> str:
+    """Right-justify *value* to display-cell *width*."""
+    text = str(value)
+    return fill * max(0, width - cell_width(text)) + text
+
+
+def cell_truncate(value: object, width: int, marker: str = "…") -> str:
+    """Truncate *value* to display-cell *width*, preserving ANSI-free text."""
+    text = strip_ansi(value)
+    if cell_width(text) <= width:
+        return text
+    if width <= 0:
+        return ""
+    marker_width = cell_width(marker)
+    if width <= marker_width:
+        return marker[:width]
+
+    budget = width - marker_width
+    out: list[str] = []
+    used = 0
+    for ch in text:
+        ch_width = cell_width(ch)
+        if used + ch_width > budget:
+            break
+        out.append(ch)
+        used += ch_width
+    return "".join(out) + marker
+
+
+def cell_fit(value: object, width: int, fill: str = " ", marker: str = "…") -> str:
+    """Truncate then left-pad *value* so it occupies exactly *width* cells."""
+    return cell_ljust(cell_truncate(value, width, marker=marker), width, fill=fill)
+
+
+def cell_fill(width: int, fill: str = " ") -> str:
+    """Return *fill* repeated/truncated to exactly *width* display cells."""
+    if width <= 0:
+        return ""
+    fill_width = cell_width(fill)
+    if fill_width <= 0:
+        return " " * width
+    repeated = str(fill) * ((width // fill_width) + 1)
+    return cell_truncate(repeated, width, marker="")
+
+
+def _rule_tail(width: int, fill: str = "─", tail: str = "╌┄") -> str:
+    """Return a fixed-width rule that fades instead of ending abruptly."""
+    tail_width = cell_width(tail)
+    if width > tail_width + 8:
+        return cell_fill(width - tail_width, fill) + tail
+    return cell_fill(width, fill)
+
+
+def rule_line(
+    value: object = "",
+    width: int = 78,
+    left: str = "╭",
+    right: str = "╮",
+    fill: str = "─",
+    tail: str = "",
+) -> str:
+    """Return a display-cell exact horizontal rule."""
+    label = str(value)
+    prefix = f"{left}─ {label} " if label else left
+    suffix_width = cell_width(right)
+    body_width = width - suffix_width
+    prefix_width = cell_width(prefix)
+    if body_width <= 0:
+        return cell_truncate(right, width, marker="")
+    if prefix_width > body_width:
+        return cell_fit(cell_truncate(prefix, body_width, marker="…"), body_width) + right
+    if tail:
+        return prefix + _rule_tail(body_width - prefix_width, fill=fill, tail=tail) + right
+    return prefix + cell_fill(body_width - prefix_width, fill) + right
+
+
+def divider_line(value: object = "", width: int = 78) -> str:
+    """Return a display-cell exact closed-box divider."""
+    return rule_line(value, width=width, left="├", right="┤")
+
+
+def bottom_rule(value: object = "", width: int = 78) -> str:
+    """Return a display-cell exact closed-box bottom rule."""
+    return rule_line(value, width=width, left="╰", right="╯")
+
+
+def frame_line(value: object = "", width: int = 78, left: str = "│", right: str = "│") -> str:
+    """Return a display-cell exact framed content row."""
+    content_width = width - cell_width(left) - cell_width(right) - 2
+    if content_width <= 0:
+        return cell_truncate(left + right, width, marker="")
+    return f"{left} {cell_fit(value, content_width)} {right}"
+
+
+def rail_line(value: object = "", width: int = 78, rail: str = "│") -> str:
+    """Return a display-cell exact open-card row with one left rail."""
+    content_width = width - cell_width(rail) - 1
+    if content_width <= 0:
+        return cell_truncate(rail, width, marker="")
+    return f"{rail} {cell_fit(value, content_width)}"
+
+
+def open_rule(value: object = "", width: int = 78, corner: str = "╭") -> str:
+    """Return a cell-width exact open-card rule with a fading right edge."""
+    return rule_line(value, width=width, left=corner, right="", tail="╌┄")
+
+
+def open_rule_divider(value: object = "", width: int = 78) -> str:
+    """Return a cell-width exact open-card section divider."""
+    return open_rule(value, width=width, corner="├")
+
+
+def open_rule_end(value: object = "", width: int = 78) -> str:
+    """Return a cell-width exact open-card bottom rule."""
+    return open_rule(value, width=width, corner="╰")
+
+
+def cell_meter(value: int, total: int, width: int = 10, filled: str = "█", empty: str = "░") -> str:
+    """Return a display-cell exact meter."""
+    if width <= 0:
+        return ""
+    fill_cells = 0 if total <= 0 else max(0, min(width, round((value / total) * width)))
+    return cell_fill(fill_cells, filled) + cell_fill(width - fill_cells, empty)