@warlock.js/ai-workspace 5.30.0 → 5.31.0

package/esm/backends/local.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"local.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/backends/local.ts"],"mappings":";;;;;AAsZA;;;;AAAsD;;;;;;;;;iBAAtC,kBAAA,IAAsB,gBAAgB"}
+{"version":3,"file":"local.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/backends/local.ts"],"mappings":";;;;;AAokBA;;;;AAAsD;;;;;;;;;iBAAtC,kBAAA,IAAsB,gBAAgB"}

package/esm/backends/local.mjs

@@ -1,8 +1,9 @@
 import { tokenizeCommand } from "../policy/tokenize-command.mjs";
-import { realpath } from "node:fs/promises";
+import { lstat, realpath } from "node:fs/promises";
 import { fs } from "@warlock.js/fs";
 import { spawn } from "node:child_process";
 import { platform } from "node:process";
+import { StringDecoder } from "node:string_decoder";
 
 //#region ../../packages/ai-workspace/src/backends/local.ts
 /**
@@ -95,6 +96,74 @@ function toWin32CmdInvocation(argv) {
 		]
 	};
 }
+/** The shell a POSIX shell-mode line runs through — an absolute path, never a PATH lookup. */
+const POSIX_SHELL = "/bin/sh";
+/**
+* Work out the spawn for a command line.
+*
+* - argv mode: tokenize (no shell semantics) and spawn the argv directly —
+*   on Windows through an individually-quoted `cmd.exe` wrapper.
+* - shell mode: `/bin/sh -c <line>`, or `cmd.exe /d /v:off /s /c "<line>"`
+*   on Windows (`/d` skips AutoRun, `/v:off` disables delayed `!` expansion,
+*   `/s` keeps the line verbatim inside the outer quotes). The ops layer has
+*   already checked every command in the line.
+*/
+function planSpawn(command, interpreter) {
+	if (interpreter === "sh") {
+		if (platform === "win32") return {
+			file: process.env.ComSpec ?? "cmd.exe",
+			args: [
+				"/d",
+				"/v:off",
+				"/s",
+				"/c",
+				`"${command}"`
+			],
+			windowsVerbatimArguments: true
+		};
+		return {
+			file: POSIX_SHELL,
+			args: ["-c", command],
+			windowsVerbatimArguments: false
+		};
+	}
+	const argv = tokenizeCommand(command);
+	const executable = argv?.[0];
+	if (argv === null || executable === void 0) return { refused: "Command was not executed: it is empty, has unbalanced quotes, or contains unquoted shell metacharacters (;, &, |, `, $, <, >, parentheses). Commands run without a shell — pass metacharacters inside quotes as literal arguments, or run one command at a time." };
+	if (platform === "win32") {
+		const invocation = toWin32CmdInvocation(argv);
+		if (invocation === null) return { refused: "Command was not executed: on Windows, arguments containing \", %, or newlines cannot be passed to cmd.exe safely." };
+		return {
+			...invocation,
+			windowsVerbatimArguments: true
+		};
+	}
+	return {
+		file: executable,
+		args: argv.slice(1),
+		windowsVerbatimArguments: false
+	};
+}
+/**
+* Kill functions of every background process still running, so they can
+* be reaped if the Node process exits without the workspace being disposed
+* (detached process groups would otherwise outlive it).
+*/
+const liveBackgroundKills = /* @__PURE__ */ new Set();
+let exitHookInstalled = false;
+/** Track a live background tree; installs (once) the exit hook that kills them. */
+function trackBackgroundProcess(kill) {
+	liveBackgroundKills.add(kill);
+	if (!exitHookInstalled) {
+		exitHookInstalled = true;
+		process.on("exit", () => {
+			for (const killTreeNow of liveBackgroundKills) killTreeNow();
+		});
+	}
+	return () => {
+		liveBackgroundKills.delete(kill);
+	};
+}
 /**
 * The real-disk executor: every filesystem method delegates to
 * `@warlock.js/fs` (never `node:fs`), and {@link LocalBackend.exec} spawns a
@@ -151,6 +220,17 @@ var LocalBackend = class {
 		return fs.dirs.list(absDir);
 	}
 	/**
+	* Describe a path without following a final symlink (`lstat` — like
+	* `realpath`, a filesystem operation `@warlock.js/fs` does not expose).
+	*/
+	async stat(absPath) {
+		const stats = await lstat(absPath);
+		return {
+			type: stats.isSymbolicLink() ? "symlink" : stats.isDirectory() ? "directory" : stats.isFile() ? "file" : "other",
+			size: stats.size
+		};
+	}
+	/**
 	* Resolve symlinks and `..` segments to a canonical absolute path — the
 	* primitive the ops-layer jail uses to detect escapes. Delegates to
 	* `node:fs/promises` `realpath`, the one filesystem operation `@warlock.js/fs`
@@ -160,14 +240,17 @@ var LocalBackend = class {
 		return realpath(absPath);
 	}
 	/**
-	* Run a command and capture its outcome. The command line is tokenized
-	* into an argv (quotes respected, NO shell semantics — see
-	* `tokenizeCommand`) and spawned **without a shell**, so metacharacters
-	* like `;`, `&&`, `|`, backticks, and `$()` can never chain extra
-	* commands past the ops layer's allowlist; a command they appear
-	* unquoted in is refused with exit code 127. On Windows the argv runs
-	* through a `cmd.exe /d /s /c` wrapper (batch shims like `npm.cmd`
+	* Run a command and capture its outcome. In argv mode (the default) the
+	* command line is tokenized into an argv (quotes respected, NO shell
+	* semantics — see `tokenizeCommand`) and spawned **without a shell**, so
+	* metacharacters like `;`, `&&`, `|`, backticks, and `$()` can never
+	* chain extra commands past the ops layer's allowlist; a command they
+	* appear unquoted in is refused with exit code 127. On Windows the argv
+	* runs through a `cmd.exe /d /s /c` wrapper (batch shims like `npm.cmd`
 	* cannot be spawned shell-less) with every element individually quoted.
+	* With `interpreter: "sh"` the line runs through `/bin/sh -c` (or
+	* `cmd.exe /d /v:off /s /c` on Windows) — only after the ops layer has
+	* checked every command in it.
 	* `cwd`, `env`, and the timeout are taken verbatim from the ops layer
 	* (the environment is NOT merged with `process.env`). On timeout the
 	* process tree is SIGKILLed and `timedOut` is set. When `signal` aborts
@@ -199,31 +282,17 @@ var LocalBackend = class {
 				});
 				return;
 			}
-			const argv = tokenizeCommand(command);
-			const executable = argv?.[0];
-			if (argv === null || executable === void 0) {
-				refuse("Command was not executed: it is empty, has unbalanced quotes, or contains unquoted shell metacharacters (;, &, |, `, $, <, >, parentheses). Commands run without a shell — pass metacharacters inside quotes as literal arguments, or run one command at a time.");
+			const plan = planSpawn(command, opts.interpreter ?? "none");
+			if ("refused" in plan) {
+				refuse(plan.refused);
 				return;
 			}
-			let file = executable;
-			let args = argv.slice(1);
-			let windowsVerbatimArguments = false;
-			if (platform === "win32") {
-				const invocation = toWin32CmdInvocation(argv);
-				if (invocation === null) {
-					refuse("Command was not executed: on Windows, arguments containing \", %, or newlines cannot be passed to cmd.exe safely.");
-					return;
-				}
-				file = invocation.file;
-				args = invocation.args;
-				windowsVerbatimArguments = true;
-			}
-			const child = spawn(file, args, {
+			const child = spawn(plan.file, plan.args, {
 				cwd: opts.cwd,
 				env: opts.env,
 				shell: false,
 				windowsHide: true,
-				windowsVerbatimArguments,
+				windowsVerbatimArguments: plan.windowsVerbatimArguments,
 				detached: platform !== "win32"
 			});
 			const stdoutChunks = [];
@@ -279,6 +348,75 @@ var LocalBackend = class {
 			});
 		});
 	}
+	/**
+	* Start a long-running command and return at once. Spawned like
+	* {@link exec} (same argv/shell planning, own process group on POSIX), with
+	* stdin closed. Output is decoded per stream with a `StringDecoder`, so a
+	* chunk never ends inside a character. `kill()` kills the whole tree; a
+	* still-running tree is also killed when the Node process exits.
+	*/
+	start(command, opts) {
+		const plan = planSpawn(command, opts.interpreter ?? "none");
+		if ("refused" in plan) {
+			opts.onOutput("stderr", plan.refused);
+			return {
+				done: Promise.resolve({ exitCode: 127 }),
+				kill: () => {}
+			};
+		}
+		const child = spawn(plan.file, plan.args, {
+			cwd: opts.cwd,
+			env: opts.env,
+			shell: false,
+			windowsHide: true,
+			windowsVerbatimArguments: plan.windowsVerbatimArguments,
+			detached: platform !== "win32",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		const stdoutDecoder = new StringDecoder("utf8");
+		const stderrDecoder = new StringDecoder("utf8");
+		let finished = false;
+		const kill = () => {
+			if (!finished) killTree(child.pid, child);
+		};
+		const untrack = trackBackgroundProcess(kill);
+		child.stdout?.on("data", (chunk) => {
+			const text = stdoutDecoder.write(chunk);
+			if (text !== "") opts.onOutput("stdout", text);
+		});
+		child.stderr?.on("data", (chunk) => {
+			const text = stderrDecoder.write(chunk);
+			if (text !== "") opts.onOutput("stderr", text);
+		});
+		const done = new Promise((resolve) => {
+			const finish = (exitCode) => {
+				if (finished) return;
+				finished = true;
+				untrack();
+				const stdoutTail = stdoutDecoder.end();
+				const stderrTail = stderrDecoder.end();
+				if (stdoutTail !== "") opts.onOutput("stdout", stdoutTail);
+				if (stderrTail !== "") opts.onOutput("stderr", stderrTail);
+				resolve({ exitCode });
+			};
+			child.on("error", (error) => {
+				opts.onOutput("stderr", `Command could not be started: ${error.message}`);
+				finish(127);
+			});
+			child.on("close", (code, signal) => {
+				finish(code === null ? 128 + (signal === "SIGKILL" ? 9 : 1) : code);
+			});
+		});
+		return {
+			...child.pid !== void 0 ? { pid: child.pid } : {},
+			done,
+			kill
+		};
+	}
 };
 /**
 * Create the **local** workspace backend — the default executor that runs the

package/esm/backends/local.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"local.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/backends/local.ts"],"sourcesContent":["import { spawn } from \"node:child_process\";\nimport { realpath } from \"node:fs/promises\";\nimport { platform } from \"node:process\";\nimport { fs } from \"@warlock.js/fs\";\nimport { tokenizeCommand } from \"../policy/tokenize-command\";\nimport type {\n  WorkspaceBackend,\n  WorkspaceBackendExecOptions,\n  WorkspaceBackendExecResult,\n} from \"../contracts/workspace-backend.contract\";\n\n/**\n * Hard ceiling on captured `stdout`/`stderr` per stream, in bytes. The raw\n * executor truncates each stream once this many bytes have accumulated so a\n * runaway command cannot exhaust memory; the ops layer applies its own\n * policy-driven cap (and the `truncated` flag) on top. Generous enough that\n * ordinary command output is never clipped here.\n */\nconst MAX_STREAM_BYTES = 10 * 1024 * 1024;\n\n/**\n * Append a chunk to a capped list of buffers, tracking the running byte\n * total and stopping once {@link MAX_STREAM_BYTES} is reached. Trailing bytes\n * past the cap are dropped rather than buffered.\n */\nfunction pushCapped(chunks: Buffer[], total: number, chunk: Buffer): number {\n  if (total >= MAX_STREAM_BYTES) {\n    return total;\n  }\n\n  const remaining = MAX_STREAM_BYTES - total;\n\n  if (chunk.length <= remaining) {\n    chunks.push(chunk);\n\n    return total + chunk.length;\n  }\n\n  chunks.push(chunk.subarray(0, remaining));\n\n  return MAX_STREAM_BYTES;\n}\n\n/**\n * Force-kill a spawned command and its entire process tree.\n *\n * The direct child may have grandchildren (on Windows it is the `cmd.exe`\n * wrapper around a batch shim; anywhere, an allowed `npm`/`node` can spawn\n * further processes), so signalling the direct child alone could leave a\n * long-running grandchild alive and the `exec` promise unsettled. We\n * therefore kill the whole group:\n *   - **Windows** — `taskkill /T /F` walks and terminates the PID's tree.\n *   - **POSIX** — the child is spawned `detached`, becoming its own process\n *     group leader, so `process.kill(-pid)` SIGKILLs the group.\n */\nfunction killTree(pid: number | undefined, child: { kill(signal: NodeJS.Signals): boolean }): void {\n  if (pid === undefined) {\n    child.kill(\"SIGKILL\");\n\n    return;\n  }\n\n  if (platform === \"win32\") {\n    const killer = spawn(\"taskkill\", [\"/pid\", String(pid), \"/T\", \"/F\"], { windowsHide: true });\n\n    // Without a listener a failed spawn (taskkill missing from PATH) is an\n    // unhandled 'error' event that crashes the process; fall back to the\n    // direct child instead.\n    killer.on(\"error\", () => {\n      child.kill(\"SIGKILL\");\n    });\n\n    return;\n  }\n\n  try {\n    process.kill(-pid, \"SIGKILL\");\n  } catch {\n    // The group may already be gone; fall back to the direct child.\n    child.kill(\"SIGKILL\");\n  }\n}\n\n/**\n * Argument bytes `cmd.exe` cannot carry safely even inside double quotes:\n * an embedded quote breaks out of the quoted span, `%` triggers variable\n * expansion regardless of quoting, and newlines end the command line. An\n * argv containing any of these is refused rather than risked (the\n * BatBadBut / CVE-2024-24576 class of `cmd.exe` argument smuggling).\n */\nconst WIN32_UNSAFE_ARGUMENT = /[\"%\\r\\n]/;\n\n/**\n * Build the `cmd.exe` invocation that runs an argv on Windows. Batch shims\n * (`npm.cmd`, `npx.cmd`, …) cannot be spawned directly without a shell\n * (Node rejects them since CVE-2024-27980), so the argv is run through\n * `cmd.exe /d /s /c` with every element individually double-quoted —\n * quoted spans are literal to cmd's parser, so pipes/ampersands inside an\n * argument stay argument data. Returns `null` when an element contains a\n * byte cmd cannot quote safely (see {@link WIN32_UNSAFE_ARGUMENT}).\n *\n * The caller must spawn with `windowsVerbatimArguments: true` so Node does\n * not re-quote the already-quoted command line.\n */\nfunction toWin32CmdInvocation(\n  argv: string[],\n): { file: string; args: string[] } | null {\n  if (argv.some((element) => WIN32_UNSAFE_ARGUMENT.test(element))) {\n    return null;\n  }\n\n  const commandLine = argv.map((element) => `\"${element}\"`).join(\" \");\n\n  return {\n    file: process.env.ComSpec ?? \"cmd.exe\",\n    args: [\"/d\", \"/s\", \"/c\", `\"${commandLine}\"`],\n  };\n}\n\n/**\n * The real-disk executor: every filesystem method delegates to\n * `@warlock.js/fs` (never `node:fs`), and {@link LocalBackend.exec} spawns a\n * process via `node:child_process`. It is deliberately **policy-agnostic** —\n * it receives already-resolved absolute paths and an already-resolved\n * environment + timeout from the ops layer, and just performs the side\n * effect. See {@link WorkspaceBackend} for the contract this implements.\n *\n * Constructed via {@link createLocalBackend}; the class itself is internal.\n */\nclass LocalBackend implements WorkspaceBackend {\n  /** Read a file's full UTF-8 content at an absolute path. */\n  public async readFile(absPath: string): Promise<string> {\n    return fs.files.get(absPath);\n  }\n\n  /**\n   * Write full content to an absolute path. Uses `atomicWriteAsync`, so a\n   * concurrent reader never observes a half-written file, and missing parent\n   * directories are created.\n   */\n  public async writeFile(absPath: string, content: string): Promise<void> {\n    await fs.files.put(absPath, content, { atomic: true });\n  }\n\n  /** Whether anything (file or directory) exists at an absolute path. */\n  public async exists(absPath: string): Promise<boolean> {\n    return fs.exists(absPath);\n  }\n\n  /** Create a directory (and any missing parents) at an absolute path; idempotent. */\n  public async mkdir(absPath: string): Promise<void> {\n    await fs.dirs.ensure(absPath);\n  }\n\n  /**\n   * Remove a file or directory tree at an absolute path. Stats the target to\n   * pick the right op — `fs.dirs.remove` (recursive) for a directory,\n   * `fs.files.remove` for anything else. A path that does not exist is a no-op\n   * (the stat's ENOENT short-circuits, and both removes swallow `ENOENT`).\n   */\n  public async remove(absPath: string): Promise<void> {\n    let isDirectory = false;\n\n    try {\n      isDirectory = (await fs.files.stats(absPath)).type === \"directory\";\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException)?.code === \"ENOENT\") {\n        return;\n      }\n\n      throw error;\n    }\n\n    if (isDirectory) {\n      await fs.dirs.remove(absPath);\n\n      return;\n    }\n\n    await fs.files.remove(absPath);\n  }\n\n  /** List immediate children of an absolute directory as absolute paths. */\n  public async list(absDir: string): Promise<string[]> {\n    return fs.dirs.list(absDir);\n  }\n\n  /**\n   * Resolve symlinks and `..` segments to a canonical absolute path — the\n   * primitive the ops-layer jail uses to detect escapes. Delegates to\n   * `node:fs/promises` `realpath`, the one filesystem operation `@warlock.js/fs`\n   * does not expose.\n   */\n  public async realpath(absPath: string): Promise<string> {\n    return realpath(absPath);\n  }\n\n  /**\n   * Run a command and capture its outcome. The command line is tokenized\n   * into an argv (quotes respected, NO shell semantics — see\n   * `tokenizeCommand`) and spawned **without a shell**, so metacharacters\n   * like `;`, `&&`, `|`, backticks, and `$()` can never chain extra\n   * commands past the ops layer's allowlist; a command they appear\n   * unquoted in is refused with exit code 127. On Windows the argv runs\n   * through a `cmd.exe /d /s /c` wrapper (batch shims like `npm.cmd`\n   * cannot be spawned shell-less) with every element individually quoted.\n   * `cwd`, `env`, and the timeout are taken verbatim from the ops layer\n   * (the environment is NOT merged with `process.env`). On timeout the\n   * process tree is SIGKILLed and `timedOut` is set. When `signal` aborts\n   * mid-run the process tree is SIGKILLed the same way and `cancelled` is\n   * set; an already-aborted `signal` resolves `cancelled` without spawning.\n   * `stdout`/`stderr` are captured and byte-capped per {@link MAX_STREAM_BYTES}.\n   *\n   * Never rejects for a non-zero exit, a missing executable, a refused\n   * command line, a timeout or a cancellation — those are reported through the resolved\n   * {@link WorkspaceBackendExecResult} so the ops layer can surface them\n   * as tool-error data.\n   */\n  public exec(\n    command: string,\n    opts: WorkspaceBackendExecOptions = {},\n  ): Promise<WorkspaceBackendExecResult> {\n    return new Promise<WorkspaceBackendExecResult>((resolve) => {\n      const refuse = (stderr: string): void =>\n        resolve({ exitCode: 127, stdout: \"\", stderr, timedOut: false });\n\n      const signal = opts.signal;\n\n      // Never spawn for an invocation that was cancelled before it started.\n      if (signal?.aborted) {\n        resolve({\n          exitCode: 130,\n          stdout: \"\",\n          stderr: \"Command was not executed: the invocation was cancelled before it started.\",\n          timedOut: false,\n          cancelled: true,\n        });\n\n        return;\n      }\n\n      const argv = tokenizeCommand(command);\n      const executable = argv?.[0];\n\n      if (argv === null || executable === undefined) {\n        refuse(\n          \"Command was not executed: it is empty, has unbalanced quotes, or \" +\n            \"contains unquoted shell metacharacters (;, &, |, `, $, <, >, \" +\n            \"parentheses). Commands run without a shell — pass metacharacters \" +\n            \"inside quotes as literal arguments, or run one command at a time.\",\n        );\n\n        return;\n      }\n\n      let file = executable;\n      let args = argv.slice(1);\n      let windowsVerbatimArguments = false;\n\n      if (platform === \"win32\") {\n        const invocation = toWin32CmdInvocation(argv);\n\n        if (invocation === null) {\n          refuse(\n            'Command was not executed: on Windows, arguments containing \", %, ' +\n              \"or newlines cannot be passed to cmd.exe safely.\",\n          );\n\n          return;\n        }\n\n        file = invocation.file;\n        args = invocation.args;\n        windowsVerbatimArguments = true;\n      }\n\n      const child = spawn(file, args, {\n        cwd: opts.cwd,\n        env: opts.env,\n        shell: false,\n        windowsHide: true,\n        windowsVerbatimArguments,\n        // POSIX: own process group so a timeout SIGKILL reaps the whole\n        // process tree, not just the direct child. Harmless on Windows\n        // (ignored; there we tree-kill via taskkill instead).\n        detached: platform !== \"win32\",\n      });\n\n      const stdoutChunks: Buffer[] = [];\n      const stderrChunks: Buffer[] = [];\n      let stdoutBytes = 0;\n      let stderrBytes = 0;\n      let timedOut = false;\n      let cancelled = false;\n      let settled = false;\n      // The direct child has exited; 'close' may still be pending while its\n      // stdio drains (or a grandchild holds the pipes open).\n      let exited = false;\n\n      // Timeout and cancellation are mutually exclusive: whichever kills the\n      // tree first owns the outcome, so a result is never both.\n      const timer =\n        opts.timeoutMs !== undefined && opts.timeoutMs > 0\n          ? setTimeout(() => {\n              if (cancelled) {\n                return;\n              }\n\n              timedOut = true;\n              killTree(child.pid, child);\n            }, opts.timeoutMs)\n          : undefined;\n\n      const onAbort = (): void => {\n        if (settled || timedOut) {\n          return;\n        }\n\n        // The command already finished: report its real outcome, not a\n        // cancellation. Still reap the tree so a grandchild holding the\n        // pipes open cannot keep `close` (and this promise) pending.\n        if (!exited) {\n          cancelled = true;\n        }\n\n        killTree(child.pid, child);\n      };\n\n      // Attached synchronously after `spawn`, so there is no window in which\n      // an abort could be missed; removed in `settle` so a long-lived signal\n      // shared across many commands does not accumulate listeners.\n      signal?.addEventListener(\"abort\", onAbort, { once: true });\n\n      const settle = (exitCode: number) => {\n        if (settled) {\n          return;\n        }\n\n        settled = true;\n\n        if (timer !== undefined) {\n          clearTimeout(timer);\n        }\n\n        signal?.removeEventListener(\"abort\", onAbort);\n\n        resolve({\n          exitCode,\n          stdout: Buffer.concat(stdoutChunks).toString(\"utf8\"),\n          stderr: Buffer.concat(stderrChunks).toString(\"utf8\"),\n          timedOut,\n          cancelled,\n        });\n      };\n\n      child.stdout?.on(\"data\", (chunk: Buffer) => {\n        stdoutBytes = pushCapped(stdoutChunks, stdoutBytes, chunk);\n      });\n\n      child.stderr?.on(\"data\", (chunk: Buffer) => {\n        stderrBytes = pushCapped(stderrChunks, stderrBytes, chunk);\n      });\n\n      // A spawn failure (e.g. the executable cannot be found) surfaces as\n      // an error event with no exit; report it as a conventional\n      // \"command not found\" exit code rather than rejecting.\n      child.on(\"error\", () => {\n        settle(127);\n      });\n\n      child.on(\"exit\", () => {\n        exited = true;\n      });\n\n      child.on(\"close\", (code, signal) => {\n        // A null code means the process was terminated by a signal (our\n        // timeout SIGKILL, or an external kill). Map that to the POSIX\n        // 128 + signal-number convention so callers see a non-zero exit.\n        if (code === null) {\n          const signalNumber = signal === \"SIGKILL\" ? 9 : 1;\n          settle(128 + signalNumber);\n\n          return;\n        }\n\n        settle(code);\n      });\n    });\n  }\n}\n\n/**\n * Create the **local** workspace backend — the default executor that runs the\n * workspace over the real disk (`@warlock.js/fs`) and the local shell\n * (`node:child_process`).\n *\n * The returned object is policy-agnostic: it expects already-jail-resolved\n * absolute paths and an already-resolved environment/timeout from the ops\n * layer. Pair it with {@link WorkspaceOps} for the actual cwd jail,\n * allow/deny lists, hashing, and output policy.\n *\n * @example\n * const backend = createLocalBackend();\n * await backend.writeFile(\"/srv/app/src/index.ts\", \"export const x = 1;\");\n * const { exitCode } = await backend.exec(\"node -v\", { cwd: \"/srv/app\" });\n */\nexport function createLocalBackend(): WorkspaceBackend {\n  return new LocalBackend();\n}\n"],"mappings":"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"}
+{"version":3,"file":"local.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/backends/local.ts"],"sourcesContent":["import { spawn } from \"node:child_process\";\nimport { lstat, realpath } from \"node:fs/promises\";\nimport { platform } from \"node:process\";\nimport { StringDecoder } from \"node:string_decoder\";\nimport { fs } from \"@warlock.js/fs\";\nimport { tokenizeCommand } from \"../policy/tokenize-command\";\nimport type { WorkspaceShellInterpreter } from \"../contracts/workspace-policy.type\";\nimport type {\n  WorkspaceBackend,\n  WorkspaceBackendExecOptions,\n  WorkspaceBackendExecResult,\n  WorkspaceBackendProcess,\n  WorkspaceBackendStartOptions,\n  WorkspaceBackendStat,\n} from \"../contracts/workspace-backend.contract\";\n\n/**\n * Hard ceiling on captured `stdout`/`stderr` per stream, in bytes. The raw\n * executor truncates each stream once this many bytes have accumulated so a\n * runaway command cannot exhaust memory; the ops layer applies its own\n * policy-driven cap (and the `truncated` flag) on top. Generous enough that\n * ordinary command output is never clipped here.\n */\nconst MAX_STREAM_BYTES = 10 * 1024 * 1024;\n\n/**\n * Append a chunk to a capped list of buffers, tracking the running byte\n * total and stopping once {@link MAX_STREAM_BYTES} is reached. Trailing bytes\n * past the cap are dropped rather than buffered.\n */\nfunction pushCapped(chunks: Buffer[], total: number, chunk: Buffer): number {\n  if (total >= MAX_STREAM_BYTES) {\n    return total;\n  }\n\n  const remaining = MAX_STREAM_BYTES - total;\n\n  if (chunk.length <= remaining) {\n    chunks.push(chunk);\n\n    return total + chunk.length;\n  }\n\n  chunks.push(chunk.subarray(0, remaining));\n\n  return MAX_STREAM_BYTES;\n}\n\n/**\n * Force-kill a spawned command and its entire process tree.\n *\n * The direct child may have grandchildren (on Windows it is the `cmd.exe`\n * wrapper around a batch shim; anywhere, an allowed `npm`/`node` can spawn\n * further processes), so signalling the direct child alone could leave a\n * long-running grandchild alive and the `exec` promise unsettled. We\n * therefore kill the whole group:\n *   - **Windows** — `taskkill /T /F` walks and terminates the PID's tree.\n *   - **POSIX** — the child is spawned `detached`, becoming its own process\n *     group leader, so `process.kill(-pid)` SIGKILLs the group.\n */\nfunction killTree(pid: number | undefined, child: { kill(signal: NodeJS.Signals): boolean }): void {\n  if (pid === undefined) {\n    child.kill(\"SIGKILL\");\n\n    return;\n  }\n\n  if (platform === \"win32\") {\n    const killer = spawn(\"taskkill\", [\"/pid\", String(pid), \"/T\", \"/F\"], { windowsHide: true });\n\n    // Without a listener a failed spawn (taskkill missing from PATH) is an\n    // unhandled 'error' event that crashes the process; fall back to the\n    // direct child instead.\n    killer.on(\"error\", () => {\n      child.kill(\"SIGKILL\");\n    });\n\n    return;\n  }\n\n  try {\n    process.kill(-pid, \"SIGKILL\");\n  } catch {\n    // The group may already be gone; fall back to the direct child.\n    child.kill(\"SIGKILL\");\n  }\n}\n\n/**\n * Argument bytes `cmd.exe` cannot carry safely even inside double quotes:\n * an embedded quote breaks out of the quoted span, `%` triggers variable\n * expansion regardless of quoting, and newlines end the command line. An\n * argv containing any of these is refused rather than risked (the\n * BatBadBut / CVE-2024-24576 class of `cmd.exe` argument smuggling).\n */\nconst WIN32_UNSAFE_ARGUMENT = /[\"%\\r\\n]/;\n\n/**\n * Build the `cmd.exe` invocation that runs an argv on Windows. Batch shims\n * (`npm.cmd`, `npx.cmd`, …) cannot be spawned directly without a shell\n * (Node rejects them since CVE-2024-27980), so the argv is run through\n * `cmd.exe /d /s /c` with every element individually double-quoted —\n * quoted spans are literal to cmd's parser, so pipes/ampersands inside an\n * argument stay argument data. Returns `null` when an element contains a\n * byte cmd cannot quote safely (see {@link WIN32_UNSAFE_ARGUMENT}).\n *\n * The caller must spawn with `windowsVerbatimArguments: true` so Node does\n * not re-quote the already-quoted command line.\n */\nfunction toWin32CmdInvocation(argv: string[]): { file: string; args: string[] } | null {\n  if (argv.some((element) => WIN32_UNSAFE_ARGUMENT.test(element))) {\n    return null;\n  }\n\n  const commandLine = argv.map((element) => `\"${element}\"`).join(\" \");\n\n  return {\n    file: process.env.ComSpec ?? \"cmd.exe\",\n    args: [\"/d\", \"/s\", \"/c\", `\"${commandLine}\"`],\n  };\n}\n\n/** The shell a POSIX shell-mode line runs through — an absolute path, never a PATH lookup. */\nconst POSIX_SHELL = \"/bin/sh\";\n\n/** How to spawn a command line, or why it cannot be spawned. */\ntype SpawnPlan =\n  | { file: string; args: string[]; windowsVerbatimArguments: boolean }\n  | { refused: string };\n\n/**\n * Work out the spawn for a command line.\n *\n * - argv mode: tokenize (no shell semantics) and spawn the argv directly —\n *   on Windows through an individually-quoted `cmd.exe` wrapper.\n * - shell mode: `/bin/sh -c <line>`, or `cmd.exe /d /v:off /s /c \"<line>\"`\n *   on Windows (`/d` skips AutoRun, `/v:off` disables delayed `!` expansion,\n *   `/s` keeps the line verbatim inside the outer quotes). The ops layer has\n *   already checked every command in the line.\n */\nfunction planSpawn(command: string, interpreter: WorkspaceShellInterpreter): SpawnPlan {\n  if (interpreter === \"sh\") {\n    if (platform === \"win32\") {\n      return {\n        file: process.env.ComSpec ?? \"cmd.exe\",\n        args: [\"/d\", \"/v:off\", \"/s\", \"/c\", `\"${command}\"`],\n        windowsVerbatimArguments: true,\n      };\n    }\n\n    return { file: POSIX_SHELL, args: [\"-c\", command], windowsVerbatimArguments: false };\n  }\n\n  const argv = tokenizeCommand(command);\n  const executable = argv?.[0];\n\n  if (argv === null || executable === undefined) {\n    return {\n      refused:\n        \"Command was not executed: it is empty, has unbalanced quotes, or \" +\n        \"contains unquoted shell metacharacters (;, &, |, `, $, <, >, \" +\n        \"parentheses). Commands run without a shell — pass metacharacters \" +\n        \"inside quotes as literal arguments, or run one command at a time.\",\n    };\n  }\n\n  if (platform === \"win32\") {\n    const invocation = toWin32CmdInvocation(argv);\n\n    if (invocation === null) {\n      return {\n        refused:\n          'Command was not executed: on Windows, arguments containing \", %, ' +\n          \"or newlines cannot be passed to cmd.exe safely.\",\n      };\n    }\n\n    return { ...invocation, windowsVerbatimArguments: true };\n  }\n\n  return { file: executable, args: argv.slice(1), windowsVerbatimArguments: false };\n}\n\n/**\n * Kill functions of every background process still running, so they can\n * be reaped if the Node process exits without the workspace being disposed\n * (detached process groups would otherwise outlive it).\n */\nconst liveBackgroundKills = new Set<() => void>();\n\nlet exitHookInstalled = false;\n\n/** Track a live background tree; installs (once) the exit hook that kills them. */\nfunction trackBackgroundProcess(kill: () => void): () => void {\n  liveBackgroundKills.add(kill);\n\n  if (!exitHookInstalled) {\n    exitHookInstalled = true;\n    process.on(\"exit\", () => {\n      for (const killTreeNow of liveBackgroundKills) {\n        killTreeNow();\n      }\n    });\n  }\n\n  return () => {\n    liveBackgroundKills.delete(kill);\n  };\n}\n\n/**\n * The real-disk executor: every filesystem method delegates to\n * `@warlock.js/fs` (never `node:fs`), and {@link LocalBackend.exec} spawns a\n * process via `node:child_process`. It is deliberately **policy-agnostic** —\n * it receives already-resolved absolute paths and an already-resolved\n * environment + timeout from the ops layer, and just performs the side\n * effect. See {@link WorkspaceBackend} for the contract this implements.\n *\n * Constructed via {@link createLocalBackend}; the class itself is internal.\n */\nclass LocalBackend implements WorkspaceBackend {\n  /** Read a file's full UTF-8 content at an absolute path. */\n  public async readFile(absPath: string): Promise<string> {\n    return fs.files.get(absPath);\n  }\n\n  /**\n   * Write full content to an absolute path. Uses `atomicWriteAsync`, so a\n   * concurrent reader never observes a half-written file, and missing parent\n   * directories are created.\n   */\n  public async writeFile(absPath: string, content: string): Promise<void> {\n    await fs.files.put(absPath, content, { atomic: true });\n  }\n\n  /** Whether anything (file or directory) exists at an absolute path. */\n  public async exists(absPath: string): Promise<boolean> {\n    return fs.exists(absPath);\n  }\n\n  /** Create a directory (and any missing parents) at an absolute path; idempotent. */\n  public async mkdir(absPath: string): Promise<void> {\n    await fs.dirs.ensure(absPath);\n  }\n\n  /**\n   * Remove a file or directory tree at an absolute path. Stats the target to\n   * pick the right op — `fs.dirs.remove` (recursive) for a directory,\n   * `fs.files.remove` for anything else. A path that does not exist is a no-op\n   * (the stat's ENOENT short-circuits, and both removes swallow `ENOENT`).\n   */\n  public async remove(absPath: string): Promise<void> {\n    let isDirectory = false;\n\n    try {\n      isDirectory = (await fs.files.stats(absPath)).type === \"directory\";\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException)?.code === \"ENOENT\") {\n        return;\n      }\n\n      throw error;\n    }\n\n    if (isDirectory) {\n      await fs.dirs.remove(absPath);\n\n      return;\n    }\n\n    await fs.files.remove(absPath);\n  }\n\n  /** List immediate children of an absolute directory as absolute paths. */\n  public async list(absDir: string): Promise<string[]> {\n    return fs.dirs.list(absDir);\n  }\n\n  /**\n   * Describe a path without following a final symlink (`lstat` — like\n   * `realpath`, a filesystem operation `@warlock.js/fs` does not expose).\n   */\n  public async stat(absPath: string): Promise<WorkspaceBackendStat> {\n    const stats = await lstat(absPath);\n    const type = stats.isSymbolicLink()\n      ? \"symlink\"\n      : stats.isDirectory()\n        ? \"directory\"\n        : stats.isFile()\n          ? \"file\"\n          : \"other\";\n\n    return { type, size: stats.size };\n  }\n\n  /**\n   * Resolve symlinks and `..` segments to a canonical absolute path — the\n   * primitive the ops-layer jail uses to detect escapes. Delegates to\n   * `node:fs/promises` `realpath`, the one filesystem operation `@warlock.js/fs`\n   * does not expose.\n   */\n  public async realpath(absPath: string): Promise<string> {\n    return realpath(absPath);\n  }\n\n  /**\n   * Run a command and capture its outcome. In argv mode (the default) the\n   * command line is tokenized into an argv (quotes respected, NO shell\n   * semantics — see `tokenizeCommand`) and spawned **without a shell**, so\n   * metacharacters like `;`, `&&`, `|`, backticks, and `$()` can never\n   * chain extra commands past the ops layer's allowlist; a command they\n   * appear unquoted in is refused with exit code 127. On Windows the argv\n   * runs through a `cmd.exe /d /s /c` wrapper (batch shims like `npm.cmd`\n   * cannot be spawned shell-less) with every element individually quoted.\n   * With `interpreter: \"sh\"` the line runs through `/bin/sh -c` (or\n   * `cmd.exe /d /v:off /s /c` on Windows) — only after the ops layer has\n   * checked every command in it.\n   * `cwd`, `env`, and the timeout are taken verbatim from the ops layer\n   * (the environment is NOT merged with `process.env`). On timeout the\n   * process tree is SIGKILLed and `timedOut` is set. When `signal` aborts\n   * mid-run the process tree is SIGKILLed the same way and `cancelled` is\n   * set; an already-aborted `signal` resolves `cancelled` without spawning.\n   * `stdout`/`stderr` are captured and byte-capped per {@link MAX_STREAM_BYTES}.\n   *\n   * Never rejects for a non-zero exit, a missing executable, a refused\n   * command line, a timeout or a cancellation — those are reported through the resolved\n   * {@link WorkspaceBackendExecResult} so the ops layer can surface them\n   * as tool-error data.\n   */\n  public exec(\n    command: string,\n    opts: WorkspaceBackendExecOptions = {},\n  ): Promise<WorkspaceBackendExecResult> {\n    return new Promise<WorkspaceBackendExecResult>((resolve) => {\n      const refuse = (stderr: string): void =>\n        resolve({ exitCode: 127, stdout: \"\", stderr, timedOut: false });\n\n      const signal = opts.signal;\n\n      // Never spawn for an invocation that was cancelled before it started.\n      if (signal?.aborted) {\n        resolve({\n          exitCode: 130,\n          stdout: \"\",\n          stderr: \"Command was not executed: the invocation was cancelled before it started.\",\n          timedOut: false,\n          cancelled: true,\n        });\n\n        return;\n      }\n\n      const plan = planSpawn(command, opts.interpreter ?? \"none\");\n\n      if (\"refused\" in plan) {\n        refuse(plan.refused);\n\n        return;\n      }\n\n      const child = spawn(plan.file, plan.args, {\n        cwd: opts.cwd,\n        env: opts.env,\n        shell: false,\n        windowsHide: true,\n        windowsVerbatimArguments: plan.windowsVerbatimArguments,\n        // POSIX: own process group so a timeout SIGKILL reaps the whole\n        // process tree, not just the direct child. Harmless on Windows\n        // (ignored; there we tree-kill via taskkill instead).\n        detached: platform !== \"win32\",\n      });\n\n      const stdoutChunks: Buffer[] = [];\n      const stderrChunks: Buffer[] = [];\n      let stdoutBytes = 0;\n      let stderrBytes = 0;\n      let timedOut = false;\n      let cancelled = false;\n      let settled = false;\n      // The direct child has exited; 'close' may still be pending while its\n      // stdio drains (or a grandchild holds the pipes open).\n      let exited = false;\n\n      // Timeout and cancellation are mutually exclusive: whichever kills the\n      // tree first owns the outcome, so a result is never both.\n      const timer =\n        opts.timeoutMs !== undefined && opts.timeoutMs > 0\n          ? setTimeout(() => {\n              if (cancelled) {\n                return;\n              }\n\n              timedOut = true;\n              killTree(child.pid, child);\n            }, opts.timeoutMs)\n          : undefined;\n\n      const onAbort = (): void => {\n        if (settled || timedOut) {\n          return;\n        }\n\n        // The command already finished: report its real outcome, not a\n        // cancellation. Still reap the tree so a grandchild holding the\n        // pipes open cannot keep `close` (and this promise) pending.\n        if (!exited) {\n          cancelled = true;\n        }\n\n        killTree(child.pid, child);\n      };\n\n      // Attached synchronously after `spawn`, so there is no window in which\n      // an abort could be missed; removed in `settle` so a long-lived signal\n      // shared across many commands does not accumulate listeners.\n      signal?.addEventListener(\"abort\", onAbort, { once: true });\n\n      const settle = (exitCode: number) => {\n        if (settled) {\n          return;\n        }\n\n        settled = true;\n\n        if (timer !== undefined) {\n          clearTimeout(timer);\n        }\n\n        signal?.removeEventListener(\"abort\", onAbort);\n\n        resolve({\n          exitCode,\n          stdout: Buffer.concat(stdoutChunks).toString(\"utf8\"),\n          stderr: Buffer.concat(stderrChunks).toString(\"utf8\"),\n          timedOut,\n          cancelled,\n        });\n      };\n\n      child.stdout?.on(\"data\", (chunk: Buffer) => {\n        stdoutBytes = pushCapped(stdoutChunks, stdoutBytes, chunk);\n      });\n\n      child.stderr?.on(\"data\", (chunk: Buffer) => {\n        stderrBytes = pushCapped(stderrChunks, stderrBytes, chunk);\n      });\n\n      // A spawn failure (e.g. the executable cannot be found) surfaces as\n      // an error event with no exit; report it as a conventional\n      // \"command not found\" exit code rather than rejecting.\n      child.on(\"error\", () => {\n        settle(127);\n      });\n\n      child.on(\"exit\", () => {\n        exited = true;\n      });\n\n      child.on(\"close\", (code, signal) => {\n        // A null code means the process was terminated by a signal (our\n        // timeout SIGKILL, or an external kill). Map that to the POSIX\n        // 128 + signal-number convention so callers see a non-zero exit.\n        if (code === null) {\n          const signalNumber = signal === \"SIGKILL\" ? 9 : 1;\n          settle(128 + signalNumber);\n\n          return;\n        }\n\n        settle(code);\n      });\n    });\n  }\n\n  /**\n   * Start a long-running command and return at once. Spawned like\n   * {@link exec} (same argv/shell planning, own process group on POSIX), with\n   * stdin closed. Output is decoded per stream with a `StringDecoder`, so a\n   * chunk never ends inside a character. `kill()` kills the whole tree; a\n   * still-running tree is also killed when the Node process exits.\n   */\n  public start(command: string, opts: WorkspaceBackendStartOptions): WorkspaceBackendProcess {\n    const plan = planSpawn(command, opts.interpreter ?? \"none\");\n\n    if (\"refused\" in plan) {\n      opts.onOutput(\"stderr\", plan.refused);\n\n      return { done: Promise.resolve({ exitCode: 127 }), kill: () => {} };\n    }\n\n    const child = spawn(plan.file, plan.args, {\n      cwd: opts.cwd,\n      env: opts.env,\n      shell: false,\n      windowsHide: true,\n      windowsVerbatimArguments: plan.windowsVerbatimArguments,\n      detached: platform !== \"win32\",\n      stdio: [\"ignore\", \"pipe\", \"pipe\"],\n    });\n\n    const stdoutDecoder = new StringDecoder(\"utf8\");\n    const stderrDecoder = new StringDecoder(\"utf8\");\n    let finished = false;\n\n    const kill = (): void => {\n      if (!finished) {\n        killTree(child.pid, child);\n      }\n    };\n\n    const untrack = trackBackgroundProcess(kill);\n\n    child.stdout?.on(\"data\", (chunk: Buffer) => {\n      const text = stdoutDecoder.write(chunk);\n\n      if (text !== \"\") {\n        opts.onOutput(\"stdout\", text);\n      }\n    });\n\n    child.stderr?.on(\"data\", (chunk: Buffer) => {\n      const text = stderrDecoder.write(chunk);\n\n      if (text !== \"\") {\n        opts.onOutput(\"stderr\", text);\n      }\n    });\n\n    const done = new Promise<{ exitCode: number }>((resolve) => {\n      const finish = (exitCode: number): void => {\n        if (finished) {\n          return;\n        }\n\n        finished = true;\n        untrack();\n\n        const stdoutTail = stdoutDecoder.end();\n        const stderrTail = stderrDecoder.end();\n\n        if (stdoutTail !== \"\") {\n          opts.onOutput(\"stdout\", stdoutTail);\n        }\n\n        if (stderrTail !== \"\") {\n          opts.onOutput(\"stderr\", stderrTail);\n        }\n\n        resolve({ exitCode });\n      };\n\n      child.on(\"error\", (error) => {\n        opts.onOutput(\"stderr\", `Command could not be started: ${error.message}`);\n        finish(127);\n      });\n\n      child.on(\"close\", (code, signal) => {\n        finish(code === null ? 128 + (signal === \"SIGKILL\" ? 9 : 1) : code);\n      });\n    });\n\n    return { ...(child.pid !== undefined ? { pid: child.pid } : {}), done, kill };\n  }\n}\n\n/**\n * Create the **local** workspace backend — the default executor that runs the\n * workspace over the real disk (`@warlock.js/fs`) and the local shell\n * (`node:child_process`).\n *\n * The returned object is policy-agnostic: it expects already-jail-resolved\n * absolute paths and an already-resolved environment/timeout from the ops\n * layer. Pair it with {@link WorkspaceOps} for the actual cwd jail,\n * allow/deny lists, hashing, and output policy.\n *\n * @example\n * const backend = createLocalBackend();\n * await backend.writeFile(\"/srv/app/src/index.ts\", \"export const x = 1;\");\n * const { exitCode } = await backend.exec(\"node -v\", { cwd: \"/srv/app\" });\n */\nexport function createLocalBackend(): WorkspaceBackend {\n  return new LocalBackend();\n}\n"],"mappings":";;;;;;;;;;;;;;;AAuBA,MAAM,mBAAmB,KAAK,OAAO;;;;;;AAOrC,SAAS,WAAW,QAAkB,OAAe,OAAuB;CAC1E,IAAI,SAAS,kBACX,OAAO;CAGT,MAAM,YAAY,mBAAmB;CAErC,IAAI,MAAM,UAAU,WAAW;EAC7B,OAAO,KAAK,KAAK;EAEjB,OAAO,QAAQ,MAAM;CACvB;CAEA,OAAO,KAAK,MAAM,SAAS,GAAG,SAAS,CAAC;CAExC,OAAO;AACT;;;;;;;;;;;;;AAcA,SAAS,SAAS,KAAyB,OAAwD;CACjG,IAAI,QAAQ,QAAW;EACrB,MAAM,KAAK,SAAS;EAEpB;CACF;CAEA,IAAI,aAAa,SAAS;EAMxB,AALe,MAAM,YAAY;GAAC;GAAQ,OAAO,GAAG;GAAG;GAAM;EAAI,GAAG,EAAE,aAAa,KAAK,CAKnF,CAAC,CAAC,GAAG,eAAe;GACvB,MAAM,KAAK,SAAS;EACtB,CAAC;EAED;CACF;CAEA,IAAI;EACF,QAAQ,KAAK,CAAC,KAAK,SAAS;CAC9B,QAAQ;EAEN,MAAM,KAAK,SAAS;CACtB;AACF;;;;;;;;AASA,MAAM,wBAAwB;;;;;;;;;;;;;AAc9B,SAAS,qBAAqB,MAAyD;CACrF,IAAI,KAAK,MAAM,YAAY,sBAAsB,KAAK,OAAO,CAAC,GAC5D,OAAO;CAGT,MAAM,cAAc,KAAK,KAAK,YAAY,IAAI,QAAQ,EAAE,CAAC,CAAC,KAAK,GAAG;CAElE,OAAO;EACL,MAAM,QAAQ,IAAI,WAAW;EAC7B,MAAM;GAAC;GAAM;GAAM;GAAM,IAAI,YAAY;EAAE;CAC7C;AACF;;AAGA,MAAM,cAAc;;;;;;;;;;;AAiBpB,SAAS,UAAU,SAAiB,aAAmD;CACrF,IAAI,gBAAgB,MAAM;EACxB,IAAI,aAAa,SACf,OAAO;GACL,MAAM,QAAQ,IAAI,WAAW;GAC7B,MAAM;IAAC;IAAM;IAAU;IAAM;IAAM,IAAI,QAAQ;GAAE;GACjD,0BAA0B;EAC5B;EAGF,OAAO;GAAE,MAAM;GAAa,MAAM,CAAC,MAAM,OAAO;GAAG,0BAA0B;EAAM;CACrF;CAEA,MAAM,OAAO,gBAAgB,OAAO;CACpC,MAAM,aAAa,OAAO;CAE1B,IAAI,SAAS,QAAQ,eAAe,QAClC,OAAO,EACL,SACE,mQAIJ;CAGF,IAAI,aAAa,SAAS;EACxB,MAAM,aAAa,qBAAqB,IAAI;EAE5C,IAAI,eAAe,MACjB,OAAO,EACL,SACE,oHAEJ;EAGF,OAAO;GAAE,GAAG;GAAY,0BAA0B;EAAK;CACzD;CAEA,OAAO;EAAE,MAAM;EAAY,MAAM,KAAK,MAAM,CAAC;EAAG,0BAA0B;CAAM;AAClF;;;;;;AAOA,MAAM,sCAAsB,IAAI,IAAgB;AAEhD,IAAI,oBAAoB;;AAGxB,SAAS,uBAAuB,MAA8B;CAC5D,oBAAoB,IAAI,IAAI;CAE5B,IAAI,CAAC,mBAAmB;EACtB,oBAAoB;EACpB,QAAQ,GAAG,cAAc;GACvB,KAAK,MAAM,eAAe,qBACxB,YAAY;EAEhB,CAAC;CACH;CAEA,aAAa;EACX,oBAAoB,OAAO,IAAI;CACjC;AACF;;;;;;;;;;;AAYA,IAAM,eAAN,MAA+C;;CAE7C,MAAa,SAAS,SAAkC;EACtD,OAAO,GAAG,MAAM,IAAI,OAAO;CAC7B;;;;;;CAOA,MAAa,UAAU,SAAiB,SAAgC;EACtE,MAAM,GAAG,MAAM,IAAI,SAAS,SAAS,EAAE,QAAQ,KAAK,CAAC;CACvD;;CAGA,MAAa,OAAO,SAAmC;EACrD,OAAO,GAAG,OAAO,OAAO;CAC1B;;CAGA,MAAa,MAAM,SAAgC;EACjD,MAAM,GAAG,KAAK,OAAO,OAAO;CAC9B;;;;;;;CAQA,MAAa,OAAO,SAAgC;EAClD,IAAI,cAAc;EAElB,IAAI;GACF,eAAe,MAAM,GAAG,MAAM,MAAM,OAAO,EAAC,CAAE,SAAS;EACzD,SAAS,OAAO;GACd,IAAK,OAAiC,SAAS,UAC7C;GAGF,MAAM;EACR;EAEA,IAAI,aAAa;GACf,MAAM,GAAG,KAAK,OAAO,OAAO;GAE5B;EACF;EAEA,MAAM,GAAG,MAAM,OAAO,OAAO;CAC/B;;CAGA,MAAa,KAAK,QAAmC;EACnD,OAAO,GAAG,KAAK,KAAK,MAAM;CAC5B;;;;;CAMA,MAAa,KAAK,SAAgD;EAChE,MAAM,QAAQ,MAAM,MAAM,OAAO;EASjC,OAAO;GAAE,MARI,MAAM,eAAe,IAC9B,YACA,MAAM,YAAY,IAChB,cACA,MAAM,OAAO,IACX,SACA;GAEO,MAAM,MAAM;EAAK;CAClC;;;;;;;CAQA,MAAa,SAAS,SAAkC;EACtD,OAAO,SAAS,OAAO;CACzB;;;;;;;;;;;;;;;;;;;;;;;;;CA0BA,AAAO,KACL,SACA,OAAoC,CAAC,GACA;EACrC,OAAO,IAAI,SAAqC,YAAY;GAC1D,MAAM,UAAU,WACd,QAAQ;IAAE,UAAU;IAAK,QAAQ;IAAI;IAAQ,UAAU;GAAM,CAAC;GAEhE,MAAM,SAAS,KAAK;GAGpB,IAAI,QAAQ,SAAS;IACnB,QAAQ;KACN,UAAU;KACV,QAAQ;KACR,QAAQ;KACR,UAAU;KACV,WAAW;IACb,CAAC;IAED;GACF;GAEA,MAAM,OAAO,UAAU,SAAS,KAAK,eAAe,MAAM;GAE1D,IAAI,aAAa,MAAM;IACrB,OAAO,KAAK,OAAO;IAEnB;GACF;GAEA,MAAM,QAAQ,MAAM,KAAK,MAAM,KAAK,MAAM;IACxC,KAAK,KAAK;IACV,KAAK,KAAK;IACV,OAAO;IACP,aAAa;IACb,0BAA0B,KAAK;IAI/B,UAAU,aAAa;GACzB,CAAC;GAED,MAAM,eAAyB,CAAC;GAChC,MAAM,eAAyB,CAAC;GAChC,IAAI,cAAc;GAClB,IAAI,cAAc;GAClB,IAAI,WAAW;GACf,IAAI,YAAY;GAChB,IAAI,UAAU;GAGd,IAAI,SAAS;GAIb,MAAM,QACJ,KAAK,cAAc,UAAa,KAAK,YAAY,IAC7C,iBAAiB;IACf,IAAI,WACF;IAGF,WAAW;IACX,SAAS,MAAM,KAAK,KAAK;GAC3B,GAAG,KAAK,SAAS,IACjB;GAEN,MAAM,gBAAsB;IAC1B,IAAI,WAAW,UACb;IAMF,IAAI,CAAC,QACH,YAAY;IAGd,SAAS,MAAM,KAAK,KAAK;GAC3B;GAKA,QAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;GAEzD,MAAM,UAAU,aAAqB;IACnC,IAAI,SACF;IAGF,UAAU;IAEV,IAAI,UAAU,QACZ,aAAa,KAAK;IAGpB,QAAQ,oBAAoB,SAAS,OAAO;IAE5C,QAAQ;KACN;KACA,QAAQ,OAAO,OAAO,YAAY,CAAC,CAAC,SAAS,MAAM;KACnD,QAAQ,OAAO,OAAO,YAAY,CAAC,CAAC,SAAS,MAAM;KACnD;KACA;IACF,CAAC;GACH;GAEA,MAAM,QAAQ,GAAG,SAAS,UAAkB;IAC1C,cAAc,WAAW,cAAc,aAAa,KAAK;GAC3D,CAAC;GAED,MAAM,QAAQ,GAAG,SAAS,UAAkB;IAC1C,cAAc,WAAW,cAAc,aAAa,KAAK;GAC3D,CAAC;GAKD,MAAM,GAAG,eAAe;IACtB,OAAO,GAAG;GACZ,CAAC;GAED,MAAM,GAAG,cAAc;IACrB,SAAS;GACX,CAAC;GAED,MAAM,GAAG,UAAU,MAAM,WAAW;IAIlC,IAAI,SAAS,MAAM;KAEjB,OAAO,OADc,WAAW,YAAY,IAAI,EACvB;KAEzB;IACF;IAEA,OAAO,IAAI;GACb,CAAC;EACH,CAAC;CACH;;;;;;;;CASA,AAAO,MAAM,SAAiB,MAA6D;EACzF,MAAM,OAAO,UAAU,SAAS,KAAK,eAAe,MAAM;EAE1D,IAAI,aAAa,MAAM;GACrB,KAAK,SAAS,UAAU,KAAK,OAAO;GAEpC,OAAO;IAAE,MAAM,QAAQ,QAAQ,EAAE,UAAU,IAAI,CAAC;IAAG,YAAY,CAAC;GAAE;EACpE;EAEA,MAAM,QAAQ,MAAM,KAAK,MAAM,KAAK,MAAM;GACxC,KAAK,KAAK;GACV,KAAK,KAAK;GACV,OAAO;GACP,aAAa;GACb,0BAA0B,KAAK;GAC/B,UAAU,aAAa;GACvB,OAAO;IAAC;IAAU;IAAQ;GAAM;EAClC,CAAC;EAED,MAAM,gBAAgB,IAAI,cAAc,MAAM;EAC9C,MAAM,gBAAgB,IAAI,cAAc,MAAM;EAC9C,IAAI,WAAW;EAEf,MAAM,aAAmB;GACvB,IAAI,CAAC,UACH,SAAS,MAAM,KAAK,KAAK;EAE7B;EAEA,MAAM,UAAU,uBAAuB,IAAI;EAE3C,MAAM,QAAQ,GAAG,SAAS,UAAkB;GAC1C,MAAM,OAAO,cAAc,MAAM,KAAK;GAEtC,IAAI,SAAS,IACX,KAAK,SAAS,UAAU,IAAI;EAEhC,CAAC;EAED,MAAM,QAAQ,GAAG,SAAS,UAAkB;GAC1C,MAAM,OAAO,cAAc,MAAM,KAAK;GAEtC,IAAI,SAAS,IACX,KAAK,SAAS,UAAU,IAAI;EAEhC,CAAC;EAED,MAAM,OAAO,IAAI,SAA+B,YAAY;GAC1D,MAAM,UAAU,aAA2B;IACzC,IAAI,UACF;IAGF,WAAW;IACX,QAAQ;IAER,MAAM,aAAa,cAAc,IAAI;IACrC,MAAM,aAAa,cAAc,IAAI;IAErC,IAAI,eAAe,IACjB,KAAK,SAAS,UAAU,UAAU;IAGpC,IAAI,eAAe,IACjB,KAAK,SAAS,UAAU,UAAU;IAGpC,QAAQ,EAAE,SAAS,CAAC;GACtB;GAEA,MAAM,GAAG,UAAU,UAAU;IAC3B,KAAK,SAAS,UAAU,iCAAiC,MAAM,SAAS;IACxE,OAAO,GAAG;GACZ,CAAC;GAED,MAAM,GAAG,UAAU,MAAM,WAAW;IAClC,OAAO,SAAS,OAAO,OAAO,WAAW,YAAY,IAAI,KAAK,IAAI;GACpE,CAAC;EACH,CAAC;EAED,OAAO;GAAE,GAAI,MAAM,QAAQ,SAAY,EAAE,KAAK,MAAM,IAAI,IAAI,CAAC;GAAI;GAAM;EAAK;CAC9E;AACF;;;;;;;;;;;;;;;;AAiBA,SAAgB,qBAAuC;CACrD,OAAO,IAAI,aAAa;AAC1B"}

package/esm/backends/mock.d.mts

@@ -2,12 +2,18 @@ import { WorkspaceBackend, WorkspaceBackendExecResult } from "../contracts/works
 
 //#region ../../packages/ai-workspace/src/backends/mock.d.ts
 /**
- * A scripted outcome for the mock backend's `exec`. Mirrors
- * {@link WorkspaceBackendExecResult} but every field is optional so a
- * registration can specify only what it cares about — the rest fall back
- * to a successful, empty-output, non-timed-out run.
+ * A scripted outcome for the mock backend's `exec` (and background
+ * `start`). Mirrors {@link WorkspaceBackendExecResult} but every field is
+ * optional so a registration can specify only what it cares about — the
+ * rest fall back to a successful, empty-output, non-timed-out run.
+ *
+ * `running: true` makes a background start keep "running" (after emitting
+ * its scripted output) until it is killed, like a dev server; otherwise it
+ * exits at once with `exitCode`.
  */
-type MockExecResult = Partial<WorkspaceBackendExecResult>;
+type MockExecResult = Partial<WorkspaceBackendExecResult> & {
+  /** Background starts only: stay running until killed. */running?: boolean;
+};
 /**
  * The two seedable inputs of a mock backend:
  *

package/esm/backends/mock.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"mock.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/backends/mock.ts"],"mappings":";;;;;AAYA;;;;KAAY,cAAA,GAAiB,OAAO,CAAC,0BAAA;AAUrC;;;;;;;;AAAA,UAAiB,eAAA;EAEP;EAAR,KAAA,GAAQ,MAAA;EAEG;EAAX,QAAA,GAAW,MAAA,SAAe,cAAA;AAAA;AAAc;AA2O1C;;;;;;;;;;;;;AAEmB;;;;;;;;;;;;;;;;;;;;AA7OuB,iBA2O1B,iBAAA,CACd,IAAA,GAAO,MAAA,mBAAyB,eAAA,GAC/B,gBAAA"}
+{"version":3,"file":"mock.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/backends/mock.ts"],"mappings":";;;;;AAmBA;;;;;;;;KAAY,cAAA,GAAiB,OAAO,CAAC,0BAAA;EAapB,yDAXf,OAAA;AAAA;;;;;;;;;UAWe,eAAA;EAIW;EAF1B,KAAA,GAAQ,MAAA;EAEgC;EAAxC,QAAA,GAAW,MAAA,SAAe,cAAA;AAAA;;;;;;;;;;;;AAuRT;;;;;;;;;;;;;;;;;;;;;;;iBAFH,iBAAA,CACd,IAAA,GAAO,MAAA,mBAAyB,eAAA,GAC/B,gBAAA"}

package/esm/backends/mock.mjs

@@ -98,6 +98,40 @@ var MockBackend = class {
 	async realpath(absPath) {
 		return canonicalize(absPath);
 	}
+	async stat(absPath) {
+		const canonical = canonicalize(absPath);
+		const content = this.files.get(canonical);
+		if (content !== void 0) return {
+			type: "file",
+			size: Buffer.byteLength(content, "utf8")
+		};
+		if (this.directories.has(canonical)) return {
+			type: "directory",
+			size: 0
+		};
+		throw new Error(`Mock backend: no such file or directory: ${canonical}`);
+	}
+	/**
+	* Scripted background start: emits the registered `stdout` / `stderr`
+	* synchronously, then exits with `exitCode` — or, when scripted with
+	* `running: true`, stays running until `kill()` (exit code 137).
+	*/
+	start(command, opts) {
+		const scripted = this.commands.get(command);
+		if (scripted?.stdout) opts.onOutput("stdout", scripted.stdout);
+		if (scripted?.stderr) opts.onOutput("stderr", scripted.stderr);
+		if (scripted?.running !== true) return {
+			done: Promise.resolve({ exitCode: scripted?.exitCode ?? 0 }),
+			kill: () => {}
+		};
+		let stop = () => {};
+		return {
+			done: new Promise((resolve) => {
+				stop = resolve;
+			}),
+			kill: () => stop({ exitCode: 137 })
+		};
+	}
 	async exec(command, opts) {
 		if (opts?.signal?.aborted) return {
 			exitCode: 130,

package/esm/backends/mock.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mock.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/backends/mock.ts"],"sourcesContent":["import type {\n  WorkspaceBackend,\n  WorkspaceBackendExecOptions,\n  WorkspaceBackendExecResult,\n} from \"../contracts/workspace-backend.contract\";\n\n/**\n * A scripted outcome for the mock backend's `exec`. Mirrors\n * {@link WorkspaceBackendExecResult} but every field is optional so a\n * registration can specify only what it cares about — the rest fall back\n * to a successful, empty-output, non-timed-out run.\n */\nexport type MockExecResult = Partial<WorkspaceBackendExecResult>;\n\n/**\n * The two seedable inputs of a mock backend:\n *\n * - `files` — initial file tree as `absolutePath -> content`. Parent\n *   directories of each seeded file are implicitly created.\n * - `commands` — scripted `exec` outcomes keyed on the **exact** command\n *   line. Any command not registered here resolves to a `0`-exit no-op.\n */\nexport interface MockBackendSeed {\n  /** Initial file contents, keyed by absolute path. */\n  files?: Record<string, string>;\n  /** Scripted `exec` results, keyed by exact command line. */\n  commands?: Record<string, MockExecResult>;\n}\n\n/**\n * Normalize an absolute path to a stable in-memory key: forward slashes,\n * collapsed duplicate separators, and resolved `.` / `..` segments. There\n * are no symlinks in memory, so this is a pure lexical canonicalization —\n * exactly what the backend's `realpath` promises.\n */\nfunction canonicalize(absPath: string): string {\n  const unified = absPath.replace(/\\\\/g, \"/\");\n  // Preserve a leading slash (POSIX root) or a `C:`-style Windows drive\n  // prefix; everything else is a normal segment.\n  const driveMatch = unified.match(/^([a-zA-Z]:)?\\/?/);\n  const prefix = driveMatch ? driveMatch[0] : \"\";\n  const rest = unified.slice(prefix.length);\n\n  const resolved: string[] = [];\n\n  for (const segment of rest.split(\"/\")) {\n    if (segment === \"\" || segment === \".\") {\n      continue;\n    }\n\n    if (segment === \"..\") {\n      resolved.pop();\n\n      continue;\n    }\n\n    resolved.push(segment);\n  }\n\n  const joined = resolved.join(\"/\");\n\n  // A trailing slash on the prefix means it was absolute; keep it so the\n  // result stays absolute even when the body is empty (the root itself).\n  const normalizedPrefix = prefix.endsWith(\"/\") ? prefix : `${prefix}/`;\n\n  return joined.length > 0 ? `${normalizedPrefix}${joined}` : normalizedPrefix;\n}\n\n/** All ancestor directory keys of a canonical path, root-first. */\nfunction ancestorsOf(canonicalPath: string): string[] {\n  const lastSlash = canonicalPath.lastIndexOf(\"/\");\n\n  if (lastSlash <= 0) {\n    return [];\n  }\n\n  const parent = canonicalPath.slice(0, lastSlash);\n  const result = ancestorsOf(parent);\n\n  result.push(parent);\n\n  return result;\n}\n\n/**\n * The in-memory executor behind {@link createMockBackend}. Holds the file\n * tree in a `Map`, the directory set in a `Set`, and the scripted command\n * table in a second `Map` — no disk, no child processes, fully\n * deterministic. Construct it via the factory, never directly.\n */\nclass MockBackend implements WorkspaceBackend {\n  /** Canonical file path -> content. */\n  private readonly files = new Map<string, string>();\n\n  /** Canonical directory paths that exist (including implicit parents). */\n  private readonly directories = new Set<string>();\n\n  /** Exact command line -> scripted outcome. */\n  private readonly commands = new Map<string, MockExecResult>();\n\n  public constructor(seed?: MockBackendSeed) {\n    for (const [path, content] of Object.entries(seed?.files ?? {})) {\n      const canonical = canonicalize(path);\n\n      this.files.set(canonical, content);\n      this.registerAncestorDirectories(canonical);\n    }\n\n    for (const [command, result] of Object.entries(seed?.commands ?? {})) {\n      this.commands.set(command, result);\n    }\n  }\n\n  /** Record every ancestor directory of a path as existing. */\n  private registerAncestorDirectories(canonicalPath: string): void {\n    for (const ancestor of ancestorsOf(canonicalPath)) {\n      this.directories.add(ancestor);\n    }\n  }\n\n  public async readFile(absPath: string): Promise<string> {\n    const canonical = canonicalize(absPath);\n    const content = this.files.get(canonical);\n\n    if (content === undefined) {\n      throw new Error(`Mock backend: no such file: ${canonical}`);\n    }\n\n    return content;\n  }\n\n  public async writeFile(absPath: string, content: string): Promise<void> {\n    const canonical = canonicalize(absPath);\n\n    this.files.set(canonical, content);\n    this.registerAncestorDirectories(canonical);\n  }\n\n  public async exists(absPath: string): Promise<boolean> {\n    const canonical = canonicalize(absPath);\n\n    return this.files.has(canonical) || this.directories.has(canonical);\n  }\n\n  public async mkdir(absPath: string): Promise<void> {\n    const canonical = canonicalize(absPath);\n\n    this.directories.add(canonical);\n    this.registerAncestorDirectories(canonical);\n  }\n\n  public async remove(absPath: string): Promise<void> {\n    const canonical = canonicalize(absPath);\n    const prefix = `${canonical}/`;\n\n    // Drop the entry itself and any descendant files/directories — a\n    // recursive tree removal, matching the contract's \"file or directory\n    // tree\" wording.\n    for (const file of [...this.files.keys()]) {\n      if (file === canonical || file.startsWith(prefix)) {\n        this.files.delete(file);\n      }\n    }\n\n    for (const directory of [...this.directories]) {\n      if (directory === canonical || directory.startsWith(prefix)) {\n        this.directories.delete(directory);\n      }\n    }\n  }\n\n  public async list(absDir: string): Promise<string[]> {\n    const canonical = canonicalize(absDir);\n    const prefix = canonical === \"/\" ? \"/\" : `${canonical}/`;\n    const children = new Set<string>();\n\n    const collect = (key: string): void => {\n      if (!key.startsWith(prefix) || key === canonical) {\n        return;\n      }\n\n      const remainder = key.slice(prefix.length);\n      const nextSlash = remainder.indexOf(\"/\");\n      const childName =\n        nextSlash === -1 ? remainder : remainder.slice(0, nextSlash);\n\n      if (childName.length > 0) {\n        children.add(`${prefix}${childName}`);\n      }\n    };\n\n    for (const file of this.files.keys()) {\n      collect(file);\n    }\n\n    for (const directory of this.directories) {\n      collect(directory);\n    }\n\n    return [...children].sort();\n  }\n\n  public async realpath(absPath: string): Promise<string> {\n    return canonicalize(absPath);\n  }\n\n  public async exec(\n    command: string,\n    opts?: WorkspaceBackendExecOptions,\n  ): Promise<WorkspaceBackendExecResult> {\n    // Honour the contract's pre-aborted rule: nothing \"runs\".\n    if (opts?.signal?.aborted) {\n      return { exitCode: 130, stdout: \"\", stderr: \"\", timedOut: false, cancelled: true };\n    }\n\n    const scripted = this.commands.get(command);\n\n    return {\n      exitCode: scripted?.exitCode ?? 0,\n      stdout: scripted?.stdout ?? \"\",\n      stderr: scripted?.stderr ?? \"\",\n      timedOut: scripted?.timedOut ?? false,\n      cancelled: scripted?.cancelled ?? false,\n    };\n  }\n}\n\n/**\n * Create an in-memory {@link WorkspaceBackend} for fast, disk-free tests.\n *\n * Every IO method operates on a `Map` of `absolutePath -> content` (with a\n * companion directory set), so reads, writes, existence checks, `mkdir`,\n * recursive `remove`, `list`, and `realpath` all run synchronously in\n * memory with no filesystem access. `exec` is **scripted**: a registered\n * `command -> result` table is consulted by exact command line, and any\n * unregistered command resolves to a successful `0`-exit no-op with empty\n * output.\n *\n * `realpath` is a pure lexical canonicalization (forward slashes,\n * collapsed separators, resolved `.`/`..`) — there are no symlinks in\n * memory — which is exactly what the jail resolver expects.\n *\n * The single positional `seed` accepts either the shorthand\n * `Record<string, string>` of file contents (matching the design's\n * `ai.workspace.mock(seed)` signature) or the richer {@link MockBackendSeed}\n * with both `files` and scripted `commands`.\n *\n * @example\n * // Shorthand: seed files only.\n * const backend = createMockBackend({ \"/srv/app/src/index.ts\": \"export const x = 1;\" });\n * await backend.readFile(\"/srv/app/src/index.ts\"); // \"export const x = 1;\"\n *\n * @example\n * // Full seed: files plus a scripted command.\n * const backend = createMockBackend({\n *   files: { \"/srv/app/package.json\": \"{}\" },\n *   commands: { \"npm test\": { exitCode: 1, stderr: \"1 failing\" } },\n * });\n * await backend.exec(\"npm test\");   // { exitCode: 1, stderr: \"1 failing\", ... }\n * await backend.exec(\"echo hi\");    // { exitCode: 0, stdout: \"\", ... } (no-op)\n */\nexport function createMockBackend(\n  seed?: Record<string, string> | MockBackendSeed,\n): WorkspaceBackend {\n  return new MockBackend(normalizeSeed(seed));\n}\n\n/** Coerce the dual-shaped `seed` argument into a {@link MockBackendSeed}. */\nfunction normalizeSeed(\n  seed?: Record<string, string> | MockBackendSeed,\n): MockBackendSeed | undefined {\n  if (seed === undefined) {\n    return undefined;\n  }\n\n  if (isMockBackendSeed(seed)) {\n    return seed;\n  }\n\n  return { files: seed };\n}\n\n/**\n * Whether `seed` is the structured {@link MockBackendSeed} (has a `files`\n * or `commands` key) rather than the flat `path -> content` shorthand. A\n * plain shorthand map whose only key happens to be named `files` is\n * treated as structured — callers wanting that literal path should use the\n * explicit `{ files: { files: \"...\" } }` form.\n */\nfunction isMockBackendSeed(\n  seed: Record<string, string> | MockBackendSeed,\n): seed is MockBackendSeed {\n  return (\n    typeof (seed as MockBackendSeed).files === \"object\" ||\n    typeof (seed as MockBackendSeed).commands === \"object\"\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"mock.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/backends/mock.ts"],"sourcesContent":["import type {\n  WorkspaceBackend,\n  WorkspaceBackendExecOptions,\n  WorkspaceBackendExecResult,\n  WorkspaceBackendProcess,\n  WorkspaceBackendStartOptions,\n  WorkspaceBackendStat,\n} from \"../contracts/workspace-backend.contract\";\n\n/**\n * A scripted outcome for the mock backend's `exec` (and background\n * `start`). Mirrors {@link WorkspaceBackendExecResult} but every field is\n * optional so a registration can specify only what it cares about — the\n * rest fall back to a successful, empty-output, non-timed-out run.\n *\n * `running: true` makes a background start keep \"running\" (after emitting\n * its scripted output) until it is killed, like a dev server; otherwise it\n * exits at once with `exitCode`.\n */\nexport type MockExecResult = Partial<WorkspaceBackendExecResult> & {\n  /** Background starts only: stay running until killed. */\n  running?: boolean;\n};\n\n/**\n * The two seedable inputs of a mock backend:\n *\n * - `files` — initial file tree as `absolutePath -> content`. Parent\n *   directories of each seeded file are implicitly created.\n * - `commands` — scripted `exec` outcomes keyed on the **exact** command\n *   line. Any command not registered here resolves to a `0`-exit no-op.\n */\nexport interface MockBackendSeed {\n  /** Initial file contents, keyed by absolute path. */\n  files?: Record<string, string>;\n  /** Scripted `exec` results, keyed by exact command line. */\n  commands?: Record<string, MockExecResult>;\n}\n\n/**\n * Normalize an absolute path to a stable in-memory key: forward slashes,\n * collapsed duplicate separators, and resolved `.` / `..` segments. There\n * are no symlinks in memory, so this is a pure lexical canonicalization —\n * exactly what the backend's `realpath` promises.\n */\nfunction canonicalize(absPath: string): string {\n  const unified = absPath.replace(/\\\\/g, \"/\");\n  // Preserve a leading slash (POSIX root) or a `C:`-style Windows drive\n  // prefix; everything else is a normal segment.\n  const driveMatch = unified.match(/^([a-zA-Z]:)?\\/?/);\n  const prefix = driveMatch ? driveMatch[0] : \"\";\n  const rest = unified.slice(prefix.length);\n\n  const resolved: string[] = [];\n\n  for (const segment of rest.split(\"/\")) {\n    if (segment === \"\" || segment === \".\") {\n      continue;\n    }\n\n    if (segment === \"..\") {\n      resolved.pop();\n\n      continue;\n    }\n\n    resolved.push(segment);\n  }\n\n  const joined = resolved.join(\"/\");\n\n  // A trailing slash on the prefix means it was absolute; keep it so the\n  // result stays absolute even when the body is empty (the root itself).\n  const normalizedPrefix = prefix.endsWith(\"/\") ? prefix : `${prefix}/`;\n\n  return joined.length > 0 ? `${normalizedPrefix}${joined}` : normalizedPrefix;\n}\n\n/** All ancestor directory keys of a canonical path, root-first. */\nfunction ancestorsOf(canonicalPath: string): string[] {\n  const lastSlash = canonicalPath.lastIndexOf(\"/\");\n\n  if (lastSlash <= 0) {\n    return [];\n  }\n\n  const parent = canonicalPath.slice(0, lastSlash);\n  const result = ancestorsOf(parent);\n\n  result.push(parent);\n\n  return result;\n}\n\n/**\n * The in-memory executor behind {@link createMockBackend}. Holds the file\n * tree in a `Map`, the directory set in a `Set`, and the scripted command\n * table in a second `Map` — no disk, no child processes, fully\n * deterministic. Construct it via the factory, never directly.\n */\nclass MockBackend implements WorkspaceBackend {\n  /** Canonical file path -> content. */\n  private readonly files = new Map<string, string>();\n\n  /** Canonical directory paths that exist (including implicit parents). */\n  private readonly directories = new Set<string>();\n\n  /** Exact command line -> scripted outcome. */\n  private readonly commands = new Map<string, MockExecResult>();\n\n  public constructor(seed?: MockBackendSeed) {\n    for (const [path, content] of Object.entries(seed?.files ?? {})) {\n      const canonical = canonicalize(path);\n\n      this.files.set(canonical, content);\n      this.registerAncestorDirectories(canonical);\n    }\n\n    for (const [command, result] of Object.entries(seed?.commands ?? {})) {\n      this.commands.set(command, result);\n    }\n  }\n\n  /** Record every ancestor directory of a path as existing. */\n  private registerAncestorDirectories(canonicalPath: string): void {\n    for (const ancestor of ancestorsOf(canonicalPath)) {\n      this.directories.add(ancestor);\n    }\n  }\n\n  public async readFile(absPath: string): Promise<string> {\n    const canonical = canonicalize(absPath);\n    const content = this.files.get(canonical);\n\n    if (content === undefined) {\n      throw new Error(`Mock backend: no such file: ${canonical}`);\n    }\n\n    return content;\n  }\n\n  public async writeFile(absPath: string, content: string): Promise<void> {\n    const canonical = canonicalize(absPath);\n\n    this.files.set(canonical, content);\n    this.registerAncestorDirectories(canonical);\n  }\n\n  public async exists(absPath: string): Promise<boolean> {\n    const canonical = canonicalize(absPath);\n\n    return this.files.has(canonical) || this.directories.has(canonical);\n  }\n\n  public async mkdir(absPath: string): Promise<void> {\n    const canonical = canonicalize(absPath);\n\n    this.directories.add(canonical);\n    this.registerAncestorDirectories(canonical);\n  }\n\n  public async remove(absPath: string): Promise<void> {\n    const canonical = canonicalize(absPath);\n    const prefix = `${canonical}/`;\n\n    // Drop the entry itself and any descendant files/directories — a\n    // recursive tree removal, matching the contract's \"file or directory\n    // tree\" wording.\n    for (const file of [...this.files.keys()]) {\n      if (file === canonical || file.startsWith(prefix)) {\n        this.files.delete(file);\n      }\n    }\n\n    for (const directory of [...this.directories]) {\n      if (directory === canonical || directory.startsWith(prefix)) {\n        this.directories.delete(directory);\n      }\n    }\n  }\n\n  public async list(absDir: string): Promise<string[]> {\n    const canonical = canonicalize(absDir);\n    const prefix = canonical === \"/\" ? \"/\" : `${canonical}/`;\n    const children = new Set<string>();\n\n    const collect = (key: string): void => {\n      if (!key.startsWith(prefix) || key === canonical) {\n        return;\n      }\n\n      const remainder = key.slice(prefix.length);\n      const nextSlash = remainder.indexOf(\"/\");\n      const childName = nextSlash === -1 ? remainder : remainder.slice(0, nextSlash);\n\n      if (childName.length > 0) {\n        children.add(`${prefix}${childName}`);\n      }\n    };\n\n    for (const file of this.files.keys()) {\n      collect(file);\n    }\n\n    for (const directory of this.directories) {\n      collect(directory);\n    }\n\n    return [...children].sort();\n  }\n\n  public async realpath(absPath: string): Promise<string> {\n    return canonicalize(absPath);\n  }\n\n  public async stat(absPath: string): Promise<WorkspaceBackendStat> {\n    const canonical = canonicalize(absPath);\n    const content = this.files.get(canonical);\n\n    if (content !== undefined) {\n      return { type: \"file\", size: Buffer.byteLength(content, \"utf8\") };\n    }\n\n    if (this.directories.has(canonical)) {\n      return { type: \"directory\", size: 0 };\n    }\n\n    throw new Error(`Mock backend: no such file or directory: ${canonical}`);\n  }\n\n  /**\n   * Scripted background start: emits the registered `stdout` / `stderr`\n   * synchronously, then exits with `exitCode` — or, when scripted with\n   * `running: true`, stays running until `kill()` (exit code 137).\n   */\n  public start(command: string, opts: WorkspaceBackendStartOptions): WorkspaceBackendProcess {\n    const scripted = this.commands.get(command);\n\n    if (scripted?.stdout) {\n      opts.onOutput(\"stdout\", scripted.stdout);\n    }\n\n    if (scripted?.stderr) {\n      opts.onOutput(\"stderr\", scripted.stderr);\n    }\n\n    if (scripted?.running !== true) {\n      return { done: Promise.resolve({ exitCode: scripted?.exitCode ?? 0 }), kill: () => {} };\n    }\n\n    let stop: (result: { exitCode: number }) => void = () => {};\n    const done = new Promise<{ exitCode: number }>((resolve) => {\n      stop = resolve;\n    });\n\n    return { done, kill: () => stop({ exitCode: 137 }) };\n  }\n\n  public async exec(\n    command: string,\n    opts?: WorkspaceBackendExecOptions,\n  ): Promise<WorkspaceBackendExecResult> {\n    // Honour the contract's pre-aborted rule: nothing \"runs\".\n    if (opts?.signal?.aborted) {\n      return { exitCode: 130, stdout: \"\", stderr: \"\", timedOut: false, cancelled: true };\n    }\n\n    const scripted = this.commands.get(command);\n\n    return {\n      exitCode: scripted?.exitCode ?? 0,\n      stdout: scripted?.stdout ?? \"\",\n      stderr: scripted?.stderr ?? \"\",\n      timedOut: scripted?.timedOut ?? false,\n      cancelled: scripted?.cancelled ?? false,\n    };\n  }\n}\n\n/**\n * Create an in-memory {@link WorkspaceBackend} for fast, disk-free tests.\n *\n * Every IO method operates on a `Map` of `absolutePath -> content` (with a\n * companion directory set), so reads, writes, existence checks, `mkdir`,\n * recursive `remove`, `list`, and `realpath` all run synchronously in\n * memory with no filesystem access. `exec` is **scripted**: a registered\n * `command -> result` table is consulted by exact command line, and any\n * unregistered command resolves to a successful `0`-exit no-op with empty\n * output.\n *\n * `realpath` is a pure lexical canonicalization (forward slashes,\n * collapsed separators, resolved `.`/`..`) — there are no symlinks in\n * memory — which is exactly what the jail resolver expects.\n *\n * The single positional `seed` accepts either the shorthand\n * `Record<string, string>` of file contents (matching the design's\n * `ai.workspace.mock(seed)` signature) or the richer {@link MockBackendSeed}\n * with both `files` and scripted `commands`.\n *\n * @example\n * // Shorthand: seed files only.\n * const backend = createMockBackend({ \"/srv/app/src/index.ts\": \"export const x = 1;\" });\n * await backend.readFile(\"/srv/app/src/index.ts\"); // \"export const x = 1;\"\n *\n * @example\n * // Full seed: files plus a scripted command.\n * const backend = createMockBackend({\n *   files: { \"/srv/app/package.json\": \"{}\" },\n *   commands: { \"npm test\": { exitCode: 1, stderr: \"1 failing\" } },\n * });\n * await backend.exec(\"npm test\");   // { exitCode: 1, stderr: \"1 failing\", ... }\n * await backend.exec(\"echo hi\");    // { exitCode: 0, stdout: \"\", ... } (no-op)\n */\nexport function createMockBackend(\n  seed?: Record<string, string> | MockBackendSeed,\n): WorkspaceBackend {\n  return new MockBackend(normalizeSeed(seed));\n}\n\n/** Coerce the dual-shaped `seed` argument into a {@link MockBackendSeed}. */\nfunction normalizeSeed(\n  seed?: Record<string, string> | MockBackendSeed,\n): MockBackendSeed | undefined {\n  if (seed === undefined) {\n    return undefined;\n  }\n\n  if (isMockBackendSeed(seed)) {\n    return seed;\n  }\n\n  return { files: seed };\n}\n\n/**\n * Whether `seed` is the structured {@link MockBackendSeed} (has a `files`\n * or `commands` key) rather than the flat `path -> content` shorthand. A\n * plain shorthand map whose only key happens to be named `files` is\n * treated as structured — callers wanting that literal path should use the\n * explicit `{ files: { files: \"...\" } }` form.\n */\nfunction isMockBackendSeed(\n  seed: Record<string, string> | MockBackendSeed,\n): seed is MockBackendSeed {\n  return (\n    typeof (seed as MockBackendSeed).files === \"object\" ||\n    typeof (seed as MockBackendSeed).commands === \"object\"\n  );\n}\n"],"mappings":"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"}

package/esm/contracts/index.d.mts

@@ -1,5 +1,5 @@
-import { EditFileInput, EditFileResult, ExecOptions, GlobInput, GlobResult, GrepInput, GrepMatch, GrepResult, ReadFileInput, ReadFileResult, RunShellInput, RunShellResult, RunTestsInput, WorkspaceToolName, WriteFileInput, WriteFileResult } from "./tool-io.type.mjs";
-import { WorkspaceBackend, WorkspaceBackendExecOptions, WorkspaceBackendExecResult } from "./workspace-backend.contract.mjs";
+import { EditFileInput, EditFileResult, ExecOptions, GlobInput, GlobResult, GrepInput, GrepMatch, GrepResult, ListDirEntry, ListDirEntryType, ListDirInput, ListDirOptions, ListDirResult, MultiEditInput, MultiEditOperation, MultiEditResult, ReadFileInput, ReadFileResult, RunShellBackgroundResult, RunShellInput, RunShellResult, RunTestsInput, ShellJobInfo, ShellJobStatus, ShellKillInput, ShellOutputInput, ShellOutputOptions, ShellOutputResult, StartShellOptions, TodoListResult, TodoWriteInput, WorkspaceTodo, WorkspaceTodoInput, WorkspaceTodoStatus, WorkspaceToolName, WriteFileInput, WriteFileResult } from "./tool-io.type.mjs";
+import { WorkspaceAllowCommand, WorkspaceBackendType, WorkspaceBackgroundPolicy, WorkspaceCommandCheckContext, WorkspaceCommandPattern, WorkspaceListPolicy, WorkspacePolicy, WorkspaceReadPolicy, WorkspaceShellInterpreter, WorkspaceShellPolicy } from "./workspace-policy.type.mjs";
+import { WorkspaceBackend, WorkspaceBackendExecOptions, WorkspaceBackendExecResult, WorkspaceBackendProcess, WorkspaceBackendStartOptions, WorkspaceBackendStat, WorkspaceOutputStream } from "./workspace-backend.contract.mjs";
 import { WorkspaceOps } from "./workspace-ops.contract.mjs";
-import { WorkspaceBackendType, WorkspacePolicy, WorkspaceReadPolicy, WorkspaceShellPolicy } from "./workspace-policy.type.mjs";
 import { Workspace, WorkspaceTools } from "./workspace.contract.mjs";