Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

6.0 KB
Raw Blame
/**
 * Admin storage routes (admin only, 403 `admin_required` for a non-admin), exactly like the
 * server-settings route beside them:
 *
 * - `GET /api/admin/storage` — the ledger: what the data root holds, class by class, with the
 *   entries a person could review. Reads only, always available.
 * - `GET|PUT /api/admin/storage/settings` — the cleanup mode (off until somebody turns it on),
 *   the trash retention, and the pins.
 * - `POST /api/admin/storage/plans` — scans and writes a bill; `GET .../plans` lists the recent
 *   ones and `GET .../plans/:planId` reads one; `POST .../plans/:planId/pin` keeps an entry out
 *   of every future bill.
 * - `POST /api/admin/storage/apply` — moves the approved entries into the trash. The only route
 *   in this file that changes the data root, and it needs a plan id, that plan's fingerprint and
 *   an explicit path list.
 * - `GET /api/admin/storage/trash`, `POST .../trash/restore`, `POST .../trash/purge` — what a
 *   run moved, putting it back, and the one deletion there is.
 *
 * Nothing here runs on a timer, and no route accepts a policy: a caller cannot widen what a
 * scan considers, and cannot ask for "everything unreferenced" — the unit of approval is a
 * specific bill. The work itself is services/storage-service.ts.
 */
import { Hono } from "hono";
import type {
  StorageApplyResponse,
  StorageApplyRequest,
  StoragePinRequest,
  StoragePlanResponse,
  StoragePlansResponse,
  StoragePurgeResponse,
  StorageReportResponse,
  StorageRestoreResponse,
  StorageSettingsResponse,
  StorageTrashResponse,
} from "../../api/types.js";
import { HttpError } from "../errors.js";
import type { AppEnv } from "../../auth/middleware.js";
import {
  optionalBoolean,
  optionalNumber,
  optionalStringArray,
  pathParam,
  readJson,
  requireString,
} from "../validate.js";
import type { StorageAdmin } from "../../services/storage-service.js";

/** What this route group reaches — bound by AdminRoutes, which builds it (src/http/routes/admin.ts). */
export interface AdminStorageRouteDeps {
  storage: StorageAdmin;
}

export function adminStorageRoutes(deps: AdminStorageRouteDeps): Hono<AppEnv> {
  const app = new Hono<AppEnv>();

  app.use("*", async (c, next) => {
    if (!c.var.user.isAdmin) {
      throw new HttpError(403, "admin_required", "Only an admin can perform this operation.");
    }
    await next();
  });

  const settings = (): StorageSettingsResponse => ({ settings: deps.storage.settings() });

  app.get("/", async (c) =>
    c.json({ report: await deps.storage.report() } satisfies StorageReportResponse),
  );

  app.get("/settings", (c) => c.json(settings()));

  app.put("/settings", async (c) => {
    const body = await readJson(c);
    // Validated before anything is written, like the server-settings route: a PUT that names one
    // bad field leaves the mode, the retention and the pins exactly as they were.
    const enabled = optionalBoolean(body, "enabled");
    const trashTtlDays = optionalNumber(body, "trashTtlDays", {
      integer: true,
      nonNegative: true,
      label: "trashTtlDays",
    });
    const pins = optionalStringArray(body, "pins");
    return c.json({
      settings: deps.storage.updateSettings({
        ...(enabled !== undefined ? { enabled } : {}),
        ...(trashTtlDays !== undefined ? { trashTtlDays } : {}),
        ...(pins !== undefined ? { pins } : {}),
      }),
    } satisfies StorageSettingsResponse);
  });

  app.get("/plans", async (c) =>
    c.json({ plans: await deps.storage.plans() } satisfies StoragePlansResponse),
  );

  // A scan writes a bill and nothing else — it is a POST because it creates a file, not because
  // it changes anything a person would have to be warned about.
  app.post("/plans", async (c) =>
    c.json({ plan: await deps.storage.scan() } satisfies StoragePlanResponse, 201),
  );

  app.get("/plans/:planId", async (c) =>
    c.json({ plan: await deps.storage.plan(pathParam(c, "planId")) } satisfies StoragePlanResponse),
  );

  app.post("/plans/:planId/pin", async (c) => {
    const planId = pathParam(c, "planId");
    const body = await readJson(c);
    // The plan is read first so that pinning an entry of a plan that does not exist — a typo in
    // the id, a plan file deleted by hand — is told so rather than answered with a settings blob.
    await deps.storage.plan(planId);
    const request: StoragePinRequest = {
      path: requireString(body, "path", { label: "path" }),
      pinned: optionalBoolean(body, "pinned") ?? true,
    };
    return c.json({ settings: await deps.storage.pin(request) } satisfies StorageSettingsResponse);
  });

  app.post("/apply", async (c) => {
    const body = await readJson(c);
    // The selection is a list of paths and nothing else: there is no "all" and no class to name,
    // so what moves is exactly what somebody ticked on a bill they were reading.
    const request: StorageApplyRequest = {
      planId: requireString(body, "planId", { label: "planId" }),
      fingerprint: requireString(body, "fingerprint", { label: "fingerprint" }),
      paths: optionalStringArray(body, "paths") ?? [],
    };
    return c.json((await deps.storage.apply(request)) satisfies StorageApplyResponse);
  });

  app.get("/trash", async (c) =>
    c.json({
      entries: await deps.storage.trash(),
      ttlDays: deps.storage.settings().trashTtlDays,
    } satisfies StorageTrashResponse),
  );

  app.post("/trash/restore", async (c) => {
    const body = await readJson(c);
    const id = requireString(body, "id", { label: "id" });
    return c.json((await deps.storage.restore(id)) satisfies StorageRestoreResponse);
  });

  // Without an id this removes only what is past the retention, which is why the body may be
  // empty; with one it removes exactly that entry, which is how a person empties the trash of
  // one run they are done with.
  app.post("/trash/purge", async (c) => {
    const body = await readJson(c);
    const id = typeof body.id === "string" ? body.id : null;
    return c.json((await deps.storage.purge(id)) satisfies StoragePurgeResponse);
  });

  return app;
}