create-flowdular 0.5.1 → 0.6.0

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

@@ -9,12 +9,12 @@ import {
 	validateApplicationPath,
 	createMailPort,
 	mailConfigFromEnvironment,
+	serverLogger,
 } from '@flowdular/sdk/server';
 import {
 	createDataClassRegistry,
 	PLATFORM_SETTINGS_TENANT,
 } from '@flowdular/sdk/kernel';
-import { resolve } from 'node:path';
 import { defineConfig, RenderRoute } from '@octanejs/vite-plugin';
 import {
 	authRuntimeOptionsFromEnvironment,
@@ -37,12 +37,24 @@ import {
 import {
 	createPlatformDatabaseProvider,
 	databaseProviderConfigFromEnvironment,
+	loadPlatformEnvironmentFile,
+	platformDatabaseConfigured,
 } from './src/server/database.ts';
 import {
 	createReadinessEndpoint,
 	healthEndpoint,
 } from './src/server/health.ts';
 import { createMetricsRoutes } from './src/server/metrics.ts';
+import {
+	platformRuntimeRole,
+	startModuleWorkers,
+} from './src/server/runtime-role.ts';
+import {
+	createWorkerTickEndpoint,
+	createWorkerTicker,
+	WORKER_TICK_PATH,
+	workerTickConfigFromEnvironment,
+} from './src/server/worker-tick.ts';
 import { createPlatformObservability } from './src/server/tracing.ts';
 import {
 	createStorageKeyring,
@@ -50,6 +62,13 @@ import {
 	createStorageRoutes,
 	storageConfigFromEnvironment,
 } from './src/server/storage.ts';
+import {
+	clearSetupToken,
+	configuredDatabaseNeedsFirstRun,
+	createFirstRunSetup,
+	createInPlaceFirstRun,
+} from './src/server/setup/index.ts';
+import { findWorkspaceRoot } from './src/server/workspace-root.ts';
 
 function checkedRoutes<T extends Parameters<typeof assertRouteConflicts>[0]>(
 	routes: T,
@@ -59,184 +78,261 @@ function checkedRoutes<T extends Parameters<typeof assertRouteConflicts>[0]>(
 }
 
 const SHELL = ['App', '/src/App.tsrx'] as const;
-const workspaceRoot = resolve(import.meta.dirname, '..');
+const workspaceRoot = findWorkspaceRoot(import.meta.dirname);
 const building = process.env.FD_INTERNAL_BUILD === 'true';
 
-/* Composed first and drained last: a trace or an error report is evidence about
+function firstRunConfig(databasePreconfigured = false) {
+	const setup = createFirstRunSetup({
+		applicationPath: applicationBasePath,
+		webMountPaths: moduleWebMounts.map((site) => site.path),
+		environment: process.env,
+		databasePreconfigured,
+		workspaceRoot,
+	});
+	return defineConfig({
+		router: {
+			routes: checkedRoutes([healthEndpoint.serverRoute, ...setup.routes]),
+		},
+	});
+}
+
+async function createPlatformConfig() {
+	loadPlatformEnvironmentFile(workspaceRoot);
+	const serverless = process.env.FD_DEPLOYMENT_TARGET === 'vercel';
+	if (!building && !platformDatabaseConfigured(process.env)) {
+		if (serverless)
+			throw new Error(
+				'Vercel requires a configured external PostgreSQL database before deployment.',
+			);
+		return firstRunConfig();
+	}
+	/* A Vercel Function can neither restart into the application after setup
+	   nor keep a token file, so it composes the application and serves setup
+	   inside it until the first workspace exists. */
+	const needsFirstRun =
+		!building &&
+		(await configuredDatabaseNeedsFirstRun(process.env, workspaceRoot));
+	if (needsFirstRun && !serverless) return firstRunConfig(true);
+	clearSetupToken(workspaceRoot);
+	const runtimeRole = platformRuntimeRole(process.env);
+	const workerTick =
+		runtimeRole === 'tick'
+			? workerTickConfigFromEnvironment(process.env)
+			: null;
+
+	/* Composed first and drained last: a trace or an error report is evidence about
    the boot that follows it, and both egresses refuse a misconfigured endpoint
    here rather than at the first request that needed them. */
-const observability = createPlatformObservability({
-	environment: building
-		? { ...process.env, NODE_ENV: 'development' }
-		: process.env,
-});
-const databases = createPlatformDatabaseProvider(
-	databaseProviderConfigFromEnvironment(
-		building ? { ...process.env, NODE_ENV: 'development' } : process.env,
-		workspaceRoot,
-	),
-);
-const storageKeyring = createStorageKeyring(process.env, workspaceRoot);
-const storage = createStoragePort(
-	storageConfigFromEnvironment(
-		building ? { ...process.env, NODE_ENV: 'development' } : process.env,
-		workspaceRoot,
-	),
-	{ keyring: storageKeyring },
-);
-const configuredApplicationPath = validateApplicationPath(
-	process.env.FD_APPLICATION_PATH ?? applicationBasePath,
-);
-/* One outbound transport for the whole deployment. auth.core is only its
+	const observability = createPlatformObservability({
+		environment: building
+			? { ...process.env, NODE_ENV: 'development' }
+			: process.env,
+	});
+	const databases = createPlatformDatabaseProvider(
+		databaseProviderConfigFromEnvironment(
+			building ? { ...process.env, NODE_ENV: 'development' } : process.env,
+			workspaceRoot,
+		),
+	);
+	const storageKeyring = createStorageKeyring(process.env, workspaceRoot);
+	const storage = createStoragePort(
+		storageConfigFromEnvironment(
+			building ? { ...process.env, NODE_ENV: 'development' } : process.env,
+			workspaceRoot,
+		),
+		{ keyring: storageKeyring },
+	);
+	const configuredApplicationPath = validateApplicationPath(
+		process.env.FD_APPLICATION_PATH ?? applicationBasePath,
+	);
+	/* One outbound transport for the whole deployment. auth.core is only its
    first sender; the SMTP client comes from that module because it is the one
    that declares the dependency. */
-const mail = createMailPort(
-	mailConfigFromEnvironment(
-		building ? { ...process.env, NODE_ENV: 'development' } : process.env,
-	),
-	{ createSmtpTransport: nodemailerSmtpTransport },
-);
-/* Created before the auth runtime so auth.core, which composes outside the
+	const mail = createMailPort(
+		mailConfigFromEnvironment(
+			building ? { ...process.env, NODE_ENV: 'development' } : process.env,
+		),
+		{ createSmtpTransport: nodemailerSmtpTransport },
+	);
+	/* Created before the auth runtime so auth.core, which composes outside the
    generated module list, declares its data classes into the same registry. */
-const dataClasses = createDataClassRegistry();
-const authRuntime = createAuthRuntime({
-	...authRuntimeOptionsFromEnvironment(
-		building ? { ...process.env, NODE_ENV: 'development' } : process.env,
-		workspaceRoot,
-	),
-	applicationPath: configuredApplicationPath,
-	databases,
-	dataClasses,
-	mail,
-	metrics: createModuleMetrics('auth.core'),
-});
+	const dataClasses = createDataClassRegistry();
+	const authRuntime = createAuthRuntime({
+		...authRuntimeOptionsFromEnvironment(
+			building ? { ...process.env, NODE_ENV: 'development' } : process.env,
+			workspaceRoot,
+		),
+		applicationPath: configuredApplicationPath,
+		databases,
+		dataClasses,
+		mail,
+		metrics: createModuleMetrics('auth.core'),
+	});
 
-/* Module APIs come from the generated composition. Enable or disable modules
+	/* Module APIs come from the generated composition. Enable or disable modules
    with "pnpm flowdular module enable <id> --apply"; never wire them here by hand. */
-const settings = authRuntime.moduleSettings;
-const agentDefinitions = createPlatformAgentRegistry();
-const moduleCompositions = composeModuleServer({
-	environment: process.env,
-	workspaceRoot,
-	auth: authRuntime,
-	settings,
-	agentTools: createPlatformToolRegistry(),
-	agentDefinitions,
-	capabilities: createPlatformCapabilityRegistry(),
-	dataClasses,
-	databases,
-	storage,
-	/* The relay auth.core resolves per message from its stored settings, falling
+	const settings = authRuntime.moduleSettings;
+	const firstRun = needsFirstRun
+		? createInPlaceFirstRun({
+				environment: process.env,
+				workspaceRoot,
+				applicationPath: configuredApplicationPath,
+				webMountPaths: moduleWebMounts.map((site) => site.path),
+				passThrough: ['/api/health', '/api/ready', WORKER_TICK_PATH],
+				workspaceExists: async () =>
+					(await authRuntime.service()).hasAnyTenant(),
+			})
+		: null;
+	const agentDefinitions = createPlatformAgentRegistry();
+	const moduleCompositions = composeModuleServer({
+		environment: process.env,
+		workspaceRoot,
+		auth: authRuntime,
+		settings,
+		agentTools: createPlatformToolRegistry(),
+		agentDefinitions,
+		capabilities: createPlatformCapabilityRegistry(),
+		dataClasses,
+		databases,
+		storage,
+		/* The relay auth.core resolves per message from its stored settings, falling
 	   back to the environment port above, so every module of the installation
 	   sends through the same one. */
-	mail: authRuntime.mail,
-	/* Rebound to the composing module by the generated composition; this binding
+		mail: authRuntime.mail,
+		/* Rebound to the composing module by the generated composition; this binding
 	   is what a series the platform itself records would carry. */
-	metrics: createModuleMetrics('platform'),
-	tracer: serverTracer(),
-});
-for (const composition of moduleCompositions) {
-	if (composition.settings) settings.declare(composition.settings);
-}
-agentDefinitions.seal();
-/* Sealed once every composition has run and before any start hook reads the
+		metrics: createModuleMetrics('platform'),
+		tracer: serverTracer(),
+	});
+	for (const composition of moduleCompositions) {
+		if (composition.settings) settings.declare(composition.settings);
+	}
+	const ticker = workerTick
+		? createWorkerTicker(moduleCompositions, { windowMs: workerTick.windowMs })
+		: null;
+	agentDefinitions.seal();
+	/* Sealed once every composition has run and before any start hook reads the
    catalogue, so every reader sees the declarations the modules agreed on. */
-dataClasses.seal();
+	dataClasses.seal();
+
+	let stopping = false;
+	const shutdown = async () => {
+		if (stopping) return;
+		stopping = true;
+		await ticker?.close();
+		for (const composition of moduleCompositions) {
+			await composition.stop?.();
+			await composition.dispose?.();
+		}
+		await authRuntime.dispose();
+		await storage.dispose();
+		await databases.dispose();
+		/* 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
+	/* check() proves the runtime role holds neither SUPERUSER nor BYPASSRLS before
    any module reads a row. */
-if (!building) {
-	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?.();
-	for (const composition of moduleCompositions) composition.start?.();
-}
+	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?.();
+			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) => {
+				serverLogger().error('platform boot cleanup failed', {
+					module: 'platform',
+					err: cleanupError,
+				});
+			});
+			throw error;
+		}
+	}
 
-let stopping = false;
-const shutdown = async () => {
-	if (stopping) return;
-	stopping = true;
-	for (const composition of moduleCompositions) {
-		await composition.stop?.();
-		await composition.dispose?.();
+	// Bundling needs route declarations without background work or retained leases.
+	if (building) {
+		await shutdown();
+	} else {
+		process.once('SIGINT', () => void shutdown());
+		process.once('SIGTERM', () => void shutdown());
 	}
-	await authRuntime.dispose();
-	await storage.dispose();
-	await databases.dispose();
-	/* Last, so the spans and error reports this process queued while it stopped
-	   still leave with it. */
-	await observability.dispose();
-};
-// Bundling needs route declarations without background work or retained leases.
-if (building) {
-	await shutdown();
-} else {
-	process.once('SIGINT', () => void shutdown());
-	process.once('SIGTERM', () => void shutdown());
-}
 
-export default defineConfig({
-	middlewares: [
-		/* Ahead of the authentication: a cross-origin preflight carries no
+	return defineConfig({
+		middlewares: [
+			/* Ahead of the authentication: a cross-origin preflight carries no
 		   credential and has to be answered before anything asks for one. The
 		   origins come from the API tokens this workspace issued. */
-		createCorsMiddleware({
-			allowOrigin: (origin) => authRuntime.apiOriginAllowed(origin),
-		}),
-		authRuntime.middleware,
-	],
-	router: {
-		routes: checkedRoutes([
-			...createApplicationRoutes({
-				path: configuredApplicationPath,
-				entry: SHELL,
-				publicRoot: moduleWebMounts.some((site) => site.path === '/'),
+			createCorsMiddleware({
+				allowOrigin: (origin) => authRuntime.apiOriginAllowed(origin),
 			}),
-			healthEndpoint.serverRoute,
-			createReadinessEndpoint(databases).serverRoute,
-			...createMetricsRoutes({ environment: process.env }),
-			/* Describes every operation the presented credential may call, built
+			...(firstRun ? [firstRun.middleware] : []),
+			authRuntime.middleware,
+		],
+		router: {
+			routes: checkedRoutes([
+				...createApplicationRoutes({
+					path: configuredApplicationPath,
+					entry: SHELL,
+					publicRoot: moduleWebMounts.some((site) => site.path === '/'),
+				}),
+				healthEndpoint.serverRoute,
+				createReadinessEndpoint(databases).serverRoute,
+				...(ticker && workerTick
+					? [createWorkerTickEndpoint(ticker, workerTick).serverRoute]
+					: []),
+				...createMetricsRoutes({ environment: process.env }),
+				/* Describes every operation the presented credential may call, built
 			   from the endpoints this application composed. */
-			...createOpenApiRoutes({
-				resolveIdentity: endpointIdentityFromContext,
-				publicBaseUrl: authRuntime.publicBaseUrl,
-			}),
-			...createStorageRoutes({
-				storage,
-				keyring: storageKeyring,
-				environment: process.env,
-			}),
-			...createAuthRoutes(authRuntime),
-			...moduleCompositions.flatMap((composition) => composition.routes),
-			...createModuleWebRoutes({
-				modules: moduleCompositions,
-				mounts: moduleWebMounts,
-				applicationPath: configuredApplicationPath,
-				/* A build composes with NODE_ENV forced to development, so the flag
+				...createOpenApiRoutes({
+					resolveIdentity: endpointIdentityFromContext,
+					publicBaseUrl: authRuntime.publicBaseUrl,
+				}),
+				...createStorageRoutes({
+					storage,
+					keyring: storageKeyring,
+					environment: process.env,
+				}),
+				...createAuthRoutes(authRuntime),
+				...(firstRun?.routes ?? []),
+				...moduleCompositions.flatMap((composition) => composition.routes),
+				...createModuleWebRoutes({
+					modules: moduleCompositions,
+					mounts: moduleWebMounts,
+					applicationPath: configuredApplicationPath,
+					/* A build composes with NODE_ENV forced to development, so the flag
 				   asks for both: only a development server serves a page whose
 				   stylesheets arrive after its markup. */
-				development: !building && process.env.NODE_ENV !== 'production',
-				resolveIdentity: async (context) => {
-					const principal = principalFromContext(context);
-					if (!principal) return null;
-					/* The /api gate does not reach these pages, and a member who
+					development: !building && process.env.NODE_ENV !== 'production',
+					resolveIdentity: async (context) => {
+						const principal = principalFromContext(context);
+						if (!principal) return null;
+						/* The /api gate does not reach these pages, and a member who
 					   still owes enrolment must not read workspace data from one.
 					   Machine credentials cannot enrol and stay exempt there too. */
-					if (
-						!isTokenPrincipal(context) &&
-						!(await mfaEnrolmentSatisfied(authRuntime, principal))
-					) {
-						return null;
-					}
-					return {
-						subjectId: principal.accountId,
-						tenantId: principal.tenantId,
-						permissions: new Set(principal.scopes),
-					};
-				},
-			}),
-		]),
-	},
-});
+						if (
+							!isTokenPrincipal(context) &&
+							!(await mfaEnrolmentSatisfied(authRuntime, principal))
+						) {
+							return null;
+						}
+						return {
+							subjectId: principal.accountId,
+							tenantId: principal.tenantId,
+							permissions: new Set(principal.scopes),
+						};
+					},
+				}),
+			]),
+		},
+	});
+}
+
+export default await createPlatformConfig();

package/template/default/platform/package.json

@@ -11,14 +11,14 @@
 	},
 	"dependencies": {
 		"@app/module-example": "workspace:*",
-		"@octanejs/seo": "0.0.38",
-		"@octanejs/vite-plugin": "0.1.51",
-		"octane": "0.1.51",
+		"@octanejs/seo": "0.0.46",
+		"@octanejs/vite-plugin": "0.2.1",
+		"octane": "0.9.1",
 		"pg": "8.23.0",
-		"@flowdular/sdk": "0.5.1"
+		"@flowdular/sdk": "0.6.0"
 	},
 	"devDependencies": {
-		"@octanejs/app-core": "0.0.47",
+		"@octanejs/app-core": "0.1.1",
 		"@tsrx/typescript-plugin": "0.3.120",
 		"@types/node": "24.13.3",
 		"@types/pg": "8.23.1",

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

@@ -0,0 +1,56 @@
+import { randomBytes } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const stateDirectory = mkdtempSync(join(tmpdir(), 'flowdular-build-'));
+const buildSecret = () => randomBytes(32).toString('base64');
+
+/* Vite clears its output trees, but can leave hidden runtime state at the
+   dist root. A prior preview must never become part of the next bundle. */
+rmSync(join(import.meta.dirname, '..', 'dist'), {
+	recursive: true,
+	force: true,
+});
+
+/* The Octane plugin evaluates the server composition while bundling it. Give
+   that build-time process isolated state and ephemeral keys, without using deployment database settings or encryption keys. The emitted server still reads its real
+   production environment when it starts. */
+const environment = {
+	...process.env,
+	/* A production bundle is evaluated while it is built, but the build must not
+	   connect to the deployment database. The embedded engine writes into the
+	   throwaway state directory below; runtime still reads its real adapter. */
+	FD_ENV: 'development',
+	FD_INTERNAL_BUILD: 'true',
+	/* The bundler evaluates the server composition. It must not open a trace or
+	   error egress to the deployment's collector while building. */
+	FD_TRACE_EXPORTER: 'none',
+	FD_ERROR_SINK: 'none',
+	FD_DATABASE_ADAPTER: 'pglite',
+	FD_DATABASE_PGLITE_DIRECTORY: join(stateDirectory, 'pglite'),
+	FD_AGENT_CREDENTIAL_KEY: buildSecret(),
+	FD_AGENT_RUN_GRANT_KEY: buildSecret(),
+	FD_APPROVAL_GRANT_KEY: buildSecret(),
+	FD_AUTOMATIONS_CREDENTIAL_KEY: buildSecret(),
+	FD_NOTIFICATIONS_SECRET_KEY: buildSecret(),
+	FD_WORKFLOWS_PAYLOAD_KEY: buildSecret(),
+	FD_WORKFLOWS_CURSOR_KEY: buildSecret(),
+	FD_STORAGE_ADAPTER: 'local',
+	FD_STORAGE_LOCAL_DIRECTORY: join(stateDirectory, 'storage'),
+	FD_STORAGE_ENCRYPTION_KEY: buildSecret(),
+	FD_CONNECTORS_SECRET_KEY: buildSecret(),
+	FD_AUDIT_ANCHOR_KEY: buildSecret(),
+};
+
+try {
+	const result = spawnSync('vite', ['build'], {
+		env: environment,
+		stdio: 'inherit',
+	});
+	if (result.error) throw result.error;
+	process.exitCode = result.status ?? 1;
+} finally {
+	rmSync(stateDirectory, { recursive: true, force: true });
+}

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

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
 import { createServer } from 'vite';
 import {
 	createOctaneLogger,
@@ -18,6 +19,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') ||
@@ -59,6 +61,42 @@ printReady({
 	],
 });
 
+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;
+}
+
+const localUrl = server.resolvedUrls?.local?.[0];
+if (localUrl && !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.
+	}
+}
+
 /* 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);

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.
+	}
+}