Give a project a page: its branches, its dependencies, and a way out

Work item V3 of the M3 plan. The projects list linked to /projects/[id], which
was an empty directory, so V1 removed the link rather than leave a 404. This
builds the page and puts the link back.

The branch table is the point of it. Everything needed to decide which branch
is worth reviewing sits in the row: how far it has moved from the default
branch either way, what its last commit said, and a Review action that carries
the branch to the new-review screen already chosen. Arriving at a form that has
forgotten the choice just made is the kind of friction that makes a tool feel
like paperwork.

Dependency links get their own panel, because a link is what makes a review of
two repositories possible: it names the package the primary consumes, so a
changed exported type can be traced to the consumer that never migrated. The
form offers only projects that could actually be linked, excluding itself and
anything already linked, so it cannot present a choice the repository would
refuse. Where the repository does refuse, its own message is shown rather than
restated in different words.

Deleting is a two-step confirm, refused while any review still refers to the
project, and it takes the clone with it. The row and the clone must not outlive
each other in either direction: a clone with no row is disk nobody can account
for, and a row with no clone is a project every screen offers and nothing can
use.

Driving the live server found what the test had missed. Delete removed the bare
repo but left the project's directory behind, empty, one per deleted project,
forever. The test asserted on the clone path, which was genuinely gone, so it
passed. It now asserts the parent directory is gone too, and the route removes
it. Verified against a fresh server: zero directories left after a delete.

Two mutations checked and both caught: leaving the clone on disk, and offering
already-linked projects as link candidates.

Author: Poolchaos

docs/DECISIONS.md

@@ -677,3 +677,17 @@ verified evidence, in writing, here.
   cancelled and failed from V1 (D-12 now fully implemented). The confirmation
   screen was the last thing that needed the checkout; the bundle and the logs
   stay as the evidence behind the report.
+- 2026-07-31 DECIDED (V3): deleting a project removes its whole directory
+  under the data root, not only the bare clone inside it. Found by driving the
+  live server rather than by the test, which asserted on the clone path and so
+  passed while an empty directory was left behind for every project ever
+  deleted. The test now asserts the parent is gone too.
+- 2026-07-31 DECIDED (V3): the project detail endpoint returns the projects
+  that could still be linked, excluding itself and anything already linked, so
+  the form cannot offer a choice the repository would refuse. The repository's
+  own errors for a self-link and a duplicate are passed through verbatim
+  rather than restated in different words on the route.
+- 2026-07-31 DECIDED (V3): a branch row links to the new-review screen with
+  the branch already chosen. Arriving at a form that has forgotten the choice
+  just made is the kind of small friction that makes a tool feel like
+  paperwork.

docs/plans/M3-FINISH-PLAN.md

@@ -345,7 +345,7 @@ confirms the wiring.
 | -- | ------------------------------------------------------------ | ---------- | ------ |
 | V1 | budget cap, engine note, no-auto-probe, worktree cleanup, 404 unlink, activity cap | -          | DONE   |
 | V2 | confirm/dismiss/complete/context routes, confirmation UI, keyboard map | V1         | DONE   |
-| V3 | project detail page, fetch-now, links CRUD, project delete    | V1         |        |
+| V3 | project detail page, fetch-now, links CRUD, project delete    | V1         | DONE   |
 | V4 | preflight route and panel, linked toggle with suggestion      | V3         |        |
 | V5 | report renderer, report/export routes, report UI              | V2         |        |
 | V6 | resume/queued/merged/delete UI, settings editor, probe buttons | V2         |        |

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

@@ -0,0 +1,35 @@
+/**
+ * Fetch a project's refs now, rather than waiting for a branch list to do it.
+ *
+ * Useful when a branch was pushed a moment ago and the picker has not been
+ * opened since. Git's own message is returned verbatim on failure: an
+ * authentication problem and an unreachable host need different answers from
+ * the person reading it.
+ */
+
+import { recordFetch, requireProject } from "@/server/db/repositories/projects";
+import { failed, handler, ok } from "@/server/api/respond";
+import { fetchAll } from "@/server/gitops/repo";
+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 { db } = runtime();
+    const { id } = await context.params;
+    const project = requireProject(db, id);
+
+    try {
+      await fetchAll(project.clonePath);
+    } catch (error) {
+      return failed(error, 502);
+    }
+
+    recordFetch(db, project.id);
+    return ok({ lastFetchedAt: requireProject(db, id).lastFetchedAt });
+  });
+}

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

@@ -0,0 +1,18 @@
+/** Removing a dependency link. Reviews already run keep their linked history. */
+
+import { unlinkDependency } 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 DELETE(
+  _request: Request,
+  context: { params: Promise<{ id: string; linkId: string }> },
+): Promise<Response> {
+  return handler(async () => {
+    const { linkId } = await context.params;
+    unlinkDependency(runtime().db, linkId);
+    return ok({ removed: linkId });
+  });
+}

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

@@ -0,0 +1,57 @@
+/**
+ * A project's dependency links.
+ *
+ * The link is what makes a review of two repositories possible: it names the
+ * package the primary consumes, so a change to an exported type in the
+ * dependency can be traced to the consumer that never migrated.
+ */
+
+import { z } from "zod";
+import { linkDependency, listDependencyLinks } from "@/server/db/repositories/projects";
+import { created, failed, handler, ok, readJson } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+
+export const dynamic = "force-dynamic";
+
+const body = z.object({
+  dependencyProjectId: z.string().min(1),
+  packageName: z.string().trim().min(1),
+  note: z.string().optional(),
+});
+
+export async function GET(
+  _request: Request,
+  context: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  return handler(async () => {
+    const { id } = await context.params;
+    return ok({ links: listDependencyLinks(runtime().db, id) });
+  });
+}
+
+export async function POST(
+  request: Request,
+  context: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  return handler(async () => {
+    const { db } = runtime();
+    const { id } = await context.params;
+    const input = await readJson(request, body);
+
+    try {
+      // The repository already refuses a self-link and a duplicate, with
+      // messages worth showing, so they are passed through rather than
+      // re-checked here in different words.
+      return created({
+        link: linkDependency(db, {
+          projectId: id,
+          dependencyProjectId: input.dependencyProjectId,
+          packageName: input.packageName,
+          ...(input.note === undefined ? {} : { note: input.note }),
+        }),
+      });
+    } catch (error) {
+      return failed(error, 400);
+    }
+  });
+}

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

@@ -1,8 +1,15 @@
-/** One project, with its dependency links and its reviews. */
+/** One project, with its dependency links and its reviews. Or gone. */
 
-import { listDependencyLinks, requireProject } from "@/server/db/repositories/projects";
+import {
+  deleteProject,
+  listDependencyLinks,
+  listProjects,
+  requireProject,
+} from "@/server/db/repositories/projects";
 import { listReviewsForProject } from "@/server/db/repositories/reviews";
-import { handler, ok } from "@/server/api/respond";
+import { failed, handler, ok } from "@/server/api/respond";
+import { dirname } from "node:path";
+import { removeRepo } from "@/server/gitops/repo";
 import { runtime } from "@/server/runtime";
 
 export const dynamic = "force-dynamic";
@@ -14,10 +21,58 @@ export async function GET(
   return handler(async () => {
     const { db } = runtime();
     const { id } = await context.params;
+    const links = listDependencyLinks(db, id);
+    const byId = new Map(listProjects(db).map((project) => [project.id, project.name]));
+
     return ok({
       project: requireProject(db, id),
-      links: listDependencyLinks(db, id),
+      links: links.map((link) => ({
+        ...link,
+        dependencyName: byId.get(link.dependencyProjectId) ?? "a project that is gone",
+      })),
+      // Offered as link candidates, so the form is a choice rather than an id
+      // someone has to find.
+      linkable: listProjects(db)
+        .filter(
+          (candidate) =>
+            candidate.id !== id &&
+            candidate.cloneStatus === "ready" &&
+            !links.some((link) => link.dependencyProjectId === candidate.id),
+        )
+        .map((candidate) => ({ id: candidate.id, name: candidate.name })),
       reviews: listReviewsForProject(db, id),
     });
   });
 }
+
+/**
+ * Removes a project and the clone it owns.
+ *
+ * The row and the clone must not outlive each other in either direction: a
+ * clone with no row is disk nobody can account for, and a row with no clone is
+ * a project every screen offers and nothing can use. Refused while reviews
+ * reference it, because deleting those silently would discard the history the
+ * reviews are for.
+ */
+export async function DELETE(
+  _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);
+
+    try {
+      deleteProject(db, id);
+    } catch (error) {
+      return failed(error, 409);
+    }
+
+    // The project's whole directory, not just the bare repo inside it.
+    // Removing only the clone leaves an empty directory per deleted project,
+    // accumulating quietly forever.
+    if (project.clonePath) await removeRepo(dirname(project.clonePath));
+    return ok({ removed: id });
+  });
+}