@openfairygui/backend 0.2.0-alpha.9 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/backend",
-  "version": "0.2.0-alpha.9",
+  "version": "0.2.0",
   "description": "FairyGUI Headless Authoring SDK — stateful backend runtime and session services.",
   "author": "OpenFairyGUI Contributors",
   "license": "MIT",
@@ -52,15 +52,16 @@
     "runtime"
   ],
   "dependencies": {
-    "@openfairygui/core": "0.2.0-alpha.9",
-    "@openfairygui/functions": "0.2.0-alpha.8"
+    "@openfairygui/core": "0.2.0",
+    "@openfairygui/functions": "0.2.0"
   },
   "devDependencies": {
     "ava": "^7.0.0",
-    "tsx": "^4.0.0"
+    "tsx": "^4.0.0",
+    "@openfairygui/test-utils": "0.2.0-alpha.10"
   },
   "scripts": {
-    "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"
+    "build": "tsdown",
+    "build:watch": "tsdown --watch"
   }
 }

package/src/index.ts

@@ -1,21 +1,29 @@
 export {
-	BackendRuntime,
+	BACKEND_CAPABILITY_SCHEMA_VERSION,
+	BACKEND_COMPATIBILITY_POLICY,
+	BACKEND_CONTRACT_VERSION,
+	type BackendDiagnostic,
+	type BackendMessage,
+	type BackendResponseMeta,
+	type BackendStage,
+} from './contracts.js';
+export {
 	type AdvisoryLockConflictError,
 	type ApplySessionTransactionInput,
 	type BackendArtifactBridgeCapability,
 	type BackendCacheEntry,
 	type BackendCacheSnapshot,
+	type BackendCapabilities,
 	type BackendCapabilityManifest,
 	type BackendCapabilityUnavailableError,
-	type BackendCapabilities,
 	type BackendError,
 	type BackendEvent,
 	type BackendEventKind,
 	type BackendFailure,
-	type BackendFileHandle,
 	type BackendFileStat,
 	type BackendFileSystem,
 	type BackendHostAdapter,
+	type BackendJobErrors,
 	type BackendJobKind,
 	type BackendJobListSnapshot,
 	type BackendJobListStatusFilter,
@@ -24,11 +32,13 @@ export {
 	type BackendJobProgress,
 	type BackendJobSnapshot,
 	type BackendJobStatus,
-	type BackendJobErrors,
+	type BackendProjectSessionStorage,
 	type BackendResult,
+	BackendRuntime,
+	type BackendRuntimeOptions,
+	type BackendSessionLock,
 	type BackendSessionSnapshot,
 	type BackendSuccess,
-	type BackendRuntimeOptions,
 	type CacheRefreshFailedError,
 	type CancelJobInput,
 	type EventCursorInvalidError,
@@ -43,25 +53,16 @@ export {
 	type MaterializeValidationFailedError,
 	type MaterializeWriteFailedError,
 	type OpenProjectSessionInput,
-	type BackendProjectSessionStorage,
 	type RefreshCacheInput,
-	type SaveSessionInput,
 	type SavePartialFailureError,
+	type SaveSessionInput,
 	type SessionNotFoundError,
 	type SessionStaleWriteError,
+	type UamFidelityUnsupportedError,
 } from './runtime.js';
 export {
-	createBackendStorageFileSystem,
 	type BackendAsyncStorageAdapter,
 	type BackendStorageFileSystem,
 	type BackendStorageStatLike,
+	createBackendStorageFileSystem,
 } from './storage.js';
-export {
-	type BackendDiagnostic,
-	type BackendMessage,
-	type BackendResponseMeta,
-	type BackendStage,
-	BACKEND_CAPABILITY_SCHEMA_VERSION,
-	BACKEND_COMPATIBILITY_POLICY,
-	BACKEND_CONTRACT_VERSION,
-} from './contracts.js';

package/src/node.ts

@@ -2,11 +2,11 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
 	BackendRuntime,
-	type BackendFileHandle,
 	type BackendFileStat,
 	type BackendFileSystem,
 	type BackendHostAdapter,
 	type BackendRuntimeOptions,
+	type BackendSessionLock,
 } from './runtime.js';
 
 export function createNodeBackendFileSystem(): BackendFileSystem {
@@ -40,20 +40,36 @@ export function createNodeBackendFileSystem(): BackendFileSystem {
 				return path.resolve(filePath);
 			}
 		},
-		async openExclusive(filePath: string): Promise<BackendFileHandle> {
+		async acquireSessionLock(filePath: string): Promise<BackendSessionLock> {
 			const handle = await fs.open(filePath, 'wx');
+			let closed = false;
+			let released = false;
+			const closeHandle = async (): Promise<void> => {
+				if (closed) return;
+				await handle.close();
+				closed = true;
+			};
 			return {
-				writeFile(content: string): Promise<void> {
-					return handle.writeFile(content, 'utf-8');
+				async writeMetadata(content: string): Promise<void> {
+					await handle.writeFile(content, 'utf-8');
+					await closeHandle();
 				},
-				close(): Promise<void> {
-					return handle.close();
+				async release(): Promise<void> {
+					if (released) return;
+					await closeHandle();
+					await fs.unlink(filePath).catch((error: NodeJS.ErrnoException) => {
+						if (error.code !== 'ENOENT') throw error;
+					});
+					released = true;
 				},
 			};
 		},
 		unlink(filePath: string): Promise<void> {
 			return fs.unlink(filePath);
 		},
+		rmdir(dirPath: string): Promise<void> {
+			return fs.rmdir(dirPath);
+		},
 		join(...paths: string[]): string {
 			return path.join(...paths);
 		},
@@ -86,11 +102,11 @@ export function createNodeBackendRuntime(options: BackendRuntimeOptions = {}): B
 	});
 }
 
-export { BackendRuntime };
 export type {
-	BackendFileHandle,
 	BackendFileStat,
 	BackendFileSystem,
 	BackendHostAdapter,
 	BackendRuntimeOptions,
+	BackendSessionLock,
 } from './runtime.js';
+export { BackendRuntime };

package/src/runtime/capabilities.ts

@@ -0,0 +1,126 @@
+import {
+	UAM_SUPPORTED_MATERIALIZATION_SCOPE,
+	UAM_SUPPORTED_TRANSACTION_SCOPE,
+} from '@openfairygui/core/uam';
+import {
+	BACKEND_CAPABILITY_SCHEMA_VERSION,
+	BACKEND_COMPATIBILITY_POLICY,
+	BACKEND_CONTRACT_VERSION,
+} from '../contracts.js';
+import { createRuntimePathPolicy } from '../path-policy.js';
+import { createArtifactCapabilities } from '../services/artifact-service.js';
+import type { BackendArtifactBridgeCapability, BackendCapabilities } from './contracts.js';
+
+const BACKEND_METHODS = [
+	'getCapabilities',
+	'openSession',
+	'openProjectSession',
+	'getSession',
+	'applyTransaction',
+	'saveSession',
+	'materializeSession',
+	'closeSession',
+	'getEvents',
+	'getJob',
+	'listJobs',
+	'cancelJob',
+	'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;
+
+export function createCapabilities(): BackendCapabilities {
+	return {
+		contractVersion: BACKEND_CONTRACT_VERSION,
+		capabilitySchemaVersion: BACKEND_CAPABILITY_SCHEMA_VERSION,
+		transactionKernelOwner: '@openfairygui/core',
+		appSeamOwner: '@openfairygui/functions',
+		runtimeOwner: '@openfairygui/backend',
+		methods: BACKEND_METHODS,
+		read: {
+			capabilitySnapshot: true,
+			sessionSnapshot: true,
+		},
+		authoring: {
+			applyTransaction: true,
+			saveSession: true,
+			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,
+			advisoryLocking: true,
+			coordinatedSave: true,
+			atomicSave: false,
+			staleRevisionProtection: true,
+			pathPolicy: createRuntimePathPolicy(),
+			events: {
+				polling: true,
+				subscriptions: false,
+				retentionLimit: 1000,
+				sequenceScope: 'runtime',
+			},
+			jobs: {
+				inMemory: true,
+				cooperativeCancel: true,
+				persistent: false,
+				supportedKinds: ['cache.refresh'],
+				artifactJobs: false,
+				completedRetentionLimit: 100,
+			},
+			cache: {
+				derivedReadOnly: true,
+				keyedBy: 'canonicalPathKey',
+				sourceOfTruth: false,
+				refreshMethod: 'refreshCache',
+			},
+		},
+	};
+}