sandboxbox 2.2.8 → 2.3.0

package/CLAUDE.md

@@ -5,10 +5,11 @@ Portable containerized environments using Podman with automatic WSL management a
 
 ## Core Components
 
-### CLI (cli.js)
-- Commands: build, run, shell, claude, version
-- Auto-detects and starts Podman machine
-- Shell execution: `shell: process.platform === 'win32'`
+### CLI Architecture
+- **Entry**: cli.js (main entry point)
+- **Commands**: utils/commands/container.js (build, run, shell), utils/commands/claude.js (claude), utils/commands/index.js (version + exports)
+- **Pattern**: Modular command structure, each file <100 lines
+- **Shell execution**: `shell: process.platform === 'win32'` for all execSync calls
 
 ### Podman Downloader (scripts/download-podman.js)
 - Cross-platform binary downloads from GitHub releases
@@ -18,7 +19,6 @@ Portable containerized environments using Podman with automatic WSL management a
 - 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:latest**: Full development environment
@@ -55,36 +55,22 @@ if (process.platform === 'win32') {
 }
 ```
 
-### Auto Podman Machine Start (Rootless Mode)
-```javascript
-// Initialize with explicit rootless mode for portability
-if (process.platform === 'win32' && isBundled) {
-  try {
-    execSync(`"${podmanPath}" info`, { stdio: 'pipe' });
-  } catch (infoError) {
-    if (infoError.message.includes('Cannot connect to Podman')) {
-      // Auto-initialize with rootless mode if machine doesn't exist
-      execSync(`"${podmanPath}" machine init --rootful=false`, { stdio: 'inherit' });
-      execSync(`"${podmanPath}" machine start`, { stdio: 'inherit' });
-    }
-  }
-}
-```
-
-### Rootless vs Rootful Mode
-- **Rootless (default)**: Runs without administrator privileges, portable across systems
-- **Configuration**: All machines initialized with `--rootful=false` flag
-- **Benefits**: No elevated permissions required, better security, true portability
-
-### Portable Podman Architecture
-- **Direct Podman Execution**: Uses bundled Podman binary without complex machine management
-- **Rootless Operation**: Always runs in rootless mode for portability (--rootful=false)
-- **Self-Contained**: All dependencies included in the package
-- **Simple Configuration**: Minimal backend setup only when needed
-- **Auto-Download**: Downloads platform-specific binaries automatically
+### Automatic Backend Setup
+**Implementation**: `ensureBackend(podmanPath)` in utils/podman.js
+- Linux: Returns immediately (native execution, no backend needed)
+- Windows/macOS: Checks `podman info` connectivity
+- Auto-initializes on first run: `podman machine init --rootful=false` (Windows) or `podman machine init` (macOS)
+- Auto-starts machine: `podman machine start`
+- Shows progress: "Initializing Podman backend (first run, takes 2-3 minutes)"
+- Detects existing machines via `podman machine list --format json`
+- Called before all container operations (build, run, shell, claude)
+
+### Portable Architecture
+- **Binary Auto-Download**: Platform-specific Podman binary (amd64/arm64) from GitHub releases
+- **Rootless Mode**: Windows uses `--rootful=false` for portability
+- **Backend Automation**: Fully automatic backend initialization on first container operation
 - **NPX Compatible**: Works via npx without global installation
-- **Architecture Support**: Auto-detects and downloads correct binary (amd64 or arm64)
-- **Cross-Platform**: Windows, macOS, Linux - all with amd64/arm64 support
+- **Cross-Platform**: Windows (amd64/arm64), macOS (amd64/arm64), Linux (amd64/arm64)
 
 ## Isolation Architecture
 

package/cli.js

@@ -8,7 +8,7 @@
 import { resolve } from 'path';
 import { color } from './utils/colors.js';
 import { showBanner, showHelp } from './utils/ui.js';
-import { buildCommand, runCommand, shellCommand, claudeCommand, versionCommand } from './utils/commands.js';
+import { buildCommand, runCommand, shellCommand, claudeCommand, versionCommand } from './utils/commands/index.js';
 
 async function main() {
   const args = process.argv.slice(2);

package/npx-test-sandboxbox/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "npx-test-sandboxbox",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": ""
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandboxbox",
-  "version": "2.2.8",
+  "version": "2.3.0",
   "description": "Portable container runner with Podman - Claude Code & Playwright support. Works on Windows, macOS, and Linux.",
   "type": "module",
   "main": "cli.js",

package/utils/commands/claude.js

@@ -0,0 +1,90 @@
+import { 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, ensureBackend, 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 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;
+  if (!ensureBackend(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;
+  }
+}
+
+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;
+  if (!ensureBackend(podmanPath)) return false;
+
+  try {
+    execSync(`"${podmanPath}" build -f "${dockerfilePath}" -t sandboxbox-local:latest .`, {
+      stdio: 'inherit',
+      cwd: resolve(__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/commands/container.js

@@ -0,0 +1,99 @@
+import { existsSync } from 'fs';
+import { execSync } from 'child_process';
+import { dirname } from 'path';
+import { color } from '../colors.js';
+import { checkPodman, ensureBackend } from '../podman.js';
+import { createIsolatedEnvironment, setupCleanupHandlers, buildContainerMounts } from '../isolation.js';
+
+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;
+  if (!ensureBackend(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;
+  if (!ensureBackend(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;
+  if (!ensureBackend(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;
+  }
+}

package/utils/commands/index.js

@@ -0,0 +1,26 @@
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { color } from '../colors.js';
+import { checkPodman } from '../podman.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export { buildCommand, runCommand, shellCommand } from './container.js';
+export { claudeCommand } from './claude.js';
+
+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;
+  }
+}

package/utils/podman.js

@@ -26,6 +26,42 @@ export function getPodmanPath() {
   return 'podman';
 }
 
+export function ensureBackend(podmanPath) {
+  if (process.platform === 'linux') return true;
+
+  const execOptions = { encoding: 'utf-8', stdio: 'pipe', shell: true };
+
+  try {
+    execSync(`"${podmanPath}" info`, execOptions);
+    return true;
+  } catch (infoError) {
+    if (!infoError.message.includes('Cannot connect to Podman')) throw infoError;
+
+    console.log(color('yellow', '\n🔧 Initializing Podman backend (first run, takes 2-3 minutes)...'));
+
+    try {
+      const machineListOutput = execSync(`"${podmanPath}" machine list --format json`, execOptions);
+      const machines = JSON.parse(machineListOutput || '[]');
+
+      if (machines.length === 0) {
+        console.log(color('cyan', '   Creating Podman machine...'));
+        const initCmd = process.platform === 'win32'
+          ? `"${podmanPath}" machine init --rootful=false`
+          : `"${podmanPath}" machine init`;
+        execSync(initCmd, { stdio: 'inherit', shell: true });
+      }
+
+      console.log(color('cyan', '   Starting Podman machine...'));
+      execSync(`"${podmanPath}" machine start`, { stdio: 'inherit', shell: true });
+      console.log(color('green', '✅ Podman backend ready\n'));
+      return true;
+    } catch (backendError) {
+      console.log(color('red', `\n❌ Backend setup failed: ${backendError.message}`));
+      return false;
+    }
+  }
+}
+
 export function checkPodman() {
   const podmanPath = getPodmanPath();
   const isBundled = podmanPath.includes('bin');

package/utils/commands.js

@@ -1,193 +0,0 @@
-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;
-  }
-}