@codebend3r/che 1.1.0 → 1.2.0

package/bin/install.py

@@ -7,31 +7,31 @@ Run it directly on a fresh machine::
     python3 bin/install.py --yes      # same, no questions asked
 
 or, once the wrappers exist, through the dispatcher: ``che install``,
-``che doctor``, ``che update``, ``che uninstall``.
+``che update``, ``che uninstall``. The machine facts this reads are in
+``machine.py``, the rc-file edits in ``rcfile.py``, and ``che doctor``, which
+checks the result, in ``doctor.py``.
 
-What "installed" means here is deliberately small. Three things go into the
-user's rc file - where the repo is, which python to use, and a line that
-sources the generated wrapper file - between two markers this script owns.
-Everything else (the wrappers themselves, the completions) lives in the repo
-and is regenerated from ``bin/commands.py``, so upgrading never rewrites the
-user's dotfiles.
+What "installed" means here is deliberately small. A few lines go into the
+user's rc file between two markers this script owns: where the repo is, which
+python to use, whether to chime, the line that puts the ``che`` shim on PATH,
+and the line that sources the generated wrapper file. Everything else (the
+wrappers themselves, the completions) lives in the repo and is regenerated
+from ``bin/commands.py``, so upgrading never rewrites the user's dotfiles.
 
 Unlike the destructive scripts under ``bin/<category>/``, this one does NOT
 default to dry-run: it is the entry point that creates the wrappers, so
 defaulting to "change nothing" would leave a first-time user with nothing
 installed and no obvious reason why. ``--dry-run`` is still there, and every
-file it touches is backed up first.
+rc file it edits is backed up first.
 """
 
 from __future__ import annotations
 
+import argparse
 import json
-import os
-import re
 import shutil
-import subprocess
 import sys
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from datetime import datetime
 from pathlib import Path
 
@@ -39,605 +39,60 @@ from pathlib import Path
 # `parent`, where the scripts under bin/<category>/ use `parent.parent`.
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 
-import art
 import shellgen
-from commands import PACKAGE_NAME, REPO, VERSION, all_commands, required_binaries
+from art import print_logo
+from commands import REPO, VERSION, all_commands
+from gitutils import has_tracked_changes
+from machine import (
+    BREW_FORMULA,
+    INSTALL_HINTS,
+    MIN_PYTHON_TEXT,
+    PYTHON_HINT,
+    SHELLS,
+    InstallRecord,
+    config_dir,
+    config_file,
+    default_shell_selection,
+    find_python,
+    is_git_checkout,
+    load_record,
+    login_shell,
+    missing_binaries,
+    python_ok,
+    python_version,
+    save_record,
+    shim_on_path,
+    shim_path,
+    state_dir,
+    tildify,
+    update_command,
+    version_text,
+)
+from rcfile import commit_rc, find_legacy, read_rc, with_block, without_block, without_legacy
 from tui import choose, confirm, is_interactive, palette
-from utils import add_bool_flag, build_parser, info, note, run, success, warning
+from utils import (
+    BoolFlagParser,
+    add_bool_flag,
+    atomic_write_text,
+    build_parser,
+    info,
+    note,
+    run,
+    run_cli,
+    run_output,
+    success,
+    warning,
+)
 
 __version__ = "1.0.0"
 
-MIN_PYTHON = (3, 12)
-
-# Binary -> how to get it. Anything absent from here is either part of macOS or
-# has no obvious one-liner, and doctor says so rather than inventing a command.
-INSTALL_HINTS: dict[str, str] = {
-    "ffmpeg": "brew install ffmpeg",
-    "ffprobe": "brew install ffmpeg",
-    "mpv": "brew install mpv",
-    "exiftool": "brew install exiftool",
-    "gh": "brew install gh",
-    "btop": "brew install btop",
-    "git": "brew install git",
-    "brew": 'bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"',
-}
-
-# Binaries that ship with macOS: never suggest installing them, just report.
-SYSTEM_BINARIES = frozenset({"diskutil", "osascript", "sfltool"})
-
-BREW_FORMULA = {
-    "ffprobe": "ffmpeg",
-    "ffmpeg": "ffmpeg",
-    "mpv": "mpv",
-    "exiftool": "exiftool",
-    "gh": "gh",
-    "btop": "btop",
-    "git": "git",
-}
-
 
 # ---------------------------------------------------------------------------
-# Locations
-#
-# Every path is resolved from the environment at call time, never at import
-# time, so the tests can point HOME at a temporary directory.
+# The PATH shim and external tools
 # ---------------------------------------------------------------------------
 
 
-def home() -> Path:
-    return Path(os.environ.get("HOME", str(Path.home())))
-
-
-def config_dir() -> Path:
-    base = os.environ.get("XDG_CONFIG_HOME") or str(home() / ".config")
-    return Path(base) / "che"
-
-
-def config_file() -> Path:
-    return config_dir() / "config.json"
-
-
-def backup_dir() -> Path:
-    return config_dir() / "backups"
-
-
-def state_dir() -> Path:
-    base = os.environ.get("XDG_STATE_HOME") or str(home() / ".local" / "state")
-    return Path(base) / "che"
-
-
-def shim_path() -> Path:
-    return home() / ".local" / "bin" / "che"
-
-
-# ---------------------------------------------------------------------------
-# Shells
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class ShellTarget:
-    """One shell che can install into, and the rc files it would touch."""
-
-    name: str
-    rc_files: list[Path] = field(default_factory=list)
-    binary: str | None = None
-    is_login_shell: bool = False
-
-    @property
-    def installed(self) -> bool:
-        """Whether the shell itself exists on this machine."""
-        return self.binary is not None
-
-    @property
-    def has_rc(self) -> bool:
-        return any(path.exists() for path in self.rc_files)
-
-
-def login_shell() -> str:
-    return Path(os.environ.get("SHELL", "")).name
-
-
-def _bash_rc_files() -> list[Path]:
-    """Which bash startup files to write.
-
-    macOS Terminal and iTerm start bash as a *login* shell, which reads
-    ``.bash_profile`` and never ``.bashrc``; most Linux terminals do the
-    opposite. Writing to whichever already exist (and to ``.bashrc`` when
-    neither does) covers both without the usual "why isn't my alias there"
-    hunt. The block is idempotent, so a ``.bash_profile`` that sources
-    ``.bashrc`` just defines the same functions twice, harmlessly.
-    """
-    candidates = [home() / ".bashrc", home() / ".bash_profile"]
-    existing = [path for path in candidates if path.exists()]
-    return existing or [home() / ".bashrc"]
-
-
-def _zsh_rc_files() -> list[Path]:
-    zdotdir = os.environ.get("ZDOTDIR")
-    base = Path(zdotdir) if zdotdir else home()
-    return [base / ".zshrc"]
-
-
-def _fish_rc_files() -> list[Path]:
-    base = os.environ.get("XDG_CONFIG_HOME") or str(home() / ".config")
-    return [Path(base) / "fish" / "config.fish"]
-
-
-def _sh_rc_files() -> list[Path]:
-    return [home() / ".profile"]
-
-
-RC_RESOLVERS = {
-    "zsh": _zsh_rc_files,
-    "bash": _bash_rc_files,
-    "fish": _fish_rc_files,
-    "sh": _sh_rc_files,
-}
-
-# `sh` reuses the bash wrapper file: it is plain POSIX shell apart from the
-# completion tail, which is guarded by a $BASH_VERSION test.
-WRAPPER_FOR_SHELL = {"zsh": "zsh", "bash": "bash", "fish": "fish", "sh": "bash"}
-
-
-def detect_shells() -> list[ShellTarget]:
-    """Every supported shell, whether or not it is present on this machine."""
-    current = login_shell()
-    targets = []
-    for name, resolver in RC_RESOLVERS.items():
-        targets.append(
-            ShellTarget(
-                name=name,
-                rc_files=resolver(),
-                binary=shutil.which(name),
-                is_login_shell=(name == current),
-            )
-        )
-    return targets
-
-
-def default_shell_selection(targets: list[ShellTarget]) -> list[str]:
-    """What to install into when the user does not say.
-
-    The login shell always, plus any other shell that is both installed and
-    already has an rc file - those are shells the user demonstrably uses.
-    ``sh``/``.profile`` is opt-in only; writing there affects every POSIX shell
-    on the machine and is rarely what someone means.
-    """
-    chosen = [target.name for target in targets if target.is_login_shell and target.name != "sh"]
-    for target in targets:
-        if target.name in ("sh", *chosen):
-            continue
-        if target.installed and target.has_rc:
-            chosen.append(target.name)
-    return chosen or ["zsh"]
-
-
-# ---------------------------------------------------------------------------
-# Python interpreter
-# ---------------------------------------------------------------------------
-
-
-def python_version(executable: str) -> tuple[int, ...] | None:
-    """Version of another interpreter, or None if it cannot be asked."""
-    if executable == sys.executable:
-        return sys.version_info[:3]
-    try:
-        output = run(
-            [executable, "-c", "import sys; print('.'.join(str(p) for p in sys.version_info[:3]))"],
-            capture=True,
-            check=True,
-            timeout=10,
-        ).stdout
-    except (OSError, subprocess.SubprocessError):
-        return None
-    try:
-        return tuple(int(part) for part in output.strip().split("."))
-    except ValueError:
-        return None
-
-
-def find_python() -> tuple[str, tuple[int, ...] | None]:
-    """Pick the interpreter the wrappers should use.
-
-    The interpreter running this script wins when it is new enough - it is the
-    one the user just proved works. Otherwise fall back to the newest suitable
-    ``python3.X`` on PATH. macOS matters here: ``/usr/bin/python3`` is whatever
-    the Command Line Tools shipped, often years behind the Homebrew python that
-    is also installed.
-    """
-    if sys.version_info[:2] >= MIN_PYTHON:
-        return sys.executable, sys.version_info[:3]
-
-    candidates = ["python3.14", "python3.13", "python3.12", "python3"]
-    for candidate in candidates:
-        resolved = shutil.which(candidate)
-        if not resolved:
-            continue
-        version = python_version(resolved)
-        if version and version[:2] >= MIN_PYTHON:
-            return resolved, version
-
-    return sys.executable, sys.version_info[:3]
-
-
-# ---------------------------------------------------------------------------
-# rc-file surgery
-# ---------------------------------------------------------------------------
-
-BEGIN = shellgen.BEGIN_MARKER
-END = shellgen.END_MARKER
-
-
-def read_rc(path: Path) -> str:
-    try:
-        return path.read_text(encoding="utf-8")
-    except (OSError, UnicodeDecodeError):
-        return ""
-
-
-def find_block(text: str) -> tuple[int, int] | None:
-    """Character span of the managed block, or None when it is not there."""
-    start = text.find(BEGIN)
-    if start < 0:
-        return None
-    end = text.find(END, start)
-    if end < 0:
-        # A truncated block (someone deleted the end marker): treat everything
-        # from the start marker to end of file as ours rather than appending a
-        # second copy that would never be found again.
-        return start, len(text)
-    return start, end + len(END)
-
-
-def backup_file(path: Path, *, dry_run: bool = False) -> Path | None:
-    """Copy ``path`` into the backup directory before it is edited."""
-    if not path.exists():
-        return None
-    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
-    target = backup_dir() / f"{path.name.lstrip('.')}.{stamp}.bak"
-    if dry_run:
-        return target
-    target.parent.mkdir(parents=True, exist_ok=True)
-    shutil.copy2(path, target)
-    return target
-
-
-def apply_block(path: Path, block: str, *, dry_run: bool = False) -> str:
-    """Insert or replace the managed block in ``path``.
-
-    Returns one of ``created``, ``updated``, ``unchanged``. The block goes at
-    the *end* of the file on a fresh install so that its definitions win over
-    anything defined earlier, and stays exactly where it is on an update so a
-    user who moved it keeps their placement.
-    """
-    original = read_rc(path)
-    span = find_block(original)
-
-    if span is None:
-        separator = "" if not original or original.endswith("\n\n") else "\n"
-        if original and not original.endswith("\n"):
-            separator = "\n\n"
-        updated = f"{original}{separator}{block}"
-        action = "created"
-    else:
-        start, end = span
-        if original[start:end].rstrip() == block.rstrip():
-            return "unchanged"
-        updated = original[:start] + block.rstrip("\n") + original[end:]
-        action = "updated"
-
-    if dry_run:
-        return action
-
-    backup_file(path)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(updated, encoding="utf-8")
-    return action
-
-
-def remove_block(path: Path, *, dry_run: bool = False) -> bool:
-    """Take the managed block back out. Returns whether anything changed."""
-    original = read_rc(path)
-    span = find_block(original)
-    if span is None:
-        return False
-    if dry_run:
-        return True
-
-    start, end = span
-    updated = original[:start].rstrip("\n") + "\n" + original[end:].lstrip("\n")
-    backup_file(path)
-    path.write_text(updated, encoding="utf-8")
-    return True
-
-
-# ---------------------------------------------------------------------------
-# Legacy hand-written wrappers
-# ---------------------------------------------------------------------------
-
-LEGACY_VARIABLE = "SHELL_FUNCTIONS_BIN"
-
-_ASSIGNMENT = re.compile(rf"^(?:export\s+)?{LEGACY_VARIABLE}=")
-_FUNCTION_HEAD = re.compile(r"^(?:function\s+)?([A-Za-z0-9_.-]+)\s*\(\)\s*\{$")
-
-
-@dataclass(frozen=True)
-class LegacyBlock:
-    """One hand-written wrapper (or the helper behind it) found in an rc file."""
-
-    start: int
-    end: int
-    name: str
-    body: str
-
-
-def find_legacy(text: str) -> list[str]:
-    """Names of hand-written wrappers in ``text`` that che now generates.
-
-    Before the installer existed, the documented workflow was to copy the
-    repo's ``.zshrc`` wrappers into ``~/.zshrc`` by hand, so most machines have
-    a few dozen of them sitting there. They are harmless - the managed block is
-    appended after, so its definitions win - but they go stale, which is why
-    doctor reports them and ``--replace-legacy`` removes them.
-    """
-    spans, _ = _legacy_spans(text)
-    return [name for _, _, name in spans if name]
-
-
-def _function_blocks(lines: list[str], managed: range) -> list[LegacyBlock]:
-    """Every complete ``name() { … }`` outside the managed block."""
-    blocks: list[LegacyBlock] = []
-    index = 0
-
-    while index < len(lines):
-        if index in managed:
-            index += 1
-            continue
-
-        head = _FUNCTION_HEAD.match(lines[index].strip())
-        if not head:
-            index += 1
-            continue
-
-        depth = 1
-        cursor = index + 1
-        body: list[str] = []
-        while cursor < len(lines) and depth > 0:
-            depth += lines[cursor].count("{") - lines[cursor].count("}")
-            body.append(lines[cursor])
-            cursor += 1
-
-        if depth == 0:
-            blocks.append(LegacyBlock(index, cursor, head.group(1), "\n".join(body)))
-            index = cursor
-            continue
-
-        index += 1
-
-    return blocks
-
-
-def _legacy_spans(text: str) -> tuple[list[tuple[int, int, str]], set[str]]:
-    """Line spans holding legacy wrappers, plus the helper names among them.
-
-    Seeded with everything that mentions ``SHELL_FUNCTIONS_BIN`` directly, then
-    grown: a function that calls a legacy *helper* is legacy too. That second
-    step is what handles a table-driven rc file, where the wrappers are built
-    by an ``_sf`` helper that itself only calls ``_sf_run``.
-
-    Growth deliberately stops at helpers. A function of the user's own that
-    happens to call ``sync-all-branches`` is their automation, not a wrapper,
-    and must survive untouched.
-    """
-    lines = text.splitlines()
-    managed = _managed_line_range(lines)
-    blocks = _function_blocks(lines, managed)
-
-    from commands import wrapper_names
-
-    generated = set(wrapper_names())
-
-    marked = {block for block in blocks if LEGACY_VARIABLE in block.body}
-    helpers = {block.name for block in marked if block.name not in generated}
-
-    while True:
-        grown = {
-            block
-            for block in blocks
-            if block not in marked and any(helper in block.body for helper in helpers)
-        }
-        if not grown:
-            break
-        marked |= grown
-        helpers |= {block.name for block in grown if block.name not in generated}
-
-    spans = [(_extend_upwards(lines, block.start), block.end, block.name) for block in marked]
-    spans += [
-        (_extend_upwards(lines, index), index + 1, "")
-        for index, line in enumerate(lines)
-        if index not in managed and _ASSIGNMENT.match(line.strip())
-    ]
-    return sorted(spans), helpers
-
-
-def _extend_upwards(lines: list[str], start: int) -> int:
-    """Pull the comment block that documents a wrapper into its span.
-
-    Every wrapper in the old ``.zshrc`` had a banner or a sentence above it.
-    Removing the function but leaving its comment behind produces a file full
-    of headings with nothing under them, so the span starts at the first line
-    of the attached comment instead. The walk stops at the first line that is
-    neither a comment nor the single blank line between a banner and what it
-    introduces, so a comment belonging to code that stays is never taken.
-    """
-    cursor = start
-    if cursor > 0 and not lines[cursor - 1].strip():
-        cursor -= 1
-    while cursor > 0 and lines[cursor - 1].lstrip().startswith("#"):
-        cursor -= 1
-    return cursor if lines[cursor].lstrip().startswith("#") else start
-
-
-def find_shadowing(text: str) -> list[tuple[str, str]]:
-    """Names in ``text`` that would win over a generated wrapper.
-
-    Two ways that happens, both silent: an alias of the same name (in zsh and
-    bash an alias is resolved before a function, so `alias remove-metadata=...`
-    makes the wrapper dead code), and a function redefined *after* the managed
-    block, since the last definition wins. Definitions before the block are
-    fine, so they are not reported.
-    """
-    from commands import wrapper_names
-
-    names = set(wrapper_names())
-    span = find_block(text)
-    block_end = span[1] if span else len(text)
-
-    alias_pattern = re.compile(r"^alias\s+([A-Za-z0-9_.-]+)=")
-    function_pattern = re.compile(r"^(?:function\s+)?([A-Za-z0-9_.-]+)\s*(?:\(\))?\s*\{")
-
-    found: list[tuple[str, str]] = []
-    offset = 0
-    for line in text.splitlines(keepends=True):
-        stripped = line.strip()
-        start_of_line, offset = offset, offset + len(line)
-
-        alias = alias_pattern.match(stripped)
-        if alias and alias.group(1) in names:
-            found.append((alias.group(1), "alias"))
-            continue
-
-        if start_of_line <= block_end:
-            # Defined before or inside our block: ours is sourced later and
-            # wins, so there is nothing to report.
-            continue
-
-        definition = function_pattern.match(stripped)
-        if definition and definition.group(1) in names:
-            found.append((definition.group(1), "redefined after the block"))
-
-    return found
-
-
-def _managed_line_range(lines: list[str]) -> range:
-    """Line indices covered by the managed block, so stripping never enters it."""
-    begin = end = None
-    for index, line in enumerate(lines):
-        if line.startswith(BEGIN):
-            begin = index
-        elif line.startswith(END):
-            end = index
-    if begin is None:
-        return range(0, 0)
-    return range(begin, (end if end is not None else len(lines) - 1) + 1)
-
-
-def _consecutive_groups(indices: list[int]) -> list[list[int]]:
-    groups: list[list[int]] = []
-    for index in sorted(indices):
-        if groups and index == groups[-1][-1] + 1:
-            groups[-1].append(index)
-        else:
-            groups.append([index])
-    return groups
-
-
-def strip_legacy(path: Path, *, dry_run: bool = False) -> list[str]:
-    """Remove legacy wrappers from ``path``; returns the names removed.
-
-    Two passes. The first drops the ``SHELL_FUNCTIONS_BIN`` assignment, every
-    function that used it, and the helpers those functions were built from,
-    along with the comment documenting each. The second drops the lines that
-    *call* a removed helper - which is what makes a table-driven ``~/.zshrc``
-    safe to clean: removing an ``_sf`` helper while leaving its forty
-    ``_sf <name> …`` lines behind would turn every new shell into forty
-    "command not found" errors.
-
-    Calls to removed *wrappers* are never touched, only calls to helpers. A
-    line of the user's own that runs ``mount-all-drives`` at login is theirs.
-    """
-    original = read_rc(path)
-    spans, helpers = _legacy_spans(original)
-    if not spans:
-        return []
-
-    removed = [name for _, _, name in spans if name]
-    lines = original.splitlines()
-    managed = _managed_line_range(lines)
-
-    drop: set[int] = set()
-    for span_start, span_end, _ in spans:
-        drop.update(range(span_start, span_end))
-
-    callers = [
-        index
-        for index, line in enumerate(lines)
-        if index not in drop and index not in managed and line.strip().split(" ")[0] in helpers
-    ]
-    for group in _consecutive_groups(callers):
-        drop.update(range(_extend_upwards(lines, group[0]), group[-1] + 1))
-
-    if dry_run:
-        return removed
-
-    kept = [line for index, line in enumerate(lines) if index not in drop]
-
-    # Collapse the runs of blank lines the removal leaves behind, so the rc
-    # file does not end up with a hole in it.
-    tidied: list[str] = []
-    for line in kept:
-        if not line.strip() and tidied and not tidied[-1].strip():
-            continue
-        tidied.append(line)
-
-    backup_file(path)
-    path.write_text("\n".join(tidied).rstrip("\n") + "\n", encoding="utf-8")
-    return removed
-
-
-# ---------------------------------------------------------------------------
-# Generated files and the PATH shim
-# ---------------------------------------------------------------------------
-
-
-def _expected_files() -> dict[Path, str]:
-    """Every generated path mapped to the contents the manifest implies.
-
-    ``shell/`` is generated whole. The README is generated in place: only the
-    marked islands are replaced, so its prose survives.
-    """
-    expected = dict(shellgen.generated_files())
-
-    readme = REPO / shellgen.README
-    if readme.exists():
-        expected[shellgen.README] = shellgen.render_readme(readme.read_text(encoding="utf-8"))
-
-    return expected
-
-
-def write_generated(*, dry_run: bool = False) -> list[Path]:
-    """Refresh the generated files; returns the ones that changed."""
-    changed = []
-    for relative, contents in _expected_files().items():
-        target = REPO / relative
-        if target.exists() and target.read_text(encoding="utf-8") == contents:
-            continue
-        changed.append(relative)
-        if not dry_run:
-            target.parent.mkdir(parents=True, exist_ok=True)
-            target.write_text(contents, encoding="utf-8")
-    return changed
-
-
-def check_generated() -> list[Path]:
-    """Generated files that differ from what the manifest would produce."""
-    stale = []
-    for relative, contents in _expected_files().items():
-        target = REPO / relative
-        if not target.exists() or target.read_text(encoding="utf-8") != contents:
-            stale.append(relative)
-    return stale
+SHIM_HEADER = "# Generated by `che install`"
 
 
 def install_shim(python: str, *, dry_run: bool = False) -> str:
@@ -645,71 +100,44 @@ def install_shim(python: str, *, dry_run: bool = False) -> str:
 
     The shell function is what a human types; this shim is what a cron job, a
     Makefile or another script can call, none of which source an rc file.
+
+    A ``che`` that is a symlink is never written through. With an npm prefix of
+    ``~/.local``, ``npm install -g`` links it straight to ``bin/che.py``, and
+    writing through that link would replace the dispatcher with a shim that
+    execs itself. A link to this repo's dispatcher already does the shim's job;
+    any other link is replaced, not followed.
     """
     target = shim_path()
+    dispatcher = REPO / "bin" / "che.py"
     script = (
         "#!/bin/sh\n"
-        f"# Generated by `che install` (che {VERSION}). Do not edit.\n"
-        f'exec {json.dumps(python)} {json.dumps(str(REPO / "bin" / "che.py"))} "$@"\n'
+        f"{SHIM_HEADER} (che {VERSION}). Do not edit.\n"
+        f'exec {json.dumps(python)} {json.dumps(str(dispatcher))} "$@"\n'
     )
 
-    if target.exists() and target.read_text(encoding="utf-8") == script:
+    if target.is_symlink():
+        if target.resolve() == dispatcher.resolve():
+            return "unchanged"
+        if not dry_run:
+            target.unlink()
+    elif target.exists() and target.read_text(encoding="utf-8", errors="replace") == script:
         return "unchanged"
-    if dry_run:
-        return "installed"
-
-    target.parent.mkdir(parents=True, exist_ok=True)
-    target.write_text(script, encoding="utf-8")
-    target.chmod(0o755)
+    if not dry_run:
+        atomic_write_text(target, script, mode=0o755)
     return "installed"
 
 
-def shim_on_path() -> bool:
-    entries = os.environ.get("PATH", "").split(os.pathsep)
-    return str(shim_path().parent) in entries
-
-
-# ---------------------------------------------------------------------------
-# Config
-# ---------------------------------------------------------------------------
-
-
-def load_config() -> dict:
-    try:
-        return json.loads(config_file().read_text(encoding="utf-8"))
-    except (OSError, ValueError):
-        return {}
-
-
-def save_config(config: dict, *, dry_run: bool = False) -> None:
-    if dry_run:
-        return
-    config_dir().mkdir(parents=True, exist_ok=True)
-    config_file().write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
-
-
-# ---------------------------------------------------------------------------
-# Dependencies
-# ---------------------------------------------------------------------------
-
-
-def binary_status() -> dict[str, dict]:
-    """Every external binary the commands need, and whether it is present."""
-    status = {}
-    for binary, users in required_binaries().items():
-        resolved = shutil.which(binary)
-        status[binary] = {
-            "path": resolved,
-            "present": bool(resolved),
-            "commands": list(users),
-            "hint": INSTALL_HINTS.get(binary, ""),
-            "system": binary in SYSTEM_BINARIES,
-        }
-    return status
+def is_che_shim(path: Path) -> bool:
+    """Whether ``path`` is a shim ``che install`` wrote, not a link or a stranger's file."""
+    return (
+        not path.is_symlink()
+        and path.is_file()
+        and SHIM_HEADER in path.read_text(encoding="utf-8", errors="replace")
+    )
 
 
 def install_missing_binaries(names: list[str], *, dry_run: bool = False) -> bool:
-    """Install missing tools with Homebrew. Returns whether it ran cleanly."""
+    """Install missing tools with Homebrew. Returns whether every one went in."""
     formulae = sorted({BREW_FORMULA[name] for name in names if name in BREW_FORMULA})
     if not formulae:
         return True
@@ -736,218 +164,117 @@ class InstallPlan:
     shells: list[str]
     python: str
     sounds: bool = True
-    completions: bool = True
     path_shim: bool = True
     replace_legacy: bool = False
     dry_run: bool = False
 
+    def to_record(self, rc_files: list[Path]) -> InstallRecord:
+        """What ``config.json`` keeps, so ``che update`` can repeat this install."""
+        return InstallRecord(
+            version=VERSION,
+            home=str(REPO),
+            python=self.python,
+            shells=self.shells,
+            rc_files=[str(path) for path in rc_files],
+            sounds=self.sounds,
+            path_shim=self.path_shim,
+            installed_at=datetime.now().isoformat(timespec="seconds"),
+        )
+
+    @classmethod
+    def from_record(cls, record: InstallRecord, *, python: str, dry_run: bool) -> InstallPlan:
+        """The plan that repeats a recorded install under ``python``."""
+        return cls(
+            shells=list(record.shells),
+            python=python,
+            sounds=record.sounds,
+            path_shim=record.path_shim,
+            dry_run=dry_run,
+        )
+
 
 @dataclass
 class InstallResult:
     rc_actions: list[tuple[Path, str]] = field(default_factory=list)
     generated: list[Path] = field(default_factory=list)
-    legacy_removed: dict[str, list[str]] = field(default_factory=dict)
+    legacy_removed: dict[Path, list[str]] = field(default_factory=dict)
     shim: str = "skipped"
 
 
+def block_for(shell: str, plan: InstallPlan) -> str:
+    """The rc block ``plan`` writes for ``shell``, and so what ``--print`` shows."""
+    return shellgen.rc_block(
+        SHELLS[shell].flavor,
+        home=REPO,
+        python=plan.python,
+        sounds=plan.sounds,
+        path_dir=shim_path().parent if plan.path_shim else None,
+    )
+
+
 def perform_install(plan: InstallPlan) -> InstallResult:
     """Do the install described by ``plan``. No prompting happens here."""
     result = InstallResult()
-    result.generated = write_generated(dry_run=plan.dry_run)
-
-    targets = {target.name: target for target in detect_shells()}
+    try:
+        result.generated = shellgen.sync_generated(dry_run=plan.dry_run)
+    except ValueError as exc:
+        # The README lost a marker. The committed shell/ files still work, so
+        # the rc blocks that point at them can still be written.
+        warning(f"❌ {exc}")
 
     for shell in plan.shells:
-        target = targets.get(shell)
-        if target is None:
+        spec = SHELLS.get(shell)
+        if spec is None:
             warning(f"❌ Unknown shell: {shell}")
             continue
 
-        block = shellgen.rc_block(
-            WRAPPER_FOR_SHELL[shell],
-            home=REPO,
-            python=plan.python,
-            sounds=plan.sounds,
-        )
-        if plan.path_shim and shell != "fish":
-            block = _with_path_line(block)
-        elif plan.path_shim and shell == "fish":
-            block = _with_fish_path_line(block)
-
-        for rc_file in target.rc_files:
+        block = block_for(shell, plan)
+        for rc_file in spec.rc_files:
+            original = text = read_rc(rc_file)
             if plan.replace_legacy:
-                removed = strip_legacy(rc_file, dry_run=plan.dry_run)
+                text, removed = without_legacy(text)
                 if removed:
-                    result.legacy_removed[str(rc_file)] = removed
-            action = apply_block(rc_file, block, dry_run=plan.dry_run)
+                    result.legacy_removed[rc_file] = removed
+            updated, action = with_block(text, block)
+            commit_rc(rc_file, original, updated, dry_run=plan.dry_run)
             result.rc_actions.append((rc_file, action))
 
     if plan.path_shim:
         result.shim = install_shim(plan.python, dry_run=plan.dry_run)
 
-    save_config(
-        {
-            "version": VERSION,
-            "home": str(REPO),
-            "python": plan.python,
-            "shells": plan.shells,
-            "rc_files": [str(path) for path, _ in result.rc_actions],
-            "sounds": plan.sounds,
-            "completions": plan.completions,
-            "path_shim": plan.path_shim,
-            "installed_at": datetime.now().isoformat(timespec="seconds"),
-        },
-        dry_run=plan.dry_run,
-    )
+    save_record(plan.to_record([path for path, _ in result.rc_actions]), dry_run=plan.dry_run)
     return result
 
 
-def _with_path_line(block: str) -> str:
-    """Add ``~/.local/bin`` to PATH inside the managed block, idempotently."""
-    directory = str(shim_path().parent)
-    line = f'case ":$PATH:" in *":{directory}:"*) ;; *) PATH="{directory}:$PATH" ;; esac'
-    return block.replace(END, f"{line}\n{END}")
-
-
-def _with_fish_path_line(block: str) -> str:
-    directory = str(shim_path().parent)
-    line = f'if not contains "{directory}" $PATH\n    set -gx PATH "{directory}" $PATH\nend'
-    return block.replace(shellgen.END_MARKER, f"{line}\n{shellgen.END_MARKER}")
-
+def run_install(plan: InstallPlan, *, install_deps: bool = False) -> int:
+    """Install, say what happened, then fetch the missing tools when asked to.
 
-# ---------------------------------------------------------------------------
-# The first-run wizard
-# ---------------------------------------------------------------------------
-
-
-def print_logo(subtitle: str = "") -> None:
-    """The face beside the wordmark, with ``subtitle`` under the letters."""
-    colors = palette()
-    right = art.wordmark(colors)
-    if subtitle:
-        right.append(f"  {colors.grey}{subtitle}{colors.reset}")
-    for line in art.banner(right, colors=colors):
-        print(line)
+    Returns the exit status: 1 when a tool the user asked for did not install.
+    """
+    report(plan, perform_install(plan))
+    missing = missing_binaries() if install_deps else []
+    if not missing:
+        return 0
     print()
+    return 0 if install_missing_binaries(missing, dry_run=plan.dry_run) else 1
 
 
-def wizard(*, dry_run: bool = False) -> int:
-    """Walk a first-time user through the whole setup."""
-    colors = palette()
-    print_logo(f"shell helpers, v{VERSION} - first-run setup")
+def require_python() -> str | None:
+    """The interpreter the wrappers will run, or None, said why, when none is new enough.
 
+    Writing a too-old one into every rc block would break every wrapper at once.
+    """
     python, version = find_python()
-    version_text = ".".join(str(part) for part in (version or ()))
-    if not version or version[:2] < MIN_PYTHON:
-        warning(
-            f"❌ Python {'.'.join(str(p) for p in MIN_PYTHON)}+ is required (found {version_text})."
-        )
-        note("   Install one with `brew install python@3.13`, then run this again.")
-        return 1
-
-    print(
-        f"  {colors.green}✓{colors.reset} python {version_text}  {colors.grey}{python}{colors.reset}"
-    )
-    print(f"  {colors.green}✓{colors.reset} repo    {colors.grey}{REPO}{colors.reset}")
-    print(f"  {colors.green}✓{colors.reset} {len(all_commands())} commands ready to wrap")
-    print()
-
-    targets = detect_shells()
-    selectable = [target for target in targets if target.installed or target.has_rc]
-    if not selectable:
-        selectable = [target for target in targets if target.name == "zsh"]
-
-    preselected = default_shell_selection(targets)
-    options = []
-    for target in selectable:
-        rc_names = ", ".join(str(path).replace(str(home()), "~") for path in target.rc_files)
-        label = target.name + ("  (your login shell)" if target.is_login_shell else "")
-        options.append((label, rc_names))
-
-    picked = choose(
-        "Which shells should che install into?",
-        options,
-        selected=[index for index, target in enumerate(selectable) if target.name in preselected],
-    )
-    if not picked:
-        warning("Nothing selected - install cancelled.")
-        return 1
-    shells = [selectable[index].name for index in picked]
+    if python_ok(version):
+        return python
+    warning(f"❌ Python {MIN_PYTHON_TEXT}+ is required (found {version_text(version)}).")
+    note(f"   Install one with `{PYTHON_HINT}`, then run this again.")
+    return None
 
-    print()
-    path_shim = confirm(
-        f"Add a `che` command to {str(shim_path()).replace(str(home()), '~')} "
-        "so scripts and cron can call it?",
-        default=True,
-    )
-    sounds = confirm("Play the playsound-N chime when a command finishes?", default=True)
-
-    legacy_found = {
-        rc_file: find_legacy(read_rc(rc_file))
-        for target in targets
-        if target.name in shells
-        for rc_file in target.rc_files
-        if find_legacy(read_rc(rc_file))
-    }
-    replace_legacy = False
-    if legacy_found:
-        print()
-        total = sum(len(names) for names in legacy_found.values())
-        note(f"Found {total} hand-written wrappers from before che managed them:")
-        for rc_file, names in legacy_found.items():
-            print(
-                f"  {colors.grey}{rc_file}: {', '.join(names[:6])}"
-                f"{'…' if len(names) > 6 else ''}{colors.reset}"
-            )
-        replace_legacy = confirm(
-            "Replace them with the generated ones? (a backup is written first)", default=True
-        )
-
-    missing = [
-        name
-        for name, entry in binary_status().items()
-        if not entry["present"] and not entry["system"]
-    ]
-    install_deps = False
-    if missing:
-        print()
-        note(f"Missing external tools: {', '.join(missing)}")
-        for name in missing:
-            hint = INSTALL_HINTS.get(name)
-            if hint:
-                print(f"  {colors.grey}{name}: {hint}{colors.reset}")
-        if shutil.which("brew"):
-            install_deps = confirm("Install them now with Homebrew?", default=False)
-
-    print()
-    plan = InstallPlan(
-        shells=shells,
-        python=python,
-        sounds=sounds,
-        path_shim=path_shim,
-        replace_legacy=replace_legacy,
-        dry_run=dry_run,
-    )
-    result = perform_install(plan)
-    report(plan, result)
-
-    if install_deps:
-        print()
-        install_missing_binaries(missing, dry_run=dry_run)
-
-    print()
-    success("Done. Start using it with:")
-    print(
-        f"  {colors.bold}exec {shells[0]}{colors.reset}   {colors.grey}(reload your shell){colors.reset}"
-    )
-    print(
-        f"  {colors.bold}che{colors.reset}          {colors.grey}(browse every command){colors.reset}"
-    )
-    print(
-        f"  {colors.bold}che doctor{colors.reset}   {colors.grey}(check the install){colors.reset}"
-    )
-    return 0
 
+# ---------------------------------------------------------------------------
+# Reporting
+# ---------------------------------------------------------------------------
 
 # Past tense for what happened, present tense for what a dry run would do.
 DRY_VERB = {
@@ -960,45 +287,47 @@ DRY_VERB = {
 }
 
 
-def report(plan: InstallPlan, result: InstallResult) -> None:
-    """Print what an install did, in the same shape for wizard and --yes."""
+def phrase(action: str, *, dry_run: bool) -> str:
+    """``action`` as done, or as what a dry run would do."""
+    if not dry_run:
+        return action
     colors = palette()
+    return f"{colors.yellow}would {DRY_VERB.get(action, action)}{colors.reset}"
+
 
-    def phrase(action: str) -> str:
-        if not plan.dry_run:
-            return action
-        return f"{colors.yellow}would {DRY_VERB.get(action, action)}{colors.reset}"
+def mark(action: str = "") -> str:
+    """What starts a report line: a grey ``=`` for something left alone, else a ``✓``."""
+    colors = palette()
+    if action == "unchanged":
+        return f"{colors.grey}={colors.reset}"
+    return f"{colors.green}✓{colors.reset}"
 
-    def short(path: Path) -> str:
-        return str(path).replace(str(home()), "~")
+
+def report(plan: InstallPlan, result: InstallResult) -> None:
+    """Print what an install did, in the same shape for wizard and --yes."""
+    colors = palette()
+    dry_run = plan.dry_run
 
     for rc_file, action in result.rc_actions:
-        mark = (
-            f"{colors.grey}={colors.reset}"
-            if action == "unchanged"
-            else f"{colors.green}✓{colors.reset}"
-        )
-        print(f"  {mark} {phrase(action)} block in {short(rc_file)}")
+        print(f"  {mark(action)} {phrase(action, dry_run=dry_run)} block in {tildify(rc_file)}")
 
     for rc_file, names in result.legacy_removed.items():
         print(
-            f"  {colors.green}✓{colors.reset} {phrase('removed')} "
-            f"{len(names)} legacy wrappers from {short(Path(rc_file))}"
+            f"  {mark()} {phrase('removed', dry_run=dry_run)} "
+            f"{len(names)} legacy wrappers from {tildify(rc_file)}"
         )
 
     if result.generated:
         print(
-            f"  {colors.green}✓{colors.reset} {phrase('regenerated')} "
+            f"  {mark()} {phrase('regenerated', dry_run=dry_run)} "
             f"{len(result.generated)} files under shell/"
         )
 
     if plan.path_shim:
-        mark = (
-            f"{colors.grey}={colors.reset}"
-            if result.shim == "unchanged"
-            else f"{colors.green}✓{colors.reset}"
+        print(
+            f"  {mark(result.shim)} che shim {phrase(result.shim, dry_run=dry_run)}: "
+            f"{tildify(shim_path())}"
         )
-        print(f"  {mark} che shim {phrase(result.shim)}: {short(shim_path())}")
         if not shim_on_path():
             print(
                 f"  {colors.grey}  ({shim_path().parent} is added to PATH by the block){colors.reset}"
@@ -1006,182 +335,119 @@ def report(plan: InstallPlan, result: InstallResult) -> None:
 
 
 # ---------------------------------------------------------------------------
-# Doctor
+# The first-run wizard
 # ---------------------------------------------------------------------------
 
-OK, WARN, FAIL = "ok", "warn", "fail"
 
+def wizard(plan: InstallPlan, *, install_deps: bool = False) -> int:
+    """Walk a first-time user through the whole setup.
 
-def diagnose() -> list[dict]:
-    """Collect every check as data, so both the table and --json use one source."""
-    checks: list[dict] = []
-    config = load_config()
+    ``plan`` is what is already decided. It preselects the shells, and a
+    question it already answers - ``--no-sounds``, ``--no-path-shim``,
+    ``--replace-legacy`` or ``install_deps`` - is not asked again.
+    """
+    colors = palette()
+    print_logo(f"shell helpers, v{VERSION} - first-run setup")
 
-    python, version = find_python()
-    version_text = ".".join(str(part) for part in (version or ()))
-    checks.append(
-        {
-            "name": "python",
-            "status": OK if version and version[:2] >= MIN_PYTHON else FAIL,
-            "detail": f"{version_text} ({python})",
-            "fix": "brew install python@3.13",
-        }
-    )
+    version = python_version(plan.python) or ()
+    print(f"  {mark()} python {version_text(version)}  {colors.grey}{plan.python}{colors.reset}")
+    print(f"  {mark()} repo    {colors.grey}{REPO}{colors.reset}")
+    print(f"  {mark()} {len(all_commands())} commands ready to wrap")
+    print()
 
-    checks.append(
-        {
-            "name": "repo",
-            "status": OK if (REPO / "bin" / "che.py").exists() else FAIL,
-            "detail": str(REPO),
-            "fix": "re-clone the repo",
-        }
-    )
+    shells = _ask_shells(plan.shells)
+    if not shells:
+        warning("Nothing selected - install cancelled.")
+        return 1
 
-    stale = check_generated()
-    checks.append(
-        {
-            "name": "generated files",
-            "status": OK if not stale else WARN,
-            "detail": "current"
-            if not stale
-            else f"{len(stale)} out of date: " + ", ".join(str(path) for path in stale),
-            "fix": "che install",
-        }
+    print()
+    path_shim = plan.path_shim and confirm(
+        f"Add a `che` command to {tildify(shim_path())} so scripts and cron can call it?",
+        default=True,
     )
-
-    installed_version = config.get("version")
-    checks.append(
-        {
-            "name": "install record",
-            "status": OK if installed_version == VERSION else (WARN if config else FAIL),
-            "detail": f"config {installed_version or 'missing'} vs che {VERSION}",
-            "fix": "che install",
-        }
+    sounds = plan.sounds and confirm(
+        "Play the playsound-N chime when a command finishes?", default=True
     )
-
-    # Only the shells this install actually targets. Reporting on every shell
-    # present would flag ~/.profile as "missing" on any machine with /bin/sh,
-    # which is every machine.
-    watched = set(config.get("shells") or default_shell_selection(detect_shells()))
-    watched.add(login_shell())
-
-    for target in detect_shells():
-        if target.name not in watched:
-            continue
-        for rc_file in target.rc_files:
-            text = read_rc(rc_file)
-            has_block = find_block(text) is not None
-            legacy = find_legacy(text)
-            status = OK if has_block else (WARN if target.name == "sh" else FAIL)
-            detail = "block installed" if has_block else "no che block"
-            if legacy:
-                status = WARN if has_block else status
-                detail += f", {len(legacy)} legacy wrappers"
-
-            shadowing = find_shadowing(text)
-            if shadowing:
-                status = WARN if status == OK else status
-                detail += ", shadowed: " + ", ".join(
-                    f"{name} ({how})" for name, how in shadowing[:3]
-                )
-                shadow_fix = (
-                    "the alias wins at the prompt; run `\\name` for the wrapper, "
-                    "or remove the alias"
-                    if any(how == "alias" for _, how in shadowing)
-                    else "move your definition above the che block"
-                )
-            checks.append(
-                {
-                    "name": f"{target.name}: {str(rc_file).replace(str(home()), '~')}",
-                    "status": status,
-                    "detail": detail,
-                    "fix": (
-                        "che install --replace-legacy"
-                        if legacy
-                        else (shadow_fix if shadowing else "che install")
-                    ),
-                }
-            )
-
-    shim = shim_path()
-    if shim.exists() and shim_on_path():
-        shim_status, shim_detail, shim_fix = OK, str(shim), ""
-    elif shim.exists():
-        shim_status = WARN
-        shim_detail = f"{shim} (PATH picks it up on your next shell)"
-        shim_fix = f"exec {login_shell() or 'zsh'}"
-    else:
-        shim_status, shim_detail, shim_fix = WARN, "not installed", "che install"
-    checks.append(
-        {"name": "che on PATH", "status": shim_status, "detail": shim_detail, "fix": shim_fix}
+    replace_legacy = plan.replace_legacy or _ask_legacy(shells)
+    install_deps = install_deps or _ask_tools()
+    plan = replace(
+        plan, shells=shells, path_shim=path_shim, sounds=sounds, replace_legacy=replace_legacy
     )
 
-    for binary, entry in binary_status().items():
-        used_by = ", ".join(entry["commands"][:3])
-        if len(entry["commands"]) > 3:
-            used_by += f" +{len(entry['commands']) - 3}"
-        checks.append(
-            {
-                "name": f"tool: {binary}",
-                "status": OK if entry["present"] else WARN,
-                "detail": entry["path"] or f"missing - needed by {used_by}",
-                "fix": entry["hint"],
-            }
-        )
+    print()
+    status = run_install(plan, install_deps=install_deps)
 
-    missing_scripts = [
-        command.name
-        for command in all_commands()
-        if command.script and not (REPO / "bin" / command.script).exists()
-    ]
-    checks.append(
-        {
-            "name": "scripts",
-            "status": OK if not missing_scripts else FAIL,
-            "detail": f"{len(all_commands())} commands"
-            + ("" if not missing_scripts else f", missing: {', '.join(missing_scripts)}"),
-            "fix": update_command(),
-        }
+    print()
+    success("Done. Start using it with:")
+    print(
+        f"  {colors.bold}exec {shells[0]}{colors.reset}   {colors.grey}(reload your shell){colors.reset}"
+    )
+    print(
+        f"  {colors.bold}che{colors.reset}          {colors.grey}(browse every command){colors.reset}"
     )
+    print(
+        f"  {colors.bold}che doctor{colors.reset}   {colors.grey}(check the install){colors.reset}"
+    )
+    return status
 
-    return checks
 
+def _ask_shells(preselected: list[str]) -> list[str]:
+    """The shells to install into: those present on this machine, ``preselected`` ticked."""
+    specs = list(SHELLS.values())
+    selectable = [spec for spec in specs if spec.installed or spec.has_rc] or [SHELLS["zsh"]]
+    picked = choose(
+        "Which shells should che install into?",
+        [
+            (
+                spec.name + ("  (your login shell)" if spec.is_login_shell else ""),
+                ", ".join(tildify(path) for path in spec.rc_files),
+            )
+            for spec in selectable
+        ],
+        selected=[index for index, spec in enumerate(selectable) if spec.name in preselected],
+    )
+    return [selectable[index].name for index in picked]
 
-def doctor(*, as_json: bool = False, verbose: bool = False) -> int:
-    checks = diagnose()
 
-    if as_json:
-        print(json.dumps({"version": VERSION, "checks": checks}, indent=2))
-        return 1 if any(check["status"] == FAIL for check in checks) else 0
+def _ask_legacy(shells: list[str]) -> bool:
+    """Whether to replace the hand-written wrappers in ``shells``' rc files, if any."""
+    found = {
+        rc_file: names
+        for shell in shells
+        for rc_file in SHELLS[shell].rc_files
+        if (names := find_legacy(read_rc(rc_file)))
+    }
+    if not found:
+        return False
 
     colors = palette()
-    marks = {
-        OK: f"{colors.green}✓{colors.reset}",
-        WARN: f"{colors.yellow}!{colors.reset}",
-        FAIL: f"{colors.red}✗{colors.reset}",
-    }
+    print()
+    total = sum(len(names) for names in found.values())
+    note(f"Found {total} hand-written wrappers from before che managed them:")
+    for rc_file, names in found.items():
+        print(
+            f"  {colors.grey}{rc_file}: {', '.join(names[:6])}"
+            f"{'…' if len(names) > 6 else ''}{colors.reset}"
+        )
+    return confirm(
+        "Replace them with the generated ones? (a backup is written first)", default=True
+    )
 
-    print_logo(f"doctor - che {VERSION}")
-    width = max(len(check["name"]) for check in checks) + 2
 
-    for check in checks:
-        if check["status"] == OK and not verbose and check["name"].startswith("tool: "):
-            continue
-        line = f"  {marks[check['status']]} {check['name']:<{width}} {colors.grey}{check['detail']}{colors.reset}"
-        print(line)
-        if check["status"] != OK and check["fix"]:
-            print(f"    {colors.grey}→ {check['fix']}{colors.reset}")
+def _ask_tools() -> bool:
+    """Whether to install the missing external tools, after listing them."""
+    missing = missing_binaries()
+    if not missing:
+        return False
 
-    failures = sum(1 for check in checks if check["status"] == FAIL)
-    warnings = sum(1 for check in checks if check["status"] == WARN)
+    colors = palette()
     print()
-    if failures:
-        warning(f"{failures} problem(s), {warnings} warning(s).")
-    elif warnings:
-        note(f"All good, with {warnings} warning(s).")
-    else:
-        success("Everything checks out.")
-    return 1 if failures else 0
+    note(f"Missing external tools: {', '.join(missing)}")
+    for name in missing:
+        hint = INSTALL_HINTS.get(name)
+        if hint:
+            print(f"  {colors.grey}{name}: {hint}{colors.reset}")
+    return bool(shutil.which("brew")) and confirm("Install them now with Homebrew?", default=False)
 
 
 # ---------------------------------------------------------------------------
@@ -1189,26 +455,6 @@ def doctor(*, as_json: bool = False, verbose: bool = False) -> int:
 # ---------------------------------------------------------------------------
 
 
-def install_source() -> str:
-    """How this copy of che got here: ``git`` for a clone, ``npm`` for a package.
-
-    The npm package is the same tree without ``.git``, unpacked under a
-    ``node_modules`` directory, so that is the whole test.
-    """
-    if (REPO / ".git").exists():
-        return "git"
-    if "node_modules" in REPO.parts:
-        return "npm"
-    return "unknown"
-
-
-def update_command() -> str:
-    """The command that fetches a newer che for this kind of install."""
-    if install_source() == "git":
-        return "git pull"
-    return f"npm install -g {PACKAGE_NAME}@latest"
-
-
 def update(*, check_only: bool = False, dry_run: bool = False) -> int:
     """Pull the latest scripts, then refresh whatever is installed.
 
@@ -1221,7 +467,7 @@ def update(*, check_only: bool = False, dry_run: bool = False) -> int:
     ``git fetch failed``.
     """
     colors = palette()
-    if install_source() != "git":
+    if not is_git_checkout():
         warning("❌ This copy of che is not a git checkout, so `che update` cannot pull it.")
         note(f"   Update it with `{update_command()}`, then `che install` to refresh the wrappers.")
         return 1
@@ -1229,110 +475,109 @@ def update(*, check_only: bool = False, dry_run: bool = False) -> int:
         warning("❌ git is not installed, so che cannot update itself.")
         return 1
 
-    before = run(["git", "rev-parse", "HEAD"], cwd=REPO, capture=True, check=False).stdout.strip()
-
     info("Fetching…")
-    fetch = run(["git", "fetch", "--prune"], cwd=REPO, check=False)
-    if fetch.returncode != 0:
+    if run(["git", "fetch", "--prune"], cwd=REPO, check=False).returncode != 0:
         warning("❌ git fetch failed.")
         return 1
 
-    behind = run(
-        ["git", "rev-list", "--count", "HEAD..@{upstream}"], cwd=REPO, capture=True, check=False
-    )
-    count = behind.stdout.strip() if behind.returncode == 0 else "?"
-
-    if count == "0":
-        success("Already up to date.")
-    elif check_only:
-        note(f"{count} commit(s) available. Run `che update` to apply.")
-        return 0
-    else:
-        dirty = run(
-            ["git", "status", "--porcelain", "--untracked-files=no"],
-            cwd=REPO,
-            capture=True,
-            check=False,
-        ).stdout.strip()
-        if dirty:
-            warning("❌ The repo has uncommitted changes; not pulling.")
-            note("   Commit or stash them, then run `che update` again.")
-            return 1
-
-        if dry_run:
-            note(f"would pull {count} commit(s)")
-        else:
-            pull = run(["git", "pull", "--ff-only"], cwd=REPO, check=False)
-            if pull.returncode != 0:
-                warning("❌ git pull --ff-only failed - the branch has diverged.")
-                return 1
-
-    after = run(["git", "rev-parse", "HEAD"], cwd=REPO, capture=True, check=False).stdout.strip()
-    if before and after and before != after:
-        print()
-        note("What changed:")
-        log = run(
-            ["git", "log", "--oneline", "--no-decorate", f"{before}..{after}"],
-            cwd=REPO,
-            capture=True,
-            check=False,
-        ).stdout
-        for line in log.splitlines()[:20]:
-            print(f"  {colors.grey}{line}{colors.reset}")
+    # Empty when the branch has no upstream or HEAD is detached: git explains
+    # on stderr and prints nothing.
+    count = run_output(["git", "rev-list", "--count", "HEAD..@{upstream}"], check=False, cwd=REPO)
 
+    if not count:
+        warning("❌ The checked-out branch has no upstream to pull from.")
+        note("   Check out a branch that tracks origin, usually main, then run `che update` again.")
+        return 1
     if check_only:
+        if count == "0":
+            success("Already up to date.")
+        else:
+            note(f"{count} commit(s) available. Run `che update` to apply.")
         return 0
 
-    config = load_config()
-    if not config:
+    python = require_python()
+    if python is None:
+        return 1
+    if count == "0":
+        success("Already up to date.")
+    elif not _pull(count, dry_run=dry_run):
+        return 1
+
+    record = load_record()
+    if record is None:
         note("che is not installed yet; running the installer.")
-        return wizard(dry_run=dry_run)
+        return wizard(InstallPlan(shells=default_shell_selection(), python=python, dry_run=dry_run))
 
     print()
-    plan = InstallPlan(
-        shells=config.get("shells", default_shell_selection(detect_shells())),
-        python=find_python()[0],
-        sounds=config.get("sounds", True),
-        path_shim=config.get("path_shim", True),
-        dry_run=dry_run,
-    )
-    result = perform_install(plan)
-    report(plan, result)
+    status = run_install(InstallPlan.from_record(record, python=python, dry_run=dry_run))
 
     print()
     success("Updated. Reload your shell to pick up new commands:")
     print(f"  {colors.bold}exec {login_shell() or 'zsh'}{colors.reset}")
-    return 0
+    return status
 
 
-def uninstall(*, dry_run: bool = False, purge: bool = False) -> int:
+def _pull(count: str, *, dry_run: bool) -> bool:
+    """Fast-forward the clone by its ``count`` new commits, then list them."""
+    if has_tracked_changes(REPO):
+        warning("❌ The repo has uncommitted changes; not pulling.")
+        note("   Commit or stash them, then run `che update` again.")
+        return False
+    if dry_run:
+        note(f"would pull {count} commit(s)")
+        return True
+
+    before = run_output(["git", "rev-parse", "HEAD"], check=False, cwd=REPO)
+    if run(["git", "pull", "--ff-only"], cwd=REPO, check=False).returncode != 0:
+        warning("❌ git pull --ff-only failed - the branch has diverged.")
+        return False
+
     colors = palette()
+    print()
+    note("What changed:")
+    log = run_output(
+        ["git", "log", "--oneline", "--no-decorate", f"{before}..HEAD"], check=False, cwd=REPO
+    )
+    for line in log.splitlines()[:20]:
+        print(f"  {colors.grey}{line}{colors.reset}")
+    return True
+
+
+def uninstall(*, dry_run: bool = False, purge: bool = False) -> int:
+    """Take out what ``che install`` put in: the rc blocks, the shim and the record.
+
+    ``purge`` also deletes the whole config directory, backups included, and
+    the state directory, which holds the menu's per-prompt input history.
+    """
+    removed = phrase("removed", dry_run=dry_run)
     touched = False
 
-    for target in detect_shells():
-        for rc_file in target.rc_files:
-            if remove_block(rc_file, dry_run=dry_run):
+    for spec in SHELLS.values():
+        for rc_file in spec.rc_files:
+            original = read_rc(rc_file)
+            if commit_rc(rc_file, original, without_block(original), dry_run=dry_run):
                 touched = True
-                display = str(rc_file).replace(str(home()), "~")
-                print(f"  {colors.green}✓{colors.reset} removed block from {display}")
-
-    shim = shim_path()
-    if shim.exists():
-        touched = True
-        if not dry_run:
-            shim.unlink()
-        print(f"  {colors.green}✓{colors.reset} removed {shim}")
+                print(f"  {mark()} {removed} block from {tildify(rc_file)}")
 
-    if purge and config_dir().exists():
+    leftovers = [config_dir(), state_dir()] if purge else [config_file()]
+    if is_che_shim(shim_path()):
+        leftovers.insert(0, shim_path())
+    for path in leftovers:
+        if not path.exists():
+            continue
         touched = True
         if not dry_run:
-            shutil.rmtree(config_dir())
-        print(f"  {colors.green}✓{colors.reset} removed {config_dir()}")
-    elif config_file().exists() and not dry_run:
-        config_file().unlink()
+            if path.is_dir():
+                shutil.rmtree(path)
+            else:
+                path.unlink()
+        print(f"  {mark()} {removed} {tildify(path)}")
 
     if not touched:
         note("Nothing to remove - che was not installed here.")
+    elif dry_run:
+        print()
+        note("Dry run: nothing was removed.")
     else:
         print()
         success("Uninstalled. The repo itself is untouched; delete it to finish.")
@@ -1344,9 +589,9 @@ def uninstall(*, dry_run: bool = False, purge: bool = False) -> int:
 # ---------------------------------------------------------------------------
 
 
-def build_install_parser(prog: str = "che install"):
+def build_install_parser() -> BoolFlagParser:
     parser = build_parser(
-        prog=prog,
+        prog="che install",
         description="📥 Install the che shell wrappers into your shell startup files.",
         epilog=(
             "Examples:\n"
@@ -1367,143 +612,109 @@ def build_install_parser(prog: str = "che install"):
     add_bool_flag(parser, "--all-shells", help="Install into every shell present on this machine")
     add_bool_flag(parser, "--yes", help="Skip the wizard and use the defaults")
     add_bool_flag(parser, "--dry-run", help="Report what would change, change nothing")
+    # Accepted and ignored: the completions load with the wrappers and cannot
+    # be left out. Hidden, but kept so an existing `--no-completions` still runs.
     add_bool_flag(
         parser,
         "--no-completions",
-        dest="no_completions",
         allow_value=False,
-        help="Skip installing tab completions",
+        help=argparse.SUPPRESS,
     )
     add_bool_flag(
         parser,
         "--no-path-shim",
-        dest="no_path_shim",
         allow_value=False,
         help="Do not put a `che` executable in ~/.local/bin",
     )
     add_bool_flag(
         parser,
         "--no-sounds",
-        dest="no_sounds",
         allow_value=False,
         help="Do not call playsound-N when a command finishes",
     )
     add_bool_flag(
         parser,
         "--replace-legacy",
-        dest="replace_legacy",
         help="Remove hand-written wrappers this repo now generates",
     )
     add_bool_flag(
         parser,
         "--install-deps",
-        dest="install_deps",
         help="Install missing external tools with Homebrew",
     )
     add_bool_flag(parser, "--print", dest="print_block", help="Print the rc block and exit")
-    add_bool_flag(parser, "--check", help="Verify the generated files are current (for CI)")
-    add_bool_flag(parser, "--generate", help="Rewrite the files under shell/ and exit")
     return parser
 
 
 def install_main(argv: list[str] | None = None) -> int:
-    parser = build_install_parser()
-    args = parser.parse_args(argv)
-
-    if args.generate or args.check:
-        try:
-            _expected_files()
-        except ValueError as exc:
-            warning(f"❌ {exc}")
-            return 1
-
-    if args.generate:
-        changed = write_generated(dry_run=args.dry_run)
-        for relative in changed:
-            note(f"wrote {relative}")
-        success(f"✓ {len(changed) or 'no'} generated file(s) updated")
-        return 0
-
-    if args.check:
-        stale = check_generated()
-        if stale:
-            warning("❌ Generated files are out of date:")
-            for path in stale:
-                note(f"   {path}")
-            note("   Run `che install` (or `bun run generate`) and commit the result.")
-            return 1
-        success("✓ Generated shell files match bin/commands.py")
-        return 0
-
-    python, version = find_python()
+    args = build_install_parser().parse_args(argv)
 
-    if args.print_block:
-        shells = _requested_shells(args)
-        for shell in shells:
-            print(
-                shellgen.rc_block(
-                    WRAPPER_FOR_SHELL[shell], home=REPO, python=python, sounds=not args.no_sounds
-                ),
-                end="",
-            )
-        return 0
-
-    if not args.yes and not args.shells and not args.all_shells and is_interactive():
-        return wizard(dry_run=args.dry_run)
-
-    if not version or version[:2] < MIN_PYTHON:
-        warning(f"❌ Python {'.'.join(str(p) for p in MIN_PYTHON)}+ is required.")
+    shells = _requested_shells(args)
+    if shells is None:
+        return 1
+    python = require_python()
+    if python is None:
         return 1
 
     plan = InstallPlan(
-        shells=_requested_shells(args),
+        shells=shells,
         python=python,
         sounds=not args.no_sounds,
-        completions=not args.no_completions,
         path_shim=not args.no_path_shim,
         replace_legacy=args.replace_legacy,
         dry_run=args.dry_run,
     )
 
+    if args.print_block:
+        for shell in plan.shells:
+            print(block_for(shell, plan), end="")
+        return 0
+
+    if not args.yes and not args.shells and not args.all_shells and is_interactive():
+        return wizard(plan, install_deps=args.install_deps)
+
     print_logo(f"installing che {VERSION}")
-    result = perform_install(plan)
-    report(plan, result)
-
-    if args.install_deps:
-        missing = [
-            name
-            for name, entry in binary_status().items()
-            if not entry["present"] and not entry["system"]
-        ]
-        if missing:
-            print()
-            install_missing_binaries(missing, dry_run=args.dry_run)
+    status = run_install(plan, install_deps=args.install_deps)
 
     print()
     success("Reload your shell to pick up the wrappers:  exec " + (login_shell() or "zsh"))
-    return 0
+    return status
 
 
-def _requested_shells(args) -> list[str]:
-    targets = detect_shells()
+def _requested_shells(args: argparse.Namespace) -> list[str] | None:
+    """The shells the flags ask for, or None, said why, when one is unknown."""
     if args.all_shells:
-        return [target.name for target in targets if target.installed and target.name != "sh"]
+        return [spec.name for spec in SHELLS.values() if spec.installed and not spec.opt_in]
     if args.shells:
         requested = [part.strip() for part in args.shells.split(",") if part.strip()]
-        unknown = [name for name in requested if name not in RC_RESOLVERS]
+        unknown = [name for name in requested if name not in SHELLS]
         if unknown:
             warning(f"❌ Unknown shell(s): {', '.join(unknown)}")
-            note(f"   Known: {', '.join(RC_RESOLVERS)}")
-            sys.exit(1)
+            note(f"   Known: {', '.join(SHELLS)}")
+            return None
         return requested
-    return default_shell_selection(targets)
+    return default_shell_selection()
 
 
-def main() -> int:
-    return install_main()
+def update_main(argv: list[str] | None = None) -> int:
+    parser = build_parser(
+        prog="che update", description="⬆️  Update the scripts, then refresh the wrappers."
+    )
+    add_bool_flag(parser, "--check", help="Report whether an update is available, apply nothing")
+    add_bool_flag(parser, "--dry-run", help="Report what would change, change nothing")
+    args = parser.parse_args(argv)
+    return update(check_only=args.check, dry_run=args.dry_run)
 
 
-if __name__ == "__main__":
-    from utils import run_cli
+def uninstall_main(argv: list[str] | None = None) -> int:
+    parser = build_parser(
+        prog="che uninstall", description="🧽 Remove the wrappers, shim and completions."
+    )
+    add_bool_flag(parser, "--dry-run", help="Report what would change, change nothing")
+    add_bool_flag(parser, "--purge", help="Also delete ~/.config/che and the menu's history")
+    args = parser.parse_args(argv)
+    return uninstall(dry_run=args.dry_run, purge=args.purge)
+
 
-    run_cli(main)
+if __name__ == "__main__":
+    run_cli(install_main)