cc-session-tools 2.12.2__tar.gz → 2.12.3__tar.gz

{cc_session_tools-2.12.2/src/cc_session_tools.egg-info → cc_session_tools-2.12.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 2.12.2
+Version: 2.12.3
 Summary: Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (cccs_hooks)
 Author: raffishquartan
 License: MIT License

{cc_session_tools-2.12.2 → cc_session_tools-2.12.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "2.12.2"
+version = "2.12.3"
 description = "Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (cccs_hooks)"
 readme = "README.md"
 license = { file = "LICENSE" }

{cc_session_tools-2.12.2 → cc_session_tools-2.12.3}/src/cc_session_tools/cli/ccst.py

@@ -2132,12 +2132,17 @@ def _cmd_ccsched_jobs_install(args: argparse.Namespace) -> int:
     for job in bundled_jobs.BUNDLED_CCSCHED_JOBS:
         spec = existing.get(job.job_id)
         if spec is not None:
-            changed = bundled_jobs.diff_from_bundled(spec, job)
-            if changed:
+            changed_detail = bundled_jobs.diff_from_bundled_detail(spec, job)
+            if changed_detail:
+                field_word = "field differs" if len(changed_detail) == 1 else "fields differ"
                 print(
-                    f"  changed (not touched): {job.job_id} - {', '.join(changed)} "
-                    f"differ from the bundled definition; run 'ccsched edit' to realign, or "
-                    f"leave as your intentional customization"
+                    f"  changed (not touched): {job.job_id} - {len(changed_detail)} "
+                    f"{field_word} from the bundled definition:"
+                )
+                print(bundled_jobs.render_field_diffs(changed_detail))
+                print(
+                    f"  run 'ccsched edit {job.job_id}' to realign, or leave as your "
+                    f"intentional customization"
                 )
             elif not spec.enabled:
                 print(f"  disabled (not touched): {job.job_id} - run 'ccsched enable {job.job_id}' to re-enable")

{cc_session_tools-2.12.2 → cc_session_tools-2.12.3}/src/cc_session_tools/lib/doctor.py

@@ -256,16 +256,20 @@ def check_ccsched_job_registered(
     for spec in specs:
         if spec.job_id == job_id:
             if expected is not None:
-                from cc_session_tools.lib.scheduler.bundled_jobs import diff_from_bundled
+                from cc_session_tools.lib.scheduler.bundled_jobs import (
+                    diff_from_bundled_detail, render_field_diffs,
+                )
 
-                changed = diff_from_bundled(spec, expected)
-                if changed:
+                changed_detail = diff_from_bundled_detail(spec, expected)
+                if changed_detail:
+                    field_word = "field differs" if len(changed_detail) == 1 else "fields differ"
                     return CheckResult(
                         name=name, status=Status.WARN,
                         reason=(
-                            f"registered but {', '.join(changed)} differ from the bundled "
-                            f"definition — run 'ccst ccsched-jobs install --apply' to see the "
-                            f"diff, or 'ccsched edit {job_id}' if this was intentional"
+                            f"registered but {len(changed_detail)} {field_word} from "
+                            f"the bundled definition:\n{render_field_diffs(changed_detail)}\n"
+                            f"run 'ccsched edit {job_id}' to realign, or leave as your "
+                            f"intentional customization"
                         ),
                     )
             if spec.enabled:

{cc_session_tools-2.12.2 → cc_session_tools-2.12.3}/src/cc_session_tools/lib/scheduler/bundled_jobs.py

@@ -10,6 +10,7 @@ deliberately excludes `enabled`: that is per-machine operational state a human t
 `_cmd_ccsched_jobs_install` and `doctor.check_ccsched_job_registered`, the two callers."""
 from __future__ import annotations
 
+import shlex
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -183,23 +184,65 @@ BUNDLED_CCSCHED_JOBS: tuple[BundledJob, ...] = (
 )
 
 
-def diff_from_bundled(spec: "JobSpec", job: BundledJob) -> tuple[str, ...]:
-    """Names of the fields where a registered JobSpec no longer matches its bundled
-    definition, in declaration order; empty if it matches exactly. Deliberately ignores
-    `enabled` — see module docstring."""
-    differing: list[str] = []
+@dataclass(frozen=True, slots=True)
+class FieldDiff:
+    """One field where a registered JobSpec no longer matches its bundled definition,
+    carrying both the bundled and the current (live) value, rendered as display-ready
+    strings so a caller never has to know a field's underlying type - see
+    `diff_from_bundled_detail`."""
+    field: str
+    bundled: str
+    current: str
+
+
+def diff_from_bundled_detail(spec: "JobSpec", job: BundledJob) -> tuple[FieldDiff, ...]:
+    """Same comparison as `diff_from_bundled`, but carries the before/after values for
+    display, in declaration order; empty if the spec matches its bundled definition
+    exactly. Deliberately ignores `enabled` — see module docstring. This is the one place
+    that decides both *whether* a field changed and *how* its value is rendered, so
+    `_cmd_ccsched_jobs_install` and `check_ccsched_job_registered` — the two callers —
+    can never disagree on either question."""
+    diffs: list[FieldDiff] = []
     if spec.cadence != job.cadence:
-        differing.append("cadence")
+        diffs.append(FieldDiff("cadence", job.cadence, spec.cadence))
     if spec.coalesce.value != job.coalesce:
-        differing.append("coalesce")
+        diffs.append(FieldDiff("coalesce", job.coalesce, spec.coalesce.value))
     if spec.catchup_window != job.catchup_window:
-        differing.append("catchup_window")
+        diffs.append(FieldDiff("catchup_window", job.catchup_window, spec.catchup_window))
     if spec.timeout != job.timeout:
-        differing.append("timeout")
+        diffs.append(FieldDiff("timeout", job.timeout, spec.timeout))
     if spec.surface != job.surface:
-        differing.append("surface")
+        diffs.append(FieldDiff("surface", str(job.surface), str(spec.surface)))
     if spec.command != job.command:
-        differing.append("command")
+        # shlex.join renders as an actual shell line, not a Python tuple repr - readable
+        # for a multi-arg command.
+        diffs.append(FieldDiff("command", shlex.join(job.command), shlex.join(spec.command)))
     if spec.success_exit_codes != job.success_exit_codes:
-        differing.append("success_exit_codes")
-    return tuple(differing)
+        diffs.append(FieldDiff(
+            "success_exit_codes",
+            ", ".join(str(c) for c in job.success_exit_codes),
+            ", ".join(str(c) for c in spec.success_exit_codes),
+        ))
+    return tuple(diffs)
+
+
+def diff_from_bundled(spec: "JobSpec", job: BundledJob) -> tuple[str, ...]:
+    """Names of the fields where a registered JobSpec no longer matches its bundled
+    definition, in declaration order; empty if it matches exactly. A thin wrapper over
+    `diff_from_bundled_detail` so both callers stay guaranteed-identical in what counts
+    as "changed" — see module docstring."""
+    return tuple(fd.field for fd in diff_from_bundled_detail(spec, job))
+
+
+def render_field_diffs(diffs: tuple[FieldDiff, ...], *, indent: str = "    ") -> str:
+    """Shared before/after rendering for a non-empty `diff_from_bundled_detail` result -
+    one `field:` sub-block per entry, in the same order, `-`/`+` prefixed so it reads as a
+    diff without pulling in `difflib`. Both `_cmd_ccsched_jobs_install` and
+    `check_ccsched_job_registered` call this so they render byte-identical bodies and only
+    differ in the header/hint text wrapped around it."""
+    lines: list[str] = []
+    for d in diffs:
+        lines.append(f"{indent}{d.field}:")
+        lines.append(f"{indent}  - bundled: {d.bundled}")
+        lines.append(f"{indent}  + current: {d.current}")
+    return "\n".join(lines)

{cc_session_tools-2.12.2 → cc_session_tools-2.12.3}/src/cc_session_tools/lib/scheduler/digest.py

@@ -40,6 +40,11 @@ class JobReport:
     # exclusive with `findings`: a given run is either a clean 0-exit or a
     # findings-bearing nonzero exit, never both.
     output: str | None = None
+    # RAN with output and count > 1 only: the span from the oldest coalesced
+    # run to now (e.g. "11h", "2d"), formatted without an "ago" suffix so it
+    # reads as a window ("... in last {window}:") rather than a point in time
+    # - see surface.py's per-job clean-output coalescing.
+    window: str | None = None
 
 
 def _ordinal(n: int) -> str:
@@ -90,7 +95,17 @@ def _line(report: JobReport) -> str | None:
             # distinct from the findings/warning case above so a passing check
             # is never mistaken for one that found something. One line-group:
             # never falls through to the bare "✓ ran" case below.
-            header = f"✓ ran {report.job_id}{overdue}{age_suffix}:"
+            if report.count > 1:
+                # Several clean-output runs of the same job coalesced within
+                # one sweep (§ output-coalesce fix, mirrors the bare-run
+                # coalesce below) - one line carrying a count and the window
+                # they span, body is the most recent run's output only.
+                header = (
+                    f"✓ ran {report.job_id}{age_suffix} "
+                    f"({report.count} times in last {report.window}):"
+                )
+            else:
+                header = f"✓ ran {report.job_id}{overdue}{age_suffix}:"
             body = "\n".join(f"  {line}" for line in report.output.splitlines())
             return f"{header}\n{body}"
         if report.count > 1:

{cc_session_tools-2.12.2 → cc_session_tools-2.12.3}/src/cc_session_tools/lib/scheduler/surface.py

@@ -17,6 +17,13 @@ unconditionally rather than the per-job flag, since digest.py never consults
 `surface` for Outcome.RAN — the per-job flag is only meaningful for LAUNCH,
 where it is still looked up via `_surface_flag`.
 
+A clean (0-exit) run's captured stdout coalesces per job_id the same way bare
+routine runs do: several such runs for the same job within one digest render
+as one line carrying a count, the span they cover, and only the MOST RECENT
+run's output (§ output-coalesce fix) — see `_output_reports`. Findings
+(nonzero-exit captured stdout) are exempt, same as FAILED/SUSPENDED: they are
+signal, never folded, always replayed individually with their own age suffix.
+
 `surface(..., lookback=...)` optionally widens the read below the session's
 own cursor to also pick up ledger activity within `lookback` of `now`, for the
 SessionStart 24h rolling lookback (§ widen fix) — see catchup.py, the only
@@ -81,6 +88,19 @@ def _format_age(sent: datetime | None, now: datetime) -> str:
     return f"{hours // 24}d ago"
 
 
+def _format_span(oldest: datetime, now: datetime) -> str:
+    """Same buckets as `_format_age`, but as a window ("11h") rather than a
+    point in time ("11h ago") - for the "N times in last {span}" wording on
+    coalesced clean-output runs."""
+    minutes = max(1, int((now - oldest).total_seconds() // 60))
+    if minutes < 60:
+        return f"{minutes}m"
+    hours = minutes // 60
+    if hours < 24:
+        return f"{hours}h"
+    return f"{hours // 24}d"
+
+
 # Sort key for an entry whose ts is missing/unparseable - sorts first, same
 # convention as `_format_age`'s "unknown time ago" treating it as maximally old.
 _UNKNOWN_TS = datetime.min.replace(tzinfo=timezone.utc)
@@ -161,6 +181,51 @@ def _routine_reports(
     return out
 
 
+def _output_reports(
+    entries: list[dict[str, object]], *, now: datetime,
+) -> list[tuple[datetime, JobReport]]:
+    """Clean-output (0-exit, captured stdout) RUN/BACKFILL entries, grouped by
+    job_id. A job_id with only one entry renders exactly as before (no count
+    suffix). A job_id with several entries within one digest coalesces to one
+    line carrying a count, the span the group covers, and only the MOST
+    RECENT entry's output - not N near-identical output blocks for the same
+    job (§ output-coalesce fix). Findings-bearing (nonzero-exit) entries never
+    reach this function - they are signal, not routine noise, and always
+    replay individually (see the caller)."""
+    groups: dict[str, list[dict[str, object]]] = {}
+    for e in entries:
+        groups.setdefault(str(e.get("job_id", "")), []).append(e)
+
+    out: list[tuple[datetime, JobReport]] = []
+    for job_id, group in groups.items():
+        timestamps = [_parse_ts(g.get("ts")) for g in group]
+        latest = max((t for t in timestamps if t is not None), default=None)
+        oldest = min((t for t in timestamps if t is not None), default=None)
+        sort_ts = latest if latest is not None else _UNKNOWN_TS
+        if len(group) == 1:
+            e = group[0]
+            out.append((sort_ts, JobReport(
+                job_id=job_id, outcome=Outcome.RAN, surface=True, overdue="",
+                ran=int(cast(int, e.get("ran", 0)) or 0), deferred=0, expired=0,
+                consecutive_failures=0, age=_format_age(latest, now),
+                output=str(e.get("error")),
+            )))
+            continue
+        # Most recent entry by ts (fall back to list order for unparseable ts).
+        latest_entry = max(
+            group, key=lambda g: (_parse_ts(g.get("ts")) or _UNKNOWN_TS),
+        )
+        window = _format_span(oldest, now) if oldest is not None else "unknown time"
+        out.append((sort_ts, JobReport(
+            job_id=job_id, outcome=Outcome.RAN, surface=True, overdue="",
+            ran=sum(int(cast(int, g.get("ran", 0)) or 0) for g in group),
+            deferred=0, expired=0, consecutive_failures=0,
+            age=_format_age(latest, now), count=len(group),
+            output=str(latest_entry.get("error")), window=window,
+        )))
+    return out
+
+
 def surface(
     *, session_uuid: str, now: datetime, lookback: timedelta | None = None,
 ) -> SurfaceResult:
@@ -185,6 +250,7 @@ def surface(
     # them.
     pairs: list[tuple[datetime, JobReport]] = []
     routine: list[dict[str, object]] = []
+    clean_output: list[dict[str, object]] = []
     for e in entries:
         event = str(e.get("event", ""))
         job_id = str(e.get("job_id", ""))
@@ -218,20 +284,23 @@ def surface(
             captured = e.get("error")
             if captured:
                 is_warning = raw_exit not in (0, None)
-                # surface=True unconditionally: a completed run is always
-                # visible, so the per-job flag is not load-bearing here (see
-                # module docstring) - matches the pre-existing findings
-                # convention rather than the FAILED/SUSPENDED "write the real
-                # flag, bypass it in digest.py" one, since digest.py does not
-                # even look at `surface` for Outcome.RAN.
-                pairs.append((sort_ts, JobReport(
-                    job_id=job_id, outcome=Outcome.RAN, surface=True, overdue="",
-                    ran=int(cast(int, e.get("ran", 0)) or 0), deferred=0, expired=0,
-                    consecutive_failures=0,
-                    findings=str(captured) if is_warning else None,
-                    output=str(captured) if not is_warning else None,
-                    age=_format_age(sent, now),
-                )))
+                if is_warning:
+                    # Findings are signal, not routine noise - never coalesced,
+                    # always replayed individually (see module docstring).
+                    # surface=True unconditionally: a completed run is always
+                    # visible, so the per-job flag is not load-bearing here.
+                    pairs.append((sort_ts, JobReport(
+                        job_id=job_id, outcome=Outcome.RAN, surface=True, overdue="",
+                        ran=int(cast(int, e.get("ran", 0)) or 0), deferred=0, expired=0,
+                        consecutive_failures=0, findings=str(captured),
+                        age=_format_age(sent, now),
+                    )))
+                else:
+                    # A clean (0-exit) run's captured stdout - eligible for
+                    # per-job_id coalescing (§ output-coalesce fix), same
+                    # spirit as the bare-run routine fold below but keeping
+                    # the most recent output rather than dropping it.
+                    clean_output.append(e)
             else:
                 # A bare clean run with no captured stdout - still eligible
                 # for the routine backlog fold (spam control, not the
@@ -249,6 +318,7 @@ def surface(
         # skip_expired and defer events are not surfaced as standalone lines.
 
     pairs.extend(_routine_reports(routine, now=now))
+    pairs.extend(_output_reports(clean_output, now=now))
     pairs.sort(key=lambda p: p[0])
 
     cursor.write_cursor(session_uuid, new_offset)

{cc_session_tools-2.12.2 → cc_session_tools-2.12.3/src/cc_session_tools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 2.12.2
+Version: 2.12.3
 Summary: Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (cccs_hooks)
 Author: raffishquartan
 License: MIT License

{cc_session_tools-2.12.2 → cc_session_tools-2.12.3}/tests/test_ccst_ccsched_jobs_cli.py

@@ -93,7 +93,14 @@ def test_changed_job_is_reported_not_touched_and_not_overwritten(base_env):
 
     r = _run(base_env, "ccsched-jobs", "install", "--apply")
     assert r.returncode == 0, r.stderr
-    assert "changed (not touched): telemetry-trim-weekly - timeout" in r.stdout
+    assert (
+        "changed (not touched): telemetry-trim-weekly - 1 field differs "
+        "from the bundled definition:" in r.stdout
+    )
+    assert "timeout:" in r.stdout
+    assert "- bundled: 60s" in r.stdout
+    assert "+ current: 9s" in r.stdout
+    assert "run 'ccsched edit telemetry-trim-weekly' to realign" in r.stdout
     assert "already registered: telemetry-trim-weekly" not in r.stdout
 
     show = subprocess.run(

{cc_session_tools-2.12.2 → cc_session_tools-2.12.3}/tests/test_ccst_doctor.py

@@ -1207,6 +1207,34 @@ def test_check_ccsched_job_registered_warns_on_drift_from_bundled_definition(
     assert "timeout" in result.reason
 
 
+def test_check_ccsched_job_registered_shows_before_and_after_values_not_just_field_name(
+    monkeypatch, tmp_path
+) -> None:
+    """§ diff-detail fix: the reason must carry the actual bundled/current values, not just
+    name the field that differs — no more 'run install --apply to see the diff' indirection."""
+    monkeypatch.setenv("CCST_DATA_HOME", str(tmp_path))
+    from cc_session_tools.lib.scheduler import bundled_jobs, registry
+    from cc_session_tools.lib.scheduler.jobspec import validate_job_fields
+
+    job = next(
+        j for j in bundled_jobs.BUNDLED_CCSCHED_JOBS if j.job_id == "telemetry-trim-weekly"
+    )
+    spec = validate_job_fields(
+        job_id=job.job_id, cadence=job.cadence, coalesce=job.coalesce,
+        command=list(job.command), surface=job.surface, enabled=True,
+        catchup_window=job.catchup_window, timeout="9s",
+        success_exit_codes=job.success_exit_codes,
+    )
+    registry.add_job(spec)
+
+    result = check_ccsched_job_registered(job.job_id, expected=job)
+    assert "1 field differ" in result.reason
+    assert "- bundled: 60s" in result.reason
+    assert "+ current: 9s" in result.reason
+    assert "run 'ccsched edit telemetry-trim-weekly' to realign" in result.reason
+    assert "install --apply' to see the diff" not in result.reason
+
+
 def test_check_ccsched_job_registered_ok_when_matching_bundled_definition(
     monkeypatch, tmp_path
 ) -> None:

{cc_session_tools-2.12.2 → cc_session_tools-2.12.3}/tests/test_scheduler_bundled_jobs.py

@@ -3,7 +3,9 @@ from __future__ import annotations
 from pathlib import Path
 
 from cc_session_tools.lib.scheduler import bundled_jobs
-from cc_session_tools.lib.scheduler.bundled_jobs import diff_from_bundled
+from cc_session_tools.lib.scheduler.bundled_jobs import (
+    diff_from_bundled, diff_from_bundled_detail, render_field_diffs,
+)
 from cc_session_tools.lib.scheduler.jobspec import validate_job_fields
 
 
@@ -209,3 +211,60 @@ def test_diff_from_bundled_detects_a_changed_command():
     job = _job("pdata-verify-all")
     spec = _spec_for(job, command=["ccst", "pdata", "verify", "--project", "x"])
     assert diff_from_bundled(spec, job) == ("command",)
+
+
+def test_diff_from_bundled_detail_is_empty_when_nothing_differs():
+    job = _job("pdata-verify-all")
+    assert diff_from_bundled_detail(_spec_for(job), job) == ()
+
+
+def test_diff_from_bundled_detail_carries_before_and_after_for_one_field():
+    job = _job("pdata-verify-all")
+    spec = _spec_for(job, timeout="30s")
+    diffs = diff_from_bundled_detail(spec, job)
+    assert len(diffs) == 1
+    assert diffs[0].field == "timeout"
+    assert diffs[0].bundled == job.timeout
+    assert diffs[0].current == "30s"
+
+
+def test_diff_from_bundled_detail_carries_every_differing_field_in_order():
+    job = _job("pdata-verify-all")
+    spec = _spec_for(job, cadence="every:3d", timeout="30s")
+    diffs = diff_from_bundled_detail(spec, job)
+    assert [d.field for d in diffs] == ["cadence", "timeout"]
+    assert diffs[0].bundled == job.cadence
+    assert diffs[0].current == "every:3d"
+
+
+def test_diff_from_bundled_detail_renders_command_as_a_shell_line_not_a_tuple_repr():
+    job = _job("pdata-verify-all")
+    spec = _spec_for(job, command=["ccst", "pdata", "verify", "--project", "x y"])
+    diffs = diff_from_bundled_detail(spec, job)
+    assert len(diffs) == 1
+    assert diffs[0].field == "command"
+    assert diffs[0].bundled == "ccst pdata verify --all-projects"
+    # shlex.join quotes the argument containing a space, unlike a bare join(" ")
+    assert diffs[0].current == "ccst pdata verify --project 'x y'"
+
+
+def test_diff_from_bundled_detail_is_the_single_source_diff_from_bundled_wraps():
+    """diff_from_bundled must return exactly the field names diff_from_bundled_detail
+    reports, in the same order — the two can never disagree since one wraps the other."""
+    job = _job("pdata-verify-all")
+    spec = _spec_for(job, cadence="every:3d", timeout="30s")
+    assert diff_from_bundled(spec, job) == tuple(
+        d.field for d in diff_from_bundled_detail(spec, job)
+    )
+
+
+def test_render_field_diffs_shows_dash_bundled_plus_current_per_field():
+    job = _job("pdata-verify-all")
+    spec = _spec_for(job, cadence="every:3d", timeout="30s")
+    out = render_field_diffs(diff_from_bundled_detail(spec, job))
+    assert "cadence:" in out
+    assert "- bundled: daily@03:00" in out
+    assert "+ current: every:3d" in out
+    assert "timeout:" in out
+    assert "- bundled: 300s" in out
+    assert "+ current: 30s" in out