@velora-cms/server 0.11.0

package/dist/routes/data-types.js

@@ -0,0 +1,100 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { ApiErrorSchema, CreateDataTypeRequestSchema, DataTypeListQuerySchema, DataTypeListResponseSchema, DataTypeResponseSchema, UpdateDataTypeRequestSchema, } from "@velora-cms/api-schemas";
+import { requireAuth } from "../auth/require-auth.js";
+import { validateDataTypeSettings } from "../data-types/validate-data-type-settings.js";
+const DataTypeIdParamsSchema = z.object({ id: z.string().uuid() });
+// Data Types: named, admin-created configurations of registry editors.
+// Auth tiers mirror document-types exactly (mutations need a JWT, reads
+// are public) — they're the same kind of schema object.
+export const dataTypeRoutes = async (app, opts) => {
+    const { adapter } = opts;
+    app.post("/api/data-types", {
+        onRequest: requireAuth,
+        schema: {
+            body: CreateDataTypeRequestSchema,
+            response: {
+                201: DataTypeResponseSchema,
+                400: ApiErrorSchema,
+                401: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const dataType = { id: randomUUID(), ...request.body };
+        const settingsErrors = validateDataTypeSettings(dataType.editorId, dataType.settings);
+        if (settingsErrors.length > 0) {
+            return reply.code(400).send({
+                message: `Invalid settings for editor "${dataType.editorId}": ${settingsErrors.join("; ")}`,
+            });
+        }
+        await adapter.createDataTypeConfig(dataType);
+        return reply.code(201).send({ dataType });
+    });
+    app.get("/api/data-types", {
+        schema: {
+            querystring: DataTypeListQuerySchema,
+            response: {
+                200: DataTypeListResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const { cursor, limit } = request.query;
+        const items = await adapter.listDataTypeConfigs({ cursor, limit });
+        const nextCursor = items.length === limit ? (items[items.length - 1]?.id ?? null) : null;
+        return { items, nextCursor };
+    });
+    app.get("/api/data-types/:id", {
+        schema: {
+            params: DataTypeIdParamsSchema,
+            response: {
+                200: DataTypeResponseSchema,
+                404: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const dataType = await adapter.getDataTypeConfig(request.params.id);
+        if (!dataType) {
+            return reply.code(404).send({ message: `No data type found with id ${request.params.id}` });
+        }
+        return { dataType };
+    });
+    // Partial update of the two mutable columns; editorId is immutable
+    // (absent from the request schema on purpose — see
+    // data-type-api.schema.ts).
+    app.patch("/api/data-types/:id", {
+        onRequest: requireAuth,
+        schema: {
+            params: DataTypeIdParamsSchema,
+            body: UpdateDataTypeRequestSchema,
+            response: {
+                200: DataTypeResponseSchema,
+                400: ApiErrorSchema,
+                401: ApiErrorSchema,
+                404: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const existing = await adapter.getDataTypeConfig(request.params.id);
+        if (!existing) {
+            return reply.code(404).send({ message: `No data type found with id ${request.params.id}` });
+        }
+        // Validate on every update, even name-only ones — a self-healing
+        // invariant once this ships (existing.settings is always valid
+        // going forward). If a built-in's settingsSchema ever tightens
+        // later, an old config with now-invalid stored settings would
+        // block until fixed.
+        const settings = request.body.settings ?? existing.settings;
+        const settingsErrors = validateDataTypeSettings(existing.editorId, settings);
+        if (settingsErrors.length > 0) {
+            return reply.code(400).send({
+                message: `Invalid settings for editor "${existing.editorId}": ${settingsErrors.join("; ")}`,
+            });
+        }
+        await adapter.updateDataTypeConfig(existing.id, {
+            name: request.body.name ?? existing.name,
+            settings,
+        });
+        const dataType = await adapter.getDataTypeConfig(existing.id);
+        return { dataType: dataType };
+    });
+};

package/dist/routes/docs-static.d.ts

@@ -0,0 +1,8 @@
+import type { FastifyInstance } from "fastify";
+interface DocsDirResolution {
+    dir: string | null;
+    invalidOverride: string | undefined;
+}
+export declare function resolveDocsDir(): DocsDirResolution;
+export declare function docsStaticRoutes(app: FastifyInstance): Promise<void>;
+export {};

package/dist/routes/docs-static.js

@@ -0,0 +1,137 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import fastifyStatic from "@fastify/static";
+import { rateLimitConfig } from "../auth/rate-limit.js";
+import { DOCS_RATE_LIMIT } from "../auth/route-rate-limits.js";
+// A usable docs directory: it must actually be a directory (not a file —
+// @fastify/static@10.1.2 throws "root must be a directory" at registration
+// otherwise, crashing buildApp()) and it must contain a "v1" edition — an
+// empty directory would otherwise resolve successfully and then serve bare
+// per-route 404s instead of the clear 404-with-cause.
+function isUsableDocsDir(candidate) {
+    try {
+        return statSync(candidate).isDirectory() && existsSync(join(candidate, "v1"));
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveDocsDir() {
+    const override = process.env.VELORA_DOCS_DIR;
+    if (override) {
+        // path.resolve() before anything else: @fastify/static@10.1.2 also
+        // throws ("root must be an absolute path") at registration when root
+        // is relative. Resolving against cwd up front means a relative
+        // override behaves the same as an absolute one instead of crashing
+        // boot.
+        const resolved = resolve(override);
+        if (isUsableDocsDir(resolved))
+            return { dir: resolved, invalidOverride: undefined };
+        return { dir: null, invalidOverride: override };
+    }
+    const here = dirname(fileURLToPath(import.meta.url)); // dist/routes or src/routes
+    const candidates = [
+        join(here, "..", "docs-bundle"),
+        join(here, "..", "..", "..", "..", "apps", "docs", "dist-bundle"),
+    ];
+    const dir = candidates.find((c) => isUsableDocsDir(c)) ?? null;
+    return { dir, invalidOverride: undefined };
+}
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+// The admin's always-visible Docs tab opens /docs/* directly in a browser
+// tab, so a degraded response there should be readable HTML, not raw JSON.
+// Anything else (headless API consumers, tests) keeps the existing JSON
+// shape.
+function wantsHtml(req) {
+    return (req.headers.accept ?? "").includes("text/html");
+}
+function sendDegraded(req, reply, message) {
+    if (wantsHtml(req)) {
+        return reply
+            .code(404)
+            .type("text/html")
+            .send(`<!doctype html><html><head><meta charset="utf-8"><title>Documentation unavailable</title></head>` +
+            `<body><h1>Documentation unavailable</h1><p>${escapeHtml(message)}</p></body></html>`);
+    }
+    return reply.code(404).send({ message });
+}
+export async function docsStaticRoutes(app) {
+    const { dir: docsDir, invalidOverride } = resolveDocsDir();
+    // S162: static-ish reads, but not unbounded — this family previously had
+    // no ceiling at all. Registered per-scope, matching the precedent in
+    // auth.ts/plugin-api-routes.ts/public-api.ts: @fastify/rate-limit
+    // decorates the instance, so it is registered in child scopes OR at the
+    // root, never both.
+    await app.register(import("@fastify/rate-limit"), rateLimitConfig);
+    // This module's routes serve static HTML/asset infra, not Zod-validated
+    // JSON — api-design.md's "every route needs a request/response schema"
+    // rule governs the Zod→OpenAPI chain, which these deliberately sit
+    // outside of. Hidden from Swagger up front (the same treatment
+    // public-api.ts gives mercurius's schema-less GraphiQL routes) rather
+    // than left to leak into the spec as bare, undocumented path entries.
+    app.addHook("onRoute", (routeOptions) => {
+        if (routeOptions.url.startsWith("/docs")) {
+            routeOptions.schema = { ...routeOptions.schema, hide: true };
+        }
+    });
+    // Exact-path redirects win over the wildcard the static handler adds.
+    // Fastify 5's Reply#redirect signature is (url, code), not (code, url) —
+    // verified against this repo's installed fastify@5.8.5 source
+    // (lib/reply.js), which differs from older Fastify majors.
+    const redirect = (reply) => reply.redirect("/docs/v1/", 302);
+    const docsRateLimit = { rateLimit: { max: DOCS_RATE_LIMIT.max(), timeWindow: DOCS_RATE_LIMIT.timeWindow() } };
+    app.get("/docs", { config: docsRateLimit }, async (_req, reply) => redirect(reply));
+    if (!docsDir) {
+        const message = invalidOverride
+            ? `VELORA_DOCS_DIR is set to "${invalidOverride}" but it is not usable (it must resolve to a ` +
+                'directory containing a "v1" edition). Fix the override or unset VELORA_DOCS_DIR to fall back ' +
+                "to the built-in bundle location."
+            : "The documentation bundle is not installed. Expected it inside the server build " +
+                "(dist/docs-bundle) or at VELORA_DOCS_DIR. Build with `turbo run build` to produce it.";
+        app.get("/docs/", { config: docsRateLimit }, async (req, reply) => sendDegraded(req, reply, message));
+        app.get("/docs/*", { config: docsRateLimit }, async (req, reply) => sendDegraded(req, reply, message));
+        app.log.warn("[docs-static] no docs bundle found — /docs/* will answer 404-with-cause");
+        return;
+    }
+    // Registering the static mount and its not-found handler inside their own
+    // encapsulated child context (rather than directly on `app`) confines
+    // setNotFoundHandler to routes under this context's prefix. Fastify scopes
+    // setNotFoundHandler by the context's prefix — calling it directly on
+    // `app` (prefix "") would replace the app-wide 404 (and its JSON shape)
+    // for every unmatched route, including /api/*. The prefix here is
+    // "/docs/" (trailing slash, not "/docs") deliberately: Fastify collapses
+    // a route path of "/" registered inside a prefixed context down to the
+    // bare prefix string itself, so a "/docs" prefix would make the child's
+    // `get("/", ...)` land on "/docs" — colliding with the exact `app.get
+    // ("/docs", ...)` redirect above. Using "/docs/" as the prefix makes that
+    // same collapse land exactly on "/docs/", which is what we want.
+    // Isolation is covered by docs-static.integration.test.ts's "does not
+    // leak the docs-scoped 404 handler onto unrelated routes" test (an
+    // unknown /api/... path keeps Fastify's default 404 shape) and its
+    // /api/health check in the no-bundle-installed case.
+    await app.register(async (docsApp) => {
+        docsApp.get("/", { config: docsRateLimit }, async (_req, reply) => redirect(reply));
+        await docsApp.register(fastifyStatic, {
+            root: docsDir,
+            decorateReply: false,
+            redirect: true, // /docs/v1 -> /docs/v1/ so index resolution works
+        });
+        // Unknown paths under /docs/ get the bundle's own 404 page when present.
+        docsApp.setNotFoundHandler((_req, reply) => {
+            const notFoundPage = join(docsDir, "404.html");
+            if (existsSync(notFoundPage)) {
+                // decorateReply: false means reply.sendFile isn't available here —
+                // read the bundle's 404 page directly and send it.
+                return reply.code(404).type("text/html").send(readFileSync(notFoundPage));
+            }
+            return reply.code(404).send({ message: "not found" });
+        });
+    }, { prefix: "/docs/" });
+}

package/dist/routes/document-types.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 documentTypeRoutes: FastifyPluginAsyncZod<ContentDb>;

package/dist/routes/document-types.js

@@ -0,0 +1,149 @@
+import { z } from "zod";
+import { ApiErrorSchema, CreateDocumentTypeRequestSchema, CreateDocumentTypeResponseSchema, DeleteDocumentTypeResponseSchema, DocumentTypeListQuerySchema, DocumentTypeListResponseSchema, SetDefaultTemplateRequestSchema, UpdateDocumentTypeRequestSchema, } from "@velora-cms/api-schemas";
+import { DocumentTypeInUseError, DocumentTypeService, DocumentTypeUnknownDataTypesError } from "@velora-cms/content-service";
+import { requireAuth } from "../auth/require-auth.js";
+const DocumentTypeIdParamsSchema = z.object({ id: z.string().uuid() });
+export const documentTypeRoutes = async (app, opts) => {
+    const { adapter } = opts;
+    const documentTypeService = new DocumentTypeService(adapter);
+    app.post("/api/document-types", {
+        onRequest: requireAuth,
+        schema: {
+            body: CreateDocumentTypeRequestSchema,
+            response: {
+                201: CreateDocumentTypeResponseSchema,
+                400: ApiErrorSchema,
+                401: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        try {
+            const documentType = await documentTypeService.createDocumentType(request.body);
+            return reply.code(201).send({ documentType });
+        }
+        catch (error) {
+            if (error instanceof DocumentTypeUnknownDataTypesError) {
+                return reply.code(400).send({ message: error.message });
+            }
+            throw error;
+        }
+    });
+    // Full edit of the mutable definition (Session 51). kind can never
+    // change (the strict schema has no kind key) and the default-template
+    // pointer is untouched — that stays with its dedicated PATCH below.
+    app.put("/api/document-types/:id", {
+        onRequest: requireAuth,
+        schema: {
+            params: DocumentTypeIdParamsSchema,
+            body: UpdateDocumentTypeRequestSchema,
+            response: {
+                200: CreateDocumentTypeResponseSchema,
+                400: ApiErrorSchema,
+                401: ApiErrorSchema,
+                404: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const existing = await adapter.getDocumentType(request.params.id);
+        if (!existing) {
+            return reply.code(404).send({ message: `No document type found with id ${request.params.id}` });
+        }
+        // treeRules semantics follow the STORED kind — the update schema
+        // can't know it.
+        if (existing.kind === "page" && !request.body.treeRules) {
+            return reply.code(400).send({ message: "treeRules is required when updating a page document type" });
+        }
+        if (existing.kind === "element" && request.body.treeRules) {
+            return reply.code(400).send({ message: "treeRules is not allowed on an element document type" });
+        }
+        const unknown = await documentTypeService.findUnknownDataTypeIds(request.body.fields);
+        if (unknown.length > 0) {
+            return reply.code(400).send({
+                message: `Unknown data type id(s): ${unknown.join(", ")}`,
+            });
+        }
+        await adapter.updateDocumentType(existing.id, {
+            name: request.body.name,
+            icon: request.body.icon,
+            fields: request.body.fields,
+            tabs: request.body.tabs,
+            treeRules: request.body.treeRules,
+        });
+        const documentType = await adapter.getDocumentType(existing.id);
+        return { documentType: documentType };
+    });
+    // No cascade: content and templates both block the delete rather than
+    // being silently swept away (the project's no-silent-data-loss rule).
+    app.delete("/api/document-types/:id", {
+        onRequest: requireAuth,
+        schema: {
+            params: DocumentTypeIdParamsSchema,
+            response: {
+                200: DeleteDocumentTypeResponseSchema,
+                401: ApiErrorSchema,
+                404: ApiErrorSchema,
+                409: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const existing = await adapter.getDocumentType(request.params.id);
+        if (!existing) {
+            return reply.code(404).send({ message: `No document type found with id ${request.params.id}` });
+        }
+        try {
+            await documentTypeService.assertDocumentTypeDeletable(existing.id);
+        }
+        catch (error) {
+            if (error instanceof DocumentTypeInUseError) {
+                const message = error.reason === "has-content"
+                    ? `${error.contentCount} content item(s) use this document type — delete or move them first`
+                    : "This document type still has templates — remove them first";
+                return reply.code(409).send({ message });
+            }
+            throw error;
+        }
+        // S154: deleteDocumentType now purges any trashed content of this
+        // type first (the one real hard delete in the trash lifecycle — see
+        // DocumentTypeService.deleteDocumentType) before removing the type
+        // row itself. The guard above already passed once that content was
+        // trashed, since countContentByDocumentType excludes trashed rows.
+        await documentTypeService.deleteDocumentType(existing.id);
+        return { success: true };
+    });
+    app.get("/api/document-types", {
+        schema: {
+            querystring: DocumentTypeListQuerySchema,
+            response: {
+                200: DocumentTypeListResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const { cursor, limit } = request.query;
+        const items = await adapter.listDocumentTypes({ cursor, limit });
+        const nextCursor = items.length === limit ? (items[items.length - 1]?.id ?? null) : null;
+        return { items, nextCursor };
+    });
+    // Narrow, single-purpose pointer-update endpoint — a template can't
+    // exist before its document type does, so defaultTemplateId is never set
+    // at create time. Deliberately not a general document-type update route.
+    app.patch("/api/document-types/:id/default-template", {
+        onRequest: requireAuth,
+        schema: {
+            params: DocumentTypeIdParamsSchema,
+            body: SetDefaultTemplateRequestSchema,
+            response: {
+                200: CreateDocumentTypeResponseSchema,
+                401: ApiErrorSchema,
+                404: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const existing = await adapter.getDocumentType(request.params.id);
+        if (!existing) {
+            return reply.code(404).send({ message: `No document type found with id ${request.params.id}` });
+        }
+        await adapter.setDefaultTemplate(request.params.id, request.body.templateId);
+        const documentType = await adapter.getDocumentType(request.params.id);
+        return { documentType: documentType };
+    });
+};

package/dist/routes/headless-bridge.d.ts

@@ -0,0 +1,10 @@
+import type { DatabaseAdapter } from "@velora-cms/db-adapter";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+export declare function toContentPath(rawUrl: string): string | null;
+export declare function createFrameworkErrorHandler(): (error: Error & {
+    code?: string;
+    statusCode?: number;
+}, request: FastifyRequest, reply: FastifyReply) => void;
+export declare function registerHeadlessBridge(app: FastifyInstance, deps: {
+    adapter: DatabaseAdapter;
+}): void;

package/dist/routes/headless-bridge.js

@@ -0,0 +1,207 @@
+import { readFileSync } from "node:fs";
+import { STATUS_CODES } from "node:http";
+import { createRequire } from "node:module";
+import { isHeadlessEnabled } from "../config/headless.js";
+// S156: the honest-headless bridge. Velora is headless-first (the template
+// rendering engine is the v1.x epic) — until it lands, a content node's
+// URL on this host renders an explainer instead of a bare 404, and every
+// non-content path gets one neutral page that never leaks whether an
+// unpublished or trashed node exists there. Only GET + Accept: text/html
+// sees any of this; API consumers keep Fastify's stock JSON 404
+// byte-identical. Deliberately claims the app-wide not-found handler —
+// the docs-static.ts warning about doing so is exactly the intent here
+// (that handler is scoped to its own "/docs/" prefixed child context, so
+// it never collides with this app-wide one). registerHeadlessBridge below
+// covers ordinary unmatched routes; createFrameworkErrorHandler (wired into
+// Fastify's constructor-time `frameworkErrors` option in app.ts, not into
+// this function) covers the separate low-level "URL couldn't even be
+// routed" case find-my-way raises for hostile encodings — see its own doc
+// comment for why that needs a different hook entirely.
+// Rate limiting deferred to S162 (tracked for a future session).
+// tokens.css is generated at build time (not committed) — resolved through
+// the package's exported "./tokens.css" subpath (NOT dist/tokens.css, which
+// is not an exported subpath — recorded gotcha). A missing build must not
+// fail boot: the page degrades to its fallback values.
+function loadTokensCss() {
+    try {
+        const require = createRequire(import.meta.url);
+        return readFileSync(require.resolve("@velora-cms/design-tokens/tokens.css"), "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function wantsHtml(req) {
+    return (req.headers.accept ?? "").includes("text/html");
+}
+// True when `text` contains a C0 control character (code points 0-31,
+// i.e. NUL through unit separator). Written as a charCode scan rather
+// than a regex literal so no raw control-byte source text has to survive
+// tool round-tripping intact.
+function hasControlChars(text) {
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) <= 31)
+            return true;
+    }
+    return false;
+}
+// Normalizes the request URL into a candidate content path, or null when
+// it can't be one: undecodable escapes and control characters render the
+// neutral page rather than a 500.
+export function toContentPath(rawUrl) {
+    let pathname;
+    try {
+        pathname = decodeURIComponent(new URL(rawUrl, "http://placeholder").pathname);
+    }
+    catch {
+        return null;
+    }
+    if (hasControlChars(pathname))
+        return null;
+    if (pathname.length > 1 && pathname.endsWith("/"))
+        pathname = pathname.slice(0, -1);
+    return pathname;
+}
+// Real token names (packages/design-tokens/dist/tokens.css, generated by
+// `pnpm --filter @velora-cms/design-tokens build`): there is no --color-background
+// / --color-foreground / --color-muted / --color-primary pair — those were
+// placeholder guesses. The actual scale is --color-background-base,
+// --color-text-primary, --color-background-hover (used here as the
+// <code> block's fill), and --color-primary-600 (the 600 step reads as
+// "link" contrast against the light background token). Fallback values
+// are kept so a missing build still renders something reasonable.
+function pageHtml(tokensCss, content) {
+    return (`<!doctype html><html dir="auto"><head><meta charset="utf-8">` +
+        `<meta name="viewport" content="width=device-width, initial-scale=1">` +
+        `<meta name="robots" content="noindex">` +
+        `<title>${escapeHtml(content.title)} — Velora</title>` +
+        `<style>${tokensCss}` +
+        `body{margin:0;font-family:system-ui,sans-serif;background:var(--color-background-base,#f8fafc);` +
+        `color:var(--color-text-primary,#0f172a);display:grid;min-block-size:100vh;place-items:center}` +
+        `main{max-inline-size:40rem;padding-block:2rem;padding-inline:1.5rem}` +
+        `h1{font-size:1.5rem;margin-block-end:.5rem}` +
+        `p{line-height:1.6;margin-block:.5rem}` +
+        `code{display:block;overflow-x:auto;padding-block:.75rem;padding-inline:1rem;` +
+        `border-radius:.5rem;background:var(--color-background-hover,#e2e8f0);font-size:.875rem}` +
+        `a{color:var(--color-primary-600,#2563eb)}` +
+        `.type{font-size:.875rem;opacity:.7}` +
+        `</style></head><body><main>${content.bodyHtml}</main></body></html>`);
+}
+function apiSectionHtml(origin, path) {
+    if (!isHeadlessEnabled()) {
+        return (`<p>The public content API is not enabled on this instance ` +
+            `(<code style="display:inline;padding:0">VELORA_HEADLESS</code> is off), so there is no ` +
+            `public URL for this content. An administrator can enable it at deploy time.</p>`);
+    }
+    const byPathUrl = `${origin}/api/v1/content/by-path?path=${encodeURIComponent(path)}`;
+    return (`<p>Fetch it from the headless API (requests need an API key):</p>` +
+        `<code>${escapeHtml(byPathUrl)}</code>` +
+        `<p>GraphQL is available at <code style="display:inline;padding:0">/api/v1/graphql</code>.</p>`);
+}
+// The one neutral page shared by missing, unpublished, and trashed paths —
+// existence is never leaked. The copy doubles as the instance's front door
+// (this is also what "/" renders).
+function neutralPageContent() {
+    const bodyHtml = `<h1>This is a headless Velora CMS</h1>` +
+        `<p>Nothing is published at this URL. Content on this instance is not rendered ` +
+        `into pages here — it is served through the API to a frontend of your choice ` +
+        `(see the starter frontends in the documentation).</p>` +
+        `<p><a href="/docs/v1/">Documentation</a></p>`;
+    return { title: "Headless Velora", bodyHtml };
+}
+// True for requests this bridge answers at all: a browser-tab GET outside
+// /api (which keeps its own JSON 404s — /docs and /plugin-assets have
+// their own scoped handlers and never reach either handler below).
+function isBridgedRequest(request) {
+    return request.method === "GET" && wantsHtml(request) && !(request.raw.url ?? "").startsWith("/api/");
+}
+// find-my-way rejects some malformed URLs (a lone "%ff" with no valid UTF-8
+// decoding, "%00", etc.) at the routing layer itself — before Fastify ever
+// builds a matched or not-found route. Verified against the installed
+// fastify@5.8.5 source (fastify.js's onBadUrl): with no `frameworkErrors`
+// option, that path answers via a raw `res.writeHead(400, ...); res.end(...)`
+// call that bypasses setNotFoundHandler, setErrorHandler, hooks — everything
+// — so setNotFoundHandler alone (the brief's original sketch) can never see
+// or reshape this case. `frameworkErrors`, a Fastify constructor-time-only
+// option, is the one hook the framework offers into that path; it also
+// covers FST_ERR_ASYNC_CONSTRAINT (unreachable here — this app registers no
+// route constraints), so anything other than a bridged bad-url request
+// reproduces Fastify's own no-frameworkErrors JSON body/status exactly,
+// changing nothing this bridge doesn't own.
+export function createFrameworkErrorHandler() {
+    const tokensCss = loadTokensCss();
+    return (error, request, reply) => {
+        if (error.code === "FST_ERR_BAD_URL" && isBridgedRequest(request)) {
+            reply.header("X-Robots-Tag", "noindex");
+            reply.header("Cache-Control", "no-store");
+            reply.code(404).type("text/html").send(pageHtml(tokensCss, neutralPageContent()));
+            return;
+        }
+        const statusCode = error.statusCode ?? 500;
+        reply.code(statusCode).send({
+            error: STATUS_CODES[statusCode] ?? "Internal Server Error",
+            code: error.code,
+            message: error.message,
+            statusCode,
+        });
+    };
+}
+export function registerHeadlessBridge(app, deps) {
+    const tokensCss = loadTokensCss();
+    if (!tokensCss) {
+        app.log.warn("[headless-bridge] tokens.css not found — explainer pages use fallback styling");
+    }
+    app.setNotFoundHandler(async (request, reply) => {
+        if (!isBridgedRequest(request)) {
+            const message = `Route ${request.method}:${request.url} not found`;
+            // Fastify's default 404 handler logs this line; keep parity so
+            // operators grepping for it don't lose unmatched-route visibility.
+            request.log.info(message);
+            return reply.code(404).send({
+                message,
+                error: "Not Found",
+                statusCode: 404,
+            });
+        }
+        reply.header("X-Robots-Tag", "noindex");
+        reply.header("Cache-Control", "no-store");
+        const path = toContentPath(request.url);
+        try {
+            const node = path
+                ? await deps.adapter.getContentNodeByPath(path, { publishedOnly: true })
+                : null;
+            if (!node || !path) {
+                return reply.code(404).type("text/html").send(pageHtml(tokensCss, neutralPageContent()));
+            }
+            const label = path.split("/").filter(Boolean).pop() ?? path;
+            const documentType = await deps.adapter.getDocumentType(node.documentTypeId);
+            const origin = `${request.protocol}://${request.headers.host ?? "localhost"}`;
+            const bodyHtml = `<h1>${escapeHtml(label)}</h1>` +
+                (documentType ? `<p class="type">${escapeHtml(documentType.name)}</p>` : "") +
+                `<p>This content exists — but this Velora instance is headless, so content URLs ` +
+                `don't render pages on this host.</p>` +
+                apiSectionHtml(origin, path) +
+                `<p><a href="/docs/v1/">Documentation</a></p>`;
+            return reply.code(200).type("text/html").send(pageHtml(tokensCss, { title: label, bodyHtml }));
+        }
+        catch (error) {
+            // A rejected adapter call (e.g. a dropped DB connection) must never
+            // reach Fastify's default error handler here: this is the public
+            // origin, and that handler serializes err.message — a raw adapter/DB
+            // error string — into a 500 body for an anonymous visitor. The
+            // neutral 404 is the correct degraded answer: it's already what
+            // "genuinely nothing here" and "can't tell" both render as, so a
+            // lookup failure just joins that same bucket rather than leaking
+            // internals or the fact that a lookup was attempted at all.
+            app.log.error({ err: error }, "[headless-bridge] adapter lookup failed; degrading to the neutral 404");
+            return reply.code(404).type("text/html").send(pageHtml(tokensCss, neutralPageContent()));
+        }
+    });
+}

package/dist/routes/health.d.ts

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

package/dist/routes/health.js

@@ -0,0 +1,15 @@
+import { HealthCheckSchema } from "@velora-cms/api-schemas";
+export const healthRoutes = async (app) => {
+    app.get("/api/health", {
+        schema: {
+            response: {
+                200: HealthCheckSchema,
+            },
+        },
+    }, async () => {
+        return {
+            status: "ok",
+            timestamp: new Date().toISOString(),
+        };
+    });
+};

package/dist/routes/marketplace-proxy.d.ts

@@ -0,0 +1,8 @@
+import type { FastifyPluginAsyncZod } from "fastify-type-provider-zod";
+import type { DatabaseAdapter } from "@velora-cms/db-adapter";
+export interface MarketplaceProxyOptions {
+    marketplaceBaseUrl: string;
+    activeDialect: string;
+    adapter: DatabaseAdapter;
+}
+export declare const marketplaceProxyRoutes: FastifyPluginAsyncZod<MarketplaceProxyOptions>;