padrone 1.0.0-beta.2

package/src/help.ts

@@ -0,0 +1,227 @@
+import type { StandardJSONSchemaV1 } from '@standard-schema/spec';
+import { createFormatter, type HelpArgumentInfo, type HelpDetail, type HelpFormat, type HelpInfo, type HelpOptionInfo } from './formatter';
+import { extractSchemaMetadata, type PadroneMeta, parsePositionalConfig } from './options';
+import type { AnyPadroneCommand } from './types';
+import { getRootCommand } from './utils';
+
+export type HelpOptions = {
+  format?: HelpFormat | 'auto';
+  detail?: HelpDetail;
+};
+
+/**
+ * Extract positional arguments info from schema based on meta.positional config.
+ */
+function extractPositionalArgsInfo(
+  schema: StandardJSONSchemaV1,
+  meta?: PadroneMeta,
+): { args: HelpArgumentInfo[]; positionalNames: Set<string> } {
+  const args: HelpArgumentInfo[] = [];
+  const positionalNames = new Set<string>();
+
+  if (!schema || !meta?.positional || meta.positional.length === 0) {
+    return { args, positionalNames };
+  }
+
+  const positionalConfig = parsePositionalConfig(meta.positional);
+
+  try {
+    const jsonSchema = schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+
+    if (jsonSchema.type === 'object' && jsonSchema.properties) {
+      const properties = jsonSchema.properties as Record<string, any>;
+      const required = (jsonSchema.required as string[]) || [];
+
+      for (const { name, variadic } of positionalConfig) {
+        const prop = properties[name];
+        if (!prop) continue;
+
+        positionalNames.add(name);
+        const optMeta = meta.options?.[name];
+
+        args.push({
+          name: variadic ? `...${name}` : name,
+          description: optMeta?.description ?? prop.description,
+          optional: !required.includes(name),
+          default: prop.default,
+          type: variadic ? `array<${prop.items?.type || 'string'}>` : prop.type,
+        });
+      }
+    }
+  } catch {
+    // Fallback to empty result if toJSONSchema fails
+  }
+
+  return { args, positionalNames };
+}
+
+function extractOptionsInfo(schema: StandardJSONSchemaV1, meta?: PadroneMeta, positionalNames?: Set<string>) {
+  const result: HelpOptionInfo[] = [];
+  if (!schema) return result;
+
+  const vendor = schema['~standard'].vendor;
+  if (!vendor.includes('zod')) return result;
+
+  const optionsMeta = meta?.options;
+
+  try {
+    const jsonSchema = schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+
+    // Handle object: z.object({ key: z.string(), ... })
+    if (jsonSchema.type === 'object' && jsonSchema.properties) {
+      const properties = jsonSchema.properties as Record<string, any>;
+      const required = (jsonSchema.required as string[]) || [];
+      const propertyNames = new Set(Object.keys(properties));
+
+      // Helper to check if a negated version of an option exists
+      const hasExplicitNegation = (key: string): boolean => {
+        // Check for noVerbose style (camelCase)
+        const camelNegated = `no${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+        if (propertyNames.has(camelNegated)) return true;
+        // Check for no-verbose style (kebab-case, though rare in JS)
+        const kebabNegated = `no-${key}`;
+        if (propertyNames.has(kebabNegated)) return true;
+        return false;
+      };
+
+      // Helper to check if this option is itself a negation of another option
+      const isNegationOf = (key: string): boolean => {
+        // Check for noVerbose -> verbose (camelCase)
+        if (key.startsWith('no') && key.length > 2 && key[2] === key[2]?.toUpperCase()) {
+          const positiveKey = key.charAt(2).toLowerCase() + key.slice(3);
+          if (propertyNames.has(positiveKey)) return true;
+        }
+        // Check for no-verbose -> verbose (kebab-case)
+        if (key.startsWith('no-')) {
+          const positiveKey = key.slice(3);
+          if (propertyNames.has(positiveKey)) return true;
+        }
+        return false;
+      };
+
+      for (const [key, prop] of Object.entries(properties)) {
+        // Skip positional arguments - they are shown in arguments section
+        if (positionalNames?.has(key)) continue;
+
+        const isOptional = !required.includes(key);
+        const enumValues = prop.enum as string[] | undefined;
+        const optMeta = optionsMeta?.[key];
+        const propType = prop.type as string;
+
+        // Booleans are negatable unless there's an explicit noOption property
+        // or this option is itself a negation of another option
+        const isNegatable = propType === 'boolean' && !hasExplicitNegation(key) && !isNegationOf(key);
+
+        result.push({
+          name: key,
+          description: optMeta?.description ?? prop.description,
+          optional: isOptional,
+          default: prop.default,
+          type: propType,
+          enum: enumValues,
+          deprecated: optMeta?.deprecated ?? prop?.deprecated,
+          hidden: optMeta?.hidden ?? prop?.hidden,
+          examples: optMeta?.examples ?? prop?.examples,
+          env: optMeta?.env ?? prop?.env,
+          variadic: propType === 'array', // Arrays are always variadic
+          negatable: isNegatable,
+          configKey: optMeta?.configKey ?? prop?.configKey,
+        });
+      }
+    }
+  } catch {
+    // Fallback to empty result if toJSONSchema fails
+  }
+
+  return result;
+}
+
+// ============================================================================
+// Core Help Info Builder
+// ============================================================================
+
+/**
+ * Builds a comprehensive HelpInfo structure from a command.
+ * This is the single source of truth that all formatters use.
+ * @param cmd - The command to build help info for
+ * @param detail - The level of detail ('minimal', 'standard', or 'full')
+ */
+function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpOptions['detail'] = 'standard'): HelpInfo {
+  const rootCmd = getRootCommand(cmd);
+  const commandName = cmd.path || cmd.name || 'program';
+
+  // Extract positional args from options schema based on meta.positional
+  const { args: positionalArgs, positionalNames } = cmd.options
+    ? extractPositionalArgsInfo(cmd.options, cmd.meta)
+    : { args: [], positionalNames: new Set<string>() };
+
+  const hasArguments = positionalArgs.length > 0;
+
+  const helpInfo: HelpInfo = {
+    name: commandName,
+    title: cmd.title,
+    description: cmd.description,
+    deprecated: cmd.deprecated,
+    hidden: cmd.hidden,
+    usage: {
+      command: rootCmd === cmd ? commandName : `${rootCmd.name} ${commandName}`,
+      hasSubcommands: !!(cmd.commands && cmd.commands.length > 0),
+      hasArguments,
+      hasOptions: !!cmd.options,
+    },
+  };
+
+  // Build subcommands info (filter out hidden commands unless showing full detail)
+  if (cmd.commands && cmd.commands.length > 0) {
+    const visibleCommands = detail === 'full' ? cmd.commands : cmd.commands.filter((c) => !c.hidden);
+    helpInfo.subcommands = visibleCommands.map((c) => ({
+      name: c.name,
+      title: c.title,
+      description: c.description,
+      deprecated: c.deprecated,
+      hidden: c.hidden,
+    }));
+
+    // In 'full' detail mode, recursively build help for all nested commands
+    if (detail === 'full') {
+      helpInfo.nestedCommands = visibleCommands.map((c) => getHelpInfo(c, 'full'));
+    }
+  }
+
+  // Build arguments info from positional options
+  if (hasArguments) {
+    helpInfo.arguments = positionalArgs;
+  }
+
+  // Build options info with aliases (excluding positional args)
+  if (cmd.options) {
+    const optionsInfo = extractOptionsInfo(cmd.options, cmd.meta, positionalNames);
+    const optMap: Record<string, HelpOptionInfo> = Object.fromEntries(optionsInfo.map((opt) => [opt.name, opt]));
+
+    // Merge aliases into options
+    const { aliases } = extractSchemaMetadata(cmd.options, cmd.meta?.options);
+    for (const [alias, name] of Object.entries(aliases)) {
+      const opt = optMap[name];
+      if (!opt) continue;
+      opt.aliases = [...(opt.aliases || []), alias];
+    }
+
+    // Filter out hidden options
+    const visibleOptions = optionsInfo.filter((opt) => !opt.hidden);
+    if (visibleOptions.length > 0) {
+      helpInfo.options = visibleOptions;
+    }
+  }
+
+  return helpInfo;
+}
+
+// ============================================================================
+// Main Entry Point
+// ============================================================================
+
+export function generateHelp(rootCommand: AnyPadroneCommand, commandObj: AnyPadroneCommand = rootCommand, options?: HelpOptions): string {
+  const helpInfo = getHelpInfo(commandObj, options?.detail);
+  const formatter = createFormatter(options?.format ?? 'auto', options?.detail);
+  return formatter.format(helpInfo);
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+import { createPadroneCommandBuilder } from './create';
+import type { PadroneCommand, PadroneProgram } from './types';
+
+export function createPadrone(name: string): PadroneProgram {
+  return createPadroneCommandBuilder({ name, path: '', commands: [] } as PadroneCommand) as PadroneProgram;
+}
+
+export type { HelpArgumentInfo, HelpFormat, HelpInfo, HelpOptionInfo, HelpSubcommandInfo } from './formatter';
+export type { HelpOptions } from './help';
+export type { PadroneOptionsMeta } from './options';
+// Re-export types for consumers
+export type {
+  AnyPadroneCommand,
+  AnyPadroneProgram,
+  PadroneCommand,
+  PadroneCommandBuilder,
+  PadroneCommandConfig,
+  PadroneCommandResult,
+  PadroneParseOptions,
+  PadroneParseResult,
+  PadroneProgram,
+} from './types';

package/src/options.ts

@@ -0,0 +1,290 @@
+import type { StandardJSONSchemaV1 } from '@standard-schema/spec';
+
+export interface PadroneOptionsMeta {
+  description?: string;
+  alias?: string[] | string;
+  deprecated?: boolean | string;
+  hidden?: boolean;
+  examples?: unknown[];
+  /**
+   * Environment variable name(s) to bind this option to.
+   * Can be a single string or array of env var names (checked in order).
+   */
+  env?: string | string[];
+  /**
+   * Key path in config file that maps to this option.
+   * Supports dot notation for nested keys (e.g., 'server.port').
+   */
+  configKey?: string;
+}
+
+type PositionalArgs<TObj> =
+  TObj extends Record<string, any>
+    ? {
+        [K in keyof TObj]: TObj[K] extends Array<any> ? `...${K & string}` : K & string;
+      }[keyof TObj]
+    : string;
+
+/**
+ * Meta configuration for options including positional arguments.
+ * The `positional` array defines which options are positional arguments and their order.
+ * Use '...name' prefix to indicate variadic (rest) arguments, matching JS/TS rest syntax.
+ *
+ * @example
+ * ```ts
+ * .options(schema, {
+ *   positional: ['source', '...files', 'dest'],  // '...files' is variadic
+ * })
+ * ```
+ */
+export interface PadroneMeta<TObj = Record<string, any>> {
+  /**
+   * Array of option names that should be treated as positional arguments.
+   * Order in array determines position. Use '...name' prefix for variadic args.
+   * @example ['source', '...files', 'dest'] - 'files' captures multiple values
+   */
+  positional?: PositionalArgs<TObj>[];
+  /**
+   * Per-option metadata.
+   */
+  options?: { [K in keyof TObj]?: PadroneOptionsMeta };
+}
+
+/**
+ * Parse positional configuration to extract names and variadic info.
+ */
+export function parsePositionalConfig(positional: string[]): { name: string; variadic: boolean }[] {
+  return positional.map((p) => {
+    const isVariadic = p.startsWith('...');
+    const name = isVariadic ? p.slice(3) : p;
+    return { name, variadic: isVariadic };
+  });
+}
+
+/**
+ * Result type for extractSchemaMetadata function.
+ */
+interface SchemaMetadataResult {
+  aliases: Record<string, string>;
+  envBindings: Record<string, string[]>;
+  configKeys: Record<string, string>;
+}
+
+/**
+ * Extract all option metadata from schema and meta in a single pass.
+ * This consolidates aliases, env bindings, and config keys extraction.
+ */
+export function extractSchemaMetadata(
+  schema: StandardJSONSchemaV1,
+  meta?: Record<string, PadroneOptionsMeta | undefined>,
+): SchemaMetadataResult {
+  const aliases: Record<string, string> = {};
+  const envBindings: Record<string, string[]> = {};
+  const configKeys: Record<string, string> = {};
+
+  // Extract from meta object
+  if (meta) {
+    for (const [key, value] of Object.entries(meta)) {
+      if (!value) continue;
+
+      // Extract aliases
+      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;
+          }
+        }
+      }
+
+      // Extract env bindings
+      if (value.env) {
+        envBindings[key] = typeof value.env === 'string' ? [value.env] : value.env;
+      }
+
+      // Extract config keys
+      if (value.configKey) {
+        configKeys[key] = value.configKey;
+      }
+    }
+  }
+
+  // Extract from JSON schema properties
+  try {
+    const jsonSchema = schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+    if (jsonSchema.type === 'object' && jsonSchema.properties) {
+      for (const [propertyName, propertySchema] of Object.entries(jsonSchema.properties as Record<string, any>)) {
+        if (!propertySchema) continue;
+
+        // Extract aliases from schema
+        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;
+              }
+            }
+          }
+        }
+
+        // Extract env bindings from schema
+        if (propertySchema.env && !(propertyName in envBindings)) {
+          const envVars = typeof propertySchema.env === 'string' ? [propertySchema.env] : propertySchema.env;
+          if (Array.isArray(envVars)) {
+            envBindings[propertyName] = envVars;
+          }
+        }
+
+        // Extract config keys from schema
+        if (propertySchema.configKey && !(propertyName in configKeys)) {
+          configKeys[propertyName] = propertySchema.configKey;
+        }
+      }
+    }
+  } catch {
+    // Ignore errors from JSON schema generation
+  }
+
+  return { aliases, envBindings, configKeys };
+}
+
+function preprocessAliases(data: Record<string, unknown>, aliases: Record<string, string>): Record<string, unknown> {
+  const result = { ...data };
+
+  for (const [aliasKey, fullOptionName] of Object.entries(aliases)) {
+    if (aliasKey in data && aliasKey !== fullOptionName) {
+      const aliasValue = data[aliasKey];
+      // Prefer full option name if it exists
+      if (!(fullOptionName in result)) result[fullOptionName] = aliasValue;
+      delete result[aliasKey];
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Apply environment variable values to options.
+ * CLI values take precedence over environment variables.
+ */
+function applyEnvBindings(
+  data: Record<string, unknown>,
+  envBindings: Record<string, string[]>,
+  env: Record<string, string | undefined> = typeof process !== 'undefined' ? process.env : {},
+): Record<string, unknown> {
+  const result = { ...data };
+
+  for (const [optionName, envVars] of Object.entries(envBindings)) {
+    // Only apply env var if option wasn't already set
+    if (optionName in result && result[optionName] !== undefined) continue;
+
+    for (const envVar of envVars) {
+      const envValue = env[envVar];
+      if (envValue !== undefined) {
+        // Try to parse the value intelligently
+        result[optionName] = parseEnvValue(envValue);
+        break;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse an environment variable value, attempting to convert to appropriate types.
+ */
+function parseEnvValue(value: string): unknown {
+  // Handle boolean-like values
+  const lowerValue = value.toLowerCase();
+  if (lowerValue === 'true' || lowerValue === '1' || lowerValue === 'yes') return true;
+  if (lowerValue === 'false' || lowerValue === '0' || lowerValue === 'no') return false;
+
+  // Handle numeric values
+  if (/^-?\d+$/.test(value)) return Number.parseInt(value, 10);
+  if (/^-?\d+\.\d+$/.test(value)) return Number.parseFloat(value);
+
+  // Handle arrays (comma-separated)
+  if (value.includes(',')) {
+    return value.split(',').map((v) => parseEnvValue(v.trim()));
+  }
+
+  return value;
+}
+
+/**
+ * Get a nested value from an object using dot notation.
+ */
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  const parts = path.split('.');
+  let current: unknown = obj;
+
+  for (const part of parts) {
+    if (current === null || current === undefined) return undefined;
+    if (typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+
+  return current;
+}
+
+/**
+ * Apply config file values to options.
+ * CLI values and env values take precedence over config file values.
+ */
+function applyConfigValues(
+  data: Record<string, unknown>,
+  configKeys: Record<string, string>,
+  configData: Record<string, unknown>,
+): Record<string, unknown> {
+  const result = { ...data };
+
+  for (const [optionName, configKey] of Object.entries(configKeys)) {
+    // Only apply config value if option wasn't already set
+    if (optionName in result && result[optionName] !== undefined) continue;
+
+    const configValue = getNestedValue(configData, configKey);
+    if (configValue !== undefined) {
+      result[optionName] = configValue;
+    }
+  }
+
+  return result;
+}
+
+interface ParseOptionsContext {
+  aliases?: Record<string, string>;
+  envBindings?: Record<string, string[]>;
+  configKeys?: Record<string, string>;
+  configData?: Record<string, unknown>;
+  env?: Record<string, string | undefined>;
+}
+
+/**
+ * Combined preprocessing of options with all features.
+ * Precedence order (highest to lowest): CLI args > env vars > config file
+ */
+export function preprocessOptions(data: Record<string, unknown>, ctx: ParseOptionsContext): Record<string, unknown> {
+  let result = { ...data };
+
+  // 1. Apply aliases first
+  if (ctx.aliases && Object.keys(ctx.aliases).length > 0) {
+    result = preprocessAliases(result, ctx.aliases);
+  }
+
+  // 2. Apply environment variables (higher precedence than config)
+  // These only apply if CLI didn't set the option
+  if (ctx.envBindings && Object.keys(ctx.envBindings).length > 0) {
+    result = applyEnvBindings(result, ctx.envBindings, ctx.env);
+  }
+
+  // 3. Apply config file values (lowest precedence)
+  // These only apply if neither CLI nor env set the option
+  if (ctx.configKeys && ctx.configData) {
+    result = applyConfigValues(result, ctx.configKeys, ctx.configData);
+  }
+
+  return result;
+}