@dereekb/dbx-cli 13.11.1 → 13.11.2

package/src/lib/manifest/build-manifest-commands.d.ts

@@ -1,5 +1,22 @@
 import { type CommandModule } from 'yargs';
 import { type CliApiManifest } from './types';
+/**
+ * Controls which sections of an action's `--help` epilogue are rendered.
+ *
+ *  - `action` (just the action explainer): only the action description JSDoc.
+ *    Useful when you already know the params shape and want to remember what
+ *    the command does.
+ *  - `params` (just the params explainer): only the params interface
+ *    description, per-field descriptions, schema, result, and source. Useful
+ *    when you already know what the command does and need to remember the
+ *    input shape.
+ *  - `both` (default): both sections together.
+ */
+export type ManifestHelpMode = 'action' | 'params' | 'both';
+/**
+ * Default help mode when no override is supplied.
+ */
+export declare const DEFAULT_MANIFEST_HELP_MODE: ManifestHelpMode;
 /**
  * Format used for the `Params Schema` section of a manifest command's `--help`
  * epilogue.
@@ -33,6 +50,14 @@ export interface BuildManifestCommandsOptions {
      * {@link DEFAULT_MANIFEST_HELP_DATA_FORMAT}.
      */
     readonly dataHelpFormat?: ManifestHelpDataFormat;
+    /**
+     * Which sections of the help epilogue to render.
+     *
+     * When omitted, the configured argv is scanned for `--help-mode=<mode>` (or
+     * `--help-mode <mode>`). Falls back to {@link DEFAULT_MANIFEST_HELP_MODE}
+     * (`both`).
+     */
+    readonly helpMode?: ManifestHelpMode;
     /**
      * Whether to hide unrelated global options (like `--verbose`, `--dump-dir`,
      * `--pick`, …) from `--help` when the user passed `--data-help`. Defaults
@@ -92,3 +117,16 @@ export declare function buildManifestCommands(manifest: CliApiManifest, options?
  * @returns The detected format, or {@link DEFAULT_MANIFEST_HELP_DATA_FORMAT}.
  */
 export declare function detectDataHelpFormat(argv?: readonly string[]): ManifestHelpDataFormat;
+/**
+ * Inspects an argv array for `--help-mode=<mode>` or `--help-mode <mode>` and
+ * returns the requested {@link ManifestHelpMode}. Unrecognized values fall
+ * back to {@link DEFAULT_MANIFEST_HELP_MODE}.
+ *
+ * Implemented as a raw argv scan (rather than going through yargs) because the
+ * value is needed when each command's builder runs — which is before yargs
+ * parses argv.
+ *
+ * @param argv - argv to inspect (defaults to `process.argv`).
+ * @returns The detected mode, or {@link DEFAULT_MANIFEST_HELP_MODE}.
+ */
+export declare function detectHelpMode(argv?: readonly string[]): ManifestHelpMode;

package/src/lib/manifest/types.d.ts

@@ -14,7 +14,27 @@ export interface CliApiManifestEntry {
     readonly resultTypeName?: string;
     readonly groupName: string;
     readonly sourceFile: string;
+    /**
+     * Per-action description, rendered as the command's `describe` in `--help`.
+     */
     readonly description?: string;
+    /**
+     * Description from the params interface's own JSDoc (e.g. on `ResetProfilePasswordParams`).
+     * Rendered in the `--help` epilogue under the params section.
+     */
+    readonly paramsTypeDescription?: string;
+    /**
+     * Per-field params descriptions read from the params interface's property JSDocs.
+     */
     readonly paramsFields?: readonly CliApiManifestField[];
+    /**
+     * Description from the result interface's own JSDoc (e.g. on `DownloadProfileArchiveResult`).
+     * Surfaces the same way `paramsTypeDescription` does, but for the response side.
+     */
+    readonly resultTypeDescription?: string;
+    /**
+     * Per-field result descriptions read from the result interface's property JSDocs.
+     */
+    readonly resultFields?: readonly CliApiManifestField[];
 }
 export type CliApiManifest = readonly CliApiManifestEntry[];