@syntax-syllogism/aloop 0.5.3 → 0.6.0

package/src/policy.mjs

@@ -0,0 +1,63 @@
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parsePullRequestDescription } from './publish.mjs';
+import { APPROVED } from './verdict.mjs';
+
+export function hasPostcondition(phase, name) {
+  return phase.postconditions?.includes(name) ?? false;
+}
+
+export function phaseIsSkippable(phase) {
+  return phase.optional && !phase.verdict && phase.kind !== 'gate';
+}
+
+export async function codePhasePostcondition(phase, ctx, {
+  hasFindings = true,
+  headBefore = null,
+  round = null,
+} = {}) {
+  if (ctx.dryRun) return null;
+  const logPath = ctx.state.logPath(phase.name);
+  if (hasPostcondition(phase, 'clean-tree') && await ctx.git.status()) {
+    return `${phase.name} left uncommitted changes; the reviewer inspects base...HEAD and will not see them. Commit the work. Check ${logPath}.`;
+  }
+  if (hasPostcondition(phase, 'pr-description-valid')) {
+    try {
+      parsePullRequestDescription(await readFile(join(ctx.state.dir, 'pr.md'), 'utf8'));
+    } catch (error) {
+      const reason = error.code === 'ENOENT' ? 'file is missing' : error.message;
+      return `${phase.name} did not produce a valid pr.md (${reason}). Check ${logPath}.`;
+    }
+  }
+  const requiresHeadAdvance = hasPostcondition(phase, 'head-advanced');
+  const permitsRebuttal = hasPostcondition(phase, 'head-advanced-or-rebuttal');
+  const requiresHeadUnchanged = hasPostcondition(phase, 'head-unchanged');
+  const headChanged = (requiresHeadAdvance || permitsRebuttal || requiresHeadUnchanged)
+    && headBefore !== null && headBefore !== (await ctx.git.revParse());
+  if (requiresHeadAdvance && !headChanged) return `${phase.name} produced no commit. Commit the work. Check ${logPath}.`;
+  if (requiresHeadUnchanged && headChanged) return `${phase.name} changed HEAD from ${headBefore} to ${await ctx.git.revParse()}; it may only write the PR description. Check ${logPath}.`;
+  if (!permitsRebuttal || headChanged || !hasFindings) return null;
+  const rebuttalPath = round === null ? null : join(ctx.state.dir, `response-round-${round}.md`);
+  try {
+    if (rebuttalPath && (await stat(rebuttalPath)).isFile()) return null;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  return `${phase.name} produced no fix commit and no rebuttal recorded. Commit the fix or record a rebuttal. Check ${logPath}.`;
+}
+
+function latestApprovedReview(state) {
+  const index = state.manifest.entries.findLastIndex((entry) => entry.role === 'verdict' && entry.status !== 'skipped');
+  const entry = index === -1 ? null : state.manifest.entries[index];
+  if (entry?.status !== 'completed' || entry.verdict?.verdict !== APPROVED || typeof entry.verdict.sha !== 'string') return null;
+  return { index, sha: entry.verdict.sha };
+}
+
+export function publishingAttestation(state, currentSha) {
+  const approved = latestApprovedReview(state);
+  if (!approved) return { approvedSha: null, currentSha, reason: `current HEAD ${currentSha} has no completed approval from a review phase` };
+  if (approved.sha !== currentSha) return { approvedSha: approved.sha, currentSha, reason: `current HEAD ${currentSha} does not match the approved review SHA ${approved.sha}` };
+  const gatePassed = state.manifest.entries.slice(0, approved.index).some((entry) => entry.role === 'gate' && entry.status === 'completed' && entry.outputSha === approved.sha);
+  if (!gatePassed) return { approvedSha: approved.sha, currentSha, reason: `approved review SHA ${approved.sha} has no passing gate receipt preceding its review` };
+  return null;
+}

package/src/publish.mjs

@@ -0,0 +1,183 @@
+import { readFile, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { runCommand } from './command.mjs';
+import { GitFacade } from './git.mjs';
+import { gitlabBackend } from './backends/gitlab.mjs';
+
+const PR_FIELDS = 'url,baseRefName,headRefOid,isDraft,number';
+
+export class PublishError extends Error {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = 'PublishError';
+  }
+}
+
+export function parsePullRequestDescription(contents) {
+  const match = /^Title:\s*(.+?)\r?\n\r?\n([\s\S]*?)\s*$/i.exec(contents);
+  if (!match) {
+    throw new PublishError('PR description must start with "Title: <one-line title>", followed by a blank line and body.');
+  }
+  const title = match[1].trim();
+  const body = match[2].trim();
+  if (!title) throw new PublishError('PR description title must not be empty.');
+  if (!body) throw new PublishError('PR description body must not be empty.');
+  return { title, body };
+}
+
+export function githubBackend({ cwd, git = new GitFacade(cwd), runner = runCommand, env } = {}) {
+  const repositories = new Map();
+
+  async function resolveRepository(remote) {
+    if (!repositories.has(remote)) {
+      const remoteUrl = await git.remoteUrl(remote);
+      const match = /^(?:https?:\/\/github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)([^/]+\/[^/]+?)(?:\.git)?\/?$/i.exec(remoteUrl);
+      if (!match) {
+        throw new PublishError(`Configured remote ${remote} does not point to a GitHub repository.`);
+      }
+      repositories.set(remote, match[1]);
+    }
+    return repositories.get(remote);
+  }
+
+  async function run(args) {
+    try {
+      return await runner('gh', args, { cwd, ...(env ? { env } : {}) });
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new PublishError('GitHub publishing requires the `gh` CLI, but it is not installed.', { cause: error });
+      }
+      throw new PublishError(error.output?.trim() || error.message, { cause: error });
+    }
+  }
+
+  async function runPullRequest(remote, args) {
+    return run([...args, '--repo', await resolveRepository(remote)]);
+  }
+
+  return {
+    async precheck({ remote }) {
+      try {
+        await resolveRepository(remote);
+        await run(['auth', 'status']);
+      } catch (error) {
+        throw new PublishError(`GitHub publishing precheck failed: ${error.message}`, { cause: error });
+      }
+    },
+    async view({ remote, branch }) {
+      try {
+        const result = await runPullRequest(remote, ['pr', 'view', branch, '--json', PR_FIELDS]);
+        return JSON.parse(result.stdout);
+      } catch (error) {
+        // `gh pr view` uses exit 1 when a branch has no PR. Authentication and
+        // executable failures were already checked by precheck and remain
+        // errors at this point.
+        if (error.cause?.output?.toLowerCase().includes('no pull requests found')) return null;
+        if (error.message.toLowerCase().includes('no pull requests found')) return null;
+        throw new PublishError(`Unable to inspect pull request for ${branch}: ${error.message}`, { cause: error });
+      }
+    },
+    async create({ remote, base, branch, title, bodyFilePath, draft }) {
+      const args = ['pr', 'create', '--base', base, '--head', branch, '--title', title, '--body-file', bodyFilePath];
+      if (draft) args.push('--draft');
+      await runPullRequest(remote, args);
+    },
+    async update({ remote, branch, title, bodyFilePath }) {
+      await runPullRequest(remote, ['pr', 'edit', branch, '--title', title, '--body-file', bodyFilePath]);
+    },
+  };
+}
+
+function resolveBackend(backend, cwd, git, env) {
+  if (backend === undefined || backend === null || backend === 'github') return githubBackend({ cwd, git, env });
+  if (backend === 'gitlab') return gitlabBackend({ cwd, git, env });
+  if (typeof backend === 'object' && backend !== null) {
+    if (env !== undefined) {
+      throw new PublishError('Hermetic publishing does not support in-process custom backends; use the built-in GitHub backend or disable hermetic publishing.');
+    }
+    return backend;
+  }
+  throw new PublishError(`Unsupported publish backend "${backend}".`);
+}
+
+function assertVerifiedPullRequest(pullRequest, { base, branch, localSha, draft }) {
+  if (!pullRequest || typeof pullRequest !== 'object') {
+    throw new PublishError(`No pull request exists for branch ${branch} after publishing.`);
+  }
+  if (pullRequest.baseRefName !== base) {
+    throw new PublishError(`Pull request base ${pullRequest.baseRefName ?? '(none)'} does not match configured base ${base}.`);
+  }
+  if (pullRequest.headRefOid?.toLowerCase() !== localSha.toLowerCase()) {
+    throw new PublishError(`Pull request head SHA ${pullRequest.headRefOid ?? '(none)'} does not match approved SHA ${localSha}.`);
+  }
+  if (pullRequest.isDraft !== draft) {
+    throw new PublishError(`Pull request draft state ${String(pullRequest.isDraft)} does not match configured draft state ${String(draft)}.`);
+  }
+  if (typeof pullRequest.url !== 'string' || !pullRequest.url) {
+    throw new PublishError('Pull request verification returned no URL.');
+  }
+  if (!Number.isInteger(pullRequest.number)) {
+    throw new PublishError('Pull request verification returned no number.');
+  }
+}
+
+/**
+ * Push an attested branch and create or update exactly one verified PR.
+ *
+ * Git is passed in as a facade and the backend is a small port. The default
+ * backend is GitHub's `gh` CLI; other remotes can supply the same precheck,
+ * view, create, and update operations without changing this use case.
+ */
+export async function publish({
+  git,
+  remote,
+  branch,
+  base,
+  prBodyPath,
+  draft = true,
+  backend = 'github',
+  approvedSha = null,
+  env,
+}) {
+  if (!git || typeof git.push !== 'function' || typeof git.lsRemote !== 'function') {
+    throw new PublishError('Publish requires a GitFacade with push and lsRemote operations.');
+  }
+  if (!prBodyPath) throw new PublishError('Publish requires a PR description path.');
+
+  const selectedBackend = resolveBackend(backend, git.cwd, git, env);
+  for (const operation of ['precheck', 'view', 'create', 'update']) {
+    if (typeof selectedBackend[operation] !== 'function') {
+      throw new PublishError(`Publish backend is missing its ${operation} operation.`);
+    }
+  }
+  await selectedBackend.precheck({ remote, branch, base });
+
+  const localSha = approvedSha ?? await git.revParse();
+  const description = parsePullRequestDescription(await readFile(prBodyPath, 'utf8'));
+  const bodyFilePath = join(dirname(prBodyPath), '.pr-body.md');
+  await writeFile(bodyFilePath, `${description.body}\n`, 'utf8');
+  try {
+    await git.push(remote, branch, { setUpstream: true, ...(env ? { env } : {}) });
+    const remoteSha = await git.lsRemote(remote, branch, env ? { env } : {});
+    if (remoteSha.toLowerCase() !== localSha.toLowerCase()) {
+      throw new PublishError(`Remote branch ${remote}/${branch} SHA ${remoteSha} does not match approved SHA ${localSha}.`);
+    }
+
+    const existing = await selectedBackend.view({ remote, branch, base });
+    if (existing) {
+      await selectedBackend.update({ remote, branch, base, title: description.title, body: description.body, bodyFilePath, draft });
+    } else {
+      await selectedBackend.create({ remote, branch, base, title: description.title, body: description.body, bodyFilePath, draft });
+    }
+    const pullRequest = await selectedBackend.view({ remote, branch, base });
+    assertVerifiedPullRequest(pullRequest, { base, branch, localSha, draft });
+    return {
+      localSha,
+      remoteSha,
+      created: !existing,
+      pullRequest,
+    };
+  } finally {
+    await unlink(bodyFilePath).catch(() => {});
+  }
+}

package/src/reporter.mjs

@@ -0,0 +1,102 @@
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+
+export function log(message) {
+  console.log(message);
+}
+
+export function banner(text) {
+  log(`\n── ${text} ${'─'.repeat(Math.max(0, 60 - text.length))}`);
+}
+
+export function describeAgent(agent) {
+  return `${agent.name}${agent.model ? ` model=${agent.model}` : ''}${agent.effort ? ` effort=${agent.effort}` : ''}`;
+}
+
+export function formatPhase(phase) {
+  const detail = phase.rounds ? ` (${phase.rounds} round${phase.rounds === 1 ? '' : 's'}, ${phase.verdict})` : '';
+  return `  ✓ ${phase.name}${detail}`;
+}
+
+export function openTerminalInput({ platform = process.platform, input = process.stdin, createInput = createReadStream } = {}) {
+  if (platform === 'win32' && input.isTTY) return Promise.resolve(input);
+  const terminalPath = platform === 'win32' ? '\\\\.\\CONIN$' : '/dev/tty';
+  return new Promise((resolveInput, rejectInput) => {
+    const terminalInput = createInput(terminalPath);
+    const onOpen = () => {
+      terminalInput.off('error', onError);
+      resolveInput(terminalInput);
+    };
+    const onError = (error) => {
+      terminalInput.off('open', onOpen);
+      terminalInput.destroy();
+      rejectInput(error);
+    };
+    terminalInput.once('open', onOpen);
+    terminalInput.once('error', onError);
+  });
+}
+
+export async function ensureConfirmationAvailable(input, terminalOpener) {
+  if (input || process.stdin.isTTY) return;
+  let terminalInput;
+  try {
+    terminalInput = await terminalOpener();
+  } catch {
+    throw new Error('no terminal available to confirm phases; re-run with --yes to run unattended');
+  }
+  if (terminalInput !== process.stdin) terminalInput.destroy();
+}
+
+export async function confirm(question, { input = null, terminalOpener = openTerminalInput } = {}) {
+  let confirmationInput = input;
+  let closeInput = false;
+  if (!confirmationInput) {
+    if (process.stdin.isTTY) {
+      confirmationInput = process.stdin;
+    } else {
+      try {
+        confirmationInput = await terminalOpener();
+      } catch {
+        throw new Error('no terminal available to confirm phases; re-run with --yes to run unattended');
+      }
+      closeInput = confirmationInput !== process.stdin;
+    }
+  }
+  const rl = createInterface({ input: confirmationInput, output: process.stdout });
+  try {
+    const answer = await rl.question(`${question} [Y/n/q] `);
+    const normalized = answer.trim().toLowerCase();
+    if (normalized === 'q') return 'quit';
+    return normalized === '' || normalized === 'y' ? 'yes' : 'skip';
+  } finally {
+    rl.close();
+    if (closeInput) confirmationInput.destroy();
+  }
+}
+
+export function report(summary, formatFindings) {
+  banner('summary');
+  for (const phase of summary.phases) {
+    log(formatPhase(phase));
+  }
+  if (!summary.stalled) {
+    log(`\nPipeline finished. Branch ${summary.branch} is ready.`);
+    if (summary.prUrl) log(`Pull request: ${summary.prUrl}`);
+    log(`Logs: ${summary.runDir}`);
+    return;
+  }
+  log(`\n  ✗ stalled in "${summary.stalled.phase}": ${summary.stalled.reason}`);
+  if (summary.stalled.findings?.length) {
+    log(`\nOutstanding blocking findings:\n${formatFindings(summary.stalled.findings)}`);
+  }
+  if (summary.stalled.output) log(`\n${summary.stalled.output.trim().split('\n').slice(-20).join('\n')}`);
+  log(`\nWorktree: ${summary.worktree}`);
+  log(`Logs:     ${summary.runDir}`);
+  const resumeArgs = [`--name ${summary.task}`];
+  if (summary.taskFile && summary.taskFile !== `${summary.runDir}/task.md`) {
+    resumeArgs.push(`--task-file ${summary.taskFile}`);
+  }
+  log(`Resume:   aloop ${resumeArgs.join(' ')} --resume`);
+  process.exitCode = 1;
+}