cctally 1.8.2 → 1.9.0

package/CHANGELOG.md

@@ -5,6 +5,15 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.9.0] - 2026-05-19
+
+### Removed
+- `cctally release` subcommand — maintainer-only release automation moved to private `bin/cctally-release`. End-user npm/brew installs no longer carry release tooling, and `cctally setup` no longer expects a `cctally-release` symlink (stale symlinks from prior versions are auto-cleaned by `cctally setup --install`). The actual release process is unchanged for the maintainer; see `docs/RELEASE.md`.
+
+### Fixed
+- Maintainer-only release tooling: recovery hints in `bin/_cctally_release.py` (Phase 4 `gh auth` fallback, Phase 5 npm poll timeout, Phase 6 brew dirty-clone refusal) now tell the operator to re-run `bin/cctally-release --resume` from the cctally-dev checkout — bare `cctally-release` is not on `~/.local/bin/` after the release-command split (`cctally setup` no longer auto-symlinks it). Round 1 of the split's review accumulator updated these hints from the removed `cctally release --resume` to `cctally-release --resume`; round 3 refines them to the path-relative form so an operator following the recovery instructions verbatim doesn't hit `command not found` unless they manually created an alias. The pre-existing docs convention (bare name in `docs/RELEASE.md` / `.claude/skills/release-cctally/SKILL.md` examples with an explicit "substitute `bin/cctally-release` (or your alias)" note) is unchanged.
+- `cctally setup` and `cctally setup --uninstall` retire legacy `~/.local/bin/cctally-release` symlinks left behind by pre-v1.9.0 brew/npm installs. Previously the round-2 "stale" predicate required the symlink target to be *dangling*, which preserved a maintainer's manual link to the current checkout's still-shipped `bin/cctally-release` (intentional) but also preserved a legacy auto-installed link whose target points at an OLD homebrew keg / `node_modules/cctally/` tree that lingers on disk until `brew cleanup` (unintentional — leaves the retired command on PATH across upgrades). New `_setup_symlink_is_retired` adds a foreign-install-root branch alongside the dangling branch: a target whose path contains `/Cellar/cctally/` or `/node_modules/cctally/` AND that token is NOT in the current install's `repo_root` is classified as retired and removed. Both the install-time cleanup and the read-only `--status` detection route through it (so they agree on what's stale); the uninstall site now composes `target == expected OR is_retired(...)` for symmetric coverage. A maintainer's hand-rolled link to the current cctally-dev checkout (`~/.local/bin/cctally-release -> <checkout>/bin/cctally-release`) is still preserved — that target is neither dangling nor under a foreign install root. Regression: `tests/test_setup_stale_symlinks.py` adds four new scenarios — brew-keg/npm-modules cleanup, brew-keg `--status` detection, brew-keg uninstall.
+
 ## [1.8.2] - 2026-05-18
 
 ### Added

package/bin/_cctally_setup.py

@@ -242,10 +242,22 @@ def _setup_local_bin_dir() -> pathlib.Path:
 @dataclasses.dataclass
 class _SetupSymlinkResult:
     name: str
-    status: str   # "created" | "already" | "replaced" | "failed"
+    status: str   # "created" | "already" | "replaced" | "failed" | "removed-stale"
     detail: str = ""
 
 
+# Symlink names cctally USED to install but no longer does. We keep
+# cleaning them up for one major-version's worth of upgraders so
+# `~/.local/bin/` doesn't accumulate dangling symlinks pointing at
+# scripts the current cctally checkout doesn't ship. Removal is
+# conservative: we only unlink symlinks whose `readlink()` target's
+# basename matches the stale name — a user's hand-rolled symlink with
+# the same name pointing elsewhere is left alone.
+_SETUP_STALE_SYMLINK_NAMES = (
+    "cctally-release",  # Removed in v1.9.0; release tooling went private.
+)
+
+
 def _setup_resolve_symlink_source(repo_root: pathlib.Path, name: str) -> pathlib.Path:
     """Resolve the symlink target for a given PATH-name.
 
@@ -326,6 +338,148 @@ def _setup_create_symlinks(
     return results
 
 
+def _setup_cleanup_stale_symlinks(
+    dst_dir: pathlib.Path,
+) -> list[_SetupSymlinkResult]:
+    """Unlink stale `cctally-*` symlinks left over from prior versions.
+
+    For each entry in :data:`_SETUP_STALE_SYMLINK_NAMES`, removes the
+    matching symlink in ``dst_dir`` when its readlink target basename
+    matches the stale name AND the target points at a "retired" cctally
+    install — meaning either (a) the target is *dangling* (no longer
+    resolves to a real file, e.g. an old checkout that was deleted) OR
+    (b) the target lives under a *foreign* cctally install root
+    (Homebrew keg, npm ``node_modules/cctally/``), i.e. an install root
+    other than the one currently running ``cctally setup``.
+
+    The foreign-root clause is what handles the common upgrade path:
+    after ``brew upgrade cctally`` or ``npm i -g cctally@<new>``, the
+    *prior* keg / module dir often lingers on disk until ``brew
+    cleanup`` (or the next npm install GC), so a legacy
+    ``~/.local/bin/cctally-release`` symlink from a pre-v1.9.0 ``cctally
+    setup`` still resolves to an existing file under the *old* install
+    root. The dangling-only predicate would skip it, leaving the retired
+    command on PATH; the foreign-root check retires it instead.
+
+    Both clauses still preserve the maintainer's intentional manual
+    link to the *current* checkout's still-shipped retired tooling
+    (e.g. ``~/.local/bin/cctally-release ->
+    <cctally-dev>/bin/cctally-release``) — that target is neither
+    dangling nor foreign, so it's left alone. Likewise a hand-rolled
+    link pointing somewhere unrelated (``~/scripts/...``) survives.
+
+    Returns a list of :class:`_SetupSymlinkResult` entries for the
+    actions taken (so callers can fold them into install output).
+    """
+    results: list[_SetupSymlinkResult] = []
+    repo_root = _setup_resolve_repo_root()
+    for name in _SETUP_STALE_SYMLINK_NAMES:
+        dst = dst_dir / name
+        if not _setup_symlink_is_retired(dst, name, repo_root):
+            continue
+        try:
+            dst.unlink()
+            results.append(
+                _SetupSymlinkResult(name, "removed-stale", "stale (from prior version)")
+            )
+        except OSError as exc:
+            results.append(
+                _SetupSymlinkResult(name, "failed", f"unlink failed: {exc}")
+            )
+    return results
+
+
+# Path tokens that identify a "foreign" cctally install root — i.e. a
+# directory tree managed by a different distribution channel (or a
+# different version of the same channel) than the one currently running
+# ``cctally setup``. A symlink whose target sits under one of these is
+# almost certainly a legacy auto-installed link from a prior version
+# whose install root the current run does NOT manage. Pre-resolved (no
+# trailing slash) so substring matching works on either UNIX or
+# resolved forms.
+_SETUP_FOREIGN_INSTALL_ROOT_TOKENS = (
+    # Homebrew keeps every installed version under
+    # ``<prefix>/Cellar/cctally/<version>/``. A target inside any of
+    # these directories points at a brew install — either the current
+    # one (when ``cctally setup`` runs from a brew install — possible
+    # but rare) or an older keg still on disk pending ``brew cleanup``.
+    "/Cellar/cctally/",
+    # npm globals land at ``<prefix>/lib/node_modules/cctally/``; npm
+    # locals at ``<project>/node_modules/cctally/``. Either way the
+    # ``/node_modules/cctally/`` segment is the discriminator. pnpm and
+    # yarn variants keep the segment, so this catches them too.
+    "/node_modules/cctally/",
+)
+
+
+def _setup_symlink_is_retired(
+    dst: pathlib.Path, name: str, repo_root: pathlib.Path,
+) -> bool:
+    """Detection predicate for retired auto-symlinks at install time.
+
+    Returns True iff ``dst`` is a symlink, its readlink target basename
+    matches ``name``, AND the target points at a "retired" cctally
+    install — i.e. one the current ``cctally setup`` run does not
+    manage. Two retirement classes:
+
+      1. **Dangling target** — readlink target does not resolve to an
+         existing filesystem entry. Covers the deleted-checkout case.
+      2. **Foreign install root** — target path contains one of
+         :data:`_SETUP_FOREIGN_INSTALL_ROOT_TOKENS` (``/Cellar/cctally/``
+         or ``/node_modules/cctally/``) AND that token does NOT also
+         appear in the current ``repo_root``. The second clause is what
+         keeps the (rare) case of running ``cctally setup`` *from* an
+         npm/brew install correctly — a symlink at the same install root
+         is NOT foreign, so it's left to the active-symlinks loop in
+         :func:`_setup_install` / :func:`_setup_uninstall`.
+
+    Targets that exist but live outside any recognized install root
+    (e.g. a maintainer's manual link to ``<checkout>/bin/cctally-release``
+    or a hand-rolled link at ``~/scripts/cctally-release``) are
+    preserved — they're either explicit operator setups or genuine
+    user-managed scripts that happen to share the name.
+
+    Shared by the cleanup site (``_setup_cleanup_stale_symlinks``) and
+    the read-only detection site (``_setup_detect_stale_symlinks``) so
+    ``--status`` and ``setup`` agree on what they call "stale".
+    """
+    if not dst.is_symlink():
+        return False
+    try:
+        target = os.readlink(dst)
+    except OSError:
+        return False
+    if pathlib.Path(target).name != name:
+        # User-managed symlink that happens to share the name; leave alone.
+        return False
+    # Resolve target relative to the symlink's parent so relative
+    # readlinks (rare for cctally setup-installed links, but possible
+    # for hand-rolled ones) classify correctly. Use lexists()-style
+    # check via Path.exists() — broken links return False, which is
+    # the "dangling, treat as stale" branch we want.
+    target_path = pathlib.Path(target)
+    if not target_path.is_absolute():
+        target_path = dst.parent / target_path
+    try:
+        target_exists = target_path.exists()
+    except OSError:
+        # Permission errors etc. — be conservative and don't remove.
+        return False
+    if not target_exists:
+        return True
+    # Target exists — retire only if it lives under a *foreign* install
+    # root (a different brew keg / npm module dir than the one running
+    # this setup). Compare against ``repo_root`` so a setup running
+    # *from* an npm/brew install doesn't classify its own siblings as
+    # foreign — that's the active-symlinks loop's job.
+    target_str = str(target_path)
+    repo_root_str = str(repo_root)
+    for token in _SETUP_FOREIGN_INSTALL_ROOT_TOKENS:
+        if token in target_str and token not in repo_root_str:
+            return True
+    return False
+
+
 def _setup_path_includes_local_bin() -> bool:
     local_bin = str(_setup_local_bin_dir())
     return local_bin in os.environ.get("PATH", "").split(os.pathsep)
@@ -816,12 +970,38 @@ def _setup_compute_symlink_state(
     return out
 
 
+def _setup_detect_stale_symlinks(dst_dir: pathlib.Path) -> list[str]:
+    """Return names of stale-but-still-present cctally symlinks in ``dst_dir``.
+
+    Mirrors :func:`_setup_cleanup_stale_symlinks` detection (without
+    removing): a symlink is "stale" when its name appears in
+    :data:`_SETUP_STALE_SYMLINK_NAMES`, its readlink target basename
+    matches that name, AND the target is "retired" — either dangling
+    OR pointing at a foreign cctally install root (see
+    :func:`_setup_symlink_is_retired`). Routing through the same
+    predicate keeps ``--status`` and ``setup`` in lockstep so a
+    manually-maintained link to a still-shipped retired tool
+    (``~/.local/bin/cctally-release -> <checkout>/bin/cctally-release``)
+    is neither reported as stale nor removed, while a legacy link left
+    over from a pre-v1.9.0 brew/npm install (target still resolves into
+    the old keg / ``node_modules`` tree) IS retired.
+    """
+    found: list[str] = []
+    repo_root = _setup_resolve_repo_root()
+    for name in _SETUP_STALE_SYMLINK_NAMES:
+        dst = dst_dir / name
+        if _setup_symlink_is_retired(dst, name, repo_root):
+            found.append(name)
+    return found
+
+
 def _setup_status(args: argparse.Namespace) -> int:
     c = _cctally()
     repo_root = _setup_resolve_repo_root()
     dst_dir = _setup_local_bin_dir()
     sym_state = _setup_compute_symlink_state(repo_root, dst_dir)
     sym_ok = sum(1 for _, s in sym_state if s == "ok")
+    stale_syms = _setup_detect_stale_symlinks(dst_dir)
     on_path = _setup_path_includes_local_bin()
     try:
         settings = c._load_claude_settings()
@@ -842,6 +1022,7 @@ def _setup_status(args: argparse.Namespace) -> int:
             "install": {
                 "symlinks_present": sym_ok,
                 "symlinks_total": len(c.SETUP_SYMLINK_NAMES),
+                "symlinks_stale": stale_syms,
                 "path_includes": on_path,
             },
             "hooks": {ev: hook_counts[ev] for ev in c.SETUP_HOOK_EVENTS},
@@ -869,6 +1050,11 @@ def _setup_status(args: argparse.Namespace) -> int:
     out.append("Install")
     sym_marker = "✓" if sym_ok == len(c.SETUP_SYMLINK_NAMES) else "✗"
     out.append(f"  Symlinks       {sym_ok}/{len(c.SETUP_SYMLINK_NAMES)} present at {dst_dir}/  {sym_marker}")
+    if stale_syms:
+        out.append(
+            f"  Stale symlinks {len(stale_syms)} from prior version: {', '.join(stale_syms)}  ⚠"
+        )
+        out.append("                 run `cctally setup` to remove")
     out.append(f"  PATH includes  {'yes' if on_path else 'no'}                                   "
                f"{'✓' if on_path else '⚠'}")
     out.append(f"Hooks ({c.CLAUDE_SETTINGS_PATH})")
@@ -950,6 +1136,50 @@ def _setup_uninstall(args: argparse.Namespace) -> int:
                     sym_removed += 1
                 except OSError as exc:
                     eprint(f"setup: failed to remove {dst}: {exc}")
+    # Also clean up legacy symlinks that older cctally versions used to
+    # install but the current version no longer manages (see
+    # :data:`_SETUP_STALE_SYMLINK_NAMES`). Without this loop, an
+    # upgrader who ran ``cctally setup`` on a prior version and now runs
+    # ``cctally setup --uninstall`` would keep e.g.
+    # ``~/.local/bin/cctally-release`` on PATH.
+    #
+    # Two removal predicates compose here:
+    #   1. ``target == _setup_resolve_symlink_source(repo_root, name)``
+    #      — the legacy auto-installed link points at *this* install
+    #      root's binary (the common case for git-checkout upgraders
+    #      who ran ``cctally setup`` on a prior version, then ``git
+    #      pull``ed; symmetric with how the active-symlink loop above
+    #      treats user-pointed `cctally` itself).
+    #   2. ``_setup_symlink_is_retired`` — target is dangling OR lives
+    #      under a *foreign* cctally install root (old brew keg /
+    #      ``node_modules/cctally/`` left behind by ``brew upgrade``
+    #      or ``npm i -g cctally@<new>``). Without this, the common
+    #      brew/npm upgrade-then-uninstall path leaves the legacy
+    #      symlink in place because the prior keg's binary still
+    #      exists on disk (``target != expected``).
+    #
+    # A maintainer's hand-rolled link pointing somewhere unrelated
+    # (``~/scripts/...``) is preserved by both predicates.
+    for name in _SETUP_STALE_SYMLINK_NAMES:
+        dst = dst_dir / name
+        if not dst.is_symlink():
+            continue
+        try:
+            target = pathlib.Path(os.readlink(dst))
+        except OSError:
+            continue
+        expected = _setup_resolve_symlink_source(repo_root, name)
+        should_remove = (
+            target == expected
+            or _setup_symlink_is_retired(dst, name, repo_root)
+        )
+        if not should_remove:
+            continue
+        try:
+            dst.unlink()
+            sym_removed += 1
+        except OSError as exc:
+            eprint(f"setup: failed to remove {dst}: {exc}")
     out.append(f"Removed {sym_removed} symlinks from {dst_dir}/")
 
     legacy = _setup_detect_legacy_snippet()
@@ -1336,6 +1566,13 @@ def _setup_install(args: argparse.Namespace) -> int:
         eprint(f"setup: {exc}")
         return 1
 
+    # Clean up symlinks left behind by prior cctally versions whose
+    # subcommand surface has changed (e.g. v1.9.0 retired
+    # `cctally-release` when release tooling went private). Only unlinks
+    # symlinks whose target's basename matches the stale name; never
+    # disturbs a user's hand-rolled symlink sharing the name.
+    stale_results = _setup_cleanup_stale_symlinks(dst_dir)
+
     sym_results = _setup_create_symlinks(repo_root, dst_dir)
     failed = [r for r in sym_results if r.status == "failed"]
     if failed:
@@ -1354,6 +1591,16 @@ def _setup_install(args: argparse.Namespace) -> int:
         detail_parts.append(f"{repl_count} re-pointed")
     detail = ", ".join(detail_parts) or "no changes"
     out.append(f"✓ Symlinks at {dst_dir}/: {len(sym_results)}/{len(sym_results)} ({detail})")
+    removed_stale = [r for r in stale_results if r.status == "removed-stale"]
+    failed_stale = [r for r in stale_results if r.status == "failed"]
+    if removed_stale:
+        out.append(
+            "✓ Cleaned up stale symlink(s) from prior version: "
+            + ", ".join(r.name for r in removed_stale)
+        )
+    for r in failed_stale:
+        out.append(f"⚠ Could not remove stale {r.name}: {r.detail}")
+        warnings += 1
 
     if not _setup_path_includes_local_bin():
         warnings += 1

package/bin/_cctally_update.py

@@ -116,10 +116,16 @@ What stays in bin/cctally:
   write surface in cmd_dashboard works unchanged; moved code
   reads via ``c.X``.
 - ``eprint``, ``_now_utc`` (used by moved code via shim/accessor),
-  ``_release_read_latest_release_version`` (stays in cctally per
-  spec §6.7 — 6+ external callers, file I/O over CHANGELOG.md),
+  ``_release_read_latest_release_version`` (impl moved to
+  ``_lib_changelog._read_latest_changelog_version``; cctally
+  re-exports the historical name. The shim below routes through
+  ``sys.modules['cctally']`` so test ``monkeypatch.setitem(ns, ...)``
+  on the historical name still overrides the 5 internal callers
+  here),
   ``_release_parse_semver`` / ``_release_semver_sort_key`` (lives
-  in ``_lib_semver`` and re-exported by cctally),
+  in ``_lib_semver``; shims below route directly to that module —
+  the cctally re-exports were removed in the release-command split
+  privatization),
   ``load_config`` (lives in ``_cctally_config``; re-exported),
   ``_BANNER_SUPPRESSED_COMMANDS`` (lives in ``_cctally_db``;
   re-exported by cctally — composed with the update-only
@@ -210,17 +216,35 @@ def load_config(*args, **kwargs):
 
 
 def _release_read_latest_release_version(*args, **kwargs):
+    """Back-compat shim. The implementation now lives in
+    ``bin/_lib_changelog._read_latest_changelog_version``; ``bin/cctally``
+    re-exports it under the historical name. This shim routes through
+    the ``cctally`` namespace (not directly to ``_lib_changelog``) so
+    that ``monkeypatch.setitem(ns, "_release_read_latest_release_version", ...)``
+    in tests/test_update.py + tests/test_release_internals.py overrides
+    the 5+ internal callers in this module. New code should call
+    ``_lib_changelog._read_latest_changelog_version`` directly.
+    """
     return sys.modules["cctally"]._release_read_latest_release_version(
         *args, **kwargs
     )
 
 
+# The semver shims now resolve via ``_lib_semver`` directly — the
+# cctally re-exports (``_release_parse_semver`` / ``_release_semver_sort_key``)
+# were removed in the release-command split privatization. Kept as
+# call-time shims (vs. module-top ``from _lib_semver import ...``) so
+# tests can still ``monkeypatch.setitem(ns, "_release_parse_semver", ...)``
+# on this module's namespace if needed; the bare-name lookup inside this
+# module resolves here, not at the import site.
 def _release_parse_semver(*args, **kwargs):
-    return sys.modules["cctally"]._release_parse_semver(*args, **kwargs)
+    import _lib_semver
+    return _lib_semver._release_parse_semver(*args, **kwargs)
 
 
 def _release_semver_sort_key(*args, **kwargs):
-    return sys.modules["cctally"]._release_semver_sort_key(*args, **kwargs)
+    import _lib_semver
+    return _lib_semver._release_semver_sort_key(*args, **kwargs)
 
 
 def _normalize_alerts_enabled_value(*args, **kwargs):

package/bin/_lib_changelog.py

@@ -0,0 +1,44 @@
+"""Public helper: read the latest stamped release header from CHANGELOG.md.
+
+Read-only. Pure with respect to inputs (CHANGELOG.md contents). The
+historical name ``_release_read_latest_release_version`` carried a
+``_release_`` prefix because the helper originated with the release-
+automation work, but the function is not release-machinery: doctor,
+the share kernel, and ``cctally --version`` all read it. Lives in a
+public sibling so the maintainer-only release tooling can move to a
+private artifact without dragging the version reader with it.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def _cctally():
+    """Call-time accessor for the ``cctally`` module (project memory
+    ``_cctally() accessor pattern``). Avoids module-top ``import cctally``
+    so monkeypatch-sensitive globals (``CHANGELOG_PATH`` and
+    ``RELEASE_HEADER_RE``) stay reachable for tests."""
+    return sys.modules["cctally"]
+
+
+def _read_latest_changelog_version() -> tuple[str, str] | None:
+    """Read latest ``## [X.Y.Z] - YYYY-MM-DD`` header from
+    ``CHANGELOG_PATH``. Returns ``(version, date)`` or ``None`` if the
+    file is missing or has no stamped release header.
+
+    Body is byte-equivalent to the original
+    ``_release_read_latest_release_version`` definition in ``bin/cctally``
+    (the rename is the only intentional change); the regex
+    ``RELEASE_HEADER_RE`` is read from the ``cctally`` module so any
+    in-process update to the pattern remains the single source of truth.
+    """
+    c = _cctally()
+    try:
+        text = c.CHANGELOG_PATH.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+    m = c.RELEASE_HEADER_RE.search(text)
+    if not m:
+        return None
+    return (m.group(1), m.group(2))

package/bin/_lib_semver.py

@@ -76,7 +76,7 @@ def _release_compute_next_version(
         return _release_format_semver(nxt_maj, nxt_min, nxt_pat, prerelease_id, 1)
 
     if is_prerelease:
-        raise ValueError("current version is a prerelease; run 'cctally release finalize' first or use --bump in a prerelease bump")
+        raise ValueError("current version is a prerelease; run 'cctally-release finalize' first or use --bump in a prerelease bump")
 
     if kind == "patch":
         return _release_format_semver(cur_maj, cur_min, cur_pat + 1)

package/bin/_lib_share_templates.py

@@ -289,8 +289,10 @@ def _release_version() -> str:
     at `bin/cctally:86`). Falls back to `"dev"` when CHANGELOG is unreadable
     or has no stamped release entry yet (pre-release dev builds).
 
-    Parallel to `_release_read_latest_release_version` in `bin/cctally` —
-    intentionally duplicated so the template module stays free of any
+    Parallel to `_lib_changelog._read_latest_changelog_version`
+    (re-exported on `bin/cctally` under the historical
+    `_release_read_latest_release_version` name) — intentionally
+    duplicated so the template module stays free of any
     `bin/cctally` import. If CHANGELOG header format changes, update both.
     """
     from pathlib import Path