closed-loop-cli 1.0.0

package/dist/tests/dynamic/skills.test.js

@@ -0,0 +1,88 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const skills_1 = require("../../tools/skills");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+async function run() {
+    console.log("   --> Running Skill Registry tests...");
+    const workspaceRoot = process.cwd();
+    const skillsDir = path.join(workspaceRoot, 'docs', 'skills');
+    const testSkillFile = path.join(skillsDir, 'test-reusable-skill.json');
+    // Clean up previous test files if any
+    if (fs.existsSync(testSkillFile)) {
+        fs.unlinkSync(testSkillFile);
+    }
+    // 1. Mock inputs
+    const mockTask = "Add a checkFileExists utility inside file-tools.ts";
+    const mockDiff = `diff --git a/src/tools/file-tools.ts b/src/tools/file-tools.ts
+index e69de29..b2a8d11 100644
+--- a/src/tools/file-tools.ts
++++ b/src/tools/file-tools.ts
+@@ -1 +1,5 @@
++export function checkFileExists(path: string): boolean {
++  return fs.existsSync(path);
++}
+`;
+    // 2. Extract and Save
+    await (0, skills_1.extractAndSaveSkill)(mockTask, mockDiff);
+    // Find any generated json files
+    if (!fs.existsSync(skillsDir)) {
+        throw new Error("skills directory was not created!");
+    }
+    const files = fs.readdirSync(skillsDir).filter(f => f.endsWith('.json'));
+    if (files.length === 0) {
+        throw new Error("No playbooks were written by extractAndSaveSkill!");
+    }
+    console.log(`   --> Created playbooks: ${files.join(', ')}`);
+    // 3. Summarize
+    const summaries = (0, skills_1.getSkillsSummary)();
+    console.log("   --> Playbook summaries:\n", summaries);
+    if (summaries === 'No custom development skills recorded yet.') {
+        throw new Error("getSkillsSummary returned default empty statement despite files present.");
+    }
+    // Clean up mock output to keep it clean, but wait, keeping it is also fine since git ignores or tracks.
+    // Actually, let's keep one test playbook for verification and delete any temporary ones if needed.
+    // Let's delete the temporary test file.
+    const testFiles = files.filter(f => f.includes('reusable-skill') || f.includes('exists'));
+    for (const f of testFiles) {
+        try {
+            fs.unlinkSync(path.join(skillsDir, f));
+        }
+        catch (e) { }
+    }
+    console.log("   --> Skill Registry tests passed!");
+}

package/dist/tests/run-tests.js

@@ -0,0 +1,294 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const shell_tools_1 = require("../tools/shell-tools");
+const fileTools = __importStar(require("../tools/file-tools"));
+const rulez = __importStar(require("../orchestrator/rulez"));
+const sahoo = __importStar(require("../orchestrator/sahoo-gateway"));
+const repo_map_1 = require("../tools/repo-map");
+const search_tools_1 = require("../tools/search-tools");
+const autogenesis_1 = require("../orchestrator/autogenesis");
+async function runTest(name, fn) {
+    console.log(`\x1b[36m[Test]\x1b[0m Running: ${name}...`);
+    try {
+        await fn();
+        console.log(`\x1b[32m[Pass]\x1b[0m ${name}\n`);
+    }
+    catch (err) {
+        console.error(`\x1b[31m[Fail]\x1b[0m ${name}`);
+        console.error(err.stack || err.message);
+        console.error('');
+        process.exit(1);
+    }
+}
+async function main() {
+    console.log('\x1b[35m=== RUNNING BINARY ASSERTION TESTS ===\x1b[0m\n');
+    // Test 1: TypeScript Compilation
+    await runTest('TypeScript Compilation Check', async () => {
+        console.log('Running tsc compilation...');
+        const result = await (0, shell_tools_1.runCommand)('npx tsc --noEmit');
+        if (result.exitCode !== 0) {
+            throw new Error(`TypeScript compilation failed!\nStdout:\n${result.stdout}\nStderr:\n${result.stderr}`);
+        }
+    });
+    // Test 2: File Tools Read/Write/Edit
+    await runTest('File Tools Functionality', () => {
+        const tempFile = 'temp-test-file.txt';
+        const content = 'Line 1\nTarget content here\nLine 3';
+        // Test Write
+        fileTools.writeFile(tempFile, content);
+        // Test Read
+        const readBack = fileTools.readFile(tempFile);
+        if (readBack !== content) {
+            fs.unlinkSync(tempFile);
+            throw new Error(`Read content did not match written content.`);
+        }
+        // Test Edit (Precise replacement)
+        fileTools.editFile(tempFile, 'Target content here', 'Replaced content');
+        const readAfterEdit = fileTools.readFile(tempFile);
+        const expectedContent = 'Line 1\nReplaced content\nLine 3';
+        // Clean up
+        fs.unlinkSync(tempFile);
+        if (readAfterEdit !== expectedContent) {
+            throw new Error(`Edit did not replace target content correctly. Got:\n${readAfterEdit}`);
+        }
+    });
+    // Test 3: List Directory
+    await runTest('List Directory Tool', () => {
+        const items = fileTools.listDir('.');
+        const hasSrc = items.some(item => item.name === 'src' && item.isDir);
+        const hasPackageJson = items.some(item => item.name === 'package.json' && !item.isDir);
+        if (!hasSrc || !hasPackageJson) {
+            throw new Error(`Directory listing did not return expected workspace files.`);
+        }
+    });
+    // Test 4: Grep Search Tool
+    await runTest('Grep Search Tool', () => {
+        const results = fileTools.grepSearch('AutogenesisEngine', 'src');
+        if (results.length === 0) {
+            throw new Error(`Grep search could not find occurrences of 'AutogenesisEngine' in src directory.`);
+        }
+        const hasIndexMatch = results.some(res => res.filePath.includes('index.ts'));
+        if (!hasIndexMatch) {
+            throw new Error(`Grep search missed match in src/index.ts`);
+        }
+    });
+    // Test 5: RuleZ Policy Engine
+    await runTest('RuleZ Policy Block and Allow Checks', () => {
+        // Unsafe commands
+        const blockCmd = rulez.checkCommand('rm -rf /');
+        if (blockCmd.allowed || blockCmd.exitCode !== 2) {
+            throw new Error(`RuleZ failed to block destructive command 'rm -rf /'.`);
+        }
+        const blockPush = rulez.checkCommand('git push --force');
+        if (blockPush.allowed) {
+            throw new Error('RuleZ failed to block git push --force');
+        }
+        // Safe command
+        const allowCmd = rulez.checkCommand('npm run build');
+        if (!allowCmd.allowed || allowCmd.exitCode !== 0) {
+            throw new Error('RuleZ blocked a safe command npm run build');
+        }
+        // Unsafe file edit (eval)
+        const blockEval = rulez.checkFileEdit('src/test.ts', 'const x = eval("1+1");');
+        if (blockEval.allowed || blockEval.exitCode !== 2) {
+            throw new Error('RuleZ failed to block file edit containing eval().');
+        }
+        // Unsafe file edit (secrets)
+        const blockSecret = rulez.checkFileEdit('src/secrets.ts', 'const token = "tp-sxbionmkvlslw9t9vnjmuwey6a47cwwnfi6jtd8zcq65bnv1";');
+        if (blockSecret.allowed || blockSecret.exitCode !== 2) {
+            throw new Error('RuleZ failed to block file edit containing a MiMo token.');
+        }
+        // Sandbox Path Isolation checks
+        const blockRelativeOutside = rulez.checkFileEdit('../outside.txt', 'hello');
+        if (blockRelativeOutside.allowed || blockRelativeOutside.exitCode !== 2) {
+            throw new Error('RuleZ failed to block file edit outside the workspace (relative path).');
+        }
+        const blockAbsoluteOutside = rulez.checkFileEdit('C:\\Users\\akara\\outside.txt', 'hello');
+        if (blockAbsoluteOutside.allowed || blockAbsoluteOutside.exitCode !== 2) {
+            throw new Error('RuleZ failed to block file edit outside the workspace (absolute path).');
+        }
+        const allowInside = rulez.checkFileEdit('src/tools/math-helper.ts', 'const x = 1;');
+        if (!allowInside.allowed || allowInside.exitCode !== 0) {
+            throw new Error('RuleZ blocked a safe file edit inside the workspace.');
+        }
+    });
+    // Test 6: SAHOO Safeguarding Gateway Checks
+    await runTest('SAHOO Gateway Drifts and Constraints', () => {
+        const beforeCode = 'function calculateSum(a: number, b: number) {\n  return a + b;\n}';
+        const afterCode = 'function calculateSum(a: number, b: number) {\n  return a + b;\n}';
+        // Test identical code drift is 0
+        const semDriftZero = sahoo.calculateSemanticDrift(beforeCode, afterCode);
+        if (semDriftZero !== 0) {
+            throw new Error(`Semantic drift for identical strings should be 0, got ${semDriftZero}`);
+        }
+        // Test different code drift
+        const veryDifferent = 'const value = "hello world";\nconsole.log(value);';
+        const semDriftDiff = sahoo.calculateSemanticDrift(beforeCode, veryDifferent);
+        if (semDriftDiff === 0) {
+            throw new Error('Semantic drift for different strings should be non-zero.');
+        }
+        // Test CPS halts on compilation failure
+        const evalFail = sahoo.evaluateSahoo('src/temp.ts', beforeCode, afterCode, false, true);
+        if (evalFail.passed) {
+            throw new Error('SAHOO should reject changes if compilation failed.');
+        }
+        // Test CPS halts on eval injection
+        const evalWithViolation = sahoo.evaluateSahoo('src/temp.ts', beforeCode, 'const x = eval("5");', true, true);
+        if (evalWithViolation.passed) {
+            throw new Error('SAHOO should reject changes containing eval dynamic code.');
+        }
+    });
+    // Test 7: Repository Map Generation
+    await runTest('Repository Map Generation Check', () => {
+        const repoMap = (0, repo_map_1.generateRepoMap)();
+        if (!repoMap) {
+            throw new Error('Repository map returned empty output.');
+        }
+        if (!repoMap.includes('File: src/orchestrator/meta-agent.ts') && !repoMap.includes('File: src/orchestrator/meta-agent')) {
+            throw new Error('Repository map is missing expected source files.');
+        }
+        if (!repoMap.includes('runSelfImprovingTask')) {
+            throw new Error('Repository map is missing expected signatures like runSelfImprovingTask.');
+        }
+    });
+    // Test 8: Web Search Tool Integration
+    await runTest('Web Search Tool Integration Check', async () => {
+        const results = await (0, search_tools_1.searchWeb)('javascript nodejs');
+        if (!results) {
+            throw new Error('Web search returned empty output.');
+        }
+        // Check if it got actual results or a readable connection error
+        if (!results.includes('results') && !results.includes('Error')) {
+            throw new Error(`Web search output format unexpected: ${results}`);
+        }
+        console.log(`Web search test output snippet: ${results.substring(0, 150)}...`);
+    });
+    // Test 9: Autonomous Refactor Proposal Generation Check
+    await runTest('Autonomous Refactor Proposal Scan Check', async () => {
+        const engine = new autogenesis_1.AutogenesisEngine();
+        const proposal = await engine.getAutonomousRefactorProposal();
+        if (!proposal.targetFile) {
+            throw new Error('Refactoring proposal targetFile is missing.');
+        }
+        if (!proposal.refactorGoal) {
+            throw new Error('Refactoring proposal refactorGoal is missing.');
+        }
+        console.log(`Scan test proposal generated - Target: ${proposal.targetFile} | Goal: ${proposal.refactorGoal}`);
+    });
+    // Test 10: Prompt Benchmarking Score Calculation Check
+    await runTest('Prompt Benchmarking Score Calculation Check', () => {
+        const engine = new autogenesis_1.AutogenesisEngine();
+        // Score with zero parameters should be 0
+        const zeroScore = engine.calculatePromptScore(0, 0);
+        if (zeroScore !== 0) {
+            throw new Error(`Expected zero score for 0 time/tokens, got ${zeroScore}`);
+        }
+        // Score with valid parameters
+        const scoreA = engine.calculatePromptScore(10, 100); // 10*0.4 + 100*0.6 = 64 => 100000/64 = 1562.5
+        const scoreB = engine.calculatePromptScore(20, 200); // 20*0.4 + 200*0.6 = 128 => 100000/128 = 781.25
+        if (Math.abs(scoreA - 1562.5) > 0.01) {
+            throw new Error(`Score A calculation incorrect: got ${scoreA}, expected 1562.5`);
+        }
+        if (Math.abs(scoreB - 781.25) > 0.01) {
+            throw new Error(`Score B calculation incorrect: got ${scoreB}, expected 781.25`);
+        }
+        // A better performance (less time, less tokens) must produce a higher score
+        if (scoreA <= scoreB) {
+            throw new Error(`Expected scoreA (${scoreA}) to be higher than scoreB (${scoreB})`);
+        }
+    });
+    // Test 11: Campbell Regime Write-Protection Policy Check
+    await runTest('Campbell Regime Write-Protection Policy Check', () => {
+        // Attempt edit of rulez.ts
+        const blockRulez = rulez.checkFileEdit('src/orchestrator/rulez.ts', 'const debug = true;');
+        if (blockRulez.allowed || blockRulez.exitCode !== 2) {
+            throw new Error('RuleZ failed to block modifications to rulez.ts safety checker.');
+        }
+        // Attempt edit of sahoo-gateway.ts
+        const blockSahoo = rulez.checkFileEdit('src/orchestrator/sahoo-gateway.ts', 'const bypass = true;');
+        if (blockSahoo.allowed || blockSahoo.exitCode !== 2) {
+            throw new Error('RuleZ failed to block modifications to sahoo-gateway.ts safety gate.');
+        }
+        // Attempt edit of run-tests.ts
+        const blockTests = rulez.checkFileEdit('src/tests/run-tests.ts', 'const pass = true;');
+        if (blockTests.allowed || blockTests.exitCode !== 2) {
+            throw new Error('RuleZ failed to block modifications to run-tests.ts test suite.');
+        }
+        // Attempt edit of package.json
+        const blockPackage = rulez.checkFileEdit('package.json', '{}');
+        if (blockPackage.allowed || blockPackage.exitCode !== 2) {
+            throw new Error('RuleZ failed to block modifications to package.json.');
+        }
+        // Attempt edit of .env
+        const blockEnv = rulez.checkFileEdit('.env', 'API_KEY=xxx');
+        if (blockEnv.allowed || blockEnv.exitCode !== 2) {
+            throw new Error('RuleZ failed to block modifications to .env.');
+        }
+    });
+    // Dynamic User-Created Tests Loading
+    const dynamicTestsDir = path.join(__dirname, 'dynamic');
+    if (fs.existsSync(dynamicTestsDir)) {
+        const files = fs.readdirSync(dynamicTestsDir).filter(f => f.endsWith('.js'));
+        if (files.length > 0) {
+            console.log('\n\x1b[35m=== RUNNING DYNAMIC USER-GENERATED TESTS ===\x1b[0m\n');
+            for (const file of files) {
+                const filePath = path.join(dynamicTestsDir, file);
+                await runTest(`Dynamic Test File: ${file}`, async () => {
+                    const testModule = require(filePath);
+                    if (typeof testModule === 'function') {
+                        await testModule();
+                    }
+                    else if (testModule && typeof testModule.run === 'function') {
+                        await testModule.run();
+                    }
+                    else if (testModule && typeof testModule.default === 'function') {
+                        await testModule.default();
+                    }
+                    else {
+                        throw new Error(`Dynamic test file ${file} does not export a default function, run function, or standard module.exports function.`);
+                    }
+                });
+            }
+        }
+    }
+    console.log('\x1b[32;1m=== ALL BINARY ASSERTION TESTS PASSED ===\x1b[0m');
+}
+main().catch(err => {
+    console.error('Test execution failed:', err);
+    process.exit(1);
+});

package/dist/tools/diff-tools.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFormattedDiff = getFormattedDiff;
+const shell_tools_1 = require("./shell-tools");
+/**
+ * Generates and formats a colorized Git diff for a specific file or the entire workspace.
+ */
+async function getFormattedDiff(filePath) {
+    const target = filePath ? `"${filePath}"` : '';
+    // Use git's native diffing with forced ANSI color codes
+    const cmd = `git diff --color=always ${target}`;
+    const result = await (0, shell_tools_1.runCommand)(cmd);
+    if (result.exitCode !== 0) {
+        return `\x1b[31mError generating diff: ${result.stderr || 'unknown error'}\x1b[0m`;
+    }
+    const output = result.stdout.trim();
+    if (!output) {
+        return '\x1b[90m(No changes detected)\x1b[0m';
+    }
+    // Wrap the diff output inside a visual container box
+    const border = '\x1b[36m┌────────────────────────────────────────────────────────────┐\x1b[0m';
+    const footer = '\x1b[36m└────────────────────────────────────────────────────────────┘\x1b[0m';
+    return `${border}\n\x1b[36m│               CODE CHANGES VISUALIZATION                   │\x1b[0m\n${border}\n${output}\n${footer}`;
+}

package/dist/tools/file-tools.js

@@ -0,0 +1,191 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveWorkspacePath = resolveWorkspacePath;
+exports.readFile = readFile;
+exports.fileExists = fileExists;
+exports.writeFile = writeFile;
+exports.editFile = editFile;
+exports.listDir = listDir;
+exports.grepSearch = grepSearch;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Resolves a path relative to the workspace root and ensures it remains inside the workspace.
+ */
+function resolveWorkspacePath(filePath, workspaceRoot = process.cwd()) {
+    const absolutePath = path.isAbsolute(filePath)
+        ? filePath
+        : path.resolve(workspaceRoot, filePath);
+    // Security check: ensure path does not escape workspace (e.g. using ../..)
+    const relative = path.relative(workspaceRoot, absolutePath);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(`Access denied: Path '${filePath}' is outside the workspace root.`);
+    }
+    return absolutePath;
+}
+/**
+ * Reads the content of a file.
+ */
+function readFile(filePath, workspaceRoot) {
+    const resolved = resolveWorkspacePath(filePath, workspaceRoot);
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    return fs.readFileSync(resolved, 'utf-8');
+}
+/**
+ * Checks if a file exists at the given path.
+ */
+function fileExists(filePath, workspaceRoot) {
+    const resolved = resolveWorkspacePath(filePath, workspaceRoot);
+    return fs.existsSync(resolved);
+}
+/**
+ * Creates or overwrites a file with content.
+ */
+function writeFile(filePath, content, workspaceRoot) {
+    const resolved = resolveWorkspacePath(filePath, workspaceRoot);
+    const dir = path.dirname(resolved);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(resolved, content, 'utf-8');
+}
+function escapeRegExp(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Replaces a target string with replacement content inside a file.
+ * Falls back to fuzzy whitespace-insensitive matching if exact match is not found.
+ */
+function editFile(filePath, targetContent, replacementContent, workspaceRoot) {
+    const resolved = resolveWorkspacePath(filePath, workspaceRoot);
+    const content = readFile(resolved, workspaceRoot);
+    // Detect if file primarily uses CRLF
+    const isCrlf = content.includes('\r\n');
+    // Normalize both content and target contents to LF (\n)
+    const normalizedContent = content.replace(/\r\n/g, '\n');
+    const normalizedTarget = targetContent.replace(/\r\n/g, '\n');
+    const normalizedReplacement = replacementContent.replace(/\r\n/g, '\n');
+    const occurrences = normalizedContent.split(normalizedTarget).length - 1;
+    if (occurrences === 1) {
+        let newContent = normalizedContent.replace(normalizedTarget, normalizedReplacement);
+        if (isCrlf) {
+            newContent = newContent.replace(/\r\n/g, '\n').replace(/\n/g, '\r\n');
+        }
+        fs.writeFileSync(resolved, newContent, 'utf-8');
+        return;
+    }
+    // Exact match failed or is ambiguous. Try fuzzy whitespace regex matching.
+    const tokens = targetContent.trim().split(/\s+/);
+    if (tokens.length === 0 || tokens.join('') === '') {
+        throw new Error(`Target content to edit is empty or whitespace only.`);
+    }
+    const regexStr = tokens.map(tok => escapeRegExp(tok)).join('\\s+');
+    const regex = new RegExp(regexStr, 'g');
+    const matches = content.match(regex);
+    const matchCount = matches ? matches.length : 0;
+    if (matchCount === 0) {
+        throw new Error(`Target content to edit was not found in file: ${filePath} (tried exact and fuzzy whitespace matching).`);
+    }
+    else if (matchCount > 1) {
+        throw new Error(`Target content to edit is ambiguous (found ${matchCount} occurrences fuzzy-matching) in file: ${filePath}. Please provide more context.`);
+    }
+    // Perform the single replace
+    const newContent = content.replace(regex, replacementContent);
+    fs.writeFileSync(resolved, newContent, 'utf-8');
+}
+function listDir(dirPath = '.', workspaceRoot) {
+    const resolved = resolveWorkspacePath(dirPath, workspaceRoot);
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`Directory not found: ${dirPath}`);
+    }
+    const stats = fs.statSync(resolved);
+    if (!stats.isDirectory()) {
+        throw new Error(`Path is not a directory: ${dirPath}`);
+    }
+    const items = fs.readdirSync(resolved);
+    return items.map(name => {
+        const itemPath = path.join(resolved, name);
+        const itemStats = fs.statSync(itemPath);
+        const isDir = itemStats.isDirectory();
+        return {
+            name,
+            isDir,
+            sizeBytes: isDir ? undefined : itemStats.size
+        };
+    });
+}
+function grepSearch(pattern, searchDir = '.', workspaceRoot = process.cwd()) {
+    const resolvedDir = resolveWorkspacePath(searchDir, workspaceRoot);
+    const results = [];
+    const regex = new RegExp(pattern, 'i'); // Case-insensitive match
+    function walk(currentDir) {
+        const files = fs.readdirSync(currentDir);
+        for (const file of files) {
+            const fullPath = path.join(currentDir, file);
+            // Skip node_modules, .git, dist
+            if (file === 'node_modules' || file === '.git' || file === 'dist' || file === '.gemini') {
+                continue;
+            }
+            const stats = fs.statSync(fullPath);
+            if (stats.isDirectory()) {
+                walk(fullPath);
+            }
+            else if (stats.isFile()) {
+                // Only search text-like files
+                const ext = path.extname(file).toLowerCase();
+                if (['.ts', '.js', '.json', '.md', '.txt', '.env', '.html', '.css'].includes(ext)) {
+                    const content = fs.readFileSync(fullPath, 'utf-8');
+                    const lines = content.split('\n');
+                    lines.forEach((line, index) => {
+                        if (regex.test(line)) {
+                            results.push({
+                                filePath: path.relative(workspaceRoot, fullPath).replace(/\\/g, '/'),
+                                lineNumber: index + 1,
+                                lineContent: line.trim()
+                            });
+                        }
+                    });
+                }
+            }
+        }
+    }
+    if (fs.existsSync(resolvedDir)) {
+        walk(resolvedDir);
+    }
+    return results.slice(0, 50); // Cap at 50 results
+}