codeforerunner 0.3.0__py3-none-any.whl

codeforerunner/doctor.py

@@ -0,0 +1,321 @@
+"""`forerunner doctor` — single-screen health report. See SPEC.md §T35."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+from codeforerunner.config import CONFIG_FILENAME, ConfigError, load_from_repo
+
+CANONICAL_REL = Path("agent/codeforerunner.skill.md")
+SKILL_COPIES_REL: tuple[Path, ...] = (
+    Path("plugins/codeforerunner/skills/codeforerunner/SKILL.md"),
+    Path("skills/codeforerunner/SKILL.md"),
+)
+MARKETPLACE_REL = Path("plugins/codex/marketplace.json")
+
+MARKER_BEGIN = "<!-- forerunner:begin managed=codeforerunner.skill -->"
+MARKER_END = "<!-- forerunner:end -->"
+
+_DEFAULT_PROVIDER_ENV = {
+    "anthropic": "ANTHROPIC_API_KEY",
+    "openai": "OPENAI_API_KEY",
+    "google": "GOOGLE_API_KEY",
+    "ollama": "OLLAMA_HOST",
+}
+
+
+@dataclass(frozen=True)
+class Finding:
+    severity: str  # "ok" | "warn" | "error"
+    check: str
+    message: str
+
+
+def _installed_skill_destinations() -> list[Path]:
+    home = Path(os.path.expanduser("~"))
+    return [
+        home / ".codex/skills/codeforerunner/SKILL.md",
+        home / ".claude/plugins/codeforerunner/skills/codeforerunner/SKILL.md",
+    ]
+
+
+def _installed_marketplace_destination() -> Path:
+    return Path(os.path.expanduser("~")) / ".codex/marketplaces/codeforerunner.json"
+
+
+def _load_script_module(repo: Path, relpath: str, module_name: str):
+    script_path = repo / relpath
+    spec = importlib.util.spec_from_file_location(module_name, script_path)
+    if spec is None or spec.loader is None:  # pragma: no cover - defensive
+        raise RuntimeError(f"cannot load {script_path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def _check_skill_body_parity(repo: Path) -> list[Finding]:
+    try:
+        skill_mod = _load_script_module(
+            repo, "scripts/validate_skill_copies.py", "_forerunner_doctor_skill_copies"
+        )
+        strip_frontmatter: Callable[[str], str] = skill_mod.strip_frontmatter
+    except Exception as exc:  # pragma: no cover - defensive
+        return [Finding("error", "skill-body-parity", f"loader failure: {exc}")]
+
+    canonical_path = repo / CANONICAL_REL
+    if not canonical_path.is_file():
+        return [
+            Finding(
+                "error",
+                "skill-body-parity",
+                f"canonical skill missing: {CANONICAL_REL}",
+            )
+        ]
+    canonical_body = strip_frontmatter(canonical_path.read_text(encoding="utf-8"))
+
+    findings: list[Finding] = []
+    for rel in SKILL_COPIES_REL:
+        p = repo / rel
+        if not p.is_file():
+            findings.append(
+                Finding("error", "skill-body-parity", f"copy missing: {rel}")
+            )
+            continue
+        body = strip_frontmatter(p.read_text(encoding="utf-8"))
+        if body != canonical_body:
+            findings.append(
+                Finding("error", "skill-body-parity", f"body drift in {rel}")
+            )
+    if not findings:
+        findings.append(
+            Finding(
+                "ok",
+                "skill-body-parity",
+                f"canonical body matches {len(SKILL_COPIES_REL)} distributed copies",
+            )
+        )
+    return findings
+
+
+def _check_codex_marketplace(repo: Path) -> list[Finding]:
+    try:
+        mp_mod = _load_script_module(
+            repo,
+            "scripts/validate_codex_marketplace.py",
+            "_forerunner_doctor_codex_marketplace",
+        )
+        validate: Callable[[Path], list[str]] = mp_mod.validate
+    except Exception as exc:  # pragma: no cover - defensive
+        return [Finding("error", "codex-marketplace", f"loader failure: {exc}")]
+
+    errors = validate(repo)
+    if not errors:
+        return [
+            Finding("ok", "codex-marketplace", f"{MARKETPLACE_REL} validates")
+        ]
+    return [Finding("error", "codex-marketplace", msg) for msg in errors]
+
+
+def _check_installed_destinations(repo: Path) -> list[Finding]:
+    findings: list[Finding] = []
+
+    for dest in _installed_skill_destinations():
+        if not dest.exists():
+            findings.append(
+                Finding(
+                    "ok",
+                    "installed-destinations",
+                    f"{dest}: not installed (skip)",
+                )
+            )
+            continue
+        try:
+            text = dest.read_text(encoding="utf-8")
+        except OSError as exc:
+            findings.append(
+                Finding(
+                    "warn",
+                    "installed-destinations",
+                    f"{dest}: unreadable ({exc})",
+                )
+            )
+            continue
+        if MARKER_BEGIN in text and MARKER_END in text:
+            findings.append(
+                Finding(
+                    "ok",
+                    "installed-destinations",
+                    f"{dest}: managed (markers present)",
+                )
+            )
+        else:
+            findings.append(
+                Finding(
+                    "warn",
+                    "installed-destinations",
+                    f"{dest}: exists without managed-region markers (installer will refuse to overwrite)",
+                )
+            )
+
+    mp_dest = _installed_marketplace_destination()
+    if not mp_dest.exists():
+        findings.append(
+            Finding(
+                "ok",
+                "installed-destinations",
+                f"{mp_dest}: not installed (skip)",
+            )
+        )
+    else:
+        src = repo / MARKETPLACE_REL
+        try:
+            installed = mp_dest.read_text(encoding="utf-8").rstrip()
+            canonical = src.read_text(encoding="utf-8").rstrip()
+        except OSError as exc:
+            findings.append(
+                Finding(
+                    "warn",
+                    "installed-destinations",
+                    f"{mp_dest}: unreadable ({exc})",
+                )
+            )
+        else:
+            if installed == canonical:
+                findings.append(
+                    Finding(
+                        "ok",
+                        "installed-destinations",
+                        f"{mp_dest}: matches {MARKETPLACE_REL}",
+                    )
+                )
+            else:
+                findings.append(
+                    Finding(
+                        "warn",
+                        "installed-destinations",
+                        f"{mp_dest}: drifted from {MARKETPLACE_REL}",
+                    )
+                )
+
+    return findings
+
+
+def _check_config_loadable(repo: Path) -> list[Finding]:
+    cfg_path = repo / CONFIG_FILENAME
+    if not cfg_path.is_file():
+        return [
+            Finding(
+                "ok",
+                "config-loadable",
+                f"no {CONFIG_FILENAME}; check is a no-op",
+            )
+        ]
+    try:
+        load_from_repo(repo)
+    except ConfigError as exc:
+        return [Finding("error", "config-loadable", str(exc))]
+    return [Finding("ok", "config-loadable", f"{CONFIG_FILENAME} parses cleanly")]
+
+
+def _check_provider_api_key(repo: Path) -> list[Finding]:
+    cfg_path = repo / CONFIG_FILENAME
+    if not cfg_path.is_file():
+        return [
+            Finding(
+                "ok",
+                "provider-api-key",
+                f"no {CONFIG_FILENAME}; provider key not checked",
+            )
+        ]
+    try:
+        cfg = load_from_repo(repo)
+    except ConfigError:
+        # config-loadable check will surface this; skip here
+        return [
+            Finding(
+                "ok",
+                "provider-api-key",
+                "config unparseable; skipped (see config-loadable)",
+            )
+        ]
+    if cfg is None:  # pragma: no cover - defensive
+        return [
+            Finding(
+                "ok",
+                "provider-api-key",
+                f"no {CONFIG_FILENAME}; provider key not checked",
+            )
+        ]
+    provider = cfg.provider
+    if provider == "ollama":
+        return [
+            Finding(
+                "ok",
+                "provider-api-key",
+                "ollama needs no API key (OLLAMA_HOST optional)",
+            )
+        ]
+    env_var = cfg.api_key_env.get(provider) or _DEFAULT_PROVIDER_ENV.get(provider, "")
+    if os.environ.get(env_var):
+        return [Finding("ok", "provider-api-key", f"{provider}: {env_var} is set")]
+    return [
+        Finding(
+            "warn",
+            "provider-api-key",
+            f"{provider}: ${env_var} is not set; `forerunner generate` will refuse to run",
+        )
+    ]
+
+
+def run(repo: Path) -> list[Finding]:
+    repo = repo.resolve()
+    findings: list[Finding] = []
+    findings.extend(_check_skill_body_parity(repo))
+    findings.extend(_check_codex_marketplace(repo))
+    findings.extend(_check_installed_destinations(repo))
+    findings.extend(_check_config_loadable(repo))
+    findings.extend(_check_provider_api_key(repo))
+    return findings
+
+
+def format_report(findings: list[Finding]) -> str:
+    lines = [f"[{f.severity}] {f.check}: {f.message}" for f in findings]
+    counts = {"ok": 0, "warn": 0, "error": 0}
+    for f in findings:
+        counts[f.severity] = counts.get(f.severity, 0) + 1
+    summary = (
+        f"summary: {counts.get('ok', 0)} ok, "
+        f"{counts.get('warn', 0)} warn, "
+        f"{counts.get('error', 0)} error"
+    )
+    lines.append(summary)
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="forerunner doctor",
+        description="Single-screen health report for codeforerunner repo.",
+    )
+    parser.add_argument(
+        "--repo",
+        type=Path,
+        default=Path.cwd(),
+        help="repo root (default: cwd)",
+    )
+    args = parser.parse_args(argv)
+
+    findings = run(args.repo)
+    print(format_report(findings))
+    return 1 if any(f.severity == "error" for f in findings) else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

codeforerunner/installer.py

@@ -0,0 +1,304 @@
+"""Idempotent skill installer. See SPEC.md §D.installer (cites V8, V10, V11, V12)."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Literal
+
+MARKER_BEGIN = "<!-- forerunner:begin managed=codeforerunner.skill -->"
+MARKER_END = "<!-- forerunner:end -->"
+
+CANONICAL_REL = Path("agent/codeforerunner.skill.md")
+MARKETPLACE_REL = Path("plugins/codex/marketplace.json")
+
+EXIT_OK = 0
+EXIT_USAGE = 2
+EXIT_BODY_MISMATCH = 3
+EXIT_UNMANAGED_DEST = 4
+
+
+@dataclass(frozen=True)
+class Target:
+    name: str
+    path: Path
+
+
+def _home() -> Path:
+    return Path(os.path.expanduser("~"))
+
+
+def resolve_target(agent: str, override: Path | None) -> Target:
+    if agent == "generic":
+        if override is None:
+            raise ValueError("generic target requires --path PATH")
+        return Target(agent, override.expanduser().resolve())
+    if override is not None:
+        return Target(agent, override.expanduser().resolve())
+    home = _home()
+    if agent == "codex":
+        return Target(agent, home / ".codex/skills/codeforerunner/SKILL.md")
+    if agent == "claude":
+        return Target(agent, home / ".claude/plugins/codeforerunner/skills/codeforerunner/SKILL.md")
+    raise ValueError(f"unknown agent '{agent}' (expected: codex, claude, generic)")
+
+
+def resolve_marketplace_target(agent: str, override: Path | None) -> Target:
+    if agent == "generic":
+        if override is None:
+            raise ValueError("generic marketplace target requires --path PATH")
+        return Target(agent, override.expanduser().resolve())
+    if override is not None:
+        return Target(agent, override.expanduser().resolve())
+    if agent == "codex":
+        return Target(agent, _home() / ".codex/marketplaces/codeforerunner.json")
+    raise ValueError(f"marketplace not supported for agent '{agent}' (expected: codex)")
+
+
+def strip_frontmatter(text: str) -> str:
+    """Body extraction matching scripts/validate_skill_copies.py."""
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    lines = text.split("\n")
+    if lines and lines[0] == "---":
+        for i in range(1, len(lines)):
+            if lines[i] == "---":
+                return "\n".join(lines[i + 1 :]).strip()
+    return text.strip()
+
+
+def extract_frontmatter(text: str) -> str:
+    """Return frontmatter block (incl. fences) or '' if none."""
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    lines = text.split("\n")
+    if lines and lines[0] == "---":
+        for i in range(1, len(lines)):
+            if lines[i] == "---":
+                return "\n".join(lines[: i + 1]) + "\n"
+    return ""
+
+
+def _hash(s: str) -> str:
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def _hash_bytes(b: bytes) -> str:
+    return hashlib.sha256(b).hexdigest()
+
+
+def render(source_text: str, dest_existing: str | None, agent: str) -> str:
+    """Render dest content: preserve dest frontmatter if present; wrap source body in markers."""
+    body = strip_frontmatter(source_text)
+    if dest_existing:
+        fm = extract_frontmatter(dest_existing)
+    else:
+        fm = ""
+    managed = f"{MARKER_BEGIN}\n{body}\n{MARKER_END}\n"
+    if fm:
+        return fm + managed
+    return managed
+
+
+def find_markers(text: str) -> tuple[int, int] | None:
+    a = text.find(MARKER_BEGIN)
+    if a < 0:
+        return None
+    b = text.find(MARKER_END, a + len(MARKER_BEGIN))
+    if b < 0:
+        return None
+    return (a, b + len(MARKER_END))
+
+
+def overlay(dest_text: str, source_body: str) -> str:
+    """Replace managed region in-place. Caller has verified markers exist."""
+    span = find_markers(dest_text)
+    assert span is not None
+    a, b = span
+    managed = f"{MARKER_BEGIN}\n{source_body}\n{MARKER_END}"
+    return dest_text[:a] + managed + dest_text[b:]
+
+
+@dataclass
+class Plan:
+    action: str  # "create" | "update" | "skip" | "abort"
+    reason: str
+    target: Target
+    new_content: str | None = None
+
+    def write(self) -> None:
+        if self.action in ("skip", "abort"):
+            return
+        assert self.new_content is not None
+        self.target.path.parent.mkdir(parents=True, exist_ok=True)
+        self.target.path.write_text(self.new_content, encoding="utf-8")
+
+
+def plan_install(
+    *,
+    source_path: Path,
+    canonical_path: Path,
+    target: Target,
+) -> tuple[Plan, int]:
+    """Return (plan, exit_code). exit_code ≠ 0 → abort."""
+    src_text = source_path.read_text(encoding="utf-8")
+    canonical_text = canonical_path.read_text(encoding="utf-8")
+
+    src_body = strip_frontmatter(src_text)
+    canon_body = strip_frontmatter(canonical_text)
+    if src_body != canon_body:
+        return (
+            Plan(
+                action="abort",
+                reason=(
+                    f"body-parity violation (V10): source body differs from canonical "
+                    f"{canonical_path}"
+                ),
+                target=target,
+            ),
+            EXIT_BODY_MISMATCH,
+        )
+
+    dest = target.path
+    if dest.exists():
+        dest_text = dest.read_text(encoding="utf-8")
+        if find_markers(dest_text) is None:
+            return (
+                Plan(
+                    action="abort",
+                    reason=(
+                        f"destination exists without managed markers ({dest}); refusing "
+                        "to overwrite user content"
+                    ),
+                    target=target,
+                ),
+                EXIT_UNMANAGED_DEST,
+            )
+        new_text = overlay(dest_text, src_body)
+        if _hash(new_text) == _hash(dest_text):
+            return Plan(action="skip", reason="dest matches source (V12 idempotent)", target=target), EXIT_OK
+        return Plan(action="update", reason="overlay managed region", target=target, new_content=new_text), EXIT_OK
+
+    new_text = render(src_text, None, target.name)
+    return Plan(action="create", reason="dest absent", target=target, new_content=new_text), EXIT_OK
+
+
+def plan_marketplace(*, source_path: Path, target: Target) -> tuple[Plan, int]:
+    """Idempotent JSON manifest install. Hash-equality on whole file (trimmed)."""
+    src_bytes = source_path.read_bytes()
+    src_trimmed = src_bytes.rstrip()
+    src_text = src_bytes.decode("utf-8")
+    dest = target.path
+    if dest.exists():
+        dest_bytes = dest.read_bytes()
+        dest_trimmed = dest_bytes.rstrip()
+        if _hash_bytes(src_trimmed) == _hash_bytes(dest_trimmed):
+            return (
+                Plan(action="skip", reason="dest matches source (V12 idempotent)", target=target),
+                EXIT_OK,
+            )
+        return (
+            Plan(
+                action="abort",
+                reason=(
+                    f"destination exists and differs from source ({dest}); refusing "
+                    "to overwrite user content"
+                ),
+                target=target,
+            ),
+            EXIT_UNMANAGED_DEST,
+        )
+    return (
+        Plan(action="create", reason="dest absent", target=target, new_content=src_text),
+        EXIT_OK,
+    )
+
+
+def install(
+    *,
+    agent: str,
+    repo_root: Path,
+    source: Path | None,
+    dest_override: Path | None,
+    check_only: bool,
+    kind: Literal["skill", "marketplace"] = "skill",
+    out=None,
+    err=None,
+) -> int:
+    out = out or sys.stdout
+    err = err or sys.stderr
+
+    if kind == "marketplace":
+        try:
+            target = resolve_marketplace_target(agent, dest_override)
+        except ValueError as e:
+            print(f"error: {e}", file=err)
+            return EXIT_USAGE
+        src_path = source if source is not None else (repo_root / MARKETPLACE_REL)
+        if not src_path.is_file():
+            print(f"error: marketplace source not found: {src_path}", file=err)
+            return EXIT_USAGE
+        plan, code = plan_marketplace(source_path=src_path, target=target)
+        prefix = "would " if check_only else ""
+        stream = err if code != EXIT_OK else out
+        print(f"{prefix}{plan.action}: {target.path} ({plan.reason})", file=stream)
+        if code != EXIT_OK:
+            return code
+        if not check_only:
+            plan.write()
+        return EXIT_OK
+
+    try:
+        target = resolve_target(agent, dest_override)
+    except ValueError as e:
+        print(f"error: {e}", file=err)
+        return EXIT_USAGE
+
+    canonical = repo_root / CANONICAL_REL
+    src_path = source if source is not None else canonical
+    if not src_path.is_file():
+        print(f"error: source not found: {src_path}", file=err)
+        return EXIT_USAGE
+    if not canonical.is_file():
+        print(f"error: canonical not found: {canonical}", file=err)
+        return EXIT_USAGE
+
+    plan, code = plan_install(source_path=src_path, canonical_path=canonical, target=target)
+    prefix = "would " if check_only else ""
+    stream = err if code != EXIT_OK else out
+    print(f"{prefix}{plan.action}: {target.path} ({plan.reason})", file=stream)
+    if code != EXIT_OK:
+        return code
+    if not check_only:
+        plan.write()
+    return EXIT_OK
+
+
+def add_subparser(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("install", help="install skill into agent-specific directory (D.installer)")
+    p.add_argument("agent", choices=["codex", "claude", "generic"])
+    p.add_argument("--check", action="store_true", help="dry-run: print plan, write nothing")
+    p.add_argument("--path", type=Path, help="dest path override (required for generic)")
+    p.add_argument("--source", type=Path, help="source skill file (default: agent/codeforerunner.skill.md)")
+    p.add_argument(
+        "--marketplace",
+        action="store_true",
+        help="install a marketplace manifest (codex only) instead of the skill body",
+    )
+    p.set_defaults(func=_cli_entry)
+
+
+def _cli_entry(args: argparse.Namespace) -> int:
+    from codeforerunner.cli import _repo_root  # local import to avoid cycle
+
+    root = _repo_root(Path(args.repo) if args.repo else None)
+    return install(
+        agent=args.agent,
+        repo_root=root,
+        source=args.source,
+        dest_override=args.path,
+        check_only=args.check,
+        kind="marketplace" if getattr(args, "marketplace", False) else "skill",
+    )