@velora-cms/server 0.11.0

package/dist/routes/users.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { ApiErrorSchema, CreateUserRequestSchema, CreateUserResponseSchema, UpdateUserRoleRequestSchema, UpdateUserRoleResponseSchema, UserListQuerySchema, UserListResponseSchema, } from "@velora-cms/api-schemas";
+import { prisma } from "../db/prisma.js";
+import { hashPassword } from "../auth/tokens.js";
+import { requireAdmin } from "../auth/require-auth.js";
+const UserParamsSchema = z.object({ id: z.string().uuid() });
+function toSummary(user) {
+    // Deliberately reconstructed field by field — passwordHash must never
+    // ride along by spread.
+    return {
+        id: user.id,
+        email: user.email,
+        name: user.name,
+        role: user.role,
+        createdAt: user.createdAt.toISOString(),
+    };
+}
+// Every route here is admin-only — user management is itself the "one
+// real thing" the editor role is locked out of (403, enforced
+// server-side, not just hidden in the UI).
+export const usersRoutes = async (app) => {
+    app.get("/api/users", {
+        onRequest: requireAdmin,
+        schema: {
+            querystring: UserListQuerySchema,
+            response: {
+                200: UserListResponseSchema,
+                401: ApiErrorSchema,
+                403: ApiErrorSchema,
+            },
+        },
+    }, async (request) => {
+        const { cursor, limit } = request.query;
+        const rows = await prisma.user.findMany({
+            orderBy: [{ createdAt: "asc" }, { id: "asc" }],
+            take: limit,
+            ...(cursor ? { cursor: { id: cursor }, skip: 1 } : {}),
+        });
+        const nextCursor = rows.length === limit ? (rows[rows.length - 1]?.id ?? null) : null;
+        return { items: rows.map(toSummary), nextCursor };
+    });
+    app.post("/api/users", {
+        onRequest: requireAdmin,
+        schema: {
+            body: CreateUserRequestSchema,
+            response: {
+                201: CreateUserResponseSchema,
+                401: ApiErrorSchema,
+                403: ApiErrorSchema,
+                409: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const { email, name, password, role } = request.body;
+        try {
+            const user = await prisma.user.create({
+                data: {
+                    email,
+                    name: name ?? null,
+                    passwordHash: await hashPassword(password),
+                    role,
+                },
+            });
+            return reply.code(201).send({ user: toSummary(user) });
+        }
+        catch (error) {
+            // Duck-typed on `.code`, not `instanceof Prisma.PrismaClientKnownRequestError`:
+            // `prisma` (db/prisma.ts) is loaded dynamically per VELORA_PRISMA_CLIENT_DIR
+            // (Session 94's multi-dialect client generation), so the error thrown by that
+            // runtime's client is a *different* module instance than the statically
+            // imported `@prisma/client` here — `instanceof` across that boundary always
+            // returns false, silently turning every duplicate-email conflict into a 500.
+            // `code` is a stable string on the wire regardless of which client instance
+            // threw it, so it survives the cross-module-instance gap `instanceof` doesn't.
+            if (error &&
+                typeof error === "object" &&
+                "code" in error &&
+                error.code === "P2002") {
+                return reply.code(409).send({ message: `A user with email ${email} already exists` });
+            }
+            throw error;
+        }
+    });
+    app.patch("/api/users/:id/role", {
+        onRequest: requireAdmin,
+        schema: {
+            params: UserParamsSchema,
+            body: UpdateUserRoleRequestSchema,
+            response: {
+                200: UpdateUserRoleResponseSchema,
+                400: ApiErrorSchema,
+                401: ApiErrorSchema,
+                403: ApiErrorSchema,
+                404: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        // Changing your own role is refused outright — the cheap, robust
+        // guard against demoting the last admin and locking everyone out.
+        if (request.params.id === request.user.sub) {
+            return reply.code(400).send({ message: "You cannot change your own role" });
+        }
+        const existing = await prisma.user.findUnique({ where: { id: request.params.id } });
+        if (!existing) {
+            return reply.code(404).send({ message: `No user found for id ${request.params.id}` });
+        }
+        const user = await prisma.user.update({
+            where: { id: existing.id },
+            data: { role: request.body.role },
+        });
+        return { user: toSummary(user) };
+    });
+};

package/dist/sandbox/register-local-plugin.d.ts

@@ -0,0 +1,36 @@
+import { PluginRegistryService } from "../plugins/plugin-registry-service.js";
+import type { TrustTier } from "../plugins/verify-package.js";
+export type RegisterLocalPluginResult = "installed" | "activated" | "already-active";
+/** The manifest entry point convention every plugin (scaffolded or
+ * hand-built) shares: a default-exported CMSPlugin in src/plugin.ts(x). */
+export declare function resolveManifestPath(pluginDir: string): string;
+/** The registry-row columns derived from the manifest (as opposed to
+ * `remoteUrl`, which comes from where velora-dev happened to boot the
+ * plugin) — what syncManifestFields writes when a re-registered manifest
+ * has changed since the row was created. */
+export interface ManifestRowFields {
+    name: string;
+    type: string;
+    version: string;
+    storageType: string;
+    /** Session 127: re-synced on re-registration for the same reason the
+     * others are — a re-install of a tampered package must DOWNGRADE a
+     * previously-verified row rather than leave a stale "verified" behind. */
+    trustTier: TrustTier;
+}
+/**
+ * Idempotent: install() throws on an existing row, so this checks first.
+ * A restart (fresh process, empty in-memory manifests map) still needs
+ * attachManifest() before activate() can run — install() only attaches
+ * automatically on the FIRST call in a given process's lifetime.
+ * remoteUrl is set unconditionally (even on a no-op activation) since a
+ * fixed sandbox port never changes, but keeps the row honest either way.
+ * On the existing-row path, name/type/version/storageType are re-synced
+ * from the freshly-read manifest whenever they differ from the row —
+ * this tool's whole premise is iterating on a local plugin between
+ * sandbox restarts, so a manifest edit (bumped version, renamed plugin,
+ * changed storage tier) must not go stale in the registry forever.
+ */
+export declare function registerLocalPlugin(service: PluginRegistryService, rawManifest: unknown, remoteUrl: string, setRemoteUrl: (pluginId: string, remoteUrl: string) => Promise<void>, syncManifestFields: (pluginId: string, fields: ManifestRowFields) => Promise<void>, opts?: {
+    trustTier?: TrustTier;
+}): Promise<RegisterLocalPluginResult>;

package/dist/sandbox/register-local-plugin.js

@@ -0,0 +1,108 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { validatePluginManifest } from "@velora-cms/plugin-sdk/manifest";
+import { PluginInstallError, PluginRegistryService } from "../plugins/plugin-registry-service.js";
+/** The manifest entry point convention every plugin (scaffolded or
+ * hand-built) shares: a default-exported CMSPlugin in src/plugin.ts(x). */
+export function resolveManifestPath(pluginDir) {
+    const tsxPath = join(pluginDir, "src", "plugin.tsx");
+    if (existsSync(tsxPath))
+        return tsxPath;
+    const tsPath = join(pluginDir, "src", "plugin.ts");
+    if (existsSync(tsPath))
+        return tsPath;
+    throw new Error(`No plugin manifest found at ${pluginDir} — expected src/plugin.tsx or src/plugin.ts`);
+}
+/**
+ * Idempotent: install() throws on an existing row, so this checks first.
+ * A restart (fresh process, empty in-memory manifests map) still needs
+ * attachManifest() before activate() can run — install() only attaches
+ * automatically on the FIRST call in a given process's lifetime.
+ * remoteUrl is set unconditionally (even on a no-op activation) since a
+ * fixed sandbox port never changes, but keeps the row honest either way.
+ * On the existing-row path, name/type/version/storageType are re-synced
+ * from the freshly-read manifest whenever they differ from the row —
+ * this tool's whole premise is iterating on a local plugin between
+ * sandbox restarts, so a manifest edit (bumped version, renamed plugin,
+ * changed storage tier) must not go stale in the registry forever.
+ */
+export async function registerLocalPlugin(service, rawManifest, remoteUrl, setRemoteUrl, syncManifestFields, opts) {
+    const result = validatePluginManifest(rawManifest);
+    if (!result.ok) {
+        // PluginInstallError (not a plain Error), matching
+        // PluginRegistryService.install()'s own identical check verbatim —
+        // this call always runs first for the built-package install path
+        // (installBuiltPackage -> registerLocalPlugin -> service.install()),
+        // so a real manifest-validation failure is thrown HERE, not inside
+        // install(). Marketplace-install.ts's typed-error mapping
+        // (`instanceof PluginInstallError`) needs this to be the same class
+        // install() throws, or a marketplace install with a genuinely invalid
+        // manifest would fall through to an unmapped 500 instead of the
+        // intended 422.
+        throw new PluginInstallError(`Plugin manifest failed validation:\n${result.errors.map((e) => `  - ${e}`).join("\n")}`, result.errors);
+    }
+    const manifest = result.manifest;
+    const trustTier = opts?.trustTier ?? "unverified";
+    const existing = await service.getInstalledPlugin(manifest.id);
+    let outcome;
+    if (!existing) {
+        await service.install(manifest, { trustTier });
+        outcome = "installed";
+    }
+    else {
+        await service.attachManifest(manifest);
+        outcome = existing.enabled ? "already-active" : "activated";
+        const fresh = {
+            name: manifest.name,
+            type: manifest.type,
+            version: manifest.version,
+            storageType: manifest.databaseCompatibility.storageType,
+            trustTier,
+        };
+        if (existing.name !== fresh.name ||
+            existing.type !== fresh.type ||
+            existing.version !== fresh.version ||
+            existing.storageType !== fresh.storageType ||
+            existing.trustTier !== fresh.trustTier) {
+            await syncManifestFields(manifest.id, fresh);
+        }
+    }
+    await service.activate(manifest.id);
+    await setRemoteUrl(manifest.id, remoteUrl);
+    return outcome;
+}
+// ---- CLI entry (spawned by velora-dev) ------------------------------------
+async function main() {
+    const [pluginDir, remoteUrl] = process.argv.slice(2);
+    if (!pluginDir || !remoteUrl) {
+        throw new Error("Usage: tsx register-local-plugin.ts <pluginDir> <remoteUrl>");
+    }
+    const manifestPath = resolveManifestPath(pluginDir);
+    const mod = await import(pathToFileURL(manifestPath).href);
+    if (!mod.default) {
+        throw new Error(`${manifestPath} has no default export`);
+    }
+    // Since Session 122, the CLI connects through connectContentDb() rather
+    // than hardcoding a PostgreSQLAdapter — this makes the sqlite sandbox a
+    // first-class CLI target (Session 121's live proof needed a throwaway
+    // driver precisely because of the old hardcoded adapter).
+    const { prisma } = await import("../db/prisma.js");
+    const { connectContentDb } = await import("../db/content-db.js");
+    const contentDb = await connectContentDb();
+    const activeDialect = process.env.VELORA_PLUGIN_ACTIVE_DIALECT ?? contentDb.dialect;
+    const service = new PluginRegistryService(prisma, contentDb.adapter, { activeDialect });
+    const outcome = await registerLocalPlugin(service, mod.default, remoteUrl, async (pluginId, url) => {
+        await prisma.pluginRegistry.update({ where: { pluginId }, data: { remoteUrl: url } });
+    }, async (pluginId, fields) => {
+        await prisma.pluginRegistry.update({ where: { pluginId }, data: fields });
+    });
+    console.log(`[velora-dev register] ${mod.default.id}: ${outcome}`);
+    await prisma.$disconnect();
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().catch((error) => {
+        console.error("[velora-dev register] failed:", error);
+        process.exit(1);
+    });
+}

package/dist/sandbox/seed-sandbox.d.ts

@@ -0,0 +1,20 @@
+import { type ContentDb } from "../db/content-db.js";
+export declare const PAGE_DOCUMENT_TYPE_ID = "d0c00000-0000-4000-8000-000000000001";
+export declare const ARTICLE_DOCUMENT_TYPE_ID = "d0c00000-0000-4000-8000-000000000002";
+export interface SeedUserStore {
+    findUnique(args: {
+        where: {
+            email: string;
+        };
+    }): Promise<unknown | null>;
+    create(args: {
+        data: {
+            email: string;
+            passwordHash: string;
+            name: string;
+            role: "admin";
+        };
+    }): Promise<unknown>;
+}
+export declare function seedAdminUser(users: SeedUserStore, email: string, password: string): Promise<"created" | "exists">;
+export declare function seedContent(contentDb: ContentDb, createdBy: string): Promise<"created" | "exists">;

package/dist/sandbox/seed-sandbox.js

@@ -0,0 +1,122 @@
+import { pathToFileURL } from "node:url";
+import { hashPassword } from "../auth/tokens.js";
+import { connectContentDb } from "../db/content-db.js";
+// Sandbox seed (velora-dev Session 78): an admin user, two document
+// types on the stable built-in Data Type config ids that migration 0006
+// seeds, and a small published tree. Idempotent — each half checks its
+// own marker and skips. Spawned by velora-dev via
+// `pnpm --filter @velora-cms/server exec tsx src/sandbox/seed-sandbox.ts`
+// with the sandbox env already set.
+export const PAGE_DOCUMENT_TYPE_ID = "d0c00000-0000-4000-8000-000000000001";
+export const ARTICLE_DOCUMENT_TYPE_ID = "d0c00000-0000-4000-8000-000000000002";
+// Built-in Data Type configs (BUILT_IN_DATA_TYPE_CONFIGS in
+// @velora-cms/api-schemas — seeded by content migration 0006, fixed ids).
+const TEXT_CONFIG_ID = "b1e00000-0000-4000-8000-000000000001";
+const RICHTEXT_CONFIG_ID = "b1e00000-0000-4000-8000-000000000006";
+export async function seedAdminUser(users, email, password) {
+    if (await users.findUnique({ where: { email } })) {
+        return "exists";
+    }
+    await users.create({
+        data: { email, passwordHash: await hashPassword(password), name: "Sandbox Admin", role: "admin" },
+    });
+    return "created";
+}
+const PAGE_TYPE = {
+    id: PAGE_DOCUMENT_TYPE_ID,
+    name: "Page",
+    icon: "file-text",
+    kind: "page",
+    tabs: [],
+    fields: [
+        { id: "title", name: "Title", datatypeId: TEXT_CONFIG_ID },
+        { id: "body", name: "Body", datatypeId: RICHTEXT_CONFIG_ID },
+    ],
+    treeRules: { allowedAtRoot: true, allowedParentTypes: [], allowedChildTypes: [] },
+};
+const ARTICLE_TYPE = {
+    id: ARTICLE_DOCUMENT_TYPE_ID,
+    name: "Article",
+    icon: "newspaper",
+    kind: "page",
+    tabs: [],
+    fields: [
+        { id: "title", name: "Title", datatypeId: TEXT_CONFIG_ID },
+        { id: "body", name: "Body", datatypeId: RICHTEXT_CONFIG_ID },
+    ],
+    treeRules: { allowedAtRoot: false, allowedParentTypes: [PAGE_DOCUMENT_TYPE_ID], allowedChildTypes: [] },
+};
+const ARTICLES = [
+    { slug: "welcome-to-velora", title: "Welcome to Velora" },
+    { slug: "building-your-first-plugin", title: "Building your first plugin" },
+    { slug: "how-content-versioning-works", title: "How content versioning works" },
+];
+export async function seedContent(contentDb, createdBy) {
+    const { adapter, contentService } = contentDb;
+    if (await adapter.getDocumentType(PAGE_DOCUMENT_TYPE_ID)) {
+        return "exists";
+    }
+    await adapter.createDocumentType(PAGE_TYPE);
+    await adapter.createDocumentType(ARTICLE_TYPE);
+    const home = await contentService.createContent({
+        documentTypeId: PAGE_DOCUMENT_TYPE_ID,
+        parentId: null,
+        path: "/home",
+        depth: 0,
+        sortOrder: 0,
+        locale: "en",
+        isDefaultLocale: true,
+        data: {
+            title: "Home",
+            body: "<p>Welcome to your Velora sandbox. Everything here is sample content — edit freely.</p>",
+        },
+        createdBy,
+    });
+    await contentService.publishContent(home.node.id);
+    let sortOrder = 0;
+    for (const article of ARTICLES) {
+        const created = await contentService.createContent({
+            documentTypeId: ARTICLE_DOCUMENT_TYPE_ID,
+            parentId: home.node.id,
+            path: `/home/${article.slug}`,
+            depth: 1,
+            sortOrder: sortOrder++,
+            locale: "en",
+            isDefaultLocale: true,
+            data: { title: article.title, body: `<p>${article.title} — sample article body.</p>` },
+            createdBy,
+        });
+        await contentService.publishContent(created.node.id);
+    }
+    return "created";
+}
+// ---- CLI entry (spawned by velora-dev) ------------------------------------
+async function main() {
+    const email = process.env.VELORA_SANDBOX_ADMIN_EMAIL ?? "admin@velora.dev";
+    const password = process.env.VELORA_SANDBOX_ADMIN_PASSWORD ?? "velora";
+    const { prisma } = await import("../db/prisma.js");
+    const userResult = await seedAdminUser(prisma.user, email, password);
+    // ContentVersion.createdBy is serialized back out through the API
+    // response schema as a strict UUID (packages/api-schemas) — a
+    // human-readable placeholder like "velora-dev-seed" writes fine at the
+    // storage layer but 500s every later GET of this content. Use the real
+    // admin user's id, looked up fresh so this works whether this run just
+    // created the user or it already existed.
+    const adminUser = await prisma.user.findUnique({ where: { email } });
+    if (!adminUser) {
+        throw new Error(`[velora-dev seed] admin user "${email}" not found after seedAdminUser`);
+    }
+    const contentDb = await connectContentDb();
+    const contentResult = await seedContent(contentDb, adminUser.id);
+    await contentDb.adapter.disconnect();
+    await prisma.$disconnect();
+    console.log(`[velora-dev seed] admin user: ${userResult}, content: ${contentResult}`);
+}
+// Only run main() when executed directly (tsx src/sandbox/seed-sandbox.ts),
+// never when imported by the integration test.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().catch((error) => {
+        console.error("[velora-dev seed] failed:", error);
+        process.exit(1);
+    });
+}

package/dist/scripts/copy-admin-bundle.d.ts

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

package/dist/scripts/copy-admin-bundle.js

@@ -0,0 +1,24 @@
+import { cpSync, existsSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// Build-time only. The devDependency on @velora-cms/admin-ui exists purely
+// so turbo's ^build ordering guarantees dist-bundle exists before this
+// runs — server CODE never imports from the admin app. Copying into the
+// server's own dist/ is the docs-bundle pattern (S130), now for the back
+// office (S184): a deployed/packed server must serve the admin with no
+// sibling checkout. Missing bundle = hard build error: an API-only server
+// build stopped being a valid product in S184.
+const here = dirname(fileURLToPath(import.meta.url)); // <server>/dist/scripts
+const serverDist = join(here, "..");
+const repoRoot = join(serverDist, "..", "..", "..");
+const source = join(repoRoot, "apps", "admin-ui", "dist-bundle");
+const target = join(serverDist, "admin-bundle");
+if (!existsSync(source)) {
+    // Loud failure: under turbo ordering the bundle must exist; its absence
+    // means the admin build broke or ordering regressed — not a skippable case.
+    console.error(`[copy-admin-bundle] missing ${source} — did the @velora-cms/admin-ui build run?`);
+    process.exit(1);
+}
+rmSync(target, { recursive: true, force: true });
+cpSync(source, target, { recursive: true });
+console.log(`[copy-admin-bundle] copied admin bundle -> ${target}`);

package/dist/scripts/copy-docs-bundle.d.ts

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

package/dist/scripts/copy-docs-bundle.js

@@ -0,0 +1,22 @@
+import { cpSync, existsSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// Build-time only. The devDependency on @velora-cms/docs exists purely so
+// turbo's ^build ordering guarantees dist-bundle exists before this runs —
+// server CODE never imports from the docs app. Copying into the server's
+// own dist/ is the S121 lesson (a production server deployed without the
+// monorepo must carry its docs inside its own artifact).
+const here = dirname(fileURLToPath(import.meta.url)); // <server>/dist/scripts
+const serverDist = join(here, "..");
+const repoRoot = join(serverDist, "..", "..", "..");
+const source = join(repoRoot, "apps", "docs", "dist-bundle");
+const target = join(serverDist, "docs-bundle");
+if (!existsSync(source)) {
+    // Loud failure: under turbo ordering the bundle must exist; its absence
+    // means the docs build broke or ordering regressed — not a skippable case.
+    console.error(`[copy-docs-bundle] missing ${source} — did the @velora-cms/docs build run?`);
+    process.exit(1);
+}
+rmSync(target, { recursive: true, force: true });
+cpSync(source, target, { recursive: true });
+console.log(`[copy-docs-bundle] copied docs bundle -> ${target}`);

package/dist/scripts/create-api-key.d.ts

@@ -0,0 +1,5 @@
+import { type ApiKeyScope } from "@velora-cms/api-schemas";
+export declare function parseArgs(argv: string[]): {
+    name: string;
+    scope: ApiKeyScope;
+};

package/dist/scripts/create-api-key.js

@@ -0,0 +1,56 @@
+// Creates a public API key and prints the plaintext ONCE — only the hash
+// is stored, so a lost key means creating a new one. The interim key
+// path for Session 101; Session 102's Settings › API Keys UI becomes the
+// primary way, and this stays as an ops fallback.
+//
+// Usage (from repo root, postgres-dev running):
+//   pnpm --filter @velora-cms/server exec dotenv -e ../../.env -- tsx src/scripts/create-api-key.ts "key name" [--scope read|write]
+//
+// --scope defaults to "read" (Session 182: keys are read-only unless
+// explicitly opted into write access).
+import { pathToFileURL } from "node:url";
+import { ApiKeyScopeSchema } from "@velora-cms/api-schemas";
+import { generateApiKey, hashApiKey } from "../auth/api-keys.js";
+import { prisma } from "../db/prisma.js";
+const USAGE = 'Usage: tsx src/scripts/create-api-key.ts "<key name>" [--scope read|write]';
+export function parseArgs(argv) {
+    const args = argv.slice(2);
+    const positional = [];
+    let scopeArg;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--scope") {
+            scopeArg = args[++i];
+        }
+        else {
+            positional.push(args[i]);
+        }
+    }
+    const name = positional[0]?.trim();
+    if (!name) {
+        throw new Error(USAGE);
+    }
+    const parsedScope = ApiKeyScopeSchema.safeParse(scopeArg ?? "read");
+    if (!parsedScope.success) {
+        throw new Error(`${USAGE}\n--scope must be "read" or "write", got "${scopeArg}"`);
+    }
+    return { name, scope: parsedScope.data };
+}
+async function main() {
+    let parsed;
+    try {
+        parsed = parseArgs(process.argv);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+    const { name, scope } = parsed;
+    const key = generateApiKey();
+    await prisma.apiKey.create({ data: { name, keyHash: hashApiKey(key), scope } });
+    console.log(`API key "${name}" created with scope "${scope}". The key is shown once — store it now:`);
+    console.log(key);
+    await prisma.$disconnect();
+}
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    await main();
+}

package/dist/scripts/generate-prisma-clients.d.ts

@@ -0,0 +1,6 @@
+import { type Dialect } from "@velora-cms/prisma-variants";
+export declare function clientDirFor(dialect: Dialect): string;
+export declare function variantPathFor(dialect: Dialect): string;
+export declare function writeVariantSchema(dialect: Dialect): string;
+export declare function generatePrismaClients(dialects?: readonly Dialect[]): Promise<void>;
+export declare function generateDefaultPrismaClient(): Promise<void>;

package/dist/scripts/generate-prisma-clients.js

@@ -0,0 +1,125 @@
+import { execFile } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+import { toMysqlSchema, toPostgresqlSchema, toSqliteSchema } from "@velora-cms/prisma-variants";
+const execFileAsync = promisify(execFile);
+// Ships one pre-generated Prisma client per Tier 1 dialect alongside the
+// built server (apps/server/dist/prisma-clients/<dialect>), so a deployed
+// instance never needs to run `prisma generate` at runtime — Session 96-97's
+// setup wizard just picks which already-built client to load via the
+// existing VELORA_PRISMA_CLIENT_DIR mechanism (apps/server/src/db/prisma.ts).
+//
+// Compiled location is dist/scripts/generate-prisma-clients.js, two levels
+// under the package root (dist/scripts -> dist -> apps/server).
+const SERVER_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const SCHEMA_PATH = join(SERVER_DIR, "prisma", "schema.prisma");
+const TRANSFORMS = {
+    postgresql: toPostgresqlSchema,
+    mysql: toMysqlSchema,
+    sqlite: toSqliteSchema,
+};
+// prisma generate never connects to a database, but it does validate that
+// DATABASE_URL's scheme matches the schema's own provider. A placeholder
+// per dialect keeps this build step reproducible regardless of whatever
+// real DATABASE_URL the machine's .env happens to point at.
+const PLACEHOLDER_URLS = {
+    postgresql: "postgresql://placeholder:placeholder@localhost:5432/placeholder",
+    mysql: "mysql://placeholder:placeholder@localhost:3306/placeholder",
+    sqlite: "file:./placeholder.db",
+};
+export function clientDirFor(dialect) {
+    return join(SERVER_DIR, "dist", "prisma-clients", dialect);
+}
+export function variantPathFor(dialect) {
+    return join(SERVER_DIR, "prisma", `.prisma-variant-${dialect}.schema.prisma`);
+}
+const ALL_DIALECTS = ["postgresql", "mysql", "sqlite"];
+export function writeVariantSchema(dialect) {
+    const source = readFileSync(SCHEMA_PATH, "utf8");
+    const variantPath = variantPathFor(dialect);
+    writeFileSync(variantPath, TRANSFORMS[dialect](source, clientDirFor(dialect)));
+    return variantPath;
+}
+// npx is safe here (unlike packages/velora-dev/src/sandbox.ts, which uses
+// `pnpm --filter @velora-cms/server exec prisma` instead): cwd is already
+// apps/server, where prisma is a direct dependency (a runtime dependency,
+// not a devDependency — the built server loads @prisma/client at runtime),
+// so there's no repo-root walk-up for npx to trigger an unwanted auto-install.
+// Was spawnSync + stdio: "inherit". A vitest worker's beforeAll chains four
+// of these calls back-to-back with no await between them (one per dialect
+// plus the default client); spawnSync blocks the whole event loop for each
+// call's full wall-clock duration, so the beforeAll became one unbroken
+// ~45-60s synchronous stretch — long enough to blow past vitest's
+// "onTaskUpdate" RPC timeout and crash the worker with exit 1 even though
+// every test passed. execFile (promisified) does the same work without
+// blocking the loop: shell: true preserves the exact command-line quoting
+// spawnSync relied on (the schema path still needs its own quotes because
+// the shell, not execFile, is what re-parses the assembled command line),
+// npx still resolves the same devDependency the same way, and the same
+// "(exit N)" error text is thrown on failure. Losing stdio: "inherit"'s
+// live streaming is deliberate: execFile has no stdio passthrough option
+// (it always captures stdout/stderr to build its callback result), so
+// output is written out in one shot after the process exits instead of
+// line-by-line — captured, not silenced.
+async function runPrismaGenerate(schemaPath, databaseUrl, label) {
+    console.log(`[generate-prisma-clients] generating ${label}…`);
+    try {
+        const { stdout, stderr } = await execFileAsync("npx", ["prisma", "generate", "--schema", `"${schemaPath}"`], {
+            cwd: SERVER_DIR,
+            shell: true,
+            // execFile buffers output (spawnSync with stdio:"inherit" did not);
+            // the 1 MiB default KILLS the child when exceeded, so give prisma
+            // generous headroom — a verbose engine error must fail loudly, not
+            // as a misleading SIGTERM.
+            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(`generate-prisma-clients: prisma generate failed for ${label} (exit ${failed.code})`);
+    }
+}
+export async function generatePrismaClients(dialects = ALL_DIALECTS) {
+    for (const dialect of dialects) {
+        const variantPath = writeVariantSchema(dialect);
+        await runPrismaGenerate(variantPath, PLACEHOLDER_URLS[dialect], dialect);
+    }
+    await generateDefaultPrismaClient();
+}
+// The FOURTH generate, and the one that makes a fresh deploy target boot
+// without a manual step.
+//
+// db/load-prisma-client.ts's static `import { PrismaClient } from
+// "@prisma/client"` means that package must be generated even when
+// VELORA_PRISMA_CLIENT_DIR points at one of the three dialect variants
+// above and the default client is never constructed. Session 155's
+// out-of-monorepo deploy needed `prisma generate` by hand before first
+// boot for exactly this reason.
+//
+// Deliberately NOT output-pinned, though the month plan's wording said so:
+// pinning it somewhere other than Prisma's default location would leave
+// that static import unresolved, i.e. would not fix the thing this exists
+// to fix.
+export async function generateDefaultPrismaClient() {
+    await runPrismaGenerate(SCHEMA_PATH, PLACEHOLDER_URLS.postgresql, "the default client");
+}
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    // void-with-catch instead of a top-level await: TLA would make every
+    // importer of this module async for the sake of a CLI-only guard. The
+    // exit code on failure stays non-zero.
+    void generatePrismaClients().catch((error) => {
+        console.error(error);
+        process.exitCode = 1;
+    });
+}

package/dist/scripts/pack-bundled-templates.d.ts

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