@flowdular/sdk 0.3.1 → 0.3.2

package/modules/system/src/client/module-columns.tsrx

@@ -2,6 +2,22 @@ import { Tag, type TableColumn } from '@flowdular/sdk/ui';
 import { activeLocale, t } from '@flowdular/sdk/client';
 import type { ModuleCatalogEntry } from './api.ts';
 
+export function activationTone(
+	module: ModuleCatalogEntry,
+): 'success' | 'warning' | 'ink' | 'neutral' {
+	if (!module.enabled) return 'neutral';
+	if (!module.optional) return 'ink';
+	return module.active ? 'success' : 'warning';
+}
+
+export function activationLabel(module: ModuleCatalogEntry): string {
+	if (!module.enabled) return t('system.status.available');
+	if (!module.optional) return t('system.status.required');
+	return module.active
+		? t('system.status.active')
+		: t('system.status.inactive');
+}
+
 export function surfaces(module: ModuleCatalogEntry): string {
 	const parts = [
 		module.platform.server && 'server',
@@ -37,7 +53,7 @@ export function moduleColumns(): readonly TableColumn<ModuleCatalogEntry>[] {
 		{
 			key: 'platform',
 			header: t('system.table.platform'),
-			width: '30%',
+			width: '20%',
 			cell: (module) => <span class="ui-cell">
 				<span>{surfaces(module)}</span>
 				<small>{module.capabilities.join(', ')}</small>
@@ -52,15 +68,25 @@ export function moduleColumns(): readonly TableColumn<ModuleCatalogEntry>[] {
 				module.permissions.length,
 			),
 		},
+		{
+			key: 'dependents',
+			header: t('system.table.dependents'),
+			width: '14%',
+			cell: (module) => <span class="ui-cell">
+				<span>{new Intl.NumberFormat(activeLocale()).format(
+					module.dependents.length,
+				)}</span>
+				{module.dependents.length > 0
+					? <small class="ui-mono">{module.dependents.join(', ')}</small>
+					: null}
+			</span>,
+		},
 		{
 			key: 'status',
 			header: t('system.table.status'),
 			width: '14%',
-			cell: (module) => <Tag tone={module.enabled ? 'success' : 'neutral'} dot>
-				{module.enabled
-					? t('system.status.enabled')
-					: t('system.status.available')}
-			</Tag>,
+			cell: (module) =>
+				<Tag tone={activationTone(module)} dot>{activationLabel(module)}</Tag>,
 		},
 	];
 }

package/modules/system/src/client/state.ts

@@ -4,6 +4,12 @@ import type { ModuleCatalogEntry } from './api.ts';
 export type ModulesStatus = 'loading' | 'idle' | 'denied' | 'error';
 export type ModulesTab = 'catalog' | 'flags';
 
+/** The activation change waiting for the owner's confirmation. */
+export interface PendingActivation {
+	readonly moduleId: string;
+	readonly active: boolean;
+}
+
 export function createModulesClientState() {
 	const store = createStore({
 		modules: cell<readonly ModuleCatalogEntry[]>([]),
@@ -13,6 +19,26 @@ export function createModulesClientState() {
 		query: '',
 		selectedModuleId: cell<string | null>(null),
 		tab: cell<ModulesTab>('catalog'),
+		pending: cell<PendingActivation | null>(null),
+		busyModuleId: cell<string | null>(null),
+		activationError: '',
 	});
 	return { store, state: store.state };
 }
+
+/** Why the row action is refused before the server is asked, else null. */
+export function activationRefusal(
+	module: ModuleCatalogEntry,
+	canManage: boolean,
+	translate: (key: string, params?: Record<string, string>) => string,
+): string | null {
+	if (!module.enabled) return translate('system.activation.notComposed');
+	if (!canManage) return translate('system.activation.deniedManage');
+	if (!module.optional) return translate('system.activation.required');
+	if (module.active && module.dependents.length > 0) {
+		return translate('system.activation.dependents', {
+			modules: module.dependents.join(', '),
+		});
+	}
+	return null;
+}

package/modules/system/src/domain/modules.ts

@@ -0,0 +1,93 @@
+import { REQUIRED_MODULE_IDS } from '@flowdular/sdk/contracts';
+
+export const SYSTEM_MODULES_CAPABILITY = 'system.modules.v1';
+
+const REQUIRED = new Set<string>(REQUIRED_MODULE_IDS);
+
+export function isRequiredModule(moduleId: string): boolean {
+	return REQUIRED.has(moduleId);
+}
+
+/** One module the application composes, with the modules it cannot run without. */
+export interface ComposedModule {
+	readonly id: string;
+	readonly version: string;
+	readonly dependencies: readonly string[];
+}
+
+export interface ModuleActivationEntry {
+	readonly id: string;
+	readonly version: string;
+	readonly active: boolean;
+	/** False for a required module, which is never deactivated. */
+	readonly optional: boolean;
+	/** Composed modules that declare this one as a dependency. */
+	readonly dependents: readonly string[];
+}
+
+export interface ModuleActivationChange {
+	readonly moduleId: string;
+	readonly active: boolean;
+}
+
+/** What other composed modules a public capability is served by. */
+export interface ManifestDependencies {
+	readonly id: string;
+	readonly version: string;
+	readonly dependencies: readonly string[];
+	readonly provides: readonly string[];
+	/** Capability ids the module cannot compose without. */
+	readonly requires: readonly string[];
+}
+
+/* A dependency is a declared module dependency or a required capability,
+   resolved to the composed module that provides it. */
+export function composedModules(
+	manifests: readonly ManifestDependencies[],
+): readonly ComposedModule[] {
+	const providers = new Map<string, string>();
+	const ids = new Set(manifests.map((manifest) => manifest.id));
+	for (const manifest of manifests) {
+		for (const capability of manifest.provides) {
+			providers.set(capability, manifest.id);
+		}
+	}
+	return manifests.map((manifest) => {
+		const dependencies = new Set<string>();
+		for (const id of manifest.dependencies) {
+			if (ids.has(id) && id !== manifest.id) dependencies.add(id);
+		}
+		for (const capability of manifest.requires) {
+			const provider = providers.get(capability);
+			if (provider !== undefined && provider !== manifest.id) {
+				dependencies.add(provider);
+			}
+		}
+		return {
+			id: manifest.id,
+			version: manifest.version,
+			dependencies: [...dependencies].sort(),
+		};
+	});
+}
+
+export function dependentsOf(
+	modules: readonly ComposedModule[],
+	moduleId: string,
+): readonly string[] {
+	return modules
+		.filter((module) => module.dependencies.includes(moduleId))
+		.map((module) => module.id)
+		.sort();
+}
+
+/** The composed module ids that are active for a workspace, sorted. */
+export function activeModuleIds(
+	modules: readonly ComposedModule[],
+	inactive: ReadonlySet<string>,
+): readonly string[] {
+	return modules
+		.map((module) => module.id)
+		.filter((id) => isRequiredModule(id) || !inactive.has(id))
+		.sort();
+}

package/modules/system/src/index.ts

@@ -21,3 +21,16 @@ export {
 	TENANT_TIME_ZONE_KEY,
 	tenantTimeZone,
 } from './domain/time-zone.ts';
+export {
+	activeModuleIds,
+	composedModules,
+	dependentsOf,
+	isRequiredModule,
+	SYSTEM_MODULES_CAPABILITY,
+} from './domain/modules.ts';
+export type {
+	ComposedModule,
+	ManifestDependencies,
+	ModuleActivationChange,
+	ModuleActivationEntry,
+} from './domain/modules.ts';

package/modules/system/src/platform.ts

@@ -2,14 +2,54 @@ import type {
 	PlatformServerComposition,
 	PlatformServerContext,
 } from '@flowdular/sdk/modules/auth/server';
+import { installModuleActivationGate } from '@flowdular/sdk/server';
+import {
+	composedModules,
+	SYSTEM_MODULES_CAPABILITY,
+	type ComposedModule,
+} from './domain/modules.ts';
 import { createSystemRoutes } from './server/endpoints.ts';
+import { readModuleCatalog } from './server/module-catalog.ts';
+import { createSystemRuntime } from './server/runtime.ts';
+import type { SystemModulesCapability } from './server/capability.ts';
 import { SYSTEM_MODULE_SETTINGS } from './settings.ts';
 
 export function createServerComposition(
 	context: PlatformServerContext,
 ): PlatformServerComposition {
+	/* The composed set is baked at build, so the manifests are read once per
+	   composition, which in development is once per reload. */
+	let composed: readonly ComposedModule[] | null = null;
+	const modules = () =>
+		(composed ??= composedModules(
+			readModuleCatalog(context.workspaceRoot).filter((entry) => entry.enabled),
+		));
+	const runtime = createSystemRuntime({
+		databases: context.databases,
+		purpose:
+			context.environment.NODE_ENV === 'test'
+				? 'test'
+				: context.environment.NODE_ENV === 'production'
+					? 'runtime'
+					: 'preview',
+		modules,
+		audit: async (actor, change) =>
+			(await context.auth.service()).recordModuleActivation(actor, change),
+	});
+	const capability: SystemModulesCapability = {
+		isActive: async (tenantId, moduleId) =>
+			(await runtime.service()).isActive(tenantId, moduleId),
+		activeIds: async (tenantId) =>
+			(await runtime.service()).activeIds(tenantId),
+	};
+	context.capabilities.register(SYSTEM_MODULES_CAPABILITY, capability);
+	installModuleActivationGate(capability);
 	return {
-		routes: createSystemRoutes(context),
+		routes: createSystemRoutes({ ...context, activation: runtime }),
 		settings: SYSTEM_MODULE_SETTINGS,
+		dispose: async () => {
+			installModuleActivationGate(null);
+			await runtime.dispose();
+		},
 	};
 }

package/modules/system/src/server/capability.ts

@@ -0,0 +1,6 @@
+/** `system.modules.v1`: which composed modules are active in a workspace. */
+export interface SystemModulesCapability {
+	isActive(tenantId: string, moduleId: string): Promise<boolean>;
+	/** Sorted ids of the composed modules active in the workspace. */
+	activeIds(tenantId: string): Promise<readonly string[]>;
+}

package/modules/system/src/server/endpoints.ts

@@ -26,12 +26,57 @@ import {
 	SYSTEM_MODULE_ID,
 	TENANT_TIME_ZONE_KEY,
 } from '../domain/time-zone.ts';
-import { readModuleCatalog } from './module-catalog.ts';
+import type { ModuleActivationEntry } from '../domain/modules.ts';
+import { ModuleActivationError } from '../services/module-activation-service.ts';
+import {
+	readModuleCatalog,
+	type ModuleCatalogEntry,
+} from './module-catalog.ts';
+import type { SystemRuntime } from './runtime.ts';
 
 export interface SystemRouteOptions {
 	readonly workspaceRoot: string;
 	readonly auth: AuthRuntime;
 	readonly settings: ModuleSettingsRuntime;
+	/** Per-workspace activation of the composed modules. */
+	readonly activation: SystemRuntime;
+}
+
+/** A catalog row with its activation in the asking principal's workspace. */
+export interface ModuleCatalogPayload extends ModuleCatalogEntry {
+	readonly active: boolean;
+	readonly optional: boolean;
+	readonly dependents: readonly string[];
+}
+
+/* A module the workspace holds but the application does not compose has no
+   activation to speak of: it is listed as available and never active. */
+function catalogPayload(
+	entry: ModuleCatalogEntry,
+	activation: ModuleActivationEntry | undefined,
+): ModuleCatalogPayload {
+	return {
+		...entry,
+		active: activation?.active ?? false,
+		optional: activation?.optional ?? true,
+		dependents: activation?.dependents ?? [],
+	};
+}
+
+function activationProblem(error: unknown): Response {
+	if (error instanceof ModuleActivationError) {
+		return jsonResponse(
+			{
+				error: {
+					code: error.code,
+					message: error.message,
+					modules: error.modules,
+				},
+			},
+			error.status,
+		);
+	}
+	return problemResponse(error, 'The module activation request failed.');
 }
 
 const MAIL_TRANSPORT_REQUIRED =
@@ -236,8 +281,9 @@ async function readActivity(
 	return keys.map((date) => ({ date, count: counts.get(date) ?? 0 }));
 }
 
-/* Metadata only: manifests and specifications from the workspace. Enabling or
-   disabling a module stays a CLI operation with its own approval trail. */
+/* Manifests and specifications from the workspace, with the per-workspace
+   activation of the composed ones. Enabling or disabling a module stays a CLI
+   operation with its own approval trail. */
 export function createSystemRoutes(options: SystemRouteOptions) {
 	const modules = defineEndpoint({
 		id: 'system.modules.list',
@@ -245,10 +291,18 @@ export function createSystemRoutes(options: SystemRouteOptions) {
 		methods: ['GET'],
 		access: { kind: 'permission', permission: SYSTEM_PERMISSIONS.modulesRead },
 		resolveIdentity: endpointIdentityFromContext,
-		handler: () => {
+		handler: async ({ octane }) => {
 			try {
+				const principal = principalFromContext(octane)!;
+				const activations = new Map(
+					(
+						await (await options.activation.service()).list(principal.tenantId)
+					).map((entry) => [entry.id, entry]),
+				);
 				return jsonResponse({
-					modules: readModuleCatalog(options.workspaceRoot),
+					modules: readModuleCatalog(options.workspaceRoot).map((entry) =>
+						catalogPayload(entry, activations.get(entry.id)),
+					),
 					commands: {
 						enable: 'pnpm flowdular module enable <id> --apply',
 						disable: 'pnpm flowdular module disable <id> --apply',
@@ -263,6 +317,66 @@ export function createSystemRoutes(options: SystemRouteOptions) {
 		},
 	});
 
+	const activeModules = defineEndpoint({
+		id: 'system.modules.active',
+		path: '/api/system/modules/active',
+		methods: ['GET'],
+		access: {
+			kind: 'permission',
+			permission: SYSTEM_PERMISSIONS.workspaceAccess,
+		},
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			try {
+				const principal = principalFromContext(octane)!;
+				const service = await options.activation.service();
+				return jsonResponse({
+					modules: await service.activeIds(principal.tenantId),
+				});
+			} catch (error) {
+				return activationProblem(error);
+			}
+		},
+	});
+
+	const activation = (id: string, path: string, active: boolean) =>
+		defineEndpoint({
+			id,
+			path,
+			methods: ['POST'],
+			access: {
+				kind: 'permission',
+				permission: SYSTEM_PERMISSIONS.settingsManage,
+			},
+			resolveIdentity: endpointIdentityFromContext,
+			handler: async ({ octane }) => {
+				const denial = sessionMutationDenial(octane, options.auth);
+				if (denial) return denial;
+				try {
+					const principal = principalFromContext(octane)!;
+					const body = await readJsonObject(octane.request);
+					const moduleId = requiredString(body, 'moduleId', { max: 128 });
+					const service = await options.activation.service();
+					const entry = active
+						? await service.activate(principal, moduleId)
+						: await service.deactivate(principal, moduleId);
+					return jsonResponse({ module: entry });
+				} catch (error) {
+					return activationProblem(error);
+				}
+			},
+		});
+	const activateModule = activation(
+		'system.modules.activate',
+		'/api/system/modules/activate',
+		true,
+	);
+	const deactivateModule = activation(
+		'system.modules.deactivate',
+		'/api/system/modules/deactivate',
+		false,
+	);
+
 	/* Module names come from the workspace specs; the catalog is read once per
 	   composition, which in development is once per reload. */
 	let names: ReadonlyMap<
@@ -409,6 +523,9 @@ export function createSystemRoutes(options: SystemRouteOptions) {
 
 	return [
 		modules.serverRoute,
+		activeModules.serverRoute,
+		activateModule.serverRoute,
+		deactivateModule.serverRoute,
 		overview.serverRoute,
 		settingsList.serverRoute,
 		settingsUpdate.serverRoute,
@@ -417,6 +534,9 @@ export function createSystemRoutes(options: SystemRouteOptions) {
 
 export const endpoints = [
 	'system.modules.list',
+	'system.modules.active',
+	'system.modules.activate',
+	'system.modules.deactivate',
 	'system.overview.read',
 	'system.settings.list',
 	'system.settings.update',

package/modules/system/src/server/index.ts

@@ -1,5 +1,6 @@
 export { createSystemRoutes, endpoints } from './endpoints.ts';
 export type {
+	ModuleCatalogPayload,
 	OverviewActivityPoint,
 	OverviewModulePoint,
 	SettingsEntryPayload,
@@ -9,3 +10,28 @@ export type {
 } from './endpoints.ts';
 export { readModuleCatalog } from './module-catalog.ts';
 export type { ModuleCatalogEntry } from './module-catalog.ts';
+export type { SystemModulesCapability } from './capability.ts';
+export { createSystemRuntime } from './runtime.ts';
+export type { SystemRuntime, SystemRuntimeOptions } from './runtime.ts';
+export {
+	DEFAULT_SNAPSHOT_TENANTS,
+	DEFAULT_SNAPSHOT_TTL_MS,
+	ModuleActivationError,
+	ModuleActivationService,
+} from '../services/module-activation-service.ts';
+export type {
+	ModuleActivationErrorCode,
+	ModuleActivationServiceOptions,
+} from '../services/module-activation-service.ts';
+export {
+	DatabaseModuleActivationRepository,
+	migrateSystemDatabase,
+} from '../services/database-repository.ts';
+export {
+	databaseMigrations,
+	SYSTEM_TENANT_TABLES,
+} from '../services/migration.ts';
+export type {
+	ModuleActivationRecord,
+	ModuleActivationRepository,
+} from '../services/repository.ts';

package/modules/system/src/server/module-catalog.ts

@@ -16,6 +16,11 @@ export interface ModuleCatalogEntry {
 	readonly platform: { readonly server: boolean; readonly client: boolean };
 	readonly enabled: boolean;
 	readonly directory: string;
+	/** Declared module dependencies, by id. */
+	readonly dependencies: readonly string[];
+	readonly provides: readonly string[];
+	/** Capability ids the module requires, optional requirements excluded. */
+	readonly requires: readonly string[];
 }
 
 interface Manifest {
@@ -23,6 +28,9 @@ interface Manifest {
 	version?: unknown;
 	capabilities?: unknown;
 	platform?: { server?: unknown; client?: unknown };
+	dependencies?: { id?: unknown }[];
+	provides?: unknown;
+	requires?: { id?: unknown; optional?: unknown }[];
 }
 
 interface Spec {
@@ -111,6 +119,17 @@ export function readModuleCatalog(
 			},
 			enabled: enabled.has(manifest.id),
 			directory,
+			dependencies: strings(
+				(Array.isArray(manifest.dependencies) ? manifest.dependencies : []).map(
+					(dependency) => dependency?.id,
+				),
+			),
+			provides: strings(manifest.provides),
+			requires: strings(
+				(Array.isArray(manifest.requires) ? manifest.requires : [])
+					.filter((requirement) => requirement?.optional !== true)
+					.map((requirement) => requirement?.id),
+			),
 		});
 	}
 	return entries;

package/modules/system/src/server/runtime.ts

@@ -0,0 +1,102 @@
+import type {
+	DatabaseAdapterLease,
+	DatabaseProvider,
+	DatabaseProviderRequest,
+} from '@flowdular/sdk/database';
+import {
+	DATABASE_CAPABILITY_IDS,
+	DATABASE_DIALECT_IDS,
+} from '@flowdular/sdk/database';
+import {
+	DatabaseModuleActivationRepository,
+	migrateSystemDatabase,
+} from '../services/database-repository.ts';
+import {
+	ModuleActivationService,
+	type ModuleActivationServiceOptions,
+} from '../services/module-activation-service.ts';
+import type { ModuleActivationRepository } from '../services/repository.ts';
+
+export interface SystemRuntimeOptions
+	extends Omit<ModuleActivationServiceOptions, 'repository'> {
+	/** Platform-owned provider. Modules never receive a DSN or a pool. */
+	readonly databases: DatabaseProvider;
+	readonly purpose: Exclude<DatabaseProviderRequest['purpose'], 'migration'>;
+	/** Supplied by tests that own the lease themselves. */
+	readonly repository?: ModuleActivationRepository;
+}
+
+export interface SystemRuntime {
+	service(): Promise<ModuleActivationService>;
+	dispose(): Promise<void>;
+}
+
+export function createSystemRuntime(
+	options: SystemRuntimeOptions,
+): SystemRuntime {
+	let disposed = false;
+	let runtimeLeasePromise: Promise<DatabaseAdapterLease> | undefined;
+	let servicePromise: Promise<ModuleActivationService> | undefined;
+	const { databases, purpose, repository, ...serviceOptions } = options;
+
+	const build = (store: ModuleActivationRepository): ModuleActivationService =>
+		new ModuleActivationService({ ...serviceOptions, repository: store });
+
+	/* Schema work runs on the migrator role and that lease is released before the
+	   runtime one is taken, so request handling never holds a schema owner. */
+	const initialize = async (): Promise<ModuleActivationService> => {
+		if (repository) return build(repository);
+		const migrationLease = await databases.acquire({
+			namespace: 'system.core',
+			purpose: 'migration',
+			requirements: {
+				dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+				capabilities: [
+					DATABASE_CAPABILITY_IDS.MIGRATION_LOCK,
+					DATABASE_CAPABILITY_IDS.SCHEMA_INTROSPECTION,
+					DATABASE_CAPABILITY_IDS.TRANSACTIONAL_DDL,
+				],
+			},
+		});
+		try {
+			await migrateSystemDatabase(migrationLease.database);
+		} finally {
+			await migrationLease.release();
+		}
+		runtimeLeasePromise = databases.acquire({
+			namespace: 'system.core',
+			purpose,
+			requirements: {
+				dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+				capabilities: [
+					DATABASE_CAPABILITY_IDS.TRANSACTIONS,
+					DATABASE_CAPABILITY_IDS.TENANT_CONTEXT,
+				],
+			},
+		});
+		const lease = await runtimeLeasePromise;
+		return build(new DatabaseModuleActivationRepository(lease.database));
+	};
+
+	return {
+		service: () => {
+			if (disposed) {
+				return Promise.reject(new Error('System runtime is disposed.'));
+			}
+			servicePromise ??= initialize();
+			return servicePromise;
+		},
+		async dispose() {
+			if (disposed) return;
+			disposed = true;
+			if (!runtimeLeasePromise) {
+				await servicePromise?.catch(() => undefined);
+			}
+			if (!runtimeLeasePromise) return;
+			const lease = await runtimeLeasePromise;
+			await lease.release();
+			runtimeLeasePromise = undefined;
+			servicePromise = undefined;
+		},
+	};
+}