codeply-cli 0.2.0 → 0.3.0

package/lib/snapshot.js

@@ -0,0 +1,146 @@
+/**
+ * Undo for agent changes: a hidden git repository, kept outside the project,
+ * that records the project's files before a message runs so exactly what that
+ * message changed can be put back.
+ *
+ * The approach (a separate --git-dir pointed at the project as --work-tree,
+ * trees written with write-tree, files restored with checkout) follows
+ * opencode's snapshot/index.ts, MIT License, Copyright (c) 2025 opencode.
+ *
+ * It never touches the project's own .git: no commits, no index, no refs.
+ * The project's .gitignore still applies, plus a built-in list of heavy
+ * folders so a project without a .gitignore doesn't snapshot node_modules.
+ * Every function fails soft (returns null/false) when git is missing.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execFile } = require('child_process');
+
+const ROOT = path.join(os.homedir(), '.codeply', 'snapshots');
+const TIMEOUT_MS = 30000;
+const EXCLUDES = [
+  'node_modules/', '.git/', 'dist/', 'build/', 'out/', '.next/', '.nuxt/', '.turbo/', '.cache/', 'coverage/',
+  '__pycache__/', '.venv/', 'venv/', 'target/', '*.log', '.DS_Store', 'Thumbs.db',
+];
+const MAX_FILE_BYTES = 5 * 1024 * 1024;
+
+function gitDirFor(cwd) {
+  const key = crypto.createHash('sha1').update(path.resolve(cwd).toLowerCase()).digest('hex').slice(0, 16);
+  return path.join(ROOT, key);
+}
+
+function git(cwd, args, { input } = {}) {
+  const gitDir = gitDirFor(cwd);
+  const full = [
+    '-c', 'core.autocrlf=false', '-c', 'core.longpaths=true', '-c', 'core.fsmonitor=false',
+    '-c', 'core.quotepath=false', '-c', `safe.directory=*`,
+    `--git-dir=${gitDir}`, `--work-tree=${path.resolve(cwd)}`, ...args,
+  ];
+  return new Promise((resolve) => {
+    const child = execFile('git', full, { cwd, timeout: TIMEOUT_MS, windowsHide: true, maxBuffer: 32 * 1024 * 1024 },
+      (err, stdout, stderr) => resolve({ ok: !err, out: String(stdout || ''), err: String(stderr || (err && err.message) || '') }));
+    if (input != null) { child.stdin.end(input); }
+  });
+}
+
+async function ensureRepo(cwd) {
+  const gitDir = gitDirFor(cwd);
+  if (!fs.existsSync(path.join(gitDir, 'HEAD'))) {
+    fs.mkdirSync(gitDir, { recursive: true });
+    const r = await git(cwd, ['init', '-q']);
+    if (!r.ok) return false;
+    fs.writeFileSync(path.join(gitDir, 'codeply-project.txt'), path.resolve(cwd));
+  }
+  // Refreshed every time so changes to the list reach existing repos.
+  fs.mkdirSync(path.join(gitDir, 'info'), { recursive: true });
+  fs.writeFileSync(path.join(gitDir, 'info', 'exclude'), EXCLUDES.join('\n') + '\n');
+  return true;
+}
+
+/** Big files (videos, datasets) that aren't gitignored are left out, like opencode does. */
+async function excludeLargeUntracked(cwd) {
+  const r = await git(cwd, ['ls-files', '--others', '--exclude-standard', '-z']);
+  if (!r.ok || !r.out) return [];
+  const big = [];
+  for (const rel of r.out.split('\0').filter(Boolean)) {
+    try { if (fs.statSync(path.join(cwd, rel)).size > MAX_FILE_BYTES) big.push(rel); } catch {}
+  }
+  return big;
+}
+
+/**
+ * Record the project's current files.
+ * @returns {Promise<string|null>} a tree hash, or null if snapshots are unavailable
+ */
+async function track(cwd) {
+  try {
+    if (!cwd || !fs.existsSync(cwd) || !(await ensureRepo(cwd))) return null;
+    const big = await excludeLargeUntracked(cwd);
+    const add = await git(cwd, ['add', '-A', '--', '.', ...big.map((b) => `:(exclude,literal)${b}`)]);
+    if (!add.ok) return null;
+    const tree = await git(cwd, ['write-tree']);
+    return tree.ok ? tree.out.trim() || null : null;
+  } catch { return null; }
+}
+
+/** Files that differ between two recorded trees. */
+async function changedFiles(cwd, fromTree, toTree) {
+  if (!fromTree || !toTree || fromTree === toTree) return [];
+  const r = await git(cwd, ['diff-tree', '-r', '--name-status', '--no-renames', '-z', fromTree, toTree]);
+  if (!r.ok) return [];
+  const parts = r.out.split('\0').filter(Boolean);
+  const out = [];
+  for (let i = 0; i + 1 < parts.length; i += 2) {
+    out.push({ status: parts[i], file: parts[i + 1] }); // A added, M modified, D deleted
+  }
+  return out;
+}
+
+/** Does `file` exist in `tree`? */
+async function inTree(cwd, tree, file) {
+  const r = await git(cwd, ['cat-file', '-e', `${tree}:${file}`]);
+  return r.ok;
+}
+
+/**
+ * Put `files` back the way they were in `tree`: restore the ones it had,
+ * delete the ones it didn't (they were created after it).
+ * @returns {Promise<{ok:boolean, restored:string[], removed:string[], failed:string[]}>}
+ */
+async function restore(cwd, tree, files) {
+  const restored = [], removed = [], failed = [];
+  if (!tree || !(await ensureRepo(cwd))) return { ok: false, restored, removed, failed: files.slice() };
+  const existed = [];
+  for (const f of files) {
+    if (await inTree(cwd, tree, f)) existed.push(f);
+    else {
+      try { fs.rmSync(path.join(cwd, f), { force: true }); removed.push(f); } catch { failed.push(f); }
+    }
+  }
+  for (let i = 0; i < existed.length; i += 100) {
+    const batch = existed.slice(i, i + 100);
+    const r = await git(cwd, ['checkout', tree, '--', ...batch]);
+    if (r.ok) restored.push(...batch);
+    else {
+      // One bad path shouldn't block the rest.
+      for (const f of batch) {
+        const one = await git(cwd, ['checkout', tree, '--', f]);
+        (one.ok ? restored : failed).push(f);
+      }
+    }
+  }
+  return { ok: failed.length === 0, restored, removed, failed };
+}
+
+/** Is git usable here at all? Cached. */
+let gitAvailable;
+function available() {
+  if (gitAvailable !== undefined) return Promise.resolve(gitAvailable);
+  return new Promise((resolve) => {
+    execFile('git', ['--version'], { timeout: 5000, windowsHide: true }, (err) => { gitAvailable = !err; resolve(gitAvailable); });
+  });
+}
+
+module.exports = { track, changedFiles, restore, available, gitDirFor };

package/lib/subagents.js

@@ -0,0 +1,164 @@
+/**
+ * Roles for the single Codeply agent.
+ *
+ * There is exactly one agent. For each task it takes on the role that fits -
+ * Frontend, Backend, Database, DevOps, Security, Testing, Docs - and the
+ * role's guide (agents/<id>.md: YAML frontmatter + markdown body) is injected
+ * into that turn's system prompt as the standard to hold the work to. Roles
+ * never run in parallel and never hand work to each other; a multi-part
+ * request simply switches role between tasks (see main.js).
+ *
+ * detectRole() picks a role from a message's text with plain keyword
+ * matching - no model call, so it costs nothing and never blocks a send.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const AGENTS_DIR = path.join(__dirname, '..', 'agents');
+
+/** Same minimal frontmatter reader as skills.js - kept local so this module has no cross-dependency. */
+function parseFrontmatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!m) return { meta: {}, body: text };
+  const meta = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = line.match(/^([a-zA-Z0-9_]+):\s*(.*)$/);
+    if (kv) meta[kv[1]] = kv[2].replace(/^["']|["']$/g, '').trim();
+  }
+  return { meta, body: text.slice(m[0].length).trim() };
+}
+
+let cache = null;
+
+/** Every specialist, sorted by their declared `order`. Cached - the set is fixed at build time, not user-editable. */
+function listSubagents() {
+  if (cache) return cache;
+  let files;
+  try { files = fs.readdirSync(AGENTS_DIR).filter((f) => f.endsWith('.md')); }
+  catch { cache = []; return cache; }
+
+  cache = files.map((f) => {
+    const text = fs.readFileSync(path.join(AGENTS_DIR, f), 'utf8');
+    const { meta, body } = parseFrontmatter(text);
+    return {
+      id: meta.id || f.replace(/\.md$/, ''),
+      name: meta.name || f.replace(/\.md$/, ''),
+      tagline: meta.tagline || '',
+      color: meta.color || '#888888',
+      mascot: meta.mascot || `${meta.id || f.replace(/\.md$/, '')}.png`,
+      order: Number(meta.order) || 0,
+      // The guides were written for separate agents that handed work to each
+      // other; the "When X Hands Off" section doesn't apply to one agent.
+      persona: body.replace(/\r?\n## When [^\r\n]*Hands Off[\s\S]*?(?=\r?\n## |$)/, '').trim(),
+    };
+  }).sort((a, b) => a.order - b.order);
+
+  return cache;
+}
+
+/** Metadata only, no persona body - what the UI's picker needs, nothing it doesn't. */
+function listSubagentsMeta() {
+  return listSubagents().map(({ persona, ...meta }) => meta);
+}
+
+function getSubagent(id) {
+  if (!id) return null;
+  return listSubagents().find((a) => a.id === id) || null;
+}
+
+/**
+ * Loose match against a free-text name (what the model writes into a
+ * <name> tag, e.g. "frontend", "the Frontend specialist", "Backend Bot") -
+ * exact id match first, then a substring check either direction so a
+ * reasonably-named delegation call still resolves.
+ */
+function findSubagentByName(name) {
+  const q = String(name || '').trim().toLowerCase();
+  if (!q) return null;
+  const all = listSubagents();
+  return all.find((a) => a.id === q) ||
+    all.find((a) => a.name.toLowerCase() === q) ||
+    all.find((a) => q.includes(a.id) || a.name.toLowerCase().includes(q) || q.includes(a.name.toLowerCase())) ||
+    null;
+}
+
+// Auto-routing: picks a specialist FOR ONE MESSAGE from its own text, no
+// manual pin required - the same specialist can get picked again on a later,
+// unrelated message, or a different one each time, since this runs fresh per
+// call. Pure keyword classification (no I/O, no model call) so it costs
+// nothing and never blocks a send. Ordered most-specific-and-safety-critical
+// first: a message that mentions both "security" and "css" should route to
+// Warden, not Pixel, so security/data-integrity concerns are checked before
+// the broader, easier-to-accidentally-match categories (frontend/design).
+// Deliberately conservative - every pattern requires a real technical term,
+// not a generic word ("test" alone doesn't match; "unit test"/"write a test"
+// does) - a false match hands the whole turn a persona/tone that doesn't fit
+// the actual request, which is worse than staying General for an ambiguous one.
+// Every bare noun below is written with its plural covered (`issues?`,
+// `bugs?`, `endpoints?`, ...) - an earlier version required the exact
+// singular form, so "security issues" (plural) silently missed the
+// security route entirely and fell through to a much broader, wrong
+// category. Getting plurals right matters more here than almost anywhere
+// else in this file: a missed match doesn't just fail quietly, it falls
+// back to whatever an unrelated EARLIER message in the conversation was
+// about (see effectiveSubagentId in main.js), which can point at a
+// completely wrong specialist instead of just staying General.
+const AUTO_ROUTES = [
+  { id: 'security', re: /\b(vulnerabilit(?:y|ies)|xss|csrf|sql\s?injections?|penetration\s?tests?|pentest|exploits?|security\b|auth(?:entication|orization)?\s?(?:bugs?|bypass(?:es)?|checks?|flows?|tokens?)|hash(?:ing)?\s?passwords?|encrypt(?:ion|ed)?|secrets?\s?(?:leak(?:ed)?|expos(?:ed|ure))|credentials?(?:\s?leak(?:ed)?)?|rate\s?limit(?:ing)?|owasp|csp\b|cors\b|jwt\b|sanitiz(?:e|ing|ation)|injection\s?attacks?)\b/i },
+  { id: 'database', re: /\b(databases?|db\s?schemas?|schemas?\s?(?:change|design|migration)|migrat(?:ion|ions|e|ing)|sql\s?quer(?:y|ies)|quer(?:y|ies)\s?(?:plan|slow|performance)|add(?:ing)?\s?an?\s?index|indexes?|foreign\s?keys?|primary\s?keys?|postgres(?:ql)?|mysql|sqlite|mongo(?:db)?|n\+1\s?quer|tables?\s?(?:column|row|schema)|orm\b|prisma\b|supabase\s?tables?)\b/i },
+  { id: 'devops', re: /\b(ci\/cd|ci\s?pipelines?|github\s?actions|deploy(?:ment|ments|ing|ed)?|rollbacks?|dockerfiles?|docker\s?compose|kubernetes|k8s|zero[- ]downtime|infra(?:structure)?(?:\s?as\s?code)?|env(?:ironment)?\s?variables?|secrets?\s?manager|build\s?pipelines?|hosting|vercel|netlify|render\.com|health\s?checks?|uptime|logging\s?(?:setup|infra)|monitoring|observability)\b/i },
+  { id: 'testing', re: /\b(unit\s?tests?|write\s?(?:a\s?|some\s?)?tests?|regression\s?tests?|e2e\s?tests?|end[- ]to[- ]end\s?tests?|test\s?coverage|flaky\s?tests?|reproduce\s?(?:this|the)\s?bugs?|test\s?suites?|qa\s?pass|edge\s?cases?|testing\s?strategy|test\s?(?:the|this|my|it|out)\b|does\s?(?:it|this)\s?works?|check\s?if\s?(?:it|this)\s?works?)\b/i },
+  { id: 'backend', re: /\b(api\s?(?:endpoints?|routes?|integrations?)|rest\s?api|backend\s?(?:logic|routes?|bugs?|code)|business\s?logic|server[- ]side|race\s?conditions?|idempotent|webhooks?|graphql|endpoints?\s?(?:for|to)|route\s?handlers?|server\s?errors?)\b/i },
+  { id: 'frontend', re: /\b(css\b|styles?\s?(?:sheet)?|responsive(?:\s?layout)?|react\s?components?|vue\s?components?|components?\b|flexbox|grid\s?layout|accessib(?:le|ility)|aria[- ]|keyboard\s?nav|hover\s?states?|animations?|transitions?|dark\s?mode\b|light\s?mode\b|frontend\b|ui\s?(?:bugs?|fix|elements?|components?)?|buttons?\b|layouts?\b|typography|fonts?(?:-family)?|padding|margins?|spacing|glassmorphism|sections?\b|footers?\b|headers?\b|navbar|sidebars?|modals?\b|breakpoints?|visual\s?hierarchy|design\s?systems?|information\s?architecture|user\s?flows?|wireframes?|mockups?|color\s?palettes?|type\s?scale|ux\s?review|luxury|aesthetics?|polish(?:ed)?|brand(?:ing)?|design\s?(?:direction|refinement|feedback|advice)|make\s?it\s?(?:look|feel)|world[- ]class|premium\s?feel|(?:landing|collection|product|pricing|contact|about|home)\s?pages?|new\s?pages?|web\s?pages?|html\s?pages?|(?:the\s+)?website\b|images?\b|photos?\b|pictures?\b)\b/i },
+  { id: 'docs', re: /\b(write\s?(?:a\s?)?readme|api\s?docs?|documentation|doc[- ]?comments?|changelog|release\s?notes|write\s?a\s?(?:guide|tutorial)|code\s?comments?)\b/i },
+];
+
+// Alternate ways someone actually types a niche's name in a sentence - not
+// just the single-word form AUTO_ROUTES already matches as a topic keyword,
+// but explicitly asking FOR that specialist ("use front end agent", "have
+// the security specialist look at this"). "front end agent" (two words,
+// space) was silently missing before this existed - AUTO_ROUTES only had
+// the one-word "frontend" as a keyword, so a request naming the specialist
+// by its actual two-word name never matched anything.
+const NICHE_ALIASES = {
+  frontend: ['frontend', 'front[- ]end'],
+  backend: ['backend', 'back[- ]end'],
+  database: ['database', 'db'],
+  devops: ['dev\\s?ops'],
+  security: ['security'],
+  testing: ['testing', 'qa'],
+  docs: ['docs', 'documentation'],
+};
+
+/**
+ * Catches a request that names a specialist directly - by its mascot name
+ * ("have Pixel look at this") or by its niche plus an agent/specialist/bot
+ * word ("use the front end agent", "security specialist please review").
+ * Checked before the topic-keyword routes below so an explicit ask always
+ * wins over guessing from subject matter.
+ */
+function detectExplicitMention(message) {
+  const text = String(message || '');
+  for (const a of listSubagents()) {
+    if (new RegExp(`\\b${a.name}\\b`, 'i').test(text)) return a.id;
+    for (const alias of NICHE_ALIASES[a.id] || []) {
+      if (new RegExp(`\\b${alias}\\s+(?:agent|specialist|bot)\\b`, 'i').test(text)) return a.id;
+    }
+  }
+  return null;
+}
+
+function detectSpecialist(message) {
+  const text = String(message || '');
+  const explicit = detectExplicitMention(text);
+  if (explicit) return explicit;
+  for (const route of AUTO_ROUTES) {
+    if (route.re.test(text)) return route.id;
+  }
+  return null;
+}
+
+const detectRole = detectSpecialist;
+const getRole = getSubagent;
+
+module.exports = { listSubagents, listSubagentsMeta, getSubagent, getRole, findSubagentByName, detectSpecialist, detectRole };

package/lib/terminal-hints.js

@@ -0,0 +1,154 @@
+/**
+ * One short, actionable recovery hint for a failed shell command, and a
+ * warning when an exit code of 0 is hiding a failure.
+ *
+ * Adapted from Hermes Agent (tools/terminal_hints.py), MIT License,
+ * Copyright (c) 2025 Nous Research - https://github.com/NousResearch/hermes-agent
+ * Windows (cmd.exe / PowerShell) and Node patterns added for Codeply.
+ *
+ * Rules: hints only fire on a non-zero exit, first match wins, only the head
+ * of the output is scanned (hints key on error headers, not deep logs), and
+ * each hint states the next action to take. Pure functions, no I/O.
+ */
+
+const SCAN_CHARS = 4000;
+
+const MISSING_COMMAND_HINTS = {
+  python: 'There is no bare `python` here. Try `python3` or `py` (Windows launcher), or the project venv interpreter.',
+  pip: 'There is no bare `pip` here. Try `pip3`, `python -m pip` / `py -m pip`, or the project venv pip.',
+};
+
+function missingCommandHint(cmd) {
+  const name = String(cmd || '').replace(/^['"]|['"]$/g, '');
+  const onWindows = process.platform === 'win32';
+  return MISSING_COMMAND_HINTS[name.toLowerCase()] ||
+    `\`${name}\` is not installed or not on PATH. Check with \`${onWindows ? `where ${name}` : `command -v ${name}`}\`, ` +
+    `then install it (${onWindows ? 'winget, npm -g, or the tool\'s installer' : 'brew/apt/npm -g'}) or use its full path. ` +
+    'Do not retry the same command unchanged.';
+}
+
+const rx = (pattern, message) => ({ pattern, message });
+
+// The shell itself choked on the command's syntax. Retrying a variation of
+// the same one-liner rarely works; a different tool does.
+const WRITE_IT_INSTEAD = 'Do not retry a variation of this one-liner. Write the content with write_file instead ' +
+  '(for a script: write_file it, then run it with node/python/etc.).';
+
+// Ordered roughly by how often they show up. First match wins.
+const OUTPUT_HINTS = [
+  rx(/<< was unexpected at this time|The '<' operator is reserved for future use|Missing file specification after redirection operator|here-document at line \d+ delimited by end-of-file/i,
+    `This shell cannot take a heredoc (<<) here (cmd.exe and PowerShell have none). ${WRITE_IT_INSTEAD}`),
+  rx(/The token '&&' is not a valid statement separator|The token '\|\|' is not a valid statement separator/i,
+    'This is Windows PowerShell 5.1, which has no && or ||. Chain with `;` (or `if ($?) { next }`), or run the whole line through `cmd /c "..."`.'),
+  rx(/The string is missing the terminator|unexpected EOF while looking for matching|Unterminated quoted string|syntax error: unterminated quoted string/i,
+    `The shell's quoting broke on this command (nested or multi-line quotes). ${WRITE_IT_INSTEAD}`),
+  rx(/The command line is too long|Argument list too long|E2BIG/i,
+    `The command is longer than the shell allows. ${WRITE_IT_INSTEAD}`),
+  rx(/The filename, directory name, or volume label syntax is incorrect/i,
+    'Windows rejected a path in this command: check for forward/back slash mix-ups, stray quotes, or characters like : * ? " < > | in a file name.'),
+  rx(/^CONFLICT |Automatic merge failed|needs merge/m,
+    'Git merge conflict. Do not retry this command. Fix the conflicted files listed above (edit, then `git add`), ' +
+    'then continue (`git rebase --continue` or commit the merge), or abort with `--abort`.'),
+  rx(/(?:bash: line \d+: |bash: |sh: \d*:? ?)?([\w.+-]+): command not found/, (m) => missingCommandHint(m[1])),
+  // cmd.exe
+  rx(/'([^']+)' is not recognized as an internal or external command/i, (m) => missingCommandHint(m[1])),
+  // PowerShell
+  rx(/The term '([^']+)' is not recognized as (?:the )?name of a cmdlet/i, (m) => missingCommandHint(m[1])),
+  rx(/Cannot find module '([^']+)'/,
+    (m) => m[1].startsWith('.') || m[1].includes('/') && !m[1].startsWith('@')
+      ? `Node cannot find '${m[1]}'. Check the path is right relative to the file that requires it (list_dir), and the file extension.`
+      : `Node cannot find the package '${m[1]}'. Run \`npm install\` in the project folder (or \`npm install ${m[1]}\` if it is not in package.json yet).`),
+  rx(/(?:ModuleNotFoundError|ImportError): No module named '?([\w.]+)/,
+    (m) => `Python cannot import '${m[1]}'. Usually the wrong interpreter is running: use the project venv's python. ` +
+      'Only pip install it if it is genuinely missing from that environment.'),
+  rx(/npm ERR! (?:code )?ERESOLVE|could not resolve dependency/i,
+    'npm dependency conflict. Read which packages clash above; retry with `--legacy-peer-deps` only if the versions are genuinely compatible.'),
+  rx(/Missing script: "?([\w:.-]+)/,
+    (m) => `package.json has no "${m[1]}" script. Check the real script names (read package.json) instead of guessing.`),
+  rx(/EADDRINUSE[^\n]*?:(\d+)/,
+    (m) => `Port ${m[1]} is already in use, probably by a server you started earlier. Reuse that server, or pick another port.`),
+  rx(/(?:fatal|error):.*?'([^']+)' already exists/,
+    (m) => `'${m[1]}' already exists, so retrying unchanged will keep failing. Reuse it, pick another name, or delete it first if it is stale.`),
+  rx(/API rate limit|was submitted too quickly/,
+    'Rate limit hit, so immediate retries will keep failing. Do other work first and retry this later.'),
+  rx(/Permission denied|EACCES|EPERM|Access is denied/,
+    'Permission denied. Check the target path is writable and not open in another program; prefer a folder the user owns. ' +
+    'Do not escalate privileges unless the task truly needs it.'),
+  rx(/cannot be loaded because running scripts is disabled/i,
+    'PowerShell blocked the script (execution policy). Run the tool through its .cmd shim (e.g. `npm.cmd`, `npx.cmd`) or through cmd instead of changing system policy.'),
+  rx(/ENOENT[^\n]*?'([^']+)'/,
+    (m) => `No such file or folder: '${m[1]}'. Check the path with list_dir before retrying.`),
+];
+
+const EXIT_CODE_HINTS = {
+  124: 'Exit 124: the command timed out. Run something smaller, or start long-running servers in the background instead of waiting on them.',
+  126: 'Exit 126: the file exists but is not executable. Run it through its interpreter (e.g. `node script.js`, `bash script.sh`).',
+  127: 'Exit 127: command not found. Check it is installed and on PATH, or use its full path.',
+  137: 'Exit 137: the process was killed, usually out of memory. Reduce what it processes at once before retrying.',
+  9009: 'Exit 9009: Windows could not find that program. Check it is installed and on PATH (`where <name>`).',
+};
+
+/** @returns {string|null} one recovery hint for a failed command */
+function annotateFailure(command, exitCode, output) {
+  if (!exitCode) return null;
+  const window = String(output || '').slice(0, SCAN_CHARS);
+  if (window) {
+    for (const { pattern, message } of OUTPUT_HINTS) {
+      const m = window.match(pattern);
+      if (m) return typeof message === 'function' ? message(m) : message;
+    }
+  }
+  return EXIT_CODE_HINTS[exitCode] || null;
+}
+
+// ─── Masked success ─────────────────────────────────────────────────────────
+// `npm test | tail -20` exits with tail's 0 and `build || echo done` with
+// echo's 0, so the model can conclude a build passed while its own output
+// says it failed. Needs BOTH a masking shape AND a strong, tool-specific
+// failure line, and skips read-only commands whose output legitimately
+// contains error text (grep for "error", cat a log).
+
+const PASSTHROUGH = '(?:tail|head|cat|tee|less|more|wc|sort|uniq|Select-Object|Out-String|findstr)';
+const MASKING_SHAPES = [
+  [new RegExp(`(?<!\\|)\\|(?!\\|)\\s*${PASSTHROUGH}\\b[^|]*$`, 'i'),
+    'Exit 0 here is the status of the last command in the pipe (tail/head/...), NOT of the command before it, and the ' +
+    'output shows a failure. Treat this run as FAILED: run the command again without the pipe to get its real exit code.'],
+  [/\|\|\s*(?:echo\b|printf\b|true\b|exit 0\b|:\s|:$)/i,
+    'Exit 0 here comes from the `||` fallback, NOT from the command before it, and the output shows a failure. ' +
+    'Treat this run as FAILED: run the command on its own to get its real exit code.'],
+  [/;\s*(?:exit\s+0|echo\b[^;|&]*)\s*$/i,
+    'Exit 0 here comes from the command after the `;`, NOT from the one before it, and the output shows a failure. ' +
+    'Treat this run as FAILED: run the command on its own to get its real exit code.'],
+];
+
+const READONLY_HEADS = new Set(['grep', 'rg', 'ag', 'find', 'findstr', 'ls', 'dir', 'cat', 'type', 'head', 'tail', 'jq', 'awk', 'sed', 'echo', 'printf', 'get-content', 'select-string']);
+
+const FAILURE_SHAPES = new RegExp([
+  'error\\[E\\d+\\]', 'error: could not compile', 'error: aborting due to',   // rust
+  'Traceback \\(most recent call last\\)',                                      // python
+  '^(?:=+ )?\\d+ failed', '^FAILED (?:\\S+::|\\S+\\.py)',                       // pytest
+  'compilation terminated\\.',                                                   // gcc/clang
+  'npm ERR!', '^npm error ',                                                     // npm
+  'BUILD FAILED', 'Build FAILED', 'FAILED: ',                                    // gradle/msbuild/ninja
+  '^make(?:\\[\\d+\\])?: \\*\\*\\*',                                             // make
+  '^\\s*(?:Tests?|Test Suites):\\s+\\d+ failed',                                 // jest/vitest
+  'error TS\\d{4}:',                                                             // tsc
+  '^SyntaxError: ',                                                              // node
+].join('|'), 'm');
+
+function firstToken(command) {
+  for (const tok of String(command || '').trim().split(/\s+/)) {
+    if (!tok.includes('=') || /^(=|\.\/|\/)/.test(tok)) return tok.split(/[\\/]/).pop().toLowerCase();
+  }
+  return '';
+}
+
+/** @returns {string|null} a warning when an exit-0 result likely hides a failure */
+function annotateMaskedSuccess(command, output) {
+  const window = String(output || '').slice(0, SCAN_CHARS);
+  if (!command || !window || READONLY_HEADS.has(firstToken(command)) || !FAILURE_SHAPES.test(window)) return null;
+  const hit = MASKING_SHAPES.find(([shape]) => shape.test(command));
+  return hit ? hit[1] : null;
+}
+
+module.exports = { annotateFailure, annotateMaskedSuccess };