tests

Author: cramforce

README.md

@@ -6,6 +6,14 @@ Designed for AI agents that need a secure, sandboxed bash environment.
 
 Supports optional network access via `curl` with secure-by-default URL filtering.
 
+## Security model
+
+- The shell only has access to the provided file system.
+- Execution is protected against infinite loops or recursion through.
+- Binaries or even WASM are inherently unsupported (Use [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) or a similar product if a full VM is needed).
+- There is no network access by default.
+- Network access can be enabled, but requests are checked against URL prefix allow-lists and HTTP-method allow-lists. See [network access](#network-access) for details
+
 ## Installation
 
 ```bash
@@ -96,30 +104,6 @@ await sandbox.mkDir("/app/logs", { recursive: true });
 await sandbox.stop();
 ```
 
-#### Command Streaming
-
-The `Command` class provides multiple ways to access output:
-
-```typescript
-const cmd = await sandbox.runCommand("echo hello; echo world >&2");
-
-// Get stdout/stderr separately
-const stdout = await cmd.stdout(); // "hello\n"
-const stderr = await cmd.stderr(); // "world\n"
-
-// Get combined output
-const output = await cmd.output(); // "hello\nworld\n"
-
-// Stream logs as they arrive
-for await (const msg of cmd.logs()) {
-  console.log(msg.type, msg.data); // "stdout" "hello\n", "stderr" "world\n"
-}
-
-// Wait for completion
-const finished = await cmd.wait();
-console.log(finished.exitCode); // 0
-```
-
 ### Interactive Shell
 
 ```bash

src/commands/help/help.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { BashEnv } from "../../BashEnv.js";
+
+describe("help", () => {
+  describe("list all commands", () => {
+    it("should list available commands", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("help");
+      expect(result.stdout).toContain("Available commands");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should show file operations category", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("help");
+      expect(result.stdout).toContain("File operations");
+      expect(result.stdout).toContain("ls");
+      expect(result.stdout).toContain("cat");
+    });
+
+    it("should show text processing category", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("help");
+      expect(result.stdout).toContain("Text processing");
+      expect(result.stdout).toContain("grep");
+      expect(result.stdout).toContain("sed");
+    });
+
+    it("should show usage hint", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("help");
+      expect(result.stdout).toContain("--help");
+    });
+  });
+
+  describe("help for specific command", () => {
+    it("should show help for ls", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("help ls");
+      expect(result.stdout).toContain("ls");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should show help for grep", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("help grep");
+      expect(result.stdout).toContain("grep");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should error for unknown command", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("help nonexistent");
+      expect(result.exitCode).toBe(127);
+    });
+  });
+
+  describe("--help flag", () => {
+    it("should show help's own help", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("help --help");
+      expect(result.stdout).toContain("help");
+      expect(result.stdout).toContain("Usage");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should support -h flag", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("help -h");
+      expect(result.stdout).toContain("help");
+      expect(result.exitCode).toBe(0);
+    });
+  });
+});

src/commands/printf/printf.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, it } from "vitest";
+import { BashEnv } from "../../BashEnv.js";
+
+describe("printf", () => {
+  describe("basic format specifiers", () => {
+    it("should format string with %s", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "Hello %s" world');
+      expect(result.stdout).toBe("Hello world");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should format integer with %d", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "Number: %d" 42');
+      expect(result.stdout).toBe("Number: 42");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should format float with %f", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "Value: %f" 3.14');
+      expect(result.stdout).toBe("Value: 3.14");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should format hex with %x", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "Hex: %x" 255');
+      expect(result.stdout).toBe("Hex: ff");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should format octal with %o", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "Octal: %o" 8');
+      expect(result.stdout).toBe("Octal: 10");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should handle literal %% ", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "100%%"');
+      expect(result.stdout).toBe("100%");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should handle multiple arguments", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "%s is %d years old" Alice 30');
+      expect(result.stdout).toBe("Alice is 30 years old");
+      expect(result.exitCode).toBe(0);
+    });
+  });
+
+  describe("escape sequences", () => {
+    it("should handle newline \\n", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "line1\\nline2"');
+      expect(result.stdout).toBe("line1\nline2");
+    });
+
+    it("should handle tab \\t", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "col1\\tcol2"');
+      expect(result.stdout).toBe("col1\tcol2");
+    });
+
+    it("should handle backslash \\\\", async () => {
+      const env = new BashEnv();
+      // 8 backslashes in source -> 4 in bash string -> 2 for printf -> 1 literal
+      const result = await env.exec('printf "x\\\\\\\\y"');
+      expect(result.stdout).toBe("x\\y");
+    });
+
+    it("should handle carriage return \\r", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "hello\\rworld"');
+      expect(result.stdout).toBe("hello\rworld");
+    });
+
+    it("should handle octal escape sequences", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "\\101\\102\\103"');
+      expect(result.stdout).toBe("ABC");
+    });
+  });
+
+  describe("width and precision", () => {
+    it("should handle width specifier", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "%10s" "hi"');
+      expect(result.stdout).toBe("        hi");
+    });
+
+    it("should handle precision for floats", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "%.2f" 3.14159');
+      expect(result.stdout).toBe("3.14");
+    });
+
+    it("should handle zero-padding", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "%05d" 42');
+      expect(result.stdout).toBe("00042");
+    });
+
+    it("should handle left-justify with -", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "%-10s|" "hi"');
+      expect(result.stdout).toBe("hi        |");
+    });
+  });
+
+  describe("error handling", () => {
+    it("should error with no arguments", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("printf");
+      expect(result.stderr).toContain("usage");
+      expect(result.exitCode).toBe(1);
+    });
+
+    it("should handle missing arguments gracefully", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "%s %s" only');
+      expect(result.stdout).toBe("only ");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should handle non-numeric for %d", async () => {
+      const env = new BashEnv();
+      const result = await env.exec('printf "%d" notanumber');
+      expect(result.stdout).toBe("0");
+      expect(result.exitCode).toBe(0);
+    });
+  });
+
+  describe("--help", () => {
+    it("should display help", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("printf --help");
+      expect(result.stdout).toContain("printf");
+      expect(result.stdout).toContain("FORMAT");
+      expect(result.exitCode).toBe(0);
+    });
+  });
+});

src/commands/readlink/readlink.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import { BashEnv } from "../../BashEnv.js";
+
+describe("readlink", () => {
+  describe("basic usage", () => {
+    it("should read symlink target", async () => {
+      const env = new BashEnv();
+      await env.exec("echo content > /tmp/target.txt");
+      await env.exec("ln -s /tmp/target.txt /tmp/link");
+      const result = await env.exec("readlink /tmp/link");
+      expect(result.stdout).toBe("/tmp/target.txt\n");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should read relative symlink target", async () => {
+      const env = new BashEnv();
+      await env.exec("echo content > /tmp/target.txt");
+      await env.exec("ln -s target.txt /tmp/link");
+      const result = await env.exec("readlink /tmp/link");
+      expect(result.stdout).toBe("target.txt\n");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should handle multiple files", async () => {
+      const env = new BashEnv();
+      await env.exec("echo a > /tmp/a.txt && echo b > /tmp/b.txt");
+      await env.exec("ln -s /tmp/a.txt /tmp/link1");
+      await env.exec("ln -s /tmp/b.txt /tmp/link2");
+      const result = await env.exec("readlink /tmp/link1 /tmp/link2");
+      expect(result.stdout).toBe("/tmp/a.txt\n/tmp/b.txt\n");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should fail for non-symlink file", async () => {
+      const env = new BashEnv();
+      await env.exec("echo content > /tmp/regular.txt");
+      const result = await env.exec("readlink /tmp/regular.txt");
+      expect(result.exitCode).toBe(1);
+    });
+
+    it("should fail for non-existent file", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("readlink /tmp/nonexistent");
+      expect(result.exitCode).toBe(1);
+    });
+  });
+
+  describe("-f (canonicalize)", () => {
+    it("should canonicalize path through symlinks", async () => {
+      const env = new BashEnv();
+      await env.exec("echo content > /tmp/real.txt");
+      await env.exec("ln -s /tmp/real.txt /tmp/link1");
+      await env.exec("ln -s /tmp/link1 /tmp/link2");
+      const result = await env.exec("readlink -f /tmp/link2");
+      expect(result.stdout).toBe("/tmp/real.txt\n");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should return path for regular file", async () => {
+      const env = new BashEnv();
+      await env.exec("echo content > /tmp/file.txt");
+      const result = await env.exec("readlink -f /tmp/file.txt");
+      expect(result.stdout).toBe("/tmp/file.txt\n");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should canonicalize with relative symlink components", async () => {
+      const env = new BashEnv();
+      await env.exec("mkdir -p /tmp/dir");
+      await env.exec("echo content > /tmp/dir/target.txt");
+      await env.exec("ln -s dir/target.txt /tmp/link");
+      const result = await env.exec("readlink -f /tmp/link");
+      expect(result.stdout).toBe("/tmp/dir/target.txt\n");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("should return resolved path for nonexistent file with -f", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("readlink -f /tmp/nonexistent");
+      expect(result.stdout).toBe("/tmp/nonexistent\n");
+      expect(result.exitCode).toBe(0);
+    });
+  });
+
+  describe("error handling", () => {
+    it("should error on missing operand", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("readlink");
+      expect(result.stderr).toBe("readlink: missing operand\n");
+      expect(result.exitCode).toBe(1);
+    });
+
+    it("should error on unknown option", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("readlink -x /tmp/link");
+      expect(result.stderr).toContain("invalid option");
+      expect(result.exitCode).toBe(1);
+    });
+
+    it("should handle -- to end options", async () => {
+      const env = new BashEnv();
+      await env.exec("ln -s target /tmp/-f");
+      const result = await env.exec("readlink -- /tmp/-f");
+      expect(result.stdout).toBe("target\n");
+      expect(result.exitCode).toBe(0);
+    });
+  });
+
+  describe("--help", () => {
+    it("should display help", async () => {
+      const env = new BashEnv();
+      const result = await env.exec("readlink --help");
+      expect(result.stdout).toContain("readlink");
+      expect(result.stdout).toContain("-f");
+      expect(result.exitCode).toBe(0);
+    });
+  });
+});