@flowdular/sdk 0.1.0

package/packages/sandbox/vite.config.ts

@@ -0,0 +1,133 @@
+import { flowdularEnvironment } from '@flowdular/sdk/kernel/runtime-config';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { octane } from '@octanejs/vite-plugin';
+import type { Plugin } from 'vite';
+import { defineConfig } from 'vite';
+import { sandboxDirectory } from './src/server/config.ts';
+import { findFlowdularWorkspace } from './src/server/workspace-root.ts';
+import { resolvePreviewModules } from './src/server/preview-modules.ts';
+import type { SandboxSession } from './src/server/sessions.ts';
+
+Object.assign(process.env, flowdularEnvironment(process.env));
+
+const appRoot = dirname(fileURLToPath(import.meta.url));
+const workspace = await findFlowdularWorkspace(
+	process.env.FD_SANDBOX_WORKSPACE ?? process.cwd(),
+);
+
+const PREVIEW_MODULE =
+	/^\/preview-module\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/([a-z][a-z0-9-]*)\/(.+)$/;
+
+/* The preview imports draft sources by session and module directory. This
+   plugin maps that URL onto the session workspace, so the browser never learns
+   where the workspace lives on disk and cannot ask for anything outside a
+   session's module directory. */
+function previewModules(workspaceRoot: string): Plugin {
+	return {
+		name: 'flowdular-preview-modules',
+		enforce: 'pre',
+		async resolveId(source) {
+			const support =
+				/^\/preview-support\/([0-9a-f-]{36})\/([a-z][a-z0-9-]*)\/(.+)$/.exec(
+					source,
+				);
+			if (support) {
+				const [, sessionId, directory, rest] = support;
+				if (rest!.split('/').some((part) => part === '..' || !part))
+					return null;
+				try {
+					const session = JSON.parse(
+						readFileSync(
+							join(
+								sandboxDirectory(workspaceRoot),
+								'sessions',
+								sessionId!,
+								'session.json',
+							),
+							'utf8',
+						),
+					) as SandboxSession;
+					const selected = (
+						await resolvePreviewModules(workspaceRoot, session)
+					).find((module) => module.support && module.directory === directory);
+					if (!selected) return null;
+					const file = join(selected.path, rest!);
+					return existsSync(file) ? file : null;
+				} catch {
+					return null;
+				}
+			}
+			const match = PREVIEW_MODULE.exec(source);
+			if (!match) return null;
+			const [, sessionId, directory, rest] = match;
+			if (rest!.split('/').some((segment) => segment === '..' || !segment)) {
+				return null;
+			}
+			const sessionRoot = join(
+				sandboxDirectory(workspaceRoot),
+				'sessions',
+				sessionId!,
+			);
+			let modules: readonly { readonly directory: string }[] = [];
+			try {
+				const record = JSON.parse(
+					readFileSync(join(sessionRoot, 'session.json'), 'utf8'),
+				) as {
+					modules?: readonly { readonly directory: string }[];
+					moduleSuffix?: string;
+				};
+				modules =
+					record.modules ??
+					(record.moduleSuffix ? [{ directory: record.moduleSuffix }] : []);
+			} catch {
+				return null;
+			}
+			if (!modules.some((module) => module.directory === directory)) {
+				return null;
+			}
+			const file = join(sessionRoot, 'workspace', 'modules', directory!, rest!);
+			return existsSync(file) ? file : null;
+		},
+	};
+}
+
+const config = {
+	root: appRoot,
+	plugins: [previewModules(workspace.root), octane()],
+	resolve: {
+		/* Draft module code is loaded from a session workspace outside this app.
+		   It resolves the workspace packages through the node_modules link the
+		   session gets, and these must stay single instances or the preview would
+		   run on a second runtime. */
+		dedupe: [
+			'octane',
+			'segment-state',
+			'@flowdular/sdk/client',
+			'@flowdular/sdk/ui',
+			'@flowdular/sdk/server',
+			'@flowdular/sdk/contracts',
+		],
+		extensions: ['.tsrx', '.ts', '.tsx', '.mjs', '.js', '.jsx', '.json'],
+	},
+	build: { target: 'esnext' },
+	/* Suites here boot the embedded PostgreSQL, which costs well past the 5s
+	   vitest default under a full workspace run. Vitest reads this file, so the
+	   timeouts live here rather than in a vitest.config.ts that would shadow it
+	   and take the preview plugins with it. */
+	test: { testTimeout: 30_000, hookTimeout: 30_000 },
+	server: {
+		host: '127.0.0.1',
+		port: 4320,
+		strictPort: true,
+		/* Draft module files change on every agent turn and are served from
+		   outside this app's root. The preview reloads itself instead, and a Vite
+		   overlay must never cover a module someone is reviewing. */
+		hmr: { overlay: false },
+		fs: { allow: [appRoot, workspace.root] },
+		watch: { ignored: ['**/.flowdular/data/**', '**/.coreloom/data/**'] },
+	},
+} satisfies import('vitest/config').UserWorkspaceConfig;
+
+export default defineConfig(config);

package/packages/server/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@flowdular/server",
+	"version": "0.1.0",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit -p tsconfig.json",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@octanejs/app-core": "0.0.47",
+		"@flowdular/contracts": "workspace:*",
+		"@flowdular/kernel": "workspace:*",
+		"@flowdular/database": "workspace:*"
+	},
+	"devDependencies": {
+		"typescript": "5.9.3",
+		"vitest": "4.1.10",
+		"@types/node": "24.13.3"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Flowdular/flowdular.git",
+		"directory": "packages/server"
+	},
+	"files": [
+		"src",
+		"schemas",
+		"dist",
+		"bin",
+		"public",
+		"module.json",
+		"migrations",
+		"translations",
+		"spec",
+		"README.md",
+		"LICENSE"
+	],
+	"private": true
+}

package/packages/server/src/application-routes.ts

@@ -0,0 +1,21 @@
+import { RenderRoute, ServerRoute, type Route, type RenderRouteEntry } from '@octanejs/app-core';
+
+export function validateApplicationPath(path: string): string {
+	if (!/^\/[a-z][a-z0-9-]*$/.test(path) || ['auth','api','sites','sign-in','sign-up','forgot-password','reset-password','accept-invitation'].includes(path.slice(1))) throw new Error('Invalid application path.');
+	return path;
+}
+
+export function createApplicationRoutes(options: { readonly path: string; readonly entry: RenderRouteEntry; readonly publicRoot: boolean }): readonly Route[] {
+	const base = validateApplicationPath(options.path);
+	const paths = [
+		'/auth', '/auth/login', '/auth/register', '/auth/forgot-password', '/auth/reset-password', '/auth/accept-invitation', '/auth/mfa',
+		'/sign-in','/sign-up','/forgot-password','/reset-password','/accept-invitation',
+		base, base+'/:workspace', base+'/:workspace/:view',
+		...(!options.publicRoot ? ['/', '/:workspace', '/:workspace/:view'] : []),
+	];
+	const routes: Route[] = paths.map(path => new RenderRoute({path,entry:options.entry}));
+	if (base !== '/app') {
+		for (const path of ['/app','/app/*legacyPath']) routes.push(new ServerRoute({path,methods:['GET','HEAD'],handler: context => new Response(null,{status:308,headers:{location:base+context.url.pathname.slice(4)+context.url.search,'cache-control':'no-store'}})}));
+	}
+	return routes;
+}

package/packages/server/src/composition.ts

@@ -0,0 +1,48 @@
+import type { ServerRoute } from '@octanejs/app-core';
+import type { ModuleWebSurface } from '@flowdular/sdk/contracts';
+import type { DatabaseProvider } from '@flowdular/sdk/database';
+import type {
+	ModuleSettingsDeclaration,
+	ModuleSettingsRuntime,
+	PlatformAgentRegistry,
+	PlatformCapabilityRegistry,
+	PlatformToolRegistry,
+} from '@flowdular/sdk/kernel';
+
+/* Contract for the generated platform composition: every enabled module with
+   a server surface exposes `createServerComposition` from its `/platform`
+   entry, and "flowdular module sync" wires the enabled ones together so agents
+   never edit octane.config.ts by hand. */
+
+export interface ModuleServerContext<Auth> {
+	readonly environment: NodeJS.ProcessEnv;
+	readonly workspaceRoot: string;
+	readonly auth: Auth;
+	/** Live, tenant-scoped module settings; read at request time, never at boot. */
+	readonly settings: ModuleSettingsRuntime;
+	/** Tools a module offers to agent runs; agents.core reads it in start(). */
+	readonly agentTools: PlatformToolRegistry;
+	/** Business agent definitions modules register before the platform starts. */
+	readonly agentDefinitions: PlatformAgentRegistry;
+	/** Typed public services shared by composed modules without database access. */
+	readonly capabilities: PlatformCapabilityRegistry;
+	/** Platform-owned database leases. Modules never receive a DSN or pool. */
+	readonly databases: DatabaseProvider;
+}
+
+export interface ModuleServerComposition {
+	/** Set by the CLI-generated composition, never inferred from a request. */
+	readonly moduleId?: string;
+	readonly web?: readonly ModuleWebSurface[];
+	readonly routes: readonly ServerRoute[];
+	/** Declared settings; the platform registers them after composing. */
+	readonly settings?: ModuleSettingsDeclaration;
+	/** Read-only validation performed before the healthy generation is retired. */
+	readonly prepare?: () => void | Promise<void>;
+	/** Runs after every module composed and declared its settings. */
+	readonly start?: () => void;
+	/** Stops and drains background work before any module resource is disposed. */
+	readonly stop?: () => void | Promise<void>;
+	/** Releases repositories, workers, timers, and listeners owned by the module. */
+	readonly dispose?: () => void | Promise<void>;
+}

package/packages/server/src/endpoint.ts

@@ -0,0 +1,142 @@
+import { ServerRoute, type Context } from '@octanejs/app-core';
+
+export interface EndpointIdentity {
+	readonly subjectId: string;
+	readonly permissions: ReadonlySet<string>;
+}
+
+export interface EndpointExecutionContext {
+	readonly requestId: string;
+	readonly identity: EndpointIdentity | null;
+	readonly octane: Context;
+}
+
+type EndpointHandler = (
+	context: EndpointExecutionContext,
+) => Response | Promise<Response>;
+
+interface EndpointBase {
+	readonly id: string;
+	readonly path: string;
+	readonly methods: readonly string[];
+	readonly handler: EndpointHandler;
+}
+
+interface PublicEndpoint extends EndpointBase {
+	readonly access: { readonly kind: 'public' };
+}
+
+interface ProtectedEndpoint extends EndpointBase {
+	readonly access: { readonly kind: 'permission'; readonly permission: string };
+	readonly resolveIdentity: (
+		context: Context,
+	) => EndpointIdentity | null | Promise<EndpointIdentity | null>;
+}
+
+export type EndpointDefinition = PublicEndpoint | ProtectedEndpoint;
+
+export interface DefinedEndpoint {
+	readonly id: string;
+	readonly access: EndpointDefinition['access'];
+	readonly serverRoute: ServerRoute;
+}
+
+function problem(
+	status: number,
+	code: string,
+	message: string,
+	requestId: string,
+): Response {
+	return Response.json(
+		{ error: { code, message }, requestId },
+		{ status, headers: { 'cache-control': 'no-store' } },
+	);
+}
+
+function requestIdOf(context: Context): string {
+	const header = context.request.headers.get('x-request-id');
+	return header && header.length <= 128 ? header : crypto.randomUUID();
+}
+
+export function defineEndpoint(
+	definition: EndpointDefinition,
+): DefinedEndpoint {
+	if (
+		!definition.access ||
+		(definition.access.kind !== 'public' &&
+			definition.access.kind !== 'permission') ||
+		(definition.access.kind === 'permission' &&
+			(!definition.access.permission?.trim() ||
+				!('resolveIdentity' in definition) ||
+				typeof definition.resolveIdentity !== 'function')) ||
+		(definition.access.kind === 'public' && 'resolveIdentity' in definition)
+	) {
+		throw new Error(
+			`Endpoint "${definition.id}" has an invalid access policy.`,
+		);
+	}
+	if (definition.methods.length === 0) {
+		throw new Error(
+			`Endpoint "${definition.id}" must declare at least one HTTP method.`,
+		);
+	}
+
+	const serverRoute = new ServerRoute({
+		path: definition.path,
+		methods: definition.methods.map((method) => method.toUpperCase()),
+		handler: async (context) => {
+			const requestId = requestIdOf(context);
+			let identity: EndpointIdentity | null = null;
+			try {
+				if (
+					definition.access.kind === 'permission' &&
+					'resolveIdentity' in definition
+				) {
+					identity = await definition.resolveIdentity(context);
+					if (!identity)
+						return problem(
+							401,
+							'UNAUTHENTICATED',
+							'Authentication is required.',
+							requestId,
+						);
+					if (!identity.permissions.has(definition.access.permission)) {
+						return problem(
+							403,
+							'FORBIDDEN',
+							'The required permission was not granted.',
+							requestId,
+						);
+					}
+				}
+
+				const response = await definition.handler({
+					requestId,
+					identity,
+					octane: context,
+				});
+				response.headers.set('x-request-id', requestId);
+				return response;
+			} catch (error) {
+				/* An unexpected error may carry SQL parameters, provider responses, or
+				   credentials in its message and attached fields. The request id and
+				   endpoint identify the failure without sending that value to a logger. */
+				console.error(
+					`[${requestId}] endpoint ${definition.id} failed (${error instanceof Error ? 'Error' : 'non-error'})`,
+				);
+				return problem(
+					500,
+					'INTERNAL_ERROR',
+					'The request could not be completed.',
+					requestId,
+				);
+			}
+		},
+	});
+
+	return Object.freeze({
+		id: definition.id,
+		access: definition.access,
+		serverRoute,
+	});
+}

package/packages/server/src/http.ts

@@ -0,0 +1,128 @@
+export class HttpProblem extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly status: number,
+	) {
+		super(message);
+		this.name = 'HttpProblem';
+	}
+}
+
+export function jsonResponse(body: unknown, status = 200): Response {
+	return Response.json(body, {
+		status,
+		headers: { 'cache-control': 'no-store' },
+	});
+}
+
+export function problemResponse(
+	error: unknown,
+	fallbackMessage = 'The operation failed.',
+): Response {
+	if (error instanceof HttpProblem) {
+		return jsonResponse(
+			{ error: { code: error.code, message: error.message } },
+			error.status,
+		);
+	}
+	return jsonResponse(
+		{ error: { code: 'INTERNAL_ERROR', message: fallbackMessage } },
+		500,
+	);
+}
+
+export async function readJsonObject(
+	request: Request,
+	maxBytes = 16_384,
+): Promise<Record<string, unknown>> {
+	if (
+		!(request.headers.get('content-type') ?? '')
+			.toLowerCase()
+			.startsWith('application/json')
+	) {
+		throw new HttpProblem(
+			'CONTENT_TYPE_REQUIRED',
+			'Expected application/json.',
+			415,
+		);
+	}
+	const declaredLength = Number(request.headers.get('content-length') ?? 0);
+	if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+		throw new HttpProblem(
+			'PAYLOAD_TOO_LARGE',
+			'The request body is too large.',
+			413,
+		);
+	}
+	const text = await request.text();
+	if (new TextEncoder().encode(text).byteLength > maxBytes) {
+		throw new HttpProblem(
+			'PAYLOAD_TOO_LARGE',
+			'The request body is too large.',
+			413,
+		);
+	}
+	let value: unknown;
+	try {
+		value = JSON.parse(text) as unknown;
+	} catch {
+		throw new HttpProblem(
+			'INVALID_JSON',
+			'The request body is not valid JSON.',
+			400,
+		);
+	}
+	if (!value || typeof value !== 'object' || Array.isArray(value)) {
+		throw new HttpProblem('INVALID_INPUT', 'Expected a JSON object.', 400);
+	}
+	return value as Record<string, unknown>;
+}
+
+export function requiredString(
+	value: Record<string, unknown>,
+	key: string,
+	options: { readonly min?: number; readonly max?: number } = {},
+): string {
+	const result = value[key];
+	if (typeof result !== 'string') {
+		throw new HttpProblem('INVALID_INPUT', `${key} must be a string.`, 400);
+	}
+	const normalized = result.trim();
+	if (normalized.length < (options.min ?? 1)) {
+		throw new HttpProblem('INVALID_INPUT', `${key} is too short.`, 400);
+	}
+	if (normalized.length > (options.max ?? Number.MAX_SAFE_INTEGER)) {
+		throw new HttpProblem('INVALID_INPUT', `${key} is too long.`, 400);
+	}
+	return normalized;
+}
+
+export function optionalString(
+	value: Record<string, unknown>,
+	key: string,
+	max: number,
+): string | null {
+	const result = value[key];
+	if (result === undefined || result === null || result === '') return null;
+	return requiredString(value, key, { max });
+}
+
+export function requiredInteger(
+	value: Record<string, unknown>,
+	key: string,
+	options: { readonly min?: number; readonly max?: number } = {},
+): number {
+	const result = value[key];
+	if (!Number.isSafeInteger(result)) {
+		throw new HttpProblem('INVALID_INPUT', `${key} must be an integer.`, 400);
+	}
+	const integer = result as number;
+	if (integer < (options.min ?? Number.MIN_SAFE_INTEGER)) {
+		throw new HttpProblem('INVALID_INPUT', `${key} is too small.`, 400);
+	}
+	if (integer > (options.max ?? Number.MAX_SAFE_INTEGER)) {
+		throw new HttpProblem('INVALID_INPUT', `${key} is too large.`, 400);
+	}
+	return integer;
+}

package/packages/server/src/index.ts

@@ -0,0 +1,46 @@
+export { defineEndpoint } from './endpoint.ts';
+export { createApplicationRoutes, validateApplicationPath } from './application-routes.ts';
+export { trackResponseBody } from './response-lifetime.ts';
+export {
+	assertRouteConflicts,
+	createModuleWebRoutes,
+	defineWebSurface,
+	validateWebMounts,
+} from './web.ts';
+export type {
+	WebMount,
+	WebIdentity,
+	WebAccess,
+	WebJson,
+	WebPage,
+	WebPageContext,
+	ModuleWebSurface,
+	WebModuleComposition,
+} from './web.ts';
+export type {
+	DefinedEndpoint,
+	EndpointDefinition,
+	EndpointExecutionContext,
+	EndpointIdentity,
+} from './endpoint.ts';
+export {
+	HttpProblem,
+	jsonResponse,
+	optionalString,
+	problemResponse,
+	readJsonObject,
+	requiredInteger,
+	requiredString,
+} from './http.ts';
+export {
+	createSecurityHeadersMiddleware,
+	DEVELOPMENT_CONTENT_SECURITY_POLICY,
+	PRODUCTION_CONTENT_SECURITY_POLICY,
+	securityHeaders,
+} from './security-headers.ts';
+export type { SecurityHeadersOptions } from './security-headers.ts';
+
+export type {
+	ModuleServerContext,
+	ModuleServerComposition,
+} from './composition.ts';

package/packages/server/src/response-lifetime.ts

@@ -0,0 +1,56 @@
+/** Own resources until the consumer finishes or cancels the response body. */
+export function trackResponseBody(
+	response: Response,
+	release: () => void,
+	signal?: AbortSignal,
+): Response {
+	if (!response.body) {
+		release();
+		return response;
+	}
+	const reader = response.body.getReader();
+	let finished = false;
+	const finish = () => {
+		if (finished) return;
+		finished = true;
+		signal?.removeEventListener('abort', abort);
+		release();
+	};
+	const abort = () => {
+		void reader
+			.cancel(signal?.reason)
+			.catch(() => undefined)
+			.finally(finish);
+	};
+	signal?.addEventListener('abort', abort, { once: true });
+	if (signal?.aborted) abort();
+	const body = new ReadableStream<Uint8Array>(
+		{
+			async pull(controller) {
+				try {
+					const chunk = await reader.read();
+					if (chunk.done) {
+						controller.close();
+						finish();
+					} else controller.enqueue(chunk.value);
+				} catch (error) {
+					controller.error(error);
+					finish();
+				}
+			},
+			async cancel(reason) {
+				try {
+					await reader.cancel(reason);
+				} finally {
+					finish();
+				}
+			},
+		},
+		{ highWaterMark: 0 },
+	);
+	return new Response(body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers,
+	});
+}