Skip to content

fix(shell): emit legacy short-int terminfo so macOS less stops warning#319

Merged
forketyfork merged 1 commit into
mainfrom
fix/less-terminfo-legacy-format
May 27, 2026
Merged

fix(shell): emit legacy short-int terminfo so macOS less stops warning#319
forketyfork merged 1 commit into
mainfrom
fix/less-terminfo-legacy-format

Conversation

@forketyfork
Copy link
Copy Markdown
Owner

@forketyfork forketyfork commented May 27, 2026

Summary

less (and other macOS pagers / TUI tools) printed WARNING: terminal is not fully functional / Press RETURN to continue whenever Architect set TERM=xterm-ghostty. more and other tools that skip terminfo lookups stayed silent. The bundled terminfo entry was technically present in ~/.cache/architect/terminfo and resolvable by the Nix-provided infocmp, so the issue looked invisible until you traced which library each tool actually links against.

Root cause

macOS ships libncurses 5.4 inside dyld_shared_cache, and everything in /usr/bin that touches terminfo (less, man, ...) links against it. That library only understands the legacy short-int terminfo file format (magic bytes 0x011a).

Architect bundles xterm-ghostty.terminfo whose source uses use=xterm-256color. When tic resolves that against the Nix ncurses 6.6 terminfo DB, it inherits pairs#0x10000 (65536), which overflows signed 16-bit. tic then has to emit the file in the extended-numbers format (magic bytes 0x021e). The 5.4 library cannot parse that format, so less can't find clear / cup and falls back to the warning.

Solution

Pin pairs#0x7fff (32767 — the largest signed-16-bit value) in the bundled terminfo source ahead of the use= line. The override clamps the inherited capability back into signed-16-bit range, so tic emits the legacy short-int format that the system libncurses can read. 24-bit truecolor (Tc / RGB) and kitty keyboard protocol capabilities are unaffected.

The compiled cache entry is rewritten by ensureTerminfoSetup on every Architect launch, so existing users get the fix automatically the next time they open the app.

Regression test

src/shell.zig adds a new test that writes the embedded terminfo source to a temp dir, runs tic -x against it, and asserts the first two bytes of the compiled file are 0x1a 0x01. The test skips with error.SkipZigTest when tic is not on PATH. Verified: it fails before the fix (gets 0x1e, the long-int marker) and passes after.

Also added _ = @import("shell.zig"); to the root test block in src/main.zig, since shell.zig's tests weren't previously reachable from the test entry point. This incidentally enables the existing pathContainsEntry test, which still passes.

Closes #318

Test plan

  • Pull this branch, delete ~/.cache/architect/terminfo to force a fresh compile, build with zig build, launch Architect.
  • In a spawned terminal session, run git log and confirm the pager opens directly into the log view with no warning prompt above it.
  • In the same session, run less /etc/hosts and man ls — both should open without the warning.
  • Confirm infocmp "$TERM" inside the session resolves the entry and shows pairs#0x7fff near the top.
  • Spot-check that the kitty keyboard protocol still works as before (any feature that relied on it — e.g., modified-arrow key sequences in your editor of choice — should behave the same).

Issue: less-based pagers like git log and man printed "WARNING: terminal
is not fully functional" inside Architect shells, while more stayed
silent. The bundled xterm-ghostty terminfo was unreadable by the libncurses
those tools link against.

Solution: macOS ships libncurses 5.4 inside dyld_shared_cache, and it only
understands the legacy short-int terminfo format (magic 0x011a). Modern
ncurses 6.x ships xterm-256color with pairs#0x10000, which our use=
inherits and forces tic to emit the extended-numbers format (magic 0x021e)
that 5.4 cannot parse. Pin pairs#0x7fff in the bundled source so the
compiled entry stays in signed-16-bit range and tic falls back to the
legacy format. Add a regression test that recompiles the embedded asset
and asserts the magic bytes. 24-bit truecolor and kitty keyboard
capabilities are unaffected.

Closes #318
@forketyfork forketyfork marked this pull request as ready for review May 27, 2026 06:52
@forketyfork forketyfork merged commit 942ae3e into main May 27, 2026
4 checks passed
@forketyfork forketyfork deleted the fix/less-terminfo-legacy-format branch May 27, 2026 07:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: less-based pagers print "terminal is not fully functional" warning in Architect shells

1 participant