@optique/core 1.4.0-dev.2733 → 1.4.0-dev.2737

package/dist/primitives.d.ts

@@ -451,6 +451,14 @@ interface CommandOptions {
    * @since 1.0.0
    */
   readonly usageLine?: Usage | ((defaultUsageLine: Usage) => Usage);
+  /**
+   * Whether to show the usage synopsis in this command's full help.
+   * Descendants inherit this setting unless they explicitly override it.
+   * Omission inherits the nearest ancestor setting, then the runner setting,
+   * with a final default of `true`. Usage-only error preambles are unaffected.
+   * @since 1.4.0
+   */
+  readonly showUsage?: boolean;
   /**
    * Controls command visibility:
    *
@@ -537,7 +545,8 @@ type CommandState<TState> = undefined | ["matched", string] | ["parsing", TState
  *          to the inner parser for the remaining arguments.
  * @throws {TypeError} If `name` is empty, whitespace-only, contains
  *         embedded whitespace, or contains control characters.
- * @throws {TypeError} If `options.showAliases` is present but not a boolean.
+ * @throws {TypeError} If `options.showAliases` or `options.showUsage` is
+ *         non-nullish and not a boolean.
  */
 declare function command<M extends Mode, T, TState>(name: string, parser: Parser<M, T, TState>, options?: CommandOptions): FluentParser<M, T, CommandState<TState>>;
 /**

package/dist/primitives.js

@@ -1,4 +1,5 @@
 import { annotateFreshArray, getAnnotations } from "./internal/annotations.js";
+import { defineBareCommandDocPolicy, enterCommandDocPolicy, matchCommandDocPolicy } from "./internal/command-doc-policy.js";
 import { validateCommandNames, validateOptionNames } from "./validate.js";
 import { extractOptionNames, isDocHidden, isSuggestionHidden } from "./usage.js";
 import { message, metavar, optionName, optionNames, text, valueSet } from "./message.js";
@@ -1447,6 +1448,12 @@ function getShowCommandAliases(options) {
 	if (typeof showAliases !== "boolean") throw new TypeError("Command showAliases must be a boolean.");
 	return showAliases;
 }
+function getShowCommandUsage(options) {
+	const showUsage = options.showUsage;
+	if (showUsage == null) return void 0;
+	if (typeof showUsage !== "boolean") throw new TypeError("Command showUsage must be a boolean.");
+	return showUsage;
+}
 function getHiddenCommandAliases(options) {
 	const hiddenAliases = options[hiddenCommandAliasesKey];
 	if (hiddenAliases == null) return [];
@@ -1511,12 +1518,15 @@ async function* suggestCommandAsync(context, prefix, name, aliases, parser, opti
 *          to the inner parser for the remaining arguments.
 * @throws {TypeError} If `name` is empty, whitespace-only, contains
 *         embedded whitespace, or contains control characters.
-* @throws {TypeError} If `options.showAliases` is present but not a boolean.
+* @throws {TypeError} If `options.showAliases` or `options.showUsage` is
+*         non-nullish and not a boolean.
 */
 function command(name, parser, options = {}) {
 	const commandNames = getCommandNames(name, options);
 	const aliases = getVisibleCommandAliases(options);
 	const showAliases = getShowCommandAliases(options);
+	const showUsage = getShowCommandUsage(options);
+	const commandId = Symbol("commandDocScope");
 	const hiddenAliases = getHiddenCommandAliases(options);
 	validateCommandNames(commandNames, "Command");
 	validateUniqueCommandNames(commandNames);
@@ -1602,7 +1612,7 @@ function command(name, parser, options = {}) {
 						...context,
 						buffer: context.buffer.slice(1),
 						state: createCommandState(context.state, ["matched", name]),
-						...context.exec != null ? { exec: appendCommandPath(context.exec, name) } : {}
+						...context.exec != null ? { exec: matchCommandDocPolicy(appendCommandPath(context.exec, name), commandId, showUsage) } : {}
 					},
 					consumed: context.buffer.slice(0, 1)
 				};
@@ -1626,7 +1636,13 @@ function command(name, parser, options = {}) {
 					}
 					return parseResult;
 				};
-				return dispatchByMode(parser.mode, () => wrapState(syncInnerParser.parse(withChildContext(context, name, innerState, parser.usage))), async () => wrapState(await parser.parse(withChildContext(context, name, innerState, parser.usage))));
+				return dispatchByMode(parser.mode, () => wrapState(syncInnerParser.parse(withChildContext({
+					...context,
+					exec: enterCommandDocPolicy(context.exec, commandId)
+				}, name, innerState, parser.usage))), async () => wrapState(await parser.parse(withChildContext({
+					...context,
+					exec: enterCommandDocPolicy(context.exec, commandId)
+				}, name, innerState, parser.usage))));
 			}
 			return {
 				success: false,
@@ -1744,6 +1760,7 @@ function command(name, parser, options = {}) {
 			return `command(${JSON.stringify(name)})`;
 		}
 	};
+	defineBareCommandDocPolicy(result, showUsage);
 	if (typeof parser.normalizeValue === "function") Object.defineProperty(result, "normalizeValue", {
 		value: parser.normalizeValue.bind(parser),
 		configurable: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2733",
+  "version": "1.4.0-dev.2737",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -235,6 +235,14 @@
       },
       "import": "./dist/internal/usage.js",
       "require": "./dist/internal/usage.cjs"
+    },
+    "./internal/command-doc-policy": {
+      "types": {
+        "import": "./dist/internal/command-doc-policy.d.ts",
+        "require": "./dist/internal/command-doc-policy.d.cts"
+      },
+      "import": "./dist/internal/command-doc-policy.js",
+      "require": "./dist/internal/command-doc-policy.cjs"
     }
   },
   "imports": {
@@ -245,7 +253,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2733+865d769f",
+    "@optique/env": "1.4.0-dev.2737+72ffb3c4",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -84,9 +84,9 @@ Core rules
     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 command or option sections without the `Usage:` synopsis.
-    For deeply nested command trees, add `commandList: "top-level"` when root
-    help should list only first-level command groups.
+    brief and sections without `Usage:`. Set `command()`'s `showUsage: true`
+    to restore it; children inherit the nearest explicit ancestor setting.
+    Add `commandList: "top-level"` to list only first-level command groups.
  -  Use `termWidth: "auto"` in runner options when descriptions should align
     after the widest visible help term. Optique measures terminal display
     width after adding built-in help/version/completion entries.