cursorfleet 0.1.0__py3-none-any.whl

cursorfleet/adapters/cursor/kit.py

@@ -0,0 +1,210 @@
+"""Render the Cursor kit (subagents, skills, rules, AGENTS.md blocks) from the roster.
+
+Pure and deterministic: the same roster, config and templates always yield the
+same bytes (no timestamps, no versions, no environment). Nothing here touches
+the filesystem except reading packaged templates.
+
+Frontmatter written for subagents is limited to ``name``, ``description``,
+``model``, ``readonly`` and ``is_background`` (ADR 0001, A7). ``capability_notes``
+in the roster are documentation only and are never rendered as if enforced.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+from cursorfleet.adapters.cursor import blocks
+from cursorfleet.adapters.cursor.templates import read_template, render
+from cursorfleet.config.models import FleetConfig
+from cursorfleet.config.roster import AgentSpec, Role, Roster
+from cursorfleet.workflow.frontmatter import yaml_string
+
+ROOT_AGENTS_MD = "AGENTS.md"
+CONFIG_PATH = ".cursorfleet/config.toml"
+ROSTER_PATH = ".cursorfleet/roster.toml"
+LOCK_PATH = ".cursorfleet/install.lock.json"
+HOOKS_PATH = ".cursor/hooks.json"
+AGENTS_DIR = ".cursor/agents"
+RULES_DIR = ".cursor/rules"
+SKILLS_DIR = ".cursor/skills"
+COORDINATOR_SKILL = "cursorfleet-coordinator"
+ARTIFACTS_SKILL = "cursorfleet-artifacts"
+SUBAGENT_FRONTMATTER_KEYS: tuple[str, ...] = (
+    "name",
+    "description",
+    "model",
+    "readonly",
+    "is_background",
+)
+_COORDINATOR_SUFFIX = (
+    " Use for planned, reviewed or parallel multi-agent changes; skip it for small "
+    "single-file edits."
+)
+
+
+@dataclass(frozen=True)
+class Kit:
+    """Everything ``init`` generates, keyed by workspace-relative POSIX path."""
+
+    files: dict[str, str] = field(default_factory=dict)  # whole files CursorFleet owns
+    blocks: dict[str, str] = field(default_factory=dict)  # managed blocks in shared files
+
+
+def agent_file_path(roster: Roster, agent: AgentSpec) -> str:
+    return f"{AGENTS_DIR}/{roster.cursor_name(agent.id)}.md"
+
+
+def _first_name(roster: Roster, role: Role) -> str:
+    for agent in roster.enabled_agents():
+        if agent.role is role:
+            return f"`{roster.cursor_name(agent.id)}`"
+    return f"(no enabled {role.value} agent)"
+
+
+def _cell(text: str) -> str:
+    return " ".join(text.split()).replace("|", "\\|")
+
+
+def roster_table(roster: Roster) -> str:
+    rows = ["| Subagent | Role | Access | Use for |", "| --- | --- | --- | --- |"]
+    for agent in roster.enabled_agents():
+        access = "read-only" if agent.readonly else "can edit"
+        name = roster.cursor_name(agent.id)
+        rows.append(f"| `{name}` | {agent.role.value} | {access} | {_cell(agent.description)} |")
+    return "\n".join(rows)
+
+
+def _values(roster: Roster, config: FleetConfig, agent: AgentSpec | None) -> dict[str, str]:
+    values: dict[str, str] = {
+        "work_dir": config.work.dir,
+        "name_prefix": roster.name_prefix,
+        "roster_table": roster_table(roster),
+        "coordinator_description": yaml_string(
+            roster.coordinator.description.rstrip() + _COORDINATOR_SUFFIX
+        ),
+        "name": "",
+        "id": "",
+    }
+    for role in Role:
+        if role is not Role.COORDINATOR:
+            values[f"role.{role.value}"] = _first_name(roster, role)
+    if agent is not None:
+        values["name"] = f"`{roster.cursor_name(agent.id)}`"
+        values["id"] = agent.id
+    return values
+
+
+def render_agent(roster: Roster, config: FleetConfig, agent: AgentSpec) -> str:
+    """Render one ``.cursor/agents/<name>.md`` file (frontmatter limited to 5 keys)."""
+    name = roster.cursor_name(agent.id)
+    front = [
+        "---",
+        f"name: {name}",
+        f"description: {yaml_string(agent.description)}",
+        f"model: {yaml_string(agent.model) if agent.model != 'inherit' else 'inherit'}",
+        f"readonly: {'true' if agent.readonly else 'false'}",
+        f"is_background: {'true' if agent.is_background else 'false'}",
+        "---",
+        "",
+        "",
+    ]
+    body = render(read_template(f"agents/{agent.role.value}.md"), _values(roster, config, agent))
+    return "\n".join(front)[:-1] + body.rstrip("\n") + "\n"
+
+
+def _coordinator_body(roster: Roster, config: FleetConfig) -> str:
+    template = read_template(f"skills/{COORDINATOR_SKILL}/SKILL.md")
+    return render(template, _values(roster, config, None))
+
+
+def _skill_to_rule(skill_text: str, description: str) -> str:
+    """Turn the coordinator SKILL.md into an on-demand rule (same body, rule frontmatter)."""
+    body = skill_text.split("\n---\n", 1)[1].lstrip("\n")
+    front = f"---\ndescription: {description}\nalwaysApply: false\n---\n\n"
+    return front + body
+
+
+def build_kit(roster: Roster, config: FleetConfig) -> Kit:
+    """Build the full kit for ``roster`` and ``config``."""
+    files: dict[str, str] = {}
+    for agent in roster.enabled_agents():
+        files[agent_file_path(roster, agent)] = render_agent(roster, config, agent)
+
+    values = _values(roster, config, None)
+    files[f"{SKILLS_DIR}/{ARTIFACTS_SKILL}/SKILL.md"] = render(
+        read_template(f"skills/{ARTIFACTS_SKILL}/SKILL.md"), values
+    )
+    files[f"{RULES_DIR}/cursorfleet-core.mdc"] = render(
+        read_template("rules/cursorfleet-core.mdc"), values
+    )
+    files[f"{RULES_DIR}/cursorfleet-handoff.mdc"] = render(
+        read_template("rules/cursorfleet-handoff.mdc"), values
+    )
+    coordinator = roster.coordinator
+    if coordinator.enabled:
+        skill_text = _coordinator_body(roster, config)
+        if coordinator.delivery in {"skill", "both"}:
+            files[f"{SKILLS_DIR}/{COORDINATOR_SKILL}/SKILL.md"] = skill_text
+        if coordinator.delivery in {"rule", "both"}:
+            files[f"{RULES_DIR}/cursorfleet-coordinator.mdc"] = _skill_to_rule(
+                skill_text, values["coordinator_description"]
+            )
+
+    kit_blocks = {
+        ROOT_AGENTS_MD: blocks.make_block(render(read_template("agents-md/root.md"), values)),
+        f"{config.work.dir}/AGENTS.md": blocks.make_block(
+            render(read_template("agents-md/work.md"), values)
+        ),
+    }
+    return Kit(files=dict(sorted(files.items())), blocks=kit_blocks)
+
+
+# ---- seed files: written only if absent, then owned by the user -------------------------
+
+
+def seed_config_text() -> str:
+    return read_template("config/config.toml")
+
+
+def _toml_str(value: str) -> str:
+    return json.dumps(value, ensure_ascii=False)
+
+
+def _toml_value(value: object) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, str):
+        return _toml_str(value)
+    if isinstance(value, list):
+        if not value:
+            return "[]"
+        items = "".join(f"  {_toml_value(v)},\n" for v in value)
+        return f"[\n{items}]"
+    msg = f"unsupported TOML value: {type(value).__name__}"
+    raise TypeError(msg)
+
+
+def _toml_table(data: dict[str, object]) -> list[str]:
+    return [f"{key} = {_toml_value(value)}" for key, value in data.items()]
+
+
+def seed_roster_text(roster: Roster) -> str:
+    """Render ``roster`` as TOML (the roster has only scalars, string lists and 2 table kinds)."""
+    dumped = roster.model_dump(mode="json")
+    out = [
+        "# CursorFleet roster (committed; data only, never executed).",
+        "# Source of truth for the generated .cursor/agents/*.md files: edit this file,",
+        "# then run `cursorfleet init --cursor` again. `capability_notes` are documentation",
+        "# only; Cursor cannot enforce per-agent tools, paths or network, and v0.1 does not.",
+        f"schema_version = {_toml_str(dumped['schema_version'])}",
+        f"name_prefix = {_toml_str(dumped['name_prefix'])}",
+        "",
+        "[coordinator]",
+        *_toml_table(dumped["coordinator"]),
+    ]
+    for agent in dumped["agents"]:
+        out += ["", "[[agents]]", *_toml_table(agent)]
+    return "\n".join(out) + "\n"

cursorfleet/adapters/cursor/kit_probe.py

@@ -0,0 +1,54 @@
+"""Read-only probe: is the observe-only hook kit present in a workspace?"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+from cursorfleet.adapters.cursor.hooksjson import HOOK_COMMAND, effective_events
+from cursorfleet.adapters.cursor.kit import HOOKS_PATH, LOCK_PATH
+
+
+class HooksKitState(StrEnum):
+    """How much of ``cursorfleet init --cursor`` is visible on disk."""
+
+    MISSING = "missing"  # no lock and no project cursorfleet-hook entries
+    PARTIAL = "partial"  # lock or hooks alone, or a broken hooks.json
+    INSTALLED = "installed"  # lockfile plus cursorfleet-hook entries in project hooks.json
+
+
+@dataclass(frozen=True)
+class HooksKitProbe:
+    state: HooksKitState
+    lock_present: bool
+    project_hooks_path: str | None
+    cursorfleet_hook_entries: int
+
+
+def probe_hooks_kit(repo_root: str | None) -> HooksKitProbe:
+    """Never raises; safe for the TUI worker and ``status``."""
+    if not repo_root:
+        return HooksKitProbe(HooksKitState.MISSING, False, None, 0)
+    root = Path(repo_root)
+    lock_present = (root / LOCK_PATH).is_file()
+    hooks_path = root / HOOKS_PATH
+    entries = 0
+    project_hooks: str | None = None
+    if hooks_path.is_file():
+        project_hooks = HOOKS_PATH
+        try:
+            parsed = effective_events(hooks_path.read_text(encoding="utf-8"))
+        except OSError:
+            parsed = {}
+        for hook_entries in parsed.values():
+            for item in hook_entries:
+                if item.get("command") == HOOK_COMMAND:
+                    entries += 1
+    if lock_present and entries > 0:
+        state = HooksKitState.INSTALLED
+    elif lock_present or entries > 0:
+        state = HooksKitState.PARTIAL
+    else:
+        state = HooksKitState.MISSING
+    return HooksKitProbe(state, lock_present, project_hooks, entries)

cursorfleet/adapters/cursor/lock.py

@@ -0,0 +1,145 @@
+"""The install lockfile ``.cursorfleet/install.lock.json``.
+
+Records exactly what ``init`` wrote (paths, sha256, managed blocks, hook entries,
+directories it created) so ``uninstall`` removes only that and ``doctor`` can
+report drift. It contains no timestamps, so re-running ``init`` is a no-op.
+
+The lock is data from the repository and therefore untrusted: every path is
+validated against an allowlist of managed locations before any use.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from cursorfleet.adapters.cursor.hooksjson import JsonStyle
+from cursorfleet.adapters.cursor.kit import HOOKS_PATH, LOCK_PATH
+from cursorfleet.events.pathcheck import check_not_in_git_dir, check_relative_posix
+
+_STRICT = ConfigDict(extra="forbid", frozen=True)
+_FILE_PREFIXES = (".cursor/agents/", ".cursor/rules/", ".cursor/skills/", ".cursorfleet/")
+_SHA256 = r"^[0-9a-f]{64}$"
+MAX_LOCK_BYTES = 256 * 1024
+
+
+def is_managed_file_path(path: str) -> bool:
+    """True for paths CursorFleet may create as whole files."""
+    try:
+        check_not_in_git_dir(check_relative_posix(path))
+    except ValueError:
+        return False
+    return path.startswith(_FILE_PREFIXES) and path != LOCK_PATH
+
+
+def is_managed_block_path(path: str) -> bool:
+    """True for ``AGENTS.md`` files (root or nested) that may hold a managed block."""
+    try:
+        check_not_in_git_dir(check_relative_posix(path))
+    except ValueError:
+        return False
+    return path == "AGENTS.md" or path.endswith("/AGENTS.md")
+
+
+class LockFile(BaseModel):
+    model_config = _STRICT
+
+    path: str
+    sha256: str = Field(pattern=_SHA256)
+    kind: Literal["file", "seed"] = "file"  # seed = user-owned after creation (config, roster)
+    adopted: bool = False  # pre-existed with identical content; never removed
+
+    @field_validator("path")
+    @classmethod
+    def _path(cls, value: str) -> str:
+        if not is_managed_file_path(value):
+            msg = f"not a managed file location: {value!r}"
+            raise ValueError(msg)
+        return value
+
+
+class LockBlock(BaseModel):
+    model_config = _STRICT
+
+    path: str
+    sha256: str = Field(pattern=_SHA256)  # of the block text (LF-normalized)
+    prefix: str = Field(default="", max_length=4)  # separator inserted before the block
+    file_created: bool = False
+
+    @field_validator("path")
+    @classmethod
+    def _path(cls, value: str) -> str:
+        if not is_managed_block_path(value):
+            msg = f"not a managed AGENTS.md location: {value!r}"
+            raise ValueError(msg)
+        return value
+
+    @field_validator("prefix")
+    @classmethod
+    def _prefix(cls, value: str) -> str:
+        if value.replace("\r", "").replace("\n", "") != "":
+            msg = "prefix may only contain newlines"
+            raise ValueError(msg)
+        return value
+
+
+class LockHooks(BaseModel):
+    model_config = _STRICT
+
+    path: str = HOOKS_PATH
+    created: bool = False  # file did not exist before init
+    added_version: bool = False
+    added_hooks_key: bool = False
+    added_events: list[str] = Field(default_factory=list)
+    entries: dict[str, dict[str, Any]] = Field(default_factory=dict)
+    style: JsonStyle = Field(default_factory=JsonStyle)
+    installed_sha256: str = Field(pattern=_SHA256)
+    original_sha256: str | None = Field(default=None, pattern=_SHA256)
+    original_b64: str | None = Field(default=None, max_length=200_000)
+
+    @field_validator("path")
+    @classmethod
+    def _path(cls, value: str) -> str:
+        if value != HOOKS_PATH:
+            msg = "hooks path must be .cursor/hooks.json"
+            raise ValueError(msg)
+        return value
+
+
+class InstallLock(BaseModel):
+    model_config = _STRICT
+
+    lock_version: Literal["1"] = "1"
+    cursorfleet_version: str = Field(max_length=64)
+    files: list[LockFile] = Field(default_factory=list)
+    blocks: list[LockBlock] = Field(default_factory=list)
+    hooks: LockHooks | None = None
+    dirs_created: list[str] = Field(default_factory=list)
+
+    @field_validator("dirs_created")
+    @classmethod
+    def _dirs(cls, value: list[str]) -> list[str]:
+        for item in value:
+            check_not_in_git_dir(check_relative_posix(item))  # only empty dirs are ever removed
+        return value
+
+    def file_map(self) -> dict[str, LockFile]:
+        return {f.path: f for f in self.files}
+
+    def block_map(self) -> dict[str, LockBlock]:
+        return {b.path: b for b in self.blocks}
+
+
+def dumps_lock(lock: InstallLock) -> str:
+    data = lock.model_dump(mode="json")
+    return json.dumps(data, indent=2, ensure_ascii=False) + "\n"
+
+
+def loads_lock(text: str) -> InstallLock:
+    """Parse lock text. Raises ``ValueError`` (including pydantic's) on any problem."""
+    if len(text.encode("utf-8")) > MAX_LOCK_BYTES:
+        msg = "install lockfile is too large"
+        raise ValueError(msg)
+    return InstallLock.model_validate_json(text)

cursorfleet/adapters/cursor/templates.py

@@ -0,0 +1,60 @@
+"""Locate and render the ``templates/cursor`` kit templates.
+
+Installed wheels carry the templates as package data at
+``cursorfleet/_templates/cursor`` (hatch ``force-include``, see pyproject.toml).
+In a source checkout they live in ``<repo>/templates/cursor``. Both are read
+through :mod:`importlib.resources`-style traversables, so zip installs work too.
+
+Rendering is plain ``{{placeholder}}`` substitution with no logic; unknown or
+unfilled placeholders are errors, which keeps generated output deterministic.
+"""
+
+from __future__ import annotations
+
+import re
+from importlib import resources
+from importlib.resources.abc import Traversable
+from pathlib import Path
+
+_PLACEHOLDER = re.compile(r"\{\{([A-Za-z0-9_.]+)\}\}")
+
+
+class TemplateError(RuntimeError):
+    """A template is missing or references an unknown placeholder."""
+
+
+def templates_root() -> Traversable:
+    """Return the root of the cursor templates (packaged copy first, repo copy second)."""
+    packaged = resources.files("cursorfleet").joinpath("_templates", "cursor")
+    if packaged.is_dir():
+        return packaged
+    # src/cursorfleet/adapters/cursor/templates.py -> repository root is parents[4]
+    repo = Path(__file__).resolve().parents[4] / "templates" / "cursor"
+    if repo.is_dir():
+        return repo
+    msg = "CursorFleet templates not found (broken install?)"
+    raise TemplateError(msg)
+
+
+def read_template(rel: str) -> str:
+    """Read template ``rel`` (POSIX path under templates/cursor) as LF-normalized text."""
+    node = templates_root()
+    for part in rel.split("/"):
+        node = node.joinpath(part)
+    if not node.is_file():
+        msg = f"missing template: {rel}"
+        raise TemplateError(msg)
+    return node.read_text(encoding="utf-8").replace("\r\n", "\n")
+
+
+def render(template: str, values: dict[str, str]) -> str:
+    """Substitute ``{{key}}`` placeholders; raise on unknown keys."""
+
+    def repl(match: re.Match[str]) -> str:
+        key = match.group(1)
+        if key not in values:
+            msg = f"unknown template placeholder: {{{{{key}}}}}"
+            raise TemplateError(msg)
+        return values[key]
+
+    return _PLACEHOLDER.sub(repl, template)