@dereekb/dbx-cli 13.11.1 → 13.11.3

package/src/lib/config/token.cache.d.ts

@@ -36,6 +36,7 @@ export interface CreateCliTokenCacheStoreInput {
  * @param input - The cache store inputs.
  * @param input.tokenCachePath - Absolute path to the JSON file backing the cache.
  * @returns A {@link CliTokenCacheStore} keyed by env name.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function createCliTokenCacheStore(input: CreateCliTokenCacheStoreInput): CliTokenCacheStore;
 /**

package/src/lib/context/cli.context.d.ts

@@ -37,5 +37,6 @@ export interface CreateCliContextInput {
  * @param input.env - The resolved {@link CliEnvConfig} for the active env.
  * @param input.accessToken - The Bearer access token to include on outgoing API calls.
  * @returns The constructed {@link CliContext}.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function createCliContext(input: CreateCliContextInput): CliContext;

package/src/lib/doctor/doctor.command.factory.d.ts

@@ -44,5 +44,6 @@ export interface CreateDoctorCommandInput {
  * @param input.checks - Additional checks to append after the default check list.
  * @param input.defaultEnvs - Built-in env presets merged underneath the user's stored env when names match.
  * @returns A yargs `CommandModule` exposing the `doctor` command.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function createDoctorCommand(input: CreateDoctorCommandInput): CommandModule;

package/src/lib/env/env.command.factory.d.ts

@@ -18,5 +18,6 @@ export interface CreateEnvCommandInput {
  * @param input.cliName - The CLI's binary name.
  * @param input.defaultEnvs - Built-in env presets merged underneath the user's stored env when names match.
  * @returns A yargs `CommandModule` exposing the full `env` subcommand surface.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function createEnvCommand(input: CreateEnvCommandInput): CommandModule;

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
@@ -78,6 +103,7 @@ export declare const DEFAULT_MANIFEST_MODEL_COMMAND_NAME = "model";
  * @param options - Optional overrides; see {@link BuildManifestCommandsOptions}.
  * @returns The yargs `CommandModule[]` ready to be passed to `runCli({ apiCommands })`. Empty
  *   when the manifest has no callable entries.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function buildManifestCommands(manifest: CliApiManifest, options?: BuildManifestCommandsOptions): CommandModule[];
 /**
@@ -92,3 +118,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[];

package/src/lib/middleware/auth.middleware.d.ts

@@ -25,5 +25,6 @@ export interface CreateAuthMiddlewareInput {
  * @param input.skipCommands - Top-level command names that bypass authentication entirely.
  * @param input.defaultEnvs - Built-in env presets merged underneath the user's stored env when names match.
  * @returns A yargs middleware function suitable for `.middleware([..., true])`.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function createAuthMiddleware(input: CreateAuthMiddlewareInput): MiddlewareFunction;

package/src/lib/middleware/output.middleware.d.ts

@@ -50,5 +50,6 @@ export interface CreateOutputMiddlewareInput {
  * @param input.loadOutputConfig - Optional override for how the output config is read.
  * @param input.saveCommandOutputConfig - Optional override for how a per-command output config is persisted.
  * @returns A yargs middleware function suitable for `.middleware([..., true])`.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function createOutputMiddleware(input: CreateOutputMiddlewareInput): MiddlewareFunction;

package/src/lib/output/output.command.factory.d.ts

@@ -51,5 +51,6 @@ export interface CreateOutputCommandInput {
  * @param input.mergeOutputConfig - Optional override for persisting partial output-config updates.
  * @param input.clearOutputConfig - Optional override for clearing the persisted output config entirely.
  * @returns A yargs `CommandModule` exposing the full `output` subcommand surface.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function createOutputCommand(input: CreateOutputCommandInput): CommandModule;

package/src/lib/runner/run.d.ts

@@ -62,6 +62,7 @@ export interface CreateCliInput {
  * @param input.argv - Argv to parse. Defaults to `hideBin(process.argv)`.
  * @param input.disableCallPassthrough - When `true`, omits the built-in `call` passthrough.
  * @returns The configured yargs `Argv` ready to be `.parse()`-d.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function createCli(input: CreateCliInput): Argv;
 /**

package/src/lib/util/context.slot.d.ts

@@ -46,5 +46,6 @@ export interface CreateContextSlotInput {
  * @param input - Optional slot configuration.
  * @param input.notInitializedMessage - Custom error message thrown by `require()` when the slot is unset.
  * @returns A new {@link ContextSlot} for type `T`.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function createContextSlot<T>(input?: CreateContextSlotInput): ContextSlot<T>;

package/src/lib/util/output.d.ts

@@ -95,6 +95,7 @@ export declare function dumpTimestamp(): string;
  * @param extension - File extension to append (`json` for full responses, `ndjson` for streaming dumps).
  * @param suffix - Optional suffix appended to the filename before the extension.
  * @returns The absolute file path, or `undefined` when `dumpDir` is not configured.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function buildDumpFilePath(extension: 'json' | 'ndjson', suffix?: string): Maybe<string>;
 /**
@@ -148,5 +149,6 @@ export declare class CliError extends Error {
  *
  * @param error - The thrown value to convert.
  * @returns The structured {@link CliErrorOutput}.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function buildErrorOutput(error: unknown): CliErrorOutput;