@ok-ggwp/git-gloss 0.2.0 → 0.3.0

package/README.md

@@ -23,6 +23,7 @@ git gloss show [<commit>|<range>]     summary: one line per group, alternatives,
       --diff                          ...every group's details and code
       --only speculative,incidental   ...just the parts you might cut
 git gloss html [<commit>|<range>]     self-contained HTML view, of one commit or a branch (--open, -o <file>)
+git gloss ary [--port <n>] [--no-open] browse branches, commits and wip in a local web page (see "Browsing")
 git gloss why <file>:<line>[-<end>]   explain why code exists (via blame), looking past mechanical edits
       --history                       ...every commit that changed the lines, newest first
       --json                          ...for agents, with risks and rejected alternatives
@@ -63,10 +64,25 @@ npm install -D @ok-ggwp/git-gloss
 npx git-gloss init --hooks
 ```
 
-The hooks run `git gloss`, so it must be on PATH wherever git runs; with a project install, that means running git from a shell where `node_modules/.bin` is on PATH, or installing it globally as well.
+The hooks run `git gloss`, so it must be on PATH wherever git runs. A project install isn't, by default: a GUI git client, or a shell that didn't run `pnpm`/`npm` scripts, won't find it. See [Project installs](#project-installs) for how to keep the team on one version anyway.
 
 To work on git-gloss itself: clone it, `npm install`, `npm link`, `npm test`. From a checkout, on Node 22.18+, the TypeScript source runs directly; on older versions the launcher runs `dist/`, which `npm install` builds (and `npm run build` rebuilds after changes). The tests need Node 23.6+.
 
+### Project installs
+
+A project install (`npm install -D`) keeps every teammate on the same version, which matters because glosses and reviews are shared git notes that each copy reads and writes. The cost is that `git gloss` is then on PATH only inside a shell that has `node_modules/.bin` on it. Two ways to deal with that:
+
+- **Put it on PATH in the hooks.** Add one line near the top of each hook that calls `git gloss` (`pre-push`, `post-commit`, `post-rewrite`), with the hooks kept in a tracked folder (for example, `.githooks/`, set with `git config core.hooksPath .githooks`):
+
+  ```sh
+  PATH="$PWD/node_modules/.bin:$PATH"
+  ```
+
+  Git runs hooks from the top of the working tree, so `$PWD` is that directory. In a monorepo where the install lives in a subfolder (`web/node_modules/.bin`), use that path instead. On Windows, use `$PWD` rather than `git rev-parse --show-toplevel`, which returns a `C:/…` path that Git for Windows' shell can't put on PATH.
+- **Run the setup from `prepare`.** A `prepare` script in the package that owns `node_modules` can set `core.hooksPath` and run `git gloss init --hooks` on every install, so nobody has to remember it in each clone. Skip it in CI, and make it never fail the install. Note that pnpm doesn't run `prepare` when `node_modules` is already up to date, so an existing clone needs `pnpm run prepare` once.
+
+Either way, the hooks never block a commit or push. Without `git gloss` on PATH they print an error and glosses aren't adopted, carried or synced, so check that `git gloss init` prints no warning after changing it. The Claude Code skill can run the tool through the project install too; see "Calling git-gloss" in the skill.
+
 ### Setting up a repo
 
 In each repo you use it in:
@@ -149,6 +165,12 @@ Give a range (`git gloss html main..feature --open`) for a branch or PR view: ev
 
 All gloss and diff text is rendered as text, and a Content-Security-Policy with a per-page nonce blocks any script the page didn't generate.
 
+## Browsing
+
+`git gloss ary` starts a small web server and opens it in your browser, so you can explore glosses without working out commits, branches and ranges on the command line. Pick a branch and a branch to compare it with (the repo's `main` or `master` by default); each picker has a search box, for repos with many branches. Then click a commit, or "Whole branch" for the range view. Each commit shows its subject (up to two lines) and whether it has a gloss and a review, and a search box above the list finds commits by message or author (case-insensitive, plain text). Searching covers the whole selected branch, not only the commits loaded so far. Your uncommitted work appears at the top once it has been snapshotted (`git gloss hunks wip`). To look at anything else, such as `HEAD~3` or `release..main`, type it into the revision box. As everywhere in git-gloss, `wip` there means the snapshot of uncommitted work, so to view a branch or tag called `wip`, type `heads/wip` or `tags/wip`. Each selection is the page `git gloss html` writes, regenerated on every load, so Reload picks up new glosses and reviews. The address bar keeps the selection, so a reload returns to it (with a random port, a bookmark lasts only until you stop the server; pass `--port` for a stable address).
+
+It serves one repository, the one you run it in, until you press Ctrl-C. It listens on 127.0.0.1 only, on a free port (or `--port`), only answers requests addressed to that host name, and never writes anything: it doesn't take snapshots or change notes. A page shows at most 200 commits; pick a narrower range for more. `--no-open` doesn't launch a browser.
+
 ## Caveats
 
 - Carrying a gloss onto a server-side squash needs the original commits in your repository; usually the author has them. If a squash merge resolved conflicts or changed much of the code, it may not reach the 80% match; run `git gloss carry <branch commits> --to <squash>`.

package/dist/ary/browse.js

@@ -0,0 +1,80 @@
+import { basename } from 'node:path';
+import { NOTES_REF, WIP_NOTES_REF, WIP_REF, git, gitTry, wipStaleness } from '../git.js';
+import { REVIEWS_REF } from '../reviews.js';
+// The commits a notes ref has notes on ("<note> <commit>" per line). A missing
+// ref is no notes.
+function notedCommits(ref) {
+    const lines = (gitTry(['notes', '--ref', ref, 'list']) ?? '').split('\n');
+    return new Set(lines.filter(Boolean).map((l) => l.split(' ')[1]));
+}
+function refList(namespace) {
+    return git(['for-each-ref', '--sort=-committerdate', '--format=%(refname)%00%(refname:short)%00%(committerdate:relative)%00%(subject)', namespace])
+        .split('\n')
+        .filter(Boolean)
+        .map((l) => l.split('\0'))
+        // refs/remotes/<remote>/HEAD is a pointer to another branch, not a branch.
+        .filter(([full]) => !full.endsWith('/HEAD'))
+        .map(([, name, date, subject]) => ({ name, date, subject }));
+}
+export function listRefs() {
+    const branches = refList('refs/heads');
+    const remotes = refList('refs/remotes');
+    const names = new Set([...branches, ...remotes].map((b) => b.name));
+    const wipSha = gitTry(['rev-parse', '--verify', '--quiet', WIP_REF])?.trim();
+    let stale = null;
+    if (wipSha) {
+        try {
+            stale = wipStaleness(wipSha);
+        }
+        catch {
+            // Staleness is advice; the snapshot is still viewable without it.
+        }
+    }
+    return {
+        repo: basename(git(['rev-parse', '--show-toplevel']).trim()),
+        current: gitTry(['symbolic-ref', '--short', '--quiet', 'HEAD'])?.trim() || null,
+        branches,
+        remotes,
+        defaultBase: ['main', 'master', 'origin/main', 'origin/master'].find((n) => names.has(n)) ?? null,
+        wip: wipSha ? { sha: wipSha, glossed: notedCommits(WIP_NOTES_REF).has(wipSha), stale } : null,
+    };
+}
+// Newest first: the commits of `head`, or only those not in `base` when given.
+// `query` keeps the commits whose message or author contains it (any case).
+export function listLog(head, base, limit, skip, query = '') {
+    const range = base ? `${base}..${head}` : head;
+    const format = '--format=%H%x00%an%x00%aI%x00%s%x00%P';
+    let out;
+    if (query) {
+        // git ANDs --grep with --author, so ask for each on its own and merge, then
+        // list the union by commit date (what --no-walk=sorted gives, which can
+        // differ from the order of an unfiltered log when dates are skewed).
+        const shas = new Set();
+        for (const filter of ['--grep', '--author']) {
+            const found = git(['log', '--format=%H', '--regexp-ignore-case', '--fixed-strings', `${filter}=${query}`, '--end-of-options', range, '--']);
+            for (const sha of found.split('\n').filter(Boolean))
+                shas.add(sha);
+        }
+        // No -n or --skip here: git then walks on to the parents, so page by hand.
+        out = shas.size
+            ? git(['log', '--no-walk=sorted', '--stdin', format], [...shas].join('\n') + '\n').split('\n').slice(skip, skip + limit + 1).join('\n')
+            : '';
+    }
+    else {
+        // One more than asked for, to know whether there are more.
+        out = git(['log', format, '-n', String(limit + 1), '--skip', String(skip), '--end-of-options', range, '--']);
+    }
+    const glossed = notedCommits(NOTES_REF);
+    const reviewed = notedCommits(REVIEWS_REF);
+    const rows = out.split('\n').filter(Boolean).map((l) => l.split('\0'));
+    return {
+        commits: rows.slice(0, limit).map(([sha, author, date, subject, parents]) => ({
+            sha, author, date, subject,
+            merge: parents.includes(' '),
+            glossed: glossed.has(sha),
+            reviewed: reviewed.has(sha),
+        })),
+        more: rows.length > limit,
+        total: base && !query ? Number(git(['rev-list', '--count', '--end-of-options', range, '--']).trim()) : null,
+    };
+}

package/dist/ary/client.js

@@ -0,0 +1,401 @@
+// The ary shell: pick a branch, a base to compare it with, and a commit (or the
+// whole branch), and the chosen view loads in the frame. Text only goes
+// through textContent; nothing from the repo is parsed as HTML.
+(function () {
+  'use strict'
+  var app = document.getElementById('app')
+  var PAGE = 100
+
+  // What is selected. head/base choose which commits are listed; rev is what
+  // the frame shows (a sha, "wip", a range, or anything typed in).
+  var state = { head: null, base: null, rev: null, q: '' }
+  var refs = null
+  var log = { commits: [], more: false, total: null }
+  var logError = null
+  var parts = {}
+
+  function el(tag, cls, text) {
+    var e = document.createElement(tag)
+    if (cls) e.className = cls
+    if (text !== undefined && text !== null) e.textContent = String(text)
+    return e
+  }
+  function add(parent) {
+    for (var i = 1; i < arguments.length; i++) if (arguments[i]) parent.appendChild(arguments[i])
+    return parent
+  }
+  function plural(n, word) { return n + ' ' + word + (n === 1 ? '' : 's') }
+  function api(path) {
+    return fetch(path).then(function (r) {
+      return r.json().then(function (body) {
+        if (!r.ok) throw new Error(body.error || r.statusText)
+        return body
+      })
+    })
+  }
+
+  // ---- location: the selection is kept in the hash, so reload and links work ----
+  function saveHash() {
+    var p = new URLSearchParams()
+    if (state.rev) p.set('rev', state.rev)
+    if (state.head) p.set('head', state.head)
+    if (state.base) p.set('base', state.base)
+    history.replaceState(null, '', '#' + p.toString())
+  }
+  function readHash() {
+    var p = new URLSearchParams(location.hash.slice(1))
+    return { rev: p.get('rev'), head: p.get('head'), base: p.get('base') }
+  }
+
+  // ---- sidebar ----
+  // A branch picker with a search box: a repo can have hundreds of branches,
+  // too many to scan in a <select>. Matching is case-insensitive and every
+  // space-separated word must appear in the name.
+  var SHOWN = 200
+  function picker(onPick) {
+    var root = el('div', 'combo')
+    var button = el('button', 'combo-btn')
+    button.type = 'button'
+    button.setAttribute('aria-haspopup', 'listbox')
+    var panel = el('div', 'combo-panel')
+    panel.hidden = true
+    var input = el('input')
+    input.type = 'search'
+    input.spellcheck = false
+    input.placeholder = 'Search branches…'
+    input.setAttribute('aria-label', 'Search branches')
+    var list = el('div', 'combo-list')
+    list.setAttribute('role', 'listbox')
+    add(panel, input, list)
+    add(root, button, panel)
+
+    var groups = []
+    var noneLabel = null
+    var value = null
+    var items = [] // the rows now shown: { value, node }
+    var active = 0
+
+    function matches(name, words) {
+      var n = name.toLowerCase()
+      return words.every(function (w) { return n.indexOf(w) >= 0 })
+    }
+    function paint() {
+      items.forEach(function (it, i) { it.node.classList.toggle('active', i === active) })
+      if (items[active]) items[active].node.scrollIntoView({ block: 'nearest' })
+    }
+    function render() {
+      var words = input.value.toLowerCase().split(/\s+/).filter(Boolean)
+      list.textContent = ''
+      items = []
+      var shown = 0
+      var hidden = 0
+      function item(label, v) {
+        var node = el('button', 'combo-item', label)
+        node.type = 'button'
+        node.setAttribute('role', 'option')
+        node.setAttribute('aria-selected', String(v === value))
+        node.addEventListener('click', function () { pick(v) })
+        items.push({ value: v, node: node })
+        return node
+      }
+      if (noneLabel && !words.length) list.appendChild(item(noneLabel, null))
+      groups.forEach(function (g) {
+        var found = g.names.filter(function (n) { return matches(n, words) })
+        var room = found.slice(0, Math.max(0, SHOWN - shown))
+        hidden += found.length - room.length
+        shown += room.length
+        if (!room.length) return
+        add(list, add(el('div', 'combo-group', g.label), el('span', 'count', found.length)))
+        room.forEach(function (n) { list.appendChild(item(n, n)) })
+      })
+      if (hidden) add(list, el('div', 'combo-more', hidden + ' more: keep typing to narrow the list'))
+      if (!items.length) add(list, el('div', 'combo-more', 'No branches match.'))
+      // Start on the current value, or on the first match when searching.
+      var at = words.length ? -1 : items.findIndex(function (it) { return it.value === value })
+      active = at >= 0 ? at : 0
+      paint()
+    }
+    function open() {
+      panel.hidden = false
+      button.setAttribute('aria-expanded', 'true')
+      input.value = ''
+      render()
+      input.focus()
+    }
+    function close() {
+      panel.hidden = true
+      button.setAttribute('aria-expanded', 'false')
+    }
+    function pick(v) {
+      close()
+      button.focus()
+      if (v !== value) onPick(v)
+    }
+    button.addEventListener('click', function () { if (panel.hidden) open(); else close() })
+    input.addEventListener('input', render)
+    input.addEventListener('keydown', function (ev) {
+      if (ev.key === 'ArrowDown' || ev.key === 'ArrowUp') {
+        ev.preventDefault()
+        if (items.length) active = (active + (ev.key === 'ArrowDown' ? 1 : items.length - 1)) % items.length
+        paint()
+      } else if (ev.key === 'Enter') {
+        ev.preventDefault()
+        if (items[active]) pick(items[active].value)
+      } else if (ev.key === 'Escape') {
+        ev.preventDefault()
+        close()
+        button.focus()
+      }
+    })
+    document.addEventListener('mousedown', function (ev) { if (!panel.hidden && !root.contains(ev.target)) close() })
+
+    return {
+      root: root,
+      // Local and remote branches, and what choosing "no branch" is called (if allowed).
+      setOptions: function (g, none) { groups = g; noneLabel = none },
+      setValue: function (v) {
+        value = v
+        button.textContent = v || noneLabel || 'choose a branch'
+        button.title = button.textContent
+      },
+    }
+  }
+
+  function branchGroups() {
+    return [
+      { label: 'Local branches', names: refs.branches.map(function (b) { return b.name }) },
+      { label: 'Remote branches', names: refs.remotes.map(function (b) { return b.name }) },
+    ]
+  }
+
+  // One entry in the list: the title gets the full width (two lines at most),
+  // with the details and status marks on a line below it.
+  function row(title, details, marks, current, onClick) {
+    var b = el('button', 'row')
+    b.type = 'button'
+    b.setAttribute('aria-current', String(current))
+    b.title = title
+    add(b, el('div', 'subject', title))
+    var meta = el('div', 'meta')
+    details.forEach(function (d) { meta.appendChild(d) })
+    add(meta, add(el('span', 'marks'), marks[0], marks[1], marks[2]))
+    add(b, meta)
+    b.addEventListener('click', onClick)
+    return b
+  }
+  function mark(kind, text, tip) {
+    var m = el('span', 'mark ' + kind, text)
+    if (tip) m.title = tip
+    return m
+  }
+  function glossMark(glossed) {
+    return glossed ? mark('glossed', '● glossed', 'This commit has a gloss') : mark('none', '○ no gloss', 'This commit has no gloss')
+  }
+
+  function renderList() {
+    var list = parts.list
+    list.textContent = ''
+    if (refs.wip) {
+      add(list, el('h2', null, 'Uncommitted work'))
+      var w = refs.wip
+      add(list, row('wip snapshot', [el('span', null, w.stale || 'the latest snapshot of your working tree')],
+        [glossMark(w.glossed), w.stale ? mark('warn', 'stale', w.stale) : null], state.rev === 'wip', function () { select('wip') }))
+    }
+    add(list, el('h2', null, state.head ? 'Commits on ' + state.head : 'Commits'))
+    if (logError) { add(list, el('p', 'error', logError)); return }
+    // A search narrows the list to some commits, so it isn't the whole branch.
+    if (state.base && state.head && log.commits.length && !state.q) {
+      var range = state.base + '..' + state.head
+      add(list, row('Whole branch', [el('span', null, range + ' · ' + plural(log.total === null ? log.commits.length : log.total, 'commit'))], [], state.rev === range, function () { select(range) }))
+    }
+    if (!log.commits.length) {
+      add(list, el('p', 'empty', state.q ? 'No commits match “' + state.q + '”.' : state.base ? 'No commits beyond ' + state.base + '.' : 'No commits.'))
+    }
+    log.commits.forEach(function (c) {
+      add(list, row(c.subject,
+        [el('span', 'sha', c.sha.slice(0, 7)), el('span', null, ' · ' + c.author + ' · ' + new Date(c.date).toLocaleDateString())],
+        c.merge ? [mark('none', 'merge')] : [glossMark(c.glossed), c.reviewed ? mark('reviewed', '✓ reviewed', 'This commit has a recorded review') : null],
+        state.rev === c.sha, function () { select(c.sha) }))
+    })
+    if (log.more) {
+      var more = el('button', 'btn more', 'Load more')
+      more.type = 'button'
+      more.addEventListener('click', function () { loadLog(true) })
+      add(list, more)
+    }
+  }
+
+  function renderSide() {
+    parts.head.setOptions(branchGroups(), null)
+    parts.head.setValue(state.head)
+    parts.base.setOptions(branchGroups(), '(none: all of the branch’s history)')
+    parts.base.setValue(state.base)
+    parts.rev.value = state.rev && state.rev !== 'wip' ? state.rev : ''
+    renderList()
+  }
+
+  // ---- viewer ----
+  function renderViewer() {
+    var v = parts.viewer
+    v.textContent = ''
+    if (!state.rev) {
+      add(v, el('div', 'placeholder', 'Pick a commit, a whole branch, or type any revision or range.'))
+      return
+    }
+    var src = '/view?rev=' + encodeURIComponent(state.rev)
+    var open = el('a', null, 'open in a tab ↗')
+    open.href = src
+    open.target = '_blank'
+    open.rel = 'noopener'
+    var reload = el('button', 'btn', 'Reload')
+    reload.type = 'button'
+    var frame = el('iframe')
+    frame.title = 'gloss of ' + state.rev
+    frame.src = src
+    // So the page's keys (j, k, o, e, c) work without clicking into it first.
+    frame.addEventListener('load', function () { frame.contentWindow.focus() })
+    reload.addEventListener('click', function () { frame.src = src })
+    add(v, add(el('div', 'viewer-bar'), el('span', 'what', state.rev === 'wip' ? 'uncommitted work (wip)' : state.rev), reload, open), frame)
+  }
+
+  // ---- actions ----
+  function select(rev) {
+    state.rev = rev
+    saveHash()
+    renderList()
+    parts.rev.value = rev === 'wip' ? '' : rev
+    renderViewer()
+  }
+
+  function loadLog(append) {
+    if (!state.head) { log = { commits: [], more: false, total: null }; renderList(); return Promise.resolve() }
+    var q = new URLSearchParams({ head: state.head, limit: PAGE, skip: append ? log.commits.length : 0 })
+    if (state.base) q.set('base', state.base)
+    if (state.q) q.set('q', state.q)
+    var asked = state.head + '..' + state.base + '?' + state.q
+    return api('/api/log?' + q).then(function (data) {
+      if (asked !== state.head + '..' + state.base + '?' + state.q) return // the selection moved on
+      logError = null
+      log = append ? { commits: log.commits.concat(data.commits), more: data.more, total: data.total } : data
+      renderList()
+    }).catch(function (err) {
+      logError = err.message
+      log = { commits: [], more: false, total: null }
+      renderList()
+    })
+  }
+
+  function pickHead(name) {
+    state.head = name
+    // A feature branch is most useful against the usual base; the base itself
+    // is listed whole.
+    state.base = name === refs.defaultBase ? null : refs.defaultBase
+    saveHash()
+    renderSide()
+    loadLog(false)
+  }
+
+  function load() {
+    return api('/api/refs').then(function (data) {
+      parts.error.hidden = true
+      refs = data
+      var h = readHash()
+      // A link or bookmark may name a branch that has since been deleted or
+      // renamed: use the usual choice instead, and say so.
+      var known = {}
+      refs.branches.concat(refs.remotes).forEach(function (b) { known[b.name] = true })
+      var head = h.head && known[h.head] ? h.head : null
+      state.head = head || refs.current || refs.defaultBase || (refs.branches[0] && refs.branches[0].name) || null
+      var notice = null
+      if (h.head && !head) {
+        // The default base goes with the default branch.
+        state.base = state.head === refs.defaultBase ? null : refs.defaultBase
+        notice = 'Branch “' + h.head + '” no longer exists; showing ' + (state.head || 'the default') + ' instead.'
+      } else if (h.base && !known[h.base]) {
+        state.base = null
+        notice = 'The branch to compare with, “' + h.base + '”, no longer exists; showing all of ' + state.head + '’s history.'
+      } else if (head) {
+        state.base = h.base || null
+      } else {
+        state.base = state.head === refs.defaultBase ? null : refs.defaultBase
+      }
+      if (notice) {
+        parts.error.textContent = notice
+        parts.error.hidden = false
+      }
+      state.rev = h.rev || (refs.wip ? 'wip' : null)
+      parts.title.textContent = refs.repo
+      renderSide()
+      renderViewer()
+      return loadLog(false).then(function () {
+        // With nothing chosen, show the whole branch, or its newest commit.
+        if (!state.rev && state.head) select(state.base && log.commits.length ? state.base + '..' + state.head : log.commits.length ? log.commits[0].sha : null)
+      })
+    })
+  }
+
+  function build() {
+    parts.title = el('span', 'repo')
+    var refresh = el('button', 'btn', 'Refresh')
+    refresh.type = 'button'
+    refresh.title = 'Re-read branches and commits'
+    refresh.addEventListener('click', function () { load().catch(fail) })
+
+    parts.head = picker(pickHead)
+    parts.base = picker(function (name) {
+      state.base = name
+      parts.base.setValue(name)
+      saveHash()
+      loadLog(false)
+    })
+
+    parts.rev = el('input')
+    parts.rev.type = 'text'
+    parts.rev.spellcheck = false
+    parts.rev.placeholder = 'HEAD~3, abc123, main..feature'
+    var go = el('button', 'btn', 'View')
+    go.type = 'submit'
+    var form = add(el('form', 'rev-row'), parts.rev, go)
+    form.addEventListener('submit', function (ev) {
+      ev.preventDefault()
+      var v = parts.rev.value.trim()
+      if (v) select(v)
+    })
+
+    parts.search = el('input')
+    parts.search.type = 'search'
+    parts.search.spellcheck = false
+    parts.search.placeholder = 'Search commit messages and authors…'
+    parts.search.setAttribute('aria-label', 'Search commits')
+    var searching = null
+    parts.search.addEventListener('input', function () {
+      // Wait for a pause in typing: each search asks git.
+      clearTimeout(searching)
+      searching = setTimeout(function () {
+        state.q = parts.search.value.trim()
+        loadLog(false)
+      }, 250)
+    })
+
+    parts.error = el('p', 'error')
+    parts.error.hidden = true
+    parts.list = el('div', 'list')
+    parts.viewer = el('section', 'viewer')
+
+    var top = add(el('div', 'side-top'),
+      add(el('div', 'title'), el('strong', null, 'git gloss ary'), parts.title, refresh),
+      parts.error,
+      add(el('div', 'field'), el('span', null, 'Branch'), parts.head.root),
+      add(el('div', 'field'), el('span', null, 'Compare with'), parts.base.root),
+      add(el('label', 'field'), document.createTextNode('Any revision or range'), form))
+    add(app, add(el('div', 'shell'), add(el('aside', 'side'), top, add(el('div', 'search-bar'), parts.search), parts.list), parts.viewer))
+  }
+
+  function fail(err) {
+    parts.error.textContent = 'Could not read the repository: ' + err.message
+    parts.error.hidden = false
+  }
+
+  build()
+  load().catch(fail)
+})()

package/dist/ary/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>git gloss ary</title>
+<link rel="stylesheet" href="/ary.css">
+</head>
+<body>
+<div id="app"><noscript>This page needs JavaScript.</noscript></div>
+<script src="/ary.js"></script>
+</body>
+</html>

package/dist/ary/server.js

@@ -0,0 +1,101 @@
+import { readFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { GlossError, WIP_REF, gitTry, resolveCommits } from '../git.js';
+import { buildPageData } from '../html/data.js';
+import { escapeHtml, renderPage } from '../html/page.js';
+import { listLog, listRefs } from './browse.js';
+const asset = (name) => readFileSync(new URL(name, import.meta.url), 'utf8');
+// A range page loads and lays out every commit in it, so a huge one would hang
+// the browser. Narrowing it is a better answer than a spinner.
+export const MAX_RANGE_COMMITS = 200;
+// The shell page loads only its own script and style, and may frame only
+// /view pages. Those carry their own policy: an inline script with a nonce.
+const SHELL_CSP = "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; frame-src 'self'; base-uri 'none'; form-action 'none'";
+class BadRequest extends GlossError {
+}
+// A revision, branch or range typed by the user or taken from the sidebar. An
+// option-looking one is refused so it can never be read by git as a flag.
+function revParam(url, name, required = true) {
+    const v = url.searchParams.get(name);
+    if (!v) {
+        if (required)
+            throw new BadRequest(`missing ?${name}=`);
+        return null;
+    }
+    if (v.startsWith('-') || v.length > 500 || v.includes('\0'))
+        throw new BadRequest(`not a revision: ${v.slice(0, 80)}`);
+    return v;
+}
+const intParam = (url, name, fallback, min, max) => {
+    const n = Number(url.searchParams.get(name) ?? fallback);
+    return Number.isInteger(n) && n >= min ? Math.min(n, max) : fallback;
+};
+function send(res, status, type, body, headers = {}) {
+    res.writeHead(status, {
+        'content-type': `${type}; charset=utf-8`,
+        // Everything reflects the repo as it is now.
+        'cache-control': 'no-store',
+        'x-content-type-options': 'nosniff',
+        'referrer-policy': 'no-referrer',
+        ...headers,
+    });
+    res.end(body);
+}
+const sendJson = (res, data) => send(res, 200, 'application/json', JSON.stringify(data));
+function viewPage(url) {
+    const rev = revParam(url, 'rev');
+    // "wip" is the latest snapshot of uncommitted work. The server never takes
+    // one (that is `git gloss hunks wip`): browsing doesn't change anything.
+    const target = rev === 'wip' ? gitTry(['rev-parse', '--verify', '--quiet', WIP_REF])?.trim() : rev;
+    if (!target)
+        throw new GlossError('no snapshot of uncommitted work yet; run `git gloss hunks wip` first');
+    const { shas, merges, range } = resolveCommits(target);
+    if (shas.length > MAX_RANGE_COMMITS) {
+        throw new GlossError(`${rev} has ${shas.length} commits; a page shows at most ${MAX_RANGE_COMMITS}. Pick a narrower range.`);
+    }
+    return renderPage(buildPageData(shas, range, merges));
+}
+function route(req, res, url) {
+    const shell = (name, type) => send(res, 200, type, asset(name), type === 'text/html' ? { 'content-security-policy': SHELL_CSP } : {});
+    switch (url.pathname) {
+        case '/': return shell('./index.html', 'text/html');
+        case '/ary.js': return shell('./client.js', 'text/javascript');
+        case '/ary.css': return shell('./style.css', 'text/css');
+        case '/api/refs': return sendJson(res, listRefs());
+        case '/api/log':
+            return sendJson(res, listLog(revParam(url, 'head'), revParam(url, 'base', false), intParam(url, 'limit', 100, 1, 500), intParam(url, 'skip', 0, 0, 1e6), (url.searchParams.get('q') ?? '').slice(0, 200)));
+        case '/view':
+            // The page may only be framed by the shell, not by another site.
+            return send(res, 200, 'text/html', viewPage(url), { 'content-security-policy': "frame-ancestors 'self'" });
+        default: return send(res, 404, 'text/plain', 'not found');
+    }
+}
+export function createAry(port) {
+    return createServer((req, res) => {
+        // A web page on another site can make the browser send requests here, and
+        // with DNS rebinding even read the answers. Only our own origin's host
+        // names get through; the server is read-only besides.
+        const allowed = [`127.0.0.1:${port()}`, `localhost:${port()}`];
+        if (!allowed.includes((req.headers.host ?? '').toLowerCase()))
+            return send(res, 403, 'text/plain', `forbidden host: this server answers to ${allowed.join(' and ')} (it listens on this machine only; through an SSH tunnel, forward the same port number)`);
+        if (req.method !== 'GET' && req.method !== 'HEAD')
+            return send(res, 405, 'text/plain', 'read-only', { allow: 'GET, HEAD' });
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        try {
+            route(req, res, url);
+        }
+        catch (err) {
+            if (!(err instanceof GlossError)) {
+                console.error(err);
+                return send(res, 500, 'text/plain', 'internal error');
+            }
+            const status = err instanceof BadRequest ? 400 : 422;
+            if (url.pathname === '/view') {
+                send(res, status, 'text/html', `<!doctype html><meta charset="utf-8"><meta name="color-scheme" content="light dark"><pre style="white-space:pre-wrap;font:14px/1.5 system-ui;padding:16px">${escapeHtml(err.message)}</pre>`, { 'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'self'" });
+            }
+            else {
+                send(res, status, 'application/json', JSON.stringify({ error: err.message }));
+            }
+        }
+    });
+}

package/dist/ary/style.css

@@ -0,0 +1,115 @@
+:root {
+  --bg: #f7f7f5;
+  --surface: #ffffff;
+  --surface-2: #f1f1ee;
+  --border: #e2e2dc;
+  --text: #1d1d1b;
+  --muted: #6b6b66;
+  --accent: #3b5bdb;
+  --ok: #1a7f37;
+  --warn-bg: #fff4e5;
+  --warn-border: #f0b35b;
+  --warn-text: #7a4300;
+  --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace;
+  --sans: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  color-scheme: light;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #151514;
+    --surface: #1e1e1c;
+    --surface-2: #262624;
+    --border: #34342f;
+    --text: #e8e8e3;
+    --muted: #9a9a92;
+    --accent: #8ea2ff;
+    --ok: #57c47a;
+    --warn-bg: #33270f;
+    --warn-border: #a2701e;
+    --warn-text: #f3c77a;
+    color-scheme: dark;
+  }
+}
+
+* { box-sizing: border-box; }
+html, body, #app { height: 100%; }
+body { margin: 0; background: var(--bg); color: var(--text); font: 14px/1.45 var(--sans); }
+button, input, select { font: inherit; color: inherit; }
+
+.shell { display: grid; grid-template-columns: 340px minmax(0, 1fr); height: 100%; }
+@media (max-width: 800px) {
+  .shell { grid-template-columns: minmax(0, 1fr); grid-template-rows: minmax(0, 45%) minmax(0, 1fr); }
+}
+
+/* Sidebar */
+.side { display: flex; flex-direction: column; min-height: 0; border-right: 1px solid var(--border); background: var(--surface); }
+.side-top { padding: 12px; border-bottom: 1px solid var(--border); display: grid; gap: 10px; }
+.title { display: flex; align-items: baseline; justify-content: space-between; gap: 8px; }
+.title strong { font-size: 15px; }
+.title .repo { color: var(--muted); font-family: var(--mono); font-size: 12px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+label.field, div.field { display: grid; gap: 3px; color: var(--muted); font-size: 11.5px; text-transform: uppercase; letter-spacing: 0.05em; }
+label.field > input, .rev-row input, .combo-btn, .combo-panel input {
+  width: 100%; padding: 5px 8px; border: 1px solid var(--border); border-radius: 6px;
+  background: var(--bg); text-transform: none; letter-spacing: 0; font-size: 13px;
+}
+.combo { position: relative; }
+.combo-btn { text-align: left; cursor: pointer; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; padding-right: 24px; position: relative; }
+.combo-btn::after { content: "▾"; position: absolute; right: 8px; color: var(--muted); }
+.combo-panel {
+  position: absolute; z-index: 10; left: 0; right: 0; top: calc(100% + 4px);
+  display: grid; gap: 6px; padding: 6px; border: 1px solid var(--border); border-radius: 8px;
+  background: var(--surface); box-shadow: 0 8px 24px rgb(0 0 0 / 0.25);
+}
+.combo-panel[hidden] { display: none; }
+.combo-list { max-height: min(50vh, 320px); overflow: auto; }
+.combo-group {
+  margin-top: 8px; padding: 10px 8px 4px; border-top: 1px solid var(--border);
+  font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.06em; color: var(--text);
+}
+.combo-group:first-child { margin-top: 0; padding-top: 4px; border-top: 0; }
+.combo-group .count { margin-left: 6px; color: var(--muted); font-weight: 400; }
+.combo-item { display: block; width: 100%; text-align: left; border: 0; background: none; border-radius: 5px; padding: 4px 8px 4px 20px; cursor: pointer; font-family: var(--mono); font-size: 12.5px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.combo-item:hover, .combo-item.active { background: var(--surface-2); }
+.combo-item[aria-selected="true"] { color: var(--accent); font-weight: 600; }
+.combo-more { padding: 6px 8px; color: var(--muted); font-size: 12.5px; }
+.rev-row { display: flex; gap: 6px; }
+.rev-row input { font-family: var(--mono); font-size: 12.5px; }
+.btn {
+  border: 1px solid var(--border); background: var(--surface); border-radius: 6px;
+  padding: 4px 10px; cursor: pointer; white-space: nowrap;
+}
+.btn:hover { background: var(--surface-2); }
+.error { margin: 0; padding: 8px 10px; border-radius: 6px; background: var(--warn-bg); border: 1px solid var(--warn-border); color: var(--warn-text); font-size: 12.5px; }
+
+.list { flex: 1; min-height: 0; overflow: auto; padding: 6px; }
+.list h2 { margin: 10px 8px 4px; font-size: 11.5px; text-transform: uppercase; letter-spacing: 0.05em; color: var(--muted); font-weight: 600; }
+.row {
+  display: block; width: 100%; text-align: left; cursor: pointer;
+  border: 1px solid transparent; background: none; border-radius: 6px; padding: 6px 8px;
+}
+.row:hover { background: var(--surface-2); }
+.row[aria-current="true"] { background: var(--surface-2); border-color: var(--accent); }
+.row .subject {
+  /* the whole point of the list: enough of the subject to tell commits apart */
+  display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; line-clamp: 2;
+  overflow: hidden; overflow-wrap: anywhere;
+}
+.row .meta { display: flex; flex-wrap: wrap; align-items: baseline; margin-top: 2px; color: var(--muted); font-size: 12px; }
+.row .marks { margin-left: auto; padding-left: 10px; display: inline-flex; gap: 10px; white-space: nowrap; }
+.sha { font-family: var(--mono); font-size: 12px; }
+.mark.glossed { color: var(--ok); }
+.mark.reviewed { color: var(--accent); }
+.mark.warn { color: var(--warn-text); background: var(--warn-bg); border-radius: 4px; padding: 0 5px; }
+.search-bar { padding: 8px 12px; border-bottom: 1px solid var(--border); }
+.search-bar input { width: 100%; padding: 5px 8px; border: 1px solid var(--border); border-radius: 6px; background: var(--bg); font-size: 13px; }
+.empty { color: var(--muted); padding: 8px; }
+.more { margin: 6px 8px; }
+
+/* Viewer */
+.viewer { display: flex; flex-direction: column; min-width: 0; min-height: 0; }
+.viewer-bar { display: flex; align-items: center; gap: 10px; padding: 8px 12px; border-bottom: 1px solid var(--border); background: var(--surface); }
+.viewer-bar .what { flex: 1; min-width: 0; font-family: var(--mono); font-size: 12.5px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.viewer-bar a { color: var(--accent); text-decoration: none; }
+.viewer-bar a:hover { text-decoration: underline; }
+iframe { flex: 1; width: 100%; min-height: 0; border: 0; background: var(--bg); }
+.placeholder { flex: 1; display: grid; place-items: center; color: var(--muted); padding: 24px; text-align: center; }

package/dist/cli.js

@@ -1,6 +1,7 @@
 import { GlossError } from './git.js';
 import * as add from './commands/add.js';
 import * as adopt from './commands/adopt.js';
+import * as ary from './commands/ary.js';
 import * as carry from './commands/carry.js';
 import * as html from './commands/html.js';
 import * as hunks from './commands/hunks.js';
@@ -13,7 +14,7 @@ import * as sync from './commands/sync.js';
 import * as versions from './commands/versions.js';
 import * as why from './commands/why.js';
 const COMMANDS = {
-    init, hunks, add, adopt, carry, show, html, why, review, reviews, sync, versions, schema,
+    init, hunks, add, adopt, carry, show, html, ary, why, review, reviews, sync, versions, schema,
 };
 function help() {
     return 'usage: git gloss <command> [options]\n\n' +

package/dist/commands/ary.js

@@ -0,0 +1,35 @@
+import { parseArgs } from 'node:util';
+import { createAry } from '../ary/server.js';
+import { GlossError, git } from '../git.js';
+import { openInBrowser } from './html.js';
+export const usage = 'ary [--port <n>] [--no-open]   browse glosses of branches, commits and uncommitted work in a local web page';
+// Starts a read-only server on this machine and keeps running until stopped.
+// The browser page lists branches and commits and shows each selection with
+// the same view as `git gloss html`.
+export function run(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: { port: { type: 'string' }, 'no-open': { type: 'boolean' } },
+    });
+    // Number('') and Number(' ') are 0, which would quietly mean "any port".
+    const port = values.port === undefined ? 0 : /^\d+$/.test(values.port) ? Number(values.port) : NaN;
+    if (!Number.isInteger(port) || port > 65535)
+        throw new GlossError(`not a port: ${values.port}`);
+    git(['rev-parse', '--git-dir']); // fail early outside a repository
+    let boundPort = port;
+    const server = createAry(() => boundPort);
+    server.on('error', (err) => {
+        console.error(`error: ${err.code === 'EADDRINUSE' ? `port ${port} is in use` : err.message}`);
+        process.exitCode = 1;
+    });
+    // Loopback only: the view includes the code of your commits.
+    server.listen(port, '127.0.0.1', () => {
+        boundPort = server.address().port;
+        const url = `http://127.0.0.1:${boundPort}/`;
+        console.log(url);
+        console.error('serving glosses read-only; press Ctrl-C to stop');
+        if (!values['no-open'])
+            openInBrowser(url);
+    });
+    return 0;
+}

package/dist/commands/html.js

@@ -7,7 +7,7 @@ import { resolveCommits } from '../git.js';
 import { buildPageData } from '../html/data.js';
 import { renderPage } from '../html/page.js';
 export const usage = 'html [<commit> | <range>] [-o <file>] [--open]   write a self-contained HTML view of a gloss, or of every commit in a range';
-function openInBrowser(file) {
+export function openInBrowser(file) {
     const [cmd, args] = process.platform === 'darwin' ? ['open', [file]]
         : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', file]]
             : ['xdg-open', [file]];

package/dist/commands/init.js

@@ -122,7 +122,12 @@ export function run(argv = []) {
         // The hooks run `git gloss`; a git without it on PATH (a GUI client, a
         // different shell) would print an error after every commit and push.
         if (spawnSync('sh', ['-c', 'command -v git-gloss'], { stdio: 'ignore' }).status !== 0) {
-            console.log('! git-gloss is not on PATH here; the hooks need it wherever git runs (see README: npm link)');
+            // Without it, every commit and push prints an error and the gloss isn't
+            // moved, synced or carried, so say that plainly.
+            console.log('! git-gloss is not on PATH in this shell, so the hooks will fail on every commit and push.');
+            console.log('  Their errors are only warnings, and glosses are not adopted, carried or synced until it is fixed.');
+            console.log('  Either install it globally (npm install -g @ok-ggwp/git-gloss), or, for a project install,');
+            console.log('  put its node_modules/.bin first on PATH in each hook (see README: "Project installs").');
         }
         installHook('pre-push', HOOK, '`git push` now syncs glosses with the remote it pushes to', [
             'git remote | grep -qxF -- "$1" && { GIT_TERMINAL_PROMPT=0 git gloss sync "$1" --pushing >&2 ||',

package/dist/git.js

@@ -146,7 +146,8 @@ export function resolveCommit(rev) {
     // "wip": the latest snapshot of uncommitted work (made by `hunks wip`). A
     // branch or tag named wip still works when there is no snapshot, and can be
     // reached as heads/wip or tags/wip when there is.
-    const named = gitTry(['rev-parse', '--verify', '--quiet', `${rev}^{commit}`])?.trim();
+    // --end-of-options: the revision is whatever the user typed, never a flag.
+    const named = gitTry(['rev-parse', '--verify', '--quiet', '--end-of-options', `${rev}^{commit}`])?.trim();
     if (rev === 'wip') {
         const sha = gitTry(['rev-parse', '--verify', '--quiet', WIP_REF])?.trim();
         if (sha) {

package/dist/html/page.js

@@ -6,7 +6,7 @@ const asset = (name) => readFileSync(new URL(name, import.meta.url), 'utf8');
 export function embedJson(data) {
     return JSON.stringify(data).replace(/</g, '\\u003c');
 }
-const escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+export const escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
 export function renderPage(data) {
     // The page only runs our own inline script. If escaping ever failed, an
     // injected script would lack the nonce and the CSP would block it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ok-ggwp/git-gloss",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Annotate agent-written diffs with intent and necessity, stored in git notes",
   "license": "MIT",
   "keywords": [

package/skills/gloss/SKILL.md

@@ -25,6 +25,10 @@ Gloss changes **before they are committed**, unless the user asks you to commit
 
 To gloss a commit instead, use its revision (default `HEAD`) wherever these steps say `wip`.
 
+## Calling git-gloss
+
+The commands below are written as `git gloss …`. That works only where git-gloss is on PATH. Check first with `command -v git-gloss`. If it isn't, look for a project install (`node_modules/.bin/git-gloss`, or a `package.json` that lists `@ok-ggwp/git-gloss`) and run the same commands as `pnpm exec git-gloss …`, `npx git-gloss …` or `node_modules/.bin/git-gloss …`. Use the package manager the repo uses. In a monorepo the install may sit in a subdirectory: run the commands from there, and give file paths to `why` relative to that directory. Don't install it globally just to run the skill.
+
 ## Steps
 
 1. Run `git gloss hunks wip` to snapshot the uncommitted work and see it split into hunks with ids `h1`, `h2`, …, with each hunk's changed (`+`/`-`) lines numbered from 1. If you change files afterwards, run it again: that takes a new snapshot, and a gloss must match the snapshot it was written for.