megit-app 0.1.0

package/dist-server/parse.js

@@ -0,0 +1,144 @@
+// %B (full message) contains arbitrary newlines, so it must be the last field
+export const META_FORMAT = '%an%x1f%ae%x1f%at%x1f%cn%x1f%ce%x1f%ct%x1f%P%x1f%B';
+export function parseMeta(raw) {
+    const [author, authorEmail, authorDate, committer, committerEmail, commitDate, parents, ...rest] = raw.split('\x1f');
+    return {
+        author,
+        authorEmail,
+        authorDate: Number(authorDate),
+        committer,
+        committerEmail,
+        commitDate: Number(commitDate),
+        parents: parents ? parents.split(' ') : [],
+        message: rest.join('\x1f').replace(/\n+$/, ''),
+    };
+}
+// \x1f field sep, \x1e record sep — never appear in git metadata
+// %ct (committer date), not %at: --date-order sorts by committer date, and stash
+// placement bisects on commit.date — author dates go non-monotonic after rebase/revert
+export const LOG_FORMAT = '%H%x1f%P%x1f%an%x1f%ae%x1f%ct%x1f%D%x1f%s%x1e';
+export function parseLog(raw) {
+    return raw
+        .split('\x1e')
+        .map(r => r.replace(/^\n/, ''))
+        .filter(r => r.length > 0)
+        .map(rec => {
+        const [hash, parents, author, email, date, refs, subject] = rec.split('\x1f');
+        return {
+            hash,
+            parents: parents ? parents.split(' ') : [],
+            author,
+            email,
+            date: Number(date),
+            refs: refs ? refs.split(', ') : [],
+            subject,
+        };
+    });
+}
+// `/api/search` asks git for `%H%x1f%ct` — the hash to select and the date to order by.
+export const parseMatches = (raw) => raw.split('\n').filter(Boolean).map(l => {
+    const [hash, ct] = l.split('\x1f');
+    return [hash, Number(ct)];
+});
+// The graph will not render 14k rows, and a one-word query can match most of a
+// history, so the route reports a bounded slice.
+export const SEARCH_CAP = 500;
+// git ANDs its commit-limiting options, so "message OR author OR hash" costs one
+// `git log` per field and a union here. Date-descending is the ordering the graph's
+// --date-order mostly agrees with.
+//
+// ponytail: ct-desc, not true --date-order — topological tie-breaks can disagree, so
+// "next" may occasionally step one row upward. Exact positions would cost a
+// full-history `--format=%H` pass per query; local search is already exact.
+export function mergeMatches(lists) {
+    const byHash = new Map();
+    for (const list of lists) {
+        for (const [hash, ct] of list)
+            if (!byHash.has(hash))
+                byHash.set(hash, ct);
+    }
+    const sorted = [...byHash].sort((a, b) => b[1] - a[1]).map(([hash]) => hash);
+    return { matches: sorted.slice(0, SEARCH_CAP), truncated: sorted.length > SEARCH_CAP };
+}
+// `stash@{N}` is positional and renumbers on every stash push/drop, so a stash
+// action must map its sha to an index against a list read at action time — an
+// index captured when the graph loaded can address a different stash by now.
+// Exact match: a prefix could collide, and every caller has the full %H.
+export const stashIndex = (raw, hash) => raw.split('\n').filter(Boolean).indexOf(hash);
+// Everything below reads `-z` output: one NUL-terminated record per entry, headers
+// included. Without it git C-quotes any path holding a non-ASCII byte, a tab or a
+// `"` ("\303\274mlaut.txt"), and that literal can't go back to git as a pathspec —
+// staging, discarding and diffing such a file all failed with "did not match any
+// files". `-z` paths are raw, so they survive the round trip.
+const records = (raw) => raw.split('\0');
+// The `# branch.*` headers `git status --porcelain=v2 --branch` prepends to the same
+// output parseStatus already reads — so the toolbar's ahead/behind badges cost no
+// extra git process. git omits branch.upstream and branch.ab when there's no upstream.
+export function parseBranchHeader(raw) {
+    const fields = new Map();
+    for (const r of records(raw)) {
+        if (!r.startsWith('# branch.'))
+            continue;
+        const sp = r.indexOf(' ', 9);
+        if (sp > 0)
+            fields.set(r.slice(9, sp), r.slice(sp + 1));
+    }
+    const head = fields.get('head') ?? null;
+    const ab = fields.get('ab')?.match(/^\+(\d+) -(\d+)$/);
+    return {
+        head: head === '(detached)' ? null : head,
+        upstream: fields.get('upstream') ?? null,
+        ahead: Number(ab?.[1] ?? 0),
+        behind: Number(ab?.[2] ?? 0),
+    };
+}
+export function parseStatus(raw) {
+    const recs = records(raw);
+    const out = [];
+    for (let i = 0; i < recs.length; i++) {
+        const line = recs[i];
+        if (!line)
+            continue;
+        const kind = line[0];
+        const parts = line.split(' ');
+        if (kind === '1') {
+            const xy = parts[1];
+            out.push({ path: parts.slice(8).join(' '), status: xy[1] !== '.' ? xy[1] : xy[0], x: xy[0], y: xy[1] });
+        }
+        else if (kind === '2') {
+            // rename/copy: extra score field, and under -z the original path is its own
+            // record rather than a \t-joined suffix — skip it, nothing here reads it
+            const xy = parts[1];
+            out.push({ path: parts.slice(9).join(' '), status: xy[0] === '.' ? xy[1] : xy[0], x: xy[0], y: xy[1] });
+            i++;
+        }
+        else if (kind === 'u') {
+            // conflicts are neither staged nor unstaged — they sit on the worktree side
+            // until resolved, so they show up under Changes and can't be committed as-is
+            out.push({ path: parts.slice(10).join(' '), status: 'U', x: '.', y: 'U' });
+        }
+        else if (kind === '?') {
+            out.push({ path: line.slice(2), status: '?', x: '.', y: '?' });
+        }
+    }
+    return out;
+}
+// `git diff --name-status -z`: a status record then its path record, except
+// rename/copy, which spends two paths (old, then new — the new one is what the
+// commit's file list shows).
+export function parseNameStatus(raw) {
+    const recs = records(raw);
+    const out = [];
+    for (let i = 0; i < recs.length; i++) {
+        const st = recs[i];
+        if (!st)
+            continue;
+        const paths = st[0] === 'R' || st[0] === 'C' ? 2 : 1;
+        // no path record (truncated output): a status with no file is nothing to show
+        if (!recs[i + paths])
+            break;
+        out.push({ status: st[0], path: recs[i + paths] });
+        i += paths;
+    }
+    return out;
+}

package/dist-server/term.js

@@ -0,0 +1,113 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { WebSocketServer, WebSocket } from 'ws';
+import { loadConfig } from './config.js';
+// node-pty is an optionalDependency: it ships prebuilds for darwin and win32 only,
+// so a Linux install either compiles from source or omits the package entirely.
+// resolve() answers "is it installed?" without executing the native binding — the
+// lazy import in getSession() stays lazy, and /api/config stays cheap.
+export function hasPty() {
+    try {
+        createRequire(import.meta.url).resolve('node-pty');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const MAX_BUFFER = 200 * 1024;
+// keep the last ~cap chars: append chunk, evict oldest whole chunks; returns new size
+export function pushCapped(buf, size, chunk, cap = MAX_BUFFER) {
+    buf.push(chunk);
+    size += chunk.length;
+    while (size > cap && buf.length > 1)
+        size -= buf.shift().length;
+    return size;
+}
+const sessions = new Map();
+async function getSession(repo) {
+    const existing = sessions.get(repo);
+    if (existing)
+        return existing;
+    // dynamic import: the native module never loads until a terminal is actually opened
+    const { spawn } = await import('node-pty');
+    const shell = process.env.SHELL || '/bin/sh';
+    const pty = spawn(shell, ['-l'], {
+        name: 'xterm-256color',
+        cols: 80,
+        rows: 24,
+        cwd: repo,
+        env: process.env,
+    });
+    const s = { pty, buffer: [], size: 0, clients: new Set() };
+    sessions.set(repo, s);
+    pty.onData(d => {
+        s.size = pushCapped(s.buffer, s.size, d);
+        for (const ws of s.clients)
+            ws.send(d);
+    });
+    pty.onExit(() => {
+        sessions.delete(repo);
+        for (const ws of s.clients) {
+            ws.send('\r\n[session ended]\r\n');
+            ws.close();
+        }
+    });
+    return s;
+}
+async function attach(repo, ws) {
+    let s;
+    try {
+        s = await getSession(repo);
+    }
+    catch {
+        // resolve() said the package is there but the native binding failed to load
+        ws.send('\r\n[terminal unavailable: node-pty could not be loaded on this platform]\r\n');
+        ws.close();
+        return;
+    }
+    s.clients.add(ws);
+    if (s.buffer.length)
+        ws.send(s.buffer.join(''));
+    ws.on('message', raw => {
+        let msg;
+        try {
+            msg = JSON.parse(String(raw));
+        }
+        catch {
+            return;
+        }
+        if (msg.t === 'i' && typeof msg.d === 'string')
+            s.pty.write(msg.d);
+        else if (msg.t === 'r' && msg.cols && msg.rows)
+            s.pty.resize(msg.cols, msg.rows);
+        else if (msg.t === 'c') {
+            s.buffer.length = 0;
+            s.size = 0;
+        }
+    });
+    ws.on('close', () => s.clients.delete(ws));
+}
+export function wireTerminal(server) {
+    const wss = new WebSocketServer({ noServer: true });
+    server.on('upgrade', (req, socket, head) => {
+        const url = new URL(req.url ?? '', 'http://localhost');
+        if (url.pathname !== '/api/term') {
+            socket.destroy();
+            return;
+        }
+        // WebSockets bypass CORS and this socket is a shell: only local pages may
+        // connect (no Origin header = non-browser client on this machine, allowed)
+        const origin = req.headers.origin;
+        if (origin && !/^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin)) {
+            socket.destroy();
+            return;
+        }
+        const repo = url.searchParams.get('repo') ?? '';
+        if (!loadConfig().repos.includes(repo) || !existsSync(repo)) {
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, ws => { void attach(repo, ws); });
+    });
+}

package/dist-server/watch.js

@@ -0,0 +1,104 @@
+// Filesystem watching for auto-refresh: which paths matter, and event debouncing.
+import { existsSync, watch } from 'node:fs';
+// dependency/build dirs git will never report on: an install or a bundler watch
+// otherwise pins the debouncer's max-wait cap and refetches the graph every 2 s
+const NOISE = /^(node_modules|dist|build|target|out|coverage|\.next|\.nuxt|\.turbo|\.venv|__pycache__)(\/|$)/;
+// rel is '/'-separated relative to the repo root (fs.watch recursive on macOS).
+// Working-tree paths count — including git-ignored ones; over-notifying is fine
+// because the client refetch is cheap and fingerprint-gated. Exception: NOISE.
+// Inside .git only the ref/index surface counts; objects/lock/log churn is noise.
+export function isRelevant(rel) {
+    if (rel === '.git')
+        return false;
+    if (NOISE.test(rel))
+        return false;
+    if (!rel.startsWith('.git/'))
+        return true;
+    const inner = rel.slice('.git/'.length);
+    return inner === 'HEAD' || inner === 'index' || inner === 'packed-refs' || inner.startsWith('refs/');
+}
+// Trailing debounce with a max-wait cap: quiet bursts flush once after `delay`;
+// sustained churn (long install, big rebase) still flushes every `maxWait`.
+export function createDebouncer(fire, delay = 400, maxWait = 2000) {
+    let trailing = null;
+    let cap = null;
+    const clear = () => {
+        if (trailing)
+            clearTimeout(trailing);
+        if (cap)
+            clearTimeout(cap);
+        trailing = cap = null;
+    };
+    const flush = () => {
+        clear();
+        fire();
+    };
+    return {
+        hit() {
+            if (trailing)
+                clearTimeout(trailing);
+            trailing = setTimeout(flush, delay);
+            if (!cap)
+                cap = setTimeout(flush, maxWait);
+        },
+        dispose: clear,
+    };
+}
+const entries = new Map();
+// test introspection: how many repos have a live watcher entry
+export function activeWatcherCount() {
+    return entries.size;
+}
+// One shared recursive watcher per repo, alive only while subscribed.
+export function subscribe(repo, onChange, onError) {
+    let entry = entries.get(repo);
+    if (!entry) {
+        // fs.watch does not agree across platforms about a path that isn't there:
+        // macOS and Windows reject it, but Linux — where recursive watching is layered
+        // over inotify — hands back a watcher that never fires and never errors. That
+        // silently dead subscription is worse than a failure, because the caller has no
+        // way to find out. Checking here makes the contract identical everywhere:
+        // subscribing to a missing path throws, and registers nothing.
+        if (!existsSync(repo)) {
+            throw Object.assign(new Error(`ENOENT: no such directory, watch '${repo}'`), { code: 'ENOENT' });
+        }
+        const subs = new Set();
+        const debouncer = createDebouncer(() => {
+            for (const s of subs)
+                s.onChange();
+        });
+        const watcher = watch(repo, { recursive: true }, (_event, filename) => {
+            // null filename: platform couldn't tell — refresh conservatively
+            if (filename === null || isRelevant(filename.toString()))
+                debouncer.hit();
+        });
+        const fresh = { watcher, debouncer, subs };
+        watcher.on('error', () => {
+            entries.delete(repo);
+            debouncer.dispose();
+            // The watcher may have failed before it ever started (a path that vanished, or
+            // never existed — Linux reports that here rather than throwing from watch()).
+            // Closing one in that state is not portable, and a throw inside an 'error'
+            // handler is an uncaught exception that takes the server down with it.
+            try {
+                watcher.close();
+            }
+            catch { /* already dead — nothing to release */ }
+            for (const s of [...subs])
+                s.onError();
+            subs.clear();
+        });
+        entries.set(repo, fresh);
+        entry = fresh;
+    }
+    const sub = { onChange, onError };
+    entry.subs.add(sub);
+    return () => {
+        entry.subs.delete(sub);
+        if (entry.subs.size === 0 && entries.get(repo) === entry) {
+            entry.watcher.close();
+            entry.debouncer.dispose();
+            entries.delete(repo);
+        }
+    };
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "megit-app",
+  "version": "0.1.0",
+  "description": "Git repository viewer in the browser: commit graph with branch lanes, diffs, stashes and WIP",
+  "license": "MIT",
+  "author": "Hoang Vuong Vu",
+  "homepage": "https://github.com/vuongvu1/megit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vuongvu1/megit.git"
+  },
+  "bugs": "https://github.com/vuongvu1/megit/issues",
+  "keywords": [
+    "git",
+    "gui",
+    "commit-graph",
+    "diff",
+    "viewer"
+  ],
+  "type": "module",
+  "bin": {
+    "megit": "bin/megit.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "dist-server",
+    "scripts/fix-pty-perms.mjs",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "dev": "PORT=4500 UI_PORT=4000 concurrently -k \"node --watch server/index.ts\" \"vite\"",
+    "build": "vite build",
+    "build:server": "node -e \"fs.rmSync('dist-server',{recursive:true,force:true})\" && tsc -p tsconfig.server.json",
+    "start": "PORT=4500  node server/index.ts",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm test && pnpm build && pnpm build:server",
+    "postinstall": "node scripts/fix-pty-perms.mjs"
+  },
+  "packageManager": "pnpm@11.18.0+sha512.33d83c77da82f49fba836925c6f1b841181ec3132b670639bd012f7075f5c7cf634c5f870147c19aae7478fac01df09d8892e880454896edd23ee9b33757563c",
+  "dependencies": {
+    "express": "^5.2.1",
+    "ws": "^8.21.1"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.1.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@types/ws": "^8.18.1",
+    "@vitejs/plugin-react": "^6.0.4",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^6.0.0",
+    "concurrently": "^10.0.4",
+    "diff2html": "^3.4.56",
+    "highlight.js": "^11.11.1",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "^7.0.2",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10"
+  }
+}

package/scripts/fix-pty-perms.mjs

@@ -0,0 +1,21 @@
+// node-pty ships spawn-helper as a prebuilt binary, and some package managers drop
+// the executable bit when extracting the tarball — the terminal then fails to spawn.
+// Resolve node-pty rather than guessing ./node_modules: under `npx` it is hoisted to
+// the installing project's node_modules, not ours.
+import { chmodSync, readdirSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+try {
+  const require = createRequire(import.meta.url)
+  const prebuilds = join(dirname(require.resolve('node-pty/package.json')), 'prebuilds')
+  for (const platform of readdirSync(prebuilds)) {
+    try {
+      chmodSync(join(prebuilds, platform, 'spawn-helper'), 0o755)
+    } catch {
+      // win32 prebuilds have no spawn-helper; nothing to do
+    }
+  }
+} catch {
+  // node-pty is optional — absent on Linux installs without build tools
+}