@cspeach/cli 0.6.2 → 0.6.4

package/dist/tools/__tests__/agent_run.test.js

@@ -0,0 +1,166 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { agentRunHandler, MAX_AGENT_DEPTH, DEFAULT_MAX_TOKENS, HARD_MAX_TOKENS } from '../subagent/agent_run.js';
+import { makeCtx } from './_helpers.js';
+// runTurn import is hoisted-mocked below so we can inspect the args
+// agent_run handed it without actually invoking the LLM.
+const { runTurnMock } = vi.hoisted(() => ({ runTurnMock: vi.fn() }));
+vi.mock('../../agent/loop.js', () => ({
+    runTurn: runTurnMock,
+}));
+function makeSkillSource(body = '# fake skill body') {
+    return {
+        async getSkillBody(name) {
+            return { name, body, sha256: 'fake', signature: 'fake', signedAt: '2026-05-14T00:00:00Z' };
+        },
+        async listAvailableSkills() { return ['abap-review']; },
+        describe() { return 'fake-source'; },
+    };
+}
+function makeProvider() {
+    return { kind: 'anthropic', name: 'fake-provider' };
+}
+let savedDepth;
+beforeEach(() => {
+    runTurnMock.mockReset();
+    savedDepth = process.env.CSPEACH_AGENT_DEPTH;
+    delete process.env.CSPEACH_AGENT_DEPTH;
+});
+afterEach(() => {
+    if (savedDepth === undefined)
+        delete process.env.CSPEACH_AGENT_DEPTH;
+    else
+        process.env.CSPEACH_AGENT_DEPTH = savedDepth;
+    vi.restoreAllMocks();
+});
+describe('agent_run handler', () => {
+    it('invokes runTurn with a fresh child session and returns the child assistant text', async () => {
+        runTurnMock.mockImplementation(async (params) => {
+            // Simulate the child loop pushing an assistant text block.
+            params.ctx.session.messages.push({
+                role: 'assistant',
+                content: [{ type: 'text', text: 'child says hi' }],
+            });
+        });
+        const ctx = makeCtx(process.cwd(), {
+            provider: makeProvider(),
+            skillSource: makeSkillSource(),
+        });
+        const r = await agentRunHandler({ skill: 'abap-review', task: 'review ZCL_X' }, ctx);
+        expect(r.is_error).toBeFalsy();
+        expect(r.content).toContain('child says hi');
+        expect(runTurnMock).toHaveBeenCalledOnce();
+        const callArgs = runTurnMock.mock.calls[0][0];
+        expect(callArgs.ctx).not.toBe(ctx);
+        expect(callArgs.ctx.session).not.toBe(ctx.session);
+        // I2 fix: chunkEmitter is now a null-sink EventEmitter (not undefined)
+        // so subagent stdout is silently dropped without polluting parent UI.
+        expect(callArgs.chunkEmitter).toBeDefined();
+        expect(callArgs.chunkEmitter.listenerCount?.('chunk') ?? 0).toBe(0);
+        expect(callArgs.ctx.previewHook).toBeUndefined();
+        expect(callArgs.ctx.chunkEmitter).toBeUndefined();
+        expect(callArgs.skill).toBe('abap-review');
+    });
+    it('I1 regression — child session.usage is a clone, not a shared reference', async () => {
+        runTurnMock.mockImplementation(async () => { });
+        const parentSession = {
+            messages: [],
+            usage: { input_tokens: 100, output_tokens: 50, cache_read_input_tokens: 10 },
+        };
+        const ctx = makeCtx(process.cwd(), {
+            provider: makeProvider(),
+            skillSource: makeSkillSource(),
+            session: parentSession,
+        });
+        await agentRunHandler({ skill: 'abap-review', task: 't' }, ctx);
+        const callArgs = runTurnMock.mock.calls[0][0];
+        expect(callArgs.ctx.session.usage).not.toBe(parentSession.usage);
+        expect(callArgs.ctx.session.usage).toEqual(parentSession.usage);
+    });
+    it('rejects when ctx.provider is missing (not wired)', async () => {
+        const ctx = makeCtx(process.cwd(), { skillSource: makeSkillSource() });
+        const r = await agentRunHandler({ skill: 'abap-review', task: 't' }, ctx);
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/provider/i);
+        expect(runTurnMock).not.toHaveBeenCalled();
+    });
+    it('rejects when ctx.skillSource is missing', async () => {
+        const ctx = makeCtx(process.cwd(), { provider: makeProvider() });
+        const r = await agentRunHandler({ skill: 'abap-review', task: 't' }, ctx);
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/skillSource|skill source/i);
+        expect(runTurnMock).not.toHaveBeenCalled();
+    });
+    it('rejects missing skill arg', async () => {
+        const ctx = makeCtx(process.cwd(), { provider: makeProvider(), skillSource: makeSkillSource() });
+        const r = await agentRunHandler({ task: 't' }, ctx);
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/skill/i);
+        expect(runTurnMock).not.toHaveBeenCalled();
+    });
+    it('rejects missing task arg', async () => {
+        const ctx = makeCtx(process.cwd(), { provider: makeProvider(), skillSource: makeSkillSource() });
+        const r = await agentRunHandler({ skill: 'abap-review' }, ctx);
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/task/i);
+        expect(runTurnMock).not.toHaveBeenCalled();
+    });
+    it('refuses to dispatch when depth would exceed MAX_AGENT_DEPTH', async () => {
+        process.env.CSPEACH_AGENT_DEPTH = String(MAX_AGENT_DEPTH);
+        const ctx = makeCtx(process.cwd(), { provider: makeProvider(), skillSource: makeSkillSource() });
+        const r = await agentRunHandler({ skill: 'abap-review', task: 't' }, ctx);
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/depth/i);
+        expect(runTurnMock).not.toHaveBeenCalled();
+    });
+    it('increments CSPEACH_AGENT_DEPTH for the child before invoking runTurn', async () => {
+        let observed;
+        runTurnMock.mockImplementation(async () => {
+            observed = process.env.CSPEACH_AGENT_DEPTH;
+        });
+        const ctx = makeCtx(process.cwd(), { provider: makeProvider(), skillSource: makeSkillSource() });
+        await agentRunHandler({ skill: 'abap-review', task: 't' }, ctx);
+        expect(observed).toBe('1');
+    });
+    it('restores CSPEACH_AGENT_DEPTH to its prior value after runTurn returns', async () => {
+        process.env.CSPEACH_AGENT_DEPTH = '1';
+        runTurnMock.mockResolvedValueOnce(undefined);
+        const ctx = makeCtx(process.cwd(), { provider: makeProvider(), skillSource: makeSkillSource() });
+        await agentRunHandler({ skill: 'abap-review', task: 't' }, ctx);
+        expect(process.env.CSPEACH_AGENT_DEPTH).toBe('1');
+    });
+    it('clamps max_tokens to HARD_MAX_TOKENS', async () => {
+        let observedMaxTokens;
+        runTurnMock.mockImplementation(async (params) => {
+            observedMaxTokens = params.maxTokensOverride;
+        });
+        const ctx = makeCtx(process.cwd(), { provider: makeProvider(), skillSource: makeSkillSource() });
+        await agentRunHandler({ skill: 'abap-review', task: 't', max_tokens: 999_999_999 }, ctx);
+        expect(observedMaxTokens).toBe(HARD_MAX_TOKENS);
+    });
+    it('uses DEFAULT_MAX_TOKENS when max_tokens omitted', async () => {
+        let observedMaxTokens;
+        runTurnMock.mockImplementation(async (params) => {
+            observedMaxTokens = params.maxTokensOverride;
+        });
+        const ctx = makeCtx(process.cwd(), { provider: makeProvider(), skillSource: makeSkillSource() });
+        await agentRunHandler({ skill: 'abap-review', task: 't' }, ctx);
+        expect(observedMaxTokens).toBe(DEFAULT_MAX_TOKENS);
+    });
+    it('forwards a runTurn rejection as a structured error envelope', async () => {
+        runTurnMock.mockRejectedValueOnce(new Error('child loop crashed'));
+        const ctx = makeCtx(process.cwd(), { provider: makeProvider(), skillSource: makeSkillSource() });
+        const r = await agentRunHandler({ skill: 'abap-review', task: 't' }, ctx);
+        expect(r.is_error).toBe(true);
+        // M5: assert BOTH wrapper AND inner message — guards against the
+        // wrapper swallowing the underlying error text.
+        expect(r.content).toMatch(/subagent failed/i);
+        expect(r.content).toMatch(/child loop crashed/i);
+    });
+    it('validates skill name shape (defense in depth on ctx.skillSource lookup key)', async () => {
+        const ctx = makeCtx(process.cwd(), { provider: makeProvider(), skillSource: makeSkillSource() });
+        const r = await agentRunHandler({ skill: '../etc/passwd', task: 't' }, ctx);
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/invalid skill/i);
+        expect(runTurnMock).not.toHaveBeenCalled();
+    });
+});

package/dist/tools/__tests__/approval-advisory.test.js

@@ -0,0 +1,66 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+// Mock loadConfig while preserving the rest of the module's exports so that
+// approval.ts's other imports (WriteMode, isValidWriteMode, etc., if any) stay
+// intact at import time.
+const mockLoadConfig = vi.fn();
+vi.mock('../../config/loader.js', async () => {
+    const actual = await vi.importActual('../../config/loader.js');
+    return { ...actual, loadConfig: mockLoadConfig };
+});
+// Mock the prompt (don't mock the renderer — it's pure).
+const mockPromptAdvisory = vi.fn();
+vi.mock('../../approvals/advisory-prompt.js', () => ({
+    promptAdvisory: mockPromptAdvisory,
+}));
+describe('handleAdvisoryApproval', () => {
+    const baseRequest = {
+        summary: 'Create ZCL_FOO',
+        risk: 'low',
+        transport: 'DEVK900123',
+        changes: [
+            { op: 'create', object: 'ZCL_FOO', type: 'CLAS', diff: 'CLASS...' },
+        ],
+    };
+    beforeEach(() => {
+        mockLoadConfig.mockReset();
+        mockPromptAdvisory.mockReset();
+    });
+    it('does not mint approval_ids when write_mode=advisory-only (outcome=applied)', async () => {
+        mockLoadConfig.mockResolvedValue({
+            write_mode: 'advisory-only',
+            sap: { DEV: { auto_approve: 'never' } },
+        });
+        mockPromptAdvisory.mockResolvedValue('applied');
+        const { handleAdvisoryApproval } = await import('../approval.js');
+        const result = await handleAdvisoryApproval(baseRequest, { sapAlias: 'DEV' });
+        const payload = JSON.parse(result.content);
+        expect(payload.approval_ids).toBeUndefined();
+        expect(payload.advisory_outcome).toBe('applied');
+        expect(String(payload.ai_directive).toLowerCase()).toContain('propos');
+        expect(String(payload.ai_directive).toLowerCase()).toContain('do not attempt');
+    });
+    it('returns outcome=skipped when developer chooses skip', async () => {
+        mockLoadConfig.mockResolvedValue({
+            write_mode: 'advisory-only',
+            sap: { DEV: { auto_approve: 'never' } },
+        });
+        mockPromptAdvisory.mockResolvedValue('skipped');
+        const { handleAdvisoryApproval } = await import('../approval.js');
+        const result = await handleAdvisoryApproval(baseRequest, { sapAlias: 'DEV' });
+        const payload = JSON.parse(result.content);
+        expect(payload.advisory_outcome).toBe('skipped');
+        expect(String(payload.ai_directive).toLowerCase()).toContain('skipped');
+    });
+    it('returns outcome=aborted when developer chooses abort', async () => {
+        mockLoadConfig.mockResolvedValue({
+            write_mode: 'advisory-only',
+            sap: { DEV: { auto_approve: 'never' } },
+        });
+        mockPromptAdvisory.mockResolvedValue('aborted');
+        const { handleAdvisoryApproval } = await import('../approval.js');
+        const result = await handleAdvisoryApproval(baseRequest, { sapAlias: 'DEV' });
+        const payload = JSON.parse(result.content);
+        expect(payload.advisory_outcome).toBe('aborted');
+        expect(String(payload.ai_directive).toLowerCase()).toContain('abort');
+    });
+});

package/dist/tools/__tests__/background_run.test.js

@@ -0,0 +1,113 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { backgroundRunHandler } from '../subagent/background_run.js';
+import { getBackground, consumeEvents, __resetRegistryForTests, } from '../subagent/_background-shared.js';
+import { makeCtx } from './_helpers.js';
+let root;
+const ctx = () => makeCtx(root);
+beforeEach(async () => {
+    __resetRegistryForTests();
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'cspeach-bg-'));
+});
+afterEach(async () => { await fs.rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 }); });
+/** Wait for the entry to be marked closed. Polls; ceiling so the test fails clearly. */
+// If you see flakes on slow CI, bump timeoutMs ceiling — don't tighten the poll interval.
+async function waitForExit(bg_id, timeoutMs = 5000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const e = getBackground(bg_id);
+        if (e?.closed)
+            return;
+        await new Promise((r) => setTimeout(r, 25));
+    }
+    throw new Error(`background ${bg_id} did not close within ${timeoutMs}ms`);
+}
+describe('background_run handler', () => {
+    it('spawns a safelisted command and returns a bg_id immediately', async () => {
+        const r = await backgroundRunHandler({ command: 'node', args: ['-e', 'process.stdout.write("hello"); process.exit(0)'] }, ctx());
+        expect(r.is_error).toBeFalsy();
+        expect(r.content).toMatch(/bg_id:\s*bg-[a-f0-9-]+/);
+        const m = r.content.match(/bg_id:\s*(bg-[a-f0-9-]+)/);
+        expect(m).not.toBeNull();
+        expect(getBackground(m[1])).toBeDefined();
+    });
+    it('records stdout events captured from the child', async () => {
+        const r = await backgroundRunHandler({ command: 'node', args: ['-e', 'process.stdout.write("line1\\nline2\\n"); process.exit(0)'] }, ctx());
+        const bg_id = r.content.match(/bg_id:\s*(bg-[a-f0-9-]+)/)[1];
+        await waitForExit(bg_id);
+        const consumed = consumeEvents(bg_id, 100);
+        expect(consumed).not.toBeNull();
+        const stdoutTexts = consumed.events.filter((e) => e.kind === 'stdout').map((e) => e.text);
+        expect(stdoutTexts.join('')).toMatch(/line1[\s\S]*line2/);
+        expect(consumed.closed).toBe(true);
+        expect(consumed.exitCode).toBe(0);
+    });
+    it('records stderr events separately from stdout', async () => {
+        const r = await backgroundRunHandler({ command: 'node', args: ['-e', 'process.stderr.write("oops\\n"); process.exit(1)'] }, ctx());
+        const bg_id = r.content.match(/bg_id:\s*(bg-[a-f0-9-]+)/)[1];
+        await waitForExit(bg_id);
+        const consumed = consumeEvents(bg_id, 100);
+        const stderrTexts = consumed.events.filter((e) => e.kind === 'stderr').map((e) => e.text);
+        expect(stderrTexts.join('')).toMatch(/oops/);
+        expect(consumed.exitCode).toBe(1);
+    });
+    it('refuses a non-safelisted command', async () => {
+        const r = await backgroundRunHandler({ command: 'curl', args: ['https://example.com'] }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/safelist/i);
+    });
+    it('refuses an absolute path even if basename is safelisted', async () => {
+        const abs = process.platform === 'win32' ? 'C:\\Windows\\System32\\cmd.exe' : '/bin/sh';
+        const r = await backgroundRunHandler({ command: abs, args: [] }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/separators|absolute/i);
+    });
+    it('rejects argv > MAX_ARGS', async () => {
+        const tooMany = Array.from({ length: 1001 }, () => 'x');
+        const r = await backgroundRunHandler({ command: 'node', args: tooMany }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/too many args/i);
+    });
+    it('refuses cwd outside the project root', async () => {
+        const outside = process.platform === 'win32' ? 'C:\\' : '/';
+        const r = await backgroundRunHandler({ command: 'node', args: ['-e', 'process.exit(0)'], cwd: outside }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/outside|cwd/i);
+    });
+    it('does NOT leak CSPEACH_*/ANTHROPIC_*/SAP_* env vars to the child', async () => {
+        process.env.CSPEACH_BG_TEST_LEAK = 'must-not-leak';
+        process.env.ANTHROPIC_BG_TEST_LEAK = 'must-not-leak';
+        process.env.FOO_BG_TEST_LEAK_CANARY = 'must-not-leak';
+        try {
+            const r = await backgroundRunHandler({
+                command: 'node',
+                args: [
+                    '-e',
+                    'const k = ["CSPEACH_BG_TEST_LEAK","ANTHROPIC_BG_TEST_LEAK","FOO_BG_TEST_LEAK_CANARY"].filter(x=>process.env[x]); process.stdout.write(k.join(","))',
+                ],
+            }, ctx());
+            const bg_id = r.content.match(/bg_id:\s*(bg-[a-f0-9-]+)/)[1];
+            await waitForExit(bg_id);
+            const consumed = consumeEvents(bg_id, 100);
+            const text = consumed.events.map((e) => e.text).join('');
+            expect(text).not.toContain('must-not-leak');
+        }
+        finally {
+            delete process.env.CSPEACH_BG_TEST_LEAK;
+            delete process.env.ANTHROPIC_BG_TEST_LEAK;
+            delete process.env.FOO_BG_TEST_LEAK_CANARY;
+        }
+    });
+    it('records exit event with exitCode + signal', async () => {
+        const r = await backgroundRunHandler({ command: 'node', args: ['-e', 'process.exit(7)'] }, ctx());
+        const bg_id = r.content.match(/bg_id:\s*(bg-[a-f0-9-]+)/)[1];
+        await waitForExit(bg_id);
+        const consumed = consumeEvents(bg_id, 100);
+        const exitEv = consumed.events.find((e) => e.kind === 'exit');
+        expect(exitEv).toBeDefined();
+        expect(exitEv.exitCode).toBe(7);
+        expect(consumed.exitCode).toBe(7);
+    });
+});

package/dist/tools/__tests__/convention_get.test.js

@@ -0,0 +1,53 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { conventionGetHandler } from '../project/convention_get.js';
+import { makeCtx } from './_helpers.js';
+import { __resetProjectContextCacheForTests } from '../../agent/maybe-build-project-context.js';
+let tmpRoot;
+beforeEach(async () => {
+    tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'cspeach-convention-get-'));
+    __resetProjectContextCacheForTests();
+});
+afterEach(async () => {
+    try {
+        await fs.rm(tmpRoot, { recursive: true, force: true });
+    }
+    catch { /* ignore */ }
+    __resetProjectContextCacheForTests();
+    vi.restoreAllMocks();
+});
+describe('convention_get', () => {
+    it("returns the full conventions object as JSON when field='all'", async () => {
+        const r = await conventionGetHandler({ field: 'all' }, makeCtx(tmpRoot));
+        expect(r.is_error).toBeFalsy();
+        const parsed = JSON.parse(r.content);
+        expect(parsed.style).toBeDefined();
+        expect(parsed.namingPatterns).toBeDefined();
+        expect(typeof parsed.style.indentSize).toBe('number');
+    });
+    it("returns the indent size as a number when field='indentSize'", async () => {
+        const r = await conventionGetHandler({ field: 'indentSize' }, makeCtx(tmpRoot));
+        expect(r.is_error).toBeFalsy();
+        expect(r.content.trim()).toMatch(/^\d+$/);
+    });
+    it("returns the EOL style when field='eol'", async () => {
+        const r = await conventionGetHandler({ field: 'eol' }, makeCtx(tmpRoot));
+        expect(r.is_error).toBeFalsy();
+        expect(['lf', 'crlf']).toContain(r.content.trim());
+    });
+    it("returns the namingPatterns object as JSON when field='namingPatterns'", async () => {
+        const r = await conventionGetHandler({ field: 'namingPatterns' }, makeCtx(tmpRoot));
+        expect(r.is_error).toBeFalsy();
+        const parsed = JSON.parse(r.content);
+        expect(parsed).toHaveProperty('classes');
+        expect(parsed).toHaveProperty('interfaces');
+        expect(parsed).toHaveProperty('cdsViews');
+    });
+    it('rejects an unknown field with a structured error', async () => {
+        const r = await conventionGetHandler({ field: 'flavor' }, makeCtx(tmpRoot));
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/unknown field|invalid field/i);
+    });
+});

package/dist/tools/__tests__/file-edit.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileEditHandler } from '../filesystem/file-edit.js';
+import { makeCtx } from './_helpers.js';
+let root;
+const ctx = () => makeCtx(root);
+beforeEach(async () => { root = await fs.mkdtemp(path.join(os.tmpdir(), 'cspeach-file-edit-')); });
+afterEach(async () => { await fs.rm(root, { recursive: true, force: true }); });
+describe('file_edit handler', () => {
+    it('happy path — replaces a unique string and returns count', async () => {
+        await fs.writeFile(path.join(root, 'hello.ts'), 'hello world\nsecond line\n', 'utf-8');
+        const r = await fileEditHandler({ path: 'hello.ts', old_string: 'hello world', new_string: 'goodbye world' }, ctx());
+        expect(r.is_error).toBeFalsy();
+        expect(r.content).toMatch(/edited.*hello\.ts.*1 replacement/i);
+        const updated = await fs.readFile(path.join(root, 'hello.ts'), 'utf-8');
+        expect(updated).toContain('goodbye world');
+        expect(updated).not.toContain('hello world');
+        expect(updated).toContain('second line');
+    });
+    it('errors when old_string is not found in the file', async () => {
+        await fs.writeFile(path.join(root, 'foo.ts'), 'line one\nline two\n', 'utf-8');
+        const r = await fileEditHandler({ path: 'foo.ts', old_string: 'does not exist', new_string: 'replacement' }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/not found/i);
+    });
+    it('errors when old_string matches multiple times without replace_all', async () => {
+        await fs.writeFile(path.join(root, 'dup.ts'), 'foo bar\nfoo baz\n', 'utf-8');
+        const r = await fileEditHandler({ path: 'dup.ts', old_string: 'foo', new_string: 'qux' }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/matches 2 times/i);
+        expect(r.content).toMatch(/replace_all/i);
+        // file must be unchanged
+        const unchanged = await fs.readFile(path.join(root, 'dup.ts'), 'utf-8');
+        expect(unchanged).toContain('foo bar');
+    });
+    it('replace_all=true replaces all occurrences', async () => {
+        await fs.writeFile(path.join(root, 'multi.ts'), 'foo bar\nfoo baz\nfoo qux\n', 'utf-8');
+        const r = await fileEditHandler({ path: 'multi.ts', old_string: 'foo', new_string: 'boo', replace_all: true }, ctx());
+        expect(r.is_error).toBeFalsy();
+        expect(r.content).toMatch(/3 replacements/i);
+        const updated = await fs.readFile(path.join(root, 'multi.ts'), 'utf-8');
+        expect(updated).toBe('boo bar\nboo baz\nboo qux\n');
+    });
+    it('refuses path traversal (../foo)', async () => {
+        const r = await fileEditHandler({ path: '../../etc/passwd', old_string: 'root', new_string: 'nobody' }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/outside/i);
+    });
+    it('refuses denylisted path (.cspeach/auth.json)', async () => {
+        await fs.mkdir(path.join(root, '.cspeach'), { recursive: true });
+        await fs.writeFile(path.join(root, '.cspeach', 'auth.json'), '{"token":"secret"}', 'utf-8');
+        const r = await fileEditHandler({ path: '.cspeach/auth.json', old_string: 'secret', new_string: 'redacted' }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/sensitive path/i);
+        // file must be unchanged
+        const unchanged = await fs.readFile(path.join(root, '.cspeach', 'auth.json'), 'utf-8');
+        expect(unchanged).toContain('secret');
+    });
+    it('errors when old_string === new_string (no-op edit refused)', async () => {
+        await fs.writeFile(path.join(root, 'noop.ts'), 'some content\n', 'utf-8');
+        const r = await fileEditHandler({ path: 'noop.ts', old_string: 'some content', new_string: 'some content' }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/no-op|old_string.*new_string.*identical|same/i);
+    });
+    it('errors when the file does not exist', async () => {
+        const r = await fileEditHandler({ path: 'nonexistent.ts', old_string: 'foo', new_string: 'bar' }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/not found|ENOENT/i);
+    });
+});

package/dist/tools/__tests__/file-read.test.js

@@ -0,0 +1,81 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileReadHandler } from '../filesystem/file-read.js';
+import { makeCtx } from './_helpers.js';
+let root;
+const ctx = () => makeCtx(root);
+beforeEach(async () => { root = await fs.mkdtemp(path.join(os.tmpdir(), 'cspeach-file-read-')); });
+afterEach(async () => { await fs.rm(root, { recursive: true, force: true }); });
+describe('file_read handler', () => {
+    it('reads a file from the project and returns content with line numbers', async () => {
+        await fs.writeFile(path.join(root, 'foo.ts'), 'line one\nline two\nline three\n', 'utf-8');
+        const r = await fileReadHandler({ path: 'foo.ts' }, ctx());
+        expect(r.is_error).toBeFalsy();
+        expect(r.content).toContain('1\tline one');
+        expect(r.content).toContain('2\tline two');
+        expect(r.content).toContain('3\tline three');
+    });
+    it('refuses paths outside the project root', async () => {
+        const r = await fileReadHandler({ path: '../../etc/passwd' }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/outside/i);
+    });
+    it('returns an error envelope when the file does not exist', async () => {
+        const r = await fileReadHandler({ path: 'nope.ts' }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/not found|ENOENT/i);
+    });
+    it('truncates at 2000 lines and indicates truncation', async () => {
+        const lines = Array.from({ length: 3000 }, (_, i) => `line ${i + 1}`).join('\n');
+        await fs.writeFile(path.join(root, 'big.ts'), lines, 'utf-8');
+        const r = await fileReadHandler({ path: 'big.ts' }, ctx());
+        expect(r.content).toContain('1\tline 1');
+        expect(r.content).toContain('2000\tline 2000');
+        expect(r.content).not.toContain('2001\tline 2001');
+        expect(r.content).toMatch(/truncated.*1000.*more/i);
+    });
+    it('respects optional offset + limit args (read a window)', async () => {
+        const lines = Array.from({ length: 100 }, (_, i) => `L${i + 1}`).join('\n');
+        await fs.writeFile(path.join(root, 'mid.ts'), lines, 'utf-8');
+        const r = await fileReadHandler({ path: 'mid.ts', offset: 50, limit: 5 }, ctx());
+        expect(r.content).toContain('51\tL51');
+        expect(r.content).toContain('55\tL55');
+        expect(r.content).not.toContain('56\tL56');
+    });
+    it('rejects negative offset', async () => {
+        await fs.writeFile(path.join(root, 'foo.ts'), 'line\n', 'utf-8');
+        const r = await fileReadHandler({ path: 'foo.ts', offset: -1 }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/offset.*non-negative/i);
+    });
+    it('rejects negative limit', async () => {
+        await fs.writeFile(path.join(root, 'foo.ts'), 'line\n', 'utf-8');
+        const r = await fileReadHandler({ path: 'foo.ts', limit: -5 }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/limit.*positive/i);
+    });
+    it('refuses to read .cspeach/* (sensitive denylist)', async () => {
+        await fs.mkdir(path.join(root, '.cspeach'), { recursive: true });
+        await fs.writeFile(path.join(root, '.cspeach', 'auth.json'), '{"password":"secret"}', 'utf-8');
+        const r = await fileReadHandler({ path: '.cspeach/auth.json' }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/sensitive path/i);
+        expect(r.content).not.toContain('secret'); // must not leak
+    });
+    it('refuses to read .env (denylist)', async () => {
+        await fs.writeFile(path.join(root, '.env'), 'SECRET=value', 'utf-8');
+        const r = await fileReadHandler({ path: '.env' }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/sensitive path/i);
+    });
+    it('does NOT mis-number a trailing blank line on files ending in newline', async () => {
+        // "a\nb\n" split naively produces ['a', 'b', ''] — line 3 should NOT appear.
+        await fs.writeFile(path.join(root, 'trailer.ts'), 'a\nb\n', 'utf-8');
+        const r = await fileReadHandler({ path: 'trailer.ts' }, ctx());
+        expect(r.content).toContain('1\ta');
+        expect(r.content).toContain('2\tb');
+        expect(r.content).not.toContain('3\t');
+    });
+});

package/dist/tools/__tests__/file-write.test.js

@@ -0,0 +1,68 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileWriteHandler } from '../filesystem/file-write.js';
+import { makeCtx } from './_helpers.js';
+let root;
+const ctx = () => makeCtx(root);
+beforeEach(async () => { root = await fs.mkdtemp(path.join(os.tmpdir(), 'cspeach-file-write-')); });
+afterEach(async () => { await fs.rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 }); });
+describe('file_write handler', () => {
+    it('creates a new file with the given content', async () => {
+        const r = await fileWriteHandler({ path: 'newfile.ts', content: 'hello world\n' }, ctx());
+        expect(r.is_error).toBeFalsy();
+        expect(r.content).toMatch(/wrote.*newfile\.ts/i);
+        const written = await fs.readFile(path.join(root, 'newfile.ts'), 'utf-8');
+        expect(written).toBe('hello world\n');
+    });
+    it('overwrites an existing file', async () => {
+        await fs.writeFile(path.join(root, 'existing.ts'), 'old content\n', 'utf-8');
+        const r = await fileWriteHandler({ path: 'existing.ts', content: 'new content\n' }, ctx());
+        expect(r.is_error).toBeFalsy();
+        expect(r.content).toMatch(/wrote.*existing\.ts/i);
+        const written = await fs.readFile(path.join(root, 'existing.ts'), 'utf-8');
+        expect(written).toBe('new content\n');
+    });
+    it('creates parent directories that do not exist yet', async () => {
+        const r = await fileWriteHandler({ path: 'deep/nested/dir/file.ts', content: 'content\n' }, ctx());
+        expect(r.is_error).toBeFalsy();
+        expect(r.content).toMatch(/wrote.*deep\/nested\/dir\/file\.ts/i);
+        const written = await fs.readFile(path.join(root, 'deep', 'nested', 'dir', 'file.ts'), 'utf-8');
+        expect(written).toBe('content\n');
+    });
+    it('refuses path traversal (../foo)', async () => {
+        const r = await fileWriteHandler({ path: '../../etc/evil.txt', content: 'bad' }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/outside/i);
+    });
+    it('refuses denylisted path (.cspeach/auth.json)', async () => {
+        await fs.mkdir(path.join(root, '.cspeach'), { recursive: true });
+        const r = await fileWriteHandler({ path: '.cspeach/auth.json', content: '{"token":"hacked"}' }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/sensitive path/i);
+        // file must not have been created/modified with the new content
+        const exists = await fs.access(path.join(root, '.cspeach', 'auth.json')).then(() => true, () => false);
+        expect(exists).toBe(false);
+    });
+    it('refuses denylisted path (.git/config)', async () => {
+        await fs.mkdir(path.join(root, '.git'), { recursive: true });
+        await fs.writeFile(path.join(root, '.git', 'config'), '[core]\n', 'utf-8');
+        const r = await fileWriteHandler({ path: '.git/config', content: 'tampered\n' }, ctx());
+        expect(r.is_error).toBe(true);
+        expect(r.content).toMatch(/sensitive path/i);
+        // original file must be unchanged
+        const content = await fs.readFile(path.join(root, '.git', 'config'), 'utf-8');
+        expect(content).toBe('[core]\n');
+    });
+    it('atomic write — no leftover .tmp file on success', async () => {
+        const r = await fileWriteHandler({ path: 'atomic.ts', content: 'data\n' }, ctx());
+        expect(r.is_error).toBeFalsy();
+        // target file exists
+        const written = await fs.readFile(path.join(root, 'atomic.ts'), 'utf-8');
+        expect(written).toBe('data\n');
+        // no leftover .tmp
+        const tmpExists = await fs.access(path.join(root, 'atomic.ts.tmp')).then(() => true, () => false);
+        expect(tmpExists).toBe(false);
+    });
+});