padrone 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # padrone
 
+## 1.5.0
+
+### Minor Changes
+
+- [`ef5e829`](https://github.com/KurtGokhan/padrone/commit/ef5e82931c06bbce70b6cdf3e34c179a48d04c66) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add `asyncStream` for streaming stdin as `AsyncIterable`. New `padrone/zod` entrypoint exports `zodAsyncStream` and `jsonCodec` for typed streams with per-item validation. Extract shared `JSON_SCHEMA_OPTS` constant across all `jsonSchema.input()` calls.
+
+- [`bbb05d9`](https://github.com/KurtGokhan/padrone/commit/bbb05d9dcf4b360d7f5ae85bdd4fa6e45b68b64d) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add `examples` configuration to options and commands for command-line usage examples.
+
+- [`7ff2738`](https://github.com/KurtGokhan/padrone/commit/7ff2738c146c419f4f03315ec8182af5be31d1b0) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Collapse global commands in help output to a single summary line by default. Add `--all` flag to show full global commands section. Bare `--detail` flag now defaults to `full`. Rename "Built-in" section to "Global".
+
+- [`369ebba`](https://github.com/KurtGokhan/padrone/commit/369ebbab4dc14c1d8acfd2af01a9322f5d964e23) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add `group` configuration to options and commands for organized help output.
+
+  Options can be grouped via `fields: { myField: { group: 'Group Name' } }` in argument metadata. Commands can be grouped via `configure({ group: 'Group Name' })`. Grouped items are rendered under labeled `${group}:` sections in help output, while ungrouped items remain under the default `Options:` / `Commands:` headers.
+
+- [`3d7b282`](https://github.com/KurtGokhan/padrone/commit/3d7b28202890925e05357c9796218349b4a8410e) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add per-field validation during interactive prompts.
+
+  When a user provides an invalid value for an interactive field, the prompt now immediately validates it against the schema and re-prompts with a warning message instead of deferring all errors until after all prompts complete. This applies to both required and optional interactive fields.
+
+- [`1843f1f`](https://github.com/KurtGokhan/padrone/commit/1843f1f3a00714d11570c245361ab73c4049aa91) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Lazily initialize commands defined with callbacks. Builder functions passed to `.command()` are now deferred until the command is routed to, avoiding upfront construction of unused commands. Features that need the full command tree (help, MCP, serve, docs, completion, REPL) resolve all commands eagerly. Added `getCommand()` and `isPadroneProgram()` helpers to replace direct `commandSymbol` usage.
+
+- [`45ba002`](https://github.com/KurtGokhan/padrone/commit/45ba002db474e34808b64b15ebce59b289f9115b) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add built-in Model Context Protocol (MCP) server. Expose CLI commands as AI tools via `mcp` command or `.mcp()` method. Supports Streamable HTTP and stdio transports per the 2025-11-25 MCP spec.
+
+- [`ab53491`](https://github.com/KurtGokhan/padrone/commit/ab534915e3bcb5cd1c3f563f4fde740d1b91fa50) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - **BREAKING:** `eval()`, `cli()`, and `run()` no longer throw errors. Instead, they return a discriminated union with an `error` field:
+
+  - Success: `{ command, args, argsResult, result, drain() }`
+  - Error: `{ error, command?, args?, argsResult?, drain() }`
+
+  Added `drain()` method to all command results. It flattens the result into a single `Promise<{ value } | { error }>` that never throws — resolving Promises, collecting iterables into arrays, and catching errors:
+
+  ```ts
+  const { value, error } = await program.cli().drain();
+  ```
+
+  New exported types: `PadroneDrainResult<T>`, `Drained<T>`.
+
+- [`dffc5cd`](https://github.com/KurtGokhan/padrone/commit/dffc5cd36250f94cc82edae850aa34ae9916d43a) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add progress indicator system for commands with auto-managed spinners and manual control.
+
+  **Auto-managed progress** via `.progress()` builder method:
+
+  - `true` or `string` for simple messages, or a full config object with per-state messages
+  - Starts before validation, auto-succeeds/fails after execution
+  - Validation-phase message transitions to execution-phase message
+  - `spinner` option: preset name (`dots`, `line`, `arc`, `bounce`), custom `{ frames, interval }`, or `false` to disable animation
+  - `success`/`error` fields accept static strings, `null` to suppress, callbacks `(result) => string | null`, or `{ message, indicator }` objects for per-call icon customization
+
+  **Manual progress** via `ctx.progress` in action handlers:
+
+  - Works even without `.progress()` config — lazily creates a real indicator on first use
+  - Auto-stopped when execution finishes (no leaked spinners)
+  - No-op when the runtime has no progress factory
+
+  **Built-in terminal spinner** (`createTerminalSpinner`):
+
+  - ANSI-based spinner with pause/resume for clean output interleaving
+  - Customizable success/error indicator icons via `PadroneProgressOptions`
+  - Empty string indicators hide the icon prefix entirely
+  - Graceful fallback in non-TTY/CI environments
+
+  **New types**: `PadroneProgressIndicator`, `PadroneProgressConfig`, `PadroneProgressMessage`, `PadroneProgressOptions`, `PadroneSpinnerConfig`, `PadroneSpinnerPreset`
+
+- [`6851b48`](https://github.com/KurtGokhan/padrone/commit/6851b4878ab0fc8d48f40e93c2f8924236a40165) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add REST server (`program.serve()`) and `mutation` command config.
+
+  - New `serve()` program method: exposes commands as HTTP endpoints with automatic OpenAPI docs (Scalar).
+  - New `serve` built-in CLI command: `myapp serve --port 3000`.
+  - Built-in endpoints: `/_health`, `/_help`, `/_schema`, `/_docs` (Scalar), `/_openapi`.
+  - New `mutation` option in `.configure()`: mutation commands are POST-only in serve, set `destructiveHint` in MCP, and default `needsApproval` to true in `tool()`.
+  - MCP: rename `endpoint` to `basePath` for consistency with serve.
+  - Shared utilities extracted from MCP (`collectEndpoints`, `buildInputSchema`, `serializeArgsToFlags`).
+
+### Patch Changes
+
+- [`7e8f14d`](https://github.com/KurtGokhan/padrone/commit/7e8f14ddb628620f94a7c9f2e88f9417577f2b04) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Expand boolean auto-coercion to accept `yes`/`no`/`on`/`off` (case-insensitive).
+
+- [`a1c7072`](https://github.com/KurtGokhan/padrone/commit/a1c70724829f8cd4fb1632098f352498c87cbf2e) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Improve help output formatting: options now display flags first, then names, type, and description in aligned columns. Metadata (deprecated, default, choices, examples, env, config) is shown on separate indented lines.
+
+- [`befc82e`](https://github.com/KurtGokhan/padrone/commit/befc82e39b4a1663c3ace74305dd48f9aded1a09) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add `.catch()` and `.finally()` methods to thenable sync results from `eval()`, `parse()`, and `cli()`
+
+- [`81f3bbc`](https://github.com/KurtGokhan/padrone/commit/81f3bbce54940953ff32d76c620eabd6cec7322f) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Use `node:child_process` in wrap handler instead of `Bun.spawn` for Node.js compatibility.
+
 ## 1.4.0
 
 ### Minor Changes

package/README.md

@@ -2,10 +2,8 @@
   <img src="media/padrone.svg" alt="Padrone Logo" width="200" height="200" />
 </p>
 
-<!-- <h1 align="center">Padrone</h1> -->
-
 <p align="center">
-  <strong>Create type-safe, interactive CLI apps with Zod schemas</strong>
+  <strong>Type-safe CLI framework powered by Zod schemas</strong>
 </p>
 
 <p align="center">
@@ -16,33 +14,26 @@
 
 ---
 
-## ✨ Features
+Define your CLI with Zod schemas. Get type safety, validation, help generation, interactive prompts, shell completions, AI tool integration, and more — all from a single source of truth.
 
-- 🔒 **Type-safe** - Full TypeScript support with Zod schema validation
-- 🎯 **Fluent API** - Chain commands and arguments with a clean builder pattern
-- 🤖 **AI-Ready** - First-class support for Vercel AI SDK tool integration
-- 📚 **Auto Help** - Automatic help generation from your schema definitions
-- 🧩 **Nested Commands** - Support for deeply nested subcommands
-- 🔄 **Standard Schema** - Built on [Standard Schema](https://github.com/standard-schema/standard-schema) for maximum compatibility
-- 🚀 **Zero Config** - Works out of the box with sensible defaults
+Built on [Standard Schema](https://github.com/standard-schema/standard-schema), so it also works with Valibot, ArkType, and others.
 
-## 📦 Installation
+## Install
 
 ```bash
-# Using npm
 npm install padrone zod
+```
 
-# Using bun
-bun add padrone zod
+## Scaffold a New Project
 
-# Using pnpm
-pnpm add padrone zod
+The fastest way to get started is with `padrone init`:
 
-# Using yarn
-yarn add padrone zod
+```bash
+npx padrone init my-cli
+cd my-cli && bun i && bun dev
 ```
 
-## 🚀 Quick Start
+## Quick Start
 
 ```typescript
 import { createPadrone } from 'padrone';
@@ -54,320 +45,150 @@ const program = createPadrone('myapp')
       .arguments(
         z.object({
           names: z.array(z.string()).describe('Names to greet'),
-          prefix: z
-            .string()
-            .optional()
-            .describe('Prefix to use in greeting')
-            .meta({ alias: 'p' }),
+          prefix: z.string().optional().describe('Prefix').meta({ flags: 'p' }),
         }),
         { positional: ['...names'] },
       )
       .action((args) => {
-        const prefix = args?.prefix ? `${args.prefix} ` : '';
-        args.names.forEach((name) => {
-          console.log(`Hello, ${prefix}${name}!`);
-        });
+        for (const name of args.names) {
+          console.log(`Hello, ${args.prefix ?? ''} ${name}!`);
+        }
       }),
   );
 
-// Run from CLI arguments
 program.cli();
 ```
 
-### Running your CLI
-
 ```bash
-# Run with arguments
-myapp greet John Jane --prefix Mr.
-
-# Or with alias
 myapp greet John Jane -p Mr.
+# Hello, Mr. John!
+# Hello, Mr. Jane!
 ```
 
-Output:
-```
-Hello, Mr. John!
-Hello, Mr. Jane!
-```
-
-## 📖 Usage Examples
-
-### Programmatic Execution
+## What It Does
 
 ```typescript
-// Run a command directly with typed arguments
-program.run('greet', { names: ['John', 'Jane'], prefix: 'Dr.' });
+// Multiple ways to run commands
+program.cli();                                              // from process.argv
+program.eval('greet John --prefix Mr.');                    // from a string
+program.run('greet', { names: ['John'], prefix: 'Mr.' });  // typed args
+program.api().greet({ names: ['John'], prefix: 'Mr.' });   // as a function
 
-// Parse CLI input without executing
-const parsed = program.parse('greet John --prefix Mr.');
-console.log(parsed.args); // { names: ['John'], prefix: 'Mr.' }
-```
-
-### API Mode
+// Parse without executing
+const { args } = program.parse('greet John --prefix Mr.');
 
-Generate a typed API from your CLI program:
+// Interactive REPL
+for await (const result of program.repl()) { /* ... */ }
 
-```typescript
-const api = program.api();
+// AI tool for Vercel AI SDK
+const tool = program.tool();
 
-// Call commands as functions with full type safety
-api.greet({ names: ['Alice', 'Bob'], prefix: 'Dr.' });
-```
+// MCP server for AI assistants (Claude, Cursor, etc.) [experimental]
+await program.mcp();  // or: myapp mcp
 
-### Nested Commands
+// REST server with OpenAPI docs [experimental]
+await program.serve();  // or: myapp serve
 
-```typescript
-const program = createPadrone('weather')
-  .command('forecast', (c) =>
-    c
-      .arguments(
-        z.object({
-          city: z.string().describe('City name'),
-          days: z.number().optional().default(3).describe('Number of days'),
-        }),
-        { positional: ['city'] },
-      )
-      .action((args) => {
-        console.log(`Forecast for ${args.city}: ${args.days} days`);
-      })
-      .command('extended', (c) =>
-        c
-          .arguments(
-            z.object({
-              city: z.string().describe('City name'),
-            }),
-            { positional: ['city'] },
-          )
-          .action((args) => {
-            console.log(`Extended forecast for ${args.city}`);
-          }),
-      ),
-  );
+// Shell completions
+const script = program.completion('zsh');
 
-// Run nested command
-program.eval('forecast extended London');
+// Help in multiple formats
+program.help('greet');                        // text
+program.help('greet', { format: 'json' });   // json, markdown, html, ansi
 ```
 
-### Option Aliases and Metadata
+## Features at a Glance
 
-```typescript
-const program = createPadrone('app')
-  .command('serve', (c) =>
-    c
-      .arguments(
-        z.object({
-          port: z
-            .number()
-            .default(3000)
-            .describe('Port to listen on')
-            .meta({ alias: 'p', examples: ['3000', '8080'] }),
-          host: z
-            .string()
-            .default('localhost')
-            .describe('Host to bind to')
-            .meta({ alias: 'h' }),
-          verbose: z
-            .boolean()
-            .optional()
-            .describe('Enable verbose logging')
-            .meta({ alias: 'v', deprecated: 'Use --debug instead' }),
-        }),
-      )
-      .action((args) => {
-        console.log(`Server running at ${args.host}:${args.port}`);
-      }),
-  );
-```
+**Arguments** — positional args, variadic args, short flags (`-v`), long aliases (`--dry-run`), auto kebab-case aliases, negatable booleans (`--no-verbose`).
 
-### Environment Variables and Config Files
+**Env & Config** — load from environment variables with `.env()` and config files with `.configFile()`. Precedence: CLI > stdin > env > config > defaults.
 
-Padrone supports loading arguments from environment variables and config files using dedicated schema methods:
+**Interactive prompts** — auto-prompt for missing fields. Booleans become confirm, enums become select, arrays become multi-select.
 
-```typescript
-const program = createPadrone('app')
-  .command('serve', (c) =>
-    c
-      .arguments(
-        z.object({
-          port: z.number().default(3000).describe('Port to listen on'),
-          apiKey: z.string().describe('API key for authentication'),
-        }),
-      )
-      // Map environment variables to arguments
-      .env(
-        z
-          .object({
-            APP_PORT: z.coerce.number().optional(),
-            API_KEY: z.string().optional(),
-          })
-          .transform((env) => ({
-            port: env.APP_PORT,
-            apiKey: env.API_KEY,
-          })),
-      )
-      // Load config from JSON file with matching schema
-      .configFile(
-        'app.config.json',
-        z.object({
-          port: z.number().optional(),
-          apiKey: z.string().optional(),
-        }),
-      )
-      .action((args) => {
-        console.log(`Server running on port ${args.port}`);
-      }),
-  );
-```
+**Progress indicators** — auto-managed spinners with dynamic messages. `.progress({ progress: 'Deploying...', success: (r) => \`v${r.version}\` })`.
 
-**Precedence order** (highest to lowest): CLI args > environment variables > config file
+**Plugins** — middleware hooks for 6 phases (start, parse, validate, execute, error, shutdown). Onion model with `next()`.
 
-### Async Validation
+**Composition** — mount programs as subcommands with `.mount()`, override commands with merge semantics.
 
-If your schema uses async refinements (e.g. `z.check(async ...)`), mark the command as async so that `parse()` and `cli()` return Promises:
+**Wrapping** *(experimental)* — wrap external CLI tools with `.wrap({ command: 'git', args: ['commit'] })`.
 
-```typescript
-import { asyncSchema, createPadrone } from 'padrone';
+## API
 
-const program = createPadrone('app')
-  .command('create', (c) =>
-    c
-      // Option 1: brand the schema with asyncSchema()
-      .arguments(asyncSchema(z.object({ name: z.string() }).check(async (ctx) => { /* ... */ })))
-      // Option 2: call .async() on the builder
-      .async()
-      .action((args) => args.name),
-  );
-
-// parse() and cli() now return Promises
-const result = await program.parse('create --name test');
-```
-
-## 🤖 AI SDK Integration
-
-Padrone provides first-class support for the [Vercel AI SDK](https://ai-sdk.dev/), making it easy to expose your CLI as an AI tool:
-
-```typescript
-import { streamText } from 'ai';
-import { createPadrone } from 'padrone';
-import * as z from 'zod/v4';
-
-const weatherCli = createPadrone('weather')
-  .command('current', (c) =>
-    c
-      .arguments(
-        z.object({
-          city: z.string().describe('City name'),
-        }),
-        { positional: ['city'] },
-      )
-      .action((args) => {
-        return { city: args.city, temperature: 72, condition: 'Sunny' };
-      }),
-  );
-
-// Convert your CLI to an AI tool
-const result = await streamText({
-  model: yourModel,
-  prompt: "What's the weather in London?",
-  tools: {
-    weather: weatherCli.tool(),
-  },
-});
-```
-
-## 📋 Auto-Generated Help
-
-Padrone automatically generates help text from your Zod schemas:
-
-```typescript
-console.log(program.help());
-```
-
-Example output:
-```
-Usage: myapp greet [names...] [arguments]
-
-Positionals:
-  names...    Names to greet
-
-Arguments:
-  -p, --prefix <string>   Prefix to use in greeting
-  -h, --help              Show help
-```
-
-## 🔧 API Reference
-
-### `createPadrone(name)`
+### Builder (define commands)
 
-Creates a new CLI program with the given name.
-
-### Program Methods
-
-| Method | Description |
+| Method | What it does |
+|--------|-------------|
+| `.arguments(schema, meta?)` | Define args with Zod schema, positional config, field metadata |
+| `.action(handler)` | Set handler `(args, ctx, base?) => result` |
+| `.command(name, builder)` | Add subcommand (name or `[name, ...aliases]`) |
+| `.mount(name, program)` | Mount another program as subcommand tree |
+| `.configure(config)` | Set title, description, version, etc. |
+| `.env(schema)` | Map env vars to args |
+| `.configFile(file, schema?)` | Load args from config files |
+| `.wrap(config)` | Wrap an external CLI tool *(experimental)* |
+| `.progress(config?)` | Auto-managed spinner |
+| `.use(plugin)` | Register middleware plugin |
+| `.runtime(runtime)` | Custom I/O (for non-terminal use) |
+| `.updateCheck(config?)` | Background version check |
+| `.async()` | Mark as async validation |
+
+### Program (run commands)
+
+| Method | What it does |
 |--------|-------------|
-| `.configure(config)` | Configure program properties (title, description, version) |
-| `.command(name, builder)` | Add a command to the program |
-| `.arguments(schema, meta?)` | Define arguments schema with optional positional args |
-| `.async()` | Mark command as async (for schemas with async validation) |
-| `.env(schema)` | Define schema for parsing environment variables into arguments |
-| `.configFile(file, schema?)` | Configure config file path(s) and schema |
-| `.action(handler)` | Set the command handler function |
-| `.cli(input?)` | Run as CLI (parses `process.argv` or input string) |
-| `.run(command, args?)` | Run a command programmatically |
-| `.parse(input?)` | Parse input without executing |
-| `.stringify(command?, args?)` | Convert command and arguments back to CLI string |
-| `.api()` | Generate a typed API object |
-| `.help(command?)` | Generate help text |
-| `.tool()` | Generate a Vercel AI SDK tool |
-| `.find(command)` | Find a command by name |
-
-### Arguments Meta
-
-Use the second argument of `.arguments()` to configure positional arguments and per-argument metadata:
+| `.cli(prefs?)` | Entry point — parses `process.argv`, throws on errors |
+| `.eval(input, prefs?)` | Parse + validate + execute string, returns errors softly |
+| `.run(command, args)` | Run by name with typed args (no validation) |
+| `.parse(input?)` | Parse without executing |
+| `.api()` | Generate typed function API |
+| `.repl(options?)` | Interactive REPL session |
+| `.help(command?, prefs?)` | Generate help (text, ansi, markdown, html, json) |
+| `.tool()` | Vercel AI SDK tool definition |
+| `.mcp(prefs?)` | Start MCP server (HTTP or stdio) *(experimental)* |
+| `.serve(prefs?)` | Start REST server with OpenAPI docs *(experimental)* |
+| `.completion(shell?)` | Shell completion script |
+| `.find(command)` | Look up command by path |
+| `.stringify(command?, args?)` | Convert back to CLI string |
+
+### Zod `.meta()` fields
+
+| Field | Example | Purpose |
+|-------|---------|---------|
+| `flags` | `'v'` | Single-char short flag (`-v`) |
+| `alias` | `'dry-run'` | Multi-char long alias (`--dry-run`) |
+| `examples` | `['8080']` | Example values in help |
+| `deprecated` | `'Use --debug'` | Deprecation warning |
+| `hidden` | `true` | Hide from help |
+| `group` | `'Advanced'` | Group in help output |
+
+### Arguments meta (second param of `.arguments()`)
 
 ```typescript
 .arguments(schema, {
-  positional: ['source', '...files', 'dest'],  // '...files' is variadic
-  fields: {
-    verbose: { alias: 'v' },
-    format: { deprecated: 'Use --output instead' },
-  },
+  positional: ['source', '...files', 'dest'],
+  interactive: ['name', 'template'],
+  optionalInteractive: ['typescript'],
+  fields: { verbose: { flags: 'v' } },
+  stdin: 'data',
+  autoAlias: true,  // default
 })
 ```
 
-### Zod Metadata
+## Agent Skill
 
-Use `.meta()` on Zod schemas to provide additional CLI metadata:
-
-```typescript
-z.string().meta({
-  alias: 'p',            // Short alias (-p)
-  examples: ['value'],   // Example values for help text
-  deprecated: 'message', // Mark as deprecated
-  hidden: true,          // Hide from help output
-})
-```
-
-## 🤖 AI Coding Agent Skill
-
-Install the [Padrone skill](https://agentskills.io) to give your AI coding agent (Claude Code, etc.) knowledge of the Padrone API:
+Give your AI coding agent knowledge of the Padrone API:
 
 ```bash
 npx skills add KurtGokhan/padrone
 ```
 
-## 🛠️ Requirements
+## Requirements
 
 - Node.js 18+ or Bun
 - TypeScript 5.0+ (recommended)
-- Zod 3.25+ or 4.x
+- Zod (or any Standard Schema-compatible library)
 
-## 📄 License
+## License
 
-[MIT](LICENSE) © [Gokhan Kurt](https://gkurt.com)
-
----
-
-<p align="center">
-  Made with ❤️ by <a href="https://gkurt.com">Gokhan Kurt</a>
-</p>
+[MIT](LICENSE)