padrone 1.4.0 → 1.6.0

package/src/core/runtime.ts

@@ -0,0 +1,246 @@
+import type { ColorConfig, ColorTheme } from '../output/colorizer.ts';
+import type { HelpFormat } from '../output/formatter.ts';
+
+/** Process signals that Padrone can handle for graceful shutdown. */
+export type PadroneSignal = 'SIGINT' | 'SIGTERM' | 'SIGHUP';
+
+/** Value accepted by `PadroneProgressIndicator.update()`. */
+export type PadroneProgressUpdate = string | number | { message?: string; progress?: number; indeterminate?: boolean; time?: boolean };
+
+/**
+ * A progress indicator instance (spinner, progress bar, etc).
+ * Created by the runtime's `progress` factory and used to show loading state during command execution.
+ */
+export type PadroneProgressIndicator = {
+  /**
+   * Update the indicator.
+   * - `string` — update the displayed message.
+   * - `number` — set progress ratio (0–1). Values outside this range are clamped.
+   * - `{ message?, progress?, indeterminate? }` — update message, progress, or both.
+   *
+   * Set `indeterminate: true` to force the bar into indeterminate mode (shows animation, no percentage).
+   * This makes the bar visible even in `show: 'auto'` mode without providing a number.
+   * Omitting `progress` (or passing a string) leaves the bar in its current state.
+   * Setting `progress` when bar mode is not enabled is a no-op for the bar portion.
+   *
+   * Set `time: true` to start the elapsed timer on demand (useful when `time` was not set in options).
+   * Set `time: false` to hide the elapsed timer.
+   */
+  update: (value: PadroneProgressUpdate) => void;
+  /** Mark as succeeded and stop. Pass `null` to stop without rendering a final message. */
+  succeed: (message?: string | null, options?: { indicator?: string }) => void;
+  /** Mark as failed and stop. Pass `null` to stop without rendering a final message. */
+  fail: (message?: string | null, options?: { indicator?: string }) => void;
+  /** Stop without success/fail status. */
+  stop: () => void;
+  /** Temporarily hide the indicator so other output can be written cleanly. */
+  pause: () => void;
+  /** Redraw the indicator after a `pause()`. */
+  resume: () => void;
+};
+
+/** Controls when a progress element (spinner or bar) is visible. */
+export type PadroneProgressShow = 'auto' | 'always' | 'never';
+
+/** Built-in spinner presets. */
+export type PadroneSpinnerPreset = 'dots' | 'line' | 'arc' | 'bounce';
+
+/**
+ * Spinner configuration for progress indicators.
+ * - A preset name (e.g., `'dots'`) to use built-in frames.
+ * - `true` — default spinner with `show: 'always'` (visible even alongside a bar).
+ * - An object with custom `frames`, `interval`, and/or `show`.
+ * - `false` to disable the spinner (`show: 'never'`).
+ *
+ * Default `show` is `'auto'`: visible when the bar is not shown.
+ */
+export type PadroneSpinnerConfig = PadroneSpinnerPreset | boolean | { frames?: string[]; interval?: number; show?: PadroneProgressShow };
+
+/**
+ * Options passed to the runtime's `progress` factory.
+ */
+/** Common fill/empty character pairs for progress bars. */
+export type PadroneBarChar = '█' | '░' | '▓' | '▒' | '─' | '━' | '■' | '□' | '#' | '-' | '=' | '·' | '▰' | '▱' | (string & {});
+
+/**
+ * Built-in indeterminate bar animation presets.
+ * - `'bounce'` — a filled segment slides back and forth (default).
+ * - `'slide'` — a filled segment slides left-to-right and wraps around.
+ * - `'pulse'` — the entire bar fades in and out using gradient characters (`░▒▓█▓▒░`).
+ */
+export type PadroneBarAnimation = 'bounce' | 'slide' | 'pulse';
+
+/**
+ * Progress bar configuration.
+ */
+export type PadroneBarConfig = {
+  /** Total width of the bar in characters. Defaults to `20`. */
+  width?: number;
+  /** Character used for the filled portion of the bar. Defaults to `'█'`. */
+  filled?: PadroneBarChar;
+  /** Character used for the empty portion of the bar. Defaults to `'░'`. */
+  empty?: PadroneBarChar;
+  /** Indeterminate animation style. Defaults to `'bounce'`. */
+  animation?: PadroneBarAnimation;
+  /**
+   * When the bar is visible. Defaults to `'always'` when bar is enabled, `'auto'` when bar is not explicitly configured.
+   * - `'always'` — bar is always shown (indeterminate until a number is provided).
+   * - `'auto'` — bar is shown only after `update()` is called with a number.
+   * - `'never'` — bar is never shown.
+   */
+  show?: PadroneProgressShow;
+};
+
+export type PadroneProgressOptions = {
+  spinner?: PadroneSpinnerConfig;
+  /** Enable a progress bar. `true` for defaults (`show: 'always'`), or a `PadroneBarConfig` object. `false` to disable entirely. When omitted, bar defaults to `show: 'auto'` (appears when a number is provided). */
+  bar?: boolean | PadroneBarConfig;
+  /** Show elapsed time since the indicator started. Defaults to `false`. */
+  time?: boolean;
+  /** Show estimated time remaining based on progress rate. Requires numeric `update()` calls. Defaults to `false`. */
+  eta?: boolean;
+  /** Character/string shown before the success message. Defaults to `'✔'`. */
+  successIndicator?: string;
+  /** Character/string shown before the error message. Defaults to `'✖'`. */
+  errorIndicator?: string;
+};
+
+/**
+ * Controls interactive prompting capability and default behavior at the runtime level.
+ * - `'supported'` — capable; caller decides.
+ * - `'unsupported'` — hard veto; nothing can override.
+ * - `'forced'` — capable and forces prompts by default.
+ * - `'disabled'` — capable but suppresses prompts by default.
+ */
+export type InteractiveMode = 'supported' | 'unsupported' | 'forced' | 'disabled';
+
+/**
+ * Configuration passed to the runtime's `prompt` function for interactive field prompting.
+ * The prompt type and choices are auto-detected from the field's JSON schema.
+ */
+export type InteractivePromptConfig = {
+  /** The field name being prompted. */
+  name: string;
+  /** Human-readable message/label for the prompt, derived from the field's description or name. */
+  message: string;
+  /** The prompt type, auto-detected from the JSON schema. */
+  type: 'input' | 'confirm' | 'select' | 'multiselect' | 'password';
+  /** Available choices for select/multiselect prompts. */
+  choices?: { label: string; value: unknown }[];
+  /** Default value from the schema. */
+  default?: unknown;
+};
+
+/**
+ * Defines the execution context for a Padrone program.
+ * Abstracts all environment-dependent I/O so the CLI framework
+ * can run outside of a terminal (e.g., web UIs, chat interfaces, testing).
+ *
+ * All fields are optional — unspecified fields fall back to the Node.js/Bun defaults.
+ */
+export type PadroneRuntime = {
+  /** Write normal output (replaces console.log). Receives the raw value — runtime handles formatting. */
+  output?: (...args: unknown[]) => void;
+  /** Write error output (replaces console.error). */
+  error?: (text: string) => void;
+  /** Return the raw CLI arguments (replaces process.argv.slice(2)). */
+  argv?: () => string[];
+  /** Return environment variables (replaces process.env). */
+  env?: () => Record<string, string | undefined>;
+  /** Default help output format. */
+  format?: HelpFormat | 'auto';
+  /** Color theme for ANSI/console help output. A theme name or partial color config. */
+  theme?: ColorTheme | ColorConfig;
+  /**
+   * Standard input abstraction. Provides methods to read piped data from stdin.
+   * When not provided, defaults to reading from `process.stdin`.
+   *
+   * Used by commands that declare a `stdin` field in their arguments meta.
+   * The framework reads stdin automatically during the validate phase and
+   * injects the data into the specified argument field.
+   */
+  stdin?: {
+    /** Whether stdin is a TTY (interactive terminal) vs a pipe/file. */
+    isTTY?: boolean;
+    /** Read all of stdin as a string. */
+    text: () => Promise<string>;
+    /** Async iterable of lines for streaming. */
+    lines: () => AsyncIterable<string>;
+  };
+  /**
+   * Controls interactive prompting capability and default behavior.
+   * - `'supported'` — runtime can handle prompts; caller (flag/pref) decides whether to prompt. This is the default when `prompt` is provided.
+   * - `'unsupported'` — runtime cannot handle prompts; hard veto that nothing can override.
+   * - `'forced'` — runtime supports prompts and forces them by default (prompts even for provided values).
+   * - `'disabled'` — runtime supports prompts but suppresses them by default.
+   *
+   * `'unsupported'` is the only immutable state. For the others, the `--interactive`/`-i` flag
+   * and `cli()` preferences can override the default behavior.
+   */
+  interactive?: InteractiveMode;
+  /**
+   * Prompt the user for input. Called during `cli()` for fields marked as interactive.
+   * When `interactive` is `true` and this is not provided, defaults to an Enquirer-based terminal prompt.
+   */
+  prompt?: (config: InteractivePromptConfig) => Promise<unknown>;
+  /**
+   * Read a line of input from the user. Used by `repl()` for custom runtimes
+   * (web UIs, chat interfaces, testing).
+   * Returns the input string, `null` on EOF (e.g. Ctrl+D, closed connection),
+   * or `REPL_SIGINT` when the user presses Ctrl+C.
+   *
+   * When not provided, `repl()` uses a built-in Node.js readline session
+   * with command history (up/down arrows) and tab completion.
+   */
+  readLine?: (prompt: string) => Promise<string | typeof REPL_SIGINT | null>;
+
+  /**
+   * Register a callback for process signals. Returns an unsubscribe function.
+   * The default runtime wires this to `process.on('SIGINT' | 'SIGTERM' | 'SIGHUP')`.
+   * Non-Node runtimes (web UIs, tests) can map their own cancellation semantics.
+   *
+   * When not provided, signal handling is disabled for this runtime.
+   */
+  onSignal?: (callback: (signal: PadroneSignal) => void) => () => void;
+
+  /**
+   * Terminal/output capabilities. Used for ANSI detection, text wrapping, and TTY checks.
+   * The default runtime auto-detects from `process.stdout`. Non-terminal runtimes
+   * (web UIs, tests) should provide explicit values.
+   */
+  terminal?: {
+    /** Number of columns in the terminal. Used for text wrapping. */
+    columns?: number;
+    /** Whether stdout is a TTY. Affects ANSI color output and interactive features. */
+    isTTY?: boolean;
+  };
+
+  /**
+   * Force-exit the process. The default runtime wires this to `process.exit()`.
+   * Non-Node runtimes can throw an error or no-op.
+   */
+  exit?: (code: number) => never;
+};
+
+/**
+ * Internal resolved runtime where all fields are guaranteed to be present.
+ * The `prompt`, `interactive`, and `readLine` fields remain optional since not all runtimes provide them.
+ */
+export type ResolvedPadroneRuntime = Required<
+  Omit<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin' | 'theme' | 'onSignal' | 'terminal' | 'exit'>
+> &
+  Pick<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin' | 'theme' | 'onSignal' | 'terminal' | 'exit'>;
+
+/**
+ * Sentinel value returned by the terminal REPL session when Ctrl+C is pressed.
+ * Distinguished from empty string (user pressed enter) and null (EOF/Ctrl+D).
+ */
+export const REPL_SIGINT = Symbol('REPL_SIGINT');
+
+/**
+ * Internal session config for the REPL's persistent readline interface.
+ */
+export type ReplSessionConfig = {
+  completer?: (line: string) => [string[], string];
+  history?: string[];
+};

package/src/core/validate.ts

@@ -0,0 +1,247 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { AnyPadroneCommand, InterceptorValidateResult } from '../types/index.ts';
+import { coerceArgs, detectUnknownArgs, extractSchemaMetadata, getJsonSchema, parsePositionalConfig, preprocessArgs } from './args.ts';
+import { getCommandRuntime } from './commands.ts';
+import { getNestedValue, parseCliInputToParts, setNestedValue } from './parse.ts';
+import { thenMaybe } from './results.ts';
+
+/**
+ * Parses CLI input to find the command and extract raw arguments without validation.
+ */
+export function parseCommand(input: string | undefined, rootCommand: AnyPadroneCommand, findCommandByName: FindCommandFn) {
+  input ??= getCommandRuntime(rootCommand).argv().join(' ') || undefined;
+  if (!input) {
+    const defaultCommand = findCommandByName('', rootCommand.commands);
+    if (defaultCommand) {
+      return { command: defaultCommand, rawArgs: {} as Record<string, unknown>, args: [] as string[], unmatchedTerms: [] as string[] };
+    }
+    return { command: rootCommand, rawArgs: {} as Record<string, unknown>, args: [] as string[], unmatchedTerms: [] as string[] };
+  }
+
+  const parts = parseCliInputToParts(input);
+
+  const terms = parts.filter((p) => p.type === 'term').map((p) => p.value);
+  const argTokens = parts.filter((p) => p.type === 'arg').map((p) => p.value);
+
+  let curCommand: AnyPadroneCommand | undefined = rootCommand;
+  let unmatchedTerms: string[] = [];
+
+  if (terms[0] === rootCommand.name) terms.shift();
+
+  for (let i = 0; i < terms.length; i++) {
+    const term = terms[i] || '';
+    const found = findCommandByName(term, curCommand.commands);
+
+    if (found) {
+      curCommand = found;
+    } else {
+      unmatchedTerms = terms.slice(i);
+      argTokens.unshift(...unmatchedTerms);
+      break;
+    }
+  }
+
+  if (unmatchedTerms.length === 0 && curCommand.commands?.length) {
+    const defaultCommand = findCommandByName('', curCommand.commands);
+    if (defaultCommand) curCommand = defaultCommand;
+  }
+
+  if (!curCommand) return { command: rootCommand, rawArgs: {} as Record<string, unknown>, args: argTokens, unmatchedTerms };
+
+  const argsMeta = curCommand.meta?.fields;
+  const schemaMetadata = curCommand.argsSchema
+    ? extractSchemaMetadata(curCommand.argsSchema, argsMeta, curCommand.meta?.autoAlias)
+    : { flags: {}, aliases: {} };
+  const { flags, aliases } = schemaMetadata;
+
+  const arrayArguments = new Set<string>();
+  if (curCommand.argsSchema) {
+    try {
+      const jsonSchema = getJsonSchema(curCommand.argsSchema) as Record<string, any>;
+      if (jsonSchema.type === 'object' && jsonSchema.properties) {
+        for (const [key, prop] of Object.entries(jsonSchema.properties as Record<string, any>)) {
+          if (prop?.type === 'array') arrayArguments.add(key);
+        }
+      }
+    } catch {
+      // Ignore schema parsing errors
+    }
+  }
+
+  const argParts = parts.filter((p) => p.type === 'named' || p.type === 'alias');
+  const rawArgs: Record<string, unknown> = {};
+
+  for (const arg of argParts) {
+    let key: string[];
+    if (arg.type === 'alias' && arg.key.length === 1 && flags[arg.key[0]!]) {
+      key = [flags[arg.key[0]!]!];
+    } else if (arg.type === 'named' && arg.key.length === 1 && aliases[arg.key[0]!]) {
+      key = [aliases[arg.key[0]!]!];
+    } else {
+      key = arg.key;
+    }
+
+    const rootKey = key[0]!;
+
+    if (arg.type === 'named' && arg.negated) {
+      setNestedValue(rawArgs, key, false);
+      continue;
+    }
+
+    const value = arg.value ?? true;
+
+    if (arrayArguments.has(rootKey)) {
+      const existing = getNestedValue(rawArgs, key);
+      if (existing !== undefined) {
+        if (Array.isArray(existing)) {
+          if (Array.isArray(value)) existing.push(...value);
+          else existing.push(value);
+        } else {
+          if (Array.isArray(value)) setNestedValue(rawArgs, key, [existing, ...value]);
+          else setNestedValue(rawArgs, key, [existing, value]);
+        }
+      } else {
+        setNestedValue(rawArgs, key, Array.isArray(value) ? value : [value]);
+      }
+    } else {
+      const existing = getNestedValue(rawArgs, key);
+      if (existing !== undefined) {
+        if (Array.isArray(existing)) {
+          if (Array.isArray(value)) existing.push(...value);
+          else existing.push(value);
+        } else {
+          if (Array.isArray(value)) setNestedValue(rawArgs, key, [existing, ...value]);
+          else setNestedValue(rawArgs, key, [existing, value]);
+        }
+      } else {
+        setNestedValue(rawArgs, key, value);
+      }
+    }
+  }
+
+  return { command: curCommand, rawArgs, args: argTokens, unmatchedTerms };
+}
+
+type FindCommandFn = (name: string, commands?: AnyPadroneCommand[]) => AnyPadroneCommand | undefined;
+
+/**
+ * Preprocesses raw arguments: maps positional arguments and performs auto-coercion.
+ * External data sources (stdin, env, config) are handled by extensions before this runs.
+ */
+export function buildCommandArgs(
+  command: AnyPadroneCommand,
+  rawArgs: Record<string, unknown>,
+  positionalArgs: string[],
+): Record<string, unknown> {
+  let preprocessedArgs = preprocessArgs(rawArgs, { flags: {}, aliases: {} });
+
+  const positionalConfig = command.meta?.positional ? parsePositionalConfig(command.meta.positional) : [];
+
+  if (positionalConfig.length > 0) {
+    let argIndex = 0;
+    for (let i = 0; i < positionalConfig.length; i++) {
+      const { name, variadic } = positionalConfig[i]!;
+      if (argIndex >= positionalArgs.length) break;
+
+      if (variadic) {
+        const remainingPositionals = positionalConfig.slice(i + 1);
+        const nonVariadicAfter = remainingPositionals.filter((p) => !p.variadic).length;
+        const variadicEnd = positionalArgs.length - nonVariadicAfter;
+        preprocessedArgs[name] = positionalArgs.slice(argIndex, variadicEnd);
+        argIndex = variadicEnd;
+      } else if (i === positionalConfig.length - 1 && positionalArgs.length > argIndex + 1) {
+        preprocessedArgs[name] = positionalArgs.slice(argIndex).join(' ');
+        argIndex = positionalArgs.length;
+      } else {
+        preprocessedArgs[name] = positionalArgs[argIndex];
+        argIndex++;
+      }
+    }
+  }
+
+  if (command.argsSchema) {
+    preprocessedArgs = coerceArgs(preprocessedArgs, command.argsSchema);
+  }
+
+  return preprocessedArgs;
+}
+
+/**
+ * Detects unknown options in args that aren't defined in the schema.
+ * Returns unknown key info with suggestions, or empty array if schema is loose.
+ */
+export function checkUnknownArgs(command: AnyPadroneCommand, preprocessedArgs: Record<string, unknown>): { key: string }[] {
+  if (!command.argsSchema) {
+    const unknowns: { key: string }[] = [];
+    for (const key of Object.keys(preprocessedArgs)) {
+      unknowns.push({ key });
+    }
+    return unknowns;
+  }
+
+  const argsMeta = command.meta?.fields;
+  const { flags, aliases } = extractSchemaMetadata(command.argsSchema, argsMeta, command.meta?.autoAlias);
+
+  return detectUnknownArgs(preprocessedArgs, command.argsSchema, flags, aliases);
+}
+
+/**
+ * Validates preprocessed arguments against the command's schema.
+ * First checks for unknown args (strict by default), then runs schema validation.
+ * Returns sync or async result depending on the schema's validate method.
+ */
+export function validateCommandArgs(command: AnyPadroneCommand, preprocessedArgs: Record<string, unknown>) {
+  const unknownArgs = checkUnknownArgs(command, preprocessedArgs);
+  if (unknownArgs.length > 0) {
+    const issues: StandardSchemaV1.Issue[] = unknownArgs.map(({ key }) => ({
+      path: [key],
+      message: `Unknown option: "${key}"`,
+    }));
+    return { args: undefined, argsResult: { issues } as any };
+  }
+
+  const argsParsed = command.argsSchema ? command.argsSchema['~standard'].validate(preprocessedArgs) : { value: {} };
+
+  const buildResult = (parsed: StandardSchemaV1.Result<unknown>) => ({
+    args: parsed.issues ? undefined : (parsed.value as any),
+    argsResult: parsed as any,
+  });
+
+  return thenMaybe(argsParsed, buildResult);
+}
+
+/**
+ * Returns the list of known option names from a command's schema (for fuzzy suggestion).
+ */
+export function getKnownOptionNames(command: AnyPadroneCommand): string[] {
+  if (!command.argsSchema) return [];
+  try {
+    const js = getJsonSchema(command.argsSchema) as Record<string, any>;
+    if (js.type === 'object' && js.properties) return Object.keys(js.properties);
+  } catch {
+    /* ignore */
+  }
+  return [];
+}
+
+/**
+ * Formats validation issue messages for display.
+ */
+export function formatIssueMessages(issues: readonly StandardSchemaV1.Issue[]): string {
+  return issues.map((i) => `  - ${i.path?.join('.') || 'root'}: ${i.message}`).join('\n');
+}
+
+/**
+ * Core validate function for parse() — preprocesses and validates CLI args.
+ * Used by the parse program method (lighter weight than the full exec pipeline).
+ * External data sources (stdin, env, config) are not resolved here — use eval() for that.
+ */
+export function coreValidateForParse(
+  command: AnyPadroneCommand,
+  rawArgs: Record<string, unknown>,
+  positionalArgs: string[],
+): InterceptorValidateResult | Promise<InterceptorValidateResult> {
+  const preprocessedArgs = buildCommandArgs(command, rawArgs, positionalArgs);
+  const validated = validateCommandArgs(command, preprocessedArgs);
+  return thenMaybe(validated, (v) => v as InterceptorValidateResult);
+}

package/src/docs/index.ts

@@ -1,9 +1,9 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { commandSymbol } from '../command-utils.ts';
-import type { HelpArgumentInfo, HelpInfo, HelpPositionalInfo, HelpSubcommandInfo } from '../formatter.ts';
-import { getHelpInfo } from '../help.ts';
-import type { AnyPadroneCommand } from '../types.ts';
+import { getCommand } from '../core/commands.ts';
+import type { HelpArgumentInfo, HelpInfo, HelpPositionalInfo, HelpSubcommandInfo } from '../output/formatter.ts';
+import { getHelpInfo } from '../output/help.ts';
+import type { AnyPadroneCommand } from '../types/index.ts';
 
 // ============================================================================
 // Types
@@ -220,6 +220,18 @@ function generateMarkdownPage(info: HelpInfo, depth: number, frontmatterFn?: Doc
   lines.push('```');
   lines.push('');
 
+  // Examples
+  if (info.examples?.length) {
+    lines.push('## Examples');
+    lines.push('');
+    lines.push('```');
+    for (const ex of info.examples) {
+      lines.push(`$ ${ex}`);
+    }
+    lines.push('```');
+    lines.push('');
+  }
+
   // Subcommands
   if (info.subcommands?.length) {
     const visibleSubs = info.subcommands.filter((s) => !s.hidden);
@@ -307,6 +319,12 @@ function generateHtmlPage(info: HelpInfo, depth: number): string {
   sections.push('  <h2>Usage</h2>');
   sections.push(`  <pre><code>${escapeHtml(usageParts.join(' '))}</code></pre>`);
 
+  // Examples
+  if (info.examples?.length) {
+    sections.push('  <h2>Examples</h2>');
+    sections.push(`  <pre><code>${info.examples.map((ex) => `$ ${escapeHtml(ex)}`).join('\n')}</code></pre>`);
+  }
+
   // Subcommands
   if (info.subcommands?.length) {
     const visibleSubs = info.subcommands.filter((s) => !s.hidden);
@@ -381,7 +399,7 @@ function generateHtmlPage(info: HelpInfo, depth: number): string {
 }
 
 // ============================================================================
-// Man Page Generator
+// Man Page Generator (experimental)
 // ============================================================================
 
 function escapeMan(text: string): string {
@@ -418,6 +436,15 @@ function generateManPage(info: HelpInfo, _depth: number, programName: string): s
     lines.push(escapeMan(info.description));
   }
 
+  // EXAMPLES
+  if (info.examples?.length) {
+    lines.push('.SH EXAMPLES');
+    for (const ex of info.examples) {
+      lines.push('.PP');
+      lines.push(`.nf\n$ ${escapeMan(ex)}\n.fi`);
+    }
+  }
+
   // COMMANDS
   if (info.subcommands?.length) {
     const visibleSubs = info.subcommands.filter((s) => !s.hidden);
@@ -517,11 +544,6 @@ function generateMarkdownIndex(rootInfo: HelpInfo, allInfos: HelpInfo[]): string
 // Main Entry Point
 // ============================================================================
 
-function resolveCommand(programOrCommand: object): AnyPadroneCommand {
-  if (commandSymbol in programOrCommand) return (programOrCommand as any)[commandSymbol] as AnyPadroneCommand;
-  return programOrCommand as AnyPadroneCommand;
-}
-
 /**
  * Generate documentation for a Padrone CLI program or command tree.
  * Accepts either a PadroneProgram (from createPadrone()) or a raw AnyPadroneCommand.
@@ -529,7 +551,7 @@ function resolveCommand(programOrCommand: object): AnyPadroneCommand {
 export function generateDocs(program: object, options: DocsOptions = {}): DocsResult {
   const { format = 'markdown', output, includeHidden = false, frontmatter, overwrite = true, dryRun = false } = options;
 
-  const cmd = resolveCommand(program);
+  const cmd = getCommand(program);
   const allInfos = collectAllHelpInfo(cmd, includeHidden);
   const rootInfo = allInfos[0]!;
   const programName = cmd.name || 'program';
@@ -605,3 +627,94 @@ export function generateDocs(program: object, options: DocsOptions = {}): DocsRe
 
   return result;
 }
+
+// ============================================================================
+// Man Page Installation
+// ============================================================================
+
+export type SetupManPagesResult = {
+  /** Directory where man pages were written. */
+  dir: string;
+  /** Man page files that were written. */
+  written: string[];
+  /** Whether existing pages were overwritten (true) or newly created (false). */
+  updated: boolean;
+};
+
+/**
+ * Returns the local man page directory for the given section.
+ * Uses `~/.local/share/man/man<section>` (XDG convention).
+ */
+async function getManPageDir(section = 1): Promise<string> {
+  const { homedir } = await import('node:os');
+  return join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'man', `man${section}`);
+}
+
+/**
+ * Converts a command name to a man page filename.
+ * "myapp" → "myapp.1", "myapp deploy" → "myapp-deploy.1"
+ */
+function manPageFilename(commandName: string, section = 1): string {
+  return `${commandName.replace(/\s+/g, '-')}.${section}`;
+}
+
+/**
+ * Installs man pages for a Padrone CLI program into the local man directory.
+ * Generates man pages for all commands and writes them to `~/.local/share/man/man1/`.
+ *
+ * After installation, `man <program>` and `man <program>-<subcommand>` should work
+ * (assuming `~/.local/share/man` is in `MANPATH` or `manpath` picks it up).
+ */
+export async function setupManPages(program: object): Promise<SetupManPagesResult> {
+  const cmd = getCommand(program);
+  const allInfos = collectAllHelpInfo(cmd, false);
+  const programName = cmd.name || 'program';
+  const manDir = await getManPageDir(1);
+
+  mkdirSync(manDir, { recursive: true });
+
+  const written: string[] = [];
+  let updated = false;
+
+  for (let i = 0; i < allInfos.length; i++) {
+    const info = allInfos[i]!;
+    const depth = i === 0 ? 0 : info.name.split(/\s+/).length;
+    const commandName = info.name === '<root>' || !info.name ? programName : info.name;
+    const filename = manPageFilename(commandName);
+    const fullPath = join(manDir, filename);
+
+    if (existsSync(fullPath)) updated = true;
+
+    const content = generateManPage(info, depth, programName);
+    writeFileSync(fullPath, content, 'utf-8');
+    written.push(filename);
+  }
+
+  return { dir: manDir, written, updated };
+}
+
+/**
+ * Removes installed man pages for a Padrone CLI program.
+ */
+export async function removeManPages(program: object): Promise<{ dir: string; removed: string[] }> {
+  const { unlinkSync } = await import('node:fs');
+  const cmd = getCommand(program);
+  const allInfos = collectAllHelpInfo(cmd, false);
+  const programName = cmd.name || 'program';
+  const manDir = await getManPageDir(1);
+  const removed: string[] = [];
+
+  for (let i = 0; i < allInfos.length; i++) {
+    const info = allInfos[i]!;
+    const commandName = info.name === '<root>' || !info.name ? programName : info.name;
+    const filename = manPageFilename(commandName);
+    const fullPath = join(manDir, filename);
+
+    if (existsSync(fullPath)) {
+      unlinkSync(fullPath);
+      removed.push(filename);
+    }
+  }
+
+  return { dir: manDir, removed };
+}