primitive-admin 1.1.0-alpha.85 → 1.1.0-alpha.87

package/dist/src/commands/documents.d.ts

@@ -1,4 +1,24 @@
 import { Command } from "commander";
+/**
+ * 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 declare function describeRecordsFailure(err: any): string;
+/**
+ * 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 declare function parseDocumentFormatOption(value: unknown): 1 | 2 | undefined;
 /**
  * What `documents records bulk` reports when the write is refused (#3619).
  *

package/dist/src/commands/documents.js

@@ -35,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.
  *
@@ -49,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).
  *
@@ -526,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);
         }
     });
@@ -577,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);
         }
     });
@@ -592,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;
@@ -636,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);
         }
     });
@@ -648,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);
@@ -680,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);
         }
     });
@@ -692,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;
@@ -707,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);
         }
     });
@@ -727,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);
@@ -752,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;
@@ -789,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);
         }
     });
@@ -812,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;
@@ -828,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);
         }
     });
@@ -841,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;
@@ -856,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);
         }
     });
@@ -868,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) {
@@ -881,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;
@@ -891,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);
         }
     });
@@ -906,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,
         });
@@ -927,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;
@@ -1601,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")