primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/commands/collections.js

@@ -0,0 +1,1282 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ApiClient } from "../lib/api-client.js";
+import { resolveAppId } from "../lib/config.js";
+import { success, error, info, warn, keyValue, result as printResult, formatTable, formatId, formatDate, json, flushOutput, } from "../lib/output.js";
+import { confirmPrompt } from "../lib/confirm-prompt.js";
+import { pageCursorOption, pageLimitOption, parsePageLimit, printEmptyPage, printPageHint, } from "../lib/list-options.js";
+import { normalizeCliListEnvelope, wholeListEnvelope, } from "../lib/paginate.js";
+import { resolveOwnerUserId } from "../lib/resolve-owner.js";
+import { COLLECTION_EXPORT_FILENAME, COLLECTION_EXPORT_VERSION, duplicateNameSources, emptyImportSummary, grantDisposition, grantUpdateLine, importExitCode, planCollection, readCollectionExportFile, serverReason, } from "../lib/collection-export.js";
+export function registerCollectionsCommands(program) {
+    const collections = program
+        .command("collections")
+        .description("Create and manage document collections and their access")
+        .addHelpText("after", `
+Examples:
+  $ primitive collections list
+  $ primitive collections create "Sprint 12"
+  $ primitive collections create "Sprint 12" --owner user@example.com
+  $ primitive collections get <collection-id>
+  $ primitive collections documents list <collection-id>
+  $ primitive collections documents add <collection-id> <document-id>
+  $ primitive collections access <collection-id>
+  $ primitive collections share <collection-id> --group team/engineering --permission read-write
+  $ primitive collections members list <collection-id>
+  $ primitive collections members add <collection-id> <user-id> --permission reader
+  $ primitive collections for-document <document-id>
+`);
+    // List collections
+    collections
+        .command("list")
+        .description("List collections in an app. By default shows only collections " +
+        "you're a direct member of. Use --all to see every collection (admin only).")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--all", "List every collection in the app (admin-only). Default is collections you're a direct member of.")
+        .addOption(pageLimitOption())
+        .addOption(pageCursorOption())
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const limit = parsePageLimit(options.limit);
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const params = { limit, cursor: options.cursor };
+            const page = normalizeCliListEnvelope(options.all
+                ? await client.listAllCollections(resolvedAppId, params)
+                : await client.listCollections(resolvedAppId, params));
+            const list = page.items;
+            if (options.json) {
+                json(page);
+                return;
+            }
+            if (list.length === 0) {
+                printEmptyPage(page, "collections");
+                return;
+            }
+            const columns = [
+                { header: "ID", key: "collectionId", format: formatId },
+                { header: "NAME", key: "name" },
+                { header: "DESCRIPTION", key: "description", format: (v) => v || "—" },
+                { header: "DOCS", key: "documentCount" },
+                { header: "CREATED", key: "createdAt", format: formatDate },
+            ];
+            // `permission` is only returned by the default list() endpoint
+            if (!options.all) {
+                columns.splice(4, 0, { header: "PERMISSION", key: "permission", format: (v) => v || "—" });
+            }
+            console.log(formatTable(list, columns));
+            printPageHint(page);
+        }
+        catch (err) {
+            // Friendly message when --all is used by a non-admin
+            if (options.all && /403|forbidden|insufficient permissions/i.test(err.message || "")) {
+                error("--all requires admin role on this app. Omit the flag to see collections you're a member of.");
+                process.exit(1);
+            }
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Create collection
+    collections
+        .command("create")
+        .description("Create a new collection")
+        .argument("<name>", "Collection name")
+        .option("--description <description>", "Collection description")
+        .option("--initial-metadata <json>", "Create-time resource metadata as JSON, keyed by category name (issue #1420)")
+        .option("--app <app-id>", "App ID")
+        .option("--owner <userId-or-email>", "User ID or email to own the collection (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 collection
+  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
+  collection, with --owner the named user does.
+  A console admin not assigned to this app has no access to the app at all.
+
+  The owner is the collection's creator, so under the default rules they — and
+  no other non-admin — can edit it, delete it, and manage its documents and
+  members.
+
+  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
+  collection.
+`)
+        .action(async (name, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        // Resolve --owner to a userId through the one shared lookup (#2763),
+        // before the create: an email nobody answers to must fail with nothing
+        // created, not leave a collection owned by the admin.
+        let ownerUserId;
+        if (options.owner) {
+            try {
+                ownerUserId = await resolveOwnerUserId(client, resolvedAppId, options.owner);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+        }
+        try {
+            const data = { name };
+            if (ownerUserId)
+                data.createdBy = ownerUserId;
+            if (options.description)
+                data.description = options.description;
+            // Create-time per-category ResourceMetadata rows (issue #1420).
+            if (options.initialMetadata) {
+                try {
+                    data.initialMetadata = JSON.parse(options.initialMetadata);
+                }
+                catch {
+                    error("Invalid --initial-metadata JSON.");
+                    process.exit(1);
+                }
+            }
+            const result = await client.createCollection(resolvedAppId, data);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success("Collection created.");
+            keyValue("Collection ID", result.collectionId);
+            keyValue("Name", result.name);
+            // Read back from the RESPONSE, not from --owner: whom the server
+            // credited is the answer, and for a non-admin token it is the caller.
+            keyValue("Owner", result.createdBy);
+            if (result.description)
+                keyValue("Description", result.description);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Get collection
+    collections
+        .command("get")
+        .description("Get collection details")
+        .argument("<collection-id>", "Collection ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (collectionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getCollection(resolvedAppId, collectionId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            printResult("Collection ID", result.collectionId);
+            printResult("Name", result.name);
+            printResult("Description", result.description || "—");
+            printResult("Documents", result.documentCount);
+            printResult("Created", formatDate(result.createdAt));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Update collection
+    collections
+        .command("update")
+        .description("Update a collection")
+        .argument("<collection-id>", "Collection ID")
+        .option("--name <name>", "New collection name")
+        .option("--description <description>", "New collection description")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (collectionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        const data = {};
+        if (options.name)
+            data.name = options.name;
+        if (options.description)
+            data.description = options.description;
+        if (Object.keys(data).length === 0) {
+            error("Provide at least --name or --description to update.");
+            process.exit(1);
+        }
+        try {
+            const result = await client.updateCollection(resolvedAppId, collectionId, data);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Collection ${collectionId} updated.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Delete collection
+    collections
+        .command("delete")
+        .description("Delete a collection (documents are preserved)")
+        .argument("<collection-id>", "Collection ID")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (collectionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Delete collection ${collectionId}? This revokes all collection-granted permissions but does NOT delete documents.`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirm) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            await client.deleteCollection(resolvedAppId, collectionId);
+            // What a script gets to confirm the removal (#3647). The server's body
+            // here is a bare `{ success: true }` that names nothing, so the ids are
+            // named by the CLI, as `documents transfer-owner` does.
+            if (options.json) {
+                json({ success: true, collectionId });
+                return;
+            }
+            success(`Collection ${collectionId} deleted.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Access command ----
+    collections
+        .command("access")
+        .description("Combined view of the groups and members with access to a collection " +
+        "(members only: 'collections members list'; group grants: 'collections share'/'unshare')")
+        .argument("<collection-id>", "Collection ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (collectionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getCollectionAccess(resolvedAppId, collectionId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            const groups = result.groups || [];
+            const members = result.members || [];
+            if (groups.length === 0 && members.length === 0) {
+                info("No groups or members have access to this collection.");
+                return;
+            }
+            if (groups.length > 0) {
+                console.log("\nGroups:");
+                console.log(formatTable(groups, [
+                    { header: "TYPE", key: "groupType" },
+                    { header: "ID", key: "groupId" },
+                    { header: "PERMISSION", key: "permission" },
+                    { header: "GRANTED", key: "grantedAt", format: formatDate },
+                ]));
+            }
+            if (members.length > 0) {
+                console.log("\nMembers:");
+                console.log(formatTable(members, [
+                    { header: "USER_ID", key: "userId", format: formatId },
+                    { header: "PERMISSION", key: "permission" },
+                ]));
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Share / unshare (group permissions) ----
+    collections
+        .command("share")
+        .description("Grant a group access to a collection")
+        .argument("<collection-id>", "Collection ID")
+        .requiredOption("--group <group>", "Group in format type/id (e.g. team/engineering)")
+        .requiredOption("--permission <permission>", "Permission level (reader or read-write)")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (collectionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        const parts = options.group.split("/");
+        if (parts.length !== 2) {
+            error("Group must be in format type/id (e.g. team/engineering).");
+            process.exit(1);
+        }
+        const [groupType, groupId] = parts;
+        try {
+            const result = await client.grantCollectionGroupPermission(resolvedAppId, collectionId, {
+                groupType,
+                groupId,
+                permission: options.permission,
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Granted ${options.permission} access to ${groupType}/${groupId} on collection.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    collections
+        .command("unshare")
+        .description("Revoke a group's access to a collection")
+        .argument("<collection-id>", "Collection ID")
+        .requiredOption("--group <group>", "Group in format type/id (e.g. team/engineering)")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (collectionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const parts = options.group.split("/");
+        if (parts.length !== 2) {
+            error("Group must be in format type/id (e.g. team/engineering).");
+            process.exit(1);
+        }
+        const [groupType, groupId] = parts;
+        if (!options.yes) {
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Revoke ${groupType}/${groupId} access to collection ${collectionId}?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirm) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            await client.revokeCollectionGroupPermission(resolvedAppId, collectionId, groupType, groupId);
+            if (options.json) {
+                json({ success: true, collectionId, groupType, groupId });
+                return;
+            }
+            success(`Revoked ${groupType}/${groupId} access from collection.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Documents subcommand group ----
+    const documents = collections
+        .command("documents")
+        .description("Manage documents in a collection");
+    // List documents
+    documents
+        .command("list")
+        .description("List documents in a collection")
+        .argument("<collection-id>", "Collection ID")
+        .option("--app <app-id>", "App ID")
+        .addOption(pageLimitOption())
+        .addOption(pageCursorOption())
+        .option("--json", "Output as JSON")
+        .action(async (collectionId, options) => {
+        const limit = parsePageLimit(options.limit);
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const page = normalizeCliListEnvelope(await client.listCollectionDocuments(resolvedAppId, collectionId, {
+                limit,
+                cursor: options.cursor,
+            }));
+            const list = page.items;
+            if (options.json) {
+                json(page);
+                return;
+            }
+            if (list.length === 0) {
+                printEmptyPage(page, "documents", "No documents in this collection.");
+                return;
+            }
+            console.log(formatTable(list, [
+                { header: "DOCUMENT_ID", key: "documentId", format: formatId },
+                { header: "ADDED", key: "addedAt", format: formatDate },
+            ]));
+            printPageHint(page);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Add document
+    documents
+        .command("add")
+        .description("Add a document to a collection")
+        .argument("<collection-id>", "Collection ID")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (collectionId, documentId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.addCollectionDocument(resolvedAppId, collectionId, {
+                documentId,
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Document ${documentId} added to collection.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Remove document
+    documents
+        .command("remove")
+        .description("Remove a document from a collection")
+        .argument("<collection-id>", "Collection ID")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (collectionId, documentId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Remove document ${documentId} from collection? Collection-sourced permissions will be revoked.`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirm) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            await client.removeCollectionDocument(resolvedAppId, collectionId, documentId);
+            if (options.json) {
+                json({ success: true, collectionId, documentId });
+                return;
+            }
+            success(`Document ${documentId} removed from collection.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- List collections for a document (reverse lookup) ----
+    collections
+        .command("for-document")
+        .description("List collections that a document belongs to")
+        .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.listCollectionsForDocument(resolvedAppId, documentId);
+            const list = Array.isArray(result) ? result : result?.items ?? [];
+            if (options.json) {
+                json(result);
+                return;
+            }
+            if (list.length === 0) {
+                info("Document is not in any collections.");
+                return;
+            }
+            console.log(formatTable(list, [
+                { header: "COLLECTION_ID", key: "collectionId", format: formatId },
+                { header: "NAME", key: "name" },
+                { header: "ADDED", key: "addedAt", format: formatDate },
+            ]));
+            if (result?.nextCursor) {
+                info(`More results available. Use --json to get the cursor for pagination.`);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Members subcommand group ----
+    const members = collections
+        .command("members")
+        .description("Manage individual user access to a collection");
+    // List members
+    //
+    // The server has no GET /collections/:id/members route — membership is read
+    // from the access endpoint, which returns groups and members together. This
+    // command is the members half of it, so reading "who is on this collection"
+    // doesn't require knowing about a command named for neither (#2764).
+    members
+        .command("list")
+        .description("List users with direct access to a collection")
+        .argument("<collection-id>", "Collection ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (collectionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getCollectionAccess(resolvedAppId, collectionId);
+            const list = result.members ?? [];
+            if (options.json) {
+                // The members half of the access payload, in the one list envelope
+                // (#3646) — the same shape `groups members list` prints (#2764).
+                json(wholeListEnvelope(list));
+                return;
+            }
+            if (list.length === 0) {
+                info("No members have direct access to this collection. Groups may still have access — see 'collections access'.");
+                return;
+            }
+            console.log(formatTable(list, [
+                { header: "USER_ID", key: "userId", format: formatId },
+                { header: "PERMISSION", key: "permission" },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Add member
+    members
+        .command("add")
+        .description("Add a user to a collection")
+        .argument("<collection-id>", "Collection ID")
+        .argument("<user-id>", "User ID")
+        .requiredOption("--permission <permission>", "Permission level (reader or read-write)")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (collectionId, userId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.addCollectionMember(resolvedAppId, collectionId, {
+                userId,
+                permission: options.permission,
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`User ${userId} added to collection with ${options.permission} access.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Remove member
+    members
+        .command("remove")
+        .description("Remove a user from a collection")
+        .argument("<collection-id>", "Collection ID")
+        .argument("<user-id>", "User ID")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (collectionId, userId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Remove user ${userId} from collection ${collectionId}?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirm) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            await client.removeCollectionMember(resolvedAppId, collectionId, userId);
+            if (options.json) {
+                json({ success: true, collectionId, userId });
+                return;
+            }
+            success(`User ${userId} removed from collection.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    registerCollectionsExport(collections);
+    registerCollectionsImport(collections);
+}
+// ---------------------------------------------------------------------------
+// Export (#3643)
+// ---------------------------------------------------------------------------
+/**
+ * `primitive collections export` — the collections half of a migration.
+ *
+ * `documents export-all` writes `manifest.json` and a directory per document;
+ * this writes `collections.json` beside them, so one directory carries the
+ * whole app. Owner and member identities travel as EMAILS wherever the server
+ * can resolve one: users are app-scoped (`models.yaml`), so the same person is
+ * a different userId in every app and a recorded source userId means nothing
+ * in the target.
+ */
+function registerCollectionsExport(collections) {
+    collections
+        .command("export")
+        .description("Export every collection in an app (name, owner, members, documents, group grants)")
+        .option("--app <app-id>", "App ID")
+        .option("--output <dir>", "Output directory", "./primitive-export")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+Admin only: the export reads the app-wide collection listing.
+
+It writes <output>/collections.json, beside the manifest.json and documents/
+that 'documents export-all' writes, so one directory is one app's migration.
+Import it with 'primitive collections import' AFTER 'documents import', which
+preserves document ids.
+
+Owner and member identities are recorded as emails wherever the server can
+resolve one — users are app-scoped, so a source app's userId means nothing in
+the target. A userId with no resolvable email is recorded as-is and will only
+import back into the same app.
+
+Not exported: collection ids (the server mints new ones), collection resource
+metadata, the groups themselves, pending member invitations.
+`)
+        .action(async (options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            await exportCollections(client, resolvedAppId, options);
+        }
+        catch (err) {
+            error(err.message);
+            await flushOutput();
+            process.exit(1);
+        }
+    });
+}
+/** Follow every page of the admin collection listing. */
+async function readAllCollections(client, appId) {
+    const rows = [];
+    let cursor;
+    do {
+        const page = await client.listAllCollections(appId, {
+            limit: 200,
+            ...(cursor ? { cursor } : {}),
+        });
+        rows.push(...(page.items ?? []));
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor);
+    return rows;
+}
+/** Follow every page of one collection's document list. */
+async function readAllCollectionDocuments(client, appId, collectionId) {
+    const rows = [];
+    let cursor;
+    do {
+        const page = await client.listCollectionDocuments(appId, collectionId, {
+            limit: 200,
+            ...(cursor ? { cursor } : {}),
+        });
+        for (const item of page.items ?? []) {
+            rows.push({
+                documentId: item.documentId,
+                addedAt: item.addedAt ?? null,
+            });
+        }
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor);
+    return rows;
+}
+async function exportCollections(client, appId, options) {
+    const rows = await readAllCollections(client, appId);
+    // One lookup per DISTINCT userId across the whole run, cached: a busy app's
+    // owner appears on every collection it owns and again in each one's members.
+    const emailCache = new Map();
+    const emailFor = async (userId) => {
+        if (emailCache.has(userId))
+            return emailCache.get(userId);
+        let email;
+        try {
+            const found = await client.listUsers(appId, { userId, limit: 1 });
+            email = (found.items ?? [])[0]?.email || undefined;
+        }
+        catch {
+            // An unresolvable email is not a reason to lose the collection: the
+            // userId is still recorded, and a same-app import can still use it.
+            email = undefined;
+        }
+        emailCache.set(userId, email);
+        return email;
+    };
+    const identity = async (userId) => {
+        const email = await emailFor(userId);
+        return email ? { userId, email } : { userId };
+    };
+    const exported = [];
+    let skipped = 0;
+    for (const row of rows) {
+        const collectionId = row.collectionId;
+        try {
+            const documents = await readAllCollectionDocuments(client, appId, collectionId);
+            const access = await client.getCollectionAccess(appId, collectionId);
+            const members = [];
+            for (const m of access?.members ?? []) {
+                members.push({
+                    ...(await identity(m.userId)),
+                    permission: m.permission,
+                });
+            }
+            const groups = (access?.groups ?? [])
+                // The server already filters system groups out of this response; a
+                // `_`-prefixed type could never be re-granted anyway (it is reserved).
+                .filter((g) => !String(g.groupType).startsWith("_"))
+                .map((g) => ({
+                groupType: g.groupType,
+                groupId: g.groupId,
+                permission: g.permission,
+            }));
+            exported.push({
+                collectionId,
+                name: row.name,
+                description: row.description ?? null,
+                collectionType: row.collectionType ?? null,
+                contextId: row.contextId ?? null,
+                createdAt: row.createdAt ?? null,
+                owner: row.createdBy ? await identity(row.createdBy) : null,
+                documents,
+                members,
+                groups,
+            });
+        }
+        catch (err) {
+            skipped += 1;
+            warn(`Skipping collection "${row.name}" (${collectionId}): ${err.message}`);
+        }
+    }
+    const filePath = path.join(options.output, COLLECTION_EXPORT_FILENAME);
+    // Each run REPLACES the file. A collection the previous one listed and this
+    // one does not becomes unreachable through the file an import reads, so say
+    // so — the same warning `documents export-all` gives for its manifest.
+    if (fs.existsSync(filePath)) {
+        try {
+            const previous = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+            const kept = new Set(exported.map((c) => c.collectionId));
+            const dropped = (Array.isArray(previous?.collections) ? previous.collections : []).filter((c) => !kept.has(c?.collectionId));
+            if (dropped.length > 0) {
+                warn(`The ${COLLECTION_EXPORT_FILENAME} already in ${options.output} lists ` +
+                    `${dropped.length} collection(s) this export does not: ` +
+                    `${dropped.map((c) => c?.name ?? c?.collectionId).join(", ")}. ` +
+                    `Replacing it leaves them unreachable through the file an import reads.`);
+            }
+        }
+        catch {
+            // An unreadable previous file is not a reason to refuse the export.
+        }
+    }
+    const file = {
+        version: COLLECTION_EXPORT_VERSION,
+        exportedAt: new Date().toISOString(),
+        sourceAppId: appId,
+        collectionCount: exported.length,
+        collections: exported,
+    };
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(file, null, 2));
+    if (options.json) {
+        // Counts and the path, not the bodies: the file is where those live.
+        json({
+            version: file.version,
+            exportedAt: file.exportedAt,
+            sourceAppId: file.sourceAppId,
+            collectionCount: file.collectionCount,
+            skipped,
+            path: filePath,
+        });
+        return;
+    }
+    success(`Exported ${exported.length} collection(s) to ${filePath}`);
+}
+// ---------------------------------------------------------------------------
+// Import (#3643)
+// ---------------------------------------------------------------------------
+/**
+ * `primitive collections import` — the other half of the migration.
+ *
+ * Two phases, in this order and never interleaved:
+ *
+ *   1. RESOLVE, reads only. Every owner, member, document and group the file
+ *      names is looked up in the target app and the plan is decided from the
+ *      answers, before anything at all is written. Only a DEFINITIVE absence
+ *      (a 404, or `exists: false` from the email lookup) reads as "not here";
+ *      any other failure fails the run with the collection and the item named,
+ *      exactly as `documents import` decides its root-document plans (#3096).
+ *   2. APPLY, in the order create → group grants → members → documents. Grants
+ *      go first ON PURPOSE: `addDocument` materializes every existing grant
+ *      onto a newly added document, so a fresh collection's access never
+ *      depends on the grant's own fan-out over the document list (F4).
+ */
+function registerCollectionsImport(collections) {
+    collections
+        .command("import")
+        .description("Recreate collections from a collections.json export (owner, members, documents, group grants)")
+        .argument("<path>", "Export directory holding collections.json, or the file itself")
+        .option("--app <app-id>", "App ID")
+        .option("--owner <userId-or-email>", "Own every imported collection with this user, instead of the owner each one records")
+        .option("--overwrite", "Merge into a collection that already carries the same name")
+        .option("--dry-run", "Show the plan and the problems without writing anything")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+For admin tokens. Assigning an owner is admin-only, so under an app-user token
+the server creates every collection owned by the caller and each one whose
+recorded owner is somebody else is reported as an 'owner' problem.
+
+Run 'primitive documents import' FIRST: it preserves document ids, which is
+what the collections file refers to.
+
+Owners and members are resolved by EMAIL — users are app-scoped, so a source
+app's userId means nothing here. A recorded userId is used only when the file
+came from this same app.
+
+Matching is by name. Without --overwrite a name already in the target is
+skipped; with it, the collection is merged — but only when its owner, type and
+context id match, since none of those can be changed after creation.
+
+A group grant the target already holds at another level is UPDATED to the level
+the file records, and what the group can reach follows the change. On a
+collection holding more than 200 documents the server refuses a collection-wide
+group change whole (COLLECTION_FANOUT_LIMIT): that is reported as a 'group'
+problem, and the rest of the collection is still merged.
+
+Exit code 1 when any per-item problem was reported. A skip is not a problem.
+`)
+        .action(async (importPath, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        let code = 0;
+        try {
+            code = await importCollections(client, resolvedAppId, importPath, options);
+        }
+        catch (err) {
+            error(err.message);
+            code = 1;
+        }
+        await flushOutput();
+        if (code !== 0)
+            process.exit(code);
+    });
+}
+/** A definitive "not here", as opposed to a read that simply failed. */
+function isNotFound(err) {
+    return err?.statusCode === 404;
+}
+async function importCollections(client, appId, importPath, options) {
+    const file = readCollectionExportFile(importPath);
+    // A source userId is only meaningful when the file came from THIS app —
+    // users are tenant-scoped, so the same person has a different userId in
+    // every app (`models.yaml`).
+    const sameApp = file.sourceAppId === appId;
+    /** userId ← recorded userId: the admin read, cached, one per distinct id. */
+    const byUserId = new Map();
+    const resolveRecordedUserId = async (userId) => {
+        if (byUserId.has(userId))
+            return byUserId.get(userId);
+        const found = await client.listUsers(appId, { userId, limit: 1 });
+        const hit = (found.items ?? [])[0];
+        // A row with no role is a user who is no longer in this app.
+        const resolved = hit && hit.role ? hit.userId : null;
+        byUserId.set(userId, resolved);
+        return resolved;
+    };
+    // `--owner` is resolved ONCE, before a single collection of the file is
+    // looked at: a name nobody answers to must fail the run with nothing written.
+    let explicitOwnerUserId;
+    if (options.owner) {
+        explicitOwnerUserId = await resolveOwnerUserId(client, appId, options.owner);
+        if (!options.owner.includes("@")) {
+            // `resolveOwnerUserId` hands a value with no "@" straight back — it is a
+            // userId as far as the flag is concerned, but nothing has yet checked
+            // that this app has such a member. Left unchecked, an id nobody answers
+            // to planned a create for every collection, `--dry-run` reported that
+            // plan as fine, and only the real run found out, one failed create at a
+            // time. The flag fails the run here instead, the way an unknown email
+            // already does.
+            let found;
+            try {
+                found = await resolveRecordedUserId(explicitOwnerUserId);
+            }
+            catch (err) {
+                throw new Error(`Checking --owner ${explicitOwnerUserId} against app ${appId} ` +
+                    `failed: ${err?.message ?? err}. Nothing has been written.`);
+            }
+            if (!found) {
+                throw new Error(`No app user found with id "${explicitOwnerUserId}" in app ${appId}.`);
+            }
+        }
+    }
+    const problems = [];
+    const summary = emptyImportSummary();
+    // ── Resolve phase ──────────────────────────────────────────────────────
+    const targetByName = new Map();
+    for (const row of await readAllCollections(client, appId)) {
+        if (!targetByName.has(row.name))
+            targetByName.set(row.name, row);
+    }
+    /** userId ← email, cached: one lookup per distinct email per run. */
+    const byEmail = new Map();
+    const resolveEmail = async (email) => {
+        if (byEmail.has(email))
+            return byEmail.get(email);
+        const lookup = await client.lookupUserByEmail(appId, email);
+        const userId = lookup?.exists && lookup.user ? lookup.user.userId : null;
+        byEmail.set(email, userId);
+        return userId;
+    };
+    /**
+     * One identity from the file to a userId in the target app.
+     *
+     * `{ userId: null, reason }` is a definitive absence to report; anything the
+     * reads could not settle has already thrown by the time this returns.
+     */
+    const resolveIdentity = async (identity) => {
+        if (!identity) {
+            return { userId: null, reason: "the export records no identity for it", id: "(none)" };
+        }
+        const id = identity.email || identity.userId || "(none)";
+        if (identity.email) {
+            const userId = await resolveEmail(identity.email);
+            return userId
+                ? { userId, id }
+                : {
+                    userId: null,
+                    id,
+                    reason: `no user with email "${identity.email}" is a member of ${appId}`,
+                };
+        }
+        if (identity.userId && sameApp) {
+            const userId = await resolveRecordedUserId(identity.userId);
+            return userId
+                ? { userId, id }
+                : {
+                    userId: null,
+                    id,
+                    reason: `no user with id ${identity.userId} is a member of ${appId}`,
+                };
+        }
+        return {
+            userId: null,
+            id,
+            reason: `it records only a userId from app ${file.sourceAppId || "(unknown)"}, ` +
+                `and users are scoped to their app — the same person has a different ` +
+                `userId here, so only an email can identify them across apps`,
+        };
+    };
+    const duplicates = duplicateNameSources(file.collections);
+    const planned = [];
+    for (const source of file.collections) {
+        const note = (kind, id, reason) => {
+            problems.push({
+                sourceCollectionId: source.collectionId,
+                name: source.name,
+                kind,
+                id,
+                reason,
+            });
+            warn(`${source.name}: ${kind} ${id} — ${reason}`);
+        };
+        /** Any read that is not a definitive absence stops the whole run. */
+        const fatal = (item, err) => {
+            throw new Error(`Reading ${item} for collection "${source.name}" ` +
+                `(${source.collectionId}) failed: ${err?.message ?? err}. ` +
+                `Nothing has been written.`);
+        };
+        let ownerUserId = explicitOwnerUserId ?? null;
+        let ownerReason;
+        if (!ownerUserId) {
+            try {
+                const resolved = await resolveIdentity(source.owner);
+                ownerUserId = resolved.userId;
+                ownerReason = resolved.reason;
+            }
+            catch (err) {
+                fatal(`owner ${source.owner?.email ?? source.owner?.userId ?? ""}`, err);
+            }
+        }
+        const existingRow = targetByName.get(source.name);
+        const row = planCollection(source, {
+            ownerUserId,
+            ownerReason,
+            existing: existingRow
+                ? {
+                    collectionId: existingRow.collectionId,
+                    createdBy: existingRow.createdBy,
+                    collectionType: existingRow.collectionType ?? null,
+                    contextId: existingRow.contextId ?? null,
+                }
+                : null,
+            duplicateOfSourceId: duplicates.get(source.collectionId) ?? null,
+        }, { overwrite: Boolean(options.overwrite) });
+        if (row.problem) {
+            note(row.problem.kind, row.problem.id, row.problem.reason);
+        }
+        if (row.action === "refused" || row.action === "skip") {
+            planned.push({ row, source, grants: [], members: [], documents: [] });
+            continue;
+        }
+        // What the target already grants, so a merge can compare levels.
+        let targetGrants = [];
+        if (row.action === "merge" && row.targetCollectionId) {
+            try {
+                const access = await client.getCollectionAccess(appId, row.targetCollectionId);
+                targetGrants = (access?.groups ?? []).map((g) => ({
+                    groupType: g.groupType,
+                    groupId: g.groupId,
+                    permission: g.permission,
+                }));
+            }
+            catch (err) {
+                fatal(`the access of ${row.targetCollectionId}`, err);
+            }
+        }
+        const grants = [];
+        for (const grant of source.groups ?? []) {
+            const label = `${grant.groupType}/${grant.groupId}`;
+            // The server reserves the `_` prefix for its own system groups; an
+            // export never writes one, and re-granting one is a 400.
+            if (String(grant.groupType).startsWith("_")) {
+                warn(`${source.name}: skipping the reserved group type ${grant.groupType} ` +
+                    `(${label}); the server manages those itself.`);
+                continue;
+            }
+            try {
+                await client.getGroup(appId, grant.groupType, grant.groupId);
+            }
+            catch (err) {
+                if (isNotFound(err)) {
+                    note("group", label, `no group ${label} exists in ${appId}`);
+                    continue;
+                }
+                fatal(`group ${label}`, err);
+            }
+            const disposition = grantDisposition(grant, targetGrants);
+            const existing = targetGrants.find((g) => g.groupType === grant.groupType && g.groupId === grant.groupId);
+            grants.push({
+                grant,
+                disposition,
+                ...(existing ? { existingPermission: existing.permission } : {}),
+            });
+        }
+        const members = [];
+        for (const member of source.members ?? []) {
+            let resolved;
+            try {
+                resolved = await resolveIdentity(member);
+            }
+            catch (err) {
+                fatal(`member ${member.email ?? member.userId}`, err);
+                continue;
+            }
+            if (!resolved.userId) {
+                note("member", resolved.id, resolved.reason);
+                continue;
+            }
+            members.push({ userId: resolved.userId, permission: member.permission });
+        }
+        const documents = [];
+        for (const document of source.documents ?? []) {
+            try {
+                await client.getDocument(appId, document.documentId);
+            }
+            catch (err) {
+                if (isNotFound(err)) {
+                    note("document", document.documentId, `no document ${document.documentId} exists in ${appId}; ` +
+                        `run 'primitive documents import' first — it preserves ids`);
+                    continue;
+                }
+                fatal(`document ${document.documentId}`, err);
+            }
+            documents.push(document.documentId);
+        }
+        planned.push({ row, source, grants, members, documents });
+    }
+    // ── Apply phase ────────────────────────────────────────────────────────
+    for (const entry of planned) {
+        const { row, source } = entry;
+        const note = (kind, id, reason) => {
+            problems.push({
+                sourceCollectionId: source.collectionId,
+                name: source.name,
+                kind,
+                id,
+                reason,
+            });
+            warn(`${source.name}: ${kind} ${id} — ${reason}`);
+        };
+        if (row.action === "refused") {
+            summary.refused += 1;
+            info(`Refusing ${source.name}: ${row.reason}`);
+            continue;
+        }
+        if (row.action === "skip") {
+            summary.skipped += 1;
+            info(`Skipping ${source.name}: ${row.reason}`);
+            continue;
+        }
+        if (options.dryRun) {
+            // The plan, and nothing else: not one write is issued.
+            if (row.action === "create") {
+                summary.created += 1;
+                info(`[dry-run] Would create ${source.name}`);
+            }
+            else {
+                summary.merged += 1;
+                info(`[dry-run] Would merge ${source.name} into ${row.targetCollectionId}`);
+            }
+            for (const { grant, disposition, existingPermission } of entry.grants) {
+                if (disposition === "already-applied")
+                    continue;
+                const label = `${grant.groupType}/${grant.groupId}`;
+                info(disposition === "update"
+                    ? `[dry-run] Would update ${grantUpdateLine(label, existingPermission, grant.permission)}`
+                    : `[dry-run] Would grant ${label} ${grant.permission}`);
+                summary.groupsGranted += 1;
+            }
+            summary.membersAdded += entry.members.length;
+            summary.documentsAdded += entry.documents.length;
+            continue;
+        }
+        let targetCollectionId = row.targetCollectionId;
+        if (row.action === "create") {
+            try {
+                const created = await client.createCollection(appId, {
+                    name: source.name,
+                    ...(source.description ? { description: source.description } : {}),
+                    ...(source.collectionType ? { collectionType: source.collectionType } : {}),
+                    ...(source.contextId ? { contextId: source.contextId } : {}),
+                    createdBy: row.ownerUserId,
+                });
+                targetCollectionId = created.collectionId;
+                row.targetCollectionId = targetCollectionId;
+                summary.created += 1;
+                info(`Created ${source.name} as ${targetCollectionId}`);
+                // Whom the server CREDITED is the answer. A server predating #3641
+                // ignores the field, and so does any server for a non-admin token.
+                if (created.createdBy && created.createdBy !== row.ownerUserId) {
+                    note("owner", row.ownerUserId, `the server did not assign the owner (it credited ` +
+                        `${created.createdBy}); the token is not an admin one, or the ` +
+                        `server predates #3641`);
+                }
+            }
+            catch (err) {
+                note("collection", source.collectionId, serverReason(err));
+                continue;
+            }
+        }
+        else {
+            summary.merged += 1;
+            info(`Merged ${source.name} into ${targetCollectionId}`);
+        }
+        for (const { grant, disposition, existingPermission } of entry.grants) {
+            if (disposition === "already-applied")
+                continue;
+            const label = `${grant.groupType}/${grant.groupId}`;
+            try {
+                await client.grantCollectionGroupPermission(appId, targetCollectionId, {
+                    groupType: grant.groupType,
+                    groupId: grant.groupId,
+                    permission: grant.permission,
+                });
+                summary.groupsGranted += 1;
+                // A level change is worth saying out loud: it is the one grant write
+                // that can take access away from people who already had it.
+                if (disposition === "update") {
+                    info(`Updated ${grantUpdateLine(label, existingPermission, grant.permission)}`);
+                }
+            }
+            catch (err) {
+                note("group", label, serverReason(err));
+            }
+        }
+        for (const member of entry.members) {
+            try {
+                const result = await client.addCollectionMember(appId, targetCollectionId, {
+                    userId: member.userId,
+                    permission: member.permission,
+                });
+                // `already_member` is the server saying it was already so — including
+                // the owner's own `_col-writer` enrolment, which every export records.
+                if (result?.status !== "already_member")
+                    summary.membersAdded += 1;
+            }
+            catch (err) {
+                note("member", member.userId, serverReason(err));
+            }
+        }
+        for (const documentId of entry.documents) {
+            try {
+                await client.addCollectionDocument(appId, targetCollectionId, { documentId });
+                summary.documentsAdded += 1;
+            }
+            catch (err) {
+                // 409 is "already in this collection": applied, not a problem.
+                if (err?.statusCode === 409)
+                    continue;
+                note("document", documentId, serverReason(err));
+            }
+        }
+    }
+    if (options.json) {
+        json({
+            ...summary,
+            collections: planned.map(({ row }) => ({
+                sourceCollectionId: row.sourceCollectionId,
+                name: row.name,
+                action: row.action,
+                ...(row.targetCollectionId
+                    ? { targetCollectionId: row.targetCollectionId }
+                    : {}),
+                ...(row.reason ? { reason: row.reason } : {}),
+            })),
+            problems,
+        });
+    }
+    else {
+        success(`${summary.created} created, ${summary.merged} merged, ` +
+            `${summary.skipped} skipped, ${summary.refused} refused; ` +
+            `${summary.groupsGranted} group grant(s), ${summary.membersAdded} member(s), ` +
+            `${summary.documentsAdded} document(s) added; ${problems.length} problem(s).`);
+    }
+    return importExitCode(problems);
+}
+//# sourceMappingURL=collections.js.map