sidebranch 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+Notable changes to sidebranch. This project follows
+[semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **Browser extension** (`extension/`) — a second delivery channel for the
+  widget: install once and every project you run `sidebranch start` in gets
+  the pill, with no `<script>` tag in your app. MV3, loadable unpacked, not
+  part of the npm package. Permissions are `storage` (a port override) plus
+  `http://localhost/*` and `http://127.0.0.1/*`. It has no service worker, so
+  all daemon traffic goes through the content script and every invariant in
+  `SECURITY.md` still holds. Unlike the tag, it can't be blocked by a page's
+  CSP — and can't reach a page served from `http://[::1]`.
+- **Extension toolbar popup** — undoes "Hide for this session", which is per
+  tab and previously needed a new tab to clear.
+- **View ports** — each pane gets a local pass-through proxy that deletes
+  `X-Frame-Options` and CSP `frame-ancestors`, so the compare view works with
+  apps that refuse framing. Removals are named in a `Sidebranch-Removed-Headers`
+  response header, bodies stream through byte-identical, and the proxy carries
+  the daemon's loopback/Host gate (upgrades included). Set `"frameProxy": false`
+  to disable. Direct pane ports are untouched.
+- **Frame-refusal detection** — the daemon probes for framing headers once per
+  server start, and the shell names the header and the fix instead of rendering
+  a blank rectangle.
+- **Info flyout** in the widget toolbar (ⓘ): start and stop commands with this
+  daemon's port substituted, click-to-copy, and which delivery channel you're
+  looking at.
+- `sidebranch stop` — shuts down the daemon and its pane dev servers from any
+  terminal. Backed by a per-repo `daemon.json` record, which also lets `start`
+  refuse to launch over an existing daemon, lets `clean` refuse to delete
+  worktrees out from under a running dev server, and lets `doctor` report
+  daemon status. Stale records are detected and cleared; no command signals a
+  process it hasn't confirmed is a sidebranch daemon.
+- `GET /handshake` — unauthenticated credential bootstrap returning
+  `{token, port, widget, version, apiVersion}` for the extension, behind the
+  same loopback/Host/Origin gate as every other route. Discloses nothing that
+  `GET /widget.js` did not.
+- `fontSource` option in `widget-core.js`, so a caller can pass the font as
+  binary instead of a URL. The extension uses it because a `FontFace` built
+  from a URL is subject to the page's `font-src` CSP.
+- `src/assets/geist-pixel.LICENSE.txt` — the bundled font is SIL OFL 1.1, not
+  MIT, and previously shipped without its license text.
+- A landing page under `site/`, deployed to GitHub Pages. Not part of the npm
+  package and adds no dependencies.
+- CI: the suite runs on Node 20/22/24 across Linux and macOS and asserts the
+  dependency count is still zero.
+- `prepublishOnly` runs the suite, so a red build can't reach the registry.
+- Releases publish from a tagged workflow with npm provenance.
+
+### Changed
+
+- The bundled UI font is now `geist-pixel.woff2` (24 KB) instead of
+  `geist-pixel.ttf` (3.7 MB). All 481 glyphs are retained and nothing renders
+  differently; the package drops from 3.8 MB unpacked to ~150 KB.
+- `src/assets/widget.js` split into `widget-core.js` (the UI) and `boot-tag.js`
+  (the tag channel's credential delivery). No user-visible change —
+  `GET /widget.js` serves the same assembled script. This is what lets the
+  extension ship the identical widget without shipping a secret.
+- `SECURITY.md` names a concrete reporting route.
+
+### Fixed
+
+- A worktree deleted from disk but still registered in git no longer wedges its
+  pane with a misleading `spawn git ENOENT`. `ensurePane` prunes the stale
+  registration and recreates the worktree; `doctor` reports the state. Also
+  fixes worktree path matching for deleted directories on macOS tmp paths
+  (the `/var` → `/private/var` symlink).
+- Piping CLI output (`sidebranch stop | head -1`) no longer crashes with EPIPE
+  when the pipe closes early.
+- The extension no longer injects the widget into the daemon's own `/shell`
+  page, which matched the content script like any other localhost dev server.
+- CI runs on Node 20 again. `node --test "test/*.test.js"` relies on glob
+  expansion Node only gained in v21, so both Node 20 jobs had been failing
+  without running a test. The glob is now unquoted and expanded by the shell.
+
+## [0.1.0]
+
+Initial release: loopback-only PR review sidecar with worktree panes, an
+in-page widget, and the side-by-side / blend / layer compare shell.

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 sidebranch contributors
+
+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.
+
+---
+
+The bundled font `src/assets/geist-pixel.woff2` is NOT covered by the MIT
+license above. It is a modified build of Geist Pixel, licensed under the SIL
+Open Font License, Version 1.1. See `src/assets/geist-pixel.LICENSE.txt` for
+the full text, the copyright notices, and a record of the modifications.

package/README.md

@@ -0,0 +1,368 @@
+# sidebranch
+
+Review pull requests from inside your running app. sidebranch is a local
+sidecar daemon plus a small in-page widget: pick a branch from a floating
+control and it appears in a dedicated **review worktree** on its own dev
+server. Your working tree, uncommitted changes and all, is never touched.
+Open a PR branch next to `main` in a synced side-by-side view, or stack them
+with a blend/layer diff to spot visual regressions.
+
+- **Framework-agnostic.** Next on 3000, Vite on 5173, Django on 8080 — if it
+  starts from a command and answers HTTP on a port, it works.
+- **Nothing leaves your machine.** The daemon binds loopback only, every
+  request is authenticated, and the widget is inert outside a localhost page.
+  Zero runtime dependencies — Node builtins only.
+- **Unobtrusive.** One small pill in the corner, rendered only when the daemon
+  is running. `×` hides it for the session, Esc closes the panel, and
+  `"widget": false` turns it off entirely.
+
+## How it works
+
+```
+your app (:5173, your working tree — never touched)
+   └── <script src="http://localhost:49400/widget.js">   ← the widget
+sidebranch daemon (127.0.0.1:49400)
+   ├── pane A → worktree ~/.sidebranch/…/panes/a → dev server :4410
+   ├── pane B → worktree ~/.sidebranch/…/panes/b → dev server :4411
+   └── /shell → compare view (side-by-side / blend / layer)
+```
+
+Panes are persistent review environments built on `git worktree`. Switching a
+pane to another branch is a checkout inside that pane. Dependencies are
+re-installed only when a lockfile actually changed (by content hash), and the
+dev server restarts only in that case; otherwise its file watcher picks up the
+checkout like any other change. Panes are never edited by hand, so they are
+always clean — nothing to stash, nothing to lose.
+
+## Quick start
+
+```sh
+cd your-repo
+npx sidebranch init      # writes .sidebranch.json — edit for your stack
+npx sidebranch start     # daemon on http://127.0.0.1:49400
+```
+
+Add the widget to your app, **dev builds only**:
+
+```html
+<script src="http://localhost:49400/widget.js" defer></script>
+```
+
+Gate it however your stack gates dev-only code, e.g.:
+
+```jsx
+// Next.js (app/layout.tsx)
+{process.env.NODE_ENV === "development" && (
+  <script src="http://localhost:49400/widget.js" defer />
+)}
+```
+
+```html
+<!-- Vite (index.html) -->
+<script>
+  if (import.meta.env.DEV) {
+    const s = document.createElement("script");
+    s.src = "http://localhost:49400/widget.js"; s.defer = true;
+    document.head.appendChild(s);
+  }
+</script>
+```
+
+If the tag does ship to production, it's harmless: the widget refuses to run
+on non-localhost pages, and a visitor's own daemon — if they run one — rejects
+requests from non-loopback origins. See [SECURITY.md](SECURITY.md).
+
+Then: click the pill → pick a branch → it builds and serves in pane A.
+**Open A** views it; **Compare A/B** opens the split view.
+
+### Or skip the tag: the browser extension
+
+The widget also ships as a Chrome/Edge extension, which puts the same pill on
+every project you run `sidebranch start` in without touching any app's HTML.
+It lives in [`extension/`](extension/) and loads unpacked:
+
+```
+chrome://extensions → Developer mode → Load unpacked → select extension/
+```
+
+It requests two origins — `http://localhost/*` and `http://127.0.0.1/*` — and
+one permission, `storage`, for a port override on its options page. It talks
+to nothing but your own daemon, and renders nothing if none is running.
+
+Two differences from the tag:
+
+- **A strict `Content-Security-Policy` can block the script tag.** It can't
+  block the extension, whose content script isn't subject to the page's CSP.
+  (The widget's font is bundled and loaded as binary so a strict `font-src`
+  can't downgrade it either.)
+- **A page served from `http://[::1]:5173` gets no widget from the
+  extension** — Chrome match patterns can't express an IPv6 literal. Use the
+  tag, or `http://localhost`, which reaches the same server.
+
+Everything else is identical, including the compare view. See
+[`extension/README.md`](extension/README.md) for details.
+
+Used **Hide for this session** and want the widget back? The flag is per tab,
+so a reload won't clear it — click the sidebranch toolbar icon and choose
+**Show the widget here**. (With the script tag, open a new tab.)
+
+## Configuration (`.sidebranch.json`)
+
+```jsonc
+{
+  "dev": "npm run dev",                 // start command, run inside each pane
+                                        //   {port} is substituted; PORT env is always set
+  "install": "pnpm install",            // run only when lockfiles change; "" disables
+  "ready": { "path": "/", "statuses": null },  // readiness probe; null = any HTTP answer
+  "panes": 2,                           // review environments kept warm (1–4)
+  "basePort": 4410,                     // first port tried for pane servers
+  "copy": [".env", ".env.local"],       // untracked files copied into new worktrees
+  "env": {},                            // extra env vars for the pane dev command
+                                        //   overrides inherited values; PORT etc. are reserved
+  "lockfiles": ["package-lock.json"],   // override the manifest list if needed
+  "widget": true,                       // false → /widget.js serves a no-op
+  "frameProxy": true                    // false → compare view frames panes directly
+}
+```
+
+Recipes:
+
+| Stack | `dev` | `install` |
+| --- | --- | --- |
+| Next.js | `npm run dev` | `npm install` |
+| Vite | `npx vite --port {port}` | `pnpm install` |
+| Django | `python3 manage.py runserver 127.0.0.1:{port}` | `pip install -r requirements.txt` |
+| Rails | `bin/rails server -p {port}` | `bundle install` |
+| Static | `python3 -m http.server {port} --bind 127.0.0.1` | *(empty)* |
+
+The daemon never parses server output. A pane is "ready" when its port answers
+the probe, which also catches servers that silently pick a different port than
+asked.
+
+## Complex apps: multiple processes, databases, and credentials
+
+sidebranch runs one process per pane and injects one port. Real apps often
+need more — a database or emulator, an auth proxy, a background worker,
+credentials for cloud services. That takes one architectural idea plus two
+config levers.
+
+### The one rule: per-pane process, shared singletons
+
+Your `dev` command is the only thing sidebranch runs per pane, and it can only
+vary one port. So anything that is a **singleton** — a database, an emulator
+on a fixed port, an auth proxy — must run once, outside sidebranch, shared by
+every pane and your own dev session. Keep the per-pane command down to the
+single server that renders the branch.
+
+If your normal dev command is a bundle like `concurrently "db" "web" "proxy"`,
+don't point sidebranch at it — two panes would each try to start the db and
+proxy on the same fixed ports and collide. Instead:
+
+- point `dev` at just the web server (`"dev": "npm run dev:web"`),
+- run the db/emulator/proxy once yourself, and
+- tell each pane how to reach them with `env`.
+
+### Two levers for everything a pane needs
+
+| Need | Lever | How |
+| --- | --- | --- |
+| An untracked **file** the app reads (`.env`, a service-account key, a cert) | `copy` | Copied from your main tree into each pane once, at creation. |
+| An **environment variable** (point at a shared service, flip a mode, unset a stale path) | `env` | Injected into the pane's dev command; overrides inherited values. |
+| A credential in a **machine-wide, out-of-tree location** (`~/.config/gcloud`, `~/.aws`, `~/.netrc`) | *(nothing)* | Panes run as you, so home-dir credentials resolve for free. |
+
+The third row is the one people miss: only in-repo, relative-path credentials
+break in a pane, because they resolve against the pane's own directory.
+Home-directory credentials need no `copy` and no `env`.
+
+### `env`: precedence and the empty-string unset
+
+`env` values layer on top of the inherited environment, so they override what
+your shell exported and what a copied `.env` would set. The exception is the
+vars sidebranch owns — `PORT`, `BROWSER`, `FORCE_COLOR`, `SIDEBRANCH` —
+because overriding `PORT` would break port injection. Those are dropped from
+`env` if you set them.
+
+Setting a var to the **empty string** unsets an inherited value:
+
+```jsonc
+"env": { "GOOGLE_APPLICATION_CREDENTIALS": "" }
+```
+
+That's the fix when a copied `.env` points a credential at an in-repo relative
+path: blank it in the pane and let the SDK fall back to your machine's default
+credentials.
+
+### Worked example: web app + database emulator + cloud credentials
+
+An app whose `npm run dev` starts an emulator, the web server, and a cloud
+auth proxy, and whose `.env` sets a relative-path service-account key:
+
+1. Keep the emulator running once (your normal dev session already starts it).
+2. Point the pane at just the web server, tell it to use the shared emulator,
+   and blank the in-repo key so cloud SDKs fall back to machine ADC:
+
+```jsonc
+{
+  "dev": "npm run dev:web",            // web server only — NOT the bundle
+  "install": "npm install",
+  "copy": [".env", ".env.local"],      // carry app config/secrets, but not the key file
+  "env": {
+    "FIRESTORE_EMULATOR_HOST": "127.0.0.1:8080",   // reach the shared emulator
+    "GOOGLE_APPLICATION_CREDENTIALS": ""           // fall back to ~/.config/gcloud ADC
+  }
+}
+```
+
+No credential file is copied into any pane, every pane points at the one
+shared emulator, and other cloud calls authenticate via machine-wide ADC.
+(Prerequisite: you've run your cloud CLI's "application default login" — the
+same setup your app already needs locally.)
+
+### Checklist for porting sidebranch into an app
+
+1. **What does your dev command start?** If it's more than one server, split
+   off the singletons.
+2. **Run the singletons once** (or confirm your normal dev session does).
+3. **Point `dev` at the single per-pane server**; make sure it honors `PORT`
+   (or use `{port}`).
+4. **`copy` the untracked files** the app needs — except secrets you can reach
+   another way.
+5. **For each service the app talks to**, choose: shared instance (`env` points
+   at it), machine-wide credential (free), or copied file (`copy`).
+6. **Blank any in-repo relative credential paths** with `"env": { "VAR": "" }`.
+7. **`npx sidebranch doctor`**, then `start`, then open a pane.
+
+### Prompt your coding agent to do it
+
+Paste this into Claude Code / Cursor / your agent of choice, from your repo
+root — it produces a `.sidebranch.json` tailored to your stack:
+
+```text
+Integrate sidebranch (a local PR-review sidecar) into this app. Steps:
+1. Read package.json (or the equivalent) and identify the dev command(s).
+   List every process and fixed port the normal dev workflow starts —
+   web server, database/emulator, proxies, workers.
+2. Identify which of those are singletons (fixed ports, shared state) vs the
+   single web server that actually renders the app.
+3. Find every credential/secret the app loads locally and where it comes
+   from: in-repo relative-path files, machine-wide locations (~/.config,
+   ~/.aws), or environment variables.
+4. Write a .sidebranch.json where:
+   - "dev" runs ONLY the web server, honoring the PORT env var (or {port}),
+   - "copy" lists the untracked files the app needs at runtime,
+   - "env" points the pane at the shared singletons and blanks ("") any
+     in-repo relative credential paths so SDKs fall back to machine defaults.
+5. Add the widget to the app's HTML/layout, gated to development only:
+   <script src="http://localhost:49400/widget.js" defer></script>
+6. Tell me exactly which singleton processes I must run once myself before
+   using panes, and any one-time credential setup (e.g. cloud ADC login).
+Do not modify my existing dev scripts or app code beyond adding the widget tag.
+```
+
+## Compare view
+
+`http://localhost:49400/shell` (or the **Compare A/B** button):
+
+- **Side by side** — both panes live, one width control driving both viewports
+  in lockstep (slider + 375/768/1280 presets).
+- **Blend diff** — panes stacked with `mix-blend-mode: difference`; identical
+  pixels go black, any change glows.
+- **Layer diff** — stacked with an opacity slider on the top pane.
+- **⇄ Swap** exchanges the panes' branches.
+
+Scroll and interaction sync between frames is out of scope: the stacked modes
+answer "did anything move?" and side-by-side answers "how does it behave?",
+without proxying or injecting script into your app.
+
+### Apps that refuse to be framed
+
+Panes and the compare view run on different ports, so they're different
+origins — an app sending `X-Frame-Options: SAMEORIGIN` or a restrictive
+`frame-ancestors` would render as a blank frame.
+
+So the compare view doesn't frame panes directly. Each pane gets a **view
+port**: a local pass-through proxy that deletes those two framing headers and
+nothing else, and names what it removed in a `Sidebranch-Removed-Headers`
+response header. Your app's code, its other headers, and the direct pane port
+(used by **Open in new tab**) are untouched, and your production config is
+never involved. Set `"frameProxy": false` to turn this off; a refusing app
+then gets an explanation in the pane instead of an embed. Details and
+safeguards: [SECURITY.md](SECURITY.md).
+
+## Non-goals and guarantees
+
+- sidebranch never runs a mutating git command against your primary working
+  tree. No stash, no reset, no checkout — reads only.
+- A dirty *pane* (someone edited a review worktree by hand) fails safe: the
+  switch is refused until you opt into discarding, and only files inside that
+  pane are affected.
+- Worktrees live under `~/.sidebranch/`, outside your repo, so file watchers
+  and tooling in your main tree never see them.
+
+## Stopping and cleanup
+
+`sidebranch stop` shuts down the daemon and its pane dev servers from any
+terminal, so you don't have to find the tab it's running in:
+
+```sh
+sidebranch stop
+```
+
+Pane worktrees survive a stop, so the next `start` reuses them instead of
+re-installing everything. That means a pane still holds the branch it last
+checked out, and git refuses to check out a branch already checked out
+elsewhere:
+
+```
+fatal: 'main' is already used by worktree at '/Users/you/.sidebranch/projects/.../panes/a'
+```
+
+`sidebranch clean` removes those worktrees:
+
+```sh
+sidebranch clean           # lists panes, asks to confirm, then removes them
+sidebranch clean --pane a  # target a single pane
+sidebranch clean --yes     # skip the confirmation prompt (for scripts/agents)
+```
+
+`clean` refuses to run while a daemon is serving this repo, since removing a
+worktree out from under a running dev server would leave it serving a
+directory that no longer exists. Run `stop` first; `clean` will say so if you
+haven't.
+
+Both commands work from a record the daemon writes to
+`~/.sidebranch/projects/<repo>/daemon.json`. If a daemon is killed outright
+(`kill -9`, a closed terminal), that record is left behind, and the next
+`stop`, `start`, or `doctor` clears it. Neither command signals a process it
+hasn't confirmed is a sidebranch daemon, so a stale record whose pid the OS
+has recycled is harmless.
+
+## Commands
+
+```
+sidebranch init      write starter config
+sidebranch start     run the daemon (--port N, default 49400)
+sidebranch stop      stop the daemon serving this repo
+sidebranch clean     remove stale pane worktrees for this repo (--pane, --yes)
+sidebranch doctor    environment checks (including daemon status)
+```
+
+## Development
+
+```sh
+node --test test/*.test.js
+```
+
+The suite covers the security gauntlet (token, Host/Origin gating, hostile ref
+names), the full worktree lifecycle against real fixture repos, and an
+end-to-end run that boots two panes on two branches and asserts both serve.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+One exception: the bundled UI font (`src/assets/geist-pixel.woff2`) is a
+modified build of [Geist Pixel](https://github.com/vercel/geist-font) under
+the SIL Open Font License 1.1, not MIT. Its license, copyright notices, and
+the modifications made are recorded in
+[`src/assets/geist-pixel.LICENSE.txt`](src/assets/geist-pixel.LICENSE.txt).

package/SECURITY.md

@@ -0,0 +1,161 @@
+# Security model
+
+sidebranch runs commands (`git`, your dev command, your install command) on
+behalf of a browser page. As designed, **nothing ever leaves the local machine and nothing
+non-local can ever reach in**.
+
+## Invariants (not configurable)
+
+1. **Loopback bind.** The daemon listens on `127.0.0.1` only. There is no
+   flag to bind elsewhere.
+2. **Peer verification.** Every request additionally checks the socket's
+   remote address is loopback (defense in depth against local forwarders).
+3. **Host header allowlist.** Requests whose `Host` is not
+   `localhost`/`127.x`/`[::1]` are rejected with 403. This defeats **DNS
+   rebinding**, where an attacker's domain resolves to 127.0.0.1 so a remote
+   page's requests arrive on a loopback socket — but with the attacker's
+   hostname in `Host`.
+4. **Origin allowlist.** Browser requests carrying an `Origin` are rejected
+   unless that origin is itself a loopback http(s) origin. `Origin: null`
+   (sandboxed iframes, `file://`) is rejected. Non-loopback origins never
+   receive CORS headers, so even the responses they can't be blocked from
+   *requesting* are unreadable to them.
+5. **Bearer token on every API call.** A 256-bit token is generated at
+   daemon start (rotates each run) and required — with constant-time
+   comparison — on all `/api/*` routes, including reads and the event
+   stream.
+6. **No shell, ever.** All child processes use `execFile`/`spawn` with
+   argument arrays. Branch names are validated twice (a conservative
+   allowlist regex, then `git check-ref-format --branch`) before reaching
+   git; names shaped like options (`-D`), paths (`..`), or containing any
+   shell-significant byte are rejected at the API boundary with 400.
+7. **No filesystem routing.** The daemon serves three embedded, fixed-path
+   assets (`widget.js`, `/shell`, and a bundled font used by both), a
+   credential bootstrap (`/handshake`), a liveness probe (`/healthz`), and
+   JSON APIs. Every servable path is a hardcoded route, not derived from
+   the request URL, so there is no traversal surface no matter how many
+   fixed routes that list grows to.
+8. **The user's working tree is read-only territory.** The daemon never
+   runs a mutating git command outside its own worktrees under
+   `~/.sidebranch/`.
+
+## Token delivery
+
+The token reaches a browser two ways, and both are unauthenticated by
+necessity — they are what *bootstrap* auth:
+
+1. **Embedded** into `widget.js` and `/shell` at response time, for the
+   `<script src>` integration.
+2. **Fetched** from `GET /handshake`, for the browser extension. An
+   extension cannot use route 1 at all: Manifest V3 forbids executing
+   remotely-fetched code, so the extension ships the widget in its own
+   package and has nowhere for a substituted token to arrive.
+
+Route 2 discloses nothing route 1 does not. Any caller that clears the gate
+below can already read the token out of the `widget.js` response body — the
+two routes are the same disclosure to the same audience, differing only in
+shape. Both are safe for the same reasons:
+
+(The bundled font both of them load via `@font-face` is unauthenticated for
+a different, simpler reason: a browser's font fetch cannot carry a custom
+`Authorization` header at all, so gating it by token was never an option.
+It carries no secret and no per-run state, so there's nothing at stake in
+it being fetchable by anything that already clears the loopback/Host/Origin
+gate below.)
+
+- They are only reachable from a loopback socket with a loopback Host
+  (invariants 1–3), so only local software can request them at all.
+- A **remote** page cannot read them: `fetch()` from a non-loopback origin
+  is rejected (invariant 4), and including `<script src="http://localhost:49400/widget.js">`
+  executes the code but cannot read its source — the token lives in a
+  closure, is never attached to `window`, the DOM, storage, cookies, or
+  URLs, and the widget exits before touching the token when the embedding
+  page is not loopback.
+- Local software on your machine could read them — but local software can
+  already run `git` as you directly. sidebranch does not attempt to defend
+  you from your own machine; no local tool can.
+
+## "What if the snippet ships to production?"
+
+Designed to be a non-event, twice over:
+
+1. The widget's first statement checks `location.hostname`; on any
+   non-loopback page it returns before creating DOM, globals, or network
+   traffic. Visitors see nothing and their browser sends nothing.
+2. Even a hand-modified copy that skipped that check would be talking to
+   the *visitor's* `localhost:49400`. If they don't run sidebranch, the
+   request fails. If they do, their daemon rejects the request because the
+   page's Origin (your production domain) is not loopback — before any
+   token check is even consulted.
+
+There is no third party in the path in any scenario: the script src is
+loopback, the API is loopback, and there is no telemetry, no analytics, no
+update check, and no outbound network code anywhere in the package.
+
+## Supply chain
+
+Zero runtime dependencies. The daemon, widget, and shell are Node builtins
+and vanilla browser APIs only. What you audit in this repo is everything
+that runs.
+
+## The shell page
+
+`/shell` is served with a strict CSP (`default-src 'none'` plus loopback
+allowances for frames and fetch), `X-Frame-Options: DENY`, `nosniff`, and
+`no-referrer`. It embeds only loopback iframes and talks only to the daemon.
+
+## View ports (the compare view's proxy)
+
+When `frameProxy` is on (the default), each pane gets a second loopback port —
+a pass-through proxy the compare view frames instead of the pane itself. It
+deletes exactly two things from responses: `X-Frame-Options` and the
+`frame-ancestors` CSP directive, and declares what it removed in a
+`Sidebranch-Removed-Headers` header. Bodies are streamed, never parsed or
+rewritten; every other header passes through untouched.
+
+Safeguards, mirroring the daemon's own gate:
+
+- Binds `127.0.0.1` only; non-loopback peers and non-loopback `Host` headers
+  are rejected (on websocket upgrades too).
+- `Sec-Fetch-Site: cross-site` is rejected, so a remote page cannot frame a
+  pane through it — the protection the stripped header was providing.
+- The target is fixed at construction to its own pane's port. Nothing in the
+  request selects where traffic goes, so it cannot proxy to anything else.
+- Dev only, local only, and off with `"frameProxy": false` — the compare view
+  then falls back to explaining a refused embed instead of hiding it.
+
+## Residual risks
+
+- **Your dev/install commands are trusted**, exactly like `npm run dev` is:
+  checking out and building a branch executes that branch's build tooling.
+  Reviewing a malicious PR locally is risky with or without sidebranch;
+  panes give you process isolation per branch but not a sandbox. If a PR is
+  untrusted, read the diff before you build it — with any tool.
+- **`copy` files** (e.g. `.env`) are duplicated into pane worktrees on your
+  own disk under `~/.sidebranch/`. Destroying a pane removes its worktree.
+- **HTTPS dev servers**: an https page cannot load the http widget (mixed
+  content). Run the daemon behind a locally-trusted cert if you need this;
+  do not weaken the invariants to work around it.
+- **The browser extension**, where used, runs on every page served from
+  `localhost`/`127.0.0.1` — that is the scope it requests and the only
+  scope it requests. It holds no permission for any other origin, so it
+  cannot see, and is never injected into, ordinary browsing. Within that
+  scope it does what the script tag does: talk to your daemon, on your
+  machine. All of its daemon traffic is issued from the content script, so
+  those requests carry the loopback page's own `Origin` and are admitted
+  by invariant 4 unchanged — no extension origin is allowlisted, and the
+  invariants above are not relaxed for it in any way.
+
+## Reporting
+
+Please report vulnerabilities privately, not as a public issue:
+
+- **Preferred:** [open a private security advisory](https://github.com/cristobalwee/sidebranch/security/advisories/new)
+  on the repository.
+  If you cannot use GitHub, open an issue asking for a private channel —
+  without any details of the vulnerability itself — and one will be
+  arranged.
+
+Expect an acknowledgement within a few days. This is a small project
+maintained by one person; there is no bounty program, but credit is given
+in the changelog for any report that leads to a fix.

package/bin/sidebranch.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+// `sidebranch stop | head -1` must not crash on EPIPE when the pipe closes.
+process.stdout.on("error", (e) => { if (e.code === "EPIPE") process.exit(0); throw e; });
+
+main(process.argv.slice(2))
+  .then((code) => { if (typeof code === "number" && code !== 0) process.exit(code); })
+  .catch((err) => {
+    process.stderr.write(`sidebranch: ${err.message}\n`);
+    process.exit(1);
+  });