@x12i/catalox 3.0.0 → 3.1.1

package/dist/src/catalox/native-scope.js

@@ -0,0 +1,184 @@
+import { CatalogAccessDeniedError } from "../contracts/errors.js";
+import { resolveCatalogItemId } from "./identity.js";
+const CX = "cx~";
+function b64u(s) {
+    return Buffer.from(s, "utf8").toString("base64url");
+}
+function b64uDec(s) {
+    return Buffer.from(s, "base64url").toString("utf8");
+}
+/** Global / legacy rows use the logical id as the Firestore document id. */
+export function encodeNativeItemStorageDocId(logicalItemId, scope) {
+    if (scope.kind === "global")
+        return String(logicalItemId);
+    const log = b64u(String(logicalItemId));
+    if (scope.kind === "account") {
+        return `${CX}a~${b64u(scope.accountId)}~${log}`;
+    }
+    if (scope.kind === "agent") {
+        return `${CX}ag~${b64u(scope.accountId)}~${b64u(scope.agentId)}~${log}`;
+    }
+    return `${CX}u~${b64u(scope.accountId)}~${b64u(scope.userId)}~${log}`;
+}
+export function decodeNativeItemStorageDocId(docId) {
+    if (!docId.startsWith(CX)) {
+        return { logicalItemId: docId, scope: { kind: "global" } };
+    }
+    const rest = docId.slice(CX.length);
+    const parts = rest.split("~");
+    if (parts[0] === "a" && parts.length === 3) {
+        return { logicalItemId: b64uDec(parts[2]), scope: { kind: "account", accountId: b64uDec(parts[1]) } };
+    }
+    if (parts[0] === "ag" && parts.length === 4) {
+        return {
+            logicalItemId: b64uDec(parts[3]),
+            scope: { kind: "agent", accountId: b64uDec(parts[1]), agentId: b64uDec(parts[2]) },
+        };
+    }
+    if (parts[0] === "u" && parts.length === 4) {
+        return {
+            logicalItemId: b64uDec(parts[3]),
+            scope: { kind: "user", accountId: b64uDec(parts[1]), userId: b64uDec(parts[2]) },
+        };
+    }
+    return null;
+}
+export function normalizeStoredScope(s) {
+    if (!s || s.kind === "global")
+        return { kind: "global" };
+    return s;
+}
+export function isGlobalPhysicalRow(r) {
+    const sl = r.indexed?.scopeLayer;
+    if (sl != null && sl !== "global")
+        return false;
+    return normalizeStoredScope(scopeFromRecordField(r.scope)).kind === "global";
+}
+export function scopeFromRecordField(scope) {
+    if (!scope || typeof scope !== "object")
+        return { kind: "global" };
+    const o = scope;
+    const k = o.kind;
+    if (k === "account" && typeof o.accountId === "string") {
+        return {
+            kind: "account",
+            accountId: o.accountId,
+            ...(Array.isArray(o.agentIds) ? { agentIds: o.agentIds.filter((x) => typeof x === "string") } : {}),
+            ...(Array.isArray(o.userIds) ? { userIds: o.userIds.filter((x) => typeof x === "string") } : {}),
+        };
+    }
+    if (k === "agent" && typeof o.accountId === "string" && typeof o.agentId === "string") {
+        return { kind: "agent", accountId: o.accountId, agentId: o.agentId };
+    }
+    if (k === "user" && typeof o.accountId === "string" && typeof o.userId === "string") {
+        return { kind: "user", accountId: o.accountId, userId: o.userId };
+    }
+    return { kind: "global" };
+}
+/** Indexed mirror for Firestore `indexed.*` queries. */
+export function indexedScopeFields(scope) {
+    const s = normalizeStoredScope(scope);
+    if (s.kind === "global")
+        return { scopeLayer: "global" };
+    if (s.kind === "account") {
+        return { scopeLayer: "account", scopeAccountId: s.accountId };
+    }
+    if (s.kind === "agent") {
+        return {
+            scopeLayer: "agent",
+            scopeAccountId: s.accountId,
+            scopeAgentId: s.agentId,
+        };
+    }
+    return {
+        scopeLayer: "user",
+        scopeAccountId: s.accountId,
+        scopeUserId: s.userId,
+    };
+}
+export function accountAudienceMatches(scope, fetch) {
+    const agents = scope.agentIds ?? [];
+    const users = scope.userIds ?? [];
+    if (agents.length === 0 && users.length === 0)
+        return true;
+    if (fetch.agentId && agents.includes(fetch.agentId))
+        return true;
+    if (fetch.userId && users.includes(fetch.userId))
+        return true;
+    return false;
+}
+export function physicalRowMatchesFetchScope(scope, fetch) {
+    const s = normalizeStoredScope(scope);
+    if (s.kind === "global")
+        return true;
+    if (!fetch.accountId)
+        return false;
+    if (s.kind === "account") {
+        if (s.accountId !== fetch.accountId)
+            return false;
+        return accountAudienceMatches(s, fetch);
+    }
+    if (s.kind === "agent") {
+        if (s.accountId !== fetch.accountId)
+            return false;
+        if (!fetch.agentId)
+            return false;
+        return s.agentId === fetch.agentId;
+    }
+    if (s.kind === "user") {
+        if (s.accountId !== fetch.accountId)
+            return false;
+        if (!fetch.userId)
+            return false;
+        return s.userId === fetch.userId;
+    }
+    return false;
+}
+export function resolveMergeIdentityMode(identity) {
+    if (identity.overrideKeys?.length)
+        return "byOverrideKeys";
+    if (identity.itemIdStrategy === "natural" || identity.itemIdStrategy === "composite")
+        return "byItemId";
+    return "none";
+}
+export function mergeIdentityKey(identity, data, indexed) {
+    const mode = resolveMergeIdentityMode(identity);
+    if (mode === "none")
+        return null;
+    if (mode === "byItemId") {
+        try {
+            return resolveCatalogItemId({ identity, data });
+        }
+        catch {
+            return null;
+        }
+    }
+    const keys = identity.overrideKeys ?? [];
+    const parts = keys.map((k) => {
+        const v = data[k] ?? indexed?.[k];
+        if (v == null || v === "")
+            return null;
+        return String(v);
+    });
+    if (parts.some((p) => p == null))
+        return null;
+    return parts.join(":");
+}
+export function shallowMergeData(base, overlay) {
+    return { ...base, ...overlay };
+}
+export function parseWriteScopeInput(raw) {
+    if (raw == null)
+        return undefined;
+    if (typeof raw !== "object")
+        return undefined;
+    return scopeFromRecordField(raw);
+}
+export function assertSuperAdminForNonGlobalScope(superAdmin, scope) {
+    if (normalizeStoredScope(scope).kind === "global")
+        return;
+    if (!superAdmin) {
+        throw new CatalogAccessDeniedError({ reason: "super_admin_required_for_scoped_write" });
+    }
+}
+//# sourceMappingURL=native-scope.js.map

package/dist/src/catalox/native-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-scope.js","sourceRoot":"","sources":["../../../src/catalox/native-scope.ts"],"names":[],"mappings":"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"}

package/dist/src/catalox/record-history.d.ts

@@ -0,0 +1,53 @@
+import type { CatalogId } from "../contracts/ids.js";
+import type { NativeCatalogItemRecord } from "../contracts/items.js";
+import type { CatalogItemHistoryEventV1, CatalogItemHistoryIndexRecord, CatalogItemHistoryOp } from "../contracts/record-history.js";
+import type { CataloxContext } from "../contracts/context.js";
+import { CatalogItemHistoryStore } from "../firebase/catalog-item-history-store.js";
+import { type CataloxHelpersGcsClient } from "./backup-data.js";
+export type RecordHistoryDeps = {
+    store: CatalogItemHistoryStore;
+    gcsBucket: string;
+    /** Prefix without leading slash; no trailing slash (helpers client normalizes). */
+    gcsBasePrefix: string;
+    failClosed: boolean;
+};
+export declare function normalizeRecordHistoryGcsPrefix(raw: string | undefined): string;
+export declare function fingerprintNativeRecord(rec: NativeCatalogItemRecord | null | undefined): string | undefined;
+/** Relative object path under the record-history prefix. */
+export declare function buildRecordHistoryGcsRelativePath(params: {
+    catalogId: CatalogId;
+    op: CatalogItemHistoryOp;
+    itemId: string;
+    ts: string;
+}): string;
+export declare function buildRecordHistoryGcsClient(deps: RecordHistoryDeps): CataloxHelpersGcsClient;
+export type EmitRecordHistoryParams = {
+    catalogId: CatalogId;
+    itemId: string;
+    storageDocId?: string;
+    op: CatalogItemHistoryOp;
+    before?: NativeCatalogItemRecord | null;
+    after?: NativeCatalogItemRecord | null;
+    manifest?: Record<string, unknown>;
+};
+export type EmitRecordHistoryResult = {
+    ok: true;
+    eventId: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function emitRecordHistoryEvent(deps: RecordHistoryDeps, context: CataloxContext, params: EmitRecordHistoryParams): Promise<EmitRecordHistoryResult>;
+export declare function readRecordHistoryEventPayload(deps: RecordHistoryDeps, indexRow: CatalogItemHistoryIndexRecord): Promise<CatalogItemHistoryEventV1>;
+export declare function emitRecordHistoryEventWithCustomPath(deps: RecordHistoryDeps, context: CataloxContext, params: {
+    gcsRelativePath: string;
+    catalogId: CatalogId;
+    itemId: string;
+    storageDocId?: string;
+    op: CatalogItemHistoryOp;
+    before?: NativeCatalogItemRecord | null;
+    after?: NativeCatalogItemRecord | null;
+    manifest?: Record<string, unknown>;
+}): Promise<EmitRecordHistoryResult>;
+export declare function recordHistoryKeyForNativeRow(_catalogId: CatalogId, rec: NativeCatalogItemRecord): string;
+//# sourceMappingURL=record-history.d.ts.map

package/dist/src/catalox/record-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-history.d.ts","sourceRoot":"","sources":["../../../src/catalox/record-history.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EACV,yBAAyB,EACzB,6BAA6B,EAC7B,oBAAoB,EACrB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AAEpF,OAAO,EAAiC,KAAK,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE/F,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,uBAAuB,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAI/E;AAgBD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAG3G;AAMD,4DAA4D;AAC5D,wBAAgB,iCAAiC,CAAC,MAAM,EAAE;IACxD,SAAS,EAAE,SAAS,CAAC;IACrB,EAAE,EAAE,oBAAoB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,MAAM,CAQT;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,iBAAiB,GAAG,uBAAuB,CAE5F;AAED,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,EAAE,EAAE,oBAAoB,CAAC;IACzB,MAAM,CAAC,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnG,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,uBAAuB,CAAC,CAsDlC;AAED,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,6BAA6B,GACtC,OAAO,CAAC,yBAAyB,CAAC,CAMpC;AAED,wBAAsB,oCAAoC,CACxD,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE;IACN,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,EAAE,EAAE,oBAAoB,CAAC;IACzB,MAAM,CAAC,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GACA,OAAO,CAAC,uBAAuB,CAAC,CA2ClC;AAED,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,EAAE,uBAAuB,GAAG,MAAM,CAExG"}

package/dist/src/catalox/record-history.js

@@ -0,0 +1,158 @@
+import { createHash, randomUUID } from "node:crypto";
+import { CatalogItemHistoryStore } from "../firebase/catalog-item-history-store.js";
+import { storageDocIdForNativeRecord } from "../firebase/native-item-store.js";
+import { createCataloxHelpersGcsClient } from "./backup-data.js";
+export function normalizeRecordHistoryGcsPrefix(raw) {
+    const p = (raw ?? "catalox-record-history/").trim();
+    if (!p)
+        return "catalox-record-history";
+    return p.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function stableStringify(value) {
+    const seen = new WeakSet();
+    const walk = (v) => {
+        if (v == null || typeof v !== "object")
+            return v;
+        if (seen.has(v))
+            return "[Circular]";
+        seen.add(v);
+        if (Array.isArray(v))
+            return v.map(walk);
+        const out = {};
+        for (const k of Object.keys(v).sort())
+            out[k] = walk(v[k]);
+        return out;
+    };
+    return JSON.stringify(walk(value));
+}
+export function fingerprintNativeRecord(rec) {
+    if (!rec)
+        return undefined;
+    return createHash("sha256").update(stableStringify(rec)).digest("hex");
+}
+function hashItemIdSegment(itemId) {
+    return createHash("sha256").update(String(itemId)).digest("hex").slice(0, 16);
+}
+/** Relative object path under the record-history prefix. */
+export function buildRecordHistoryGcsRelativePath(params) {
+    const d = new Date(params.ts);
+    const yyyy = String(d.getUTCFullYear());
+    const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
+    const dd = String(d.getUTCDate()).padStart(2, "0");
+    const idHash = hashItemIdSegment(params.itemId);
+    const safeTs = params.ts.replace(/[/\\:]/g, "_");
+    return `records/${String(params.catalogId)}/${yyyy}/${mm}/${dd}/${safeTs}__${params.op}__${idHash}.ndjson`;
+}
+export function buildRecordHistoryGcsClient(deps) {
+    return createCataloxHelpersGcsClient(deps.gcsBucket, deps.gcsBasePrefix);
+}
+export async function emitRecordHistoryEvent(deps, context, params) {
+    const eventId = randomUUID();
+    const ts = new Date().toISOString();
+    const actorId = context.userId ?? context.actor?.id;
+    const gcsRelativePath = buildRecordHistoryGcsRelativePath({
+        catalogId: params.catalogId,
+        op: params.op,
+        itemId: params.itemId,
+        ts,
+    });
+    const fpBefore = fingerprintNativeRecord(params.before ?? undefined);
+    const fpAfter = fingerprintNativeRecord(params.after ?? undefined);
+    const payload = {
+        schemaVersion: 1,
+        eventId,
+        op: params.op,
+        catalogId: params.catalogId,
+        itemId: params.itemId,
+        ...(params.storageDocId != null ? { storageDocId: params.storageDocId } : {}),
+        ...(actorId ? { actorId } : {}),
+        ts,
+        ...(fpBefore != null ? { fingerprintBefore: fpBefore } : {}),
+        ...(fpAfter != null ? { fingerprintAfter: fpAfter } : {}),
+        ...(params.before !== undefined ? { before: params.before } : {}),
+        ...(params.after !== undefined ? { after: params.after } : {}),
+        ...(params.manifest != null ? { manifest: params.manifest } : {}),
+    };
+    const line = `${JSON.stringify(payload)}\n`;
+    try {
+        const gcs = buildRecordHistoryGcsClient(deps);
+        await gcs.uploadObject(gcsRelativePath, line, { contentType: "application/x-ndjson", resumable: false });
+        const indexRow = {
+            eventId,
+            catalogId: params.catalogId,
+            itemId: params.itemId,
+            op: params.op,
+            ...(actorId ? { actorId } : {}),
+            ts,
+            gcsRelativePath,
+            ...(fpBefore != null ? { fingerprintBefore: fpBefore } : {}),
+            ...(fpAfter != null ? { fingerprintAfter: fpAfter } : {}),
+            ...(params.storageDocId != null ? { storageDocId: params.storageDocId } : {}),
+        };
+        await deps.store.upsertIndex(indexRow);
+        return { ok: true, eventId };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (deps.failClosed)
+            throw e;
+        return { ok: false, error: msg };
+    }
+}
+export async function readRecordHistoryEventPayload(deps, indexRow) {
+    const gcs = buildRecordHistoryGcsClient(deps);
+    const buf = await gcs.readObjectBuffer(indexRow.gcsRelativePath);
+    const text = buf.toString("utf8").trim();
+    const firstLine = text.split("\n")[0] ?? text;
+    return JSON.parse(firstLine);
+}
+export async function emitRecordHistoryEventWithCustomPath(deps, context, params) {
+    const eventId = randomUUID();
+    const ts = new Date().toISOString();
+    const actorId = context.userId ?? context.actor?.id;
+    const fpBefore2 = fingerprintNativeRecord(params.before ?? undefined);
+    const fpAfter2 = fingerprintNativeRecord(params.after ?? undefined);
+    const payload = {
+        schemaVersion: 1,
+        eventId,
+        op: params.op,
+        catalogId: params.catalogId,
+        itemId: params.itemId,
+        ...(params.storageDocId != null ? { storageDocId: params.storageDocId } : {}),
+        ...(actorId ? { actorId } : {}),
+        ts,
+        ...(fpBefore2 != null ? { fingerprintBefore: fpBefore2 } : {}),
+        ...(fpAfter2 != null ? { fingerprintAfter: fpAfter2 } : {}),
+        ...(params.before !== undefined ? { before: params.before } : {}),
+        ...(params.after !== undefined ? { after: params.after } : {}),
+        ...(params.manifest != null ? { manifest: params.manifest } : {}),
+    };
+    const line = `${JSON.stringify(payload)}\n`;
+    try {
+        const gcs = buildRecordHistoryGcsClient(deps);
+        await gcs.uploadObject(params.gcsRelativePath, line, { contentType: "application/x-ndjson", resumable: false });
+        await deps.store.upsertIndex({
+            eventId,
+            catalogId: params.catalogId,
+            itemId: params.itemId,
+            op: params.op,
+            ...(actorId ? { actorId } : {}),
+            ts,
+            gcsRelativePath: params.gcsRelativePath,
+            ...(fpBefore2 != null ? { fingerprintBefore: fpBefore2 } : {}),
+            ...(fpAfter2 != null ? { fingerprintAfter: fpAfter2 } : {}),
+            ...(params.storageDocId != null ? { storageDocId: params.storageDocId } : {}),
+        });
+        return { ok: true, eventId };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (deps.failClosed)
+            throw e;
+        return { ok: false, error: msg };
+    }
+}
+export function recordHistoryKeyForNativeRow(_catalogId, rec) {
+    return storageDocIdForNativeRecord(rec);
+}
+//# sourceMappingURL=record-history.js.map

package/dist/src/catalox/record-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-history.js","sourceRoot":"","sources":["../../../src/catalox/record-history.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/index.js

@@ -49,7 +49,7 @@ function baseContext(opts) {
     return {
         appId,
         ...(storeId ? { storeId } : {}),
-        ...(opts.god ? { isGodMode: true } : {}),
+        ...(opts.god ? { superAdmin: true } : {}),
         ...(userId ? { userId, actor: { type: "user", id: userId } } : {}),
     };
 }
@@ -669,6 +669,138 @@ firestoreCmd
     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("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;
+});
 program.parseAsync(process.argv).catch((err) => {
     // eslint-disable-next-line no-console
     console.error(err instanceof Error ? err.message : err);