@hudhod/webcontainer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hudhod
+
+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

@@ -0,0 +1,27 @@
+# @hudhod/webcontainer
+
+WebContainer adapters for the headless Hudhod runtime.
+
+This package is browser-only. It provides `WebContainerFileSystemProvider`, `WebContainerProcessSpawner`, and `createWebContainerServices()` for use with `createHudhodRuntime()` or `createHudhodReactHost()`.
+
+## Install
+
+```sh
+pnpm add @hudhod/webcontainer @hudhod/core @webcontainer/api
+```
+
+WebContainers require `SharedArrayBuffer` and cross-origin isolation. Do not import this package from Node or server-rendered code.
+
+## Usage
+
+```ts
+import { createHudhodReactHost } from "@hudhod/react";
+import { createWebContainerServices } from "@hudhod/webcontainer";
+
+const host = createHudhodReactHost({
+  ...createWebContainerServices(container),
+  ui: myUiAdapter,
+});
+```
+
+The package is optional. Desktop, remote, and test hosts can instead supply their own `FileSystemProvider` and `ProcessSpawner` implementations from `@hudhod/core`.

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { FileSystemProvider, ProcessSpawner, ProviderEntry, ProviderStat, ProviderWatchOptions, SpawnedProcess, SpawnerOptions } from "@hudhod/core";
+import { WebContainer } from "@webcontainer/api";
+import { Disposable, FileChangeEvent } from "@hudhod/sdk";
+
+//#region src/index.d.ts
+/** Adapts WebContainer's filesystem to Hudhod's provider contract. */
+declare class WebContainerFileSystemProvider implements FileSystemProvider {
+  #private;
+  readonly name = "webcontainer";
+  constructor(container: WebContainer);
+  readFile(path: string): Promise<Uint8Array>;
+  writeFile(path: string, data: Uint8Array): Promise<void>;
+  createDirectory(path: string): Promise<void>;
+  delete(path: string, options: {
+    recursive: boolean;
+  }): Promise<void>;
+  rename(from: string, to: string, options: {
+    overwrite: boolean;
+  }): Promise<void>;
+  stat(path: string): Promise<ProviderStat>;
+  readDirectory(path: string): Promise<ProviderEntry[]>;
+  watch(path: string, options: ProviderWatchOptions, listener: (events: readonly FileChangeEvent[]) => void): Disposable;
+}
+/** Adapts WebContainer process spawning to Hudhod's process contract. */
+declare class WebContainerProcessSpawner implements ProcessSpawner {
+  #private;
+  readonly name = "webcontainer";
+  constructor(container: WebContainer);
+  spawn(command: string, args: readonly string[], options: SpawnerOptions): Promise<SpawnedProcess>;
+}
+/** Creates the standard filesystem and process adapters for a WebContainer instance. */
+declare function createWebContainerServices(container: WebContainer): {
+  fileSystemProvider: FileSystemProvider;
+  processSpawner: ProcessSpawner;
+};
+//#endregion
+export { WebContainerFileSystemProvider, WebContainerProcessSpawner, createWebContainerServices };

package/dist/index.js

@@ -0,0 +1,164 @@
+import { ROOT, basename, directoryNotEmpty, dirname, fileExists, fileNotFound, joinPath, notADirectory, toDisposable } from "@hudhod/core";
+
+//#region src/index.ts
+/** Adapts WebContainer's filesystem to Hudhod's provider contract. */
+var WebContainerFileSystemProvider = class {
+	name = "webcontainer";
+	#container;
+	constructor(container) {
+		this.#container = container;
+	}
+	async readFile(path) {
+		try {
+			return await this.#container.fs.readFile(path);
+		} catch (error) {
+			throw translate(error, path);
+		}
+	}
+	async writeFile(path, data) {
+		try {
+			await this.#container.fs.writeFile(path, data);
+		} catch (error) {
+			throw translate(error, path);
+		}
+	}
+	async createDirectory(path) {
+		try {
+			await this.#container.fs.mkdir(path, { recursive: true });
+		} catch (error) {
+			if (isErrno(error, "EEXIST")) {
+				if ((await this.stat(path)).type === "directory") return;
+				throw fileExists(path);
+			}
+			throw translate(error, path);
+		}
+	}
+	async delete(path, options) {
+		try {
+			await this.#container.fs.rm(path, { recursive: options.recursive });
+		} catch (error) {
+			if (isErrno(error, "ENOTEMPTY")) throw directoryNotEmpty(path);
+			throw translate(error, path);
+		}
+	}
+	async rename(from, to, options) {
+		if (!options.overwrite && await this.#exists(to)) throw fileExists(to);
+		try {
+			await this.#container.fs.rename(from, to);
+		} catch (error) {
+			throw translate(error, from);
+		}
+	}
+	async stat(path) {
+		if (path === ROOT) return {
+			type: "directory",
+			size: 0,
+			mtime: 0
+		};
+		const name = basename(path);
+		let entries;
+		try {
+			entries = await this.readDirectory(dirname(path));
+		} catch {
+			throw fileNotFound(path);
+		}
+		const entry = entries.find((candidate) => candidate.name === name);
+		if (!entry) throw fileNotFound(path);
+		if (entry.type === "directory") return {
+			type: "directory",
+			size: 0,
+			mtime: 0
+		};
+		return {
+			type: "file",
+			size: (await this.readFile(path)).byteLength,
+			mtime: 0
+		};
+	}
+	async readDirectory(path) {
+		try {
+			return (await this.#container.fs.readdir(path, { withFileTypes: true })).map((entry) => ({
+				name: entry.name,
+				type: entry.isDirectory() ? "directory" : "file"
+			}));
+		} catch (error) {
+			if (isErrno(error, "ENOTDIR")) throw notADirectory(path);
+			throw translate(error, path);
+		}
+	}
+	watch(path, options, listener) {
+		const watcher = this.#container.fs.watch(path, { recursive: options.recursive }, (event, filename) => {
+			if (typeof filename !== "string") return;
+			const changed = joinPath(path, filename);
+			if (event === "change") {
+				listener([{
+					type: "changed",
+					path: changed
+				}]);
+				return;
+			}
+			this.#exists(changed).then((exists) => listener([{
+				type: exists ? "created" : "deleted",
+				path: changed
+			}]));
+		});
+		return toDisposable(() => watcher.close());
+	}
+	async #exists(path) {
+		try {
+			await this.stat(path);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+/** Adapts WebContainer process spawning to Hudhod's process contract. */
+var WebContainerProcessSpawner = class {
+	name = "webcontainer";
+	#container;
+	constructor(container) {
+		this.#container = container;
+	}
+	async spawn(command, args, options) {
+		const process = await this.#container.spawn(command, [...args], {
+			...options.cwd ? { cwd: options.cwd } : {},
+			...options.env ? { env: { ...options.env } } : {},
+			...options.terminal ? { terminal: { ...options.terminal } } : {}
+		});
+		let killed = false;
+		return {
+			output: process.output,
+			input: process.input,
+			exit: process.exit,
+			kill() {
+				if (killed) return;
+				killed = true;
+				process.kill();
+			},
+			resize(dimensions) {
+				if (options.terminal) process.resize(dimensions);
+			}
+		};
+	}
+};
+/** Creates the standard filesystem and process adapters for a WebContainer instance. */
+function createWebContainerServices(container) {
+	return {
+		fileSystemProvider: new WebContainerFileSystemProvider(container),
+		processSpawner: new WebContainerProcessSpawner(container)
+	};
+}
+function isErrno(error, code) {
+	return typeof error === "object" && error !== null && error.code === code;
+}
+function translate(error, path) {
+	if (isErrno(error, "ENOENT")) return fileNotFound(path);
+	if (isErrno(error, "ENOTDIR")) return notADirectory(path);
+	if (isErrno(error, "EEXIST")) return fileExists(path);
+	if (isErrno(error, "ENOTEMPTY")) return directoryNotEmpty(path);
+	return error;
+}
+
+//#endregion
+export { WebContainerFileSystemProvider, WebContainerProcessSpawner, createWebContainerServices };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@hudhod/webcontainer",
+  "version": "0.1.0",
+  "description": "WebContainer adapters for the headless Hudhod runtime.",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hudhod/core": "0.1.0",
+    "@hudhod/sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "@webcontainer/api": "^1.6.4",
+    "tsdown": "^0.15.6",
+    "typescript": "^5.7.2"
+  },
+  "peerDependencies": {
+    "@webcontainer/api": "^1.6.4"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}