padrone 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# padrone
+
+## 1.2.0
+
+### Minor Changes
+
+- 66336e5: auto-output is now enabled by default: command return values are automatically written to output in eval, cli, and repl modes. The runtime `output` function now accepts `unknown` values instead of only strings, letting runtimes handle formatting natively. Use `autoOutput: false` in preferences or `configure({ autoOutput: false })` on individual commands to opt out.
+- 02a171c: Add runtime adapter for I/O abstraction, enabling CLI framework usage outside of terminals (web UIs, chat interfaces, testing). New `.runtime()` builder method configures output, error, argv, env, format, config file loading, and file discovery. All fields are optional with Node.js/Bun defaults. Successive `.runtime()` calls merge with previous configuration.
+- 93155ef: Add `padrone/codegen` entry point with a generic code generation toolkit including CodeBuilder (fluent TypeScript source builder), template engine, schemaToCode (Standard Schema to Zod source), FileEmitter (multi-file output), built-in generators (command files, command trees, barrel files), and parsers (help text, fish completions, zsh completions, multi-source merge). Also add `padrone init` CLI command that scaffolds a new Padrone project using the codegen utilities, and reorganize CLI files into `src/cli/` subfolder.
+- 68508a7: Add command override/extension support. Re-registering a command with the same name now merges instead of duplicating: configuration is shallow-merged, the previous handler is passed as a `base` parameter to `.action()`, arguments can be overridden, and subcommands are recursively merged by name. Aliases are preserved from the original when the override doesn't specify new ones. All fully strongly typed.
+
+  Also fixes: REPL `.` command now works at any scope (including root) to execute the current command, `.help` always shows `.` and `.scope` entries, `cli()` and `repl()` return types now include all possible command results, and nested commands with default `''` subcommands route correctly.
+
+- 7e83ebb: Improve command routing, help display, and `--` separator support.
+- 583394b: Add `padrone/completion` subpath export and `padrone completions` CLI command. Shell completion generation is now lazy-loaded via dynamic import, and `setupCompletions()` writes eval snippets to shell config files with idempotent marker-based replacement. User programs get `--setup` on the built-in `completion` command (e.g. `myapp completion bash --setup`). The `.completion()` method is now async.
+- 457f1f7: Add `padrone/docs` entry point with a `generateDocs()` utility that walks the command tree and generates structured documentation in four formats: markdown (with index page, frontmatter support for VitePress/Starlight), HTML (semantic with CSS classes), man pages (groff-formatted), and JSON. Each page includes command name, description, usage syntax, options with types/defaults/choices/aliases/env vars/config keys/examples, positional arguments, and subcommands table. Also add `padrone docs` CLI command that imports a Padrone program from any entry file and generates documentation to an output directory.
+- 038d0aa: Add `padrone doctor <entry>` CLI command that lints and validates a Padrone program definition. Catches duplicate aliases, shadowed option/command names (help, version), commands without actions, schemas without descriptions, conflicting positional configs, and unused plugins.
+- 262e2e6: Add `eval()` method and separate from `cli()`. `program.eval(input)` parses, validates, and executes a command string with soft error handling (returns result with issues instead of throwing). `program.cli()` is now exclusively the process entry point that reads from `process.argv` and throws on validation errors. The REPL and AI SDK tool integration now use `eval()` internally.
+- fb86d5b: Add fuzzy matching for "Did you mean?" suggestions on unknown commands and options.
+- 020cc21: Add interactive field prompting. Commands can now declare `interactive` and `optionalInteractive` in the arguments meta to prompt users for missing field values during `cli()`. Interactive prompts are auto-detected from the schema (boolean → confirm, enum → select, array enum → multiselect). The runtime controls whether interactivity is enabled via `runtime({ interactive: true })`, with a built-in Enquirer-powered terminal prompt as the default. Custom prompt implementations can be provided for non-terminal runtimes.
+- cba6615: Add lifecycle hooks to the plugin system: `start`, `error`, and `shutdown` phases. `start` wraps the entire pipeline (before parse), `error` handles pipeline failures with the ability to suppress or transform errors, and `shutdown` always runs after completion for cleanup. All three use the same onion/middleware pattern as existing phases. Available in `eval()` and `cli()` only. Sync preservation is maintained.
+- 727c6af: Add `padrone link` and `padrone unlink` CLI commands for linking programs during development. Creates shell shims in `~/.padrone/bin/` that invoke the entry file with the detected runtime. Auto-detects entry from `package.json` bin field and runtime from lockfiles. Use `--setup` to automatically add `~/.padrone/bin` to PATH in shell config. Shell utilities (`detectShell`, `getRcFile`, `writeToRcFile`) extracted to `shell-utils.ts` for reuse.
+- fdca76f: Add `.mount(name, program)` method for composing Padrone programs together. Mounts an existing program as a subcommand, recursively re-pathing all nested commands and preserving arguments, handlers, plugins, and schemas. Supports aliases via array syntax. Mounted program's root-level `version` is dropped. Type-level paths are recursively updated for correct inference with `eval()`, `find()`, `run()`, etc.
+- 4706462: Add plugin system with middleware pattern for intercepting command execution phases. Plugins use an onion model with `next()` to wrap parse, validate, and execute phases. Registered via `.use()` on both programs and subcommand builders. Program-level plugins apply as outermost wrappers; subcommand plugins compose as inner layers. Parse phase runs root plugins only. Supports explicit ordering via `order` parameter, shared mutable `state` across phases, sync preservation, and short-circuiting.
+- 1a44f9d: Add REPL command history, tab completion, and output styling. The built-in terminal REPL now supports up/down arrow history navigation and tab completion for command names, subcommands, options, and aliases. New `repl()` preferences: `history` (initial entries), `completion` (toggle tab completion), `spacing` (separators before/after command output — supports blank lines, repeated characters, multi-line arrays, and independent before/after config), and `outputPrefix` (prefix each output line, e.g. `'│ '`). The default prompt is bold in ANSI-capable terminals.
+- a73bf6a: Add REPL mode. `program.repl()` starts an interactive Read-Eval-Print Loop that returns an `AsyncIterable<PadroneCommandResult>`, yielding a result for each successfully executed command. Errors are caught and printed without crashing the session. Built-in REPL commands (`exit`, `quit`, `clear`) are provided but yield to user-defined commands of the same name. The runtime gains a new `readLine` field for abstracting line input, with a default Node.js/Bun `readline` implementation.
+- 5437416: Add scoped/contextual REPLs, `--repl` CLI flag, and dot-prefixed built-in commands. All REPL built-ins now use dot-prefix notation (`.exit`, `.quit`, `.clear`, `.scope`, `.help`, `.history`) to avoid collisions with user commands. `.scope <subcommand>` scopes the REPL session to a command subtree, `.scope ..`/`..` goes back up, `.` executes the current scoped command. `.help` shows REPL-specific commands and keybindings. `.history` shows session command history. Default greeting displays program name and version; configurable `hint` text shown below. Double Ctrl+C to exit (first press shows hint). The prompt updates to reflect scope (e.g. `myapp/db ❯`). `options.scope` allows starting pre-scoped and is strongly typed to valid command paths. The `--repl` flag in `cli()` starts a REPL (optionally scoped to a command).
+- b021824: Removed parse options. Custom runtimes can be used for the same behavior.
+- 3ad9c6f: Add stdin piping support. Commands can declare a `stdin` field in their arguments meta to read piped input and inject it into a schema field. Supports `text` mode (read all as string) and `lines` mode (read as string array). Precedence: CLI flags > stdin > env vars > config file > schema defaults. Stdin is only read when piped (not a TTY) and the target field wasn't already provided via CLI. Runtime abstraction (`PadroneRuntime.stdin`) enables custom stdin sources for testing and non-terminal environments. Test harness gains `.stdin(data)` builder method. Help output shows `[stdin > field]` in usage line.
+- a64f576: Add `padrone/test` entry point with testing utilities. The `testCli(program)` function provides a fluent builder for setting up CLI test scenarios with mock I/O capture. Supports mocking environment variables (`.env()`), interactive prompt answers (`.prompt()`), config files (`.config()`), and REPL sessions (`.repl()`). Works with any test framework.
+- 6269637: add async validation support
+- 6d15076: Add built-in opt-in update checking via `.updateCheck()`. When enabled, the program checks the npm registry (or a custom URL) for newer versions in the background and displays a notification after command output. Checks are cached to avoid hitting the registry on every invocation. Respects CI environments, non-TTY contexts, `--no-update-check` flag, and a configurable env var to disable.
+
+### Patch Changes
+
+- 54de1b9: show built-in commands and flags (help, version, completion, --repl) in root help output
+- 6fa2ac9: improve help output formatting: show actual positional argument names in usage line, use `[options]` instead of `[arguments]` for flags, and rename flags section from "Arguments" to "Options"
+- bf6fe49: Add AI coding agent skill with API reference, examples, and installation instructions for Claude Code and other Agent Skills-compatible tools.
+
+## 1.0.0
+
+Initial stable release of Padrone - a TypeScript CLI framework with Zod schema support.
+
+### Features
+
+- Type-safe argument parsing with Zod schemas
+- Interactive prompts with validation
+- AI integration support via Vercel AI SDK
+- Standard Schema compatibility
+- Terminal UI components
+- Command builder pattern

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Gökhan Kurt
+Copyright (c) 2026 Gökhan Kurt
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -19,7 +19,7 @@
 ## ✨ Features
 
 - 🔒 **Type-safe** - Full TypeScript support with Zod schema validation
-- 🎯 **Fluent API** - Chain commands, arguments, and options with a clean builder pattern
+- 🎯 **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
@@ -51,7 +51,7 @@ import * as z from 'zod/v4';
 const program = createPadrone('myapp')
   .command('greet', (c) =>
     c
-      .options(
+      .arguments(
         z.object({
           names: z.array(z.string()).describe('Names to greet'),
           prefix: z
@@ -62,9 +62,9 @@ const program = createPadrone('myapp')
         }),
         { positional: ['...names'] },
       )
-      .action((options) => {
-        const prefix = options?.prefix ? `${options.prefix} ` : '';
-        options.names.forEach((name) => {
+      .action((args) => {
+        const prefix = args?.prefix ? `${args.prefix} ` : '';
+        args.names.forEach((name) => {
           console.log(`Hello, ${prefix}${name}!`);
         });
       }),
@@ -95,12 +95,12 @@ Hello, Mr. Jane!
 ### Programmatic Execution
 
 ```typescript
-// Run a command directly with typed options
+// Run a command directly with typed arguments
 program.run('greet', { names: ['John', 'Jane'], prefix: 'Dr.' });
 
 // Parse CLI input without executing
 const parsed = program.parse('greet John --prefix Mr.');
-console.log(parsed.options); // { names: ['John'], prefix: 'Mr.' }
+console.log(parsed.args); // { names: ['John'], prefix: 'Mr.' }
 ```
 
 ### API Mode
@@ -120,32 +120,32 @@ api.greet({ names: ['Alice', 'Bob'], prefix: 'Dr.' });
 const program = createPadrone('weather')
   .command('forecast', (c) =>
     c
-      .options(
+      .arguments(
         z.object({
           city: z.string().describe('City name'),
           days: z.number().optional().default(3).describe('Number of days'),
         }),
         { positional: ['city'] },
       )
-      .action((options) => {
-        console.log(`Forecast for ${options.city}: ${options.days} days`);
+      .action((args) => {
+        console.log(`Forecast for ${args.city}: ${args.days} days`);
       })
       .command('extended', (c) =>
         c
-          .options(
+          .arguments(
             z.object({
               city: z.string().describe('City name'),
             }),
             { positional: ['city'] },
           )
-          .action((options) => {
-            console.log(`Extended forecast for ${options.city}`);
+          .action((args) => {
+            console.log(`Extended forecast for ${args.city}`);
           }),
       ),
   );
 
 // Run nested command
-program.cli('forecast extended London');
+program.eval('forecast extended London');
 ```
 
 ### Option Aliases and Metadata
@@ -154,7 +154,7 @@ program.cli('forecast extended London');
 const program = createPadrone('app')
   .command('serve', (c) =>
     c
-      .options(
+      .arguments(
         z.object({
           port: z
             .number()
@@ -173,41 +173,75 @@ const program = createPadrone('app')
             .meta({ alias: 'v', deprecated: 'Use --debug instead' }),
         }),
       )
-      .action((options) => {
-        console.log(`Server running at ${options.host}:${options.port}`);
+      .action((args) => {
+        console.log(`Server running at ${args.host}:${args.port}`);
       }),
   );
 ```
 
 ### Environment Variables and Config Files
 
-Padrone supports binding options to environment variables and config files:
+Padrone supports loading arguments from environment variables and config files using dedicated schema methods:
 
 ```typescript
 const program = createPadrone('app')
-  .configure({
-    configFiles: ['app.config.json', '.apprc'],
-  })
   .command('serve', (c) =>
     c
-      .options(
+      .arguments(
         z.object({
           port: z.number().default(3000).describe('Port to listen on'),
           apiKey: z.string().describe('API key for authentication'),
         }),
-        {
-          options: {
-            port: { env: 'APP_PORT', configKey: 'server.port' },
-            apiKey: { env: ['API_KEY', 'APP_API_KEY'] },
-          },
-        },
       )
-      .action((options) => {
-        console.log(`Server running on port ${options.port}`);
+      // 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}`);
       }),
   );
 ```
 
+**Precedence order** (highest to lowest): CLI args > environment variables > config file
+
+### Async Validation
+
+If your schema uses async refinements (e.g. `z.check(async ...)`), mark the command as async so that `parse()` and `cli()` return Promises:
+
+```typescript
+import { asyncSchema, createPadrone } from 'padrone';
+
+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:
@@ -220,14 +254,14 @@ import * as z from 'zod/v4';
 const weatherCli = createPadrone('weather')
   .command('current', (c) =>
     c
-      .options(
+      .arguments(
         z.object({
           city: z.string().describe('City name'),
         }),
         { positional: ['city'] },
       )
-      .action((options) => {
-        return { city: options.city, temperature: 72, condition: 'Sunny' };
+      .action((args) => {
+        return { city: args.city, temperature: 72, condition: 'Sunny' };
       }),
   );
 
@@ -251,12 +285,12 @@ console.log(program.help());
 
 Example output:
 ```
-Usage: myapp greet [names...] [options]
+Usage: myapp greet [names...] [arguments]
 
-Arguments:
+Positionals:
   names...    Names to greet
 
-Options:
+Arguments:
   -p, --prefix <string>   Prefix to use in greeting
   -h, --help              Show help
 ```
@@ -271,34 +305,37 @@ Creates a new CLI program with the given name.
 
 | Method | Description |
 |--------|-------------|
-| `.configure(config)` | Configure program properties (title, description, version, configFiles) |
+| `.configure(config)` | Configure program properties (title, description, version) |
 | `.command(name, builder)` | Add a command to the program |
-| `.options(schema, meta?)` | Define options schema with optional positional args |
+| `.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, options)` | Run a command programmatically |
+| `.run(command, args?)` | Run a command programmatically |
 | `.parse(input?)` | Parse input without executing |
-| `.stringify(command?, options?)` | Convert command and options back to CLI string |
+| `.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 |
 
-### Options Meta
+### Arguments Meta
 
-Use the second argument of `.options()` to configure positional arguments and per-option metadata:
+Use the second argument of `.arguments()` to configure positional arguments and per-argument metadata:
 
 ```typescript
-.options(schema, {
+.arguments(schema, {
   positional: ['source', '...files', 'dest'],  // '...files' is variadic
-  options: {
-    verbose: { alias: 'v', env: 'VERBOSE' },
-    config: { configKey: 'settings.config' },
+  fields: {
+    verbose: { alias: 'v' },
+    format: { deprecated: 'Use --output instead' },
   },
 })
 ```
 
-### Zod Meta Options
+### Zod Metadata
 
 Use `.meta()` on Zod schemas to provide additional CLI metadata:
 
@@ -308,11 +345,17 @@ z.string().meta({
   examples: ['value'],   // Example values for help text
   deprecated: 'message', // Mark as deprecated
   hidden: true,          // Hide from help output
-  env: 'MY_VAR',         // Bind to environment variable
-  configKey: 'path.key', // Bind to config file key
 })
 ```
 
+## 🤖 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:
+
+```bash
+npx skills add KurtGokhan/padrone
+```
+
 ## 🛠️ Requirements
 
 - Node.js 18+ or Bun

package/dist/args-CKNh7Dm9.mjs

@@ -0,0 +1,175 @@
+//#region src/args.ts
+/**
+* Normalizes stdin config into its explicit form.
+*/
+function parseStdinConfig(stdin) {
+	if (typeof stdin === "string") return {
+		field: stdin,
+		as: "text"
+	};
+	return {
+		field: stdin.field,
+		as: stdin.as ?? "text"
+	};
+}
+/**
+* Parse positional configuration to extract names and variadic info.
+*/
+function parsePositionalConfig(positional) {
+	return positional.map((p) => {
+		const isVariadic = p.startsWith("...");
+		return {
+			name: isVariadic ? p.slice(3) : p,
+			variadic: isVariadic
+		};
+	});
+}
+/**
+* Extract all arg metadata from schema and meta in a single pass.
+* This consolidates aliases, env bindings, and config keys extraction.
+*/
+function extractSchemaMetadata(schema, meta) {
+	const aliases = {};
+	if (meta) for (const [key, value] of Object.entries(meta)) {
+		if (!value) continue;
+		if (value.alias) {
+			const list = typeof value.alias === "string" ? [value.alias] : value.alias;
+			for (const aliasKey of list) if (typeof aliasKey === "string" && aliasKey && aliasKey !== key) aliases[aliasKey] = key;
+		}
+	}
+	try {
+		const jsonSchema = schema["~standard"].jsonSchema.input({ target: "draft-2020-12" });
+		if (jsonSchema.type === "object" && jsonSchema.properties) for (const [propertyName, propertySchema] of Object.entries(jsonSchema.properties)) {
+			if (!propertySchema) continue;
+			const propAlias = propertySchema.alias;
+			if (propAlias) {
+				const list = typeof propAlias === "string" ? [propAlias] : propAlias;
+				if (Array.isArray(list)) {
+					for (const aliasKey of list) if (typeof aliasKey === "string" && aliasKey && aliasKey !== propertyName && !(aliasKey in aliases)) aliases[aliasKey] = propertyName;
+				}
+			}
+		}
+	} catch {}
+	return { aliases };
+}
+function preprocessAliases(data, aliases) {
+	const result = { ...data };
+	for (const [aliasKey, fullArgName] of Object.entries(aliases)) if (aliasKey in data && aliasKey !== fullArgName) {
+		const aliasValue = data[aliasKey];
+		if (!(fullArgName in result)) result[fullArgName] = aliasValue;
+		delete result[aliasKey];
+	}
+	return result;
+}
+/**
+* Apply values directly to arguments.
+* CLI values take precedence over the provided values.
+*/
+function applyValues(data, values) {
+	const result = { ...data };
+	for (const [key, value] of Object.entries(values)) {
+		if (key in result && result[key] !== void 0) continue;
+		if (value !== void 0) result[key] = value;
+	}
+	return result;
+}
+/**
+* Combined preprocessing of arguments with all features.
+* Precedence order (highest to lowest): CLI args > stdin > env vars > config file
+*/
+function preprocessArgs(data, ctx) {
+	let result = { ...data };
+	if (ctx.aliases && Object.keys(ctx.aliases).length > 0) result = preprocessAliases(result, ctx.aliases);
+	if (ctx.stdinData) result = applyValues(result, ctx.stdinData);
+	if (ctx.envData) result = applyValues(result, ctx.envData);
+	if (ctx.configData) result = applyValues(result, ctx.configData);
+	return result;
+}
+/**
+* Auto-coerce CLI string values to match the expected schema types.
+* Handles: string → number, string → boolean for primitive schema fields.
+* Arrays of primitives are also coerced element-wise.
+*/
+function coerceArgs(data, schema) {
+	let properties;
+	try {
+		const jsonSchema = schema["~standard"].jsonSchema.input({ target: "draft-2020-12" });
+		if (jsonSchema.type !== "object" || !jsonSchema.properties) return data;
+		properties = jsonSchema.properties;
+	} catch {
+		return data;
+	}
+	const result = { ...data };
+	for (const [key, value] of Object.entries(result)) {
+		const prop = properties[key];
+		if (!prop) continue;
+		const targetType = prop.type;
+		if (targetType === "number" || targetType === "integer") {
+			if (typeof value === "string") {
+				const num = Number(value);
+				if (!Number.isNaN(num)) result[key] = num;
+			}
+		} else if (targetType === "boolean") {
+			if (typeof value === "string") {
+				if (value === "true" || value === "1") result[key] = true;
+				else if (value === "false" || value === "0") result[key] = false;
+			}
+		} else if (targetType === "array" && Array.isArray(value)) {
+			const itemType = prop.items?.type;
+			if (itemType === "number" || itemType === "integer") result[key] = value.map((v) => {
+				if (typeof v === "string") {
+					const num = Number(v);
+					return Number.isNaN(num) ? v : num;
+				}
+				return v;
+			});
+			else if (itemType === "boolean") result[key] = value.map((v) => {
+				if (typeof v === "string") {
+					if (v === "true" || v === "1") return true;
+					if (v === "false" || v === "0") return false;
+				}
+				return v;
+			});
+		}
+	}
+	return result;
+}
+/** Keys consumed by the CLI framework that are not user-defined args. */
+const frameworkReservedKeys = new Set(["config", "c"]);
+/**
+* Detect unknown keys in the args that don't match any schema property.
+* Returns an array of { key, suggestion? } for each unknown key.
+* Framework-reserved keys (--config, -c) are always allowed.
+*/
+function detectUnknownArgs(data, schema, aliases, suggestFn) {
+	let properties;
+	let isLoose = false;
+	try {
+		const jsonSchema = schema["~standard"].jsonSchema.input({ target: "draft-2020-12" });
+		if (jsonSchema.type !== "object" || !jsonSchema.properties) return [];
+		properties = jsonSchema.properties;
+		if (jsonSchema.additionalProperties !== void 0 && jsonSchema.additionalProperties !== false) isLoose = true;
+	} catch {
+		return [];
+	}
+	if (isLoose) return [];
+	const knownKeys = new Set([
+		...Object.keys(properties),
+		...Object.keys(aliases),
+		...Object.values(aliases)
+	]);
+	const propertyNames = Object.keys(properties);
+	const unknowns = [];
+	for (const key of Object.keys(data)) if (!knownKeys.has(key) && !frameworkReservedKeys.has(key)) {
+		const suggestion = suggestFn(key, propertyNames);
+		unknowns.push({
+			key,
+			suggestion
+		});
+	}
+	return unknowns;
+}
+//#endregion
+export { parseStdinConfig as a, parsePositionalConfig as i, detectUnknownArgs as n, preprocessArgs as o, extractSchemaMetadata as r, coerceArgs as t };
+
+//# sourceMappingURL=args-CKNh7Dm9.mjs.map

package/dist/args-CKNh7Dm9.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"args-CKNh7Dm9.mjs","names":[],"sources":["../src/args.ts"],"sourcesContent":["import type { StandardJSONSchemaV1 } from '@standard-schema/spec';\n\nexport interface PadroneFieldMeta {\n  description?: string;\n  alias?: string[] | string;\n  deprecated?: boolean | string;\n  hidden?: boolean;\n  examples?: unknown[];\n}\n\ntype PositionalArgs<TObj> =\n  TObj extends Record<string, any>\n    ? {\n        [K in keyof TObj]: TObj[K] extends Array<any> ? `...${K & string}` : K & string;\n      }[keyof TObj]\n    : string;\n\n/**\n * Meta configuration for arguments, including positional arguments.\n * The `positional` array defines which arguments are positional and their order.\n * Use '...name' prefix to indicate variadic (rest) arguments, matching JS/TS rest syntax.\n *\n * @example\n * ```ts\n * .arguments(schema, {\n *   positional: ['source', '...files', 'dest'],  // '...files' is variadic\n * })\n * ```\n */\n/**\n * Configuration for reading from stdin and mapping it to an argument field.\n */\nexport type StdinConfig<TObj = Record<string, any>> =\n  | (keyof TObj & string)\n  | {\n      /** The argument field to populate with stdin data. */\n      field: keyof TObj & string;\n      /**\n       * How to consume stdin:\n       * - `'text'` (default): read all stdin as a single string.\n       * - `'lines'`: read stdin as an array of lines (string[]).\n       */\n      as?: 'text' | 'lines';\n    };\n\nexport interface PadroneArgsSchemaMeta<TObj = Record<string, any>> {\n  /**\n   * Array of argument names that should be treated as positional arguments.\n   * Order in array determines position. Use '...name' prefix for variadic args.\n   * @example ['source', '...files', 'dest'] - 'files' captures multiple values\n   */\n  positional?: PositionalArgs<TObj>[];\n  /**\n   * Per-argument metadata.\n   */\n  fields?: { [K in keyof TObj]?: PadroneFieldMeta };\n  /**\n   * Read from stdin and inject the data into the specified argument field.\n   * Only reads when stdin is piped (not a TTY) and the field wasn't already provided via CLI flags.\n   *\n   * - `string`: shorthand for `{ field: name, as: 'text' }` — read all stdin as a string.\n   * - `{ field, as }`: explicit form. `as: 'text'` reads all stdin as a string,\n   *   `as: 'lines'` reads stdin as an array of line strings.\n   *\n   * Precedence: CLI flags > stdin > env vars > config file > schema defaults.\n   *\n   * @example\n   * ```ts\n   * // Shorthand: read all stdin as text into 'data' field\n   * .arguments(z.object({ data: z.string() }), { stdin: 'data' })\n   *\n   * // Explicit: read stdin lines into 'lines' field\n   * .arguments(z.object({ lines: z.string().array() }), {\n   *   stdin: { field: 'lines', as: 'lines' },\n   * })\n   * ```\n   */\n  stdin?: StdinConfig<TObj>;\n  /**\n   * Fields to interactively prompt for when their values are missing after CLI/env/config resolution.\n   * - `true`: prompt for all required fields that are missing.\n   * - `string[]`: prompt for these specific fields if missing.\n   *\n   * Interactive prompting only occurs in `cli()` when the runtime has `interactive: true`.\n   * Setting this makes `parse()` and `cli()` return Promises.\n   *\n   * @example\n   * ```ts\n   * .arguments(schema, {\n   *   interactive: true,                        // prompt all missing required fields\n   *   interactive: ['name', 'template'],         // prompt only these fields\n   * })\n   * ```\n   */\n  interactive?: true | (keyof TObj & string)[];\n  /**\n   * Optional fields offered after required interactive prompts.\n   * Users are shown a multi-select to choose which of these fields to configure.\n   * - `true`: offer all optional fields that are missing.\n   * - `string[]`: offer these specific fields.\n   *\n   * @example\n   * ```ts\n   * .arguments(schema, {\n   *   interactive: ['name'],\n   *   optionalInteractive: ['typescript', 'eslint', 'prettier'],\n   * })\n   * ```\n   */\n  optionalInteractive?: true | (keyof TObj & string)[];\n}\n\n/**\n * Normalizes stdin config into its explicit form.\n */\nexport function parseStdinConfig(stdin: StdinConfig): { field: string; as: 'text' | 'lines' } {\n  if (typeof stdin === 'string') return { field: stdin, as: 'text' };\n  return { field: stdin.field as string, as: stdin.as ?? 'text' };\n}\n\n/**\n * Parse positional configuration to extract names and variadic info.\n */\nexport function parsePositionalConfig(positional: string[]): { name: string; variadic: boolean }[] {\n  return positional.map((p) => {\n    const isVariadic = p.startsWith('...');\n    const name = isVariadic ? p.slice(3) : p;\n    return { name, variadic: isVariadic };\n  });\n}\n\n/**\n * Result type for extractSchemaMetadata function.\n */\ninterface SchemaMetadataResult {\n  aliases: Record<string, string>;\n}\n\n/**\n * Extract all arg metadata from schema and meta in a single pass.\n * This consolidates aliases, env bindings, and config keys extraction.\n */\nexport function extractSchemaMetadata(\n  schema: StandardJSONSchemaV1,\n  meta?: Record<string, PadroneFieldMeta | undefined>,\n): SchemaMetadataResult {\n  const aliases: Record<string, string> = {};\n\n  // Extract from meta object\n  if (meta) {\n    for (const [key, value] of Object.entries(meta)) {\n      if (!value) continue;\n\n      // Extract aliases\n      if (value.alias) {\n        const list = typeof value.alias === 'string' ? [value.alias] : value.alias;\n        for (const aliasKey of list) {\n          if (typeof aliasKey === 'string' && aliasKey && aliasKey !== key) {\n            aliases[aliasKey] = key;\n          }\n        }\n      }\n    }\n  }\n\n  // Extract from JSON schema properties\n  try {\n    const jsonSchema = schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;\n    if (jsonSchema.type === 'object' && jsonSchema.properties) {\n      for (const [propertyName, propertySchema] of Object.entries(jsonSchema.properties as Record<string, any>)) {\n        if (!propertySchema) continue;\n\n        // Extract aliases from schema\n        const propAlias = propertySchema.alias;\n        if (propAlias) {\n          const list = typeof propAlias === 'string' ? [propAlias] : propAlias;\n          if (Array.isArray(list)) {\n            for (const aliasKey of list) {\n              if (typeof aliasKey === 'string' && aliasKey && aliasKey !== propertyName && !(aliasKey in aliases)) {\n                aliases[aliasKey] = propertyName;\n              }\n            }\n          }\n        }\n      }\n    }\n  } catch {\n    // Ignore errors from JSON schema generation\n  }\n\n  return { aliases };\n}\n\nfunction preprocessAliases(data: Record<string, unknown>, aliases: Record<string, string>): Record<string, unknown> {\n  const result = { ...data };\n\n  for (const [aliasKey, fullArgName] of Object.entries(aliases)) {\n    if (aliasKey in data && aliasKey !== fullArgName) {\n      const aliasValue = data[aliasKey];\n      // Prefer full arg name if it exists\n      if (!(fullArgName in result)) result[fullArgName] = aliasValue;\n      delete result[aliasKey];\n    }\n  }\n\n  return result;\n}\n\ninterface ParseArgsContext {\n  aliases?: Record<string, string>;\n  stdinData?: Record<string, unknown>;\n  envData?: Record<string, unknown>;\n  configData?: Record<string, unknown>;\n}\n\n/**\n * Apply values directly to arguments.\n * CLI values take precedence over the provided values.\n */\nfunction applyValues(data: Record<string, unknown>, values: Record<string, unknown>): Record<string, unknown> {\n  const result = { ...data };\n\n  for (const [key, value] of Object.entries(values)) {\n    // Only apply value if arg wasn't already set\n    if (key in result && result[key] !== undefined) continue;\n    if (value !== undefined) {\n      result[key] = value;\n    }\n  }\n\n  return result;\n}\n\n/**\n * Combined preprocessing of arguments with all features.\n * Precedence order (highest to lowest): CLI args > stdin > env vars > config file\n */\nexport function preprocessArgs(data: Record<string, unknown>, ctx: ParseArgsContext): Record<string, unknown> {\n  let result = { ...data };\n\n  // 1. Apply aliases first\n  if (ctx.aliases && Object.keys(ctx.aliases).length > 0) {\n    result = preprocessAliases(result, ctx.aliases);\n  }\n\n  // 2. Apply stdin data (higher precedence than env)\n  // Only applies if CLI didn't set the arg\n  if (ctx.stdinData) {\n    result = applyValues(result, ctx.stdinData);\n  }\n\n  // 3. Apply environment variables (higher precedence than config)\n  // These only apply if CLI/stdin didn't set the arg\n  if (ctx.envData) {\n    result = applyValues(result, ctx.envData);\n  }\n\n  // 4. Apply config file values (lowest precedence)\n  // These only apply if neither CLI, stdin, nor env set the arg\n  if (ctx.configData) {\n    result = applyValues(result, ctx.configData);\n  }\n\n  return result;\n}\n\n/**\n * Auto-coerce CLI string values to match the expected schema types.\n * Handles: string → number, string → boolean for primitive schema fields.\n * Arrays of primitives are also coerced element-wise.\n */\nexport function coerceArgs(data: Record<string, unknown>, schema: StandardJSONSchemaV1): Record<string, unknown> {\n  let properties: Record<string, any>;\n  try {\n    const jsonSchema = schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;\n    if (jsonSchema.type !== 'object' || !jsonSchema.properties) return data;\n    properties = jsonSchema.properties;\n  } catch {\n    return data;\n  }\n\n  const result = { ...data };\n\n  for (const [key, value] of Object.entries(result)) {\n    const prop = properties[key];\n    if (!prop) continue;\n\n    const targetType = prop.type as string | undefined;\n\n    if (targetType === 'number' || targetType === 'integer') {\n      if (typeof value === 'string') {\n        const num = Number(value);\n        if (!Number.isNaN(num)) result[key] = num;\n      }\n    } else if (targetType === 'boolean') {\n      if (typeof value === 'string') {\n        if (value === 'true' || value === '1') result[key] = true;\n        else if (value === 'false' || value === '0') result[key] = false;\n      }\n    } else if (targetType === 'array' && Array.isArray(value)) {\n      const itemType = prop.items?.type as string | undefined;\n      if (itemType === 'number' || itemType === 'integer') {\n        result[key] = value.map((v) => {\n          if (typeof v === 'string') {\n            const num = Number(v);\n            return Number.isNaN(num) ? v : num;\n          }\n          return v;\n        });\n      } else if (itemType === 'boolean') {\n        result[key] = value.map((v) => {\n          if (typeof v === 'string') {\n            if (v === 'true' || v === '1') return true;\n            if (v === 'false' || v === '0') return false;\n          }\n          return v;\n        });\n      }\n    }\n  }\n\n  return result;\n}\n\n/** Keys consumed by the CLI framework that are not user-defined args. */\nconst frameworkReservedKeys = new Set(['config', 'c']);\n\n/**\n * Detect unknown keys in the args that don't match any schema property.\n * Returns an array of { key, suggestion? } for each unknown key.\n * Framework-reserved keys (--config, -c) are always allowed.\n */\nexport function detectUnknownArgs(\n  data: Record<string, unknown>,\n  schema: StandardJSONSchemaV1,\n  aliases: Record<string, string>,\n  suggestFn: (input: string, candidates: string[]) => string,\n): { key: string; suggestion: string }[] {\n  let properties: Record<string, any>;\n  let isLoose = false;\n  try {\n    const jsonSchema = schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;\n    if (jsonSchema.type !== 'object' || !jsonSchema.properties) return [];\n    properties = jsonSchema.properties;\n    // If additionalProperties is set (true, {}, or a schema), the schema allows extra keys\n    if (jsonSchema.additionalProperties !== undefined && jsonSchema.additionalProperties !== false) isLoose = true;\n  } catch {\n    return [];\n  }\n\n  if (isLoose) return [];\n\n  const knownKeys = new Set<string>([...Object.keys(properties), ...Object.keys(aliases), ...Object.values(aliases)]);\n  const propertyNames = Object.keys(properties);\n  const unknowns: { key: string; suggestion: string }[] = [];\n\n  for (const key of Object.keys(data)) {\n    if (!knownKeys.has(key) && !frameworkReservedKeys.has(key)) {\n      const suggestion = suggestFn(key, propertyNames);\n      unknowns.push({ key, suggestion });\n    }\n  }\n\n  return unknowns;\n}\n"],"mappings":";;;;AAmHA,SAAgB,iBAAiB,OAA6D;AAC5F,KAAI,OAAO,UAAU,SAAU,QAAO;EAAE,OAAO;EAAO,IAAI;EAAQ;AAClE,QAAO;EAAE,OAAO,MAAM;EAAiB,IAAI,MAAM,MAAM;EAAQ;;;;;AAMjE,SAAgB,sBAAsB,YAA6D;AACjG,QAAO,WAAW,KAAK,MAAM;EAC3B,MAAM,aAAa,EAAE,WAAW,MAAM;AAEtC,SAAO;GAAE,MADI,aAAa,EAAE,MAAM,EAAE,GAAG;GACxB,UAAU;GAAY;GACrC;;;;;;AAcJ,SAAgB,sBACd,QACA,MACsB;CACtB,MAAM,UAAkC,EAAE;AAG1C,KAAI,KACF,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,KAAK,EAAE;AAC/C,MAAI,CAAC,MAAO;AAGZ,MAAI,MAAM,OAAO;GACf,MAAM,OAAO,OAAO,MAAM,UAAU,WAAW,CAAC,MAAM,MAAM,GAAG,MAAM;AACrE,QAAK,MAAM,YAAY,KACrB,KAAI,OAAO,aAAa,YAAY,YAAY,aAAa,IAC3D,SAAQ,YAAY;;;AAQ9B,KAAI;EACF,MAAM,aAAa,OAAO,aAAa,WAAW,MAAM,EAAE,QAAQ,iBAAiB,CAAC;AACpF,MAAI,WAAW,SAAS,YAAY,WAAW,WAC7C,MAAK,MAAM,CAAC,cAAc,mBAAmB,OAAO,QAAQ,WAAW,WAAkC,EAAE;AACzG,OAAI,CAAC,eAAgB;GAGrB,MAAM,YAAY,eAAe;AACjC,OAAI,WAAW;IACb,MAAM,OAAO,OAAO,cAAc,WAAW,CAAC,UAAU,GAAG;AAC3D,QAAI,MAAM,QAAQ,KAAK;UAChB,MAAM,YAAY,KACrB,KAAI,OAAO,aAAa,YAAY,YAAY,aAAa,gBAAgB,EAAE,YAAY,SACzF,SAAQ,YAAY;;;;SAO1B;AAIR,QAAO,EAAE,SAAS;;AAGpB,SAAS,kBAAkB,MAA+B,SAA0D;CAClH,MAAM,SAAS,EAAE,GAAG,MAAM;AAE1B,MAAK,MAAM,CAAC,UAAU,gBAAgB,OAAO,QAAQ,QAAQ,CAC3D,KAAI,YAAY,QAAQ,aAAa,aAAa;EAChD,MAAM,aAAa,KAAK;AAExB,MAAI,EAAE,eAAe,QAAS,QAAO,eAAe;AACpD,SAAO,OAAO;;AAIlB,QAAO;;;;;;AAcT,SAAS,YAAY,MAA+B,QAA0D;CAC5G,MAAM,SAAS,EAAE,GAAG,MAAM;AAE1B,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,EAAE;AAEjD,MAAI,OAAO,UAAU,OAAO,SAAS,KAAA,EAAW;AAChD,MAAI,UAAU,KAAA,EACZ,QAAO,OAAO;;AAIlB,QAAO;;;;;;AAOT,SAAgB,eAAe,MAA+B,KAAgD;CAC5G,IAAI,SAAS,EAAE,GAAG,MAAM;AAGxB,KAAI,IAAI,WAAW,OAAO,KAAK,IAAI,QAAQ,CAAC,SAAS,EACnD,UAAS,kBAAkB,QAAQ,IAAI,QAAQ;AAKjD,KAAI,IAAI,UACN,UAAS,YAAY,QAAQ,IAAI,UAAU;AAK7C,KAAI,IAAI,QACN,UAAS,YAAY,QAAQ,IAAI,QAAQ;AAK3C,KAAI,IAAI,WACN,UAAS,YAAY,QAAQ,IAAI,WAAW;AAG9C,QAAO;;;;;;;AAQT,SAAgB,WAAW,MAA+B,QAAuD;CAC/G,IAAI;AACJ,KAAI;EACF,MAAM,aAAa,OAAO,aAAa,WAAW,MAAM,EAAE,QAAQ,iBAAiB,CAAC;AACpF,MAAI,WAAW,SAAS,YAAY,CAAC,WAAW,WAAY,QAAO;AACnE,eAAa,WAAW;SAClB;AACN,SAAO;;CAGT,MAAM,SAAS,EAAE,GAAG,MAAM;AAE1B,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,EAAE;EACjD,MAAM,OAAO,WAAW;AACxB,MAAI,CAAC,KAAM;EAEX,MAAM,aAAa,KAAK;AAExB,MAAI,eAAe,YAAY,eAAe;OACxC,OAAO,UAAU,UAAU;IAC7B,MAAM,MAAM,OAAO,MAAM;AACzB,QAAI,CAAC,OAAO,MAAM,IAAI,CAAE,QAAO,OAAO;;aAE/B,eAAe;OACpB,OAAO,UAAU;QACf,UAAU,UAAU,UAAU,IAAK,QAAO,OAAO;aAC5C,UAAU,WAAW,UAAU,IAAK,QAAO,OAAO;;aAEpD,eAAe,WAAW,MAAM,QAAQ,MAAM,EAAE;GACzD,MAAM,WAAW,KAAK,OAAO;AAC7B,OAAI,aAAa,YAAY,aAAa,UACxC,QAAO,OAAO,MAAM,KAAK,MAAM;AAC7B,QAAI,OAAO,MAAM,UAAU;KACzB,MAAM,MAAM,OAAO,EAAE;AACrB,YAAO,OAAO,MAAM,IAAI,GAAG,IAAI;;AAEjC,WAAO;KACP;YACO,aAAa,UACtB,QAAO,OAAO,MAAM,KAAK,MAAM;AAC7B,QAAI,OAAO,MAAM,UAAU;AACzB,SAAI,MAAM,UAAU,MAAM,IAAK,QAAO;AACtC,SAAI,MAAM,WAAW,MAAM,IAAK,QAAO;;AAEzC,WAAO;KACP;;;AAKR,QAAO;;;AAIT,MAAM,wBAAwB,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC;;;;;;AAOtD,SAAgB,kBACd,MACA,QACA,SACA,WACuC;CACvC,IAAI;CACJ,IAAI,UAAU;AACd,KAAI;EACF,MAAM,aAAa,OAAO,aAAa,WAAW,MAAM,EAAE,QAAQ,iBAAiB,CAAC;AACpF,MAAI,WAAW,SAAS,YAAY,CAAC,WAAW,WAAY,QAAO,EAAE;AACrE,eAAa,WAAW;AAExB,MAAI,WAAW,yBAAyB,KAAA,KAAa,WAAW,yBAAyB,MAAO,WAAU;SACpG;AACN,SAAO,EAAE;;AAGX,KAAI,QAAS,QAAO,EAAE;CAEtB,MAAM,YAAY,IAAI,IAAY;EAAC,GAAG,OAAO,KAAK,WAAW;EAAE,GAAG,OAAO,KAAK,QAAQ;EAAE,GAAG,OAAO,OAAO,QAAQ;EAAC,CAAC;CACnH,MAAM,gBAAgB,OAAO,KAAK,WAAW;CAC7C,MAAM,WAAkD,EAAE;AAE1D,MAAK,MAAM,OAAO,OAAO,KAAK,KAAK,CACjC,KAAI,CAAC,UAAU,IAAI,IAAI,IAAI,CAAC,sBAAsB,IAAI,IAAI,EAAE;EAC1D,MAAM,aAAa,UAAU,KAAK,cAAc;AAChD,WAAS,KAAK;GAAE;GAAK;GAAY,CAAC;;AAItC,QAAO"}

package/dist/chunk-y_GBKt04.mjs

@@ -0,0 +1,5 @@
+import { createRequire } from "node:module";
+//#region \0rolldown/runtime.js
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+//#endregion
+export { __require as t };