@x12i/catalox 3.1.1 → 3.3.0

package/README.md

@@ -54,7 +54,9 @@ Scoping:
 - You can scope the service account to **Firestore-related IAM roles** and to a specific **project**.
 - You generally cannot scope an Admin SDK credential to only certain collections/documents via IAM the way client rules work.
 
-To connect to a real Firebase project, initialize `firebase-admin` using `GOOGLE_APPLICATION_CREDENTIALS` (service account JSON) or your preferred Admin initialization strategy.
+To connect to a real Firebase project, initialize `firebase-admin` using `GOOGLE_APPLICATION_CREDENTIALS` (service account JSON), workload identity, or your preferred Admin initialization strategy.
+
+This repo’s CLI + live tests typically load `.env` via **`@x12i/env`** and support **`GOOGLE_SERVICE_ACCOUNT_BASE64`** as a convenient local/dev secret carrier. That value is picked up **automatically** by the supporting x12i tooling (including **`@x12i/helpers/gcs`**) when present—**upstream code does not need to plumb it through**; just set it in the environment.
 
 Minimal example:
 
@@ -81,6 +83,8 @@ Example `.env` (do not commit secrets):
 ```bash
 MONGO_URI=mongodb://127.0.0.1:27017
 GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+# Alternative (supported by this repo’s CLI/tests and x12i helpers): base64-encoded service account JSON
+# GOOGLE_SERVICE_ACCOUNT_BASE64=...
 # Or (used by the packaged CLI migration + live integration tests):
 FIREBASE_SERVICE_ACCOUNT_PATH=/path/to/service-account.json
 FIREBASE_PROJECT_ID=your-project-id
@@ -104,6 +108,7 @@ The `catalox` binary loads `.env` via `dotenv`. Use **`CATALOX_*`** for **Catalo
 - **`CATALOX_USER_ID`** — Optional user id / actor for authz-sensitive CLI paths.
 - **`CATALOX_MONGO_URI`** — If set, enables the Mongo catalog adapter in the CLI (wired via **`createCatalox`** in `src/catalox/create-catalox.ts`, called from `src/cli/index.ts`).
 - **`CATALOX_RECORD_HISTORY_BUCKET`** — If set, **`createCatalox`** wires **`recordHistory`** (GCS payloads + **`catalogItemHistory`** on native writes; also required for **`catalox history …`** to persist new events).
+- **`CATALOX_BUCKET`** — Default GCS bucket for Catalox storage features (used by the CLI and live tests; also used as a fallback for `CATALOX_RECORD_HISTORY_BUCKET` when wiring `recordHistory` via env).
 - **`CATALOX_RECORD_HISTORY_PREFIX`** — Optional GCS prefix for record history (default `catalox-record-history/`).
 - **`CATALOX_RECORD_HISTORY_FAIL_CLOSED`** — When **`1`**, failed history writes fail the parent Firestore mutation.
 

package/dist/src/catalox/backup-data.d.ts

@@ -1,6 +1,5 @@
 import { Readable } from "node:stream";
 import { type Firestore } from "firebase-admin/firestore";
-import { type Db } from "mongodb";
 import type { CatalogId } from "../contracts/ids.js";
 import type { BackupDataInput, BackupDataResult } from "../contracts/backup.js";
 import type { PruneGcsBackupRunsInput, PruneGcsBackupRunsResult } from "../contracts/restore.js";
@@ -29,8 +28,6 @@ export declare function discoverNativeCatalogIds(fs: Firestore, catalogs: Catalo
     catalogIds?: CatalogId[];
     appId?: string;
 }): Promise<CatalogId[]>;
-/** Delete Mongo `backupRuns` documents with createdAt older than cutoff ISO string. */
-export declare function pruneMongoBackupRuns(db: Db, createdBeforeIso: string): Promise<number>;
 /** Exported for tests: `{gcsPrefix|default}/{formatBackupTimestamp}/` without trailing slash (helpers client prefix). */
 export declare function gcsBackupRunFolder(ts: string, gcsPrefix?: string): string;
 /** Subset of `@x12i/helpers/gcs` client used by Catalox backup / restore / prune. */
@@ -57,6 +54,7 @@ export type CataloxHelpersGcsClient = {
     deleteObject: (objectName: string) => Promise<void>;
 };
 export declare const CATALOX_GCS_BACKUP_MANIFEST_FILENAME = "catalox-backup-manifest.json";
+export declare function defaultCataloxBucketName(): string;
 /** Same as internal backup client: `prefix` is the logical root prepended to relative object names. */
 export declare function createCataloxHelpersGcsClient(bucket: string, prefixWithoutTrailingSlash: string): CataloxHelpersGcsClient;
 /** Delete every object under one backup run folder (`…/{timestamp}/…`). */
@@ -68,8 +66,5 @@ export declare function deleteCataloxGcsBackupRunObjects(bucket: string, runFold
  * Folder names are sorted lexicographically (compatible with `formatBackupTimestamp` ISO-style tokens).
  */
 export declare function pruneGcsBackupRuns(input: PruneGcsBackupRunsInput): Promise<PruneGcsBackupRunsResult>;
-export declare function pruneFirebaseVersionedBackups(firestore: Firestore, keepLast: number): Promise<{
-    deleted: string[];
-}>;
 export declare function runBackupData(deps: BackupDataDeps, input: BackupDataInput): Promise<BackupDataResult>;
 //# sourceMappingURL=backup-data.d.ts.map

package/dist/src/catalox/backup-data.d.ts.map

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

package/dist/src/catalox/backup-data.js

@@ -1,13 +1,12 @@
 import { createRequire } from "node:module";
 import { Readable } from "node:stream";
+import { readFileSync } from "node:fs";
 import { FieldPath, } from "firebase-admin/firestore";
-import { MongoClient } from "mongodb";
 import { CatalogStore } from "../firebase/catalog-store.js";
 import { BindingStore } from "../firebase/binding-store.js";
 import { FirestoreStore } from "../firebase/firestore-store.js";
 import { flatNativeItemsCollectionRef, legacyNativeItemsCollectionRef, nativeItemsCollectionId, resolveNativeItemsLayout, } from "../firebase/catalog-data-paths.js";
 import { collectionRefFromSlashPath } from "../firebase/firestore-collection-path.js";
-const MONGO_BACKUP_DB = "catalox-backups";
 export const BACKUP_METADATA_SOURCE_NAMES = [
     "apps",
     "catalogs",
@@ -39,24 +38,7 @@ export function firebaseLatestName(logical) {
 export function firebaseVersionedName(ts, logical) {
     return `${ts}__backup-${logical}`;
 }
-function mongoTmpName(logical) {
-    return `__tmp_backup_${logical}`;
-}
-function mongoVersionedName(ts, logical) {
-    return `${ts}__${logical}`;
-}
-function mongoNativeItemsCollectionName(catalogId) {
-    return `catalogData__${sanitizeMongoCollectionPart(catalogId)}`;
-}
-function mongoSnapshotCollectionName(catalogId) {
-    return `catalogSnapshots__${sanitizeMongoCollectionPart(catalogId)}`;
-}
-function mongoSnapshotRunCollectionName(catalogId, runId) {
-    return `catalogSnapshotsRun__${sanitizeMongoCollectionPart(catalogId)}__${sanitizeMongoCollectionPart(runId)}`;
-}
-function sanitizeMongoCollectionPart(s) {
-    return String(s).replace(/[^a-zA-Z0-9_-]/g, "_");
-}
+// Mongo backup mode has been removed; use explicit Mongo export/import instead.
 export function firebaseNativeLogical(catalogId) {
     return `catalogData--${catalogId}`;
 }
@@ -132,208 +114,26 @@ async function copyNativeCatalogToFirestoreBackup(fs, catalogId, destCollectionP
         : flatNativeItemsCollectionRef(fs, catalogId);
     await paginatedCopyFirestoreToFirestore(fs, src.path, destCollectionPath, counts, destCollectionPath);
 }
-async function mongoReplacePage(col, docs) {
-    const bulk = docs.map((d) => {
-        const payload = { ...d.data() };
-        delete payload._id;
-        return {
-            replaceOne: {
-                filter: { _id: d.id },
-                replacement: { _id: d.id, ...payload },
-                upsert: true,
-            },
-        };
-    });
-    if (bulk.length)
-        await col.bulkWrite(bulk);
-}
-async function paginatedCopyFirestoreToMongo(fs, sourceCollectionPath, db, destCollectionName, counts, countKey) {
-    const src = fs.collection(sourceCollectionPath);
-    const col = db.collection(destCollectionName);
-    let last;
-    let total = 0;
-    while (true) {
-        let q = src.orderBy(FieldPath.documentId()).limit(200);
-        if (last)
-            q = q.startAfter(last);
-        const snap = await q.get();
-        if (snap.empty)
-            break;
-        await mongoReplacePage(col, snap.docs);
-        total += snap.docs.length;
-        last = snap.docs[snap.docs.length - 1];
-    }
-    counts[countKey] = (counts[countKey] ?? 0) + total;
-}
-async function promoteMongoLatest(db, tmpName, latestName) {
-    const n = await db.collection(tmpName).countDocuments();
-    if (n === 0) {
-        await db.collection(latestName).drop().catch(() => undefined);
-        return;
-    }
-    await db.collection(latestName).drop().catch(() => undefined);
-    await db.collection(tmpName).rename(latestName, { dropTarget: true });
-}
-async function backupMetadataMongo(fs, db, ts, counts, collectionsWritten, versionedWritten, issues) {
-    for (const name of BACKUP_METADATA_SOURCE_NAMES) {
-        const tmp = mongoTmpName(name);
-        const versioned = mongoVersionedName(ts, name);
-        try {
-            await db.collection(tmp).drop().catch(() => undefined);
-            await paginatedCopyFirestoreToMongo(fs, name, db, tmp, counts, tmp);
-            await db.collection(versioned).drop().catch(() => undefined);
-            await paginatedCopyFirestoreToMongo(fs, name, db, versioned, counts, versioned);
-            await promoteMongoLatest(db, tmp, name);
-            collectionsWritten.push(name);
-            versionedWritten.push(versioned);
-        }
-        catch (e) {
-            issues.push({
-                code: "mongo_metadata_copy_failed",
-                message: e instanceof Error ? e.message : String(e),
-                detail: { name },
-            });
-            throw e;
-        }
-    }
-}
-async function backupMetadataFirebase(fs, ts, counts, collectionsWritten, versionedWritten, issues) {
-    for (const name of BACKUP_METADATA_SOURCE_NAMES) {
-        const tmp = firebaseTmpName(name);
-        const latest = firebaseLatestName(name);
-        const ver = firebaseVersionedName(ts, name);
-        try {
-            await deleteAllDocsInFirestoreCollection(fs, tmp);
-            await paginatedCopyFirestoreToFirestore(fs, name, tmp, counts, tmp);
-            await paginatedCopyFirestoreToFirestore(fs, name, ver, counts, ver);
-            await deleteAllDocsInFirestoreCollection(fs, latest);
-            await paginatedCopyFirestoreToFirestore(fs, tmp, latest, counts, latest);
-            await deleteAllDocsInFirestoreCollection(fs, tmp);
-            collectionsWritten.push(latest);
-            versionedWritten.push(ver);
-        }
-        catch (e) {
-            issues.push({
-                code: "firebase_metadata_copy_failed",
-                message: e instanceof Error ? e.message : String(e),
-                detail: { name },
-            });
-            throw e;
-        }
-    }
-}
-async function backupSnapshotsFirebase(fs, ts, counts, collectionsWritten, versionedWritten, issues) {
-    const roots = await fs.collection("catalogSnapshots").listDocuments();
-    for (const pref of roots) {
-        const catalogId = pref.id;
-        const logical = firebaseSnapshotLogical(catalogId);
-        const itemsPath = pref.collection("items").path;
-        const tmp = firebaseTmpName(logical);
-        const latest = firebaseLatestName(logical);
-        const ver = firebaseVersionedName(ts, logical);
-        try {
-            await deleteAllDocsInFirestoreCollection(fs, tmp);
-            await paginatedCopyFirestoreToFirestore(fs, itemsPath, tmp, counts, tmp);
-            await paginatedCopyFirestoreToFirestore(fs, itemsPath, ver, counts, ver);
-            await deleteAllDocsInFirestoreCollection(fs, latest);
-            await paginatedCopyFirestoreToFirestore(fs, tmp, latest, counts, latest);
-            await deleteAllDocsInFirestoreCollection(fs, tmp);
-            collectionsWritten.push(latest);
-            versionedWritten.push(ver);
-            const runs = await pref.collection("runs").listDocuments();
-            for (const runRef of runs) {
-                const runId = runRef.id;
-                const runLogical = firebaseSnapshotRunLogical(catalogId, runId);
-                const runItemsPath = runRef.collection("items").path;
-                const rtmp = firebaseTmpName(runLogical);
-                const rlatest = firebaseLatestName(runLogical);
-                const rver = firebaseVersionedName(ts, runLogical);
-                await deleteAllDocsInFirestoreCollection(fs, rtmp);
-                await paginatedCopyFirestoreToFirestore(fs, runItemsPath, rtmp, counts, rtmp);
-                await paginatedCopyFirestoreToFirestore(fs, runItemsPath, rver, counts, rver);
-                await deleteAllDocsInFirestoreCollection(fs, rlatest);
-                await paginatedCopyFirestoreToFirestore(fs, rtmp, rlatest, counts, rlatest);
-                await deleteAllDocsInFirestoreCollection(fs, rtmp);
-                collectionsWritten.push(rlatest);
-                versionedWritten.push(rver);
-            }
-        }
-        catch (e) {
-            issues.push({
-                code: "firebase_snapshot_copy_failed",
-                message: e instanceof Error ? e.message : String(e),
-                detail: { catalogId },
-            });
-            throw e;
-        }
-    }
-}
-async function backupSnapshotsMongo(fs, db, ts, counts, collectionsWritten, versionedWritten, issues) {
-    const roots = await fs.collection("catalogSnapshots").listDocuments();
-    for (const pref of roots) {
-        const catalogId = pref.id;
-        const itemsPath = pref.collection("items").path;
-        const latestName = mongoSnapshotCollectionName(catalogId);
-        const versionedName = mongoVersionedName(ts, latestName);
-        const tmpName = mongoTmpName(latestName);
-        try {
-            await db.collection(tmpName).drop().catch(() => undefined);
-            await paginatedCopyFirestoreToMongo(fs, itemsPath, db, tmpName, counts, tmpName);
-            await db.collection(versionedName).drop().catch(() => undefined);
-            await paginatedCopyFirestoreToMongo(fs, itemsPath, db, versionedName, counts, versionedName);
-            await promoteMongoLatest(db, tmpName, latestName);
-            collectionsWritten.push(latestName);
-            versionedWritten.push(versionedName);
-            const runs = await pref.collection("runs").listDocuments();
-            for (const runRef of runs) {
-                const runId = runRef.id;
-                const runItemsPath = runRef.collection("items").path;
-                const runLatest = mongoSnapshotRunCollectionName(catalogId, runId);
-                const runVer = mongoVersionedName(ts, runLatest);
-                const runTmp = mongoTmpName(runLatest);
-                await db.collection(runTmp).drop().catch(() => undefined);
-                await paginatedCopyFirestoreToMongo(fs, runItemsPath, db, runTmp, counts, runTmp);
-                await db.collection(runVer).drop().catch(() => undefined);
-                await paginatedCopyFirestoreToMongo(fs, runItemsPath, db, runVer, counts, runVer);
-                await promoteMongoLatest(db, runTmp, runLatest);
-                collectionsWritten.push(runLatest);
-                versionedWritten.push(runVer);
-            }
-        }
-        catch (e) {
-            issues.push({
-                code: "mongo_snapshot_copy_failed",
-                message: e instanceof Error ? e.message : String(e),
-                detail: { catalogId },
-            });
-            throw e;
-        }
-    }
-}
-async function writeBackupManifestFirebase(fs, payload) {
-    await fs.collection("backup-backupRuns").add({
-        ...payload,
-        createdAt: new Date().toISOString(),
-    });
-}
-async function writeBackupManifestMongo(db, payload) {
-    await db.collection("backupRuns").insertOne({
-        ...payload,
-        createdAt: new Date().toISOString(),
-    });
-}
-/** Delete Mongo `backupRuns` documents with createdAt older than cutoff ISO string. */
-export async function pruneMongoBackupRuns(db, createdBeforeIso) {
-    const res = await db.collection("backupRuns").deleteMany({
-        createdAt: { $lt: createdBeforeIso },
-    });
-    return res.deletedCount ?? 0;
-}
 /**
  * Delete documents in oldest Firestore versioned backup collections matching `{ts}__backup-*`
  * until at most `keepLast` such collections remain.
  */
 const require = createRequire(import.meta.url);
+let warnedDefaultBucket = false;
+function warnMissingCataloxBucketEnv(feature) {
+    if (warnedDefaultBucket)
+        return;
+    warnedDefaultBucket = true;
+    try {
+        const { createLogxer } = require("@x12i/logxer");
+        const log = createLogxer({ packageName: "CATALOX", envPrefix: "CATALOX", debugNamespace: "catalox" });
+        log.warn(`${feature}: CATALOX_BUCKET is not set; defaulting to bucket "catalox". ` +
+            `Set CATALOX_BUCKET to an existing bucket to avoid unexpected writes or bucket-create failures.`);
+    }
+    catch {
+        // If logxer can't initialize for any reason, do not crash the caller for a warning.
+    }
+}
 function normalizeBackupGcsBasePrefix(prefix) {
     const p = (prefix ?? "").trim();
     if (!p)
@@ -347,6 +147,41 @@ export function gcsBackupRunFolder(ts, gcsPrefix) {
     return `${base.replace(/\/+$/, "")}${base ? "/" : ""}${ts}`.replace(/\/+$/, "");
 }
 export const CATALOX_GCS_BACKUP_MANIFEST_FILENAME = "catalox-backup-manifest.json";
+function resolveGoogleCredentialsForStorage() {
+    // Prefer base64 carrier used in this repo.
+    const b64 = String(process.env.GOOGLE_SERVICE_ACCOUNT_BASE64 ?? "").trim();
+    if (b64) {
+        const json = Buffer.from(b64, "base64").toString("utf8");
+        const creds = JSON.parse(json);
+        const pid = String(creds.project_id ?? "").trim();
+        return { credentials: creds, ...(pid ? { projectId: pid } : {}) };
+    }
+    const p = String(process.env.FIREBASE_SERVICE_ACCOUNT_PATH ?? "").trim();
+    if (p) {
+        const json = readFileSync(p, "utf8");
+        const creds = JSON.parse(json);
+        const pid = String(creds.project_id ?? "").trim();
+        return { credentials: creds, ...(pid ? { projectId: pid } : {}) };
+    }
+    return {};
+}
+async function ensureGcsBucketExists(bucketName) {
+    // This uses @google-cloud/storage directly because @x12i/helpers/gcs does not create buckets.
+    // Requires permissions: storage.buckets.get + storage.buckets.create (if missing).
+    const { Storage } = require("@google-cloud/storage");
+    const auth = resolveGoogleCredentialsForStorage();
+    const storage = auth.credentials != null
+        ? new Storage({ credentials: auth.credentials, ...(auth.projectId ? { projectId: auth.projectId } : {}) })
+        : new Storage();
+    const b = storage.bucket(bucketName);
+    const [exists] = await b.exists();
+    if (exists)
+        return;
+    await storage.createBucket(bucketName);
+}
+export function defaultCataloxBucketName() {
+    return "catalox";
+}
 function createHelpersGcsClient(bucket, prefixWithoutTrailingSlash) {
     const { createGcsClient } = require("@x12i/helpers/gcs");
     return createGcsClient({
@@ -512,23 +347,36 @@ async function runBackupDataGcs(deps, input, nativeCatalogIds) {
     const fs = deps.firestoreStore.firestore;
     const ts = formatBackupTimestamp(input.versionTimestamp);
     const includeSnapshots = Boolean(input.includeSnapshots);
-    const bucket = input.gcsBucket?.trim() ?? "";
-    if (!bucket) {
+    const envBucket = typeof process !== "undefined" ? String(process.env.CATALOX_BUCKET ?? "").trim() : "";
+    const rawBucket = input.gcsBucket?.trim() || envBucket || defaultCataloxBucketName();
+    if (!input.gcsBucket?.trim() && !envBucket)
+        warnMissingCataloxBucketEnv("backupData(gcs)");
+    const bucket = rawBucket.trim();
+    const runFolder = gcsBackupRunFolder(ts, input.gcsPrefix);
+    try {
+        await ensureGcsBucketExists(bucket);
+    }
+    catch (e) {
         return {
             ok: false,
             mode: "gcs",
-            databaseName: "",
+            databaseName: `gs://${bucket}/`,
             backupTimestamp: new Date().toISOString(),
             ...(input.backupLabel != null ? { backupLabel: input.backupLabel } : {}),
             includeSnapshots,
             collectionsWritten: [],
             versionedCollectionsWritten: [],
             counts: {},
-            issues: [{ code: "missing_gcs_bucket", message: "gcsBucket is required when mode === \"gcs\"" }],
+            issues: [
+                {
+                    code: "gcs_bucket_ensure_failed",
+                    message: e instanceof Error ? e.message : String(e),
+                    detail: { bucket },
+                },
+            ],
             nativeItemSourceLayoutByCatalogId: {},
         };
     }
-    const runFolder = gcsBackupRunFolder(ts, input.gcsPrefix);
     const gcs = createHelpersGcsClient(bucket, runFolder);
     try {
         versionedCollectionsWritten.push(runFolder);
@@ -605,22 +453,6 @@ async function runBackupDataGcs(deps, input, nativeCatalogIds) {
         };
     }
 }
-export async function pruneFirebaseVersionedBackups(firestore, keepLast) {
-    const cols = await firestore.listCollections();
-    const versioned = cols
-        .map((c) => c.id)
-        .filter((id) => /^\d{4}_\d{2}_\d{2}T.*__backup-/.test(id))
-        .sort();
-    if (versioned.length <= keepLast)
-        return { deleted: [] };
-    const toRemove = versioned.slice(0, versioned.length - keepLast);
-    const deleted = [];
-    for (const id of toRemove) {
-        await deleteAllDocsInFirestoreCollection(firestore, id);
-        deleted.push(id);
-    }
-    return { deleted };
-}
 export async function runBackupData(deps, input) {
     const issues = [];
     const collectionsWritten = [];
@@ -636,185 +468,6 @@ export async function runBackupData(deps, input) {
         ...(input.catalogIds != null && input.catalogIds.length ? { catalogIds: input.catalogIds } : {}),
         ...(input.appId != null && input.appId !== "" ? { appId: input.appId } : {}),
     });
-    if (input.mode === "mongo") {
-        if (!input.mongoBackupUri?.trim()) {
-            return {
-                ok: false,
-                mode: "mongo",
-                databaseName: MONGO_BACKUP_DB,
-                backupTimestamp: new Date().toISOString(),
-                ...(input.backupLabel != null ? { backupLabel: input.backupLabel } : {}),
-                includeSnapshots,
-                collectionsWritten: [],
-                versionedCollectionsWritten: [],
-                counts: {},
-                issues: [{ code: "missing_mongo_uri", message: "mongoBackupUri is required for mongo mode" }],
-                nativeItemSourceLayoutByCatalogId: {},
-            };
-        }
-        const client = new MongoClient(input.mongoBackupUri);
-        try {
-            await client.connect();
-            const db = client.db(MONGO_BACKUP_DB);
-            await backupMetadataMongo(fs, db, ts, counts, collectionsWritten, versionedCollectionsWritten, issues);
-            for (const catalogId of nativeCatalogIds) {
-                const layout = await resolveNativeItemsLayout(fs, catalogId);
-                nativeItemSourceLayoutByCatalogId[String(catalogId)] = layout;
-                const logical = mongoNativeItemsCollectionName(String(catalogId));
-                const tmp = mongoTmpName(logical);
-                const versioned = mongoVersionedName(ts, logical);
-                await db.collection(tmp).drop().catch(() => undefined);
-                await copyNativeCatalogToMongo(fs, db, catalogId, tmp, counts, layout);
-                await db.collection(versioned).drop().catch(() => undefined);
-                await copyNativeCatalogToMongo(fs, db, catalogId, versioned, counts, layout);
-                await promoteMongoLatest(db, tmp, logical);
-                collectionsWritten.push(logical);
-                versionedCollectionsWritten.push(versioned);
-            }
-            if (includeSnapshots) {
-                await backupSnapshotsMongo(fs, db, ts, counts, collectionsWritten, versionedCollectionsWritten, issues);
-            }
-            await writeBackupManifestMongo(db, {
-                backupTimestamp: new Date().toISOString(),
-                mode: "mongo",
-                backupLabel: input.backupLabel,
-                includeSnapshots,
-                collectionsWritten,
-                versionedCollectionsWritten,
-                counts,
-                issues,
-                nativeItemSourceLayoutByCatalogId,
-            });
-            return {
-                ok: true,
-                mode: "mongo",
-                databaseName: MONGO_BACKUP_DB,
-                backupTimestamp: new Date().toISOString(),
-                ...(input.backupLabel != null ? { backupLabel: input.backupLabel } : {}),
-                includeSnapshots,
-                collectionsWritten,
-                versionedCollectionsWritten,
-                counts,
-                issues,
-                nativeItemSourceLayoutByCatalogId,
-            };
-        }
-        catch (e) {
-            issues.push({
-                code: "mongo_backup_failed",
-                message: e instanceof Error ? e.message : String(e),
-            });
-            return {
-                ok: false,
-                mode: "mongo",
-                databaseName: MONGO_BACKUP_DB,
-                backupTimestamp: new Date().toISOString(),
-                ...(input.backupLabel != null ? { backupLabel: input.backupLabel } : {}),
-                includeSnapshots,
-                collectionsWritten,
-                versionedCollectionsWritten,
-                counts,
-                issues,
-                nativeItemSourceLayoutByCatalogId,
-            };
-        }
-        finally {
-            await client.close().catch(() => undefined);
-        }
-    }
-    if (input.mode === "gcs") {
-        return await runBackupDataGcs(deps, input, nativeCatalogIds);
-    }
-    if (input.mode !== "firebase") {
-        return {
-            ok: false,
-            mode: input.mode,
-            databaseName: "",
-            backupTimestamp: new Date().toISOString(),
-            ...(input.backupLabel != null ? { backupLabel: input.backupLabel } : {}),
-            includeSnapshots,
-            collectionsWritten: [],
-            versionedCollectionsWritten: [],
-            counts: {},
-            issues: [
-                {
-                    code: "unknown_backup_mode",
-                    message: `Unsupported backup mode: ${String(input.mode)}`,
-                },
-            ],
-            nativeItemSourceLayoutByCatalogId: {},
-        };
-    }
-    try {
-        await backupMetadataFirebase(fs, ts, counts, collectionsWritten, versionedCollectionsWritten, issues);
-        for (const catalogId of nativeCatalogIds) {
-            const layout = await resolveNativeItemsLayout(fs, catalogId);
-            nativeItemSourceLayoutByCatalogId[String(catalogId)] = layout;
-            const logical = firebaseNativeLogical(String(catalogId));
-            const tmp = firebaseTmpName(logical);
-            const latest = firebaseLatestName(logical);
-            const ver = firebaseVersionedName(ts, logical);
-            await deleteAllDocsInFirestoreCollection(fs, tmp);
-            await copyNativeCatalogToFirestoreBackup(fs, catalogId, tmp, counts, layout);
-            await copyNativeCatalogToFirestoreBackup(fs, catalogId, ver, counts, layout);
-            await deleteAllDocsInFirestoreCollection(fs, latest);
-            await paginatedCopyFirestoreToFirestore(fs, tmp, latest, counts, latest);
-            await deleteAllDocsInFirestoreCollection(fs, tmp);
-            collectionsWritten.push(latest);
-            versionedCollectionsWritten.push(ver);
-        }
-        if (includeSnapshots) {
-            await backupSnapshotsFirebase(fs, ts, counts, collectionsWritten, versionedCollectionsWritten, issues);
-        }
-        await writeBackupManifestFirebase(fs, {
-            backupTimestamp: new Date().toISOString(),
-            mode: "firebase",
-            backupLabel: input.backupLabel,
-            includeSnapshots,
-            collectionsWritten,
-            versionedCollectionsWritten,
-            counts,
-            issues,
-            nativeItemSourceLayoutByCatalogId,
-        });
-        return {
-            ok: true,
-            mode: "firebase",
-            databaseName: "(same-firestore-target)",
-            backupTimestamp: new Date().toISOString(),
-            ...(input.backupLabel != null ? { backupLabel: input.backupLabel } : {}),
-            includeSnapshots,
-            collectionsWritten,
-            versionedCollectionsWritten,
-            counts,
-            issues,
-            nativeItemSourceLayoutByCatalogId,
-        };
-    }
-    catch (e) {
-        issues.push({
-            code: "firebase_backup_failed",
-            message: e instanceof Error ? e.message : String(e),
-        });
-        return {
-            ok: false,
-            mode: "firebase",
-            databaseName: "(same-firestore-target)",
-            backupTimestamp: new Date().toISOString(),
-            ...(input.backupLabel != null ? { backupLabel: input.backupLabel } : {}),
-            includeSnapshots,
-            collectionsWritten,
-            versionedCollectionsWritten,
-            counts,
-            issues,
-            nativeItemSourceLayoutByCatalogId,
-        };
-    }
-}
-async function copyNativeCatalogToMongo(fs, db, catalogId, destCollection, counts, layout) {
-    const src = layout === "legacy"
-        ? legacyNativeItemsCollectionRef(fs, catalogId)
-        : flatNativeItemsCollectionRef(fs, catalogId);
-    await paginatedCopyFirestoreToMongo(fs, src.path, db, destCollection, counts, destCollection);
+    return await runBackupDataGcs(deps, input, nativeCatalogIds);
 }
 //# sourceMappingURL=backup-data.js.map