@almightygpt/core 0.2.0

package/src/review/write.ts

@@ -0,0 +1,208 @@
+/**
+ * Write the human-facing review file at docs/<reviewer>-reviews/<topic>.md.
+ *
+ * The topic-named file overwrites on re-run; audit history is preserved by
+ * git. Before writing, the path is checked against `git status --short` —
+ * if dirty, we refuse to overwrite unless `force` is set.
+ *
+ * The orchestrator wraps the Reviewer's raw markdown in a small header
+ * (metadata) and footer (cost/latency + appendix pointers) so the file is
+ * self-contained without depending on the run folder.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { assertSafeToWrite } from "../git/status.js";
+
+export class ReviewFileExistsError extends Error {
+  override readonly name = "ReviewFileExistsError";
+  constructor(message: string, public readonly path: string) {
+    super(message);
+  }
+}
+
+export interface WriteReviewFileOptions {
+  repoRoot: string;
+  reviewsDir: string;
+  topic: string;
+  reviewerName: string;
+  reviewerProvider: string;
+  modelUsed: string;
+  /** The Reviewer's raw markdown output. */
+  body: string;
+  /** Cost/latency to render in the footer. */
+  metrics: {
+    tokensIn: number;
+    tokensOut: number;
+    costUsd: number;
+    latencyMs: number;
+  };
+  /** Optional run-folder relative path for the appendix pointer. */
+  runFolder?: string;
+  /** Optional shallow-review warning to prefix at the top of the file. */
+  shallowWarning?: string;
+  force?: boolean;
+}
+
+export interface WrittenReviewFile {
+  path: string;
+  bytes: number;
+}
+
+export async function writeHumanReviewFile(
+  opts: WriteReviewFileOptions,
+): Promise<WrittenReviewFile> {
+  const safeTopic = sanitizeTopic(opts.topic);
+  const relPath = join(opts.reviewsDir, `${safeTopic}.md`);
+  const absPath = join(opts.repoRoot, relPath);
+
+  // Defensive default: never silently overwrite an existing review file.
+  // Even a clean (committed) file should require explicit --force, because
+  // accidental topic collisions are easy and the user's previous review may
+  // be the answer they wanted to keep on top. Git history preserves the old
+  // version when --force is used, so no data is truly lost.
+  if (existsSync(absPath) && !opts.force) {
+    // Still run the git-status check so callers get a richer dirty-file
+    // message when applicable; falls through to the existence error below.
+    await assertSafeToWrite(opts.repoRoot, relPath, false);
+    throw new ReviewFileExistsError(
+      `Refusing to overwrite ${relPath}. Pass --force to overwrite (the ` +
+        `previous version remains in git history). Alternatively pick a ` +
+        `different --topic to keep both reviews.`,
+      relPath,
+    );
+  }
+
+  // When --force is set, we still want the dirty-file check unless the user
+  // also passed it explicitly; preserve assertSafeToWrite's prior behavior.
+  await assertSafeToWrite(opts.repoRoot, relPath, opts.force);
+
+  await mkdir(dirname(absPath), { recursive: true });
+
+  const content = renderReviewMarkdown(opts);
+  await writeFile(absPath, content, "utf8");
+
+  return { path: relPath, bytes: content.length };
+}
+
+function sanitizeTopic(topic: string): string {
+  // Allow letters, digits, dot, dash, underscore. Replace everything else
+  // with a single dash. Trim leading/trailing dashes. Lowercase.
+  const cleaned = topic
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!cleaned) {
+    throw new Error(
+      `Topic "${topic}" produced an empty sanitized name. Pick a topic with ` +
+        `at least one alphanumeric character.`,
+    );
+  }
+  return cleaned;
+}
+
+function renderReviewMarkdown(opts: WriteReviewFileOptions): string {
+  const now = new Date().toISOString();
+  const cost = opts.metrics.costUsd.toFixed(4);
+  const headerLines = [
+    `# Review: ${opts.topic}`,
+    "",
+    `> Reviewer: \`${opts.reviewerName}\` (${opts.reviewerProvider}, ${opts.modelUsed})  `,
+    `> Generated: ${now}  `,
+    `> Tokens: ${opts.metrics.tokensIn} in / ${opts.metrics.tokensOut} out  `,
+    `> Cost: $${cost} USD  `,
+    `> Latency: ${(opts.metrics.latencyMs / 1000).toFixed(2)}s  `,
+    opts.runFolder ? `> Run folder: \`${opts.runFolder}\`  ` : "",
+    "",
+  ].filter((line, i, arr) => !(line === "" && arr[i - 1] === ""));
+
+  const sections: string[] = [headerLines.join("\n")];
+
+  if (opts.shallowWarning) {
+    sections.push(
+      [
+        "> ⚠️  **SHALLOW REVIEW WARNING**",
+        ">",
+        `> ${opts.shallowWarning}`,
+        ">",
+        "> Consider re-running with a different reviewer or model.",
+        "",
+      ].join("\n"),
+    );
+  }
+
+  // Defend against models that emit orchestrator-owned sections despite
+  // the prompt asking them not to. Each helper is idempotent.
+  let cleanBody = opts.body.trim();
+  cleanBody = stripModelH1(cleanBody, opts.topic);
+  cleanBody = stripOrchestratorSections(cleanBody);
+  sections.push(cleanBody);
+
+  // Appendix is the orchestrator's responsibility — keeps the model from
+  // emitting a placeholder it doesn't have the data to fill.
+  if (opts.runFolder) {
+    sections.push(
+      [
+        "",
+        "## Appendix: Raw Outputs",
+        "",
+        `- Run folder: \`${opts.runFolder}/\``,
+        `- Worker output (if applicable): \`${opts.runFolder}/outputs/worker.md\``,
+        `- Reviewer output (raw): \`${opts.runFolder}/outputs/reviewer.md\``,
+        `- Context manifest: \`${opts.runFolder}/context-manifest.json\``,
+        `- Input (redacted): \`${opts.runFolder}/input.md\``,
+        `- Run metadata: \`${opts.runFolder}/run.json\``,
+      ].join("\n"),
+    );
+  }
+
+  sections.push(
+    [
+      "",
+      "---",
+      `_Generated by AlmightyGPT. Edit the human-facing sections (Human Decision, notes); the rest will be overwritten on next run._`,
+    ].join("\n"),
+  );
+
+  return sections.join("\n");
+}
+
+/**
+ * Strip an `# Review:` (or similar) H1 the model emitted at the top of its
+ * response. The prompt explicitly tells the model not to do this, but we
+ * defend against backslide so the file never has two H1s.
+ */
+function stripModelH1(body: string, topic: string): string {
+  const lines = body.split("\n");
+  // Drop any leading H1 line and the blank line that may follow.
+  while (lines.length > 0) {
+    const line = lines[0]!;
+    if (/^#\s+/i.test(line)) {
+      lines.shift();
+      // Also drop a single immediately-following blank line.
+      if (lines.length > 0 && lines[0]!.trim() === "") lines.shift();
+      continue;
+    }
+    break;
+  }
+  // Reference topic to discourage `noUnusedParameters` complaints and
+  // make future logic that wants to match topic-specific H1s straightforward.
+  void topic;
+  return lines.join("\n");
+}
+
+/**
+ * Strip any orchestrator-owned sections the model emitted: Cost and Latency,
+ * and Appendix: Raw Outputs. The orchestrator emits both from real data; if
+ * the model emits placeholder versions, drop them so the file is clean.
+ *
+ * Sections are matched at `## ` level, case-insensitive on the title text,
+ * and span until the next `## ` heading or end-of-string.
+ */
+function stripOrchestratorSections(body: string): string {
+  const sectionPattern =
+    /\n##\s+(?:Cost\s+and\s+Latency|Appendix(?::\s+Raw\s+Outputs)?)\s*\n[\s\S]*?(?=\n##\s|\n?$)/gi;
+  return body.replace(sectionPattern, "").trimEnd();
+}

package/src/runs/decide.ts

@@ -0,0 +1,153 @@
+/**
+ * Record a human decision on a completed review.
+ *
+ * Updates two places:
+ *   1. The human review file (docs/<reviewer>-reviews/<topic>.md): the
+ *      `## Human Decision` section gets a structured body (status,
+ *      decidedBy, decidedAt, note). Other sections are left alone.
+ *   2. The run's run.json: `decision` field is set with the same content.
+ *
+ * If the run.json's `reviewPath` is missing, the function falls back to
+ * computing `docs/<reviewer>-reviews/<topic>.md` from `topic` and the
+ * config's reviewsDir.
+ */
+
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { writeRunMetadata } from "./folder.js";
+import type {
+  DecisionStatus,
+  HumanDecision,
+  RunMetadata,
+} from "./types.js";
+
+export interface RecordDecisionOptions {
+  repoRoot: string;
+  /** Parsed run metadata loaded by the caller. */
+  meta: RunMetadata;
+  /** Absolute path to the run folder containing run.json. */
+  runFolderAbs: string;
+  /** Decision status. */
+  status: DecisionStatus;
+  /** Optional one-paragraph note. */
+  note?: string;
+  /** Optional decider identity (defaults to undefined). */
+  decidedBy?: string;
+  /** Override the auto-detected review file path. */
+  reviewPath?: string;
+  /**
+   * No-op flag preserved for forward compatibility. recordDecision only
+   * rewrites the "## Human Decision" section; other content is preserved,
+   * so a git-status safety check is not needed here. Was previously used
+   * to bypass an assertSafeToWrite check that proved too strict in
+   * practice (review files are routinely untracked right after a review
+   * run completes).
+   */
+  force?: boolean;
+}
+
+export interface RecordDecisionResult {
+  reviewPath: string;
+  runJsonUpdated: boolean;
+  decision: HumanDecision;
+}
+
+const DECISION_SECTION_HEADER = "## Human Decision";
+
+export async function recordDecision(
+  opts: RecordDecisionOptions,
+): Promise<RecordDecisionResult> {
+  const reviewPath =
+    opts.reviewPath ?? opts.meta.reviewPath ?? null;
+  if (!reviewPath) {
+    throw new Error(
+      `Run ${opts.meta.id} has no reviewPath in run.json and no --review-path override was supplied.`,
+    );
+  }
+
+  const reviewAbs = join(opts.repoRoot, reviewPath);
+  if (!existsSync(reviewAbs)) {
+    throw new Error(
+      `Review file not found at ${reviewPath}. Did the review run complete successfully?`,
+    );
+  }
+
+  // No git-status safety check: recordDecision only rewrites the
+  // "## Human Decision" section. All other content (Worker plan summary,
+  // Reviewer findings, the reader's hand-written notes) is preserved
+  // verbatim by updateDecisionSection. Adding a dirty-file refusal here
+  // breaks the natural workflow where users `decide` immediately after
+  // a review run, before committing the freshly-written review file.
+
+  const decision: HumanDecision = {
+    status: opts.status,
+    decidedAt: new Date().toISOString(),
+  };
+  if (opts.note) decision.note = opts.note;
+  if (opts.decidedBy) decision.decidedBy = opts.decidedBy;
+
+  const original = await readFile(reviewAbs, "utf8");
+  const updated = updateDecisionSection(original, decision);
+  await writeFile(reviewAbs, updated, "utf8");
+
+  const updatedMeta: RunMetadata = { ...opts.meta, decision };
+  await writeRunMetadata(opts.runFolderAbs, updatedMeta);
+
+  return {
+    reviewPath,
+    runJsonUpdated: true,
+    decision,
+  };
+}
+
+function renderDecisionBody(d: HumanDecision): string {
+  const lines: string[] = [
+    "",
+    `**Status:** ${d.status}`,
+    `**Decided at:** ${d.decidedAt}`,
+  ];
+  if (d.decidedBy) lines.push(`**Decided by:** ${d.decidedBy}`);
+  if (d.note) {
+    lines.push("");
+    lines.push(d.note);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Replace the body of the "## Human Decision" section (or append the section
+ * if it's missing). Everything between the header and the next `## ` (or end
+ * of file) is replaced with the rendered decision body.
+ */
+function updateDecisionSection(
+  content: string,
+  decision: HumanDecision,
+): string {
+  const body = renderDecisionBody(decision);
+  const headerRegex = /^## Human Decision\s*$/m;
+  const match = content.match(headerRegex);
+
+  if (!match) {
+    // Append a new section. Make sure the file ends with a newline first.
+    const sep = content.endsWith("\n") ? "" : "\n";
+    return `${content}${sep}\n${DECISION_SECTION_HEADER}\n${body}`;
+  }
+
+  const headerIdx = match.index!;
+  const afterHeader = headerIdx + match[0].length;
+
+  // Find the next `## ` heading (or end of file).
+  const nextHeading = content.slice(afterHeader).search(/\n## /);
+  const replaceTo =
+    nextHeading === -1 ? content.length : afterHeader + nextHeading;
+
+  return (
+    content.slice(0, afterHeader) +
+    "\n" +
+    body.trimEnd() +
+    "\n" +
+    content.slice(replaceTo)
+  );
+}

package/src/runs/folder.ts

@@ -0,0 +1,137 @@
+/**
+ * Create and populate run folders at .almightygpt/runs/<id>/.
+ *
+ * Layout:
+ *   <id>/
+ *     run.json
+ *     input.md
+ *     context-manifest.json
+ *     outputs/
+ *       worker.md     (when Worker stage runs — task #16)
+ *       reviewer.md
+ *     logs/
+ *       orchestrator.log  (later)
+ *
+ * The id format is <YYYY-MM-DD-HHmmss>-<topic-slug>-<4-char-random> to keep
+ * two concurrent runs in the same second from colliding.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { execa } from "execa";
+import type { RunMetadata } from "./types.js";
+
+export interface CreateRunFolderOptions {
+  repoRoot: string;
+  runsDir: string;
+  topic: string;
+  type: RunMetadata["type"];
+}
+
+export interface CreatedRunFolder {
+  /** Run id (the folder name). */
+  id: string;
+  /** Absolute path of the run folder. */
+  absPath: string;
+  /** Path relative to repo root. */
+  relPath: string;
+}
+
+export async function createRunFolder(
+  opts: CreateRunFolderOptions,
+): Promise<CreatedRunFolder> {
+  const timestamp = isoTimestampForId();
+  const topicSlug = slug(opts.topic);
+  const rand = randomBytes(2).toString("hex");
+  const id = `${timestamp}-${topicSlug}-${rand}`;
+
+  const relPath = join(opts.runsDir, id);
+  const absPath = join(opts.repoRoot, relPath);
+
+  await mkdir(join(absPath, "outputs"), { recursive: true });
+  await mkdir(join(absPath, "logs"), { recursive: true });
+
+  return { id, absPath, relPath };
+}
+
+export async function writeRunMetadata(
+  folderAbsPath: string,
+  meta: RunMetadata,
+): Promise<void> {
+  await writeFile(
+    join(folderAbsPath, "run.json"),
+    JSON.stringify(meta, null, 2) + "\n",
+    "utf8",
+  );
+}
+
+export async function writeRunInput(
+  folderAbsPath: string,
+  content: string,
+): Promise<void> {
+  await writeFile(join(folderAbsPath, "input.md"), content, "utf8");
+}
+
+export async function writeAgentOutput(
+  folderAbsPath: string,
+  role: "worker" | "reviewer" | "judge",
+  content: string,
+): Promise<void> {
+  await writeFile(
+    join(folderAbsPath, "outputs", `${role}.md`),
+    content,
+    "utf8",
+  );
+}
+
+export async function collectGitContext(repoRoot: string): Promise<{
+  branch?: string;
+  commit?: string;
+  dirty: boolean;
+}> {
+  const branch = await safeGit(repoRoot, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const commit = await safeGit(repoRoot, ["rev-parse", "HEAD"]);
+  const dirtyOut = await safeGit(repoRoot, ["status", "--short"]);
+  return {
+    ...(branch ? { branch } : {}),
+    ...(commit ? { commit } : {}),
+    dirty: dirtyOut !== undefined && dirtyOut.trim().length > 0,
+  };
+}
+
+async function safeGit(
+  repoRoot: string,
+  args: string[],
+): Promise<string | undefined> {
+  try {
+    const { stdout, exitCode } = await execa("git", args, {
+      cwd: repoRoot,
+      reject: false,
+      stripFinalNewline: true,
+    });
+    if (exitCode !== 0) return undefined;
+    return stdout || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isoTimestampForId(): string {
+  // YYYY-MM-DD-HHmmss in UTC. Filesystem-safe.
+  const d = new Date();
+  const pad = (n: number): string => n.toString().padStart(2, "0");
+  return (
+    `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}` +
+    `-${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}`
+  );
+}
+
+function slug(s: string): string {
+  return s
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40) || "run";
+}

package/src/runs/list.ts

@@ -0,0 +1,152 @@
+/**
+ * List existing runs from `.almightygpt/runs/`.
+ *
+ * Reads every `<id>/run.json`, validates it minimally, and returns a list
+ * sorted newest-first by `createdAt`. Used by `almightygpt runs list` and
+ * `almightygpt runs latest`.
+ *
+ * Bad/missing run.json entries are surfaced as `errors` instead of
+ * throwing, so a single corrupt run doesn't break the listing.
+ */
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { RunMetadata, RunStatus, RunType } from "./types.js";
+
+export interface RunSummary {
+  id: string;
+  type: RunType;
+  topic: string;
+  status: RunStatus;
+  createdAt: string;
+  finishedAt?: string;
+  totalCostUsd: number;
+  totalTokens: number;
+  reviewer?: string;
+  worker?: string;
+  reviewPath?: string;
+  runFolder: string;
+  decision?: RunMetadata["decision"];
+  error?: RunMetadata["error"];
+}
+
+export interface ListRunsResult {
+  runs: RunSummary[];
+  /** Run folders that couldn't be parsed (path → reason). */
+  errors: { path: string; reason: string }[];
+}
+
+export interface ListRunsOptions {
+  repoRoot: string;
+  runsDir: string;
+  /** Cap the number of results. Most recent first. */
+  limit?: number;
+}
+
+export async function listRuns(opts: ListRunsOptions): Promise<ListRunsResult> {
+  const runsAbs = join(opts.repoRoot, opts.runsDir);
+  if (!existsSync(runsAbs)) {
+    return { runs: [], errors: [] };
+  }
+
+  const entries = await readdir(runsAbs, { withFileTypes: true });
+  const folders = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+
+  const runs: RunSummary[] = [];
+  const errors: { path: string; reason: string }[] = [];
+
+  for (const folder of folders) {
+    const runJsonPath = join(runsAbs, folder, "run.json");
+    if (!existsSync(runJsonPath)) {
+      errors.push({ path: folder, reason: "missing run.json" });
+      continue;
+    }
+    try {
+      const raw = await readFile(runJsonPath, "utf8");
+      const meta = JSON.parse(raw) as RunMetadata;
+      runs.push(toSummary(meta, opts.runsDir));
+    } catch (err) {
+      errors.push({
+        path: folder,
+        reason: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  runs.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+
+  if (opts.limit && runs.length > opts.limit) {
+    runs.length = opts.limit;
+  }
+
+  return { runs, errors };
+}
+
+export async function findRunById(
+  repoRoot: string,
+  runsDir: string,
+  runId: string,
+): Promise<{ meta: RunMetadata; absPath: string } | null> {
+  const absPath = join(repoRoot, runsDir, runId);
+  const runJsonPath = join(absPath, "run.json");
+  if (!existsSync(runJsonPath)) return null;
+  try {
+    const raw = await readFile(runJsonPath, "utf8");
+    const meta = JSON.parse(raw) as RunMetadata;
+    return { meta, absPath };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve "latest" to a concrete run id. Returns null if no runs exist.
+ */
+export async function findLatestRun(
+  repoRoot: string,
+  runsDir: string,
+): Promise<{ meta: RunMetadata; absPath: string } | null> {
+  const { runs } = await listRuns({ repoRoot, runsDir, limit: 1 });
+  const first = runs[0];
+  if (!first) return null;
+  return findRunById(repoRoot, runsDir, first.id);
+}
+
+function toSummary(meta: RunMetadata, runsDir: string): RunSummary {
+  const reviewerMetric = meta.metrics.find((m) => m.role === "reviewer");
+  const workerMetric = meta.metrics.find((m) => m.role === "worker");
+  const summary: RunSummary = {
+    id: meta.id,
+    type: meta.type,
+    topic: meta.topic,
+    status: meta.status,
+    createdAt: meta.createdAt,
+    totalCostUsd: meta.totals.costUsd,
+    totalTokens: meta.totals.tokensIn + meta.totals.tokensOut,
+    runFolder: join(runsDir, meta.id),
+  };
+  if (meta.finishedAt) summary.finishedAt = meta.finishedAt;
+  if (reviewerMetric) summary.reviewer = reviewerMetric.agent;
+  if (workerMetric) summary.worker = workerMetric.agent;
+  if (meta.reviewPath) summary.reviewPath = meta.reviewPath;
+  if (meta.decision) summary.decision = meta.decision;
+  if (meta.error) summary.error = meta.error;
+  // stat to make sure the folder is real — but skip if we can't stat
+  void stat;
+  return summary;
+}
+
+/**
+ * Format a duration in seconds for human display.
+ */
+export function formatDuration(fromIso: string, toIso?: string): string {
+  if (!toIso) return "—";
+  const ms = Date.parse(toIso) - Date.parse(fromIso);
+  if (Number.isNaN(ms) || ms < 0) return "—";
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  const min = Math.floor(ms / 60_000);
+  const sec = Math.floor((ms % 60_000) / 1000);
+  return `${min}m${sec}s`;
+}