@codebend3r/che 1.1.0 → 1.2.0

package/README.md

@@ -5,7 +5,7 @@
 **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)
@@ -79,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
@@ -103,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">
@@ -118,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.
@@ -139,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 <<<
 ```
@@ -164,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.
@@ -214,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 |  |
@@ -316,9 +318,16 @@ where you copy one machine's rc file to another.
 ```
 bin/
   art.py              the wordmark and the face beside it, for every screen
-  che.py              the dispatcher and the interactive menu
+  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
@@ -351,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
 
@@ -408,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

@@ -56,28 +56,20 @@ INDENT = "  "
 GAP = 1
 
 
-def logo_lines() -> list[str]:
-    return LOGO.strip("\n").splitlines()
+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 face_lines() -> list[str]:
-    return FACE.strip("\n").splitlines()
 
+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]
 
-HEIGHT = len(face_lines())
-WIDTH = len(INDENT) + max(len(line) for line in face_lines())
 
-
-def wordmark(colors: tui.Palette | None = None) -> list[str]:
+def wordmark(colors: tui.Palette) -> list[str]:
     """The block letters, coloured the way every screen prints them."""
-    colors = colors or tui.palette()
-    return [f"{colors.bright_magenta}{line}{colors.reset}" for line in logo_lines()]
-
-
-def face(colors: tui.Palette | None = None) -> list[str]:
-    """The face, indented to line up with the wordmark and in the same colour."""
-    colors = colors or tui.palette()
-    return [f"{colors.bright_magenta}{INDENT}{line}{colors.reset}" for line in face_lines()]
+    return _paint(LOGO_LINES, colors)
 
 
 def compose(left: Sequence[str], right: Sequence[str], *, gap: int = GAP) -> list[str]:
@@ -105,17 +97,27 @@ def fits(right: Sequence[str], columns: int) -> bool:
     return WIDTH + GAP + right_width <= columns
 
 
-def banner(
-    right: Sequence[str], *, columns: int | None = None, colors: tui.Palette | None = None
-) -> list[str]:
+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(face(colors), 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()