@optique/core 1.4.0-dev.2748 → 1.4.0-dev.2749

package/dist/facade.cjs

@@ -17,6 +17,7 @@ const require_command_alias = require('./internal/command-alias.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_constructs = require('./constructs.cjs');
+const require_internal_help_request = require('./internal/help-request.cjs');
 const require_valueparser = require('./valueparser.cjs');
 const require_primitives = require('./primitives.cjs');
 
@@ -1145,6 +1146,20 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		}
 	};
 	const parserMode = parser.mode;
+	const helpRequest = require_internal_help_request.getHelpRequest(options);
+	if (helpRequest != null) return require_mode_dispatch.dispatchByMode(parserMode, () => {
+		const handled = handleResult({
+			type: "help",
+			commands: helpRequest,
+			preferUserCommandDocs: true
+		});
+		if (handled instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
+		return handled;
+	}, async () => await handleResult({
+		type: "help",
+		commands: helpRequest,
+		preferUserCommandDocs: true
+	}));
 	return require_mode_dispatch.dispatchByMode(parserMode, () => {
 		const attempted = require_internal_parser.attemptParseSync(parser, args, {
 			mode: "complete",
@@ -1368,6 +1383,7 @@ function shouldProbeEarlyExit(options, needsTwoPhase) {
 * handled without collecting source-context annotations first.
 */
 function needsEarlyExitSync(parser, args, options) {
+	if (require_internal_help_request.getHelpRequest(options) != null) return true;
 	const attempted = require_internal_parser.attemptParseSync(parser, args, { mode: "parse-only" });
 	if (attempted.kind === "success") return false;
 	return isMetaEarlyExit(classifyEarlyExitFailure(attempted, options));
@@ -1376,6 +1392,7 @@ function needsEarlyExitSync(parser, args, options) {
 * Async variant of {@link needsEarlyExitSync}.
 */
 async function needsEarlyExitAsync(parser, args, options) {
+	if (require_internal_help_request.getHelpRequest(options) != null) return true;
 	const attempted = await require_internal_parser.attemptParseAsync(parser, args, { mode: "parse-only" });
 	if (attempted.kind === "success") return false;
 	return isMetaEarlyExit(classifyEarlyExitFailure(attempted, options));

package/dist/facade.js

@@ -17,6 +17,7 @@ import { allowDuplicateLeadingCommandNamesKey, hiddenCommandAliasesKey } from ".
 import { completeOrExtractPhase2Seed } from "./phase2-seed.js";
 import { multiple, optional, withDefault } from "./modifiers.js";
 import { group, longestMatch, object } from "./constructs.js";
+import { getHelpRequest } from "./internal/help-request.js";
 import { string } from "./valueparser.js";
 import { argument, command, constant, flag, option } from "./primitives.js";
 
@@ -1145,6 +1146,20 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		}
 	};
 	const parserMode = parser.mode;
+	const helpRequest = getHelpRequest(options);
+	if (helpRequest != null) return dispatchByMode(parserMode, () => {
+		const handled = handleResult({
+			type: "help",
+			commands: helpRequest,
+			preferUserCommandDocs: true
+		});
+		if (handled instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
+		return handled;
+	}, async () => await handleResult({
+		type: "help",
+		commands: helpRequest,
+		preferUserCommandDocs: true
+	}));
 	return dispatchByMode(parserMode, () => {
 		const attempted = attemptParseSync(parser, args, {
 			mode: "complete",
@@ -1368,6 +1383,7 @@ function shouldProbeEarlyExit(options, needsTwoPhase) {
 * handled without collecting source-context annotations first.
 */
 function needsEarlyExitSync(parser, args, options) {
+	if (getHelpRequest(options) != null) return true;
 	const attempted = attemptParseSync(parser, args, { mode: "parse-only" });
 	if (attempted.kind === "success") return false;
 	return isMetaEarlyExit(classifyEarlyExitFailure(attempted, options));
@@ -1376,6 +1392,7 @@ function needsEarlyExitSync(parser, args, options) {
 * Async variant of {@link needsEarlyExitSync}.
 */
 async function needsEarlyExitAsync(parser, args, options) {
+	if (getHelpRequest(options) != null) return true;
 	const attempted = await attemptParseAsync(parser, args, { mode: "parse-only" });
 	if (attempted.kind === "success") return false;
 	return isMetaEarlyExit(classifyEarlyExitFailure(attempted, options));

package/dist/internal/help-request.cjs

@@ -0,0 +1,33 @@
+
+//#region src/internal/help-request.ts
+/** Internal help request bridge; not a stable extension API. @module */
+const helpRequestKey = Symbol.for("@optique/core/internal/help-request");
+/**
+* Copies options with a help target independent of help entry-point names.
+* @param options The runner options to copy.
+* @param commands The canonical command path to display.
+* @returns Options carrying the internal request through transparent spreads.
+* @internal
+* @since 1.4.0
+*/
+function withHelpRequest(options, commands) {
+	return {
+		...options,
+		[helpRequestKey]: [...commands]
+	};
+}
+/**
+* Reads an internal help target, including the empty root path.
+* @param options The runner options.
+* @returns The requested path, or undefined when no request exists.
+* @internal
+* @since 1.4.0
+*/
+function getHelpRequest(options) {
+	const value = Reflect.get(options, helpRequestKey);
+	return Array.isArray(value) && value.every((part) => typeof part === "string") ? value : void 0;
+}
+
+//#endregion
+exports.getHelpRequest = getHelpRequest;
+exports.withHelpRequest = withHelpRequest;

package/dist/internal/help-request.d.cts

@@ -0,0 +1,20 @@
+//#region src/internal/help-request.d.ts
+/**
+ * Copies options with a help target independent of help entry-point names.
+ * @param options The runner options to copy.
+ * @param commands The canonical command path to display.
+ * @returns Options carrying the internal request through transparent spreads.
+ * @internal
+ * @since 1.4.0
+ */
+declare function withHelpRequest<T extends object>(options: T, commands: readonly string[]): T;
+/**
+ * Reads an internal help target, including the empty root path.
+ * @param options The runner options.
+ * @returns The requested path, or undefined when no request exists.
+ * @internal
+ * @since 1.4.0
+ */
+declare function getHelpRequest(options: object): readonly string[] | undefined;
+//#endregion
+export { getHelpRequest, withHelpRequest };

package/dist/internal/help-request.d.ts

@@ -0,0 +1,20 @@
+//#region src/internal/help-request.d.ts
+/**
+ * Copies options with a help target independent of help entry-point names.
+ * @param options The runner options to copy.
+ * @param commands The canonical command path to display.
+ * @returns Options carrying the internal request through transparent spreads.
+ * @internal
+ * @since 1.4.0
+ */
+declare function withHelpRequest<T extends object>(options: T, commands: readonly string[]): T;
+/**
+ * Reads an internal help target, including the empty root path.
+ * @param options The runner options.
+ * @returns The requested path, or undefined when no request exists.
+ * @internal
+ * @since 1.4.0
+ */
+declare function getHelpRequest(options: object): readonly string[] | undefined;
+//#endregion
+export { getHelpRequest, withHelpRequest };

package/dist/internal/help-request.js

@@ -0,0 +1,31 @@
+//#region src/internal/help-request.ts
+/** Internal help request bridge; not a stable extension API. @module */
+const helpRequestKey = Symbol.for("@optique/core/internal/help-request");
+/**
+* Copies options with a help target independent of help entry-point names.
+* @param options The runner options to copy.
+* @param commands The canonical command path to display.
+* @returns Options carrying the internal request through transparent spreads.
+* @internal
+* @since 1.4.0
+*/
+function withHelpRequest(options, commands) {
+	return {
+		...options,
+		[helpRequestKey]: [...commands]
+	};
+}
+/**
+* Reads an internal help target, including the empty root path.
+* @param options The runner options.
+* @returns The requested path, or undefined when no request exists.
+* @internal
+* @since 1.4.0
+*/
+function getHelpRequest(options) {
+	const value = Reflect.get(options, helpRequestKey);
+	return Array.isArray(value) && value.every((part) => typeof part === "string") ? value : void 0;
+}
+
+//#endregion
+export { getHelpRequest, withHelpRequest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2748",
+  "version": "1.4.0-dev.2749",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -243,6 +243,14 @@
       },
       "import": "./dist/internal/command-doc-policy.js",
       "require": "./dist/internal/command-doc-policy.cjs"
+    },
+    "./internal/help-request": {
+      "types": {
+        "import": "./dist/internal/help-request.d.ts",
+        "require": "./dist/internal/help-request.d.cts"
+      },
+      "import": "./dist/internal/help-request.js",
+      "require": "./dist/internal/help-request.cjs"
     }
   },
   "imports": {
@@ -253,7 +261,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2748+8f05c2bd",
+    "@optique/env": "1.4.0-dev.2749+6d558083",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -295,5 +295,5 @@ Integration packages
 | `@optique/git`              | Async Git reference validation              | <https://optique.dev/integrations/git.md>             |
 | `@optique/logtape`          | LogTape levels and formatter/output options | <https://optique.dev/integrations/logtape.md>         |
 | `@optique/man`              | Man page generation                         | <https://optique.dev/concepts/man.md>                 |
-| `@optique/discover`         | File-based command discovery                | <https://optique.dev/concepts/discover.md>            |
+| `@optique/discover`         | Command discovery; opt-in `help.bareGroup`  | <https://optique.dev/concepts/discover.md>            |
 | `@optique/testing`          | Layered CLI testing at a chosen boundary    | <https://optique.dev/concepts/testing.md>             |