@jhlee0619/codexloop 0.1.0

package/scripts/lib/iteration.mjs

@@ -0,0 +1,484 @@
+// Single-iteration orchestration: evaluate → suggest → rank → apply → validate → record.
+//
+// This is where the six-step loop lives. `runIteration` is called either
+// synchronously by /cloop:iterate or in a loop by the background worker
+// (/cloop:start --background). It loads state from disk, runs the six steps,
+// persists state, and returns the full iteration record.
+
+import process from "node:process";
+
+import { codexCall, CodexError } from "./codex-exec.mjs";
+import { runCommand } from "./process.mjs";
+import {
+  loadState,
+  saveState,
+  writeIterationFile,
+  writeProposalFile,
+  appendProgressLog,
+  readProgressLogTail,
+  computeGoalHash
+} from "./state.mjs";
+import { recomputeWinner } from "./rank.mjs";
+import { computeQualityScore, checkStopping } from "./convergence.mjs";
+import { applyPatch, rollbackToSha } from "./apply.mjs";
+import { runValidation } from "./validate.mjs";
+
+const DEFAULT_PROPOSAL_COUNT = 3;
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function newIterationRecord(state, { dryRun }) {
+  const index = (state.iterations?.length ?? 0) + 1;
+  return {
+    index,
+    startedAt: nowIso(),
+    completedAt: null,
+    evaluate: null,
+    proposals: null,
+    ranking: null,
+    acceptedProposalId: null,
+    rejectionReasons: null,
+    apply: null,
+    validate: null,
+    qualityScore: null,
+    qualityDelta: null,
+    rationale: null,
+    confidence: null,
+    remainingIssues: null,
+    nextStep: null,
+    stopReason: null,
+    error: null,
+    codexUsage: {
+      evaluate: null,
+      suggest: null,
+      rank: null,
+      totals: { inputTokens: 0, cachedInputTokens: 0, outputTokens: 0 }
+    },
+    dryRun: !!dryRun
+  };
+}
+
+function accumulateUsage(totals, usage) {
+  if (!usage) return;
+  totals.inputTokens += usage.inputTokens ?? 0;
+  totals.cachedInputTokens += usage.cachedInputTokens ?? 0;
+  totals.outputTokens += usage.outputTokens ?? 0;
+}
+
+function gitDiffSince(cwd, sinceSha) {
+  if (!sinceSha) return "";
+  const res = runCommand("git", ["diff", `${sinceSha}..HEAD`, "--", "."], {
+    cwd,
+    maxBuffer: 32 * 1024 * 1024
+  });
+  if (res.status !== 0) return "";
+  const diff = res.stdout || "";
+  // Keep it bounded so the prompt does not blow up.
+  if (diff.length > 20_000) {
+    return `${diff.slice(0, 20_000)}\n\n... [truncated: ${diff.length - 20_000} more chars]`;
+  }
+  return diff;
+}
+
+function ensureGoalHash(state) {
+  if (!state.goal?.goalHash) {
+    state.goal.goalHash = computeGoalHash(state.goal ?? {});
+  }
+  return state.goal.goalHash;
+}
+
+function assertGoalImmutable(state, expectedHash) {
+  const currentHash = computeGoalHash(state.goal ?? {});
+  if (expectedHash && currentHash !== expectedHash) {
+    throw new Error(
+      `goal hash mismatch (expected ${expectedHash}, got ${currentHash}) — goal text may have drifted`
+    );
+  }
+}
+
+function summaryForState(iteration) {
+  return {
+    index: iteration.index,
+    startedAt: iteration.startedAt,
+    completedAt: iteration.completedAt,
+    qualityScore: iteration.qualityScore,
+    qualityDelta: iteration.qualityDelta,
+    acceptedProposalId: iteration.acceptedProposalId,
+    evaluate: iteration.evaluate
+      ? {
+          verdict: iteration.evaluate.verdict,
+          distanceFromGoal: iteration.evaluate.distanceFromGoal,
+          openIssueCount: iteration.evaluate.openIssues?.length ?? 0,
+          passingTests: iteration.evaluate.passingTests ?? null,
+          failingTests: iteration.evaluate.failingTests ?? null,
+          completionClaim: iteration.evaluate.completionClaim ?? false
+        }
+      : null,
+    validate: iteration.validate
+      ? {
+          passed: iteration.validate.passed,
+          regression: iteration.validate.regression ?? false,
+          skipped: iteration.validate.skipped ?? null
+        }
+      : null,
+    apply: iteration.apply
+      ? {
+          applied: iteration.apply.applied ?? false,
+          empty: iteration.apply.empty ?? false,
+          skipped: iteration.apply.skipped ?? null,
+          preSha: iteration.apply.preSha ?? null,
+          postSha: iteration.apply.postSha ?? null,
+          filesTouched: iteration.apply.filesTouched ?? [],
+          rolledBack: iteration.apply.rolledBack ?? false,
+          error: iteration.apply.error ?? null
+        }
+      : null,
+    ranking: iteration.ranking
+      ? {
+          winner: iteration.ranking.winner,
+          tiebreaker: iteration.ranking.tiebreaker ?? null,
+          disagreement: iteration.ranking.disagreement ?? false,
+          judgeWinnerId: iteration.ranking.judgeWinnerId ?? null
+        }
+      : null,
+    stopReason: iteration.stopReason,
+    error: iteration.error,
+    dryRun: iteration.dryRun ?? false
+  };
+}
+
+function finalizeIteration(state, iteration, { repoRoot }) {
+  iteration.completedAt = nowIso();
+
+  writeIterationFile(repoRoot, iteration, { dryRun: iteration.dryRun });
+
+  state.iterations.push(summaryForState(iteration));
+  // Budget counts dry-run too: dry-run still burns real Codex calls and time.
+  state.budget.consumed.iterations = (state.budget.consumed.iterations ?? 0) + 1;
+  const startedAtMs = state.budget.consumed.startedAtMs ?? Date.now();
+  state.budget.consumed.elapsedMs = Date.now() - startedAtMs;
+  state.convergence.scoreHistory.push(iteration.qualityScore ?? 0);
+  state.lastIterationAt = iteration.completedAt;
+
+  if (iteration.acceptedProposalId) {
+    state.accepted.push(`${iteration.index}-${iteration.acceptedProposalId}`);
+  }
+  for (const [id, reason] of Object.entries(iteration.rejectionReasons ?? {})) {
+    state.rejected.push({ id: `${iteration.index}-${id}`, reason });
+  }
+
+  if (Array.isArray(iteration.evaluate?.openIssues)) {
+    state.openIssues = iteration.evaluate.openIssues;
+  }
+
+  const applyTag = iteration.apply?.applied
+    ? "applied"
+    : iteration.apply?.empty
+      ? "empty"
+      : iteration.apply?.skipped
+        ? `skipped(${iteration.apply.skipped})`
+        : iteration.apply?.error
+          ? "fail"
+          : "none";
+  const validateTag = iteration.validate?.skipped
+    ? `skipped(${iteration.validate.skipped})`
+    : iteration.validate?.passed === true
+      ? "pass"
+      : iteration.validate?.passed === false
+        ? (iteration.validate.regression ? "fail(regression)" : "fail")
+        : "n/a";
+  appendProgressLog(
+    repoRoot,
+    `[iter ${iteration.index}${iteration.dryRun ? " DRY" : ""}] verdict=${iteration.evaluate?.verdict ?? "?"} ` +
+      `proposals=${iteration.proposals?.length ?? 0} winner=${iteration.acceptedProposalId ?? "?"} ` +
+      `apply=${applyTag} validate=${validateTag} q=${(iteration.qualityScore ?? 0).toFixed(3)} ` +
+      `(Δ ${(iteration.qualityDelta ?? 0).toFixed(3)})`
+  );
+}
+
+// Core runIteration. Loads state, runs the six steps, persists, returns.
+export async function runIteration({ repoRoot, options = {} }) {
+  let state = loadState(repoRoot);
+
+  if (state.budget.consumed.startedAtMs == null) {
+    state.budget.consumed.startedAtMs = Date.now();
+  }
+
+  const goalHash = ensureGoalHash(state);
+
+  const iteration = newIterationRecord(state, { dryRun: options.dryRun });
+
+  try {
+    assertGoalImmutable(state, goalHash);
+
+    const diffSinceSeed = gitDiffSince(repoRoot, state.goal?.seedCommit);
+    const progressTail = readProgressLogTail(repoRoot, { lines: 30 });
+
+    const recentIterations = (state.iterations ?? []).slice(-3).map((i) => ({
+      index: i.index,
+      qualityScore: i.qualityScore,
+      acceptedProposalId: i.acceptedProposalId,
+      verdict: i.evaluate?.verdict,
+      openIssueCount: i.evaluate?.openIssueCount,
+      validatePassed: i.validate?.passed,
+      stopReason: i.stopReason
+    }));
+
+    const commonVars = {
+      GOAL: state.goal?.text ?? "(unspecified)",
+      ACCEPTANCE_CRITERIA:
+        Array.isArray(state.goal?.acceptanceCriteria) && state.goal.acceptanceCriteria.length > 0
+          ? state.goal.acceptanceCriteria.map((c) => `- ${c}`).join("\n")
+          : "(none)",
+      ITERATION_INDEX: iteration.index,
+      MAX_ITERATIONS: state.budget?.maxIterations ?? 20,
+      LAST_ITERATIONS: recentIterations.length > 0 ? recentIterations : "(none)",
+      PROGRESS_LOG_TAIL: progressTail || "(none)",
+      OPEN_ISSUES:
+        Array.isArray(state.openIssues) && state.openIssues.length > 0
+          ? state.openIssues
+          : "(none)",
+      DIFF_SINCE_SEED: diffSinceSeed || "(none)",
+      CURRENT_CHECK_STATE: "(none)"
+    };
+
+    const codexOpts = {
+      cwd: repoRoot,
+      timeoutMs: options.codexTimeoutMs ?? 300_000,
+      retries: 1,
+      model: options.model ?? state.model ?? null,
+      reasoningEffort: options.reasoningEffort ?? state.reasoningEffort ?? null
+    };
+
+    // ── 1. EVALUATE ────────────────────────────────────────────────
+    const evalResult = await codexCall("evaluate", commonVars, codexOpts);
+    iteration.evaluate = evalResult.data;
+    iteration.codexUsage.evaluate = evalResult.usage;
+    accumulateUsage(iteration.codexUsage.totals, evalResult.usage);
+    state.budget.consumed.codexCalls += 1;
+
+    if ((state.openIssuesInitial ?? 0) === 0 && Array.isArray(iteration.evaluate?.openIssues)) {
+      state.openIssuesInitial = iteration.evaluate.openIssues.length;
+    }
+
+    // Early exit: reviewer declares goal met.
+    if (iteration.evaluate?.verdict === "goal-met") {
+      if (!options.dryRun) {
+        iteration.validate = await runValidation({
+          cwd: repoRoot,
+          goal: state.goal,
+          previousIteration: state.iterations[state.iterations.length - 1]
+        });
+      } else {
+        iteration.validate = { passed: null, regression: false, commands: [], skipped: "dry-run" };
+      }
+
+      const q = computeQualityScore(iteration, state);
+      iteration.qualityScore = q.score;
+      const prev = state.iterations[state.iterations.length - 1];
+      iteration.qualityDelta = iteration.qualityScore - (prev?.qualityScore ?? 0);
+
+      if (iteration.validate?.passed !== false) {
+        iteration.stopReason = "goal-met";
+        state.stopReason = "goal-met";
+        state.status = "completed";
+        state.completedAt = nowIso();
+      }
+
+      finalizeIteration(state, iteration, { repoRoot });
+      saveState(repoRoot, state);
+      return { state, iteration };
+    }
+
+    // ── 2. SUGGEST ─────────────────────────────────────────────────
+    const recentRejections = (state.rejected ?? []).slice(-5);
+    const suggestResult = await codexCall(
+      "suggest",
+      {
+        ...commonVars,
+        EVALUATION: iteration.evaluate,
+        N_PROPOSALS: options.nProposals ?? DEFAULT_PROPOSAL_COUNT,
+        RECENT_REJECTIONS: recentRejections.length > 0 ? recentRejections : "(none)"
+      },
+      codexOpts
+    );
+    iteration.codexUsage.suggest = suggestResult.usage;
+    accumulateUsage(iteration.codexUsage.totals, suggestResult.usage);
+    state.budget.consumed.codexCalls += 1;
+
+    const proposalList = Array.isArray(suggestResult.data?.proposals)
+      ? suggestResult.data.proposals
+      : [];
+    if (proposalList.length < 2) {
+      throw new Error(`suggest returned ${proposalList.length} proposal(s); minimum is 2`);
+    }
+    iteration.proposals = proposalList;
+    for (const proposal of proposalList) {
+      writeProposalFile(repoRoot, iteration.index, proposal.id, proposal);
+    }
+
+    // ── 3. RANK ────────────────────────────────────────────────────
+    const rankResult = await codexCall(
+      "rank",
+      {
+        ...commonVars,
+        EVALUATION: iteration.evaluate,
+        PROPOSALS: proposalList
+      },
+      codexOpts
+    );
+    iteration.codexUsage.rank = rankResult.usage;
+    accumulateUsage(iteration.codexUsage.totals, rankResult.usage);
+    state.budget.consumed.codexCalls += 1;
+
+    const canonical = recomputeWinner(rankResult.data, proposalList);
+    iteration.ranking = canonical;
+    iteration.acceptedProposalId = canonical.winner.id;
+    iteration.rejectionReasons = canonical.rejections;
+    iteration.confidence = canonical.winner.confidence;
+
+    if (canonical.disagreement) {
+      appendProgressLog(
+        repoRoot,
+        `[iter ${iteration.index}] judge picked ${canonical.judgeWinnerId} but runtime overrode to ${canonical.winner.id}`
+      );
+    }
+
+    const winnerProposal = proposalList.find((p) => p.id === canonical.winner.id);
+    if (!winnerProposal) {
+      throw new Error(`winner ${canonical.winner.id} not in proposals list`);
+    }
+
+    // ── 4. APPLY ───────────────────────────────────────────────────
+    if (options.dryRun || options.skipApply) {
+      iteration.apply = {
+        applied: false,
+        empty: false,
+        filesTouched: winnerProposal.filesTouched ?? [],
+        skipped: options.dryRun ? "dry-run" : "skip-apply",
+        hackingFindings: [],
+        preSha: null,
+        postSha: null
+      };
+    } else {
+      iteration.apply = await applyPatch({
+        cwd: repoRoot,
+        proposal: winnerProposal,
+        iterationIndex: iteration.index
+      });
+
+      if (!iteration.apply.applied && !iteration.apply.empty) {
+        // Try runner-up once.
+        const runnerUpEntry = canonical.scores
+          .filter((s) => s.proposalId !== canonical.winner.id)
+          .sort((a, b) => b.weighted - a.weighted)[0];
+        const runnerUp = runnerUpEntry ? proposalList.find((p) => p.id === runnerUpEntry.proposalId) : null;
+        if (runnerUp) {
+          appendProgressLog(
+            repoRoot,
+            `[iter ${iteration.index}] winner ${winnerProposal.id} failed to apply (${(iteration.apply.error ?? "").slice(0, 80)}); trying runner-up ${runnerUp.id}`
+          );
+          const runnerResult = await applyPatch({
+            cwd: repoRoot,
+            proposal: runnerUp,
+            iterationIndex: iteration.index
+          });
+          if (runnerResult.applied || runnerResult.empty) {
+            iteration.apply = runnerResult;
+            const prevWinnerId = canonical.winner.id;
+            iteration.acceptedProposalId = runnerUp.id;
+            iteration.rejectionReasons = {
+              ...(iteration.rejectionReasons ?? {}),
+              [prevWinnerId]: `apply-failed: ${(iteration.rejectionReasons?.[prevWinnerId] ?? "patch did not apply cleanly")}`
+            };
+            delete iteration.rejectionReasons[runnerUp.id];
+          }
+        }
+      }
+    }
+
+    // ── 5. VALIDATE ────────────────────────────────────────────────
+    if (options.dryRun) {
+      iteration.validate = {
+        passed: null,
+        regression: false,
+        commands: [],
+        skipped: "dry-run"
+      };
+    } else if (iteration.apply?.applied || iteration.apply?.empty) {
+      iteration.validate = await runValidation({
+        cwd: repoRoot,
+        goal: state.goal,
+        previousIteration: state.iterations[state.iterations.length - 1]
+      });
+
+      if (iteration.validate.regression && iteration.apply.applied && iteration.apply.preSha) {
+        appendProgressLog(
+          repoRoot,
+          `[iter ${iteration.index}] regression detected; rolling back to ${iteration.apply.preSha.slice(0, 8)}`
+        );
+        const rb = rollbackToSha(repoRoot, iteration.apply.preSha);
+        if (rb.ok) {
+          iteration.apply.rolledBack = true;
+        }
+      }
+    } else {
+      iteration.validate = {
+        passed: null,
+        regression: false,
+        commands: [],
+        skipped: "apply-failed"
+      };
+    }
+
+    // ── 6. RECORD + stopping ──────────────────────────────────────
+    const q = computeQualityScore(iteration, state);
+    iteration.qualityScore = q.score;
+    const prev = state.iterations[state.iterations.length - 1];
+    iteration.qualityDelta = iteration.qualityScore - (prev?.qualityScore ?? 0);
+    iteration.remainingIssues = iteration.evaluate?.openIssues?.map((i) => i.summary) ?? [];
+
+    finalizeIteration(state, iteration, { repoRoot });
+
+    const stop = checkStopping(state);
+    if (stop.shouldStop) {
+      iteration.stopReason = stop.reason;
+      state.stopReason = stop.reason;
+      state.status = stop.reason === "goal-met" ? "completed" : "paused";
+      state.completedAt = nowIso();
+      // Re-write the iteration file so the stop reason is persisted in the full record.
+      writeIterationFile(repoRoot, iteration, { dryRun: iteration.dryRun });
+      const summaryIndex = state.iterations.length - 1;
+      if (summaryIndex >= 0) {
+        state.iterations[summaryIndex] = summaryForState(iteration);
+      }
+    }
+
+    saveState(repoRoot, state);
+    return { state, iteration };
+  } catch (err) {
+    iteration.completedAt = nowIso();
+    iteration.error = err instanceof CodexError ? `${err.kind}: ${err.message}` : err.message ?? String(err);
+    state.error = {
+      kind: err instanceof CodexError ? err.kind : err.name ?? "Error",
+      message: iteration.error,
+      iteration: iteration.index
+    };
+    try {
+      writeIterationFile(repoRoot, iteration, { dryRun: iteration.dryRun });
+      // Only append a summary row if we have not already.
+      if (!state.iterations.some((i) => i.index === iteration.index)) {
+        state.iterations.push(summaryForState(iteration));
+        state.budget.consumed.codexCalls = state.budget.consumed.codexCalls ?? 0;
+      }
+      appendProgressLog(
+        repoRoot,
+        `[iter ${iteration.index}] ERROR ${iteration.error}`
+      );
+      saveState(repoRoot, state);
+    } catch {}
+    throw err;
+  }
+}

package/scripts/lib/process.mjs

@@ -0,0 +1,164 @@
+// Process utilities: synchronous commands, background worker spawning, PID
+// liveness checks, and graceful termination.
+//
+// Shape is deliberately close to what the codex plugin ships so code review
+// across the two plugins stays cheap. Nothing here is imported from there.
+
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import process from "node:process";
+
+export function runCommand(command, args = [], options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    env: options.env ?? process.env,
+    encoding: "utf8",
+    input: options.input,
+    stdio: options.stdio ?? "pipe",
+    timeout: options.timeoutMs,
+    maxBuffer: options.maxBuffer ?? 64 * 1024 * 1024,
+    shell: options.shell ?? (process.platform === "win32")
+  });
+  return {
+    command,
+    args,
+    status: result.status ?? 0,
+    signal: result.signal ?? null,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    error: result.error ?? null
+  };
+}
+
+export function runCommandChecked(command, args = [], options = {}) {
+  const result = runCommand(command, args, options);
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(formatCommandFailure(result));
+  }
+  return result;
+}
+
+export function binaryAvailable(command, versionArgs = ["--version"], options = {}) {
+  const result = runCommand(command, versionArgs, options);
+  if (result.error && result.error.code === "ENOENT") {
+    return { available: false, detail: "not found" };
+  }
+  if (result.error) {
+    return { available: false, detail: result.error.message };
+  }
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || "").trim() || `exit ${result.status}`;
+    return { available: false, detail };
+  }
+  return { available: true, detail: (result.stdout || result.stderr || "ok").trim() };
+}
+
+// Spawn a detached Node worker that survives the parent process exiting.
+// Stdout/stderr are redirected to `logFile` (append mode). Returns the child PID.
+export function spawnDetached(scriptPath, args, options = {}) {
+  const { cwd, logFile, env } = options;
+  if (!logFile) {
+    throw new Error("spawnDetached requires options.logFile");
+  }
+  const out = fs.openSync(logFile, "a");
+  try {
+    const child = spawn(process.execPath, [scriptPath, ...args], {
+      cwd,
+      detached: true,
+      stdio: ["ignore", out, out],
+      env: { ...process.env, ...(env ?? {}) }
+    });
+    child.unref();
+    return child.pid ?? null;
+  } finally {
+    // Child has inherited its own fd; parent can release this handle now.
+    try {
+      fs.closeSync(out);
+    } catch {}
+  }
+}
+
+export function isProcessAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means the process exists but we can't signal it. Treat as alive
+    // so we err on the side of "do not stomp on someone else's process".
+    return err.code === "EPERM";
+  }
+}
+
+// Send a signal to a PID. Tries the process group first (`-pid`) so we
+// take down any children the worker may have spawned; falls back to the
+// single PID if the group send fails.
+export function terminateProcess(pid, signal = "SIGTERM") {
+  if (!Number.isFinite(pid) || pid <= 0) {
+    return { delivered: false, reason: "invalid-pid", method: null };
+  }
+
+  const tryKill = (target) => {
+    try {
+      process.kill(target, signal);
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, err };
+    }
+  };
+
+  const groupResult = tryKill(-pid);
+  if (groupResult.ok) {
+    return { delivered: true, method: "process-group", signal };
+  }
+
+  if (groupResult.err?.code === "ESRCH") {
+    // No group under that leader (or nothing running). Try the raw PID.
+    const directResult = tryKill(pid);
+    if (directResult.ok) {
+      return { delivered: true, method: "process", signal };
+    }
+    if (directResult.err?.code === "ESRCH") {
+      return { delivered: false, reason: "not-running", method: "process", signal };
+    }
+    throw directResult.err;
+  }
+
+  if (groupResult.err?.code === "EPERM") {
+    return { delivered: false, reason: "not-permitted", method: "process-group", signal };
+  }
+
+  // Unknown failure mode — try direct as a last resort.
+  const directResult = tryKill(pid);
+  if (directResult.ok) {
+    return { delivered: true, method: "process", signal };
+  }
+  throw directResult.err ?? groupResult.err;
+}
+
+export function formatCommandFailure(result) {
+  const head = `${result.command} ${result.args.join(" ")}`.trim();
+  const parts = [head];
+  if (result.signal) {
+    parts.push(`signal=${result.signal}`);
+  } else {
+    parts.push(`exit=${result.status}`);
+  }
+  const stderr = (result.stderr || "").trim();
+  const stdout = (result.stdout || "").trim();
+  if (stderr) {
+    parts.push(stderr);
+  } else if (stdout) {
+    parts.push(stdout);
+  }
+  return parts.join(": ");
+}
+
+export async function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/scripts/lib/prompts.mjs

@@ -0,0 +1,53 @@
+// Prompt template loader + interpolator.
+//
+// Templates live at <plugin-root>/prompts/<name>.md and use {{UPPER_SNAKE}}
+// placeholders. The loader is intentionally dumb — no conditionals, no loops,
+// no arithmetic. If a placeholder is missing from `vars`, it is substituted
+// with "(missing:KEY)" so the prompt stays syntactically valid and any bug in
+// the caller shows up clearly in the rendered prompt rather than silently.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = path.resolve(SCRIPT_DIR, "..", "..");
+
+export function getPluginRoot() {
+  return PLUGIN_ROOT;
+}
+
+export function getPromptPath(name) {
+  const fileName = name.endsWith(".md") ? name : `${name}.md`;
+  return path.join(PLUGIN_ROOT, "prompts", fileName);
+}
+
+export function getSchemaPath(name) {
+  const fileName = name.endsWith(".json") ? name : `${name}.schema.json`;
+  return path.join(PLUGIN_ROOT, "schemas", fileName);
+}
+
+export function loadPromptTemplate(name) {
+  return fs.readFileSync(getPromptPath(name), "utf8");
+}
+
+export function interpolate(template, vars) {
+  return template.replace(/\{\{([A-Z0-9_]+)\}\}/g, (_match, key) => {
+    if (!(key in vars)) {
+      return `(missing:${key})`;
+    }
+    const value = vars[key];
+    if (value == null) return "(none)";
+    if (typeof value === "string") return value;
+    if (typeof value === "number" || typeof value === "boolean") return String(value);
+    try {
+      return JSON.stringify(value, null, 2);
+    } catch {
+      return String(value);
+    }
+  });
+}
+
+export function renderPrompt(name, vars) {
+  return interpolate(loadPromptTemplate(name), vars);
+}