@profullstack/g1tz 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Profullstack, Inc.
+
+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,90 @@
+# g1tz
+
+A git TUI that shows you the repository, not a menu of git commands.
+
+```
+bunx @profullstack/g1tz          # the repository you are standing in
+bunx @profullstack/g1tz ~/proj   # somewhere else
+npm i -g @profullstack/g1tz      # then just g1tz
+```
+
+The package is scoped because npm refuses the bare name ("too similar to got, gts"); the command it installs is still `g1tz`.
+
+```
+ g1tz  main                    origin/main ↓1                        ~/hqtui  Tab panes  Space stage  q quit
+╭─ Files (3) ───────────────────────────╮ ╭─ Diff ─────────────────────────────────────────────────────────╮
+│ M    src/a.ts                         │ │ @@ -0,0 +1,8 @@                                                │
+│  M   src/b.ts                         │ │ +export interface Span {                                       │
+│ ??   new.ts                           │ │ +  text: string;                                               │
+╰───────────────────────────────────────╯ │ +}                                                             │
+╭─ Branches (39) ───────────────────────╮ │  const style: Style = { fg: options.fg };                      │
+│ * main ↓1                             │ │                                                                │
+│   spans-richtext                      │ │                                                                │
+╰───────────────────────────────────────╯ │                                                                │
+╭─ Log (78) ────────────────────────────╮ │                                                                │
+│ e28fec7   Finish widget parity  2h   │ │                                                                 │
+╰───────────────────────────────────────╯ ╰────────────────────────────────────────────────────────────────╯
+ Tab files  Space Stage  ↑↓ Move  r Reload  q Quit
+```
+
+Files, branches and log down the left. The diff on the right follows whatever you have selected — a file's changes, or a commit's patch.
+
+## Keys
+
+| Key | Does |
+|---|---|
+| `Tab` | Cycle files → branches → log |
+| `↑` `↓` `PgUp` `PgDn` | Move the selection |
+| `Space` | Stage the selected file, or unstage it if it is fully staged |
+| `←` `→` | Scroll the diff |
+| `r` | Re-read the repository |
+| `p` | Pulse: what moved over a period (below) |
+| `q` | Quit |
+
+## Pulse
+
+`p` flips to Pulse: what moved in this repository over a period, the way GitHub's Insights > Pulse tab shows it, but for the repository you are standing in and without leaving the terminal.
+
+```
+bunx @profullstack/g1tz pulse                 # start on the Pulse screen, last week
+bunx @profullstack/g1tz pulse --range month   # day, week, month, quarter, year, all
+```
+
+Three sources, each optional beyond the first:
+
+- **git**, always, offline: commits and authors on the branch and across every branch (merges counted separately, as GitHub does), the net change to the tree since the period began (`git diff` from the first parent of the oldest commit in range, with `-M` so a rename is a rename), commits per hour, day, week or month, the branches that saw commits and the tags that were created.
+- **GitHub**, when `origin` is on github.com and `gh` is logged in: pull requests opened, merged and closed, issues opened and closed, releases, and new stars for the period. Pages are walked newest first under a small budget; when the budget runs out the counts are floors and the status bar says so. Nothing here sees a token; `gh` holds the login.
+- **Traffic**, when a [gh-pulse](https://github.com/profullstack/cli-tools) report exists on the machine (`~/.local/share/gh-pulse`, or `GH_PULSE_DATA`): views and clones for the last fourteen days, referrers and popular paths. GitHub only serves those through its traffic API and only for fourteen days; gh-pulse keeps them.
+
+| Key | Does |
+|---|---|
+| `d` `w` `m` `q` `y` `a` | Pick the range: day, week, month, quarter, year, all time. The range buttons are clickable too. |
+| `↑` `↓` `PgUp` `PgDn` | Scroll the files |
+| `r` | Read it again |
+| `p` `Esc` | Back to the repository, where `q` quits |
+| `Ctrl+C` | Quit |
+
+## How it reads git
+
+By shelling out, using porcelain formats only, with `-z` wherever a path could contain a newline. Parsing output meant for humans is how a TUI ends up corrupting someone's working tree.
+
+`git` runs with `GIT_PAGER=cat`, `GIT_EDITOR=true` and `GIT_OPTIONAL_LOCKS=0`, so nothing it invokes can take the terminal away from the interface or fight the editor you already have open.
+
+Untracked files are listed with `--untracked-files=all`. The default collapses a new directory to a single `? sub/` entry, and you cannot stage or diff a directory.
+
+## Status
+
+Early, and deliberately read-mostly. It reads the repository and stages files. It does **not** yet commit, push, pull, branch, rebase, stash, or discard — the destructive half is the half worth getting right slowly.
+
+Known rough edges:
+
+- The diff is coloured a line at a time, one `text()` call per line, because per-line styling is all the library offers today. Styled spans land in `@profullstack/hqtui` 0.3.0 ([hqtui#60](https://github.com/profullstack/hqtui/issues/60)) and will make word-level diff highlighting possible.
+- No hunk staging. That wants an interactive diff pane.
+
+## Built with
+
+[hqtui](https://hqtui.com) — the terminal UI library. g1tz exists partly to keep hqtui honest: a real application finds the gaps a widget gallery does not.
+
+## Licence
+
+MIT

package/bin/g1tz.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/main.js";

package/dist/diff.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Diff rendering, as spans.
+ *
+ * A whole line coloured green tells you it changed. Colouring only the words
+ * that actually differ tells you *what* changed, which is the thing you were
+ * squinting at the line to work out.
+ */
+import type { SpanLine } from "@profullstack/hqtui";
+export interface DiffPalette {
+    add: number;
+    remove: number;
+    hunk: number;
+    meta: number;
+    context: number;
+    /** Background emphasis for the words that actually differ. */
+    addEmphasis: number;
+    removeEmphasis: number;
+}
+/** Split into words and the separators between them, both kept. */
+export declare function words(line: string): string[];
+export interface Segment {
+    text: string;
+    changed: boolean;
+}
+/**
+ * The differing middle of two lines, found by trimming the common prefix and
+ * suffix. Not a full Myers diff: for the single-line case a prefix/suffix trim
+ * is what people actually read, and it cannot produce the confetti that a
+ * token-level LCS gives you on a reformatted line.
+ */
+export declare function intraLine(before: string, after: string): {
+    before: Segment[];
+    after: Segment[];
+};
+/**
+ * Pair each removed line with the added line that replaced it.
+ *
+ * Only runs of equal length are paired. An unequal run is a genuine insertion
+ * or deletion rather than an edit, and pretending otherwise produces word
+ * highlighting that points at the wrong thing.
+ */
+export declare function pairRuns(lines: string[]): Map<number, number>;
+/** A whole diff as span lines, with the changed words emphasised. */
+export declare function highlightDiff(lines: string[], palette: DiffPalette): SpanLine[];

package/dist/diff.js

@@ -0,0 +1,112 @@
+import { diffLineKind } from "./git.js";
+/** Split into words and the separators between them, both kept. */
+export function words(line) {
+    return line.split(/(\W)/).filter((part) => part !== "");
+}
+/**
+ * The differing middle of two lines, found by trimming the common prefix and
+ * suffix. Not a full Myers diff: for the single-line case a prefix/suffix trim
+ * is what people actually read, and it cannot produce the confetti that a
+ * token-level LCS gives you on a reformatted line.
+ */
+export function intraLine(before, after) {
+    const a = words(before);
+    const b = words(after);
+    let head = 0;
+    while (head < a.length && head < b.length && a[head] === b[head])
+        head++;
+    let tail = 0;
+    while (tail < a.length - head &&
+        tail < b.length - head &&
+        a[a.length - 1 - tail] === b[b.length - 1 - tail])
+        tail++;
+    const build = (parts) => {
+        const middle = parts.slice(head, parts.length - tail).join("");
+        const out = [];
+        const prefix = parts.slice(0, head).join("");
+        const suffix = parts.slice(parts.length - tail).join("");
+        if (prefix)
+            out.push({ text: prefix, changed: false });
+        if (middle)
+            out.push({ text: middle, changed: true });
+        if (suffix)
+            out.push({ text: suffix, changed: false });
+        return out;
+    };
+    return { before: build(a), after: build(b) };
+}
+/**
+ * Pair each removed line with the added line that replaced it.
+ *
+ * Only runs of equal length are paired. An unequal run is a genuine insertion
+ * or deletion rather than an edit, and pretending otherwise produces word
+ * highlighting that points at the wrong thing.
+ */
+export function pairRuns(lines) {
+    const pairs = new Map();
+    let i = 0;
+    while (i < lines.length) {
+        if (!isRemoval(lines[i])) {
+            i++;
+            continue;
+        }
+        let removals = 0;
+        while (i + removals < lines.length && isRemoval(lines[i + removals]))
+            removals++;
+        let additions = 0;
+        while (i + removals + additions < lines.length &&
+            isAddition(lines[i + removals + additions]))
+            additions++;
+        if (removals === additions && removals > 0) {
+            for (let k = 0; k < removals; k++)
+                pairs.set(i + k, i + removals + k);
+        }
+        i += removals + additions;
+    }
+    return pairs;
+}
+function isRemoval(line) {
+    return line.startsWith("-") && !line.startsWith("---");
+}
+function isAddition(line) {
+    return line.startsWith("+") && !line.startsWith("+++");
+}
+/** A whole diff as span lines, with the changed words emphasised. */
+export function highlightDiff(lines, palette) {
+    const pairs = pairRuns(lines);
+    const partnerOf = new Map();
+    for (const [from, to] of pairs)
+        partnerOf.set(to, from);
+    const colorFor = (line) => {
+        switch (diffLineKind(line)) {
+            case "success": return palette.add;
+            case "danger": return palette.remove;
+            case "accent": return palette.hunk;
+            case "muted": return palette.meta;
+            default: return palette.context;
+        }
+    };
+    return lines.map((line, index) => {
+        const base = colorFor(line);
+        const partner = pairs.has(index)
+            ? lines[pairs.get(index)]
+            : partnerOf.has(index)
+                ? lines[partnerOf.get(index)]
+                : undefined;
+        if (partner === undefined) {
+            return line === "" ? [] : [{ text: line, fg: base }];
+        }
+        const removed = isRemoval(line);
+        const { before, after } = intraLine((removed ? line : partner).slice(1), (removed ? partner : line).slice(1));
+        const segments = removed ? before : after;
+        const emphasis = removed ? palette.removeEmphasis : palette.addEmphasis;
+        return [
+            { text: line.slice(0, 1), fg: base },
+            ...segments.map((segment) => ({
+                text: segment.text,
+                fg: base,
+                ...(segment.changed ? { bg: emphasis, bold: true } : {}),
+            })),
+        ];
+    });
+}

package/dist/git.d.ts

@@ -0,0 +1,61 @@
+export interface FileChange {
+    /** Index status, as git reports it: M, A, D, R, C, U or space. */
+    index: string;
+    /** Worktree status. */
+    work: string;
+    path: string;
+    /** Original path for a rename. */
+    from?: string;
+    staged: boolean;
+    unstaged: boolean;
+    untracked: boolean;
+    conflicted: boolean;
+}
+export interface Commit {
+    hash: string;
+    short: string;
+    subject: string;
+    author: string;
+    when: string;
+    refs: string;
+}
+export interface Branch {
+    name: string;
+    current: boolean;
+    upstream: string;
+    ahead: number;
+    behind: number;
+}
+export interface GitError {
+    command: string;
+    message: string;
+}
+export interface Repo {
+    root: string;
+    branch: string;
+    upstream: string;
+    ahead: number;
+    behind: number;
+    files: FileChange[];
+    commits: Commit[];
+    branches: Branch[];
+    errors: GitError[];
+}
+/** Run git and return stdout, or null when it fails. Never throws. */
+export declare function git(cwd: string, args: string[]): string | null;
+export declare function repoRoot(cwd: string): string | null;
+/**
+ * `git status --porcelain=v2 -z`. v2 rather than v1 because it reports the
+ * branch, the upstream and the ahead/behind counts in the same call, and -z
+ * because a path may contain anything but NUL.
+ */
+export declare function parseStatus(out: string): Pick<Repo, "branch" | "upstream" | "ahead" | "behind" | "files">;
+export declare function parseLog(out: string): Commit[];
+export declare function parseBranches(out: string): Branch[];
+export declare function readRepo(cwd: string, logLimit?: number): Repo | null;
+/** The diff for one path, staged or not. Empty string when there is none. */
+export declare function fileDiff(root: string, file: FileChange, staged: boolean): string;
+/** Colour family for a diff line, as a theme key. */
+export declare function diffLineKind(line: string): "success" | "danger" | "accent" | "muted" | "foreground";
+export declare function stage(root: string, file: FileChange): boolean;
+export declare function unstage(root: string, file: FileChange): boolean;

package/dist/git.js

@@ -0,0 +1,182 @@
+/**
+ * Everything g1tz knows about a repository, read by shelling out to git.
+ *
+ * Porcelain formats only, with explicit -z where a filename could contain a
+ * newline. Parsing `git status` output meant for humans is how a TUI ends up
+ * corrupting someone's working tree.
+ */
+import { spawnSync } from "node:child_process";
+/** Run git and return stdout, or null when it fails. Never throws. */
+export function git(cwd, args) {
+    const result = spawnSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        maxBuffer: 32 * 1024 * 1024,
+        // A pager or an editor would take the terminal away from the TUI.
+        env: { ...process.env, GIT_PAGER: "cat", GIT_EDITOR: "true", GIT_OPTIONAL_LOCKS: "0" },
+    });
+    if (result.error || result.status !== 0)
+        return null;
+    return result.stdout;
+}
+export function repoRoot(cwd) {
+    return git(cwd, ["rev-parse", "--show-toplevel"])?.trim() || null;
+}
+/**
+ * `git status --porcelain=v2 -z`. v2 rather than v1 because it reports the
+ * branch, the upstream and the ahead/behind counts in the same call, and -z
+ * because a path may contain anything but NUL.
+ */
+export function parseStatus(out) {
+    const result = { branch: "", upstream: "", ahead: 0, behind: 0, files: [] };
+    const records = out.split("\0");
+    for (let i = 0; i < records.length; i++) {
+        const line = records[i];
+        if (line === "")
+            continue;
+        if (line.startsWith("# branch.head ")) {
+            result.branch = line.slice("# branch.head ".length);
+        }
+        else if (line.startsWith("# branch.upstream ")) {
+            result.upstream = line.slice("# branch.upstream ".length);
+        }
+        else if (line.startsWith("# branch.ab ")) {
+            const m = /\+(-?\d+) -(-?\d+)/.exec(line);
+            if (m) {
+                result.ahead = Number(m[1]);
+                result.behind = Number(m[2]);
+            }
+        }
+        else if (line.startsWith("1 ") || line.startsWith("2 ")) {
+            const rename = line.startsWith("2 ");
+            const parts = line.split(" ");
+            const xy = parts[1] ?? "..";
+            const index = xy[0] ?? ".";
+            const work = xy[1] ?? ".";
+            // Fields are fixed up to the path, which is the rest of the record.
+            const pathStart = rename ? 9 : 8;
+            const path = parts.slice(pathStart).join(" ");
+            // A rename's original path is the *next* NUL-separated record.
+            const from = rename ? records[++i] : undefined;
+            result.files.push({
+                index, work, path, from,
+                staged: index !== "." && index !== " ",
+                unstaged: work !== "." && work !== " ",
+                untracked: false,
+                conflicted: false,
+            });
+        }
+        else if (line.startsWith("u ")) {
+            const parts = line.split(" ");
+            result.files.push({
+                index: "U", work: "U",
+                path: parts.slice(10).join(" "),
+                staged: false, unstaged: true, untracked: false, conflicted: true,
+            });
+        }
+        else if (line.startsWith("? ")) {
+            result.files.push({
+                index: "?", work: "?", path: line.slice(2),
+                staged: false, unstaged: true, untracked: true, conflicted: false,
+            });
+        }
+    }
+    return result;
+}
+const LOG_FORMAT = "%H%x1f%h%x1f%s%x1f%an%x1f%ar%x1f%D";
+export function parseLog(out) {
+    const commits = [];
+    for (const raw of out.split("\0")) {
+        // `--pretty=format:` puts a newline BETWEEN records, after the NUL, so
+        // every record but the first starts with one. Left in, it rode along on
+        // the hash and `git show` failed for every commit but the first.
+        const line = raw.replace(/^\n/, "");
+        if (line === "")
+            continue;
+        const [hash, short, subject, author, when, refs] = line.split("\x1f");
+        if (!hash)
+            continue;
+        commits.push({
+            hash, short: short ?? "", subject: subject ?? "",
+            author: author ?? "", when: when ?? "", refs: refs ?? "",
+        });
+    }
+    return commits;
+}
+const BRANCH_FORMAT = "%(HEAD)%1f%(refname:short)%1f%(upstream:short)%1f%(upstream:track)";
+export function parseBranches(out) {
+    const branches = [];
+    for (const line of out.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        const [head, name, upstream, track] = line.split("\x1f");
+        if (!name)
+            continue;
+        const ahead = /ahead (\d+)/.exec(track ?? "");
+        const behind = /behind (\d+)/.exec(track ?? "");
+        branches.push({
+            name,
+            current: head === "*",
+            upstream: upstream ?? "",
+            ahead: ahead ? Number(ahead[1]) : 0,
+            behind: behind ? Number(behind[1]) : 0,
+        });
+    }
+    return branches;
+}
+export function readRepo(cwd, logLimit = 200) {
+    const root = repoRoot(cwd);
+    if (!root)
+        return null;
+    const errors = [];
+    const run = (args) => {
+        const out = git(root, args);
+        if (out === null) {
+            errors.push({ command: `git ${args[0]}`, message: "failed" });
+            return "";
+        }
+        return out;
+    };
+    // --untracked-files=all, because the default collapses a new directory to a
+    // single "? sub/" entry and you cannot stage or diff a directory here.
+    const status = parseStatus(run(["status", "--porcelain=v2", "--branch", "--untracked-files=all", "-z"]));
+    // --no-show-signature: with log.showSignature set, git writes the
+    // verification text on stdout ahead of every record, glued to the hash.
+    const commits = parseLog(run(["log", "--no-show-signature", `--pretty=format:${LOG_FORMAT}%x00`, "-n", String(logLimit)]));
+    const branches = parseBranches(run(["for-each-ref", "--sort=-committerdate",
+        `--format=${BRANCH_FORMAT}`, "refs/heads"]));
+    return { root, ...status, commits, branches, errors };
+}
+/** The diff for one path, staged or not. Empty string when there is none. */
+export function fileDiff(root, file, staged) {
+    if (file.untracked) {
+        const out = git(root, ["diff", "--no-color", "--no-index", "/dev/null", file.path]);
+        // --no-index exits 1 when the files differ, which is always here.
+        return out ?? git(root, ["show", `:${file.path}`]) ?? "(untracked)";
+    }
+    const args = ["diff", "--no-color"];
+    if (staged)
+        args.push("--cached");
+    args.push("--", file.path);
+    return git(root, args) ?? "";
+}
+/** Colour family for a diff line, as a theme key. */
+export function diffLineKind(line) {
+    if (line.startsWith("+++") || line.startsWith("---"))
+        return "muted";
+    if (line.startsWith("@@"))
+        return "accent";
+    if (line.startsWith("+"))
+        return "success";
+    if (line.startsWith("-"))
+        return "danger";
+    if (line.startsWith("diff ") || line.startsWith("index "))
+        return "muted";
+    return "foreground";
+}
+export function stage(root, file) {
+    return git(root, ["add", "--", file.path]) !== null;
+}
+export function unstage(root, file) {
+    return git(root, ["restore", "--staged", "--", file.path]) !== null;
+}

package/dist/github.d.ts

@@ -0,0 +1,63 @@
+export interface GitHubRepo {
+    owner: string;
+    name: string;
+}
+export interface GitHubItem {
+    number: number;
+    title: string;
+    user: string;
+    /** ISO date of the event this item is listed for: opened, merged or closed. */
+    at: string;
+}
+export interface GitHubRelease {
+    tag: string;
+    name: string;
+    at: string;
+}
+export interface GitHubPulse {
+    repo: string;
+    url: string;
+    description: string;
+    stars: number;
+    forks: number;
+    /** GitHub's open issue count, which includes open pull requests. */
+    openIssues: number;
+    prsOpened: GitHubItem[];
+    prsMerged: GitHubItem[];
+    /** Closed without merging. */
+    prsClosed: GitHubItem[];
+    issuesOpened: GitHubItem[];
+    issuesClosed: GitHubItem[];
+    releases: GitHubRelease[];
+    newStars: number;
+    /** A page budget ran out somewhere, so a count is a floor rather than a total. */
+    partial: boolean;
+}
+/**
+ * https, ssh and scp-style GitHub remotes, with or without .git, including
+ * GitHub's "SSH over the HTTPS port" form (ssh.github.com:443) and an explicit
+ * port. Anything else is null.
+ */
+export declare function parseGitHubRemote(url: string): GitHubRepo | null;
+export declare function githubRemote(root: string): GitHubRepo | null;
+export declare const repoName: (repo: GitHubRepo) => string;
+/** One GitHub API call: a path relative to the API root, parsed JSON back. */
+export type Fetch = (path: string, headers?: Record<string, string>) => Promise<unknown>;
+/** Whether gh is on the PATH. Asked once per process. */
+export declare function ghInstalled(): boolean;
+/** What to tell the user when gh could not answer. */
+export declare function ghErrorMessage(error: {
+    code?: string | number | null | undefined;
+    signal?: string | null | undefined;
+    killed?: boolean | undefined;
+    message: string;
+}, stderr: string): string;
+export declare function ghFetch(path: string, headers?: Record<string, string>): Promise<unknown>;
+export interface PageBudget {
+    pulls: number;
+    issues: number;
+    releases: number;
+    stars: number;
+}
+export declare const PAGE_BUDGET: PageBudget;
+export declare function readGitHubPulse(repo: GitHubRepo, since: Date | null, fetch?: Fetch, budget?: PageBudget): Promise<GitHubPulse>;