@tcb-sandbox/cli 0.3.7

package/dist/cli.js

@@ -0,0 +1,1234 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+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 = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+const DEFAULT_LOG_LEVEL = "warn";
+function asInt(value) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`Invalid integer value: ${value}`);
+    }
+    return parsed;
+}
+function asNonNegativeInt(value) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`Invalid non-negative integer value: ${value}`);
+    }
+    return parsed;
+}
+function normalizeEndpoint(endpoint) {
+    return endpoint.replace(/\/+$/, "");
+}
+function parseHeaderValue(input) {
+    const idx = input.indexOf(":");
+    if (idx <= 0) {
+        throw new Error(`Invalid --header value "${input}". Expected "Key: Value".`);
+    }
+    const key = input.slice(0, idx).trim();
+    const value = input.slice(idx + 1).trim();
+    if (!key)
+        throw new Error(`Invalid --header value "${input}". Header key is empty.`);
+    return [key, value];
+}
+function parseJsonObject(input, label) {
+    let parsed;
+    try {
+        parsed = JSON.parse(input);
+    }
+    catch (err) {
+        throw new Error(`${label} must be valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`${label} must be a JSON object`);
+    }
+    return parsed;
+}
+function parseJsonRecord(input, label) {
+    const obj = parseJsonObject(input, label);
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (typeof v !== "string") {
+            throw new Error(`${label} must contain string values only (invalid key: ${k})`);
+        }
+        out[k] = v;
+    }
+    return out;
+}
+function isLogLevel(value) {
+    return value === "debug" || value === "info" || value === "warn" || value === "error";
+}
+function isLogFormat(value) {
+    return value === "text" || value === "json";
+}
+function resolveLogLevel(opts) {
+    if (opts.debug)
+        return "debug";
+    if (opts.verbose)
+        return "info";
+    if (opts.quiet)
+        return "error";
+    if (opts.logLevel && isLogLevel(opts.logLevel))
+        return opts.logLevel;
+    return DEFAULT_LOG_LEVEL;
+}
+function resolveLogFormat(opts) {
+    if (opts.logFormat && isLogFormat(opts.logFormat))
+        return opts.logFormat;
+    return "text";
+}
+function shouldLog(ctx, level) {
+    return LOG_PRIORITIES[level] >= LOG_PRIORITIES[ctx.logLevel];
+}
+function maskHeaderValue(key, value) {
+    const lower = key.toLowerCase();
+    if (lower.includes("authorization") ||
+        lower.includes("api-key") ||
+        lower.includes("token") ||
+        lower.includes("cookie") ||
+        lower.includes("session")) {
+        return "***";
+    }
+    return value;
+}
+const SENSITIVE_JSON_KEY_RE = /(authorization|api[_-]?key|token|secret|password|cookie|session|value)/i;
+function redactJsonForDebug(input) {
+    if (Array.isArray(input)) {
+        return input.map((item) => redactJsonForDebug(item));
+    }
+    if (!input || typeof input !== "object") {
+        return input;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (SENSITIVE_JSON_KEY_RE.test(key)) {
+            out[key] = "***";
+            continue;
+        }
+        out[key] = redactJsonForDebug(value);
+    }
+    return out;
+}
+function logMessage(ctx, level, message) {
+    if (!shouldLog(ctx, level))
+        return;
+    if (ctx.logFormat === "json") {
+        process.stderr.write(`${JSON.stringify({ ts: new Date().toISOString(), level, component: "@tcb-sandbox/cli", message })}\n`);
+        return;
+    }
+    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".');
+    }
+    const value = input.trim().toLowerCase();
+    if (value === "execute")
+        return "execute";
+    if (value === "dry_run" || value === "dryrun")
+        return "dry_run";
+    throw new Error('Invalid bash mode. Supported values: "execute", "dry_run", "dryrun".');
+}
+function ensureSessionId(ctx) {
+    if (!ctx.sessionId) {
+        throw new Error("session-id is required for this command. Pass --session-id or set TCB_SANDBOX_SESSION_ID.");
+    }
+    return ctx.sessionId;
+}
+function buildContext(cmd) {
+    const opts = cmd.optsWithGlobals();
+    const endpoint = opts.endpoint ?? process.env.TCB_SANDBOX_ENDPOINT;
+    if (!endpoint) {
+        throw new Error("endpoint is required. Pass --endpoint or set TCB_SANDBOX_ENDPOINT.");
+    }
+    const sessionId = opts.sessionId ?? process.env.TCB_SANDBOX_SESSION_ID;
+    const headers = {};
+    const headersFromEnv = process.env.TCB_SANDBOX_HEADERS_JSON;
+    if (headersFromEnv) {
+        Object.assign(headers, parseJsonRecord(headersFromEnv, "TCB_SANDBOX_HEADERS_JSON"));
+    }
+    for (const raw of opts.header ?? []) {
+        const [key, value] = parseHeaderValue(raw);
+        headers[key] = value;
+    }
+    if (sessionId &&
+        !Object.keys(headers).some((k) => k.toLowerCase() === "x-cloudbase-session-id")) {
+        headers["X-Cloudbase-Session-Id"] = sessionId;
+    }
+    return {
+        endpoint: normalizeEndpoint(endpoint ?? ""),
+        sessionId,
+        headers,
+        output: opts.output ?? "pretty",
+        timeout: opts.timeout ?? DEFAULT_TIMEOUT,
+        logLevel: resolveLogLevel(opts),
+        logFormat: resolveLogFormat(opts),
+    };
+}
+function createSdkClientFromContext(ctx) {
+    return new TcbSandboxClient({
+        baseUrl: ctx.endpoint,
+        cloudbaseSessionId: ctx.sessionId,
+        headers: ctx.headers,
+        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`);
+}
+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) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    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);
+    const response = await client.preview.url({
+        port,
+        endpoint: ctx.endpoint,
+        includeSessionQuery: Boolean(ctx.sessionId),
+    });
+    const result = "data" in response ? response.data : response;
+    const resultRecord = result;
+    const innerResult = resultRecord?.result;
+    const previewUrl = typeof innerResult?.previewUrl === "string" ? innerResult.previewUrl : "";
+    if (!previewUrl) {
+        throw new Error("preview-service.url returned invalid previewUrl");
+    }
+    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;
+    if (platform === "darwin") {
+        await new Promise((resolve, reject) => {
+            const child = spawn("open", [url], { stdio: "ignore" });
+            child.once("error", reject);
+            child.once("close", (code) => code === 0 ? resolve() : reject(new Error(`open exited ${code}`)));
+        });
+        return;
+    }
+    if (platform === "win32") {
+        await new Promise((resolve, reject) => {
+            const child = spawn("cmd", ["/c", "start", "", url], { stdio: "ignore" });
+            child.once("error", reject);
+            child.once("close", (code) => code === 0 ? resolve() : reject(new Error(`cmd start exited ${code}`)));
+        });
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        const child = spawn("xdg-open", [url], { stdio: "ignore" });
+        child.once("error", reject);
+        child.once("close", (code) => code === 0 ? resolve() : reject(new Error(`xdg-open exited ${code}`)));
+    });
+}
+async function main() {
+    const program = new Command();
+    program
+        .name("tcb-sandbox")
+        .description("Thin CLI client for tcb-remote-workspace HTTP API.")
+        .option("-e, --endpoint <url>", "TRW endpoint URL. Env: TCB_SANDBOX_ENDPOINT")
+        .option("-s, --session-id <id>", "Session id. Env: TCB_SANDBOX_SESSION_ID")
+        .option("-H, --header <header...>", 'Extra HTTP header, repeatable. Example: -H "X-Trace-Id: 1"')
+        .option("-o, --output <format>", "Output format: json | pretty", "pretty")
+        .option("--timeout <ms>", "HTTP timeout in milliseconds", asInt, DEFAULT_TIMEOUT)
+        .option("--log-level <level>", "debug | info | warn | error", DEFAULT_LOG_LEVEL)
+        .option("--log-format <format>", "text | json", "text")
+        .option("--verbose", "Enable info logs (stderr)")
+        .option("--debug", "Enable debug logs (stderr)")
+        .option("--quiet", "Only show errors (stderr)")
+        .showHelpAfterError();
+    program.addHelpText("after", `
+Quick Start
+  tcb-sandbox serve    # alias: local — embedded TRW on loopback
+  tcb-sandbox --endpoint http://127.0.0.1:9000 health
+  tcb-sandbox --endpoint http://127.0.0.1:9000 docs
+  tcb-sandbox --endpoint http://127.0.0.1:9000 --session-id demo tools call read --param path=README.md
+
+Error Handling
+  HTTP failures are parsed as RFC 9457 problem details when available.
+  Use --debug to inspect request/response metadata.
+`);
+    program
+        .command("serve")
+        .alias("local")
+        .description("Run embedded tcb-remote-workspace locally (multi-session; X-Cloudbase-Session-Id; no auth).")
+        .option("--port <n>", "Listen port", "9000")
+        .option("--host <addr>", "Bind address (use 0.0.0.0 for all interfaces)", "127.0.0.1")
+        .option("--workspace-root <path>", "Parent directory; each session is a subdirectory by session id", defaultWorkspaceRoot())
+        .action(async function (opts) {
+        const port = asInt(opts.port);
+        const workspaceRoot = path.resolve(opts.workspaceRoot);
+        const code = await runServe({
+            host: opts.host,
+            port,
+            workspaceRoot,
+        });
+        process.exit(code === null ? 0 : code);
+    });
+    program
+        .command("health")
+        .description("Call GET /health")
+        .action(async function () {
+        const ctx = buildContext(this);
+        logMessage(ctx, "info", "GET /health");
+        const client = createSdkClientFromContext(ctx);
+        const body = await client.system.health();
+        const result = "data" in body ? body.data : body;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Health", result);
+    });
+    program
+        .command("docs")
+        .description("Call GET /api/docs (machine-readable API spec)")
+        .action(async function () {
+        const ctx = buildContext(this);
+        logMessage(ctx, "info", "GET /api/docs");
+        const client = createSdkClientFromContext(ctx);
+        let docs;
+        try {
+            const response = await client.system.apiDocs();
+            docs = ("data" in response ? response.data : response);
+        }
+        catch (err) {
+            logMessage(ctx, "warn", "GET /api/docs unavailable, using bundled fallback docs");
+            docs = BUNDLED_API_DOCS;
+        }
+        if (ctx.output === "json")
+            return printJson(docs);
+        printPretty("API Docs", docs);
+    });
+    program
+        .command("read <path>")
+        .description("Read file contents")
+        .option("--offset <n>", "Start line (1-indexed)", asInt)
+        .option("--limit <n>", "Max lines", asInt)
+        .action(async function (path, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/read");
+        const response = await client.fileOperations.read({
+            path,
+            offset: options.offset,
+            limit: options.limit,
+        });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Read", result);
+    });
+    program
+        .command("write <path>")
+        .description("Create or overwrite a file")
+        .option("--content <text>", "File content")
+        .option("--content-stdin", "Read content from stdin")
+        .action(async function (path, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        const content = options.contentStdin
+            ? (await readFromStdin()).trimEnd()
+            : (options.content ?? "");
+        logMessage(ctx, "info", "POST /api/tools/write");
+        const response = await client.fileOperations.write({ path, content });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Write", result);
+    });
+    program
+        .command("edit <path>")
+        .description("Apply a targeted string replacement in a file")
+        .option("--old <text>", "String to replace")
+        .option("--new <text>", "Replacement string")
+        .option("--replace-all", "Replace all matches", false)
+        .action(async function (path, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        if (options.old === undefined || options.new === undefined) {
+            throw new Error("--old and --new are required");
+        }
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/edit");
+        const response = await client.fileOperations.edit({
+            path,
+            oldString: options.old,
+            newString: options.new,
+            replaceAll: options.replaceAll,
+        });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Edit", result);
+    });
+    program
+        .command("bash <command>")
+        .description("Execute a shell command in the session workspace")
+        .option("--timeout <ms>", "Execution timeout in milliseconds", asInt)
+        .option("--cwd <dir>", "Working directory")
+        .option("--mode <mode>", "execute | dry_run")
+        .action(async function (command, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/bash");
+        const bashRequest = {
+            command,
+            timeout: options.timeout,
+            cwd: options.cwd,
+            mode: options.mode ? normalizeBashModeValue(options.mode) : undefined,
+        };
+        const response = await client.execution.bash(bashRequest);
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Bash", result);
+    });
+    program
+        .command("grep <pattern>")
+        .description("Search file contents by regex pattern")
+        .option("--path <dir>", "Directory to search in")
+        .option("--include <glob>", "File glob filter, e.g. '*.ts'")
+        .option("--glob <glob>", "Alias for --include")
+        .option("--case-sensitive", "Enable case-sensitive matching", false)
+        .option("--limit <n>", "Max matches", asInt)
+        .option("--offset <n>", "Skip first N file results", asNonNegativeInt)
+        .action(async function (pattern, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        const effectiveGlob = options.include ?? options.glob;
+        logMessage(ctx, "info", "POST /api/tools/grep");
+        const grepRequest = {
+            pattern,
+            path: options.path,
+            include: effectiveGlob,
+            caseSensitive: options.caseSensitive,
+            limit: options.limit,
+            offset: options.offset,
+        };
+        const response = await client.search.grep(grepRequest);
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Grep", result);
+    });
+    program
+        .command("glob <pattern>")
+        .description("Find files by name/path glob pattern")
+        .option("--path <dir>", "Search root path")
+        .option("--ignore <pattern...>", "Ignore patterns, repeatable")
+        .action(async function (pattern, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/glob");
+        const globRequest = {
+            pattern,
+            path: options.path,
+            ignore: options.ignore,
+        };
+        const response = await client.search.glob(globRequest);
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Glob", result);
+    });
+    program
+        .command("ls [path]")
+        .description("List directory contents")
+        .option("--ignore <pattern...>", "Ignore patterns, repeatable")
+        .action(async function (path, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/ls");
+        const response = await client.search.ls({
+            path,
+            ignore: options.ignore,
+        });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Ls", result);
+    });
+    program
+        .command("batch")
+        .description("Execute multiple tool calls in one request")
+        .option("--data <json>", "JSON array of tool calls")
+        .option("--param <key=value...>", "Key/value entry, repeatable (merged into each call)")
+        .action(async function (options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        const payload = options.data ? parseJsonObject(options.data, "--data") : { tool_calls: [] };
+        logMessage(ctx, "info", "POST /api/tools/batch");
+        const batchRequest = {
+            tool_calls: payload.tool_calls || [],
+        };
+        const response = await client.execution.batch(batchRequest);
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Batch", result);
+    });
+    program
+        .command("git-push <message>")
+        .description("Push a workspace snapshot to a remote git repository")
+        .action(async function (message) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/git_push");
+        const response = await client.git.push({ message });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Git Push", result);
+    });
+    program
+        .command("mcporter <command...>")
+        .description("mcporter CLI — pass full command line as arguments")
+        .action(async function (command, _options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        const cmdStr = command.join(" ");
+        logMessage(ctx, "info", "POST /api/tools/mcporter_cli");
+        const response = await client.mcpServerManagement.mcporterCli({ command: cmdStr });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Mcporter CLI", result);
+    });
+    program
+        .command("add-mcp-servers")
+        .description("Add one or more stdio MCP servers to session mcporter config (idempotent)")
+        .option("--data <json>", "Full JSON payload (supports mcpServers object, or bare fields)")
+        .option("--server-name <name>", "Server name")
+        .option("--command <cmd>", "Executable path or command")
+        .option("--args <args...>", "Command arguments, repeatable")
+        .option("--env <key=val...>", "Environment variables, repeatable")
+        .action(async function (options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        let payload;
+        if (options.data) {
+            payload = parseJsonObject(options.data, "--data");
+        }
+        else if (options.serverName && options.command) {
+            payload = { serverName: options.serverName, command: options.command };
+            if (options.args)
+                payload.args = options.args;
+            if (options.env) {
+                const envMap = {};
+                for (const e of options.env) {
+                    const idx = e.indexOf("=");
+                    if (idx <= 0)
+                        throw new Error(`Invalid --env "${e}". Expected KEY=VALUE.`);
+                    envMap[e.slice(0, idx)] = e.slice(idx + 1);
+                }
+                payload.env = envMap;
+            }
+        }
+        else {
+            throw new Error("--data or (--server-name + --command) is required");
+        }
+        const client = createSdkClientFromContext(ctx);
+        const response = await client.mcpServerManagement.addMcpServers(payload);
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Add MCP Servers", result);
+    });
+    program
+        .command("remove-mcp-servers")
+        .description("Remove one or more MCP servers from session mcporter config")
+        .option("--data <json>", "Full JSON payload (serverNames array or bare serverName)")
+        .option("--server-name <name>", "Single server name to remove")
+        .option("--server-names <names...>", "Multiple server names to remove, repeatable")
+        .action(async function (options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        let payload;
+        if (options.data) {
+            payload = parseJsonObject(options.data, "--data");
+        }
+        else if (options.serverNames && options.serverNames.length > 0) {
+            payload = { serverNames: options.serverNames };
+        }
+        else if (options.serverName) {
+            payload = { serverName: options.serverName };
+        }
+        else {
+            throw new Error("--data, --server-name, or --server-names is required");
+        }
+        logMessage(ctx, "info", "POST /api/tools/remove_mcp_servers");
+        const response = await client.mcpServerManagement.removeMcpServers(payload);
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Remove MCP Servers", result);
+    });
+    program
+        .command("list-mcp-servers")
+        .description("List configured MCP server names in session mcporter")
+        .action(async function () {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/list_mcp_servers");
+        const response = await client.mcpServerManagement.listMcpServers();
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("List MCP Servers", result);
+    });
+    program
+        .command("capability-list")
+        .description("List all capabilities in the current session")
+        .option("--reveal-paths", "Include absolute paths for skill packages", false)
+        .action(async function (options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/capability_list");
+        const response = await client.capabilitySystem.capabilityList({ revealPaths: options.revealPaths });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Capability List", result);
+    });
+    program
+        .command("capability-describe <id>")
+        .description("Describe a single capability (executionBy / executionVia / actions / schema)")
+        .action(async function (id) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/capability_describe");
+        const response = await client.capabilitySystem.capabilityDescribe({ id });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Capability Describe", result);
+    });
+    program
+        .command("capability-install <id>")
+        .description("Get installation guidance for a capability (instruction-only, no registry change)")
+        .option("--kind <kind>", "Capability kind: mcp | cli | skill")
+        .option("--server-name <name>", "MCP server name (required when kind=mcp)")
+        .option("--command <cmd>", "Executable path")
+        .option("--package-path <path>", "Skill package path")
+        .option("--entry-file <file>", "Skill entry file, default SKILL.md")
+        .action(async function (id, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/capability_install");
+        const installRequest = {
+            id,
+            kind: options.kind,
+            serverName: options.serverName,
+            command: options.command,
+            packagePath: options.packagePath,
+            entryFile: options.entryFile,
+        };
+        const response = await client.capabilitySystem.capabilityInstall(installRequest);
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Capability Install", result);
+    });
+    program
+        .command("capability-register <id>")
+        .description("Register a capability into the session (after external installation)")
+        .option("--kind <kind>", "Capability kind: mcp | cli | skill")
+        .option("--server-name <name>", "MCP server name (required when kind=mcp)")
+        .option("--command <cmd>", "Executable path")
+        .option("--args <args...>", "Command arguments, repeatable")
+        .option("--package-path <path>", "Skill package path")
+        .option("--entry-file <file>", "Skill entry file, default SKILL.md")
+        .action(async function (id, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/capability_register");
+        if (!options.kind) {
+            throw new Error("--kind is required (mcp | cli | skill)");
+        }
+        const registerRequest = {
+            id,
+            kind: options.kind,
+            serverName: options.serverName,
+            command: options.command,
+            args: options.args,
+            packagePath: options.packagePath,
+            entryFile: options.entryFile,
+        };
+        const response = await client.capabilitySystem.capabilityRegister(registerRequest);
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Capability Register", result);
+    });
+    program
+        .command("capability-remove <id>")
+        .description("Remove a registered capability (built-in capabilities cannot be removed)")
+        .action(async function (id) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/capability_remove");
+        const response = await client.capabilitySystem.capabilityRemove({ id });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Capability Remove", result);
+    });
+    program
+        .command("capability-invoke <id> <action>")
+        .description("Invoke a native capability action (secrets-store / files-transfer / preview-service / pty-service / git-archive)")
+        .option("--parameters <json>", "Action parameters as JSON string")
+        .action(async function (id, action, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        const parameters = options.parameters
+            ? parseJsonObject(options.parameters, "--parameters")
+            : {};
+        logMessage(ctx, "info", "POST /api/tools/capability_invoke");
+        const response = await client.capabilitySystem.capabilityInvoke({ id, action, parameters });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Capability Invoke", result);
+    });
+    const snapshot = program
+        .command("snapshot")
+        .description("Workspace snapshot and restore (S3-backed)");
+    snapshot
+        .command("create")
+        .description("Create async workspace snapshot and upload to S3")
+        .option("--exclude <patterns...>", "Additional exclude patterns")
+        .option("--include-all", "Skip default excludes (only sensitive files still excluded)")
+        .action(async function (options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/workspace_snapshot");
+        const response = await client.other.workspaceSnapshot({
+            exclude: options.exclude,
+            include_all: options.includeAll,
+        });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Snapshot Create", result);
+    });
+    snapshot
+        .command("status [snapshotId]")
+        .description("Check snapshot status (single or all session tasks)")
+        .action(async function (snapshotId) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/workspace_snapshot_status");
+        const response = await client.other.workspaceSnapshotStatus({
+            snapshot_id: snapshotId,
+        });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Snapshot Status", result);
+    });
+    snapshot
+        .command("restore <snapshotId>")
+        .description("Restore workspace from snapshot (supports cross-session)")
+        .option("--mode <mode>", 'Restore mode: "merge" (default) or "replace"', "merge")
+        .action(async function (snapshotId, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/workspace_restore");
+        const response = await client.other.workspaceRestore({
+            snapshot_id: snapshotId,
+            mode: options.mode,
+        });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Snapshot Restore", result);
+    });
+    const secrets = program.command("secrets").description("Secrets helpers (session-scoped)");
+    secrets
+        .command("set <key>")
+        .description("Set or overwrite a secret")
+        .option("--value <value>", "Secret value")
+        .option("--value-stdin", "Read secret value from stdin")
+        .action(async function (key, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        const byArg = options.value;
+        const byStdin = options.valueStdin ? (await readFromStdin()).trimEnd() : undefined;
+        const value = byStdin ?? byArg;
+        if (value === undefined) {
+            throw new Error("Missing value. Use --value <value> or --value-stdin.");
+        }
+        logMessage(ctx, "info", "POST /api/tools/secrets_set");
+        const secretsRequest = { key, value };
+        if (shouldLog(ctx, "debug")) {
+            logMessage(ctx, "debug", `request json: ${JSON.stringify(redactJsonForDebug(secretsRequest))}`);
+        }
+        const response = await client.secrets.set(secretsRequest);
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Secret Set", result);
+    });
+    secrets
+        .command("get <key>")
+        .description("Get plaintext secret value")
+        .action(async function (key) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/secrets_get");
+        const response = await client.secrets.get({ key });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Secret Get", result);
+    });
+    secrets
+        .command("list")
+        .description("List secret keys (without plaintext values)")
+        .action(async function () {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/secrets_list");
+        const response = await client.secrets.list();
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Secret List", result);
+    });
+    secrets
+        .command("delete <key>")
+        .description("Delete a secret by key")
+        .action(async function (key) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/secrets_delete");
+        const response = await client.secrets.delete({ key });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Secret Delete", result);
+    });
+    const files = program.command("files").description("Binary file upload/download");
+    files
+        .command("upload <localPath> <remotePath>")
+        .description("Upload local file via top-level files_upload tool")
+        .action(async function (localPath, remotePath) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        const full = path.resolve(localPath);
+        const content = await fs.readFile(full);
+        logMessage(ctx, "info", "POST /api/tools/files_upload");
+        const response = await client.fileOperations.filesUpload({
+            path: remotePath,
+            contentBase64: content.toString("base64"),
+        });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("File Upload", result);
+    });
+    files
+        .command("download <remotePath> <localPath>")
+        .description("Download remote file via top-level files_download tool")
+        .action(async function (remotePath, localPath) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/files_download");
+        const response = await client.fileOperations.filesDownload({ path: remotePath });
+        const result = "data" in response ? response.data : response;
+        const resultRecord = result;
+        const innerResult = resultRecord?.result;
+        const contentBase64 = typeof innerResult?.contentBase64 === "string" ? innerResult.contentBase64 : "";
+        if (!contentBase64) {
+            throw new Error("files-transfer.download returned empty contentBase64");
+        }
+        const buffer = Buffer.from(contentBase64, "base64");
+        const full = path.resolve(localPath);
+        await fs.mkdir(path.dirname(full), { recursive: true });
+        await fs.writeFile(full, buffer);
+        if (ctx.output === "json") {
+            return printJson({ success: true, path: full, bytes: buffer.byteLength });
+        }
+        process.stdout.write(`Downloaded ${buffer.byteLength} bytes -> ${full}\n`);
+    });
+    const preview = program.command("preview").description("Preview endpoints");
+    preview
+        .command("ports")
+        .description("List previewable ports via top-level preview_ports tool")
+        .action(async function () {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/preview_ports");
+        const response = await client.preview.ports({
+            endpoint: ctx.endpoint,
+            includeSessionQuery: Boolean(ctx.sessionId),
+        });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("Preview Ports", result);
+    });
+    preview
+        .command("url <port>")
+        .description("Build preview URL for a port")
+        .action(async function (portRaw) {
+        const ctx = buildContext(this);
+        const port = asInt(portRaw);
+        const url = await getPreviewUrl(ctx, port);
+        if (ctx.output === "json") {
+            return printJson({ url, port, sessionIdIncluded: Boolean(ctx.sessionId) });
+        }
+        process.stdout.write(`${url}\n`);
+    });
+    preview
+        .command("open <port>")
+        .description("Open preview URL in default browser")
+        .option("--print-only", "Print URL only, do not open browser")
+        .action(async function (portRaw, options) {
+        const ctx = buildContext(this);
+        const port = asInt(portRaw);
+        const url = await getPreviewUrl(ctx, port);
+        if (options.printOnly) {
+            process.stdout.write(`${url}\n`);
+            return;
+        }
+        await openUrl(url);
+        if (ctx.output === "json") {
+            return printJson({ opened: true, url, port, sessionIdIncluded: Boolean(ctx.sessionId) });
+        }
+        process.stdout.write(`Opened ${url}\n`);
+    });
+    const pty = program.command("pty").description("PTY process helpers");
+    pty
+        .command("create")
+        .description("Create PTY process via top-level pty_create tool")
+        .option("--command <command>", "Command to run")
+        .option("--args <args...>", "Command arguments")
+        .option("--cwd <cwd>", "Working directory (workspace relative or absolute)")
+        .option("--cols <cols>", "Terminal columns")
+        .option("--rows <rows>", "Terminal rows")
+        .action(async function (options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        logMessage(ctx, "info", "POST /api/tools/pty_create");
+        const response = await client.ptyTerminal.ptyCreate({
+            cmd: options.command,
+            args: options.args && options.args.length > 0 ? options.args : undefined,
+            cwd: options.cwd,
+            cols: options.cols !== undefined ? asInt(options.cols) : undefined,
+            rows: options.rows !== undefined ? asInt(options.rows) : undefined,
+        });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("PTY Create", result);
+    });
+    pty
+        .command("send-input <pid>")
+        .description("Send stdin payload to PTY process via top-level pty_send_input tool")
+        .option("--text <text>", "Plain text to send")
+        .option("--text-stdin", "Read plain text from stdin")
+        .option("--base64 <content>", "Base64 payload to send directly")
+        .action(async function (pidRaw, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        const pid = asInt(pidRaw);
+        const textFromStdin = options.textStdin ? await readFromStdin() : undefined;
+        const base64Payload = options.base64 ??
+            (textFromStdin !== undefined
+                ? Buffer.from(textFromStdin, "utf8").toString("base64")
+                : options.text !== undefined
+                    ? Buffer.from(options.text, "utf8").toString("base64")
+                    : undefined);
+        if (!base64Payload) {
+            throw new Error("Missing input payload. Use --text, --text-stdin, or --base64.");
+        }
+        logMessage(ctx, "info", "POST /api/tools/pty_send_input");
+        const response = await client.ptyTerminal.ptySendInput({ pid, inputBase64: base64Payload });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("PTY Send Input", result);
+    });
+    pty
+        .command("kill <pid>")
+        .description("Kill PTY process via top-level pty_kill tool")
+        .option("--signal <signal>", "Signal to use (default: SIGTERM)")
+        .action(async function (pidRaw, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        const pid = asInt(pidRaw);
+        logMessage(ctx, "info", "POST /api/tools/pty_kill");
+        const response = await client.ptyTerminal.ptyKill({ pid, signal: options.signal });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("PTY Kill", result);
+    });
+    pty
+        .command("resize <pid>")
+        .description("Resize PTY process via top-level pty_resize tool")
+        .requiredOption("--cols <cols>", "Terminal columns")
+        .requiredOption("--rows <rows>", "Terminal rows")
+        .action(async function (pidRaw, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        const pid = asInt(pidRaw);
+        const cols = asInt(options.cols);
+        const rows = asInt(options.rows);
+        logMessage(ctx, "info", "POST /api/tools/pty_resize");
+        const response = await client.ptyTerminal.ptyResize({ pid, cols, rows });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("PTY Resize", result);
+    });
+    pty
+        .command("read-output <pid>")
+        .description("Read buffered PTY output via top-level pty_read_output tool")
+        .option("--after-seq <seq>", "Read events strictly after this sequence")
+        .option("--limit <limit>", "Max number of events to read")
+        .action(async function (pidRaw, options) {
+        const ctx = buildContext(this);
+        ensureSessionId(ctx);
+        const client = createSdkClientFromContext(ctx);
+        const pid = asInt(pidRaw);
+        logMessage(ctx, "info", "POST /api/tools/pty_read_output");
+        const response = await client.ptyTerminal.ptyReadOutput({
+            pid,
+            afterSeq: options.afterSeq !== undefined ? asNonNegativeInt(options.afterSeq) : undefined,
+            limit: options.limit !== undefined ? asInt(options.limit) : undefined,
+        });
+        const result = "data" in response ? response.data : response;
+        if (ctx.output === "json")
+            return printJson(result);
+        printPretty("PTY Read Output", result);
+    });
+    await program.parseAsync(process.argv);
+}
+main().catch((err) => {
+    process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});