heeded 0.0.0-stage → 0.1.0

package/dist/rules.js

@@ -0,0 +1,376 @@
+// From instruction files to rules: sections, the extraction call, verification, the cache.
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { applies, compile, LANGUAGES, verdict } from './check.js';
+import { ask, batches, pool } from './model.js';
+import { redact } from './redact.js';
+/** The extraction prompt's version: part of every cache key, so a new prompt reads every section again. */
+export const PROMPT_VERSION = 4;
+export const MODEL = 'sonnet';
+/** A section's key in the cache, under a version of the prompt. */
+export const sectionHash = (path, text, version = PROMPT_VERSION) => createHash('sha256').update(JSON.stringify([version, MODEL, path, text])).digest('hex');
+export function sections(content) {
+    const out = [];
+    const ancestors = [];
+    let path = [];
+    let lines = [];
+    let heading = '';
+    // A heading with nothing under it holds no rule: it is context for its subsections.
+    const close = () => {
+        const text = lines.join('\n').trim();
+        if (text && text !== heading)
+            out.push({ path, text, hash: sectionHash(path, text) });
+    };
+    let fence = ''; // the marker of the open code block: it closes with its own kind, at least as long
+    for (const line of content.replace(/\r\n?/g, '\n').split('\n')) {
+        const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+        if (marker && !fence)
+            fence = marker;
+        else if (marker && marker[0] === fence[0] && marker.length >= fence.length)
+            fence = '';
+        const h = fence ? null : /^(#{1,6})[ \t]+(.+)$/.exec(line);
+        if (h) {
+            close();
+            const level = h[1].length;
+            while (ancestors.length && ancestors[ancestors.length - 1].level >= level)
+                ancestors.pop();
+            path = ancestors.map((a) => a.title);
+            ancestors.push({ level, title: h[2].trim() });
+            heading = line.trim();
+            lines = [];
+        }
+        lines.push(line);
+    }
+    close();
+    return out;
+}
+const collapse = (text) => text.replace(/\s+/g, ' ').trim();
+/**
+ * A rule as the extraction returned it, checked here: its quote must be in its section as the model read it (secrets
+ * redacted), word for word (spacing aside), or the rule is dropped; a check that can't be trusted is demoted, with the
+ * reason, and never gives a violation.
+ */
+export function verify(raw, section) {
+    const r = raw;
+    if (typeof r?.quote !== 'string' || !collapse(redact(section.text)).includes(collapse(r.quote)))
+        return null;
+    const id = createHash('sha256').update(collapse(r.quote).toLowerCase()).digest('hex').slice(0, 8);
+    const name = [...String(r.name).replace(/[\p{Cc}\s]+/gu, ' ').trim()].slice(0, 40).join('').trimEnd();
+    const own = /^#{1,6}[ \t]+(.+)$/.exec(section.text.split('\n')[0])?.[1].trim();
+    const heading = [...section.path, ...(own ? [own] : [])].join(' › ');
+    // What the section says around the rule: from 500 characters before its words to 1,000 after.
+    const text = collapse(redact(section.text));
+    const at = text.indexOf(collapse(r.quote));
+    const [from, to] = [Math.max(0, at - 500), Math.min(text.length, at + collapse(r.quote).length + 1000)];
+    const context = `${from ? '…' : ''}${text.slice(from, to)}${to < text.length ? '…' : ''}`;
+    const rule = { ...r, id, name, heading, context };
+    if (rule.kind === 'judgment') {
+        // What breaks a judgment rule is for the judge to say: its check only finds the cases.
+        const { broken: _, ...check } = rule.check ?? {};
+        const judged = rule.check ? { ...rule, check } : rule;
+        const noCases = casesless(judged);
+        return noCases ? { ...judged, noCases } : judged;
+    }
+    const language = rule.check?.language;
+    const demoted = rule.kind === 'tool' ? demotion(rule)
+        : rule.kind === 'language' && !LANGUAGES.includes(String(language)) ? `language ${language} not supported` : undefined;
+    return demoted ? { ...rule, demoted } : rule;
+}
+function demotion(rule) {
+    const b = rule.check?.broken;
+    if (b?.tool === undefined && b?.value === undefined && b?.data === undefined)
+        return 'no broken pattern';
+    const compiled = compile(rule.check);
+    if (typeof compiled === 'string')
+        return compiled;
+    if (!rule.breaking?.length)
+        return 'no breaking example';
+    if (!rule.keeping?.length)
+        return 'no keeping example';
+    const call = (e) => verdict(compiled, e.tool, compiled.field === undefined ? {} : { [compiled.field]: e.value });
+    const breaks = rule.breaking.find((e) => call(e) !== 'broken');
+    if (breaks)
+        return `failed its examples: breaks "${breaks.value}"`;
+    // A keeping example may be a near miss the rule doesn't apply to (a search for the forbidden word); none may break it.
+    const keeps = rule.keeping.find((e) => call(e) === 'broken');
+    if (keeps)
+        return `failed its examples: keeps "${keeps.value}"`;
+    if (!rule.keeping.some((e) => call(e) === 'kept'))
+        return 'failed its examples: none of the keeping examples applies';
+}
+/** Why a judgment rule has no case a judge could read, if so: a rule about replies has every reply; another needs a
+ * `when` that compiles and finds each of its keeping examples. */
+function casesless(rule) {
+    const c = rule.check;
+    if (c?.reply === true)
+        return;
+    if (c?.when?.tool === undefined && c?.when?.value === undefined && c?.when?.data === undefined)
+        return 'no case to judge it on';
+    const compiled = compile(c);
+    if (typeof compiled === 'string')
+        return compiled;
+    if (!rule.keeping?.length)
+        return 'no example of a case';
+    const missed = rule.keeping.find((e) => !applies(compiled, e.tool, compiled.field === undefined ? {} : { [compiled.field]: e.value }));
+    if (missed)
+        return `failed its examples: "${missed.value}" is not a case`;
+}
+/** A section's rules as the extraction returned them, or null when they were never read (or the file is damaged). */
+export function load(cacheDir, hash) {
+    try {
+        const rules = JSON.parse(readFileSync(join(cacheDir, 'heeded', `${hash}.json`), 'utf8'));
+        return Array.isArray(rules) ? rules : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Written whole or not at all: a temporary file, then a rename. */
+export function write(dir, name, value) {
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `${name}.${process.pid}.tmp`);
+    writeFileSync(tmp, JSON.stringify(value));
+    renameSync(tmp, join(dir, `${name}.json`));
+}
+export function save(cacheDir, hash, rules) {
+    write(join(cacheDir, 'heeded'), hash, rules);
+}
+/** The same section across versions of its file: the file, the headings above it, its own heading, and which one of
+ * that name it is when a file repeats a heading. */
+function identity(path, s, seen) {
+    const key = JSON.stringify([s.path, /^#{1,6}[ \t]/.test(s.text) ? s.text.split('\n')[0] : '']);
+    const n = seen.get(key) ?? 0;
+    seen.set(key, n + 1);
+    return JSON.stringify([path, ...JSON.parse(key), ...(n ? [n] : [])]);
+}
+const latest = (cacheDir) => join(cacheDir, 'heeded', 'latest');
+// Under the prompt's version and the model, like each section's hash: a new prompt reads every section again.
+const idHash = (id, version) => createHash('sha256').update(JSON.stringify([version, MODEL, id])).digest('hex');
+/** The version of a section read last, by the time it was in effect: the one older versions take their rules from. */
+function recall(cacheDir, id, version = PROMPT_VERSION) {
+    try {
+        const known = JSON.parse(readFileSync(join(latest(cacheDir), `${idHash(id, version)}.json`), 'utf8'));
+        return typeof known?.hash === 'string' && typeof known.at === 'string' ? known : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Remembers a read version of a section, unless one in effect as late or later is remembered already: the cache is
+ * shared by every folder and config dir, whose histories interleave. */
+export function remember(cacheDir, id, hash, at, version = PROMPT_VERSION) {
+    const known = recall(cacheDir, id, version);
+    if (!known || at > known.at)
+        write(latest(cacheDir), idHash(id, version), { hash, at });
+}
+/**
+ * A file's rules from the cache, and its sections never read, memoized by path and content: worktrees and sessions
+ * record the same files over and over. A section never read takes the rules of the version of it read last, each kept
+ * only where its words are written. Null for a file not measured: `AutoMem` is Claude Code's memory index, one-line
+ * pointers edited constantly.
+ */
+export function rulesOf(cacheDir) {
+    const seen = new Map();
+    return (file) => {
+        if (file.type === 'AutoMem')
+            return null;
+        let byContent = seen.get(file.path);
+        if (!byContent)
+            seen.set(file.path, (byContent = new Map()));
+        let found = byContent.get(file.content);
+        if (!found) {
+            found = { rules: [], versions: [] };
+            const names = new Map();
+            for (const section of sections(file.content)) {
+                const id = identity(file.path, section, names);
+                const known = recall(cacheDir, id);
+                let raw = load(cacheDir, section.hash);
+                const read = raw !== null;
+                if (raw === null && known)
+                    raw = load(cacheDir, known.hash);
+                // Read under the previous prompt only: those rules stand until the section is read under this one. One step
+                // back: a prompt older than that is read again from nothing.
+                if (raw === null) {
+                    const older = recall(cacheDir, id, PROMPT_VERSION - 1);
+                    raw = load(cacheDir, sectionHash(section.path, section.text, PROMPT_VERSION - 1)) ?? (older && load(cacheDir, older.hash));
+                }
+                const rules = (raw ?? []).map((r) => verify(r, section)).filter((r) => r !== null);
+                for (const rule of rules)
+                    found.rules.push({ ...rule, file: file.path });
+                // Read before: found to hold no rule, or with rules whose words are still written in it. Rules none of which is
+                // still there stand for nothing: it is as never read.
+                const before = !read && raw !== null && (raw.length === 0 || rules.length > 0);
+                found.versions.push({ section, identity: id, read, readAt: known?.at ?? null, before });
+            }
+            byContent.set(file.content, found);
+        }
+        return found;
+    };
+}
+/** Sections go to claude in calls of at most 30,000 characters of their text. */
+const BATCH = 30_000;
+/** What reading `sections` would cost: each call carries ~5.6k tokens of prompt, schema and claude's own; the text is
+ * read once and answered with about five times as much (a JSON object per rule, with its check and examples). Fitted on
+ * real calls with prompt v4 (13 sections, 24.6k and 27.3k tokens; a short section, 5.6k–5.8k); the real count is shown
+ * after. */
+export function estimate(sections) {
+    const calls = batches(sections, (s) => s.text.length, BATCH).length;
+    const chars = sections.reduce((n, s) => n + s.text.length, 0);
+    return { calls, tokens: 5600 * calls + 6 * Math.ceil(chars / 4) };
+}
+const PATTERNS = { type: 'object', properties: { tool: { type: 'string' }, value: { type: 'string' }, data: { type: 'string' } } };
+const EXAMPLES = {
+    type: 'array',
+    items: { type: 'object', properties: { tool: { type: 'string' }, value: { type: 'string' } }, required: ['tool', 'value'] },
+};
+const SCHEMA = JSON.stringify({
+    type: 'object',
+    properties: {
+        sections: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    id: { type: 'string' },
+                    rules: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                quote: { type: 'string' },
+                                name: { type: 'string' },
+                                kind: { enum: ['tool', 'language', 'judgment'] },
+                                trigger: { type: 'string' },
+                                check: {
+                                    type: 'object',
+                                    properties: {
+                                        field: { type: 'string' }, when: PATTERNS, broken: PATTERNS, ignoreCase: { type: 'boolean' },
+                                        language: { type: 'string' }, reply: { type: 'boolean' },
+                                    },
+                                },
+                                breaking: EXAMPLES,
+                                keeping: EXAMPLES,
+                            },
+                            required: ['quote', 'name', 'kind', 'trigger'],
+                        },
+                    },
+                },
+                required: ['id', 'rules'],
+            },
+        },
+    },
+    required: ['sections'],
+});
+// Raw: the regexes in it reach the model as written.
+const PROMPT = String.raw `You read the instruction files a coding agent (Claude Code) is given, and list the rules in them, so that a tool
+can check later whether the agent followed each one. Below are sections of those files. Return every section by its id
+with the rules it states: an empty list when it states none. A rule tells the agent to do or not to do something;
+descriptions, explanations and context are not rules. List every rule, whether a tool can check it or not: the user
+reads this list to know what their files ask.
+
+For each rule:
+- quote: the rule's own words, copied exactly from the section: never reworded, typos and formatting (backticks) kept.
+- name: a summary of at most 40 characters, in the rule's own language.
+- kind: "tool" when a single tool call shows, without doubt and whatever came before it, whether the rule was kept or
+  broken; "language" for the language the agent must use in its replies to the user (not in code, commits or files);
+  "judgment" for everything else. A rule with an exception, or a condition one call can't show (the user's go or
+  request, being asked first, a folder or a sub-project, a time, before or after something else), is "judgment".
+- trigger: when the rule applies, in a few words ("staging files with git").
+
+A "language" rule has check: { "language": "<two-letter ISO 639-1 code>" }.
+
+A "tool" rule has a check over one call: its tool name and one top-level string field of its input.
+- Claude Code tools: Bash (field "command"), Edit (file_path, old_string, new_string), Write (file_path, content),
+  Read (file_path); MCP tools are named mcp__<server>__<tool>. A file_path is absolute: match a folder in it
+  (/vendor/) or its end (\.lock$), not its start.
+- field: the input field matched; left out to match on the tool name alone.
+- A "command" is read the way a shell reads it, one simple command at a time (split on &&, ||, ;, |, & and line
+  breaks). "value" sees what a simple command does: its words, with quoted text emptied ('' and "" stay) and heredoc
+  bodies left out; it may start with assignments (CI=1), sudo, env, time or nohup. Match a program or a subcommand as
+  a whole word of the command, (^|\s)tsc(\s|$) or (^|\s)git\s+push(\s|$), never with \b: it matches inside paths and
+  hyphenated words (tsc-after.txt, git merge-base). "data" sees what it carries: its heredoc bodies, then its quoted
+  texts, one per line, such as a commit message; it is empty when there are none, and ^ and $ anchor the whole of it.
+  A rule on a message's form needs a "data" in "when" too, like \S, so a command without a message is not counted.
+  What sh -c, bash -c, ssh, eval and $( … ) run is read as commands too. Any other field is matched whole by "value".
+- when: the calls the rule is about: "tool", a regex over the tool name (anchored, like ^Bash$), and "value" and "data",
+  regexes as above; any may be left out.
+- broken: what makes such a call break the rule: a "tool", "value" or "data" regex, at least one. For a command, when
+  and broken must match the same simple command.
+- ignoreCase: true when letter case doesn't matter.
+- The regexes are JavaScript, without flags, and never repeat a group that holds a quantifier or an alternation, like
+  (a+)+ or (a|b)+.
+- breaking: two or three example calls { "tool", "value" } that break the rule; keeping: two or three calls that keep
+  it, at least one the rule is about, and near misses chosen for the rule that must not break it: a path or a file
+  name holding the forbidden word, a read-only form of the command (git tag alone lists tags), its --help, a search or
+  an echo naming it. A value is the field's whole value: for Bash, a whole command line.
+
+A "judgment" rule has a check that finds the cases a judge will read whenever some calls or replies can show it kept
+or broken, however many they are: { "reply": true } for a rule about what the agent tells the user; else the calls it
+is about, as a tool rule's "field" and "when", without "broken", and always with keeping: one or two calls that are
+cases of the rule, each matched by "when", never a call that only keeps the rule without being one of its cases (a
+read of a file the rule forbids editing). A check without them is not used.
+- A rule about what the agent writes in files (code, comments, tests, docs, their language or their style) has as
+  cases the Edit and Write calls on the files it is about ("field": "file_path"; left out for any file): the judge
+  reads what each one writes.
+- A rule about commit messages has the git commit commands with a message ("data": "\S" in "when").
+- A rule about a command, a setting or a tool has the calls that run it.
+Leave the check out only when no call or reply can show the rule (how to plan, what to remember, the order of the
+work): the rule is listed all the same.
+`;
+/**
+ * Reads the rules of the pending sections through the user's own claude, sonnet, one call per batch, up to 3 at once,
+ * and caches each batch as it comes, each section remembered as its section's latest read version: an interrupted run
+ * keeps what it paid for. Only the sections' text leaves the machine, secrets redacted; never a file's path. A batch
+ * that fails is reported and nothing of it is cached. Errors come in the order of the batches. `progress` hears of the
+ * calls done, of how many.
+ */
+export async function extract(pending, env, cacheDir, progress) {
+    const errors = [];
+    let read = 0;
+    let tokens = 0;
+    let done = 0;
+    let fatal = false;
+    // A text under several paths (a worktree's copy of a file) is sent once, and remembered for each.
+    const byHash = new Map();
+    for (const p of pending)
+        byHash.set(p.section.hash, [...(byHash.get(p.section.hash) ?? []), p]);
+    const all = batches([...byHash.values()], (group) => group[0].section.text.length, BATCH);
+    progress?.(0, all.length);
+    await pool(all, async (batch, b, stop) => {
+        const body = batch.map(([{ section: s }], i) => `<section id="${i + 1}" path="${redact(s.path.join(' › ')).replaceAll('"', "'")}">\n${redact(s.text)}\n</section>`);
+        const run = await ask(MODEL, SCHEMA, `${PROMPT}\n${body.join('\n\n')}\n`, env);
+        progress?.(++done, all.length);
+        tokens += run.tokens;
+        if (run.error) {
+            // No claude to run: said once, though the calls already started fail the same way.
+            if (!fatal)
+                errors[b] = run.error;
+            if (run.fatal) {
+                fatal = true;
+                stop();
+            }
+            return;
+        }
+        const answered = run.output?.sections;
+        if (!Array.isArray(answered) || !answered.every((a) => typeof a?.id === 'string' && Array.isArray(a.rules))) {
+            errors[b] = "claude's answer didn't match the schema";
+            return;
+        }
+        // A section left out of the answer is not cached as holding no rule: it is asked about again.
+        const byId = new Map(answered.map((a) => [a?.id, a?.rules]));
+        let left = 0;
+        batch.forEach((group, i) => {
+            const rules = byId.get(String(i + 1));
+            if (!Array.isArray(rules))
+                return void left++;
+            save(cacheDir, group[0].section.hash, rules);
+            for (const p of group)
+                remember(cacheDir, p.identity, p.section.hash, p.at);
+        });
+        if (left)
+            errors[b] = `claude's answer left out ${left} of ${batch.length} sections: they will be asked about again`;
+        read += batch.length - left;
+    });
+    return { read, tokens, errors: errors.filter((e) => e !== undefined) };
+}

package/dist/shell.js

@@ -0,0 +1,182 @@
+// A shell command line read the way a shell reads it, without running one: its simple commands, each with what it
+// does (its quoted text emptied, heredoc bodies out) and what it carries (that quoted text and those bodies). Rules
+// about running something look at the first; rules about a commit message look at the second; a search for a word, or
+// a file written with it, does neither.
+/** Where the substitution opened at `i` ends: past its closing `)` or backtick, its quotes and nested parentheses read
+ * as a shell reads them; the end of the line when it is left open. */
+function substitution(line, i) {
+    let j = i + 1;
+    if (line[i] === '`') {
+        while (j < line.length && line[j] !== '`')
+            j += line[j] === '\\' ? 2 : 1;
+    }
+    else {
+        for (let depth = 0; j < line.length; j++) {
+            const c = line[j];
+            if (c === '\\')
+                j++;
+            else if (c === "'" || c === '"')
+                j = quoted(line, j).end - 1;
+            else if (c === '`')
+                j = substitution(line, j).end - 1;
+            else if (c === '(')
+                depth++;
+            else if (c === ')' && --depth === 0)
+                break;
+        }
+    }
+    const end = Math.min(j + 1, line.length);
+    // $(( … )) is arithmetic, not a command.
+    const inner = line.startsWith('$((', i) ? '' : line.slice(line[i] === '`' ? i + 1 : i + 2, j);
+    return { end, text: line.slice(i, end), inner };
+}
+/** The quoted text opened at `i`: where it ends (past its closing quote, or the end of the line), its content, the
+ * quotes as they stay in what the command does (one when it is left open), and the substitutions in a `"…"`. */
+function quoted(line, i) {
+    const open = line[i] === '$' ? "$'" : line[i];
+    const close = open.at(-1);
+    const subs = [];
+    let j = i + open.length;
+    while (j < line.length && line[j] !== close) {
+        // In "…" a backslash escapes only these, and $( … ) and backticks run commands; in $'…' a backslash escapes
+        // anything; in '…' nothing is special.
+        if (open === '"' && (line.startsWith('$(', j) || line[j] === '`')) {
+            const sub = substitution(line, j);
+            subs.push(sub);
+            j = sub.end;
+            continue;
+        }
+        if (line[j] === '\\' && (open === "$'" || (open === '"' && '"\\$`'.includes(line[j + 1] ?? ''))))
+            j++;
+        j++;
+    }
+    const closed = j < line.length;
+    return { end: closed ? j + 1 : line.length, content: line.slice(i + open.length, j), quotes: closed ? open + close : open, subs };
+}
+/**
+ * Heredoc bodies taken out of the raw lines, each with the offset of its `<<` in the text left. Found before quotes
+ * are read, since a heredoc inside `"$( … )"` (how commit messages are often written) holds any quotes; and only with
+ * its closing line, so `$((1 << 2))` is not one.
+ */
+function heredocs(line) {
+    const lines = line.replace(/\r\n?/g, '\n').split('\n');
+    const kept = [];
+    const bodies = [];
+    // A closing line not found from some line on is not found from any later one: each is looked for once.
+    const missing = new Map();
+    const closing = (word, tabs, from) => {
+        const key = `${tabs}${word}`;
+        if ((missing.get(key) ?? Infinity) <= from)
+            return -1;
+        for (let k = from; k < lines.length; k++)
+            if ((tabs ? lines[k].replace(/^\t+/, '') : lines[k]) === word)
+                return k;
+        missing.set(key, from);
+        return -1;
+    };
+    let offset = 0;
+    for (let i = 0; i < lines.length; i++) {
+        let next = i + 1;
+        let line = '';
+        let from = 0;
+        // `\EOF` is a heredoc like `'EOF'`; a line that is a comment opens none.
+        const markers = /^\s*#/.test(lines[i]) ? [] : lines[i].matchAll(/(?<!<)<<(?!<)(-?)\s*\\?(['"]?)([\w.-]+)\2/g);
+        for (const m of markers) {
+            const end = closing(m[3], m[1] === '-', next);
+            if (end < 0)
+                continue;
+            // The marker is kept without its quotes: they only say how the body is expanded.
+            line += lines[i].slice(from, m.index);
+            bodies.push({ at: offset + line.length, body: lines.slice(next, end).join('\n') });
+            line += `<<${m[1]}${m[3]}`;
+            from = m.index + m[0].length;
+            next = end + 1;
+        }
+        line += lines[i].slice(from);
+        kept.push(line);
+        offset += line.length + 1;
+        i = next - 1;
+    }
+    return { text: kept.join('\n'), bodies };
+}
+/**
+ * A command that runs what it carries: a shell given `-c` (`bash -c '…'`, `docker exec app sh -c '…'`) or only options
+ * and a heredoc (`sh <<EOF`), `ssh`, `eval`; wherever it sits in the command, its path optional. A shell given a script
+ * (`bash run.sh "x"`) is not one.
+ */
+const SHELL = String.raw `(?:^|\s)(?:\S*/)?(?:sh|bash|zsh|dash)`;
+const WRAPPER = new RegExp(String.raw `${SHELL}\s(?:.*\s)?-[a-zA-Z]*c\b|${SHELL}(?:\s+-\S+)*\s*(?:$|<<)|(?:^|\s)(?:ssh|eval)\s`);
+/** Shell syntax that may open a simple command without being part of what it runs. */
+const SYNTAX = /^(?:[({!]\s*|(?:if|then|else|elif|do|while|until)\s+)+/;
+export function commands(raw) {
+    const { text: line, bodies } = heredocs(raw);
+    const out = [];
+    let does = '';
+    let carried = [];
+    let inner = []; // the commands of its substitutions
+    let start = 0;
+    const close = (end, next) => {
+        // Heredoc bodies first: a commit message written through one is what the command carries, from its first line.
+        const carries = [...bodies.filter((b) => b.at >= start && b.at < end).map((b) => b.body), ...carried].filter(Boolean);
+        const command = does.trim().replace(SYNTAX, '');
+        if (command) {
+            out.push({ does: command, carries: carries.join('\n'), text: line.slice(start, end).trim() });
+            if (WRAPPER.test(command))
+                for (const c of carries)
+                    out.push(...commands(c));
+            out.push(...inner);
+        }
+        does = '';
+        carried = [];
+        inner = [];
+        start = next;
+    };
+    let i = 0;
+    while (i < line.length) {
+        const c = line[i];
+        const two = line.slice(i, i + 2);
+        if (c === "'" || c === '"' || two === "$'") {
+            const q = quoted(line, i);
+            does += q.quotes;
+            for (const sub of q.subs)
+                inner.push(...commands(sub.inner));
+            // A quoted text that is one substitution carries what its commands carry: `"$(printf 'feat: x')"` carries the
+            // message, not the command that prints it.
+            const only = q.subs.length === 1 && q.content.trim() === q.subs[0].text;
+            carried.push(only ? commands(q.subs[0].inner).map((x) => x.carries).filter(Boolean).join('\n') : q.content);
+            i = q.end;
+        }
+        else if (two === '$(' || c === '`') {
+            const sub = substitution(line, i);
+            does += sub.text;
+            inner.push(...commands(sub.inner));
+            i = sub.end;
+        }
+        else if (c === '\\') {
+            // A backslash before a line break continues the line; before anything else it escapes it.
+            if (line[i + 1] !== '\n')
+                does += two;
+            i += 2;
+        }
+        else if (c === '#' && (i === start || /\s/.test(line[i - 1]))) {
+            // A comment runs to the end of its line.
+            while (i < line.length && line[i] !== '\n')
+                i++;
+        }
+        else if (two === '&&' || two === '||' || two === '|&') {
+            close(i, i + 2);
+            i += 2;
+        }
+        else if (c === ';' || c === '\n' || (c === '|' && line[i - 1] !== '>')
+            || (c === '&' && !/[<>]/.test(line[i - 1] ?? '') && line[i + 1] !== '>')) {
+            close(i, i + 1);
+            i++;
+        }
+        else {
+            does += c;
+            i++;
+        }
+    }
+    close(line.length, line.length);
+    return out;
+}

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "heeded",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "did your coding agent follow its instructions?",
+  "license": "MIT",
+  "author": "Francesco Musso",
+  "repository": { "type": "git", "url": "git+https://github.com/frmusso/heeded.git" },
+  "bugs": "https://github.com/frmusso/heeded/issues",
+  "homepage": "https://github.com/frmusso/heeded#readme",
+  "keywords": ["claude-code", "claude", "coding-agent", "claude-md", "instructions", "transcripts", "cli"],
+  "type": "module",
+  "bin": { "heeded": "dist/cli.js" },
+  "files": ["dist"],
+  "engines": { "node": ">=22" },
+  "scripts": {
+    "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc",
+    "test": "node --test --test-concurrency=1 'tests/**/*.test.ts'"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.5",
+    "typescript": "7.0.2"
+  }
+}