padrone 1.1.0 → 1.3.0

package/src/cli/doctor.ts

@@ -0,0 +1,330 @@
+import { resolve } from 'node:path';
+import { commandSymbol } from '../command-utils.ts';
+import type { AnyPadroneCommand, PadroneActionContext } from '../types.ts';
+
+interface DoctorArgs {
+  entry: string;
+}
+
+type Severity = 'error' | 'warning';
+
+interface Diagnostic {
+  severity: Severity;
+  command: string;
+  message: string;
+}
+
+export async function runDoctor(args: DoctorArgs, _ctx: PadroneActionContext) {
+  const entryPath = resolve(args.entry);
+
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(entryPath)) as Record<string, unknown>;
+  } catch (err) {
+    console.error(`Failed to import entry file: ${entryPath}`);
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+
+  const program = findProgram(mod);
+  if (!program) {
+    console.error('No Padrone program found in the entry file.');
+    console.error('The entry file must export a Padrone program (default or named export).');
+    process.exit(1);
+  }
+
+  const cmd = (program as any)[commandSymbol] as AnyPadroneCommand;
+  const diagnostics: Diagnostic[] = [];
+
+  collectDiagnostics(cmd, diagnostics);
+
+  if (diagnostics.length === 0) {
+    console.log('No issues found.');
+    return;
+  }
+
+  const errors = diagnostics.filter((d) => d.severity === 'error');
+  const warnings = diagnostics.filter((d) => d.severity === 'warning');
+
+  for (const d of diagnostics) {
+    const prefix = d.severity === 'error' ? 'error' : 'warning';
+    console.log(`  ${prefix}: [${d.command}] ${d.message}`);
+  }
+
+  console.log();
+  const parts: string[] = [];
+  if (errors.length > 0) parts.push(`${errors.length} error(s)`);
+  if (warnings.length > 0) parts.push(`${warnings.length} warning(s)`);
+  console.log(`Found ${parts.join(' and ')}.`);
+
+  if (errors.length > 0) {
+    process.exit(1);
+  }
+}
+
+function collectDiagnostics(cmd: AnyPadroneCommand, diagnostics: Diagnostic[]) {
+  const allCommands = flattenCommands(cmd);
+
+  checkDuplicateAliases(allCommands, diagnostics);
+  checkShadowedOptionNames(allCommands, diagnostics);
+  checkCommandsWithoutActions(allCommands, diagnostics);
+  checkSchemasWithoutDescriptions(allCommands, diagnostics);
+  checkConflictingPositionals(allCommands, diagnostics);
+  checkUnusedPlugins(allCommands, diagnostics);
+}
+
+function flattenCommands(cmd: AnyPadroneCommand): AnyPadroneCommand[] {
+  const result: AnyPadroneCommand[] = [cmd];
+  if (cmd.commands) {
+    for (const sub of cmd.commands) {
+      result.push(...flattenCommands(sub));
+    }
+  }
+  return result;
+}
+
+function commandDisplayName(cmd: AnyPadroneCommand): string {
+  return cmd.path || cmd.name || '<root>';
+}
+
+function getJsonSchema(cmd: AnyPadroneCommand): Record<string, any> | null {
+  try {
+    if (!cmd.argsSchema) return null;
+    return cmd.argsSchema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check for duplicate aliases across sibling commands.
+ */
+function checkDuplicateAliases(commands: AnyPadroneCommand[], diagnostics: Diagnostic[]) {
+  for (const cmd of commands) {
+    if (!cmd.commands || cmd.commands.length < 2) continue;
+
+    const seen = new Map<string, string>();
+    for (const sub of cmd.commands) {
+      const names = [sub.name, ...(sub.aliases || [])];
+      for (const name of names) {
+        if (!name) continue;
+        const existing = seen.get(name);
+        if (existing) {
+          diagnostics.push({
+            severity: 'error',
+            command: commandDisplayName(cmd),
+            message: `Duplicate alias "${name}" used by both "${existing}" and "${sub.name}".`,
+          });
+        } else {
+          seen.set(name, sub.name);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Check for option names or subcommand names that shadow built-in flags/commands (help, version).
+ */
+function checkShadowedOptionNames(commands: AnyPadroneCommand[], diagnostics: Diagnostic[]) {
+  const builtins = new Set(['help', 'version']);
+
+  for (const cmd of commands) {
+    // Check subcommand names and aliases
+    if (cmd.commands) {
+      for (const sub of cmd.commands) {
+        const names = [sub.name, ...(sub.aliases || [])];
+        for (const name of names) {
+          if (name && builtins.has(name)) {
+            diagnostics.push({
+              severity: 'warning',
+              command: commandDisplayName(cmd),
+              message: `Subcommand "${sub.name}"${name !== sub.name ? ` (alias "${name}")` : ''} shadows the built-in "${name}" command.`,
+            });
+          }
+        }
+      }
+    }
+
+    // Check option names in schema
+    const jsonSchema = getJsonSchema(cmd);
+    if (!jsonSchema?.properties) continue;
+
+    for (const propName of Object.keys(jsonSchema.properties)) {
+      if (builtins.has(propName)) {
+        diagnostics.push({
+          severity: 'warning',
+          command: commandDisplayName(cmd),
+          message: `Option "${propName}" shadows the built-in --${propName} flag.`,
+        });
+      }
+    }
+
+    // Also check field flags and aliases from meta
+    if (cmd.meta?.fields) {
+      for (const [fieldName, fieldMeta] of Object.entries(cmd.meta.fields)) {
+        if (!fieldMeta) continue;
+
+        // Check flags (single-char)
+        if (fieldMeta.flags) {
+          const flagList = typeof fieldMeta.flags === 'string' ? [fieldMeta.flags] : fieldMeta.flags;
+          for (const flag of flagList) {
+            if (builtins.has(flag)) {
+              diagnostics.push({
+                severity: 'warning',
+                command: commandDisplayName(cmd),
+                message: `Flag "${flag}" on field "${fieldName}" shadows the built-in --${flag} flag.`,
+              });
+            }
+          }
+        }
+
+        // Check aliases (multi-char)
+        if (fieldMeta.alias) {
+          const aliasList = typeof fieldMeta.alias === 'string' ? [fieldMeta.alias] : fieldMeta.alias;
+          for (const alias of aliasList) {
+            if (builtins.has(alias)) {
+              diagnostics.push({
+                severity: 'warning',
+                command: commandDisplayName(cmd),
+                message: `Alias "${alias}" on field "${fieldName}" shadows the built-in --${alias} flag.`,
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Check for leaf commands (no subcommands) that have no action defined.
+ */
+function checkCommandsWithoutActions(commands: AnyPadroneCommand[], diagnostics: Diagnostic[]) {
+  for (const cmd of commands) {
+    const isLeaf = !cmd.commands || cmd.commands.length === 0;
+    // Root without subcommands or leaf commands should have actions
+    const isRoot = !cmd.parent;
+    if (isLeaf && !isRoot && !cmd.action) {
+      diagnostics.push({
+        severity: 'warning',
+        command: commandDisplayName(cmd),
+        message: 'Command has no action defined.',
+      });
+    }
+  }
+}
+
+/**
+ * Check for schema properties without descriptions.
+ */
+function checkSchemasWithoutDescriptions(commands: AnyPadroneCommand[], diagnostics: Diagnostic[]) {
+  for (const cmd of commands) {
+    const jsonSchema = getJsonSchema(cmd);
+    if (!jsonSchema?.properties) continue;
+
+    for (const [propName, propSchema] of Object.entries(jsonSchema.properties as Record<string, any>)) {
+      if (!propSchema) continue;
+
+      const hasDescription = propSchema.description || cmd.meta?.fields?.[propName]?.description;
+      if (!hasDescription) {
+        diagnostics.push({
+          severity: 'warning',
+          command: commandDisplayName(cmd),
+          message: `Option "${propName}" has no description.`,
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Check for conflicting positional argument configurations.
+ * e.g., variadic positional not at the end, or multiple variadics.
+ */
+function checkConflictingPositionals(commands: AnyPadroneCommand[], diagnostics: Diagnostic[]) {
+  for (const cmd of commands) {
+    const positional = cmd.meta?.positional;
+    if (!positional || positional.length === 0) continue;
+
+    let variadicCount = 0;
+    let variadicIndex = -1;
+
+    for (let i = 0; i < positional.length; i++) {
+      const p = positional[i] as string;
+      if (p.startsWith('...')) {
+        variadicCount++;
+        variadicIndex = i;
+      }
+    }
+
+    if (variadicCount > 1) {
+      diagnostics.push({
+        severity: 'error',
+        command: commandDisplayName(cmd),
+        message: 'Multiple variadic positional arguments defined.',
+      });
+    }
+
+    if (variadicCount === 1 && variadicIndex !== positional.length - 1) {
+      diagnostics.push({
+        severity: 'warning',
+        command: commandDisplayName(cmd),
+        message: 'Variadic positional argument is not in the last position.',
+      });
+    }
+
+    // Check for positional names that don't exist in schema
+    const jsonSchema = getJsonSchema(cmd);
+    if (jsonSchema?.properties) {
+      for (const p of positional) {
+        const name = (p as string).replace(/^\.\.\./, '');
+        if (!(name in jsonSchema.properties)) {
+          diagnostics.push({
+            severity: 'error',
+            command: commandDisplayName(cmd),
+            message: `Positional "${name}" does not exist in the schema.`,
+          });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Check for plugins that don't define any phase handlers.
+ */
+function checkUnusedPlugins(commands: AnyPadroneCommand[], diagnostics: Diagnostic[]) {
+  const phases = ['start', 'parse', 'validate', 'execute', 'error', 'shutdown'] as const;
+
+  for (const cmd of commands) {
+    if (!cmd.plugins) continue;
+
+    for (const plugin of cmd.plugins) {
+      const hasHandler = phases.some((phase) => typeof (plugin as any)[phase] === 'function');
+      if (!hasHandler) {
+        diagnostics.push({
+          severity: 'warning',
+          command: commandDisplayName(cmd),
+          message: `Plugin "${plugin.name}" has no phase handlers.`,
+        });
+      }
+    }
+  }
+}
+
+function findProgram(mod: Record<string, unknown>): unknown | null {
+  const defaultExport = mod.default;
+  if (isPadroneProgram(defaultExport)) return defaultExport;
+
+  for (const value of Object.values(mod)) {
+    if (isPadroneProgram(value)) return value;
+  }
+
+  return null;
+}
+
+function isPadroneProgram(value: unknown): boolean {
+  if (!value || typeof value !== 'object') return false;
+  return commandSymbol in value;
+}

package/src/cli/index.ts

@@ -0,0 +1,159 @@
+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';
+
+const PadroneCLI = createPadrone('padrone')
+  .configure({
+    version: pkg.version,
+    title: 'Padrone CLI',
+    description: 'The Padrone CLI',
+  })
+  .command('init', (cmd) =>
+    cmd
+      .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'],
+        },
+      )
+      .async()
+      .action(runInit),
+  )
+  .command('docs', (cmd) =>
+    cmd
+      .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'],
+        },
+      )
+      .async()
+      .action(runDocs),
+  )
+  .command('doctor', (cmd) =>
+    cmd
+      .configure({
+        description: 'Lint and validate a Padrone CLI program definition',
+      })
+      .arguments(
+        z.object({
+          entry: z.string().describe('Entry file that exports a Padrone program'),
+        }),
+        {
+          positional: ['entry'],
+        },
+      )
+      .async()
+      .action(runDoctor),
+  )
+  .command('completions', (cmd) =>
+    cmd
+      .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'],
+        },
+      )
+      .action(runCompletions),
+  )
+  .command('link', (cmd) =>
+    cmd
+      .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'],
+        },
+      )
+      .async()
+      .action(runLink),
+  )
+  .command('unlink', (cmd) =>
+    cmd
+      .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'],
+        },
+      )
+      .async()
+      .action(runUnlink),
+  )
+  .command('wrap', (cmd) =>
+    cmd
+      .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' } },
+        },
+      )
+      .async()
+      .action(runWrap),
+  );
+
+if (import.meta.main) {
+  try {
+    const cliRes = await PadroneCLI.cli();
+    await cliRes.result;
+  } catch (error) {
+    console.error('Error running Padrone CLI:', error);
+    process.exit(1);
+  }
+}
+
+export default PadroneCLI;
+export { PadroneCLI };

package/src/cli/init.ts

@@ -0,0 +1,135 @@
+import { existsSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { createFileEmitter, template } from 'padrone/codegen';
+import type { PadroneActionContext } from '../types.ts';
+
+interface InitArgs {
+  name?: string;
+  description?: string;
+  version?: string;
+  dir?: string;
+}
+
+const packageJsonTemplate = template(`{
+  "name": "{{name}}",
+  "version": "{{version}}",
+  "private": true,
+  "type": "module",
+  "module": "src/index.ts",
+  "bin": {
+    "{{name}}": "src/index.ts"
+  },
+  "scripts": {
+    "start": "bun src/index.ts",
+    "dev": "bun --watch src/index.ts",
+    "link": "padrone link",
+    "unlink": "padrone unlink"
+  },
+  "dependencies": {
+    "padrone": "^{{padroneVersion}}",
+    "zod": "^4.0.0"
+  }
+}
+`);
+
+const tsconfigTemplate = template(`{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
+`);
+
+const programTemplate = template(`import { createPadrone } from 'padrone'
+import * as z from 'zod/v4'
+
+const program = createPadrone('{{name}}')
+  .configure({
+    version: '{{version}}',
+    description: '{{description}}',
+  })
+  .command('hello', (cmd) => cmd
+    .configure({ description: 'Say hello' })
+    .arguments(z.object({
+      name: z.string().default('world').describe('Name to greet'),
+    }), {
+      positional: ['name'],
+    })
+    .action((args) => {
+      return \`Hello, \${args.name}!\`
+    })
+  )
+
+if (import.meta.main) {
+  try {
+    const cliRes = await program.cli();
+    await cliRes.result;
+  } catch (error) {
+    console.error('Error running program:', error);
+    process.exit(1);
+  }
+}
+
+export default program;
+export { program };
+`);
+
+export async function runInit(args: InitArgs, ctx: PadroneActionContext) {
+  const { output, error } = ctx.runtime;
+  const dir = resolve(args.dir || '.');
+  const name = args.name || basename(dir);
+  const description = args.description || `${name} CLI`;
+  const version = args.version || '0.1.0';
+
+  if (existsSync(resolve(dir, 'package.json'))) {
+    error(`A package.json already exists in ${dir}. Aborting.`);
+    return;
+  }
+
+  let padroneVersion = '1.0.0';
+  try {
+    const pkg = await import('padrone/package.json', { with: { type: 'json' } });
+    padroneVersion = (pkg.default as any).version || padroneVersion;
+  } catch {
+    // Use fallback version
+  }
+
+  const data = { name, description, version, padroneVersion };
+
+  const emitter = createFileEmitter({ outDir: dir });
+
+  emitter.addFile('package.json', packageJsonTemplate(data));
+  emitter.addFile('tsconfig.json', tsconfigTemplate(data));
+  emitter.addFile('src/index.ts', programTemplate(data));
+
+  const result = await emitter.emit();
+
+  if (result.errors.length > 0) {
+    for (const err of result.errors) {
+      error(`Failed to write ${err.file}: ${err.error.message}`);
+    }
+    return;
+  }
+
+  output(`Created ${name} CLI project in ${dir}`);
+  output('');
+  output('Files written:');
+  for (const file of result.written) {
+    output(`  ${file}`);
+  }
+  output('');
+  output('Next steps:');
+  if (dir !== process.cwd()) {
+    output(`  cd ${dir}`);
+  }
+  output('  bun install');
+  output('  bun run dev');
+}