repo-cloak-cli 1.0.2 → 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.2",
+  "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",

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, loadRawMapping, mergeMapping, hasMapping } 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,7 +221,7 @@ export async function pull(options = {}) {
             });
         }
 
-        // Step 8: Prepare new file mappings
+        // Step 9: Prepare new file mappings
         const newFiles = selectedFiles.map(f => {
             const originalPath = relative(sourceDir, f);
             let anonymizedPath = originalPath;
@@ -120,8 +235,7 @@ export async function pull(options = {}) {
             };
         });
 
-        // Step 9: Check for existing mapping and merge if found
-        const existingMapping = loadRawMapping(destDir);
+        // Step 10: Check for existing mapping and merge if found
         let mapping;
         let isIncremental = false;
 
@@ -129,7 +243,7 @@ export async function pull(options = {}) {
             // Merge with existing
             mapping = mergeMapping(existingMapping, newFiles);
             isIncremental = true;
-            console.log(chalk.cyan(`   🔄 Merged with existing mapping (incremental pull)`));
+            console.log(chalk.cyan(`   🔄 Merged with existing mapping`));
         } else {
             // Create new mapping
             mapping = createMapping({
@@ -153,7 +267,12 @@ export async function pull(options = {}) {
         // 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}`);