@x12i/catalox 4.0.3 → 4.1.0

package/dist/src/cli/index.js

@@ -9,7 +9,9 @@ import { CATALOX_GCS_BACKUP_MANIFEST_FILENAME, createCataloxHelpersGcsClient } f
 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 } from "../catalox/seed-preset.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";
@@ -268,6 +270,286 @@ seedCmd
         : 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);
+    await writeOrStdout(JSON.stringify({
+        ok: true,
+        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,
+        },
+    }, null, 2));
+});
+const itemsCmd = program.command("items").description("Catalog items: validate, list, CRUD, batch upsert, export (native + mapped read paths)");
+itemsCmd
+    .command("validate")
+    .description("validateCatalog (catalog) and/or validateCatalogItem (relations vs descriptor)")
+    .requiredOption("--app <appId>", "AppId context")
+    .option("--store <storeId>", "StoreId context (overrides CATALOX_STORE_ID)")
+    .requiredOption("--catalog <catalogId>", "Catalog id")
+    .option("--item <itemId>", "When set, validateCatalogItem; otherwise validateCatalog")
+    .option("--out <path>", "Write JSON to file instead of stdout")
+    .option("--god", "God mode (bypass binding checks where applicable)", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, 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());
+        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("--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 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 } : {}),
+    });
+    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("--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);
+    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 res = await catalox.listCatalogItemsWithOutcome(ctx, catalogId, {
+        limit: opts.limit,
+        offset: opts.offset,
+        ...(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("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");
@@ -781,6 +1063,158 @@ catalogCmd
     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);