@velora-cms/server 0.11.0

package/dist/scripts/pack-bundled-templates.js

@@ -0,0 +1,87 @@
+// Build-time only. Packs the first-party starter templates the setup
+// wizard's optional "starter template" step offers (currently just the
+// blog template — plugins/blog) with the REAL velora-plugin build
+// pipeline, and lays the result out for setup/bundled-templates.ts to
+// find: apps/server/bundled-templates/<pluginId>/{package.tar.gz,
+// manifest.json, sample-content.json} (repo path — what a `tsx`-run dev
+// server resolves), then copied wholesale into
+// apps/server/dist/bundled-templates (the production-shaped location —
+// copy-docs-bundle.ts's precedent: ship the artifact inside the server's
+// own dist/, not just the repo path).
+//
+// ONE plugin only, packed IN-PROCESS via packPlugin(). velora-plugin's
+// build runs a real Vite Module Federation build — running a SECOND one
+// inside the same process deadlocks reproducibly (S143, discovered while
+// building apps/marketplace/scripts/seed-artifacts.ts: five straight
+// hangs at the second plugin, hours of spun CPU, while every
+// single-plugin run completed in seconds — leaked in-process Vite build
+// state, not a property of any one plugin). See seed-artifact-one.ts for
+// the child-process-per-plugin pattern this script MUST switch to before
+// a second bundled template is ever added here.
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadManifest } from "velora-plugin";
+import { packPlugin } from "velora-plugin/pack";
+// This script runs from TWO locations: <server>/dist/scripts (compiled,
+// via `pnpm build`) and <server>/src/scripts (standalone `tsx` run via the
+// pack-templates script). Both sit exactly two directories under the
+// package root, so anchor everything off that root — never off `here`'s
+// parent, which would land the dist copy inside src/ on a tsx run and
+// shadow the repo-dir candidate resolveBundledTemplatesDir() checks.
+const here = dirname(fileURLToPath(import.meta.url)); // <server>/{dist|src}/scripts
+const serverDir = join(here, "..", ".."); // <server> (package root)
+const serverDist = join(serverDir, "dist"); // <server>/dist
+const repoRoot = join(serverDir, "..", ".."); // repo root
+const PLUGIN_DIRS = [join(repoRoot, "plugins", "blog")];
+const repoOutRoot = join(serverDir, "bundled-templates");
+const distOutRoot = join(serverDist, "bundled-templates");
+async function packOne(pluginDir) {
+    const manifestResult = await loadManifest(pluginDir);
+    if (!manifestResult.ok) {
+        throw new Error(`pack-bundled-templates: manifest failed to load from ${pluginDir}:\n${manifestResult.errors.join("\n")}`);
+    }
+    const { id } = manifestResult.manifest;
+    console.log(`[pack-bundled-templates] packing ${id} (real build — this takes a while)…`);
+    const packed = await packPlugin(pluginDir);
+    try {
+        const templateOutDir = join(repoOutRoot, id);
+        rmSync(templateOutDir, { recursive: true, force: true });
+        mkdirSync(templateOutDir, { recursive: true });
+        cpSync(packed.archivePath, join(templateOutDir, "package.tar.gz"));
+        // manifest.json and sample-content.json (when present) come from the
+        // build's own outDir — velora-plugin's writeManifestJson/
+        // copySampleContentIfPresent already put them there; this only ever
+        // COPIES what the build produced, never regenerates it.
+        const manifestJsonPath = join(packed.buildResult.outDir, "manifest.json");
+        if (!existsSync(manifestJsonPath)) {
+            throw new Error(`pack-bundled-templates: ${manifestJsonPath} missing after build — did velora-plugin's writeManifestJson change?`);
+        }
+        cpSync(manifestJsonPath, join(templateOutDir, "manifest.json"));
+        const sampleContentPath = join(packed.buildResult.outDir, "sample-content.json");
+        if (existsSync(sampleContentPath)) {
+            cpSync(sampleContentPath, join(templateOutDir, "sample-content.json"));
+        }
+        console.log(`[pack-bundled-templates] ${id} -> ${templateOutDir}`);
+    }
+    finally {
+        // packPlugin leaves <pluginDir>/<id>-<version>.tar.gz behind (its
+        // default outFile) — apps/marketplace/scripts/seed-artifact-one.ts's
+        // precedent for cleaning it up unconditionally, success or failure.
+        rmSync(packed.archivePath, { force: true });
+    }
+}
+async function main() {
+    for (const pluginDir of PLUGIN_DIRS) {
+        await packOne(pluginDir);
+    }
+    rmSync(distOutRoot, { recursive: true, force: true });
+    cpSync(repoOutRoot, distOutRoot, { recursive: true });
+    console.log(`[pack-bundled-templates] copied bundled templates -> ${distOutRoot}`);
+}
+main().catch((error) => {
+    // Loud failure, same convention as copy-docs-bundle.ts: a broken bundled
+    // template is a build regression, never a skippable case.
+    console.error(`[pack-bundled-templates] failed: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+    process.exit(1);
+});

package/dist/setup/build-connection-string.d.ts

@@ -0,0 +1,19 @@
+export type DatabaseSelection = {
+    dialect: "sqlite";
+    filePath: string;
+} | {
+    dialect: "postgresql";
+    host: string;
+    port: number;
+    database: string;
+    username: string;
+    password: string;
+} | {
+    dialect: "mysql";
+    host: string;
+    port: number;
+    database: string;
+    username: string;
+    password: string;
+};
+export declare function buildConnectionString(selection: DatabaseSelection): string;

package/dist/setup/build-connection-string.js

@@ -0,0 +1,14 @@
+import { normalizeDatabaseUrl } from "./normalize-database-url.js";
+// Credentials must be encoded — a password containing @, :, or / would
+// otherwise silently corrupt the assembled URL (e.g. a literal "@" in
+// the password would be parsed as the user/host separator).
+export function buildConnectionString(selection) {
+    if (selection.dialect === "sqlite") {
+        // Absolute, always — see normalize-database-url.ts for why a relative
+        // file: URL becomes two physical databases.
+        return normalizeDatabaseUrl(selection.filePath);
+    }
+    const user = encodeURIComponent(selection.username);
+    const password = encodeURIComponent(selection.password);
+    return `${selection.dialect}://${user}:${password}@${selection.host}:${selection.port}/${selection.database}`;
+}

package/dist/setup/bundled-templates.d.ts

@@ -0,0 +1,19 @@
+import type { BundledTemplate } from "@velora-cms/api-schemas";
+export declare function resolveBundledTemplatesDir(): string | null;
+/**
+ * Never throws. Returns [] when the bundled-templates directory can't be
+ * resolved, is empty, or every entry in it is malformed — the "outside
+ * setup mode" and "nothing bundled" cases both answer this way from
+ * routes/setup.ts.
+ */
+export declare function listBundledTemplates(): BundledTemplate[];
+/**
+ * Resolves the packed archive for one bundled template by EXACT match
+ * against listBundledTemplates() — pluginId is only ever compared with
+ * `===`, never joined into a filesystem path itself. The path actually
+ * joined and returned is built from the matched listing's own pluginId
+ * (which came from enumerating real directory entries, not from the
+ * request), so an unrelated or path-traversal-shaped input can only ever
+ * fail to match and return null.
+ */
+export declare function resolveBundledTemplateTarball(pluginId: string): string | null;

package/dist/setup/bundled-templates.js

@@ -0,0 +1,121 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+// Lists the first-party starter templates pack-bundled-templates.ts (a
+// build-time script) packs into the server build, for the setup wizard's
+// optional "starter template" step. Resolution order mirrors
+// routes/docs-static.ts's resolveDocsDir() exactly:
+//   1. VELORA_BUNDLED_TEMPLATES_DIR (ops override)
+//   2. <server dist>/bundled-templates (what pack-bundled-templates.ts
+//      copies there — the production-shaped location)
+//   3. <repo>/apps/server/bundled-templates (the pre-copy location the
+//      script writes FIRST, and the only one that exists when running the
+//      server straight off `tsx` in the monorepo — same "dev candidate"
+//      role docs-static.ts's apps/docs/dist-bundle candidate plays there)
+// This module is imported by routes/setup.ts, which is registered by BOTH
+// buildApp() (full app, db access available) and buildSetupOnlyApp() (a
+// bare Fastify app during first-run setup, NO db access) — so everything
+// here must be pure filesystem, never prisma/adapter.
+//
+// A missing or malformed bundled-templates tree NEVER throws: it degrades
+// to an empty list, same "never break boot over an optional extra"
+// philosophy as docs-static.ts's 404-with-cause.
+function isUsableBundledTemplatesDir(candidate) {
+    try {
+        return statSync(candidate).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveBundledTemplatesDir() {
+    const override = process.env.VELORA_BUNDLED_TEMPLATES_DIR;
+    if (override) {
+        const resolved = resolve(override);
+        return isUsableBundledTemplatesDir(resolved) ? resolved : null;
+    }
+    const here = dirname(fileURLToPath(import.meta.url)); // dist/setup or src/setup
+    const candidates = [
+        join(here, "..", "bundled-templates"), // dist sibling: dist/setup/../bundled-templates
+        join(here, "..", "..", "bundled-templates"), // repo path: apps/server/bundled-templates
+        // (same two levels-up from both dist/setup and src/setup, since both
+        // sit two directories under the apps/server package root)
+    ];
+    return candidates.find(isUsableBundledTemplatesDir) ?? null;
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/**
+ * Reads and validates one <bundledTemplatesDir>/<entryName>/manifest.json.
+ * Returns null (never throws) for anything unreadable, unparsable, or
+ * missing the fields the setup wizard needs — a malformed entry is
+ * skipped, not fatal to the rest of the listing.
+ */
+function readTemplateListing(templateDir) {
+    const manifestPath = join(templateDir, "manifest.json");
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!isNonEmptyString(parsed.id) || !isNonEmptyString(parsed.name) || !isNonEmptyString(parsed.version)) {
+        return null;
+    }
+    const sampleContent = existsSync(join(templateDir, "sample-content.json"));
+    return {
+        pluginId: parsed.id,
+        version: parsed.version,
+        name: parsed.name,
+        ...(isNonEmptyString(parsed.description) ? { description: parsed.description } : {}),
+        sampleContent,
+    };
+}
+/**
+ * Never throws. Returns [] when the bundled-templates directory can't be
+ * resolved, is empty, or every entry in it is malformed — the "outside
+ * setup mode" and "nothing bundled" cases both answer this way from
+ * routes/setup.ts.
+ */
+export function listBundledTemplates() {
+    const dir = resolveBundledTemplatesDir();
+    if (!dir)
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+    const templates = [];
+    for (const entryName of entries) {
+        const listing = readTemplateListing(join(dir, entryName));
+        if (listing)
+            templates.push(listing);
+    }
+    return templates;
+}
+/**
+ * Resolves the packed archive for one bundled template by EXACT match
+ * against listBundledTemplates() — pluginId is only ever compared with
+ * `===`, never joined into a filesystem path itself. The path actually
+ * joined and returned is built from the matched listing's own pluginId
+ * (which came from enumerating real directory entries, not from the
+ * request), so an unrelated or path-traversal-shaped input can only ever
+ * fail to match and return null.
+ */
+export function resolveBundledTemplateTarball(pluginId) {
+    const match = listBundledTemplates().find((template) => template.pluginId === pluginId);
+    if (!match)
+        return null;
+    const dir = resolveBundledTemplatesDir();
+    if (!dir)
+        return null;
+    const tarballPath = join(dir, match.pluginId, "package.tar.gz");
+    return existsSync(tarballPath) ? tarballPath : null;
+}

package/dist/setup/ensure-prisma-client.d.ts

@@ -0,0 +1,3 @@
+export declare function ensurePrismaClientGenerated(dialect: "postgresql" | "mysql" | "sqlite", opts?: {
+    clientDir?: string;
+}): Promise<"present" | "generated">;

package/dist/setup/ensure-prisma-client.js

@@ -0,0 +1,23 @@
+import { clientDirFor, generatePrismaClients } from "../scripts/generate-prisma-clients.js";
+import { hasGeneratedClientOnDisk } from "../db/resolve-client-dir.js";
+// An npm-installed server ships no generated Prisma clients (they are
+// platform-specific and huge) — the dialect's client is generated on this
+// machine the first time it is needed: at wizard provisioning, and here at
+// boot as self-heal after a node_modules wipe.
+export async function ensurePrismaClientGenerated(dialect, opts = {}) {
+    // resolve-client-dir.ts:64-66 gives VELORA_PRISMA_CLIENT_DIR strict
+    // precedence over the dialect-derived dist/prisma-clients/<dialect> path
+    // — velora-dev's sandbox sets it to point at its own state directory for
+    // every --db choice. Honor that same precedence here: when it's set,
+    // that directory's owner (not this self-heal) manages what lives there.
+    // Generating into clientDirFor(dialect) instead would spend up to a
+    // minute producing a client at a path boot never actually loads.
+    if (process.env.VELORA_PRISMA_CLIENT_DIR?.trim())
+        return "present";
+    const dir = opts.clientDir ?? clientDirFor(dialect);
+    if (hasGeneratedClientOnDisk(dir))
+        return "present";
+    console.log(`generating Prisma clients for ${dialect} (first run after install — this can take a minute)…`);
+    await generatePrismaClients([dialect]);
+    return "generated";
+}

package/dist/setup/install-starter.d.ts

@@ -0,0 +1,14 @@
+import type { PrismaClient } from "@prisma/client";
+import type { SetupStarterResult, SetupStarterSelection } from "@velora-cms/api-schemas";
+export interface InstallStarterTemplateOptions {
+    /** The setup handler's dialect-specific client, still connected — the
+     * same instance that just created the admin user. */
+    prisma: PrismaClient;
+    /** The just-built connection string for the chosen database — not in
+     * process.env yet at this point in the request. */
+    databaseUrl: string;
+    /** The freshly-created admin row's id: sample content's createdBy. */
+    adminUserId: string;
+    starter: SetupStarterSelection;
+}
+export declare function installStarterTemplate(options: InstallStarterTemplateOptions): Promise<SetupStarterResult>;

package/dist/setup/install-starter.js

@@ -0,0 +1,76 @@
+import { connectContentDbAt } from "../db/content-db.js";
+import { installPackageTarball } from "../plugins/install-package-tarball.js";
+import { PluginRegistryService } from "../plugins/plugin-registry-service.js";
+import { resolveBundledTemplateTarball } from "./bundled-templates.js";
+export async function installStarterTemplate(options) {
+    const { prisma, databaseUrl, adminUserId, starter } = options;
+    const failed = (reason) => ({
+        pluginId: starter.pluginId,
+        outcome: "failed",
+        reason,
+    });
+    try {
+        const tarballPath = resolveBundledTemplateTarball(starter.pluginId);
+        if (!tarballPath) {
+            return failed(`No bundled starter template found for "${starter.pluginId}"`);
+        }
+        // The content-db connection for the CHOSEN database — brings the
+        // content tables up to date (the setup-only app never connected a
+        // content db; the later real boot re-runs the same migrations
+        // idempotently via velora_migrations).
+        const contentDb = await connectContentDbAt(databaseUrl);
+        try {
+            // Same service construction as install-built-package.ts's CLI entry:
+            // the registry service plus the three prisma-backed row callbacks.
+            const service = new PluginRegistryService(prisma, contentDb.adapter, {
+                activeDialect: contentDb.dialect,
+            });
+            const setRemoteUrl = async (pluginId, remoteUrl) => {
+                await prisma.pluginRegistry.update({ where: { pluginId }, data: { remoteUrl } });
+            };
+            const syncManifestFields = async (pluginId, fields) => {
+                await prisma.pluginRegistry.update({ where: { pluginId }, data: fields });
+            };
+            const setPackagePath = async (pluginId, packagePath) => {
+                await prisma.pluginRegistry.update({ where: { pluginId }, data: { packagePath } });
+            };
+            // remoteUrl "" — a template plugin has no client bundle, so there is
+            // no remoteEntry.js to point the admin loader at (the same rule
+            // install-from-marketplace.ts applies to view-less plugin types).
+            await installPackageTarball(service, tarballPath, "", setRemoteUrl, syncManifestFields, setPackagePath, {
+                seed: starter.includeSampleContent
+                    ? { prisma, adapter: contentDb.adapter, createdBy: adminUserId }
+                    : undefined,
+            });
+            return { pluginId: starter.pluginId, outcome: "installed" };
+        }
+        finally {
+            // Best-effort: a disconnect hiccup must not convert a completed
+            // install into a reported failure via the outer catch.
+            try {
+                await contentDb.adapter.disconnect();
+            }
+            catch (disconnectError) {
+                console.warn("[install-starter] content-db disconnect failed after starter install", disconnectError);
+            }
+        }
+    }
+    catch (error) {
+        console.error(`[install-starter] starter "${starter.pluginId}" failed — setup itself stands`, error);
+        return failed(failureReason(error));
+    }
+}
+/**
+ * Compresses an arbitrary thrown error into a schema-safe, single-line
+ * `reason` for the setup response: first line only, trimmed, capped at
+ * 200 chars, never empty ("" would fail SetupStarterResultSchema's
+ * `min(1)` and turn an already-succeeded setup into a 500). This response
+ * is unauthenticated, so the full error (stack, paths, connection
+ * strings) stays in the server-side log above — never in the reason.
+ */
+function failureReason(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const firstLine = (message.split("\n", 1)[0] ?? "").trim();
+    const capped = firstLine.length > 200 ? firstLine.slice(0, 200) : firstLine;
+    return capped.length > 0 ? capped : "unknown error";
+}

package/dist/setup/normalize-database-url.d.ts

@@ -0,0 +1,2 @@
+export declare const FILE_PREFIX = "file:";
+export declare function normalizeDatabaseUrl(url: string, cwd?: string): string;

package/dist/setup/normalize-database-url.js

@@ -0,0 +1,35 @@
+import { isAbsolute, resolve } from "node:path";
+// Config-visible constant, not a magic literal repeated between this
+// module and its own tests (env-file-path.ts's DEFAULT_ENV_FILENAME sets
+// the same precedent) — normalize-database-url.test.ts and
+// build-connection-string.test.ts import this instead of spelling "file:"
+// out themselves.
+export const FILE_PREFIX = "file:";
+// One choke point for the Session 155 "one sqlite database is two files"
+// trap. A relative `file:` URL is resolved differently by Prisma's CLI
+// (schema-directory-relative, see setup/provision-database.ts's
+// `--schema` invocation) and by the content-db adapter (cwd-relative), so
+// `file:./velora.db` produced two physical files that were each
+// internally consistent and collectively wrong — the operator backs up
+// the one they were told about, which may not be the one being written.
+//
+// Making the path absolute removes the divergence rather than documenting
+// it: there is nothing relative left for the two resolvers to disagree
+// about.
+//
+// Applied in TWO places, which together cover every source of a database
+// URL: buildConnectionString (what the wizard collects) and index.ts (an
+// externally injected DATABASE_URL, normalised in place at boot before
+// anything reads it).
+//
+// Non-sqlite URLs are returned byte-identical — the credential encoding
+// buildConnectionString performs must not be disturbed.
+export function normalizeDatabaseUrl(url, cwd = process.cwd()) {
+    const isFileUrl = url.startsWith(FILE_PREFIX);
+    if (!isFileUrl && url.includes("://"))
+        return url;
+    const path = isFileUrl ? url.slice(FILE_PREFIX.length) : url;
+    if (path.length === 0)
+        return url;
+    return `${FILE_PREFIX}${isAbsolute(path) ? path : resolve(cwd, path)}`;
+}

package/dist/setup/persist-env-config.d.ts

@@ -0,0 +1,2 @@
+export declare function upsertEnvVars(content: string, vars: Record<string, string>): string;
+export declare function persistDatabaseConfig(databaseUrl: string, envPath?: string): void;

package/dist/setup/persist-env-config.js

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolveEnvFilePath } from "../config/env-file-path.js";
+export function upsertEnvVars(content, vars) {
+    let out = content;
+    for (const [key, value] of Object.entries(vars)) {
+        const line = `${key}=${value}`;
+        const pattern = new RegExp(`^${key}=.*$`, "m");
+        if (pattern.test(out)) {
+            out = out.replace(pattern, () => line);
+        }
+        else {
+            out = out.length > 0 && !out.endsWith("\n") ? `${out}\n${line}\n` : `${out}${line}\n`;
+        }
+    }
+    return out;
+}
+// Writes ONLY DATABASE_URL, and only to the path config/env-file-path.ts
+// resolves — the same path load-env.ts reads at the next boot, so the two
+// cannot drift.
+//
+// Two things this deliberately no longer does:
+//
+//   - It no longer walks four levels up from its own compiled location to
+//     find the repo root. That assumed the monorepo's directory depth and
+//     overshot on a flattened `pnpm deploy` output.
+//
+//   - It no longer writes VELORA_PRISMA_CLIENT_DIR. That was an absolute
+//     path captured from the machine that ran setup, wrong as soon as the
+//     install moved. db/resolve-client-dir.ts derives it from
+//     DATABASE_URL's scheme instead. The variable is still READ, and
+//     still wins when set explicitly — velora-dev's sandbox depends on
+//     that (packages/velora-dev/src/config.ts).
+//
+// One thing that was true before this file's packaging rework and still
+// is: this only ever writes a physical .env FILE. A deployment target
+// configured entirely by externally injected environment variables (a
+// container's env block, a platform's secret manager) has no file for
+// this to find or create, and persisting to one there would be actively
+// wrong — nothing downstream would read it back, and it would leave a
+// stray file with no one owning its lifecycle. That per-deployment-shape
+// decision now DOES exist upstream, in routes/setup.ts's POST
+// /api/setup/complete handler: it calls persistDatabaseConfig() only when
+// `!opts.databaseConfigured` (the setup-full path, where DATABASE_URL was
+// unset at boot). In admin-only mode (opts.databaseConfigured: true —
+// DATABASE_URL was already injected by the environment) it skips this
+// call entirely, precisely because that shape has nothing of its own to
+// persist. This module still just writes to whatever path it's given (or
+// resolveEnvFilePath() derives) — it has no opinion of its own about
+// when it should run; that decision belongs to, and now lives in, the
+// caller.
+//
+// Only ever called on the setup-full path (routes/setup.ts's
+// `if (!opts.databaseConfigured)` guard around this call), where
+// DATABASE_URL was unset at boot. Two other cases never reach it: an
+// already-fully-configured instance (setupRequired: false) is rejected by
+// this route's earlier 409 guard before any of this runs at all, and
+// admin-only mode (opts.databaseConfigured: true, DATABASE_URL already
+// injected by the environment) reaches admin creation but is excluded by
+// that same `if` — see the comment above for why.
+export function persistDatabaseConfig(databaseUrl, envPath = resolveEnvFilePath()) {
+    const existing = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+    writeFileSync(envPath, upsertEnvVars(existing, { DATABASE_URL: databaseUrl }));
+}

package/dist/setup/provision-database.d.ts

@@ -0,0 +1,2 @@
+import type { Dialect } from "@velora-cms/prisma-variants";
+export declare function provisionDatabase(dialect: Dialect, databaseUrl: string): Promise<void>;

package/dist/setup/provision-database.js

@@ -0,0 +1,89 @@
+import { execFile } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { writeVariantSchema } from "../scripts/generate-prisma-clients.js";
+const execFileAsync = promisify(execFile);
+// Anchored the same way generate-prisma-clients.ts anchors its own
+// SERVER_DIR (see that file's comment): npx should always resolve
+// `prisma` as apps/server's own devDependency, not walk up from whatever
+// cwd happened to invoke this function and potentially trigger an
+// unwanted auto-install. Compiled location is dist/setup/provision-database.js,
+// two levels under the package root (dist/setup -> dist -> apps/server) —
+// same depth as dist/scripts.
+const SERVER_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+// Deliberately `db push`, never `migrate deploy`/`migrate dev`: the real
+// migration history under apps/server/prisma/migrations/ is hard-locked
+// to provider = "postgresql" (migration_lock.toml) and its SQL is
+// Postgres-specific — pointing a mysql/sqlite schema variant at it fails
+// outright. `db push` is provider-agnostic and has no migration-history
+// dependency, matching velora-dev's sandbox (Session 78) and Session 94's
+// own verification test. Trade-off, deliberately unsolved this session: a
+// database provisioned this way has no _prisma_migrations table, so it
+// can't later be incrementally upgraded via a normal `migrate deploy` —
+// that's a separate problem (existing self-hosted instance schema
+// updates), not first-run setup.
+// Twin of generate-prisma-clients.ts's runPrismaGenerate — same spawnSync +
+// stdio: "inherit" + shell: true pattern, same fix for the same reason (see
+// that file's comment on the vitest-worker "onTaskUpdate" RPC timeout).
+// This call site's own single spawnSync is shorter in isolation (~10-12s
+// against real infra), but it is a live setup-request code path — provision
+// on any given call can run slower under load (the full-suite run's
+// mysql-dialect setup-complete case measured 37s wall for the whole
+// request) — so it carries the same class of risk and gets the same fix.
+async function provisionDatabaseNow(dialect, databaseUrl) {
+    const variantPath = writeVariantSchema(dialect);
+    try {
+        const { stdout, stderr } = await execFileAsync("npx", ["prisma", "db", "push", "--schema", `"${variantPath}"`, "--skip-generate"], {
+            cwd: SERVER_DIR,
+            shell: true,
+            // Same rationale as generate-prisma-clients.ts: the 1 MiB default
+            // maxBuffer kills the child on overflow — setup must never fail
+            // that way over verbose prisma output.
+            maxBuffer: 64 * 1024 * 1024,
+            env: { ...process.env, DATABASE_URL: databaseUrl },
+        });
+        if (stdout)
+            process.stdout.write(stdout);
+        if (stderr)
+            process.stderr.write(stderr);
+    }
+    catch (error) {
+        const failed = error;
+        if (failed.stdout)
+            process.stdout.write(failed.stdout);
+        if (failed.stderr)
+            process.stderr.write(failed.stderr);
+        throw new Error(`provisionDatabase: prisma db push failed for ${dialect} (exit ${failed.code})`);
+    }
+}
+// `prisma db push` is not safe to run truly concurrently against the same
+// target: two overlapping schema-engine invocations racing on the same
+// fresh schema were observed to fail outright — postgresql refuses with a
+// data-loss warning it can't auto-accept, mysql fails a bare `CREATE TABLE`
+// with "already exists" — instead of both landing cleanly. Before this
+// file's spawnSync -> execFile conversion this was invisible: spawnSync
+// blocks the entire process, so two "concurrent" provisionDatabase() calls
+// in the same Node process could never actually overlap — the second
+// caller's code couldn't even start running until the first's synchronous
+// call returned, which serialized them as a side effect. Fixing the real
+// bug (spawnSync blocking the event loop past vitest's RPC timeout) removed
+// that accidental serialization and exposed the race directly:
+// setup-complete.integration.test.ts's M-3 concurrent-completion test
+// started seeing [200, 400] instead of [200, 409] on both postgresql and
+// mysql. Restoring in-process serialization explicitly — a bare promise
+// chain, not a new dependency — keeps calls in the SAME process (e.g. two
+// inbound setup requests racing the same live server, exactly what that
+// test reproduces) queued one at a time, while still letting the event
+// loop answer other work between them. Calls from separate processes
+// (separate vitest workers, a real deploy) are unaffected either way, same
+// as before.
+let queue = Promise.resolve();
+export function provisionDatabase(dialect, databaseUrl) {
+    const run = queue.then(() => provisionDatabaseNow(dialect, databaseUrl));
+    // Chain the queue off a version that never rejects, so one failed
+    // provision doesn't wedge every call queued after it — each caller still
+    // observes its own real outcome (including a real rejection) via `run`.
+    queue = run.then(() => undefined, () => undefined);
+    return run;
+}

package/dist/setup-app.d.ts

@@ -0,0 +1,4 @@
+import { type FastifyInstance } from "fastify";
+export declare function buildSetupOnlyApp(opts?: {
+    databaseConfigured: boolean;
+}): Promise<FastifyInstance>;

package/dist/setup-app.js

@@ -0,0 +1,43 @@
+import Fastify from "fastify";
+import { serializerCompiler, validatorCompiler } from "fastify-type-provider-zod";
+import { adminStaticRoutes } from "./routes/admin-static.js";
+import { setupRoutes } from "./routes/setup.js";
+// The reduced "not configured yet" boot mode (Session 96), later widened
+// (Task 4, boot/resolve-boot-mode.ts's resolveBootMode) to a second case:
+// a genuinely minimal app, built whenever resolveBootMode() picks anything
+// other than "full" — that's no longer only DATABASE_URL being unset
+// (setup-full); it's also "setup-admin-only", where DATABASE_URL IS set
+// but no admin row exists yet. Never calls connectContentDb(), never
+// touches prisma, never constructs PluginRegistryService/MediaService/
+// StructuredStorageAPI — in the setup-full case there is nothing
+// configured for those to connect to yet, and in setup-admin-only the
+// whole point of this app is the single admin-creation route, not the
+// rest of the stack. This is a SEPARATE boot path, not a gate inside
+// buildApp() itself: buildApp() calls connectContentDb() before any hook
+// could be registered, and connectContentDb() throws immediately when no
+// database URL is set — a hook registered later in the same app could
+// never run in that case.
+//
+// Session 164: also built when DATABASE_URL IS set but the database holds
+// no admin user — the admin-only mode. In that case Prisma HAS already
+// been reached, by boot/resolve-boot-mode.ts's probe, before this app was
+// chosen; the "never touches prisma" invariant above is about the
+// unconfigured path and still holds there.
+export async function buildSetupOnlyApp(opts = { databaseConfigured: false }) {
+    const app = Fastify({ logger: true }).withTypeProvider();
+    app.setValidatorCompiler(validatorCompiler);
+    app.setSerializerCompiler(serializerCompiler);
+    await app.register(setupRoutes, { setupRequired: true, databaseConfigured: opts.databaseConfigured });
+    // S184: the wizard IS the admin SPA, so this reduced boot mode has to
+    // serve /velora too — a fresh install has no other browser surface.
+    // Registered BEFORE setNotFoundHandler below, and route matching beats a
+    // not-found handler regardless, so the 503 "not configured yet" reply
+    // still covers every path this module does not own. admin-static.ts is
+    // deliberately Prisma-free (see its rate-limit comment) so importing it
+    // here cannot violate this path's no-Prisma invariant.
+    await app.register(adminStaticRoutes);
+    app.setNotFoundHandler((_request, reply) => {
+        reply.code(503).send({ message: "Velora is not configured yet — complete setup first." });
+    });
+    return app;
+}