bx-mac 0.1.5 → 0.3.0

package/README.md

@@ -1,38 +1,38 @@
-# bx
+# 📦 bx
 
-Launch VSCode, a terminal, Claude Code, or any command in a macOS sandbox. Your tools can only see the project you're working on — not your private files, SSH keys, or other repositories.
+> **Put your AI in a box.** Launch VSCode, Claude Code, a terminal, or any command in a macOS sandbox — your tools can only see the project you're working on.
 
-## Why?
+## 🤔 Why?
 
-AI-powered coding tools like Claude Code, Copilot, or Cline run with broad file system access. A misguided tool call or hallucinated path could accidentally read your SSH keys, credentials, tax documents, or private photos.
+AI-powered coding tools like Claude Code, Copilot, or Cline run with **broad file system access**. A misguided tool call or hallucinated path could accidentally read your SSH keys, credentials, tax documents, or private photos.
 
 **bx** wraps any application in a macOS sandbox (`sandbox-exec`) that blocks access to everything except the project directory you explicitly specify. No containers, no VMs, no setup — just one command.
 
-## What it does
+```bash
+bx ~/work/my-project
+```
+
+That's it. 🎉 VSCode opens with full access to `~/work/my-project` and nothing else.
 
-- Blocks access to `~/Documents`, `~/Desktop`, `~/Downloads`, and all other personal folders
-- Blocks access to sibling projects — only the directory you specify is accessible
-- Protects sensitive dotdirs like `~/.ssh`, `~/.gnupg`, `~/.docker`, `~/.cargo` by default
-- Keeps VSCode, extensions, shell, Node.js, and other tooling fully functional
-- Generates sandbox rules dynamically based on your actual `$HOME` contents
-- Supports `.bxignore` to hide secrets like `.env` files within a project
-- Supports `~/.bxallow` to grant access to shared utility directories
+## ✅ What it does
 
-## What it doesn't do
+- 🔒 Blocks `~/Documents`, `~/Desktop`, `~/Downloads`, and all other personal folders
+- 🚧 Blocks sibling projects — only the directory you specify is accessible
+- 🛡️ Protects sensitive dotdirs like `~/.ssh`, `~/.gnupg`, `~/.docker`, `~/.cargo`
+- ⚙️ Keeps VSCode, extensions, shell, Node.js, and other tooling fully functional
+- 🔍 Generates sandbox rules dynamically based on your actual `$HOME` contents
+- 📝 Supports `.bxignore` to hide secrets like `.env` files within a project
+- 📂 Supports `~/.bxallow` to grant access to shared utility directories
+
+## 🚫 What it doesn't do
 
 - **No network restrictions** — API calls, git push/pull, npm install all work normally
 - **No process isolation** — this is file-level sandboxing, not a container
 - **No protection against root/sudo** — the sandbox applies to the user-level process
-- **macOS only** — relies on `sandbox-exec` which is an Apple-specific technology
-- **Not a security guarantee** — `sandbox-exec` is undocumented and may have limitations; treat this as a safety net, not a vault
-
-## Requirements
-
-- macOS (tested on Sequoia / macOS 15)
-- Node.js >= 22
-- Visual Studio Code installed in `/Applications` (for `code` mode)
+- **macOS only** — relies on `sandbox-exec` (Apple-specific)
+- **Not a vault** — `sandbox-exec` is undocumented; treat this as a safety net, not a guarantee
 
-## Install
+## 📥 Install
 
 ```bash
 # Homebrew
@@ -48,71 +48,65 @@ pnpm install && pnpm build
 pnpm link -g
 ```
 
-## Quick start
+**Requirements:** macOS (tested on Sequoia 15), Node.js >= 22
 
-```bash
-# Launch VSCode with sandbox protection
-bx ~/work/my-project
-```
+## 🚀 Modes
 
-That's it. VSCode opens with full access to `~/work/my-project` and nothing else.
-
-## Modes
-
-```bash
-bx [workdir]                            # VSCode (default)
-bx code [workdir]                       # VSCode (explicit)
-bx term [workdir]                       # sandboxed login shell ($SHELL -l)
-bx claude [workdir]                     # Claude Code CLI
-bx exec [workdir] -- command [args...]  # arbitrary command
-```
+| Command | What it launches |
+|---|---|
+| `bx [workdir]` | 🖥️ VSCode (default) |
+| `bx code [workdir]` | 🖥️ VSCode (explicit) |
+| `bx term [workdir]` | 💻 Sandboxed login shell (`$SHELL -l`) |
+| `bx claude [workdir]` | 🤖 Claude Code CLI |
+| `bx exec [workdir] -- cmd` | ⚡ Any command you want |
 
 If no directory is given, the current directory is used.
 
 ### Examples
 
 ```bash
-# Work on a project in a sandboxed terminal
+# 🖥️ VSCode with sandbox protection
+bx ~/work/my-project
+
+# 💻 Work on a project in a sandboxed terminal
 bx term ~/work/my-project
 
-# Let Claude Code work on a project without access to anything else
+# 🤖 Let Claude Code work on a project — nothing else visible
 bx claude ~/work/my-project
 
-# Run a script in a sandbox
+# ⚡ Run a script in a sandbox
 bx exec ~/work/my-project -- python train.py
 
-# VSCode with verbose output
+# 🔍 See the generated sandbox profile
 bx --verbose ~/work/my-project
 ```
 
-## Options
+## ⚙️ Options
 
 | Option | Description |
 |---|---|
 | `--verbose` | Print the generated sandbox profile to stderr |
-| `--profile-sandbox` | Use an isolated VSCode profile (separate extensions and settings, `code` mode only) |
+| `--profile-sandbox` | Use an isolated VSCode profile (separate extensions/settings, `code` mode only) |
 
-## Configuration
+## 📝 Configuration
 
-bx uses three optional config files, all with the same format: one entry per line, `#` for comments.
+bx uses three optional config files — one entry per line, `#` for comments.
 
 ### `~/.bxallow`
 
-Allow extra directories beyond the working directory. Paths are relative to `$HOME`.
+Allow extra directories beyond the working directory. Paths relative to `$HOME`.
 
 ```gitignore
 # Shared shell scripts and utilities
 work/bin
-# Shared libraries used across projects
 shared/libs
 ```
 
 ### `~/.bxignore`
 
-Block additional dotdirs or files in your home. Paths are relative to `$HOME`.
+Block additional dotdirs or files in your home. Paths relative to `$HOME`.
 
 ```gitignore
-# Cloud provider credentials
 .aws
 .azure
 .kube
@@ -121,74 +115,70 @@ Block additional dotdirs or files in your home. Paths are relative to `$HOME`.
 
 These are blocked **in addition** to the built-in protected list:
 
-> `.Trash` `.ssh` `.gnupg` `.docker` `.zsh_sessions` `.cargo` `.gradle` `.gem`
+> 🔒 `.Trash` `.ssh` `.gnupg` `.docker` `.zsh_sessions` `.cargo` `.gradle` `.gem`
 
 ### `<project>/.bxignore`
 
-Block paths within the working directory itself. Supports glob patterns.
+Block paths within the working directory. Supports glob patterns.
 
 ```gitignore
-# Environment files with secrets
 .env
 .env.*
-
-# Credentials and keys
 secrets/
 **/*.pem
 **/*.key
 ```
 
-## How it works
+## 🔧 How it works
 
 bx generates a macOS sandbox profile at launch time:
 
 1. **Scan** `$HOME` for non-hidden directories
-2. **Block** each one individually with a `(deny file* (subpath ...))` rule
-3. **Skip** the working directory, `~/Library`, dotfiles, and any paths from `~/.bxallow`
-4. **Descend** into parent directories of allowed paths to block only siblings (because SBPL deny rules always override allow rules — you can't deny a parent and allow a child)
+2. **Block** each one individually with `(deny file* (subpath ...))`
+3. **Skip** the working directory, `~/Library`, dotfiles, and `~/.bxallow` paths
+4. **Descend** into parent directories of allowed paths to block only siblings (because SBPL deny rules always override allow rules)
 5. **Append** deny rules for protected dotdirs and `.bxignore` entries
-6. **Write** the profile to `/tmp`, launch VSCode via `sandbox-exec`, clean up on exit
+6. **Write** the profile to `/tmp`, launch the app via `sandbox-exec`, clean up on exit
 
 ### Why not a simple deny-all + allow?
 
-Apple's Sandbox Profile Language (SBPL) has a critical quirk: **`deny` always wins over `allow`**, regardless of rule order. This means:
+Apple's SBPL has a critical quirk: **`deny` always wins over `allow`**, regardless of rule order:
 
 ```scheme
-;; Does NOT work — the deny still blocks myproject
+;; ❌ Does NOT work — the deny still blocks myproject
 (deny file* (subpath "/Users/me/work"))
 (allow file* (subpath "/Users/me/work/myproject"))
 ```
 
-Additionally, a broad `(deny file* (subpath HOME))` breaks `kqueue`/FSEvents file watchers and SQLite `fcntl` locks, causing VSCode errors even for paths that should be allowed.
-
-bx avoids both issues by **never denying a parent of an allowed path**. Instead, it walks the directory tree and denies only the specific siblings that should be blocked.
+Additionally, a broad `(deny file* (subpath HOME))` breaks `kqueue`/FSEvents file watchers and SQLite locks, causing VSCode errors.
 
-## Tips
+bx avoids both issues by **never denying a parent of an allowed path** — it walks the directory tree and blocks only the specific siblings.
 
-**See what's happening:** Use `--verbose` to inspect the generated profile before trusting it with sensitive work.
+## 🛡️ Safety checks
 
-**Test the sandbox:** Try reading a blocked file from VSCode's terminal:
+bx detects and prevents problematic scenarios:
 
-```bash
-cat ~/Documents/something.txt   # Should fail with "Operation not permitted"
-cat ~/Desktop/file.txt           # Should fail
-ls ~/work/other-project/         # Should fail
-```
+- **🔄 Sandbox nesting:** If `CODEBOX_SANDBOX=1` is set (auto-propagated), bx refuses to start — nested sandboxes cause silent failures.
+- **🔍 Unknown sandbox:** On startup, bx probes `~/Documents`, `~/Desktop`, `~/Downloads`. If any return `EPERM`, another sandbox is active — bx aborts.
+- **⚠️ VSCode terminal:** If `VSCODE_PID` is set, bx warns that it will launch a *new* instance, not sandbox the current one.
 
-## Safety checks
+## 💡 Tips
 
-bx detects and prevents problematic scenarios:
+**Verify it works** — try reading a blocked file from the sandboxed terminal:
 
-- **Sandbox nesting:** If `CODEBOX_SANDBOX=1` is set (automatically passed to child processes), bx refuses to start — nested `sandbox-exec` causes silent failures.
-- **Unknown sandbox:** On startup, bx probes `~/Documents`, `~/Desktop`, and `~/Downloads`. If any return `EPERM`, another sandbox is already active — bx aborts.
-- **VSCode terminal:** If `VSCODE_PID` is set, bx warns that it will launch a *new* instance, not sandbox the current one.
+```bash
+cat ~/Documents/something.txt   # ❌ Operation not permitted
+cat ~/Desktop/file.txt           # ❌ Operation not permitted
+ls ~/work/other-project/         # ❌ Operation not permitted
+cat ./src/index.ts               # ✅ Works!
+```
 
-## Known limitations
+## ⚠️ Known limitations
 
-- **File watcher warnings:** VSCode may log `EPERM` errors for `fs.watch()` on some paths. These are cosmetic and don't affect functionality.
-- **SQLite warnings:** `state.vscdb` errors may appear in logs when VSCode's state database paths are affected. Extensions still work correctly.
-- **`sandbox-exec` is undocumented:** Apple provides no official documentation for SBPL. The tool works in practice but could change with OS updates.
+- **File watcher warnings:** VSCode may log `EPERM` for `fs.watch()` on some paths — cosmetic only
+- **SQLite warnings:** `state.vscdb` errors may appear in logs — extensions still work
+- **`sandbox-exec` is undocumented:** Apple could change behavior with OS updates
 
-## License
+## 📄 License
 
 MIT — see [LICENSE](LICENSE).

package/dist/bx.js

@@ -1,21 +1,36 @@
 #!/usr/bin/env node
+const __VERSION__ = "0.3.0";
 import { accessSync, constants, cpSync, existsSync, globSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-//#region src/index.ts
-const __dirname = dirname(fileURLToPath(import.meta.url));
-if (process.env.CODEBOX_SANDBOX === "1") {
-	console.error("sandbox: ERROR — already running inside a bx sandbox.");
-	console.error("sandbox: Nesting sandbox-exec causes silent failures. Aborting.");
-	process.exit(1);
+import process from "node:process";
+//#region src/guards.ts
+/**
+* Abort if we're already inside a bx sandbox (env var set by us).
+*/
+function checkOwnSandbox() {
+	if (process.env.CODEBOX_SANDBOX === "1") {
+		console.error("sandbox: ERROR — already running inside a bx sandbox.");
+		console.error("sandbox: Nesting sandbox-exec causes silent failures. Aborting.");
+		process.exit(1);
+	}
 }
-if (process.env.VSCODE_PID) {
-	console.error("sandbox: WARNING — running from inside a VSCode terminal.");
-	console.error("sandbox: This will launch a *new* instance in a sandbox.");
-	console.error("sandbox: The current VSCode instance will NOT be sandboxed.");
+/**
+* Warn if launched from inside a VSCode terminal.
+*/
+function checkVSCodeTerminal() {
+	if (process.env.VSCODE_PID) {
+		console.error("sandbox: WARNING — running from inside a VSCode terminal.");
+		console.error("sandbox: This will launch a *new* instance in a sandbox.");
+		console.error("sandbox: The current VSCode instance will NOT be sandboxed.");
+	}
 }
-function isAlreadySandboxed() {
+/**
+* Detect if we're inside an unknown sandbox by probing well-known
+* directories that exist on every Mac but would be blocked.
+*/
+function checkExternalSandbox() {
 	for (const dir of [
 		"Documents",
 		"Desktop",
@@ -25,141 +40,187 @@ function isAlreadySandboxed() {
 		try {
 			accessSync(target, constants.R_OK);
 		} catch (e) {
-			if (e.code === "EPERM") return true;
+			if (e.code === "EPERM") {
+				console.error("sandbox: ERROR — already running inside a sandbox!");
+				console.error("sandbox: Nesting sandbox-exec may cause silent failures. Aborting.");
+				process.exit(1);
+			}
 		}
 	}
-	return false;
-}
-if (isAlreadySandboxed()) {
-	console.error("sandbox: ERROR — already running inside a sandbox!");
-	console.error("sandbox: Nesting sandbox-exec may cause silent failures. Aborting.");
-	process.exit(1);
 }
+//#endregion
+//#region src/args.ts
 const MODES = [
 	"code",
 	"term",
 	"claude",
 	"exec"
 ];
-const rawArgs = process.argv.slice(2);
-const verbose = rawArgs.includes("--verbose");
-const profileSandbox = rawArgs.includes("--profile-sandbox");
-const positional = rawArgs.filter((a) => !a.startsWith("--"));
-const doubleDashIdx = rawArgs.indexOf("--");
-const execCmd = doubleDashIdx >= 0 ? rawArgs.slice(doubleDashIdx + 1) : [];
-const beforeDash = doubleDashIdx >= 0 ? rawArgs.slice(0, doubleDashIdx).filter((a) => !a.startsWith("--")) : positional;
-let mode = "code";
-let workArg = ".";
-if (beforeDash.length > 0 && MODES.includes(beforeDash[0])) {
-	mode = beforeDash[0];
-	workArg = beforeDash[1] ?? ".";
-} else if (beforeDash.length > 0) workArg = beforeDash[0];
-if (mode === "exec" && execCmd.length === 0) {
-	console.error("sandbox: exec mode requires a command after \"--\"");
-	console.error("usage: bx exec [workdir] -- command [args...]");
-	process.exit(1);
+function parseArgs() {
+	const rawArgs = process.argv.slice(2);
+	const verbose = rawArgs.includes("--verbose");
+	const profileSandbox = rawArgs.includes("--profile-sandbox");
+	const positional = rawArgs.filter((a) => !a.startsWith("--"));
+	const doubleDashIdx = rawArgs.indexOf("--");
+	const execCmd = doubleDashIdx >= 0 ? rawArgs.slice(doubleDashIdx + 1) : [];
+	const beforeDash = doubleDashIdx >= 0 ? rawArgs.slice(0, doubleDashIdx).filter((a) => !a.startsWith("--")) : positional;
+	let mode = "code";
+	let workArgs;
+	if (beforeDash.length > 0 && MODES.includes(beforeDash[0])) {
+		mode = beforeDash[0];
+		workArgs = beforeDash.slice(1);
+	} else workArgs = beforeDash;
+	if (workArgs.length === 0) workArgs = ["."];
+	if (mode === "exec" && execCmd.length === 0) {
+		console.error("sandbox: exec mode requires a command after \"--\"");
+		console.error("usage: bx exec [workdir...] -- command [args...]");
+		process.exit(1);
+	}
+	return {
+		mode,
+		workArgs,
+		verbose,
+		profileSandbox,
+		execCmd
+	};
 }
-const HOME = process.env.HOME;
-const SCRIPT_DIR = __dirname;
-const WORK_DIR = resolve(workArg);
-const allowedDirs = new Set([WORK_DIR]);
-const sandboxAllowPath = join(HOME, ".bxallow");
-if (existsSync(sandboxAllowPath)) for (const raw of readFileSync(sandboxAllowPath, "utf-8").split("\n")) {
-	const line = raw.trim();
-	if (!line || line.startsWith("#")) continue;
-	const absolute = resolve(HOME, line);
-	if (existsSync(absolute) && statSync(absolute).isDirectory()) allowedDirs.add(absolute);
+//#endregion
+//#region src/profile.ts
+const PROTECTED_DOTDIRS = [
+	".Trash",
+	".ssh",
+	".gnupg",
+	".docker",
+	".zsh_sessions",
+	".cargo",
+	".gradle",
+	".gem"
+];
+/**
+* Parse a config file with one entry per line (supports # comments).
+*/
+function parseLines(filePath) {
+	if (!existsSync(filePath)) return [];
+	return readFileSync(filePath, "utf-8").split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
 }
-const VSCODE_APP = "/Applications/Visual Studio Code.app/Contents/MacOS/Electron";
-const VSCODE_DATA = join(HOME, ".vscode-sandbox");
-const VSCODE_EXTENSIONS_GLOBAL = join(HOME, ".vscode", "extensions");
-const VSCODE_EXTENSIONS_LOCAL = join(VSCODE_DATA, "extensions");
-if (mode === "code" && profileSandbox) {
-	mkdirSync(VSCODE_DATA, { recursive: true });
-	if (!existsSync(VSCODE_EXTENSIONS_LOCAL) && existsSync(VSCODE_EXTENSIONS_GLOBAL)) {
-		console.error("sandbox: copying extensions from global install...");
-		cpSync(VSCODE_EXTENSIONS_GLOBAL, VSCODE_EXTENSIONS_LOCAL, { recursive: true });
+/**
+* Apply a single .bxignore file: resolve glob patterns relative to baseDir.
+*/
+function applyIgnoreFile(filePath, baseDir, ignored) {
+	for (const line of parseLines(filePath)) for (const match of globSync(line, { cwd: baseDir })) ignored.push(resolve(baseDir, match));
+}
+/**
+* Recursively find and apply .bxignore files in a directory tree.
+*/
+function collectIgnoreFilesRecursive(dir, ignored) {
+	const ignoreFile = join(dir, ".bxignore");
+	if (existsSync(ignoreFile)) applyIgnoreFile(ignoreFile, dir, ignored);
+	let entries;
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return;
 	}
+	for (const name of entries) {
+		if (name.startsWith(".") || name === "node_modules") continue;
+		const fullPath = join(dir, name);
+		try {
+			if (statSync(fullPath).isDirectory()) collectIgnoreFilesRecursive(fullPath, ignored);
+		} catch {}
+	}
+}
+/**
+* Parse ~/.bxallow and return a set of all allowed directories.
+*/
+function parseAllowedDirs(home, workDirs) {
+	const allowed = new Set(workDirs);
+	for (const line of parseLines(join(home, ".bxallow"))) {
+		const absolute = resolve(home, line);
+		if (existsSync(absolute) && statSync(absolute).isDirectory()) allowed.add(absolute);
+	}
+	return allowed;
 }
-function collectBlockedDirs(parentDir) {
+/**
+* Recursively collect directories to block under parentDir.
+* Never blocks a parent of an allowed path — instead descends and blocks siblings.
+*/
+function collectBlockedDirs(parentDir, home, scriptDir, allowedDirs) {
 	const blocked = [];
 	for (const name of readdirSync(parentDir)) {
 		if (name.startsWith(".")) continue;
 		const fullPath = join(parentDir, name);
 		if (!statSync(fullPath).isDirectory()) continue;
-		if (parentDir === HOME && name === "Library") continue;
-		if (SCRIPT_DIR.startsWith(fullPath + "/") || SCRIPT_DIR === fullPath) continue;
+		if (parentDir === home && name === "Library") continue;
+		if (scriptDir.startsWith(fullPath + "/") || scriptDir === fullPath) continue;
 		if (allowedDirs.has(fullPath)) continue;
 		if ([...allowedDirs].some((d) => d.startsWith(fullPath + "/"))) {
-			blocked.push(...collectBlockedDirs(fullPath));
+			blocked.push(...collectBlockedDirs(fullPath, home, scriptDir, allowedDirs));
 			continue;
 		}
 		blocked.push(fullPath);
 	}
 	return blocked;
 }
-const blockedDirs = collectBlockedDirs(HOME);
-const PROTECTED_DOTDIRS = [
-	".Trash",
-	".ssh",
-	".gnupg",
-	".docker",
-	".zsh_sessions",
-	".cargo",
-	".gradle",
-	".gem"
-];
-const ignoredPaths = PROTECTED_DOTDIRS.map((d) => join(HOME, d));
-function parseSandboxIgnore(filePath, baseDir) {
-	if (!existsSync(filePath)) return;
-	for (const raw of readFileSync(filePath, "utf-8").split("\n")) {
-		const line = raw.trim();
-		if (!line || line.startsWith("#")) continue;
-		const matches = globSync(line, { cwd: baseDir });
-		for (const match of matches) ignoredPaths.push(resolve(baseDir, match));
-	}
+/**
+* Collect paths to deny from .bxignore files and built-in protected dotdirs.
+* Searches ~/.bxignore and recursively through all workdirs.
+*/
+function collectIgnoredPaths(home, workDirs) {
+	const ignored = PROTECTED_DOTDIRS.map((d) => join(home, d));
+	applyIgnoreFile(join(home, ".bxignore"), home, ignored);
+	for (const workDir of workDirs) collectIgnoreFilesRecursive(workDir, ignored);
+	return ignored;
 }
-parseSandboxIgnore(join(HOME, ".bxignore"), HOME);
-parseSandboxIgnore(join(WORK_DIR, ".bxignore"), WORK_DIR);
-const extraIgnored = ignoredPaths.length - PROTECTED_DOTDIRS.length;
-if (extraIgnored > 0) console.error(`sandbox: .bxignore hides ${extraIgnored} extra path(s)`);
-const profile = `; Auto-generated sandbox profile
-; Working directory: ${WORK_DIR}
+/**
+* Generate the SBPL sandbox profile string.
+*/
+function generateProfile(workDirs, blockedDirs, ignoredPaths) {
+	const denyRules = blockedDirs.map((dir) => `  (subpath "${dir}")`).join("\n");
+	const ignoredRules = ignoredPaths.length > 0 ? `\n; Hidden paths from .bxignore\n(deny file*\n${ignoredPaths.map((p) => {
+		return existsSync(p) && statSync(p).isDirectory() ? `  (subpath "${p}")` : `  (literal "${p}")`;
+	}).join("\n")}\n)\n` : "";
+	return `; Auto-generated sandbox profile
+; Working directories: ${workDirs.join(", ")}
 
 (version 1)
 (allow default)
 
 ; Blocked directories (auto-generated from $HOME contents)
 (deny file*
-${blockedDirs.map((dir) => `  (subpath "${dir}")`).join("\n")}
+${denyRules}
 )
-
-${ignoredPaths.length > 0 ? `
-; Hidden paths from .bxignore
-(deny file*
-${ignoredPaths.map((p) => {
-	return existsSync(p) && statSync(p).isDirectory() ? `  (subpath "${p}")` : `  (literal "${p}")`;
-}).join("\n")}
-)
-` : ""}
+${ignoredRules}
 `;
-const profilePath = join("/tmp", `bx-${process.pid}.sb`);
-writeFileSync(profilePath, profile);
-console.error(`sandbox: ${mode} mode, working directory: ${WORK_DIR}`);
-if (verbose) {
-	console.error("\n--- Generated sandbox profile ---");
-	console.error(profile);
-	console.error("--- End of profile ---\n");
 }
-function buildCommand() {
+//#endregion
+//#region src/modes.ts
+const VSCODE_APP = "/Applications/Visual Studio Code.app/Contents/MacOS/Electron";
+/**
+* Prepare VSCode isolated profile if --profile-sandbox is set.
+*/
+function setupVSCodeProfile(home) {
+	const dataDir = join(home, ".vscode-sandbox");
+	const globalExt = join(home, ".vscode", "extensions");
+	const localExt = join(dataDir, "extensions");
+	mkdirSync(dataDir, { recursive: true });
+	if (!existsSync(localExt) && existsSync(globalExt)) {
+		console.error("sandbox: copying extensions from global install...");
+		cpSync(globalExt, localExt, { recursive: true });
+	}
+}
+/**
+* Build the command + args to run inside the sandbox for the given mode.
+*/
+function buildCommand(mode, workDirs, home, profileSandbox, execCmd) {
 	switch (mode) {
 		case "code": {
+			const dataDir = join(home, ".vscode-sandbox");
 			const args = ["--no-sandbox"];
 			if (profileSandbox) {
-				args.push("--user-data-dir", join(VSCODE_DATA, "data"));
-				args.push("--extensions-dir", VSCODE_EXTENSIONS_LOCAL);
+				args.push("--user-data-dir", join(dataDir, "data"));
+				args.push("--extensions-dir", join(dataDir, "extensions"));
 			}
-			args.push(WORK_DIR);
+			args.push(...workDirs);
 			return {
 				bin: VSCODE_APP,
 				args
@@ -171,7 +232,7 @@ function buildCommand() {
 		};
 		case "claude": return {
 			bin: "claude",
-			args: [WORK_DIR]
+			args: [workDirs[0]]
 		};
 		case "exec": return {
 			bin: execCmd[0],
@@ -179,18 +240,71 @@ function buildCommand() {
 		};
 	}
 }
-const cmd = buildCommand();
+//#endregion
+//#region src/index.ts
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VERSION = typeof __VERSION__ !== "undefined" ? __VERSION__ : "dev";
+if (process.argv.includes("--version") || process.argv.includes("-v")) {
+	console.log(`bx ${VERSION}`);
+	process.exit(0);
+}
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+	console.log(`bx ${VERSION} — launch apps in a macOS sandbox
+
+Usage:
+  bx [workdir...]                            VSCode (default)
+  bx code [workdir...]                       VSCode
+  bx term [workdir...]                       sandboxed login shell
+  bx claude [workdir...]                     Claude Code CLI
+  bx exec [workdir...] -- command [args...]  arbitrary command
+
+Options:
+  --verbose            print the generated sandbox profile
+  --profile-sandbox    use an isolated VSCode profile (code mode only)
+  -v, --version        show version
+  -h, --help           show this help
+
+Configuration:
+  ~/.bxallow           extra allowed directories (one per line)
+  ~/.bxignore          extra blocked paths in $HOME (one per line)
+  <workdir>/.bxignore  blocked paths in project (supports globs, searched recursively)
+
+https://github.com/holtwick/bx-mac`);
+	process.exit(0);
+}
+checkOwnSandbox();
+checkVSCodeTerminal();
+checkExternalSandbox();
+const { mode, workArgs, verbose, profileSandbox, execCmd } = parseArgs();
+const HOME = process.env.HOME;
+const WORK_DIRS = workArgs.map((a) => resolve(a));
+if (mode === "code" && profileSandbox) setupVSCodeProfile(HOME);
+const blockedDirs = collectBlockedDirs(HOME, HOME, __dirname, parseAllowedDirs(HOME, WORK_DIRS));
+const ignoredPaths = collectIgnoredPaths(HOME, WORK_DIRS);
+const extraIgnored = ignoredPaths.length - PROTECTED_DOTDIRS.length;
+if (extraIgnored > 0) console.error(`sandbox: .bxignore hides ${extraIgnored} extra path(s)`);
+const profile = generateProfile(WORK_DIRS, blockedDirs, ignoredPaths);
+const profilePath = join("/tmp", `bx-${process.pid}.sb`);
+writeFileSync(profilePath, profile);
+const dirLabel = WORK_DIRS.length === 1 ? WORK_DIRS[0] : `${WORK_DIRS.length} directories`;
+console.error(`sandbox: ${mode} mode, working directory: ${dirLabel}`);
+if (verbose) {
+	console.error("\n--- Generated sandbox profile ---");
+	console.error(profile);
+	console.error("--- End of profile ---\n");
+}
+const cmd = buildCommand(mode, WORK_DIRS, HOME, profileSandbox, execCmd);
 spawn("sandbox-exec", [
 	"-f",
 	profilePath,
 	"-D",
 	`HOME=${HOME}`,
 	"-D",
-	`WORK=${WORK_DIR}`,
+	`WORK=${WORK_DIRS[0]}`,
 	cmd.bin,
 	...cmd.args
 ], {
-	cwd: WORK_DIR,
+	cwd: WORK_DIRS[0],
 	stdio: "inherit",
 	env: {
 		...process.env,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bx-mac",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "description": "Launch apps in a macOS sandbox — only the project directory is accessible",
   "type": "module",
   "bin": {
@@ -11,8 +11,8 @@
   ],
   "scripts": {
     "build": "rolldown -c",
-    "release": "./scripts/release.sh",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "post:release": "./scripts/release.sh"
   },
   "keywords": [
     "sandbox",
@@ -24,6 +24,7 @@
   "author": "Dirk Holtwick",
   "license": "MIT",
   "devDependencies": {
+    "@types/node": "^25.5.0",
     "rolldown": "^1.0.0-rc.12"
   },
   "engines": {