politty 0.9.2 → 0.10.1

package/dist/{arg-registry-DDJpsUea.d.ts → arg-registry-BN3I-XON.d.ts}

@@ -228,6 +228,8 @@ interface Logger {
   log(message: string): void;
   /** Log error message to stderr */
   error(message: string): void;
+  /** Log warning message to stderr */
+  warn?(message: string): void;
 }
 /**
  * Supported schema types for args
@@ -939,4 +941,4 @@ declare function arg<T extends z.ZodType>(schema: T): T;
 declare function arg<T extends z.ZodType, M extends ArgMeta<z.output<T>>>(schema: T, meta: ValidateArgMeta<M, z.output<T>>): T;
 //#endregion
 export { toKebabCase as $, LogStream as A, SetupContext as B, Example as C, IsEmpty as D, GlobalSetupContext as E, RunCommandOptions as F, isLazyCommand as G, SubCommandsRecord as H, RunResult as I, ResolvedFieldMeta as J, lazy as K, RunResultFailure as L, MainOptions as M, NonRunnableCommand as N, LogEntry as O, PromptResolver as P, toCamelCase as Q, RunResultSuccess as R, CommandBase as S, GlobalCleanupContext as T, UnknownSubcommandHandler as U, SubCommandValue as V, LazyCommand as W, extractFields as X, UnknownKeysMode as Y, getUnknownKeysMode as Z, AnyCommand as _, EffectContext as a, CollectedLogs as b, arg as c, ResolvedExpandCandidate as d, CompletionDirectiveMask as f, DynamicCompletionResult as g, DynamicCompletionResolver as h, CustomCompletion as i, Logger as j, LogLevel as k, ExpandCandidate as l, DynamicCompletionContext as m, CompletionMeta as n, PromptMeta as o, DynamicCompletionCandidate as p, ExtractedFields as q, CompletionType as r, PromptType as s, ArgMeta as t, ExpandCompletion as u, ArgsSchema as v, GlobalArgs as w, Command as x, CleanupContext as y, RunnableCommand as z };
-//# sourceMappingURL=arg-registry-DDJpsUea.d.ts.map
+//# sourceMappingURL=arg-registry-BN3I-XON.d.ts.map

package/dist/augment.d.ts

@@ -1,4 +1,4 @@
-import { t as ArgMeta } from "./arg-registry-DDJpsUea.js";
+import { t as ArgMeta } from "./arg-registry-BN3I-XON.js";
 
 //#region src/augment.d.ts
 declare module "zod" {

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as runMain } from "./runner-BmWR9TLM.js";
+import { n as runMain } from "./runner-BCMB67GV.js";
 import { t as arg } from "./arg-registry-BeLLAW5-.js";
 import { n as defineCommand } from "./command-B4yA4LXX.js";
 import { p as generateBundledCompletionWorker } from "./completion-DwTFOtQk.js";

package/dist/completion/index.d.ts

@@ -1,3 +1,3 @@
-import { f as CompletionDirectiveMask, g as DynamicCompletionResult, h as DynamicCompletionResolver, m as DynamicCompletionContext, p as DynamicCompletionCandidate } from "../arg-registry-DDJpsUea.js";
-import { A as BundledWorkerOptions, C as CandidateResult, D as CompletionContext, E as generateCandidates, F as CompletionMode, I as CompletionOptions, L as CompletionResult, M as CompletableSubcommand, N as CompletionData, O as CompletionType, P as CompletionGenerator, R as ShellType, S as hasCompleteCommand, T as CompletionDirective, _ as extractCompletionData, a as detectShell, b as formatForShell, c as withCompletionCommand, d as GenerateBundledCompletionWorkerOptions, f as GenerateBundledCompletionWorkerResult, g as validateBundledWorkerFile, h as generateBundledCompletionWorker, i as createRefreshCompletionCommand, j as CompletableOption, k as parseCompletionContext, l as ValueCompletionField, m as defaultBundledWorkerOutputPath, n as createCompletionCommand, o as generateCompletion, p as bundledWorkerShellExtension, r as createCompletionWorkerPathCommand, s as getSupportedShells, t as WithCompletionOptions, u as resolveValueCompletion, v as extractPositionals, w as CompletionCandidate, x as createDynamicCompleteCommand, y as ShellFormatOptions } from "../index-DKGn3lIl.js";
+import { f as CompletionDirectiveMask, g as DynamicCompletionResult, h as DynamicCompletionResolver, m as DynamicCompletionContext, p as DynamicCompletionCandidate } from "../arg-registry-BN3I-XON.js";
+import { A as BundledWorkerOptions, C as CandidateResult, D as CompletionContext, E as generateCandidates, F as CompletionMode, I as CompletionOptions, L as CompletionResult, M as CompletableSubcommand, N as CompletionData, O as CompletionType, P as CompletionGenerator, R as ShellType, S as hasCompleteCommand, T as CompletionDirective, _ as extractCompletionData, a as detectShell, b as formatForShell, c as withCompletionCommand, d as GenerateBundledCompletionWorkerOptions, f as GenerateBundledCompletionWorkerResult, g as validateBundledWorkerFile, h as generateBundledCompletionWorker, i as createRefreshCompletionCommand, j as CompletableOption, k as parseCompletionContext, l as ValueCompletionField, m as defaultBundledWorkerOutputPath, n as createCompletionCommand, o as generateCompletion, p as bundledWorkerShellExtension, r as createCompletionWorkerPathCommand, s as getSupportedShells, t as WithCompletionOptions, u as resolveValueCompletion, v as extractPositionals, w as CompletionCandidate, x as createDynamicCompleteCommand, y as ShellFormatOptions } from "../index-CtRrTVTL.js";
 export { type BundledWorkerOptions, type CandidateResult, type CompletableOption, type CompletableSubcommand, type CompletionCandidate, type CompletionContext, type CompletionData, CompletionDirective, type CompletionDirectiveMask, type CompletionGenerator, type CompletionMode, type CompletionOptions, type CompletionResult, type CompletionType, type DynamicCompletionCandidate, type DynamicCompletionContext, type DynamicCompletionResolver, type DynamicCompletionResult, type GenerateBundledCompletionWorkerOptions, type GenerateBundledCompletionWorkerResult, type ShellFormatOptions, type ShellType, type ValueCompletionField, WithCompletionOptions, bundledWorkerShellExtension, createCompletionCommand, createCompletionWorkerPathCommand, createDynamicCompleteCommand, createRefreshCompletionCommand, defaultBundledWorkerOutputPath, detectShell, extractCompletionData, extractPositionals, formatForShell, generateBundledCompletionWorker, generateCandidates, generateCompletion, getSupportedShells, hasCompleteCommand, parseCompletionContext, resolveValueCompletion, validateBundledWorkerFile, withCompletionCommand };

package/dist/docs/index.d.ts

@@ -1,4 +1,4 @@
-import { C as Example, J as ResolvedFieldMeta, V as SubCommandValue, _ as AnyCommand, q as ExtractedFields, v as ArgsSchema } from "../arg-registry-DDJpsUea.js";
+import { C as Example, J as ResolvedFieldMeta, V as SubCommandValue, _ as AnyCommand, q as ExtractedFields, v as ArgsSchema } from "../arg-registry-BN3I-XON.js";
 import { z } from "zod";
 import * as fs from "node:fs";
 
@@ -11,6 +11,12 @@ import * as fs from "node:fs";
  */
 declare function resolveLazyCommand(cmd: SubCommandValue): Promise<AnyCommand>;
 //#endregion
+//#region src/docs/option-rows.d.ts
+/**
+ * Column identifiers for the options markdown table, in their canonical order.
+ */
+type ColumnId = "option" | "alias" | "description" | "required" | "default" | "env";
+//#endregion
 //#region src/docs/render-args.d.ts
 /**
  * Args shape type (Record of string keys to Zod schemas)
@@ -21,7 +27,7 @@ type ArgsShape = Record<string, z.ZodType>;
  * Options for rendering args table
  */
 type ArgsTableOptions = {
-  /** Columns to include in the table (default: all columns) */columns?: ("option" | "alias" | "description" | "required" | "default" | "env")[];
+  /** Columns to include in the table (default: all columns) */columns?: ColumnId[];
 };
 /**
  * Render args definition as a markdown options table

package/dist/docs/index.js

@@ -6,6 +6,204 @@ import * as path$1 from "node:path";
 import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 
+//#region src/docs/option-rows.ts
+/** Canonical column order used when no explicit column subset is requested. */
+const DEFAULT_COLUMNS = [
+	"option",
+	"alias",
+	"description",
+	"required",
+	"default"
+];
+/**
+* Marker appended to a custom negation row/line so readers can see which
+* positive flag it negates (e.g. `--monochrome` → ``(↔ `--color`)``).
+*/
+function negationRelationMarker(opt) {
+	return `(↔ \`--${opt.cliName}\`)`;
+}
+/**
+* Resolve placeholder for an option (uses kebab-case cliName).
+*/
+function resolvePlaceholder(opt) {
+	return opt.placeholder ?? opt.cliName.toUpperCase().replace(/-/g, "_");
+}
+/**
+* Normalize a single {@link ResolvedFieldMeta} into an {@link OptionRow}.
+*/
+function toOptionRow(opt) {
+	const longFlag = opt.type === "boolean" ? `--${opt.cliName}` : `--${opt.cliName} <${resolvePlaceholder(opt)}>`;
+	const aliases = [];
+	if (opt.alias) for (const a of opt.alias) aliases.push(a.length === 1 ? `-${a}` : `--${a}`);
+	const hasNegationDisplay = opt.type === "boolean" && !!opt.negationDisplay;
+	const inlineNegation = hasNegationDisplay && !opt.negationDescription ? `--${opt.negationDisplay}` : void 0;
+	const negationRow = hasNegationDisplay && opt.negationDescription ? {
+		flag: `--${opt.negationDisplay}`,
+		description: opt.negationDescription,
+		relationMarker: negationRelationMarker(opt),
+		required: opt.required
+	} : void 0;
+	return {
+		longFlag,
+		aliases,
+		inlineNegation,
+		description: opt.description,
+		required: opt.required,
+		hasDefault: opt.defaultValue !== void 0,
+		defaultValue: opt.defaultValue,
+		env: opt.env,
+		negationRow
+	};
+}
+/**
+* Build the normalized intermediate representation for a list of options.
+* This is the single source of truth for per-option display decisions; the
+* emitters below ({@link emitMarkdownTable}, {@link emitMarkdownList}) are pure
+* formatting.
+*/
+function toOptionRows(options) {
+	return options.map(toOptionRow);
+}
+/**
+* Escape markdown special characters in table cells.
+*/
+function escapeTableCell$2(str) {
+	return str.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+function backtick(value) {
+	return `\`${value}\``;
+}
+/**
+* Format default value for table display.
+*/
+function formatDefaultValue(row) {
+	if (!row.hasDefault) return "-";
+	return `\`${JSON.stringify(row.defaultValue)}\``;
+}
+/**
+* Format env variable names for a markdown table cell.
+*/
+function formatEnvNames(env) {
+	if (!env) return "-";
+	if (Array.isArray(env)) return env.map((e) => `\`${e}\``).join(", ");
+	return `\`${env}\``;
+}
+/**
+* Format env variable info for a markdown list item (e.g. `[env: PORT, SERVER_PORT]`).
+*/
+function formatEnvInfo(env) {
+	if (!env) return "";
+	return ` [env: ${(Array.isArray(env) ? env : [env]).join(", ")}]`;
+}
+/** Header label + separator dashes for each column, matching legacy widths. */
+const COLUMN_META = {
+	option: {
+		header: "Option",
+		separator: "--------"
+	},
+	alias: {
+		header: "Alias",
+		separator: "-------"
+	},
+	description: {
+		header: "Description",
+		separator: "-------------"
+	},
+	required: {
+		header: "Required",
+		separator: "----------"
+	},
+	default: {
+		header: "Default",
+		separator: "---------"
+	},
+	env: {
+		header: "Env",
+		separator: "-----"
+	}
+};
+/**
+* Render the table cell for a base option row in the given column.
+*/
+function tableCell(row, col) {
+	switch (col) {
+		case "option": {
+			const name = backtick(row.longFlag);
+			return row.inlineNegation ? `${name} / ${backtick(row.inlineNegation)}` : name;
+		}
+		case "alias": return row.aliases.length > 0 ? row.aliases.map(backtick).join(", ") : "-";
+		case "description": return escapeTableCell$2(row.description ?? "");
+		case "required": return row.required ? "Yes" : "No";
+		case "default": return formatDefaultValue(row);
+		case "env": return formatEnvNames(row.env);
+	}
+}
+/**
+* Render the table cell for a negation row in the given column.
+*/
+function negationTableCell(neg, col) {
+	switch (col) {
+		case "option": return backtick(neg.flag);
+		case "description": return `${escapeTableCell$2(neg.description)} ${neg.relationMarker}`;
+		case "required": return neg.required ? "Yes" : "No";
+		case "alias":
+		case "default":
+		case "env": return "-";
+	}
+}
+/**
+* Emit option rows as a markdown table.
+*
+* When `columns` is omitted, the canonical column set is used and the `Env`
+* column is appended automatically iff any row has env configured. When
+* `columns` is provided, exactly those columns are emitted, in that order.
+*
+* The separator row always uses the canonical fixed-width dashes from
+* {@link COLUMN_META}, so every table — default or column-filtered — shares a
+* single, consistent format.
+*/
+function emitMarkdownTable(rows, columns) {
+	if (rows.length === 0) return "";
+	const cols = columns ?? (rows.some((r) => r.env) ? [...DEFAULT_COLUMNS, "env"] : DEFAULT_COLUMNS);
+	const lines = [];
+	lines.push(`| ${cols.map((c) => COLUMN_META[c].header).join(" | ")} |`);
+	lines.push(`|${cols.map((c) => COLUMN_META[c].separator).join("|")}|`);
+	for (const row of rows) {
+		lines.push(`| ${cols.map((c) => tableCell(row, c)).join(" | ")} |`);
+		if (row.negationRow) lines.push(`| ${cols.map((c) => negationTableCell(row.negationRow, c)).join(" | ")} |`);
+	}
+	return lines.join("\n");
+}
+/**
+* Emit option rows as a markdown list.
+*
+* Aliases are joined with `, ` (short flags first, then the long flag, then
+* long aliases); the inline negation is appended with ` / ` so it stays
+* visually distinct from aliases.
+*/
+function emitMarkdownList(rows) {
+	if (rows.length === 0) return "";
+	const lines = [];
+	for (const row of rows) {
+		const shortAliases = row.aliases.filter((a) => !a.startsWith("--"));
+		const longAliases = row.aliases.filter((a) => a.startsWith("--"));
+		let flags = [
+			...shortAliases,
+			row.longFlag,
+			...longAliases
+		].map(backtick).join(", ");
+		if (row.inlineNegation) flags += ` / ${backtick(row.inlineNegation)}`;
+		const desc = row.description ? ` - ${row.description}` : "";
+		const required = row.required ? " (required)" : "";
+		const defaultVal = row.hasDefault ? ` (default: ${JSON.stringify(row.defaultValue)})` : "";
+		const envInfo = formatEnvInfo(row.env);
+		lines.push(`- ${flags}${desc}${required}${defaultVal}${envInfo}`);
+		if (row.negationRow) lines.push(`- ${backtick(row.negationRow.flag)} - ${row.negationRow.description} ${row.negationRow.relationMarker}`);
+	}
+	return lines.join("\n");
+}
+
+//#endregion
 //#region src/docs/types.ts
 /**
 * Environment variable name for update mode
@@ -108,24 +306,10 @@ function indexEndMarker(scope) {
 /**
 * Escape markdown special characters in table cells
 */
-function escapeTableCell$2(str) {
+function escapeTableCell$1(str) {
 	return str.replace(/\|/g, "\\|").replace(/\n/g, " ");
 }
 /**
-* Marker appended to a custom negation row/line so readers can see which
-* positive flag it negates (e.g. `--monochrome` → `(↔ \`--color\`)`).
-*/
-function negationRelationMarker(opt) {
-	return `(↔ \`--${opt.cliName}\`)`;
-}
-/**
-* Format default value for display
-*/
-function formatDefaultValue$1(value) {
-	if (value === void 0) return "-";
-	return `\`${JSON.stringify(value)}\``;
-}
-/**
 * Render usage line
 */
 function renderUsage(info) {
@@ -146,7 +330,7 @@ function renderArgumentsTable(info) {
 	lines.push("| Argument | Description | Required |");
 	lines.push("|----------|-------------|----------|");
 	for (const arg of info.positionalArgs) {
-		const desc = escapeTableCell$2(arg.description ?? "");
+		const desc = escapeTableCell$1(arg.description ?? "");
 		const required = arg.required ? "Yes" : "No";
 		lines.push(`| \`${arg.name}\` | ${desc} | ${required} |`);
 	}
@@ -166,70 +350,6 @@ function renderArgumentsList(info) {
 	return lines.join("\n");
 }
 /**
-* Format environment variable info for display
-*/
-function formatEnvInfo(env) {
-	if (!env) return "";
-	return ` [env: ${(Array.isArray(env) ? env : [env]).join(", ")}]`;
-}
-/**
-* Resolve placeholder for an option (uses kebab-case cliName)
-*/
-function resolvePlaceholder(opt) {
-	return opt.placeholder ?? opt.cliName.toUpperCase().replace(/-/g, "_");
-}
-/**
-* Format option name for table display (e.g., `--dry-run` or `--port <PORT>`)
-*
-* Boolean fields with a custom inline `negation` (no separate description) are
-* shown as `\`--cache\` / \`--disable-cache\``.
-*/
-function formatOptionName(opt) {
-	const placeholder = resolvePlaceholder(opt);
-	if (opt.type === "boolean") {
-		const positive = `\`--${opt.cliName}\``;
-		if (opt.negationDisplay && !opt.negationDescription) return `${positive} / \`--${opt.negationDisplay}\``;
-		return positive;
-	}
-	return `\`--${opt.cliName} <${placeholder}>\``;
-}
-/**
-* Format option flags for list display (uses kebab-case cliName).
-* Aliases are joined with `, `; the inline negation (when no separate
-* `negationDescription` is set) is appended with ` / ` so it stays
-* visually distinct from aliases, matching help and table output.
-*/
-function formatOptionFlags(opt) {
-	const placeholder = resolvePlaceholder(opt);
-	const longFlag = opt.type === "boolean" ? `--${opt.cliName}` : `--${opt.cliName} <${placeholder}>`;
-	const parts = [];
-	if (opt.alias) {
-		for (const a of opt.alias) if (a.length === 1) parts.push(`\`-${a}\``);
-	}
-	parts.push(`\`${longFlag}\``);
-	if (opt.alias) {
-		for (const a of opt.alias) if (a.length > 1) parts.push(`\`--${a}\``);
-	}
-	const aliasJoined = parts.join(", ");
-	if (opt.type === "boolean" && opt.negationDisplay && !opt.negationDescription) return `${aliasJoined} / \`--${opt.negationDisplay}\``;
-	return aliasJoined;
-}
-/**
-* Format aliases for a markdown table cell
-*/
-function formatAliasCell(alias) {
-	if (!alias || alias.length === 0) return "-";
-	return alias.map((a) => `\`${a.length === 1 ? `-${a}` : `--${a}`}\``).join(", ");
-}
-/**
-* Format env variable names for table display
-*/
-function formatEnvNames(env) {
-	if (!env) return "-";
-	if (Array.isArray(env)) return env.map((e) => `\`${e}\``).join(", ");
-	return `\`${env}\``;
-}
-/**
 * Render options as markdown table
 *
 * Features:
@@ -244,34 +364,7 @@ function formatEnvNames(env) {
 * | `--port <PORT>` | - | Server port | Yes | - | `PORT`, `SERVER_PORT` |
 */
 function renderOptionsTable(info) {
-	if (info.options.length === 0) return "";
-	const hasEnv = info.options.some((opt) => opt.env);
-	const lines = [];
-	if (hasEnv) {
-		lines.push("| Option | Alias | Description | Required | Default | Env |");
-		lines.push("|--------|-------|-------------|----------|---------|-----|");
-	} else {
-		lines.push("| Option | Alias | Description | Required | Default |");
-		lines.push("|--------|-------|-------------|----------|---------|");
-	}
-	for (const opt of info.options) {
-		const optionName = formatOptionName(opt);
-		const alias = formatAliasCell(opt.alias);
-		const desc = escapeTableCell$2(opt.description ?? "");
-		const required = opt.required ? "Yes" : "No";
-		const defaultVal = formatDefaultValue$1(opt.defaultValue);
-		if (hasEnv) {
-			const envNames = formatEnvNames(opt.env);
-			lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} | ${envNames} |`);
-		} else lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} |`);
-		if (opt.type === "boolean" && opt.negationDisplay && opt.negationDescription) {
-			const negName = `\`--${opt.negationDisplay}\``;
-			const negDesc = `${escapeTableCell$2(opt.negationDescription)} ${negationRelationMarker(opt)}`;
-			if (hasEnv) lines.push(`| ${negName} | - | ${negDesc} | ${required} | - | - |`);
-			else lines.push(`| ${negName} | - | ${negDesc} | ${required} | - |`);
-		}
-	}
-	return lines.join("\n");
+	return emitMarkdownTable(toOptionRows(info.options));
 }
 /**
 * Render options as markdown list
@@ -285,18 +378,7 @@ function renderOptionsTable(info) {
 * - `--port <PORT>` - Server port (required) [env: PORT, SERVER_PORT]
 */
 function renderOptionsList(info) {
-	if (info.options.length === 0) return "";
-	const lines = [];
-	for (const opt of info.options) {
-		const flags = formatOptionFlags(opt);
-		const desc = opt.description ? ` - ${opt.description}` : "";
-		const required = opt.required ? " (required)" : "";
-		const defaultVal = opt.defaultValue !== void 0 ? ` (default: ${JSON.stringify(opt.defaultValue)})` : "";
-		const envInfo = formatEnvInfo(opt.env);
-		lines.push(`- ${flags}${desc}${required}${defaultVal}${envInfo}`);
-		if (opt.type === "boolean" && opt.negationDisplay && opt.negationDescription) lines.push(`- \`--${opt.negationDisplay}\` - ${opt.negationDescription} ${negationRelationMarker(opt)}`);
-	}
-	return lines.join("\n");
+	return emitMarkdownList(toOptionRows(info.options));
 }
 /**
 * Generate anchor from command path
@@ -323,34 +405,7 @@ function renderSubcommandsTable(info, generateAnchors = true) {
 * Render options from array as table
 */
 function renderOptionsTableFromArray(options) {
-	if (options.length === 0) return "";
-	const hasEnv = options.some((opt) => opt.env);
-	const lines = [];
-	if (hasEnv) {
-		lines.push("| Option | Alias | Description | Required | Default | Env |");
-		lines.push("|--------|-------|-------------|----------|---------|-----|");
-	} else {
-		lines.push("| Option | Alias | Description | Required | Default |");
-		lines.push("|--------|-------|-------------|----------|---------|");
-	}
-	for (const opt of options) {
-		const optionName = formatOptionName(opt);
-		const alias = formatAliasCell(opt.alias);
-		const desc = escapeTableCell$2(opt.description ?? "");
-		const required = opt.required ? "Yes" : "No";
-		const defaultVal = formatDefaultValue$1(opt.defaultValue);
-		if (hasEnv) {
-			const envNames = formatEnvNames(opt.env);
-			lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} | ${envNames} |`);
-		} else lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} |`);
-		if (opt.type === "boolean" && opt.negationDisplay && opt.negationDescription) {
-			const negName = `\`--${opt.negationDisplay}\``;
-			const negDesc = `${escapeTableCell$2(opt.negationDescription)} ${negationRelationMarker(opt)}`;
-			if (hasEnv) lines.push(`| ${negName} | - | ${negDesc} | ${required} | - | - |`);
-			else lines.push(`| ${negName} | - | ${negDesc} | ${required} | - |`);
-		}
-	}
-	return lines.join("\n");
+	return emitMarkdownTable(toOptionRows(options));
 }
 /**
 * Render union/xor options as markdown with variant grouping
@@ -421,18 +476,7 @@ function renderDiscriminatedUnionOptionsMarkdown(extracted, style = "table") {
 * Render options from array as list
 */
 function renderOptionsListFromArray(options) {
-	if (options.length === 0) return "";
-	const lines = [];
-	for (const opt of options) {
-		const flags = formatOptionFlags(opt);
-		const desc = opt.description ? ` - ${opt.description}` : "";
-		const required = opt.required ? " (required)" : "";
-		const defaultVal = opt.defaultValue !== void 0 ? ` (default: ${JSON.stringify(opt.defaultValue)})` : "";
-		const envInfo = formatEnvInfo(opt.env);
-		lines.push(`- ${flags}${desc}${required}${defaultVal}${envInfo}`);
-		if (opt.type === "boolean" && opt.negationDisplay && opt.negationDescription) lines.push(`- \`--${opt.negationDisplay}\` - ${opt.negationDescription} ${negationRelationMarker(opt)}`);
-	}
-	return lines.join("\n");
+	return emitMarkdownList(toOptionRows(options));
 }
 /**
 * Render arguments from array as table
@@ -443,7 +487,7 @@ function renderArgumentsTableFromArray(args) {
 	lines.push("| Argument | Description | Required |");
 	lines.push("|----------|-------------|----------|");
 	for (const arg of args) {
-		const desc = escapeTableCell$2(arg.description ?? "");
+		const desc = escapeTableCell$1(arg.description ?? "");
 		const required = arg.required ? "Yes" : "No";
 		lines.push(`| \`${arg.name}\` | ${desc} | ${required} |`);
 	}
@@ -480,9 +524,9 @@ function renderSubcommandsTableFromArray(subcommands, info, generateAnchors = tr
 	const fileMap = info.fileMap;
 	for (const sub of subcommands) {
 		const fullName = sub.fullPath.join(" ");
-		const desc = escapeTableCell$2(sub.description ?? "");
+		const desc = escapeTableCell$1(sub.description ?? "");
 		const subCommandPath = sub.fullPath.join(" ");
-		const aliasCell = hasAliases ? sub.aliases && sub.aliases.length > 0 ? sub.aliases.map((a) => `\`${escapeTableCell$2(a)}\``).join(", ") : "-" : "";
+		const aliasCell = hasAliases ? sub.aliases && sub.aliases.length > 0 ? sub.aliases.map((a) => `\`${escapeTableCell$1(a)}\``).join(", ") : "-" : "";
 		let cmdCell;
 		if (generateAnchors) {
 			const anchor = generateAnchor$1(sub.fullPath);
@@ -875,7 +919,7 @@ async function executeSingleExample(example, rootCommand, commandPath) {
 	collector.start();
 	let success = true;
 	try {
-		const { runCommand } = await import("../runner-BmWR9TLM.js").then((n) => n.r);
+		const { runCommand } = await import("../runner-BCMB67GV.js").then((n) => n.r);
 		const result = await runCommand(rootCommand, argv);
 		success = result.success;
 		if (!result.success && result.error) console.error(result.error.message);
@@ -967,111 +1011,7 @@ function extractArgsFields(args) {
 function renderArgsTable(args, options) {
 	const optionFields = extractArgsFields(args).filter((f) => !f.positional);
 	if (optionFields.length === 0) return "";
-	if (options?.columns) return renderFilteredTable(optionFields, options.columns);
-	return renderOptionsTableFromArray(optionFields);
-}
-/**
-* Escape markdown special characters in table cells
-*/
-function escapeTableCell$1(str) {
-	return str.replace(/\|/g, "\\|").replace(/\n/g, " ");
-}
-/**
-* Format default value for display
-*/
-function formatDefaultValue(value) {
-	if (value === void 0) return "-";
-	return `\`${JSON.stringify(value)}\``;
-}
-/**
-* Render table with filtered columns
-*/
-function renderFilteredTable(options, columns) {
-	const lines = [];
-	const headerCells = [];
-	const separatorCells = [];
-	for (const col of columns) switch (col) {
-		case "option":
-			headerCells.push("Option");
-			separatorCells.push("------");
-			break;
-		case "alias":
-			headerCells.push("Alias");
-			separatorCells.push("-----");
-			break;
-		case "description":
-			headerCells.push("Description");
-			separatorCells.push("-----------");
-			break;
-		case "required":
-			headerCells.push("Required");
-			separatorCells.push("--------");
-			break;
-		case "default":
-			headerCells.push("Default");
-			separatorCells.push("-------");
-			break;
-		case "env":
-			headerCells.push("Env");
-			separatorCells.push("---");
-			break;
-	}
-	lines.push(`| ${headerCells.join(" | ")} |`);
-	lines.push(`| ${separatorCells.join(" | ")} |`);
-	for (const opt of options) {
-		const cells = [];
-		for (const col of columns) switch (col) {
-			case "option": {
-				const placeholder = opt.placeholder ?? opt.cliName.toUpperCase().replace(/-/g, "_");
-				let optionName;
-				if (opt.type === "boolean") {
-					optionName = `\`--${opt.cliName}\``;
-					if (opt.negationDisplay && !opt.negationDescription) optionName += ` / \`--${opt.negationDisplay}\``;
-				} else optionName = `\`--${opt.cliName} <${placeholder}>\``;
-				cells.push(optionName);
-				break;
-			}
-			case "alias":
-				cells.push(opt.alias && opt.alias.length > 0 ? opt.alias.map((a) => `\`${a.length === 1 ? `-${a}` : `--${a}`}\``).join(", ") : "-");
-				break;
-			case "description":
-				cells.push(escapeTableCell$1(opt.description ?? ""));
-				break;
-			case "required":
-				cells.push(opt.required ? "Yes" : "No");
-				break;
-			case "default":
-				cells.push(formatDefaultValue(opt.defaultValue));
-				break;
-			case "env": {
-				const envNames = opt.env ? Array.isArray(opt.env) ? opt.env.map((e) => `\`${e}\``).join(", ") : `\`${opt.env}\`` : "-";
-				cells.push(envNames);
-				break;
-			}
-		}
-		lines.push(`| ${cells.join(" | ")} |`);
-		if (opt.type === "boolean" && opt.negationDisplay && opt.negationDescription) {
-			const negCells = [];
-			for (const col of columns) switch (col) {
-				case "option":
-					negCells.push(`\`--${opt.negationDisplay}\``);
-					break;
-				case "description":
-					negCells.push(`${escapeTableCell$1(opt.negationDescription)} ${negationRelationMarker(opt)}`);
-					break;
-				case "required":
-					negCells.push(opt.required ? "Yes" : "No");
-					break;
-				case "alias":
-				case "default":
-				case "env":
-					negCells.push("-");
-					break;
-			}
-			lines.push(`| ${negCells.join(" | ")} |`);
-		}
-	}
-	return lines.join("\n");
+	return emitMarkdownTable(toOptionRows(optionFields), options?.columns);
 }
 
 //#endregion

package/dist/{index-DKGn3lIl.d.ts → index-CtRrTVTL.d.ts}

@@ -1,4 +1,4 @@
-import { J as ResolvedFieldMeta, _ as AnyCommand, d as ResolvedExpandCandidate, h as DynamicCompletionResolver, u as ExpandCompletion, v as ArgsSchema, x as Command } from "./arg-registry-DDJpsUea.js";
+import { J as ResolvedFieldMeta, _ as AnyCommand, d as ResolvedExpandCandidate, h as DynamicCompletionResolver, u as ExpandCompletion, v as ArgsSchema, x as Command } from "./arg-registry-BN3I-XON.js";
 import { z } from "zod";
 
 //#region src/completion/types.d.ts
@@ -660,4 +660,4 @@ interface WithCompletionOptions {
 declare function withCompletionCommand<T extends AnyCommand>(command: T, options?: string | WithCompletionOptions): T;
 //#endregion
 export { BundledWorkerOptions as A, CandidateResult as C, CompletionContext as D, generateCandidates as E, CompletionMode as F, CompletionOptions as I, CompletionResult as L, CompletableSubcommand as M, CompletionData as N, CompletionType as O, CompletionGenerator as P, ShellType as R, hasCompleteCommand as S, CompletionDirective as T, extractCompletionData as _, detectShell as a, formatForShell as b, withCompletionCommand as c, GenerateBundledCompletionWorkerOptions as d, GenerateBundledCompletionWorkerResult as f, validateBundledWorkerFile as g, generateBundledCompletionWorker as h, createRefreshCompletionCommand as i, CompletableOption as j, parseCompletionContext as k, ValueCompletionField as l, defaultBundledWorkerOutputPath as m, createCompletionCommand as n, generateCompletion as o, bundledWorkerShellExtension as p, createCompletionWorkerPathCommand as r, getSupportedShells as s, WithCompletionOptions as t, resolveValueCompletion as u, extractPositionals as v, CompletionCandidate as w, createDynamicCompleteCommand as x, ShellFormatOptions as y };
-//# sourceMappingURL=index-DKGn3lIl.d.ts.map
+//# sourceMappingURL=index-CtRrTVTL.d.ts.map

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { $ as toKebabCase, A as LogStream, B as SetupContext, C as Example, D as IsEmpty, E as GlobalSetupContext, F as RunCommandOptions, G as isLazyCommand, H as SubCommandsRecord, I as RunResult, J as ResolvedFieldMeta, K as lazy, L as RunResultFailure, M as MainOptions, N as NonRunnableCommand, O as LogEntry, P as PromptResolver, Q as toCamelCase, R as RunResultSuccess, S as CommandBase, T as GlobalCleanupContext, U as UnknownSubcommandHandler, V as SubCommandValue, W as LazyCommand, X as extractFields, Y as UnknownKeysMode, Z as getUnknownKeysMode, _ as AnyCommand, a as EffectContext, b as CollectedLogs, c as arg, d as ResolvedExpandCandidate, f as CompletionDirectiveMask, g as DynamicCompletionResult, h as DynamicCompletionResolver, i as CustomCompletion, j as Logger, k as LogLevel, l as ExpandCandidate, m as DynamicCompletionContext, n as CompletionMeta, o as PromptMeta, p as DynamicCompletionCandidate, q as ExtractedFields, r as CompletionType, s as PromptType, t as ArgMeta, u as ExpandCompletion, v as ArgsSchema, w as GlobalArgs, x as Command, y as CleanupContext, z as RunnableCommand } from "./arg-registry-DDJpsUea.js";
-import { I as CompletionOptions, L as CompletionResult, c as withCompletionCommand, d as GenerateBundledCompletionWorkerOptions, f as GenerateBundledCompletionWorkerResult, h as generateBundledCompletionWorker, o as generateCompletion, t as WithCompletionOptions } from "./index-DKGn3lIl.js";
+import { $ as toKebabCase, A as LogStream, B as SetupContext, C as Example, D as IsEmpty, E as GlobalSetupContext, F as RunCommandOptions, G as isLazyCommand, H as SubCommandsRecord, I as RunResult, J as ResolvedFieldMeta, K as lazy, L as RunResultFailure, M as MainOptions, N as NonRunnableCommand, O as LogEntry, P as PromptResolver, Q as toCamelCase, R as RunResultSuccess, S as CommandBase, T as GlobalCleanupContext, U as UnknownSubcommandHandler, V as SubCommandValue, W as LazyCommand, X as extractFields, Y as UnknownKeysMode, Z as getUnknownKeysMode, _ as AnyCommand, a as EffectContext, b as CollectedLogs, c as arg, d as ResolvedExpandCandidate, f as CompletionDirectiveMask, g as DynamicCompletionResult, h as DynamicCompletionResolver, i as CustomCompletion, j as Logger, k as LogLevel, l as ExpandCandidate, m as DynamicCompletionContext, n as CompletionMeta, o as PromptMeta, p as DynamicCompletionCandidate, q as ExtractedFields, r as CompletionType, s as PromptType, t as ArgMeta, u as ExpandCompletion, v as ArgsSchema, w as GlobalArgs, x as Command, y as CleanupContext, z as RunnableCommand } from "./arg-registry-BN3I-XON.js";
+import { I as CompletionOptions, L as CompletionResult, c as withCompletionCommand, d as GenerateBundledCompletionWorkerOptions, f as GenerateBundledCompletionWorkerResult, h as generateBundledCompletionWorker, o as generateCompletion, t as WithCompletionOptions } from "./index-CtRrTVTL.js";
 import { z } from "zod";
 
 //#region src/core/case-types.d.ts

package/dist/index.js

@@ -1,4 +1,4 @@
-import { C as renderMarkdown, S as renderInline, _ as DuplicateFieldError, a as parseArgv, b as ReservedAliasError, c as validateCommand, d as validateDuplicateFields, f as validateDuplicateNegations, g as DuplicateAliasError, h as CaseVariantCollisionError, i as formatValidationErrors, l as validateCrossSchemaCollisions, m as validateReservedAliases, n as runMain, o as formatCommandValidationErrors, p as validatePositionalConfig, s as validateCaseVariantCollisions, t as runCommand, u as validateDuplicateAliases, v as DuplicateNegationError, w as createDualCaseProxy, x as generateHelp, y as PositionalConfigError } from "./runner-BmWR9TLM.js";
+import { C as renderMarkdown, S as renderInline, _ as DuplicateFieldError, a as parseArgv, b as ReservedAliasError, c as validateCommand, d as validateDuplicateFields, f as validateDuplicateNegations, g as DuplicateAliasError, h as CaseVariantCollisionError, i as formatValidationErrors, l as validateCrossSchemaCollisions, m as validateReservedAliases, n as runMain, o as formatCommandValidationErrors, p as validatePositionalConfig, s as validateCaseVariantCollisions, t as runCommand, u as validateDuplicateAliases, v as DuplicateNegationError, w as createDualCaseProxy, x as generateHelp, y as PositionalConfigError } from "./runner-BCMB67GV.js";
 import { t as arg } from "./arg-registry-BeLLAW5-.js";
 import { n as defineCommand, t as createDefineCommand } from "./command-B4yA4LXX.js";
 import { a as toCamelCase, f as isLazyCommand, i as getUnknownKeysMode, o as toKebabCase, p as lazy, t as extractFields } from "./schema-extractor-CVHWm23M.js";

package/dist/prompt/clack/index.d.ts

@@ -1,4 +1,4 @@
-import { P as PromptResolver } from "../../arg-registry-DDJpsUea.js";
+import { P as PromptResolver } from "../../arg-registry-BN3I-XON.js";
 
 //#region src/prompt/clack/index.d.ts
 /**

package/dist/prompt/index.d.ts

@@ -1,4 +1,4 @@
-import { J as ResolvedFieldMeta, q as ExtractedFields } from "../arg-registry-DDJpsUea.js";
+import { J as ResolvedFieldMeta, q as ExtractedFields } from "../arg-registry-BN3I-XON.js";
 
 //#region src/prompt/types.d.ts
 /**

package/dist/prompt/inquirer/index.d.ts

@@ -1,4 +1,4 @@
-import { P as PromptResolver } from "../../arg-registry-DDJpsUea.js";
+import { P as PromptResolver } from "../../arg-registry-BN3I-XON.js";
 
 //#region src/prompt/inquirer/index.d.ts
 /**

package/dist/{runner-BmWR9TLM.js → runner-BCMB67GV.js}

@@ -1421,6 +1421,78 @@ function formatCommandValidationErrors(errors) {
 	return lines.join("\n");
 }
 
+//#endregion
+//#region src/parser/long-option-resolver.ts
+function resolveLongOption(arg, lookup) {
+	const withoutDashes = arg.includes("=") ? arg.slice(2, arg.indexOf("=")) : arg.slice(2);
+	if (!arg.includes("=")) {
+		const negatedField = lookup.negationMap.get(withoutDashes);
+		if (negatedField && lookup.booleanFlags.has(negatedField)) return {
+			resolvedName: negatedField,
+			withoutDashes,
+			isNegated: true,
+			isCustomNegation: true,
+			isSuppressedNegation: false
+		};
+	}
+	const hasEquals = arg.includes("=");
+	if (!hasEquals && withoutDashes.startsWith("no-")) {
+		const flagName = withoutDashes.slice(3);
+		if (flagName === flagName.toLowerCase()) {
+			const resolvedName = lookup.aliasMap.get(flagName) ?? flagName;
+			if (lookup.booleanFlags.has(resolvedName)) {
+				const asIsResolved = lookup.aliasMap.get(withoutDashes) ?? withoutDashes;
+				if (!lookup.definedNames.has(asIsResolved)) {
+					if (lookup.customNegatedFields.has(resolvedName)) return {
+						resolvedName,
+						withoutDashes,
+						isNegated: false,
+						isCustomNegation: false,
+						isSuppressedNegation: true
+					};
+					return {
+						resolvedName,
+						withoutDashes,
+						isNegated: true,
+						isCustomNegation: false,
+						isSuppressedNegation: false
+					};
+				}
+			}
+		}
+	}
+	if (!hasEquals && withoutDashes.length > 2 && withoutDashes.startsWith("no") && /[A-Z]/.test(withoutDashes[2])) {
+		const camelFlagName = withoutDashes[2].toLowerCase() + withoutDashes.slice(3);
+		const resolvedName = lookup.aliasMap.get(camelFlagName) ?? camelFlagName;
+		if (lookup.booleanFlags.has(resolvedName)) {
+			const asIsResolved = lookup.aliasMap.get(withoutDashes) ?? withoutDashes;
+			if (!lookup.definedNames.has(asIsResolved)) {
+				if (lookup.customNegatedFields.has(resolvedName)) return {
+					resolvedName,
+					withoutDashes,
+					isNegated: false,
+					isCustomNegation: false,
+					isSuppressedNegation: true
+				};
+				return {
+					resolvedName,
+					withoutDashes,
+					isNegated: true,
+					isCustomNegation: false,
+					isSuppressedNegation: false
+				};
+			}
+		}
+	}
+	return {
+		resolvedName: lookup.aliasMap.get(withoutDashes) ?? withoutDashes,
+		withoutDashes,
+		isNegated: false,
+		isCustomNegation: false,
+		isSuppressedNegation: false
+	};
+}
+
 //#endregion
 //#region src/parser/argv-parser.ts
 /**
@@ -1446,6 +1518,13 @@ function formatCommandValidationErrors(errors) {
 */
 function parseArgv(argv, options = {}) {
 	const { aliasMap = /* @__PURE__ */ new Map(), booleanFlags = /* @__PURE__ */ new Set(), arrayFlags = /* @__PURE__ */ new Set(), definedNames = /* @__PURE__ */ new Set(), negationMap = /* @__PURE__ */ new Map(), customNegatedFields = /* @__PURE__ */ new Set() } = options;
+	const longOptionLookup = {
+		aliasMap,
+		booleanFlags,
+		definedNames,
+		negationMap,
+		customNegatedFields
+	};
 	const result = {
 		options: {},
 		positionals: [],
@@ -1476,39 +1555,11 @@ function parseArgv(argv, options = {}) {
 		}
 		if (arg.startsWith("--")) {
 			const withoutDashes = arg.slice(2);
-			if (!withoutDashes.includes("=")) {
-				const negatedField = negationMap.get(withoutDashes);
-				if (negatedField && booleanFlags.has(negatedField)) {
-					setOption(negatedField, false);
-					i++;
-					continue;
-				}
-			}
-			if (withoutDashes.startsWith("no-")) {
-				const flagName = withoutDashes.slice(3);
-				if (flagName === flagName.toLowerCase()) {
-					const resolvedName = aliasMap.get(flagName) ?? flagName;
-					if (booleanFlags.has(resolvedName) && !customNegatedFields.has(resolvedName)) {
-						const asIsResolved = aliasMap.get(withoutDashes) ?? withoutDashes;
-						if (!definedNames.has(asIsResolved)) {
-							setOption(flagName, false);
-							i++;
-							continue;
-						}
-					}
-				}
-			}
-			if (withoutDashes.length > 2 && withoutDashes.startsWith("no") && /[A-Z]/.test(withoutDashes[2])) {
-				const camelFlagName = withoutDashes[2].toLowerCase() + withoutDashes.slice(3);
-				const resolvedName = aliasMap.get(camelFlagName) ?? camelFlagName;
-				if (booleanFlags.has(resolvedName) && !customNegatedFields.has(resolvedName)) {
-					const asIsResolved = aliasMap.get(withoutDashes) ?? withoutDashes;
-					if (!definedNames.has(asIsResolved)) {
-						setOption(camelFlagName, false);
-						i++;
-						continue;
-					}
-				}
+			const resolution = resolveLongOption(arg, longOptionLookup);
+			if (resolution.isNegated) {
+				setOption(resolution.resolvedName, false);
+				i++;
+				continue;
 			}
 			const eqIndex = withoutDashes.indexOf("=");
 			if (eqIndex !== -1) {
@@ -1638,12 +1689,13 @@ function mergeWithPositionals(parsed, extracted) {
 * Shared by scanForSubcommand, separateGlobalArgs, and findFirstPositional.
 */
 function buildGlobalFlagLookup(globalExtracted) {
-	const { aliasMap = /* @__PURE__ */ new Map(), booleanFlags = /* @__PURE__ */ new Set(), negationMap = /* @__PURE__ */ new Map(), customNegatedFields = /* @__PURE__ */ new Set() } = buildParserOptions(globalExtracted);
+	const { aliasMap = /* @__PURE__ */ new Map(), booleanFlags = /* @__PURE__ */ new Set(), definedNames = /* @__PURE__ */ new Set(), negationMap = /* @__PURE__ */ new Map(), customNegatedFields = /* @__PURE__ */ new Set() } = buildParserOptions(globalExtracted);
 	const shortAliases = /* @__PURE__ */ new Set();
 	for (const field of globalExtracted.fields) for (const alias of getAllAliases(field)) if (alias.length === 1) shortAliases.add(alias);
 	return {
 		aliasMap,
 		booleanFlags,
+		definedNames,
 		flagNames: new Set(globalExtracted.fields.map((f) => f.name)),
 		cliNames: new Set(globalExtracted.fields.map((f) => f.cliName)),
 		aliases: shortAliases,
@@ -1662,37 +1714,21 @@ function buildGlobalFlagLookup(globalExtracted) {
 * trailing subcommand is still detected) even though they no longer negate.
 */
 function resolveGlobalLongOption(arg, lookup) {
-	const withoutDashes = arg.includes("=") ? arg.slice(2, arg.indexOf("=")) : arg.slice(2);
-	const customNegated = !arg.includes("=") ? lookup.negationMap.get(withoutDashes) : void 0;
-	if (customNegated) return {
-		resolvedName: customNegated,
+	const { resolvedName, withoutDashes, isNegated, isCustomNegation, isSuppressedNegation } = resolveLongOption(arg, lookup);
+	if (isSuppressedNegation) return {
+		resolvedName,
 		withoutDashes,
-		isNegated: true,
-		isGlobal: lookup.flagNames.has(customNegated),
-		isSuppressedNegation: false
+		isNegated: false,
+		isGlobal: false,
+		isSuppressedNegation
 	};
-	const kebabNegated = withoutDashes.startsWith("no-");
-	const camelNegated = !kebabNegated && withoutDashes.length > 2 && withoutDashes.startsWith("no") && /[A-Z]/.test(withoutDashes[2]);
-	if (kebabNegated || camelNegated) {
-		const literalResolved = lookup.aliasMap.get(withoutDashes) ?? withoutDashes;
-		if (lookup.flagNames.has(literalResolved) || lookup.cliNames.has(withoutDashes)) return {
-			resolvedName: literalResolved,
-			withoutDashes,
-			isNegated: false,
-			isGlobal: true,
-			isSuppressedNegation: false
-		};
-	}
-	const defaultIsNegated = kebabNegated || camelNegated;
-	const flagName = kebabNegated ? withoutDashes.slice(3) : camelNegated ? withoutDashes[2].toLowerCase() + withoutDashes.slice(3) : withoutDashes;
-	const resolvedName = lookup.aliasMap.get(flagName) ?? flagName;
-	const suppressDefaultNegation = defaultIsNegated && lookup.customNegatedFields.has(resolvedName);
+	const flagName = isNegated && !isCustomNegation ? withoutDashes.startsWith("no-") ? withoutDashes.slice(3) : withoutDashes[2].toLowerCase() + withoutDashes.slice(3) : withoutDashes;
 	return {
 		resolvedName,
 		withoutDashes,
-		isNegated: defaultIsNegated && !suppressDefaultNegation,
-		isGlobal: !suppressDefaultNegation && (lookup.flagNames.has(resolvedName) || lookup.cliNames.has(withoutDashes) || lookup.cliNames.has(flagName)),
-		isSuppressedNegation: suppressDefaultNegation
+		isNegated,
+		isGlobal: lookup.flagNames.has(resolvedName) || lookup.cliNames.has(withoutDashes) || lookup.cliNames.has(flagName),
+		isSuppressedNegation: false
 	};
 }
 /**
@@ -1808,6 +1844,7 @@ function findFirstPositionalIndex(argv, globalExtracted) {
 	const lookup = globalExtracted ? buildGlobalFlagLookup(globalExtracted) : {
 		aliasMap: /* @__PURE__ */ new Map(),
 		booleanFlags: /* @__PURE__ */ new Set(),
+		definedNames: /* @__PURE__ */ new Set(),
 		flagNames: /* @__PURE__ */ new Set(),
 		cliNames: /* @__PURE__ */ new Set(),
 		aliases: /* @__PURE__ */ new Set(),
@@ -1875,6 +1912,7 @@ function parseArgs(argv, command, options = {}) {
 				remainingArgs: scanResult.tokensAfterSubcommand,
 				rawArgs: {},
 				positionals: [],
+				rest: [],
 				unknownFlags: scanResult.suppressedTokens,
 				rawGlobalArgs
 			};
@@ -1889,6 +1927,7 @@ function parseArgs(argv, command, options = {}) {
 			remainingArgs: argv.slice(1),
 			rawArgs: {},
 			positionals: [],
+			rest: [],
 			unknownFlags: []
 		};
 	}
@@ -1920,6 +1959,7 @@ function parseArgs(argv, command, options = {}) {
 		remainingArgs: [],
 		rawArgs: {},
 		positionals: [],
+		rest: [],
 		unknownFlags: []
 	};
 	let commandArgv = argv;
@@ -1929,17 +1969,21 @@ function parseArgs(argv, command, options = {}) {
 		commandArgv = separated;
 		rawGlobalArgs = globalParsed;
 	}
-	if (!extracted) return {
-		helpRequested: false,
-		helpAllRequested: false,
-		versionRequested: false,
-		subCommand: void 0,
-		remainingArgs: [],
-		rawArgs: {},
-		positionals: [],
-		unknownFlags: [],
-		rawGlobalArgs
-	};
+	if (!extracted) {
+		const ddIdx = commandArgv.indexOf("--");
+		return {
+			helpRequested: false,
+			helpAllRequested: false,
+			versionRequested: false,
+			subCommand: void 0,
+			remainingArgs: [],
+			rawArgs: {},
+			positionals: ddIdx >= 0 ? commandArgv.slice(0, ddIdx) : commandArgv,
+			rest: ddIdx >= 0 ? commandArgv.slice(ddIdx + 1) : [],
+			unknownFlags: [],
+			rawGlobalArgs
+		};
+	}
 	const parserOptions = buildParserOptions(extracted);
 	const parsed = parseArgv(commandArgv, parserOptions);
 	const rawArgs = mergeWithPositionals(parsed, extracted);
@@ -1972,6 +2016,7 @@ function parseArgs(argv, command, options = {}) {
 		remainingArgs: [],
 		rawArgs,
 		positionals: parsed.positionals,
+		rest: parsed.rest,
 		unknownFlags,
 		extractedFields: extracted,
 		rawGlobalArgs
@@ -2161,7 +2206,8 @@ var runner_exports = /* @__PURE__ */ __exportAll({
 */
 const defaultLogger = {
 	log: (message) => console.log(message),
-	error: (message) => console.error(message)
+	error: (message) => console.error(message),
+	warn: (message) => console.warn(message)
 };
 /**
 * Run a command with the given arguments (programmatic/test usage)
@@ -2308,7 +2354,7 @@ async function runMain(command, options = {}) {
 		effectiveOptions = rest;
 	}
 	const globalExtracted = extractAndValidateGlobal(effectiveOptions);
-	if (effectiveOptions.onUnknownSubcommand && !isInternalSubcommandInvocation(command, argv, globalExtractedForBypass)) {
+	if (effectiveOptions.onUnknownSubcommand && !command.run && !isInternalSubcommandInvocation(command, argv, globalExtractedForBypass)) {
 		const knownSubCommands = listSubCommandNamesWithAliases(command);
 		if (knownSubCommands.size > 0) {
 			const positionalIndex = findFirstPositionalIndex(argv, globalExtracted);
@@ -2401,7 +2447,7 @@ async function runCommandInternal(command, argv, options = {}) {
 			...parseResult.rawGlobalArgs
 		};
 		const nestedCommandPath = context.commandPath ?? [];
-		if (options.onUnknownSubcommand && nestedCommandPath.length > 0) {
+		if (options.onUnknownSubcommand && !command.run && nestedCommandPath.length > 0) {
 			const knownSubCommands = listSubCommandNamesWithAliases(command);
 			if (knownSubCommands.size > 0) {
 				const positionalIndex = findFirstPositionalIndex(argv, options._globalExtracted);
@@ -2516,7 +2562,12 @@ async function runCommandInternal(command, argv, options = {}) {
 				});
 			}
 		}
-		if (listSubCommands(command).length > 0 && !parseResult.subCommand && !command.run) {
+		const positionalFields = parseResult.extractedFields?.fields.filter((f) => f.positional) ?? [];
+		const hasArrayPositional = positionalFields.some((f) => f.type === "array");
+		const allPositionals = [...parseResult.positionals, ...parseResult.rest];
+		const extraPositionals = hasArrayPositional ? [] : allPositionals.slice(positionalFields.length);
+		const unconsumedRegulars = hasArrayPositional ? [] : parseResult.positionals.slice(positionalFields.length);
+		if (listSubCommands(command).length > 0 && !parseResult.subCommand && !command.run && extraPositionals.length === 0) {
 			const help = generateHelp(command, {
 				showSubcommands: options.showSubcommands ?? true,
 				context
@@ -2543,6 +2594,33 @@ async function runCommandInternal(command, argv, options = {}) {
 				};
 			} else if (unknownKeysMode === "strip") for (const flag of parseResult.unknownFlags) logger.error(formatUnknownFlagWarning(flag, knownFlags));
 		}
+		if (extraPositionals.length > 0) {
+			const subCmdNames = listSubCommandNamesWithAliases(command);
+			if (subCmdNames.size > 0) {
+				const unknownCmd = unconsumedRegulars.find((t) => !t.startsWith("-") && !subCmdNames.has(t));
+				if (unknownCmd) {
+					const similar = findSimilar(unknownCmd, [...subCmdNames]);
+					const suggestion = similar.length > 0 ? ` Did you mean: ${similar.join(", ")}?` : "";
+					collector?.stop();
+					return {
+						success: false,
+						error: /* @__PURE__ */ new Error(`Unknown subcommand: ${unknownCmd}${suggestion ? `.${suggestion}` : ""}`),
+						exitCode: 1,
+						logs: getCurrentLogs()
+					};
+				}
+			}
+			const unknownKeysMode = parseResult.extractedFields?.unknownKeysMode ?? "strip";
+			if (unknownKeysMode === "strict") {
+				collector?.stop();
+				return {
+					success: false,
+					error: /* @__PURE__ */ new Error(`Unexpected positional argument${extraPositionals.length > 1 ? "s" : ""}: ${extraPositionals.join(", ")}`),
+					exitCode: 1,
+					logs: getCurrentLogs()
+				};
+			} else if (unknownKeysMode === "strip") for (const positional of extraPositionals) (logger.warn ?? logger.error)(`Warning: Unexpected positional argument: ${positional}`);
+		}
 		let validatedGlobalArgs = {};
 		const isCompletionInvocation = command.name === "__complete";
 		if (options.globalArgs && options._globalExtracted && !isCompletionInvocation) {
@@ -2649,4 +2727,4 @@ function extractAndValidateGlobal(options) {
 
 //#endregion
 export { renderMarkdown as C, renderInline as S, DuplicateFieldError as _, parseArgv as a, ReservedAliasError as b, validateCommand as c, validateDuplicateFields as d, validateDuplicateNegations as f, DuplicateAliasError as g, CaseVariantCollisionError as h, formatValidationErrors as i, validateCrossSchemaCollisions as l, validateReservedAliases as m, runMain as n, formatCommandValidationErrors as o, validatePositionalConfig as p, runner_exports as r, validateCaseVariantCollisions as s, runCommand as t, validateDuplicateAliases as u, DuplicateNegationError as v, createDualCaseProxy as w, generateHelp as x, PositionalConfigError as y };
-//# sourceMappingURL=runner-BmWR9TLM.js.map
+//# sourceMappingURL=runner-BCMB67GV.js.map

package/dist/skill/index.d.ts

@@ -1,4 +1,4 @@
-import { _ as AnyCommand } from "../arg-registry-DDJpsUea.js";
+import { _ as AnyCommand } from "../arg-registry-BN3I-XON.js";
 import { z } from "zod";
 
 //#region src/skill/frontmatter.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "politty",
-  "version": "0.9.2",
+  "version": "0.10.1",
   "description": "A lightweight CLI framework inspired by citty with zod v4 registry integration for type-safe metadata management",
   "keywords": [
     "argument-parser",
@@ -69,18 +69,18 @@
     "@inquirer/prompts": "8.5.2",
     "@quansync/fs": "1.0.0",
     "@types/node": "25.9.3",
-    "@typescript/native-preview": "7.0.0-dev.20260611.2",
-    "@vitest/coverage-v8": "4.1.8",
-    "knip": "6.16.1",
+    "@typescript/native-preview": "7.0.0-dev.20260617.2",
+    "@vitest/coverage-v8": "4.1.9",
+    "knip": "6.17.1",
     "lefthook": "2.1.9",
     "organize-imports-cli": "1.0.2",
-    "oxfmt": "0.54.0",
-    "oxlint": "1.69.0",
+    "oxfmt": "0.55.0",
+    "oxlint": "1.70.0",
     "quansync": "1.0.0",
-    "tsdown": "0.22.2",
+    "tsdown": "0.22.3",
     "tsx": "4.22.4",
     "typescript": "6.0.3",
-    "vitest": "4.1.8",
+    "vitest": "4.1.9",
     "zod": "4.4.3"
   },
   "peerDependencies": {