@velora-cms/server 0.11.0

package/dist/routes/setup.js

@@ -0,0 +1,477 @@
+import { ApiErrorSchema, SetupCompleteRequestSchema, SetupCompleteResponseSchema, SetupStatusResponseSchema } from "@velora-cms/api-schemas";
+import { clientDirFor } from "../scripts/generate-prisma-clients.js";
+import { loadPrismaClient } from "../db/load-prisma-client.js";
+import { buildConnectionString } from "../setup/build-connection-string.js";
+import { provisionDatabase } from "../setup/provision-database.js";
+import { persistDatabaseConfig } from "../setup/persist-env-config.js";
+import { hashPassword } from "../auth/tokens.js";
+import { listBundledTemplates } from "../setup/bundled-templates.js";
+import { installStarterTemplate } from "../setup/install-starter.js";
+import { SETUP_RATE_LIMIT, ipOnlyRateLimitConfig } from "../auth/route-rate-limits.js";
+import { resolveEnvFilePath } from "../config/env-file-path.js";
+import { dialectFromUrlScheme } from "../db/content-db.js";
+import { applyCoreMigrations } from "../db/core-migrations/index.js";
+import { ensurePrismaClientGenerated } from "../setup/ensure-prisma-client.js";
+import { ADMIN_PROBE_TIMEOUT_MS, countAdminUsers, withTimeout } from "../boot/resolve-boot-mode.js";
+// F6 (fix wave 1)/M3: named so the 409/503 message literals exist exactly
+// once each, and tests assert against these constants instead of
+// duplicating the string or matching a regex against it.
+export const SETUP_ALREADY_COMPLETED_MESSAGE = "Setup has already been completed.";
+export const SETUP_PROBE_FAILED_MESSAGE = "Could not verify whether setup has already been completed. Try again.";
+// M2: the two pairing guards below constrain `database` (the request
+// body), not DATABASE_URL (the environment) — they cannot, by themselves,
+// prove process.env.DATABASE_URL is actually set. In production
+// opts.databaseConfigured: true is passed by index.ts after
+// resolveBootMode() (boot/resolve-boot-mode.ts) confirmed DATABASE_URL is
+// set (the setup-admin-only path), and also by app.ts's own registration
+// of this same route with { setupRequired: false, databaseConfigured:
+// true } (the already-fully-configured, buildApp() path — DATABASE_URL is
+// always set there too, or buildApp() itself would already have failed
+// elsewhere). Harmless in both real callers because the 409
+// already-completed guard fires first on that second path, but
+// buildSetupOnlyApp() is exported and callable with
+// { databaseConfigured: true } independently of either guarantee (tests
+// do exactly this) — so this message exists for the case where neither
+// production invariant holds.
+export const SETUP_MISCONFIGURED_DATABASE_URL_MESSAGE = "Setup is misconfigured: the database is reported as configured, but no database URL is set.";
+// Task 5 final follow-ups (S164 review), item 1: distinct from
+// SETUP_ALREADY_COMPLETED_MESSAGE on purpose. A setup_lock row and its
+// admin commit together (createFirstAdmin's own transaction, below), so a
+// setup_lock row surviving with zero admins can only mean an admin was
+// deleted after setup completed — the classic lost-password recovery.
+// Without this distinct message that state answered the ordinary "already
+// completed" 409 forever, with nothing naming setup_lock as the cause and
+// no way back in. See createFirstAdmin's SetupLockWedgedError.
+export const SETUP_LOCK_WEDGED_MESSAGE = "Setup cannot run: a setup_lock row exists but no admin account does. This only happens when an " +
+    "administrator account was deleted after setup had already completed. To recover, delete the single " +
+    "row (id = 1) from the setup_lock table, then re-run setup.";
+/** Duck-typed on `.code`, same reasoning as
+ * marketplace/install-from-marketplace.ts's own isUniqueConstraintViolation:
+ * the client loaded here comes from a per-dialect generated module
+ * (db/load-prisma-client.ts), a different module instance than any
+ * statically imported `@prisma/client`, so `instanceof
+ * Prisma.PrismaClientKnownRequestError` would always be false across that
+ * boundary. `.code` is stable regardless of which client instance threw. */
+function isUniqueConstraintViolation(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "P2002";
+}
+// Task 5 final follow-ups (S164 review), item 1: thrown by createFirstAdmin
+// when it can prove the setup_lock sentinel is wedged (row present, zero
+// admins) rather than just an ordinary concurrent loser. Caught at the
+// route call site below and mapped to SETUP_LOCK_WEDGED_MESSAGE instead of
+// SETUP_ALREADY_COMPLETED_MESSAGE. Not exported: nothing outside this
+// module needs to name it, only catch it.
+class SetupLockWedgedError extends Error {
+}
+// F3 (fix wave 2, S164 review): creates the first admin as one atomic
+// unit, GUARANTEED atomic on every Tier 1 dialect — not just narrowed —
+// unlike fix wave 1's count-and-create-in-one-$transaction, which this
+// replaces.
+//
+// Fix wave 1's claim was wrong: a Prisma interactive transaction inherits
+// the database's default isolation (READ COMMITTED on Postgres,
+// REPEATABLE READ on MySQL), and a plain COUNT is a non-locking snapshot
+// read with no phantom protection for a later INSERT in the same
+// transaction. Reproduced live — two genuinely concurrent
+// createFirstAdmin-shaped transactions, each on its own connection,
+// BOTH committed a create on both postgresql and mysql, at gaps from 5ms
+// to 200ms. Only SQLite hid this, because Prisma's single-connection pool
+// serializes every write there regardless of isolation level — the one
+// dialect fix wave 1's own test exercised. That test was a sequential
+// stale-read scenario (any isolation level handles that); it was never
+// evidence of atomicity under real concurrency.
+//
+// The fix: SetupLock (prisma/schema.prisma) is a fixed-PK singleton row.
+// Every completion — admin-only AND setup-full, closing M-3 as well as F3
+// since neither branches on mode anymore — inserts it unconditionally,
+// inside the same transaction as the admin count/create. A PK insert is
+// enforced by the storage engine itself: a second concurrent INSERT of
+// the same key value blocks until the first inserting transaction
+// resolves, then fails with a real unique-constraint violation (P2002) if
+// it committed — on every Tier 1 dialect, regardless of isolation level.
+// That is a fundamentally different guarantee than a COUNT snapshot read,
+// which is why this closes the race a plain count-and-create could not.
+//
+// Task 5 final follow-ups (S164 review), item 3: this only holds for as
+// long as the WINNER's transaction stays inside Prisma's default 5-second
+// interactive-transaction timeout. Past that window the loser's blocked
+// INSERT sees the winner's transaction time out and roll back rather than
+// commit, so the loser's own statement resolves with no conflict at all —
+// or, if the loser's OWN transaction is what times out while still
+// blocked, Prisma raises P2028 instead of P2002. Neither is caught by
+// isUniqueConstraintViolation below, so it is rethrown out of this
+// function and — uncaught by the route handler beyond that — becomes an
+// undeclared 500 rather than this function's 409. Still fail-closed (no
+// second admin either way, since one of the two writes always loses), just
+// a different status code once a transaction runs that long.
+async function createFirstAdmin(client, admin) {
+    const data = {
+        email: admin.email,
+        name: admin.name,
+        passwordHash: await hashPassword(admin.password),
+        role: "admin",
+    };
+    try {
+        return await client.$transaction(async (tx) => {
+            const existingAdmins = await tx.user.count({ where: { role: "admin" } });
+            if (existingAdmins > 0)
+                return null;
+            // The loser of a genuine concurrent race throws P2002 here, caught
+            // below — this is what actually closes the window; the count above
+            // is only what makes an ALREADY-admin'd database (a pre-existing
+            // admin-only install predating this fix, which never got a
+            // SetupLock row) refuse without needing the sentinel at all.
+            await tx.setupLock.create({ data: { id: 1 } });
+            return tx.user.create({ data });
+        });
+    }
+    catch (err) {
+        if (isUniqueConstraintViolation(err)) {
+            // Task 5 final follow-ups (S164 review), item 1: the transaction
+            // above just aborted on the storage engine's own P2002 — on Postgres
+            // in particular, an aborted transaction refuses every further
+            // statement until it rolls back, so there is no way to keep reading
+            // INSIDE it. This recount is therefore its own separate read against
+            // `client`, taken after that rollback has already happened.
+            //
+            // A count of zero here is provable evidence of the wedge: the
+            // sentinel and its admin always commit together (same transaction,
+            // above), so a P2002 on the sentinel with STILL zero admins means
+            // the row that P2002 collided with cannot have been created by a
+            // request racing this one — it can only be a sentinel left behind by
+            // an admin that existed and was later deleted. A non-zero count
+            // means an admin exists right now — either a genuine concurrent
+            // winner, or a pre-existing admin — the ordinary case.
+            //
+            // This has its own (narrower) race: a genuine concurrent winner
+            // could still be between its P2002-causing commit and this recount,
+            // in which case this recount could read 0 and misreport an ordinary
+            // race as a wedge. It cannot misreport in the other direction — an
+            // ordinary winner's commit is exactly what would make this count
+            // non-zero — so the mistake this leaves possible is a false wedge
+            // report, never a false "all clear," and either outcome still
+            // refuses with a 409 and creates no second admin.
+            const adminsNow = await client.user.count({ where: { role: "admin" } });
+            if (adminsNow === 0)
+                throw new SetupLockWedgedError();
+            return null;
+        }
+        throw err;
+    }
+}
+// Registered by BOTH apps: buildApp() with setupRequired: false (a
+// fully-configured instance answering "no, setup already happened"),
+// buildSetupOnlyApp() with setupRequired: true — one shared route
+// definition instead of two near-identical copies. Session 164 adds a
+// third caller shape: buildSetupOnlyApp({ databaseConfigured: true }),
+// the admin-only mode — still setupRequired: true (the wizard is still
+// running), but with a database already injected and read-only.
+export const setupRoutes = async (app, opts) => {
+    // F2 (fix wave 1): closes the setup-completion window for as long as
+    // THIS registered app instance keeps running, without waiting for a
+    // restart. In production index.ts builds exactly one app per boot
+    // (buildApp() or buildSetupOnlyApp(), never both), so this closure's
+    // lifetime IS the process's lifetime — "in-process latch." Scoped to
+    // this plugin registration rather than module scope so every
+    // independently built app (every test that calls buildSetupOnlyApp()/
+    // buildTestApp() gets its own fresh app) starts with its own latch too;
+    // a module-level flag would leak between unrelated app instances built
+    // in the same test process. Set the moment a completion actually
+    // succeeds, below, and checked at entry here — before the setupRequired
+    // check reads the boot-time flag opts.setupRequired never changes for
+    // the lifetime of this closure, which is exactly why a request-time
+    // re-check was needed at all (S164 final review of Task 4): without it,
+    // a first legitimate completion would not close this endpoint on its
+    // own — it would keep accepting unauthenticated admin-creation/database-
+    // provisioning requests until the next restart.
+    let setupCompleted = false;
+    // S162: an unauthenticated POST that provisions a database and creates
+    // the first admin. It 409s on an already-configured instance (S151), so
+    // the ceiling is about making the pre-configuration window uninteresting
+    // to probe, not about the configured steady state.
+    //
+    // ipOnlyRateLimitConfig() (I6, S162 final review; reshaped into a builder
+    // by Session 163's gate run), not the shared three-lane rateLimitConfig: this
+    // scope is also registered inside buildSetupOnlyApp() (setup-app.ts), the
+    // not-yet-configured boot path documented as never touching Prisma.
+    // rateLimitConfig imports auth/api-keys.ts -> db/prisma.ts, which has a
+    // top-level `await loadPrismaClient(...)` — importing it here would make
+    // that documented invariant false. Setup has no API keys or JWT sessions
+    // to lane anyway, so the plain IP-keyed config costs nothing behaviorally.
+    //
+    // Called here, not passed as a bare reference: it's a builder function now
+    // (route-rate-limits.ts), not a plain object, so the plugin receives the
+    // built options object — evaluated at this exact registration point, same
+    // read-timing as before the reshape.
+    await app.register(import("@fastify/rate-limit"), ipOnlyRateLimitConfig());
+    app.get("/api/setup/status", {
+        schema: {
+            response: {
+                200: SetupStatusResponseSchema,
+            },
+        },
+    }, async () => ({
+        setupRequired: opts.setupRequired,
+        // Only offered while setup is actually in progress — a
+        // fully-configured instance (setupRequired: false) has nothing left
+        // to pick a starter template for, so this route never bothers
+        // resolving the bundle on that path.
+        bundledTemplates: opts.setupRequired ? listBundledTemplates() : [],
+        databaseConfigured: opts.databaseConfigured,
+    }));
+    app.post("/api/setup/complete", {
+        schema: {
+            body: SetupCompleteRequestSchema,
+            response: {
+                200: SetupCompleteResponseSchema,
+                400: ApiErrorSchema,
+                409: ApiErrorSchema,
+                500: ApiErrorSchema,
+                503: ApiErrorSchema,
+            },
+        },
+        config: { rateLimit: { max: SETUP_RATE_LIMIT.max(), timeWindow: SETUP_RATE_LIMIT.timeWindow() } },
+    }, async (request, reply) => {
+        // buildApp() registers this route with setupRequired: false — on a
+        // configured instance, completing setup again would let any
+        // unauthenticated caller provision an attacker-supplied database,
+        // create their own admin in it, and REWRITE the real .env. Refuse
+        // before any provisioning side effect. setupCompleted (F2 above)
+        // answers the identical 409 once THIS app instance has already
+        // completed setup once, even though opts.setupRequired itself never
+        // changes.
+        if (!opts.setupRequired || setupCompleted) {
+            return reply.code(409).send({ message: SETUP_ALREADY_COMPLETED_MESSAGE });
+        }
+        const { admin, database, starter } = request.body;
+        // The pairing is enforced here, not by the schema, and in BOTH
+        // directions. Accepting-and-ignoring a selection would let an
+        // operator believe they had changed the database when the injected
+        // DATABASE_URL is what actually stands.
+        if (opts.databaseConfigured && database) {
+            return reply.code(400).send({
+                message: "The database is already configured by the environment and cannot be changed here. " +
+                    "Remove the database selection from this request.",
+            });
+        }
+        if (!opts.databaseConfigured && !database) {
+            return reply.code(400).send({ message: "A database selection is required to complete setup." });
+        }
+        // Security fix (S164 final review of Task 4): opts.setupRequired /
+        // opts.databaseConfigured are frozen at BOOT — read once by
+        // index.ts's call into resolveBootMode() (boot/resolve-boot-mode.ts)
+        // and handed to whichever app got built. In admin-only mode this
+        // route stays registered, and therefore reachable, for as long as
+        // the process keeps running. Without this re-check, a first
+        // legitimate call that creates the admin would not close this
+        // endpoint: it would stay an unauthenticated "provision + create
+        // admin + rewrite DATABASE_URL" route until someone restarts the
+        // process. Re-probing here, at request time, closes that window
+        // immediately instead of on the next boot. Reuses countAdminUsers
+        // (boot/resolve-boot-mode.ts) — the same admin-existence question
+        // resolveBootMode already answers at boot, not a second
+        // implementation of it. F4 (fix wave 1): bounded with the same
+        // withTimeout/ADMIN_PROBE_TIMEOUT_MS resolveBootMode uses for its
+        // own boot-time probe — an unbounded await here would hang the
+        // REQUEST forever on a wedged database (M-1, fix wave 2: withTimeout
+        // does not cancel the underlying countAdminUsers() promise or
+        // disconnect its client early — it only races a timer against it, so
+        // the client is held open until that probe eventually settles on its
+        // own. What this bound actually buys is that the CALLER stops
+        // waiting and gets a named 503 instead of a hang; it is not a
+        // resource-leak fix).
+        //
+        // This only applies in admin-only mode (opts.databaseConfigured &&
+        // opts.setupRequired — setup-full has no configured database to
+        // probe, and setupRequired: false already returned 409 above). This
+        // pre-check is a cheap, non-atomic optimization — it lets an
+        // already-configured instance reject FAST, before running `prisma db
+        // push` or opening a real connection for the create below, but it
+        // does not by itself close the race between two concurrent
+        // requests. createFirstAdmin's own sentinel-backed transaction
+        // (F3, fix wave 2, above) is what actually closes that race; this
+        // check just keeps the common case cheap.
+        if (opts.databaseConfigured) {
+            let admins;
+            try {
+                admins = await withTimeout(countAdminUsers(), ADMIN_PROBE_TIMEOUT_MS);
+            }
+            catch (err) {
+                // FAIL CLOSED, matching resolveBootMode's own doctrine
+                // (boot/resolve-boot-mode.ts): a probe that rejects must never
+                // be read as "no admin yet" — that misreading is exactly the
+                // hole Task 4's review caught one level up, at boot. 503, not
+                // 400 or 500: this is neither a bad request nor a generic bug,
+                // it is the server unable to confirm whether setup is still
+                // open, and the operator should retry once the database answers.
+                app.log.error({ err }, "setup/complete: admin re-probe failed");
+                return reply.code(503).send({ message: SETUP_PROBE_FAILED_MESSAGE });
+            }
+            // Same "resolved but not a real count" doctrine as
+            // resolveBootMode: NaN, a negative number, or anything else that
+            // isn't a non-negative integer must refuse, not be treated as
+            // zero.
+            if (!Number.isInteger(admins) || admins < 0) {
+                app.log.error({ admins }, "setup/complete: admin re-probe resolved with a non-count value");
+                return reply.code(503).send({ message: SETUP_PROBE_FAILED_MESSAGE });
+            }
+            if (admins > 0) {
+                return reply.code(409).send({ message: SETUP_ALREADY_COMPLETED_MESSAGE });
+            }
+        }
+        // In admin-only mode the URL comes from the environment, already
+        // normalised in index.ts. M2 (fix wave 1): the two pairing guards
+        // above make exactly one of these branches reachable IN PRODUCTION —
+        // `database` is defined whenever opts.databaseConfigured is false,
+        // and DATABASE_URL is guaranteed set whenever it's true, because
+        // that is what "databaseConfigured" means (see BootMode /
+        // resolveBootMode in boot/resolve-boot-mode.ts, and index.ts's call
+        // into buildSetupOnlyApp). But that guarantee lives in index.ts, not
+        // in this function's own inputs — buildSetupOnlyApp() is exported
+        // and callable with { databaseConfigured: true } independently of
+        // it (tests do exactly this), so a bare `!` here would trade a
+        // declared, tested 500 for an undeclared, untested one the moment
+        // that external guarantee doesn't hold. Checked explicitly instead.
+        let databaseUrl;
+        if (database) {
+            databaseUrl = buildConnectionString(database);
+        }
+        else if (process.env.DATABASE_URL) {
+            databaseUrl = process.env.DATABASE_URL;
+        }
+        else {
+            return reply.code(500).send({ message: SETUP_MISCONFIGURED_DATABASE_URL_MESSAGE });
+        }
+        const dialect = database?.dialect ?? dialectFromUrlScheme(databaseUrl);
+        if (!dialect) {
+            return reply.code(400).send({
+                message: `The configured DATABASE_URL does not name a supported database (${databaseUrl.split(":")[0]}:).`,
+            });
+        }
+        try {
+            // Runs on BOTH paths. `prisma db push` is idempotent, and an
+            // injected DATABASE_URL may point at a completely empty database —
+            // without this, the admin create below would fail on a missing
+            // table. S185: the Prisma client self-heal runs first — not
+            // because `db push --skip-generate` itself needs a generated
+            // client (it doesn't), but because the `loadPrismaClient(
+            // clientDirFor(dialect))` call a few lines below this block does —
+            // and the core-migration ledger is recorded in "fresh-push" mode
+            // right after — db push just created the CURRENT schema from
+            // scratch, so every step is already reflected and gets recorded
+            // without executing any SQL.
+            await ensurePrismaClientGenerated(dialect);
+            await provisionDatabase(dialect, databaseUrl);
+            await applyCoreMigrations({ dialect, databaseUrl, mode: "fresh-push" });
+        }
+        catch (err) {
+            return reply.code(400).send({ message: err instanceof Error ? err.message : "Failed to provision database" });
+        }
+        const client = await loadPrismaClient(clientDirFor(dialect), databaseUrl);
+        // The optional starter install (Session 151) needs both the created
+        // admin row's id (sample content's createdBy) and the still-connected
+        // client, so the disconnect moved from around the create alone to
+        // after the whole block. Without a starter this executes exactly the
+        // operations it always did — create, disconnect, persist — nothing
+        // content-db-shaped ever runs on the skip path.
+        let starterResult;
+        let adminUser = null;
+        // Task 5 final follow-ups (S164 review), item 1: set only when
+        // createFirstAdmin proved the setup_lock sentinel is wedged (see its
+        // own comment) — distinct from the ordinary `!adminUser` refusal
+        // below, which covers both "an admin already exists" and "an
+        // ordinary concurrent loser."
+        let wedged = false;
+        try {
+            // F3 (fix wave 2): unconditional now — see createFirstAdmin's own
+            // comment for why the sentinel-backed transaction applies to both
+            // modes, closing M-3 (setup-full vs. setup-full) as well as the
+            // original admin-only race.
+            try {
+                adminUser = await createFirstAdmin(client, admin);
+            }
+            catch (err) {
+                if (err instanceof SetupLockWedgedError) {
+                    wedged = true;
+                }
+                else {
+                    throw err;
+                }
+            }
+            // M-2 (fix wave 2): latched immediately after a real create
+            // succeeds — inside this try, before the starter install and
+            // before $disconnect() below. Fix wave 1 set this flag only after
+            // the whole try/finally returned, which left a window: if
+            // $disconnect() throws AFTER a successful create, the handler 500s
+            // with setupCompleted still false, reopening (for setup-full) the
+            // exact unauthenticated-completion window F2 exists to close. A
+            // starter failure below still can't unwind the admin account or
+            // the database config (installStarterTemplate never throws), so
+            // latching before it runs is safe.
+            if (adminUser) {
+                setupCompleted = true;
+            }
+            if (adminUser && starter) {
+                // Never throws — a starter failure is reported in the response,
+                // it must not unwind the admin account or the database config.
+                starterResult = await installStarterTemplate({
+                    prisma: client,
+                    databaseUrl,
+                    adminUserId: adminUser.id,
+                    starter,
+                });
+            }
+        }
+        finally {
+            await client.$disconnect();
+        }
+        if (wedged) {
+            // Task 5 final follow-ups (S164 review), item 1: named and logged
+            // so an operator locked out by a deleted admin has both a
+            // diagnosable response and a server-side record of when/why —
+            // unlike the silent, indistinguishable 409 this replaces.
+            app.log.error({ attemptedEmail: admin.email }, "setup/complete: setup_lock sentinel exists with zero admins — an admin was likely deleted after setup completed");
+            return reply.code(409).send({ message: SETUP_LOCK_WEDGED_MESSAGE });
+        }
+        if (!adminUser) {
+            // F3: the atomic transaction's own count/sentinel saw an admin
+            // that did not exist when the cheap pre-check ran above — another
+            // request, in this same process, won the race and created it
+            // first. Same 409 shape as every other "setup already completed"
+            // answer.
+            return reply.code(409).send({ message: SETUP_ALREADY_COMPLETED_MESSAGE });
+        }
+        // Only the setup-full path has anything to persist. In admin-only
+        // mode DATABASE_URL was already set at boot — by the environment or
+        // by a previous run's env file — so there is nothing new to write,
+        // and writing would risk contradicting what the next restart is
+        // injected with. See BootMode / resolveBootMode in
+        // boot/resolve-boot-mode.ts.
+        let configWarning;
+        if (!opts.databaseConfigured) {
+            try {
+                persistDatabaseConfig(databaseUrl);
+            }
+            catch (err) {
+                // Never unwind. The admin row and any starter install have
+                // already succeeded, and throwing here would lose them while
+                // leaving the database provisioned — the same reasoning the
+                // starter failure path uses a few lines above. Report it
+                // instead, naming the resolved path, so the operator can set
+                // DATABASE_URL themselves and restart.
+                configWarning =
+                    `Setup finished, but the configuration could not be saved to ${resolveEnvFilePath()}: ` +
+                        `${err instanceof Error ? err.message : String(err)}. ` +
+                        "Set DATABASE_URL in the environment before restarting, or this instance will run setup again.";
+            }
+        }
+        // `starter` and `configWarning` stay ABSENT (not null) when there is
+        // nothing to report, keeping the ordinary response byte-identical to
+        // the pre-Session-164 shape.
+        return {
+            success: true,
+            ...(starterResult ? { starter: starterResult } : {}),
+            ...(configWarning ? { configWarning } : {}),
+        };
+    });
+};

package/dist/routes/snapshots.d.ts

@@ -0,0 +1,3 @@
+import type { FastifyPluginAsyncZod } from "fastify-type-provider-zod";
+import type { ContentDb } from "../db/content-db.js";
+export declare const snapshotRoutes: FastifyPluginAsyncZod<ContentDb>;

package/dist/routes/snapshots.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { SnapshotService } from "@velora-cms/content-service";
+import { ApiErrorSchema, CreateSnapshotRequestSchema, RestoreSnapshotResponseSchema, SnapshotListQuerySchema, SnapshotListResponseSchema, SnapshotResponseSchema, } from "@velora-cms/api-schemas";
+import { requireAdmin } from "../auth/require-auth.js";
+const SnapshotParamsSchema = z.object({ id: z.string().uuid() });
+// Everything here is admin-only: a snapshot restore repoints every content
+// node's published pointer at once — system-level blast radius, same
+// gating tier as user management.
+export const snapshotRoutes = async (app, opts) => {
+    const snapshotService = new SnapshotService(opts.adapter);
+    app.post("/api/snapshots", {
+        onRequest: requireAdmin,
+        schema: {
+            body: CreateSnapshotRequestSchema,
+            response: {
+                201: SnapshotResponseSchema,
+                401: ApiErrorSchema,
+                403: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const { items: _items, ...meta } = await snapshotService.createSnapshot(request.body.label, request.user.sub, request.body.description ?? null);
+        return reply.code(201).send({ snapshot: meta });
+    });
+    app.get("/api/snapshots", {
+        onRequest: requireAdmin,
+        schema: {
+            querystring: SnapshotListQuerySchema,
+            response: {
+                200: SnapshotListResponseSchema,
+                401: ApiErrorSchema,
+                403: ApiErrorSchema,
+            },
+        },
+    }, async (request) => {
+        const { cursor, limit } = request.query;
+        const items = await snapshotService.listSnapshots({ cursor, limit });
+        const nextCursor = items.length === limit ? (items[items.length - 1]?.id ?? null) : null;
+        return { items, nextCursor };
+    });
+    app.post("/api/snapshots/:id/restore", {
+        onRequest: requireAdmin,
+        schema: {
+            params: SnapshotParamsSchema,
+            response: {
+                200: RestoreSnapshotResponseSchema,
+                401: ApiErrorSchema,
+                403: ApiErrorSchema,
+                404: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        try {
+            const restored = await snapshotService.restoreSnapshot(request.params.id);
+            const { items, ...meta } = restored;
+            return { snapshot: meta, restoredItems: items.length };
+        }
+        catch (error) {
+            if (error instanceof Error && /no snapshot found/i.test(error.message)) {
+                return reply.code(404).send({ message: error.message });
+            }
+            throw error;
+        }
+    });
+};

package/dist/routes/templates.d.ts

@@ -0,0 +1,3 @@
+import type { FastifyPluginAsyncZod } from "fastify-type-provider-zod";
+import type { ContentDb } from "../db/content-db.js";
+export declare const templateRoutes: FastifyPluginAsyncZod<ContentDb>;

package/dist/routes/templates.js

@@ -0,0 +1,37 @@
+import { randomUUID } from "node:crypto";
+import { ApiErrorSchema, CreateTemplateRequestSchema, CreateTemplateResponseSchema, TemplateListQuerySchema, TemplateListResponseSchema, } from "@velora-cms/api-schemas";
+import { requireAuth } from "../auth/require-auth.js";
+// Mirrors document-types.ts's shape exactly. Templates are genuinely inert
+// data at this point — no rendering engine consumes them yet (per the
+// Document Types tabs/preview/templates plan revision) — this just lets
+// a document type record which named template(s) exist for it.
+export const templateRoutes = async (app, opts) => {
+    const { adapter } = opts;
+    app.post("/api/templates", {
+        onRequest: requireAuth,
+        schema: {
+            body: CreateTemplateRequestSchema,
+            response: {
+                201: CreateTemplateResponseSchema,
+                401: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const template = { id: randomUUID(), ...request.body };
+        await adapter.createTemplate(template);
+        return reply.code(201).send({ template });
+    });
+    app.get("/api/templates", {
+        schema: {
+            querystring: TemplateListQuerySchema,
+            response: {
+                200: TemplateListResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const { cursor, limit, documentTypeId } = request.query;
+        const items = await adapter.listTemplates({ cursor, limit, documentTypeId });
+        const nextCursor = items.length === limit ? (items[items.length - 1]?.id ?? null) : null;
+        return { items, nextCursor };
+    });
+};

package/dist/routes/themes.d.ts

@@ -0,0 +1,2 @@
+import type { FastifyPluginAsyncZod } from "fastify-type-provider-zod";
+export declare const themeRoutes: FastifyPluginAsyncZod;

package/dist/routes/themes.js

@@ -0,0 +1,30 @@
+import { ThemeListResponseSchema } from "@velora-cms/api-schemas";
+import { prisma } from "../db/prisma.js";
+// Read-only, no auth (the GET /api/plugins posture): theme tokens are
+// cosmetic metadata. Rows are the source of WHICH themes are installed
+// and enabled; the attached manifest is the source of the tokens — a
+// row whose manifest isn't attached in this process (mid-install crash,
+// stale row) is skipped rather than served without tokens.
+//
+// No pagination: installed themes are a handful, never a growing content
+// or media list — the cursor rule (api-design.md) targets those, not this.
+export const themeRoutes = async (app) => {
+    app.get("/api/themes", { schema: { response: { 200: ThemeListResponseSchema } } }, async () => {
+        const rows = await prisma.pluginRegistry.findMany({
+            where: { enabled: true, type: "theme" },
+            orderBy: { id: "asc" },
+        });
+        const items = [];
+        for (const row of rows) {
+            const manifest = app.pluginRegistry.getManifest(row.pluginId);
+            if (!manifest || manifest.type !== "theme")
+                continue;
+            const tokens = manifest.contributions.themeTokens;
+            if (!tokens)
+                continue;
+            // ThemeTokenOverrides interface vs Record<string, unknown> assignability limitation
+            items.push({ pluginId: row.pluginId, name: row.name, author: manifest.author, tokens: tokens });
+        }
+        return { items };
+    });
+};

package/dist/routes/users.d.ts

@@ -0,0 +1,2 @@
+import type { FastifyPluginAsyncZod } from "fastify-type-provider-zod";
+export declare const usersRoutes: FastifyPluginAsyncZod;