@fazetitans/fscopy 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fazetitans/fscopy",
-    "version": "1.3.0",
+    "version": "1.4.0",
     "description": "Fast CLI tool to copy Firestore collections between Firebase projects with filtering, parallel transfers, and subcollection support",
     "type": "module",
     "bin": {

package/src/cli.ts

@@ -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',
@@ -111,23 +110,19 @@ const argv = yargs(hideBin(process.argv))
         alias: 'm',
         type: 'boolean',
         description: 'Merge documents instead of overwriting',
-        default: false,
     })
     .option('parallel', {
         alias: 'p',
         type: 'number',
         description: 'Number of parallel collection transfers (default: 1)',
-        default: 1,
     })
     .option('clear', {
         type: 'boolean',
         description: 'Clear destination collections before transfer (DESTRUCTIVE)',
-        default: false,
     })
     .option('delete-missing', {
         type: 'boolean',
         description: 'Delete destination docs not present in source (sync mode)',
-        default: false,
     })
     .option('interactive', {
         alias: 'i',
@@ -170,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',
@@ -195,17 +187,14 @@ 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',
-        default: false,
     })
     .option('validate-only', {
         type: 'boolean',
@@ -254,7 +243,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);

package/src/config/parser.ts

@@ -66,6 +66,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> {
@@ -115,6 +121,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 +162,13 @@ 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 +192,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 +220,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,
     };
 }
 
@@ -232,7 +266,6 @@ export function mergeConfig(
         sourceProject:
             cliArgs.sourceProject ?? fileConfig.sourceProject ?? defaultConfig.sourceProject,
         destProject: cliArgs.destProject ?? fileConfig.destProject ?? defaultConfig.destProject,
-        retries: cliArgs.retries ?? defaultConfig.retries,
         where:
             cliWhereFilters.length > 0
                 ? cliWhereFilters
@@ -251,15 +284,16 @@ export function mergeConfig(
         idPrefix: cliArgs.idPrefix ?? fileConfig.idPrefix ?? defaultConfig.idPrefix,
         idSuffix: cliArgs.idSuffix ?? fileConfig.idSuffix ?? defaultConfig.idSuffix,
         webhook: cliArgs.webhook ?? fileConfig.webhook ?? defaultConfig.webhook,
+        retries: cliArgs.retries ?? fileConfig.retries ?? defaultConfig.retries,
         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,
+        verify: cliArgs.verify ?? fileConfig.verify ?? defaultConfig.verify,
+        rateLimit: cliArgs.rateLimit ?? fileConfig.rateLimit ?? defaultConfig.rateLimit,
+        skipOversized: cliArgs.skipOversized ?? fileConfig.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,
+        detectConflicts: cliArgs.detectConflicts ?? fileConfig.detectConflicts ?? defaultConfig.detectConflicts,
+        maxDepth: cliArgs.maxDepth ?? fileConfig.maxDepth ?? defaultConfig.maxDepth,
+        verifyIntegrity: cliArgs.verifyIntegrity ?? fileConfig.verifyIntegrity ?? defaultConfig.verifyIntegrity,
     };
 }

package/src/interactive.ts

@@ -1,8 +1,31 @@
 import admin from 'firebase-admin';
+import fs from 'node:fs';
+import path from 'node:path';
 import type { Firestore } from 'firebase-admin/firestore';
-import { input, checkbox, confirm } from '@inquirer/prompts';
+import { input, checkbox, confirm, select, number } from '@inquirer/prompts';
 import { SEPARATOR_LENGTH } from './constants.js';
-import type { Config } from './types.js';
+import type { Config, WhereFilter } from './types.js';
+import { parseWhereFilter, parseRenameMapping, parseStringList } from './config/parser.js';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface InteractiveResult {
+    config: Config;
+    action: 'execute' | 'save';
+}
+
+type AdvancedOption =
+    | 'exclude' | 'where' | 'parallel' | 'batchSize' | 'limit'
+    | 'maxDepth' | 'rateLimit' | 'clear' | 'deleteMissing' | 'transform'
+    | 'renameCollection' | 'idPrefix' | 'idSuffix' | 'webhook'
+    | 'skipOversized' | 'detectConflicts' | 'verify' | 'verifyIntegrity'
+    | 'retries';
+
+// =============================================================================
+// Project prompts
+// =============================================================================
 
 async function promptForProject(
     currentValue: string | null | undefined,
@@ -23,7 +46,7 @@ async function promptForIdModification(
     currentPrefix: string | null,
     currentSuffix: string | null
 ): Promise<{ idPrefix: string | null; idSuffix: string | null }> {
-    console.log('\n⚠️  Source and destination are the same project.');
+    console.log('\nSource and destination are the same project.');
     console.log('   You need to rename collections or modify document IDs to avoid overwriting.\n');
 
     const modifyIds = await confirm({
@@ -54,30 +77,24 @@ async function promptForIdModification(
         return { idPrefix: currentPrefix, idSuffix };
     }
 
-    console.log('\n❌ Cannot proceed: source and destination are the same without ID modification.');
+    console.log('\nCannot proceed: source and destination are the same without ID modification.');
     console.log('   This would overwrite your data. Use --rename-collection, --id-prefix, or --id-suffix.\n');
     process.exit(1);
 }
 
-export async function runInteractiveMode(config: Config): Promise<Config> {
-    console.log('\n' + '='.repeat(SEPARATOR_LENGTH));
-    console.log('🔄 FSCOPY - INTERACTIVE MODE');
-    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', '📥');
-
-    let idPrefix = config.idPrefix;
-    let idSuffix = config.idSuffix;
+// =============================================================================
+// Collection discovery
+// =============================================================================
 
-    if (sourceProject === destProject) {
-        const mods = await promptForIdModification(idPrefix, idSuffix);
-        idPrefix = mods.idPrefix;
-        idSuffix = mods.idSuffix;
-    }
+interface CollectionInfo {
+    id: string;
+    count: number;
+}
 
-    // Initialize source Firebase to list collections
-    console.log('\n📊 Connecting to source project...');
+async function discoverCollections(
+    sourceProject: string
+): Promise<{ app: admin.app.App; db: Firestore; collections: CollectionInfo[] }> {
+    console.log('\nConnecting to source project...');
 
     let tempSourceApp: admin.app.App;
     let sourceDb: Firestore;
@@ -92,12 +109,10 @@ export async function runInteractiveMode(config: Config): Promise<Config> {
             'interactive-source'
         );
         sourceDb = tempSourceApp.firestore();
-
-        // List collections (also tests connectivity)
         rootCollections = await sourceDb.listCollections();
     } catch (error) {
         const err = error as Error & { code?: string };
-        console.error('\n❌ Cannot connect to Firebase project:', err.message);
+        console.error('\nCannot connect to Firebase project:', err.message);
 
         if (err.message.includes('default credentials') || err.message.includes('credential')) {
             console.error('\n   Run this command to authenticate:');
@@ -114,14 +129,13 @@ export async function runInteractiveMode(config: Config): Promise<Config> {
     const collectionIds = rootCollections.map((col) => col.id);
 
     if (collectionIds.length === 0) {
-        console.log('\n⚠️  No collections found in source project');
+        console.log('\nNo collections found in source project');
         await tempSourceApp.delete();
         process.exit(0);
     }
 
-    // Count documents in each collection for preview
-    console.log('\n📋 Available collections:');
-    const collectionInfo: { id: string; count: number }[] = [];
+    console.log('\nAvailable collections:');
+    const collectionInfo: CollectionInfo[] = [];
     for (const id of collectionIds) {
         const snapshot = await sourceDb.collection(id).count().get();
         const count = snapshot.data().count;
@@ -129,7 +143,462 @@ export async function runInteractiveMode(config: Config): Promise<Config> {
         console.log(`   - ${id} (${count} documents)`);
     }
 
-    // Let user select collections
+    return { app: tempSourceApp, db: sourceDb, collections: collectionInfo };
+}
+
+// =============================================================================
+// Advanced options
+// =============================================================================
+
+const advancedOptionChoices: Array<{ name: string; value: AdvancedOption }> = [
+    { name: 'Exclude subcollection patterns', value: 'exclude' },
+    { name: 'Where filters (filter source documents)', value: 'where' },
+    { name: 'Parallel transfers', value: 'parallel' },
+    { name: 'Batch size', value: 'batchSize' },
+    { name: 'Document limit per collection', value: 'limit' },
+    { name: 'Max subcollection depth', value: 'maxDepth' },
+    { name: 'Rate limit (docs/sec)', value: 'rateLimit' },
+    { name: 'Clear destination before transfer', value: 'clear' },
+    { name: 'Delete missing docs in destination (sync mode)', value: 'deleteMissing' },
+    { name: 'Transform file (JS/TS)', value: 'transform' },
+    { name: 'Rename collections in destination', value: 'renameCollection' },
+    { name: 'ID prefix', value: 'idPrefix' },
+    { name: 'ID suffix', value: 'idSuffix' },
+    { name: 'Webhook URL (Slack, Discord, custom)', value: 'webhook' },
+    { name: 'Skip oversized documents (>1MB)', value: 'skipOversized' },
+    { name: 'Detect conflicts during transfer', value: 'detectConflicts' },
+    { name: 'Verify counts after transfer', value: 'verify' },
+    { name: 'Verify integrity (hash comparison)', value: 'verifyIntegrity' },
+    { name: 'Retries on error', value: 'retries' },
+];
+
+async function promptAdvancedOptions(config: Config): Promise<Partial<Config>> {
+    const wantAdvanced = await confirm({
+        message: 'Configure additional options?',
+        default: false,
+    });
+
+    if (!wantAdvanced) return {};
+
+    console.log('');
+    const selected = new Set(
+        await checkbox<AdvancedOption>({
+            message: 'Select options to configure:',
+            choices: advancedOptionChoices,
+        })
+    );
+
+    if (selected.size === 0) return {};
+
+    console.log('');
+    const updates: Partial<Config> = {};
+
+    if (selected.has('exclude')) {
+        const val = await input({
+            message: 'Exclude patterns (comma-separated, e.g. "logs, cache*, temp"):',
+            default: config.exclude.length > 0 ? config.exclude.join(', ') : undefined,
+        });
+        updates.exclude = parseStringList(val);
+    }
+
+    if (selected.has('where')) {
+        const filters: WhereFilter[] = [];
+        let addMore = true;
+        while (addMore) {
+            const filterStr = await input({
+                message: `Where filter${filters.length > 0 ? ' (leave empty to stop)' : ''} (e.g. "status == active"):`,
+            });
+            if (!filterStr.trim()) break;
+            const parsed = parseWhereFilter(filterStr);
+            if (parsed) {
+                filters.push(parsed);
+                console.log(`   Added: ${parsed.field} ${parsed.operator} ${parsed.value}`);
+            }
+            if (filters.length > 0) {
+                addMore = await confirm({ message: 'Add another filter?', default: false });
+            }
+        }
+        if (filters.length > 0) {
+            updates.where = filters;
+        }
+    }
+
+    if (selected.has('parallel')) {
+        const val = await number({
+            message: 'Number of parallel collection transfers:',
+            default: config.parallel,
+            min: 1,
+            max: 20,
+            step: 1,
+        });
+        if (val !== undefined) updates.parallel = val;
+    }
+
+    if (selected.has('batchSize')) {
+        const val = await number({
+            message: 'Batch size (documents per write):',
+            default: config.batchSize,
+            min: 1,
+            max: 500,
+            step: 1,
+        });
+        if (val !== undefined) updates.batchSize = val;
+    }
+
+    if (selected.has('limit')) {
+        const val = await number({
+            message: 'Document limit per collection (0 = no limit):',
+            default: config.limit,
+            min: 0,
+            step: 1,
+        });
+        if (val !== undefined) updates.limit = val;
+    }
+
+    if (selected.has('maxDepth')) {
+        const val = await number({
+            message: 'Max subcollection depth (0 = unlimited):',
+            default: config.maxDepth,
+            min: 0,
+            step: 1,
+        });
+        if (val !== undefined) updates.maxDepth = val;
+    }
+
+    if (selected.has('rateLimit')) {
+        const val = await number({
+            message: 'Rate limit in docs/sec (0 = unlimited):',
+            default: config.rateLimit,
+            min: 0,
+            step: 1,
+        });
+        if (val !== undefined) updates.rateLimit = val;
+    }
+
+    if (selected.has('clear')) {
+        updates.clear = await confirm({
+            message: 'Clear destination collections before transfer? (DESTRUCTIVE)',
+            default: config.clear,
+        });
+    }
+
+    if (selected.has('deleteMissing')) {
+        updates.deleteMissing = await confirm({
+            message: 'Delete docs in destination not present in source? (sync mode)',
+            default: config.deleteMissing,
+        });
+    }
+
+    if (selected.has('transform')) {
+        const val = await input({
+            message: 'Path to transform file (JS/TS):',
+            default: config.transform ?? undefined,
+            validate: (value) => {
+                if (!value.trim()) return 'Path is required';
+                return true;
+            },
+        });
+        updates.transform = val.trim();
+    }
+
+    if (selected.has('renameCollection')) {
+        const val = await input({
+            message: 'Rename mappings (e.g. "users:users_backup, orders:orders_v2"):',
+            default: Object.entries(config.renameCollection).map(([s, d]) => `${s}:${d}`).join(', ') || undefined,
+        });
+        updates.renameCollection = parseRenameMapping(parseStringList(val));
+    }
+
+    if (selected.has('idPrefix')) {
+        const val = await input({
+            message: 'Document ID prefix:',
+            default: config.idPrefix ?? undefined,
+        });
+        updates.idPrefix = val.trim() || null;
+    }
+
+    if (selected.has('idSuffix')) {
+        const val = await input({
+            message: 'Document ID suffix:',
+            default: config.idSuffix ?? undefined,
+        });
+        updates.idSuffix = val.trim() || null;
+    }
+
+    if (selected.has('webhook')) {
+        const val = await input({
+            message: 'Webhook URL:',
+            default: config.webhook ?? undefined,
+        });
+        updates.webhook = val.trim() || null;
+    }
+
+    if (selected.has('skipOversized')) {
+        updates.skipOversized = await confirm({
+            message: 'Skip documents exceeding 1MB instead of failing?',
+            default: config.skipOversized,
+        });
+    }
+
+    if (selected.has('detectConflicts')) {
+        updates.detectConflicts = await confirm({
+            message: 'Detect destination modifications during transfer?',
+            default: config.detectConflicts,
+        });
+    }
+
+    if (selected.has('verify')) {
+        updates.verify = await confirm({
+            message: 'Verify document counts after transfer?',
+            default: config.verify,
+        });
+    }
+
+    if (selected.has('verifyIntegrity')) {
+        updates.verifyIntegrity = await confirm({
+            message: 'Verify document integrity with hash after transfer?',
+            default: config.verifyIntegrity,
+        });
+    }
+
+    if (selected.has('retries')) {
+        const val = await number({
+            message: 'Number of retries on error:',
+            default: config.retries,
+            min: 0,
+            max: 10,
+            step: 1,
+        });
+        if (val !== undefined) updates.retries = val;
+    }
+
+    return updates;
+}
+
+// =============================================================================
+// Final action
+// =============================================================================
+
+async function promptFinalAction(): Promise<'execute' | 'save-ini' | 'save-json'> {
+    console.log('');
+    return select({
+        message: 'What would you like to do?',
+        choices: [
+            { name: 'Execute transfer', value: 'execute' as const },
+            { name: 'Save as INI config file', value: 'save-ini' as const },
+            { name: 'Save as JSON config file', value: 'save-json' as const },
+        ],
+    });
+}
+
+// =============================================================================
+// Config serialization
+// =============================================================================
+
+function serializeWhereFilters(filters: WhereFilter[]): string[] {
+    return filters.map((f) => `${f.field} ${f.operator} ${f.value}`);
+}
+
+function serializeRenameMapping(mapping: Record<string, string>): string {
+    return Object.entries(mapping)
+        .map(([src, dest]) => `${src}:${dest}`)
+        .join(', ');
+}
+
+function configToJson(config: Config): string {
+    const output: Record<string, unknown> = {
+        sourceProject: config.sourceProject,
+        destProject: config.destProject,
+        collections: config.collections,
+        includeSubcollections: config.includeSubcollections,
+        dryRun: config.dryRun,
+        batchSize: config.batchSize,
+        limit: config.limit,
+        where: serializeWhereFilters(config.where),
+        exclude: config.exclude,
+        merge: config.merge,
+        parallel: config.parallel,
+        clear: config.clear,
+        deleteMissing: config.deleteMissing,
+    };
+
+    // Include optional fields only if set
+    if (config.transform) output.transform = config.transform;
+    if (Object.keys(config.renameCollection).length > 0) output.renameCollection = config.renameCollection;
+    if (config.idPrefix) output.idPrefix = config.idPrefix;
+    if (config.idSuffix) output.idSuffix = config.idSuffix;
+    if (config.webhook) output.webhook = config.webhook;
+    if (config.rateLimit > 0) output.rateLimit = config.rateLimit;
+    if (config.skipOversized) output.skipOversized = config.skipOversized;
+    if (config.detectConflicts) output.detectConflicts = config.detectConflicts;
+    if (config.maxDepth > 0) output.maxDepth = config.maxDepth;
+    if (config.verify) output.verify = config.verify;
+    if (config.verifyIntegrity) output.verifyIntegrity = config.verifyIntegrity;
+    if (config.retries !== 3) output.retries = config.retries;
+
+    return JSON.stringify(output, null, 4);
+}
+
+function iniLine(key: string, value: string | number | boolean): string {
+    return `${key} = ${value}\n`;
+}
+
+function iniComment(key: string, value: string | number | boolean): string {
+    return `; ${key} = ${value}\n`;
+}
+
+function configToIni(config: Config): string {
+    let ini = '; fscopy configuration file\n';
+    ini += '; Generated by interactive mode\n\n';
+
+    // [projects]
+    ini += '[projects]\n';
+    ini += iniLine('source', config.sourceProject ?? '');
+    ini += iniLine('dest', config.destProject ?? '');
+    ini += '\n';
+
+    // [transfer]
+    ini += '[transfer]\n';
+    ini += iniLine('collections', config.collections.join(', '));
+    ini += iniLine('includeSubcollections', config.includeSubcollections);
+    ini += iniLine('dryRun', config.dryRun);
+    ini += iniLine('batchSize', config.batchSize);
+    ini += iniLine('limit', config.limit);
+    ini += '\n';
+
+    // [options]
+    ini += '[options]\n';
+
+    if (config.where.length > 0) {
+        ini += iniLine('where', serializeWhereFilters(config.where).join(', '));
+    } else {
+        ini += iniComment('where', 'status == active');
+    }
+
+    if (config.exclude.length > 0) {
+        ini += iniLine('exclude', config.exclude.join(', '));
+    } else {
+        ini += iniComment('exclude', 'logs, temp/*, cache');
+    }
+
+    ini += iniLine('merge', config.merge);
+    ini += iniLine('parallel', config.parallel);
+    ini += iniLine('clear', config.clear);
+    ini += iniLine('deleteMissing', config.deleteMissing);
+
+    if (config.transform) {
+        ini += iniLine('transform', config.transform);
+    } else {
+        ini += iniComment('transform', './transforms/anonymize.ts');
+    }
+
+    if (Object.keys(config.renameCollection).length > 0) {
+        ini += iniLine('renameCollection', serializeRenameMapping(config.renameCollection));
+    } else {
+        ini += iniComment('renameCollection', 'users:users_backup, orders:orders_2024');
+    }
+
+    if (config.idPrefix) {
+        ini += iniLine('idPrefix', config.idPrefix);
+    } else {
+        ini += iniComment('idPrefix', 'backup_');
+    }
+
+    if (config.idSuffix) {
+        ini += iniLine('idSuffix', config.idSuffix);
+    } else {
+        ini += iniComment('idSuffix', '_v2');
+    }
+
+    if (config.webhook) {
+        ini += iniLine('webhook', config.webhook);
+    } else {
+        ini += iniComment('webhook', 'https://hooks.slack.com/services/...');
+    }
+
+    if (config.retries !== 3) {
+        ini += iniLine('retries', config.retries);
+    } else {
+        ini += iniComment('retries', 3);
+    }
+
+    if (config.rateLimit > 0) {
+        ini += iniLine('rateLimit', config.rateLimit);
+    } else {
+        ini += iniComment('rateLimit', 0);
+    }
+
+    ini += iniLine('skipOversized', config.skipOversized);
+    ini += iniLine('detectConflicts', config.detectConflicts);
+
+    if (config.maxDepth > 0) {
+        ini += iniLine('maxDepth', config.maxDepth);
+    } else {
+        ini += iniComment('maxDepth', 0);
+    }
+
+    ini += iniLine('verify', config.verify);
+    ini += iniLine('verifyIntegrity', config.verifyIntegrity);
+
+    return ini;
+}
+
+async function saveConfig(config: Config, format: 'ini' | 'json'): Promise<string> {
+    const defaultName = format === 'json' ? 'fscopy-config.json' : 'fscopy-config.ini';
+
+    const filePath = await input({
+        message: `Save path:`,
+        default: defaultName,
+    });
+
+    const resolvedPath = path.resolve(filePath);
+
+    if (fs.existsSync(resolvedPath)) {
+        const overwrite = await confirm({
+            message: `File "${filePath}" already exists. Overwrite?`,
+            default: false,
+        });
+        if (!overwrite) {
+            console.log('\nSave cancelled.\n');
+            process.exit(0);
+        }
+    }
+
+    const content = format === 'json' ? configToJson(config) : configToIni(config);
+    fs.writeFileSync(resolvedPath, content, 'utf-8');
+
+    console.log(`\nConfig saved: ${resolvedPath}`);
+    console.log(`\n   Run with:  fscopy -f ${filePath}\n`);
+
+    return resolvedPath;
+}
+
+// =============================================================================
+// Main interactive flow
+// =============================================================================
+
+export async function runInteractiveMode(config: Config): Promise<InteractiveResult> {
+    console.log('\n' + '='.repeat(SEPARATOR_LENGTH));
+    console.log('FSCOPY - INTERACTIVE MODE');
+    console.log('='.repeat(SEPARATOR_LENGTH) + '\n');
+
+    // 1. Projects
+    const sourceProject = await promptForProject(config.sourceProject, 'Source Firebase project ID', '>>');
+    const destProject = await promptForProject(config.destProject, 'Destination Firebase project ID', '>>');
+
+    let idPrefix = config.idPrefix;
+    let idSuffix = config.idSuffix;
+
+    if (sourceProject === destProject) {
+        const mods = await promptForIdModification(idPrefix, idSuffix);
+        idPrefix = mods.idPrefix;
+        idSuffix = mods.idSuffix;
+    }
+
+    // 2. Discover collections
+    const { app: tempSourceApp, collections: collectionInfo } = await discoverCollections(sourceProject);
+
+    // 3. Select collections
     console.log('');
     const selectedCollections = await checkbox({
         message: 'Select collections to transfer:',
@@ -141,7 +610,7 @@ export async function runInteractiveMode(config: Config): Promise<Config> {
         validate: (value) => value.length > 0 || 'Select at least one collection',
     });
 
-    // Ask about options
+    // 4. Basic options
     console.log('');
     const includeSubcollections = await confirm({
         message: 'Include subcollections?',
@@ -158,11 +627,8 @@ export async function runInteractiveMode(config: Config): Promise<Config> {
         default: config.merge,
     });
 
-    // Clean up temporary app
-    await tempSourceApp.delete();
-
-    // Return updated config
-    return {
+    // Build config so far
+    let finalConfig: Config = {
         ...config,
         sourceProject,
         destProject,
@@ -173,4 +639,23 @@ export async function runInteractiveMode(config: Config): Promise<Config> {
         idPrefix,
         idSuffix,
     };
+
+    // 5. Advanced options
+    console.log('');
+    const advancedUpdates = await promptAdvancedOptions(finalConfig);
+    finalConfig = { ...finalConfig, ...advancedUpdates };
+
+    // Clean up temporary Firebase app
+    await tempSourceApp.delete();
+
+    // 6. Final action
+    const action = await promptFinalAction();
+
+    if (action === 'save-ini' || action === 'save-json') {
+        const format = action === 'save-json' ? 'json' : 'ini';
+        await saveConfig(finalConfig, format);
+        return { config: finalConfig, action: 'save' };
+    }
+
+    return { config: finalConfig, action: 'execute' };
 }

package/src/orchestrator.ts

@@ -265,6 +265,24 @@ async function validateTransformWithSamples(
     output.blank();
 }
 
+function canWriteProgress(output: Output): boolean {
+    return !output.isQuiet && !output.isJson && process.stdout.isTTY === true;
+}
+
+function clearLine(): void {
+    if (!process.stdout.isTTY) return;
+    const width = typeof process.stdout.columns === 'number' && process.stdout.columns > 0
+        ? process.stdout.columns
+        : SEPARATOR_LENGTH;
+    process.stdout.write('\r' + ' '.repeat(width) + '\r');
+}
+
+function formatNameList(names: Set<string>, max: number = 8): string {
+    const arr = [...names];
+    if (arr.length <= max) return arr.join(', ');
+    return arr.slice(0, max).join(', ') + `, ... (+${arr.length - max})`;
+}
+
 async function setupProgressTracking(
     sourceDb: Firestore,
     config: Config,
@@ -276,34 +294,66 @@ async function setupProgressTracking(
 
     if (!output.isQuiet) {
         output.info('📊 Counting documents...');
-        let lastSubcollectionLog = Date.now();
-        let subcollectionCount = 0;
-
-        const countProgress: CountProgress = {
-            onCollection: (path, count) => {
-                output.info(`   ${path}: ${count} documents`);
-            },
-            onSubcollection: (_path) => {
-                subcollectionCount++;
-                const now = Date.now();
-                if (now - lastSubcollectionLog > PROGRESS_LOG_INTERVAL_MS) {
-                    process.stdout.write(`\r   Scanning subcollections... (${subcollectionCount} found)`);
-                    lastSubcollectionLog = now;
-                }
-            },
-        };
 
         for (const collection of config.collections) {
-            totalDocs += await countDocuments(sourceDb, collection, config, 0, countProgress);
-        }
+            let rootCount = 0;
+            let subcollectionInstances = 0;
+            const subcollectionNames = new Set<string>();
+            const excludedNames = new Set<string>();
+            let lastLog = Date.now();
+            let showedScanLine = false;
+
+            if (canWriteProgress(output)) {
+                process.stdout.write(`   Counting ${collection}...`);
+                showedScanLine = true;
+            }
+
+            const countProgress: CountProgress = {
+                onCollection: (_path, count) => {
+                    rootCount = count;
+                },
+                onSubcollection: (path) => {
+                    subcollectionInstances++;
+                    const segments = path.split('/');
+                    subcollectionNames.add(segments[segments.length - 1]);
+
+                    if (!canWriteProgress(output)) return;
+                    const now = Date.now();
+                    if (now - lastLog > PROGRESS_LOG_INTERVAL_MS) {
+                        process.stdout.write(`\r   Scanning ${collection}... (${subcollectionInstances} subcollections found)`);
+                        showedScanLine = true;
+                        lastLog = now;
+                    }
+                },
+                onSubcollectionExcluded: (name) => {
+                    excludedNames.add(name);
+                },
+            };
+
+            const collectionTotal = await countDocuments(sourceDb, collection, config, 0, countProgress);
+            totalDocs += collectionTotal;
+
+            // Clear live indicator line
+            if (showedScanLine && canWriteProgress(output)) {
+                clearLine();
+            }
+
+            // Print collection summary
+            output.info(`   ${collection}: ${rootCount} documents`);
 
-        if (subcollectionCount > 0) {
-            process.stdout.write('\r' + ' '.repeat(SEPARATOR_LENGTH) + '\r');
-            output.info(`   Subcollections scanned: ${subcollectionCount}`);
+            if (subcollectionInstances > 0) {
+                const subDocs = collectionTotal - rootCount;
+                output.info(`      + ${subDocs} in subcollections (${formatNameList(subcollectionNames)})`);
+            }
+            if (excludedNames.size > 0) {
+                output.info(`      Excluded: ${formatNameList(excludedNames)}`);
+            }
         }
-        output.info(`   Total: ${totalDocs} documents to transfer\n`);
 
-        progressBar.start(totalDocs, stats);
+        output.info(`\n   Total: ${totalDocs} documents to transfer\n`);
+        if (canWriteProgress(output)) {
+            progressBar.start(totalDocs, stats);
+        }
     }
 
     return { totalDocs, progressBar };
@@ -376,14 +426,17 @@ async function deleteOrphanDocs(
     let lastProgressLog = Date.now();
     let subcollectionCount = 0;
 
+    const showProgress = canWriteProgress(output);
+
     const progress: DeleteOrphansProgress = {
         onScanStart: (collection) => {
-            process.stdout.write(`   Scanning ${collection}...`);
+            if (showProgress) process.stdout.write(`   Scanning ${collection}...`);
         },
         onScanComplete: (collection, orphanCount, totalDest) => {
-            process.stdout.write(`\r   ${collection}: ${orphanCount}/${totalDest} orphan docs\n`);
+            if (showProgress) process.stdout.write(`\r   ${collection}: ${orphanCount}/${totalDest} orphan docs\n`);
         },
         onBatchDeleted: (collection, deletedSoFar, total) => {
+            if (!showProgress) return;
             process.stdout.write(`\r   Deleting from ${collection}... ${deletedSoFar}/${total}`);
             if (deletedSoFar === total) {
                 process.stdout.write('\n');
@@ -391,6 +444,7 @@ async function deleteOrphanDocs(
         },
         onSubcollectionScan: (_path) => {
             subcollectionCount++;
+            if (!showProgress) return;
             const now = Date.now();
             if (now - lastProgressLog > PROGRESS_LOG_INTERVAL_MS) {
                 process.stdout.write(`\r   Scanning subcollections... (${subcollectionCount} checked)`);
@@ -411,8 +465,8 @@ async function deleteOrphanDocs(
         stats.documentsDeleted += deleted;
     }
 
-    if (subcollectionCount > 0) {
-        process.stdout.write('\r' + ' '.repeat(SEPARATOR_LENGTH) + '\r');
+    if (subcollectionCount > 0 && showProgress) {
+        clearLine();
     }
 
     if (stats.documentsDeleted > 0) {

package/src/transfer/count.ts

@@ -6,6 +6,7 @@ import { getSubcollections } from './helpers.js';
 export interface CountProgress {
     onCollection?: (path: string, count: number) => void;
     onSubcollection?: (path: string) => void;
+    onSubcollectionExcluded?: (name: string) => void;
 }
 
 function buildQueryWithFilters(
@@ -65,11 +66,19 @@ async function countSubcollectionsForDoc(
     depth: number,
     progress?: CountProgress
 ): Promise<number> {
+    // Respect maxDepth to match transfer behavior
+    if (config.maxDepth > 0 && depth >= config.maxDepth) return 0;
+
     let count = 0;
     const subcollections = await getSubcollections(doc.ref);
 
     for (const subId of subcollections) {
-        if (matchesExcludePattern(subId, config.exclude)) continue;
+        if (matchesExcludePattern(subId, config.exclude)) {
+            if (progress?.onSubcollectionExcluded) {
+                progress.onSubcollectionExcluded(subId);
+            }
+            continue;
+        }
 
         const subPath = `${collectionPath}/${doc.id}/${subId}`;
         if (progress?.onSubcollection) {

package/src/transfer/transfer.ts

@@ -101,7 +101,7 @@ async function checkForConflicts(
     return conflicts;
 }
 
-function buildTransferQuery(
+function buildBaseQuery(
     sourceDb: Firestore,
     collectionPath: string,
     config: Config,
@@ -115,10 +115,7 @@ function buildTransferQuery(
         }
     }
 
-    if (config.limit > 0 && depth === 0) {
-        query = query.limit(config.limit);
-    }
-
+    // Limit is handled via pagination in transferCollection
     return query;
 }
 
@@ -533,25 +530,50 @@ export async function transferCollection(
     const { sourceDb, config, stats, output } = ctx;
     const destCollectionPath = getDestCollectionPath(collectionPath, config.renameCollection);
 
-    const query = buildTransferQuery(sourceDb, collectionPath, config, depth);
+    const baseQuery = buildBaseQuery(sourceDb, collectionPath, config, depth);
+    const userLimit = config.limit > 0 && depth === 0 ? config.limit : 0;
 
-    const snapshot = await withRetry(() => query.get(), {
-        retries: config.retries,
-        onRetry: (attempt, max, err, delay) => {
-            output.logError(`Retry ${attempt}/${max} for ${collectionPath}`, {
-                error: err.message,
-                delay,
-            });
-        },
-    });
+    let totalProcessed = 0;
+    let lastDoc: QueryDocumentSnapshot | undefined;
+
+    while (true) {
+        // Calculate page size respecting user limit
+        let pageSize = config.batchSize;
+        if (userLimit > 0) {
+            const remaining = userLimit - totalProcessed;
+            if (remaining <= 0) break;
+            pageSize = Math.min(pageSize, remaining);
+        }
+
+        // Build paginated query
+        let pageQuery = baseQuery.limit(pageSize);
+        if (lastDoc) {
+            pageQuery = pageQuery.startAfter(lastDoc);
+        }
+
+        const snapshot = await withRetry(() => pageQuery.get(), {
+            retries: config.retries,
+            onRetry: (attempt, max, err, delay) => {
+                output.logError(`Retry ${attempt}/${max} for ${collectionPath}`, {
+                    error: err.message,
+                    delay,
+                });
+            },
+        });
+
+        if (snapshot.empty) break;
+
+        if (totalProcessed === 0) {
+            stats.collectionsProcessed++;
+            output.logInfo(`Processing collection: ${collectionPath}`);
+        }
 
-    if (snapshot.empty) return;
+        await processBatch(snapshot.docs, ctx, collectionPath, destCollectionPath, depth);
 
-    stats.collectionsProcessed++;
-    output.logInfo(`Processing collection: ${collectionPath}`, { documents: snapshot.size });
+        totalProcessed += snapshot.docs.length;
+        lastDoc = snapshot.docs[snapshot.docs.length - 1];
 
-    for (let i = 0; i < snapshot.docs.length; i += config.batchSize) {
-        const batch = snapshot.docs.slice(i, i + config.batchSize);
-        await processBatch(batch, ctx, collectionPath, destCollectionPath, depth);
+        // Fewer docs than requested means we've reached the end
+        if (snapshot.docs.length < pageSize) break;
     }
 }

package/src/types.ts

@@ -97,7 +97,7 @@ export interface CliArgs {
     yes: boolean;
     log?: string;
     maxLogSize?: string;
-    retries: number;
+    retries?: number;
     quiet: boolean;
     where?: string[];
     exclude?: string[];