primitive-admin 1.2.0-alpha.0 → 1.2.0-alpha.10

package/dist/src/commands/db3.js

@@ -0,0 +1,1052 @@
+import { ApiClient } from "../lib/api-client.js";
+import { resolveAppId } from "../lib/config.js";
+import { error, flushOutput, formatDate, formatTable, info, json, result as printResult, success } from "../lib/output.js";
+import { confirmPrompt } from "../lib/confirm-prompt.js";
+import { normalizeCliListEnvelope, wholeListEnvelope } from "../lib/paginate.js";
+import { parseDataOption } from "../lib/data-input.js";
+import { DB3_ROUTES } from "../lib/records-verbs.js";
+import { DB3_LOAD_ROUTES } from "../lib/load-routes.js";
+import { declarationOfSchemaAnswer, declaredModelNames, exportDb3, loadDb3Rows, pendingRegistrations, planDb3Import, readDb3Manifest, readExportedBlobs, resolvedTypeName, } from "../lib/db3-export.js";
+import fs from "fs";
+import path from "path";
+import { db3IndexRefusalLines, db3IndexTableRows } from "../lib/db3-index-output.js";
+import { parseCustodianOrExit } from "../lib/custodian.js";
+import { pageCursorOption, pageLimitOption, parsePageLimit, printEmptyPage, printPageHint } from "../lib/list-options.js";
+import { BULK_DATA_FILE_HELP, aggregateRecordsAction, bulkRecordsAction, countRecordsAction, deleteRecordAction, describeAction, describeRecordsFailure, displayTags, inspectAction, modelsAction, patchRecordAction, queryRecordsAction, saveRecordAction, schemaAction, statsAction, ingestAction, listIngestsAction, getIngestAction, abortIngestAction, listSnapshotsAction, getSnapshotAction, buildSnapshotAction, } from "./documents.js";
+/**
+ * A refused index call: the server's sentence, its code and status, then one
+ * line per detail the code names (the duplicate keys, the origins keeping
+ * the index, the index a name belongs to, the stored format).
+ */
+function refuse(err) {
+    error(describeRecordsFailure(err));
+    for (const line of db3IndexRefusalLines(err))
+        console.error(`  ${line}`);
+    process.exit(1);
+}
+/** A refused db3 call: the server's sentence, its code and its status, then exit 1. */
+function fail(err) {
+    error(describeRecordsFailure(err));
+    process.exit(1);
+}
+/** `on` or `off` as a boolean, or exit 1 naming `label` before any request. */
+function parseOnOff(value, label) {
+    if (value === "on")
+        return true;
+    if (value === "off")
+        return false;
+    error(`${label} must be "on" or "off".`);
+    process.exit(1);
+}
+/** The lines a db3 is printed as: its id, title, custodian, sync and type. */
+function printDb3(row) {
+    printResult("ID", row.id);
+    printResult("Title", row.title);
+    printResult("Custodian", row.custodian ?? "none");
+    printResult("Sync", row.sync === false ? "off" : "on");
+    printResult("Type", row.type ?? "none");
+}
+/**
+ * `primitive db3` (#4696, #4804): a db3's lifecycle (`create`, `get`,
+ * `list`, `delete`, `stats`), its sync, app access and custody, its indexes,
+ * and its records, schema and room through the `db3/:id/*` routes.
+ *
+ * The records, schema and inspect verbs are the `documents` verbs' twins:
+ * they share their action code (`./documents.ts`) through the db3 routes
+ * (`DB3_ROUTES`), take the same arguments and flags but `--document-format`
+ * (a db3 is format 3), and print what their twins print.
+ */
+export function registerDb3Commands(program) {
+    const db3 = program
+        .command("db3")
+        .description("Work with db3s: create, read, list and delete them, their sync, app access and custody, indexes, records, schema and room");
+    // ---- Indexes ----
+    const indexes = db3.command("indexes").description("List, register and drop a db3's indexes");
+    indexes
+        .command("list")
+        .description("List a db3's indexes: declared and registered")
+        .argument("<db3-id>", "db3 ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const { indexes: list } = await client.listDb3Indexes(resolvedAppId, db3Id);
+            if (options.json) {
+                json(wholeListEnvelope(list));
+                return;
+            }
+            if (list.length === 0) {
+                info("No indexes on this db3.");
+                return;
+            }
+            console.log(formatTable(db3IndexTableRows(list), [
+                { header: "NAME", key: "name", flex: true },
+                { header: "MODEL", key: "model" },
+                { header: "FIELDS", key: "fields" },
+                { header: "UNIQUE", key: "unique" },
+                { header: "ORIGINS", key: "origins" },
+            ]));
+        }
+        catch (err) {
+            refuse(err);
+        }
+    });
+    indexes
+        .command("register")
+        .description("Register an index on a db3 model's field, or a named composite over several fields")
+        .argument("<db3-id>", "db3 ID")
+        .requiredOption("--model <model>", "Model name")
+        .requiredOption("--field <field>", "Field to index (repeat it for a composite unique index, which also needs --unique and --name)", (value, previous = []) => previous.concat(value))
+        .option("--unique", "Enforce that no two records share the key")
+        .option("--name <name>", "Name the index (idx_named_<model>_<name>)")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const fields = options.field;
+        const body = {
+            model: options.model,
+            ...(fields.length === 1 ? { field: fields[0] } : { fields }),
+            ...(options.unique ? { unique: true } : {}),
+            ...(options.name !== undefined ? { name: options.name } : {}),
+        };
+        const client = new ApiClient();
+        try {
+            const { index } = await client.registerDb3Index(resolvedAppId, db3Id, body);
+            if (options.json) {
+                json(index);
+                return;
+            }
+            success(`Registered ${index.name} on ${index.model} (${index.fields.join(", ")}${index.unique ? ", unique" : ""}).`);
+        }
+        catch (err) {
+            refuse(err);
+        }
+    });
+    indexes
+        .command("drop")
+        .description("Drop a db3 index you registered (one a declaration keeps stays)")
+        .argument("<db3-id>", "db3 ID")
+        .argument("<name>", "Index name, as `db3 indexes list` prints it")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, name, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirmed;
+            try {
+                confirmed = await confirmPrompt(`Drop index ${name} from db3 ${db3Id}?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirmed) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            const answer = await client.dropDb3Index(resolvedAppId, db3Id, name);
+            if (options.json) {
+                json(answer);
+                return;
+            }
+            success(`Dropped ${answer.name}.`);
+        }
+        catch (err) {
+            refuse(err);
+        }
+    });
+    // ---- Records: the `documents records` verbs' twins ----
+    const records = db3.command("records").description("Query and write a db3's records");
+    records
+        .command("query")
+        .description("Query records in a db3 model")
+        .argument("<db3-id>", "db3 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("--filter-file <path>", "Read filter from a JSON or TOML file")
+        .option("--sort <json>", "Sort as JSON, e.g. '{\"createdAt\":-1}'; 1 ascending, -1 descending, key order is precedence; repeat it with --cursor")
+        .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("--include <json>", "Related records as a JSON array of include specs, e.g. '[{\"model\":\"customer\",\"type\":\"refersTo\",\"sourceField\":\"customerId\"}]'; answered as _related")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, modelName, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        await queryRecordsAction(DB3_ROUTES, resolvedAppId, db3Id, modelName, options);
+    });
+    records
+        .command("count")
+        .description("Count records in a db3 model")
+        .argument("<db3-id>", "db3 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("--filter-file <path>", "Read filter from a JSON or TOML file")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, modelName, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        await countRecordsAction(DB3_ROUTES, resolvedAppId, db3Id, modelName, options);
+    });
+    records
+        .command("aggregate")
+        .description("Aggregate records in a db3 model (count/sum/avg/min/max, optional group-by)")
+        .argument("<db3-id>", "db3 ID")
+        .argument("<model-name>", "Model name")
+        .option("--app <app-id>", "App ID")
+        .requiredOption("--op <operation>", "Aggregate operation: count|sum|avg|min|max")
+        .option("--field <field>", "Field to aggregate (required for sum/avg/min/max)")
+        .option("--group-by <field>", "Group results by this field (repeatable)", (value, previous = []) => previous.concat(value), [])
+        .option("--filter <json>", "Filter as JSON")
+        .option("--filter-file <path>", "Read filter from a JSON or TOML file")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, modelName, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        await aggregateRecordsAction(DB3_ROUTES, resolvedAppId, db3Id, modelName, options);
+    });
+    records
+        .command("save")
+        .description("Create or replace a record in a db3 model")
+        .argument("<db3-id>", "db3 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 (db3Id, modelName, options) => {
+        const data = parseDataOption(options, "record fields");
+        const resolvedAppId = resolveAppId(undefined, options);
+        await saveRecordAction(DB3_ROUTES, resolvedAppId, db3Id, modelName, data, options);
+    });
+    records
+        .command("patch")
+        .description("Merge fields into an existing record in a db3 model")
+        .argument("<db3-id>", "db3 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 (db3Id, modelName, recordId, options) => {
+        const data = parseDataOption(options, "fields to merge");
+        const resolvedAppId = resolveAppId(undefined, options);
+        await patchRecordAction(DB3_ROUTES, resolvedAppId, db3Id, modelName, recordId, data, options);
+    });
+    records
+        .command("delete")
+        .description("Delete a record from a db3 model")
+        .argument("<db3-id>", "db3 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 (db3Id, modelName, recordId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        await deleteRecordAction(DB3_ROUTES, resolvedAppId, db3Id, modelName, recordId, options);
+    });
+    records
+        .command("bulk")
+        .description("Apply an atomic create/patch/delete/upsert operations blob to a db3")
+        .argument("<db3-id>", "db3 ID")
+        .requiredOption("--data-file <file>", BULK_DATA_FILE_HELP)
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, options) => {
+        await bulkRecordsAction(DB3_ROUTES, db3Id, options);
+    });
+    records
+        .command("models")
+        .description("List model names in a db3")
+        .argument("<db3-id>", "db3 ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, options) => {
+        await modelsAction(DB3_ROUTES, db3Id, options);
+    });
+    records
+        .command("describe")
+        .description("Show a db3 model's fields and indexes")
+        .argument("<db3-id>", "db3 ID")
+        .argument("<model-name>", "Model name")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, modelName, options) => {
+        await describeAction(DB3_ROUTES, db3Id, modelName, options);
+    });
+    records
+        .command("increment")
+        .description("Add to numeric fields of a record in a db3 model (a missing or non-numeric field starts at 0)")
+        .argument("<db3-id>", "db3 ID")
+        .argument("<model-name>", "Model name")
+        .argument("<record-id>", "Record ID")
+        .option("--app <app-id>", "App ID")
+        .option("--data <json>", "Each field's delta as JSON (e.g. '{\"qty\":2}')")
+        .option("--data-file <file>", "Read the deltas from a JSON file")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, modelName, recordId, options) => {
+        const fields = parseDataOption(options, "field deltas");
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const answer = await new ApiClient().incrementDb3Record(resolvedAppId, db3Id, modelName, recordId, { fields });
+            if (options.json) {
+                json(answer);
+                return;
+            }
+            for (const [field, value] of Object.entries(answer.values ?? {}))
+                printResult(field, value);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    // ---- Schema and room: the `documents schema` and `documents inspect` twins ----
+    db3
+        .command("schema")
+        .description("Show a db3's models and fields as declared and observed, or export them as a schema.toml")
+        .argument("<db3-id>", "db3 ID")
+        .option("--app <app-id>", "App ID")
+        .option("--toml", "Print a schema.toml the client's schemaToml option and js-bao-codegen-v2 accept")
+        .option("--output <file>", "With --toml: write the TOML to this file (overwriting it) instead of stdout")
+        .option("--json", "Output the /schema answer as JSON")
+        .action(async (db3Id, options) => {
+        await schemaAction(DB3_ROUTES, db3Id, options);
+    });
+    // ---- Type (#4802): attach a db3 type, or read the one it has ----
+    const type = db3.command("type").description("Attach a db3 type to a db3, or show the one it has");
+    type
+        .command("attach")
+        .description("Install a type's current revision in a db3, whole or not at all (a type is never detached)")
+        .argument("<db3-id>", "db3 ID")
+        .argument("<name>", "Type name")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, name, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const answer = await new ApiClient().attachDb3Type(resolvedAppId, db3Id, name);
+            if (options.json) {
+                json(answer);
+                return;
+            }
+            success(`${db3Id} is of type ${answer.type}: ${answer.outcome} (revision ${new Date(answer.revision.generation).toISOString()})`);
+        }
+        catch (err) {
+            if (options.json) {
+                json({ ok: false, code: err?.code ?? null, message: err?.message ?? String(err), details: err?.details ?? null });
+                process.exit(1);
+            }
+            error(describeRecordsFailure(err));
+            for (const reason of err?.details?.reasons ?? [])
+                console.error(`  ${reason.path}: ${reason.reason}`);
+            if (err?.details?.installed)
+                console.error(`  installed: ${err.details.installed}`);
+            process.exit(1);
+        }
+    });
+    type
+        .command("get")
+        .description("Show the type a db3's row names, its revision, and what the db3's room holds")
+        .argument("<db3-id>", "db3 ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const answer = await new ApiClient().getDb3Type(resolvedAppId, db3Id);
+            if (options.json) {
+                json(answer);
+                return;
+            }
+            const revision = (r) => (r ? `${new Date(r.generation).toISOString()} (${String(r.hash).slice(0, 12)})` : "—");
+            console.log(`Type:      ${answer.type ?? "none"}`);
+            console.log(`Revision:  ${revision(answer.revision)}`);
+            console.log(`Installed: ${answer.installed ? `${answer.installed.name} ${revision(answer.installed.revision)}` : "none"}`);
+        }
+        catch (err) {
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
+    });
+    db3
+        .command("inspect")
+        .description("Show a db3's room: epochs, log number, floors, writers, the bulk load in progress and checkpoint")
+        .argument("<db3-id>", "db3 ID")
+        .option("--app <app-id>", "App ID")
+        .option("--refused <session-id>", "Print every row that bulk load refused, with its code, instead")
+        .option("--limit <n>", "With --refused: rows per page read (1–100)", "100")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, options) => {
+        await inspectAction(DB3_ROUTES, db3Id, options);
+    });
+    // ---- Bulk loads, snapshots, export and import (#4889) ----
+    // The `documents ingest|ingests|snapshots` verbs' twins over `db3/:id/*`:
+    // the same action code (`./documents.ts`), arguments and flags.
+    db3
+        .command("ingest")
+        .description("Bulk-load records into a db3 from a directory")
+        .argument("<db3-id>", "db3 ID")
+        .requiredOption("--input <dir>", "Directory of <model>.ndjson[.gz] files, or a `db3 export` or `documents export` output")
+        .option("--app <app-id>", "App ID")
+        .option("--reserve-epoch <when>", "Reserve the load's epoch at session open (open, the default) or at commit")
+        .option("--mode <mode>", "Merge the rows (merge, the default), or refresh: also delete every record of the input's models that no row names")
+        .option("-y, --yes", "Skip the confirmation prompt")
+        .option("--no-wait", "Exit once the session is committed")
+        .option("--timeout <seconds>", "Give up waiting after this many seconds")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+Rows a load refuses are listed by \`primitive db3 inspect <db3-id> --refused <session-id>\`.
+`)
+        .action(async (db3Id, options) => {
+        await ingestAction(DB3_LOAD_ROUTES, db3Id, options);
+    });
+    const ingests = db3.command("ingests").description("Inspect or abort a db3's bulk-load sessions");
+    ingests
+        .command("list")
+        .description("List a db3's bulk-load sessions, newest first")
+        .argument("<db3-id>", "db3 ID")
+        .option("--app <app-id>", "App ID")
+        .option("--limit <n>", "Page size (1–100)", "20")
+        .option("--cursor <cursor>", "Continue from a previous page's nextCursor")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, options) => {
+        await listIngestsAction(DB3_LOAD_ROUTES, db3Id, options);
+    });
+    ingests
+        .command("get")
+        .description("Show one bulk-load session, its progress and why it stopped")
+        .argument("<db3-id>", "db3 ID")
+        .argument("<session-id>", "Session ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, sessionId, options) => {
+        await getIngestAction(DB3_LOAD_ROUTES, db3Id, sessionId, options);
+    });
+    ingests
+        .command("abort")
+        .description("Abort a bulk-load session and discard what it uploaded")
+        .argument("<db3-id>", "db3 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 (db3Id, sessionId, options) => {
+        await abortIngestAction(DB3_LOAD_ROUTES, db3Id, sessionId, options);
+    });
+    const snapshots = db3.command("snapshots").description("Inspect or start a db3's segment exports");
+    snapshots
+        .command("list")
+        .description("List a db3's segment exports, newest first")
+        .argument("<db3-id>", "db3 ID")
+        .option("--app <app-id>", "App ID")
+        .option("--limit <n>", "Page size (1–100)", "20")
+        .option("--cursor <cursor>", "Continue from a previous page's nextCursor")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, options) => {
+        await listSnapshotsAction(DB3_LOAD_ROUTES, db3Id, options);
+    });
+    snapshots
+        .command("get")
+        .description("Show one segment export: its state, log number, rows and chunks")
+        .argument("<db3-id>", "db3 ID")
+        .argument("<segment-id>", "Segment ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, segmentId, options) => {
+        await getSnapshotAction(DB3_LOAD_ROUTES, db3Id, segmentId, options);
+    });
+    snapshots
+        .command("build")
+        .description("Start a segment export of a db3's records now")
+        .argument("<db3-id>", "db3 ID")
+        .option("--app <app-id>", "App ID")
+        .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 (db3Id, options) => {
+        await buildSnapshotAction(DB3_LOAD_ROUTES, db3Id, options);
+    });
+    db3
+        .command("export")
+        .description("Export a db3 to a directory: its rows, type, declaration and blobs")
+        .argument("<db3-id>", "db3 ID")
+        .option("--app <app-id>", "App ID")
+        .option("--output <dir>", "Directory to write (default ./primitive-export/db3/<db3-id>)")
+        .option("--no-blobs", "Leave the blobs out")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+The directory holds db3.json (the db3's id, title, tags, type and revision,
+its declaration and registered indexes, and the log number the rows are at),
+the rows under snapshot/, chain.json and the blobs under blobs/. It holds no
+grant, custody, sync state or alias. \`primitive db3 import\` loads it.
+`)
+        .action(async (db3Id, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const dir = path.resolve(options.output ?? path.join("primitive-export", "db3", db3Id));
+        let code = 0;
+        try {
+            const exported = await exportDb3(new ApiClient(), resolvedAppId, db3Id, dir, {
+                blobs: options.blobs !== false,
+                onProgress: (line) => info(line),
+            });
+            if (options.json) {
+                json({ id: db3Id, exportPath: dir, rows: exported.rows, blobs: exported.blobs, type: exported.manifest.type, lsn: exported.manifest.lsn });
+            }
+            else {
+                success(`Exported db3 ${db3Id} (${exported.manifest.title || "untitled"}) to ${dir}`);
+                printResult("Rows", exported.rows);
+                printResult("Blobs", options.blobs === false ? "left out" : exported.blobs);
+                printResult("Type", exported.manifest.type?.name ?? "none");
+                printResult("Log number", exported.manifest.lsn);
+            }
+        }
+        catch (err) {
+            error(err?.statusCode ? describeRecordsFailure(err) : err?.message ?? String(err));
+            code = 1;
+        }
+        await flushOutput();
+        process.exit(code);
+    });
+    db3
+        .command("import")
+        .description("Import a `db3 export` directory: a new db3 of its type, or --into an existing one")
+        .argument("<path>", "The export's directory")
+        .option("--app <app-id>", "App ID")
+        .option("--into <db3-id>", "Load into this db3 instead of creating one (of the same type and declaration)")
+        .option("--keep-id", "Create the db3 under the export's id (an app owner or admin; the id must be free in this app)")
+        .option("--title <title>", "The new db3's title (default: the export's)")
+        .option("--type <name>", "The db3 type to create it with (default: the export's)")
+        .option("--untyped", "Load into an untyped db3, registering the export's indexes and uniques first")
+        .option("--no-blobs", "Leave the blobs out")
+        .option("-y, --yes", "Skip the confirmation prompt (--into)")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+Every check runs before anything is written: the type must be one the app
+has (primitive db3-types push), with the export's declaration; an --into
+target must be of the export's type and declare its models alike; and the
+blobs keep their ids, so the exported db3 must be gone from the app (or
+import into another app, or pass --no-blobs). A load that refuses a row exits
+1 naming \`primitive db3 inspect <db3-id> --refused <session-id>\`.
+
+--keep-id creates the db3 under the export's id, so what stored that id still
+finds it: the id must be free in this app (delete the exported db3 first, or
+import into another app). Without it the import gets a new id.
+`)
+        .action(async (dir, options) => {
+        const code = await importAction(dir, options);
+        await flushOutput();
+        process.exit(code);
+    });
+    // ---- Lifecycle (#4804) ----
+    db3
+        .command("create")
+        .description("Create a db3")
+        .argument("<title>", "db3 title")
+        .option("--type <name>", "A db3 type of the app: its current revision is installed before the db3 answers")
+        .option("--sync <on|off>", "off: no client ever opens the db3 over a socket (app owners and admins only)")
+        .option("--custodian <custodian>", '"app" or "user:<user-id>" (a member of the app)')
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+Custody:
+  A member's token creates a db3 the member holds. An admin token's create is
+  held by the app, which no member owns, unless --custodian names a member.
+`)
+        .action(async (title, options) => {
+        const sync = options.sync === undefined ? undefined : parseOnOff(options.sync, "--sync");
+        const custodian = options.custodian === undefined ? undefined : parseCustodianOrExit(options.custodian, "--custodian");
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const created = await new ApiClient().createDb3(resolvedAppId, {
+                title,
+                ...(options.type !== undefined ? { type: options.type } : {}),
+                ...(sync !== undefined ? { sync } : {}),
+                ...(custodian !== undefined ? { custodian } : {}),
+            });
+            if (options.json) {
+                json(created);
+                return;
+            }
+            success("db3 created.");
+            printDb3(created);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    db3
+        .command("get")
+        .description("Show a db3, and the caller's access to it")
+        .argument("<db3-id>", "db3 ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const row = await new ApiClient().getDb3(resolvedAppId, db3Id);
+            if (options.json) {
+                json(row);
+                return;
+            }
+            printDb3(row);
+            printResult("Created By", row.createdBy);
+            printResult("Created", formatDate(row.createdAt));
+            printResult("Modified", formatDate(row.modifiedAt));
+            const tags = displayTags(row.tags);
+            if (tags.length > 0)
+                printResult("Tags", tags.join(", "));
+            if (row.permission)
+                printResult("Your Permission", row.permission);
+            if (row.accessSource)
+                printResult("Access Source", row.accessSource);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    db3
+        .command("list")
+        .description("List one custodian's db3s, oldest first")
+        .requiredOption("--custodian <custodian>", '"app" or "user:<user-id>"')
+        .option("--app <app-id>", "App ID")
+        .addOption(pageLimitOption())
+        .addOption(pageCursorOption())
+        .option("--json", "Output as JSON")
+        .allowExcessArguments(false)
+        .action(async (options) => {
+        const limit = parsePageLimit(options.limit);
+        const custodian = parseCustodianOrExit(options.custodian, "--custodian");
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const page = normalizeCliListEnvelope(await new ApiClient().listDb3ByCustodian(resolvedAppId, custodian, {
+                ...(limit !== undefined ? { limit } : {}),
+                ...(options.cursor ? { cursor: options.cursor } : {}),
+            }));
+            if (options.json) {
+                json(page);
+                return;
+            }
+            if (page.items.length === 0) {
+                printEmptyPage(page, "db3s");
+                return;
+            }
+            const rows = page.items.map((row) => ({
+                id: row.id,
+                title: row.title ?? "",
+                custodian: row.custodian ?? "none",
+                sync: row.sync === false ? "off" : "on",
+                type: row.type ?? "none",
+                createdAt: row.createdAt,
+            }));
+            console.log(formatTable(rows, [
+                { header: "ID", key: "id" },
+                { header: "TITLE", key: "title", flex: true },
+                { header: "CUSTODIAN", key: "custodian" },
+                { header: "SYNC", key: "sync" },
+                { header: "TYPE", key: "type" },
+                { header: "CREATED", key: "createdAt", format: formatDate },
+            ]));
+            printPageHint(page);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    db3
+        .command("delete")
+        .description("Delete a db3 and all its data (records, blobs, aliases, permissions)")
+        .argument("<db3-id>", "db3 ID")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirmed;
+            try {
+                confirmed = await confirmPrompt(`Delete db3 ${db3Id}? This permanently deletes its records, blobs, aliases and permissions.`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirmed) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        try {
+            const answer = await new ApiClient().deleteDb3(resolvedAppId, db3Id);
+            if (options.json) {
+                json(answer);
+                return;
+            }
+            success(`db3 ${db3Id} deleted.`);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    db3
+        .command("stats")
+        .description("Show a db3's record/model/blob counts and size")
+        .argument("<db3-id>", "db3 ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, options) => {
+        await statsAction(DB3_ROUTES, db3Id, options);
+    });
+    // ---- Sync (#4799, #4804) ----
+    const sync = db3.command("sync").description("Show or change whether a db3 is synced");
+    sync
+        .command("get")
+        .description("Print on or off: whether clients open the db3 over a socket")
+        .argument("<db3-id>", "db3 ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const answer = await new ApiClient().getDb3Sync(resolvedAppId, db3Id);
+            if (options.json) {
+                json(answer);
+                return;
+            }
+            console.log(answer.sync ? "on" : "off");
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    sync
+        .command("set")
+        .description("Turn a db3's sync on or off (app owners and admins only)")
+        .argument("<db3-id>", "db3 ID")
+        .argument("<on|off>", "on or off")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, state, options) => {
+        const on = parseOnOff(state, "The sync state");
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const answer = await new ApiClient().setDb3Sync(resolvedAppId, db3Id, on);
+            if (options.json) {
+                json(answer);
+                return;
+            }
+            success(answer.changed ? `Sync is ${on ? "on" : "off"} for ${db3Id}.` : `Sync was already ${on ? "on" : "off"} for ${db3Id}.`);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    // ---- App access (#4801, #4804) ----
+    const appAccess = db3.command("app-access").description("Show or change the access every user of the app holds on a db3");
+    appAccess
+        .command("get")
+        .description("Print reader, read-write or none")
+        .argument("<db3-id>", "db3 ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const answer = await new ApiClient().getDb3AppAccess(resolvedAppId, db3Id);
+            if (options.json) {
+                json(answer);
+                return;
+            }
+            console.log(answer.level ?? "none");
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    appAccess
+        .command("set")
+        .description("Grant the db3 to every user of the app, or remove the grant with none (app owners and admins only)")
+        .argument("<db3-id>", "db3 ID")
+        .argument("<level>", "reader, read-write or none")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, level, options) => {
+        if (!["reader", "read-write", "none"].includes(level)) {
+            error('The level must be "reader", "read-write" or "none".');
+            process.exit(1);
+        }
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const answer = await new ApiClient().setDb3AppAccess(resolvedAppId, db3Id, level === "none" ? null : level);
+            if (options.json) {
+                json(answer);
+                return;
+            }
+            success(`App access on ${db3Id}: ${answer.level ?? "none"}${answer.changed ? "" : " (unchanged)"}.`);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    // ---- Custody (#4800, #4804): through the admin API ----
+    db3
+        .command("transfer")
+        .description("Transfer a db3 to another user or to the app")
+        .argument("<db3-id>", "db3 ID")
+        .argument("<custodian>", '"user:<user-id>" (a member of the app) or "app"')
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .allowExcessArguments(false)
+        .addHelpText("after", `
+The custodian and the owner row move together: a user custodian holds the
+owner row and the previous owner keeps read-write; moving to the app deletes
+every owner row. No other grant changes.
+`)
+        .action(async (db3Id, custodianArg, options) => {
+        const to = parseCustodianOrExit(custodianArg, "custodian");
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const answer = await new ApiClient().transferDb3(resolvedAppId, db3Id, to);
+            if (options.json) {
+                json(answer);
+                return;
+            }
+            success(`db3 ${db3Id} transferred.`);
+            printResult("Custodian", answer.custodian);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    const ownerRow = db3.command("owner-row").description("Remove or restore the owner row of the user who holds a db3");
+    ownerRow
+        .command("set")
+        .description("present restores the custodian user's owner row, absent removes it; the custodian stays")
+        .argument("<db3-id>", "db3 ID")
+        .argument("<present|absent>", "present or absent")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (db3Id, state, options) => {
+        if (state !== "present" && state !== "absent") {
+            error('The owner row must be "present" or "absent".');
+            process.exit(1);
+        }
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const answer = await new ApiClient().setDb3OwnerRow(resolvedAppId, db3Id, state === "present");
+            if (options.json) {
+                json(answer);
+                return;
+            }
+            printResult("Custodian", answer.custodian);
+            printResult("Owner row", answer.ownerRow ? "present" : "absent");
+            printResult("Changed", answer.changed ? "yes" : "no");
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+/** What to do about a refused create of the import's db3 (#4921), after the refusal itself. */
+function createRefusalAdvice(code) {
+    switch (code) {
+        case "DB3_ID_EXISTS":
+            return " This app holds the export's id: delete that db3 first, import into another app, or import without --keep-id.";
+        case "DB3_CREATE_IN_PROGRESS":
+            return " Another create of this id is running: try again shortly.";
+        case "DB3_ID_INVALID":
+            return " The manifest's id is not a ULID this server accepts: import without --keep-id.";
+        case "DB3_ID_NOT_ALLOWED":
+            return " Keeping an id needs an app owner or admin: log in as one, or import without --keep-id.";
+        default:
+            return "";
+    }
+}
+/** `db3 import`: the reads, the plan, then the writes; answers the exit code. */
+async function importAction(dir, options) {
+    const resolvedAppId = resolveAppId(undefined, options);
+    const client = new ApiClient();
+    const root = path.resolve(dir);
+    try {
+        const manifest = readDb3Manifest(root);
+        if (!manifest) {
+            error(`${root} holds no db3.json, so it is not a \`db3 export\` directory. ` +
+                "Load a directory of rows into an existing db3 with `primitive db3 ingest <db3-id> --input <dir>`.");
+            return 1;
+        }
+        const flags = {
+            ...(options.into ? { into: String(options.into) } : {}),
+            ...(options.title !== undefined ? { title: String(options.title) } : {}),
+            ...(options.type !== undefined ? { type: String(options.type) } : {}),
+            untyped: Boolean(options.untyped),
+            noBlobs: options.blobs === false,
+            keepId: Boolean(options.keepId),
+        };
+        if (flags.keepId && flags.into) {
+            const refused = planDb3Import(manifest, flags, { blobCount: 0 });
+            if ("refusal" in refused)
+                error(refused.refusal);
+            return 1;
+        }
+        // Every read before any write.
+        const blobs = flags.noBlobs ? [] : readExportedBlobs(root);
+        const facts = { blobCount: blobs.length };
+        const named = resolvedTypeName(manifest, flags);
+        if (named && !flags.untyped) {
+            try {
+                facts.type = await client.getDb3TypeConfig(resolvedAppId, named);
+            }
+            catch (err) {
+                if (err?.statusCode !== 404)
+                    throw err;
+                facts.type = null;
+            }
+        }
+        if (flags.into) {
+            const row = await client.getDb3(resolvedAppId, flags.into);
+            let declaredModels = [];
+            if (row?.type) {
+                const targetType = facts.type?.name === row.type ? facts.type : await client.getDb3TypeConfig(resolvedAppId, String(row.type));
+                declaredModels = declaredModelNames(targetType?.schema);
+            }
+            const declaration = declarationOfSchemaAnswer(await client.getDb3Schema(resolvedAppId, flags.into), { declaredModels });
+            const listed = await client.listDb3Indexes(resolvedAppId, flags.into);
+            facts.target = { row, declaration, indexes: listed?.indexes ?? [] };
+        }
+        // One read of the source's id, for the blobs and for --keep-id alike.
+        if (blobs.length > 0 || flags.keepId) {
+            try {
+                await client.getDb3(resolvedAppId, manifest.id);
+                facts.sourceExists = true;
+            }
+            catch (err) {
+                if (err?.statusCode !== 404)
+                    throw err;
+                facts.sourceExists = false;
+            }
+        }
+        const plan = planDb3Import(manifest, flags, facts);
+        if ("refusal" in plan) {
+            error(plan.refusal);
+            for (const line of plan.lines ?? [])
+                console.error(`  ${line}`);
+            return 1;
+        }
+        for (const note of plan.notes)
+            info(note);
+        let db3Id;
+        let created = false;
+        if (plan.into) {
+            if (!options.yes) {
+                let confirmed;
+                try {
+                    confirmed = await confirmPrompt(`Load the export's rows into db3 ${plan.into}? Rows with an id it already holds are replaced.`);
+                }
+                catch (err) {
+                    error(err.message);
+                    return 1;
+                }
+                if (!confirmed) {
+                    info("Nothing was written.");
+                    return 1;
+                }
+            }
+            db3Id = plan.into;
+        }
+        else {
+            let row;
+            try {
+                row = await client.createDb3(resolvedAppId, plan.create);
+            }
+            catch (err) {
+                error(`${describeRecordsFailure(err)}${createRefusalAdvice(err?.code)} Nothing was written.`);
+                return 1;
+            }
+            db3Id = row.id;
+            created = true;
+            if (!options.json)
+                success(`Created db3 ${db3Id}${plan.typeName ? ` of type ${plan.typeName}` : ""}.`);
+        }
+        let register = plan.register;
+        if (created && plan.typeName && register.length > 0) {
+            // A typed db3 has its type's indexes from the create: register only what they leave out.
+            const pending = pendingRegistrations(register, (await client.listDb3Indexes(resolvedAppId, db3Id))?.indexes ?? []);
+            if (pending.conflicts.length) {
+                error(`The export's indexes clash with type ${plan.typeName}'s by name; db3 ${db3Id} was created and holds no rows.`);
+                for (const line of pending.conflicts)
+                    console.error(`  ${line}`);
+                return 1;
+            }
+            register = pending.register;
+        }
+        for (const registration of register) {
+            await client.registerDb3Index(resolvedAppId, db3Id, registration);
+        }
+        const outcome = await loadDb3Rows(client, resolvedAppId, db3Id, root, (line) => info(line));
+        const session = outcome?.session ?? null;
+        if (outcome && outcome.exitCode !== 0) {
+            if (outcome.message)
+                error(outcome.message);
+            if (options.json)
+                json({ id: db3Id, created, keptId: flags.keepId, session, exitCode: outcome.exitCode });
+            return 1;
+        }
+        const refusedRows = Number(session?.refusedRows ?? 0);
+        let blobsUploaded = 0;
+        if (plan.blobs) {
+            for (const blob of blobs) {
+                const data = fs.readFileSync(path.join(root, "blobs", `${blob.blobId}.bin`));
+                try {
+                    await client.uploadDb3Blob(resolvedAppId, db3Id, blob.blobId, data, {
+                        filename: blob.filename,
+                        contentType: blob.contentType,
+                        sha256: blob.sha256,
+                    });
+                }
+                catch (err) {
+                    error(`Blob ${blob.blobId} could not be uploaded under its id: ${describeRecordsFailure(err)}. The rows are loaded into db3 ${db3Id}.`);
+                    return 1;
+                }
+                blobsUploaded++;
+            }
+        }
+        if (options.json) {
+            json({
+                id: db3Id,
+                created,
+                keptId: flags.keepId,
+                type: plan.typeName,
+                registered: register.length,
+                rows: session?.rows ?? 0,
+                refusedRows,
+                session,
+                blobs: blobsUploaded,
+            });
+        }
+        else {
+            printResult("db3", db3Id);
+            printResult("Rows", session?.rows ?? 0);
+            printResult("Indexes registered", register.length);
+            printResult("Blobs", plan.blobs ? blobsUploaded : "none");
+        }
+        if (refusedRows > 0) {
+            error(`The load refused ${refusedRows} row(s). List them with \`primitive db3 inspect ${db3Id} --refused ${session?.sessionId}\`.`);
+            return 1;
+        }
+        return 0;
+    }
+    catch (err) {
+        error(err?.statusCode ? describeRecordsFailure(err) : err?.message ?? String(err));
+        return 1;
+    }
+}
+//# sourceMappingURL=db3.js.map