@tpmjs/tools-sprites-exec 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,88 @@
+# @tpmjs/sprites-exec
+
+Execute a command inside a sprite and return the output.
+
+## Installation
+
+```bash
+npm install @tpmjs/sprites-exec
+```
+
+## Requirements
+
+- `SPRITES_TOKEN` environment variable - Get your token from https://sprites.dev
+
+## Usage
+
+```typescript
+import { spritesExecTool } from '@tpmjs/sprites-exec';
+
+// Run a simple command
+const result = await spritesExecTool.execute({
+  name: 'my-sandbox',
+  cmd: 'ls -la /home'
+});
+
+console.log(result);
+// {
+//   exitCode: 0,
+//   stdout: 'total 4\ndrwxr-xr-x 2 root root 4096 Jan 15 10:30 .\n...',
+//   stderr: '',
+//   duration: 45
+// }
+
+// Run with stdin input
+const pythonResult = await spritesExecTool.execute({
+  name: 'my-sandbox',
+  cmd: 'python3',
+  stdin: 'print("Hello from stdin!")'
+});
+
+// For shell features (pipes, redirects, etc), use bash -c
+const shellResult = await spritesExecTool.execute({
+  name: 'my-sandbox',
+  cmd: 'bash -c "echo hello > /tmp/test.txt && cat /tmp/test.txt"'
+});
+```
+
+## Shell Commands
+
+Commands are executed directly (like `exec.Command` in Go), not through a shell. This means shell operators like `|`, `>`, `>>`, `&&` won't work directly.
+
+For shell features, wrap your command with `bash -c`:
+```typescript
+// Won't work: cmd: 'echo hello > file.txt'
+// Use instead:
+cmd: 'bash -c "echo hello > file.txt"'
+```
+
+## Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | `string` | Yes | Name of the sprite to execute command in |
+| `cmd` | `string` | Yes | Command to execute (e.g., 'ls -la', 'python script.py') |
+| `stdin` | `string` | No | Optional stdin input to pass to the command |
+| `timeoutMs` | `number` | No | Execution timeout in milliseconds (default: 60000) |
+
+## Output
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `exitCode` | `number` | Command exit code (0 = success) |
+| `stdout` | `string` | Standard output from the command |
+| `stderr` | `string` | Standard error from the command |
+| `duration` | `number` | Execution duration in milliseconds |
+
+## Error Handling
+
+The tool throws errors in these cases:
+- `SPRITES_TOKEN` environment variable is not set
+- Sprite not found (HTTP 404)
+- Command execution timeout
+- Invalid or expired API token (HTTP 401)
+- Network errors with descriptive messages
+
+## License
+
+MIT

package/dist/index.js

@@ -2,6 +2,10 @@ import { tool, jsonSchema } from 'ai';
 
 // src/index.ts
 var SPRITES_API_BASE = "https://api.sprites.dev/v1";
+var STREAM_STDIN = 0;
+var STREAM_STDOUT = 1;
+var STREAM_STDERR = 2;
+var STREAM_EXIT = 3;
 function getSpritesToken() {
   const token = process.env.SPRITES_TOKEN;
   if (!token) {
@@ -11,6 +15,84 @@ function getSpritesToken() {
   }
   return token;
 }
+function parseCommand(cmdString) {
+  const args = [];
+  let current = "";
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let escaped = false;
+  for (let i = 0; i < cmdString.length; i++) {
+    const char = cmdString[i];
+    if (escaped) {
+      current += char;
+      escaped = false;
+      continue;
+    }
+    if (char === "\\" && !inSingleQuote) {
+      escaped = true;
+      continue;
+    }
+    if (char === "'" && !inDoubleQuote) {
+      inSingleQuote = !inSingleQuote;
+      continue;
+    }
+    if (char === '"' && !inSingleQuote) {
+      inDoubleQuote = !inDoubleQuote;
+      continue;
+    }
+    if (char === " " && !inSingleQuote && !inDoubleQuote) {
+      if (current.length > 0) {
+        args.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += char;
+  }
+  if (current.length > 0) {
+    args.push(current);
+  }
+  return args;
+}
+function parseBinaryResponse(buffer) {
+  let stdout = "";
+  let stderr = "";
+  let exitCode = 0;
+  const decoder = new TextDecoder();
+  let i = 0;
+  while (i < buffer.length) {
+    const streamId = buffer[i];
+    i++;
+    if (streamId === STREAM_EXIT) {
+      if (i < buffer.length) {
+        exitCode = buffer[i];
+        i++;
+      }
+      continue;
+    }
+    let end = i;
+    while (end < buffer.length) {
+      const nextByte = buffer[end];
+      if (nextByte <= STREAM_EXIT) {
+        break;
+      }
+      end++;
+    }
+    const payload = decoder.decode(buffer.slice(i, end));
+    switch (streamId) {
+      case STREAM_STDIN:
+        break;
+      case STREAM_STDOUT:
+        stdout += payload;
+        break;
+      case STREAM_STDERR:
+        stderr += payload;
+        break;
+    }
+    i = end;
+  }
+  return { stdout, stderr, exitCode };
+}
 var spritesExecTool = tool({
   description: "Execute a command inside a sprite and return the output. Supports stdin input for interactive commands. Returns exit code, stdout, stderr, and execution duration.",
   inputSchema: jsonSchema({
@@ -46,31 +128,36 @@ var spritesExecTool = tool({
     const token = getSpritesToken();
     const timeout = timeoutMs || 6e4;
     const startTime = Date.now();
+    const cmdParts = parseCommand(cmd);
+    if (cmdParts.length === 0) {
+      throw new Error("Command cannot be empty");
+    }
+    const url = new URL(`${SPRITES_API_BASE}/sprites/${encodeURIComponent(name)}/exec`);
+    for (const part of cmdParts) {
+      url.searchParams.append("cmd", part);
+    }
+    if (stdin) {
+      url.searchParams.set("stdin", "true");
+    }
     let response;
     try {
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), timeout);
-      const body = { cmd };
-      if (stdin) {
-        body.stdin = stdin;
-      }
-      response = await fetch(`${SPRITES_API_BASE}/sprites/${encodeURIComponent(name)}/exec`, {
+      response = await fetch(url.toString(), {
         method: "POST",
         headers: {
           Authorization: `Bearer ${token}`,
-          "Content-Type": "application/json",
-          "User-Agent": "TPMJS/1.0"
+          "User-Agent": "TPMJS/1.0",
+          ...stdin ? { "Content-Type": "application/octet-stream" } : {}
         },
-        body: JSON.stringify(body),
+        body: stdin || void 0,
         signal: controller.signal
       });
       clearTimeout(timeoutId);
     } catch (error) {
       if (error instanceof Error) {
         if (error.name === "AbortError") {
-          throw new Error(
-            `Command execution in sprite "${name}" timed out after ${timeout}ms`
-          );
+          throw new Error(`Command execution in sprite "${name}" timed out after ${timeout}ms`);
         }
         throw new Error(`Failed to execute command in sprite "${name}": ${error.message}`);
       }
@@ -89,17 +176,14 @@ var spritesExecTool = tool({
         `Failed to execute command in sprite "${name}": HTTP ${response.status} - ${errorText}`
       );
     }
-    let data;
-    try {
-      data = await response.json();
-    } catch {
-      throw new Error("Failed to parse response from Sprites API");
-    }
+    const arrayBuffer = await response.arrayBuffer();
+    const buffer = new Uint8Array(arrayBuffer);
+    const { stdout, stderr, exitCode } = parseBinaryResponse(buffer);
     return {
-      exitCode: data.exitCode ?? data.exit_code ?? 0,
-      stdout: data.stdout || "",
-      stderr: data.stderr || "",
-      duration: data.duration || duration
+      exitCode,
+      stdout,
+      stderr,
+      duration
     };
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpmjs/tools-sprites-exec",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Execute a command inside a sprite and return the output with exit code",
   "type": "module",
   "keywords": [