treebox 0.3.0__tar.gz → 0.5.0__tar.gz

treebox-0.5.0/.github/workflows/autofix.yml

@@ -0,0 +1,69 @@
+name: Autofix
+
+# Applies ruff's auto-fixes (`ruff check --fix` + `ruff format`) to pull requests
+# and commits the result back to the PR branch. This is the CI counterpart to the
+# pre-commit hooks: if a change lands unformatted (hooks skipped), the branch is
+# fixed in place instead of just failing the CI gate. Skips fork PRs, where the
+# workflow token cannot push, and its own commits, to avoid loops.
+#
+# Gotcha: pushes made with the default GITHUB_TOKEN (from actions/checkout) do
+# NOT trigger new workflow runs. So the auto-fixed commit this job pushes will
+# not re-run ci.yml. Two implications:
+#   - If branch protection REQUIRES the CI status checks, the auto-fixed SHA will
+#     have no reported checks and the PR will stall. The remedy is to check out
+#     and push using a PAT or GitHub App token stored as a repo secret (e.g.
+#     AUTOFIX_TOKEN) instead of GITHUB_TOKEN, so the push re-triggers CI.
+#   - To close the "merged with a commit CI never validated" hole regardless,
+#     this job re-runs the ruff + mypy checks on the fixed tree below and fails
+#     rather than pushing if they don't pass, so the exact pushed commit is
+#     validated within this run.
+
+on:
+  pull_request:
+
+concurrency:
+  group: autofix-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  autofix:
+    name: ruff --fix
+    runs-on: ubuntu-latest
+    if: >-
+      github.event.pull_request.head.repo.full_name == github.repository &&
+      github.actor != 'github-actions[bot]'
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.head_ref }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+
+      - name: ruff check --fix
+        run: uv run --extra dev ruff check --fix src tests
+
+      - name: ruff format
+        run: uv run --extra dev ruff format src tests
+
+      - name: Validate fixed tree
+        run: |
+          uv run --extra dev ruff check src tests
+          uv run --extra dev ruff format --check src tests
+          uv run --extra dev mypy
+
+      - name: Commit fixes
+        run: |
+          if git diff --quiet; then
+            echo "No formatting or lint fixes needed."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -am "style: apply ruff --fix and format"
+          git push

{treebox-0.3.0 → treebox-0.5.0}/.github/workflows/ci.yml

@@ -29,6 +29,9 @@ jobs:
       - name: Lint
         run: uv run -p ${{ matrix.python-version }} --extra dev ruff check src tests
 
+      - name: Format
+        run: uv run -p ${{ matrix.python-version }} --extra dev ruff format --check src tests
+
       - name: Type check
         run: uv run -p ${{ matrix.python-version }} --extra dev mypy
 

treebox-0.5.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+# Pre-commit hooks: keep every commit lint-clean, formatted, and type-checked.
+# Install once with `uv run --extra dev pre-commit install` (or `pre-commit install`).
+# Run against everything with `uv run --extra dev pre-commit run --all-files`.
+#
+# Keep the ruff rev in sync with the `ruff>=…` pin in pyproject.toml's [dev] extra.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20
+    hooks:
+      # Lint and auto-fix (import sorting, pyupgrade, simplify, …), then format.
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  # mypy runs from the project's own dev environment so it sees typer/questionary
+  # stubs and the [tool.mypy] config (files = ["src"]). pass_filenames is off
+  # because that config already selects the files to check.
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run --extra dev mypy
+        language: system
+        types: [python]
+        pass_filenames: false

{treebox-0.3.0 → treebox-0.5.0}/CLAUDE.md

@@ -19,9 +19,11 @@ template it provisions is separately pinned to CPython 3.14.6).
 uv run treebox ...                      # run the CLI from the working tree
 uv run --extra dev python -m pytest     # full unit + integration suite
 uv run --extra dev python -m pytest tests/test_units.py::test_name   # single test (or -k <pattern>)
-ruff check src tests                    # lint
-uv run --extra dev mypy                 # type check (config in pyproject.toml)
-./scripts/validate.sh                   # lint + tests + live host-runner smoke (real uv, throwaway local remote)
+uv run --extra dev ruff check src tests # lint
+uv run --extra dev ruff format --check src tests   # format check (drop --check to apply)
+uv run --extra dev mypy                 # strict type check (config in pyproject.toml)
+uv run --extra dev pre-commit install   # install lint/format/strict type-check hooks (see CONTRIBUTING.md)
+./scripts/validate.sh                   # lint + format + tests + live host-runner smoke (real uv, throwaway local remote)
 uv pip install -e ".[dev]"              # editable dev environment
 uv run --extra docs mkdocs serve        # docs site (docs/ + mkdocs.yml), live-reloading
 uv run --extra docs mkdocs build --strict   # build docs to site/ (gitignored)
@@ -50,13 +52,13 @@ run (pluggable)**.
   git just works). `HARNESS_COMMANDS` maps `claude`/`codex` to their
   fully-autonomous launch argv.
 - **`cli.py`** (Typer) is the entry point: `create [NAME] / enter <ref> /
-  list / teardown <ref>... / doctor` (`ls`/`rm` are hidden aliases of
-  list/teardown). `enter`/`teardown` resolve a ref as
+  list / teardown <ref>... / doctor / version` (`ls`/`rm` are hidden aliases
+  of list/teardown). `enter`/`teardown` resolve a ref as
   name → live branch → unique substring (`resolve.py`); ambiguity exits 2.
-  It enforces **stable exit codes** (`0` ok · `2` usage · `3` not-found · `4`
-  auth/fetch · `5` conflict) and **`--json`** output carrying a
-  `schemaVersion` that only gains fields within a version — a breaking reshape
-  bumps it (git-porcelain discipline). Agents
+  It enforces **stable exit codes** (`0` ok · `1` runtime/doctor hard-check ·
+  `2` usage · `3` not-found · `4` auth/fetch · `5` conflict) and **`--json`**
+  output carrying a `schemaVersion` that only gains fields within a version —
+  a breaking reshape bumps it (git-porcelain discipline). Agents
   branch on these, so don't change their meanings casually.
 - **`ecosystems.py`** detects package managers (uv, npm, pnpm, go, cargo),
   drives their cache-backed setup, and defines which manifest files feed the
@@ -71,11 +73,14 @@ run (pluggable)**.
   with `git branch -m`). `create --checkout feature/auth` derives the name by
   flattening slashes to `--` (`feature--auth`); generated names come from
   `names.py`.
-- **`config.py`** is **user-level TOML only**, never read from the target repo —
-  a repo-level config could run arbitrary host commands. Same principle in
-  **`assets.py`**: the sandbox template is operator-owned and rendered into
-  a host-side dir *beside* the worktree, never inside the mount, so a boxed agent
-  cannot edit the config that defines its own sandbox.
+- **`config.py`** is **user-level TOML only** (`$TREEBOX_CONFIG`, else
+  `$TREEBOX_HOME/config.toml`, default `~/.treebox/config.toml`), never read
+  from the target repo — a repo-level config could run arbitrary host commands.
+  Same principle in **`assets.py`**: templates resolve from
+  `$TREEBOX_TEMPLATE_DIR`, then `$TREEBOX_HOME/templates/<name>` (default
+  `~/.treebox/templates/<name>`), and the sandbox template is operator-owned
+  and rendered into a host-side dir *beside* the worktree, never inside the
+  mount, so a boxed agent cannot edit the config that defines its own sandbox.
 
 ## Invariants to preserve
 

treebox-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+treebox is a small, one-maintainer project. Contributions are welcome, but the scope is intentionally modest.
+
+## Good contributions
+
+- Bug fixes with a clear reproduction.
+- Documentation fixes that make install, usage, or runner behavior clearer.
+- Small compatibility fixes that preserve the existing CLI and scripting behavior.
+
+For larger feature ideas, open an issue first so we can decide whether they fit the project.
+
+## Local checks
+
+Install the pre-commit hooks once so every commit is auto-formatted, lint-fixed,
+and type-checked in strict mode (`ruff format`, `ruff check --fix`, and `mypy`):
+
+```bash
+uv run --extra dev pre-commit install
+```
+
+Note: `pre-commit install` has no effect inside a treebox worktree, because
+treebox sets `core.hooksPath` for its own pre-push guard, so git ignores the
+hook pre-commit writes to `.git/hooks`. Run the hooks manually there with
+`uv run --extra dev pre-commit run --all-files`.
+
+If the hooks are skipped, the Autofix CI workflow applies the same `ruff --fix`
+and `ruff format` to same-repo PRs and pushes the result back. Note that pushes
+made with the default `GITHUB_TOKEN` do not re-trigger CI, so if this repo ever
+requires the CI status checks under branch protection, the auto-fixed commit
+will have no reported checks and the PR will stall; the remedy is to push from
+the workflow using a PAT or GitHub App token stored as a repo secret (e.g.
+`AUTOFIX_TOKEN`) instead of `GITHUB_TOKEN`.
+
+For code changes, run the relevant checks before opening a PR. Mypy runs in
+strict mode (configured in `pyproject.toml`):
+
+```bash
+uv run --extra dev python -m pytest
+uv run --extra dev ruff check src tests
+uv run --extra dev ruff format --check src tests
+uv run --extra dev mypy
+```
+
+For docs-only changes, this is enough:
+
+```bash
+uv run --extra docs mkdocs build --strict
+```
+
+## Boundaries
+
+Please preserve the basics: fresh refs by default, no trust in target-repo sandbox config, stable CLI output for scripts, and subscription-based agent auth.

{treebox-0.3.0 → treebox-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: treebox
-Version: 0.3.0
+Version: 0.5.0
 Summary: Isolated, ready-to-run git worktrees for AI coding agents — host-native or docker-sandboxed.
 Project-URL: Homepage, https://github.com/Seth-Peters/treebox
 Project-URL: Documentation, https://seth-peters.github.io/treebox/
@@ -23,9 +23,11 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Version Control :: Git
 Requires-Python: >=3.11
 Requires-Dist: questionary<3,>=2
+Requires-Dist: rich<16,>=13
 Requires-Dist: typer<1.0,>=0.12
 Provides-Extra: dev
 Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pre-commit>=4; extra == 'dev'
 Requires-Dist: pytest-cov>=6; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.15; extra == 'dev'
@@ -34,13 +36,13 @@ Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="assets/treebox-logo.png" alt="treebox" width="220">
+  <img src="https://raw.githubusercontent.com/Seth-Peters/treebox/main/assets/treebox-logo.png" alt="treebox logo: a small tree growing inside a glass box" width="300">
 </p>
 
-<h1 align="center">treebox</h1>
+<h1 align="center">Spin up worktrees, put them in a box,<br>tear them down - treebox</h1>
 
 <p align="center">
-  <strong>Isolated, ready-to-run git worktrees for AI coding agents.</strong>
+  <strong>Isolated, ready-to-run git worktrees for coding agents.</strong>
 </p>
 
 <p align="center">
@@ -59,17 +61,19 @@ Description-Content-Type: text/markdown
   <a href="https://www.linkedin.com/in/seth-peters/">Seth Peters</a>
 </p>
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Seth-Peters/treebox/main/assets/treebox-demo.gif" alt="treebox lifecycle demo: create, enter, ls, and an interactive teardown" width="900">
+</p>
+
 ---
 
-Run `treebox create` and it fetches, cuts a worktree from a fresh
-`origin/<base>`, copies your `.env`, installs dependencies from a shared
+`treebox` hands coding agents isolated, ready-to-run git worktrees — one
+directory per worktree name. `treebox create` fetches, cuts a worktree from a
+fresh `origin/<base>`, copies your `.env`, installs dependencies from a shared
 cache, and launches `claude` or `codex` inside. No branch name needed up
-front: the worktree gets a stable name (yours, or a generated petname) and an
-un-pushable `treebox/<name>` placeholder branch the agent renames when the
-work takes shape. Agents work the same repo in parallel without collisions —
-on a laptop or over plain SSH.
-
-Built by [Seth Peters](https://www.linkedin.com/in/seth-peters/) as a small, operator-focused layer for AI agent infrastructure: git worktrees, sandbox boundaries, subscription auth, and repeatable developer environments. If that is the kind of problem you are solving, the [docs](https://seth-peters.github.io/treebox/) go deeper on the design tradeoffs — and I'm [on LinkedIn](https://www.linkedin.com/in/seth-peters/) if you want to compare notes.
+front: the worktree gets a stable name and an un-pushable `treebox/<name>`
+placeholder branch the agent renames when the work takes shape. Agents work the same repo
+in parallel without collisions — on a laptop or over plain SSH.
 
 Provisioning is identical everywhere; a pluggable **isolation mode** decides
 where the agent runs:
@@ -79,26 +83,6 @@ where the agent runs:
 | `host` (default) | none      | the worktree shell                                    |
 | `docker`         | sandboxed | a docker container, with your `.env` + caches mounted |
 
-## Every agent ships its own cage
-
-Every coding agent invents its own answer to "run me in parallel" and "don't
-let me touch the wrong thing" — a different config file, a different schema, a
-different word for the same idea:
-
-| Agent | Sandbox / permission config | Built-in worktrees | Config lives in |
-| ----- | --------------------------- | ------------------ | --------------- |
-| **Claude Code** | `permissions` allow/ask/deny **+** native OS sandbox (Seatbelt/bubblewrap) **+** dev container | Yes (`--worktree`) | `.claude/settings.json`, `.devcontainer/` |
-| **OpenAI Codex** | `sandbox_mode` × `approval_policy` (Seatbelt / Landlock+seccomp) | No in CLI (app only) | `~/.codex/config.toml`, `[profiles.*]` |
-| **opencode** | `permission` per-tool allow/ask/deny (no OS sandbox) | No (community plugins) | `opencode.json` |
-| **pi** | none built-in ("all permissions by default"); BYO Docker/VM + trust prompt | No in core (`pi-subagents`) | `~/.pi/agent/settings.json` |
-
-Learn one and it teaches you nothing about the next, and none of it ports
-across tools. treebox owns the *isolation* layer instead — **one
-worktree-per-branch layout, one operator-owned sandbox, one config file** — and
-launches your agent of choice inside it. Learn treebox once; swap the agent,
-keep the box. Full comparison with citations:
-[Agents & sandboxing](https://seth-peters.github.io/treebox/agents/).
-
 ## Install
 
 ```bash
@@ -110,7 +94,7 @@ instructions if uv is missing — it never installs a package manager behind
 your back. Or install directly:
 
 ```bash
-uv tool install git+https://github.com/Seth-Peters/treebox
+uv tool install treebox
 ```
 
 Host isolation needs only `git` and a logged-in agent CLI (`claude` /
@@ -121,8 +105,7 @@ requirements and installer overrides.
 
 ## Usage
 
-The whole surface is five commands, and a worktree's life runs through all of
-them.
+The worktree lifecycle is five commands.
 
 **Check the host.** `doctor` verifies exactly what `create` will need — git,
 agent logins, `.env`, credentials for the required fetch — and prints the fix
@@ -149,7 +132,7 @@ the branch starts as a `treebox/<name>` placeholder that a per-worktree
 pre-push guard keeps **un-pushable** — rename it conventionally
 (`git branch -m feature/user-auth`, `fix/login-race`, `chore/bump-deps`, …)
 when the work has a shape, then push. So a machine-generated name can never
-become a PR title. `-b` is the one path that skips the placeholder: it checks out an
+become a PR title. `--checkout` is the one path that skips the placeholder: it checks out an
 existing branch exactly.
 
 `--base` takes any branch, not just `main` — branch off `dev`, or stack a new
@@ -157,10 +140,11 @@ worktree on top of an existing PR's branch, even while that branch is checked
 out in another worktree. It resolves as the freshly fetched `origin/<base>`,
 so push the base first if its latest commits only exist locally.
 
-**Enter.** Come back to an existing worktree, picking the agent per entry.
-The ref is the name, the *current* branch (renames are followed live), or a
-unique substring of either. Dependencies re-sync only if the lockfile changed
-since last time:
+**Enter.** Come back to an existing worktree. By default it reuses the harness
+the worktree was created with; an explicit `--harness` overrides it for that
+session only, without changing what's recorded on disk. The ref is the name,
+the *current* branch (renames are followed live), or a unique substring of
+either. Dependencies re-sync only if the lockfile changed since last time:
 
 ```bash
 treebox enter fix-auth --harness claude
@@ -186,12 +170,32 @@ treebox teardown fix-auth brave-otter --delete-branch
 treebox teardown                        # pick interactively
 ```
 
-treebox is built to be scripted, including by agents: every command takes
-`--json` (data to stdout, diagnostics to stderr, a schema that only gains
-fields within a version), `--dry-run` prints the exact commands without running them, and exit
-codes are stable (`0` ok · `2` usage · `3` not found · `4` auth · `5`
-conflict). Full reference in the
-[usage guide](https://seth-peters.github.io/treebox/usage/).
+treebox is built to be scripted, including by agents: the worktree commands and
+`doctor` take `--json` (data to stdout, diagnostics to stderr, a schema that
+only gains fields within a version), `--dry-run` prints the exact commands
+without running them, and exit codes are stable (`0` ok · `1` runtime/doctor
+blocked · `2` usage · `3` not found · `4` auth · `5` conflict). Full
+reference in the [usage guide](https://seth-peters.github.io/treebox/usage/).
+
+## Every agent ships its own cage
+
+Every coding agent invents its own answer to "run me in parallel" and "don't
+let me touch the wrong thing" — a different config file, a different schema, a
+different word for the same idea:
+
+| Agent | Sandbox / permission config | Built-in worktrees | Config lives in |
+| ----- | --------------------------- | ------------------ | --------------- |
+| **Claude Code** | `permissions` allow/ask/deny **+** native OS sandbox (Seatbelt/bubblewrap) **+** dev container | Yes (`--worktree`) | `.claude/settings.json`, `.devcontainer/` |
+| **OpenAI Codex** | `sandbox_mode` × `approval_policy` (Seatbelt / Landlock+seccomp) | No in CLI (app only) | `~/.codex/config.toml`, `[profiles.*]` |
+| **opencode** | `permission` per-tool allow/ask/deny (no OS sandbox) | No (community plugins) | `opencode.json` |
+| **pi** | none built-in ("all permissions by default"); BYO Docker/VM + trust prompt | No in core (`pi-subagents`) | `~/.pi/agent/settings.json` |
+
+Learn one and it teaches you nothing about the next, and none of it ports
+across tools. treebox owns the *isolation* layer instead — **one
+named-worktree layout, one operator-owned sandbox, one config file** — and
+launches your agent of choice inside it. Learn treebox once; swap the agent,
+keep the box. Full comparison with citations:
+[Agents & sandboxing](https://seth-peters.github.io/treebox/agents/).
 
 ## Design
 
@@ -207,14 +211,15 @@ conflict). Full reference in the
   hooks are ignored.
 - **Credentials go in as scoped copies.** Only the agents' login files are
   copied into a throwaway per-worktree dir — never the live `~/.claude` /
-  `~/.codex` — and treebox uses your subscription login, never
-  `ANTHROPIC_API_KEY`.
+  `~/.codex` — refreshed on every entry so a host logout or a fresh login
+  reaches the sandbox next time; treebox uses your subscription login.
 
 More in [how it works](https://seth-peters.github.io/treebox/how-it-works/).
 
 ## Configuration
 
-Optional, and user-level only (`~/.config/treebox/config.toml`) — treebox
+Optional, and user-level only (`$TREEBOX_CONFIG`, else
+`$TREEBOX_HOME/config.toml`, default `~/.treebox/config.toml`) — treebox
 never reads config from the target repo:
 
 ```toml
@@ -227,13 +232,54 @@ All keys, shared-cache overrides, setup hooks, and sandbox templates are
 covered in the
 [configuration guide](https://seth-peters.github.io/treebox/configuration/).
 
+## Customizing isolation
+
+`docker` isolation builds from a **template you own** — a directory of files
+treebox ships and you edit. treebox renders it beside the worktree so a boxed
+agent can't touch its own cage. Three steps:
+
+**1. Copy the template out** — you edit a copy, never the shipped one. Name it
+(here `node`); a `node` box and a `python` box can coexist, one per stack:
+
+```bash
+mkdir -p ~/.treebox/templates
+cp -R "$(python -c 'import treebox.assets, pathlib; print(pathlib.Path(treebox.assets.__file__).parent)')/container" \
+      ~/.treebox/templates/node
+```
+
+**2. Edit two files.** The shipped image already bundles Node 22, uv, `gh`,
+ripgrep, and the agent CLIs, so most projects touch only these:
+
+```dockerfile
+# ~/.treebox/templates/node/Dockerfile — global tooling
+USER root
+RUN npm install -g pnpm@9 typescript tsx
+USER ${USERNAME}
+```
+
+```json
+// ~/.treebox/templates/node/container.json — your install command
+"postCreate": "if [ -f pnpm-lock.yaml ]; then pnpm install --frozen-lockfile; elif [ -f package-lock.json ]; then npm ci; else npm install; fi"
+```
+
+(In docker, setup runs `postCreate`, not the host-mode ecosystem auto-detect,
+so a non-Python project wires its install here.)
+
+**3. Point treebox at it** — per run with `--isolation docker --template node`,
+or set `template = "node"` in `~/.treebox/config.toml`.
+
+Full walkthrough — every file in a template and the `container.json` schema — in
+the [configuration guide](https://seth-peters.github.io/treebox/configuration/#customizing-the-sandbox).
+
 ## Development
 
 ```bash
 git clone https://github.com/Seth-Peters/treebox && cd treebox
 uv run treebox ...                    # run the CLI from the working tree
+uv run --extra dev pre-commit install # lint/format/strict type-check hooks (see CONTRIBUTING.md)
 uv run --extra dev python -m pytest   # unit + integration suite
-./scripts/validate.sh                 # lint + tests + live host-runner smoke
+uv run --extra dev mypy               # strict type check
+./scripts/validate.sh                 # lint + format + tests + live host-runner smoke
 ```
 
 ## Contributing