Give the app an HTTP layer, so there is something for a screen to talk to

Route handlers for the flow a person actually follows: add a project, watch it
clone, list its branches, create a review pinned to those branches, start it,
watch it, cancel it. Plus rulesets, models, and one read that gives a review
page everything it needs.

Cloning happens in the background and the row is created immediately with a
pending state. A large repository takes minutes, and a request that waited for
it would time out somewhere unhelpful; the screen watches the clone state
instead. A clone that fails keeps git's stderr verbatim, because that text is
the only part a person can act on.

Creating a review fetches and then pins from the refs that fetch produced, both
sides of a linked pair before either is pinned, so the pair describes one
moment rather than two. A fetch that fails blocks creation rather than falling
back to stale refs. Listing branches fetches too, but is allowed to fall back
and say so: browsing offline is reasonable, starting a review from stale refs
is not.

Two things the tests found rather than the design anticipated. An address git
would read as a command-line option was answering 500, which reads as a server
fault rather than a mistake on the form; it is a 400 now. And importing a
document that produced no rules was accepted, which would have given someone a
ruleset that checks nothing and a review that comes back clean for the wrong
reason. That is refused, with a message saying what to look at.

Errors reach the client as the message the thing that failed actually produced.
A route that replaced git's stderr or the state machine's complaint with
"something went wrong" would throw away the only part worth reading.

Author: Poolchaos

src/app/api/models/route.ts

@@ -0,0 +1,18 @@
+/** The models this account can actually use, and what each one is good for. */
+
+import { availabilityOf, listModels } from "@/server/db/repositories/models";
+import { handler, ok } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+
+export const dynamic = "force-dynamic";
+
+export function GET(): Promise<Response> {
+  return handler(async () => {
+    const now = Date.now();
+    const models = listModels(runtime().db).map((model) => ({
+      ...model,
+      availability: availabilityOf(model, now),
+    }));
+    return ok({ models });
+  });
+}

src/app/api/projects/[id]/branches/route.ts

@@ -0,0 +1,55 @@
+/**
+ * The branches a project has, fetched before they are listed.
+ *
+ * Fetching first is the point (D-29): a picker showing yesterday's refs would
+ * let someone review a branch tip that has already moved. When the remote is
+ * unreachable the cached refs are still listed, marked stale, because browsing
+ * offline is reasonable even though starting a review that way is not.
+ */
+
+import { detectDefaultBranch, divergence, fetchAll, listBranches } from "@/server/gitops/repo";
+import { recordFetch, requireProject } from "@/server/db/repositories/projects";
+import { handler, ok } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(
+  _request: Request,
+  context: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  return handler(async () => {
+    const { db } = runtime();
+    const { id } = await context.params;
+    const project = requireProject(db, id);
+
+    let stale: string | null = null;
+    try {
+      await fetchAll(project.clonePath);
+      recordFetch(db, project.id);
+    } catch (error) {
+      stale = error instanceof Error ? error.message : String(error);
+    }
+
+    const branches = await listBranches(project.clonePath);
+    const into = project.defaultBranch || (await detectDefaultBranch(project.clonePath));
+
+    // Ahead and behind are what tell someone whether a branch is worth
+    // reviewing yet, and they are cheap to compute while we are here.
+    const withDivergence = await Promise.all(
+      branches.map(async (branch) => ({
+        ...branch,
+        ...(branch.name === into
+          ? { ahead: 0, behind: 0 }
+          : await divergence(project.clonePath, branch.name, into)),
+      })),
+    );
+
+    return ok({
+      branches: withDivergence,
+      defaultBranch: into,
+      lastFetchedAt: requireProject(db, id).lastFetchedAt,
+      stale,
+    });
+  });
+}

src/app/api/projects/[id]/route.ts

@@ -0,0 +1,23 @@
+/** One project, with its dependency links and its reviews. */
+
+import { listDependencyLinks, requireProject } from "@/server/db/repositories/projects";
+import { listReviewsForProject } from "@/server/db/repositories/reviews";
+import { handler, ok } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(
+  _request: Request,
+  context: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  return handler(async () => {
+    const { db } = runtime();
+    const { id } = await context.params;
+    return ok({
+      project: requireProject(db, id),
+      links: listDependencyLinks(db, id),
+      reviews: listReviewsForProject(db, id),
+    });
+  });
+}

src/app/api/projects/route.ts

@@ -0,0 +1,92 @@
+/**
+ * The projects this app knows about, and adding one.
+ *
+ * Cloning happens in the background: a large repository takes minutes and a
+ * request that waited for it would time out somewhere unhelpful. The row is
+ * created immediately with a pending clone state, and the projects screen
+ * shows that state until it resolves.
+ */
+
+import { z } from "zod";
+import { repoSlug, validateGitUrl } from "@/lib/git/url";
+import { projectRepoDir } from "@/lib/paths";
+import {
+  createProject,
+  listProjects,
+  setCloneStatus,
+  setClonePath,
+  setDefaultBranch,
+} from "@/server/db/repositories/projects";
+import { cloneBare, detectDefaultBranch } from "@/server/gitops/repo";
+import { created, failed, handler, ok, readJson } from "@/server/api/respond";
+import { runtime as appRuntime } from "@/server/runtime";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+const addProject = z.object({
+  gitUrl: z.string().min(1),
+  name: z.string().trim().min(1).optional(),
+});
+
+export function GET(): Promise<Response> {
+  return handler(async () => ok({ projects: listProjects(appRuntime().db) }));
+}
+
+export function POST(request: Request): Promise<Response> {
+  return handler(async () => {
+    const { db, dataDir } = appRuntime();
+    const body = await readJson(request, addProject);
+
+    // Validated before the row exists, so a bad address is an error the user
+    // sees on the form rather than a project stuck in a failed clone.
+    let url: string;
+    try {
+      url = validateGitUrl(body.gitUrl);
+    } catch (error) {
+      return failed(error, 400);
+    }
+    const name = body.name ?? nameFromUrl(url);
+
+    const project = createProject(db, {
+      name,
+      gitUrl: url,
+      defaultBranch: "main",
+      clonePath: "",
+    });
+    const clonePath = projectRepoDir(dataDir, project.id);
+    setClonePath(db, project.id, clonePath);
+    setCloneStatus(db, project.id, "pending");
+
+    void cloneInBackground(db, project.id, url, clonePath);
+    return created({ project: { ...project, clonePath } });
+  });
+}
+
+async function cloneInBackground(
+  db: ReturnType<typeof appRuntime>["db"],
+  projectId: string,
+  url: string,
+  clonePath: string,
+): Promise<void> {
+  try {
+    await cloneBare(url, clonePath);
+    setDefaultBranch(db, projectId, await detectDefaultBranch(clonePath));
+    setCloneStatus(db, projectId, "ready");
+  } catch (error) {
+    // Verbatim: git's stderr says what is actually wrong, and a summary of it
+    // would leave the user guessing at an authentication or address problem.
+    setCloneStatus(db, projectId, "failed", error instanceof Error ? error.message : String(error));
+  }
+}
+
+/** A readable name from the address, which is what a person would have typed. */
+function nameFromUrl(url: string): string {
+  const last =
+    url
+      .replace(/\.git$/, "")
+      .split(/[/:]/)
+      .filter(Boolean)
+      .pop() ?? "project";
+  return repoSlug(last);
+}

src/app/api/reviews/[id]/cancel/route.ts

@@ -0,0 +1,17 @@
+/** Stops a running review, or takes a queued one out of the line. */
+
+import { handler, ok } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(
+  _request: Request,
+  context: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  return handler(async () => {
+    const { manager } = runtime();
+    const { id } = await context.params;
+    return ok({ cancelled: manager.cancel(id), snapshot: manager.snapshot(id) });
+  });
+}

src/app/api/reviews/[id]/route.ts

@@ -0,0 +1,18 @@
+/** Everything a review page needs in one read. */
+
+import { listFindings } from "@/server/db/repositories/findings";
+import { handler, ok } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(
+  _request: Request,
+  context: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  return handler(async () => {
+    const { db, manager } = runtime();
+    const { id } = await context.params;
+    return ok({ ...manager.snapshot(id), findings: listFindings(db, id) });
+  });
+}

src/app/api/reviews/[id]/start/route.ts

@@ -0,0 +1,50 @@
+/**
+ * Starts or resumes a review.
+ *
+ * Returns as soon as the review is scheduled rather than when it finishes: a
+ * review takes minutes, and the page watches the event stream for the rest.
+ */
+
+import { z } from "zod";
+import { rulesetTierSchema } from "@/lib/domain/enums";
+import { loadRuleset, readReviewSnapshot, requireRuleset } from "@/server/db/repositories/rulesets";
+import { handler, ok, readJson } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+
+export const dynamic = "force-dynamic";
+
+const body = z.object({ rulesetId: z.string().min(1).optional() });
+
+export async function POST(
+  request: Request,
+  context: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  return handler(async () => {
+    const { db, manager } = runtime();
+    const { id } = await context.params;
+    const input = await readJson(request, body).catch(() => ({ rulesetId: undefined }));
+
+    // A resumed review already carries its frozen ruleset and must not be
+    // handed a different one.
+    let ruleset;
+    try {
+      readReviewSnapshot(db, id);
+    } catch {
+      if (!input.rulesetId) {
+        throw Response.json(
+          { error: "Choose a ruleset before starting this review.", code: "RulesetRequired" },
+          { status: 400 },
+        );
+      }
+      const row = requireRuleset(db, input.rulesetId);
+      ruleset = {
+        imported: loadRuleset(db, input.rulesetId),
+        name: row.name,
+        tier: rulesetTierSchema.parse(row.tier),
+      };
+    }
+
+    const state = manager.start(id, ...(ruleset ? [{ ruleset }] : []));
+    return ok({ state, snapshot: manager.snapshot(id) });
+  });
+}

src/app/api/reviews/route.ts

@@ -0,0 +1,119 @@
+/**
+ * Creating a review, and listing them.
+ *
+ * Creating one is where the commits are pinned, so it fetches first and then
+ * resolves the tips from the refs that fetch produced (D-27). A stale pin is
+ * the worst failure this app can have: the run completes, the report reads as
+ * authoritative, and it describes code the branch has already moved past. A
+ * fetch that fails therefore blocks creation rather than falling back.
+ */
+
+import { z } from "zod";
+import { reviewEffortSchema, reviewProfileSchema } from "@/lib/domain/enums";
+import {
+  listDependencyLinks,
+  recordFetch,
+  requireProject,
+} from "@/server/db/repositories/projects";
+import { createReview, listActiveReviews } from "@/server/db/repositories/reviews";
+import { fetchAll, mergeBase, resolveCommit } from "@/server/gitops/repo";
+import { created, handler, ok, readJson } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+import { listProjects } from "@/server/db/repositories/projects";
+import { listReviewsForProject } from "@/server/db/repositories/reviews";
+
+export const dynamic = "force-dynamic";
+
+const body = z.object({
+  projectId: z.string().min(1),
+  fromBranch: z.string().min(1),
+  intoBranch: z.string().min(1),
+  model: z.string().min(1),
+  profileId: reviewProfileSchema.default("full-context"),
+  effort: reviewEffortSchema.default("high"),
+  intent: z.string().optional(),
+  linked: z
+    .object({
+      projectId: z.string().min(1),
+      fromBranch: z.string().min(1),
+      intoBranch: z.string().min(1),
+    })
+    .optional(),
+});
+
+export function GET(): Promise<Response> {
+  return handler(async () => {
+    const { db } = runtime();
+    const reviews = listProjects(db).flatMap((project) =>
+      listReviewsForProject(db, project.id).map((review) => ({
+        ...review,
+        projectName: project.name,
+      })),
+    );
+    reviews.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    return ok({ reviews, active: listActiveReviews(db).map((review) => review.id) });
+  });
+}
+
+export function POST(request: Request): Promise<Response> {
+  return handler(async () => {
+    const { db } = runtime();
+    const input = await readJson(request, body);
+    const project = requireProject(db, input.projectId);
+
+    // Fetched immediately before pinning, so the commits recorded are the tips
+    // the remote has now rather than whatever the last clone left behind.
+    await fetchAll(project.clonePath);
+    recordFetch(db, project.id);
+    const pins = await pin(project.clonePath, input.fromBranch, input.intoBranch);
+
+    let linked;
+    if (input.linked) {
+      const dependency = requireProject(db, input.linked.projectId);
+      const isLinked = listDependencyLinks(db, project.id).some(
+        (link) => link.dependencyProjectId === dependency.id,
+      );
+      if (!isLinked) {
+        throw Response.json(
+          {
+            error: `${dependency.name} is not a dependency of ${project.name}.`,
+            code: "NotLinked",
+          },
+          { status: 400 },
+        );
+      }
+      // Both sides fetched before either is pinned, so the pair describes one
+      // moment rather than two.
+      await fetchAll(dependency.clonePath);
+      recordFetch(db, dependency.id);
+      linked = {
+        ...input.linked,
+        projectId: dependency.id,
+        ...(await pin(dependency.clonePath, input.linked.fromBranch, input.linked.intoBranch)),
+      };
+    }
+
+    const review = createReview(db, {
+      projectId: project.id,
+      fromBranch: input.fromBranch,
+      intoBranch: input.intoBranch,
+      ...pins,
+      model: input.model,
+      profileId: input.profileId,
+      engineMode: "headless",
+      effort: input.effort,
+      ...(input.intent === undefined ? {} : { intent: input.intent }),
+      ...(linked === undefined ? {} : { linked }),
+    });
+
+    return created({ review });
+  });
+}
+
+async function pin(repoDir: string, fromBranch: string, intoBranch: string) {
+  return {
+    fromCommit: await resolveCommit(repoDir, fromBranch),
+    intoCommit: await resolveCommit(repoDir, intoBranch),
+    mergeBaseCommit: await mergeBase(repoDir, intoBranch, fromBranch),
+  };
+}