lightjj: Instructions file for Claude Code

lightjj

Browser-based UI for Jujutsu (jj) version control. See docs/ARCHITECTURE.md for system design, docs/FILES.md for the detailed per-file guide, BACKLOG.md for planned features.

Build & Test

go test ./...                                        # Go tests
go vet ./...                                         # static analysis
cd frontend && pnpm install && pnpm run build        # build frontend
cd frontend && pnpm check                            # svelte-check type-check (not run by vite build or vitest — run it before shipping)
cd frontend && pnpm run bench                        # diff perf benchmarks (see docs/design-notes/diff-perf-benchmarks.md)
go build -tags embed ./cmd/lightjj                   # build binary (needs frontend build first; no tag = stub)

# Dev mode: two terminals
# 1: go run ./cmd/lightjj --addr localhost:3000 --no-browser
# 2: cd frontend && pnpm run dev
# Vite proxies /api/* to localhost:3000

Project Structure

One line per file; routine *_test.go / *.test.ts files are omitted (they sit alongside their subjects), shared test infrastructure is listed. Detailed per-file notes and invariants live in docs/FILES.md — read a file's entry there before modifying the file or adding a new caller of its exports; update the entry (plus the one-liner here) when adding, removing, or renaming a file or when its contract changes.

cmd/lightjj/main.go       — CLI entry point, flag parsing, embeds frontend-dist/
cmd/lightjj/frontend_embed.go — go:embed frontend-dist/ handler (-tags embed)
cmd/lightjj/frontend_stub.go — No-embed fallback: static "frontend not bundled" help page
cmd/lightjj/session_file.go — Agent port-discovery session files ($XDG_RUNTIME_DIR/lightjj/sessions/<pid>.json)
cmd/lightjj/session_file_unix.go — verifyOwner uid check on the session dir (unix)
cmd/lightjj/session_file_other.go — verifyOwner no-op stub (non-unix)
cmd/lightjj/api_cmd.go    — lightjj api / lightjj sessions subcommands: loopback HTTP client for agent harnesses
cmd/lightjj/skill_cmd.go  — lightjj skill [install]: prints/installs embedded SKILL.md agent guide
cmd/lightjj/apply_hunks.go — --apply-hunks re-entry for `jj split --tool lightjj-hunks` (writes hunk spec into $right)
internal/
  jj/                     — Command builders + data models (PURE — no I/O, no side effects)
    commands.go            — Functions that return []string args for jj subcommands
    commit.go              — Commit model (ChangePrefix/CommitPrefix, Immutable, Divergent, WorkingCopies, …)
    bookmark.go            — Bookmark model + output parsers
    alias.go               — jj config alias parser
    file_change.go         — FileChange model, FilesTemplate, ParseFilesTemplate
    file_list.go           — TreeFile model + FileListJSON/FileList(pre-json fallback)/ResolveCommitId builders + parsers (full tree at a revision)
    divergence.go          — DivergenceEntry, Divergence() template builder, ParseDivergence
    selected_revisions.go  — Multi-revision selection helper
    version.go             — Semver type + named jj feature gates + FeatureGates wire registry (→ /api/info features)
    workspace_store.go     — Protobuf parser for .jj/repo/workspace_store/index (<0.40 fallback)
  runner/                  — CommandRunner interface + implementations
    runner.go              — Interface (Run, RunWithInput, RunForMutation, StreamCombined, RunRaw, WriteFile)
    local.go               — LocalRunner: exec("jj", args); WriteFile symlink-escape hardening; resolve rejects forgotten workspaces
    ssh.go                 — SSHRunner: wraps jj args in an ssh command
  api/                     — HTTP handlers
    server.go              — Route registration (route lines ARE the pure-mutation handlers), runMutation, op-id cache (getOpId/setOpId/casOpId), helpers
    handlers.go            — Endpoint implementations, generic mutation[Req] factory, flag validation
    watcher.go             — Op-id watcher: fsnotify + SSE push (local), sshPollLoop (SSH), typed sseEvent broadcasts, shared probeTracker, stale-WC detection
    tabs.go                — TabManager: per-tab Server + Watcher mounted at /tab/{id}/
    config.go              — Server-side JSONC config (hujson); mergeAndWriteConfig single write path for human-edited keys
    config_jsonc.go        — hujson helpers: standardizeJSONC, unmarshalJSONC, patchConfigKeys, removeConfigKeys
    config_template.go     — First-run JSONC template constant
    state.go               — Machine-state store (state.json, plain JSON): openTabs + recentActions, GET/POST /api/state/recent-actions, legacy-key migration
    jsonstore.go           — jsonCollection[T]: generic keyed flat-file JSON store (mutex, merge-on-upsert, stamping, cascade delete, batch) + atomicWriteFile primitive
    annotations.go         — Per-changeId review comments: Annotation type + store config + GET/POST/DELETE handlers
    doc_comments.go        — Doc-mode range-anchored comments: DocComment types + store config + GET/POST/DELETE/batch handlers
    agent_docs.go          — GET /api/agent serves embedded agent_api.md (doc/route drift guard test)
    symbol.go              — rg-backed go-to-definition (GET /api/symbol) via RunRaw rg --json
    focus.go               — GET/POST /api/focus: frontend view-state report for agent steering
    file_tree.go           — GET /api/file-tree (+/search): per-commit LRU index of one `jj file list` run (in-flight dedup, caps) → dir children + ranked path search
    open.go                — Open-in-$EDITOR ({file}/{line} substitution, detached process)
    open_unix.go           — detachProcess via Setsid (!windows)
    open_windows.go        — detachProcess no-op (windows)
    gzip.go                — Gzip response middleware (Flush passthrough for SSE)
    hostgate.go            — HostPolicy: Host-header gate middleware + originAllowed() Origin gate, one allow-list (loopback + --allowed-host)
  parser/                  — Graph log parser
    graph.go               — Parses jj log graph output with _PREFIX: markers into GraphRow[] (Hidden = self.hidden() marker OR `◌` glyph)
testutil/                  — Go test infrastructure
  mock_runner.go           — MockRunner with Expect(args)/Verify() pattern
frontend/                  — Svelte 5 SPA (Vite + TypeScript + pnpm)
  src/testutil/            — mock-api.ts (vi.mock netStubs + builders), wait-for.ts (frame/predicate waits), node-ambient.d.ts (minimal node:fs/node:path typings for svelte-check — not @types/node)
  src/App.interactions.test.ts — In-process keyboard-gate tests
  src/main.ts              — Vite entry point: mounts AppShell, imports theme.css
  src/vite-env.d.ts        — `/// <reference types="vite/client" />` so side-effect `.css` imports type-check
  src/AppShell.svelte      — Tab-switch host ({#key activeTabId} remount + state snapshot); owns per-repo workspace info + the tab/workspace ContextMenu
  src/App.svelte           — Main app shell: layout, keyboard routing, state, revset filter bar
  src/lib/
    api.ts                 — Typed API client, op-id tracking, commit_id-keyed LRU cache, SSE auto-refresh
    RevisionGraph.svelte   — Revision list + graph gutter; always windowed via createWindower
    virtual.svelte.ts      — createWindower() fixed-row virtualization + holdViewport()
    GraphSvg.svelte        — SVG renderer for graph gutter characters
    DiffPanel.svelte       — Diff viewer: unified/split, collapse/defer, search, hunk/annotation nav
    file-actions.svelte.ts — createFileActions(): per-file edit/preview/merge/quick-resolve state + actions (DiffPanel's mutation cluster)
    diff-cache.ts          — App-lifetime caches: derived highlights, parsed diffs, collapse state
    SearchResults.svelte   — Diff search match jump-list dropdown (capped render, snippet windowing)
    ReviewJumpList.svelte  — Annotation jump-list dropdown over navAnnotations (SearchResults sibling, parent-owned cursor)
    FileSelectionPanel.svelte — Squash/split/review file checkbox panel
    hunk-apply.ts          — PURE — hunk selection model + forward-apply accepted hunks (spec for apply_hunks.go)
    RevisionHeader.svelte  — Header slot: change_id, description, badges, Describe/Divergence/Edit-parents buttons
    DiffFileView.svelte    — Per-file diff: collapse, context expansion, conflict badges, Alt+click annotate, binary-image → ImageDiff
    ImageDiff.svelte       — Binary-image diff body: side-by-side panes (split) or swipe-compare slider (unified); pure presentational, parent re-keys on src change
    SymbolHover.svelte     — Go-to-definition hover card (signature + doc context, click → open in $EDITOR)
    symbol-hover.svelte.ts — createSymbolHover() hover controller (span dedup, exit grace, gen-guarded fetch)
    FileEditor.svelte      — CodeMirror 6 wrapper for inline editing
    MergePanel.svelte      — 3-pane conflict editor (ours | result | theirs)
    merge-surgery.ts       — PURE — line-range position model: planTake/planTakeBoth/remapBlock/normalizeBlocks surgery
    merge-tracker.ts       — Center block tracker: CM StateField + whole-array undo snapshots + take/takeAll transaction specs (MergePanel's state half)
    cm-shared.ts           — CM6 helpers: detectIndent, getCmLanguage, cmTheme, cmHighlight (tok-* classes — theme-following syntax)
    conflict-markers.ts    — PURE — shared conflict-marker scanner (escalation-aware width discovery, exact-width matching)
    conflict-extract.ts    — reconstructSides(): jj conflict markers → {base, ours, theirs, blocks}
    conflict-resolve.ts    — PURE — resolveConflictFile(): single @/non-@/SSH conflict-resolution strategy (both surfaces)
    merge-diff.ts          — ChangeBlock/LineDiff types; diffBlocks() LCS is test-only
    ConflictQueue.svelte   — Merge-view left rail: conflicted files grouped by commit
    merge-controller.svelte.ts — createMergeController(): merge-view queue/sides/save orchestration (shared gen)
    DocView.svelte         — Doc-mode ProseMirror editor (View|Edit)
    DocCommentRail.svelte  — Doc-mode comment rail (PlacedReview threads → CommentCard)
    review.ts              — Unified read-model over Annotation + DocComment (Review/PlacedReview + reviewed-marker predicate)
    review-mutations.svelte.ts — createReviewMutations(): shared optimistic-mutation policy for both review stores
    CommentCard.svelte     — Pure presentational comment card
    comment-visibility.svelte.ts — createCommentVisibility() per-App comment visibility store
    doc-session.svelte.ts  — createDocSession(): PM ↔ file two-tier model; comments = PlacedReview projection
    pm-schema.ts           — ProseMirror Schema + parseMarkdown/serializeMarkdown
    pm-mermaid.ts          — Mermaid code_block NodeView
    reanchor.ts            — Content-addressed anchor capture/refind
    FileHistoryPanel.svelte — Two-cursor file history overlay
    FileHistoryRail.svelte — Reusable file-history revision rail (two-tier mutable→full loading)
    FileComparePicker.svelte — Compare a file against another revision (FileHistoryRail + diffRange)
    FileTreePanel.svelte   — Full-tree-at-revision overlay (F / "Files"): lazy tree + server-search filter + read-only highlighted viewer
    file-tree.ts           — PURE — FileTreePanel view model: flattenTree, changeMarks, ancestorDirs, contentKind/contentLines, visiblePath
    SplitToggle.svelte     — ◫/≡ split/unified button (glyph + a11y strings); parent owns the boolean
    DescriptionEditor.svelte — Inline commit message editor
    CommandPalette.svelte  — Fuzzy-search command palette (Cmd+K) with submenus
    ContextMenu.svelte     — Reusable right-click context menu
    StatusBar.svelte       — Bottom status bar with mode indicators and shortcuts
    MessageBar.svelte      — Single user-facing message surface (error/warning/success)
    TabBar.svelte          — Tab strip: repoRoot-grouped (chip + --graph-N notch), stale dots, ✕ close, + open, ◇N workspace icon; emits onWorkspaceIcon/onTabMenu (AppShell hosts the menu)
    BookmarkModal.svelte   — Bookmark modal (move/advance/delete/forget/track)
    BookmarksPanel.svelte  — Branches view: bookmark list (sortable Priority/Recent/Name, author shown + filterable)
    bookmark-sync.ts       — classifyBookmark() → 8 sync states + sort/format helpers + canCreatePR/prCompareUrl (Create PR)
    workspace-recovery.ts  — PURE — planRecoverAll()/recoverAllMessage() for "Update all (recover stale)"
    tab-groups.ts          — PURE — groupTabs()/tabGroupKey()/colorFor() + LAUNCH_TAB_ID/isClosableTab(): tab→repo grouping + the one closability predicate, shared by TabBar + AppShell + App palette
    workspace-menu.ts      — PURE — workspaceSectionItems()/tabMenuItems(): builds the tab `◇N`/right-click menu items (AppShell injects callbacks)
    remote-visibility.ts   — buildVisibilityRevset(): per-remote visibility → revset string
    url-intent.ts          — PURE — routable-URL grammar (?change=/&revset=/&path=): parse/strip, changeLink(), ref→row unique-prefix match, widen-once locatorRevset (never all())
    themes.ts              — 7 builtin themes + lazy Ghostty palettes + deriveTheme()
    jj-features.svelte.ts  — jj feature labels; booleans come from /api/info features (optimistic until loaded)
    confirm-gate.svelte.ts — createConfirmGate() double-press confirm factory
    drag-resize.ts         — resizeFromDelta() (pure) + startResizeDrag(): delta-based divider drags (rendered start size ± pointer delta)
    list-cursor.svelte.ts  — createListCursor() keyboard-list cursor factory (nav/hover/clamp/scroll)
    BookmarkPicker.svelte  — Shared autocomplete bookmark-picker modal (BookmarkInput/DestinationInput wrap it)
    BookmarkInput.svelte   — Bookmark name input with autocomplete (BookmarkPicker wrapper)
    DestinationInput.svelte — Destination picker (/) for inline rebase/squash (BookmarkPicker wrapper, raw revset pass-through)
    ConfigModal.svelte     — Cmd+K → "Edit config" CodeMirror JSON editor
    GitModal.svelte        — Git push/fetch modal
    EvologPanel.svelte     — Evolution log with inline per-entry diffs
    OplogPanel.svelte      — Operation log panel
    DivergencePanel.svelte — Stack-aware divergence resolution UI
    divergence.ts          — classify() + buildKeepPlan() + refined-kind taxonomy (see docs/jj-divergence.md)
    divergence-strategy.ts — recommend(): ranked resolution strategies
    divergence-actions.ts  — executeKeepPlan/splitIdentity/squashDivergent/abandonMutable (api-calling execution)
    divergence.fixtures.ts — Shared DivergenceEntry/DivergenceGroup test builders
    diff-parser.ts         — Unified diff parser
    context-expand.ts      — PURE — expandGaps() merges revealed context gaps
    conflict-parser.ts     — Diff-side adapter over conflict-markers.ts → ConflictRegion[] for DiffFileView
    split-view.ts          — Side-by-side diff alignment
    word-diff.ts           — Word-level inline diff computation
    perf-fixtures.ts       — Synthetic diff generators for diff-compute.bench.ts (`pnpm run bench`)
    languages.ts           — SINGLE language registry (one LANGUAGES entry per language)
    lang-zig.ts            — Zig StreamLanguage tokenizer (legacy simple-mode, lazy-loaded)
    highlighter.ts         — Lezer highlightCode → tok-* spans + escapeHtml/escapeAttr
    markdown-render.ts     — marked (GFM) + DOMPurify renderMarkdown + gutter block stamping
    mermaid.ts             — beautiful-mermaid lazy-load + render
    panzoom.ts             — wireSvg() wheel-zoom/drag-pan/dblclick-reset
    excalidraw-render.ts   — PURE — .excalidraw JSON → SVG string
    ExcalidrawPreview.svelte — .excalidraw preview (lazy chunk)
    MarkdownPreview.svelte — .md preview toggle with annotation gutter
    fuzzy.ts               — Fuzzy string matching
    group-by.ts            — groupByWithIndex utility
    paths.ts               — basename()/dirname() display helpers (jump-list dropdowns)
    time-format.ts         — relativeTime() compact ages + firstLine()
    scroll-into-view.ts    — scrollIdxIntoView() data-idx row scroll helper
    loader.svelte.ts       — createLoader() async factory with generation counter
    op-sync.svelte.ts      — createOpSync(): op-id-driven auto-refresh policy for repo-scoped loaders
    revision-navigator.svelte.ts — createRevisionNavigator(): diff/files/description load orchestration
    diff-derivation.svelte.ts — createDiffDerivation() per-file progressive computation
    keyboard-gate.ts       — PURE — routeKeydown() gate-priority router
    modes.svelte.ts        — Rebase/squash/split/megamerge mode state factories (ModeBase: kind/sources/diffFollows/hasDestination/destinationIds)
    slide.ts               — computeSlide(): Shift+J/K single-step reorder along linear graph segments
    config.svelte.ts       — Reactive config singleton (server config + localStorage cache)
    recent-actions.svelte.ts — State-backed (state.json) last-used timestamps for bookmark recency sort
    annotations.svelte.ts  — Per-line review comment store (server-backed, agent workflows; PlacedReview projection)
    AnnotationBubble.svelte — Annotation create/edit popup
    WelcomeModal.svelte    — "What's new" modal on version bump
    tutorial-content.ts    — Feature announcements keyed by version
    version.ts             — APP_VERSION constant
  vite.config.ts           — Dev proxy + build output to ../cmd/lightjj/frontend-dist/