@optique/core 1.4.0-dev.2895 → 1.4.0-dev.2899

package/dist/facade.cjs

@@ -818,7 +818,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, showAliases, showEnvironment, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", errorUsage = "root", onError = () => {
+	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, showAliases, showEnvironment, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	let maxWidth = requestedMaxWidth;
@@ -1117,15 +1117,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						})));
 					}
 					if (effectiveAboveError === "usage") {
-						const rootUsage = augmentedParser.usage;
-						const optionCount = Number(helpParsers.helpOption != null) + Number(versionParsers.versionOption != null);
-						const alternativeCount = optionCount + Number(helpParsers.helpCommand != null) + Number(versionParsers.versionCommand != null) + Number(completionParsers.completionCommand != null);
-						const errorUsageTerms = aboveError === "usage" && errorUsage === "command" ? require_usage_internals.projectCommandUsage(rootUsage, classified.commandPath, alternativeCount === 0 ? void 0 : {
-							optionCount,
-							alternativeCount
-						}) ?? rootUsage : rootUsage;
-						resolveUsageWidth(errorUsageTerms);
-						stderr(`${usageLabel()}${indentLines(require_usage.formatUsage(programName, errorUsageTerms, {
+						resolveUsageWidth(augmentedParser.usage);
+						stderr(`${usageLabel()}${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
 							theme,
 							colors,
 							maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),

package/dist/facade.d.cts

@@ -326,17 +326,6 @@ interface RunOptions<THelp, TError> {
    * @default `"usage"`
    */
   readonly aboveError?: "usage" | "help" | "none";
-  /**
-   * Scope of the compact preamble when `aboveError` is `"usage"`.
-   * `"command"` uses the failed parse's canonical command path and usage
-   * metadata, retaining parent options. Hidden or unresolved paths and
-   * unsupported compositions fall back to root usage. Neither mode applies
-   * help-only `usageLine` overrides or evaluates the parser again.
-   *
-   * @default `"root"`
-   * @since 1.4.0
-   */
-  readonly errorUsage?: "root" | "command";
   /**
    * Callback invoked after error output for a parse failure, an invalid
    * command path before help, or a missing or unsupported completion shell.

package/dist/facade.d.ts

@@ -326,17 +326,6 @@ interface RunOptions<THelp, TError> {
    * @default `"usage"`
    */
   readonly aboveError?: "usage" | "help" | "none";
-  /**
-   * Scope of the compact preamble when `aboveError` is `"usage"`.
-   * `"command"` uses the failed parse's canonical command path and usage
-   * metadata, retaining parent options. Hidden or unresolved paths and
-   * unsupported compositions fall back to root usage. Neither mode applies
-   * help-only `usageLine` overrides or evaluates the parser again.
-   *
-   * @default `"root"`
-   * @since 1.4.0
-   */
-  readonly errorUsage?: "root" | "command";
   /**
    * Callback invoked after error output for a parse failure, an invalid
    * command path before help, or a missing or unsupported completion shell.

package/dist/facade.js

@@ -12,7 +12,7 @@ import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDe
 import { createInputTrace } from "./input-trace.js";
 import { attemptParseAsync, attemptParseSync, createEffectfulCompletionSession, createParserContext, getDocPage } from "./internal/parser.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
-import { collectActiveOptionNames, collectRootOptionNames, projectCommandUsage } from "./usage-internals.js";
+import { collectActiveOptionNames, collectRootOptionNames } from "./usage-internals.js";
 import { allowDuplicateLeadingCommandNamesKey, hiddenCommandAliasesKey } from "./internal/command-alias.js";
 import { completeOrExtractPhase2Seed } from "./phase2-seed.js";
 import { multiple, optional, withDefault } from "./modifiers.js";
@@ -818,7 +818,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	validateProgramName(programName);
-	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, showAliases, showEnvironment, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", errorUsage = "root", onError = () => {
+	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, showAliases, showEnvironment, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	let maxWidth = requestedMaxWidth;
@@ -1117,15 +1117,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						})));
 					}
 					if (effectiveAboveError === "usage") {
-						const rootUsage = augmentedParser.usage;
-						const optionCount = Number(helpParsers.helpOption != null) + Number(versionParsers.versionOption != null);
-						const alternativeCount = optionCount + Number(helpParsers.helpCommand != null) + Number(versionParsers.versionCommand != null) + Number(completionParsers.completionCommand != null);
-						const errorUsageTerms = aboveError === "usage" && errorUsage === "command" ? projectCommandUsage(rootUsage, classified.commandPath, alternativeCount === 0 ? void 0 : {
-							optionCount,
-							alternativeCount
-						}) ?? rootUsage : rootUsage;
-						resolveUsageWidth(errorUsageTerms);
-						stderr(`${usageLabel()}${indentLines(formatUsage(programName, errorUsageTerms, {
+						resolveUsageWidth(augmentedParser.usage);
+						stderr(`${usageLabel()}${indentLines(formatUsage(programName, augmentedParser.usage, {
 							theme,
 							colors,
 							maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),

package/dist/usage-internals.cjs

@@ -2,103 +2,6 @@ const require_usage = require('./usage.cjs');
 
 //#region src/usage-internals.ts
 /**
-* Projects augmented runner usage onto a recorded canonical command path.
-* Unsupported or ambiguous metadata returns undefined, preserving root usage.
-* No parser, documentation, or usage-override callbacks are evaluated.
-* @param usage The runner's original augmented usage.
-* @param path The canonical path recorded by the failed parse.
-* @param meta The known augmentation boundary, absent without alternatives.
-* @returns The selected grammar, or undefined when projection is uncertain.
-* @internal
-*/
-function projectCommandUsage(usage, path, meta) {
-	if (path.length === 0) return void 0;
-	if (meta == null) return projectCommandTerms(usage, path, 0);
-	const top = usage[0];
-	if (usage.length !== 1 || top.type !== "exclusive" || top.terms.length !== meta.alternativeCount + 1) return void 0;
-	const selected = projectCommandTerms(top.terms[meta.optionCount], path, 0);
-	if (selected == null) return void 0;
-	const options = top.terms.slice(0, meta.optionCount).filter((branch) => branch.some((term) => term.type === "option" && !require_usage.isUsageHidden(term.hidden)));
-	return options.length === 0 ? selected : [{
-		type: "exclusive",
-		terms: [...options, selected]
-	}];
-}
-function containsCommand(usage) {
-	return usage.some((term) => {
-		switch (term.type) {
-			case "command": return true;
-			case "exclusive": return term.terms.some(containsCommand);
-			case "optional":
-			case "multiple":
-			case "sequence": return containsCommand(term.terms);
-			default: return false;
-		}
-	});
-}
-/** Undefined distinguishes unsupported metadata from a command-free branch. */
-function firstCommandNames(usage) {
-	const hosts = usage.filter((term) => containsCommand([term]));
-	const first = hosts[0];
-	if (first == null) return [];
-	if (first.type === "command") return [first.name];
-	if (hosts.length !== 1) return void 0;
-	if (first.type === "sequence") return firstCommandNames(first.terms);
-	if (first.type !== "exclusive") return void 0;
-	const names = [];
-	for (const branch of first.terms) {
-		const found = firstCommandNames(branch);
-		if (found == null) return void 0;
-		names.push(...found);
-	}
-	return names;
-}
-function projectCommandTerms(usage, path, offset) {
-	if (offset === path.length) return usage;
-	const index = usage.findIndex((term) => containsCommand([term]));
-	if (index < 0) return void 0;
-	const host = usage[index];
-	const prefix = usage.slice(0, index);
-	const suffix = usage.slice(index + 1);
-	if (host.type === "command") {
-		if (host.name !== path[offset] || require_usage.isUsageHidden(host.hidden)) return void 0;
-		const rest = projectCommandTerms(suffix, path, offset + 1);
-		return rest == null ? void 0 : [
-			...prefix,
-			host,
-			...rest
-		];
-	}
-	if (containsCommand(suffix)) return void 0;
-	if (host.type === "sequence") {
-		const terms$1 = projectCommandTerms(host.terms, path, offset);
-		return terms$1 == null ? void 0 : [
-			...prefix,
-			{
-				...host,
-				terms: terms$1
-			},
-			...suffix
-		];
-	}
-	if (host.type !== "exclusive") return void 0;
-	let selected;
-	for (const branch of host.terms) {
-		const names = firstCommandNames(branch);
-		if (names == null) return void 0;
-		if (!names.includes(path[offset])) continue;
-		if (selected != null) return void 0;
-		selected = branch;
-	}
-	if (selected == null) return void 0;
-	const terms = projectCommandTerms(selected, path, offset);
-	return terms == null ? void 0 : [
-		...prefix,
-		...terms,
-		...suffix
-	];
-}
-/**
 * Collects option names and command names that are valid as the *immediate*
 * next token at the current parse position ("leading candidates").
 *
@@ -249,5 +152,4 @@ exports.collectActiveOptionNames = collectActiveOptionNames;
 exports.collectLeadingCandidates = collectLeadingCandidates;
 exports.collectOptionNamesAtCurrentCommandDepth = collectOptionNamesAtCurrentCommandDepth;
 exports.collectRootOptionNames = collectRootOptionNames;
-exports.extractLeadingCommandNames = extractLeadingCommandNames;
-exports.projectCommandUsage = projectCommandUsage;
+exports.extractLeadingCommandNames = extractLeadingCommandNames;

package/dist/usage-internals.js

@@ -1,104 +1,7 @@
-import { isSuggestionHidden, isUsageHidden } from "./usage.js";
+import { isSuggestionHidden } from "./usage.js";
 
 //#region src/usage-internals.ts
 /**
-* Projects augmented runner usage onto a recorded canonical command path.
-* Unsupported or ambiguous metadata returns undefined, preserving root usage.
-* No parser, documentation, or usage-override callbacks are evaluated.
-* @param usage The runner's original augmented usage.
-* @param path The canonical path recorded by the failed parse.
-* @param meta The known augmentation boundary, absent without alternatives.
-* @returns The selected grammar, or undefined when projection is uncertain.
-* @internal
-*/
-function projectCommandUsage(usage, path, meta) {
-	if (path.length === 0) return void 0;
-	if (meta == null) return projectCommandTerms(usage, path, 0);
-	const top = usage[0];
-	if (usage.length !== 1 || top.type !== "exclusive" || top.terms.length !== meta.alternativeCount + 1) return void 0;
-	const selected = projectCommandTerms(top.terms[meta.optionCount], path, 0);
-	if (selected == null) return void 0;
-	const options = top.terms.slice(0, meta.optionCount).filter((branch) => branch.some((term) => term.type === "option" && !isUsageHidden(term.hidden)));
-	return options.length === 0 ? selected : [{
-		type: "exclusive",
-		terms: [...options, selected]
-	}];
-}
-function containsCommand(usage) {
-	return usage.some((term) => {
-		switch (term.type) {
-			case "command": return true;
-			case "exclusive": return term.terms.some(containsCommand);
-			case "optional":
-			case "multiple":
-			case "sequence": return containsCommand(term.terms);
-			default: return false;
-		}
-	});
-}
-/** Undefined distinguishes unsupported metadata from a command-free branch. */
-function firstCommandNames(usage) {
-	const hosts = usage.filter((term) => containsCommand([term]));
-	const first = hosts[0];
-	if (first == null) return [];
-	if (first.type === "command") return [first.name];
-	if (hosts.length !== 1) return void 0;
-	if (first.type === "sequence") return firstCommandNames(first.terms);
-	if (first.type !== "exclusive") return void 0;
-	const names = [];
-	for (const branch of first.terms) {
-		const found = firstCommandNames(branch);
-		if (found == null) return void 0;
-		names.push(...found);
-	}
-	return names;
-}
-function projectCommandTerms(usage, path, offset) {
-	if (offset === path.length) return usage;
-	const index = usage.findIndex((term) => containsCommand([term]));
-	if (index < 0) return void 0;
-	const host = usage[index];
-	const prefix = usage.slice(0, index);
-	const suffix = usage.slice(index + 1);
-	if (host.type === "command") {
-		if (host.name !== path[offset] || isUsageHidden(host.hidden)) return void 0;
-		const rest = projectCommandTerms(suffix, path, offset + 1);
-		return rest == null ? void 0 : [
-			...prefix,
-			host,
-			...rest
-		];
-	}
-	if (containsCommand(suffix)) return void 0;
-	if (host.type === "sequence") {
-		const terms$1 = projectCommandTerms(host.terms, path, offset);
-		return terms$1 == null ? void 0 : [
-			...prefix,
-			{
-				...host,
-				terms: terms$1
-			},
-			...suffix
-		];
-	}
-	if (host.type !== "exclusive") return void 0;
-	let selected;
-	for (const branch of host.terms) {
-		const names = firstCommandNames(branch);
-		if (names == null) return void 0;
-		if (!names.includes(path[offset])) continue;
-		if (selected != null) return void 0;
-		selected = branch;
-	}
-	if (selected == null) return void 0;
-	const terms = projectCommandTerms(selected, path, offset);
-	return terms == null ? void 0 : [
-		...prefix,
-		...terms,
-		...suffix
-	];
-}
-/**
 * Collects option names and command names that are valid as the *immediate*
 * next token at the current parse position ("leading candidates").
 *
@@ -245,4 +148,4 @@ function collectRootOptionNamesFromTerm(term, names, rootLeadingNames) {
 }
 
 //#endregion
-export { collectActiveOptionNames, collectLeadingCandidates, collectOptionNamesAtCurrentCommandDepth, collectRootOptionNames, extractLeadingCommandNames, projectCommandUsage };
+export { collectActiveOptionNames, collectLeadingCandidates, collectOptionNamesAtCurrentCommandDepth, collectRootOptionNames, extractLeadingCommandNames };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2895",
+  "version": "1.4.0-dev.2899",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -261,7 +261,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2895+fb7758c4",
+    "@optique/env": "1.4.0-dev.2899+9c2973b0",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -80,9 +80,9 @@ Core rules
     Show hidden `aliases` in help with `showAliases` on `command()` or runner.
  -  Use `run(parser, { completion: "both" })` for completion, or the object form
     with `completion.errors` for custom shell errors. Do not hand-write scripts.
- -  Use `usageLine: [{ type: "ellipsis" }]` for compact root full help and the
-    override on `command()` for subcommand help. `errorUsage: "command"` scopes
-    usage above errors with root fallback, ignoring help-only overrides.
+ -  Use `usageLine: [{ type: "ellipsis" }]` in runner options when a large root
+    synopsis should become a compact `Usage: myapp ...` line. This applies only
+    to root full help; use `command()`'s `usageLine` for subcommand help.
  -  Use `showUsage: false` in runner options when full help should show the
     brief and sections without `Usage:`. Set `command()`'s `showUsage: true`
     to restore it; children inherit the nearest explicit ancestor setting.
@@ -263,7 +263,6 @@ For the detailed maintained guide, use <https://optique.dev/pitfalls.md>.
 Reference links
 ---------------
 
- -  Documentation index for agents: <https://optique.dev/llms.txt>
  -  Runners and entry points: <https://optique.dev/concepts/runners.md>
  -  Primitive parsers: <https://optique.dev/concepts/primitives.md>
  -  Construct combinators: <https://optique.dev/concepts/constructs.md>
@@ -273,6 +272,7 @@ Reference links
  -  Structured messages: <https://optique.dev/concepts/messages.md>
  -  Shell completion: <https://optique.dev/concepts/completion.md>
  -  Command discovery: <https://optique.dev/concepts/discover.md>
+ -  CLI: <https://github.com/dahlia/optique/tree/main/examples/file-inspect>
  -  Man pages: <https://optique.dev/concepts/man.md>