koru 0.1.9__py3-none-any.whl

koru/__init__.py

@@ -0,0 +1,67 @@
+"""Koru loop automation package."""
+
+from .bootstrap import (
+    ImportReport,
+    ValidationError,
+    import_flat_pipeline,
+    load_flat_pipeline,
+    materialize_to_planfile,
+    validate_flat_pipeline,
+)
+from .context import build_context, render_markdown_handoff
+from .doctor import Check, DoctorReport, run_diagnostics
+from .init import InitReport, init_project
+from .loop import LoopReport, RunRecord, discover_repositories, run_closed_loop
+from .planfile_queue import (
+    LlmRunResult,
+    QueueLoopResult,
+    QueueRunResult,
+    run_next_planfile_task,
+    run_planfile_queue_loop,
+)
+from .policy import Policy, load_policy, policy_path, policy_violations
+from .run_log import RunLogWriter, open_run_log, open_run_log_eagerly
+from .runtime import (
+    ensure_runs_dir,
+    new_run_id,
+    planfile_dir,
+    runs_dir,
+    runtime_dir,
+)
+
+__all__ = [
+    "Check",
+    "DoctorReport",
+    "ImportReport",
+    "InitReport",
+    "LlmRunResult",
+    "LoopReport",
+    "Policy",
+    "QueueLoopResult",
+    "QueueRunResult",
+    "RunLogWriter",
+    "RunRecord",
+    "ValidationError",
+    "build_context",
+    "discover_repositories",
+    "ensure_runs_dir",
+    "import_flat_pipeline",
+    "init_project",
+    "load_flat_pipeline",
+    "load_policy",
+    "materialize_to_planfile",
+    "new_run_id",
+    "open_run_log",
+    "open_run_log_eagerly",
+    "planfile_dir",
+    "policy_path",
+    "policy_violations",
+    "render_markdown_handoff",
+    "run_diagnostics",
+    "run_closed_loop",
+    "run_next_planfile_task",
+    "run_planfile_queue_loop",
+    "runs_dir",
+    "runtime_dir",
+    "validate_flat_pipeline",
+]

koru/agents.py

@@ -0,0 +1,222 @@
+"""Detect and launch LLM/IDE agents available for a koru project."""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .runtime import runtime_dir
+from .semcod_tools import detect_semcod_tools
+
+
+@dataclass(frozen=True)
+class AgentOption:
+    id: str
+    label: str
+    available: bool
+    launchable: bool
+    command: str | None = None
+    reason: str = ""
+    project_hint: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "label": self.label,
+            "available": self.available,
+            "launchable": self.launchable,
+            "command": self.command,
+            "reason": self.reason,
+            "project_hint": self.project_hint,
+        }
+
+
+def _which(command: str) -> str | None:
+    return shutil.which(command)
+
+
+def _marker(project: Path, *parts: str) -> bool:
+    return (project.joinpath(*parts)).exists()
+
+
+def detect_agent_options(project: Path) -> list[AgentOption]:
+    """Return known LLM/IDE lanes ordered by koru preference."""
+    project = project.resolve()
+    windsurf_cmd = _which("windsurf")
+    cursor_cmd = _which("cursor")
+    claude_cmd = _which("claude")
+    aider_cmd = _which("aider")
+    codex_cmd = _which("codex")
+    openrouter_ready = bool(os.getenv("OPENROUTER_API_KEY"))
+
+    return [
+        AgentOption(
+            id="claude-code",
+            label="Claude Code",
+            available=bool(claude_cmd),
+            launchable=bool(claude_cmd),
+            command=claude_cmd,
+            reason=(
+                "Claude Code CLI detected in PATH."
+                if claude_cmd
+                else "Install Claude Code CLI to launch it from koru."
+            ),
+        ),
+        AgentOption(
+            id="codex",
+            label="Codex CLI",
+            available=bool(codex_cmd),
+            launchable=bool(codex_cmd),
+            command=codex_cmd,
+            reason="Codex CLI detected in PATH." if codex_cmd else "Codex CLI is not in PATH.",
+        ),
+        AgentOption(
+            id="cursor",
+            label="Cursor",
+            available=bool(cursor_cmd or _marker(project, ".cursor")),
+            launchable=bool(cursor_cmd),
+            command=cursor_cmd,
+            project_hint=_marker(project, ".cursor"),
+            reason=(
+                "Cursor CLI detected."
+                if cursor_cmd
+                else "Cursor project config detected; open the prompt in Cursor manually."
+            ),
+        ),
+        AgentOption(
+            id="windsurf",
+            label="Windsurf",
+            available=bool(windsurf_cmd or _marker(project, ".windsurf")),
+            launchable=bool(windsurf_cmd),
+            command=windsurf_cmd,
+            project_hint=_marker(project, ".windsurf"),
+            reason=(
+                "Windsurf CLI detected."
+                if windsurf_cmd
+                else "Windsurf project rules detected; paste the prompt into Windsurf."
+            ),
+        ),
+        AgentOption(
+            id="aider",
+            label="aider",
+            available=bool(aider_cmd),
+            launchable=bool(aider_cmd),
+            command=aider_cmd,
+            reason="aider detected in PATH." if aider_cmd else "aider is not in PATH.",
+        ),
+        AgentOption(
+            id="openrouter",
+            label="OpenRouter automation lane",
+            available=openrouter_ready,
+            launchable=False,
+            command=None,
+            reason=(
+                "OPENROUTER_API_KEY is set; executor.kind=llm can run headless."
+                if openrouter_ready
+                else "OPENROUTER_API_KEY is not set."
+            ),
+        ),
+    ]
+
+
+def detect_project_environment(project: Path) -> dict[str, Any]:
+    """Best-effort, read-only fingerprint of the current project."""
+    project = project.resolve()
+    markers = {
+        "git": _marker(project, ".git"),
+        "planfile": _marker(project, ".planfile", "config.yaml"),
+        "koru_policy": _marker(project, ".planfile", ".koru", "policy.yaml"),
+        "pyproject": _marker(project, "pyproject.toml"),
+        "package_json": _marker(project, "package.json"),
+        "taskfile": _marker(project, "Taskfile.yml") or _marker(project, "Taskfile.yaml"),
+        "makefile": _marker(project, "Makefile"),
+        "docker_compose": any(project.glob("docker-compose*.yml"))
+        or any(project.glob("docker-compose*.yaml")),
+        "windsurf_rules": _marker(project, ".windsurf", "rules.md"),
+        "cursor_rules": _marker(project, ".cursor"),
+        # On-change gate triad — surfaced in the brief's "On-change gates"
+        # section so the agent immediately sees which packages are wired
+        # to validate the project on every file save / pre-complete check.
+        "wup_yaml": _marker(project, "wup.yaml"),
+        "regix_yaml": _marker(project, "regix.yaml"),
+        "testql_scenarios": (
+            _marker(project, "testql-testing", "scenarios")
+            or _marker(project, "testql-scenarios")
+        ),
+    }
+    return {
+        "cwd": str(project),
+        "name": project.name,
+        "python": sys.version.split()[0],
+        "platform": platform.platform(),
+        "markers": markers,
+    }
+
+
+def detect_agent_environment(project: Path) -> dict[str, Any]:
+    """Combined environment block embedded in the LLM handoff."""
+    agents = detect_agent_options(project)
+    recommended = next((agent for agent in agents if agent.available), None)
+    semcod_tools = detect_semcod_tools(project)
+    return {
+        "project": detect_project_environment(project),
+        "llm_agents": [agent.to_dict() for agent in agents],
+        "recommended_agent": recommended.to_dict() if recommended else None,
+        "semcod_tools": [tool.to_dict() for tool in semcod_tools],
+    }
+
+
+def select_agent(
+    agents: list[AgentOption],
+    *,
+    agent_id: str | None = None,
+    interactive: bool = True,
+) -> AgentOption | None:
+    candidates = [agent for agent in agents if agent.available]
+    if agent_id:
+        return next((agent for agent in agents if agent.id == agent_id), None)
+    if not candidates:
+        return None
+    launchable = [agent for agent in candidates if agent.launchable]
+    if len(launchable) <= 1 or not interactive:
+        return (launchable or candidates)[0]
+
+    print("Multiple launchable agents detected:")
+    for index, agent in enumerate(launchable, start=1):
+        print(f"  {index}. {agent.label} ({agent.id})")
+    choice = input("Select agent number: ").strip()
+    try:
+        return launchable[int(choice) - 1]
+    except (ValueError, IndexError):
+        return None
+
+
+def save_agent_prompt(project: Path, prompt: str) -> Path:
+    prompts = runtime_dir(project) / "prompts"
+    prompts.mkdir(parents=True, exist_ok=True)
+    path = prompts / "latest-agent-prompt.md"
+    path.write_text(prompt, encoding="utf-8")
+    return path
+
+
+def launch_agent(agent: AgentOption, project: Path, prompt: str) -> int:
+    """Launch an agent CLI from the project root after saving the prompt."""
+    prompt_path = save_agent_prompt(project, prompt)
+    if not agent.launchable or not agent.command:
+        print(f"koru agent: {agent.label} is not launchable from PATH.")
+        print(f"Prompt saved: {prompt_path}")
+        return 2
+    print(f"koru agent: launching {agent.label}")
+    print(f"Prompt saved: {prompt_path}")
+    print("Open that prompt in the agent if its CLI starts an interactive session.")
+    try:
+        return subprocess.call([agent.command], cwd=project)
+    except OSError as exc:
+        print(f"koru agent: failed to launch {agent.label}: {exc}")
+        return 1

koru/bootstrap.py

@@ -0,0 +1,396 @@
+"""Bootstrap a new project from a flat-format pipeline YAML.
+
+This module bridges the two koru pipeline formats:
+
+- **Authoring (flat)** — the format from
+  ``docs/planfile-execution-gateway.md`` and ``examples/bootstrap.planfile.yaml``.
+  Tasks are a top-level list, easy to write and review.
+
+- **Runtime (nested)** — the planfile-native layout:
+  ``.planfile/sprints/<sprint>.yaml`` with tickets keyed by id under
+  ``sprint.tickets``. Used by ``planfile`` CLI and ``koru --queue``.
+
+The converter validates the flat schema and materialises it into the
+runtime layout without touching planfile internals — koru stays a thin
+orchestrator and planfile remains the source of truth at runtime.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+VALID_EXECUTOR_KINDS: frozenset[str] = frozenset({"shell", "human", "llm", "api", "mcp"})
+VALID_EXECUTOR_MODES: frozenset[str] = frozenset({"automatic", "interactive"})
+VALID_STATUSES: frozenset[str] = frozenset(
+    {"open", "in_progress", "review", "done", "blocked"}
+)
+VALID_PRIORITIES: frozenset[str] = frozenset({"critical", "high", "medium", "normal", "low"})
+VALID_EXECUTION_STATES: frozenset[str] = frozenset(
+    {"pending", "ready", "running", "waiting_input", "done", "failed", "skipped"}
+)
+
+
+@dataclass
+class ValidationError:
+    task_id: str
+    field: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.task_id}: {self.field}: {self.message}"
+
+
+@dataclass
+class ImportReport:
+    project_dir: Path
+    sprint: str
+    tickets_imported: list[str] = field(default_factory=list)
+    config_created: bool = False
+    sprint_file_created: bool = False
+    sprint_file_overwritten: bool = False
+
+    def summary(self) -> str:
+        lines = [
+            f"project: {self.project_dir}",
+            f"sprint:  {self.sprint}",
+            f"tickets: {len(self.tickets_imported)} imported",
+        ]
+        if self.config_created:
+            lines.append("config:  .planfile/config.yaml created")
+        if self.sprint_file_created:
+            lines.append(f"sprint:  .planfile/sprints/{self.sprint}.yaml created")
+        elif self.sprint_file_overwritten:
+            lines.append(f"sprint:  .planfile/sprints/{self.sprint}.yaml overwritten")
+        return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Loader + validator
+# ---------------------------------------------------------------------------
+
+
+def load_flat_pipeline(path: str | Path) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    """Read a flat-format pipeline YAML and return ``(header, tasks)``.
+
+    The file must have a ``tasks`` top-level list. The header is everything
+    else (project, version, generated, description, etc.) and is preserved
+    for round-tripping.
+    """
+    file = Path(path)
+    if not file.exists():
+        raise FileNotFoundError(f"pipeline file not found: {file}")
+    data = yaml.safe_load(file.read_text(encoding="utf-8")) or {}
+    if not isinstance(data, dict):
+        raise ValueError(f"{file}: expected a YAML mapping at top level")
+    raw_tasks = data.get("tasks")
+    if not isinstance(raw_tasks, list):
+        raise ValueError(f"{file}: missing top-level 'tasks' list")
+    tasks = [t for t in raw_tasks if isinstance(t, dict)]
+    header = {k: v for k, v in data.items() if k != "tasks"}
+    return header, tasks
+
+
+def validate_flat_pipeline(tasks: list[dict[str, Any]]) -> list[ValidationError]:
+    """Validate a flat pipeline. Returns a list of errors (empty == valid)."""
+    errors: list[ValidationError] = []
+    seen_ids: set[str] = set()
+
+    for task in tasks:
+        tid = str(task.get("id") or "<missing-id>")
+
+        if "id" not in task:
+            errors.append(ValidationError(tid, "id", "missing"))
+            continue
+        if tid in seen_ids:
+            errors.append(ValidationError(tid, "id", "duplicate"))
+            continue
+        seen_ids.add(tid)
+
+        # name
+        if not (task.get("name") or task.get("title")):
+            errors.append(ValidationError(tid, "name", "missing (or 'title')"))
+
+        # status
+        status = task.get("status", "open")
+        if status not in VALID_STATUSES:
+            errors.append(
+                ValidationError(tid, "status", f"{status!r} not in {sorted(VALID_STATUSES)}")
+            )
+
+        # priority
+        priority = task.get("priority", "normal")
+        if isinstance(priority, str) and priority not in VALID_PRIORITIES:
+            errors.append(
+                ValidationError(
+                    tid, "priority", f"{priority!r} not in {sorted(VALID_PRIORITIES)}"
+                )
+            )
+
+        # executor
+        executor = task.get("executor")
+        if not isinstance(executor, dict):
+            errors.append(ValidationError(tid, "executor", "missing or not a mapping"))
+        else:
+            kind = executor.get("kind")
+            if kind not in VALID_EXECUTOR_KINDS:
+                errors.append(
+                    ValidationError(
+                        tid, "executor.kind", f"{kind!r} not in {sorted(VALID_EXECUTOR_KINDS)}"
+                    )
+                )
+            mode = executor.get("mode", "automatic")
+            if mode not in VALID_EXECUTOR_MODES:
+                errors.append(
+                    ValidationError(
+                        tid, "executor.mode", f"{mode!r} not in {sorted(VALID_EXECUTOR_MODES)}"
+                    )
+                )
+
+        # execution.state
+        execution = task.get("execution") or {}
+        state = execution.get("state", "pending")
+        if state not in VALID_EXECUTION_STATES:
+            errors.append(
+                ValidationError(
+                    tid, "execution.state", f"{state!r} not in {sorted(VALID_EXECUTION_STATES)}"
+                )
+            )
+
+        # blocked_by must be list[str]
+        blocked_by = task.get("blocked_by", []) or []
+        if not isinstance(blocked_by, list):
+            errors.append(ValidationError(tid, "blocked_by", "must be a list"))
+        else:
+            for dep in blocked_by:
+                if not isinstance(dep, str):
+                    errors.append(
+                        ValidationError(tid, "blocked_by", f"non-string entry: {dep!r}")
+                    )
+
+    # Cross-task validation: all blocked_by references resolve, no cycles
+    ids = {str(t.get("id")) for t in tasks if t.get("id")}
+    for task in tasks:
+        tid = str(task.get("id") or "")
+        for dep in task.get("blocked_by") or []:
+            if isinstance(dep, str) and dep not in ids:
+                errors.append(
+                    ValidationError(tid, "blocked_by", f"unknown task id {dep!r}")
+                )
+    cycle = _detect_cycle(tasks)
+    if cycle:
+        errors.append(
+            ValidationError(cycle[0], "blocked_by", f"cycle detected: {' → '.join(cycle)}")
+        )
+    return errors
+
+
+def _detect_cycle(tasks: list[dict[str, Any]]) -> list[str]:
+    """Return the first detected dependency cycle, or empty list."""
+    graph: dict[str, list[str]] = {}
+    for t in tasks:
+        tid = str(t.get("id") or "")
+        if not tid:
+            continue
+        graph[tid] = [
+            d for d in (t.get("blocked_by") or []) if isinstance(d, str)
+        ]
+
+    WHITE, GRAY, BLACK = 0, 1, 2
+    color: dict[str, int] = dict.fromkeys(graph, WHITE)
+    parent: dict[str, str] = {}
+
+    def dfs(node: str) -> list[str]:
+        color[node] = GRAY
+        for nb in graph.get(node, []):
+            if color.get(nb, WHITE) == GRAY:
+                # Reconstruct cycle node → ... → nb → node
+                cycle = [node]
+                cursor = node
+                while cursor != nb and cursor in parent:
+                    cursor = parent[cursor]
+                    cycle.append(cursor)
+                cycle.append(node)
+                cycle.reverse()
+                return cycle
+            if color.get(nb, WHITE) == WHITE:
+                parent[nb] = node
+                found = dfs(nb)
+                if found:
+                    return found
+        color[node] = BLACK
+        return []
+
+    for node in graph:
+        if color[node] == WHITE:
+            cycle = dfs(node)
+            if cycle:
+                return cycle
+    return []
+
+
+# ---------------------------------------------------------------------------
+# Materialiser (flat → nested .planfile/)
+# ---------------------------------------------------------------------------
+
+
+def materialize_to_planfile(
+    flat_tasks: list[dict[str, Any]],
+    project_dir: str | Path,
+    *,
+    sprint: str = "current",
+    sprint_name: str = "Imported pipeline",
+    prefix: str = "PLF",
+    overwrite: bool = False,
+) -> ImportReport:
+    """Write ``flat_tasks`` into ``project_dir/.planfile/sprints/<sprint>.yaml``.
+
+    Creates ``.planfile/config.yaml`` if missing. Existing sprint file is
+    preserved unless ``overwrite=True``; otherwise raises ``FileExistsError``.
+    """
+    project = Path(project_dir).resolve()
+    base_dir = project / ".planfile"
+    sprints_dir = base_dir / "sprints"
+    config_path = base_dir / "config.yaml"
+    sprint_path = sprints_dir / f"{sprint}.yaml"
+
+    sprints_dir.mkdir(parents=True, exist_ok=True)
+
+    report = ImportReport(project_dir=project, sprint=sprint)
+
+    if not config_path.exists():
+        config_data = {
+            "project": project.name,
+            "prefix": prefix,
+            "next_id": _next_id_after(flat_tasks, prefix),
+        }
+        config_path.write_text(yaml.safe_dump(config_data, sort_keys=False), encoding="utf-8")
+        report.config_created = True
+
+    if sprint_path.exists() and not overwrite:
+        raise FileExistsError(
+            f"{sprint_path} already exists. Use overwrite=True (or --force) to replace it."
+        )
+
+    tickets: dict[str, dict[str, Any]] = {}
+    for task in flat_tasks:
+        tid = str(task["id"])
+        tickets[tid] = _normalise_task(task, default_sprint=sprint)
+        report.tickets_imported.append(tid)
+
+    sprint_data = {
+        "sprint": {
+            "id": sprint,
+            "name": sprint_name,
+            "status": "active",
+            "tickets": tickets,
+        }
+    }
+    if sprint_path.exists():
+        report.sprint_file_overwritten = True
+    else:
+        report.sprint_file_created = True
+    sprint_path.write_text(
+        yaml.safe_dump(sprint_data, sort_keys=False, default_flow_style=False),
+        encoding="utf-8",
+    )
+    return report
+
+
+def _normalise_task(task: dict[str, Any], *, default_sprint: str) -> dict[str, Any]:
+    """Return a planfile-Ticket-compatible mapping for a flat task."""
+    out = dict(task)
+    # Map title -> name if name absent
+    if "name" not in out and "title" in out:
+        out["name"] = out.pop("title")
+    out.setdefault("sprint", default_sprint)
+    out.setdefault("status", "open")
+    out.setdefault("priority", "normal")
+
+    # Default the executor mode for safety.
+    if isinstance(out.get("executor"), dict):
+        out["executor"].setdefault("mode", "automatic")
+
+    # Default execution.state to "ready" for tasks with no blocked_by, else "pending"
+    execution = out.get("execution")
+    if not isinstance(execution, dict):
+        execution = {}
+    execution.setdefault("queue", "default")
+    if "state" not in execution:
+        execution["state"] = "ready" if not out.get("blocked_by") else "pending"
+    execution.setdefault("attempt", 0)
+    execution.setdefault("max_attempts", 1)
+    out["execution"] = execution
+
+    # Drop fields planfile doesn't model so it stays clean.
+    for noisy in ("phase",):
+        out.pop(noisy, None)
+
+    return out
+
+
+def _next_id_after(tasks: list[dict[str, Any]], prefix: str) -> int:
+    """Compute a safe next_id higher than any numeric suffix already in use."""
+    max_id = 0
+    pref = f"{prefix}-"
+    for task in tasks:
+        tid = str(task.get("id") or "")
+        if tid.startswith(pref):
+            try:
+                num = int(tid[len(pref):].split("-")[-1])
+                max_id = max(max_id, num)
+            except ValueError:
+                continue
+    return max_id + 1
+
+
+# ---------------------------------------------------------------------------
+# Top-level entry: validate → materialize
+# ---------------------------------------------------------------------------
+
+
+def import_flat_pipeline(
+    flat_path: str | Path,
+    project_dir: str | Path,
+    *,
+    sprint: str = "current",
+    overwrite: bool = False,
+    prefix: str | None = None,
+) -> ImportReport:
+    """Validate and import a flat pipeline into ``project_dir/.planfile/``.
+
+    Raises ``ValueError`` with a multi-line message if validation fails.
+    """
+    header, tasks = load_flat_pipeline(flat_path)
+    if not tasks:
+        raise ValueError(f"{flat_path}: no tasks found")
+
+    errors = validate_flat_pipeline(tasks)
+    if errors:
+        joined = "\n".join(f"  - {e}" for e in errors)
+        raise ValueError(f"{flat_path}: validation failed\n{joined}")
+
+    sprint_name = str(header.get("description") or header.get("project") or "Imported pipeline")
+    if "\n" in sprint_name:
+        sprint_name = sprint_name.splitlines()[0].strip()
+
+    return materialize_to_planfile(
+        tasks,
+        project_dir,
+        sprint=sprint,
+        sprint_name=sprint_name,
+        prefix=(prefix or _infer_prefix(tasks) or "PLF"),
+        overwrite=overwrite,
+    )
+
+
+def _infer_prefix(tasks: list[dict[str, Any]]) -> str | None:
+    """Infer planfile prefix from the first task id (e.g. KORU-B-001 → KORU)."""
+    for task in tasks:
+        tid = str(task.get("id") or "")
+        if "-" in tid:
+            return tid.split("-", 1)[0]
+    return None