cc-session-control 0.4.0__py3-none-any.whl

cc_session_control/cli.py

@@ -0,0 +1,288 @@
+"""CLI entry point for csctl."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    from . import __version__
+
+    parser = argparse.ArgumentParser(
+        prog="csctl",
+        description="TUI manager for Claude Code sessions and Remote Control",
+    )
+    parser.add_argument("--version", action="version", version=f"csctl {__version__}")
+    parser.add_argument("--workspace", type=Path, help="Override workspace root directory")
+
+    sub = parser.add_subparsers(dest="command")
+
+    # rc subcommand group
+    rc_parser = sub.add_parser("rc", help="Remote Control management")
+    rc_sub = rc_parser.add_subparsers(dest="rc_command")
+    rc_sub.add_parser("status", help="Show RC status for all projects")
+    rc_add = rc_sub.add_parser("add", help="Add project to RC list and start")
+    rc_add.add_argument("project", nargs="?", default=".", help="Project name or '.' for current dir")
+    rc_rm = rc_sub.add_parser("rm", help="Remove project from RC list and stop")
+    rc_rm.add_argument("project", help="Project name")
+    rc_sub.add_parser("up", help="Start all listed projects")
+    rc_stop = rc_sub.add_parser("stop", help="Stop RC for a project")
+    rc_stop.add_argument("target", help="Project name or 'all'")
+    rc_sub.add_parser("list", help="Show enabled project list")
+
+    # prune subcommand
+    prune_parser = sub.add_parser("prune", help="Clean up sessions")
+    prune_parser.add_argument("--max-prompts", type=int, default=0, help="Max prompt count to prune (default: 0)")
+    prune_parser.add_argument("--apply", action="store_true", help="Actually delete (default: dry run)")
+    prune_parser.add_argument("--sweep-orphans", action="store_true", help="Clean orphan sid-keyed artifact directories")
+    prune_parser.add_argument("--sweep-zombies", action="store_true", help="Remove zombie sessions/<pid>.json files (dead procs; keeps current + alive pids)")
+    prune_parser.add_argument("--sweep-aged", action="store_true", help="Remove age-keyed global entries older than cleanup_age_days")
+
+    # agents subcommand
+    sub.add_parser("agents", help="List background agents")
+
+    # env subcommand
+    sub.add_parser("env", help="List bridge environments (current + orphan)")
+
+    return parser
+
+
+def _apply_workspace(args: argparse.Namespace) -> None:
+    if args.workspace:
+        from .config import cfg
+        cfg.workspace = args.workspace
+
+
+def _cmd_rc(args: argparse.Namespace) -> None:
+    from .data import rc
+
+    if not args.rc_command:
+        print("Usage: csctl rc <status|add|rm|up|stop|list>")
+        sys.exit(1)
+
+    sub = args.rc_command
+
+    if sub == "status":
+        projects = rc.scan()
+        for p in projects:
+            icon = {"running": "[running]", "dead": "[dead   ]", "stopped": "[stopped]"}.get(p.status, p.status)
+            auto = "auto" if p.auto_start else "    "
+            print(f"  {icon} {auto}  {p.name}")
+
+    elif sub == "add":
+        proj = args.project
+        if proj == ".":
+            ws = str(rc.cfg.workspace)
+            cwd = os.getcwd()
+            if cwd.startswith(ws + "/"):
+                proj = cwd[len(ws) + 1:].split("/")[0]
+            else:
+                print(f"Current directory is not under {ws}. Specify project name explicitly.")
+                sys.exit(1)
+        if not rc.is_trusted(proj):
+            print(f"Not trusted: {proj} — run 'claude' in that directory first to accept the trust dialog")
+            sys.exit(1)
+        rc.list_add(proj)
+        print(f"Added to list: {proj}")
+        ok = rc.start_one(proj)
+        if ok:
+            print(f"Started: ws/{proj}")
+
+    elif sub == "rm":
+        rc.list_rm(args.project)
+        rc.stop_one(args.project)
+        print(f"Removed and stopped: {args.project}")
+
+    elif sub == "up":
+        enabled = rc.list_enabled()
+        if not enabled:
+            print("List is empty")
+            return
+        count = rc.start_many(enabled)
+        print(f"Started {count} project(s)")
+
+    elif sub == "stop":
+        if args.target == "all":
+            rc.stop_all()
+            print("Stopped all")
+        else:
+            ok = rc.stop_one(args.target)
+            print(f"Stopped {args.target}" if ok else f"Not running: {args.target}")
+
+    elif sub == "list":
+        for name in rc.list_enabled():
+            print(name)
+
+
+def _cmd_prune(args: argparse.Namespace) -> None:
+    from .data.cleanup import (
+        cleanup_stats,
+        list_orphan_dirs,
+        prune_sessions,
+        remove_orphan_dirs,
+        remove_session,
+    )
+    from .data.sessions import scan
+
+    sessions = scan()
+    stats = cleanup_stats(sessions)
+    print(f"Total: {stats['total']}  Empty: {stats['empty']}  Short(<=2): {stats['short']}  Orphans: {stats['orphans']}")
+
+    if args.sweep_orphans:
+        orphans = list_orphan_dirs(sessions)
+        print(f"Would sweep {len(orphans)} orphan artifact dir(s)")
+        if not args.apply:
+            print("Dry run. Add --apply to execute.")
+            return
+        count = remove_orphan_dirs(sessions)
+        print(f"Swept {count} orphan dir(s).")
+        return
+
+    if args.sweep_zombies:
+        _cmd_prune_zombies(args)
+        return
+
+    if args.sweep_aged:
+        _cmd_prune_aged(args)
+        return
+
+    targets = prune_sessions(sessions, max_prompts=args.max_prompts)
+    print(f"Would prune {len(targets)} session(s) (<={args.max_prompts} prompts)")
+
+    if not args.apply:
+        print("Dry run. Add --apply to execute.")
+        return
+
+    for s in targets:
+        remove_session(s)
+    print(f"Pruned {len(targets)} session(s).")
+
+
+def _cmd_prune_zombies(args: argparse.Namespace) -> None:
+    """Strategy A pid-keyed sweep of `sessions/<pid>.json` (R7.1) via the CLI.
+
+    Reuses the already-gated `data/cleanup` helpers: `select_zombie_pids` keeps
+    the current session's pid and any alive pid of a resumed multi-pid sid, and
+    `remove_zombie_session_files` refuses without `/proc`. The dry-run preview is
+    gated here too — off `/proc` every pid looks dead, so `current` can't be
+    determined and we must not even claim the files are sweepable (R10).
+    """
+    from dataclasses import replace
+
+    from .data import proc, registry
+    from .data.cleanup import remove_zombie_session_files, select_zombie_pids
+
+    if not proc.current_determinable():
+        print("Refused: '/proc' unavailable — cannot determine the current session (R10).")
+        return
+    procs = [
+        replace(sp, proc_alive=proc.pid_alive(sp.pid, sp.proc_start))
+        for sp in registry.read_session_procs(max_age=0.0)
+    ]
+    cur = proc.ancestor_pids()
+    zombies = select_zombie_pids(procs, cur)
+    print(f"Would sweep {len(zombies)} zombie session file(s)")
+    if not args.apply:
+        print("Dry run. Add --apply to execute.")
+        return
+    count = remove_zombie_session_files(procs, cur)
+    print(f"Swept {count} zombie session file(s).")
+
+
+def _cmd_prune_aged(args: argparse.Namespace) -> None:
+    """Strategy B age sweep of time/global-keyed dirs (R7.2) via the CLI.
+
+    `remove_aged_entries` is mtime-only and session-agnostic, so (unlike the
+    zombie sweep) it is not gated on `/proc`.
+    """
+    from .config import cfg
+    from .data.cleanup import list_aged_entries, remove_aged_entries
+
+    aged = list_aged_entries()
+    print(f"Would sweep {len(aged)} aged entr(y/ies) older than {cfg.cleanup_age_days}d")
+    if not args.apply:
+        print("Dry run. Add --apply to execute.")
+        return
+    count = remove_aged_entries()
+    print(f"Swept {count} aged entr(y/ies).")
+
+
+def _cmd_agents(args: argparse.Namespace) -> None:
+    from .actions.agent_ops import job_host
+    from .data.registry import read_agent_jobs
+
+    jobs = read_agent_jobs(max_age=0.0)
+    if not jobs:
+        print("No background agents found.")
+        return
+    for job in jobs:
+        _pid, alive = job_host(job)
+        state = "live" if alive else (job.state or "settled")
+        tempo = job.tempo or "-"
+        name = job.name or job.short
+        print(f"  {job.short}  [{state}]  tempo={tempo}  {name}  {job.cwd}")
+
+
+def _cmd_env(args: argparse.Namespace) -> None:
+    from .data import environments, rc
+
+    # Scan RC servers so the env_* namespace is covered too (it has no state
+    # file — only a running server references it).
+    servers = rc.scan_servers()
+    # CURRENT is alive-gated (R3/R6): a zombie session's stale bridge must not be
+    # counted as bound. FILE-REFERENCED is the bridge-truthy membership set.
+    observed = environments.observe_live(rc_servers=servers, max_age=0.0)
+    file_referenced = environments.observe(rc_servers=servers, max_age=0.0)
+    # Record every file-referenced env so a later run (after RC toggled off / a job
+    # removed) reports it as an orphan = ledger − file-referenced (R6 persistence).
+    environments.upsert(file_referenced)
+    current = environments.current_envs(observed)
+    orphans = environments.orphan_envs(file_referenced)
+
+    print(f"Current bridge environments: {len(current)}")
+    for e in current:
+        print(f"  {e.env_id}  sid={e.bound_sid or '-'}")
+
+    print(f"Orphan environments (delete manually on claude.ai/code): {len(orphans)}")
+    for row in environments.manual_delete_list(file_referenced):
+        print(f"  {row['env_id']}  sid={row['bound_sid'] or '-'}")
+
+    print(
+        "Note: csctl cannot deregister cloud environments; "
+        "the orphan list is inherently incomplete "
+        "(environments minted while csctl was not running are not tracked)."
+    )
+
+
+def _cmd_tui(args: argparse.Namespace) -> None:
+    from .actions.session_ops import do_resume
+    from .app import App
+
+    app = App()
+    result = app.run()
+
+    if result and isinstance(result, tuple) and result[0] == "resume":
+        _, session, fork = result
+        do_resume(session, fork=fork)
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+    _apply_workspace(args)
+
+    if args.command == "rc":
+        _cmd_rc(args)
+    elif args.command == "prune":
+        _cmd_prune(args)
+    elif args.command == "agents":
+        _cmd_agents(args)
+    elif args.command == "env":
+        _cmd_env(args)
+    elif args.command is None:
+        _cmd_tui(args)
+    else:
+        parser.print_help()

cc_session_control/clipboard.py

@@ -0,0 +1,44 @@
+"""Cross-platform clipboard support."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+
+_backend: list[str] | None = None
+_encoding: str = "utf-8"
+
+
+def _detect() -> tuple[list[str], str]:
+    if os.path.isfile("/mnt/c/Windows/System32/clip.exe"):
+        return ["/mnt/c/Windows/System32/clip.exe"], "utf-16-le"
+
+    if shutil.which("pbcopy"):
+        return ["pbcopy"], "utf-8"
+
+    if os.environ.get("WAYLAND_DISPLAY") and shutil.which("wl-copy"):
+        return ["wl-copy"], "utf-8"
+
+    if os.environ.get("DISPLAY") and shutil.which("xclip"):
+        return ["xclip", "-selection", "clipboard"], "utf-8"
+
+    return [], "utf-8"
+
+
+def copy(text: str) -> bool:
+    global _backend, _encoding
+    if _backend is None:
+        _backend, _encoding = _detect()
+
+    if not _backend:
+        return False
+
+    try:
+        subprocess.run(
+            _backend, input=text.encode(_encoding),
+            timeout=5, check=True, capture_output=True,
+        )
+        return True
+    except Exception:
+        return False

cc_session_control/config.py

@@ -0,0 +1,132 @@
+"""Path detection and configuration."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+
+class Config:
+    def __init__(self) -> None:
+        self.claude_home: Path = Path.home() / ".claude"
+        self.claude_json: Path = Path.home() / ".claude.json"
+        xdg = os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config"))
+        self.config_dir: Path = Path(xdg) / "csctl"
+        self.rc_list: Path = self.config_dir / "rc-enabled"
+        self.rc_session: str = os.environ.get("CSCTL_RC_SESSION", "rc")
+        self.rc_stagger: int = int(os.environ.get("CSCTL_RC_STAGGER", "2"))
+        # Dedicated tmux session for interactive sessions relaunched under remote
+        # control (kept separate from rc_session, whose windows are managed RC
+        # server processes).
+        self.tmux_session: str = os.environ.get("CSCTL_TMUX_SESSION", "cc")
+        # Age threshold (days) for the time/global-keyed cleanup strategy.
+        self.cleanup_age_days: int = int(os.environ.get("CSCTL_CLEANUP_AGE_DAYS", "14"))
+        self._workspace: Path | None = None
+
+    @property
+    def workspace(self) -> Path:
+        if self._workspace is not None:
+            return self._workspace
+        self._workspace = _detect_workspace(self.claude_json)
+        return self._workspace
+
+    @workspace.setter
+    def workspace(self, value: Path) -> None:
+        self._workspace = value
+
+    @property
+    def projects_root(self) -> Path:
+        return self.claude_home / "projects"
+
+    @property
+    def environments_ledger(self) -> Path:
+        """csctl's own append-only bridge-environment ledger (R6).
+
+        Lives under `config_dir` (csctl state, NOT Claude Code's `claude_home`).
+        A property so tests that monkeypatch `cfg.config_dir` flow through.
+        """
+        return self.config_dir / "environments.jsonl"
+
+    # --- Claude Code state directories (single path authority) ---
+    # All derive from claude_home so tests that monkeypatch cfg.claude_home flow
+    # through. Never inline `claude_home / "..."` elsewhere — add it here.
+
+    @property
+    def sessions_dir(self) -> Path:
+        """Per-pid session registry files (`sessions/<pid>.json`)."""
+        return self.claude_home / "sessions"
+
+    @property
+    def jobs_dir(self) -> Path:
+        """Background agent job state (`jobs/<short>/state.json`)."""
+        return self.claude_home / "jobs"
+
+    @property
+    def session_env_dir(self) -> Path:
+        """Per-session env artifacts (`session-env/<sid>`)."""
+        return self.claude_home / "session-env"
+
+    @property
+    def file_history_dir(self) -> Path:
+        """Per-session file-edit history (`file-history/<sid>`)."""
+        return self.claude_home / "file-history"
+
+    @property
+    def shell_snapshots_dir(self) -> Path:
+        return self.claude_home / "shell-snapshots"
+
+    @property
+    def telemetry_dir(self) -> Path:
+        return self.claude_home / "telemetry"
+
+    @property
+    def plans_dir(self) -> Path:
+        return self.claude_home / "plans"
+
+    @property
+    def backups_dir(self) -> Path:
+        return self.claude_home / "backups"
+
+    @property
+    def paste_cache_dir(self) -> Path:
+        return self.claude_home / "paste-cache"
+
+    @property
+    def debug_dir(self) -> Path:
+        return self.claude_home / "debug"
+
+    @property
+    def uploads_dir(self) -> Path:
+        return self.claude_home / "uploads"
+
+    @property
+    def tasks_dir(self) -> Path:
+        return self.claude_home / "tasks"
+
+
+def _detect_workspace(claude_json: Path) -> Path:
+    env = os.environ.get("CSCTL_WORKSPACE")
+    if env:
+        return Path(env)
+
+    default = Path.home() / "workspace"
+    if default.is_dir():
+        return default
+
+    try:
+        with open(claude_json) as f:
+            data = json.load(f)
+        dirs = [k for k in data.get("projects", {}) if "/" in k]
+        if dirs:
+            from os.path import commonpath
+            common = Path(commonpath(dirs))
+            if common.is_dir() and common != Path.home():
+                return common
+    except Exception:
+        pass
+
+    return Path.cwd()
+
+
+cfg = Config()

cc_session_control/data/agents.py

@@ -0,0 +1,12 @@
+"""Backward-compatible re-export shim — liveness lives in `liveness.py` now.
+
+Kept zero-logic on purpose: re-exporting the *same* callables means terminate's
+`invalidate_cache()` and scan's `alive_map()` share the ONE cache in
+`liveness` (`liveness._cache`). New code should import from `.liveness`.
+"""
+
+from __future__ import annotations
+
+from .liveness import alive_map, invalidate_cache
+
+__all__ = ["alive_map", "invalidate_cache"]