@openfairygui/backend 0.2.0-alpha.6 → 0.2.0-alpha.8

package/src/services/authoring-service.ts

@@ -1,5 +1,5 @@
 import { ProjectWriter, type FileSystem } from '@openfairygui/core/project-io';
-import { materializeUamProject } from '@openfairygui/core/uam';
+import { materializeUamProject, validateUamProject } from '@openfairygui/core/uam';
 import { applyUamTransactionApp, type ApplyUamTransactionAppError } from '@openfairygui/functions/uam';
 import type { CacheService } from './cache-service.js';
 import { failure, success, type BackendContext } from './context.js';
@@ -10,12 +10,18 @@ import type {
 	BackendFileSystem,
 	BackendResult,
 	BackendSessionSnapshot,
+	InProcessLockConflictError,
+	MaterializeSessionInput,
+	MaterializeSessionSnapshot,
+	MaterializeValidationFailedError,
+	MaterializeWriteFailedError,
+	SaveSessionInput,
 	SavePartialFailureError,
 	SessionNotFoundError,
 	SessionStaleWriteError,
 } from '../runtime.js';
 import type { BackendDiagnostic } from '../contracts.js';
-import { validateSaveTarget, type PathPolicyViolationError } from '../path-policy.js';
+import { normalizeComparablePath, validateSaveTarget, type PathPolicyViolationError } from '../path-policy.js';
 import { createSessionNotFoundError, createStaleWriteError, toSessionSnapshot } from './session-utils.js';
 
 function createWriterFileSystem(
@@ -91,6 +97,63 @@ function toBackendDiagnostics(error: ApplyUamTransactionAppError): BackendDiagno
 		];
 }
 
+function createCapabilityUnavailableError(message: string): BackendCapabilityUnavailableError {
+	return {
+		code: 'capability_unavailable',
+		message,
+		capability: 'fileSystem',
+		requiredAdapter: 'BackendFileSystem',
+	};
+}
+
+function validationDiagnostics(sessionProject: Parameters<typeof validateUamProject>[0]): BackendDiagnostic[] {
+	const issues = validateUamProject(sessionProject);
+	return issues.map((issue) => ({
+		code: 'materialize_validation_failed',
+		message: issue.message,
+		severity: 'error',
+		path: issue.path,
+		operationKind: 'materializeSession',
+	}));
+}
+
+function toMaterializeSnapshot(
+	session: Parameters<typeof toSessionSnapshot>[0],
+	capabilities: Parameters<typeof toSessionSnapshot>[1],
+	input: {
+		reason?: string;
+		writtenPaths: string[];
+		skippedPaths: string[];
+		diagnostics: BackendDiagnostic[];
+	},
+): MaterializeSessionSnapshot {
+	return {
+		...toSessionSnapshot(session, capabilities),
+		mode: 'fullProject',
+		reason: input.reason,
+		materializeRevision: session.revision,
+		saveRevision: session.lastSavedRevision,
+		writtenPaths: [...input.writtenPaths],
+		skippedPaths: [...input.skippedPaths],
+		diagnostics: input.diagnostics.map((diagnostic) => ({ ...diagnostic })),
+	};
+}
+
+function storageCanonicalTarget(input: NonNullable<MaterializeSessionInput['storage']>): {
+	fileSystem: BackendFileSystem;
+	fairyPath: string;
+	canonicalProjectPath: string;
+	canonicalPathKey: string;
+} {
+	const canonicalProjectPath = input.canonicalProjectPath ?? (input.fileSystem.dirname(input.fairyPath) || '.');
+	return {
+		fileSystem: input.fileSystem,
+		fairyPath: input.fairyPath,
+		canonicalProjectPath,
+		canonicalPathKey: input.canonicalPathKey ?? normalizeComparablePath(canonicalProjectPath),
+	};
+}
+
 export class AuthoringService {
 	public constructor(
 		private readonly context: BackendContext,
@@ -180,35 +243,42 @@ export class AuthoringService {
 		});
 	}
 
-	public async saveSession(input: {
-		sessionId: string;
-		expectedRevision?: number;
-		targetPath?: string;
-	}): Promise<
+	public async saveSession(input: SaveSessionInput): Promise<
 		BackendResult<
-			BackendSessionSnapshot,
+			BackendSessionSnapshot | MaterializeSessionSnapshot,
 			| SessionNotFoundError
 			| SessionStaleWriteError
 			| SavePartialFailureError
+			| MaterializeValidationFailedError
+			| MaterializeWriteFailedError
 			| PathPolicyViolationError
+			| InProcessLockConflictError
 			| BackendCapabilityUnavailableError
 		>
 	> {
+		if (input.force === true || input.mode === 'materializeCleanSession') {
+			return this.materializeSession({
+				sessionId: input.sessionId,
+				expectedRevision: input.expectedRevision,
+				targetPath: input.targetPath,
+				fileSystem: input.fileSystem,
+				mode: 'fullProject',
+				reason: 'force_save',
+			});
+		}
 		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) {
+		const fileSystem = input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		if (!fileSystem) {
 			return failure(
 				'authoring',
 				startedAt,
-				{
-					code: 'capability_unavailable',
-					message: 'saveSession requires an injected BackendFileSystem adapter.',
-					capability: 'fileSystem',
-					requiredAdapter: 'BackendFileSystem',
-				},
+				createCapabilityUnavailableError(
+					'saveSession requires an injected BackendFileSystem adapter.',
+				),
 				toSessionSnapshot(session, this.context.capabilities),
 				{
 					sessionId: session.sessionId,
@@ -228,7 +298,6 @@ export class AuthoringService {
 				},
 			);
 		}
-		const fileSystem = this.context.fileSystem;
 		const targetViolation = await validateSaveTarget(fileSystem, session.fairyPath, input.targetPath);
 		if (targetViolation) {
 			return failure(
@@ -310,4 +379,237 @@ export class AuthoringService {
 			);
 		}
 	}
+
+	public async materializeSession(input: MaterializeSessionInput): Promise<
+		BackendResult<
+			MaterializeSessionSnapshot,
+			| SessionNotFoundError
+			| SessionStaleWriteError
+			| MaterializeValidationFailedError
+			| MaterializeWriteFailedError
+			| PathPolicyViolationError
+			| InProcessLockConflictError
+			| 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 (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 storageTarget = input.storage ? storageCanonicalTarget(input.storage) : null;
+		const fileSystem = storageTarget?.fileSystem ?? input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		if (!fileSystem) {
+			return failure(
+				'authoring',
+				startedAt,
+				createCapabilityUnavailableError(
+					'materializeSession requires an injected BackendFileSystem adapter.',
+				),
+				toSessionSnapshot(session, this.context.capabilities),
+				{
+					sessionId: session.sessionId,
+					revision: session.revision,
+				},
+			);
+		}
+
+		const fairyPath = storageTarget?.fairyPath ?? session.fairyPath;
+		const targetViolation = await validateSaveTarget(fileSystem, fairyPath, input.targetPath);
+		if (targetViolation) {
+			return failure(
+				'authoring',
+				startedAt,
+				targetViolation,
+				toSessionSnapshot(session, this.context.capabilities),
+				{
+					sessionId: session.sessionId,
+					revision: session.revision,
+				},
+			);
+		}
+
+		if (storageTarget) {
+			const holderSessionId = this.context.sessionsByPath.get(storageTarget.canonicalPathKey);
+			if (holderSessionId && holderSessionId !== session.sessionId) {
+				return failure(
+					'authoring',
+					startedAt,
+					{
+						code: 'lock_conflict',
+						kind: 'in_process_session_exists',
+						message: `Project is already open in this backend runtime: ${storageTarget.canonicalProjectPath}`,
+						canonicalPathKey: storageTarget.canonicalPathKey,
+						holderSessionId,
+					},
+					toSessionSnapshot(session, this.context.capabilities),
+					{
+						sessionId: session.sessionId,
+						revision: session.revision,
+					},
+				);
+			}
+		}
+
+		const diagnostics = validationDiagnostics(session.project);
+		if (diagnostics.length > 0) {
+			const error: MaterializeValidationFailedError = {
+				code: 'materialize_validation_failed',
+				message: `UAM materialize validation failed with ${diagnostics.length} issue(s).`,
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				issueCount: diagnostics.length,
+				diagnostics,
+			};
+			return failure(
+				'authoring',
+				startedAt,
+				error,
+				toSessionSnapshot(session, this.context.capabilities),
+				{
+					sessionId: session.sessionId,
+					revision: session.revision,
+					diagnostics,
+				},
+			);
+		}
+
+		let document: ReturnType<typeof materializeUamProject>;
+		try {
+			document = materializeUamProject(session.project);
+		} catch (error) {
+			const diagnosticsFromError: BackendDiagnostic[] = [
+				{
+					code: 'materialize_validation_failed',
+					message: error instanceof Error ? error.message : String(error),
+					severity: 'error',
+					operationKind: 'materializeSession',
+				},
+			];
+			return failure(
+				'authoring',
+				startedAt,
+				{
+					code: 'materialize_validation_failed',
+					message: error instanceof Error ? error.message : String(error),
+					sessionId: session.sessionId,
+					canonicalPathKey: session.canonicalPathKey,
+					issueCount: diagnosticsFromError.length,
+					diagnostics: diagnosticsFromError,
+				},
+				toSessionSnapshot(session, this.context.capabilities),
+				{
+					sessionId: session.sessionId,
+					revision: session.revision,
+					diagnostics: diagnosticsFromError,
+				},
+			);
+		}
+
+		const writtenPaths: string[] = [];
+		const failedPaths: string[] = [];
+		const skippedPaths: string[] = [];
+		this.eventService.emit({
+			kind: 'save.started',
+			sessionId: session.sessionId,
+			canonicalPathKey: storageTarget?.canonicalPathKey ?? session.canonicalPathKey,
+			revision: session.revision,
+		});
+		try {
+			const writer = new ProjectWriter(createWriterFileSystem(fileSystem, writtenPaths, failedPaths));
+			await writer.write(document, fairyPath);
+			if (storageTarget) {
+				this.context.sessionsByPath.delete(session.canonicalPathKey);
+				session.fileSystem = storageTarget.fileSystem;
+				session.fairyPath = storageTarget.fairyPath;
+				session.canonicalProjectPath = storageTarget.canonicalProjectPath;
+				session.canonicalPathKey = storageTarget.canonicalPathKey;
+				this.context.sessionsByPath.set(session.canonicalPathKey, session.sessionId);
+			}
+			session.lastSavedRevision = session.revision;
+			session.dirty = false;
+			const cacheEntry = this.cacheService.refreshSession(session);
+			this.eventService.emit({
+				kind: 'save.completed',
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision,
+			});
+			this.eventService.emit({
+				kind: 'cache.updated',
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision,
+				cacheRevision: cacheEntry.revision,
+			});
+			return success(
+				'authoring',
+				startedAt,
+				toMaterializeSnapshot(session, this.context.capabilities, {
+					reason: input.reason,
+					writtenPaths,
+					skippedPaths,
+					diagnostics: [],
+				}),
+				{
+					sessionId: session.sessionId,
+					revision: session.revision,
+				},
+			);
+		} catch (error) {
+			const diagnosticsFromError: BackendDiagnostic[] = [
+				{
+					code: 'write_failed',
+					message: error instanceof Error ? error.message : String(error),
+					severity: 'error',
+					path: failedPaths[0],
+					operationKind: 'materializeSession',
+				},
+			];
+			this.cacheService.invalidateSession(session);
+			this.eventService.emit({
+				kind: 'save.failed',
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision,
+				diagnostics: diagnosticsFromError,
+			});
+			return failure(
+				'authoring',
+				startedAt,
+				{
+					code: 'write_failed',
+					message: error instanceof Error ? error.message : String(error),
+					sessionId: session.sessionId,
+					canonicalPathKey: session.canonicalPathKey,
+					attemptedRevision: session.revision,
+					lastSavedRevision: session.lastSavedRevision,
+					writtenPaths,
+					failedPaths,
+					skippedPaths,
+					diagnostics: diagnosticsFromError,
+					diskMayBePartiallyUpdated: true,
+				},
+				toSessionSnapshot(session, this.context.capabilities),
+				{
+					sessionId: session.sessionId,
+					revision: session.revision,
+					diagnostics: diagnosticsFromError,
+				},
+			);
+		}
+	}
 }

package/src/services/context.ts

@@ -25,6 +25,7 @@ export interface BackendSessionState {
 	canonicalProjectPath: string;
 	canonicalPathKey: string;
 	lockFilePath: string;
+	fileSystem?: BackendFileSystem;
 	project: import('@openfairygui/core/uam').UamProject;
 	revision: number;
 	lastSavedRevision: number;

package/src/services/runtime-service.ts

@@ -14,7 +14,7 @@ import type {
 	OpenProjectSessionInput,
 	SessionNotFoundError,
 } from '../runtime.js';
-import { resolveCanonicalProjectRoot } from '../path-policy.js';
+import { normalizeComparablePath, resolveCanonicalProjectRoot } from '../path-policy.js';
 import { createSessionNotFoundError, toSessionSnapshot } from './session-utils.js';
 
 function randomId(): string {
@@ -137,6 +137,7 @@ export class RuntimeService {
 				canonicalProjectPath,
 				canonicalPathKey,
 				lockFilePath,
+				fileSystem,
 				project,
 				revision: 0,
 				lastSavedRevision: 0,
@@ -174,8 +175,14 @@ export class RuntimeService {
 	public openProjectSession(input: OpenProjectSessionInput): BackendResult<BackendSessionSnapshot> {
 		const startedAt = Date.now();
 		const sessionId = input.sessionId ?? randomId();
-		const canonicalProjectPath = input.canonicalProjectPath ?? `memory://${sessionId}`;
-		const canonicalPathKey = input.canonicalPathKey ?? canonicalProjectPath.toLowerCase();
+		const storage = input.storage;
+		const memoryProjectPath = `memory://${sessionId}`;
+		const canonicalProjectPath = storage?.canonicalProjectPath
+			?? input.canonicalProjectPath
+			?? (storage ? storage.fileSystem.dirname(storage.fairyPath) || '.' : memoryProjectPath);
+		const canonicalPathKey = storage?.canonicalPathKey
+			?? input.canonicalPathKey
+			?? (storage ? normalizeComparablePath(canonicalProjectPath) : canonicalProjectPath.toLowerCase());
 		const existingSessionId = this.context.sessionsByPath.get(canonicalPathKey);
 		if (existingSessionId) {
 			return failure('runtime', startedAt, {
@@ -189,10 +196,11 @@ export class RuntimeService {
 
 		const session: BackendSessionState = {
 			sessionId,
-			fairyPath: canonicalProjectPath,
+			fairyPath: storage?.fairyPath ?? canonicalProjectPath,
 			canonicalProjectPath,
 			canonicalPathKey,
 			lockFilePath: '',
+			fileSystem: storage?.fileSystem,
 			project: normalizeUamProject(input.project),
 			revision: 0,
 			lastSavedRevision: 0,

package/src/storage.ts

@@ -0,0 +1,192 @@
+import type { FileSystem as CoreProjectFileSystem } from '@openfairygui/core/project-io';
+import type { BackendFileHandle, BackendFileStat, BackendFileSystem } from './runtime.js';
+
+type StorageStatKind = 'file' | 'directory';
+
+export interface BackendStorageStatLike {
+	kind?: StorageStatKind;
+	type?: StorageStatKind;
+	isFile?(): boolean;
+	isDirectory?(): boolean;
+}
+
+export interface BackendAsyncStorageAdapter {
+	readFile(filePath: string): Promise<string>;
+	readFileRaw(filePath: string): Promise<Uint8Array>;
+	writeFile(filePath: string, content: string): Promise<void>;
+	writeFileRaw(filePath: string, data: Uint8Array): Promise<void>;
+	mkdir(dirPath: string, options?: { recursive?: boolean }): Promise<void>;
+	readdir(dirPath: string): Promise<string[]>;
+	exists?(filePath: string): Promise<boolean>;
+	stat?(filePath: string): Promise<BackendStorageStatLike>;
+	resolvePath?(filePath: string): Promise<string>;
+	openExclusive?(filePath: string): Promise<BackendFileHandle>;
+	unlink?(filePath: string): Promise<void>;
+	join?(...paths: string[]): string;
+	dirname?(filePath: string): string;
+	resolve?(...paths: string[]): string;
+}
+
+class StorageFileStat implements BackendFileStat {
+	public constructor(private readonly kind: StorageStatKind) {}
+
+	public isFile(): boolean {
+		return this.kind === 'file';
+	}
+
+	public isDirectory(): boolean {
+		return this.kind === 'directory';
+	}
+}
+
+function createPathError(code: string, message: string): Error & { code: string } {
+	const error = new Error(message) as Error & { code: string };
+	error.code = code;
+	return error;
+}
+
+function normalizeStoragePath(value: string): string {
+	const normalized = value.replace(/\\/g, '/').replace(/\/+/g, '/');
+	const absolute = normalized.startsWith('/');
+	const rawSegments = normalized.split('/').filter((segment) => segment.length > 0);
+	const segments: string[] = [];
+
+	for (const segment of rawSegments) {
+		if (segment === '.') continue;
+		if (segment === '..') {
+			if (segments.length > 0) segments.pop();
+			continue;
+		}
+		segments.push(segment);
+	}
+
+	const joined = segments.join('/');
+	if (absolute) return joined ? `/${joined}` : '/';
+	return joined || '.';
+}
+
+function joinStoragePath(...paths: string[]): string {
+	return normalizeStoragePath(paths.filter((part) => part.length > 0).join('/'));
+}
+
+function dirnameStoragePath(filePath: string): string {
+	const normalized = normalizeStoragePath(filePath);
+	if (normalized === '/' || normalized === '.') return '.';
+	const absolute = normalized.startsWith('/');
+	const parts = normalized.split('/').filter((part) => part.length > 0);
+	parts.pop();
+	if (parts.length === 0) return absolute ? '/' : '.';
+	return `${absolute ? '/' : ''}${parts.join('/')}`;
+}
+
+function statFromLike(stat: BackendStorageStatLike): BackendFileStat {
+	if (typeof stat.isFile === 'function' && typeof stat.isDirectory === 'function') {
+		return stat as BackendFileStat;
+	}
+	const kind = stat.kind ?? stat.type;
+	if (kind === 'file' || kind === 'directory') return new StorageFileStat(kind);
+	throw createPathError('EINVAL', 'Storage stat must provide kind/type or isFile()/isDirectory().');
+}
+
+async function inferStat(storage: BackendAsyncStorageAdapter, filePath: string): Promise<BackendFileStat> {
+	if (storage.stat) return statFromLike(await storage.stat(filePath));
+
+	try {
+		await storage.readdir(filePath);
+		return new StorageFileStat('directory');
+	} catch {
+		// Try file probes below.
+	}
+
+	try {
+		await storage.readFileRaw(filePath);
+		return new StorageFileStat('file');
+	} catch {
+		try {
+			await storage.readFile(filePath);
+			return new StorageFileStat('file');
+		} catch {
+			throw createPathError('ENOENT', `Storage path not found: ${filePath}`);
+		}
+	}
+}
+
+export type BackendStorageFileSystem = BackendFileSystem & CoreProjectFileSystem;
+
+export function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapter): BackendStorageFileSystem {
+	const lockedPaths = new Set<string>();
+
+	const fileSystem: BackendStorageFileSystem = {
+		stat(filePath: string): Promise<BackendFileStat> {
+			return inferStat(storage, fileSystem.resolve(filePath));
+		},
+		readdir(dirPath: string): Promise<string[]> {
+			return storage.readdir(fileSystem.resolve(dirPath));
+		},
+		readFile(filePath: string): Promise<string> {
+			return storage.readFile(fileSystem.resolve(filePath));
+		},
+		readFileRaw(filePath: string): Promise<Uint8Array> {
+			return storage.readFileRaw(fileSystem.resolve(filePath));
+		},
+		writeFile(filePath: string, content: string): Promise<void> {
+			return storage.writeFile(fileSystem.resolve(filePath), content);
+		},
+		writeFileRaw(filePath: string, data: Uint8Array): Promise<void> {
+			return storage.writeFileRaw(fileSystem.resolve(filePath), data);
+		},
+		mkdir(dirPath: string, options?: { recursive?: boolean }): Promise<void> {
+			return storage.mkdir(fileSystem.resolve(dirPath), options);
+		},
+		async exists(filePath: string): Promise<boolean> {
+			if (storage.exists) return storage.exists(fileSystem.resolve(filePath));
+			try {
+				await fileSystem.stat(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		resolvePath(filePath: string): Promise<string> {
+			const resolved = fileSystem.resolve(filePath);
+			return storage.resolvePath ? storage.resolvePath(resolved) : Promise.resolve(resolved);
+		},
+		async openExclusive(filePath: string): Promise<BackendFileHandle> {
+			const resolved = fileSystem.resolve(filePath);
+			if (storage.openExclusive) return storage.openExclusive(resolved);
+			if (lockedPaths.has(resolved) || await fileSystem.exists(resolved)) {
+				throw createPathError('EEXIST', `Storage path already exists: ${resolved}`);
+			}
+			lockedPaths.add(resolved);
+			let closed = false;
+			return {
+				async writeFile(content: string): Promise<void> {
+					if (closed) throw createPathError('EBADF', `Storage lock handle is closed: ${resolved}`);
+					await fileSystem.mkdir(fileSystem.dirname(resolved), { recursive: true });
+					await storage.writeFile(resolved, content);
+				},
+				async close(): Promise<void> {
+					closed = true;
+					lockedPaths.delete(resolved);
+				},
+			};
+		},
+		unlink(filePath: string): Promise<void> {
+			const resolved = fileSystem.resolve(filePath);
+			lockedPaths.delete(resolved);
+			if (storage.unlink) return storage.unlink(resolved);
+			throw createPathError('ENOTSUP', 'Storage adapter does not provide unlink().');
+		},
+		join(...paths: string[]): string {
+			return storage.join ? storage.join(...paths) : joinStoragePath(...paths);
+		},
+		dirname(filePath: string): string {
+			return storage.dirname ? storage.dirname(filePath) : dirnameStoragePath(filePath);
+		},
+		resolve(...paths: string[]): string {
+			return storage.resolve ? storage.resolve(...paths) : joinStoragePath(...paths);
+		},
+	};
+
+	return fileSystem;
+}