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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 3.12.2
+Version: 3.14.0
 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.2 → cc_session_tools-3.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "3.12.2"
+version = "3.14.0"
 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.2 → cc_session_tools-3.14.0}/src/cc_session_tools/cli/ccmsg.py

@@ -14,10 +14,12 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from cc_session_tools import __version__
+from cc_session_tools.lib import sessions_db
 from cc_session_tools.lib.messaging import service, store
 from cc_session_tools.lib.messaging.addressing import SessionContext
 from cc_session_tools.lib.messaging.lock import AlreadyClaimedError
 from cc_session_tools.lib.messaging.message import ToKind
+from cc_session_tools.lib.messaging.session_ref import resolve_session_ref
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -30,7 +32,11 @@ def _build_parser() -> argparse.ArgumentParser:
 
     send_p = sub.add_parser("send", help="Compose and route a message.")
     rcpt = send_p.add_argument_group("recipient (exactly one)")
-    rcpt.add_argument("--to-session", metavar="UUID")
+    rcpt.add_argument(
+        "--to-session", metavar="UUID|NAME|PREFIX",
+        help="a session uuid, a session name (YYYYMMDD-<tag>) or a uuid prefix of 8+ hex "
+             "characters; names and prefixes are resolved in the sessions store",
+    )
     rcpt.add_argument("--to-project", metavar="NAME")
     rcpt.add_argument("--to-description", metavar="TEXT")
     send_p.add_argument("--subject", required=True)
@@ -94,6 +100,11 @@ def _resolve_recipient(args: argparse.Namespace) -> tuple[ToKind, str]:
         )
     kind, val = chosen[0]
     assert val is not None  # the filter above guarantees this; narrows for mypy
+    if kind == "session":
+        val = resolve_session_ref(
+            val, find_by_name=sessions_db.find_exact,
+            find_by_prefix=sessions_db.find_by_uuid_prefix,
+        )
     return kind, val
 
 
@@ -189,6 +200,7 @@ def _cmd_read(args: argparse.Namespace) -> int:
         return 1
     print(f"id:       {message.id}")
     print(f"from:     {message.from_session} ({message.from_project})")
+    print(f"from_uuid: {message.from_uuid}")
     print(f"to:       {message.to_kind}={message.to_value}")
     print(f"subject:  {message.subject}")
     print(f"status:   {message.status}")

cc_session_tools-3.14.0/src/cc_session_tools/lib/messaging/session_ref.py

@@ -0,0 +1,59 @@
+"""Resolve a `ccmsg send --to-session` reference to a full session uuid."""
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+
+from cc_session_tools.lib.sessions_db import SessionRow
+
+_UUID = re.compile(r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}")
+_UUID_PREFIX = re.compile(r"[0-9a-f]{8}[0-9a-f-]*")
+_SESSION_NAME = re.compile(r"\d{8}-\S+")
+
+_FORMS = (
+    "a session uuid, a session name (YYYYMMDD-<tag>) or a uuid prefix of at least 8 hex characters"
+)
+
+
+class SessionRefError(ValueError):
+    """The reference cannot be resolved to exactly one session."""
+
+
+def resolve_session_ref(
+    ref: str,
+    *,
+    find_by_name: Callable[[str], list[SessionRow]],
+    find_by_prefix: Callable[[str], list[SessionRow]],
+) -> str:
+    """Return the full lowercase uuid `ref` names.
+
+    A canonical uuid is returned as given: the sessions store only records sessions opened
+    through ccd/ccr, so a valid uuid it has not seen must still be addressable. A session name is
+    tried before a uuid prefix because a date-prefixed name can also read as hex."""
+    ref = ref.strip()
+    if _UUID.fullmatch(ref.lower()):
+        return ref.lower()
+
+    is_name = _SESSION_NAME.fullmatch(ref) is not None
+    is_prefix = _UUID_PREFIX.fullmatch(ref.lower()) is not None
+    if not is_name and not is_prefix:
+        raise SessionRefError(f"{ref!r} is not {_FORMS}")
+
+    rows = find_by_name(ref) if is_name else []
+    if not rows and is_prefix:
+        rows = find_by_prefix(ref.lower())
+    if not rows:
+        raise SessionRefError(
+            f"no session matches {ref!r}; the sessions store only knows sessions opened with "
+            "ccd or ccr, so pass the full uuid for any other session"
+        )
+    uuids = {row.uuid for row in rows}
+    if len(uuids) > 1:
+        lines = "\n".join(
+            f"  {row.uuid[:8]}  {row.basename}  {row.project_dir}"
+            for row in sorted(rows, key=lambda r: (r.uuid, str(r.project_dir)))
+        )
+        raise SessionRefError(
+            f"{ref!r} matches {len(uuids)} sessions; retry with a full uuid:\n{lines}"
+        )
+    return next(iter(uuids))

{cc_session_tools-3.12.2 → cc_session_tools-3.14.0}/src/cc_session_tools/lib/pdata/init_paths.py

@@ -10,7 +10,7 @@ from collections.abc import Iterator
 from contextlib import contextmanager
 from pathlib import Path
 
-from cc_session_tools.lib.pdata import backup, store
+from cc_session_tools.lib.pdata import backup, project_claude_md, store
 
 PROJECTS_ROOT_ENV = "CCST_PROJECTS_ROOT"
 # Permanent tool state, not a draft - a project's pdata classification/migration record. Named
@@ -77,13 +77,17 @@ def project_root_exists_already(project: str, *, rehearse: Path | None) -> bool:
     return (default_projects_root() / project).exists()
 
 
-def scaffold_new_project_dirs(project_root: Path) -> None:
-    """Create NEW_PROJECT_SCAFFOLD_DIRNAMES under project_root. Idempotent (mkdir(exist_ok=True)
-    per folder) - safe to call even if some or all already exist, though callers should gate
+def scaffold_new_project(project_root: Path, project: str) -> None:
+    """Create NEW_PROJECT_SCAFFOLD_DIRNAMES under project_root and, if absent, its starting
+    CLAUDE.md. Idempotent (mkdir(exist_ok=True) per folder; an existing CLAUDE.md is never
+    overwritten) - safe to call even if some or all already exist, though callers should gate
     this to a genuinely new project (see project_root_exists_already) so an existing project
-    that deliberately doesn't use these folders is never given them back after deletion."""
+    that deliberately doesn't use these folders or has its own CLAUDE.md is never changed."""
     for name in NEW_PROJECT_SCAFFOLD_DIRNAMES:
         (project_root / name).mkdir(parents=True, exist_ok=True)
+    claude_md = project_root / "CLAUDE.md"
+    if not claude_md.exists():
+        claude_md.write_bytes(project_claude_md.seed_text(project).encode("utf-8"))
 
 
 def resolve_project_root(project: str, *, rehearse: Path | None) -> Path:

{cc_session_tools-3.12.2 → cc_session_tools-3.14.0}/src/cc_session_tools/lib/pdata/init_service.py

@@ -48,7 +48,7 @@ def dry_run(*, project: str, rehearse: Path | None = None) -> DryRunResult:
     is_new_project = not init_paths.project_root_exists_already(project, rehearse=rehearse)
     project_root = init_paths.resolve_project_root(project, rehearse=rehearse)
     if is_new_project:
-        init_paths.scaffold_new_project_dirs(project_root)
+        init_paths.scaffold_new_project(project_root, project)
     proposal_path = init_paths.resolve_proposal_path(project_root)
     with init_paths.project_db_dir_override(rehearse):
         # Checked before anything below opens/creates this project's .db (repository.connect()'s

cc_session_tools-3.14.0/src/cc_session_tools/lib/pdata/project_claude_md.py

@@ -0,0 +1,29 @@
+"""The starting CLAUDE.md `ccst pdata init` writes into a genuinely new project."""
+from __future__ import annotations
+
+_SECTIONS = """\
+## Date format
+
+- Filenames and folder names: `yyyy.MM.dd` (with time `yyyy.MM.dd-HHmm`, partial `yyyy.MM`).
+- Formal external letters: long form (for example "5 October 2026") in the header only.
+- Everything else: `yyyy-MM-dd` - prose, WORKLOG, CSV/TSV and pdata date fields, frontmatter, \
+JSON/YAML, commit text. Time of day is `yyyy-MM-dd HH:mm`; machine timestamps stay ISO 8601 \
+(`2026-10-05T14:30:00Z`).
+- Never mix formats inside one column or field.
+- Exempt: identifiers containing a date (session tags, branch names, backup stamps), \
+tool-generated names, existing filenames, and evidence or any document the project did not write.
+
+## Line endings
+
+- Standard is LF, not CRLF, for all text files (CSV, Markdown, scripts, JSON).
+- Python's `csv.writer` emits CRLF by default, even with `open(..., newline='')`. Always pass \
+`lineterminator='\\n'` to `csv.writer` / `csv.DictWriter`.
+- Other Python defaults can also write the wrong ending: open text files with `newline='\\n'` \
+when writing, and check any tool that rewrites a file.
+- When adding or rewriting a text file, check it has no `\\r` (`grep -c $'\\r' <file>` should \
+print 0).
+"""
+
+
+def seed_text(project: str) -> str:
+    return f"# {project}\n\n{_SECTIONS}"

{cc_session_tools-3.12.2 → cc_session_tools-3.14.0}/src/cc_session_tools/lib/sessions_db.py

@@ -626,6 +626,24 @@ def find_exact(basename: str, *, path: Path | None = None) -> list[SessionRow]:
         conn.close()
 
 
+def find_by_uuid_prefix(prefix: str, *, path: Path | None = None) -> list[SessionRow]:
+    """Every row whose uuid starts with `prefix`. `prefix` must hold only hex digits and
+    dashes (the caller validates), so it contains no LIKE wildcard."""
+    try:
+        conn = connect(path=path, readonly=True)
+    except sqlite3.OperationalError:
+        return []
+    try:
+        rows = conn.execute(
+            "SELECT project_dir, basename, uuid, start_date, last_opened, last_active "
+            "FROM sessions WHERE uuid LIKE ?",
+            (prefix + "%",),
+        ).fetchall()
+        return [_row_to_session(r) for r in rows]
+    finally:
+        conn.close()
+
+
 # ---------------------------------------------------------------------------
 # sessions_migration_ambiguous
 # ---------------------------------------------------------------------------

{cc_session_tools-3.12.2 → cc_session_tools-3.14.0}/src/cc_session_tools/skills/send-session-message/SKILL.md

@@ -21,7 +21,15 @@ Do not send for things the user can see in this session, or to talk to yourself.
 Decide which of three addressing modes fits, and **confirm with the user when it
 is ambiguous**:
 
-1. `--to-session <uuid>` - a specific known session (you have its uuid).
+1. `--to-session <ref>` - a specific known session. `<ref>` is a full uuid, a session name
+   (the `cc-sessions/` directory name, `YYYYMMDD-<tag>`) or a uuid prefix of at least 8 hex
+   characters, for example the leading characters shown in a received message's sender field. A
+   name or prefix is resolved in the sessions store and the message is stored for the full uuid.
+   It exits 2 and stores nothing when nothing matches or when it matches several sessions (a
+   forked session): the error lists the candidates, so retry with a full uuid. The store knows
+   only sessions opened with `ccd`/`ccr`; for any other session pass the full uuid. `ccmsg read`
+   prints the sender's full uuid on its `from_uuid:` line, so you can reply to a session you know
+   only from a message.
 2. `--to-project <name>` - any session in a named project.
 3. `--to-description "<text>"` - "whoever is working on X". Surfaced to candidate
    sessions; one claims it.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 3.12.2
+Version: 3.14.0
 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.2 → cc_session_tools-3.14.0}/src/cc_session_tools.egg-info/SOURCES.txt

@@ -62,6 +62,7 @@ src/cc_session_tools/lib/messaging/move_safety.py
 src/cc_session_tools/lib/messaging/repository.py
 src/cc_session_tools/lib/messaging/retention.py
 src/cc_session_tools/lib/messaging/service.py
+src/cc_session_tools/lib/messaging/session_ref.py
 src/cc_session_tools/lib/messaging/store.py
 src/cc_session_tools/lib/pdata/__init__.py
 src/cc_session_tools/lib/pdata/backup.py
@@ -74,6 +75,7 @@ src/cc_session_tools/lib/pdata/init_paths.py
 src/cc_session_tools/lib/pdata/init_service.py
 src/cc_session_tools/lib/pdata/manifest.py
 src/cc_session_tools/lib/pdata/naming.py
+src/cc_session_tools/lib/pdata/project_claude_md.py
 src/cc_session_tools/lib/pdata/readiness.py
 src/cc_session_tools/lib/pdata/rehydrate.py
 src/cc_session_tools/lib/pdata/rename_group.py