@dereekb/dbx-cli 13.11.0 → 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
@@ -48,19 +73,36 @@ export interface BuildManifestCommandsOptions {
      * {@link createCli}).
      */
     readonly hiddenWhenFocused?: readonly string[];
+    /**
+     * Name of the parent command that groups all per-model dispatch subcommands.
+     * Defaults to {@link DEFAULT_MANIFEST_MODEL_COMMAND_NAME} (`model`), so the
+     * full invocation reads `<cli> model <model> <action>`.
+     */
+    readonly modelCommandName?: string;
 }
+/**
+ * Default name of the parent command that groups all per-model manifest commands.
+ * Surfaces as `<cli> model <model> <action>` so the top-level `--help` stays focused
+ * on first-class commands instead of dumping every model.
+ */
+export declare const DEFAULT_MANIFEST_MODEL_COMMAND_NAME = "model";
 /**
  * Builds yargs `CommandModule[]` from a generated {@link CliApiManifest}.
  *
- * Groups entries by `model`, emitting one parent command per model and one child action per entry
- * (named `<verb>` or `<verb>-<specifier>`). Each child accepts `--data <json>`, validates the
+ * Returns a single parent command (default name `model`) whose subcommands are the per-model
+ * dispatch commands. Each per-model subcommand has one child action per entry
+ * (named `<verb>` or `<verb>-<specifier>`). Each leaf accepts `--data <json>`, validates the
  * payload against the entry's bound arktype validator (when present), and dispatches via the
  * authenticated CLI context's `callModel` helper. Standalone entries are skipped because they
  * are not dispatched through the `/model/call` endpoint.
  *
+ * Wrapping under `model` keeps the top-level `--help` short — users invoke
+ * `<cli> model --help` to see the full list of available models.
+ *
  * @param manifest - The generated manifest array.
  * @param options - Optional overrides; see {@link BuildManifestCommandsOptions}.
- * @returns The yargs `CommandModule[]` ready to be passed to `runCli({ apiCommands })`.
+ * @returns The yargs `CommandModule[]` ready to be passed to `runCli({ apiCommands })`. Empty
+ *   when the manifest has no callable entries.
  */
 export declare function buildManifestCommands(manifest: CliApiManifest, options?: BuildManifestCommandsOptions): CommandModule[];
 /**
@@ -75,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[];

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

@@ -20,6 +20,9 @@ export interface CreateCliInput {
      * App-specific API commands appended after the built-in `call` passthrough.
      *
      * Commands listed here run after the auth middleware, so they have access to the {@link CliContext}.
+     *
+     * For manifest-driven typed model commands, pass the result of `buildManifestCommands(manifest)` —
+     * it returns a single parent `model <model>` command so the top-level `--help` stays focused.
      */
     readonly apiCommands?: CommandModule[];
     /**

package/firebase-api-manifest/src/generate-api-manifest/bind-validators.d.ts

@@ -1,44 +0,0 @@
-/**
- * For a given Params type name (e.g. `SetProfileUsernameParams`), derives the
- * canonical arktype validator identifier (`setProfileUsernameParamsType`) by
- * naming convention and confirms it is exported from the resolved package.
- *
- * Verification is best-effort: we string-search the package's `src/index.ts`
- * and follow `export * from './...';` re-exports recursively until we find
- * the declaration of the validator. The convention everywhere in the codebase
- * is `export const <name>ParamsType = ... as Type<<Name>Params>`.
- */
-/**
- * Derives the canonical arktype validator identifier from a Params type name.
- *
- * `SetProfileUsernameParams` → `setProfileUsernameParamsType`.
- *
- * @param paramsTypeName - PascalCase Params type identifier.
- * @returns The lowerCamelCase validator identifier (or empty string for empty input).
- */
-export declare function deriveValidatorName(paramsTypeName: string): string;
-/**
- * Inputs for {@link isExportedFromPackage}.
- */
-export interface IsExportedInput {
-    readonly packageRoot: string;
-    readonly identifier: string;
-}
-/**
- * Confirms an identifier is exported from `packageRoot/src/index.ts` —
- * directly or via re-export chains.
- *
- * @param input - Package root + identifier to look up.
- * @returns `true` when the identifier is reachable from the barrel.
- */
-export declare function isExportedFromPackage(input: IsExportedInput): boolean;
-/**
- * Walks the `src/lib` tree under a package and returns the absolute file
- * paths of every `.ts` file (used as a fallback when index-chain lookup
- * misses the identifier — some packages rely on flat barrels that don't
- * `export *`).
- *
- * @param packageRoot - Absolute path to the source package's root directory.
- * @returns Absolute paths of every non-spec `.ts` file under `src`.
- */
-export declare function listPackageTsFiles(packageRoot: string): string[];

package/firebase-api-manifest/src/generate-api-manifest/emit.d.ts

@@ -1,29 +0,0 @@
-/**
- * Renders the final manifest TS module — banner + grouped imports + the
- * `<NAMESPACE>` array literal. Formatted with the workspace prettier config
- * so the output matches what `prettier --write` would produce on the
- * committed file.
- *
- * The reusable `CliApiManifest` type is imported from `@dereekb/dbx-cli` so
- * any consuming app gets it from the shared dbx-cli barrel.
- */
-import type { CollectedEntry } from './types';
-/**
- * Inputs for {@link renderManifest}.
- */
-export interface RenderManifestInput {
-    readonly outputFile: string;
-    readonly entries: readonly CollectedEntry[];
-    readonly projectName: string;
-    readonly namespace: string;
-}
-/**
- * Renders the manifest TS source for a CLI app and formats it with the
- * workspace prettier config so the output matches a `prettier --write` of the
- * committed file.
- *
- * @param input - Output file path, collected entries, project name (banner),
- *   and the manifest namespace identifier.
- * @returns Prettier-formatted TypeScript source.
- */
-export declare function renderManifest(input: RenderManifestInput): Promise<string>;

package/firebase-api-manifest/src/generate-api-manifest/extract-crud.d.ts

@@ -1,25 +0,0 @@
-/**
- * Walks `<Group>ModelCrudFunctionsConfig` and `<Group>FunctionTypeMap` type
- * aliases in a `<model>.api.ts` source. Returns one entry per callable leaf,
- * keyed by (model, verb, specifier).
- *
- * Mirrors `extractCrudEntries` from
- * packages/dbx-components-mcp/src/tools/model-api-shared/extract-crud.ts —
- * keep the two in lockstep when the .api.ts convention changes.
- */
-import type { CrudExtraction } from './types';
-/**
- * Inputs for {@link extractCrudEntries}.
- */
-export interface ExtractCrudInput {
-    readonly name: string;
-    readonly text: string;
-}
-/**
- * Extracts CRUD + standalone entries from a `.api.ts` source by walking its
- * `<Group>ModelCrudFunctionsConfig` and `<Group>FunctionTypeMap` aliases.
- *
- * @param source - The source file's name + text.
- * @returns The extracted entries, group name, model keys, and `*Functions` class name.
- */
-export declare function extractCrudEntries(source: ExtractCrudInput): CrudExtraction;

package/firebase-api-manifest/src/generate-api-manifest/find-api-files.d.ts

@@ -1,16 +0,0 @@
-/**
- * Walks a package's `src/lib/**\/*.api.ts` and returns the files that declare
- * an abstract `*Functions` class along with the class name. Used to map a
- * class identifier from `<APP>_FIREBASE_FUNCTIONS_CONFIG` back to the source
- * `*.api.ts`.
- */
-import type { ApiFileMatch } from './types';
-/**
- * Walks `packageRoot/src/lib/**\/*.api.ts` and returns the files that declare
- * an abstract `*Functions` class along with the class name and the
- * extracted CRUD entries.
- *
- * @param packageRoot - Absolute path to the source package's root directory.
- * @returns One {@link ApiFileMatch} per qualifying `.api.ts`.
- */
-export declare function findApiFiles(packageRoot: string): ApiFileMatch[];

package/firebase-api-manifest/src/generate-api-manifest/main.d.ts

@@ -1,46 +0,0 @@
-/**
- * Generates an API manifest TS file for any dbx-components CLI app.
- *
- * Pipeline (build-time, run via `nx run <cli>:generate-api-manifest`):
- *
- *   1. Parse the app's `<APP>_FIREBASE_FUNCTIONS_CONFIG` from the file passed
- *      via --functions-config to enumerate the `*Functions` abstract classes
- *      used by the app, including their source-module specifier
- *      ("@dereekb/firebase", "demo-firebase", "./model", "./development",
- *      ...). The leading-app prefix is matched generically by
- *      `/FIREBASE_FUNCTIONS_CONFIG$/` so any app variable name works.
- *
- *   2. Resolve each module to a source-package root via the workspace's
- *      tsconfig.base.json `paths`.
- *
- *   3. Walk that package's `src/lib/**\/*.api.ts`, run the CRUD-entry walker
- *      on each, and pick the file whose abstract `*Functions` class name
- *      matches the entry's class identifier.
- *
- *   4. For each CRUD entry with a `paramsTypeName`, derive the canonical
- *      arktype validator name (lowercaseFirst + `Type`) and confirm it is
- *      exported from the package's barrel chain. Warn on miss; the entry is
- *      still emitted with `paramsValidator: undefined`. `--strict` makes a
- *      miss fatal.
- *
- *   5. Emit the manifest to the path passed via --output with grouped
- *      per-package imports + the `<NAMESPACE>_API_MANIFEST` array literal.
- *      Skip the write if the file content is byte-identical (preserves mtime
- *      for incremental builds).
- *
- * Flags:
- *   --functions-config=<path>   (required) path to the app's functions.ts.
- *                                Absolute or workspace-relative.
- *   --output=<path>             (required) path to the manifest TS file to write.
- *                                Absolute or workspace-relative.
- *   --project=<name>            Project name shown in the regenerate banner
- *                                (defaults to "<cli>"). Also used to derive
- *                                the manifest namespace (e.g. "demo-cli" ->
- *                                DEMO_CLI_API_MANIFEST).
- *   --only=<model[,model]>      Filter the emitted entries to those models.
- *   --strict                    Exit 1 if any validator is missing.
- *
- * Run from any cwd; workspace-relative paths resolve against `process.cwd()`
- * (Nx invokes with cwd: "{workspaceRoot}").
- */
-export {};

package/firebase-api-manifest/src/generate-api-manifest/parse-functions.d.ts

@@ -1,18 +0,0 @@
-/**
- * Parses the `<APP>_FIREBASE_FUNCTIONS_CONFIG` variable from a CLI app's
- * `functions.ts` and returns the (groupKey, className, importedFromModule)
- * tuple for every entry.
- *
- * We follow the import declaration of the abstract-class identifier to know
- * which package the `*.api.ts` lives in. The variable name is matched
- * generically by `/FIREBASE_FUNCTIONS_CONFIG$/` so any app-prefix works.
- */
-import type { FunctionsGroup } from './types';
-/**
- * Parses the `<APP>_FIREBASE_FUNCTIONS_CONFIG` literal at `functionsTsPath`
- * into one entry per group declared in the config object.
- *
- * @param functionsTsPath - Absolute path to the app's `functions.ts`.
- * @returns One {@link FunctionsGroup} per `<groupKey>: [<Class>, ...]` pair.
- */
-export declare function parseFunctionsConfig(functionsTsPath: string): FunctionsGroup[];

package/firebase-api-manifest/src/generate-api-manifest/resolve-package.d.ts

@@ -1,59 +0,0 @@
-/**
- * Resolves a workspace module specifier (e.g. "@dereekb/firebase",
- * "demo-firebase", "./model", "./development") to a source-package root and
- * canonical import name.
- *
- * Reads the workspace tsconfig.base.json `compilerOptions.paths` to map bare
- * specifiers to their `src/index.ts` entry. Relative specifiers are resolved
- * against the importing file's directory and then walked back up to the
- * nearest `package.json` that owns them.
- */
-import type { PackageRef } from './types';
-/**
- * Inputs accepted by {@link resolveModuleToPackage}.
- */
-export interface ResolveModuleInput {
-    readonly workspaceRoot: string;
-    readonly importingFile: string;
-    readonly moduleSpecifier: string;
-}
-/**
- * Reads `tsconfig.base.json` and returns the `compilerOptions.paths` map
- * (canonical bare specifier → absolute path to its `src/index.ts`).
- *
- * @param workspaceRoot - Workspace root directory.
- * @returns Cached map of canonical specifiers to absolute index paths.
- */
-export declare function loadTsconfigPaths(workspaceRoot: string): Map<string, string>;
-/**
- * Resolves a module specifier to the source-package that owns it.
- *
- * @param input - Workspace root + importing-file location + the specifier.
- * @returns The {@link PackageRef} of the owning package, or `undefined` when unresolved.
- */
-export declare function resolveModuleToPackage(input: ResolveModuleInput): PackageRef | undefined;
-/**
- * Walks up from `startPath` until it finds a directory containing a `package.json`
- * with a `name` field, then returns its package name + root.
- *
- * @param workspaceRoot - Stop walking when this directory is reached.
- * @param startPath - Path to walk up from.
- * @returns The package name + root, or `undefined` if no package.json is found.
- */
-export declare function locatePackageForPath(workspaceRoot: string, startPath: string): PackageRef | undefined;
-/**
- * Returns the workspace-root-relative path with forward slashes for display.
- *
- * @param workspaceRoot - Workspace root directory.
- * @param absolutePath - Absolute path to make relative.
- * @returns The workspace-relative path with forward slashes.
- */
-export declare function relPath(workspaceRoot: string, absolutePath: string): string;
-/**
- * Type-narrowed `isAbsolute` re-export so the generator scripts only depend on
- * `node:path` indirectly through this module.
- *
- * @param value - Path to test.
- * @returns `true` when the path is absolute.
- */
-export declare function isAbsolutePathLike(value: string): boolean;

package/firebase-api-manifest/src/generate-api-manifest/types.d.ts

@@ -1,44 +0,0 @@
-/**
- * Internal types shared between the generator's pipeline stages.
- *
- * The runtime manifest types (`CliApiManifest`, `CliApiManifestEntry`,
- * `CliApiVerb`) live in `packages/dbx-cli/src/lib/manifest/types.ts` and are
- * re-exported from `@dereekb/dbx-cli`. The generator emits TypeScript that
- * imports those runtime types — it does not reference them itself.
- */
-export interface FunctionsGroup {
-    readonly groupKey: string;
-    readonly className: string;
-    readonly importedFromModule: string;
-}
-export interface PackageRef {
-    readonly packageName: string;
-    readonly packageRoot: string;
-}
-export interface CrudEntry {
-    readonly model: string;
-    readonly verb: string;
-    readonly specifier?: string;
-    readonly paramsTypeName?: string;
-    readonly resultTypeName?: string;
-    readonly line: number;
-}
-export interface CrudExtraction {
-    readonly groupName: string | undefined;
-    readonly modelKeys: readonly string[];
-    readonly entries: readonly CrudEntry[];
-    readonly functionsClassName?: string;
-}
-export interface ApiFileMatch {
-    readonly filePath: string;
-    readonly className: string;
-    readonly extraction: CrudExtraction;
-}
-export interface CollectedEntry {
-    readonly entry: CrudEntry & {
-        readonly groupName: string;
-        readonly sourceFile: string;
-    };
-    readonly packageName?: string;
-    readonly validatorName?: string;
-}