GitManager/AGENT.md

# AGENT.md

> **This file is the contract for Claude Code working on this repository.**
> Read it fully before any task. It defines the architecture, the non‑negotiable
> rules, and the self‑documenting workflow you must follow on every change.
>
> When this file and the code disagree, this file wins until you are explicitly
> told to change the file. If a request conflicts with a rule here, **pause and
> ask** before proceeding.

---

## 0. What this project is

A standalone, long‑lived development application: a **multi‑repo web dashboard for
Git**. It scans one or more configured roots on the host, discovers every Git
repository under them, and presents a control panel over the whole set — per‑repo
status (clean/dirty, ahead/behind, current branch), branches, remotes, recent
commits, stashes, and tags — plus user‑initiated Git actions (fetch, pull, push,
checkout, create branch, commit, view diffs, manage remotes). It has per‑user
dockable UI panels and is architected so that host/forge integrations
(GitHub/GitLab pull‑ and merge‑requests) can be attached without touching the
core.

This is a **dev environment first**. It is expected to grow continuously via
incremental requests ("add X functionality"). Every addition must keep the
self‑documenting workflow in Section 9 intact.

**Trust model:** there is **no user authentication**. The app is a single‑operator
tool that acts as the host user against local repositories. It binds to
**localhost** by default; exposing it to a network is the operator's decision and
their responsibility. Do not add a login/auth layer without asking.

---

## 1. Non‑negotiable architectural laws

These are hard rules. Do not violate them, do not "optimize them away," and do
not assume an exception without asking.

### 1.1 Web Components are the only UI unit (ActiveX‑spirit, enforced)

The UI is built **exclusively** from native Web Components. The design intent is
deliberately modeled on the *self‑contained control* philosophy of Windows‑98‑era
ActiveX/OCX controls — **the spirit, not the dead COM/binary/registry mechanism**.

Concretely, **every** UI element that does real work MUST be:

- A **Custom Element v1** (`customElements.define('x-thing', ...)`).
- Encapsulated with **Shadow DOM** (`attachShadow({mode:'open'})`). Styles and
  DOM are isolated. No leaking global CSS into components, no reaching out of a
  component into another component's internals.
- **Self‑instantiating**: the page declares the element in markup (or via a thin
  loader). The browser "constructs" it. The page does not micro‑manage it.
- **Independently live**: on connect, each component **fetches its own data and
  renders itself**. Components do **not** wait for a central controller to hand
  them data. One component being slow or failing must not block another.
- **Self‑contained**: no shared mutable global state. Cross‑component
  communication happens only via (a) DOM custom events (`dispatchEvent` of a
  `CustomEvent` that bubbles/composes) or (b) explicit attributes/properties set
  on the element. Treat each component like a control you could drop onto any
  page and it would just work.
- **Lifecycle‑correct**: implement `connectedCallback` / `disconnectedCallback`
  and clean up timers, listeners, and in‑flight fetches on disconnect.

If you are tempted to introduce a heavy SPA framework (React/Vue/Angular/Svelte)
for the component layer — **stop and ask.** The default answer is no. Vanilla
Web Components are the chosen model. (Small, dependency‑free helpers like
`lit` *may* be proposed, but only with explicit approval, because `lit` still
produces standards‑based custom elements.)

**Shared styling — design tokens.** The one sanctioned cross‑shadow‑boundary
styling channel is **CSS custom properties**. The shared theme palette and corner
radii live as tokens (`--color-*`, `--surface-*`, `--border-*`, `--fill-*`,
`--radius*`) in `web/static/app.css :root`; custom properties inherit *into* every
shadow root, so a component references them with `var(--…)` for all shared colors
and radii instead of hardcoding hex. This is **not** the forbidden "leaking global
CSS" — no global *selectors* reach into a component; it is the deliberate theming
layer (change a token once, the whole UI follows). Status feedback is semantic —
destructive/error use the `--color-danger*` set, success uses `--color-success`,
and Git‑state colors (ahead/behind, clean/dirty, conflicted) get their own
semantic tokens. **New or edited components MUST consume the tokens for shared
values** rather than reintroducing hardcoded hex.

### 1.2 Component foldering & per‑component docs

- There is a **top‑level `components/` folder**. All web components live there.
- **Each component gets its own folder**: `components/<component-name>/`.
- **Each component folder contains its own `<component-name>.md`** (see Section 9)
  that records the **history and intent** of that component and acts as the
  scoped context when working on it. Component‑specific detail belongs in that
  file, **not** in this AGENT.md. This keeps AGENT.md lean as the app grows.

### 1.3 Git is the system of record (the app never silently mutates a repo)

- **The Git repositories are the truth.** The app holds only a **derived,
  read‑optimized in‑memory index** of repo state (discovered repos, their status,
  branches, remotes, recent log), refreshed by the scanner (Section 5). That index
  is a cache — it can be thrown away and rebuilt from the repos at any time.
- **All mutations go through explicit, user‑initiated Git operations.** The app
  **never** writes to a repository except in direct response to a user action
  routed through the `internal/git` boundary. No background process ever mutates a
  working tree, index, or ref.
- **The background scanner is read‑only.** It may run `status`, `rev-list`,
  `for-each-ref`, `log`, and (only when explicitly enabled) `fetch`. It must never
  run a command that changes local state.
- **Never invent local persistence for domain state.** If something must survive a
  restart and it isn't already in Git, it is either app config (`.env`, Section
  1.4) or per‑user UI state (browser `localStorage`, Section 4). Adding any other
  datastore (SQLite, a server‑side DB) requires asking first — the default is no.

### 1.4 Destructive Git operations are explicit, confirmed, and never automatic

Operations that can lose work or rewrite shared history are a distinct class and
must be treated as such:

- **Always require an explicit, deliberate user action** (a dedicated control, not
  a side effect of another action) **and a confirmation** that names exactly what
  will happen and to which repo/branch.
- This class includes at least: `push --force`/`--force-with-lease`, `reset --hard`,
  `checkout`/`restore` that discards uncommitted changes, `clean -fd`, branch/tag
  deletion, `stash drop`/`clear`, history rewrites (`rebase`, `commit --amend`),
  and remote deletions.
- **Never chain a destructive operation into an automated flow** and never pick a
  destructive default. Prefer the safe variant (`--force-with-lease` over
  `--force`) and surface it as such.

### 1.5 Configuration via `.env`

Repo scan roots, the `git` binary path, scan/fetch behavior, the listen address,
and any optional forge tokens are all configurable through a single `.env` file. A
committed `.env.example` documents every variable. **Never commit a real `.env`**
and never hardcode paths, tokens, hosts, or the set of watched repositories.

### 1.6 Everything runs in Docker / docker‑compose

The dev environment (the Go app + hot reload) is brought up with
`docker compose up`. Because the app operates on repositories that live on the
**host**, the compose file **mounts the configured repo roots into the container**
(read‑write, since Git operations write to them) along with whatever Git needs to
authenticate to remotes (SSH agent socket / mounted keys, or a credential helper).
The app must be runnable by a new developer with: clone → copy `.env.example` to
`.env` → set the repo roots → `docker compose up`. Document any host‑side
prerequisites (SSH agent, credential helper) in `.env.example` and the help page.

---

## 2. Technology stack (locked unless told otherwise)

| Concern | Choice | Notes |
|---|---|---|
| Language | **Go** | Backend, page rendering, Git orchestration, scanner. |
| HTTP framework | **Echo** (`github.com/labstack/echo/v4`) | Idiomatic, fast, good middleware story. If you prefer Chi, ask first. |
| Page rendering | Go server‑rendered HTML shell | Server emits the page + declares web components; components fetch their own data. Use `html/template`. |
| Git access | **System `git` via `os/exec`**, wrapped behind an `internal/git` interface | The system binary is authoritative: it honors the user's credential helpers, SSH keys, hooks, and config exactly. Pure‑Go `go-git` may be proposed for cheap read‑only queries, but only behind the same interface and only with approval. |
| Repo discovery / index | **In‑memory cache + `github.com/fsnotify/fsnotify`** (optional) | Scan roots for `.git`, hold an index, refresh on interval and/or on filesystem change. |
| Forge integration (PRs/MRs) | **Provider‑abstracted** (`internal/forge`) — GitHub via `github.com/google/go-github`, GitLab via `gitlab.com/gitlab-org/api/client-go` | Optional, read‑only by default, enabled per‑host when a token is configured. See Section 8. |
| Diff rendering | Server produces unified diff from `git`; client renders it in a component | No heavy client diff lib without asking. |
| Config | **`.env`** via `github.com/joho/godotenv` + a typed config struct | Section 1.5. |
| Logging | **`log/slog`** → stdout/stderr (structured), optional rotating file sink | See Section 7. No database sink (there is no database). |
| Hot reload (dev) | **air** (`github.com/air-verse/air`) | Inside the app container. |

Anything not in this table that you want to add as a dependency: **propose it and
wait for approval.** Keep the dependency surface small. Note in particular there is
**no database and no auth library** — do not add one without asking (Section 1.3,
Section 0).

---

## 3. Repository layout (target)

```
.
├── AGENT.md                  # this file — lean, architecture-level only
├── CHANGELOG.md              # append-only running history of ALL changes (Section 9)
├── .env.example              # every config var, documented, no secrets
├── docker-compose.yml        # go app (+ hot reload); mounts host repo roots + git creds
├── Dockerfile                # multi-stage build for the Go app (git installed in the image)
├── .air.toml                 # hot reload config (dev)
├── cmd/
│   └── server/main.go        # entrypoint: wire config, git, scanner, router
├── internal/
│   ├── config/               # .env loading, typed config struct
│   ├── git/                  # THE Git boundary: interface + os/exec impl (all git ops)
│   ├── repos/                # discovery, in-memory index/cache, refresh scanner worker
│   ├── forge/                # OPTIONAL seam: GitHub/GitLab PR/MR + remote metadata (provider-abstracted)
│   ├── logging/              # slog handler → stdout/stderr (+ optional file)
│   └── render/               # html/template page shell rendering
├── components/               # ALL web components live here (Section 1.2)
│   └── <component-name>/
│       ├── <component-name>.md    # history + intent for THIS component (scoped context)
│       ├── <component-name>.js     # the custom element
│       └── <component-name>.css    # (optional) styles consumed inside shadow DOM
└── web/
    ├── static/               # shared static assets (app.css tokens, etc. — NOT component-specific)
    └── templates/            # Go html/template page shells (incl. help.html)
```

> If a new concern doesn't fit cleanly, **ask** before inventing a new top‑level
> directory. Keep `components/` strictly for web components. There is deliberately
> **no `migrations/` and no `db/`** — see Section 1.3.

---

## 4. UI layout & per‑user state (no server DB)

Because there is no authentication and no database, **per‑user UI state lives in
the browser** (`localStorage`), namespaced under a `gitmanager.*` prefix:

- Dockable panels: the **repo list docked LEFT**, the **repo detail panel docked
  RIGHT** by default. Dock options are `top`, `left`, `bottom`, `right`; positions
  are remembered in `localStorage` and reapplied on load.
- Other view state (selected repo, active filter/search, expanded sections, chosen
  branch view) also persists in `localStorage`.
- A **reset control** clears every `gitmanager.*` key and reloads to first‑load
  defaults (mirror the pattern: view state only — never touch the repos).

Server‑side there is no session and no user record. Requests act as the single
host operator.

---

## 5. Repo discovery & the refresh scanner (read‑only)

**Git is truth; the index is a derived cache.** Implement in `internal/repos`,
using the `internal/git` boundary for every command.

- **Discovery:** walk each configured root (`GIT_REPO_ROOTS`) for directories
  containing `.git`, honoring a configurable max depth and ignore globs. Build an
  in‑memory index keyed by absolute repo path.
- **Refresh (read‑only):** for each repo compute status (dirty/clean, staged vs
  unstaged counts), current branch, ahead/behind vs upstream, remotes, and a short
  recent‑commit summary — all via read‑only Git commands (Section 1.3). Refresh on
  a **configurable interval** and, optionally, on filesystem change via `fsnotify`.
- **Optional background `fetch`:** disabled by default. Only when
  `SCAN_FETCH_ENABLED=true` may the scanner run `git fetch` (network, read‑only to
  the working tree) to keep ahead/behind counts current. Rate‑limit it.
- **Never block a request on a slow repo.** The dashboard reads from the index;
  the scanner updates the index in the background. A single unreachable remote or
  huge repo must not stall the others (per‑repo timeouts, isolated goroutines).

Resulting data path:

```
Host repositories (system of record)
   │  read-only scan (status / rev-list / for-each-ref / log [/ fetch if enabled])
   ▼
internal/repos  ──►  in-memory index (per-repo state)
                         │
                         ▼
                    Echo JSON endpoints  ──►  web components (self-fetch)

User action ──► internal/git (os/exec) ──► repository mutated ──► index refresh
```

---

## 6. Dashboard & Git operations (client side)

The dashboard is composed of web components, each obeying Section 1 (shadow DOM,
self‑fetching, independent lifecycle, cleanup on disconnect). Expected surface
(create each with its own folder + `.md` as you build it):

- A **repo list / grid** of all discovered repos with status badges (branch,
  dirty/clean, ahead/behind), searchable/filterable.
- A **repo detail panel** for the selected repo: branches, remotes, recent commit
  log, stashes, tags.
- **Diff / commit views** rendered from server‑produced unified diffs.
- An **action surface** for Git operations. Safe operations (fetch, pull,
  checkout, create branch, stage, commit, push) can proceed on a normal click;
  **destructive operations follow Section 1.4** (explicit control + confirmation
  naming the target).
- Cross‑component communication is via bubbling/composed `CustomEvent`s (e.g. a
  `repo:select` event the detail panel listens for) — never shared globals.

Server endpoints return JSON for the components to self‑fetch; mutating endpoints
route through `internal/git` and trigger an index refresh for the affected repo so
the UI reflects reality without a full rescan.

---

## 7. Logging (structured, to stdout/stderr)

- Use Go's **`log/slog`** as the logging API throughout.
- Emit **structured records to stdout/stderr** (JSON in non‑dev, a readable
  console handler in dev). Capture: timestamp, level, message, structured
  attributes, request id, and the repo path when an operation targets one.
- **Log every Git mutation** (the command, target repo/branch, and outcome) so the
  operator has an audit trail of what the tool did on their behalf.
- Optionally also write to a **rotating file** when `LOG_FILE` is set. There is no
  database sink — do not add one (Section 1.3).

---

## 8. Forge integration — OPTIONAL seam (PRs / MRs)

Viewing pull/merge requests requires talking to a hosting provider, which is
**outside** the "Git is the store" core. Keep it isolated and optional.

- Live in `internal/forge` behind a **provider interface** so GitHub, GitLab, and
  others can drop in without touching the dashboard or the Git boundary.
- **Read‑only by default**: list open PRs/MRs and their CI/check status for a repo
  whose remote points at a supported host. Any write action (comment, merge,
  approve) is a **separate, explicitly‑requested** capability — do not build write
  paths without asking, and route them through Section 1.4 if destructive.
- **Enablement is per‑host and token‑gated.** Tokens come from `.env`
  (e.g. `GITHUB_TOKEN`, `GITLAB_TOKEN`); with no token, the feature is simply
  absent and the rest of the app works unchanged (**graceful degradation** — never
  a hard dependency).
- The provider is inferred from a repo's remote URL. Never send repo data to a host
  the user didn't configure.

Design the interface cleanly now; implement providers incrementally as requested.

---

## 9. Self‑documenting workflow (MANDATORY on every change)

This is how the project documents itself so AGENT.md stays small and each
component carries its own context.

### 9.1 Root `CHANGELOG.md`
- **On every change you make**, append an entry to root `CHANGELOG.md`. Never
  rewrite history; only append. Each entry:
  ```
  ## YYYY-MM-DD — <short title>
  - **What:** what changed (files, behavior).
  - **Why:** the intent / the request behind it.
  - **Affects:** components/areas touched.
  ```

### 9.2 Per‑component `<component-name>.md`
- When you **create a component**, create `components/<name>/<name>.md` with:
  ```
  # <component-name>

  ## Intent
  What this component is for; the ActiveX-spirit contract it fulfills.

  ## Public surface
  Tag name, attributes/properties, emitted events, what data it fetches and from where.

  ## History
  - YYYY-MM-DD: created — <reason>.
  - YYYY-MM-DD: <change> — <reason>.

  ## Notes / gotchas
  ```
- When you **work on an existing component**, **read its `.md` first** (it is the
  scoped context for that component), make the change, then **append to its
  History** and update Public surface if it changed.

### 9.3 User‑facing help page
- `web/templates/help.html` (served at `/help`, linked from the app header) explains
  **how to use the app** for end users. **When a user‑facing feature changes** — a new
  control, a changed workflow, a removed/renamed option — **update the help page in the
  same change**, the way you update the `CHANGELOG`. Keep it task‑oriented (how to do
  things), not implementation detail. Document any host prerequisites (SSH agent /
  credential helper for pushing from the container).

### 9.4 Keep AGENT.md lean
- Component‑specific detail lives in the component's `.md`, **not here**. Once a
  component has its own `.md`, **move any component‑specific detail out of
  AGENT.md** into that file. AGENT.md stays architecture‑level only.
- If a change alters an **architectural law or stack choice** in this file,
  update AGENT.md too — but only architecture‑level facts belong here.

---

## 10. How to take a new task ("add X functionality")

1. **Read** this AGENT.md, then any relevant component `.md` files.
2. **Check the rules** in Section 1. If the request conflicts, **pause and ask.**
3. If the work is UI: it is a **web component** in `components/<name>/` with its
   own `.md`. No exceptions without asking.
4. If it touches repositories: go through the **`internal/git` boundary**, respect
   **Git = system of record** (Section 1.3), and treat **destructive operations**
   per Section 1.4. Never add a datastore.
5. If it needs a **new dependency** or a **new top‑level folder**, propose it and
   wait for approval.
6. Implement, run it in the **docker‑compose dev environment**, verify hot reload
   and that it operates correctly against a real mounted repo.
7. **Document:** append to `CHANGELOG.md`; create/append the component `.md`;
   update `help.html` if user‑facing; trim AGENT.md if component detail crept in.

---

## 11. Open items to confirm before/while building
*(Claude Code: surface these to the human at the first relevant moment; don't
silently guess.)*

- **Repo discovery strategy:** recursive scan of `GIT_REPO_ROOTS` (max depth?
  ignore globs?) vs an explicit list of repo paths. Default assumption: recursive
  scan with a configurable depth.
- **Background `fetch`:** off by default (no unsolicited network). Confirm whether
  it should be enabled, and the interval / rate limit, before turning it on.
- **Git access library:** system `git` via `os/exec` is the locked default
  (Section 2). Confirm before introducing `go-git` for any read path.
- **Forge providers:** which to support first (GitHub? GitLab?), and whether any
  **write** actions (merge/comment/approve) are ever in scope (default: read‑only).
- **Listen address / exposure:** localhost‑only by default. Confirm before binding
  to a non‑local interface — there is no auth (Section 0).
- **Credential path from the container:** SSH agent socket vs mounted keys vs
  credential helper, for pushing/fetching from inside Docker.

---

*End of AGENT.md. Keep it lean. Let the CHANGELOG and per‑component `.md` files
carry the detail.*