@manishbht/helpcode 0.2.2

package/dist/src/lib/runclass.js

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+/**
+ * Patterns that indicate the runner could not start — a setup problem,
+ * not a test failure. Cross-platform.
+ */
+const SETUP_PATTERNS = [
+    // POSIX shells: "/bin/sh: pytest: command not found" or "bash: jest: command not found"
+    {
+        re: /(?:^|\n).*?:\s*([\w.-]+):\s*command not found/i,
+        describe: m => `\`${m[1]}\` is not installed or not on your PATH`,
+    },
+    // Windows cmd: "'pytest' is not recognized as an internal or external command"
+    {
+        re: /'([\w.-]+)' is not recognized as an internal or external command/i,
+        describe: m => `\`${m[1]}\` is not installed or not on your PATH`,
+    },
+    // Python module missing: "No module named pytest"
+    {
+        re: /No module named ([\w.]+)/i,
+        describe: m => `the Python module \`${m[1]}\` is not installed`,
+    },
+    // Node module missing: "Cannot find module 'jest'"
+    {
+        re: /Cannot find module '([\w@/.-]+)'/i,
+        describe: m => `the module \`${m[1]}\` is not installed`,
+    },
+];
+export function classifyRunFailure(result) {
+    if (result.timedOut || result.exitCode === 124) {
+        return {
+            kind: 'timeout',
+            message: 'The command timed out and was killed.',
+            hint: 'If the command is genuinely slow, raise the timeout or run it manually.',
+        };
+    }
+    const haystack = `${result.stderr}\n${result.stdout}`;
+    for (const pattern of SETUP_PATTERNS) {
+        const m = haystack.match(pattern.re);
+        if (m) {
+            return {
+                kind: 'setup',
+                message: `The test runner didn't start — ${pattern.describe(m)}.`,
+                hint: 'Install it (e.g. `pip install pytest` / `npm install`), or fix the test_command in .helpcode/project.json. This is a setup issue, not something to send back to Claude.',
+            };
+        }
+    }
+    return {
+        kind: 'test',
+        message: 'Tests ran and some failed.',
+        hint: 'Run `helpcode ask "..."` to send the failure back to Claude.',
+    };
+}
+//# sourceMappingURL=runclass.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runclass.js","sourceRoot":"","sources":["../../../src/lib/runclass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAcH;;;GAGG;AACH,MAAM,cAAc,GAAgE;IAClF,wFAAwF;IACxF;QACE,EAAE,EAAE,gDAAgD;QACpD,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,yCAAyC;KAClE;IACD,+EAA+E;IAC/E;QACE,EAAE,EAAE,mEAAmE;QACvE,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,yCAAyC;KAClE;IACD,kDAAkD;IAClD;QACE,EAAE,EAAE,2BAA2B;QAC/B,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,qBAAqB;KAChE;IACD,mDAAmD;IACnD;QACE,EAAE,EAAE,mCAAmC;QACvC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,qBAAqB;KACzD;CACF,CAAC;AAEF,MAAM,UAAU,kBAAkB,CAAC,MAAqB;IACtD,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,GAAG,EAAE,CAAC;QAC/C,OAAO;YACL,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,uCAAuC;YAChD,IAAI,EAAE,yEAAyE;SAChF,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;IACtD,KAAK,MAAM,OAAO,IAAI,cAAc,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,EAAE,CAAC;YACN,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,OAAO,EAAE,kCAAkC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG;gBACjE,IAAI,EAAE,yKAAyK;aAChL,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,4BAA4B;QACrC,IAAI,EAAE,8DAA8D;KACrE,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,41 @@
+/**
+ * Tiny terminal UI helpers. Zero dependencies.
+ *
+ * Colors degrade gracefully when stdout isn't a TTY (CI, pipes).
+ */
+export declare const c: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    red: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    blue: (s: string) => string;
+    cyan: (s: string) => string;
+    gray: (s: string) => string;
+};
+/**
+ * Print text inside a clearly-marked block so the user knows what to copy.
+ * Format:
+ *
+ *   ───────── COPY EVERYTHING BELOW INTO CLAUDE.AI ─────────
+ *   <body>
+ *   ───────── END COPY BLOCK ─────────
+ */
+export declare function printPasteBlock(body: string): void;
+/** Print a header for a section of output. */
+export declare function header(title: string): void;
+/** A simple status line. Use info/warn/ok/err. */
+export declare const log: {
+    info: (msg: string) => void;
+    ok: (msg: string) => void;
+    warn: (msg: string) => void;
+    err: (msg: string) => void;
+    dim: (msg: string) => void;
+};
+/**
+ * Read all of stdin until EOF. Used for `helpcode apply` to receive
+ * Claude's pasted response.
+ */
+export declare function readStdin(): Promise<string>;
+/** Simple Y/n prompt that defaults to N. */
+export declare function confirm(question: string): Promise<boolean>;

package/dist/src/lib/ui.js

@@ -0,0 +1,92 @@
+/**
+ * Tiny terminal UI helpers. Zero dependencies.
+ *
+ * Colors degrade gracefully when stdout isn't a TTY (CI, pipes).
+ */
+const supportsColor = process.stdout.isTTY && process.env.NO_COLOR !== '1';
+const codes = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+};
+function color(c, s) {
+    return supportsColor ? codes[c] + s + codes.reset : s;
+}
+export const c = {
+    bold: (s) => color('bold', s),
+    dim: (s) => color('dim', s),
+    red: (s) => color('red', s),
+    green: (s) => color('green', s),
+    yellow: (s) => color('yellow', s),
+    blue: (s) => color('blue', s),
+    cyan: (s) => color('cyan', s),
+    gray: (s) => color('gray', s),
+};
+const DIVIDER = '─'.repeat(60);
+/**
+ * Print text inside a clearly-marked block so the user knows what to copy.
+ * Format:
+ *
+ *   ───────── COPY EVERYTHING BELOW INTO CLAUDE.AI ─────────
+ *   <body>
+ *   ───────── END COPY BLOCK ─────────
+ */
+export function printPasteBlock(body) {
+    console.log();
+    console.log(c.cyan(DIVIDER));
+    console.log(c.cyan('  COPY EVERYTHING BELOW INTO CLAUDE.AI'));
+    console.log(c.cyan(DIVIDER));
+    console.log();
+    console.log(body);
+    console.log();
+    console.log(c.cyan(DIVIDER));
+    console.log(c.cyan('  END COPY BLOCK'));
+    console.log(c.cyan(DIVIDER));
+}
+/** Print a header for a section of output. */
+export function header(title) {
+    console.log();
+    console.log(c.bold(title));
+    console.log(c.dim('─'.repeat(title.length)));
+}
+/** A simple status line. Use info/warn/ok/err. */
+export const log = {
+    info: (msg) => console.log(`${c.blue('•')} ${msg}`),
+    ok: (msg) => console.log(`${c.green('✓')} ${msg}`),
+    warn: (msg) => console.log(`${c.yellow('!')} ${msg}`),
+    err: (msg) => console.error(`${c.red('✗')} ${msg}`),
+    dim: (msg) => console.log(c.dim(msg)),
+};
+/**
+ * Read all of stdin until EOF. Used for `helpcode apply` to receive
+ * Claude's pasted response.
+ */
+export async function readStdin() {
+    if (process.stdin.isTTY) {
+        log.dim('Paste Claude\'s reply, then press Ctrl-D (Linux/Mac) or Ctrl-Z+Enter (Windows):');
+    }
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+/** Simple Y/n prompt that defaults to N. */
+export async function confirm(question) {
+    process.stdout.write(`${question} ${c.dim('[y/N]')} `);
+    return new Promise(resolve => {
+        process.stdin.resume();
+        process.stdin.setEncoding('utf-8');
+        process.stdin.once('data', (data) => {
+            process.stdin.pause();
+            resolve(data.trim().toLowerCase().startsWith('y'));
+        });
+    });
+}
+//# sourceMappingURL=ui.js.map

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

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

package/dist/src/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared types used across the helpcode CLI.
+ *
+ * Kept in one file so contributors can read the data model in one place.
+ */
+/** What kind of project the user is in. Detected by `init`, stored on disk. */
+export interface ProjectConfig {
+    /** Absolute path to the project root. */
+    root: string;
+    /** Primary language detected. */
+    language: 'python' | 'javascript' | 'typescript' | 'unknown';
+    /** Framework, if obvious. */
+    framework: string | null;
+    /** Command (as a single string) the user's test runner expects. */
+    testCommand: string | null;
+    /** Source dirs to consider when selecting context. */
+    sourceDirs: string[];
+    /** When this config was written. */
+    createdAt: string;
+    /** Optional local-LLM (Ollama) settings for smarter file selection (v0.2). */
+    ollama?: OllamaSettings;
+}
+/** Local-LLM configuration. Opt-in; absent or disabled = heuristic only. */
+export interface OllamaSettings {
+    /** When true, file selection uses the local model (with heuristic fallback). */
+    enabled: boolean;
+    /** Model tag, e.g. "qwen2.5-coder:7b". User-editable. */
+    model: string;
+    /** Ollama server URL. */
+    host: string;
+    /** Generation timeout in milliseconds. */
+    timeoutMs: number;
+}
+/** Status of the current iteration with Claude. */
+export type TaskStatus = 'idle' | 'awaiting_paste' | 'applying' | 'testing' | 'resolved' | 'failed';
+/** The agent's memory across CLI invocations. Stored at .helpcode/state.json. */
+export interface AgentState {
+    /** Schema version so we can migrate later without breaking installs. */
+    version: 1;
+    currentTask: CurrentTask | null;
+    /** History of resolved tasks (summary only, not full content). */
+    history: TaskHistoryEntry[];
+}
+export interface CurrentTask {
+    id: string;
+    description: string;
+    createdAt: string;
+    iterations: number;
+    status: TaskStatus;
+    /** Last prompt generated for Claude. */
+    lastPrompt: string | null;
+    /** Raw last response from Claude (as pasted by the user). */
+    lastResponseRaw: string | null;
+    /** Last captured test output, compacted. */
+    lastTestOutput: string | null;
+    /** Files touched by the most recent apply. */
+    lastDiffsApplied: AppliedDiff[];
+}
+export interface AppliedDiff {
+    filepath: string;
+    hunks: number;
+    ok: boolean;
+    created: boolean;
+}
+export interface TaskHistoryEntry {
+    id: string;
+    description: string;
+    resolvedAt: string;
+    iterations: number;
+}

package/dist/src/types.js

@@ -0,0 +1,7 @@
+/**
+ * Shared types used across the helpcode CLI.
+ *
+ * Kept in one file so contributors can read the data model in one place.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@manishbht/helpcode",
+  "version": "0.2.2",
+  "description": "A local agent that makes Claude.ai conversations efficient enough to ship real projects on a Pro subscription.",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "bin": {
+    "helpcode": "dist/bin/helpcode.js"
+  },
+  "files": [
+    "dist/src/",
+    "dist/bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test dist/tests/unit/*.test.js dist/tests/integration/*.test.js",
+    "test:unit": "npm run build && node --test dist/tests/unit/*.test.js",
+    "test:integration": "npm run build && node --test dist/tests/integration/*.test.js",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "claude",
+    "ai",
+    "cli",
+    "code-assistant",
+    "anthropic",
+    "claude-code",
+    "developer-tools",
+    "frugal-ai"
+  ],
+  "author": "merolaagi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/merolaagi/helpcode.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/merolaagi/helpcode/issues"
+  },
+  "homepage": "https://github.com/merolaagi/helpcode#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0"
+  }
+}