@sanlabs/sanbox-cli 0.0.1 → 0.0.4

package/dist/config.js

@@ -1,12 +1,60 @@
-export const defaultApiUrl = "http://127.0.0.1:8788";
-export const defaultWorkloadId = "opencode-runner";
-export const readConfig = (flags = {}) => {
-    const apiUrl = String(flags["api-url"] || process.env.SANBOX_API_URL || defaultApiUrl).replace(/\/+$/, "");
-    const org = String(flags.org || process.env.SANBOX_ORG || "").trim();
+import fs from "node:fs";
+import path from "node:path";
+import { CliError, commandAction } from "./errors.js";
+export const defaultApiUrl = "https://console.sanbox.cloud";
+export const readLocalConfig = (cwd = process.cwd()) => {
+    const configPath = path.join(cwd, ".sanbox", "config.json");
+    try {
+        const parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const record = parsed;
+        return {
+            api_url: typeof record.api_url === "string" ? record.api_url : undefined,
+            org: typeof record.org === "string" ? record.org : undefined,
+            default_template: typeof record.default_template === "string" ? record.default_template : undefined
+        };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+};
+export const readConfig = (flags = {}, options = {}) => {
+    const localConfig = readLocalConfig();
+    const apiUrl = String(flags["api-url"] || process.env.SANBOX_API_URL || localConfig.api_url || defaultApiUrl).replace(/\/+$/, "");
+    const org = String(flags.org || process.env.SANBOX_ORG || localConfig.org || "").trim();
     const apiKey = process.env.SANBOX_API_KEY || "";
-    if (!org)
-        throw new Error("SANBOX_ORG or --org is required.");
-    if (!apiKey)
-        throw new Error("SANBOX_API_KEY is required.");
+    if (options.requireOrg !== false && !org) {
+        throw new CliError("org_required", "Organization context is required.", {
+            nextActions: [commandAction(["sanbox", "context", "--json"], "Select an organization and retry with SANBOX_ORG set.", { SANBOX_ORG: "<org-slug>" })]
+        });
+    }
+    if (!apiKey) {
+        throw new CliError("api_key_required", "SANBOX_API_KEY is required.", {
+            nextActions: [commandAction(["sanbox", "auth", "check", "--json"], "Set a Sanbox control-plane API key and check access.", { SANBOX_API_KEY: "<sanbox-api-key>" })]
+        });
+    }
     return { apiUrl, org, apiKey };
 };
+export function readTemplateSelection(flags = {}, options = {}) {
+    const flagValue = flags.template;
+    if (typeof flagValue === "string" && flagValue.trim())
+        return { id: flagValue.trim(), source: "flag" };
+    const envValue = process.env.SANBOX_TEMPLATE?.trim();
+    if (envValue)
+        return { id: envValue, source: "environment" };
+    const configValue = readLocalConfig(options.cwd).default_template?.trim();
+    if (configValue)
+        return { id: configValue, source: "project_config" };
+    if (options.required === false)
+        return null;
+    throw new CliError("template_required", "A template must be selected explicitly.", {
+        nextActions: [
+            commandAction(["sanbox", "templates", "list", "--json"], "List templates available to the selected organization."),
+            commandAction(["sanbox", "run", "<task>", "--template", "<template-id>"], "Run with an explicit template."),
+            commandAction(["sanbox", "context", "--json"], "Select a template for this shell and inspect the resolved context.", { SANBOX_TEMPLATE: "<template-id>" })
+        ]
+    });
+}

package/dist/errors.js

@@ -0,0 +1,24 @@
+export class CliError extends Error {
+    code;
+    options;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.code = code;
+        this.options = options;
+        this.name = "CliError";
+    }
+    get exitCode() {
+        return this.options.exitCode ?? 1;
+    }
+}
+export const commandAction = (argv, description, env) => ({
+    type: "command",
+    argv,
+    ...(env ? { env } : {}),
+    description
+});
+export const consoleAction = (url, description) => ({
+    type: "console",
+    url,
+    description
+});

package/dist/inputs.js

@@ -0,0 +1,150 @@
+import crypto from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import fg from "fast-glob";
+import ignore from "ignore";
+import yazl from "yazl";
+const maximumInputBytes = 64 * 1024 * 1024;
+const maximumInputFiles = 10_000;
+const defaultIgnorePatterns = [
+    ".git/**",
+    "**/.git/**",
+    "node_modules/**",
+    "**/node_modules/**",
+    "dist/**",
+    "**/dist/**",
+    "build/**",
+    "**/build/**",
+    "coverage/**",
+    "**/coverage/**",
+    ".next/**",
+    "**/.next/**",
+    ".turbo/**",
+    "**/.turbo/**",
+    ".env",
+    ".env.*",
+    "**/.env",
+    "**/.env.*",
+    "**/*secret*",
+    "**/*Secret*",
+    "**/*token*",
+    "**/*Token*",
+    "**/*credential*",
+    "**/*Credential*",
+    "**/*.pem",
+    "**/*.key",
+    "**/id_rsa",
+    "**/id_ed25519"
+];
+const normalizePattern = async (cwd, pattern) => {
+    const slashPattern = pattern.replaceAll(path.sep, "/");
+    const normalizedPath = path.posix.normalize(slashPattern);
+    if (path.isAbsolute(pattern) || normalizedPath === ".." || normalizedPath.startsWith("../")) {
+        throw new Error(`Input path must be relative to the current directory: ${pattern}`);
+    }
+    if (pattern === ".")
+        return "**/*";
+    const normalized = normalizedPath.replace(/\/+$/, "");
+    if (normalized.includes("*"))
+        return normalized;
+    try {
+        const stat = await fs.stat(path.resolve(cwd, normalized));
+        if (stat.isDirectory())
+            return `${normalized}/**`;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    return normalized;
+};
+const readSanboxIgnore = async (cwd) => {
+    try {
+        const raw = await fs.readFile(path.join(cwd, ".sanboxignore"), "utf8");
+        return raw.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith("#"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+};
+const selectedInputs = async (cwd, inputs) => {
+    const patterns = await Promise.all(inputs.map((input) => normalizePattern(cwd, input)));
+    const ignored = ignore().add([...defaultIgnorePatterns, ...(await readSanboxIgnore(cwd))]);
+    const candidates = await fg(patterns, {
+        cwd,
+        dot: true,
+        onlyFiles: true,
+        followSymbolicLinks: false,
+        unique: true
+    });
+    const normalizedCandidates = candidates
+        .map((item) => item.replaceAll(path.sep, "/"))
+        .filter((item) => !item.startsWith("../") && !path.isAbsolute(item))
+        .filter((item) => !ignored.ignores(item))
+        .sort();
+    const files = [];
+    for (const item of normalizedCandidates) {
+        const stat = await fs.lstat(path.join(cwd, item));
+        if (stat.isFile())
+            files.push(item);
+    }
+    return { patterns, files };
+};
+const zipToBuffer = async (zip) => new Promise((resolve, reject) => {
+    const chunks = [];
+    zip.outputStream.on("data", (chunk) => chunks.push(chunk));
+    zip.outputStream.on("error", reject);
+    zip.outputStream.on("end", () => resolve(Buffer.concat(chunks)));
+    zip.end();
+});
+export const sha256 = (buffer) => crypto.createHash("sha256").update(buffer).digest("hex");
+export const previewInputs = async (input) => {
+    const { patterns, files } = await selectedInputs(input.cwd, input.inputs);
+    const previewFiles = [];
+    let totalBytes = 0;
+    for (const relative of files) {
+        const stat = await fs.stat(path.join(input.cwd, relative));
+        if (!stat.isFile())
+            continue;
+        totalBytes += stat.size;
+        previewFiles.push({ path: relative, size: stat.size });
+    }
+    return { patterns, files: previewFiles, totalBytes };
+};
+export const buildInputBundle = async (input) => {
+    const { files } = await selectedInputs(input.cwd, input.inputs);
+    if (files.length === 0)
+        throw new Error("No files matched the supplied --input values.");
+    if (files.length > maximumInputFiles)
+        throw new Error(`Inputs exceed the ${maximumInputFiles}-file limit.`);
+    const zip = new yazl.ZipFile();
+    const metadata = [];
+    let totalBytes = 0;
+    for (const relative of files) {
+        const absolute = path.join(input.cwd, relative);
+        const file = await fs.open(absolute, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile())
+                continue;
+            if (totalBytes + stat.size > maximumInputBytes)
+                throw new Error("Inputs exceed the 64 MiB uncompressed limit.");
+            const content = await file.readFile();
+            totalBytes += content.byteLength;
+            if (totalBytes > maximumInputBytes)
+                throw new Error("Inputs exceed the 64 MiB uncompressed limit.");
+            metadata.push({ path: relative, size: content.byteLength, sha256: sha256(content) });
+            zip.addBuffer(content, `input/${relative}`, { mode: stat.mode });
+        }
+        finally {
+            await file.close();
+        }
+    }
+    const buffer = await zipToBuffer(zip);
+    if (buffer.byteLength > maximumInputBytes)
+        throw new Error("Inputs exceed the 64 MiB upload limit.");
+    return { buffer, sha256: sha256(buffer), files: metadata };
+};

package/dist/output.js

@@ -1,9 +1,85 @@
+import { CliError } from "./errors.js";
+import { SanboxApiError } from "./api.js";
 export const printJson = (value) => {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 };
+export const successEnvelope = (command, data, context = {}, nextActions = []) => ({
+    schema_version: 1,
+    ok: true,
+    command,
+    context,
+    data,
+    next_actions: nextActions
+});
+export const errorEnvelope = (command, error, context = {}) => {
+    if (error instanceof CliError) {
+        return {
+            schema_version: 1,
+            ok: false,
+            command,
+            context,
+            error: {
+                code: error.code,
+                message: error.message,
+                ...(error.options.status === undefined ? {} : { status: error.options.status }),
+                ...(error.options.details === undefined ? {} : { details: error.options.details })
+            },
+            next_actions: error.options.nextActions ?? []
+        };
+    }
+    if (error instanceof SanboxApiError) {
+        return {
+            schema_version: 1,
+            ok: false,
+            command,
+            context,
+            error: {
+                code: error.code,
+                message: error.message,
+                status: error.status
+            },
+            next_actions: []
+        };
+    }
+    return {
+        schema_version: 1,
+        ok: false,
+        command,
+        context,
+        error: {
+            code: "cli_error",
+            message: error instanceof Error ? error.message : String(error)
+        },
+        next_actions: []
+    };
+};
+export const printSuccess = (command, data, context = {}, nextActions = []) => printJson(successEnvelope(command, data, context, nextActions));
+export const printError = (command, error, context = {}) => {
+    process.stderr.write(`${JSON.stringify(errorEnvelope(command, error, context), null, 2)}\n`);
+};
+export const printJsonlError = (command, error, context = {}) => {
+    process.stderr.write(`${JSON.stringify(errorEnvelope(command, error, context))}\n`);
+};
+export const publicRun = (run) => {
+    const { workload_id: workloadId, ...rest } = run;
+    return {
+        ...rest,
+        template_id: run.template_id || workloadId || null
+    };
+};
+export const publicRunPayload = (payload) => ({
+    run: publicRun(payload.run),
+    events: payload.events
+});
 export const summarizeRun = (payload) => {
     const { run } = payload;
-    return `${run.id} ${run.status}${run.exit_code === null ? "" : ` exit=${run.exit_code}`}${run.error ? ` error=${run.error}` : ""}`;
+    const templateId = run.template_id || run.workload_id;
+    const selection = [
+        templateId ? `template=${templateId}` : "",
+        run.provider_id ? `provider=${run.provider_id}` : "",
+        run.model_id ? `model=${run.model_id}` : ""
+    ].filter(Boolean).join(" ");
+    return `${run.id} ${run.status}${selection ? ` ${selection}` : ""}${run.exit_code === null ? "" : ` exit=${run.exit_code}`}${run.error ? ` error=${run.error}` : ""}`;
 };
 export const printRun = (payload) => {
     process.stdout.write(`${summarizeRun(payload)}\n`);

package/dist/runs.js

@@ -1,10 +1,8 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { defaultWorkloadId } from "./config.js";
-import { buildTaskDossier, readDossierFile } from "./dossier.js";
+import { buildInputBundle } from "./inputs.js";
 const terminalStatuses = new Set(["completed", "failed", "canceled", "expired"]);
-const inlineLimitBytes = 8 * 1024 * 1024;
 export const isTerminalRun = (run) => terminalStatuses.has(run.status);
 export const waitForRun = async (client, runId, options = {}) => {
     const pollIntervalMs = options.pollIntervalMs ?? 2000;
@@ -19,31 +17,21 @@ export const waitForRun = async (client, runId, options = {}) => {
     return payload;
 };
 export const createRun = async (client, options) => {
-    const dossier = options.dossierPath
-        ? await readDossierFile(path.resolve(options.cwd, options.dossierPath))
-        : await buildTaskDossier({
-            cwd: options.cwd,
-            task: options.task || "",
-            include: options.include,
-            cliVersion: options.cliVersion
+    let inputCollectionId;
+    if (options.inputs.length > 0) {
+        const bundle = await buildInputBundle({ cwd: options.cwd, inputs: options.inputs });
+        const uploaded = await client.uploadInputCollection({
+            buffer: bundle.buffer,
+            sha256: bundle.sha256,
+            fileCount: bundle.files.length
         });
-    if (dossier.buffer.byteLength > inlineLimitBytes) {
-        throw new Error(`Dossier is ${dossier.buffer.byteLength} bytes; inline dossier limit is ${inlineLimitBytes} bytes.`);
+        inputCollectionId = uploaded.input_collection.id;
     }
-    const manifest = {
-        dossier: {
-            inline_base64: dossier.buffer.toString("base64"),
-            sha256: dossier.sha256
-        },
-        sanbox_cli: {
-            files: dossier.files,
-            source: options.dossierPath ? "dossier_file" : "generated_task"
-        }
-    };
     return client.createRun({
         external_run_id: options.externalRunId,
-        workload_id: options.workloadId || defaultWorkloadId,
-        manifest,
+        workload_id: options.templateId,
+        instruction: options.instruction,
+        ...(inputCollectionId ? { input_collection_id: inputCollectionId } : {}),
         retention_ttl_seconds: options.retentionTtlSeconds
     });
 };
@@ -65,7 +53,7 @@ export const readTasks = async (tasksPath) => {
         return {
             task,
             external_run_id: record.external_run_id ? String(record.external_run_id) : undefined,
-            include: Array.isArray(record.include) ? record.include.map(String) : undefined
+            input: Array.isArray(record.input) ? record.input.map(String) : undefined
         };
     });
 };

package/dist/version.js

@@ -1 +1 @@
-export const version = "0.0.1";
+export const version = "0.0.4";

package/dist/watch.js

@@ -0,0 +1,170 @@
+import { SanboxApiError } from "./api.js";
+const terminalStatuses = new Set(["completed", "failed", "canceled", "expired"]);
+const terminalEventKinds = new Set(["run.completed", "run.failed", "run.canceled", "run.expired"]);
+const retryableNetworkCodes = new Set(["ECONNRESET", "ECONNREFUSED", "EPIPE", "ETIMEDOUT", "EAI_AGAIN", "ENETUNREACH"]);
+export class WatchInterruptedError extends Error {
+    constructor() {
+        super("Watch interrupted.");
+        this.name = "WatchInterruptedError";
+    }
+}
+const defaultSleep = (milliseconds, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(new WatchInterruptedError());
+        return;
+    }
+    const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+    }, milliseconds);
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(new WatchInterruptedError());
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+});
+const isRetryable = (error) => {
+    if (error instanceof SanboxApiError)
+        return error.status === 429 || error.status >= 500;
+    if (error instanceof TypeError)
+        return true;
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+    return retryableNetworkCodes.has(code);
+};
+const assertActive = (signal, deadline, now, runId) => {
+    if (signal?.aborted)
+        throw new WatchInterruptedError();
+    if (now() >= deadline)
+        throw new Error(`Timed out watching run ${runId}.`);
+};
+export const isTerminalStatus = (status) => terminalStatuses.has(status);
+export const watchEventsUntil = async (client, runId, options) => {
+    const pageSize = Math.max(1, Math.min(500, Math.floor(options.pageSize ?? 200)));
+    const pollIntervalMs = Math.max(1, Math.floor(options.pollIntervalMs ?? 2000));
+    const timeoutSeconds = Math.max(1, options.timeoutSeconds ?? 1800);
+    const maxReconnectDelayMs = Math.max(250, options.maxReconnectDelayMs ?? 10_000);
+    const sleep = options.sleep ?? defaultSleep;
+    const now = options.now ?? Date.now;
+    const random = options.random ?? Math.random;
+    const deadline = now() + timeoutSeconds * 1000;
+    let cursor = Math.max(0, Math.floor(options.afterEventId ?? 0));
+    const request = async (operation) => {
+        let attempt = 0;
+        for (;;) {
+            assertActive(options.signal, deadline, now, runId);
+            try {
+                return await operation();
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    throw new WatchInterruptedError();
+                if (error instanceof WatchInterruptedError || !isRetryable(error))
+                    throw error;
+                attempt += 1;
+                const exponential = Math.min(maxReconnectDelayMs, 250 * (2 ** Math.min(attempt - 1, 8)));
+                const remainingMs = deadline - now();
+                if (remainingMs <= 0)
+                    throw new Error(`Timed out watching run ${runId}.`);
+                const delayMs = Math.min(remainingMs, Math.max(1, Math.floor(exponential * (0.8 + random() * 0.4))));
+                options.onRetry?.({ error, attempt, delayMs });
+                await sleep(delayMs, options.signal);
+            }
+        }
+    };
+    for (;;) {
+        assertActive(options.signal, deadline, now, runId);
+        let delivered = 0;
+        let fetchAnotherPage = true;
+        while (fetchAnotherPage) {
+            const page = await request(() => client.listEvents(runId, cursor, pageSize, options.signal));
+            const previousCursor = cursor;
+            const ordered = [...page.events].sort((left, right) => left.id - right.id);
+            const seen = new Set();
+            for (const event of ordered) {
+                if (!Number.isSafeInteger(event.id) || event.id <= cursor || seen.has(event.id))
+                    continue;
+                seen.add(event.id);
+                await options.onEvent?.(event);
+                cursor = event.id;
+                delivered += 1;
+                if (options.stopWhen(event))
+                    return event;
+            }
+            const reportedMore = page.has_more ?? page.events.length >= pageSize;
+            fetchAnotherPage = reportedMore && cursor > previousCursor;
+        }
+        if (delivered === 0)
+            await sleep(pollIntervalMs, options.signal);
+    }
+};
+export const watchRun = async (client, runId, options) => {
+    const pageSize = Math.max(1, Math.min(500, Math.floor(options.pageSize ?? 200)));
+    const pollIntervalMs = Math.max(1, Math.floor(options.pollIntervalMs ?? 2000));
+    const terminalDrainIntervalMs = Math.max(1, Math.floor(options.terminalDrainIntervalMs ?? Math.min(250, pollIntervalMs)));
+    const timeoutSeconds = Math.max(1, options.timeoutSeconds ?? 1800);
+    const maxReconnectDelayMs = Math.max(250, options.maxReconnectDelayMs ?? 10_000);
+    const sleep = options.sleep ?? defaultSleep;
+    const now = options.now ?? Date.now;
+    const random = options.random ?? Math.random;
+    const deadline = now() + timeoutSeconds * 1000;
+    let cursor = Math.max(0, Math.floor(options.afterEventId ?? 0));
+    let sawTerminalEvent = false;
+    let emptyTerminalReads = 0;
+    const request = async (operation) => {
+        let attempt = 0;
+        for (;;) {
+            assertActive(options.signal, deadline, now, runId);
+            try {
+                return await operation();
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    throw new WatchInterruptedError();
+                if (error instanceof WatchInterruptedError || !isRetryable(error))
+                    throw error;
+                attempt += 1;
+                const exponential = Math.min(maxReconnectDelayMs, 250 * (2 ** Math.min(attempt - 1, 8)));
+                const remainingMs = deadline - now();
+                if (remainingMs <= 0)
+                    throw new Error(`Timed out watching run ${runId}.`);
+                const delayMs = Math.min(remainingMs, Math.max(1, Math.floor(exponential * (0.8 + random() * 0.4))));
+                options.onRetry?.({ error, attempt, delayMs });
+                await sleep(delayMs, options.signal);
+            }
+        }
+    };
+    for (;;) {
+        assertActive(options.signal, deadline, now, runId);
+        let deliveredThisCycle = 0;
+        let fetchAnotherPage = true;
+        while (fetchAnotherPage) {
+            const page = await request(() => client.listEvents(runId, cursor, pageSize, options.signal));
+            const previousCursor = cursor;
+            const ordered = [...page.events].sort((left, right) => left.id - right.id);
+            const seen = new Set();
+            for (const event of ordered) {
+                if (!Number.isSafeInteger(event.id) || event.id <= cursor || seen.has(event.id))
+                    continue;
+                seen.add(event.id);
+                await options.onEvent(event);
+                cursor = event.id;
+                deliveredThisCycle += 1;
+                if (terminalEventKinds.has(event.kind))
+                    sawTerminalEvent = true;
+            }
+            const reportedMore = page.has_more ?? page.events.length >= pageSize;
+            fetchAnotherPage = reportedMore && cursor > previousCursor;
+        }
+        const payload = await request(() => client.getRun(runId, options.signal));
+        if (isTerminalStatus(payload.run.status)) {
+            emptyTerminalReads = deliveredThisCycle === 0 ? emptyTerminalReads + 1 : 0;
+            const requiredEmptyReads = sawTerminalEvent ? 1 : 2;
+            if (emptyTerminalReads >= requiredEmptyReads)
+                return payload;
+            await sleep(terminalDrainIntervalMs, options.signal);
+            continue;
+        }
+        emptyTerminalReads = 0;
+        await sleep(pollIntervalMs, options.signal);
+    }
+};

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@sanlabs/sanbox-cli",
-  "version": "0.0.1",
+  "version": "0.0.4",
   "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sanlabs-ai/sanbox.git",
+    "directory": "cli"
+  },
   "type": "module",
   "bin": {
-    "sanbox": "dist/cli.js",
-    "sanbox-mcp": "dist/mcp.js"
+    "sanbox": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -19,14 +23,13 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "test": "tsx --test test/**/*.test.ts",
     "dev": "tsx src/cli.ts"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.21.0",
     "fast-glob": "^3.3.3",
     "ignore": "^7.0.5",
-    "yazl": "^3.3.1",
-    "zod": "^3.25.76"
+    "yazl": "^3.3.1"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",