@plakboek/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florian Vanthuyne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,222 @@
-# Temporary Holding Version
+# @plakboek/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The host integration package for a Plakboek site. A scaffolded host app
+composes this package into its own React Router 8 application: `cmsRoutes()`
+supplies the CMS's routes, the `plakboek()` Vite plugin connects the package's
+route modules to the host's configuration and site module, and `createServer()`
+is the production server that serves a published page from Postgres next to the
+host's own routes.
+
+You normally do not install this by hand: `npx create-plakboek` writes a host
+that already depends on it.
+
+## Install
+
+```sh
+pnpm add @plakboek/core react react-dom react-router
+```
+
+`react`, `react-dom` and `react-router` are peer dependencies. A host that
+builds with React Router also has `@react-router/dev` and `vite`; they are
+optional peers because only the build-time subpaths import them. Node 22.22 or
+later is required.
+
+## Status
+
+Pre-alpha: the API settles over phase 6. The package root (`defineBlock` and the
+host-facing types) is safe to import from a client bundle; everything
+server-side lives behind the `./config`, `./routes`, `./vite` and `./server`
+subpaths.
+
+## What a host provides
+
+A host is four small files plus its own blocks and site chrome.
+
+`app/routes.ts` lists the host's own routes first and spreads the CMS routes
+after them, so a host route wins every tie, including an index route at `/`:
+
+```ts
+import { cmsRoutes } from '@plakboek/core/routes';
+import type { RouteConfig, RouteConfigEntry } from '@react-router/dev/routes';
+
+const hostRoutes: RouteConfigEntry[] = [];
+
+export default [...hostRoutes, ...cmsRoutes()] satisfies RouteConfig;
+```
+
+`vite.config.ts` adds the plugin next to React Router's:
+
+```ts
+import { plakboek } from '@plakboek/core/vite';
+import { reactRouter } from '@react-router/dev/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    plakboek({
+      config: './plakboek.config.ts',
+      site: './app/site/index.ts',
+    }),
+    reactRouter(),
+  ],
+});
+```
+
+`server.ts` is the production entry point:
+
+```ts
+import { createServer } from '@plakboek/core/server';
+
+await createServer().start();
+```
+
+`plakboek.config.ts` default-exports the result of `defineConfig` from
+`@plakboek/core/config`: the site name, locales, default locale, timezone,
+blocks, menus, modules, roles and an optional seed page. Everything structural
+is declared in this file and checked when it is evaluated, so a bad
+configuration fails the process at start. A block file imports `defineBlock`
+from the package root, which stays safe for a client bundle.
+
+The site module (`app/site/index.ts` in the starter) exports `renderDocument`
+and, optionally, `renderNotFound` and `renderError`; each receives a site
+context with the site name, locale, current path and `getMenu(name)`.
+
+## Environment
+
+The runtime reads and validates these variables once, collects every problem
+and fails with all of them listed, never printing a value. In development the
+plugin loads `.env` from the project root; variables already set in the
+process win over the file.
+
+| Variable                               | Required | Meaning                                                                                                                                                          |
+| -------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`                         | yes      | Postgres connection string (`postgres://` or `postgresql://`).                                                                                                   |
+| `DATABASE_MIGRATION_URL`               | no       | A direct (session) connection used only by `plakboek migrate`; falls back to `DATABASE_URL`. Migrations need it when `DATABASE_URL` is a pooler.                 |
+| `PLAKBOEK_URL`                         | yes      | The installation's public origin, such as `https://www.example.org`. No path, query or fragment. Never derived from a request.                                   |
+| `PLAKBOEK_SECRET`                      | yes      | At least 32 characters, no fallback in any environment. Generate one with `node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"`. |
+| `PLAKBOEK_BUILD_ID`                    | no       | Identifies the deployed render code, such as a commit hash. Letters, digits, `.`, `_` and `-`, up to 128 characters.                                             |
+| `PLAKBOEK_SMTP_HOST`                   | no       | The SMTP server. The rest of the SMTP group is read only when this is set.                                                                                       |
+| `PLAKBOEK_SMTP_PORT`                   | no       | SMTP port, 1 to 65535.                                                                                                                                           |
+| `PLAKBOEK_SMTP_SECURE`                 | no       | `true` for implicit TLS (port 465), `false` otherwise.                                                                                                           |
+| `PLAKBOEK_SMTP_USER`                   | no       | SMTP user; must be set together with `PLAKBOEK_SMTP_PASS`.                                                                                                       |
+| `PLAKBOEK_SMTP_PASS`                   | no       | SMTP password; must be set together with `PLAKBOEK_SMTP_USER`.                                                                                                   |
+| `PLAKBOEK_MAIL_FROM`                   | no       | The sender address for outgoing mail, such as `no-reply@example.org`.                                                                                            |
+| `PLAKBOEK_MIGRATION_LOCK_WAIT_SECONDS` | no       | How long `plakboek migrate` waits for another migrator (default 120).                                                                                            |
+| `PLAKBOEK_BOOTSTRAP_PASSWORD`          | no       | The password `plakboek bootstrap` uses when it is not given on stdin or at a prompt.                                                                             |
+| `PORT`                                 | no       | The production server's port (default 3000).                                                                                                                     |
+| `HOST`                                 | no       | The production server's bind address (default `0.0.0.0`).                                                                                                        |
+
+## Routes and reserved paths
+
+`cmsRoutes()` returns these routes, in this order, each pointing at a built
+route module inside this package:
+
+| Path                    | Purpose                                            |
+| ----------------------- | -------------------------------------------------- |
+| `/cms/health`           | Liveness and database probe (`200` or `503`).      |
+| `/cms/setup`            | First-run setup of the first superadmin.           |
+| `/cms/setup/test-email` | Sends a test email from the setup page.            |
+| `/api/auth/*`           | The authentication API.                            |
+| `/` and `/*`            | The visitor route: published pages, from Postgres. |
+
+`/cms/*` and `/api/auth/*` are reserved for the CMS. A page whose first slug
+segment is `cms` or `api` is shadowed and unreachable. A host's own routes win
+over every CMS route when they come first in `app/routes.ts`.
+
+The health body is a fixed `{"status":"ok"}` or `{"status":"unavailable"}`;
+a database error never reaches the response.
+
+The visitor route reads only the published snapshot of a page and renders it on
+the server, with no client React. In production one in-process LRU cache per
+app container holds rendered pages, and a publish purges the page right after
+its transaction commits. Every other `NODE_ENV` runs uncached, so the next
+request re-evaluates the host configuration.
+
+The plugin's `edit` option names a module exporting `edit`, the editor's
+entrypoint. A request carrying `_edit` is handed to it; without the option such
+a request is bounced to the plain page.
+
+## The `plakboek` command
+
+The package ships a `plakboek` bin. Each command loads `.env` from the current
+directory first. Exit codes: `0` success, `1` failure, `2` bad usage.
+
+| Command                        | What it does                                                                                                                              |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `plakboek migrate`             | Applies the core database migrations under an advisory lock, so two deploys cannot double-apply. `--lock-wait <seconds>` bounds the wait. |
+| `plakboek bootstrap`           | Creates the first superadmin and publishes the seed home page; only on an installation with no users. The password is never a flag.       |
+| `plakboek mail:test <address>` | Sends one test email through the real mail transport to check delivery. Needs no database, secret or host configuration.                  |
+
+`plakboek --version` prints the installed version and `plakboek --help` lists
+the commands.
+
+`plakboek migrate` applies only the core package's migrations. A host that adds
+its own Drizzle schema keeps a separate migration history and runs it with its
+own tooling.
+
+## Public API
+
+Each entry point below is pinned by a test: a name added to or removed from an
+entry, or from its table here, fails the build.
+
+### Root entry: `@plakboek/core`
+
+Safe to import from any bundle, including the editor and every block module.
+
+| Name                  | Kind     | Purpose                                                                  |
+| --------------------- | -------- | ------------------------------------------------------------------------ |
+| `defineBlock`         | function | Declares one block; an identity with type inference.                     |
+| `defineModule`        | function | Declares a named bundle of blocks, field types, widgets and constraints. |
+| `HostBlockDefinition` | type     | A block definition with its render component.                            |
+| `HostModule`          | type     | What the virtual host module resolves to.                                |
+| `MenuDefinitions`     | type     | Menus by name, declared in code.                                         |
+| `MenuItem`            | type     | One menu item: a label and an `href`.                                    |
+| `MenuLabel`           | type     | A label: one string, or a record keyed by locale.                        |
+| `ModuleDefinition`    | type     | A module's contributions.                                                |
+| `PlakboekConfig`      | type     | The frozen, validated configuration `defineConfig` returns.              |
+| `PlakboekConfigInput` | type     | What `defineConfig` accepts.                                             |
+| `ResolvedMenuItem`    | type     | A menu item resolved for one locale and the current path.                |
+| `SeedBlock`           | type     | One block of the seed page.                                              |
+| `SeedPage`            | type     | The page a fresh installation is seeded with.                            |
+| `SiteContext`         | type     | What a site module receives alongside the page it composes.              |
+| `SiteModule`          | type     | The host's site chrome: the document around every page.                  |
+
+### Config entry: `@plakboek/core/config`
+
+Server side only.
+
+| Name                      | Kind     | Purpose                                                            |
+| ------------------------- | -------- | ------------------------------------------------------------------ |
+| `defineConfig`            | function | Validates the host configuration and returns it frozen.            |
+| `PlakboekConfigError`     | class    | Thrown with every problem found, collected first.                  |
+| `defaultRoles`            | constant | The role-to-permission mapping used when a host declares no roles. |
+| `PlakboekConfigIssue`     | type     | One problem: a code and a message.                                 |
+| `PlakboekConfigIssueCode` | type     | The closed set of problem codes.                                   |
+
+### Routes entry: `@plakboek/core/routes`
+
+| Name        | Kind     | Purpose                                                       |
+| ----------- | -------- | ------------------------------------------------------------- |
+| `cmsRoutes` | function | The CMS's route table, to spread after the host's own routes. |
+
+### Vite entry: `@plakboek/core/vite`
+
+| Name                    | Kind     | Purpose                                                                 |
+| ----------------------- | -------- | ----------------------------------------------------------------------- |
+| `plakboek`              | function | The Vite plugin that wires the host configuration to the route modules. |
+| `PlakboekPluginOptions` | type     | The plugin's options: `config`, `site` and an optional `edit`.          |
+
+### Server entry: `@plakboek/core/server`
+
+| Name                  | Kind     | Purpose                                                              |
+| --------------------- | -------- | -------------------------------------------------------------------- |
+| `createServer`        | function | The production server: static assets, then the React Router handler. |
+| `CreateServerOptions` | type     | Build paths, port, host and shutdown bound.                          |
+| `PlakboekServer`      | type     | The Hono `app` and `start()`.                                        |
+| `RunningServer`       | type     | A started server's port, host and `close()`.                         |
+
+### Internal: `./route-modules/*`
+
+The `./route-modules/*` subpath exists only so `cmsRoutes()` can point React
+Router at the built route modules. It is internal: not part of the public API,
+not covered by any compatibility promise, and subject to change in any release.

package/dist/body-limit-DViLUMvl.js

@@ -0,0 +1,86 @@
+//#region src/setup/body-limit.ts
+/**
+* The size cap on the first-run POST endpoints (T-06-86). Both are reachable
+* without authentication, so an unbounded body would let any client exhaust
+* the app's memory. This module imports nothing from Hono: the route-module
+* chunks use it too.
+*/
+/**
+* 16 KiB. A real setup submission is four short urlencoded text fields (a
+* name of at most 200 code points, an email of at most 320 characters and two
+* passwords), which stays under about 8 KiB even with every character
+* percent-encoded. The test-email body is one token of about 200 bytes.
+*/
+const SETUP_BODY_LIMIT_BYTES = 16384;
+/**
+* Whether a request path belongs to the setup endpoints. Case-insensitive on
+* purpose: React Router matches routes case-insensitively, so a case-sensitive
+* guard could be bypassed with `/CMS/Setup`.
+*/
+function isSetupPath(pathname) {
+	const path = pathname.toLowerCase();
+	return path === "/cms/setup" || path.startsWith("/cms/setup/");
+}
+/**
+* The 413 for a body over the cap: fixed text, uncacheable, unindexable and
+* nothing taken from the request. No `Connection: close`: closing a socket
+* that still holds unread request bytes can reset it before the client reads
+* the answer.
+*/
+function payloadTooLarge() {
+	return new Response("Payload Too Large", {
+		status: 413,
+		headers: {
+			"Content-Type": "text/plain; charset=utf-8",
+			"Cache-Control": "no-store",
+			"X-Robots-Tag": "noindex, nofollow"
+		}
+	});
+}
+/**
+* Reads a request body of at most `maxBytes`, in every runtime. A declared
+* Content-Length over the cap, or one that is not a plain integer, is refused
+* without touching the body. It is never trusted as an upper bound, though:
+* the bytes are counted as they arrive and the stream is cancelled the moment
+* the count passes the cap, so a header that understates the body gains
+* nothing.
+*/
+async function readBodyWithinLimit(request, maxBytes) {
+	const declared = request.headers.get("content-length")?.trim();
+	if (declared !== void 0) {
+		if (!/^\d+$/.test(declared) || Number(declared) > maxBytes) return { kind: "too-large" };
+	}
+	if (request.body === null) return {
+		kind: "bytes",
+		bytes: /* @__PURE__ */ new Uint8Array(0)
+	};
+	const reader = request.body.getReader();
+	const chunks = [];
+	let total = 0;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			total += value.byteLength;
+			if (total > maxBytes) {
+				await reader.cancel().catch(() => void 0);
+				return { kind: "too-large" };
+			}
+			chunks.push(value);
+		}
+	} catch {
+		return { kind: "unreadable" };
+	}
+	const bytes = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return {
+		kind: "bytes",
+		bytes
+	};
+}
+//#endregion
+export { readBodyWithinLimit as i, isSetupPath as n, payloadTooLarge as r, SETUP_BODY_LIMIT_BYTES as t };

package/dist/bootstrap-BUV7ahx4.js

@@ -0,0 +1,198 @@
+import { r as readRuntimeEnv, t as PlakboekEnvError } from "./env-DEELGUpc.js";
+import { t as closeAllDbs } from "./db-D5ByUm9I.js";
+import { a as parseFlags, c as printLine, i as oneLine, n as connectionSecrets, o as printError, r as messageOf, t as UsageError } from "./output-Co4mJhFM.js";
+import { t as createRuntime } from "./runtime-DDseFOVL.js";
+import { a as validateBootstrapInput, i as bootstrapInstallation, n as DatabaseNotReadyError, r as InstallationNotEmptyError, t as BootstrapValidationError } from "./bootstrap-DplDxN7W.js";
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { PASSWORD_MIN_LENGTH } from "@plakboek/auth";
+import { Writable } from "node:stream";
+import { createInterface } from "node:readline";
+import { register } from "tsx/esm/api";
+//#region src/cli/load-config.ts
+/**
+* Loads the host's `plakboek.config.ts` into the CLI process.
+*
+* tsx's global `register()` hook teaches this process's own module loader to
+* run TypeScript, and a plain dynamic import then evaluates the file. The
+* config's `defineConfig` therefore fills the very block registry (held in
+* `@plakboek/pages`) that `insertBlock` reads later in this process. tsx's
+* isolated per-call import helper is deliberately not used: it gives the
+* config its own module instances, which would leave the CLI's registry empty.
+*/
+/** The config file is missing or is not a Plakboek config. The message is
+* the exact copy shown to the operator. */
+var HostConfigError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "HostConfigError";
+	}
+};
+function looksLikeConfig(value) {
+	return typeof value === "object" && value !== null && typeof Reflect.get(value, "siteName") === "string" && typeof Reflect.get(value, "pages") === "object" && Reflect.get(value, "pages") !== null;
+}
+async function loadHostConfig(path) {
+	const absolute = resolve(path);
+	if (!existsSync(absolute)) throw new HostConfigError(`Could not find ${path}. Run this command from the project root or pass --config <path>.`);
+	const unregister = register();
+	let loaded;
+	try {
+		loaded = await import(pathToFileURL(absolute).href);
+	} finally {
+		await unregister();
+	}
+	const config = typeof loaded === "object" && loaded !== null ? Reflect.get(loaded, "default") : void 0;
+	if (!looksLikeConfig(config)) throw new HostConfigError(`${path} must default-export defineConfig({...}).`);
+	return config;
+}
+//#endregion
+//#region src/cli/bootstrap.ts
+/**
+* `plakboek bootstrap`: the headless first-superadmin surface (D-08). It calls
+* the same `bootstrapInstallation` as the setup page, so the first user and
+* the seeded home page are created identically from the terminal. It is the
+* operator's way around the open web setup window (D-09).
+*
+* The password is never a flag value (it would land in shell history and
+* process lists): it comes from stdin with `--password-stdin`, from
+* `PLAKBOEK_BOOTSTRAP_PASSWORD`, or from a hidden prompt on a TTY.
+*/
+const BOOTSTRAP_HELP = `Usage: plakboek bootstrap [--name <name>] [--email <address>] [--password-stdin]
+                          [--config <path>]
+
+Creates the first superadmin and publishes the seed home page. Only runs on an
+installation with no users. Run plakboek migrate first.
+
+The password is never a flag. Provide it on stdin with --password-stdin, in
+PLAKBOEK_BOOTSTRAP_PASSWORD, or at the hidden prompt in a terminal.
+
+Options:
+  --name <name>        The superadmin's name
+  --email <address>    The superadmin's email address
+  --password-stdin     Read the password from stdin
+  --config <path>      The host config (default ./plakboek.config.ts)
+  -h, --help           Show this help`;
+const NON_INTERACTIVE = "when input is not interactive";
+/** Asks one question on the terminal; `hidden` suppresses the echo. */
+function ask(question, hidden) {
+	return new Promise((resolve, reject) => {
+		const sink = new Writable({ write(_chunk, _encoding, done) {
+			done();
+		} });
+		process.stdout.write(`${question}: `);
+		const lines = createInterface({
+			input: process.stdin,
+			output: hidden ? sink : process.stdout,
+			terminal: true
+		});
+		let answered = false;
+		lines.question("", (answer) => {
+			answered = true;
+			lines.close();
+			if (hidden) process.stdout.write("\n");
+			resolve(answer);
+		});
+		lines.on("close", () => {
+			if (!answered) reject(new UsageError("Input was cancelled."));
+		});
+	});
+}
+async function readStdin() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+	return Buffer.concat(chunks).toString("utf8");
+}
+/** Exactly one trailing newline (LF or CRLF) is not part of the password. */
+function stripTrailingNewline(value) {
+	return value.replace(/\r?\n$/, "");
+}
+async function resolvePassword(fromStdin, env, interactive) {
+	if (fromStdin) return stripTrailingNewline(await readStdin());
+	const fromEnv = env.PLAKBOEK_BOOTSTRAP_PASSWORD;
+	if (fromEnv !== void 0 && fromEnv.length > 0) return fromEnv;
+	if (!interactive) throw new UsageError(`--password-stdin or PLAKBOEK_BOOTSTRAP_PASSWORD is required ${NON_INTERACTIVE}.`);
+	const password = await ask("Password", true);
+	if (password !== await ask("Confirm password", true)) throw new UsageError("The two passwords do not match.");
+	return password;
+}
+/** The copy for one field problem; the password rule has its own wording. */
+function issueCopy(issue) {
+	return issue.field === "password" ? `The password must be at least ${String(PASSWORD_MIN_LENGTH)} characters.` : issue.message;
+}
+function reportIssues(issues) {
+	for (const issue of issues) printError(issueCopy(issue));
+	return 2;
+}
+async function runBootstrapCommand(argv, env = process.env) {
+	const { values } = parseFlags(argv, {
+		name: { type: "string" },
+		email: { type: "string" },
+		"password-stdin": { type: "boolean" },
+		config: { type: "string" },
+		help: {
+			type: "boolean",
+			short: "h"
+		}
+	});
+	if (values.help === true) {
+		printLine(BOOTSTRAP_HELP);
+		return 0;
+	}
+	const interactive = process.stdin.isTTY === true;
+	let name = values.name;
+	if (name === void 0) {
+		if (!interactive) throw new UsageError(`--name is required ${NON_INTERACTIVE}.`);
+		name = await ask("Name", false);
+	}
+	let email = values.email;
+	if (email === void 0) {
+		if (!interactive) throw new UsageError(`--email is required ${NON_INTERACTIVE}.`);
+		email = await ask("Email address", false);
+	}
+	const password = await resolvePassword(values["password-stdin"] === true, env, interactive);
+	const issues = validateBootstrapInput({
+		name,
+		email,
+		password
+	});
+	if (issues.length > 0) return reportIssues(issues);
+	let runtimeEnv;
+	try {
+		runtimeEnv = readRuntimeEnv(env);
+	} catch (error) {
+		if (error instanceof PlakboekEnvError) {
+			for (const issue of error.issues) printError(issue.message);
+			return 1;
+		}
+		throw error;
+	}
+	const secrets = [
+		password,
+		...connectionSecrets(runtimeEnv.databaseUrl),
+		...runtimeEnv.smtp?.pass === void 0 ? [] : [runtimeEnv.smtp.pass]
+	];
+	try {
+		const config = await loadHostConfig(values.config ?? "./plakboek.config.ts");
+		const runtime = createRuntime({ config }, runtimeEnv);
+		const result = await bootstrapInstallation(runtime, {
+			name,
+			email,
+			password
+		});
+		printLine(`Created superadmin ${result.email}.`);
+		if (result.homePublished) printLine(`Published the home page at ${result.homePath}.`);
+		return 0;
+	} catch (error) {
+		if (error instanceof BootstrapValidationError) return reportIssues(error.issues);
+		if (error instanceof InstallationNotEmptyError) printError(error.message);
+		else if (error instanceof DatabaseNotReadyError) printError("The database is not ready. Run plakboek migrate first.");
+		else if (error instanceof HostConfigError) printError(error.message);
+		else printError(oneLine(messageOf(error), secrets));
+		return 1;
+	} finally {
+		await closeAllDbs();
+	}
+}
+//#endregion
+export { runBootstrapCommand };