@dereekb/dbx-cli 14.6.0 → 14.7.0

package/lint-cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli-lint-cache",
-  "version": "14.6.0",
+  "version": "14.7.0",
   "sideEffects": false,
   "private": true,
   "type": "module",
@@ -9,7 +9,7 @@
     "eslint": "10.9.1"
   },
   "peerDependencies": {
-    "@dereekb/util": "14.6.0",
+    "@dereekb/util": "14.7.0",
     "yargs": "^18.0.0"
   }
 }

package/manifest-extract/package.json

@@ -1,21 +1,21 @@
 {
   "name": "@dereekb/dbx-cli/manifest-extract",
-  "version": "14.6.0",
+  "version": "14.7.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "14.6.0",
-    "@dereekb/dbx-cli": "14.6.0",
-    "@dereekb/firebase": "14.6.0",
-    "@dereekb/model": "14.6.0",
-    "@dereekb/nestjs": "14.6.0",
-    "@dereekb/oauth-resource": "14.6.0",
-    "@dereekb/rxjs": "14.6.0",
-    "@dereekb/util": "14.6.0",
+    "@dereekb/date": "14.7.0",
+    "@dereekb/dbx-cli": "14.7.0",
+    "@dereekb/firebase": "14.7.0",
+    "@dereekb/model": "14.7.0",
+    "@dereekb/nestjs": "14.7.0",
+    "@dereekb/oauth-resource": "14.7.0",
+    "@dereekb/rxjs": "14.7.0",
+    "@dereekb/util": "14.7.0",
     "ts-morph": "^28.0.0"
   },
   "devDependencies": {
-    "@dereekb/firebase": "14.6.0"
+    "@dereekb/firebase": "14.7.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/model-test/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dereekb/dbx-cli/model-test",
-  "version": "14.6.0",
+  "version": "14.7.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/util": "14.6.0",
+    "@dereekb/util": "14.7.0",
     "ts-morph": "^28.0.0"
   },
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli",
-  "version": "14.6.0",
+  "version": "14.7.0",
   "type": "module",
   "sideEffects": false,
   "bin": {
@@ -66,12 +66,12 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "14.6.0",
-    "@dereekb/firebase": "14.6.0",
-    "@dereekb/model": "14.6.0",
-    "@dereekb/nestjs": "14.6.0",
-    "@dereekb/oauth-resource": "14.6.0",
-    "@dereekb/util": "14.6.0",
+    "@dereekb/date": "14.7.0",
+    "@dereekb/firebase": "14.7.0",
+    "@dereekb/model": "14.7.0",
+    "@dereekb/nestjs": "14.7.0",
+    "@dereekb/oauth-resource": "14.7.0",
+    "@dereekb/util": "14.7.0",
     "@nestjs/common": "^12.0.1",
     "arktype": "^2.2.0",
     "firebase": "^12.18.0",

package/route/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/dbx-cli/route",
-  "version": "14.6.0",
+  "version": "14.7.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "14.6.0",
-    "@dereekb/dbx-cli": "14.6.0",
-    "@dereekb/firebase": "14.6.0",
-    "@dereekb/model": "14.6.0",
-    "@dereekb/nestjs": "14.6.0",
-    "@dereekb/oauth-resource": "14.6.0",
-    "@dereekb/util": "14.6.0"
+    "@dereekb/date": "14.7.0",
+    "@dereekb/dbx-cli": "14.7.0",
+    "@dereekb/firebase": "14.7.0",
+    "@dereekb/model": "14.7.0",
+    "@dereekb/nestjs": "14.7.0",
+    "@dereekb/oauth-resource": "14.7.0",
+    "@dereekb/util": "14.7.0"
   },
   "exports": {
     "./package.json": "./package.json",

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

@@ -1,4 +1,4 @@
-import { type AsyncKeyedValueCache, type Maybe } from '@dereekb/util';
+import { type AsyncKeyedValueCache, type Maybe, type OidcTokenResponse } from '@dereekb/util';
 /**
  * A cached token entry for a single env.
  */
@@ -67,3 +67,34 @@ export declare function createCliTokenCacheStore(input: CreateCliTokenCacheStore
  * @returns `true` when the token is at or within `bufferMs` of expiry, otherwise `false`.
  */
 export declare function isTokenExpired(entry: Maybe<CliTokenEntry>, nowMs?: number, bufferMs?: number): boolean;
+/**
+ * Input for {@link mergeRefreshedTokenEntry}.
+ */
+export interface MergeRefreshedTokenEntryInput {
+    readonly entry: CliTokenEntry;
+    readonly refreshed: OidcTokenResponse;
+    /**
+     * The current time in unix epoch milliseconds, used to derive `expiresAt`. Defaults to `Date.now()`.
+     */
+    readonly nowMs?: number;
+}
+/**
+ * Folds an OIDC refresh response into the cached entry it was obtained with.
+ *
+ * EVERY refresh must persist the result of this merge. A refresh CONSUMES the supplied refresh
+ * token whenever the grant rotates, so keeping the old entry leaves the cache holding a spent
+ * credential and strands the session on the next refresh — with replay detection on the provider
+ * side, reusing the spent token can revoke the whole grant. Centralized so the refresh call sites
+ * (auth middleware, `auth check`, `doctor`) cannot drift apart on this.
+ *
+ * @param input - The entry that was refreshed and the token response it produced.
+ * @returns The updated entry to persist. Fields the provider omits fall back to the previous entry.
+ */
+export declare function mergeRefreshedTokenEntry(input: MergeRefreshedTokenEntryInput): CliTokenEntry;
+/**
+ * Whether a refresh response rotated the refresh token it was obtained with.
+ *
+ * @param input - The entry that was refreshed and the token response it produced.
+ * @returns `true` when the provider issued a DIFFERENT refresh token, meaning the old one is spent.
+ */
+export declare function didRotateRefreshToken(input: Pick<MergeRefreshedTokenEntryInput, 'entry' | 'refreshed'>): boolean;

package/src/lib/doctor/index.d.ts

@@ -1,3 +1,4 @@
 export * from './build-drift.check';
 export * from './doctor.command.factory';
 export * from './firestore-session.check';
+export * from './token-refresh.check';

package/src/lib/doctor/token-refresh.check.d.ts

@@ -0,0 +1,32 @@
+import { discoverOidcMetadata, refreshAccessToken } from '../auth/oidc.client';
+import { type CliTokenCacheStore } from '../config/token.cache';
+import { type DoctorCheck } from './doctor.command.factory';
+/**
+ * Name reported by the check {@link createTokenRefreshDoctorCheck} builds.
+ */
+export declare const TOKEN_REFRESH_DOCTOR_CHECK_NAME = "token-refresh-round-trip";
+/**
+ * Seams for {@link createTokenRefreshDoctorCheck}. Production omits all of them and gets the real
+ * OIDC client plus the on-disk token cache; tests substitute fakes so the check's PERSIST step can
+ * be asserted without a network or a home directory.
+ */
+export interface TokenRefreshDoctorCheckOverrides {
+    readonly tokenStoreForCli?: (cliName: string) => CliTokenCacheStore;
+    readonly discoverOidcMetadata?: typeof discoverOidcMetadata;
+    readonly refreshAccessToken?: typeof refreshAccessToken;
+}
+/**
+ * Builds the doctor check that proves the cached refresh token still works.
+ *
+ * The round-trip is a REAL refresh, so on a rotating grant it consumes the cached refresh token and
+ * the response must be written back — see `mergeRefreshedTokenEntry`. Discarding it (as this check
+ * once did) leaves the cache holding a spent credential: the very next refresh fails
+ * `invalid_grant`, and a provider doing replay detection revokes the whole grant. The symptom is
+ * maximally confusing because the session dies only AFTER the cached access token lapses, so the
+ * damage surfaces well away from the `doctor` run that caused it.
+ *
+ * @param overrides - Optional test seams; production passes none.
+ * @returns The {@link DoctorCheck}.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createTokenRefreshDoctorCheck(overrides?: TokenRefreshDoctorCheckOverrides): DoctorCheck;

package/src/lib/mcp-scan/manifest/load-utils-registry.d.ts

@@ -44,6 +44,15 @@ export interface LoadUtilRegistryResult {
     readonly loaderWarnings: readonly UtilLoaderWarning[];
     readonly externalSourceCount: number;
 }
+/**
+ * The bundled `@dereekb/*` utils manifests to load at startup. Must stay in step with the `utils.scan` entries in
+ * `dbx-mcp.config.json` — a generated manifest that is missing from this list is silently invisible to
+ * `dbx_util_lookup`/`dbx_util_search` no matter how well its exports are tagged.
+ *
+ * Loading is non-strict, so naming a file that a given workspace has not generated warns and skips rather than
+ * failing server startup.
+ */
+export declare const DEFAULT_BUNDLED_FILENAMES: readonly ["dereekb-util.utils.mcp.generated.json", "dereekb-util-fetch.utils.mcp.generated.json", "dereekb-date.utils.mcp.generated.json", "dereekb-rxjs.utils.mcp.generated.json", "dereekb-model.utils.mcp.generated.json", "dereekb-firebase.utils.mcp.generated.json", "dereekb-firebase-server.utils.mcp.generated.json"];
 /**
  * Loads the merged utils registry for the current MCP server.
  *

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

@@ -185,6 +185,32 @@ export declare function buildDumpFilePath(extension: 'json' | 'ndjson', suffix?:
  * @returns The filtered value (typed as the input).
  */
 export declare function pickFields<T>(data: T, pick: string): T;
+/**
+ * Applies the configured `--pick` filter to the document payload(s) carried by a command result.
+ *
+ * Returns `unknown` rather than `T` because picking REDUCES each payload — the reduced value is a
+ * partial view of the document and does not satisfy the result's own type.
+ *
+ * @param data - The full command result.
+ * @param pick - Reduces a document to the configured fields. Apply it to each payload, not the wrapper.
+ * @returns The result with its payload(s) reduced, wrapper fields intact.
+ */
+export type CliOutputPickApplier<T> = (data: T, pick: (value: unknown) => unknown) => unknown;
+/**
+ * Per-command output overrides for {@link outputResult}.
+ */
+export interface CliOutputResultOptions<T> {
+    /**
+     * Redirects the `--pick` filter into the result's document payload(s).
+     *
+     * Read commands wrap documents in an envelope (`{ key, data }`, `{ results, errors }`), so the
+     * default top-level pick can only ever match the wrapper's own keys — a pick naming real document
+     * fields silently yields `{}`, which is indistinguishable from an empty document. Supplied by the
+     * command because only it knows its envelope shape. Commands whose result *is* the payload
+     * (the common case) omit this and keep the top-level behavior.
+     */
+    readonly applyPick?: CliOutputPickApplier<T>;
+}
 /**
  * Prints a successful command result as a `{ ok: true, data, meta? }` JSON envelope on stdout.
  *
@@ -194,8 +220,9 @@ export declare function pickFields<T>(data: T, pick: string): T;
  *
  * @param data - The command result to emit.
  * @param meta - Optional additional metadata to attach to the envelope.
+ * @param options - Optional per-command overrides — see {@link CliOutputResultOptions}.
  */
-export declare function outputResult<T>(data: T, meta?: Record<string, unknown>): void;
+export declare function outputResult<T>(data: T, meta?: Record<string, unknown>, options?: CliOutputResultOptions<T>): void;
 /**
  * Prints a failed command result as a `{ ok: false, error, code, suggestion? }` JSON envelope on stdout.
  *

package/test/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@dereekb/dbx-cli/test",
-  "version": "14.6.0",
+  "version": "14.7.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "14.6.0",
-    "@dereekb/dbx-cli": "14.6.0",
-    "@dereekb/firebase": "14.6.0",
-    "@dereekb/firebase-server/test": "14.5.1",
-    "@dereekb/model": "14.6.0",
-    "@dereekb/nestjs": "14.6.0",
-    "@dereekb/oauth-resource": "14.6.0",
-    "@dereekb/rxjs": "14.6.0",
-    "@dereekb/util": "14.6.0",
+    "@dereekb/date": "14.7.0",
+    "@dereekb/dbx-cli": "14.7.0",
+    "@dereekb/firebase": "14.7.0",
+    "@dereekb/firebase-server/test": "14.6.0",
+    "@dereekb/model": "14.7.0",
+    "@dereekb/nestjs": "14.7.0",
+    "@dereekb/oauth-resource": "14.7.0",
+    "@dereekb/rxjs": "14.7.0",
+    "@dereekb/util": "14.7.0",
     "@nestjs/common": "^12.0.1",
     "arktype": "^2.2.0",
     "vitest": "4.1.11",

package/validate/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dereekb/dbx-cli/validate",
-  "version": "14.6.0",
+  "version": "14.7.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/dbx-cli": "14.6.0",
-    "@dereekb/util": "14.6.0",
+    "@dereekb/dbx-cli": "14.7.0",
+    "@dereekb/util": "14.7.0",
     "ts-morph": "^28.0.0"
   }
 }