@downcity/shell 0.1.4

package/bin/sandbox/LinuxBubblewrapSandbox.js

@@ -0,0 +1,186 @@
+/**
+ * Linux Bubblewrap sandbox backend。
+ *
+ * 关键点（中文）
+ * - 基于 `bwrap` 提供 Linux 本机 shell sandbox。
+ * - 继续保持“shell 命令必须进入 sandbox”的安全语义，不提供宿主机裸跑回退。
+ * - 边界与 macOS backend 对齐：路径、环境变量、网络、agent 级共享 HOME/TMPDIR/cache。
+ */
+import { spawn } from "node:child_process";
+import path from "node:path";
+import fs from "fs-extra";
+const DEFAULT_PATH_VALUE = "/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:/usr/sbin:/sbin";
+function dedupeExistingPaths(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        const normalized = path.resolve(String(value || "").trim());
+        if (!normalized || seen.has(normalized))
+            continue;
+        if (!fs.existsSync(normalized))
+            continue;
+        seen.add(normalized);
+        result.push(normalized);
+    }
+    return result;
+}
+function buildReadablePaths(params) {
+    return dedupeExistingPaths([
+        "/usr",
+        "/bin",
+        "/sbin",
+        "/lib",
+        "/lib64",
+        "/etc",
+        params.rootPath,
+        params.sandboxDir,
+        params.tmpDir,
+        params.cacheDir,
+        path.dirname(params.shellPath),
+    ]);
+}
+function buildWritablePaths(params) {
+    return dedupeExistingPaths([
+        ...params.config.writablePaths,
+        params.executionDir,
+        params.config.sandboxDir,
+        params.config.tmpDir,
+        params.config.cacheDir,
+    ]);
+}
+function isPathCoveredBy(paths, targetPath) {
+    const normalizedTarget = path.resolve(targetPath);
+    return paths.some((value) => {
+        const normalizedValue = path.resolve(value);
+        if (normalizedValue === normalizedTarget)
+            return true;
+        const relative = path.relative(normalizedValue, normalizedTarget);
+        return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+    });
+}
+function buildSandboxEnv(params) {
+    const env = {};
+    for (const key of params.config.envAllowlist) {
+        const value = params.baseEnv[key];
+        if (typeof value !== "string" || !value.trim())
+            continue;
+        env[key] = value;
+    }
+    for (const [key, value] of Object.entries(params.baseEnv)) {
+        if (!key.startsWith("DC_"))
+            continue;
+        if (typeof value !== "string" || !value.trim())
+            continue;
+        env[key] = value;
+    }
+    env.PATH = String(env.PATH || params.baseEnv.PATH || DEFAULT_PATH_VALUE);
+    env.HOME = params.config.homeDir;
+    env.TMPDIR = params.config.tmpDir;
+    env.XDG_CACHE_HOME = params.config.cacheDir;
+    env.DC_SANDBOX = "1";
+    env.DC_SANDBOX_DIR = params.config.sandboxDir;
+    env.DC_SANDBOX_HOME = params.config.homeDir;
+    env.DC_SANDBOX_CACHE = params.config.cacheDir;
+    env.SHELL = params.shellPath;
+    return env;
+}
+function addReadOnlyBind(args, sourcePath) {
+    args.push("--ro-bind", sourcePath, sourcePath);
+}
+function addWritableBind(args, sourcePath) {
+    args.push("--bind", sourcePath, sourcePath);
+}
+function addParentDirs(args, targetPath, createdDirs) {
+    const parts = path.resolve(targetPath).split(path.sep).filter(Boolean);
+    let current = "";
+    for (let index = 0; index < parts.length - 1; index += 1) {
+        current = `${current}/${parts[index]}`;
+        if (createdDirs.has(current))
+            continue;
+        createdDirs.add(current);
+        args.push("--dir", current);
+    }
+}
+export function buildLinuxBubblewrapArgs(params) {
+    const readablePaths = buildReadablePaths({
+        rootPath: params.config.rootPath,
+        shellPath: params.shellPath,
+        sandboxDir: params.config.sandboxDir,
+        tmpDir: params.config.tmpDir,
+        cacheDir: params.config.cacheDir,
+    });
+    const writablePaths = buildWritablePaths(params);
+    const writableSet = new Set(writablePaths);
+    const createdDirs = new Set();
+    const mountedPaths = [];
+    const args = [
+        "--die-with-parent",
+        "--unshare-pid",
+        "--proc",
+        "/proc",
+        "--dev",
+        "/dev",
+    ];
+    if (params.config.networkMode === "off") {
+        args.push("--unshare-net");
+    }
+    for (const readablePath of readablePaths) {
+        if (writableSet.has(readablePath))
+            continue;
+        if (!isPathCoveredBy(mountedPaths, readablePath)) {
+            addParentDirs(args, readablePath, createdDirs);
+        }
+        addReadOnlyBind(args, readablePath);
+        mountedPaths.push(readablePath);
+    }
+    for (const writablePath of writablePaths) {
+        if (isPathCoveredBy(mountedPaths, writablePath))
+            continue;
+        addParentDirs(args, writablePath, createdDirs);
+        addWritableBind(args, writablePath);
+        mountedPaths.push(writablePath);
+    }
+    if (!isPathCoveredBy(readablePaths, params.actualCwd) &&
+        !isPathCoveredBy(writablePaths, params.actualCwd)) {
+        if (!isPathCoveredBy(mountedPaths, params.actualCwd)) {
+            addParentDirs(args, params.actualCwd, createdDirs);
+        }
+        addReadOnlyBind(args, params.actualCwd);
+    }
+    args.push("--chdir", params.actualCwd, params.shellPath, params.login ? "-lc" : "-c", params.cmd);
+    return args;
+}
+/**
+ * 在 Linux bubblewrap sandbox 中启动 shell 子进程。
+ */
+export async function spawnLinuxBubblewrapSandbox(params) {
+    await fs.ensureDir(params.config.sandboxDir);
+    await fs.ensureDir(params.config.tmpDir);
+    await fs.ensureDir(params.config.cacheDir);
+    await fs.ensureDir(params.executionDir);
+    for (const writablePath of params.config.writablePaths) {
+        await fs.ensureDir(writablePath);
+    }
+    const child = spawn("bwrap", buildLinuxBubblewrapArgs({
+        ...params,
+    }), {
+        cwd: params.actualCwd,
+        stdio: "pipe",
+        env: buildSandboxEnv(params),
+    });
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    return {
+        child,
+        cwd: params.actualCwd,
+        sandboxed: true,
+        sandboxMode: "safe",
+        backend: "linux-bubblewrap",
+        networkMode: params.config.networkMode,
+        sandboxDir: params.config.sandboxDir,
+        homeDir: params.config.homeDir,
+        tmpDir: params.config.tmpDir,
+        cacheDir: params.config.cacheDir,
+    };
+}
+//# sourceMappingURL=LinuxBubblewrapSandbox.js.map

package/bin/sandbox/LinuxBubblewrapSandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LinuxBubblewrapSandbox.js","sourceRoot":"","sources":["../../src/sandbox/LinuxBubblewrapSandbox.ts"],"names":[],"mappings":"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"}

package/bin/sandbox/MacOsSeatbeltSandbox.d.ts

@@ -0,0 +1,16 @@
+/**
+ * macOS Seatbelt sandbox backend。
+ *
+ * 关键点（中文）
+ * - 当前最小实现直接基于系统自带 `sandbox-exec`。
+ * - 目标不是抽象完整 provider 体系，而是先把 shell 命令从“宿主机直跑”收敛成“带边界执行”。
+ * - 边界只保留四类：路径、环境变量、网络、agent 级共享 HOME/TMPDIR/cache。
+ */
+import type { SandboxSpawnParams, SandboxSpawnResult } from "../sandbox/types/SandboxRuntime.js";
+/**
+ * 在 macOS seatbelt sandbox 中启动 shell 子进程。
+ */
+export declare function spawnMacOsSeatbeltSandbox(params: SandboxSpawnParams & {
+    actualCwd: string;
+}): Promise<SandboxSpawnResult>;
+//# sourceMappingURL=MacOsSeatbeltSandbox.d.ts.map

package/bin/sandbox/MacOsSeatbeltSandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MacOsSeatbeltSandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox/MacOsSeatbeltSandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,mCAAmC,CAAC;AA8H3C;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,kBAAkB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GACjD,OAAO,CAAC,kBAAkB,CAAC,CA4C7B"}

package/bin/sandbox/MacOsSeatbeltSandbox.js

@@ -0,0 +1,154 @@
+/**
+ * macOS Seatbelt sandbox backend。
+ *
+ * 关键点（中文）
+ * - 当前最小实现直接基于系统自带 `sandbox-exec`。
+ * - 目标不是抽象完整 provider 体系，而是先把 shell 命令从“宿主机直跑”收敛成“带边界执行”。
+ * - 边界只保留四类：路径、环境变量、网络、agent 级共享 HOME/TMPDIR/cache。
+ */
+import { spawn } from "node:child_process";
+import path from "node:path";
+import fs from "fs-extra";
+const DEFAULT_PATH_VALUE = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+function escapeSeatbeltString(value) {
+    return String(value || "").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function dedupePaths(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        const normalized = path.resolve(String(value || "").trim());
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        result.push(normalized);
+    }
+    return result;
+}
+function buildReadablePaths(params) {
+    return dedupePaths([
+        "/bin",
+        "/usr",
+        "/System",
+        "/etc",
+        "/dev",
+        "/Library",
+        "/opt/homebrew",
+        "/usr/local",
+        params.rootPath,
+        params.sandboxDir,
+        params.tmpDir,
+        params.cacheDir,
+        path.dirname(params.shellPath),
+    ]);
+}
+function buildWritablePaths(params) {
+    return dedupePaths([
+        ...params.config.writablePaths,
+        params.executionDir,
+        params.config.sandboxDir,
+        params.config.tmpDir,
+        params.config.cacheDir,
+    ]);
+}
+function buildNetworkRules(networkMode) {
+    if (networkMode === "restricted" || networkMode === "full") {
+        return ["(allow network-outbound)", "(allow network-inbound)"];
+    }
+    return [];
+}
+function buildSeatbeltProfile(params) {
+    const readablePaths = buildReadablePaths({
+        rootPath: params.config.rootPath,
+        shellPath: params.shellPath,
+        sandboxDir: params.config.sandboxDir,
+        tmpDir: params.config.tmpDir,
+        cacheDir: params.config.cacheDir,
+    });
+    const writablePaths = buildWritablePaths(params);
+    const lines = [
+        "(version 1)",
+        "(deny default)",
+        '(import "system.sb")',
+        "(allow process*)",
+        "(allow sysctl-read)",
+        "(allow file-read-metadata)",
+        ...readablePaths.map((value) => `(allow file-read* (subpath "${escapeSeatbeltString(value)}"))`),
+        ...writablePaths.map((value) => `(allow file-write* (subpath "${escapeSeatbeltString(value)}"))`),
+        ...buildNetworkRules(params.config.networkMode),
+    ];
+    // 关键点（中文）
+    // - `cwd` 需要显式出现在读集合里，否则很多命令刚启动时就会因为工作目录不可见而失败。
+    // - 这里单独追加，避免未来 rootPath 与 cwd 的关系变化时被遗漏。
+    if (!readablePaths.includes(params.actualCwd)) {
+        lines.push(`(allow file-read* (subpath "${escapeSeatbeltString(params.actualCwd)}"))`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function buildSandboxEnv(params) {
+    const env = {};
+    for (const key of params.config.envAllowlist) {
+        const value = params.baseEnv[key];
+        if (typeof value !== "string" || !value.trim())
+            continue;
+        env[key] = value;
+    }
+    for (const [key, value] of Object.entries(params.baseEnv)) {
+        if (!key.startsWith("DC_"))
+            continue;
+        if (typeof value !== "string" || !value.trim())
+            continue;
+        env[key] = value;
+    }
+    env.PATH = String(env.PATH || params.baseEnv.PATH || DEFAULT_PATH_VALUE);
+    env.HOME = params.config.homeDir;
+    env.ZDOTDIR = params.config.homeDir;
+    env.TMPDIR = params.config.tmpDir;
+    env.XDG_CACHE_HOME = params.config.cacheDir;
+    env.DC_SANDBOX = "1";
+    env.DC_SANDBOX_DIR = params.config.sandboxDir;
+    env.DC_SANDBOX_HOME = params.config.homeDir;
+    env.DC_SANDBOX_CACHE = params.config.cacheDir;
+    env.SHELL = params.shellPath;
+    return env;
+}
+/**
+ * 在 macOS seatbelt sandbox 中启动 shell 子进程。
+ */
+export async function spawnMacOsSeatbeltSandbox(params) {
+    const profilePath = path.join(params.executionDir, "sandbox-profile.sb");
+    await fs.ensureDir(params.config.sandboxDir);
+    await fs.ensureDir(params.config.tmpDir);
+    await fs.ensureDir(params.config.cacheDir);
+    await fs.ensureDir(params.executionDir);
+    const profile = buildSeatbeltProfile({
+        ...params,
+    });
+    await fs.writeFile(profilePath, profile, "utf-8");
+    const child = spawn("sandbox-exec", [
+        "-f",
+        profilePath,
+        params.shellPath,
+        params.login ? "-lc" : "-c",
+        params.cmd,
+    ], {
+        cwd: params.actualCwd,
+        stdio: "pipe",
+        env: buildSandboxEnv(params),
+    });
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    return {
+        child,
+        cwd: params.actualCwd,
+        sandboxed: true,
+        sandboxMode: "safe",
+        backend: "macos-seatbelt",
+        networkMode: params.config.networkMode,
+        sandboxDir: params.config.sandboxDir,
+        homeDir: params.config.homeDir,
+        tmpDir: params.config.tmpDir,
+        cacheDir: params.config.cacheDir,
+    };
+}
+//# sourceMappingURL=MacOsSeatbeltSandbox.js.map

package/bin/sandbox/MacOsSeatbeltSandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MacOsSeatbeltSandbox.js","sourceRoot":"","sources":["../../src/sandbox/MacOsSeatbeltSandbox.ts"],"names":[],"mappings":"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"}

package/bin/sandbox/SandboxConfigResolver.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Sandbox 配置解析器。
+ *
+ * 关键点（中文）
+ * - 这里负责把 `downcity.json` 中面向用户的最小配置，收敛成运行时可直接执行的绝对路径配置。
+ * - sandbox 是 agent 项目级能力，持久目录固定为 `<project>/.downcity/sandbox`。
+ * - 当前版本只服务 shell / CLI 这条命令执行链，不引入审批、profile 绑定或用户权限系统。
+ * - 解析结果只回答一个问题：这次命令执行的 sandbox 边界是什么。
+ */
+import type { ShellHostContext } from "../types/ShellHostContext.js";
+import type { SandboxBackend } from "../sandbox/types/SandboxRuntime.js";
+import type { ResolvedSandboxConfig } from "../sandbox/types/SandboxRuntime.js";
+/**
+ * 判断目标路径是否位于根目录内，或与根目录本身相同。
+ */
+export declare function isPathInsideRoot(rootPath: string, targetPath: string): boolean;
+/**
+ * 根据宿主平台解析当前 sandbox backend。
+ */
+export declare function resolveSandboxBackend(): SandboxBackend;
+/**
+ * 解析当前请求最终使用的 sandbox 配置。
+ */
+export declare function resolveSandboxConfig(context: ShellHostContext): ResolvedSandboxConfig;
+/**
+ * 归一化 sandbox 内实际使用的工作目录。
+ *
+ * 说明（中文）
+ * - sandbox 启用时，工作目录必须收敛在 `rootPath` 范围内。
+ * - 超出项目根目录的 `cwd` 会被强制拉回 `rootPath`，避免宿主目录通过 `cwd` 泄漏回去。
+ */
+export declare function resolveSandboxCwd(params: {
+    rootPath: string;
+    requestedCwd: string;
+    context: ShellHostContext;
+}): string;
+//# sourceMappingURL=SandboxConfigResolver.d.ts.map

package/bin/sandbox/SandboxConfigResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxConfigResolver.d.ts","sourceRoot":"","sources":["../../src/sandbox/SandboxConfigResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AA4B/E;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAM9E;AAyCD;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,cAAc,CAMtD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,gBAAgB,GAAG,qBAAqB,CAuBrF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,gBAAgB,CAAC;CAC3B,GAAG,MAAM,CAUT"}

package/bin/sandbox/SandboxConfigResolver.js

@@ -0,0 +1,130 @@
+/**
+ * Sandbox 配置解析器。
+ *
+ * 关键点（中文）
+ * - 这里负责把 `downcity.json` 中面向用户的最小配置，收敛成运行时可直接执行的绝对路径配置。
+ * - sandbox 是 agent 项目级能力，持久目录固定为 `<project>/.downcity/sandbox`。
+ * - 当前版本只服务 shell / CLI 这条命令执行链，不引入审批、profile 绑定或用户权限系统。
+ * - 解析结果只回答一个问题：这次命令执行的 sandbox 边界是什么。
+ */
+import path from "node:path";
+const DEFAULT_ENV_ALLOWLIST = [
+    "PATH",
+    "LANG",
+    "TERM",
+    "COLORTERM",
+    "LC_ALL",
+    "LC_CTYPE",
+    "SHELL",
+    "USER",
+    "LOGNAME",
+];
+const SANDBOX_RELATIVE_DIR = path.join(".downcity", "sandbox");
+function normalizeEnvAllowlist(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values || DEFAULT_ENV_ALLOWLIST) {
+        const normalized = String(value || "").trim();
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        result.push(normalized);
+    }
+    return result;
+}
+/**
+ * 判断目标路径是否位于根目录内，或与根目录本身相同。
+ */
+export function isPathInsideRoot(rootPath, targetPath) {
+    const normalizedRoot = path.resolve(rootPath);
+    const normalizedTarget = path.resolve(targetPath);
+    if (normalizedRoot === normalizedTarget)
+        return true;
+    const relative = path.relative(normalizedRoot, normalizedTarget);
+    return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function normalizeWritablePaths(params) {
+    const { rootPath, sandboxDir, writablePaths, context } = params;
+    const rawValues = Array.isArray(writablePaths) && writablePaths.length > 0
+        ? [rootPath, sandboxDir, ...writablePaths]
+        : [rootPath, sandboxDir];
+    const seen = new Set();
+    const result = [];
+    for (const rawValue of rawValues) {
+        const normalizedValue = String(rawValue || "").trim();
+        if (!normalizedValue)
+            continue;
+        const resolvedPath = path.resolve(path.isAbsolute(normalizedValue) ? normalizedValue : path.join(rootPath, normalizedValue));
+        if (!isPathInsideRoot(rootPath, resolvedPath)) {
+            context.logger?.warn("[sandbox] writable path ignored because it escapes project root", {
+                rootPath,
+                ignoredPath: normalizedValue,
+                resolvedPath,
+            });
+            continue;
+        }
+        if (seen.has(resolvedPath))
+            continue;
+        seen.add(resolvedPath);
+        result.push(resolvedPath);
+    }
+    if (result.length === 0) {
+        result.push(path.resolve(rootPath));
+    }
+    return result;
+}
+/**
+ * 根据宿主平台解析当前 sandbox backend。
+ */
+export function resolveSandboxBackend() {
+    if (process.platform === "darwin")
+        return "macos-seatbelt";
+    if (process.platform === "linux")
+        return "linux-bubblewrap";
+    throw new Error(`sandbox backend is required for shell execution, but current platform is unsupported: ${process.platform}`);
+}
+/**
+ * 解析当前请求最终使用的 sandbox 配置。
+ */
+export function resolveSandboxConfig(context) {
+    const rootPath = path.resolve(context.rootPath);
+    const projectConfig = context.config?.sandbox;
+    const sandboxDir = path.join(rootPath, SANDBOX_RELATIVE_DIR);
+    const tmpDir = path.join(sandboxDir, "tmp");
+    const cacheDir = path.join(sandboxDir, ".cache");
+    return {
+        backend: resolveSandboxBackend(),
+        rootPath,
+        sandboxDir,
+        homeDir: sandboxDir,
+        tmpDir,
+        cacheDir,
+        envAllowlist: normalizeEnvAllowlist(projectConfig?.envAllowlist),
+        writablePaths: normalizeWritablePaths({
+            rootPath,
+            sandboxDir,
+            writablePaths: projectConfig?.writablePaths,
+            context,
+        }),
+        networkMode: projectConfig?.networkMode || "full",
+    };
+}
+/**
+ * 归一化 sandbox 内实际使用的工作目录。
+ *
+ * 说明（中文）
+ * - sandbox 启用时，工作目录必须收敛在 `rootPath` 范围内。
+ * - 超出项目根目录的 `cwd` 会被强制拉回 `rootPath`，避免宿主目录通过 `cwd` 泄漏回去。
+ */
+export function resolveSandboxCwd(params) {
+    const normalizedCwd = path.resolve(params.requestedCwd);
+    if (isPathInsideRoot(params.rootPath, normalizedCwd)) {
+        return normalizedCwd;
+    }
+    params.context.logger?.warn("[sandbox] cwd escapes project root and was reset to rootPath", {
+        rootPath: params.rootPath,
+        requestedCwd: normalizedCwd,
+    });
+    return params.rootPath;
+}
+//# sourceMappingURL=SandboxConfigResolver.js.map

package/bin/sandbox/SandboxConfigResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxConfigResolver.js","sourceRoot":"","sources":["../../src/sandbox/SandboxConfigResolver.ts"],"names":[],"mappings":"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"}

package/bin/sandbox/SandboxPreflight.d.ts

@@ -0,0 +1,73 @@
+/**
+ * SandboxPreflight：本机 shell sandbox 依赖预检。
+ *
+ * 关键点（中文）
+ * - shell 命令必须进入 sandbox；这里提前检查 backend 依赖，避免启动后首次 shell 执行才失败。
+ * - Linux backend 基于 bubblewrap，本质使用 Linux namespaces / bind mount 等内核能力。
+ * - 本模块只诊断并给出修复建议，不自动安装软件，也不修改宿主机 sysctl。
+ */
+import type { SandboxBackend } from "../sandbox/types/SandboxRuntime.js";
+/**
+ * sandbox 预检失败原因。
+ */
+export type SandboxPreflightIssueCode = "unsupported-platform" | "missing-command" | "userns-disabled";
+/**
+ * 单条 sandbox 预检失败。
+ */
+export interface SandboxPreflightIssue {
+    /**
+     * 机器可读的失败原因。
+     */
+    code: SandboxPreflightIssueCode;
+    /**
+     * 人类可读的失败说明。
+     */
+    message: string;
+    /**
+     * 可复制的修复建议列表。
+     */
+    fixes: string[];
+}
+/**
+ * sandbox 预检结果。
+ */
+export interface SandboxPreflightResult {
+    /**
+     * 当前平台是否满足 shell sandbox 启动要求。
+     */
+    ok: boolean;
+    /**
+     * 当前宿主平台。
+     */
+    platform: NodeJS.Platform;
+    /**
+     * 当前平台对应的 sandbox backend。
+     */
+    backend?: SandboxBackend;
+    /**
+     * 失败原因集合。
+     */
+    issues: SandboxPreflightIssue[];
+}
+/**
+ * sandbox 预检宿主探测依赖。
+ */
+export interface ShellSandboxPreflightProbe {
+    /**
+     * 判断命令是否存在于 PATH 中。
+     */
+    commandExists(command: string): Promise<boolean>;
+    /**
+     * 读取 `/proc` 下整数配置。
+     */
+    readProcInt(filePath: string): Promise<number | null>;
+}
+/**
+ * 检查当前宿主是否满足 shell sandbox 运行要求。
+ */
+export declare function checkShellSandboxPreflight(): Promise<SandboxPreflightResult>;
+/**
+ * 使用注入探针检查当前宿主是否满足 shell sandbox 运行要求。
+ */
+export declare function checkShellSandboxPreflightWithProbe(probe: ShellSandboxPreflightProbe): Promise<SandboxPreflightResult>;
+//# sourceMappingURL=SandboxPreflight.d.ts.map

package/bin/sandbox/SandboxPreflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxPreflight.d.ts","sourceRoot":"","sources":["../../src/sandbox/SandboxPreflight.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAExE;;GAEG;AACH,MAAM,MAAM,yBAAyB,GACjC,sBAAsB,GACtB,iBAAiB,GACjB,iBAAiB,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,IAAI,EAAE,yBAAyB,CAAC;IAEhC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,EAAE,EAAE,OAAO,CAAC;IAEZ;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAE1B;;OAEG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB;;OAEG;IACH,MAAM,EAAE,qBAAqB,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjD;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACvD;AAyCD;;GAEG;AACH,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,sBAAsB,CAAC,CAKlF;AAED;;GAEG;AACH,wBAAsB,mCAAmC,CACvD,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,sBAAsB,CAAC,CAoEjC"}