@fazetitans/fscopy 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fazetitans/fscopy",
-    "version": "1.2.1",
+    "version": "1.3.0",
     "description": "Fast CLI tool to copy Firestore collections between Firebase projects with filtering, parallel transfers, and subcollection support",
     "type": "module",
     "bin": {
@@ -11,9 +11,10 @@
         "dev": "bun --watch src/cli.ts",
         "test": "bun test",
         "test:watch": "bun test --watch",
+        "test:coverage": "bun test --coverage",
         "type-check": "tsc --noEmit",
-        "lint": "eslint src/**/*.ts --ignore-pattern 'src/__tests__/**' --no-warn-ignored",
-        "lint:fix": "eslint src/**/*.ts --ignore-pattern 'src/__tests__/**' --no-warn-ignored --fix",
+        "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"
@@ -43,7 +44,8 @@
         "url": "https://github.com/FaZeTitans/fscopy/issues"
     },
     "engines": {
-        "node": ">=18.0.0"
+        "node": ">=18.0.0",
+        "bun": ">=1.0.0"
     },
     "files": [
         "src/**/*.ts",

package/src/cli.ts

@@ -7,11 +7,11 @@ import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 
 import pkg from '../package.json';
-import type { Config, CliArgs } from './types.js';
+import type { Config, CliArgs, ValidatedConfig } from './types.js';
 import { Output, parseSize } from './utils/output.js';
 import { ensureCredentials } from './utils/credentials.js';
 import { loadConfigFile, mergeConfig } from './config/parser.js';
-import { validateConfig } from './config/validator.js';
+import { validateConfig, isValidatedConfig } from './config/validator.js';
 import { defaults } from './config/defaults.js';
 import { generateConfigFile } from './config/generator.js';
 import { validateWebhookUrl } from './webhook/index.js';
@@ -267,9 +267,16 @@ async function main(): Promise<void> {
         process.exit(1);
     }
 
+    // After validation, config is guaranteed to have required fields
+    if (!isValidatedConfig(config)) {
+        console.log('\n❌ Configuration validation failed');
+        process.exit(1);
+    }
+    const validConfig: ValidatedConfig = config;
+
     // Validate webhook URL if configured
-    if (config.webhook) {
-        const webhookValidation = validateWebhookUrl(config.webhook);
+    if (validConfig.webhook) {
+        const webhookValidation = validateWebhookUrl(validConfig.webhook);
         if (!webhookValidation.valid) {
             console.log(`\n❌ ${webhookValidation.warning}`);
             process.exit(1);
@@ -287,7 +294,7 @@ async function main(): Promise<void> {
 
     // Skip confirmation in interactive mode (already confirmed by selection)
     if (!argv.yes && !argv.interactive) {
-        const confirmed = await askConfirmation(config);
+        const confirmed = await askConfirmation(validConfig);
         if (!confirmed) {
             console.log('\n🚫 Transfer cancelled by user\n');
             process.exit(0);
@@ -302,10 +309,10 @@ async function main(): Promise<void> {
         maxLogSize: parseSize(argv.maxLogSize),
     });
     output.init();
-    output.logInfo('Transfer started', { config: config as unknown as Record<string, unknown> });
+    output.logInfo('Transfer started', { config: validConfig as unknown as Record<string, unknown> });
 
     // Run transfer
-    const result = await runTransfer(config, argv, output);
+    const result = await runTransfer(validConfig, argv, output);
 
     if (!result.success) {
         process.exit(1);

package/src/config/index.ts

@@ -11,5 +11,5 @@ export {
     loadConfigFile,
     mergeConfig,
 } from './parser.js';
-export { validateConfig } from './validator.js';
+export { validateConfig, isValidatedConfig, assertValidConfig } from './validator.js';
 export { generateConfigFile } from './generator.js';

package/src/config/validator.ts

@@ -1,4 +1,4 @@
-import type { Config } from '../types.js';
+import type { Config, ValidatedConfig } from '../types.js';
 
 /**
  * Validate a Firestore collection or document ID.
@@ -79,3 +79,29 @@ export function validateConfig(config: Config): string[] {
 
     return errors;
 }
+
+/**
+ * Type guard to check if a Config has been validated.
+ * Returns true if sourceProject and destProject are non-null strings.
+ */
+export function isValidatedConfig(config: Config): config is ValidatedConfig {
+    return (
+        typeof config.sourceProject === 'string' &&
+        typeof config.destProject === 'string' &&
+        config.collections.length > 0
+    );
+}
+
+/**
+ * Validates config and returns ValidatedConfig if valid, throws otherwise.
+ */
+export function assertValidConfig(config: Config): ValidatedConfig {
+    const errors = validateConfig(config);
+    if (errors.length > 0) {
+        throw new Error(`Invalid configuration: ${errors.join(', ')}`);
+    }
+    if (!isValidatedConfig(config)) {
+        throw new Error('Configuration validation failed');
+    }
+    return config;
+}

package/src/constants.ts

@@ -0,0 +1,30 @@
+/**
+ * Application-wide constants.
+ * Centralizes magic numbers for better maintainability.
+ */
+
+// =============================================================================
+// Display Constants
+// =============================================================================
+
+/** Width for separator lines and progress line clearing */
+export const SEPARATOR_LENGTH = 60;
+
+// =============================================================================
+// Timing Constants
+// =============================================================================
+
+/** Interval for logging subcollection/progress updates during scanning (ms) */
+export const PROGRESS_LOG_INTERVAL_MS = 2000;
+
+/** Interval for updating speed display in progress bar (ms) */
+export const SPEED_UPDATE_INTERVAL_MS = 500;
+
+/** Interval for flushing batched progress bar increments (ms) */
+export const PROGRESS_FLUSH_INTERVAL_MS = 50;
+
+/** Default interval for auto-saving transfer state (ms) */
+export const STATE_SAVE_INTERVAL_MS = 5000;
+
+/** Default number of batches between state saves */
+export const STATE_SAVE_BATCH_INTERVAL = 10;

package/src/interactive.ts

@@ -1,6 +1,7 @@
 import admin from 'firebase-admin';
 import type { Firestore } from 'firebase-admin/firestore';
 import { input, checkbox, confirm } from '@inquirer/prompts';
+import { SEPARATOR_LENGTH } from './constants.js';
 import type { Config } from './types.js';
 
 async function promptForProject(
@@ -59,9 +60,9 @@ async function promptForIdModification(
 }
 
 export async function runInteractiveMode(config: Config): Promise<Config> {
-    console.log('\n' + '='.repeat(60));
+    console.log('\n' + '='.repeat(SEPARATOR_LENGTH));
     console.log('🔄 FSCOPY - INTERACTIVE MODE');
-    console.log('='.repeat(60) + '\n');
+    console.log('='.repeat(SEPARATOR_LENGTH) + '\n');
 
     const sourceProject = await promptForProject(config.sourceProject, 'Source Firebase project ID', '📤');
     const destProject = await promptForProject(config.destProject, 'Destination Firebase project ID', '📥');

package/src/orchestrator.ts

@@ -1,12 +1,13 @@
 import type { Firestore } from 'firebase-admin/firestore';
 
-import type { Config, Stats, TransferState, TransformFunction, CliArgs, ConflictInfo } from './types.js';
+import { PROGRESS_LOG_INTERVAL_MS, SEPARATOR_LENGTH } from './constants.js';
+import type { Config, ValidatedConfig, Stats, TransferState, TransformFunction, CliArgs, ConflictInfo } from './types.js';
 import { Output } from './utils/output.js';
 import { RateLimiter } from './utils/rate-limiter.js';
 import { ProgressBarWrapper } from './utils/progress.js';
 import { loadTransferState, saveTransferState, createInitialState, validateStateForResume, deleteTransferState, StateSaver } from './state/index.js';
 import { sendWebhook } from './webhook/index.js';
-import { countDocuments, transferCollection, clearCollection, deleteOrphanDocuments, processInParallel, getDestCollectionPath, type TransferContext, type CountProgress } from './transfer/index.js';
+import { countDocuments, transferCollection, clearCollection, deleteOrphanDocuments, processInParallel, getDestCollectionPath, type TransferContext, type CountProgress, type DeleteOrphansProgress } from './transfer/index.js';
 import { initializeFirebase, checkDatabaseConnectivity, cleanupFirebase } from './firebase/index.js';
 import { loadTransformFunction } from './transform/loader.js';
 import { printSummary, formatJsonOutput } from './output/display.js';
@@ -24,7 +25,7 @@ interface ResumeResult {
     stats: Stats;
 }
 
-function initializeResumeMode(config: Config, output: Output): ResumeResult {
+function initializeResumeMode(config: ValidatedConfig, output: Output): ResumeResult {
     if (config.resume) {
         const existingState = loadTransferState(config.stateFile);
         if (!existingState) {
@@ -68,7 +69,7 @@ async function loadTransform(config: Config, output: Output): Promise<TransformF
 }
 
 async function handleSuccessOutput(
-    config: Config,
+    config: ValidatedConfig,
     argv: CliArgs,
     stats: Stats,
     duration: number,
@@ -83,8 +84,8 @@ async function handleSuccessOutput(
 
     if (config.webhook) {
         await sendWebhook(config.webhook, {
-            source: config.sourceProject!,
-            destination: config.destProject!,
+            source: config.sourceProject,
+            destination: config.destProject,
             collections: config.collections,
             stats,
             duration,
@@ -95,7 +96,7 @@ async function handleSuccessOutput(
 }
 
 async function handleErrorOutput(
-    config: Config,
+    config: ValidatedConfig,
     stats: Stats,
     duration: number,
     errorMessage: string,
@@ -109,8 +110,8 @@ async function handleErrorOutput(
 
     if (config.webhook) {
         await sendWebhook(config.webhook, {
-            source: config.sourceProject ?? 'unknown',
-            destination: config.destProject ?? 'unknown',
+            source: config.sourceProject,
+            destination: config.destProject,
             collections: config.collections,
             stats,
             duration,
@@ -121,7 +122,30 @@ async function handleErrorOutput(
     }
 }
 
-export async function runTransfer(config: Config, argv: CliArgs, output: Output): Promise<TransferResult> {
+function displayTransferOptions(config: Config, rateLimiter: RateLimiter | null, output: Output): void {
+    let hasOptions = false;
+
+    if (rateLimiter) {
+        output.info(`⏱️  Rate limiting enabled: ${config.rateLimit} docs/s`);
+        hasOptions = true;
+    }
+
+    if (config.detectConflicts) {
+        output.info('🔒 Conflict detection enabled: Conflicts will be logged but won\'t stop the transfer');
+        hasOptions = true;
+    }
+
+    if (config.maxDepth > 0 && config.includeSubcollections) {
+        output.info(`📊 Max depth: ${config.maxDepth} - Subcollections beyond this level will be skipped`);
+        hasOptions = true;
+    }
+
+    if (hasOptions) {
+        output.blank();
+    }
+}
+
+export async function runTransfer(config: ValidatedConfig, argv: CliArgs, output: Output): Promise<TransferResult> {
     const startTime = Date.now();
 
     try {
@@ -145,9 +169,7 @@ export async function runTransfer(config: Config, argv: CliArgs, output: Output)
         const { progressBar } = await setupProgressTracking(sourceDb, config, currentStats, output);
 
         const rateLimiter = config.rateLimit > 0 ? new RateLimiter(config.rateLimit) : null;
-        if (rateLimiter) {
-            output.info(`⏱️  Rate limiting enabled: ${config.rateLimit} docs/s\n`);
-        }
+        displayTransferOptions(config, rateLimiter, output);
 
         const stateSaver = transferState ? new StateSaver(config.stateFile, transferState) : null;
 
@@ -264,7 +286,7 @@ async function setupProgressTracking(
             onSubcollection: (_path) => {
                 subcollectionCount++;
                 const now = Date.now();
-                if (now - lastSubcollectionLog > 2000) {
+                if (now - lastSubcollectionLog > PROGRESS_LOG_INTERVAL_MS) {
                     process.stdout.write(`\r   Scanning subcollections... (${subcollectionCount} found)`);
                     lastSubcollectionLog = now;
                 }
@@ -276,7 +298,7 @@ async function setupProgressTracking(
         }
 
         if (subcollectionCount > 0) {
-            process.stdout.write('\r' + ' '.repeat(60) + '\r');
+            process.stdout.write('\r' + ' '.repeat(SEPARATOR_LENGTH) + '\r');
             output.info(`   Subcollections scanned: ${subcollectionCount}`);
         }
         output.info(`   Total: ${totalDocs} documents to transfer\n`);
@@ -350,16 +372,49 @@ async function deleteOrphanDocs(
     output: Output
 ): Promise<void> {
     output.info('\n🔄 Deleting orphan documents (sync mode)...');
+
+    let lastProgressLog = Date.now();
+    let subcollectionCount = 0;
+
+    const progress: DeleteOrphansProgress = {
+        onScanStart: (collection) => {
+            process.stdout.write(`   Scanning ${collection}...`);
+        },
+        onScanComplete: (collection, orphanCount, totalDest) => {
+            process.stdout.write(`\r   ${collection}: ${orphanCount}/${totalDest} orphan docs\n`);
+        },
+        onBatchDeleted: (collection, deletedSoFar, total) => {
+            process.stdout.write(`\r   Deleting from ${collection}... ${deletedSoFar}/${total}`);
+            if (deletedSoFar === total) {
+                process.stdout.write('\n');
+            }
+        },
+        onSubcollectionScan: (_path) => {
+            subcollectionCount++;
+            const now = Date.now();
+            if (now - lastProgressLog > PROGRESS_LOG_INTERVAL_MS) {
+                process.stdout.write(`\r   Scanning subcollections... (${subcollectionCount} checked)`);
+                lastProgressLog = now;
+            }
+        },
+    };
+
     for (const collection of config.collections) {
         const deleted = await deleteOrphanDocuments(
             sourceDb,
             destDb,
             collection,
             config,
-            output
+            output,
+            progress
         );
         stats.documentsDeleted += deleted;
     }
+
+    if (subcollectionCount > 0) {
+        process.stdout.write('\r' + ' '.repeat(SEPARATOR_LENGTH) + '\r');
+    }
+
     if (stats.documentsDeleted > 0) {
         output.info(`   Deleted ${stats.documentsDeleted} orphan documents`);
     } else {

package/src/output/display.ts

@@ -1,4 +1,5 @@
 import readline from 'node:readline';
+import { SEPARATOR_LENGTH } from '../constants.js';
 import type { Config, Stats } from '../types.js';
 
 function formatIdModification(config: Config): string | null {
@@ -113,9 +114,9 @@ function displayAdditionalOptions(config: Config): void {
 }
 
 export function displayConfig(config: Config): void {
-    console.log('='.repeat(60));
+    console.log('='.repeat(SEPARATOR_LENGTH));
     console.log('🔄 FSCOPY - CONFIGURATION');
-    console.log('='.repeat(60));
+    console.log('='.repeat(SEPARATOR_LENGTH));
     console.log('');
     console.log(`  📤 Source project:       ${config.sourceProject || '(not set)'}`);
     console.log(`  📥 Destination project:  ${config.destProject || '(not set)'}`);
@@ -137,7 +138,7 @@ export function displayConfig(config: Config): void {
             : '  ⚡ Mode:                 LIVE (data WILL be transferred)'
     );
     console.log('');
-    console.log('='.repeat(60));
+    console.log('='.repeat(SEPARATOR_LENGTH));
 }
 
 export async function askConfirmation(config: Config): Promise<boolean> {
@@ -162,9 +163,9 @@ export function printSummary(
     dryRun?: boolean,
     verifyIntegrity?: boolean
 ): void {
-    console.log('\n' + '='.repeat(60));
+    console.log('\n' + '='.repeat(SEPARATOR_LENGTH));
     console.log('📊 TRANSFER SUMMARY');
-    console.log('='.repeat(60));
+    console.log('='.repeat(SEPARATOR_LENGTH));
     console.log(`Collections processed: ${stats.collectionsProcessed}`);
     if (stats.documentsDeleted > 0) {
         console.log(`Documents deleted:     ${stats.documentsDeleted}`);
@@ -193,7 +194,7 @@ export function printSummary(
     } else {
         console.log('\n✓ Transfer completed successfully');
     }
-    console.log('='.repeat(60) + '\n');
+    console.log('='.repeat(SEPARATOR_LENGTH) + '\n');
 }
 
 export function formatJsonOutput(

package/src/state/index.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
-import type { Config, TransferState, Stats } from '../types.js';
+import { STATE_SAVE_INTERVAL_MS, STATE_SAVE_BATCH_INTERVAL } from '../constants.js';
+import type { Config, ValidatedConfig, TransferState, Stats } from '../types.js';
 
 export const STATE_VERSION = 1;
 
@@ -81,15 +82,12 @@ export class CompletedDocsCache {
 // =============================================================================
 
 export interface StateSaverOptions {
-    /** Save every N batches (default: 10) */
+    /** Save every N batches (default: STATE_SAVE_BATCH_INTERVAL) */
     batchInterval?: number;
-    /** Save every N milliseconds (default: 5000) */
+    /** Save every N milliseconds (default: STATE_SAVE_INTERVAL_MS) */
     timeInterval?: number;
 }
 
-const DEFAULT_BATCH_INTERVAL = 10;
-const DEFAULT_TIME_INTERVAL = 5000;
-
 /**
  * Throttled state saver with O(1) completed doc lookups.
  * Uses CompletedDocsCache for efficient lookups during transfer.
@@ -108,8 +106,8 @@ export class StateSaver {
         private readonly state: TransferState,
         options: StateSaverOptions = {}
     ) {
-        this.batchInterval = options.batchInterval ?? DEFAULT_BATCH_INTERVAL;
-        this.timeInterval = options.timeInterval ?? DEFAULT_TIME_INTERVAL;
+        this.batchInterval = options.batchInterval ?? STATE_SAVE_BATCH_INTERVAL;
+        this.timeInterval = options.timeInterval ?? STATE_SAVE_INTERVAL_MS;
         this.cache = new CompletedDocsCache(state.completedDocs);
     }
 
@@ -244,11 +242,11 @@ export function deleteTransferState(stateFile: string): void {
     }
 }
 
-export function createInitialState(config: Config): TransferState {
+export function createInitialState(config: ValidatedConfig): TransferState {
     return {
         version: STATE_VERSION,
-        sourceProject: config.sourceProject!,
-        destProject: config.destProject!,
+        sourceProject: config.sourceProject,
+        destProject: config.destProject,
         collections: config.collections,
         startedAt: new Date().toISOString(),
         updatedAt: new Date().toISOString(),

package/src/transfer/clear.ts

@@ -145,13 +145,14 @@ async function deleteOrphanBatch(
     return deletedCount;
 }
 
-async function processSubcollectionOrphans(
+async function processSubcollectionOrphansWithProgress(
     sourceDb: Firestore,
     destDb: Firestore,
     sourceSnapshot: FirebaseFirestore.QuerySnapshot,
     sourceCollectionPath: string,
     config: Config,
-    output: Output
+    output: Output,
+    progress?: DeleteOrphansProgress
 ): Promise<number> {
     let deletedCount = 0;
 
@@ -161,28 +162,48 @@ async function processSubcollectionOrphans(
             if (matchesExcludePattern(subId, config.exclude)) continue;
 
             const subPath = `${sourceCollectionPath}/${sourceDoc.id}/${subId}`;
-            deletedCount += await deleteOrphanDocuments(sourceDb, destDb, subPath, config, output);
+            progress?.onSubcollectionScan?.(subPath);
+            deletedCount += await deleteOrphanDocuments(
+                sourceDb,
+                destDb,
+                subPath,
+                config,
+                output,
+                progress
+            );
         }
     }
 
     return deletedCount;
 }
 
+export interface DeleteOrphansProgress {
+    onScanStart?: (collection: string) => void;
+    onScanComplete?: (collection: string, orphanCount: number, totalDest: number) => void;
+    onBatchDeleted?: (collection: string, deletedSoFar: number, total: number) => void;
+    onSubcollectionScan?: (path: string) => void;
+}
+
 export async function deleteOrphanDocuments(
     sourceDb: Firestore,
     destDb: Firestore,
     sourceCollectionPath: string,
     config: Config,
-    output: Output
+    output: Output,
+    progress?: DeleteOrphansProgress
 ): Promise<number> {
     const destCollectionPath = getDestCollectionPath(sourceCollectionPath, config.renameCollection);
 
+    progress?.onScanStart?.(destCollectionPath);
+
     const sourceSnapshot = await sourceDb.collection(sourceCollectionPath).select().get();
     const sourceIds = new Set(sourceSnapshot.docs.map((doc) => doc.id));
 
     const destSnapshot = await destDb.collection(destCollectionPath).select().get();
     const orphanDocs = destSnapshot.docs.filter((doc) => !sourceIds.has(doc.id));
 
+    progress?.onScanComplete?.(destCollectionPath, orphanDocs.length, destSnapshot.size);
+
     let deletedCount = 0;
 
     if (orphanDocs.length > 0) {
@@ -197,17 +218,19 @@ export async function deleteOrphanDocuments(
                 config,
                 output
             );
+            progress?.onBatchDeleted?.(destCollectionPath, deletedCount, orphanDocs.length);
         }
     }
 
     if (config.includeSubcollections) {
-        deletedCount += await processSubcollectionOrphans(
+        deletedCount += await processSubcollectionOrphansWithProgress(
             sourceDb,
             destDb,
             sourceSnapshot,
             sourceCollectionPath,
             config,
-            output
+            output,
+            progress
         );
     }
 

package/src/transfer/index.ts

@@ -1,5 +1,5 @@
 export { getSubcollections, getDestCollectionPath, getDestDocId } from './helpers.js';
 export { processInParallel, type ParallelResult } from './parallel.js';
 export { countDocuments, type CountProgress } from './count.js';
-export { clearCollection, deleteOrphanDocuments } from './clear.js';
+export { clearCollection, deleteOrphanDocuments, type DeleteOrphansProgress } from './clear.js';
 export { transferCollection, type TransferContext } from './transfer.js';

package/src/transfer/transfer.ts

@@ -186,6 +186,9 @@ function checkDocumentSize(
     );
 }
 
+// Track which collections have already shown the max-depth warning (to avoid spam)
+const maxDepthWarningsShown = new Set<string>();
+
 async function processSubcollections(
     ctx: TransferContext,
     doc: QueryDocumentSnapshot,
@@ -196,6 +199,15 @@ async function processSubcollections(
 
     // Check max depth limit (0 = unlimited)
     if (config.maxDepth > 0 && depth >= config.maxDepth) {
+        // Show console warning only once per root collection
+        const rootCollection = collectionPath.split('/')[0];
+        if (!maxDepthWarningsShown.has(rootCollection)) {
+            maxDepthWarningsShown.add(rootCollection);
+            output.warn(
+                `⚠️  Subcollections in ${rootCollection} beyond depth ${config.maxDepth} will be skipped`
+            );
+        }
+
         output.logInfo(`Skipping subcollections at depth ${depth} (max: ${config.maxDepth})`, {
             collection: collectionPath,
             docId: doc.id,

package/src/types.ts

@@ -40,6 +40,12 @@ export interface Config {
     verifyIntegrity: boolean;
 }
 
+// Config after validation - required fields are guaranteed non-null
+export interface ValidatedConfig extends Omit<Config, 'sourceProject' | 'destProject'> {
+    sourceProject: string;
+    destProject: string;
+}
+
 export interface ConflictInfo {
     collection: string;
     docId: string;

package/src/utils/doc-size.ts

@@ -1,3 +1,10 @@
+import {
+    isTimestamp,
+    isGeoPoint,
+    isDocumentReference,
+    getDocumentReferencePath,
+} from './firestore-types.js';
+
 /**
  * Firestore maximum document size in bytes (1 MiB)
  */
@@ -31,24 +38,11 @@ export function estimateDocumentSize(data: Record<string, unknown>, docPath?: st
     return size;
 }
 
-function isFirestoreTimestamp(value: object): boolean {
-    return '_seconds' in value && '_nanoseconds' in value;
-}
-
-function isGeoPoint(value: object): boolean {
-    return '_latitude' in value && '_longitude' in value;
-}
-
-function isDocumentReference(value: object): boolean {
-    return '_path' in value && typeof (value as { _path: unknown })._path === 'object';
-}
-
-function getDocRefSize(value: object): number {
-    const pathObj = (value as { _path: { segments?: string[] } })._path;
-    if (pathObj.segments) {
-        return pathObj.segments.join('/').length + 1;
+function getDocRefSize(value: unknown): number {
+    if (isDocumentReference(value)) {
+        return getDocumentReferencePath(value).length + 1;
     }
-    return 16; // Approximate
+    return 16; // Approximate for unknown reference format
 }
 
 function estimateArraySize(arr: unknown[]): number {
@@ -76,7 +70,7 @@ function estimateValueSize(value: unknown): number {
     if (value instanceof Date) return 8;
 
     if (typeof value === 'object') {
-        if (isFirestoreTimestamp(value)) return 8;
+        if (isTimestamp(value)) return 8;
         if (isGeoPoint(value)) return 16;
         if (isDocumentReference(value)) return getDocRefSize(value);
         if (Array.isArray(value)) return estimateArraySize(value);

package/src/utils/file-rotation.ts

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Rotate a file if it exceeds maxSize.
+ * Creates numbered backups: file.1.ext, file.2.ext, etc.
+ *
+ * @param filePath - Path to the file to rotate
+ * @param maxSize - Maximum file size in bytes (0 = no rotation)
+ * @param maxFiles - Maximum number of rotated files to keep (default: 5)
+ * @returns true if rotation occurred, false otherwise
+ */
+export function rotateFileIfNeeded(
+    filePath: string,
+    maxSize: number,
+    maxFiles: number = 5
+): boolean {
+    if (!filePath || maxSize <= 0) return false;
+    if (!fs.existsSync(filePath)) return false;
+
+    const stats = fs.statSync(filePath);
+    if (stats.size < maxSize) return false;
+
+    const dir = path.dirname(filePath);
+    const ext = path.extname(filePath);
+    const base = path.basename(filePath, ext);
+
+    // Delete oldest backup if at max
+    const oldestPath = path.join(dir, `${base}.${maxFiles}${ext}`);
+    if (fs.existsSync(oldestPath)) {
+        fs.unlinkSync(oldestPath);
+    }
+
+    // Shift existing backups: .4 -> .5, .3 -> .4, etc.
+    for (let i = maxFiles - 1; i >= 1; i--) {
+        const from = path.join(dir, `${base}.${i}${ext}`);
+        const to = path.join(dir, `${base}.${i + 1}${ext}`);
+        if (fs.existsSync(from)) {
+            fs.renameSync(from, to);
+        }
+    }
+
+    // Rename current to .1
+    const backupPath = path.join(dir, `${base}.1${ext}`);
+    fs.renameSync(filePath, backupPath);
+
+    return true;
+}

package/src/utils/firestore-types.ts

@@ -0,0 +1,82 @@
+/**
+ * Type guards for Firestore special types.
+ *
+ * Firestore SDK exposes these types with public properties:
+ * - Timestamp: { seconds: number, nanoseconds: number, toDate(), toMillis() }
+ * - GeoPoint: { latitude: number, longitude: number, isEqual() }
+ * - DocumentReference: { path: string, id: string, parent, ... }
+ *
+ * Note: Internal properties like _seconds, _path may exist but are not guaranteed.
+ * We use public API properties for reliability.
+ */
+
+export interface FirestoreTimestamp {
+    seconds: number;
+    nanoseconds: number;
+    toDate?: () => Date;
+    toMillis?: () => number;
+}
+
+export interface FirestoreGeoPoint {
+    latitude: number;
+    longitude: number;
+    isEqual?: (other: unknown) => boolean;
+}
+
+export interface FirestoreDocumentReference {
+    path: string;
+    id: string;
+}
+
+/**
+ * Check if value is a Firestore Timestamp.
+ * Works with both SDK instances and plain objects with same shape.
+ */
+export function isTimestamp(value: unknown): value is FirestoreTimestamp {
+    return (
+        typeof value === 'object' &&
+        value !== null &&
+        'seconds' in value &&
+        'nanoseconds' in value &&
+        typeof (value as FirestoreTimestamp).seconds === 'number' &&
+        typeof (value as FirestoreTimestamp).nanoseconds === 'number'
+    );
+}
+
+/**
+ * Check if value is a Firestore GeoPoint.
+ * Excludes Timestamps which also have numeric properties.
+ */
+export function isGeoPoint(value: unknown): value is FirestoreGeoPoint {
+    return (
+        typeof value === 'object' &&
+        value !== null &&
+        'latitude' in value &&
+        'longitude' in value &&
+        typeof (value as FirestoreGeoPoint).latitude === 'number' &&
+        typeof (value as FirestoreGeoPoint).longitude === 'number' &&
+        !('seconds' in value) // Distinguish from Timestamp
+    );
+}
+
+/**
+ * Check if value is a Firestore DocumentReference.
+ */
+export function isDocumentReference(value: unknown): value is FirestoreDocumentReference {
+    return (
+        typeof value === 'object' &&
+        value !== null &&
+        'path' in value &&
+        'id' in value &&
+        typeof (value as FirestoreDocumentReference).path === 'string' &&
+        typeof (value as FirestoreDocumentReference).id === 'string'
+    );
+}
+
+/**
+ * Get the path from a DocumentReference.
+ * Handles both SDK instances and plain objects.
+ */
+export function getDocumentReferencePath(ref: FirestoreDocumentReference): string {
+    return ref.path;
+}

package/src/utils/integrity.ts

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { isTimestamp, isGeoPoint, isDocumentReference } from './firestore-types.js';
 
 /**
  * Compute a SHA-256 hash of document data.
@@ -28,17 +29,17 @@ function serializeForHash(value: unknown): string {
     }
 
     // Handle Firestore Timestamp
-    if (isFirestoreTimestamp(value)) {
+    if (isTimestamp(value)) {
         return JSON.stringify({ _seconds: value.seconds, _nanoseconds: value.nanoseconds });
     }
 
     // Handle Firestore GeoPoint
-    if (isFirestoreGeoPoint(value)) {
+    if (isGeoPoint(value)) {
         return JSON.stringify({ _latitude: value.latitude, _longitude: value.longitude });
     }
 
     // Handle Firestore DocumentReference
-    if (isFirestoreDocumentReference(value)) {
+    if (isDocumentReference(value)) {
         return JSON.stringify({ _path: value.path });
     }
 
@@ -68,55 +69,3 @@ function serializeForHash(value: unknown): string {
 export function compareHashes(sourceHash: string, destHash: string): boolean {
     return sourceHash === destHash;
 }
-
-// Type guards for Firestore types
-
-interface FirestoreTimestamp {
-    seconds: number;
-    nanoseconds: number;
-    toDate?: () => Date;
-}
-
-interface FirestoreGeoPoint {
-    latitude: number;
-    longitude: number;
-}
-
-interface FirestoreDocumentReference {
-    path: string;
-    id: string;
-}
-
-function isFirestoreTimestamp(value: unknown): value is FirestoreTimestamp {
-    return (
-        typeof value === 'object' &&
-        value !== null &&
-        'seconds' in value &&
-        'nanoseconds' in value &&
-        typeof (value as FirestoreTimestamp).seconds === 'number' &&
-        typeof (value as FirestoreTimestamp).nanoseconds === 'number'
-    );
-}
-
-function isFirestoreGeoPoint(value: unknown): value is FirestoreGeoPoint {
-    return (
-        typeof value === 'object' &&
-        value !== null &&
-        'latitude' in value &&
-        'longitude' in value &&
-        typeof (value as FirestoreGeoPoint).latitude === 'number' &&
-        typeof (value as FirestoreGeoPoint).longitude === 'number' &&
-        !('seconds' in value)
-    );
-}
-
-function isFirestoreDocumentReference(value: unknown): value is FirestoreDocumentReference {
-    return (
-        typeof value === 'object' &&
-        value !== null &&
-        'path' in value &&
-        'id' in value &&
-        typeof (value as FirestoreDocumentReference).path === 'string' &&
-        typeof (value as FirestoreDocumentReference).id === 'string'
-    );
-}

package/src/utils/logger.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
-import path from 'node:path';
 import type { Stats, LogEntry } from '../types.js';
+import { rotateFileIfNeeded } from './file-rotation.js';
 
 export interface LoggerOptions {
     logPath?: string;
@@ -69,35 +69,9 @@ export class Logger {
      * Creates numbered backups: log.1, log.2, etc.
      */
     private rotateIfNeeded(): void {
-        if (!this.logPath || this.maxSize <= 0) return;
-        if (!fs.existsSync(this.logPath)) return;
-
-        const stats = fs.statSync(this.logPath);
-        if (stats.size < this.maxSize) return;
-
-        // Rotate existing backups
-        const dir = path.dirname(this.logPath);
-        const ext = path.extname(this.logPath);
-        const base = path.basename(this.logPath, ext);
-
-        // Delete oldest if at max
-        const oldestPath = path.join(dir, `${base}.${this.maxFiles}${ext}`);
-        if (fs.existsSync(oldestPath)) {
-            fs.unlinkSync(oldestPath);
-        }
-
-        // Shift existing backups: .4 -> .5, .3 -> .4, etc.
-        for (let i = this.maxFiles - 1; i >= 1; i--) {
-            const from = path.join(dir, `${base}.${i}${ext}`);
-            const to = path.join(dir, `${base}.${i + 1}${ext}`);
-            if (fs.existsSync(from)) {
-                fs.renameSync(from, to);
-            }
+        if (this.logPath) {
+            rotateFileIfNeeded(this.logPath, this.maxSize, this.maxFiles);
         }
-
-        // Rename current to .1
-        const backupPath = path.join(dir, `${base}.1${ext}`);
-        fs.renameSync(this.logPath, backupPath);
     }
 
     summary(stats: Stats, duration: string): void {

package/src/utils/output.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
-import path from 'node:path';
+import { SEPARATOR_LENGTH } from '../constants.js';
 import type { Stats, LogEntry } from '../types.js';
+import { rotateFileIfNeeded } from './file-rotation.js';
 
 /**
  * Parse a size string like "10MB" or "1GB" into bytes.
@@ -72,38 +73,13 @@ export class Output {
      * Creates numbered backups: log.1.ext, log.2.ext, etc.
      */
     private rotateLogIfNeeded(): void {
-        const logFile = this.options.logFile;
-        const maxSize = this.options.maxLogSize ?? 0;
-        const maxFiles = this.options.maxLogFiles ?? 5;
-
-        if (!logFile || maxSize <= 0) return;
-        if (!fs.existsSync(logFile)) return;
-
-        const stats = fs.statSync(logFile);
-        if (stats.size < maxSize) return;
-
-        const dir = path.dirname(logFile);
-        const ext = path.extname(logFile);
-        const base = path.basename(logFile, ext);
-
-        // Delete oldest backup if at max
-        const oldestPath = path.join(dir, `${base}.${maxFiles}${ext}`);
-        if (fs.existsSync(oldestPath)) {
-            fs.unlinkSync(oldestPath);
-        }
-
-        // Shift existing backups: .4 -> .5, .3 -> .4, etc.
-        for (let i = maxFiles - 1; i >= 1; i--) {
-            const from = path.join(dir, `${base}.${i}${ext}`);
-            const to = path.join(dir, `${base}.${i + 1}${ext}`);
-            if (fs.existsSync(from)) {
-                fs.renameSync(from, to);
-            }
+        if (this.options.logFile) {
+            rotateFileIfNeeded(
+                this.options.logFile,
+                this.options.maxLogSize ?? 0,
+                this.options.maxLogFiles ?? 5
+            );
         }
-
-        // Rename current to .1
-        const backupPath = path.join(dir, `${base}.1${ext}`);
-        fs.renameSync(logFile, backupPath);
     }
 
     // ==========================================================================
@@ -156,7 +132,7 @@ export class Output {
     }
 
     /** Print a separator line */
-    separator(char: string = '=', length: number = 60): void {
+    separator(char: string = '=', length: number = SEPARATOR_LENGTH): void {
         if (!this.options.quiet && !this.options.json) {
             console.log(char.repeat(length));
         }
@@ -165,9 +141,9 @@ export class Output {
     /** Print a header with separators */
     header(title: string): void {
         if (!this.options.quiet && !this.options.json) {
-            console.log('='.repeat(60));
+            console.log('='.repeat(SEPARATOR_LENGTH));
             console.log(title);
-            console.log('='.repeat(60));
+            console.log('='.repeat(SEPARATOR_LENGTH));
         }
     }
 

package/src/utils/progress.ts

@@ -1,4 +1,5 @@
 import cliProgress from 'cli-progress';
+import { SPEED_UPDATE_INTERVAL_MS, PROGRESS_FLUSH_INTERVAL_MS } from '../constants.js';
 import type { Stats } from '../types.js';
 
 export interface ProgressBarOptions {
@@ -17,14 +18,18 @@ const DEFAULT_OPTIONS: ProgressBarOptions = {
 
 /**
  * Wrapper around cli-progress that handles speed calculation and cleanup.
- * Eliminates the need for type hacks to store the speed interval.
+ * Thread-safe for parallel mode: uses batched updates to prevent UI flickering.
  */
 export class ProgressBarWrapper {
     private bar: cliProgress.SingleBar | null = null;
     private speedInterval: NodeJS.Timeout | null = null;
+    private flushInterval: NodeJS.Timeout | null = null;
     private lastDocsTransferred = 0;
     private lastTime = Date.now();
 
+    // Batched increment counter for parallel-safe updates
+    private pendingIncrements = 0;
+
     constructor(private readonly options: ProgressBarOptions = {}) {}
 
     /**
@@ -45,21 +50,50 @@ export class ProgressBarWrapper {
         this.bar.start(total, 0, { speed: '0' });
         this.lastDocsTransferred = 0;
         this.lastTime = Date.now();
+        this.pendingIncrements = 0;
 
+        // Speed update interval
         this.speedInterval = setInterval(() => {
             this.updateSpeed(stats);
-        }, 500);
+        }, SPEED_UPDATE_INTERVAL_MS);
+
+        // Batched increment flush interval (for parallel mode)
+        this.flushInterval = setInterval(() => {
+            this.flushIncrements();
+        }, PROGRESS_FLUSH_INTERVAL_MS);
     }
 
     /**
      * Increment the progress bar by 1.
+     * Thread-safe: increments are batched and flushed periodically.
      */
     increment(): void {
         if (this.bar) {
-            this.bar.increment();
+            this.pendingIncrements++;
+        }
+    }
+
+    /**
+     * Increment the progress bar by a specific amount.
+     * Thread-safe: increments are batched and flushed periodically.
+     */
+    incrementBy(count: number): void {
+        if (this.bar && count > 0) {
+            this.pendingIncrements += count;
         }
     }
 
+    /**
+     * Flush pending increments to the progress bar.
+     */
+    private flushIncrements(): void {
+        if (!this.bar || this.pendingIncrements === 0) return;
+
+        const toFlush = this.pendingIncrements;
+        this.pendingIncrements = 0;
+        this.bar.increment(toFlush);
+    }
+
     /**
      * Update the speed display based on current stats.
      */
@@ -80,9 +114,17 @@ export class ProgressBarWrapper {
     }
 
     /**
-     * Stop the progress bar and clean up the speed interval.
+     * Stop the progress bar and clean up intervals.
+     * Flushes any pending increments before stopping.
      */
     stop(): void {
+        // Flush remaining increments
+        this.flushIncrements();
+
+        if (this.flushInterval) {
+            clearInterval(this.flushInterval);
+            this.flushInterval = null;
+        }
         if (this.speedInterval) {
             clearInterval(this.speedInterval);
             this.speedInterval = null;

package/src/webhook/index.ts

@@ -125,22 +125,62 @@ export async function sendWebhook(
     }
 
     try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 30000);
+
         const response = await fetch(webhookUrl, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(body),
+            signal: controller.signal,
         });
 
+        clearTimeout(timeout);
+
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`HTTP ${response.status}: ${errorText}`);
+            const statusCode = response.status;
+
+            if (statusCode >= 400 && statusCode < 500) {
+                // Client error - likely bad URL or payload format
+                output.logError(`Webhook client error (${statusCode})`, {
+                    url: webhookUrl,
+                    status: statusCode,
+                    error: errorText,
+                });
+                output.warn(
+                    `⚠️  Webhook failed (HTTP ${statusCode}): Check webhook URL or payload format`
+                );
+            } else if (statusCode >= 500) {
+                // Server error - retry might help
+                output.logError(`Webhook server error (${statusCode})`, {
+                    url: webhookUrl,
+                    status: statusCode,
+                    error: errorText,
+                });
+                output.warn(
+                    `⚠️  Webhook server error (HTTP ${statusCode}): The webhook service may be temporarily unavailable`
+                );
+            }
+            return;
         }
 
         output.logInfo(`Webhook sent successfully (${webhookType})`, { url: webhookUrl });
         output.info(`📤 Webhook notification sent (${webhookType})`);
     } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        output.logError(`Failed to send webhook: ${message}`, { url: webhookUrl });
-        output.warn(`⚠️  Failed to send webhook: ${message}`);
+        const err = error as Error;
+
+        if (err.name === 'AbortError') {
+            output.logError('Webhook timeout after 30s', { url: webhookUrl });
+            output.warn('⚠️  Webhook request timed out after 30 seconds');
+        } else if (err.message.includes('ECONNREFUSED') || err.message.includes('ENOTFOUND')) {
+            output.logError(`Webhook connection failed: ${err.message}`, { url: webhookUrl });
+            output.warn(
+                `⚠️  Webhook connection failed: Unable to reach ${new URL(webhookUrl).hostname}`
+            );
+        } else {
+            output.logError(`Failed to send webhook: ${err.message}`, { url: webhookUrl });
+            output.warn(`⚠️  Failed to send webhook: ${err.message}`);
+        }
     }
 }