create-flowdular 0.5.1 → 0.6.1

package/template/default/platform/src/server/setup/environment.ts

@@ -0,0 +1,154 @@
+import { randomBytes } from 'node:crypto';
+import {
+	lstatSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs';
+import { resolve } from 'node:path';
+
+/* Writing configuration is a real capability and a deployment may withhold it
+   on purpose: infra/docker/compose.yaml sets read_only: true. A refused write
+   is reported as a refused write, and the operator gets the exact block to
+   paste into their orchestrator instead of a success that did not happen. */
+
+export type EnvironmentWriteStatus =
+	| 'failed'
+	| 'read-only'
+	| 'unchanged'
+	| 'written';
+
+export interface EnvironmentWriteResult {
+	readonly status: EnvironmentWriteStatus;
+	readonly path: string;
+	/** Keys this run added to the file. */
+	readonly added: readonly string[];
+	/** Keys the file already set. An existing value is never replaced. */
+	readonly kept: readonly string[];
+	/** The block to paste when this deployment cannot persist it itself. */
+	readonly block: string;
+}
+
+const BARE_VALUE = /^[A-Za-z0-9_@%:/.,+~=?&[\]{}!*()$^-]+$/;
+const KEY_LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+
+function quote(value: string): string {
+	if (BARE_VALUE.test(value)) return value;
+	if (value.includes('"') || value.includes('\\')) {
+		throw new Error(
+			'A value containing a quote or a backslash cannot be stored in a .env file.',
+		);
+	}
+	return `"${value}"`;
+}
+
+function existingKeys(contents: string): ReadonlySet<string> {
+	const keys = new Set<string>();
+	for (const line of contents.split('\n')) {
+		const match = KEY_LINE.exec(line);
+		if (match?.[1]) keys.add(match[1]);
+	}
+	return keys;
+}
+
+export function renderEnvironmentBlock(
+	values: Readonly<Record<string, string>>,
+): string {
+	return Object.entries(values)
+		.map(([key, value]) => `${key}=${quote(value)}`)
+		.join('\n');
+}
+
+function isReadOnly(error: unknown): boolean {
+	const code =
+		typeof error === 'object' && error !== null && 'code' in error
+			? String((error as { code: unknown }).code)
+			: '';
+	return code === 'EROFS' || code === 'EACCES' || code === 'EPERM';
+}
+
+/**
+ * Adds the keys this deployment is missing to `<workspaceRoot>/.env`, owner
+ * readable only. A key the file already sets is left exactly as it is, so a
+ * second run can never quietly re-point a database that is already configured.
+ */
+export function writeEnvironmentFile(
+	workspaceRoot: string,
+	values: Readonly<Record<string, string>>,
+): EnvironmentWriteResult {
+	const path = resolve(workspaceRoot, '.env');
+	let block: string;
+	try {
+		block = renderEnvironmentBlock(values);
+	} catch {
+		/* A value a .env file cannot represent unambiguously. Reporting the keys
+		   is the whole answer; writing a file that parses back differently is
+		   the one outcome worse than not writing at all. */
+		return {
+			status: 'failed',
+			path,
+			added: [],
+			kept: [],
+			block: Object.keys(values).join('\n'),
+		};
+	}
+	let contents = '';
+	try {
+		const stat = lstatSync(path);
+		if (!stat.isFile() || stat.isSymbolicLink()) {
+			return { status: 'failed', path, added: [], kept: [], block };
+		}
+		contents = readFileSync(path, 'utf8');
+	} catch (error) {
+		/* Only a missing file may be created. An unreadable file must not be
+		   treated as empty and replaced by the atomic rename below. */
+		if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+			return {
+				status: isReadOnly(error) ? 'read-only' : 'failed',
+				path,
+				added: [],
+				kept: [],
+				block,
+			};
+		}
+	}
+	const present = existingKeys(contents);
+	const added: string[] = [];
+	const kept: string[] = [];
+	for (const key of Object.keys(values)) {
+		if (present.has(key)) kept.push(key);
+		else added.push(key);
+	}
+	if (added.length === 0) {
+		return { status: 'unchanged', path, added, kept, block };
+	}
+	const appended = added.map((key) => `${key}=${quote(values[key]!)}`);
+	const next = [
+		...(contents.length > 0 ? [contents.replace(/\n*$/, '\n')] : []),
+		'# Written by the Flowdular first-run setup.\n',
+		`${appended.join('\n')}\n`,
+	].join('');
+	/* A partial .env is worse than none, and a read-only mount must leave no
+	   trace at all, so the file appears only once it is complete. */
+	const temporary = `${path}.${randomBytes(6).toString('hex')}.tmp`;
+	try {
+		writeFileSync(temporary, next, { encoding: 'utf8', mode: 0o600 });
+		renameSync(temporary, path);
+	} catch (error) {
+		try {
+			rmSync(temporary, { force: true });
+		} catch {
+			/* The temporary file was never created on a filesystem that refused
+			   the write, so there is nothing to clean up. */
+		}
+		return {
+			status: isReadOnly(error) ? 'read-only' : 'failed',
+			path,
+			added: [],
+			kept,
+			block,
+		};
+	}
+	return { status: 'written', path, added, kept, block };
+}

package/template/default/platform/src/server/setup/gate.ts

@@ -0,0 +1,84 @@
+import { ServerRoute, type Context, type Middleware } from '@octanejs/app-core';
+
+export interface FirstRunGate {
+	/** Runs ahead of authentication. Until a workspace exists it answers every
+	 *  request itself, except the pass-through paths. */
+	readonly middleware: Middleware;
+	/** Global middleware runs only for a matched route, so /setup needs one. */
+	readonly routes: readonly ServerRoute[];
+}
+
+export interface FirstRunGateOptions {
+	readonly applicationPath: string;
+	/** Served normally before the first workspace exists, such as /api/ready. */
+	readonly passThrough: readonly string[];
+	readonly workspaceExists: () => Promise<boolean>;
+	/** Builds the /setup handler. `claimed` opens this instance at once. */
+	readonly setup: (
+		claimed: () => void,
+	) => (context: Context) => Promise<Response>;
+}
+
+function redirect(location: string): Response {
+	return new Response(null, {
+		status: 303,
+		headers: { location, 'cache-control': 'no-store' },
+	});
+}
+
+export function createFirstRunGate(options: FirstRunGateOptions): FirstRunGate {
+	let open = false;
+	let checking: Promise<boolean> | null = null;
+	const setup = options.setup(() => {
+		open = true;
+	});
+	/* Asked on every request until it first answers yes, so an instance that
+	   did not run setup itself opens on its next request after another did.
+	   Concurrent requests share one query; a failed one keeps the gate shut. */
+	const workspaceExists = (): Promise<boolean> =>
+		(checking ??= options.workspaceExists().then(
+			(exists) => {
+				checking = null;
+				if (exists) open = true;
+				return exists;
+			},
+			() => {
+				checking = null;
+				return false;
+			},
+		));
+	const middleware: Middleware = async (context, next) => {
+		if (open || (await workspaceExists())) return next();
+		const { pathname } = context.url;
+		if (pathname === '/setup') return setup(context);
+		if (options.passThrough.includes(pathname)) return next();
+		const method = context.request.method;
+		if (
+			(method === 'GET' || method === 'HEAD') &&
+			pathname !== '/api' &&
+			!pathname.startsWith('/api/')
+		) {
+			return redirect('/setup');
+		}
+		return Response.json(
+			{
+				error: {
+					code: 'PLATFORM_NOT_CONFIGURED',
+					message:
+						'Complete the first-run setup at /setup before using the platform.',
+				},
+			},
+			{ status: 503, headers: { 'cache-control': 'no-store' } },
+		);
+	};
+	return {
+		middleware,
+		routes: [
+			new ServerRoute({
+				path: '/setup',
+				methods: ['GET', 'POST'],
+				handler: () => redirect(options.applicationPath),
+			}),
+		],
+	};
+}

package/template/default/platform/src/server/setup/index.ts

@@ -0,0 +1,181 @@
+import process from 'node:process';
+import type { ServerRoute } from '@octanejs/app-core';
+import {
+	authRuntimeOptionsFromEnvironment,
+	createAuthRuntime,
+} from '@flowdular/sdk/modules/auth/server';
+import {
+	createPlatformDatabaseProvider,
+	databaseProviderConfigFromEnvironment,
+} from '../database.ts';
+import { createSetupAccess } from './access.ts';
+import { createSetupAdapters } from './adapters.ts';
+import { createFirstRunGate, type FirstRunGate } from './gate.ts';
+import { enabledDatabaseModules } from './modules.ts';
+import { createSetupHandler, createSetupRoutes } from './routes.ts';
+import { issueSetupToken } from './token.ts';
+
+export { clearSetupToken } from './token.ts';
+
+const FIRST_RUN_SYMBOL = Symbol.for('flowdular.platform.first-run-setup');
+
+export interface FirstRunSetup {
+	readonly routes: readonly ServerRoute[];
+	readonly token: string;
+	readonly tokenFile: string | null;
+}
+
+export interface FirstRunSetupOptions {
+	readonly environment: NodeJS.ProcessEnv;
+	readonly workspaceRoot: string;
+	readonly databasePreconfigured?: boolean;
+	readonly applicationPath?: string;
+	readonly webMountPaths?: readonly string[];
+	readonly log?: (message: string) => void;
+}
+
+/** A reachable, empty configured database still needs its first owner.
+ * Auth's normal migration path is used before the read, and an outage throws
+ * rather than accidentally opening setup against an existing installation.
+ */
+export async function configuredDatabaseNeedsFirstRun(
+	environment: NodeJS.ProcessEnv,
+	workspaceRoot: string,
+): Promise<boolean> {
+	const databases = createPlatformDatabaseProvider(
+		databaseProviderConfigFromEnvironment(environment, workspaceRoot),
+	);
+	try {
+		await databases.check();
+		const auth = createAuthRuntime({
+			...authRuntimeOptionsFromEnvironment(environment, workspaceRoot),
+			databases,
+		});
+		try {
+			return !(await (await auth.service()).hasAnyTenant());
+		} finally {
+			await auth.dispose();
+		}
+	} finally {
+		await databases.dispose();
+	}
+}
+
+type ProcessWithSetup = NodeJS.Process & {
+	[FIRST_RUN_SYMBOL]?: FirstRunSetup;
+};
+
+function origin(environment: NodeJS.ProcessEnv): string {
+	const configured = environment.FD_AUTH_PUBLIC_ORIGIN?.trim();
+	if (configured) return configured.replace(/\/+$/, '');
+	return `http://127.0.0.1:${environment.PORT?.trim() || '4310'}`;
+}
+
+/**
+ * The routes a deployment serves while it has no database. Held on the process
+ * so a development re-evaluation of the configuration keeps the token, the
+ * lockout counter, and the operator's half-finished session alive; a
+ * production process evaluates the configuration once, so this is a plain
+ * construction there.
+ */
+export function createFirstRunSetup(
+	options: FirstRunSetupOptions,
+): FirstRunSetup {
+	const owner = process as ProcessWithSetup;
+	const existing = owner[FIRST_RUN_SYMBOL];
+	if (existing) return existing;
+	const production = options.environment.NODE_ENV === 'production';
+	const issued = issueSetupToken({
+		workspaceRoot: options.workspaceRoot,
+		origin: origin(options.environment),
+	});
+	const adapters = createSetupAdapters({
+		workspaceRoot: options.workspaceRoot,
+		production,
+	});
+	const enabled = enabledDatabaseModules(options.workspaceRoot);
+	const setup: FirstRunSetup = {
+		token: issued.token,
+		tokenFile: issued.file,
+		routes: createSetupRoutes({
+			environment: options.environment,
+			databasePreconfigured: options.databasePreconfigured ?? false,
+			defaultApplicationPath: options.applicationPath ?? '/app',
+			webMountPaths: options.webMountPaths ?? [],
+			workspaceRoot: options.workspaceRoot,
+			adapters,
+			access: createSetupAccess(issued.token),
+			modules: enabled.modules,
+			modulesApproximated: enabled.approximated,
+			tokenFile: issued.file,
+			secureCookies:
+				options.environment.FD_AUTH_SECURE_COOKIE === 'false'
+					? false
+					: production,
+		}),
+	};
+	owner[FIRST_RUN_SYMBOL] = setup;
+	(options.log ?? console.log)(issued.banner);
+	return setup;
+}
+
+export interface InPlaceFirstRunOptions {
+	readonly environment: NodeJS.ProcessEnv;
+	readonly workspaceRoot: string;
+	readonly applicationPath: string;
+	readonly webMountPaths: readonly string[];
+	readonly passThrough: readonly string[];
+	readonly workspaceExists: () => Promise<boolean>;
+	readonly log?: (message: string) => void;
+}
+
+/**
+ * First run for a deployment that can neither restart itself nor write files,
+ * such as a Vercel Function: the composed application serves setup behind a
+ * gate until a workspace exists. The deploy command keeps the token and the
+ * deployment holds only its SHA-256, so nothing is issued or written here.
+ */
+export function createInPlaceFirstRun(
+	options: InPlaceFirstRunOptions,
+): FirstRunGate {
+	const digest = options.environment.FD_SETUP_TOKEN_SHA256?.trim();
+	if (!digest) {
+		throw new Error(
+			'The database has no workspace yet and FD_SETUP_TOKEN_SHA256 is not set. Run flowdular deploy start vercel --apply, which sets it and prints the setup token.',
+		);
+	}
+	const access = createSetupAccess({ sha256: digest });
+	const production = options.environment.NODE_ENV === 'production';
+	const adapters = createSetupAdapters({
+		workspaceRoot: options.workspaceRoot,
+		production,
+	});
+	const enabled = enabledDatabaseModules(options.workspaceRoot);
+	const gate = createFirstRunGate({
+		applicationPath: options.applicationPath,
+		passThrough: options.passThrough,
+		workspaceExists: options.workspaceExists,
+		setup: (claimed) =>
+			createSetupHandler({
+				environment: options.environment,
+				databasePreconfigured: true,
+				defaultApplicationPath: options.applicationPath,
+				webMountPaths: options.webMountPaths,
+				workspaceRoot: options.workspaceRoot,
+				adapters,
+				access,
+				modules: enabled.modules,
+				modulesApproximated: enabled.approximated,
+				tokenFile: null,
+				secureCookies:
+					options.environment.FD_AUTH_SECURE_COOKIE === 'false'
+						? false
+						: production,
+				inPlace: { onClaimed: claimed },
+			}),
+	});
+	(options.log ?? console.log)(
+		'No workspace exists yet. Open /setup and enter the setup token the deploy command printed.',
+	);
+	return gate;
+}

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

@@ -0,0 +1,119 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+	DATABASE_CAPABILITY_IDS,
+	DATABASE_DIALECT_IDS,
+	type ModuleDatabaseRequirements,
+} from '@flowdular/sdk/database';
+import { findModuleManifests } from '@flowdular/sdk/kernel/module-manifests';
+import projectManifest from '../../../../flowdular.json';
+
+/**
+ * What every database-owning module in this repository asks its lease for. The
+ * module manifest carries no machine-readable database block yet, so the
+ * platform applies the strictest set any enabled module requests rather than
+ * guessing a looser one per module. The precise fix is a `database` block in
+ * packages/contracts/schemas/module.schema.json that each module fills in.
+ */
+export const PLATFORM_MODULE_DATABASE_REQUIREMENTS = Object.freeze({
+	dialectIds: Object.freeze([DATABASE_DIALECT_IDS.postgresql]),
+	capabilities: Object.freeze([
+		DATABASE_CAPABILITY_IDS.MIGRATION_LOCK,
+		DATABASE_CAPABILITY_IDS.SCHEMA_INTROSPECTION,
+		DATABASE_CAPABILITY_IDS.TRANSACTIONAL_DDL,
+		DATABASE_CAPABILITY_IDS.TRANSACTIONS,
+	]),
+});
+
+export interface EnabledDatabaseModules {
+	readonly modules: readonly ModuleDatabaseRequirements[];
+	/**
+	 * True when a module manifest could not be read, so the enabled module it
+	 * belongs to is treated as owning tenant-scoped tables. Over-approximating
+	 * keeps the check strict; the review screen says the list came from this
+	 * fallback.
+	 */
+	readonly approximated: boolean;
+}
+
+interface ModuleManifest {
+	readonly id?: unknown;
+	readonly capabilities?: unknown;
+	readonly tenancy?: unknown;
+}
+
+interface ProjectManifest {
+	readonly modules?: {
+		readonly roots?: unknown;
+		readonly enabled?: unknown;
+	};
+}
+
+function readJson<T>(path: string): T | null {
+	try {
+		return JSON.parse(readFileSync(path, 'utf8')) as T;
+	} catch {
+		return null;
+	}
+}
+
+function stringList(value: unknown): readonly string[] {
+	return Array.isArray(value)
+		? value.filter((entry): entry is string => typeof entry === 'string')
+		: [];
+}
+
+function requirements(
+	moduleId: string,
+	tenantOwned: boolean,
+): ModuleDatabaseRequirements {
+	return {
+		moduleId,
+		tenantOwned,
+		dialectIds: PLATFORM_MODULE_DATABASE_REQUIREMENTS.dialectIds,
+		capabilities: PLATFORM_MODULE_DATABASE_REQUIREMENTS.capabilities,
+	};
+}
+
+/**
+ * The enabled modules that own database tables, in `flowdular.json` order.
+ * Manifests are found where the CLI finds them, @flowdular/sdk included. A
+ * container image ships only `platform/dist`, so the enabled list falls back
+ * to the manifest bundled at build time and an enabled module whose manifest
+ * is not beside it is assumed to own tenant-scoped tables.
+ */
+export function enabledDatabaseModules(
+	workspaceRoot: string,
+): EnabledDatabaseModules {
+	const project =
+		readJson<ProjectManifest>(resolve(workspaceRoot, 'flowdular.json')) ??
+		(projectManifest as ProjectManifest);
+	const enabled = stringList(project.modules?.enabled);
+	if (enabled.length === 0) return { modules: [], approximated: false };
+	let paths: readonly string[] = [];
+	try {
+		paths = findModuleManifests(workspaceRoot, project.modules?.roots);
+	} catch {
+		/* Unreadable roots leave every module to the strict fallback below. */
+	}
+	const manifests = new Map<string, ModuleManifest>();
+	for (const path of paths) {
+		const manifest = readJson<ModuleManifest>(path);
+		if (typeof manifest?.id === 'string') {
+			manifests.set(manifest.id, manifest);
+		}
+	}
+	const modules: ModuleDatabaseRequirements[] = [];
+	let approximated = false;
+	for (const moduleId of enabled) {
+		const manifest = manifests.get(moduleId);
+		if (!manifest) {
+			modules.push(requirements(moduleId, true));
+			approximated = true;
+			continue;
+		}
+		if (!stringList(manifest.capabilities).includes('database')) continue;
+		modules.push(requirements(moduleId, manifest.tenancy === 'required'));
+	}
+	return { modules, approximated };
+}