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. A second host is a sibling directory, not a rename |
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/markdown |
Markdown and raw HTML flattened to terminal lines, folding <details> to its summary so a bot's changelog costs one line |
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 |
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 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 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
|
|
|
markdown
Package markdown renders GitHub markdown bodies as terminal lines.
|
Package markdown renders GitHub markdown bodies as terminal lines. |
|
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. |
|
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.