0002 — Forgejo salvage plan

What to take from ~/references/forgejo for quarry, what to rework, and how. Companion to 0001-quarry-forge.md (which records the verdict this document executes: parts and map, not chassis). Informal working document.

0. Ground rules — the three modes of "take"

Forgejo's top-level LICENSE is GPLv3: post-fork code is GPL, Gitea-inherited code is MIT. Every item below is tagged with its mode:

• [COPY] — lift code. Only from files whose lineage is MIT (exists in go-gitea/gitea upstream predating the fork) OR where we accept the GPL consequence for quarry. Default: take the Gitea upstream version of the file, not the forgejo one, and record it in a third_party/PROVENANCE.md ledger (path, source repo, commit, license). No exceptions to the ledger.
• [DEP] — import as a library. Verify the module's own license first (gof3 ships separately from forgejo proper; check before v2).
• [MAP] — read for structure, reimplement fresh. Layouts, route taxonomy, UX decisions, empty-state wording. No code crosses; no license question.

Rework baseline: quarry keeps Go html/template so [MAP] items port with their shapes intact, renders server-side, and uses Datastar for progressive JS (0001 Principles 2–3: server-owned state, views usable without JS, live features degrade to load-time state + refresh). We do NOT adopt forgejo's Vue layer — they are mid-migration (jQuery-era + Vue + a start on htmx) and the Vue components drag a build chain quarry doesn't want; any framework exception beyond Datastar is made explicitly per 0001 Principle 2, never by porting convenience.

1. The page inventory — what quarry v1/v2/v3 replicates

Route-by-route map from templates/ and routers/web/. "Rework" states the zit-semantic change, not cosmetics.

v1 — read plane

Forgejo source	Quarry page	Mode	Rework
templates/explore/repos.tmpl, repo_list.tmpl, navbar.tmpl	Fleet page (all repos, activity, search)	[MAP]	Data from quarry's derived indexes, not an authoritative DB; add cross-repo timeline (forgejo has none — this is our addition, fossil reasons 15-18).
templates/repo/home.tmpl, header.tmpl, clone_buttons.tmpl, clone_script.tmpl	Repo home / file browser	[MAP]	Clone box emits zit clone URL (quarry /r/<repo> fronting). No fork/PR buttons. Branch dropdown reads repostate branches (multiple-same-name branches are legal in zit — dropdown must disambiguate by tip hash, forgejo assumes unique names).
templates/repo/commits.tmpl, commits_list.tmpl, commit_page.tmpl, commit_header.tmpl	Timeline + check-in page	[MAP]	Check-in page shows tags/control-artifact history (amend overrides displayed with provenance — zit shows both original and override; forgejo has no concept). Timestamp links use #60 resolution.
templates/repo/graph.tmpl, graph/* + web_src/js/features/repo-graph.js	DAG graph view	COPY, MAP	Feed it plink-equivalent rows from the index. Their renderer draws git DAGs; zit DAGs are the same shape. Verify lineage (predates fork — likely MIT).
templates/repo/diff/section_split.tmpl, section_unified.tmpl, blob_excerpt.tmpl, whitespace_dropdown.tmpl, options_dropdown.tmpl	Diff views (split/unified, expandable context)	[MAP] with structure kept close	Driven by zit's own diff output, not git's. Drop: comment forms, review machinery (that's v2 forum-anchored, different model). Keep: the expand-context UX (blob_excerpt), whitespace toggles.
templates/repo/diff/image_diff.tmpl + web_src/js/features/imagediff.js	Image diff (swipe/onion-skin)	[COPY]	Self-contained, excellent, rarely reimplemented well. Lineage check.
templates/repo/diff/csv_diff.tmpl + modules/csv	CSV diff	[COPY]	Small, agnostic.
templates/repo/blame.tmpl	Annotate view	[MAP]	zit annotate output; forgejo's chunk-coloring layout is the good part.
templates/repo/wiki/view.tmpl, pages.tmpl, revision.tmpl	Wiki render + history	[MAP]	Backing store inverts: forgejo wiki = a side git repo; quarry wiki = wiki artifacts with P-chain history. revision.tmpl's history-list layout maps 1:1 onto the artifact chain. new/edit deferred to v2.
templates/repo/search.tmpl, templates/explore/code.tmpl	Search (FTS)	[MAP]	SQLite FTS5 behind it; keep their filter chrome.
templates/repo/activity.tmpl, code_frequency.tmpl, contributors.tmpl	Activity/stats pages	[MAP]	Computed in the SQL index (they compute in-process); charts can wait, tables first.
templates/user/heatmap.tmpl + web_src/js/components/ActivityHeatmap.vue	Activity heatmap	[MAP] — server-rendered SVG	~150 lines server-side, no build chain, works without JS (0001 Principles 2–3). The Vue component is reference only.
templates/status/*, templates/base/*	Error pages, base layout, alerts	[MAP]	Base layout skeleton (head/nav/footer blocks) worth mirroring for the classes/structure; quarry ships its own CSS (see §3).

v2 — write plane

Forgejo source	Quarry page	Mode	Rework
Issue list/detail templates (under templates/repo/issue/)	Tickets list/detail	[MAP] layout only	The storage inverts completely: forgejo issues are DB rows; quarry tickets are ticket artifacts (J-card field history). The list page (filters, labels, sort) and detail page (event timeline) layouts transfer; every data access reworks to index queries + artifact minting via the lease holder. Labels: zit has no label concept — map to ticket fields, render forgejo-style chips.
templates/repo/diff/comment_form.tmpl, conversation.tmpl	Forum threads / check-in discussion	[MAP]	Conversations anchor to artifacts (forum posts with I/P/G refs), not to diff line rows. Line-anchored review is explicitly OUT (fossil-model discussion, not GitHub-model review) — this is the biggest deliberate divergence; record it in the UI as "discuss this check-in" not "review".
templates/user/auth/*, templates/user/settings/*	Login, settings	[MAP]	Auth stack is NOT taken (§2). Screens only.
templates/org/*	Org/team pages	[MAP], mostly SKIP	v1 is single-org; take the member-list layouts when needed.
Wiki new.tmpl/editor	Wiki editing	[MAP]	Editor posts to artifact-minting endpoint; CodeMirror from their web_src/css/codemirror setup is [COPY]-able if we want in-browser editing sugar.

v3 — CI + fleet ops

Forgejo source	Quarry page	Mode	Rework
templates/repo/actions/*, web_src/js/components/ActionRunStatus.vue, ActionJobStep*.vue	dagnats run views	[MAP]	Their run/step/log UI is the right shape; rebuild server-rendered + Datastar SSE (live steps stream in; without JS the page shows state-at-load and refresh works — 0001 Principle 3). The Vue components are reference only. routers/web/events (SSE plumbing) is worth [MAP]-reading for the endpoint shape. Runner protocol NOT taken (dagnats is the engine).
templates/repo/commit_status.tmpl, commit_statuses.tmpl	Status badges on timeline	[MAP]	Verdict source = tag artifacts + live dagnats state.
templates/admin/*	Fleet admin	[MAP]	Registry/leases/ingest health — mostly quarry-specific content in their layout skeleton.

2. Code salvage list (beyond page-linked items above)

Take:

• modules/markup/ — the crown jewel: markdown/ (goldmark assembly: callouts, math, link resolution hooks), common/, console/ (ANSI rendering), asciicast/, file_preview.go, mdstripper/. [COPY, lineage-check per file]. Exception: the sanitizer is a cleanroom reimplementation, not a copy from either lineage. Forgejo and Gitea have diverged on XSS fixes since the fork, so "take the MIT upstream version" can mean shipping holes the other lineage already closed, and cherry-picking across a GPL/MIT boundary is exactly the provenance mess the ledger exists to prevent. Strategy: write quarry's bluemonday policy fresh; treat the union of both projects' sanitizer test vectors as a conformance corpus (test inputs/expected outputs are data — recorded in the ledger with attribution, no policy code crosses); run the corpus in CI so we pass every XSS edge either lineage has ever caught; watch both projects' security advisories and fold new vectors into the corpus as they publish; add a fuzz target over the policy from day one. Rework: their link resolution resolves git refs/issues (#123, !45, commit SHAs) — replace the resolver hooks with zit resolution (artifact hashes, ticket ids via HashTokenKind, [[wiki]] interwiki per fossil convention).
• modules/highlight/highlight.go — thin chroma wrapper with sane fallbacks, plus web_src/css/chroma/ themes. [COPY].
• modules/avatar/ — identicon generation + processing. [COPY].
• modules/charset/ — UTF-8 detection/BOM handling for rendering unknown files. [COPY].
• modules/emoji/ — shortcode table. [COPY].
• web_src/js/features/clipboard.js, repo-diff.js (expand-context wiring) — small vanilla features. [COPY, trim].
• code.forgejo.org/f3/gof3 — F3 interchange. [DEP, license-verify]. The quarry F3 importer (forgejo/gitea/github issues→ticket artifacts, comments→forum artifacts, wiki→wiki artifacts) is the migration weapon; v2.

Explicitly do not take:

• models/ + XORM + models/migrations/ (600+; the authoritative-DB architecture itself) — quarry's derived indexes + tiny litestream'd OLTP replace it.
• services/ layer and routers/ handlers — coupled to the above.
• Auth stack (services/auth, LDAP/OAuth internals) — entangled with their user model; quarry uses standalone libs when v2 arrives.
• Actions runner + protocol implementation — dagnats.
• Webhooks subsystem — their implementation is entangled with the models layer. Quarry builds its own: webhooks/SSE/websockets are the supported external async surface (0001 Principle 6 — users are never required to speak NATS), implemented as a dispatcher worker on the internal event stream. Their payload shapes are worth [MAP]-reading for ecosystem familiarity; no code crosses.
• modules/git, modules/gitrepo, LFS, githttp — git.
• modules/activitypub, forgefed — federation for quarry is zit sync (RFC §future); ForgeFed is git-shaped and drags the models layer.
• The Vue build chain wholesale; jQuery remnants; their ini config system; modules/indexer (bleve/ES adapters — the derived index plane replaces).

3. CSS / design system

[MAP] only. Take the information — spacing scale, the diff color semantics (add/del/context in both themes), muted-vs-emphasis text hierarchy — and write quarry's own small CSS with native vars + the artifact-design two-theme discipline. Copying base.css (~their whole design system) imports a decade of dead selectors and fights every layout we change. Exception: chroma/ syntax themes [COPY] since they pair with the highlight module.

4. Mechanics — how the salvage actually runs

1. Ledger first. third_party/PROVENANCE.md + a CI check that every file under third_party/ (or carrying a salvage header) has a ledger row with source repo/commit/license. GPL-lineage code gets refused at review unless the row says we accepted it knowingly.
2. Vendor the [COPY] modules as packages, not sprinkles: internal/markup (forgejo markup + our resolver hooks + the cleanroom sanitizer per §2), internal/highlight, internal/avatar, etc. Each lands with its upstream tests ported — for the sanitizer, only the test vectors cross (as the conformance corpus), never the policy code.
3. Resolver inversion is one seam. All git-flavored reference resolution in markup goes through one Resolver interface (hash → link, ticket id → link, wiki name → link, branch@date per #60). Implement once against the index; markup stays upstream-diffable for future re-syncs of their XSS fixes.
4. Templates are rewritten, looking at theirs. Keep their DOM structure and class shapes where the layout is the thing being taken (diff sections, graph container, wiki history) so their JS features port unmodified; everything else is fresh.
5. Per-page definition of done: renders from derived-index data only (passes the 0001 §11 disposability test), no git vocabulary in user-facing strings ("check-in" not "commit" — fossil's term, zit's term), both themes, keyboard focus states, usable with JS disabled (0001 Principle 3), and the page's capability exposed through the API (0001 Principle 5 — shared query/command layer, documented endpoint).
6. Order of extraction (matches quarry v1 build order): markup+highlight +charset first (everything renders through them) → base layout + fleet + repo home/files → timeline + check-in page → diff stack (incl. image/csv) → graph → wiki render → search → activity/stats → chat UI (no forgejo ancestor — fresh, notify Inbox patterns apply) → v2/v3 per §1.

5. What forgejo simply doesn't have (fresh builds, no salvage)

Cross-repo timeline; chat (their closest is nothing — fossil's chat and notify's Inbox are the references); the ingest/index plane; sync fronting; lease routing; the disposability harness; timestamp-resolution links (#60); amend-provenance display; submanifest-aware tree browsing (S-card trees can render lazily per subtree — a wide-repo browsing win forgejo can't express); the #41 replay table as a repo settings page.