codeforerunner 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

codeforerunner/__init__.py

@@ -1 +1,6 @@
-__version__ = "0.2.0"
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("codeforerunner")
+except PackageNotFoundError:
+    __version__ = "0.0.0"  # running from source without install

codeforerunner/bundle.py

@@ -0,0 +1,58 @@
+"""Shared prompt resolution used by cli.py and mcp_server.py."""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _package_prompts() -> Path:
+    return Path(__file__).parent / "prompts"
+
+
+def find_prompts_root(repo_arg: str | Path | None = None) -> Path:
+    """Return the prompts root directory (parent of tasks/).
+
+    Resolution order:
+    1. {repo_arg}/prompts/ if given and contains tasks/
+    2. Walk up from cwd looking for prompts/tasks/ (checkout compat)
+    3. Package-bundled prompts (always available after pip install)
+    """
+    if repo_arg is not None:
+        p = Path(repo_arg) / "prompts"
+        if (p / "tasks").is_dir():
+            return p
+        raise FileNotFoundError(
+            f"no prompts/tasks/ found under {str(repo_arg)!r}"
+        )
+
+    here = Path.cwd().resolve()
+    for candidate in [here, *here.parents]:
+        if (candidate / "prompts" / "tasks").is_dir():
+            return candidate / "prompts"
+
+    pkg = _package_prompts()
+    if (pkg / "tasks").is_dir():
+        return pkg
+
+    raise FileNotFoundError(
+        "could not find prompts/tasks/; specify --repo or reinstall the package"
+    )
+
+
+def resolve_bundle(prompts_root: Path, task: str) -> str:
+    """Concatenate system/base.md + sorted partials/*.md + tasks/<task>.md."""
+    task_path = prompts_root / "tasks" / f"{task}.md"
+    if not task_path.is_file():
+        raise FileNotFoundError(f"unknown task {task!r} (no {task_path})")
+
+    parts: list[str] = []
+    base = prompts_root / "system" / "base.md"
+    if base.is_file():
+        parts.append(f"<!-- system: base.md -->\n{base.read_text(encoding='utf-8').rstrip()}")
+
+    partials_dir = prompts_root / "partials"
+    if partials_dir.is_dir():
+        for p in sorted(partials_dir.glob("*.md")):
+            parts.append(f"<!-- partial: {p.name} -->\n{p.read_text(encoding='utf-8').rstrip()}")
+
+    parts.append(f"<!-- task: {task_path.name} -->\n{task_path.read_text(encoding='utf-8').rstrip()}")
+    return "\n\n".join(parts) + "\n"

codeforerunner/check.py

@@ -1,9 +1,9 @@
-"""Drift detection for docs that claim files don't exist when they do."""
+"""Drift detection for docs vs repo state."""
 from __future__ import annotations
 
 import fnmatch
 import re
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 
 from codeforerunner.config import CheckConfig
@@ -17,8 +17,18 @@ class Violation:
     message: str
 
 
-_RULES = [
-    (
+@dataclass(frozen=True)
+class _Rule:
+    id: str
+    pattern: re.Pattern
+    triggers: tuple[str, ...]
+    message: str
+    invert: bool = False  # True = fire when triggers ABSENT (doc claims feature exists but file gone)
+
+
+_RULES: list[_Rule] = [
+    # Normal rules: fire when trigger EXISTS and phrase matches (doc denies a thing that's present)
+    _Rule(
         "R1-no-cli",
         re.compile(
             r"(?i)no\s+CLI\s+exists"
@@ -29,56 +39,87 @@ _RULES = [
         ("src/codeforerunner/cli.py",),
         "doc claims no CLI exists, but src/codeforerunner/cli.py is present",
     ),
-    (
+    _Rule(
         "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",
     ),
-    (
+    _Rule(
         "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",
     ),
-    (
+    _Rule(
         "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",
     ),
-    (
+    _Rule(
         "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",
     ),
-    (
+    _Rule(
         "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",
     ),
-    (
+    _Rule(
         "R6b-no-makefile",
         re.compile(r"(?i)no\s+Makefile"),
         ("Makefile",),
         "doc claims no Makefile, but Makefile is present",
     ),
-    (
+    _Rule(
         "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",
     ),
-    (
+    _Rule(
         "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",
     ),
+    # Inverse rules: fire when trigger ABSENT and phrase matches (doc claims thing exists but file gone)
+    _Rule(
+        "RI1-missing-cli",
+        re.compile(
+            r"(?i)\bforerunner\s+(?:init|scan|doc|check|generate|doctor)\b"
+        ),
+        ("src/codeforerunner/cli.py",),
+        "doc references forerunner CLI commands, but src/codeforerunner/cli.py is absent",
+        invert=True,
+    ),
+    _Rule(
+        "RI5-missing-python-package",
+        re.compile(r"(?i)\bpipx?\s+install\s+codeforerunner\b"),
+        ("pyproject.toml",),
+        "doc claims package is installable via pip/pipx, but pyproject.toml is absent",
+        invert=True,
+    ),
+    _Rule(
+        "RI7-missing-mcp",
+        re.compile(r"(?i)\bforerunner\s+mcp-server\b"),
+        ("src/codeforerunner/mcp_server.py",),
+        "doc references forerunner mcp-server, but src/codeforerunner/mcp_server.py is absent",
+        invert=True,
+    ),
 ]
 
+_VERSION_PIN_RE = re.compile(
+    r"(?:codeforerunner==|codeforerunner@v)"
+    r"(\d+\.\d+\.\d+)"
+)
+_PYPROJECT_VERSION_RE = re.compile(r'^version\s*=\s*"(\d+\.\d+\.\d+)"', re.MULTILINE)
+_CHANGELOG_FILENAME = "CHANGELOG.md"
+
 
 def _trigger_exists(repo: Path, patterns: tuple[str, ...]) -> bool:
     for pat in patterns:
@@ -114,6 +155,54 @@ def _path_ignored(repo: Path, doc: Path, ignore_patterns: tuple[str, ...]) -> bo
     return any(fnmatch.fnmatch(rel, pat) for pat in ignore_patterns)
 
 
+def _current_version(repo: Path) -> str | None:
+    pyproject = repo / "pyproject.toml"
+    if not pyproject.is_file():
+        return None
+    try:
+        text = pyproject.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    m = _PYPROJECT_VERSION_RE.search(text)
+    return m.group(1) if m else None
+
+
+def _check_version_drift(
+    repo: Path,
+    docs: list[Path],
+    ignore_patterns: tuple[str, ...],
+    enabled: set[str] | None,
+) -> list[Violation]:
+    if enabled is not None and "RV1-version-drift" not in enabled:
+        return []
+    current = _current_version(repo)
+    if current is None:
+        return []
+    violations: list[Violation] = []
+    for doc in docs:
+        if doc.name == _CHANGELOG_FILENAME:
+            continue
+        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 m in _VERSION_PIN_RE.finditer(line):
+                pinned = m.group(1)
+                if pinned != current:
+                    violations.append(
+                        Violation(
+                            path=doc,
+                            line=lineno,
+                            rule_id="RV1-version-drift",
+                            message=f"version pin {pinned!r} does not match current {current!r}",
+                        )
+                    )
+    return violations
+
+
 def run(repo: Path, config: CheckConfig | None = None) -> list[Violation]:
     """Scan repo docs for drift; return list of violations.
 
@@ -124,16 +213,18 @@ def run(repo: Path, config: CheckConfig | None = None) -> list[Violation]:
     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 []
+    docs = _scanned_docs(repo)
+
+    active_rules: list[_Rule] = []
+    for rule in _RULES:
+        if enabled is not None and rule.id not in enabled:
+            continue
+        trigger_found = _trigger_exists(repo, rule.triggers)
+        if (not rule.invert and trigger_found) or (rule.invert and not trigger_found):
+            active_rules.append(rule)
 
     violations: list[Violation] = []
-    for doc in _scanned_docs(repo):
+    for doc in docs:
         if _path_ignored(repo, doc, ignore_patterns):
             continue
         try:
@@ -141,11 +232,13 @@ def run(repo: Path, config: CheckConfig | None = None) -> list[Violation]:
         except (OSError, UnicodeDecodeError):
             continue
         for lineno, line in enumerate(text.splitlines(), start=1):
-            for rid, rx, msg in active_rules:
-                if rx.search(line):
+            for rule in active_rules:
+                if rule.pattern.search(line):
                     violations.append(
-                        Violation(path=doc, line=lineno, rule_id=rid, message=msg)
+                        Violation(path=doc, line=lineno, rule_id=rule.id, message=rule.message)
                     )
+
+    violations.extend(_check_version_drift(repo, docs, ignore_patterns, enabled))
     return violations
 
 

codeforerunner/cli.py

@@ -1,4 +1,4 @@
-"""Thin CLI orchestration. Product logic lives in `prompts/`. See SPEC.md §D.cli."""
+"""Thin CLI orchestration. Product logic lives in prompts/. See SPEC.md §D.cli."""
 
 from __future__ import annotations
 
@@ -8,36 +8,29 @@ import sys
 from pathlib import Path
 from typing import Sequence
 
+from codeforerunner.bundle import find_prompts_root, resolve_bundle
+
 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"
+    """Resolve base + partials + task bundle to stdout."""
+    try:
+        prompts_root = find_prompts_root(args.repo)
+    except FileNotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    task_path = prompts_root / "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
 
+    repo_root = Path(args.repo) if args.repo else Path.cwd()
     if (
         args.task not in SCAN_EXEMPT_TASKS
-        and (root / "forerunner.config.yaml").is_file()
+        and (repo_root / "forerunner.config.yaml").is_file()
         and not os.environ.get(SCAN_DONE_ENV)
     ):
         print(
@@ -46,18 +39,11 @@ def cmd_doc(args: argparse.Namespace) -> int:
             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")
+    try:
+        sys.stdout.write(resolve_bundle(prompts_root, args.task))
+    except FileNotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
     return 0
 
 
@@ -89,11 +75,8 @@ def cmd_scan(args: argparse.Namespace) -> int:
 
 
 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()
+    """Run check rules when forerunner.config.yaml present. Silent no-op otherwise."""
+    root = Path(args.repo).resolve() if args.repo else Path.cwd()
     from codeforerunner import check as _check
     from codeforerunner.config import ConfigError, load_from_repo
     try:
@@ -112,8 +95,12 @@ def cmd_check(args: argparse.Namespace) -> int:
 
 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)
+    try:
+        prompts_root = find_prompts_root(args.repo)
+    except FileNotFoundError as e:
+        print(f"mcp_server: {e}", file=sys.stderr)
+        return 2
+    return mcp_server.serve(prompts_root)
 
 
 def cmd_generate(args: argparse.Namespace) -> int:
@@ -121,8 +108,8 @@ def cmd_generate(args: argparse.Namespace) -> int:
     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)
+    repo_root = Path(args.repo).resolve() if args.repo else Path.cwd()
+    cfg = load_from_repo(repo_root)
 
     provider_name = args.provider or (cfg.provider if cfg else "anthropic")
     model = args.model or (cfg.model if cfg else None)
@@ -133,7 +120,6 @@ def cmd_generate(args: argparse.Namespace) -> int:
     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:
@@ -146,12 +132,20 @@ def cmd_generate(args: argparse.Namespace) -> int:
     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,
-        )
+        print(f"error: missing API key; set ${env_var}", file=sys.stderr)
         return 3
 
+    if getattr(args, "stream", False):
+        try:
+            for chunk in provider.stream(prompt=buf.getvalue(), model=model, api_key=api_key):
+                sys.stdout.write(chunk)
+                sys.stdout.flush()
+        except _providers.ProviderError as e:
+            print(f"error: {provider_name} provider failed: {e}", file=sys.stderr)
+            return 4
+        sys.stdout.write("\n")
+        return 0
+
     try:
         result = provider.complete(prompt=buf.getvalue(), model=model, api_key=api_key)
     except _providers.ProviderError as e:
@@ -168,7 +162,15 @@ def cmd_generate(args: argparse.Namespace) -> int:
 
 def cmd_doctor(args: argparse.Namespace) -> int:
     from codeforerunner import doctor
-    root = _repo_root(Path(args.repo) if args.repo else None)
+    from codeforerunner.config import CONFIG_FILENAME
+    root = Path(args.repo).resolve() if args.repo else Path.cwd()
+    if getattr(args, "fix", False):
+        cfg_path = root / CONFIG_FILENAME
+        if not cfg_path.is_file():
+            cfg_path.write_text(doctor.starter_config(), encoding="utf-8")
+            print(f"wrote {cfg_path}", file=sys.stderr)
+        else:
+            print(f"{cfg_path} already exists; skipping --fix", file=sys.stderr)
     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
@@ -179,7 +181,7 @@ def build_parser() -> 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/)")
+    p.add_argument("--repo", default=argparse.SUPPRESS, help="path to repo root")
     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>")
@@ -209,15 +211,26 @@ def build_parser() -> argparse.ArgumentParser:
     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.add_argument(
+        "--repo",
+        default=argparse.SUPPRESS,
+        help="path containing prompts/tasks/ (default: package-bundled prompts)",
+    )
     s_mcp.set_defaults(func=cmd_mcp_server)
 
     s_doctor = sub.add_parser("doctor", help="health report: skill parity + marketplace + installed dests")
+    s_doctor.add_argument(
+        "--fix",
+        action="store_true",
+        help="write a starter forerunner.config.yaml if absent",
+    )
     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.add_argument("--stream", action="store_true", help="stream output token-by-token")
     s_gen.set_defaults(func=cmd_generate)
 
     from codeforerunner import installer
@@ -229,6 +242,8 @@ def build_parser() -> argparse.ArgumentParser:
 def main(argv: Sequence[str] | None = None) -> int:
     parser = build_parser()
     args = parser.parse_args(argv)
+    if not hasattr(args, "repo"):
+        args.repo = None
     return args.func(args)
 
 

codeforerunner/doctor.py

@@ -274,6 +274,26 @@ def _check_provider_api_key(repo: Path) -> list[Finding]:
     ]
 
 
+_STARTER_CONFIG = """\
+# forerunner.config.yaml — generated by `forerunner doctor --fix`
+# See https://github.com/derek-palmer/codeforerunner for docs.
+
+enabled_rules:
+  - R1-no-cli
+  - R2-no-pre-commit
+  - R3-no-ci
+  - R4-no-installer
+  - R5-no-python-package
+  - R7-no-mcp
+  - R8-no-marketplace
+ignore_paths: []
+"""
+
+
+def starter_config() -> str:
+    return _STARTER_CONFIG
+
+
 def run(repo: Path) -> list[Finding]:
     repo = repo.resolve()
     findings: list[Finding] = []

codeforerunner/installer.py

@@ -291,9 +291,7 @@ def add_subparser(sub: argparse._SubParsersAction) -> None:
 
 
 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)
+    root = Path(args.repo).resolve() if args.repo else Path.cwd()
     return install(
         agent=args.agent,
         repo_root=root,