@velora-cms/server 0.11.0

package/dist/routes/plugins.js

@@ -0,0 +1,36 @@
+import { PluginListQuerySchema, PluginListResponseSchema } from "@velora-cms/api-schemas";
+import { prisma } from "../db/prisma.js";
+// Read-only, no auth (matches GET /api/data-types — this is metadata,
+// not content). Always filters to enabled:true: an installed-but-inactive
+// plugin isn't a candidate for the admin's boot-time remote loader, the
+// only consumer today.
+export const pluginRoutes = async (app) => {
+    app.get("/api/plugins", {
+        schema: {
+            querystring: PluginListQuerySchema,
+            response: {
+                200: PluginListResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const { cursor, limit } = request.query;
+        const rows = await prisma.pluginRegistry.findMany({
+            where: { enabled: true },
+            orderBy: { id: "asc" },
+            take: limit,
+            ...(cursor ? { cursor: { id: cursor }, skip: 1 } : {}),
+        });
+        const items = rows.map((row) => ({
+            pluginId: row.pluginId,
+            name: row.name,
+            type: row.type,
+            version: row.version,
+            trustTier: row.trustTier,
+            storageType: row.storageType,
+            enabled: row.enabled,
+            remoteUrl: row.remoteUrl,
+        }));
+        const nextCursor = items.length === limit ? (rows[rows.length - 1]?.id ?? null) : null;
+        return { items, nextCursor };
+    });
+};

package/dist/routes/public-api.d.ts

@@ -0,0 +1,9 @@
+import type { FastifyPluginAsyncZod } from "fastify-type-provider-zod";
+import type { ContentDb } from "../db/content-db.js";
+import type { MediaService } from "../media/media-service.js";
+interface PublicApiRoutesOptions extends ContentDb {
+    mediaService: MediaService;
+    apiContentAuthorId: string;
+}
+export declare const publicApiRoutes: FastifyPluginAsyncZod<PublicApiRoutesOptions>;
+export {};

package/dist/routes/public-api.js

@@ -0,0 +1,545 @@
+import { createRequire } from "node:module";
+import { Ajv } from "ajv";
+import mercurius from "mercurius";
+import { z } from "zod";
+import { ApiErrorSchema, ContentValidationErrorSchema, PublicContentByPathQuerySchema, PublicContentFormatResponseSchema, PublicContentItemQuerySchema, PublicContentItemSchema, PublicContentListQuerySchema, PublicContentListResponseSchema, PublicContentSearchQuerySchema, PublicContentWriteResponseSchema, PublicCreateContentRequestSchema, PublicUpdateContentRequestSchema, PublicDocumentTypeListQuerySchema, PublicDocumentTypeListResponseSchema, PublicDocumentTypeSchema, PublicMediaFileSchema, PublicMediaListQuerySchema, PublicMediaListResponseSchema, PublicTemplateListQuerySchema, PublicTemplateListResponseSchema, } from "@velora-cms/api-schemas";
+import { ContentValidationError, DocumentTypeNotFoundForContentError, ParentContentNotFoundError, TreeRulesViolationError, } from "@velora-cms/content-service";
+import { requireApiKey, requireApiKeyScope } from "../auth/api-keys.js";
+import { verifyPreviewToken } from "../auth/preview-tokens.js";
+import { rateLimitConfig } from "../auth/rate-limit.js";
+import { isPublicDocsEnabled } from "../config/public-docs.js";
+import { maxQueryComplexity, maxQueryDepth } from "../config/graphql-limits.js";
+import { createFieldCountRule } from "../graphql/field-count-rule.js";
+import { buildGraphqlSchema } from "../graphql/schema.js";
+import { computeExtensions, isNotFoundError, preparePublishedItem, resolveItemNode, resolveSubtreeFilter, toPublicDocumentType, toPublicMediaFile, toSummaries, } from "./published-item.js";
+const PublicContentParamsSchema = z.object({ id: z.string().uuid() });
+// mercurius' own /api/v1/graphql routes carry plain JSON-Schema objects for
+// their request/response envelope (not Zod). This app's validatorCompiler/
+// serializerCompiler are set globally to fastify-type-provider-zod's Zod
+// compilers (app.ts), which unconditionally treat `schema` as a Zod object
+// and mis-validate anything else — every mercurius request failed
+// validation until these were wired in as a per-route override via
+// mercurius' `additionalRouteOptions` (Session 113, Task 2). Plain `ajv`,
+// already a direct dependency (see validate-data-type-settings.ts), stands
+// in for Fastify's own default compiler here.
+const mercuriusAjv = new Ajv({ allErrors: true, strict: false });
+const mercuriusValidatorCompiler = ({ schema }) => {
+    const validate = mercuriusAjv.compile(schema);
+    return (data) => {
+        if (validate(data))
+            return { value: data };
+        return { error: new Error(mercuriusAjv.errorsText(validate.errors)) };
+    };
+};
+// fast-json-stringify isn't wired up for this one-off route; a plain
+// JSON.stringify is a correct (if slower) response serializer, and
+// response payloads here are small.
+const mercuriusSerializerCompiler = () => {
+    return (data) => JSON.stringify(data);
+};
+// One uniform 404 body for every public miss — unknown id, unknown path,
+// draft, unpublished translation. Distinguishing them would let a keyed
+// caller probe which drafts exist.
+const NOT_FOUND_MESSAGE = "No published content found";
+// The public Content API namespace (Month 9). Registered by buildApp()
+// only when VELORA_HEADLESS is on — when off, none of these routes exist.
+// Every route is API-key gated (requireApiKey), never JWT. Strict
+// published-only rule: every node this surface touches — the anchor of a
+// locale resolution AND the resolved translation — must be published, so
+// drafts are indistinguishable from nonexistent everywhere. Exception: the
+// write routes (create/PUT/PATCH/publish, Session 107) operate on a node by
+// id in any publish state — a key holder is a trusted writer editing their
+// own draft, not an anonymous reader.
+export const publicApiRoutes = async (app, opts) => {
+    await app.register(import("@fastify/rate-limit"), rateLimitConfig);
+    const { adapter, contentService, mediaService, apiContentAuthorId } = opts;
+    // Shared by the by-id and by-path routes: apply locale resolution (same
+    // contract as the backoffice — fallback is a locale string), enforce the
+    // published-only rule on the resolved node, and load its pointer version.
+    async function sendPublishedItem(request, reply, anchor, query, previewContentId) {
+        const node = await resolveItemNode({ adapter, contentService }, anchor, { locale: query.locale, fallback: query.fallback }, { previewContentId });
+        if (!node) {
+            return reply.code(404).send({ message: NOT_FOUND_MESSAGE });
+        }
+        // Passed in AFTER locale resolution, against the FINAL resolved
+        // node — `preparePublishedItem` itself only bypasses its gate when
+        // `node.id === previewContentId`, so a token for a different node
+        // (or no token) has no effect here.
+        const prepare = await preparePublishedItem({
+            adapter,
+            listSerializerContributions: () => app.pluginRegistry.listActiveSerializerContributions(),
+            warn: (obj, msg) => request.log.warn(obj, msg),
+        }, node, { previewContentId });
+        if (prepare.status === "notFound") {
+            return reply.code(404).send({ message: NOT_FOUND_MESSAGE });
+        }
+        if (prepare.status === "brokenVersion") {
+            return reply.code(500).send({ message: prepare.message });
+        }
+        const { core, data, contributions, buildSerializerContext } = prepare;
+        // ?format=<pluginId>:<name> — a whole-response projection owned by one
+        // plugin. Never falls back to the default shape on failure: the caller
+        // asked for a specific projection, so a missing/broken one is a 400.
+        if (query.format) {
+            const [pluginId, formatName] = query.format.split(":", 2);
+            const owner = contributions.find((c) => c.pluginId === pluginId);
+            const format = owner?.serializers.customFormats?.find((f) => f.name === formatName);
+            if (!format) {
+                return reply.code(400).send({ message: `Unknown format ${query.format}` });
+            }
+            try {
+                const content = await format.build(buildSerializerContext());
+                JSON.stringify(content); // S111-handoff guard: non-JSON output is a plugin bug, not a 500
+                return reply.send({ format: query.format, content });
+            }
+            catch (error) {
+                request.log.warn({ pluginId, format: formatName, err: error }, "custom format build failed");
+                return reply.code(400).send({ message: `Format ${query.format} failed to build` });
+            }
+        }
+        const extensions = await computeExtensions(prepare, (obj, msg) => request.log.warn(obj, msg));
+        return reply.send({
+            ...core,
+            data,
+            ...(extensions ? { extensions } : {}),
+        });
+    }
+    app.get("/api/v1/content/roots", {
+        onRequest: requireApiKey,
+        schema: {
+            querystring: PublicContentListQuerySchema,
+            response: { 200: PublicContentListResponseSchema, 401: ApiErrorSchema },
+        },
+    }, async (request) => {
+        const { cursor, limit } = request.query;
+        const items = await adapter.getRootNodes({ cursor, limit, publishedOnly: true });
+        const nextCursor = items.length === limit ? (items[items.length - 1]?.id ?? null) : null;
+        return { items: toSummaries(items), nextCursor };
+    });
+    app.get("/api/v1/content/by-path", {
+        onRequest: requireApiKey,
+        schema: {
+            querystring: PublicContentByPathQuerySchema,
+            response: {
+                200: z.union([PublicContentItemSchema, PublicContentFormatResponseSchema]),
+                400: ApiErrorSchema,
+                401: ApiErrorSchema,
+                404: ApiErrorSchema,
+                500: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const { path, ...query } = request.query;
+        // Session 116 (Task 2 fix): verified ONCE, up front, so it can also
+        // decide whether the anchor fetch itself may return a draft.
+        // `verifyPreviewToken` returns null for every failure mode (absent,
+        // malformed, tampered, expired), so an absent/invalid token
+        // collapses to `previewContentId: null` and the anchor fetch keeps
+        // its original `publishedOnly: true` — bit-for-bit today's
+        // behavior. A verified token lifts the adapter-level filter so a
+        // draft-only anchor can even be fetched; `resolveItemNode` and
+        // `preparePublishedItem` still do ALL the actual gating below (a
+        // token only ever unlocks the exact node it names).
+        const previewContentId = query.previewToken
+            ? (verifyPreviewToken(query.previewToken)?.contentId ?? null)
+            : null;
+        const anchor = previewContentId
+            ? await adapter.getContentNodeByPath(path)
+            : await adapter.getContentNodeByPath(path, { publishedOnly: true });
+        return sendPublishedItem(request, reply, anchor, query, previewContentId);
+    });
+    app.get("/api/v1/content", {
+        onRequest: requireApiKey,
+        schema: {
+            querystring: PublicContentSearchQuerySchema,
+            response: {
+                200: PublicContentListResponseSchema,
+                401: ApiErrorSchema,
+                404: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const { documentTypeId, under, q, cursor, limit } = request.query;
+        let pathPrefix;
+        if (under) {
+            const resolved = await resolveSubtreeFilter(adapter, under);
+            if (!resolved) {
+                return reply.code(404).send({ message: NOT_FOUND_MESSAGE });
+            }
+            pathPrefix = resolved.pathPrefix;
+        }
+        const items = await adapter.searchPublishedContent({
+            cursor,
+            limit,
+            documentTypeId,
+            pathPrefix,
+            text: q,
+        });
+        const nextCursor = items.length === limit ? (items[items.length - 1]?.id ?? null) : null;
+        return { items: toSummaries(items), nextCursor };
+    });
+    function toWriteResponse(node, version) {
+        return {
+            id: node.id,
+            documentTypeId: node.documentTypeId,
+            parentId: node.parentId,
+            path: node.path,
+            locale: node.locale,
+            version: version.version,
+            publishedAt: node.publishedAt,
+            data: version.data,
+        };
+    }
+    app.post("/api/v1/content", {
+        onRequest: [requireApiKey, requireApiKeyScope("write")],
+        schema: {
+            description: "Create a content node. Derives path and depth server-side from parentId + slug; sortOrder is fixed at 0 for API-created nodes. Non-empty `data` is fully field-validated against the document type (400 with fieldErrors); empty `data` ({}) creates a stub to fill in later via PATCH.",
+            body: PublicCreateContentRequestSchema,
+            response: {
+                201: PublicContentWriteResponseSchema,
+                // Union so both bodies serialize on the one 400 slot: the
+                // structured field-validation body, and the plain-message body
+                // Fastify's own Zod body validation produces.
+                400: z.union([ContentValidationErrorSchema, ApiErrorSchema]),
+                401: ApiErrorSchema,
+                403: ApiErrorSchema,
+                404: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const { documentTypeId, parentId, slug, locale, isDefaultLocale, translationGroupId, data } = request.body;
+        // Derive path/depth from the parent (create derives tree internals so
+        // an external consumer never computes materialized-path values).
+        let path;
+        let depth;
+        if (parentId === null) {
+            path = `/${slug}`;
+            depth = 0;
+        }
+        else {
+            const parent = await adapter.getContentNode(parentId);
+            if (!parent) {
+                return reply.code(404).send({ message: `No content found for parent id ${parentId}` });
+            }
+            path = `${parent.path}/${slug}`;
+            depth = parent.depth + 1;
+        }
+        // Field validation of non-empty `data` lives in
+        // ContentService.createContent (S182), so the backoffice and public
+        // create paths share one rule; the ContentValidationError it throws
+        // is mapped to a 400 by the catch below.
+        try {
+            const { node, version } = await contentService.createContent({
+                documentTypeId,
+                parentId,
+                path,
+                depth,
+                sortOrder: 0,
+                locale,
+                isDefaultLocale,
+                ...(translationGroupId ? { translationGroupId } : {}),
+                data,
+                createdBy: apiContentAuthorId,
+            });
+            return reply.code(201).send(toWriteResponse(node, version));
+        }
+        catch (error) {
+            if (error instanceof ParentContentNotFoundError) {
+                return reply.code(404).send({ message: error.message });
+            }
+            if (error instanceof ContentValidationError) {
+                return reply.code(400).send({ message: error.message, fieldErrors: error.failures });
+            }
+            if (error instanceof DocumentTypeNotFoundForContentError || error instanceof TreeRulesViolationError) {
+                // Same 400 slot as the field-validation branch above, so it must
+                // satisfy ContentValidationErrorSchema's required fieldErrors —
+                // there are no per-field failures for these two error kinds, so
+                // an empty array is the honest shape, not a placeholder.
+                return reply.code(400).send({ message: error.message, fieldErrors: [] });
+            }
+            throw error;
+        }
+    });
+    // Shared by PUT/PATCH: resolve the node (any publish state — writers edit
+    // drafts), compute the data to save per the verb, then go through
+    // saveContent (Session 106 field-validates the result). Returns the reply.
+    async function saveContentWrite(reply, id, computeData) {
+        const node = await adapter.getContentNode(id);
+        if (!node) {
+            return reply.code(404).send({ message: `No content found for id ${id}` });
+        }
+        const latest = await adapter.getLatestContentVersion(id);
+        if (!latest) {
+            return reply.code(404).send({ message: `No content found for id ${id}` });
+        }
+        try {
+            const version = await contentService.saveContent(id, computeData(latest), apiContentAuthorId);
+            // saveContent doesn't return the node; the node's path/parentId/locale
+            // are unchanged by a save, so reuse the one already fetched.
+            return reply.code(200).send(toWriteResponse(node, version));
+        }
+        catch (error) {
+            if (error instanceof ContentValidationError) {
+                return reply.code(400).send({ message: error.message, fieldErrors: error.failures });
+            }
+            throw error;
+        }
+    }
+    app.put("/api/v1/content/:id", {
+        onRequest: [requireApiKey, requireApiKeyScope("write")],
+        schema: {
+            description: "Full-replace update: the node's data becomes exactly the request body's `data`, as a new immutable version. The whole record is field-validated, so omitting a required field is a 400. Use PATCH to change a subset of fields.",
+            params: PublicContentParamsSchema,
+            body: PublicUpdateContentRequestSchema,
+            response: {
+                200: PublicContentWriteResponseSchema,
+                400: z.union([ContentValidationErrorSchema, ApiErrorSchema]),
+                401: ApiErrorSchema,
+                403: ApiErrorSchema,
+                404: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => saveContentWrite(reply, request.params.id, () => request.body.data));
+    app.patch("/api/v1/content/:id", {
+        onRequest: [requireApiKey, requireApiKeyScope("write")],
+        schema: {
+            description: "Partial update: the request body's `data` keys are shallow-merged over the node's latest version (top-level per-key replace — a JSON/object field value is replaced whole, never deep-merged), saved as a new immutable version. The merged result is field-validated. Omitting a required field the node already has succeeds.",
+            params: PublicContentParamsSchema,
+            body: PublicUpdateContentRequestSchema,
+            response: {
+                200: PublicContentWriteResponseSchema,
+                400: z.union([ContentValidationErrorSchema, ApiErrorSchema]),
+                401: ApiErrorSchema,
+                403: ApiErrorSchema,
+                404: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => saveContentWrite(reply, request.params.id, (latest) => ({ ...latest.data, ...request.body.data })));
+    app.post("/api/v1/content/:id/publish", {
+        onRequest: [requireApiKey, requireApiKeyScope("write")],
+        schema: {
+            description: "Publish the node's latest saved version, repointing current_version (no new version row). Makes the node readable on the published-only read surface.",
+            params: PublicContentParamsSchema,
+            response: {
+                200: PublicContentWriteResponseSchema,
+                401: ApiErrorSchema,
+                403: ApiErrorSchema,
+                404: ApiErrorSchema,
+                500: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        try {
+            const node = await contentService.publishContent(request.params.id);
+            const version = await adapter.getContentVersion(node.id, node.currentVersion);
+            if (!version) {
+                return reply.code(500).send({
+                    message: `current_version (${node.currentVersion}) for ${node.id} has no matching content version`,
+                });
+            }
+            return reply.code(200).send(toWriteResponse(node, version));
+        }
+        catch (error) {
+            if (isNotFoundError(error)) {
+                return reply.code(404).send({ message: NOT_FOUND_MESSAGE });
+            }
+            throw error;
+        }
+    });
+    app.get("/api/v1/content/:id/children", {
+        onRequest: requireApiKey,
+        schema: {
+            params: PublicContentParamsSchema,
+            querystring: PublicContentListQuerySchema,
+            response: {
+                200: PublicContentListResponseSchema,
+                401: ApiErrorSchema,
+                404: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const parent = await adapter.getContentNode(request.params.id);
+        if (!parent || parent.publishedAt === null) {
+            return reply.code(404).send({ message: NOT_FOUND_MESSAGE });
+        }
+        const { cursor, limit } = request.query;
+        const items = await adapter.getChildren(parent.id, { cursor, limit, publishedOnly: true });
+        const nextCursor = items.length === limit ? (items[items.length - 1]?.id ?? null) : null;
+        return { items: toSummaries(items), nextCursor };
+    });
+    app.get("/api/v1/content/:id", {
+        onRequest: requireApiKey,
+        schema: {
+            params: PublicContentParamsSchema,
+            querystring: PublicContentItemQuerySchema,
+            response: {
+                200: z.union([PublicContentItemSchema, PublicContentFormatResponseSchema]),
+                400: ApiErrorSchema,
+                401: ApiErrorSchema,
+                404: ApiErrorSchema,
+                500: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        // Verified ONCE, up front — see the by-path route's identical
+        // comment. `getContentNode` never filters by publish state, so
+        // unlike by-path this anchor fetch was never the bug; the
+        // verify-once shape is kept identical across both routes anyway.
+        const previewContentId = request.query.previewToken
+            ? (verifyPreviewToken(request.query.previewToken)?.contentId ?? null)
+            : null;
+        const anchor = await adapter.getContentNode(request.params.id);
+        return sendPublishedItem(request, reply, anchor, request.query, previewContentId);
+    });
+    app.get("/api/v1/media", {
+        onRequest: requireApiKey,
+        schema: {
+            querystring: PublicMediaListQuerySchema,
+            response: { 200: PublicMediaListResponseSchema, 401: ApiErrorSchema },
+        },
+    }, async (request) => {
+        const { cursor, limit, search } = request.query;
+        const files = await mediaService.list({ cursor, limit, search });
+        const items = await Promise.all(files.map((file) => toPublicMediaFile(mediaService, file)));
+        const nextCursor = files.length === limit ? (files[files.length - 1]?.id ?? null) : null;
+        return { items, nextCursor };
+    });
+    app.get("/api/v1/media/:id", {
+        onRequest: requireApiKey,
+        schema: {
+            params: PublicContentParamsSchema,
+            response: { 200: PublicMediaFileSchema, 401: ApiErrorSchema, 404: ApiErrorSchema },
+        },
+    }, async (request, reply) => {
+        const media = await mediaService.getById(request.params.id);
+        if (!media) {
+            return reply.code(404).send({ message: `No media file found for id ${request.params.id}` });
+        }
+        return toPublicMediaFile(mediaService, media);
+    });
+    // Public document type introspection + template listing (Session 105).
+    // Both are read-only projections over existing backoffice adapter calls
+    // (document-types.ts / templates.ts) — no new adapter methods.
+    app.get("/api/v1/document-types", {
+        onRequest: requireApiKey,
+        schema: {
+            querystring: PublicDocumentTypeListQuerySchema,
+            response: { 200: PublicDocumentTypeListResponseSchema, 401: ApiErrorSchema },
+        },
+    }, 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: items.map(toPublicDocumentType), nextCursor };
+    });
+    app.get("/api/v1/document-types/:id", {
+        onRequest: requireApiKey,
+        schema: {
+            params: PublicContentParamsSchema,
+            response: { 200: PublicDocumentTypeSchema, 401: ApiErrorSchema, 404: ApiErrorSchema },
+        },
+    }, async (request, reply) => {
+        const doc = await adapter.getDocumentType(request.params.id);
+        if (!doc) {
+            return reply.code(404).send({ message: `No document type found for id ${request.params.id}` });
+        }
+        return toPublicDocumentType(doc);
+    });
+    app.get("/api/v1/templates", {
+        onRequest: requireApiKey,
+        schema: {
+            querystring: PublicTemplateListQuerySchema,
+            response: { 200: PublicTemplateListResponseSchema, 401: ApiErrorSchema },
+        },
+    }, 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 };
+    });
+    // GraphQL surface (Session 113, Task 2) — same public-content namespace,
+    // a second protocol over the identical published-item pipeline as the
+    // REST routes above. Nested scope so the key-gate hook below only
+    // touches this plugin's own routes, never the REST ones (which already
+    // gate per-route via onRequest: requireApiKey).
+    await app.register(async (gql) => {
+        // Key-gate ONLY the data endpoint: GraphiQL's HTML/asset routes ride
+        // the docs flag alone (its queries still need a key like any caller,
+        // same as swagger-ui showing schema shape without exposing data).
+        // mercurius' graphiql page lives at /api/v1/graphiql (and
+        // /api/v1/graphiql/*), which never matches this startsWith check.
+        gql.addHook("onRequest", async (request, reply) => {
+            if (request.url.startsWith("/api/v1/graphql")) {
+                await requireApiKey(request, reply);
+            }
+        });
+        // Dual-package hazard: this file is loaded as ESM, so `import {
+        // NoSchemaIntrospectionCustomRule } from "graphql"` resolves the ESM
+        // build — a DIFFERENT module instance than the CJS `graphql` mercurius
+        // (itself CJS) requires internally to validate queries. A rule object
+        // built from the ESM instance fails `instanceof`/identity checks
+        // inside mercurius' CJS graphql-js, so instead of a clean
+        // introspection-disabled rejection every query 500s with "Cannot use
+        // GraphQLNonNull ... from another module or realm ... Duplicate
+        // "graphql" modules". createRequire forces Node's CJS resolver, which
+        // hits the very same `graphql/index.js` mercurius itself requires —
+        // one instance, no realm mismatch.
+        const cjsGraphql = createRequire(import.meta.url)("graphql");
+        const { GraphQLError, NoSchemaIntrospectionCustomRule } = cjsGraphql;
+        // field-count-rule.ts's rule reports via `context.reportError(new
+        // GraphQLErrorCtor(...))` — the GraphQLError class it's given here is
+        // the SAME createRequire'd one NoSchemaIntrospectionCustomRule above
+        // is already built from, so every error either rule reports lives in
+        // the one true realm mercurius' CJS graphql-js instance validates
+        // against (see field-count-rule.ts's realm note for the full
+        // reasoning; S113 is the original incident this guards against).
+        const fieldCountRule = createFieldCountRule(maxQueryComplexity(), GraphQLError);
+        // mercurius registers its GraphiQL page (/api/v1/graphiql,
+        // .../main.js, .../sw.js, .../config.js) as plain, schema-less Fastify
+        // routes. Without an explicit `hide`, fastify-swagger picks each one
+        // up as a bare, undocumented path entry — and because this plugin
+        // scope is nested under BOTH the internal (/api/docs) and public
+        // (/api/v1/docs) Swagger surfaces, they leak into both specs. Hide
+        // them before mercurius registers those routes.
+        gql.addHook("onRoute", (routeOptions) => {
+            if (routeOptions.url.startsWith("/api/v1/graphiql")) {
+                routeOptions.schema = { ...routeOptions.schema, hide: true };
+            }
+        });
+        await gql.register(mercurius, {
+            schema: buildGraphqlSchema(),
+            prefix: "/api/v1",
+            path: "/graphql",
+            // mercurius 16's graphiql option has no per-path override — its
+            // GraphiQL page is always served at the plugin's own `/graphiql`,
+            // so `prefix` above is what nests it under /api/v1 alongside the
+            // data endpoint. Read at registration (boot) time, same convention
+            // as the /api/v1/docs Swagger UI gate in app.ts.
+            graphiql: isPublicDocsEnabled() ? { enabled: true } : false,
+            queryDepth: maxQueryDepth(),
+            // Session 119, Task 2: array-form validationRules (unlike the S115
+            // function-form workaround graphql-query-complexity required) keeps
+            // mercurius' query-plan cache on — the S118 baseline measured the
+            // function-form/`cache: false` alternative at ~10ms higher p50 and
+            // 23% lower throughput on GraphQL item reads.
+            validationRules: [
+                ...(isPublicDocsEnabled() ? [] : [NoSchemaIntrospectionCustomRule]),
+                fieldCountRule,
+            ],
+            additionalRouteOptions: {
+                validatorCompiler: mercuriusValidatorCompiler,
+                serializerCompiler: mercuriusSerializerCompiler,
+            },
+            context: async (request) => ({
+                deps: {
+                    adapter,
+                    listSerializerContributions: () => app.pluginRegistry.listActiveSerializerContributions(),
+                    warn: (obj, msg) => request.log.warn(obj, msg),
+                },
+                contentService,
+                mediaService,
+                getContentNode: (id) => adapter.getContentNode(id),
+            }),
+        });
+    });
+};

package/dist/routes/published-item.d.ts

@@ -0,0 +1,57 @@
+import type { DatabaseAdapter } from "@velora-cms/db-adapter";
+import { type ContentService } from "@velora-cms/content-service";
+import type { ContentNode, DocumentTypeDefinition, MediaFile, PublicContentNodeSummary, PublicDocumentType, PublicMediaFile } from "@velora-cms/api-schemas";
+import type { SerializerContext, SerializerContribution } from "@velora-cms/plugin-sdk/manifest";
+import type { MediaService } from "../media/media-service.js";
+export declare function isNotFoundError(error: unknown): error is Error;
+export declare function resolveItemNode(deps: {
+    adapter: DatabaseAdapter;
+    contentService: ContentService;
+}, anchor: ContentNode | null, query: {
+    locale?: string;
+    fallback?: string;
+}, options?: {
+    previewContentId?: string | null;
+}): Promise<ContentNode | null>;
+export declare function resolveSubtreeFilter(adapter: DatabaseAdapter, underId: string): Promise<{
+    pathPrefix: string;
+} | null>;
+export declare function toSummaries(nodes: ContentNode[]): PublicContentNodeSummary[];
+export declare function toPublicDocumentType(doc: DocumentTypeDefinition): PublicDocumentType;
+export declare function toPublicMediaFile(mediaService: MediaService, media: MediaFile): Promise<PublicMediaFile>;
+export type PublishedItemDeps = {
+    adapter: DatabaseAdapter;
+    listSerializerContributions: () => Array<{
+        pluginId: string;
+        serializers: SerializerContribution;
+    }>;
+    warn: (obj: Record<string, unknown>, msg: string) => void;
+};
+export type PreparedPublishedItem = {
+    status: "notFound";
+} | {
+    status: "brokenVersion";
+    message: string;
+} | {
+    status: "ok";
+    core: {
+        id: string;
+        documentTypeId: string;
+        locale: string;
+        publishedAt: string | null;
+        version: number;
+    };
+    data: Record<string, unknown>;
+    contributions: Array<{
+        pluginId: string;
+        serializers: SerializerContribution;
+    }>;
+    buildSerializerContext: () => SerializerContext;
+};
+export type PreparePublishedItemOptions = {
+    previewContentId?: string | null;
+};
+export declare function preparePublishedItem(deps: PublishedItemDeps, anchor: ContentNode | null, options?: PreparePublishedItemOptions): Promise<PreparedPublishedItem>;
+export declare function computeExtensions(prepared: Extract<PreparedPublishedItem, {
+    status: "ok";
+}>, warn: PublishedItemDeps["warn"]): Promise<Record<string, Record<string, unknown>> | undefined>;