padrone 1.4.0 → 1.6.0

package/src/codegen/discovery.ts

@@ -1,15 +1,23 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+
+import { parseBashCompletions } from './parsers/bash.ts';
 import { parseFishCompletions } from './parsers/fish.ts';
 import { parseHelpOutput } from './parsers/help.ts';
 import { mergeCommandMeta } from './parsers/merge.ts';
 import { parseZshCompletions } from './parsers/zsh.ts';
 import type { CommandMeta, GeneratorLogger } from './types.ts';
 
-export type DiscoverySource = 'help' | 'fish' | 'zsh';
+export type DiscoverySource = 'help' | 'completion' | 'bash' | 'fish' | 'zsh';
 
 export interface DiscoveryOptions {
   /** The command to discover (e.g. 'gh', 'docker', 'kubectl'). */
   command: string;
-  /** Which parsing sources to use. Default: ['help'] */
+  /**
+   * Which parsing sources to use. Default: ['help'].
+   * Use `'completion'` to auto-detect the best shell completion source
+   * by probing `<cmd> completion <shell>` (bash → fish → zsh).
+   */
   sources?: DiscoverySource[];
   /** Max subcommand depth. 0 = root only, undefined = unlimited. */
   depth?: number;
@@ -35,7 +43,10 @@ export interface DiscoveryResult {
  * parsing shell completion scripts.
  */
 export async function discoverCli(options: DiscoveryOptions): Promise<DiscoveryResult> {
-  const { command, sources = ['help'], depth, delay = 50, log, timeout = 10000 } = options;
+  const { command, sources: rawSources = ['help'], depth, delay = 50, log, timeout = 10000 } = options;
+
+  // Resolve 'completion' source by probing for the best available shell
+  const sources = await resolveSources(rawSources, command, timeout, log);
 
   const warnings: string[] = [];
   let invocations = 0;
@@ -60,7 +71,18 @@ export async function discoverCli(options: DiscoveryOptions): Promise<DiscoveryR
     results.push(helpResult);
   }
 
-  // Source 2: Fish completions
+  // Source 2: Bash completions
+  if (sources.includes('bash')) {
+    log?.info(`Parsing bash completions for ${command}...`);
+    const bashText = await getCompletionScript(command, 'bash', timeout);
+    if (bashText) {
+      results.push(parseBashCompletions(bashText));
+    } else {
+      warnings.push('Could not obtain bash completion script');
+    }
+  }
+
+  // Source 3: Fish completions
   if (sources.includes('fish')) {
     log?.info(`Parsing fish completions for ${command}...`);
     const fishText = await getCompletionScript(command, 'fish', timeout);
@@ -71,7 +93,7 @@ export async function discoverCli(options: DiscoveryOptions): Promise<DiscoveryR
     }
   }
 
-  // Source 3: Zsh completions
+  // Source 4: Zsh completions
   if (sources.includes('zsh')) {
     log?.info(`Parsing zsh completions for ${command}...`);
     const zshText = await getCompletionScript(command, 'zsh', timeout);
@@ -163,25 +185,13 @@ async function runHelp(command: string, args: string[], timeout: number): Promis
  */
 async function runCommand(command: string, args: string[], timeout: number): Promise<string | null> {
   try {
-    const proc = Bun.spawn([command, ...args], {
-      stdout: 'pipe',
-      stderr: 'pipe',
-      stdin: 'ignore',
+    const { stdout, stderr } = await new Promise<{ stdout: string; stderr: string }>((resolve) => {
+      execFile(command, args, { timeout, maxBuffer: 10 * 1024 * 1024 }, (_error, stdout, stderr) => {
+        // Resolve even on non-zero exit — many CLIs exit non-zero on --help
+        resolve({ stdout: (stdout ?? '').trim(), stderr: (stderr ?? '').trim() });
+      });
     });
 
-    const timer = setTimeout(() => proc.kill(), timeout);
-
-    const [_exitCode, stdoutBuf, stderrBuf] = await Promise.all([
-      proc.exited,
-      new Response(proc.stdout).arrayBuffer(),
-      new Response(proc.stderr).arrayBuffer(),
-    ]);
-
-    clearTimeout(timer);
-
-    const stdout = new TextDecoder().decode(stdoutBuf).trim();
-    const stderr = new TextDecoder().decode(stderrBuf).trim();
-
     // Some CLIs output help to stderr, some exit non-zero on --help
     const combined = stdout || stderr;
     if (!combined) return null;
@@ -199,7 +209,7 @@ async function runCommand(command: string, args: string[], timeout: number): Pro
  * Try to get a shell completion script for a command.
  * Checks both `<cmd> completion <shell>` and well-known file paths.
  */
-async function getCompletionScript(command: string, shell: 'fish' | 'zsh', timeout: number): Promise<string | null> {
+async function getCompletionScript(command: string, shell: 'bash' | 'fish' | 'zsh', timeout: number): Promise<string | null> {
   // Try `<cmd> completion <shell>`
   const completionArgs = ['completion', shell];
   let result = await runCommand(command, completionArgs, timeout);
@@ -213,20 +223,62 @@ async function getCompletionScript(command: string, shell: 'fish' | 'zsh', timeo
   const paths =
     shell === 'fish'
       ? [`/usr/share/fish/vendor_completions.d/${command}.fish`, `/usr/local/share/fish/vendor_completions.d/${command}.fish`]
-      : [`/usr/share/zsh/site-functions/_${command}`, `/usr/local/share/zsh/site-functions/_${command}`];
+      : shell === 'bash'
+        ? [
+            `/usr/share/bash-completion/completions/${command}`,
+            `/usr/local/share/bash-completion/completions/${command}`,
+            `/etc/bash_completion.d/${command}`,
+          ]
+        : [`/usr/share/zsh/site-functions/_${command}`, `/usr/local/share/zsh/site-functions/_${command}`];
 
   for (const path of paths) {
     try {
-      const file = Bun.file(path);
-      if (await file.exists()) {
-        return await file.text();
-      }
+      return await readFile(path, 'utf-8');
     } catch {}
   }
 
   return null;
 }
 
+/**
+ * Detect the best shell for completion parsing by probing the command.
+ * Tries `<cmd> completion <shell>` for bash, fish, zsh (in that order).
+ * Returns the shell name if successful, or null if no completion command exists.
+ */
+export async function detectCompletionShell(command: string, timeout = 5000): Promise<'bash' | 'fish' | 'zsh' | null> {
+  for (const shell of ['bash', 'fish', 'zsh'] as const) {
+    const result = await getCompletionScript(command, shell, timeout);
+    if (result) return shell;
+  }
+  return null;
+}
+
+/**
+ * Resolve 'completion' entries in the sources array by probing for the best available shell.
+ * Other sources are passed through unchanged.
+ */
+async function resolveSources(
+  sources: DiscoverySource[],
+  command: string,
+  timeout: number,
+  log?: GeneratorLogger,
+): Promise<DiscoverySource[]> {
+  if (!sources.includes('completion')) return sources;
+
+  log?.info(`Probing ${command} for completion command...`);
+  const shell = await detectCompletionShell(command, timeout);
+
+  return sources.flatMap((s) => {
+    if (s !== 'completion') return s;
+    if (shell) {
+      log?.info(`  Found ${shell} completion support`);
+      return shell;
+    }
+    log?.info('  No completion command found, skipping');
+    return [];
+  });
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/src/codegen/index.ts

@@ -4,7 +4,7 @@
 export { createCodeBuilder } from './code-builder.ts';
 export type { DiscoveryOptions, DiscoveryResult, DiscoverySource } from './discovery.ts';
 // Discovery
-export { discoverCli } from './discovery.ts';
+export { detectCompletionShell, discoverCli } from './discovery.ts';
 export { createFileEmitter } from './file-emitter.ts';
 // Generators
 export { generateBarrelFile } from './generators/barrel-file.ts';
@@ -13,6 +13,7 @@ export { generateCommandFile } from './generators/command-file.ts';
 export type { CommandTreeOptions } from './generators/command-tree.ts';
 export { generateCommandTree } from './generators/command-tree.ts';
 // Parsers
+export { parseBashCompletions } from './parsers/bash.ts';
 export { parseFishCompletions } from './parsers/fish.ts';
 export { parseHelpOutput } from './parsers/help.ts';
 export { mergeCommandMeta } from './parsers/merge.ts';

package/src/codegen/parsers/bash.ts

@@ -0,0 +1,179 @@
+import type { CommandMeta, FieldMeta } from '../types.ts';
+
+/**
+ * Parse bash completion scripts into CommandMeta.
+ *
+ * Bash completions typically use `complete -F <func> <command>` and define
+ * a function that sets COMPREPLY. Common patterns:
+ *
+ *   local commands="init build deploy"
+ *   local args="--verbose --output --format"
+ *   case "$prev" in --format) COMPREPLY=($(compgen -W "json yaml toml" ...)) ;;
+ *   COMPREPLY=($(compgen -W "$commands" ...))
+ *   COMPREPLY=($(compgen -W "$args" ...))
+ */
+export function parseBashCompletions(text: string): CommandMeta {
+  const result: CommandMeta = {
+    name: '',
+    arguments: [],
+    subcommands: [],
+  };
+
+  // Detect command name from `complete -F _func <command>` or `complete -o ... -F _func <command>`
+  const completeMatch = text.match(/complete\s+(?:[^-]|-[^F])*-F\s+\S+\s+(\S+)/);
+  if (completeMatch) {
+    result.name = completeMatch[1]!;
+  }
+
+  // Fallback: detect from marker comments like ###-begin-<name>-completion-###
+  if (!result.name) {
+    const markerMatch = text.match(/###-begin-(\S+)-completion-###/);
+    if (markerMatch) {
+      result.name = markerMatch[1]!;
+    }
+  }
+
+  // Join continuation lines for easier parsing
+  const joined = text.replace(/\\\n\s*/g, ' ');
+
+  // Collect variable values: local commands="..." or local args="..."
+  const variables = extractVariables(joined);
+
+  // Extract subcommand names from commands variable or compgen -W "cmd1 cmd2"
+  const commandWords = variables.get('commands') ?? variables.get('cmds') ?? variables.get('subcommands');
+  if (commandWords) {
+    for (const name of splitWords(commandWords)) {
+      result.subcommands!.push({ name });
+    }
+  }
+
+  // Extract option names from args/opts/options variable
+  const argWords = variables.get('args') ?? variables.get('opts') ?? variables.get('options') ?? variables.get('flags');
+  const optionNames = new Set<string>();
+
+  if (argWords) {
+    for (const word of splitWords(argWords)) {
+      if (word.startsWith('-')) {
+        optionNames.add(word);
+      }
+    }
+  }
+
+  // Also scan for compgen -W patterns not tied to a case statement
+  const compgenRegex = /compgen\s+-W\s+["']([^"']+)["']/g;
+  let compgenMatch: RegExpExecArray | null;
+  while ((compgenMatch = compgenRegex.exec(joined)) !== null) {
+    // Skip variable references like $args, $commands
+    if (compgenMatch[1]!.startsWith('$')) continue;
+    for (const word of splitWords(compgenMatch[1]!)) {
+      if (word.startsWith('-')) {
+        optionNames.add(word);
+      }
+    }
+  }
+
+  // Parse case statement for option value completions (enum detection)
+  const enumMap = parseCaseStatement(joined);
+
+  // Build argument fields
+  const seenArgs = new Set<string>();
+
+  for (const rawName of optionNames) {
+    // Skip builtins
+    if (rawName === '--help' || rawName === '-h' || rawName === '--version' || rawName === '-V') continue;
+
+    const name = rawName.replace(/^-+/, '').replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+    if (!name || seenArgs.has(name)) continue;
+    seenArgs.add(name);
+
+    // Check if this option has enum values from case statement
+    const enumValues = enumMap.get(rawName);
+
+    const isShort = rawName.startsWith('-') && !rawName.startsWith('--') && rawName.length === 2;
+    const field: FieldMeta = {
+      name,
+      type: enumValues ? 'enum' : 'string',
+      enumValues,
+      ambiguous: !enumValues,
+    };
+
+    // If there's a corresponding long-form, record alias
+    if (isShort) {
+      field.aliases = [rawName];
+    }
+
+    result.arguments!.push(field);
+  }
+
+  if (result.arguments!.length === 0) delete result.arguments;
+  if (result.subcommands!.length === 0) delete result.subcommands;
+
+  return result;
+}
+
+/**
+ * Extract variable assignments: `local VAR="value"`, `VAR="value"`, `local VAR='value'`
+ */
+function extractVariables(text: string): Map<string, string> {
+  const vars = new Map<string, string>();
+  const regex = /(?:local\s+)?(\w+)=["']([^"']+)["']/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(text)) !== null) {
+    vars.set(match[1]!, match[2]!);
+  }
+
+  return vars;
+}
+
+/**
+ * Parse case statements to find option → enum value mappings.
+ *
+ * Matches patterns like:
+ *   case "$prev" in
+ *     --format) COMPREPLY=($(compgen -W "json yaml toml" ...)) ;;
+ *     --env|--environment) COMPREPLY=($(compgen -W "dev staging prod" ...)) ;;
+ */
+function parseCaseStatement(text: string): Map<string, string[]> {
+  const result = new Map<string, string[]>();
+
+  // Find case blocks on $prev or similar variables
+  const caseRegex = /case\s+[^i]*\bin\b\s*([\s\S]*?)esac/g;
+  let caseMatch: RegExpExecArray | null;
+
+  while ((caseMatch = caseRegex.exec(text)) !== null) {
+    const body = caseMatch[1]!;
+
+    // Split into branches by ;; delimiter
+    const branches = body.split(';;');
+    for (const branch of branches) {
+      // Match pattern: --opt1|--opt2) ... compgen -W "values" ...
+      const patternMatch = branch.match(/^\s*([-\w|]+)\)/);
+      if (!patternMatch) continue;
+
+      // Find compgen -W "values" within this branch
+      const compgenMatch = branch.match(/compgen\s+-W\s+["']([^"']+)["']/);
+      if (!compgenMatch) continue;
+
+      const values = compgenMatch[1]!;
+      const words = splitWords(values).filter((w) => !w.startsWith('$'));
+      if (words.length === 0) continue;
+
+      for (const pattern of patternMatch[1]!.split('|')) {
+        const trimmed = pattern.trim();
+        if (trimmed.startsWith('-')) {
+          result.set(trimmed, words);
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Split a space-separated word list, filtering empty strings.
+ */
+function splitWords(text: string): string[] {
+  return text.split(/\s+/).filter(Boolean);
+}

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

@@ -1,4 +1,5 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { getJsonSchema } from '../core/args.ts';
 import type { FieldMeta } from './types.ts';
 
 interface SchemaToCodeResult {
@@ -57,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({ target: 'draft-2020-12' }) as Record<string, any>;
+    const jsonSchema = getJsonSchema(schema as any) as Record<string, any>;
     return jsonSchemaToCode(jsonSchema);
   } catch {
     return { code: 'z.unknown()', imports: ['z'] };

package/src/core/args.ts

@@ -0,0 +1,296 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec';
+import type { PadroneFieldMeta } from '../types/args-meta.ts';
+import { camelToKebab } from '../util/shell-utils.ts';
+import { asyncStreamRegistry } from '../util/stream.ts';
+
+export type { PadroneArgsSchemaMeta, PadroneFieldMeta, SingleChar, StdinConfig } from '../types/args-meta.ts';
+
+/** Extract the JSON schema from a Standard Schema, returning it as a plain record. */
+export function getJsonSchema(schema: StandardJSONSchemaV1): Record<string, any> {
+  return schema['~standard'].jsonSchema.input({
+    target: 'draft-2020-12',
+    libraryOptions: { unrepresentable: 'any' },
+  }) as Record<string, any>;
+}
+
+function getFieldJsonSchema(schema: StandardJSONSchemaV1 | undefined, field: string): Record<string, any> | undefined {
+  if (!schema) return undefined;
+  try {
+    const jsonSchema = getJsonSchema(schema);
+    if (jsonSchema.type === 'object' && jsonSchema.properties) return jsonSchema.properties[field];
+  } catch {}
+  return undefined;
+}
+
+/**
+ * Checks if a field in the schema is an array type (e.g. `z.string().array()`).
+ */
+export function isArrayField(schema: StandardJSONSchemaV1 | undefined, field: string): boolean {
+  return getFieldJsonSchema(schema, field)?.type === 'array';
+}
+
+/**
+ * Checks if a field is an async stream (marked with `asyncStream()` metadata).
+ * Returns the item schema if provided, or `true` if it's a plain string stream.
+ */
+export function isAsyncStreamField(schema: StandardJSONSchemaV1 | undefined, field: string): { itemSchema?: StandardSchemaV1 } | false {
+  const prop = getFieldJsonSchema(schema, field);
+  const asyncStreamId = prop?.asyncStream;
+  if (asyncStreamId && asyncStreamRegistry.has(asyncStreamId)) {
+    const meta = asyncStreamRegistry.get(asyncStreamId);
+    return { itemSchema: meta?.itemSchema };
+  }
+
+  return false;
+}
+
+/**
+ * Parse positional configuration to extract names and variadic info.
+ */
+export function parsePositionalConfig(positional: readonly string[]): { name: string; variadic: boolean }[] {
+  return positional.map((p) => {
+    const variadic = p.startsWith('...');
+    const name = variadic ? p.slice(3) : p;
+    return { name, variadic };
+  });
+}
+
+/**
+ * Result type for extractSchemaMetadata function.
+ */
+interface SchemaMetadataResult {
+  /** Single-char flags: maps flag char → full arg name (e.g. `{ v: 'verbose' }`) */
+  flags: Record<string, string>;
+  /** Multi-char aliases: maps alias → full arg name (e.g. `{ 'dry-run': 'dryRun' }`) */
+  aliases: Record<string, string>;
+}
+
+function addEntries(target: Record<string, string>, key: string, items: string | readonly string[], filter?: (item: string) => boolean) {
+  const list = typeof items === 'string' ? [items] : items;
+  for (const item of list) {
+    if (typeof item === 'string' && item && item !== key && !(item in target) && (!filter || filter(item))) {
+      target[item] = key;
+    }
+  }
+}
+
+/**
+ * Extract all arg metadata from schema and meta in a single pass.
+ * Returns flags (single-char, stackable) and aliases (multi-char, long names) separately.
+ * When `autoAlias` is true (default), camelCase property names automatically get kebab-case aliases.
+ */
+export function extractSchemaMetadata(
+  schema: StandardJSONSchemaV1,
+  meta?: Record<string, PadroneFieldMeta | undefined>,
+  autoAlias?: boolean,
+): SchemaMetadataResult {
+  const flags: Record<string, string> = {};
+  const aliases: Record<string, string> = {};
+
+  // Extract from meta object
+  if (meta) {
+    for (const [key, value] of Object.entries(meta)) {
+      if (!value) continue;
+
+      if (value.flags) {
+        addEntries(flags, key, value.flags, (item) => item.length === 1);
+      }
+      if (value.alias) {
+        addEntries(aliases, key, value.alias, (item) => item.length > 1);
+      }
+    }
+  }
+
+  // Extract from JSON schema properties
+  try {
+    const jsonSchema = getJsonSchema(schema) 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 flags from schema `.meta({ flags: ... })`
+        const propFlags = propertySchema.flags;
+        if (propFlags) {
+          addEntries(flags, propertyName, propFlags, (item) => item.length === 1);
+        }
+
+        // Extract aliases from schema `.meta({ alias: ... })`
+        const propAlias = propertySchema.alias;
+        if (propAlias) {
+          const list = typeof propAlias === 'string' ? [propAlias] : propAlias;
+          if (Array.isArray(list)) {
+            addEntries(aliases, propertyName, list, (item) => item.length > 1);
+          }
+        }
+
+        // Auto-generate kebab-case alias for camelCase property names
+        if (autoAlias !== false) {
+          const kebab = camelToKebab(propertyName);
+          if (kebab && !(kebab in aliases)) {
+            aliases[kebab] = propertyName;
+          }
+        }
+      }
+    }
+  } catch {
+    // Ignore errors from JSON schema generation
+  }
+
+  return { flags, aliases };
+}
+
+function preprocessMappings(data: Record<string, unknown>, mappings: Record<string, string>): Record<string, unknown> {
+  const result = { ...data };
+
+  for (const [mappedKey, fullArgName] of Object.entries(mappings)) {
+    if (mappedKey in data && mappedKey !== fullArgName) {
+      const mappedValue = data[mappedKey];
+      // Prefer full arg name if it exists
+      if (!(fullArgName in result)) result[fullArgName] = mappedValue;
+      delete result[mappedKey];
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Apply values to arguments using "set if not present" semantics.
+ * Existing values take precedence — only fills in undefined or missing keys.
+ */
+export function applyValues(data: Record<string, unknown>, values: Record<string, unknown>): Record<string, unknown> {
+  const result = { ...data };
+
+  for (const [key, value] of Object.entries(values)) {
+    if (key in result && result[key] !== undefined) continue;
+    if (value !== undefined) {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/** Applies flag and alias mappings to raw arguments. */
+export function preprocessArgs(
+  data: Record<string, unknown>,
+  ctx: { flags?: Record<string, string>; aliases?: Record<string, string> },
+): Record<string, unknown> {
+  let result = { ...data };
+
+  if (ctx.flags && Object.keys(ctx.flags).length > 0) {
+    result = preprocessMappings(result, ctx.flags);
+  }
+  if (ctx.aliases && Object.keys(ctx.aliases).length > 0) {
+    result = preprocessMappings(result, ctx.aliases);
+  }
+
+  return result;
+}
+
+/**
+ * Auto-coerce CLI string values to match the expected schema types.
+ * Handles: string → number, string → boolean for primitive schema fields.
+ * Arrays of primitives are also coerced element-wise.
+ */
+export function coerceArgs(data: Record<string, unknown>, schema: StandardJSONSchemaV1): Record<string, unknown> {
+  let properties: Record<string, any>;
+  try {
+    const jsonSchema = getJsonSchema(schema) as Record<string, any>;
+    if (jsonSchema.type !== 'object' || !jsonSchema.properties) return data;
+    properties = jsonSchema.properties;
+  } catch {
+    return data;
+  }
+
+  const result = { ...data };
+
+  for (const [key, value] of Object.entries(result)) {
+    const prop = properties[key];
+    if (!prop) continue;
+
+    const targetType = prop.type as string | undefined;
+
+    if (targetType === 'number' || targetType === 'integer') {
+      if (typeof value === 'string') {
+        const num = Number(value);
+        if (!Number.isNaN(num)) result[key] = num;
+      }
+    } else if (targetType === 'boolean') {
+      if (typeof value === 'string') {
+        const lower = value.toLowerCase();
+        if (lower === 'true' || lower === '1' || lower === 'yes' || lower === 'on') result[key] = true;
+        else if (lower === 'false' || lower === '0' || lower === 'no' || lower === 'off') result[key] = false;
+      }
+    } else if (targetType === 'array') {
+      // Coerce single items to array
+      const arr = Array.isArray(value) ? value : [value];
+      const itemType = prop.items?.type as string | undefined;
+      if (itemType === 'number' || itemType === 'integer') {
+        result[key] = arr.map((v) => {
+          if (typeof v === 'string') {
+            const num = Number(v);
+            return Number.isNaN(num) ? v : num;
+          }
+          return v;
+        });
+      } else if (itemType === 'boolean') {
+        result[key] = arr.map((v) => {
+          if (typeof v === 'string') {
+            const lower = v.toLowerCase();
+            if (lower === 'true' || lower === '1' || lower === 'yes' || lower === 'on') return true;
+            if (lower === 'false' || lower === '0' || lower === 'no' || lower === 'off') return false;
+          }
+          return v;
+        });
+      } else if (!Array.isArray(value)) {
+        result[key] = arr;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Detect unknown keys in the args that don't match any schema property.
+ * Returns an array of { key } for each unknown key.
+ * Framework-reserved keys (--config, -c) are always allowed.
+ */
+export function detectUnknownArgs(
+  data: Record<string, unknown>,
+  schema: StandardJSONSchemaV1,
+  flags: Record<string, string>,
+  aliases: Record<string, string>,
+): { key: string }[] {
+  let properties: Record<string, any>;
+  let isLoose = false;
+  try {
+    const jsonSchema = getJsonSchema(schema) as Record<string, any>;
+    if (jsonSchema.type !== 'object' || !jsonSchema.properties) return [];
+    properties = jsonSchema.properties;
+    // If additionalProperties is set (true, {}, or a schema), the schema allows extra keys
+    if (jsonSchema.additionalProperties !== undefined && jsonSchema.additionalProperties !== false) isLoose = true;
+  } catch {
+    return [];
+  }
+
+  if (isLoose) return [];
+
+  const knownKeys = new Set<string>([
+    ...Object.keys(properties),
+    ...Object.keys(flags),
+    ...Object.values(flags),
+    ...Object.keys(aliases),
+    ...Object.values(aliases),
+  ]);
+  const unknowns: { key: string }[] = [];
+
+  for (const key of Object.keys(data)) {
+    if (!knownKeys.has(key)) {
+      unknowns.push({ key });
+    }
+  }
+
+  return unknowns;
+}