padrone 1.1.0 → 1.3.0

package/src/help.ts

@@ -1,17 +1,19 @@
 import type { StandardJSONSchemaV1 } from '@standard-schema/spec';
+import { extractSchemaMetadata, type PadroneArgsSchemaMeta, parsePositionalConfig, parseStdinConfig } from './args.ts';
+import { findCommandByName } from './command-utils.ts';
 import {
   createFormatter,
   type HelpArgumentInfo,
   type HelpDetail,
   type HelpFormat,
   type HelpInfo,
-  type HelpOptionInfo,
+  type HelpPositionalInfo,
+  type HelpSubcommandInfo,
 } from './formatter.ts';
-import { extractSchemaMetadata, type PadroneMeta, parsePositionalConfig } from './options.ts';
 import type { AnyPadroneCommand } from './types.ts';
 import { getRootCommand } from './utils.ts';
 
-export type HelpOptions = {
+export type HelpPreferences = {
   format?: HelpFormat | 'auto';
   detail?: HelpDetail;
 };
@@ -21,9 +23,9 @@ export type HelpOptions = {
  */
 function extractPositionalArgsInfo(
   schema: StandardJSONSchemaV1,
-  meta?: PadroneMeta,
-): { args: HelpArgumentInfo[]; positionalNames: Set<string> } {
-  const args: HelpArgumentInfo[] = [];
+  meta?: PadroneArgsSchemaMeta,
+): { args: HelpPositionalInfo[]; positionalNames: Set<string> } {
+  const args: HelpPositionalInfo[] = [];
   const positionalNames = new Set<string>();
 
   if (!schema || !meta?.positional || meta.positional.length === 0) {
@@ -44,7 +46,7 @@ function extractPositionalArgsInfo(
         if (!prop) continue;
 
         positionalNames.add(name);
-        const optMeta = meta.options?.[name];
+        const optMeta = meta.fields?.[name];
 
         args.push({
           name: variadic ? `...${name}` : name,
@@ -62,14 +64,14 @@ function extractPositionalArgsInfo(
   return { args, positionalNames };
 }
 
-function extractOptionsInfo(schema: StandardJSONSchemaV1, meta?: PadroneMeta, positionalNames?: Set<string>) {
-  const result: HelpOptionInfo[] = [];
+function extractArgsInfo(schema: StandardJSONSchemaV1, meta?: PadroneArgsSchemaMeta, positionalNames?: Set<string>) {
+  const result: HelpArgumentInfo[] = [];
   if (!schema) return result;
 
   const vendor = schema['~standard'].vendor;
   if (!vendor.includes('zod')) return result;
 
-  const optionsMeta = meta?.options;
+  const argsMeta = meta?.fields;
 
   try {
     const jsonSchema = schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
@@ -80,7 +82,7 @@ function extractOptionsInfo(schema: StandardJSONSchemaV1, meta?: PadroneMeta, po
       const required = (jsonSchema.required as string[]) || [];
       const propertyNames = new Set(Object.keys(properties));
 
-      // Helper to check if a negated version of an option exists
+      // Helper to check if a negated version of an arg exists
       const hasExplicitNegation = (key: string): boolean => {
         // Check for noVerbose style (camelCase)
         const camelNegated = `no${key.charAt(0).toUpperCase()}${key.slice(1)}`;
@@ -91,7 +93,7 @@ function extractOptionsInfo(schema: StandardJSONSchemaV1, meta?: PadroneMeta, po
         return false;
       };
 
-      // Helper to check if this option is itself a negation of another option
+      // Helper to check if this arg is itself a negation of another arg
       const isNegationOf = (key: string): boolean => {
         // Check for noVerbose -> verbose (camelCase)
         if (key.startsWith('no') && key.length > 2 && key[2] === key[2]?.toUpperCase()) {
@@ -111,12 +113,12 @@ function extractOptionsInfo(schema: StandardJSONSchemaV1, meta?: PadroneMeta, po
         if (positionalNames?.has(key)) continue;
 
         const isOptional = !required.includes(key);
-        const enumValues = prop.enum as string[] | undefined;
-        const optMeta = optionsMeta?.[key];
+        const enumValues = (prop.enum ?? prop.items?.enum) as string[] | undefined;
+        const optMeta = argsMeta?.[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
+        // Booleans are negatable unless there's an explicit noArg property
+        // or this arg is itself a negation of another arg
         const isNegatable = propType === 'boolean' && !hasExplicitNegation(key) && !isNegationOf(key);
 
         result.push({
@@ -124,12 +126,12 @@ function extractOptionsInfo(schema: StandardJSONSchemaV1, meta?: PadroneMeta, po
           description: optMeta?.description ?? prop.description,
           optional: isOptional,
           default: prop.default,
-          type: propType,
+          type: propType === 'array' ? `${prop.items?.type || 'string'}[]` : propType,
           enum: enumValues,
           deprecated: optMeta?.deprecated ?? prop?.deprecated,
           hidden: optMeta?.hidden ?? prop?.hidden,
           examples: optMeta?.examples ?? prop?.examples,
-          variadic: propType === 'array', // Arrays are always variadic
+          variadic: propType === 'array',
           negatable: isNegatable,
         });
       }
@@ -151,45 +153,99 @@ function extractOptionsInfo(schema: StandardJSONSchemaV1, meta?: PadroneMeta, po
  * @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 {
+export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['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)
+  // A command is a "default" command if its name is '' or it has '' as an alias
+  const isDefaultCommand = cmd.parent && (!cmd.name || cmd.aliases?.includes(''));
+  // For commands with empty name, use the first non-empty alias as display name
+  const nonEmptyAliases = cmd.aliases?.filter(Boolean);
+  const commandName = cmd.path || cmd.name || nonEmptyAliases?.[0] || (cmd.parent ? '[default]' : 'program');
+  // Build display aliases: real aliases (excluding the one promoted to display name) + [default] marker
+  const remainingAliases = !cmd.name && nonEmptyAliases?.length ? nonEmptyAliases.slice(1) : (nonEmptyAliases ?? []);
+  const displayAliases = isDefaultCommand ? [...remainingAliases, '[default]'] : nonEmptyAliases;
+
+  // Extract positional args from schema based on meta.positional
+  const { args: positionalArgs, positionalNames } = cmd.argsSchema
+    ? extractPositionalArgsInfo(cmd.argsSchema, cmd.meta)
     : { args: [], positionalNames: new Set<string>() };
 
-  const hasArguments = positionalArgs.length > 0;
+  const hasPositionals = positionalArgs.length > 0;
 
   const helpInfo: HelpInfo = {
     name: commandName,
     title: cmd.title,
     description: cmd.description,
-    aliases: cmd.aliases,
+    aliases: displayAliases,
     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,
+      hasPositionals,
+      hasArguments: false, // updated below after extracting arguments
+      stdinField: cmd.meta?.stdin ? parseStdinConfig(cmd.meta.stdin).field : undefined,
     },
   };
 
   // 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) => {
-      return {
-        name: c.name,
-        title: c.title,
-        description: c.description,
-        aliases: c.aliases,
-        deprecated: c.deprecated,
-        hidden: c.hidden,
-      };
-    });
+    // If the command has both a handler and subcommands, show the handler as a "[default]" entry
+    const selfEntry: typeof helpInfo.subcommands = cmd.action
+      ? [{ name: '[default]', title: cmd.title, description: cmd.description }]
+      : [];
+
+    helpInfo.subcommands = [
+      ...selfEntry,
+      ...visibleCommands.flatMap((c): HelpSubcommandInfo[] => {
+        const isDefault = !c.name || c.aliases?.includes('');
+        const nonEmptyAliases = c.aliases?.filter(Boolean);
+        const displayName = c.name || nonEmptyAliases?.[0] || '[default]';
+        const remainingAliases = !c.name && nonEmptyAliases?.length ? nonEmptyAliases.slice(1) : (nonEmptyAliases ?? []);
+        // Only add [default] alias marker if it's not already the display name
+        const displayAliases =
+          isDefault && displayName !== '[default]' ? [...remainingAliases, '[default]'] : isDefault ? remainingAliases : nonEmptyAliases;
+        const hasSubcommands = !!(c.commands && c.commands.length > 0);
+
+        // If a command has subcommands AND a default handler (direct or '' subcommand),
+        // show two entries: one for the default action, one for the subcommand router
+        const hasDefaultHandler = c.action || c.commands?.some((sub) => !sub.name || sub.aliases?.includes(''));
+        if (hasSubcommands && hasDefaultHandler) {
+          const defaultSub = !c.action ? c.commands?.find((sub) => !sub.name || sub.aliases?.includes('')) : undefined;
+          const hasDefaultSubInfo = defaultSub && (defaultSub.title || defaultSub.description);
+          return [
+            {
+              name: displayName,
+              title: hasDefaultSubInfo ? defaultSub.title : c.title,
+              description: hasDefaultSubInfo ? defaultSub.description : c.description,
+              aliases: displayAliases?.length ? displayAliases : undefined,
+              deprecated: c.deprecated,
+              hidden: c.hidden,
+            },
+            {
+              name: displayName,
+              title: c.title,
+              description: c.description,
+              deprecated: c.deprecated,
+              hidden: c.hidden,
+              hasSubcommands: true,
+            },
+          ];
+        }
+
+        return [
+          {
+            name: displayName,
+            title: c.title,
+            description: c.description,
+            aliases: displayAliases?.length ? displayAliases : undefined,
+            deprecated: c.deprecated,
+            hidden: c.hidden,
+            hasSubcommands,
+          },
+        ];
+      }),
+    ];
 
     // In 'full' detail mode, recursively build help for all nested commands
     if (detail === 'full') {
@@ -197,28 +253,73 @@ function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpOptions['detail'] = 'st
     }
   }
 
-  // Build arguments info from positional options
-  if (hasArguments) {
-    helpInfo.arguments = positionalArgs;
+  // Build arguments info from positionals
+  if (hasPositionals) {
+    helpInfo.positionals = 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);
+  // Build arguments info with aliases (excluding positional args)
+  if (cmd.argsSchema) {
+    const argsInfo = extractArgsInfo(cmd.argsSchema, cmd.meta, positionalNames);
+    const argMap: Record<string, HelpArgumentInfo> = Object.fromEntries(argsInfo.map((arg) => [arg.name, arg]));
+
+    // Merge flags and aliases into arguments
+    const { flags, aliases } = extractSchemaMetadata(cmd.argsSchema, cmd.meta?.fields, cmd.meta?.autoAlias);
+    for (const [flag, name] of Object.entries(flags)) {
+      const arg = argMap[name];
+      if (!arg) continue;
+      arg.flags = [...(arg.flags || []), flag];
+    }
     for (const [alias, name] of Object.entries(aliases)) {
-      const opt = optMap[name];
-      if (!opt) continue;
-      opt.aliases = [...(opt.aliases || []), alias];
+      const arg = argMap[name];
+      if (!arg) continue;
+      arg.aliases = [...(arg.aliases || []), alias];
+    }
+
+    // Filter out hidden arguments
+    const visibleArgs = argsInfo.filter((arg) => !arg.hidden);
+    if (visibleArgs.length > 0) {
+      helpInfo.arguments = visibleArgs;
+      helpInfo.usage.hasArguments = true;
     }
+  }
+
+  // Add built-in commands/flags for root command only
+  if (!cmd.parent) {
+    const builtins: HelpInfo['builtins'] = [];
+
+    if (!findCommandByName('help', cmd.commands)) {
+      builtins.push({
+        name: 'help [command], -h, --help',
+        description: 'Show help for a command',
+        sub: [
+          { name: '--detail <level>', description: 'Detail level (minimal, standard, full)' },
+          { name: '--format <format>', description: 'Output format (text, ansi, json, markdown, html)' },
+        ],
+      });
+    }
+
+    if (!findCommandByName('version', cmd.commands)) {
+      builtins.push({
+        name: 'version, -v, --version',
+        description: 'Show version information',
+      });
+    }
+
+    if (!findCommandByName('completion', cmd.commands)) {
+      builtins.push({
+        name: 'completion [shell]',
+        description: 'Generate shell completions (bash, zsh, fish, powershell)',
+      });
+    }
+
+    builtins.push({
+      name: '[command] --repl',
+      description: 'Start interactive REPL scoped to a command',
+    });
 
-    // Filter out hidden options
-    const visibleOptions = optionsInfo.filter((opt) => !opt.hidden);
-    if (visibleOptions.length > 0) {
-      helpInfo.options = visibleOptions;
+    if (builtins.length > 0) {
+      helpInfo.builtins = builtins;
     }
   }
 
@@ -229,8 +330,8 @@ function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpOptions['detail'] = 'st
 // 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);
+export function generateHelp(rootCommand: AnyPadroneCommand, commandObj: AnyPadroneCommand = rootCommand, prefs?: HelpPreferences): string {
+  const helpInfo = getHelpInfo(commandObj, prefs?.detail);
+  const formatter = createFormatter(prefs?.format ?? 'auto', prefs?.detail);
   return formatter.format(helpInfo);
 }

package/src/index.ts

@@ -1,26 +1,23 @@
-export { createPadrone } from './create.ts';
-export type { HelpArgumentInfo, HelpFormat, HelpInfo, HelpOptionInfo, HelpSubcommandInfo } from './formatter.ts';
-export type { HelpOptions } from './help.ts';
-export type { PadroneOptionsMeta } from './options.ts';
-export type {
-  InferCommand,
-  InferConfigInput,
-  InferConfigOutput,
-  InferEnvInput,
-  InferEnvOutput,
-  InferOptionsInput,
-  InferOptionsOutput,
-} from './type-helpers.ts';
+export { asyncSchema, buildReplCompleter, createPadrone } from './create.ts';
+export type { PadroneErrorOptions } from './errors.ts';
+export { ActionError, ConfigError, PadroneError, RoutingError, ValidationError } from './errors.ts';
+export type { HelpInfo } from './formatter.ts';
+export type { InteractiveMode, InteractivePromptConfig, PadroneRuntime } from './runtime.ts';
+export { REPL_SIGINT } from './runtime.ts';
+export type { InferArgsInput, InferArgsOutput, InferCommand } from './type-helpers.ts';
 export type {
+  AnyPadroneBuilder,
   AnyPadroneCommand,
   AnyPadroneProgram,
+  AsyncPadroneSchema,
+  PadroneActionContext,
   PadroneBuilder,
   PadroneCommand,
-  PadroneCommandConfig,
   PadroneCommandResult,
-  PadroneParseOptions,
   PadroneParseResult,
+  PadronePlugin,
   PadroneProgram,
   PadroneSchema,
 } from './types.ts';
+export type { UpdateCheckConfig } from './update-check.ts';
 export type { WrapConfig, WrapResult } from './wrap.ts';

package/src/interactive.ts

@@ -0,0 +1,169 @@
+import type { InteractivePromptConfig, ResolvedPadroneRuntime } from './runtime.ts';
+import type { AnyPadroneCommand } from './types.ts';
+
+/**
+ * Auto-detect the prompt type for a field based on its JSON schema property definition.
+ */
+export function detectPromptConfig(
+  name: string,
+  propSchema: Record<string, any> | undefined,
+  description?: string,
+): InteractivePromptConfig {
+  const message = description || propSchema?.description || name;
+
+  if (!propSchema) return { name, message, type: 'input' };
+
+  if (propSchema.type === 'boolean') {
+    return { name, message, type: 'confirm', default: propSchema.default };
+  }
+
+  if (propSchema.enum) {
+    return {
+      name,
+      message,
+      type: 'select',
+      choices: propSchema.enum.map((v: unknown) => ({ label: String(v), value: v })),
+      default: propSchema.default,
+    };
+  }
+
+  if (propSchema.type === 'array' && propSchema.items?.enum) {
+    return {
+      name,
+      message,
+      type: 'multiselect',
+      choices: propSchema.items.enum.map((v: unknown) => ({ label: String(v), value: v })),
+      default: propSchema.default,
+    };
+  }
+
+  if (propSchema.format === 'password') {
+    return { name, message, type: 'password', default: propSchema.default };
+  }
+
+  return { name, message, type: 'input', default: propSchema.default };
+}
+
+/**
+ * Prompt for missing interactive fields.
+ * Runs after env/config preprocessing and before schema validation.
+ *
+ * When `force` is true, all configured interactive fields are prompted even if they already
+ * have values. The current values are used as defaults in the prompts.
+ */
+export async function promptInteractiveFields(
+  data: Record<string, unknown>,
+  command: AnyPadroneCommand,
+  runtime: ResolvedPadroneRuntime,
+  force?: boolean,
+): Promise<Record<string, unknown>> {
+  if (!runtime.prompt) return data;
+
+  const meta = command.meta;
+  const interactiveConfig = meta?.interactive;
+  const optionalInteractiveConfig = meta?.optionalInteractive;
+  if (!interactiveConfig && !optionalInteractiveConfig) return data;
+
+  // Extract JSON schema properties for prompt type detection
+  let jsonProperties: Record<string, any> = {};
+  let requiredFields: Set<string> = new Set();
+  if (command.argsSchema) {
+    try {
+      const jsonSchema = command.argsSchema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+      if (jsonSchema.type === 'object' && jsonSchema.properties) {
+        jsonProperties = jsonSchema.properties;
+      }
+      if (Array.isArray(jsonSchema.required)) {
+        requiredFields = new Set(jsonSchema.required);
+      }
+    } catch {
+      // Ignore schema parsing errors
+    }
+  }
+
+  const fieldDescriptions: Record<string, string | undefined> = {};
+  if (meta?.fields) {
+    for (const [key, value] of Object.entries(meta.fields)) {
+      if (value?.description) fieldDescriptions[key] = value.description;
+    }
+  }
+
+  const result = { ...data };
+
+  // Determine which required interactive fields to prompt
+  let fieldsToPrompt: string[] = [];
+  if (interactiveConfig === true) {
+    if (force) {
+      // When forced, prompt all required fields regardless of current value
+      fieldsToPrompt = [...requiredFields];
+    } else {
+      // All required fields that are missing
+      fieldsToPrompt = [...requiredFields].filter((name) => result[name] === undefined);
+    }
+  } else if (Array.isArray(interactiveConfig)) {
+    if (force) {
+      fieldsToPrompt = [...interactiveConfig];
+    } else {
+      fieldsToPrompt = interactiveConfig.filter((name) => result[name] === undefined);
+    }
+  }
+
+  // Prompt each required interactive field
+  for (const field of fieldsToPrompt) {
+    const config = detectPromptConfig(field, jsonProperties[field], fieldDescriptions[field]);
+    // When forced, use the current value as the default
+    if (force && result[field] !== undefined) {
+      config.default = result[field];
+    }
+    result[field] = await runtime.prompt(config);
+  }
+
+  // Determine optional interactive fields
+  let optionalFields: string[] = [];
+  if (optionalInteractiveConfig === true) {
+    if (force) {
+      // When forced, include all non-required fields (even those with values)
+      const allKeys = Object.keys(jsonProperties);
+      optionalFields = allKeys.filter((name) => !requiredFields.has(name));
+    } else {
+      // All non-required fields that are still missing
+      const allKeys = Object.keys(jsonProperties);
+      optionalFields = allKeys.filter((name) => !requiredFields.has(name) && result[name] === undefined);
+    }
+  } else if (Array.isArray(optionalInteractiveConfig)) {
+    if (force) {
+      optionalFields = [...optionalInteractiveConfig];
+    } else {
+      optionalFields = optionalInteractiveConfig.filter((name) => result[name] === undefined);
+    }
+  }
+
+  // Show multiselect for optional fields, then prompt selected ones
+  if (optionalFields.length > 0) {
+    const selected = (await runtime.prompt({
+      name: '_optionalFields',
+      message: 'Would you also like to configure:',
+      type: 'multiselect',
+      choices: optionalFields.map((f) => {
+        const label = fieldDescriptions[f] || jsonProperties[f]?.description || f;
+        const currentValue = result[f];
+        // When forced, show current value next to the label for fields that already have values
+        const displayLabel = force && currentValue !== undefined ? `${label} (current: ${currentValue})` : label;
+        return { label: displayLabel, value: f };
+      }),
+    })) as string[];
+
+    if (Array.isArray(selected)) {
+      for (const field of selected) {
+        const config = detectPromptConfig(field, jsonProperties[field], fieldDescriptions[field]);
+        // When forced, use the current value as the default
+        if (force && result[field] !== undefined) {
+          config.default = result[field];
+        }
+        result[field] = await runtime.prompt(config);
+      }
+    }
+  }
+
+  return result;
+}

package/src/parse.ts

@@ -19,20 +19,20 @@ type ParseParts = {
     value: string;
   };
   /**
-   * An option provided to the command, prefixed with `--`.
-   * If the option has an `=` sign, the value after it is used as the option's value.
+   * An arg provided to the command, prefixed with `--`.
+   * If the arg has an `=` sign, the value after it is used as the arg's value.
    * Otherwise, the value is obtained from the next part or set to `true` if no value is provided.
-   * The key is an array representing the path for nested options (e.g., `--user.id=123` becomes `['user', 'id']`).
+   * The key is an array representing the path for nested args (e.g., `--user.id=123` becomes `['user', 'id']`).
    */
-  option: {
-    type: 'option';
+  named: {
+    type: 'named';
     key: string[];
     value?: string | string[];
     negated?: boolean;
   };
   /**
-   * An alias option provided to the command, prefixed with `-`.
-   * Which option it maps to cannot be determined until the command structure is known.
+   * An alias arg provided to the command, prefixed with `-`.
+   * Which arg it maps to cannot be determined until the command structure is known.
    * Aliases cannot be nested, so the key is always a single-element array.
    */
   alias: {
@@ -112,36 +112,67 @@ export function parseCliInputToParts(input: string): ParsePart[] {
   const parts = tokenizeInput(input.trim());
   const result: ParsePart[] = [];
 
-  let pendingValue: ParseParts['option'] | ParseParts['alias'] | undefined;
+  let pendingValue: ParseParts['named'] | ParseParts['alias'] | undefined;
   let allowTerm = true;
+  let afterDoubleDash = false;
 
   for (const part of parts) {
     if (!part) continue;
+
+    // Bare `--` separator: everything after is a literal positional arg
+    if (part === '--' && !afterDoubleDash) {
+      if (pendingValue) pendingValue = undefined;
+      afterDoubleDash = true;
+      allowTerm = false;
+      continue;
+    }
+
+    if (afterDoubleDash) {
+      result.push({ type: 'arg', value: part });
+      continue;
+    }
+
     const wasPending = pendingValue;
     pendingValue = undefined;
 
     if (part.startsWith('--no-') && part.length > 5) {
-      // Negated boolean option (--no-verbose or --no-config.debug)
+      // Negated boolean arg (--no-verbose or --no-config.debug)
       const keyStr = part.slice(5);
       const key = keyStr.split('.');
-      const p = { type: 'option' as const, key, value: undefined, negated: true };
+      const p = { type: 'named' as const, key, value: undefined, negated: true };
       result.push(p);
     } else if (part.startsWith('--')) {
-      const [keyStr = '', value] = splitOptionValue(part.slice(2));
+      const [keyStr = '', value] = splitNamedArgValue(part.slice(2));
       const key = keyStr.split('.');
 
-      const p = { type: 'option' as const, key, value };
+      const p = { type: 'named' as const, key, value };
       if (typeof value === 'undefined') pendingValue = p;
       result.push(p);
     } else if (part.startsWith('-') && part.length > 1 && !/^-\d/.test(part)) {
-      // Short option (but not negative numbers like -5)
-      // Aliases cannot be nested, so key is always a single-element array
-      const [keyStr = '', value] = splitOptionValue(part.slice(1));
-      const key = [keyStr];
+      // Short flag(s) (but not negative numbers like -5)
+      // Supports flag stacking: -abc → -a -b -c (last flag can take a value)
+      const [keyStr = '', value] = splitNamedArgValue(part.slice(1));
 
-      const p = { type: 'alias' as const, key, value };
-      if (typeof value === 'undefined') pendingValue = p;
-      result.push(p);
+      if (keyStr.length > 1 && typeof value === 'undefined') {
+        // Flag stacking: -abc → -a, -b, -c (all set to true except last which can take next arg's value)
+        for (let ci = 0; ci < keyStr.length - 1; ci++) {
+          result.push({ type: 'alias' as const, key: [keyStr[ci]!], value: undefined });
+        }
+        const lastFlag = { type: 'alias' as const, key: [keyStr[keyStr.length - 1]!], value: undefined as string | string[] | undefined };
+        pendingValue = lastFlag;
+        result.push(lastFlag);
+      } else if (keyStr.length > 1 && typeof value !== 'undefined') {
+        // -abc=val → -a, -b, -c=val (stacked with value on last)
+        for (let ci = 0; ci < keyStr.length - 1; ci++) {
+          result.push({ type: 'alias' as const, key: [keyStr[ci]!], value: undefined });
+        }
+        result.push({ type: 'alias' as const, key: [keyStr[keyStr.length - 1]!], value });
+      } else {
+        // Single char: -v or -v=value
+        const p = { type: 'alias' as const, key: [keyStr], value };
+        if (typeof value === 'undefined') pendingValue = p;
+        result.push(p);
+      }
     } else if (wasPending) {
       wasPending.value = part;
     } else if (/^[a-zA-Z0-9_-]+$/.test(part) && allowTerm) {
@@ -155,9 +186,9 @@ export function parseCliInputToParts(input: string): ParsePart[] {
 }
 
 /**
- * Split option key and value, handling quoted values after =.
+ * Split named arg key and value, handling quoted values after =.
  */
-function splitOptionValue(str: string): [string, string | string[] | undefined] {
+function splitNamedArgValue(str: string): [string, string | string[] | undefined] {
   const eqIndex = str.indexOf('=');
   if (eqIndex === -1) return [str, undefined];