gitxp 0.0.1

package/README.md

@@ -0,0 +1,325 @@
+# gitxp
+
+An alternative GitHub UI that runs on your own machine. `npx gitxp` starts a
+local server, authenticates through the GitHub CLI you already have set up, and
+opens the app in your browser. There is no account to create and no OAuth app to
+register.
+
+The goal is an interface that feels like Linear rather than a website: the UI
+reads from a local store and never blocks on a network round trip, and syncing
+with GitHub happens in the background.
+
+The long-term scope is the daily GitHub workflow: browsing repos, issues and
+pull requests, reviewing code, discussions and comments, watching CI, and
+merging. v0 is narrower, see Roadmap.
+
+## Requirements
+
+- Node 22.13 or newer, because the local store uses the built-in `node:sqlite`
+  module
+- The [GitHub CLI](https://cli.github.com), authenticated with `gh auth login`
+
+## Usage
+
+```bash
+npx gitxp
+```
+
+Options:
+
+- `--port <number>` use a specific port instead of a random free one
+- `--no-open` start the server without opening a browser
+
+## How it works
+
+```
+npx gitxp
+   |
+   +-- bin/gitxp.js       checks `gh auth status`, picks a free port,
+   |                      sets HOST=127.0.0.1, boots the built server
+   |
+   +-- .output/server     TanStack Start server functions talk to the
+   |                      GitHub API using the token from `gh auth token`
+   |
+   +-- browser            React app that reads and writes a local
+                          collection, synced against GitHub in the background
+```
+
+The build output is a self-contained Node server produced by Nitro. It imports
+nothing but `node:` builtins, so the published package has no runtime
+dependencies.
+
+## Roadmap
+
+v0 is a complete review loop: a notifications inbox, the pull requests waiting
+on you, the pull request itself with its diff and CI status, and submitting a
+review with inline comments, approval or changes requested, and merging.
+
+Build order, risky parts first, each step runnable on its own:
+
+1. SQLite store, migration runner, the two zones
+2. API client: token from `gh`, ETags, rate limit accounting
+3. Notifications sync loop, one resource proven end to end
+4. SSE and the client mirror, so a background write reaches the UI
+5. Inbox UI: list, preview pane, command palette, row actions
+6. Mutation queue, proven on mark-as-done
+7. Review inbox as the second resource
+8. Pull request detail: `@pierre/diffs`, existing review comments, CI status
+9. Review submission: inline comments, approve, request changes, merge
+
+After v0, in rough order: issues, repo and file browsing, discussions.
+
+Out of v0 on purpose: search, projects, Actions logs, wikis, gists, org and team
+views.
+
+None of it is built yet. What is in `src/` today is the project scaffold.
+
+## Interface
+
+Three columns: a sidebar of views, the list, and a preview pane. Triage happens
+without leaving the list. A pull request diff breaks out of that layout and
+takes the full width.
+
+Keyboard first. Cmd+K opens a command palette covering everything, and single
+letters act on the focused row. The palette is also where an action lives before
+it earns a shortcut, so nothing ends up reachable only by mouse.
+
+The visual layer stays on stock shadcn for now. It is the one choice here that
+is cheap to revisit, because retuning spacing and type tokens later does not
+touch component structure or focus handling.
+
+Cached rows render immediately, with a thin indicator while a background refresh
+runs. Skeletons appear only where data is genuinely absent. Applied everywhere,
+that rule is most of what separates this from a website.
+
+## Local sync layer
+
+The UI reads from a SQLite database at `~/.gitxp/`, written by the server
+process. It uses the built-in `node:sqlite` module, so it adds no dependency and
+the published package stays free of them. One server process means one writer,
+sync keeps running while no tab is open, and the cache survives clearing browser
+data.
+
+### What gets synced
+
+GitHub is too large to mirror, so the store has a boundary:
+
+- Synced in the background: your notifications, pull requests waiting on your
+  review, and the repos you explicitly follow in gitxp.
+- Fetched on demand and cached afterwards: file trees, blobs, older comment
+  threads, CI logs, anything you reach by navigating rather than by triage.
+
+Anything outside the synced set is a cache miss on first view. The UI should
+show it arriving rather than pretending it was already local.
+
+### Schema
+
+Each entity keeps GitHub's JSON payload as-is in a `raw` column, alongside
+extracted columns for the fields queries filter and sort on. Scope grows toward
+all of GitHub, and keeping the payload whole means adding a view does not need a
+migration for every field that view happens to read.
+
+Rows are keyed by GitHub's GraphQL `node_id`. REST and GraphQL return different
+identifiers for the same object and REST payloads carry `node_id` too, so keying
+on it means a row written by a bulk GraphQL pull and a row written by a REST
+poll are the same row.
+
+Notification threads are the exception. The REST notifications endpoint returns
+no `node_id`, only a string thread `id`, so `notifications` is keyed on that.
+
+The store has two zones. Everything cached from GitHub is disposable, can be
+dropped and resynced, and therefore makes most schema changes free. The mutation
+queue and your settings cannot be rederived from GitHub, so they live in tables
+migrations have to preserve. That split is what makes a reset-cache command safe
+to offer. Migrations run off SQLite's `user_version`.
+
+### Scheduling
+
+Each resource is its own job with its own interval, ETag and backoff, rather
+than one loop polling everything. Checks on a pull request you are looking at
+want seconds, followed repos want minutes, and whatever is on screen gets a
+priority lane.
+
+`node:sqlite` is synchronous, so a large write batch stalls HTTP responses in
+the same process. Keep batches small and measure. If the UI stutters, the sync
+loop moves to a worker thread.
+
+### The client mirror
+
+React runs in the browser and cannot read that SQLite file, so every row the UI
+renders is copied into browser memory first. That copy is a TanStack DB
+collection holding the slice the current view needs.
+
+Holding a collection, rather than calling a server function per view, is what
+allows filtering, sorting and joining to happen in the browser with no round
+trip. It is why an inbox filter can feel instant. Only the bounded triage set is
+mirrored this way; everything fetched on demand stays in the plain TanStack
+Query cache.
+
+The server pushes over Server-Sent Events at `/api/events`, as a plain
+`ReadableStream` response. A sync that writes rows emits a change signal naming
+the resource, and the client refetches that collection through its server
+function, applying the result inside TanStack DB's `begin`, `truncate`, `write`
+and `commit` calls. Mutations travel the other way as ordinary server function
+calls, so the stream stays one-directional.
+
+The stream carries a signal rather than the changed rows. On localhost the
+refetch costs a sub-millisecond round trip and reuses the same query path as the
+initial load, which is worth more than the saved bytes. Streaming rows, and
+per-subset subscriptions through `loadSubset` and `unloadSubset`, are the
+refinement if a collection ever grows past what a full refetch can carry.
+
+```
+GitHub --poll--> sync loop --write--> SQLite (~/.gitxp)
+                                         |
+                                  change signal
+                                         |
+                            SSE stream at /api/events
+                                         |
+                           client refetches that collection
+                                         |
+                    SyncConfig: begin / truncate / write / commit
+                                         |
+                              client collection --> React
+```
+
+### Writes
+
+Mutations are queued in the same database and applied in order, so a write
+survives a page reload. They fall into two classes:
+
+- Optimistic: comments, labels, review submissions, marking a notification
+  done. The local store updates immediately and rolls back if the request fails.
+- Confirmed: merging, closing, anything awkward to undo or that branch
+  protection and required checks can reject. The UI waits for GitHub and shows
+  the request in flight.
+
+A queued write can fail long after you navigated away, so failed actions need a
+persistent surface with retry rather than a toast that disappears.
+
+A review in progress stays local until you submit it. Inline comments accumulate
+in the queue and reach GitHub as one request that creates the review with its
+comments, which keeps drafting instant and makes submission atomic.
+
+### Staying inside the rate limit
+
+The limit is 5000 requests an hour on REST and on GraphQL, and 30 a minute on
+search, so search is not used for syncing.
+
+- Background polling uses conditional requests. A 304 does not count against the
+  REST limit.
+- The notifications endpoint returns an `X-Poll-Interval` header saying how
+  often GitHub wants to be polled. Respect it instead of picking an interval.
+- GraphQL is for composite reads where one query replaces several REST calls,
+  such as a pull request with its reviews and checks.
+- CI status is the hungriest part, because check runs change often. Poll it only
+  for a pull request currently on screen, never globally.
+
+## Reviewing pull requests
+
+Rendering is [`@pierre/diffs`](https://diffs.com) rather than a hand-built
+viewer. It is Apache-2.0, built on Shiki, does stacked and split layouts, and
+ships an annotation framework meant for review comments and CI annotations. File
+trees come from [`@pierre/trees`](https://trees.software).
+
+`@pierre/trees` is at `1.0.0-beta.6` and depends on a Preact 11 beta, so a
+Preact beta ends up bundled next to React 19. Worth watching, and worth pinning
+the version.
+
+The data still comes from the REST pull request files endpoint, because GitHub
+has already computed the patch hunks. That endpoint omits the patch for binary
+files and for files over its size limit, so those need a fallback rather than an
+empty view.
+
+The preview pane is narrow, so it shows a stacked diff. Split view is available
+at full width.
+
+Review comments anchor to a path, a line and a side, mapped onto the annotation
+framework. Comments whose line no longer exists in the current diff are
+outdated, and the UI has to show them rather than drop them.
+
+Long lists outside the diff still need virtualizing. `@tanstack/react-virtual`
+is the fit, and is not installed yet because nothing imports it.
+
+## Security
+
+The server holds a real GitHub token, so it is only ever reachable from the
+machine it runs on. `bin/gitxp.js` sets `HOST=127.0.0.1`, because the Nitro
+default binds every interface.
+
+The token comes from `gh auth token` and stays on the server side. Server
+functions read it and the browser never receives it. It is re-read on a 401
+rather than cached for the life of the process, and the host comes from
+`gh auth status`, so an enterprise host works without extra configuration.
+
+Server functions reject requests whose `Origin` header is not the app itself.
+Any page open in your browser can reach `127.0.0.1`, and that is the realistic
+attacker. This is not built yet, and needs to exist before the server starts
+holding a token.
+
+A local process can read the port and send no `Origin` at all. Defending against
+that would need a secret generated at boot and carried in the URL. That is not
+planned.
+
+## Development
+
+```bash
+npm install
+npm run dev          # vite dev server on port 3000
+npm run build        # produces .output/
+npm start            # runs bin/gitxp.js against .output, same path as npx
+npm run lint
+npm run typecheck
+npm run format
+```
+
+`npm run lint` does not typecheck. `npm run typecheck` catches what it misses,
+including unsound casts on SQLite rows.
+
+Modules under `src/server` import with explicit `.ts` extensions and stay inside
+the TypeScript syntax Node can strip, so they run directly without the bundler:
+
+```bash
+GITXP_HOME=/tmp/gitxp-scratch node some-script.ts
+```
+
+## Publishing
+
+`prepublishOnly` runs the build, and the `files` field ships `.output` and
+`bin`. Everything else is a build-time concern and lives in `devDependencies`.
+
+`dependencies` is empty on purpose. npm installs a package's dependencies when
+you run it through npx, so anything listed there is downloaded by every user.
+Nitro already inlines the framework into `.output`, which is about 1.4 MB
+against a 278 MB development tree.
+
+Check what would be published before releasing:
+
+```bash
+npm pack --dry-run
+```
+
+## Project layout
+
+```
+bin/gitxp.js        CLI entry point, boots the built server
+src/server/db/      SQLite store, migrations, per-resource sync state
+src/server/github/  gh token, API client with ETags and rate limit accounting
+src/server/sync/    per-resource sync jobs, scheduler, change emitter
+src/functions/      server functions, the boundary the client calls
+src/db-collections/ client collections mirroring the local database
+src/routes/         file-based routes (TanStack Router)
+src/components/ui/  shadcn components, all of them
+src/integrations/   TanStack Query setup
+.output/            build output, generated
+```
+
+## Built with
+
+[TanStack Start](https://tanstack.com/start) with Nitro, TanStack Router,
+Query, DB, Table and Form, Tailwind, and shadcn/ui. Diffs and file trees come
+from [`@pierre/diffs`](https://diffs.com) and
+[`@pierre/trees`](https://trees.software).
+
+Every shadcn component is installed under `src/components/ui`. The full list is
+in `AGENTS.md`.

package/bin/gitxp.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { createServer } from 'node:net'
+import { fileURLToPath } from 'node:url'
+
+const serverEntry = new URL('../.output/server/index.mjs', import.meta.url)
+
+if (!existsSync(fileURLToPath(serverEntry))) {
+  console.error('Build output is missing. Run `npm run build` first.')
+  process.exit(1)
+}
+
+try {
+  execFileSync('gh', ['auth', 'status'], { stdio: 'ignore' })
+} catch (error) {
+  console.error(
+    error.code === 'ENOENT'
+      ? 'gitxp needs the GitHub CLI. Install it from https://cli.github.com, then run `gh auth login`.'
+      : 'gitxp needs an authenticated GitHub CLI. Run `gh auth login`.',
+  )
+  process.exit(1)
+}
+
+const args = process.argv.slice(2)
+const portFlag = args.indexOf('--port')
+const requestedPort = portFlag === -1 ? null : Number(args[portFlag + 1])
+
+if (requestedPort !== null && !Number.isInteger(requestedPort)) {
+  console.error('--port needs a number, for example `gitxp --port 4000`.')
+  process.exit(1)
+}
+
+const port = requestedPort ?? (await findFreePort())
+const url = `http://127.0.0.1:${port}`
+
+process.env.HOST = '127.0.0.1'
+process.env.PORT = String(port)
+
+await import(serverEntry.href)
+await waitUntilReady(url)
+
+console.log(`gitxp is running at ${url}`)
+
+if (!args.includes('--no-open')) {
+  openBrowser(url)
+}
+
+function findFreePort() {
+  return new Promise((resolve, reject) => {
+    const probe = createServer()
+    probe.on('error', reject)
+    probe.listen(0, '127.0.0.1', () => {
+      const { port } = probe.address()
+      probe.close(() => resolve(port))
+    })
+  })
+}
+
+async function waitUntilReady(target) {
+  for (let attempt = 0; attempt < 100; attempt++) {
+    try {
+      await fetch(target, { method: 'HEAD' })
+      return
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, 50))
+    }
+  }
+  throw new Error(`Server did not start at ${target}`)
+}
+
+function openBrowser(target) {
+  const [command, commandArgs] =
+    process.platform === 'darwin'
+      ? ['open', [target]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', target]]
+        : ['xdg-open', [target]]
+
+  try {
+    execFileSync(command, commandArgs, { stdio: 'ignore' })
+  } catch {
+    console.error(`Could not open a browser. Open ${target} manually.`)
+  }
+}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "gitxp",
+  "version": "0.0.1",
+  "description": "An alternative GitHub UI that runs locally on top of the GitHub CLI",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "gitxp": "bin/gitxp.js"
+  },
+  "files": [
+    ".output",
+    "bin"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "imports": {
+    "#/*": "./src/*"
+  },
+  "scripts": {
+    "dev": "vite dev --port 3000",
+    "generate-routes": "tsr generate",
+    "build": "vite build",
+    "start": "node bin/gitxp.js",
+    "preview": "vite preview",
+    "lint": "eslint",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write . && eslint --fix",
+    "check": "prettier --check .",
+    "prepublishOnly": "vite build"
+  },
+  "devDependencies": {
+    "@base-ui/react": "^1.7.0",
+    "@hookform/resolvers": "^5.9.1",
+    "@pierre/diffs": "^1.3.6",
+    "@pierre/trees": "^1.0.0-beta.6",
+    "@shadcn/react": "^0.3.0",
+    "@tailwindcss/typography": "^0.5.16",
+    "@tailwindcss/vite": "^4.1.18",
+    "@tanstack/devtools-vite": "latest",
+    "@tanstack/eslint-config": "latest",
+    "@tanstack/match-sorter-utils": "latest",
+    "@tanstack/query-db-collection": "latest",
+    "@tanstack/react-db": "latest",
+    "@tanstack/react-devtools": "latest",
+    "@tanstack/react-form": "latest",
+    "@tanstack/react-query": "latest",
+    "@tanstack/react-query-devtools": "latest",
+    "@tanstack/react-router": "latest",
+    "@tanstack/react-router-devtools": "latest",
+    "@tanstack/react-router-ssr-query": "latest",
+    "@tanstack/react-start": "latest",
+    "@tanstack/react-table": "latest",
+    "@tanstack/router-cli": "^1.132.0",
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "date-fns": "^4.4.0",
+    "embla-carousel-react": "^8.6.0",
+    "eslint": "^9.20.0",
+    "input-otp": "^1.5.0",
+    "lucide-react": "^0.577.0",
+    "next-themes": "^0.4.6",
+    "nitro": "3.0.260610-beta",
+    "prettier": "^3.8.1",
+    "radix-ui": "^1.6.7",
+    "react": "^19.2.0",
+    "react-day-picker": "^10.0.1",
+    "react-dom": "^19.2.0",
+    "react-hook-form": "^7.87.0",
+    "react-resizable-panels": "^4.12.3",
+    "recharts": "^3.8.0",
+    "sonner": "^2.0.8",
+    "tailwind-merge": "^3.0.2",
+    "tailwindcss": "^4.1.18",
+    "tw-animate-css": "^1.3.6",
+    "typescript": "^6.0.2",
+    "vaul": "^1.1.2",
+    "vite": "^8.0.0",
+    "zod": "^4.3.6"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "lightningcss"
+    ]
+  }
+}