primitive-admin 1.0.60 → 1.0.62

package/dist/src/commands/databases.js

@@ -1,15 +1,19 @@
+import { Option } from "commander";
 import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, readdirSync } from "fs";
 import * as path from "path";
-import { parseConfigToml } from "../lib/config-toml.js";
 import { ApiClient } from "../lib/api-client.js";
 import { getCurrentAppId } from "../lib/config.js";
 import { resolveCodegenSourceDir } from "../lib/codegen-shared/resolveCodegenSourceDir.js";
+import { resolveSyncDirOverride } from "../lib/sync-dir-selector.js";
 import { parseCsv, applyColumnMap, buildRows } from "../lib/csv.js";
 import { chunk, parseBatchSize } from "../lib/batch.js";
 import { generateDbTypes, } from "../lib/db-codegen/dbGenerator.js";
 import { generateDbSwiftTypes } from "../lib/swift-codegen/dbGenerator.js";
 import { success, error, info, warn, keyValue, result as printResult, formatTable, formatId, formatDate, json, } from "../lib/output.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
+import { parseFilterOptions } from "../lib/record-filter.js";
+import { parseDataOption } from "../lib/data-input.js";
+import { ulid } from "ulid";
 function resolveAppId(appId, options) {
     const resolved = appId || options.app || getCurrentAppId();
     if (!resolved) {
@@ -18,6 +22,43 @@ function resolveAppId(appId, options) {
     }
     return resolved;
 }
+/**
+ * Render the flat `{ success, id, appliedFields }` response that
+ * `records/save` and `records/patch` return — these endpoints answer with a
+ * write receipt, not the stored record, so the human view shows the resolved id
+ * plus any server-applied fields (autoStamps / trigger-computed values).
+ */
+function renderRecordWriteResult(result, fallbackId, message) {
+    success(message);
+    keyValue("id", String(result?.id ?? fallbackId));
+    const applied = result?.appliedFields;
+    if (applied && typeof applied === "object" && Object.keys(applied).length > 0) {
+        for (const [key, value] of Object.entries(applied)) {
+            keyValue(`applied.${key}`, value === null || value === undefined ? "—" : String(value));
+        }
+    }
+}
+/**
+ * Refuse a write whose `--data` carries an `id` that is not the record being
+ * written. The server strips `id` from the record body on both the save and the
+ * patch path, so such an `id` would be dropped silently and the write would
+ * land on the id from the argument — somewhere the caller did not intend.
+ *
+ * `recordId` is the id the caller passed as an argument (absent on a `save`
+ * that mints one); `writtenId` is the id actually being written. Exits non-zero
+ * when they disagree with `--data` (#1965 review).
+ */
+function assertDataIdMatches(data, recordId, writtenId, commandPath) {
+    if (!data || typeof data !== "object")
+        return;
+    const dataId = data.id;
+    if (dataId === undefined || dataId === writtenId)
+        return;
+    error(recordId
+        ? `The "id" in --data ("${dataId}") does not match the record id "${recordId}". Remove it, or pass the id you mean as the argument.`
+        : `Pass the record id as the argument, not inside --data: ${commandPath} ${dataId} --data ...`);
+    process.exit(1);
+}
 /**
  * Validate that the named operation is an import-compatible, save-like
  * mutation before importing (issue #145, Codex finding (a)).
@@ -61,6 +102,95 @@ async function validateImportOperation(client, appId, databaseId, operationName)
         return;
     }
 }
+/**
+ * The full `databases records bulk` precondition value space, audited in one
+ * pass (issue #2437, Codex cycle 3). A precondition is field-equality only, so
+ * a value is one of: `null`, a boolean, a number, or a string. For each, what
+ * the DatabaseDO `condition` grammar can express, compared against the
+ * documents twin's strict JS equality (`evaluatePrecondition`):
+ *
+ * | Value             | Disposition | Why                                                                  |
+ * |-------------------|-------------|----------------------------------------------------------------------|
+ * | string            | round-trips | bound as TEXT; SQLite never equates TEXT with a number or a JSON bool |
+ * | number ≠ 0 and ≠1 | round-trips | bound as-is; no other JSON type extracts to that value                |
+ * | `null`            | rewritten   | paired with `$exists: true` so an absent key fails (cycle-2 fix)      |
+ * | `true` / `false`  | REJECTED    | bound as 1/0, and `json_extract` yields 1/0 for JSON booleans too     |
+ * | number 0 or 1     | REJECTED    | same collision seen from the other side: matches a stored `false`/`true` |
+ * | `{}` (no fields)  | see #2511   | sent as an empty `condition`, which the DO reads as "record must exist" |
+ * | object / array    | rejected    | not field-equality; rejected by the bulk validator before reaching here |
+ *
+ * The two REJECTED rows are the boolean/number collision: `JsonQueryTranslator`
+ * binds `true`/`false` as `1`/`0`, and SQLite's `json_extract` also returns a
+ * stored JSON boolean as `1`/`0`, so `{ enabled: true }` matches a record
+ * holding the number `1` and `{ retries: 1 }` matches a record holding `true`.
+ * The documents twin compares with `!==` and fails both. The `condition`
+ * grammar has no type predicate (`$exists` only distinguishes present from
+ * absent), so this cannot be translated exactly — the CLI rejects those values
+ * at the boundary instead, so the databases twin fails loudly rather than
+ * running with a weaker guard than the caller wrote. Issue #2507 tracks giving
+ * the grammar a type-aware equality, which would let these values be accepted.
+ *
+ * Returns an explanation when the value cannot be translated exactly, or
+ * `null` when it round-trips or is rewritten.
+ */
+export function untranslatablePreconditionValue(value) {
+    if (typeof value === "boolean") {
+        return (`a boolean precondition cannot be checked exactly on a database — the ` +
+            `record store compares JSON booleans as 1/0, so \`${value}\` would also ` +
+            `match a record holding the number ${value ? 1 : 0}`);
+    }
+    if (value === 0 || value === 1) {
+        return (`the number ${value} cannot be checked exactly on a database — the ` +
+            `record store compares JSON booleans as 1/0, so ${value} would also ` +
+            `match a record holding \`${value === 1}\``);
+    }
+    return null;
+}
+/**
+ * Translate a `databases records bulk` op's documents-surface `precondition`
+ * into the DatabaseDO's per-op `condition` (issue #2437). See
+ * {@link untranslatablePreconditionValue} for the audit of the whole value
+ * space; this function handles the one value that is REWRITTEN rather than
+ * passed through or rejected.
+ *
+ * The two are NOT the same grammar, and a straight hand-off silently weakens
+ * the guard for one value: `null`. A `condition` is a query filter, so
+ * `{ approvedAt: null }` translates to
+ * `json_extract(_data, '$.approvedAt') IS NULL` — which is also true when the
+ * key is ABSENT. A guarded patch/delete would then execute against a record
+ * that never had the field. The documents surface evaluates the same
+ * precondition in JS (`evaluatePrecondition` in `src/document-models.ts`): an
+ * absent field reads `undefined`, and `undefined !== null`, so the guard fails
+ * closed there.
+ *
+ * Pin the database side to the documents meaning — "the key is present AND
+ * holds null" — by pairing each null check with an existence constraint.
+ * `$exists: true` translates to `json_type(_data, '$.<field>') IS NOT NULL`,
+ * true for a key holding JSON null and false for an absent key, so the pair
+ * emits `json_extract(...) IS NULL AND json_type(...) IS NOT NULL`.
+ *
+ * Non-null scalars need no rewrite: `= ?` against `json_extract` already fails
+ * for an absent field, because NULL never equals a bound value.
+ *
+ * Assumes the caller has already rejected `$`-prefixed keys, non-scalar values,
+ * and the values {@link untranslatablePreconditionValue} names — which is what
+ * leaves `$and` free to use here and what makes a pass-through exact.
+ */
+export function preconditionToCondition(precondition) {
+    const nullFields = Object.keys(precondition).filter((f) => precondition[f] === null);
+    if (nullFields.length === 0)
+        return { ...precondition };
+    const condition = {};
+    for (const [field, expected] of Object.entries(precondition)) {
+        if (expected !== null)
+            condition[field] = expected;
+    }
+    condition.$and = nullFields.flatMap((field) => [
+        { [field]: null },
+        { [field]: { $exists: true } },
+    ]);
+    return condition;
+}
 export function registerDatabasesCommands(program) {
     const databases = program
         .command("databases")
@@ -68,11 +198,17 @@ export function registerDatabasesCommands(program) {
         .addHelpText("after", `
 Examples:
   $ primitive databases list
+  $ primitive databases list --owner <user-id>
   $ primitive databases create "My Database"
   $ primitive databases get <database-id>
   $ primitive databases records models <database-id>
   $ primitive databases records describe <database-id> <model-name>
   $ primitive databases records query <database-id> <model-name> --filter '{"name":"Alice"}'
+  $ primitive databases records get <database-id> <model-name> <record-id>
+  $ primitive databases records count <database-id> <model-name> --filter '{"status":"open"}'
+  $ primitive databases records aggregate <database-id> <model-name> --op avg --field price
+  $ primitive databases records save <database-id> <model-name> [record-id] --data '{"name":"Alice"}'
+  $ primitive databases records patch <database-id> <model-name> <record-id> --data '{"name":"Alice"}'
   $ primitive databases operations list <database-id>
   $ primitive databases operations execute <database-id> <operation-name> --params '{"key":"value"}'
   $ primitive databases indexes list <database-id>
@@ -80,13 +216,14 @@ Examples:
   $ primitive databases records delete <database-id> <model-name> <record-id> --yes
   $ primitive databases records delete-all <database-id> <model-name> --yes
   $ primitive databases records delete-all <database-id> <model-name> --filter '{"status":"draft"}' --yes
+  $ primitive databases records bulk <database-id> --data-file ops.json --yes
   $ primitive databases permissions list <database-id>
 
-Note: this group manages database *instances*. To manage database *type*
-configurations (schemas, rules, operations) — including deleting a type — use
-the 'database-types' group:
-  $ primitive database-types list
-  $ primitive database-types delete <database-type>   # refuses if instances exist; pass --force to override
+Note: this group manages database *instances*. Database *type* configurations
+(schemas, rules, operations) are authored in TOML — see 'primitive config fields
+database-type-config' and the 'database-type-configs' group for inspection:
+  $ primitive database-type-configs list
+  $ rm database-type-configs/<database-type>.toml && primitive config push --prune
 `);
     // List databases
     databases
@@ -94,12 +231,15 @@ the 'database-types' group:
         .description("List databases in an app")
         .argument("[app-id]", "App ID (uses current app if not specified)")
         .option("--app <app-id>", "App ID")
+        .option("--owner <user-id>", "Only list databases created by this user")
         .option("--json", "Output as JSON")
         .action(async (appId, options) => {
         const resolvedAppId = resolveAppId(appId, options);
         const client = new ApiClient();
         try {
-            const result = await client.listDatabases(resolvedAppId);
+            const result = await client.listDatabases(resolvedAppId, {
+                owner: options.owner,
+            });
             const list = Array.isArray(result) ? result : result?.databases ?? [];
             if (options.json) {
                 json(list);
@@ -114,6 +254,18 @@ the 'database-types' group:
                 { header: "TITLE", key: "title" },
                 { header: "TYPE", key: "databaseType", format: (v) => v || "—" },
                 { header: "PERMISSION", key: "permission" },
+                // `permission` reads "owner" on every row for an app admin, so it
+                // cannot confirm --owner narrowed anything. Show who created each
+                // database when the filter is in play.
+                ...(options.owner
+                    ? [
+                        {
+                            header: "CREATED BY",
+                            key: "createdBy",
+                            format: (v) => (v ? formatId(v) : "—"),
+                        },
+                    ]
+                    : []),
                 { header: "CREATED", key: "createdAt", format: formatDate },
             ]));
         }
@@ -465,7 +617,7 @@ the 'database-types' group:
             process.exit(1);
         }
     });
-    // Query records (direct introspection via admin-data route)
+    // Query records (direct introspection via the records route)
     records
         .command("query")
         .description("Query records in a database model (admin only)")
@@ -480,43 +632,14 @@ the 'database-types' group:
         .action(async (databaseId, modelName, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
-        if (options.filter && options.filterFile) {
-            error("Cannot use both --filter and --filter-file.");
-            process.exit(1);
-        }
-        let filter;
-        if (options.filterFile) {
-            try {
-                const content = readFileSync(options.filterFile, "utf-8");
-                if (options.filterFile.endsWith(".toml")) {
-                    const parsed = parseConfigToml(content);
-                    filter = parsed.filter || parsed;
-                }
-                else {
-                    filter = JSON.parse(content);
-                }
-            }
-            catch (err) {
-                error(`Failed to read filter file: ${err.message}`);
-                process.exit(1);
-            }
-        }
-        else if (options.filter) {
-            try {
-                filter = JSON.parse(options.filter);
-            }
-            catch {
-                error("Invalid --filter JSON.");
-                process.exit(1);
-            }
-        }
+        const filter = parseFilterOptions(options);
         try {
             const result = await client.queryDatabaseRecords(resolvedAppId, databaseId, modelName, { filter, limit: options.limit, cursor: options.cursor });
             if (options.json) {
                 json(result);
                 return;
             }
-            const records = result.data || [];
+            const records = result.items;
             if (records.length === 0) {
                 info("No records found.");
                 return;
@@ -560,6 +683,228 @@ the 'database-types' group:
             process.exit(1);
         }
     });
+    // Get a single record by id
+    records
+        .command("get")
+        .description("Get a single record by id (admin only)")
+        .argument("<database-id>", "Database ID")
+        .argument("<model-name>", "Model name")
+        .argument("<record-id>", "Record ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (databaseId, modelName, recordId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            // A single-record fetch is a query filtered by primary-key id (there is
+            // no dedicated get endpoint — reuse queryDatabaseRecords).
+            const result = await client.queryDatabaseRecords(resolvedAppId, databaseId, modelName, { filter: { id: recordId }, limit: 1 });
+            const record = result.items[0];
+            if (options.json) {
+                json(record ?? null);
+                return;
+            }
+            if (!record) {
+                info(`No record found with id ${recordId} in ${modelName}.`);
+                return;
+            }
+            // `get` is a data command, so its fields go to stdout via `result()`
+            // — the #711 split (`result()` = the data the caller asked for,
+            // `keyValue()` = a post-action diagnostic summary). Issue #2437; the
+            // documents twin renders identically.
+            for (const [key, value] of Object.entries(record)) {
+                const rendered = value === null || value === undefined
+                    ? "—"
+                    : typeof value === "object"
+                        ? JSON.stringify(value)
+                        : String(value);
+                printResult(key, rendered);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Count records
+    records
+        .command("count")
+        .description("Count records in a database model (admin only)")
+        .argument("<database-id>", "Database ID")
+        .argument("<model-name>", "Model name")
+        .option("--app <app-id>", "App ID")
+        .option("--filter <json>", "Filter as JSON (e.g. '{\"name\":\"Alice\"}')")
+        .option("--filter-file <path>", "Read filter from a JSON or TOML file")
+        .option("--json", "Output as JSON")
+        .action(async (databaseId, modelName, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const filter = parseFilterOptions(options);
+        const client = new ApiClient();
+        try {
+            const result = await client.countDatabaseRecords(resolvedAppId, databaseId, modelName, filter);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            keyValue("count", String(result?.count ?? 0));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Aggregate records
+    const AGGREGATE_OPS = ["count", "sum", "avg", "min", "max"];
+    records
+        .command("aggregate")
+        .description("Aggregate records in a database model (count/sum/avg/min/max, optional group-by; admin only)")
+        .argument("<database-id>", "Database ID")
+        .argument("<model-name>", "Model name")
+        .option("--app <app-id>", "App ID")
+        .requiredOption("--op <operation>", `Aggregate operation: ${AGGREGATE_OPS.join("|")}`)
+        .option("--field <field>", "Field to aggregate (required for sum/avg/min/max)")
+        .option("--group-by <field>", "Group results by this field (repeatable)", (value, previous = []) => previous.concat(value), [])
+        .option("--filter <json>", "Filter as JSON")
+        .option("--filter-file <path>", "Read filter from a JSON or TOML file")
+        .option("--json", "Output as JSON")
+        .action(async (databaseId, modelName, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!AGGREGATE_OPS.includes(options.op)) {
+            error(`Invalid --op "${options.op}". Expected one of: ${AGGREGATE_OPS.join(", ")}.`);
+            process.exit(1);
+        }
+        const operation = { type: options.op };
+        if (options.op === "count") {
+            if (options.field) {
+                error("--field is not valid for --op count.");
+                process.exit(1);
+            }
+        }
+        else {
+            if (!options.field) {
+                error(`--op ${options.op} requires --field.`);
+                process.exit(1);
+            }
+            operation.field = options.field;
+        }
+        const filter = parseFilterOptions(options);
+        const groupBy = options.groupBy || [];
+        const client = new ApiClient();
+        try {
+            const result = await client.aggregateDatabaseRecords(resolvedAppId, databaseId, modelName, { operations: [operation], groupBy, filter });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            const aggregated = result?.result;
+            // Label the value column after the operation, including the field it
+            // ran over: `SUM` alone does not say what was summed. The field name is
+            // reproduced verbatim in both labels — it is a user-supplied
+            // identifier, and case-folding it produced `avg(lastvalue)` for
+            // `--field lastValue` (issue #2357).
+            const valueLabel = options.op === "count"
+                ? "COUNT"
+                : `${options.op.toUpperCase()}(${options.field})`;
+            const scalarLabel = options.op === "count"
+                ? "count"
+                : `${options.op.toLowerCase()}(${options.field})`;
+            if (groupBy.length === 0) {
+                // Ungrouped: one scalar per operation, keyed by the endpoint's
+                // operation name (`count`, `sum_<field>`, …). Render it as a
+                // key/value line — there is no group column to table.
+                const value = (aggregated ?? {})[options.op === "count" ? "count" : `${options.op}_${options.field}`];
+                keyValue(scalarLabel, value === null || value === undefined ? "—" : String(value));
+                return;
+            }
+            if (aggregated &&
+                typeof aggregated === "object" &&
+                !Array.isArray(aggregated) &&
+                Object.values(aggregated).every((v) => typeof v !== "object" || v === null)) {
+                // Flat { group -> value } shape (single operation, single group-by): render a table.
+                const rows = Object.entries(aggregated).map(([group, value]) => ({
+                    group,
+                    value: value === null || value === undefined ? "—" : String(value),
+                }));
+                console.log(formatTable(rows, [
+                    { header: "GROUP", key: "group" },
+                    { header: valueLabel, key: "value" },
+                ]));
+            }
+            else {
+                // Grouped/nested or multi-operation shape: print the structured result.
+                console.log(JSON.stringify(aggregated ?? {}, null, 2));
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Upsert a record (create, or merge into an existing one)
+    records
+        .command("save")
+        .description("Create a record, or merge fields into an existing one (admin only)")
+        .argument("<database-id>", "Database ID")
+        .argument("<model-name>", "Model name")
+        .argument("[record-id]", "Record ID (generated when omitted)")
+        .option("--app <app-id>", "App ID")
+        .option("--data <json>", "Record fields as inline JSON")
+        .option("--data-file <path>", "Read the record fields from a JSON file")
+        .option("--json", "Output as JSON")
+        .action(async (databaseId, modelName, recordId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const data = parseDataOption(options, "record");
+        const client = new ApiClient();
+        // The DatabaseDO requires an id on the plain save path (it only generates
+        // one for `upsertOn` writes). Mint the id client-side for a create so
+        // `save` works without an id, the same way CSV import does
+        // (`lib/csv.ts`).
+        const id = recordId || ulid();
+        assertDataIdMatches(data, recordId, id, "primitive databases records save <database-id> <model-name>");
+        try {
+            const result = await client.saveDatabaseRecord(resolvedAppId, databaseId, modelName, id, data);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            renderRecordWriteResult(result, id, `Record saved to ${modelName}.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Patch a record (partial merge)
+    records
+        .command("patch")
+        .description("Merge fields into an existing record (admin only)")
+        .argument("<database-id>", "Database ID")
+        .argument("<model-name>", "Model name")
+        .argument("<record-id>", "Record ID")
+        .option("--app <app-id>", "App ID")
+        .option("--data <json>", "Fields to merge as inline JSON")
+        .option("--data-file <path>", "Read the fields to merge from a JSON file")
+        .option("--json", "Output as JSON")
+        .action(async (databaseId, modelName, recordId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const data = parseDataOption(options, "fields to merge");
+        const client = new ApiClient();
+        // Same guard as `save` — on this path `recordId` is required, so the
+        // "pass it as the argument" branch is unreachable here.
+        assertDataIdMatches(data, recordId, recordId, "primitive databases records patch <database-id> <model-name>");
+        try {
+            const result = await client.patchDatabaseRecord(resolvedAppId, databaseId, modelName, recordId, data);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            renderRecordWriteResult(result, recordId, `Record ${recordId} patched in ${modelName}.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
     // Delete a single record
     records
         .command("delete")
@@ -608,21 +953,13 @@ the 'database-types' group:
         .argument("<model-name>", "Model name")
         .option("--app <app-id>", "App ID")
         .option("--filter <json>", "Filter as JSON to select which records to delete")
+        .option("--filter-file <path>", "Read filter from a JSON or TOML file")
         .option("-y, --yes", "Skip confirmation prompt")
         .option("--json", "Output as JSON")
         .action(async (databaseId, modelName, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
-        let filter;
-        if (options.filter) {
-            try {
-                filter = JSON.parse(options.filter);
-            }
-            catch {
-                error("Invalid --filter JSON.");
-                process.exit(1);
-            }
-        }
+        const filter = parseFilterOptions(options);
         try {
             // First, query to find all matching records
             let allRecords = [];
@@ -630,9 +967,9 @@ the 'database-types' group:
             let hasMore = true;
             while (hasMore) {
                 const result = await client.queryDatabaseRecords(resolvedAppId, databaseId, modelName, { filter, limit: 100, cursor });
-                const records = result?.data || [];
+                const records = result.items;
                 allRecords = allRecords.concat(records);
-                cursor = result?.nextCursor;
+                cursor = result.nextCursor;
                 hasMore = !!cursor && records.length > 0;
             }
             if (allRecords.length === 0) {
@@ -681,6 +1018,206 @@ the 'database-types' group:
             process.exit(1);
         }
     });
+    // Apply an atomic multi-model operations blob (issue #2437).
+    //
+    // Takes the SAME `--data-file` blob as `documents records bulk` — one file
+    // works against either surface — and translates it to the DatabaseDO's
+    // `records/batch` wire shape (`{ op, modelName, id, data }`) with
+    // `atomic: true`, so the whole blob is all-or-nothing like the documents
+    // twin. Both guards the documents blob can carry survive the translation:
+    // `action: create` maps to `save` with `ifNotExists: true` (the DatabaseDO's
+    // strict-create flag, a 409 `ALREADY_EXISTS` inside the transaction), and an
+    // op's `precondition` maps to the DO's per-op `condition` (a 409
+    // `CONDITION_NOT_MET`). Both abort the whole batch, matching the documents
+    // twin.
+    const BULK_ACTIONS = ["create", "patch", "delete"];
+    const BULK_ACTION_TO_OP = {
+        create: "save",
+        patch: "patch",
+        delete: "delete",
+    };
+    // Mirrors the documents surface's `BULK_WRITE_OP_KEYS` / `BULK_DELETE_OP_KEYS`
+    // (`src/document-models.ts`). Unknown keys are an error rather than ignored:
+    // a guard the author asked for must never be dropped silently.
+    const BULK_OP_KEYS = ["model", "action", "id", "data", "precondition"];
+    const BULK_DELETE_OP_KEYS = ["model", "action", "id", "precondition"];
+    records
+        .command("bulk")
+        .description("Apply an atomic create/patch/delete operations blob to a database (admin only)")
+        .argument("<database-id>", "Database ID")
+        .requiredOption("--data-file <file>", "JSON file with { operations: [...] } or a bare operations array. " +
+        "Each op is { model, action: create|patch|delete, id, data, precondition? } " +
+        "— the same shape `documents records bulk` takes. `data` holds the " +
+        "record fields and is required on create/patch, not allowed on delete. " +
+        "A `create` against an id that already exists fails the whole batch, " +
+        "and a `precondition` that does not hold rolls the whole batch back")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (databaseId, options) => {
+        const parsed = parseDataOption(options, "operations blob", {
+            allowArray: true,
+        });
+        const rawOperations = Array.isArray(parsed) ? parsed : parsed?.operations;
+        if (!Array.isArray(rawOperations) || rawOperations.length === 0) {
+            error("--data-file must contain { operations: [...] } or a non-empty operations array.");
+            process.exit(1);
+        }
+        // Translate to the batch wire shape, rejecting a malformed op before any
+        // request goes out so the caller sees which entry is wrong.
+        const operations = [];
+        for (let i = 0; i < rawOperations.length; i++) {
+            const op = rawOperations[i];
+            if (!op || typeof op !== "object" || Array.isArray(op)) {
+                error(`Operation ${i}: each operation must be a JSON object.`);
+                process.exit(1);
+            }
+            const action = op.action;
+            if (!BULK_ACTIONS.includes(action)) {
+                error(`Operation ${i}: invalid action "${action}". Expected one of: ${BULK_ACTIONS.join(", ")}.`);
+                process.exit(1);
+            }
+            if (!op.model || typeof op.model !== "string") {
+                error(`Operation ${i}: "model" is required and must be a model name.`);
+                process.exit(1);
+            }
+            if (!op.id || typeof op.id !== "string") {
+                error(`Operation ${i}: "id" is required.`);
+                process.exit(1);
+            }
+            // `data` on a delete gets its own message before the allowlist runs, so
+            // the caller is not told a first-class key is "unknown".
+            if (action === "delete" && op.data !== undefined) {
+                error(`Operation ${i}: "data" is not allowed on a delete.`);
+                process.exit(1);
+            }
+            const allowedKeys = action === "delete" ? BULK_DELETE_OP_KEYS : BULK_OP_KEYS;
+            const unknownKey = Object.keys(op).find((k) => !allowedKeys.includes(k));
+            if (unknownKey) {
+                error(`Operation ${i}: unknown key "${unknownKey}". Expected one of: ${allowedKeys.join(", ")}.`);
+                process.exit(1);
+            }
+            // A `precondition` is field-equality only, the same grammar the
+            // documents surface enforces (`validatePrecondition` in
+            // `src/document-models.ts`), so one blob means the same thing on both.
+            // `preconditionToCondition` translates it to the DO's per-op
+            // `condition`, checked inside the transaction: a mismatch is a 409 that
+            // rolls the whole batch back.
+            let condition;
+            if (op.precondition !== undefined && op.precondition !== null) {
+                if (typeof op.precondition !== "object" || Array.isArray(op.precondition)) {
+                    error(`Operation ${i}: "precondition" must be a field-equality object ({ field: scalar, … }).`);
+                    process.exit(1);
+                }
+                for (const [field, expected] of Object.entries(op.precondition)) {
+                    if (field.startsWith("$")) {
+                        error(`Operation ${i}: precondition operator "${field}" is not supported — preconditions are field-equality only ({ field: scalar, … }).`);
+                        process.exit(1);
+                    }
+                    if (expected !== null && typeof expected === "object") {
+                        error(`Operation ${i}: precondition on field "${field}" must be a scalar equality value — operators and nested objects/arrays are not supported.`);
+                        process.exit(1);
+                    }
+                    // Fail loudly on the values the `condition` grammar cannot check
+                    // exactly, rather than running with a weaker guard than the caller
+                    // wrote (issue #2437; the grammar fix is tracked in #2507).
+                    const untranslatable = untranslatablePreconditionValue(expected);
+                    if (untranslatable) {
+                        error(`Operation ${i}: precondition on field "${field}" is not supported — ${untranslatable}. ` +
+                            `Guard on a field whose value is a string or a number other than 0/1, or read the record ` +
+                            `first and gate the write on that.`);
+                        process.exit(1);
+                    }
+                }
+                condition = preconditionToCondition(op.precondition);
+            }
+            if (action === "delete") {
+                if (op.data !== undefined) {
+                    error(`Operation ${i}: "data" is not allowed on a delete.`);
+                    process.exit(1);
+                }
+                operations.push({
+                    op: "delete",
+                    modelName: op.model,
+                    id: op.id,
+                    ...(condition ? { condition } : {}),
+                });
+                continue;
+            }
+            if (!op.data ||
+                typeof op.data !== "object" ||
+                Array.isArray(op.data) ||
+                Object.keys(op.data).length === 0) {
+                error(`Operation ${i}: "data" is required and must be a non-empty object on a ${action}.`);
+                process.exit(1);
+            }
+            operations.push({
+                op: BULK_ACTION_TO_OP[action],
+                modelName: op.model,
+                id: op.id,
+                data: op.data,
+                // `create` is a STRICT create on both twins: `ifNotExists` is the
+                // DatabaseDO batch's strict-create flag (409 `ALREADY_EXISTS`), so a
+                // create against a live id fails the batch instead of merging.
+                ...(action === "create" ? { ifNotExists: true } : {}),
+                ...(condition ? { condition } : {}),
+            });
+        }
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Apply ${operations.length} operation(s) atomically to database ${databaseId}?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirm) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            await client.batchDatabaseRecords(resolvedAppId, databaseId, operations, {
+                atomic: true,
+            });
+            // The batch endpoint answers with a per-operation `results` array; the
+            // documents twin answers with a rolled-up summary. Report the twin's
+            // summary so one blob produces one contract on both surfaces — the
+            // batch is atomic, so a 2xx means every op in the input applied.
+            //
+            // One reporting difference, documented alongside the verb: the
+            // documents twin's `deleted` counts records actually removed, because
+            // its DO reports that. The database batch issues a plain DELETE and
+            // reports no rows-affected, so `deleted` here counts delete operations
+            // applied — deleting an id that was not there still counts 1.
+            const added = rawOperations
+                .filter((op) => op.action === "create")
+                .map((op) => ({ model: op.model, id: op.id }));
+            const updated = rawOperations
+                .filter((op) => op.action === "patch")
+                .map((op) => ({ model: op.model, id: op.id }));
+            const deleted = rawOperations.filter((op) => op.action === "delete").length;
+            const summary = {
+                applied: added.length + updated.length + deleted,
+                added,
+                updated,
+                deleted,
+            };
+            if (options.json) {
+                json(summary);
+                return;
+            }
+            success(`Applied ${summary.applied} operation(s): ` +
+                `${added.length} added, ${updated.length} updated, ${deleted} deleted.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
     // ---- CEL context subcommand group ----
     // `cel-context` is the user-facing name for the dict that feeds CEL
     // access rules and filter placeholders. `metadata` is kept as a hidden
@@ -837,14 +1374,17 @@ the 'database-types' group:
                 json(result);
                 return;
             }
-            // Smart display based on result shape
-            if (result.data && Array.isArray(result.data)) {
-                if (result.data.length === 0) {
+            // Smart display based on result shape. `executeDatabaseOperation()`
+            // has already normalized a query page to `{ items, hasMore,
+            // nextCursor? }` (#2440), so `items` is exactly "this result was a
+            // list" — the two branches cannot disagree about it.
+            if (Array.isArray(result.items)) {
+                if (result.items.length === 0) {
                     info("No records found.");
                 }
                 else {
-                    const cols = Object.keys(result.data[0]).filter((k) => k !== "type");
-                    console.log(formatTable(result.data, cols.map((c) => ({
+                    const cols = Object.keys(result.items[0]).filter((k) => k !== "type");
+                    console.log(formatTable(result.items, cols.map((c) => ({
                         header: c.toUpperCase(),
                         key: c,
                         format: (v) => {
@@ -859,8 +1399,10 @@ the 'database-types' group:
                         },
                     }))));
                 }
-                if (result.hasMore) {
-                    info(`More records available. Use --cursor ${result.cursor} to continue.`);
+                // Gate on the cursor itself, the way `records query` does: `hasMore`
+                // without a cursor used to print the literal `undefined` (#2440).
+                if (result.nextCursor) {
+                    info(`More records available. Use --cursor ${result.nextCursor} to continue.`);
                 }
             }
             else if (result.count !== undefined) {
@@ -1094,7 +1636,7 @@ the 'database-types' group:
         }
         // Validate --batch-size up front so a bad value fails before any write.
         // Unlike `import-csv` (registered-batch path, hard 100k server cap),
-        // `admin-data/batch` has no fixed server item cap — bound it with a
+        // `records/batch` has no fixed server item cap — bound it with a
         // conservative client-side ceiling to keep each request within
         // Cloudflare body-size and Durable Object memory limits.
         const parsedBatchSize = parseBatchSize(options.batchSize, {
@@ -1368,13 +1910,17 @@ the 'database-types' group:
         .description("Manage the TOML schema attached to a database type");
     schema
         .command("generate")
-        .description("Scaffold a starting TOML schema for <database-type> from existing operations + DO introspection, and insert it into the local database-types/<type>.toml file.")
+        .description("Scaffold a starting TOML schema for <database-type> from existing operations + DO introspection, and insert it into the local database-type-configs/<type>.toml file.")
         .argument("<database-type>", "Database type name")
         .option("--app <app-id>", "App ID")
-        .option("--sync-dir <path>", "Override path to the sync directory (defaults to ./.primitive/sync/<env>/<appId>/)")
+        .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
+        .addOption(new Option("--sync-dir <path>", "Deprecated alias of --dir").hideHelp())
         .option("-f, --force", "Overwrite an existing [models.*] block in the local file")
         .option("--json", "Output the generated TOML as JSON")
         .action(async (databaseType, options) => {
+        // Resolve the sync-dir override before the API call, so a caller who
+        // passed both spellings hears about it without a network round trip.
+        const configDir = resolveSyncDirOverride(options, "databases schema generate");
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
@@ -1385,14 +1931,14 @@ the 'database-types' group:
                 json({ schema: scaffoldedToml });
                 return;
             }
-            // 2. Locate the local `database-types/<type>.toml` file. Per the
+            // 2. Locate the local `database-type-configs/<type>.toml` file. Per the
             // plan-of-record CLI sync layout, the file lives at
-            // `<sync-dir>/database-types/<type>.toml`. We don't need to know the
-            // exact sync dir for the happy path — just look for an existing
+            // `<config-dir>/database-type-configs/<type>.toml`. We don't need to know
+            // the exact config dir for the happy path — just look for an existing
             // file relative to the CWD's `.primitive/sync/` directory tree.
             const candidateFiles = [];
-            if (options.syncDir) {
-                candidateFiles.push(path.join(options.syncDir, "database-types", `${databaseType}.toml`));
+            if (configDir) {
+                candidateFiles.push(path.join(configDir, "database-type-configs", `${databaseType}.toml`));
             }
             else {
                 // Search any env/appId subtree under .primitive/sync that matches.
@@ -1402,7 +1948,7 @@ the 'database-types' group:
                         const envDir = path.join(root, env);
                         try {
                             for (const app of readdirSync(envDir)) {
-                                const candidate = path.join(envDir, app, "database-types", `${databaseType}.toml`);
+                                const candidate = path.join(envDir, app, "database-type-configs", `${databaseType}.toml`);
                                 if (existsSync(candidate)) {
                                     candidateFiles.push(candidate);
                                 }
@@ -1417,7 +1963,7 @@ the 'database-types' group:
             if (candidateFiles.length === 0) {
                 // No local file found — print the scaffold to stdout and tell
                 // the user where to put it.
-                info(`No local database-types/${databaseType}.toml found under .primitive/sync/. Generated TOML:`);
+                info(`No local database-type-configs/${databaseType}.toml found under .primitive/sync/. Generated TOML:`);
                 console.log("");
                 console.log(scaffoldedToml);
                 return;
@@ -1457,7 +2003,7 @@ the 'database-types' group:
                 writeFileSync(targetPath, merged);
                 success(`Inserted schema into ${targetPath}`);
             }
-            info("Review the generated schema, fix types the generator guessed wrong, then run `primitive sync push` (or `primitive sync push --dry-run`).");
+            info("Review the generated schema, fix types the generator guessed wrong, then run `primitive config push` (or `primitive config push --dry-run`).");
         }
         catch (err) {
             error(err.message);
@@ -1469,11 +2015,12 @@ the 'database-types' group:
     // ============================================
     databases
         .command("codegen")
-        .description("Generate record + operation types from the local database-types/*.toml schema. TypeScript (default): a <type>.generated.ts per database type (record interfaces, per-op input-params interfaces, per-op result aliases, and a typed <type>Ops factory). Swift (--lang swift): a <type>.generated.swift per database type (record structs, per-op params structs, per-op result typealiases, and a typed <Type>Ops factory).\n\nFormatting: the emitted TypeScript is already formatted the way Prettier's DEFAULT config formats it, so a `codegen` -> `prettier --write` -> `codegen --check` pipeline stays green. If your project uses a NON-default Prettier config (a different printWidth, trailingComma, or quote style), Prettier will reformat the generated files and `--check` will then fail: add the generated directory to `.prettierignore` and commit the raw emission instead.")
-        .argument("[database-type]", "Generate for a single database type (defaults to every database-types/*.toml found)")
+        .description("Generate record + operation types from the local database-type-configs/*.toml schema. TypeScript (default): a <type>.generated.ts per database type (record interfaces, per-op input-params interfaces, per-op result aliases, and a typed <type>Ops factory). Swift (--lang swift): a <type>.generated.swift per database type (record structs, per-op params structs, per-op result typealiases, and a typed <Type>Ops factory).\n\nFormatting: the emitted TypeScript is already formatted the way Prettier's DEFAULT config formats it, so a `codegen` -> `prettier --write` -> `codegen --check` pipeline stays green. If your project uses a NON-default Prettier config (a different printWidth, trailingComma, or quote style), Prettier will reformat the generated files and `--check` will then fail: add the generated directory to `.prettierignore` and commit the raw emission instead.")
+        .argument("[database-type]", "Generate for a single database type (defaults to every database-type-configs/*.toml found)")
         .option("--app <app-id>", "App ID")
-        .option("--sync-dir <path>", "Override path to the sync directory (defaults to ./.primitive/sync/<env>/<appId>/)")
-        .option("-o, --output <dir>", "Output directory for the generated files (defaults to <sync-dir>/database-types/generated/)")
+        .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
+        .addOption(new Option("--sync-dir <path>", "Deprecated alias of --dir").hideHelp())
+        .option("-o, --output <dir>", "Output directory for the generated files (defaults to <config-dir>/database-type-configs/generated/)")
         .option("--lang <lang>", "Target language for the generated types: 'ts' (default) or 'swift'.", "ts")
         .option("--check", "Exit non-zero if generated output is out of date (CI guard); does not write. Compares byte-for-byte, so the file on disk must match the emission exactly.")
         .option("--json", "Output the result summary as JSON")
@@ -1486,14 +2033,17 @@ the 'database-types' group:
                 error(`Unknown --lang "${options.lang}". Use "ts" or "swift".`);
                 process.exit(1);
             }
-            // 1. Resolve the single source database-types/ directory via the
+            // 1. Resolve the single source database-type-configs/ directory via the
             //    shared active-environment resolver (issue #1510). Honors
-            //    --sync-dir / --app overrides and resolves the active env
+            //    --dir / --app overrides and resolves the active env
             //    (--env → PRIMITIVE_ENV → defaultEnvironment → single-env) instead
             //    of silently merging types across every synced env.
             const dbTypesSourceDir = resolveCodegenSourceDir({
-                subdir: "database-types",
-                options: { app: options.app, syncDir: options.syncDir },
+                subdir: "database-type-configs",
+                options: {
+                    app: options.app,
+                    syncDir: resolveSyncDirOverride(options, "databases codegen"),
+                },
             });
             // 2. Collect the source .toml files (one per database type), filtered
             //    to a single type when an argument is given.
@@ -1513,8 +2063,8 @@ the 'database-types' group:
             }
             if (inputs.length === 0) {
                 error(databaseType
-                    ? `No database-types/${databaseType}.toml found under .primitive/sync/.`
-                    : "No database-types/*.toml files found to generate from.");
+                    ? `No database-type-configs/${databaseType}.toml found under .primitive/sync/.`
+                    : "No database-type-configs/*.toml files found to generate from.");
                 process.exit(1);
             }
             // 3. Resolve the output directory. Default: a `generated/` subdir of
@@ -1552,9 +2102,21 @@ the 'database-types' group:
                         for (const m of codegenResult.mismatches) {
                             error(`  ${m.reason}: ${path.relative(process.cwd(), m.filePath)}`);
                         }
-                        info(lang === "swift"
-                            ? "Run `primitive databases codegen --lang swift` to regenerate."
-                            : "Run `primitive databases codegen` to regenerate.");
+                        // Echo back the options that decide WHERE and WHAT was
+                        // checked, the way `workflows codegen` does (#2895). Suggesting
+                        // a bare `databases codegen` after a `--check -o <dir>` sent
+                        // people to regenerate into the default
+                        // <config-dir>/database-type-configs/generated/ instead of the
+                        // directory that is actually out of date, so the files stayed
+                        // stale and the next check failed the same way (#2911).
+                        const regenerate = ["primitive databases codegen"];
+                        if (databaseType)
+                            regenerate.push(databaseType);
+                        if (lang === "swift")
+                            regenerate.push("--lang swift");
+                        if (options.output)
+                            regenerate.push(`-o ${options.output}`);
+                        info(`Run \`${regenerate.join(" ")}\` to regenerate.`);
                     }
                     process.exit(1);
                 }
@@ -1620,7 +2182,7 @@ async function exportSingleDatabase(client, appId, databaseId, outputDir, jsonOu
     const dbMeta = await client.getDatabase(appId, databaseId);
     // Warn about databaseType sync
     if (dbMeta.databaseType) {
-        warn(`This database uses type "${dbMeta.databaseType}". Make sure to \`primitive sync push\` the type config before importing into a new app.`);
+        warn(`This database uses type "${dbMeta.databaseType}". Make sure to \`primitive config push\` the type config before importing into a new app.`);
     }
     // 2. Write metadata
     const metadata = {
@@ -1648,13 +2210,13 @@ async function exportSingleDatabase(client, appId, databaseId, outputDir, jsonOu
                 limit: 100,
                 cursor,
             });
-            const records = result?.data || [];
+            const records = result.items;
             for (const record of records) {
                 const line = JSON.stringify({ _type: modelName, _id: record.id, _data: record });
                 appendFileSync(recordsFile, line + "\n");
                 totalRecords++;
             }
-            cursor = result?.nextCursor;
+            cursor = result.nextCursor;
             hasMore = !!cursor && records.length > 0;
         }
     }
@@ -1685,7 +2247,7 @@ async function exportSingleDatabase(client, appId, databaseId, outputDir, jsonOu
 }
 /**
  * Conservative client-side ceiling for `databases import --batch-size`.
- * `admin-data/batch` has no fixed server-side item cap (unlike the
+ * `records/batch` has no fixed server-side item cap (unlike the
  * registered-batch path used by `import-csv`), so this bounds each request to
  * keep it within Cloudflare body-size and Durable Object memory limits.
  */
@@ -1713,7 +2275,7 @@ async function importSingleDatabase(client, appId, dbDir, options) {
     }
     // Check if database type exists — warn if not
     if (metadata.databaseType) {
-        warn(`Database uses type "${metadata.databaseType}". Ensure the type config exists in the target app (use \`primitive sync push\`).`);
+        warn(`Database uses type "${metadata.databaseType}". Ensure the type config exists in the target app (use \`primitive config push\`).`);
     }
     // Check if database exists — use the original ID for overwrite scenarios
     let targetDatabaseId = databaseId;