# CLAUDE.md — SPB Git · Personal Git Platform for Simon-Pierre Boucher

Read this entire document before writing a single line of code. This file is the single source of truth for the project. Every architectural decision, naming convention, UI detail, and non-negotiable rule lives here. When in doubt, re-read this file. When this file conflicts with your instinct, this file wins.

# 0. Identity & Non-Negotiables

# 0.1 THE GOLDEN RULE — Mandatory Author Header

Every single file you generate — source, config, script, style, test, docs tooling — MUST begin with an author header. No exceptions. A file without this header is a bug.

Canonical template (adapt comment syntax per language):

/**
 * ─────────────────────────────────────────────
 *  SPB Git — Personal Git Platform
 * ─────────────────────────────────────────────
 *  Author  : Simon-Pierre Boucher
 *  Contact : contact@spboucher.ai
 *  File    : <relative/path/filename.ext>
 *  Purpose : <one-line description>
 *  License : MIT © Simon-Pierre Boucher
 * ─────────────────────────────────────────────
 */

Per-language syntax:

Additionally, the server itself must inject/verify this header: a lint script npm run check:headers fails CI if any tracked file in this project lacks the header. Provide scripts/inject-headers.mjs to add headers in bulk.

# 1. Product Vision

SPB Git is not a toy. It is a polished, self-hosted software forge — the personal equivalent of GitHub — that serves three purposes:

1. Canonical home for all of Simon-Pierre's repositories, clonable by anyone at https://git.spboucher.ai/<repo>.git.
2. Public showcase / portfolio: every repo page must look as good as (or better than) a GitHub repo page — rendered README with badges, syntax-highlighted code browsing, commit graphs, language stats.
3. Frictionless daily driver: a powerful CLI (spbgit) that manages all repos from the terminal — create, commit, push, sync, open — in single commands.

The bar for quality is: "If a stranger lands on git.spboucher.ai, they should assume a small team built this."

# 2. High-Level Architecture

┌────────────────────────────  node m3u96a  ────────────────────────────┐
│                                                                       │
│  ┌─────────────┐   ┌───────────────────────────────────────────────┐  │
│  │   ngrok      │   │              SPB Git Server (Node 20)         │  │
│  │  tunnel      │──▶│  Fastify app :7420                            │  │
│  │ git.spboucher│   │  ├─ /            Web UI (SSR, Nunjucks)       │  │
│  │    .ai       │   │  ├─ /api/v1/*    JSON API                     │  │
│  └─────────────┘   │  ├─ /:repo.git/* Git Smart HTTP (backend)     │  │
│                    │  ├─ /raw/*        Raw file serving             │  │
│                    │  └─ /archive/*    zip/tar.gz snapshots         │  │
│                    └───────────────┬───────────────────────────────┘  │
│                                    │                                  │
│         ┌──────────────────────────┼───────────────────────────┐      │
│         │                          │                           │      │
│  ┌──────▼──────┐  ┌────────────────▼─────────┐  ┌──────────────▼───┐  │
│  │ /srv/git/   │  │ /srv/spbgit/data/        │  │ /srv/spbgit/     │  │
│  │ *.git       │  │ meta.json (repo index)   │  │ cache/           │  │
│  │ bare repos  │  │ tokens, hooks, stats     │  │ rendered HTML,   │  │
│  │ (source of  │  │                          │  │ lang stats, zips │  │
│  │  truth)     │  │                          │  │                  │  │
│  └─────────────┘  └──────────────────────────┘  └──────────────────┘  │
└───────────────────────────────────────────────────────────────────────┘

Principles:

• Filesystem is the database. Bare Git repos under /srv/git/ are the source of truth. A single meta.json holds per-repo metadata (description, topics, pinned, homepage, created date). No SQL/NoSQL database.
• Cache aggressively, invalidate on push. Rendered READMEs, language stats, commit counts, and archives are cached in /srv/spbgit/cache/ keyed by <repo>@<commit-sha>; a post-receive hook busts the cache.
• SSR-first web UI. Server-rendered pages (Nunjucks templates + a small vanilla JS layer). No SPA framework. Fast, crawlable, sharp.

# 2.1 Repository Layout of this project

spbgit/
├── CLAUDE.md                  # this file
├── README.md                  # project readme (with badges, of course)
├── package.json
├── src/
│   ├── server.mjs             # Fastify bootstrap
│   ├── config.mjs             # env + config loading (zod-validated)
│   ├── git/
│   │   ├── smart-http.mjs     # upload-pack / receive-pack over HTTP
│   │   ├── repo.mjs           # repo model: branches, tree, blob, log, blame
│   │   ├── hooks.mjs          # post-receive hook installer + handlers
│   │   └── archive.mjs        # zip / tar.gz snapshot generation
│   ├── auth/
│   │   └── token.mjs          # owner PAT verification (argon2-hashed)
│   ├── render/
│   │   ├── markdown.mjs       # GFM pipeline (markdown-it + plugins)
│   │   ├── highlight.mjs      # code highlighting (shiki)
│   │   └── og-image.mjs       # dynamic Open Graph card per repo (satori/resvg)
│   ├── api/
│   │   └── v1.mjs             # JSON API routes
│   ├── web/
│   │   ├── routes.mjs         # HTML routes
│   │   ├── views/             # Nunjucks templates
│   │   └── assets/            # css (hand-written, design tokens), js, fonts, logo
│   └── stats/
│       ├── languages.mjs      # linguist-style language detection + percentages
│       └── activity.mjs       # commit calendar / punch-card data
├── cli/
│   ├── spbgit.mjs             # entry point (bin)
│   └── commands/              # one file per command
├── deploy/
│   ├── ngrok.yml
│   ├── ecosystem.config.cjs   # pm2: server + ngrok, autorestart
│   ├── spbgit.service         # systemd alternative
│   ├── setup-m3u96a.sh        # idempotent server bootstrap script
│   └── backup.sh              # nightly tar of /srv/git + meta.json
├── scripts/
│   ├── inject-headers.mjs
│   └── check-headers.mjs
└── test/                      # vitest: unit + integration (smart HTTP round-trip)

# 3. Git Hosting Engine

# 3.1 Smart HTTP protocol

• Implement Git Smart HTTP v2 by spawning git upload-pack / git receive-pack (via git http-backend or direct spawn with proper pkt-line streaming — stream, never buffer packfiles).
• Routes:
  • GET /:repo.git/info/refs?service=git-upload-pack → public (clone/fetch/pull).
  • POST /:repo.git/git-upload-pack → public.
  • GET /:repo.git/info/refs?service=git-receive-pack → auth required.
  • POST /:repo.git/git-receive-pack → auth required (push).
• Auth for push: HTTP Basic where username = spb and password = a Personal Access Token. Tokens are generated by spbgit token new, stored argon2-hashed in data/tokens.json, revocable, with a label and last-used timestamp.
• Set correct Content-Type, chunked encoding, gzip request body support (Content-Encoding: gzip from git clients), and side-band progress passthrough.
• Repo names: ^[a-z0-9][a-z0-9._-]{0,63}$. Reject path traversal hard.

# 3.2 Post-receive hooks (installed automatically in every bare repo)

On every push, the hook POSTs to http://127.0.0.1:7420/internal/hooks/post-receive (localhost-only route) which:

1. Busts all caches for that repo.
2. Recomputes language stats + default-branch README render (warm cache).
3. Appends an event to the activity feed (data/activity.jsonl).
4. Regenerates the repo's OG image.

# 3.3 Repo lifecycle

• POST /api/v1/repos (auth) → git init --bare, install hooks, write meta.json entry, set HEAD to refs/heads/main.
• PATCH /api/v1/repos/:name (auth) → description, topics (max 10), homepage URL, pinned flag, default branch.
• DELETE /api/v1/repos/:name (auth) → moves repo to /srv/git/.trash/<name>-<timestamp>.git (soft delete, recoverable for 30 days).
• Everything is public: there is no private field anywhere in the codebase. Don't build one.

# 4. Web UI — "It must look sharp" (Design Spec)

# 4.1 Design system

• Aesthetic: modern developer-forge. Dark theme by default, light theme toggle (persisted in localStorage, respects prefers-color-scheme on first visit).
• Design tokens (CSS custom properties in assets/css/tokens.css):
  • Dark: background #0b0e14, surface #11151c, border #1f2530, text #e6e9ef, muted #8b93a3, accent #4f8cff, accent-2 #22d3aa, danger #ff5d5d.
  • Radius 10px, subtle 1px borders, no heavy shadows; hover states elevate with border-color shifts, not box-shadows.
• Typography: Inter (UI) + JetBrains Mono (code), self-hosted woff2 in assets/fonts/ — no third-party font CDNs.
• Layout: max-width 1200px, sticky top nav: logo "SPB Git" (monogram SVG), global search input (/ focuses it), theme toggle, link to spboucher.ai.
• Fully responsive down to 360px. Code views scroll horizontally, never break the page.
• Footer on every page: © Simon-Pierre Boucher · contact@spboucher.ai · Powered by SPB Git.

# 4.2 Pages

/ — Home / repo index

• Hero strip: avatar/monogram, "Simon-Pierre Boucher", tagline, contact link, count badges (X repos · Y commits · Z languages).
• Pinned repos grid (up to 6 cards) then full repo list.
• Repo card: name, description, top language with colored dot (GitHub linguist colors), star-like "clone count" if tracked, last-pushed relative time ("3 h ago"), topic chips.
• Controls: search-as-you-type filter, sort by Recently pushed / Name / Created, filter by language and topic.
• Activity feed sidebar: last 15 pushes ("pushed 3 commits to api-tools · 2 h ago").
• Commit calendar (GitHub-style contribution heatmap, last 52 weeks, SVG, tooltip per day).

/:repo — Repo home

• Header: repo name (breadcrumb spb / name), description, topic chips, homepage link, language bar (stacked percentage bar like GitHub, with legend).
• Clone box: HTTPS URL with copy button + spbgit clone <name> snippet + "Download ZIP".
• Meta row: default branch selector, branch/tag counts, commit count, repo size, license badge (auto-detected from LICENSE).
• File table for the current tree: icon, name, last commit message touching that path, relative date (computed efficiently via a single git log walk, cached).
• README.md rendered below the file table. See §5 — this must be pixel-perfect.

/:repo/tree/:ref/*path — directory browsing (same file table pattern).

/:repo/blob/:ref/*path — file view:

• Sticky header: path breadcrumb, size, LOC, buttons: Raw, Blame, History, Copy permalink (permalink pins the commit SHA).
• Shiki-highlighted code with line numbers; clickable line anchors (#L42, ranges #L10-L20 with highlight).
• Markdown files render as HTML by default with a "View source" toggle. Images display inline. Jupyter notebooks: at minimum render as pretty JSON with a note (nice-to-have: nbconvert-style render).
• Binary files: show size + download button; images/SVG preview inline.

/:repo/commits/:ref — paginated history (40/page): avatar-less but with identicon per author email, message (first line, expandable body), short SHA chip (copy on click), relative + absolute date, files-changed count.

/:repo/commit/:sha — full diff view: per-file collapsible diffs, syntax-highlighted, green/red gutters, stats header (+X −Y across N files), rename/binary detection.

/:repo/blame/:ref/*path — blame view with commit hunks grouped and color-aged (newer = brighter accent).

/:repo/branches, /:repo/tags — lists with ahead/behind counts vs default branch (branches) and archive download links (tags → releases-lite).

/search?q= — global search across repo names, descriptions, topics, and README content (build a tiny inverted index in cache; refresh on push). Grouped results.

Error pages — custom 404/500 with the design system (404: "This ref does not exist in any timeline.").

# 4.3 Meta / polish

• Every page: proper <title>, meta description, canonical URL, Open Graph + Twitter card with the dynamically generated per-repo OG image (repo name, description, language bar — generated with satori → resvg, cached).
• sitemap.xml + robots.txt + RSS/Atom feed of activity at /feed.atom.
• Favicon set (SVG + PNG) with the SPB monogram.
• Lighthouse targets: Performance ≥ 95, A11y ≥ 95. No render-blocking third-party requests at all.

# 5. README & Markdown Rendering — Badge-Perfect (Critical)

This is a flagship feature. The rendered README must be indistinguishable from GitHub's rendering quality.

Pipeline (src/render/markdown.mjs), built on markdown-it +:

• GFM tables, task lists (rendered checkboxes, disabled), strikethrough, autolinks, footnotes.
• Heading anchors with hover link icon; auto-generated slug IDs (GitHub algorithm) so #installation links work.
• Syntax highlighting in fenced blocks via shiki (same themes as file view; dual dark/light output via CSS variables). Support ```mermaid blocks → render client-side with mermaid.js (lazy-loaded only when present).
• Badges & images:
  • Badges (img.shields.io, etc.) must render inline, on one line, correctly sized — CSS: img[src*="shields.io"], img[height] { display: inline-block; vertical-align: middle; } and consecutive badge images separated by single spaces must not wrap awkwardly.
  • Relative image paths resolve to the raw endpoint: ./docs/demo.png → /raw/:repo/:ref/docs/demo.png. Same for relative links → blob URLs. This is mandatory; broken relative images are a failing grade.
  • <img>/<picture>/<details>/<summary>/<kbd>/<sup>/<sub>/align attributes: allowed. Sanitize with a strict allowlist (DOMPurify-style via sanitize-html): no scripts, no event handlers, no iframes (except a curated allowlist: YouTube embeds off by default).
• HTML in Markdown (centered headers, badge tables — the classic GitHub README style) must render correctly.
• Emoji shortcodes (:rocket: → 🚀).
• Look for README.md case-insensitively, then readme.rst/README.txt fallbacks (plain render).
• Cache the rendered HTML per (repo, sha, theme-agnostic).

Typography of rendered Markdown mirrors GitHub's .markdown-body: 16px base, 1.6 line-height, bordered tables with zebra rows, blockquote left-border in muted accent, code chips with surface background, hr as 1px border.

# 6. spbgit CLI — Terminal Command Center

A standalone Node CLI (cli/spbgit.mjs, exposed as bin: { "spbgit": ... }, installable via npm i -g from the repo or npm link). Zero heavy deps — use commander (or hand-rolled parser), picocolors for output, native fetch.

# 6.1 Configuration

~/.spbgit/config.json:

{
  "server": "https://git.spboucher.ai",
  "token": "<PAT>",
  "workspace": "~/code",
  "author": { "name": "Simon-Pierre Boucher", "email": "contact@spboucher.ai" }
}

• spbgit init — interactive setup wizard (server URL, token paste, workspace dir); sets git config user.name/email globally if missing; chmod 600 the config.
• Token is never printed back, never logged, never in argv.

# 6.2 Commands (full spec)

# 6.3 CLI UX rules

• Colorized, aligned output; respects NO_COLOR and --json everywhere.
• Exit codes: 0 ok, 1 user error, 2 network/auth, 3 partial failure in --all operations.
• All multi-repo operations run with a concurrency limit of 4 and stream per-repo progress lines.
• Helpful errors: on 401 → "Token invalid or revoked. Run spbgit token new then spbgit init."

# 7. JSON API (/api/v1)

Public reads, token-gated writes (Authorization: Bearer <PAT>).

• GET /api/v1/repos · GET /api/v1/repos/:name · GET /api/v1/repos/:name/languages · GET /api/v1/repos/:name/commits?ref&page
• POST /api/v1/repos · PATCH /api/v1/repos/:name · DELETE /api/v1/repos/:name (auth)
• POST /api/v1/tokens · GET /api/v1/tokens · DELETE /api/v1/tokens/:id (auth; creation of the first token happens server-side via deploy/setup script printing a bootstrap token once)
• GET /api/v1/stats — totals for the home hero.
• Rate limit public endpoints (200 req/min/IP, @fastify/rate-limit), sane JSON error envelope { "error": { "code", "message" } }.

# 8. Deployment — node m3u96a + ngrok + git.spboucher.ai

# 8.1 deploy/setup-m3u96a.sh (idempotent)

1. Install Node 20 (via nvm or distro), git, ngrok.
2. Create dirs: /srv/git, /srv/spbgit/{data,cache}, correct ownership.
3. Clone/pull this repo to /srv/spbgit/app, npm ci --omit=dev.
4. Generate bootstrap PAT, print it once to stdout.
5. Install pm2 config (or systemd unit) and start.

# 8.2 ngrok (deploy/ngrok.yml)

version: 3
agent:
  authtoken: ${NGROK_AUTHTOKEN}
endpoints:
  - name: spbgit
    url: https://git.spboucher.ai
    upstream:
      url: http://127.0.0.1:7420

• Document the DNS step: CNAME git.spboucher.ai → the ngrok-provided edge target, plus domain registration in the ngrok dashboard.
• ngrok provides TLS termination; the app still sets trustProxy: true and derives client IPs from x-forwarded-for for rate limiting.

# 8.3 Process management (deploy/ecosystem.config.cjs)

• Two pm2 apps: spbgit-server (node src/server.mjs) and spbgit-tunnel (ngrok start --config deploy/ngrok.yml spbgit), both autorestart: true, max_restarts sane, logs to /srv/spbgit/logs/.
• pm2 save + pm2 startup documented so everything survives reboot of m3u96a.
• Provide the systemd unit as the documented alternative.

# 8.4 Backups & ops

• deploy/backup.sh — nightly cron: tar.zst of /srv/git + data/ into /srv/spbgit/backups/, keep 14, log result.
• GET /healthz (uptime, repo count, cache size) for monitoring; pm2 healthcheck hits it.
• Structured logs (pino), request logging with latency, log rotation.

# 9. Security Checklist (verify each before "done")

• Path traversal impossible in repo names, tree paths, raw endpoint (normalize + verify prefix).
• Push requires valid PAT; tokens argon2-hashed at rest; constant-time compare.
• Rendered Markdown sanitized (no script/style/iframe/event-handlers) while keeping badges, <details>, alignment HTML working.
• Raw endpoint serves with Content-Type sniffing disabled (X-Content-Type-Options: nosniff) and correct types; HTML files served as text/plain from /raw to prevent stored-XSS-via-repo.
• CSP header on web UI (self + data: images + shields.io/img allowlist for remote images in READMEs — use a relaxed img-src * since READMEs embed arbitrary badges, but everything else locked down).
• Localhost-only guard on /internal/* hook routes.
• No secrets in code, logs, or error messages. .env + zod-validated config.

# 10. Quality Bar & Definition of Done

Engineering standards: ESM, small modules, JSDoc on exported functions, vitest coverage on the git plumbing (tree/log/blame parsing) and an end-to-end test that spins the server, creates a repo via API, pushes via real git CLI, and asserts the web UI + API reflect it. npm run lint (eslint) + npm run check:headers both green.

The platform is DONE when every box below is checked:

• bash deploy/setup-m3u96a.sh on a fresh m3u96a gets the whole stack live at https://git.spboucher.ai and survives a reboot.
• git clone https://git.spboucher.ai/anything.git works for a stranger with no auth; pushing without a PAT is rejected with 401.
• spbgit init → spbgit create demo --push → repo instantly visible on the home page with correct language stats.
• spbgit sync walks every workspace repo and prints an accurate summary table.
• A README containing a badge row, a centered HTML header, a mermaid diagram, a task list, relative images, and code blocks renders flawlessly in dark and light theme.
• Repo pages have working file browser, blob view with line anchors, commits, single-commit diff, blame, branches, tags, ZIP download.
• Home page shows pinned repos, activity feed, and the contribution heatmap.
• Every generated file in the codebase carries the Simon-Pierre Boucher / contact@spboucher.ai header (npm run check:headers passes).
• OG image cards, sitemap, Atom feed, custom 404 — all present.
• Lighthouse ≥ 95 / 95 on home and a repo page.

# 11. Build Order (follow this sequence)

1. Skeleton: config, Fastify bootstrap, logging, healthz, header scripts.
2. Git core: bare-repo model + Smart HTTP (clone/push round-trip test passes) + hooks + PAT auth.
3. API v1 + meta.json model.
4. CLI (init → create → push → sync working end-to-end against local server).
5. Web UI: design tokens → layout → home → repo page → README pipeline (badges!) → blob/commits/diff/blame → search/stats/heatmap.
6. Polish: OG images, feeds, error pages, a11y pass, Lighthouse.
7. Deploy: scripts, ngrok, pm2, backups; go live on m3u96a; run the full DoD checklist.

Work in small commits with conventional-commit messages (feat:, fix:, chore:). At the end of each phase, state which DoD boxes are now satisfied.