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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@openfairygui/backend",
-	"version": "0.2.0-alpha.0",
+	"version": "0.2.0-alpha.1",
 	"description": "FairyGUI Headless Authoring SDK — stateful backend runtime and session services.",
 	"author": "OpenFairyGUI Contributors",
 	"license": "MIT",
@@ -19,18 +19,30 @@
 	"module": "./dist/index.mjs",
 	"types": "./dist/index.d.mts",
 	"exports": {
-		"require": {
-			"types": "./dist/index.d.cts",
-			"default": "./dist/index.cjs"
+		".": {
+			"require": {
+				"types": "./dist/index.d.cts",
+				"default": "./dist/index.cjs"
+			},
+			"default": {
+				"types": "./dist/index.d.mts",
+				"default": "./dist/index.mjs"
+			}
 		},
-		"default": {
-			"types": "./dist/index.d.mts",
-			"default": "./dist/index.mjs"
+		"./node": {
+			"require": {
+				"types": "./dist/node.d.cts",
+				"default": "./dist/node.cjs"
+			},
+			"default": {
+				"types": "./dist/node.d.mts",
+				"default": "./dist/node.mjs"
+			}
 		}
 	},
 	"scripts": {
-		"build": "tsdown --format esm,cjs --platform node --external node:fs --external node:fs/promises --external node:path --env.PACKAGE_VERSION=$npm_package_version",
-		"build:watch": "tsdown --watch --format esm,cjs --platform node --env.PACKAGE_VERSION=$npm_package_version"
+		"build": "tsdown src/index.ts src/node.ts --format esm,cjs --platform node --external node:fs --external node:fs/promises --external node:path --env.PACKAGE_VERSION=$npm_package_version",
+		"build:watch": "tsdown src/index.ts src/node.ts --watch --format esm,cjs --platform node --external node:fs --external node:fs/promises --external node:path --env.PACKAGE_VERSION=$npm_package_version"
 	},
 	"files": [
 		"dist/",

package/src/index.ts

@@ -1,17 +1,21 @@
 export {
 	BackendRuntime,
-	createNodeBackendFileSystem,
 	type AdvisoryLockConflictError,
 	type ApplySessionTransactionInput,
+	type BackendArtifactBridgeCapability,
 	type BackendCacheEntry,
 	type BackendCacheSnapshot,
+	type BackendCapabilityManifest,
+	type BackendCapabilityUnavailableError,
 	type BackendCapabilities,
 	type BackendError,
 	type BackendEvent,
 	type BackendEventKind,
 	type BackendFailure,
 	type BackendFileHandle,
+	type BackendFileStat,
 	type BackendFileSystem,
+	type BackendHostAdapter,
 	type BackendJobKind,
 	type BackendJobListSnapshot,
 	type BackendJobListStatusFilter,
@@ -34,6 +38,7 @@ export {
 	type GetJobInput,
 	type InProcessLockConflictError,
 	type ListJobsInput,
+	type OpenProjectSessionInput,
 	type RefreshCacheInput,
 	type SavePartialFailureError,
 	type SessionNotFoundError,

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,9 @@
 import {
 	UAM_SUPPORTED_MATERIALIZATION_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';
 import {
 	BACKEND_CAPABILITY_SCHEMA_VERSION,
 	BACKEND_COMPATIBILITY_POLICY,
@@ -27,8 +25,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 +46,48 @@ 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'];
+		};
+		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,6 +97,7 @@ export interface BackendCapabilities {
 	methods: readonly [
 		'getCapabilities',
 		'openSession',
+		'openProjectSession',
 		'getSession',
 		'applyTransaction',
 		'saveSession',
@@ -78,8 +124,11 @@ export interface BackendCapabilities {
 	artifact: {
 		publish: false;
 		restore: false;
-		status: 'deferred';
+		status: 'bridge-required';
+		publishBridge: BackendArtifactBridgeCapability;
+		restoreBridge: BackendArtifactBridgeCapability;
 	};
+	manifest: BackendCapabilityManifest;
 	compatibilityPolicy: typeof BACKEND_COMPATIBILITY_POLICY;
 	runtime: {
 		sessionRuntime: true;
@@ -319,6 +368,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
@@ -366,6 +424,7 @@ export type BackendError =
 	| BackendJobNotCancellableError
 	| BackendJobCancelledError
 	| CacheRefreshFailedError
+	| BackendCapabilityUnavailableError
 	| ApplyUamTransactionAppError;
 
 export interface ApplySessionTransactionInput {
@@ -374,14 +433,23 @@ export interface ApplySessionTransactionInput {
 	operations: UamTransactionOperation[];
 }
 
+export interface OpenProjectSessionInput {
+	project: UamProject;
+	sessionId?: string;
+	canonicalProjectPath?: string;
+	canonicalPathKey?: string;
+}
+
 export interface BackendRuntimeOptions {
 	fileSystem?: BackendFileSystem;
+	host?: BackendHostAdapter;
 }
 
 const BACKEND_METHODS = [
-	'getCapabilities',
-	'openSession',
-	'getSession',
+		'getCapabilities',
+		'openSession',
+		'openProjectSession',
+		'getSession',
 	'applyTransaction',
 	'saveSession',
 	'closeSession',
@@ -389,10 +457,18 @@ const BACKEND_METHODS = [
 	'getJob',
 	'listJobs',
 	'cancelJob',
-	'getCacheSnapshot',
-	'refreshCache',
+		'getCacheSnapshot',
+		'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,
@@ -414,6 +490,31 @@ function createCapabilities(): BackendCapabilities {
 			unsupported: ['artifact.publish', 'artifact.restore'],
 		},
 		artifact: createArtifactCapabilities(),
+		manifest: {
+			browserSafe: true,
+			rootEntrypoint: '@openfairygui/backend',
+			nodeEntrypoint: '@openfairygui/backend/node',
+			adapters: {
+				fileSystem: {
+					injected: true,
+					requiredFor: ['openSession', 'saveSession'],
+				},
+				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 +547,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 +565,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,10 +593,14 @@ 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);
 	}
@@ -564,7 +613,7 @@ export class BackendRuntime {
 
 	public async saveSession(
 		input: { sessionId: string; expectedRevision?: number; targetPath?: string },
-	): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | PathPolicyViolationError>> {
+	): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | PathPolicyViolationError | BackendCapabilityUnavailableError>> {
 		return this.authoringService.saveSession(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,
 	};
 }

package/src/services/authoring-service.ts

@@ -5,6 +5,7 @@ import { failure, success, type BackendContext } from './context.js';
 import type { EventService } from './event-service.js';
 import type {
 	ApplySessionTransactionInput,
+	BackendCapabilityUnavailableError,
 	BackendFileSystem,
 	BackendResult,
 	BackendSessionSnapshot,
@@ -123,19 +124,31 @@ export class AuthoringService {
 
 	public async saveSession(
 		input: { sessionId: string; expectedRevision?: number; targetPath?: string },
-	): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | PathPolicyViolationError>> {
+	): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | PathPolicyViolationError | BackendCapabilityUnavailableError>> {
 		const startedAt = Date.now();
 		const session = this.context.sessions.get(input.sessionId);
 		if (!session || session.closed) {
 			return failure('authoring', startedAt, createSessionNotFoundError(input.sessionId));
 		}
+		if (!this.context.fileSystem) {
+			return failure('authoring', startedAt, {
+				code: 'capability_unavailable',
+				message: 'saveSession requires an injected BackendFileSystem adapter.',
+				capability: 'fileSystem',
+				requiredAdapter: 'BackendFileSystem',
+			}, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+			});
+		}
 		if (input.expectedRevision !== undefined && input.expectedRevision !== session.revision) {
 			return failure('authoring', startedAt, createStaleWriteError(session, input.expectedRevision), toSessionSnapshot(session, this.context.capabilities), {
 				sessionId: session.sessionId,
 				revision: session.revision,
 			});
 		}
-		const targetViolation = await validateSaveTarget(this.context.fileSystem, session.fairyPath, input.targetPath);
+		const fileSystem = this.context.fileSystem;
+		const targetViolation = await validateSaveTarget(fileSystem, session.fairyPath, input.targetPath);
 		if (targetViolation) {
 			return failure('authoring', startedAt, targetViolation, toSessionSnapshot(session, this.context.capabilities), {
 				sessionId: session.sessionId,
@@ -153,7 +166,7 @@ export class AuthoringService {
 		const failedPaths: string[] = [];
 		this.eventService.emit({ kind: 'save.started', sessionId: session.sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision });
 		try {
-			const writer = new ProjectWriter(createWriterFileSystem(this.context.fileSystem, committedPaths, failedPaths));
+			const writer = new ProjectWriter(createWriterFileSystem(fileSystem, committedPaths, failedPaths));
 			await writer.write(materializeUamProject(session.project), session.fairyPath);
 			session.lastSavedRevision = session.revision;
 			session.dirty = false;

package/src/services/context.ts

@@ -5,6 +5,7 @@ import type {
 	BackendEvent,
 	BackendFailure,
 	BackendFileSystem,
+	BackendHostAdapter,
 	BackendJobSnapshot,
 	BackendSessionSnapshot,
 	BackendSuccess,
@@ -33,7 +34,8 @@ export interface BackendSessionState {
 }
 
 export interface BackendContext {
-	fileSystem: BackendFileSystem;
+	fileSystem?: BackendFileSystem;
+	host?: BackendHostAdapter;
 	capabilities: BackendCapabilities;
 	sessions: Map<string, BackendSessionState>;
 	sessionsByPath: Map<string, string>;
@@ -43,6 +45,14 @@ export interface BackendContext {
 	nextEventSequence: () => number;
 }
 
+function diagnosticFromError(error: BackendError): BackendDiagnostic {
+	return {
+		code: error.code,
+		message: error.message,
+		severity: 'error',
+	};
+}
+
 function randomId(): string {
 	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
@@ -103,9 +113,10 @@ export function failure<E extends BackendError>(
 		diagnostics?: BackendDiagnostic[];
 	},
 ): BackendFailure<E> {
+	const diagnostics = options?.diagnostics ?? [diagnosticFromError(error)];
 	return {
 		ok: false,
-		meta: createMeta(stage, startedAt, options),
+		meta: createMeta(stage, startedAt, { ...options, diagnostics }),
 		error,
 		session,
 	};

package/src/services/event-service.ts

@@ -51,7 +51,7 @@ export class EventService {
 				after: String(input.after),
 			});
 		}
-		if (events.length > 0 && after < oldestSequence - 1) {
+		if (events.length > 0 && after !== 0 && after < oldestSequence - 1) {
 			return failure('runtime', startedAt, {
 				code: 'event_cursor_invalid',
 				message: `Event cursor has expired: ${after}`,