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

package/dist/src/commands/documents.js

@@ -1,8 +1,13 @@
 import { snapshotBuildRows } from "../lib/snapshot-build-rows.js";
+import { driveSnapshotBuild } from "../lib/snapshot-build.js";
+import { ingestClientRows, ingestSessionRows, } from "../lib/document-ingest-rows.js";
 import { ApiClient } from "../lib/api-client.js";
 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";
@@ -18,37 +23,16 @@ import { ulid } from "ulid";
 import * as fs from "fs";
 import * as path from "path";
 /**
- * One bulk-load session as rows (#3434, #3435).
+ * One bulk-load session as rows (#3434, #3435, #3598).
  *
  * Shared by `documents ingests get` and by `documents ingest`'s own terminal
- * report, so an operator reads the same thing however they arrived at it.
+ * report, so an operator reads the same thing however they arrived at it. The
+ * rows themselves are decided in `document-ingest-rows`, where they can be
+ * checked without a live server holding a session in the right state.
  */
 function printIngestSession(session) {
-    printResult("Session", session.sessionId);
-    printResult("Document", session.documentId);
-    printResult("State", session.state);
-    printResult("Created by", session.createdBy);
-    printResult("Created", formatDate(session.createdAt));
-    printResult("Updated", formatDate(session.updatedAt));
-    printResult("Completed", session.completedAt ? formatDate(session.completedAt) : "—");
-    printResult("Chunks", session.chunks);
-    printResult("Rows", session.rows);
-    printResult("Bytes", session.bytes);
-    const progress = session.progress ?? {};
-    printResult("Progress", `copied ${progress.rowsCopied ?? 0} rows, applied ` +
-        `${progress.chunksApplied ?? 0} chunks / ${progress.rowsApplied ?? 0} rows, ` +
-        `reconciled ${progress.recordsReconciled ?? 0} records`);
-    printResult("Copy point", session.copyStartedAt ? formatDate(session.copyStartedAt) : "—");
-    printResult("Discontinuity epoch", session.discontinuityEpoch ?? "—");
-    printResult("Build", session.buildId ?? "—");
-    printResult("Expires", formatDate(session.expiresAt));
-    // Why it stopped is the reason an operator opened this at all.
-    if (session.failure) {
-        printResult("Failure", session.failure.code);
-        printResult("Reason", session.failure.reason);
-        for (const row of session.failure.rows ?? []) {
-            printResult("  Row", typeof row === "string" ? row : `${row.model} ${row.id}`);
-        }
+    for (const [label, value] of ingestSessionRows(session)) {
+        printResult(label, value);
     }
 }
 /**
@@ -66,22 +50,85 @@ function printDocumentFormat(doc) {
     }
 }
 /**
- * Resolve a `--owner` value to a userId. A value containing "@" is looked up
- * by exact email through the member-accessible `users/lookup` endpoint
- * (issue #2763); anything else is already a user id and is passed through.
- * Failures throw with the server's own message — a permission problem must
- * not read as "no such user", which is how the old admin-only lookup
- * reported it.
+ * What `documents records bulk` reports when the write is refused (#3619).
+ *
+ * The command used to catch every failure with `error(err.message)` while
+ * `ApiError` carried the code and the status on separate fields, so the stable
+ * code the server answers never reached the output and `--json` handled
+ * successes only. An operator driving a multi-hour load had to read human text
+ * to tell "ask again" from "somebody look at the log" (finding 3619-SO-04).
+ *
+ * The status is read from `statusCode` FIRST: that is where
+ * `cli/src/lib/api-client.ts`'s `ApiError` keeps it, and a reader that asks for
+ * `status` alone sees `undefined` on every error the client raises and prints
+ * nothing at all — #3597 paid for that once already. `status` is the fallback,
+ * for an error that came from somewhere else.
+ *
+ * Its own function so both surfaces are composed once and can be graded
+ * without spawning a process: the human line and the `--json` envelope must
+ * agree about which failure happened.
  */
-async function resolveOwnerUserId(client, appId, owner) {
-    if (!owner.includes("@"))
-        return owner;
-    const lookup = await client.lookupUserByEmail(appId, owner);
-    if (!lookup?.exists || !lookup.user) {
-        throw new Error(`No app user found with email "${owner}" in app ${appId}.`);
-    }
-    info(`Resolved owner email to userId: ${lookup.user.userId}`);
-    return lookup.user.userId;
+export function describeBulkFailure(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 {
+        line: `${message}${code ? ` [${code}]` : ""}${status !== undefined ? ` (${status})` : ""}`,
+        envelope: {
+            ok: false,
+            ...(code ? { code } : {}),
+            ...(status !== undefined ? { status } : {}),
+            error: message,
+        },
+    };
+}
+/**
+ * A document's tags as a list, from whatever the wire handed back (#3644).
+ *
+ * `tags` is absent when the document has none — the server's presence rule,
+ * shared by the app API's list shape and the admin inventory — so every
+ * reader here has to cope with `undefined`. A stray non-array (an older
+ * server, a hand-edited fixture) is read as "no tags" rather than printed
+ * raw.
+ */
+function documentTagList(tags) {
+    return Array.isArray(tags)
+        ? tags.filter((tag) => typeof tag === "string" && tag !== "")
+        : [];
+}
+/**
+ * Tag text a terminal prints rather than obeys (#3644).
+ *
+ * A tag is app-user text. The write-side validator
+ * (`validateTag` in `src/app-api/controllers/documents-controller.ts`) trims
+ * it, caps it at 48 characters and refuses dynamo-bao's key separator, but
+ * every other byte survives — including the escape character. Printed raw
+ * into an operator's terminal, a 15-character tag such as
+ * `\x1b[2J\x1b[Hrestored` clears the screen and homes the cursor while
+ * the listing is being written, so a member with write access to one document
+ * could hide or falsify what `documents list` and `documents get` appear to
+ * report about the rest. The C0 range, DEL and the C1 range are therefore
+ * rendered as their `\uXXXX` source escapes: readable, one line and one cell
+ * per tag, and inert. Ordinary text — accents, CJK, emoji — is untouched.
+ */
+function escapeForTerminal(tag) {
+    return tag.replace(/[\x00-\x1f\x7f-\x9f]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+/**
+ * A document's tags as printable text, in the order the wire reported them.
+ *
+ * Only the plain-text surfaces come through here: `--json` on both commands
+ * returns the server's object untouched, so a migration diffing tags against
+ * what it wrote still reads the stored bytes.
+ */
+export function displayTags(tags) {
+    return documentTagList(tags).map(escapeForTerminal);
+}
+/** The tags cell of a documents table: comma-joined, or `-` when there are none. */
+export function formatTags(tags) {
+    const list = displayTags(tags);
+    return list.length > 0 ? list.join(", ") : "-";
 }
 export function registerDocumentsCommands(program) {
     const documents = program
@@ -119,26 +166,38 @@ 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, [
                 { header: "DOCUMENT_ID", key: "documentId", format: formatId },
                 { header: "TITLE", key: "title", flex: true },
+                // #3644 — the tags the route now reports. An app migration that
+                // regenerates tags on import verifies them from here; a document
+                // with none shows `-` rather than an empty cell.
+                { header: "TAGS", key: "tags", format: formatTags },
                 { header: "PERMISSION", key: "permission" },
                 { header: "GRANTED", key: "grantedAt", format: formatDate },
             ]));
+            printPageHint(page);
         }
         catch (err) {
             error(err.message);
@@ -167,6 +226,15 @@ Examples:
             keyValue("Created", formatDate(doc.createdAt));
             keyValue("Modified", formatDate(doc.modifiedAt ?? doc.lastModified));
             printDocumentFormat(doc);
+            // #3644 — tags, when the document has any. The endpoint has returned
+            // them since #3096 but only `--json` showed them, so a migration
+            // verifying restored tags had to parse JSON to see its own work.
+            // Printed only when present, by the same rule the response uses: an
+            // untagged document's output is unchanged, and escaped the same way
+            // the table's cell is so a crafted tag cannot drive the terminal.
+            const tags = displayTags(doc.tags);
+            if (tags.length > 0)
+                keyValue("Tags", tags.join(", "));
             // `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
@@ -320,7 +388,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) {
@@ -868,7 +936,11 @@ Permissions (enforced by the server, not the CLI):
                 `${result.added.length} added, ${result.updated.length} updated, ${result.deleted} deleted.`);
         }
         catch (err) {
-            error(err.message);
+            const report = describeBulkFailure(err);
+            if (options.json)
+                json(report.envelope);
+            else
+                error(report.line);
             process.exit(1);
         }
     });
@@ -983,7 +1055,13 @@ Permissions (enforced by the server, not the CLI):
             for (const ignored of input.ignored) {
                 info(`Ignoring ${ignored}: a bulk load reads the snapshot only.`);
             }
+            // #3598 — reading, checking, sorting, cutting and gzipping is this
+            // side's biggest phase on a large input, and it used to be invisible
+            // inside one wall-clock number that also covered the platform's work.
+            const buildStartedAt = Date.now();
             plan = await buildIngestArtifact({ input, schema });
+            const buildMs = Date.now() - buildStartedAt;
+            info(`Built artifact in ${(buildMs / 1000).toFixed(1)}s.`);
             for (const line of summariseIngestPlan(plan))
                 info(line);
             assertIngestConfirmable({
@@ -1028,14 +1106,27 @@ Permissions (enforced by the server, not the CLI):
             }
             if (outcome.message)
                 error(outcome.message);
+            // #3598 — the two sides, side by side. The session's own `timings`
+            // say where the platform's share went; `client` says what this
+            // process spent before and around it, so a slow load can be blamed on
+            // the side that was actually slow.
+            const clientTimings = { buildMs, ...outcome.timings };
             if (options.json) {
-                json(outcome.session ?? { sessionId: outcome.sessionId });
-            }
-            else if (outcome.session) {
-                printIngestSession(outcome.session);
+                json({
+                    ...(outcome.session ?? { sessionId: outcome.sessionId }),
+                    client: clientTimings,
+                });
             }
-            else if (outcome.sessionId) {
-                printResult("Session", outcome.sessionId);
+            else {
+                if (outcome.session) {
+                    printIngestSession(outcome.session);
+                }
+                else if (outcome.sessionId) {
+                    printResult("Session", outcome.sessionId);
+                }
+                for (const [label, value] of ingestClientRows(clientTimings)) {
+                    printResult(label, value);
+                }
             }
             return outcome.exitCode;
         };
@@ -1071,13 +1162,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;
@@ -1145,13 +1237,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;
@@ -1216,6 +1309,96 @@ Permissions (enforced by the server, not the CLI):
             process.exit(1);
         }
     });
+    // #3666, criterion 7 — the one ACTION verb in this group: snapshot the
+    // document now instead of waiting for the size or age trigger. Its exit
+    // codes are `documents ingest`'s, as `docs/cli-design.md` records them, and
+    // for the same reason: giving up on WATCHING a build is not the build
+    // failing.
+    //
+    // Not destructive, so it does not confirm: a seal rotates the overlay the
+    // room is writing to and loses nothing, which is what the size trigger does
+    // on its own several times a day.
+    snapshots
+        .command("build")
+        .description("Snapshot a large document now: seal the open epoch and build a base")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("--wait", "Poll until the build has verified or failed")
+        .option("--timeout <seconds>", "Give up waiting after this many seconds")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        const run = async () => {
+            // Ctrl-C while polling leaves the build running — by then the room is
+            // already building it and giving up on watching is not giving up on
+            // the build — so the signal is handed to the driver rather than
+            // killing the process.
+            const interrupt = new AbortController();
+            const onSignal = () => interrupt.abort();
+            process.on("SIGINT", onSignal);
+            let outcome;
+            try {
+                outcome = await driveSnapshotBuild({
+                    client: {
+                        requestSnapshot: (id) => client.requestDocumentSnapshot(resolvedAppId, id),
+                        getSnapshot: (id, buildId) => client.getDocumentSnapshot(resolvedAppId, id, buildId),
+                    },
+                    documentId,
+                    wait: Boolean(options.wait),
+                    timeoutMs: options.timeout ? Number(options.timeout) * 1000 : null,
+                    signal: interrupt.signal,
+                    onProgress: (line) => info(line),
+                });
+            }
+            finally {
+                process.off("SIGINT", onSignal);
+            }
+            if (outcome.message)
+                error(outcome.message);
+            if (options.json) {
+                // The route's answer as received, with the build the wait settled
+                // on beside it when there was one — so a script branches on the
+                // verdict rather than on an exit code alone.
+                json(outcome.build ? { ...outcome.response, build: outcome.build } : outcome.response);
+                return outcome.exitCode;
+            }
+            if (outcome.response?.sealed === false) {
+                printResult("Sealed", "no — the open epoch carried nothing");
+                printResult("Reason", outcome.response.reason);
+                printResult("Covering build", outcome.response.coveringBuildId ?? "—");
+                return outcome.exitCode;
+            }
+            printResult("Sealed epoch", outcome.response.sealedEpoch);
+            printResult("Open epoch", outcome.response.nextEpoch);
+            printResult("Build", outcome.response.buildId);
+            if (outcome.build) {
+                for (const [label, value] of snapshotBuildRows(outcome.build)) {
+                    printResult(label, value);
+                }
+            }
+            return outcome.exitCode;
+        };
+        let code = 1;
+        try {
+            code = await run();
+        }
+        catch (err) {
+            // The server's own sentence, plus the code a script branches on
+            // (#3403) — a refused loop that only says "too young to seal" leaves
+            // a caller parsing prose to tell it from a permission refusal.
+            error(err.code ? `${err.message} (${err.code})` : err.message);
+            const retryAfterMs = err.details?.retryAfterMs;
+            if (typeof retryAfterMs === "number") {
+                error(`Ask again in ${Math.ceil(retryAfterMs / 1000)}s.`);
+            }
+            code = 1;
+        }
+        // The result has to reach the pipe before the process ends: stdout to a
+        // pipe is asynchronous and `process.exit` does not wait for it.
+        await flushOutput();
+        process.exit(code);
+    });
     // #3433, criterion 10 — the operator audit: `snapshot ⊕ overlays == table`,
     // recomputed on this side with the CLIENT's loader and fold and compared
     // with the authoritative table page by page. The one check that can catch a
@@ -1288,9 +1471,16 @@ Permissions (enforced by the server, not the CLI):
     documents
         .command("transfer-owner")
         .description("Transfer document ownership to another user")
+        // Every positional is declared optional and the action decides which is
+        // which (#3645). A required positional AFTER an optional one makes the
+        // optional one mandatory: commander binds the first value it sees to
+        // `[app-id]` and then reports the required argument missing, so
+        // `transfer-owner <document-id> <new-owner-id>` never reached the action.
+        // What each slot actually requires is enforced below, where the shift is
+        // already known.
         .argument("[app-id]", "App ID (uses current app if not specified)")
-        .argument("<document-id>", "Document ID")
-        .argument("<new-owner-id>", "User ID of the new owner")
+        .argument("[document-id]", "Document ID (required)")
+        .argument("[new-owner-id]", "User ID of the new owner (required)")
         .option("--app <app-id>", "App ID")
         .option("-y, --yes", "Skip confirmation prompt")
         .option("--json", "Output as JSON")
@@ -1362,7 +1552,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) {
@@ -1492,8 +1682,11 @@ Permissions (enforced by the server, not the CLI):
     documents
         .command("export")
         .description("Export a document (Yjs state, blobs, permissions, aliases)")
+        // Optional in commander, required in the action (#3645) — see
+        // `transfer-owner` above for why a `<...>` here would make `[app-id]`
+        // mandatory.
         .argument("[app-id]", "App ID (uses current app if not specified)")
-        .argument("<document-id>", "Document ID to export")
+        .argument("[document-id]", "Document ID to export (required)")
         .option("--app <app-id>", "App ID")
         .option("--output <dir>", "Output directory", "./primitive-export")
         .option("--no-blobs", "Skip blob data")
@@ -1604,8 +1797,9 @@ Permissions (enforced by the server, not the CLI):
     documents
         .command("import")
         .description("Import documents from an export directory")
+        // Optional in commander, required in the action (#3645).
         .argument("[app-id]", "App ID (uses current app if not specified)")
-        .argument("<path>", "Path to export directory or single document directory")
+        .argument("[path]", "Path to export directory or single document directory (required)")
         .option("--app <app-id>", "App ID")
         .option("--aliases <mode>", "Alias conflict handling: overwrite or skip", "skip")
         // `--overwrite` has never replaced a document: the import path issues no