@hasna/sandboxes 0.1.27 → 0.1.28

package/README.md

@@ -17,6 +17,29 @@ npm install -g @hasna/sandboxes
 sandboxes --help
 ```
 
+## SDK One-shot Commands
+
+Use the SDK to create a sandbox, upload a local project, run a command, and clean up:
+
+```ts
+import { createSandboxesSDK } from "@hasna/sandboxes";
+
+const sandboxes = createSandboxesSDK();
+
+await sandboxes.runCommandInSandbox({
+  provider: "e2b",
+  command: "bun test",
+  upload: {
+    localDir: process.cwd(),
+    remoteDir: "/workspace/app",
+    syncStrategy: "rsync",
+  },
+  cleanup: "delete",
+});
+```
+
+Set `E2B_API_KEY` for E2B-backed runs. `syncStrategy: "rsync"` mirrors the local directory into a temporary staging tree with `rsync` before uploading it through the provider file APIs.
+
 ## MCP Server
 
 ```bash

package/dist/cli/index.js

@@ -12060,7 +12060,9 @@ var init_config2 = __esm(() => {
 });
 
 // src/lib/archive.ts
-import { existsSync as existsSync7, statSync } from "fs";
+import { existsSync as existsSync7, mkdtempSync, rmSync, statSync } from "fs";
+import { tmpdir } from "os";
+import { join as join8 } from "path";
 function shellQuote(value) {
   return "'" + value.replace(/'/g, "'\\''") + "'";
 }
@@ -12068,6 +12070,15 @@ async function tarDirectory(localDir, opts) {
   if (!existsSync7(localDir) || !statSync(localDir).isDirectory()) {
     throw new Error(`tarDirectory: not a directory: ${localDir}`);
   }
+  if (opts?.syncStrategy === "rsync") {
+    const stagingDir = mkdtempSync(join8(tmpdir(), "sandboxes-rsync-"));
+    try {
+      await rsyncDirectory(localDir, stagingDir, opts.exclude ?? DEFAULT_UPLOAD_EXCLUDES);
+      return await tarDirectory(stagingDir, { exclude: [], syncStrategy: "archive" });
+    } finally {
+      rmSync(stagingDir, { recursive: true, force: true });
+    }
+  }
   const excludes = opts?.exclude ?? DEFAULT_UPLOAD_EXCLUDES;
   const args = ["-czf", "-"];
   for (const ex of excludes)
@@ -12084,6 +12095,23 @@ async function tarDirectory(localDir, opts) {
   }
   return Buffer.from(buf);
 }
+async function rsyncDirectory(localDir, stagingDir, excludes) {
+  const args = [
+    "-a",
+    "--delete",
+    ...excludes.flatMap((ex) => ["--exclude", ex]),
+    `${localDir.replace(/\/+$/, "")}/`,
+    `${stagingDir.replace(/\/+$/, "")}/`
+  ];
+  const proc = Bun.spawn(["rsync", ...args], { stdout: "pipe", stderr: "pipe" });
+  const [stderr, exitCode] = await Promise.all([
+    new Response(proc.stderr).text(),
+    proc.exited
+  ]);
+  if (exitCode !== 0) {
+    throw new Error(`rsyncDirectory: rsync exited ${exitCode}: ${stderr.trim()}`);
+  }
+}
 function buildUntarCommand(remoteTarPath, remoteDir) {
   const tar = shellQuote(remoteTarPath);
   const dir = shellQuote(remoteDir);

package/dist/index.js

@@ -88,7 +88,9 @@ var init_types = __esm(() => {
 });
 
 // src/lib/archive.ts
-import { existsSync as existsSync7, statSync } from "fs";
+import { existsSync as existsSync7, mkdtempSync, rmSync, statSync } from "fs";
+import { tmpdir } from "os";
+import { join as join8 } from "path";
 function shellQuote(value) {
   return "'" + value.replace(/'/g, "'\\''") + "'";
 }
@@ -96,6 +98,15 @@ async function tarDirectory(localDir, opts) {
   if (!existsSync7(localDir) || !statSync(localDir).isDirectory()) {
     throw new Error(`tarDirectory: not a directory: ${localDir}`);
   }
+  if (opts?.syncStrategy === "rsync") {
+    const stagingDir = mkdtempSync(join8(tmpdir(), "sandboxes-rsync-"));
+    try {
+      await rsyncDirectory(localDir, stagingDir, opts.exclude ?? DEFAULT_UPLOAD_EXCLUDES);
+      return await tarDirectory(stagingDir, { exclude: [], syncStrategy: "archive" });
+    } finally {
+      rmSync(stagingDir, { recursive: true, force: true });
+    }
+  }
   const excludes = opts?.exclude ?? DEFAULT_UPLOAD_EXCLUDES;
   const args = ["-czf", "-"];
   for (const ex of excludes)
@@ -112,6 +123,23 @@ async function tarDirectory(localDir, opts) {
   }
   return Buffer.from(buf);
 }
+async function rsyncDirectory(localDir, stagingDir, excludes) {
+  const args = [
+    "-a",
+    "--delete",
+    ...excludes.flatMap((ex) => ["--exclude", ex]),
+    `${localDir.replace(/\/+$/, "")}/`,
+    `${stagingDir.replace(/\/+$/, "")}/`
+  ];
+  const proc = Bun.spawn(["rsync", ...args], { stdout: "pipe", stderr: "pipe" });
+  const [stderr, exitCode] = await Promise.all([
+    new Response(proc.stderr).text(),
+    proc.exited
+  ]);
+  if (exitCode !== 0) {
+    throw new Error(`rsyncDirectory: rsync exited ${exitCode}: ${stderr.trim()}`);
+  }
+}
 function buildUntarCommand(remoteTarPath, remoteDir) {
   const tar = shellQuote(remoteTarPath);
   const dir = shellQuote(remoteDir);
@@ -11658,7 +11686,12 @@ class SandboxesSDK {
     let exec;
     try {
       if (input.upload) {
-        upload = await this.uploadDir(sandbox.id, input.upload.localDir, input.upload.remoteDir, { exclude: input.upload.exclude });
+        const uploadOptions = {};
+        if (input.upload.exclude !== undefined)
+          uploadOptions.exclude = input.upload.exclude;
+        if (input.upload.syncStrategy !== undefined)
+          uploadOptions.syncStrategy = input.upload.syncStrategy;
+        upload = await this.uploadDir(sandbox.id, input.upload.localDir, input.upload.remoteDir, uploadOptions);
       }
       exec = await this.execCommand(sandbox.id, input.command, {
         cwd: input.cwd ?? input.upload?.remoteDir,

package/dist/lib/archive.d.ts

@@ -11,6 +11,8 @@ export interface TarDirectoryOptions {
      * {@link DEFAULT_UPLOAD_EXCLUDES}; pass `[]` to include everything.
      */
     exclude?: string[];
+    /** Prepare a temporary upload tree with rsync before creating the archive. */
+    syncStrategy?: "archive" | "rsync";
 }
 /** Single-quote a value for safe POSIX shell interpolation. */
 export declare function shellQuote(value: string): string;

package/dist/mcp/http.d.ts

@@ -1,6 +1,7 @@
 import { type Server } from "node:http";
-export declare const DEFAULT_MCP_HTTP_PORT = 8831;
+export declare const DEFAULT_MCP_HTTP_PORT = 8875;
 export declare function isHttpMode(argv: string[]): boolean;
+export declare function isStdioMode(argv: string[]): boolean;
 export declare function resolveMcpHttpPort(argv: string[]): number;
 export declare function healthPayload(name?: string): {
     status: string;

package/dist/mcp/index.js

@@ -61,7 +61,9 @@ var init_types2 = __esm(() => {
 });
 
 // src/lib/archive.ts
-import { existsSync as existsSync7, statSync } from "fs";
+import { existsSync as existsSync7, mkdtempSync, rmSync, statSync } from "fs";
+import { tmpdir } from "os";
+import { join as join8 } from "path";
 function shellQuote(value) {
   return "'" + value.replace(/'/g, "'\\''") + "'";
 }
@@ -69,6 +71,15 @@ async function tarDirectory(localDir, opts) {
   if (!existsSync7(localDir) || !statSync(localDir).isDirectory()) {
     throw new Error(`tarDirectory: not a directory: ${localDir}`);
   }
+  if (opts?.syncStrategy === "rsync") {
+    const stagingDir = mkdtempSync(join8(tmpdir(), "sandboxes-rsync-"));
+    try {
+      await rsyncDirectory(localDir, stagingDir, opts.exclude ?? DEFAULT_UPLOAD_EXCLUDES);
+      return await tarDirectory(stagingDir, { exclude: [], syncStrategy: "archive" });
+    } finally {
+      rmSync(stagingDir, { recursive: true, force: true });
+    }
+  }
   const excludes = opts?.exclude ?? DEFAULT_UPLOAD_EXCLUDES;
   const args = ["-czf", "-"];
   for (const ex of excludes)
@@ -85,6 +96,23 @@ async function tarDirectory(localDir, opts) {
   }
   return Buffer.from(buf);
 }
+async function rsyncDirectory(localDir, stagingDir, excludes) {
+  const args = [
+    "-a",
+    "--delete",
+    ...excludes.flatMap((ex) => ["--exclude", ex]),
+    `${localDir.replace(/\/+$/, "")}/`,
+    `${stagingDir.replace(/\/+$/, "")}/`
+  ];
+  const proc = Bun.spawn(["rsync", ...args], { stdout: "pipe", stderr: "pipe" });
+  const [stderr, exitCode] = await Promise.all([
+    new Response(proc.stderr).text(),
+    proc.exited
+  ]);
+  if (exitCode !== 0) {
+    throw new Error(`rsyncDirectory: rsync exited ${exitCode}: ${stderr.trim()}`);
+  }
+}
 function buildUntarCommand(remoteTarPath, remoteDir) {
   const tar = shellQuote(remoteTarPath);
   const dir = shellQuote(remoteDir);
@@ -16930,9 +16958,9 @@ function buildServer() {
 import { createServer } from "http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
-var DEFAULT_MCP_HTTP_PORT = 8831;
-function isHttpMode(argv) {
-  return argv.includes("--http") || process.env["MCP_HTTP"] === "1";
+var DEFAULT_MCP_HTTP_PORT = 8875;
+function isStdioMode(argv) {
+  return argv.includes("--stdio") || process.env["MCP_STDIO"] === "1";
 }
 function resolveMcpHttpPort(argv) {
   const portIdx = argv.indexOf("--port");
@@ -17014,12 +17042,12 @@ if (handleCliFlags(argv)) {
   process.exit(0);
 }
 async function main() {
-  if (isHttpMode(argv)) {
-    startMcpHttpServer({ port: resolveMcpHttpPort(argv) });
+  if (isStdioMode(argv)) {
+    const server = buildServer();
+    const transport = new StdioServerTransport;
+    await server.connect(transport);
     return;
   }
-  const server = buildServer();
-  const transport = new StdioServerTransport;
-  await server.connect(transport);
+  startMcpHttpServer({ port: resolveMcpHttpPort(argv) });
 }
 main().catch(console.error);

package/dist/sdk.d.ts

@@ -20,6 +20,7 @@ export interface RunCommandInSandboxUploadOptions {
     localDir: string;
     remoteDir: string;
     exclude?: string[];
+    syncStrategy?: "archive" | "rsync";
 }
 export interface RunCommandInSandboxOptions {
     command: string;

package/dist/server/index.js

@@ -97,7 +97,9 @@ var init_types2 = __esm(() => {
 });
 
 // src/lib/archive.ts
-import { existsSync as existsSync7, statSync } from "fs";
+import { existsSync as existsSync7, mkdtempSync, rmSync, statSync } from "fs";
+import { tmpdir } from "os";
+import { join as join8 } from "path";
 function shellQuote(value) {
   return "'" + value.replace(/'/g, "'\\''") + "'";
 }
@@ -105,6 +107,15 @@ async function tarDirectory(localDir, opts) {
   if (!existsSync7(localDir) || !statSync(localDir).isDirectory()) {
     throw new Error(`tarDirectory: not a directory: ${localDir}`);
   }
+  if (opts?.syncStrategy === "rsync") {
+    const stagingDir = mkdtempSync(join8(tmpdir(), "sandboxes-rsync-"));
+    try {
+      await rsyncDirectory(localDir, stagingDir, opts.exclude ?? DEFAULT_UPLOAD_EXCLUDES);
+      return await tarDirectory(stagingDir, { exclude: [], syncStrategy: "archive" });
+    } finally {
+      rmSync(stagingDir, { recursive: true, force: true });
+    }
+  }
   const excludes = opts?.exclude ?? DEFAULT_UPLOAD_EXCLUDES;
   const args = ["-czf", "-"];
   for (const ex of excludes)
@@ -121,6 +132,23 @@ async function tarDirectory(localDir, opts) {
   }
   return Buffer.from(buf);
 }
+async function rsyncDirectory(localDir, stagingDir, excludes) {
+  const args = [
+    "-a",
+    "--delete",
+    ...excludes.flatMap((ex) => ["--exclude", ex]),
+    `${localDir.replace(/\/+$/, "")}/`,
+    `${stagingDir.replace(/\/+$/, "")}/`
+  ];
+  const proc = Bun.spawn(["rsync", ...args], { stdout: "pipe", stderr: "pipe" });
+  const [stderr, exitCode] = await Promise.all([
+    new Response(proc.stderr).text(),
+    proc.exited
+  ]);
+  if (exitCode !== 0) {
+    throw new Error(`rsyncDirectory: rsync exited ${exitCode}: ${stderr.trim()}`);
+  }
+}
 function buildUntarCommand(remoteTarPath, remoteDir) {
   const tar = shellQuote(remoteTarPath);
   const dir = shellQuote(remoteDir);

package/dist/types/index.d.ts

@@ -179,6 +179,12 @@ export interface FileInfo {
 export interface UploadDirOptions {
     /** Patterns to exclude (passed to `tar --exclude`); defaults applied by the archiver. */
     exclude?: string[];
+    /**
+     * How to prepare the upload payload. `archive` tars the source directory
+     * directly; `rsync` first mirrors the source into a temporary staging
+     * directory with rsync, then uploads the staged tree.
+     */
+    syncStrategy?: "archive" | "rsync";
 }
 export interface UploadDirResult {
     /** Number of bytes uploaded (compressed archive size). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/sandboxes",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "author": "Andrei Hasna <andrei@hasna.com>",
   "repository": {
     "type": "git",