feat(config-settings): replace the ANSI renderer with a curses front-end

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).
This commit is contained in:
2026-09-09 14:50:26 -04:00
parent c5d2624a06
commit 078d01666e
15 changed files with 745 additions and 6738 deletions
File diff suppressed because it is too large Load Diff
-285
View File
@@ -1,285 +0,0 @@
#!/usr/bin/env fish
# Copyright (C) 2026 Rootiest
# SPDX-License-Identifier: AGPL-3.0-or-later
#
# Golden-output harness for the config-settings TUI renderer.
#
# fish tests/config-settings-render.fish compare against the golden
# fish tests/config-settings-render.fish --update rewrite the golden
#
# __config_settings_draw, __config_settings_draw_subcat and
# __config_settings_draw_value are hand-tuned layout code: field widths, dash
# counts and pad targets are arithmetic on the width tier, verified by eye once
# and never since. Any refactor of them has to be byte-identical, so this
# renders every page at every width tier, in both scopes, with the cursor on
# every row, and byte-compares the result against a committed baseline.
#
# The golden holds RAW output: the set_color escapes and box drawing exactly as
# the draw functions emit them, plus the \e[<N>A\e[J erase config-settings.fish
# would emit for that panel. Nothing is normalized, folded or pretty-printed --
# the gate is cmp(1) over the bytes, and a one-space change anywhere fails it.
# `diff` is only used to *display* a failure, through cat -v.
#
# Everything runs inside a throwaway HOME/XDG_CONFIG_HOME sandbox. The fixtures
# have to be real universal variables (the Universal page reads universal scope
# through `set --show`), and this repo doubles as a live ~/.config/fish whose
# fish_variables must never be touched by a test run. `fish --no-config` is not
# an option here: under -N, `set -U` silently degrades to global scope, which
# would render the Universal page as all-DEFAULT and prove nothing.
#
# Every external utility below is called through `command`. The outer pass runs
# under the user's real config, which shadows rm (-> trash), cat (-> bat) and
# mkdir, and aliases cp to `cp -i` -- a bare `cp` over an existing golden would
# sit waiting for a confirmation that never comes.
set -l self (command realpath (status filename))
set -l repo (command realpath (command dirname $self)/..)
set -l golden $repo/tests/golden/config-settings-render.txt
# ╭──────────────────────────────────────────────────────────────────────────╮
# │ Outer pass: sandbox, run the render, compare or update │
# ╰──────────────────────────────────────────────────────────────────────────╯
if not set -q CS_RENDER_OUT
set -l sandbox (command mktemp -d)
command mkdir -p $sandbox/home $sandbox/xdg/fish
set -l out (command mktemp)
set -l errf (command mktemp)
# TERM is pinned so set_color emits a fixed sequence set regardless of the
# terminal this runs from; COLUMNS is set per case inside the render pass.
command env -i \
HOME=$sandbox/home \
XDG_CONFIG_HOME=$sandbox/xdg \
PATH="$PATH" \
TERM=xterm-256color \
CS_RENDER_OUT=$out \
fish $self >/dev/null 2>$errf
set -l render_status $status
command rm -rf $sandbox
if test $render_status -ne 0
echo " FAIL render pass exited $render_status"
command cat $errf >&2
command rm -f $out $errf
exit 1
end
set -l cases (command grep -c '^### ' $out)
if contains -- --update $argv
command mkdir -p (command dirname $golden)
command cp $out $golden
echo "golden updated: $cases cases, "(command wc -l <$golden | string trim)" lines, "(command wc -c <$golden | string trim)" bytes"
command rm -f $out $errf
exit 0
end
if not test -f $golden
echo " FAIL no golden at $golden -- run with --update to create it"
command rm -f $out $errf
exit 1
end
if command cmp -s $out $golden
echo "$cases/$cases config-settings render cases byte-identical"
command rm -f $out $errf
exit 0
end
echo " FAIL rendering differs from $golden"
# cat -v only to make the escapes readable in the report; the gate above is
# a raw byte compare, never this.
command diff (command cat -v $golden | psub) (command cat -v $out | psub) | command head -40
command rm -f $out $errf
exit 1
end
# ╭──────────────────────────────────────────────────────────────────────────╮
# │ Render pass (inside the sandbox) │
# ╰──────────────────────────────────────────────────────────────────────────╯
# Sourced, not autoloaded: XDG_CONFIG_HOME points at the empty sandbox. Only
# the draw path is ever called -- __config_settings_apply and
# __config_settings_set_value are defined here and never invoked.
# __fish_palette is sourced too: the draw functions call it (instead of
# declaring $c_head/$c_dim/etc. inline) and it doesn't match the
# __config_settings_* glob, so without this line every draw function's
# colors silently unset and the golden loses all its escape sequences.
source $repo/functions/__fish_palette.fish
for f in $repo/functions/__config_settings_*.fish
source $f
end
set -l toggle_vars \
__fish_config_op_aliases \
__fish_config_op_autoexec \
__fish_config_op_overrides \
__fish_config_op_integrations \
__fish_config_op_logging \
__fish_config_op_greeting \
__fish_config_opinionated
set -l categories $toggle_vars[1..6]
# ── Fixtures ──────────────────────────────────────────────────────────────
# Chosen so every badge branch is live somewhere in the golden: an explicit
# truthy (ON), an explicit falsy (OFF), and an unset variable (DEFAULT). The
# session values deliberately differ from the universal ones so the two pages
# cannot render identically by accident.
set -U __fish_config_op_aliases on
set -U __fish_config_op_autoexec off
set -U __fish_config_op_integrations on
set -U __fish_config_op_logging off
set -U __fish_config_opinionated off
# __fish_config_op_overrides, __fish_config_op_greeting: unset -> DEFAULT
set -g __fish_config_op_aliases off
set -g __fish_config_op_overrides on
set -g __fish_config_op_greeting off
# Sub-category fixtures. "Notifications" is the 13-char label the subcat page's
# label field was widened for; multiplexer-capture exercises the slug's '-'->'_'
# rewrite into a variable name.
set -U __fish_config_op_aliases_filesystem on
set -U __fish_config_op_aliases_search off
set -U __fish_config_op_integrations_notifications on
set -U __fish_config_op_logging_multiplexer_capture off
set -g __fish_config_op_aliases_search on
# Value-page fixtures: one per type badge (INT / LIST / PATH) plus unset rows
# for DEFAULT, plus a value long enough to force `string shorten`'s ellipsis at
# every tier.
set -U sponge_delay 5
set -U sponge_purge_only_on_exit true
set -U sponge_allow_previously_successful false
set -U __fish_sponge_extra_sensitive KOPIA_PASSWORD MY_CORP_AUTH
# sponge_successful_exit_codes: unset -> DEFAULT
set -U __fish_scrollback_history_dir /home/tester/very/long/scrollback/history/directory
set -U __fish_user_dots_path /home/tester/.config/.user-dots/fish
set -U __fish_user_dots_symlink false
# __fish_scrollback_history_max_files: unset -> DEFAULT
# ── Case emitter ──────────────────────────────────────────────────────────
# panel_h is passed in by the caller, independently declaring the expected
# height for each page so it can be cross-checked against the draw functions'
# real output: the category list and both value pages are a fixed 16 lines, a
# sub-category page is 7 + <sub-category count>. The golden records the
# declared height, the measured line count, and the erase sequence derived
# from the declared height -- so flattening the fixed/dynamic divergence, or
# changing a page's height at all, breaks the compare three ways.
function _cs_render_case --argument-names label panel_h
set -l cmd $argv[3..]
set -l t (command mktemp)
$cmd >$t
set -l lines (command wc -l <$t | string trim)
# Wrap-aware erase, byte-for-byte what config-settings.fish emits for a
# panel of this height at this width in the steady state (last_cols ==
# COLUMNS). 78 is the widest box (IW=76 + 2 borders).
set -l pml (math --scale=0 "($COLUMNS + 78) / 2")
set -l eh (math --scale=0 "$panel_h * max(1, ceil($pml / $COLUMNS))")
printf '### %s COLUMNS=%d PANEL_H=%d LINES=%d ERASE=' $label $COLUMNS $panel_h $lines
printf '\e[%dA\e[J' $eh
printf '\n'
command cat $t
command rm -f $t
end
# ── Frame-verb fragments ──────────────────────────────────────────────────
# The shared computations pinned directly, not only through the pages that use
# them. <END> marks the end of each fragment so trailing padding -- which is
# the entire point of a 7-column badge or a 2-column cursor cell -- shows up in
# a diff instead of being invisible whitespace.
function _cs_frame_case --argument-names label
printf '### frame %s\n' $label
$argv[2..]
printf '<END>\n'
end
# ── Cases ─────────────────────────────────────────────────────────────────
# 100 -> IW 76, 88 -> IW 72, 84 -> IW 68, 70 -> IW 50: one COLUMNS value per
# width tier, each a few columns above its threshold.
begin
for cols in 100 88 84 70
set -g COLUMNS $cols
for scope in universal session
for row in (seq 0 6)
_cs_render_case "toggle scope=$scope row=$row" 16 \
__config_settings_draw $row $scope $toggle_vars
end
end
for category in $categories
set -l n (count (__config_settings_subcats $category))
for scope in universal session
for row in (seq 0 $n)
_cs_render_case "subcat cat=$category scope=$scope row=$row" (math 7 + $n) \
__config_settings_draw_subcat $row $scope $category
end
end
end
for row in (seq 0 4)
_cs_render_case "value page=sponge row=$row" 16 \
__config_settings_draw_value $row sponge
end
for row in (seq 0 3)
_cs_render_case "value page=paths row=$row" 16 \
__config_settings_draw_value $row paths
end
# Inline editor: only reachable on non-bool rows. Short buffer, a
# buffer long enough to tail-anchor against the caret, and an empty one.
_cs_render_case "edit page=sponge row=0 buf=short" 16 \
__config_settings_draw_value 0 sponge edit 12
_cs_render_case "edit page=sponge row=4 buf=long" 16 \
__config_settings_draw_value 4 sponge edit "KOPIA_PASSWORD MY_CORP_AUTH ANOTHER_SECRET_NAME"
_cs_render_case "edit page=paths row=0 buf=long" 16 \
__config_settings_draw_value 0 paths edit /home/tester/very/long/scrollback/history/directory
_cs_render_case "edit page=paths row=2 buf=empty" 16 \
__config_settings_draw_value 2 paths edit ""
end
# Emitted last on purpose: everything above is page output, so the page
# section's byte offsets never move when this section grows.
for cols in 100 88 84 70
set -g COLUMNS $cols
_cs_frame_case "width cols=$cols" __config_settings_frame width
end
set -g COLUMNS 100
set -l head (set_color --bold cyan)
set -l rst (set_color normal)
set -l p_test (string repeat -n 11 ' ')
for v in on off DEFAULT ''
_cs_frame_case "badge onoff val=$v" __config_settings_frame badge $v
end
for v in true false DEFAULT
_cs_frame_case "badge boolean val=$v" __config_settings_frame badge $v true false
end
_cs_frame_case "cursor hit" __config_settings_frame cursor 3 3
_cs_frame_case "cursor miss" __config_settings_frame cursor 3 4
_cs_frame_case "title toggle-page" __config_settings_frame title 76 $p_test \
"$head Opinionated Settings $rst"
_cs_frame_case "title subcat-page" __config_settings_frame title 76 $p_test \
"$head Sub-categories: aliases (Universal)$rst "
_cs_frame_case "title value-page" __config_settings_frame title 76 $p_test \
"$head Sponge Settings$rst "
set -l badge_on (__config_settings_frame badge on)
_cs_frame_case "row pad lw=12" __config_settings_frame row 76 $p_test \
(__config_settings_frame cursor 0 0) Aliases 12 $badge_on "cmd shadows" pad
_cs_frame_case "row cut lw=13" __config_settings_frame row 76 $p_test \
(__config_settings_frame cursor 0 1) Notifications 13 $badge_on "done, WakaTime hook" cut
_cs_frame_case "row cut lw=13 overlong" __config_settings_frame row 50 $p_test \
(__config_settings_frame cursor 0 0) Notifications 13 $badge_on \
"ls, cat, cd, du, mkdir, rm, mv, zoxide" cut
_cs_frame_case "row shorten lw=12" __config_settings_frame row 76 $p_test \
(__config_settings_frame cursor 0 0) "Log dir" 12 $badge_on \
/home/tester/very/long/scrollback/history/directory shorten
_cs_frame_case "row shorten lw=12 empty" __config_settings_frame row 50 $p_test \
(__config_settings_frame cursor 1 0) "Log max" 12 $badge_on "" shorten
end >$CS_RENDER_OUT
+33 -10
View File
@@ -2,24 +2,34 @@
# Copyright (C) 2026 Rootiest
# SPDX-License-Identifier: AGPL-3.0-or-later
#
# Gate for the curses config-settings PROTOTYPE (scripts/config-settings-tui.py).
# Gate for the curses config-settings front-end (scripts/config-settings-tui.py).
#
# Runs isolated (no `# MODE:` marker). Two things are checked, and only two:
# Runs isolated (no `# MODE:` marker). Three things are checked here:
#
# 1. python3 can import `curses`. On Arch, Fedora and a full Debian/Ubuntu
# python3 this is stdlib and always true, but python3-minimal alone does
# not carry _curses -- the one portability claim the prototype makes.
# 2. The prototype's own --self-test passes. That covers the pure state
# machine (value cycling, filtering, sub-category lookup, badge and
# ellipsis rendering) with no TTY, which is all a test runner has.
# not carry _curses -- the one portability claim config-settings makes,
# and the reason the function checks the import rather than just `type -q`.
# 2. The TUI's own --self-test passes. That covers the state-dump parser,
# variable-name derivation, toggle cycling, the sub-category-aware filter,
# fish quoting and command emission, with no TTY.
# 3. config-settings still degrades cleanly with no terminal, rather than
# leaving a half-initialised curses screen behind.
#
# The drawing code is deliberately NOT golden-tested. That is the whole
# argument for the prototype: curses owns the cell arithmetic, so there is no
# hand-tuned width/pad/dash math to pin down the way
# test-config-settings-render.fish has to pin the fish renderer's.
# The drawing code is deliberately NOT golden-tested, and the golden harness
# the ANSI renderer needed is gone. That is the point of the rewrite: curses
# owns the cell arithmetic, so there is no hand-tuned width/pad/dash maths left
# to pin down. The seam that does need pinning -- dump in, fish script out --
# is covered here and, for session scope, in tests/test-session.fish.
source (dirname (status filename))/lib.fish
# Isolated suites run under `fish --no-config`, which autoloads nothing from
# this repo. The launcher cases below call config-settings for real, so put the
# repo's functions on the autoload path -- and only that, so nothing in conf.d
# runs and the guard variables stay unset.
set -p fish_function_path $repo_root/functions
set -l tui $repo_root/scripts/config-settings-tui.py
section "config-settings-tui: prerequisites"
@@ -30,4 +40,17 @@ check "python3 ships the curses module" 0 (python3 -c 'import curses' >/dev/null
section "config-settings-tui: self-test"
check "--self-test passes" 0 (python3 $tui --self-test >/dev/null 2>&1; echo $status)
section "config-settings: launcher"
check "--help exits 0" 0 (config-settings --help >/dev/null 2>&1; echo $status)
check "an unknown flag exits 1" 1 (config-settings --nope >/dev/null 2>&1; echo $status)
# stdout is a pipe here, so the isatty guard fires before curses ever starts.
# Without it the TUI would fail deep inside setupterm and leave the terminal
# in whatever state it got to.
function test_no_tty_is_refused_cleanly
set -l out (config-settings 2>&1 >/dev/null | string collect)
string match -q '*needs a terminal*' -- $out
end
check "no TTY is refused with a message, not a curses crash" true (test_no_tty_is_refused_cleanly; and echo true; or echo false)
report
+95 -43
View File
@@ -164,56 +164,108 @@ function test_functions_keep_their_palette
end
check "colored --help output keeps its escape sequences" true (test_functions_keep_their_palette; and echo true; or echo false)
section "session: config-settings diff redraw"
section "session: config-settings state dump"
# Locks in the invariant the diff-redraw renderer depends on: each draw
# function's real line count must match the height config-settings.fish's
# dispatch derives from it (count $new_frame) -- see
# __cs_dispatch_draw in functions/config-settings.fish.
function test_draw_line_count_matches_panel_h
set -l toggle_vars \
__fish_config_op_aliases __fish_config_op_autoexec \
# The curses TUI is a child process: it can neither read the session's global
# variables nor write them, so everything it knows arrives through
# __config_settings_state. These cases run here, in a real loaded session,
# because session scope is exactly what an isolated suite cannot produce.
# Every sub-category __config_settings_subcats knows must reach the dump --
# the TUI does not carry a second copy of the taxonomy, so a category missing
# here is a category the TUI silently cannot show.
function test_state_dump_carries_the_whole_taxonomy
# US/RS have to come from printf: fish does not expand \x escapes inside
# double quotes, so a literal "\x1f" in a pattern matches backslash-x-1-f.
set -l US (printf '\x1f')
set -l dump (__config_settings_state | string split (printf '\x1e'))
set -l want 0
for cvar in __fish_config_op_aliases __fish_config_op_autoexec \
__fish_config_op_overrides __fish_config_op_integrations \
__fish_config_op_logging __fish_config_op_greeting \
__fish_config_opinionated
set -l lines (__config_settings_draw 0 universal $toggle_vars)
if test (count $lines) -ne 16
echo " __config_settings_draw: expected 16 lines, got "(count $lines)
return 1
__fish_config_op_logging __fish_config_op_greeting
set -l n (count (__config_settings_subcats $cvar))
set want (math $want + $n)
set -l got (count (string match -- "sub$US$cvar$US*" $dump))
if test $got -ne $n
echo " $cvar: expected $n sub records, got $got"
return 1
end
end
set -l vlines (__config_settings_draw_value 0 sponge)
if test (count $vlines) -ne 16
echo " __config_settings_draw_value: expected 16 lines, got "(count $vlines)
return 1
end
set -l n (count (__config_settings_subcats __fish_config_op_aliases))
set -l slines (__config_settings_draw_subcat 0 universal __fish_config_op_aliases)
set -l want (math 7 + $n)
if test (count $slines) -ne $want
echo " __config_settings_draw_subcat: expected $want lines, got "(count $slines)
set -l subs (count (string match -- "sub$US*" $dump))
if test $subs -ne $want
echo " expected $want sub records in total, got $subs"
return 1
end
return 0
end
check "draw functions' line counts match their panel heights" true (test_draw_line_count_matches_panel_h; and echo true; or echo false)
check "state dump carries every sub-category" true (test_state_dump_carries_the_whole_taxonomy; and echo true; or echo false)
function test_diff_redraw_unchanged_lines_are_bare_newlines
functions -q __config_settings_diff_redraw; or return 1
set -l old (string join \n -- AAA BBB CCC | string collect)
set -l new (string join \n -- AAA BBB CCC | string collect)
set -l out (__config_settings_diff_redraw "$old" "$new" | string collect -N)
test "$out" = \n\n\n
end
check "diff_redraw: unchanged lines are bare newlines" true (test_diff_redraw_unchanged_lines_are_bare_newlines; and echo true; or echo false)
# Toggles are dumped per scope; value rows are universal-only. A variable that
# is unset must not appear at all -- absence is how the TUI renders DEFAULT.
function test_state_dump_records_both_scopes
set -l US (printf '\x1f')
set -g __fish_config_op_overrides off
set -g sponge_delay 7
set -l dump (__config_settings_state | string split (printf '\x1e'))
set -e __fish_config_op_overrides
set -e sponge_delay
function test_diff_redraw_changed_line_is_cleared_and_rewritten
functions -q __config_settings_diff_redraw; or return 1
set -l old (string join \n -- AAA BBB CCC | string collect)
set -l new (string join \n -- AAA XYZ CCC | string collect)
set -l out (__config_settings_diff_redraw "$old" "$new" | string collect -N)
test "$out" = \n\e\[2K\rXYZ\n\n
set -l failed 0
if test (count (string match -- "var$US""session$US""__fish_config_op_overrides$US""off" $dump)) -ne 1
echo " session toggle missing from the dump"
set failed 1
end
if test (count (string match -- "var$US""universal$US""sponge_delay$US""7" $dump)) -ne 1
echo " value row missing from the dump"
set failed 1
end
if test (count (string match -- "var$US*$US""__fish_config_op_greeting$US*" $dump)) -ne 0
echo " an unset toggle was emitted; absence is what renders DEFAULT"
set failed 1
end
# The conf.d registry data table shares the op_ prefix and is not a setting.
if test (count (string match -- "var$US*$US""__fish_config_op_registry_*" $dump)) -ne 0
echo " the registry data table leaked into the dump"
set failed 1
end
test $failed -eq 0
end
check "diff_redraw: a changed line is cleared and rewritten" true (test_diff_redraw_changed_line_is_cleared_and_rewritten; and echo true; or echo false)
check "state dump records both scopes and omits unset variables" true (test_state_dump_records_both_scopes; and echo true; or echo false)
# The other half of the seam: what the TUI emits has to be runnable fish that
# actually moves the variable. Emitting is Python's job, applying is fish's.
function test_emitted_script_applies
set -l tui $repo_root/scripts/config-settings-tui.py
type -q python3; or return 1
set -l script (python3 $tui --self-test >/dev/null 2>&1; and python3 -c '
import importlib.util, sys
spec = importlib.util.spec_from_file_location("cst", sys.argv[1])
m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
st = m.State("")
st.set("session", "__fish_config_op_greeting", "off")
st.set("universal", "sponge_delay", "11")
sys.stdout.write(m.emit(st, m.rows_by_var()))
' $tui)
or return 1
set -l tmp (command mktemp)
printf '%s\n' $script >$tmp
source $tmp
command rm -f $tmp
set -l failed 0
test "$__fish_config_op_greeting" = off
or begin
echo " sourcing the emitted script did not set the session toggle"
set failed 1
end
test "$sponge_delay" = 11
or begin
echo " sourcing the emitted script did not set the value row"
set failed 1
end
set -e __fish_config_op_greeting
set -Ue sponge_delay 2>/dev/null
test $failed -eq 0
end
check "an emitted script applies when sourced" true (test_emitted_script_applies; and echo true; or echo false)