fix(install): preserve an explicit tuiMode instead of resetting it to fullscreen

[barckcode]

Fixes #1017

Summary

The recognized-global postinstall used to overwrite any tuiMode that was not already "fullscreen", so every package update silently reset an explicit "regular" choice (made through /settings) back to fullscreen. This PR makes the installer treat tuiMode as a settled preference:

• Absent tuiMode → first-install default to "fullscreen" (unchanged experience for fresh installs).
• Explicit tuiMode ("regular", "fullscreen", or any written value) → installer returns changed: false and leaves settings.json byte-identical.

Already-fullscreen settings keep the exact current behavior (byte-identical, same inode), and unowned/project-local installs were never touched and still are not.

Changes

• scripts/install-tui-mode-setting.mjs: short-circuit on any defined tuiMode instead of only "fullscreen".
• tests/install-tui-mode-setting.test.ts:
  • "persists fullscreen" tests now use settings without tuiMode (the actual defaulting scenario).
  • New coverage: an explicit regular is preserved across reruns (both recognized npm and Pi Git paths).
  • "later packages-only save" test now also asserts that a subsequent postinstall rerun (the package-update scenario) keeps the explicit choice.
  • Concurrency, fault-injection, lock-contention, and postinstall-lifecycle tests are unchanged and still pass.
• README.md + docs/readme-reference.md: the install-time fullscreen note now states the default only applies when no tuiMode is set, and that an explicit choice is preserved across updates.

Test evidence

• node --experimental-strip-types --test tests/install-tui-mode-setting.test.ts → 50/50 pass (Node 22.14 local; CI runs Node 24).
• pnpm run typecheck → no regressions against the recorded diagnostic baseline.
• Manual end-to-end: global settings with "tuiMode": "regular" survive installTuiModeSetting() unchanged; settings without tuiMode gain "fullscreen".

Notes for maintainers

• Release/versioning intentionally left untouched (no VERSION bump, no changelog entry) — happy to add a changelog line if you prefer contributions to prepare it.
• If you would rather solve this with an opt-out env var (GENTLE_PI_SKIP_TUI_MODE=1) while keeping the overwrite semantics, say the word and I will rework the branch.

Summary by CodeRabbit

• Documentation

  • Clarified that installation sets fullscreen mode only when no mode is configured.
  • Documented that explicit regular or fullscreen choices remain unchanged across updates.
  • Clarified that skipping native provisioning does not skip the recognized fullscreen default.

• Bug Fixes

  • Installation now preserves explicit regular and fullscreen preferences instead of overwriting them.
  • Unset or unrecognized mode values continue to be replaced with fullscreen.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 0f473424-34d2-463f-85af-f13daa563c17

📥 Commits

Reviewing files that changed from the base of the PR and between 16cd137 and 4d70308.

📒 Files selected for processing (4)

• README.md
• docs/readme-reference.md
• scripts/install-tui-mode-setting.mjs
• tests/install-tui-mode-setting.test.ts

Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

The installer now sets "tuiMode": "fullscreen" only when tuiMode is absent. Explicit values, including "regular", remain unchanged across recognized global postinstalls. Documentation and tests describe and verify this behavior.

Changes

TUI mode preference preservation

Layer / File(s)	Summary
Installation guard and documentation scripts/install-tui-mode-setting.mjs, README.md, docs/readme-reference.md	The recognized global postinstall skips updates when tuiMode is defined. Documentation states that explicit values remain unchanged.
Regression coverage tests/install-tui-mode-setting.test.ts	Tests verify fullscreen creation when tuiMode is missing and preservation of explicit "regular" settings across reruns.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: alan-thegentleman

Merge Risk: ⚪ Minimal · up to 4d703

The installer preserves explicit TUI preferences and self-heals missing or invalid values without affecting project-local installs; no concrete merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: preserving an explicit tuiMode instead of resetting it to fullscreen.
Linked Issues check	✅ Passed	Issue #1017 requires a fullscreen default when tuiMode is absent, preservation of explicit regular and fullscreen values, byte-identical preservation for recognized values, and continued self-he…
Out of Scope Changes check	✅ Passed	The changes stay within Issue #1017. The implementation changes only recognized global tuiMode handling. The tests verify the required behavior, and the README changes document the same defaulting a…
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (2 skipped: 2 …

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}