git-backstory 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amado / ByteCraft Technologies LLC
+
+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

@@ -1,3 +1,138 @@
-# Temporary Holding Version
+# git-backstory
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/git-backstory)](https://www.npmjs.com/package/git-backstory)
+[![CI](https://github.com/hexmillionaire/git-backstory/actions/workflows/ci.yml/badge.svg)](https://github.com/hexmillionaire/git-backstory/actions/workflows/ci.yml)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](package.json)
+[![license](https://img.shields.io/npm/l/git-backstory)](LICENSE)
+
+**The backstory of a file, in one page, for whoever has to change it next.**
+
+```bash
+npx git-backstory src/billing/invoice.ts
+```
+
+`git blame` tells you who. `git log` tells you when. Neither tells you that the rounding change was reverted twice, that this file never changes without `invoice.test.ts`, or that someone wrote "must be applied before rounding, otherwise totals drift" in a commit body three years ago. git-backstory reads the history and writes that down in a page of markdown.
+
+Zero dependencies. Runs `git log` and `git blame` only. Never writes to your repo, never touches the network, no API key.
+
+---
+
+## Who it's for
+
+**Coding agents.** Claude Code, Cursor, Codex and friends read the current code and nothing else. They don't know a change was tried and reverted, so they try it again. Run git-backstory on the file before editing and paste the brief in, or install the [skill](#let-your-agent-run-it) and let the agent do it.
+
+**You, on a file you didn't write.** Before touching the scary file, read its brief. Takes a second to generate and a minute to read.
+
+**Reviewers.** `git-backstory path/to/file:120-160` on the lines a PR touches tells you whether those lines have a history of trouble.
+
+---
+
+## Example
+
+Run on the navbar of a Next.js app:
+
+```markdown
+# History brief: `src/components/navbar.tsx`
+
+22 commits · first 2026-03-26 (7 months ago) · last 2026-10-08 (10 days ago) · 2 authors · 139 lines now
+
+## Be careful
+
+- Fix-shaped commits (8): `41a3ae1` "feat: fix reading on a phone"; `2722d44` "fix: use Clerk
+  useUser() for UI auth gating to break auth loop"; `b24e8cc` "fix: resolve Convex-Clerk auth
+  integration and add logout button"; …
+
+## Reasons on record
+
+- Geist fonts from node_modules so builds never fetch Google Fonts — `a77be23`, 2026-10-08
+
+## Usually changes together with
+
+- `src/app/bible/[book]/[chapter]/chapter-reader.tsx` — 10 of the sampled commits (45%)
+- `src/app/layout.tsx` — 9 of the sampled commits (41%)
+- `src/app/login/page.tsx` — 7 of the sampled commits (32%)
+
+If you change this file, check whether those need the same change.
+
+## Who to ask
+
+Current lines by author: hexmillionaire 65%, Amado 35%.
+
+## Timeline
+
+- 2026-10-08 `a77be23` Extract Vibe Stack: Next.js + Convex + Clerk starter kit — Amado
+- 2026-08-31 `41a3ae1` feat: fix reading on a phone — hexmillionaire
+- 2026-03-28 `2722d44` fix: use Clerk useUser() for UI auth gating to break auth loop — hexmillionaire
+…
+```
+
+When the remote is on GitHub, GitLab or Bitbucket, hashes and `#123` references become links.
+
+## What it looks for
+
+| Section | Source | Shows up when |
+|---|---|---|
+| **Be careful** | Reverts (`This reverts commit…` or `Revert "…"`), fix-shaped subjects, bursts of commits around a fix | There is a revert, a fix, or a cluster of attempts |
+| **Reasons on record** | Commit bodies: sentences with *because*, *must*, *never*, *otherwise*, *so that*… | An author explained a constraint |
+| **Usually changes together with** | Files changed in the same commits, ≥30% of the time | The file has coupling worth knowing about |
+| **Referenced issues and PRs** | `#123` / `GH-123` in subjects and bodies | Any are present |
+| **Who to ask** | `git blame` ownership of the current lines | Always, for tracked files |
+| **Timeline** | Notable commits plus the most recent ones, newest first | Always |
+
+Sections with nothing to say are omitted, so a quiet file gets a quiet brief.
+
+---
+
+## Usage
+
+```bash
+npx git-backstory <path>              # brief for a file
+npx git-backstory <path>:<line>       # one line
+npx git-backstory <path>:<from>-<to>  # a line range (uses git log -L)
+npx git-backstory <path> --json       # the facts as JSON
+npx git-backstory <path> --out BRIEF.md
+npx git-backstory <path> --since "6 months ago"
+npx git-backstory <path> --max 500    # sample more than 200 commits
+npx git-backstory <path> --no-links   # plain hashes
+```
+
+Requires Node 18+ and git. Paths can be relative to your current directory or absolute; the brief is for the repository that contains them. Renames are followed, and the brief lists the file's previous paths.
+
+---
+
+## Let your agent run it
+
+**Claude Code:** install the skill once; the agent then runs a brief before editing files with history.
+
+```bash
+mkdir -p ~/.claude/skills/git-backstory
+curl -fsSL https://raw.githubusercontent.com/hexmillionaire/git-backstory/main/skills/git-backstory/SKILL.md \
+  -o ~/.claude/skills/git-backstory/SKILL.md
+```
+
+**Anything else:** add a line to your `CLAUDE.md`, `AGENTS.md` or rules file:
+
+> Before changing a file with more than a handful of commits, run `npx -y git-backstory <path>` and read the "Be careful" and "Usually changes together with" sections.
+
+Agents looking for a summary of this tool can read [`llms.txt`](llms.txt).
+
+---
+
+## Why
+
+The most expensive bugs in a codebase are the ones that were already fixed once. The fix is in the history, the reason is in a commit body, and nobody reads either before changing the code, least of all an agent that only sees the working tree. git-backstory makes that history cheap to read: one command, one page, the parts that matter first.
+
+It is deliberately heuristic. "Fix-shaped" means the subject says fix, regression, revert, broke or similar; "reasons" means sentences that sound like constraints. It will miss some and over-include others. Read the brief like a colleague's notes, not a verdict.
+
+## Safety
+
+Runs `git log`, `git blame`, `git show`, `git ls-files`, `git rev-parse` and `git remote get-url`. All reads. It never executes project code and never makes network requests. Commit messages and author names from the repository appear in the output, so review a brief before sharing it outside the team. See [SECURITY.md](SECURITY.md).
+
+## Related
+
+- [claude-md-generator](https://github.com/hexmillionaire/claude-md-generator) — `npx claude-md-generator` drafts the CLAUDE.md your agent reads every session.
+- [Agent Lanes](https://github.com/hexmillionaire/agent-lanes) — keep an agent's task inside its declared file scope, then hand it off.
+
+## License
+
+MIT

package/bin/git-backstory.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.js";
+process.exitCode = await run();

package/llms.txt

@@ -0,0 +1,27 @@
+# git-backstory
+
+> Zero-dependency Node CLI that writes a one-page markdown history brief for a single file (or line range) from `git log` and `git blame`: reverts, fix bursts, constraints quoted from commit bodies, files that usually change together, line ownership and a short timeline. Built so coding agents stop re-making changes that were already reverted.
+
+Run in any git repo, no install: `npx -y git-backstory <path>`. Node 18+ and git. Read-only: never writes to the repo, never uses the network, no API key.
+
+## Usage
+
+- `npx -y git-backstory src/file.ts` — brief for a file (follows renames)
+- `npx -y git-backstory src/file.ts:120-160` — brief for a line range
+- `npx -y git-backstory src/file.ts --json` — the same facts as JSON
+- `--since <date>`, `--max <n>`, `--out <file>`, `--no-links`
+
+## When an agent should run it
+
+Before editing a file that has more than a handful of commits, or any file the task calls risky. Read "Be careful" (reverts, fixes, bursts) and "Usually changes together with" (coupling) first; if a revert is listed, open both commits before attempting a similar change.
+
+## Output sections
+
+Be careful · Reasons on record · Usually changes together with · Referenced issues and PRs · Who to ask · Timeline. Empty sections are omitted.
+
+## Docs
+
+- README: https://github.com/hexmillionaire/git-backstory#readme
+- Agent skill: https://github.com/hexmillionaire/git-backstory/blob/main/skills/git-backstory/SKILL.md
+- Security: https://github.com/hexmillionaire/git-backstory/blob/main/SECURITY.md
+- npm: https://www.npmjs.com/package/git-backstory

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "git-backstory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The backstory of a file, in one page, for whoever has to change it next: reverts, fix bursts, reasons from commit bodies, co-changed files and owners, from git log and git blame. Zero dependencies.",
+  "type": "module",
+  "bin": {
+    "git-backstory": "bin/git-backstory.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE",
+    "llms.txt",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/analyze.test.js test/cli.test.js",
+    "try": "node bin/git-backstory.js src/cli.js"
+  },
+  "keywords": [
+    "git",
+    "git-log",
+    "git-blame",
+    "history",
+    "code-archaeology",
+    "ai-coding",
+    "claude-code",
+    "cursor",
+    "codex",
+    "copilot",
+    "agents",
+    "context-engineering",
+    "cli",
+    "developer-tools",
+    "zero-dependencies",
+    "backstory"
+  ],
+  "author": "Amado (hexmillionaire)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hexmillionaire/git-backstory.git"
+  },
+  "homepage": "https://github.com/hexmillionaire/git-backstory#readme",
+  "bugs": {
+    "url": "https://github.com/hexmillionaire/git-backstory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/git-backstory/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: git-backstory
+description: Run a one-page git backstory on a file before changing it — reverts, fix bursts, reasons from commit bodies, files that change together. Use before editing any file with real history, when a task says "careful", or when a change you are about to make feels like it may have been tried before.
+---
+
+# git-backstory
+
+A file's history says what not to do. This skill reads it in one command before you edit.
+
+## When
+
+- Before editing a file with more than ~5 commits, or one the user calls fragile, legacy or "the scary one".
+- Before re-implementing something that looks like it should already exist.
+- When a PR touches lines you don't understand: brief the range.
+
+## Steps
+
+1. Run `npx -y git-backstory <path>` (or `<path>:<from>-<to>` for a range). It needs git and Node 18+; nothing is installed into the repo.
+2. Read **Be careful** first. If a revert is listed, open both commits (`git show <hash>`) and understand why before attempting anything similar. If there is a fix burst, assume the area is subtle.
+3. Read **Usually changes together with**. When you change this file, check each listed file for the same change, and mention the ones you deliberately left alone.
+4. Read **Reasons on record**. These are constraints the authors wrote down; treat them as requirements unless the user overrides them.
+5. Make the change. In your summary to the user, cite the relevant brief lines in one sentence ("the rounding change was reverted in `b8bc09f`, so I kept rounding out of `price()`").
+
+## Notes
+
+- Heuristic by design: "fix-shaped" means the subject says fix/regression/revert/broke; "reasons" means sentences with because/must/never/otherwise. Use judgment.
+- Pass `--json` when you want to filter the facts yourself.
+- Commit messages and author names appear in the output; don't paste a brief from a private repo into a public place.

package/src/analyze.js

@@ -0,0 +1,170 @@
+// Pure: commit list in, facts out. No git here, so this is easy to test.
+
+const REVERT_RE = /^Revert\s+"(.+)"/i;
+const REVERTS_HASH_RE = /This reverts commit ([0-9a-f]{7,40})/i;
+const ISSUE_RE = /(?:^|[\s(])(?:#|GH-)(\d+)\b/g;
+const FIX_RE = /\b(fix|fixes|fixed|bug|regression|hotfix|revert|crash|broke|broken|workaround|incident|rollback|flaky)\b/i;
+const CONSTRAINT_RE = /\b(must|never|always|do not|don't|because|otherwise|so that|required|invariant|careful|note:|important|gotcha|subtle)\b/i;
+
+export function analyze(commits, { file, blame = null, lineCount = null, now = new Date() } = {}) {
+  const selfPaths = new Set([file, ...renameTrail(commits, file)]);
+  const byHash = new Map(commits.map((c) => [c.hash, c]));
+  const byShort = new Map(commits.map((c) => [c.short, c]));
+
+  // Reverts: either "This reverts commit X" or Revert "<subject>".
+  const reverts = [];
+  const revertedHashes = new Set();
+  for (const c of commits) {
+    const h = c.body.match(REVERTS_HASH_RE)?.[1];
+    let target = null;
+    if (h) target = byHash.get(h) ?? [...byHash.values()].find((x) => x.hash.startsWith(h)) ?? byShort.get(h) ?? null;
+    const s = c.subject.match(REVERT_RE)?.[1];
+    if (!target && s) target = commits.find((x) => x !== c && x.subject === s) ?? null;
+    if (h || s) {
+      reverts.push({ revert: c, target });
+      if (target) revertedHashes.add(target.hash);
+    }
+  }
+
+  // Fix-shaped commits: the places where something went wrong before.
+  const fixes = commits.filter((c) => !revertedHashes.has(c.hash) && !REVERT_RE.test(c.subject) && FIX_RE.test(c.subject));
+
+  // Issue/PR references.
+  const refs = new Map(); // number -> commits
+  for (const c of commits) {
+    for (const m of `${c.subject}\n${c.body}`.matchAll(ISSUE_RE)) {
+      const n = m[1];
+      if (!refs.has(n)) refs.set(n, []);
+      refs.get(n).push(c);
+    }
+  }
+
+  // Co-changed files: what else moves when this file moves.
+  const co = new Map();
+  let withFiles = 0;
+  for (const c of commits) {
+    if (!c.files.length) continue;
+    withFiles += 1;
+    for (const f of c.files) {
+      if (selfPaths.has(f)) continue;
+      co.set(f, (co.get(f) ?? 0) + 1);
+    }
+  }
+  const coChanged = [...co.entries()]
+    .filter(([, n]) => n >= 2 && withFiles >= 3)
+    .map(([path, n]) => ({ path, count: n, share: n / withFiles }))
+    .filter((x) => x.share >= 0.3)
+    .sort((a, b) => b.count - a.count || a.path.localeCompare(b.path))
+    .slice(0, 5);
+
+  // Churn: bursts of activity (3+ commits within 7 days) read as "this was hard".
+  const sorted = [...commits].sort((a, b) => new Date(a.date) - new Date(b.date));
+  const bursts = [];
+  let run = [];
+  for (const c of sorted) {
+    if (run.length && new Date(c.date) - new Date(run[run.length - 1].date) > 7 * 86400e3) {
+      if (run.length >= 3) bursts.push(run);
+      run = [];
+    }
+    run.push(c);
+  }
+  if (run.length >= 3) bursts.push(run);
+  // A burst only matters when it reads as struggle, not normal early development:
+  // it contains a fix or revert, or an older file suddenly got 4+ commits in 3 days.
+  const ageDaysAll = sorted.length ? (now - new Date(sorted[0].date)) / 86400e3 : 0;
+  const isFixy = (c) => FIX_RE.test(c.subject) || REVERT_RE.test(c.subject) || REVERTS_HASH_RE.test(c.body);
+  const notableBursts = bursts.filter((b) => {
+    if (sorted[0] && b[0].hash === sorted[0].hash) return false; // the initial build-out is not a warning
+    const span = (new Date(b[b.length - 1].date) - new Date(b[0].date)) / 86400e3;
+    return b.some(isFixy) || (ageDaysAll > 30 && b.length >= 4 && span <= 3);
+  });
+
+  // Authors.
+  const authorCount = new Map();
+  for (const c of commits) authorCount.set(c.author, (authorCount.get(c.author) ?? 0) + 1);
+  const authors = [...authorCount.entries()].sort((a, b) => b[1] - a[1]).map(([name, count]) => ({ name, count }));
+
+  // Lines worth surfacing from bodies: reasons, constraints, warnings.
+  const notes = [];
+  for (const c of commits) {
+    if (revertedHashes.has(c.hash)) continue;
+    for (const raw of unwrap(c.body)) {
+      const line = raw.replace(/^[-*>\s]+/, "").trim();
+      if (line.length < 20 || line.length > 240 || /[,:;]$/.test(line)) continue;
+      if (/^(signed-off-by|co-authored-by|reviewed-by|see-also|refs?:|closes|fixes #|resolves|claude-session|https?:\/\/)/i.test(line)) continue;
+      if (CONSTRAINT_RE.test(line)) notes.push({ commit: c, line });
+      if (notes.length >= 12) break;
+    }
+    if (notes.length >= 12) break;
+  }
+
+  const first = sorted[0] ?? null;
+  const last = sorted[sorted.length - 1] ?? null;
+  const ageDays = first ? Math.round((now - new Date(first.date)) / 86400e3) : null;
+  const quietDays = last ? Math.round((now - new Date(last.date)) / 86400e3) : null;
+
+  // Blame: who owns the current lines, and how much is from one commit.
+  let ownership = null;
+  if (blame && blame.total > 0) {
+    const topAuthors = [...blame.byAuthor.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 3)
+      .map(([name, lines]) => ({ name, lines, share: lines / blame.total }));
+    const topCommits = [...blame.byCommit.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 3)
+      .map(([hash, lines]) => ({ commit: byHash.get(hash) ?? { hash, short: hash.slice(0, 7), subject: "(outside the sampled history)" }, lines, share: lines / blame.total }));
+    ownership = { total: blame.total, topAuthors, topCommits };
+  }
+
+  return {
+    file,
+    lineCount,
+    commitCount: commits.length,
+    allCommits: commits,
+    first,
+    last,
+    ageDays,
+    quietDays,
+    authors,
+    reverts,
+    fixes,
+    refs: [...refs.entries()].map(([number, cs]) => ({ number, commits: cs })).sort((a, b) => Number(b.number) - Number(a.number)),
+    coChanged,
+    bursts: notableBursts,
+    notes,
+    ownership,
+  };
+}
+
+/** Re-join hard-wrapped paragraphs; list items stay separate. */
+export function unwrap(body) {
+  const out = [];
+  for (const para of body.split(/\n\s*\n/)) {
+    let cur = "";
+    for (const line of para.split("\n")) {
+      const t = line.trim();
+      if (!t) continue;
+      if (/^([-*•]|\d+[.)])\s/.test(t) || !cur) {
+        if (cur) out.push(cur);
+        cur = t;
+      } else cur += " " + t;
+    }
+    if (cur) out.push(cur);
+  }
+  return out;
+}
+
+/** Paths this file lived at before, newest first, from rename records. */
+export function renameTrail(commits, file) {
+  const trail = [];
+  let current = file;
+  for (const c of commits) {
+    const r = c.renames?.find((x) => x.to === current);
+    if (r) {
+      trail.push(r.from);
+      current = r.from;
+    }
+  }
+  return trail;
+}

package/src/cli.js

@@ -0,0 +1,153 @@
+import { resolve, relative, sep, isAbsolute } from "node:path";
+import { existsSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { analyze, renameTrail } from "./analyze.js";
+import { render } from "./render.js";
+import { GitError, blame, fileLog, isTracked, lineCount, rangeLog, remoteWebUrl, repoRoot } from "./git.js";
+
+const { version } = createRequire(import.meta.url)("../package.json");
+
+export const HELP = `git-backstory ${version} — the backstory of a file, in one page, for whoever has to change it next.
+
+Usage
+  git-backstory <path>              brief for a file
+  git-backstory <path>:<line>       brief for one line
+  git-backstory <path>:<from>-<to>  brief for a line range
+  git-backstory <path> --json       the facts as JSON instead of markdown
+
+Options
+  --max <n>       commits to sample (default 200)
+  --since <date>  only commits after this date, e.g. 2025-01-01 or "6 months ago"
+  --out <file>    write the brief to a file instead of stdout
+  --no-links      plain hashes, no web links
+  --version, --help
+
+Reads git only (log, blame, show). Never writes to the repository, never
+touches the network. Zero dependencies.`;
+
+export function parseArgs(argv) {
+  const o = { target: null, json: false, max: 200, since: null, out: null, links: true, help: false, version: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") o.help = true;
+    else if (a === "--version" || a === "-v") o.version = true;
+    else if (a === "--json") o.json = true;
+    else if (a === "--no-links") o.links = false;
+    else if (a === "--max") o.max = Number(argv[++i]);
+    else if (a.startsWith("--max=")) o.max = Number(a.slice(6));
+    else if (a === "--since") o.since = argv[++i];
+    else if (a.startsWith("--since=")) o.since = a.slice(8);
+    else if (a === "--out") o.out = argv[++i];
+    else if (a.startsWith("--out=")) o.out = a.slice(6);
+    else if (a.startsWith("-")) throw new UsageError(`Unknown option: ${a}`);
+    else if (o.target) throw new UsageError("Only one path at a time.");
+    else o.target = a;
+  }
+  if (!Number.isInteger(o.max) || o.max < 1) throw new UsageError("--max must be a positive integer.");
+  return o;
+}
+
+export class UsageError extends Error {}
+
+/** Real path of the deepest existing ancestor, with the missing tail re-attached. */
+function canonical(p) {
+  const missing = [];
+  let cur = p;
+  while (!existsSync(cur)) {
+    const parent = resolve(cur, "..");
+    if (parent === cur) return p;
+    missing.unshift(cur.slice(parent.length).replace(/^[\\/]/, ""));
+    cur = parent;
+  }
+  return resolve(realpathSync.native(cur), ...missing);
+}
+
+/** "src/a.ts:10-20" -> { file, range } ; Windows drive letters are left alone. */
+export function splitTarget(target) {
+  const m = target.match(/^(.*?):(\d+)(?:-(\d+))?$/);
+  if (!m || /^[A-Za-z]:$/.test(m[1])) return { file: target, range: null };
+  const start = Number(m[2]);
+  const end = m[3] ? Number(m[3]) : start;
+  if (start < 1 || end < start) throw new UsageError(`Bad line range: ${target}`);
+  return { file: m[1], range: { start, end } };
+}
+
+export function brief(targetArg, opts, cwd = process.cwd()) {
+  const { file: rawFile, range } = splitTarget(targetArg);
+  // Compare canonical paths: macOS puts temp dirs behind a /var -> /private/var
+  // symlink and Windows hands out 8.3 short names, while git reports real paths.
+  const abs = canonical(resolve(cwd, rawFile));
+  const root = canonical(repoRoot(existsSync(abs) && statSync(abs).isDirectory() ? abs : resolve(abs, "..")));
+  let file = relative(root, abs).split(sep).join("/");
+  if (!file || file.startsWith("..") || isAbsolute(file)) throw new UsageError(`${rawFile} is outside the repository at ${root}.`);
+
+  if (existsSync(abs) && statSync(abs).isDirectory()) throw new UsageError(`${rawFile} is a directory. git-backstory works on one file.`);
+  if (!isTracked(root, file) && !existsSync(abs)) {
+    // Allow briefs on deleted files: the log still exists.
+  }
+
+  const commits = range ? rangeLog(root, file, range.start, range.end, { max: opts.max }) : fileLog(root, file, { max: opts.max, since: opts.since });
+  const b = isTracked(root, file) ? blame(root, file, range ? { start: range.start, end: range.end } : {}) : null;
+  const lines = isTracked(root, file) ? lineCount(root, file) : null;
+  const facts = analyze(commits, { file, blame: b, lineCount: lines });
+  facts.sampleLimit = opts.max;
+  const previousPaths = range ? [] : renameTrail(commits, file);
+  const webUrl = opts.links ? remoteWebUrl(root) : null;
+  return { facts, markdown: render(facts, { webUrl, range, previousPaths }), root, file, range };
+}
+
+export async function run(argv = process.argv.slice(2), io = { stdout: process.stdout, stderr: process.stderr }) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (e) {
+    if (e instanceof UsageError) {
+      io.stderr.write(`${e.message}\n\n${HELP}\n`);
+      return 2;
+    }
+    throw e;
+  }
+  if (opts.version) return io.stdout.write(`${version}\n`), 0;
+  if (opts.help || !opts.target) return io.stdout.write(`${HELP}\n`), opts.help ? 0 : 2;
+
+  try {
+    const { facts, markdown } = brief(opts.target, opts);
+    const out = opts.json ? JSON.stringify(toJson(facts), null, 2) + "\n" : markdown;
+    if (opts.out) {
+      writeFileSync(opts.out, out);
+      io.stderr.write(`Wrote ${opts.out}\n`);
+    } else io.stdout.write(out);
+    return 0;
+  } catch (e) {
+    if (e instanceof UsageError || e instanceof GitError) {
+      io.stderr.write(`git-backstory: ${e.message}\n`);
+      return e.code ?? 2;
+    }
+    throw e;
+  }
+}
+
+function toJson(f) {
+  const c = (x) => x && { hash: x.hash, short: x.short, author: x.author, date: x.date, subject: x.subject };
+  return {
+    file: f.file,
+    lineCount: f.lineCount,
+    commitCount: f.commitCount,
+    first: c(f.first),
+    last: c(f.last),
+    ageDays: f.ageDays,
+    quietDays: f.quietDays,
+    authors: f.authors,
+    reverts: f.reverts.map((r) => ({ revert: c(r.revert), target: c(r.target) })),
+    fixes: f.fixes.map(c),
+    refs: f.refs.map((r) => ({ number: r.number, commits: r.commits.map((x) => x.short) })),
+    coChanged: f.coChanged,
+    bursts: f.bursts.map((b) => b.map(c)),
+    notes: f.notes.map((n) => ({ line: n.line, commit: n.commit.short })),
+    ownership: f.ownership && {
+      total: f.ownership.total,
+      topAuthors: f.ownership.topAuthors,
+      topCommits: f.ownership.topCommits.map((x) => ({ commit: c(x.commit), lines: x.lines, share: x.share })),
+    },
+  };
+}

package/src/git.js

@@ -0,0 +1,147 @@
+// Thin, read-only wrapper around the git CLI. Every command here is a read:
+// log, blame, show, rev-parse, ls-files, remote. Nothing writes to the repo.
+
+import { spawnSync } from "node:child_process";
+
+export class GitError extends Error {
+  constructor(message, code = 1) {
+    super(message);
+    this.name = "GitError";
+    this.code = code;
+  }
+}
+
+export function git(cwd, args, { allowFail = false } = {}) {
+  const r = spawnSync(
+    "git",
+    ["-c", "core.quotepath=off", "-c", "log.showSignature=false", "-c", "color.ui=never", ...args],
+    { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024, windowsHide: true },
+  );
+  if (r.error) {
+    if (r.error.code === "ENOENT") throw new GitError("git is not installed or not on PATH.", 2);
+    throw new GitError(r.error.message, 2);
+  }
+  if (r.status !== 0 && !allowFail) throw new GitError((r.stderr || "git failed").trim(), 1);
+  return r.stdout;
+}
+
+export function repoRoot(cwd) {
+  const out = git(cwd, ["rev-parse", "--show-toplevel"], { allowFail: true }).trim();
+  if (!out) throw new GitError(`Not inside a git repository: ${cwd}`, 1);
+  return out;
+}
+
+/** Web base URL for the origin remote on GitHub/GitLab/Bitbucket, or null. */
+export function remoteWebUrl(cwd) {
+  const url = git(cwd, ["remote", "get-url", "origin"], { allowFail: true }).trim();
+  if (!url) return null;
+  const m = url.match(/(?:[@/])(github\.com|gitlab\.com|bitbucket\.org)[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i);
+  if (!m) return null;
+  return `https://${m[1].toLowerCase()}/${m[2]}/${m[3]}`;
+}
+
+// Unit/record separators keep multi-line bodies unambiguous.
+const US = "\u001f";
+const RS = "\u001e";
+const FORMAT = ["%H", "%h", "%an", "%aI", "%P", "%s", "%b"].join(US) + RS;
+
+/**
+ * Commits touching `file` (following renames), newest first.
+ * Each: { hash, short, author, date, parents[], subject, body, files[] }
+ * `files` lists every path changed in that commit, for co-change analysis.
+ */
+export function fileLog(cwd, file, { max = 200, since = null } = {}) {
+  const args = ["log", `--max-count=${max}`, "--follow"];
+  if (since) args.push(`--since=${since}`);
+  const commits = parseLog(git(cwd, ["log", ...args.slice(1), `--format=${FORMAT}`, "--", file], { allowFail: true }));
+  if (!commits.length) return commits;
+  // A pathspec limits --name-status to the followed file, so list every
+  // changed path in a second pass over exactly these commits.
+  const status = git(cwd, ["log", "--no-walk=unsorted", "--name-status", "--format=%x01%H", ...commits.map((c) => c.hash)], { allowFail: true });
+  const byHash = new Map();
+  for (const chunk of status.split("\u0001")) {
+    const lines = chunk.split("\n").map((s) => s.trimEnd()).filter(Boolean);
+    if (!lines.length) continue;
+    const files = [];
+    const renames = [];
+    for (const l of lines.slice(1)) {
+      const parts = l.split("\t");
+      const code = parts[0];
+      if (/^R/.test(code) && parts.length >= 3) {
+        renames.push({ from: parts[1], to: parts[2] });
+        files.push(parts[2]);
+      } else if (parts[1]) files.push(parts[parts.length - 1]);
+    }
+    byHash.set(lines[0], { files, renames });
+  }
+  for (const c of commits) {
+    const e = byHash.get(c.hash) ?? { files: [], renames: [] };
+    c.files = e.files;
+    c.renames = e.renames;
+  }
+  return commits;
+}
+
+/** Commits that touched a line range, via `git log -L`. git forbids --follow with -L. */
+export function rangeLog(cwd, file, start, end, { max = 50 } = {}) {
+  const out = git(cwd, ["log", `--max-count=${max}`, "--no-patch", `-L${start},${end}:${file}`, `--format=${FORMAT}`], {
+    allowFail: true,
+  });
+  return parseLog(out).map((c) => ({ ...c, files: [], renames: [] }));
+}
+
+function parseLog(out) {
+  const commits = [];
+  for (const chunk of out.split(RS)) {
+    const text = chunk.replace(/^\s+/, "");
+    if (!text) continue;
+    const [hash, short, author, date, parents, subject, body = ""] = text.split(US);
+    if (!/^[0-9a-f]{40}$/.test(hash)) continue;
+    commits.push({
+      hash,
+      short,
+      author,
+      date,
+      parents: parents ? parents.split(" ").filter(Boolean) : [],
+      subject: subject ?? "",
+      body: body.trim(),
+      files: [],
+      renames: [],
+    });
+  }
+  return commits;
+}
+
+/** Blame summary: how many current lines each commit and each author owns. */
+export function blame(cwd, file, { start = null, end = null } = {}) {
+  const args = ["blame", "--line-porcelain"];
+  if (start != null) args.push("-L", `${start},${end ?? start}`);
+  args.push("--", file);
+  const out = git(cwd, args, { allowFail: true });
+  const byCommit = new Map();
+  const byAuthor = new Map();
+  let total = 0;
+  let current = null;
+  for (const line of out.split("\n")) {
+    const head = line.match(/^([0-9a-f]{40}) \d+ \d+(?: \d+)?$/);
+    if (head) {
+      current = head[1];
+      total += 1;
+      byCommit.set(current, (byCommit.get(current) ?? 0) + 1);
+    } else if (current && line.startsWith("author ")) {
+      const a = line.slice(7);
+      byAuthor.set(a, (byAuthor.get(a) ?? 0) + 1);
+    }
+  }
+  return { total, byCommit, byAuthor };
+}
+
+export function isTracked(cwd, file) {
+  return git(cwd, ["ls-files", "--error-unmatch", "--", file], { allowFail: true }).trim().length > 0;
+}
+
+export function lineCount(cwd, file) {
+  const out = git(cwd, ["show", `HEAD:${file}`], { allowFail: true });
+  if (!out) return null;
+  return out.split("\n").length - (out.endsWith("\n") ? 1 : 0);
+}

package/src/render.js

@@ -0,0 +1,113 @@
+// Pure: facts in, markdown out. Short on purpose — an agent reads all of it.
+
+export function render(a, { webUrl = null, range = null, previousPaths = [] } = {}) {
+  const L = [];
+  const link = (c) => (webUrl ? `[\`${c.short}\`](${webUrl}/commit/${c.hash})` : `\`${c.short}\``);
+  const issue = (n) => (webUrl ? `[#${n}](${webUrl}/issues/${n})` : `#${n}`);
+  const when = (c) => c.date.slice(0, 10);
+  const subj = (c) => c.subject.replace(/\s+/g, " ").trim();
+  const title = range ? `${a.file}:${range.start}${range.end !== range.start ? `-${range.end}` : ""}` : a.file;
+
+  L.push(`# History brief: \`${title}\``, "");
+
+  if (a.commitCount === 0) {
+    L.push(range ? "No commits touched this range." : "No history for this path. Is it tracked, and is the path relative to the repository root?");
+    return L.join("\n") + "\n";
+  }
+
+  // Summary line.
+  const parts = [];
+  parts.push(`${a.commitCount} commit${a.commitCount === 1 ? "" : "s"}`);
+  const ago = (d) => (d < 1 ? "today" : `${humanDays(d)} ago`);
+  if (a.ageDays != null) parts.push(`first ${when(a.first)} (${ago(a.ageDays)})`);
+  if (a.quietDays != null) parts.push(`last ${when(a.last)} (${ago(a.quietDays)})`);
+  parts.push(`${a.authors.length} author${a.authors.length === 1 ? "" : "s"}`);
+  if (a.lineCount != null && !range) parts.push(`${a.lineCount} lines now`);
+  L.push(parts.join(" · "), "");
+  if (previousPaths.length) L.push(`Previously at: ${previousPaths.map((p) => `\`${p}\``).join(", ")}`, "");
+
+  // What to be careful about: the section that earns the file.
+  const careful = [];
+  for (const { revert, target } of a.reverts) {
+    careful.push(
+      target
+        ? `${link(revert)} (${when(revert)}) reverted ${link(target)} "${subj(target)}". Whatever that change did was not safe here; read both before trying it again.`
+        : `${link(revert)} (${when(revert)}) is a revert: "${subj(revert)}".`,
+    );
+  }
+  for (const b of a.bursts.slice(0, 2)) {
+    const from = when(b[0]);
+    const to = when(b[b.length - 1]);
+    const shown = b.slice(0, 5).map(link).join(", ") + (b.length > 5 ? `, +${b.length - 5} more` : "");
+    careful.push(`${b.length} commits between ${from} and ${to} (${shown}): several attempts in a short window, so the first one didn't hold.`);
+  }
+  if (a.fixes.length) {
+    const shown = a.fixes.slice(0, 5);
+    careful.push(`Fix-shaped commits (${a.fixes.length}): ${shown.map((c) => `${link(c)} "${subj(c)}"`).join("; ")}${a.fixes.length > shown.length ? "; …" : ""}.`);
+  }
+  if (careful.length) {
+    L.push("## Be careful", "");
+    for (const c of careful) L.push(`- ${c}`);
+    L.push("");
+  }
+
+  // Reasons the authors wrote down.
+  if (a.notes.length) {
+    L.push("## Reasons on record", "");
+    for (const { commit, line } of a.notes.slice(0, 8)) L.push(`- ${line} — ${link(commit)}, ${when(commit)}`);
+    L.push("");
+  }
+
+  // Co-change coupling.
+  if (a.coChanged.length) {
+    L.push("## Usually changes together with", "");
+    for (const x of a.coChanged) L.push(`- \`${x.path}\` — ${x.count} of the sampled commits (${Math.round(x.share * 100)}%)`);
+    L.push("", "If you change this file, check whether those need the same change.", "");
+  }
+
+  // Issues / PRs.
+  if (a.refs.length) {
+    const shown = a.refs.slice(0, 10);
+    L.push("## Referenced issues and PRs", "", shown.map((r) => `${issue(r.number)} (${r.commits.length})`).join(", "), "");
+  }
+
+  // Ownership.
+  if (a.ownership) {
+    const o = a.ownership;
+    const people = o.topAuthors.map((x) => `${x.name} ${Math.round(x.share * 100)}%`).join(", ");
+    L.push("## Who to ask", "", `Current lines by author: ${people}.`);
+    const big = o.topCommits[0];
+    if (big && big.share >= 0.5) L.push(`${Math.round(big.share * 100)}% of the current lines come from one commit: ${link(big.commit)} "${subj(big.commit)}".`);
+    L.push("");
+  } else if (a.authors.length) {
+    L.push("## Who to ask", "", a.authors.slice(0, 3).map((x) => `${x.name} (${x.count})`).join(", "), "");
+  }
+
+  // Timeline, newest first, compact.
+  L.push("## Timeline", "");
+  const tl = [...a.reverts.map((r) => r.revert), ...a.fixes, a.first, a.last]
+    .filter(Boolean)
+    .filter((c, i, arr) => arr.findIndex((x) => x.hash === c.hash) === i)
+    .sort((x, y) => new Date(y.date) - new Date(x.date))
+    .slice(0, 12);
+  // Fill with recent commits if the notable ones are few.
+  if (tl.length < 8) {
+    const recent = [...a.allCommits ?? []].slice(0, 8 - tl.length);
+    for (const c of recent) if (!tl.some((x) => x.hash === c.hash)) tl.push(c);
+    tl.sort((x, y) => new Date(y.date) - new Date(x.date));
+  }
+  for (const c of tl) L.push(`- ${when(c)} ${link(c)} ${subj(c)} — ${c.author}`);
+  L.push("");
+
+  const sampled = a.sampleLimit && a.commitCount >= a.sampleLimit ? ` Sampled the latest ${a.sampleLimit} commits; pass --max for more.` : "";
+  L.push(`_Generated by git-backstory from \`git log\` and \`git blame\`.${sampled}_`);
+  return L.join("\n") + "\n";
+}
+
+export function humanDays(d) {
+  if (d < 1) return "today";
+  if (d < 14) return `${d} day${d === 1 ? "" : "s"}`;
+  if (d < 60) return `${Math.round(d / 7)} weeks`;
+  if (d < 730) return `${Math.round(d / 30)} months`;
+  return `${(d / 365).toFixed(1)} years`;
+}