primitive-admin 1.0.61 → 1.0.63

package/dist/src/commands/documents.js

@@ -1,18 +1,880 @@
 import { ApiClient } from "../lib/api-client.js";
 import { resolveAppId } from "../lib/config.js";
-import { success, error, info, formatTable, formatDate, json, keyValue, warn, } from "../lib/output.js";
+import { success, error, info, formatTable, formatId, formatDate, json, keyValue, result as printResult, warn, } from "../lib/output.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
+import { parseDataOption } from "../lib/data-input.js";
+import { parseFilterOptions } from "../lib/record-filter.js";
+import { ulid } from "ulid";
 import * as fs from "fs";
 import * as path from "path";
+/**
+ * Resolve a `--owner` value to a userId. A value containing "@" is looked up
+ * by exact email through the member-accessible `users/lookup` endpoint
+ * (issue #2763); anything else is already a user id and is passed through.
+ * Failures throw with the server's own message — a permission problem must
+ * not read as "no such user", which is how the old admin-only lookup
+ * reported it.
+ */
+async function resolveOwnerUserId(client, appId, owner) {
+    if (!owner.includes("@"))
+        return owner;
+    const lookup = await client.lookupUserByEmail(appId, owner);
+    if (!lookup?.exists || !lookup.user) {
+        throw new Error(`No app user found with email "${owner}" in app ${appId}.`);
+    }
+    info(`Resolved owner email to userId: ${lookup.user.userId}`);
+    return lookup.user.userId;
+}
 export function registerDocumentsCommands(program) {
     const documents = program
         .command("documents")
         .description("Manage documents within an app")
         .addHelpText("after", `
 Examples:
+  $ primitive documents list --user-id <user-id>
+  $ primitive documents get <document-id>
+  $ primitive documents create "My Doc"
+  $ primitive documents create "My Doc" --owner user@example.com
+  $ primitive documents delete <document-id> -y
+  $ primitive documents permissions list <document-id>
+  $ primitive documents permissions grant <document-id> --user-id <user-id> --permission reader
+  $ primitive documents permissions revoke <document-id> <user-id>
+  $ primitive documents records models <document-id>
+  $ primitive documents records describe <document-id> <model-name>
+  $ primitive documents records query <document-id> <model-name> --filter '{"status":"open"}'
+  $ primitive documents records count <document-id> <model-name>
+  $ primitive documents records save <document-id> <model-name> --data '{"qty":10}'
+  $ primitive documents records patch <document-id> <model-name> <record-id> --data '{"qty":11}'
+  $ primitive documents records delete <document-id> <model-name> <record-id> -y
+  $ primitive documents records aggregate <document-id> <model-name> --op avg --field price
+  $ primitive documents records bulk <document-id> --data-file ops.json -y
+  $ primitive documents dump <document-id>
+  $ primitive documents stats <document-id>
   $ primitive documents transfer-owner <document-id> <new-owner-id>
   $ primitive documents group-permissions list <document-id>
 `);
+    // ---- List a user's documents ----
+    // No app-wide enumeration: `--user-id` is required (the admin token has no
+    // "self"). Reads the per-user permission partition via the admin endpoint.
+    documents
+        .command("list")
+        .description("List a user's documents")
+        .requiredOption("--user-id <id>", "User ID whose documents to list")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const list = await client.listAdminDocuments(resolvedAppId, options.userId);
+            if (options.json) {
+                json(list);
+                return;
+            }
+            if (list.length === 0) {
+                info("No documents found.");
+                return;
+            }
+            console.log(formatTable(list, [
+                { header: "DOCUMENT_ID", key: "documentId", format: formatId },
+                { header: "TITLE", key: "title", flex: true },
+                { header: "PERMISSION", key: "permission" },
+                { header: "GRANTED", key: "grantedAt", format: formatDate },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Get a single document's metadata ----
+    documents
+        .command("get")
+        .description("Show a document's metadata and the caller's access to it")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const doc = await client.getDocument(resolvedAppId, documentId);
+            if (options.json) {
+                json(doc);
+                return;
+            }
+            keyValue("Document ID", doc.documentId);
+            keyValue("Title", doc.title);
+            keyValue("Created By", doc.createdBy);
+            keyValue("Created", formatDate(doc.createdAt));
+            keyValue("Modified", formatDate(doc.modifiedAt ?? doc.lastModified));
+            // `GET documents/:id` reports the caller's own access, not the
+            // document's grant/alias/collection inventory — printing counts for
+            // fields the endpoint never returns read as a definitive "0" for
+            // documents that demonstrably have them. Use
+            // `documents permissions list` for the grant list.
+            if (doc.permission)
+                keyValue("Your Permission", doc.permission);
+            if (doc.accessSource)
+                keyValue("Access Source", doc.accessSource);
+            if (doc.linkAccess)
+                keyValue("Link Access", doc.linkAccess);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Create a document ----
+    // The same `POST /documents` every client uses (#2763). Who ends up owning
+    // the document is the server's call, decided from the token's identity —
+    // the help below states that matrix rather than the CLI guessing at a role.
+    documents
+        .command("create")
+        .description("Create a document")
+        .argument("<title>", "Document title")
+        .option("--app <app-id>", "App ID")
+        .option("--owner <userId-or-email>", "User ID or email to own the document (super-admin or assigned-console-admin tokens only)")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+Ownership:
+  An app-user token — member, admin, or owner — always creates the document
+  owned by the caller: the server ignores --owner for those tokens.
+  A super-admin token, or a console-admin token assigned to this app, acts
+  through an admin shadow app user — without --owner that shadow user owns the
+  document, with --owner the named user does.
+  A console admin not assigned to this app has no access to the app at all.
+
+  An email given to --owner is resolved to a user id before anything is
+  created; a user who is not in the app fails the command without creating a
+  document.
+`)
+        .action(async (title, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        let ownerUserId;
+        if (options.owner) {
+            try {
+                ownerUserId = await resolveOwnerUserId(client, resolvedAppId, options.owner);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+        }
+        try {
+            const result = await client.createDocument(resolvedAppId, {
+                title,
+                ...(ownerUserId ? { createdBy: ownerUserId } : {}),
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success("Document created.");
+            keyValue("Document ID", result.documentId);
+            keyValue("Title", result.title);
+            keyValue("Owner", result.createdBy);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Delete a document ----
+    // The runtime-resource delete verb (#2756): the server endpoint cascades
+    // through records, Yjs history, blobs, aliases and permissions, so an
+    // operator resetting an app's data no longer needs a one-off SDK script.
+    // Who may run it is the server's decision, so the help below states that
+    // model (#2763) rather than leaving it to be discovered from a 403.
+    documents
+        .command("delete")
+        .description("Delete a document and all its data (records, history, blobs, aliases, permissions)")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+Permissions (enforced by the server, not the CLI):
+  The document's owner, the app owner, and super-admin or assigned-console-admin
+  tokens — which act with app-owner authority — delete directly.
+  Everyone else, including app-role admins, can delete only when a containing
+  collection's document.delete rule allows it: an app admin cannot delete a
+  standalone document (one in no collection) they do not own.
+  The app's root document cannot be deleted.
+`)
+        .action(async (documentId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Delete document ${documentId}? This permanently deletes its records, ` +
+                    `update history, blobs, aliases, and permissions. This cannot be undone.`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirm) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            const result = await client.deleteDocument(resolvedAppId, documentId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Document ${documentId} deleted.`);
+        }
+        catch (err) {
+            // Server refusals (404 not found, 403 root document / owner-only, the
+            // non-owner fail-closed 503) are printed verbatim, never swallowed.
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- User-level permissions subcommand group ----
+    const permissions = documents
+        .command("permissions")
+        .description("Manage user-level permissions on a document");
+    // List user-level permissions
+    permissions
+        .command("list")
+        .description("List user-level permissions for a document")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.listDocumentPermissions(resolvedAppId, documentId);
+            const list = Array.isArray(result) ? result : result?.permissions ?? [];
+            if (options.json) {
+                json(list);
+                return;
+            }
+            if (list.length === 0) {
+                info("No permissions found.");
+                return;
+            }
+            console.log(formatTable(list, [
+                { header: "USER_ID", key: "userId", format: formatId },
+                { header: "EMAIL", key: "email", flex: true },
+                { header: "PERMISSION", key: "permission" },
+                { header: "GRANTED", key: "grantedAt", format: formatDate },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Grant (or update) a user-level permission
+    permissions
+        .command("grant")
+        .description("Grant or update a user's permission on a document")
+        .argument("<document-id>", "Document ID")
+        .option("--user-id <id>", "User ID to grant the permission to")
+        .option("--email <email>", "Email of the user to grant the permission to")
+        .requiredOption("--permission <permission>", "Permission level: reader or read-write")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, options) => {
+        if (!options.userId && !options.email) {
+            error("Either --user-id or --email is required.");
+            process.exit(1);
+        }
+        if (options.userId && options.email) {
+            error("Provide only one of --user-id or --email, not both.");
+            process.exit(1);
+        }
+        if (!["reader", "read-write"].includes(options.permission)) {
+            error("Invalid --permission. Must be 'reader' or 'read-write'.");
+            process.exit(1);
+        }
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const entry = options.userId
+                ? { userId: options.userId, permission: options.permission }
+                : { email: options.email, permission: options.permission };
+            const result = await client.grantDocumentPermission(resolvedAppId, documentId, [entry]);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            const target = options.userId ? options.userId : options.email;
+            success(`Permission '${options.permission}' granted to ${target}.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Revoke a user-level permission
+    permissions
+        .command("revoke")
+        .description("Revoke a user's permission on a document")
+        .argument("<document-id>", "Document ID")
+        .argument("[user-id]", "User ID to revoke (or use --email)")
+        .option("--email <email>", "Email of the user to revoke (alternative to <user-id>)")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .action(async (documentId, userId, options) => {
+        if (!userId && !options.email) {
+            error("Either a <user-id> argument or --email is required.");
+            process.exit(1);
+        }
+        if (userId && options.email) {
+            error("Provide only one of <user-id> or --email, not both.");
+            process.exit(1);
+        }
+        const target = userId ?? options.email;
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Revoke permission for ${target} on document ${documentId}?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirm) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            await client.revokeDocumentPermission(resolvedAppId, documentId, {
+                userId,
+                email: options.email,
+            });
+            success(`Permission revoked for ${target}.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Records introspection subcommand group ----
+    const records = documents
+        .command("records")
+        .description("Inspect a document's models and records");
+    // List model names
+    records
+        .command("models")
+        .description("List model names in a document")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getDocumentSchema(resolvedAppId, documentId);
+            const models = result?.modelNames ?? Object.keys(result?.schema?.models ?? {});
+            if (options.json) {
+                json(models);
+                return;
+            }
+            if (models.length === 0) {
+                info("No models found.");
+                return;
+            }
+            for (const m of models) {
+                console.log(`  ${m}`);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Describe a model's fields and indexes
+    records
+        .command("describe")
+        .description("Show a model's fields and indexes")
+        .argument("<document-id>", "Document ID")
+        .argument("<model-name>", "Model name")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, modelName, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getDocumentSchema(resolvedAppId, documentId);
+            const model = result?.schema?.models?.[modelName];
+            if (!model) {
+                if (options.json) {
+                    json(null);
+                    return;
+                }
+                info(`Model '${modelName}' not found in this document.`);
+                return;
+            }
+            const fieldsObj = model.fields ?? {};
+            const rows = Object.entries(fieldsObj).map(([name, meta]) => ({
+                field: name,
+                type: meta?.type ?? "unknown",
+                indexed: meta?.indexed ? "yes" : "",
+                unique: meta?.unique ? "yes" : "",
+                required: meta?.required ? "yes" : "",
+            }));
+            if (options.json) {
+                json({ fields: fieldsObj, constraints: model.constraints ?? {} });
+                return;
+            }
+            if (rows.length === 0) {
+                info("No fields detected for this model.");
+                return;
+            }
+            console.log(formatTable(rows, [
+                { header: "FIELD", key: "field", flex: true },
+                { header: "TYPE", key: "type" },
+                { header: "INDEXED", key: "indexed" },
+                { header: "UNIQUE", key: "unique" },
+                { header: "REQUIRED", key: "required" },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Query records in a document model
+    records
+        .command("query")
+        .description("Query records in a document model")
+        .argument("<document-id>", "Document ID")
+        .argument("<model-name>", "Model name to query")
+        .option("--app <app-id>", "App ID")
+        .option("--filter <json>", "Filter as JSON (e.g. '{\"status\":\"open\"}')")
+        .option("--filter-file <path>", "Read filter from a JSON or TOML file")
+        .option("--limit <n>", "Maximum number of records to return (max 100)", parseInt)
+        .option("--cursor <cursor>", "Pagination cursor from a previous query")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, modelName, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const filter = parseFilterOptions(options);
+        const client = new ApiClient();
+        try {
+            const result = await client.queryDocumentRecords(resolvedAppId, documentId, modelName, { filter, limit: options.limit, cursor: options.cursor });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            const items = result.items;
+            if (items.length === 0) {
+                info("No records found.");
+                return;
+            }
+            const allKeys = new Set();
+            for (const rec of items) {
+                for (const key of Object.keys(rec))
+                    allKeys.add(key);
+            }
+            const orderedKeys = [];
+            if (allKeys.has("id")) {
+                orderedKeys.push("id");
+                allKeys.delete("id");
+            }
+            orderedKeys.push(...[...allKeys].sort());
+            const columns = orderedKeys.map((key) => ({
+                header: key.toUpperCase(),
+                key,
+                format: (v) => {
+                    if (v === null || v === undefined)
+                        return "—";
+                    if (typeof v === "object")
+                        return JSON.stringify(v);
+                    return String(v);
+                },
+            }));
+            console.log(formatTable(items, columns));
+            if (result.nextCursor) {
+                info(`More results available. Use --cursor ${result.nextCursor}`);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Get a single record by id (mirrors `databases records get`, issue #2357).
+    records
+        .command("get")
+        .description("Get a single record by id from a document model")
+        .argument("<document-id>", "Document ID")
+        .argument("<model-name>", "Model name")
+        .argument("<record-id>", "Record ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, 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 queryDocumentRecords, exactly as
+            // the `databases records get` twin reuses queryDatabaseRecords).
+            const result = await client.queryDocumentRecords(resolvedAppId, documentId, 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
+            // databases 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 in a document model
+    records
+        .command("count")
+        .description("Count records in a document model")
+        .argument("<document-id>", "Document ID")
+        .argument("<model-name>", "Model name to count")
+        .option("--app <app-id>", "App ID")
+        .option("--filter <json>", "Filter as JSON (e.g. '{\"status\":\"open\"}')")
+        .option("--filter-file <path>", "Read filter from a JSON or TOML file")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, modelName, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const filter = parseFilterOptions(options);
+        const client = new ApiClient();
+        try {
+            const result = await client.countDocumentRecords(resolvedAppId, documentId, modelName, { filter });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            console.log(`  ${result.count}`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Aggregate records in a document model (issue #2437). Mirrors
+    // `databases records aggregate` flag for flag and rendering for rendering —
+    // including the deliberate `keyValue()` for the ungrouped scalar, so the two
+    // twins keep printing the same thing.
+    const AGGREGATE_OPS = ["count", "sum", "avg", "min", "max"];
+    records
+        .command("aggregate")
+        .description("Aggregate records in a document model (count/sum/avg/min/max, optional group-by)")
+        .argument("<document-id>", "Document 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 plain field (repeatable; StringSet fields are not supported)", (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 (documentId, 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 response = await client.aggregateDocumentRecords(resolvedAppId, documentId, modelName, { operations: [operation], groupBy, filter });
+            if (options.json) {
+                json(response);
+                return;
+            }
+            const aggregated = response?.result;
+            // Same labelling rule as the databases twin: the field name is
+            // reproduced verbatim, never case-folded (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) {
+                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)) {
+                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 {
+                console.log(JSON.stringify(aggregated ?? {}, null, 2));
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Record writes (#1964 Phase 4) ----
+    // Server-side writes through the document facade: Yjs-first, CRDT-safe,
+    // broadcast to connected clients. Requires read-write or higher on the
+    // document (or an admin token). `--data` / `--data-file` are validated
+    // CLI-side before any request is sent.
+    // `--data`/`--data-file` parsing (including the object-shape check and the
+    // both-flags rule) is the shared `parseDataOption` helper, so these verbs
+    // behave and diagnose identically to `metadata` and `databases records`.
+    // Create or replace a record
+    records
+        .command("save")
+        .description("Create or replace a record in a document model")
+        .argument("<document-id>", "Document ID")
+        .argument("<model-name>", "Model name to write to")
+        .option("--app <app-id>", "App ID")
+        .option("--id <record-id>", "Record ID (a ULID is generated when omitted)")
+        .option("--data <json>", "Record fields as JSON (e.g. '{\"qty\":10}')")
+        .option("--data-file <file>", "Read record fields from a JSON file")
+        .option("--upsert-on <field>", "Update the record whose <field> matches instead of creating")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, modelName, options) => {
+        const data = parseDataOption(options, "record fields");
+        const resolvedAppId = resolveAppId(undefined, options);
+        const recordId = options.id || ulid();
+        const writeOptions = options.upsertOn ? { upsertOn: options.upsertOn } : undefined;
+        const client = new ApiClient();
+        try {
+            const result = await client.saveDocumentRecord(resolvedAppId, documentId, modelName, { id: recordId, data, ...(writeOptions ? { options: writeOptions } : {}) });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Record saved: ${result.record?.id ?? recordId}`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Merge fields into an existing record
+    records
+        .command("patch")
+        .description("Merge fields into an existing record in a document model")
+        .argument("<document-id>", "Document ID")
+        .argument("<model-name>", "Model name")
+        .argument("<record-id>", "Record ID to patch")
+        .option("--app <app-id>", "App ID")
+        .option("--data <json>", "Fields to merge as JSON (e.g. '{\"status\":\"closed\"}')")
+        .option("--data-file <file>", "Read fields from a JSON file")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, modelName, recordId, options) => {
+        const data = parseDataOption(options, "fields to merge");
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.patchDocumentRecord(resolvedAppId, documentId, modelName, recordId, { data });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Record patched: ${recordId}`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Delete a record
+    records
+        .command("delete")
+        .description("Delete a record from a document model")
+        .argument("<document-id>", "Document ID")
+        .argument("<model-name>", "Model name")
+        .argument("<record-id>", "Record ID to delete")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, modelName, recordId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            const confirmed = await confirmPrompt(`Delete record ${recordId} from ${modelName} in document ${documentId}?`);
+            if (!confirmed) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            const result = await client.deleteDocumentRecord(resolvedAppId, documentId, modelName, recordId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            // A delete of a missing record is a silent no-op server-side, so
+            // this reports the request outcome, not record existence.
+            success(`Record deleted: ${recordId}`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Apply an atomic multi-model operations blob
+    records
+        .command("bulk")
+        .description("Apply an atomic create/patch/delete operations blob to a document")
+        .argument("<document-id>", "Document 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? } " +
+        "— `data` holds the record fields and is required (non-empty) on " +
+        "create/patch, not allowed on delete; a create `id` must be a 26-char " +
+        "uppercase Crockford ULID")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, options) => {
+        const parsed = parseDataOption(options, "operations blob", {
+            allowArray: true,
+        });
+        const operations = Array.isArray(parsed) ? parsed : parsed?.operations;
+        if (!Array.isArray(operations) || operations.length === 0) {
+            error("--data-file must contain { operations: [...] } or a non-empty operations array.");
+            process.exit(1);
+        }
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            const confirmed = await confirmPrompt(`Apply ${operations.length} operation(s) atomically to document ${documentId}?`);
+            if (!confirmed) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            const result = await client.bulkDocumentRecords(resolvedAppId, documentId, operations);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Applied ${result.applied} operation(s): ` +
+                `${result.added.length} added, ${result.updated.length} updated, ${result.deleted} deleted.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Dump a document's records grouped by model (CLI-side composition)
+    documents
+        .command("dump")
+        .description("Dump a document's records grouped by model as JSON")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("--output <file>", "Write the JSON dump to a file instead of stdout")
+        .option("--json", "Output as JSON (default)")
+        .action(async (documentId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            // Model names come from the schema; records are assembled from paged
+            // reads per model (not a single atomic snapshot — the paged path is
+            // the contract, same pattern as `databases export`).
+            const schema = await client.getDocumentSchema(resolvedAppId, documentId);
+            const modelNames = schema?.modelNames ?? Object.keys(schema?.schema?.models ?? {});
+            const grouped = {};
+            for (const modelName of modelNames) {
+                const records = [];
+                let cursor;
+                do {
+                    const page = await client.queryDocumentRecords(resolvedAppId, documentId, modelName, { limit: 100, cursor });
+                    records.push(...page.items);
+                    cursor = page.nextCursor;
+                } while (cursor);
+                grouped[modelName] = records;
+            }
+            const output = JSON.stringify(grouped, null, 2);
+            if (options.output) {
+                fs.writeFileSync(options.output, output);
+                success(`Document dump written to ${options.output}`);
+                return;
+            }
+            console.log(output);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Document statistics (platform-vocabulary projection)
+    documents
+        .command("stats")
+        .description("Show a document's record/model/blob counts and approximate size")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getDocumentStats(resolvedAppId, documentId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            keyValue("Document ID", result.documentId);
+            keyValue("Records", result.recordCount);
+            keyValue("Models", result.modelCount);
+            keyValue("Blobs", result.blobCount);
+            keyValue("Size (bytes, approx)", result.sizeBytes);
+            keyValue("Last modified", result.lastModifiedAt ? formatDate(result.lastModifiedAt) : "—");
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
     // Transfer document ownership
     documents
         .command("transfer-owner")
@@ -337,20 +1199,15 @@ Examples:
             process.exit(1);
         }
         const client = new ApiClient();
-        // Resolve --owner to a userId
+        // Resolve --owner to a userId through the one shared lookup (#2763).
         let ownerUserId;
         if (options.owner) {
-            if (options.owner.includes("@")) {
-                const user = await client.findUserByEmail(resolvedAppId, options.owner);
-                if (!user) {
-                    error(`No user found with email "${options.owner}" in app ${resolvedAppId}.`);
-                    process.exit(1);
-                }
-                ownerUserId = user.userId || user.id;
-                info(`Resolved owner email to userId: ${ownerUserId}`);
+            try {
+                ownerUserId = await resolveOwnerUserId(client, resolvedAppId, options.owner);
             }
-            else {
-                ownerUserId = options.owner;
+            catch (err) {
+                error(err.message);
+                process.exit(1);
             }
         }
         try {