cc-session-tools 3.7.0__tar.gz → 3.8.0__tar.gz

{cc_session_tools-3.7.0/src/cc_session_tools.egg-info → cc_session_tools-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 3.7.0
+Version: 3.8.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
@@ -928,6 +928,25 @@ ccst context-override off      # re-enable the warnings
 ccst context-override status   # report the current state
 ```
 
+### `ccst pdata readiness-scan`
+
+A read-only scan of a project's CSV files for the mechanical blockers to a `ccst pdata init`
+migration, used by the `pm-pdata-do-audit-and-prepare-to-migrate` skill and useful on its own:
+
+```sh
+ccst pdata readiness-scan --project myproject                 # compact Markdown report
+ccst pdata readiness-scan --project myproject --format json   # machine-readable
+ccst pdata readiness-scan --project myproject --path notes/ --findings-only   # one folder's findings
+```
+
+It reports ragged rows, empty/duplicate headers, mixed date formats, mixed `|`/`;` separators,
+machine-specific paths, null-like placeholder strings, duplicate rows, comment rows, repeated
+header rows, byte-order marks, CRLF line endings and unreadable files, plus a per-file inventory
+and the columns that are unique on every row. Findings carry counts and row numbers, never cell
+text, and a unique column is a fact rather than a recommended key. It exits 0 whenever the scan
+ran (findings are not failures), and 2 when the project directory does not exist. It scans exactly
+the CSVs `ccst pdata init` would classify.
+
 ### `ccst skills install`
 
 > You normally don't need this: `ccst install-everything --apply` runs it, and `ccst` runs that

{cc_session_tools-3.7.0 → cc_session_tools-3.8.0}/README.md

@@ -871,6 +871,25 @@ ccst context-override off      # re-enable the warnings
 ccst context-override status   # report the current state
 ```
 
+### `ccst pdata readiness-scan`
+
+A read-only scan of a project's CSV files for the mechanical blockers to a `ccst pdata init`
+migration, used by the `pm-pdata-do-audit-and-prepare-to-migrate` skill and useful on its own:
+
+```sh
+ccst pdata readiness-scan --project myproject                 # compact Markdown report
+ccst pdata readiness-scan --project myproject --format json   # machine-readable
+ccst pdata readiness-scan --project myproject --path notes/ --findings-only   # one folder's findings
+```
+
+It reports ragged rows, empty/duplicate headers, mixed date formats, mixed `|`/`;` separators,
+machine-specific paths, null-like placeholder strings, duplicate rows, comment rows, repeated
+header rows, byte-order marks, CRLF line endings and unreadable files, plus a per-file inventory
+and the columns that are unique on every row. Findings carry counts and row numbers, never cell
+text, and a unique column is a fact rather than a recommended key. It exits 0 whenever the scan
+ran (findings are not failures), and 2 when the project directory does not exist. It scans exactly
+the CSVs `ccst pdata init` would classify.
+
 ### `ccst skills install`
 
 > You normally don't need this: `ccst install-everything --apply` runs it, and `ccst` runs that

{cc_session_tools-3.7.0 → cc_session_tools-3.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "3.7.0"
+version = "3.8.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.7.0 → cc_session_tools-3.8.0}/src/cc_session_tools/cli/ccst.py

@@ -112,6 +112,7 @@ from cc_session_tools.hooks_install import (
 )
 from cc_session_tools.lib import machine_identity
 from cc_session_tools.lib.hook_registry import HOOK_DESCRIPTIONS, HOOK_VERBS
+from cc_session_tools.lib.text_wrap import wrap_block
 
 if TYPE_CHECKING:
     # Type-only, so the handler's own lazy `from ... import sync_check` (this file's convention:
@@ -538,30 +539,45 @@ def _bundle_inventory(bundle: dict[str, Any]) -> list[tuple[str, str, str | None
     return out
 
 
-def _print_hooks_install_table(
+def _format_hooks_install_records(
     inventory: list[tuple[str, str, str | None, str]],
     added_keys: set[tuple[str, str | None, str]],
-) -> None:
-    """Print a Hook | Status | Event | Description table to stdout."""
-    headers = ("Hook", "Status", "Event", "Description")
-    if not inventory:
-        return
+) -> str:
+    """One record per hook: a `name  status` header, an indented `Events:` line, then the
+    indented, terminal-width-wrapped description. Records are separated by a blank line.
 
-    rows: list[tuple[str, str, str, str]] = []
+    A hook registered for several events is one record; when only some of its registrations
+    would be added, those events carry a `(new)` marker. Order follows the inventory (sorted by
+    hook name).
+    """
+    by_hook: dict[str, list[tuple[bool, str]]] = {}
     for name, event, matcher, cmd in inventory:
-        status = "install" if (event, matcher, cmd) in added_keys else "already-installed"
         event_label = f"{event}[{matcher}]" if matcher else event
+        by_hook.setdefault(name, []).append(((event, matcher, cmd) in added_keys, event_label))
+
+    records: list[str] = []
+    for name, registrations in by_hook.items():
+        any_new = any(is_new for is_new, _ in registrations)
+        mixed = any_new and not all(is_new for is_new, _ in registrations)
+        status = "install" if any_new else "already-installed"
+        events = ", ".join(
+            f"{label} (new)" if mixed and is_new else label for is_new, label in registrations
+        )
+        lines = [f"{name}  {status}", wrap_block(f"Events: {events}")]
         description = HOOK_DESCRIPTIONS.get(name, "")
-        rows.append((name, status, event_label, description))
+        if description:
+            lines.append(wrap_block(description))
+        records.append("\n".join(lines))
+    return "\n\n".join(records)
 
-    widths = [
-        max([len(headers[i])] + [len(r[i]) for r in rows]) for i in range(4)
-    ]
-    fmt = f"{{:<{widths[0]}}}  {{:<{widths[1]}}}  {{:<{widths[2]}}}  {{:<{widths[3]}}}"
-    print(fmt.format(*headers))
-    print(fmt.format(*("-" * w for w in widths)))
-    for row in rows:
-        print(fmt.format(*row))
+
+def _print_hooks_install_table(
+    inventory: list[tuple[str, str, str | None, str]],
+    added_keys: set[tuple[str, str | None, str]],
+) -> None:
+    """Print the per-hook install records to stdout."""
+    if inventory:
+        print(_format_hooks_install_records(inventory, added_keys))
 
 
 def _list_bundle_hook_names(bundle: dict[str, Any]) -> list[str]:
@@ -1842,6 +1858,28 @@ def _cmd_pdata_resolve(args: argparse.Namespace) -> int:
     return 1 if outstanding else 0
 
 
+def _cmd_pdata_readiness_scan(args: argparse.Namespace) -> int:
+    from cc_session_tools.lib.pdata import readiness, store
+
+    try:
+        root = store.project_root(args.project)
+    except ValueError as exc:
+        print(f"ccst pdata readiness-scan: {exc}", file=sys.stderr)
+        return 2
+    if not root.is_dir():
+        print(
+            f"ccst pdata readiness-scan: project directory does not exist: {root}",
+            file=sys.stderr,
+        )
+        return 2
+    report = readiness.scan_project(root, path_prefix=args.path)
+    if args.format == "json":
+        print(readiness.format_json(report))
+    else:
+        print(readiness.format_markdown(report, findings_only=args.findings_only))
+    return 0
+
+
 def _cmd_pdata_sync_check(args: argparse.Namespace) -> int:
     """The spec's "Hourly `ccsched` job" trigger: per project, rehydrate-check and - only if no
     rehydrate happened - dump-check. The whole decision lives in `pdata.sync_check` (shared with
@@ -3240,6 +3278,24 @@ def _build_parser() -> argparse.ArgumentParser:
              "the default one-line summary (--project always prints full detail)",
     )
 
+    pdata_readiness_parser = pdata_sub.add_parser(
+        "readiness-scan",
+        help="Scan a project's CSVs for pdata-migration blockers (read-only)",
+    )
+    pdata_readiness_parser.add_argument("--project", metavar="NAME", required=True)
+    pdata_readiness_parser.add_argument(
+        "--format", choices=("markdown", "json"), default="markdown",
+        help="Output format (default: markdown)",
+    )
+    pdata_readiness_parser.add_argument(
+        "--path", metavar="PREFIX", default=None,
+        help="Only scan CSVs whose project-relative path starts with PREFIX",
+    )
+    pdata_readiness_parser.add_argument(
+        "--findings-only", action="store_true",
+        help="Omit the per-file inventory from the Markdown report",
+    )
+
     pdata_dump_parser = pdata_sub.add_parser(
         "dump", help="Publish the current local DB state to .pdata-db-dump/latest.sql"
     )
@@ -3643,6 +3699,8 @@ def main() -> None:
             sys.exit(_cmd_pdata_reconcile_session_output(args))
         if args.verb == "verify":
             sys.exit(_cmd_pdata_verify(args))
+        if args.verb == "readiness-scan":
+            sys.exit(_cmd_pdata_readiness_scan(args))
         if args.verb == "dump":
             sys.exit(_cmd_pdata_dump(args))
         if args.verb == "rehydrate":

{cc_session_tools-3.7.0 → cc_session_tools-3.8.0}/src/cc_session_tools/lib/doctor.py

@@ -14,7 +14,6 @@ import os
 import shutil
 import sqlite3
 import subprocess
-import textwrap
 import time
 from dataclasses import dataclass
 from enum import Enum
@@ -29,6 +28,7 @@ from cc_session_tools.lib.pdata.init_paths import (
     MIGRATED_ARCHIVE_DIRNAME,
     MIGRATED_MANIFEST_FILENAME,
 )
+from cc_session_tools.lib.text_wrap import wrap_block
 
 if TYPE_CHECKING:
     from cc_session_tools.lib.install_sync import FailedAttempt
@@ -1224,12 +1224,11 @@ def _wrap_reason(reason: str, *, indent: str = "    ") -> str:
     embedded paths and remediation commands); printed on a single line they
     hard-wrap at the terminal edge with no continuation indent, making a
     wrapped reason indistinguishable from a new, unrelated result. Wrapping
-    to the real terminal width — falling back to 80 columns for non-tty
+    to the real terminal width - falling back to 80 columns for non-tty
     output (piped, redirected, or the scheduled drift-monitor job whose
-    stdout is forwarded to Telegram) — and indenting every line fixes that.
+    stdout is forwarded to Telegram) - and indenting every line fixes that.
     """
-    width = shutil.get_terminal_size(fallback=(80, 24)).columns
-    return textwrap.fill(reason, width=width, initial_indent=indent, subsequent_indent=indent)
+    return wrap_block(reason, indent=indent)
 
 
 def format_results(results: list[CheckResult], *, show_all: bool = False) -> str:
@@ -1265,7 +1264,13 @@ def format_results(results: list[CheckResult], *, show_all: bool = False) -> str
         lines.append(f"All {len(results)} checks OK.")
     has_issues = any(r.status in (Status.WARN, Status.FAIL) for r in results)
     if has_issues:
-        lines.append("\nTip: run `ccst install-everything --apply` to sync skills, hooks, shell, and CLAUDE.md")
+        lines.append("")
+        lines.append(
+            wrap_block(
+                "Tip: run `ccst install-everything --apply` to sync skills, hooks, shell, and CLAUDE.md",
+                indent="",
+            )
+        )
     if not show_all:
         lines.append("\nTo see full doctor output use --all argument")
     return "\n".join(lines)

cc_session_tools-3.8.0/src/cc_session_tools/lib/pdata/readiness.py

@@ -0,0 +1,319 @@
+"""Deterministic pdata-readiness scan of a project's CSV files (`ccst pdata readiness-scan`).
+
+Reports the mechanical blockers a migration audit would otherwise find by reading: ragged rows,
+mixed date formats, mixed separators, machine-specific paths, fake nulls, duplicates, BOM/CRLF and
+unreadable files, plus a per-file inventory and unique-column facts. Read-only: the scan never
+writes. Findings carry counts and 1-based data-record numbers (header excluded), never cell text;
+`unreadable` reasons are a fixed vocabulary, so file content cannot reach a report.
+"""
+from __future__ import annotations
+
+import csv
+import io
+import json
+import os
+import re
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from cc_session_tools.lib.pdata.init_paths import EXCLUDED_DIR_NAMES
+
+FINDING_KINDS: tuple[str, ...] = (
+    "ragged-rows", "machine-paths", "null-strings", "duplicate-rows", "comment-rows",
+    "repeated-header", "mixed-date-formats", "mixed-separators", "bad-header",
+    "no-unique-column", "unreadable", "bom", "crlf",
+)
+
+MAX_EXAMPLE_ROWS = 3
+FREE_TEXT_MEAN_LENGTH = 64
+NULL_STRINGS = frozenset({"NO DATA", "N/A", "NA", "NULL", "NONE", "TBD", "UNKNOWN", "-", "--", "?"})
+_MACHINE_PATH = re.compile(r"/Users/[^/\s]+|/home/[^/\s]+|/mnt/[a-z]/|[A-Za-z]:\\Users\\")
+_DATE_FORMATS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("iso-datetime", re.compile(r"^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}")),
+    ("iso-date", re.compile(r"^\d{4}-\d{2}-\d{2}$")),
+    ("slash", re.compile(r"^\d{1,2}/\d{1,2}/\d{2,4}$")),
+    ("d-month-yyyy", re.compile(r"^\d{1,2} [A-Za-z]{3,9} \d{4}$")),
+    ("month-d-yyyy", re.compile(r"^[A-Za-z]{3,9} \d{1,2},? \d{4}$")),
+)
+_BOM = b"\xef\xbb\xbf"
+
+
+@dataclass(frozen=True)
+class Finding:
+    kind: str
+    file: str
+    column: str | None = None
+    count: int | None = None
+    rows: tuple[int, ...] = ()
+    detail: tuple[tuple[str, int | str], ...] = ()
+
+
+@dataclass(frozen=True)
+class UniqueColumn:
+    name: str
+    labels: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class FileReport:
+    path: str
+    rows: int
+    columns: int
+    header: tuple[str, ...]
+    unique_columns: tuple[UniqueColumn, ...]
+
+
+@dataclass(frozen=True)
+class ReadinessReport:
+    files: tuple[FileReport, ...]
+    findings: tuple[Finding, ...]
+    not_scanned: dict[str, int]
+
+
+class _Unreadable(Exception):
+    def __init__(self, reason: str) -> None:
+        super().__init__(reason)
+        self.reason = reason
+
+
+def _is_real_yyyymmdd(value: str) -> bool:
+    if not re.fullmatch(r"\d{8}", value):
+        return False
+    try:
+        parsed = datetime.strptime(value, "%Y%m%d")
+    except ValueError:
+        return False
+    return 1900 <= parsed.year <= 2100
+
+
+def _date_format(value: str) -> str | None:
+    for name, pattern in _DATE_FORMATS:
+        if pattern.match(value):
+            return name
+    return "yyyymmdd" if _is_real_yyyymmdd(value) else None
+
+
+def _walk(root: Path) -> list[Path]:
+    """Every file under root outside EXCLUDED_DIR_NAMES, without following directory symlinks -
+    the same exclusion set `ccst pdata init`'s classifier uses, so coverage matches migration."""
+    found: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+        dirnames[:] = sorted(d for d in dirnames if d not in EXCLUDED_DIR_NAMES)
+        found.extend(Path(dirpath) / name for name in sorted(filenames))
+    return found
+
+
+def _parse(raw: bytes) -> tuple[list[list[str]], bool, bool]:
+    if not raw:
+        raise _Unreadable("empty-file")
+    try:
+        text = raw.decode("utf-8-sig")
+    except UnicodeDecodeError:
+        raise _Unreadable("not-utf8") from None
+    if not text.strip():
+        raise _Unreadable("empty-file")
+    try:
+        records = list(csv.reader(io.StringIO(text, newline=""), strict=True))
+    except csv.Error as exc:
+        raise _Unreadable(
+            "field-too-large" if "field larger" in str(exc) else "csv-parse-error"
+        ) from None
+    return records, raw.startswith(_BOM), b"\r\n" in raw
+
+
+def _scan_file(rel: str, raw: bytes) -> tuple[FileReport | None, list[Finding]]:
+    try:
+        records, has_bom, has_crlf = _parse(raw)
+    except _Unreadable as exc:
+        return None, [Finding("unreadable", rel, detail=(("reason", exc.reason),))]
+
+    findings: list[Finding] = []
+    if has_bom:
+        findings.append(Finding("bom", rel))
+    if has_crlf:
+        findings.append(Finding("crlf", rel))
+
+    header = records[0]
+    ncols = len(header)
+    if any(not h.strip() for h in header) or len(set(header)) != ncols:
+        findings.append(Finding("bad-header", rel))
+
+    data = [r for r in records[1:] if r]
+    nonempty = [0] * ncols
+    lengths = [0] * ncols
+    distinct: list[set[str]] = [set() for _ in range(ncols)]
+    all_int = [True] * ncols
+    dates: list[dict[str, int]] = [{} for _ in range(ncols)]
+    seps: list[dict[str, int]] = [{} for _ in range(ncols)]
+    nulls: list[dict[str, int]] = [{} for _ in range(ncols)]
+    null_rows: list[list[int]] = [[] for _ in range(ncols)]
+    path_rows: list[list[int]] = [[] for _ in range(ncols)]
+    ragged: list[int] = []
+    dup_rows: list[int] = []
+    comment_rows: list[int] = []
+    header_rows: list[int] = []
+    seen_rows: set[tuple[str, ...]] = set()
+
+    for number, row in enumerate(data, start=1):
+        if row == header:
+            header_rows.append(number)
+        if row[0].startswith("#"):
+            comment_rows.append(number)
+        if len(row) != ncols:
+            ragged.append(number)
+        key = tuple(row)
+        if key in seen_rows:
+            dup_rows.append(number)
+        seen_rows.add(key)
+        for i, value in enumerate(row[:ncols]):
+            if not value.strip():
+                continue
+            nonempty[i] += 1
+            lengths[i] += len(value)
+            distinct[i].add(value)
+            if not re.fullmatch(r"-?\d+", value.strip()):
+                all_int[i] = False
+            fmt = _date_format(value.strip())
+            if fmt:
+                dates[i][fmt] = dates[i].get(fmt, 0) + 1
+            for sep in ("|", ";"):
+                if sep in value:
+                    seps[i][sep] = seps[i].get(sep, 0) + 1
+            token = value.strip().upper()
+            if token in NULL_STRINGS:
+                nulls[i][token] = nulls[i].get(token, 0) + 1
+                null_rows[i].append(number)
+            if _MACHINE_PATH.search(value):
+                path_rows[i].append(number)
+
+    def row_finding(kind: str, rows: list[int], column: str | None = None,
+                    detail: tuple[tuple[str, int | str], ...] = ()) -> Finding:
+        return Finding(kind, rel, column, len(rows), tuple(rows[:MAX_EXAMPLE_ROWS]), detail)
+
+    if ragged:
+        findings.append(row_finding("ragged-rows", ragged))
+    if dup_rows:
+        findings.append(row_finding("duplicate-rows", dup_rows))
+    if comment_rows:
+        findings.append(row_finding("comment-rows", comment_rows))
+    if header_rows:
+        findings.append(row_finding("repeated-header", header_rows))
+    for i, name in enumerate(header):
+        if len(dates[i]) >= 2:
+            findings.append(Finding("mixed-date-formats", rel, name,
+                                    detail=tuple(sorted(dates[i].items()))))
+        if len(seps[i]) == 2:
+            findings.append(Finding("mixed-separators", rel, name,
+                                    detail=tuple(sorted(seps[i].items()))))
+        if path_rows[i]:
+            findings.append(row_finding("machine-paths", path_rows[i], name))
+        if null_rows[i]:
+            findings.append(row_finding("null-strings", null_rows[i], name,
+                                        tuple(sorted(nulls[i].items()))))
+
+    unique: list[UniqueColumn] = []
+    if len(data) >= 2:
+        for i, name in enumerate(header):
+            if nonempty[i] == len(data) and len(distinct[i]) == len(data):
+                labels: list[str] = []
+                if all_int[i]:
+                    labels.append("integer-like")
+                if lengths[i] / len(data) > FREE_TEXT_MEAN_LENGTH:
+                    labels.append("free-text")
+                unique.append(UniqueColumn(name, tuple(labels)))
+        if not unique:
+            findings.append(Finding("no-unique-column", rel))
+
+    return FileReport(rel, len(data), ncols, tuple(header), tuple(unique)), findings
+
+
+def scan_project(root: Path, *, path_prefix: str | None = None) -> ReadinessReport:
+    files: list[FileReport] = []
+    findings: list[Finding] = []
+    not_scanned = {"json": 0, "markdown": 0, "other": 0}
+    for abs_path in _walk(root):
+        rel = abs_path.relative_to(root).as_posix()
+        if path_prefix and not rel.startswith(path_prefix):
+            continue
+        suffix = abs_path.suffix.lower()
+        if suffix != ".csv":
+            bucket = {".json": "json", ".md": "markdown", ".markdown": "markdown"}.get(suffix, "other")
+            not_scanned[bucket] += 1
+            continue
+        report, file_findings = _scan_file(rel, abs_path.read_bytes())
+        if report is not None:
+            files.append(report)
+        findings.extend(file_findings)
+    findings.sort(key=lambda f: (f.file, FINDING_KINDS.index(f.kind), f.column or ""))
+    return ReadinessReport(tuple(files), tuple(findings), not_scanned)
+
+
+def _finding_line(f: Finding) -> str:
+    parts = [f"- {f.kind}: {f.file}"]
+    if f.column is not None:
+        parts.append(f"column {f.column!r}")
+    if f.count is not None:
+        parts.append(f"count={f.count}")
+    if f.rows:
+        parts.append("rows=" + ",".join(str(r) for r in f.rows))
+    if f.detail:
+        parts.append(", ".join(f"{k}={v}" for k, v in f.detail))
+    return "  ".join(parts)
+
+
+def format_markdown(report: ReadinessReport, *, findings_only: bool = False) -> str:
+    ns = report.not_scanned
+    lines = [
+        "# pdata readiness scan",
+        "",
+        "Row numbers are 1-based data records (header excluded), not line numbers: a quoted "
+        "multiline cell makes them differ.",
+        f"Scanned {len(report.files)} CSV file(s); not scanned: {ns['json']} JSON, "
+        f"{ns['markdown']} Markdown, {ns['other']} other.",
+    ]
+    if not report.files and not any(f.kind == "unreadable" for f in report.findings):
+        lines += ["", "No CSV files found."]
+    lines += ["", "## Findings"]
+    lines += [_finding_line(f) for f in report.findings] or ["No findings."]
+    if not findings_only and report.files:
+        lines += [
+            "",
+            "## Inventory",
+            "A unique column is a fact, not a recommended key: it is not a stable key until a "
+            "human has confirmed its values are not re-numbered per session or machine.",
+        ]
+        for f in report.files:
+            unique = ", ".join(
+                u.name + (f" ({'/'.join(u.labels)})" if u.labels else "") for u in f.unique_columns
+            )
+            lines.append(
+                f"- {f.path}: {f.rows} rows, {f.columns} columns"
+                + (f"; unique: {unique}" if unique else "")
+            )
+    return "\n".join(lines)
+
+
+def format_json(report: ReadinessReport) -> str:
+    return json.dumps(
+        {
+            "files": [
+                {
+                    "path": f.path, "rows": f.rows, "columns": f.columns,
+                    "header": list(f.header),
+                    "unique_columns": [{"name": u.name, "labels": list(u.labels)}
+                                       for u in f.unique_columns],
+                }
+                for f in report.files
+            ],
+            "findings": [
+                {
+                    "kind": f.kind, "file": f.file, "column": f.column, "count": f.count,
+                    "rows": list(f.rows), "detail": dict(f.detail),
+                }
+                for f in report.findings
+            ],
+            "not_scanned": report.not_scanned,
+        },
+        indent=2,
+    )

cc_session_tools-3.8.0/src/cc_session_tools/lib/text_wrap.py

@@ -0,0 +1,35 @@
+"""Terminal-width word wrapping shared by `ccst doctor` and the hooks install output."""
+from __future__ import annotations
+
+import shutil
+import textwrap
+
+FALLBACK_WIDTH = 80
+MIN_WIDTH = 40
+
+
+def effective_width() -> int:
+    """Width to wrap to: the detected terminal width, never below MIN_WIDTH.
+
+    `shutil.get_terminal_size` reads `COLUMNS`, then the real terminal via the process's stdout
+    file descriptor (so an in-process `redirect_stdout` capture still sees the real terminal),
+    and falls back to FALLBACK_WIDTH when neither is available. It is called through the module
+    attribute so tests can patch it.
+    """
+    return max(shutil.get_terminal_size(fallback=(FALLBACK_WIDTH, 24)).columns, MIN_WIDTH)
+
+
+def wrap_block(text: str, *, indent: str = "    ") -> str:
+    """Word-wrap `text` to the effective width, indenting every line.
+
+    Words are never split: a path, hyphenated name or backticked command that has no whitespace
+    stays on one line, and a single token longer than the width overflows rather than breaking.
+    """
+    return textwrap.fill(
+        text,
+        width=effective_width(),
+        initial_indent=indent,
+        subsequent_indent=indent,
+        break_long_words=False,
+        break_on_hyphens=False,
+    )