cursorfleet 0.1.0__py3-none-any.whl

cursorfleet/cli/commands/status.py

@@ -0,0 +1,210 @@
+"""``cursorfleet status [--json]``: fleet snapshot from the projection plus read-only git."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from cursorfleet.adapters.cursor.kit_probe import probe_hooks_kit
+from cursorfleet.git.collector import DEFAULT_STALE_AFTER_HOURS, GitSnapshot, collect
+from cursorfleet.git.runner import NotAGitRepo
+from cursorfleet.state.artifact_scan import DEFAULT_WORK_DIR, ArtifactScanner
+from cursorfleet.state.context import RepoContext, parse_now, resolve_repo
+from cursorfleet.state.indexer import Indexer, replay_session_state
+from cursorfleet.state.models import FleetView, SessionAcc
+from cursorfleet.state.reducer import snapshot
+from cursorfleet.state.run_builder import build_active_run, pick_primary_task
+from cursorfleet.state.run_store import list_runs
+from cursorfleet.state.spool_read import Corruption, list_spool_files
+from cursorfleet.state.status_doc import (
+    STATUS_SCHEMA,
+    RunDoc,
+    StatusDoc,
+    build_status,
+    run_docs_from_snapshots,
+    worktree_activity,
+)
+
+
+def _safe(text: object) -> str:
+    """Make untrusted strings safe for a terminal (no control or bidi characters)."""
+    return "".join(c if c.isprintable() else "?" for c in str(text))
+
+
+def _load(ctx: RepoContext) -> tuple[dict[str, SessionAcc], Corruption, int, str]:
+    """Return (sessions, corruption, spool file count, source)."""
+    files = len(list_spool_files(ctx.paths))
+    if files == 0:
+        return {}, Corruption(), 0, "none"
+    indexer = Indexer(ctx.paths)
+    indexer.try_sync()  # another indexer may be running; then we just read its projection
+    sessions = indexer.load_sessions()
+    if sessions:
+        return sessions, indexer.corruption(), files, "projection"
+    replayed, corruption, _n = replay_session_state(ctx.paths)
+    return replayed, corruption, files, "replay"
+
+
+def build(ctx: RepoContext, *, now: datetime, stale_after_s: int, with_git: bool) -> StatusDoc:
+    sessions, corruption, files, source = _load(ctx)
+    fleet = snapshot(sessions, now=now, stale_after_s=stale_after_s)
+    git: GitSnapshot | None = None
+    if with_git:
+        git = collect(
+            ctx.top_level or ctx.common_dir,
+            now=now,
+            stale_after_hours=DEFAULT_STALE_AFTER_HOURS,
+            activity=worktree_activity(sessions),
+        )
+    repo_root = ctx.top_level or ctx.common_dir
+    run_docs = _status_runs(
+        ctx=ctx,
+        sessions=sessions,
+        fleet=fleet,
+        now=now,
+        stale_after_s=stale_after_s,
+        repo_root=repo_root,
+    )
+    return build_status(
+        now=now,
+        fleet=fleet,
+        git=git,
+        common_dir=ctx.common_dir,
+        runtime_dir=ctx.paths.root,
+        corruption=corruption,
+        spool_files=files,
+        source=source,
+        hooks_kit=probe_hooks_kit(repo_root).state,
+        runs=run_docs or None,
+    )
+
+
+def _status_runs(  # noqa: PLR0913
+    *,
+    ctx: RepoContext,
+    sessions: dict[str, SessionAcc],
+    fleet: FleetView,
+    now: datetime,
+    stale_after_s: int,
+    repo_root: str,
+) -> list[RunDoc]:
+    session_views = {s.session_id: s for s in fleet.sessions}
+    scan = ArtifactScanner(DEFAULT_WORK_DIR).scan([repo_root])
+    records = scan.records
+    snapshots = []
+    for meta in sorted(
+        (r for r in list_runs(ctx.paths.root) if not r.archived),
+        key=lambda r: r.created_at,
+        reverse=True,
+    ):
+        snapshots.append(
+            build_active_run(
+                task_slug=meta.task_slug,
+                run_id=meta.run_id,
+                sessions=sessions,
+                session_views=session_views,
+                records=records,
+                linked_session_ids=frozenset(meta.session_ids),
+                now=now,
+                stale_after_s=stale_after_s,
+            )
+        )
+    if not snapshots:
+        task = pick_primary_task(records, now=now)
+        if task is None and not session_views:
+            return []
+        slug = task or "unscoped"
+        snapshots.append(
+            build_active_run(
+                task_slug=slug,
+                run_id=f"inferred:{slug}",
+                sessions=sessions,
+                session_views=session_views,
+                records=records,
+                linked_session_ids=frozenset(),
+                now=now,
+                stale_after_s=stale_after_s,
+            )
+        )
+    docs: list[RunDoc] = run_docs_from_snapshots(snapshots)
+    return docs
+
+
+def _render_text(doc: StatusDoc) -> str:
+    lines = [
+        f"CursorFleet status  ({doc.generated_at.isoformat()})",
+        f"telemetry: {doc.telemetry.state} | sessions {doc.telemetry.sessions} | "
+        f"events {doc.telemetry.events} | token budget: {doc.limits.token_budget}",
+    ]
+    lines.extend(f"note: {_safe(n)}" for n in doc.telemetry.notes)
+    lines.append("")
+    lines.append("SESSIONS")
+    if not doc.sessions:
+        awaiting = any("hooks installed" in n for n in doc.telemetry.notes)
+        hint = "await Cursor session" if awaiting else "no hook telemetry"
+        lines.append(f"  (none: {hint})")
+    for s in doc.sessions:
+        lines.append(
+            f"  {_safe(s.session_id)}  lane={s.lane}  tools={s.tool_call_count}  "
+            f"compactions={s.compactions}  elapsed={s.elapsed_s:.0f}s  events={s.event_count}"
+        )
+        for a in s.agents:
+            lines.append(
+                f"    - {_safe(a.key)}  lane={a.lane} ({a.lane_basis})  "
+                f"attribution={a.attribution}  tools={a.tool_call_count}"
+            )
+    lines.append("")
+    lines.append("WORKTREES")
+    if not doc.worktrees:
+        lines.append(f"  (none: {_safe(doc.git.error or 'git disabled')})")
+    for w in doc.worktrees:
+        marks = ",".join(w.stale_reasons)
+        sync = "" if w.ahead is None else f" +{w.ahead}/-{w.behind}"
+        lines.append(
+            f"  {_safe(w.path)}  [{_safe(w.branch or 'detached')}]  "
+            f"dirty={w.dirty_count if w.dirty_count is not None else '?'}{sync}  "
+            f"lane={w.lane}  telemetry={w.telemetry}" + (f"  STALE({marks})" if marks else "")
+        )
+    return "\n".join(lines)
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("status")
+    def status(
+        json_output: Annotated[bool, typer.Option("--json", help="Stable JSON output.")] = False,
+        repo: Annotated[
+            Path, typer.Option("--repo", help="Directory inside the git repo (default: cwd).")
+        ] = Path(),
+        stale_after_minutes: Annotated[
+            int, typer.Option("--stale-after-minutes", min=1, help="Silence before stale_offline.")
+        ] = 15,
+        no_git: Annotated[bool, typer.Option("--no-git", help="Skip the git collector.")] = False,
+        now: Annotated[
+            str | None, typer.Option("--now", hidden=True, help="ISO-8601 clock for tests.")
+        ] = None,
+    ) -> None:
+        """Show the fleet: sessions, agents, lanes and worktrees. Read-only; no network."""
+        try:
+            clock = parse_now(now)
+        except ValueError as exc:
+            typer.echo(f"error: {exc}", err=True)
+            raise typer.Exit(2) from exc
+        try:
+            ctx = resolve_repo(repo)
+        except NotAGitRepo as exc:
+            if json_output:
+                typer.echo(
+                    json.dumps({"schema": STATUS_SCHEMA, "error": {"code": "not_a_git_repo"}})
+                )
+            else:
+                typer.echo(f"error: {_safe(exc)}", err=True)
+            raise typer.Exit(1) from exc
+        doc = build(ctx, now=clock, stale_after_s=stale_after_minutes * 60, with_git=not no_git)
+        if json_output:
+            typer.echo(json.dumps(doc.to_json_dict(), indent=2, sort_keys=False))
+        else:
+            typer.echo(_render_text(doc))

cursorfleet/cli/commands/tui.py

@@ -0,0 +1,47 @@
+"""``cursorfleet tui``: the Textual dashboard (read-only; no network)."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+DEFAULT_REFRESH_S = 2.0
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("tui")
+    def tui(
+        path: Annotated[
+            Path, typer.Option("--path", help="A directory inside the git repo (default: cwd).")
+        ] = Path(),
+        refresh: Annotated[
+            float,
+            typer.Option(
+                "--refresh", min=0.25, max=60.0, help="Seconds between re-reads of the spool."
+            ),
+        ] = DEFAULT_REFRESH_S,
+        no_git: Annotated[
+            bool, typer.Option("--no-git", help="Do not run the read-only git collector.")
+        ] = False,
+        no_watch: Annotated[
+            bool, typer.Option("--no-watch", help="Poll only; ignore watchfiles if installed.")
+        ] = False,
+    ) -> None:
+        """Open the dashboard: workflow lanes, agents, timeline, worktrees and gates.
+
+        Observe-only: it reads the SQLite projection and read-only git state, never fetches,
+        never enforces anything and never shows prompts, thinking or file contents.
+        """
+        if not (sys.stdin.isatty() and sys.stdout.isatty()):
+            typer.echo(
+                "error: `cursorfleet tui` needs an interactive terminal. "
+                "Use `cursorfleet status` (or `status --json`) in scripts.",
+                err=True,
+            )
+            raise typer.Exit(2)
+        from cursorfleet.tui.app import build_app  # noqa: PLC0415 - lazy: keeps --help fast
+
+        build_app(path.resolve(), refresh_s=refresh, with_git=not no_git, watch=not no_watch).run()

cursorfleet/cli/commands/uninstall.py

@@ -0,0 +1,73 @@
+"""``cursorfleet uninstall``: remove exactly what the install lockfile recorded."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from cursorfleet.adapters.cursor import installer
+from cursorfleet.adapters.cursor.fsutil import UnsafePathError, safe_text
+from cursorfleet.cli.commands._common import fail, show_plan, workspace_root
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("uninstall")
+    def uninstall(
+        dry_run: Annotated[
+            bool, typer.Option("--dry-run", help="Print the diff and write nothing.")
+        ] = False,
+        yes: Annotated[
+            bool, typer.Option("--yes", "-y", help="Skip the prompt (the diff is still printed).")
+        ] = False,
+        force: Annotated[
+            bool,
+            typer.Option("--force", help="Also remove installed items that were modified since."),
+        ] = False,
+        path: Annotated[
+            Path, typer.Option("--path", help="Repository root (default: current directory).")
+        ] = Path(),
+    ) -> None:
+        """Remove the files, AGENTS.md blocks and hook entries CursorFleet installed.
+
+        Only items listed in .cursorfleet/install.lock.json are touched, and only if
+        they still match their recorded hash. Modified items are reported and skipped
+        (unless --force). Your own hooks and AGENTS.md content are left as they were.
+        """
+        root = workspace_root(path, command="uninstall")
+        plan = installer.build_uninstall_plan(root, force=force)
+        if plan.conflicts:
+            typer.echo("Cannot uninstall (nothing was written):", err=True)
+            for conflict in plan.conflicts:
+                typer.echo(f"  - {safe_text(conflict)}", err=True)
+            raise typer.Exit(1)
+        if plan.noop and not plan.drift:
+            for note in plan.notes:
+                typer.echo(safe_text(note))
+            if not plan.notes:
+                typer.echo("Nothing to remove.")
+            return
+        if not plan.noop:
+            show_plan(plan)
+        for item in plan.drift:
+            typer.echo(f"drift: {safe_text(item)}", err=True)
+        if dry_run:
+            typer.echo("\nDry run: no files were written.")
+            raise typer.Exit(1 if plan.drift else 0)
+        if not plan.noop:
+            if not yes and not typer.confirm("\nApply these changes?", default=False):
+                typer.echo("Aborted; nothing was written.")
+                raise typer.Exit(1)
+            try:
+                installer.apply_plan(plan)
+            except (OSError, UnsafePathError) as exc:
+                raise fail(f"error while writing: {exc}") from exc
+        if plan.drift:
+            typer.echo(
+                "\nUninstalled everything that still matched. Drifted items remain and stay "
+                "listed in the lockfile; fix them or re-run with --force.",
+                err=True,
+            )
+            raise typer.Exit(1)
+        typer.echo("\nUninstalled.")

cursorfleet/cli/commands/validate.py

@@ -0,0 +1,69 @@
+"""``cursorfleet validate``: config, roster, generated kit, rules and artifacts."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from cursorfleet.adapters.cursor.fsutil import safe_text
+from cursorfleet.adapters.cursor.validation import Finding, validate_workspace
+from cursorfleet.cli.commands._resolution import (
+    build_resolution,
+    render_resolution_text,
+    resolution_as_dict,
+)
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("validate")
+    def validate(
+        json_output: Annotated[
+            bool, typer.Option("--json", help="Machine-readable output.")
+        ] = False,
+        path: Annotated[
+            Path, typer.Option("--path", help="Directory inside the git repo (default: current).")
+        ] = Path(),
+    ) -> None:
+        """Validate .cursorfleet config and roster, the generated kit and work artifacts.
+
+        Exit code 1 if any error is found; warnings do not fail the command.
+        """
+        resolution = build_resolution(path)
+        root = Path(resolution.top_level) if resolution.top_level else path.expanduser().resolve()
+        findings, stats = validate_workspace(root)
+        if resolution.status == "fail":
+            findings.insert(
+                0,
+                Finding(
+                    "error",
+                    "repo.resolution",
+                    resolution.reason,
+                    hint="doctor and validate never walk past an inner Git boundary "
+                    "and never write.",
+                ),
+            )
+        errors = sum(1 for f in findings if f.severity == "error")
+        warnings = len(findings) - errors
+        if json_output:
+            payload = {
+                "schema": "cursorfleet.validate/1",
+                "ok": errors == 0,
+                "counts": {"error": errors, "warning": warnings},
+                "stats": stats,
+                "resolution": resolution_as_dict(resolution),
+                "findings": [f.as_dict() for f in findings],
+            }
+            typer.echo(json.dumps(payload, indent=2))
+        else:
+            typer.echo(render_resolution_text(resolution))
+            for f in findings:
+                where = f" {safe_text(f.path)}" if f.path else ""
+                typer.echo(f"[{f.severity}] {f.code}{where}: {safe_text(f.message)}")
+                if f.hint:
+                    typer.echo(f"        fix: {safe_text(f.hint)}")
+            typer.echo(f"{errors} error(s), {warnings} warning(s)")
+        if errors:
+            raise typer.Exit(1)

cursorfleet/cli/main.py

@@ -0,0 +1,81 @@
+"""CursorFleet CLI entry point.
+
+Command registration pattern
+----------------------------
+Each command group lives in its own module under ``cursorfleet.cli.commands``
+and exposes ``register(app: typer.Typer) -> None``. Modules are discovered and
+imported by :func:`register_commands` below, so adding a command group means
+adding one new file and never editing this one (no merge conflicts between
+phases). Modules are loaded in alphabetical order for deterministic help
+output.
+
+Example (``cursorfleet/cli/commands/doctor.py``)::
+
+    import typer
+
+    def register(app: typer.Typer) -> None:
+        @app.command()
+        def doctor() -> None:
+            ...
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+
+import typer
+
+from cursorfleet import __version__
+from cursorfleet.cli import commands as _commands_pkg
+
+app = typer.Typer(
+    name="cursorfleet",
+    help="A local TUI and workflow harness for Cursor agent teams.",
+    no_args_is_help=True,
+    add_completion=False,
+    # An unexpected error must not dump local variables (paths, config text, spool data)
+    # into a pasted traceback (security review SR-08).
+    pretty_exceptions_show_locals=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"cursorfleet {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+) -> None:
+    """A local TUI and workflow harness for Cursor agent teams."""
+
+
+def register_commands(target: typer.Typer) -> None:
+    """Import every module in ``cursorfleet.cli.commands`` and call its ``register``."""
+    for info in sorted(pkgutil.iter_modules(_commands_pkg.__path__), key=lambda m: m.name):
+        if info.name.startswith("_"):
+            continue
+        module = importlib.import_module(f"{_commands_pkg.__name__}.{info.name}")
+        register = getattr(module, "register", None)
+        if callable(register):
+            register(target)
+
+
+register_commands(app)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

cursorfleet/config/__init__.py

@@ -0,0 +1,44 @@
+"""Configuration and roster models.
+
+Importing this package is cheap; models (Pydantic) are re-exported lazily
+(PEP 562). Import from ``cursorfleet.config.models`` / ``.roster`` / ``.io``
+for explicit, eager access.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from cursorfleet.config.io import loads_config, loads_roster
+    from cursorfleet.config.models import FleetConfig
+    from cursorfleet.config.roster import AgentSpec, CoordinatorSpec, Roster, default_roster
+
+_LAZY = {
+    "FleetConfig": "cursorfleet.config.models",
+    "AgentSpec": "cursorfleet.config.roster",
+    "CoordinatorSpec": "cursorfleet.config.roster",
+    "Roster": "cursorfleet.config.roster",
+    "default_roster": "cursorfleet.config.roster",
+    "loads_config": "cursorfleet.config.io",
+    "loads_roster": "cursorfleet.config.io",
+}
+
+__all__ = [
+    "AgentSpec",
+    "CoordinatorSpec",
+    "FleetConfig",
+    "Roster",
+    "default_roster",
+    "loads_config",
+    "loads_roster",
+]
+
+
+def __getattr__(name: str) -> Any:
+    module = _LAZY.get(name)
+    if module is None:
+        msg = f"module {__name__!r} has no attribute {name!r}"
+        raise AttributeError(msg)
+    return getattr(import_module(module), name)

cursorfleet/config/io.py

@@ -0,0 +1,27 @@
+"""Parse ``config.toml`` / ``roster.toml`` text into models. Size-capped, stdlib TOML."""
+
+from __future__ import annotations
+
+import tomllib
+
+from cursorfleet.config.models import FleetConfig
+from cursorfleet.config.roster import Roster
+
+MAX_TOML_BYTES = 256 * 1024
+
+
+def _parse(text: str) -> dict[str, object]:
+    if len(text.encode("utf-8")) > MAX_TOML_BYTES:
+        msg = f"TOML input exceeds {MAX_TOML_BYTES} bytes"
+        raise ValueError(msg)
+    return tomllib.loads(text)
+
+
+def loads_config(text: str) -> FleetConfig:
+    """Parse and validate ``config.toml`` text. Raises ValueError subclasses on any problem."""
+    return FleetConfig.model_validate(_parse(text))
+
+
+def loads_roster(text: str) -> Roster:
+    """Parse and validate ``roster.toml`` text. Raises ValueError subclasses on any problem."""
+    return Roster.model_validate(_parse(text))