repo-cloak-cli 1.0.1 → 1.2.0

package/medium.md

@@ -0,0 +1,319 @@
+# Repo-Cloak: A CLI Tool for Safely Using AI Coding Assistants on Proprietary Codebases
+
+The rise of AI-powered coding assistants like GitHub Copilot, Cursor, and Claude has fundamentally changed how developers write software. These tools can dramatically accelerate development, debug complex issues, and even architect entire systems. But for engineers working on proprietary or enterprise codebases, there is a persistent concern: *How do you leverage these powerful AI tools without exposing sensitive business logic, customer data, or confidential intellectual property?*
+
+This article introduces **Repo-Cloak**, a command-line tool I built to address this exact challenge. It provides a secure, selective approach to sharing code with AI assistants while maintaining complete control over what information leaves your environment.
+
+---
+
+## The Problem: AI Assistance vs Enterprise Security
+
+Modern AI coding assistants require context to be effective. The more code they can see, the better their suggestions. But enterprise environments present unique challenges:
+
+- **Proprietary Business Logic**: Core algorithms, pricing engines, and competitive differentiators must remain confidential
+- **Customer Data References**: Database schemas, API endpoints, and configuration files often contain sensitive identifiers
+- **Company-Specific Naming**: Project names, internal tools, and organizational structures reveal information about your infrastructure
+- **Compliance Requirements**: Healthcare, finance, and government sectors have strict regulations about data handling
+
+The traditional approach forces developers to choose between two suboptimal paths: either manually copy-paste sanitized code snippets (losing context and wasting time), or share entire repositories with AI tools (accepting security risks). Repo-Cloak offers a third path.
+
+---
+
+## The Solution: Selective Extraction with Intelligent Anonymization
+
+Repo-Cloak operates on a simple but powerful principle: **extract only what you need, anonymize what you must protect, and maintain a reversible mapping for seamless integration**.
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        ORIGINAL REPOSITORY                          │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
+│  │ XCorpAPI/    │  │ Payments/    │  │ Analytics/   │              │
+│  │   auth.cs    │  │   stripe.cs  │  │   metrics.cs │              │
+│  │   users.cs   │  │   billing.cs │  │   reports.cs │              │
+│  └──────────────┘  └──────────────┘  └──────────────┘              │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              │ PULL (selective + anonymize)
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                        CLOAKED WORKSPACE                            │
+│  ┌──────────────┐                                                   │
+│  │ AcmeAPI/     │  ← Folder names anonymized                        │
+│  │   auth.cs    │  ← Content: "XCorp" → "Acme"                      │
+│  │   users.cs   │  ← Safe to share with AI assistants               │
+│  └──────────────┘                                                   │
+│                                                                     │
+│  .repo-cloak-map.json  ← Encrypted mapping for restoration          │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              │ AI AGENT MAKES MODIFICATIONS
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                        PUSH (restore + de-anonymize)                │
+│                                                                     │
+│  Modified files pushed back to original repository                  │
+│  All anonymization reversed automatically                           │
+│  "Acme" → "XCorp" in both content and file paths                    │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## How It Works: A Technical Deep Dive
+
+### 1. Interactive File Selection
+
+Rather than extracting entire directories, Repo-Cloak provides an interactive file selector with hierarchical navigation. Developers can search, filter, and selectively choose exactly which files to extract.
+
+```
+? Select files to extract:
+  ◉ 📁 src/Services
+  ◉   📄 BookService.cs
+  ◯   📄 PaymentService.cs      ← Excluded: contains billing logic
+  ◉   📄 UserService.cs
+  ◯ 📁 src/Infrastructure       ← Entire folder excluded
+```
+
+The selector supports pagination for large codebases, folder-level selection (selecting a folder automatically includes all children), and real-time filtering.
+
+### 2. Intelligent Content Anonymization
+
+The anonymization engine performs case-preserving replacements across all extracted content. This means your code remains syntactically valid and readable:
+
+```csharp
+// Original
+namespace XCorp.Services {
+    public class XCorpBookManager : IXCorpService {
+        private const string XCORP_API_KEY = "...";
+    }
+}
+
+// Anonymized (case preservation maintained)
+namespace Acme.Services {
+    public class AcmeBookManager : IAcmeService {
+        private const string ACME_API_KEY = "...";
+    }
+}
+```
+
+The engine handles:
+- **PascalCase**: `XCorpService` becomes `AcmeService`
+- **camelCase**: `xcorpClient` becomes `acmeClient`
+- **SCREAMING_CASE**: `XCORP_KEY` becomes `ACME_KEY`
+- **lowercase**: `xcorp` becomes `acme`
+
+### 3. Path Anonymization
+
+Beyond content, Repo-Cloak also anonymizes folder and file names. This prevents directory structures from revealing organizational patterns:
+
+```
+Original:  src/XCorpFrontEnd/XCorpComponents/XCorpButton.tsx
+Cloaked:   src/AcmeFrontEnd/AcmeComponents/AcmeButton.tsx
+```
+
+### 4. Encrypted Mapping with User-Specific Secrets
+
+Here is where security becomes critical. The mapping file that tracks original-to-anonymized paths must itself be protected. Repo-Cloak uses AES-256-GCM encryption with a user-specific secret key:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    ENCRYPTION ARCHITECTURE                    │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ~/.repo-cloak/secret.key                                    │
+│  ├── Generated automatically on first use                   │
+│  ├── 256-bit cryptographically random key                   │
+│  ├── Stored with 0600 permissions (owner-only)              │
+│  └── Unique per user/machine                                │
+│                                                              │
+│  .repo-cloak-map.json                                        │
+│  ├── Source paths: ENCRYPTED                                 │
+│  ├── Original keywords: ENCRYPTED                            │
+│  ├── Replacement keywords: VISIBLE (safe values)             │
+│  └── Cloaked file paths: VISIBLE (already anonymized)        │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+The mapping file can be safely committed or shared because:
+- The encrypted fields cannot be decrypted without the user's secret key
+- The visible fields contain only anonymized, non-sensitive values
+- Even if an attacker obtains the mapping, they cannot determine original values
+
+If a user loses their secret key (machine reinstall, key deletion), the tool prompts for manual keyword entry during restoration. Since developers know their own codebase, they can provide the original terms when needed.
+
+### 5. Incremental Extraction Support
+
+Real-world usage rarely involves a single extraction. As AI assistants request additional context, developers need to pull more files. Repo-Cloak handles this with intelligent merging:
+
+```
+Pull #1:  BookService.cs    → Mapping tracks 1 file
+Pull #2:  UserService.cs      → Mapping tracks 2 files (merged)
+Pull #3:  Same files again    → Deduplication, no duplicates added
+```
+
+Each pull is tracked in a history log:
+```json
+{
+  "pullHistory": [
+    { "timestamp": "2024-01-15T10:30:00Z", "filesAdded": 5, "totalFiles": 5 },
+    { "timestamp": "2024-01-15T14:22:00Z", "filesAdded": 3, "totalFiles": 8 }
+  ]
+}
+```
+
+---
+
+## The Workflow in Practice
+
+### Step 1: Pull Files from Your Repository
+
+```bash
+repo-cloak pull
+```
+
+The interactive interface guides you through:
+1. Selecting a source directory (your project)
+2. Choosing specific files via the tree selector
+3. Defining keyword replacements (e.g., "XCorp" to "Acme")
+4. Specifying an output directory
+
+### Step 2: Work with AI Assistants
+
+Open the cloaked workspace in your preferred AI-enabled IDE. The anonymized code is syntactically valid and maintains all structural relationships. AI assistants can:
+- Analyze patterns and suggest improvements
+- Debug issues with full context
+- Generate new code that follows your conventions
+- Refactor existing implementations
+
+### Step 3: Push Changes Back
+
+```bash
+repo-cloak push
+```
+
+The tool automatically:
+1. Locates the mapping file in the cloaked directory
+2. Decrypts the mapping using your secret key
+3. Reverses all anonymization in both content and file paths
+4. Copies modified files back to the original repository
+
+---
+
+## Security Considerations
+
+### What Gets Protected
+
+| Element | Protection Method |
+|---------|------------------|
+| File content keywords | Case-preserving replacement |
+| Folder names | Path anonymization |
+| File names | Path anonymization |
+| Original keywords in mapping | AES-256-GCM encryption |
+| Source directory path | AES-256-GCM encryption |
+| Original file paths | AES-256-GCM encryption |
+
+### What Remains Visible
+
+| Element | Reason |
+|---------|--------|
+| Replacement keywords | Already anonymized, safe to expose |
+| Cloaked file paths | Already anonymized, safe to expose |
+| Code structure and logic | Required for AI assistance |
+
+### Threat Model
+
+Repo-Cloak protects against:
+- **Accidental exposure**: AI tools cannot see original company names, project identifiers, or sensitive naming
+- **Mapping file leakage**: Even if the mapping file is exposed, encryption prevents recovery of original values
+- **Third-party logging**: Cloud-based AI services only receive anonymized content
+
+Repo-Cloak does not protect against:
+- **Logic inference**: Sufficiently advanced analysis might infer business purpose from code structure
+- **Unique patterns**: Highly distinctive algorithms may be recognizable regardless of naming
+- **Malicious insiders**: Users with the secret key have full access
+
+### User Responsibility
+
+Repo-Cloak is a tool that assists with anonymization, but it does not replace sound judgment. **The responsibility for selecting appropriate files lies entirely with the user.**
+
+Before extracting any code, you should:
+
+1. **Review your organization's policies**: Most companies have guidelines about sharing code with external tools or AI services. Ensure you understand and comply with these policies before using Repo-Cloak or any similar tool.
+
+2. **Avoid proprietary algorithms**: Even with anonymized naming, core business logic, patented algorithms, or trade secrets should not be extracted. If an algorithm is proprietary, changing variable names does not make it safe to share.
+
+3. **Verify file contents before extraction**: The selective file picker exists precisely so you can make informed decisions. Do not blindly select entire directories without understanding what they contain.
+
+4. **Cross-check with your team**: When in doubt, consult with your security team, legal department, or engineering leadership. A quick conversation can prevent significant issues.
+
+5. **Use the minimum necessary context**: Extract only what the AI assistant needs to help you. More files means more exposure, even if that exposure is anonymized.
+
+This tool provides a layer of protection, but no tool can substitute for thoughtful decision-making about what code should or should not leave your environment.
+
+---
+
+## Installation and Usage
+
+```bash
+# Install globally via npm
+npm install -g repo-cloak-cli
+
+# Run the interactive interface
+repo-cloak
+
+# Or use specific commands
+repo-cloak pull --source ./my-project --dest ./cloaked-output
+repo-cloak push --source ./cloaked-output --dest ./my-project
+```
+
+---
+
+## Technical Architecture
+
+```
+repo-cloak/
+├── bin/
+│   └── repo-cloak.js          # CLI entry point
+├── src/
+│   ├── commands/
+│   │   ├── pull.js            # Extraction and anonymization
+│   │   └── push.js            # Restoration and de-anonymization
+│   ├── core/
+│   │   ├── anonymizer.js      # Case-preserving replacement engine
+│   │   ├── copier.js          # File operations with transformation
+│   │   ├── crypto.js          # AES-256-GCM encryption
+│   │   ├── mapper.js          # Mapping file management
+│   │   └── scanner.js         # File discovery and filtering
+│   └── ui/
+│       ├── fileSelector.js    # Interactive tree selector
+│       └── prompts.js         # User input handling
+└── tests/
+    ├── anonymizer.test.js     # 13 test cases
+    ├── copier.test.js         # 5 test cases
+    ├── crypto.test.js         # 9 test cases
+    ├── mapper.test.js         # 10 test cases
+    └── scanner.test.js        # 8 test cases
+```
+
+The project includes 45 unit tests covering all core functionality, ensuring reliability for production use.
+
+---
+
+## Conclusion
+
+The tension between leveraging AI tools and maintaining code security is real, but it does not have to be a binary choice. Repo-Cloak provides a practical middle ground: keep your proprietary information private while still benefiting from the productivity gains of modern AI coding assistants.
+
+By implementing selective extraction, intelligent anonymization, and encrypted reversible mappings, developers can confidently use tools like Cursor, GitHub Copilot, or any AI coding assistant without exposing sensitive business logic or company-specific information.
+
+The tool is open-source and available on npm. Contributions, feedback, and feature requests are welcome.
+
+---
+
+**Repository**: [github.com/iamshz97/repo-cloak](https://github.com/iamshz97/repo-cloak)
+
+**npm**: `npm install -g repo-cloak-cli`
+
+---
+
+*Shazni Shiraz is a software engineer focused on developer tooling and enterprise software architecture.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-cloak-cli",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "🎭 Selectively extract and anonymize files from repositories. Perfect for sharing code with AI agents without exposing proprietary details.",
   "main": "src/index.js",
   "type": "module",
@@ -10,7 +10,8 @@
   },
   "scripts": {
     "start": "node bin/repo-cloak.js",
-    "test": "node --test",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "lint": "eslint src/"
   },
   "keywords": [
@@ -43,5 +44,8 @@
     "glob": "^10.3.10",
     "inquirer": "^9.2.12",
     "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
   }
 }

package/src/commands/pull.js

@@ -1,10 +1,12 @@
 /**
  * Pull Command
  * Extract files and anonymize sensitive information
+ * Supports quick-add mode when pulling to existing cloaked directory
  */
 
 import ora from 'ora';
 import chalk from 'chalk';
+import inquirer from 'inquirer';
 import { existsSync, mkdirSync } from 'fs';
 import { resolve, relative } from 'path';
 
@@ -13,29 +15,117 @@ import {
     promptSourceDirectory,
     promptDestinationDirectory,
     promptKeywordReplacements,
-    showSummaryAndConfirm
+    showSummaryAndConfirm,
+    confirmAction
 } from '../ui/prompts.js';
 import { showSuccess, showError, showInfo } from '../ui/banner.js';
 import { getAllFiles } from '../core/scanner.js';
 import { copyFiles } from '../core/copier.js';
 import { createAnonymizer } from '../core/anonymizer.js';
-import { createMapping, saveMapping } from '../core/mapper.js';
+import { createMapping, saveMapping, loadRawMapping, mergeMapping, hasMapping, decryptMapping } from '../core/mapper.js';
+import { getOrCreateSecret, hasSecret, decryptReplacements } from '../core/crypto.js';
 
 export async function pull(options = {}) {
     try {
-        // Step 1: Get source directory
-        const sourceDir = options.source
-            ? resolve(options.source)
-            : await promptSourceDirectory();
+        // Step 1: Get destination directory first (to check for existing mapping)
+        let destDir = options.dest
+            ? resolve(options.dest)
+            : await promptDestinationDirectory();
+
+        let existingMapping = null;
+        let existingReplacements = [];
+        let sourceDir = null;
+        let isQuickAdd = false;
+
+        // Step 2: Check for existing mapping in destination
+        if (existsSync(destDir) && hasMapping(destDir)) {
+            existingMapping = loadRawMapping(destDir);
+
+            console.log(chalk.cyan('\n   Existing cloaked directory detected'));
+            console.log(chalk.dim(`   Created: ${existingMapping.timestamp}`));
+            console.log(chalk.dim(`   Files: ${existingMapping.stats?.totalFiles || existingMapping.files?.length || 0}`));
+            console.log(chalk.dim(`   Replacements: ${existingMapping.replacements?.length || 0}\n`));
+
+            // Ask if they want quick-add mode
+            const { mode } = await inquirer.prompt([
+                {
+                    type: 'list',
+                    name: 'mode',
+                    message: 'What would you like to do?',
+                    choices: [
+                        {
+                            name: 'Quick Add - Use existing replacements and add more files',
+                            value: 'quick'
+                        },
+                        {
+                            name: 'Add More Replacements - Add files with additional anonymization',
+                            value: 'extend'
+                        },
+                        {
+                            name: 'Fresh Start - Choose new destination',
+                            value: 'fresh'
+                        }
+                    ]
+                }
+            ]);
+
+            if (mode === 'fresh') {
+                // Get a new destination
+                destDir = await promptDestinationDirectory();
+                existingMapping = null;
+            } else {
+                isQuickAdd = mode === 'quick';
+
+                // Decrypt existing replacements
+                if (existingMapping.encrypted && hasSecret()) {
+                    const secret = getOrCreateSecret();
+                    try {
+                        const decrypted = decryptReplacements(existingMapping.replacements || [], secret);
+                        existingReplacements = decrypted.filter(r => !r.decryptFailed);
+
+                        if (existingReplacements.length > 0) {
+                            console.log(chalk.green('   Existing replacements loaded:\n'));
+                            existingReplacements.forEach(r => {
+                                console.log(chalk.dim(`      "${r.original}" → "${r.replacement}"`));
+                            });
+                            console.log('');
+                        }
+                    } catch (err) {
+                        console.log(chalk.yellow('   Could not decrypt existing replacements'));
+                    }
+                }
+
+                // Try to get original source path
+                if (existingMapping.encrypted && hasSecret()) {
+                    const secret = getOrCreateSecret();
+                    try {
+                        const decrypted = decryptMapping(existingMapping, secret);
+                        if (decrypted.source?.path && existsSync(decrypted.source.path)) {
+                            sourceDir = decrypted.source.path;
+                            console.log(chalk.dim(`   Source: ${sourceDir}\n`));
+                        }
+                    } catch (err) {
+                        // Source path couldn't be decrypted, will prompt
+                    }
+                }
+            }
+        }
+
+        // Step 3: Get source directory if not already determined
+        if (!sourceDir) {
+            sourceDir = options.source
+                ? resolve(options.source)
+                : await promptSourceDirectory();
+        }
 
         if (!existsSync(sourceDir)) {
             showError(`Source directory does not exist: ${sourceDir}`);
             return;
         }
 
-        console.log(chalk.dim(`\n   Source: ${sourceDir}\n`));
+        console.log(chalk.dim(`   Source: ${sourceDir}\n`));
 
-        // Step 2: Select files
+        // Step 4: Select files
         const selectedFiles = await selectFiles(sourceDir);
 
         if (selectedFiles.length === 0) {
@@ -45,15 +135,40 @@ export async function pull(options = {}) {
 
         console.log(chalk.green(`\n✓ Selected ${selectedFiles.length} files\n`));
 
-        // Step 3: Get destination directory
-        const destDir = options.dest
-            ? resolve(options.dest)
-            : await promptDestinationDirectory();
+        // Step 5: Handle replacements based on mode
+        let replacements = [...existingReplacements];
+
+        if (isQuickAdd) {
+            // Quick add mode - just use existing replacements
+            if (replacements.length > 0) {
+                console.log(chalk.cyan('   Using existing replacements (quick-add mode)\n'));
+            }
+
+            // Ask if they want to add more
+            const { addMore } = await inquirer.prompt([
+                {
+                    type: 'confirm',
+                    name: 'addMore',
+                    message: 'Add additional replacements?',
+                    default: false
+                }
+            ]);
 
-        // Step 4: Get keyword replacements
-        const replacements = await promptKeywordReplacements();
+            if (addMore) {
+                const additionalReplacements = await promptKeywordReplacements();
+                replacements = [...replacements, ...additionalReplacements];
+            }
+        } else if (existingMapping) {
+            // Extend mode - prompt for more replacements to add to existing
+            console.log(chalk.cyan('\n   Add more replacements (existing will be preserved):\n'));
+            const additionalReplacements = await promptKeywordReplacements();
+            replacements = [...replacements, ...additionalReplacements];
+        } else {
+            // Fresh start - prompt for all replacements
+            replacements = await promptKeywordReplacements();
+        }
 
-        // Step 5: Confirm
+        // Step 6: Confirm
         const confirmed = await showSummaryAndConfirm(
             selectedFiles.length,
             destDir,
@@ -65,13 +180,13 @@ export async function pull(options = {}) {
             return;
         }
 
-        // Step 6: Create destination directory
+        // Step 7: Create destination directory
         if (!existsSync(destDir)) {
             mkdirSync(destDir, { recursive: true });
             console.log(chalk.dim(`   Created directory: ${destDir}`));
         }
 
-        // Step 7: Copy and anonymize files
+        // Step 8: Copy and anonymize files
         const spinner = ora('Copying and anonymizing files...').start();
 
         const anonymizer = createAnonymizer(replacements);
@@ -106,33 +221,58 @@ export async function pull(options = {}) {
             });
         }
 
-        // Step 8: Save mapping file with original->anonymized path tracking
-        const mapping = createMapping({
-            sourceDir,
-            destDir,
-            replacements,
-            files: selectedFiles.map(f => {
-                const originalPath = relative(sourceDir, f);
-                // Apply same anonymization logic used in copier
-                let anonymizedPath = originalPath;
-                for (const { original, replacement } of replacements) {
-                    const regex = new RegExp(original.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
-                    anonymizedPath = anonymizedPath.replace(regex, replacement);
-                }
-                return {
-                    original: originalPath,
-                    cloaked: anonymizedPath
-                };
-            })
+        // Step 9: Prepare new file mappings
+        const newFiles = selectedFiles.map(f => {
+            const originalPath = relative(sourceDir, f);
+            let anonymizedPath = originalPath;
+            for (const { original, replacement } of replacements) {
+                const regex = new RegExp(original.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
+                anonymizedPath = anonymizedPath.replace(regex, replacement);
+            }
+            return {
+                original: originalPath,
+                cloaked: anonymizedPath
+            };
         });
 
+        // Step 10: Check for existing mapping and merge if found
+        let mapping;
+        let isIncremental = false;
+
+        if (existingMapping) {
+            // Merge with existing
+            mapping = mergeMapping(existingMapping, newFiles);
+            isIncremental = true;
+            console.log(chalk.cyan(`   🔄 Merged with existing mapping`));
+        } else {
+            // Create new mapping
+            mapping = createMapping({
+                sourceDir,
+                destDir,
+                replacements,
+                files: newFiles
+            });
+        }
+
         const mapPath = saveMapping(destDir, mapping);
-        console.log(chalk.dim(`   📋 Mapping saved: ${mapPath}`));
+
+        if (isIncremental) {
+            const history = mapping.pullHistory || [];
+            const lastPull = history[history.length - 1];
+            console.log(chalk.dim(`   📋 Mapping updated: ${lastPull?.filesAdded || 0} new files added (total: ${mapping.stats?.totalFiles})`));
+        } else {
+            console.log(chalk.dim(`   📋 Mapping saved: ${mapPath}`));
+        }
 
         // Done!
         showSuccess('Extraction complete!');
         console.log(chalk.white(`   📂 Files extracted to: ${chalk.cyan.bold(destDir)}`));
-        console.log(chalk.dim(`\n   To restore later, run: ${chalk.white('repo-cloak push')}\n`));
+
+        if (isQuickAdd || isIncremental) {
+            console.log(chalk.dim(`\n   Tip: Run again to add more files quickly\n`));
+        } else {
+            console.log(chalk.dim(`\n   To restore later, run: ${chalk.white('repo-cloak push')}\n`));
+        }
 
     } catch (error) {
         showError(`Pull failed: ${error.message}`);

package/src/core/mapper.js

@@ -177,3 +177,59 @@ export function updateMapping(destDir, updates) {
     writeFileSync(mapPath, JSON.stringify(updated, null, 2), 'utf-8');
     return updated;
 }
+
+/**
+ * Load existing raw mapping (without decryption) for merging
+ */
+export function loadRawMapping(cloakedDir) {
+    const mapPath = join(cloakedDir, MAP_FILENAME);
+
+    if (!existsSync(mapPath)) {
+        return null;
+    }
+
+    try {
+        const content = readFileSync(mapPath, 'utf-8');
+        return JSON.parse(content);
+    } catch (error) {
+        return null;
+    }
+}
+
+/**
+ * Merge new files into existing mapping (for incremental pulls)
+ */
+export function mergeMapping(existingMapping, newFiles) {
+    // Get existing file paths for deduplication
+    const existingPaths = new Set(
+        (existingMapping.files || []).map(f => f.cloaked)
+    );
+
+    // Filter out files that already exist (avoid duplicates)
+    const uniqueNewFiles = newFiles.filter(f => !existingPaths.has(f.cloaked));
+
+    // Merge files
+    const mergedFiles = [
+        ...(existingMapping.files || []),
+        ...uniqueNewFiles
+    ];
+
+    // Track pull history
+    const pullHistory = existingMapping.pullHistory || [];
+    pullHistory.push({
+        timestamp: new Date().toISOString(),
+        filesAdded: uniqueNewFiles.length,
+        totalFiles: mergedFiles.length
+    });
+
+    return {
+        ...existingMapping,
+        files: mergedFiles,
+        pullHistory,
+        stats: {
+            ...existingMapping.stats,
+            totalFiles: mergedFiles.length
+        },
+        updatedAt: new Date().toISOString()
+    };
+}

package/tests/anonymizer.test.js

@@ -0,0 +1,127 @@
+/**
+ * Anonymizer Tests
+ */
+
+import { describe, it, expect } from 'vitest';
+import { createAnonymizer, createDeanonymizer } from '../src/core/anonymizer.js';
+
+describe('Anonymizer', () => {
+    describe('createAnonymizer', () => {
+        it('should replace exact matches', () => {
+            const anonymizer = createAnonymizer([
+                { original: 'Cuviva', replacement: 'ABCCompany' }
+            ]);
+
+            // Title case input -> Title case output (first letter upper, rest lower)
+            expect(anonymizer('Hello Cuviva world')).toBe('Hello Abccompany world');
+        });
+
+        it('should handle all uppercase', () => {
+            const anonymizer = createAnonymizer([
+                { original: 'Cuviva', replacement: 'ABCCompany' }
+            ]);
+
+            expect(anonymizer('CUVIVA is great')).toBe('ABCCOMPANY is great');
+        });
+
+        it('should handle all lowercase', () => {
+            const anonymizer = createAnonymizer([
+                { original: 'Cuviva', replacement: 'ABCCompany' }
+            ]);
+
+            expect(anonymizer('cuviva is lower')).toBe('abccompany is lower');
+        });
+
+        it('should handle multiple replacements', () => {
+            const anonymizer = createAnonymizer([
+                { original: 'Cuviva', replacement: 'ABCCompany' },
+                { original: 'Frontend', replacement: 'Client' }
+            ]);
+
+            // Both are Title case -> first upper + rest lower
+            expect(anonymizer('Cuviva Frontend API')).toBe('Abccompany Client API');
+        });
+
+        it('should handle empty replacements', () => {
+            const anonymizer = createAnonymizer([]);
+            expect(anonymizer('Hello world')).toBe('Hello world');
+        });
+
+        it('should handle special regex characters in original', () => {
+            const anonymizer = createAnonymizer([
+                { original: 'test.value', replacement: 'replaced' }
+            ]);
+
+            // Title case preservation
+            expect(anonymizer('This is Test.value here')).toBe('This is Replaced here');
+        });
+
+        it('should handle null or undefined replacements', () => {
+            const anonymizer = createAnonymizer(null);
+            expect(anonymizer('Hello world')).toBe('Hello world');
+        });
+    });
+
+    describe('createDeanonymizer', () => {
+        it('should reverse the anonymization', () => {
+            const replacements = [
+                { original: 'Cuviva', replacement: 'ABCCompany' }
+            ];
+
+            const deanonymizer = createDeanonymizer(replacements);
+
+            // ABCCompany (Title case) -> Cuviva (Title case: first upper + rest lower)
+            expect(deanonymizer('Hello ABCCompany world')).toBe('Hello Cuviva world');
+        });
+
+        it('should handle multiple replacements in reverse', () => {
+            const replacements = [
+                { original: 'Cuviva', replacement: 'ABCCompany' },
+                { original: 'API', replacement: 'Service' }
+            ];
+
+            const deanonymizer = createDeanonymizer(replacements);
+
+            // Title case -> Title case for both
+            expect(deanonymizer('ABCCompany Service')).toBe('Cuviva Api');
+        });
+
+        it('should handle uppercase in reverse', () => {
+            const replacements = [
+                { original: 'Cuviva', replacement: 'ABCCompany' }
+            ];
+
+            const deanonymizer = createDeanonymizer(replacements);
+
+            expect(deanonymizer('ABCCOMPANY')).toBe('CUVIVA');
+        });
+
+        it('should handle lowercase in reverse', () => {
+            const replacements = [
+                { original: 'Cuviva', replacement: 'ABCCompany' }
+            ];
+
+            const deanonymizer = createDeanonymizer(replacements);
+
+            expect(deanonymizer('abccompany')).toBe('cuviva');
+        });
+    });
+});
+
+describe('Case transformation', () => {
+    it('should preserve all uppercase', () => {
+        const anonymizer = createAnonymizer([
+            { original: 'SECRET', replacement: 'PUBLIC' }
+        ]);
+
+        expect(anonymizer('This is SECRET data')).toBe('This is PUBLIC data');
+    });
+
+    it('should preserve all lowercase', () => {
+        const anonymizer = createAnonymizer([
+            { original: 'secret', replacement: 'public' }
+        ]);
+
+        expect(anonymizer('this is secret data')).toBe('this is public data');
+    });
+});

package/tests/copier.test.js

@@ -0,0 +1,94 @@
+/**
+ * Copier Tests
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { copyFile, copyFileWithTransform } from '../src/core/copier.js';
+import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+describe('Copier Module', () => {
+    let testDir;
+    let sourceDir;
+    let destDir;
+
+    beforeEach(() => {
+        testDir = join(tmpdir(), `repo-cloak-copier-test-${Date.now()}`);
+        sourceDir = join(testDir, 'source');
+        destDir = join(testDir, 'dest');
+        mkdirSync(sourceDir, { recursive: true });
+        mkdirSync(destDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        if (existsSync(testDir)) {
+            rmSync(testDir, { recursive: true, force: true });
+        }
+    });
+
+    describe('copyFile', () => {
+        it('should copy a file to destination', () => {
+            const sourceFile = join(sourceDir, 'test.txt');
+            const destFile = join(destDir, 'test.txt');
+
+            writeFileSync(sourceFile, 'Hello World');
+            copyFile(sourceFile, destFile);
+
+            expect(existsSync(destFile)).toBe(true);
+            expect(readFileSync(destFile, 'utf-8')).toBe('Hello World');
+        });
+
+        it('should create nested directories', () => {
+            const sourceFile = join(sourceDir, 'test.txt');
+            const destFile = join(destDir, 'nested', 'deep', 'test.txt');
+
+            writeFileSync(sourceFile, 'Content');
+            copyFile(sourceFile, destFile);
+
+            expect(existsSync(destFile)).toBe(true);
+        });
+    });
+
+    describe('copyFileWithTransform', () => {
+        it('should transform content during copy', () => {
+            const sourceFile = join(sourceDir, 'code.js');
+            const destFile = join(destDir, 'code.js');
+
+            writeFileSync(sourceFile, 'const company = "Cuviva";');
+
+            const transform = (content) => content.replace(/Cuviva/g, 'ABCCompany');
+            const result = copyFileWithTransform(sourceFile, destFile, transform);
+
+            expect(result.transformed).toBe(true);
+            expect(readFileSync(destFile, 'utf-8')).toBe('const company = "ABCCompany";');
+        });
+
+        it('should report no transformation when content unchanged', () => {
+            const sourceFile = join(sourceDir, 'code.js');
+            const destFile = join(destDir, 'code.js');
+
+            writeFileSync(sourceFile, 'const x = 1;');
+
+            const transform = (content) => content.replace(/Cuviva/g, 'ABCCompany');
+            const result = copyFileWithTransform(sourceFile, destFile, transform);
+
+            expect(result.transformed).toBe(false);
+        });
+
+        it('should handle binary files by copying as-is', () => {
+            const sourceFile = join(sourceDir, 'image.png');
+            const destFile = join(destDir, 'image.png');
+
+            // Create a simple binary-like file
+            const buffer = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x00]);
+            writeFileSync(sourceFile, buffer);
+
+            const transform = (content) => content.replace(/test/g, 'replaced');
+            const result = copyFileWithTransform(sourceFile, destFile, transform);
+
+            expect(result.transformed).toBe(false);
+            expect(existsSync(destFile)).toBe(true);
+        });
+    });
+});

package/tests/crypto.test.js

@@ -0,0 +1,106 @@
+/**
+ * Crypto Tests
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { encrypt, decrypt, encryptReplacements, decryptReplacements } from '../src/core/crypto.js';
+import { existsSync, rmSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+describe('Crypto Module', () => {
+    const testSecret = 'test-secret-key-for-unit-tests-1234567890';
+
+    describe('encrypt/decrypt', () => {
+        it('should encrypt and decrypt a string', () => {
+            const original = 'Hello World';
+            const encrypted = encrypt(original, testSecret);
+            const decrypted = decrypt(encrypted, testSecret);
+
+            expect(decrypted).toBe(original);
+        });
+
+        it('should produce different encrypted output each time (random IV)', () => {
+            const original = 'Same input';
+            const encrypted1 = encrypt(original, testSecret);
+            const encrypted2 = encrypt(original, testSecret);
+
+            expect(encrypted1).not.toBe(encrypted2);
+        });
+
+        it('should return null for wrong secret', () => {
+            const original = 'Secret message';
+            const encrypted = encrypt(original, testSecret);
+            const decrypted = decrypt(encrypted, 'wrong-secret');
+
+            expect(decrypted).toBeNull();
+        });
+
+        it('should handle special characters', () => {
+            const original = 'Special: @#$%^&*()_+ 日本語 🎭';
+            const encrypted = encrypt(original, testSecret);
+            const decrypted = decrypt(encrypted, testSecret);
+
+            expect(decrypted).toBe(original);
+        });
+
+        it('should handle empty string or return null for empty', () => {
+            const original = '';
+            const encrypted = encrypt(original, testSecret);
+            const decrypted = decrypt(encrypted, testSecret);
+
+            // Empty string may return empty or null depending on cipher
+            expect(decrypted === '' || decrypted === null).toBe(true);
+        });
+
+        it('should handle long strings', () => {
+            const original = 'A'.repeat(10000);
+            const encrypted = encrypt(original, testSecret);
+            const decrypted = decrypt(encrypted, testSecret);
+
+            expect(decrypted).toBe(original);
+        });
+    });
+
+    describe('encryptReplacements/decryptReplacements', () => {
+        it('should encrypt only the original field', () => {
+            const replacements = [
+                { original: 'Cuviva', replacement: 'ABCCompany' },
+                { original: 'Secret', replacement: 'Public' }
+            ];
+
+            const encrypted = encryptReplacements(replacements, testSecret);
+
+            // Replacement should still be visible
+            expect(encrypted[0].replacement).toBe('ABCCompany');
+            expect(encrypted[1].replacement).toBe('Public');
+
+            // Original should be encrypted (contains colons from format)
+            expect(encrypted[0].original).toContain(':');
+            expect(encrypted[0].encrypted).toBe(true);
+        });
+
+        it('should decrypt back to original', () => {
+            const replacements = [
+                { original: 'Cuviva', replacement: 'ABCCompany' }
+            ];
+
+            const encrypted = encryptReplacements(replacements, testSecret);
+            const decrypted = decryptReplacements(encrypted, testSecret);
+
+            expect(decrypted[0].original).toBe('Cuviva');
+            expect(decrypted[0].replacement).toBe('ABCCompany');
+        });
+
+        it('should mark failed decryptions', () => {
+            const replacements = [
+                { original: 'Test', replacement: 'Demo' }
+            ];
+
+            const encrypted = encryptReplacements(replacements, testSecret);
+            const decrypted = decryptReplacements(encrypted, 'wrong-secret');
+
+            expect(decrypted[0].decryptFailed).toBe(true);
+        });
+    });
+});

package/tests/mapper.test.js

@@ -0,0 +1,166 @@
+/**
+ * Mapper Tests
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+    createMapping,
+    saveMapping,
+    loadRawMapping,
+    mergeMapping,
+    hasMapping
+} from '../src/core/mapper.js';
+import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+describe('Mapper Module', () => {
+    let testDir;
+
+    beforeEach(() => {
+        testDir = join(tmpdir(), `repo-cloak-test-${Date.now()}`);
+        mkdirSync(testDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        if (existsSync(testDir)) {
+            rmSync(testDir, { recursive: true, force: true });
+        }
+    });
+
+    describe('createMapping', () => {
+        it('should create a valid mapping object', () => {
+            const mapping = createMapping({
+                sourceDir: '/path/to/source',
+                destDir: '/path/to/dest',
+                replacements: [{ original: 'Test', replacement: 'Demo' }],
+                files: [{ original: 'file.js', cloaked: 'file.js' }]
+            });
+
+            expect(mapping.version).toBe('1.1.0');
+            expect(mapping.tool).toBe('repo-cloak');
+            expect(mapping.encrypted).toBe(true);
+            expect(mapping.files).toHaveLength(1);
+            expect(mapping.stats.totalFiles).toBe(1);
+        });
+
+        it('should encrypt sensitive data', () => {
+            const mapping = createMapping({
+                sourceDir: '/secret/path',
+                destDir: '/dest/path',
+                replacements: [{ original: 'SecretWord', replacement: 'Public' }],
+                files: [{ original: 'secret.js', cloaked: 'public.js' }]
+            });
+
+            // Source path should be encrypted (contains :)
+            expect(mapping.source.path).toContain(':');
+            // Replacements original should be encrypted
+            expect(mapping.replacements[0].original).toContain(':');
+            expect(mapping.replacements[0].encrypted).toBe(true);
+        });
+    });
+
+    describe('saveMapping / loadRawMapping', () => {
+        it('should save and load mapping file', () => {
+            const mapping = {
+                version: '1.0.0',
+                files: [{ original: 'a.js', cloaked: 'b.js' }]
+            };
+
+            saveMapping(testDir, mapping);
+
+            expect(hasMapping(testDir)).toBe(true);
+
+            const loaded = loadRawMapping(testDir);
+            expect(loaded.version).toBe('1.0.0');
+            expect(loaded.files).toHaveLength(1);
+        });
+
+        it('should return null for non-existent mapping', () => {
+            const loaded = loadRawMapping('/non/existent/path');
+            expect(loaded).toBeNull();
+        });
+    });
+
+    describe('hasMapping', () => {
+        it('should return true when mapping exists', () => {
+            writeFileSync(join(testDir, '.repo-cloak-map.json'), '{}');
+            expect(hasMapping(testDir)).toBe(true);
+        });
+
+        it('should return false when mapping does not exist', () => {
+            expect(hasMapping(testDir)).toBe(false);
+        });
+    });
+
+    describe('mergeMapping', () => {
+        it('should merge new files with existing mapping', () => {
+            const existing = {
+                version: '1.0.0',
+                files: [
+                    { original: 'a.js', cloaked: 'a.js' },
+                    { original: 'b.js', cloaked: 'b.js' }
+                ],
+                stats: { totalFiles: 2 }
+            };
+
+            const newFiles = [
+                { original: 'c.js', cloaked: 'c.js' },
+                { original: 'd.js', cloaked: 'd.js' }
+            ];
+
+            const merged = mergeMapping(existing, newFiles);
+
+            expect(merged.files).toHaveLength(4);
+            expect(merged.stats.totalFiles).toBe(4);
+        });
+
+        it('should avoid duplicate files', () => {
+            const existing = {
+                version: '1.0.0',
+                files: [
+                    { original: 'a.js', cloaked: 'a.js' },
+                    { original: 'b.js', cloaked: 'b.js' }
+                ],
+                stats: { totalFiles: 2 }
+            };
+
+            const newFiles = [
+                { original: 'b.js', cloaked: 'b.js' },  // Duplicate
+                { original: 'c.js', cloaked: 'c.js' }   // New
+            ];
+
+            const merged = mergeMapping(existing, newFiles);
+
+            expect(merged.files).toHaveLength(3); // Not 4
+            expect(merged.stats.totalFiles).toBe(3);
+        });
+
+        it('should track pull history', () => {
+            const existing = {
+                version: '1.0.0',
+                files: [],
+                stats: { totalFiles: 0 }
+            };
+
+            const merged = mergeMapping(existing, [{ original: 'a.js', cloaked: 'a.js' }]);
+
+            expect(merged.pullHistory).toHaveLength(1);
+            expect(merged.pullHistory[0].filesAdded).toBe(1);
+            expect(merged.pullHistory[0].timestamp).toBeDefined();
+        });
+
+        it('should append to existing pull history', () => {
+            const existing = {
+                version: '1.0.0',
+                files: [{ original: 'a.js', cloaked: 'a.js' }],
+                stats: { totalFiles: 1 },
+                pullHistory: [{ timestamp: '2024-01-01', filesAdded: 1, totalFiles: 1 }]
+            };
+
+            const merged = mergeMapping(existing, [{ original: 'b.js', cloaked: 'b.js' }]);
+
+            expect(merged.pullHistory).toHaveLength(2);
+        });
+    });
+});

package/tests/scanner.test.js

@@ -0,0 +1,100 @@
+/**
+ * Scanner Tests
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { getAllFiles, isBinaryFile } from '../src/core/scanner.js';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+describe('Scanner Module', () => {
+    let testDir;
+
+    beforeEach(() => {
+        testDir = join(tmpdir(), `repo-cloak-scanner-test-${Date.now()}`);
+        mkdirSync(testDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        if (existsSync(testDir)) {
+            rmSync(testDir, { recursive: true, force: true });
+        }
+    });
+
+    describe('getAllFiles', () => {
+        it('should find all files in directory', () => {
+            writeFileSync(join(testDir, 'a.js'), 'content');
+            writeFileSync(join(testDir, 'b.js'), 'content');
+
+            const files = getAllFiles(testDir);
+
+            expect(files).toHaveLength(2);
+        });
+
+        it('should find files in nested directories', () => {
+            const nestedDir = join(testDir, 'src', 'components');
+            mkdirSync(nestedDir, { recursive: true });
+
+            writeFileSync(join(testDir, 'index.js'), 'content');
+            writeFileSync(join(nestedDir, 'Button.js'), 'content');
+
+            const files = getAllFiles(testDir);
+
+            expect(files).toHaveLength(2);
+        });
+
+        it('should ignore node_modules', () => {
+            const nodeModules = join(testDir, 'node_modules', 'package');
+            mkdirSync(nodeModules, { recursive: true });
+
+            writeFileSync(join(testDir, 'index.js'), 'content');
+            writeFileSync(join(nodeModules, 'index.js'), 'content');
+
+            const files = getAllFiles(testDir);
+
+            expect(files).toHaveLength(1);
+        });
+
+        it('should ignore .git directories', () => {
+            const gitDir = join(testDir, '.git', 'objects');
+            mkdirSync(gitDir, { recursive: true });
+
+            writeFileSync(join(testDir, 'index.js'), 'content');
+            writeFileSync(join(gitDir, 'abc123'), 'content');
+
+            const files = getAllFiles(testDir);
+
+            expect(files).toHaveLength(1);
+        });
+
+        it('should return empty array for empty directory', () => {
+            const files = getAllFiles(testDir);
+            expect(files).toHaveLength(0);
+        });
+    });
+
+    describe('isBinaryFile', () => {
+        it('should detect common binary extensions', () => {
+            expect(isBinaryFile('image.png')).toBe(true);
+            expect(isBinaryFile('image.jpg')).toBe(true);
+            expect(isBinaryFile('archive.zip')).toBe(true);
+            expect(isBinaryFile('doc.pdf')).toBe(true);
+            expect(isBinaryFile('lib.dll')).toBe(true);
+            expect(isBinaryFile('app.exe')).toBe(true);
+        });
+
+        it('should detect text files', () => {
+            expect(isBinaryFile('code.js')).toBe(false);
+            expect(isBinaryFile('style.css')).toBe(false);
+            expect(isBinaryFile('data.json')).toBe(false);
+            expect(isBinaryFile('README.md')).toBe(false);
+            expect(isBinaryFile('code.ts')).toBe(false);
+        });
+
+        it('should handle paths with directories', () => {
+            expect(isBinaryFile('/path/to/image.png')).toBe(true);
+            expect(isBinaryFile('src/components/Button.js')).toBe(false);
+        });
+    });
+});