cc-session-tools 3.12.0__tar.gz → 3.12.2__tar.gz

{cc_session_tools-3.12.0/src/cc_session_tools.egg-info → cc_session_tools-3.12.2}/PKG-INFO

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

{cc_session_tools-3.12.0 → cc_session_tools-3.12.2}/pyproject.toml

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

{cc_session_tools-3.12.0 → cc_session_tools-3.12.2}/src/cc_session_tools/lib/doctor.py

@@ -14,7 +14,6 @@ import os
 import shutil
 import sqlite3
 import subprocess
-import time
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
@@ -29,6 +28,7 @@ from cc_session_tools.lib.pdata.init_paths import (
     MIGRATED_MANIFEST_FILENAME,
 )
 from cc_session_tools.lib.text_wrap import wrap_block
+from cc_session_tools.lib.timefmt import format_utc, format_utc_epoch
 
 if TYPE_CHECKING:
     from cc_session_tools.lib.install_sync import FailedAttempt
@@ -480,7 +480,7 @@ def check_install_everything_synced(
             reason=(
                 f"installed {installed_version}, and the automatic install sync already "
                 f"failed for this version (rc {failed_attempt.rc} at "
-                f"{failed_attempt.at.strftime('%Y-%m-%d %H:%M UTC')}) — "
+                f"{format_utc(failed_attempt.at)}) — "
                 "run `ccst install-everything --apply` to see why"
             ),
         )
@@ -854,7 +854,7 @@ def check_pending_pdata_migration(projects_root: Path) -> list[CheckResult]:
 
 
 def _fmt_epoch(epoch: int) -> str:
-    return time.strftime("%Y-%m-%d %H:%M UTC", time.gmtime(epoch))
+    return format_utc_epoch(epoch)
 
 
 def check_pdata_verify(projects: list[str]) -> list[CheckResult]:

{cc_session_tools-3.12.0 → cc_session_tools-3.12.2}/src/cc_session_tools/lib/install_sync.py

@@ -24,6 +24,7 @@ from enum import Enum
 from pathlib import Path
 
 from cc_session_tools.lib import sessions_db
+from cc_session_tools.lib.timefmt import format_utc
 
 _SYNCED_VERSION_KEY = "synced_version"
 
@@ -301,7 +302,7 @@ def ensure_synced(*, noun: str | None, verb: str | None, installed_version: str)
             )
         print(
             f"ccst: install config is out of sync (installed {installed_version}, {state}) "
-            f"and the last auto-sync failed at {last_failure.at.strftime('%Y-%m-%d %H:%M UTC')} — "
+            f"and the last auto-sync failed at {format_utc(last_failure.at)} — "
             "run `ccst install-everything --apply` to see why.",
             file=sys.stderr,
         )

{cc_session_tools-3.12.0 → cc_session_tools-3.12.2}/src/cc_session_tools/lib/messaging/service.py

@@ -8,6 +8,7 @@ from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Literal
 
+from cc_session_tools.lib.timefmt import format_utc
 from cc_session_tools.lib.messaging import cursor as cursor_mod
 from cc_session_tools.lib.messaging import repository
 from cc_session_tools.lib.messaging import retention
@@ -136,9 +137,13 @@ def list_messages(
 
 
 def format_sent_at(sent_at: str) -> str:
-    """Render a stored `sent_at` machine timestamp as `yyyy-MM-dd HH:mm UTC` for a human."""
-    sent = datetime.strptime(sent_at, "%Y-%m-%dT%H:%M:%SZ")
-    return sent.strftime("%Y-%m-%d %H:%M UTC")
+    """Render a stored `sent_at` machine timestamp as `yyyy-MM-dd HH:mm UTC` for a human; a value
+    not in the writer's shape is returned as stored so the message stays readable."""
+    try:
+        sent = datetime.strptime(sent_at, "%Y-%m-%dT%H:%M:%SZ")
+    except ValueError:
+        return sent_at
+    return format_utc(sent)
 
 
 def relative_age(sent_at: str, now: datetime) -> str:

{cc_session_tools-3.12.0 → cc_session_tools-3.12.2}/src/cc_session_tools/lib/pdata/cutover.py

@@ -2,7 +2,6 @@
 from __future__ import annotations
 
 import os
-import time
 from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
@@ -12,6 +11,7 @@ from cc_session_tools.lib.pdata.init_paths import (
     MIGRATED_MANIFEST_FILENAME,
 )
 from cc_session_tools.lib.pdata.manifest import ManifestEntry
+from cc_session_tools.lib.timefmt import format_utc_epoch
 
 
 _POINTER_BODY_PREFIX = "This file's data now lives in pdata record group"
@@ -190,7 +190,7 @@ def archive_entries(
     archive_root = project_root / MIGRATED_ARCHIVE_DIRNAME
     archive_root.mkdir(parents=True, exist_ok=True)
     manifest_path = archive_root / MIGRATED_MANIFEST_FILENAME
-    now = time.strftime("%Y-%m-%d %H:%M UTC", time.gmtime())
+    now = format_utc_epoch()
     outcomes: list[PointerPlan] = []
     with manifest_path.open("a", encoding="utf-8") as log:
         for index, entry in enumerate(entries):

{cc_session_tools-3.12.0 → cc_session_tools-3.12.2}/src/cc_session_tools/lib/pdata/readiness.py

@@ -89,10 +89,26 @@ def _is_real_yyyymmdd(value: str) -> bool:
     return 1900 <= parsed.year <= 2100
 
 
+_COMPACT_DATETIME = re.compile(r"(\d{8})T(\d{2})(\d{2})(\d{2})?Z?")
+
+
+def _is_compact_datetime(value: str) -> bool:
+    match = _COMPACT_DATETIME.fullmatch(value)
+    if match is None:
+        return False
+    date_part, hour, minute, second = match.groups()
+    return (
+        _is_real_yyyymmdd(date_part)
+        and int(hour) <= 23 and int(minute) <= 59 and int(second or 0) <= 59
+    )
+
+
 def _date_format(value: str) -> str | None:
     for name, pattern in _DATE_FORMATS:
         if pattern.match(value):
             return name
+    if _is_compact_datetime(value):
+        return "compact-datetime"
     return "yyyymmdd" if _is_real_yyyymmdd(value) else None
 
 

{cc_session_tools-3.12.0 → cc_session_tools-3.12.2}/src/cc_session_tools/lib/pdata/service.py

@@ -499,11 +499,13 @@ def date_field_warnings(
     A field is date-like when its name ends `_at` or `_date`, or its description contains the
     word "date"; a name ending `_text` (verbatim text) never is. Numeric fields are skipped
     (an integer `_at` field holds an epoch, not a date string), as are empty and null values.
-    Advisory only: this reads the schema and writes nothing."""
-    columns = {
-        str(c["name"]): c for c in schema_show(project=project, record_group=record_group)
-        if c["source"] == "extension"
-    }
+    Advisory only: this reads the schema and writes nothing, and returns no warnings if the schema
+    cannot be read, so it can never change the outcome of the write it follows."""
+    try:
+        schema = schema_show(project=project, record_group=record_group)
+    except (sqlite3.Error, ValueError):
+        return []  # advisory check; the write it follows has already committed
+    columns = {str(c["name"]): c for c in schema if c["source"] == "extension"}
     warnings: list[str] = []
     for name, value in fields.items():
         column = columns.get(name)

cc_session_tools-3.12.2/src/cc_session_tools/lib/timefmt.py

@@ -0,0 +1,17 @@
+"""The one definition of how CCST renders a UTC time for a human (`yyyy-MM-dd HH:mm UTC`)."""
+from __future__ import annotations
+
+import time
+from datetime import datetime
+
+HUMAN_UTC_FORMAT = "%Y-%m-%d %H:%M UTC"
+
+
+def format_utc(moment: datetime) -> str:
+    """Render a datetime that is already in UTC."""
+    return moment.strftime(HUMAN_UTC_FORMAT)
+
+
+def format_utc_epoch(epoch: float | None = None) -> str:
+    """Render an epoch (seconds) in UTC; the current time when omitted."""
+    return time.strftime(HUMAN_UTC_FORMAT, time.gmtime(epoch))

{cc_session_tools-3.12.0 → cc_session_tools-3.12.2}/src/cc_session_tools/skills/pm-pdata-do-audit-and-prepare-to-migrate/SKILL.md

@@ -57,8 +57,8 @@ ccst pdata readiness-scan --project <name> --path <domain-dir>/ --findings-only
 ```
 
 It is read-only and deterministic. It reports, per CSV, `ragged-rows`, `bad-header`,
-`mixed-date-formats`, `non-iso-dates` (any dotted `yyyy.MM.dd`, compact `yyyyMMdd`, slash or
-long-form value, even when the whole column uses it; advisory, since an 8-digit identifier that
+`mixed-date-formats`, `non-iso-dates` (any dotted `yyyy.MM.dd`, compact `yyyyMMdd` or `yyyyMMddTHHmm`, slash
+or long-form value, even when the whole column uses it; advisory, since an 8-digit identifier that
 is a real date is flagged too), `mixed-separators` (`|` with `;` only), `machine-paths`, `null-strings`,
 `duplicate-rows`, `comment-rows`, `repeated-header`, `no-unique-column`, `bom`, `crlf` and
 `unreadable`, plus row counts and unique columns. Treat findings as leads to verify, not facts to

{cc_session_tools-3.12.0 → cc_session_tools-3.12.2/src/cc_session_tools.egg-info}/PKG-INFO

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

{cc_session_tools-3.12.0 → cc_session_tools-3.12.2}/src/cc_session_tools.egg-info/SOURCES.txt

@@ -52,6 +52,7 @@ src/cc_session_tools/lib/shell_install.py
 src/cc_session_tools/lib/tasklist.py
 src/cc_session_tools/lib/telemetry_store.py
 src/cc_session_tools/lib/text_wrap.py
+src/cc_session_tools/lib/timefmt.py
 src/cc_session_tools/lib/messaging/__init__.py
 src/cc_session_tools/lib/messaging/addressing.py
 src/cc_session_tools/lib/messaging/cursor.py
@@ -249,6 +250,7 @@ tests/test_cli_version.py
 tests/test_confirm_8digit.py
 tests/test_context_overrides.py
 tests/test_context_window_warning.py
+tests/test_date_format_conformance.py
 tests/test_db.py
 tests/test_debug.py
 tests/test_doctor_mutes.py
@@ -295,5 +297,6 @@ tests/test_tasklist.py
 tests/test_telemetry.py
 tests/test_telemetry_store.py
 tests/test_text_wrap.py
+tests/test_timefmt.py
 tests/test_transcript.py
 tests/test_worklog_guard.py

cc_session_tools-3.12.2/tests/test_date_format_conformance.py

@@ -0,0 +1,140 @@
+"""Every date format string under src/ is a convention form or a listed exemption.
+
+The convention: filenames and folder names use `yyyy.MM.dd`; everything else is ISO `yyyy-MM-dd`
+(`yyyy-MM-dd HH:mm` for a time of day, ISO 8601 with `T` and `Z` for machine timestamps).
+A new format string must be added to ALLOWED below with one of the REASONS, or the test fails; an
+entry that no longer matches a format string in src/ must be deleted.
+"""
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+
+SRC = Path(__file__).parent.parent / "src"
+
+REASONS = {
+    "machine-iso": "stored, compared or exchanged timestamp: ISO 8601 with T and Z",
+    "identifier": "session tag or other identifier that contains a date",
+    "backup-stamp": "backup, snapshot or migration stamp in a file name",
+    "human-iso": "printed for a human in the ISO text form",
+    "folder-name": "year or month folder name",
+    "time-only": "time of day with no date",
+    "input-parse": "accepts a user-supplied value, writes nothing",
+    "detection-parse": "recognises a value in data, writes nothing",
+}
+
+_MACHINE = "%Y-%m-%dT%H:%M:%SZ"
+_HUMAN = "%Y-%m-%d %H:%M"
+_BACKUP_UTC = "%Y%m%dT%H%M%SZ"
+
+ALLOWED: dict[tuple[str, str], str] = {
+    ("cc_session_tools/cli/ccd.py", "%Y%m%d"): "identifier",
+    ("cc_session_tools/cli/ccr.py", _HUMAN): "human-iso",
+    ("cc_session_tools/cli/ccs.py", "%Y%m%d"): "identifier",
+    ("cc_session_tools/cli/ccs.py", "%Y-%m-%d"): "input-parse",
+    ("cc_session_tools/cli/ccs.py", _HUMAN): "human-iso",
+    ("cc_session_tools/cli/ccs.py", "%Y-%m-%dT%H:%M"): "input-parse",
+    ("cc_session_tools/cli/ccs.py", "%Y-%m-%dT%H:%M:%S"): "input-parse",
+    ("cc_session_tools/cli/ccsched.py", _MACHINE): "machine-iso",
+    ("cc_session_tools/cli/ccst.py", "%Y%m%d%H%M%S"): "backup-stamp",
+    ("cc_session_tools/cli/ccst.py", _BACKUP_UTC): "backup-stamp",
+    ("cc_session_tools/cli/ccst.py", _HUMAN): "human-iso",
+    ("cc_session_tools/cli/migrate_ccmsg.py", _BACKUP_UTC): "backup-stamp",
+    ("cc_session_tools/cli/migrate_ccsched.py", _BACKUP_UTC): "backup-stamp",
+    ("cc_session_tools/cli/migrate_ccsched.py", _MACHINE): "machine-iso",
+    ("cc_session_tools/cli/migrate_sessions_db.py", _BACKUP_UTC): "backup-stamp",
+    ("cc_session_tools/cli/migrate_telemetry.py", _BACKUP_UTC): "backup-stamp",
+    ("cc_session_tools/lib/install_sync.py", _MACHINE): "machine-iso",
+    ("cc_session_tools/lib/messaging/repository.py", _MACHINE): "machine-iso",
+    ("cc_session_tools/lib/messaging/retention.py", _MACHINE): "machine-iso",
+    ("cc_session_tools/lib/messaging/service.py", _MACHINE): "machine-iso",
+    ("cc_session_tools/lib/messaging/store.py", _BACKUP_UTC): "backup-stamp",
+    ("cc_session_tools/lib/pdata/backup.py", "%Y%m%d-%H%M%S"): "backup-stamp",
+    ("cc_session_tools/lib/pdata/dump.py", _HUMAN): "human-iso",
+    ("cc_session_tools/lib/pdata/init_service.py", _MACHINE): "machine-iso",
+    ("cc_session_tools/lib/pdata/readiness.py", "%Y%m%d"): "detection-parse",
+    ("cc_session_tools/lib/pdata/reorganize.py", "%Y"): "folder-name",
+    ("cc_session_tools/lib/pdata/reorganize.py", "%m"): "folder-name",
+    ("cc_session_tools/lib/proc_lock.py", _MACHINE): "machine-iso",
+    ("cc_session_tools/lib/scheduler/cursor.py", _MACHINE): "machine-iso",
+    ("cc_session_tools/lib/scheduler/registry.py", _MACHINE): "machine-iso",
+    ("cc_session_tools/lib/scheduler/state.py", _MACHINE): "machine-iso",
+    ("cc_session_tools/lib/scheduler/surface.py", _MACHINE): "machine-iso",
+    ("cc_session_tools/lib/sessions_db.py", _MACHINE): "machine-iso",
+    ("cc_session_tools/lib/telemetry_store.py", _MACHINE): "machine-iso",
+    ("cc_session_tools/lib/timefmt.py", "%Y-%m-%d %H:%M UTC"): "human-iso",
+    ("cc_session_tools/skills/clean-hook-sessions/scripts/clean-hook-sessions.py",
+     "%Y%m%d-%H%M%S"): "backup-stamp",
+    ("cc_session_tools/skills/clean-hook-sessions/scripts/clean-hook-sessions.py",
+     _HUMAN): "human-iso",
+    ("cc_session_tools/skills/move-session/scripts/move_session.py",
+     "%Y%m%d-%H%M%S"): "backup-stamp",
+    ("cc_session_tools/skills/move-session/scripts/move_session.py",
+     "%Y-%m-%dT%H:%M:%S.%f"): "machine-iso",
+    ("claude_code_usage/query.py", "%Y"): "human-iso",
+    ("claude_code_usage/query.py", "%Y-%m"): "human-iso",
+    ("claude_code_usage/query.py", "%Y-%m-%d"): "human-iso",
+    ("hooks/bash_security_review.py", "%Y%m%d-%H%M"): "identifier",
+    ("hooks/cache.py", _MACHINE): "machine-iso",
+    ("hooks/cache.py", f"strftime('{_MACHINE}', datetime('now', ?))"): "machine-iso",
+    ("hooks/context_window_warning.py", "%H:%M"): "time-only",
+    ("hooks/session_tag.py", "%Y%m%d"): "identifier",
+    ("hooks/telemetry_query.py", _MACHINE): "machine-iso",
+    ("hooks/telemetry_trim.py", _MACHINE): "machine-iso",
+}
+
+# A year, month, hour, minute, second or fraction directive. Bare %d/%s are logging placeholders.
+_DIRECTIVE = re.compile(r"%[YymHMSfBb]")
+_MAX_FORMAT_LENGTH = 80
+
+
+def _docstring_ids(tree: ast.AST) -> set[int]:
+    ids: set[int] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+            first = node.body[0] if node.body else None
+            if (
+                isinstance(first, ast.Expr)
+                and isinstance(first.value, ast.Constant)
+                and isinstance(first.value.value, str)
+            ):
+                ids.add(id(first.value))
+    return ids
+
+
+def _format_strings() -> set[tuple[str, str]]:
+    found: set[tuple[str, str]] = set()
+    for path in sorted(SRC.rglob("*.py")):
+        if "tests" in path.relative_to(SRC).parts:
+            continue
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+        docstrings = _docstring_ids(tree)
+        for node in ast.walk(tree):
+            if (
+                isinstance(node, ast.Constant)
+                and isinstance(node.value, str)
+                and id(node) not in docstrings
+                and len(node.value) < _MAX_FORMAT_LENGTH
+                and _DIRECTIVE.search(node.value)
+            ):
+                found.add((path.relative_to(SRC).as_posix(), node.value))
+    return found
+
+
+def test_every_allowlist_entry_has_a_known_reason() -> None:
+    assert set(ALLOWED.values()) <= set(REASONS)
+
+
+def test_no_date_format_string_outside_the_allowlist() -> None:
+    unlisted = sorted(_format_strings() - set(ALLOWED))
+    assert not unlisted, (
+        "date format string(s) not in the convention: use yyyy-MM-dd / yyyy-MM-dd HH:mm for "
+        "output and ISO 8601 with T and Z for stored timestamps, or add an ALLOWED entry with a "
+        f"reason from REASONS if it is exempt: {unlisted}"
+    )
+
+
+def test_no_stale_allowlist_entry() -> None:
+    stale = sorted(set(ALLOWED) - _format_strings())
+    assert not stale, f"ALLOWED entries that match no format string in src/: {stale}"

cc_session_tools-3.12.2/tests/test_timefmt.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from cc_session_tools.lib.timefmt import HUMAN_UTC_FORMAT, format_utc, format_utc_epoch
+
+
+def test_format_utc_renders_text_form() -> None:
+    assert format_utc(datetime(2026, 10, 5, 14, 30, 59, tzinfo=timezone.utc)) == "2026-10-05 14:30 UTC"
+
+
+def test_format_utc_epoch_renders_text_form() -> None:
+    assert format_utc_epoch(1_790_000_000) == "2026-09-21 14:13 UTC"
+
+
+def test_format_utc_epoch_defaults_to_now() -> None:
+    import re
+
+    assert re.fullmatch(r"\d{4}-\d{2}-\d{2} \d{2}:\d{2} UTC", format_utc_epoch())
+
+
+def test_format_constant_is_the_documented_form() -> None:
+    assert HUMAN_UTC_FORMAT == "%Y-%m-%d %H:%M UTC"