primitive-admin 1.1.0-alpha.84 → 1.1.0-alpha.86

package/dist/src/commands/documents.js

@@ -6,6 +6,8 @@ import { resolveAppId } from "../lib/config.js";
 import { success, error, info, formatTable, formatId, formatDate, json, keyValue, result as printResult, warn, flushOutput, } from "../lib/output.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
 import { resolveOwnerUserId } from "../lib/resolve-owner.js";
+import { pageCursorOption, pageLimitOption, parsePageLimit, printEmptyPage, printPageHint, } from "../lib/list-options.js";
+import { normalizeCliListEnvelope, wholeListEnvelope, } from "../lib/paginate.js";
 import { parseDataOption } from "../lib/data-input.js";
 import { parseFilterOptions } from "../lib/record-filter.js";
 import { buildPermissionsExport } from "../lib/document-export-permissions.js";
@@ -33,6 +35,23 @@ function printIngestSession(session) {
         printResult(label, value);
     }
 }
+/**
+ * One refused records call, as one line for an operator (#3764).
+ *
+ * The same composition `describeBulkFailure` makes for the atomic blob, on the
+ * verbs that have no `--json` envelope to fill: the server's sentence, the
+ * stable code a script branches on, and the status. `statusCode` FIRST —
+ * `cli/src/lib/api-client.ts`'s `ApiError` is where the status lives, and a
+ * reader that asks for `status` alone prints nothing at all (#3597 paid for
+ * that once already).
+ */
+export function describeRecordsFailure(err) {
+    const message = (typeof err?.message === "string" && err.message) || String(err);
+    const code = typeof err?.code === "string" && err.code ? err.code : undefined;
+    const raw = err?.statusCode ?? err?.status;
+    const status = Number.isFinite(Number(raw)) ? Number(raw) : undefined;
+    return `${message}${code ? ` [${code}]` : ""}${status !== undefined ? ` (${status})` : ""}`;
+}
 /**
  * Report a document's format (#2816) — but only when it is a large document.
  *
@@ -47,6 +66,30 @@ function printDocumentFormat(doc) {
         keyValue("Format", "2 (large document)");
     }
 }
+/**
+ * The `--document-format` an operator stated, or the refusal (#3764, E10).
+ *
+ * Refused HERE rather than by the server, because an operator CAN act on it
+ * (principle 6) and a round trip to be told what they typed wrong is a round
+ * trip they do not need to spend. Commander hands the raw string over, so the
+ * digits are what is read; an unset flag states nothing.
+ */
+export function parseDocumentFormatOption(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = String(value).trim();
+    if (text === "1")
+        return 1;
+    if (text === "2")
+        return 2;
+    throw new Error(`Invalid --document-format "${String(value)}". Expected 1 (an ordinary ` +
+        `document) or 2 (a large document).`);
+}
+/** The `--document-format <1|2>` flag, said once for every records verb. */
+const DOCUMENT_FORMAT_FLAG = "--document-format <1|2>";
+const DOCUMENT_FORMAT_HELP = "The document format you expect: 1 (ordinary) or 2 (large). A disagreement " +
+    "with the platform's own answer is refused with DOCUMENT_FORMAT_MISMATCH " +
+    "rather than answered out of the wrong tables";
 /**
  * What `documents records bulk` reports when the write is refused (#3619).
  *
@@ -164,18 +207,25 @@ Examples:
         .description("List a user's documents")
         .requiredOption("--user-id <id>", "User ID whose documents to list")
         .option("--app <app-id>", "App ID")
+        .addOption(pageLimitOption())
+        .addOption(pageCursorOption())
         .option("--json", "Output as JSON")
         .action(async (options) => {
+        const limit = parsePageLimit(options.limit);
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const list = await client.listAdminDocuments(resolvedAppId, options.userId);
+            const page = normalizeCliListEnvelope(await client.listAdminDocumentsPage(resolvedAppId, options.userId, {
+                limit,
+                cursor: options.cursor,
+            }));
+            const list = page.items;
             if (options.json) {
-                json(list);
+                json(page);
                 return;
             }
             if (list.length === 0) {
-                info("No documents found.");
+                printEmptyPage(page, "documents");
                 return;
             }
             console.log(formatTable(list, [
@@ -188,6 +238,7 @@ Examples:
                 { header: "PERMISSION", key: "permission" },
                 { header: "GRANTED", key: "grantedAt", format: formatDate },
             ]));
+            printPageHint(page);
         }
         catch (err) {
             error(err.message);
@@ -378,7 +429,7 @@ Permissions (enforced by the server, not the CLI):
             const result = await client.listDocumentPermissions(resolvedAppId, documentId);
             const list = Array.isArray(result) ? result : result?.permissions ?? [];
             if (options.json) {
-                json(list);
+                json(wholeListEnvelope(list));
                 return;
             }
             if (list.length === 0) {
@@ -516,7 +567,9 @@ Permissions (enforced by the server, not the CLI):
             }
         }
         catch (err) {
-            error(err.message);
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
             process.exit(1);
         }
     });
@@ -567,7 +620,9 @@ Permissions (enforced by the server, not the CLI):
             ]));
         }
         catch (err) {
-            error(err.message);
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
             process.exit(1);
         }
     });
@@ -582,13 +637,24 @@ Permissions (enforced by the server, not the CLI):
         .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(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
         .option("--json", "Output as JSON")
         .action(async (documentId, modelName, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        catch (err) {
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
         const filter = parseFilterOptions(options);
         const client = new ApiClient();
         try {
-            const result = await client.queryDocumentRecords(resolvedAppId, documentId, modelName, { filter, limit: options.limit, cursor: options.cursor });
+            const result = await client.queryDocumentRecords(resolvedAppId, documentId, modelName, { filter, limit: options.limit, cursor: options.cursor, documentFormat });
             if (options.json) {
                 json(result);
                 return;
@@ -626,7 +692,9 @@ Permissions (enforced by the server, not the CLI):
             }
         }
         catch (err) {
-            error(err.message);
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
             process.exit(1);
         }
     });
@@ -638,15 +706,26 @@ Permissions (enforced by the server, not the CLI):
         .argument("<model-name>", "Model name")
         .argument("<record-id>", "Record ID")
         .option("--app <app-id>", "App ID")
+        .option(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
         .option("--json", "Output as JSON")
         .action(async (documentId, modelName, recordId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        catch (err) {
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
         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 result = await client.queryDocumentRecords(resolvedAppId, documentId, modelName, { filter: { id: recordId }, limit: 1, documentFormat });
             const record = result.items[0];
             if (options.json) {
                 json(record ?? null);
@@ -670,7 +749,9 @@ Permissions (enforced by the server, not the CLI):
             }
         }
         catch (err) {
-            error(err.message);
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
             process.exit(1);
         }
     });
@@ -682,14 +763,25 @@ Permissions (enforced by the server, not the CLI):
         .argument("<model-name>", "Model name to count")
         .option("--app <app-id>", "App ID")
         .option("--filter <json>", "Filter as JSON (e.g. '{\"status\":\"open\"}')")
+        .option(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
         .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);
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        catch (err) {
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
         const filter = parseFilterOptions(options);
         const client = new ApiClient();
         try {
-            const result = await client.countDocumentRecords(resolvedAppId, documentId, modelName, { filter });
+            const result = await client.countDocumentRecords(resolvedAppId, documentId, modelName, { filter, documentFormat });
             if (options.json) {
                 json(result);
                 return;
@@ -697,7 +789,9 @@ Permissions (enforced by the server, not the CLI):
             console.log(`  ${result.count}`);
         }
         catch (err) {
-            error(err.message);
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
             process.exit(1);
         }
     });
@@ -717,9 +811,20 @@ Permissions (enforced by the server, not the CLI):
         .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(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
         .option("--json", "Output as JSON")
         .action(async (documentId, modelName, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        catch (err) {
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
         if (!AGGREGATE_OPS.includes(options.op)) {
             error(`Invalid --op "${options.op}". Expected one of: ${AGGREGATE_OPS.join(", ")}.`);
             process.exit(1);
@@ -742,7 +847,7 @@ Permissions (enforced by the server, not the CLI):
         const groupBy = options.groupBy || [];
         const client = new ApiClient();
         try {
-            const response = await client.aggregateDocumentRecords(resolvedAppId, documentId, modelName, { operations: [operation], groupBy, filter });
+            const response = await client.aggregateDocumentRecords(resolvedAppId, documentId, modelName, { operations: [operation], groupBy, filter }, { documentFormat });
             if (options.json) {
                 json(response);
                 return;
@@ -779,7 +884,9 @@ Permissions (enforced by the server, not the CLI):
             }
         }
         catch (err) {
-            error(err.message);
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
             process.exit(1);
         }
     });
@@ -802,15 +909,26 @@ Permissions (enforced by the server, not the CLI):
         .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(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
         .option("--json", "Output as JSON")
         .action(async (documentId, modelName, options) => {
         const data = parseDataOption(options, "record fields");
         const resolvedAppId = resolveAppId(undefined, options);
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        catch (err) {
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
         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 } : {}) });
+            const result = await client.saveDocumentRecord(resolvedAppId, documentId, modelName, { id: recordId, data, ...(writeOptions ? { options: writeOptions } : {}) }, { documentFormat });
             if (options.json) {
                 json(result);
                 return;
@@ -818,7 +936,9 @@ Permissions (enforced by the server, not the CLI):
             success(`Record saved: ${result.record?.id ?? recordId}`);
         }
         catch (err) {
-            error(err.message);
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
             process.exit(1);
         }
     });
@@ -831,14 +951,25 @@ Permissions (enforced by the server, not the CLI):
         .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(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
         .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);
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        catch (err) {
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
         const client = new ApiClient();
         try {
-            const result = await client.patchDocumentRecord(resolvedAppId, documentId, modelName, recordId, { data });
+            const result = await client.patchDocumentRecord(resolvedAppId, documentId, modelName, recordId, { data }, { documentFormat });
             if (options.json) {
                 json(result);
                 return;
@@ -846,7 +977,9 @@ Permissions (enforced by the server, not the CLI):
             success(`Record patched: ${recordId}`);
         }
         catch (err) {
-            error(err.message);
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
             process.exit(1);
         }
     });
@@ -858,10 +991,21 @@ Permissions (enforced by the server, not the CLI):
         .argument("<model-name>", "Model name")
         .argument("<record-id>", "Record ID to delete")
         .option("--app <app-id>", "App ID")
+        .option(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
         .option("-y, --yes", "Skip confirmation prompt")
         .option("--json", "Output as JSON")
         .action(async (documentId, modelName, recordId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        catch (err) {
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
         if (!options.yes) {
             const confirmed = await confirmPrompt(`Delete record ${recordId} from ${modelName} in document ${documentId}?`);
             if (!confirmed) {
@@ -871,7 +1015,7 @@ Permissions (enforced by the server, not the CLI):
         }
         const client = new ApiClient();
         try {
-            const result = await client.deleteDocumentRecord(resolvedAppId, documentId, modelName, recordId);
+            const result = await client.deleteDocumentRecord(resolvedAppId, documentId, modelName, recordId, { documentFormat });
             if (options.json) {
                 json(result);
                 return;
@@ -881,7 +1025,9 @@ Permissions (enforced by the server, not the CLI):
             success(`Record deleted: ${recordId}`);
         }
         catch (err) {
-            error(err.message);
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
             process.exit(1);
         }
     });
@@ -896,9 +1042,20 @@ Permissions (enforced by the server, not the CLI):
         "create/patch, not allowed on delete; a create `id` must be a 26-char " +
         "uppercase Crockford ULID")
         .option("--app <app-id>", "App ID")
+        .option(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
         .option("-y, --yes", "Skip confirmation prompt")
         .option("--json", "Output as JSON")
         .action(async (documentId, options) => {
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        catch (err) {
+            // #3764 — the server's sentence, the stable code and the status, so a
+            // refused records call is scriptable rather than only readable.
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
         const parsed = parseDataOption(options, "operations blob", {
             allowArray: true,
         });
@@ -917,7 +1074,7 @@ Permissions (enforced by the server, not the CLI):
         }
         const client = new ApiClient();
         try {
-            const result = await client.bulkDocumentRecords(resolvedAppId, documentId, operations);
+            const result = await client.bulkDocumentRecords(resolvedAppId, documentId, operations, { documentFormat });
             if (options.json) {
                 json(result);
                 return;
@@ -1152,13 +1309,14 @@ Permissions (enforced by the server, not the CLI):
         .option("--cursor <cursor>", "Continue from a previous page's nextCursor")
         .option("--json", "Output as JSON")
         .action(async (documentId, options) => {
+        const limit = parsePageLimit(options.limit);
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const page = await client.listDocumentIngests(resolvedAppId, documentId, {
-                limit: Number(options.limit),
+            const page = normalizeCliListEnvelope(await client.listDocumentIngests(resolvedAppId, documentId, {
+                limit,
                 ...(options.cursor ? { cursor: options.cursor } : {}),
-            });
+            }));
             if (options.json) {
                 json(page);
                 return;
@@ -1226,13 +1384,14 @@ Permissions (enforced by the server, not the CLI):
         .option("--cursor <cursor>", "Continue from a previous page's nextCursor")
         .option("--json", "Output as JSON")
         .action(async (documentId, options) => {
+        const limit = parsePageLimit(options.limit);
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const page = await client.listDocumentSnapshots(resolvedAppId, documentId, {
-                limit: Number(options.limit),
+            const page = normalizeCliListEnvelope(await client.listDocumentSnapshots(resolvedAppId, documentId, {
+                limit,
                 ...(options.cursor ? { cursor: options.cursor } : {}),
-            });
+            }));
             if (options.json) {
                 json(page);
                 return;
@@ -1540,7 +1699,7 @@ Permissions (enforced by the server, not the CLI):
             const result = await client.listDocumentGroupPermissions(resolvedAppId, documentId);
             const list = Array.isArray(result) ? result : result?.permissions ?? [];
             if (options.json) {
-                json(list);
+                json(wholeListEnvelope(list));
                 return;
             }
             if (list.length === 0) {
@@ -1589,6 +1748,55 @@ Permissions (enforced by the server, not the CLI):
             process.exit(1);
         }
     });
+    // ---- Effective access for a named user (#3658) ----
+    const access = documents
+        .command("access")
+        .description("Read a user's effective access to a document");
+    access
+        .command("get")
+        .description("Show what a user may do with a document, across direct, group, " +
+        "collection and link access")
+        .argument("<document-id>", "Document ID")
+        .requiredOption("--user <user-id>", "The user whose access to resolve")
+        .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.validateDocumentAccessForUser(resolvedAppId, documentId, options.user);
+            const row = {
+                documentId,
+                userId: options.user,
+                hasAccess: result?.hasAccess === true,
+                permission: result?.permission ?? null,
+                accessSource: result?.accessSource ?? null,
+                appRole: result?.appRole ?? null,
+            };
+            if (options.json) {
+                json(row);
+                return;
+            }
+            console.log(formatTable([row], [
+                { header: "DOCUMENT", key: "documentId" },
+                { header: "USER", key: "userId" },
+                { header: "ACCESS", key: "hasAccess" },
+                { header: "PERMISSION", key: "permission" },
+                { header: "SOURCE", key: "accessSource" },
+                { header: "APP_ROLE", key: "appRole" },
+            ]));
+            if (!row.hasAccess) {
+                // The role is not a grant: only the tag routes admit an
+                // administrator without one, so an operator reading "admin" here
+                // should not conclude the user may write content.
+                info("No document grant. An app role admits tag changes only, never a content write.");
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
     // ---- Link access ("anyone with the link") ----
     const linkAccess = documents
         .command("link-access")