@fazetitans/fscopy 1.3.1 → 1.5.0

package/README.md

@@ -389,6 +389,7 @@ fscopy --init config.json
 | `--max-depth`              |       | number  | `0`                  | Max subcollection depth (0 = unlimited) |
 | `--detect-conflicts`       |       | boolean | `false`              | Detect concurrent modifications         |
 | `--verify-integrity`       |       | boolean | `false`              | Verify document integrity with hash     |
+| `--allow-http-webhook`     |       | boolean | `false`              | Allow HTTP (non-HTTPS) webhook URLs     |
 
 ## How It Works
 
@@ -402,7 +403,9 @@ fscopy --init config.json
 
 - **Transform files execute arbitrary code** - The `--transform` option uses dynamic imports to load and execute JavaScript/TypeScript files. Only use transform files you have written or thoroughly reviewed. Malicious transform files could access your filesystem, network, or credentials.
 
-- **Webhook URLs should use HTTPS** - fscopy warns if you use HTTP webhooks (except localhost). Webhook payloads contain project names and transfer statistics that could be sensitive.
+- **Webhook URLs must use HTTPS** - fscopy blocks HTTP webhooks by default (except localhost). Use `--allow-http-webhook` to explicitly allow unencrypted webhooks. Webhook payloads contain project names and transfer statistics that could be sensitive.
+
+- **Transform file extensions are validated** - Only `.ts`, `.js`, `.mjs`, and `.mts` files are accepted as transform files.
 
 - **Credentials via ADC** - fscopy uses Google Application Default Credentials. Ensure you're authenticated with the correct account before running transfers.
 
@@ -416,8 +419,16 @@ fscopy --init config.json
 - **Clear is destructive** - `--clear` deletes all destination docs before transfer
 - **Delete-missing syncs** - `--delete-missing` removes orphan docs after transfer
 - **Transform applies to all** - Transform function is applied to both root and subcollection docs
+- **Limit applies to root only** - `--limit` restricts the number of documents at the root collection level; subcollections are always copied in full
 - **Same project allowed** - Source and destination can be the same project when using `--rename-collection` or `--id-prefix`/`--id-suffix`
 
+## Environment Variables
+
+| Variable | Description |
+| -------- | ----------- |
+| `GOOGLE_APPLICATION_CREDENTIALS` | Path to Google Cloud credentials JSON file |
+| `FSCOPY_SKIP_CREDENTIALS_CHECK` | Set to `1` to skip the credentials check at startup (useful in CI/CD with alternative auth) |
+
 ## Limitations
 
 ### Firestore Special Types

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fazetitans/fscopy",
-    "version": "1.3.1",
+    "version": "1.5.0",
     "description": "Fast CLI tool to copy Firestore collections between Firebase projects with filtering, parallel transfers, and subcollection support",
     "type": "module",
     "bin": {
@@ -9,15 +9,18 @@
     "scripts": {
         "start": "bun src/cli.ts",
         "dev": "bun --watch src/cli.ts",
-        "test": "bun test",
+        "test": "bun test src/__tests__/*.test.ts",
+        "test:integration": "firebase emulators:exec --only firestore --project fscopy-test 'FIRESTORE_EMULATOR_HOST=127.0.0.1:8080 FSCOPY_SKIP_CREDENTIALS_CHECK=1 bun test src/__tests__/integration/'",
+        "test:all": "bun run test && bun run test:integration",
         "test:watch": "bun test --watch",
-        "test:coverage": "bun test --coverage",
+        "test:coverage": "bun test --coverage src/__tests__/*.test.ts",
+        "emulator": "firebase emulators:start --only firestore --project fscopy-test",
         "type-check": "tsc --noEmit",
         "lint": "eslint src/**/*.ts --no-warn-ignored",
         "lint:fix": "eslint src/**/*.ts --no-warn-ignored --fix",
         "format": "prettier --write src/**/*.ts",
         "format:check": "prettier --check src/**/*.ts",
-        "prepublishOnly": "bun run type-check && bun run lint && bun test"
+        "prepublishOnly": "bun run type-check && bun run lint && bun run test"
     },
     "keywords": [
         "firestore",
@@ -54,24 +57,25 @@
         "LICENSE"
     ],
     "dependencies": {
-        "@inquirer/prompts": "^8.1.0",
+        "@inquirer/prompts": "^8.3.0",
         "cli-progress": "^3.12.0",
-        "firebase-admin": "^13.6.0",
+        "firebase-admin": "^13.7.0",
         "ini": "^6.0.0",
-        "yargs": "^17.7.2"
+        "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@eslint/js": "^9.39.2",
+        "@eslint/js": "^10.0.1",
         "@types/cli-progress": "^3.11.6",
         "@types/ini": "^4.1.1",
-        "@types/node": "^25.0.3",
+        "@types/node": "^25.3.5",
         "@types/yargs": "^17.0.35",
-        "@typescript-eslint/eslint-plugin": "^8.51.0",
-        "@typescript-eslint/parser": "^8.51.0",
-        "bun-types": "^1.3.5",
-        "eslint": "^9.39.2",
-        "prettier": "^3.7.4",
+        "@typescript-eslint/eslint-plugin": "^8.56.1",
+        "@typescript-eslint/parser": "^8.56.1",
+        "bun-types": "^1.3.10",
+        "eslint": "^10.0.2",
+        "prettier": "^3.8.1",
         "typescript": "^5.9.3",
-        "typescript-eslint": "^8.51.0"
+        "firebase-tools": "^15.9.0",
+        "typescript-eslint": "^8.56.1"
     }
 }

package/src/cli.ts

@@ -61,7 +61,7 @@ const argv = yargs(hideBin(process.argv))
     .option('limit', {
         alias: 'l',
         type: 'number',
-        description: 'Limit number of documents per collection (0 = no limit)',
+        description: 'Limit number of documents per root collection (0 = no limit, does not apply to subcollections)',
     })
     .option('source-project', {
         type: 'string',
@@ -89,7 +89,6 @@ const argv = yargs(hideBin(process.argv))
     .option('retries', {
         type: 'number',
         description: 'Number of retries on error (default: 3)',
-        default: 3,
     })
     .option('quiet', {
         alias: 'q',
@@ -166,17 +165,14 @@ const argv = yargs(hideBin(process.argv))
     .option('verify', {
         type: 'boolean',
         description: 'Verify document counts after transfer',
-        default: false,
     })
     .option('rate-limit', {
         type: 'number',
         description: 'Limit transfer rate (documents per second, 0 = unlimited)',
-        default: 0,
     })
     .option('skip-oversized', {
         type: 'boolean',
         description: 'Skip documents exceeding 1MB instead of failing',
-        default: false,
     })
     .option('json', {
         type: 'boolean',
@@ -191,16 +187,18 @@ const argv = yargs(hideBin(process.argv))
     .option('detect-conflicts', {
         type: 'boolean',
         description: 'Detect if destination docs were modified during transfer',
-        default: false,
     })
     .option('max-depth', {
         type: 'number',
         description: 'Max subcollection depth (0 = unlimited)',
-        default: 0,
     })
     .option('verify-integrity', {
         type: 'boolean',
         description: 'Verify document integrity with hash after transfer',
+    })
+    .option('allow-http-webhook', {
+        type: 'boolean',
+        description: 'Allow webhook URLs using HTTP instead of HTTPS',
         default: false,
     })
     .option('validate-only', {
@@ -250,7 +248,11 @@ async function main(): Promise<void> {
 
     // Run interactive mode if enabled
     if (argv.interactive) {
-        config = await runInteractiveMode(config);
+        const result = await runInteractiveMode(config);
+        config = result.config;
+        if (result.action === 'save') {
+            process.exit(0);
+        }
     }
 
     displayConfig(config);
@@ -272,7 +274,10 @@ async function main(): Promise<void> {
 
     // Validate webhook URL if configured
     if (validConfig.webhook) {
-        const webhookValidation = validateWebhookUrl(validConfig.webhook);
+        const webhookValidation = validateWebhookUrl(
+            validConfig.webhook,
+            validConfig.allowHttpWebhook
+        );
         if (!webhookValidation.valid) {
             console.log(`\n❌ ${webhookValidation.warning}`);
             process.exit(1);

package/src/config/defaults.ts

@@ -30,6 +30,7 @@ export const defaults: Config = {
     detectConflicts: false,
     maxDepth: 0,
     verifyIntegrity: false,
+    allowHttpWebhook: false,
 };
 
 export const iniTemplate = `; fscopy configuration file

package/src/config/parser.ts

@@ -3,9 +3,18 @@ import path from 'node:path';
 import ini from 'ini';
 import type { Config, WhereFilter, CliArgs } from '../types.js';
 
+const SUPPORTED_EXTENSIONS = new Set(['.ini', '.json', '.cfg', '.conf']);
+
+function stderrWarn(message: string): void {
+    process.stderr.write(`${message}\n`);
+}
+
 export function getFileFormat(filePath: string): 'json' | 'ini' {
     const ext = path.extname(filePath).toLowerCase();
     if (ext === '.json') return 'json';
+    if (ext && !SUPPORTED_EXTENSIONS.has(ext)) {
+        stderrWarn(`⚠️  Unrecognized config file extension "${ext}", parsing as INI format`);
+    }
     return 'ini';
 }
 
@@ -22,7 +31,7 @@ export function parseWhereFilter(filterStr: string): WhereFilter | null {
     const match = new RegExp(operatorRegex).exec(filterStr);
 
     if (!match) {
-        console.warn(`⚠️  Invalid where filter: "${filterStr}" (missing operator)`);
+        stderrWarn(`⚠️  Invalid where filter: "${filterStr}" (missing operator)`);
         return null;
     }
 
@@ -30,20 +39,20 @@ export function parseWhereFilter(filterStr: string): WhereFilter | null {
     const [fieldPart, valuePart] = filterStr.split(operatorRegex).filter((_, i) => i !== 1);
 
     if (!fieldPart || !valuePart) {
-        console.warn(`⚠️  Invalid where filter: "${filterStr}" (missing field or value)`);
+        stderrWarn(`⚠️  Invalid where filter: "${filterStr}" (missing field or value)`);
         return null;
     }
 
     const field = fieldPart.trim();
     const rawValue = valuePart.trim();
 
-    let value: string | number | boolean;
+    let value: string | number | boolean | null;
     if (rawValue === 'true') {
         value = true;
     } else if (rawValue === 'false') {
         value = false;
     } else if (rawValue === 'null') {
-        value = null as unknown as string;
+        value = null;
     } else if (!Number.isNaN(Number(rawValue)) && rawValue !== '') {
         value = Number(rawValue);
     } else {
@@ -66,6 +75,12 @@ export function parseStringList(value: string | undefined): string[] {
         .filter((s) => s.length > 0);
 }
 
+export function parseIntOption(value: string | undefined): number | undefined {
+    if (value === undefined || value === '') return undefined;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isNaN(parsed) ? undefined : parsed;
+}
+
 export function parseRenameMapping(
     mappings: string[] | string | undefined
 ): Record<string, string> {
@@ -78,13 +93,13 @@ export function parseRenameMapping(
         const mapping = String(item).trim();
         const colonIndex = mapping.indexOf(':');
         if (colonIndex === -1) {
-            console.warn(`⚠️  Invalid rename mapping: "${mapping}" (missing ':')`);
+            stderrWarn(`⚠️  Invalid rename mapping: "${mapping}" (missing ':')`);
             continue;
         }
         const source = mapping.slice(0, colonIndex).trim();
         const dest = mapping.slice(colonIndex + 1).trim();
         if (!source || !dest) {
-            console.warn(`⚠️  Invalid rename mapping: "${mapping}" (empty source or dest)`);
+            stderrWarn(`⚠️  Invalid rename mapping: "${mapping}" (empty source or dest)`);
             continue;
         }
         result[source] = dest;
@@ -115,6 +130,13 @@ export function parseIniConfig(content: string): Partial<Config> {
             idPrefix?: string;
             idSuffix?: string;
             webhook?: string;
+            retries?: string;
+            rateLimit?: string;
+            skipOversized?: string | boolean;
+            detectConflicts?: string | boolean;
+            maxDepth?: string;
+            verify?: string | boolean;
+            verifyIntegrity?: string | boolean;
         };
     };
 
@@ -149,6 +171,23 @@ export function parseIniConfig(content: string): Partial<Config> {
         idPrefix: parsed.options?.idPrefix ?? null,
         idSuffix: parsed.options?.idSuffix ?? null,
         webhook: parsed.options?.webhook ?? null,
+        retries: parseIntOption(parsed.options?.retries),
+        rateLimit: parseIntOption(parsed.options?.rateLimit),
+        skipOversized:
+            parsed.options?.skipOversized !== undefined
+                ? parseBoolean(parsed.options.skipOversized)
+                : undefined,
+        detectConflicts:
+            parsed.options?.detectConflicts !== undefined
+                ? parseBoolean(parsed.options.detectConflicts)
+                : undefined,
+        maxDepth: parseIntOption(parsed.options?.maxDepth),
+        verify:
+            parsed.options?.verify !== undefined ? parseBoolean(parsed.options.verify) : undefined,
+        verifyIntegrity:
+            parsed.options?.verifyIntegrity !== undefined
+                ? parseBoolean(parsed.options.verifyIntegrity)
+                : undefined,
     };
 }
 
@@ -172,6 +211,13 @@ export function parseJsonConfig(content: string): Partial<Config> {
         idPrefix?: string;
         idSuffix?: string;
         webhook?: string;
+        retries?: number;
+        rateLimit?: number;
+        skipOversized?: boolean;
+        detectConflicts?: boolean;
+        maxDepth?: number;
+        verify?: boolean;
+        verifyIntegrity?: boolean;
     };
 
     return {
@@ -193,6 +239,13 @@ export function parseJsonConfig(content: string): Partial<Config> {
         idPrefix: config.idPrefix ?? null,
         idSuffix: config.idSuffix ?? null,
         webhook: config.webhook ?? null,
+        retries: config.retries,
+        rateLimit: config.rateLimit,
+        skipOversized: config.skipOversized,
+        detectConflicts: config.detectConflicts,
+        maxDepth: config.maxDepth,
+        verify: config.verify,
+        verifyIntegrity: config.verifyIntegrity,
     };
 }
 
@@ -207,11 +260,23 @@ export function loadConfigFile(configPath?: string): Partial<Config> {
     const content = fs.readFileSync(absolutePath, 'utf-8');
     const format = getFileFormat(absolutePath);
 
-    console.log(`📄 Loaded config from: ${absolutePath} (${format.toUpperCase()})\n`);
+    process.stderr.write(`📄 Loaded config from: ${absolutePath} (${format.toUpperCase()})\n`);
 
     return format === 'json' ? parseJsonConfig(content) : parseIniConfig(content);
 }
 
+/**
+ * Resolve a config value with priority: CLI > file > default.
+ */
+function resolve<K extends keyof Config>(
+    key: K,
+    cliArgs: Partial<Record<K, Config[K]>>,
+    fileConfig: Partial<Config>,
+    defaultConfig: Config
+): Config[K] {
+    return (cliArgs[key] ?? fileConfig[key] ?? defaultConfig[key]) as Config[K];
+}
+
 export function mergeConfig(
     defaultConfig: Config,
     fileConfig: Partial<Config>,
@@ -220,46 +285,52 @@ export function mergeConfig(
     const cliWhereFilters = parseWhereFilters(cliArgs.where);
     const cliRenameCollection = parseRenameMapping(cliArgs.renameCollection);
 
-    return {
-        collections: cliArgs.collections ?? fileConfig.collections ?? defaultConfig.collections,
-        includeSubcollections:
-            cliArgs.includeSubcollections ??
-            fileConfig.includeSubcollections ??
-            defaultConfig.includeSubcollections,
-        dryRun: cliArgs.dryRun ?? fileConfig.dryRun ?? defaultConfig.dryRun,
-        batchSize: cliArgs.batchSize ?? fileConfig.batchSize ?? defaultConfig.batchSize,
-        limit: cliArgs.limit ?? fileConfig.limit ?? defaultConfig.limit,
-        sourceProject:
-            cliArgs.sourceProject ?? fileConfig.sourceProject ?? defaultConfig.sourceProject,
-        destProject: cliArgs.destProject ?? fileConfig.destProject ?? defaultConfig.destProject,
-        retries: cliArgs.retries ?? defaultConfig.retries,
-        where:
-            cliWhereFilters.length > 0
-                ? cliWhereFilters
-                : (fileConfig.where ?? defaultConfig.where),
-        exclude: cliArgs.exclude ?? fileConfig.exclude ?? defaultConfig.exclude,
-        merge: cliArgs.merge ?? fileConfig.merge ?? defaultConfig.merge,
-        parallel: cliArgs.parallel ?? fileConfig.parallel ?? defaultConfig.parallel,
-        clear: cliArgs.clear ?? fileConfig.clear ?? defaultConfig.clear,
-        deleteMissing:
-            cliArgs.deleteMissing ?? fileConfig.deleteMissing ?? defaultConfig.deleteMissing,
-        transform: cliArgs.transform ?? fileConfig.transform ?? defaultConfig.transform,
-        renameCollection:
-            Object.keys(cliRenameCollection).length > 0
-                ? cliRenameCollection
-                : (fileConfig.renameCollection ?? defaultConfig.renameCollection),
-        idPrefix: cliArgs.idPrefix ?? fileConfig.idPrefix ?? defaultConfig.idPrefix,
-        idSuffix: cliArgs.idSuffix ?? fileConfig.idSuffix ?? defaultConfig.idSuffix,
-        webhook: cliArgs.webhook ?? fileConfig.webhook ?? defaultConfig.webhook,
-        resume: cliArgs.resume ?? defaultConfig.resume,
-        stateFile: cliArgs.stateFile ?? defaultConfig.stateFile,
-        verify: cliArgs.verify ?? defaultConfig.verify,
-        rateLimit: cliArgs.rateLimit ?? defaultConfig.rateLimit,
-        skipOversized: cliArgs.skipOversized ?? defaultConfig.skipOversized,
-        json: cliArgs.json ?? defaultConfig.json,
-        transformSamples: cliArgs.transformSamples ?? defaultConfig.transformSamples,
-        detectConflicts: cliArgs.detectConflicts ?? defaultConfig.detectConflicts,
-        maxDepth: cliArgs.maxDepth ?? defaultConfig.maxDepth,
-        verifyIntegrity: cliArgs.verifyIntegrity ?? defaultConfig.verifyIntegrity,
-    };
+    // Keys that follow standard CLI > file > default priority
+    const standardKeys = [
+        'collections',
+        'includeSubcollections',
+        'dryRun',
+        'batchSize',
+        'limit',
+        'sourceProject',
+        'destProject',
+        'exclude',
+        'merge',
+        'parallel',
+        'clear',
+        'deleteMissing',
+        'transform',
+        'idPrefix',
+        'idSuffix',
+        'webhook',
+        'retries',
+        'verify',
+        'rateLimit',
+        'skipOversized',
+        'detectConflicts',
+        'maxDepth',
+        'verifyIntegrity',
+    ] as const;
+
+    const merged = {} as Record<string, unknown>;
+    for (const key of standardKeys) {
+        merged[key] = resolve(key, cliArgs, fileConfig, defaultConfig);
+    }
+
+    // Special cases: where/rename have non-trivial merge logic
+    merged.where =
+        cliWhereFilters.length > 0 ? cliWhereFilters : (fileConfig.where ?? defaultConfig.where);
+    merged.renameCollection =
+        Object.keys(cliRenameCollection).length > 0
+            ? cliRenameCollection
+            : (fileConfig.renameCollection ?? defaultConfig.renameCollection);
+
+    // CLI-only options (no file config support)
+    merged.resume = cliArgs.resume ?? defaultConfig.resume;
+    merged.stateFile = cliArgs.stateFile ?? defaultConfig.stateFile;
+    merged.json = cliArgs.json ?? defaultConfig.json;
+    merged.transformSamples = cliArgs.transformSamples ?? defaultConfig.transformSamples;
+    merged.allowHttpWebhook = cliArgs.allowHttpWebhook ?? defaultConfig.allowHttpWebhook;
+
+    return merged as unknown as Config;
 }

package/src/config/validator.ts

@@ -1,4 +1,5 @@
 import type { Config, ValidatedConfig } from '../types.js';
+import { MAX_BATCH_SIZE, MAX_PARALLEL, MAX_DEPTH, MAX_RETRIES } from '../constants.js';
 
 /**
  * Validate a Firestore collection or document ID.
@@ -77,6 +78,56 @@ export function validateConfig(config: Config): string[] {
         errors.push(...pathErrors);
     }
 
+    // Validate rename mapping names as valid Firestore IDs
+    for (const [source, dest] of Object.entries(config.renameCollection)) {
+        const sourceError = validateFirestoreId(source, 'collection');
+        if (sourceError) {
+            errors.push(`Invalid rename source "${source}": ${sourceError}`);
+        }
+        const destError = validateFirestoreId(dest, 'collection');
+        if (destError) {
+            errors.push(`Invalid rename destination "${dest}": ${destError}`);
+        }
+    }
+
+    // Validate numeric bounds
+    if (config.batchSize < 1 || config.batchSize > MAX_BATCH_SIZE) {
+        errors.push(`Batch size must be between 1 and ${MAX_BATCH_SIZE} (Firestore limit)`);
+    }
+    if (config.parallel < 1 || config.parallel > MAX_PARALLEL) {
+        errors.push(`Parallel must be between 1 and ${MAX_PARALLEL}`);
+    }
+    if (config.rateLimit < 0) {
+        errors.push('Rate limit must be 0 (unlimited) or a positive number');
+    }
+    if (config.maxDepth < 0 || config.maxDepth > MAX_DEPTH) {
+        errors.push(`Max depth must be between 0 (unlimited) and ${MAX_DEPTH}`);
+    }
+    if (config.retries < 0 || config.retries > MAX_RETRIES) {
+        errors.push(`Retries must be between 0 and ${MAX_RETRIES}`);
+    }
+    if (config.limit < 0) {
+        errors.push('Document limit must be 0 (no limit) or a positive number');
+    }
+
+    // Validate rename mapping for collisions (multiple sources mapping to same dest)
+    const renameDestinations = Object.values(config.renameCollection);
+    const seenDests = new Set<string>();
+    for (const dest of renameDestinations) {
+        if (seenDests.has(dest)) {
+            errors.push(`Rename collision: multiple collections map to destination "${dest}"`);
+        }
+        seenDests.add(dest);
+    }
+
+    // Validate idPrefix/idSuffix format
+    if (config.idPrefix !== null && config.idPrefix.includes('/')) {
+        errors.push('ID prefix cannot contain "/" (would create invalid document paths)');
+    }
+    if (config.idSuffix !== null && config.idSuffix.includes('/')) {
+        errors.push('ID suffix cannot contain "/" (would create invalid document paths)');
+    }
+
     return errors;
 }
 

package/src/constants.ts

@@ -28,3 +28,42 @@ export const STATE_SAVE_INTERVAL_MS = 5000;
 
 /** Default number of batches between state saves */
 export const STATE_SAVE_BATCH_INTERVAL = 10;
+
+// =============================================================================
+// Validation Limits
+// =============================================================================
+
+/** Maximum Firestore batch size */
+export const MAX_BATCH_SIZE = 500;
+
+/** Maximum parallel transfers */
+export const MAX_PARALLEL = 20;
+
+/** Maximum subcollection recursion depth */
+export const MAX_DEPTH = 100;
+
+/** Maximum retry attempts */
+export const MAX_RETRIES = 10;
+
+// =============================================================================
+// Webhook Constants
+// =============================================================================
+
+/** Webhook request timeout in milliseconds */
+export const WEBHOOK_TIMEOUT_MS = 30_000;
+
+/** Maximum webhook payload size in bytes (Discord limit) */
+export const WEBHOOK_MAX_PAYLOAD_BYTES = 2_000_000;
+
+/** Maximum webhook retry attempts */
+export const WEBHOOK_MAX_RETRIES = 2;
+
+/** Webhook retry base delay in milliseconds */
+export const WEBHOOK_RETRY_DELAY_MS = 1_000;
+
+// =============================================================================
+// Clear Collection Constants
+// =============================================================================
+
+/** Page size for paginated collection clearing */
+export const CLEAR_PAGE_SIZE = 500;

package/src/firebase/index.ts

@@ -12,22 +12,21 @@ export interface FirebaseConnections {
     destDb: Firestore;
 }
 
+function getAppOptions(projectId: string): admin.AppOptions {
+    const isEmulator = !!process.env.FIRESTORE_EMULATOR_HOST;
+    return {
+        projectId,
+        ...(isEmulator ? {} : { credential: admin.credential.applicationDefault() }),
+    };
+}
+
 export function initializeFirebase(config: Config): FirebaseConnections {
-    sourceApp = admin.initializeApp(
-        {
-            credential: admin.credential.applicationDefault(),
-            projectId: config.sourceProject!,
-        },
-        'source'
-    );
+    if (sourceApp || destApp) {
+        throw new Error('Firebase already initialized. Call cleanupFirebase() first.');
+    }
 
-    destApp = admin.initializeApp(
-        {
-            credential: admin.credential.applicationDefault(),
-            projectId: config.destProject!,
-        },
-        'dest'
-    );
+    sourceApp = admin.initializeApp(getAppOptions(config.sourceProject!), 'source');
+    destApp = admin.initializeApp(getAppOptions(config.destProject!), 'dest');
 
     return {
         sourceDb: sourceApp.firestore(),
@@ -52,7 +51,8 @@ export async function checkDatabaseConnectivity(
         const errorInfo = formatFirebaseError(err);
         const hint = errorInfo.suggestion ? `\n   Hint: ${errorInfo.suggestion}` : '';
         throw new Error(
-            `Cannot connect to source database (${config.sourceProject}): ${errorInfo.message}${hint}`
+            `Cannot connect to source database (${config.sourceProject}): ${errorInfo.message}${hint}`,
+            { cause: error }
         );
     }
 
@@ -66,7 +66,8 @@ export async function checkDatabaseConnectivity(
             const errorInfo = formatFirebaseError(err);
             const hint = errorInfo.suggestion ? `\n   Hint: ${errorInfo.suggestion}` : '';
             throw new Error(
-                `Cannot connect to destination database (${config.destProject}): ${errorInfo.message}${hint}`
+                `Cannot connect to destination database (${config.destProject}): ${errorInfo.message}${hint}`,
+                { cause: error }
             );
         }
     } else {
@@ -77,6 +78,16 @@ export async function checkDatabaseConnectivity(
 }
 
 export async function cleanupFirebase(): Promise<void> {
-    if (sourceApp) await sourceApp.delete();
-    if (destApp) await destApp.delete();
+    try {
+        if (sourceApp) await sourceApp.delete();
+    } catch {
+        // Ignore cleanup errors - app may already be deleted
+    }
+    try {
+        if (destApp) await destApp.delete();
+    } catch {
+        // Ignore cleanup errors - app may already be deleted
+    }
+    sourceApp = null;
+    destApp = null;
 }