cc-session-tools 0.7.0__py3-none-any.whl

cc_session_tools/__init__.py

@@ -0,0 +1,21 @@
+"""Claude Code session management CLI tools (ccd, ccr, ccs)."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+
+def _get_version() -> str:
+    # Prefer the installed-distribution version (set by pipx/pip install).
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+        return version("cc-session-tools")
+    except PackageNotFoundError:
+        pass
+    except ImportError:
+        pass
+    # Fallback for source-tree runs (e.g. PYTHONPATH=src python -m ...).
+    return "0.0.0+source"
+
+
+__version__ = _get_version()

cc_session_tools/cli/ccd.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from cc_session_tools import __version__
+from cc_session_tools.lib import prompts, rules
+from cc_session_tools.lib.tasklist import id_for_project
+
+
+def launch_claude(cmd: list[str], env: dict[str, str]) -> None:
+    """Replace the current process with `claude`. Wrapped in a function so
+    tests can monkeypatch this without performing a real exec."""
+    os.execvpe(cmd[0], cmd, env)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="ccd",
+        description="Start a new Claude Code session with a pre-created cc-sessions/ dir.",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    p.add_argument("--force", action="store_true",
+                   help="Skip root, project-name, and tag-prefix checks.")
+    p.add_argument("--debug", action="store_true",
+                   help="Enable debug output (also: CCX_DEBUG=1).")
+    p.add_argument("tag", help="Name tag (no spaces; use dashes).")
+    p.add_argument("extra", nargs=argparse.REMAINDER,
+                   help="Additional args passed through to claude.")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+
+    if args.debug:
+        os.environ["CCX_DEBUG"] = "1"
+    from cc_session_tools.lib.debug import debug
+
+    real_pwd = Path.cwd().resolve()
+
+    # Run the Levenshtein typo / missing-prefix prompts FIRST so that a tag
+    # like "test-foo" under the strict root can be corrected to "oneshot-test-foo"
+    # interactively, before the rules validator would reject it outright.
+    # The prompt is a no-op outside the strict (PROJ) root.
+    tag = args.tag
+    if not args.force:
+        tag = prompts.maybe_correct_tag(real_pwd, tag)
+
+    # Validate tag/cwd via shared rules (on the possibly-corrected tag).
+    ok, errors = rules.check_session_init(real_pwd, tag, force=args.force)
+    if not ok:
+        print("ccd: validation failed:", file=sys.stderr)
+        for e in errors:
+            for line in e.splitlines():
+                print(f"  {line}", file=sys.stderr)
+        if not args.force:
+            print("  (use --force to bypass root and strict-root checks)",
+                  file=sys.stderr)
+        return 1
+
+    date_str = datetime.now().strftime("%Y%m%d")
+    session_name = f"{date_str}-{tag}"
+    session_dir = real_pwd / "cc-sessions" / session_name
+    debug(f"tag: {tag!r}")
+    debug(f"session_dir: {session_dir}")
+
+    if session_dir.exists():
+        print(
+            f"ccd: session '{session_name}' already started today in this directory.",
+            file=sys.stderr,
+        )
+        print(f"ccd:   existing: {session_dir}", file=sys.stderr)
+        print(
+            f"ccd: Use a different name tag, or 'ccr {tag}' to resume the existing one.",
+            file=sys.stderr,
+        )
+        return 1
+
+    (session_dir / "working").mkdir(parents=True)
+    (session_dir / "out").mkdir(parents=True)
+
+    # Build env for the SessionStart hook + task list. Drop any inherited
+    # CLAUDE_CODE_TASK_LIST_ID so the new one (or absence of one) is authoritative.
+    env = os.environ.copy()
+    env.pop("CLAUDE_CODE_TASK_LIST_ID", None)
+    env["CLD_SESSION_TAG"] = tag
+    env["CLD_SESSION_DIR"] = str(session_dir.relative_to(real_pwd))
+    env["CLD_SESSION_MODE"] = "new"
+    task_list_id = id_for_project(real_pwd)
+    if task_list_id is not None:
+        env["CLAUDE_CODE_TASK_LIST_ID"] = task_list_id
+
+    cmd = [
+        "claude",
+        "-n", session_name,
+        "--remote-control", session_name,
+        *(args.extra or []),
+    ]
+    # Chdir to the resolved project path so Claude Code records its
+    # ~/.claude/projects/<encoded-cwd>/ key against the canonical, symlink-
+    # resolved path. Matches the original bash ccd's `cd "$real_pwd"` step.
+    debug(f"launching: {cmd}")
+    os.chdir(real_pwd)
+    launch_claude(cmd, env)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cc_session_tools/cli/ccr.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from cc_session_tools import __version__
+from cc_session_tools.lib.claude_flags import get_claude_flags
+from cc_session_tools.lib.roots import load_session_roots
+from cc_session_tools.lib.sessions import SESSION_FULL_RE, SessionMatch, find_matching_sessions, session_tag
+from cc_session_tools.lib.tasklist import id_for_project
+
+
+def launch_claude_resume(cmd: list[str], env: dict[str, str], cwd: Path | None = None) -> None:
+    """Replace the current process with `claude --resume`. Wrapped so tests
+    can monkeypatch this without performing a real exec."""
+    if cwd is not None:
+        os.chdir(cwd)
+    os.execvpe(cmd[0], cmd, env)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="ccr",
+        description="Resume a Claude Code session by name-tag fragment.",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    p.add_argument("fragment", help="Substring to match against session basenames.")
+    p.add_argument("--debug", action="store_true",
+                   help="Enable debug output (also: CCX_DEBUG=1).")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args, remainder = _build_parser().parse_known_args(argv)
+
+    if args.debug:
+        os.environ["CCX_DEBUG"] = "1"
+    from cc_session_tools.lib.debug import debug
+
+    roots = load_session_roots()
+
+    # Exact-match fast-path: if fragment looks like a full basename, try a
+    # direct directory lookup before falling back to substring search.  This
+    # prevents "20260504-foo" from being treated as ambiguous when
+    # "20260504-foo-bar" also exists.
+    exact_match: SessionMatch | None = None
+    if SESSION_FULL_RE.fullmatch(args.fragment):
+        for root in roots:
+            if not root.is_dir():
+                continue
+            for proj in root.iterdir():
+                if not proj.is_dir():
+                    continue
+                candidate = proj / "cc-sessions" / args.fragment
+                if candidate.is_dir():
+                    exact_match = SessionMatch(
+                        basename=args.fragment,
+                        project_dir=proj,
+                        session_dir=candidate,
+                    )
+                    break
+            if exact_match:
+                break
+
+    matches = [exact_match] if exact_match else find_matching_sessions(args.fragment, roots)
+    debug(f"fragment: {args.fragment!r}")
+    debug(f"matches: {[m.basename for m in matches]}")
+
+    if not matches:
+        print(f"ccr: no sessions match '{args.fragment}'", file=sys.stderr)
+        return 1
+
+    if len(matches) > 1:
+        if len(matches) <= 10 and sys.stdin.isatty():
+            from cc_session_tools.lib.picker import pick_from_list
+            from cc_session_tools.lib.sessions import session_start_date
+            matches.sort(key=lambda x: session_start_date(x.basename) or "", reverse=True)
+            labels = [f"{m.basename} ({m.project_dir})" for m in matches]
+            idx = pick_from_list(labels)
+            if idx is None:
+                return 0
+            m = matches[idx]
+            # Fall through to single-match resume logic below
+        else:
+            print("Multiple sessions match that name tag fragment:")
+            for m in matches:
+                print(f"  {m.basename} ({m.project_dir})")
+            print(
+                "Please re-run ccr with an unambiguous fragment of the name tag "
+                "of the session you want to resume."
+            )
+            return 0
+    else:
+        m = matches[0]
+
+    # single match (or picker selection) - variable m is set above
+    tag = session_tag(m.basename)
+    if tag is None:
+        # Should not happen because find_matching_sessions only returns
+        # basenames that match SESSION_BASENAME_RE, but fall back gracefully.
+        tag = m.basename
+
+    # Fail fast with a clear message when claude is not on PATH.
+    if not shutil.which("claude"):
+        print(
+            "ccr: 'claude' not found on PATH - is Claude Code installed?",
+            file=sys.stderr,
+        )
+        return 1
+
+    # Validate and pass through any extra flags from remainder.
+    # Long flags (--foo) are checked against claude's known flags.
+    # Short flags (-f) pass through without validation.
+    if remainder:
+        valid_flags = get_claude_flags()
+        for arg in remainder:
+            if arg.startswith("--"):
+                flag_name = arg.split("=")[0]
+                if flag_name not in valid_flags:
+                    print(
+                        f"ccr: unknown flag '{arg}'; not a recognised claude option",
+                        file=sys.stderr,
+                    )
+                    return 1
+
+    env = os.environ.copy()
+    env.pop("CLAUDE_CODE_TASK_LIST_ID", None)
+    env["CLD_SESSION_TAG"] = tag
+    env["CLD_SESSION_DIR"] = str(m.session_dir)
+    env["CLD_SESSION_MODE"] = "resume"
+    task_list_id = id_for_project(m.project_dir)
+    if task_list_id is not None:
+        env["CLAUDE_CODE_TASK_LIST_ID"] = task_list_id
+
+    cmd = [
+        "claude",
+        "--resume", m.basename,
+        "--remote-control", m.basename,
+    ]
+    if remainder:
+        cmd.extend(remainder)
+    debug(f"resuming: {m.basename} in {m.project_dir}")
+    launch_claude_resume(cmd, env, cwd=m.project_dir)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())