@open-tomato/rafa 0.7.1

package/dist/index-adgde7x3.js

@@ -0,0 +1,1101 @@
+// @bun
+import {
+  activeOutput,
+  messageOf,
+  parseTaskDeclaration,
+  readRafaBlocks
+} from "./index-akz06erg.js";
+// src/preflight/prerequisites-md.ts
+import { basename, dirname, join } from "path";
+var SECTION_AUTO_RE = /\[auto\]/i;
+var SECTION_START_RE = /\[start\]/i;
+var SECTION_HUMAN_RE = /\[human\]|manual|human|sign.?off|team/i;
+var ITEM_RE = /^-\s+\[\s*\]\s+/;
+var INLINE_AUTO_RE = /^-\s+\[\s*\]\s+\[auto\]\s+/i;
+var INLINE_HUMAN_RE = /^-\s+\[\s*\]\s+\[human\]\s+/i;
+var INLINE_START_RE = /^-\s+\[\s*\]\s+\[start\]\s+/i;
+var BACKTICK_RE = /`([^`]+)`/;
+var HEADING_MARKS_RE = /^#+/;
+var FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
+var NESTED_LIST_ITEM_RE = /^\s+(?:[-*+]|\d+[.)])\s/;
+var PLAN_FILE_RE = /^PLAN-(.+)\.md$/;
+function inferSectionTag(header) {
+  if (SECTION_AUTO_RE.test(header))
+    return "auto";
+  if (SECTION_START_RE.test(header))
+    return "start";
+  if (SECTION_HUMAN_RE.test(header))
+    return "human";
+  return null;
+}
+function enterHeading(scope, header) {
+  const level = HEADING_MARKS_RE.exec(header)?.[0].length ?? 1;
+  const above = Array.from({ length: level - 1 }, (_, index) => scope[index] ?? null);
+  return [...above, inferSectionTag(header)];
+}
+function sectionDefault(scope) {
+  for (let index = scope.length - 1;index >= 0; index -= 1) {
+    const tag = scope[index];
+    if (tag)
+      return tag;
+  }
+  return "human";
+}
+function fenceOf(line) {
+  return FENCE_RE.exec(line)?.[1] ?? null;
+}
+function closesFence(opened, marker) {
+  return marker !== null && marker[0] === opened[0] && marker.length >= opened.length;
+}
+function isContinuation(line) {
+  return /^\s/.test(line) && line.trim() !== "" && !NESTED_LIST_ITEM_RE.test(line) && fenceOf(line) === null;
+}
+function continuationOf(lines, start) {
+  const following = [];
+  for (let index = start;index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    if (!isContinuation(line))
+      break;
+    following.push(line.trim());
+  }
+  return following;
+}
+function inlineTag(line) {
+  if (INLINE_AUTO_RE.test(line))
+    return "auto";
+  if (INLINE_START_RE.test(line))
+    return "start";
+  if (INLINE_HUMAN_RE.test(line))
+    return "human";
+  return null;
+}
+function stripItemPrefix(line) {
+  return line.replace(INLINE_AUTO_RE, "").replace(INLINE_HUMAN_RE, "").replace(INLINE_START_RE, "").replace(ITEM_RE, "").trim();
+}
+function isProbedTag(tag) {
+  return tag === "auto" || tag === "start";
+}
+function extractProbe(description) {
+  const probe = BACKTICK_RE.exec(description)?.[1]?.trim();
+  return probe || null;
+}
+function readItem(lines, lineIndex, inherited) {
+  const raw = lines[lineIndex] ?? "";
+  const tag = inlineTag(raw) ?? inherited;
+  const description = [stripItemPrefix(raw), ...continuationOf(lines, lineIndex + 1)].join(" ");
+  const probe = isProbedTag(tag) ? extractProbe(description) : null;
+  return Object.freeze({ raw, description, tag, lineIndex, probe });
+}
+function parsePrerequisites(content) {
+  const lines = content.split(`
+`);
+  const items = [];
+  let scope = [];
+  let fence = null;
+  for (let index = 0;index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    const marker = fenceOf(line);
+    if (fence !== null) {
+      if (closesFence(fence, marker))
+        fence = null;
+      continue;
+    }
+    if (marker !== null) {
+      fence = marker;
+      continue;
+    }
+    if (line.startsWith("#")) {
+      scope = enterHeading(scope, line);
+      continue;
+    }
+    if (ITEM_RE.test(line))
+      items.push(readItem(lines, index, sectionDefault(scope)));
+  }
+  return Object.freeze(items);
+}
+function isProbed(item) {
+  return isProbedTag(item.tag) && item.probe !== null;
+}
+function requiredItem(item) {
+  return Object.freeze({ kind: "tool", name: item.description, probe: item.probe });
+}
+function requiredItemsTagged(items, tag) {
+  const probed = items.filter(isProbed).filter((item) => item.tag === tag);
+  return Object.freeze(probed.map(requiredItem));
+}
+function reminderOf(item) {
+  return Object.freeze({ description: item.description, tag: item.tag, line: item.lineIndex + 1 });
+}
+function planPrerequisites(content) {
+  const items = parsePrerequisites(content);
+  return Object.freeze({
+    required: requiredItemsTagged(items, "auto"),
+    startRequired: requiredItemsTagged(items, "start"),
+    reminders: Object.freeze(items.filter((item) => !isProbed(item)).map(reminderOf))
+  });
+}
+function mergePlanPrerequisites(settings, content) {
+  const plan = planPrerequisites(content ?? "");
+  return Object.freeze({
+    required: Object.freeze([...settings.prerequisitesRequired, ...plan.required]),
+    startRequired: plan.startRequired,
+    optional: Object.freeze([...settings.prerequisitesOptional]),
+    reminders: plan.reminders
+  });
+}
+function prerequisitesPathForPlan(planPath) {
+  const stub = PLAN_FILE_RE.exec(basename(planPath))?.[1];
+  if (stub === undefined)
+    return null;
+  return join(dirname(planPath), `PREREQUISITES-${stub}.md`);
+}
+async function readIfPresent(path) {
+  try {
+    return await Bun.file(path).text();
+  } catch (error) {
+    const isAbsent = typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+    if (isAbsent)
+      return null;
+    throw new Error(`${path}: cannot be read (${messageOf(error)})`, { cause: error });
+  }
+}
+async function loadPlanPrerequisites(planPath, settings) {
+  const path = prerequisitesPathForPlan(planPath);
+  const content = path === null ? null : await readIfPresent(path);
+  return mergePlanPrerequisites(settings, content);
+}
+// src/preflight/run.ts
+var PROBE_TIMEOUT_MS = 30000;
+var SHELL = "/bin/sh";
+var PASS = Object.freeze({ outcome: "pass", failure: null });
+function spawnShell(probe, options) {
+  return Bun.spawn([SHELL, "-c", probe], {
+    cwd: options.cwd,
+    env: { ...options.env },
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "pipe",
+    detached: true
+  });
+}
+function isNoSuchProcess(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ESRCH";
+}
+function killGroup(proc) {
+  try {
+    process.kill(-proc.pid, "SIGKILL");
+  } catch (error) {
+    if (!isNoSuchProcess(error))
+      proc.kill("SIGKILL");
+  }
+}
+function collect(stream) {
+  const reader = stream.getReader();
+  const read = async () => {
+    const chunks = [];
+    let next = await reader.read();
+    while (!next.done) {
+      chunks.push(next.value);
+      next = await reader.read();
+    }
+    return Buffer.concat(chunks).toString("utf8");
+  };
+  const stop = () => {
+    reader.cancel().catch(() => {
+      return;
+    });
+  };
+  return { text: read(), stop };
+}
+async function runShellProbe(probe, options) {
+  let proc;
+  try {
+    proc = spawnShell(probe, options);
+  } catch (error) {
+    const stderr2 = `could not run ${SHELL} in ${options.cwd}: ${messageOf(error)}`;
+    return Object.freeze({ exitCode: null, stderr: stderr2, timedOut: false });
+  }
+  const stderr = collect(proc.stderr);
+  let timedOut = false;
+  const deadline = setTimeout(() => {
+    timedOut = proc.exitCode === null && proc.signalCode === null;
+    killGroup(proc);
+    stderr.stop();
+  }, options.timeoutMs);
+  try {
+    const exitCode = await proc.exited;
+    const text = await stderr.text;
+    return Object.freeze({ exitCode, stderr: text, timedOut });
+  } finally {
+    clearTimeout(deadline);
+  }
+}
+function secondsOf(timeoutMs) {
+  return `${timeoutMs / 1000}s`;
+}
+function firstLineOf(stderr) {
+  const line = stderr.split(`
+`).map((part) => part.trim()).find((part) => part !== "");
+  return line ?? null;
+}
+function endingOf(run, timeoutMs) {
+  if (run.timedOut)
+    return `timed out after ${secondsOf(timeoutMs)} and was killed (exit ${run.exitCode})`;
+  if (run.exitCode === null)
+    return "could not be run";
+  return `exited ${run.exitCode}`;
+}
+function probeVerdict(probe, run, timeoutMs) {
+  if (run.exitCode === 0 && !run.timedOut)
+    return PASS;
+  const line = firstLineOf(run.stderr);
+  const stated = `probe \`${probe}\` ${endingOf(run, timeoutMs)}`;
+  const failure = line === null ? stated : `${stated}: ${line}`;
+  const outcome = run.timedOut ? "timeout" : "fail";
+  return Object.freeze({ outcome, failure });
+}
+function missing(outcome, what) {
+  return Object.freeze({ outcome, failure: `presence check: ${what}` });
+}
+function onPath(command, context) {
+  const found = Bun.which(command, { PATH: context.env.PATH ?? "", cwd: context.cwd });
+  return found === null ? missing("fail", `${command} is not on PATH`) : PASS;
+}
+function envSet(name, context) {
+  const value = context.env[name];
+  if (value === undefined)
+    return missing("fail", `${name} is not set`);
+  if (value === "")
+    return missing("fail", `${name} is set but empty`);
+  return PASS;
+}
+async function serviceAnswers(url, context) {
+  const controller = new AbortController;
+  const deadline = setTimeout(() => {
+    controller.abort();
+  }, context.timeoutMs);
+  try {
+    await context.request(url, { method: "HEAD", redirect: "manual", signal: controller.signal });
+    return PASS;
+  } catch (error) {
+    if (controller.signal.aborted) {
+      return missing("timeout", `${url} did not answer within ${secondsOf(context.timeoutMs)}`);
+    }
+    return missing("fail", `${url} did not answer: ${messageOf(error)}`);
+  } finally {
+    clearTimeout(deadline);
+  }
+}
+async function presenceVerdict(item, context) {
+  switch (item.kind) {
+    case "tool":
+      return onPath(item.name, context);
+    case "env":
+      return envSet(item.name, context);
+    case "service":
+      return serviceAnswers(item.name, context);
+    case "lsp":
+      return onPath(`${item.name}-language-server`, context);
+  }
+}
+async function checkItem(tier, item, context) {
+  const started = context.now();
+  const verdict = item.probe === null ? await presenceVerdict(item, context) : probeVerdict(item.probe, await context.runProbe(item.probe, context), context.timeoutMs);
+  const durationMs = Math.max(0, Math.round(context.now() - started));
+  return Object.freeze({ tier, item, outcome: verdict.outcome, durationMs, failure: verdict.failure });
+}
+function labelOf(item) {
+  return `${item.kind} ${JSON.stringify(item.name)}`;
+}
+function oneLine(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+function knownMissingLine(item) {
+  const reason = item.reason === null ? "" : ` (${oneLine(item.reason)})`;
+  return `known-missing: ${oneLine(item.name)}${reason}`;
+}
+function warningOf(check) {
+  return `preflight: optional item ${labelOf(check.item)} failed: ${check.failure}; ` + "the run goes on, and each task prompt names it known-missing";
+}
+function haltOf(failed) {
+  if (failed.length === 0)
+    return null;
+  const noun = failed.length === 1 ? "item" : "items";
+  const lines = failed.map((check) => `  ${labelOf(check.item)}: ${check.failure}`);
+  return [`preflight halted: ${failed.length} required ${noun} failed`, ...lines].join(`
+`);
+}
+function warnThroughActiveOutput(message) {
+  activeOutput().warn(message);
+}
+function contextOf(options) {
+  return {
+    cwd: options.cwd,
+    env: options.env ?? process.env,
+    timeoutMs: options.timeoutMs ?? PROBE_TIMEOUT_MS,
+    runProbe: options.runProbe ?? runShellProbe,
+    request: options.request ?? ((url, init) => fetch(url, init)),
+    warn: options.warn ?? warnThroughActiveOutput,
+    now: options.now ?? (() => performance.now())
+  };
+}
+async function runPreflight(items, options) {
+  const context = contextOf(options);
+  const checks = [];
+  const knownMissing = [];
+  for (const item of items.required) {
+    checks.push(await checkItem("required", item, context));
+  }
+  for (const item of items.optional) {
+    const check = await checkItem("optional", item, context);
+    checks.push(check);
+    if (check.outcome === "pass")
+      continue;
+    context.warn(warningOf(check));
+    knownMissing.push(knownMissingLine(item));
+  }
+  const failed = checks.filter((check) => check.tier === "required" && check.outcome !== "pass");
+  return Object.freeze({
+    checks: Object.freeze(checks),
+    halt: haltOf(failed),
+    knownMissing: Object.freeze(knownMissing)
+  });
+}
+// src/report/parse.ts
+var REPORT_STATUSES = ["done", "blocked"];
+var FINDING_KINDS = ["gotcha", "pattern", "location", "skill-suggestion"];
+var FINDING_SIGNALS = ["loud", "silent"];
+var CHANGE_LEVELS = ["patch", "minor", "major", "none"];
+var REPORT_KIND = "report";
+var REQUIRED = true;
+var OPTIONAL = false;
+var REPORT_KEYS = [
+  "status",
+  "feedback",
+  "findings",
+  "skills_used",
+  "blockers",
+  "out_of_scope_bugs",
+  "changes"
+];
+var FINDING_KEYS = ["trigger", "kind", "what", "cause", "resolution", "artifact", "signal"];
+var BLOCKER_KEYS = ["what", "artifact"];
+var BUG_KEYS = ["what", "artifact", "security"];
+var CHANGE_KEYS = ["level", "area", "summary"];
+function isMapping(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isOneOf(choices, value) {
+  return choices.includes(value);
+}
+function describeValue(value) {
+  if (typeof value === "string")
+    return JSON.stringify(value);
+  if (value === null)
+    return "nothing";
+  if (Array.isArray(value))
+    return "a list";
+  if (typeof value === "object")
+    return "a mapping";
+  return `the ${typeof value} ${String(value)}`;
+}
+function messageOf2(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function reportIssue(reason, field, text) {
+  return { reason, field, text };
+}
+function absent(reason, block, text) {
+  return { present: false, reason, block, text };
+}
+function scopeOf(mapping, keys, prefix, issues) {
+  const fields = new Map;
+  const extras = [];
+  for (const [key, value] of Object.entries(mapping)) {
+    if (keys.includes(key))
+      fields.set(key, value);
+    else
+      extras.push({ key, value });
+  }
+  return { fields, extras, prefix, issues };
+}
+function valueOf(scope, key, required) {
+  const value = scope.fields.get(key) ?? null;
+  if (value === null && required) {
+    const field = `${scope.prefix}${key}`;
+    scope.issues.push(reportIssue("missing-field", field, `${field} is missing`));
+  }
+  return value;
+}
+function unusable(scope, key, why) {
+  const field = `${scope.prefix}${key}`;
+  scope.issues.push(reportIssue("unusable-field", field, `${field} ${why}`));
+  return null;
+}
+function stringProblem(value) {
+  if (typeof value !== "string")
+    return `is ${describeValue(value)}, not a string; quote it`;
+  if (value.trim().length === 0)
+    return "is blank";
+  return null;
+}
+function stringField(scope, key, required) {
+  const value = valueOf(scope, key, required);
+  if (value === null)
+    return null;
+  const problem = stringProblem(value);
+  return problem === null ? value : unusable(scope, key, problem);
+}
+function choiceField(scope, key, choices, required) {
+  const value = valueOf(scope, key, required);
+  if (value === null || isOneOf(choices, value))
+    return value;
+  return unusable(scope, key, `is ${describeValue(value)}, not one of ${choices.join(", ")}`);
+}
+function booleanField(scope, key, required) {
+  const value = valueOf(scope, key, required);
+  if (value === null || typeof value === "boolean")
+    return value;
+  return unusable(scope, key, `is ${describeValue(value)}, not true or false; write it unquoted`);
+}
+function listField(scope, key, readEntry) {
+  const value = valueOf(scope, key, OPTIONAL);
+  if (value === null)
+    return [];
+  if (!Array.isArray(value)) {
+    unusable(scope, key, `is ${describeValue(value)}, not a list`);
+    return [];
+  }
+  const entries = [];
+  const items = value;
+  for (const [index, item] of items.entries()) {
+    const entry = readEntry(item, `${scope.prefix}${key}[${index}]`, scope.issues);
+    if (entry !== null)
+      entries.push(entry);
+  }
+  return entries;
+}
+function entryScope(item, field, keys, issues) {
+  if (isMapping(item))
+    return scopeOf(item, keys, `${field}.`, issues);
+  const text = `${field} is ${describeValue(item)}, not a mapping of ${keys.join(", ")}; dropped`;
+  issues.push(reportIssue("unusable-field", field, text));
+  return null;
+}
+function readSkill(item, field, issues) {
+  const problem = stringProblem(item);
+  if (problem === null)
+    return item;
+  issues.push(reportIssue("unusable-field", field, `${field} ${problem}; dropped`));
+  return null;
+}
+function readFinding(item, field, issues) {
+  const scope = entryScope(item, field, FINDING_KEYS, issues);
+  if (scope === null)
+    return null;
+  return {
+    trigger: stringField(scope, "trigger", REQUIRED),
+    kind: choiceField(scope, "kind", FINDING_KINDS, REQUIRED),
+    what: stringField(scope, "what", REQUIRED),
+    cause: stringField(scope, "cause", OPTIONAL),
+    resolution: stringField(scope, "resolution", OPTIONAL),
+    artifact: stringField(scope, "artifact", OPTIONAL),
+    signal: choiceField(scope, "signal", FINDING_SIGNALS, REQUIRED),
+    extras: scope.extras
+  };
+}
+function readBlocker(item, field, issues) {
+  const scope = entryScope(item, field, BLOCKER_KEYS, issues);
+  if (scope === null)
+    return null;
+  return {
+    what: stringField(scope, "what", REQUIRED),
+    artifact: stringField(scope, "artifact", OPTIONAL),
+    extras: scope.extras
+  };
+}
+function readBug(item, field, issues) {
+  const scope = entryScope(item, field, BUG_KEYS, issues);
+  if (scope === null)
+    return null;
+  return {
+    what: stringField(scope, "what", REQUIRED),
+    artifact: stringField(scope, "artifact", OPTIONAL),
+    security: booleanField(scope, "security", REQUIRED),
+    extras: scope.extras
+  };
+}
+function readChange(item, field, issues) {
+  const scope = entryScope(item, field, CHANGE_KEYS, issues);
+  if (scope === null)
+    return null;
+  return {
+    level: choiceField(scope, "level", CHANGE_LEVELS, REQUIRED),
+    area: stringField(scope, "area", OPTIONAL),
+    summary: stringField(scope, "summary", REQUIRED),
+    extras: scope.extras
+  };
+}
+function readReport(document, issues) {
+  const scope = scopeOf(document, REPORT_KEYS, "", issues);
+  return {
+    status: choiceField(scope, "status", REPORT_STATUSES, REQUIRED),
+    feedback: stringField(scope, "feedback", OPTIONAL),
+    findings: listField(scope, "findings", readFinding),
+    skillsUsed: listField(scope, "skills_used", readSkill),
+    blockers: listField(scope, "blockers", readBlocker),
+    outOfScopeBugs: listField(scope, "out_of_scope_bugs", readBug),
+    changes: listField(scope, "changes", readChange),
+    extras: scope.extras
+  };
+}
+function parseReport(output) {
+  const reports = readRafaBlocks(output).filter((block2) => block2.kind === REPORT_KIND);
+  const block = reports.at(-1);
+  if (block === undefined) {
+    return absent("no-block", null, "the session output holds no rafa:report block");
+  }
+  const line = block.span.first;
+  if (!block.closed) {
+    return absent("unclosed-block", block, `rafa:report block at line ${line} is never closed, so its body may have been cut short ` + "and is not read");
+  }
+  let document;
+  try {
+    document = Bun.YAML.parse(block.body);
+  } catch (error) {
+    const text = `rafa:report block at line ${line} is not valid YAML (${messageOf2(error)})`;
+    return absent("malformed-block", block, text);
+  }
+  if (!isMapping(document)) {
+    const text = `rafa:report block at line ${line} holds ${describeValue(document)}, ` + "not a mapping of report fields";
+    return absent("malformed-block", block, text);
+  }
+  const issues = [];
+  const report = readReport(document, issues);
+  return { present: true, report, block, issues };
+}
+// src/utils/plan-stamp.ts
+var STUB_PATTERN = "[A-Za-z0-9._-]+";
+var STAMP_PATTERN = new RegExp(`<!--\\s*ralph:plan=(${STUB_PATTERN})\\s*-->`);
+function isStampableStub(stub) {
+  return new RegExp(`^${STUB_PATTERN}$`).test(stub);
+}
+function planStampLine(stub) {
+  if (!isStampableStub(stub)) {
+    throw new Error(`rafa plan stamp: unusable stub ${JSON.stringify(stub)}`);
+  }
+  return `<!-- ralph:plan=${stub} -->`;
+}
+function planStubFromPrompt(content) {
+  if (typeof content !== "string" || content.length === 0)
+    return null;
+  const match = STAMP_PATTERN.exec(content);
+  const stub = match?.[1];
+  return stub !== undefined && isStampableStub(stub) ? stub : null;
+}
+function stampPrompt(stub, prompt) {
+  return `${prompt}
+${planStampLine(stub)}`;
+}
+function planStubFromPath(planPath) {
+  const base = planPath.split("/").pop() ?? planPath;
+  const match = /^PLAN(?:_TRACKER)?-(.+)\.md$/.exec(base);
+  const stub = match?.[1];
+  return stub !== undefined && isStampableStub(stub) ? stub : null;
+}
+
+// src/utils/tracker.ts
+import fs from "fs";
+var BLOCKER_OPEN = "<!-- blocked: ";
+var BLOCKER_CLOSE = " -->";
+var BLOCKER_GAP = "  ";
+var BLOCKER_COMMENT = /\s<!-- blocked: ((?:(?!<!--|-->).)*) -->$/;
+var OPEN_TASK_PREFIX = /^- \[(?: |BLOCKED)\] /;
+var ESCAPE_SEQUENCE = /\\(u[0-9A-Fa-f]{4}|[\s\S])/g;
+var TAB = 9;
+var FIRST_PRINTABLE = 32;
+var ESCAPED_CODE_UNITS = [127, 8232, 8233];
+function isEscapedCodeUnit(code) {
+  if (code < FIRST_PRINTABLE)
+    return code !== TAB;
+  return ESCAPED_CODE_UNITS.includes(code);
+}
+function escapeCharacter(char) {
+  if (char === "\\")
+    return "\\\\";
+  if (char === `
+`)
+    return "\\n";
+  if (char === "\r")
+    return "\\r";
+  const code = char.charCodeAt(0);
+  return isEscapedCodeUnit(code) ? `\\u${code.toString(16).padStart(4, "0")}` : char;
+}
+function escapeBlockerText(text) {
+  return Array.from(text, escapeCharacter).join("").replace(/(?<=--!?)>/g, "\\>").replace(/(?<=<)!(?=--)/g, "\\!");
+}
+function unescapeBlockerText(escaped) {
+  return escaped.replace(ESCAPE_SEQUENCE, (_sequence, code) => {
+    if (code === "n")
+      return `
+`;
+    if (code === "r")
+      return "\r";
+    return code.length === 5 ? String.fromCharCode(Number.parseInt(code.slice(1), 16)) : code;
+  });
+}
+function blockerComment(blocker) {
+  return `${BLOCKER_OPEN}${escapeBlockerText(blocker)}${BLOCKER_CLOSE}`;
+}
+function findBlockerComment(text) {
+  const trimmed = text.trimEnd();
+  const match = BLOCKER_COMMENT.exec(trimmed);
+  const escaped = match?.[1];
+  if (match === null || escaped === undefined)
+    return null;
+  const before = trimmed.slice(0, match.index).trimEnd();
+  return before.length === 0 ? null : { before, escaped };
+}
+function splitBlockerComment(taskText) {
+  const found = findBlockerComment(taskText);
+  if (found === null)
+    return { text: taskText, blocker: null };
+  const blocker = unescapeBlockerText(found.escaped);
+  return {
+    text: found.before,
+    blocker: blocker.trim().length === 0 ? null : blocker
+  };
+}
+function splitCarriageReturn(line) {
+  return line.endsWith("\r") ? { body: line.slice(0, -1), cr: "\r" } : { body: line, cr: "" };
+}
+function withoutBlockerComment(line) {
+  const { body, cr } = splitCarriageReturn(line);
+  const prefix = OPEN_TASK_PREFIX.exec(body)?.[0];
+  if (prefix === undefined)
+    return line;
+  const found = findBlockerComment(body.slice(prefix.length));
+  return found === null ? line : `${prefix}${found.before}${cr}`;
+}
+function closedBlockLines(trackerContent) {
+  const inside = new Set;
+  for (const block of readRafaBlocks(trackerContent)) {
+    if (!block.closed)
+      continue;
+    for (let line = block.span.first;line <= block.span.last; line += 1) {
+      inside.add(line - 1);
+    }
+  }
+  return inside;
+}
+function taskInfoOf(capture, lineNum, status) {
+  const { text, blocker } = splitBlockerComment(capture.trim());
+  return blocker === null ? { task: text, lineNum, status } : { task: text, lineNum, status, blocker };
+}
+function findNextTask(trackerContent) {
+  const lines = trackerContent.split(`
+`);
+  const inBlock = closedBlockLines(trackerContent);
+  for (let i = 0;i < lines.length; i++) {
+    if (inBlock.has(i))
+      continue;
+    const match = lines[i].match(/^- \[BLOCKED\] (.+)/);
+    if (match?.[1])
+      return taskInfoOf(match[1], i, "blocked");
+  }
+  for (let i = 0;i < lines.length; i++) {
+    if (inBlock.has(i))
+      continue;
+    const match = lines[i].match(/^- \[ \] (.+)/);
+    if (match?.[1])
+      return taskInfoOf(match[1], i, "unchecked");
+  }
+  return null;
+}
+function updateTrackerLine(trackerPath, lineNum, newStatus) {
+  const lines = fs.readFileSync(trackerPath, "utf8").split(`
+`);
+  const line = lines[lineNum];
+  if (!line)
+    return;
+  if (newStatus === "done") {
+    lines[lineNum] = withoutBlockerComment(line).replace(/^- \[ \]/, "- [x]").replace(/^- \[BLOCKED\]/, "- [x]");
+  } else {
+    lines[lineNum] = line.replace(/^- \[ \]/, "- [BLOCKED]");
+  }
+  fs.writeFileSync(trackerPath, lines.join(`
+`), "utf8");
+}
+function writeTrackerBlocker(trackerPath, lineNum, blocker) {
+  const lines = fs.readFileSync(trackerPath, "utf8").split(`
+`);
+  const line = lines[lineNum];
+  if (line === undefined)
+    return false;
+  const { body, cr } = splitCarriageReturn(line);
+  const prefix = OPEN_TASK_PREFIX.exec(body)?.[0];
+  if (prefix === undefined)
+    return false;
+  const rest = body.slice(prefix.length);
+  const text = (findBlockerComment(rest)?.before ?? rest).trimEnd();
+  if (text.trim().length === 0)
+    return false;
+  const comment = blocker.trim().length === 0 ? "" : `${BLOCKER_GAP}${blockerComment(blocker)}`;
+  lines[lineNum] = `- [BLOCKED] ${text}${comment}${cr}`;
+  fs.writeFileSync(trackerPath, lines.join(`
+`), "utf8");
+  return true;
+}
+function trackerPathFor(planPath) {
+  return planPath.replace(/PLAN(-[^/]*)?\.md$/, (_m, stub) => `PLAN_TRACKER${stub ?? ""}.md`);
+}
+
+// src/plan/parse.ts
+var PLAN_BLOCK_KINDS = ["plan", "context", "stage-context"];
+var PLAN_HEADER_FIELDS = ["stub", "issue", "spec", "release"];
+var PLAN_RELEASE_LEVELS = ["patch", "minor", "major", "none"];
+var TASK_LINES = [
+  ["unchecked", /^- \[ \] (.+)/],
+  ["blocked", /^- \[BLOCKED\] (.+)/],
+  ["done", /^- \[x\] (.+)/]
+];
+var STAGE_HEADING = /^# Stage: (.+)/;
+function isPlanBlockKind(kind) {
+  return PLAN_BLOCK_KINDS.includes(kind);
+}
+function isHeaderField(key) {
+  return PLAN_HEADER_FIELDS.includes(key);
+}
+function isReleaseLevel(value) {
+  return PLAN_RELEASE_LEVELS.includes(value);
+}
+function isMapping2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describeValue2(value) {
+  if (typeof value === "string")
+    return JSON.stringify(value);
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "a list";
+  if (typeof value === "object")
+    return "a mapping";
+  return String(value);
+}
+function messageOf3(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function planIssue(reason, line, text) {
+  return { reason, line, text };
+}
+function emptyHeader() {
+  return { stub: null, issue: null, spec: null, release: null, extras: [] };
+}
+function readTaskLine(line) {
+  for (const [status, pattern] of TASK_LINES) {
+    const capture = pattern.exec(line)?.[1];
+    if (capture !== undefined)
+      return { status, task: splitBlockerComment(capture.trim()).text };
+  }
+  return null;
+}
+function readStageHeading(line) {
+  const capture = STAGE_HEADING.exec(line)?.[1];
+  return capture === undefined ? null : capture.trim();
+}
+function blockAt(blocks, lineNum) {
+  const line = lineNum + 1;
+  return blocks.find((block) => block.span.first <= line && line <= block.span.last);
+}
+function taskInBlock(lineNum, status, block) {
+  const { first, last } = block.span;
+  const dispatcher = block.closed ? "findNextTask skips it" : "findNextTask still dispatches it, the block never being closed";
+  return planIssue("task-in-block", lineNum + 1, `${status} task line inside the rafa:${block.kind} block at lines ${first}-${last}: ` + `${dispatcher}, and the model reads it as block body`);
+}
+function planTask(line, lineNum, headings) {
+  const { text, declaration } = parseTaskDeclaration(line.task);
+  const stage = headings.length > 0 ? headings.length - 1 : null;
+  return { task: line.task, lineNum, status: line.status, text, declaration, stage };
+}
+function readChecklist(markdown, blocks) {
+  const headings = [];
+  const tasks = [];
+  const hidden = [];
+  const issues = [];
+  for (const [lineNum, line] of markdown.split(`
+`).entries()) {
+    const taskLine = readTaskLine(line);
+    const block = blockAt(blocks, lineNum);
+    if (block !== undefined) {
+      if (taskLine !== null && taskLine.status !== "done") {
+        issues.push(taskInBlock(lineNum, taskLine.status, block));
+        if (!block.closed)
+          hidden.push(planTask(taskLine, lineNum, headings));
+      }
+      continue;
+    }
+    const name = readStageHeading(line);
+    if (name !== null) {
+      headings.push({ name, lineNum });
+      continue;
+    }
+    if (taskLine === null)
+      continue;
+    tasks.push(planTask(taskLine, lineNum, headings));
+  }
+  return { headings, tasks, hidden, issues };
+}
+function headingAbove(headings, lineNum) {
+  let above = null;
+  for (const [index, heading] of headings.entries()) {
+    if (heading.lineNum >= lineNum)
+      break;
+    above = index;
+  }
+  return above;
+}
+function stageSlot(index) {
+  return `stage-context@${index}`;
+}
+function slotOf(block, headings) {
+  if (block.kind !== "stage-context")
+    return { key: block.kind, scope: "" };
+  const index = headingAbove(headings, block.span.first - 1);
+  if (index === null)
+    return null;
+  const name = headings[index]?.name ?? "";
+  return { key: stageSlot(index), scope: ` under # Stage: ${name}` };
+}
+function bindBlocks(blocks, headings) {
+  const read = new Map;
+  const issues = [];
+  for (const block of blocks) {
+    const line = block.span.first;
+    if (!block.closed) {
+      issues.push(planIssue("unclosed-block", line, `rafa:${block.kind} block is never closed, so it runs to the end of the document ` + "and nothing after its fence is read"));
+      continue;
+    }
+    if (!isPlanBlockKind(block.kind))
+      continue;
+    const slot = slotOf(block, headings);
+    if (slot === null) {
+      issues.push(planIssue("orphan-stage-context", line, "rafa:stage-context block above every # Stage: heading belongs to no stage and is not read"));
+      continue;
+    }
+    const earlier = read.get(slot.key);
+    if (earlier === undefined) {
+      read.set(slot.key, block);
+      continue;
+    }
+    issues.push(planIssue("duplicate-block", line, `rafa:${block.kind} block${slot.scope} repeats the one at line ${earlier.span.first}, ` + "which is the one read"));
+  }
+  return {
+    header: read.get("plan") ?? null,
+    context: read.get("context") ?? null,
+    stageContexts: headings.map((_, index) => read.get(stageSlot(index))?.body ?? null),
+    issues
+  };
+}
+function usableField(field, value) {
+  if (field === "issue" && typeof value === "number") {
+    return Number.isSafeInteger(value) ? String(value) : null;
+  }
+  if (typeof value !== "string" || value.trim().length === 0)
+    return null;
+  if (field === "stub" && !isStampableStub(value))
+    return null;
+  if (field === "release" && !isReleaseLevel(value))
+    return null;
+  return value;
+}
+function unusableText(field, value) {
+  const subject = `rafa:plan ${field}`;
+  if (value === null) {
+    return `${subject} is empty; a value opening with # after a space is a YAML comment unless quoted`;
+  }
+  if (field === "release") {
+    return `${subject} is ${describeValue2(value)}, not one of ${PLAN_RELEASE_LEVELS.join(", ")}`;
+  }
+  if (typeof value !== "string") {
+    return field === "issue" ? `${subject} is ${describeValue2(value)}, not a string or a whole number; quote it` : `${subject} is ${describeValue2(value)}, not a string; quote it`;
+  }
+  if (value.trim().length === 0)
+    return `${subject} is blank`;
+  return `${subject} ${JSON.stringify(value)} is no stub a plan stamp can carry ` + '(letters, digits, ".", "_" and "-")';
+}
+function releaseOf(values) {
+  const value = values.get("release");
+  if (value === undefined || !isReleaseLevel(value))
+    return null;
+  return value;
+}
+function readFields(document, line) {
+  const values = new Map;
+  const extras = [];
+  const issues = [];
+  for (const [key, value] of Object.entries(document)) {
+    if (!isHeaderField(key)) {
+      extras.push({ key, value });
+      continue;
+    }
+    const usable = usableField(key, value);
+    if (usable === null)
+      issues.push(planIssue("unusable-field", line, unusableText(key, value)));
+    else
+      values.set(key, usable);
+  }
+  const header = {
+    stub: values.get("stub") ?? null,
+    issue: values.get("issue") ?? null,
+    spec: values.get("spec") ?? null,
+    release: releaseOf(values),
+    extras
+  };
+  return { header, issues };
+}
+function readHeader(block) {
+  if (block === null)
+    return { header: emptyHeader(), issues: [] };
+  const line = block.span.first;
+  let document;
+  try {
+    document = Bun.YAML.parse(block.body);
+  } catch (error) {
+    const text = `rafa:plan block is not valid YAML (${messageOf3(error)})`;
+    return { header: emptyHeader(), issues: [planIssue("malformed-header", line, text)] };
+  }
+  if (document === null)
+    return { header: emptyHeader(), issues: [] };
+  if (!isMapping2(document)) {
+    const text = `rafa:plan block holds ${describeValue2(document)}, not a mapping of fields`;
+    return { header: emptyHeader(), issues: [planIssue("malformed-header", line, text)] };
+  }
+  return readFields(document, line);
+}
+function parsePlan(markdown) {
+  const blocks = readRafaBlocks(markdown);
+  const checklist = readChecklist(markdown, blocks);
+  const bound = bindBlocks(blocks, checklist.headings);
+  const reading = readHeader(bound.header);
+  const stages = checklist.headings.map((heading, index) => ({
+    name: heading.name,
+    lineNum: heading.lineNum,
+    context: bound.stageContexts[index] ?? null
+  }));
+  const issues = [...checklist.issues, ...bound.issues, ...reading.issues].sort((a, b) => a.line - b.line);
+  return {
+    header: reading.header,
+    context: bound.context?.body ?? null,
+    stages,
+    tasks: checklist.tasks,
+    hiddenTasks: checklist.hidden,
+    blocks,
+    issues
+  };
+}
+
+// src/plan/inject.ts
+var PLAN_CONTEXT_HEADING = "## Plan context";
+var STAGE_HEADING_PREFIX = "## Stage: ";
+var CHECKLIST_HEADING = "## Checklist";
+var STAGE_LIST_HEADING = "## Stages";
+var CURRENT_STAGE_MARK = " (current stage)";
+var CHECKBOXES = {
+  unchecked: "- [ ]",
+  blocked: "- [BLOCKED]",
+  done: "- [x]"
+};
+function fallbackFor(reason, lineNum) {
+  const line = lineNum + 1;
+  const found = reason === "no-task-at-line" ? "no task the plan model reads" : "a different task than the one dispatched";
+  const text = `line ${line} of the plan holds ${found}, so the whole plan is handed over; ` + "the plan may have changed since its tracker was copied, or the line sits inside a rafa:* block";
+  return { found: false, fallback: { reason, line, text } };
+}
+function locate(model, wanted) {
+  const task = model.tasks.find((candidate) => candidate.lineNum === wanted.lineNum);
+  if (task === undefined)
+    return fallbackFor("no-task-at-line", wanted.lineNum);
+  if (task.task !== wanted.task)
+    return fallbackFor("task-text-differs", wanted.lineNum);
+  return { found: true, task };
+}
+function contextBody(body) {
+  if (body === null || body.trim().length === 0)
+    return null;
+  return body.replace(/^(?:[ \t]*\n)+/, "").replace(/(?:\n[ \t]*)+$/, "");
+}
+function section(heading, ...parts) {
+  return [heading, ...parts].filter((part) => part !== null).join(`
+
+`);
+}
+function renderDocument(sections) {
+  const present = sections.filter((part) => part !== null);
+  return `${present.join(`
+
+`)}
+`;
+}
+function shownStatus(task, dispatched) {
+  if (task.lineNum < dispatched.lineNum)
+    return "done";
+  if (task.lineNum === dispatched.lineNum)
+    return "unchecked";
+  return task.status;
+}
+function taskLine(status, task) {
+  return `${CHECKBOXES[status]} ${task.text}`;
+}
+function planContextSection(model) {
+  const body = contextBody(model.context);
+  return body === null ? null : section(PLAN_CONTEXT_HEADING, body);
+}
+function stageSection(model, dispatched, lines) {
+  const owner = dispatched.stage === null ? undefined : model.stages[dispatched.stage];
+  if (owner === undefined)
+    return section(CHECKLIST_HEADING, lines.join(`
+`));
+  return section(`${STAGE_HEADING_PREFIX}${owner.name}`, contextBody(owner.context), lines.join(`
+`));
+}
+function stageListSection(model, dispatched) {
+  if (model.stages.length === 0)
+    return null;
+  const items = model.stages.map((stage, index) => {
+    const mark = index === dispatched.stage ? CURRENT_STAGE_MARK : "";
+    return `${index + 1}. ${stage.name}${mark}`;
+  });
+  return section(STAGE_LIST_HEADING, items.join(`
+`));
+}
+function renderStage(model, dispatched) {
+  const checklist = model.tasks.filter((task) => task.stage === dispatched.stage).map((task) => taskLine(shownStatus(task, dispatched), task));
+  return renderDocument([
+    planContextSection(model),
+    stageSection(model, dispatched, checklist),
+    stageListSection(model, dispatched)
+  ]);
+}
+function renderTask(model, dispatched) {
+  return renderDocument([
+    planContextSection(model),
+    stageSection(model, dispatched, [taskLine("unchecked", dispatched)])
+  ]);
+}
+var RENDERERS = {
+  stage: renderStage,
+  task: renderTask
+};
+function renderInjection(request) {
+  const { mode, plan, task } = request;
+  if (mode === "full")
+    return { requested: mode, mode, text: plan, fallback: null };
+  const model = parsePlan(plan);
+  const location = locate(model, task);
+  if (!location.found) {
+    return { requested: mode, mode: "full", text: plan, fallback: location.fallback };
+  }
+  return { requested: mode, mode, text: RENDERERS[mode](model, location.task), fallback: null };
+}
+export { isStampableStub, planStubFromPrompt, stampPrompt, planStubFromPath, REPORT_STATUSES, FINDING_KINDS, FINDING_SIGNALS, CHANGE_LEVELS, parseReport, escapeBlockerText, findNextTask, updateTrackerLine, writeTrackerBlocker, trackerPathFor, PLAN_BLOCK_KINDS, PLAN_HEADER_FIELDS, parsePlan, parsePrerequisites, planPrerequisites, mergePlanPrerequisites, prerequisitesPathForPlan, loadPlanPrerequisites, PROBE_TIMEOUT_MS, runShellProbe, runPreflight, renderInjection };