primitive-admin 1.1.0-alpha.53 → 1.1.0-alpha.55

package/dist/src/commands/documents.js

@@ -1,7 +1,9 @@
 import { ApiClient } from "../lib/api-client.js";
 import { resolveAppId } from "../lib/config.js";
-import { success, error, info, formatTable, formatDate, json, keyValue, warn, } from "../lib/output.js";
+import { success, error, info, formatTable, formatId, formatDate, json, keyValue, warn, } from "../lib/output.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
+import { parseDataOption } from "../lib/data-input.js";
+import { ulid } from "ulid";
 import * as fs from "fs";
 import * as path from "path";
 export function registerDocumentsCommands(program) {
@@ -10,9 +12,621 @@ export function registerDocumentsCommands(program) {
         .description("Manage documents within an app")
         .addHelpText("after", `
 Examples:
+  $ primitive documents list --user-id <user-id>
+  $ primitive documents get <document-id>
+  $ 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 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);
+        }
+    });
+    // ---- 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("--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);
+        let filter;
+        if (options.filter) {
+            try {
+                filter = JSON.parse(options.filter);
+            }
+            catch {
+                error("Invalid --filter JSON.");
+                process.exit(1);
+            }
+        }
+        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);
+        }
+    });
+    // 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("--json", "Output as JSON")
+        .action(async (documentId, modelName, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        let filter;
+        if (options.filter) {
+            try {
+                filter = JSON.parse(options.filter);
+            }
+            catch {
+                error("Invalid --filter JSON.");
+                process.exit(1);
+            }
+        }
+        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);
+        }
+    });
+    // ---- 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")
+        .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")