@dereekb/dbx-cli 13.11.10 → 13.11.12

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

@@ -1,5 +1,7 @@
 import { type Argv, type CommandModule } from 'yargs';
+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';
 /**
@@ -26,6 +28,18 @@ export interface CreateCliInput {
      * it returns a single parent `model <model>` command so the top-level `--help` stays focused.
      */
     readonly apiCommands?: CommandModule[];
+    /**
+     * App-defined composite actions surfaced under `<cli> action <action>` (root) or
+     * `<cli> action <model> <action>` (model-scoped).
+     *
+     * Each action runs after the auth middleware so the handler receives the live
+     * {@link CliContext}. Use for high-leverage workflows that chain multiple
+     * `callModel` / `getModel` / `getMultipleModels` calls in-process so the caller
+     * does not pay one CLI round-trip per call.
+     *
+     * When omitted or empty, no `action` parent command is registered.
+     */
+    readonly actionCommands?: readonly ActionCommandSpec[];
     /**
      * Extra checks appended to the doctor's default check list.
      */
@@ -87,6 +101,33 @@ export interface CreateCliInput {
      * not want to surface the key-decode command itself.
      */
     readonly disableModelDecode?: boolean;
+    /**
+     * Test-only override that bypasses the auth middleware entirely and attaches the supplied
+     * {@link CliContext} on every command invocation.
+     *
+     * When set, the default auth middleware (OIDC discovery, disk token load, refresh, `process.exit`
+     * on failure) is replaced with a passthrough that just calls `setCliContext(testCliContext)`. The
+     * output middleware still runs.
+     *
+     * @internal Intended for use from `@dereekb/dbx-cli/test`. Not for production wiring.
+     */
+    readonly testCliContext?: CliContext;
+    /**
+     * Optional version string. When set, yargs registers `--version` / `-V` on the root parser
+     * returning this value. Defaults to omitted (no `--version` flag).
+     *
+     * Consumers typically pass their `package.json` version (read at build time, e.g. via a
+     * bundler `define` or a generated module).
+     */
+    readonly version?: string;
+    /**
+     * Optional shell-completion command name. When set, yargs registers
+     * `<cli> <completionCommandName>` (defaults to `completion`) that emits a bash/zsh script.
+     * Pass `false` to disable.
+     *
+     * @default 'completion'
+     */
+    readonly completionCommandName?: string | false;
 }
 /**
  * Top-level CLI builder.

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

@@ -2,12 +2,28 @@ import type { Arguments } from 'yargs';
 /**
  * Wraps a yargs command handler with the standard structured-error boilerplate:
  * any thrown error is converted to a `{ ok: false, ... }` envelope via {@link outputError}
- * and the process exits with code 1.
+ * and the process exits with the supplied code (default {@link CLI_EXIT_CODE_HANDLER} = 1).
  *
  * Lets command files drop the per-handler `try { ... } catch (e) { outputError(e); process.exit(1); }`
  * block while keeping the same observable behavior.
  *
  * @param handler - The inner command handler to invoke. May be sync or async.
+ * @param exitCode - Optional override for the exit code on failure (defaults to {@link CLI_EXIT_CODE_HANDLER}).
  * @returns An async handler that delegates to `handler` and converts thrown errors into the standard envelope.
  */
-export declare function wrapCommandHandler<T>(handler: (argv: Arguments<T>) => Promise<void> | void): (argv: Arguments<T>) => Promise<void>;
+export declare function wrapCommandHandler<T>(handler: (argv: Arguments<T>) => Promise<void> | void, exitCode?: number): (argv: Arguments<T>) => Promise<void>;
+/**
+ * Sync variant of {@link wrapCommandHandler} for handlers that never return a Promise.
+ *
+ * Yargs invokes the wrapped function synchronously when registered, so errors thrown by the
+ * inner handler (and by `process.exit` itself when stubbed in tests) propagate synchronously —
+ * which is what `parseSync()`-based tests assert against via `expect(() => ...).toThrow(...)`.
+ *
+ * Use this when the inner handler does not perform any I/O. For async handlers (HTTP calls,
+ * disk reads, prompts) keep using {@link wrapCommandHandler}.
+ *
+ * @param handler - The inner sync command handler.
+ * @param exitCode - Optional override for the exit code on failure.
+ * @returns A sync handler that converts thrown errors into the standard envelope.
+ */
+export declare function wrapSyncCommandHandler<T>(handler: (argv: Arguments<T>) => void, exitCode?: number): (argv: Arguments<T>) => void;

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

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

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

@@ -20,7 +20,23 @@ export interface CliOutputOptions {
     readonly dumpDir?: string;
     readonly pick?: string;
     readonly commandPath?: string[];
+    /**
+     * When true, the stdout JSON envelope is rendered with 2-space indent instead of compact.
+     * Driven by the global `--pretty` flag.
+     */
+    readonly pretty?: boolean;
 }
+/**
+ * Standard exit code used when a CLI command handler throws.
+ *
+ * Used by {@link wrapCommandHandler} when no override is supplied.
+ */
+export declare const CLI_EXIT_CODE_HANDLER = 1;
+/**
+ * Exit code used when the auth middleware itself fails (no env, no token, expired refresh,
+ * etc.) — distinct from a handler error so scripts can disambiguate auth from logic failures.
+ */
+export declare const CLI_EXIT_CODE_AUTH = 4;
 /**
  * Patterns that indicate a string may contain a secret token or credential.
  */
@@ -54,6 +70,51 @@ export declare function configureOutputOptions(options: CliOutputOptions): void;
  * @returns The active output options (empty object when never configured).
  */
 export declare function getOutputOptions(): CliOutputOptions;
+/**
+ * Toggles the process-wide verbose flag. The HTTP layer (`call-model.client.ts`,
+ * `oidc.client.ts`) checks {@link isCliVerbose} before each request and emits a
+ * `[<method> <url>]` trace line to stderr when enabled.
+ *
+ * @param value - Whether verbose tracing is on.
+ */
+export declare function setCliVerbose(value: boolean): void;
+/**
+ * @returns Whether the verbose flag is currently enabled.
+ */
+export declare function isCliVerbose(): boolean;
+/**
+ * Writes a one-line stderr trace prefixed with `[verbose]` when the verbose
+ * flag is on. No-op otherwise. Kept off stdout so the JSON envelope on stdout
+ * stays parseable.
+ *
+ * @param message - The trace message.
+ */
+export declare function verboseLog(message: string): void;
+/**
+ * Drop-in `fetch` replacement that wraps the request with the configured verbose-trace
+ * and `--timeout` behavior. Aborts via `AbortController` after the configured timeout.
+ *
+ * Translates an aborted request into a {@link CliError} with code `TIMEOUT`.
+ *
+ * @param fetcher - The underlying fetch impl (defaults to global `fetch`). Allows tests to inject.
+ * @param input - The first arg to fetch (URL or Request).
+ * @param init - The RequestInit. Any existing `signal` is preserved; we only attach our own when no signal was supplied.
+ * @returns The fetch Response.
+ */
+export declare function tracedFetch(fetcher: typeof fetch | undefined, input: string | URL | Request, init?: RequestInit): Promise<Response>;
+/**
+ * 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.
+ *
+ * @param ms - Timeout in ms, or `undefined` to clear.
+ */
+export declare function setCliTimeoutMs(ms: Maybe<number>): void;
+/**
+ * @returns The current process-wide HTTP timeout in ms, or `undefined` when unset.
+ */
+export declare function getCliTimeoutMs(): Maybe<number>;
 /**
  * Replaces the active secret-redaction pattern list with the given patterns.
  *
@@ -110,7 +171,8 @@ export declare function pickFields<T>(data: T, pick: string): T;
  * Prints a successful command result as a `{ ok: true, data, meta? }` JSON envelope on stdout.
  *
  * Also writes a full unfiltered dump to disk when `dumpDir` is configured, then applies any
- * configured `pick` filter to the stdout payload.
+ * configured `pick` filter to the stdout payload. Honors the global `--pretty` flag for the
+ * stdout payload only (the dump-to-disk path is always pretty-printed).
  *
  * @param data - The command result to emit.
  * @param meta - Optional additional metadata to attach to the envelope.
@@ -119,6 +181,8 @@ export declare function outputResult<T>(data: T, meta?: Record<string, unknown>)
 /**
  * Prints a failed command result as a `{ ok: false, error, code, suggestion? }` JSON envelope on stdout.
  *
+ * Honors the global `--pretty` flag.
+ *
  * @param error - The thrown value to convert. Mapped via {@link buildErrorOutput} (which consults any registered {@link CliErrorMapper}).
  */
 export declare function outputError(error: unknown): void;

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

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ *
+ * @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;
+/**
+ * Reads the entire contents of `process.stdin` as a UTF-8 string.
+ *
+ * Used by command handlers that accept `-` to mean "read from stdin" (e.g. `--data -`,
+ * `get-many -`). Resolves once the stream emits `end`; no timeout is applied — callers that
+ * need one should wrap with `Promise.race`.
+ *
+ * @returns The UTF-8 decoded stdin contents.
+ */
+export declare function readAllStdin(): Promise<string>;
+/**
+ * Reads stdin as a list of whitespace-separated tokens (newlines, spaces, tabs).
+ *
+ * Empty tokens are dropped so a trailing newline doesn't introduce a phantom entry.
+ *
+ * @returns The tokens parsed from stdin.
+ */
+export declare function readStdinTokens(): Promise<string[]>;

package/test/index.cjs.default.js

@@ -0,0 +1 @@
+exports._default = require('./index.cjs.js').default;

package/test/index.cjs.js

@@ -0,0 +1,381 @@
+'use strict';
+
+var vitest = require('vitest');
+var dbxCli = require('@dereekb/dbx-cli');
+
+function _array_like_to_array(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_without_holes(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array(arr);
+}
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _instanceof(left, right) {
+    "@swc/helpers - instanceof";
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else {
+        return left instanceof right;
+    }
+}
+function _iterable_to_array(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _non_iterable_spread() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _to_consumable_array(arr) {
+    return _array_without_holes(arr) || _iterable_to_array(arr) || _unsupported_iterable_to_array(arr) || _non_iterable_spread();
+}
+function _type_of(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+function _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+/**
+ * Builds a {@link CliContext} for use as `testCliContext` on {@link createCli}.
+ *
+ * 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).
+ * @returns The constructed {@link CliContext} that drives `callModel` / `getModel` / `getMultipleModels`
+ *   against `input.env.apiBaseUrl` with `input.accessToken` as the Bearer token.
+ * @__NO_SIDE_EFFECTS__
+ */ function buildTestCliContext(input) {
+    return dbxCli.createCliContext({
+        cliName: input.cliName,
+        envName: input.envName,
+        env: input.env,
+        accessToken: input.accessToken,
+        modelManifest: input.modelManifest
+    });
+}
+/**
+ * Drives a CLI invocation in-process and captures all output.
+ *
+ * Creates a fresh yargs `Argv` per call (so middleware/option defaults can't leak across tests),
+ * parses `args`, and collects `process.stdout.write` / `process.stderr.write` / `console.log` /
+ * `console.error` output via `vi.spyOn`. The spies are always restored on completion.
+ *
+ * Always resolves — handler errors and yargs failures are surfaced in {@link RunCliCommandResult.error}
+ * instead of being thrown.
+ *
+ * @param input - The {@link CreateCliInput} used to build the CLI for this invocation. Pass a fresh
+ *   object each call (or rely on the caller-side factory) — yargs `Argv` state is not reused across
+ *   invocations.
+ * @param args - The argv vector to parse (e.g. `['get', 'p/abc']`).
+ * @returns The captured output envelope.
+ */ function runCliCommand(input, args) {
+    return _async_to_generator(function() {
+        var stdoutChunks, stderrChunks, writeSpy, errSpy, logSpy, errLogSpy, capturedExitCode, exitSentinel, exitSpy, capturedArgv, capturedError, helpOutput, e, result;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    stdoutChunks = [];
+                    stderrChunks = [];
+                    writeSpy = vitest.vi.spyOn(process.stdout, 'write').mockImplementation(function(chunk) {
+                        stdoutChunks.push(toChunkString(chunk));
+                        return true;
+                    });
+                    errSpy = vitest.vi.spyOn(process.stderr, 'write').mockImplementation(function(chunk) {
+                        stderrChunks.push(toChunkString(chunk));
+                        return true;
+                    });
+                    logSpy = vitest.vi.spyOn(console, 'log').mockImplementation(function() {
+                        for(var _len = arguments.length, parts = new Array(_len), _key = 0; _key < _len; _key++){
+                            parts[_key] = arguments[_key];
+                        }
+                        stdoutChunks.push(parts.map(function(p) {
+                            return stringifyConsolePart(p);
+                        }).join(' ') + '\n');
+                    });
+                    errLogSpy = vitest.vi.spyOn(console, 'error').mockImplementation(function() {
+                        for(var _len = arguments.length, parts = new Array(_len), _key = 0; _key < _len; _key++){
+                            parts[_key] = arguments[_key];
+                        }
+                        stderrChunks.push(parts.map(function(p) {
+                            return stringifyConsolePart(p);
+                        }).join(' ') + '\n');
+                    });
+                    exitSentinel = new Error('__cli_test_process_exit__');
+                    exitSpy = vitest.vi.spyOn(process, 'exit').mockImplementation(function(code) {
+                        capturedExitCode = typeof code === 'number' ? code : 0;
+                        throw exitSentinel;
+                    });
+                    helpOutput = '';
+                    _state.label = 1;
+                case 1:
+                    _state.trys.push([
+                        1,
+                        3,
+                        4,
+                        5
+                    ]);
+                    return [
+                        4,
+                        dbxCli.createCli(input).exitProcess(false).parse(_to_consumable_array(args), function(err, argv, output) {
+                            capturedArgv = argv;
+                            if (err) capturedError = err;
+                            helpOutput = output;
+                        })
+                    ];
+                case 2:
+                    _state.sent();
+                    return [
+                        3,
+                        5
+                    ];
+                case 3:
+                    e = _state.sent();
+                    if (e !== exitSentinel) {
+                        capturedError = _instanceof(e, Error) ? e : new Error(String(e));
+                    }
+                    return [
+                        3,
+                        5
+                    ];
+                case 4:
+                    writeSpy.mockRestore();
+                    errSpy.mockRestore();
+                    logSpy.mockRestore();
+                    errLogSpy.mockRestore();
+                    exitSpy.mockRestore();
+                    return [
+                        7
+                    ];
+                case 5:
+                    result = {
+                        stdout: stdoutChunks,
+                        stderr: stderrChunks,
+                        stdoutText: stdoutChunks.join(''),
+                        stderrText: stderrChunks.join(''),
+                        argv: capturedArgv,
+                        helpOutput: helpOutput,
+                        error: capturedError,
+                        exitCode: capturedExitCode
+                    };
+                    return [
+                        2,
+                        result
+                    ];
+            }
+        });
+    })();
+}
+/**
+ * Idempotently binds the fixture's NestJS application to `127.0.0.1:0` (or the supplied host) and
+ * returns the live `apiBaseUrl` so the CLI's `fetch` calls have a real socket to hit.
+ *
+ * Safe to call multiple times against the same app — when `app.getHttpServer().listening` is true,
+ * skips re-binding and just resolves the current address.
+ *
+ * The caller does NOT need to `.close()` explicitly: the demoApi/firebase-admin-nest fixture closes
+ * the underlying NestJS app at the end of its describe block, which closes the HTTP listener.
+ *
+ * @param input - The fixture app + optional global route prefix (defaults to `'api'` to match
+ *   demo-api's production prefix) and host (defaults to `127.0.0.1`).
+ * @returns The bound `apiBaseUrl` (e.g. `http://127.0.0.1:54321/api`) and the resolved port.
+ */ function listenOnNestAppForTest(input) {
+    return _async_to_generator(function() {
+        var _input_host, _input_apiPrefix, host, prefix, server, address, port, trimmedPrefix, apiBaseUrl;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    host = (_input_host = input.host) !== null && _input_host !== void 0 ? _input_host : '127.0.0.1';
+                    prefix = (_input_apiPrefix = input.apiPrefix) !== null && _input_apiPrefix !== void 0 ? _input_apiPrefix : 'api';
+                    server = input.app.getHttpServer();
+                    if (!!server.listening) return [
+                        3,
+                        2
+                    ];
+                    return [
+                        4,
+                        input.app.listen(0, host)
+                    ];
+                case 1:
+                    _state.sent();
+                    _state.label = 2;
+                case 2:
+                    address = server.address();
+                    port = (typeof address === "undefined" ? "undefined" : _type_of(address)) === 'object' && address ? address.port : 0;
+                    trimmedPrefix = prefix.replace(/^\/+|\/+$/g, '');
+                    apiBaseUrl = trimmedPrefix.length > 0 ? "http://".concat(host, ":").concat(port, "/").concat(trimmedPrefix) : "http://".concat(host, ":").concat(port);
+                    return [
+                        2,
+                        {
+                            apiBaseUrl: apiBaseUrl,
+                            port: port
+                        }
+                    ];
+            }
+        });
+    })();
+}
+function toChunkString(chunk) {
+    var result;
+    if (typeof chunk === 'string') {
+        result = chunk;
+    } else if (_instanceof(chunk, Uint8Array)) {
+        result = Buffer.from(chunk).toString('utf8');
+    } else {
+        result = String(chunk);
+    }
+    return result;
+}
+function stringifyConsolePart(part) {
+    var result;
+    if (typeof part === 'string') {
+        result = part;
+    } else if (_instanceof(part, Error)) {
+        var _part_stack;
+        result = (_part_stack = part.stack) !== null && _part_stack !== void 0 ? _part_stack : part.message;
+    } else {
+        try {
+            result = JSON.stringify(part);
+        } catch (unused) {
+            result = String(part);
+        }
+    }
+    return result;
+}
+
+exports.buildTestCliContext = buildTestCliContext;
+exports.listenOnNestAppForTest = listenOnNestAppForTest;
+exports.runCliCommand = runCliCommand;

package/test/index.cjs.mjs

@@ -0,0 +1,2 @@
+export * from './index.cjs.js';
+export { _default as default } from './index.cjs.default.js';

package/test/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/index";