padrone 1.1.0 → 1.3.0

package/src/cli/link.ts

@@ -0,0 +1,320 @@
+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;
+}
+
+interface UnlinkArgs {
+  name?: string;
+}
+
+interface LinkEntry {
+  name: string;
+  entry: string;
+  dir: string;
+  linkedAt: string;
+}
+
+type LinksData = Record<string, LinkEntry>;
+
+function sanitizeBinName(name: string): string {
+  // Strip npm scope (@org/name → name)
+  const unscoped = name.startsWith('@') ? name.split('/').pop()! : name;
+  // Replace any remaining path-unsafe chars
+  return unscoped.replace(/[^a-zA-Z0-9._-]/g, '-');
+}
+
+const PADRONE_HOME = resolve(homedir(), '.padrone');
+const BIN_DIR = resolve(PADRONE_HOME, 'bin');
+const LINKS_FILE = resolve(PADRONE_HOME, 'links.json');
+
+function readLinks(): LinksData {
+  if (!existsSync(LINKS_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(LINKS_FILE, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeLinks(links: LinksData) {
+  mkdirSync(PADRONE_HOME, { recursive: true });
+  writeFileSync(LINKS_FILE, `${JSON.stringify(links, null, 2)}\n`);
+}
+
+interface DetectedEntry {
+  entry: string;
+  name: string;
+  /** Full run command prefix parsed from scripts (e.g. "bun --conditions=padrone@dev") */
+  runPrefix?: string;
+}
+
+function parseRunPrefix(script: string, entryRelative: string, dir: string): string | undefined {
+  // Split script into tokens and find the one that resolves to the same path as the entry
+  const entryResolved = resolve(dir, entryRelative);
+  const tokens = script.split(/\s+/);
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]!;
+    if (resolve(dir, token) === entryResolved) {
+      const prefix = tokens.slice(0, i).join(' ');
+      return prefix || undefined;
+    }
+  }
+  return undefined;
+}
+
+function detectEntry(dir: string): DetectedEntry | undefined {
+  const pkgPath = resolve(dir, 'package.json');
+  if (!existsSync(pkgPath)) return undefined;
+
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+
+    let entryRelative: string | undefined;
+    let name: string | undefined;
+
+    // Try bin field first
+    if (pkg.bin) {
+      if (typeof pkg.bin === 'string') {
+        entryRelative = pkg.bin;
+        name = pkg.name || basename(dir);
+      } else {
+        const binEntries = Object.entries(pkg.bin);
+        if (binEntries.length > 0) {
+          [name, entryRelative] = binEntries[0] as [string, string];
+        }
+      }
+    }
+
+    // Fallback to main/module
+    if (!entryRelative) {
+      const main = pkg.module || pkg.main;
+      if (main) {
+        entryRelative = main;
+        name = pkg.name || basename(dir);
+      }
+    }
+
+    if (!entryRelative || !name) return undefined;
+
+    // Check start/dev scripts for runtime flags
+    let runPrefix: string | undefined;
+    const scripts = pkg.scripts as Record<string, string> | undefined;
+    if (scripts) {
+      for (const key of ['start', 'dev']) {
+        if (scripts[key]) {
+          runPrefix = parseRunPrefix(scripts[key], entryRelative!, dir);
+          if (runPrefix) break;
+        }
+      }
+    }
+
+    return { entry: resolve(dir, entryRelative), name, runPrefix };
+  } catch {
+    // Invalid package.json
+  }
+
+  return undefined;
+}
+
+function isInPath(dir: string): boolean {
+  const pathEnv = process.env.PATH || '';
+  return pathEnv.split(':').includes(dir);
+}
+
+const PATH_BEGIN_MARKER = '###-begin-padrone-path-###';
+const PATH_END_MARKER = '###-end-padrone-path-###';
+
+function buildPathSnippet(shell: ShellType, binDir: string): string {
+  switch (shell) {
+    case 'fish':
+      return `${PATH_BEGIN_MARKER}\nfish_add_path "${binDir}"\n${PATH_END_MARKER}`;
+    case 'powershell':
+      return `${PATH_BEGIN_MARKER}\n$env:PATH = "${binDir}" + [IO.Path]::PathSeparator + $env:PATH\n${PATH_END_MARKER}`;
+    default:
+      return `${PATH_BEGIN_MARKER}\nexport PATH="${binDir}:$PATH"\n${PATH_END_MARKER}`;
+  }
+}
+
+function setupPath(shell: ShellType): { file: string; updated: boolean } {
+  const rcFile = getRcFile(shell);
+  if (!rcFile) {
+    throw new Error(`Could not determine config file for ${shell}.`);
+  }
+
+  const snippet = buildPathSnippet(shell, BIN_DIR);
+  return writeToRcFile(rcFile, snippet, PATH_BEGIN_MARKER, PATH_END_MARKER);
+}
+
+function detectRuntime(dir: string): string {
+  let current = dir;
+  while (true) {
+    if (existsSync(resolve(current, 'bun.lock')) || existsSync(resolve(current, 'bun.lockb'))) return 'bun';
+    if (
+      existsSync(resolve(current, 'package-lock.json')) ||
+      existsSync(resolve(current, 'yarn.lock')) ||
+      existsSync(resolve(current, 'pnpm-lock.yaml'))
+    )
+      return 'node';
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return 'node';
+}
+
+function createShim(name: string, entry: string, dir: string, runPrefix?: string) {
+  mkdirSync(BIN_DIR, { recursive: true });
+  const shimPath = resolve(BIN_DIR, sanitizeBinName(name));
+
+  const prefix = runPrefix ?? detectRuntime(dir);
+
+  const shim = ['#!/usr/bin/env sh', `# Linked by padrone — do not edit`, `${prefix} "${entry}" "$@"`, ''].join('\n');
+
+  writeFileSync(shimPath, shim);
+  chmodSync(shimPath, 0o755);
+}
+
+function removeShim(name: string) {
+  const shimPath = resolve(BIN_DIR, sanitizeBinName(name));
+  if (existsSync(shimPath)) {
+    rmSync(shimPath);
+  }
+}
+
+export async function runLink(args: LinkArgs, ctx: PadroneActionContext) {
+  const { output, error } = ctx.runtime;
+
+  if (args.list) {
+    const links = readLinks();
+    const entries = Object.values(links);
+    if (entries.length === 0) {
+      output('No linked programs.');
+      return;
+    }
+    output('Linked programs:');
+    for (const link of entries) {
+      output(`  ${link.name} → ${link.entry}`);
+    }
+    return;
+  }
+
+  const dir = process.cwd();
+
+  let entry: string;
+  let name: string;
+  let runPrefix: string | undefined;
+
+  const resolvedArg = args.entry ? resolve(dir, args.entry) : undefined;
+
+  // Determine the target directory: if a folder or package.json was passed, use that
+  let targetDir: string | undefined;
+  if (resolvedArg) {
+    if (existsSync(resolvedArg) && statSync(resolvedArg).isDirectory()) {
+      targetDir = resolvedArg;
+    } else if (basename(resolvedArg) === 'package.json' && existsSync(resolvedArg)) {
+      targetDir = dirname(resolvedArg);
+    }
+  }
+
+  if (targetDir || !resolvedArg) {
+    // Detect entry from the target directory's package.json
+    const detected = detectEntry(targetDir ?? dir);
+    if (!detected) {
+      error('Could not detect entry point. Provide an entry file or add a "bin" field to package.json.');
+      process.exit(1);
+    }
+    entry = detected.entry;
+    name = sanitizeBinName(args.name || detected.name);
+    runPrefix = detected.runPrefix;
+  } else {
+    // Explicit file path
+    entry = resolvedArg;
+    name = sanitizeBinName(args.name || basename(entry).replace(/\.[cm]?[jt]sx?$/, ''));
+  }
+
+  const GENERIC_NAMES = new Set(['cli', 'index', 'main', 'app', 'bin', 'start', 'src', 'run', 'server', 'program']);
+  if (GENERIC_NAMES.has(name)) {
+    error(`"${name}" is too generic to use as a command name. Use --name to specify one.`);
+    process.exit(1);
+  }
+
+  if (!existsSync(entry)) {
+    error(`Entry file not found: ${entry}`);
+    process.exit(1);
+  }
+
+  const entryDir = targetDir ?? (existsSync(resolve(dirname(entry), 'package.json')) ? dirname(entry) : dir);
+
+  createShim(name, entry, entryDir, runPrefix);
+
+  const links = readLinks();
+  links[name] = {
+    name,
+    entry,
+    dir: entryDir,
+    linkedAt: new Date().toISOString(),
+  };
+  writeLinks(links);
+
+  output(`Linked ${name} → ${entry}`);
+
+  if (!isInPath(BIN_DIR)) {
+    if (args.setup) {
+      const shell = detectShell();
+      if (!shell) {
+        error('Could not detect shell. Add the PATH manually:');
+        error(`  export PATH="${BIN_DIR}:$PATH"`);
+        return;
+      }
+      const result = setupPath(shell);
+      const verb = result.updated ? 'Updated' : 'Added';
+      output(`${verb} PATH in ${result.file}`);
+      output('Restart your shell or run:');
+      output(`  export PATH="${BIN_DIR}:$PATH"`);
+    } else {
+      output('');
+      output(`Add ${BIN_DIR} to your PATH to use "${name}" globally:`);
+      output(`  export PATH="${BIN_DIR}:$PATH"`);
+      output('Or re-run with --setup to do it automatically.');
+    }
+  }
+}
+
+export async function runUnlink(args: UnlinkArgs, ctx: PadroneActionContext) {
+  const { output, error } = ctx.runtime;
+  const links = readLinks();
+
+  let name = args.name ? sanitizeBinName(args.name) : undefined;
+
+  if (!name) {
+    const dir = process.cwd();
+    const detected = detectEntry(dir);
+    if (detected) {
+      name = sanitizeBinName(detected.name);
+    }
+  }
+
+  if (!name) {
+    error('Could not detect program name. Provide the name to unlink.');
+    process.exit(1);
+  }
+
+  if (!links[name]) {
+    error(`"${name}" is not linked.`);
+    process.exit(1);
+  }
+
+  removeShim(name);
+  delete links[name];
+  writeLinks(links);
+
+  output(`Unlinked ${name}`);
+}

package/src/cli/wrap.ts

@@ -0,0 +1,152 @@
+import { resolve } from 'node:path';
+import { createCodeBuilder, createFileEmitter, generateCommandTree } from 'padrone/codegen';
+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;
+}
+
+export async function runWrap(args: WrapArgs, ctx: PadroneActionContext) {
+  const { output, error } = ctx.runtime;
+  const command = args.command;
+  const sources: DiscoverySource[] = args.source ? [args.source] : ['help'];
+  const outDir = resolve(args.output || `./src/${command}`);
+
+  // Experimental warning — skip with -y
+  if (!args.yes) {
+    output('⚠ The `wrap` command is experimental. Generated code may require manual adjustments.');
+    output('');
+
+    if (ctx.runtime.prompt) {
+      const proceed = await ctx.runtime.prompt({
+        name: 'confirm',
+        message: 'Do you want to continue?',
+        type: 'confirm',
+        default: true,
+      });
+      if (!proceed) {
+        output('Aborted.');
+        return;
+      }
+      output('');
+    }
+  }
+
+  output(`Discovering ${command} CLI structure...`);
+
+  const result = await discoverCli({
+    command,
+    sources,
+    depth: args.depth,
+    log: {
+      info: (msg) => output(msg),
+      warn: (msg) => output(`  warn: ${msg}`),
+      error: (msg) => error(msg),
+      success: (msg) => output(msg),
+    },
+  });
+
+  // Error out if the root command returned nothing useful
+  const hasSubcommands = result.command.subcommands && result.command.subcommands.length > 0;
+  const hasArguments = result.command.arguments && result.command.arguments.length > 0;
+  if (!hasSubcommands && !hasArguments && !result.command.description) {
+    error(`Could not discover CLI structure for "${command}". Make sure the command exists and supports --help.`);
+    return;
+  }
+
+  if (result.warnings.length > 0) {
+    output('');
+    output('Warnings:');
+    for (const warn of result.warnings) {
+      output(`  - ${warn}`);
+    }
+  }
+
+  const subcommandCount = countSubcommands(result.command);
+  const optionCount = countOptions(result.command);
+
+  output('');
+  output(`Discovered: ${subcommandCount} commands, ${optionCount} options (${result.invocations} invocations)`);
+  output('');
+
+  // Generate the wrapper project
+  const emitter = createFileEmitter({
+    outDir,
+    header: `// Generated by \`padrone wrap ${command}\` — do not edit manually`,
+    overwrite: args.overwrite,
+    dryRun: args.dryRun,
+  });
+
+  const genCtx: GeneratorContext = {
+    outDir,
+    createCodeBuilder,
+    emitter,
+    template,
+    log: {
+      info: (msg) => output(msg),
+      warn: (msg) => output(`  warn: ${msg}`),
+      error: (msg) => error(msg),
+      success: (msg) => output(msg),
+    },
+  };
+
+  generateCommandTree(result.command, genCtx, { wrap: { command } });
+
+  const emitResult = await emitter.emit();
+
+  if (emitResult.errors.length > 0) {
+    for (const err of emitResult.errors) {
+      error(`Failed to write ${err.file}: ${err.error.message}`);
+    }
+    return;
+  }
+
+  if (args.dryRun) {
+    output('Dry run — files that would be written:');
+  } else {
+    output('Files written:');
+  }
+
+  for (const file of emitResult.written) {
+    output(`  ${file}`);
+  }
+
+  if (emitResult.skipped.length > 0) {
+    output('');
+    output('Skipped (already exist, use --overwrite to replace):');
+    for (const file of emitResult.skipped) {
+      output(`  ${file}`);
+    }
+  }
+}
+
+function countSubcommands(cmd: { subcommands?: { subcommands?: any[] }[] }): number {
+  let count = 0;
+  if (cmd.subcommands) {
+    count += cmd.subcommands.length;
+    for (const sub of cmd.subcommands) {
+      count += countSubcommands(sub);
+    }
+  }
+  return count;
+}
+
+function countOptions(cmd: { arguments?: unknown[]; subcommands?: any[] }): number {
+  let count = cmd.arguments?.length || 0;
+  if (cmd.subcommands) {
+    for (const sub of cmd.subcommands) {
+      count += countOptions(sub);
+    }
+  }
+  return count;
+}

package/src/codegen/README.md

@@ -0,0 +1,118 @@
+# padrone/codegen
+
+Code generation toolkit for Padrone CLI projects. Import from `padrone/codegen`.
+
+## Core Concepts
+
+All parsers produce `CommandMeta` / `FieldMeta` (intermediate representations). All generators consume them. This decouples input formats from output formats.
+
+## API Reference
+
+### Types
+
+- **`FieldMeta`** — Metadata for a single option/flag/argument: `name`, `type` (`string | number | boolean | array | enum | unknown`), `description`, `default`, `required`, `aliases`, `positional`, `enumValues`, `ambiguous`.
+- **`CommandMeta`** — Intermediate representation for a CLI command: `name`, `description`, `aliases`, `arguments` (named options), `positionals`, `subcommands` (recursive), `examples`, `deprecated`.
+- **`CodeBuilder`** — Fluent interface for building TypeScript source with `.import()`, `.importType()`, `.line()`, `.block()`, `.comment()`, `.raw()`, `.build()`.
+- **`FileEmitter`** — Multi-file output manager with `.addFile()` and `.emit()`.
+- **`GeneratorContext`** — Shared context for generators: `outDir`, `createCodeBuilder`, `emitter`, `template`, `log`.
+
+### Template Engine
+
+```ts
+import { template } from 'padrone/codegen'
+
+const render = template(`Hello, {{name}}!`)
+render({ name: 'world' }) // "Hello, world!"
+```
+
+Syntax: `{{var}}` interpolation, `{{#arr}}...{{/arr}}` iteration (`{{.}}` for current item), `{{#bool}}...{{/bool}}` conditionals, `{{>partial}}` partials.
+
+### CodeBuilder
+
+```ts
+import { createCodeBuilder } from 'padrone/codegen'
+
+const code = createCodeBuilder()
+  .import(['createPadrone'], 'padrone')
+  .import(['z'], 'zod/v4')
+  .line(`const program = createPadrone('my-cli')`)
+  .block('.configure({', (b) => b.line(`description: 'My CLI',`), '})')
+  .build()
+
+// code.text contains the formatted source
+// code.imports contains the deduped import map
+```
+
+### FileEmitter
+
+```ts
+import { createFileEmitter } from 'padrone/codegen'
+
+const emitter = createFileEmitter({
+  outDir: './output',
+  header: '// Auto-generated',
+  overwrite: false,  // skip existing files
+  dryRun: false,
+})
+
+emitter.addFile('src/index.ts', codeBuilder.build())
+emitter.addFile('package.json', jsonString)
+const result = await emitter.emit()
+// result: { written: string[], skipped: string[], errors: [] }
+```
+
+### Schema-to-Code
+
+```ts
+import { schemaToCode, fieldMetaToCode } from 'padrone/codegen'
+
+// Convert a Standard Schema (e.g. Zod) to Zod source code
+const result = schemaToCode(myZodSchema)
+// result: { code: 'z.object({ ... })', imports: ['z'] }
+
+// Convert FieldMeta[] to Zod z.object() source
+const result2 = fieldMetaToCode(fields)
+// result2: { code: 'z.object({ ... })', imports: ['z'] }
+```
+
+### Generators
+
+```ts
+import { generateCommandFile, generateCommandTree, generateBarrelFile } from 'padrone/codegen'
+
+// Generate a single command file from CommandMeta
+const builder = generateCommandFile(commandMeta, generatorCtx)
+
+// Walk a CommandMeta tree and emit one file per command + program.ts + index.ts
+generateCommandTree(rootCommandMeta, generatorCtx)
+
+// Generate a barrel (index.ts) re-exporting from given paths
+const barrelCode = generateBarrelFile(['./commands/hello', './commands/deploy'])
+```
+
+### Parsers
+
+```ts
+import { parseHelpOutput, parseFishCompletions, parseZshCompletions, mergeCommandMeta } from 'padrone/codegen'
+
+// Parse --help output (GNU, cobra, argparse, commander/yargs styles)
+const meta = parseHelpOutput(helpText, { name: 'my-tool' })
+
+// Parse fish shell completion scripts
+const meta2 = parseFishCompletions(fishScript)
+
+// Parse zsh _arguments completion definitions
+const meta3 = parseZshCompletions(zshScript)
+
+// Merge multiple CommandMeta from different sources (later sources take precedence unless ambiguous)
+const merged = mergeCommandMeta(meta, meta2, meta3)
+```
+
+## Typical Workflow
+
+1. **Parse** existing CLI help/completions into `CommandMeta` using parsers
+2. **Merge** multiple sources with `mergeCommandMeta()` for best coverage
+3. **Generate** Padrone source files with `generateCommandTree()` or `generateCommandFile()`
+4. **Emit** files to disk with `FileEmitter`
+
+Or use `template()` and `createFileEmitter()` directly for custom scaffolding (see `padrone init` implementation in `src/cli/init.ts`).