@x12i/catalox 5.1.3 → 5.9.6

package/packages/engine/dist/cli/index.js

@@ -0,0 +1,1508 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { Command } from "commander";
+import { writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { CATALOX_GCS_BACKUP_MANIFEST_FILENAME, createCataloxHelpersGcsClient } from "../catalox/backup-data.js";
+import { cataloxGcsBackupManifestToFirestoreExportManifest } from "../catalox/catalox-gcs-backup-export-manifest.js";
+import { normalizeGcsPrefix, ndjsonObjectPath } from "../catalox/firestore-gcs-transfer.js";
+import { createCataloxFromEnv, testFirestoreConnectionFromEnv } from "../firebase/bootstrap.js";
+import { applyCataloxSeedPreset, loadCataloxSeedManifestFromPath } from "../catalox/seed-preset.js";
+import { resolveCataloxSeedPresetPath } from "../catalox/seed-preset-resolve.js";
+import { normalizeNativePatchBody, normalizeNativeUpsertBody, parseJsonArrayOrNdjson, parseJsonObject, readUtf8FromFileOrStdin, } from "./item-json.js";
+import { buildCatalogListMarkdownMap, renderCatalogListMarkdown } from "../markdown/render-list-markdown.js";
+import { buildCatalogItemMarkdownMap, renderCatalogItemMarkdown } from "../markdown/render-item-markdown.js";
+import { renderCatalogRelationsMermaid } from "../diagrams/render-catalog-diagram.js";
+import { renderItemRelationsMermaid } from "../diagrams/render-item-diagram.js";
+function createCatalox() {
+    return createCataloxFromEnv().catalox;
+}
+/** CLI `--store` wins over `CATALOX_STORE_ID` when both are set. */
+function resolvedStoreId(cliStore) {
+    const id = (cliStore ?? process.env.CATALOX_STORE_ID ?? "").trim();
+    return id || undefined;
+}
+function parseScopeJson(raw) {
+    const t = raw?.trim();
+    if (!t)
+        return undefined;
+    const parsed = JSON.parse(t);
+    if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("scope JSON must be an object of string arrays");
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(parsed)) {
+        if (!Array.isArray(v))
+            throw new Error(`scope.${k} must be a string array`);
+        out[k] = v.filter((x) => typeof x === "string" && x.trim() !== "");
+    }
+    return out;
+}
+function baseContext(opts) {
+    const appId = (opts.app ?? process.env.CATALOX_APP_ID ?? "").trim();
+    if (!appId)
+        throw new Error("Missing --app or CATALOX_APP_ID");
+    const userId = (process.env.CATALOX_USER_ID ?? "").trim() || undefined;
+    const storeId = resolvedStoreId(opts.store);
+    const scope = parseScopeJson(opts.scopeJson) ??
+        parseScopeJson(process.env.CATALOX_SCOPE_JSON) ??
+        undefined;
+    return {
+        appId,
+        ...(storeId ? { storeId } : {}),
+        ...(opts.god ? { superAdmin: true } : {}),
+        ...(opts.unrestricted ? { unrestrictedScope: true } : {}),
+        ...(scope ? { scope } : {}),
+        ...(userId ? { userId, actor: { type: "user", id: userId } } : {}),
+    };
+}
+async function writeOrStdout(text, outPath) {
+    if (outPath) {
+        await writeFile(outPath, text, "utf8");
+    }
+    else {
+        process.stdout.write(text);
+        if (!text.endsWith("\n"))
+            process.stdout.write("\n");
+    }
+}
+const require = createRequire(import.meta.url);
+const pkg = (() => {
+    try {
+        const p = resolvePath(process.cwd(), "package.json");
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return { version: "0.0.0" };
+    }
+})();
+const program = new Command();
+program
+    .name("catalox")
+    .description("Catalox CLI")
+    .version(pkg.version ?? "0.0.0");
+program
+    .command("report")
+    .description("Generate a smart inventory report (Markdown)")
+    .requiredOption("--app <appId>", "AppId context")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .option("--catalog <catalogId...>", "Limit to specific catalogIds")
+    .option("--top <n>", "Top examples per catalog", (v) => Number(v), 10)
+    .option("--diff", "Include snapshot run diff section", false)
+    .option("--out <path>", "Write markdown to file instead of stdout")
+    .option("--god", "God mode (bypass binding checks)", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext(opts);
+    const storeId = resolvedStoreId(opts.store);
+    const { markdown } = await catalox.generateInventoryReport(ctx, {
+        ...(storeId ? { storeId } : {}),
+        ...(opts.catalog?.length ? { catalogIds: opts.catalog } : {}),
+        top: opts.top,
+        includeDiff: Boolean(opts.diff),
+    });
+    await writeOrStdout(markdown, opts.out);
+});
+const snapshotCmd = program.command("snapshot").description("Versioned catalog snapshots for backup and drift (catalox-export/v1)");
+snapshotCmd
+    .command("export")
+    .description("Export native (default) catalogs with full item pagination; deterministic catalog/item ordering (read-only bindings)")
+    .requiredOption("--app <appId>", "AppId context")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .option("--catalog <catalogId...>", "Limit to specific catalogIds")
+    .option("--catalog-type <type...>", "Filter by catalogType")
+    .option("--include-mapped", "Include mapped catalogs (default: native only)", false)
+    .option("--include-disabled", "Include disabled catalogs", false)
+    .option("--include-hidden", "Include hidden catalogs (or use --god)", false)
+    .option("--no-item-data", "Metadata-only items (omit item.data)", false)
+    .option("--page-size <n>", "Items per list request", (v) => Number(v), 200)
+    .option("--max-items-per-catalog <n>", "Safety cap per catalog (omit for no cap)")
+    .option("--no-all-native-scopes", "Do not super-list all native scope layers (even with --god)", false)
+    .option("--pretty", "Pretty-print JSON", false)
+    .option("--out <path>", "Write JSON to file instead of stdout")
+    .option("--god", "God mode: super-admin context + all native physical rows", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext(opts);
+    const storeId = resolvedStoreId(opts.store);
+    const sourceModes = opts.includeMapped ? ["native", "mapped"] : ["native"];
+    const maxRaw = opts.maxItemsPerCatalog;
+    const maxItemsPerCatalog = maxRaw != null && String(maxRaw).trim() !== "" ? Number(maxRaw) : undefined;
+    const json = await catalox.exportCatalogSnapshotToJson(ctx, {
+        ...(storeId ? { storeId } : {}),
+        ...(opts.catalog?.length ? { catalogIds: opts.catalog } : {}),
+        ...(opts.catalogType?.length ? { catalogTypes: opts.catalogType } : {}),
+        sourceModes: [...sourceModes],
+        includeDisabledCatalogs: Boolean(opts.includeDisabled),
+        includeHiddenCatalogs: Boolean(opts.includeHidden) || Boolean(opts.god),
+        includeItemData: Boolean(opts.itemData),
+        pageSize: opts.pageSize,
+        ...(maxItemsPerCatalog != null && Number.isFinite(maxItemsPerCatalog)
+            ? { maxItemsPerCatalog }
+            : {}),
+        includeAllNativeScopes: !opts.noAllNativeScopes,
+    }, Boolean(opts.pretty));
+    await writeOrStdout(json, opts.out);
+});
+program
+    .command("export")
+    .description("Export inventory to JSON (legacy inventory shape; use snapshot export for backup/drift)")
+    .requiredOption("--app <appId>", "AppId context")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .option("--catalog <catalogId...>", "Limit to specific catalogIds")
+    .option("--include-items", "Include items in export", false)
+    .option("--no-item-data", "Exclude `items[].data` (metadata-only items)")
+    .option("--limit-per-catalog <n>", "Item limit per catalog", (v) => Number(v), 50)
+    .option("--pretty", "Pretty-print JSON", false)
+    .option("--out <path>", "Write JSON to file instead of stdout")
+    .option("--god", "God mode (bypass binding checks)", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext(opts);
+    const storeId = resolvedStoreId(opts.store);
+    const json = await catalox.exportInventoryToJson(ctx, {
+        ...(storeId ? { storeId } : {}),
+        ...(opts.catalog?.length ? { catalogIds: opts.catalog } : {}),
+        includeItems: Boolean(opts.includeItems),
+        includeItemData: Boolean(opts.itemData),
+        limitPerCatalog: opts.limitPerCatalog,
+    }, Boolean(opts.pretty));
+    await writeOrStdout(json, opts.out);
+});
+const renderCmd = program.command("render").description("Render helpers (Markdown/diagrams)");
+renderCmd
+    .command("list-md")
+    .description("Render a catalog list as Markdown (using CatalogListRenderMap)")
+    .requiredOption("--app <appId>", "AppId context")
+    .requiredOption("--catalog <catalogId>", "CatalogId")
+    .option("--limit <n>", "Max items to include", (v) => Number(v), 50)
+    .option("--out <path>", "Write markdown to file instead of stdout")
+    .option("--god", "God mode (bypass binding checks)", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext(opts);
+    const catalogId = String(opts.catalog);
+    const map = await catalox.buildCatalogListRenderMap(ctx, catalogId, {
+        limit: opts.limit,
+        resolveSources: true,
+        displayContext: "grid",
+    });
+    const mdMap = buildCatalogListMarkdownMap(map, { maxRows: opts.limit });
+    const markdown = renderCatalogListMarkdown(mdMap);
+    await writeOrStdout(markdown, opts.out);
+});
+renderCmd
+    .command("item-md")
+    .description("Render a single catalog item as Markdown (using CatalogItemRenderMap)")
+    .requiredOption("--app <appId>", "AppId context")
+    .requiredOption("--catalog <catalogId>", "CatalogId")
+    .requiredOption("--item <itemId>", "ItemId")
+    .option("--out <path>", "Write markdown to file instead of stdout")
+    .option("--refs", "Include references section", false)
+    .option("--god", "God mode (bypass binding checks)", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext(opts);
+    const catalogId = String(opts.catalog);
+    const itemId = String(opts.item);
+    const map = await catalox.buildCatalogItemRenderMap(ctx, catalogId, itemId, {
+        includeReferences: Boolean(opts.refs),
+        resolveSources: true,
+        displayContext: "form",
+    });
+    const mdMap = buildCatalogItemMarkdownMap(map, { includeReferences: Boolean(opts.refs) });
+    const markdown = renderCatalogItemMarkdown(mdMap);
+    await writeOrStdout(markdown, opts.out);
+});
+renderCmd
+    .command("catalog-diagram")
+    .description("Render a catalog relations diagram as Mermaid (flowchart)")
+    .requiredOption("--app <appId>", "AppId context")
+    .requiredOption("--catalog <catalogId>", "CatalogId (used as root node)")
+    .option("--out <path>", "Write mermaid to file instead of stdout")
+    .option("--god", "God mode (bypass binding checks)", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext(opts);
+    const rootCatalogId = String(opts.catalog);
+    // Minimal map: only root catalog node. Relations are consumer-owned today.
+    const descriptor = await catalox.getCatalogDescriptor(ctx, rootCatalogId);
+    const map = {
+        title: `Catalog relations: ${descriptor?.label ?? rootCatalogId}`,
+        catalogs: [{ id: rootCatalogId, label: descriptor?.label ?? rootCatalogId }],
+        relations: [],
+    };
+    const mermaid = renderCatalogRelationsMermaid(map);
+    await writeOrStdout(mermaid, opts.out);
+});
+renderCmd
+    .command("item-diagram")
+    .description("Render an item relations diagram as Mermaid (flowchart)")
+    .requiredOption("--app <appId>", "AppId context")
+    .requiredOption("--catalog <catalogId>", "CatalogId")
+    .requiredOption("--item <itemId>", "ItemId")
+    .option("--out <path>", "Write mermaid to file instead of stdout")
+    .option("--god", "God mode (bypass binding checks)", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext(opts);
+    const catalogId = String(opts.catalog);
+    const itemId = String(opts.item);
+    const got = await catalox.getCatalogItem(ctx, catalogId, itemId);
+    if (got.outcome === "mapping_blocked") {
+        throw new Error(`Mapping blocked for catalog ${catalogId}: ${JSON.stringify(got.issues)}`);
+    }
+    if (got.outcome === "not_found")
+        throw new Error(`Item not found: ${catalogId}/${itemId}`);
+    const item = got.item;
+    const refs = await catalox.getCatalogItemReferences(ctx, catalogId, itemId);
+    const nodes = [
+        { id: `${catalogId}:${itemId}`, label: item.title ?? `${catalogId}:${itemId}` },
+        ...refs.map((r) => ({
+            id: `${String(r.toCatalogId)}:${String(r.toItemId)}`,
+            label: `${String(r.toCatalogId)}:${String(r.toItemId)}`,
+        })),
+    ];
+    const edges = refs.map((r) => ({
+        from: `${catalogId}:${itemId}`,
+        to: `${String(r.toCatalogId)}:${String(r.toItemId)}`,
+        label: String(r.relationType),
+    }));
+    const map = {
+        title: `Item relations: ${catalogId}:${itemId}`,
+        items: nodes,
+        relations: edges,
+    };
+    const mermaid = renderItemRelationsMermaid(map);
+    await writeOrStdout(mermaid, opts.out);
+});
+const storeCmd = program.command("store").description("Manage storeId bindings");
+storeCmd
+    .command("bind-app")
+    .requiredOption("--store <storeId>", "StoreId")
+    .requiredOption("--app <appId>", "AppId")
+    .option("--god", "God mode (required to bind other apps)", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, store: opts.store, god: opts.god });
+    const rec = await catalox.bindAppToStore(ctx, { storeId: opts.store, appId: opts.app });
+    await writeOrStdout(JSON.stringify(rec, null, 2));
+});
+storeCmd
+    .command("unbind-app")
+    .requiredOption("--store <storeId>", "StoreId")
+    .requiredOption("--app <appId>", "AppId")
+    .option("--god", "God mode (required to unbind other apps)", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, store: opts.store, god: opts.god });
+    await catalox.unbindAppFromStore(ctx, opts.store, opts.app);
+});
+storeCmd
+    .command("list-apps")
+    .requiredOption("--store <storeId>", "StoreId")
+    .requiredOption("--app <appId>", "AppId context for authz")
+    .option("--god", "God mode (list all apps)", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, store: opts.store, god: opts.god });
+    const rows = await catalox.listAppsForStore(ctx, opts.store);
+    await writeOrStdout(JSON.stringify(rows, null, 2));
+});
+const seedCmd = program.command("seed").description("Declarative catalog seed manifests (idempotent apply)");
+seedCmd
+    .command("apply")
+    .description("Apply a JSON preset: catalogs, optional descriptors/bindings/items")
+    .requiredOption("--app <appId>", "AppId context (CataloxContext.appId)")
+    .option("--file <path>", "Path to preset JSON manifest")
+    .option("--preset <id>", "Logical preset: builtin:native-map-v1, registry alias (native-map@v1), npm package name, or path to .json")
+    .option("--god", "Super-admin context (required for descriptor section and bindings to other apps)", false)
+    .action(async (opts) => {
+    const fileRaw = opts.file != null ? String(opts.file).trim() : "";
+    const presetRaw = opts.preset != null ? String(opts.preset).trim() : "";
+    if ((fileRaw !== "") === (presetRaw !== "")) {
+        throw new Error("Specify exactly one of --file <path> or --preset <id>");
+    }
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const res = presetRaw
+        ? await applyCataloxSeedPreset(catalox, ctx, { preset: presetRaw })
+        : await applyCataloxSeedPreset(catalox, ctx, { presetPath: fileRaw });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+});
+seedCmd
+    .command("validate")
+    .description("Parse and AJV-validate a seed manifest (--file or --preset); no Firestore writes")
+    .option("--file <path>", "Path to preset JSON manifest")
+    .option("--preset <id>", "Logical preset: builtin:native-map-v1, registry alias, npm package name, or path to .json")
+    .action(async (opts) => {
+    const fileRaw = opts.file != null ? String(opts.file).trim() : "";
+    const presetRaw = opts.preset != null ? String(opts.preset).trim() : "";
+    if ((fileRaw !== "") === (presetRaw !== "")) {
+        throw new Error("Specify exactly one of --file <path> or --preset <id>");
+    }
+    const manifest = presetRaw
+        ? await loadCataloxSeedManifestFromPath(resolveCataloxSeedPresetPath(presetRaw))
+        : await loadCataloxSeedManifestFromPath(fileRaw);
+    const { validateCataloxSeedManifestItemPayloads } = await import("../catalox/seed-preset.js");
+    const itemPayloadIssues = validateCataloxSeedManifestItemPayloads(manifest);
+    const ok = itemPayloadIssues.length === 0;
+    await writeOrStdout(JSON.stringify({
+        ok,
+        presetVersion: manifest.presetVersion,
+        id: manifest.id ?? null,
+        name: manifest.name ?? null,
+        counts: {
+            catalogs: manifest.catalogs.length,
+            descriptors: manifest.descriptors?.length ?? 0,
+            bindings: manifest.bindings?.length ?? 0,
+            items: manifest.items?.length ?? 0,
+        },
+        ...(itemPayloadIssues.length ? { itemPayloadIssues } : {}),
+    }, null, 2));
+    if (!ok)
+        process.exitCode = 1;
+});
+const itemsCmd = program.command("items").description("Catalog items: validate, list, CRUD, batch upsert, export (native + mapped read paths)");
+itemsCmd
+    .command("validate")
+    .description("validateCatalog, validateCatalogItem (--item), or offline payload validate (--file; optional --catalog-type)")
+    .option("--app <appId>", "AppId context (required unless --file with --catalog-type only)")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .option("--catalog <catalogId>", "Catalog id")
+    .option("--item <itemId>", "When set, validateCatalogItem; otherwise validateCatalog")
+    .option("--file <path>", "Offline: validate item JSON from file (or stdin when omitted)")
+    .option("--catalog-type <type>", "Offline with --file: resolve schema by catalogType + registry")
+    .option("--schema-version <id>", "Offline: payload schema id (e.g. catalox.payload.generic-map/v1)")
+    .option("--out <path>", "Write JSON to file instead of stdout")
+    .option("--no-auto-create", "Fail validate when smart-property target codes are missing", false)
+    .option("--god", "God mode (bypass binding checks where applicable)", false)
+    .action(async (opts) => {
+    const fileRaw = opts.file != null ? String(opts.file).trim() : "";
+    const catalogTypeRaw = opts.catalogType != null ? String(opts.catalogType).trim() : "";
+    const schemaVersionRaw = opts.schemaVersion != null ? String(opts.schemaVersion).trim() : "";
+    if (fileRaw !== "" || (catalogTypeRaw !== "" && !opts.catalog)) {
+        const { catalogRecordFromCreateInput, validateNativeItemPayloadOrMissing, resolvePayloadSchema, validateNativeItemPayload } = await import("../validation/payload-schema.js");
+        const { createBundledPayloadSchemaRegistry } = await import("../validation/payload-schema-registry.js");
+        const registry = createBundledPayloadSchemaRegistry();
+        const rawText = await readUtf8FromFileOrStdin(fileRaw || undefined);
+        let parsed;
+        try {
+            parsed = JSON.parse(rawText);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`Item JSON is not valid: ${msg}`);
+        }
+        const body = parsed != null && typeof parsed === "object" && !Array.isArray(parsed) && "data" in parsed
+            ? parsed.data
+            : parsed;
+        let report;
+        if (opts.catalog != null && String(opts.catalog).trim() !== "") {
+            const catalox = createCatalox();
+            const appId = opts.app != null ? String(opts.app).trim() : String(process.env.CATALOX_APP_ID ?? "").trim();
+            if (!appId)
+                throw new Error("--app or CATALOX_APP_ID is required with --catalog and --file");
+            const ctx = baseContext({ app: appId, store: opts.store, god: opts.god });
+            const catalogId = String(opts.catalog).trim();
+            const catalog = await catalox.getCatalog(ctx, catalogId);
+            if (!catalog)
+                throw new Error(`Catalog not found: ${catalogId}`);
+            const resolved = resolvePayloadSchema({ catalog, registry });
+            report = resolved
+                ? validateNativeItemPayload(body, resolved, registry)
+                : validateNativeItemPayloadOrMissing(body, { catalog, registry });
+        }
+        else if (catalogTypeRaw !== "") {
+            const catalog = catalogRecordFromCreateInput({
+                catalogId: "_offline_",
+                name: "_offline_",
+                catalogType: catalogTypeRaw,
+                ...(schemaVersionRaw ? { schemaVersion: schemaVersionRaw } : {}),
+                sourceMode: "native",
+                native: { type: "native" },
+            });
+            report = validateNativeItemPayloadOrMissing(body, { catalog, registry });
+        }
+        else {
+            throw new Error("Offline validate requires --catalog-type or --catalog with --app");
+        }
+        await writeOrStdout(JSON.stringify({ scope: "payload", ...report }, null, 2), opts.out);
+        if (!report.isValid)
+            process.exitCode = 1;
+        return;
+    }
+    const appId = opts.app != null ? String(opts.app).trim() : String(process.env.CATALOX_APP_ID ?? "").trim();
+    if (!appId)
+        throw new Error("--app or CATALOX_APP_ID is required");
+    if (opts.catalog == null || String(opts.catalog).trim() === "") {
+        throw new Error("--catalog is required for live validate");
+    }
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: appId, store: opts.store, god: opts.god });
+    const catalogId = String(opts.catalog);
+    if (opts.item != null && String(opts.item).trim() !== "") {
+        const report = await catalox.validateCatalogItem(ctx, catalogId, String(opts.item).trim(), opts.noAutoCreate ? { noAutoCreate: true } : undefined);
+        await writeOrStdout(JSON.stringify({ scope: "item", catalogId, itemId: String(opts.item).trim(), ...report }, null, 2), opts.out);
+        if (!report.isValid)
+            process.exitCode = 1;
+        return;
+    }
+    const report = await catalox.validateCatalog(ctx, catalogId);
+    await writeOrStdout(JSON.stringify({ scope: "catalog", catalogId, ...report }, null, 2), opts.out);
+    if (!report.isValid)
+        process.exitCode = 1;
+});
+itemsCmd
+    .command("get")
+    .description("getCatalogItem JSON (outcome: found | not_found | mapping_blocked)")
+    .requiredOption("--app <appId>", "AppId context")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .requiredOption("--catalog <catalogId>", "Catalog id")
+    .requiredOption("--item <itemId>", "Logical item id")
+    .option("--storage-doc-id <id>", "Native: target a specific physical storage doc id")
+    .option("--scope-json <json>", "Fetch scope narrowing (JSON object of string arrays)")
+    .option("--scoped-only", "Exclude generic items", false)
+    .option("--generic-only", "Return only generic items", false)
+    .option("--out <path>", "Write JSON to file instead of stdout")
+    .option("--god", "God mode", false)
+    .option("--scope-json-token <json>", "Token scope on context (defaults to CATALOX_SCOPE_JSON)")
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const fetchScope = parseScopeJson(opts.scopeJson != null ? String(opts.scopeJson) : undefined);
+    const ctx = baseContext({
+        app: opts.app,
+        store: opts.store,
+        god: opts.god,
+        ...(opts.scopeJsonToken != null ? { scopeJson: String(opts.scopeJsonToken) } : {}),
+    });
+    const catalogId = String(opts.catalog);
+    const itemId = String(opts.item);
+    const storageDocId = opts.storageDocId != null && String(opts.storageDocId).trim() ? String(opts.storageDocId).trim() : undefined;
+    const got = await catalox.getCatalogItem(ctx, catalogId, itemId, {
+        ...(storageDocId ? { storageDocId } : {}),
+        ...(fetchScope || opts.scopedOnly || opts.genericOnly
+            ? {
+                scope: {
+                    ...(fetchScope ? { scope: fetchScope } : {}),
+                    ...(opts.scopedOnly ? { scopedOnly: true } : {}),
+                    ...(opts.genericOnly ? { genericOnly: true } : {}),
+                },
+            }
+            : {}),
+    });
+    await writeOrStdout(JSON.stringify(got, null, 2), opts.out);
+    if (got.outcome !== "found")
+        process.exitCode = 1;
+});
+itemsCmd
+    .command("list")
+    .description("listCatalogItemsWithOutcome (explicit outcome for scripts)")
+    .requiredOption("--app <appId>", "AppId context")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .requiredOption("--catalog <catalogId>", "Catalog id")
+    .option("--limit <n>", "Page size", (v) => Number(v), 50)
+    .option("--offset <n>", "Offset (native)", (v) => Number(v), 0)
+    .option("--cursor <token>", "Mapped catalogs: pass nextCursor from a prior response")
+    .option("--filter-json <json>", "JSON object merged into list filter (compact empty strings ignored by server)")
+    .option("--scope-json <json>", "Fetch scope narrowing (JSON object of string arrays)")
+    .option("--scope-json-token <json>", "Token scope on context (defaults to CATALOX_SCOPE_JSON)")
+    .option("--scoped-only", "Exclude generic items", false)
+    .option("--generic-only", "Return only generic items", false)
+    .option("--no-generic", "Same as --scoped-only", false)
+    .option("--out <path>", "Write JSON to file instead of stdout")
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const fetchScope = parseScopeJson(opts.scopeJson != null ? String(opts.scopeJson) : undefined);
+    const ctx = baseContext({
+        app: opts.app,
+        store: opts.store,
+        god: opts.god,
+        ...(opts.scopeJsonToken != null ? { scopeJson: String(opts.scopeJsonToken) } : {}),
+    });
+    const catalogId = String(opts.catalog);
+    let filter;
+    const fj = opts.filterJson != null ? String(opts.filterJson).trim() : "";
+    if (fj) {
+        const parsed = JSON.parse(fj);
+        if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("--filter-json must be a JSON object");
+        }
+        filter = parsed;
+    }
+    const scopedOnly = Boolean(opts.scopedOnly || opts.noGeneric);
+    const res = await catalox.listCatalogItemsWithOutcome(ctx, catalogId, {
+        limit: opts.limit,
+        offset: opts.offset,
+        ...(fetchScope || scopedOnly || opts.genericOnly
+            ? {
+                scope: {
+                    ...(fetchScope ? { scope: fetchScope } : {}),
+                    ...(scopedOnly ? { scopedOnly: true } : {}),
+                    ...(opts.genericOnly ? { genericOnly: true } : {}),
+                },
+            }
+            : {}),
+        ...(filter ? { filter } : {}),
+        ...(opts.cursor != null && String(opts.cursor).trim()
+            ? { cursor: String(opts.cursor).trim() }
+            : {}),
+    });
+    await writeOrStdout(JSON.stringify(res, null, 2), opts.out);
+    if (res.outcome !== "ok" && res.outcome !== "empty")
+        process.exitCode = 1;
+});
+itemsCmd
+    .command("upsert")
+    .description("upsertNativeCatalogItem: JSON body is item fields at top level, or { data, scope?, relations? }")
+    .requiredOption("--app <appId>", "AppId context")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .requiredOption("--catalog <catalogId>", "Native catalog id")
+    .option("--file <path>", "JSON file (otherwise read stdin)")
+    .option("--out <path>", "Write result JSON to file instead of stdout")
+    .option("--god", "God mode (non-global scope rows require super-admin)", false)
+    .action(async (opts) => {
+    const raw = await readUtf8FromFileOrStdin(opts.file != null ? String(opts.file).trim() : undefined);
+    const body = normalizeNativeUpsertBody(parseJsonObject(raw, "items upsert"));
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, store: opts.store, god: opts.god });
+    const item = await catalox.upsertNativeCatalogItem(ctx, String(opts.catalog), body);
+    await writeOrStdout(JSON.stringify(item, null, 2), opts.out);
+});
+itemsCmd
+    .command("patch")
+    .description("updateNativeCatalogItem: shallow-merge patch into existing item data (+ optional scope/relations)")
+    .requiredOption("--app <appId>", "AppId context")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .requiredOption("--catalog <catalogId>", "Native catalog id")
+    .requiredOption("--item <itemId>", "Logical item id")
+    .option("--file <path>", "JSON patch file (otherwise read stdin)")
+    .option("--storage-doc-id <id>", "Disambiguate physical row when multiple scopes share logical id")
+    .option("--out <path>", "Write result JSON to file instead of stdout")
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const raw = await readUtf8FromFileOrStdin(opts.file != null ? String(opts.file).trim() : undefined);
+    const patch = normalizeNativePatchBody(parseJsonObject(raw, "items patch"));
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, store: opts.store, god: opts.god });
+    const storageDocId = opts.storageDocId != null && String(opts.storageDocId).trim() ? String(opts.storageDocId).trim() : undefined;
+    const item = await catalox.updateNativeCatalogItem(ctx, String(opts.catalog), String(opts.item).trim(), patch, { ...(storageDocId ? { storageDocId } : {}) });
+    await writeOrStdout(JSON.stringify(item, null, 2), opts.out);
+});
+itemsCmd
+    .command("delete")
+    .description("deleteNativeCatalogItem (requires --confirm)")
+    .requiredOption("--app <appId>", "AppId context")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .requiredOption("--catalog <catalogId>", "Native catalog id")
+    .requiredOption("--item <itemId>", "Logical item id")
+    .option("--storage-doc-id <id>", "Target a specific physical storage doc id")
+    .option("--confirm", "Must pass --confirm to run", false)
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    if (!opts.confirm) {
+        // eslint-disable-next-line no-console
+        console.error("Refusing to delete without --confirm");
+        process.exitCode = 1;
+        return;
+    }
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, store: opts.store, god: opts.god });
+    const storageDocId = opts.storageDocId != null && String(opts.storageDocId).trim() ? String(opts.storageDocId).trim() : undefined;
+    await catalox.deleteNativeCatalogItem(ctx, String(opts.catalog), String(opts.item).trim(), {
+        ...(storageDocId ? { storageDocId } : {}),
+    });
+    await writeOrStdout(JSON.stringify({ ok: true, catalogId: String(opts.catalog), itemId: String(opts.item).trim() }, null, 2));
+});
+itemsCmd
+    .command("batch-upsert")
+    .description("batchUpsertNativeCatalogItems: JSON array or NDJSON lines (≤450 rows per Firestore batch internally). Item shape matches items upsert.")
+    .requiredOption("--app <appId>", "AppId context")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .requiredOption("--catalog <catalogId>", "Native catalog id")
+    .option("--file <path>", "JSON array or NDJSON file (otherwise read stdin)")
+    .option("--god", "God mode (non-global scope rows require super-admin)", false)
+    .action(async (opts) => {
+    const raw = await readUtf8FromFileOrStdin(opts.file != null ? String(opts.file).trim() : undefined);
+    const rows = parseJsonArrayOrNdjson(raw, "items batch-upsert");
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, store: opts.store, god: opts.god });
+    await catalox.batchUpsertNativeCatalogItems(ctx, String(opts.catalog), rows);
+    await writeOrStdout(JSON.stringify({ ok: true, count: rows.length, catalogId: String(opts.catalog) }, null, 2));
+});
+itemsCmd
+    .command("replace")
+    .description("replaceNativeCatalogItem: full-document native replace (no merge). Body is a NativeCatalogItemRecord JSON object.")
+    .requiredOption("--app <appId>", "AppId context")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .requiredOption("--catalog <catalogId>", "Native catalog id")
+    .option("--file <path>", "JSON file (otherwise read stdin)")
+    .option("--god", "God mode (non-global scope rows require super-admin)", false)
+    .action(async (opts) => {
+    const raw = await readUtf8FromFileOrStdin(opts.file != null ? String(opts.file).trim() : undefined);
+    const record = JSON.parse(raw);
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, store: opts.store, god: opts.god });
+    await catalox.replaceNativeCatalogItem(ctx, String(opts.catalog), record);
+    await writeOrStdout(JSON.stringify({ ok: true, catalogId: String(opts.catalog), itemId: record.itemId }, null, 2));
+});
+itemsCmd
+    .command("batch-replace")
+    .description("replaceNativeCatalogItems: JSON array or NDJSON lines of NativeCatalogItemRecord (≤450 rows per Firestore batch internally).")
+    .requiredOption("--app <appId>", "AppId context")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .requiredOption("--catalog <catalogId>", "Native catalog id")
+    .option("--file <path>", "JSON array or NDJSON file (otherwise read stdin)")
+    .option("--no-atomic", "Write rows one at a time instead of batched replace", false)
+    .option("--god", "God mode (non-global scope rows require super-admin)", false)
+    .action(async (opts) => {
+    const raw = await readUtf8FromFileOrStdin(opts.file != null ? String(opts.file).trim() : undefined);
+    const rows = parseJsonArrayOrNdjson(raw, "items batch-replace");
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, store: opts.store, god: opts.god });
+    await catalox.replaceNativeCatalogItems(ctx, String(opts.catalog), rows, {
+        atomic: !opts.noAtomic,
+    });
+    await writeOrStdout(JSON.stringify({ ok: true, count: rows.length, catalogId: String(opts.catalog) }, null, 2));
+});
+itemsCmd
+    .command("export")
+    .description("Export one catalog's items to { catalogId, items } JSON (paginates nextCursor when present)")
+    .requiredOption("--app <appId>", "AppId context")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .requiredOption("--catalog <catalogId>", "Catalog id")
+    .option("--page-size <n>", "Per request", (v) => Number(v), 200)
+    .option("--max-total <n>", "Stop after this many items (safety cap)", (v) => Number(v), 10000)
+    .option("--pretty", "Pretty-print JSON", false)
+    .option("--out <path>", "Write JSON to file instead of stdout")
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, store: opts.store, god: opts.god });
+    const catalogId = String(opts.catalog);
+    const pageSize = Math.max(1, Math.min(500, Number(opts.pageSize) || 200));
+    const maxTotal = Math.max(1, Number(opts.maxTotal) || 10000);
+    const items = [];
+    let offset = 0;
+    let cursor;
+    const indent = opts.pretty ? 2 : undefined;
+    for (;;) {
+        const page = await catalox.listCatalogItems(ctx, catalogId, {
+            limit: pageSize,
+            ...(cursor ? { cursor: cursor } : { offset }),
+        });
+        if (page.listOutcome === "mapping_blocked") {
+            await writeOrStdout(JSON.stringify({ catalogId, error: "mapping_blocked", issues: page.issues ?? [] }, null, indent), opts.out);
+            process.exitCode = 1;
+            return;
+        }
+        for (const it of page.items) {
+            items.push(it);
+            if (items.length >= maxTotal)
+                break;
+        }
+        if (items.length >= maxTotal)
+            break;
+        if (page.nextCursor) {
+            cursor = page.nextCursor;
+            offset = 0;
+            continue;
+        }
+        if (!page.items.length)
+            break;
+        if (page.items.length < pageSize)
+            break;
+        offset += page.items.length;
+        cursor = undefined;
+    }
+    const payload = {
+        catalogId,
+        exportedCount: items.length,
+        truncated: items.length >= maxTotal,
+        items,
+    };
+    await writeOrStdout(JSON.stringify(payload, null, indent), opts.out);
+});
+const itemsRelationCmd = itemsCmd.command("relation").description("Item↔item relations (catalogReferences)");
+itemsRelationCmd
+    .command("upsert")
+    .description("Create or update one relation edge")
+    .requiredOption("--app <appId>", "AppId context")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .option("--file <path>", "JSON file (otherwise stdin): fromCatalogId, fromItemId, toCatalogId, toItemId, relationType, optional label/metadata")
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const raw = await readUtf8FromFileOrStdin(opts.file != null ? String(opts.file).trim() : undefined);
+    const input = parseJsonObject(raw, "items relation upsert");
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, store: opts.store, god: opts.god });
+    const res = await catalox.upsertCatalogItemRelation(ctx, input);
+    await writeOrStdout(JSON.stringify(res, null, 2));
+});
+itemsRelationCmd
+    .command("delete")
+    .description("Delete by referenceId or by endpoint tuple (fromCatalogId, fromItemId, toCatalogId, toItemId, relationType)")
+    .requiredOption("--app <appId>", "AppId context")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .option("--file <path>", "JSON file (otherwise stdin)")
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const raw = await readUtf8FromFileOrStdin(opts.file != null ? String(opts.file).trim() : undefined);
+    const input = parseJsonObject(raw, "items relation delete");
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, store: opts.store, god: opts.god });
+    await catalox.deleteCatalogItemRelation(ctx, input);
+    await writeOrStdout(JSON.stringify({ ok: true }, null, 2));
+});
+const firestoreCmd = program
+    .command("firestore")
+    .description("Firestore backup (GCS), restore-from-GCS, native layout migration, and connectivity probe");
+firestoreCmd
+    .command("probe")
+    .description("Minimal Firestore read to verify credentials (disposable Admin app; same env as createCataloxFromEnv)")
+    .action(async () => {
+    const res = await testFirestoreConnectionFromEnv();
+    const body = res.ok
+        ? { ok: true, credentialSource: res.credentialSource }
+        : {
+            ok: false,
+            ...(res.credentialSource != null ? { credentialSource: res.credentialSource } : {}),
+            error: res.error instanceof Error ? res.error.message : String(res.error),
+        };
+    await writeOrStdout(JSON.stringify(body, null, 2));
+    if (!res.ok)
+        process.exitCode = 1;
+});
+firestoreCmd
+    .command("backup")
+    .description("Catalox backup to GCS only (NDJSON + catalox-backup-manifest.json)")
+    .requiredOption("--app <appId>", "AppId for Catalox context")
+    .option("--bucket <name>", "GCS bucket name (default: catalox)", "catalox")
+    .option("--gcs-prefix <path>", "Optional prefix before timestamp folder (default: catalox-firestore-backups/)", "")
+    .option("--label <text>", "Backup label stored on manifest")
+    .option("--snapshots", "Include catalogSnapshots data", false)
+    .option("--catalog <catalogId...>", "Restrict which native catalogs are copied")
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    // Bucket defaults to "catalox" when omitted.
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const gcsPrefixOpt = opts.gcsPrefix != null && String(opts.gcsPrefix).trim() ? String(opts.gcsPrefix).trim() : undefined;
+    const res = await catalox.backupData(ctx, {
+        mode: "gcs",
+        gcsBucket: String(opts.bucket ?? "catalox").trim(),
+        ...(gcsPrefixOpt !== undefined ? { gcsPrefix: gcsPrefixOpt } : {}),
+        includeSnapshots: Boolean(opts.snapshots),
+        ...(opts.catalog?.length ? { catalogIds: opts.catalog } : {}),
+        ...(opts.label != null && String(opts.label) !== "" ? { backupLabel: String(opts.label) } : {}),
+    });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+    if (!res.ok)
+        process.exitCode = 1;
+});
+firestoreCmd
+    .command("undo-restore-backup")
+    .description("Revert a prior restore-backup-from-gcs using backup-restoreSessions/{sessionId} and preRestore collections")
+    .requiredOption("--app <appId>", "AppId for Catalox context")
+    .requiredOption("--session <restoreSessionId>", "restoreSessionId returned by restore-backup-from-gcs")
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const res = await catalox.undoFirestoreRestore(ctx, {
+        restoreSessionId: String(opts.session),
+    });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+    if (!res.ok)
+        process.exitCode = 1;
+});
+firestoreCmd
+    .command("restore-backup-from-gcs")
+    .description("Restore live Firestore from one backupData GCS run (NDJSON under --run-folder). Uses pre-restore sidecars so undo works.")
+    .requiredOption("--app <appId>", "AppId for Catalox context")
+    .option("--bucket <name>", "GCS bucket name (default: catalox)", "catalox")
+    .requiredOption("--run-folder <path>", "Run folder within bucket (e.g. catalox-firestore-backups/2026_04_18T12_00_00Z)")
+    .option("--snapshots", "Also restore catalogSnapshots NDJSON from the run", false)
+    .option("--catalog <catalogId...>", "Restrict which native catalogs are restored")
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const res = await catalox.restoreFirestoreBackupFromGcs(ctx, {
+        gcsBucket: String(opts.bucket ?? "catalox").trim(),
+        gcsRunFolder: String(opts.runFolder).trim(),
+        includeSnapshots: Boolean(opts.snapshots),
+        ...(opts.catalog?.length ? { catalogIds: opts.catalog } : {}),
+    });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+    if (!res.ok)
+        process.exitCode = 1;
+});
+firestoreCmd
+    .command("prune-gcs-backups")
+    .description("Delete oldest GCS Catalox backup run folders (children of --gcs-prefix) until --keep-last remain (lexicographic sort on folder names)")
+    .option("--bucket <name>", "GCS bucket name (default: catalox)", "catalox")
+    .option("--gcs-prefix <path>", "Base prefix containing timestamp folders (default: catalox-firestore-backups/)", "")
+    .requiredOption("--keep-last <n>", "Number of newest run folders to keep", (v) => parseInt(String(v), 10))
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: "cli", god: true });
+    const keepRaw = opts.keepLast;
+    const keepLast = typeof keepRaw === "number" && Number.isFinite(keepRaw) ? keepRaw : parseInt(String(keepRaw), 10);
+    const res = await catalox.pruneGcsBackupRuns(ctx, {
+        bucket: String(opts.bucket ?? "catalox").trim(),
+        ...(opts.gcsPrefix != null && String(opts.gcsPrefix).trim() !== ""
+            ? { gcsBasePrefix: String(opts.gcsPrefix).trim() }
+            : {}),
+        keepLast,
+    });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+    if (!res.ok)
+        process.exitCode = 1;
+});
+firestoreCmd
+    .command("delete-gcs-backup-run")
+    .description("Delete all objects under one GCS backup run folder (e.g. after a failed partial backup)")
+    .option("--bucket <name>", "GCS bucket name (default: catalox)", "catalox")
+    .requiredOption("--run-folder <path>", "Run folder prefix within the bucket")
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: "cli", god: true });
+    const res = await catalox.deleteCataloxGcsBackupRun(ctx, {
+        gcsBucket: String(opts.bucket ?? "catalox").trim(),
+        gcsRunFolder: String(opts.runFolder).trim(),
+    });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+    if (!res.ok)
+        process.exitCode = 1;
+});
+firestoreCmd
+    .command("gcs-backup-to-export-manifest")
+    .description("Read catalox-backup-manifest.json from a GCS run and print catalox-firestore-export-manifest.json JSON (for import-gcs --restore-all)")
+    .option("--bucket <name>", "GCS bucket name (default: catalox)", "catalox")
+    .requiredOption("--run-folder <path>", "Run folder within bucket")
+    .action(async (opts) => {
+    try {
+        const bucket = String(opts.bucket ?? "catalox").trim();
+        const runFolder = String(opts.runFolder).trim().replace(/^\/+/, "").replace(/\/+$/, "");
+        const gcs = createCataloxHelpersGcsClient(bucket, runFolder);
+        const buf = await gcs.readObjectBuffer(CATALOX_GCS_BACKUP_MANIFEST_FILENAME);
+        const manifest = JSON.parse(buf.toString("utf8"));
+        const exportManifest = cataloxGcsBackupManifestToFirestoreExportManifest(manifest, runFolder);
+        await writeOrStdout(JSON.stringify(exportManifest, null, 2));
+    }
+    catch (e) {
+        // eslint-disable-next-line no-console
+        console.error(e instanceof Error ? e.message : String(e));
+        process.exitCode = 1;
+    }
+});
+firestoreCmd
+    .command("report-native-layout")
+    .description("JSON report: legacy vs flat doc counts per native catalog (when you still see catalogData/{id}/items in console)")
+    .requiredOption("--app <appId>", "AppId for Catalox context")
+    .option("--catalog <catalogId...>", "Restrict to these catalog ids")
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const rows = await catalox.reportNativeCatalogLayoutDiagnostics(ctx, {
+        ...(opts.catalog?.length ? { catalogIds: opts.catalog } : {}),
+    });
+    const summary = {
+        hint: "If needsLegacyToFlatMigration is true, run: catalox firestore migrate-native-catalog-data --app <sameApp>",
+        catalogs: rows,
+    };
+    await writeOrStdout(JSON.stringify(summary, null, 2));
+});
+firestoreCmd
+    .command("migrate-native-catalog-data")
+    .description("Optional pre-migrate backup to GCS, then copy legacy catalogData/{catalogId}/items → flat catalogData-{catalogId}-items")
+    .requiredOption("--app <appId>", "AppId for Catalox context")
+    .option("--skip-backup", "Skip pre-migrate GCS backup", false)
+    .option("--backup-bucket <name>", "GCS bucket for pre-migrate backup (default: catalox)", "catalox")
+    .option("--backup-prefix <path>", "Optional gcsPrefix for pre-migrate backupData")
+    .option("--backup-label <text>", "Label for pre-migrate backup", "pre-native-layout-migration")
+    .option("--snapshots", "Include snapshots in pre-migrate backup", false)
+    .option("--dry-run", "Count/copy simulation only for migrate", false)
+    .option("--verify-only", "Compare legacy vs flat doc counts", false)
+    .option("--overwrite", "Overwrite existing flat docs", false)
+    .option("--delete-legacy", "Delete legacy catalogData/{id}/items after migrate", false)
+    .option("--i-have-backups", "Required with --delete-legacy", false)
+    .option("--continue-on-error", "Continue other catalogs if one fails", false)
+    .option("--also-export-files", "Write NDJSON+manifest under .catalox-migration-backups/", false)
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    if (!opts.skipBackup) {
+        const b = await catalox.backupData(ctx, {
+            mode: "gcs",
+            gcsBucket: String(opts.backupBucket ?? "catalox").trim(),
+            ...(opts.backupPrefix != null && String(opts.backupPrefix).trim() !== ""
+                ? { gcsPrefix: String(opts.backupPrefix).trim() }
+                : {}),
+            backupLabel: String(opts.backupLabel != null ? opts.backupLabel : "pre-native-layout-migration"),
+            includeSnapshots: Boolean(opts.snapshots),
+        });
+        await writeOrStdout(JSON.stringify({ phase: "backup", result: b }, null, 2));
+        if (!b.ok) {
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const exportDir = opts.alsoExportFiles
+        ? resolvePath(process.cwd(), ".catalox-migration-backups")
+        : undefined;
+    const m = await catalox.migrateNativeCatalogLayout(ctx, {
+        dryRun: Boolean(opts.dryRun),
+        verifyOnly: Boolean(opts.verifyOnly),
+        overwrite: Boolean(opts.overwrite),
+        deleteLegacy: Boolean(opts.deleteLegacy),
+        iHaveBackups: Boolean(opts.iHaveBackups),
+        continueOnError: Boolean(opts.continueOnError),
+        ...(exportDir ? { exportFilesDir: exportDir } : {}),
+    });
+    await writeOrStdout(JSON.stringify({ phase: "migrate", result: m }, null, 2));
+    if (!m.ok)
+        process.exitCode = 1;
+});
+firestoreCmd
+    .command("migrate-native-item-scope")
+    .description("One-time: convert legacy/native scope shapes to flexible scope maps (domains[], agents[], …)")
+    .requiredOption("--app <appId>", "AppId for Catalox context")
+    .option("--dry-run", "Report only; no writes", false)
+    .option("--verify-only", "Fail if any legacy scope shapes remain", false)
+    .option("--i-have-backups", "Required to apply writes (not dry-run/verify-only)", false)
+    .option("--continue-on-error", "Continue other catalogs if one fails", false)
+    .option("--catalog <catalogId...>", "Limit to catalog ids")
+    .option("--scope-mapping <path>", "JSON map accountId:agentId → { domains, agents }")
+    .option("--also-export-files", "Write NDJSON under .catalox-migration-backups/", false)
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const exportDir = opts.alsoExportFiles
+        ? resolvePath(process.cwd(), ".catalox-migration-backups")
+        : undefined;
+    const m = await catalox.migrateNativeItemScope(ctx, {
+        dryRun: Boolean(opts.dryRun),
+        verifyOnly: Boolean(opts.verifyOnly),
+        iHaveBackups: Boolean(opts.iHaveBackups),
+        continueOnError: Boolean(opts.continueOnError),
+        ...(opts.catalog?.length ? { catalogIds: opts.catalog } : {}),
+        ...(opts.scopeMapping ? { scopeMappingPath: String(opts.scopeMapping) } : {}),
+        ...(exportDir ? { exportFilesDir: exportDir } : {}),
+    });
+    await writeOrStdout(JSON.stringify({ phase: "migrate-native-item-scope", result: m }, null, 2));
+    if (!m.ok)
+        process.exitCode = 1;
+});
+firestoreCmd
+    .command("export-gcs")
+    .description("Export Firestore collection(s) to a GCS bucket as NDJSON + manifest (for --all). Uses Application Default Credentials for GCS.")
+    .requiredOption("--app <appId>", "AppId for Catalox context")
+    .requiredOption("--bucket <name>", "GCS bucket name")
+    .option("--prefix <path>", "Object key prefix inside the bucket", "")
+    .option("--postfix <suffix>", "Optional suffix before .ndjson in each object name", "")
+    .option("--path <collectionPath>", "Single collection path (e.g. apps or catalogData/myId/items)")
+    .option("--all", "Export every root collection; writes catalox-firestore-export-manifest.json", false)
+    .option("--recursive", "With --all: include all document subcollections (expensive)", false)
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const hasPath = Boolean(opts.path && String(opts.path).trim());
+    const all = Boolean(opts.all);
+    if (hasPath === all) {
+        // eslint-disable-next-line no-console
+        console.error("Specify exactly one of: --path <collectionPath> OR --all");
+        process.exitCode = 1;
+        return;
+    }
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const bucket = String(opts.bucket);
+    const gcsPrefix = String(opts.prefix ?? "");
+    const objectNamePostfix = opts.postfix != null ? String(opts.postfix) : undefined;
+    if (hasPath) {
+        const res = await catalox.exportFirestoreCollectionToGcs(ctx, {
+            bucket,
+            gcsPrefix,
+            ...(objectNamePostfix !== undefined && objectNamePostfix !== "" ? { objectNamePostfix } : {}),
+            collectionPath: String(opts.path).trim(),
+        });
+        await writeOrStdout(JSON.stringify(res, null, 2));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    const res = await catalox.exportAllFirestoreCollectionsToGcs(ctx, {
+        bucket,
+        gcsPrefix,
+        ...(objectNamePostfix !== undefined && objectNamePostfix !== "" ? { objectNamePostfix } : {}),
+        recursive: Boolean(opts.recursive),
+    });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+    if (!res.ok)
+        process.exitCode = 1;
+});
+firestoreCmd
+    .command("import-gcs")
+    .description("Restore Firestore from GCS NDJSON produced by export-gcs (single collection or manifest for all). Uses ADC for GCS.")
+    .requiredOption("--app <appId>", "AppId for Catalox context")
+    .requiredOption("--bucket <name>", "GCS bucket name")
+    .option("--prefix <path>", "Object key prefix (must match export)", "")
+    .option("--postfix <suffix>", "Suffix used at export time", "")
+    .option("--path <collectionPath>", "Target Firestore collection path for single-file restore")
+    .option("--object <objectPath>", "Full GCS object path within bucket (overrides prefix/path/postfix inference)")
+    .option("--manifest <objectPath>", "Restore all entries from this manifest object path in the bucket")
+    .option("--restore-all", "Restore all entries using default manifest name under --prefix (same as export --all)", false)
+    .option("--replace", "Delete each destination collection before writing", false)
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const bucket = String(opts.bucket);
+    const gcsPrefix = String(opts.prefix ?? "");
+    const postfix = opts.postfix != null ? String(opts.postfix) : undefined;
+    const replace = Boolean(opts.replace);
+    const manifestPath = opts.manifest != null && String(opts.manifest).trim() ? String(opts.manifest).trim() : "";
+    const restoreAll = Boolean(opts.restoreAll);
+    if (manifestPath || restoreAll) {
+        const res = await catalox.restoreAllFirestoreCollectionsFromGcsManifest(ctx, {
+            bucket,
+            gcsPrefix,
+            ...(postfix !== undefined && postfix !== "" ? { objectNamePostfix: postfix } : {}),
+            ...(manifestPath ? { manifestObjectPath: manifestPath } : {}),
+            replaceDestinationCollection: replace,
+        });
+        await writeOrStdout(JSON.stringify(res, null, 2));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    const collectionPath = opts.path != null && String(opts.path).trim() ? String(opts.path).trim() : "";
+    if (!collectionPath) {
+        // eslint-disable-next-line no-console
+        console.error("For single-collection restore, pass --path (and optionally --object), or use --manifest / --restore-all");
+        process.exitCode = 1;
+        return;
+    }
+    const explicitObject = opts.object != null && String(opts.object).trim() ? String(opts.object).trim() : "";
+    const objectPath = explicitObject ||
+        ndjsonObjectPath({
+            gcsPrefix: normalizeGcsPrefix(gcsPrefix),
+            collectionPath,
+            ...(postfix != null && postfix !== "" ? { objectNamePostfix: postfix } : {}),
+        });
+    const res = await catalox.restoreFirestoreCollectionFromGcs(ctx, {
+        bucket,
+        gcsPrefix,
+        ...(postfix !== undefined && postfix !== "" ? { objectNamePostfix: postfix } : {}),
+        collectionPath,
+        objectPath,
+        replaceDestinationCollection: replace,
+    });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+    if (!res.ok)
+        process.exitCode = 1;
+});
+firestoreCmd
+    .command("compare-gcs")
+    .description("Compare live Firestore to NDJSON in GCS: identical, changed, only-in-Firestore, only-in-bucket (see docs/firestore-gcs-export.md)")
+    .requiredOption("--app <appId>", "AppId for Catalox context")
+    .requiredOption("--bucket <name>", "GCS bucket name")
+    .option("--prefix <path>", "Object key prefix (must match export)", "")
+    .option("--postfix <suffix>", "Suffix used at export time (single-collection mode)", "")
+    .option("--path <collectionPath>", "Firestore collection path for single-object compare")
+    .option("--object <objectPath>", "Full GCS object path (overrides prefix/path/postfix inference)")
+    .option("--manifest <objectPath>", "Compare all entries from this manifest object path")
+    .option("--restore-all", "Compare all entries using default manifest name under --prefix (same as export --all)", false)
+    .option("--max-ids <n>", "Max document ids listed per category (counts are always full)", "500")
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const bucket = String(opts.bucket);
+    const gcsPrefix = String(opts.prefix ?? "");
+    const postfix = opts.postfix != null ? String(opts.postfix) : undefined;
+    const maxIds = Math.max(0, Number.parseInt(String(opts.maxIds ?? "500"), 10) || 0);
+    const manifestPath = opts.manifest != null && String(opts.manifest).trim() ? String(opts.manifest).trim() : "";
+    const restoreAll = Boolean(opts.restoreAll);
+    if (manifestPath || restoreAll) {
+        const res = await catalox.compareAllFirestoreCollectionsWithGcsManifest(ctx, {
+            bucket,
+            gcsPrefix,
+            ...(manifestPath ? { manifestObjectPath: manifestPath } : {}),
+            maxListedIdsPerCategory: maxIds,
+        });
+        await writeOrStdout(JSON.stringify(res, null, 2));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    const collectionPath = opts.path != null && String(opts.path).trim() ? String(opts.path).trim() : "";
+    if (!collectionPath) {
+        // eslint-disable-next-line no-console
+        console.error("Pass --path for single-collection compare, or --manifest / --restore-all for manifest-driven compare");
+        process.exitCode = 1;
+        return;
+    }
+    const explicitObject = opts.object != null && String(opts.object).trim() ? String(opts.object).trim() : "";
+    const objectPath = explicitObject ||
+        ndjsonObjectPath({
+            gcsPrefix: normalizeGcsPrefix(gcsPrefix),
+            collectionPath,
+            ...(postfix != null && postfix !== "" ? { objectNamePostfix: postfix } : {}),
+        });
+    const res = await catalox.compareFirestoreCollectionWithGcsNdjson(ctx, {
+        bucket,
+        gcsPrefix,
+        ...(postfix != null && postfix !== "" ? { objectNamePostfix: postfix } : {}),
+        collectionPath,
+        objectPath,
+        maxListedIdsPerCategory: maxIds,
+    });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+    if (!res.ok)
+        process.exitCode = 1;
+});
+const historyCmd = program.command("history").description("Native item history (Firestore index + GCS payloads)");
+historyCmd
+    .command("list")
+    .description("List catalogItemHistory rows for a catalog (newest first)")
+    .requiredOption("--app <appId>", "AppId for authz")
+    .requiredOption("--catalog <catalogId>", "Catalog id")
+    .option("--item <itemId>", "Filter by logical item id")
+    .option("--op <op>", "Filter by op (update|delete|restore|catalog_delete_bulk|catalog_rename)")
+    .option("--since <iso>", "Client-side filter: ts >= since")
+    .option("--until <iso>", "Client-side filter: ts <= until")
+    .option("--limit <n>", "Page size", "50")
+    .option("--cursor <eventId>", "startAfterEventId for pagination")
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const limit = Math.max(1, Math.min(500, parseInt(String(opts.limit ?? "50"), 10) || 50));
+    const res = await catalox.listCatalogItemHistory(ctx, String(opts.catalog), {
+        ...(opts.item ? { itemId: String(opts.item) } : {}),
+        ...(opts.op ? { op: String(opts.op) } : {}),
+        ...(opts.since ? { since: String(opts.since) } : {}),
+        ...(opts.until ? { until: String(opts.until) } : {}),
+        limit,
+        ...(opts.cursor ? { startAfterEventId: String(opts.cursor) } : {}),
+    });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+});
+historyCmd
+    .command("show")
+    .description("Load index row + GCS payload for one eventId")
+    .requiredOption("--app <appId>", "AppId for authz")
+    .argument("<eventId>", "catalogItemHistory document id")
+    .option("--god", "God mode", false)
+    .action(async (eventId, opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const res = await catalox.getCatalogItemHistoryEvent(ctx, String(eventId));
+    await writeOrStdout(JSON.stringify(res, null, 2));
+    if (!res)
+        process.exitCode = 1;
+});
+historyCmd
+    .command("restore")
+    .description("Restore a native row from a history event (before or after snapshot)")
+    .requiredOption("--app <appId>", "AppId for authz")
+    .argument("<eventId>", "catalogItemHistory document id")
+    .option("--mode <before|after>", "Which snapshot to apply", "before")
+    .option("--god", "God mode", false)
+    .action(async (eventId, opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const mode = String(opts.mode ?? "before").toLowerCase() === "after" ? "after" : "before";
+    const res = await catalox.restoreCatalogItemFromHistory(ctx, String(eventId), { mode });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+});
+historyCmd
+    .command("field-list")
+    .description("List changes to one item field (derived from row-level history snapshots)")
+    .requiredOption("--app <appId>", "AppId for authz")
+    .requiredOption("--catalog <catalogId>", "Catalog id")
+    .requiredOption("--item <itemId>", "Logical item id")
+    .requiredOption("--field <path>", "Field path (e.g. instructions or data.instructions)")
+    .option("--since <iso>", "Client-side filter: ts >= since")
+    .option("--until <iso>", "Client-side filter: ts <= until")
+    .option("--limit <n>", "Max field changes to return", "50")
+    .option("--max-scan <n>", "Max history index rows to scan", "500")
+    .option("--cursor <eventId>", "startAfterEventId from a previous page")
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const limit = Math.max(1, Math.min(500, parseInt(String(opts.limit ?? "50"), 10) || 50));
+    const maxScan = Math.max(limit, Math.min(5000, parseInt(String(opts.maxScan ?? "500"), 10) || 500));
+    const res = await catalox.listCatalogItemFieldHistory(ctx, String(opts.catalog), {
+        itemId: String(opts.item),
+        fieldPath: String(opts.field),
+        ...(opts.since ? { since: String(opts.since) } : {}),
+        ...(opts.until ? { until: String(opts.until) } : {}),
+        limit,
+        maxScan,
+        ...(opts.cursor ? { startAfterEventId: String(opts.cursor) } : {}),
+    });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+});
+historyCmd
+    .command("field-restore")
+    .description("Restore one data or indexed field from a history event")
+    .requiredOption("--app <appId>", "AppId for authz")
+    .requiredOption("--field <path>", "Field path (e.g. instructions or data.instructions)")
+    .argument("<eventId>", "catalogItemHistory document id")
+    .option("--mode <before|after>", "Use before or after snapshot value", "before")
+    .option("--god", "God mode", false)
+    .action(async (eventId, opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const mode = String(opts.mode ?? "before").toLowerCase() === "after" ? "after" : "before";
+    const res = await catalox.restoreCatalogItemFieldFromHistory(ctx, String(eventId), {
+        fieldPath: String(opts.field),
+        mode,
+    });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+});
+historyCmd
+    .command("replay")
+    .description("Replay history up to --as-of and diff-apply to live native items")
+    .requiredOption("--app <appId>", "AppId for authz")
+    .requiredOption("--catalog <catalogId>", "Catalog id")
+    .requiredOption("--as-of <iso>", "Inclusive upper bound on event ts")
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const res = await catalox.replayCatalogToPointInTime(ctx, String(opts.catalog), { asOf: String(opts.asOf) });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+});
+const catalogCmd = program.command("catalog").description("Catalog lifecycle (delete / restore / hard rename)");
+catalogCmd
+    .command("delete")
+    .description("Snapshot catalog to GCS, write delete manifest, then hard-delete Firestore rows (requires record history bucket)")
+    .requiredOption("--app <appId>", "AppId for authz")
+    .requiredOption("--catalog <catalogId>", "Catalog id")
+    .option("--confirm", "Must pass --confirm to run", false)
+    .option("--backup-bucket <name>", "Optional: run backupData mode=gcs to this bucket before delete")
+    .option("--backup-prefix <path>", "Optional gcsPrefix for pre-delete backupData")
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    if (!opts.confirm) {
+        // eslint-disable-next-line no-console
+        console.error("Refusing to delete without --confirm");
+        process.exitCode = 1;
+        return;
+    }
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const res = await catalox.deleteCatalog(ctx, String(opts.catalog), {
+        confirm: true,
+        ...(opts.backupBucket ? { gcsBackupBucket: String(opts.backupBucket).trim() } : {}),
+        ...(opts.backupPrefix ? { gcsBackupPrefix: String(opts.backupPrefix).trim() } : {}),
+    });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+    if (!res.ok)
+        process.exitCode = 1;
+});
+catalogCmd
+    .command("restore")
+    .description("Restore a catalog from a delete manifest path (requires superAdmin context / --god)")
+    .requiredOption("--app <appId>", "AppId (superAdmin)")
+    .requiredOption("--manifest <relativePath>", "GCS object path relative to record-history prefix, ending in manifest.json")
+    .option("--god", "God mode (superAdmin)", true)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: true });
+    const res = await catalox.restoreDeletedCatalog(ctx, {
+        gcsManifestRelativePath: String(opts.manifest).trim(),
+    });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+    if (!res.ok)
+        process.exitCode = 1;
+});
+catalogCmd
+    .command("rename")
+    .description("Hard rename catalog id (copy + rewrite + delete source; requires record history bucket)")
+    .requiredOption("--app <appId>", "AppId for authz")
+    .requiredOption("--from <catalogId>", "Source catalog id")
+    .requiredOption("--to <catalogId>", "Target catalog id (must not exist)")
+    .option("--backup-bucket <name>", "Optional: backupData gcs bucket before rename")
+    .option("--backup-prefix <path>", "Optional gcsPrefix for pre-rename backup")
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const res = await catalox.renameCatalog(ctx, String(opts.from), String(opts.to), {
+        ...(opts.backupBucket ? { gcsBackupBucket: String(opts.backupBucket).trim() } : {}),
+        ...(opts.backupPrefix ? { gcsBackupPrefix: String(opts.backupPrefix).trim() } : {}),
+    });
+    await writeOrStdout(JSON.stringify(res, null, 2));
+    if (!res.ok)
+        process.exitCode = 1;
+});
+const toolboxCmd = program
+    .command("toolbox")
+    .description("Operator helpers: diagnose app↔catalog access (bindings) and repair common mistakes");
+toolboxCmd
+    .command("check-access")
+    .description("Read Firestore catalogBindings doc, catalog row, and run listCatalogItemsWithOutcome (same auth rules as runtime)")
+    .requiredOption("--app <appId>", "App id (must match CataloxContext.appId in your host)")
+    .requiredOption("--catalog <catalogId>", "Catalog id (e.g. entities)")
+    .option("--show-all-bindings", "List every catalogBindings row for this catalogId (who else is bound)", false)
+    .action(async (opts) => {
+    const { catalox, firestore } = createCataloxFromEnv();
+    const appId = String(opts.app).trim();
+    const catalogId = String(opts.catalog).trim();
+    const bindingDocId = `${appId}:${catalogId}`;
+    const bindingSnap = await firestore.collection("catalogBindings").doc(bindingDocId).get();
+    const catalog = await catalox.getCatalog({ appId }, catalogId);
+    const listSim = await catalox.listCatalogItemsWithOutcome({ appId }, catalogId, { limit: 1 });
+    const recommendations = [];
+    if (!catalog) {
+        recommendations.push("Catalog document missing under `catalogs` (typo in catalogId, or catalog never created in this project).");
+    }
+    if (!bindingSnap.exists) {
+        recommendations.push(`No binding document at catalogBindings/${bindingDocId}. Fix: catalox toolbox ensure-binding --app ${appId} --catalog ${catalogId} (use --god if your CLI context app differs from --app).`);
+    }
+    else {
+        const b = bindingSnap.data();
+        const status = b?.status;
+        const access = b?.access;
+        if (status !== "active") {
+            recommendations.push(`Binding status is "${String(status)}" (expected active). Fix: catalox toolbox repair-binding --god --app ${appId} --catalog ${catalogId}`);
+        }
+        if (!access?.canRead) {
+            recommendations.push("Binding has canRead false or missing; readers will be denied.");
+        }
+    }
+    if (listSim.outcome === "denied") {
+        recommendations.push("Simulated list returned denied — matches missing/inactive binding or insufficient access flags.");
+    }
+    if (listSim.outcome === "misconfigured") {
+        recommendations.push("Simulated list returned misconfigured (catalog/adapter/descriptor issue after authz).");
+    }
+    if (listSim.outcome === "mapping_blocked") {
+        recommendations.push("Simulated list returned mapping_blocked (mapping spec / adapter execution).");
+    }
+    let allBindingsForCatalog;
+    if (opts.showAllBindings) {
+        const q = await firestore.collection("catalogBindings").where("catalogId", "==", catalogId).get();
+        allBindingsForCatalog = q.docs.map((d) => ({ id: d.id, ...d.data() }));
+    }
+    const payload = {
+        appId,
+        catalogId,
+        bindingDocId,
+        bindingDocExists: bindingSnap.exists,
+        binding: bindingSnap.exists ? bindingSnap.data() : null,
+        catalogExists: Boolean(catalog),
+        ...(catalog ? { catalogMetadataStatus: catalog.metadata?.status } : {}),
+        simulatedListOutcome: listSim.outcome,
+        ...(listSim.outcome === "denied" && "error" in listSim
+            ? { deniedMessage: listSim.error?.message }
+            : {}),
+        ...(allBindingsForCatalog ? { allBindingsForCatalog } : {}),
+        recommendations,
+    };
+    await writeOrStdout(JSON.stringify(payload, null, 2));
+    if (listSim.outcome !== "ok" && listSim.outcome !== "empty")
+        process.exitCode = 1;
+});
+toolboxCmd
+    .command("ensure-binding")
+    .description("Create catalogBindings/{appId:catalogId} if absent (Catalox ensureBinding). Does not upgrade access if a row already exists.")
+    .requiredOption("--app <appId>", "App id that should receive catalog access")
+    .requiredOption("--catalog <catalogId>", "Catalog id")
+    .option("--write", "Set canWrite true (default false)", false)
+    .option("--admin", "Set canAdmin true", false)
+    .option("--god", "Super-admin context: required when CLI context app is not the same as --app (see ensureBinding rules)", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const appId = String(opts.app).trim();
+    const ctx = baseContext({ app: appId, god: Boolean(opts.god) });
+    await catalox.ensureBinding(ctx, {
+        appId,
+        catalogId: String(opts.catalog).trim(),
+        access: {
+            canRead: true,
+            canWrite: Boolean(opts.write),
+            ...(opts.admin ? { canAdmin: true } : {}),
+        },
+    });
+    await writeOrStdout(JSON.stringify({
+        ok: true,
+        hint: "If a binding already existed, ensureBinding is a no-op (use toolbox repair-binding to change access or reactivate).",
+    }, null, 2));
+});
+toolboxCmd
+    .command("repair-binding")
+    .description("Merge-write catalogBindings doc to status=active and access flags (use when ensure-binding no-ops on a disabled or wrong-access row)")
+    .requiredOption("--app <appId>", "App id")
+    .requiredOption("--catalog <catalogId>", "Catalog id")
+    .option("--write", "Set canWrite true", false)
+    .option("--admin", "Set canAdmin true", false)
+    .option("--god", "Required: confirms operator intent (writes Firestore as Admin SDK)", false)
+    .action(async (opts) => {
+    if (!opts.god) {
+        // eslint-disable-next-line no-console
+        console.error("repair-binding requires --god");
+        process.exitCode = 1;
+        return;
+    }
+    const { firestore } = createCataloxFromEnv();
+    const appId = String(opts.app).trim();
+    const catalogId = String(opts.catalog).trim();
+    const bindingDocId = `${appId}:${catalogId}`;
+    const now = new Date().toISOString();
+    const snap = await firestore.collection("catalogBindings").doc(bindingDocId).get();
+    const prev = snap.exists ? snap.data() : {};
+    const createdAt = typeof prev.createdAt === "string" ? prev.createdAt : now;
+    await firestore
+        .collection("catalogBindings")
+        .doc(bindingDocId)
+        .set({
+        bindingId: bindingDocId,
+        appId,
+        catalogId,
+        access: {
+            canRead: true,
+            canWrite: Boolean(opts.write),
+            ...(opts.admin ? { canAdmin: true } : {}),
+        },
+        status: "active",
+        createdAt,
+        updatedAt: now,
+    }, { merge: true });
+    await writeOrStdout(JSON.stringify({ ok: true, bindingDocId, updatedAt: now }, null, 2));
+});
+toolboxCmd
+    .command("unbind-catalog")
+    .description("Disable app↔catalog binding (sets catalogBindings status to disabled; same row id as ensure-binding)")
+    .requiredOption("--app <appId>", "App id")
+    .requiredOption("--catalog <catalogId>", "Catalog id")
+    .option("--god", "Super-admin context: required when CLI context app is not the same as --app (see bindCatalogToApp / unbind rules)", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const appId = String(opts.app).trim();
+    const ctx = baseContext({ app: appId, god: Boolean(opts.god) });
+    await catalox.unbindCatalogFromApp(ctx, appId, String(opts.catalog).trim());
+    await writeOrStdout(JSON.stringify({
+        ok: true,
+        bindingDocId: `${appId}:${String(opts.catalog).trim()}`,
+        hint: "Binding row is disabled (not deleted). Re-enable with toolbox repair-binding --god ...",
+    }, null, 2));
+});
+program.parseAsync(process.argv).catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error(err instanceof Error ? err.message : err);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=index.js.map