@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/global/hooks/gnu-shell.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// gnu-shell (SessionStart; global by design): the Bash tool runs bash 5 with the GNU tools, not zsh with the BSD ones.
+//
+// "can you do a proper skill/hook for zsh because this seems to happen alot?". Claude Code's Bash tool runs
+// the login shell, zsh on this Mac: `$VAR` holding several words is not split, an unmatched glob is an error, and
+// `sed -i`, `date -d`, `stat -c` are the BSD tools'. The fix has two halves:
+//   1. THE SHELL: settings.json `env` sets CLAUDE_CODE_SHELL and SHELL to /opt/homebrew/bin/bash (Homebrew's bash 5).
+//   2. THE TOOLS: this hook writes one `export PATH=...` to the file CLAUDE_ENV_FILE names, which Claude Code sources
+//      before every Bash call: ~/.claude/bin first (buildq, the machine-wide build queue), then the `libexec/gnubin`
+//      folder of every GNU formula installed, so sed, date, stat, awk, tar, find, xargs, which are the GNU builds; and a
+//      line that warns on EVERY command while the session runs zsh (WB-41). The user's own terminal is not touched.
+// It says so at the session's start when it cannot deliver: no Homebrew, a formula missing, the shell not bash 5.
+// On Linux (KWB-27) the system's sed, date, stat and awk are the GNU builds already: no Homebrew is looked for, the PATH line
+// puts only ~/.claude/bin first, and the shell is still checked for bash 5 (any bash 5, not Homebrew's).
+//   node gnu-shell.mjs --selftest
+import { execFileSync } from 'node:child_process';
+import { appendFileSync, chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+
+export const FORMULAS = ['coreutils', 'findutils', 'gawk', 'gnu-sed', 'gnu-tar', 'gnu-which', 'grep'];
+const BASH = '/opt/homebrew/bin/bash';
+const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+const gnubin = (pre, f) => join(pre, 'opt', f, 'libexec', 'gnubin');
+
+// Homebrew's prefix, found on the disk, not by asking brew (a hook started by an app may not have brew on PATH).
+export function prefix() {
+  return ['/opt/homebrew', '/usr/local'].find((p) => isDir(join(p, 'opt')) && FORMULAS.some((f) => isDir(gnubin(p, f)))) ?? null;
+}
+
+function bashMajor(path) {
+  try { return Number(execFileSync(path, ['--version'], { encoding: 'utf8', timeout: 5000 }).match(/version (\d+)\./)?.[1] ?? 0); } catch { return 0; }
+}
+
+const shellSaid = (sh, mac) => `gnu-shell: the Bash tool's shell is ${sh || 'unknown'}, not ${mac ? `Homebrew's bash 5 (${BASH})` : 'bash 5'}: ` +
+  '`$VAR` lists do not split (use ${=VAR} or an array) and an unmatched glob is an error. The env block in .claude/settings.json takes effect from the next session.';
+const shellOk = (sh) => basename(sh ?? '') === 'bash' && bashMajor(sh) >= 5;
+const ZSH_WARNING = '[ -n "$ZSH_VERSION" ] && echo "gnu-shell: THIS SESSION RUNS ZSH, not bash 5 (variables are not split into words, an unmatched glob is an error). Restart Claude Code to get bash 5." >&2\n';
+
+// Linux: the tools are GNU already; ~/.claude/bin first, the zsh warning, and the shell checked.
+function runLinux(envFile, shell) {
+  const said = [];
+  if (envFile) {
+    appendFileSync(envFile, 'export PATH="$HOME/.claude/bin:${PATH}"\n');
+    appendFileSync(envFile, ZSH_WARNING);
+  } else said.push('gnu-shell: CLAUDE_ENV_FILE is not set, so ~/.claude/bin could not be put first on the Bash tool\'s PATH.');
+  if (!shellOk(shell)) said.push(shellSaid(shell, false));
+  return said;
+}
+
+// Writes the PATH line; returns what must be said (empty when all is as it should be).
+export function run(envFile, shell, { platform = process.platform, pre } = {}) {
+  if (platform !== 'darwin') return runLinux(envFile, shell);
+  if (pre === undefined) pre = prefix();
+  const said = [];
+  if (!pre) {
+    return ["gnu-shell: no Homebrew found (/opt/homebrew or /usr/local): this session's sed, date, stat and awk are the macOS (BSD) builds, " +
+      "not GNU. Write BSD-safe commands (sed -i '' ..., no date -d)."];
+  }
+  const have = FORMULAS.filter((f) => isDir(gnubin(pre, f))).map((f) => gnubin(pre, f));
+  const missing = FORMULAS.filter((f) => !isDir(gnubin(pre, f)));
+  if (envFile && have.length) {
+    appendFileSync(envFile, `export PATH="$HOME/.claude/bin:${have.join(':')}:\${PATH}"\n`);
+    appendFileSync(envFile, ZSH_WARNING);
+  }
+  if (missing.length) {
+    said.push(`gnu-shell: GNU formula(s) not installed: ${missing.join(', ')}; those tools are the macOS (BSD) builds this session. ` +
+      `Install them with: brew install ${missing.join(' ')}`);
+  }
+  if (!envFile) said.push('gnu-shell: CLAUDE_ENV_FILE is not set, so the GNU tools could not be put first on the Bash tool\'s PATH.');
+  if (!shellOk(shell)) said.push(shellSaid(shell, true));
+  return said;
+}
+
+// A fake bash that reports the given version: the selftest never depends on this machine's /bin/bash (KWB-27).
+function fakeBash(dir, version) {
+  const file = join(dir, `bash-${version}`, 'bash');
+  mkdirSync(join(dir, `bash-${version}`), { recursive: true });
+  writeFileSync(file, `#!/bin/sh\necho 'GNU bash, version ${version}(1)-release'\n`);
+  chmodSync(file, 0o755);
+  return file;
+}
+
+function selftest() {
+  const bad = [];
+  const expect = (name, ok) => { if (!ok) bad.push(name); };
+  const d = mkdtempSync(join(tmpdir(), 'gnu-shell-'));
+  const bash5 = fakeBash(d, '5.2.37');
+  const bash32 = fakeBash(d, '3.2.57');
+  const notBash5 = (said) => said.some((s) => s.includes('not ') && s.includes('bash 5'));
+  // macOS
+  const pre = join(d, 'brew');
+  for (const f of FORMULAS) mkdirSync(gnubin(pre, f), { recursive: true });
+  const mac = (file, shell) => run(join(d, file), shell, { platform: 'darwin', pre });
+  const said = mac('env.sh', bash5);
+  const text = readFileSync(join(d, 'env.sh'), 'utf8');
+  const line = text.split('\n')[0];
+  expect("mac: every formula's gnubin written first on PATH", FORMULAS.every((f) => line.includes(`/opt/${f}/libexec/gnubin`)) && line.endsWith(':${PATH}"'));
+  expect('mac: ~/.claude/bin first', line.startsWith('export PATH="$HOME/.claude/bin:'));
+  expect('mac: a zsh session is warned on every command (WB-41)', text.includes('[ -n "$ZSH_VERSION" ]') && text.toUpperCase().includes('RESTART'));
+  expect('mac: bash 5 and every formula: nothing said', said.length === 0);
+  expect('mac: no Homebrew is said', run(join(d, 'e1.sh'), bash5, { platform: 'darwin', pre: null }).some((s) => s.includes('no Homebrew')));
+  expect("mac: zsh as the shell is said", mac('e3.sh', '/bin/zsh').some((s) => s.includes("not Homebrew's bash 5")));
+  expect("mac: Apple's bash 3.2 is said", mac('e4.sh', bash32).some((s) => s.includes("not Homebrew's bash 5")));
+  rmSync(gnubin(pre, 'gnu-sed'), { recursive: true });
+  expect('mac: a missing formula is said, by name', mac('e2.sh', bash5).some((s) => s.includes('gnu-sed')));
+  // Linux (KWB-27): the system tools are GNU; no Homebrew is looked for, even when one is there
+  const linux = (file, shell) => run(join(d, file), shell, { platform: 'linux', pre });
+  const lsaid = linux('l1.sh', bash5);
+  const ltext = readFileSync(join(d, 'l1.sh'), 'utf8');
+  expect('linux: bash 5: nothing said (no Homebrew, no BSD tools)', lsaid.length === 0);
+  expect('linux: ~/.claude/bin first, no gnubin', ltext.split('\n')[0] === 'export PATH="$HOME/.claude/bin:${PATH}"');
+  expect('linux: a zsh session is warned on every command', ltext.includes('[ -n "$ZSH_VERSION" ]'));
+  expect('linux: zsh as the shell is said', notBash5(linux('l2.sh', '/usr/bin/zsh')));
+  expect('linux: bash 3.2 is said', notBash5(linux('l3.sh', bash32)));
+  expect('linux: no env file is said', run(undefined, bash5, { platform: 'linux' }).some((s) => s.includes('CLAUDE_ENV_FILE')));
+  rmSync(d, { recursive: true, force: true });
+  for (const b of bad) console.error(`FAIL  ${b}`);
+  console.log(`gnu-shell selftest: ${bad.length ? `${bad.length} wrong` : 'OK'}`);
+  return bad.length ? 1 : 0;
+}
+
+function main() {
+  if (process.argv.includes('--selftest')) return selftest();
+  try { readFileSync(0, 'utf8'); } catch { /* no stdin */ }
+  const said = run(process.env.CLAUDE_ENV_FILE, process.env.CLAUDE_CODE_SHELL || process.env.SHELL);
+  if (said.length) console.log(said.join('\n')); // SessionStart: what is printed reaches the session's context
+  return 0;
+}
+
+process.exit(main());

package/global/hooks/lib/program-read.mjs

@@ -0,0 +1,196 @@
+// program-read: a small reader of an inline program (python, node, perl, ruby) for program-writes.mjs (KWB-8). It never
+// runs the program; it reads string literals, splits statements, and evaluates the simple expressions a file-writing
+// program uses (a literal, a variable, Path(...) and joins, a file's text read, .replace chains, + of strings).
+//   scan(code, lang) -> { code, lits }   code: the program with every literal replaced by \x01n\x02 and comments blanked;
+//                                        lits[n]: its text, or null when it interpolates (f-string, ${}, "$x")
+//   statements(code) -> [string]         split at newlines and ; outside brackets
+//   splitArgs(text) -> [string]          top-level comma split of a call's arguments
+//   closeOf(text, open) -> index         the bracket that closes text[open]
+//   evaluate(expr, ctx) -> value | null  value: { t: 'str'|'path', v }; ctx: { env, lang, at, readText }
+const PAIRS = { '(': ')', '[': ']', '{': '}' };
+
+function unescape(s, lang) {
+  return s.replace(/\\(\n|x[0-9a-fA-F]{2}|u[0-9a-fA-F]{4}|.)/gs, (m, e) => {
+    if (e === '\n') return '';
+    if (e[0] === 'x' && e.length === 3) return String.fromCharCode(parseInt(e.slice(1), 16));
+    if (e[0] === 'u' && e.length === 5) return String.fromCharCode(parseInt(e.slice(1), 16));
+    const map = { n: '\n', t: '\t', r: '\r', 0: '\0', '\\': '\\', "'": "'", '"': '"', '`': '`', $: '$' };
+    if (e in map) return map[e];
+    return lang === 'python' ? m : e;
+  });
+}
+
+export function scan(src, lang) {
+  const lits = [];
+  let out = '';
+  let i = 0;
+  const hash = lang !== 'node';
+  while (i < src.length) {
+    const c = src[i];
+    if ((hash && c === '#') || (!hash && c === '/' && src[i + 1] === '/')) {
+      while (i < src.length && src[i] !== '\n') i += 1;
+      continue;
+    }
+    if (!hash && c === '/' && src[i + 1] === '*') { const j = src.indexOf('*/', i + 2); i = j < 0 ? src.length : j + 2; continue; }
+    let pre = '';
+    if (lang === 'python') pre = src.slice(i).match(/^[rRbBuUfF]{0,2}(?=['"])/)?.[0] ?? '';
+    if (pre && /\w/.test(src[i - 1] ?? '')) pre = '';
+    const q0 = src[i + pre.length];
+    const quote = q0 === "'" || q0 === '"' || (q0 === '`' && lang === 'node') ? q0 : null;
+    if (!quote || (pre === '' && /\w/.test(src[i - 1] ?? '') && lang === 'python')) { out += c; i += 1; continue; }
+    const start = i + pre.length;
+    const triple = lang === 'python' && src.startsWith(quote.repeat(3), start);
+    const open = triple ? 3 : 1;
+    let j = start + open;
+    while (j < src.length && !(triple ? src.startsWith(quote.repeat(3), j) : src[j] === quote) && (triple || quote === '`' || src[j] !== '\n')) j += src[j] === '\\' ? 2 : 1;
+    const raw = src.slice(start + open, j);
+    i = Math.min(src.length, j + open);
+    const rawFlag = /[rR]/.test(pre);
+    let v;
+    if (/[fF]/.test(pre) && /[{}]/.test(raw)) v = null;
+    else if (quote === '`' && raw.includes('${')) v = null;
+    else if ((lang === 'perl' || lang === 'ruby') && quote === '"' && /[$@]|#\{/.test(raw)) v = null;
+    else if ((lang === 'perl' || lang === 'ruby') && quote === "'") v = raw.replace(/\\([\\'])/g, '$1');
+    else v = rawFlag ? raw : unescape(raw, lang);
+    out += `\x01${lits.length}\x02`;
+    lits.push(v);
+  }
+  return { code: out, lits };
+}
+
+export function closeOf(text, open) {
+  const want = PAIRS[text[open]];
+  let depth = 0;
+  for (let k = open; k < text.length; k += 1) {
+    if (PAIRS[text[k]]) depth += 1;
+    else if (')]}'.includes(text[k])) { depth -= 1; if (depth === 0) return text[k] === want ? k : -1; }
+  }
+  return -1;
+}
+
+function splitTop(text, seps) {
+  const out = [];
+  let depth = 0;
+  let cur = '';
+  for (const c of text) {
+    if (PAIRS[c]) depth += 1;
+    else if (')]}'.includes(c)) depth -= 1;
+    if (depth <= 0 && seps.includes(c)) { out.push(cur); cur = ''; } else cur += c;
+  }
+  out.push(cur);
+  return out;
+}
+
+export const statements = (code) => splitTop(code, '\n;').map((s) => s.trim()).filter(Boolean);
+export const splitArgs = (text) => (text.trim() ? splitTop(text, ',').map((s) => s.trim()) : []);
+
+// A postfix chain: a primary (a literal, a name, a parenthesised expression) and its .name, (args) and [index] steps.
+function chain(expr) {
+  let k = 0;
+  let primary;
+  const lit = expr.match(/^\x01(\d+)\x02/);
+  const name = expr.match(/^[A-Za-z_$][\w$]*/);
+  if (lit) { primary = { lit: Number(lit[1]) }; k = lit[0].length; }
+  else if (expr[0] === '(') { const e = closeOf(expr, 0); if (e < 0) return null; primary = { group: expr.slice(1, e) }; k = e + 1; }
+  else if (name) { primary = { name: name[0] }; k = name[0].length; }
+  else return null;
+  const steps = [];
+  while (k < expr.length) {
+    const rest = expr.slice(k);
+    const dot = rest.match(/^\s*(?:\.|->|::)\s*([A-Za-z_$][\w$]*)/);
+    if (dot) { steps.push({ name: dot[1] }); k += dot[0].length; continue; }
+    const ws = rest.match(/^\s*/)[0].length;
+    if (rest[ws] === '(' || rest[ws] === '[') {
+      const e = closeOf(expr, k + ws);
+      if (e < 0) return null;
+      steps.push(rest[ws] === '(' ? { args: splitArgs(expr.slice(k + ws + 1, e)) } : { index: expr.slice(k + ws + 1, e) });
+      k = e + 1;
+      continue;
+    }
+    return null;
+  }
+  return { primary, steps };
+}
+
+const str = (v) => (v && (v.t === 'str' || v.t === 'path') ? v.v : null);
+const joinPaths = (parts) => (parts.some((p) => p === null) ? null : parts.reduce((a, b) => (b.startsWith('/') ? b : a ? `${a.replace(/\/$/, '')}/${b}` : b), ''));
+const PATH_FNS = /^(?:(?:pathlib\.)?(?:Pure)?(?:Posix)?Path|os\.path\.join|path\.join|path\.resolve|join|resolve|File\.join|os\.path\.expanduser|os\.path\.abspath|path\.normalize)$/;
+const READS = /^(?:(?:fs|fsp|fs\.promises)\.)?readFileSync$|^File\.read$|^IO\.read$/;
+
+export function evaluate(expr, ctx) {
+  const e = expr.trim().replace(/^await\s+/, '');
+  if (!e) return null;
+  const plus = splitTop(e, '+');
+  if (plus.length > 1 && ctx.lang !== 'perl') {
+    const vs = plus.map((p) => str(evaluate(p, ctx)));
+    return vs.some((v) => v === null) ? null : { t: 'str', v: vs.join('') };
+  }
+  if (ctx.lang === 'python') {
+    const slash = splitTop(e, '/');
+    if (slash.length > 1) {
+      const vs = slash.map((p) => evaluate(p, ctx));
+      return vs[0]?.t === 'path' ? { t: 'path', v: joinPaths(vs.map(str)) } : null;
+    }
+  }
+  const c = chain(e);
+  if (!c) return null;
+  // callee: the dotted name while the chain is still a plain name (os.path.join, p.read_text); recv: the value before its last dot
+  let cur = null;
+  let callee = null;
+  let recv = null;
+  let method = null;
+  if (c.primary.lit !== undefined) cur = ctx.lits[c.primary.lit] === null ? null : { t: 'str', v: ctx.lits[c.primary.lit] };
+  else if (c.primary.group !== undefined) cur = evaluate(c.primary.group, ctx);
+  else { callee = c.primary.name; cur = ctx.env.get(callee) ?? null; }
+  for (const s of c.steps) {
+    if (s.name !== undefined) {
+      if (callee !== null) { recv = cur; callee = `${callee}.${s.name}`; cur = ctx.env.get(callee) ?? null; } else { method = s.name; }
+      continue;
+    }
+    if (s.args) {
+      if (callee !== null) {
+        const last = callee.split('.').pop();
+        cur = callFn(callee, s.args, ctx) ?? (recv && callee.includes('.') ? callMethod(recv, last, s.args, ctx) : null);
+        callee = null;
+      } else cur = method && cur ? callMethod(cur, method, s.args, ctx) : null;
+      method = null;
+      recv = null;
+      continue;
+    }
+    cur = null; callee = null; method = null;
+  }
+  return method ? null : cur;
+}
+
+function callFn(name, args, ctx) {
+  const vs = args.filter((a) => !/^\w+\s*=[^=]/.test(a)).map((a) => evaluate(a, ctx));
+  if (/(?:^|\.)Path\.home$/.test(name)) return process.env.HOME ? { t: 'path', v: process.env.HOME } : null;
+  if (/(?:^|\.)Path\.cwd$|^process\.cwd$|^os\.getcwd$/.test(name)) return { t: 'path', v: ctx.at('.') };
+  if (PATH_FNS.test(name)) return vs.length ? { t: 'path', v: joinPaths(vs.map(str)) } : null;
+  if (READS.test(name) || /^(?:io\.|codecs\.)?open$/.test(name)) {
+    const p = str(vs[0]);
+    if (p === null) return null;
+    ctx.reads?.add(ctx.at(p));
+    return READS.test(name) ? { t: 'str', v: ctx.readText(ctx.at(p)) ?? '' } : { t: 'file', v: p };
+  }
+  return null;
+}
+
+function callMethod(base, m, args, ctx) {
+  const vs = args.map((a) => evaluate(a, ctx));
+  if (['expanduser', 'resolve', 'absolute'].includes(m)) return base.t === 'path' ? base : null;
+  if (m === 'joinpath') return { t: 'path', v: joinPaths([base.v, ...vs.map(str)]) };
+  if ((m === 'read_text' && base.t === 'path') || (m === 'read' && base.t === 'file')) {
+    ctx.reads?.add(ctx.at(base.v));
+    return { t: 'str', v: ctx.readText(ctx.at(base.v)) ?? '' };
+  }
+  if ((m === 'replace' || m === 'replaceAll') && base.t === 'str') {
+    const [a, b] = vs.map(str);
+    if (a === null || b === null || /^\//.test(args[0] ?? '')) return null;
+    if (m === 'replace' && ctx.lang === 'node') return { t: 'str', v: base.v.replace(a, () => b) };
+    const n = vs[2] ? Number(str(vs[2]) ?? args[2]) : -1;
+    if (!(n < 0)) { let out = base.v; for (let k = 0; k < n && out.includes(a); k += 1) out = out.replace(a, () => b); return { t: 'str', v: out }; }
+    return { t: 'str', v: base.v.split(a).join(b) };
+  }
+  return null;
+}

package/global/hooks/lib/program-writes.mjs

@@ -0,0 +1,177 @@
+// program-writes: the files an inline program writes (KWB-8: `python3 - <<EOF ... open(p,'w').write(...)` got past every
+// write-time hook; the shell reader saw redirects, tee, sed -i, cp and heredocs, not a program's own writes).
+//   programOf(exe, args, stdin) -> { lang, code } | null
+//     an interpreter given its program inline: python -c / python - or python with a heredoc on stdin; node -e / -p /
+//     node - or a heredoc; perl -e / -E (or a heredoc); ruby -e (or a heredoc). A script file (python3 tools/x.py,
+//     node tools/x.mjs, python3 -m mod) is null: it is the project's own tool, reviewed like code, not judged as a write.
+//   programWrites(program, at, readText) -> [{ path, op, content, from? }]   (op and content as in shell-writes.mjs)
+//     a write is a call that opens or makes a file for writing: python open(p, 'w'|'a'|'x'|'r+'), Path.write_text /
+//     write_bytes / touch / unlink, shutil.copy* / move / copytree / rmtree, os.remove / rename / replace; node
+//     fs.writeFileSync / appendFileSync / copyFileSync / cpSync / renameSync / rmSync / unlinkSync / createWriteStream;
+//     perl open(FH, '>' ...), rename, unlink, File::Copy; ruby File.write / File.open(p, 'w') / FileUtils.*.
+//     A read (open(p), open(p, 'r'), read_text, readFileSync) is never a write. content is the new text where the
+//     program says it (a literal, or a file's text read and .replace'd, in a program with no loop or branch), else null.
+//     A write whose path the reader cannot work out makes every path the program names (its path-like literals, less
+//     the ones it only reads) a write of unknown content, so the path-based hooks still judge it.
+import { basename, join } from 'node:path';
+import { statSync } from 'node:fs';
+import { closeOf, evaluate, scan, splitArgs, statements } from './program-read.mjs';
+
+const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+
+export function programOf(exe, args, stdin) {
+  const lang = /^python(\d+(\.\d+)*)?$|^pypy3?$/.test(exe) ? 'python' : /^(node|nodejs|bun)$/.test(exe) ? 'node' : exe === 'perl' ? 'perl' : exe === 'ruby' ? 'ruby' : null;
+  if (!lang) return null;
+  const inline = { python: /^-[A-Za-z]*c$/, node: /^(-e|--eval|-p|--print|-pe)$/, perl: /^-[A-Za-z]*[eE]$/, ruby: /^-[A-Za-z]*e$/ }[lang];
+  const takesValue = { python: /^-[WXQ]$/, node: /^(-r|--require|--import|--loader|--experimental-loader|-C|--conditions)$/, perl: /^-[IMx]$/, ruby: /^-[Ir]$/ }[lang];
+  const code = [];
+  for (let k = 0; k < args.length; k += 1) {
+    const a = args[k];
+    if (inline.test(a)) { if (args[k + 1] !== undefined) code.push(args[k + 1]); k += 1; if (lang === 'python') break; continue; }
+    if (lang === 'node' && /^--(eval|print)=/.test(a)) { code.push(a.slice(a.indexOf('=') + 1)); continue; }
+    if (lang === 'python' && /^-[A-Za-z]*m$/.test(a)) return null;
+    if (takesValue.test(a)) { k += 1; continue; }
+    if (a.startsWith('-') && a !== '-') continue;
+    if (code.length) break;
+    return a === '-' && stdin !== null ? { lang, code: stdin } : null;
+  }
+  if (code.length) return { lang, code: code.join('\n') };
+  return stdin !== null && stdin !== undefined ? { lang, code: stdin } : null;
+}
+
+// The receiver of a method call: the postfix expression that ends just before text[dot].
+function receiverBefore(text, dot) {
+  let k = dot - 1;
+  while (k >= 0) {
+    const c = text[k];
+    if (c === ')' || c === ']') {
+      const open = c === ')' ? '(' : '[';
+      let depth = 0;
+      for (; k >= 0; k -= 1) { if (text[k] === c) depth += 1; else if (text[k] === open && --depth === 0) break; }
+      k -= 1;
+    } else if (c === '\x02') k = text.lastIndexOf('\x01', k) - 1;
+    else if (/[\w$.]/.test(c)) k -= 1;
+    else break;
+  }
+  return text.slice(k + 1, dot);
+}
+
+const modeOp = (m) => (m === null ? 'write' : /^\+?>>|a/.test(m) ? 'append' : /^\+</.test(m) || /r\+/.test(m) ? 'edit' : /[wx>]|\+/.test(m) ? 'write' : null);
+
+const SITES = {
+  python: /(?<![\w.])(?:io\.|codecs\.)?open\s*\(|\.(open|write_text|write_bytes|touch|unlink|rmdir)\s*\(|\bshutil\.(copy|copy2|copyfile|move|copytree|rmtree)\s*\(|\bos\.(remove|unlink|rename|replace)\s*\(/g,
+  node: /\b(writeFileSync|writeFile|appendFileSync|appendFile|copyFileSync|copyFile|cpSync|renameSync|rmSync|unlinkSync|createWriteStream|truncateSync|openSync|outputFileSync)\s*\(|\bBun\.(write)\s*\(/g,
+  perl: /\bopen\s*(?=[\s(])|\b(rename|unlink|copy|move)\s*\(/g,
+  ruby: /\b(?:File|IO)\.(write|binwrite|open|rename|delete|unlink)\s*\(|\bFileUtils\.(cp|copy|mv|move|rm|rm_f|rm_rf|touch|install)\s*\(/g,
+};
+
+const COPY = /^(copy|copy2|copyfile|copyFileSync|copyFile|cp|install)$/;
+const MOVE = /^(move|rename|replace|renameSync|mv)$/;
+const DELETE = /^(rmtree|remove|unlink|rmdir|rmSync|unlinkSync|delete|rm|rm_f|rm_rf)$/;
+
+export function programWrites({ lang, code: src }, at, readText) {
+  const { code, lits } = scan(src, lang);
+  const stmts = statements(code);
+  const branchy = /\b(for|while|foreach|until|unless|lambda|function|each|map|if|elif|else|try|switch|case|def)\b|=>|\bdo\b/.test(code);
+  const ASSIGN = /^(?:(?:const|let|var|my|our)\s+)?([$@%]?[A-Za-z_][\w.]*)\s*(\+?)=(?!=)\s*([\s\S]+)$/;
+  const count = new Map();
+  for (const s of stmts) { const m = s.match(ASSIGN); if (m) count.set(m[1], (count.get(m[1]) ?? 0) + 1); }
+  const env = new Map();
+  const reads = new Set();
+  const ctx = { env, lits, lang, at, readText, reads };
+  const val = (e) => (e === undefined ? null : evaluate(e, ctx));
+  const pathOf = (e) => { const v = val(e); return v && (v.t === 'str' || v.t === 'path') && v.v ? at(v.v) : null; };
+  const textOf = (e) => { const v = val(e); return !branchy && v && v.t === 'str' ? v.v : null; };
+  const out = [];
+  const handles = new Map();
+  let unresolved = false;
+  const add = (path, op, content, extra = {}) => { if (path === null) unresolved = true; else out.push({ path, op, content, ...extra }); return out.at(-1); };
+  const kw = (args, name) => args.find((a) => new RegExp(`^${name}\\s*=`).test(a))?.replace(/^\w+\s*=\s*/, '');
+  const modeArg = (e) => (e === undefined ? undefined : val(e)?.t === 'str' ? val(e).v : null);
+
+  for (const s of stmts) {
+    for (const m of s.matchAll(SITES[lang])) {
+      const name = m.slice(1).find(Boolean) ?? 'open';
+      const paren = s.indexOf('(', m.index + m[0].length - 1);
+      let args;
+      let end;
+      if (lang === 'perl' && name === 'open' && s[paren] !== '(' ) {
+        const rest = s.slice(m.index + m[0].length).split(/\s+(?:or|\|\|)\s+|\s+or$/)[0];
+        args = splitArgs(rest.replace(/^\s*\(|\)\s*$/g, ''));
+        end = s.length;
+      } else {
+        end = closeOf(s, paren);
+        if (end < 0) continue;
+        args = splitArgs(s.slice(paren + 1, end));
+      }
+      const pos = args.filter((a) => !/^\w+\s*=[^=]/.test(a));
+      const method = m[0].startsWith('.');
+      const recv = method ? receiverBefore(s, m.index) : null;
+      let site = null;
+      if (lang === 'perl' && name === 'open') {
+        const mode = pos.length >= 3 ? modeArg(pos[1]) : modeArg(pos[1]);
+        if (pos.length >= 3) { const op = modeOp(mode); if (op) site = add(pathOf(pos[2]), op, null); } else if (mode !== null && mode !== undefined) {
+          const two = mode.match(/^\s*(\+?[<>]{1,2}|\|)?\s*(.*)$/);
+          const op = two[1] && two[1] !== '|' ? modeOp(two[1]) : null;
+          if (op) site = add(two[2] ? at(two[2]) : null, op, null);
+        } else if (pos[1] !== undefined) site = add(null, 'write', null);
+      } else if (name === 'open' || name === 'openSync') {
+        if (method && val(recv)?.t !== 'path') continue;
+        const target = method ? recv : pos[0];
+        const mode = modeArg(method ? pos[0] ?? kw(args, 'mode') : pos[1] ?? kw(args, 'mode'));
+        const op = mode === undefined ? null : modeOp(mode);
+        if (!op) { const p = pathOf(target); if (p) reads.add(p); continue; }
+        site = add(pathOf(target), op, op === 'edit' ? null : '');
+        const after = s.slice(end + 1);
+        const chained = after.match(/^\s*\.\s*write\s*\(/);
+        const as = after.match(/^\s*as\s+([A-Za-z_]\w*)/) ?? s.slice(0, m.index).match(/^([A-Za-z_]\w*)\s*=\s*$/);
+        if (site && chained) { const e = closeOf(after, after.indexOf('(')); site.content = e < 0 ? null : textOf(after.slice(after.indexOf('(') + 1, e)); }
+        else if (site && as) handles.set(as[1], { site, parts: [], ok: !branchy && site.content !== null, uses: 0 });
+        else if (site) site.content = null;
+      } else if (name === 'write_text' || name === 'write' || name === 'binwrite' || /^(writeFile|outputFile)/.test(name) || /^appendFile/.test(name)) {
+        const target = method ? recv : pos[0];
+        site = add(pathOf(target), /^append/.test(name) ? 'append' : 'write', name === 'binwrite' ? null : textOf(method ? pos[0] : pos[1]));
+      } else if (name === 'write_bytes' || name === 'createWriteStream' || name === 'truncateSync') site = add(pathOf(method ? recv : pos[0]), name === 'truncateSync' ? 'truncate' : 'write', null);
+      else if (name === 'touch') site = add(pathOf(method ? recv : pos[0]), 'touch', null);
+      else if (DELETE.test(name)) { if (method && val(recv)?.t !== 'path') continue; for (const a of method ? [recv] : pos.slice(0, lang === 'ruby' ? pos.length : 1)) add(pathOf(a), 'delete', null); }
+      else if (COPY.test(name) || MOVE.test(name) || /^(copytree|cpSync)$/.test(name)) {
+        if (method) continue;
+        const from = pathOf(pos[0]);
+        let to = pathOf(pos[1]);
+        if (to && from && isDir(to) && !/^(copytree|cpSync)$/.test(name)) to = join(to, basename(from));
+        const tree = /^(copytree|cpSync)$/.test(name);
+        add(to, MOVE.test(name) ? 'move' : 'copy', tree || !from ? null : readText(from), from ? { from } : {});
+        if (MOVE.test(name)) add(from, 'delete', null);
+      }
+    }
+    for (const [h, rec] of handles) {
+      for (const m of s.matchAll(new RegExp(`(?<![\\w.])${h.replace(/\$/g, '\\$')}\\b`, 'g'))) {
+        rec.uses += 1;
+        const after = s.slice(m.index + h.length);
+        const w = after.match(/^\s*\.\s*(write|close)\s*\(/);
+        if (!w) continue;
+        rec.uses -= 1;
+        if (w[1] === 'close') continue;
+        const open = m.index + h.length + after.indexOf('(');
+        const e = closeOf(s, open);
+        const t = e < 0 ? null : textOf(s.slice(open + 1, e));
+        if (t === null) rec.ok = false; else rec.parts.push(t);
+      }
+    }
+    const a = s.match(ASSIGN);
+    if (a) {
+      const v = branchy && count.get(a[1]) > 1 ? null : a[2] ? ((x, y) => (x?.t === 'str' && y?.t === 'str' ? { t: 'str', v: x.v + y.v } : null))(env.get(a[1]), val(a[3])) : val(a[3]);
+      if (v) env.set(a[1], v); else env.delete(a[1]);
+    }
+  }
+  for (const rec of handles.values()) rec.site.content = rec.ok && rec.uses <= 1 ? rec.parts.join('') : null;
+  if (unresolved) {
+    const named = new Set(out.map((w) => w.path));
+    for (const l of lits) {
+      if (l === null || l.length > 300 || !/^[~\w.@+\-/]+$/.test(l) || /^[-.]+$|^-|^\d+(\.\d+)*$/.test(l) || !(l.includes('/') || /\.[A-Za-z][A-Za-z0-9]{0,7}$/.test(l))) continue;
+      const p = at(l);
+      if (!named.has(p) && !reads.has(p)) { named.add(p); out.push({ path: p, op: 'write', content: null, named: true }); }
+    }
+  }
+  return out;
+}