@young1lin/dsh-ui-gitworkbench 0.1.0

package/lib/commit-cache.js

@@ -0,0 +1,68 @@
+/**
+ * Bounded store for payloads addressed by a git object name.
+ *
+ * A commit hash names content that cannot change, so a hit stays valid for the
+ * life of the process and there is nothing to invalidate — capacity is the only
+ * reason an entry ever leaves. That is the whole distinction from working-tree
+ * data, which must never be cached because the next keystroke can change it.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/commit-cache
+ */
+/**
+ * Compose a cache key from its parts.
+ *
+ * The separator is a unit separator, which cannot occur in a filesystem path, a
+ * git object name, or a repository-relative filename. No two distinct part
+ * lists can therefore produce the same key.
+ * @param parts - key components, most general first.
+ * @returns the composed key.
+ */
+export function cacheKey(...parts) {
+    return parts.join('\x1f');
+}
+/**
+ * Fixed-capacity map with least-recently-used eviction.
+ *
+ * A Map iterates in insertion order, so re-inserting an entry on every hit
+ * makes insertion order the recency order and the first key the least recently
+ * used one. No timestamps, no separate list.
+ */
+export class CommitPayloadCache {
+    capacity;
+    entries = new Map();
+    /** @param capacity - entries kept resident; the least recently used is dropped past it. */
+    constructor(capacity) {
+        this.capacity = capacity;
+    }
+    /** How many entries are resident. */
+    get size() {
+        return this.entries.size;
+    }
+    /**
+     * Read an entry, marking it most recently used.
+     * @param key - cache key.
+     * @returns the stored payload, or undefined when the key is absent.
+     */
+    get(key) {
+        const hit = this.entries.get(key);
+        if (hit === undefined)
+            return undefined;
+        this.entries.delete(key);
+        this.entries.set(key, hit);
+        return hit;
+    }
+    /**
+     * Store an entry as most recently used, evicting past capacity.
+     * @param key - cache key.
+     * @param value - payload to store, replacing any existing entry for the key.
+     */
+    set(key, value) {
+        this.entries.delete(key);
+        this.entries.set(key, value);
+        if (this.entries.size > this.capacity) {
+            const oldest = this.entries.keys().next();
+            if (!oldest.done)
+                this.entries.delete(oldest.value);
+        }
+    }
+}

package/lib/git-log.js

@@ -0,0 +1,79 @@
+/**
+ * Commit-log records from `git log` / `git show`.
+ *
+ * Subject (`%s`) is the first line; body (`%b`) is everything after the blank
+ * line. Records are delimited by ASCII RS (`%x1e`) so a body may contain
+ * newlines without breaking the parse. Fields inside a record are US (`%x1f`).
+ *
+ * `body` is always a string (empty when the commit has none). RPC payloads
+ * cannot carry `undefined`.
+ */
+/**
+ * Pretty format: RS, hash, when, subject, parents, refs, body.
+ *
+ * `body` stays last because it is the only field that may contain newlines;
+ * anything after it would have to survive them. Parents (`%p`) and refs (`%D`)
+ * are single-line by construction.
+ */
+export const LOG_FORMAT = '%x1e%h%x1f%cr%x1f%s%x1f%p%x1f%D%x1f%b';
+/**
+ * Split `%D` into plain ref names.
+ *
+ * git writes decorations as a comma-joined list where HEAD is an arrow pair
+ * (`HEAD -> main`) and tags carry a `tag: ` prefix. Both are rendered as the
+ * bare name; which kind of ref it is does not change what the row shows.
+ * @param decoration - the `%D` field, possibly empty.
+ */
+function parseRefs(decoration) {
+    const out = [];
+    for (const raw of decoration.split(',')) {
+        let name = raw.trim();
+        if (name.length === 0)
+            continue;
+        // `HEAD -> main` names the branch HEAD is on; keep the branch.
+        const arrow = name.indexOf('->');
+        if (arrow !== -1)
+            name = name.slice(arrow + 2).trim();
+        if (name.startsWith('tag:'))
+            name = name.slice(4).trim();
+        // A remote's HEAD is a symbolic ref: it always points where that remote's
+        // default branch already points, so it is a second label for a commit that
+        // is guaranteed to carry the first. In a log row it is pure noise.
+        if (name === 'origin/HEAD' || name.endsWith('/HEAD'))
+            continue;
+        if (name.length > 0)
+            out.push(name);
+    }
+    return out;
+}
+/**
+ * Parse a `LOG_FORMAT` stream into commits.
+ * @param stdout - git's stdout.
+ */
+export function parseLog(stdout) {
+    const out = [];
+    for (const record of stdout.split('\x1e')) {
+        if (record.length === 0)
+            continue;
+        const parts = record.split('\x1f');
+        if (parts.length < 3)
+            continue;
+        const hash = parts[0].trim();
+        const when = parts[1] ?? '';
+        const subject = (parts[2] ?? '').replace(/\n+$/g, '');
+        const parents = (parts[3] ?? '').trim().split(/\s+/).filter(part => part.length > 0);
+        const refs = parseRefs(parts[4] ?? '');
+        const body = (parts[5] ?? '').replace(/^\n+/, '').replace(/\n+$/g, '');
+        if (hash.length > 0)
+            out.push({ hash, subject, when, body, parents, refs });
+    }
+    return out;
+}
+/**
+ * The text a "copy message" action puts on the clipboard: subject, then a
+ * blank line, then the body when there is one.
+ * @param commit - parsed commit.
+ */
+export function commitMessageText(commit) {
+    return commit.body.length > 0 ? `${commit.subject}\n\n${commit.body}` : commit.subject;
+}

package/lib/git-ops.js

@@ -0,0 +1,409 @@
+/**
+ * Argument vectors and output readers for the drawer's WRITE operations —
+ * stage, unstage, commit, fetch, pull, push.
+ *
+ * Everything here is a pure function over strings, kept apart from the RPC
+ * methods in `index.ts` so the interesting half can be tested without spawning
+ * git. What matters about `git push` is the argv it is handed and what the
+ * plugin concludes from the exit code; the spawn between them has no branches.
+ *
+ * Two rules hold throughout, because both failures are silent:
+ *
+ *   - Every pathspec goes after `--`, and is checked for a leading dash on top
+ *     of that. A file may legitimately be named `-f`, and passed positionally
+ *     it becomes an option instead of a path.
+ *   - Nothing here builds a destructive command. There is no `--force`, no
+ *     `reset --hard`, no `clean`. Losing committed work needs a confirmation
+ *     design of its own, not a button that happens to be adjacent to Push.
+ *
+ * @module
+ */
+/**
+ * Environment that makes git FAIL on a credential prompt instead of waiting for
+ * one.
+ *
+ * The subprocess capability is spawned with `stdin: 'ignore'`, which does not
+ * make an interactive prompt an error — it makes it a prompt nobody can answer,
+ * and git waits. That wait is inside the host process, so a single push to a
+ * repository whose token expired would hang the plugin for every session until
+ * the 30s grace elapsed. Each variable below closes one prompt route: git's own
+ * terminal prompt, Git Credential Manager's GUI, and the two askpass helpers.
+ */
+export const NON_INTERACTIVE_ENV = {
+    GIT_TERMINAL_PROMPT: '0',
+    GCM_INTERACTIVE: 'never',
+    GIT_ASKPASS: '',
+    SSH_ASKPASS: '',
+};
+/** Network operations wait on a remote, not on the disk. */
+export const NETWORK_GRACE_MS = 120_000;
+/**
+ * Whether a string is safe to hand git as a pathspec.
+ * @param path - repository-relative path from the client.
+ * @returns false for an empty string or anything git would read as an option.
+ */
+export function isSafePathArg(path) {
+    return typeof path === 'string' && path.length > 0 && !path.startsWith('-');
+}
+function checkedPaths(paths) {
+    if (paths.length === 0)
+        throw new Error('no paths given');
+    for (const path of paths) {
+        if (!isSafePathArg(path))
+            throw new Error(`unsafe path argument: ${JSON.stringify(path)}`);
+    }
+    return [...paths];
+}
+/**
+ * @param paths - repository-relative paths to stage.
+ * @returns argv for `git`, paths separated by `--`.
+ */
+export function stageArgv(paths) {
+    return ['add', '--', ...checkedPaths(paths)];
+}
+/**
+ * @param paths - repository-relative paths to remove from the index.
+ * @returns argv for `git`. `restore --staged` leaves the working tree alone;
+ *          `reset` would too, but `restore` cannot be confused with the
+ *          destructive spellings of the same verb.
+ */
+export function unstageArgv(paths) {
+    return ['restore', '--staged', '--', ...checkedPaths(paths)];
+}
+/**
+ * @param message - the commit message, used verbatim.
+ * @param amend - replace the previous commit instead of adding one.
+ * @returns argv for `git`. Never `-a`: the drawer has a staging area, and
+ *          sweeping the whole worktree in would make that split a lie.
+ */
+export function commitArgv(message, amend) {
+    if (typeof message !== 'string' || message.trim().length === 0) {
+        throw new Error('a commit message is required');
+    }
+    // One argv element. No shell runs here, so quoting is not the hazard —
+    // splitting on whitespace would be, and a multi-line body is normal.
+    return amend ? ['commit', '--amend', '-m', message] : ['commit', '-m', message];
+}
+/**
+ * @returns argv for `git`. `--prune` so a branch deleted on the remote stops
+ *          being counted as something to pull.
+ */
+export function fetchArgv() {
+    return ['fetch', '--prune'];
+}
+/**
+ * @param mode - how to integrate the upstream's commits.
+ * @returns argv for `git`. The mode is always explicit, never the user's
+ *          `pull.rebase` config: the button says what it will do.
+ */
+export function pullArgv(mode) {
+    if (mode === 'rebase')
+        return ['pull', '--rebase'];
+    if (mode === 'merge')
+        return ['pull', '--no-rebase'];
+    return ['pull', '--ff-only'];
+}
+/**
+ * @param branch - the current branch, needed only on its first push.
+ * @param hasUpstream - whether the branch already tracks a remote branch.
+ * @returns argv for `git`. With an upstream, bare `push` respects the user's
+ *          own remote and refspec configuration; without one, the first push
+ *          establishes `origin/<branch>`.
+ */
+export function pushArgv(branch, hasUpstream) {
+    if (hasUpstream)
+        return ['push'];
+    if (!isSafePathArg(branch))
+        throw new Error(`unsafe branch name: ${JSON.stringify(branch)}`);
+    return ['push', '--set-upstream', 'origin', branch];
+}
+const NO_TRACKING = { branch: '', upstream: null, ahead: 0, behind: 0, detached: false };
+/**
+ * Read the `##` header of porcelain status output.
+ *
+ * The distinction that matters is "no upstream" versus "an upstream we are level
+ * with": the first means push must pass `--set-upstream`, and both otherwise
+ * look like zero ahead and zero behind.
+ * @param stdout - full `git status --porcelain=v1 --branch` output.
+ */
+export function parseTracking(stdout) {
+    const header = stdout.split('\n').find(line => line.startsWith('## '));
+    if (header === undefined)
+        return NO_TRACKING;
+    const body = header.slice(3);
+    if (body.startsWith('HEAD (no branch)'))
+        return { ...NO_TRACKING, detached: true };
+    // An unborn branch (fresh `git init`) reports "No commits yet on main" —
+    // with the same optional upstream and bracket suffixes as a born header.
+    // The sync bar wants the branch's NAME, not the English sentence around it.
+    const UNBORN_PREFIX = 'No commits yet on ';
+    const born = body.startsWith(UNBORN_PREFIX) ? body.slice(UNBORN_PREFIX.length) : body;
+    // Divergence rides in a trailing bracket; strip it before splitting the refs.
+    const bracket = born.indexOf(' [');
+    const refs = bracket === -1 ? born : born.slice(0, bracket);
+    const counts = bracket === -1 ? '' : born.slice(bracket);
+    // `...` is the separator. Split on the LAST occurrence, not the first: a
+    // branch may contain dots, and only the separator is three of them.
+    const at = refs.lastIndexOf('...');
+    const branch = at === -1 ? refs : refs.slice(0, at);
+    const upstream = at === -1 ? null : refs.slice(at + 3);
+    const ahead = /ahead (\d+)/.exec(counts);
+    const behind = /behind (\d+)/.exec(counts);
+    return {
+        branch,
+        upstream: upstream !== null && upstream.length > 0 ? upstream : null,
+        ahead: ahead ? Number.parseInt(ahead[1], 10) : 0,
+        behind: behind ? Number.parseInt(behind[1], 10) : 0,
+        detached: false,
+    };
+}
+/** Porcelain XY pairs that mean "unmerged", per git-status(1). */
+const CONFLICT_XY = new Set(['DD', 'AU', 'UD', 'UA', 'DU', 'AA', 'UU']);
+/**
+ * Split a porcelain status pair into index and worktree state.
+ *
+ * A conflicted file reports content in the index (`UU`), so reading the X
+ * column alone calls it staged — and the drawer would then offer to commit a
+ * file with conflict markers still in it. Conflicts are reported as unstaged
+ * work, which is what they are until somebody resolves them.
+ * @param xy - the two status columns, e.g. ` M`, `MM`, `??`.
+ */
+export function stageStateOf(xy) {
+    if (xy === '??' || xy === '!!')
+        return { staged: false, unstaged: true };
+    if (CONFLICT_XY.has(xy))
+        return { staged: false, unstaged: true };
+    const index = xy[0] ?? ' ';
+    const worktree = xy[1] ?? ' ';
+    return { staged: index !== ' ', unstaged: worktree !== ' ' };
+}
+/**
+ * Turn git's exit into a reason the UI can act on.
+ *
+ * Matching on message text is fragile in general, but the alternative is
+ * showing raw stderr and letting the user work out that "Updates were rejected"
+ * means "fetch first". Anything unrecognised becomes `unknown`, and the caller
+ * still carries the real stderr alongside — the classification adds a hint, it
+ * never replaces the evidence.
+ * @param exitCode - git's exit status.
+ * @param stderr - captured stderr.
+ * @param stdout - captured stdout; `nothing to commit` arrives here, not stderr.
+ * @returns null when the command succeeded.
+ */
+export function classifyFailure(exitCode, stderr, stdout) {
+    if (exitCode === 0)
+        return null;
+    const text = `${stderr}\n${stdout}`.toLowerCase();
+    if (text.includes('nothing to commit')
+        || text.includes('no changes added to commit')
+        || text.includes('nothing added to commit'))
+        return 'nothing-to-commit';
+    if (text.includes('authentication failed')
+        || text.includes('could not read username')
+        || text.includes('could not read password')
+        || text.includes('permission denied (publickey)')
+        || text.includes('terminal prompts disabled'))
+        return 'auth';
+    // A network failure is worth its own class: "offline" and "bad remote URL"
+    // are fixable in different places, and neither is git's fault (TESTS.md D5).
+    if (text.includes('could not resolve host')
+        || text.includes('network is unreachable')
+        || text.includes('failed to connect')
+        || text.includes('connection timed out'))
+        return 'network';
+    if (text.includes('no upstream configured')
+        || text.includes('has no upstream branch'))
+        return 'no-upstream';
+    if (text.includes('conflict (')
+        || text.includes('merge conflict')
+        || text.includes('fix conflicts'))
+        return 'conflict';
+    if (text.includes('[rejected]')
+        || text.includes('updates were rejected')
+        || text.includes('not possible to fast-forward')
+        || text.includes('need to specify how to reconcile divergent branches'))
+        return 'diverged';
+    if (text.includes('would be overwritten')
+        || text.includes('local changes'))
+        return 'dirty';
+    return 'unknown';
+}
+/**
+ * Read `git diff --numstat` output into a path-keyed map.
+ *
+ * A `-` in either count column means git could not (or would not — a `-diff`
+ * gitattributes marker does it too) count the file: binary. Rename entries
+ * print `old => new` in the path column; the NEW path is what the porcelain
+ * status list also keys on, so that is the key kept here.
+ * @param stdout - full `--numstat` output.
+ */
+export function parseNumstat(stdout) {
+    const out = new Map();
+    for (const line of stdout.split('\n')) {
+        if (line.length === 0)
+            continue;
+        const parts = line.split('\t');
+        if (parts.length < 3)
+            continue;
+        const binary = parts[0] === '-' || parts[1] === '-';
+        const added = parts[0] === '-' ? 0 : Number.parseInt(parts[0], 10);
+        const deleted = parts[1] === '-' ? 0 : Number.parseInt(parts[1], 10);
+        const path = stripRenameTarget(parts.slice(2).join('\t'));
+        if (path.length > 0)
+            out.set(path, { added: Number.isFinite(added) ? added : 0, deleted: Number.isFinite(deleted) ? deleted : 0, binary });
+    }
+    return out;
+}
+/** Parse porcelain lines into a MUTABLE file list — untracked entries get their
+ * counts filled in by the synthesis pass afterwards. */
+export function parseStatus(stdout, numstat) {
+    const files = [];
+    for (const line of stdout.split('\n')) {
+        if (line.length === 0 || line.startsWith('##'))
+            continue;
+        if (line.length < 3)
+            continue;
+        const xy = line.slice(0, 2);
+        const { path, previousPath, renamed } = parsePath(line.slice(3));
+        if (path.length === 0)
+            continue;
+        const counts = numstat.get(path) ?? { added: 0, deleted: 0, binary: false };
+        const { staged, unstaged } = stageStateOf(xy);
+        const base = {
+            path, status: statusFromXY(xy, renamed),
+            addedLines: counts.added, deletedLines: counts.deleted, binary: counts.binary,
+            staged, unstaged,
+        };
+        files.push(renamed && previousPath.length > 0 ? { ...base, previousPath } : base);
+    }
+    return files;
+}
+/**
+ * Parse `git show --name-status --no-renames` into the mutable file list, taking
+ * line counts from the matching `--numstat` entry.
+ * @param stdout - name-status output (`<status>\t<path>` per line).
+ * @param numstat - per-path counts from {@link parseNumstat}.
+ * @returns one entry per file the commit touched.
+ */
+export function parseNameStatus(stdout, numstat) {
+    const files = [];
+    for (const line of stdout.split('\n')) {
+        if (line.length === 0)
+            continue;
+        const tab = line.indexOf('\t');
+        if (tab < 0)
+            continue;
+        const code = line.slice(0, tab);
+        const path = line.slice(tab + 1).trim();
+        if (path.length === 0)
+            continue;
+        const counts = numstat.get(path) ?? { added: 0, deleted: 0, binary: false };
+        files.push({
+            path,
+            status: code.startsWith('A') ? 'added' : code.startsWith('D') ? 'deleted' : 'modified',
+            addedLines: counts.added,
+            deletedLines: counts.deleted,
+            binary: counts.binary,
+        });
+    }
+    return files;
+}
+/**
+ * Split a porcelain path field into the file's path and, for a rename, the
+ * path it moved from.
+ *
+ * With `core.quotepath=false` (this plugin sets it on every git call) CJK and
+ * accented paths arrive as raw UTF-8, unquoted. Git still quotes a path that
+ * contains control characters or a quote, using C escapes — which is exactly
+ * JSON's escape alphabet, so `JSON.parse` un-escapes it. Octal escapes from
+ * the default quotepath mode are NOT JSON and stay raw; that is why the
+ * config, not smarter unescaping, is the fix.
+ * @param rest - the porcelain line past the two status columns.
+ */
+function parsePath(rest) {
+    let value = rest;
+    if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+        value = value.slice(1, -1);
+        try {
+            value = JSON.parse(`"${value}"`);
+        }
+        catch { /* keep raw */ }
+    }
+    const arrow = value.indexOf(' -> ');
+    if (arrow >= 0)
+        return { path: value.slice(arrow + 4), previousPath: value.slice(0, arrow), renamed: true };
+    return { path: value, previousPath: '', renamed: false };
+}
+function stripRenameTarget(path) {
+    const arrow = path.indexOf(' -> ');
+    return arrow >= 0 ? path.slice(arrow + 4) : path;
+}
+function statusFromXY(xy, renamed) {
+    if (xy === '??')
+        return 'untracked';
+    if (renamed || xy[0] === 'R' || xy[1] === 'R' || xy[0] === 'C' || xy[1] === 'C')
+        return 'renamed';
+    if (xy[0] === 'A' || xy[1] === 'A')
+        return 'added';
+    if (xy[0] === 'D' || xy[1] === 'D')
+        return 'deleted';
+    return 'modified';
+}
+/** ASCII line feed. Safe to count in raw UTF-8 bytes: no multi-byte sequence
+ * can contain it, so a byte scan and a decoded scan agree exactly. */
+const NEWLINE = 0x0a;
+/**
+ * Count lines in a UTF-8 buffer without decoding it.
+ * @param bytes - file contents.
+ * @returns the line count, counting a final unterminated line.
+ */
+export function countBufferLines(bytes) {
+    if (bytes.length === 0)
+        return 0;
+    let lines = 0;
+    for (let at = bytes.indexOf(NEWLINE); at !== -1; at = bytes.indexOf(NEWLINE, at + 1))
+        lines += 1;
+    return bytes[bytes.length - 1] === NEWLINE ? lines : lines + 1;
+}
+/**
+ * Whether a raw file buffer smells binary: a NUL byte inside the sniff window.
+ *
+ * UTF-16 text is the trap this exists for — it is text, but every other byte
+ * is NUL, so an 8 KB prefix catches it without reading a 200 MB blob. A NUL
+ * PAST the window does not decide anything: a text file may legitimately
+ * contain one deep in its body (TESTS.md A9).
+ * @param bytes - the file's contents, however much of them is cheap to read.
+ * @param windowBytes - how many leading bytes may decide.
+ */
+export function isBinaryPrefix(bytes, windowBytes) {
+    return bytes.subarray(0, windowBytes).includes(0);
+}
+/**
+ * Clip a diff to a character cap, and SAY so when the clip happened — a
+ * silently shortened diff reads as a complete one (TESTS.md H1).
+ * @param text - the diff.
+ * @param cap - most characters to keep.
+ * @param marker - the truncation note appended when clipping.
+ */
+export function clipDiff(text, cap, marker) {
+    return text.length > cap ? `${text.slice(0, cap)}\n${marker}` : text;
+}
+/**
+ * Cap the branch list the picker shows, and REPORT the cut: `branchesTruncated`
+ * is what lets the picker say "showing the first 500" instead of quietly
+ * looking like the repository only has 500 branches (TESTS.md F5).
+ * @param names - branch names, newest-commit-first.
+ * @param cap - how many to send.
+ */
+export function capBranches(names, cap) {
+    return { branches: names.slice(0, cap), branchesTruncated: names.length > cap };
+}
+/**
+ * Whether stderr is the "no merge base" refusal `git diff A...B` gives for
+ * histories with no common ancestor — the cue to retry the comparison as a
+ * plain two-tip diff instead of failing outright (TESTS.md C3).
+ * @param stderr - stderr of the failed three-dot diff.
+ */
+export function isNoMergeBaseError(stderr) {
+    return stderr.includes('no merge base');
+}