sandwrap 0.0.1

package/README.md

@@ -0,0 +1,385 @@
+# sandwrap
+
+A simple CLI tool that runs any command inside a bubblewrap + overlayfs sandbox, preventing it from modifying your actual filesystem. After the command exits, you can review diffs and selectively apply or discard changes.
+
+## Usage
+
+```bash
+bunx sandwrap <command> [args...]
+
+# Examples
+bunx sandwrap claude
+bunx sandwrap claude code
+bunx sandwrap ./my-agent.sh
+bunx sandwrap npm run dangerous-script
+```
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      sandwrap process                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. Setup Phase                                             │
+│     ┌─────────────────────────────────────────────────┐     │
+│     │  Create temp directory structure:               │     │
+│     │    /tmp/sandwrap-XXXX/                          │     │
+│     │      ├── upper/    (overlay writes go here)    │     │
+│     │      ├── work/     (overlayfs workdir)         │     │
+│     │      └── merged/   (union mount point)         │     │
+│     └─────────────────────────────────────────────────┘     │
+│                                                             │
+│  2. Execution Phase                                         │
+│     ┌─────────────────────────────────────────────────┐     │
+│     │  bwrap invocation:                              │     │
+│     │    - Mount CWD as lower (read-only)            │     │
+│     │    - Mount upper + lower as overlay            │     │
+│     │    - Bind essential dirs (/usr, /bin, etc.)    │     │
+│     │    - Run <command> inside sandbox              │     │
+│     │    - All writes captured in upper/             │     │
+│     └─────────────────────────────────────────────────┘     │
+│                                                             │
+│  3. Review Phase (after command exits)                      │
+│     ┌─────────────────────────────────────────────────┐     │
+│     │  - Scan upper/ for changes                      │     │
+│     │  - Generate diffs for modified files           │     │
+│     │  - Show new/deleted files                       │     │
+│     │  - Interactive prompt: apply/discard/review    │     │
+│     └─────────────────────────────────────────────────┘     │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## CLI Interface
+
+### Main Command
+
+```
+sandwrap <command> [args...]
+
+Options:
+  --no-network, -n     Disable network access inside sandbox
+  --keep, -k           Keep overlay directory after exit (for debugging)
+  --auto-apply, -y     Apply all changes without prompting
+  --auto-discard, -d   Discard all changes without prompting
+  --help, -h           Show help
+  --version, -v        Show version
+```
+
+### Post-Execution Review
+
+After the sandboxed command exits, sandwrap enters interactive review mode:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  sandwrap: command exited with code 0
+  
+  Changes detected:
+    M  src/index.ts        (+42, -13)
+    M  package.json        (+2, -1)
+    A  src/utils/new.ts    (+87)
+    D  old-config.json
+    
+  Total: 2 modified, 1 added, 1 deleted
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+What would you like to do?
+
+  [a] Apply all changes
+  [d] Discard all changes  
+  [r] Review changes interactively
+  [s] Select files to apply
+  [q] Quit (discard all)
+
+> 
+```
+
+### Interactive Review Mode (`r`)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Reviewing: src/index.ts (1/4)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+--- a/src/index.ts
++++ b/src/index.ts
+@@ -10,6 +10,12 @@ import { foo } from './foo';
+ 
+ export function main() {
++  // Added safety check
++  if (!validateInput(input)) {
++    throw new Error('Invalid input');
++  }
++
+   const result = process(input);
+   return result;
+ }
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  [y] Apply this file  [n] Skip  [v] View full file  
+  [e] Edit before applying  [q] Quit review
+> 
+```
+
+### Select Files Mode (`s`)
+
+```
+Select files to apply (space to toggle, enter to confirm):
+
+  [x] M  src/index.ts
+  [ ] M  package.json  
+  [x] A  src/utils/new.ts
+  [ ] D  old-config.json
+
+> 
+```
+
+## Architecture
+
+```
+sandwrap/
+├── package.json
+├── src/
+│   ├── index.ts          # Entry point & CLI parsing
+│   ├── sandbox.ts        # bwrap + overlay setup/teardown
+│   ├── diff.ts           # Change detection & diff generation
+│   ├── review.ts         # Interactive review UI
+│   └── apply.ts          # File operations to apply changes
+└── README.md
+```
+
+## Core Module: `sandbox.ts`
+
+Responsible for:
+
+1. **Creating overlay structure**
+   ```typescript
+   interface SandboxContext {
+     id: string;
+     tempDir: string;
+     upperDir: string;   // Where writes go
+     workDir: string;    // OverlayFS requirement
+     mergedDir: string;  // Union mount point
+     targetDir: string;  // Original CWD being sandboxed
+   }
+   ```
+
+2. **Building bwrap command**
+   ```bash
+   bwrap \
+     --ro-bind /usr /usr \
+     --ro-bind /lib /lib \
+     --ro-bind /lib64 /lib64 \
+     --ro-bind /bin /bin \
+     --ro-bind /etc /etc \
+     --dev /dev \
+     --proc /proc \
+     --tmpfs /tmp \
+     --bind $UPPER $CWD \        # Overlay writes go to upper
+     --ro-bind $CWD $CWD/.lower  # Read-only access to original
+     --chdir $CWD \
+     --unshare-user \
+     --unshare-pid \
+     --unshare-net \             # If --no-network
+     --die-with-parent \
+     -- <command> [args...]
+   ```
+
+3. **Alternative: fuse-overlayfs for unprivileged users**
+   
+   If user lacks permissions for kernel overlayfs, fall back to fuse-overlayfs:
+   ```bash
+   fuse-overlayfs -o lowerdir=$CWD,upperdir=$UPPER,workdir=$WORK $MERGED
+   ```
+
+## Core Module: `diff.ts`
+
+Responsible for detecting and formatting changes:
+
+```typescript
+interface FileChange {
+  path: string;
+  type: 'added' | 'modified' | 'deleted';
+  diff?: string;           // Unified diff for text files
+  linesAdded?: number;
+  linesRemoved?: number;
+  isBinary: boolean;
+}
+
+// Scan upper directory for changes
+function detectChanges(ctx: SandboxContext): FileChange[];
+
+// Generate unified diff between original and modified
+function generateDiff(original: string, modified: string): string;
+```
+
+### Change Detection Logic
+
+OverlayFS marks changes in the upper directory:
+- **New files**: Present in upper, not in lower
+- **Modified files**: Present in both (upper shadows lower)
+- **Deleted files**: Character device with 0/0 major/minor (whiteout)
+  ```typescript
+  // Detect whiteout files (overlayfs deletion markers)
+  const stats = await fs.lstat(path);
+  const isWhiteout = stats.isCharacterDevice() && 
+                     stats.rdev === 0;
+  ```
+
+## Core Module: `review.ts`
+
+Interactive terminal UI using something like `@clack/prompts` or raw readline:
+
+```typescript
+interface ReviewResult {
+  filesToApply: string[];
+  filesToDiscard: string[];
+}
+
+async function reviewChanges(changes: FileChange[]): Promise<ReviewResult>;
+```
+
+## Core Module: `apply.ts`
+
+Applies selected changes from upper directory to original:
+
+```typescript
+async function applyChanges(
+  ctx: SandboxContext, 
+  files: string[]
+): Promise<void> {
+  for (const file of files) {
+    const src = path.join(ctx.upperDir, file);
+    const dst = path.join(ctx.targetDir, file);
+    
+    const stats = await fs.lstat(src);
+    
+    if (isWhiteout(stats)) {
+      // Delete from original
+      await fs.rm(dst, { recursive: true });
+    } else {
+      // Copy from upper to original
+      await fs.cp(src, dst, { recursive: true });
+    }
+  }
+}
+```
+
+## Dependencies
+
+```json
+{
+  "name": "sandwrap",
+  "version": "0.1.0",
+  "bin": {
+    "sandwrap": "./dist/index.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "diff": "^5.2.0",
+    "picocolors": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "@types/diff": "^5.0.0"
+  }
+}
+```
+
+## Requirements
+
+**System dependencies (must be installed):**
+- `bwrap` (bubblewrap) - Usually available as `bubblewrap` package
+- `fuse-overlayfs` (optional fallback for unprivileged overlay)
+
+**Check on startup:**
+```typescript
+async function checkDependencies(): Promise<void> {
+  try {
+    await execAsync('which bwrap');
+  } catch {
+    console.error('Error: bubblewrap not found.');
+    console.error('Install with: sudo apt install bubblewrap');
+    process.exit(1);
+  }
+}
+```
+
+## Edge Cases & Considerations
+
+1. **Binary files**: Show as changed but don't display diff content
+2. **Symlinks**: Preserve symlink targets when applying
+3. **Permissions**: Preserve file modes when copying
+4. **Large files**: Stream diff rather than loading into memory
+5. **Nested sandboxing**: Detect if already in sandbox and warn/fail
+6. **Signal handling**: Clean up overlay on SIGINT/SIGTERM
+7. **Unprivileged users**: Fall back to fuse-overlayfs if needed
+8. **macOS**: bubblewrap is Linux-only; would need alternative (maybe lima/colima + bwrap inside)
+
+## Example Session
+
+```bash
+$ bunx sandwrap claude
+
+# ... claude runs, makes changes ...
+# User types /exit or Ctrl+D
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  sandwrap: claude exited with code 0
+  
+  Changes detected:
+    M  src/api.ts           (+15, -3)
+    M  src/types.ts         (+8, -0)
+    A  src/helpers/cache.ts (+45)
+    
+  Total: 2 modified, 1 added, 0 deleted
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+What would you like to do?
+
+  [a] Apply all changes
+  [d] Discard all changes  
+  [r] Review changes interactively
+  [s] Select files to apply
+  [q] Quit (discard all)
+
+> r
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Reviewing: src/api.ts (1/3)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+--- a/src/api.ts
++++ b/src/api.ts
+@@ -22,6 +22,18 @@ export async function fetchData(id: string) {
++  // Add caching layer
++  const cached = await cache.get(id);
++  if (cached) return cached;
++
+   const response = await fetch(`/api/data/${id}`);
+-  return response.json();
++  const data = await response.json();
++  await cache.set(id, data);
++  return data;
+ }
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  [y] Apply  [n] Skip  [v] View full  [q] Quit
+> y
+
+✓ Applied src/api.ts
+✓ Applied src/types.ts  
+✓ Applied src/helpers/cache.ts
+
+Done! 3 files applied, 0 discarded.
+```
+
+## Future Enhancements
+
+- `--snapshot` mode: Save overlay as tarball for later replay
+- `--compare` mode: Run same command with/without changes, compare output
+- Git integration: Stage applied changes automatically
+- Undo support: Keep backup of original files before applying
+- Config file: `.sandwraprc` for default options per project

package/dist/index.js

@@ -0,0 +1,697 @@
+#!/usr/bin/env node
+// index.ts
+import { parseArgs } from "util";
+
+// src/sandbox.ts
+import { spawn, execSync } from "child_process";
+import { randomBytes } from "crypto";
+import { join } from "path";
+import { rm, mkdir, cp } from "fs/promises";
+async function checkDependencies() {
+  try {
+    execSync("which bwrap", { stdio: "ignore" });
+  } catch {
+    console.error("Error: bubblewrap not found.");
+    console.error("Install with: sudo apt install bubblewrap");
+    process.exit(1);
+  }
+}
+async function createSandbox(targetDir) {
+  const id = randomBytes(4).toString("hex");
+  const tempDir = join("/tmp", `sandwrap-${id}`);
+  const upperDir = join(tempDir, "upper");
+  const workDir = join(tempDir, "work");
+  const mergedDir = join(tempDir, "merged");
+  await mkdir(upperDir, { recursive: true });
+  await mkdir(workDir, { recursive: true });
+  await mkdir(mergedDir, { recursive: true });
+  return {
+    id,
+    tempDir,
+    upperDir,
+    workDir,
+    mergedDir,
+    targetDir
+  };
+}
+function dirExists(path) {
+  try {
+    execSync(`test -d ${path}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function runInSandbox(ctx, options) {
+  const args = [
+    "--ro-bind",
+    "/usr",
+    "/usr",
+    "--ro-bind",
+    "/bin",
+    "/bin",
+    "--ro-bind",
+    "/etc",
+    "/etc",
+    "--dev",
+    "/dev",
+    "--proc",
+    "/proc",
+    "--tmpfs",
+    "/tmp"
+  ];
+  if (dirExists("/lib")) {
+    args.push("--ro-bind", "/lib", "/lib");
+  }
+  if (dirExists("/lib64")) {
+    args.push("--ro-bind", "/lib64", "/lib64");
+  }
+  if (dirExists("/sbin")) {
+    args.push("--ro-bind", "/sbin", "/sbin");
+  }
+  const homeDir = process.env.HOME;
+  if (homeDir) {
+    args.push("--ro-bind", homeDir, homeDir);
+  }
+  args.push("--bind", ctx.upperDir, ctx.targetDir);
+  await cp(ctx.targetDir, ctx.upperDir, { recursive: true });
+  args.push("--chdir", ctx.targetDir);
+  args.push("--unshare-pid");
+  args.push("--die-with-parent");
+  if (options.noNetwork) {
+    args.push("--unshare-net");
+  }
+  args.push("--");
+  args.push(...options.command);
+  return new Promise((resolve) => {
+    const proc = spawn("bwrap", args, {
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        SANDWRAP: "1",
+        SANDWRAP_ID: ctx.id
+      }
+    });
+    proc.on("close", (code) => {
+      resolve(code ?? 1);
+    });
+    proc.on("error", (err) => {
+      console.error(`Failed to start sandbox: ${err.message}`);
+      resolve(1);
+    });
+  });
+}
+async function cleanupSandbox(ctx) {
+  await rm(ctx.tempDir, { recursive: true, force: true });
+}
+
+// src/diff.ts
+import { join as join2, relative } from "path";
+import { readdir, lstat, readFile } from "fs/promises";
+async function isBinaryFile(filePath) {
+  try {
+    const buffer = await readFile(filePath);
+    const slice = buffer.subarray(0, 8192);
+    for (const byte of slice) {
+      if (byte === 0)
+        return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+function generateUnifiedDiff(originalContent, modifiedContent, filePath) {
+  const originalLines = originalContent.split(`
+`);
+  const modifiedLines = modifiedContent.split(`
+`);
+  const result = [];
+  result.push(`--- a/${filePath}`);
+  result.push(`+++ b/${filePath}`);
+  let i = 0, j = 0;
+  let hunkStart = -1;
+  let hunkLines = [];
+  const flushHunk = () => {
+    if (hunkLines.length > 0) {
+      result.push(`@@ -${hunkStart + 1} +${hunkStart + 1} @@`);
+      result.push(...hunkLines);
+      hunkLines = [];
+    }
+  };
+  while (i < originalLines.length || j < modifiedLines.length) {
+    if (i < originalLines.length && j < modifiedLines.length) {
+      if (originalLines[i] === modifiedLines[j]) {
+        flushHunk();
+        i++;
+        j++;
+      } else {
+        if (hunkStart === -1)
+          hunkStart = i;
+        const origInMod = modifiedLines.indexOf(originalLines[i], j);
+        const modInOrig = originalLines.indexOf(modifiedLines[j], i);
+        if (origInMod === -1 && modInOrig === -1) {
+          hunkLines.push(`-${originalLines[i]}`);
+          hunkLines.push(`+${modifiedLines[j]}`);
+          i++;
+          j++;
+        } else if (origInMod === -1) {
+          hunkLines.push(`-${originalLines[i]}`);
+          i++;
+        } else {
+          hunkLines.push(`+${modifiedLines[j]}`);
+          j++;
+        }
+      }
+    } else if (i < originalLines.length) {
+      if (hunkStart === -1)
+        hunkStart = i;
+      hunkLines.push(`-${originalLines[i]}`);
+      i++;
+    } else {
+      if (hunkStart === -1)
+        hunkStart = j;
+      hunkLines.push(`+${modifiedLines[j]}`);
+      j++;
+    }
+  }
+  flushHunk();
+  return result.join(`
+`);
+}
+async function* walkDir(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join2(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkDir(fullPath);
+    } else {
+      yield fullPath;
+    }
+  }
+}
+async function detectChanges(ctx) {
+  const changes = [];
+  const originalFiles = new Set;
+  try {
+    for await (const file of walkDir(ctx.targetDir)) {
+      const relPath = relative(ctx.targetDir, file);
+      originalFiles.add(relPath);
+    }
+  } catch {}
+  const upperFiles = new Set;
+  try {
+    for await (const file of walkDir(ctx.upperDir)) {
+      const relPath = relative(ctx.upperDir, file);
+      upperFiles.add(relPath);
+      const upperPath = file;
+      const originalPath = join2(ctx.targetDir, relPath);
+      const upperStats = await lstat(upperPath);
+      if (upperStats.isCharacterDevice() && upperStats.rdev === 0) {
+        changes.push({
+          path: relPath,
+          type: "deleted",
+          linesAdded: 0,
+          linesRemoved: 0,
+          isBinary: false
+        });
+        continue;
+      }
+      const binary = await isBinaryFile(upperPath);
+      const existsInOriginal = originalFiles.has(relPath);
+      if (!existsInOriginal) {
+        let linesAdded = 0;
+        if (!binary) {
+          const content = await readFile(upperPath, "utf-8");
+          linesAdded = content.split(`
+`).length;
+        }
+        changes.push({
+          path: relPath,
+          type: "added",
+          linesAdded,
+          linesRemoved: 0,
+          isBinary: binary
+        });
+      } else {
+        const upperContent = await readFile(upperPath);
+        let originalContent;
+        try {
+          originalContent = await readFile(originalPath);
+        } catch {
+          changes.push({
+            path: relPath,
+            type: "added",
+            linesAdded: 0,
+            linesRemoved: 0,
+            isBinary: binary
+          });
+          continue;
+        }
+        const same = upperContent.equals(originalContent);
+        if (!same) {
+          let diff;
+          let linesAdded = 0;
+          let linesRemoved = 0;
+          if (!binary) {
+            const origText = originalContent.toString("utf-8");
+            const modText = upperContent.toString("utf-8");
+            diff = generateUnifiedDiff(origText, modText, relPath);
+            for (const line of diff.split(`
+`)) {
+              if (line.startsWith("+") && !line.startsWith("+++"))
+                linesAdded++;
+              if (line.startsWith("-") && !line.startsWith("---"))
+                linesRemoved++;
+            }
+          }
+          changes.push({
+            path: relPath,
+            type: "modified",
+            diff,
+            linesAdded,
+            linesRemoved,
+            isBinary: binary
+          });
+        }
+      }
+    }
+  } catch (err) {}
+  for (const originalFile of originalFiles) {
+    if (!upperFiles.has(originalFile)) {
+      const originalPath = join2(ctx.targetDir, originalFile);
+      const binary = await isBinaryFile(originalPath);
+      let linesRemoved = 0;
+      if (!binary) {
+        try {
+          const content = await readFile(originalPath, "utf-8");
+          linesRemoved = content.split(`
+`).length;
+        } catch {}
+      }
+      changes.push({
+        path: originalFile,
+        type: "deleted",
+        linesAdded: 0,
+        linesRemoved,
+        isBinary: binary
+      });
+    }
+  }
+  changes.sort((a, b) => a.path.localeCompare(b.path));
+  return changes;
+}
+
+// src/review.ts
+import * as readline from "readline";
+var colors = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  cyan: "\x1B[36m"
+};
+function colorize(text, color) {
+  return `${colors[color]}${text}${colors.reset}`;
+}
+function formatChangeType(type) {
+  switch (type) {
+    case "added":
+      return colorize("A", "green");
+    case "modified":
+      return colorize("M", "yellow");
+    case "deleted":
+      return colorize("D", "red");
+  }
+}
+function formatStats(change) {
+  if (change.isBinary)
+    return colorize("[binary]", "dim");
+  const parts = [];
+  if (change.linesAdded > 0)
+    parts.push(colorize(`+${change.linesAdded}`, "green"));
+  if (change.linesRemoved > 0)
+    parts.push(colorize(`-${change.linesRemoved}`, "red"));
+  return parts.length > 0 ? `(${parts.join(", ")})` : "";
+}
+function printSeparator() {
+  console.log(colorize("━".repeat(60), "dim"));
+}
+function printChangeSummary(changes, exitCode) {
+  printSeparator();
+  console.log(`  ${colorize("sandwrap", "bold")}: command exited with code ${exitCode}`);
+  console.log();
+  if (changes.length === 0) {
+    console.log("  No changes detected.");
+    printSeparator();
+    return;
+  }
+  console.log("  Changes detected:");
+  for (const change of changes) {
+    const typeStr = formatChangeType(change.type);
+    const stats = formatStats(change);
+    console.log(`    ${typeStr}  ${change.path.padEnd(30)} ${stats}`);
+  }
+  console.log();
+  const added = changes.filter((c) => c.type === "added").length;
+  const modified = changes.filter((c) => c.type === "modified").length;
+  const deleted = changes.filter((c) => c.type === "deleted").length;
+  console.log(`  Total: ${modified} modified, ${added} added, ${deleted} deleted`);
+  printSeparator();
+}
+function printDiff(change) {
+  if (!change.diff) {
+    if (change.isBinary) {
+      console.log(colorize("  [Binary file]", "dim"));
+    }
+    return;
+  }
+  for (const line of change.diff.split(`
+`)) {
+    if (line.startsWith("+++") || line.startsWith("---")) {
+      console.log(colorize(line, "bold"));
+    } else if (line.startsWith("+")) {
+      console.log(colorize(line, "green"));
+    } else if (line.startsWith("-")) {
+      console.log(colorize(line, "red"));
+    } else if (line.startsWith("@@")) {
+      console.log(colorize(line, "cyan"));
+    } else {
+      console.log(line);
+    }
+  }
+}
+async function prompt(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+async function selectFiles(changes) {
+  const selected = new Set(changes.map((c) => c.path));
+  console.log(`
+Select files to apply (enter number to toggle, 'done' to confirm):
+`);
+  const printList = () => {
+    for (let i = 0;i < changes.length; i++) {
+      const change = changes[i];
+      const check = selected.has(change.path) ? "[x]" : "[ ]";
+      const typeStr = formatChangeType(change.type);
+      console.log(`  ${i + 1}. ${check} ${typeStr}  ${change.path}`);
+    }
+  };
+  printList();
+  while (true) {
+    const answer = await prompt(`
+> `);
+    if (answer === "done" || answer === "d" || answer === "") {
+      break;
+    }
+    if (answer === "all" || answer === "a") {
+      for (const c of changes)
+        selected.add(c.path);
+      printList();
+      continue;
+    }
+    if (answer === "none" || answer === "n") {
+      selected.clear();
+      printList();
+      continue;
+    }
+    const num = parseInt(answer, 10);
+    if (num >= 1 && num <= changes.length) {
+      const path = changes[num - 1].path;
+      if (selected.has(path)) {
+        selected.delete(path);
+      } else {
+        selected.add(path);
+      }
+      printList();
+    }
+  }
+  return Array.from(selected);
+}
+async function reviewInteractively(changes) {
+  const filesToApply = [];
+  for (let i = 0;i < changes.length; i++) {
+    const change = changes[i];
+    console.log();
+    printSeparator();
+    console.log(`  Reviewing: ${change.path} (${i + 1}/${changes.length})`);
+    printSeparator();
+    console.log();
+    printDiff(change);
+    console.log();
+    printSeparator();
+    console.log("  [y] Apply  [n] Skip  [q] Quit review");
+    const answer = await prompt("> ");
+    if (answer === "y" || answer === "yes") {
+      filesToApply.push(change.path);
+      console.log(colorize(`  ✓ Will apply ${change.path}`, "green"));
+    } else if (answer === "q" || answer === "quit") {
+      break;
+    } else {
+      console.log(colorize(`  ✗ Skipped ${change.path}`, "dim"));
+    }
+  }
+  return filesToApply;
+}
+async function reviewChanges(changes, exitCode, autoApply, autoDiscard) {
+  printChangeSummary(changes, exitCode);
+  if (changes.length === 0) {
+    return { filesToApply: [], filesToDiscard: [] };
+  }
+  if (autoApply) {
+    console.log(colorize(`
+  Auto-applying all changes...`, "green"));
+    return {
+      filesToApply: changes.map((c) => c.path),
+      filesToDiscard: []
+    };
+  }
+  if (autoDiscard) {
+    console.log(colorize(`
+  Auto-discarding all changes...`, "yellow"));
+    return {
+      filesToApply: [],
+      filesToDiscard: changes.map((c) => c.path)
+    };
+  }
+  console.log(`
+What would you like to do?
+`);
+  console.log("  [a] Apply all changes");
+  console.log("  [d] Discard all changes");
+  console.log("  [r] Review changes interactively");
+  console.log("  [s] Select files to apply");
+  console.log("  [q] Quit (discard all)");
+  const answer = await prompt(`
+> `);
+  let filesToApply = [];
+  switch (answer) {
+    case "a":
+    case "apply":
+      filesToApply = changes.map((c) => c.path);
+      break;
+    case "d":
+    case "discard":
+    case "q":
+    case "quit":
+      break;
+    case "r":
+    case "review":
+      filesToApply = await reviewInteractively(changes);
+      break;
+    case "s":
+    case "select":
+      filesToApply = await selectFiles(changes);
+      break;
+    default:
+      console.log("Invalid option, discarding all changes.");
+  }
+  const filesToDiscard = changes.map((c) => c.path).filter((p) => !filesToApply.includes(p));
+  return { filesToApply, filesToDiscard };
+}
+
+// src/apply.ts
+import { join as join3, dirname } from "path";
+import { cp as cp2, rm as rm2, lstat as lstat2, mkdir as mkdir2 } from "fs/promises";
+var green = (s) => `\x1B[32m${s}\x1B[0m`;
+var red = (s) => `\x1B[31m${s}\x1B[0m`;
+async function isWhiteout(path) {
+  try {
+    const stats = await lstat2(path);
+    return stats.isCharacterDevice() && stats.rdev === 0;
+  } catch {
+    return false;
+  }
+}
+async function applyChanges(ctx, changes, filesToApply) {
+  const toApplySet = new Set(filesToApply);
+  let applied = 0;
+  let failed = 0;
+  for (const change of changes) {
+    if (!toApplySet.has(change.path))
+      continue;
+    const src = join3(ctx.upperDir, change.path);
+    const dst = join3(ctx.targetDir, change.path);
+    try {
+      if (change.type === "deleted" || await isWhiteout(src)) {
+        await rm2(dst, { recursive: true, force: true });
+        console.log(green(`  ✓ Deleted ${change.path}`));
+      } else {
+        await mkdir2(dirname(dst), { recursive: true });
+        await cp2(src, dst, { force: true, recursive: true, preserveTimestamps: true });
+        console.log(green(`  ✓ Applied ${change.path}`));
+      }
+      applied++;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.log(red(`  ✗ Failed to apply ${change.path}: ${message}`));
+      failed++;
+    }
+  }
+  const discarded = changes.length - applied - failed;
+  console.log();
+  console.log(`Done! ${applied} files applied` + (discarded > 0 ? `, ${discarded} discarded` : "") + (failed > 0 ? `, ${failed} failed` : "") + ".");
+}
+
+// index.ts
+var VERSION = "0.0.1";
+var HELP = `
+sandwrap - Run commands in a sandbox with filesystem isolation
+
+Usage:
+  sandwrap [options] <command> [args...]
+
+Options:
+  -n, --no-network    Disable network access inside sandbox
+  -k, --keep          Keep overlay directory after exit (for debugging)
+  -y, --auto-apply    Apply all changes without prompting
+  -d, --auto-discard  Discard all changes without prompting
+  -h, --help          Show this help message
+  -v, --version       Show version
+
+Examples:
+  sandwrap claude
+  sandwrap npm run build
+  sandwrap --no-network ./untrusted-script.sh
+
+After the command exits, you can review filesystem changes and
+selectively apply or discard them.
+`;
+function printHelp() {
+  console.log(HELP.trim());
+}
+function printVersion() {
+  console.log(`sandwrap v${VERSION}`);
+}
+function parseCliArgs() {
+  try {
+    const { values, positionals } = parseArgs({
+      args: process.argv.slice(2),
+      options: {
+        "no-network": { type: "boolean", short: "n", default: false },
+        keep: { type: "boolean", short: "k", default: false },
+        "auto-apply": { type: "boolean", short: "y", default: false },
+        "auto-discard": { type: "boolean", short: "d", default: false },
+        help: { type: "boolean", short: "h", default: false },
+        version: { type: "boolean", short: "v", default: false }
+      },
+      allowPositionals: true,
+      strict: true
+    });
+    if (values.help) {
+      printHelp();
+      process.exit(0);
+    }
+    if (values.version) {
+      printVersion();
+      process.exit(0);
+    }
+    if (positionals.length === 0) {
+      console.error(`Error: No command specified.
+`);
+      printHelp();
+      process.exit(1);
+    }
+    if (values["auto-apply"] && values["auto-discard"]) {
+      console.error("Error: Cannot use both --auto-apply and --auto-discard.");
+      process.exit(1);
+    }
+    return {
+      command: positionals,
+      noNetwork: values["no-network"] ?? false,
+      keep: values.keep ?? false,
+      autoApply: values["auto-apply"] ?? false,
+      autoDiscard: values["auto-discard"] ?? false
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  }
+}
+async function main() {
+  if (process.env.SANDWRAP) {
+    console.error("Error: Already running inside a sandwrap sandbox.");
+    console.error(`Sandbox ID: ${process.env.SANDWRAP_ID}`);
+    process.exit(1);
+  }
+  const options = parseCliArgs();
+  if (!options)
+    return;
+  await checkDependencies();
+  const targetDir = process.cwd();
+  let ctx = null;
+  const cleanup = async () => {
+    if (ctx && !options.keep) {
+      console.log(`
+Cleaning up sandbox...`);
+      await cleanupSandbox(ctx);
+    }
+    process.exit(130);
+  };
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+  try {
+    ctx = await createSandbox(targetDir);
+    console.log(`sandwrap: Starting sandbox (id: ${ctx.id})`);
+    console.log(`sandwrap: Running: ${options.command.join(" ")}`);
+    console.log();
+    const exitCode = await runInSandbox(ctx, options);
+    console.log();
+    const changes = await detectChanges(ctx);
+    const result = await reviewChanges(changes, exitCode, options.autoApply, options.autoDiscard);
+    if (result.filesToApply.length > 0) {
+      console.log();
+      await applyChanges(ctx, changes, result.filesToApply);
+    } else if (changes.length > 0) {
+      console.log(`
+No changes applied.`);
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  } finally {
+    if (ctx) {
+      if (options.keep) {
+        console.log(`
+Keeping overlay directory: ${ctx.tempDir}`);
+      } else {
+        await cleanupSandbox(ctx);
+      }
+    }
+  }
+}
+main();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "sandwrap",
+  "version": "0.0.1",
+  "description": "Run commands in a sandbox with filesystem isolation using bubblewrap",
+  "type": "module",
+  "bin": {
+    "sandwrap": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build index.ts --outdir dist --target node --format esm && { echo '#!/usr/bin/env node'; cat dist/index.js; } > dist/index.tmp && mv dist/index.tmp dist/index.js && chmod +x dist/index.js",
+    "prepublishOnly": "bun run build",
+    "start": "bun index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "sandbox",
+    "bubblewrap",
+    "bwrap",
+    "isolation",
+    "security",
+    "filesystem"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "linux"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^25.0.3"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}