padrone 1.5.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "padrone",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Create type-safe, interactive CLI apps with Zod schemas",
   "license": "MIT",
   "type": "module",
@@ -89,18 +89,10 @@
       },
       "source": "./src/zod.ts"
     },
-    "./completion": {
-      "padrone@dev": "./src/completion.ts",
-      "import": {
-        "types": "./dist/completion.d.mts",
-        "default": "./dist/completion.mjs"
-      },
-      "source": "./src/completion.ts"
-    },
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "tsdown src/index.ts src/test.ts src/zod.ts src/codegen/index.ts src/docs/index.ts src/completion.ts --dts --sourcemap",
+    "build": "tsdown src/index.ts src/test.ts src/zod.ts src/codegen/index.ts src/docs/index.ts --dts --sourcemap",
     "start": "bun --conditions=padrone@dev src/cli/index.ts",
     "dev": "bun --conditions=padrone@dev --watch src/cli/index.ts",
     "test": "bun test --conditions=padrone@dev",
@@ -113,18 +105,29 @@
     "enquirer": "^2.4.1"
   },
   "devDependencies": {
-    "ai": "^6.0.116",
-    "tsdown": "^0.21.4",
+    "@types/react": "^19.2.14",
+    "ai": "^6.0.141",
+    "ink": "^6.8.0",
+    "react": "^19.2.4",
+    "tsdown": "^0.21.6",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
     "ai": "5 || 6",
+    "ink": "^6.0.0",
+    "react": ">=18.0.0",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
     "ai": {
       "optional": true
     },
+    "ink": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     }

package/src/cli/completions.ts

@@ -1,16 +1,19 @@
-import { basename } from 'node:path';
-import { detectShell, getCompletionInstallInstructions, type ShellType, setupCompletions } from '../completion.ts';
-import type { PadroneActionContext } from '../types.ts';
+import * as z from 'zod/v4';
+import { detectShell, getCompletionInstallInstructions, setupCompletions } from '../feature/completion.ts';
+import type { PadroneActionContext } from '../types/index.ts';
 
-interface CompletionsArgs {
-  appPath?: string;
-  for?: ShellType;
-  setup?: boolean;
-}
+export const completionsSchema = z.object({
+  appPath: z.string().optional().describe('Path or name of the CLI program (defaults to padrone)'),
+  for: z.enum(['bash', 'zsh', 'fish', 'powershell']).optional().describe('Target shell (auto-detected if omitted)'),
+  setup: z.boolean().optional().default(false).describe('Write completions to shell config file'),
+});
+
+type CompletionsArgs = z.infer<typeof completionsSchema>;
 
-export function runCompletions(args: CompletionsArgs, _ctx: PadroneActionContext) {
+export async function runCompletions(args: CompletionsArgs, _ctx: PadroneActionContext) {
+  const { basename } = await import('node:path');
   const programName = args.appPath ? basename(args.appPath).replace(/\.[cm]?[jt]sx?$/, '') : 'padrone';
-  const shell = args.for ?? detectShell();
+  const shell = args.for ?? (await detectShell());
 
   if (!shell) {
     console.error('Could not detect shell. Use --for to specify one: bash, zsh, fish, powershell');
@@ -18,7 +21,7 @@ export function runCompletions(args: CompletionsArgs, _ctx: PadroneActionContext
   }
 
   if (args.setup) {
-    const result = setupCompletions(programName, shell);
+    const result = await setupCompletions(programName, shell);
     const verb = result.updated ? 'Updated' : 'Added';
     console.log(`${verb} ${programName} completions in ${result.file}`);
     return;

package/src/cli/docs.ts

@@ -1,15 +1,18 @@
 import { resolve } from 'node:path';
-import { isPadroneProgram } from '../command-utils.ts';
-import { type DocsFormat, generateDocs } from '../docs/index.ts';
-import type { PadroneActionContext } from '../types.ts';
+import * as z from 'zod/v4';
+import { isPadroneProgram } from '../core/commands.ts';
+import { generateDocs } from '../docs/index.ts';
+import type { PadroneActionContext } from '../types/index.ts';
 
-interface DocsArgs {
-  entry: string;
-  output?: string;
-  format?: DocsFormat;
-  includeHidden?: boolean;
-  dryRun?: boolean;
-}
+export const docsSchema = z.object({
+  entry: z.string().describe('Entry file that exports a Padrone program'),
+  output: z.string().optional().default('./docs/cli').describe('Output directory'),
+  format: z.enum(['markdown', 'html', 'man', 'json']).optional().default('markdown').describe('Output format'),
+  includeHidden: z.boolean().optional().default(false).describe('Include hidden commands and options'),
+  dryRun: z.boolean().optional().default(false).describe('Print what would be generated without writing'),
+});
+
+type DocsArgs = z.infer<typeof docsSchema>;
 
 export async function runDocs(args: DocsArgs, _ctx: PadroneActionContext) {
   const entryPath = resolve(args.entry);

package/src/cli/doctor.ts

@@ -1,12 +1,15 @@
 import { resolve } from 'node:path';
-import { JSON_SCHEMA_OPTS } from '../args.ts';
-import { getCommand, isPadroneProgram } from '../command-utils.ts';
-import type { AnyPadroneCommand, PadroneActionContext } from '../types.ts';
+import * as z from 'zod/v4';
+import { getJsonSchema } from '../core/args.ts';
+import { getCommand, isPadroneProgram } from '../core/commands.ts';
+import type { AnyPadroneCommand, PadroneActionContext } from '../types/index.ts';
 import { detectEntry } from './link.ts';
 
-interface DoctorArgs {
-  entry?: string;
-}
+export const doctorSchema = z.object({
+  entry: z.string().optional().describe('Entry file that exports a Padrone program (auto-detected from package.json if omitted)'),
+});
+
+type DoctorArgs = z.infer<typeof doctorSchema>;
 
 type Severity = 'error' | 'warning';
 
@@ -85,7 +88,7 @@ function collectDiagnostics(cmd: AnyPadroneCommand, diagnostics: Diagnostic[]) {
   checkCommandsWithoutActions(allCommands, diagnostics);
   checkSchemasWithoutDescriptions(allCommands, diagnostics);
   checkConflictingPositionals(allCommands, diagnostics);
-  checkUnusedPlugins(allCommands, diagnostics);
+  checkUnusedInterceptors(allCommands, diagnostics);
   checkDuplicateOptionFlagsAndAliases(allCommands, diagnostics);
   checkUnreachableCommands(allCommands, diagnostics);
   checkMissingCommandDescriptions(allCommands, diagnostics);
@@ -107,10 +110,10 @@ function commandDisplayName(cmd: AnyPadroneCommand): string {
   return cmd.path || cmd.name || '<root>';
 }
 
-function getJsonSchema(cmd: AnyPadroneCommand): Record<string, any> | null {
+function getCommandJsonSchema(cmd: AnyPadroneCommand): Record<string, any> | null {
   try {
     if (!cmd.argsSchema) return null;
-    return cmd.argsSchema['~standard'].jsonSchema.input(JSON_SCHEMA_OPTS) as Record<string, any>;
+    return getJsonSchema(cmd.argsSchema) as Record<string, any>;
   } catch {
     return null;
   }
@@ -167,7 +170,7 @@ function checkShadowedOptionNames(commands: AnyPadroneCommand[], diagnostics: Di
     }
 
     // Check option names in schema
-    const jsonSchema = getJsonSchema(cmd);
+    const jsonSchema = getCommandJsonSchema(cmd);
     if (!jsonSchema?.properties) continue;
 
     for (const propName of Object.keys(jsonSchema.properties)) {
@@ -240,7 +243,7 @@ function checkCommandsWithoutActions(commands: AnyPadroneCommand[], diagnostics:
  */
 function checkSchemasWithoutDescriptions(commands: AnyPadroneCommand[], diagnostics: Diagnostic[]) {
   for (const cmd of commands) {
-    const jsonSchema = getJsonSchema(cmd);
+    const jsonSchema = getCommandJsonSchema(cmd);
     if (!jsonSchema?.properties) continue;
 
     for (const [propName, propSchema] of Object.entries(jsonSchema.properties as Record<string, any>)) {
@@ -295,7 +298,7 @@ function checkConflictingPositionals(commands: AnyPadroneCommand[], diagnostics:
     }
 
     // Check for positional names that don't exist in schema
-    const jsonSchema = getJsonSchema(cmd);
+    const jsonSchema = getCommandJsonSchema(cmd);
     if (jsonSchema?.properties) {
       for (const p of positional) {
         const name = (p as string).replace(/^\.\.\./, '');
@@ -312,21 +315,22 @@ function checkConflictingPositionals(commands: AnyPadroneCommand[], diagnostics:
 }
 
 /**
- * Check for plugins that don't define any phase handlers.
+ * Check for interceptors that don't define any phase handlers.
  */
-function checkUnusedPlugins(commands: AnyPadroneCommand[], diagnostics: Diagnostic[]) {
+function checkUnusedInterceptors(commands: AnyPadroneCommand[], diagnostics: Diagnostic[]) {
   const phases = ['start', 'parse', 'validate', 'execute', 'error', 'shutdown'] as const;
 
   for (const cmd of commands) {
-    if (!cmd.plugins) continue;
+    if (!cmd.interceptors) continue;
 
-    for (const plugin of cmd.plugins) {
-      const hasHandler = phases.some((phase) => typeof (plugin as any)[phase] === 'function');
+    for (const interceptor of cmd.interceptors) {
+      const phases_obj = interceptor.factory();
+      const hasHandler = phases.some((phase) => typeof (phases_obj as any)[phase] === 'function');
       if (!hasHandler) {
         diagnostics.push({
           severity: 'warning',
           command: commandDisplayName(cmd),
-          message: `Plugin "${plugin.name}" has no phase handlers.`,
+          message: `Interceptor "${interceptor.meta.name}" has no phase handlers.`,
         });
       }
     }

package/src/cli/index.ts

@@ -1,12 +1,11 @@
 import { createPadrone } from 'padrone';
 import pkg from 'padrone/package.json' with { type: 'json' };
-import * as z from 'zod/v4';
-import { runCompletions } from './completions.ts';
-import { runDocs } from './docs.ts';
-import { runDoctor } from './doctor.ts';
-import { runInit } from './init.ts';
-import { runLink, runUnlink } from './link.ts';
-import { runWrap } from './wrap.ts';
+import { completionsSchema, runCompletions } from './completions.ts';
+import { docsSchema, runDocs } from './docs.ts';
+import { doctorSchema, runDoctor } from './doctor.ts';
+import { initSchema, runInit } from './init.ts';
+import { linkSchema, runLink, runUnlink, unlinkSchema } from './link.ts';
+import { runWrap, wrapSchema } from './wrap.ts';
 
 const PadroneCLI = createPadrone('padrone')
   .configure({
@@ -19,17 +18,9 @@ const PadroneCLI = createPadrone('padrone')
       .configure({
         description: 'Scaffold a new Padrone CLI project',
       })
-      .arguments(
-        z.object({
-          name: z.string().optional().describe('Project name (defaults to directory name)'),
-          description: z.string().optional().describe('Project description'),
-          version: z.string().optional().default('0.1.0').describe('Initial version'),
-          dir: z.string().optional().describe('Target directory (defaults to current directory)'),
-        }),
-        {
-          positional: ['dir'],
-        },
-      )
+      .arguments(initSchema, {
+        positional: ['dir'],
+      })
       .async()
       .action(runInit),
   )
@@ -38,18 +29,9 @@ const PadroneCLI = createPadrone('padrone')
       .configure({
         description: 'Generate documentation for a Padrone CLI program',
       })
-      .arguments(
-        z.object({
-          entry: z.string().describe('Entry file that exports a Padrone program'),
-          output: z.string().optional().default('./docs/cli').describe('Output directory'),
-          format: z.enum(['markdown', 'html', 'man', 'json']).optional().default('markdown').describe('Output format'),
-          includeHidden: z.boolean().optional().default(false).describe('Include hidden commands and options'),
-          dryRun: z.boolean().optional().default(false).describe('Print what would be generated without writing'),
-        }),
-        {
-          positional: ['entry'],
-        },
-      )
+      .arguments(docsSchema, {
+        positional: ['entry'],
+      })
       .async()
       .action(runDocs),
   )
@@ -58,14 +40,9 @@ const PadroneCLI = createPadrone('padrone')
       .configure({
         description: 'Lint and validate a Padrone CLI program definition',
       })
-      .arguments(
-        z.object({
-          entry: z.string().optional().describe('Entry file that exports a Padrone program (auto-detected from package.json if omitted)'),
-        }),
-        {
-          positional: ['entry'],
-        },
-      )
+      .arguments(doctorSchema, {
+        positional: ['entry'],
+      })
       .async()
       .action(runDoctor),
   )
@@ -74,16 +51,9 @@ const PadroneCLI = createPadrone('padrone')
       .configure({
         description: 'Show shell completion install instructions for a Padrone CLI program',
       })
-      .arguments(
-        z.object({
-          appPath: z.string().optional().describe('Path or name of the CLI program (defaults to padrone)'),
-          for: z.enum(['bash', 'zsh', 'fish', 'powershell']).optional().describe('Target shell (auto-detected if omitted)'),
-          setup: z.boolean().optional().default(false).describe('Write completions to shell config file'),
-        }),
-        {
-          positional: ['appPath'],
-        },
-      )
+      .arguments(completionsSchema, {
+        positional: ['appPath'],
+      })
       .action(runCompletions),
   )
   .command('link', (cmd) =>
@@ -91,17 +61,9 @@ const PadroneCLI = createPadrone('padrone')
       .configure({
         description: 'Link a Padrone CLI program for global use during development',
       })
-      .arguments(
-        z.object({
-          entry: z.string().optional().describe('Entry file (auto-detected from package.json bin field)'),
-          name: z.string().optional().describe('Command name (auto-detected from package.json)'),
-          list: z.boolean().optional().default(false).describe('List all linked programs'),
-          setup: z.boolean().optional().default(false).describe('Add ~/.padrone/bin to PATH in shell config'),
-        }),
-        {
-          positional: ['entry'],
-        },
-      )
+      .arguments(linkSchema, {
+        positional: ['entry'],
+      })
       .async()
       .action(runLink),
   )
@@ -110,14 +72,9 @@ const PadroneCLI = createPadrone('padrone')
       .configure({
         description: 'Remove a previously linked Padrone CLI program',
       })
-      .arguments(
-        z.object({
-          name: z.string().optional().describe('Program name to unlink (auto-detected from current directory)'),
-        }),
-        {
-          positional: ['name'],
-        },
-      )
+      .arguments(unlinkSchema, {
+        positional: ['name'],
+      })
       .async()
       .action(runUnlink),
   )
@@ -126,21 +83,10 @@ const PadroneCLI = createPadrone('padrone')
       .configure({
         description: 'Generate a Padrone wrapper for an existing CLI tool',
       })
-      .arguments(
-        z.object({
-          command: z.string().describe('CLI command to wrap (e.g. gh, docker, kubectl)'),
-          source: z.enum(['help', 'fish', 'zsh']).optional().default('help').describe('Parsing source (default: help)'),
-          output: z.string().optional().describe('Output directory (default: ./src/<command>)'),
-          depth: z.number().default(4).optional().describe('Max subcommand depth'),
-          dryRun: z.boolean().optional().default(false).describe('Print what would be generated without writing'),
-          overwrite: z.boolean().optional().default(false).describe('Overwrite existing files'),
-          yes: z.boolean().optional().default(false).describe('Skip confirmation prompt'),
-        }),
-        {
-          positional: ['command'],
-          fields: { yes: { alias: 'y' } },
-        },
-      )
+      .arguments(wrapSchema, {
+        positional: ['command'],
+        fields: { yes: { alias: 'y' } },
+      })
       .async()
       .action(runWrap),
   );

package/src/cli/init.ts

@@ -1,14 +1,17 @@
 import { existsSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
 import { createFileEmitter, template } from 'padrone/codegen';
-import type { PadroneActionContext } from '../types.ts';
+import * as z from 'zod/v4';
+import type { PadroneActionContext } from '../types/index.ts';
 
-interface InitArgs {
-  name?: string;
-  description?: string;
-  version?: string;
-  dir?: string;
-}
+export const initSchema = z.object({
+  name: z.string().optional().describe('Project name (defaults to directory name)'),
+  description: z.string().optional().describe('Project description'),
+  version: z.string().optional().default('0.1.0').describe('Initial version'),
+  dir: z.string().optional().describe('Target directory (defaults to current directory)'),
+});
+
+type InitArgs = z.infer<typeof initSchema>;
 
 const packageJsonTemplate = template(`{
   "name": "{{name}}",

package/src/cli/link.ts

@@ -1,19 +1,23 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, resolve } from 'node:path';
-import { detectShell, getRcFile, type ShellType, writeToRcFile } from '../shell-utils.ts';
-import type { PadroneActionContext } from '../types.ts';
-
-interface LinkArgs {
-  entry?: string;
-  name?: string;
-  list?: boolean;
-  setup?: boolean;
-}
+import * as z from 'zod/v4';
+import type { PadroneActionContext } from '../types/index.ts';
+import { detectShell, getRcFile, type ShellType, writeToRcFile } from '../util/shell-utils.ts';
 
-interface UnlinkArgs {
-  name?: string;
-}
+export const linkSchema = z.object({
+  entry: z.string().optional().describe('Entry file (auto-detected from package.json bin field)'),
+  name: z.string().optional().describe('Command name (auto-detected from package.json)'),
+  list: z.boolean().optional().default(false).describe('List all linked programs'),
+  setup: z.boolean().optional().default(false).describe('Add ~/.padrone/bin to PATH in shell config'),
+});
+
+export const unlinkSchema = z.object({
+  name: z.string().optional().describe('Program name to unlink (auto-detected from current directory)'),
+});
+
+type LinkArgs = z.infer<typeof linkSchema>;
+type UnlinkArgs = z.infer<typeof unlinkSchema>;
 
 interface LinkEntry {
   name: string;
@@ -143,8 +147,8 @@ function buildPathSnippet(shell: ShellType, binDir: string): string {
   }
 }
 
-function setupPath(shell: ShellType): { file: string; updated: boolean } {
-  const rcFile = getRcFile(shell);
+async function setupPath(shell: ShellType): Promise<{ file: string; updated: boolean }> {
+  const rcFile = await getRcFile(shell);
   if (!rcFile) {
     throw new Error(`Could not determine config file for ${shell}.`);
   }
@@ -268,13 +272,13 @@ export async function runLink(args: LinkArgs, ctx: PadroneActionContext) {
 
   if (!isInPath(BIN_DIR)) {
     if (args.setup) {
-      const shell = detectShell();
+      const shell = await detectShell();
       if (!shell) {
         error('Could not detect shell. Add the PATH manually:');
         error(`  export PATH="${BIN_DIR}:$PATH"`);
         return;
       }
-      const result = setupPath(shell);
+      const result = await setupPath(shell);
       const verb = result.updated ? 'Updated' : 'Added';
       output(`${verb} PATH in ${result.file}`);
       output('Restart your shell or run:');

package/src/cli/wrap.ts

@@ -1,20 +1,23 @@
 import { resolve } from 'node:path';
 import { createCodeBuilder, createFileEmitter, generateCommandTree } from 'padrone/codegen';
+import * as z from 'zod/v4';
 import type { DiscoverySource } from '../codegen/discovery.ts';
 import { discoverCli } from '../codegen/discovery.ts';
 import { template } from '../codegen/template.ts';
 import type { GeneratorContext } from '../codegen/types.ts';
-import type { PadroneActionContext } from '../types.ts';
-
-interface WrapArgs {
-  command: string;
-  source?: DiscoverySource;
-  output?: string;
-  depth?: number;
-  dryRun?: boolean;
-  overwrite?: boolean;
-  yes?: boolean;
-}
+import type { PadroneActionContext } from '../types/index.ts';
+
+export const wrapSchema = z.object({
+  command: z.string().describe('CLI command to wrap (e.g. gh, docker, kubectl)'),
+  source: z.enum(['help', 'fish', 'zsh']).optional().default('help').describe('Parsing source (default: help)'),
+  output: z.string().optional().describe('Output directory (default: ./src/<command>)'),
+  depth: z.number().default(4).optional().describe('Max subcommand depth'),
+  dryRun: z.boolean().optional().default(false).describe('Print what would be generated without writing'),
+  overwrite: z.boolean().optional().default(false).describe('Overwrite existing files'),
+  yes: z.boolean().optional().default(false).describe('Skip confirmation prompt'),
+});
+
+type WrapArgs = z.infer<typeof wrapSchema>;
 
 export async function runWrap(args: WrapArgs, ctx: PadroneActionContext) {
   const { output, error } = ctx.runtime;

package/src/codegen/schema-to-code.ts

@@ -1,5 +1,5 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
-import { JSON_SCHEMA_OPTS } from '../args.ts';
+import { getJsonSchema } from '../core/args.ts';
 import type { FieldMeta } from './types.ts';
 
 interface SchemaToCodeResult {
@@ -58,7 +58,7 @@ function jsonSchemaPropertyToZod(prop: Record<string, any>, required: boolean, a
  */
 export function schemaToCode(schema: StandardSchemaV1): SchemaToCodeResult {
   try {
-    const jsonSchema = (schema as any)['~standard'].jsonSchema.input(JSON_SCHEMA_OPTS) as Record<string, any>;
+    const jsonSchema = getJsonSchema(schema as any) as Record<string, any>;
     return jsonSchemaToCode(jsonSchema);
   } catch {
     return { code: 'z.unknown()', imports: ['z'] };