@openfairygui/backend 0.2.0-alpha.0 → 0.2.0-alpha.10

package/src/node.ts

@@ -0,0 +1,96 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+	BackendRuntime,
+	type BackendFileHandle,
+	type BackendFileStat,
+	type BackendFileSystem,
+	type BackendHostAdapter,
+	type BackendRuntimeOptions,
+} from './runtime.js';
+
+export function createNodeBackendFileSystem(): BackendFileSystem {
+	return {
+		stat(filePath: string): Promise<BackendFileStat> {
+			return fs.stat(filePath);
+		},
+		readdir(dirPath: string): Promise<string[]> {
+			return fs.readdir(dirPath);
+		},
+		readFile(filePath: string): Promise<string> {
+			return fs.readFile(filePath, 'utf-8');
+		},
+		async readFileRaw(filePath: string): Promise<Uint8Array> {
+			const buffer = await fs.readFile(filePath);
+			return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+		},
+		writeFile(filePath: string, content: string): Promise<void> {
+			return fs.writeFile(filePath, content, 'utf-8');
+		},
+		writeFileRaw(filePath: string, data: Uint8Array): Promise<void> {
+			return fs.writeFile(filePath, data);
+		},
+		async mkdir(dirPath: string, options?: { recursive?: boolean }): Promise<void> {
+			await fs.mkdir(dirPath, { recursive: options?.recursive ?? false });
+		},
+		async resolvePath(filePath: string): Promise<string> {
+			try {
+				return await fs.realpath(filePath);
+			} catch {
+				return path.resolve(filePath);
+			}
+		},
+		async openExclusive(filePath: string): Promise<BackendFileHandle> {
+			const handle = await fs.open(filePath, 'wx');
+			return {
+				writeFile(content: string): Promise<void> {
+					return handle.writeFile(content, 'utf-8');
+				},
+				close(): Promise<void> {
+					return handle.close();
+				},
+			};
+		},
+		unlink(filePath: string): Promise<void> {
+			return fs.unlink(filePath);
+		},
+		join(...paths: string[]): string {
+			return path.join(...paths);
+		},
+		dirname(filePath: string): string {
+			return path.dirname(filePath);
+		},
+		resolve(...paths: string[]): string {
+			return path.resolve(...paths);
+		},
+	};
+}
+
+export function createNodeBackendHostAdapter(): BackendHostAdapter {
+	return {
+		lockMetadata(input) {
+			return {
+				pid: process.pid,
+				createdAt: new Date().toISOString(),
+				canonicalPathKey: input.canonicalPathKey,
+			};
+		},
+	};
+}
+
+export function createNodeBackendRuntime(options: BackendRuntimeOptions = {}): BackendRuntime {
+	return new BackendRuntime({
+		...options,
+		fileSystem: options.fileSystem ?? createNodeBackendFileSystem(),
+		host: options.host ?? createNodeBackendHostAdapter(),
+	});
+}
+
+export { BackendRuntime };
+export type {
+	BackendFileHandle,
+	BackendFileStat,
+	BackendFileSystem,
+	BackendHostAdapter,
+	BackendRuntimeOptions,
+} from './runtime.js';

package/src/runtime.ts

@@ -1,11 +1,10 @@
 import {
 	UAM_SUPPORTED_MATERIALIZATION_SCOPE,
+	UAM_SUPPORTED_TRANSACTION_SCOPE,
+	type UamProject,
 	type UamTransactionOperation,
-} from '@openfairygui/core';
-import type { ApplyUamTransactionAppError } from '@openfairygui/functions';
-import fs from 'node:fs/promises';
-import type { Stats } from 'node:fs';
-import path from 'node:path';
+} from '@openfairygui/core/uam';
+import type { ApplyUamTransactionAppError } from '@openfairygui/functions/uam';
 import {
 	BACKEND_CAPABILITY_SCHEMA_VERSION,
 	BACKEND_COMPATIBILITY_POLICY,
@@ -27,8 +26,13 @@ export interface BackendFileHandle {
 	close(): Promise<void>;
 }
 
+export interface BackendFileStat {
+	isFile(): boolean;
+	isDirectory(): boolean;
+}
+
 export interface BackendFileSystem {
-	stat(filePath: string): Promise<Stats>;
+	stat(filePath: string): Promise<BackendFileStat>;
 	readdir(dirPath: string): Promise<string[]>;
 	readFile(filePath: string): Promise<string>;
 	readFileRaw(filePath: string): Promise<Uint8Array>;
@@ -43,6 +47,50 @@ export interface BackendFileSystem {
 	resolve(...paths: string[]): string;
 }
 
+export interface BackendHostAdapter {
+	lockMetadata?(input: { canonicalPathKey: string; canonicalProjectPath: string; lockFilePath: string }): unknown;
+}
+
+export interface BackendArtifactBridgeCapability {
+	available: false;
+	requiredHost: 'node';
+	executionBoundary: 'external-bridge';
+	bridgeEntrypoint: '@openfairygui/backend/node';
+	reason: string;
+}
+
+export interface BackendCapabilityManifest {
+	browserSafe: true;
+	rootEntrypoint: '@openfairygui/backend';
+	nodeEntrypoint: '@openfairygui/backend/node';
+	adapters: {
+		fileSystem: {
+			injected: true;
+			requiredFor: readonly ['openSession', 'saveSession', 'materializeSession'];
+		};
+		projectStorage: {
+			injected: true;
+			browserSafe: true;
+			requiredFor: readonly ['openProjectSession.writeback', 'saveSession', 'materializeSession'];
+			adapterFactory: 'createBackendStorageFileSystem';
+		};
+		host: {
+			injected: true;
+			requiredFor: readonly ['advisoryLockMetadata'];
+		};
+	};
+	executionBoundaries: {
+		projectSession: 'in-process-browser-safe';
+		fileBackedSession: 'adapter-backed';
+		artifactPublish: BackendArtifactBridgeCapability;
+		artifactRestore: BackendArtifactBridgeCapability;
+	};
+	diagnostics: {
+		stableCodes: true;
+		errorDiagnosticMirror: true;
+	};
+}
+
 export interface BackendCapabilities {
 	contractVersion: typeof BACKEND_CONTRACT_VERSION;
 	capabilitySchemaVersion: typeof BACKEND_CAPABILITY_SCHEMA_VERSION;
@@ -52,9 +100,11 @@ export interface BackendCapabilities {
 	methods: readonly [
 		'getCapabilities',
 		'openSession',
+		'openProjectSession',
 		'getSession',
 		'applyTransaction',
 		'saveSession',
+		'materializeSession',
 		'closeSession',
 		'getEvents',
 		'getJob',
@@ -73,13 +123,21 @@ export interface BackendCapabilities {
 		resourceKinds: readonly string[];
 		nodeKinds: readonly string[];
 		gearKinds: readonly string[];
+		transactionScope: {
+			resourceKinds: readonly string[];
+			nodeKinds: readonly string[];
+			gearKinds: readonly string[];
+		};
 		unsupported: readonly ['artifact.publish', 'artifact.restore'];
 	};
 	artifact: {
 		publish: false;
 		restore: false;
-		status: 'deferred';
+		status: 'bridge-required';
+		publishBridge: BackendArtifactBridgeCapability;
+		restoreBridge: BackendArtifactBridgeCapability;
 	};
+	manifest: BackendCapabilityManifest;
 	compatibilityPolicy: typeof BACKEND_COMPATIBILITY_POLICY;
 	runtime: {
 		sessionRuntime: true;
@@ -127,6 +185,16 @@ export interface BackendSessionSnapshot {
 	capabilities: BackendCapabilities;
 }
 
+export interface MaterializeSessionSnapshot extends BackendSessionSnapshot {
+	mode: 'fullProject';
+	reason?: string;
+	materializeRevision: number;
+	saveRevision: number;
+	writtenPaths: string[];
+	skippedPaths: string[];
+	diagnostics: import('./contracts.js').BackendDiagnostic[];
+}
+
 export interface BackendSuccess<T> {
 	ok: true;
 	meta: BackendResponseMeta;
@@ -140,9 +208,7 @@ export interface BackendFailure<E extends BackendError = BackendError> {
 	session?: BackendSessionSnapshot;
 }
 
-export type BackendResult<T, E extends BackendError = BackendError> =
-	| BackendSuccess<T>
-	| BackendFailure<E>;
+export type BackendResult<T, E extends BackendError = BackendError> = BackendSuccess<T> | BackendFailure<E>;
 
 export interface SessionNotFoundError {
 	code: 'session_not_found';
@@ -189,6 +255,29 @@ export interface SavePartialFailureError {
 	diskMayBePartiallyUpdated: true;
 }
 
+export interface MaterializeValidationFailedError {
+	code: 'materialize_validation_failed';
+	message: string;
+	sessionId: string;
+	canonicalPathKey: string;
+	issueCount: number;
+	diagnostics: import('./contracts.js').BackendDiagnostic[];
+}
+
+export interface MaterializeWriteFailedError {
+	code: 'write_failed';
+	message: string;
+	sessionId: string;
+	canonicalPathKey: string;
+	attemptedRevision: number;
+	lastSavedRevision: number;
+	writtenPaths: string[];
+	failedPaths: string[];
+	skippedPaths: string[];
+	diagnostics: import('./contracts.js').BackendDiagnostic[];
+	diskMayBePartiallyUpdated: true;
+}
+
 export type BackendEventKind =
 	| 'session.opened'
 	| 'transaction.applied'
@@ -319,6 +408,15 @@ export interface CacheRefreshFailedError {
 	causeCode?: string;
 }
 
+export interface BackendCapabilityUnavailableError {
+	code: 'capability_unavailable';
+	message: string;
+	capability: 'fileSystem' | 'artifact.publish' | 'artifact.restore';
+	requiredAdapter?: 'BackendFileSystem';
+	requiredHost?: 'node';
+	bridgeBoundary?: 'external-bridge';
+}
+
 export type BackendJobErrors =
 	| BackendJobNotFoundError
 	| BackendJobNotCancellableError
@@ -360,12 +458,15 @@ export type BackendError =
 	| InProcessLockConflictError
 	| AdvisoryLockConflictError
 	| SavePartialFailureError
+	| MaterializeValidationFailedError
+	| MaterializeWriteFailedError
 	| PathPolicyViolationError
 	| EventCursorInvalidError
 	| BackendJobNotFoundError
 	| BackendJobNotCancellableError
 	| BackendJobCancelledError
 	| CacheRefreshFailedError
+	| BackendCapabilityUnavailableError
 	| ApplyUamTransactionAppError;
 
 export interface ApplySessionTransactionInput {
@@ -374,16 +475,53 @@ export interface ApplySessionTransactionInput {
 	operations: UamTransactionOperation[];
 }
 
+export interface OpenProjectSessionInput {
+	project: UamProject;
+	sessionId?: string;
+	canonicalProjectPath?: string;
+	canonicalPathKey?: string;
+	storage?: BackendProjectSessionStorage;
+}
+
+export interface BackendProjectSessionStorage {
+	fileSystem: BackendFileSystem;
+	fairyPath: string;
+	canonicalProjectPath?: string;
+	canonicalPathKey?: string;
+}
+
+export interface SaveSessionInput {
+	sessionId: string;
+	expectedRevision?: number;
+	targetPath?: string;
+	fileSystem?: BackendFileSystem;
+	force?: boolean;
+	mode?: 'materializeCleanSession';
+}
+
+export interface MaterializeSessionInput {
+	sessionId: string;
+	expectedRevision?: number;
+	storage?: BackendProjectSessionStorage;
+	targetPath?: string;
+	fileSystem?: BackendFileSystem;
+	mode?: 'fullProject';
+	reason?: string;
+}
+
 export interface BackendRuntimeOptions {
 	fileSystem?: BackendFileSystem;
+	host?: BackendHostAdapter;
 }
 
 const BACKEND_METHODS = [
 	'getCapabilities',
 	'openSession',
+	'openProjectSession',
 	'getSession',
 	'applyTransaction',
 	'saveSession',
+	'materializeSession',
 	'closeSession',
 	'getEvents',
 	'getJob',
@@ -393,6 +531,14 @@ const BACKEND_METHODS = [
 	'refreshCache',
 ] as const;
 
+const ARTIFACT_BRIDGE_CAPABILITY = {
+	available: false,
+	requiredHost: 'node',
+	executionBoundary: 'external-bridge',
+	bridgeEntrypoint: '@openfairygui/backend/node',
+	reason: 'publish/restore require explicit Node-hosted filesystem and artifact execution.',
+} as const satisfies BackendArtifactBridgeCapability;
+
 function createCapabilities(): BackendCapabilities {
 	return {
 		contractVersion: BACKEND_CONTRACT_VERSION,
@@ -411,9 +557,45 @@ function createCapabilities(): BackendCapabilities {
 			resourceKinds: [...UAM_SUPPORTED_MATERIALIZATION_SCOPE.resourceKinds],
 			nodeKinds: [...UAM_SUPPORTED_MATERIALIZATION_SCOPE.nodeKinds],
 			gearKinds: [...UAM_SUPPORTED_MATERIALIZATION_SCOPE.gearKinds],
+			transactionScope: {
+				resourceKinds: [...UAM_SUPPORTED_TRANSACTION_SCOPE.resourceKinds],
+				nodeKinds: [...UAM_SUPPORTED_TRANSACTION_SCOPE.nodeKinds],
+				gearKinds: [...UAM_SUPPORTED_TRANSACTION_SCOPE.gearKinds],
+			},
 			unsupported: ['artifact.publish', 'artifact.restore'],
 		},
 		artifact: createArtifactCapabilities(),
+		manifest: {
+			browserSafe: true,
+			rootEntrypoint: '@openfairygui/backend',
+			nodeEntrypoint: '@openfairygui/backend/node',
+			adapters: {
+				fileSystem: {
+					injected: true,
+					requiredFor: ['openSession', 'saveSession', 'materializeSession'],
+				},
+				projectStorage: {
+					injected: true,
+					browserSafe: true,
+					requiredFor: ['openProjectSession.writeback', 'saveSession', 'materializeSession'],
+					adapterFactory: 'createBackendStorageFileSystem',
+				},
+				host: {
+					injected: true,
+					requiredFor: ['advisoryLockMetadata'],
+				},
+			},
+			executionBoundaries: {
+				projectSession: 'in-process-browser-safe',
+				fileBackedSession: 'adapter-backed',
+				artifactPublish: ARTIFACT_BRIDGE_CAPABILITY,
+				artifactRestore: ARTIFACT_BRIDGE_CAPABILITY,
+			},
+			diagnostics: {
+				stableCodes: true,
+				errorDiagnosticMirror: true,
+			},
+		},
 		compatibilityPolicy: BACKEND_COMPATIBILITY_POLICY,
 		runtime: {
 			sessionRuntime: true,
@@ -446,65 +628,8 @@ function createCapabilities(): BackendCapabilities {
 	};
 }
 
-export function createNodeBackendFileSystem(): BackendFileSystem {
-	return {
-		stat(filePath: string): Promise<Stats> {
-			return fs.stat(filePath);
-		},
-		readdir(dirPath: string): Promise<string[]> {
-			return fs.readdir(dirPath);
-		},
-		readFile(filePath: string): Promise<string> {
-			return fs.readFile(filePath, 'utf-8');
-		},
-		async readFileRaw(filePath: string): Promise<Uint8Array> {
-			const buffer = await fs.readFile(filePath);
-			return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
-		},
-		writeFile(filePath: string, content: string): Promise<void> {
-			return fs.writeFile(filePath, content, 'utf-8');
-		},
-		writeFileRaw(filePath: string, data: Uint8Array): Promise<void> {
-			return fs.writeFile(filePath, data);
-		},
-		async mkdir(dirPath: string, options?: { recursive?: boolean }): Promise<void> {
-			await fs.mkdir(dirPath, { recursive: options?.recursive ?? false });
-		},
-		async resolvePath(filePath: string): Promise<string> {
-			try {
-				return await fs.realpath(filePath);
-			} catch {
-				return path.resolve(filePath);
-			}
-		},
-		async openExclusive(filePath: string): Promise<BackendFileHandle> {
-			const handle = await fs.open(filePath, 'wx');
-			return {
-				writeFile(content: string): Promise<void> {
-					return handle.writeFile(content, 'utf-8');
-				},
-				close(): Promise<void> {
-					return handle.close();
-				},
-			};
-		},
-		unlink(filePath: string): Promise<void> {
-			return fs.unlink(filePath);
-		},
-		join(...paths: string[]): string {
-			return path.join(...paths);
-		},
-		dirname(filePath: string): string {
-			return path.dirname(filePath);
-		},
-		resolve(...paths: string[]): string {
-			return path.resolve(...paths);
-		},
-	};
-}
-
 export class BackendRuntime {
-	private readonly fileSystem: BackendFileSystem;
+	private readonly fileSystem?: BackendFileSystem;
 	private readonly capabilities: BackendCapabilities;
 	private readonly sessions = new Map<string, BackendSessionState>();
 	private readonly sessionsByPath = new Map<string, string>();
@@ -521,10 +646,11 @@ export class BackendRuntime {
 	private readonly jobService: JobService;
 
 	public constructor(options: BackendRuntimeOptions = {}) {
-		this.fileSystem = options.fileSystem ?? createNodeBackendFileSystem();
+		this.fileSystem = options.fileSystem;
 		this.capabilities = createCapabilities();
 		this.context = {
 			fileSystem: this.fileSystem,
+			host: options.host,
 			capabilities: this.capabilities,
 			sessions: this.sessions,
 			sessionsByPath: this.sessionsByPath,
@@ -548,37 +674,82 @@ export class BackendRuntime {
 		return this.readService.getCapabilities() as BackendSuccess<BackendCapabilities>;
 	}
 
-	public async openSession(input: { projectPath: string }): Promise<BackendResult<BackendSessionSnapshot, InProcessLockConflictError | AdvisoryLockConflictError>> {
+	public async openSession(input: {
+		projectPath: string;
+	}): Promise<
+		BackendResult<
+			BackendSessionSnapshot,
+			InProcessLockConflictError | AdvisoryLockConflictError | BackendCapabilityUnavailableError
+		>
+	> {
 		return this.runtimeService.openSession(input);
 	}
 
+	public openProjectSession(input: OpenProjectSessionInput): BackendResult<BackendSessionSnapshot> {
+		return this.runtimeService.openProjectSession(input);
+	}
+
 	public getSession(input: { sessionId: string }): BackendResult<BackendSessionSnapshot, SessionNotFoundError> {
 		return this.readService.getSession(input);
 	}
 
 	public async applyTransaction(
 		input: ApplySessionTransactionInput,
-	): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError>> {
+	): Promise<
+		BackendResult<
+			BackendSessionSnapshot,
+			SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError
+		>
+	> {
 		return this.authoringService.applyTransaction(input);
 	}
 
-	public async saveSession(
-		input: { sessionId: string; expectedRevision?: number; targetPath?: string },
-	): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | PathPolicyViolationError>> {
+	public async saveSession(input: SaveSessionInput): Promise<
+		BackendResult<
+			BackendSessionSnapshot | MaterializeSessionSnapshot,
+			| SessionNotFoundError
+			| SessionStaleWriteError
+			| SavePartialFailureError
+			| MaterializeValidationFailedError
+			| MaterializeWriteFailedError
+			| PathPolicyViolationError
+			| InProcessLockConflictError
+			| BackendCapabilityUnavailableError
+		>
+	> {
 		return this.authoringService.saveSession(input);
 	}
 
-	public async closeSession(
-		input: { sessionId: string },
-	): Promise<BackendResult<{ sessionId: string; closed: true }, SessionNotFoundError>> {
+	public async materializeSession(input: MaterializeSessionInput): Promise<
+		BackendResult<
+			MaterializeSessionSnapshot,
+			| SessionNotFoundError
+			| SessionStaleWriteError
+			| MaterializeValidationFailedError
+			| MaterializeWriteFailedError
+			| PathPolicyViolationError
+			| InProcessLockConflictError
+			| BackendCapabilityUnavailableError
+		>
+	> {
+		return this.authoringService.materializeSession(input);
+	}
+
+	public async closeSession(input: {
+		sessionId: string;
+	}): Promise<BackendResult<{ sessionId: string; closed: true }, SessionNotFoundError>> {
 		return this.runtimeService.closeSession(input);
 	}
 
-	public getEvents(input: GetEventsInput): BackendResult<GetEventsSnapshot, SessionNotFoundError | EventCursorInvalidError> {
+	public getEvents(
+		input: GetEventsInput,
+	): BackendResult<GetEventsSnapshot, SessionNotFoundError | EventCursorInvalidError> {
 		return this.eventService.getEvents(input);
 	}
 
-	public getJob(input: GetJobInput): BackendResult<BackendJobSnapshot, SessionNotFoundError | BackendJobNotFoundError> {
+	public getJob(
+		input: GetJobInput,
+	): BackendResult<BackendJobSnapshot, SessionNotFoundError | BackendJobNotFoundError> {
 		return this.jobService.getJob(input);
 	}
 
@@ -586,7 +757,12 @@ export class BackendRuntime {
 		return this.jobService.listJobs(input);
 	}
 
-	public cancelJob(input: CancelJobInput): BackendResult<BackendJobSnapshot, SessionNotFoundError | BackendJobNotFoundError | BackendJobNotCancellableError> {
+	public cancelJob(
+		input: CancelJobInput,
+	): BackendResult<
+		BackendJobSnapshot,
+		SessionNotFoundError | BackendJobNotFoundError | BackendJobNotCancellableError
+	> {
 		return this.jobService.cancelJob(input);
 	}
 

package/src/services/artifact-service.ts

@@ -1,9 +1,19 @@
 import type { BackendCapabilities } from '../runtime.js';
 
 export function createArtifactCapabilities(): BackendCapabilities['artifact'] {
+	const bridge = {
+		available: false,
+		requiredHost: 'node',
+		executionBoundary: 'external-bridge',
+		bridgeEntrypoint: '@openfairygui/backend/node',
+		reason: 'publish/restore require explicit Node-hosted filesystem and artifact execution.',
+	} as const;
+
 	return {
 		publish: false,
 		restore: false,
-		status: 'deferred',
+		status: 'bridge-required',
+		publishBridge: bridge,
+		restoreBridge: bridge,
 	};
 }