tldr-experts 0.3.0 → 0.4.0

package/dist/hooks/chunk-phmdk72a.js

@@ -0,0 +1,164 @@
+import {
+  isRecord
+} from "./chunk-39zh2e44.js";
+import {
+  parseYaml
+} from "./chunk-sq44k6g2.js";
+
+// src/core/schemas/planCommon.ts
+var STORY_ID_RE = /^S\d{1,4}$/;
+var WAVE_ID_RE = /^W\d{1,3}$/;
+var MAX_LIST_ITEMS = 64;
+var MAX_ITEM_CHARS = 512;
+var MAX_WAVES = 32;
+var MAX_STORIES_PER_WAVE = 32;
+var MAX_PLAN_STORIES = 200;
+function requireStringList(value, path, issues, rules = {}) {
+  if (value === undefined)
+    return [];
+  if (!Array.isArray(value)) {
+    issues.push({ path, message: `expected a list, got ${describe(value)}` });
+    return [];
+  }
+  const max = rules.max ?? MAX_LIST_ITEMS;
+  if (value.length > max) {
+    issues.push({ path, message: `${value.length} items exceeds the ${max}-item cap` });
+  }
+  if (rules.nonEmpty === true && value.length === 0) {
+    issues.push({ path, message: "must not be empty" });
+  }
+  const seen = new Set;
+  const out = [];
+  value.forEach((item, i) => {
+    const at = `${path}[${i}]`;
+    if (typeof item !== "string") {
+      issues.push({ path: at, message: `expected a string, got ${describe(item)}` });
+      return;
+    }
+    if (item.trim() === "") {
+      issues.push({ path: at, message: "must not be blank" });
+      return;
+    }
+    if (item.length > MAX_ITEM_CHARS) {
+      issues.push({
+        path: at,
+        message: `${item.length} characters exceeds the ${MAX_ITEM_CHARS}-character cap on one list item ` + "— split it into several items"
+      });
+    }
+    if (rules.pattern !== undefined && !rules.pattern.test(item)) {
+      issues.push({ path: at, message: `expected ${rules.patternName ?? String(rules.pattern)}, got \`${item}\`` });
+      return;
+    }
+    if (rules.unique === true && seen.has(item)) {
+      issues.push({ path: at, message: `\`${item}\` is listed twice` });
+      return;
+    }
+    seen.add(item);
+    out.push(item);
+  });
+  return out;
+}
+function requirePattern(value, pattern, patternName, path, issues) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string") {
+    issues.push({ path, message: `expected a string, got ${describe(value)}` });
+    return;
+  }
+  if (!pattern.test(value)) {
+    issues.push({ path, message: `expected ${patternName}, got \`${value}\`` });
+  }
+}
+function requireVersion1(doc, issues) {
+  if (doc.version !== undefined && doc.version !== 1) {
+    issues.push({ path: "version", message: `unknown schema version ${String(doc.version)} (expected 1)` });
+  }
+}
+function describe(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "a list";
+  if (isRecord(value))
+    return "a mapping";
+  return typeof value;
+}
+
+// src/core/schemas/frontMatter.ts
+var FENCE = "---";
+function splitFrontMatter(text) {
+  const lines = text.split(`
+`);
+  if ((lines[0] ?? "").trimEnd() !== FENCE) {
+    return { present: false, raw: "", body: text, bodyLine: 1 };
+  }
+  for (let i = 1;i < lines.length; i++) {
+    if ((lines[i] ?? "").trimEnd() !== FENCE)
+      continue;
+    return {
+      present: true,
+      raw: lines.slice(1, i).join(`
+`),
+      body: lines.slice(i + 1).join(`
+`),
+      bodyLine: i + 2
+    };
+  }
+  return { present: false, raw: "", body: text, bodyLine: 1 };
+}
+function parseFrontMatter(text) {
+  const frontMatter = splitFrontMatter(text);
+  if (!frontMatter.present) {
+    return {
+      frontMatter,
+      doc: null,
+      issue: {
+        path: "",
+        message: "no YAML front matter — the file must open with `---` and close the block with `---`"
+      }
+    };
+  }
+  try {
+    return { frontMatter, doc: parseYaml(frontMatter.raw), issue: null };
+  } catch (error) {
+    return {
+      frontMatter,
+      doc: null,
+      issue: { path: "", message: `front matter is not valid YAML: ${message(error)}` }
+    };
+  }
+}
+function message(error) {
+  return error instanceof Error ? error.message.split(`
+`)[0] ?? "parse error" : String(error);
+}
+// src/core/schemas/story.ts
+var DOD_FENCE_OPEN_RE = /^\s*```+\s*dod\s*$/i;
+var DOD_FENCE_CLOSE_RE = /^\s*```+\s*$/;
+var FENCE_OPEN_RE = DOD_FENCE_OPEN_RE;
+var FENCE_CLOSE_RE = DOD_FENCE_CLOSE_RE;
+function parseDodBlock(text) {
+  const commands = [];
+  let present = false;
+  let inside = false;
+  for (const line of text.split(`
+`)) {
+    if (inside) {
+      if (FENCE_CLOSE_RE.test(line)) {
+        inside = false;
+        continue;
+      }
+      const command = line.trim();
+      if (command !== "" && !command.startsWith("#"))
+        commands.push(command);
+      continue;
+    }
+    if (FENCE_OPEN_RE.test(line)) {
+      present = true;
+      inside = true;
+    }
+  }
+  return { present, commands };
+}
+
+export { STORY_ID_RE, WAVE_ID_RE, MAX_WAVES, MAX_STORIES_PER_WAVE, MAX_PLAN_STORIES, requireStringList, requirePattern, requireVersion1, parseFrontMatter, parseDodBlock };

package/dist/hooks/chunk-rpcxsqh3.js

@@ -0,0 +1,199 @@
+import {
+  parseSrcToken
+} from "./chunk-m3mewgnw.js";
+
+// src/core/text/questions.ts
+var REQUIRED_METADATA_KEYS = ["id", "status", "area", "asked_by", "asked_at"];
+var HEADING_RE = /^##\s+(Q\d{1,6})\s+·\s+(.+?)\s*$/;
+var METADATA_RE = /^<!--\s*(.*?)\s*-->$/;
+var WHY_RE = /^Why asked:\s*(.*)$/;
+var OPTION_RE = /^-\s+([A-E])\)\s*(.*)$/;
+var ANSWER_RE = /^\[Answer\]:[ \t]*(\S.*)$/;
+var ANSWER_SLOT_RE = /^\[Answer\]:/;
+var FOOTER_KEYS = ["answered_by", "answered_at", "fact"];
+function parseQuestions(text) {
+  const trailingNewline = text.endsWith(`
+`);
+  const body = trailingNewline ? text.slice(0, -1) : text;
+  const lines = body === "" ? [] : body.split(`
+`);
+  const preamble = [];
+  const blocks = [];
+  let pending = null;
+  const close = () => {
+    if (pending === null)
+      return;
+    blocks.push(buildBlock(pending.start + 1, pending.lines));
+    pending = null;
+  };
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    if (HEADING_RE.test(line)) {
+      close();
+      pending = { start: i, lines: [line] };
+      continue;
+    }
+    if (pending === null)
+      preamble.push(line);
+    else
+      pending.lines.push(line);
+  }
+  close();
+  return { preamble, blocks, trailingNewline };
+}
+function buildBlock(startLine, lines) {
+  const heading = HEADING_RE.exec(lines[0] ?? "");
+  const id = heading?.[1] ?? "";
+  const title = heading?.[2] ?? "";
+  let metadata = null;
+  let metadataIndex = -1;
+  let whyAsked = null;
+  let whySrc = null;
+  const options = [];
+  let answer = "";
+  let answerIndex = -1;
+  let footer = null;
+  for (let i = 1;i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const comment = METADATA_RE.exec(line);
+    if (comment !== null && comment[1] !== undefined) {
+      const pairs = parsePipeComment(comment[1]);
+      if (metadata === null && pairs.some(([k]) => k === "id")) {
+        metadata = toMetadata(pairs);
+        metadataIndex = i;
+      } else if (footer === null && pairs.some(([k]) => k === "answered_by")) {
+        footer = toFooter(pairs);
+      }
+      continue;
+    }
+    const why = WHY_RE.exec(line);
+    if (why !== null && whyAsked === null) {
+      whyAsked = why[1] ?? "";
+      whySrc = parseSrcToken(line);
+      continue;
+    }
+    const option = OPTION_RE.exec(line);
+    if (option !== null && option[1] !== undefined && option[2] !== undefined) {
+      options.push({ letter: option[1], text: option[2] });
+      continue;
+    }
+    if (ANSWER_SLOT_RE.test(line) && answerIndex === -1) {
+      answerIndex = i;
+      const captured = ANSWER_RE.exec(line);
+      answer = (captured?.[1] ?? "").trim();
+    }
+  }
+  return {
+    id,
+    title,
+    metadata,
+    metadataIndex,
+    whyAsked,
+    whySrc,
+    options,
+    answer,
+    answerIndex,
+    footer,
+    startLine,
+    lines: [...lines]
+  };
+}
+function parsePipeComment(inner) {
+  const pairs = [];
+  for (const part of inner.split("|")) {
+    const colon = part.indexOf(":");
+    if (colon === -1)
+      continue;
+    pairs.push([part.slice(0, colon).trim(), part.slice(colon + 1).trim()]);
+  }
+  return pairs;
+}
+function toMetadata(pairs) {
+  const map = new Map(pairs);
+  const extra = pairs.filter(([k]) => !REQUIRED_METADATA_KEYS.includes(k));
+  return {
+    id: map.get("id") ?? "",
+    status: map.get("status") ?? "",
+    area: map.get("area") ?? "",
+    asked_by: map.get("asked_by") ?? "",
+    asked_at: map.get("asked_at") ?? "",
+    extra
+  };
+}
+function toFooter(pairs) {
+  const map = new Map(pairs);
+  return {
+    answered_by: map.get("answered_by") ?? "",
+    answered_at: map.get("answered_at") ?? "",
+    fact: map.get("fact") ?? ""
+  };
+}
+function serializeQuestions(doc) {
+  const out = [...doc.preamble];
+  for (const block of doc.blocks)
+    out.push(...block.lines);
+  const text = out.join(`
+`);
+  return doc.trailingNewline ? `${text}
+` : text;
+}
+function detectAnswered(blocks) {
+  return blocks.filter((b) => b.metadata?.status === "open" && b.answer !== "");
+}
+function openBlocks(blocks) {
+  return blocks.filter((b) => b.metadata?.status === "open");
+}
+function recordAnswer(block, footer) {
+  const lines = [...block.lines];
+  if (block.metadataIndex >= 0) {
+    const line = lines[block.metadataIndex] ?? "";
+    lines[block.metadataIndex] = line.replace(/(\|\s*status:\s*)open(\s*\|)/, "$1answered$2");
+  }
+  const footerLine = `<!-- ${FOOTER_KEYS.map((k) => `${k}: ${footer[k]}`).join(" | ")} -->`;
+  const insertAt = block.answerIndex >= 0 ? block.answerIndex + 1 : lines.length;
+  lines.splice(insertAt, 0, footerLine);
+  const metadata = block.metadata === null ? null : { ...block.metadata, status: "answered" };
+  return { ...block, lines, metadata, footer };
+}
+function replaceBlock(doc, block) {
+  return {
+    ...doc,
+    blocks: doc.blocks.map((b) => b.id === block.id ? block : b)
+  };
+}
+
+// src/core/facts/Fact.ts
+var FACT_KINDS = ["answer", "observed", "derived"];
+var FACT_CONFIDENCES = ["measured", "inferred", "stated"];
+var MAX_FACTS = 5000;
+var MAX_FACT_CHARS = 2000;
+function isRetired(fact) {
+  return fact.retired !== null && fact.retired.at !== null;
+}
+function isSuperseded(fact) {
+  return fact.superseded_by !== null;
+}
+function isLive(fact) {
+  return !isRetired(fact) && !isSuperseded(fact);
+}
+function factNumber(id) {
+  return Number.parseInt(id.slice(1), 10);
+}
+function formatFactId(n) {
+  return `F${String(n).padStart(3, "0")}`;
+}
+
+// src/core/schemas/deprecationNotice.ts
+var said = new Set;
+function noteDeprecations(file, outcome) {
+  for (const note of outcome.deprecations ?? []) {
+    const line = `${file}: ${note}`;
+    if (said.has(line))
+      continue;
+    said.add(line);
+    process.stderr.write(`${line}
+`);
+  }
+}
+
+export { FACT_KINDS, FACT_CONFIDENCES, MAX_FACTS, MAX_FACT_CHARS, isRetired, isLive, factNumber, formatFactId, noteDeprecations, parseQuestions, serializeQuestions, detectAnswered, openBlocks, recordAnswer, replaceBlock };

package/dist/hooks/{chunk-azctppjh.js → chunk-rz541e2b.js}

@@ -5,7 +5,7 @@ import {
   requireNumber,
   requireString,
   result
-} from "./chunk-0bt6yb2q.js";
+} from "./chunk-39zh2e44.js";
 
 // src/core/events/EventLog.ts
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -17,6 +17,7 @@ var EVENT_TYPES = [
   "run.closed",
   "run.unlocked",
   "run.cancelled",
+  "run.attended",
   "phase.started",
   "phase.done",
   "stage.started",
@@ -33,6 +34,10 @@ var EVENT_TYPES = [
   "gate.approved",
   "gate.rejected",
   "gate.revoked",
+  "gate.policy_changed",
+  "story.reopened",
+  "story.base_fastforwarded",
+  "operator_note",
   "check.passed",
   "check.failed",
   "budget.warned",
@@ -40,6 +45,7 @@ var EVENT_TYPES = [
   "budget.raised",
   "fact.added",
   "fact.retired",
+  "fact.superseded",
   "map.refreshed",
   "ticket.synced",
   "error"

package/dist/hooks/{chunk-y0jdr3et.js → chunk-s1c5h7yx.js}

@@ -1,10 +1,14 @@
 import {
+  DEFAULT_ECONOMY,
+  DEFAULT_ON_HOST_TOKENS_EXCEED,
   asRunBudget,
   asRunFile,
   cursorStage,
   derivePhaseStatus,
   deriveRunStatus,
   flatten,
+  isAttendedByHost,
+  isAttendedByHostView,
   isFinished,
   isTerminal,
   nowRfc3339,
@@ -12,34 +16,37 @@ import {
   stageAt,
   validateRunBudget,
   validateRunFile
-} from "./chunk-sdjnnmzz.js";
+} from "./chunk-4cp363kv.js";
 import {
   EventLog
-} from "./chunk-azctppjh.js";
+} from "./chunk-rz541e2b.js";
 import {
+  backupPathFor,
   isAlive,
-  openBlocks,
-  parseQuestions,
   readLock,
   withWorkspaceLock,
   workspaceRootOfRunDir,
+  writeAtomic,
   yamlScalar
-} from "./chunk-j234zf0t.js";
+} from "./chunk-c6t5nx0r.js";
 import {
-  noteDeprecations
-} from "./chunk-t56k6146.js";
+  noteDeprecations,
+  openBlocks,
+  parseQuestions
+} from "./chunk-rpcxsqh3.js";
 import {
   listRunDirs,
-  parseYaml
-} from "./chunk-p274ckxv.js";
+  parseYaml,
+  parseYamlRepairing
+} from "./chunk-sq44k6g2.js";
 
 // src/core/statusline/runSnapshot.ts
 import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
 import { join as join2 } from "node:path";
 
 // src/core/run/RunStore.ts
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
 
 // src/core/run/emitRunYaml.ts
 function inlineList(values) {
@@ -52,8 +59,12 @@ function gatesPolicy(policy) {
   const entries = Object.entries(policy).map(([id, value]) => `${yamlScalar(id)}: ${yamlScalar(value)}`);
   return `{${entries.join(", ")}}`;
 }
+function gateEvidence(e) {
+  return `{path: ${yamlScalar(e.path)}, role: ${yamlScalar(e.role)}, verdict: ${yamlScalar(e.verdict)}, ` + `sampled: ${String(e.sampled)}, of: ${String(e.of)}, resolved: ${String(e.resolved)}, ` + `refuted: ${String(e.refuted)}, outside_surface: ${String(e.outside_surface)}}`;
+}
 function gate(g) {
-  return `{type: ${yamlScalar(g.type)}, status: ${yamlScalar(g.status)}, by: ${yamlScalar(g.by)}, ` + `at: ${yamlScalar(g.at)}, note: ${yamlScalar(g.note)}}`;
+  const evidence = g.evidence === undefined ? "" : `, evidence: ${gateEvidence(g.evidence)}`;
+  return `{type: ${yamlScalar(g.type)}, status: ${yamlScalar(g.status)}, by: ${yamlScalar(g.by)}, ` + `at: ${yamlScalar(g.at)}, note: ${yamlScalar(g.note)}${evidence}}`;
 }
 function task(t, indent) {
   const inner = `${indent}   `;
@@ -115,11 +126,18 @@ function emitRunYaml(run) {
     lines.push(`triage: {split: ${yamlScalar(run.triage.split)}, depends_on: ${inlineList(run.triage.depends_on)}}`);
   }
   if (run.build !== undefined && run.build.epic_branch.length > 0) {
-    lines.push(`build: {epic_branch: ${inlineList(run.build.epic_branch)}}`);
+    const model = run.build.branch_model === undefined ? "" : `, branch_model: ${yamlScalar(run.build.branch_model)}`;
+    lines.push(`build: {epic_branch: ${inlineList(run.build.epic_branch)}${model}}`);
   }
   if (run.cancelled !== undefined) {
     lines.push(`cancelled: {by: ${yamlScalar(run.cancelled.by)}, at: ${yamlScalar(run.cancelled.at)}, ` + `note: ${yamlScalar(run.cancelled.note)}}`);
   }
+  if (run.attended_by !== undefined) {
+    lines.push(`attended_by: ${yamlScalar(run.attended_by)}`);
+  }
+  if (run.keep_worktrees === true) {
+    lines.push("keep_worktrees: true");
+  }
   if (run.gates_policy !== undefined && Object.keys(run.gates_policy).length > 0) {
     lines.push(`gates_policy: ${gatesPolicy(run.gates_policy)}`);
   }
@@ -149,10 +167,13 @@ function emitBudgetYaml(budget) {
     `per_agent_max_usd: ${money(budget.per_agent_max_usd)}`,
     `warn_at_pct: ${budget.warn_at_pct}`,
     `on_exceed: ${yamlScalar(budget.on_exceed)}`,
+    ...budget.economy === DEFAULT_ECONOMY ? [] : [`economy: ${yamlScalar(budget.economy)}`],
+    ...budget.on_host_tokens_exceed === DEFAULT_ON_HOST_TOKENS_EXCEED ? [] : [`on_host_tokens_exceed: ${yamlScalar(budget.on_host_tokens_exceed)}`],
     "phases:"
   ];
   for (const phase of budget.phases) {
-    lines.push(`  - {id: ${yamlScalar(phase.id)}, ceiling_usd: ${money(phase.ceiling_usd)}, ` + `spent_usd: ${money(phase.spent_usd)}}`);
+    const economy = phase.economy === null ? "" : `, economy: ${yamlScalar(phase.economy)}`;
+    lines.push(`  - {id: ${yamlScalar(phase.id)}, ceiling_usd: ${money(phase.ceiling_usd)}, ` + `spent_usd: ${money(phase.spent_usd)}${economy}}`);
   }
   return `${lines.join(`
 `)}
@@ -179,8 +200,8 @@ class RunStore {
     const runPath = join(runDir, "run.yml");
     if (!existsSync(runPath))
       throw new RunStoreError(`no run.yml in ${runDir}`);
-    const doc = parseYaml(readFileSync(runPath, "utf8"));
-    const validation = validateRunFile(doc);
+    const run = parseStateFile(runPath);
+    const validation = validateRunFile(run.doc);
     noteDeprecations(runPath, validation);
     if (!validation.ok) {
       const first = validation.issues[0];
@@ -189,14 +210,30 @@ class RunStore {
     const budgetPath = join(runDir, "budget.yml");
     if (!existsSync(budgetPath))
       throw new RunStoreError(`no budget.yml in ${runDir}`);
-    const budgetDoc = parseYaml(readFileSync(budgetPath, "utf8"));
-    const budgetValidation = validateRunBudget(budgetDoc);
+    const budget = parseStateFile(budgetPath);
+    const budgetValidation = validateRunBudget(budget.doc);
     noteDeprecations(budgetPath, budgetValidation);
     if (!budgetValidation.ok) {
       const first = budgetValidation.issues[0];
       throw new RunStoreError(`invalid budget.yml (${budgetPath}): ${first?.path ?? ""} ${first?.message ?? "schema error"}`);
     }
-    return new RunStore(runDir, asRunFile(doc), asRunBudget(budgetDoc), EventLog.forRun(runDir));
+    const store = new RunStore(runDir, asRunFile(run.doc), asRunBudget(budget.doc), EventLog.forRun(runDir));
+    if (run.repaired || budget.repaired)
+      store.healOnDisk(run.repaired, budget.repaired);
+    return store;
+  }
+  healOnDisk(runRepaired, budgetRepaired) {
+    try {
+      withWorkspaceLock(workspaceRootOfRunDir(this.runDir), () => {
+        if (runRepaired)
+          writeAtomic(join(this.runDir, "run.yml"), emitRunYaml(this.current));
+        if (budgetRepaired)
+          writeAtomic(join(this.runDir, "budget.yml"), emitBudgetYaml(this.currentBudget));
+      });
+      const which = [runRepaired ? "run.yml" : "", budgetRepaired ? "budget.yml" : ""].filter((name) => name !== "").join(" and ");
+      process.stderr.write(`tldrx: ${this.runDir}: ${which} held text broken across lines by an emitter bug ` + "since fixed. It was repaired in memory and rewritten correctly; the version that was " + `on disk is beside it as .bak. Nothing else about the run was changed.
+`);
+    } catch {}
   }
   static find(root, runId) {
     const dir = listRunDirs(root).find((d) => basename(d) === runId);
@@ -306,18 +343,21 @@ class RunStore {
     }
   }
 }
-function writeAtomic(path, content) {
-  const temp = `${path}.tmp-${String(process.pid)}`;
-  mkdirSync(dirname(path), { recursive: true });
+function parseStateFile(path) {
+  const text = readFileSync(path, "utf8");
   try {
-    writeFileSync(temp, content, "utf8");
-    renameSync(temp, path);
+    return parseYamlRepairing(text);
   } catch (error) {
-    try {
-      if (existsSync(temp))
-        rmSync(temp, { force: true });
-    } catch {}
-    throw error;
+    const backup = backupPathFor(path);
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new RunStoreError([
+      `${path} does not parse: ${detail}`,
+      "  every tldrx command on this run reads that file first, so all of them fail until it does",
+      existsSync(backup) ? `  the version the last save replaced is at ${backup} — recovery is MANUAL and tldrx ` + "will not do it for you:" + `
+    diff it, and if that version is the one you want, copy it back over ${basename(path)}` : `  there is no ${basename(backup)} beside it — this file has not been written since ` + "backups arrived, so there is no previous version to go back to",
+      "  a hand-edit is the other way out, and it is the only one that keeps work the backup predates"
+    ].join(`
+`));
   }
 }
 function rollUp(run) {
@@ -418,6 +458,7 @@ function fromStore(root) {
     openCount: open.length,
     autoGates: stages.filter((s) => s.gate.status === "approved" && s.gate.by === AUTO).length,
     staleStages: stages.filter((s) => s.stale === true).length,
+    attendedByHost: isAttendedByHost(run),
     source: "run-store"
   };
 }
@@ -446,6 +487,7 @@ function fromTolerantRead(root) {
     openCount: open.length,
     autoGates: 0,
     staleStages: 0,
+    attendedByHost: isAttendedByHostView(view),
     source: "tolerant"
   };
 }