@tcb-sandbox/cli 0.3.7 → 0.3.8

package/README.md

@@ -1,67 +1,87 @@
 # @tcb-sandbox/cli
 
-面向 **TRW（tcb-remote-workspace）** 的命令行工具：**一种安装，两种用法**。
-
-> **目录位置：** `clis/sandbox-cli/`
-
-| 用法 | 说明 |
-|------|------|
-| **本机起服务** | `tcb-sandbox serve`（或 `local`）在本地跑内置 TRW，默认 `http://127.0.0.1:9000`。 |
-| **只当客户端** | 其它子命令都是 **HTTP 薄客户端**，用 `--endpoint` / `--session-id` 连已有 TRW（远端或本机均可）。 |
-
-**文档（建议按顺序看）：** [快速上手](./docs/quick-start.md) → [薄客户端](./docs/thin-client.md) → [本地 serve](./docs/local-mode.md) → [文档索引](./docs/README.md) → [变更记录](./CHANGELOG.md)
-
----
+TRW 的官方命令行工具：**一种安装，两种用法**。
 
 ## 安装
 
-任选一种全局安装方式：
-
 ```bash
 npm install -g @tcb-sandbox/cli
-```
-
-```bash
+# 或
 pnpm add -g @tcb-sandbox/cli
 ```
 
-安装后可用命令名：**`tcb-sandbox`**（主名）、**`tcb-sandbox`**（别名）。
+## 两种用法
 
----
+| 用法 | 命令 | 说明 |
+|------|------|------|
+| **本地起服务** | `tcb-sandbox serve` | 启动内置 TRW，默认 `http://127.0.0.1:9000` |
+| **只当客户端** | `tcb-sandbox <tool>` | 调用已有 TRW（远端或本地） |
 
-## 最短路径
+## 快速开始
 
 ```bash
+# 本地模式
 tcb-sandbox serve
+
 # 另开终端
 tcb-sandbox --endpoint http://127.0.0.1:9000 --session-id my-session health
+tcb-sandbox --session-id my-session write --path hello.txt --content "world"
+tcb-sandbox --session-id my-session read --path hello.txt
 ```
 
-serve 之后 TRW **六大门面**（HTTP API、`/mcp`、`/mcp_user_define`、CLI、Skills、E2B）及探活/文档/预览，见 **[docs/quick-start.md](./docs/quick-start.md)**。
+## 环境变量
 
----
+```bash
+export TRW_ENDPOINT=https://your-gateway.com
+export TRW_SESSION_ID=your-session-id
 
-## 使用前提（读一遍即可）
+# 然后可直接使用
+tcb-sandbox health
+tcb-sandbox bash --command "ls -la"
+```
 
-- **TRW 没有单独发 npm 包**；本地模式用的是本包自带的 **`dist/trw-embedded.js`**（esbuild 打好的服务）。
-- 需要 **node-pty**、**@mongodb-js/zstd**：已写在包的 `dependencies` 里，给内置 bundle 动态加载用。
-- 想用**自己编出来的 TRW** 替代内置文件：设环境变量 **`TCB_SANDBOX_TRW_ENTRY`** 指向你的 `dist/index.js` 等入口（见 [local-mode.md](./docs/local-mode.md)）。
-- 公开展示的相关仓库还有 **@tcb-sandbox/e2b-sandbox-adapter** 等；**npm 上搜不到名叫 TRW 的包**是正常的。
-- 连远端 TRW 时**不会**在 CLI 里写死密钥；工具列表优先走 **`GET /api/docs`**（离线时 CLI 可能用内置文档快照）。
+## 命令列表
 
----
+| 命令 | 说明 |
+|------|------|
+| `serve` / `local` | 启动本地 TRW |
+| `health` | 健康检查 |
+| `read` / `write` / `edit` | 文件操作 |
+| `bash` | 执行命令 |
+| `grep` / `glob` / `ls` | 搜索 |
+| `batch` | 批量执行 |
+| `git-push` | Git 提交 |
+| `add-mcp-servers` / `remove-mcp-servers` / `list-mcp-servers` | MCP 管理 |
+| `mcporter` | mcporter CLI |
+| `capability-*` | 能力管理（6个） |
+| `secrets` | 密钥管理 |
+| `files` | 文件传输 |
+| `preview` | 预览服务 |
+| `pty` | PTY 终端 |
+| `snapshot` | 快照管理 |
+
+## 本地模式详情
 
-## 仓库内维护 / 发布
+```bash
+# 默认端口 9000
+tcb-sandbox serve
 
-以下在 **tcb-remote-workspace** monorepo **根目录**执行（发布前请再跑一遍 test）：
+# 指定端口
+tcb-sandbox serve --port 8080
 
-```bash
-pnpm --filter @tcb-sandbox/cli run build
-pnpm --filter @tcb-sandbox/cli run test
-pnpm --filter @tcb-sandbox/cli run pack:dry-run
-pnpm --filter @tcb-sandbox/cli run pack:safety   # 拒绝把 .env、src、tests、*.map 打进包
-pnpm --filter @tcb-sandbox/cli version patch     # 或 minor / major
-pnpm --filter @tcb-sandbox/cli publish
+# 使用自定义 TRW 入口（开发用）
+export TCB_SANDBOX_TRW_ENTRY=/path/to/your/dist/index.js
+tcb-sandbox serve
 ```
 
-可选：包内 **live 测试** 读 `cli/.env`（参考 `.env.example`）。
+## 限制
+
+- 除 `serve` 外所有命令都是纯 HTTP 客户端
+- 需要有效的 `endpoint` 和 `session-id`
+- 文件传输受 6MB 限制
+
+## 更多文档
+
+- `docs/quick-start.md` — 快速上手
+- `docs/local-mode.md` — 本地模式详解
+- `docs/thin-client.md` — 薄客户端说明

package/dist/bundled-docs.js

@@ -87,10 +87,7 @@ export const BUNDLED_API_DOCS = {
                 additionalProperties: false,
                 properties: {
                     serverNames: {
-                        oneOf: [
-                            { type: "array", items: { type: "string" } },
-                            { type: "string" },
-                        ],
+                        oneOf: [{ type: "array", items: { type: "string" } }, { type: "string" }],
                     },
                     serverName: { type: "string" },
                     name: { type: "string" },
@@ -161,11 +158,17 @@ export const BUNDLED_API_DOCS = {
                 type: "object",
                 required: ["command"],
                 properties: {
-                    command: { type: "string", description: "Mcporter subcommand (without 'mcporter' prefix)" },
+                    command: {
+                        type: "string",
+                        description: "Mcporter subcommand (without 'mcporter' prefix)",
+                    },
                     timeout: { type: "integer", description: "Timeout in ms (default 300000)" },
                 },
             },
-            limits: { default_timeout_ms: 300_000, allowed_subcommands: ["help", "list", "call", "config"] },
+            limits: {
+                default_timeout_ms: 300_000,
+                allowed_subcommands: ["help", "list", "call", "config"],
+            },
             notes: ["Bundled fallback docs snapshot."],
         },
         {

package/dist/cli.js

@@ -2,10 +2,10 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
+import { TcbSandboxClient } from "@tcb-sandbox/sdk-js";
 import { Command } from "commander";
 import { BUNDLED_API_DOCS } from "./bundled-docs.js";
 import { defaultWorkspaceRoot, runServe } from "./serve.js";
-import { TcbSandboxClient } from "@tcb-sandbox/sdk-js";
 const DEFAULT_TIMEOUT = 600_000;
 const DEFAULT_ACCEPT_HEADER = "application/problem+json, application/json;q=0.9, text/markdown;q=0.8, */*;q=0.1";
 const LOG_PRIORITIES = {
@@ -130,24 +130,6 @@ function logMessage(ctx, level, message) {
     }
     process.stderr.write(`[${level.toUpperCase()}] ${message}\n`);
 }
-function parseKeyValue(input) {
-    const idx = input.indexOf("=");
-    if (idx <= 0)
-        throw new Error(`Invalid --param "${input}". Expected key=value.`);
-    const key = input.slice(0, idx).trim();
-    const raw = input.slice(idx + 1);
-    if (!key)
-        throw new Error(`Invalid --param "${input}". Key is empty.`);
-    if (raw === "true")
-        return [key, true];
-    if (raw === "false")
-        return [key, false];
-    if (raw === "null")
-        return [key, null];
-    if (raw !== "" && /^-?\d+(\.\d+)?$/.test(raw))
-        return [key, Number(raw)];
-    return [key, raw];
-}
 function normalizeBashModeValue(input) {
     if (typeof input !== "string") {
         throw new Error('Invalid bash mode. Supported values: "execute", "dry_run", "dryrun".');
@@ -203,112 +185,6 @@ function createSdkClientFromContext(ctx) {
         timeoutInSeconds: ctx.timeout > 0 ? Math.floor(ctx.timeout / 1000) : DEFAULT_TIMEOUT / 1000,
     });
 }
-async function request(ctx, method, route, options) {
-    const controller = new AbortController();
-    const startedAt = Date.now();
-    const timer = setTimeout(() => controller.abort(), ctx.timeout);
-    const headers = { ...ctx.headers };
-    if (options?.accept) {
-        headers.Accept = options.accept;
-    }
-    else if (!Object.keys(headers).some((key) => key.toLowerCase() === "accept")) {
-        headers.Accept = DEFAULT_ACCEPT_HEADER;
-    }
-    let body;
-    if (options?.json !== undefined) {
-        headers["Content-Type"] = "application/json";
-        body = JSON.stringify(options.json);
-    }
-    else if (options?.body) {
-        headers["Content-Type"] = options.contentType ?? "application/octet-stream";
-        body = new Uint8Array(options.body);
-    }
-    logMessage(ctx, "info", `${method} ${route}`);
-    if (shouldLog(ctx, "debug")) {
-        const maskedHeaders = {};
-        for (const [k, v] of Object.entries(headers)) {
-            maskedHeaders[k] = maskHeaderValue(k, v);
-        }
-        logMessage(ctx, "debug", `request headers: ${JSON.stringify(maskedHeaders)}`);
-        if (options?.json !== undefined) {
-            logMessage(ctx, "debug", `request json: ${JSON.stringify(redactJsonForDebug(options.json))}`);
-        }
-        else if (options?.body) {
-            logMessage(ctx, "debug", `request body bytes: ${options.body.byteLength}`);
-        }
-    }
-    try {
-        const res = await fetch(`${ctx.endpoint}${route}`, {
-            method,
-            headers,
-            body,
-            signal: controller.signal,
-        });
-        const elapsed = Date.now() - startedAt;
-        logMessage(ctx, "info", `${method} ${route} -> ${res.status} (${elapsed}ms)`);
-        return res;
-    }
-    catch (err) {
-        const elapsed = Date.now() - startedAt;
-        logMessage(ctx, "error", `${method} ${route} failed after ${elapsed}ms: ${err instanceof Error ? err.message : String(err)}`);
-        throw err;
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-function safeParseJson(input) {
-    try {
-        return JSON.parse(input);
-    }
-    catch {
-        return undefined;
-    }
-}
-function extractErrorMessage(payload) {
-    if (!payload || typeof payload !== "object")
-        return undefined;
-    const maybe = payload;
-    if (typeof maybe.detail === "string" && maybe.detail.trim())
-        return maybe.detail;
-    if (typeof maybe.error === "string" && maybe.error.trim())
-        return maybe.error;
-    if (typeof maybe.message === "string" && maybe.message.trim())
-        return maybe.message;
-    if (typeof maybe.title === "string" && maybe.title.trim())
-        return maybe.title;
-    return undefined;
-}
-async function throwHttpError(res, requestLabel) {
-    const text = await res.text();
-    const payload = safeParseJson(text);
-    const contentType = res.headers.get("content-type") ?? "";
-    const message = extractErrorMessage(payload);
-    if (payload && typeof payload === "object" && contentType.includes("application/problem+json")) {
-        const problem = payload;
-        const retryHint = problem.retryable && typeof problem.retry_after === "number"
-            ? `; retry after ${problem.retry_after}s`
-            : problem.retryable
-                ? "; retryable"
-                : "";
-        const codeHint = problem.error_code ? ` [${problem.error_code}]` : "";
-        throw new Error(`${requestLabel} failed (${res.status})${codeHint}: ${message ?? "Unknown problem response"}${retryHint}`);
-    }
-    throw new Error(`${requestLabel} failed (${res.status}): ${message ?? (text || "Unknown error response")}`);
-}
-async function readJsonResponse(res, requestLabel) {
-    if (!res.ok) {
-        return throwHttpError(res, requestLabel);
-    }
-    let body;
-    try {
-        body = await res.json();
-    }
-    catch (err) {
-        throw new Error(`${requestLabel} returned non-JSON response: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    return body;
-}
 function printJson(data) {
     process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
 }
@@ -316,19 +192,6 @@ function printPretty(title, data) {
     process.stdout.write(`${title}\n`);
     printJson(data);
 }
-async function readApiDocs(ctx) {
-    const res = await request(ctx, "GET", "/api/docs");
-    return readJsonResponse(res, "GET /api/docs");
-}
-async function getDocs(ctx) {
-    try {
-        return await readApiDocs(ctx);
-    }
-    catch {
-        logMessage(ctx, "warn", "GET /api/docs unavailable, using bundled fallback docs");
-        return BUNDLED_API_DOCS;
-    }
-}
 async function readFromStdin() {
     const chunks = [];
     for await (const chunk of process.stdin) {
@@ -336,35 +199,6 @@ async function readFromStdin() {
     }
     return Buffer.concat(chunks).toString("utf8");
 }
-function renderSchema(schema) {
-    const properties = (schema.properties ?? {});
-    const required = new Set((schema.required ?? []));
-    const lines = [];
-    const keys = Object.keys(properties);
-    if (keys.length === 0) {
-        lines.push("  (no fields)");
-        return lines;
-    }
-    for (const key of keys) {
-        const spec = properties[key];
-        const type = spec.type ?? "unknown";
-        const desc = spec.description ?? "";
-        const mark = required.has(key) ? "required" : "optional";
-        const constraint = typeof spec.minimum === "number"
-            ? `, min=${spec.minimum}`
-            : typeof spec.pattern === "string"
-                ? `, pattern=${spec.pattern}`
-                : "";
-        lines.push(`  - ${key}: ${type} (${mark}${constraint})${desc ? ` — ${desc}` : ""}`);
-    }
-    return lines;
-}
-function renderRecord(record) {
-    const entries = Object.entries(record);
-    if (entries.length === 0)
-        return ["  (none)"];
-    return entries.map(([k, v]) => `  - ${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`);
-}
 async function getPreviewUrl(ctx, port) {
     ensureSessionId(ctx);
     const client = createSdkClientFromContext(ctx);
@@ -382,12 +216,6 @@ async function getPreviewUrl(ctx, port) {
     }
     return previewUrl;
 }
-async function callTopLevelTool(ctx, tool, payload, label) {
-    const res = await request(ctx, "POST", `/api/tools/${encodeURIComponent(tool)}`, {
-        json: payload,
-    });
-    return readJsonResponse(res, label);
-}
 async function openUrl(url) {
     const { spawn } = await import("node:child_process");
     const platform = process.platform;
@@ -569,7 +397,9 @@ Error Handling
             command,
             timeout: options.timeout,
             cwd: options.cwd,
-            mode: options.mode ? normalizeBashModeValue(options.mode) : undefined,
+            mode: options.mode
+                ? normalizeBashModeValue(options.mode)
+                : undefined,
         };
         const response = await client.execution.bash(bashRequest);
         const result = "data" in response ? response.data : response;
@@ -657,7 +487,8 @@ Error Handling
         const payload = options.data ? parseJsonObject(options.data, "--data") : { tool_calls: [] };
         logMessage(ctx, "info", "POST /api/tools/batch");
         const batchRequest = {
-            tool_calls: payload.tool_calls || [],
+            tool_calls: payload.tool_calls ||
+                [],
         };
         const response = await client.execution.batch(batchRequest);
         const result = "data" in response ? response.data : response;
@@ -787,7 +618,9 @@ Error Handling
         ensureSessionId(ctx);
         const client = createSdkClientFromContext(ctx);
         logMessage(ctx, "info", "POST /api/tools/capability_list");
-        const response = await client.capabilitySystem.capabilityList({ revealPaths: options.revealPaths });
+        const response = await client.capabilitySystem.capabilityList({
+            revealPaths: options.revealPaths,
+        });
         const result = "data" in response ? response.data : response;
         if (ctx.output === "json")
             return printJson(result);

package/dist/sandbox.js

@@ -0,0 +1,86 @@
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function isMacOSSandboxAvailable() {
+    if (process.platform !== "darwin")
+        return false;
+    try {
+        execFileSync("/usr/bin/sandbox-exec", ["-p", "(version 1)(allow default)", "/usr/bin/true"], {
+            timeout: 5000,
+            stdio: "ignore",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function generateProfile(writablePaths) {
+    const lines = [
+        ";; Auto-generated by @tcb-sandbox/cli — macOS sandbox profile",
+        ";; Restricts file-write to workspace + system temp directories.",
+        "(version 1)",
+        "",
+        ";; Allow everything by default (read, network, process, IPC, …)",
+        "(allow default)",
+        "",
+        ";; Deny all file writes globally",
+        "(deny file-write*)",
+        "",
+        ";; Re-allow writes to specific paths",
+    ];
+    for (const p of writablePaths) {
+        const abs = path.resolve(p);
+        lines.push(`(allow file-write* (subpath "${abs}"))`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+export function resolveWritablePaths(workspaceRoot) {
+    const paths = [
+        path.resolve(workspaceRoot),
+        "/tmp",
+        "/private/tmp",
+        "/dev",
+        "/private/var/folders",
+    ];
+    const tmpDir = os.tmpdir();
+    if (tmpDir && !paths.some((p) => tmpDir.startsWith(p))) {
+        paths.push(tmpDir);
+    }
+    return paths;
+}
+export function writeProfileFile(workspaceRoot, profile) {
+    const sandboxDir = path.join(path.dirname(path.resolve(workspaceRoot)), "sandbox");
+    fs.mkdirSync(sandboxDir, { recursive: true });
+    const profilePath = path.join(sandboxDir, "serve.sb");
+    fs.writeFileSync(profilePath, profile, "utf8");
+    return profilePath;
+}
+export function spawnSandboxed(trwMain, env, workspaceRoot) {
+    const available = isMacOSSandboxAvailable();
+    if (!available) {
+        const child = spawn(process.execPath, [trwMain], {
+            stdio: "inherit",
+            env,
+        });
+        return {
+            enabled: false,
+            status: "unavailable (not macOS or sandbox-exec missing)",
+            child,
+        };
+    }
+    const writablePaths = resolveWritablePaths(workspaceRoot);
+    const profile = generateProfile(writablePaths);
+    const profilePath = writeProfileFile(workspaceRoot, profile);
+    const child = spawn("/usr/bin/sandbox-exec", ["-f", profilePath, process.execPath, trwMain], {
+        stdio: "inherit",
+        env,
+    });
+    return {
+        enabled: true,
+        status: `active (writes restricted to ${workspaceRoot}, /tmp)`,
+        child,
+    };
+}