create-flowdular 0.6.0 → 0.6.1

package/template/default/infra/sdk-module-manifests.mjs

@@ -0,0 +1,118 @@
+import {
+	cp,
+	lstat,
+	mkdir,
+	readFile,
+	realpath,
+	writeFile,
+} from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+
+/* A deployment ships no node_modules, yet the platform lists the modules
+   @flowdular/sdk ships by resolving the SDK's module index from platform/. This
+   copies what that lookup reads (the index, each indexed module.json and its
+   spec/module.yaml, and a package.json exporting the index) to the same place
+   under the deployment root. A workspace without the SDK copies nothing.
+
+   Usage: node infra/sdk-module-manifests.mjs <workspace> <deployment root> */
+
+/* The platform refuses a larger index, so the copy does too. */
+const INDEX_LIMIT = 256;
+const UNRESOLVED = new Set([
+	'MODULE_NOT_FOUND',
+	'ERR_PACKAGE_PATH_NOT_EXPORTED',
+]);
+
+const [workspaceArgument, deploymentArgument] = process.argv.slice(2);
+if (!workspaceArgument || !deploymentArgument) {
+	throw new Error(
+		'Usage: node infra/sdk-module-manifests.mjs <workspace> <deployment root>',
+	);
+}
+const workspace = resolve(workspaceArgument);
+const destination = join(
+	resolve(deploymentArgument),
+	'platform/node_modules/@flowdular/sdk',
+);
+
+function sdkIndexPath() {
+	try {
+		return createRequire(join(workspace, 'platform/package.json')).resolve(
+			'@flowdular/sdk/modules.json',
+		);
+	} catch (error) {
+		if (UNRESOLVED.has(error.code)) return null;
+		throw error;
+	}
+}
+
+function insidePath(root, path) {
+	const fromRoot = relative(root, path);
+	return (
+		Boolean(fromRoot) && !fromRoot.startsWith('..') && !isAbsolute(fromRoot)
+	);
+}
+
+/* Copies a file the index names, refusing one that leaves the SDK lexically or
+   through a link. An absent optional file is skipped. */
+async function copyFromSdk(sdkRoot, path, optional = false) {
+	const lexical = resolve(sdkRoot, path);
+	if (!insidePath(sdkRoot, lexical)) {
+		throw new Error(`SDK module file escapes the package: ${path}`);
+	}
+	let source;
+	try {
+		source = await realpath(lexical);
+	} catch (error) {
+		if (optional && error.code === 'ENOENT') return;
+		throw error;
+	}
+	if (!insidePath(sdkRoot, source) || !(await lstat(source)).isFile()) {
+		throw new Error(
+			`SDK module file must be a regular file inside the package: ${path}`,
+		);
+	}
+	const target = join(destination, relative(sdkRoot, lexical));
+	await mkdir(dirname(target), { recursive: true });
+	await cp(source, target);
+}
+
+const indexPath = sdkIndexPath();
+if (indexPath) {
+	const sdkRoot = await realpath(dirname(indexPath));
+	const indexSource = await readFile(indexPath, 'utf8');
+	const index = JSON.parse(indexSource);
+	if (
+		index.schemaVersion !== 1 ||
+		!Array.isArray(index.modules) ||
+		index.modules.length > INDEX_LIMIT
+	) {
+		throw new Error('Invalid SDK module index.');
+	}
+	await mkdir(destination, { recursive: true });
+	for (const entry of index.modules) {
+		if (typeof entry?.manifest !== 'string') {
+			throw new Error('Invalid SDK module manifest path.');
+		}
+		await copyFromSdk(sdkRoot, entry.manifest);
+		await copyFromSdk(
+			sdkRoot,
+			join(dirname(entry.manifest), 'spec/module.yaml'),
+			true,
+		);
+	}
+	await writeFile(join(destination, 'modules.json'), indexSource);
+	await writeFile(
+		join(destination, 'package.json'),
+		`${JSON.stringify(
+			{
+				name: '@flowdular/sdk',
+				private: true,
+				exports: { './modules.json': './modules.json' },
+			},
+			null,
+			'\t',
+		)}\n`,
+	);
+}

package/template/default/infra/vercel/build.mjs

@@ -160,6 +160,15 @@ async function writeFunction(directory, runtimeRole) {
 			);
 		}
 	}
+	const sdkManifests = spawnSync(
+		process.execPath,
+		[join(repositoryRoot, 'infra/sdk-module-manifests.mjs'), root, directory],
+		{ stdio: 'inherit' },
+	);
+	if (sdkManifests.error) throw sdkManifests.error;
+	if (sdkManifests.status !== 0) {
+		throw new Error('Copying the SDK module manifests failed.');
+	}
 	await copyRegular(
 		join(repositoryRoot, 'infra/vercel/handler.mjs'),
 		join(directory, 'handler.mjs'),

package/template/default/modules/example/package.json

@@ -16,7 +16,7 @@
 	"dependencies": {
 		"octane": "0.9.1",
 		"segment-state": "0.4.0",
-		"@flowdular/sdk": "0.6.0"
+		"@flowdular/sdk": "0.6.1"
 	},
 	"devDependencies": {
 		"@tsrx/typescript-plugin": "0.3.120",

package/template/default/package.json

@@ -15,7 +15,6 @@
 		"format": "prettier --write .",
 		"format:check": "prettier --check .",
 		"flowdular": "flowdular",
-		"cl": "flowdular",
 		"doctor": "flowdular doctor",
 		"verify": "pnpm rules:check && pnpm typecheck && pnpm test && flowdular spec validate --all && flowdular module validate && pnpm format:check",
 		"rules:generate": "rulesync generate",
@@ -23,10 +22,10 @@
 		"build": "flowdular module sync --apply && pnpm --filter @app/platform build"
 	},
 	"devDependencies": {
-		"@flowdular/sandbox": "0.6.0",
+		"@flowdular/sandbox": "0.6.1",
 		"@tsrx/prettier-plugin": "0.3.120",
 		"prettier": "3.6.2",
-		"flowdular": "0.6.0",
+		"flowdular": "0.6.1",
 		"rulesync": "16.21.0"
 	}
 }

package/template/default/platform/octane.config.ts

@@ -44,6 +44,10 @@ import {
 	createReadinessEndpoint,
 	healthEndpoint,
 } from './src/server/health.ts';
+import {
+	createPlatformRuntimeLifecycle,
+	prepareAndActivatePlatformRuntimeLifecycle,
+} from './src/server/lifecycle.ts';
 import { createMetricsRoutes } from './src/server/metrics.ts';
 import {
 	platformRuntimeRole,
@@ -97,6 +101,11 @@ function firstRunConfig(databasePreconfigured = false) {
 }
 
 async function createPlatformConfig() {
+	if (process.env.FD_INTERNAL_PLATFORM_TERMINATING === 'true') {
+		throw new Error(
+			'Platform startup was requested while the process is stopping.',
+		);
+	}
 	loadPlatformEnvironmentFile(workspaceRoot);
 	const serverless = process.env.FD_DEPLOYMENT_TARGET === 'vercel';
 	if (!building && !platformDatabaseConfigured(process.env)) {
@@ -215,10 +224,11 @@ async function createPlatformConfig() {
    catalogue, so every reader sees the declarations the modules agreed on. */
 	dataClasses.seal();
 
-	let stopping = false;
-	const shutdown = async () => {
-		if (stopping) return;
-		stopping = true;
+	/* Each evaluation of this file is one generation, and Vite evaluates it more
+	   than once per process. The generation retires when the next one is
+	   prepared, when the development server stops, or on a stop signal. */
+	const lifecycle = createPlatformRuntimeLifecycle();
+	lifecycle.add(async () => {
 		await ticker?.close();
 		for (const composition of moduleCompositions) {
 			await composition.stop?.();
@@ -230,24 +240,38 @@ async function createPlatformConfig() {
 		/* Last, so the spans and error reports this process queued while it stopped
 	   still leave with it. */
 		await observability.dispose();
-	};
+	});
 
 	/* check() proves the runtime role holds neither SUPERUSER nor BYPASSRLS before
    any module reads a row. */
 	if (!building) {
 		try {
-			await databases.check();
-			/* Platform-scoped settings are read by background work before any request
-		   could prime them; a workspace is primed by the authentication middleware. */
-			await settings.prime(PLATFORM_SETTINGS_TENANT);
-			for (const composition of moduleCompositions)
-				await composition.prepare?.();
+			/* The previous generation retires once this one is prepared, and this
+			   one starts its workers only after the previous has drained. */
+			await prepareAndActivatePlatformRuntimeLifecycle(lifecycle, [
+				async () => {
+					await databases.check();
+				},
+				/* Platform-scoped settings are read by background work before any request
+			   could prime them; a workspace is primed by the authentication middleware. */
+				() => settings.prime(PLATFORM_SETTINGS_TENANT),
+				...moduleCompositions.map(
+					(composition) => () => composition.prepare?.(),
+				),
+			]);
+			/* A stop that arrived while this generation was preparing retired only
+			   the generations active then, so this one retires itself. */
+			if (process.env.FD_INTERNAL_PLATFORM_TERMINATING === 'true') {
+				throw new Error(
+					'Platform startup was requested while the process is stopping.',
+				);
+			}
 			for (const composition of moduleCompositions) composition.start?.();
 			await startModuleWorkers(moduleCompositions, runtimeRole);
 		} catch (error) {
 			/* A worker that started before the failure would keep running in a
 		   process that never serves. The boot failure is the one rethrown. */
-			await shutdown().catch((cleanupError: unknown) => {
+			await lifecycle.retire().catch((cleanupError: unknown) => {
 				serverLogger().error('platform boot cleanup failed', {
 					module: 'platform',
 					err: cleanupError,
@@ -259,10 +283,23 @@ async function createPlatformConfig() {
 
 	// Bundling needs route declarations without background work or retained leases.
 	if (building) {
-		await shutdown();
+		await lifecycle.retire();
 	} else {
-		process.once('SIGINT', () => void shutdown());
-		process.once('SIGTERM', () => void shutdown());
+		/* scripts/dev.mjs retires every generation itself; a production server
+		   has only these. */
+		const retire = () =>
+			void lifecycle.retire().catch((error: unknown) => {
+				serverLogger().error('platform shutdown failed', {
+					module: 'platform',
+					err: error,
+				});
+			});
+		process.once('SIGINT', retire);
+		process.once('SIGTERM', retire);
+		lifecycle.add(() => {
+			process.off('SIGINT', retire);
+			process.off('SIGTERM', retire);
+		});
 	}
 
 	return defineConfig({
@@ -273,6 +310,7 @@ async function createPlatformConfig() {
 			createCorsMiddleware({
 				allowOrigin: (origin) => authRuntime.apiOriginAllowed(origin),
 			}),
+			lifecycle.middleware,
 			...(firstRun ? [firstRun.middleware] : []),
 			authRuntime.middleware,
 		],

package/template/default/platform/package.json

@@ -15,7 +15,7 @@
 		"@octanejs/vite-plugin": "0.2.1",
 		"octane": "0.9.1",
 		"pg": "8.23.0",
-		"@flowdular/sdk": "0.6.0"
+		"@flowdular/sdk": "0.6.1"
 	},
 	"devDependencies": {
 		"@octanejs/app-core": "0.1.1",

package/template/default/platform/scripts/dev.mjs

@@ -1,3 +1,4 @@
+import { createServer as createHttpServer } from 'node:http';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
@@ -9,6 +10,12 @@ import {
 	createTheme,
 	printReady,
 } from '@flowdular/sdk/dev-console';
+import {
+	PLATFORM_SHUTDOWN_BUDGET_MS,
+	retirePlatformRuntimes,
+	stopOnSignals,
+	stopServing,
+} from '@flowdular/sdk/dev-console/shutdown';
 
 const appRoot = resolve(fileURLToPath(new URL('..', import.meta.url)));
 /* `pnpm dev -- --port 4396 --host 0.0.0.0` overrides vite.config.ts, so a
@@ -27,36 +34,81 @@ const verbose =
 const color = shouldUseColor();
 const restoreConsole = installOctaneConsoleBridge(verbose, color);
 
+/* Vite serves in middleware mode behind this server. A Vite that listens
+   itself exits the process on SIGTERM as soon as it has closed, before
+   octane.config.ts has released its databases. */
 let server;
+const httpServer = createHttpServer((request, response) =>
+	server.middlewares(request, response),
+);
+let localUrl;
 try {
 	server = await createServer({
 		root: appRoot,
 		configFile: resolve(appRoot, 'vite.config.ts'),
 		customLogger: createOctaneLogger(verbose, color),
 		clearScreen: false,
-		...(Number.isInteger(port) && port > 0
-			? { server: { port, strictPort: true, ...(host ? { host } : {}) } }
-			: host
-				? { server: { host } }
-				: {}),
+		server: {
+			middlewareMode: true,
+			ws: { server: httpServer },
+			...(Number.isInteger(port) && port > 0 ? { port, strictPort: true } : {}),
+			...(host ? { host } : {}),
+		},
+	});
+	/* The address Vite would have bound: vite.config.ts or the flags above,
+	   and localhost when neither names a host. */
+	const listenPort = server.config.server.port;
+	const configuredHost = server.config.server.host;
+	const listenHost =
+		configuredHost === true ? undefined : configuredHost || 'localhost';
+	await new Promise((resolveListen, rejectListen) => {
+		httpServer.once('error', rejectListen);
+		httpServer.listen(listenPort, listenHost, () => {
+			httpServer.off('error', rejectListen);
+			resolveListen();
+		});
 	});
-	await server.listen();
+	const displayHost =
+		listenHost === undefined || listenHost === '0.0.0.0' || listenHost === '::'
+			? 'localhost'
+			: listenHost;
+	localUrl = `http://${displayHost.includes(':') ? `[${displayHost}]` : displayHost}:${listenPort}/`;
 } catch (error) {
+	if (httpServer.listening) httpServer.close();
 	restoreConsole();
 	throw error;
 }
+
+/* The process ends on its own once every runtime generation has released
+   what it holds, so one that was still preparing when the stop arrived
+   drains as well; the deadline bounds the wait. */
+async function stop() {
+	process.env.FD_INTERNAL_PLATFORM_TERMINATING = 'true';
+	try {
+		await Promise.all([
+			stopServing(httpServer, server),
+			retirePlatformRuntimes(),
+		]);
+	} finally {
+		await server.close();
+		restoreConsole();
+	}
+}
+stopOnSignals(
+	() =>
+		void stop().catch((error) => {
+			console.error(error instanceof Error ? error.message : String(error));
+			process.exitCode = 1;
+		}),
+	{ deadlineMs: PLATFORM_SHUTDOWN_BUDGET_MS },
+);
+
 printReady({
 	title: 'FLOWDULAR',
 	subtitle: 'development workspace',
 	theme: createTheme(color),
 	lines: [
-		[
-			'local',
-			server.resolvedUrls?.local?.[0] ??
-				server.resolvedUrls?.network?.[0] ??
-				'the address vite.config.ts sets',
-			'info',
-		],
+		['local', localUrl, 'info'],
 		['diagnostics', verbose ? 'verbose' : 'quiet · use --verbose', 'muted'],
 	],
 });
@@ -80,8 +132,7 @@ function openBrowser(url) {
 	return !result.error && result.status === 0;
 }
 
-const localUrl = server.resolvedUrls?.local?.[0];
-if (localUrl && !process.argv.includes('--no-open')) {
+if (!process.argv.includes('--no-open')) {
 	const setupUrl = new URL('/setup', localUrl).href;
 	try {
 		const response = await fetch(setupUrl, {
@@ -96,9 +147,3 @@ if (localUrl && !process.argv.includes('--no-open')) {
 		// The server remains usable when a browser is unavailable.
 	}
 }
-
-/* Closing without exiting lets octane.config.ts release the database on the
-   same signal; the process ends once both have drained. */
-const stop = () => void server.close().finally(restoreConsole);
-process.once('SIGINT', stop);
-process.once('SIGTERM', stop);