cc-session-tools 2.7.2__tar.gz → 2.8.1__tar.gz

{cc_session_tools-2.7.2/src/cc_session_tools.egg-info → cc_session_tools-2.8.1}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "2.7.2"
+version = "2.8.1"
 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" }
@@ -62,11 +62,11 @@ where = ["src"]
 # only filters within the file's *own* discovered package, and a wrongly
 # auto-discovered "cc_session_tools.skills.<name>.tests" package was never
 # covered by an exclude-package-data entry keyed just "cc_session_tools").
-exclude = ["cc_session_tools.skills", "cc_session_tools.skills.*", "cc_session_tools.config", "cc_session_tools.config.*"]
+exclude = ["cc_session_tools.skills", "cc_session_tools.skills.*", "cc_session_tools.config", "cc_session_tools.config.*", "cc_session_tools.prompts", "cc_session_tools.prompts.*"]
 
 [tool.setuptools.package-data]
 claude_code_usage = ["data/*.json"]
-cc_session_tools = ["skills/**/*", "config/*"]
+cc_session_tools = ["skills/**/*", "config/*", "prompts/**/*"]
 
 [tool.setuptools.exclude-package-data]
 cc_session_tools = ["**/tests/*", "**/__pycache__/*"]

{cc_session_tools-2.7.2 → cc_session_tools-2.8.1}/src/cc_session_tools/cli/ccst.py

@@ -122,6 +122,40 @@ def _discover_bundle() -> Path:
     )
 
 
+def _discover_prompts_dir() -> Path:
+    """Return the bundled prompts/ directory (pdata-migration follow-up prompts).
+
+    prompts/ is packaged inside cc_session_tools the same way skills/ and config/ are (see
+    _discover_source_dir) - src/cc_session_tools/cli/ccst.py -> ../prompts. No install-location
+    fallback, same reasoning as the other two: a fallback here would just mask a broken install.
+    """
+    candidate = Path(__file__).resolve().parent.parent / "prompts"
+    if candidate.is_dir():
+        return candidate
+    raise FileNotFoundError(
+        "Cannot locate bundled prompts/ directory. Run from the source tree or reinstall ccst."
+    )
+
+
+def _print_migration_prompt_reminders(*labeled_filenames: tuple[str, str]) -> None:
+    """Print one "<label>: <path>" reminder line per (label, filename) pair, for the bundled
+    prompts/ directory.
+
+    Best-effort, deliberately swallowing a missing prompts/ directory: these reminders are a
+    nicety layered on top of an otherwise-already-completed classification or migration, not
+    the operation itself — a broken/partial install must never turn a successful --write (rows
+    already written, files already cut over) or dry-run (proposal already written) into a
+    reported failure just because this follow-up reminder couldn't be printed.
+    """
+    try:
+        prompts_dir = _discover_prompts_dir()
+    except FileNotFoundError as exc:
+        print(f"({exc})", file=sys.stderr)
+        return
+    for label, filename in labeled_filenames:
+        print(f"{label}: {prompts_dir / filename}")
+
+
 # ---------- skills install ----------
 
 
@@ -1056,6 +1090,9 @@ def _cmd_pdata_init(args: argparse.Namespace) -> int:
             return 2
         print(result.report)
         print(f"\nProposal: {result.proposal_path}")
+        _print_migration_prompt_reminders(
+            ("After a successful --write, update project docs", "pdata-migration-claude-md-update.md"),
+        )
         return 0
 
     try:
@@ -1091,6 +1128,71 @@ def _cmd_pdata_init(args: argparse.Namespace) -> int:
         print()
         print(write_result.report)  # spec §7.1 step 4's diff report, for review
         print(f"\nVerify: ccst pdata verify --project {args.project} --full")
+        _print_migration_prompt_reminders(
+            ("Update project docs", "pdata-migration-claude-md-update.md"),
+            ("Update consuming skills", "pdata-migration-skills-update.md"),
+        )
+        print("SUCCESS")
+        return 0
+
+
+def _cmd_pdata_reorganize(args: argparse.Namespace) -> int:
+    from cc_session_tools.lib.pdata import init_paths, reorganize, write_log
+
+    try:
+        project_root = init_paths.resolve_project_root(args.project, rehearse=None)
+    except ValueError as exc:
+        # Matches _cmd_pdata_init's own handling of the identical resolve_project_root() call -
+        # a bad --project name (e.g. containing '/') must give the same clean exit-2 message
+        # every other pdata command gives, not an uncaught traceback.
+        print(f"ccst pdata: {exc}", file=sys.stderr)
+        return 2
+
+    if not args.write:
+        try:
+            plan = reorganize.dry_run(
+                project=args.project, project_root=project_root,
+                folder=args.folder, strategy=args.strategy,
+            )
+        except (FileNotFoundError, ValueError) as exc:
+            print(f"ccst pdata: {exc}", file=sys.stderr)
+            return 2
+        for move in plan.moves:
+            print(f"{move.old_relative} -> {move.new_relative}")
+        for matched in plan.matched_records:
+            print(f"  pdata record {matched.record.id} (group={matched.record.record_group}): "
+                  f"file_path -> {matched.new_file_path}")
+        for ref in plan.external_references:
+            print(f"  external reference: {ref.file}:{ref.line_number}: {ref.line_text}")
+        if not plan.moves:
+            print(f"no files found directly under {args.folder}/")
+        return 0
+
+    # --write can move many files over a long-running, potentially flaky I/O path - durably
+    # logged the same way `ccst pdata init --write` is, under this operation's own filename so
+    # the two never truncate each other's log (see reorganize.REORGANIZE_WRITE_LOG_FILENAME).
+    with write_log.WriteLog(project_root, log_filename=reorganize.REORGANIZE_WRITE_LOG_FILENAME):
+        try:
+            result = reorganize.write(
+                project=args.project, project_root=project_root,
+                folder=args.folder, strategy=args.strategy,
+            )
+        except (FileNotFoundError, ValueError) as exc:
+            print(f"ccst pdata: {exc}", file=sys.stderr)
+            print(f"ERROR: {exc}")
+            return 2
+
+        if result.failure is not None:
+            print("ccst pdata reorganize: failed, rolled back:", file=sys.stderr)
+            for reason in result.failure.reasons:
+                print(f"  - {reason}", file=sys.stderr)
+            print(f"ERROR: failed, rolled back ({len(result.failure.reasons)} reason(s))")
+            return 1
+
+        print(f"Moved {len(result.plan.moves)} file(s) under {args.folder}/")
+        print(f"Backup: {result.backup_path}")
+        for ref in result.plan.external_references:
+            print(f"  still needs manual review: {ref.file}:{ref.line_number}: {ref.line_text}")
         print("SUCCESS")
         return 0
 
@@ -2105,6 +2207,19 @@ def _build_parser() -> argparse.ArgumentParser:
         ),
     )
 
+    pdata_reorganize_parser = pdata_sub.add_parser(
+        "reorganize", help="Split a flat folder into a nested (by-year or by-year-month) structure"
+    )
+    pdata_reorganize_parser.add_argument("--project", required=True, metavar="NAME")
+    pdata_reorganize_parser.add_argument("--folder", required=True, metavar="RELATIVE_PATH")
+    pdata_reorganize_parser.add_argument(
+        "--strategy", required=True, choices=("by-year", "by-year-month"),
+    )
+    pdata_reorganize_parser.add_argument(
+        "--write", action="store_true",
+        help="Perform the move and update matching pdata records (default: dry-run only)",
+    )
+
     pdata_reconcile_parser = pdata_sub.add_parser(
         "reconcile-session-output",
         help="Backfill the session-output index from cc-sessions/*/out/ on disk (idempotent)",
@@ -2409,6 +2524,8 @@ def main() -> None:
             sys.exit(_cmd_pdata_restore(args))
         if args.verb == "init":
             sys.exit(_cmd_pdata_init(args))
+        if args.verb == "reorganize":
+            sys.exit(_cmd_pdata_reorganize(args))
         if args.verb == "reconcile-session-output":
             sys.exit(_cmd_pdata_reconcile_session_output(args))
         if args.verb == "verify":

{cc_session_tools-2.7.2 → cc_session_tools-2.8.1}/src/cc_session_tools/lib/pdata/init_paths.py

@@ -76,7 +76,7 @@ def backup_dir_override(rehearse: Path | None) -> Iterator[None]:
     whatever CCST_PDATA_BACKUP_DIR is already set to), by reusing this plan's own
     backup.BACKUP_DIR_ENV seam — mirrors project_db_dir_override's shape exactly.
     Without this, a rehearsed --write would still deposit a
-    <project>-<epoch>.tar.gz into the same directory a genuine production
+    <project>-<YYYYMMDD-HHMMSS>.tar.gz into the same directory a genuine production
     migration's backup would use, indistinguishable by filename. No-op when
     rehearse is None."""
     if rehearse is None:

{cc_session_tools-2.7.2 → cc_session_tools-2.8.1}/src/cc_session_tools/lib/pdata/init_service.py

@@ -164,7 +164,7 @@ def write(
     # A's CCST_PROJECT_DB_DIR seam), backup_dir_override redirects where
     # backup.create_backup() below writes its tar.gz (this module's own
     # CCST_PDATA_BACKUP_DIR seam). Without the second seam, a rehearsed --write
-    # would still deposit a real <project>-<epoch>.tar.gz into the production
+    # would still deposit a real <project>-<YYYYMMDD-HHMMSS>.tar.gz into the production
     # backup directory — indistinguishable by filename from a genuine migration's
     # backup. Both are no-ops when rehearse is None.
     with (

cc_session_tools-2.8.1/src/cc_session_tools/lib/pdata/reorganize.py

@@ -0,0 +1,367 @@
+"""Flat-to-nested folder restructuring for `ccst pdata reorganize` (design spec
+2026-08-21-pm-project-layout-reference-design.md, §3). Scoped to exactly one operation:
+splitting a flat folder into year or year/month subfolders once it's grown past the
+`pm-project-layout-reference` skill's 500-file guidance - not general-purpose reorganisation.
+
+dry_run() never touches the filesystem or the database; write() (a later task) performs the
+moves and DB updates dry_run() planned, reusing backup.create_backup() as its safety net
+exactly the way `ccst pdata init --write` does.
+"""
+from __future__ import annotations
+
+import re
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from cc_session_tools.lib.pdata import backup, init_paths, service
+from cc_session_tools.lib.pdata.init_paths import PROPOSAL_FILENAME
+from cc_session_tools.lib.pdata.service import Record
+from cc_session_tools.lib.pdata.write_log import LOG_FILENAME as WRITE_LOG_FILENAME
+
+_LEADING_DATE_RE = re.compile(r"^(?P<year>\d{4})\.(?P<month>\d{2})\.(?P<day>\d{2})-")
+
+_STRATEGIES = frozenset({"by-year", "by-year-month"})
+
+# This operation's own durable per-run log (mirrors ccst-pdata-init-write.log, but under its
+# own name so a reorganize run never truncates - or gets excluded/included alongside - an
+# unrelated pdata init run's log). Named here, not in write_log.py, since it's this module's
+# own concern; the CLI layer imports it to pass to write_log.WriteLog(log_filename=...).
+REORGANIZE_WRITE_LOG_FILENAME = "ccst-pdata-reorganize-write.log"
+
+# Filenames excluded from the external-reference scan by name, not just by directory - all
+# three persist at the project root indefinitely (classify.py excludes the first two from
+# classification for the same reason) and can literally contain the file_path of every
+# classified/moved entry, including files under whatever folder is being reorganized. Without
+# this, a project that has ever run `ccst pdata init` or a previous `ccst pdata reorganize`
+# would get a spurious "external reference" hit inside its own bookkeeping every time
+# dry_run() runs.
+_EXCLUDED_FILENAMES = frozenset({
+    PROPOSAL_FILENAME, WRITE_LOG_FILENAME, REORGANIZE_WRITE_LOG_FILENAME,
+})
+
+
+@dataclass(frozen=True, slots=True)
+class Move:
+    old_relative: str
+    new_relative: str
+
+
+@dataclass(frozen=True, slots=True)
+class ExternalReference:
+    file: Path
+    line_number: int
+    line_text: str
+
+
+@dataclass(frozen=True, slots=True)
+class MatchedRecord:
+    record: Record
+    new_file_path: str
+
+
+@dataclass(frozen=True, slots=True)
+class ReorganizePlan:
+    project: str
+    project_root: Path
+    folder: str
+    strategy: str
+    moves: list[Move]
+    matched_records: list[MatchedRecord]
+    external_references: list[ExternalReference]
+
+
+def _year_and_month_for(path: Path) -> tuple[str, str]:
+    """(year, month) for path - from a leading YYYY.MM.DD- date in the filename if present
+    (this codebase's own naming convention, e.g. archive-correspondence's output), else the
+    file's mtime. Shared by _year_for/_year_month_for so the date-vs-mtime decision and the
+    regex match happen exactly once, not twice with the same logic duplicated between them.
+
+    No validation that a regex-matched month is actually 01-12 (or day 01-31) - a malformed
+    but shape-matching date in a filename (e.g. "2025.13.99-foo.md") is accepted at face value.
+    Low-risk for a dry-run/planning tool whose output is reviewed before any --write, but worth
+    knowing if this is ever reused somewhere the plan isn't reviewed first."""
+    match = _LEADING_DATE_RE.match(path.name)
+    if match:
+        return match.group("year"), match.group("month")
+    localtime = time.localtime(path.stat().st_mtime)
+    return time.strftime("%Y", localtime), time.strftime("%m", localtime)
+
+
+def _year_for(path: Path) -> str:
+    year, _month = _year_and_month_for(path)
+    return year
+
+
+def _year_month_for(path: Path) -> str:
+    year, month = _year_and_month_for(path)
+    return f"{year}/{month}"
+
+
+def _new_relative(folder: str, entry: Path, strategy: str) -> str:
+    subdir = _year_for(entry) if strategy == "by-year" else _year_month_for(entry)
+    return f"{folder}/{subdir}/{entry.name}"
+
+
+def _scan_external_references(
+    *, project_root: Path, folder: str, old_relatives: list[str],
+) -> list[ExternalReference]:
+    """Grep every text file in project_root (excluding folder itself and the usual
+    ccst/git bookkeeping dirs) for a literal occurrence of any old_relatives entry - reported
+    only, never edited (design spec §3: rewriting prose isn't safe to automate).
+
+    folder is excluded by path-prefix comparison, not single-component name matching - folder
+    can itself be multi-segment (e.g. "workstreams/ws-01"), which a plain
+    `part in excluded_names` check would never match against any single path component.
+
+    Reuses init_paths.EXCLUDED_DIR_NAMES - the same set classify.py's own directory walk
+    already excludes - rather than hardcoding a second, incomplete copy: a hardcoded
+    ".pdata-migrated" literal here would also miss REHEARSAL_DB_DIRNAME/
+    REHEARSAL_BACKUP_DIRNAME, walking into a rehearsal sandbox's own contents on any project
+    that has ever used --rehearse and reporting spurious matches from inside it."""
+    excluded_dir_names = init_paths.EXCLUDED_DIR_NAMES
+    folder_parts = Path(folder).parts
+    refs: list[ExternalReference] = []
+    for candidate in sorted(project_root.rglob("*")):
+        if not candidate.is_file():
+            continue
+        rel_parts = candidate.relative_to(project_root).parts
+        if rel_parts[:len(folder_parts)] == folder_parts:
+            continue  # inside the folder being reorganized itself
+        if any(part in excluded_dir_names for part in rel_parts[:-1]):
+            continue
+        if candidate.name in _EXCLUDED_FILENAMES:
+            continue  # ccst's own bookkeeping - see _EXCLUDED_FILENAMES's comment
+        try:
+            text = candidate.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            continue
+        for line_number, line in enumerate(text.splitlines(), start=1):
+            for old_relative in old_relatives:
+                if old_relative in line:
+                    refs.append(ExternalReference(
+                        file=candidate, line_number=line_number, line_text=line.strip(),
+                    ))
+    return refs
+
+
+def _validate_relative_folder(folder: str) -> None:
+    """A separate check from (not a call to) service._validate_relative_file_path - similar in
+    spirit, but folder has two failure modes file_path doesn't need to guard against, since
+    file_path is never joined with mkdir() to build a new directory tree the way folder is here:
+
+    - An absolute path silently discards project_root entirely when joined with `/` (pathlib's
+      own behaviour, not a bug in this code - `Path("/a") / "/etc"` is `Path("/etc")`), and a
+      '..' segment can escape project_root the same way a crafted --file could.
+    - An EMPTY folder ("") makes old_relative/new_relative leading-slash strings
+      (f"{folder}/{name}" -> "/name"), which then trigger the exact same absolute-path escape
+      above once project_root / new_relative is evaluated - so empty must be rejected as its
+      own case, before the absolute-path check ever sees it (an empty string doesn't start with
+      "/", so that check alone wouldn't catch it). A trailing or doubled slash
+      ("correspondence/", "a//b") produces a doubled-slash old_relative/new_relative that no
+      longer matches the single-slash file_path values pdata records and project docs actually
+      use - write() would then silently update zero matching records and report success while
+      every affected record's file_path goes stale, instead of erroring loudly."""
+    if folder.startswith("/"):
+        raise ValueError(f"--folder must be relative to the project root, got absolute path: {folder!r}")
+    segments = folder.split("/")
+    if not folder or any(not segment for segment in segments):
+        raise ValueError(
+            f"--folder must not be empty or contain empty/trailing path segments: {folder!r}"
+        )
+    if any(segment == ".." for segment in segments):
+        raise ValueError(f"--folder must not contain '..' path-traversal segments: {folder!r}")
+
+
+def dry_run(*, project: str, project_root: Path, folder: str, strategy: str) -> ReorganizePlan:
+    if strategy not in _STRATEGIES:
+        raise ValueError(f"unknown strategy {strategy!r} - must be one of {sorted(_STRATEGIES)}")
+    _validate_relative_folder(folder)
+    folder_path = project_root / folder
+    if not folder_path.is_dir():
+        raise FileNotFoundError(f"no such folder to reorganize: {folder_path}")
+
+    entries = sorted(p for p in folder_path.iterdir() if p.is_file())
+    moves = [
+        Move(
+            old_relative=f"{folder}/{entry.name}",
+            new_relative=_new_relative(folder, entry, strategy),
+        )
+        for entry in entries
+    ]
+
+    matched = service.find_records_by_file_path_prefix(project=project, prefix=f"{folder}/")
+    move_by_old = {m.old_relative: m.new_relative for m in moves}
+    matched_records = [
+        MatchedRecord(record=record, new_file_path=move_by_old[record.file_path])
+        for record in matched
+        if record.file_path is not None and record.file_path in move_by_old
+    ]
+
+    external_references = _scan_external_references(
+        project_root=project_root, folder=folder,
+        old_relatives=[m.old_relative for m in moves],
+    )
+
+    return ReorganizePlan(
+        project=project, project_root=project_root, folder=folder, strategy=strategy,
+        moves=moves, matched_records=matched_records, external_references=external_references,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class ReorganizeFailure:
+    reasons: list[str]
+
+
+@dataclass(frozen=True, slots=True)
+class ReorganizeResult:
+    plan: ReorganizePlan
+    backup_path: Path | None
+    failure: ReorganizeFailure | None
+
+
+def _is_git_repo(project_root: Path) -> bool:
+    return (project_root / ".git").exists()
+
+
+def _remove_empty_dirs_up_to(*, start: Path, boundary: Path) -> None:
+    """Remove start and each successive empty parent directory, stopping at (never removing)
+    boundary itself. Shared by _move_file's own failure cleanup and _move_file_back's rollback
+    cleanup - both need to walk back up through however many nesting levels by-year-month left
+    (two - correspondence/2025/06/) without ever deleting the folder being reorganized."""
+    current = start
+    while current != boundary and current.is_dir() and not any(current.iterdir()):
+        current.rmdir()
+        current = current.parent
+
+
+def _first_missing_ancestor(*, start: Path, boundary: Path) -> Path | None:
+    """Walking from start up towards (not including) boundary, the shallowest directory that
+    does not yet exist - exactly the topmost directory `start.mkdir(parents=True)` would
+    actually create. None if start already exists (mkdir would be a complete no-op).
+
+    Used so _move_file's failure-cleanup only ever removes directories its own mkdir call
+    genuinely created, never one that already existed before it - e.g. left over from an
+    earlier partial/crashed run, or present for an unrelated reason. Without this, cleanup
+    would delete any empty directory sitting at the destination path regardless of whether
+    this call was the one that created it."""
+    if start.exists():
+        return None
+    missing = start
+    while missing.parent != boundary and not missing.parent.exists():
+        missing = missing.parent
+    return missing
+
+
+def _move_file(*, project_root: Path, move: Move, folder: str, use_git: bool) -> None:
+    src = project_root / move.old_relative
+    dest = project_root / move.new_relative
+    folder_path = project_root / folder
+    newly_created_root = _first_missing_ancestor(start=dest.parent, boundary=folder_path)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        if use_git:
+            subprocess.run(
+                ["git", "mv", move.old_relative, move.new_relative],
+                cwd=project_root, check=True, capture_output=True, text=True,
+            )
+        else:
+            src.rename(dest)
+    except (OSError, subprocess.CalledProcessError):
+        # The mkdir above may have just created dest.parent (and its own new parents, for
+        # by-year-month) - if the move itself then failed, that directory was never populated
+        # and would otherwise be left behind as debris: write()'s own rollback only knows
+        # about *completed* moves (this one was never added to `moved`), so nothing else
+        # would ever clean it up. newly_created_root is None when dest.parent already existed
+        # before this call (nothing to clean up - it wasn't ours to remove).
+        if newly_created_root is not None:
+            _remove_empty_dirs_up_to(start=dest.parent, boundary=newly_created_root.parent)
+        raise
+
+
+def _move_file_back(*, project_root: Path, move: Move, folder: str, use_git: bool) -> None:
+    """Undo _move_file - used by write()'s rollback path only."""
+    dest_parent = (project_root / move.new_relative).parent
+    if use_git:
+        subprocess.run(
+            ["git", "mv", move.new_relative, move.old_relative],
+            cwd=project_root, check=True, capture_output=True, text=True,
+        )
+    else:
+        (project_root / move.new_relative).rename(project_root / move.old_relative)
+    _remove_empty_dirs_up_to(start=dest_parent, boundary=project_root / folder)
+
+
+def write(*, project: str, project_root: Path, folder: str, strategy: str) -> ReorganizeResult:
+    plan = dry_run(project=project, project_root=project_root, folder=folder, strategy=strategy)
+    use_git = _is_git_repo(project_root)
+
+    # Matches init_service.write()'s own handling of this exact call (init_service.py
+    # ~lines 220-232): create_backup() can exhaust its retries and raise BackupError, which
+    # must become a structured failure here too, not an uncaught crash before anything has
+    # been moved.
+    try:
+        backup_path = backup.create_backup(project=project, project_root=project_root)
+    except backup.BackupError as exc:
+        return ReorganizeResult(plan=plan, backup_path=None, failure=ReorganizeFailure(reasons=[str(exc)]))
+
+    moved: list[Move] = []
+    # (matched, post-update Record incl. its bumped version) for every update_record() call
+    # that succeeded so far - needed to reverse them in the right order on failure, each with
+    # the expected_version its OWN update actually left the row at, not its pre-update version.
+    updated: list[tuple[MatchedRecord, Record]] = []
+    try:
+        for move in plan.moves:
+            _move_file(project_root=project_root, move=move, folder=folder, use_git=use_git)
+            moved.append(move)
+
+        for matched in plan.matched_records:
+            updated_record = service.update_record(
+                project=project, record_id=matched.record.id,
+                expected_version=matched.record.version,
+                content=None, file_path=matched.new_file_path, fields={},
+            )
+            updated.append((matched, updated_record))
+    except (OSError, subprocess.CalledProcessError, service.VersionConflictError,
+            service.RecordNotFoundError) as exc:
+        reasons = [str(exc)]
+        # Roll back each moved file and its matching DB update (if any) as one paired unit,
+        # in reverse order - move the file back FIRST, then revert its record, so the two
+        # can never end up disagreeing about where the file actually is:
+        #   - if the move-back fails, the record is left un-reverted too (still pointing at
+        #     the new path) - consistent, since the file is still physically there.
+        #   - if the move-back succeeds but the reversal update_record() call then fails,
+        #     that's flagged explicitly rather than silently diverging - matched.record is
+        #     filtered upstream (dry_run) to always have a non-None file_path, so the
+        #     reversal always restores a real prior value, never a no-op None.
+        # Each step is wrapped individually, matching init_service._rollback()'s own contract:
+        # an unwrapped raise here would abort the rest of the rollback (and this whole
+        # function) instead of returning a ReorganizeResult at all.
+        updated_by_new_path = {m.new_file_path: (m, r) for m, r in updated}
+        for move in reversed(moved):
+            pair = updated_by_new_path.get(move.new_relative)
+            try:
+                _move_file_back(project_root=project_root, move=move, folder=folder, use_git=use_git)
+            except (OSError, subprocess.CalledProcessError) as rollback_exc:
+                reasons.append(f"{move.new_relative}: rollback failed: {rollback_exc}")
+                continue  # file never moved back - its record (if any) must keep the new path
+            if pair is None:
+                continue
+            matched, updated_record = pair
+            try:
+                service.update_record(
+                    project=project, record_id=matched.record.id,
+                    expected_version=updated_record.version,
+                    content=None, file_path=matched.record.file_path, fields={},
+                )
+            except (service.VersionConflictError, service.RecordNotFoundError) as rollback_exc:
+                reasons.append(f"record {matched.record.id}: rollback failed: {rollback_exc}")
+
+        return ReorganizeResult(
+            plan=plan, backup_path=backup_path,
+            failure=ReorganizeFailure(reasons=reasons),
+        )
+
+    return ReorganizeResult(plan=plan, backup_path=backup_path, failure=None)

{cc_session_tools-2.7.2 → cc_session_tools-2.8.1}/src/cc_session_tools/lib/pdata/service.py

@@ -9,7 +9,7 @@ import re as _re
 from collections.abc import Mapping
 from dataclasses import dataclass, field
 
-from cc_session_tools.lib.pdata import naming, repository
+from cc_session_tools.lib.pdata import naming, repository, store
 
 # op is deliberately \S+ here (not the literal alternation of valid ops) — matching only a
 # literal alternation would make an invalid op (e.g. "~=") fail to match the whole regex at all,
@@ -213,6 +213,65 @@ def query_records(
         conn.close()
 
 
+def find_records_by_file_path_prefix(*, project: str, prefix: str) -> list[Record]:
+    """Every active record across every record_group in this project whose file_path starts
+    with prefix - used by lib/pdata/reorganize.py to find which rows need their file_path
+    updated when a folder is split into a nested structure. Returns [] both when the project
+    has no .db yet and when it has one but nothing matches - callers that need to distinguish
+    "no store" from "store, no match" should check store.db_path(project).exists() themselves.
+
+    Goes straight to repository.query_records() with an already-parsed (field, op, value)
+    condition, one connection reused across every record_group, rather than routing through
+    this module's own query_records()/_parse_where_clause() string DSL: that DSL's
+    `\\s+`-based regex would silently strip any leading whitespace off prefix on the round
+    trip through it (a real, if narrow, correctness bug for a prefix that legitimately starts
+    with a space), and re-resolving a fresh connection per record_group here would be needless
+    overhead for what's logically one read. list_extension_columns/get_extension_row's
+    row-materialisation is duplicated inline here rather than shared with list_records/
+    query_records above - matching how those two already duplicate the same block between
+    each other rather than a factored-out helper.
+
+    Known limitation: prefix is still used as a raw SQL LIKE pattern, so a literal '%' or '_'
+    in it is interpreted as a wildcard rather than a literal character - SQLite's LIKE has no
+    ESCAPE-clause support wired up anywhere in this codebase. Not a practical issue for this
+    callsite specifically - prefix is always a project-relative folder path (this codebase's
+    own naming convention uses hyphens, not underscores, e.g. ws-01-slug), but worth knowing if
+    this function is ever reused somewhere prefix isn't a controlled folder name."""
+    if not prefix:
+        raise ValueError("find_records_by_file_path_prefix requires a non-empty prefix")
+    if not store.db_path(project).exists():
+        return []
+    conn = repository.connect(project)
+    try:
+        matches: list[Record] = []
+        for group in repository.list_record_groups(conn):
+            record_group = group["record_group"]
+            # list_record_groups() types its return as dict[str, object] since row_count and
+            # max_updated_at are int-shaped columns in the same row - record_group itself is
+            # always the TEXT column's value, never anything else, so this narrows it for
+            # mypy the same way an impossible-state assert would (coding-standards: make the
+            # impossible state visible rather than silently re-checking it).
+            assert isinstance(record_group, str)
+            rows = repository.query_records(
+                conn, record_group=record_group,
+                conditions=[("file_path", "LIKE", f"{prefix}%")],
+                limit=None, include_deleted=False,
+            )
+            has_ext = repository.extension_table_exists(conn, record_group)
+            for row in rows:
+                record = _row_to_record(row)
+                if has_ext:
+                    ext_row = repository.get_extension_row(conn, record_group, row["id"])
+                    if ext_row is not None:
+                        record.fields = {
+                            k: ext_row[k] for k in ext_row.keys() if k != "record_id"
+                        }
+                matches.append(record)
+        return matches
+    finally:
+        conn.close()
+
+
 class RecordNotFoundError(Exception):
     """Raised when a record id resolves to no row (or no active row)."""