@fazetitans/fscopy 1.1.2 → 1.2.0

package/README.md

@@ -237,6 +237,8 @@ The transform function receives:
 
 Return the transformed document, or `null` to skip it.
 
+> **Security Warning**: The `--transform` option executes arbitrary code from the specified file. Only use transform files from trusted sources. Never run transforms from untrusted or unverified files as they have full access to your system.
+
 ### Webhook Notifications
 
 Get notified when transfers complete (success or failure):
@@ -351,39 +353,42 @@ fscopy --init config.json
 
 ## CLI Reference
 
-| Option                     | Alias | Type    | Default | Description                       |
-| -------------------------- | ----- | ------- | ------- | --------------------------------- |
-| `--init`                   |       | string  |         | Generate config template          |
-| `--config`                 | `-f`  | string  |         | Path to config file               |
-| `--source-project`         |       | string  |         | Source Firebase project           |
-| `--dest-project`           |       | string  |         | Destination project               |
-| `--collections`            | `-c`  | array   |         | Collections to transfer           |
-| `--include-subcollections` | `-s`  | boolean | `false` | Include subcollections            |
-| `--where`                  | `-w`  | array   |         | Filter documents                  |
-| `--exclude`                | `-x`  | array   |         | Exclude subcollections            |
-| `--merge`                  | `-m`  | boolean | `false` | Merge instead of overwrite        |
-| `--parallel`               | `-p`  | number  | `1`     | Parallel transfers                |
-| `--dry-run`                | `-d`  | boolean | `true`  | Preview without writing           |
-| `--batch-size`             | `-b`  | number  | `500`   | Documents per batch               |
-| `--limit`                  | `-l`  | number  | `0`     | Limit docs (0 = no limit)         |
-| `--retries`                |       | number  | `3`     | Retries on error                  |
-| `--log`                    |       | string  |         | Log file path                     |
-| `--quiet`                  | `-q`  | boolean | `false` | No progress bar                   |
-| `--yes`                    | `-y`  | boolean | `false` | Skip confirmation                 |
-| `--clear`                  |       | boolean | `false` | Clear destination before transfer |
-| `--delete-missing`         |       | boolean | `false` | Delete dest docs not in source    |
-| `--interactive`            | `-i`  | boolean | `false` | Interactive mode with prompts     |
-| `--transform`              | `-t`  | string  |         | Path to JS/TS transform file      |
-| `--rename-collection`      | `-r`  | array   |         | Rename collection (source:dest)   |
-| `--id-prefix`              |       | string  |         | Add prefix to document IDs        |
-| `--id-suffix`              |       | string  |         | Add suffix to document IDs        |
-| `--webhook`                |       | string  |         | Webhook URL for notifications     |
-| `--resume`                 |       | boolean | `false` | Resume from saved state           |
-| `--state-file`             |       | string  | `.fscopy-state.json` | State file path      |
-| `--verify`                 |       | boolean | `false` | Verify counts after transfer      |
-| `--rate-limit`             |       | number  | `0`     | Limit docs/second (0 = unlimited) |
-| `--skip-oversized`         |       | boolean | `false` | Skip documents > 1MB              |
-| `--json`                   |       | boolean | `false` | JSON output for CI/CD             |
+| Option                     | Alias | Type    | Default              | Description                             |
+| -------------------------- | ----- | ------- | -------------------- | --------------------------------------- |
+| `--init`                   |       | string  |                      | Generate config template                |
+| `--config`                 | `-f`  | string  |                      | Path to config file                     |
+| `--source-project`         |       | string  |                      | Source Firebase project                 |
+| `--dest-project`           |       | string  |                      | Destination project                     |
+| `--collections`            | `-c`  | array   |                      | Collections to transfer                 |
+| `--include-subcollections` | `-s`  | boolean | `false`              | Include subcollections                  |
+| `--where`                  | `-w`  | array   |                      | Filter documents                        |
+| `--exclude`                | `-x`  | array   |                      | Exclude subcollections                  |
+| `--merge`                  | `-m`  | boolean | `false`              | Merge instead of overwrite              |
+| `--parallel`               | `-p`  | number  | `1`                  | Parallel transfers                      |
+| `--dry-run`                | `-d`  | boolean | `true`               | Preview without writing                 |
+| `--batch-size`             | `-b`  | number  | `500`                | Documents per batch                     |
+| `--limit`                  | `-l`  | number  | `0`                  | Limit docs (0 = no limit)               |
+| `--retries`                |       | number  | `3`                  | Retries on error                        |
+| `--log`                    |       | string  |                      | Log file path                           |
+| `--quiet`                  | `-q`  | boolean | `false`              | No progress bar                         |
+| `--yes`                    | `-y`  | boolean | `false`              | Skip confirmation                       |
+| `--clear`                  |       | boolean | `false`              | Clear destination before transfer       |
+| `--delete-missing`         |       | boolean | `false`              | Delete dest docs not in source          |
+| `--interactive`            | `-i`  | boolean | `false`              | Interactive mode with prompts           |
+| `--transform`              | `-t`  | string  |                      | Path to JS/TS transform file            |
+| `--rename-collection`      | `-r`  | array   |                      | Rename collection (source:dest)         |
+| `--id-prefix`              |       | string  |                      | Add prefix to document IDs              |
+| `--id-suffix`              |       | string  |                      | Add suffix to document IDs              |
+| `--webhook`                |       | string  |                      | Webhook URL for notifications           |
+| `--resume`                 |       | boolean | `false`              | Resume from saved state                 |
+| `--state-file`             |       | string  | `.fscopy-state.json` | State file path                         |
+| `--verify`                 |       | boolean | `false`              | Verify counts after transfer            |
+| `--rate-limit`             |       | number  | `0`                  | Limit docs/second (0 = unlimited)       |
+| `--skip-oversized`         |       | boolean | `false`              | Skip documents > 1MB                    |
+| `--json`                   |       | boolean | `false`              | JSON output for CI/CD                   |
+| `--max-depth`              |       | number  | `0`                  | Max subcollection depth (0 = unlimited) |
+| `--detect-conflicts`       |       | boolean | `false`              | Detect concurrent modifications         |
+| `--verify-integrity`       |       | boolean | `false`              | Verify document integrity with hash     |
 
 ## How It Works
 
@@ -393,6 +398,14 @@ fscopy --init config.json
 4. **Retry logic** - Automatic retry with exponential backoff on failures
 5. **Subcollection discovery** - Uses `listCollections()` to find nested data
 
+## Security
+
+- **Transform files execute arbitrary code** - The `--transform` option uses dynamic imports to load and execute JavaScript/TypeScript files. Only use transform files you have written or thoroughly reviewed. Malicious transform files could access your filesystem, network, or credentials.
+
+- **Webhook URLs should use HTTPS** - fscopy warns if you use HTTP webhooks (except localhost). Webhook payloads contain project names and transfer statistics that could be sensitive.
+
+- **Credentials via ADC** - fscopy uses Google Application Default Credentials. Ensure you're authenticated with the correct account before running transfers.
+
 ## Notes
 
 - **Dry run is ON by default** - Use `-d false` for actual transfer
@@ -405,6 +418,46 @@ fscopy --init config.json
 - **Transform applies to all** - Transform function is applied to both root and subcollection docs
 - **Same project allowed** - Source and destination can be the same project when using `--rename-collection` or `--id-prefix`/`--id-suffix`
 
+## Limitations
+
+### Firestore Special Types
+
+When reading documents, Firestore sentinel values are resolved to their actual values:
+
+| Sentinel | Behavior |
+| -------- | -------- |
+| `serverTimestamp()` | Resolved to actual `Timestamp` value |
+| `increment()` | Resolved to current numeric value |
+| `arrayUnion()` / `arrayRemove()` | Resolved to current array value |
+
+These sentinels are **write-time operations**, not persistent values. fscopy transfers the resolved data, which is the expected behavior for data migration.
+
+### Document References
+
+`DocumentReference` fields are transferred as-is. If the reference points to a document in the source project, it will still point to the source after transfer. Consider using `--transform` to update references if needed.
+
+### Collection and Document IDs
+
+fscopy validates IDs according to Firestore rules:
+
+- Cannot be empty
+- Cannot be `.` or `..`
+- Cannot match `__*__` pattern (reserved by Firestore)
+
+Unicode characters, special characters (`#`, `$`, `[`, `]`), and forward slashes in nested paths are all supported.
+
+### Subcollection Depth
+
+Use `--max-depth` to limit recursion when copying deeply nested subcollections:
+
+```bash
+# Copy only first level of subcollections
+fscopy -f config.ini -s --max-depth 1
+
+# Copy up to 3 levels deep
+fscopy -f config.ini -s --max-depth 3
+```
+
 ## Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fazetitans/fscopy",
-    "version": "1.1.2",
+    "version": "1.2.0",
     "description": "Fast CLI tool to copy Firestore collections between Firebase projects with filtering, parallel transfers, and subcollection support",
     "type": "module",
     "bin": {
@@ -12,8 +12,8 @@
         "test": "bun test",
         "test:watch": "bun test --watch",
         "type-check": "tsc --noEmit",
-        "lint": "eslint src/**/*.ts",
-        "lint:fix": "eslint src/**/*.ts --fix",
+        "lint": "eslint src/**/*.ts --ignore-pattern 'src/__tests__/**' --no-warn-ignored",
+        "lint:fix": "eslint src/**/*.ts --ignore-pattern 'src/__tests__/**' --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"