@demicodes/host-local 0.17.3 → 0.18.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { AgentHarness, AgentServer, AgentServerSessionOptions } from "@demicodes/agent";
 import { resolveDemiHome } from "@demicodes/provider/credentials-pool";
-import { BashEnvironmentOptions, Host, HostFileSystem, HostProcess, HostStore } from "@demicodes/shell";
+import { BashEnvironmentOptions, Host, HostFileSystem, HostIdentity, HostProcess, HostStore } from "@demicodes/shell";
 import { Provider } from "@demicodes/provider";
 //#region src/command-bridge.d.ts
 /**
@@ -50,6 +50,8 @@ interface LocalHostOptions {
   storeRoot?: string;
   /** Where command artifacts land as plain files; defaults next to the store. */
   commandArtifactsDir?: string;
+  /** Bring-your-own persistence, e.g. to wrap or gate writes; defaults to a LocalHostStore rooted at storeRoot. */
+  store?: HostStore;
 }
 declare class LocalHost implements Host {
   readonly defaultCwd: string;
@@ -57,9 +59,21 @@ declare class LocalHost implements Host {
   readonly fs: HostFileSystem;
   readonly process: HostProcess;
   readonly store: HostStore;
+  readonly identity: HostIdentity;
   constructor(defaultCwd: string, options?: LocalHostOptions);
 }
 //#endregion
+//#region src/local-store.d.ts
+declare class LocalHostStore implements HostStore {
+  readonly root: string;
+  constructor(root: string);
+  readJson<T>(key: string): Promise<T | null>;
+  writeJson<T>(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(prefix: string): Promise<string[]>;
+  private pathForKey;
+}
+//#endregion
 //#region src/local-agent-server.d.ts
 interface CreateLocalAgentServerOptions {
   /** Same LocalHost instance the harness was built with. */
@@ -106,4 +120,4 @@ interface LocalAgentServerHandle {
  */
 declare function createLocalAgentServer(options: CreateLocalAgentServerOptions): LocalAgentServerHandle;
 //#endregion
-export { COMMAND_BRIDGE_SHIM_SOURCE, CommandBridgeHandle, CommandBridgeOptions, CreateLocalAgentServerOptions, LocalAgentServerHandle, LocalHost, LocalHostOptions, MaterializeCommandBridgeShimsOptions, bridgeBinDirFor, createLocalAgentServer, defaultBridgeSocketPath, materializeCommandBridgeShims, resolveDemiHome, startCommandBridge };
+export { COMMAND_BRIDGE_SHIM_SOURCE, CommandBridgeHandle, CommandBridgeOptions, CreateLocalAgentServerOptions, LocalAgentServerHandle, LocalHost, LocalHostOptions, LocalHostStore, MaterializeCommandBridgeShimsOptions, bridgeBinDirFor, createLocalAgentServer, defaultBridgeSocketPath, materializeCommandBridgeShims, resolveDemiHome, startCommandBridge };

package/dist/index.mjs

@@ -1,13 +1,13 @@
-import { existsSync, mkdirSync, unlinkSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { constants, existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { dirname, isAbsolute, join, posix, relative, resolve } from "node:path";
 import { createServer } from "node:http";
 import { AgentServer, RunCommandLineCommandNotRegisteredError, RunCommandLineShellNotFoundError, RunCommandLineTimeoutError } from "@demicodes/agent";
 import { encodeUtf8, errorMessage, isFileNotFoundError, parsePortableJson, stringifyPortableJson } from "@demicodes/utils";
 import { createHash, randomUUID } from "node:crypto";
 import { resolveDemiHome } from "@demicodes/provider/credentials-pool";
 import { spawn } from "node:child_process";
-import { homedir } from "node:os";
-import { appendFile, chmod, cp, link, lstat, mkdir, readFile, readdir, readlink, realpath, rename, rm, stat, symlink, utimes, writeFile } from "node:fs/promises";
+import { homedir, hostname, userInfo } from "node:os";
+import { appendFile, chmod, cp, link, lstat, mkdir, open, readFile, readdir, readlink, realpath, rename, rm, stat, symlink, utimes, writeFile } from "node:fs/promises";
 //#region src/command-bridge.ts
 /**
 * Dispatch script shared by every generated command-name symlink.
@@ -337,6 +337,61 @@ function validateHostStoreKey(key) {
 	for (const segment of key.split(/[\\/]+/)) if (segment === "..") throw new Error(`HostStore keys must not contain path traversal: ${key}`);
 }
 //#endregion
+//#region src/local-cwd.ts
+const DIR_FLAGS = constants.O_RDONLY | constants.O_DIRECTORY;
+var LocalHostCwd = class LocalHostCwd {
+	path;
+	handle;
+	static async open(path) {
+		const cwd = new LocalHostCwd(path);
+		cwd.handle = await open(path, DIR_FLAGS);
+		return cwd;
+	}
+	constructor(path) {
+		this.path = path;
+	}
+	spawnPath() {
+		return this.fdAnchor() ?? this.path;
+	}
+	async chdir(path) {
+		if (path === ".") return;
+		const target = isAbsolute(path) ? path : this.fdAnchor() ? `${this.fdAnchor()}/${path}` : posix.join(this.path, path);
+		const next = await open(target, DIR_FLAGS);
+		const previous = this.handle;
+		this.handle = next;
+		this.path = isAbsolute(path) ? path : posix.normalize(posix.join(this.path, path));
+		await previous?.close().catch(() => {});
+	}
+	async snapshot() {
+		const anchor = this.fdAnchor();
+		if (!this.handle || !anchor) {
+			const path = this.path;
+			const handle = this.handle;
+			return { restore: () => {
+				this.path = path;
+				this.handle = handle;
+			} };
+		}
+		const dup = await open(anchor, DIR_FLAGS);
+		const path = this.path;
+		return { restore: () => {
+			const abandoned = this.handle;
+			this.handle = dup;
+			this.path = path;
+			if (abandoned && abandoned.fd !== dup.fd) abandoned.close().catch(() => {});
+		} };
+	}
+	async close() {
+		await this.handle?.close().catch(() => {});
+		this.handle = void 0;
+	}
+	fdAnchor() {
+		if (!this.handle) return void 0;
+		if (process.platform === "linux") return `/proc/self/fd/${this.handle.fd}`;
+		if (process.platform === "darwin") return `/dev/fd/${this.handle.fd}`;
+	}
+};
+//#endregion
 //#region src/local-host.ts
 var LocalHost = class {
 	defaultCwd;
@@ -344,13 +399,20 @@ var LocalHost = class {
 	fs;
 	process;
 	store;
+	identity;
 	constructor(defaultCwd, options = {}) {
 		this.defaultCwd = resolve(defaultCwd);
 		const storeRoot = options.storeRoot ?? defaultStoreRoot(this.defaultCwd);
 		this.commandArtifactsDir = resolve(options.commandArtifactsDir ?? join(storeRoot, "command-artifacts"));
 		this.fs = new LocalHostFileSystem(this.defaultCwd);
 		this.process = new LocalHostProcess(this.defaultCwd);
-		this.store = new LocalHostStore(storeRoot);
+		this.store = options.store ?? new LocalHostStore(storeRoot);
+		const info = userInfo();
+		this.identity = {
+			uid: info.uid,
+			gid: info.gid,
+			hostname: hostname()
+		};
 	}
 };
 var LocalHostProcess = class {
@@ -358,13 +420,14 @@ var LocalHostProcess = class {
 	constructor(defaultCwd) {
 		this.defaultCwd = defaultCwd;
 	}
+	async openCwd(path) {
+		return LocalHostCwd.open(path);
+	}
 	async spawn(params) {
+		const cwd = params.cwd ?? this.defaultCwd;
 		const child = spawn(params.command, params.args ?? [], {
-			cwd: params.cwd ?? this.defaultCwd,
-			env: {
-				...process.env,
-				...params.env
-			},
+			cwd,
+			...params.env ? { env: definedEnv(params.env) } : {},
 			detached: params.killProcessGroup === true,
 			stdio: [
 				"pipe",
@@ -373,21 +436,26 @@ var LocalHostProcess = class {
 			]
 		});
 		let settled = false;
-		const waitPromise = new Promise((resolve) => {
+		const waitPromise = new Promise((resolveWait) => {
 			child.once("error", (error) => {
 				if (settled) return;
 				settled = true;
-				resolve({
-					exitCode: null,
-					signal: error.message
+				classifySpawnFailure(error, cwd).then((kind) => {
+					resolveWait({
+						exitCode: null,
+						signal: error.message,
+						spawnError: { kind }
+					});
 				});
 			});
 			child.once("close", (exitCode, signal) => {
-				if (settled) return;
-				settled = true;
-				resolve({
-					exitCode,
-					signal: signal ?? void 0
+				setImmediate(() => {
+					if (settled) return;
+					settled = true;
+					resolveWait({
+						exitCode,
+						signal: signal ?? void 0
+					});
 				});
 			});
 		});
@@ -565,9 +633,33 @@ function toHostFileStat(value) {
 		isSymbolicLink: value.isSymbolicLink(),
 		mode: value.mode,
 		size: value.size,
-		mtime: value.mtime
+		mtime: value.mtime,
+		uid: value.uid,
+		gid: value.gid,
+		ino: value.ino,
+		dev: value.dev,
+		nlink: value.nlink,
+		isCharacterDevice: value.isCharacterDevice(),
+		isFIFO: value.isFIFO()
 	};
 }
+function definedEnv(env) {
+	const defined = {};
+	for (const [key, value] of Object.entries(env)) if (value !== void 0) defined[key] = value;
+	return defined;
+}
+async function classifySpawnFailure(error, cwd) {
+	try {
+		if (!(await stat(cwd)).isDirectory()) return "cwd_unusable";
+	} catch {
+		return "cwd_unusable";
+	}
+	const code = "code" in error ? String(error.code) : "";
+	if (code === "ENOENT") return "executable_not_found";
+	if (code === "EACCES" || code === "EPERM") return "permission_denied";
+	if (code === "EISDIR") return "is_directory";
+	return "other";
+}
 function toHostDirent(value) {
 	return {
 		name: value.name,
@@ -657,4 +749,4 @@ function createLocalAgentServer(options) {
 	};
 }
 //#endregion
-export { COMMAND_BRIDGE_SHIM_SOURCE, LocalHost, bridgeBinDirFor, createLocalAgentServer, defaultBridgeSocketPath, materializeCommandBridgeShims, resolveDemiHome, startCommandBridge };
+export { COMMAND_BRIDGE_SHIM_SOURCE, LocalHost, LocalHostStore, bridgeBinDirFor, createLocalAgentServer, defaultBridgeSocketPath, materializeCommandBridgeShims, resolveDemiHome, startCommandBridge };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@demicodes/host-local",
   "description": "Node LocalHost and open-box local AgentServer assembly (command bridge on by default).",
-  "version": "0.17.3",
+  "version": "0.18.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -11,10 +11,10 @@
     }
   },
   "dependencies": {
-    "@demicodes/agent": "^0.17.3",
-    "@demicodes/provider": "^0.17.3",
-    "@demicodes/shell": "^0.17.3",
-    "@demicodes/utils": "^0.17.3"
+    "@demicodes/agent": "^0.18.0",
+    "@demicodes/provider": "^0.18.0",
+    "@demicodes/shell": "^0.18.0",
+    "@demicodes/utils": "^0.18.0"
   },
   "license": "Apache-2.0",
   "main": "./dist/index.mjs",