Metadata-Version: 2.4
Name: worktree-atlas
Version: 1.0.0
Summary: A private, read-only dashboard for your Git workspaces
Author: Matthew Chapin
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Worktree Atlas

A private, read-only dashboard for finding unfinished work across your Git
projects. See branches, staged and unstaged files, conflicts, linked worktrees
and local divergence without opening every checkout.

**Python 3.10+ · Git 2.36+ · macOS or Linux · no runtime dependencies**

## Open your workspace

From this directory:

```sh
python3 -m worktree_atlas serve ~/projects --open
```

The dashboard opens at **http://127.0.0.1:8743**. Stop it with Ctrl+C.
Use `--port 0` to choose an available port. No account, telemetry, remote Git
requests, background installation or internet connection is needed.

To inspect only named checkouts, including checkouts nested in a larger repo:

```sh
python3 -m worktree_atlas serve ~/projects/web ~/projects/api --depth 0 --no-worktrees --open
```

By default, discovery reaches three directory levels below each supplied root
and adds registered linked worktrees, even outside those roots. Supply
`--no-worktrees` to keep discovery within the selected roots. Dependency/build
directories are excluded. Symlink targets are resolved and deduplicated.

## Terminal reports

```sh
python3 -m worktree_atlas scan ~/projects --depth 2
python3 -m worktree_atlas scan ~/projects --json > workspace.json
python3 -m worktree_atlas --help
```

Exit status: **0** means inspection completed within the selected scope (dirty
work is a successful observation); **1** means an inspection error or exhausted
resource budget; **2** means invalid command arguments. Informational depth or
duplicate-path notices do not fail the command. JSON contains all observed file
counts, bounded file lists, diagnostics and the configured scope.

## Install the command

The public package and install guide are at
<https://atlas.thesolostack.dev/>. You can also build from this source tree:

```sh
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/worktree-atlas serve ~/projects --open
```

Installation uses setuptools to build the package. Running directly from the
source tree needs only Python and Git. All browser assets ship inside the
package; there is no frontend build step.

## Using the dashboard

- Search by checkout name, canonical path or branch; filter conflicts, changes,
  clean or linked worktrees; sort by attention, name, path or changed-file count.
- Select a checkout to inspect HEAD, upstream, last commit and active Git operations.
- Choose **Staged diff** or **Unstaged diff** beside a tracked changed file.
  Rename previews include the original path. Untracked contents are not served.
- **Refresh** rescans the same roots. The prior snapshot remains available if
  refresh fails. The update summary detects status and bounded metadata changes.
- **Copy path** copies the resolved checkout location. **Export JSON** downloads
  the snapshot, including its local paths and filenames.

Counts overlap: a file may have both staged and unstaged changes; conflicts
appear in the conflict count as well as relevant state counts. No label means
that work is safe to discard. Upstream numbers compare locally stored refs;
Atlas never fetches and cannot assert that a remote server is current.

## Inspection boundaries

Atlas disables Git helpers, optional index writes and network fetch behavior.
Its server binds to loopback and checks Host, Origin and a per-launch browser
token. It has no write, cleanup, shell-command or arbitrary-file endpoint.
It is designed for trusted local projects, not as a sandbox for hostile Git
executables or concurrently tampered filesystem mounts.

Defaults bound discovery to **300 checkouts**, **20,000 directory visits**,
**200,000 directory entries**, **60 seconds** overall and **5 seconds per Git
command**. A blocked OS filesystem call can exceed the overall budget; Git
processes have enforced deadlines. Status output is capped at 8 MiB; displayed
changes at 2,000 per checkout; each diff at 128 KiB. Incomplete observations are
visible and are never turned into a clean status.

System/global Git configuration is ignored and local content filters are
disabled, so results may differ from your terminal's configured Git, especially
global ignores or filter-normalized contents. A filter warning explains the
difference. Partial clones are explicitly refused to prevent lazy fetching.
Submodule contents are excluded from the parent's status; gitlink changes are
reported, and in-scope submodule checkouts may be inspected separately. Bare
repositories have no working tree and produce an explicit notice.

Refresh uses stat metadata for the displayed changed paths and index, not file
content hashes. Edits beyond the displayed list or with preserved metadata may
not appear in the update summary. Each scan is an observation over time, not an
atomic snapshot. See [the inspection reference](docs/INSPECTION.md).

## Try a disposable workspace

```sh
python3 scripts/create_demo.py /tmp/atlas-demo
python3 -m worktree_atlas serve /tmp/atlas-demo --open
```

The demo creates five real checkouts: staged/unstaged work, an untracked draft,
a linked feature branch, a merge conflict, a clean project and an unborn branch.
The destination must not exist. It uses no network or personal Git identity.

## Verify and maintain

```sh
python3 -m unittest discover -s tests -v
node --check worktree_atlas/static/app.js
```

Optional browser acceptance requires Node 20+, Playwright with Chromium, and
optionally axe-core for automated accessibility checks:

```sh
npm install --no-save --package-lock=false playwright axe-core
npx playwright install chromium
ATLAS_AXE="$PWD/node_modules/axe-core/axe.min.js" node scripts/browser_acceptance.cjs
```

The script starts and stops its own server, creates/removes its own fixture,
and saves results/screenshots under ignored `artifacts/browser/`. For an existing
Playwright installation, set `ATLAS_PLAYWRIGHT` to its package path. `PYTHON`
selects the test interpreter. Automated accessibility checks supplement manual
review; they do not establish full accessibility conformance.

Project map: [architecture and safety](docs/INSPECTION.md),
[specification](SPEC.md), [campaign and beads](docs/CAMPAIGN.md),
[verification evidence](docs/VERIFICATION.md), [index](docs/INDEX.md).

Licensed under MIT.
