primitive-admin 1.1.0-alpha.7 → 1.1.0-alpha.71

package/dist/src/commands/documents.js

@@ -1,15 +1,880 @@
 import { ApiClient } from "../lib/api-client.js";
 import { resolveAppId } from "../lib/config.js";
-import { success, error, info, formatTable, formatDate, json, } 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")
@@ -43,15 +908,14 @@ Examples:
             process.exit(1);
         }
         if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Transfer ownership of document ${documentId} to user ${newOwnerId}? This cannot be undone.`,
-                    default: false,
-                },
-            ]);
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Transfer ownership of document ${documentId} to user ${newOwnerId}? This cannot be undone.`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
             if (!confirm) {
                 info("Cancelled.");
                 return;
@@ -138,6 +1002,282 @@ Examples:
             process.exit(1);
         }
     });
+    // ---- Link access ("anyone with the link") ----
+    const linkAccess = documents
+        .command("link-access")
+        .description('Manage "anyone with the link" access on a document');
+    linkAccess
+        .command("get")
+        .description("Show the current link-access level 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 state = await client.getDocumentLinkAccess(resolvedAppId, documentId);
+            const level = state?.linkAccess ?? null;
+            if (options.json) {
+                json({ documentId, linkAccess: level });
+                return;
+            }
+            if (!level) {
+                info("Link access is off for this document.");
+                return;
+            }
+            keyValue("Document", documentId);
+            keyValue("Link access", level);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    linkAccess
+        .command("set")
+        .description("Turn on link access at a given level")
+        .argument("<document-id>", "Document ID")
+        .requiredOption("--level <level>", "Link access level: reader or read-write")
+        .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.setDocumentLinkAccess(resolvedAppId, documentId, options.level);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Link access set to '${options.level}' for document ${documentId}.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    linkAccess
+        .command("clear")
+        .description("Turn off link access")
+        .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.clearDocumentLinkAccess(resolvedAppId, documentId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Link access turned off for document ${documentId}.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Export / Import commands ----
+    documents
+        .command("export")
+        .description("Export a document (Yjs state, blobs, permissions, aliases)")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .argument("<document-id>", "Document ID to export")
+        .option("--app <app-id>", "App ID")
+        .option("--output <dir>", "Output directory", "./primitive-export")
+        .option("--no-blobs", "Skip blob data")
+        .option("--json", "Output as JSON")
+        .action(async (first, second, options) => {
+        let resolvedAppId;
+        let documentId;
+        if (second && !second.startsWith("-")) {
+            resolvedAppId = resolveAppId(first, options);
+            documentId = second;
+        }
+        else {
+            resolvedAppId = resolveAppId(undefined, options);
+            documentId = first;
+        }
+        if (!documentId) {
+            error("Document ID is required.");
+            process.exit(1);
+        }
+        const client = new ApiClient();
+        try {
+            await exportSingleDocument(client, resolvedAppId, documentId, options.output, options.blobs !== false ? true : false, options.json);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    documents
+        .command("export-all")
+        .description("Export all documents for a user")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .requiredOption("--user-id <id>", "User ID to export documents for")
+        .option("--app <app-id>", "App ID")
+        .option("--owned-only", "Only export documents owned by the user")
+        .option("--output <dir>", "Output directory", "./primitive-export")
+        .option("--no-blobs", "Skip blob data")
+        .option("--json", "Output as JSON")
+        .action(async (appIdArg, options) => {
+        const resolvedAppId = resolveAppId(appIdArg, options);
+        const client = new ApiClient();
+        const includeBlobs = options.blobs !== false;
+        try {
+            const documents = await client.listAdminDocuments(resolvedAppId, options.userId);
+            let docList = Array.isArray(documents) ? documents : [];
+            if (options.ownedOnly) {
+                docList = docList.filter((d) => d.permission === "owner");
+            }
+            if (docList.length === 0) {
+                info("No documents found.");
+                return;
+            }
+            info(`Exporting ${docList.length} document(s)...`);
+            const exportedIds = [];
+            for (const doc of docList) {
+                const docId = doc.documentId || doc.id;
+                try {
+                    await exportSingleDocument(client, resolvedAppId, docId, options.output, includeBlobs, false);
+                    exportedIds.push(docId);
+                }
+                catch (err) {
+                    warn(`Failed to export ${docId}: ${err.message}`);
+                }
+            }
+            // Write manifest
+            const manifestPath = path.join(options.output, "manifest.json");
+            const manifest = {
+                version: 1,
+                exportedAt: new Date().toISOString(),
+                sourceAppId: resolvedAppId,
+                documentCount: exportedIds.length,
+                documents: exportedIds,
+            };
+            fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+            fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+            if (options.json) {
+                json(manifest);
+            }
+            else {
+                success(`Exported ${exportedIds.length} document(s) to ${options.output}`);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    documents
+        .command("import")
+        .description("Import documents from an export directory")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .argument("<path>", "Path to export directory or single document directory")
+        .option("--app <app-id>", "App ID")
+        .option("--aliases <mode>", "Alias conflict handling: overwrite or skip", "skip")
+        .option("--overwrite", "Replace existing documents if IDs collide")
+        .option("--dry-run", "Show what would be imported without making changes")
+        .option("--owner <userId-or-email>", "User ID or email to set as document owner (admin only)")
+        .option("--json", "Output as JSON")
+        .action(async (first, second, options) => {
+        let resolvedAppId;
+        let importPath;
+        if (second && !second.startsWith("-")) {
+            resolvedAppId = resolveAppId(first, options);
+            importPath = second;
+        }
+        else {
+            resolvedAppId = resolveAppId(undefined, options);
+            importPath = first;
+        }
+        if (!importPath) {
+            error("Import path is required.");
+            process.exit(1);
+        }
+        const client = new ApiClient();
+        // Resolve --owner to a userId through the one shared lookup (#2763).
+        let ownerUserId;
+        if (options.owner) {
+            try {
+                ownerUserId = await resolveOwnerUserId(client, resolvedAppId, options.owner);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+        }
+        try {
+            // Determine if this is a manifest-based export or a single document
+            const manifestPath = path.join(importPath, "manifest.json");
+            let docDirs = [];
+            if (fs.existsSync(manifestPath)) {
+                const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+                for (const docId of manifest.documents) {
+                    const docDir = path.join(importPath, "documents", docId);
+                    if (fs.existsSync(docDir)) {
+                        docDirs.push(docDir);
+                    }
+                }
+            }
+            else if (fs.existsSync(path.join(importPath, "metadata.json"))) {
+                // Single document directory
+                docDirs = [importPath];
+            }
+            else if (fs.existsSync(path.join(importPath, "documents"))) {
+                // Export directory without manifest — discover documents
+                const entries = fs.readdirSync(path.join(importPath, "documents"), { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isDirectory()) {
+                        docDirs.push(path.join(importPath, "documents", entry.name));
+                    }
+                }
+            }
+            else {
+                error("No valid export data found at the specified path.");
+                process.exit(1);
+            }
+            if (docDirs.length === 0) {
+                info("No documents to import.");
+                return;
+            }
+            const summary = {
+                created: 0,
+                updated: 0,
+                skipped: 0,
+                blobsUploaded: 0,
+                aliasesSet: 0,
+                aliasesSkipped: 0,
+            };
+            for (const docDir of docDirs) {
+                await importSingleDocument(client, resolvedAppId, docDir, options.overwrite || false, options.aliases || "skip", options.dryRun || false, summary, ownerUserId);
+            }
+            if (options.json) {
+                json(summary);
+            }
+            else {
+                success(`Import complete:`);
+                keyValue("  Documents created", String(summary.created));
+                if (summary.updated > 0)
+                    keyValue("  Documents updated", String(summary.updated));
+                if (summary.skipped > 0)
+                    keyValue("  Documents skipped", String(summary.skipped));
+                if (summary.blobsUploaded > 0)
+                    keyValue("  Blobs uploaded", String(summary.blobsUploaded));
+                if (summary.aliasesSet > 0)
+                    keyValue("  Aliases set", String(summary.aliasesSet));
+                if (summary.aliasesSkipped > 0)
+                    keyValue("  Aliases skipped", String(summary.aliasesSkipped));
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
     // Revoke group permission
     groupPermissions
         .command("revoke")
@@ -150,15 +1290,14 @@ Examples:
         .action(async (documentId, groupType, groupId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Revoke permission for group ${groupType}/${groupId} on document ${documentId}?`,
-                    default: false,
-                },
-            ]);
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Revoke permission for group ${groupType}/${groupId} on document ${documentId}?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
             if (!confirm) {
                 info("Cancelled.");
                 return;
@@ -175,4 +1314,203 @@ Examples:
         }
     });
 }
+// ============================================
+// Helper functions for export/import
+// ============================================
+async function exportSingleDocument(client, appId, documentId, outputDir, includeBlobs, jsonOutput) {
+    const docDir = path.join(outputDir, "documents", documentId);
+    fs.mkdirSync(docDir, { recursive: true });
+    // 1. Fetch document metadata
+    const docMeta = await client.getDocument(appId, documentId);
+    // 2. Export Yjs state
+    const stateResult = await client.exportDocumentState(appId, documentId);
+    fs.writeFileSync(path.join(docDir, "document.yjs"), Buffer.from(stateResult.state, "base64"));
+    // 3. Fetch permissions
+    let permissions = [];
+    try {
+        const permResult = await client.listDocumentPermissions(appId, documentId);
+        permissions = Array.isArray(permResult) ? permResult : permResult?.permissions || [];
+    }
+    catch {
+        // Permissions endpoint might not return data for all docs
+    }
+    // 4. Fetch invitations
+    let invitations = [];
+    try {
+        const invResult = await client.listDocumentInvitations(appId, documentId);
+        invitations = Array.isArray(invResult) ? invResult : invResult?.invitations || [];
+    }
+    catch {
+        // May not have invitations
+    }
+    // Merge permissions and invitations into a single list with email identifiers
+    const permissionsExport = [
+        ...permissions.map((p) => ({
+            email: p.email,
+            permission: p.permission,
+            grantedAt: p.grantedAt,
+        })),
+        ...invitations
+            .filter((i) => !i.accepted && new Date(i.expiresAt) > new Date())
+            .map((i) => ({
+            email: i.email,
+            permission: i.permission,
+            source: "invitation",
+            status: "pending",
+        })),
+    ];
+    fs.writeFileSync(path.join(docDir, "permissions.json"), JSON.stringify(permissionsExport, null, 2));
+    // 5. Fetch aliases (user-scoped only)
+    let aliases = [];
+    try {
+        const aliasResult = await client.listDocumentAliases(appId, documentId);
+        aliases = (Array.isArray(aliasResult) ? aliasResult : aliasResult?.aliases || [])
+            .filter((a) => (a.scope || a.aliasScope) === "user");
+    }
+    catch {
+        // May not have aliases
+    }
+    // 6. Write metadata
+    const metadata = {
+        documentId: docMeta.documentId || documentId,
+        title: docMeta.title,
+        tags: docMeta.tags || [],
+        createdAt: docMeta.createdAt,
+        createdBy: docMeta.createdByEmail || docMeta.createdBy,
+        aliases: aliases.map((a) => ({
+            aliasScope: a.scope || a.aliasScope,
+            aliasKey: a.aliasKey,
+        })),
+    };
+    fs.writeFileSync(path.join(docDir, "metadata.json"), JSON.stringify(metadata, null, 2));
+    // 7. Blobs
+    if (includeBlobs) {
+        let blobs = [];
+        try {
+            const blobResult = await client.listDocumentBlobs(appId, documentId);
+            blobs = Array.isArray(blobResult) ? blobResult : blobResult?.items || blobResult?.blobs || [];
+        }
+        catch {
+            // May not have blobs
+        }
+        if (blobs.length > 0) {
+            const blobsDir = path.join(docDir, "blobs");
+            fs.mkdirSync(blobsDir, { recursive: true });
+            const blobIndex = blobs.map((b) => ({
+                blobId: b.blobId,
+                filename: b.filename,
+                contentType: b.contentType,
+                sha256: b.sha256,
+                numBytes: b.numBytes,
+            }));
+            fs.writeFileSync(path.join(blobsDir, "index.json"), JSON.stringify(blobIndex, null, 2));
+            // Download blobs (sequentially to avoid overwhelming the server)
+            for (const blob of blobs) {
+                const data = await client.downloadBlob(appId, documentId, blob.blobId);
+                fs.writeFileSync(path.join(blobsDir, `${blob.blobId}.bin`), data);
+            }
+        }
+    }
+    if (jsonOutput) {
+        json({
+            documentId,
+            title: metadata.title,
+            stateBytes: stateResult.byteLength,
+            permissions: permissionsExport.length,
+            aliases: aliases.length,
+            exportPath: docDir,
+        });
+    }
+    else {
+        success(`Exported document ${documentId} (${metadata.title || "untitled"}) to ${docDir}`);
+    }
+}
+async function importSingleDocument(client, appId, docDir, overwrite, aliasMode, dryRun, summary, ownerUserId) {
+    const metadataPath = path.join(docDir, "metadata.json");
+    if (!fs.existsSync(metadataPath)) {
+        warn(`Skipping ${docDir}: no metadata.json found`);
+        summary.skipped++;
+        return;
+    }
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf-8"));
+    const documentId = metadata.documentId;
+    if (dryRun) {
+        info(`[dry-run] Would import document ${documentId} (${metadata.title || "untitled"})`);
+        summary.created++;
+        return;
+    }
+    // Check if document exists
+    let exists = false;
+    try {
+        await client.getDocument(appId, documentId);
+        exists = true;
+    }
+    catch {
+        exists = false;
+    }
+    if (exists && !overwrite) {
+        warn(`Skipping ${documentId}: already exists (use --overwrite to replace)`);
+        summary.skipped++;
+        return;
+    }
+    // Create document if it doesn't exist
+    if (!exists) {
+        await client.createDocument(appId, {
+            title: metadata.title || "Imported Document",
+            documentId,
+            tags: metadata.tags,
+            ...(ownerUserId ? { createdBy: ownerUserId } : {}),
+        });
+        summary.created++;
+    }
+    else {
+        summary.updated++;
+    }
+    // Import Yjs state
+    const yjsPath = path.join(docDir, "document.yjs");
+    if (fs.existsSync(yjsPath)) {
+        const stateBuffer = fs.readFileSync(yjsPath);
+        const stateBase64 = stateBuffer.toString("base64");
+        await client.importDocumentState(appId, documentId, stateBase64);
+    }
+    // Upload blobs
+    const blobIndexPath = path.join(docDir, "blobs", "index.json");
+    if (fs.existsSync(blobIndexPath)) {
+        const blobIndex = JSON.parse(fs.readFileSync(blobIndexPath, "utf-8"));
+        for (const blob of blobIndex) {
+            const blobPath = path.join(docDir, "blobs", `${blob.blobId}.bin`);
+            if (fs.existsSync(blobPath)) {
+                const data = fs.readFileSync(blobPath);
+                await client.uploadBlob(appId, documentId, blob.blobId, data, {
+                    filename: blob.filename,
+                    contentType: blob.contentType,
+                    sha256: blob.sha256,
+                });
+                summary.blobsUploaded++;
+            }
+        }
+    }
+    // Permissions are exported for reference but not restored during import.
+    // The importing admin is the new owner; sharing is managed in the target app.
+    // Restore aliases
+    if (metadata.aliases && Array.isArray(metadata.aliases)) {
+        for (const alias of metadata.aliases) {
+            if (alias.aliasScope !== "user")
+                continue;
+            if (!ownerUserId) {
+                summary.aliasesSkipped++;
+                continue;
+            }
+            try {
+                await client.setDocumentAlias(appId, alias.aliasScope, alias.aliasKey, documentId, ownerUserId, aliasMode === "skip" // mustNotExist: true for skip mode, false for overwrite
+                );
+                summary.aliasesSet++;
+            }
+            catch {
+                summary.aliasesSkipped++;
+            }
+        }
+    }
+    info(`Imported document ${documentId} (${metadata.title || "untitled"})`);
+}
 //# sourceMappingURL=documents.js.map