tldr-experts 0.3.0

package/dist/hooks/chunk-1zwcxd3f.js

@@ -0,0 +1,66 @@
+import {
+  parseHookInput,
+  readStdin
+} from "./chunk-a8p2rc94.js";
+
+// src/hooks/lib/decide.ts
+function deny(reason) {
+  process.stdout.write(`${JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason
+    }
+  })}
+`);
+  process.exit(0);
+}
+function allow() {
+  process.exit(0);
+}
+function postContext(text) {
+  process.stdout.write(`${JSON.stringify({
+    hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: text }
+  })}
+`);
+  process.exit(0);
+}
+function sessionContext(text) {
+  process.stdout.write(`${JSON.stringify({
+    hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: text }
+  })}
+`);
+  process.exit(0);
+}
+function failOpen(name, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`tldrx hook ${name}: internal error, allowing — ${message.split(`
+`)[0] ?? ""}
+`);
+  process.exit(0);
+}
+async function runHook(name, body) {
+  try {
+    await body();
+  } catch (error) {
+    failOpen(name, error);
+  }
+  return allow();
+}
+
+// src/hooks/lib/payload.ts
+async function readPayload() {
+  return parseHookInput(await readStdin()) ?? {};
+}
+function toolInput(payload) {
+  const input = payload.tool_input;
+  return input !== undefined && typeof input === "object" ? input : {};
+}
+function filePathOf(payload) {
+  return toolInput(payload).file_path ?? payload.file_path ?? payload.path ?? "";
+}
+function isWriteOrEdit(payload) {
+  return payload.tool_name === "Write" || payload.tool_name === "Edit";
+}
+
+export { deny, allow, postContext, sessionContext, failOpen, runHook, readPayload, toolInput, filePathOf, isWriteOrEdit };

package/dist/hooks/chunk-9gb21660.js

@@ -0,0 +1,66 @@
+// src/hooks/lib/messages.ts
+var GRAMMAR = "[src: <repo:path:line> | https://… | Q<n> | F<n> | $ <cmd> → exit <n> | graph:<node> | absent:<path>]";
+function usd(amount) {
+  return `$${amount.toFixed(2)}`;
+}
+function claimSourcesDeny(relPath, lines) {
+  const list = lines.map((n) => `L${n}`).join(", ");
+  return `[tldrx] claim-sources: ${lines.length} unsourced bullet(s) in ${relPath} — ${list}.
+` + `Every bullet under Findings/Decisions/Unknowns/Evidence ledger must end with ${GRAMMAR}. ` + "Add the source or delete the claim.";
+}
+function claimSourcesEmptySectionDeny(relPath, sections) {
+  const list = sections.map((s) => `"${s.name}" (L${s.line})`).join(", ");
+  return `[tldrx] claim-sources: ${sections.length} checked section(s) in ${relPath} contain no list ` + `items — ${list}.
+` + "Findings/Decisions/Unknowns/Evidence ledger must each hold at least one sourced item; prose alone " + "is not a claim anything can check. If there is genuinely nothing, say so as an item: " + "`- none [src: absent:<what you looked at>]`.";
+}
+function claimSourcesMalformedDeny(relPath, issues) {
+  const list = issues.map((i) => `L${i.line}`).join(", ");
+  return `[tldrx] claim-sources: ${issues.length} malformed citation(s) in ${relPath} — ${list}.
+` + "The bullet cites a source but the token could not be read. The `[src: …]` token must be the LAST " + "thing on the line: remove the backticks around it and any words after it. A closing quote, bracket " + "or a final `.` after the `]` is fine.";
+}
+function claimSourcesUnresolvedDeny(relPath, issues) {
+  const detail = issues.map((i) => `L${i.line}: ${i.message}`).join(`
+`);
+  return `[tldrx] claim-sources: ${issues.length} unresolvable source(s) in ${relPath}.
+` + `${detail}
+` + "A cited file must exist with the line in range, a command must be one of workspace.yml's, and " + "`$ … → exit n` belongs only in the Evidence ledger. Fix the citation or delete the claim.";
+}
+function noReAskDeny(questionId, questionTitle, fact) {
+  const who = fact.source.who;
+  const when = fact.source.when.slice(0, 10);
+  const run = fact.source.run ?? "init";
+  return `[tldrx] no-re-ask: ${questionId} "${questionTitle}" is already answered by ${fact.id} ` + `(${who}, ${when}, run ${run}): "${ellipsise(fact.fact)}". Cite it as [src: ${fact.id}] instead of asking.
+` + "If the fact is stale, set its `retired: {at, by, reason}` in .tldrx/memory/facts.yml first, " + "then re-write the question.";
+}
+function dodGateDeny(storyId, command, repo, exitCode, outputTail) {
+  const tail = outputTail.trim() === "" ? "(no output)" : outputTail.trim();
+  return `[tldrx] DoD-gate: story ${storyId} cannot be marked done — \`${command}\` in repo ${repo} ` + `exited ${exitCode} (expected 0).
+` + `Command output tail: ${tail}
+` + "Fix the code or the story's dod block; done means proven, not asserted.";
+}
+function dodGateMissingBlockDeny(storyId, relPath) {
+  return `[tldrx] DoD-gate: story ${storyId} cannot be marked done — no fenced \`\`\`dod block in ${relPath}.
+` + "Add the commands that prove it (test, lint, typecheck from map/commands.md) and let the gate re-run them; " + "done means proven, not asserted.";
+}
+function dodGateRefusedCommandDeny(storyId, command, why) {
+  return `[tldrx] DoD-gate: story ${storyId} cannot be marked done — refusing to RUN \`${command}\`.
+` + `${why}
+` + "This gate executes its commands for real, as you. It runs only what the workspace declared, " + "argv-split with no shell — a story is data, and data does not get to invent a command.";
+}
+function dodGateInternalErrorDeny(storyId, message) {
+  return `[tldrx] DoD-gate: story ${storyId} cannot be marked done — the gate itself failed: ${message}
+` + "This gate fails closed: an unproven story stays not-done. Fix the gate's inputs and try again.";
+}
+function budgetGateDeny(stage, phase, left, ceiling, estimate, fixCommand) {
+  return `[tldrx] budget-gate: refusing to start stage "${stage}" — phase ${phase} has ${usd(left)} left of ` + `${usd(ceiling)} and the stage estimate is ${usd(estimate)}. Run \`${fixCommand}\` (add \`--take-from ` + `<phase>\` to move the money instead of adding it), lower budget_usd in .tldrx/stages/${stage}/stage.yml, ` + "or set on_exceed: warn.";
+}
+function ellipsise(text, max = 40) {
+  if (text.length <= max)
+    return text;
+  const head = text.slice(0, max);
+  const lastSpace = head.lastIndexOf(" ");
+  const cut = lastSpace > 0 ? head.slice(0, lastSpace) : head;
+  return `${cut.replace(/[\s.,;:—-]+$/, "")}…`;
+}
+
+export { claimSourcesDeny, claimSourcesEmptySectionDeny, claimSourcesMalformedDeny, claimSourcesUnresolvedDeny, noReAskDeny, dodGateDeny, dodGateMissingBlockDeny, dodGateRefusedCommandDeny, dodGateInternalErrorDeny, budgetGateDeny };

package/dist/hooks/chunk-a8p2rc94.js

@@ -0,0 +1,20 @@
+import {
+  runtime
+} from "./chunk-p274ckxv.js";
+
+// src/core/hooks/passthrough.ts
+async function readStdin() {
+  return await runtime.readStdin();
+}
+function parseHookInput(text) {
+  if (text.trim() === "")
+    return null;
+  try {
+    const value = JSON.parse(text);
+    return typeof value === "object" && value !== null ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export { readStdin, parseHookInput };

package/dist/hooks/chunk-azctppjh.js

@@ -0,0 +1,198 @@
+import {
+  asDocument,
+  requireEnum,
+  requireKeys,
+  requireNumber,
+  requireString,
+  result
+} from "./chunk-0bt6yb2q.js";
+
+// src/core/events/EventLog.ts
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+// src/core/events/Event.ts
+var EVENT_TYPES = [
+  "run.created",
+  "run.closed",
+  "run.unlocked",
+  "run.cancelled",
+  "phase.started",
+  "phase.done",
+  "stage.started",
+  "stage.done",
+  "stage.failed",
+  "stage.skipped",
+  "task.started",
+  "task.done",
+  "agent.spawned",
+  "agent.result",
+  "question.asked",
+  "question.answered",
+  "gate.requested",
+  "gate.approved",
+  "gate.rejected",
+  "gate.revoked",
+  "check.passed",
+  "check.failed",
+  "budget.warned",
+  "budget.blocked",
+  "budget.raised",
+  "fact.added",
+  "fact.retired",
+  "map.refreshed",
+  "ticket.synced",
+  "error"
+];
+var EVENT_KEYS = ["ts", "run", "stage", "type", "actor", "cost_usd", "payload"];
+var MAX_LINE_BYTES = 8 * 1024;
+var MAX_PAYLOAD_BYTES = 4 * 1024;
+var MAX_PAYLOAD_DEPTH = 3;
+function validateEvent(input) {
+  const issues = [];
+  const doc = asDocument(input, issues);
+  if (!doc)
+    return result(issues);
+  requireKeys(doc, EVENT_KEYS, "", issues);
+  for (const key of Object.keys(doc)) {
+    if (!EVENT_KEYS.includes(key)) {
+      issues.push({ path: key, message: `unexpected key \`${key}\` — the envelope is exactly ${EVENT_KEYS.join(", ")}` });
+    }
+  }
+  requireString(doc.ts, "ts", issues);
+  requireString(doc.run, "run", issues);
+  if (doc.stage !== null)
+    requireString(doc.stage, "stage", issues);
+  requireEnum(doc.type, EVENT_TYPES, "type", issues);
+  requireString(doc.actor, "actor", issues);
+  requireNumber(doc.cost_usd, "cost_usd", issues);
+  if (typeof doc.cost_usd === "number" && doc.cost_usd < 0) {
+    issues.push({ path: "cost_usd", message: "must be >= 0" });
+  }
+  if (typeof doc.payload !== "object" || doc.payload === null || Array.isArray(doc.payload)) {
+    issues.push({ path: "payload", message: "expected an object" });
+  } else {
+    const bytes = Buffer.byteLength(JSON.stringify(doc.payload), "utf8");
+    if (bytes > MAX_PAYLOAD_BYTES) {
+      issues.push({ path: "payload", message: `${bytes} bytes exceeds the ${MAX_PAYLOAD_BYTES} byte cap` });
+    }
+    const depth = objectDepth(doc.payload);
+    if (depth > MAX_PAYLOAD_DEPTH) {
+      issues.push({ path: "payload", message: `nesting depth ${depth} exceeds ${MAX_PAYLOAD_DEPTH}` });
+    }
+  }
+  return result(issues);
+}
+function serializeEvent(event) {
+  return JSON.stringify({
+    ts: event.ts,
+    run: event.run,
+    stage: event.stage,
+    type: event.type,
+    actor: event.actor,
+    cost_usd: event.cost_usd,
+    payload: event.payload
+  });
+}
+function objectDepth(value, depth = 1) {
+  if (typeof value !== "object" || value === null)
+    return depth - 1;
+  let deepest = depth;
+  for (const child of Object.values(value)) {
+    if (typeof child === "object" && child !== null) {
+      deepest = Math.max(deepest, objectDepth(child, depth + 1));
+    }
+  }
+  return deepest;
+}
+
+// src/core/events/EventLog.ts
+class EventLog {
+  path;
+  constructor(path) {
+    this.path = path;
+  }
+  static forRun(runDir) {
+    return new EventLog(join(runDir, "events.jsonl"));
+  }
+  get sizeBytes() {
+    return existsSync(this.path) ? statSync(this.path).size : 0;
+  }
+  append(event) {
+    const validation = validateEvent(event);
+    if (!validation.ok) {
+      const first = validation.issues[0];
+      throw new Error(`refusing to append an invalid event: ${first?.path ?? ""} ${first?.message ?? ""}`);
+    }
+    const line = serializeEvent(event);
+    const bytes = Buffer.byteLength(line, "utf8") + 1;
+    if (bytes > MAX_LINE_BYTES) {
+      throw new Error(`event line is ${bytes} bytes (max ${MAX_LINE_BYTES})`);
+    }
+    const before = this.sizeBytes;
+    mkdirSync(dirname(this.path), { recursive: true });
+    appendFileSync(this.path, `${line}
+`, "utf8");
+    const after = this.sizeBytes;
+    if (after < before + bytes) {
+      throw new Error(`events.jsonl shrank under an append (${before} -> ${after} bytes): the log is append-only`);
+    }
+  }
+  tryAppend(event) {
+    try {
+      this.append(event);
+      return null;
+    } catch (error) {
+      return error instanceof Error ? error.message : String(error);
+    }
+  }
+  replaceAll(content) {
+    const next = Buffer.byteLength(content, "utf8");
+    const current = this.sizeBytes;
+    if (next < current) {
+      throw new Error(`refusing to shorten events.jsonl (${current} -> ${next} bytes): the log is append-only`);
+    }
+    mkdirSync(dirname(this.path), { recursive: true });
+    writeFileSync(this.path, content, "utf8");
+  }
+  readAll() {
+    if (!existsSync(this.path))
+      return { events: [], lines: [], skipped: 0 };
+    let text;
+    try {
+      text = readFileSync(this.path, "utf8");
+    } catch {
+      return { events: [], lines: [], skipped: 0 };
+    }
+    const events = [];
+    const lines = [];
+    let skipped = 0;
+    text.split(`
+`).forEach((line, index) => {
+      if (line.trim() === "")
+        return;
+      try {
+        events.push(JSON.parse(line));
+        lines.push(index + 1);
+      } catch {
+        skipped += 1;
+      }
+    });
+    return { events, lines, skipped };
+  }
+  read() {
+    const result2 = this.readAll();
+    if (result2.skipped > 0 && !WARNED.has(this.path)) {
+      WARNED.add(this.path);
+      process.stderr.write(`tldrx: ${this.path}: ${skippedNote(result2.skipped)} (unparseable — a torn write)
+`);
+    }
+    return result2.events;
+  }
+}
+function skippedNote(skipped) {
+  return `${String(skipped)} line${skipped === 1 ? "" : "s"} skipped`;
+}
+var WARNED = new Set;
+
+export { EventLog };