primitive-admin 1.0.48 → 1.0.50

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

@@ -0,0 +1,85 @@
+/**
+ * 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.
+ *
+ * `confirmPrompt()` fixes the cause:
+ *   1. Non-TTY guard — if stdin is not a TTY, it never touches inquirer.
+ *      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 surfaces as a clean `ConfirmPromptError`, not a 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(questions) {
+    const inquirer = await import("inquirer");
+    return inquirer.default.prompt(questions);
+}
+/**
+ * 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 answers = await promptFn([
+            {
+                type: "confirm",
+                name: "confirm",
+                message,
+                default: options.defaultValue ?? false,
+            },
+        ]);
+        return Boolean(answers.confirm);
+    }
+    catch (err) {
+        // An abort/EOF/Ctrl-D inside inquirer (ERR_USE_AFTER_CLOSE) or any other
+        // prompt failure: surface it as a clean, catchable error rather than
+        // letting it escape as an uncaught crash.
+        if (err?.code === "ERR_USE_AFTER_CLOSE") {
+            throw new ConfirmPromptError("Confirmation prompt was interrupted (no interactive input). " +
+                "Re-run with --yes (-y) to skip confirmation.");
+        }
+        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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;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;AA0BD,KAAK,UAAU,eAAe,CAC5B,SAAkC;IAElC,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;IAC1C,OAAO,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,SAAgB,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;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,OAAO,GAAG,MAAM,QAAQ,CAAC;YAC7B;gBACE,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,SAAS;gBACf,OAAO;gBACP,OAAO,EAAE,OAAO,CAAC,YAAY,IAAI,KAAK;aACvC;SACF,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,yEAAyE;QACzE,qEAAqE;QACrE,0CAA0C;QAC1C,IAAI,GAAG,EAAE,IAAI,KAAK,qBAAqB,EAAE,CAAC;YACxC,MAAM,IAAI,kBAAkB,CAC1B,8DAA8D;gBAC5D,8CAA8C,CACjD,CAAC;QACJ,CAAC;QACD,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;

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

@@ -0,0 +1,97 @@
+/**
+ * Pure string templates for the `databases codegen` generator (issue #814).
+ *
+ * Mirrors the codegen-v2 template style
+ * (`packages/js-bao/src/cli/v2/templates.ts`): total functions (no I/O, no
+ * hidden state), an auto-generated banner + fingerprint header, and
+ * deterministic ordering so `--check` can compare byte-for-byte.
+ *
+ * Diverges from codegen-v2 in two ways:
+ *   1. Database-DO records are schemaless documents, NOT `BaseModel` ORM
+ *      classes — so we emit plain `export interface` types with no class
+ *      shell, no barrel registration, and `import type` only.
+ *   2. We add an OPERATIONS half codegen-v2 has no analog for: per-op
+ *      input-params interfaces + per-op result aliases keyed off `op.type`.
+ */
+/** A field on a record interface (read shape). */
+export interface RecordField {
+    name: string;
+    /** TOML field type (`string|number|boolean|date|id|stringset`). */
+    type: string;
+    /** Required props render as `name: T`; otherwise `name?: T`. */
+    required: boolean;
+    /**
+     * Allowed-value set for a `string` field (#843). When non-empty, the field
+     * renders a TS string-literal union (`"a" | "b"`) instead of bare `string`.
+     */
+    enum?: string[];
+}
+export interface RenderRecordInterfaceInput {
+    /** PascalCase interface name (e.g. `Account`). */
+    interfaceName: string;
+    /** TOML model name (e.g. `accounts`). */
+    modelName: string;
+    fields: RecordField[];
+    /**
+     * Server-stamped field names (timestamps + auto-populated fields) that
+     * appear on the READ record interface as OPTIONAL props, and only if not
+     * already declared in `fields`.
+     */
+    stampedFields: string[];
+}
+/** One declared param on an op-input interface (write shape). */
+export interface ParamField {
+    name: string;
+    /** TOML param type (`string|number|boolean|object`). */
+    type: string;
+    required: boolean;
+    /**
+     * Allowed-value set for a `string` param → string-literal union (#861).
+     * Validated server-side (`validateParams`) at config-push time; the emitter
+     * renders the union when present and falls back to the base type otherwise.
+     */
+    enum?: string[];
+}
+export interface RenderOpParamsInterfaceInput {
+    /** PascalCase params interface name (e.g. `SaveAccountParams`). */
+    interfaceName: string;
+    /** Operation name (e.g. `saveAccount`). */
+    opName: string;
+    params: ParamField[];
+}
+export interface RenderOpResultAliasInput {
+    /** Per-op result alias name (e.g. `SaveAccountResult`). */
+    aliasName: string;
+    /** Operation name (e.g. `saveAccount`). */
+    opName: string;
+    /** Operation type (`query|mutation|count|aggregate|pipeline|applyToQuery`). */
+    opType: string;
+    /**
+     * For `query` ops, the record interface name the result is generic over
+     * (`QueryResult<Account>`). Null when the op's model has no record
+     * interface (e.g. pipeline) — falls back to `QueryResult<Record<string, unknown>>`.
+     */
+    recordInterfaceName: string | null;
+}
+/** The shared generic result aliases, keyed off `op.type`. */
+export declare const RESULT_ALIASES_BLOCK = "// Generic per-op result shapes, keyed off the operation type. The op\n// return contract is NOT stored in the TOML \u2014 these mirror the runtime\n// result shapes produced by the database-operations controller.\n\n/** `query` ops return a page of records. */\nexport interface QueryResult<T = Record<string, unknown>> {\n  data: T[];\n  hasMore?: boolean;\n  nextCursor?: string;\n}\n\n/** `mutation` ops return per-step results. */\nexport interface MutationResult {\n  results: unknown[];\n}\n\n/** `count` ops return a single count. */\nexport interface CountResult {\n  count: number;\n}\n\n/** `aggregate` ops return a single result object. */\nexport interface AggregateResult {\n  result: Record<string, unknown>;\n}\n\n/** `applyToQuery` ops return match/affect/fail counts. */\nexport interface ApplyToQueryResult {\n  matched: number;\n  affected: number;\n  failed: number;\n  sample?: unknown[];\n}\n\n/** `pipeline` ops return per-step results keyed by step name. */\nexport interface PipelineResult {\n  steps: Record<string, unknown>;\n}\n";
+/**
+ * Render the header (banner + regen hint + fingerprint).
+ */
+export declare function renderHeader(fingerprint: string): string;
+/**
+ * Render a single record interface (read shape). Stamped fields
+ * (`createdAt`, `modifiedAt`, `ownerId`, …) are appended as OPTIONAL props
+ * if not already present in `fields`.
+ */
+export declare function renderRecordInterface(input: RenderRecordInterfaceInput): string;
+/**
+ * Render a single op-input-params interface (write shape). `required: true`
+ * params are non-optional; others are optional. `object` params render as
+ * `Record<string, any>`.
+ */
+export declare function renderOpParamsInterface(input: RenderOpParamsInterfaceInput): string;
+/**
+ * Render a per-op result alias keyed off `op.type`.
+ */
+export declare function renderOpResultAlias(input: RenderOpResultAliasInput): string;