megit-app 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). While the
+version is below 1.0.0, the config file format (`~/.config/megit/config.json`), the CLI
+surface, and the HTTP API may change in any minor release.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-28
+
+First public release.
+
+### Graph
+
+- Commit graph with per-branch lanes and colours, greedy top-down lane assignment, and reserved leftmost lanes so WIP and stash connectors get straight runs into HEAD
+- The checked-out branch's path is drawn thicker and highlighted
+- Merge edges bulge around the lanes they cross rather than cutting through them
+- Commits page in 200 at a time, loading more on demand
+- Stash entries render as their own rows, dot-connected to the commit they were taken from
+- Sticky WIP row at the top of the list whenever the worktree is dirty
+- Resizable ref / graph / message columns, with widths persisted
+- Gravatar avatars with initials fallback
+
+### Diffs
+
+- Unified and split (side-by-side) views
+- Syntax highlighting and word-level intra-line highlighting
+- Collapsed context expandable a hunk at a time
+- Per-file "Viewed" checkbox
+- Merge commits diff against their first parent
+- Images diff visually instead of as binary noise
+- Untracked files diff via `git diff --no-index`
+
+### Search
+
+- <kbd>⌘F</kbd> find bar filtering the loaded rows as you type, matching commit message, author name, email, hash prefix, or ref name — no request, and immune to going stale across a background refresh
+- <kbd>Enter</kbd> / <kbd>Shift+Enter</kbd> step through matches, wrapping at both ends
+- Full-history search on demand: three `git log` passes (message, author, hash) unioned into one date-ordered list, capped at 500 results, with the query treated as a literal so a typed `(` or `.` is not a regex
+- A match below the loaded window pulls the graph down to it
+
+### Working tree
+
+- Stage, unstage, and discard individual files
+- Commit message composer with staged / unstaged sections and counts
+- Amend the last commit's message
+- Non-ASCII paths handled correctly (`core.quotePath=false`, NUL-delimited output)
+
+### Git operations
+
+- Toolbar: pull (fast-forward only), push, create branch, stash all, pop latest stash, undo last commit (soft reset)
+- Ref chips: checkout, create branch here, rename, delete, set upstream, merge, rebase, delete tag, copy name, copy GitHub link
+- Commit rows: checkout, cherry-pick, revert, reset (soft / mixed / hard), copy hash, copy GitHub link
+- Checkout auto-stashes a dirty worktree first
+- Destructive actions are marked, and hidden where they would be meaningless
+
+### Shell
+
+- Full PTY terminal (xterm.js + node-pty) opened in the active repository, lazy-loaded so it costs nothing until used
+- Sessions survive panel hides and tab switches, with a replay buffer on reattach
+
+### App
+
+- Multiple repositories in draggable tabs
+- Light and dark themes
+- Auto-refresh: the server watches each open repo (`fs.watch`, filtered and debounced) and pushes updates over SSE
+- Keyboard navigation through rows, plus shortcuts for refresh, terminal, theme, and commit
+- Toast notifications for errors
+
+### Security
+
+- Server binds `127.0.0.1` only
+- `Host` header pinned to loopback names, closing DNS-rebinding access
+- WebSocket `Origin` checked before handing out a PTY
+- Repositories are only reachable once registered in `~/.config/megit/config.json`
+- Client-supplied revs whitelisted rather than escaped, so a leading-dash rev cannot smuggle in a git option
+- Git invocations cannot block on credential prompts
+
+### Platforms
+
+- macOS (arm64, x64): full support, and the only platform verified by hand
+- Windows (arm64, x64): builds and runs, but untested on real hardware — recursive `fs.watch` crashes the test worker there, so auto-refresh is not covered by CI
+- Linux: everything except the terminal — `node-pty` is an `optionalDependency` with no Linux prebuild, and the terminal button is hidden when it is unavailable
+
+[Unreleased]: https://github.com/vuongvu1/megit/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/vuongvu1/megit/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hoang Vuong Vu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# <img src="public/logo.svg" width="28"/> megit
+
+A git repository viewer that runs in your browser. Commit graph with real branch lanes, diffs including your uncommitted work, stashes, staging, search, and a shell — pointed at as many local repos as you like, each in its own tab.
+
+It writes, too: stage/unstage/discard, commit and amend, branch and tag create/delete, stash push/pop/drop, checkout (with auto-stash when the worktree is dirty), plus revert, reset, cherry-pick, merge, rebase, pull and push.
+
+Nothing leaves your machine: the server binds `127.0.0.1`, shells out to your own `git`, and has no account, telemetry, or network dependency beyond optional Gravatar avatars.
+
+![megit — commit graph with branch lanes, stash rows and the sticky WIP row](docs/graph-dark.png)
+
+## Install
+
+Requires Node ≥ 24.
+
+```bash
+npx megit-app              # reopen your last session
+```
+
+Installed globally (`npm i -g megit-app`), the command is just `megit`.
+
+`PORT` picks the port (default 3411). The server opens your browser at it.
+
+## Features
+
+### Commit graph with lanes
+
+Branches get their own colour and lane. The checked-out branch's path is drawn thicker so you can follow it at a glance, and merges bulge around the lanes they cross instead of cutting through them. Commits page in 200 at a time and load more on demand, so opening a repository never waits on the full history.
+
+Ref chips sit in their own resizable column to the left — local branches, remotes, and tags — and the graph column and message column can be dragged to whatever widths suit the repo.
+
+### Light and dark themes
+
+Toggle with the switch in the toolbar or <kbd>⌘</kbd><kbd>⇧</kbd><kbd>0</kbd>. The choice persists.
+
+![megit in the light theme](docs/graph-light.png)
+
+### Uncommitted work is part of the graph
+
+A sticky WIP row sits at the top of the list whenever the worktree is dirty, connected into HEAD like any other node. Click it to stage, unstage, or discard individual files, write a message, and commit — staged and unstaged changes are separate collapsible sections with counts.
+
+![the WIP row expanded into staged and unstaged sections with a commit composer](docs/wip-staging.png)
+
+Stashes appear as their own rows, attached to the commit they were taken from with a dotted connector, and can be popped, deleted, or retitled in place.
+
+### Diffs
+
+Click a commit to see its changed files, then a file to see the diff. Syntax highlighting, word-level intra-line highlighting, collapsed context you can expand a hunk at a time, and a per-file "Viewed" checkbox.
+
+**Unified:**
+
+![unified diff with an expandable hunk gap](docs/diff-unified.png)
+
+**Split**, side by side:
+
+![split diff with word-level highlighting](docs/diff-side-by-side.png)
+
+Merge commits diff against their first parent. Images diff visually rather than as binary noise. Untracked files diff too, via `git diff --no-index`.
+
+### Commit detail
+
+Author and committer are shown separately when they differ — including the dates, which is the bit most tools hide. The changed-file list toggles between a flat path list and a directory tree.
+
+![commit detail panel showing author, committer and changed files](docs/commit-detail.png)
+
+### Search
+
+<kbd>⌘</kbd><kbd>F</kbd> opens a find bar that filters the rows already loaded, as you type — matching commit message, author name, email, hash prefix, or ref name. That costs no request and can't go stale when the graph refreshes underneath you. <kbd>↵</kbd> and <kbd>⇧</kbd><kbd>↵</kbd> walk the matches, wrapping at the ends the way a find bar should.
+
+If what you want is further back than the rows you've loaded, the globe button re-runs the same query as a full-history `git log` search. Because git ANDs its commit-limiting options, "message OR author OR hash" is three searches unioned into one date-ordered list, capped at 500 results — the counter shows `12 of 340 · all`, with a `+` when the cap truncated it. A match below the loaded window pulls the graph down to it.
+
+### A real shell, in the repo
+
+<kbd>⌘</kbd><kbd>J</kbd> opens a full PTY already `cd`'d into the active repository — your shell, your prompt, your aliases. It survives panel hides and tab switches, and <kbd>⌘</kbd><kbd>K</kbd> clears it. xterm.js is lazy-loaded, so it costs nothing until you open it.
+
+![terminal panel open below the graph, running git log](docs/terminal.png)
+
+### Git operations
+
+megit started as a viewer, but the common operations are here:
+
+- **Toolbar** — pull (fast-forward only), push, create branch, stash all, pop latest stash, undo last commit (soft reset, keeps changes staged)
+- **Ref chips** — checkout, create branch here, rename, delete, set upstream, merge, rebase, delete tag, copy name, copy GitHub link
+- **Commit rows** — checkout, cherry-pick, revert, reset (soft / mixed / hard), copy hash, copy GitHub link
+- **Files** — stage, unstage, discard, amend the last commit's message
+
+Checkout auto-stashes a dirty worktree first. Destructive items are marked as such and are hidden where they'd be meaningless.
+
+### Auto-refresh
+
+The server watches each open repository (`fs.watch`, filtered and debounced) and pushes changes to the browser over SSE. Commit in your terminal and the graph updates within about a second. <kbd>r</kbd> forces a refresh if you want one.
+
+### Keyboard
+
+| Key                                                      | Action                             |
+| -------------------------------------------------------- | ---------------------------------- |
+| <kbd>↑</kbd> <kbd>↓</kbd> <kbd>Home</kbd> <kbd>End</kbd> | move through rows                  |
+| <kbd>⌘</kbd><kbd>F</kbd>                                 | search commits                     |
+| <kbd>↵</kbd> / <kbd>⇧</kbd><kbd>↵</kbd>                  | next / previous match              |
+| <kbd>r</kbd>                                             | refresh                            |
+| <kbd>⌘</kbd><kbd>J</kbd>                                 | toggle terminal                    |
+| <kbd>⌘</kbd><kbd>K</kbd>                                 | clear terminal                     |
+| <kbd>⌘</kbd><kbd>⇧</kbd><kbd>0</kbd>                     | toggle theme                       |
+| <kbd>⌘</kbd><kbd>↵</kbd>                                 | commit                             |
+| <kbd>Esc</kbd>                                           | close search or menu / cancel edit |
+
+## Platform support
+
+| Platform             | Status                                    |
+| -------------------- | ----------------------------------------- |
+| macOS (arm64, x64)   | full                                      |
+| Windows (arm64, x64) | untested on real hardware; auto-refresh unverified |
+| Linux                | everything except the built-in terminal   |
+
+The terminal needs [node-pty](https://github.com/microsoft/node-pty), which ships prebuilt binaries for macOS and Windows only. It is an `optionalDependency`: on Linux the install either compiles it from source (needs python3 and a C++ toolchain) or skips it, and megit hides the terminal button. Nothing else is affected.
+
+On Windows, the watcher integration tests crash the test worker outright, so they are skipped there and auto-refresh is not exercised by CI. Everything else in the suite runs. If you use megit on Windows, please report whether the graph updates on its own after a commit — that is the part we cannot currently verify.
+
+## Configuration
+
+The list of open repositories lives in `~/.config/megit/config.json`. Repositories are only reachable through the API if they are registered there, so pointing megit at a repo is always an explicit act.
+
+## Development
+
+Requires pnpm.
+
+```bash
+pnpm install
+pnpm dev        # Express API on :4500 + Vite dev server on :4000
+```
+
+Production build:
+
+```bash
+pnpm build          # vite → dist/
+pnpm build:server   # tsc → dist-server/  (only needed for publishing)
+pnpm start          # serves dist/ + API on http://127.0.0.1:4500
+```
+
+Ports come from `PORT` (API, default 3411) and `UI_PORT` (Vite dev server, default 5173); the dev/start scripts pin 4500/4000.
+
+In development the server runs its TypeScript directly via Node's native type-stripping — no build step. That does not work for a published package, because Node refuses to strip types under `node_modules`, so `pnpm build:server` compiles `server/` to `dist-server/` at publish time.
+
+`scripts/make-test-repo.sh` generates `test-repo/` — a throwaway fixture with interleaved branches, merges, stashes and a dirty worktree, used for manual testing and for the screenshots above.
+
+[`docs/architecture.md`](docs/architecture.md) explains how the two halves fit together and why the graph layout lives in a pure module. [CONTRIBUTING.md](CONTRIBUTING.md) has the setup and the house rules; [SECURITY.md](SECURITY.md) has the threat model.
+
+```bash
+pnpm test           # vitest — parsers, lane layout, watcher, menus
+npx tsc --noEmit    # typecheck
+```
+
+## License
+
+MIT

package/bin/megit.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// megit CLI — start the local server, open the browser at it, and register the
+// repo path given as an argument (if any) by POSTing to our own /api/repos, so
+// path validation stays in one place.
+import { execFile } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { resolve } from 'node:path'
+
+const arg = process.argv[2]
+
+// handled before importing the server, so --help never binds a port
+if (arg === '-h' || arg === '--help') {
+  console.log(`megit — git repository viewer in the browser
+
+Usage:
+  megit [repo-path]
+
+Arguments:
+  repo-path        open this repository in a tab (default: reopen last session)
+
+Options:
+  -h, --help       show this message
+  -v, --version    print the version
+
+Environment:
+  PORT             port to listen on (default 3411)`)
+  process.exit(0)
+}
+
+if (arg === '-v' || arg === '--version') {
+  console.log(createRequire(import.meta.url)('../package.json').version)
+  process.exit(0)
+}
+
+const port = Number(process.env.PORT) || 3411
+const url = `http://127.0.0.1:${port}`
+
+const { server } = await import('../dist-server/index.js')
+if (!server.listening) await new Promise(r => server.once('listening', r))
+
+if (arg) {
+  await fetch(`${url}/api/repos`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ path: resolve(arg) }),
+  })
+    .then(async r => { if (!r.ok) console.error(`megit: ${(await r.json()).error}`) })
+    .catch(() => {})
+}
+
+// ponytail: no `open` dependency — three platform names cover what it does.
+const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer' : 'xdg-open'
+execFile(opener, [url], () => {}) // exit code ignored: explorer.exe returns 1 on success
+console.log(`megit → ${url}`)