@runko/just-bash 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# @runko/just-bash
+
+`RunkoExec` 的全语法档实现：适配 [vercel-labs/just-bash](https://github.com/vercel-labs/just-bash)（Apache-2.0，纯 TS，专为 AI agent 场景设计），跑在任意 `RunkoFS` 之上——"模式 A 同源工作区"的另一种实证，语法面从 `@runko/mini-bash` 的六个只读命令升级到完整 `if`/`elif`/`for`/`while`/`until`/`case`/函数/`local`/变量与参数扩展/glob/管道/`&&`/`||`/重定向。定位：Claude 系模型高频产出的控制流脚本，mini-bash 的六命令撑不住时换这个档（一行代码：`exec: justBash(fs)` 换掉 `exec: miniBash(fs)`）。
+
+> **本包不随 `@runko/sdk` 一起装**（[core-sdk · 技术方案 §4.5b](../../docs/logic/engine/tech/core-sdk.md) "包关系"）：`just-bash` 自身依赖树含 sql.js / quickjs-emscripten 等 wasm 大件，强制打包进门面违背 sdk 轻量默认。需要全语法档的宿主显式 `pnpm add @runko/just-bash`；`@runko/mini-bash` 仍是零依赖极简档，随 `@runko/sdk` 一起装，定位是安全默认与测试/演示载体。真实命令执行的第三个选项是 `@runko/core` 的 `localExec`，或宿主自己的沙盒实现（见 [core-sdk · 技术方案 §4.5a](../../docs/logic/engine/tech/core-sdk.md)）。
+
+## 安装
+
+```sh
+pnpm add @runko/just-bash
+```
+
+（`@runko/core`、`just-bash` 作为本包的 `dependencies` 一并装入，不需要单独 `pnpm add just-bash`。）
+
+## 最小用例
+
+```ts
+import { justBash } from "@runko/just-bash";
+import { fromMemory } from "@runko/virtual-fs";   // 任何 RunkoFS 实现都行
+
+const fs = fromMemory({});
+const exec = justBash(fs);
+
+const result = await exec.exec({
+  command: 'for n in 1 2 3; do echo "line-$n"; done',
+  cwd: "/",
+  signal: new AbortController().signal,
+});
+console.log(result);   // { exitCode: 0, stdout: "line-1\nline-2\nline-3\n", stderr: "", durationMs: ... }
+```
+
+接进 session（同源工作区，`bash` 工具随 `exec` 注入自动出现；`fs`/`createSession`/`defineAgent` 仍从 `@runko/sdk` 拿，只有 `justBash` 本身来自本包）：
+
+```ts
+import { createSession, defineAgent, RunkoFS } from "@runko/sdk";
+import { justBash } from "@runko/just-bash";
+
+const fs = RunkoFS.fromMemory({});
+const session = createSession(defineAgent({ model: "anthropic/claude-sonnet-5" }), {
+  fs,
+  exec: justBash(fs),   // 同一个 fs：write_file 写的文件，bash 立即可见，反之亦然
+});
+```
+
+完整可跑示例见 [examples/08-just-bash.ts](../../examples/src/08-just-bash.ts)。
+
+## API 面
+
+本包公共 API 收紧到一个函数 + 它需要的选项/限额类型：
+
+| 导出 | 说明 |
+|---|---|
+| `justBash(fs: RunkoFS, opts?: JustBashOptions): RunkoExec` | 返回跑在 `fs` 上的全语法档解释器。`defaultApproval: "never"`（重定向写面落在同一个注入的 `RunkoFS`，与文件工具同沙盒）；`describe()` 声明全语法能力、无 symlink、无网络、输出非流式；`cwd` 在同一个 `justBash(fs)` 实例上跨 `exec()` 调用持久（同 `@runko/mini-bash` 语义） |
+| `JustBashOptions` | `{ limits?: ExecutionLimits }`——与默认收紧值逐字段合并，未指定的字段沿用默认值 |
+| `ExecutionLimits` | just-bash 的执行限额类型（`maxCommandCount`/`maxLoopIterations`/`maxOutputSize` 等，见下表） |
+
+`createFsAdapter`/`IFileSystem` 等适配细节不导出（同 `@runko/mini-bash` 的 `parse()`/`COMMANDS` 先例）。
+
+## 执行限额（默认值）
+
+出厂默认（`just-bash` 自己的默认值是为通用 CLI 场景设的，对"一次 agent 工具调用里跑的一段脚本"明显过宽，这里整体收紧一个数量级左右；全部字段都能被 `opts.limits` 逐个覆盖）：
+
+| 字段 | 默认值 | 字段 | 默认值 |
+|---|---|---|---|
+| `maxCommandCount` | 2000 | `maxLoopIterations` | 2000 |
+| `maxOutputSize` | 1MB（`1024 * 1024`） | `maxCallDepth` | 20 |
+| `maxAwkIterations` | 2000 | `maxSedIterations` | 2000 |
+| `maxJqIterations` | 2000 | `maxSqliteTimeoutMs` | 3000 |
+| `maxGlobOperations` | 5000 | `maxStringLength` | 2MB（`2 * 1024 * 1024`） |
+| `maxArrayElements` | 10,000 | `maxHeredocSize` | 1MB（`1024 * 1024`） |
+| `maxSubstitutionDepth` | 20 | `maxBraceExpansionResults` | 2000 |
+| `maxFileDescriptors` | 256 | `maxSourceDepth` | 20 |
+
+```ts
+justBash(fs, { limits: { maxCommandCount: 500 } });   // 只覆盖这一个字段，其余仍是上表默认值
+```
+
+## 支持的语法
+
+完整控制流：`if`/`elif`/`else`、`for`（list 形式与 C 式 `for ((i=0;i<n;i++))`）、`while`/`until`、`case`、函数（含 `local`）、变量/参数扩展、glob 展开、管道、`&&`/`||`、重定向（`>`/`>>`/`<`/`2>&1`）。命令集是 just-bash 内置的完整命令族（`cat`/`grep`/`sed`/`awk`/`find`/`sort`/`jq` 等数十个，详见 [just-bash 上游文档](https://github.com/vercel-labs/just-bash)），而非 mini-bash 那样的手写六命令子集。
+
+## 已知限制（docs/logic/engine/tech/core-sdk.md §4.5b，如实照抄，不发明）
+
+- **无 symlink**：`symlink`/`link`/`readlink` 始终抛不支持；`stat`/`lstat` 从不报告符号链接（与 v1 全线"无符号链接"立场一致）。
+- **无网络**：curl/wget 不注册（未接入 fetch/network 配置）。
+- **输出非流式**：just-bash 无增量回调，`onOutput` 每次 `exec()` 至多触发一次（脚本整体跑完后一次性回报 stdout/stderr），不是逐命令/逐行增量推送。
+- **`**` 递归 glob 在同一次 `exec()` 内看不到该次脚本前面命令新写的文件**：`IFileSystem.getAllPaths()` 是同步签名而 `RunkoFS.glob` 是异步的，适配器折中为"每次顶层 `exec()` 开始时刷新一次同步缓存"——脚本运行期间新写入的文件要下一次 `exec()` 调用才对 `**` 展开可见；单层 glob（如 `*.txt`）走 `readdir` 不受影响，同一脚本内实时可见。
+- **`cp`/`mv` 递归目录时空子目录不参与**：目录场景经 `glob` 枚举子树文件逐个搬运，继承"`RunkoFS.glob` 只报文件"的既有限制（§4.4），不额外物化空目录。
+- `chmod`/`utimes` 是 no-op 成功（脚本常见惯用法，硬失败徒增纠错轮次），不是真实生效的权限/时间戳变更。
+- `cwd` 的跨调用持久化由适配器自己维护（闭包变量 + 读回 `env.PWD`），不是 just-bash 引擎自带的免费特性——`Bash.exec()` 每次调用本身是无状态的。
+
+## 退出码与取消契约（同 `@runko/mini-bash`，docs/logic/engine/tech/core-sdk.md §4.5a"实现契约"）
+
+`exec()` 的全部失败路径以 resolve 的 `ExecResult`（非零 `exitCode` + stderr）返回，从不 reject：超时 124、abort 130；just-bash 自身抛出的非正常异常兜底为 `exitCode: 1`。中止/超时不采信 just-bash 自己返回的退出码（实测不稳定）——适配器用独立的 `raceAbort` 竞速，信号一响就立即以合成结果返回，不等底层调用真正落定。

package/dist/index.cjs

@@ -0,0 +1,372 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let just_bash = require("just-bash");
+//#region src/path.ts
+/**
+* 自包含的极简 POSIX 虚拟路径解析——与 `@runko/mini-bash` 的 `src/path.ts`
+* 同一份逻辑独立实现（不跨包依赖：src 侧只允许依赖 `@runko/core` + `just-bash`，
+* 见 P6-4 mini-bash 先例头注释）。`..` 越界静默 clamp 到根而非抛错——这一层
+* 不是安全边界（docs/tech/core-sdk.md §4.4："安全边界在 FS 不在工具"），真正的边界校验
+* 留给注入的 `RunkoFS` 实现自己那一层。
+*/
+/** 把任意输入（含 `.`、`..`、重复斜杠）规范化为以 `/` 开头的虚拟绝对路径。 */
+function normalizePath(input) {
+	const segments = input.split("/");
+	const stack = [];
+	for (const segment of segments) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			if (stack.length > 0) stack.pop();
+			continue;
+		}
+		stack.push(segment);
+	}
+	return `/${stack.join("/")}`;
+}
+/** 绝对路径直接规范化；相对路径先拼上 base 再规范化——与 `IFileSystem.resolvePath(base, path)` 签名同形。 */
+function resolvePath(base, input) {
+	if (input.startsWith("/")) return normalizePath(input);
+	return normalizePath(`${base}/${input}`);
+}
+/** 假定 path 已规范化。用于 `getAllPaths()` 从文件路径合成祖先目录集合（§4.5b）。 */
+function dirnameOf(path) {
+	if (path === "/") return "/";
+	const idx = path.lastIndexOf("/");
+	if (idx <= 0) return "/";
+	return path.slice(0, idx);
+}
+//#endregion
+//#region src/fs-adapter.ts
+const textDecoder = new TextDecoder();
+const textEncoder = new TextEncoder();
+const FILE_MODE = 420;
+const DIR_MODE = 493;
+/** reference 条目 stat 视为 file（降级表原文）。 */
+function toFsStat(stat) {
+	const isDirectory = stat.type === "dir";
+	return {
+		isFile: !isDirectory,
+		isDirectory,
+		isSymbolicLink: false,
+		mode: isDirectory ? DIR_MODE : FILE_MODE,
+		size: stat.size ?? 0,
+		mtime: new Date(stat.mtime ?? 0)
+	};
+}
+async function statImpl(fs, path) {
+	return toFsStat(await fs.stat(normalizePath(path)));
+}
+async function existsImpl(fs, path) {
+	try {
+		await fs.stat(normalizePath(path));
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** `${dir}/**` 形式的 glob 模式，匹配 dir 子树下的全部文件（不含 dir 自身）。 */
+function subtreeGlobPattern(dir) {
+	return dir === "/" ? "/**" : `${dir}/**`;
+}
+/** 把子树内某个文件的绝对路径，重定位到新的根 `destRoot` 下。 */
+function relocate(srcRoot, destRoot, filePath) {
+	const prefix = srcRoot === "/" ? "/" : `${srcRoot}/`;
+	const rel = filePath.startsWith(prefix) ? filePath.slice(prefix.length) : filePath.slice(srcRoot.length);
+	return destRoot === "/" ? `/${rel}` : `${destRoot}/${rel}`;
+}
+/** cp -r / mv 目录场景的共用体：把 src 子树下每个文件 read 出来再 write 到重定位后的 dest 路径。空子目录不参与（RunkoFS.glob 只报文件）。 */
+async function copySubtree(fs, src, dest) {
+	const files = await fs.glob(subtreeGlobPattern(src));
+	for (const filePath of files) {
+		const data = await fs.readFile(filePath);
+		await fs.writeFile(relocate(src, dest, filePath), data);
+	}
+}
+async function cpImpl(fs, src, dest, options) {
+	const srcPath = normalizePath(src);
+	const destPath = normalizePath(dest);
+	if ((await fs.stat(srcPath)).type === "dir") {
+		if (options?.recursive !== true) throw new Error(`cp: -r not specified; omitting directory '${src}'`);
+		await copySubtree(fs, srcPath, destPath);
+		return;
+	}
+	const data = await fs.readFile(srcPath);
+	await fs.writeFile(destPath, data);
+}
+async function mvImpl(fs, src, dest) {
+	const srcPath = normalizePath(src);
+	const destPath = normalizePath(dest);
+	if ((await fs.stat(srcPath)).type === "dir") {
+		await copySubtree(fs, srcPath, destPath);
+		await fs.rm(srcPath, { recursive: true });
+		return;
+	}
+	const data = await fs.readFile(srcPath);
+	await fs.writeFile(destPath, data);
+	await fs.rm(srcPath);
+}
+async function rmImpl(fs, path, options) {
+	try {
+		await fs.rm(normalizePath(path), { recursive: options?.recursive });
+	} catch (error) {
+		if (options?.force === true) return;
+		throw error;
+	}
+}
+async function appendFileImpl(fs, path, addition) {
+	const normalized = normalizePath(path);
+	let existing;
+	try {
+		existing = await fs.readFile(normalized);
+	} catch {
+		existing = /* @__PURE__ */ new Uint8Array(0);
+	}
+	const combined = new Uint8Array(existing.length + addition.length);
+	combined.set(existing, 0);
+	combined.set(addition, existing.length);
+	await fs.writeFile(normalized, combined);
+}
+function createFsAdapter(fs) {
+	let allPathsCache = [];
+	async function refreshAllPaths() {
+		const files = await fs.glob("**");
+		const dirs = /* @__PURE__ */ new Set(["/"]);
+		for (const file of files) {
+			let dir = dirnameOf(file);
+			while (!dirs.has(dir)) {
+				dirs.add(dir);
+				const parent = dirnameOf(dir);
+				if (parent === dir) break;
+				dir = parent;
+			}
+		}
+		allPathsCache = [...files, ...dirs];
+	}
+	return {
+		async readFile(path) {
+			const bytes = await fs.readFile(normalizePath(path));
+			return textDecoder.decode(bytes);
+		},
+		async readFileBytes(path) {
+			const bytes = await fs.readFile(normalizePath(path));
+			return (0, just_bash.unsafeBytesFromLatin1)(Buffer.from(bytes).toString("latin1"));
+		},
+		async readFileBuffer(path) {
+			return fs.readFile(normalizePath(path));
+		},
+		async writeFile(path, content) {
+			await fs.writeFile(normalizePath(path), content);
+		},
+		async appendFile(path, content) {
+			await appendFileImpl(fs, path, typeof content === "string" ? textEncoder.encode(content) : content);
+		},
+		async exists(path) {
+			return existsImpl(fs, path);
+		},
+		async stat(path) {
+			return statImpl(fs, path);
+		},
+		async mkdir(path) {
+			await fs.mkdir(normalizePath(path));
+		},
+		async readdir(path) {
+			return (await fs.readdir(normalizePath(path))).map((entry) => entry.name);
+		},
+		async readdirWithFileTypes(path) {
+			return (await fs.readdir(normalizePath(path))).map((entry) => ({
+				name: entry.name,
+				isFile: entry.type === "file" || entry.type === "reference",
+				isDirectory: entry.type === "dir",
+				isSymbolicLink: false
+			}));
+		},
+		async rm(path, options) {
+			await rmImpl(fs, path, options);
+		},
+		async cp(src, dest, options) {
+			await cpImpl(fs, src, dest, options);
+		},
+		async mv(src, dest) {
+			await mvImpl(fs, src, dest);
+		},
+		resolvePath(base, path) {
+			return resolvePath(base, path);
+		},
+		getAllPaths() {
+			return allPathsCache;
+		},
+		async chmod() {},
+		async symlink(target, linkPath) {
+			throw new Error(`just-bash adapter: symlink is not supported (no symlink concept in RunkoFS v1): '${linkPath}' -> '${target}'`);
+		},
+		async link(existingPath, newPath) {
+			throw new Error(`just-bash adapter: hard link is not supported (no symlink concept in RunkoFS v1): '${newPath}' -> '${existingPath}'`);
+		},
+		async readlink(path) {
+			throw new Error(`just-bash adapter: readlink is not supported (no symlink concept in RunkoFS v1): '${path}'`);
+		},
+		async lstat(path) {
+			return statImpl(fs, path);
+		},
+		async realpath(path) {
+			return normalizePath(path);
+		},
+		async utimes() {},
+		refreshAllPaths
+	};
+}
+//#endregion
+//#region src/exec.ts
+/**
+* 默认收紧值（工单裁量：just-bash 自己的出厂默认——如 maxCommandCount 1万、
+* maxLoopIterations 1万、maxOutputSize 10MB——是为通用 CLI 场景设的，对
+* "一次 agent 工具调用里跑的一段脚本"明显过宽。这里按"典型 agent 脚本远小
+* 于这些量级，但仍留足够余量不误伤正常用例"的原则整体收紧一个数量级左右；
+* 全部字段都能被 `opts.limits` 逐个覆盖。）
+*/
+const DEFAULT_EXECUTION_LIMITS = {
+	maxCallDepth: 20,
+	maxCommandCount: 2e3,
+	maxLoopIterations: 2e3,
+	maxAwkIterations: 2e3,
+	maxSedIterations: 2e3,
+	maxJqIterations: 2e3,
+	maxSqliteTimeoutMs: 3e3,
+	maxGlobOperations: 5e3,
+	maxStringLength: 2 * 1024 * 1024,
+	maxArrayElements: 1e4,
+	maxHeredocSize: 1024 * 1024,
+	maxSubstitutionDepth: 20,
+	maxBraceExpansionResults: 2e3,
+	maxOutputSize: 1024 * 1024,
+	maxFileDescriptors: 256,
+	maxSourceDepth: 20
+};
+const DESCRIBE = [
+	"just-bash: full-syntax bash interpreter (vercel-labs/just-bash), running entirely on the injected RunkoFS",
+	"(mode A same-source workspace — bash and the file tools share one filesystem, nothing to reconcile).",
+	"Supports the full control-flow surface: if/elif/else, for (list and C-style `for ((i=0;i<n;i++))`),",
+	"while, until, case, functions with local variables, variable/parameter expansion, glob expansion,",
+	"pipes, `&&`/`||`, and redirections (`>`, `>>`, `<`, `2>&1`).",
+	"No symlinks: symlink/link/readlink always fail, and stat never reports a symbolic link.",
+	"No network: curl/wget are not registered (no fetch/network config is wired in).",
+	"No python/js sub-interpreters: disabled by default for reduced execution surface.",
+	"Output is NOT streamed: just-bash reports stdout/stderr only once the whole script has finished, so",
+	"onOutput fires at most once per stream, after the command completes (not incrementally as it runs).",
+	"cwd is persistent on this instance: a `cd` inside a script carries over to the next exec() call on the",
+	"same justBash(fs) instance (same semantics as @runko/mini-bash); an explicit req.cwd only overrides the",
+	"starting point for that one call and is not promoted to permanent memory unless a cd actually runs.",
+	"Execution limits are enforced (loop iterations, command count, call depth, output size, and more) to",
+	"bound runaway scripts; see justBash(fs, { limits }) to override the defaults."
+].join(" ");
+var JustBashAbortedError = class extends Error {
+	constructor(reason) {
+		super(reason === "timeout" ? "just-bash: command timed out" : "just-bash: aborted");
+		this.name = "JustBashAbortedError";
+	}
+};
+/**
+* 同 `@runko/mini-bash` 的 `raceAbort`：`signal` 先触发就立刻 reject，不等
+* `work` 真正落定（`work` 可能因为注入的 fs/glob 永久 pending，这正是需要
+* 竞速的原因）。给 `work` 补一个空 catch，避免它在竞速结束后才 reject/resolve
+* 时产生 unhandled rejection 噪音。
+*/
+function raceAbort(work, signal) {
+	return new Promise((resolve, reject) => {
+		const settleAborted = () => {
+			work.catch(() => {});
+			reject(new JustBashAbortedError("signal"));
+		};
+		if (signal.aborted) {
+			settleAborted();
+			return;
+		}
+		const onAbort = () => settleAborted();
+		signal.addEventListener("abort", onAbort, { once: true });
+		work.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(error instanceof Error ? error : new Error(String(error)));
+		});
+	});
+}
+function describeError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/** `result.env.PWD` 的类型安全读取——`noUncheckedIndexedAccess` 下 `Record<string,string>` 索引即 `string | undefined`，用 typeof 守卫而非断言。 */
+function endingCwdOf(result, fallback) {
+	const pwd = result.env.PWD;
+	return typeof pwd === "string" ? pwd : fallback;
+}
+function justBash(fs, opts = {}) {
+	const adapter = createFsAdapter(fs);
+	const bash = new just_bash.Bash({
+		fs: adapter,
+		cwd: "/",
+		executionLimits: {
+			...DEFAULT_EXECUTION_LIMITS,
+			...opts.limits
+		},
+		python: false,
+		javascript: false
+	});
+	let instanceCwd = "/";
+	return {
+		defaultApproval: "allow",
+		describe() {
+			return DESCRIBE;
+		},
+		async exec(req, execOpts) {
+			const start = Date.now();
+			const startCwd = req.cwd !== void 0 ? resolvePath("/", req.cwd) : instanceCwd;
+			const timeoutController = new AbortController();
+			const timer = req.timeoutMs !== void 0 ? setTimeout(() => timeoutController.abort(), req.timeoutMs) : void 0;
+			const combined = AbortSignal.any([req.signal, timeoutController.signal]);
+			const work = (async () => {
+				await adapter.refreshAllPaths();
+				return bash.exec(req.command, {
+					cwd: startCwd,
+					signal: combined
+				});
+			})();
+			try {
+				const result = await raceAbort(work, combined);
+				const endCwd = endingCwdOf(result, startCwd);
+				if (endCwd !== startCwd) instanceCwd = endCwd;
+				if (result.stdout.length > 0) execOpts?.onOutput?.({
+					stream: "stdout",
+					data: result.stdout
+				});
+				if (result.stderr.length > 0) execOpts?.onOutput?.({
+					stream: "stderr",
+					data: result.stderr
+				});
+				return {
+					exitCode: result.exitCode,
+					stdout: result.stdout,
+					stderr: result.stderr,
+					durationMs: Date.now() - start
+				};
+			} catch (error) {
+				const timedOut = timeoutController.signal.aborted;
+				if (error instanceof JustBashAbortedError || timedOut) return {
+					exitCode: timedOut ? 124 : 130,
+					stdout: "",
+					stderr: timedOut ? `just-bash: command timed out after ${String(req.timeoutMs)}ms` : "just-bash: aborted",
+					durationMs: Date.now() - start
+				};
+				return {
+					exitCode: 1,
+					stdout: "",
+					stderr: `just-bash: internal error: ${describeError(error)}`,
+					durationMs: Date.now() - start
+				};
+			} finally {
+				if (timer !== void 0) clearTimeout(timer);
+			}
+		}
+	};
+}
+//#endregion
+exports.justBash = justBash;

package/dist/index.d.cts

@@ -0,0 +1,19 @@
+import { RunkoExec, RunkoFS } from "@runko/core";
+import { BashOptions } from "just-bash";
+//#region src/exec.d.ts
+/**
+ * `just-bash` 不从包顶层导出 `ExecutionLimits` 这个类型名（`Bash.ts` 内部
+ * 有 `export type { ExecutionLimits } from "./limits.js"`，但顶层
+ * `index.ts` 的重导出列表里漏了它——实测 `tsc` 报 "has no exported member
+ * 'ExecutionLimits'" 确认）。改用索引访问类型从确实导出的 `BashOptions`
+ * 上派生同一个类型——结构上与直接导出完全等价，只是不依赖一个未导出的
+ * 名字；这不是类型逃逸（不是 `any`/断言），是用类型系统本身收窄出真实形状。
+ */
+type ExecutionLimits = NonNullable<BashOptions["executionLimits"]>;
+interface JustBashOptions {
+  /** 执行限额覆盖——与默认收紧值逐字段合并（未指定的字段沿用默认值）。 */
+  limits?: ExecutionLimits;
+}
+declare function justBash(fs: RunkoFS, opts?: JustBashOptions): RunkoExec;
+//#endregion
+export { type ExecutionLimits, type JustBashOptions, justBash };

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { BashOptions } from "just-bash";
+import { RunkoExec, RunkoFS } from "@runko/core";
+//#region src/exec.d.ts
+/**
+ * `just-bash` 不从包顶层导出 `ExecutionLimits` 这个类型名（`Bash.ts` 内部
+ * 有 `export type { ExecutionLimits } from "./limits.js"`，但顶层
+ * `index.ts` 的重导出列表里漏了它——实测 `tsc` 报 "has no exported member
+ * 'ExecutionLimits'" 确认）。改用索引访问类型从确实导出的 `BashOptions`
+ * 上派生同一个类型——结构上与直接导出完全等价，只是不依赖一个未导出的
+ * 名字；这不是类型逃逸（不是 `any`/断言），是用类型系统本身收窄出真实形状。
+ */
+type ExecutionLimits = NonNullable<BashOptions["executionLimits"]>;
+interface JustBashOptions {
+  /** 执行限额覆盖——与默认收紧值逐字段合并（未指定的字段沿用默认值）。 */
+  limits?: ExecutionLimits;
+}
+declare function justBash(fs: RunkoFS, opts?: JustBashOptions): RunkoExec;
+//#endregion
+export { type ExecutionLimits, type JustBashOptions, justBash };

package/dist/index.js

@@ -0,0 +1,371 @@
+import { Bash, unsafeBytesFromLatin1 } from "just-bash";
+//#region src/path.ts
+/**
+* 自包含的极简 POSIX 虚拟路径解析——与 `@runko/mini-bash` 的 `src/path.ts`
+* 同一份逻辑独立实现（不跨包依赖：src 侧只允许依赖 `@runko/core` + `just-bash`，
+* 见 P6-4 mini-bash 先例头注释）。`..` 越界静默 clamp 到根而非抛错——这一层
+* 不是安全边界（docs/tech/core-sdk.md §4.4："安全边界在 FS 不在工具"），真正的边界校验
+* 留给注入的 `RunkoFS` 实现自己那一层。
+*/
+/** 把任意输入（含 `.`、`..`、重复斜杠）规范化为以 `/` 开头的虚拟绝对路径。 */
+function normalizePath(input) {
+	const segments = input.split("/");
+	const stack = [];
+	for (const segment of segments) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			if (stack.length > 0) stack.pop();
+			continue;
+		}
+		stack.push(segment);
+	}
+	return `/${stack.join("/")}`;
+}
+/** 绝对路径直接规范化；相对路径先拼上 base 再规范化——与 `IFileSystem.resolvePath(base, path)` 签名同形。 */
+function resolvePath(base, input) {
+	if (input.startsWith("/")) return normalizePath(input);
+	return normalizePath(`${base}/${input}`);
+}
+/** 假定 path 已规范化。用于 `getAllPaths()` 从文件路径合成祖先目录集合（§4.5b）。 */
+function dirnameOf(path) {
+	if (path === "/") return "/";
+	const idx = path.lastIndexOf("/");
+	if (idx <= 0) return "/";
+	return path.slice(0, idx);
+}
+//#endregion
+//#region src/fs-adapter.ts
+const textDecoder = new TextDecoder();
+const textEncoder = new TextEncoder();
+const FILE_MODE = 420;
+const DIR_MODE = 493;
+/** reference 条目 stat 视为 file（降级表原文）。 */
+function toFsStat(stat) {
+	const isDirectory = stat.type === "dir";
+	return {
+		isFile: !isDirectory,
+		isDirectory,
+		isSymbolicLink: false,
+		mode: isDirectory ? DIR_MODE : FILE_MODE,
+		size: stat.size ?? 0,
+		mtime: new Date(stat.mtime ?? 0)
+	};
+}
+async function statImpl(fs, path) {
+	return toFsStat(await fs.stat(normalizePath(path)));
+}
+async function existsImpl(fs, path) {
+	try {
+		await fs.stat(normalizePath(path));
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** `${dir}/**` 形式的 glob 模式，匹配 dir 子树下的全部文件（不含 dir 自身）。 */
+function subtreeGlobPattern(dir) {
+	return dir === "/" ? "/**" : `${dir}/**`;
+}
+/** 把子树内某个文件的绝对路径，重定位到新的根 `destRoot` 下。 */
+function relocate(srcRoot, destRoot, filePath) {
+	const prefix = srcRoot === "/" ? "/" : `${srcRoot}/`;
+	const rel = filePath.startsWith(prefix) ? filePath.slice(prefix.length) : filePath.slice(srcRoot.length);
+	return destRoot === "/" ? `/${rel}` : `${destRoot}/${rel}`;
+}
+/** cp -r / mv 目录场景的共用体：把 src 子树下每个文件 read 出来再 write 到重定位后的 dest 路径。空子目录不参与（RunkoFS.glob 只报文件）。 */
+async function copySubtree(fs, src, dest) {
+	const files = await fs.glob(subtreeGlobPattern(src));
+	for (const filePath of files) {
+		const data = await fs.readFile(filePath);
+		await fs.writeFile(relocate(src, dest, filePath), data);
+	}
+}
+async function cpImpl(fs, src, dest, options) {
+	const srcPath = normalizePath(src);
+	const destPath = normalizePath(dest);
+	if ((await fs.stat(srcPath)).type === "dir") {
+		if (options?.recursive !== true) throw new Error(`cp: -r not specified; omitting directory '${src}'`);
+		await copySubtree(fs, srcPath, destPath);
+		return;
+	}
+	const data = await fs.readFile(srcPath);
+	await fs.writeFile(destPath, data);
+}
+async function mvImpl(fs, src, dest) {
+	const srcPath = normalizePath(src);
+	const destPath = normalizePath(dest);
+	if ((await fs.stat(srcPath)).type === "dir") {
+		await copySubtree(fs, srcPath, destPath);
+		await fs.rm(srcPath, { recursive: true });
+		return;
+	}
+	const data = await fs.readFile(srcPath);
+	await fs.writeFile(destPath, data);
+	await fs.rm(srcPath);
+}
+async function rmImpl(fs, path, options) {
+	try {
+		await fs.rm(normalizePath(path), { recursive: options?.recursive });
+	} catch (error) {
+		if (options?.force === true) return;
+		throw error;
+	}
+}
+async function appendFileImpl(fs, path, addition) {
+	const normalized = normalizePath(path);
+	let existing;
+	try {
+		existing = await fs.readFile(normalized);
+	} catch {
+		existing = /* @__PURE__ */ new Uint8Array(0);
+	}
+	const combined = new Uint8Array(existing.length + addition.length);
+	combined.set(existing, 0);
+	combined.set(addition, existing.length);
+	await fs.writeFile(normalized, combined);
+}
+function createFsAdapter(fs) {
+	let allPathsCache = [];
+	async function refreshAllPaths() {
+		const files = await fs.glob("**");
+		const dirs = /* @__PURE__ */ new Set(["/"]);
+		for (const file of files) {
+			let dir = dirnameOf(file);
+			while (!dirs.has(dir)) {
+				dirs.add(dir);
+				const parent = dirnameOf(dir);
+				if (parent === dir) break;
+				dir = parent;
+			}
+		}
+		allPathsCache = [...files, ...dirs];
+	}
+	return {
+		async readFile(path) {
+			const bytes = await fs.readFile(normalizePath(path));
+			return textDecoder.decode(bytes);
+		},
+		async readFileBytes(path) {
+			const bytes = await fs.readFile(normalizePath(path));
+			return unsafeBytesFromLatin1(Buffer.from(bytes).toString("latin1"));
+		},
+		async readFileBuffer(path) {
+			return fs.readFile(normalizePath(path));
+		},
+		async writeFile(path, content) {
+			await fs.writeFile(normalizePath(path), content);
+		},
+		async appendFile(path, content) {
+			await appendFileImpl(fs, path, typeof content === "string" ? textEncoder.encode(content) : content);
+		},
+		async exists(path) {
+			return existsImpl(fs, path);
+		},
+		async stat(path) {
+			return statImpl(fs, path);
+		},
+		async mkdir(path) {
+			await fs.mkdir(normalizePath(path));
+		},
+		async readdir(path) {
+			return (await fs.readdir(normalizePath(path))).map((entry) => entry.name);
+		},
+		async readdirWithFileTypes(path) {
+			return (await fs.readdir(normalizePath(path))).map((entry) => ({
+				name: entry.name,
+				isFile: entry.type === "file" || entry.type === "reference",
+				isDirectory: entry.type === "dir",
+				isSymbolicLink: false
+			}));
+		},
+		async rm(path, options) {
+			await rmImpl(fs, path, options);
+		},
+		async cp(src, dest, options) {
+			await cpImpl(fs, src, dest, options);
+		},
+		async mv(src, dest) {
+			await mvImpl(fs, src, dest);
+		},
+		resolvePath(base, path) {
+			return resolvePath(base, path);
+		},
+		getAllPaths() {
+			return allPathsCache;
+		},
+		async chmod() {},
+		async symlink(target, linkPath) {
+			throw new Error(`just-bash adapter: symlink is not supported (no symlink concept in RunkoFS v1): '${linkPath}' -> '${target}'`);
+		},
+		async link(existingPath, newPath) {
+			throw new Error(`just-bash adapter: hard link is not supported (no symlink concept in RunkoFS v1): '${newPath}' -> '${existingPath}'`);
+		},
+		async readlink(path) {
+			throw new Error(`just-bash adapter: readlink is not supported (no symlink concept in RunkoFS v1): '${path}'`);
+		},
+		async lstat(path) {
+			return statImpl(fs, path);
+		},
+		async realpath(path) {
+			return normalizePath(path);
+		},
+		async utimes() {},
+		refreshAllPaths
+	};
+}
+//#endregion
+//#region src/exec.ts
+/**
+* 默认收紧值（工单裁量：just-bash 自己的出厂默认——如 maxCommandCount 1万、
+* maxLoopIterations 1万、maxOutputSize 10MB——是为通用 CLI 场景设的，对
+* "一次 agent 工具调用里跑的一段脚本"明显过宽。这里按"典型 agent 脚本远小
+* 于这些量级，但仍留足够余量不误伤正常用例"的原则整体收紧一个数量级左右；
+* 全部字段都能被 `opts.limits` 逐个覆盖。）
+*/
+const DEFAULT_EXECUTION_LIMITS = {
+	maxCallDepth: 20,
+	maxCommandCount: 2e3,
+	maxLoopIterations: 2e3,
+	maxAwkIterations: 2e3,
+	maxSedIterations: 2e3,
+	maxJqIterations: 2e3,
+	maxSqliteTimeoutMs: 3e3,
+	maxGlobOperations: 5e3,
+	maxStringLength: 2 * 1024 * 1024,
+	maxArrayElements: 1e4,
+	maxHeredocSize: 1024 * 1024,
+	maxSubstitutionDepth: 20,
+	maxBraceExpansionResults: 2e3,
+	maxOutputSize: 1024 * 1024,
+	maxFileDescriptors: 256,
+	maxSourceDepth: 20
+};
+const DESCRIBE = [
+	"just-bash: full-syntax bash interpreter (vercel-labs/just-bash), running entirely on the injected RunkoFS",
+	"(mode A same-source workspace — bash and the file tools share one filesystem, nothing to reconcile).",
+	"Supports the full control-flow surface: if/elif/else, for (list and C-style `for ((i=0;i<n;i++))`),",
+	"while, until, case, functions with local variables, variable/parameter expansion, glob expansion,",
+	"pipes, `&&`/`||`, and redirections (`>`, `>>`, `<`, `2>&1`).",
+	"No symlinks: symlink/link/readlink always fail, and stat never reports a symbolic link.",
+	"No network: curl/wget are not registered (no fetch/network config is wired in).",
+	"No python/js sub-interpreters: disabled by default for reduced execution surface.",
+	"Output is NOT streamed: just-bash reports stdout/stderr only once the whole script has finished, so",
+	"onOutput fires at most once per stream, after the command completes (not incrementally as it runs).",
+	"cwd is persistent on this instance: a `cd` inside a script carries over to the next exec() call on the",
+	"same justBash(fs) instance (same semantics as @runko/mini-bash); an explicit req.cwd only overrides the",
+	"starting point for that one call and is not promoted to permanent memory unless a cd actually runs.",
+	"Execution limits are enforced (loop iterations, command count, call depth, output size, and more) to",
+	"bound runaway scripts; see justBash(fs, { limits }) to override the defaults."
+].join(" ");
+var JustBashAbortedError = class extends Error {
+	constructor(reason) {
+		super(reason === "timeout" ? "just-bash: command timed out" : "just-bash: aborted");
+		this.name = "JustBashAbortedError";
+	}
+};
+/**
+* 同 `@runko/mini-bash` 的 `raceAbort`：`signal` 先触发就立刻 reject，不等
+* `work` 真正落定（`work` 可能因为注入的 fs/glob 永久 pending，这正是需要
+* 竞速的原因）。给 `work` 补一个空 catch，避免它在竞速结束后才 reject/resolve
+* 时产生 unhandled rejection 噪音。
+*/
+function raceAbort(work, signal) {
+	return new Promise((resolve, reject) => {
+		const settleAborted = () => {
+			work.catch(() => {});
+			reject(new JustBashAbortedError("signal"));
+		};
+		if (signal.aborted) {
+			settleAborted();
+			return;
+		}
+		const onAbort = () => settleAborted();
+		signal.addEventListener("abort", onAbort, { once: true });
+		work.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(error instanceof Error ? error : new Error(String(error)));
+		});
+	});
+}
+function describeError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/** `result.env.PWD` 的类型安全读取——`noUncheckedIndexedAccess` 下 `Record<string,string>` 索引即 `string | undefined`，用 typeof 守卫而非断言。 */
+function endingCwdOf(result, fallback) {
+	const pwd = result.env.PWD;
+	return typeof pwd === "string" ? pwd : fallback;
+}
+function justBash(fs, opts = {}) {
+	const adapter = createFsAdapter(fs);
+	const bash = new Bash({
+		fs: adapter,
+		cwd: "/",
+		executionLimits: {
+			...DEFAULT_EXECUTION_LIMITS,
+			...opts.limits
+		},
+		python: false,
+		javascript: false
+	});
+	let instanceCwd = "/";
+	return {
+		defaultApproval: "allow",
+		describe() {
+			return DESCRIBE;
+		},
+		async exec(req, execOpts) {
+			const start = Date.now();
+			const startCwd = req.cwd !== void 0 ? resolvePath("/", req.cwd) : instanceCwd;
+			const timeoutController = new AbortController();
+			const timer = req.timeoutMs !== void 0 ? setTimeout(() => timeoutController.abort(), req.timeoutMs) : void 0;
+			const combined = AbortSignal.any([req.signal, timeoutController.signal]);
+			const work = (async () => {
+				await adapter.refreshAllPaths();
+				return bash.exec(req.command, {
+					cwd: startCwd,
+					signal: combined
+				});
+			})();
+			try {
+				const result = await raceAbort(work, combined);
+				const endCwd = endingCwdOf(result, startCwd);
+				if (endCwd !== startCwd) instanceCwd = endCwd;
+				if (result.stdout.length > 0) execOpts?.onOutput?.({
+					stream: "stdout",
+					data: result.stdout
+				});
+				if (result.stderr.length > 0) execOpts?.onOutput?.({
+					stream: "stderr",
+					data: result.stderr
+				});
+				return {
+					exitCode: result.exitCode,
+					stdout: result.stdout,
+					stderr: result.stderr,
+					durationMs: Date.now() - start
+				};
+			} catch (error) {
+				const timedOut = timeoutController.signal.aborted;
+				if (error instanceof JustBashAbortedError || timedOut) return {
+					exitCode: timedOut ? 124 : 130,
+					stdout: "",
+					stderr: timedOut ? `just-bash: command timed out after ${String(req.timeoutMs)}ms` : "just-bash: aborted",
+					durationMs: Date.now() - start
+				};
+				return {
+					exitCode: 1,
+					stdout: "",
+					stderr: `just-bash: internal error: ${describeError(error)}`,
+					durationMs: Date.now() - start
+				};
+			} finally {
+				if (timer !== void 0) clearTimeout(timer);
+			}
+		}
+	};
+}
+//#endregion
+export { justBash };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@runko/just-bash",
+  "version": "0.1.0",
+  "description": "RunkoExec 实现：适配 vercel-labs/just-bash 的全语法档 bash（if/for/while/case/函数），跑在任意 RunkoFS 上",
+  "type": "module",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "just-bash": "^3.1.0",
+    "@runko/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "ai": "^7.0.20",
+    "tsdown": "^0.22.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "@runko/virtual-fs": "^0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run"
+  }
+}