@optique/core 1.3.0-dev.2519 → 1.3.0-dev.2522

package/dist/facade.cjs

@@ -1054,8 +1054,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							sectionOrder,
 							showUsage
 						}));
+						return onHelp(0, renderedDoc);
 					}
-					return onHelp(0);
+					throw new RunParserError("Failed to generate help page.");
 				};
 				if (classified.commands.length > 0) {
 					let validationContext = {

package/dist/facade.d.cts

@@ -1,6 +1,6 @@
 import { Message } from "./message.cjs";
 import { HiddenVisibility, OptionName, Usage } from "./usage.cjs";
-import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.cjs";
+import { DocPage, DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.cjs";
@@ -180,8 +180,19 @@ interface RunOptions<THelp, TError> {
    * @since 1.0.0
    */
   readonly help?: {
-    /** Callback invoked when help is requested. */
-    readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
+    /**
+     * Callback invoked after help output, with the exit code and the final
+     * page passed to {@link formatDocPage}. Treat the page as read-only.
+     * It includes runner-provided entries and root usage customization.
+     * Subcommand and meta-command help use the selected command's docs,
+     * with the run-level footer as a fallback. Formatting options remain
+     * separate from the page.
+     *
+     * Handlers may ignore either argument. Wrappers that invoke this
+     * callback themselves must forward both arguments.
+     * @since 1.3.0 Added the `page` parameter.
+     */
+    readonly onShow?: (exitCode: number, page: DocPage) => THelp;
   } & ({
     readonly command: true | CommandSubConfig;
     readonly option?: true | OptionSubConfig;
@@ -341,7 +352,7 @@ interface RunOptions<THelp, TError> {
  *          whitespace or control characters, or (for option names) lacks a
  *          valid prefix (`--`, `-`, `/`, or `+`).
  * @throws {RunParserError} When parsing fails and no `onError` callback is
- *          provided.
+ *          provided, or if the requested help page cannot be generated.
  * @since 0.10.0 Added support for {@link Program} objects.
  */
 declare function runParser<T, THelp = void, TError = never>(program: Program<"sync", T>, args: readonly string[], options?: RunOptions<THelp, TError>): T;

package/dist/facade.d.ts

@@ -1,6 +1,6 @@
 import { Message } from "./message.js";
 import { HiddenVisibility, OptionName, Usage } from "./usage.js";
-import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.js";
+import { DocPage, DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.js";
 import { ShellCompletion } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.js";
@@ -180,8 +180,19 @@ interface RunOptions<THelp, TError> {
    * @since 1.0.0
    */
   readonly help?: {
-    /** Callback invoked when help is requested. */
-    readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
+    /**
+     * Callback invoked after help output, with the exit code and the final
+     * page passed to {@link formatDocPage}. Treat the page as read-only.
+     * It includes runner-provided entries and root usage customization.
+     * Subcommand and meta-command help use the selected command's docs,
+     * with the run-level footer as a fallback. Formatting options remain
+     * separate from the page.
+     *
+     * Handlers may ignore either argument. Wrappers that invoke this
+     * callback themselves must forward both arguments.
+     * @since 1.3.0 Added the `page` parameter.
+     */
+    readonly onShow?: (exitCode: number, page: DocPage) => THelp;
   } & ({
     readonly command: true | CommandSubConfig;
     readonly option?: true | OptionSubConfig;
@@ -341,7 +352,7 @@ interface RunOptions<THelp, TError> {
  *          whitespace or control characters, or (for option names) lacks a
  *          valid prefix (`--`, `-`, `/`, or `+`).
  * @throws {RunParserError} When parsing fails and no `onError` callback is
- *          provided.
+ *          provided, or if the requested help page cannot be generated.
  * @since 0.10.0 Added support for {@link Program} objects.
  */
 declare function runParser<T, THelp = void, TError = never>(program: Program<"sync", T>, args: readonly string[], options?: RunOptions<THelp, TError>): T;

package/dist/facade.js

@@ -1054,8 +1054,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							sectionOrder,
 							showUsage
 						}));
+						return onHelp(0, renderedDoc);
 					}
-					return onHelp(0);
+					throw new RunParserError("Failed to generate help page.");
 				};
 				if (classified.commands.length > 0) {
 					let validationContext = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0-dev.2519",
+  "version": "1.3.0-dev.2522",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -221,7 +221,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.3.0-dev.2519+af660a4e",
+    "@optique/env": "1.3.0-dev.2522+939139d1",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -11,19 +11,19 @@ description: >
 license: MIT
 ---
 
-Build CLI grammars by composing Optique parsers instead of walking `argv`.
-
-If online, start at <https://optique.dev/llms.txt> for maintained docs. These
-rules also cover common pitfalls when offline.
+Start at <https://optique.dev/llms.txt> when online. These rules cover the
+combinatorial parser model and common pitfalls offline.
 
 
 Core rules
 ----------
 
  -  Use `run()` from *@optique/run* for applications; use `parse()` or
-    `runParser()` for embedded and custom runtimes. With `runParser()`,
-    `onError(exitCode, error)` receives a structured `Message` after stderr
-    output; use that argument instead of parsing rendered error text.
+    `runParser()` for embedded and custom runtimes.
+ -  With `runParser()`, `onError(exitCode, error)` supplies a structured
+    `Message`; `help.onShow(exitCode, page)` supplies the final `DocPage`. Both
+    follow output. Supply `stdout: () => {}` for custom help rendering. See
+    <https://optique.dev/concepts/runners.md#structured-help-callbacks>.
  -  In tests, use `parseArgs()`/`parseArgsSync()` from *@optique/testing/parser*
     for parser results, `captureRun()` from *@optique/testing/run* for runner
     output/exits, `captureProgramRun()` from *@optique/testing/discover* for