@codebend3r/che 1.0.0 → 1.2.0

package/README.md

@@ -5,14 +5,39 @@
 **A collection of helper scripts shared amongst computers, called by name from
 your shell, and browsable through one menu.**
 
-[![CI](https://github.com/codebend3r/che/actions/workflows/ci.yml/badge.svg)](https://github.com/codebend3r/che/actions/workflows/ci.yml)
+[![CI](https://github.com/codebend3r/che/actions/workflows/sanity-check.yml/badge.svg)](https://github.com/codebend3r/che/actions/workflows/sanity-check.yml)
 [![npm](https://img.shields.io/npm/v/%40codebend3r%2Fche)](https://www.npmjs.com/package/@codebend3r/che)
 ![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)
 ![Dependencies: stdlib only](https://img.shields.io/badge/dependencies-stdlib%20only-brightgreen)
 ![Shells: zsh, bash, fish](https://img.shields.io/badge/shells-zsh%20%7C%20bash%20%7C%20fish-8A2BE2)
 
-<img src="menu.png" alt="The che menu: commands grouped by category on the left, details for the selected command on the right" width="850">
+</div>
+
+<!-- che:banner -->
+```text
+**#*-
+#*-.         .::---:::.
+=       .:+#%@@@@@@@@@%#*+-.
+      .-*%@@@@@@@@@*==----+*-
+     .=-====*%@@@@+:..:===--+:
+     . .-:.  .=%@%+=-+:...=+==
+      .=:-.:=:.+#***+***+++**+.    ██████╗██╗  ██╗███████╗
+      -.:++**+-#@%##%%####%##*-   ██╔════╝██║  ██║██╔════╝
+     .=+**#%#-:-+=--+%%@@####+.   ██║     ███████║█████╗
+     .+*#%@@*...=+::+##%%#***-.   ██║     ██╔══██║██╔══╝
+      -*##%@*=:-#*=-:--==##*+:.   ╚██████╗██║  ██║███████╗
+      .=+#+-::--::-:.:.: :++=:.    ╚═════╝╚═╝  ╚═╝╚══════╝
+       :++...::::---==++:---...
+        :..=**+++-=*#%@%=:::..
+         .:-*%@@@@@@@%#*. :::
+:  .      .  -+**#*=-.
+++-.                       .::
++*+=:                    .-===.
+```
+<!-- /che:banner -->
 
+<div align="center">
+<img src="menu.png" alt="The che menu: commands grouped by category on the left, details for the selected command on the right" width="850">
 </div>
 
 The scripts are Python, standard library only. The names you type
@@ -54,8 +79,8 @@ git clone https://github.com/codebend3r/che.git ~/Developer/git/che
 ~/Developer/git/che/install.sh
 ```
 
-Or in one line, which clones for you (into `~/Developer/git/shell-functions`,
-or wherever `CHE_HOME` points):
+Or in one line, which clones for you (into `~/Developer/git/che`, or wherever
+`CHE_HOME` points):
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/codebend3r/che/main/install.sh | bash
@@ -78,7 +103,9 @@ which opens a first-run wizard: it lists the shells it found and the rc files
 it would touch, asks whether to add a `che` on `PATH` and whether to keep the
 completion chimes, offers to remove hand-written wrappers left over from before
 the installer existed, and reports any missing external tool (offering to
-`brew install` them when Homebrew is present).
+`brew install` them when Homebrew is present). A question already answered on
+the command line (`--no-sounds`, `--no-path-shim`, `--replace-legacy`,
+`--install-deps`) is not asked again.
 
 <div align="center">
 <img src="first-run.png" alt="The first run screen: che is not installed in this shell yet, offering to install, open the menu, or quit" width="700">
@@ -93,7 +120,7 @@ Skip the wizard:
 ./install.sh --yes --shells=zsh,fish  # or the ones you name
 ./install.sh --dry-run                # report what would change, write nothing
 ./install.sh --yes --replace-legacy   # also remove pre-che hand-written wrappers
-./install.sh --print                  # print the rc block, install nothing
+./install.sh --print                  # print the exact rc block, install nothing
 ```
 
 Every rc file is copied to `~/.config/che/backups/` before it is edited.
@@ -114,9 +141,9 @@ dotfiles:
 ```zsh
 # >>> che shell functions >>>
 # Managed by `che install` (che 1.0.0). Edits here are overwritten.
-export CHE_HOME=/Users/you/Developer/git/shell-functions
+export CHE_HOME=/Users/you/Developer/git/che
 export CHE_PYTHON=/opt/homebrew/bin/python3
-[ -r /Users/you/Developer/git/shell-functions/shell/che.zsh ] && . /Users/you/Developer/git/shell-functions/shell/che.zsh
+[ -r /Users/you/Developer/git/che/shell/che.zsh ] && . /Users/you/Developer/git/che/shell/che.zsh
 case ":$PATH:" in *":/Users/you/.local/bin:"*) ;; *) PATH="/Users/you/.local/bin:$PATH" ;; esac
 # <<< che shell functions <<<
 ```
@@ -139,7 +166,7 @@ python3 exists. `brew install python@3.13` if none does.
 
 ```sh
 che uninstall           # remove the block, the shim and the completions
-che uninstall --purge   # also delete ~/.config/che
+che uninstall --purge   # also delete ~/.config/che and the menu's input history
 ```
 
 The repo itself is left alone; delete the directory to finish.
@@ -189,13 +216,13 @@ have used, and `che help <command>` prints that script's own `--help`.
 | Command | Does | Preview |
 | --- | --- | --- |
 | **Git** | *Branch hygiene, worktrees and GitHub Actions* | |
-| `all-actions` | GitHub Actions status for every open PR you authored |  |
+| `all-actions` | GitHub Actions status for every open PR and every default branch |  |
 | `all-actions-watch` | Same as all-actions, refreshed on an interval |  |
 | `checkout-my-branches` | Check out recent remote branches you authored that aren't local yet |  |
 | `clean-stale-branches` | Delete local branches whose upstream is gone | `clean-stale-branches-dr` |
 | `prune-worktrees` | Remove every linked worktree, then prune stale admin records | `prune-worktrees-dr` |
-| `sync-all-branches` | Push every worktree, collapse the pushed ones, then tidy branches | `sync-all-branches-dr` |
-| `update-from-origin` | Same as sync-all-branches but never pushes: fetch, collapse, rebase |  |
+| `sync-all-branches` | Delete merged branches, rebase the rest, check out new ones; branches only | `sync-all-branches-dr` |
+| `update-from-origin` | Alias of sync-all-branches | `--dry-run` |
 | `update-local-branches` | Rebase every local branch that has an upstream onto origin | `--dry-run` |
 | **Video** | *Codecs, renaming, dedupe and metadata* | |
 | `show-codecs` | Report media files outside the Direct Play codec/container set |  |
@@ -290,9 +317,17 @@ where you copy one machine's rc file to another.
 
 ```
 bin/
-  che.py              the dispatcher and the interactive menu
+  art.py              the wordmark and the face beside it, for every screen
+  che.py              the dispatcher, and the loop that runs what the menu picks
   commands.py         the command manifest: the source of truth for everything
-  install.py          installer, first-run wizard, doctor, self-update
+  doctor.py           `che doctor`: every check on the install
+  gitutils.py         shared git helpers: worktrees, main branch, hook skipping
+  install.py          installer, first-run wizard, self-update, uninstall
+  machine.py          shells, rc file paths, python, config: facts about the machine
+  media.py            shared ffprobe helpers for the video scripts
+  menu.py             the menu's list, keys and drawing
+  nas.py              the NAS drive table and SMB mounting, for the drive scripts
+  rcfile.py           edits to rc files: the che block and old hand-written wrappers
   shellgen.py         renders the wrappers, completions and README tables
   tui.py              terminal primitives: raw input, frame buffer, prompts
   utils.py            shared library: logging, arg parsing, subprocess, files
@@ -325,22 +360,27 @@ Every script follows the same shape, described in full at the top of
   point, so pointing a delete tool at `~/media -> /Volumes/...` used to be a
   silent no-op. Pass the real path to act on it.
 
-## Syncing branches and worktrees
+## Syncing branches
 
 ```sh
-sync-all-branches       # push every worktree, collapse the pushed ones, then sync
+sync-all-branches       # delete merged branches, rebase the rest, check out new ones
 sync-all-branches-dr    # preview only
-update-from-origin      # same, but --no-push: only collapses already-pushed worktrees
+update-from-origin      # alias of sync-all-branches
 ```
 
-A worktree is a temporary workspace. Once its commits are on origin the
-directory holds nothing the remote doesn't, so `sync-all-branches` pushes it,
-removes the directory, and leaves the branch behind as an ordinary local
-branch. That also clears the `already used by worktree` pin, which is what
-otherwise makes `main` un-checkoutable and stale branches un-deletable.
+Only branches change. The sync deletes local branches whose upstream is gone,
+`pull --rebase`s every branch with an upstream, and creates local tracking
+branches for the remote branches you authored that aren't local yet, without
+switching to them. It ends with the main clone on `main`.
 
-A worktree is only collapsed when it is **clean** *and* **fully pushed**.
-Anything else is kept and reported with the reason.
+It **never pushes**, **never touches a worktree** and **never runs the repo's
+git hooks**. A branch checked out in a linked worktree is rebased in place
+there when that worktree is clean; a stale one is reported and kept, since git
+won't delete a branch a worktree has checked out. The branch scripts
+(`clean-stale-branches`, `update-local-branches`, `checkout-my-branches`,
+`prune-worktrees`, `sync-all-branches`) point `core.hooksPath` at `/dev/null`
+for every git they run, so a lefthook or husky pre-commit, pre-push or
+post-checkout never fires on a checkout or a rebase.
 
 ## External tools
 
@@ -382,7 +422,7 @@ This repo uses [Bun](https://bun.sh) as its task runner and
 ```sh
 bun run test        # pytest
 bun run generate    # rewrite shell/ and this README's tables from the manifest
-bun run ci          # ruff + syntax + exec bits + shebangs + generated files + pytest
+bun run ci          # ruff + exec bits + shebangs + pytest (stale generated files fail it)
 ```
 
 Neither `pytest` nor `ruff` needs to be installed globally: the scripts shell

package/bin/art.py

@@ -0,0 +1,123 @@
+"""The che wordmark and the face it shares a name with, as text.
+
+``LOGO`` is the block-letter wordmark that ``che install``, ``che doctor`` and
+the first-run screen print. ``FACE`` is Che Guevara, rendered from a photograph
+to 32 columns by 18 rows so the two fit side by side in an 80-column terminal.
+Dense characters are the bright parts of the photo, which reads correctly on a
+dark background.
+
+``banner()`` lays the face beside whatever a screen wants next to it, normally
+the wordmark with a subtitle underneath, centred vertically on the face. Lines
+may carry colour escapes; widths are measured with ``tui.display_width`` so the
+escapes do not push the right-hand column about.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import tui
+
+LOGO = r"""
+   ██████╗██╗  ██╗███████╗
+  ██╔════╝██║  ██║██╔════╝
+  ██║     ███████║█████╗
+  ██║     ██╔══██║██╔══╝
+  ╚██████╗██║  ██║███████╗
+   ╚═════╝╚═╝  ╚═╝╚══════╝
+"""
+
+FACE = """
+**#*-
+#*-.         .::---:::.
+=       .:+#%@@@@@@@@@%#*+-.
+      .-*%@@@@@@@@@*==----+*-
+     .=-====*%@@@@+:..:===--+:
+     . .-:.  .=%@%+=-+:...=+==
+      .=:-.:=:.+#***+***+++**+.
+      -.:++**+-#@%##%%####%##*-
+     .=+**#%#-:-+=--+%%@@####+.
+     .+*#%@@*...=+::+##%%#***-.
+      -*##%@*=:-#*=-:--==##*+:.
+      .=+#+-::--::-:.:.: :++=:.
+       :++...::::---==++:---...
+        :..=**+++-=*#%@%=:::..
+         .:-*%@@@@@@@%#*. :::
+:  .      .  -+**#*=-.
+++-.                       .::
++*+=:                    .-===.
+"""
+
+# What the face gets on its left, so it lines up with the two-space indent the
+# wordmark and every subtitle carry.
+INDENT = "  "
+# Columns between the face and the block beside it. The wordmark lines start
+# with two spaces of their own, so the visible gap is wider than this.
+GAP = 1
+
+
+LOGO_LINES: tuple[str, ...] = tuple(LOGO.strip("\n").splitlines())
+FACE_LINES: tuple[str, ...] = tuple(FACE.strip("\n").splitlines())
+
+HEIGHT = len(FACE_LINES)
+WIDTH = len(INDENT) + max(len(line) for line in FACE_LINES)
+
+
+def _paint(lines: Sequence[str], colors: tui.Palette, indent: str = "") -> list[str]:
+    return [f"{colors.bright_magenta}{indent}{line}{colors.reset}" for line in lines]
+
+
+def wordmark(colors: tui.Palette) -> list[str]:
+    """The block letters, coloured the way every screen prints them."""
+    return _paint(LOGO_LINES, colors)
+
+
+def compose(left: Sequence[str], right: Sequence[str], *, gap: int = GAP) -> list[str]:
+    """Lay ``right`` beside ``left``, the shorter block centred on the taller."""
+    left = list(left)
+    right = list(right)
+    left_width = max((tui.display_width(line) for line in left), default=0)
+    height = max(len(left), len(right))
+    left_top = (height - len(left)) // 2
+    right_top = (height - len(right)) // 2
+
+    rows = []
+    for index in range(height):
+        a = left[index - left_top] if 0 <= index - left_top < len(left) else ""
+        b = right[index - right_top] if 0 <= index - right_top < len(right) else ""
+        if b:
+            a += " " * (left_width + gap - tui.display_width(a))
+        rows.append((a + b).rstrip())
+    return rows
+
+
+def fits(right: Sequence[str], columns: int) -> bool:
+    """Whether the face and ``right`` sit side by side in ``columns``."""
+    right_width = max((tui.display_width(line) for line in right), default=0)
+    return WIDTH + GAP + right_width <= columns
+
+
+def banner(right: Sequence[str], *, colors: tui.Palette, columns: int | None = None) -> list[str]:
+    """The face with ``right`` beside it, or ``right`` alone when it would not fit.
+
+    ``right`` is normally the wordmark plus whatever a screen wants under it (a
+    subtitle, the command count). It comes back untouched, indent and all, on a
+    terminal too narrow for both, so every caller keeps working at 40 columns.
+    The face is indented to line up with the wordmark and painted in its colour.
+    """
+    if columns is None:
+        columns = tui.size()[0]
+    if not fits(right, columns):
+        return list(right)
+    return compose(_paint(FACE_LINES, colors, INDENT), right)
+
+
+def print_logo(subtitle: str = "") -> None:
+    """The face beside the wordmark, with ``subtitle`` under the letters."""
+    colors = tui.palette()
+    right = wordmark(colors)
+    if subtitle:
+        right.append(f"  {colors.grey}{subtitle}{colors.reset}")
+    for line in banner(right, colors=colors):
+        print(line)
+    print()