@plitzi/sdk-server 0.38.6 → 0.38.8

package/dist/modules/project/plugins.js

@@ -0,0 +1,162 @@
+import { loadFunctions, loadFunctionsSource } from "../functions/load.js";
+import { PLUGIN_FUNCTIONS_SOURCE } from "@plitzi/sdk-shared/actions";
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
+import path from "node:path";
+import { existsSync, readFileSync, readdirSync, watch } from "node:fs";
+import { checkPluginFolder, layoutFindingText, pluginEntry, pluginTypeOf, readVendorPlugin } from "@plitzi/sdk-shared/project/layout";
+import { PLUGINS_DIR, PLUGIN_FUNCTIONS_DIR, VENDOR_PLUGINS_DIR } from "@plitzi/sdk-shared/project/paths";
+//#region src/modules/project/plugins.ts
+/**
+* `action: 'compile'` is what makes a folder's plugin SERVER-rendered: the server builds the entry with esbuild, keeps
+* React external so the plugin runs on the one copy the page already has, serves the bundle to the browser AND
+* imports it into the render — so the component's markup is in the HTML before any JavaScript arrives.
+*/
+var folderSource = (entry) => ({
+	js: entry,
+	action: "compile",
+	version: "1.0.0"
+});
+var foldersOf = (dir) => existsSync(dir) ? readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort() : [];
+/** Every folder of `src/plugins` the server can build, by the plugin it is: what it registers. */
+var pluginFolders = (root) => {
+	const found = /* @__PURE__ */ new Map();
+	for (const folder of foldersOf(path.join(root, PLUGINS_DIR))) {
+		const entry = pluginEntry(root, folder);
+		if (entry && !found.has(pluginTypeOf(folder))) found.set(pluginTypeOf(folder), {
+			folder,
+			entry
+		});
+	}
+	return found;
+};
+/**
+* A plugin's server half: its `functions/` folder (`src/plugins/Board/functions/index.ts`), written like the project's
+* own `src/functions/` and loaded with what a plugin may reach — its own corner of `kv`, its routes under
+* `/fn/plugins/<name>/`, its tasks named `<name>.<action>`. A folder without one is a component and nothing else; one
+* with code and no `index.ts` is the layout check's to say (`plugin-functions-entry-missing`).
+*/
+var folderFunctions = async (root, folder) => {
+	const functions = path.join(root, PLUGINS_DIR, folder, PLUGIN_FUNCTIONS_DIR);
+	return existsSync(path.join(functions, "index.ts")) ? (await loadFunctions(functions)).at(0) : void 0;
+};
+/** A plugin of `vendor/plugins`, from the manifest `plitzi plugin pack` wrote beside its bundle when it was published. */
+var builtPlugin = (root, type) => {
+	const read = readVendorPlugin(root, type);
+	if ("problem" in read) throw new Error(read.problem.message);
+	return {
+		type,
+		source: {
+			js: read.script,
+			...read.style ? { css: read.style } : {},
+			action: "copy",
+			version: read.version
+		},
+		...read.functions ? { functions: read.functions } : {}
+	};
+};
+/** The files of a packed plugin's server half (`functions.source.json`), by their path. */
+var carriedSource = (file) => {
+	const carried = JSON.parse(readFileSync(file, "utf-8"));
+	const files = isRecord(carried) ? Object.entries(carried).flatMap(([name, text]) => typeof text === "string" ? [[name, text]] : []) : [];
+	if (!isRecord(carried) || files.length !== Object.keys(carried).length) throw new Error(`${file} is not a plugin's server half: ${PLUGIN_FUNCTIONS_SOURCE} maps each file's path to its text.`);
+	return Object.fromEntries(files);
+};
+/** Every plugin of the project at `root`, as its server registers them at boot. */
+var projectPlugins = async (root) => {
+	const folders = pluginFolders(root);
+	const sources = Object.fromEntries([...folders].map(([name, { entry }]) => [name, folderSource(entry)]));
+	const functions = {};
+	for (const [name, { folder }] of folders) {
+		const definition = await folderFunctions(root, folder);
+		if (definition) functions[name] = definition;
+	}
+	const built = foldersOf(path.join(root, VENDOR_PLUGINS_DIR)).map((type) => builtPlugin(root, type));
+	for (const { type, source, functions: carried } of built) {
+		sources[type] = source;
+		if (carried) {
+			const definition = (await loadFunctionsSource(carriedSource(carried))).at(0);
+			if (definition) functions[type] = definition;
+		}
+	}
+	return {
+		sources,
+		names: Object.keys(sources),
+		functions,
+		fromFolders: new Set(folders.keys())
+	};
+};
+/**
+* A plugin edited while developing is built again by the server, and the open pages swap it where it is drawn — the
+* rest of the page, its state included, stays as it was (`devReload`). Its server half (`functions/`) is loaded again
+* here, in place. A plugin ADDED — a new folder with an `index.ts`, what `plitzi plugin add` writes — is registered
+* here, and the pages load again to render it; one removed is turned off. A folder the server cannot build, or whose
+* server half has no entry, is said in the terminal as the layout check says it at boot — once, until it changes — and
+* the server goes on. Answers what stops watching.
+*/
+var watchProjectPlugins = (root, server, plugins) => {
+	const dir = path.join(root, PLUGINS_DIR);
+	if (!existsSync(dir)) return () => void 0;
+	const { names, fromFolders } = plugins;
+	let timer;
+	const reloading = /* @__PURE__ */ new Map();
+	/** What was said of each folder last — at boot, by the layout check — so a save says only what changed. */
+	const said = new Map(foldersOf(dir).map((folder) => [folder, checkPluginFolder(root, folder).map(layoutFindingText).join("\n")]));
+	const sayOf = (folder) => {
+		const findings = checkPluginFolder(root, folder);
+		const text = findings.map(layoutFindingText).join("\n");
+		if (text === (said.get(folder) ?? "")) return;
+		said.set(folder, text);
+		for (const finding of findings) {
+			const line = `[plugins] ${layoutFindingText(finding)}`;
+			if (finding.level === "error") console.error(line);
+			else console.warn(line);
+		}
+	};
+	const reloadFunctions = (folder) => {
+		const name = pluginTypeOf(folder);
+		sayOf(folder);
+		folderFunctions(root, folder).then((definition) => {
+			server.functions.setPlugin(name, definition);
+			if (definition) console.log(`[plugins] ${name}: its functions, loaded again`);
+		}).catch((error) => {
+			console.error(`[plugins] ${name}: its functions were not loaded again:`, error instanceof Error ? error.message : error);
+		});
+	};
+	const sync = () => {
+		const folders = foldersOf(dir);
+		folders.forEach(sayOf);
+		for (const folder of [...said.keys()].filter((each) => !folders.includes(each))) said.delete(folder);
+		const present = pluginFolders(root);
+		const added = [...present].filter(([name]) => !fromFolders.has(name));
+		const removed = [...fromFolders].filter((name) => !present.has(name));
+		for (const [name, { folder, entry }] of added) {
+			server.plugins.register(name, folderSource(entry));
+			fromFolders.add(name);
+			names.push(name);
+			reloadFunctions(folder);
+		}
+		for (const name of removed) {
+			fromFolders.delete(name);
+			names.splice(names.indexOf(name), 1);
+			server.functions.setPlugin(name, void 0);
+		}
+		if (added.length > 0 || removed.length > 0) server.reloadPages();
+	};
+	const watcher = watch(dir, { recursive: true }, (_event, file) => {
+		const [folder, part] = (file ?? "").split(path.sep);
+		if (folder && part === PLUGIN_FUNCTIONS_DIR && fromFolders.has(pluginTypeOf(folder))) {
+			clearTimeout(reloading.get(folder));
+			reloading.set(folder, setTimeout(() => reloadFunctions(folder), 200));
+			return;
+		}
+		clearTimeout(timer);
+		timer = setTimeout(sync, 300);
+	});
+	return () => {
+		clearTimeout(timer);
+		reloading.forEach(clearTimeout);
+		watcher.close();
+	};
+};
+//#endregion
+export { projectPlugins, watchProjectPlugins };

package/dist/modules/project/serveProject.d.ts

@@ -0,0 +1,78 @@
+import { AuthoredDocuments } from './watchSpace';
+import { ServerConfig } from '../../core/createServer';
+import { ConnectorManifest } from '../connectors';
+import { ActionEntry, SSRServer } from '@plitzi/sdk-shared';
+/** What `serveProject` sets itself, from the project's layout — so never the project's options'. */
+type SetByProject = 'port' | 'devMode' | 'devReload' | 'health' | 'adapters' | 'plugins' | 'publicDir' | 'dataDir' | 'functions' | 'action';
+/**
+ * What a project's server does besides serving its space — its `src/config/serverOptions.ts`: what `createServer`
+ * takes, but for what `serveProject` wires from the project's layout, and an action's `lookups`, which are the
+ * project's `src/actions/`. `logLevel` and `logger` are the project's to change; `action.kv` too.
+ */
+export type ProjectServerOptions = Partial<Omit<ServerConfig, SetByProject>> & {
+    action?: Omit<NonNullable<ServerConfig['action']>, 'lookups'>;
+};
+/** A space authored in the project — `authorProjectSpace` of `@plitzi/sdk-authoring/node` — and what it warned of. */
+export type ProjectSpace = AuthoredDocuments & {
+    warnings?: readonly {
+        message: string;
+    }[];
+};
+type ServeProjectBase = {
+    /** The space's server actions (`src/actions/`), found by their id. Left out, the server runs none. */
+    actions?: readonly ActionEntry[];
+    /** The connectors those actions call, by id. */
+    connectors?: ReadonlyMap<string, ConnectorManifest>;
+    /** `src/config/serverOptions.ts`: spread before what `serveProject` wires, which wins where both say something. */
+    serverOptions?: ProjectServerOptions;
+};
+export type ServeProjectOptions = ServeProjectBase & ({
+    /**
+     * The space, held in the project: authored once its layout is checked — `authorProjectSpace` of
+     * `@plitzi/sdk-authoring/node` — served from memory, and, while developing, authored again on a save.
+     */
+    space: () => ProjectSpace | Promise<ProjectSpace>;
+    cloud?: never;
+} | {
+    /**
+     * The space stays in Plitzi, read with `PLITZI_HOST_KEY` (and `PLITZI_ENVIRONMENT`, `PLITZI_REVISION`,
+     * `PLITZI_SERVER_URL`): `name` is what `/health` answers with — no space document says it here.
+     */
+    cloud: {
+        name: string;
+    };
+    space?: never;
+});
+/** The project's server, running. */
+export type ServedProject = {
+    server: SSRServer;
+    /** Where it listens, as `tmp/dev-server.json` records it: `http://127.0.0.1:<port>`. */
+    url: string;
+    /** Stops watching, closes the server and the runtime — what a signal does, for a caller that stops it itself. */
+    close: () => Promise<void>;
+};
+/**
+ * The server of a project `@plitzi/cli` writes — its `src/main.ts` hands it the space, its actions and its options,
+ * and everything else comes from where the project keeps it. The project is the working directory, where its scripts
+ * start it (`projectRoot`: refused, saying what is missing, anywhere else), laid out where the server reads each part
+ * (`assertProjectLayout`: refused with every error at once; its warnings said while developing), and only then is its
+ * space authored. A refusal of any of the three is printed as it is — the message is the whole report, every problem
+ * and its fix, and a stack would only point inside the SDK — and the process exits with 1. What it serves:
+ *
+ * - the port: `PORT`, or 8080 — the next free one from there while developing; `HOST`, loopback by default;
+ * - its plugins: every folder of `src/plugins` built from its source and server-rendered, every one of `vendor/plugins`
+ *   as it was built, each with its server half;
+ * - its code: `src/functions/`, and the space's runtime (`src/runtime/` — compiled under `dist/` when the server runs
+ *   compiled, `projectModule` — or `vendor/runtime.bundle`) in this process;
+ * - `public/` served as it is, `src/data/` read and never served, `kv` kept in `state/kv.json`;
+ * - `/health` answering with the space's permanent URL (or the cloud project's name), and the port it took written to
+ *   `tmp/dev-server.json` for `check`, `shot` and `visual` to find;
+ * - a signal closes it, finishing what runs.
+ *
+ * While developing (`NODE_ENV` other than `production`), a save to the space is authored again by the project's
+ * `plitzi/author.ts`, in a process of its own, which hands the documents back over IPC: the server swaps them in memory
+ * and every open page loads again. A plugin folder added is registered, one removed turned off, and a plugin's
+ * `functions/` loaded again; a folder it cannot build is said in the terminal, and the server goes on.
+ */
+export declare const serveProject: (options: ServeProjectOptions) => Promise<ServedProject>;
+export {};

package/dist/modules/project/serveProject.js

@@ -0,0 +1,200 @@
+import { consoleLogger } from "../../helpers/serverLog.js";
+import { isFleetWorker } from "../../core/server/fleet/role.js";
+import { loadFunctions } from "../functions/load.js";
+import { createServer } from "../../core/createServer.js";
+import { closeOnSignals } from "../../core/server/closeOnSignals.js";
+import { freePort } from "../../core/freePort.js";
+import { createCloudAdapters } from "../../adapters/cloudAdapters.js";
+import { createJsonAdapters } from "../../adapters/jsonAdapters.js";
+import { createFileKv } from "../actions/runtime/fileKv.js";
+import { loadRuntime, loadRuntimeModule } from "../runtime/bundle.js";
+import { serveRuntime } from "../runtime/stages.js";
+import { projectPlugins, watchProjectPlugins } from "./plugins.js";
+import { watchSpace } from "./watchSpace.js";
+import path from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { assertProjectLayout, layoutFindingText } from "@plitzi/sdk-shared/project/layout";
+import { DATA_DIR, DEV_SERVER_FILE, FUNCTIONS_DIR, KV_FILE, PROJECT_TMP, PUBLIC_DIR, RUNTIME_BUNDLE, RUNTIME_ENTRY } from "@plitzi/sdk-shared/project/paths";
+import { projectModule, projectRoot } from "@plitzi/sdk-shared/project/root";
+//#region src/modules/project/serveProject.ts
+/**
+* The errors whose message is the whole report — every problem, where it is and what to write instead — and whose
+* stack would only point inside the SDK: the project's root, its layout, a space module with no space, a space that does
+* not author. Told by name, since each package that throws one carries its own copy of the class.
+*/
+var REPORTS = /* @__PURE__ */ new Set([
+	"ProjectRootError",
+	"ProjectLayoutError",
+	"ProjectSpaceError",
+	"SpaceRefusedError"
+]);
+var isReport = (error) => error instanceof Error && REPORTS.has(error.name);
+var ENVIRONMENTS = [
+	"main",
+	"production",
+	"staging",
+	"development"
+];
+var isEnvironment = (value) => ENVIRONMENTS.some((environment) => environment === value);
+/** The one space a project's server serves, which is the one it runs the actions on a clock for. */
+var SPACE_ID = 1;
+/**
+* The space's HOST key — not the public one a published page embeds. They are different credentials on purpose: the
+* public `render` key is readable by anyone who views source, and what keeps a copied one from working is that a
+* browser states the origin it presents from. A server has no such statement to make, so it gets a key whose
+* protection is that it is secret: issued once, never committed, never shipped in a page, revocable on its own.
+*/
+var cloudAdapters = (pluginNames) => {
+	const webKey = process.env.PLITZI_HOST_KEY ?? "";
+	if (!webKey) throw new Error("Set PLITZI_HOST_KEY in .env — Credentials, in the builder.");
+	const environment = process.env.PLITZI_ENVIRONMENT ?? "main";
+	if (!isEnvironment(environment)) throw new Error(`PLITZI_ENVIRONMENT is "${environment}": one of ${ENVIRONMENTS.join(", ")}.`);
+	return createCloudAdapters({
+		webKey,
+		...process.env.PLITZI_SERVER_URL ? { serverUrl: process.env.PLITZI_SERVER_URL } : {},
+		environment,
+		...process.env.PLITZI_REVISION ? { revision: Number(process.env.PLITZI_REVISION) } : {},
+		deployment: { pluginNames }
+	});
+};
+var actionLookups = (actions, connectors) => ({
+	getAction: (_spaceId, actionId) => Promise.resolve(actions.find((entry) => entry.id === actionId)),
+	listActions: () => Promise.resolve([...actions]),
+	getConnector: (_spaceId, connectorId) => Promise.resolve(connectors.get(connectorId)),
+	listScheduledSpaces: () => Promise.resolve([SPACE_ID])
+});
+/** The space this project serves, authored from its own source — or Plitzi's, named for `/health`. */
+var spaceToServe = async ({ space, cloud }) => {
+	if (!space) return { name: cloud.name };
+	const authored = await space();
+	return {
+		space: authored,
+		name: authored.schema.definition.permanentUrl
+	};
+};
+var startProject = async (options) => {
+	const { actions, connectors = /* @__PURE__ */ new Map(), serverOptions = {} } = options;
+	const root = projectRoot();
+	const developing = process.env.NODE_ENV !== "production";
+	const layout = assertProjectLayout(root, {
+		mode: "server",
+		space: options.space ? "local" : "cloud"
+	});
+	if (developing) for (const warning of layout) console.warn(`[layout] ${layoutFindingText(warning)}`);
+	const host = process.env.HOST ?? "127.0.0.1";
+	const port = process.env.PORT ? Number(process.env.PORT) : developing ? await freePort(8080, host) : 8080;
+	/** Where people reach this server: `PUBLIC_URL` behind a proxy, its own address otherwise. */
+	const publicUrl = (process.env.PUBLIC_URL ?? `http://127.0.0.1:${String(port)}`).replace(/\/+$/, "");
+	const { space, name } = await spaceToServe(options);
+	const plugins = await projectPlugins(root);
+	const held = space && { documents: {
+		schema: space.schema,
+		style: space.style
+	} };
+	const speaks = !isFleetWorker();
+	for (const warning of speaks ? space?.warnings ?? [] : []) console.warn(`[author] ${warning.message}`);
+	const adapters = held ? createJsonAdapters({
+		offlineData: () => held.documents,
+		deployment: {
+			spaceId: SPACE_ID,
+			environment: "main",
+			revision: 0,
+			pluginNames: plugins.names
+		}
+	}) : cloudAdapters(plugins.names);
+	const functionsDir = path.join(root, FUNCTIONS_DIR);
+	const functions = existsSync(functionsDir) ? await loadFunctions(functionsDir) : [];
+	const runtimeBundle = path.join(root, RUNTIME_BUNDLE);
+	const spaceRuntime = await loadRuntimeModule(projectModule(root, RUNTIME_ENTRY, process.argv[1])) ?? (existsSync(runtimeBundle) ? await loadRuntime(readFileSync(runtimeBundle), path.join(root, PROJECT_TMP, "runtime")) : void 0);
+	const runtime = spaceRuntime && await serveRuntime(spaceRuntime, {
+		env: process.env,
+		publicUrl
+	});
+	const server = createServer({
+		logLevel: process.argv.includes("--verbose") ? "info" : "warn",
+		logger: consoleLogger,
+		...serverOptions,
+		port,
+		devMode: developing,
+		devReload: developing,
+		health: { name },
+		adapters,
+		plugins: plugins.sources,
+		publicDir: path.join(root, PUBLIC_DIR),
+		dataDir: path.join(root, DATA_DIR),
+		functions: {
+			native: [...functions, ...runtime?.native ?? []],
+			plugins: plugins.functions
+		},
+		action: {
+			signingSecret: process.env.PLITZI_SIGNING_SECRET,
+			kv: createFileKv({ file: path.join(root, KV_FILE) }),
+			...serverOptions.action,
+			...actions ? { lookups: actionLookups(actions, connectors) } : {}
+		}
+	}, { preAuth: runtime ? [runtime.stage] : [] });
+	server.listen(port, host);
+	const url = `http://127.0.0.1:${String(port)}`;
+	if (speaks) {
+		mkdirSync(path.join(root, PROJECT_TMP), { recursive: true });
+		writeFileSync(path.join(root, DEV_SERVER_FILE), `${JSON.stringify({
+			name,
+			port,
+			url
+		}, null, 2)}\n`);
+		console.log(`pages on ${url}/`);
+	}
+	const watching = developing ? [...held ? [watchSpace(root, (authored) => {
+		held.documents = authored;
+		server.reloadPages();
+	})] : [], watchProjectPlugins(root, server, plugins)] : [];
+	const close = async () => {
+		watching.forEach((stop) => stop());
+		await server.close();
+		await runtime?.close();
+	};
+	const stopListening = closeOnSignals({ close });
+	return {
+		server,
+		url,
+		close: async () => {
+			stopListening();
+			await close();
+		}
+	};
+};
+/**
+* The server of a project `@plitzi/cli` writes — its `src/main.ts` hands it the space, its actions and its options,
+* and everything else comes from where the project keeps it. The project is the working directory, where its scripts
+* start it (`projectRoot`: refused, saying what is missing, anywhere else), laid out where the server reads each part
+* (`assertProjectLayout`: refused with every error at once; its warnings said while developing), and only then is its
+* space authored. A refusal of any of the three is printed as it is — the message is the whole report, every problem
+* and its fix, and a stack would only point inside the SDK — and the process exits with 1. What it serves:
+*
+* - the port: `PORT`, or 8080 — the next free one from there while developing; `HOST`, loopback by default;
+* - its plugins: every folder of `src/plugins` built from its source and server-rendered, every one of `vendor/plugins`
+*   as it was built, each with its server half;
+* - its code: `src/functions/`, and the space's runtime (`src/runtime/` — compiled under `dist/` when the server runs
+*   compiled, `projectModule` — or `vendor/runtime.bundle`) in this process;
+* - `public/` served as it is, `src/data/` read and never served, `kv` kept in `state/kv.json`;
+* - `/health` answering with the space's permanent URL (or the cloud project's name), and the port it took written to
+*   `tmp/dev-server.json` for `check`, `shot` and `visual` to find;
+* - a signal closes it, finishing what runs.
+*
+* While developing (`NODE_ENV` other than `production`), a save to the space is authored again by the project's
+* `plitzi/author.ts`, in a process of its own, which hands the documents back over IPC: the server swaps them in memory
+* and every open page loads again. A plugin folder added is registered, one removed turned off, and a plugin's
+* `functions/` loaded again; a folder it cannot build is said in the terminal, and the server goes on.
+*/
+var serveProject = async (options) => {
+	try {
+		return await startProject(options);
+	} catch (error) {
+		if (!isReport(error)) throw error;
+		console.error(error.message);
+		process.exitCode = 1;
+		process.exit(1);
+	}
+};
+//#endregion
+export { serveProject };

package/dist/modules/project/serveProject.test.d.ts

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

package/dist/modules/project/watchSpace.d.ts

@@ -0,0 +1,14 @@
+import { Schema, Style } from '@plitzi/sdk-shared';
+/** The two documents a page server renders a space from, as the author script hands them over. */
+export type AuthoredDocuments = {
+    schema: Schema;
+    style: Style;
+};
+/**
+ * A save to the space, while developing: re-authored by the project's `plitzi/author.ts` in a process of its own — the
+ * only way to read every file of it again, which an import never does twice — and handed over IPC (`--ipc`), so
+ * `onAuthored` swaps the documents the server serves. What it refuses is printed by the script, and the page keeps
+ * the last space that authored. Saves in quick succession author once; one during a run, once more after it. Answers
+ * what stops watching.
+ */
+export declare const watchSpace: (root: string, onAuthored: (documents: AuthoredDocuments) => void) => (() => void);

package/dist/modules/project/watchSpace.js

@@ -0,0 +1,77 @@
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
+import path from "node:path";
+import { watch } from "node:fs";
+import { AUTHOR_FILE, SOURCE_DIR } from "@plitzi/sdk-shared/project/paths";
+import { spawn } from "node:child_process";
+//#region src/modules/project/watchSpace.ts
+/**
+* What the author script sent: its own `{ schema, style }`, which `authorSpace` built and checked — the message is
+* looked at only for its shape, so a stray one from a script that is not the CLI's is not served.
+*/
+var isAuthoredDocuments = (message) => isRecord(message) && isRecord(message.schema) && isRecord(message.style);
+/**
+* What of `src/` is the space's: everything but the server's own code — its entry point, the server options,
+* actions, connectors, functions and runtime — which `start:dev` restarts the server on instead; and of a plugin, only
+* its declaration — its component is swapped in the open pages by the server itself.
+*/
+var authored = (file) => file !== "main.ts" && !/^(config|actions|connectors|functions|runtime)([\\/]|$)/.test(file) && (!/^plugins([\\/]|$)/.test(file) || path.basename(file) === "declaration.ts");
+/**
+* A save to the space, while developing: re-authored by the project's `plitzi/author.ts` in a process of its own — the
+* only way to read every file of it again, which an import never does twice — and handed over IPC (`--ipc`), so
+* `onAuthored` swaps the documents the server serves. What it refuses is printed by the script, and the page keeps
+* the last space that authored. Saves in quick succession author once; one during a run, once more after it. Answers
+* what stops watching.
+*/
+var watchSpace = (root, onAuthored) => {
+	let timer;
+	let running;
+	let again = false;
+	let stopped = false;
+	const author = () => {
+		if (stopped) return;
+		if (running) {
+			again = true;
+			return;
+		}
+		let documents;
+		const child = spawn(process.execPath, [path.join(root, AUTHOR_FILE), "--ipc"], {
+			cwd: root,
+			stdio: [
+				"inherit",
+				"inherit",
+				"inherit",
+				"ipc"
+			]
+		});
+		running = child;
+		child.on("message", (message) => {
+			if (isAuthoredDocuments(message)) documents = message;
+		});
+		child.on("error", (error) => {
+			console.error(`[author] ${AUTHOR_FILE} did not run: ${error.message}`);
+		});
+		child.on("close", (code) => {
+			running = void 0;
+			if (stopped) return;
+			if (code === 0 && documents) onAuthored(documents);
+			else if (code === 0) console.error(`[author] ${AUTHOR_FILE} authored the space and handed nothing over: it is older than this server — npx plitzi upgrade files --write`);
+			if (again) {
+				again = false;
+				author();
+			}
+		});
+	};
+	const watcher = watch(path.join(root, SOURCE_DIR), { recursive: true }, (_event, file) => {
+		if (!file || !authored(file)) return;
+		clearTimeout(timer);
+		timer = setTimeout(author, 100);
+	});
+	return () => {
+		stopped = true;
+		clearTimeout(timer);
+		watcher.close();
+		running?.kill();
+	};
+};
+//#endregion
+export { watchSpace };

package/dist/modules/realtime/failure.d.ts

@@ -0,0 +1,6 @@
+/**
+ * What a realtime promise nobody waits on does when the pub/sub under it fails — Redis timing out under load: it says so
+ * and the server goes on. Left to reject, it reached the process's `unhandledRejection` handler, which shuts the whole
+ * server down over one undelivered cursor.
+ */
+export declare const warnRealtime: (what: string) => (error: unknown) => void;

package/dist/modules/realtime/failure.js

@@ -0,0 +1,11 @@
+//#region src/modules/realtime/failure.ts
+/**
+* What a realtime promise nobody waits on does when the pub/sub under it fails — Redis timing out under load: it says so
+* and the server goes on. Left to reject, it reached the process's `unhandledRejection` handler, which shuts the whole
+* server down over one undelivered cursor.
+*/
+var warnRealtime = (what) => (error) => {
+	console.warn(`[Realtime] ${what}:`, error instanceof Error ? error.message : error);
+};
+//#endregion
+export { warnRealtime };

package/dist/modules/realtime/handlers.js

@@ -1,5 +1,6 @@
 import onAbort from "../../helpers/onAbort.js";
 import { openEventStream } from "../../core/http/sse.js";
+import { warnRealtime } from "./failure.js";
 import { accessRefusal } from "@plitzi/sdk-shared/actions";
 import { randomBytes, randomUUID } from "node:crypto";
 import { PRESENCE_TYPE, channelLimits, matchChannel } from "@plitzi/sdk-shared/realtime";
@@ -155,7 +156,16 @@ var publishFrom = async (hub, connection, { topic, type, data }) => {
 		reason: "rate_limited"
 	};
 	if (presence) connection.announced.add(name);
-	await hub.publish(connection.space, hub.from(connection, name, kind, value));
+	try {
+		await hub.publish(connection.space, hub.from(connection, name, kind, value));
+	} catch (error) {
+		warnRealtime("a message was not delivered")(error);
+		return {
+			status: 503,
+			error: "The message was not delivered: send it again",
+			reason: "unavailable"
+		};
+	}
 	return { status: 204 };
 };
 /**
@@ -186,11 +196,11 @@ var handleRealtimeSubscribe = async ({ req, res, raw, signal, hub, resolveChanne
 		topics: [...admission.accepted.keys()],
 		refused: admission.refused
 	});
-	await hub.connect(connection);
+	await hub.connect(connection).catch(warnRealtime("a connection was not announced"));
 	await gone;
 	release();
 	stream.close();
-	await hub.disconnect(connection);
+	await hub.disconnect(connection).catch(warnRealtime("a connection was not let go"));
 };
 var parseBody = (body) => {
 	try {

package/dist/modules/realtime/hub.js

@@ -1,3 +1,4 @@
+import { warnRealtime } from "./failure.js";
 import { JOIN_TYPE, LEAVE_TYPE, REVOKED_TYPE } from "@plitzi/sdk-shared/realtime";
 //#region src/modules/realtime/hub.ts
 /** A space's topic, as the adapter knows it: namespaced, so two spaces never hear each other. */
@@ -43,7 +44,9 @@ var createRealtimeHub = (pubsub) => {
 						[...connections].filter((member) => {
 							const opened = member.grants.get(message.topic);
 							return opened !== void 0 && (grant === void 0 || opened === grant);
-						}).forEach((member) => void releaseTopic(member, message.topic));
+						}).forEach((member) => {
+							releaseTopic(member, message.topic).catch(warnRealtime(`"${message.topic}" was not let go`));
+						});
 					} else if (message) connections.forEach((member) => member.send("message", message));
 				})
 			};

package/dist/modules/realtime/socket.js

@@ -1,3 +1,4 @@
+import { warnRealtime } from "./failure.js";
 import { admit, answer, connectionFor, publishFrom } from "./handlers.js";
 import { requestOrigin } from "../../core/requestParser.js";
 import { frameText } from "../../helpers/wsFrame.js";
@@ -107,7 +108,7 @@ var handleRealtimeSocket = async ({ req, res, raw, upgrade, hub, resolveChannels
 		});
 		socket.on("close", () => {
 			clearInterval(heartbeat);
-			hub.disconnect(connection);
+			hub.disconnect(connection).catch(warnRealtime("a connection was not let go"));
 		});
 		socket.on("error", () => socket.terminate());
 		send("ready", {
@@ -115,7 +116,7 @@ var handleRealtimeSocket = async ({ req, res, raw, upgrade, hub, resolveChannels
 			topics: [...admission.accepted.keys()],
 			refused: admission.refused
 		});
-		hub.connect(connection);
+		hub.connect(connection).catch(warnRealtime("a connection was not announced"));
 	});
 };
 //#endregion

package/dist/modules/rsc/connectorRscData.d.ts

@@ -1,4 +1,5 @@
 import { ActionsModule } from '../actions';
+import { ProjectDataLookup } from '../actions/runtime/projectData';
 import { ActionLookups } from '../actions/types';
 import { ConnectorLookups } from '../connectors/resolver';
 import { SSRAdapters } from '@plitzi/sdk-shared';
@@ -17,7 +18,7 @@ import { SSRAdapters } from '@plitzi/sdk-shared';
  *
  * A deployment that resolves server elements some other way still supplies its own `getRscData`, and that one wins.
  */
-export declare const connectorRscData: ({ connectors, actions, publicDir, dataDir, elementTimeoutMs }: {
+export declare const connectorRscData: ({ connectors, actions, publicDir, data, elementTimeoutMs }: {
     connectors?: ConnectorLookups;
     actions?: {
         lookups: ActionLookups;
@@ -25,8 +26,11 @@ export declare const connectorRscData: ({ connectors, actions, publicDir, dataDi
     };
     /** Where the server's static files are: a provider whose `query` is one of them is read from disk. */
     publicDir?: string;
-    /** The project's own data, never served: a provider whose `query` is `/data/<file>` is read from it. */
-    dataDir?: string;
+    /**
+     * The space's data, never served: a provider whose `query` is `/data/<file>` is read from it — the lookup a
+     * deployment gave, or the one `createServer` derives from `dataDir`.
+     */
+    data?: ProjectDataLookup;
     /** The deployment's per-element ceiling, when it set one. `resolveRscData` decides the default. */
     elementTimeoutMs?: number;
 }) => NonNullable<SSRAdapters["getRscData"]>;