primitive-admin 1.0.49 → 1.0.51

package/dist/src/lib/confirm-prompt.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Shared interactive-confirmation helper for destructive CLI commands.
+ *
+ * Background (issue #972): every destructive command used the legacy
+ * `inquirer.default.prompt([{ type: "confirm", ... }])` pattern directly. When
+ * stdin is not a usable TTY (closed/piped/EOF/Ctrl-D), inquirer v9.3.8 throws
+ * `ERR_USE_AFTER_CLOSE: readline was closed` from inside a Node event-emitter
+ * callback (`PromptUI.onForceClose` -> `process.emit`). Because that throw
+ * originates in event-dispatch, it escapes both the command's own `try/catch`
+ * AND the top-level `.catch` in `cli/bin/primitive.ts` — and with no
+ * `uncaughtException` handler, Node printed only the bare `Node.js vX` banner
+ * and died before the API call. `cron-triggers delete` / `workflows delete`
+ * crashed without deleting anything.
+ *
+ * Migration (issue #999): the helper's internals are now built on the modern
+ * `@inquirer/prompts` `confirm()` API instead of legacy `inquirer.default.prompt`.
+ * The modern API rejects its promise with a *catchable* `ExitPromptError`
+ * (Ctrl-C / SIGINT / force-close) / `AbortPromptError` / `CancelPromptError`
+ * rather than crashing via `process.emit`, so the root-cause crash class is
+ * removed. Crucially, `@inquirer/prompts` `confirm()` has **no built-in non-TTY
+ * guard** — so the #972 guard below MUST stay, or the crash class regresses into
+ * a hang/opaque-reject on piped/closed stdin. The migration changes only the
+ * default prompt fn's internals; the guard, the `ConfirmPromptError` contract,
+ * and the public `confirmPrompt()` signature are preserved.
+ *
+ * `confirmPrompt()` fixes the cause:
+ *   1. Non-TTY guard — if stdin is not a TTY, it never touches the prompt.
+ *      Instead it throws a catchable `ConfirmPromptError` with an actionable
+ *      message ("re-run with --yes ..."). Per the maintainer decision on #972
+ *      this is a hard error, never a silent mutate or silent abort.
+ *   2. Local try/catch — in a real TTY the prompt is awaited inside a try/catch
+ *      so an abort/EOF (`ExitPromptError` / `AbortPromptError` /
+ *      `CancelPromptError`, or legacy `ERR_USE_AFTER_CLOSE`) surfaces as a clean
+ *      `ConfirmPromptError`, not a stack trace or crash.
+ *
+ * Commands should call this instead of inquirer directly, e.g.:
+ *
+ *   if (!options.yes) {
+ *     try {
+ *       const ok = await confirmPrompt(`Delete cron trigger ${id}?`);
+ *       if (!ok) { info("Cancelled."); return; }
+ *     } catch (err) {
+ *       error(err.message);
+ *       process.exit(1);
+ *     }
+ *   }
+ */
+/** Error thrown when a confirmation can't be obtained interactively. */
+export declare class ConfirmPromptError extends Error {
+    constructor(message: string);
+}
+/**
+ * Shape of the `@inquirer/prompts` `confirm()` function. Injectable for testing.
+ *
+ * Note (#999): this shifted from the legacy inquirer questions-array →
+ * `{ confirm: boolean }` shape to the modern bare `{ message, default }` →
+ * `Promise<boolean>` shape.
+ */
+export type PromptFn = (config: {
+    message: string;
+    default?: boolean;
+}) => Promise<boolean>;
+export interface ConfirmPromptOptions {
+    /** Default answer when the user just presses enter. Defaults to false. */
+    defaultValue?: boolean;
+    /**
+     * Override the underlying prompt function (for tests). Defaults to lazily
+     * importing `@inquirer/prompts` `confirm`.
+     */
+    promptFn?: PromptFn;
+    /**
+     * Override TTY detection (for tests). Defaults to `process.stdin.isTTY`.
+     */
+    isTTY?: boolean;
+}
+/**
+ * Ask the user a yes/no confirmation question.
+ *
+ * @returns `true` if the user confirms, `false` if they decline.
+ * @throws {ConfirmPromptError} when stdin is not an interactive TTY (so the
+ *   prompt can't be shown), or when the underlying prompt aborts/crashes.
+ */
+export declare function confirmPrompt(message: string, options?: ConfirmPromptOptions): Promise<boolean>;

package/dist/src/lib/confirm-prompt.js

@@ -0,0 +1,110 @@
+/**
+ * Shared interactive-confirmation helper for destructive CLI commands.
+ *
+ * Background (issue #972): every destructive command used the legacy
+ * `inquirer.default.prompt([{ type: "confirm", ... }])` pattern directly. When
+ * stdin is not a usable TTY (closed/piped/EOF/Ctrl-D), inquirer v9.3.8 throws
+ * `ERR_USE_AFTER_CLOSE: readline was closed` from inside a Node event-emitter
+ * callback (`PromptUI.onForceClose` -> `process.emit`). Because that throw
+ * originates in event-dispatch, it escapes both the command's own `try/catch`
+ * AND the top-level `.catch` in `cli/bin/primitive.ts` — and with no
+ * `uncaughtException` handler, Node printed only the bare `Node.js vX` banner
+ * and died before the API call. `cron-triggers delete` / `workflows delete`
+ * crashed without deleting anything.
+ *
+ * Migration (issue #999): the helper's internals are now built on the modern
+ * `@inquirer/prompts` `confirm()` API instead of legacy `inquirer.default.prompt`.
+ * The modern API rejects its promise with a *catchable* `ExitPromptError`
+ * (Ctrl-C / SIGINT / force-close) / `AbortPromptError` / `CancelPromptError`
+ * rather than crashing via `process.emit`, so the root-cause crash class is
+ * removed. Crucially, `@inquirer/prompts` `confirm()` has **no built-in non-TTY
+ * guard** — so the #972 guard below MUST stay, or the crash class regresses into
+ * a hang/opaque-reject on piped/closed stdin. The migration changes only the
+ * default prompt fn's internals; the guard, the `ConfirmPromptError` contract,
+ * and the public `confirmPrompt()` signature are preserved.
+ *
+ * `confirmPrompt()` fixes the cause:
+ *   1. Non-TTY guard — if stdin is not a TTY, it never touches the prompt.
+ *      Instead it throws a catchable `ConfirmPromptError` with an actionable
+ *      message ("re-run with --yes ..."). Per the maintainer decision on #972
+ *      this is a hard error, never a silent mutate or silent abort.
+ *   2. Local try/catch — in a real TTY the prompt is awaited inside a try/catch
+ *      so an abort/EOF (`ExitPromptError` / `AbortPromptError` /
+ *      `CancelPromptError`, or legacy `ERR_USE_AFTER_CLOSE`) surfaces as a clean
+ *      `ConfirmPromptError`, not a stack trace or crash.
+ *
+ * Commands should call this instead of inquirer directly, e.g.:
+ *
+ *   if (!options.yes) {
+ *     try {
+ *       const ok = await confirmPrompt(`Delete cron trigger ${id}?`);
+ *       if (!ok) { info("Cancelled."); return; }
+ *     } catch (err) {
+ *       error(err.message);
+ *       process.exit(1);
+ *     }
+ *   }
+ */
+/** Error thrown when a confirmation can't be obtained interactively. */
+export class ConfirmPromptError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfirmPromptError";
+    }
+}
+async function defaultPromptFn(config) {
+    const { confirm } = await import("@inquirer/prompts");
+    return confirm(config);
+}
+/**
+ * Names of the catchable abort errors thrown by `@inquirer/prompts` when the
+ * user interrupts a prompt (Ctrl-C / SIGINT / force-close / abort signal /
+ * cancel). We match on `name` (not just `instanceof`) so detection is robust to
+ * the error class being duplicated across module realms.
+ */
+const ABORT_ERROR_NAMES = new Set([
+    "ExitPromptError",
+    "AbortPromptError",
+    "CancelPromptError",
+]);
+/**
+ * Ask the user a yes/no confirmation question.
+ *
+ * @returns `true` if the user confirms, `false` if they decline.
+ * @throws {ConfirmPromptError} when stdin is not an interactive TTY (so the
+ *   prompt can't be shown), or when the underlying prompt aborts/crashes.
+ */
+export async function confirmPrompt(message, options = {}) {
+    const isTTY = options.isTTY ?? Boolean(process.stdin.isTTY);
+    if (!isTTY) {
+        throw new ConfirmPromptError("No interactive terminal available to confirm this action. " +
+            "Re-run with --yes (-y) to skip the confirmation prompt in " +
+            "non-interactive contexts (CI, pipes, agents).");
+    }
+    const promptFn = options.promptFn ?? defaultPromptFn;
+    try {
+        const confirmed = await promptFn({
+            message,
+            default: options.defaultValue ?? false,
+        });
+        return Boolean(confirmed);
+    }
+    catch (err) {
+        // A deliberate abort/EOF/Ctrl-C/Ctrl-D — either the modern
+        // `@inquirer/prompts` `ExitPromptError`/`AbortPromptError`/`CancelPromptError`
+        // (matched by name to survive cross-realm `instanceof` mismatches), or the
+        // legacy inquirer `ERR_USE_AFTER_CLOSE`. Surface as a clean, actionable
+        // error so the caller exits 1 with no stack trace / bare `Node.js vX` banner.
+        if (ABORT_ERROR_NAMES.has(err?.name) ||
+            err?.code === "ERR_USE_AFTER_CLOSE") {
+            throw new ConfirmPromptError("Confirmation cancelled (no interactive input). " +
+                "Re-run with --yes (-y) to skip confirmation.");
+        }
+        // Any other prompt failure: still surface it as a clean, catchable error
+        // rather than letting it escape as an uncaught crash.
+        throw new ConfirmPromptError(err?.message
+            ? `Confirmation prompt failed: ${err.message}`
+            : "Confirmation prompt failed.");
+    }
+}
+//# sourceMappingURL=confirm-prompt.js.map

package/dist/src/lib/confirm-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm-prompt.js","sourceRoot":"","sources":["../../../src/lib/confirm-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,wEAAwE;AACxE,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AA4BD,KAAK,UAAU,eAAe,CAAC,MAG9B;IACC,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;IACtD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;AACzB,CAAC;AAED;;;;;GAKG;AACH,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;IAChC,iBAAiB;IACjB,kBAAkB;IAClB,mBAAmB;CACpB,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAe,EACf,UAAgC,EAAE;IAElC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAE5D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,kBAAkB,CAC1B,4DAA4D;YAC1D,4DAA4D;YAC5D,+CAA+C,CAClD,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,eAAe,CAAC;IAErD,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC;YAC/B,OAAO;YACP,OAAO,EAAE,OAAO,CAAC,YAAY,IAAI,KAAK;SACvC,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,2DAA2D;QAC3D,+EAA+E;QAC/E,2EAA2E;QAC3E,wEAAwE;QACxE,8EAA8E;QAC9E,IACE,iBAAiB,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC;YAChC,GAAG,EAAE,IAAI,KAAK,qBAAqB,EACnC,CAAC;YACD,MAAM,IAAI,kBAAkB,CAC1B,iDAAiD;gBAC/C,8CAA8C,CACjD,CAAC;QACJ,CAAC;QACD,yEAAyE;QACzE,sDAAsD;QACtD,MAAM,IAAI,kBAAkB,CAC1B,GAAG,EAAE,OAAO;YACV,CAAC,CAAC,+BAA+B,GAAG,CAAC,OAAO,EAAE;YAC9C,CAAC,CAAC,6BAA6B,CAClC,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/src/lib/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const PRODUCTION_SERVER_URL = "https://primitiveapi.com";
+export declare const DEFAULT_SERVER_URL: string;

package/dist/src/lib/crash-handlers.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Global crash handlers for the CLI entrypoint (issue #972, Option A).
+ *
+ * The CLI previously registered no `uncaughtException` / `unhandledRejection`
+ * handlers. When an error escaped the top-level `.catch` in
+ * `cli/bin/primitive.ts` — e.g. the `ERR_USE_AFTER_CLOSE` thrown from inside an
+ * inquirer event-emitter callback when stdin isn't a usable TTY — Node printed
+ * only its bare `Node.js vX` version banner and died. That was the exact
+ * symptom in #972: a delete command crashed with no error message.
+ *
+ * These handlers are a narrow safety net: print a clean `✗ <message>` to stderr
+ * (matching `error()` in output.ts) and exit non-zero, so NO command can ever
+ * bare-crash again. They intentionally do not try to recover — they only make
+ * an already-fatal error legible.
+ */
+/**
+ * Register process-level handlers that convert otherwise-fatal escaped errors
+ * into a clean stderr message + non-zero exit. Idempotent.
+ */
+export declare function installGlobalCrashHandlers(): void;

package/dist/src/lib/crash-handlers.js

@@ -0,0 +1,49 @@
+/**
+ * Global crash handlers for the CLI entrypoint (issue #972, Option A).
+ *
+ * The CLI previously registered no `uncaughtException` / `unhandledRejection`
+ * handlers. When an error escaped the top-level `.catch` in
+ * `cli/bin/primitive.ts` — e.g. the `ERR_USE_AFTER_CLOSE` thrown from inside an
+ * inquirer event-emitter callback when stdin isn't a usable TTY — Node printed
+ * only its bare `Node.js vX` version banner and died. That was the exact
+ * symptom in #972: a delete command crashed with no error message.
+ *
+ * These handlers are a narrow safety net: print a clean `✗ <message>` to stderr
+ * (matching `error()` in output.ts) and exit non-zero, so NO command can ever
+ * bare-crash again. They intentionally do not try to recover — they only make
+ * an already-fatal error legible.
+ */
+import { error } from "./output.js";
+function describe(err) {
+    if (err && typeof err === "object") {
+        const e = err;
+        // The signature crash from a non-TTY confirm prompt — give actionable help.
+        if (e.code === "ERR_USE_AFTER_CLOSE") {
+            return ("No interactive terminal available to confirm this action. " +
+                "Re-run with --yes (-y) to skip the confirmation prompt in " +
+                "non-interactive contexts (CI, pipes, agents).");
+        }
+        if (e.message)
+            return e.message;
+    }
+    return "An unexpected error occurred.";
+}
+let installed = false;
+/**
+ * Register process-level handlers that convert otherwise-fatal escaped errors
+ * into a clean stderr message + non-zero exit. Idempotent.
+ */
+export function installGlobalCrashHandlers() {
+    if (installed)
+        return;
+    installed = true;
+    process.on("uncaughtException", (err) => {
+        error(describe(err));
+        process.exit(1);
+    });
+    process.on("unhandledRejection", (reason) => {
+        error(describe(reason));
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=crash-handlers.js.map

package/dist/src/lib/crash-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crash-handlers.js","sourceRoot":"","sources":["../../../src/lib/crash-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpC,SAAS,QAAQ,CAAC,GAAY;IAC5B,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,GAA0C,CAAC;QACrD,4EAA4E;QAC5E,IAAI,CAAC,CAAC,IAAI,KAAK,qBAAqB,EAAE,CAAC;YACrC,OAAO,CACL,4DAA4D;gBAC5D,4DAA4D;gBAC5D,+CAA+C,CAChD,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,CAAC,OAAO;YAAE,OAAO,CAAC,CAAC,OAAO,CAAC;IAClC,CAAC;IACD,OAAO,+BAA+B,CAAC;AACzC,CAAC;AAED,IAAI,SAAS,GAAG,KAAK,CAAC;AAEtB;;;GAGG;AACH,MAAM,UAAU,0BAA0B;IACxC,IAAI,SAAS;QAAE,OAAO;IACtB,SAAS,GAAG,IAAI,CAAC;IAEjB,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAG,EAAE,EAAE;QACtC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAM,EAAE,EAAE;QAC1C,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACxB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/lib/credentials-store.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Credentials storage with dual-mode support.
+ *
+ * Mode A (project mode): credentials live at
+ *   <projectRoot>/.primitive/credentials.json
+ * with per-environment slots:
+ *   {
+ *     "environments": {
+ *       "dev":  { "accessToken": "...", "refreshToken": "...", ... },
+ *       "prod": { ... }
+ *     }
+ *   }
+ *
+ * Mode B (legacy mode): no .primitive/config.json in scope, so we fall back to
+ *   ~/.primitive/credentials.json
+ * with the flat Credentials shape the CLI has always used.
+ *
+ * The legacy mode is still the "global default" for users who haven't
+ * run `primitive init` yet.
+ */
+import type { Credentials } from "../types/index.js";
+export declare const PROJECT_LOCAL_DIR = ".primitive";
+export declare const PROJECT_CREDENTIALS_FILENAME = "credentials.json";
+/** Returns true when a .primitive/config.json is in scope (project mode active). */
+export declare function isProjectMode(): boolean;
+/**
+ * Returns the path to the credentials file that will be used, based on
+ * whether we're in project mode or legacy mode.
+ */
+export declare function getCredentialsFilePath(): string;
+/**
+ * Reads credentials for the current environment (project mode) or the
+ * legacy global file. Returns the standard Credentials shape so existing
+ * callers don't need to change.
+ *
+ * In project mode, we blend the per-env stored creds with the serverUrl
+ * and appId from .primitive/config.json to produce the Credentials the rest of
+ * the CLI expects.
+ */
+export declare function loadCredentialsStore(): Credentials | null;
+/**
+ * Saves credentials. In project mode, writes to the per-env slot in the
+ * project credentials file. In legacy mode, writes the global file.
+ *
+ * The serverUrl on the incoming Credentials is used as-is for legacy
+ * mode, and ignored in project mode (the env's apiUrl is canonical).
+ */
+export declare function saveCredentialsStore(credentials: Credentials): void;
+/**
+ * Clears credentials for the current environment (project mode) or
+ * deletes the legacy file (legacy mode).
+ */
+export declare function clearCredentialsStore(): void;
+/**
+ * Removes the credentials slot for the named environment in a specific
+ * project's credentials file. Used by `env remove` so stale tokens from a
+ * previously-removed environment can never be silently re-used if the same
+ * name is later added back. Never throws.
+ */
+export declare function clearCredentialsForEnvInProject(projectRoot: string, envName: string): void;
+/**
+ * Lists all environments that have stored credentials in project mode.
+ * Returns an empty array in legacy mode.
+ */
+export declare function listAuthenticatedEnvironments(): string[];
+/**
+ * Updates the "current app" in credential storage. In project mode with a
+ * project-level appId this is a no-op (the project config is canonical).
+ */
+export declare function setCurrentAppStore(appId: string, appName?: string): void;
+/**
+ * Clears the "current app" for the current environment.
+ */
+export declare function clearCurrentAppStore(): void;
+/**
+ * Returns the legacy credentials file, if one exists. Used by migration
+ * prompts that want to detect a pre-project-config install.
+ */
+export declare function peekLegacyCredentials(): Credentials | null;

package/dist/src/lib/csv.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Parse a CSV string into an array of row objects keyed by header.
+ *
+ * Quote-aware: respects double-quoted fields that may contain the delimiter,
+ * embedded newlines, and escaped double-quotes (`""`). Empty-string cells are
+ * omitted from the row object (matching the client). Headers-only / empty
+ * input yields `[]`.
+ */
+export declare function parseCsv(csv: string, delimiter?: string): Record<string, string>[];
+/**
+ * Coerce a string cell to a target type. Mirrors the client's `coerceValue`:
+ * a failed number coercion returns the original string (so the server's
+ * schema validation surfaces a precise error rather than a silent bad write).
+ */
+export declare function coerceValue(value: string, type: string): any;
+/**
+ * Rename row keys per a `{ "CSV Header": "fieldName" }` map. Keys not present
+ * in the map are preserved. No-op when `map` is undefined.
+ */
+export declare function applyColumnMap(rows: Record<string, any>[], map: Record<string, string> | undefined): Record<string, any>[];
+export interface BuildRowsOptions {
+    /** Model name passed in each batch item's params. */
+    modelName: string;
+    /** Type coercion overrides keyed by (post-column-map) field name. */
+    types?: Record<string, string>;
+    /** CSV column whose value to use as the record id (else a ULID is generated). */
+    idColumn?: string;
+}
+export interface BatchItem {
+    params: {
+        modelName: string;
+        id: string;
+        data: Record<string, any>;
+    };
+}
+export interface BuildRowsResult {
+    batch: BatchItem[];
+    rowCount: number;
+}
+/**
+ * Apply type coercion, assign each row an id (from `idColumn` or a generated
+ * ULID), and shape rows into `executeBatch` items
+ * (`{ params: { modelName, id, data } }`). Mirrors steps 5–7 of the client's
+ * `importCsv`.
+ */
+export declare function buildRows(rows: Record<string, any>[], options: BuildRowsOptions): BuildRowsResult;
+/** Split an array into fixed-size chunks. */
+export declare function chunk<T>(items: T[], size: number): T[][];

package/dist/src/lib/db-codegen/dbFingerprint.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Short fingerprint for a database-type TOML string (issue #814).
+ *
+ * Stamped in the header of every generated file so a human (or the
+ * `--check` CI guard) can tell at a glance whether the source TOML and the
+ * generated output are in sync. Mirrors codegen-v2's `fingerprintToml`
+ * (`packages/js-bao/src/cli/v2/fingerprint.ts`): 16 hex chars of SHA-256 —
+ * enough for a sanity check, short enough to fit on one comment line.
+ */
+export declare function fingerprintToml(tomlContent: string): string;

package/dist/src/lib/db-codegen/dbGenerator.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `databases codegen` orchestrator (issue #814).
+ *
+ * Pure-ish core: given a set of database-type TOML strings + a target
+ * output dir, decides what `*.generated.ts` files to write (in memory),
+ * then either (a) writes them, or (b) compares them against on-disk for
+ * `--check`. No commander dependency, no `process.exit`.
+ *
+ * Reuses the codegen-v2 machinery:
+ *   - `loadSchemaFromTomlString` (the shared `[models.*]` parser) for record
+ *     interfaces — the database-type `[models.*]` blocks round-trip through
+ *     the same loader and the same `FieldType` vocabulary.
+ *   - The banner + fingerprint header pattern and stale-output cleanup.
+ *
+ * Adds the OPERATIONS half (op-params interfaces + per-op result aliases)
+ * that codegen-v2 has no analog for. Op return contracts are NOT stored in
+ * the TOML, so result aliases are generic shapes keyed off `op.type`.
+ */
+export interface DbCodegenInput {
+    /** Database type name (drives the output filename). */
+    databaseType: string;
+    /** Path to the source `database-types/<type>.toml` file. */
+    tomlPath: string;
+    /** Raw TOML content (already read from disk). */
+    tomlContent: string;
+}
+export interface GenerateDbTypesOptions {
+    /** One entry per database-type TOML file to generate from. */
+    inputs: DbCodegenInput[];
+    /** Directory where `<type>.generated.ts` files are written. */
+    outputDir: string;
+    /**
+     * If true, do not write to disk. Compare the would-be output to what's on
+     * disk and return a non-empty `mismatches` list if any file would change.
+     */
+    check?: boolean;
+    /**
+     * Set when the run was filtered to a single database type (the
+     * `primitive databases codegen <type>` argument). The `inputs` set is then
+     * PARTIAL — it does not represent the full set of owned generated files — so
+     * stale-output cleanup (and `--check` stale detection) must be scoped to the
+     * filtered type's own file and must NOT touch / flag sibling types'
+     * `*.generated.ts` files. The unfiltered "generate all" run leaves this unset
+     * and keeps full orphan cleanup.
+     */
+    singleType?: boolean;
+}
+export interface DbCodegenResult {
+    /** Files written (or that would be written under `--check`). */
+    writtenFiles: string[];
+    /** Stale `*.generated.ts` files deleted (or flagged stale under `--check`). */
+    deletedFiles: string[];
+    /** Only populated under `--check`: files whose on-disk content is out of date. */
+    mismatches: DbCheckMismatch[];
+}
+export interface DbCheckMismatch {
+    filePath: string;
+    reason: "missing" | "differs" | "stale";
+}
+/**
+ * Render the in-memory `.generated.ts` content for a single database-type
+ * TOML. Exported so tests can assert on the rendered string directly.
+ */
+export declare function renderDbTypeFile(input: DbCodegenInput): string;
+/**
+ * Per-model result of {@link inferRequiredRecordFields}. Shaped as an object
+ * (rather than a bare `Set`) so it can grow additional inferred metadata later
+ * without changing the call-site contract — e.g. future alignment with #845's
+ * server-side op-params analysis. For now it carries only the set of record
+ * fields the operation params prove are always supplied at create time.
+ */
+export interface InferredRecordModelInfo {
+    /** Record field names promoted to non-optional by op-params inference. */
+    fields: Set<string>;
+}
+/**
+ * Infer which record fields are always supplied at create time, by reading the
+ * `save` operation params (issue #842).
+ *
+ * A field is promoted to required for a model only if:
+ *   - at least one `save` (create) op writes it from a bare `$params.X`
+ *     binding, AND
+ *   - EVERY `save` op that writes the field binds it to a param declared
+ *     `required: true` (the "ALL writers agree" rule).
+ *
+ * Deliberately conservative:
+ *   - `patch` (and every non-`save` inner op) is excluded — partial updates
+ *     don't guarantee creation-time presence.
+ *   - whole-object saves (`data = "$params.X"`, a string rather than a
+ *     per-field map) carry no field-level mapping, so no field can be promoted
+ *     from them (Q4 skip).
+ *   - only an EXACT top-level bare `$params.X` value counts (the whole binding
+ *     value must match `^\$params\.X$`, and `X` must be a declared top-level
+ *     param). A literal, computed, partially-interpolated value, or a nested
+ *     path (`$params.obj.sub`) never promotes a field — a nested sub-property
+ *     may be absent even when the top-level object param is required. This is
+ *     deliberately stricter than the CLI's lenient `collectParamRefs`
+ *     first-segment rule, which is fine for its validation use but would
+ *     wrongly promote nested bindings here.
+ *   - inner ops are matched to the record model by the inner op's own
+ *     `modelName` when present, falling back to the enclosing operation's
+ *     `modelName`.
+ *
+ * Pure: no I/O, no mutation of the input. The caller OR's the result with the
+ * schema-level `required` flag, so inference only ever ADDS requiredness.
+ */
+export declare function inferRequiredRecordFields(operations: any[]): Map<string, InferredRecordModelInfo>;
+/**
+ * Run codegen end-to-end across one or more database-type TOML inputs.
+ */
+export declare function generateDbTypes(options: GenerateDbTypesOptions): Promise<DbCodegenResult>;

package/dist/src/lib/db-codegen/dbNaming.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Identifier-naming helpers for the `databases codegen` generator (issue #814).
+ *
+ * Record interfaces mirror codegen-v2's class-name resolution
+ * (`packages/js-bao/src/cli/v2/pluralization.ts`): honor a `class_name`
+ * override, else singularize a snake_case plural to PascalCase. The
+ * singularization algorithm below is a faithful copy of codegen-v2's
+ * `singularizeToPascalCase`; it is inlined rather than imported because the
+ * CLI builds standalone (`tsc -p cli/tsconfig.json`, `rootDir: "."`) and
+ * cannot reach into the vendored `packages/js-bao/src` tree.
+ *
+ * It DIVERGES in the fallback: codegen-v2 THROWS when a model name doesn't
+ * look like a recognizable plural (ORM models are expected to be plural).
+ * Database-type model names are author-curated and frequently already
+ * singular / PascalCase (e.g. `[models.User]`), so we PascalCase the name
+ * verbatim rather than failing the whole run.
+ *
+ * Op interfaces/aliases derive from the operation name (PascalCase) +
+ * `Params` / `Result` suffix (e.g. `saveAccount` → `SaveAccountParams`,
+ * `SaveAccountResult`).
+ */
+/**
+ * Resolve the record-interface name for a model. Honors a `class_name`
+ * override, then tries plural→singular Pascal, then falls back to a verbatim
+ * PascalCase of the model name (no throw).
+ */
+export declare function resolveRecordInterfaceName(modelName: string, classNameOverride: string | undefined): string;
+/** `saveAccount` → `SaveAccountParams`. */
+export declare function opParamsInterfaceName(opName: string): string;
+/** `saveAccount` → `SaveAccountResult`. */
+export declare function opResultAliasName(opName: string): string;
+/**
+ * Convert a snake_case plural model name (`user_prefs`, `categories`) into a
+ * PascalCase singular interface name (`UserPref`, `Category`). Returns null
+ * if no suffix rule matches the input. Faithful copy of codegen-v2's
+ * `singularizeToPascalCase`.
+ */
+export declare function singularizeToPascalCase(snakePlural: string): string | null;
+/**
+ * PascalCase an identifier: splits on non-alphanumeric separators
+ * (`_`, `-`, spaces) and capitalizes each segment, preserving any existing
+ * internal casing (`saveAccount` → `SaveAccount`, `save_account` →
+ * `SaveAccount`).
+ */
+export declare function pascalCase(name: string): string;