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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenFairyGUI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -12,6 +12,7 @@ It owns:
 - revisioned request handling
 - coordinated but non-atomic save semantics
 - browser-safe project sessions
+- browser-safe async project storage adapter
 - adapter-backed file sessions and backend-local advisory locking
 - capability discovery
 - transport-neutral bootstrap
@@ -31,8 +32,9 @@ It also provides:
 
 It does **not** redefine transaction grammar or expose `Document`.
 It also does **not** implement MCP or any transport-specific wire protocol.
-The root `@openfairygui/backend` entrypoint is browser-safe: file-backed sessions require an injected
-`BackendFileSystem`, while the default Node filesystem/runtime lives under `@openfairygui/backend/node`.
+The root `@openfairygui/backend` entrypoint is browser-safe: pure authoring sessions can run in memory,
+and browser editors can inject an async storage adapter for OPFS, IndexedDB, ZIP-backed virtual filesystems,
+or File System Access API bridges. The default Node filesystem/runtime lives under `@openfairygui/backend/node`.
 
 ## Relationship to other packages
 
@@ -58,6 +60,42 @@ const applied = await runtime.applyTransaction({
 });
 ```
 
+Browser-safe project session with injected storage:
+
+```ts
+import { BackendRuntime, createBackendStorageFileSystem } from '@openfairygui/backend';
+
+const fileSystem = createBackendStorageFileSystem({
+	async readFile(filePath) { return storage.readText(filePath); },
+	async readFileRaw(filePath) { return storage.readBytes(filePath); },
+	async writeFile(filePath, content) { await storage.writeText(filePath, content); },
+	async writeFileRaw(filePath, data) { await storage.writeBytes(filePath, data); },
+	async mkdir(dirPath) { await storage.mkdir(dirPath); },
+	async readdir(dirPath) { return storage.readdir(dirPath); },
+	async exists(filePath) { return storage.exists(filePath); },
+});
+
+const runtime = new BackendRuntime();
+const opened = runtime.openProjectSession({
+	project: uamProject,
+	storage: {
+		fileSystem,
+		fairyPath: 'Project.fairy',
+	},
+});
+if (!opened.ok) throw new Error(opened.error.message);
+
+const bootstrapped = await runtime.materializeSession({
+	sessionId: opened.data.sessionId,
+	expectedRevision: opened.data.revision,
+	mode: 'fullProject',
+	reason: 'workspace_bootstrap',
+});
+if (!bootstrapped.ok) throw new Error(bootstrapped.error.message);
+
+console.log(bootstrapped.data.writtenPaths);
+```
+
 Node file-backed session:
 
 ```ts

package/dist/index.cjs

@@ -1,6 +1,151 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_runtime = require("./runtime-BXbt135W.cjs");
+const require_runtime = require("./runtime-GKzsXJdO.cjs");
+//#region src/storage.ts
+var StorageFileStat = class {
+	constructor(kind) {
+		this.kind = kind;
+	}
+	isFile() {
+		return this.kind === "file";
+	}
+	isDirectory() {
+		return this.kind === "directory";
+	}
+};
+function createPathError(code, message) {
+	const error = new Error(message);
+	error.code = code;
+	return error;
+}
+function normalizeStoragePath(value) {
+	const normalized = value.replace(/\\/g, "/").replace(/\/+/g, "/");
+	const absolute = normalized.startsWith("/");
+	const rawSegments = normalized.split("/").filter((segment) => segment.length > 0);
+	const segments = [];
+	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) {
+	return normalizeStoragePath(paths.filter((part) => part.length > 0).join("/"));
+}
+function dirnameStoragePath(filePath) {
+	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) {
+	if (typeof stat.isFile === "function" && typeof stat.isDirectory === "function") return stat;
+	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, filePath) {
+	if (storage.stat) return statFromLike(await storage.stat(filePath));
+	try {
+		await storage.readdir(filePath);
+		return new StorageFileStat("directory");
+	} catch {}
+	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}`);
+		}
+	}
+}
+function createBackendStorageFileSystem(storage) {
+	const lockedPaths = /* @__PURE__ */ new Set();
+	const fileSystem = {
+		stat(filePath) {
+			return inferStat(storage, fileSystem.resolve(filePath));
+		},
+		readdir(dirPath) {
+			return storage.readdir(fileSystem.resolve(dirPath));
+		},
+		readFile(filePath) {
+			return storage.readFile(fileSystem.resolve(filePath));
+		},
+		readFileRaw(filePath) {
+			return storage.readFileRaw(fileSystem.resolve(filePath));
+		},
+		writeFile(filePath, content) {
+			return storage.writeFile(fileSystem.resolve(filePath), content);
+		},
+		writeFileRaw(filePath, data) {
+			return storage.writeFileRaw(fileSystem.resolve(filePath), data);
+		},
+		mkdir(dirPath, options) {
+			return storage.mkdir(fileSystem.resolve(dirPath), options);
+		},
+		async exists(filePath) {
+			if (storage.exists) return storage.exists(fileSystem.resolve(filePath));
+			try {
+				await fileSystem.stat(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		resolvePath(filePath) {
+			const resolved = fileSystem.resolve(filePath);
+			return storage.resolvePath ? storage.resolvePath(resolved) : Promise.resolve(resolved);
+		},
+		async openExclusive(filePath) {
+			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) {
+					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() {
+					closed = true;
+					lockedPaths.delete(resolved);
+				}
+			};
+		},
+		unlink(filePath) {
+			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) {
+			return storage.join ? storage.join(...paths) : joinStoragePath(...paths);
+		},
+		dirname(filePath) {
+			return storage.dirname ? storage.dirname(filePath) : dirnameStoragePath(filePath);
+		},
+		resolve(...paths) {
+			return storage.resolve ? storage.resolve(...paths) : joinStoragePath(...paths);
+		}
+	};
+	return fileSystem;
+}
+//#endregion
 exports.BACKEND_CAPABILITY_SCHEMA_VERSION = require_runtime.BACKEND_CAPABILITY_SCHEMA_VERSION;
 exports.BACKEND_COMPATIBILITY_POLICY = require_runtime.BACKEND_COMPATIBILITY_POLICY;
 exports.BACKEND_CONTRACT_VERSION = require_runtime.BACKEND_CONTRACT_VERSION;
 exports.BackendRuntime = require_runtime.BackendRuntime;
+exports.createBackendStorageFileSystem = createBackendStorageFileSystem;

package/dist/index.d.cts

@@ -1,2 +1,33 @@
-import { A as BackendSuccess, B as OpenProjectSessionInput, C as BackendJobProgress, D as BackendRuntime, E as BackendResult, F as GetEventsInput, G as BACKEND_CAPABILITY_SCHEMA_VERSION, H as SavePartialFailureError, I as GetEventsSnapshot, J as BackendDiagnostic, K as BACKEND_COMPATIBILITY_POLICY, L as GetJobInput, M as CancelJobInput, N as EventCursorInvalidError, O as BackendRuntimeOptions, P as GetCacheSnapshotInput, R as InProcessLockConflictError, S as BackendJobNotFoundError, T as BackendJobStatus, U as SessionNotFoundError, V as RefreshCacheInput, W as SessionStaleWriteError, X as BackendResponseMeta, Y as BackendMessage, Z as BackendStage, _ as BackendJobErrors, a as BackendCacheSnapshot, b as BackendJobListStatusFilter, c as BackendCapabilityUnavailableError, d as BackendEventKind, f as BackendFailure, g as BackendHostAdapter, h as BackendFileSystem, i as BackendCacheEntry, j as CacheRefreshFailedError, k as BackendSessionSnapshot, l as BackendError, m as BackendFileStat, n as ApplySessionTransactionInput, o as BackendCapabilities, p as BackendFileHandle, q as BACKEND_CONTRACT_VERSION, r as BackendArtifactBridgeCapability, s as BackendCapabilityManifest, t as AdvisoryLockConflictError, u as BackendEvent, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as ListJobsInput } from "./runtime-C5JY_kRI.cjs";
-export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SessionNotFoundError, type SessionStaleWriteError };
+import { $ as BACKEND_CONTRACT_VERSION, A as BackendSessionSnapshot, B as ListJobsInput, C as BackendJobProgress, D as BackendResult, E as BackendProjectSessionStorage, F as GetCacheSnapshotInput, G as OpenProjectSessionInput, H as MaterializeSessionSnapshot, I as GetEventsInput, J as SaveSessionInput, K as RefreshCacheInput, L as GetEventsSnapshot, M as CacheRefreshFailedError, N as CancelJobInput, O as BackendRuntime, P as EventCursorInvalidError, Q as BACKEND_COMPATIBILITY_POLICY, R as GetJobInput, S as BackendJobNotFoundError, T as BackendJobStatus, U as MaterializeValidationFailedError, V as MaterializeSessionInput, W as MaterializeWriteFailedError, X as SessionStaleWriteError, Y as SessionNotFoundError, Z as BACKEND_CAPABILITY_SCHEMA_VERSION, _ as BackendJobErrors, a as BackendCacheSnapshot, b as BackendJobListStatusFilter, c as BackendCapabilityUnavailableError, d as BackendEventKind, et as BackendDiagnostic, f as BackendFailure, g as BackendHostAdapter, h as BackendFileSystem, i as BackendCacheEntry, j as BackendSuccess, k as BackendRuntimeOptions, l as BackendError, m as BackendFileStat, n as ApplySessionTransactionInput, nt as BackendResponseMeta, o as BackendCapabilities, p as BackendFileHandle, q as SavePartialFailureError, r as BackendArtifactBridgeCapability, rt as BackendStage, s as BackendCapabilityManifest, t as AdvisoryLockConflictError, tt as BackendMessage, u as BackendEvent, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as InProcessLockConflictError } from "./runtime-Jec6FcF5.cjs";
+import { FileSystem } from "@openfairygui/core/project-io";
+
+//#region src/storage.d.ts
+type StorageStatKind = 'file' | 'directory';
+interface BackendStorageStatLike {
+  kind?: StorageStatKind;
+  type?: StorageStatKind;
+  isFile?(): boolean;
+  isDirectory?(): boolean;
+}
+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;
+}
+type BackendStorageFileSystem = BackendFileSystem & FileSystem;
+declare function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapter): BackendStorageFileSystem;
+//#endregion
+export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type MaterializeSessionInput, type MaterializeSessionSnapshot, type MaterializeValidationFailedError, type MaterializeWriteFailedError, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionNotFoundError, type SessionStaleWriteError, createBackendStorageFileSystem };

package/dist/index.d.mts

@@ -1,2 +1,33 @@
-import { A as BackendSuccess, B as OpenProjectSessionInput, C as BackendJobProgress, D as BackendRuntime, E as BackendResult, F as GetEventsInput, G as BACKEND_CAPABILITY_SCHEMA_VERSION, H as SavePartialFailureError, I as GetEventsSnapshot, J as BackendDiagnostic, K as BACKEND_COMPATIBILITY_POLICY, L as GetJobInput, M as CancelJobInput, N as EventCursorInvalidError, O as BackendRuntimeOptions, P as GetCacheSnapshotInput, R as InProcessLockConflictError, S as BackendJobNotFoundError, T as BackendJobStatus, U as SessionNotFoundError, V as RefreshCacheInput, W as SessionStaleWriteError, X as BackendResponseMeta, Y as BackendMessage, Z as BackendStage, _ as BackendJobErrors, a as BackendCacheSnapshot, b as BackendJobListStatusFilter, c as BackendCapabilityUnavailableError, d as BackendEventKind, f as BackendFailure, g as BackendHostAdapter, h as BackendFileSystem, i as BackendCacheEntry, j as CacheRefreshFailedError, k as BackendSessionSnapshot, l as BackendError, m as BackendFileStat, n as ApplySessionTransactionInput, o as BackendCapabilities, p as BackendFileHandle, q as BACKEND_CONTRACT_VERSION, r as BackendArtifactBridgeCapability, s as BackendCapabilityManifest, t as AdvisoryLockConflictError, u as BackendEvent, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as ListJobsInput } from "./runtime-C5ZsWMnH.mjs";
-export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SessionNotFoundError, type SessionStaleWriteError };
+import { $ as BACKEND_CONTRACT_VERSION, A as BackendSessionSnapshot, B as ListJobsInput, C as BackendJobProgress, D as BackendResult, E as BackendProjectSessionStorage, F as GetCacheSnapshotInput, G as OpenProjectSessionInput, H as MaterializeSessionSnapshot, I as GetEventsInput, J as SaveSessionInput, K as RefreshCacheInput, L as GetEventsSnapshot, M as CacheRefreshFailedError, N as CancelJobInput, O as BackendRuntime, P as EventCursorInvalidError, Q as BACKEND_COMPATIBILITY_POLICY, R as GetJobInput, S as BackendJobNotFoundError, T as BackendJobStatus, U as MaterializeValidationFailedError, V as MaterializeSessionInput, W as MaterializeWriteFailedError, X as SessionStaleWriteError, Y as SessionNotFoundError, Z as BACKEND_CAPABILITY_SCHEMA_VERSION, _ as BackendJobErrors, a as BackendCacheSnapshot, b as BackendJobListStatusFilter, c as BackendCapabilityUnavailableError, d as BackendEventKind, et as BackendDiagnostic, f as BackendFailure, g as BackendHostAdapter, h as BackendFileSystem, i as BackendCacheEntry, j as BackendSuccess, k as BackendRuntimeOptions, l as BackendError, m as BackendFileStat, n as ApplySessionTransactionInput, nt as BackendResponseMeta, o as BackendCapabilities, p as BackendFileHandle, q as SavePartialFailureError, r as BackendArtifactBridgeCapability, rt as BackendStage, s as BackendCapabilityManifest, t as AdvisoryLockConflictError, tt as BackendMessage, u as BackendEvent, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as InProcessLockConflictError } from "./runtime-GyNVxAQ0.mjs";
+import { FileSystem } from "@openfairygui/core/project-io";
+
+//#region src/storage.d.ts
+type StorageStatKind = 'file' | 'directory';
+interface BackendStorageStatLike {
+  kind?: StorageStatKind;
+  type?: StorageStatKind;
+  isFile?(): boolean;
+  isDirectory?(): boolean;
+}
+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;
+}
+type BackendStorageFileSystem = BackendFileSystem & FileSystem;
+declare function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapter): BackendStorageFileSystem;
+//#endregion
+export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type MaterializeSessionInput, type MaterializeSessionSnapshot, type MaterializeValidationFailedError, type MaterializeWriteFailedError, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionNotFoundError, type SessionStaleWriteError, createBackendStorageFileSystem };

package/dist/index.mjs

@@ -1,2 +1,146 @@
-import { i as BACKEND_CONTRACT_VERSION, n as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BACKEND_COMPATIBILITY_POLICY, t as BackendRuntime } from "./runtime-DLWLghmH.mjs";
-export { BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, BackendRuntime };
+import { i as BACKEND_CONTRACT_VERSION, n as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BACKEND_COMPATIBILITY_POLICY, t as BackendRuntime } from "./runtime-DFatY9W0.mjs";
+//#region src/storage.ts
+var StorageFileStat = class {
+	constructor(kind) {
+		this.kind = kind;
+	}
+	isFile() {
+		return this.kind === "file";
+	}
+	isDirectory() {
+		return this.kind === "directory";
+	}
+};
+function createPathError(code, message) {
+	const error = new Error(message);
+	error.code = code;
+	return error;
+}
+function normalizeStoragePath(value) {
+	const normalized = value.replace(/\\/g, "/").replace(/\/+/g, "/");
+	const absolute = normalized.startsWith("/");
+	const rawSegments = normalized.split("/").filter((segment) => segment.length > 0);
+	const segments = [];
+	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) {
+	return normalizeStoragePath(paths.filter((part) => part.length > 0).join("/"));
+}
+function dirnameStoragePath(filePath) {
+	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) {
+	if (typeof stat.isFile === "function" && typeof stat.isDirectory === "function") return stat;
+	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, filePath) {
+	if (storage.stat) return statFromLike(await storage.stat(filePath));
+	try {
+		await storage.readdir(filePath);
+		return new StorageFileStat("directory");
+	} catch {}
+	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}`);
+		}
+	}
+}
+function createBackendStorageFileSystem(storage) {
+	const lockedPaths = /* @__PURE__ */ new Set();
+	const fileSystem = {
+		stat(filePath) {
+			return inferStat(storage, fileSystem.resolve(filePath));
+		},
+		readdir(dirPath) {
+			return storage.readdir(fileSystem.resolve(dirPath));
+		},
+		readFile(filePath) {
+			return storage.readFile(fileSystem.resolve(filePath));
+		},
+		readFileRaw(filePath) {
+			return storage.readFileRaw(fileSystem.resolve(filePath));
+		},
+		writeFile(filePath, content) {
+			return storage.writeFile(fileSystem.resolve(filePath), content);
+		},
+		writeFileRaw(filePath, data) {
+			return storage.writeFileRaw(fileSystem.resolve(filePath), data);
+		},
+		mkdir(dirPath, options) {
+			return storage.mkdir(fileSystem.resolve(dirPath), options);
+		},
+		async exists(filePath) {
+			if (storage.exists) return storage.exists(fileSystem.resolve(filePath));
+			try {
+				await fileSystem.stat(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		resolvePath(filePath) {
+			const resolved = fileSystem.resolve(filePath);
+			return storage.resolvePath ? storage.resolvePath(resolved) : Promise.resolve(resolved);
+		},
+		async openExclusive(filePath) {
+			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) {
+					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() {
+					closed = true;
+					lockedPaths.delete(resolved);
+				}
+			};
+		},
+		unlink(filePath) {
+			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) {
+			return storage.join ? storage.join(...paths) : joinStoragePath(...paths);
+		},
+		dirname(filePath) {
+			return storage.dirname ? storage.dirname(filePath) : dirnameStoragePath(filePath);
+		},
+		resolve(...paths) {
+			return storage.resolve ? storage.resolve(...paths) : joinStoragePath(...paths);
+		}
+	};
+	return fileSystem;
+}
+//#endregion
+export { BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, BackendRuntime, createBackendStorageFileSystem };

package/dist/node.cjs

@@ -21,7 +21,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_runtime = require("./runtime-BXbt135W.cjs");
+const require_runtime = require("./runtime-GKzsXJdO.cjs");
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = __toESM(node_fs_promises);
 let node_path = require("node:path");

package/dist/node.d.cts

@@ -1,4 +1,4 @@
-import { D as BackendRuntime, O as BackendRuntimeOptions, g as BackendHostAdapter, h as BackendFileSystem, m as BackendFileStat, p as BackendFileHandle } from "./runtime-C5JY_kRI.cjs";
+import { O as BackendRuntime, g as BackendHostAdapter, h as BackendFileSystem, k as BackendRuntimeOptions, m as BackendFileStat, p as BackendFileHandle } from "./runtime-Jec6FcF5.cjs";
 
 //#region src/node.d.ts
 declare function createNodeBackendFileSystem(): BackendFileSystem;

package/dist/node.d.mts

@@ -1,4 +1,4 @@
-import { D as BackendRuntime, O as BackendRuntimeOptions, g as BackendHostAdapter, h as BackendFileSystem, m as BackendFileStat, p as BackendFileHandle } from "./runtime-C5ZsWMnH.mjs";
+import { O as BackendRuntime, g as BackendHostAdapter, h as BackendFileSystem, k as BackendRuntimeOptions, m as BackendFileStat, p as BackendFileHandle } from "./runtime-GyNVxAQ0.mjs";
 
 //#region src/node.d.ts
 declare function createNodeBackendFileSystem(): BackendFileSystem;

package/dist/node.mjs

@@ -1,4 +1,4 @@
-import { t as BackendRuntime } from "./runtime-DLWLghmH.mjs";
+import { t as BackendRuntime } from "./runtime-DFatY9W0.mjs";
 import fs from "node:fs/promises";
 import path from "node:path";
 //#region src/node.ts