@manishbht/helpcode 0.2.2

package/dist/src/core/state.js

@@ -0,0 +1,63 @@
+/**
+ * Persistent agent state. Stored at .helpcode/state.json.
+ *
+ * State is intentionally readable JSON. Users can `cat` it to see exactly
+ * what helpcode is thinking. No black-box memory.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { HelpcodeError, ErrorCode } from '../lib/errors.js';
+const STATE_DIR = '.helpcode';
+const STATE_FILE = path.join(STATE_DIR, 'state.json');
+function emptyState() {
+    return {
+        version: 1,
+        currentTask: null,
+        history: [],
+    };
+}
+export function loadState(cwd = process.cwd()) {
+    const file = path.join(cwd, STATE_FILE);
+    if (!fs.existsSync(file)) {
+        return emptyState();
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (parsed.version !== 1) {
+            throw new HelpcodeError(ErrorCode.STATE_ERROR, `Unknown state version: ${parsed.version}`, 'This state was written by a different helpcode version. Run `helpcode reset` to start fresh.');
+        }
+        return parsed;
+    }
+    catch (e) {
+        if (e instanceof HelpcodeError)
+            throw e;
+        throw new HelpcodeError(ErrorCode.STATE_ERROR, `Could not parse state file: ${e.message}`, 'Run `helpcode reset` to start fresh (this won\'t touch your code).');
+    }
+}
+export function saveState(state, cwd = process.cwd()) {
+    const dir = path.join(cwd, STATE_DIR);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(cwd, STATE_FILE);
+    const tmp = `${file}.${Math.random().toString(36).slice(2)}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf-8');
+    fs.renameSync(tmp, file);
+}
+export function createTask(description) {
+    const now = new Date().toISOString();
+    return {
+        id: `task-${now.replace(/[:.]/g, '-')}`,
+        description,
+        createdAt: now,
+        iterations: 0,
+        status: 'idle',
+        lastPrompt: null,
+        lastResponseRaw: null,
+        lastTestOutput: null,
+        lastDiffsApplied: [],
+    };
+}
+export function resetState(cwd = process.cwd()) {
+    saveState(emptyState(), cwd);
+}
+//# sourceMappingURL=state.js.map

package/dist/src/core/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/core/state.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE5D,MAAM,SAAS,GAAG,WAAW,CAAC;AAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;AAEtD,SAAS,UAAU;IACjB,OAAO;QACL,OAAO,EAAE,CAAC;QACV,WAAW,EAAE,IAAI;QACjB,OAAO,EAAE,EAAE;KACZ,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,MAAc,OAAO,CAAC,GAAG,EAAE;IACnD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO,UAAU,EAAE,CAAC;IACtB,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;QAC1D,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,aAAa,CACrB,SAAS,CAAC,WAAW,EACrB,0BAA0B,MAAM,CAAC,OAAO,EAAE,EAC1C,8FAA8F,CAC/F,CAAC;QACJ,CAAC;QACD,OAAO,MAAoB,CAAC;IAC9B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,aAAa;YAAE,MAAM,CAAC,CAAC;QACxC,MAAM,IAAI,aAAa,CACrB,SAAS,CAAC,WAAW,EACrB,+BAAgC,CAAW,CAAC,OAAO,EAAE,EACrD,oEAAoE,CACrE,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAiB,EAAE,MAAc,OAAO,CAAC,GAAG,EAAE;IACtE,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACtC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;IACjE,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC/D,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,WAAmB;IAC5C,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,OAAO;QACL,EAAE,EAAE,QAAQ,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE;QACvC,WAAW;QACX,SAAS,EAAE,GAAG;QACd,UAAU,EAAE,CAAC;QACb,MAAM,EAAE,MAAM;QACd,UAAU,EAAE,IAAI;QAChB,eAAe,EAAE,IAAI;QACrB,cAAc,EAAE,IAAI;QACpB,gBAAgB,EAAE,EAAE;KACrB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAc,OAAO,CAAC,GAAG,EAAE;IACpD,SAAS,CAAC,UAAU,EAAE,EAAE,GAAG,CAAC,CAAC;AAC/B,CAAC"}

package/dist/src/core/tools.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Tool runner. Spawns subprocesses and captures their output in a
+ * helpcode-friendly form.
+ *
+ * - Cross-platform (uses spawn directly, no shell unless asked)
+ * - Timeout enforced
+ * - Returns structured result so callers can decide what to display
+ */
+export interface CommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+    timedOut: boolean;
+}
+export interface RunOptions {
+    /** Timeout in seconds. Defaults to 60. */
+    timeoutSecs?: number;
+    /** Working directory. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Environment variables to merge into the subprocess env. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Run a shell command (parsed by the OS shell) and return its result.
+ * On Windows this uses cmd.exe, on POSIX it uses bash via `/bin/sh -c`.
+ */
+export declare function runShellCommand(command: string, opts?: RunOptions): Promise<CommandResult>;
+/**
+ * Run a process by argv (no shell). Use this when you control the args.
+ */
+export declare function runProcess(cmd: string, args: string[], opts?: RunOptions): Promise<CommandResult>;

package/dist/src/core/tools.js

@@ -0,0 +1,67 @@
+/**
+ * Tool runner. Spawns subprocesses and captures their output in a
+ * helpcode-friendly form.
+ *
+ * - Cross-platform (uses spawn directly, no shell unless asked)
+ * - Timeout enforced
+ * - Returns structured result so callers can decide what to display
+ */
+import { spawn } from 'child_process';
+/**
+ * Run a shell command (parsed by the OS shell) and return its result.
+ * On Windows this uses cmd.exe, on POSIX it uses bash via `/bin/sh -c`.
+ */
+export async function runShellCommand(command, opts = {}) {
+    const isWindows = process.platform === 'win32';
+    const shell = isWindows ? 'cmd.exe' : '/bin/sh';
+    const shellFlag = isWindows ? '/c' : '-c';
+    return runProcess(shell, [shellFlag, command], opts);
+}
+/**
+ * Run a process by argv (no shell). Use this when you control the args.
+ */
+export async function runProcess(cmd, args, opts = {}) {
+    const timeoutMs = (opts.timeoutSecs ?? 60) * 1000;
+    const start = Date.now();
+    return new Promise(resolve => {
+        const child = spawn(cmd, args, {
+            cwd: opts.cwd ?? process.cwd(),
+            env: { ...process.env, ...opts.env },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: false,
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* ignore */ }
+        }, timeoutMs);
+        child.stdout?.on('data', (d) => stdoutChunks.push(d));
+        child.stderr?.on('data', (d) => stderrChunks.push(d));
+        child.on('error', err => {
+            clearTimeout(timer);
+            resolve({
+                exitCode: 127,
+                stdout: '',
+                stderr: `Failed to start: ${err.message}`,
+                durationMs: Date.now() - start,
+                timedOut: false,
+            });
+        });
+        child.on('close', exitCode => {
+            clearTimeout(timer);
+            resolve({
+                exitCode: timedOut ? 124 : (exitCode ?? 0),
+                stdout: Buffer.concat(stdoutChunks).toString('utf-8'),
+                stderr: Buffer.concat(stderrChunks).toString('utf-8'),
+                durationMs: Date.now() - start,
+                timedOut,
+            });
+        });
+    });
+}
+//# sourceMappingURL=tools.js.map

package/dist/src/core/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/core/tools.ts"],"names":[],"mappings":"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"}

package/dist/src/core/triage.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Output triage (v0.2.x) — the second local-LLM task after file selection.
+ *
+ * Long command output (a 200-line pytest dump, a webpack error wall) bloats
+ * the next Claude brief and buries the signal. helpcode already truncates
+ * deterministically (head + tail). When Ollama is available, we can do
+ * better: ask a local model to extract the key failure(s) so the brief stays
+ * tight and on-point.
+ *
+ * Same contract as the selector: the LLM is a free upgrade. If Ollama is
+ * disabled, unreachable, slow, errors, or returns nothing useful, we fall
+ * back to the existing deterministic truncation. Triage NEVER loses the
+ * output entirely — worst case you get the same truncation as before.
+ */
+import { OllamaSettings } from '../types.js';
+export interface TriageResult {
+    /** The compacted output to put in the brief. */
+    text: string;
+    /** True if the local model produced the summary; false if fallback. */
+    triaged: boolean;
+}
+type GenerateImpl = (host: string, model: string, prompt: string, opts?: {
+    timeoutMs?: number;
+}) => Promise<string>;
+export interface TriageDeps {
+    /** Injectable model call for testing. Defaults to the real Ollama client. */
+    generateImpl?: GenerateImpl;
+}
+/** Is this output worth sending to the model? Long, and Ollama enabled. */
+export declare function shouldTriage(output: string, ollama: Pick<OllamaSettings, 'enabled'>): boolean;
+export declare function buildTriagePrompt(output: string): string;
+/**
+ * Triage command output. Returns a compacted version plus whether the model
+ * was used. Never throws — any failure falls back to deterministic truncation.
+ */
+export declare function triageOutput(output: string, ollama: OllamaSettings, deps?: TriageDeps): Promise<TriageResult>;
+export {};

package/dist/src/core/triage.js

@@ -0,0 +1,69 @@
+/**
+ * Output triage (v0.2.x) — the second local-LLM task after file selection.
+ *
+ * Long command output (a 200-line pytest dump, a webpack error wall) bloats
+ * the next Claude brief and buries the signal. helpcode already truncates
+ * deterministically (head + tail). When Ollama is available, we can do
+ * better: ask a local model to extract the key failure(s) so the brief stays
+ * tight and on-point.
+ *
+ * Same contract as the selector: the LLM is a free upgrade. If Ollama is
+ * disabled, unreachable, slow, errors, or returns nothing useful, we fall
+ * back to the existing deterministic truncation. Triage NEVER loses the
+ * output entirely — worst case you get the same truncation as before.
+ */
+import { generate, OllamaError } from './ollama.js';
+import { truncateLines } from '../lib/compress.js';
+/** Output longer than this (lines) is a candidate for triage. */
+const TRIAGE_THRESHOLD_LINES = 30;
+/** Deterministic fallback truncation cap. */
+const FALLBACK_MAX_LINES = 40;
+/** Is this output worth sending to the model? Long, and Ollama enabled. */
+export function shouldTriage(output, ollama) {
+    if (!ollama.enabled)
+        return false;
+    return output.split(/\r?\n/).length > TRIAGE_THRESHOLD_LINES;
+}
+export function buildTriagePrompt(output) {
+    return [
+        'The following is output from running a command (often a test run or build).',
+        'Extract ONLY the information needed to understand and fix any failure:',
+        '- which test(s) or step(s) failed, and the exact error message',
+        '- the file and line if present',
+        'Omit passing tests, setup banners, and noise. If everything passed, say so in one line.',
+        'Be concise — a few lines at most. No preamble.',
+        '',
+        '--- OUTPUT ---',
+        output,
+        '--- END OUTPUT ---',
+    ].join('\n');
+}
+/**
+ * Triage command output. Returns a compacted version plus whether the model
+ * was used. Never throws — any failure falls back to deterministic truncation.
+ */
+export async function triageOutput(output, ollama, deps = {}) {
+    // Short output, or triage disabled: return as-is or truncate, no model.
+    if (!shouldTriage(output, ollama)) {
+        const lineCount = output.split(/\r?\n/).length;
+        const text = lineCount > FALLBACK_MAX_LINES
+            ? truncateLines(output, FALLBACK_MAX_LINES, 'lines')
+            : output;
+        return { text, triaged: false };
+    }
+    const generateImpl = deps.generateImpl ?? generate;
+    try {
+        const summary = await generateImpl(ollama.host, ollama.model, buildTriagePrompt(output), { timeoutMs: ollama.timeoutMs });
+        if (summary && summary.trim().length > 0) {
+            return { text: summary.trim(), triaged: true };
+        }
+        // Empty model result: fall back.
+        return { text: truncateLines(output, FALLBACK_MAX_LINES, 'lines'), triaged: false };
+    }
+    catch (e) {
+        // Transport/timeout/etc.: fall back to deterministic truncation.
+        void (e instanceof OllamaError);
+        return { text: truncateLines(output, FALLBACK_MAX_LINES, 'lines'), triaged: false };
+    }
+}
+//# sourceMappingURL=triage.js.map

package/dist/src/core/triage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"triage.js","sourceRoot":"","sources":["../../../src/core/triage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,iEAAiE;AACjE,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAClC,6CAA6C;AAC7C,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAqB9B,2EAA2E;AAC3E,MAAM,UAAU,YAAY,CAC1B,MAAc,EACd,MAAuC;IAEvC,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAClC,OAAO,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,sBAAsB,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,OAAO;QACL,6EAA6E;QAC7E,wEAAwE;QACxE,gEAAgE;QAChE,gCAAgC;QAChC,yFAAyF;QACzF,gDAAgD;QAChD,EAAE;QACF,gBAAgB;QAChB,MAAM;QACN,oBAAoB;KACrB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAc,EACd,MAAsB,EACtB,OAAmB,EAAE;IAErB,wEAAwE;IACxE,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;QAC/C,MAAM,IAAI,GAAG,SAAS,GAAG,kBAAkB;YACzC,CAAC,CAAC,aAAa,CAAC,MAAM,EAAE,kBAAkB,EAAE,OAAO,CAAC;YACpD,CAAC,CAAC,MAAM,CAAC;QACX,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAClC,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,QAAQ,CAAC;IACnD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,YAAY,CAChC,MAAM,CAAC,IAAI,EACX,MAAM,CAAC,KAAK,EACZ,iBAAiB,CAAC,MAAM,CAAC,EACzB,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAChC,CAAC;QACF,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACjD,CAAC;QACD,iCAAiC;QACjC,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,MAAM,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACtF,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,iEAAiE;QACjE,KAAK,CAAC,CAAC,YAAY,WAAW,CAAC,CAAC;QAChC,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,MAAM,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACtF,CAAC;AACH,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * helpcode — CLI router.
+ *
+ * Six commands, kept deliberately small:
+ *   init    detect project and set up .helpcode/
+ *   ask     compose a prompt for Claude.ai
+ *   apply   apply Claude's reply
+ *   run     run a shell command, get compact output
+ *   status  show current state
+ *   reset   clear state
+ */
+export declare function run(argv: string[]): Promise<number>;

package/dist/src/index.js

@@ -0,0 +1,120 @@
+/**
+ * helpcode — CLI router.
+ *
+ * Six commands, kept deliberately small:
+ *   init    detect project and set up .helpcode/
+ *   ask     compose a prompt for Claude.ai
+ *   apply   apply Claude's reply
+ *   run     run a shell command, get compact output
+ *   status  show current state
+ *   reset   clear state
+ */
+import { handleInit } from './commands/init.js';
+import { handleAsk } from './commands/ask.js';
+import { handleApply } from './commands/apply.js';
+import { handleRun } from './commands/run.js';
+import { handleStatus } from './commands/status.js';
+import { handleReset } from './commands/reset.js';
+import { HelpcodeError } from './lib/errors.js';
+import { c, log } from './lib/ui.js';
+const VERSION = '0.2.2';
+const HELP = `helpcode v${VERSION}
+
+A local agent that makes Claude.ai conversations efficient enough to ship
+real projects on a Pro subscription.
+
+USAGE:
+  helpcode <command> [options]
+
+COMMANDS:
+  init                       Detect this project and set up .helpcode/
+  ask "<task>" [options]     Compose a Claude prompt for the given task
+       --files <paths...>      include specific files (skips auto-selection)
+       --no-llm                force keyword selection even if Ollama is on
+       --explain-selection     show why each file was chosen
+  apply [--yes] [--dry-run]  Apply Claude's pasted reply (from stdin)
+  run "<command>"            Run a shell command, get compact output
+  status                     Show current task and state
+  reset [--yes]              Clear state (project config is untouched)
+
+GLOBAL FLAGS:
+  --version                  Print version and exit
+  --help                     Show this help
+
+Read more: https://github.com/USER/helpcode
+`;
+export async function run(argv) {
+    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+        console.log(HELP);
+        return 0;
+    }
+    if (argv.includes('--version') || argv.includes('-v')) {
+        console.log(VERSION);
+        return 0;
+    }
+    const [cmd, ...rest] = argv;
+    try {
+        switch (cmd) {
+            case 'init':
+                return await handleInit({ force: rest.includes('--force') });
+            case 'ask': {
+                const files = extractFlagValues(rest, '--files');
+                const task = rest.filter(a => !a.startsWith('--') && !files.includes(a)).join(' ');
+                return await handleAsk(task, {
+                    files: files.length ? files : undefined,
+                    noLlm: rest.includes('--no-llm'),
+                    explainSelection: rest.includes('--explain-selection'),
+                });
+            }
+            case 'apply':
+                return await handleApply({
+                    yes: rest.includes('--yes'),
+                    dryRun: rest.includes('--dry-run'),
+                });
+            case 'run': {
+                const command = rest.filter(a => !a.startsWith('--')).join(' ');
+                const timeout = extractFlagInt(rest, '--timeout');
+                return await handleRun(command, timeout !== null ? { timeout } : {});
+            }
+            case 'status':
+                return await handleStatus();
+            case 'reset':
+                return await handleReset({ yes: rest.includes('--yes') });
+            default:
+                log.err(`Unknown command: ${cmd}`);
+                console.log();
+                console.log(HELP);
+                return 1;
+        }
+    }
+    catch (e) {
+        if (e instanceof HelpcodeError) {
+            log.err(e.message);
+            if (e.hint)
+                console.log(c.dim('  ' + e.hint));
+            return 1;
+        }
+        log.err(e.message);
+        return 1;
+    }
+}
+function extractFlagValues(args, flag) {
+    const idx = args.indexOf(flag);
+    if (idx === -1)
+        return [];
+    const values = [];
+    for (let i = idx + 1; i < args.length; i++) {
+        if (args[i].startsWith('--'))
+            break;
+        values.push(args[i]);
+    }
+    return values;
+}
+function extractFlagInt(args, flag) {
+    const idx = args.indexOf(flag);
+    if (idx === -1 || idx + 1 >= args.length)
+        return null;
+    const n = parseInt(args[idx + 1], 10);
+    return Number.isNaN(n) ? null : n;
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,OAAO,GAAG,OAAO,CAAC;AAExB,MAAM,IAAI,GAAG,aAAa,OAAO;;;;;;;;;;;;;;;;;;;;;;;;CAwBhC,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,IAAc;IACtC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACxE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACtD,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAE5B,IAAI,CAAC;QACH,QAAQ,GAAG,EAAE,CAAC;YACZ,KAAK,MAAM;gBACT,OAAO,MAAM,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YAE/D,KAAK,KAAK,CAAC,CAAC,CAAC;gBACX,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;gBACjD,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACnF,OAAO,MAAM,SAAS,CAAC,IAAI,EAAE;oBAC3B,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;oBACvC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC;oBAChC,gBAAgB,EAAE,IAAI,CAAC,QAAQ,CAAC,qBAAqB,CAAC;iBACvD,CAAC,CAAC;YACL,CAAC;YAED,KAAK,OAAO;gBACV,OAAO,MAAM,WAAW,CAAC;oBACvB,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;oBAC3B,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;iBACnC,CAAC,CAAC;YAEL,KAAK,KAAK,CAAC,CAAC,CAAC;gBACX,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAChE,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;gBAClD,OAAO,MAAM,SAAS,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACvE,CAAC;YAED,KAAK,QAAQ;gBACX,OAAO,MAAM,YAAY,EAAE,CAAC;YAE9B,KAAK,OAAO;gBACV,OAAO,MAAM,WAAW,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAE5D;gBACE,GAAG,CAAC,GAAG,CAAC,oBAAoB,GAAG,EAAE,CAAC,CAAC;gBACnC,OAAO,CAAC,GAAG,EAAE,CAAC;gBACd,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBAClB,OAAO,CAAC,CAAC;QACb,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,aAAa,EAAE,CAAC;YAC/B,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YACnB,IAAI,CAAC,CAAC,IAAI;gBAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YAC9C,OAAO,CAAC,CAAC;QACX,CAAC;QACD,GAAG,CAAC,GAAG,CAAE,CAAW,CAAC,OAAO,CAAC,CAAC;QAC9B,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAc,EAAE,IAAY;IACrD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,MAAM;QACpC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,cAAc,CAAC,IAAc,EAAE,IAAY;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACtD,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACtC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC"}

package/dist/src/lib/compress.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compression helpers — make long process output fit in a Claude prompt
+ * without losing the signal.
+ */
+/**
+ * If `text` exceeds `maxLines`, keep the first third and last two-thirds,
+ * replacing the middle with a one-line summary of what was omitted.
+ */
+export declare function truncateLines(text: string, maxLines?: number, label?: string): string;
+/**
+ * If stderr contains a Python traceback, return just the traceback (trimmed).
+ * Otherwise return the stderr trimmed to `maxLines`.
+ */
+export declare function extractTraceback(stderr: string, maxLines?: number): string;

package/dist/src/lib/compress.js

@@ -0,0 +1,35 @@
+/**
+ * Compression helpers — make long process output fit in a Claude prompt
+ * without losing the signal.
+ */
+const DEFAULT_MAX_LINES = 40;
+const DEFAULT_TRACEBACK_LINES = 25;
+/**
+ * If `text` exceeds `maxLines`, keep the first third and last two-thirds,
+ * replacing the middle with a one-line summary of what was omitted.
+ */
+export function truncateLines(text, maxLines = DEFAULT_MAX_LINES, label = 'lines') {
+    const lines = text.split(/\r?\n/);
+    if (lines.length <= maxLines)
+        return text;
+    const head = Math.floor(maxLines / 3);
+    const tail = maxLines - head;
+    const omitted = lines.length - maxLines;
+    return [
+        ...lines.slice(0, head),
+        `... [${omitted} ${label} omitted] ...`,
+        ...lines.slice(lines.length - tail),
+    ].join('\n');
+}
+/**
+ * If stderr contains a Python traceback, return just the traceback (trimmed).
+ * Otherwise return the stderr trimmed to `maxLines`.
+ */
+export function extractTraceback(stderr, maxLines = DEFAULT_TRACEBACK_LINES) {
+    const idx = stderr.indexOf('Traceback');
+    if (idx >= 0) {
+        return truncateLines(stderr.slice(idx), maxLines, 'traceback lines');
+    }
+    return truncateLines(stderr.trim(), maxLines, 'stderr lines');
+}
+//# sourceMappingURL=compress.js.map

package/dist/src/lib/compress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compress.js","sourceRoot":"","sources":["../../../src/lib/compress.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAC7B,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAEnC;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,WAAmB,iBAAiB,EACpC,QAAgB,OAAO;IAEvB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAClC,IAAI,KAAK,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC;IAE1C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC7B,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC;IAExC,OAAO;QACL,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC;QACvB,QAAQ,OAAO,IAAI,KAAK,eAAe;QACvC,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;KACpC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,WAAmB,uBAAuB;IAE1C,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACxC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACb,OAAO,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,aAAa,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC;AAChE,CAAC"}

package/dist/src/lib/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Errors thrown by helpcode itself.
+ *
+ * Use HelpcodeError, never plain Error, for any user-facing failure.
+ * The CLI's top-level handler reads `.hint` and shows it to the user.
+ */
+export declare enum ErrorCode {
+    /** State or config file missing/malformed. */
+    STATE_ERROR = "STATE_ERROR",
+    /** Reading or writing a file failed. */
+    IO_ERROR = "IO_ERROR",
+    /** Input failed validation (parser, patcher, etc.). */
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    /** A subprocess (tests, git, etc.) failed in a way we report up. */
+    SUBPROCESS_ERROR = "SUBPROCESS_ERROR",
+    /** User cancelled or provided no input where required. */
+    USER_CANCELLED = "USER_CANCELLED",
+    /** A feature isn't implemented yet on this path. */
+    NOT_IMPLEMENTED = "NOT_IMPLEMENTED"
+}
+export declare class HelpcodeError extends Error {
+    readonly code: ErrorCode;
+    readonly hint: string;
+    constructor(code: ErrorCode, message: string, hint?: string);
+}

package/dist/src/lib/errors.js

@@ -0,0 +1,32 @@
+/**
+ * Errors thrown by helpcode itself.
+ *
+ * Use HelpcodeError, never plain Error, for any user-facing failure.
+ * The CLI's top-level handler reads `.hint` and shows it to the user.
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    /** State or config file missing/malformed. */
+    ErrorCode["STATE_ERROR"] = "STATE_ERROR";
+    /** Reading or writing a file failed. */
+    ErrorCode["IO_ERROR"] = "IO_ERROR";
+    /** Input failed validation (parser, patcher, etc.). */
+    ErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    /** A subprocess (tests, git, etc.) failed in a way we report up. */
+    ErrorCode["SUBPROCESS_ERROR"] = "SUBPROCESS_ERROR";
+    /** User cancelled or provided no input where required. */
+    ErrorCode["USER_CANCELLED"] = "USER_CANCELLED";
+    /** A feature isn't implemented yet on this path. */
+    ErrorCode["NOT_IMPLEMENTED"] = "NOT_IMPLEMENTED";
+})(ErrorCode || (ErrorCode = {}));
+export class HelpcodeError extends Error {
+    code;
+    hint;
+    constructor(code, message, hint = '') {
+        super(message);
+        this.name = 'HelpcodeError';
+        this.code = code;
+        this.hint = hint;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAN,IAAY,SAaX;AAbD,WAAY,SAAS;IACnB,8CAA8C;IAC9C,wCAA2B,CAAA;IAC3B,wCAAwC;IACxC,kCAAqB,CAAA;IACrB,uDAAuD;IACvD,kDAAqC,CAAA;IACrC,oEAAoE;IACpE,kDAAqC,CAAA;IACrC,0DAA0D;IAC1D,8CAAiC,CAAA;IACjC,oDAAoD;IACpD,gDAAmC,CAAA;AACrC,CAAC,EAbW,SAAS,KAAT,SAAS,QAapB;AAED,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,IAAI,CAAY;IAChB,IAAI,CAAS;IAEtB,YAAY,IAAe,EAAE,OAAe,EAAE,IAAI,GAAG,EAAE;QACrD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/src/lib/git.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Git helpers. All best-effort — return null/empty when git isn't available
+ * or the directory isn't a repo. Never throws.
+ */
+export declare function getLastCommitSummary(cwd?: string): string | null;
+export declare function getUncommittedFileCount(cwd?: string): number;
+export declare function getUncommittedFiles(cwd?: string): string[];

package/dist/src/lib/git.js

@@ -0,0 +1,45 @@
+/**
+ * Git helpers. All best-effort — return null/empty when git isn't available
+ * or the directory isn't a repo. Never throws.
+ */
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+function isGitRepo(cwd = process.cwd()) {
+    return fs.existsSync(path.join(cwd, '.git'));
+}
+function tryGit(args, cwd = process.cwd()) {
+    if (!isGitRepo(cwd))
+        return null;
+    try {
+        return execSync(`git ${args.join(' ')}`, {
+            cwd,
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function getLastCommitSummary(cwd) {
+    return tryGit(['log', '-1', '--pretty=format:%h %s (%cr)'], cwd);
+}
+export function getUncommittedFileCount(cwd) {
+    const out = tryGit(['status', '--short'], cwd);
+    if (!out)
+        return 0;
+    return out.split('\n').filter(l => l.trim().length > 0).length;
+}
+export function getUncommittedFiles(cwd) {
+    const out = tryGit(['status', '--short'], cwd);
+    if (!out)
+        return [];
+    return out
+        .split('\n')
+        .map(l => l.trim())
+        .filter(Boolean)
+        .map(l => l.replace(/^.{1,3}/, '').trim());
+}
+//# sourceMappingURL=git.js.map

package/dist/src/lib/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../../src/lib/git.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,SAAS,SAAS,CAAC,MAAc,OAAO,CAAC,GAAG,EAAE;IAC5C,OAAO,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,MAAM,CAAC,IAAc,EAAE,MAAc,OAAO,CAAC,GAAG,EAAE;IACzD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE;YACvC,GAAG;YACH,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,GAAY;IAC/C,OAAO,MAAM,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,6BAA6B,CAAC,EAAE,GAAG,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,GAAY;IAClD,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,CAAC;IAC/C,IAAI,CAAC,GAAG;QAAE,OAAO,CAAC,CAAC;IACnB,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,CAAC;IAC/C,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,OAAO,GAAG;SACP,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SAClB,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAC/C,CAAC"}

package/dist/src/lib/runclass.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Classify why a test/command run failed, so the CLI can give the right
+ * advice. The key distinction:
+ *
+ *   - 'setup'   : the runner never started (not installed, not on PATH,
+ *                 missing module). Sending this back to Claude wastes a
+ *                 turn — the user needs to install something.
+ *   - 'timeout' : the command ran too long and was killed.
+ *   - 'test'    : the runner started and tests genuinely failed. THIS is
+ *                 the case worth sending back to Claude.
+ *
+ * This is a pure function over the captured CommandResult, so it's easy to
+ * unit-test against real-world stderr strings.
+ */
+import { CommandResult } from '../core/tools.js';
+export type FailureKind = 'setup' | 'timeout' | 'test';
+export interface FailureClassification {
+    kind: FailureKind;
+    /** A short, human-readable message describing the failure. */
+    message: string;
+    /** Actionable hint for the user, or empty string. */
+    hint: string;
+}
+export declare function classifyRunFailure(result: CommandResult): FailureClassification;