@dereekb/dbx-cli 13.13.0 → 13.15.0

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

@@ -123,6 +123,12 @@ export interface CliModelManifestEntry {
      * Persisted-field metadata in source order.
      */
     readonly fields: readonly CliModelField[];
+    /**
+     * Per-model override of the MCP tool-name model segment, from `@dbxModelMcpToolNameSegment
+     * <segment>` on the model interface. When present it replaces the model type in generated tool
+     * names (e.g. the collection prefix). Absent when the model omits the tag.
+     */
+    readonly mcpToolNameSegment?: string;
     /**
      * Read posture declared by `@dbxModelRead <level>` on the model interface. Closed enum:
      * `system` / `owner` / `admin-only` / `permissions`. Absent when the model interface omits the tag.
@@ -181,6 +187,21 @@ export interface CliApiManifestEntry {
      * Per-field result descriptions read from the result interface's property JSDocs.
      */
     readonly resultFields?: readonly CliApiManifestField[];
+    /**
+     * Name of the MCP-mapped result interface declared via the `@dbxModelApiMcpResult <TypeName>`
+     * JSDoc tag on the CRUD leaf. Present only when a handler remaps its success result for MCP.
+     */
+    readonly mcpResultTypeName?: string;
+    /**
+     * Description from the MCP-mapped result interface's own JSDoc. The MCP manifest renderer prefers
+     * this over {@link resultTypeDescription} when building the tool output schema.
+     */
+    readonly mcpResultTypeDescription?: string;
+    /**
+     * Per-field descriptions read from the MCP-mapped result interface's property JSDocs. The MCP
+     * manifest renderer prefers these over {@link resultFields} when building the tool output schema.
+     */
+    readonly mcpResultFields?: readonly CliApiManifestField[];
 }
 export type CliApiManifest = readonly CliApiManifestEntry[];
 /**
@@ -210,6 +231,12 @@ export interface McpManifestToolEntry {
      * JSON Schema synthesized from `resultFields[]` / `resultTypeDescription`. Omitted when both absent.
      */
     readonly outputSchema?: object;
+    /**
+     * Name of the MCP-mapped result interface (from `@dbxModelApiMcpResult`) when the output schema was
+     * built from a mapped type. Present iff the source leaf was annotated — the runtime tool generator
+     * uses it to detect handlers whose `mapSuccessfulResult` lacks the matching `.api.ts` annotation.
+     */
+    readonly mcpResultTypeName?: string;
 }
 /**
  * One persisted field on a {@link McpManifestModelEntry}.
@@ -245,6 +272,12 @@ export interface McpManifestModelEntry {
     readonly sourcePackage: string;
     readonly sourceFile: string;
     readonly fields: readonly McpManifestModelField[];
+    /**
+     * Per-model override of the model segment used in generated MCP tool names (mirror of
+     * {@link CliModelManifestEntry.mcpToolNameSegment}). Consumed by the runtime generator and the
+     * build-time name validation so both compose the same names.
+     */
+    readonly mcpToolNameSegment?: string;
 }
 /**
  * One auth claim entry in the pre-rendered MCP manifest JSON. Powers the
@@ -323,3 +356,106 @@ export interface McpManifest {
  * @returns The canonical `modelType.call.specifier` lookup key, with the default specifier normalized to `_`.
  */
 export declare function mcpManifestKey(modelType: string, call: string, specifier?: Maybe<string>): string;
+/**
+ * Default specifier key used when a handler is not behind a specifier router.
+ *
+ * Mirrors `DEFAULT_SPECIFIER_KEY` in `@dereekb/firebase-server/mcp` — kept in sync so the
+ * build-time renderer composes the same tool names as the runtime generator.
+ */
+export declare const DEFAULT_SPECIFIER_KEY = "_";
+/**
+ * Soft limit for an MCP tool name. Mirrors `MCP_TOOL_NAME_WARN_LENGTH` in
+ * `@dereekb/firebase-server/mcp`. Names over this are flagged at manifest-generation time.
+ */
+export declare const MCP_TOOL_NAME_WARN_LENGTH = 55;
+/**
+ * Hard limit for an MCP tool name. Mirrors `MCP_TOOL_NAME_MAX_LENGTH` in
+ * `@dereekb/firebase-server/mcp`. Remote MCP clients reject a `tools/list` payload containing any
+ * tool whose `name` exceeds this, so manifest generation fails when a name is over the cap.
+ */
+export declare const MCP_TOOL_NAME_MAX_LENGTH = 64;
+/**
+ * Severity of a tool name's length relative to the soft / hard limits.
+ */
+export type McpToolNameLengthLevel = 'ok' | 'warn' | 'error';
+/**
+ * The outcome of validating a tool name's length.
+ */
+export interface McpToolNameValidation {
+    readonly name: string;
+    readonly length: number;
+    readonly level: McpToolNameLengthLevel;
+}
+/**
+ * Builds the MCP tool name for a (modelSegment, callType, specifier) triple.
+ *
+ * Mirrors `buildMcpToolName` in `@dereekb/firebase-server/mcp` so the build-time manifest validation
+ * sees the same names the runtime advertises. The call-type segment is only emitted for the default
+ * (`_`) specifier; named specifiers drop it (`worker-syncCheckHqEmployee`).
+ *
+ * @param modelSegment - The model segment of the name (model type, or a per-model override).
+ * @param callType - The call type / verb.
+ * @param specifier - The specifier key, or `_` / undefined for the default entry.
+ * @returns The hyphen-joined tool name.
+ *
+ * @example
+ * ```ts
+ * buildMcpToolName('worker', 'update', 'syncCheckHqEmployee'); // 'worker-syncCheckHqEmployee'
+ * ```
+ */
+export declare function buildMcpToolName(modelSegment: string, callType: string, specifier?: Maybe<string>): string;
+/**
+ * Classifies a tool name's length against the soft/hard MCP name-length limits.
+ *
+ * Mirrors `validateMcpToolName` in `@dereekb/firebase-server/mcp`.
+ *
+ * @param name - The fully-resolved tool name.
+ * @returns The length classification — `error` over {@link MCP_TOOL_NAME_MAX_LENGTH}, `warn` over
+ *   {@link MCP_TOOL_NAME_WARN_LENGTH}, otherwise `ok`.
+ *
+ * @example
+ * ```ts
+ * validateMcpToolName('worker-create').level; // 'ok'
+ * ```
+ */
+export declare function validateMcpToolName(name: string): McpToolNameValidation;
+/**
+ * Single-character abbreviations for the standard CRUDQ + invoke call types.
+ *
+ * Mirrors `MCP_CALL_TYPE_ABBREVIATIONS` in `@dereekb/firebase-server/mcp` so the build-time renderer
+ * disambiguates colliding names exactly like the runtime generator.
+ */
+export declare const MCP_CALL_TYPE_ABBREVIATIONS: Readonly<Record<string, string>>;
+/**
+ * Abbreviates a call type for a disambiguated tool name; a custom call type is returned unchanged.
+ *
+ * Mirrors `abbreviateMcpCallType` in `@dereekb/firebase-server/mcp`.
+ *
+ * @param callType - The call type / verb.
+ * @returns The single-character abbreviation, or the original string for a custom call type.
+ *
+ * @example
+ * ```ts
+ * abbreviateMcpCallType('update'); // 'u'
+ * ```
+ */
+export declare function abbreviateMcpCallType(callType: string): string;
+/**
+ * Builds the disambiguated MCP tool name — the form used only when {@link buildMcpToolName} collides
+ * with another visible tool. Named specifiers re-insert the abbreviated call type
+ * (`worker-u-syncCheckHqEmployee`); default (`_`) specifiers already carry the full call type and are
+ * returned unchanged.
+ *
+ * Mirrors `buildDisambiguatedMcpToolName` in `@dereekb/firebase-server/mcp`.
+ *
+ * @param modelSegment - The model segment of the name (model type, or a per-model override).
+ * @param callType - The call type / verb.
+ * @param specifier - The specifier key, or `_` / undefined for the default entry.
+ * @returns The hyphen-joined disambiguated tool name.
+ *
+ * @example
+ * ```ts
+ * buildDisambiguatedMcpToolName('worker', 'update', 'syncCheckHqEmployee'); // 'worker-u-syncCheckHqEmployee'
+ * ```
+ */
+export declare function buildDisambiguatedMcpToolName(modelSegment: string, callType: string, specifier?: Maybe<string>): string;

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

@@ -55,6 +55,13 @@ export declare const DEFAULT_CLI_SECRET_PATTERNS: CliSecretPattern[];
  * back to the built-in `CliError` / `Error` / unknown branches. Returning `undefined` defers to the defaults.
  */
 export type CliErrorMapper = (error: unknown) => Maybe<CliErrorOutput>;
+/**
+ * Default per-request HTTP timeout in milliseconds, applied when no explicit `--timeout` is set.
+ *
+ * Without a default, the HTTP layer's `fetch` waits indefinitely on an unresponsive server, which
+ * surfaces as a CLI (or CI test) that hangs forever rather than failing with a clear error.
+ */
+export declare const DEFAULT_CLI_HTTP_TIMEOUT_MS = 60000;
 /**
  * Configures output options from parsed CLI arguments.
  *
@@ -105,10 +112,11 @@ export declare function tracedFetch(fetcher: typeof fetch | undefined, input: st
 /**
  * Sets the process-wide HTTP timeout (in milliseconds) honored by the HTTP layer.
  *
- * Pass `undefined` to clear. The HTTP helpers thread this into an `AbortController`
- * so individual `fetch` calls cancel after the configured duration.
+ * The HTTP helpers thread a positive value into an `AbortController` so individual `fetch` calls
+ * cancel after the configured duration. `undefined` falls back to {@link DEFAULT_CLI_HTTP_TIMEOUT_MS};
+ * `0` (or a negative value) disables the timeout entirely (the request waits indefinitely).
  *
- * @param ms - Timeout in ms, or `undefined` to clear.
+ * @param ms - Timeout in ms, `0`/negative to disable, or `undefined` to fall back to the default.
  */
 export declare function setCliTimeoutMs(ms: Maybe<number>): void;
 /**

package/test/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/dbx-cli/test",
-  "version": "13.13.0",
+  "version": "13.15.0",
   "peerDependencies": {
-    "@dereekb/date": "13.13.0",
-    "@dereekb/dbx-cli": "13.13.0",
-    "@dereekb/firebase": "13.13.0",
-    "@dereekb/firebase-server/test": "13.13.0",
-    "@dereekb/model": "13.13.0",
-    "@dereekb/nestjs": "13.13.0",
-    "@dereekb/rxjs": "13.13.0",
-    "@dereekb/util": "13.13.0",
+    "@dereekb/date": "13.15.0",
+    "@dereekb/dbx-cli": "13.15.0",
+    "@dereekb/firebase": "13.15.0",
+    "@dereekb/firebase-server/test": "13.15.0",
+    "@dereekb/model": "13.15.0",
+    "@dereekb/nestjs": "13.15.0",
+    "@dereekb/rxjs": "13.15.0",
+    "@dereekb/util": "13.15.0",
     "@nestjs/common": "^11.1.19",
     "arktype": "^2.2.0",
     "vitest": "4.1.5",