@gentbajko/slopify 0.1.0

package/dist/edge/http/actions.js

@@ -0,0 +1,125 @@
+import { zValidator } from "@hono/zod-validator";
+import { Hono } from "hono";
+import { z } from "zod";
+import { stageKinds } from "../../kernel/pipeline.js";
+import { derive } from "../../kernel/runner/graph.js";
+import { projectById, stagesOf } from "../../slices/admission/repo.js";
+import { cancelProject } from "../../slices/cancel/index.js";
+import { deleteImage, editArticle, regenerateImage, rerunStage, retryStage, } from "../../slices/reruns/index.js";
+import { outputsOf } from "../../slices/storage/repo.js";
+import { onInvalid, problem, titleOf } from "./problem.js";
+// The actions `mockup/08-project.md` puts on the project header and on each stage: Cancel,
+// Retry, Re-run, Save & re-run, Regenerate one image, Delete one image. Every one of them
+// changes rows and files through a slice and then ticks the runner; the route itself
+// decides nothing (`logic/12`, `logic/13`).
+const idParam = z.object({
+    id: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[0-9A-Za-z_-]+$/),
+});
+const stageParam = idParam.extend({ kind: z.enum(stageKinds) });
+const imageParam = idParam.extend({
+    outputId: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[0-9A-Za-z_-]+$/),
+});
+// ceiling: half a megabyte of markdown, which is far past any narratable article and
+// keeps a paste from filling the process's memory. A longer one needs a streamed edit.
+const articleBody = z.object({ markdown: z.string().min(1).max(500_000) });
+const status = {
+    "no-project": 404,
+    "unknown-image": 404,
+    "empty-article": 400,
+    running: 409,
+    "not-rerunnable": 409,
+    "not-retryable": 409,
+    "no-article": 409,
+    "last-image": 409,
+};
+const details = {
+    "no-project": "No project has that id.",
+    "unknown-image": "This project has no image with that id.",
+    "empty-article": "An article cannot be saved empty.",
+    // logic/12 preconditions: "no stage of the project is `running` (§Q106)".
+    running: "This project is still running. Cancel it or wait for it to finish.",
+    "not-rerunnable": "Only a stage that has finished, failed, or been canceled can be re-run.",
+    "not-retryable": "Only a failed or canceled stage can be retried.",
+    "no-article": "This project has no article to edit yet.",
+    // logic/09 §Q75 and logic/12's invariant: "at least one image always remains".
+    "last-image": "At least one image must remain, so the last one cannot be deleted.",
+};
+// The return type is inferred so Hono keeps the route types the SPA's client is
+// generated from; see stagingRoutes.
+export function actionRoutes(deps) {
+    const reruns = {
+        db: deps.db,
+        paths: deps.paths,
+        ids: deps.ids,
+        clock: deps.clock,
+        log: deps.log,
+    };
+    const cancel = {
+        db: deps.db,
+        clock: deps.clock,
+        log: deps.log,
+        abort: (projectId) => deps.runner.abortProject(projectId),
+        emit: (projectId, event) => {
+            deps.hub.emit(projectId, event);
+        },
+    };
+    const view = (projectId) => {
+        const stages = stagesOf(deps.db, projectId);
+        return {
+            project: { ...projectById(deps.db, projectId), status: derive(stages) },
+            stages,
+            outputs: outputsOf(deps.db, projectId),
+        };
+    };
+    // Every re-run action ends the same way: the rows are written, then the runner is
+    // asked to look at the project. `logic/12` step 9 does the rest by itself.
+    const started = (c, projectId, result) => {
+        if (!result.ok) {
+            return problem(c, {
+                status: status[result.reason],
+                title: titleOf(status[result.reason]),
+                detail: details[result.reason],
+            });
+        }
+        deps.runner.tick(projectId);
+        return c.json({ ...view(projectId), redone: result.redone });
+    };
+    return new Hono()
+        .post("/:id/cancel", zValidator("param", idParam, onInvalid), async (c) => {
+        const { id } = c.req.valid("param");
+        const result = await cancelProject(cancel, id);
+        if (!result.ok) {
+            return problem(c, { status: 404, title: titleOf(404), detail: details["no-project"] });
+        }
+        // No tick: §Q111 leaves a canceled project sitting until the user retries a stage.
+        return c.json({ ...view(id), canceled: result.canceled });
+    })
+        .post("/:id/stages/:kind/retry", zValidator("param", stageParam, onInvalid), (c) => {
+        const { id, kind } = c.req.valid("param");
+        return started(c, id, retryStage(reruns, id, kind));
+    })
+        .post("/:id/stages/:kind/rerun", zValidator("param", stageParam, onInvalid), (c) => {
+        const { id, kind } = c.req.valid("param");
+        return started(c, id, rerunStage(reruns, id, kind));
+    })
+        .put("/:id/article", zValidator("param", idParam, onInvalid), zValidator("json", articleBody, onInvalid), (c) => {
+        const { id } = c.req.valid("param");
+        return started(c, id, editArticle(reruns, id, c.req.valid("json").markdown));
+    })
+        .delete("/:id/images/:outputId", zValidator("param", imageParam, onInvalid), (c) => {
+        const { id, outputId } = c.req.valid("param");
+        return started(c, id, deleteImage(reruns, id, outputId));
+    })
+        .post("/:id/images/:outputId/regenerate", zValidator("param", imageParam, onInvalid), (c) => {
+        const { id, outputId } = c.req.valid("param");
+        return started(c, id, regenerateImage(reruns, id, outputId));
+    });
+}

package/dist/edge/http/app.js

@@ -0,0 +1,72 @@
+import { existsSync } from "node:fs";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+import { actionRoutes } from "./actions.js";
+import { entryRoutes } from "./entries.js";
+import { fileRoutes } from "./files.js";
+import { problem, problemFromError, titleOf } from "./problem.js";
+import { projectRoutes } from "./projects.js";
+import { promptRoutes } from "./prompts.js";
+import { providerRoutes } from "./providers.js";
+import { settingsRoutes } from "./settings.js";
+import { stagingRoutes } from "./staging.js";
+import { telemetryRoutes } from "./telemetry.js";
+import { usageRoutes } from "./usage.js";
+const notBuilt = "The Slopify UI is not built yet. The API is running: try /api/health.\n" +
+    "Build the SPA with `npm run build` at the repository root.\n";
+function apiRoutes(deps, startedAt) {
+    return (new Hono()
+        .get("/health", (c) => c.json({
+        status: "ok",
+        version: deps.version,
+        uptimeMs: deps.clock.now().getTime() - startedAt,
+    }))
+        .route("/staging", stagingRoutes(deps))
+        .route("/projects", projectRoutes(deps))
+        // The actions of `logic/12` and `logic/13` sit on the same prefix as the project
+        // itself; they are their own router because they are their own concern.
+        .route("/projects", actionRoutes(deps))
+        .route("/prompts", promptRoutes(deps))
+        .route("/entries", entryRoutes(deps))
+        .route("/telemetry", telemetryRoutes(deps))
+        .route("/usage", usageRoutes(deps))
+        .route("/settings", settingsRoutes(deps))
+        .route("/providers", providerRoutes(deps)));
+}
+export function createApp(deps) {
+    const startedAt = deps.clock.now().getTime();
+    const app = new Hono()
+        .use("*", async (c, next) => {
+        c.header("X-Slopify-Version", deps.version);
+        await next();
+    })
+        .onError((error, c) => problemFromError(c, error, deps))
+        .notFound(missing)
+        .route("/api", apiRoutes(deps, startedAt))
+        .get("/api/events/global", (c) => streamSSE(c, (stream) => deps.hub.subscribeGlobal(stream, c.req.raw.signal)))
+        .get("/api/events/projects/:id", (c) => streamSSE(c, (stream) => deps.hub.subscribe(c.req.param("id"), stream, c.req.raw.signal)))
+        // Files are served by URL, not through the API (02-models Boundaries).
+        .route("/", fileRoutes(deps))
+        // The API answers for its whole prefix, so an unknown endpoint is a problem+json 404
+        // rather than the SPA's index.html with a 200.
+        .all("/api/*", missing);
+    // ceiling: the SPA directory is looked up once, at boot. The build that fills it runs
+    // before the server starts; a server started before its own build needs a restart.
+    if (existsSync(deps.webDist)) {
+        app.use("/*", serveStatic({ root: deps.webDist }));
+        // Client-side routes are not files: anything the SPA owns falls back to its shell.
+        app.get("/*", serveStatic({ root: deps.webDist, path: "index.html" }));
+    }
+    else {
+        app.get("/*", (c) => c.text(notBuilt));
+    }
+    return app;
+}
+function missing(c) {
+    return problem(c, {
+        status: 404,
+        title: titleOf(404),
+        detail: `${c.req.method} ${c.req.path} is not a route of this API.`,
+    });
+}

package/dist/edge/http/entries.js

@@ -0,0 +1,41 @@
+import { zValidator } from "@hono/zod-validator";
+import { Hono } from "hono";
+import { z } from "zod";
+import { entryCategories, entryModes } from "../../slices/library/model.js";
+import { listEntries } from "../../slices/library/repo.js";
+import { createEntry, removeEntry, updateEntry } from "../../slices/library/save.js";
+import { onInvalid } from "./problem.js";
+// `logic/15` §Q121: one rule set for prompts and entries, so one refusal mapping too.
+import { refused } from "./prompts.js";
+const idParam = z.object({
+    id: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[0-9A-Za-z_-]+$/),
+});
+const entryBody = z.object({
+    category: z.enum(entryCategories),
+    mode: z.enum(entryModes),
+    name: z.string(),
+    body: z.string(),
+});
+// The return type is inferred so Hono keeps the route types the SPA's client is
+// generated from; see stagingRoutes.
+export function entryRoutes(deps) {
+    const library = { db: deps.db, ids: deps.ids, clock: deps.clock };
+    return new Hono()
+        .get("/", (c) => c.json({ entries: listEntries(deps.db) }))
+        .post("/", zValidator("json", entryBody, onInvalid), (c) => {
+        const result = createEntry(library, c.req.valid("json"));
+        return result.ok ? c.json(result.value, 201) : refused(c, result, "entry");
+    })
+        .put("/:id", zValidator("param", idParam, onInvalid), zValidator("json", entryBody, onInvalid), (c) => {
+        const result = updateEntry(library, c.req.valid("param").id, c.req.valid("json"));
+        return result.ok ? c.json(result.value) : refused(c, result, "entry");
+    })
+        .delete("/:id", zValidator("param", idParam, onInvalid), (c) => {
+        const result = removeEntry(library, c.req.valid("param").id);
+        return result.ok ? c.body(null, 204) : refused(c, result, "entry");
+    });
+}

package/dist/edge/http/files.js

@@ -0,0 +1,67 @@
+import { createReadStream } from "node:fs";
+import { Readable } from "node:stream";
+import { zValidator } from "@hono/zod-validator";
+import { Hono } from "hono";
+import { z } from "zod";
+import { findDownload, imagesZip } from "../../slices/storage/downloads.js";
+import { onInvalid, problem, titleOf } from "./problem.js";
+const projectParam = z.object({
+    projectId: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[0-9A-Za-z_-]+$/),
+});
+const assetParam = projectParam.extend({
+    asset: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[a-z0-9-]+$/),
+});
+// The return type is inferred so Hono keeps the route types; see stagingRoutes.
+export function fileRoutes(deps) {
+    const storage = { db: deps.db, paths: deps.paths };
+    return (new Hono()
+        // Declared before :asset so the zip is never read as an asset name.
+        .get("/files/:projectId/images.zip", zValidator("param", projectParam, onInvalid), (c) => {
+        const result = imagesZip(storage, c.req.valid("param").projectId);
+        if (!result.ok) {
+            return missing(c, result.reason);
+        }
+        return c.body(result.bytes, 200, {
+            "content-type": "application/zip",
+            "content-length": String(result.bytes.byteLength),
+            "content-disposition": disposition(result.filename),
+        });
+    })
+        .get("/files/:projectId/:asset", zValidator("param", assetParam, onInvalid), (c) => {
+        const { projectId, asset } = c.req.valid("param");
+        const result = findDownload(storage, projectId, asset);
+        if (!result.ok) {
+            return missing(c, result.reason);
+        }
+        const { download } = result;
+        // ceiling: whole-file responses only. Seeking inside the finished video would
+        // need a Range handler answering 206 with the requested slice.
+        return c.body(Readable.toWeb(createReadStream(download.path)), 200, {
+            "content-type": download.contentType,
+            "content-length": String(download.bytes),
+            "content-disposition": disposition(download.filename),
+        });
+    }));
+}
+// A download name is built from a slug, a role, and an extension, so it is always
+// `[a-z0-9.-]` and needs neither quoting nor the RFC 5987 encoded form.
+function disposition(filename) {
+    return `attachment; filename="${filename}"`;
+}
+function missing(c, reason) {
+    const details = {
+        "unknown-project": "No project has that id.",
+        "unknown-asset": "This project has no such file.",
+        "missing-file": "This file is recorded but is no longer on disk; re-run the stage.",
+        "no-images": "This project has no images or thumbnail yet.",
+    };
+    return problem(c, { status: 404, title: titleOf(404), detail: details[reason] });
+}

package/dist/edge/http/problem.js

@@ -0,0 +1,65 @@
+import { HTTPException } from "hono/http-exception";
+const titles = {
+    400: "Bad Request",
+    404: "Not Found",
+    409: "Conflict",
+    415: "Unsupported Media Type",
+    500: "Internal Server Error",
+};
+export function problem(c, init) {
+    const body = {
+        // Extensions go first so a route cannot shadow a member RFC 9457 reserves.
+        ...init.extensions,
+        type: init.type ?? "about:blank",
+        title: init.title,
+        status: init.status,
+        ...(init.detail === undefined ? {} : { detail: init.detail }),
+        instance: c.req.path,
+    };
+    return c.body(JSON.stringify(body), init.status, {
+        "content-type": "application/problem+json",
+    });
+}
+export function problemFromError(c, error, deps) {
+    if (error instanceof HTTPException) {
+        return problem(c, {
+            status: error.status,
+            title: titleOf(error.status),
+            detail: error.message === "" ? undefined : error.message,
+        });
+    }
+    // An unexpected exception can carry a provider's response text, and that text can
+    // carry the key that was sent. Only the correlation id crosses to the client; the
+    // message goes to the log, which redacts key-shaped strings.
+    const correlationId = deps.ids.next();
+    deps.log.write("error", "http.error", {
+        detail: `${correlationId} ${c.req.method} ${c.req.path}: ${error.message}`,
+    });
+    return problem(c, {
+        status: 500,
+        title: titleOf(500),
+        detail: `The server failed to handle this request. Correlation id ${correlationId} is in the log.`,
+        extensions: { correlationId },
+    });
+}
+export function titleOf(status) {
+    return titles[status] ?? "Error";
+}
+// The hook shape @hono/zod-validator calls, described structurally so this module
+// carries none of the validator's or the schema's generics.
+export function onInvalid(result, c) {
+    if (result.success) {
+        return undefined;
+    }
+    return problem(c, {
+        status: 400,
+        title: titleOf(400),
+        detail: "The request does not match this endpoint's schema.",
+        extensions: {
+            errors: result.error.issues.map((issue) => ({
+                path: issue.path.join("."),
+                message: issue.message,
+            })),
+        },
+    });
+}

package/dist/edge/http/projects.js

@@ -0,0 +1,128 @@
+import { zValidator } from "@hono/zod-validator";
+import { Hono } from "hono";
+import { z } from "zod";
+import { derive, progressOf } from "../../kernel/runner/graph.js";
+import { listProjects, projectById, runDraftSchema, stageStandingsByProject, stagesOf, } from "../../slices/admission/repo.js";
+import { admit } from "../../slices/admission/rules.js";
+import { startRun } from "../../slices/admission/start.js";
+import { pickTemplates, renderPicked } from "../../slices/library/slots.js";
+import { deleteProject } from "../../slices/storage/delete-project.js";
+import { outputsOf, stagedFiles } from "../../slices/storage/repo.js";
+import { record } from "../../slices/telemetry/record.js";
+import { onInvalid, problem, titleOf } from "./problem.js";
+const idParam = z.object({
+    id: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[0-9A-Za-z_-]+$/),
+});
+// The return type is inferred so Hono keeps the route types the SPA's client is
+// generated from; see stagingRoutes.
+export function projectRoutes(deps) {
+    const storage = {
+        db: deps.db,
+        paths: deps.paths,
+        ids: deps.ids,
+        clock: deps.clock,
+        log: deps.log,
+        emit: (event) => {
+            deps.hub.emitGlobal(event);
+        },
+    };
+    const telemetry = {
+        db: deps.db,
+        ids: deps.ids,
+        clock: deps.clock,
+        log: deps.log,
+        appVersion: deps.version,
+    };
+    const storageForDelete = { db: deps.db, paths: deps.paths, log: deps.log };
+    const summarise = (project) => ({
+        ...project,
+        status: derive(stagesOf(deps.db, project.id)),
+    });
+    return (new Hono()
+        .post("/", zValidator("json", runDraftSchema, onInvalid), (c) => {
+        // logic/04 §Q34: the bodies are read here, at the click, so an edit made since the
+        // prompt was selected is the one that runs.
+        const picked = pickTemplates(deps.db, c.req.valid("json"));
+        const admitted = admit({
+            draft: picked.draft,
+            staged: stagedFiles(deps.db),
+            requiredSlots: picked.requiredSlots,
+        });
+        if (!admitted.ok || picked.missing.length > 0) {
+            return problem(c, {
+                status: 400,
+                title: titleOf(400),
+                detail: "This run cannot start yet; the listed fields need attention.",
+                extensions: {
+                    fields: [...picked.missing, ...(admitted.ok ? [] : admitted.fields)],
+                },
+            });
+        }
+        // Rendered from the values admit() has trimmed, so the stored text carries no
+        // padding the user did not intend (logic/03 step 4 and step 5).
+        const { project } = startRun(storage, admitted.draft, renderPicked(picked, admitted.draft.values));
+        // logic/16 step 2: one event per project created. record() swallows its own
+        // failures, so a broken telemetry write cannot cost the user the run.
+        record(telemetry, "project.created", {});
+        deps.flushSoon();
+        // logic/04 step 6: the run starts only once the project is committed.
+        deps.runner.tick(project.id);
+        // Read back after the tick, not from the rows startRun built: the runner has
+        // already claimed every eligible stage, and a body that paired status "running"
+        // with "video: pending" would contradict itself.
+        return c.json({ project: summarise(project), stages: stagesOf(deps.db, project.id) }, 201);
+    })
+        // One statement for every project's stage standings, not one per row: the list needs
+        // a status word and a meter, and both come out of the same five columns.
+        .get("/", (c) => {
+        const standings = stageStandingsByProject(deps.db);
+        const projects = listProjects(deps.db).map((project) => {
+            const stages = standings.get(project.id) ?? [];
+            return { ...project, status: derive(stages), progress: progressOf(stages) };
+        });
+        return c.json({ projects });
+    })
+        .get("/:id", zValidator("param", idParam, onInvalid), (c) => {
+        const project = projectById(deps.db, c.req.valid("param").id);
+        if (project === undefined) {
+            return problem(c, {
+                status: 404,
+                title: titleOf(404),
+                detail: "No project has that id.",
+            });
+        }
+        return c.json({
+            project: summarise(project),
+            stages: stagesOf(deps.db, project.id),
+            outputs: outputsOf(deps.db, project.id),
+        });
+    })
+        // `logic/14` step 4. Irreversible, and only from the app: 07 Projects puts the
+        // confirmation dialog in front of it.
+        .delete("/:id", zValidator("param", idParam, onInvalid), (c) => {
+        const result = deleteProject(storageForDelete, c.req.valid("param").id);
+        if (result.ok) {
+            return c.body(null, 204);
+        }
+        return problem(c, {
+            status: deleteStatus[result.reason],
+            title: titleOf(deleteStatus[result.reason]),
+            detail: result.detail ?? deleteDetails[result.reason],
+        });
+    }));
+}
+const deleteStatus = {
+    "no-project": 404,
+    running: 409,
+    files: 500,
+};
+const deleteDetails = {
+    "no-project": "No project has that id.",
+    // §Q117: the run has to be stopped before its files can go.
+    running: "This project is still running. Cancel the run first.",
+    files: "Some of this project's files could not be removed.",
+};

package/dist/edge/http/prompts.js

@@ -0,0 +1,73 @@
+import { zValidator } from "@hono/zod-validator";
+import { Hono } from "hono";
+import { z } from "zod";
+import { promptKinds } from "../../slices/library/model.js";
+import { listPrompts } from "../../slices/library/repo.js";
+import { createPrompt, removePrompt, updatePrompt } from "../../slices/library/save.js";
+import { onInvalid, problem, titleOf } from "./problem.js";
+const idParam = z.object({
+    id: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[0-9A-Za-z_-]+$/),
+});
+// Shape only. The rules - trimming, emptiness, length, the slot lint - are the slice's,
+// so one set of messages reaches the editor (03-conventions).
+const promptBody = z.object({
+    kind: z.enum(promptKinds),
+    name: z.string(),
+    body: z.string(),
+});
+// The return type is inferred so Hono keeps the route types the SPA's client is
+// generated from; see stagingRoutes.
+export function promptRoutes(deps) {
+    const library = { db: deps.db, ids: deps.ids, clock: deps.clock };
+    return (new Hono()
+        // Every kind in one list: 04 Prompts filters by tab, and Duplicate needs the body it
+        // is copying (`logic/15` step 3).
+        .get("/", (c) => c.json({ prompts: listPrompts(deps.db) }))
+        .post("/", zValidator("json", promptBody, onInvalid), (c) => {
+        const result = createPrompt(library, c.req.valid("json"));
+        return result.ok ? c.json(result.value, 201) : refused(c, result, "prompt");
+    })
+        .put("/:id", zValidator("param", idParam, onInvalid), zValidator("json", promptBody, onInvalid), (c) => {
+        const result = updatePrompt(library, c.req.valid("param").id, c.req.valid("json"));
+        return result.ok ? c.json(result.value) : refused(c, result, "prompt");
+    })
+        // `logic/15` §Q123: a project holds its own rendered text, so nothing cascades and a
+        // template used by past projects is deleted like any other.
+        .delete("/:id", zValidator("param", idParam, onInvalid), (c) => {
+        const result = removePrompt(library, c.req.valid("param").id);
+        return result.ok ? c.body(null, 204) : refused(c, result, "prompt");
+    }));
+}
+// One refusal mapping for both libraries: `logic/15` §Q121 puts one rule set over
+// prompts and entries, so entryRoutes shares this rather than mirroring it.
+export function refused(c, failure, noun) {
+    switch (failure.reason) {
+        case "invalid":
+            return problem(c, {
+                status: 400,
+                title: titleOf(400),
+                detail: `This ${noun} cannot be saved; the listed fields need attention.`,
+                extensions: { fields: failure.fields },
+            });
+        // §Q122: the name is refused against a row that exists, and the form marks the field.
+        case "duplicate-name":
+            return problem(c, {
+                status: 409,
+                title: titleOf(409),
+                detail: `Another ${noun} already has this name.`,
+                extensions: {
+                    fields: [{ field: "name", message: `Another ${noun} already has this name.` }],
+                },
+            });
+        case "not-found":
+            return problem(c, {
+                status: 404,
+                title: titleOf(404),
+                detail: `No ${noun} has that id.`,
+            });
+    }
+}

package/dist/edge/http/providers.js

@@ -0,0 +1,62 @@
+import { zValidator } from "@hono/zod-validator";
+import { Hono } from "hono";
+import { z } from "zod";
+import { keyStatus, removeProviderKey, saveProviderKey } from "../../slices/settings/keys.js";
+import { providerById, providerIds } from "../../slices/settings/model.js";
+import { providerStatuses } from "../../slices/settings/readiness.js";
+import { onInvalid, problem, titleOf } from "./problem.js";
+const providerParam = z.object({ id: z.enum(providerIds) });
+// ceiling: `logic/02` §Q11 forbids any format check, so the only thing said about the
+// value is that it is a string of a length a key could plausibly have. Raise the bound
+// if a provider ever issues something longer.
+const keyBody = z.object({ key: z.string().min(1).max(4096) });
+// The return type is inferred so Hono keeps the route types the SPA's client is
+// generated from; see stagingRoutes.
+export function providerRoutes(deps) {
+    const keys = { db: deps.db, clock: deps.clock };
+    const readiness = { db: deps.db, probe: deps.probe };
+    return (new Hono()
+        // What Settings draws its rails from and Play its dropdowns: every provider, with
+        // the one fact that decides whether it is selectable (`logic/02` step 5, §Q135).
+        .get("/", async (c) => c.json({ providers: await providerStatuses(readiness) }))
+        .put("/:id/key", zValidator("param", providerParam, onInvalid), zValidator("json", keyBody, onInvalid), (c) => {
+        const { id } = c.req.valid("param");
+        const result = saveProviderKey(keys, id, c.req.valid("json").key);
+        if (!result.ok) {
+            return refusal(c, id, result.reason);
+        }
+        // The response says a key is stored and shows the mask, never the value.
+        return c.json(keyStatus(keys, id));
+    })
+        .delete("/:id/key", zValidator("param", providerParam, onInvalid), (c) => {
+        const { id } = c.req.valid("param");
+        const result = removeProviderKey(keys, id);
+        if (!result.ok) {
+            return refusal(c, id, result.reason);
+        }
+        return c.body(null, 204);
+    }));
+}
+function refusal(c, id, reason) {
+    const name = providerById(id).displayName;
+    if (reason === "cli-provider") {
+        return problem(c, {
+            status: 400,
+            title: titleOf(400),
+            detail: `${name} signs in through its own CLI, so there is no key to store here.`,
+        });
+    }
+    if (reason === "absent") {
+        return problem(c, {
+            status: 404,
+            title: titleOf(404),
+            detail: `No key is stored for ${name}.`,
+        });
+    }
+    return problem(c, {
+        status: 400,
+        title: titleOf(400),
+        detail: "This key cannot be saved; the listed fields need attention.",
+        extensions: { fields: [{ field: "key", message: "An API key is required." }] },
+    });
+}