README
¶
aragonite
Shared Go packages for kyleking's terminal tools. Aragonite is the mineral coral skeletons are built from, which puts it alongside calcipy and corallium.
Extracted from gh-repo-dashboard rather than designed up front, so every package here has at least one real consumer.
The data packages hold data and predicates only. The rendering packages under display
and tui/ take their styles as an argument and carry no vocabulary of their own, so a
consumer keeps naming its own colors and styles while sharing the layout, wrapping, and
measurement underneath. DESIGN.md has the layering rule in full.
Packages
| Package | What it holds |
|---|---|
cache |
Generic TTL cache with a disk store, a registry for package-level caches, and remote-scoped keys so parallel checkouts of one remote share a read |
display |
forge and vcs models as plain text: relative times, status summaries, review glyphs, and the em-dash placeholder. Importing both is what keeps forge and vcs from importing each other |
forge |
The pull request model shared by every tool that reads a code host: PullRequest, its detail and preview forms, checks, and workflow runs |
ghcassette |
Records and replays gh subprocess calls through a stand-in binary on PATH, so a test replays the bytes GitHub sent in the shape gh prints them. The subprocess counterpart to transport |
forge/github |
GitHub through the gh CLI: pull requests, reviews, comments, search, Actions runs (by ID, by query, and the latest per workflow on a ref) with their jobs and step timings, and the caches typed on them. WithRunner puts a consumer's own executor behind every call, which is how a tool keeps its own recording seam or mutation guard. Budgets reads what is left of the hourly allowances, one per pool, since core, GraphQL, and search are separate and a tool out of one can still make the other's calls; the read is free, so a burst can ask whether it is affordable rather than firing and reporting the wreckage. A second host is a sibling directory, not a rename |
ratelimit |
GitHub's hourly allowances enforced on an http.RoundTripper: an exhausted pool becomes a typed error naming when it returns, and further requests to that pool fail without spending one to relearn it. Blocks per pool, since core, GraphQL, and search are separate allowances and being out of one leaves the others usable. The reactive half of forge/github.Budgets: ask that before a burst, get this when one runs out anyway. Auth is left to whatever builds the client, because go-gh already resolves the gh CLI token with a GITHUB_TOKEN fallback and wrapping that would buy nothing |
transport |
A test seam and mutation guard for an http.RoundTripper-based API client: register a fake transport in tests, or get a guard that panics on a real mutating request when none is registered |
tui/keyhint |
The keys a screen offers, bracketed inside the word they do ([p]ost one, [tab] switch) so a footer needs no legend. The same shape captions the second key of a chord while it waits, and Help lays out the full legend with the keys right-aligned in one column |
tui/markdown |
Markdown and raw HTML flattened to terminal lines, folding <details> to its summary so a bot's changelog costs one line |
tui/skin |
The faces every screen here draws with, built from a palette and the one accent that tells a tool from its siblings, so a title looks like a title in each of them |
tui/region |
The block a list opens beneath itself: a rule, label/value facts, a body, and a captioned divider |
tui/table |
Fits columns to an available width and pads cells to it, measuring in display cells so wide glyphs never shift a row |
tui/theme |
Catppuccin Latte and Macchiato palettes, terminal-background detection with a CATPPUCCIN_THEME override, and an eight-role semantic view over a palette |
vcs |
git and jj behind one interface, with the working-tree summary, branches, commits, stashes, worktrees, diff, checkout identity, and stamp |
Planned, once a second consumer needs them:
| Package | Source | Why it is shared |
|---|---|---|
filter |
gh-repo-dashboard internal/filters |
The predicate, query, and sort engine behind both tools' pull request lists |
codeintel |
wavez internal/codeintel |
Symbols, edges, FTS, and line-to-test coverage in SQLite |
tui/editor |
second-look internal/tui |
A text box with modal editing: normal and insert modes, hjkl w b 0 $, x dd D cc, i a o and their capitals, and undo. Every tool here writes prose in a terminal (a review comment, a pull request body, a commit message) and bubbles/textarea gives them arrow keys. Two open questions: how far to go before the missing key is worse than no modes at all (counts, registers, and / are where the subset starts lying), and whether the honest answer is to hand the buffer to the user's own nvim in a small pane the way Claude Code's ctrl+g does, which costs nothing to learn and gets their real config |
Generic TUI helpers start under tui/. They only earn their own module if something
that is not a git tool needs them.
Consumers
- gh-repo-dashboard
- second-look
- gh-sweep (
transportandtui/theme; see docs/gh-sweep.md for whycacheandforgewere not a fit) - gh-lazydispatch (
forge/github,ghcassette,tui/table, andtui/theme)
Local development
Consumers use a go.work pointing at a sibling checkout, so nothing has to be published
to iterate across repos. go.work is gitignored.
cd second-look && go work init . ../aragonite
docs/extraction.md records what the first extraction taught, so the next one costs less.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cache provides a generic in-memory TTL cache used to avoid redundant gh/git/jj calls across TUI refreshes.
|
Package cache provides a generic in-memory TTL cache used to avoid redundant gh/git/jj calls across TUI refreshes. |
|
Package display renders forge and vcs models as plain text.
|
Package display renders forge and vcs models as plain text. |
|
Package filter narrows a list to the rows worth looking at, the shape every tool here reaches for once a list is long enough to need a live search: a predicate to combine and apply, a smart-case substring match for the base case, and a scoped-prefix query so "kind:thread pool" or "r:foo b:bar rest" parses the same way wherever the prefixes differ.
|
Package filter narrows a list to the rows worth looking at, the shape every tool here reaches for once a list is long enough to need a live search: a predicate to combine and apply, a smart-case substring match for the base case, and a scoped-prefix query so "kind:thread pool" or "r:foo b:bar rest" parses the same way wherever the prefixes differ. |
|
Package forge holds the pull request model shared by every tool that reads a code host.
|
Package forge holds the pull request model shared by every tool that reads a code host. |
|
github
Package github wraps the gh CLI to fetch pull request and workflow run data.
|
Package github wraps the gh CLI to fetch pull request and workflow run data. |
|
Package ghcassette records and replays gh subprocess calls.
|
Package ghcassette records and replays gh subprocess calls. |
|
ghstub
command
Command ghstub stands in for the gh binary while tests run.
|
Command ghstub stands in for the gh binary while tests run. |
|
Package ratelimit keeps a GitHub API client from spending requests to rediscover that it has none left.
|
Package ratelimit keeps a GitHub API client from spending requests to rediscover that it has none left. |
|
Package transport gives an HTTP-based API client (go-gh's REST/GraphQL clients, or anything else built on http.RoundTripper) a test seam and a safety net in one: a fake transport tests can register, and a guard that panics on a real mutating request reaching the network when no fake is registered.
|
Package transport gives an HTTP-based API client (go-gh's REST/GraphQL clients, or anything else built on http.RoundTripper) a test seam and a safety net in one: a fake transport tests can register, and a guard that panics on a real mutating request reaching the network when no fake is registered. |
|
tui
|
|
|
keyhint
Package keyhint renders the keys a screen offers, in one shape everywhere: the letter that presses a thing bracketed inside the word for it, and bracketed in front where the word does not carry the letter.
|
Package keyhint renders the keys a screen offers, in one shape everywhere: the letter that presses a thing bracketed inside the word for it, and bracketed in front where the word does not carry the letter. |
|
markdown
Package markdown renders GitHub markdown bodies as terminal lines.
|
Package markdown renders GitHub markdown bodies as terminal lines. |
|
overlay
Package overlay centers a block of content over a full-screen frame: a modal, or a pane too small for what it holds and promoted out of the layout.
|
Package overlay centers a block of content over a full-screen frame: a modal, or a pane too small for what it holds and promoted out of the layout. |
|
region
Package region renders the block a list opens beneath itself: a rule naming what is open, a head of label/value facts, a second rule, a body of free text, and a divider captioning what sat above it.
|
Package region renders the block a list opens beneath itself: a rule naming what is open, a head of label/value facts, a second rule, a body of free text, and a divider captioning what sat above it. |
|
skin
Package skin is the set of faces every screen in these tools draws with, so a title looks like a title in each of them and a reader moving between two is not relearning the same screen.
|
Package skin is the set of faces every screen in these tools draws with, so a title looks like a title in each of them and a reader moving between two is not relearning the same screen. |
|
table
Package table fits a set of columns into an available terminal width and pads cells to it.
|
Package table fits a set of columns into an available terminal width and pads cells to it. |
|
theme
Package theme carries the Catppuccin palettes a terminal UI draws from, the terminal-background detection that picks between them, and a semantic view naming the eight roles most views actually reach for.
|
Package theme carries the Catppuccin palettes a terminal UI draws from, the terminal-background detection that picks between them, and a semantic view naming the eight roles most views actually reach for. |
|
Package vcs abstracts git and jj repository operations behind a common Operations interface.
|
Package vcs abstracts git and jj repository operations behind a common Operations interface. |
Click to show internal directories.
Click to hide internal directories.