codeforerunner 0.3.0__py3-none-any.whl

codeforerunner/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

codeforerunner/check.py

@@ -0,0 +1,156 @@
+"""Drift detection for docs that claim files don't exist when they do."""
+from __future__ import annotations
+
+import fnmatch
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from codeforerunner.config import CheckConfig
+
+
+@dataclass(frozen=True)
+class Violation:
+    path: Path
+    line: int
+    rule_id: str
+    message: str
+
+
+_RULES = [
+    (
+        "R1-no-cli",
+        re.compile(
+            r"(?i)no\s+CLI\s+exists"
+            r"|CLI\s+does\s+not\s+exist"
+            r"|not\s+currently\s+present:[^.]*\bCLI\b"
+            r"|Do\s+not\s+run\s+`forerunner`"
+        ),
+        ("src/codeforerunner/cli.py",),
+        "doc claims no CLI exists, but src/codeforerunner/cli.py is present",
+    ),
+    (
+        "R2-no-pre-commit",
+        re.compile(r"(?i)no\s+pre[- ]commit(\s+hook)?"),
+        (".pre-commit-hooks.yaml",),
+        "doc claims no pre-commit hook, but .pre-commit-hooks.yaml is present",
+    ),
+    (
+        "R3-no-ci",
+        re.compile(r"(?i)no\s+CI(\s+workflow)?"),
+        (".github/workflows/*.yml",),
+        "doc claims no CI workflow, but .github/workflows/*.yml is present",
+    ),
+    (
+        "R4-no-installer",
+        re.compile(r"(?i)no\s+installer"),
+        ("src/codeforerunner/installer.py",),
+        "doc claims no installer, but src/codeforerunner/installer.py is present",
+    ),
+    (
+        "R5-no-python-package",
+        re.compile(r"(?i)no\s+Python\s+package"),
+        ("pyproject.toml",),
+        "doc claims no Python package, but pyproject.toml is present",
+    ),
+    (
+        "R6-no-docker",
+        re.compile(r"(?i)no\s+Docker(\s+image)?|no\s+Dockerfile"),
+        ("Dockerfile", "compose.yml", "docker-compose.yml"),
+        "doc claims no Docker, but Dockerfile/compose file is present",
+    ),
+    (
+        "R6b-no-makefile",
+        re.compile(r"(?i)no\s+Makefile"),
+        ("Makefile",),
+        "doc claims no Makefile, but Makefile is present",
+    ),
+    (
+        "R7-no-mcp",
+        re.compile(r"(?i)no\s+MCP(\s+server)?"),
+        ("src/codeforerunner/mcp_server.py",),
+        "doc claims no MCP server, but src/codeforerunner/mcp_server.py is present",
+    ),
+    (
+        "R8-no-marketplace",
+        re.compile(r"(?i)no\s+marketplace(\s+manifest)?"),
+        ("plugins/codex/marketplace.json",),
+        "doc claims no marketplace, but plugins/codex/marketplace.json is present",
+    ),
+]
+
+
+def _trigger_exists(repo: Path, patterns: tuple[str, ...]) -> bool:
+    for pat in patterns:
+        if "*" in pat:
+            parent = repo / Path(pat).parent
+            name = Path(pat).name
+            if parent.is_dir() and any(parent.glob(name)):
+                return True
+        else:
+            if (repo / pat).exists():
+                return True
+    return False
+
+
+def _scanned_docs(repo: Path) -> list[Path]:
+    docs: list[Path] = []
+    readme = repo / "README.md"
+    if readme.is_file():
+        docs.append(readme)
+    docs_dir = repo / "docs"
+    if docs_dir.is_dir():
+        docs.extend(sorted(p for p in docs_dir.rglob("*.md") if p.is_file()))
+    return docs
+
+
+def _path_ignored(repo: Path, doc: Path, ignore_patterns: tuple[str, ...]) -> bool:
+    if not ignore_patterns:
+        return False
+    try:
+        rel = doc.relative_to(repo).as_posix()
+    except ValueError:
+        rel = doc.as_posix()
+    return any(fnmatch.fnmatch(rel, pat) for pat in ignore_patterns)
+
+
+def run(repo: Path, config: CheckConfig | None = None) -> list[Violation]:
+    """Scan repo docs for drift; return list of violations.
+
+    `config` filters rules via `enabled_rules` and skips docs matching `ignore_paths`.
+    `None` config (default) preserves the pre-T25 behavior: all rules, no ignores.
+    """
+    repo = Path(repo)
+    enabled = set(config.enabled_rules) if (config and config.enabled_rules is not None) else None
+    ignore_patterns = config.ignore_paths if config else ()
+
+    active_rules = [
+        (rid, rx, msg)
+        for rid, rx, triggers, msg in _RULES
+        if _trigger_exists(repo, triggers) and (enabled is None or rid in enabled)
+    ]
+    if not active_rules:
+        return []
+
+    violations: list[Violation] = []
+    for doc in _scanned_docs(repo):
+        if _path_ignored(repo, doc, ignore_patterns):
+            continue
+        try:
+            text = doc.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        for lineno, line in enumerate(text.splitlines(), start=1):
+            for rid, rx, msg in active_rules:
+                if rx.search(line):
+                    violations.append(
+                        Violation(path=doc, line=lineno, rule_id=rid, message=msg)
+                    )
+    return violations
+
+
+def format_violations(vs: list[Violation]) -> str:
+    """Format violations one per line for stderr."""
+    return "\n".join(
+        f"{v.path}:{v.line}: {v.rule_id}: {v.message}" for v in vs
+    )

codeforerunner/cli.py

@@ -0,0 +1,236 @@
+"""Thin CLI orchestration. Product logic lives in `prompts/`. See SPEC.md §D.cli."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import Sequence
+
+SCAN_EXEMPT_TASKS = frozenset({"scan", "init-agent-onboarding"})
+SCAN_DONE_ENV = "FORERUNNER_SCAN_DONE"
+
+
+def _repo_root(start: Path | None = None) -> Path:
+    """Walk up from cwd (or `start`) to a directory containing `prompts/tasks`."""
+    here = (start or Path.cwd()).resolve()
+    for candidate in [here, *here.parents]:
+        if (candidate / "prompts" / "tasks").is_dir():
+            return candidate
+    raise FileNotFoundError(
+        "could not locate codeforerunner repo root (no prompts/tasks/ found upward)"
+    )
+
+
+def _read(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def cmd_doc(args: argparse.Namespace) -> int:
+    """Resolve `prompts/system/base.md` + `prompts/partials/*.md` + `prompts/tasks/<task>.md` to stdout."""
+    root = _repo_root(Path(args.repo) if args.repo else None)
+    task_path = root / "prompts" / "tasks" / f"{args.task}.md"
+    if not task_path.is_file():
+        print(f"error: unknown task '{args.task}' (no {task_path})", file=sys.stderr)
+        return 2
+
+    if (
+        args.task not in SCAN_EXEMPT_TASKS
+        and (root / "forerunner.config.yaml").is_file()
+        and not os.environ.get(SCAN_DONE_ENV)
+    ):
+        print(
+            f"warning: SPEC V2 scan-first — run `forerunner scan` first, "
+            f"then export {SCAN_DONE_ENV}=1 to silence this warning.",
+            file=sys.stderr,
+        )
+
+    parts: list[str] = []
+    base = root / "prompts" / "system" / "base.md"
+    if base.is_file():
+        parts.append(f"<!-- system: base.md -->\n{_read(base).rstrip()}")
+
+    partials_dir = root / "prompts" / "partials"
+    if partials_dir.is_dir():
+        for p in sorted(partials_dir.glob("*.md")):
+            parts.append(f"<!-- partial: {p.name} -->\n{_read(p).rstrip()}")
+
+    parts.append(f"<!-- task: {task_path.name} -->\n{_read(task_path).rstrip()}")
+    sys.stdout.write("\n\n".join(parts) + "\n")
+    return 0
+
+
+def _doc_for(args: argparse.Namespace, task: str) -> int:
+    ns = argparse.Namespace(repo=getattr(args, "repo", None), task=task)
+    return cmd_doc(ns)
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    """Default + --agents-only = onboarding bundle only. --full prepends scan."""
+    if getattr(args, "full", False):
+        sys.stdout.write("<!-- forerunner init --full: section 1/2 (scan) -->\n")
+        rc = _doc_for(args, "scan")
+        if rc != 0:
+            return rc
+        sys.stdout.write("\n<!-- forerunner init --full: section 2/2 (onboarding) -->\n")
+    return _doc_for(args, "init-agent-onboarding")
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    rc = _doc_for(args, "scan")
+    if rc == 0:
+        print(
+            f"hint: export {SCAN_DONE_ENV}=1 in this shell to silence "
+            "scan-first warnings on follow-up `forerunner doc`/`init` calls.",
+            file=sys.stderr,
+        )
+    return rc
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    """Run check rules when `forerunner.config.yaml` present. Silent no-op otherwise."""
+    try:
+        root = _repo_root(Path(args.repo) if args.repo else None)
+    except FileNotFoundError:
+        root = Path.cwd()
+    from codeforerunner import check as _check
+    from codeforerunner.config import ConfigError, load_from_repo
+    try:
+        cfg = load_from_repo(root)
+    except ConfigError as e:
+        print(f"forerunner check: invalid config: {e}", file=sys.stderr)
+        return 2
+    if cfg is None:
+        return 0
+    violations = _check.run(root, cfg.check)
+    if not violations:
+        return 0
+    sys.stderr.write(_check.format_violations(violations) + "\n")
+    return 1
+
+
+def cmd_mcp_server(args: argparse.Namespace) -> int:
+    from codeforerunner import mcp_server
+    root = _repo_root(Path(args.repo) if args.repo else None)
+    return mcp_server.serve(root)
+
+
+def cmd_generate(args: argparse.Namespace) -> int:
+    """Resolve the bundle for <task> and send it to the configured provider."""
+    from codeforerunner import providers as _providers
+    from codeforerunner.config import load_from_repo
+
+    root = _repo_root(Path(args.repo) if args.repo else None)
+    cfg = load_from_repo(root)
+
+    provider_name = args.provider or (cfg.provider if cfg else "anthropic")
+    model = args.model or (cfg.model if cfg else None)
+    provider_cls = _providers.get(provider_name)
+    provider = provider_cls()
+    model = model or provider.default_model
+
+    import io as _io
+    buf = _io.StringIO()
+    ns = argparse.Namespace(repo=getattr(args, "repo", None), task=args.task)
+    # Temporarily redirect stdout to capture cmd_doc output.
+    real_stdout = sys.stdout
+    sys.stdout = buf
+    try:
+        rc = cmd_doc(ns)
+    finally:
+        sys.stdout = real_stdout
+    if rc != 0:
+        return rc
+
+    env_var = (cfg.api_key_env.get(provider_name) if cfg else None) or provider.default_env_var
+    api_key = os.environ.get(env_var)
+    if api_key is None and provider_name != "ollama":
+        print(
+            f"error: missing API key; set ${env_var}",
+            file=sys.stderr,
+        )
+        return 3
+
+    try:
+        result = provider.complete(prompt=buf.getvalue(), model=model, api_key=api_key)
+    except _providers.ProviderError as e:
+        print(f"error: {provider_name} provider failed: {e}", file=sys.stderr)
+        return 4
+
+    sys.stdout.write(result.text.rstrip() + "\n")
+    print(
+        f"# {provider_name} {result.model} {result.usage or ''}".rstrip(),
+        file=sys.stderr,
+    )
+    return 0
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    from codeforerunner import doctor
+    root = _repo_root(Path(args.repo) if args.repo else None)
+    findings = doctor.run(root)
+    sys.stdout.write(doctor.format_report(findings) + "\n")
+    return 1 if any(f.severity == "error" for f in findings) else 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="forerunner",
+        description="Prompt-first repo documentation tooling. Thin CLI; product logic in prompts/.",
+    )
+    p.add_argument("--repo", help="path to repo root (defaults to cwd ancestor with prompts/tasks/)")
+    from codeforerunner import __version__ as _version
+    p.add_argument("--version", action="version", version=f"forerunner {_version}")
+    sub = p.add_subparsers(dest="cmd", required=True, metavar="<cmd>")
+
+    s_init = sub.add_parser("init", help="resolve init-agent-onboarding prompt bundle to stdout")
+    init_scope = s_init.add_mutually_exclusive_group()
+    init_scope.add_argument(
+        "--full",
+        action="store_true",
+        help="prepend scan bundle before the onboarding bundle (scan-first per V2)",
+    )
+    init_scope.add_argument(
+        "--agents-only",
+        action="store_true",
+        help="explicit alias for the default scope (AGENTS.md update only)",
+    )
+    s_init.set_defaults(func=cmd_init)
+
+    s_scan = sub.add_parser("scan", help="resolve scan prompt bundle to stdout")
+    s_scan.set_defaults(func=cmd_scan)
+
+    s_doc = sub.add_parser("doc", help="resolve prompt bundle for <task> to stdout")
+    s_doc.add_argument("task", help="task name (basename without .md) under prompts/tasks/")
+    s_doc.set_defaults(func=cmd_doc)
+
+    s_check = sub.add_parser("check", help="run drift-detection rules against tracked docs")
+    s_check.set_defaults(func=cmd_check)
+
+    s_mcp = sub.add_parser("mcp-server", help="serve prompt bundles as MCP tools over stdio")
+    s_mcp.set_defaults(func=cmd_mcp_server)
+
+    s_doctor = sub.add_parser("doctor", help="health report: skill parity + marketplace + installed dests")
+    s_doctor.set_defaults(func=cmd_doctor)
+
+    s_gen = sub.add_parser("generate", help="resolve bundle for <task> and call the configured provider")
+    s_gen.add_argument("task", help="task basename under prompts/tasks/")
+    s_gen.add_argument("--provider", help="override config provider")
+    s_gen.add_argument("--model", help="override config model")
+    s_gen.set_defaults(func=cmd_generate)
+
+    from codeforerunner import installer
+    installer.add_subparser(sub)
+
+    return p
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

codeforerunner/config.py

@@ -0,0 +1,176 @@
+"""`forerunner.config.yaml` schema + loader. See SPEC.md §T25."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+CONFIG_FILENAME = "forerunner.config.yaml"
+
+_KNOWN_PROVIDERS = {"anthropic", "openai", "google", "ollama"}
+_KNOWN_SEVERITIES = {"HIGH", "MEDIUM", "LOW"}
+
+
+class ConfigError(Exception):
+    """Schema violation in forerunner.config.yaml."""
+
+
+@dataclass(frozen=True)
+class CheckConfig:
+    block_on: tuple[str, ...] = ("HIGH", "MEDIUM")
+    warn_on: tuple[str, ...] = ("LOW",)
+    enabled_rules: tuple[str, ...] | None = None  # None = all rules enabled
+    ignore_paths: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class VersionAuditConfig:
+    enabled: bool = True
+    stale_after_days: int = 30
+    fetch_live_eol_data: bool = False
+
+
+@dataclass(frozen=True)
+class ForerunnerConfig:
+    provider: str = "anthropic"
+    model: str = "claude-opus-4-7"
+    output_dir: Path = field(default_factory=lambda: Path("docs"))
+    context_max_files: int = 30
+    context_max_lines_per_file: int = 300
+    approaching_eol_threshold_months: int = 6
+    ignore_patterns: tuple[str, ...] = ()
+    api_key_env: dict[str, str] = field(default_factory=dict)
+    check: CheckConfig = field(default_factory=CheckConfig)
+    version_audit: VersionAuditConfig = field(default_factory=VersionAuditConfig)
+
+
+def _require_type(value: Any, expected: type, field_name: str) -> Any:
+    if not isinstance(value, expected):
+        raise ConfigError(
+            f"{field_name}: expected {expected.__name__}, got {type(value).__name__}"
+        )
+    return value
+
+
+def _coerce_str_tuple(value: Any, field_name: str) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if not isinstance(value, list):
+        raise ConfigError(f"{field_name}: expected list, got {type(value).__name__}")
+    out: list[str] = []
+    for i, item in enumerate(value):
+        if not isinstance(item, str):
+            raise ConfigError(f"{field_name}[{i}]: expected string, got {type(item).__name__}")
+        out.append(item)
+    return tuple(out)
+
+
+def _parse_api_key_env(raw: Any) -> dict[str, str]:
+    if raw is None:
+        return {}
+    if not isinstance(raw, dict):
+        raise ConfigError(f"api_key_env: expected dict, got {type(raw).__name__}")
+    out: dict[str, str] = {}
+    for k, v in raw.items():
+        if not isinstance(k, str):
+            raise ConfigError(
+                f"api_key_env: keys must be strings, got {type(k).__name__}"
+            )
+        if k not in _KNOWN_PROVIDERS:
+            raise ConfigError(
+                f"api_key_env: unknown provider '{k}' (expected one of {sorted(_KNOWN_PROVIDERS)})"
+            )
+        if not isinstance(v, str) or not v:
+            raise ConfigError(
+                f"api_key_env[{k}]: expected non-empty string, got {type(v).__name__}"
+            )
+        out[k] = v
+    return out
+
+
+def _parse_check(raw: Any) -> CheckConfig:
+    if raw is None:
+        return CheckConfig()
+    _require_type(raw, dict, "tasks.check")
+    block_on = _coerce_str_tuple(raw.get("block_on", ["HIGH", "MEDIUM"]), "tasks.check.block_on")
+    warn_on = _coerce_str_tuple(raw.get("warn_on", ["LOW"]), "tasks.check.warn_on")
+    for sev in (*block_on, *warn_on):
+        if sev not in _KNOWN_SEVERITIES:
+            raise ConfigError(
+                f"tasks.check: unknown severity '{sev}' (expected one of {sorted(_KNOWN_SEVERITIES)})"
+            )
+    enabled_rules_raw = raw.get("enabled_rules")
+    enabled_rules = (
+        _coerce_str_tuple(enabled_rules_raw, "tasks.check.enabled_rules")
+        if enabled_rules_raw is not None
+        else None
+    )
+    ignore_paths = _coerce_str_tuple(raw.get("ignore_paths", []), "tasks.check.ignore_paths")
+    return CheckConfig(
+        block_on=block_on,
+        warn_on=warn_on,
+        enabled_rules=enabled_rules,
+        ignore_paths=ignore_paths,
+    )
+
+
+def _parse_version_audit(raw: Any) -> VersionAuditConfig:
+    if raw is None:
+        return VersionAuditConfig()
+    _require_type(raw, dict, "tasks.version_audit")
+    return VersionAuditConfig(
+        enabled=bool(raw.get("enabled", True)),
+        stale_after_days=int(raw.get("stale_after_days", 30)),
+        fetch_live_eol_data=bool(raw.get("fetch_live_eol_data", False)),
+    )
+
+
+def parse(raw: dict[str, Any] | None) -> ForerunnerConfig:
+    """Validate a parsed YAML mapping into a ForerunnerConfig."""
+    if raw is None:
+        return ForerunnerConfig()
+    _require_type(raw, dict, "<root>")
+
+    provider = raw.get("provider", "anthropic")
+    _require_type(provider, str, "provider")
+    if provider not in _KNOWN_PROVIDERS:
+        raise ConfigError(
+            f"provider: unknown '{provider}' (expected one of {sorted(_KNOWN_PROVIDERS)})"
+        )
+
+    tasks = raw.get("tasks") or {}
+    _require_type(tasks, dict, "tasks")
+
+    return ForerunnerConfig(
+        provider=provider,
+        model=_require_type(raw.get("model", "claude-opus-4-7"), str, "model"),
+        output_dir=Path(_require_type(raw.get("output_dir", "docs"), str, "output_dir")),
+        context_max_files=int(raw.get("context_max_files", 30)),
+        context_max_lines_per_file=int(raw.get("context_max_lines_per_file", 300)),
+        approaching_eol_threshold_months=int(raw.get("approaching_eol_threshold_months", 6)),
+        ignore_patterns=_coerce_str_tuple(raw.get("ignore_patterns", []), "ignore_patterns"),
+        api_key_env=_parse_api_key_env(raw.get("api_key_env")),
+        check=_parse_check(tasks.get("check")),
+        version_audit=_parse_version_audit(tasks.get("version_audit")),
+    )
+
+
+def load(path: Path) -> ForerunnerConfig:
+    """Load and validate a config file. Empty file = all defaults."""
+    text = path.read_text(encoding="utf-8")
+    try:
+        raw = yaml.safe_load(text)
+    except yaml.YAMLError as e:
+        raise ConfigError(f"{path}: invalid YAML: {e}") from e
+    return parse(raw)
+
+
+def load_from_repo(repo: Path) -> ForerunnerConfig | None:
+    """Return parsed config when `forerunner.config.yaml` is present, else None."""
+    p = repo / CONFIG_FILENAME
+    if not p.is_file():
+        return None
+    return load(p)