An empty dump does not fail loudly: the TUI renders every row as
DEFAULT, which is indistinguishable from a config where nothing is set.
That is a wrong answer rather than a missing one -- the user would be
looking at ON rows reported as DEFAULT -- so the launcher now checks the
dump is non-empty and bails with a message instead. The taxonomy alone
guarantees output on any working checkout. Also guard a failed mktemp,
which would otherwise send the dump to /state and hand an empty path to
rm -rf.
README: mention that / searches sub-categories across every category.
test_concat_section_five_stays_verbatim forbids backticks inside
generated Section 5 entries -- function headers are rendered verbatim, so
inline code markup there breaks the man page.
config-settings is now a launcher for scripts/config-settings-tui.py,
drawn with Python's stdlib curses. The seven fish files that hand-rolled
the ANSI renderer are gone, along with the golden harness that had to pin
their byte-exact output.
The TUI is a child process, so it can neither read the session's global
variables nor write them. State goes in as a dump from the new
__config_settings_state; the edits come back as a fish script that
config-settings sources, which is what lets the Session page's `set -g`
land in the caller's shell instead of in a child that is about to exit.
Every edit is emitted as a call to __config_settings_apply or
__config_settings_set_value, so list splitting, the SCROLLBACK_HISTORY_*
export mirror and the shadow-warning suppression all stay in the fish
layer that already owned them.
The consequence, and the one behaviour change: edits are applied in one
batch on exit rather than on each keypress. The status bar shows a
pending count.
New: `/` filters the current page, and on the Universal and Session pages
it reaches into every category's sub-categories, listing hits as
"Category › Sub" so a sub-category can be toggled without drilling into
its parent first. Also a `?` help overlay, mouse selection, and a
drill-down page that leads with the category's own toggle.
Gone with the renderer: the four width tiers, the wrap-aware erase
arithmetic, the stty/dd/od raw key reader, the panel-height bookkeeping
and the hand-written redraw differ. curses owns all of it, and the alt
screen plus absolute addressing makes the desync class behind 608b022,
4210f3b, 93fc5e0 and 3c4f720 unreachable.
The sub-category taxonomy is NOT duplicated in Python: it travels in the
state dump, still sourced from __config_settings_subcats. The category,
Sponge and Paths row tables move into Python, consolidating the two
copies the fish renderers kept.
Dependency: python3 with curses. Stdlib on Arch, Fedora and a full
Debian/Ubuntu python3; python3-minimal alone lacks _curses. The launcher
checks for both and names what is missing. Called out in the README.
Verified: 416/416 assertions, plus a live end-to-end in a sandbox HOME
confirming the Universal page writes universal scope only (U1/G0) and the
Session page global scope only (U0/G1).
- Print the missing exit-repaint after the inline editor's
__cs_dispatch_draw call (was silently changed to capture-only earlier
in the branch; this call site was missed, blanking the panel on
commit/cancel of an inline edit).
- Hoist (count $prev_edit_frame) out of a quoted math string in the
inline editor's per-keystroke redraw -- fish doesn't expand a command
substitution there, so math silently errored.
- Add a >= 52 column floor to both diff-path guards: below the
narrowest tier's own 52-column box width, lines wrap and the diff
path's one-physical-row-per-logical-line walk corrupts the display.
- Reword a stale test comment that described panel_h as mirroring a
hand-set constant in __cs_dispatch_draw; it derives panel_h from real
output now.
- Declare prev_edit_frame with -l alongside edit_frame instead of a
bare set, matching the file's convention.
- Move prev_frame's declaration to its point of use instead of an
empty top-level placeholder, matching old_h in the same block.
27 duplicated declarations replaced by 5 calls. Output strings untouched.
Four of these five files have no --help path, so the byte-identity harness
cannot reach them. Covered instead by driving the real TUI under a pty on
both the baseline and converted trees with an identical paced keystroke
feed (down x3, Tab, Enter, Esc, Tab, down, q):
9 redraws, 15068 bytes, byte-identical on both sides
c_sel (ESC[35;1m) x9, c_hi (ESC[37;1m) x8, c_head (ESC[36;1m) x9
all four draw helpers reached -- draw, pagetab, draw_subcat
("cascade default", "(category)"), draw_value ("Allow prev")
Add the established c_head/c_cmd/c_flag/c_dim/c_arg color scheme to
--help (or usage-on-error) output in play-media and 13 other functions
that lacked it or used an ad hoc scheme: bkg, detach, replay, p, y,
spark, wake-lock, open-url, repo-open, dng2avif, dockup, fish-deps
(__fish_deps_help), and scrub.
Also tweak the standard itself:
- c_cmd now uses plain `set_color --bold` instead of `--bold white`,
so the command name adapts to the terminal's foreground instead of
forcing white text that washes out on light-background themes.
Applied across all functions already using the pattern.
- jobrunner's reset variable renamed from c_rst to c_reset to match
the naming used everywhere else.
The wrapped description for the Enter key was indented one column past
every other description in the Navigation block. Drop the extra leading
space so it lines up at column 17 with the rest.
Bundled fix wave for six findings from the sub-category-granularity
whole-branch review:
- config-settings: reset in_subcat on Tab/Shift-Tab so up/down keep
routing to cur_row instead of freezing on the Sponge/Paths pages
after a drill-down
- verify-manual: _parsed_components() now delegates to
generate_component_registry.collect_components() instead of a
lossy dict.update() merge, closing a taxonomy-check blind spot on
identity collisions
- verify-manual: add test_committed_registry_matches_headers to
catch the committed registry drifting from current # COMPONENT
headers
- build-docs workflow: trigger on conf.d/** and config.fish edits,
not just functions/**
- __config_settings_draw_subcat: show (Universal)/(Session) in the
drill-down title so the persistence scope is visible before toggling
- __config_settings_draw / config-settings: mention the Enter
sub-category drill-down in the on-screen hint and --help text
- generate_component_registry: send the "wrote ..." progress line to
stderr so it no longer corrupts --concat's stdout output
Two bugs invisible to single-frame rendering, only reachable via the
interactive event loop:
- right/l and left/h resolved the sub-category variable name with
"$toggle_vars[(math ...)]"_(...) inside a quoted string -- fish
cannot expand a command-substitution index there ("Invalid index
value"), so the set never ran and varname silently kept the parent
category variable. Every arrow-key press on a sub-category row
toggled the parent category instead. Fixed by hoisting the category
variable into a plain local first, the same technique the down/j
case already used for its page index.
- __cs_dispatch_draw left panel_h fixed at 16 regardless of what it
actually drew, but the new sub-category page is n+7 lines (9-13,
always < 16). Every redraw/cleanup erase computed its height from
the stale constant, erasing too many rows and corrupting whatever
was above the panel. Fixed by having the dispatcher record the
actual printed height into panel_h after every draw, including
resetting it back to 16 on the value pages even when in_subcat is
stale from a Tab away without an intervening Escape.
Adds __config_settings_draw_subcat.fish, rendering a category's own
toggle plus its sub-category rows, sized dynamically from
__config_settings_subcats instead of the fixed 6-row category layout.
Wires the real per-category row count into config-settings.fish's
up/down handling (replacing Task 17's stub) and adds the
hyphen-to-underscore sub-category variable resolution to the
left/right toggle handlers, mirroring the translation the guard
function already applies.
Two box-drawing bugs surfaced while adapting the design doc's draft to
the real static sub-category data and were fixed rather than
transcribed: the title-dashes offset was off by 5, and several real
sub-category labels/descriptions (e.g. "Notifications", 13 chars;
several descriptions past 30 chars) exceed the narrower width tiers'
fixed field widths, so both fields are now defensively truncated
before padding to keep every row exactly iw+2 wide regardless of
content length.
RETURNS previously conflated fish's $status exit code with genuine
stdout/printed output, e.g. rm listing "0/1" as if they were print
values rather than exit codes. Rename RETURNS to EXIT STATUS across
all 83 documented functions, and reintroduce RETURNS as a distinct
label reserved for the 15 functions that actually print to stdout.
Update build-manual.py's ENTRY_HEADS to render Exit Status before
Returns, manualtools.py's SECTIONS constant, and AGENTS.md's label
order and label-usage guidance to match. Add two verify-manual.py
regression tests: EXIT STATUS bodies must never contain stray
stdout/printed language, and Returns: must always render after
Exit Status: when both are present. Regenerate docs/fish-config.md.
Word-level diff of every manual entry against its generated counterpart
surfaced 546 tokens present in the manual and absent from the header —
losses reconcile.py missed, because it compared description length and
these headers are longer overall thanks to ARGUMENTS/RETURNS.
Merged the substantive ones (546 -> 202 residual tokens, the remainder
being synonym drift). Notable real fixes:
- git-clean: -f/--force was missing from ARGUMENTS entirely
- pkg: per-package-manager query table
- qc: cli-role rationale, role paths, --role passthrough
- config-help: site URL, xdg-open, man page path, case-insensitivity
- agents-init: idempotency, .gitignore paths, upstream pull, wrapper callers
- smart_exit: exit-builtin wiring note, $SCROLLBACK_HISTORY_DIR
The manual's claim that claude/agy pass `agents-init --agents` is stale;
both pass `--quiet` (full setup). Header wins, manual dropped.
Folds the last seven manual entries whose description exceeded their header
back into the source-of-truth comment blocks: config-settings (Sponge/Paths
page detail, list-value parsing, width tiers, navigation keys), fish-deps
(install-method priority, dependency tiers), logs (fzf keybindings, ov
viewer behavior), kitty-logging (symlink wording, C5 inert-vs-uninstalled),
config-update (exec fish reload), yt-dlp (C1 guard). Drops duplicate example
lines left by the previous merge.
Records each documented function's manual category in its own header, so
Section 5 can later be generated from source instead of hand-maintained
alongside it. Values reproduce the current grouping in
docs/manual/05-functions/ exactly; no documentation changes meaning here.
Four functions are skipped because they have no header at all yet
(branch, fc, gitup, sudo-toggle); they get one in the merge that follows.
Extract the user-dots symlink logic into the __fish_user_dots_link helper and
add a dedicated __fish_user_dots_symlink toggle, surfaced as a 'Dots link' bool
row on the config-settings Paths page. Unlike the opinionated categories it has
no universal/session split — it acts on a literal path.
Setting it falsy (or toggling off) stops symlink generation and removes any
existing link immediately, honoured regardless of the C2 master switch.
Creation remains a C2 startup side-effect. config.fish now calls the helper.
Docs: README, fish-config.md (C2 table, Paths page, machine-local section),
and fish-config.index updated.
Replace the fish `read` prompt (which showed an unstyled `read>` and left the
prompt line behind on redraw) with an in-place editor built on the raw key
reader. The value is edited directly in its UI field with a block caret; the
panel redraws each keystroke and cleans up on exit. Pre-fills the current value;
Backspace deletes, Enter saves (empty reverts to default), Esc cancels.
- __config_settings_read_key: decode Backspace (bytes 8/127)
- __config_settings_draw_value: edit-mode field with caret + edit hint line
- config-settings: inline edit loop replaces the read-based prompt block
A blank or escaped inline edit, and the ← clear, previously erased the variable.
sponge reads sponge_delay / sponge_purge_only_on_exit / sponge_allow_previously_
successful with no fallback, so an unset value crashed the prompt
('test: Missing argument'). Fixes:
- Value rows reset to a per-row default value (sponge_delay→2, exit_codes→0) or
erase only when the var tolerates unset (paths, extra-sensitive list).
- Blank/escaped Enter reverts to that default instead of writing empty.
- Sponge booleans are now a 2-state true/false (sponge's convention), never unset.
- Defensive set -q;or set -l fallbacks added to the sponge consumer functions so
a transiently-unset var can never error the prompt.
- C1: sponge_purge_only_on_exit / sponge_allow_previously_successful are 'bool'
rows that write true/false (sponge's convention), not on/off; badge maps
true->ON, false->OFF, unset->DEFAULT
- I1: shorten value-page hint to 49 cols so it fits the 50-wide tier
- M1: set -U -- before the var name guards typed values beginning with a dash
- Add __fish_user_dots_path as 8th entry in vars list
- Update panel_h from 14 to 16 (matches draw function's 16-line output)
- Clamp cur_row down to min(7, ...) to allow navigation to path row
- Add did_redraw flag (reset per iteration) to skip double-redraw after Enter
- Add Enter handler for row 7: erases panel, prompts for path, sets or clears
__fish_user_dots_path universally, redraws, sets did_redraw
- Special-case RIGHT on row 7 as no-op (path is set via Enter only)
- Special-case LEFT on row 7 to clear path var via apply DEFAULT
- Add Enter key hint to --help navigation section
- Fix EXAMPLE block in __config_settings_draw docstring to include 8th arg
rootiest