@fazetitans/fscopy 1.1.3 → 1.2.0

package/src/transform/loader.ts

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { TransformFunction } from '../types.js';
+
+export async function loadTransformFunction(transformPath: string): Promise<TransformFunction> {
+    const absolutePath = path.resolve(transformPath);
+
+    if (!fs.existsSync(absolutePath)) {
+        throw new Error(`Transform file not found: ${absolutePath}`);
+    }
+
+    try {
+        const module = await import(absolutePath);
+
+        // Look for 'transform' export (default or named)
+        const transformFn = module.default?.transform ?? module.transform ?? module.default;
+
+        if (typeof transformFn !== 'function') {
+            throw new TypeError(
+                `Transform file must export a 'transform' function. Got: ${typeof transformFn}`
+            );
+        }
+
+        return transformFn as TransformFunction;
+    } catch (error) {
+        if ((error as Error).message.includes('Transform file')) {
+            throw error;
+        }
+        throw new Error(`Failed to load transform file: ${(error as Error).message}`);
+    }
+}

package/src/types.ts

@@ -34,6 +34,16 @@ export interface Config {
     rateLimit: number;
     skipOversized: boolean;
     json: boolean;
+    transformSamples: number;
+    detectConflicts: boolean;
+    maxDepth: number;
+    verifyIntegrity: boolean;
+}
+
+export interface ConflictInfo {
+    collection: string;
+    docId: string;
+    reason: string;
 }
 
 export interface Stats {
@@ -41,6 +51,8 @@ export interface Stats {
     documentsTransferred: number;
     documentsDeleted: number;
     errors: number;
+    conflicts: number;
+    integrityErrors: number;
 }
 
 export interface TransferState {
@@ -78,6 +90,7 @@ export interface CliArgs {
     destProject?: string;
     yes: boolean;
     log?: string;
+    maxLogSize?: string;
     retries: number;
     quiet: boolean;
     where?: string[];
@@ -98,4 +111,9 @@ export interface CliArgs {
     rateLimit?: number;
     skipOversized?: boolean;
     json?: boolean;
+    transformSamples?: number;
+    detectConflicts?: boolean;
+    maxDepth?: number;
+    verifyIntegrity?: boolean;
+    validateOnly?: boolean;
 }

package/src/utils/credentials.ts

@@ -3,10 +3,10 @@ import path from 'node:path';
 import os from 'node:os';
 
 export function checkCredentialsExist(): { exists: boolean; path: string } {
-    // Check for explicit credentials file
-    if (process.env.GOOGLE_APPLICATION_CREDENTIALS) {
-        const credPath = process.env.GOOGLE_APPLICATION_CREDENTIALS;
-        return { exists: fs.existsSync(credPath), path: credPath };
+    // Check for explicit credentials file (non-empty string)
+    const envCredPath = process.env.GOOGLE_APPLICATION_CREDENTIALS;
+    if (envCredPath && envCredPath.length > 0) {
+        return { exists: fs.existsSync(envCredPath), path: envCredPath };
     }
 
     // Check for Application Default Credentials
@@ -20,6 +20,11 @@ export function checkCredentialsExist(): { exists: boolean; path: string } {
 }
 
 export function ensureCredentials(): void {
+    // Skip credentials check in test environment
+    if (process.env.FSCOPY_SKIP_CREDENTIALS_CHECK === '1') {
+        return;
+    }
+
     const { exists, path: credPath } = checkCredentialsExist();
 
     if (!exists) {

package/src/utils/doc-size.ts

@@ -18,10 +18,7 @@ export const FIRESTORE_MAX_DOC_SIZE = 1024 * 1024;
  * - GeoPoints: 16 bytes
  * - References: document path length + 1
  */
-export function estimateDocumentSize(
-    data: Record<string, unknown>,
-    docPath?: string
-): number {
+export function estimateDocumentSize(data: Record<string, unknown>, docPath?: string): number {
     let size = 0;
 
     // Document name (path) contributes to size
@@ -34,85 +31,59 @@ export function estimateDocumentSize(
     return size;
 }
 
-function estimateValueSize(value: unknown): number {
-    if (value === null || value === undefined) {
-        return 1;
-    }
-
-    if (typeof value === 'boolean') {
-        return 1;
-    }
-
-    if (typeof value === 'number') {
-        return 8;
-    }
+function isFirestoreTimestamp(value: object): boolean {
+    return '_seconds' in value && '_nanoseconds' in value;
+}
 
-    if (typeof value === 'string') {
-        // UTF-8 encoded length
-        return Buffer.byteLength(value, 'utf8') + 1;
-    }
+function isGeoPoint(value: object): boolean {
+    return '_latitude' in value && '_longitude' in value;
+}
 
-    if (value instanceof Date) {
-        return 8;
-    }
+function isDocumentReference(value: object): boolean {
+    return '_path' in value && typeof (value as { _path: unknown })._path === 'object';
+}
 
-    // Firestore Timestamp
-    if (
-        value &&
-        typeof value === 'object' &&
-        '_seconds' in value &&
-        '_nanoseconds' in value
-    ) {
-        return 8;
+function getDocRefSize(value: object): number {
+    const pathObj = (value as { _path: { segments?: string[] } })._path;
+    if (pathObj.segments) {
+        return pathObj.segments.join('/').length + 1;
     }
+    return 16; // Approximate
+}
 
-    // GeoPoint
-    if (
-        value &&
-        typeof value === 'object' &&
-        '_latitude' in value &&
-        '_longitude' in value
-    ) {
-        return 16;
+function estimateArraySize(arr: unknown[]): number {
+    let size = 0;
+    for (const item of arr) {
+        size += estimateValueSize(item);
     }
+    return size;
+}
 
-    // DocumentReference
-    if (
-        value &&
-        typeof value === 'object' &&
-        '_path' in value &&
-        typeof (value as { _path: unknown })._path === 'object'
-    ) {
-        const pathObj = (value as { _path: { segments?: string[] } })._path;
-        if (pathObj.segments) {
-            return pathObj.segments.join('/').length + 1;
-        }
-        return 16; // Approximate
+function estimateObjectSize(obj: object): number {
+    let size = 0;
+    for (const [key, val] of Object.entries(obj)) {
+        size += key.length + 1; // Key size
+        size += estimateValueSize(val); // Value size
     }
+    return size;
+}
 
-    // Array
-    if (Array.isArray(value)) {
-        let size = 0;
-        for (const item of value) {
-            size += estimateValueSize(item);
-        }
-        return size;
-    }
+function estimateValueSize(value: unknown): number {
+    if (value === null || value === undefined) return 1;
+    if (typeof value === 'boolean') return 1;
+    if (typeof value === 'number') return 8;
+    if (typeof value === 'string') return Buffer.byteLength(value, 'utf8') + 1;
+    if (value instanceof Date) return 8;
 
-    // Map/Object
     if (typeof value === 'object') {
-        let size = 0;
-        for (const [key, val] of Object.entries(value)) {
-            // Key size (field name)
-            size += key.length + 1;
-            // Value size
-            size += estimateValueSize(val);
-        }
-        return size;
+        if (isFirestoreTimestamp(value)) return 8;
+        if (isGeoPoint(value)) return 16;
+        if (isDocumentReference(value)) return getDocRefSize(value);
+        if (Array.isArray(value)) return estimateArraySize(value);
+        return estimateObjectSize(value);
     }
 
-    // Unknown type - estimate as small value
-    return 8;
+    return 8; // Unknown type
 }
 
 /**

package/src/utils/errors.ts

@@ -19,7 +19,7 @@ const errorMap: Record<string, FirebaseErrorInfo> = {
         message: 'Permission denied',
         suggestion: 'Ensure you have Firestore read/write access on this project',
     },
-    'PERMISSION_DENIED': {
+    PERMISSION_DENIED: {
         message: 'Permission denied',
         suggestion: 'Ensure you have Firestore read/write access on this project',
     },

package/src/utils/index.ts

@@ -1,5 +1,6 @@
 export { withRetry, type RetryOptions } from './retry.js';
-export { Logger } from './logger.js';
+export { Output, type OutputOptions } from './output.js';
+export { ProgressBarWrapper, type ProgressBarOptions } from './progress.js';
 export { checkCredentialsExist, ensureCredentials } from './credentials.js';
 export { matchesExcludePattern } from './patterns.js';
 export { formatFirebaseError, logFirebaseError, type FirebaseErrorInfo } from './errors.js';

package/src/utils/integrity.ts

@@ -0,0 +1,122 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Compute a SHA-256 hash of document data.
+ * The data is serialized to a deterministic JSON string before hashing.
+ */
+export function hashDocumentData(data: Record<string, unknown>): string {
+    const serialized = serializeForHash(data);
+    return createHash('sha256').update(serialized).digest('hex');
+}
+
+/**
+ * Serialize document data to a deterministic JSON string.
+ * Keys are sorted alphabetically at each level for consistency.
+ */
+function serializeForHash(value: unknown): string {
+    if (value === null || value === undefined) {
+        return 'null';
+    }
+
+    if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+
+    // Handle Date objects
+    if (value instanceof Date) {
+        return JSON.stringify(value.toISOString());
+    }
+
+    // Handle Firestore Timestamp
+    if (isFirestoreTimestamp(value)) {
+        return JSON.stringify({ _seconds: value.seconds, _nanoseconds: value.nanoseconds });
+    }
+
+    // Handle Firestore GeoPoint
+    if (isFirestoreGeoPoint(value)) {
+        return JSON.stringify({ _latitude: value.latitude, _longitude: value.longitude });
+    }
+
+    // Handle Firestore DocumentReference
+    if (isFirestoreDocumentReference(value)) {
+        return JSON.stringify({ _path: value.path });
+    }
+
+    // Handle arrays
+    if (Array.isArray(value)) {
+        const elements = value.map((item) => serializeForHash(item));
+        return `[${elements.join(',')}]`;
+    }
+
+    // Handle objects - sort keys for deterministic output
+    if (typeof value === 'object') {
+        const obj = value as Record<string, unknown>;
+        const sortedKeys = Object.keys(obj).sort((a, b) => a.localeCompare(b));
+        const pairs = sortedKeys.map(
+            (key) => `${JSON.stringify(key)}:${serializeForHash(obj[key])}`
+        );
+        return `{${pairs.join(',')}}`;
+    }
+
+    // Fallback for unknown types - should not reach here normally
+    return '"[unknown]"';
+}
+
+/**
+ * Compare two document hashes.
+ */
+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,13 +1,28 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import type { Stats, LogEntry } from '../types.js';
 
+export interface LoggerOptions {
+    logPath?: string;
+    maxSize?: number; // Max size in bytes (0 = unlimited)
+    maxFiles?: number; // Max number of rotated files to keep
+}
+
 export class Logger {
     private readonly logPath: string | undefined;
     private readonly entries: LogEntry[] = [];
     private readonly startTime: Date;
+    private readonly maxSize: number;
+    private readonly maxFiles: number;
 
-    constructor(logPath?: string) {
-        this.logPath = logPath;
+    constructor(optionsOrPath?: LoggerOptions | string) {
+        // Backward compatibility: accept string as logPath
+        const options: LoggerOptions =
+            typeof optionsOrPath === 'string' ? { logPath: optionsOrPath } : (optionsOrPath ?? {});
+
+        this.logPath = options.logPath;
+        this.maxSize = options.maxSize ?? 0;
+        this.maxFiles = options.maxFiles ?? 5;
         this.startTime = new Date();
     }
 
@@ -43,18 +58,59 @@ export class Logger {
 
     init(): void {
         if (this.logPath) {
+            this.rotateIfNeeded();
             const header = `# fscopy transfer log\n# Started: ${this.startTime.toISOString()}\n\n`;
             fs.writeFileSync(this.logPath, header);
         }
     }
 
+    /**
+     * Rotate log file if it exceeds maxSize.
+     * 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);
+            }
+        }
+
+        // Rename current to .1
+        const backupPath = path.join(dir, `${base}.1${ext}`);
+        fs.renameSync(this.logPath, backupPath);
+    }
+
     summary(stats: Stats, duration: string): void {
         if (this.logPath) {
             let summary = `\n# Summary\n# Collections: ${stats.collectionsProcessed}\n`;
             if (stats.documentsDeleted > 0) {
                 summary += `# Deleted: ${stats.documentsDeleted}\n`;
             }
-            summary += `# Transferred: ${stats.documentsTransferred}\n# Errors: ${stats.errors}\n# Duration: ${duration}s\n`;
+            summary += `# Transferred: ${stats.documentsTransferred}\n`;
+            if (stats.conflicts > 0) {
+                summary += `# Conflicts: ${stats.conflicts}\n`;
+            }
+            summary += `# Errors: ${stats.errors}\n# Duration: ${duration}s\n`;
             fs.appendFileSync(this.logPath, summary);
         }
     }