cctally 1.21.0 → 1.21.2

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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
+- **`cctally statusline` now shows the correct 7d percentage after an Anthropic mid-week reset (or in-place credit) instead of staying pinned to the pre-reset peak.** The statusline's 7d number is monotonic-clamped against a high-water mark read from `weekly_usage_snapshots`, but the clamp keyed only on `week_start_date` — `SELECT MAX(weekly_percent) WHERE week_start_date = ?`. When Anthropic resets a 7d window mid-cycle, the post-reset snapshots keep the *same* `week_start_date` (and `week_end_at`) as the pre-reset ramp, so the bucket-wide `MAX` returned the stale pre-reset peak (e.g. 41%) and clamped the true post-reset value (e.g. 2%) back up to it; the statusline read e.g. `7d 41%` while `cctally report`/`forecast` and the dashboard — which segment the week at the reset via `week_reset_events` — correctly showed 2%. The 5h segment was never affected because a 5h reset mints a new `five_hour_window_key` that naturally scopes its `MAX`. The clamp now mirrors the CLI/dashboard segmentation (`_apply_reset_events_to_subweeks`: the post-reset window's `start_ts` becomes `effective_reset_at_utc`) by flooring the `MAX` to snapshots captured at/after the latest reset effective within the current window — `... AND unixepoch(captured_at_utc) >= unixepoch(<floor>)`, with `unixepoch()` on both sides because reset rows carry mixed offset spellings (`+00:00` and legacy `+03:00`) while `captured_at_utc` uses `Z`, so a lexical comparison would misorder them (the same rule the 5h-block cross-reset flag follows). Weeks with no reset event take the unchanged legacy query, so the normal monotonic-within-window behavior is byte-identical. Regression: new `extensions-hwm-7d-post-reset` fixture in `bin/cctally-statusline-test` (33 scenarios) seeds a pre-reset peak + post-reset row sharing one `week_start_date` plus a `week_reset_events` row and asserts the rendered line reads `7d 2%`, not `7d 41%`.
+
 ## [1.21.0] - 2026-05-28
 
 ### Added

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
@@ -4953,17 +4954,56 @@ def _build_statusline_injections(warn_once):
                     pass
             if seven_resets is not None:
                 try:
-                    # Seven-day window: derive week_start_date from the
-                    # resets_at epoch (reset - 7 days, UTC date).
-                    week_start_date = dt.datetime.fromtimestamp(
-                        int(seven_resets) - 7 * 86400, tz=dt.timezone.utc,
-                    ).date().isoformat()
-                    row = conn.execute(
-                        "SELECT MAX(weekly_percent) "
-                        "FROM weekly_usage_snapshots "
-                        "WHERE week_start_date = ?",
-                        (week_start_date,),
+                    # Seven-day window bounds from the resets_at epoch:
+                    # week_end = reset; week_start = reset - 7 days. The
+                    # date form is the snapshot lookup key (week_start_date
+                    # is deliberately NOT re-anchored across a mid-week
+                    # reset — see _apply_reset_events_to_subweeks).
+                    week_end_dt = dt.datetime.fromtimestamp(
+                        int(seven_resets), tz=dt.timezone.utc,
+                    )
+                    week_start_dt = week_end_dt - dt.timedelta(days=7)
+                    week_start_date = week_start_dt.date().isoformat()
+                    # Reset-aware floor. An Anthropic mid-week reset / in-
+                    # place credit leaves the pre-reset peak snapshots in
+                    # this SAME week_start_date bucket (the boundary the
+                    # snapshots carry does not change). A naive bucket-wide
+                    # MAX(weekly_percent) would clamp the post-reset value
+                    # UP to that stale peak — the statusline would show the
+                    # pre-reset 7d %. Mirror the CLI/dashboard segmentation
+                    # (_apply_reset_events_to_subweeks: post-reset window
+                    # start_ts := effective_reset_at_utc) by flooring the
+                    # MAX to snapshots captured at/after the latest reset
+                    # effective WITHIN this window. unixepoch() on both
+                    # sides — reset rows carry mixed offset spellings
+                    # (+00:00 / +03:00) while captured_at_utc uses 'Z', so a
+                    # lexical compare would misorder them (same rule as the
+                    # 5h-block cross-reset flag).
+                    floor_row = conn.execute(
+                        "SELECT MAX(effective_reset_at_utc) "
+                        "FROM week_reset_events "
+                        "WHERE unixepoch(effective_reset_at_utc) >= unixepoch(?) "
+                        "  AND unixepoch(effective_reset_at_utc) <  unixepoch(?)",
+                        (week_start_dt.isoformat(), week_end_dt.isoformat()),
                     ).fetchone()
+                    floor_iso = (
+                        floor_row[0] if floor_row and floor_row[0] else None
+                    )
+                    if floor_iso is not None:
+                        row = conn.execute(
+                            "SELECT MAX(weekly_percent) "
+                            "FROM weekly_usage_snapshots "
+                            "WHERE week_start_date = ? "
+                            "  AND unixepoch(captured_at_utc) >= unixepoch(?)",
+                            (week_start_date, floor_iso),
+                        ).fetchone()
+                    else:
+                        row = conn.execute(
+                            "SELECT MAX(weekly_percent) "
+                            "FROM weekly_usage_snapshots "
+                            "WHERE week_start_date = ?",
+                            (week_start_date,),
+                        ).fetchone()
                     if row and row[0] is not None:
                         seven_hwm = float(row[0])
                 except Exception:
@@ -13069,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
@@ -14882,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()
@@ -14955,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.0",
+  "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": {