cursorfleet 0.1.0__py3-none-any.whl

cursorfleet/cli/commands/events.py

@@ -0,0 +1,197 @@
+"""``cursorfleet events purge`` and ``events export --sanitized`` (docs/privacy.md)."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from pydantic import ValidationError
+
+from cursorfleet.adapters.cursor.fsutil import safe_text
+from cursorfleet.config.io import loads_config
+from cursorfleet.events.models import Event
+from cursorfleet.git.runner import NotAGitRepo
+from cursorfleet.state.context import RepoContext, parse_now, resolve_repo
+from cursorfleet.state.indexer import Indexer, IndexerBusy
+from cursorfleet.state.reducer import dedupe_and_sort
+from cursorfleet.state.retention import (
+    DEFAULT_MAX_AGE_DAYS,
+    DEFAULT_MAX_SESSION_MB,
+    PurgePlan,
+    apply_plan,
+    parse_duration,
+    plan_purge,
+)
+from cursorfleet.state.spool_read import read_all
+
+RepoOption = Annotated[
+    Path, typer.Option("--repo", help="Directory inside the git repo (default: cwd).")
+]
+
+
+def _retention(ctx: RepoContext) -> tuple[int, int]:
+    """Configured (max_age_days, max_session_mb); defaults if absent or invalid."""
+    if ctx.top_level is None:
+        return DEFAULT_MAX_AGE_DAYS, DEFAULT_MAX_SESSION_MB
+    path = Path(ctx.top_level) / ".cursorfleet" / "config.toml"
+    try:
+        config = loads_config(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return DEFAULT_MAX_AGE_DAYS, DEFAULT_MAX_SESSION_MB
+    except (OSError, ValueError) as exc:
+        typer.echo(
+            f"warning: ignoring unreadable .cursorfleet/config.toml ({exc.__class__.__name__})",
+            err=True,
+        )
+        return DEFAULT_MAX_AGE_DAYS, DEFAULT_MAX_SESSION_MB
+    return config.retention.max_age_days, config.retention.max_session_mb
+
+
+def _describe(plan: PurgePlan) -> str:
+    extras = []
+    if plan.remove_projection:
+        extras.append("projection")
+    if plan.rotate_key:
+        extras.append("hashing key (rotated)")
+    if plan.remove_quarantine:
+        extras.append("quarantine")
+    tail = f"; also: {', '.join(extras)}" if extras else ""
+    return f"{plan.sessions} session(s), {len(plan.files)} file(s), {plan.file_bytes} byte(s){tail}"
+
+
+def purge(  # noqa: PLR0913
+    *,
+    older_than: Annotated[
+        str | None, typer.Option("--older-than", help="Duration such as 7d, 12h, 90m.")
+    ] = None,
+    session: Annotated[str | None, typer.Option("--session", help="One session id.")] = None,
+    all_: Annotated[
+        bool,
+        typer.Option("--all", help="Remove every spool file and the projection; rotate the key."),
+    ] = False,
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", help="Print counts, delete nothing.")
+    ] = False,
+    yes: Annotated[bool, typer.Option("--yes", "-y", help="Do not ask for confirmation.")] = False,
+    repo: RepoOption = Path(),
+    now: Annotated[str | None, typer.Option("--now", hidden=True)] = None,
+) -> None:
+    """Delete spool data under the git common dir. Never touches committed config.
+
+    With no selector the configured retention is applied (default 14 days or 50 MB per
+    session). Exit 0 on success (including nothing to purge), 1 on error, 2 on bad usage.
+    """
+    if sum([older_than is not None, session is not None, all_]) > 1:
+        typer.echo("error: use at most one of --older-than, --session, --all", err=True)
+        raise typer.Exit(2)
+    try:
+        delta = parse_duration(older_than) if older_than is not None else None
+        clock = parse_now(now)
+    except ValueError as exc:
+        typer.echo(f"error: {safe_text(str(exc))}", err=True)
+        raise typer.Exit(2) from exc
+    try:
+        ctx = resolve_repo(repo)
+    except NotAGitRepo as exc:
+        typer.echo(f"error: {safe_text(str(exc))}", err=True)
+        raise typer.Exit(1) from exc
+    max_age, max_mb = _retention(ctx)
+    plan = plan_purge(
+        ctx.paths,
+        now=clock,
+        older_than=delta,
+        session=session,
+        everything=all_,
+        max_age_days=max_age,
+        max_session_mb=max_mb,
+    )
+    if plan.empty:
+        typer.echo("nothing to purge")
+        return
+    if dry_run:
+        typer.echo(f"dry run: would remove {_describe(plan)}")
+        return
+    _confirm(yes, plan)
+    report = apply_plan(ctx.paths, plan)
+    if report.needs_reindex and not report.projection_removed:
+        try:
+            Indexer(ctx.paths).sync(rebuild=True)
+        except IndexerBusy:
+            typer.echo("note: another indexer is running; run `cursorfleet index --rebuild` later")
+    typer.echo(
+        f"removed {report.sessions} session(s), {report.files} file(s), {report.bytes} byte(s)"
+        + ("; projection removed" if report.projection_removed else "")
+        + ("; hashing key rotated" if report.key_rotated else "")
+    )
+    for problem in report.errors:
+        typer.echo(f"warning: {problem}", err=True)
+    if report.errors:
+        raise typer.Exit(1)
+
+
+def _confirm(yes: bool, plan: PurgePlan) -> None:
+    if yes:
+        return
+    if not sys.stdin.isatty():
+        typer.echo("error: refusing to delete without --yes when not interactive", err=True)
+        raise typer.Exit(2)
+    if not typer.confirm(f"Remove {_describe(plan)}?", default=False):
+        typer.echo("aborted")
+        raise typer.Exit(1)
+
+
+def export(
+    *,
+    sanitized: Annotated[
+        bool, typer.Option("--sanitized", help="Required: export only re-validated events.")
+    ] = False,
+    session: Annotated[str | None, typer.Option("--session")] = None,
+    output: Annotated[Path | None, typer.Option("--output", "-o")] = None,
+    repo: RepoOption = Path(),
+) -> None:
+    """Export spool events as JSON Lines after re-validating each one with the Event model.
+
+    Events are de-duplicated and ordered by (ts, event_id). Invalid or corrupt lines are
+    skipped and counted on stderr. Check branch names and paths before sharing.
+    """
+    if not sanitized:
+        typer.echo("error: only --sanitized export exists; raw export is not offered", err=True)
+        raise typer.Exit(2)
+    try:
+        ctx = resolve_repo(repo)
+    except NotAGitRepo as exc:
+        typer.echo(f"error: {safe_text(str(exc))}", err=True)
+        raise typer.Exit(1) from exc
+    spooled, corruption, _files = read_all(ctx.paths, session)
+    lines: list[str] = []
+    rejected = 0
+    for event in dedupe_and_sort(spooled):
+        dumped = event.model_dump_json(exclude_none=True)
+        try:
+            Event.model_validate(json.loads(dumped))  # re-validate the exact bytes we emit
+        except (ValidationError, ValueError):
+            rejected += 1
+            continue
+        lines.append(dumped)
+    text = "".join(line + "\n" for line in lines)
+    if output is None:
+        sys.stdout.write(text)
+    else:
+        with output.open("w", encoding="utf-8", newline="\n") as handle:
+            handle.write(text)
+    skipped = corruption.total + rejected
+    typer.echo(f"exported {len(lines)} event(s); skipped {skipped} corrupt/invalid", err=True)
+
+
+def register(app: typer.Typer) -> None:
+    events = typer.Typer(
+        name="events",
+        help="Inspect, export and purge the local event spool.",
+        no_args_is_help=True,
+    )
+    events.command("purge")(purge)
+    events.command("export")(export)
+    app.add_typer(events, name="events")

cursorfleet/cli/commands/index.py

@@ -0,0 +1,55 @@
+"""``cursorfleet index [--rebuild]``: run the single-writer indexer once."""
+
+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.git.runner import NotAGitRepo
+from cursorfleet.state.context import resolve_repo
+from cursorfleet.state.indexer import Indexer, IndexerBusy
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("index")
+    def index(
+        rebuild: Annotated[
+            bool,
+            typer.Option("--rebuild", help="Delete the projection and rebuild from the spool."),
+        ] = False,
+        json_output: Annotated[bool, typer.Option("--json")] = False,
+        repo: Annotated[Path, typer.Option("--repo")] = Path(),
+    ) -> None:
+        """Tail the spool into the SQLite projection once (the projection is rebuildable)."""
+        try:
+            ctx = resolve_repo(repo)
+        except NotAGitRepo as exc:
+            typer.echo(f"error: {safe_text(str(exc))}", err=True)
+            raise typer.Exit(1) from exc
+        try:
+            stats = Indexer(ctx.paths).sync(rebuild=rebuild)
+        except IndexerBusy as exc:
+            typer.echo(f"error: {safe_text(str(exc))}", err=True)
+            raise typer.Exit(1) from exc
+        summary = {
+            "files_scanned": stats.files_scanned,
+            "events_read": stats.events_read,
+            "events_new": stats.events_new,
+            "sessions_updated": stats.sessions_updated,
+            "sessions_rebuilt": stats.sessions_rebuilt,
+            "sessions_pruned": stats.sessions_pruned,
+            "db_recovered": stats.db_recovered,
+            "corruption": stats.corruption.to_dict(),
+        }
+        if json_output:
+            typer.echo(json.dumps({"schema": "cursorfleet.index/1", **summary}, indent=2))
+        else:
+            typer.echo(
+                f"indexed {stats.events_new} new event(s) from {stats.files_scanned} file(s); "
+                f"{stats.sessions_updated} updated, {stats.sessions_rebuilt} rebuilt, "
+                f"{stats.corruption.total} corrupt/skipped"
+            )

cursorfleet/cli/commands/init.py

@@ -0,0 +1,71 @@
+"""``cursorfleet init --cursor``: install the Cursor kit with a diff and confirmation."""
+
+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.adapters.cursor.hooksjson import HOOK_COMMAND
+from cursorfleet.cli.commands._common import fail, show_plan, workspace_root
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("init")
+    def init(
+        cursor: Annotated[
+            bool, typer.Option("--cursor", help="Install the kit for Cursor (the only target).")
+        ] = False,
+        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,
+        path: Annotated[
+            Path,
+            typer.Option("--path", help="Repository root (default: current directory)."),
+        ] = Path(),
+    ) -> None:
+        """Generate subagents, skills, rules, AGENTS.md blocks and observe-only hooks.
+
+        Prints an exact diff of every file (including .cursor/hooks.json), then asks for
+        confirmation. Existing hooks and AGENTS.md content are preserved. Undo with
+        `cursorfleet uninstall`.
+        """
+        if not cursor:
+            raise fail("error: choose a target, e.g. `cursorfleet init --cursor`.", 2)
+        root = workspace_root(path, command="init")
+        plan = installer.build_install_plan(root)
+        if plan.conflicts:
+            typer.echo(
+                "Cannot install; resolve these conflicts first (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:
+            typer.echo("Already up to date: nothing to do.")
+            return
+        show_plan(plan)
+        if plan.touches_hooks:
+            typer.echo(
+                f"\nWARNING: this edits .cursor/hooks.json. Cursor runs `{HOOK_COMMAND}` on the "
+                "registered events (observe-only: it records sanitized metadata and always "
+                "exits 0). Review the hooks.json diff above."
+            )
+        if dry_run:
+            typer.echo("\nDry run: no files were written.")
+            return
+        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}\nRun `cursorfleet doctor` to inspect.") from exc
+        typer.echo("\nInstalled. Next: `cursorfleet doctor`. Undo with `cursorfleet uninstall`.")

cursorfleet/cli/commands/migrate.py

@@ -0,0 +1,43 @@
+"""``cursorfleet migrate`` — offline migrations (artifacts, etc.)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from cursorfleet.state.artifact_scan import DEFAULT_WORK_DIR, ArtifactScanner
+from cursorfleet.workflow.artifacts import ARTIFACT_SCHEMA, ARTIFACT_SCHEMA_LEGACY
+
+migrate_app = typer.Typer(name="migrate", help="Inspect or migrate local CursorFleet data.")
+
+
+def register(app: typer.Typer) -> None:
+    app.add_typer(migrate_app)
+
+    @migrate_app.command("artifacts")
+    def artifacts(
+        path: Annotated[Path, typer.Option("--path", help="Repository root.")] = Path(),
+        dry_run: Annotated[
+            bool, typer.Option("--dry-run", help="Report only; write nothing.")
+        ] = True,
+        yes: Annotated[
+            bool, typer.Option("--yes", help="Apply migrations (not implemented).")
+        ] = False,
+    ) -> None:
+        """List legacy YAML artifacts vs TOML 0.1 (dry-run by default)."""
+        root = path.resolve()
+        work = root / DEFAULT_WORK_DIR
+        if not work.is_dir():
+            typer.echo("no work directory")
+            return
+        scan = ArtifactScanner(str(work))
+        result = scan.scan([str(root)])
+        typer.echo(f"valid artifacts: {len(result.records)} issues: {len(result.issues)}")
+        typer.echo(f"target schema: {ARTIFACT_SCHEMA}")
+        typer.echo(f"legacy accepted: {ARTIFACT_SCHEMA_LEGACY}")
+        if dry_run or not yes:
+            typer.echo("dry-run: no files changed (TOML rewrite is manual or future --yes)")
+            return
+        typer.echo("nothing to apply yet")

cursorfleet/cli/commands/replay.py

@@ -0,0 +1,76 @@
+"""``cursorfleet replay <session-id> [--json]``: rebuild from the spool, prove determinism."""
+
+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.git.runner import NotAGitRepo
+from cursorfleet.state.context import parse_now, resolve_repo
+from cursorfleet.state.reducer import digest, reduce_events, session_view
+from cursorfleet.state.spool_read import read_all
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("replay")
+    def replay(
+        session_id: Annotated[str, typer.Argument(help="Cursor conversation/session id.")],
+        json_output: Annotated[
+            bool, typer.Option("--json", help="Machine-readable 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)] = 15,
+        now: Annotated[
+            str | None, typer.Option("--now", hidden=True, help="ISO-8601 clock for tests.")
+        ] = None,
+    ) -> None:
+        """Rebuild one session's state from the spool, twice, and check both runs agree.
+
+        Exit 0 if the two replays are identical, 1 if the session is unknown or the
+        replays differ (a bug), 2 on usage errors. Corrupt spool lines are counted, never fatal.
+        """
+        try:
+            clock = parse_now(now)
+        except ValueError as exc:
+            typer.echo(f"error: {safe_text(str(exc))}", err=True)
+            raise typer.Exit(2) from exc
+        try:
+            ctx = resolve_repo(repo)
+        except NotAGitRepo as exc:
+            typer.echo(f"error: {safe_text(str(exc))}", err=True)
+            raise typer.Exit(1) from exc
+        events_a, corruption, files = read_all(ctx.paths, session_id)
+        events_b, _c, _f = read_all(ctx.paths, session_id)
+        first = reduce_events(events_a).get(session_id)
+        second = reduce_events(reversed(events_b)).get(session_id)
+        if first is None or second is None:
+            typer.echo(f"error: no events for session {session_id!r} in the spool", err=True)
+            raise typer.Exit(1)
+        deterministic = digest(first) == digest(second)
+        view = session_view(first, clock, stale_after_minutes * 60)
+        if json_output:
+            payload = {
+                "schema": "cursorfleet.replay/1",
+                "session_id": session_id,
+                "deterministic": deterministic,
+                "digest": digest(first),
+                "spool_files": files,
+                "events": len(events_a),
+                "corruption": corruption.to_dict(),
+                "state": json.loads(view.model_dump_json()),
+            }
+            typer.echo(json.dumps(payload, indent=2))
+        else:
+            typer.echo(
+                f"session {session_id}: {len(events_a)} event(s) from {files} file(s); "
+                f"lane={view.lane}; corrupt/skipped={corruption.total}"
+            )
+            typer.echo(f"digest {digest(first)}  deterministic={str(deterministic).lower()}")
+        if not deterministic:
+            raise typer.Exit(1)

cursorfleet/cli/commands/run.py

@@ -0,0 +1,97 @@
+"""``cursorfleet run`` — observe-only run metadata (runtime dir only)."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from cursorfleet.git.runner import NotAGitRepo
+from cursorfleet.state.context import resolve_repo
+from cursorfleet.state.run_store import RunRecord, attach_session, list_runs, load_run, save_run
+
+run_app = typer.Typer(name="run", help="Local run bookkeeping (does not modify git or hooks).")
+
+
+def register(app: typer.Typer) -> None:
+    app.add_typer(run_app)
+
+    @run_app.command("start")
+    def start(
+        task: Annotated[
+            str, typer.Option("--task", help="Task slug under .cursorfleet/work/<task>/")
+        ],
+        path: Annotated[
+            Path, typer.Option("--path", help="Repository root or inside it.")
+        ] = Path(),
+        run_id: Annotated[
+            str | None, typer.Option("--run-id", help="Optional stable id; default: random.")
+        ] = None,
+    ) -> None:
+        try:
+            ctx = resolve_repo(path.resolve())
+        except NotAGitRepo:
+            typer.echo("error: not a git repository", err=True)
+            raise typer.Exit(2) from None
+        rid = run_id or f"run-{uuid.uuid4().hex[:12]}"
+        record = RunRecord(
+            run_id=rid,
+            task_slug=task,
+            created_at=datetime.now(tz=UTC).isoformat(),
+        )
+        save_run(ctx.paths.root, record)
+        typer.echo(rid)
+
+    @run_app.command("list")
+    def list_cmd(
+        path: Annotated[Path, typer.Option("--path")] = Path(),
+    ) -> None:
+        try:
+            ctx = resolve_repo(path.resolve())
+        except NotAGitRepo:
+            typer.echo("error: not a git repository", err=True)
+            raise typer.Exit(2) from None
+        rows = list_runs(ctx.paths.root)
+        if not rows:
+            typer.echo("no runs")
+            return
+        for row in rows:
+            flag = "archived" if row.archived else "active"
+            typer.echo(f"{row.run_id}\t{row.task_slug}\t{flag}\tsessions={len(row.session_ids)}")
+
+    @run_app.command("attach")
+    def attach(
+        run_id: Annotated[str, typer.Argument(help="Run id from run start")],
+        session: Annotated[str, typer.Option("--session", help="Cursor session_id to attach.")],
+        path: Annotated[Path, typer.Option("--path")] = Path(),
+    ) -> None:
+        try:
+            ctx = resolve_repo(path.resolve())
+        except NotAGitRepo:
+            typer.echo("error: not a git repository", err=True)
+            raise typer.Exit(2) from None
+        if not attach_session(ctx.paths.root, run_id, session):
+            typer.echo("attach failed (unknown or archived run)", err=True)
+            raise typer.Exit(1)
+        typer.echo("attached")
+
+    @run_app.command("archive")
+    def archive(
+        run_id: Annotated[str, typer.Argument()],
+        path: Annotated[Path, typer.Option("--path")] = Path(),
+    ) -> None:
+        try:
+            ctx = resolve_repo(path.resolve())
+        except NotAGitRepo:
+            typer.echo("error: not a git repository", err=True)
+            raise typer.Exit(2) from None
+        record = load_run(ctx.paths.root, run_id)
+        if record is None:
+            typer.echo("run not found", err=True)
+            raise typer.Exit(1)
+        record.archived = True
+        save_run(ctx.paths.root, record)
+        typer.echo("archived")