@dereekb/dbx-cli 13.37.0 → 13.39.0

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

@@ -1,6 +1,7 @@
 import type { MiddlewareFunction } from 'yargs';
 import { type CliEnvDefault } from '../config/env';
 import { type CliContext } from '../context/cli.context';
+import { type CliFirestoreBinding } from '../firestore/firestore.models';
 import { type CliModelManifest } from '../manifest/types';
 export interface CreateAuthMiddlewareInput {
     readonly cliName: string;
@@ -19,6 +20,11 @@ export interface CreateAuthMiddlewareInput {
      * can resolve `prefix/id` keys to a `modelType` via `decodeFirestoreModelKey`.
      */
     readonly modelManifest?: CliModelManifest;
+    /**
+     * The app-supplied direct-Firestore binding. When present, the attached {@link CliContext}
+     * exposes `getFirestoreModels()`.
+     */
+    readonly firestore?: CliFirestoreBinding;
 }
 /**
  * Yargs middleware that resolves the active env, loads/refreshes its access token, and attaches

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

@@ -3,7 +3,8 @@ import { type ActionCommandSpec } from '../action/action.command.factory';
 import { type CliEnvDefault } from '../config/env';
 import { type CliContext } from '../context/cli.context';
 import { type DoctorCheck } from '../doctor/doctor.command.factory';
-import { type CliModelManifest } from '../manifest/types';
+import { type CliFirestoreQueryManifest, type CliModelManifest } from '../manifest/types';
+import { type CliFirestoreBinding } from '../firestore/firestore.models';
 /**
  * Names of the global options registered by {@link createCli} that are not
  * specific to a single manifest command's payload. Manifest commands hide
@@ -101,6 +102,30 @@ export interface CreateCliInput {
      * not want to surface the key-decode command itself.
      */
     readonly disableModelDecode?: boolean;
+    /**
+     * The app-supplied direct-Firestore binding — `cliFirestoreBinding({ collections, models })`.
+     *
+     * `dbx-cli` cannot import an app's collections factory, so this one option is what makes the
+     * generic `firestore-get` / `firestore-query` commands possible at all. Supplying it wires them
+     * for EVERY registered model at once.
+     */
+    readonly firestore?: CliFirestoreBinding;
+    /**
+     * The generated Firestore query catalog (`<NS>_FIRESTORE_QUERY_MANIFEST`).
+     *
+     * Enables the auth-bypassed `firestore-queries` catalog command on its own, and — paired with
+     * {@link firestore} — the `firestore-query` execution command.
+     */
+    readonly firestoreQueryManifest?: CliFirestoreQueryManifest;
+    /**
+     * Disable the built-in `firestore-query` command even when {@link firestore} and
+     * {@link firestoreQueryManifest} are both provided.
+     */
+    readonly disableFirestoreQuery?: boolean;
+    /**
+     * Disable the built-in `firestore-get` command even when {@link firestore} is provided.
+     */
+    readonly disableFirestoreGet?: boolean;
     /**
      * Test-only override that bypasses the auth middleware entirely and attaches the supplied
      * {@link CliContext} on every command invocation.
@@ -150,6 +175,8 @@ export interface CreateCliInput {
  *   built-in `model-info` command. Opt-in per app.
  * @param input.disableModelInfo - When `true`, suppresses the auto-wired `model-info` command even
  *   if {@link CreateCliInput.modelManifest} is provided.
+ * @param input.firestore - The app-supplied direct-Firestore binding; enables `firestore-get` / `firestore-query`.
+ * @param input.firestoreQueryManifest - The generated Firestore query catalog; enables `firestore-queries`.
  * @returns The configured yargs `Argv` ready to be `.parse()`-d.
  * @__NO_SIDE_EFFECTS__
  */

package/src/lib/scan-helpers/emit-generated-ts.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared emission primitives for the build-time manifest generators.
+ *
+ * Every generator ends the same way: group the runtime imports it needs by
+ * package, render a banner + module source, format it with the workspace
+ * prettier config so the output matches a `prettier --write` of the committed
+ * file, then skip the write when the bytes are unchanged so incremental builds
+ * see a preserved mtime. That tail lives here once instead of being copied
+ * into each `<generator>/src/emit.ts`.
+ */
+/**
+ * One named runtime import a generated module needs.
+ */
+export interface GeneratedTsImport {
+    /**
+     * Module specifier to import from — typically a package name.
+     */
+    readonly packageName: string;
+    /**
+     * Identifier to import.
+     */
+    readonly identifier: string;
+}
+/**
+ * Result of {@link writeGeneratedTsFile}.
+ *
+ * `unchanged` means the file already held byte-identical content and was left
+ * untouched, preserving its mtime.
+ */
+export type WriteGeneratedTsFileOutcome = 'wrote' | 'unchanged';
+/**
+ * Inputs for {@link writeGeneratedTsFile}.
+ */
+export interface WriteGeneratedTsFileInput {
+    /**
+     * Absolute path of the file to write.
+     */
+    readonly outputFile: string;
+    /**
+     * Full file contents.
+     */
+    readonly contents: string;
+}
+/**
+ * Groups named imports by their module specifier and renders one
+ * `import { … } from '…';` line per package, packages sorted by specifier and
+ * identifiers sorted within each line.
+ *
+ * @param imports - Every identifier the generated module references, with the package it comes from.
+ * @returns One import line per distinct package, in specifier order.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function renderGroupedImportLines(imports: readonly GeneratedTsImport[]): string[];
+/**
+ * Formats generated TypeScript source with the workspace prettier config
+ * resolved for `outputFile`, so the emitted bytes match what
+ * `prettier --write` would produce on the committed file.
+ *
+ * @param source - The unformatted module source.
+ * @param outputFile - Path the source will be written to; selects the prettier config and parser.
+ * @returns The formatted source.
+ */
+export declare function formatGeneratedTs(source: string, outputFile: string): Promise<string>;
+/**
+ * Writes generated content to disk, creating the containing directory when
+ * missing and skipping the write entirely when the existing file is
+ * byte-identical.
+ *
+ * Skipping matters for incremental builds: rewriting identical bytes would
+ * bump the mtime and invalidate every downstream target.
+ *
+ * @param input - Output path and full contents.
+ * @returns `'unchanged'` when the write was skipped, `'wrote'` otherwise.
+ */
+export declare function writeGeneratedTsFile(input: WriteGeneratedTsFileInput): WriteGeneratedTsFileOutcome;

package/src/lib/scan-helpers/exported-from-package.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Confirms an identifier is exported from a source package's barrel chain.
+ *
+ * Verification is deliberately textual rather than a full ts-morph resolve:
+ * the generators call this once per candidate identifier across whole
+ * packages, and the only question that matters is "would `import { X } from
+ * '<pkg>'` resolve". We string-search the package's `src/index.ts` and follow
+ * `export * from './...';` re-exports recursively until the declaration turns
+ * up, falling back to declaration barrels so installed `@dereekb/*` packages
+ * in `node_modules` resolve the same way.
+ */
+/**
+ * Inputs for {@link isExportedFromPackage}.
+ */
+export interface IsExportedInput {
+    readonly packageRoot: string;
+    readonly identifier: string;
+}
+/**
+ * Confirms an identifier is exported from a package's barrel —
+ * directly or via re-export chains. Tries the source barrel
+ * (`packageRoot/src/index.ts`) first, then falls back to declaration
+ * barrels (`src/index.d.ts`, `index.d.ts`) so installed `@dereekb/*`
+ * packages in `node_modules` resolve the same way.
+ *
+ * @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;

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

@@ -5,3 +5,4 @@ export * from './interactive';
 export * from './output';
 export * from './pagination';
 export * from './stdin';
+export * from './table';

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

@@ -142,6 +142,16 @@ export declare function configureCliSecretPatterns(patterns: CliSecretPattern[])
  * @param mapper - The mapper to install, or `undefined` to clear any previously registered mapper.
  */
 export declare function configureCliErrorMapper(mapper?: CliErrorMapper): void;
+/**
+ * Chains an additional {@link CliErrorMapper} BEHIND any already-registered one.
+ *
+ * Only one mapper slot exists, and an app may already own it (see `@dereekb/zoho/cli`). A built-in
+ * that wants to map its own error family therefore appends rather than installing, so the app's
+ * mapper keeps first refusal and the built-in only sees what the app declined.
+ *
+ * @param mapper - The mapper to consult after the current one defers.
+ */
+export declare function appendCliErrorMapper(mapper: CliErrorMapper): void;
 /**
  * Applies the configured secret-redaction patterns to a string, replacing each match with `[REDACTED]`.
  *

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

@@ -1,13 +1,46 @@
+/**
+ * Error code thrown by {@link readAllStdin} when `-` was passed but stdin is an interactive
+ * terminal, so no piped input will ever arrive.
+ */
+export declare const STDIN_NOT_PIPED_ERROR_CODE = "STDIN_NOT_PIPED";
+/**
+ * Records the raw argv the parser was handed so {@link isStdinPositionalSentinel} can distinguish a
+ * user-typed `-` from an ordinary empty positional.
+ *
+ * Called by `createCli` with the same argv it passes to yargs, which keeps the behaviour identical
+ * under the `CreateCliInput.argv` test override as it is in production.
+ *
+ * @param argv - The argv the parser was constructed with.
+ */
+export declare function setCliRawArgv(argv: readonly string[]): void;
 /**
  * Returns `true` when the user passed `-` (the conventional "read from stdin" sentinel) as a
- * positional or flag value. Centralizes the convention so command handlers can pattern-match
- * consistently.
+ * flag value. Centralizes the convention so command handlers can pattern-match consistently.
+ *
+ * Only reliable for flag values, and only when the option declares `.nargs(<name>, 1)` — without it
+ * yargs treats the `-` in `--data -` as the next option rather than the flag's value, and the flag
+ * parses as boolean `true`. Positionals cannot be expressed this way; use
+ * {@link isStdinPositionalSentinel} for those.
  *
  * @param value - The raw argv value to inspect.
  * @returns `true` when the value is exactly `'-'`.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function isStdinSentinel(value: unknown): boolean;
+/**
+ * Returns `true` when a *positional* carried the `-` stdin sentinel.
+ *
+ * yargs cannot surface a lone `-` positional intact: with `type: 'string'` it coerces to `''`, and
+ * with no type at all to `true` — the raw `-` survives only in yargs-parser's `_`, which the
+ * positional mapping has already consumed by the time a handler runs. So an empty positional is
+ * treated as the sentinel only when the argv actually contained a bare `-`, which keeps a genuinely
+ * empty argument from being mistaken for a request to read stdin.
+ *
+ * @param value - The parsed positional value to inspect.
+ * @returns `true` when the positional was the stdin sentinel.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isStdinPositionalSentinel(value: unknown): boolean;
 /**
  * Reads the entire contents of `process.stdin` as a UTF-8 string.
  *
@@ -15,7 +48,11 @@ export declare function isStdinSentinel(value: unknown): boolean;
  * `get-many -`). Resolves once the stream emits `end`; no timeout is applied — callers that
  * need one should wrap with `Promise.race`.
  *
+ * Throws when stdin is an interactive terminal: nothing is piped in, so the read would block
+ * forever and the CLI would appear to hang rather than report a usage mistake.
+ *
  * @returns The UTF-8 decoded stdin contents.
+ * @throws {CliError} When stdin is a TTY, with `code: 'STDIN_NOT_PIPED'`.
  */
 export declare function readAllStdin(): Promise<string>;
 /**

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

@@ -0,0 +1,40 @@
+/**
+ * Plain-text table and indentation helpers shared by the CLI's human-readable
+ * renderers (`model-info`, `firestore-queries`, ...).
+ *
+ * These started life private to `manifest/model-info-utils.ts`; every catalog
+ * command renders the same column-aligned shape, so they live here once.
+ */
+/**
+ * Renders rows as a column-aligned, two-space-separated table.
+ *
+ * Every column except the last is padded to the widest cell in that column,
+ * and trailing whitespace is stripped from each line.
+ *
+ * @param rows - The rows to render, each an ordered list of cell texts.
+ * @returns The formatted table with no trailing newline, or `''` when empty.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function renderTable(rows: readonly (readonly string[])[]): string;
+/**
+ * Truncates `text` to at most `max` characters, replacing the final character
+ * with an ellipsis when a cut is made.
+ *
+ * @param text - The text to truncate.
+ * @param max - The maximum length of the result.
+ * @returns The original text, or a truncated copy ending in `…`.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function truncate(text: string, max: number): string;
+/**
+ * Indents every non-empty line of `text` by `indent` spaces.
+ *
+ * @param text - The text to indent.
+ * @param indent - The number of spaces to prefix. Values `<= 0` are a no-op.
+ * @returns The indented text.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function indentLines(text: string, indent: number): string;

package/test/index.esm.js

@@ -172,7 +172,7 @@ function _ts_generator(thisArg, body) {
  * Thin wrapper around {@link createCliContext} that exists so test code can import from a single
  * test-only entry without pulling in production-only types.
  *
- * @param input - The context inputs (cliName, envName, env, accessToken, optional modelManifest).
+ * @param input - The context inputs (cliName, envName, env, accessToken, optional modelManifest / firestore binding / session cache).
  * @returns The constructed {@link CliContext} that drives `callModel` / `getModel` / `getMultipleModels`
  *   against `input.env.apiBaseUrl` with `input.accessToken` as the Bearer token.
  * @__NO_SIDE_EFFECTS__
@@ -182,7 +182,9 @@ function _ts_generator(thisArg, body) {
         envName: input.envName,
         env: input.env,
         accessToken: input.accessToken,
-        modelManifest: input.modelManifest
+        modelManifest: input.modelManifest,
+        firestore: input.firestore,
+        firestoreSessionCache: input.firestoreSessionCache
     });
 }
 /**

package/test/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@dereekb/dbx-cli/test",
-  "version": "13.37.0",
+  "version": "13.39.0",
+  "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "13.37.0",
-    "@dereekb/dbx-cli": "13.37.0",
-    "@dereekb/firebase": "13.37.0",
-    "@dereekb/firebase-server/test": "13.37.0",
-    "@dereekb/model": "13.37.0",
-    "@dereekb/nestjs": "13.37.0",
-    "@dereekb/rxjs": "13.37.0",
-    "@dereekb/util": "13.37.0",
+    "@dereekb/date": "13.39.0",
+    "@dereekb/dbx-cli": "13.39.0",
+    "@dereekb/firebase": "13.39.0",
+    "@dereekb/firebase-server/test": "13.39.0",
+    "@dereekb/model": "13.39.0",
+    "@dereekb/nestjs": "13.39.0",
+    "@dereekb/rxjs": "13.39.0",
+    "@dereekb/util": "13.39.0",
     "@nestjs/common": "^11.1.19",
     "arktype": "^2.2.0",
     "vitest": "4.1.5",
@@ -18,13 +19,12 @@
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "module": "./index.esm.js",
       "types": "./index.d.ts",
-      "import": "./index.cjs.mjs",
-      "default": "./index.cjs.js"
+      "import": "./index.esm.js",
+      "default": "./index.esm.js"
     }
   },
   "module": "./index.esm.js",
-  "main": "./index.cjs.js",
+  "main": "./index.esm.js",
   "types": "./index.d.ts"
-}
+}

package/test/src/lib/cli-test.d.ts

@@ -1,5 +1,5 @@
 import { type INestApplication } from '@nestjs/common';
-import { type CliContext, type CliEnvConfig, type CliModelManifest, type CreateCliInput } from '@dereekb/dbx-cli';
+import { type CliContext, type CliEnvConfig, type CliFirestoreBinding, type CliFirestoreSessionCacheStore, type CliModelManifest, type CreateCliInput } from '@dereekb/dbx-cli';
 /**
  * Input for {@link buildTestCliContext}.
  */
@@ -9,6 +9,16 @@ export interface BuildTestCliContextInput {
     readonly env: CliEnvConfig;
     readonly accessToken: string;
     readonly modelManifest?: CliModelManifest;
+    /**
+     * The app-supplied direct-Firestore binding. Supply it when the test drives `firestore-get` /
+     * `firestore-query`, which reach for `context.getFirestoreModels()`.
+     */
+    readonly firestore?: CliFirestoreBinding;
+    /**
+     * Optional on-disk direct-Firestore session cache. Point it at a temp dir when a test wants the
+     * cross-invocation caching behaviour.
+     */
+    readonly firestoreSessionCache?: CliFirestoreSessionCacheStore;
 }
 /**
  * Builds a {@link CliContext} for use as `testCliContext` on {@link createCli}.
@@ -16,7 +26,7 @@ export interface BuildTestCliContextInput {
  * Thin wrapper around {@link createCliContext} that exists so test code can import from a single
  * test-only entry without pulling in production-only types.
  *
- * @param input - The context inputs (cliName, envName, env, accessToken, optional modelManifest).
+ * @param input - The context inputs (cliName, envName, env, accessToken, optional modelManifest / firestore binding / session cache).
  * @returns The constructed {@link CliContext} that drives `callModel` / `getModel` / `getMultipleModels`
  *   against `input.env.apiBaseUrl` with `input.accessToken` as the Bearer token.
  * @__NO_SIDE_EFFECTS__

package/validate/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hapier Creative LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.