primitive-admin 1.2.0-alpha.6 → 1.2.0-alpha.8

package/dist/src/commands/documents.js

@@ -8,7 +8,7 @@ import { success, error, info, formatTable, formatId, formatDate, json, keyValue
 import { renderAggregateResult } from "../lib/aggregate-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 { pageCursorOption, pageLimitOption, parsePageLimit, printEmptyPage, printPageHint, quoteCursorArg, } 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";
@@ -263,6 +263,7 @@ Examples:
   $ 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 query <document-id> <model-name> --sort '{"createdAt":-1}' --limit 50
   $ 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}'
@@ -725,8 +726,11 @@ Permissions (enforced by the server, not the CLI):
         .option("--app <app-id>", "App ID")
         .option("--filter <json>", "Filter as JSON (e.g. '{\"status\":\"open\"}')")
         .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("--sort <json>", "Sort as JSON, e.g. '{\"createdAt\":-1}'; 1 ascending, -1 descending, key order is precedence; repeat it with --cursor")
+        // Forwarded as typed: the server refuses a value outside 1–10000 with a
+        // sentence naming the maximum, which a CLI-side parse would hide.
+        .option("--limit <n>", "Records per page (default 100, max 10000)")
+        .option("--cursor <cursor>", "Pagination cursor from a previous query (valid only with the same --sort)")
         .option(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
         .option("--json", "Output as JSON")
         .action(async (documentId, modelName, options) => {
@@ -742,9 +746,21 @@ Permissions (enforced by the server, not the CLI):
             process.exit(1);
         }
         const filter = parseFilterOptions(options);
+        // The JSON is checked here; its shape (`{ field: 1 | -1 }`) is the
+        // route's to refuse, with its own `Invalid sort` message.
+        let sort;
+        if (options.sort !== undefined) {
+            try {
+                sort = JSON.parse(options.sort);
+            }
+            catch {
+                error("Invalid --sort JSON.");
+                process.exit(1);
+            }
+        }
         const client = new ApiClient();
         try {
-            const result = await client.queryDocumentRecords(resolvedAppId, documentId, modelName, { filter, limit: options.limit, cursor: options.cursor, documentFormat });
+            const result = await client.queryDocumentRecords(resolvedAppId, documentId, modelName, { filter, sort, limit: options.limit, cursor: options.cursor, documentFormat });
             if (options.json) {
                 json(result);
                 return;
@@ -778,7 +794,9 @@ Permissions (enforced by the server, not the CLI):
             }));
             console.log(formatTable(items, columns));
             if (result.nextCursor) {
-                info(`More results available. Use --cursor ${result.nextCursor}`);
+                // A cursor continues only the sort that minted it.
+                const sortArg = sort !== undefined ? ` --sort ${quoteCursorArg(JSON.stringify(sort))}` : "";
+                info(`More results available. Use --cursor ${result.nextCursor}${sortArg}`);
             }
         }
         catch (err) {
@@ -1467,10 +1485,11 @@ Permissions (enforced by the server, not the CLI):
     // Bulk-load sessions of a large document (#3434, criterion 9): a data noun
     // with `list` and `get` readers, per docs/cli-design.md, beside `snapshots`
     // below. The ACTION verb `documents ingest` is #3435's; these two are how an
-    // operator sees what a session did and why one stopped.
+    // operator sees what a session did and why one stopped, and `abort` (#4475)
+    // is how they give one up.
     const ingests = documents
         .command("ingests")
-        .description("Inspect a large document's bulk-load sessions");
+        .description("Inspect or abort a large document's bulk-load sessions");
     ingests
         .command("list")
         .description("List a large document's bulk-load sessions, newest first")
@@ -1540,12 +1559,52 @@ Permissions (enforced by the server, not the CLI):
             process.exit(1);
         }
     });
+    // Destructive — what the session uploaded is discarded — so it confirms
+    // unless `-y`, and a non-TTY stdin without `-y` is refused before any
+    // request, as `documents ingest` refuses it (#4475).
+    ingests
+        .command("abort")
+        .description("Abort a bulk-load session and discard what it uploaded")
+        .argument("<document-id>", "Document ID")
+        .argument("<session-id>", "Session ID")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip the confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, sessionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            if (!process.stdin.isTTY) {
+                error("Aborting a bulk load discards what it uploaded. " +
+                    "Re-run with -y to confirm it without a prompt.");
+                process.exit(1);
+            }
+            const confirmed = await confirmPrompt(`Abort bulk load ${sessionId} on ${documentId}? What it uploaded is ` +
+                "discarded; rows a committed load already applied stay.");
+            if (!confirmed) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            const session = await client.abortDocumentIngest(resolvedAppId, documentId, sessionId);
+            if (options.json) {
+                json(session);
+                return;
+            }
+            printIngestSession(session);
+        }
+        catch (err) {
+            error(describeDocumentFailure(err));
+            process.exit(1);
+        }
+    });
     // Snapshot builds of a large document (#3432, criterion 9): a data noun
     // with `list` and `get` readers, per docs/cli-design.md, over the app API's
     // read-only inspection routes.
     const snapshots = documents
         .command("snapshots")
-        .description("Inspect a large document's snapshot builds and their verification");
+        .description("Inspect a large document's snapshots (its segments)");
     snapshots
         .command("list")
         .description("List a large document's snapshot builds, newest first")
@@ -1615,7 +1674,7 @@ Permissions (enforced by the server, not the CLI):
     });
     snapshots
         .command("get")
-        .description("Show one snapshot build, its verification result and where its time went")
+        .description("Show one snapshot (a segment): its state, rows and chunks")
         .argument("<document-id>", "Document ID")
         .argument("<build-id>", "Build ID")
         .option("--app <app-id>", "App ID")
@@ -1653,10 +1712,10 @@ Permissions (enforced by the server, not the CLI):
     // on its own several times a day.
     snapshots
         .command("build")
-        .description("Snapshot a large document now: seal the open epoch and build a base")
+        .description("Snapshot a large document now: start a segment export of its records")
         .argument("<document-id>", "Document ID")
         .option("--app <app-id>", "App ID")
-        .option("--wait", "Poll until the build has verified or failed")
+        .option("--wait", "Poll until the segment is complete or failed")
         .option("--timeout <seconds>", "Give up waiting after this many seconds")
         .option("--json", "Output as JSON")
         .action(async (documentId, options) => {