clabox 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Suvorov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# 📦 clabox
+
+[![LSK.js](https://github.com/lskjs/presets/raw/main/docs/badge.svg)](https://github.com/lskjs)
+[![NPM version](https://badgen.net/npm/v/clabox)](https://www.npmjs.com/package/clabox)
+[![NPM downloads](https://badgen.net/npm/dt/clabox)](https://www.npmjs.com/package/clabox)
+[![Have TypeScript types](https://badgen.net/npm/types/clabox)](https://www.npmjs.com/package/clabox)
+[![Package size](https://img.shields.io/npm/unpacked-size/clabox?label=size&color=blue)](https://www.npmjs.com/package/clabox)
+[![License](https://badgen.net/github/license/ycmds/clabox)](https://github.com/ycmds/clabox/blob/main/LICENSE)
+[![Write us in Telegram](https://img.shields.io/badge/write%20us-0088CC?logo=telegram&logoColor=white)](https://t.me/isuvorov)
+
+<div align="center">
+  <h3><p><strong>🛡️ Run Claude Code in a sandbox for super-safe YOLO mode 🛡️</strong></p></h3>
+</div>
+
+<img src="./docs/logo.png" align="right" width="200" height="200" alt="clabox logo" />
+
+**🛡️ Tight Seatbelt sandbox** — the profile starts with `(deny default)` <br/>
+**📂 Project-scoped access** — only the CWD and explicitly allowed paths <br/>
+**🔒 Secrets stay out of reach** — SSH keys, `~/.aws`, `~/.ssh/id_*`, private dirs <br/>
+**📦 Declarative JS config** instead of sed surgery over a heredoc <br/>
+**🤖 Bot identity** for git/ssh inside the sandbox <br/>
+**🧨 Fork-bomb guard** via `ulimit -u` <br/>
+**⚡ YOLO mode, safely** (`--dangerously-skip-permissions`) <br/>
+**🍎 macOS only**, Node ≥ 18, no runtime deps beyond `yargs` <br/>
+
+---
+
+## Install
+
+```bash
+npm install -g clabox      # exposes the global `clabox` command
+# or run without installing:
+bunx clabox …
+npx clabox …
+```
+
+## Usage
+
+```bash
+# Default profile (~/.claude), YOLO mode
+clabox run --dangerously-skip-permissions
+
+# A different Claude profile
+CLAUDE_CONFIG_DIR=~/.claude_work clabox run --dangerously-skip-permissions
+
+# A named box from ~/.config/clabox/configs/<name>.config.mjs
+clabox -b ax-root --dangerously-skip-permissions
+
+# Debugging
+clabox generate            # build the profile, print the .sb path
+clabox profile             # just the path (no build)
+CLABOX_DEBUG=1 clabox      # print profile/config/dir on launch
+clabox --help
+```
+
+Unknown flags are passed straight through to `claude`, so anything after the
+command (`--dangerously-skip-permissions`, `--model …`, etc.) just works.
+
+---
+
+## Configuration
+
+Three layers, later wins: **defaults → environment variables → JS config file**.
+
+The config file is looked up in this order: `--config /path` →
+`CLABOX_CONFIG=/path` → `./clabox.config.mjs` (project root) →
+`~/.config/clabox/config.mjs`.
+See [`clabox.config.example.mjs`](clabox.config.example.mjs).
+
+```bash
+clabox --config ./my.clabox.mjs run --dangerously-skip-permissions
+```
+
+```js
+// clabox.config.mjs
+export default {
+  configDir: '~/.claude_work',
+  bot: { name: 'workBOT', email: 'bot@work.dev', sshDir: '~/.ssh/workbot' },
+  network: true,
+  paths: {
+    readWrite: ['~/scratch'],    // RW on top of project / configDir / tmp
+    readOnly:  ['~/reference'],   // RO
+    exec:      ['/opt/tool/bin'], // process-exec
+    deny:      ['~/secret'],      // explicit deny (read + write)
+  },
+};
+```
+
+You may also export a function `(defaults) => config` for full control. `~` is
+expanded to `$HOME`.
+
+### Named boxes (`-b` / `--box`)
+
+Keep a directory of named configs and switch between them by name from anywhere:
+
+```bash
+# ~/.config/clabox/configs/ax-root.config.mjs
+clabox -b ax-root --dangerously-skip-permissions
+```
+
+`-b <name>` resolves `~/.config/clabox/configs/<name>.config.mjs` (falling back
+to a bare `<name>.mjs`) and loads it like `--config` — so it wins over `--config`
+/ `CLABOX_CONFIG`. Override the dir with `CLABOX_CONFIGS_DIR`. Files named
+`_*.mjs` are treated as shared partials (e.g. `_presets.mjs`), not boxes.
+
+A box can pin its own `cwd` so it always targets one project, no matter where you
+run `clabox` from:
+
+```js
+// ~/.config/clabox/configs/ax-root.config.mjs
+export default {
+  cwd: '~/projects/my-app', // claude runs here; this dir is the RW project dir
+  configDir: '~/.claude_axiomus',
+};
+```
+
+### Environment variables
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `CLAUDE_CONFIG_DIR` | Claude config/profile dir (multi-account); passed through to `claude` | `~/.claude` |
+| `CLABOX_CLAUDE_BIN` | path to the `claude` binary | `PATH`, then `~/.local/bin/claude` |
+| `CLABOX_BOT_NAME` / `CLABOX_BOT_EMAIL` | git identity | `claudeBOT` / `bot@example.com` |
+| `CLABOX_BOT_SSH_DIR` | bot key dir (`id_ed25519`, `config`) | `~/.ssh/claudebot` |
+| `CLABOX_CONFIG` | path to the JS config file (the `--config` flag overrides it) | — |
+| `CLABOX_CONFIGS_DIR` | global dir of named boxes for `-b`/`--box <name>` (`<name>.config.mjs`) | `~/.config/clabox/configs` |
+| `CLABOX_CWD` | working dir to run `claude` in (also the RW project dir); `~` expanded | — (the shell CWD) |
+| `CLABOX_HOOKS_DIR` | hooks dir (RO + exec inside the sandbox) | — (off) |
+| `CLABOX_DEBUG` | print diagnostics on launch | — |
+| `TMPDIR` | where the generated profile is stored | `/tmp` |
+
+---
+
+## How it works
+
+`sandbox-exec` runs a process inside a Seatbelt profile that starts with
+`(deny default)` — everything is forbidden unless explicitly allowed.
+
+```
+clabox run  →  loadConfig()  →  buildProfile()  →  <TMPDIR>/…sb
+            →  sh -c 'ulimit -u N; exec sandbox-exec -f <sb> env … claude …'
+```
+
+| Module | Responsibility |
+|---|---|
+| `src/utils/config.ts` | defaults, env, loading/merging the JS config, `~` expansion |
+| `src/sandbox/profile.ts` | assembling the SBPL profile from config (typed helpers `subpath`/`literal`/`regex`/…) |
+| `src/sandbox/run.ts` | locating `claude`/`sandbox-exec`, generating the profile, launching with bot env + `ulimit` |
+| `src/cli.ts` | the CLI (`run` / `generate` / `profile`), built on yargs |
+
+Profile path: `$TMPDIR/clabox-<dir-name>-<hash>.sb` (hash of the absolute
+project path — each project gets its own cached profile).
+
+Package managers are autodetected (`src/sandbox/profile.ts`) and added to the
+read/exec sections: Homebrew (`/opt/homebrew` or `/usr/local/Homebrew`),
+`~/.local`, Nix (`/nix/store`).
+
+### What the profile allows and denies
+
+**Read-only:** system dirs `/System`, `/usr`, `/bin`, `/sbin`,
+`/Library/Frameworks`, Command Line Tools / Xcode, tzdata, system and user
+`Library/Preferences`, detected package paths.
+
+**Read-write:** the project dir (CWD), the Claude config dir (`configDir`),
+`/tmp`, `/private/tmp`, `/private/var/folders/…`, `~/Library/Keychains` (for
+OAuth refresh), plus `paths.readWrite` from your config.
+
+**Network:** `(allow network*)` when `network: true` (the default).
+
+**Explicit deny — wins even over the allows above:**
+- private dirs: `denyHome` (`~/Documents`, `~/Desktop`, `~/Downloads`,
+  `~/Pictures`, `~/Movies`, `~/Music`);
+- secrets: `denyDotConfigs` (`~/.aws`, `~/.gnupg`, `~/.kube`, `~/.docker`,
+  `~/.config`) with a carve-out for `~/.config/git`;
+- personal SSH keys `~/.ssh/id_*`, `*.pem`, `*.key` — Claude physically cannot
+  read them. Only the bot key subdir (`bot.sshDir`) is readable.
+
+### Git/ssh bot identity
+
+- `ulimit -u <ulimitProcs>` — fork-bomb guard (`0` to disable);
+- `GIT_AUTHOR_*` / `GIT_COMMITTER_*` — bot name/email from config;
+- if `bot.sshDir/id_ed25519` exists, `GIT_SSH_COMMAND` is pinned to it
+  (`IdentitiesOnly=yes`, `IdentityAgent=none`);
+- gpg signing disabled, `NPM_CONFIG_USERCONFIG=/dev/null`, `DISABLE_AUTOUPDATER=1`.
+
+---
+
+## Tests
+
+```bash
+bun test            # unit + functional (bun:test)
+bun run test        # full gate: lint + types + unit + size
+```
+
+The suite tests the wrapper, not `claude`:
+
+- **Unit** — the generated profile text: SBPL preamble, project RW/exec, network
+  toggle, config dir, ssh-key denials, the deny list, extra config paths, hooks.
+- **Functional** — runs real `sandbox-exec` against a generated profile and
+  asserts that reads/writes inside the project succeed while denied paths are
+  blocked. Auto-skipped off macOS or when running nested inside another sandbox.
+
+---
+
+## Limitations
+
+- **macOS only** — needs `sandbox-exec` (Seatbelt). Formally deprecated, still
+  works on macOS 14/15.
+- **No nested sandbox** — you cannot launch the sandbox from inside another
+  sandbox (`sandbox_apply: Operation not permitted`). Run from a bare host.
+- **Keychain is writable** for OAuth refresh (otherwise tokens hit 401 after
+  ~24h). For a stricter setup, swap the RW Keychain block for RO in
+  `src/sandbox/profile.ts` (the "Keychain access" section).
+
+---
+
+## License
+
+[MIT](LICENSE)

package/clabox.config.example.mjs

@@ -0,0 +1,90 @@
+// Example clabox config. Copy to `clabox.config.mjs` (in your
+// project root) or `~/.config/clabox/config.mjs`, then edit.
+//
+// Default-export either a plain object (merged over the built-in defaults) or
+// a function `(defaults) => config` for full control. `~` is expanded to $HOME.
+
+export default {
+  // Working directory to run `claude` in (also granted RW as the project dir).
+  // null → the shell's CWD. Set it on a named box that should always target one
+  // project regardless of where you launch `clabox` from. `~` is expanded.
+  cwd: null, // e.g. '~/projects/my-app'
+
+  // Which Claude profile/account to use.
+  configDir: '~/.claude',
+
+  // Args always passed to `claude`, before any args from the CLI.
+  claudeArgs: ['--settings', '{"includeCoAuthoredBy": false}'],
+
+  // Identity forced onto git commits/pushes made from inside the sandbox.
+  bot: {
+    name: 'claudeBOT',
+    email: 'bot@example.com',
+    // If `${sshDir}/id_ed25519` exists, git ssh is pinned to it and your
+    // personal keys (~/.ssh/id_*, *.pem, *.key) stay denied either way.
+    sshDir: '~/.ssh/claudebot',
+  },
+
+  // Extra environment variables forced onto the sandboxed `claude` process.
+  // Layered after the built-in vars (so a key here wins) and on top of the
+  // inherited shell env. Handy for secrets like GITHUB_TOKEN. Don't hard-code
+  // secrets in a config committed to the repo — read them from process.env, or
+  // keep this file in ~/.config/clabox/config.mjs (outside the project).
+  env: {
+    // GITHUB_TOKEN: process.env.MY_GH_TOKEN ?? '',
+  },
+
+  // Outbound network (set false to cut it off entirely).
+  network: true,
+
+  // Process-table cap inside the sandbox (fork-bomb guard); 0 to disable.
+  ulimitProcs: 1024,
+
+  // Extra directory granted read + execute (e.g. shared Claude hooks).
+  hooksDir: null, // '~/some/hooks'
+
+  // Extra rules layered on top of the base profile.
+  paths: {
+    readWrite: [], // e.g. ['~/scratch', '/Volumes/work']
+    readOnly: [], // e.g. ['~/reference-data']
+    exec: [], // e.g. ['/opt/some/tool/bin']
+    deny: [], // e.g. ['~/secret-project']
+  },
+
+  // Home subdirectories denied entirely (read + write).
+  denyHome: ['Documents', 'Desktop', 'Downloads', 'Pictures', 'Movies', 'Music'],
+
+  // Dotfile config dirs under $HOME denied entirely (.config/git is re-allowed
+  // read-only regardless, so git keeps working).
+  denyDotConfigs: ['aws', 'gnupg', 'kube', 'docker', 'config'],
+
+  // Opt-in: turn this box into a standalone Ghostty app. With `app` present,
+  // `clabox init` writes a Ghostty config (with a `command` that runs
+  // `clabox -b <box>`), a Raycast command (`<dir>/raycast/<name>.sh` → opens the
+  // app), and clones Ghostty.app into <appsDir>/<name>.app. Omit `app` entirely
+  // on boxes that should only get a shell alias (the default).
+  // app: {
+  //   name: 'AX Manager',          // → ~/Applications/AX Manager.app
+  //   title: '🐈‍⬛ AX Manager',      // ghostty window title (default: name)
+  //   emoji: '🐈‍⬛',                 // Raycast icon (default: the title's emoji)
+  //   icon: '~/icons/ax.png',      // .icns or .png (.png is converted); .app icon
+  //   macosIcon: 'retro',          // ghostty built-in macos-icon
+  //   ghostty: {                   // extra raw `key = value` ghostty lines
+  //     background: '#0d1117',
+  //     'background-opacity': '0.92',
+  //   },
+  //   // bundleId: 'com.me.ax',    // default: com.ghostty.custom.<box-dotted>
+  // },
+
+  // Machine-wide settings for the `clabox init` Ghostty-app builder. Shared by
+  // every `app` box — handy to set once in a shared preset. Env overrides:
+  // CLABOX_GHOSTTY_APP, CLABOX_APPS_DIR, CLABOX_SIGN_ID,
+  // CLABOX_GHOSTTY_BASE_CONFIG, CLABOX_CLABOX_BIN.
+  appBuilder: {
+    ghosttyApp: '/Applications/Ghostty.app', // donor app to clone
+    appsDir: '~/Applications', // where built apps land
+    signId: null, // codesign identity; null → ad-hoc (`codesign -s -`)
+    baseGhosttyConfig: null, // optional leading `config-file = …`
+    claboxBin: null, // clabox path baked into `command`; null → autodetect
+  },
+};

package/docs/guideline.md

@@ -0,0 +1,196 @@
+# Project Guidelines
+
+> **This file contains project documentation for developers.** For AI assistant instructions see [CLAUDE.md](../CLAUDE.md).
+
+Guidelines for clabox — run Claude Code in a sandbox for super-safe YOLO mode, configured in plain JavaScript.
+
+**Important:**
+- Update this file after large project changes
+- Run `bun run fix` and `bun run test` after each code change
+
+## Stack
+
+| Tool | Choice | Notes |
+|---|---|---|
+| Runtime (published) | Node.js ≥ 18 | `lib/` is plain ESM; macOS only (`sandbox-exec`) |
+| Runtime (dev) | Bun | install / test / run TS source directly |
+| Language | TypeScript (ESM) | strict `tsconfig`, `module`/`moduleResolution` nodenext |
+| Build | tsdown (rolldown) | `src/**/*.ts` → `lib/` (ESM + `.d.ts` + sourcemaps) |
+| Lint / Format | Biome | `recommended` preset, `.js`-import enforcement |
+| Test | bun:test | `tests/` (configured in `bunfig.toml`) |
+| Type-check | `tsc --noEmit` | strict, `src/` only |
+| Size budget | size-limit | `@size-limit/preset-small-lib`, `lib/index.js` |
+| Release | semantic-release | fully automatic on push to `main` |
+| CI/CD | GitHub Actions | `macos-latest` (real `sandbox-exec`) |
+| CLI | yargs ^17 | the only runtime dependency |
+| Sandbox | macOS `sandbox-exec` (Seatbelt/SBPL) | profile generated as plain text |
+
+## Project Structure
+
+**Rule:** Only entry-point files live in `src/` root — `index.ts` (public API aggregator) and `cli.ts` (the CLI, built to `lib/cli.js` = the `clabox` bin). All other code lives in subdirectories. The build emits to `lib/`; `bin`/`main`/`exports` point at built `lib/*.js`.
+
+```
+src/
+├── index.ts              # public API aggregator — re-exports config / profile / run / init
+├── cli.ts                # CLI entry (yargs): run / generate / profile / init → lib/cli.js (bin)
+├── sandbox/
+│   ├── profile.ts        # pure SBPL builder: buildProfile, detectPackagePaths,
+│   │                     #   subpath/literal/regex/globalName/ipcName/reEscape helpers
+│   └── run.ts            # I/O: profilePath, generateProfile, runClaude (sandbox-exec launch)
+├── init/
+│   ├── aliases.ts        # pure: aliasName, buildIndex, buildWrapper, buildAliasFiles
+│   ├── ghostty.ts        # pure: buildGhosttyConfig, buildCommand, buildLauncherSource,
+│   │                     #   appBundlePath, bundleId
+│   ├── raycast.ts        # pure: buildRaycastCommand, raycastIcon
+│   ├── app.ts            # I/O (macOS): buildApp, canBuildApps (clone Ghostty.app + sign)
+│   └── scaffold.ts       # I/O: discoverProfiles, runInit (scan configs → scripts + apps + raycast)
+└── utils/
+    └── config.ts         # defaultConfig, expandHome, mergeConfig, findConfigFile, loadConfig,
+                          #   configsDir/resolveBox/listBoxes (named-box resolution)
+tests/
+├── profile.test.ts       # bun:test — unit (profile text) + functional (real sandbox-exec)
+├── init.test.ts          # bun:test — alias/ghostty text + scaffold & app boxes (tmp-dir fs)
+└── box.test.ts           # bun:test — named-box resolution (tmp-dir fs)
+lib/                      # build output (tsdown) — gitignored
+docs/
+├── guideline.md          # this file
+└── logo.png              # README logo
+.github/workflows/
+├── test.yml              # PR → install + build + test (macos-latest)
+└── release.yml           # push main → semantic-release (macos-latest)
+clabox.config.example.mjs  # copyable user config (object or (defaults) => config)
+```
+
+## Commands
+
+```bash
+# Build
+bun run build                 # tsdown --out-dir lib (release build: ESM + .d.ts + maps)
+bun run build:tsdown          # tsdown → lib-tsdown (default outDir)
+bun run build:tsdown:release  # tsdown --out-dir lib
+bun run dev                   # tsdown --watch
+
+# Run
+bun run cli                   # bun run src/cli.ts  (pass args after `--`)
+bun run generate              # bun run src/cli.ts generate (build a profile, print its path)
+bun run cli -- init           # aliases per box + build Ghostty apps for `app` boxes
+bun run cli -- init --no-apps # aliases only (skip the Ghostty-app build)
+bun run cli -- init --app "AX Manager"  # (re)build just one app box
+
+# Testing
+bun run test                  # lint + types + unit + size (the full gate)
+bun run test:unit             # bun test
+bun run test:unit:coverage    # bun test --coverage
+bun run test:unit:watch       # bun test --watch
+bun run test:types            # tsc --noEmit
+bun run test:lint             # biome lint
+bun run test:size             # size-limit
+
+# Fixing
+bun run fix                   # biome check --write
+bun run fix:lint              # biome check --write
+bun run fix:lint:unsafe       # biome check --write --unsafe
+
+# Release (normally automatic in CI)
+bun run version:release       # semantic-release --no-ci --dry-run (preview next version)
+bun run release               # build + test + dry-run + npm publish (local fallback)
+```
+
+## Architecture
+
+`sandbox-exec` runs a process inside a Seatbelt profile that starts with `(deny default)` — everything is forbidden unless explicitly allowed.
+
+```
+clabox run  →  loadConfig()  →  buildProfile()  →  <TMPDIR>/…sb
+            →  sh -c 'ulimit -u N; exec sandbox-exec -f <sb> env … claude …'
+```
+
+### `utils/config.ts`
+Builds the effective config in three layers (later wins): `defaultConfig` → env vars → a JS config file. `findConfigFile(explicit?)` looks up the explicit path (the `--config` CLI flag, falling back to `CLABOX_CONFIG`) → `./clabox.config.mjs` / `./clabox.config.js` → `~/.config/clabox/config.mjs`; the `--config` flag wins over `CLABOX_CONFIG`. `loadConfig(explicit?)` forwards that path, dynamically imports the file and accepts either a plain object (merged via `mergeConfig`, a deep merge over the defaults) or a function `(defaults) => config`. `expandHome()` expands a leading `~`. Exports the `Config`/`BotConfig`/`PathRules`/`LoadedConfig` types.
+
+**Named boxes.** `configsDir()` returns the global box dir (`~/.config/clabox/configs`, overridable via `CLABOX_CONFIGS_DIR`). `resolveBox(name, dir?)` maps a name to its config file there, preferring `<name>.config.mjs` over a bare `<name>.mjs` and throwing (with the available boxes listed) when none exists; a `_`-prefixed name is refused (it's a shared partial, not a box), so `-b` matches exactly what `listBoxes` advertises. `listBoxes(dir?)` returns the sorted, de-duplicated box names, skipping `_`-prefixed shared partials (e.g. `_presets.mjs`). The CLI's `-b`/`--box <name>` flag resolves the name and feeds the path to `loadConfig` as the explicit config (so `-b` wins over `--config`).
+
+### `sandbox/profile.ts` (pure)
+Assembles the SBPL profile text from typed helpers (`subpath`, `literal`, `regex`, `globalName`, `ipcName`, `reEscape`) — no I/O beyond `fs.existsSync` for autodetection. `detectPackagePaths()` finds installed package managers (Homebrew `/opt/homebrew` or `/usr/local/Homebrew`, `~/.local`, Nix `/nix/store`) to grant read/exec. `buildProfile(config, { projectDir, detectedPaths })` returns the full profile and sanity-checks it carries `(version 1)`.
+
+### `sandbox/run.ts` (I/O)
+`profilePath()` returns the deterministic `$TMPDIR/clabox-<dir>-<hash>.sb` path. `resolveProjectDir(config)` returns the effective project dir — `config.cwd` (with `~` expanded) when set, else `process.cwd()` — and is what `generateProfile`/`runClaude` default to. `generateProfile()` requires `sandbox-exec`, builds the profile and writes it. `runClaude()` resolves the project dir + `claude` binary (config → PATH → `~/.local/bin/claude`), forces the bot git identity + hardening env (`buildEnvArgs`, with `config.env` appended last so it wins), sets the terminal title, and execs `sh -c 'ulimit -u N; exec sandbox-exec -f <sb> env … claude …'` **in the resolved project dir** (`spawnSync` `cwd`), returning the exit code.
+
+### `init/aliases.ts` (pure) + `init/scaffold.ts` (I/O)
+`clabox init` turns a directory of box configs into ready-to-use shell commands. `aliases.ts` is pure text: `aliasName(profile)` yields `clabox-<name>`; `buildIndex()` renders the source-able `index.sh` (a `_clabox_run` helper that runs `CLABOX_CONFIGS_DIR=<configsDir> clabox -b "$1"` plus one function per box); `buildWrapper()` renders a standalone `.sh` that sources `index.sh` and calls one function; `buildAliasFiles()` returns the full file set. There is **one command per box** — yolo vs. safe is decided by the box's own preset (`claudeArgs`), not by a `-safe` alias. `scaffold.ts` does the I/O: `discoverProfiles(configsDir)` returns the sorted box names via `listBoxes` (both `<name>.mjs`/`<name>.config.mjs`, `_`-partials skipped; throws if the dir is missing or has no boxes), and `runInit({ baseDir, buildApps, only })` (async) resolves `<baseDir>/configs` + `<baseDir>/scripts` (default `<cwd>/__`), prunes its own prior artifacts (`index.sh`, `clabox-*.sh`), then writes the new ones `chmod +x`. Absolute paths are baked in so the scripts run from any cwd. It returns `{ profiles, written, apps, ghosttyConfigs, warnings, … }`.
+
+### `init/ghostty.ts` + `init/raycast.ts` (pure) + `init/app.ts` (I/O) — standalone Ghostty apps
+A box becomes a real macOS app by carrying an `app` object (`AppConfig`: `name`, `title?`, `emoji?`, `icon?`, `macosIcon?`, `ghostty?`, `bundleId?`). When `runInit` runs with `buildApps` (the default), it `loadConfig`s each box and, for every box with an `app`, writes `<baseDir>/ghostty/<name>.config`, a `<baseDir>/raycast/<name>.sh` Raycast command, and clones a `.app`. `ghostty.ts` is pure text: `buildGhosttyConfig()` renders the config (a `command = bash -c 'cd <cwd> && CLABOX_CONFIGS_DIR=<dir> <claboxBin> -b <name>; exec zsh'` plus `title`/`macos-icon`/extra `app.ghostty` lines and an optional leading `config-file`); `buildLauncherSource()` renders a tiny C launcher that finds `ghostty.real` next to itself and re-execs it with `--config-file=<config>` baked in; `appBundlePath()`/`bundleId()` derive the bundle path/id. `raycast.ts` renders the Raycast script command (`buildRaycastCommand()`: `@raycast.*` metadata + `open <appPath>`; `raycastIcon()` picks `app.emoji`, else the title's leading emoji, else 👻). `app.ts` is the macOS-only I/O (replaces the old `ghostty-app-builder.sh`): `canBuildApps(builder)` gates on darwin + donor app + `cc`; `buildApp()` extracts the donor's entitlements, `cp -R` clones Ghostty.app into `<appsDir>/<name>.app`, patches `Info.plist` (identity + Sparkle off), swaps the binary for the compiled launcher, installs the icon (`.icns` copy or `.png`→`sips`+`iconutil`), and `codesign`s (`appBuilder.signId`, else ad-hoc `-`). Machine-wide build settings live in `config.appBuilder` (`ghosttyApp`, `appsDir`, `signId`, `baseGhosttyConfig`, `claboxBin`). Builds are best-effort: a non-buildable host or a thrown build records a `warning` and the aliases (plus the ghostty config + raycast script) are still emitted. `init` prunes its own `<baseDir>/ghostty/*.config` and `<baseDir>/raycast/*.sh` on a full run (not under `--app`, which would orphan other apps' artifacts); built `.app` bundles are **not** auto-deleted.
+
+### `cli.ts`
+The yargs CLI (`scriptName('clabox')`). Commands: `run [claudeArgs..]` (default), `generate`, `profile`, `init`. `unknown-options-as-args` keeps unknown flags as positionals so they pass straight through to `claude` (e.g. `--dangerously-skip-permissions`). clabox-owned flags: `--config <path>` (a JS config file that overrides `CLABOX_CONFIG`) and `-b`/`--box <name>` (a named box from the global configs dir; resolved via `resolveBox` and winning over `--config`) — both forwarded to `loadConfig()` by `run` and `generate` through the `explicitConfig(argv)` helper. (`-b` deliberately avoids `-p`/`-c`/`-r`/`-d`/`-v`, which are claude's own `--print`/`--continue`/`--resume`/`--debug`/`--verbose`.) `init` takes `--dir <path>` (the base dir holding `configs/` and `scripts/`, default `./__`), `--no-apps` (skip the Ghostty-app build), and `--app <box|name>` ((re)build a single app box, by box name or `app.name`).
+
+### What the profile allows and denies
+- **Read-only:** system dirs (`/System`, `/usr`, `/bin`, `/sbin`, `/Library/Frameworks`), Command Line Tools / Xcode, tzdata, system + user `Library/Preferences`, detected package paths.
+- **Read-write:** the project dir (`config.cwd` if set, else the shell CWD), the Claude config dir (`configDir`), `/tmp`, `/private/tmp`, `/private/var/folders/…`, `~/Library/Keychains` (OAuth refresh), plus `paths.readWrite`.
+- **Network:** `(allow network*)` when `network: true` (default).
+- **Two deny tiers** (Seatbelt evaluates rules in order — the *last* match wins — so placement is deliberate):
+  - **Soft privacy deny (overridable):** `denyHome` (`~/Documents`, `~/Desktop`, …) and `paths.deny`, emitted *before* the extra `readOnly`/`readWrite` and the project dir. An explicit grant therefore overrides it — handy for a project that lives under `~/Documents`, or a debug box that wants `readOnly: ['/']` to roam the disk.
+  - **Hard secret deny (always wins):** `denyDotConfigs` (`~/.aws`, `~/.gnupg`, `~/.kube`, `~/.docker`, `~/.config`) and personal SSH keys `~/.ssh/id_*`, `*.pem`, `*.key`, emitted as the **very last file rule** — after every allow, the extra paths and the project dir. No `readOnly`/`readWrite` grant can re-expose these. Only the bot key subdir (`bot.sshDir`, not matched by the patterns) stays readable. (The `~/.config/git` RO carve-out is shadowed by the hard deny on `~/.config`; git still reads `~/.gitconfig` outside `~/.config`.)
+
+### Git/ssh bot identity
+`ulimit -u <ulimitProcs>` (fork-bomb guard, `0` to disable); `GIT_AUTHOR_*` / `GIT_COMMITTER_*` from `bot.name`/`bot.email`; if `bot.sshDir/id_ed25519` exists, `GIT_SSH_COMMAND` is pinned to it (`IdentitiesOnly=yes`, `IdentityAgent=none`); gpg signing disabled; `NPM_CONFIG_USERCONFIG=/dev/null`; `DISABLE_AUTOUPDATER=1`.
+
+### Passing environment variables
+`sandbox-exec` restricts files and network, not the environment, and `runClaude` spawns through `/bin/sh` without an `env` option — so the sandboxed `claude` **inherits the parent shell env** (e.g. `export GITHUB_TOKEN=… && clabox`). For a declarative alternative, `config.env` (a `KEY=VALUE` map) is appended **last** in `buildEnvArgs`, so it layers over both the inherited env and the built-in hardening vars and a colliding key wins. Don't hard-code secrets in a repo-committed `clabox.config.mjs` (the project dir is mounted RW and readable from inside): read them from `process.env`, or keep the config in `~/.config/clabox/config.mjs`. Anything in the env is readable by `claude` and, with `network: true`, exfiltratable.
+
+## Lint
+
+Biome (`biome.json`), scoped to `src/**/*.ts` + `tests/**/*.ts`:
+- `recommended` preset; `noExplicitAny` and `noNonNullAssertion` off.
+- `useImportExtensions` (error, `forceJsExtensions`) — relative imports must use `.js` specifiers.
+- Formatter: 2-space indent, line width 100, single quotes, always semicolons.
+
+## CI/CD
+
+Both workflows run on `macos-latest` so the functional tests can exercise the real `sandbox-exec`.
+
+- **`test.yml`** — on PR to `main`: checkout → setup Bun + Node 20 → `bun install --frozen-lockfile` → `bun run build` → `bun run test`.
+- **`release.yml`** — on push to `main`: checkout (`fetch-depth: 0`) → setup Bun + Node 20 (`registry-url`) → install → build → test → `npx semantic-release`. Releases are **fully automatic**: semantic-release reads the Conventional Commits, decides the version, updates `CHANGELOG.md`, publishes to npm (provenance) + GitHub Releases, and commits the bump back with `[skip ci]`. Nobody bumps a version by hand.
+
+## Size Limits
+
+| Entry | Limit | Note |
+|---|---|---|
+| `lib/index.js` | 10 kB | brotlied, `node:*` ignored (the CLI bin uses top-level await and is not size-budgeted) |
+
+## Package Exports
+
+```typescript
+import { loadConfig, buildProfile, runClaude, runInit } from 'clabox'; // lib/index.js
+import { loadConfig, defaultConfig, mergeConfig } from 'clabox/config'; // lib/utils/config.js
+import { buildProfile, detectPackagePaths } from 'clabox/profile';   // lib/sandbox/profile.js
+import { generateProfile, profilePath, resolveProjectDir, runClaude } from 'clabox/run'; // lib/sandbox/run.js
+// CLI entry: clabox/cli (lib/cli.js) — also the `clabox` bin
+```
+
+## Environment Variables
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `CLAUDE_CONFIG_DIR` | Claude config/profile dir (multi-account); passed through to `claude` | `~/.claude` |
+| `CLABOX_CWD` | working dir to run `claude` in (also the RW project dir); `~` expanded | — (the shell CWD) |
+| `CLABOX_CLAUDE_BIN` | path to the `claude` binary | PATH, then `~/.local/bin/claude` |
+| `CLABOX_BOT_NAME` / `CLABOX_BOT_EMAIL` | git identity inside the sandbox | `claudeBOT` / `bot@example.com` |
+| `CLABOX_BOT_SSH_DIR` | bot key dir (`id_ed25519`, `config`) | `~/.ssh/claudebot` |
+| `CLABOX_CONFIG` | path to the JS config file (the `--config` flag overrides it) | — |
+| `CLABOX_CONFIGS_DIR` | global dir of named boxes for `-b`/`--box <name>` (`<name>.config.mjs`) | `~/.config/clabox/configs` |
+| `CLABOX_HOOKS_DIR` | hooks dir (RO + exec inside the sandbox) | — (off) |
+| `CLABOX_GHOSTTY_APP` | donor app cloned by `init` for `app` boxes (`config.appBuilder.ghosttyApp`) | `/Applications/Ghostty.app` |
+| `CLABOX_APPS_DIR` | where `init` writes built `.app`s (`config.appBuilder.appsDir`) | `~/Applications` |
+| `CLABOX_SIGN_ID` | codesign identity for built apps (`config.appBuilder.signId`); unset → ad-hoc | — |
+| `CLABOX_GHOSTTY_BASE_CONFIG` | leading `config-file = …` in generated Ghostty configs | — |
+| `CLABOX_CLABOX_BIN` | `clabox` path baked into the Ghostty `command` (`config.appBuilder.claboxBin`) | autodetect |
+| `CLABOX_DEBUG` | print profile/config/dir diagnostics on launch | — |
+| `TMPDIR` | where the generated profile is stored | `/tmp` |
+
+## Limitations
+
+- **macOS only** — needs `sandbox-exec` (Seatbelt). Formally deprecated, still works on macOS 14/15.
+- **No nested sandbox** — you cannot launch the sandbox from inside another sandbox (`sandbox_apply: Operation not permitted`). Run from a bare host.
+- **Keychain is writable** for OAuth refresh (else tokens hit 401 after ~24h). For a stricter setup, swap the RW Keychain block for RO in `src/sandbox/profile.ts` (the "Keychain access" section).

package/lib/aliases-DKGcMHHe.js

@@ -0,0 +1,60 @@
+import path from "node:path";
+//#region src/init/aliases.ts
+/** The `clabox-<name>` command name for a box. */
+function aliasName(profile) {
+	return `clabox-${profile}`;
+}
+/** Build the source-able `index.sh` defining one function per box. */
+function buildIndex(profiles, { configsDir, scriptsDir }) {
+	const indexPath = path.join(scriptsDir, "index.sh");
+	const usage = profiles.map((p) => `#   ${aliasName(p)}`);
+	const defs = profiles.map((p) => `${aliasName(p)}() { _clabox_run ${p} "$@"; }`);
+	return `${[
+		"#!/usr/bin/env bash",
+		"# Generated by `clabox init` — do not edit; rerun it after changing the configs dir.",
+		"#",
+		"# Source this from ~/.zshrc or ~/.bashrc:",
+		`#   source ${indexPath}`,
+		"#",
+		"# Commands (run from any cwd). yolo vs. safe is set by each box's preset:",
+		...usage,
+		"",
+		"_clabox_run() {",
+		`  CLABOX_CONFIGS_DIR="${configsDir}" clabox -b "$1" "\${@:2}"`,
+		"}",
+		"",
+		...defs
+	].join("\n")}\n`;
+}
+/** Build a standalone wrapper script that sources `index.sh` and calls one fn. */
+function buildWrapper(fnName, indexPath) {
+	return `${[
+		"#!/usr/bin/env bash",
+		"# Generated by `clabox init`.",
+		"set -euo pipefail",
+		`source "${indexPath}"`,
+		`${fnName} "$@"`
+	].join("\n")}\n`;
+}
+/** All files `clabox init` writes: the `index.sh` plus a wrapper per box. */
+function buildAliasFiles(profiles, paths) {
+	const indexPath = path.join(paths.scriptsDir, "index.sh");
+	const files = [{
+		path: indexPath,
+		content: buildIndex(profiles, paths),
+		executable: true
+	}];
+	for (const p of profiles) {
+		const fn = aliasName(p);
+		files.push({
+			path: path.join(paths.scriptsDir, `${fn}.sh`),
+			content: buildWrapper(fn, indexPath),
+			executable: true
+		});
+	}
+	return files;
+}
+//#endregion
+export { buildWrapper as i, buildAliasFiles as n, buildIndex as r, aliasName as t };
+
+//# sourceMappingURL=aliases-DKGcMHHe.js.map

package/lib/aliases-DKGcMHHe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliases-DKGcMHHe.js","names":[],"sources":["../src/init/aliases.ts"],"sourcesContent":["// Pure builder for the shell aliases emitted by `clabox init`.\n//\n// For each box config (`<name>.mjs` / `<name>.config.mjs`) it produces one\n// command `clabox-<name>` that runs that box. Whether it runs yolo or asks for\n// confirmation is decided by the box's own preset (its `claudeArgs`), not here.\n// Plus an `index.sh` defining them all as shell functions to `source`.\n\nimport path from 'node:path';\n\n/** A file to be written by `clabox init`. */\nexport interface InitFile {\n  /** Absolute path to write. */\n  path: string;\n  /** File contents. */\n  content: string;\n  /** Whether to `chmod +x` after writing. */\n  executable: boolean;\n}\n\n/** Absolute locations for the generated artifacts. */\nexport interface AliasPaths {\n  /** Dir holding the box config files. */\n  configsDir: string;\n  /** Dir to emit `index.sh` and the per-box wrappers into. */\n  scriptsDir: string;\n}\n\n/** The `clabox-<name>` command name for a box. */\nexport function aliasName(profile: string): string {\n  return `clabox-${profile}`;\n}\n\n/** Build the source-able `index.sh` defining one function per box. */\nexport function buildIndex(profiles: string[], { configsDir, scriptsDir }: AliasPaths): string {\n  const indexPath = path.join(scriptsDir, 'index.sh');\n  const usage = profiles.map((p) => `#   ${aliasName(p)}`);\n  const defs = profiles.map((p) => `${aliasName(p)}() { _clabox_run ${p} \"$@\"; }`);\n  return `${[\n    '#!/usr/bin/env bash',\n    '# Generated by `clabox init` — do not edit; rerun it after changing the configs dir.',\n    '#',\n    '# Source this from ~/.zshrc or ~/.bashrc:',\n    `#   source ${indexPath}`,\n    '#',\n    \"# Commands (run from any cwd). yolo vs. safe is set by each box's preset:\",\n    ...usage,\n    '',\n    '_clabox_run() {',\n    // Point `-b` at this dir so resolveBox picks the right .mjs/.config.mjs file.\n    `  CLABOX_CONFIGS_DIR=\"${configsDir}\" clabox -b \"$1\" \"\\${@:2}\"`,\n    '}',\n    '',\n    ...defs,\n  ].join('\\n')}\\n`;\n}\n\n/** Build a standalone wrapper script that sources `index.sh` and calls one fn. */\nexport function buildWrapper(fnName: string, indexPath: string): string {\n  return `${[\n    '#!/usr/bin/env bash',\n    '# Generated by `clabox init`.',\n    'set -euo pipefail',\n    `source \"${indexPath}\"`,\n    `${fnName} \"$@\"`,\n  ].join('\\n')}\\n`;\n}\n\n/** All files `clabox init` writes: the `index.sh` plus a wrapper per box. */\nexport function buildAliasFiles(profiles: string[], paths: AliasPaths): InitFile[] {\n  const indexPath = path.join(paths.scriptsDir, 'index.sh');\n  const files: InitFile[] = [\n    { path: indexPath, content: buildIndex(profiles, paths), executable: true },\n  ];\n  for (const p of profiles) {\n    const fn = aliasName(p);\n    files.push({\n      path: path.join(paths.scriptsDir, `${fn}.sh`),\n      content: buildWrapper(fn, indexPath),\n      executable: true,\n    });\n  }\n  return files;\n}\n"],"mappings":";;;AA4BA,SAAgB,UAAU,SAAyB;CACjD,OAAO,UAAU;AACnB;;AAGA,SAAgB,WAAW,UAAoB,EAAE,YAAY,cAAkC;CAC7F,MAAM,YAAY,KAAK,KAAK,YAAY,UAAU;CAClD,MAAM,QAAQ,SAAS,KAAK,MAAM,OAAO,UAAU,CAAC,GAAG;CACvD,MAAM,OAAO,SAAS,KAAK,MAAM,GAAG,UAAU,CAAC,EAAE,mBAAmB,EAAE,SAAS;CAC/E,OAAO,GAAG;EACR;EACA;EACA;EACA;EACA,cAAc;EACd;EACA;EACA,GAAG;EACH;EACA;EAEA,yBAAyB,WAAW;EACpC;EACA;EACA,GAAG;CACL,CAAC,CAAC,KAAK,IAAI,EAAE;AACf;;AAGA,SAAgB,aAAa,QAAgB,WAA2B;CACtE,OAAO,GAAG;EACR;EACA;EACA;EACA,WAAW,UAAU;EACrB,GAAG,OAAO;CACZ,CAAC,CAAC,KAAK,IAAI,EAAE;AACf;;AAGA,SAAgB,gBAAgB,UAAoB,OAA+B;CACjF,MAAM,YAAY,KAAK,KAAK,MAAM,YAAY,UAAU;CACxD,MAAM,QAAoB,CACxB;EAAE,MAAM;EAAW,SAAS,WAAW,UAAU,KAAK;EAAG,YAAY;CAAK,CAC5E;CACA,KAAK,MAAM,KAAK,UAAU;EACxB,MAAM,KAAK,UAAU,CAAC;EACtB,MAAM,KAAK;GACT,MAAM,KAAK,KAAK,MAAM,YAAY,GAAG,GAAG,IAAI;GAC5C,SAAS,aAAa,IAAI,SAAS;GACnC,YAAY;EACd,CAAC;CACH;CACA,OAAO;AACT"}

package/lib/aliases-DXyz-ufw.d.ts

@@ -0,0 +1,31 @@
+//#region src/init/aliases.d.ts
+/** A file to be written by `clabox init`. */
+interface InitFile {
+  /** Absolute path to write. */
+  path: string;
+  /** File contents. */
+  content: string;
+  /** Whether to `chmod +x` after writing. */
+  executable: boolean;
+}
+/** Absolute locations for the generated artifacts. */
+interface AliasPaths {
+  /** Dir holding the box config files. */
+  configsDir: string;
+  /** Dir to emit `index.sh` and the per-box wrappers into. */
+  scriptsDir: string;
+}
+/** The `clabox-<name>` command name for a box. */
+declare function aliasName(profile: string): string;
+/** Build the source-able `index.sh` defining one function per box. */
+declare function buildIndex(profiles: string[], {
+  configsDir,
+  scriptsDir
+}: AliasPaths): string;
+/** Build a standalone wrapper script that sources `index.sh` and calls one fn. */
+declare function buildWrapper(fnName: string, indexPath: string): string;
+/** All files `clabox init` writes: the `index.sh` plus a wrapper per box. */
+declare function buildAliasFiles(profiles: string[], paths: AliasPaths): InitFile[];
+//#endregion
+export { buildIndex as a, buildAliasFiles as i, InitFile as n, buildWrapper as o, aliasName as r, AliasPaths as t };
+//# sourceMappingURL=aliases-DXyz-ufw.d.ts.map