aiseerr 1.0.0

package/src/commands/scout.ts

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { handleEnvCommand } from './env';
+import { handleTreeCommand } from './tree';
+import { handleDiffCommand } from './diff';
+
+export function handleScoutCommand(budget?: number): any {
+    const result: any = {};
+    const cwd = process.cwd();
+
+    // 1. Env (Always)
+    try {
+        result.env = handleEnvCommand();
+    } catch (e: any) {
+        result.env = { error: e.message };
+    }
+
+    // 2. Tree (Always, depth=2)
+    try {
+        // If a global budget is set, allocate approximately half of it to the tree
+        // since tree and diff are typically the largest components.
+        const treeBudget = budget ? Math.floor(budget * 0.5) : undefined;
+        result.tree = handleTreeCommand(['--depth=2'], treeBudget);
+    } catch (e: any) {
+        result.tree = { error: e.message };
+    }
+
+    // 3. Readme
+    const readmePaths = ['README.md', 'Readme.md', 'readme.md'];
+    let readmeFound = false;
+    for (const p of readmePaths) {
+        const fullPath = join(cwd, p);
+        if (existsSync(fullPath)) {
+            try {
+                const content = readFileSync(fullPath, 'utf-8');
+                const lines = content.split('\n');
+                // Truncate to first 60 lines for a quick summary
+                if (lines.length > 60) {
+                    result.readme = lines.slice(0, 60).join('\n') + '\n...[TRUNCATED TO 60 LINES]';
+                } else {
+                    result.readme = content;
+                }
+                readmeFound = true;
+                break;
+            } catch {
+                // ignore
+            }
+        }
+    }
+    if (!readmeFound) result.readme = null;
+
+    // 4. Agent Rules
+    const rulePaths = ['.cursorrules', 'CLAUDE.md', 'AGENTS.md', '.github/copilot-instructions.md'];
+    let rulesFound = false;
+    for (const p of rulePaths) {
+        const fullPath = join(cwd, p);
+        if (existsSync(fullPath)) {
+            try {
+                result.agentRules = {
+                    source: p,
+                    // Limit rules to 500 lines to prevent runaway tokens, though usually they are small
+                    content: readFileSync(fullPath, 'utf-8').split('\n').slice(0, 500).join('\n')
+                };
+                rulesFound = true;
+                break;
+            } catch {
+                // ignore
+            }
+        }
+    }
+    if (!rulesFound) result.agentRules = null;
+
+    // 5. Diff (Stat only, no full diff payload to save tokens in a generic scout)
+    try {
+        const diffRes = handleDiffCommand([], undefined);
+        // Remove the full diffs if they somehow got in
+        delete diffRes.stagedDiff;
+        delete diffRes.unstagedDiff;
+        result.diff = diffRes;
+    } catch (e: any) {
+        // Expected to fail cleanly if not a git repository
+        result.diff = null;
+    }
+
+    // 6. Workspaces
+    if (result.env && result.env.workspaces) {
+        result.workspaces = result.env.workspaces;
+    } else {
+        result.workspaces = null;
+    }
+
+    return result;
+}

package/src/commands/tree.ts

@@ -0,0 +1,133 @@
+import { readdirSync, statSync, existsSync, readFileSync } from 'fs';
+import { join, basename } from 'path';
+
+function buildIgnoreMatcher(cwd: string): (path: string) => boolean {
+    const ignoreFile = join(cwd, '.gitignore');
+    const defaults = ['node_modules', '.git', 'dist', '.next', 'build', 'out', 'coverage'];
+
+    let patterns: string[] = [];
+    if (existsSync(ignoreFile)) {
+        const lines = readFileSync(ignoreFile, 'utf-8').split('\n');
+        patterns = lines
+            .map(l => l.trim())
+            .filter(l => l && !l.startsWith('#'))
+            .map(l => l.replace(/\/$/, '')); // normalize dir ignores
+    }
+
+    const allIgnores = new Set([...defaults, ...patterns]);
+
+    return (path: string) => {
+        const name = basename(path);
+        // Rough match for v1.0, sufficient for 95% of use cases
+        if (allIgnores.has(name)) return true;
+        for (const pattern of allIgnores) {
+            if (pattern.startsWith('*') && name.endsWith(pattern.slice(1))) return true;
+        }
+        return false;
+    };
+}
+
+export function handleTreeCommand(args: string[], budget?: number): any {
+    let targetDir = '.';
+    let maxDepth = 3;
+
+    for (const arg of args) {
+        if (arg.startsWith('--depth=')) {
+            maxDepth = parseInt(arg.split('=')[1], 10) || 3;
+        } else if (!arg.startsWith('--')) {
+            targetDir = arg;
+        }
+    }
+
+    const fullTarget = join(process.cwd(), targetDir);
+    if (!existsSync(fullTarget)) {
+        throw new Error(`Directory not found: ${targetDir}`);
+    }
+
+    const isIgnored = buildIgnoreMatcher(process.cwd());
+    const stats = {
+        totalFiles: 0,
+        displayed: 0,
+        ignoredDirs: new Set<string>()
+    };
+
+    function traverse(currentPath: string, currentDepth: number): any {
+        if (currentDepth > maxDepth) {
+            return { _more: true }; // Hit depth limit
+        }
+
+        let entries: string[] = [];
+        try {
+            entries = readdirSync(currentPath);
+        } catch {
+            return {}; // Permission issues
+        }
+
+        const result: Record<string, any> = {};
+        const filesOnly: string[] = [];
+        let hiddenCount = 0;
+
+        for (const entry of entries) {
+            const entryPath = join(currentPath, entry);
+
+            if (isIgnored(entryPath) || entry.startsWith('.DS_Store')) {
+                const stat = statSync(entryPath, { throwIfNoEntry: false });
+                if (stat?.isDirectory()) {
+                    stats.ignoredDirs.add(entry);
+                }
+                continue;
+            }
+
+            const stat = statSync(entryPath, { throwIfNoEntry: false });
+            if (!stat) continue;
+
+            if (stat.isDirectory()) {
+                const sub = traverse(entryPath, currentDepth + 1);
+                if (sub && Object.keys(sub).length > 0) {
+                    result[entry + '/'] = sub;
+                } else if (sub && sub._more) {
+                    result[entry + '/'] = { _more: true };
+                }
+            } else {
+                stats.totalFiles++;
+
+                // Basic budget pruning threshold logic: if we are displaying too many files, start summarizing 
+                // to stay within reasonable bounds even before the global output filter kicks in.
+                if (stats.displayed > 200) {
+                    hiddenCount++;
+                } else {
+                    filesOnly.push(entry);
+                    stats.displayed++;
+                }
+            }
+        }
+
+        if (filesOnly.length > 0) {
+            if (Object.keys(result).length === 0) {
+                // It's a directory with ONLY files. Use the flat array optimization.
+                const res: any = { _files: filesOnly };
+                if (hiddenCount > 0) res._more = hiddenCount;
+                return res;
+            } else {
+                // Mixed dir
+                for (const f of filesOnly) result[f] = {};
+                if (hiddenCount > 0) result['_moreReplacedFiles'] = hiddenCount;
+            }
+        }
+
+        return result;
+    }
+
+    const structure = traverse(fullTarget, 1);
+
+    return {
+        root: targetDir,
+        depth: maxDepth,
+        structure,
+        stats: {
+            totalFiles: stats.totalFiles,
+            displayed: stats.displayed,
+            ignored: Array.from(stats.ignoredDirs)
+        }
+    };
+}

package/src/utils/output.ts

@@ -0,0 +1,123 @@
+/**
+ * Core output management for aiseerr.
+ * Guarantees Machine-First protocol: Pure JSON on stdout, structured error on stderr.
+ */
+
+// A very rough token estimator (approximately 4 characters per token for English/code)
+export function estimateTokens(text: string): number {
+    return Math.max(1, Math.ceil(text.length / 4));
+}
+
+// Ensure the final object doesn't exceed the token budget if one is provided
+export function applyBudget(data: any, budget?: number): any {
+    if (!budget || budget <= 0) return data;
+
+    const serialized = JSON.stringify(data);
+    const estimated = estimateTokens(serialized);
+
+    if (estimated > budget) {
+        // Actually truncate: serialize to JSON, cut to budget char limit, close cleanly
+        const budgetChars = budget * 4;
+
+        if (typeof data === 'object' && data !== null && !Array.isArray(data)) {
+            // Try pruning array values first (largest arrays get trimmed)
+            const pruned = { ...data };
+            const keys = Object.keys(pruned);
+
+            // Sort keys by serialized size descending to prune largest first
+            const keySizes = keys
+                .filter(k => k !== '_meta')
+                .map(k => ({ key: k, size: JSON.stringify(pruned[k]).length }))
+                .sort((a, b) => b.size - a.size);
+
+            for (const { key } of keySizes) {
+                const currentSize = JSON.stringify(pruned).length;
+                if (currentSize <= budgetChars) break;
+
+                if (Array.isArray(pruned[key]) && pruned[key].length > 0) {
+                    // Trim array items from the end until under budget
+                    const arr = [...pruned[key]];
+                    while (arr.length > 0 && JSON.stringify({ ...pruned, [key]: arr }).length > budgetChars) {
+                        arr.pop();
+                    }
+                    pruned[key] = arr.length > 0 ? arr : `[TRUNCATED: ${pruned[key].length} items removed]`;
+                } else if (typeof pruned[key] === 'string' && pruned[key].length > 200) {
+                    // Truncate long string values
+                    const allowedLen = Math.max(100, pruned[key].length - (currentSize - budgetChars));
+                    pruned[key] = pruned[key].slice(0, allowedLen) + '...[TRUNCATED]';
+                }
+            }
+
+            // Final fallback: if still over budget, hard-truncate the JSON string
+            const prunedJson = JSON.stringify(pruned);
+            if (prunedJson.length > budgetChars) {
+                const truncatedStr = prunedJson.slice(0, budgetChars);
+                // Try to parse back; if not valid, wrap as raw truncated output
+                return {
+                    _truncated_raw: truncatedStr,
+                    _meta: {
+                        tokensEstimate: estimated,
+                        budget,
+                        truncated: true,
+                        hint: `Output exceeded budget of ${budget} tokens. Data was hard-truncated.`
+                    }
+                };
+            }
+
+            return {
+                ...pruned,
+                _meta: {
+                    ...(pruned._meta || {}),
+                    tokensEstimate: estimateTokens(JSON.stringify(pruned)),
+                    budget,
+                    truncated: true,
+                    hint: `Output exceeded budget of ${budget} tokens. Some fields were pruned.`
+                }
+            };
+        }
+
+        // Non-object data: hard truncate the serialized string
+        const truncated = serialized.slice(0, budgetChars);
+        return {
+            _truncated_raw: truncated,
+            _meta: {
+                tokensEstimate: estimated,
+                budget,
+                truncated: true,
+                hint: `Output exceeded budget of ${budget} tokens. Data was hard-truncated.`
+            }
+        };
+    }
+
+    // Under budget — attach meta info
+    if (typeof data === 'object' && data !== null && !Array.isArray(data)) {
+        return {
+            ...data,
+            _meta: {
+                ...(data._meta || {}),
+                tokensEstimate: estimated,
+                budget,
+                truncated: false
+            }
+        };
+    }
+
+    return data;
+}
+
+export function outputSuccess(data: any, budget?: number) {
+    const finalData = applyBudget(data, budget);
+    const output = JSON.stringify(finalData, null, process.argv.includes('--pretty') ? 2 : undefined) + '\n';
+    process.stdout.write(output, () => process.exit(0));
+}
+
+export function outputError(error: unknown, code = 1) {
+    const message = error instanceof Error ? error.message : String(error);
+    const errorObj = {
+        error: message,
+        code: code
+    };
+
+    process.stderr.write(JSON.stringify(errorObj, null, process.argv.includes('--pretty') ? 2 : undefined) + '\n');
+    process.exit(code);
+}

package/tests/cli.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// We test the CLI routing logic by extracting the core routing behavior.
+// Since cli.ts calls main() on import and uses process.argv / process.exit,
+// we test the command routing indirectly through the individual handlers,
+// and verify the arg-parsing logic directly.
+
+// Mock all command handlers
+vi.mock('../src/commands/env', () => ({ handleEnvCommand: vi.fn(() => ({ mock: 'env' })) }));
+vi.mock('../src/commands/tree', () => ({ handleTreeCommand: vi.fn(() => ({ mock: 'tree' })) }));
+vi.mock('../src/commands/read', () => ({ handleReadCommand: vi.fn(() => ({ mock: 'read' })) }));
+vi.mock('../src/commands/diff', () => ({ handleDiffCommand: vi.fn(() => ({ mock: 'diff' })) }));
+vi.mock('../src/commands/scout', () => ({ handleScoutCommand: vi.fn(() => ({ mock: 'scout' })) }));
+vi.mock('../src/commands/init', () => ({ handleInitCommand: vi.fn(() => ({ mock: 'init' })) }));
+
+// Mock output to prevent process.exit calls
+vi.mock('../src/utils/output', () => ({
+    outputSuccess: vi.fn(),
+    outputError: vi.fn(),
+}));
+
+import { handleEnvCommand } from '../src/commands/env';
+import { handleTreeCommand } from '../src/commands/tree';
+import { handleReadCommand } from '../src/commands/read';
+import { handleDiffCommand } from '../src/commands/diff';
+import { handleScoutCommand } from '../src/commands/scout';
+import { handleInitCommand } from '../src/commands/init';
+import { outputSuccess, outputError } from '../src/utils/output';
+
+/**
+ * Re-implements the CLI arg parsing and routing logic from src/cli.ts
+ * to test it in isolation without triggering process.exit or auto-execution.
+ */
+function routeCommand(args: string[]): { command: string; result?: any; error?: string; isHelp?: boolean } {
+    if (args.length === 0 || args[0] === 'help' || args.includes('--help') || args.includes('-h')) {
+        return { command: 'help', isHelp: true };
+    }
+
+    const command = args[0];
+    const originalParams = args.slice(1);
+
+    let budget: number | undefined;
+    const commandParams: string[] = [];
+
+    for (const p of originalParams) {
+        if (p.startsWith('--budget=')) {
+            budget = parseInt(p.split('=')[1], 10);
+            if (isNaN(budget)) {
+                return { command, error: 'Invalid --budget value. Must be a number.' };
+            }
+        } else if (p === '--pretty') {
+            // handled globally
+        } else {
+            commandParams.push(p);
+        }
+    }
+
+    let result: any;
+    switch (command) {
+        case 'scout':
+            result = (handleScoutCommand as any)(budget);
+            break;
+        case 'env':
+            result = (handleEnvCommand as any)();
+            break;
+        case 'tree':
+            result = (handleTreeCommand as any)(commandParams, budget);
+            break;
+        case 'read':
+            result = (handleReadCommand as any)(commandParams, budget);
+            break;
+        case 'diff':
+            result = (handleDiffCommand as any)(commandParams, budget);
+            break;
+        case 'init':
+            result = (handleInitCommand as any)(commandParams);
+            break;
+        default:
+            return { command, error: `Unknown command: ${command}` };
+    }
+
+    return { command, result };
+}
+
+describe('CLI Routing', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    it('should show help when no arguments provided', () => {
+        const res = routeCommand([]);
+        expect(res.isHelp).toBe(true);
+        expect(res.command).toBe('help');
+    });
+
+    it('should show help when "help" is the first argument (args[0] === "help" fix)', () => {
+        const res = routeCommand(['help']);
+        expect(res.isHelp).toBe(true);
+    });
+
+    it('should show help when --help flag is present anywhere', () => {
+        const res = routeCommand(['env', '--help']);
+        expect(res.isHelp).toBe(true);
+    });
+
+    it('should show help when -h flag is present', () => {
+        const res = routeCommand(['-h']);
+        expect(res.isHelp).toBe(true);
+    });
+
+    it('should route to env command', () => {
+        const res = routeCommand(['env']);
+        expect(res.command).toBe('env');
+        expect(handleEnvCommand).toHaveBeenCalled();
+    });
+
+    it('should route to tree command with params', () => {
+        routeCommand(['tree', 'src/', '--depth=5']);
+        expect(handleTreeCommand).toHaveBeenCalledWith(['src/', '--depth=5'], undefined);
+    });
+
+    it('should route to read command', () => {
+        routeCommand(['read', 'file.ts']);
+        expect(handleReadCommand).toHaveBeenCalledWith(['file.ts'], undefined);
+    });
+
+    it('should route to diff command', () => {
+        routeCommand(['diff', '--full']);
+        expect(handleDiffCommand).toHaveBeenCalledWith(['--full'], undefined);
+    });
+
+    it('should route to scout command', () => {
+        routeCommand(['scout']);
+        expect(handleScoutCommand).toHaveBeenCalledWith(undefined);
+    });
+
+    it('should route to init command', () => {
+        routeCommand(['init', '--format=claude']);
+        expect(handleInitCommand).toHaveBeenCalledWith(['--format=claude']);
+    });
+
+    it('should return error for unknown commands', () => {
+        const res = routeCommand(['foobar']);
+        expect(res.error).toBe('Unknown command: foobar');
+    });
+
+    it('should extract --budget flag and pass as number', () => {
+        routeCommand(['scout', '--budget=500']);
+        expect(handleScoutCommand).toHaveBeenCalledWith(500);
+    });
+
+    it('should pass budget to tree command', () => {
+        routeCommand(['tree', 'src/', '--budget=1000', '--depth=2']);
+        expect(handleTreeCommand).toHaveBeenCalledWith(['src/', '--depth=2'], 1000);
+    });
+
+    it('should error on invalid budget value (NaN)', () => {
+        const res = routeCommand(['env', '--budget=abc']);
+        expect(res.error).toContain('Invalid --budget value');
+    });
+
+    it('should strip --pretty from command params', () => {
+        routeCommand(['tree', 'src/', '--pretty']);
+        // --pretty should not be passed to the command handler
+        expect(handleTreeCommand).toHaveBeenCalledWith(['src/'], undefined);
+    });
+
+    it('should handle multiple flags together', () => {
+        routeCommand(['read', 'file.ts', '--lines=1-10', '--budget=200', '--pretty']);
+        expect(handleReadCommand).toHaveBeenCalledWith(['file.ts', '--lines=1-10'], 200);
+    });
+});

package/tests/diff.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { handleDiffCommand } from '../src/commands/diff';
+import * as child_process from 'child_process';
+import * as fs from 'fs';
+
+vi.mock('fs', async () => {
+    const actual = await vi.importActual<typeof import('fs')>('fs');
+    return { ...actual, existsSync: vi.fn() };
+});
+
+vi.mock('child_process', () => ({
+    execFileSync: vi.fn()
+}));
+
+const mockExistsSync = fs.existsSync as any;
+const mockExecFileSync = child_process.execFileSync as any;
+
+describe('Diff Command', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    it('should throw when not a git repository', () => {
+        mockExistsSync.mockReturnValue(false);
+        expect(() => handleDiffCommand([])).toThrow('Not a git repository');
+    });
+
+    it('should return branch, ahead/behind counts, staged/unstaged/untracked', () => {
+        mockExistsSync.mockImplementation((p: string) => p.endsWith('.git'));
+        mockExecFileSync.mockImplementation((cmd: string, args: string[]) => {
+            if (args.includes('--abbrev-ref')) return 'feature-x\n';
+            if (args.includes('--left-right')) return '3\t1\n';
+            if (args.includes('--porcelain')) return 'M  staged.ts\n M unstaged.ts\n?? new.ts\n';
+            if (args.includes('--numstat') && args.includes('--cached')) return '10\t2\tstaged.ts\n';
+            if (args.includes('--numstat')) return '5\t3\tunstaged.ts\n';
+            return '';
+        });
+
+        const result = handleDiffCommand([]);
+        expect(result.branch).toBe('feature-x');
+        expect(result.ahead).toBe(3);
+        expect(result.behind).toBe(1);
+        expect(result.staged).toEqual([{ file: 'staged.ts', status: 'M', insertions: 10, deletions: 2 }]);
+        expect(result.unstaged).toEqual([{ file: 'unstaged.ts', status: 'M', insertions: 5, deletions: 3 }]);
+        expect(result.untracked).toEqual(['new.ts']);
+    });
+
+    it('should handle --full flag and attach raw diff output', () => {
+        mockExistsSync.mockImplementation((p: string) => p.endsWith('.git'));
+        mockExecFileSync.mockImplementation((cmd: string, args: string[]) => {
+            if (args.includes('--abbrev-ref')) return 'main\n';
+            if (args.includes('--left-right')) return null;
+            if (args.includes('--porcelain')) return '';
+            if (args[0] === 'diff' && args.includes('--cached')) return 'staged diff content\n';
+            if (args[0] === 'diff' && !args.includes('--cached') && !args.includes('--numstat')) return 'unstaged diff content\n';
+            return '';
+        });
+
+        const result = handleDiffCommand(['--full']);
+        expect(result.stagedDiff).toBe('staged diff content');
+        expect(result.unstagedDiff).toBe('unstaged diff content');
+    });
+
+    it('should filter by --file flag', () => {
+        mockExistsSync.mockImplementation((p: string) => p.endsWith('.git'));
+        mockExecFileSync.mockImplementation((cmd: string, args: string[]) => {
+            if (args.includes('--abbrev-ref')) return 'main\n';
+            if (args.includes('--left-right')) return '';
+            if (args.includes('--porcelain')) return 'M  target.ts\nM  other.ts\n';
+            return '';
+        });
+
+        const result = handleDiffCommand(['--file=target.ts']);
+        expect(result.staged.length).toBe(1);
+        expect(result.staged[0].file).toBe('target.ts');
+        // other.ts should be filtered out
+        expect(result.unstaged.length).toBe(0);
+    });
+
+    it('should use execFileSync (not execSync) to prevent shell injection', () => {
+        // Verify the module uses execFileSync by checking the import
+        // execFileSync takes command and args array separately — no shell interpretation
+        mockExistsSync.mockImplementation((p: string) => p.endsWith('.git'));
+        mockExecFileSync.mockImplementation(() => '');
+
+        handleDiffCommand([]);
+
+        // All calls should be to execFileSync (our mock), not execSync
+        expect(mockExecFileSync).toHaveBeenCalled();
+        // Verify args are passed as arrays (safe), not concatenated strings
+        for (const call of mockExecFileSync.mock.calls) {
+            expect(call[0]).toBe('git');
+            expect(Array.isArray(call[1])).toBe(true);
+        }
+    });
+
+    it('should handle no tracking info gracefully (ahead/behind = 0)', () => {
+        mockExistsSync.mockImplementation((p: string) => p.endsWith('.git'));
+        mockExecFileSync.mockImplementation((cmd: string, args: string[]) => {
+            if (args.includes('--abbrev-ref')) return 'main\n';
+            if (args.includes('--left-right')) return null; // no upstream
+            if (args.includes('--porcelain')) return '';
+            return '';
+        });
+
+        const result = handleDiffCommand([]);
+        expect(result.ahead).toBe(0);
+        expect(result.behind).toBe(0);
+    });
+
+    it('should handle empty git status (clean working directory)', () => {
+        mockExistsSync.mockImplementation((p: string) => p.endsWith('.git'));
+        mockExecFileSync.mockImplementation((cmd: string, args: string[]) => {
+            if (args.includes('--abbrev-ref')) return 'main\n';
+            if (args.includes('--left-right')) return '0\t0\n';
+            if (args.includes('--porcelain')) return '';
+            return null;
+        });
+
+        const result = handleDiffCommand([]);
+        expect(result.staged).toEqual([]);
+        expect(result.unstaged).toEqual([]);
+        expect(result.untracked).toEqual([]);
+    });
+
+    it('should not attach stagedDiff/unstagedDiff without --full flag', () => {
+        mockExistsSync.mockImplementation((p: string) => p.endsWith('.git'));
+        mockExecFileSync.mockImplementation((cmd: string, args: string[]) => {
+            if (args.includes('--abbrev-ref')) return 'main\n';
+            if (args.includes('--left-right')) return '';
+            if (args.includes('--porcelain')) return '';
+            return '';
+        });
+
+        const result = handleDiffCommand([]);
+        expect(result.stagedDiff).toBeUndefined();
+        expect(result.unstagedDiff).toBeUndefined();
+    });
+
+    it('should handle --full with --file to scope diff', () => {
+        mockExistsSync.mockImplementation((p: string) => p.endsWith('.git'));
+        mockExecFileSync.mockImplementation((cmd: string, args: string[]) => {
+            if (args.includes('--abbrev-ref')) return 'main\n';
+            if (args.includes('--left-right')) return '';
+            if (args.includes('--porcelain')) return '';
+            // When --full + --file=target.ts, diff args should include the file
+            if (args[0] === 'diff' && args.includes('target.ts')) return 'targeted diff\n';
+            if (args[0] === 'diff') return '';
+            return '';
+        });
+
+        const result = handleDiffCommand(['--full', '--file=target.ts']);
+        // The --file flag should cause diff to be scoped to target.ts
+        expect(result).toBeDefined();
+    });
+
+    it('should handle branch detection failure', () => {
+        mockExistsSync.mockImplementation((p: string) => p.endsWith('.git'));
+        mockExecFileSync.mockImplementation((cmd: string, args: string[]) => {
+            if (args.includes('--abbrev-ref')) { throw new Error('git failed'); }
+            if (args.includes('--left-right')) return null;
+            if (args.includes('--porcelain')) return '';
+            return null;
+        });
+
+        const result = handleDiffCommand([]);
+        expect(result.branch).toBe('unknown');
+    });
+});