@dereekb/dbx-cli 14.1.0 → 14.3.0

package/lint-cache/package.json

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

package/manifest-extract/index.esm.js

@@ -696,6 +696,10 @@ var MCP_TOOL_NAME_SEGMENT_TAG = 'dbxModelMcpToolNameSegment';
 var MODEL_TYPE_VALUE_PATTERN = /^[a-z][A-Za-z0-9_$]*$/;
 var TOOL_NAME_SEGMENT_PATTERN = /^[A-Za-z][A-Za-z0-9_$]*$/;
 var IDENTITY_FN = 'firestoreModelIdentity';
+// the declared-type counterparts of IDENTITY_FN, which is all a .d.ts retains of the call
+var IDENTITY_TYPE = 'FirestoreModelIdentity';
+var ROOT_IDENTITY_TYPE = 'RootFirestoreModelIdentity';
+var IDENTITY_WITH_PARENT_TYPE = 'FirestoreModelIdentityWithParent';
 var SINGLE_ITEM_COLLECTION_FN = 'singleItemFirestoreCollection';
 var ROOT_SINGLE_ITEM_COLLECTION_FN = 'rootSingleItemFirestoreCollection';
 var SINGLE_ITEM_COLLECTION_FN_NAMES = [
@@ -763,13 +767,25 @@ function readIdentities(sourceFile) {
                 for(var _iterator1 = statement.getDeclarations()[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
                     var decl = _step1.value;
                     var initializer = decl.getInitializer();
-                    if (!initializer || !Node.isCallExpression(initializer)) continue;
-                    if (initializer.getExpression().getText() !== IDENTITY_FN) continue;
-                    var parsed = parseFirestoreModelIdentityArgs(initializer.getArguments());
-                    if (parsed) {
-                        out.push(_object_spread({
-                            identityConst: decl.getName()
-                        }, parsed));
+                    if (initializer && Node.isCallExpression(initializer)) {
+                        if (initializer.getExpression().getText() !== IDENTITY_FN) continue;
+                        var parsed = parseFirestoreModelIdentityArgs(initializer.getArguments());
+                        if (parsed) {
+                            out.push(_object_spread_props(_object_spread({
+                                identityConst: decl.getName()
+                            }, parsed), {
+                                parentModelType: undefined
+                            }));
+                        }
+                    } else {
+                        // A declaration file has no initializer to read — the identity survives only in the declared
+                        // type, which is the whole reason a node_modules-installed package can contribute models at all.
+                        var parsed1 = parseDeclaredIdentityType(decl.getTypeNode());
+                        if (parsed1) {
+                            out.push(_object_spread({
+                                identityConst: decl.getName()
+                            }, parsed1));
+                        }
                     }
                 }
             } catch (err) {
@@ -803,6 +819,96 @@ function readIdentities(sourceFile) {
     }
     return out;
 }
+/**
+ * Reads an identity out of the DECLARED TYPE of an initializer-less export.
+ *
+ * The three shapes `@dereekb/firebase` declares, after a `.d.ts` rewrites every import as an inline
+ * `import("…").` qualifier:
+ *
+ * - `RootFirestoreModelIdentity<"worker", "wk">`
+ * - `FirestoreModelIdentity<"worker", "wk">`
+ * - `FirestoreModelIdentityWithParent<RootFirestoreModelIdentity<"prompt", "orp">, "version", "orpv">`
+ *
+ * @param typeNode - The declared type node, when the declaration carries one.
+ * @returns The identity parts, or undefined when the type is not one of the identity shapes.
+ */ function parseDeclaredIdentityType(typeNode) {
+    var result;
+    var named = readNamedTypeNode(typeNode);
+    if (named) {
+        var typeName = named.typeName, args = named.args;
+        if (typeName === IDENTITY_WITH_PARENT_TYPE && args.length >= 3) {
+            var _readLiteralTypeText;
+            var parent = parseDeclaredIdentityType(args[0]);
+            result = {
+                modelType: (_readLiteralTypeText = readLiteralTypeText(args[1])) !== null && _readLiteralTypeText !== void 0 ? _readLiteralTypeText : '',
+                collectionPrefix: readLiteralTypeText(args[2]),
+                parentIdentityConst: undefined,
+                parentModelType: parent === null || parent === void 0 ? void 0 : parent.modelType
+            };
+        } else if ((typeName === ROOT_IDENTITY_TYPE || typeName === IDENTITY_TYPE) && args.length >= 2) {
+            var _readLiteralTypeText1;
+            result = {
+                modelType: (_readLiteralTypeText1 = readLiteralTypeText(args[0])) !== null && _readLiteralTypeText1 !== void 0 ? _readLiteralTypeText1 : '',
+                collectionPrefix: readLiteralTypeText(args[1]),
+                parentIdentityConst: undefined,
+                parentModelType: undefined
+            };
+        }
+        // a default-parameterized identity carries no literals, so it names no model
+        if (result && !result.modelType) {
+            result = undefined;
+        }
+    }
+    return result;
+}
+/**
+ * Normalizes a type node to its name and type arguments.
+ *
+ * Two shapes, because a `.d.ts` does not write the one the source did: source that imported the type
+ * normally leaves a `TypeReference` (`RootFirestoreModelIdentity<…>`), while a declaration file inlines
+ * the import and leaves an `ImportType` (`import("@dereekb/firebase").RootFirestoreModelIdentity<…>`),
+ * whose name is its QUALIFIER rather than its type name. Reading only the first is what made a
+ * declaration-sourced identity invisible.
+ *
+ * @param typeNode - The type node to read.
+ * @returns The unqualified type name and its type arguments, or undefined when the node is neither shape.
+ */ function readNamedTypeNode(typeNode) {
+    var result;
+    if (typeNode) {
+        if (Node.isImportTypeNode(typeNode)) {
+            var qualifier = typeNode.getQualifier();
+            if (qualifier) {
+                var _qualifier_getText_split_pop;
+                result = {
+                    typeName: (_qualifier_getText_split_pop = qualifier.getText().split('.').pop()) !== null && _qualifier_getText_split_pop !== void 0 ? _qualifier_getText_split_pop : '',
+                    args: typeNode.getTypeArguments()
+                };
+            }
+        } else if (Node.isTypeReference(typeNode)) {
+            var _typeNode_getTypeName_getText_split_pop;
+            result = {
+                typeName: (_typeNode_getTypeName_getText_split_pop = typeNode.getTypeName().getText().split('.').pop()) !== null && _typeNode_getTypeName_getText_split_pop !== void 0 ? _typeNode_getTypeName_getText_split_pop : '',
+                args: typeNode.getTypeArguments()
+            };
+        }
+    }
+    return result;
+}
+/**
+ * Reads the text of a string-literal type node (`"wk"` → `wk`).
+ *
+ * @param node - The type node to read.
+ * @returns The literal's text, or undefined when the node is not a string literal type.
+ */ function readLiteralTypeText(node) {
+    var result;
+    if (node && Node.isLiteralTypeNode(node)) {
+        var literal = node.getLiteral();
+        if (Node.isStringLiteral(literal)) {
+            result = literal.getLiteralText();
+        }
+    }
+    return result;
+}
 function readInterfaces(sourceFile) {
     var out = [];
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;

package/manifest-extract/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/dbx-cli/manifest-extract",
-  "version": "14.1.0",
+  "version": "14.3.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "14.1.0",
-    "@dereekb/dbx-cli": "14.1.0",
-    "@dereekb/firebase": "14.1.0",
-    "@dereekb/model": "14.1.0",
-    "@dereekb/nestjs": "14.1.0",
-    "@dereekb/rxjs": "14.1.0",
-    "@dereekb/util": "14.1.0",
+    "@dereekb/date": "14.3.0",
+    "@dereekb/dbx-cli": "14.3.0",
+    "@dereekb/firebase": "14.3.0",
+    "@dereekb/model": "14.3.0",
+    "@dereekb/nestjs": "14.3.0",
+    "@dereekb/rxjs": "14.3.0",
+    "@dereekb/util": "14.3.0",
     "ts-morph": "^28.0.0"
   },
   "exports": {

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

@@ -119,6 +119,16 @@ export interface ModelExtractionIdentity {
     readonly modelType: string;
     readonly collectionPrefix: string | undefined;
     readonly parentIdentityConst: string | undefined;
+    /**
+     * Model type of the parent, when the identity was read from a DECLARATION rather than a call.
+     *
+     * A `.d.ts` spells the parent as an inline type (`FirestoreModelIdentityWithParent<
+     * RootFirestoreModelIdentity<"openRouterPrompt", "orp">, …>`) rather than by naming the const the
+     * source called `firestoreModelIdentity` with, so the const name the parent chain is walked by is not
+     * present to read. The model type is, and it identifies the same parent — the orchestrator resolves
+     * one to the other against the global identity registry.
+     */
+    readonly parentModelType: string | undefined;
 }
 /**
  * One property on a `@dbxModel`-tagged interface.

package/model-test/package.json

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

package/package.json

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

package/route/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/dbx-cli/route",
-  "version": "14.1.0",
+  "version": "14.3.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "14.1.0",
-    "@dereekb/dbx-cli": "14.1.0",
-    "@dereekb/firebase": "14.1.0",
-    "@dereekb/model": "14.1.0",
-    "@dereekb/nestjs": "14.1.0",
-    "@dereekb/util": "14.1.0"
+    "@dereekb/date": "14.3.0",
+    "@dereekb/dbx-cli": "14.3.0",
+    "@dereekb/firebase": "14.3.0",
+    "@dereekb/model": "14.3.0",
+    "@dereekb/nestjs": "14.3.0",
+    "@dereekb/util": "14.3.0"
   },
   "exports": {
     "./package.json": "./package.json",

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

@@ -1,3 +1,4 @@
 export * from './auth.command.factory';
 export * from './oidc.client';
 export * from './oidc.flow';
+export * from './oidc.loopback';

package/src/lib/auth/oidc.loopback.d.ts

@@ -0,0 +1,127 @@
+import { type Maybe, type PortNumber, type WebsiteUrl } from '@dereekb/util';
+/**
+ * Hostnames RFC 8252 §7.3 treats as the loopback interface, and the exact set `oidc-provider`
+ * recognizes as a loopback redirect host.
+ *
+ * `[::1]` carries its brackets because that is what `URL.hostname` returns for an IPv6 literal —
+ * the brackets are stripped again before the address is handed to `server.listen`.
+ */
+export declare const LOOPBACK_REDIRECT_HOSTNAMES: readonly string[];
+/**
+ * The loopback port the CLI suggests when the configured redirect URI has no bindable port.
+ *
+ * Deliberately outside the 9900-9910 block the Firebase emulators occupy, so a suggested redirect
+ * URI never collides with a running emulator.
+ */
+export declare const SUGGESTED_CLI_LOOPBACK_REDIRECT_PORT: PortNumber;
+/**
+ * Error code raised when the loopback listener cannot bind the redirect URI's port (e.g. the port
+ * is already in use, or is privileged).
+ */
+export declare const LOOPBACK_REDIRECT_LISTEN_FAILED_ERROR_CODE = "AUTH_REDIRECT_LISTEN_FAILED";
+/**
+ * Error code raised when no redirect reached the loopback listener within the allotted time.
+ */
+export declare const LOOPBACK_REDIRECT_TIMEOUT_ERROR_CODE = "AUTH_REDIRECT_TIMEOUT";
+/**
+ * A redirect URI the CLI can bind a local HTTP listener to, decomposed into its parts.
+ */
+export interface LoopbackRedirectTarget {
+    /**
+     * The normalized redirect URI to send as `redirect_uri`. Identical to the configured URI unless a
+     * port override was applied.
+     */
+    readonly redirectUri: WebsiteUrl;
+    /**
+     * The loopback hostname, as `URL.hostname` reports it (so `[::1]` keeps its brackets).
+     */
+    readonly hostname: string;
+    /**
+     * The port to bind. Always a positive integer — a `0`/absent port is not a capturable target.
+     */
+    readonly port: PortNumber;
+    /**
+     * The path the provider redirects to. Requests to any other path are answered `404` so a stray
+     * `/favicon.ico` cannot be mistaken for the authorization redirect.
+     */
+    readonly pathname: string;
+}
+export interface ParseLoopbackRedirectUriInput {
+    /**
+     * The configured redirect URI.
+     */
+    readonly redirectUri: Maybe<string>;
+    /**
+     * Optional port override, replacing whatever port the redirect URI carries.
+     *
+     * The resulting URI is what gets sent as `redirect_uri`, so it must be registered with the OAuth
+     * client just like the configured one.
+     */
+    readonly port?: Maybe<PortNumber>;
+}
+/**
+ * Decomposes a redirect URI into a {@link LoopbackRedirectTarget} when the CLI can bind a local
+ * listener for it.
+ *
+ * A target is only produced for an `http:` loopback URI carrying a concrete, non-zero port. The
+ * conventional `http://127.0.0.1:0/callback` placeholder is deliberately NOT capturable: binding an
+ * ephemeral port would mean sending a `redirect_uri` that differs from the registered one, which
+ * every OAuth provider rejects unless the client is registered as a native app (where loopback
+ * ports are compared port-insensitively).
+ *
+ * @param input - The parse inputs.
+ * @param input.redirectUri - The configured redirect URI.
+ * @param input.port - Optional port override applied to the parsed URI.
+ * @returns The bindable target, or `undefined` when the URI cannot be captured locally.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function parseLoopbackRedirectUri(input: ParseLoopbackRedirectUriInput): Maybe<LoopbackRedirectTarget>;
+export interface StartLoopbackRedirectCaptureInput {
+    /**
+     * The bindable target, from {@link parseLoopbackRedirectUri}.
+     */
+    readonly target: LoopbackRedirectTarget;
+    /**
+     * Text shown in the browser tab once the redirect is captured.
+     */
+    readonly successMessage?: Maybe<string>;
+}
+export interface LoopbackRedirectCapture {
+    /**
+     * The `redirect_uri` the listener is bound to. Send this value in the authorization request.
+     */
+    readonly redirectUri: WebsiteUrl;
+    /**
+     * The bound port.
+     */
+    readonly port: PortNumber;
+    /**
+     * Resolves with the full redirect URL (query string included) the browser was sent to.
+     *
+     * A provider error redirect resolves rather than rejects — the returned URL carries the `error`
+     * params, which the shared redirect parser already turns into an `AUTH_PROVIDER_ERROR`.
+     *
+     * @param timeoutMs - Optional milliseconds to wait before rejecting with
+     *   {@link LOOPBACK_REDIRECT_TIMEOUT_ERROR_CODE}. Waits indefinitely when omitted.
+     */
+    readonly waitForRedirect: (timeoutMs?: Maybe<number>) => Promise<WebsiteUrl>;
+    /**
+     * Closes the listener and destroys any open sockets, so the CLI's event loop can drain.
+     */
+    readonly close: () => Promise<void>;
+}
+/**
+ * Binds a local HTTP listener to a loopback redirect URI so the authorization code can be read
+ * straight out of the browser redirect instead of being pasted back by hand.
+ *
+ * The listener answers exactly one path — the redirect URI's own — and serves a short "you can close
+ * this tab" page. Everything else is answered `404`, which is what keeps the browser's automatic
+ * `/favicon.ico` request from being mistaken for the redirect.
+ *
+ * @param input - The capture inputs.
+ * @param input.target - The bindable target, from {@link parseLoopbackRedirectUri}.
+ * @param input.successMessage - Optional override for the browser success page's body line.
+ * @returns The started {@link LoopbackRedirectCapture}.
+ * @throws {CliError} `AUTH_REDIRECT_LISTEN_FAILED` when the port cannot be bound.
+ */
+export declare function startLoopbackRedirectCapture(input: StartLoopbackRedirectCaptureInput): Promise<LoopbackRedirectCapture>;

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

@@ -0,0 +1,44 @@
+import { type Maybe } from '@dereekb/util';
+import type { CommandModule } from 'yargs';
+import { type CliDataCache } from './data-cache';
+/**
+ * Default command name for the data-cache management command.
+ */
+export declare const DEFAULT_CLI_DATA_CACHE_COMMAND_NAME = "cache";
+export interface CreateCacheCommandInput {
+    readonly cliName: string;
+    /**
+     * Override for the cache the command manages. Defaults to the CLI's own
+     * `<configDir>/cache` directory.
+     */
+    readonly cache?: Maybe<CliDataCache>;
+    /**
+     * The current CLI build stamp. When supplied, `cache list` marks entries recorded by a different
+     * build, which is the one staleness signal the fingerprint deliberately does not cover.
+     */
+    readonly cliBuildStamp?: Maybe<string>;
+    readonly commandName?: string;
+}
+/**
+ * Factory for the `cache` command.
+ *
+ * Registered as a CONFIG command, not an API command: inspecting or clearing a LOCAL cache must work
+ * offline and without a token — which is precisely the situation in which a cache matters. Mirrors
+ * the `firestore-queries` (config) vs `firestore-query` (api) split.
+ *
+ * Subcommands:
+ * - `cache list [--env <env>] [--dataset <id>] [--json]`
+ * - `cache show <dataset> [--env <env>] [--fingerprint <fp>] [--data]`
+ * - `cache clear [--env <env>] [--dataset <id>] [--all]`
+ * - `cache prune --older-than <hours> [--env <env>] [--dataset <id>]`
+ *
+ * @param input - Factory configuration.
+ * @param input.cliName - The CLI's binary name, used to derive the default cache directory.
+ * @param input.cache - Optional cache override (tests point this at a temp dir).
+ * @param input.cliBuildStamp - The current build stamp, for marking entries from another build.
+ * @param input.commandName - Optional command-name override.
+ * @returns A yargs `CommandModule` for `runCli({ configCommands })`.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createCacheCommand(input: CreateCacheCommandInput): CommandModule;

package/src/lib/cache/data-cache.codec.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Error code thrown when a value handed to {@link toCliCacheJson} contains a reference cycle.
+ */
+export declare const CLI_DATA_CACHE_CYCLE_ERROR_CODE = "CLI_DATA_CACHE_CYCLE";
+/**
+ * Error code thrown when a value handed to {@link toCliCacheJson} holds something that cannot be
+ * persisted and re-read at all — a function or a symbol.
+ */
+export declare const CLI_DATA_CACHE_UNSUPPORTED_VALUE_ERROR_CODE = "CLI_DATA_CACHE_UNSUPPORTED_VALUE";
+/**
+ * Converts a value into a JSON-safe tree, tagging the types a plain `JSON.stringify` round trip
+ * would lose.
+ *
+ * This is a PRE-WALK rather than a `JSON.stringify` replacer, and that is load-bearing:
+ * `Date.prototype.toJSON` runs BEFORE a replacer sees the value, so a replacer is handed an ISO
+ * string and cannot tell a `Date` from a string that merely looks like one. Every model in a
+ * dbx-components app persists its dates through `firestoreDate` (an ISO string on the wire, a live
+ * `Date` in memory), so that distinction is the whole problem.
+ *
+ * Handled: `Date`, `Map`, `Set`, `undefined`, non-finite numbers, `bigint`, arrays, plain objects,
+ * and the JSON primitives. A class instance that is none of the above is FLATTENED to its own
+ * enumerable properties — the one lossy case, and the reason a stage whose output holds a class
+ * instance must supply its own codec.
+ *
+ * @param value - The value to encode.
+ * @returns A tree containing only values `JSON.stringify` renders losslessly.
+ * @throws {CliError} On a reference cycle, or on a function/symbol anywhere in the tree.
+ */
+export declare function toCliCacheJson(value: unknown): unknown;
+/**
+ * Rebuilds a value encoded by {@link toCliCacheJson}, restoring the tagged types.
+ *
+ * @param raw - The JSON-parsed tree written by {@link toCliCacheJson}.
+ * @returns The decoded value.
+ */
+export declare function fromCliCacheJson(raw: unknown): unknown;