create-flowdular 0.5.1 → 0.6.1

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

@@ -1,5 +1,7 @@
+import { createServer as createHttpServer } from 'node:http';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
 import { createServer } from 'vite';
 import {
 	createOctaneLogger,
@@ -8,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
@@ -18,6 +26,7 @@ const flag = (name) => {
 };
 const port = Number(flag('--port'));
 const host = flag('--host');
+if (Number.isInteger(port) && port > 0) process.env.PORT = String(port);
 const verbose =
 	process.argv.includes('--verbose') ||
 	process.argv.includes('-v') ||
@@ -25,42 +34,116 @@ 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'],
 	],
 });
 
-/* 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);
+function openBrowser(url) {
+	if (
+		process.platform === 'linux' &&
+		!process.env.DISPLAY &&
+		!process.env.WAYLAND_DISPLAY
+	)
+		return false;
+	const command =
+		process.platform === 'darwin'
+			? 'open'
+			: process.platform === 'win32'
+				? 'rundll32.exe'
+				: 'xdg-open';
+	const args =
+		process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
+	const result = spawnSync(command, args, { stdio: 'ignore', timeout: 10000 });
+	return !result.error && result.status === 0;
+}
+
+if (!process.argv.includes('--no-open')) {
+	const setupUrl = new URL('/setup', localUrl).href;
+	try {
+		const response = await fetch(setupUrl, {
+			signal: AbortSignal.timeout(30000),
+		});
+		if (response.ok && (await response.text()).includes('setup-page')) {
+			console.log(`First-run setup: ${setupUrl}`);
+			if (!openBrowser(setupUrl))
+				console.log('Open the setup URL in a browser on this workstation.');
+		}
+	} catch {
+		// The server remains usable when a browser is unavailable.
+	}
+}

package/template/default/platform/src/generated/modules.server.ts

@@ -121,6 +121,7 @@ export function composeModuleServer(
 						'agents.run-queue',
 						'agents.run-execution.v2',
 						'agents.actions.v1',
+						'agents.actions.v2',
 						'agents.decisions.v1',
 					],
 					requires: [

package/template/default/platform/src/server/database.ts

@@ -7,8 +7,11 @@ import {
 } from '@flowdular/sdk/database';
 import { createPgliteCluster } from '@flowdular/sdk/database-pglite';
 import { Pool } from 'pg';
+import process from 'node:process';
+import { resolve } from 'node:path';
 
 export { databaseProviderConfigFromEnvironment };
+export type PlatformDatabaseProvider = ConfiguredDatabaseProvider;
 
 /* The deployable owns both PostgreSQL drivers: node-postgres for a deployment
    and the embedded build for a local run. @flowdular/sdk/database stays driver free,
@@ -23,3 +26,24 @@ export function createPlatformDatabaseProvider(
 		...factories,
 	});
 }
+
+/** A missing PostgreSQL URL is an unconfigured installation. */
+export function platformDatabaseConfigured(
+	environment: NodeJS.ProcessEnv,
+): boolean {
+	const adapter =
+		environment.FD_DATABASE_ADAPTER?.trim() ||
+		(environment.NODE_ENV === 'production' ? 'postgresql' : 'pglite');
+	return (
+		adapter !== 'postgresql' || Boolean(environment.FD_DATABASE_URL?.trim())
+	);
+}
+
+/** An orchestrator's environment takes precedence over the generated .env. */
+export function loadPlatformEnvironmentFile(workspaceRoot: string): void {
+	try {
+		process.loadEnvFile(resolve(workspaceRoot, '.env'));
+	} catch {
+		// Container deployments configure the process without a workspace .env.
+	}
+}

package/template/default/platform/src/server/lifecycle.ts

@@ -0,0 +1,325 @@
+import process from 'node:process';
+import { randomUUID } from 'node:crypto';
+import type { EventEmitter } from 'node:events';
+import { BroadcastChannel } from 'node:worker_threads';
+import type { Middleware } from '@octanejs/app-core';
+import { serverLogger, trackResponseBody } from '@flowdular/sdk/server';
+
+export const PLATFORM_LIFECYCLE_SYMBOL = Symbol.for(
+	'flowdular.platform.runtime-lifecycle',
+);
+export const PLATFORM_LIFECYCLE_ACTIVATE_EVENT =
+	'flowdular:platform-runtime-activate';
+export const PLATFORM_LIFECYCLE_RETIRE_EVENT =
+	'flowdular:platform-runtime-retire';
+const PLATFORM_LIFECYCLE_CHANNEL = 'flowdular.platform.runtime-lifecycle';
+
+type Dispose = () => void | Promise<void>;
+
+export interface PlatformRuntimeLifecycle {
+	readonly middleware: Middleware;
+	/** Runs as soon as retirement begins, before the requests in flight drain:
+	    for a producer that holds a request open until it is told to stop. */
+	addInterrupt(interrupt: Dispose): void;
+	addQuiesce(quiesce: Dispose): void;
+	add(dispose: Dispose): void;
+	retire(): Promise<void>;
+}
+
+type ProcessWithLifecycle = NodeJS.Process & {
+	[PLATFORM_LIFECYCLE_SYMBOL]?: PlatformRuntimeLifecycle;
+};
+
+/* An event stream never finishes on its own. Its protocol has the client
+	reconnect and resume from Last-Event-ID, which reaches the next generation,
+	so retirement ends it instead of waiting for it. Any other body drains. */
+function isEventStream(response: Response): boolean {
+	const type = response.headers.get('content-type')?.split(';', 1)[0];
+	return type?.trim().toLowerCase() === 'text/event-stream';
+}
+
+/* EventSource stops reconnecting for good on any answer but a 200 event
+	stream, and a production server keeps listening while it retires. A stream
+	request to a retired generation gets an empty stream that ends at once, so
+	the client keeps reconnecting until the next process answers. */
+function retiredResponse(request: Request | undefined): Response {
+	if (
+		request?.method === 'GET' &&
+		request.headers.get('accept')?.includes('text/event-stream')
+	) {
+		return new Response('retry: 1000\n\n', {
+			headers: {
+				'content-type': 'text/event-stream; charset=utf-8',
+				'cache-control': 'no-store',
+			},
+		});
+	}
+	return new Response(null, {
+		status: 503,
+		headers: { 'retry-after': '1' },
+	});
+}
+
+/* Vite evaluates octane.config.ts again when one of its SSR dependencies is
+	invalidated. A generation owns every resource created by that evaluation.
+	Retirement interrupts what would hold a request open, waits for requests
+	already using the old route closures, then disposes its resources in
+	reverse composition order. */
+export function createPlatformRuntimeLifecycle(): PlatformRuntimeLifecycle {
+	const disposers: Dispose[] = [];
+	const quiescers: Dispose[] = [];
+	const interrupts = new Set<Dispose>();
+	let interrupted: Promise<unknown[]> = Promise.resolve([]);
+	let activeRequests = 0;
+	let retired = false;
+	let finishing = false;
+	let disposal: Promise<void> | undefined;
+	let resolveDisposal: (() => void) | undefined;
+	let rejectDisposal: ((error: unknown) => void) | undefined;
+
+	const finish = () => {
+		if (!retired || activeRequests !== 0 || disposal === undefined || finishing)
+			return;
+		finishing = true;
+		const currentQuiescers = quiescers.splice(0).reverse();
+		const current = disposers.splice(0).reverse();
+		void (async () => {
+			const failures = await interrupted;
+			/* Every background producer stops before any module repository closes. */
+			for (const quiesce of currentQuiescers) {
+				try {
+					await quiesce();
+				} catch (error) {
+					failures.push(error);
+				}
+			}
+			for (const dispose of current) {
+				try {
+					await dispose();
+				} catch (error) {
+					failures.push(error);
+				}
+			}
+			if (failures.length > 0) {
+				/* A logger reads the message, not the errors array, so each cause
+				   is named there rather than left for a debugger. */
+				rejectDisposal?.(
+					new AggregateError(
+						failures,
+						'Platform runtime teardown did not release every resource: ' +
+							failures
+								.map((failure) =>
+									failure instanceof Error ? failure.message : String(failure),
+								)
+								.join('; '),
+					),
+				);
+			} else {
+				resolveDisposal?.();
+			}
+		})();
+	};
+
+	const interrupt = async (): Promise<unknown[]> => {
+		const failures: unknown[] = [];
+		await Promise.all(
+			[...interrupts].map(async (run) => {
+				try {
+					await run();
+				} catch (error) {
+					failures.push(error);
+				}
+			}),
+		);
+		return failures;
+	};
+
+	const lifecycle: PlatformRuntimeLifecycle = {
+		middleware: async (context, next) => {
+			if (retired) return retiredResponse(context.request);
+			activeRequests += 1;
+			let endStream: (() => void) | undefined;
+			const release = () => {
+				if (endStream) interrupts.delete(endStream);
+				activeRequests -= 1;
+				finish();
+			};
+			try {
+				const response = await next();
+				const signal = context.request?.signal;
+				if (!isEventStream(response)) {
+					return trackResponseBody(response, release, signal);
+				}
+				const end = new AbortController();
+				endStream = () => end.abort(new Error('The platform runtime retired.'));
+				if (retired) endStream();
+				else interrupts.add(endStream);
+				return trackResponseBody(
+					response,
+					release,
+					signal ? AbortSignal.any([signal, end.signal]) : end.signal,
+				);
+			} catch (error) {
+				release();
+				throw error;
+			}
+		},
+		addInterrupt(run) {
+			if (retired) {
+				void Promise.resolve()
+					.then(run)
+					.catch((error: unknown) => {
+						serverLogger().error('late platform interrupt failed', {
+							module: 'platform',
+							err: error,
+						});
+					});
+				return;
+			}
+			interrupts.add(run);
+		},
+		addQuiesce(quiesce) {
+			if (retired) {
+				void Promise.resolve()
+					.then(quiesce)
+					.catch((error: unknown) => {
+						serverLogger().error('late platform quiesce failed', {
+							module: 'platform',
+							err: error,
+						});
+					});
+				return;
+			}
+			quiescers.push(quiesce);
+		},
+		add(dispose) {
+			if (retired) {
+				void Promise.resolve()
+					.then(dispose)
+					.catch((error: unknown) => {
+						serverLogger().error('late platform teardown failed', {
+							module: 'platform',
+							err: error,
+						});
+					});
+				return;
+			}
+			disposers.push(dispose);
+		},
+		retire() {
+			if (!disposal) {
+				disposal = new Promise<void>((resolve, reject) => {
+					resolveDisposal = resolve;
+					rejectDisposal = reject;
+				});
+				retired = true;
+				interrupted = interrupt();
+				finish();
+			}
+			return disposal;
+		},
+	};
+	return lifecycle;
+}
+
+/* Activation happens only after the new configuration composed successfully.
+	A failed HMR evaluation therefore tears down only its partial generation and
+	leaves the previous, still-routable generation alive. */
+export function activatePlatformRuntimeLifecycle(
+	lifecycle: PlatformRuntimeLifecycle,
+): Promise<void> {
+	const owner = process as ProcessWithLifecycle;
+	const events = process as unknown as EventEmitter;
+	const generationId = `${process.pid}:${randomUUID()}`;
+	const channel = new BroadcastChannel(PLATFORM_LIFECYCLE_CHANNEL);
+	channel.unref();
+	const previous = owner[PLATFORM_LIFECYCLE_SYMBOL];
+	owner[PLATFORM_LIFECYCLE_SYMBOL] = lifecycle;
+	/* Octane loads its config once through the Vite config loader and again
+	   through the SSR module runner. Their process wrappers do not share custom
+	   properties, but both delegate EventEmitter operations to the real process.
+	   The event is therefore the cross-runner ownership handoff. */
+	const onActivation = (
+		next: PlatformRuntimeLifecycle,
+		report?: (retirement: Promise<void>) => void,
+	) => {
+		if (next === lifecycle) return;
+		const retirement = lifecycle.retire();
+		report?.(retirement);
+		void retirement.catch((error: unknown) => {
+			serverLogger().error('stale platform teardown failed', {
+				module: 'platform',
+				err: error,
+			});
+		});
+	};
+	const onRetire = (report: (retirement: Promise<void>) => void) => {
+		report(lifecycle.retire());
+	};
+	channel.onmessage = (event) => {
+		if (!event.data || typeof event.data !== 'object') return;
+		const message = event.data as { type?: unknown; generationId?: unknown };
+		if (
+			message.type !== 'retire-all' &&
+			(message.type !== 'activate' || message.generationId === generationId)
+		) {
+			return;
+		}
+		/* Closing a BroadcastChannel from inside its own callback can wait for the
+		   callback to return. Start retirement in the next microtask so channel
+		   teardown cannot deadlock the generation it is releasing. */
+		queueMicrotask(() => {
+			void lifecycle.retire().catch((error: unknown) => {
+				serverLogger().error('cross-runner platform teardown failed', {
+					module: 'platform',
+					err: error,
+				});
+			});
+		});
+	};
+	events.on(PLATFORM_LIFECYCLE_ACTIVATE_EVENT, onActivation);
+	events.on(PLATFORM_LIFECYCLE_RETIRE_EVENT, onRetire);
+	lifecycle.add(() => {
+		channel.close();
+		events.off(PLATFORM_LIFECYCLE_ACTIVATE_EVENT, onActivation);
+		events.off(PLATFORM_LIFECYCLE_RETIRE_EVENT, onRetire);
+		if (owner[PLATFORM_LIFECYCLE_SYMBOL] === lifecycle) {
+			delete owner[PLATFORM_LIFECYCLE_SYMBOL];
+		}
+	});
+	const retirements = new Set<Promise<void>>();
+	events.emit(
+		PLATFORM_LIFECYCLE_ACTIVATE_EVENT,
+		lifecycle,
+		(retirement: Promise<void>) => retirements.add(retirement),
+	);
+	channel.postMessage({ type: 'activate', generationId });
+	if (previous && previous !== lifecycle) {
+		const retirement = previous.retire();
+		retirements.add(retirement);
+		void retirement.catch((error: unknown) => {
+			serverLogger().error('stale platform teardown failed', {
+				module: 'platform',
+				err: error,
+			});
+		});
+	}
+	return Promise.all(retirements).then(() => undefined);
+}
+
+/* Preparation may inspect durable state but must not create write handles,
+	 workers or timers. Only a fully prepared generation may retire the one that
+	 is currently serving requests. */
+export async function prepareAndActivatePlatformRuntimeLifecycle(
+	lifecycle: PlatformRuntimeLifecycle,
+	preparations: readonly (() => void | Promise<void>)[],
+): Promise<void> {
+	for (const prepare of preparations) await prepare();
+	await activatePlatformRuntimeLifecycle(lifecycle);
+}
+
+export function activePlatformRuntimeLifecycle():
+	| PlatformRuntimeLifecycle
+	| undefined {
+	return (process as ProcessWithLifecycle)[PLATFORM_LIFECYCLE_SYMBOL];
+}

package/template/default/platform/src/server/runtime-role.ts

@@ -0,0 +1,33 @@
+import type { ModuleServerComposition } from '@flowdular/sdk/server';
+
+/* combined serves HTTP and runs every module worker in one process. web serves
+   HTTP only: its compositions start, but no module worker loop, poller or
+   wake-driven claim runs there, so a host that freezes idle instances never
+   strands work. The loops a web process still runs are auth.core's expired
+   session sweep (auth.core.sessions) and settings log sweep
+   (auth.core.settings-log), which start with the auth service in every role;
+   freezing them only delays deleting rows no lookup needs and writing a
+   platform settings event its saving process deferred. tick runs the module
+   workers only inside an authenticated tick request, which drains them before
+   it answers. */
+export type PlatformRuntimeRole = 'combined' | 'web' | 'tick';
+
+export function platformRuntimeRole(
+	environment: NodeJS.ProcessEnv,
+): PlatformRuntimeRole {
+	const role = environment.FD_RUNTIME_ROLE?.trim() || 'combined';
+	if (role !== 'combined' && role !== 'web' && role !== 'tick') {
+		throw new Error('FD_RUNTIME_ROLE must be "combined", "web" or "tick".');
+	}
+	return role;
+}
+
+/* Awaited in composition order, so a failed worker start fails the boot before
+   the process reports itself ready. */
+export async function startModuleWorkers(
+	compositions: readonly ModuleServerComposition[],
+	role: PlatformRuntimeRole,
+): Promise<void> {
+	if (role !== 'combined') return;
+	for (const composition of compositions) await composition.startWorker?.();
+}