@velora-cms/server 0.11.0

package/dist/graphql/field-count-rule.d.ts

@@ -0,0 +1,5 @@
+import type { GraphQLError, ValidationRule } from "graphql";
+export interface GraphQLErrorConstructor {
+    new (message: string): GraphQLError;
+}
+export declare function createFieldCountRule(max: number, GraphQLErrorCtor: GraphQLErrorConstructor): ValidationRule;

package/dist/graphql/field-count-rule.js

@@ -0,0 +1,59 @@
+export function createFieldCountRule(max, GraphQLErrorCtor) {
+    return function FieldCountRule(context) {
+        return {
+            Document: {
+                leave(document) {
+                    const fragments = new Map();
+                    for (const definition of document.definitions) {
+                        if (definition.kind === "FragmentDefinition") {
+                            fragments.set(definition.name.value, definition);
+                        }
+                    }
+                    let count = 0;
+                    const activeSpreads = new Set();
+                    function countSelectionSet(selectionSet) {
+                        if (!selectionSet)
+                            return;
+                        for (const selection of selectionSet.selections) {
+                            switch (selection.kind) {
+                                case "Field": {
+                                    count++;
+                                    countSelectionSet(selection.selectionSet);
+                                    break;
+                                }
+                                case "InlineFragment": {
+                                    countSelectionSet(selection.selectionSet);
+                                    break;
+                                }
+                                case "FragmentSpread": {
+                                    const name = selection.name.value;
+                                    // Guard (b): cycle — stop recursing here, don't loop
+                                    // forever. NoFragmentCyclesRule reports the cycle.
+                                    if (activeSpreads.has(name))
+                                        break;
+                                    const fragment = fragments.get(name);
+                                    // Guard (a): unknown fragment — count 0.
+                                    // KnownFragmentNamesRule reports it separately.
+                                    if (!fragment)
+                                        break;
+                                    activeSpreads.add(name);
+                                    countSelectionSet(fragment.selectionSet);
+                                    activeSpreads.delete(name);
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                    for (const definition of document.definitions) {
+                        if (definition.kind === "OperationDefinition") {
+                            countSelectionSet(definition.selectionSet);
+                        }
+                    }
+                    if (count > max) {
+                        context.reportError(new GraphQLErrorCtor(`Query field count of ${count} exceeds the maximum allowed complexity of ${max}`));
+                    }
+                },
+            },
+        };
+    };
+}

package/dist/graphql/schema.d.ts

@@ -0,0 +1,12 @@
+import type { GraphQLSchema } from "graphql";
+import type { ContentService } from "@velora-cms/content-service";
+import { type ContentNode } from "@velora-cms/api-schemas";
+import type { MediaService } from "../media/media-service.js";
+import { type PublishedItemDeps } from "../routes/published-item.js";
+export interface GraphqlContext {
+    deps: PublishedItemDeps;
+    contentService: ContentService;
+    mediaService: MediaService;
+    getContentNode: (id: string) => Promise<ContentNode | null>;
+}
+export declare function buildGraphqlSchema(): GraphQLSchema;

package/dist/graphql/schema.js

@@ -0,0 +1,330 @@
+import SchemaBuilder from "@pothos/core";
+import { JSONResolver } from "graphql-scalars";
+import { PublicContentByPathQuerySchema, PublicContentItemQuerySchema, PublicContentListQuerySchema, PublicContentSearchQuerySchema, PublicDocumentTypeListQuerySchema, PublicMediaListQuerySchema, PublicTemplateListQuerySchema, } from "@velora-cms/api-schemas";
+import { verifyPreviewToken } from "../auth/preview-tokens.js";
+import { computeExtensions, preparePublishedItem, resolveItemNode, resolveSubtreeFilter, toPublicDocumentType, toPublicMediaFile, toSummaries, } from "../routes/published-item.js";
+// Re-parses a GraphQL args object through the exact REST querystring Zod
+// schema for the sibling endpoint. `undefined` fields fall through to the
+// schema's own `.default()`s (same as an omitted REST querystring key);
+// an out-of-bounds/malformed value fails validation exactly like REST's
+// Fastify schema compiler does — the caller gets a GraphQL error, not a
+// silent clamp.
+function parseArgs(schema, value, label) {
+    const result = schema.safeParse(value);
+    if (!result.success) {
+        throw new Error(`Invalid ${label}: ${result.error?.message}`);
+    }
+    return result.data;
+}
+const builder = new SchemaBuilder({});
+builder.addScalarType("JSON", JSONResolver, {});
+const PublicContentItem = builder.objectRef("PublicContentItem").implement({
+    fields: (t) => ({
+        id: t.exposeID("id"),
+        documentTypeId: t.exposeID("documentTypeId"),
+        locale: t.exposeString("locale"),
+        publishedAt: t.exposeString("publishedAt", { nullable: true }),
+        version: t.exposeInt("version"),
+        data: t.expose("data", { type: "JSON" }),
+        extensions: t.expose("extensions", { type: "JSON", nullable: true }),
+    }),
+});
+const PublicContentNodeSummaryRef = builder
+    .objectRef("PublicContentNodeSummary")
+    .implement({
+    fields: (t) => ({
+        id: t.exposeID("id"),
+        parentId: t.exposeID("parentId", { nullable: true }),
+        path: t.exposeString("path"),
+        depth: t.exposeInt("depth"),
+        sortOrder: t.exposeInt("sortOrder"),
+        documentTypeId: t.exposeID("documentTypeId"),
+        locale: t.exposeString("locale"),
+        publishedAt: t.exposeString("publishedAt"),
+    }),
+});
+const PublicFieldValidationRef = builder
+    .objectRef("PublicFieldValidation")
+    .implement({
+    fields: (t) => ({
+        required: t.exposeBoolean("required", { nullable: true }),
+        minLength: t.exposeInt("minLength", { nullable: true }),
+        maxLength: t.exposeInt("maxLength", { nullable: true }),
+        min: t.exposeFloat("min", { nullable: true }),
+        max: t.exposeFloat("max", { nullable: true }),
+        pattern: t.exposeString("pattern", { nullable: true }),
+    }),
+});
+const PublicFieldDefinitionRef = builder.objectRef("PublicFieldDefinition").implement({
+    fields: (t) => ({
+        id: t.exposeString("id"),
+        name: t.exposeString("name"),
+        datatypeId: t.exposeString("datatypeId"),
+        validation: t.expose("validation", { type: PublicFieldValidationRef, nullable: true }),
+    }),
+});
+const PublicDocumentTypeRef = builder.objectRef("PublicDocumentType").implement({
+    fields: (t) => ({
+        id: t.exposeID("id"),
+        name: t.exposeString("name"),
+        icon: t.exposeString("icon"),
+        kind: t.exposeString("kind"),
+        fields: t.expose("fields", { type: [PublicFieldDefinitionRef] }),
+    }),
+});
+const PublicTemplateRef = builder.objectRef("PublicTemplate").implement({
+    fields: (t) => ({
+        id: t.exposeID("id"),
+        name: t.exposeString("name"),
+        documentTypeId: t.exposeID("documentTypeId"),
+    }),
+});
+const PublicMediaFileRef = builder.objectRef("PublicMediaFile").implement({
+    fields: (t) => ({
+        id: t.exposeID("id"),
+        filename: t.exposeString("filename"),
+        mimeType: t.exposeString("mimeType"),
+        size: t.exposeInt("size"),
+        downloadUrl: t.exposeString("downloadUrl"),
+        uploadedAt: t.exposeString("uploadedAt"),
+    }),
+});
+const ContentNodeConnectionRef = builder
+    .objectRef("ContentNodeConnection")
+    .implement({
+    fields: (t) => ({
+        items: t.expose("items", { type: [PublicContentNodeSummaryRef] }),
+        nextCursor: t.exposeID("nextCursor", { nullable: true }),
+    }),
+});
+const DocumentTypeConnectionRef = builder
+    .objectRef("DocumentTypeConnection")
+    .implement({
+    fields: (t) => ({
+        items: t.expose("items", { type: [PublicDocumentTypeRef] }),
+        nextCursor: t.exposeID("nextCursor", { nullable: true }),
+    }),
+});
+const TemplateConnectionRef = builder
+    .objectRef("TemplateConnection")
+    .implement({
+    fields: (t) => ({
+        items: t.expose("items", { type: [PublicTemplateRef] }),
+        nextCursor: t.exposeID("nextCursor", { nullable: true }),
+    }),
+});
+const MediaConnectionRef = builder
+    .objectRef("MediaConnection")
+    .implement({
+    fields: (t) => ({
+        items: t.expose("items", { type: [PublicMediaFileRef] }),
+        nextCursor: t.exposeID("nextCursor", { nullable: true }),
+    }),
+});
+builder.queryType({
+    fields: (t) => ({
+        // GET /api/v1/content/:id analog. Uniform null for unknown id, draft,
+        // and (once locale/fallback are set) an unresolvable/unpublished
+        // translation — same "no oracle" contract as REST's 404.
+        content: t.field({
+            type: PublicContentItem,
+            nullable: true,
+            args: {
+                id: t.arg.id({ required: true }),
+                locale: t.arg.string(),
+                fallback: t.arg.string(),
+                // Session 116: GraphQL analog of REST's ?previewToken= — same
+                // core (resolveItemNode + preparePublishedItem), verified once,
+                // matched against the FINAL resolved node. Deliberately not
+                // added to contentByPath or any list/connection query this
+                // session.
+                previewToken: t.arg.string(),
+            },
+            resolve: async (_root, args, ctx) => {
+                const query = parseArgs(PublicContentItemQuerySchema, {
+                    locale: args.locale ?? undefined,
+                    fallback: args.fallback ?? undefined,
+                    previewToken: args.previewToken ?? undefined,
+                }, "content arguments");
+                const previewContentId = query.previewToken ? (verifyPreviewToken(query.previewToken)?.contentId ?? null) : null;
+                const anchor = await ctx.getContentNode(String(args.id));
+                const node = await resolveItemNode({ adapter: ctx.deps.adapter, contentService: ctx.contentService }, anchor, query, { previewContentId });
+                const prepared = await preparePublishedItem(ctx.deps, node, { previewContentId });
+                if (prepared.status === "notFound")
+                    return null; // uniform: unknown AND draft
+                if (prepared.status === "brokenVersion")
+                    throw new Error(prepared.message); // REST-500 analog
+                const extensions = await computeExtensions(prepared, ctx.deps.warn);
+                return { ...prepared.core, data: prepared.data, extensions: extensions ?? null };
+            },
+        }),
+        // GET /api/v1/content/by-path analog. Same uniform-null contract as
+        // `content`; the by-path anchor lookup is already publishedOnly.
+        contentByPath: t.field({
+            type: PublicContentItem,
+            nullable: true,
+            args: {
+                path: t.arg.string({ required: true }),
+                locale: t.arg.string(),
+                fallback: t.arg.string(),
+            },
+            resolve: async (_root, args, ctx) => {
+                const query = parseArgs(PublicContentByPathQuerySchema, { path: args.path, locale: args.locale ?? undefined, fallback: args.fallback ?? undefined }, "contentByPath arguments");
+                const anchor = await ctx.deps.adapter.getContentNodeByPath(query.path, { publishedOnly: true });
+                const node = await resolveItemNode({ adapter: ctx.deps.adapter, contentService: ctx.contentService }, anchor, query);
+                const prepared = await preparePublishedItem(ctx.deps, node);
+                if (prepared.status === "notFound")
+                    return null;
+                if (prepared.status === "brokenVersion")
+                    throw new Error(prepared.message);
+                const extensions = await computeExtensions(prepared, ctx.deps.warn);
+                return { ...prepared.core, data: prepared.data, extensions: extensions ?? null };
+            },
+        }),
+        // GET /api/v1/content/roots analog — REST never 404s this one, so the
+        // connection is always returned (never null).
+        contentRoots: t.field({
+            type: ContentNodeConnectionRef,
+            nullable: false,
+            args: { cursor: t.arg.id(), limit: t.arg.int() },
+            resolve: async (_root, args, ctx) => {
+                const { cursor, limit } = parseArgs(PublicContentListQuerySchema, { cursor: args.cursor ?? undefined, limit: args.limit ?? undefined }, "contentRoots arguments");
+                const items = await ctx.deps.adapter.getRootNodes({ cursor, limit, publishedOnly: true });
+                const nextCursor = items.length === limit ? (items[items.length - 1]?.id ?? null) : null;
+                return { items: toSummaries(items), nextCursor };
+            },
+        }),
+        // GET /api/v1/content/:id/children analog. Null connection (not an
+        // empty page) when the parent is unknown/draft, mirroring REST's 404.
+        contentChildren: t.field({
+            type: ContentNodeConnectionRef,
+            nullable: true,
+            args: { id: t.arg.id({ required: true }), cursor: t.arg.id(), limit: t.arg.int() },
+            resolve: async (_root, args, ctx) => {
+                const { cursor, limit } = parseArgs(PublicContentListQuerySchema, { cursor: args.cursor ?? undefined, limit: args.limit ?? undefined }, "contentChildren arguments");
+                const parent = await ctx.getContentNode(String(args.id));
+                if (!parent || parent.publishedAt === null)
+                    return null;
+                const items = await ctx.deps.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 };
+            },
+        }),
+        // GET /api/v1/content analog (Session 115, Task 1) — combinable
+        // filters over the published surface: documentTypeId, a subtree
+        // anchor (under), and a case-insensitive substring (q), matching
+        // REST's PublicContentSearchQuerySchema-validated querystring
+        // exactly for documentTypeId/q/cursor/limit. `under` is deliberately
+        // NOT part of that parseArgs call — it's resolved via the same
+        // resolveSubtreeFilter helper REST's route now shares, unvalidated
+        // by the schema's `.uuid()` check, the same convention `content`/
+        // `documentType`/`mediaItem`/`contentChildren` already use for their
+        // own id args (a malformed value is a lookup miss, not a thrown
+        // validation error). Null (not an empty page) whenever `under`
+        // doesn't resolve to a published anchor — unknown, unpublished, or
+        // malformed — mirroring REST's 404 for the valid-format misses
+        // (unknown/unpublished); a malformed-format `under` never reaches
+        // REST's handler at all, since Fastify's querystring schema 400s it
+        // before the route runs.
+        contents: t.field({
+            type: ContentNodeConnectionRef,
+            nullable: true,
+            args: {
+                documentTypeId: t.arg.id(),
+                under: t.arg.id(),
+                q: t.arg.string(),
+                cursor: t.arg.id(),
+                limit: t.arg.int(),
+            },
+            resolve: async (_root, args, ctx) => {
+                const { documentTypeId, q, cursor, limit } = parseArgs(PublicContentSearchQuerySchema, {
+                    documentTypeId: args.documentTypeId ?? undefined,
+                    q: args.q ?? undefined,
+                    cursor: args.cursor ?? undefined,
+                    limit: args.limit ?? undefined,
+                }, "contents arguments");
+                let pathPrefix;
+                if (args.under) {
+                    const resolved = await resolveSubtreeFilter(ctx.deps.adapter, args.under);
+                    if (!resolved)
+                        return null;
+                    pathPrefix = resolved.pathPrefix;
+                }
+                const items = await ctx.deps.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 };
+            },
+        }),
+        // GET /api/v1/document-types/:id analog. Uniform null for unknown id.
+        documentType: t.field({
+            type: PublicDocumentTypeRef,
+            nullable: true,
+            args: { id: t.arg.id({ required: true }) },
+            resolve: async (_root, args, ctx) => {
+                const doc = await ctx.deps.adapter.getDocumentType(String(args.id));
+                return doc ? toPublicDocumentType(doc) : null;
+            },
+        }),
+        // GET /api/v1/document-types analog — never null, same as contentRoots.
+        documentTypes: t.field({
+            type: DocumentTypeConnectionRef,
+            nullable: false,
+            args: { cursor: t.arg.id(), limit: t.arg.int() },
+            resolve: async (_root, args, ctx) => {
+                const { cursor, limit } = parseArgs(PublicDocumentTypeListQuerySchema, { cursor: args.cursor ?? undefined, limit: args.limit ?? undefined }, "documentTypes arguments");
+                const items = await ctx.deps.adapter.listDocumentTypes({ cursor, limit });
+                const nextCursor = items.length === limit ? (items[items.length - 1]?.id ?? null) : null;
+                return { items: items.map(toPublicDocumentType), nextCursor };
+            },
+        }),
+        // GET /api/v1/templates analog — never null; no by-id REST route
+        // exists for templates, so there is no singular `template(id)` query.
+        templates: t.field({
+            type: TemplateConnectionRef,
+            nullable: false,
+            args: { cursor: t.arg.id(), limit: t.arg.int(), documentTypeId: t.arg.id() },
+            resolve: async (_root, args, ctx) => {
+                const { cursor, limit, documentTypeId } = parseArgs(PublicTemplateListQuerySchema, {
+                    cursor: args.cursor ?? undefined,
+                    limit: args.limit ?? undefined,
+                    documentTypeId: args.documentTypeId ?? undefined,
+                }, "templates arguments");
+                const items = await ctx.deps.adapter.listTemplates({ cursor, limit, documentTypeId });
+                const nextCursor = items.length === limit ? (items[items.length - 1]?.id ?? null) : null;
+                return { items, nextCursor };
+            },
+        }),
+        // GET /api/v1/media/:id analog. Uniform null for unknown id.
+        mediaItem: t.field({
+            type: PublicMediaFileRef,
+            nullable: true,
+            args: { id: t.arg.id({ required: true }) },
+            resolve: async (_root, args, ctx) => {
+                const media = await ctx.mediaService.getById(String(args.id));
+                return media ? toPublicMediaFile(ctx.mediaService, media) : null;
+            },
+        }),
+        // GET /api/v1/media analog — never null, same as contentRoots.
+        media: t.field({
+            type: MediaConnectionRef,
+            nullable: false,
+            args: { cursor: t.arg.id(), limit: t.arg.int(), search: t.arg.string() },
+            resolve: async (_root, args, ctx) => {
+                const { cursor, limit, search } = parseArgs(PublicMediaListQuerySchema, { cursor: args.cursor ?? undefined, limit: args.limit ?? undefined, search: args.search ?? undefined }, "media arguments");
+                const files = await ctx.mediaService.list({ cursor, limit, search });
+                const items = await Promise.all(files.map((file) => toPublicMediaFile(ctx.mediaService, file)));
+                const nextCursor = files.length === limit ? (files[files.length - 1]?.id ?? null) : null;
+                return { items, nextCursor };
+            },
+        }),
+    }),
+});
+export function buildGraphqlSchema() {
+    return builder.toSchema();
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,180 @@
+import { loadEnvFile } from "./config/load-env.js";
+import { normalizeDatabaseUrl } from "./setup/normalize-database-url.js";
+import { countAdminUsers, resolveBootMode } from "./boot/resolve-boot-mode.js";
+import { judgeCoreMigrationFailure } from "./boot/core-migration-gate.js";
+// FIRST, before anything reads process.env. app.js's import graph reaches
+// db/prisma.ts, whose module body is `export const prisma = await
+// loadPrismaClient(resolveClientDir())` — a top-level await that runs as a
+// side effect of the import. If that module were imported before the env
+// file is merged, it would connect with whatever DATABASE_URL happened to
+// already be set. Hence a static import of the loader here and DYNAMIC
+// imports of the apps below, deferred until after the boot mode is known.
+loadEnvFile();
+// An externally injected DATABASE_URL gets the same treatment the wizard's
+// own input gets — a relative sqlite path becomes absolute exactly once,
+// here, before anything downstream reads it. Doing it in place means the
+// Prisma CLI (setup/provision-database.ts), the content-db adapter and
+// every other reader see one identical absolute string.
+if (process.env.DATABASE_URL) {
+    process.env.DATABASE_URL = normalizeDatabaseUrl(process.env.DATABASE_URL);
+}
+// S185: self-heal the Prisma client and bring the Prisma-owned schema's
+// migration ledger up to date BEFORE resolveBootMode below — its
+// countAdminUsers builds a Prisma client of its own, which needs both the
+// generated client and the migrated schema to exist. Still dynamic imports,
+// for the same reason as the app-selection block further down: nothing
+// Prisma-shaped may load before loadEnvFile()/normalizeDatabaseUrl() have
+// settled process.env.DATABASE_URL. An unset or dialect-less DATABASE_URL
+// falls through untouched — the setup app path (no DATABASE_URL yet) is
+// unchanged. An injected DATABASE_URL may point at a completely empty
+// database the wizard hasn't provisioned yet; applyCoreMigrations(mode:
+// "boot") handles that itself (outcome "skipped-empty"), so nothing here
+// pre-checks for it.
+//
+// Fix wave (review): migrations are attempted FIRST, before resolveBootMode
+// runs, so a "full" (configured) boot never proceeds against an
+// un-migrated schema. But refusal on failure is deferred until AFTER mode
+// is known — resolveBootMode is the actual decision-maker here and is
+// fail-closed by design (see its own header): a DATABASE_URL pointing at a
+// database that doesn't exist as a catalog entry at all (P1003) is a
+// deliberately supported shape, not a crash — it reads as zero admins and
+// resolves to a setup-* mode so the wizard can create the database. Any
+// error here is therefore captured and remembered rather than thrown, and
+// only judged once the mode is known: it refuses "full" (a configured
+// install must never run the app against a database whose core schema
+// didn't or couldn't migrate) but is expected, and logged quietly, for the
+// setup-* modes, where an empty or missing database is exactly why the
+// wizard exists.
+let coreMigrationError;
+let coreMigrationPhase;
+if (process.env.DATABASE_URL) {
+    const { dialectFromUrlScheme } = await import("./db/content-db.js");
+    const dialect = dialectFromUrlScheme(process.env.DATABASE_URL);
+    if (dialect) {
+        // Which of the two awaits below was in flight when/if the catch fires —
+        // set right before each one starts, so a throw from either leaves the
+        // right phase behind for judgeCoreMigrationFailure to word correctly.
+        let phase = "client-generation";
+        try {
+            const { ensurePrismaClientGenerated } = await import("./setup/ensure-prisma-client.js");
+            const { applyCoreMigrations } = await import("./db/core-migrations/index.js");
+            await ensurePrismaClientGenerated(dialect);
+            phase = "core-migrations";
+            await applyCoreMigrations({ dialect, databaseUrl: process.env.DATABASE_URL, mode: "boot" });
+        }
+        catch (err) {
+            coreMigrationError = err instanceof Error ? err : new Error(String(err));
+            coreMigrationPhase = phase;
+        }
+    }
+}
+let mode;
+try {
+    mode = await resolveBootMode(process.env, countAdminUsers);
+}
+catch (err) {
+    // A plain process.stderr.write (what console.error calls internally) can
+    // be buffered (notably on Windows, and on any piped stderr) — an
+    // immediately following process.exit(1) can cut the write off before it
+    // flushes, and this message is the ONLY explanation the operator gets for
+    // a refused boot. Wait for the write's own callback so it has actually
+    // left the process before exiting.
+    const message = err instanceof Error ? err.message : String(err);
+    // If a core-migration/client-generation error was ALSO captured above,
+    // don't let resolveBootMode's own failure bury it: that earlier error is
+    // frequently the actual root cause (e.g. an un-migrated schema is exactly
+    // the kind of thing that can make the admin-count probe below it fail
+    // too), and without this line it would be silently dropped — the operator
+    // would see only the downstream symptom.
+    const lines = [message];
+    if (coreMigrationError && coreMigrationPhase) {
+        lines.push(`Earlier failure while preparing the database (${coreMigrationPhase}): ${coreMigrationError.message}`);
+    }
+    await new Promise((resolve) => {
+        process.stderr.write(`${lines.join("\n")}\n`, () => resolve());
+    });
+    process.exit(1);
+}
+// A captured core-migration/client-generation error only matters once mode
+// is known — see the comment above the capture. judgeCoreMigrationFailure
+// is the pure decision (unit-tested in boot/core-migration-gate.test.ts,
+// including the never-boot-un-migrated invariant for mode "full"); this is
+// just the process.exit/console plumbing around its answer, using the same
+// flushed-stderr + exit shape the resolveBootMode catch above uses so the
+// operator always gets the named cause.
+if (coreMigrationError && coreMigrationPhase) {
+    const gate = judgeCoreMigrationFailure(coreMigrationError, mode, coreMigrationPhase);
+    if (gate.action === "refuse") {
+        await new Promise((resolve) => {
+            process.stderr.write(`${gate.message}\n`, () => resolve());
+        });
+        process.exit(1);
+    }
+    else if (gate.action === "log") {
+        console.log(gate.message);
+    }
+}
+// Deferred until the mode is known, and still dynamic, for two reasons:
+// (1) db/prisma.ts's top-level-await `prisma` singleton (see above) must
+// not be constructed before loadEnvFile()/normalizeDatabaseUrl() have
+// settled process.env.DATABASE_URL, and (2) resolve-boot-mode.ts's
+// countAdminUsers deliberately builds its own short-lived client instead of
+// importing that singleton, specifically so the mode decision can be made
+// before committing to a connection — importing app.js (which statically
+// imports db/prisma.ts) unconditionally, before that decision ran, would
+// construct the singleton anyway and defeat the point. This also means
+// setup-full/setup-admin-only no longer load the entire buildApp() import
+// graph at all.
+let app;
+if (mode === "full") {
+    const { buildApp } = await import("./app.js");
+    app = await buildApp();
+}
+else {
+    const { buildSetupOnlyApp } = await import("./setup-app.js");
+    app = await buildSetupOnlyApp({ databaseConfigured: mode === "setup-admin-only" });
+}
+const port = Number(process.env.PORT ?? 3000);
+const host = process.env.HOST ?? "127.0.0.1";
+try {
+    await app.listen({ port, host });
+}
+catch (err) {
+    app.log.error(err);
+    process.exit(1);
+}
+// Without this, SIGTERM/SIGINT (Docker stop, systemd, a Windows service, or a
+// plain Ctrl-C) hit Node's default signal action — immediate termination —
+// and app.close() never runs. That means every onClose hook (content DB
+// disconnect, the license-revalidation job's own bounded drain) is dead code
+// in production, only ever exercised by tests that call app.close() directly.
+// Verified live against a running server, Session 139.
+//
+// SHUTDOWN_TIMEOUT_MS sits above the license job's own 15s pass-timeout bound
+// (license-revalidation-job.ts) so that job's own drain has room to give up
+// cleanly and log first; this is the outer safety net for the rest of
+// app.close() (e.g. the content DB disconnect) hanging too.
+const SHUTDOWN_TIMEOUT_MS = 20_000;
+let shuttingDown = false;
+function shutdown(signal) {
+    // A second signal while already closing must not start a second close.
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    app.log.info(`[shutdown] received ${signal}, closing…`);
+    const forceExit = setTimeout(() => {
+        app.log.error(`[shutdown] app.close() did not resolve within ${SHUTDOWN_TIMEOUT_MS}ms — forcing exit`);
+        process.exit(1);
+    }, SHUTDOWN_TIMEOUT_MS);
+    app.close().then(() => {
+        app.log.info("[shutdown] closed cleanly");
+        clearTimeout(forceExit);
+        process.exit(0);
+    }, (closeErr) => {
+        app.log.error(closeErr, "[shutdown] error while closing");
+        clearTimeout(forceExit);
+        process.exit(1);
+    });
+}
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+process.on("SIGINT", () => shutdown("SIGINT"));

package/dist/lib.d.ts

@@ -0,0 +1,2 @@
+export declare function createApp(): Promise<import("fastify").FastifyInstance<import("fastify").RawServerDefault, import("http").IncomingMessage, import("http").ServerResponse<import("http").IncomingMessage>, import("fastify").FastifyBaseLogger, import("fastify").FastifyTypeProviderDefault>>;
+export declare const buildApp: typeof createApp;

package/dist/lib.js

@@ -0,0 +1,39 @@
+// The embed surface (S185). createApp() mirrors the preparation the
+// `velora-server` bin (index.ts) performs before building the app — env
+// file load, DATABASE_URL normalization, Prisma-client self-heal, core
+// migrations — then returns the built (not-listening) Fastify instance for
+// the caller to mount or listen on themselves.
+//
+// Everything below is imported DYNAMICALLY and only inside the call:
+// db/prisma.ts holds a top-level-await Prisma client that must not be
+// constructed at import time (see index.ts's own comments on the same
+// point), and a consumer must be able to set process.env AFTER importing
+// this module and BEFORE calling createApp().
+//
+// Unlike index.ts, this does NOT reproduce the bin's boot-mode gate
+// (resolveBootMode / judgeCoreMigrationFailure) or its process.exit
+// refusal behavior — those belong to the standalone server process, not to
+// a library call. Here, any failure (env parsing, client generation,
+// migrations, or buildApp itself) simply propagates as a rejected promise
+// for the caller to catch. That IS the right embed behavior: a library
+// function must never call process.exit or decide a host process's fate.
+export async function createApp() {
+    const { loadEnvFile } = await import("./config/load-env.js");
+    const { normalizeDatabaseUrl } = await import("./setup/normalize-database-url.js");
+    loadEnvFile();
+    if (process.env.DATABASE_URL) {
+        process.env.DATABASE_URL = normalizeDatabaseUrl(process.env.DATABASE_URL);
+        const { dialectFromUrlScheme } = await import("./db/content-db.js");
+        const dialect = dialectFromUrlScheme(process.env.DATABASE_URL);
+        if (dialect) {
+            const { ensurePrismaClientGenerated } = await import("./setup/ensure-prisma-client.js");
+            const { applyCoreMigrations } = await import("./db/core-migrations/index.js");
+            await ensurePrismaClientGenerated(dialect);
+            await applyCoreMigrations({ dialect, databaseUrl: process.env.DATABASE_URL, mode: "boot" });
+        }
+    }
+    const { buildApp } = await import("./app.js");
+    return buildApp();
+}
+// Alias kept for symmetry with app.ts's internal name.
+export const buildApp = createApp;