@syntax-syllogism/aloop 0.5.0

package/src/prompts.mjs

@@ -0,0 +1,54 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packagePrompts = join(dirname(fileURLToPath(import.meta.url)), '..', 'prompts');
+
+/**
+ * Load a prompt template, preferring the project's copy over the packaged one.
+ *
+ * Overriding is per-file rather than all-or-nothing: a project that only needs
+ * a different reviewer drops in `review.md` and keeps receiving improvements to
+ * every other phase.
+ */
+export async function loadTemplate(name, { projectPromptDir }) {
+  const candidates = [join(projectPromptDir, `${name}.md`), join(packagePrompts, `${name}.md`)];
+  for (const candidate of candidates) {
+    try {
+      return { path: candidate, body: await readFile(candidate, 'utf8') };
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  throw new Error(`No prompt template "${name}.md" in ${projectPromptDir} or ${packagePrompts}.`);
+}
+
+/**
+ * Substitute `{{VARIABLE}}` placeholders, failing on any that go unresolved.
+ *
+ * An unresolved placeholder reaching an agent is worse than a crash: the agent
+ * reads it as literal text and improvises around it, producing work that looks
+ * plausible and targets the wrong thing.
+ */
+export function interpolate(body, variables) {
+  const missing = new Set();
+  const filled = body.replace(/\{\{\s*([A-Z0-9_]+)\s*\}\}/g, (match, key) => {
+    const value = variables[key];
+    if (value === undefined || value === null) {
+      missing.add(key);
+      return match;
+    }
+    return String(value);
+  });
+  if (missing.size) {
+    throw new Error(`Prompt has unresolved variables: ${[...missing].sort().join(', ')}`);
+  }
+  return filled;
+}
+
+export async function renderPrompt(name, variables, options) {
+  const { path, body } = await loadTemplate(name, options);
+  return { path, prompt: interpolate(body, variables) };
+}
+
+export { packagePrompts };

package/src/state.mjs

@@ -0,0 +1,88 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Run state, persisted after every phase.
+ *
+ * The point is resumability: a run that dies in the docs phase should restart
+ * at the docs phase, not re-implement the work item. State lives next to the
+ * run's logs rather than in a session, so `--resume` works even if the run is
+ * resumed with a different engine than started it.
+ */
+export function slugFor(input) {
+  if (!input) return '';
+  return input
+    .split('/')
+    .at(-1)
+    .replace(/\.(md|txt|markdown)$/i, '')
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .toLowerCase();
+}
+
+export class RunState {
+  constructor(dir, data, readOnly = false) {
+    this.dir = dir;
+    this.data = data;
+    this.readOnly = readOnly;
+  }
+
+  static async open(runsDir, slug, seed, { readOnly = false } = {}) {
+    const dir = join(runsDir, slug);
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, 'state.json');
+    let data;
+    try {
+      data = JSON.parse(await readFile(path, 'utf8'));
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      data = {
+        startedAt: new Date().toISOString(),
+        completed: [],
+        rounds: {},
+        reviewedShas: {},
+        ...seed,
+      };
+    }
+    return new RunState(dir, data, readOnly);
+  }
+
+  get path() {
+    return join(this.dir, 'state.json');
+  }
+
+  logPath(name) {
+    return join(this.dir, `${name}.log`);
+  }
+
+  verdictPath(round) {
+    return join(this.dir, `verdict-round-${round}.json`);
+  }
+
+  isComplete(name) {
+    return this.data.completed.includes(name);
+  }
+
+  async markComplete(name, details = {}) {
+    if (!this.data.completed.includes(name)) this.data.completed.push(name);
+    this.data.phases = { ...this.data.phases, [name]: { finishedAt: new Date().toISOString(), ...details } };
+    await this.save();
+  }
+
+  async record(patch) {
+    Object.assign(this.data, patch);
+    await this.save();
+  }
+
+  /**
+   * Persist, unless this is a dry run.
+   *
+   * A dry run that recorded phases as complete would poison the next
+   * `--resume`, which would then skip work that never actually happened.
+   */
+  async save() {
+    if (this.readOnly) return;
+    this.data.updatedAt = new Date().toISOString();
+    await writeFile(this.path, `${JSON.stringify(this.data, null, 2)}\n`);
+  }
+}

package/src/verdict.mjs

@@ -0,0 +1,69 @@
+import { readFile } from 'node:fs/promises';
+
+export const APPROVED = 'APPROVED';
+export const CHANGES_REQUESTED = 'CHANGES_REQUESTED';
+
+/**
+ * Pull the JSON object out of whatever the reviewer wrote.
+ *
+ * Agents fence JSON in markdown often enough that rejecting it would be
+ * pedantic, so tolerate the fence — but tolerate nothing about the contents.
+ */
+function extractJson(text) {
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+  const candidate = (fenced ? fenced[1] : text).trim();
+  try {
+    return JSON.parse(candidate);
+  } catch (error) {
+    throw new Error(`Verdict file is not valid JSON: ${error.message}`);
+  }
+}
+
+/**
+ * Validate a verdict.
+ *
+ * This fails closed on purpose. A missing, malformed, or unrecognized verdict
+ * stalls the run rather than defaulting to either outcome: defaulting to
+ * approval ships unreviewed code, and defaulting to changes burns rounds
+ * against a reviewer that is not actually reporting.
+ */
+export function parseVerdict(text) {
+  const data = extractJson(text);
+  const verdict = String(data.verdict ?? '').toUpperCase();
+  if (![APPROVED, CHANGES_REQUESTED].includes(verdict)) {
+    throw new Error(`Verdict must be ${APPROVED} or ${CHANGES_REQUESTED}, got ${JSON.stringify(data.verdict)}.`);
+  }
+  const blocking = Array.isArray(data.blocking) ? data.blocking : [];
+  if (verdict === CHANGES_REQUESTED && blocking.length === 0) {
+    throw new Error(`Verdict is ${CHANGES_REQUESTED} but lists no blocking findings.`);
+  }
+  return {
+    verdict,
+    blocking,
+    nits: Array.isArray(data.nits) ? data.nits : [],
+    summary: typeof data.summary === 'string' ? data.summary : '',
+  };
+}
+
+export async function readVerdict(path) {
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`The review phase did not write a verdict to ${path}.`);
+    }
+    throw error;
+  }
+  return parseVerdict(text);
+}
+
+export function formatFindings(findings) {
+  if (!findings.length) return '(none)';
+  return findings
+    .map((finding, index) => {
+      const where = [finding.file, finding.line].filter(Boolean).join(':');
+      return `${index + 1}. ${where ? `${where} — ` : ''}${finding.issue ?? finding.summary ?? ''}`;
+    })
+    .join('\n');
+}