aiseerr 1.0.0

package/src/cli.ts

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+/**
+ * Entry point for aiseerr.
+ * Parses raw `process.argv` and routes to command modules.
+ */
+
+import { outputError, outputSuccess } from './utils/output';
+import { handleEnvCommand } from './commands/env';
+import { handleTreeCommand } from './commands/tree';
+import { handleReadCommand } from './commands/read';
+import { handleDiffCommand } from './commands/diff';
+import { handleScoutCommand } from './commands/scout';
+import { handleInitCommand } from './commands/init';
+
+// Global error handler to guarantee valid JSON on crash
+process.on('uncaughtException', (err) => {
+    outputError(err, 1);
+});
+process.on('unhandledRejection', (err) => {
+    outputError(err, 1);
+});
+
+async function main() {
+    const args = process.argv.slice(2);
+
+    if (args.length === 0 || args[0] === 'help' || args.includes('--help') || args.includes('-h')) {
+        outputSuccess({
+            _help: "aiseerr: Structured Context Gathering for AI Agents",
+            commands: {
+                "scout": {
+                    usage: "aiseerr scout [--budget=N]",
+                    desc: "One-shot comprehensive environment scan. Bundles env, tree, readmes, diffs."
+                },
+                "env": {
+                    usage: "aiseerr env",
+                    desc: "Detect package manager, node version, frameworks, test setups."
+                },
+                "tree": {
+                    usage: "aiseerr tree [dir] [--depth=N] [--budget=N]",
+                    desc: "Explore directory structure with smart json compaction."
+                },
+                "read": {
+                    usage: "aiseerr read <file...> [--lines=N-M] [--keys=a,b] [--budget=N]",
+                    desc: "Extract exact files, specific line ranges, or json keys."
+                },
+                "diff": {
+                    usage: "aiseerr diff [--full] [--file=path]",
+                    desc: "Get git status, changed lines count, or full patch hunks."
+                },
+                "init": {
+                    usage: "aiseerr init [--format=cursorrules|claude|agents]",
+                    desc: "Auto-inject aiseerr usage instructions into project agent rules."
+                }
+            },
+            global_flags: {
+                "--budget=N": "Truncates/summarizes output to fit within N approximate tokens.",
+                "--pretty": "Human readable formatting (not recommended for AI LLMs natively)."
+            }
+        });
+        return;
+    }
+
+    const command = args[0];
+    const originalParams = args.slice(1);
+
+    // Extract global flags
+    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)) {
+                outputError('Invalid --budget value. Must be a number.', 1);
+            }
+        } else if (p === '--pretty') {
+            // handled globally in output.ts by inspecting process.argv
+        } else {
+            commandParams.push(p);
+        }
+    }
+
+    try {
+        let result: any;
+        switch (command) {
+            case 'scout':
+                result = handleScoutCommand(budget);
+                break;
+            case 'env':
+                result = handleEnvCommand();
+                break;
+            case 'tree':
+                result = handleTreeCommand(commandParams, budget);
+                break;
+            case 'read':
+                result = handleReadCommand(commandParams, budget);
+                break;
+            case 'diff':
+                result = handleDiffCommand(commandParams, budget);
+                break;
+            case 'init':
+                result = handleInitCommand(commandParams);
+                break;
+            default:
+                outputError(`Unknown command: ${command}`);
+                return;
+        }
+
+        // Commands return plain objects, we funnel them through the budget system
+        outputSuccess(result, budget);
+
+    } catch (error) {
+        outputError(error);
+    }
+}
+
+main();

package/src/commands/diff.ts

@@ -0,0 +1,128 @@
+import { execFileSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+const EXEC_TIMEOUT = 10000;
+
+function execSafe(command: string, args: string[]): string | null {
+    try {
+        return execFileSync(command, args, { stdio: 'pipe', encoding: 'utf-8', timeout: EXEC_TIMEOUT }).trim();
+    } catch {
+        return null;
+    }
+}
+
+export function handleDiffCommand(args: string[], budget?: number): any {
+    let fullDiff = false;
+    let targetFile: string | null = null;
+
+    for (const arg of args) {
+        if (arg === '--full') {
+            fullDiff = true;
+        } else if (arg.startsWith('--file=')) {
+            targetFile = arg.split('=')[1];
+        }
+    }
+
+    const cwd = process.cwd();
+    if (!existsSync(join(cwd, '.git'))) {
+        throw new Error('Not a git repository');
+    }
+
+    const branch = execSafe('git', ['rev-parse', '--abbrev-ref', 'HEAD']) || 'unknown';
+
+    // Get ahead/behind counts (rough fetch is not done here to keep it local/fast)
+    let ahead = 0;
+    let behind = 0;
+    const trackingInfo = execSafe('git', ['rev-list', '--left-right', '--count', 'HEAD...@{u}']);
+    if (trackingInfo) {
+        const parts = trackingInfo.split('\t');
+        if (parts.length === 2) {
+            ahead = parseInt(parts[0], 10) || 0;
+            behind = parseInt(parts[1], 10) || 0;
+        }
+    }
+
+    // Parse porcelain status
+    const statusOut = execSafe('git', ['status', '--porcelain']);
+    const staged: any[] = [];
+    const unstaged: any[] = [];
+    const untracked: string[] = [];
+
+    if (statusOut) {
+        const lines = statusOut.split('\n');
+        for (const line of lines) {
+            if (!line) continue;
+            const x = line[0];
+            const y = line[1];
+            const file = line.slice(3);
+
+            if (targetFile && file !== targetFile) continue;
+
+            if (x === '?' && y === '?') {
+                untracked.push(file);
+            } else {
+                if (x !== ' ' && x !== '?') {
+                    staged.push({ file, status: x });
+                }
+                if (y !== ' ' && y !== '?') {
+                    unstaged.push({ file, status: y });
+                }
+            }
+        }
+    }
+
+    // Augment with numstat
+    const numStatStaged = execSafe('git', ['diff', '--cached', '--numstat']);
+    if (numStatStaged) {
+        const lines = numStatStaged.split('\n');
+        for (const line of lines) {
+            if (!line) continue;
+            const [ins, del, file] = line.split('\t');
+            const entry = staged.find(s => s.file === file);
+            if (entry) {
+                entry.insertions = parseInt(ins, 10) || 0;
+                entry.deletions = parseInt(del, 10) || 0;
+            }
+        }
+    }
+
+    const numStatUnstaged = execSafe('git', ['diff', '--numstat']);
+    if (numStatUnstaged) {
+        const lines = numStatUnstaged.split('\n');
+        for (const line of lines) {
+            if (!line) continue;
+            const [ins, del, file] = line.split('\t');
+            const entry = unstaged.find(s => s.file === file);
+            if (entry) {
+                entry.insertions = parseInt(ins, 10) || 0;
+                entry.deletions = parseInt(del, 10) || 0;
+            }
+        }
+    }
+
+    const result: any = {
+        branch,
+        ahead,
+        behind,
+        staged,
+        unstaged,
+        untracked
+    };
+
+    // If --full is requested, pull the actual diff content
+    if (fullDiff) {
+        const diffArgs = targetFile ? ['diff', targetFile] : ['diff'];
+        const diffStagedArgs = targetFile ? ['diff', '--cached', targetFile] : ['diff', '--cached'];
+
+        const fullDiffOut = execSafe('git', diffArgs);
+        const fullDiffStagedOut = execSafe('git', diffStagedArgs);
+
+        // We attach the raw unified diff string rather than parsing hunks to save overhead
+        // LLMs are perfectly capable of reading raw unified diffs, making custom hunk parsing redundant for v1
+        if (fullDiffStagedOut) result.stagedDiff = fullDiffStagedOut;
+        if (fullDiffOut) result.unstagedDiff = fullDiffOut;
+    }
+
+    return result;
+}

package/src/commands/env.ts

@@ -0,0 +1,234 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { execFileSync } from 'child_process';
+
+/**
+ * Executes a child process purely for simple string returns
+ * Used for fast probes like git status
+ */
+const EXEC_TIMEOUT = 10000;
+
+function execSafe(command: string, args: string[]): string | null {
+    try {
+        return execFileSync(command, args, { stdio: 'pipe', encoding: 'utf-8', timeout: EXEC_TIMEOUT }).trim();
+    } catch {
+        return null;
+    }
+}
+
+interface ShellInfo {
+    name: string;
+    path: string | null;
+    chain: string;
+    setEnv: string;
+    pathSep: string;
+    pitfalls: string[];
+}
+
+function detectShell(): ShellInfo {
+    const platform = process.platform;
+
+    // Check common shell env vars (order matters)
+    const shell = process.env.SHELL           // unix default
+        || process.env.PSModulePath && 'powershell'  // PowerShell sets this
+        || process.env.ComSpec                  // cmd.exe fallback
+        || '';
+
+    const shellLower = shell.toLowerCase();
+
+    // PowerShell detection (works on both Windows and Unix)
+    if (process.env.PSModulePath || shellLower.includes('pwsh') || shellLower.includes('powershell')) {
+        return {
+            name: shellLower.includes('pwsh') ? 'pwsh' : 'powershell',
+            path: shell === 'powershell' ? null : shell,
+            chain: ';',
+            setEnv: '$env:VAR="value"',
+            pathSep: '\\',
+            pitfalls: [
+                '`&&` does NOT work in PowerShell 5.x. Use `;` or `pwsh 7+`.',
+                'Use `$env:VAR` instead of `export VAR=` or `set VAR=`.',
+                'Backtick ` is the escape char, not backslash.',
+                'Single quotes are literal strings; double quotes allow interpolation.',
+            ]
+        };
+    }
+
+    if (shellLower.includes('fish')) {
+        return {
+            name: 'fish',
+            path: shell,
+            chain: '; and',
+            setEnv: 'set -x VAR value',
+            pathSep: '/',
+            pitfalls: [
+                '`&&` and `||` are NOT supported. Use `; and` / `; or`.',
+                'Use `set -x VAR value` instead of `export VAR=value`.',
+                'Subshells `$(...)` are not supported. Use `(command)` instead.',
+            ]
+        };
+    }
+
+    if (shellLower.includes('zsh')) {
+        return {
+            name: 'zsh',
+            path: shell,
+            chain: '&&',
+            setEnv: 'export VAR="value"',
+            pathSep: '/',
+            pitfalls: [
+                'Array indexing starts at 1, not 0 (unlike bash).',
+            ]
+        };
+    }
+
+    if (shellLower.includes('bash') || shellLower.includes('sh')) {
+        return {
+            name: shellLower.includes('bash') ? 'bash' : 'sh',
+            path: shell,
+            chain: '&&',
+            setEnv: 'export VAR="value"',
+            pathSep: '/',
+            pitfalls: []
+        };
+    }
+
+    // Windows cmd.exe
+    if (platform === 'win32' && (shellLower.includes('cmd') || !process.env.SHELL)) {
+        return {
+            name: 'cmd',
+            path: shell || 'C:\\Windows\\System32\\cmd.exe',
+            chain: '&&',
+            setEnv: 'set VAR=value',
+            pathSep: '\\',
+            pitfalls: [
+                'Use `set VAR=value` instead of `export`.',
+                'No native support for `$(...)` subshells.',
+                'Use `%VAR%` to expand env vars, not `$VAR`.',
+            ]
+        };
+    }
+
+    // Unknown fallback
+    return {
+        name: 'unknown',
+        path: shell || null,
+        chain: '&&',
+        setEnv: 'export VAR="value"',
+        pathSep: platform === 'win32' ? '\\' : '/',
+        pitfalls: ['Shell could not be detected. Assume POSIX-compatible.']
+    };
+}
+
+export function handleEnvCommand(): any {
+    const cwd = process.cwd();
+    const pkgPath = join(cwd, 'package.json');
+
+    if (!existsSync(pkgPath)) {
+        return {
+            os: { platform: process.platform, arch: process.arch },
+            shell: detectShell(),
+            packageManager: null,
+            node: { version: process.version, engines: undefined },
+            frameworks: [],
+            scripts: {},
+            _note: 'Not a Node.js project: package.json not found.'
+        };
+    }
+
+    let pkg: any;
+    try {
+        pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    } catch (e) {
+        throw new Error('Failed to parse package.json.');
+    }
+
+    // 1. Package Manager Detection
+    let pmInfo = { name: 'npm', version: 'unknown' };
+    if (existsSync(join(cwd, 'pnpm-lock.yaml'))) {
+        pmInfo.name = 'pnpm';
+        const ver = execSafe('pnpm', ['--version']);
+        if (ver) pmInfo.version = ver;
+    } else if (existsSync(join(cwd, 'yarn.lock'))) {
+        pmInfo.name = 'yarn';
+        const ver = execSafe('yarn', ['--version']);
+        if (ver) pmInfo.version = ver;
+    } else if (existsSync(join(cwd, 'bun.lockb'))) {
+        pmInfo.name = 'bun';
+        const ver = execSafe('bun', ['--version']);
+        if (ver) pmInfo.version = ver;
+    } else {
+        // default to npm
+        const ver = execSafe('npm', ['--version']);
+        if (ver) pmInfo.version = ver;
+    }
+
+    // 2. Node Version
+    const nodeInfo = {
+        version: process.version,
+        engines: pkg.engines?.node
+    };
+
+    // 3. Frameworks
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    const allDeps = Object.keys(deps);
+    const knownFrameworks = ['react', 'vue', 'next', 'nuxt', 'svelte', 'express', 'nestjs', 'tailwindcss', 'prisma', 'vite', 'webpack'];
+    const detectedFrameworks = knownFrameworks.filter(f => allDeps.includes(f));
+
+    // 4. Test Framework
+    let testFramework = null;
+    if (allDeps.includes('vitest')) {
+        testFramework = {
+            name: 'vitest',
+            runCommand: `npx vitest run --reporter=json`,
+            parseHint: `Look for 'testResults[].assertionResults[].failureMessages'`
+        };
+    } else if (allDeps.includes('jest')) {
+        testFramework = {
+            name: 'jest',
+            runCommand: `npx jest --json`,
+            parseHint: `Look for 'testResults[].assertionResults[].failureMessages'`
+        };
+    }
+
+    // 5. Lint Framework
+    let lintFramework = null;
+    if (allDeps.includes('eslint')) {
+        lintFramework = {
+            name: 'eslint',
+            runCommand: `npx eslint . --format=json`,
+            parseHint: `Array of objects with 'filePath' and 'messages[]'`
+        };
+    }
+
+    // 6. Git Status
+    let git = null;
+    if (existsSync(join(cwd, '.git'))) {
+        const branch = execSafe('git', ['rev-parse', '--abbrev-ref', 'HEAD']);
+        const status = execSafe('git', ['status', '--porcelain']);
+        const remote = execSafe('git', ['config', '--get', 'remote.origin.url']);
+        git = {
+            branch: branch || 'unknown',
+            hasUncommitted: !!status,
+            remoteUrl: remote || null
+        };
+    }
+
+    const result: any = {
+        os: { platform: process.platform, arch: process.arch },
+        shell: detectShell(),
+        packageManager: pmInfo,
+        node: nodeInfo,
+        frameworks: detectedFrameworks,
+        scripts: pkg.scripts || {},
+    };
+
+    if (pkg.workspaces) {
+        result.workspaces = pkg.workspaces;
+    }
+
+    if (testFramework) result.testFramework = testFramework;
+    if (lintFramework) result.lintFramework = lintFramework;
+    if (git) result.git = git;
+
+    return result;
+}

package/src/commands/init.ts

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+export function handleInitCommand(args: string[]): any {
+    let format: string | null = null;
+    for (const arg of args) {
+        if (arg.startsWith('--format=')) {
+            format = arg.split('=')[1];
+        }
+    }
+
+    const cwd = process.cwd();
+
+    const injectTemplate = `
+<!-- aiseerr:start -->
+## Project Context Protocol (powered by aiseerr)
+
+Before modifying this project, gather context by running:
+  npx aiseerr scout --budget=2000
+
+When debugging a failing test:
+  npx aiseerr read <file> --lines=<error-range>
+
+Before committing changes:
+  npx aiseerr diff --full
+<!-- aiseerr:end -->
+`;
+
+    const filesToSearch = [
+        'AGENTS.md',
+        'CLAUDE.md',
+        '.cursorrules',
+        '.github/copilot-instructions.md'
+    ];
+
+    let targetFile = 'AGENTS.md'; // Default fallback
+
+    if (format) {
+        if (format === 'claude') targetFile = 'CLAUDE.md';
+        else if (format === 'cursorrules') targetFile = '.cursorrules';
+        else if (format === 'agents') targetFile = 'AGENTS.md';
+        else throw new Error(`Unknown format: ${format}`);
+    } else {
+        // Smart Detection
+        for (const f of filesToSearch) {
+            if (existsSync(join(cwd, f))) {
+                targetFile = f;
+                break;
+            }
+        }
+    }
+
+    const targetPath = join(cwd, targetFile);
+    let action = 'created';
+    let linesAdded = injectTemplate.trim().split('\n').length;
+
+    if (existsSync(targetPath)) {
+        const existingContent = readFileSync(targetPath, 'utf-8');
+        if (existingContent.includes('<!-- aiseerr:start -->')) {
+            return {
+                action: 'skipped',
+                target: targetFile,
+                reason: 'Already injected'
+            };
+        } else {
+            writeFileSync(targetPath, existingContent + '\n' + injectTemplate.trim() + '\n', 'utf-8');
+            action = 'injected';
+        }
+    } else {
+        // In creation mode, maybe add a generic title
+        const content = `# AI Agent Rules\n\n${injectTemplate.trim()}\n`;
+        writeFileSync(targetPath, content, 'utf-8');
+        linesAdded = content.trim().split('\n').length;
+    }
+
+    return {
+        action,
+        target: targetFile,
+        linesAdded,
+        marker: 'aiseerr:start'
+    };
+}

package/src/commands/read.ts

@@ -0,0 +1,113 @@
+import { readFileSync, existsSync, statSync } from 'fs';
+import { estimateTokens } from '../utils/output';
+
+export function handleReadCommand(args: string[], budget?: number): any {
+    let linesRange: [number, number] | null = null;
+    let keysExtract: string[] | null = null;
+    const files: string[] = [];
+
+    for (const arg of args) {
+        if (arg.startsWith('--lines=')) {
+            const parts = arg.split('=')[1].split('-');
+            if (parts.length === 2) {
+                linesRange = [parseInt(parts[0], 10), parseInt(parts[1], 10)];
+            }
+        } else if (arg.startsWith('--keys=')) {
+            keysExtract = arg.split('=')[1].split(',').map(k => k.trim());
+        } else if (!arg.startsWith('--')) {
+            files.push(arg);
+        }
+    }
+
+    if (files.length === 0) {
+        throw new Error('No files provided to read.');
+    }
+
+    const results = [];
+    let currentEstimatedTokens = 0;
+
+    for (const file of files) {
+        if (!existsSync(file)) {
+            results.push({ file, error: 'File not found' });
+            continue;
+        }
+        const stat = statSync(file);
+        if (stat.isDirectory()) {
+            results.push({ file, error: 'Target is a directory, not a file' });
+            continue;
+        }
+
+        try {
+            const rawContent = readFileSync(file, 'utf-8');
+            const linesCount = rawContent.split('\n').length;
+            let finalContent: any = rawContent;
+            let isTruncated = false;
+            let contextMeta: any = undefined;
+
+            // JSON Keys Extraction Mode
+            if (keysExtract && file.endsWith('.json')) {
+                try {
+                    const parsed = JSON.parse(rawContent);
+                    const extracted: Record<string, any> = {};
+                    for (const k of keysExtract) {
+                        if (k in parsed) extracted[k] = parsed[k];
+                    }
+                    finalContent = extracted;
+                } catch {
+                    // Fallback to text if parsing fails
+                }
+            }
+            // Line Range Mode
+            else if (linesRange && typeof finalContent === 'string') {
+                const [start, end] = linesRange;
+                const lines = rawContent.split('\n');
+                // 1-indexed for users
+                const slice = lines.slice(Math.max(0, start - 1), end);
+                finalContent = slice.join('\n');
+                contextMeta = { range: [start, Math.min(end, lines.length)] };
+            }
+
+            // Check purely text tokens against remaining budget
+            if (budget && typeof finalContent === 'string') {
+                const fileTokens = estimateTokens(finalContent);
+                if (currentEstimatedTokens + fileTokens > budget) {
+                    // How much budget do we have left for this file?
+                    const remainingTokens = Math.max(0, budget - currentEstimatedTokens);
+                    // Roughly 4 chars per token
+                    const charLimit = remainingTokens * 4;
+
+                    if (charLimit < 50) {
+                        // Not enough room even for a snippet
+                        results.push({ file, lines: linesCount, error: 'Skipped due to token budget limits' });
+                        break; // Stop processing further files
+                    } else {
+                        finalContent = finalContent.slice(0, charLimit) + '\n...[TRUNCATED BY BUDGET]';
+                        isTruncated = true;
+                    }
+                }
+                currentEstimatedTokens += estimateTokens(finalContent);
+            }
+
+            const fileObj: any = {
+                file,
+                lines: linesCount,
+                content: finalContent
+            };
+
+            if (contextMeta) fileObj.context = contextMeta;
+            if (isTruncated) fileObj.truncated = true;
+
+            results.push(fileObj);
+
+        } catch (e: any) {
+            results.push({ file, error: e.message || 'Failed to read file' });
+        }
+    }
+
+    // If only one file requested, return just that object to save tokens
+    if (files.length === 1 && results.length === 1) {
+        return results[0];
+    }
+
+    return { files: results };
+}