@hudhod/core 0.1.0

package/dist/paths-B3gr2EuI.js

@@ -0,0 +1,282 @@
+//#region src/base/disposable.ts
+/**
+* Wraps a callback as a {@link Disposable} that runs at most once.
+*
+* @example
+* ```ts
+* const sub = toDisposable(() => clearInterval(timer));
+* sub.dispose();
+* sub.dispose(); // no-op
+* ```
+*/
+function toDisposable(onDispose) {
+	let disposed = false;
+	return { dispose() {
+		if (disposed) return;
+		disposed = true;
+		onDispose();
+	} };
+}
+/** A {@link Disposable} that does nothing. Useful as a default return value. */
+const NO_OP_DISPOSABLE = Object.freeze({ dispose() {} });
+/**
+* Collects disposables and releases them together.
+*
+* Disposal runs in reverse insertion order, so resources are torn down in the
+* opposite order they were set up. A failure in one disposable does not
+* prevent the rest from running; all errors are collected and rethrown
+* together via {@link AggregateError}.
+*
+* @example
+* ```ts
+* const store = new DisposableStore();
+* store.add(emitter.event(handler));
+* store.add(toDisposable(() => socket.close()));
+* store.dispose();
+* ```
+*/
+var DisposableStore = class {
+	#items = /* @__PURE__ */ new Set();
+	#disposed = false;
+	/** Whether {@link dispose} has already run. */
+	get isDisposed() {
+		return this.#disposed;
+	}
+	/** Number of disposables currently held. */
+	get size() {
+		return this.#items.size;
+	}
+	/**
+	* Registers a disposable.
+	*
+	* When the store is already disposed the argument is disposed immediately,
+	* which keeps late registrations from leaking.
+	*
+	* @returns The same disposable, for convenient chaining.
+	*/
+	add(disposable) {
+		if (this.#disposed) {
+			disposable.dispose();
+			return disposable;
+		}
+		this.#items.add(disposable);
+		return disposable;
+	}
+	/** Disposes and forgets a single entry. Returns `false` when not held. */
+	delete(disposable) {
+		if (!this.#items.delete(disposable)) return false;
+		disposable.dispose();
+		return true;
+	}
+	/** Disposes everything held without marking the store itself as disposed. */
+	clear() {
+		const errors = disposeAll(this.#items);
+		this.#items.clear();
+		if (errors.length > 0) throw new AggregateError(errors, "Failed to dispose one or more items");
+	}
+	/** Disposes everything held and blocks further use. Safe to call repeatedly. */
+	dispose() {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		this.clear();
+	}
+};
+/** Disposes items newest-first, collecting rather than propagating errors. */
+function disposeAll(items) {
+	const errors = [];
+	const snapshot = Array.from(items);
+	for (let index = snapshot.length - 1; index >= 0; index -= 1) {
+		const item = snapshot[index];
+		if (!item) continue;
+		try {
+			item.dispose();
+		} catch (error) {
+			errors.push(error);
+		}
+	}
+	return errors;
+}
+
+//#endregion
+//#region src/base/errors.ts
+/**
+* Builds a {@link HudhodError}.
+*
+* @example
+* ```ts
+* throw createError("FileNotFound", "No such file: /a.ts", { path: "/a.ts" });
+* ```
+*/
+function createError(code, message, details = {}) {
+	const error = new Error(message, { cause: details.cause });
+	error.name = `HudhodError(${code})`;
+	error.code = code;
+	if (details.path !== void 0) error.path = details.path;
+	if (details.partialOutput !== void 0) error.partialOutput = details.partialOutput;
+	return error;
+}
+/** The path does not exist. */
+function fileNotFound(path) {
+	return createError("FileNotFound", `File not found: ${path}`, { path });
+}
+/** The path exists and overwriting was not permitted. */
+function fileExists(path) {
+	return createError("FileExists", `File already exists: ${path}`, { path });
+}
+/** A directory was required but the path is not one. */
+function notADirectory(path) {
+	return createError("NotADirectory", `Not a directory: ${path}`, { path });
+}
+/** A file was required but the path is not one. */
+function notAFile(path) {
+	return createError("NotAFile", `Not a file: ${path}`, { path });
+}
+/** The directory still has children and `recursive` was not set. */
+function directoryNotEmpty(path) {
+	return createError("DirectoryNotEmpty", `Directory not empty: ${path}`, { path });
+}
+/** The path is malformed, relative, or escapes the workspace root. */
+function invalidPath(path, reason) {
+	return createError("InvalidPath", `Invalid path "${path}": ${reason}`, { path });
+}
+
+//#endregion
+//#region src/base/paths.ts
+/** The workspace root. */
+const ROOT = "/";
+/**
+* Normalises a path: collapses duplicate slashes, resolves `.` and `..`, and
+* strips any trailing slash.
+*
+* @throws An `InvalidPath` error when the path is relative, empty, or traverses
+* above the workspace root.
+*
+* @example
+* ```ts
+* normalizePath("/src//lib/../index.ts"); // "/src/index.ts"
+* ```
+*/
+function normalizePath(path) {
+	if (typeof path !== "string" || path.length === 0) throw invalidPath(String(path), "path must be a non-empty string");
+	if (path.includes("\0")) throw invalidPath(path, "path must not contain null bytes");
+	if (!path.startsWith("/")) throw invalidPath(path, "path must be absolute");
+	const resolved = [];
+	for (const segment of path.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			if (resolved.length === 0) throw invalidPath(path, "path escapes the workspace root");
+			resolved.pop();
+			continue;
+		}
+		resolved.push(segment);
+	}
+	return resolved.length === 0 ? ROOT : `/${resolved.join("/")}`;
+}
+/**
+* Joins segments onto a base path and normalises the result.
+*
+* @example
+* ```ts
+* joinPath("/src", "lib", "index.ts"); // "/src/lib/index.ts"
+* ```
+*/
+function joinPath(base, ...segments) {
+	const suffix = segments.filter((segment) => segment.length > 0).join("/");
+	return normalizePath(suffix.length === 0 ? base : `${base}/${suffix}`);
+}
+/**
+* Returns the parent directory. The root is its own parent.
+*
+* @example
+* ```ts
+* dirname("/src/index.ts"); // "/src"
+* dirname("/");             // "/"
+* ```
+*/
+function dirname(path) {
+	const normalized = normalizePath(path);
+	if (normalized === ROOT) return ROOT;
+	const index = normalized.lastIndexOf("/");
+	return index <= 0 ? ROOT : normalized.slice(0, index);
+}
+/**
+* Returns the final segment. The root has an empty basename.
+*
+* @example
+* ```ts
+* basename("/src/index.ts"); // "index.ts"
+* ```
+*/
+function basename(path) {
+	const normalized = normalizePath(path);
+	if (normalized === ROOT) return "";
+	return normalized.slice(normalized.lastIndexOf("/") + 1);
+}
+/**
+* Returns the lowercased extension including the leading dot, or an empty
+* string when there is none.
+*
+* A leading dot marks a hidden file rather than an extension, so `.gitignore`
+* has no extension.
+*
+* @example
+* ```ts
+* extname("/src/App.TSX");  // ".tsx"
+* extname("/.gitignore");   // ""
+* ```
+*/
+function extname(path) {
+	const name = basename(path);
+	const index = name.lastIndexOf(".");
+	if (index <= 0) return "";
+	return name.slice(index).toLowerCase();
+}
+/**
+* Expresses `path` relative to `from`, without a leading slash.
+*
+* @example
+* ```ts
+* relativePath("/src", "/src/lib/a.ts"); // "lib/a.ts"
+* ```
+*/
+function relativePath(from, path) {
+	const base = normalizePath(from);
+	const target = normalizePath(path);
+	if (base === ROOT) return target.slice(1);
+	if (target === base) return "";
+	if (target.startsWith(`${base}/`)) return target.slice(base.length + 1);
+	return target.slice(1);
+}
+/**
+* Whether `path` is `parent` or sits underneath it.
+*
+* Compares whole segments, so `/src` does not contain `/src-old`.
+*
+* @example
+* ```ts
+* isSubPath("/src", "/src/a.ts");  // true
+* isSubPath("/src", "/src-old");   // false
+* ```
+*/
+function isSubPath(parent, path) {
+	const base = normalizePath(parent);
+	const target = normalizePath(path);
+	if (base === target) return true;
+	if (base === ROOT) return true;
+	return target.startsWith(`${base}/`);
+}
+/**
+* Splits a path into its segments. The root yields an empty array.
+*
+* @example
+* ```ts
+* pathSegments("/src/lib/a.ts"); // ["src", "lib", "a.ts"]
+* ```
+*/
+function pathSegments(path) {
+	const normalized = normalizePath(path);
+	return normalized === ROOT ? [] : normalized.slice(1).split("/");
+}
+
+//#endregion
+export { DisposableStore as _, isSubPath as a, pathSegments as c, directoryNotEmpty as d, fileExists as f, notAFile as g, notADirectory as h, extname as i, relativePath as l, invalidPath as m, basename as n, joinPath as o, fileNotFound as p, dirname as r, normalizePath as s, ROOT as t, createError as u, NO_OP_DISPOSABLE as v, toDisposable as y };

package/dist/spawner-CqGITKbd.d.ts

@@ -0,0 +1,150 @@
+import { Disposable, FileChangeEvent, FileType } from "@hudhod/sdk";
+
+//#region src/fs/provider.d.ts
+
+/** Metadata a provider reports for a path. */
+interface ProviderStat {
+  /** Whether the entry is a file, directory, or symlink. */
+  readonly type: FileType;
+  /** Size in bytes. Providers may report `0` for directories. */
+  readonly size: number;
+  /** Last-modified time, in milliseconds since the Unix epoch. */
+  readonly mtime: number;
+}
+/** A child entry reported by {@link FileSystemProvider.readDirectory}. */
+interface ProviderEntry {
+  /** Entry name, with no directory component. */
+  readonly name: string;
+  /** Whether the entry is a file, directory, or symlink. */
+  readonly type: FileType;
+}
+/** Options for {@link FileSystemProvider.watch}. */
+interface ProviderWatchOptions {
+  /** Whether to watch nested directories. */
+  readonly recursive: boolean;
+}
+/**
+ * A storage backend.
+ *
+ * ## Implementer contract
+ *
+ * - Every `path` argument is already normalised: absolute, POSIX-style, no
+ *   trailing slash, no `.` or `..` segments. Providers must not re-normalise.
+ * - Throw the typed errors from `@hudhod/core` — `fileNotFound`,
+ *   `notADirectory`, and friends — so callers can branch on `error.code`.
+ * - Do not create parent directories implicitly; {@link FileSystemService}
+ *   handles that so the behaviour is identical across backends.
+ * - `watch` is best-effort. A provider that cannot watch may return a no-op
+ *   disposable, at the cost of stale UI when files change outside the app.
+ */
+interface FileSystemProvider {
+  /** Human-readable backend name, used in diagnostics. */
+  readonly name: string;
+  /**
+   * Reads a file's raw bytes.
+   * @throws `FileNotFound` when the path does not exist.
+   * @throws `NotAFile` when the path is a directory.
+   */
+  readFile(path: string): Promise<Uint8Array>;
+  /**
+   * Writes a file's raw bytes, replacing any existing content.
+   * @throws `FileNotFound` when the parent directory does not exist.
+   */
+  writeFile(path: string, data: Uint8Array): Promise<void>;
+  /**
+   * Creates a directory. Implementations may assume the parent exists.
+   * @throws `FileExists` when a *file* already occupies the path.
+   */
+  createDirectory(path: string): Promise<void>;
+  /**
+   * Removes a file or directory.
+   * @throws `FileNotFound` when the path does not exist.
+   * @throws `DirectoryNotEmpty` when removing a non-empty directory without `recursive`.
+   */
+  delete(path: string, options: {
+    recursive: boolean;
+  }): Promise<void>;
+  /**
+   * Moves an entry.
+   * @throws `FileNotFound` when the source does not exist.
+   * @throws `FileExists` when the destination exists and `overwrite` is false.
+   */
+  rename(from: string, to: string, options: {
+    overwrite: boolean;
+  }): Promise<void>;
+  /**
+   * Reads metadata.
+   * @throws `FileNotFound` when the path does not exist.
+   */
+  stat(path: string): Promise<ProviderStat>;
+  /**
+   * Lists a directory's immediate children, in any order.
+   * @throws `FileNotFound` when the path does not exist.
+   * @throws `NotADirectory` when the path is a file.
+   */
+  readDirectory(path: string): Promise<ProviderEntry[]>;
+  /**
+   * Observes changes beneath a path.
+   *
+   * Events may be delivered individually or in batches; debouncing is the
+   * service's job. Returns a {@link Disposable} that stops the watch.
+   */
+  watch(path: string, options: ProviderWatchOptions, listener: (events: readonly FileChangeEvent[]) => void): Disposable;
+}
+//#endregion
+//#region src/process/spawner.d.ts
+/**
+ * The process spawning abstraction.
+ *
+ * Mirrors the {@link FileSystemProvider} pattern: services depend on this
+ * interface rather than on WebContainer directly, so process semantics —
+ * timeouts, output caps, lifecycle tracking — can be tested in Node against a
+ * fake.
+ *
+ * @packageDocumentation
+ */
+/** A process that has been started by a {@link ProcessSpawner}. */
+interface SpawnedProcess {
+  /** Merged stdout and stderr, as decoded text chunks. */
+  readonly output: ReadableStream<string>;
+  /** Standard input. */
+  readonly input: WritableStream<string>;
+  /** Resolves with the exit code when the process finishes. */
+  readonly exit: Promise<number>;
+  /** Terminates the process. Must be safe to call after exit. */
+  kill(): void;
+  /** Resizes the pseudo-terminal, if the process has one. */
+  resize(dimensions: {
+    cols: number;
+    rows: number;
+  }): void;
+}
+/** Options passed through to the backend. */
+interface SpawnerOptions {
+  /** Working directory. */
+  readonly cwd?: string;
+  /** Environment variables to merge over the backend defaults. */
+  readonly env?: Readonly<Record<string, string>>;
+  /** Pseudo-terminal dimensions, when one is required. */
+  readonly terminal?: {
+    readonly cols: number;
+    readonly rows: number;
+  };
+}
+/**
+ * Starts processes.
+ *
+ * ## Implementer contract
+ *
+ * - `output` must close when the process exits, otherwise readers hang.
+ * - `exit` must resolve exactly once, including when the process is killed.
+ * - `kill()` must be idempotent.
+ */
+interface ProcessSpawner {
+  /** Human-readable backend name, used in diagnostics. */
+  readonly name: string;
+  /** Starts a process. */
+  spawn(command: string, args: readonly string[], options: SpawnerOptions): Promise<SpawnedProcess>;
+}
+//#endregion
+export { ProviderEntry as a, FileSystemProvider as i, SpawnedProcess as n, ProviderStat as o, SpawnerOptions as r, ProviderWatchOptions as s, ProcessSpawner as t };

package/dist/webcontainer/index.d.ts

@@ -0,0 +1,67 @@
+import { a as ProviderEntry, i as FileSystemProvider, n as SpawnedProcess, o as ProviderStat, r as SpawnerOptions, s as ProviderWatchOptions, t as ProcessSpawner } from "../spawner-CqGITKbd.js";
+import { Disposable, FileChangeEvent } from "@hudhod/sdk";
+import { WebContainer } from "@webcontainer/api";
+
+//#region src/webcontainer/file-system-provider.d.ts
+
+/**
+ * Adapts WebContainer's file system to the provider contract.
+ *
+ * ## Known limitations
+ *
+ * WebContainer exposes no `stat` call, so {@link stat} is emulated by listing
+ * the parent directory. Two consequences follow, and both are deliberate:
+ *
+ * - `mtime` is always `0`. No modification time is available, and inventing one
+ *   from `Date.now()` would be worse than reporting an obvious sentinel.
+ * - `size` requires reading the file. {@link FileSystemService} calls `stat`
+ *   mainly through `exists()`, which discards the size, so this is acceptable —
+ *   but avoid calling `stat` in a hot loop.
+ */
+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[]>;
+  /**
+   * Watches a subtree.
+   *
+   * WebContainer reports a `rename` event for both creation and deletion, so
+   * each one is resolved by probing for the path afterwards. The probe is why
+   * the listener is async and why events arrive slightly after the change.
+   */
+  watch(path: string, options: ProviderWatchOptions, listener: (events: readonly FileChangeEvent[]) => void): Disposable;
+}
+//#endregion
+//#region src/webcontainer/process-spawner.d.ts
+/**
+ * Spawns processes inside a WebContainer.
+ *
+ * The mapping is close to one-to-one: WebContainer already exposes a merged
+ * output stream, a writable stdin, and an exit promise. The only adaptation is
+ * making `kill()` idempotent, which the provider contract requires.
+ *
+ * @example
+ * ```ts
+ * const spawner = new WebContainerProcessSpawner(container);
+ * const processes = new ProcessService(spawner);
+ * ```
+ */
+declare class WebContainerProcessSpawner implements ProcessSpawner {
+  #private;
+  readonly name = "webcontainer";
+  constructor(container: WebContainer);
+  spawn(command: string, args: readonly string[], options: SpawnerOptions): Promise<SpawnedProcess>;
+}
+//#endregion
+export { WebContainerFileSystemProvider, WebContainerProcessSpawner };

package/dist/webcontainer/index.js

@@ -0,0 +1,200 @@
+import { d as directoryNotEmpty, f as fileExists, h as notADirectory, n as basename, o as joinPath, p as fileNotFound, r as dirname, t as ROOT, y as toDisposable } from "../paths-B3gr2EuI.js";
+
+//#region src/webcontainer/file-system-provider.ts
+/**
+* Adapts WebContainer's file system to the provider contract.
+*
+* ## Known limitations
+*
+* WebContainer exposes no `stat` call, so {@link stat} is emulated by listing
+* the parent directory. Two consequences follow, and both are deliberate:
+*
+* - `mtime` is always `0`. No modification time is available, and inventing one
+*   from `Date.now()` would be worse than reporting an obvious sentinel.
+* - `size` requires reading the file. {@link FileSystemService} calls `stat`
+*   mainly through `exists()`, which discards the size, so this is acceptable —
+*   but avoid calling `stat` in a hot loop.
+*/
+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) {
+		let entries;
+		try {
+			entries = await this.#container.fs.readdir(path, { withFileTypes: true });
+		} catch (error) {
+			if (isErrno(error, "ENOTDIR")) throw notADirectory(path);
+			throw translate(error, path);
+		}
+		return entries.map((entry) => ({
+			name: entry.name,
+			type: entry.isDirectory() ? "directory" : "file"
+		}));
+	}
+	/**
+	* Watches a subtree.
+	*
+	* WebContainer reports a `rename` event for both creation and deletion, so
+	* each one is resolved by probing for the path afterwards. The probe is why
+	* the listener is async and why events arrive slightly after the change.
+	*/
+	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());
+	}
+	/** Existence probe that never throws. */
+	async #exists(path) {
+		try {
+			await this.stat(path);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+/** Whether an unknown thrown value is a Node-style error with `code`. */
+function isErrno(error, code) {
+	return typeof error === "object" && error !== null && error.code === code;
+}
+/** Converts a WebContainer/Node error into a typed hudhod error. */
+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
+//#region src/webcontainer/process-spawner.ts
+/**
+* Spawns processes inside a WebContainer.
+*
+* The mapping is close to one-to-one: WebContainer already exposes a merged
+* output stream, a writable stdin, and an exit promise. The only adaptation is
+* making `kill()` idempotent, which the provider contract requires.
+*
+* @example
+* ```ts
+* const spawner = new WebContainerProcessSpawner(container);
+* const processes = new ProcessService(spawner);
+* ```
+*/
+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) return;
+				process.resize(dimensions);
+			}
+		};
+	}
+};
+
+//#endregion
+export { WebContainerFileSystemProvider, WebContainerProcessSpawner };