sandboxbox 2.1.1 → 2.2.1

package/CLAUDE.md

@@ -1,272 +1,159 @@
 # SandboxBox Technical Documentation
 
-## Architecture Overview
-SandboxBox provides portable containerized development environments using Podman with automatic WSL machine management and Claude Code integration.
+## Architecture
+Portable containerized environments using Podman with automatic WSL management and Claude Code integration.
 
 ## Core Components
 
 ### CLI (cli.js)
-- Main entry point with automatic Podman machine management
-- Commands: build, run, shell, version, help
-- Auto-detects and starts Podman machine when needed
-- Shell execution with Windows compatibility (`shell: process.platform === 'win32'`)
+- Commands: build, run, shell, claude, version
+- Auto-detects and starts Podman machine
+- Shell execution: `shell: process.platform === 'win32'`
 
 ### Podman Downloader (scripts/download-podman.js)
 - Cross-platform binary downloads from GitHub releases
-- PowerShell ZIP extraction on Windows (no external dependencies)
-- Automatic version detection and binary path resolution
+- PowerShell ZIP extraction on Windows
+- Auto-detects existing installations
+- Auto-triggers on first use if Podman not found
+- Verifies binary existence post-download
+- Auto-initializes Podman machine on Windows after download
 
 ### Container Images
-- **sandboxbox-auth**: Full development environment with Claude Code
-- **sandboxbox-local**: Local repository workspace (symlink approach)
+- **sandboxbox:latest**: Full development environment
+- **sandboxbox-local:latest**: Claude Code with local repository
 
-## Windows Compatibility Fixes
+## Windows Compatibility
 
-### Critical PowerShell ZIP Extraction
+### Shell Execution Pattern
 ```javascript
-// scripts/download-podman.js:81
-execSync(`powershell -Command "${psCommand}"`, {
+execSync(command, {
   stdio: 'pipe',
-  cwd: __dirname,
-  shell: true  // REQUIRED for PowerShell commands
+  shell: process.platform === 'win32'
 });
 ```
 
-### Shell Execution Pattern
-All `execSync()` calls must include:
+### PowerShell ZIP Extraction
 ```javascript
-{
+execSync(`powershell -Command "${psCommand}"`, {
   stdio: 'pipe',
-  shell: process.platform === 'win32'  // Windows compatibility
-}
+  shell: true  // REQUIRED
+});
 ```
 
-### Windows Command Interpretation
-- **Avoid Unix-specific syntax**: `|| true` doesn't work on Windows
-- **Use platform-specific error handling**:
-  ```javascript
-  if (process.platform === 'win32') {
-    try {
-      execSync(`git remote remove origin`, { stdio: 'pipe', shell: true });
-    } catch (e) {
-      // Ignore if origin doesn't exist
-    }
-  } else {
-    execSync(`git remote remove origin 2>/dev/null || true`, { stdio: 'pipe', shell: true });
-  }
-  ```
+### Command Interpretation
+- Avoid Unix syntax: `|| true` fails on Windows
+- Use platform-specific error handling:
+```javascript
+if (process.platform === 'win32') {
+  try {
+    execSync(`git remote remove origin`, { stdio: 'pipe', shell: true });
+  } catch (e) { /* ignore */ }
+} else {
+  execSync(`git remote remove origin 2>/dev/null || true`, { stdio: 'pipe', shell: true });
+}
+```
 
-### Auto Podman Machine Management
+### Auto Podman Machine Start
 ```javascript
-// cli.js checkPodman() function
 if (process.platform === 'win32' && isBundled) {
   try {
-    execSync(`"${podmanPath}" info`, { ...execOptions, stdio: 'pipe' });
+    execSync(`"${podmanPath}" info`, { stdio: 'pipe' });
   } catch (infoError) {
     if (infoError.message.includes('Cannot connect to Podman')) {
-      // Auto-start existing machine
       execSync(`"${podmanPath}" machine start`, { stdio: 'inherit' });
     }
   }
 }
 ```
 
-## Claude Code Integration
-
-### Authentication Transfer
-Mount complete Claude session data:
-```bash
--v "$HOME/.claude:/root/.claude"
-```
-
-### Environment Variables
-Key variables to transfer:
-```bash
-ANTHROPIC_AUTH_TOKEN
-CLAUDECODE=1
-ANTHROPIC_BASE_URL
-```
-
-### Git Identity Transfer
-```bash
--v "$HOME/.gitconfig:/root/.gitconfig:ro"
--v "$HOME/.ssh:/root/.ssh:ro"
-```
-
-## Local Repository Workflow
-
-### Architecture
-- Container mounts local repo as `/project:rw`
-- Creates symlink `/workspace/project` → `/project`
-- Works directly with local repository (no cloning needed)
-- Changes persist to host folder automatically
-
-### Container Command
-```bash
-podman run --rm \
-  -v "/path/to/repo:/project:rw" \
-  -v "$HOME/.claude:/root/.claude" \
-  -v "$HOME/.gitconfig:/root/.gitconfig:ro" \
-  -v "$HOME/.ssh:/root/.ssh" \
-  -e "ANTHROPIC_AUTH_TOKEN=..." \
-  -e "CLAUDECODE=1" \
-  sandboxbox-local:latest
-```
-
-### Dockerfile.local-workspace
-```dockerfile
-# Creates symlink to mounted repository
-ln -sf "$REPO_PATH" "$WORKSPACE_DIR"
-cd "$WORKSPACE_DIR"
-exec claude  # Changes save directly to local repo
-```
-
-## Complete Workflow Example
-
-1. **Setup**: Build sandboxbox-local image
-2. **Mount**: Local repository as `/project:rw`
-3. **Auth Transfer**: Mount `.claude`, `.gitconfig`, `.ssh`
-4. **Edit**: Claude Code modifies files in `/workspace/project` (symlink to `/project`)
-5. **Commit**: Changes made directly to local repository
-6. **Persist**: No additional push/pull needed - changes already in host folder
-
-## Troubleshooting
-
-### "unzip command not found"
-**Solution**: Use PowerShell ZIP extraction with `shell: true`
-
-### "Cannot connect to Podman"
-**Solution**: Automatic machine start in checkPodman() function
-
-### Build context issues
-**Solution**: Use direct Podman build, then tag for SandboxBox
-
-### Git identity errors
-**Solution**: Mount `.gitconfig:ro` for user identity transfer
-
-### Path resolution issues
-**Solution**: Use explicit REPO_PATH environment variable
-
-## Command Isolation Principles
+## Isolation Architecture
 
-### Unified Architecture - All Commands Use Isolation
-- **`run` command**: Creates isolated temporary environment - changes DO NOT affect host
-- **`claude` command**: Creates isolated temporary environment - changes DO NOT affect host
-- **`shell` command**: Creates isolated temporary environment - changes DO NOT affect host
-
-### Isolation Workflow
-1. Copy project to temporary directory (including hidden files like .git)
+### Workflow
+1. Copy project to temporary directory (including .git)
 2. Mount temporary directory as /workspace in container
 3. Run commands in isolated environment
 4. Clean up temporary directory on exit
-5. Changes are persisted via git commands (commit/push) if needed
+5. Changes persist via git push to host repository
 
-### Shared Isolation Utility (utils/isolation.js)
+### Pattern
 ```javascript
-// All commands use the same isolation pattern
 import { createIsolatedEnvironment, setupCleanupHandlers, buildContainerMounts } from './utils/isolation.js';
 
-// Create isolated environment
 const { tempProjectDir, cleanup } = createIsolatedEnvironment(projectDir);
-
-// Set up cleanup handlers
 setupCleanupHandlers(cleanup);
+const mounts = buildContainerMounts(tempProjectDir, projectDir);
 
-// Build container mounts with git identity
-const mounts = buildContainerMounts(tempProjectDir);
-
-// Run command with isolated directory and git identity
 execSync(`podman run --rm -it ${mounts.join(' ')} -w /workspace sandboxbox:latest ${cmd}`, {
   stdio: 'inherit',
   shell: process.platform === 'win32'
 });
 
-// Clean up on completion
 cleanup();
 ```
 
+## Git Integration
+
 ### Git Identity Transfer
-All commands automatically mount git identity:
 ```bash
--v "$HOME/.gitconfig:/root/.gitconfig:ro"  # Git configuration
--v "$HOME/.ssh:/root/.ssh:ro"            # SSH keys for git operations
+-v "$HOME/.gitconfig:/root/.gitconfig:ro"
+-v "$HOME/.ssh:/root/.ssh:ro"
 ```
 
-### Host Repository Git Remote Setup
-For git push functionality from isolated containers:
+### Git Remote Setup
 ```bash
 # Mount host repository as accessible remote
 -v "/path/to/host/repo:/host-repo:rw"
 
-# Configure git remote to point to mounted host repository
+# Configure remote in container
 git remote add origin /host-repo
-git branch --set-upstream-to=origin/main main
 ```
 
-### Git Push Workflow Limitations
-- **Windows command quoting**: Complex git commands with spaces require bash wrapper
-- **Interactive shells**: Use `bash -c 'command'` for complex operations
-- **Command chaining**: Multiple git operations work better in single container session
-- **Bash command execution**: Commands like `bash -c 'command'` may start interactive shell instead of executing
+### Git Safe Directory Configuration
+```bash
+git config --global --add safe.directory /workspace
+git config --global --add safe.directory /host-repo
+git config --global --add safe.directory /host-repo/.git
+```
 
-### Git Remote Setup Requirements
-- **Automatic remote configuration**: `git remote add origin /host-repo`
-- **Upstream branch setup**: Use `git push -u origin master` instead of manual upstream configuration
-- **Host repository mounting**: Must mount original project as `/host-repo:rw` in container
-- **Git identity transfer**: Requires `.gitconfig` and `.ssh` directory mounting
-- **Windows path normalization**: Critical for cross-platform compatibility:
-  ```javascript
-  // Normalize paths for cross-platform compatibility
-  const normalizedTempDir = tempProjectDir.replace(/\\/g, '/');
-  ```
-- **Git safe directory configuration**: Required for mounted repositories:
-  ```bash
-  git config --global --add safe.directory /workspace
-  git config --global --add safe.directory /host-repo
-  git config --global --add safe.directory /host-repo/.git
-  ```
-- **Host repository push configuration**: Allow pushes to checked-out branch:
-  ```bash
-  git config receive.denyCurrentBranch ignore
-  ```
-- **Git identity setup**: Container requires explicit git user configuration:
-  ```bash
-  git config --global user.email "user@example.com"
-  git config --global user.name "User Name"
-  ```
+### Git Push Configuration
+```bash
+# Host repository - allow pushes to checked-out branch
+git config receive.denyCurrentBranch ignore
 
-### Claude Code MCP Integration
-The claude command includes MCP servers and settings:
+# Container - set git identity
+git config --global user.email "user@example.com"
+git config --global user.name "User Name"
+```
+
+### Windows Path Normalization
+```javascript
+const normalizedTempDir = tempProjectDir.replace(/\\/g, '/');
+```
+
+## Claude Code Integration
+
+### Authentication
 ```bash
-# MCP servers pre-installed in container
+-v "$HOME/.claude:/root/.claude"
+-e "ANTHROPIC_AUTH_TOKEN=..."
+-e "CLAUDECODE=1"
+```
+
+### MCP Servers
+```dockerfile
 RUN claude mcp add glootie -- npx -y mcp-glootie@latest
 RUN claude mcp add vexify -- npx -y mcp-vexify@latest
 RUN claude mcp add playwright -- npx @playwright/mcp@latest
-
-# Settings injection
--v "./claude-settings.json:/root/.claude/settings.json:ro"
--v "$HOME/.claude:/root/.claude-host:ro"
 ```
 
-### Container Naming and Cleanup
-- Use random short names: `sandboxbox-run-${Math.random().toString(36).substr(2, 9)}`
-- Force cleanup: `podman rm -f container-name`
-- Automatic cleanup handlers for all exit scenarios
-- Cross-platform signal handling (SIGINT, SIGTERM)
-
-### Cross-Platform Path Handling
-```javascript
-// Normalize Windows paths for podman cp command
-const normalizedProjectDir = projectDir.replace(/\\/g, '/');
-```
+## Cleanup
 
-## Version Management
-- Publish new version when fixing critical Windows issues
-- Clear npm cache: `npm cache clean --force`
-- Use specific version: `npx sandboxbox@latest`
+### Container Cleanup
+- Random names: `sandboxbox-run-${Math.random().toString(36).substr(2, 9)}`
+- Force cleanup: `podman rm -f container-name`
+- Automatic cleanup handlers for SIGINT, SIGTERM
 
-## File Cleanup Requirements
-- All temporary containers auto-cleanup on exit
+### File Cleanup
 - All temporary directories auto-cleanup on exit
 - Error handling for cleanup failures (ignore errors)
 - Signal handlers ensure cleanup on interrupts

package/cli.js

@@ -2,125 +2,13 @@
 
 /**
  * SandboxBox CLI - Portable Container Runner with Podman
- *
  * Cross-platform container runner using Podman with Claude Code integration
- * Works on Windows, macOS, and Linux
  */
 
-import { readFileSync, existsSync, writeFileSync } from 'fs';
-import { execSync } from 'child_process';
-import { resolve, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
+import { resolve } from 'path';
 import { color } from './utils/colors.js';
-import { checkPodman, getPodmanPath } from './utils/podman.js';
-import { buildClaudeContainerCommand, createClaudeDockerfile } from './utils/claude-workspace.js';
-import { createIsolatedEnvironment, setupCleanupHandlers, buildContainerMounts } from './utils/isolation.js';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-function showBanner() {
-  console.log(color('cyan', '📦 SandboxBox - Portable Container Runner'));
-  console.log(color('cyan', '═════════════════════════════════════════════════'));
-  console.log('');
-}
-
-function showHelp() {
-  console.log(color('yellow', 'Usage:'));
-  console.log('  npx sandboxbox <command> [options]');
-  console.log('');
-  console.log(color('yellow', 'Commands:'));
-  console.log('  build [dockerfile]            Build container from Dockerfile');
-  console.log('  run <project-dir> [cmd]       Run project in container');
-  console.log('  shell <project-dir>           Start interactive shell');
-  console.log('  claude <project-dir>          Start Claude Code with local repository');
-  console.log('  version                       Show version information');
-  console.log('');
-  console.log(color('yellow', 'Examples:'));
-  console.log('  npx sandboxbox build');
-  console.log('  npx sandboxbox claude ./my-project');
-  console.log('  npx sandboxbox run ./my-project "npm test"');
-  console.log('  npx sandboxbox shell ./my-project');
-  console.log('');
-  console.log(color('yellow', 'Requirements:'));
-  console.log('  - Podman (auto-downloaded if needed)');
-  console.log('  - Works on Windows, macOS, and Linux!');
-  console.log('');
-  console.log(color('magenta', '🚀 Fast startup • True isolation • Claude Code integration'));
-}
-
-function buildClaudeContainer() {
-  const dockerfilePath = resolve(__dirname, 'Dockerfile.claude');
-  const dockerfileContent = createClaudeDockerfile();
-
-  writeFileSync(dockerfilePath, dockerfileContent);
-  console.log(color('blue', '🏗️  Building Claude Code container...'));
-
-  const podmanPath = checkPodman();
-  if (!podmanPath) return false;
-
-  try {
-    execSync(`"${podmanPath}" build -f "${dockerfilePath}" -t sandboxbox-local:latest .`, {
-      stdio: 'inherit',
-      cwd: __dirname,
-      shell: process.platform === 'win32'
-    });
-    console.log(color('green', '\n✅ Claude Code container built successfully!'));
-    return true;
-  } catch (error) {
-    console.log(color('red', `\n❌ Build failed: ${error.message}`));
-    return false;
-  }
-}
-
-function runClaudeWorkspace(projectDir, command = 'claude') {
-  if (!existsSync(projectDir)) {
-    console.log(color('red', `❌ Project directory not found: ${projectDir}`));
-    return false;
-  }
-
-  if (!existsSync(resolve(projectDir, '.git'))) {
-    console.log(color('red', `❌ Not a git repository: ${projectDir}`));
-    console.log(color('yellow', 'Please run this command in a git repository directory'));
-    return false;
-  }
-
-  console.log(color('blue', '🚀 Starting Claude Code in isolated environment...'));
-  console.log(color('yellow', `Project: ${projectDir}`));
-  console.log(color('yellow', `Command: ${command}`));
-  console.log(color('cyan', '📦 Note: Changes will be isolated and will NOT affect the original repository\n'));
-
-  const podmanPath = checkPodman();
-  if (!podmanPath) return false;
-
-  try {
-    // Create isolated environment
-    const { tempProjectDir, cleanup } = createIsolatedEnvironment(projectDir);
-
-    // Set up cleanup handlers
-    setupCleanupHandlers(cleanup);
-
-    // Build container mounts with git identity and host remote
-    const mounts = buildContainerMounts(tempProjectDir, projectDir);
-
-    // Build claude-specific container command with mounts
-    const containerCommand = buildClaudeContainerCommand(tempProjectDir, podmanPath, command, mounts);
-    execSync(containerCommand, {
-      stdio: 'inherit',
-      shell: process.platform === 'win32'
-    });
-
-    // Clean up the temporary directory
-    cleanup();
-
-    console.log(color('green', '\n✅ Claude Code session completed! (Isolated - no host changes)'));
-    return true;
-  } catch (error) {
-    console.log(color('red', `\n❌ Claude Code failed: ${error.message}`));
-    return false;
-  }
-}
+import { showBanner, showHelp } from './utils/ui.js';
+import { buildCommand, runCommand, shellCommand, claudeCommand, versionCommand } from './utils/commands.js';
 
 async function main() {
   const args = process.argv.slice(2);
@@ -137,29 +25,7 @@ async function main() {
   switch (command) {
     case 'build':
       const dockerfilePath = commandArgs[0] || './Dockerfile';
-
-      if (!existsSync(dockerfilePath)) {
-        console.log(color('red', `❌ Dockerfile not found: ${dockerfilePath}`));
-        process.exit(1);
-      }
-
-      console.log(color('blue', '🏗️  Building container...'));
-      console.log(color('yellow', `Dockerfile: ${dockerfilePath}\n`));
-
-      const buildPodman = checkPodman();
-      if (!buildPodman) process.exit(1);
-
-      try {
-        execSync(`"${buildPodman}" build -f "${dockerfilePath}" -t sandboxbox:latest .`, {
-          stdio: 'inherit',
-          cwd: dirname(dockerfilePath),
-          shell: process.platform === 'win32'
-        });
-        console.log(color('green', '\n✅ Container built successfully!'));
-      } catch (error) {
-        console.log(color('red', `\n❌ Build failed: ${error.message}`));
-        process.exit(1);
-      }
+      if (!buildCommand(dockerfilePath)) process.exit(1);
       break;
 
     case 'run':
@@ -168,47 +34,9 @@ async function main() {
         console.log(color('yellow', 'Usage: npx sandboxbox run <project-dir> [command]'));
         process.exit(1);
       }
-
       const projectDir = resolve(commandArgs[0]);
       const cmd = commandArgs[1] || 'bash';
-
-      if (!existsSync(projectDir)) {
-        console.log(color('red', `❌ Project directory not found: ${projectDir}`));
-        process.exit(1);
-      }
-
-      console.log(color('blue', '🚀 Running project in isolated container...'));
-      console.log(color('yellow', `Project: ${projectDir}`));
-      console.log(color('yellow', `Command: ${cmd}\n`));
-      console.log(color('cyan', '📦 Note: Changes will NOT affect host files (isolated environment)'));
-
-      const runPodman = checkPodman();
-      if (!runPodman) process.exit(1);
-
-      try {
-        // Create isolated environment
-        const { tempProjectDir, cleanup } = createIsolatedEnvironment(projectDir);
-
-        // Set up cleanup handlers
-        setupCleanupHandlers(cleanup);
-
-        // Build container mounts with git identity and host remote
-        const mounts = buildContainerMounts(tempProjectDir, projectDir);
-
-        // Run the command in isolated container with temporary directory and git identity
-        execSync(`"${runPodman}" run --rm -it ${mounts.join(' ')} -w /workspace sandboxbox:latest ${cmd}`, {
-          stdio: 'inherit',
-          shell: process.platform === 'win32'
-        });
-
-        // Clean up the temporary directory
-        cleanup();
-
-        console.log(color('green', '\n✅ Container execution completed! (Isolated - no host changes)'));
-      } catch (error) {
-        console.log(color('red', `\n❌ Run failed: ${error.message}`));
-        process.exit(1);
-      }
+      if (!runCommand(projectDir, cmd)) process.exit(1);
       break;
 
     case 'shell':
@@ -217,43 +45,8 @@ async function main() {
         console.log(color('yellow', 'Usage: npx sandboxbox shell <project-dir>'));
         process.exit(1);
       }
-
       const shellProjectDir = resolve(commandArgs[0]);
-
-      if (!existsSync(shellProjectDir)) {
-        console.log(color('red', `❌ Project directory not found: ${shellProjectDir}`));
-        process.exit(1);
-      }
-
-      console.log(color('blue', '🐚 Starting interactive shell in isolated container...'));
-      console.log(color('yellow', `Project: ${shellProjectDir}\n`));
-      console.log(color('cyan', '📦 Note: Changes will NOT affect host files (isolated environment)'));
-
-      const shellPodman = checkPodman();
-      if (!shellPodman) process.exit(1);
-
-      try {
-        // Create isolated environment
-        const { tempProjectDir, cleanup } = createIsolatedEnvironment(shellProjectDir);
-
-        // Set up cleanup handlers
-        setupCleanupHandlers(cleanup);
-
-        // Build container mounts with git identity and host remote
-        const mounts = buildContainerMounts(tempProjectDir, shellProjectDir);
-
-        // Start interactive shell in isolated container with temporary directory and git identity
-        execSync(`"${shellPodman}" run --rm -it ${mounts.join(' ')} -w /workspace sandboxbox:latest /bin/bash`, {
-          stdio: 'inherit',
-          shell: process.platform === 'win32'
-        });
-
-        // Clean up the temporary directory
-        cleanup();
-      } catch (error) {
-        console.log(color('red', `\n❌ Shell failed: ${error.message}`));
-        process.exit(1);
-      }
+      if (!shellCommand(shellProjectDir)) process.exit(1);
       break;
 
     case 'claude':
@@ -262,40 +55,13 @@ async function main() {
         console.log(color('yellow', 'Usage: npx sandboxbox claude <project-dir>'));
         process.exit(1);
       }
-
       const claudeProjectDir = resolve(commandArgs[0]);
-      const claudeCommand = commandArgs.slice(1).join(' ') || 'claude';
-
-      // Check if Claude container exists, build if needed
-      const podmanPath = getPodmanPath();
-      try {
-        execSync(`"${podmanPath}" image inspect sandboxbox-local:latest`, {
-          stdio: 'pipe',
-          shell: process.platform === 'win32'
-        });
-      } catch {
-        console.log(color('yellow', '📦 Building Claude Code container...'));
-        if (!buildClaudeContainer()) {
-          process.exit(1);
-        }
-      }
-
-      if (!runClaudeWorkspace(claudeProjectDir, claudeCommand)) {
-        process.exit(1);
-      }
+      const claudeCmd = commandArgs.slice(1).join(' ') || 'claude';
+      if (!claudeCommand(claudeProjectDir, claudeCmd)) process.exit(1);
       break;
 
     case 'version':
-      try {
-        const packageJson = JSON.parse(readFileSync(resolve(__dirname, 'package.json'), 'utf-8'));
-        console.log(color('green', `SandboxBox v${packageJson.version}`));
-        console.log(color('cyan', 'Portable containers with Claude Code integration'));
-        if (checkPodman()) {
-          console.log('');
-        }
-      } catch (error) {
-        console.log(color('red', '❌ Could not read version'));
-      }
+      if (!versionCommand()) process.exit(1);
       break;
 
     default:

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "sandboxbox",
-  "version": "2.1.1",
+  "version": "2.2.1",
   "description": "Portable container runner with Podman - Claude Code & Playwright support. Works on Windows, macOS, and Linux.",
   "type": "module",
   "main": "cli.js",
   "bin": {
-    "sandboxbox": "./cli.js"
+    "sandboxbox": "cli.js"
   },
   "scripts": {
     "start": "node cli.js",
@@ -29,7 +29,7 @@
   "dependencies": {},
   "repository": {
     "type": "git",
-    "url": "https://github.com/AnEntrypoint/sandboxbox.git"
+    "url": "git+https://github.com/AnEntrypoint/sandboxbox.git"
   },
   "homepage": "https://github.com/AnEntrypoint/sandboxbox#readme",
   "bugs": {

package/scripts/download-podman.js

@@ -5,138 +5,16 @@
  * Similar to how sqlite/playwright auto-downloads platform-specific binaries
  */
 
-import { createWriteStream, existsSync, mkdirSync, chmodSync, unlinkSync, createReadStream, readdirSync, statSync } from 'fs';
-import { get as httpsGet } from 'https';
-import { get as httpGet } from 'http';
-import { join, dirname, sep } from 'path';
+import { existsSync, mkdirSync, chmodSync, unlinkSync } from 'fs';
+import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { execSync } from 'child_process';
-import { createGunzip } from 'zlib';
-import { pipeline } from 'stream/promises';
+import { PODMAN_VERSION, DOWNLOADS } from './podman-config.js';
+import { download, extractZip, extractTarGz } from './podman-extract.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const binDir = join(__dirname, '..', 'bin');
 
-// Podman remote client versions
-const PODMAN_VERSION = '4.9.3';
-
-// Get architecture
-const ARCH = process.arch === 'arm64' ? 'arm64' : 'amd64';
-
-const DOWNLOADS = {
-  win32: {
-    url: `https://github.com/containers/podman/releases/download/v${PODMAN_VERSION}/podman-remote-release-windows_amd64.zip`,
-    binary: 'podman.exe',
-    extract: 'unzip'
-  },
-  darwin: {
-    url: `https://github.com/containers/podman/releases/download/v${PODMAN_VERSION}/podman-remote-release-darwin_${ARCH}.tar.gz`,
-    binary: 'podman',
-    extract: 'tar'
-  },
-  linux: {
-    url: `https://github.com/containers/podman/releases/download/v${PODMAN_VERSION}/podman-remote-static-linux_${ARCH}.tar.gz`,
-    binary: `podman-remote-static-linux_${ARCH}`,
-    extract: 'tar'
-  }
-};
-
-function download(url, dest) {
-  return new Promise((resolve, reject) => {
-    const get = url.startsWith('https') ? httpsGet : httpGet;
-
-    get(url, (response) => {
-      if (response.statusCode === 302 || response.statusCode === 301) {
-        return download(response.headers.location, dest).then(resolve).catch(reject);
-      }
-
-      if (response.statusCode !== 200) {
-        reject(new Error(`Download failed: ${response.statusCode}`));
-        return;
-      }
-
-      const file = createWriteStream(dest);
-      response.pipe(file);
-
-      file.on('finish', () => {
-        file.close();
-        resolve();
-      });
-
-      file.on('error', reject);
-    }).on('error', reject);
-  });
-}
-
-// Simple ZIP extraction using built-in Node.js modules
-// Basic implementation that handles standard ZIP files without compression complications
-async function extractZip(zipPath, extractTo) {
-  return new Promise((resolve, reject) => {
-    try {
-      // For Windows, we'll use PowerShell's built-in ZIP extraction capability
-      // This is more reliable than expecting external tools
-      const psCommand = `Add-Type -AssemblyName System.IO.Compression.FileSystem; [System.IO.Compression.ZipFile]::ExtractToDirectory('${zipPath.replace(/'/g, "''")}', '${extractTo.replace(/'/g, "''")}')`;
-
-      execSync(`powershell -Command "${psCommand}"`, {
-        stdio: 'pipe',
-        cwd: __dirname,
-        shell: true
-      });
-
-      resolve();
-    } catch (error) {
-      reject(error);
-    }
-  });
-}
-
-// Extract tar.gz files using Node.js built-in modules
-async function extractTarGz(tarPath, extractTo, stripComponents = 0) {
-  return new Promise(async (resolve, reject) => {
-    try {
-      // First, decompress the .gz file
-      const tarWithoutGz = tarPath.replace('.gz', '');
-      const readStream = createReadStream(tarPath);
-      const writeStream = createWriteStream(tarWithoutGz);
-      const gunzip = createGunzip();
-
-      await pipeline(readStream, gunzip, writeStream);
-
-      // For tar extraction, we need to use system tar since implementing a full tar parser is complex
-      // But we'll ensure it works across platforms by providing fallbacks
-      try {
-        execSync(`tar -xf "${tarWithoutGz}" -C "${extractTo}"${stripComponents ? ` --strip-components=${stripComponents}` : ''}`, {
-          stdio: 'pipe',
-          shell: process.platform === 'win32'
-        });
-      } catch (tarError) {
-        // If system tar fails, try with specific flags for different platforms
-        if (process.platform === 'win32') {
-          // On Windows, try with different tar implementations
-          try {
-            execSync(`bsdtar -xf "${tarWithoutGz}" -C "${extractTo}"${stripComponents ? ` --strip-components=${stripComponents}` : ''}`, {
-              stdio: 'pipe',
-              shell: true
-            });
-          } catch (bsdtarError) {
-            throw new Error(`Failed to extract tar archive. Please install tar or bsdtar: ${tarError.message}`);
-          }
-        } else {
-          throw tarError;
-        }
-      }
-
-      // Clean up the intermediate .tar file
-      unlinkSync(tarWithoutGz);
-
-      resolve();
-    } catch (error) {
-      reject(error);
-    }
-  });
-}
-
 async function main() {
   const platform = process.platform;
 
@@ -148,7 +26,6 @@ async function main() {
     return;
   }
 
-  // Create bin directory
   if (!existsSync(binDir)) {
     mkdirSync(binDir, { recursive: true });
   }
@@ -156,7 +33,6 @@ async function main() {
   const { url, binary, extract } = DOWNLOADS[platform];
   const binaryPath = join(binDir, binary);
 
-  // Check if already downloaded
   if (existsSync(binaryPath)) {
     console.log(`✅ Podman already installed at ${binaryPath}`);
     return;
@@ -168,43 +44,35 @@ async function main() {
   const archivePath = join(binDir, archiveName);
 
   try {
-    // Clean up any previous failed extractions using fs operations
     const extractedDir = join(binDir, 'podman-4.9.3');
     if (existsSync(extractedDir)) {
       const fs = await import('fs/promises');
       await fs.rm(extractedDir, { recursive: true, force: true });
     }
 
-    // Download archive
     console.log(`   Downloading from GitHub releases...`);
     await download(url, archivePath);
     console.log(`✅ Downloaded successfully`);
 
-    // Extract based on platform
     console.log(`📦 Extracting...`);
     if (extract === 'tar') {
       await extractTarGz(archivePath, binDir, 1);
     } else if (extract === 'unzip') {
       await extractZip(archivePath, binDir);
 
-      // Windows-specific: move podman.exe from nested directory to bin/
       if (platform === 'win32') {
         const extractedDir = join(binDir, `podman-4.9.3`);
         const extractedPodman = join(extractedDir, 'usr', 'bin', 'podman.exe');
         const targetPodman = join(binDir, binary);
 
         if (existsSync(extractedPodman)) {
-          // Use fs operations instead of shell commands for cross-platform compatibility
           const fs = await import('fs/promises');
           await fs.copyFile(extractedPodman, targetPodman);
-
-          // Clean up the extracted directory
           await fs.rm(extractedDir, { recursive: true, force: true });
         }
       }
     }
 
-    // Make executable on Unix
     if (platform !== 'win32' && existsSync(binaryPath)) {
       chmodSync(binaryPath, 0o755);
     }
@@ -212,7 +80,6 @@ async function main() {
     console.log(`✅ Podman remote installed successfully!`);
     console.log(`   Binary: ${binaryPath}\n`);
 
-    // Clean up archive
     if (existsSync(archivePath)) {
       unlinkSync(archivePath);
     }
@@ -228,10 +95,9 @@ async function main() {
       console.log(`   sudo apt-get install podman  # Ubuntu/Debian`);
     }
     console.log(`\n   Or it will use system Podman if installed.\n`);
-    // Don't fail the npm install
   }
 }
 
 main().catch(() => {
   // Silently fail - will use system Podman
-});
+});

package/scripts/podman-config.js

@@ -0,0 +1,20 @@
+export const PODMAN_VERSION = '4.9.3';
+export const ARCH = process.arch === 'arm64' ? 'arm64' : 'amd64';
+
+export const DOWNLOADS = {
+  win32: {
+    url: `https://github.com/containers/podman/releases/download/v${PODMAN_VERSION}/podman-remote-release-windows_amd64.zip`,
+    binary: 'podman.exe',
+    extract: 'unzip'
+  },
+  darwin: {
+    url: `https://github.com/containers/podman/releases/download/v${PODMAN_VERSION}/podman-remote-release-darwin_${ARCH}.tar.gz`,
+    binary: 'podman',
+    extract: 'tar'
+  },
+  linux: {
+    url: `https://github.com/containers/podman/releases/download/v${PODMAN_VERSION}/podman-remote-static-linux_${ARCH}.tar.gz`,
+    binary: `podman-remote-static-linux_${ARCH}`,
+    extract: 'tar'
+  }
+};

package/scripts/podman-extract.js

@@ -0,0 +1,90 @@
+import { createWriteStream, createReadStream, unlinkSync } from 'fs';
+import { execSync } from 'child_process';
+import { createGunzip } from 'zlib';
+import { pipeline } from 'stream/promises';
+
+export async function extractZip(zipPath, extractTo) {
+  return new Promise((resolve, reject) => {
+    try {
+      const psCommand = `Add-Type -AssemblyName System.IO.Compression.FileSystem; [System.IO.Compression.ZipFile]::ExtractToDirectory('${zipPath.replace(/'/g, "''")}', '${extractTo.replace(/'/g, "''")}')`;
+
+      execSync(`powershell -Command "${psCommand}"`, {
+        stdio: 'pipe',
+        shell: true
+      });
+
+      resolve();
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+
+export async function extractTarGz(tarPath, extractTo, stripComponents = 0) {
+  return new Promise(async (resolve, reject) => {
+    try {
+      const tarWithoutGz = tarPath.replace('.gz', '');
+      const readStream = createReadStream(tarPath);
+      const writeStream = createWriteStream(tarWithoutGz);
+      const gunzip = createGunzip();
+
+      await pipeline(readStream, gunzip, writeStream);
+
+      try {
+        execSync(`tar -xf "${tarWithoutGz}" -C "${extractTo}"${stripComponents ? ` --strip-components=${stripComponents}` : ''}`, {
+          stdio: 'pipe',
+          shell: process.platform === 'win32'
+        });
+      } catch (tarError) {
+        if (process.platform === 'win32') {
+          try {
+            execSync(`bsdtar -xf "${tarWithoutGz}" -C "${extractTo}"${stripComponents ? ` --strip-components=${stripComponents}` : ''}`, {
+              stdio: 'pipe',
+              shell: true
+            });
+          } catch (bsdtarError) {
+            throw new Error(`Failed to extract tar archive. Please install tar or bsdtar: ${tarError.message}`);
+          }
+        } else {
+          throw tarError;
+        }
+      }
+
+      unlinkSync(tarWithoutGz);
+      resolve();
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+
+export function download(url, dest) {
+  return new Promise(async (resolve, reject) => {
+    const { get: httpsGet } = await import('https');
+    const { get: httpGet } = await import('http');
+    const { createWriteStream } = await import('fs');
+
+    const get = url.startsWith('https') ? httpsGet : httpGet;
+
+    get(url, (response) => {
+      if (response.statusCode === 302 || response.statusCode === 301) {
+        return download(response.headers.location, dest).then(resolve).catch(reject);
+      }
+
+      if (response.statusCode !== 200) {
+        reject(new Error(`Download failed: ${response.statusCode}`));
+        return;
+      }
+
+      const file = createWriteStream(dest);
+      response.pipe(file);
+
+      file.on('finish', () => {
+        file.close();
+        resolve();
+      });
+
+      file.on('error', reject);
+    }).on('error', reject);
+  });
+}

package/utils/commands.js

@@ -0,0 +1,193 @@
+import { readFileSync, existsSync, writeFileSync } from 'fs';
+import { execSync } from 'child_process';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { color } from './colors.js';
+import { checkPodman, getPodmanPath } from './podman.js';
+import { buildClaudeContainerCommand, createClaudeDockerfile } from './claude-workspace.js';
+import { createIsolatedEnvironment, setupCleanupHandlers, buildContainerMounts } from './isolation.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export function buildCommand(dockerfilePath) {
+  if (!existsSync(dockerfilePath)) {
+    console.log(color('red', `❌ Dockerfile not found: ${dockerfilePath}`));
+    return false;
+  }
+
+  console.log(color('blue', '🏗️  Building container...'));
+  console.log(color('yellow', `Dockerfile: ${dockerfilePath}\n`));
+
+  const podmanPath = checkPodman();
+  if (!podmanPath) return false;
+
+  try {
+    execSync(`"${podmanPath}" build -f "${dockerfilePath}" -t sandboxbox:latest .`, {
+      stdio: 'inherit',
+      cwd: dirname(dockerfilePath),
+      shell: process.platform === 'win32'
+    });
+    console.log(color('green', '\n✅ Container built successfully!'));
+    return true;
+  } catch (error) {
+    console.log(color('red', `\n❌ Build failed: ${error.message}`));
+    return false;
+  }
+}
+
+export function runCommand(projectDir, cmd = 'bash') {
+  if (!existsSync(projectDir)) {
+    console.log(color('red', `❌ Project directory not found: ${projectDir}`));
+    return false;
+  }
+
+  console.log(color('blue', '🚀 Running project in isolated container...'));
+  console.log(color('yellow', `Project: ${projectDir}`));
+  console.log(color('yellow', `Command: ${cmd}\n`));
+  console.log(color('cyan', '📦 Note: Changes will NOT affect host files (isolated environment)'));
+
+  const podmanPath = checkPodman();
+  if (!podmanPath) return false;
+
+  try {
+    const { tempProjectDir, cleanup } = createIsolatedEnvironment(projectDir);
+    setupCleanupHandlers(cleanup);
+    const mounts = buildContainerMounts(tempProjectDir, projectDir);
+
+    execSync(`"${podmanPath}" run --rm -it ${mounts.join(' ')} -w /workspace sandboxbox:latest ${cmd}`, {
+      stdio: 'inherit',
+      shell: process.platform === 'win32'
+    });
+
+    cleanup();
+    console.log(color('green', '\n✅ Container execution completed! (Isolated - no host changes)'));
+    return true;
+  } catch (error) {
+    console.log(color('red', `\n❌ Run failed: ${error.message}`));
+    return false;
+  }
+}
+
+export function shellCommand(projectDir) {
+  if (!existsSync(projectDir)) {
+    console.log(color('red', `❌ Project directory not found: ${projectDir}`));
+    return false;
+  }
+
+  console.log(color('blue', '🐚 Starting interactive shell in isolated container...'));
+  console.log(color('yellow', `Project: ${projectDir}\n`));
+  console.log(color('cyan', '📦 Note: Changes will NOT affect host files (isolated environment)'));
+
+  const podmanPath = checkPodman();
+  if (!podmanPath) return false;
+
+  try {
+    const { tempProjectDir, cleanup } = createIsolatedEnvironment(projectDir);
+    setupCleanupHandlers(cleanup);
+    const mounts = buildContainerMounts(tempProjectDir, projectDir);
+
+    execSync(`"${podmanPath}" run --rm -it ${mounts.join(' ')} -w /workspace sandboxbox:latest /bin/bash`, {
+      stdio: 'inherit',
+      shell: process.platform === 'win32'
+    });
+
+    cleanup();
+    return true;
+  } catch (error) {
+    console.log(color('red', `\n❌ Shell failed: ${error.message}`));
+    return false;
+  }
+}
+
+export function claudeCommand(projectDir, command = 'claude') {
+  if (!existsSync(projectDir)) {
+    console.log(color('red', `❌ Project directory not found: ${projectDir}`));
+    return false;
+  }
+
+  if (!existsSync(resolve(projectDir, '.git'))) {
+    console.log(color('red', `❌ Not a git repository: ${projectDir}`));
+    console.log(color('yellow', 'Please run this command in a git repository directory'));
+    return false;
+  }
+
+  const podmanPath = getPodmanPath();
+  try {
+    execSync(`"${podmanPath}" image inspect sandboxbox-local:latest`, {
+      stdio: 'pipe',
+      shell: process.platform === 'win32'
+    });
+  } catch {
+    console.log(color('yellow', '📦 Building Claude Code container...'));
+    if (!buildClaudeContainer()) {
+      return false;
+    }
+  }
+
+  console.log(color('blue', '🚀 Starting Claude Code in isolated environment...'));
+  console.log(color('yellow', `Project: ${projectDir}`));
+  console.log(color('yellow', `Command: ${command}`));
+  console.log(color('cyan', '📦 Note: Changes will be isolated and will NOT affect the original repository\n'));
+
+  const buildPodman = checkPodman();
+  if (!buildPodman) return false;
+
+  try {
+    const { tempProjectDir, cleanup } = createIsolatedEnvironment(projectDir);
+    setupCleanupHandlers(cleanup);
+    const mounts = buildContainerMounts(tempProjectDir, projectDir);
+    const containerCommand = buildClaudeContainerCommand(tempProjectDir, buildPodman, command, mounts);
+
+    execSync(containerCommand, {
+      stdio: 'inherit',
+      shell: process.platform === 'win32'
+    });
+
+    cleanup();
+    console.log(color('green', '\n✅ Claude Code session completed! (Isolated - no host changes)'));
+    return true;
+  } catch (error) {
+    console.log(color('red', `\n❌ Claude Code failed: ${error.message}`));
+    return false;
+  }
+}
+
+export function versionCommand() {
+  try {
+    const packageJson = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf-8'));
+    console.log(color('green', `SandboxBox v${packageJson.version}`));
+    console.log(color('cyan', 'Portable containers with Claude Code integration'));
+    if (checkPodman()) {
+      console.log('');
+    }
+    return true;
+  } catch (error) {
+    console.log(color('red', '❌ Could not read version'));
+    return false;
+  }
+}
+
+function buildClaudeContainer() {
+  const dockerfilePath = resolve(__dirname, '../Dockerfile.claude');
+  const dockerfileContent = createClaudeDockerfile();
+
+  writeFileSync(dockerfilePath, dockerfileContent);
+  console.log(color('blue', '🏗️  Building Claude Code container...'));
+
+  const podmanPath = checkPodman();
+  if (!podmanPath) return false;
+
+  try {
+    execSync(`"${podmanPath}" build -f "${dockerfilePath}" -t sandboxbox-local:latest .`, {
+      stdio: 'inherit',
+      cwd: dirname(__dirname),
+      shell: process.platform === 'win32'
+    });
+    console.log(color('green', '\n✅ Claude Code container built successfully!'));
+    return true;
+  } catch (error) {
+    console.log(color('red', `\n❌ Build failed: ${error.message}`));
+    return false;
+  }
+}

package/utils/podman.js

@@ -76,28 +76,47 @@ export function checkPodman() {
 
     return podmanPath;
   } catch (error) {
-    if (!isBundled) {
-      console.log('❌ Podman not found');
-      console.log('\n📦 Auto-downloading Podman...');
+    console.log('❌ Podman not found');
+    console.log('\n📦 Auto-downloading Podman...');
 
-      try {
-        const scriptPath = resolve(__dirname, '..', 'scripts', 'download-podman.js');
-        execSync(`node "${scriptPath}"`, { stdio: 'inherit', cwd: __dirname, shell: process.platform === 'win32' });
-
-        const newPodmanPath = getPodmanPath();
-        const execOptions = {
-          encoding: 'utf-8',
-          stdio: 'pipe',
-          shell: process.platform === 'win32'
-        };
-        const newVersion = execSync(`"${newPodmanPath}" --version`, execOptions).trim();
-        console.log(`\n✅ ${newVersion} (auto-downloaded)`);
-        return newPodmanPath;
-      } catch (downloadError) {
-        console.log(`\n❌ Auto-download failed: ${downloadError.message}`);
+    try {
+      const scriptPath = resolve(__dirname, '..', 'scripts', 'download-podman.js');
+      execSync(`node "${scriptPath}"`, { stdio: 'inherit', cwd: __dirname, shell: process.platform === 'win32' });
+
+      const newPodmanPath = getPodmanPath();
+      if (!existsSync(newPodmanPath) && newPodmanPath !== 'podman') {
+        throw new Error('Download completed but binary not found');
       }
-    } else {
-      console.log('❌ Podman not found');
+
+      const execOptions = {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+        shell: process.platform === 'win32'
+      };
+
+      const newVersion = execSync(`"${newPodmanPath}" --version`, execOptions).trim();
+      console.log(`\n✅ ${newVersion} (auto-downloaded)`);
+
+      if (process.platform === 'win32') {
+        try {
+          execSync(`"${newPodmanPath}" info`, { ...execOptions, stdio: 'pipe' });
+        } catch (infoError) {
+          if (infoError.message.includes('Cannot connect to Podman')) {
+            console.log('\n🔧 Initializing Podman machine...');
+            try {
+              execSync(`"${newPodmanPath}" machine init`, { stdio: 'inherit', shell: true });
+              execSync(`"${newPodmanPath}" machine start`, { stdio: 'inherit', shell: true });
+              console.log('\n✅ Podman machine initialized and started!');
+            } catch (machineError) {
+              console.log('\n⚠️  Podman machine initialization will be done on first use');
+            }
+          }
+        }
+      }
+
+      return newPodmanPath;
+    } catch (downloadError) {
+      console.log(`\n❌ Auto-download failed: ${downloadError.message}`);
     }
 
     console.log('\n💡 Please install Podman manually:');

package/utils/ui.js

@@ -0,0 +1,31 @@
+import { color } from './colors.js';
+
+export function showBanner() {
+  console.log(color('cyan', '📦 SandboxBox - Portable Container Runner'));
+  console.log(color('cyan', '═════════════════════════════════════════════════'));
+  console.log('');
+}
+
+export function showHelp() {
+  console.log(color('yellow', 'Usage:'));
+  console.log('  npx sandboxbox <command> [options]');
+  console.log('');
+  console.log(color('yellow', 'Commands:'));
+  console.log('  build [dockerfile]            Build container from Dockerfile');
+  console.log('  run <project-dir> [cmd]       Run project in container');
+  console.log('  shell <project-dir>           Start interactive shell');
+  console.log('  claude <project-dir>          Start Claude Code with local repository');
+  console.log('  version                       Show version information');
+  console.log('');
+  console.log(color('yellow', 'Examples:'));
+  console.log('  npx sandboxbox build');
+  console.log('  npx sandboxbox claude ./my-project');
+  console.log('  npx sandboxbox run ./my-project "npm test"');
+  console.log('  npx sandboxbox shell ./my-project');
+  console.log('');
+  console.log(color('yellow', 'Requirements:'));
+  console.log('  - Podman (auto-downloaded if needed)');
+  console.log('  - Works on Windows, macOS, and Linux!');
+  console.log('');
+  console.log(color('magenta', '🚀 Fast startup • True isolation • Claude Code integration'));
+}