tldr-experts 0.3.0

package/dist/hooks/chunk-sdjnnmzz.js

@@ -0,0 +1,497 @@
+import {
+  asDocument,
+  isRecord,
+  requireArray,
+  requireEnum,
+  requireKeys,
+  requireNumber,
+  requireString,
+  requireVersion,
+  result
+} from "./chunk-0bt6yb2q.js";
+import {
+  listRunDirs,
+  parseYaml
+} from "./chunk-p274ckxv.js";
+
+// src/hooks/lib/runFile.ts
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+var TERMINAL_STATUSES = ["done", "failed", "skipped", "cancelled"];
+function loadRunView(runDir) {
+  const path = join(runDir, "run.yml");
+  if (!existsSync(path))
+    return null;
+  let doc;
+  try {
+    const parsed = parseYaml(readFileSync(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null)
+      return null;
+    doc = parsed;
+  } catch {
+    return null;
+  }
+  const rawCursor = doc.cursor;
+  const cursor = rawCursor === undefined || rawCursor === null ? null : {
+    phase: str(rawCursor.phase),
+    stage: str(rawCursor.stage),
+    task: typeof rawCursor.task === "string" ? rawCursor.task : null
+  };
+  const phases = [];
+  if (Array.isArray(doc.phases)) {
+    for (const entry of doc.phases) {
+      const stages = [];
+      if (Array.isArray(entry?.stages)) {
+        for (const s of entry.stages) {
+          stages.push({
+            id: str(s?.id),
+            status: str(s?.status),
+            expert: typeof s?.expert === "string" ? s.expert : null,
+            budget_usd: typeof s?.budget_usd === "number" ? s.budget_usd : null
+          });
+        }
+      }
+      phases.push({ id: str(entry?.id), status: str(entry?.status), stages });
+    }
+  }
+  return {
+    dir: runDir,
+    run: str(doc.run) || str(doc.run_id),
+    title: str(doc.title),
+    scope: str(doc.scope),
+    status: str(doc.status),
+    updated_at: str(doc.updated_at),
+    cursor,
+    phases
+  };
+}
+function isTerminal(status) {
+  return TERMINAL_STATUSES.includes(status);
+}
+function cursorStage(view) {
+  if (view.cursor === null)
+    return null;
+  for (const phase of view.phases) {
+    if (phase.id !== view.cursor.phase)
+      continue;
+    return phase.stages.find((s) => s.id === view.cursor?.stage) ?? null;
+  }
+  return null;
+}
+function openRunViews(root) {
+  const open = [];
+  for (const dir of listRunDirs(root)) {
+    const view = loadRunView(dir);
+    if (view === null || isTerminal(view.status))
+      continue;
+    open.push(view);
+  }
+  return open.sort((a, b) => a.updated_at > b.updated_at ? -1 : a.updated_at < b.updated_at ? 1 : 0);
+}
+function newestActiveRun(root) {
+  return openRunViews(root)[0] ?? null;
+}
+function str(value) {
+  return typeof value === "string" ? value : "";
+}
+
+// src/hooks/lib/actor.ts
+function currentActor() {
+  const user = process.env.USER ?? process.env.USERNAME ?? "";
+  return user.trim() === "" ? "unknown" : user.trim();
+}
+function nowRfc3339() {
+  return `${new Date().toISOString().slice(0, 19)}Z`;
+}
+
+// src/core/budget/wouldExceed.ts
+function totalSpent(budget) {
+  return budget.phases.reduce((sum, p) => sum + p.spent_usd, 0);
+}
+function wouldExceed(budget, phaseId, estimate) {
+  const phase = phaseId === null ? undefined : budget.phases.find((p) => p.id === phaseId);
+  const scope = phase === undefined ? "run" : "phase";
+  const ceiling = phase === undefined ? budget.ceiling_usd : phase.ceiling_usd;
+  const spent = phase === undefined ? totalSpent(budget) : phase.spent_usd;
+  const left = round(ceiling - spent);
+  const exceeds = round(spent + estimate) > ceiling;
+  const pct = ceiling === 0 ? 100 : (spent + estimate) / ceiling * 100;
+  return {
+    exceeds,
+    blocked: exceeds && budget.on_exceed === "block",
+    scope,
+    phaseId: phase === undefined ? null : phase.id,
+    remaining: left,
+    ceiling,
+    estimate,
+    warns: !exceeds && pct >= budget.warn_at_pct
+  };
+}
+function round(n) {
+  return Math.round(n * 1e6) / 1e6;
+}
+
+// src/core/run/gatePolicy.ts
+var GATE_POLICIES = ["human", "auto"];
+function isGatePolicy(value) {
+  return typeof value === "string" && GATE_POLICIES.includes(value);
+}
+function validateGatesPolicy(value, stageIds, issues) {
+  if (value === undefined || value === null)
+    return;
+  if (!isRecord(value)) {
+    issues.push({ path: "gates_policy", message: "expected a mapping of stage id -> human | auto" });
+    return;
+  }
+  const known = new Set(stageIds);
+  for (const [key, raw] of Object.entries(value)) {
+    if (!isGatePolicy(raw)) {
+      issues.push({
+        path: `gates_policy.${key}`,
+        message: `expected one of ${GATE_POLICIES.join(" | ")}, got ${JSON.stringify(raw)}`
+      });
+    }
+    if (known.size > 0 && !known.has(key)) {
+      issues.push({ path: `gates_policy.${key}`, message: `names no stage in this run` });
+    }
+  }
+}
+
+// src/core/run/RunFile.ts
+var STAGE_STATUSES = [
+  "pending",
+  "ready",
+  "running",
+  "awaiting_answer",
+  "awaiting_gate",
+  "blocked",
+  "done",
+  "failed",
+  "skipped",
+  "cancelled"
+];
+var TERMINAL_STATUSES2 = ["done", "failed", "skipped", "cancelled"];
+var GATE_TYPES = ["approve", "checks", "auto"];
+var GATE_STATUSES = ["pending", "approved", "rejected", "n-a"];
+var RUN_ID_RE = /^\d{6}-[a-z0-9-]{1,40}$/;
+var PHASE_ID_RE = /^0[1-5]-[a-z]+$/;
+var MAX_PHASES = 5;
+var MAX_STAGES = 40;
+var MAX_TASKS = 200;
+function isTerminal2(status) {
+  return TERMINAL_STATUSES2.includes(status);
+}
+function isFinished(status) {
+  return status === "done" || status === "cancelled";
+}
+function flatten(run) {
+  const out = [];
+  for (const phase of run.phases)
+    for (const stage of phase.stages)
+      out.push({ phase, stage });
+  return out;
+}
+function stageAt(run, cursor) {
+  return flatten(run).find((e) => e.phase.id === cursor.phase && e.stage.id === cursor.stage) ?? null;
+}
+function deriveRunStatus(run) {
+  const all = flatten(run);
+  if (run.cancelled !== undefined)
+    return "cancelled";
+  if (all.some((e) => e.stage.status === "failed"))
+    return "failed";
+  if (all.length > 0 && all.every((e) => isTerminal2(e.stage.status)))
+    return "done";
+  return stageAt(run, run.cursor)?.stage.status ?? "pending";
+}
+function derivePhaseStatus(phase) {
+  if (phase.stages.length === 0)
+    return "skipped";
+  if (phase.stages.some((s) => s.status === "failed"))
+    return "failed";
+  if (phase.stages.every((s) => isTerminal2(s.status)))
+    return "done";
+  const live = phase.stages.find((s) => !isTerminal2(s.status));
+  return live?.status ?? "pending";
+}
+function validateRunFile(input) {
+  const issues = [];
+  const deprecations = [];
+  const doc = asDocument(input, issues);
+  if (!doc)
+    return result(issues);
+  requireVersion(doc, issues, deprecations);
+  requireKeys(doc, ["run", "title", "scope", "workflow", "repos", "created_at", "updated_at", "status", "cursor", "budget", "phases"], "", issues);
+  if (typeof doc.run !== "string" || !RUN_ID_RE.test(doc.run)) {
+    issues.push({ path: "run", message: "run id must match ^\\d{6}-[a-z0-9-]{1,40}$" });
+  }
+  requireString(doc.title, "title", issues);
+  requireString(doc.scope, "scope", issues);
+  requireString(doc.workflow, "workflow", issues);
+  requireString(doc.created_at, "created_at", issues);
+  requireString(doc.updated_at, "updated_at", issues);
+  requireEnum(doc.status, STAGE_STATUSES, "status", issues);
+  requireArray(doc.repos, "repos", issues);
+  let cursor = null;
+  if (isRecord(doc.cursor)) {
+    requireKeys(doc.cursor, ["phase", "stage", "task"], "cursor", issues);
+    cursor = {
+      phase: String(doc.cursor.phase ?? ""),
+      stage: String(doc.cursor.stage ?? ""),
+      task: typeof doc.cursor.task === "string" ? doc.cursor.task : null
+    };
+  } else if (doc.cursor !== undefined) {
+    issues.push({ path: "cursor", message: "expected a mapping" });
+  }
+  if (isRecord(doc.budget)) {
+    requireKeys(doc.budget, ["ceiling_usd", "spent_usd", "per_agent_max_usd"], "budget", issues);
+    requireNumber(doc.budget.ceiling_usd, "budget.ceiling_usd", issues);
+    requireNumber(doc.budget.spent_usd, "budget.spent_usd", issues);
+    requireNumber(doc.budget.per_agent_max_usd, "budget.per_agent_max_usd", issues);
+  } else if (doc.budget !== undefined) {
+    issues.push({ path: "budget", message: "expected a mapping" });
+  }
+  if (doc.build !== undefined) {
+    if (isRecord(doc.build)) {
+      requireKeys(doc.build, ["epic_branch"], "build", issues);
+      if (requireArray(doc.build.epic_branch, "build.epic_branch", issues)) {
+        doc.build.epic_branch.forEach((branch, i) => {
+          requireString(branch, `build.epic_branch[${i}]`, issues);
+        });
+      }
+    } else {
+      issues.push({ path: "build", message: "expected a mapping" });
+    }
+  }
+  if (doc.cancelled !== undefined) {
+    if (isRecord(doc.cancelled)) {
+      requireKeys(doc.cancelled, ["by", "at", "note"], "cancelled", issues);
+      requireString(doc.cancelled.by, "cancelled.by", issues);
+      requireString(doc.cancelled.at, "cancelled.at", issues);
+      requireString(doc.cancelled.note, "cancelled.note", issues);
+    } else {
+      issues.push({ path: "cancelled", message: "expected a mapping" });
+    }
+  }
+  if (doc.triage !== undefined) {
+    if (isRecord(doc.triage)) {
+      requireKeys(doc.triage, ["split", "depends_on"], "triage", issues);
+      requireString(doc.triage.split, "triage.split", issues);
+      if (requireArray(doc.triage.depends_on, "triage.depends_on", issues)) {
+        doc.triage.depends_on.forEach((slug, i) => {
+          requireString(slug, `triage.depends_on[${i}]`, issues);
+        });
+      }
+    } else {
+      issues.push({ path: "triage", message: "expected a mapping" });
+    }
+  }
+  if (!requireArray(doc.phases, "phases", issues))
+    return result(issues, deprecations);
+  const phases = doc.phases;
+  if (phases.length > MAX_PHASES) {
+    issues.push({ path: "phases", message: `${phases.length} phases exceeds the ${MAX_PHASES} cap` });
+  }
+  const declaredStageIds = [];
+  for (const phase of phases) {
+    if (!isRecord(phase) || !Array.isArray(phase.stages))
+      continue;
+    for (const stage of phase.stages) {
+      if (isRecord(stage) && typeof stage.id === "string")
+        declaredStageIds.push(stage.id);
+    }
+  }
+  validateGatesPolicy(doc.gates_policy, declaredStageIds, issues);
+  let stageCount = 0;
+  let taskCount = 0;
+  let running = 0;
+  let cursorResolves = false;
+  let spentFromTasks = 0;
+  const phaseIds = new Set;
+  phases.forEach((phase, i) => {
+    const base = `phases[${i}]`;
+    if (!isRecord(phase)) {
+      issues.push({ path: base, message: "expected a mapping" });
+      return;
+    }
+    requireKeys(phase, ["id", "status", "stages"], base, issues);
+    const phaseId = typeof phase.id === "string" ? phase.id : "";
+    if (!PHASE_ID_RE.test(phaseId)) {
+      issues.push({ path: `${base}.id`, message: "phase id must match ^0[1-5]-[a-z]+$" });
+    }
+    if (phaseIds.has(phaseId))
+      issues.push({ path: `${base}.id`, message: `duplicate phase id ${phaseId}` });
+    phaseIds.add(phaseId);
+    requireEnum(phase.status, STAGE_STATUSES, `${base}.status`, issues);
+    if (!requireArray(phase.stages, `${base}.stages`, issues))
+      return;
+    const stageIds = new Set;
+    phase.stages.forEach((stage, j) => {
+      const path = `${base}.stages[${j}]`;
+      stageCount++;
+      if (!isRecord(stage)) {
+        issues.push({ path, message: "expected a mapping" });
+        return;
+      }
+      requireKeys(stage, ["id", "status", "expert", "model", "budget_usd", "cost_usd", "started_at", "ended_at", "inputs", "outputs", "gate", "tasks"], path, issues);
+      const stageId = typeof stage.id === "string" ? stage.id : "";
+      if (stageIds.has(stageId))
+        issues.push({ path: `${path}.id`, message: `duplicate stage id ${stageId}` });
+      stageIds.add(stageId);
+      requireEnum(stage.status, STAGE_STATUSES, `${path}.status`, issues);
+      if (stage.status === "running")
+        running++;
+      requireNumber(stage.budget_usd, `${path}.budget_usd`, issues);
+      requireNumber(stage.cost_usd, `${path}.cost_usd`, issues);
+      requireArray(stage.inputs, `${path}.inputs`, issues);
+      requireArray(stage.outputs, `${path}.outputs`, issues);
+      if (stage.stale !== undefined && typeof stage.stale !== "boolean") {
+        issues.push({ path: `${path}.stale`, message: "expected true or false" });
+      }
+      checkOrder(stage.started_at, stage.ended_at, path, issues);
+      if (cursor !== null && cursor.phase === phaseId && cursor.stage === stageId)
+        cursorResolves = true;
+      if (isRecord(stage.gate)) {
+        const gate = stage.gate;
+        requireKeys(gate, ["type", "status", "by", "at", "note"], `${path}.gate`, issues);
+        requireEnum(gate.type, GATE_TYPES, `${path}.gate.type`, issues);
+        requireEnum(gate.status, GATE_STATUSES, `${path}.gate.status`, issues);
+        if (gate.status === "approved" && (typeof gate.by !== "string" || typeof gate.at !== "string")) {
+          issues.push({ path: `${path}.gate`, message: "an approved gate needs both `by` and `at`" });
+        }
+      } else if (stage.gate !== undefined) {
+        issues.push({ path: `${path}.gate`, message: "expected a mapping" });
+      }
+      if (requireArray(stage.tasks, `${path}.tasks`, issues)) {
+        const taskIds = new Set;
+        stage.tasks.forEach((task, k) => {
+          const tp = `${path}.tasks[${k}]`;
+          taskCount++;
+          if (!isRecord(task)) {
+            issues.push({ path: tp, message: "expected a mapping" });
+            return;
+          }
+          requireKeys(task, ["id", "status", "cost_usd", "error", "session_id"], tp, issues);
+          const taskId = typeof task.id === "string" ? task.id : "";
+          if (!/^t\d+$/.test(taskId))
+            issues.push({ path: `${tp}.id`, message: "task id must match ^t\\d+$" });
+          if (taskIds.has(taskId))
+            issues.push({ path: `${tp}.id`, message: `duplicate task id ${taskId}` });
+          taskIds.add(taskId);
+          requireEnum(task.status, STAGE_STATUSES, `${tp}.status`, issues);
+          if (task.cost_usd !== null)
+            requireNumber(task.cost_usd, `${tp}.cost_usd`, issues);
+          if (task.metered !== undefined && typeof task.metered !== "boolean") {
+            issues.push({ path: `${tp}.metered`, message: "expected true or false" });
+          }
+          if (task.cost_usd === null && task.metered !== false) {
+            issues.push({ path: `${tp}.metered`, message: "a null cost_usd must be marked `metered: false`" });
+          }
+          if (typeof task.cost_usd === "number")
+            spentFromTasks += task.cost_usd;
+          checkOrder(task.started_at, task.ended_at, tp, issues);
+        });
+      }
+    });
+  });
+  if (stageCount > MAX_STAGES)
+    issues.push({ path: "phases", message: `${stageCount} stages exceeds the ${MAX_STAGES} cap` });
+  if (taskCount > MAX_TASKS)
+    issues.push({ path: "phases", message: `${taskCount} tasks exceeds the ${MAX_TASKS} cap` });
+  if (running > 1)
+    issues.push({ path: "phases", message: `${running} stages are running; tldrx is single-writer` });
+  if (cursor !== null && !cursorResolves) {
+    issues.push({ path: "cursor", message: `cursor ${cursor.phase}/${cursor.stage} does not resolve to a stage` });
+  }
+  if (isRecord(doc.budget) && typeof doc.budget.spent_usd === "number") {
+    if (Math.abs(doc.budget.spent_usd - spentFromTasks) > 0.01) {
+      issues.push({
+        path: "budget.spent_usd",
+        message: `${doc.budget.spent_usd} does not match the task total ${round2(spentFromTasks)} (tolerance 0.01)`
+      });
+    }
+  }
+  return result(issues, deprecations);
+}
+function checkOrder(started, ended, path, issues) {
+  if (typeof started === "string" && typeof ended === "string" && ended < started) {
+    issues.push({ path: `${path}.ended_at`, message: "ended_at is before started_at" });
+  }
+}
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+function asRunFile(input) {
+  return input;
+}
+
+// src/core/budget/budgetView.ts
+function raiseCommand(runId, phaseId, amountUsd) {
+  return `tldrx budget raise ${phaseId} ${amountUsd.toFixed(2)} --run ${runId}`;
+}
+function shortBy(estimate, remaining) {
+  return Math.max(0.01, Math.ceil((estimate - remaining) * 100) / 100);
+}
+
+// src/core/budget/RunBudget.ts
+var ON_EXCEED = ["block", "warn"];
+var DEFAULT_WARN_AT_PCT = 80;
+var MAX_PHASES2 = 5;
+function validateRunBudget(input) {
+  const issues = [];
+  const deprecations = [];
+  const doc = asDocument(input, issues);
+  if (!doc)
+    return result(issues);
+  requireVersion(doc, issues, deprecations);
+  requireKeys(doc, ["run", "ceiling_usd", "per_agent_max_usd", "on_exceed", "phases"], "", issues);
+  requireString(doc.run, "run", issues);
+  requireNumber(doc.ceiling_usd, "ceiling_usd", issues);
+  requireNumber(doc.per_agent_max_usd, "per_agent_max_usd", issues);
+  requireEnum(doc.on_exceed, ON_EXCEED, "on_exceed", issues);
+  if (doc.warn_at_pct !== undefined) {
+    requireNumber(doc.warn_at_pct, "warn_at_pct", issues);
+    const pct = doc.warn_at_pct;
+    if (typeof pct === "number" && (pct < 1 || pct > 99)) {
+      issues.push({ path: "warn_at_pct", message: "expected 1–99" });
+    }
+  }
+  if (!requireArray(doc.phases, "phases", issues))
+    return result(issues, deprecations);
+  const phases = doc.phases;
+  if (phases.length > MAX_PHASES2) {
+    issues.push({ path: "phases", message: `${phases.length} phases exceeds the ${MAX_PHASES2} cap` });
+  }
+  let sum = 0;
+  phases.forEach((phase, i) => {
+    const path = `phases[${i}]`;
+    if (!isRecord(phase)) {
+      issues.push({ path, message: "expected a mapping" });
+      return;
+    }
+    requireKeys(phase, ["id", "ceiling_usd", "spent_usd"], path, issues);
+    requireString(phase.id, `${path}.id`, issues);
+    requireNumber(phase.ceiling_usd, `${path}.ceiling_usd`, issues);
+    requireNumber(phase.spent_usd, `${path}.spent_usd`, issues);
+    if (typeof phase.ceiling_usd === "number")
+      sum += phase.ceiling_usd;
+  });
+  if (typeof doc.ceiling_usd === "number" && sum > doc.ceiling_usd + 0.000000001) {
+    issues.push({ path: "phases", message: `phase ceilings sum to ${sum} > ceiling_usd ${doc.ceiling_usd}` });
+  }
+  return result(issues, deprecations);
+}
+function asRunBudget(input) {
+  const doc = input;
+  return {
+    version: doc.version ?? 1,
+    run: doc.run ?? "",
+    ceiling_usd: doc.ceiling_usd ?? 0,
+    per_agent_max_usd: doc.per_agent_max_usd ?? 0,
+    warn_at_pct: doc.warn_at_pct ?? DEFAULT_WARN_AT_PCT,
+    on_exceed: doc.on_exceed ?? "block",
+    phases: doc.phases ?? []
+  };
+}
+
+export { loadRunView, cursorStage, openRunViews, newestActiveRun, currentActor, nowRfc3339, validateRunBudget, asRunBudget, wouldExceed, isTerminal2 as isTerminal, isFinished, flatten, stageAt, deriveRunStatus, derivePhaseStatus, validateRunFile, asRunFile, raiseCommand, shortBy };

package/dist/hooks/chunk-t56k6146.js

@@ -0,0 +1,14 @@
+// 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 { noteDeprecations };

package/dist/hooks/chunk-t8tdv11p.js

@@ -0,0 +1,35 @@
+import {
+  toolInput
+} from "./chunk-1zwcxd3f.js";
+
+// src/hooks/lib/wouldBe.ts
+import { existsSync, readFileSync } from "node:fs";
+function wouldBeContent(payload, filePath) {
+  const input = toolInput(payload);
+  if (payload.tool_name === "Write") {
+    return typeof input.content === "string" ? { kind: "content", text: input.content } : { kind: "not-applicable", why: "Write payload carried no content" };
+  }
+  if (payload.tool_name === "Edit") {
+    const oldString = input.old_string;
+    const newString = input.new_string;
+    if (typeof oldString !== "string" || typeof newString !== "string") {
+      return { kind: "not-applicable", why: "Edit payload carried no old_string/new_string" };
+    }
+    if (!existsSync(filePath)) {
+      return { kind: "not-applicable", why: "Edit target does not exist yet" };
+    }
+    if (oldString === "") {
+      return { kind: "not-applicable", why: "Edit payload carried an empty old_string" };
+    }
+    const current = readFileSync(filePath, "utf8");
+    const at = current.indexOf(oldString);
+    if (at === -1) {
+      return { kind: "not-applicable", why: "old_string is not in the file; the Edit will fail on its own" };
+    }
+    const text = input.replace_all === true ? current.split(oldString).join(newString) : current.slice(0, at) + newString + current.slice(at + oldString.length);
+    return { kind: "content", text };
+  }
+  return { kind: "not-applicable", why: `tool ${String(payload.tool_name)} does not write files` };
+}
+
+export { wouldBeContent };