1# webui2
2
3New web interface for git-bug. Built with Vite + React + TypeScript + Tailwind + shadcn/ui.
4
5## Quickstart
6
7You need two processes running:
8
9```bash
10# 1. Go backend (from repo root)
11go run . webui --no-open --port 3000
12
13# 2. Vite dev server (from this directory)
14npm install
15npm run dev
16```
17
18Open http://localhost:5173. Vite proxies `/graphql`, `/api`, and `/auth` to the Go server on port 3000.
19
20Node 22 is required. If you use asdf, `.tool-versions` pins the right version automatically.
21
22## Routes
23
24| Path | Page |
25|-------------------------|----------------------------------------------------------|
26| `/` | Repo picker — auto-redirects when there is only one repo |
27| `/_` | Default repo (issues + code browser) |
28| `/_/issues` | Issue list with search and label filtering |
29| `/_/issues/new` | New issue form |
30| `/_/issues/:id` | Issue detail and timeline |
31| `/_/user/:id` | User profile |
32| `/_/commit/:hash` | Commit detail with collapsible file diffs |
33| `/auth/select-identity` | OAuth identity adoption (first-time login) |
34
35`_` is the URL segment for the default (unnamed) repository. Named repositories use their registered name.
36
37## Code structure
38
39```
40src/
41├── pages/ # One file per route
42├── components/
43│ ├── bugs/ # Issue components (BugRow, Timeline, ...)
44│ ├── code/ # Code browser (FileTree, FileViewer, ...)
45│ ├── content/ # Markdown renderer
46│ ├── layout/ # Header + Shell
47│ └── ui/ # shadcn/ui — never edit manually
48│ # Update with: npx shadcn update <component>
49├── graphql/ # .graphql source files — edit these, then run codegen
50├── __generated__/ # Generated typed hooks — do not edit
51└── lib/ # apollo.ts, auth.tsx, theme.tsx, gitApi.ts, repo.tsx, utils.ts
52```
53
54## Data flow
55
56**Bug tracking** uses GraphQL (`/graphql`). Queries and mutations are defined in `src/graphql/*.graphql` and codegen produces typed React hooks into `src/__generated__/graphql.ts`. After changing any `.graphql` file run:
57
58```bash
59npm run codegen
60```
61
62**Code browser** uses REST endpoints at `/api/repos/{owner}/{repo}/git/*` implemented in `api/http/git_browse_handler.go`. `_` is used for both owner and repo (local single-user setup). The TypeScript client is `src/lib/gitApi.ts`.
63
64| Endpoint | Description |
65|---------------------------------------|-----------------------------------------|
66| `GET /git/refs` | List branches and tags |
67| `GET /git/trees/{ref}?path=` | Directory listing with last-commit info |
68| `GET /git/blobs/{ref}?path=` | File content |
69| `GET /git/raw/{ref}/{path}` | Raw file download |
70| `GET /git/commits?ref=&limit=&after=` | Paginated commit log |
71| `GET /git/commits/{sha}` | Commit metadata + changed file list |
72| `GET /git/commits/{sha}/diff?path=` | Per-file structured diff (lazy-loaded) |
73
74## Auth
75
76Three modes, configured at server start:
77
78- **`local`** — single user derived from git config; all writes enabled, no login UI.
79- **`oauth`** — multi-user via external providers; all API endpoints require a valid session; unauthenticated requests get 401.
80- **`readonly`** — no identity; all write actions hidden in the UI.
81
82`AuthContext` (`src/lib/auth.tsx`) fetches `serverConfig` + `userIdentity` on load and exposes `{ user, mode, oauthProviders }` to the whole tree.
83
84## Build for production
85
86The Go binary embeds the compiled frontend via `//go:embed all:dist` in `webui2/handler.go`. The Makefile `build-webui2` target runs the Vite build before compiling Go:
87
88```bash
89# From repo root
90make build
91```
92
93Or manually:
94
95```bash
96npm run build # outputs to webui2/dist/
97cd .. && go build . # embeds dist/ into the binary
98```
99
100## Theming
101
102`ThemeProvider` (`src/lib/theme.tsx`) toggles the `dark` class on `<html>`. CSS variables for both modes are defined in `src/index.css`. shadcn/ui components pick them up automatically.