cctally 1.21.1 → 1.21.2

package/CHANGELOG.md

@@ -5,6 +5,14 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.21.2] - 2026-05-28
+
+### Fixed
+- npm upgrades now self-heal `~/.local/bin/` symlinks for newly added subcommands: the postinstall best-effort runs an internal additive `repair-symlinks` pass (gated to existing installs), so a new `cctally-*` binary is reachable immediately after `npm install -g cctally@<newer>` without re-running `cctally setup` (#114).
+
+### Changed
+- `cctally doctor` / `cctally setup --status` now report subcommand symlinks as "available" and treat a command reachable on `$PATH` via another install channel (e.g. Homebrew) as present, instead of warning only because `~/.local/bin/` lacks the link (#114).
+
 ## [1.21.1] - 2026-05-28
 
 ### Fixed

package/bin/_cctally_db.py

@@ -1023,6 +1023,7 @@ _BANNER_SUPPRESSED_COMMANDS = frozenset({
     "doctor",          # consolidates migration + update banner state into its
                        # own report; double-printing the banner would duplicate
                        # findings doctor already surfaces structurally.
+    "repair-symlinks", # invoked by npm postinstall; no banner during install
     "blocks",          # stdout-formatted table replacing `ccusage blocks`;
                        # stderr noise pollutes the visually-aligned report and
                        # confuses scripted pipelines piping via `2>&1`.

package/bin/_cctally_setup.py

@@ -373,6 +373,44 @@ def _setup_create_symlinks(
     return results
 
 
+@dataclasses.dataclass
+class _RepairResult:
+    gated: bool
+    created: list[str]
+    failed: list[tuple[str, str]]  # (name, detail)
+
+
+def _setup_repair_symlinks(
+    repo_root: pathlib.Path, dst_dir: pathlib.Path,
+) -> _RepairResult:
+    """Additively reconcile ``dst_dir`` to ``SETUP_SYMLINK_NAMES`` (issue #114).
+
+    Existing-install gate: acts only when at least one
+    ``SETUP_SYMLINK_NAMES`` symlink is already present in ``dst_dir`` — a
+    fresh install (zero links) is left untouched so onboarding stays
+    opt-in. Strictly additive: creates only *genuinely empty* slots and
+    leaves present / wrong-target / dangling / non-symlink slots alone.
+    Touches nothing but ``~/.local/bin/`` symlinks (no hooks /
+    settings.json / cache). Filesystem-only — deliberately NOT PATH-aware
+    (unlike :func:`_setup_compute_symlink_state`), so it stays
+    deterministic regardless of the live ``PATH``.
+    """
+    names = _cctally().SETUP_SYMLINK_NAMES
+    present = [n for n in names if (dst_dir / n).is_symlink()]
+    if not present:
+        return _RepairResult(gated=True, created=[], failed=[])
+    missing = [
+        n for n in names
+        if not (dst_dir / n).is_symlink() and not (dst_dir / n).exists()
+    ]
+    if not missing:
+        return _RepairResult(gated=False, created=[], failed=[])
+    results = _setup_create_symlinks(repo_root, dst_dir, names=tuple(missing))
+    created = [r.name for r in results if r.status == "created"]
+    failed = [(r.name, r.detail) for r in results if r.status == "failed"]
+    return _RepairResult(gated=False, created=created, failed=failed)
+
+
 def _setup_cleanup_stale_symlinks(
     dst_dir: pathlib.Path,
 ) -> list[_SetupSymlinkResult]:
@@ -982,8 +1020,14 @@ def _setup_compute_symlink_state(
         keeps its own strict equality check for install-management
         (replace-vs-already).
       - "wrong": a non-symlink file occupies the slot, or the symlink
-        target is dangling.
-      - "missing": nothing at ``dst_dir/name``.
+        target is dangling. Unchanged by the PATH-aware fallback below —
+        a dangling/occupied slot stays "wrong" even if the command is
+        reachable elsewhere (that's the §9 brew-cleanup follow-up's job).
+      - "missing": nothing at ``dst_dir/name`` AND the command is not
+        reachable on ``$PATH`` via another channel. When the slot is
+        empty but ``shutil.which(name)`` resolves (e.g. a brew
+        ``<prefix>/bin`` install), the state is "ok" instead — the
+        diagnostic question is "is cctally-X invokable?" (issue #114).
 
     ``repo_root`` is unused here — retained on the signature for
     call-site stability across `_setup_status` and `doctor_gather_state`.
@@ -1000,6 +1044,12 @@ def _setup_compute_symlink_state(
                 out.append((name, "wrong"))
         elif dst.exists():
             out.append((name, "wrong"))
+        elif shutil.which(name):
+            # Slot empty in dst_dir but the command is reachable on PATH
+            # via another channel (e.g. brew's <prefix>/bin). The
+            # diagnostic question is "is cctally-X invokable?", so treat
+            # as ok rather than false-warning. (Issue #114.)
+            out.append((name, "ok"))
         else:
             out.append((name, "missing"))
     return out
@@ -1084,7 +1134,7 @@ def _setup_status(args: argparse.Namespace) -> int:
     out: list[str] = []
     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}")
+    out.append(f"  Symlinks       {sym_ok}/{len(c.SETUP_SYMLINK_NAMES)} available at {dst_dir}/  {sym_marker}")
     if stale_syms:
         out.append(
             f"  Stale symlinks {len(stale_syms)} from prior version: {', '.join(stale_syms)}  ⚠"

package/bin/_lib_doctor.py

@@ -157,14 +157,14 @@ def _check_install_symlinks(s: DoctorState) -> CheckResult:
     if not missing:
         return CheckResult(
             id="install.symlinks", title="Symlinks",
-            severity="ok", summary=f"{ok_count}/{total} present",
+            severity="ok", summary=f"{ok_count}/{total} available",
             remediation=None,
             details={"present": ok_count, "total": total, "missing": []},
         )
     return CheckResult(
         id="install.symlinks", title="Symlinks",
         severity="warn",
-        summary=f"{ok_count}/{total} present; missing {', '.join(missing)}",
+        summary=f"{ok_count}/{total} available; missing {', '.join(missing)}",
         remediation="Run `cctally setup`",
         details={"present": ok_count, "total": total, "missing": missing},
     )

package/bin/cctally

@@ -479,6 +479,7 @@ _SetupSymlinkResult = _cctally_setup._SetupSymlinkResult
 _setup_resolve_symlink_source = _cctally_setup._setup_resolve_symlink_source
 _setup_resolve_hook_target = _cctally_setup._setup_resolve_hook_target
 _setup_create_symlinks = _cctally_setup._setup_create_symlinks
+_setup_repair_symlinks = _cctally_setup._setup_repair_symlinks
 _setup_path_includes_local_bin = _cctally_setup._setup_path_includes_local_bin
 _setup_shell_rc_hint = _cctally_setup._setup_shell_rc_hint
 _setup_detect_legacy_snippet = _cctally_setup._setup_detect_legacy_snippet
@@ -13108,6 +13109,27 @@ def build_parser() -> argparse.ArgumentParser:
     )
     uc.set_defaults(func=cmd_update_check_internal)
 
+    # ---- repair-symlinks (internal — hidden; npm-postinstall self-heal, issue #114) ----
+    rs = sub.add_parser(
+        "repair-symlinks",
+        help=argparse.SUPPRESS,
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+            """\
+            Internal subcommand: additively create any missing
+            ~/.local/bin/ symlinks for cctally subcommands (issue #114).
+
+            Invoked best-effort by the npm postinstall on upgrade so new
+            cctally-* binaries become reachable without re-running
+            `cctally setup`. Gated to existing installs (>=1 symlink
+            already present); a fresh install is a silent no-op. Touches
+            only symlinks — no hooks, settings.json, or cache. Refuses
+            from a dev checkout.
+            """
+        ),
+    )
+    rs.set_defaults(func=cmd_repair_symlinks)
+
     # Python 3.14 leaks `==SUPPRESS==` for hidden subparsers in --help; strip
     # the pseudo-action so the row disappears entirely. (The choice still
     # appears in the `{...}` choices header — there's no clean way to hide
@@ -14921,6 +14943,33 @@ cmd_tui = _cctally_tui.cmd_tui
 _tui_render_once = _cctally_tui._tui_render_once
 
 
+def cmd_repair_symlinks(args: argparse.Namespace) -> int:
+    """Hidden: additively create missing ~/.local/bin/ symlinks on upgrade.
+
+    Invoked best-effort by the npm postinstall (issue #114). Refuses from
+    a dev checkout (would point ~/.local/bin at the dev tree). Touches
+    only symlinks — see _setup_repair_symlinks. Exempted from main()'s
+    post-command update hooks (see _post_command_update_hooks).
+    """
+    if _cctally_core._is_dev_checkout():
+        eprint(
+            "repair-symlinks: refusing to run from a dev checkout "
+            "(would point ~/.local/bin at the dev tree)"
+        )
+        return 2
+    repo_root = _setup_resolve_repo_root()
+    dst_dir = _setup_local_bin_dir()
+    result = _setup_repair_symlinks(repo_root, dst_dir)
+    if result.created:
+        print(
+            f"cctally: linked {len(result.created)} new command symlink(s): "
+            + ", ".join(result.created)
+        )
+    for name, detail in result.failed:
+        eprint(f"repair-symlinks: {name}: {detail}")
+    return 1 if result.failed else 0
+
+
 def main(argv: list[str] | None = None) -> int:
     _migrate_legacy_data_dir()
     parser = build_parser()
@@ -14994,11 +15043,21 @@ def _post_command_update_hooks(command: str | None, args) -> None:
     does not stop these side effects. Doctor reads update state for
     its report via the gather layer; it must not refresh that state
     opportunistically. Users who want a fresh check have
-    ``cctally update --check``."""
+    ``cctally update --check``.
+
+    Skip-for-repair-symlinks: ``repair-symlinks`` is spawned by the npm
+    postinstall on every install (issue #114). It must touch nothing but
+    ~/.local/bin/ symlinks — running ``load_config()`` /
+    ``_spawn_background_update_check`` here would create ``config.json``,
+    ``update-state.json``, and ``update.log`` on a fresh install where
+    the existing-install gate already makes the symlink work a no-op.
+    Same rationale as doctor."""
     if command == "setup" and getattr(args, "uninstall", False):
         return
     if command == "doctor":
         return
+    if command == "repair-symlinks":
+        return
     # Self-heal: reconcile current_version with the running binary's
     # CHANGELOG. Cheap (one CHANGELOG read, write only on the first
     # command after a manual upgrade). Runs before load_config so a

package/bin/cctally-npm-postinstall.js

@@ -16,6 +16,20 @@ if (process.env.CCTALLY_NPM_POSTINSTALL_QUIET === '1') {
   process.exit(0);
 }
 
+// Best-effort symlink self-heal on upgrade (issue #114): additively
+// create ~/.local/bin/ symlinks for any new cctally-* subcommands so an
+// upgrade doesn't strand them until the user re-runs `cctally setup`.
+// MUST NOT fail the npm install — swallow every error, ignore exit code.
+try {
+  const { spawnSync } = require('child_process');
+  const path = require('path');
+  const python = process.env.CCTALLY_PYTHON || 'python3';
+  const scriptPath = path.join(__dirname, 'cctally');
+  spawnSync(python, [scriptPath, 'repair-symlinks'], { stdio: 'inherit' });
+} catch (_) {
+  // best-effort only
+}
+
 process.stdout.write(
   '\ncctally installed.\n' +
   '\nTo finish setup, run:\n' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cctally",
-  "version": "1.21.1",
+  "version": "1.21.2",
   "description": "Claude Code usage tracker and local dashboard for Pro/Max subscription limits - weekly cost-per-percent trend, quota forecasts, threshold alerts. ccusage-compatible.",
   "homepage": "https://github.com/omrikais/cctally",
   "repository": {