@yansirplus/workspace-env-local 0.2.9

package/PUBLIC_API.md

@@ -0,0 +1,26 @@
+<!-- generated by scripts/generate-docs.mjs; edit docs/surface.json and docs/api/workspace-env-local.md -->
+
+# @agent-os/workspace-env-local Public API
+
+Status: 0.2.x active development. Public exports are limited to local WorkspaceEnv adapter types and factories.
+
+## Public exports
+
+- `.:LocalWorkspaceEnvError`
+- `.:LocalWorkspaceEnvOptions`
+- `.:LocalWorkspaceEnvWithRoot`
+- `.:TemporaryLocalWorkspaceEnvOptions`
+- `.:makeLocalWorkspaceEnv`
+- `.:makeTemporaryLocalWorkspaceEnv`
+
+## Experimental exports
+
+None.
+
+## Deprecated exports
+
+None.
+
+## Internal-only exports
+
+Any package file or symbol not listed above.

package/README.md

@@ -0,0 +1,38 @@
+<!-- generated by scripts/generate-docs.mjs; edit docs/surface.json and docs/packages/workspace-env-local.md -->
+
+# @agent-os/workspace-env-local
+
+## Purpose
+
+Local host adapter for `@agent-os/workspace-env`.
+
+## Public API Status
+
+0.2.x active development. Provider-specific exports are listed in `PUBLIC_API.md`; this is not an API freeze.
+
+## Invariant
+
+The adapter maps a virtual workspace root such as `/workspace` to one explicit
+host directory and declares generated tools as `effectful host`. Host execution
+is never implicit: a consumer must construct this adapter directly, and the
+tool contract carries the host execution domain.
+
+This is not a `just-bash` fallback. It does not embed an in-memory shell and it
+does not silently replace Cloudflare Sandbox or another provider. It uses real
+Node fs and real host shell calls bound to the declared root.
+
+## Minimal Usage
+
+Create an isolated root directory, then call `makeLocalWorkspaceEnv`. The
+returned env can be passed to `createWorkspaceTools`.
+
+For throwaway tests or onboarding demos, call `makeTemporaryLocalWorkspaceEnv`.
+The returned root directory remains caller-owned and should be removed by the
+test or demo harness.
+
+## Verification
+
+```sh
+cd packages/execution-domains/workspace-env-local
+vp test run
+```

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { type WorkspaceEnv } from "@yansirplus/workspace-env";
+export interface LocalWorkspaceEnvOptions {
+    readonly rootDir: string;
+    readonly cwd?: string;
+    readonly workspaceRef?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly envAllowlist?: ReadonlyArray<string>;
+}
+export interface TemporaryLocalWorkspaceEnvOptions {
+    readonly prefix?: string;
+    readonly cwd?: string;
+    readonly workspaceRef?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly envAllowlist?: ReadonlyArray<string>;
+}
+export interface LocalWorkspaceEnvWithRoot {
+    readonly env: WorkspaceEnv;
+    readonly rootDir: string;
+}
+export declare class LocalWorkspaceEnvError extends Error {
+    readonly name = "LocalWorkspaceEnvError";
+}
+export declare const makeLocalWorkspaceEnv: (options: LocalWorkspaceEnvOptions) => WorkspaceEnv;
+export declare const makeTemporaryLocalWorkspaceEnv: (options?: TemporaryLocalWorkspaceEnvOptions) => Promise<LocalWorkspaceEnvWithRoot>;

package/dist/index.js

@@ -0,0 +1,254 @@
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createWorkspaceEnv, } from "@yansirplus/workspace-env";
+export class LocalWorkspaceEnvError extends Error {
+    name = "LocalWorkspaceEnvError";
+}
+const DEFAULT_CWD = "/workspace";
+const TIMEOUT_EXIT_CODE = 124;
+const localError = (message) => new LocalWorkspaceEnvError(message);
+const abortErrorFor = (signal) => {
+    const reason = signal.reason;
+    if (reason instanceof Error)
+        return reason;
+    const error = new Error(reason === undefined ? "workspace operation aborted" : String(reason));
+    error.name = "AbortError";
+    return error;
+};
+const checkSignal = (signal) => {
+    if (signal?.aborted)
+        throw abortErrorFor(signal);
+};
+const normalizeRootDir = (rootDir) => {
+    const resolved = path.resolve(rootDir);
+    if (resolved.length === path.parse(resolved).root.length) {
+        throw localError("local workspace root cannot be filesystem root");
+    }
+    return resolved;
+};
+const relativeVirtualPath = (cwd, virtualPath) => {
+    if (virtualPath === cwd)
+        return "";
+    if (!virtualPath.startsWith(`${cwd}/`)) {
+        throw localError("workspace path is outside local workspace root");
+    }
+    return virtualPath.slice(cwd.length + 1);
+};
+const hostPathFor = (rootDir, cwd, virtualPath) => {
+    const hostPath = path.resolve(rootDir, relativeVirtualPath(cwd, virtualPath));
+    if (hostPath !== rootDir && !hostPath.startsWith(`${rootDir}${path.sep}`)) {
+        throw localError("workspace path escapes local root");
+    }
+    return hostPath;
+};
+const statType = (stat) => stat.isFile() ? "file" : stat.isDirectory() ? "directory" : "other";
+const fileStat = async (hostPath) => {
+    const stat = await fs.stat(hostPath);
+    return {
+        type: statType(stat),
+        size: stat.size,
+        mtimeMs: stat.mtimeMs,
+    };
+};
+const truncateUtf8 = (bytes, maxOutputBytes) => {
+    if (maxOutputBytes === undefined || bytes.byteLength <= maxOutputBytes) {
+        return { text: new TextDecoder().decode(bytes), bytes: bytes.byteLength, truncated: false };
+    }
+    return {
+        text: new TextDecoder().decode(bytes.slice(0, maxOutputBytes)),
+        bytes: bytes.byteLength,
+        truncated: true,
+    };
+};
+const appendChunk = (chunks, chunk) => {
+    chunks.push(typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk);
+};
+const concatChunks = (chunks) => {
+    const length = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+    const output = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        output.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return output;
+};
+const allowedEnv = (source, allowlist) => {
+    const entries = [];
+    for (const name of allowlist) {
+        const value = source[name];
+        if (value !== undefined)
+            entries.push([name, value]);
+    }
+    return Object.fromEntries(entries);
+};
+const signalAbortPromise = (signal) => new Promise((_resolve, reject) => {
+    if (signal === undefined)
+        return;
+    if (signal.aborted) {
+        reject(abortErrorFor(signal));
+        return;
+    }
+    signal.addEventListener("abort", () => reject(abortErrorFor(signal)), { once: true });
+});
+const runLocalCommand = async (command, hostCwd, sourceEnv, envAllowlist, options) => {
+    if (options.envRefs !== undefined && Object.keys(options.envRefs).length > 0) {
+        throw localError("local WorkspaceEnv does not resolve symbolic envRefs");
+    }
+    if (options.materialRefs !== undefined && options.materialRefs.length > 0) {
+        throw localError("local WorkspaceEnv does not resolve symbolic materialRefs");
+    }
+    if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
+        throw localError("local WorkspaceEnv exec requires a positive finite timeoutMs");
+    }
+    checkSignal(options.signal);
+    const started = Date.now();
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let timedOut = false;
+    let externalAbort = false;
+    const child = spawn(command, {
+        cwd: hostCwd,
+        env: allowedEnv(sourceEnv, envAllowlist),
+        shell: true,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const kill = () => {
+        if (!child.killed)
+            child.kill("SIGTERM");
+    };
+    const abortListener = () => {
+        externalAbort = true;
+        kill();
+    };
+    options.signal?.addEventListener("abort", abortListener, { once: true });
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        kill();
+    }, options.timeoutMs);
+    try {
+        const result = await Promise.race([
+            new Promise((resolve, reject) => {
+                child.stdout?.on("data", (chunk) => appendChunk(stdoutChunks, chunk));
+                child.stderr?.on("data", (chunk) => appendChunk(stderrChunks, chunk));
+                child.once("error", reject);
+                child.once("close", (code, signal) => resolve({ code, signal }));
+            }),
+            signalAbortPromise(options.signal),
+        ]);
+        if (externalAbort)
+            throw abortErrorFor(options.signal);
+        const stdout = truncateUtf8(concatChunks(stdoutChunks), options.maxOutputBytes);
+        const stderrBytes = concatChunks(stderrChunks);
+        const timeoutMessage = timedOut
+            ? new TextEncoder().encode(`${stderrBytes.byteLength === 0 ? "" : "\n"}Command timed out after ${options.timeoutMs}ms`)
+            : new Uint8Array();
+        const stderr = truncateUtf8(timeoutMessage.byteLength === 0 ? stderrBytes : concatChunks([stderrBytes, timeoutMessage]), options.maxOutputBytes);
+        return {
+            exitCode: timedOut ? TIMEOUT_EXIT_CODE : (result.code ?? (result.signal === null ? 1 : 128)),
+            stdout: stdout.text,
+            stderr: stderr.text,
+            stdoutBytes: stdout.bytes,
+            stderrBytes: stderr.bytes,
+            stdoutTruncated: stdout.truncated,
+            stderrTruncated: stderr.truncated,
+            durationMs: Date.now() - started,
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+        options.signal?.removeEventListener("abort", abortListener);
+    }
+};
+const localBackend = (rootDir, cwd, sourceEnv, envAllowlist) => ({
+    readFile: async (virtualPath, options) => {
+        checkSignal(options?.signal);
+        const content = await fs.readFile(hostPathFor(rootDir, cwd, virtualPath), "utf8");
+        checkSignal(options?.signal);
+        return content;
+    },
+    readFileBuffer: async (virtualPath, options) => {
+        checkSignal(options?.signal);
+        const content = await fs.readFile(hostPathFor(rootDir, cwd, virtualPath));
+        checkSignal(options?.signal);
+        return content;
+    },
+    writeFile: async (virtualPath, content, options) => {
+        checkSignal(options?.signal);
+        await fs.writeFile(hostPathFor(rootDir, cwd, virtualPath), content);
+        checkSignal(options?.signal);
+    },
+    stat: async (virtualPath, options) => {
+        checkSignal(options?.signal);
+        const stat = await fileStat(hostPathFor(rootDir, cwd, virtualPath));
+        checkSignal(options?.signal);
+        return stat;
+    },
+    readdir: async (virtualPath, options) => {
+        checkSignal(options?.signal);
+        const entries = await fs.readdir(hostPathFor(rootDir, cwd, virtualPath));
+        checkSignal(options?.signal);
+        return entries.sort();
+    },
+    exists: async (virtualPath, options) => {
+        checkSignal(options?.signal);
+        try {
+            await fs.access(hostPathFor(rootDir, cwd, virtualPath));
+            checkSignal(options?.signal);
+            return true;
+        }
+        catch {
+            checkSignal(options?.signal);
+            return false;
+        }
+    },
+    mkdir: async (virtualPath, options) => {
+        checkSignal(options?.signal);
+        await fs.mkdir(hostPathFor(rootDir, cwd, virtualPath), {
+            recursive: options?.recursive ?? false,
+        });
+        checkSignal(options?.signal);
+    },
+    rm: async (virtualPath, options) => {
+        checkSignal(options?.signal);
+        await fs.rm(hostPathFor(rootDir, cwd, virtualPath), {
+            recursive: options?.recursive ?? false,
+            force: options?.force ?? false,
+        });
+        checkSignal(options?.signal);
+    },
+    exec: async (command, options) => {
+        const hostCwd = hostPathFor(rootDir, cwd, options.cwd ?? cwd);
+        await fs.mkdir(hostCwd, { recursive: true });
+        return runLocalCommand(command, hostCwd, sourceEnv, envAllowlist, options);
+    },
+});
+export const makeLocalWorkspaceEnv = (options) => {
+    const rootDir = normalizeRootDir(options.rootDir);
+    const cwd = options.cwd ?? DEFAULT_CWD;
+    const envAllowlist = options.envAllowlist ?? [];
+    return createWorkspaceEnv({
+        cwd,
+        domain: {
+            kind: "host",
+            ref: options.workspaceRef ?? `local:${rootDir}`,
+            envAllowlist,
+        },
+        backend: localBackend(rootDir, cwd, options.env ?? process.env, envAllowlist),
+    });
+};
+export const makeTemporaryLocalWorkspaceEnv = async (options = {}) => {
+    const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), options.prefix ?? "agent-os-workspace-"));
+    return {
+        rootDir,
+        env: makeLocalWorkspaceEnv({
+            rootDir,
+            cwd: options.cwd,
+            workspaceRef: options.workspaceRef,
+            env: options.env,
+            envAllowlist: options.envAllowlist,
+        }),
+    };
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@yansirplus/workspace-env-local",
+  "version": "0.2.9",
+  "type": "module",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "PUBLIC_API.md"
+  ],
+  "dependencies": {
+    "@yansirplus/workspace-env": "0.2.9"
+  }
+}