@flowdular/sdk 0.1.0

package/packages/kernel/src/actor.ts

@@ -0,0 +1,139 @@
+export type ActorKind = 'user' | 'agent' | 'service';
+
+interface ActorIdentity {
+	readonly id: string;
+	readonly label: string;
+}
+
+export interface UserActor extends ActorIdentity {
+	readonly kind: 'user';
+	readonly runId?: never;
+}
+
+export interface AgentActor extends ActorIdentity {
+	readonly kind: 'agent';
+	/* Every agent mutation remains traceable to the run that authorized it. */
+	readonly runId: string;
+}
+
+export interface ServiceActor extends ActorIdentity {
+	readonly kind: 'service';
+	/* A service acts with authority configured by a real account. Keeping the
+	   user here prevents schedules and webhooks from becoming anonymous system
+	   actors in record history. */
+	readonly configuredBy: UserActor;
+}
+
+/* Audit and record-history surfaces use one discriminated actor model. The
+   required runId prevents an agent from being stored as an anonymous user-like
+   label while keeping user records free of synthetic run identifiers. */
+export type Actor = UserActor | AgentActor | ServiceActor;
+
+export const MAX_ACTOR_ID_LENGTH = 128;
+export const MAX_ACTOR_LABEL_LENGTH = 160;
+
+/* Older tool callers may still provide only a run identifier. New harness
+   calls also carry the exact agent identity. */
+export interface AgentActorSource {
+	readonly runId: string;
+	readonly agentId?: string;
+	readonly agentName?: string;
+}
+
+export interface UserActorSource {
+	readonly accountId: string;
+	readonly displayName?: string;
+	readonly email: string;
+}
+
+export interface ServiceActorSource {
+	readonly serviceId: string;
+	readonly label: string;
+	readonly configuredBy: UserActor | UserActorSource;
+}
+
+function trimmed(value: string | undefined): string {
+	return typeof value === 'string' ? value.trim() : '';
+}
+
+export function agentActor(source: AgentActorSource): Actor {
+	const runId = trimmed(source.runId);
+	return {
+		kind: 'agent',
+		id: trimmed(source.agentId) || runId,
+		label: trimmed(source.agentName) || `Agent run ${runId}`,
+		runId,
+	};
+}
+
+export function userActor(source: UserActorSource): UserActor {
+	const accountId = trimmed(source.accountId);
+	const displayName = trimmed(source.displayName);
+	const email = trimmed(source.email);
+	return {
+		kind: 'user',
+		id: accountId,
+		label: displayName || email,
+	};
+}
+
+export function serviceActor(source: ServiceActorSource): ServiceActor {
+	const configuredBy =
+		'kind' in source.configuredBy
+			? source.configuredBy
+			: userActor(source.configuredBy);
+	return {
+		kind: 'service',
+		id: trimmed(source.serviceId),
+		label: trimmed(source.label),
+		configuredBy,
+	};
+}
+
+/* Returns null instead of throwing so each service reports the refusal with
+   its own error code. */
+export function normalizeActor(actor: Actor): Actor | null {
+	if (
+		actor.kind !== 'user' &&
+		actor.kind !== 'agent' &&
+		actor.kind !== 'service'
+	)
+		return null;
+	const id = trimmed(actor.id);
+	const label = trimmed(actor.label);
+	if (id.length === 0 || id.length > MAX_ACTOR_ID_LENGTH) return null;
+	if (label.length === 0 || label.length > MAX_ACTOR_LABEL_LENGTH) return null;
+	if (actor.kind === 'agent') {
+		const runId = trimmed(actor.runId);
+		if (runId.length === 0 || runId.length > MAX_ACTOR_ID_LENGTH) return null;
+		return { kind: 'agent', id, label, runId };
+	}
+	if (actor.kind === 'service') {
+		const configuredBy = normalizeActor(actor.configuredBy);
+		if (!configuredBy || configuredBy.kind !== 'user') return null;
+		return { kind: 'service', id, label, configuredBy };
+	}
+	return { kind: 'user', id, label };
+}
+
+/* Labels are presentation data and may change. Authority is the actor kind and
+   stable id, plus the provenance that makes agent and service actors traceable. */
+export function actorsEqual(left: Actor, right: Actor): boolean {
+	const normalizedLeft = normalizeActor(left);
+	const normalizedRight = normalizeActor(right);
+	if (
+		!normalizedLeft ||
+		!normalizedRight ||
+		normalizedLeft.kind !== normalizedRight.kind ||
+		normalizedLeft.id !== normalizedRight.id
+	) {
+		return false;
+	}
+	if (normalizedLeft.kind === 'agent' && normalizedRight.kind === 'agent') {
+		return normalizedLeft.runId === normalizedRight.runId;
+	}
+	if (normalizedLeft.kind === 'service' && normalizedRight.kind === 'service') {
+		return normalizedLeft.configuredBy.id === normalizedRight.configuredBy.id;
+	}
+	return normalizedLeft.kind === 'user' && normalizedRight.kind === 'user';
+}

package/packages/kernel/src/agent-registry.ts

@@ -0,0 +1,81 @@
+/* Business modules register code-owned agent definitions while the platform is
+	 composing. The registry becomes an immutable catalog before start hooks run. */
+export interface PlatformAgentRegistry<T = unknown> {
+	register(definitions: readonly T[]): void;
+	list(): readonly T[];
+	/** Returns a registrar that accepts definitions owned by one module only. */
+	forModule(moduleId: string): PlatformAgentRegistry<T>;
+}
+
+export interface MutablePlatformAgentRegistry<T>
+	extends PlatformAgentRegistry<T> {
+	seal(): void;
+}
+
+export function createPlatformAgentRegistry<
+	T extends { readonly id: string },
+>(): MutablePlatformAgentRegistry<T> {
+	const definitions = new Map<string, T>();
+	let sealed: readonly T[] | null = null;
+	const view = (boundModuleId?: string): PlatformAgentRegistry<T> => ({
+		register(entries) {
+			if (sealed !== null) {
+				throw new Error('The platform agent registry is already sealed.');
+			}
+
+			/* Validate the whole batch before changing the registry. A duplicate must
+			   never leave only part of one module's declaration registered. */
+			const incoming = new Set<string>();
+			for (const definition of entries) {
+				if (
+					boundModuleId !== undefined &&
+					(definition as { readonly moduleId?: unknown }).moduleId !==
+						boundModuleId
+				) {
+					throw new Error(
+						`Module ${boundModuleId} cannot register an agent owned by ${String((definition as { readonly moduleId?: unknown }).moduleId ?? 'an unknown module')}.`,
+					);
+				}
+				if (typeof definition.id !== 'string' || definition.id.length === 0) {
+					throw new Error('A platform agent definition requires an id.');
+				}
+				if (definitions.has(definition.id) || incoming.has(definition.id)) {
+					throw new Error(
+						`Platform agent ${definition.id} is already registered.`,
+					);
+				}
+				incoming.add(definition.id);
+			}
+
+			for (const definition of entries) {
+				definitions.set(definition.id, definition);
+			}
+		},
+		list() {
+			return sealed ?? Object.freeze([...definitions.values()]);
+		},
+		forModule(moduleId) {
+			const normalized = moduleId.trim();
+			if (!normalized)
+				throw new Error('A module-bound agent registry needs an id.');
+			if (boundModuleId !== undefined && normalized !== boundModuleId) {
+				throw new Error(
+					`Module ${boundModuleId} cannot obtain the agent registrar for ${normalized}.`,
+				);
+			}
+			return boundModuleId === normalized ? this : view(normalized);
+		},
+	});
+
+	return {
+		...view(),
+		seal() {
+			if (sealed !== null) return;
+			sealed = Object.freeze(
+				[...definitions.values()].sort((left, right) =>
+					left.id.localeCompare(right.id),
+				),
+			);
+		},
+	};
+}

package/packages/kernel/src/capability-registry.ts

@@ -0,0 +1,28 @@
+/* Public services exposed between composed modules. The registry owns only
+   identities and lifetimes; each provider owns the capability's types. */
+export interface PlatformCapabilityRegistry {
+	register<T>(id: string, capability: T): void;
+	get<T>(id: string): T | null;
+	has(id: string): boolean;
+}
+
+export function createPlatformCapabilityRegistry(): PlatformCapabilityRegistry {
+	const capabilities = new Map<string, unknown>();
+	return {
+		register(id, capability) {
+			if (!/^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/.test(id)) {
+				throw new Error(`Platform capability ${id} has an invalid id.`);
+			}
+			if (capabilities.has(id)) {
+				throw new Error(`Platform capability ${id} is already registered.`);
+			}
+			capabilities.set(id, capability);
+		},
+		get<T>(id: string): T | null {
+			return (capabilities.get(id) as T | undefined) ?? null;
+		},
+		has(id) {
+			return capabilities.has(id);
+		},
+	};
+}

package/packages/kernel/src/errors.ts

@@ -0,0 +1,9 @@
+export class RegistryError extends Error {
+	readonly code: string;
+
+	constructor(code: string, message: string) {
+		super(message);
+		this.name = 'RegistryError';
+		this.code = code;
+	}
+}

package/packages/kernel/src/index.ts

@@ -0,0 +1,90 @@
+export { authorize } from './acl.ts';
+export type { AccessDecision, Principal } from './acl.ts';
+export { createPlatformAgentRegistry } from './agent-registry.ts';
+export type {
+	MutablePlatformAgentRegistry,
+	PlatformAgentRegistry,
+} from './agent-registry.ts';
+export {
+	agentActor,
+	actorsEqual,
+	MAX_ACTOR_ID_LENGTH,
+	MAX_ACTOR_LABEL_LENGTH,
+	normalizeActor,
+	serviceActor,
+	userActor,
+} from './actor.ts';
+export type {
+	Actor,
+	ActorKind,
+	AgentActor,
+	AgentActorSource,
+	ServiceActor,
+	ServiceActorSource,
+	UserActor,
+	UserActorSource,
+} from './actor.ts';
+export { createPlatformCapabilityRegistry } from './capability-registry.ts';
+export type { PlatformCapabilityRegistry } from './capability-registry.ts';
+export { RegistryError } from './errors.ts';
+export {
+	DEFAULT_HISTORY_PAGE,
+	diffFields,
+	MAX_HISTORY_PAGE,
+	parseHistoryRequest,
+} from './record-history.ts';
+export type {
+	FieldChange,
+	HistoryEntry,
+	HistoryPage,
+	HistoryQuery,
+	HistoryRequest,
+	HistoryValue,
+	HistoryWrite,
+	RecordChanges,
+	TrackedFields,
+} from './record-history.ts';
+export { createModuleRegistry } from './module-registry.ts';
+export {
+	assertSettingValue,
+	createModuleSettingsRuntime,
+	defineModuleSettings,
+	ModuleSettingsError,
+	PLATFORM_SETTINGS_TENANT,
+} from './module-settings.ts';
+export type {
+	ModuleSettingChange,
+	ModuleSettingDefinition,
+	ModuleSettingEntry,
+	ModuleSettingRecord,
+	ModuleSettingScope,
+	ModuleSettingsDeclaration,
+	ModuleSettingsRuntime,
+	ModuleSettingsRuntimeOptions,
+	ModuleSettingsStore,
+	ModuleSettingType,
+	ModuleSettingValue,
+} from './module-settings.ts';
+export type { ModuleRegistry } from './module-registry.ts';
+export { createPlatformToolRegistry } from './tool-registry.ts';
+export type { PlatformToolRegistry } from './tool-registry.ts';
+export {
+	createPlatformVariableRegistry,
+	platformVariableRegistry,
+	PLATFORM_VARIABLES_CAPABILITY,
+	VariableResolutionError,
+} from './variable-registry.ts';
+export type {
+	PlatformVariableRegistry,
+	VariableResolutionRequest,
+	VariableSourceResolutionContext,
+	VariableSourceResolver,
+} from './variable-registry.ts';
+
+export {
+	PLATFORM_API_VERSION,
+	assertModuleCompatibility,
+	assertModuleDependency,
+	satisfiesModuleVersion,
+	compareModuleVersions,
+} from './module-compatibility.ts';

package/packages/kernel/src/legacy-local-state.ts

@@ -0,0 +1,103 @@
+import {
+	flowdularStateDirectory,
+	UnsafeLocalStatePathError,
+} from './runtime-config.ts';
+import { chmodSync, lstatSync, mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export const FLOWDULAR_DATA_DIRECTORY = '.flowdular/data';
+
+/* Kept only for the guarded compatibility path and the explicit CLI copy.
+   Runtime code must never read from this directory. */
+export const LEGACY_DATA_DIRECTORY = '.octane-erp';
+
+export class LegacyLocalStateError extends Error {
+	readonly code = 'LEGACY_LOCAL_STATE_REQUIRES_MIGRATION';
+
+	constructor(readonly fileName: string) {
+		super(
+			`Legacy local state exists for ${fileName}. Stop Flowdular and run "flowdular setup migrate-state" before starting it again.`,
+		);
+		this.name = 'LegacyLocalStateError';
+	}
+}
+
+export { UnsafeLocalStatePathError } from './runtime-config.ts';
+
+function state(path: string) {
+	try {
+		return lstatSync(path);
+	} catch (error) {
+		if (
+			error instanceof Error &&
+			'code' in error &&
+			(error as NodeJS.ErrnoException).code === 'ENOENT'
+		)
+			return undefined;
+		throw error;
+	}
+}
+
+function directory(path: string, create: boolean): void {
+	let current = state(path);
+	if (!current && create) {
+		try {
+			mkdirSync(path, { mode: 0o700 });
+		} catch (error) {
+			if (
+				!(
+					error instanceof Error &&
+					'code' in error &&
+					(error as NodeJS.ErrnoException).code === 'EEXIST'
+				)
+			)
+				throw error;
+		}
+		current = state(path);
+	}
+	if (current && (current.isSymbolicLink() || !current.isDirectory())) {
+		throw new UnsafeLocalStatePathError(path, 'directory');
+	}
+	if (current && create) chmodSync(path, 0o700);
+}
+
+function regularFile(path: string) {
+	const current = state(path);
+	if (current && (current.isSymbolicLink() || !current.isFile())) {
+		throw new UnsafeLocalStatePathError(path, 'file');
+	}
+	return current;
+}
+
+export function flowdularLocalDataPath(
+	workspaceRoot: string,
+	fileName: string,
+): string {
+	if (
+		fileName.length === 0 ||
+		fileName.includes('/') ||
+		fileName.includes('\\') ||
+		fileName === '.' ||
+		fileName === '..'
+	) {
+		throw new TypeError(
+			'A local state file name must be a single path segment.',
+		);
+	}
+	const flowdularDirectory = flowdularStateDirectory(workspaceRoot);
+	const dataDirectory = resolve(flowdularDirectory, 'data');
+	const legacyDirectory = resolve(workspaceRoot, LEGACY_DATA_DIRECTORY);
+	const target = resolve(dataDirectory, fileName);
+	const legacy = resolve(legacyDirectory, fileName);
+	directory(legacyDirectory, false);
+	const legacyState = regularFile(legacy);
+	directory(flowdularDirectory, false);
+	directory(dataDirectory, false);
+	const targetState = regularFile(target);
+	if (!targetState && legacyState) {
+		throw new LegacyLocalStateError(fileName);
+	}
+	directory(flowdularDirectory, true);
+	directory(dataDirectory, true);
+	return target;
+}

package/packages/kernel/src/module-compatibility.ts

@@ -0,0 +1,70 @@
+import { satisfies, valid, validRange, rcompare } from 'semver';
+import type { ModuleManifest } from '@flowdular/sdk/contracts';
+import { RegistryError } from './errors.ts';
+
+/** Version of the public platform contract, independent of application versions. */
+export const PLATFORM_API_VERSION = '0.1.0';
+
+export function satisfiesModuleVersion(
+	version: string,
+	range: string,
+): boolean {
+	return (
+		valid(version) !== null &&
+		validRange(range) !== null &&
+		satisfies(version, range)
+	);
+}
+
+export function compareModuleVersions(left: string, right: string): number {
+	return rcompare(left, right);
+}
+
+export function assertModuleCompatibility(
+	manifest: ModuleManifest,
+	platformVersion: string | null = PLATFORM_API_VERSION,
+): void {
+	if (!valid(manifest.version))
+		throw new RegistryError(
+			'MODULE_VERSION_INVALID',
+			`Invalid version for ${manifest.id}: ${manifest.version}`,
+		);
+	if (
+		manifest.platformApi !== undefined &&
+		(!validRange(manifest.platformApi) ||
+			(platformVersion !== null &&
+				!satisfiesModuleVersion(platformVersion, manifest.platformApi)))
+	) {
+		throw new RegistryError(
+			'MODULE_PLATFORM_INCOMPATIBLE',
+			`${manifest.id} requires platform API ${manifest.platformApi}; available ${PLATFORM_API_VERSION}.`,
+		);
+	}
+	const ids = new Set<string>();
+	for (const dependency of manifest.dependencies) {
+		if (!dependency.range.trim() || !validRange(dependency.range))
+			throw new RegistryError(
+				'MODULE_RANGE_INVALID',
+				`${manifest.id} declares an invalid range for ${dependency.id}: ${dependency.range}`,
+			);
+		if (ids.has(dependency.id))
+			throw new RegistryError(
+				'MODULE_DEPENDENCY_DUPLICATE',
+				`${manifest.id} declares ${dependency.id} more than once.`,
+			);
+		ids.add(dependency.id);
+	}
+}
+
+export function assertModuleDependency(
+	consumer: string,
+	dependency: { id: string; range: string },
+	version: string,
+): void {
+	if (!satisfiesModuleVersion(version, dependency.range)) {
+		throw new RegistryError(
+			'MODULE_DEPENDENCY_INCOMPATIBLE',
+			`${consumer} requires ${dependency.id} ${dependency.range}; available ${version}.`,
+		);
+	}
+}

package/packages/kernel/src/module-registry.ts

@@ -0,0 +1,124 @@
+import type {
+	NavigationContribution,
+	RegisteredModule,
+} from '@flowdular/sdk/contracts';
+import {
+	assertModuleCompatibility,
+	assertModuleDependency,
+} from './module-compatibility.ts';
+import { RegistryError } from './errors.ts';
+
+function compareModules(
+	left: RegisteredModule,
+	right: RegisteredModule,
+): number {
+	return left.manifest.id.localeCompare(right.manifest.id);
+}
+
+function visitModule(
+	id: string,
+	modules: ReadonlyMap<string, RegisteredModule>,
+	visiting: Set<string>,
+	visited: Set<string>,
+	ordered: RegisteredModule[],
+): void {
+	if (visited.has(id)) return;
+	if (visiting.has(id)) {
+		throw new RegistryError(
+			'MODULE_DEPENDENCY_CYCLE',
+			`Dependency cycle detected at "${id}".`,
+		);
+	}
+
+	const current = modules.get(id);
+	if (!current) {
+		throw new RegistryError(
+			'MODULE_NOT_FOUND',
+			`Module "${id}" is not registered.`,
+		);
+	}
+
+	visiting.add(id);
+	for (const dependency of [...current.manifest.dependencies].sort((a, b) =>
+		a.id.localeCompare(b.id),
+	)) {
+		if (!modules.has(dependency.id)) {
+			throw new RegistryError(
+				'MODULE_DEPENDENCY_MISSING',
+				`Module "${id}" requires missing module "${dependency.id}".`,
+			);
+		}
+		assertModuleDependency(
+			id,
+			dependency,
+			modules.get(dependency.id)!.manifest.version,
+		);
+		visitModule(dependency.id, modules, visiting, visited, ordered);
+	}
+	visiting.delete(id);
+	visited.add(id);
+	ordered.push(current);
+}
+
+export interface ModuleRegistry {
+	readonly modules: readonly RegisteredModule[];
+	get(id: string): RegisteredModule | undefined;
+	has(id: string): boolean;
+	navigation(
+		permissions?: ReadonlySet<string>,
+	): readonly NavigationContribution[];
+}
+
+export function createModuleRegistry(
+	input: readonly RegisteredModule[],
+): ModuleRegistry {
+	const byId = new Map<string, RegisteredModule>();
+	const navigationIds = new Set<string>();
+
+	for (const module of input) {
+		assertModuleCompatibility(module.manifest);
+		if (byId.has(module.manifest.id)) {
+			throw new RegistryError(
+				'MODULE_DUPLICATE',
+				`Module "${module.manifest.id}" is registered more than once.`,
+			);
+		}
+		byId.set(module.manifest.id, module);
+
+		for (const item of module.navigation ?? []) {
+			if (navigationIds.has(item.id)) {
+				throw new RegistryError(
+					'NAVIGATION_DUPLICATE',
+					`Navigation contribution "${item.id}" is registered more than once.`,
+				);
+			}
+			navigationIds.add(item.id);
+		}
+	}
+
+	const ordered: RegisteredModule[] = [];
+	const visiting = new Set<string>();
+	const visited = new Set<string>();
+	for (const module of [...input].sort(compareModules)) {
+		visitModule(module.manifest.id, byId, visiting, visited, ordered);
+	}
+
+	return Object.freeze({
+		modules: Object.freeze(ordered),
+		get: (id: string) => byId.get(id),
+		has: (id: string) => byId.has(id),
+		navigation: (permissions?: ReadonlySet<string>) =>
+			Object.freeze(
+				ordered
+					.flatMap((module) => module.navigation ?? [])
+					.filter(
+						(item) => !item.permission || permissions?.has(item.permission),
+					)
+					.sort(
+						(left, right) =>
+							(left.order ?? 1000) - (right.order ?? 1000) ||
+							left.id.localeCompare(right.id),
+					),
+			),
+	});
+}