codeforerunner 0.4.1__py3-none-any.whl → 0.4.3__py3-none-any.whl

codeforerunner/__init__.py

@@ -1,6 +1,8 @@
+"""codeforerunner — prompt-first repo documentation tooling."""
+
 from importlib.metadata import PackageNotFoundError, version
 
 try:
     __version__ = version("codeforerunner")
-except PackageNotFoundError:
+except PackageNotFoundError:  # pragma: no cover
     __version__ = "0.0.0"  # running from source without install

codeforerunner/bundle.py

@@ -25,7 +25,8 @@ def find_prompts_root(repo_arg: str | Path | None = None) -> Path:
         )
 
     here = Path.cwd().resolve()
-    for candidate in [here, *here.parents]:
+    parents = list(here.parents)
+    for candidate in [here, *parents[:10]]:
         if (candidate / "prompts" / "tasks").is_dir():
             return candidate / "prompts"
 

codeforerunner/check.py

@@ -11,6 +11,8 @@ from codeforerunner.config import CheckConfig
 
 @dataclass(frozen=True)
 class Violation:
+    """Single rule match: which doc, which line, which rule, and what it means."""
+
     path: Path
     line: int
     rule_id: str

codeforerunner/cli.py

@@ -8,24 +8,24 @@ import sys
 from pathlib import Path
 from typing import Sequence
 
-from codeforerunner.bundle import find_prompts_root, resolve_bundle
+from codeforerunner.bundle import find_prompts_root, resolve_bundle as _resolve_bundle
 
 SCAN_EXEMPT_TASKS = frozenset({"scan", "init-agent-onboarding"})
 SCAN_DONE_ENV = "FORERUNNER_SCAN_DONE"
 
 
-def cmd_doc(args: argparse.Namespace) -> int:
-    """Resolve base + partials + task bundle to stdout."""
+def _get_bundle(args: argparse.Namespace) -> tuple[str, int]:
+    """Resolve bundle for args.task. Returns (bundle_text, exit_code). exit_code != 0 on error."""
     try:
         prompts_root = find_prompts_root(args.repo)
     except FileNotFoundError as e:
         print(f"error: {e}", file=sys.stderr)
-        return 2
+        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
+        return "", 2
 
     repo_root = Path(args.repo) if args.repo else Path.cwd()
     if (
@@ -40,10 +40,18 @@ def cmd_doc(args: argparse.Namespace) -> int:
         )
 
     try:
-        sys.stdout.write(resolve_bundle(prompts_root, args.task))
+        return _resolve_bundle(prompts_root, args.task), 0
     except FileNotFoundError as e:
         print(f"error: {e}", file=sys.stderr)
-        return 2
+        return "", 2
+
+
+def cmd_doc(args: argparse.Namespace) -> int:
+    """Resolve base + partials + task bundle to stdout."""
+    bundle, rc = _get_bundle(args)
+    if rc != 0:
+        return rc
+    sys.stdout.write(bundle)
     return 0
 
 
@@ -53,7 +61,7 @@ def _doc_for(args: argparse.Namespace, task: str) -> int:
 
 
 def cmd_init(args: argparse.Namespace) -> int:
-    """Default + --agents-only = onboarding bundle only. --full prepends scan."""
+    """Emit onboarding bundle; prepend scan bundle when --full is given."""
     if getattr(args, "full", False):
         sys.stdout.write("<!-- forerunner init --full: section 1/2 (scan) -->\n")
         rc = _doc_for(args, "scan")
@@ -64,6 +72,7 @@ def cmd_init(args: argparse.Namespace) -> int:
 
 
 def cmd_scan(args: argparse.Namespace) -> int:
+    """Emit the scan prompt bundle and hint about FORERUNNER_SCAN_DONE."""
     rc = _doc_for(args, "scan")
     if rc == 0:
         print(
@@ -94,6 +103,7 @@ def cmd_check(args: argparse.Namespace) -> int:
 
 
 def cmd_mcp_server(args: argparse.Namespace) -> int:
+    """Start the stdio MCP server exposing prompt bundles as tools."""
     from codeforerunner import mcp_server
     try:
         prompts_root = find_prompts_root(args.repo)
@@ -104,13 +114,28 @@ def cmd_mcp_server(args: argparse.Namespace) -> int:
 
 
 def cmd_generate(args: argparse.Namespace) -> int:
-    """Resolve the bundle for <task> and send it to the configured provider."""
+    """Resolve the bundle for <task> and send it to the configured provider.
+
+    With --prompt-only (or when no provider/key/Ollama is reachable), outputs
+    the assembled prompt bundle to stdout for the calling agent to process.
+    """
     from codeforerunner import providers as _providers
     from codeforerunner.config import load_from_repo
 
     repo_root = Path(args.repo).resolve() if args.repo else Path.cwd()
     cfg = load_from_repo(repo_root)
 
+    ns = argparse.Namespace(repo=getattr(args, "repo", None), task=args.task)
+
+    # --prompt-only: output the bundle and stop; the calling agent is the model.
+    if getattr(args, "prompt_only", False):
+        return cmd_doc(ns)
+
+    bundle, rc = _get_bundle(ns)
+    if rc != 0:
+        return rc
+
+
     explicit_provider = args.provider or (cfg.provider if cfg else None)
     provider_name = explicit_provider or "anthropic"
     model = args.model or (cfg.model if cfg else None)
@@ -118,18 +143,6 @@ def cmd_generate(args: argparse.Namespace) -> int:
     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)
-    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":
@@ -140,16 +153,26 @@ def cmd_generate(args: argparse.Namespace) -> int:
             if not args.model:
                 model = provider.default_model
             print("info: no API key; falling back to Ollama (local mode)", file=sys.stderr)
+        elif explicit_provider is None:
+            # Skill-mode auto-detect: no provider configured, no Ollama — output
+            # the prompt bundle for the calling agent to process directly.
+            sys.stdout.write(bundle)
+            if sys.stdout.isatty():
+                print(
+                    "\ninfo: no provider configured and Ollama not running.\n"
+                    "      Prompt bundle written above — paste into your agent,\n"
+                    "      or run: forerunner generate --prompt-only "
+                    f"{args.task}",
+                    file=sys.stderr,
+                )
+            return 0
         else:
-            msg = f"error: missing API key; set ${env_var}"
-            if explicit_provider is None:
-                msg += "\nhint: start Ollama for keyless local generation (https://ollama.com)"
-            print(msg, 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):
+            for chunk in provider.stream(prompt=bundle, model=model, api_key=api_key):
                 sys.stdout.write(chunk)
                 sys.stdout.flush()
         except _providers.ProviderError as e:
@@ -159,7 +182,7 @@ def cmd_generate(args: argparse.Namespace) -> int:
         return 0
 
     try:
-        result = provider.complete(prompt=buf.getvalue(), model=model, api_key=api_key)
+        result = provider.complete(prompt=bundle, model=model, api_key=api_key)
     except _providers.ProviderError as e:
         print(f"error: {provider_name} provider failed: {e}", file=sys.stderr)
         return 4
@@ -173,6 +196,7 @@ def cmd_generate(args: argparse.Namespace) -> int:
 
 
 def cmd_doctor(args: argparse.Namespace) -> int:
+    """Run health checks and print a single-screen report; exit 1 on errors."""
     from codeforerunner import doctor
     from codeforerunner.config import CONFIG_FILENAME
     root = Path(args.repo).resolve() if args.repo else Path.cwd()
@@ -183,12 +207,13 @@ def cmd_doctor(args: argparse.Namespace) -> int:
             print(f"wrote {cfg_path}", file=sys.stderr)
         else:
             print(f"{cfg_path} already exists; skipping --fix", file=sys.stderr)
-    findings = doctor.run(root)
+    findings = doctor.run(root, run_scripts=getattr(args, "run_scripts", False))
     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:
+    """Build and return the top-level argument parser with all subcommands registered."""
     p = argparse.ArgumentParser(
         prog="forerunner",
         description="Prompt-first repo documentation tooling. Thin CLI; product logic in prompts/.",
@@ -236,6 +261,13 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="write a starter forerunner.config.yaml if absent",
     )
+    s_doctor.add_argument(
+        "--run-scripts",
+        dest="run_scripts",
+        action="store_true",
+        default=False,
+        help="allow executing Python scripts from the target repo to validate skill copies (off by default)",
+    )
     s_doctor.set_defaults(func=cmd_doctor)
 
     s_gen = sub.add_parser("generate", help="resolve bundle for <task> and call the configured provider")
@@ -243,6 +275,12 @@ def build_parser() -> argparse.ArgumentParser:
     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.add_argument(
+        "--prompt-only",
+        dest="prompt_only",
+        action="store_true",
+        help="output the assembled prompt bundle to stdout; do not call a model (skill mode)",
+    )
     s_gen.set_defaults(func=cmd_generate)
 
     from codeforerunner import installer
@@ -252,6 +290,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def main(argv: Sequence[str] | None = None) -> int:
+    """Parse argv and dispatch to the appropriate subcommand handler."""
     parser = build_parser()
     args = parser.parse_args(argv)
     if not hasattr(args, "repo"):

codeforerunner/config.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from pathlib import Path
 from typing import Any
 
 import yaml
@@ -20,6 +19,8 @@ class ConfigError(Exception):
 
 @dataclass(frozen=True)
 class CheckConfig:
+    """Drift-check task configuration: severity gates and path filters."""
+
     block_on: tuple[str, ...] = ("HIGH", "MEDIUM")
     warn_on: tuple[str, ...] = ("LOW",)
     enabled_rules: tuple[str, ...] | None = None  # None = all rules enabled
@@ -28,6 +29,8 @@ class CheckConfig:
 
 @dataclass(frozen=True)
 class VersionAuditConfig:
+    """Version-audit task configuration: staleness window and live EOL data toggle."""
+
     enabled: bool = True
     stale_after_days: int = 30
     fetch_live_eol_data: bool = False
@@ -35,11 +38,10 @@ class VersionAuditConfig:
 
 @dataclass(frozen=True)
 class ForerunnerConfig:
+    """Top-level forerunner.config.yaml configuration."""
+
     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)
@@ -56,7 +58,7 @@ def _require_type(value: Any, expected: type, field_name: str) -> Any:
 
 
 def _coerce_str_tuple(value: Any, field_name: str) -> tuple[str, ...]:
-    if value is None:
+    if value is None:  # pragma: no cover - callers supply defaults, never pass None
         return ()
     if not isinstance(value, list):
         raise ConfigError(f"{field_name}: expected list, got {type(value).__name__}")
@@ -75,7 +77,7 @@ def _parse_api_key_env(raw: Any) -> dict[str, str]:
         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):
+        if not isinstance(k, str):  # pragma: no cover - YAML keys are always strings
             raise ConfigError(
                 f"api_key_env: keys must be strings, got {type(k).__name__}"
             )
@@ -117,13 +119,20 @@ def _parse_check(raw: Any) -> CheckConfig:
     )
 
 
+def _to_int(value: Any, field_name: str) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError) as e:
+        raise ConfigError(f"{field_name}: expected integer, got {value!r}") from e
+
+
 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)),
+        stale_after_days=_to_int(raw.get("stale_after_days", 30), "tasks.version_audit.stale_after_days"),
         fetch_live_eol_data=bool(raw.get("fetch_live_eol_data", False)),
     )
 
@@ -147,10 +156,9 @@ def parse(raw: dict[str, Any] | None) -> ForerunnerConfig:
     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)),
+        approaching_eol_threshold_months=_to_int(
+            raw.get("approaching_eol_threshold_months", 6), "approaching_eol_threshold_months"
+        ),
         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")),

codeforerunner/doctor.py

@@ -6,6 +6,7 @@ import argparse
 import importlib.util
 import os
 import sys
+import uuid
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Callable
@@ -32,6 +33,8 @@ _DEFAULT_PROVIDER_ENV = {
 
 @dataclass(frozen=True)
 class Finding:
+    """Single health-check result with severity, check name, and human message."""
+
     severity: str  # "ok" | "warn" | "error"
     check: str
     message: str
@@ -50,17 +53,27 @@ def _installed_marketplace_destination() -> Path:
 
 
 def _load_script_module(repo: Path, relpath: str, module_name: str):
+    # L3: unique name prevents stale cached module on repeated calls
+    unique_name = f"{module_name}_{uuid.uuid4().hex}"
     script_path = repo / relpath
-    spec = importlib.util.spec_from_file_location(module_name, script_path)
+    spec = importlib.util.spec_from_file_location(unique_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
+    sys.modules[unique_name] = module
     spec.loader.exec_module(module)
     return module
 
 
-def _check_skill_body_parity(repo: Path) -> list[Finding]:
+def _check_skill_body_parity(repo: Path, run_scripts: bool = False) -> list[Finding]:
+    if not run_scripts:
+        return [
+            Finding(
+                "warn",
+                "skill-body-parity",
+                "skipping script validation (pass --run-scripts to allow executing repo scripts)",
+            )
+        ]
     try:
         skill_mod = _load_script_module(
             repo, "scripts/validate_skill_copies.py", "_forerunner_doctor_skill_copies"
@@ -104,7 +117,15 @@ def _check_skill_body_parity(repo: Path) -> list[Finding]:
     return findings
 
 
-def _check_codex_marketplace(repo: Path) -> list[Finding]:
+def _check_codex_marketplace(repo: Path, run_scripts: bool = False) -> list[Finding]:
+    if not run_scripts:
+        return [
+            Finding(
+                "warn",
+                "codex-marketplace",
+                "skipping script validation (pass --run-scripts to allow executing repo scripts)",
+            )
+        ]
     try:
         mp_mod = _load_script_module(
             repo,
@@ -224,6 +245,19 @@ def _check_config_loadable(repo: Path) -> list[Finding]:
     return [Finding("ok", "config-loadable", f"{CONFIG_FILENAME} parses cleanly")]
 
 
+def _skill_mode_active() -> bool:
+    """Return True if any installed skill destination has managed markers (agent is the model)."""
+    for dest in _installed_skill_destinations():
+        if dest.exists():
+            try:
+                text = dest.read_text(encoding="utf-8")
+                if MARKER_BEGIN in text and MARKER_END in text:
+                    return True
+            except OSError:
+                pass
+    return False
+
+
 def _check_provider_api_key(repo: Path) -> list[Finding]:
     from codeforerunner.providers.ollama import is_available as _ollama_available
 
@@ -237,11 +271,19 @@ def _check_provider_api_key(repo: Path) -> list[Finding]:
                     "no config; Ollama running — generate will use local mode automatically",
                 )
             ]
+        if _skill_mode_active():
+            return [
+                Finding(
+                    "ok",
+                    "provider-api-key",
+                    "no config; skill mode active — the installed agent is the model, no API key needed",
+                )
+            ]
         return [
             Finding(
                 "ok",
                 "provider-api-key",
-                f"no {CONFIG_FILENAME}; set an API key in config or start Ollama for keyless local generation",
+                f"no {CONFIG_FILENAME}; set an API key in config, start Ollama, or use skill mode (`forerunner generate --prompt-only`)",
             )
         ]
     try:
@@ -275,6 +317,8 @@ def _check_provider_api_key(repo: Path) -> list[Finding]:
     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")]
+    # Emit the same warning regardless of skill mode: an explicit provider in config
+    # means the user intends to use that provider, so a missing key is always a real problem.
     return [
         Finding(
             "warn",
@@ -288,27 +332,31 @@ _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: []
+tasks:
+  check:
+    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 the default forerunner.config.yaml content written by --fix."""
     return _STARTER_CONFIG
 
 
-def run(repo: Path) -> list[Finding]:
+def run(repo: Path, run_scripts: bool = False) -> list[Finding]:
+    """Run all health checks against *repo* and return findings."""
     repo = repo.resolve()
     findings: list[Finding] = []
-    findings.extend(_check_skill_body_parity(repo))
-    findings.extend(_check_codex_marketplace(repo))
+    findings.extend(_check_skill_body_parity(repo, run_scripts=run_scripts))
+    findings.extend(_check_codex_marketplace(repo, run_scripts=run_scripts))
     findings.extend(_check_installed_destinations(repo))
     findings.extend(_check_config_loadable(repo))
     findings.extend(_check_provider_api_key(repo))
@@ -316,20 +364,18 @@ def run(repo: Path) -> list[Finding]:
 
 
 def format_report(findings: list[Finding]) -> str:
+    """Format findings as a human-readable report string with a summary line."""
     lines = [f"[{f.severity}] {f.check}: {f.message}" for f in findings]
-    counts = {"ok": 0, "warn": 0, "error": 0}
+    counts: dict[str, int] = {"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"
-    )
+        counts[f.severity] += 1
+    summary = f"summary: {counts['ok']} ok, {counts['warn']} warn, {counts['error']} error"
     lines.append(summary)
     return "\n".join(lines)
 
 
 def main(argv: list[str] | None = None) -> int:
+    """Entry point for `forerunner doctor`; returns 1 when any finding is an error."""
     parser = argparse.ArgumentParser(
         prog="forerunner doctor",
         description="Single-screen health report for codeforerunner repo.",
@@ -340,9 +386,15 @@ def main(argv: list[str] | None = None) -> int:
         default=Path.cwd(),
         help="repo root (default: cwd)",
     )
+    parser.add_argument(
+        "--run-scripts",
+        action="store_true",
+        default=False,
+        help="allow executing Python scripts from the target repo (off by default for safety)",
+    )
     args = parser.parse_args(argv)
 
-    findings = run(args.repo)
+    findings = run(args.repo, run_scripts=args.run_scripts)
     print(format_report(findings))
     return 1 if any(f.severity == "error" for f in findings) else 0
 

codeforerunner/installer.py

@@ -41,6 +41,8 @@ TASK_SKILL_SLUGS: tuple[str, ...] = (
 
 @dataclass(frozen=True)
 class Target:
+    """Resolved install destination: agent name + absolute path."""
+
     name: str
     path: Path
 
@@ -50,6 +52,7 @@ def _home() -> Path:
 
 
 def resolve_target(agent: str, override: Path | None) -> Target:
+    """Return the default install Target for the given agent, or use override path."""
     if agent == "generic":
         if override is None:
             raise ValueError("generic target requires --path PATH")
@@ -95,6 +98,7 @@ def install_all_skills(
         src_path = repo_root / "plugins" / "codeforerunner" / "skills" / slug / "SKILL.md"
         if not src_path.is_file():
             print(f"warning: skill source not found: {src_path}", file=err)
+            any_error = True
             continue
         try:
             target = resolve_skill_target(agent, slug)
@@ -116,11 +120,16 @@ def install_all_skills(
         print(f"{prefix}{action}: {dest}", file=out)
         if not check_only:
             dest.parent.mkdir(parents=True, exist_ok=True)
-            dest.write_bytes(src_path.read_bytes())
+            try:
+                dest.write_bytes(src_path.read_bytes())
+            except OSError as e:
+                print(f"error: failed to write {dest}: {e}", file=err)
+                any_error = True
     return EXIT_OK if not any_error else EXIT_BODY_MISMATCH
 
 
 def resolve_marketplace_target(agent: str, override: Path | None) -> Target:
+    """Return the marketplace install Target for the given agent, or use override path."""
     if agent == "generic":
         if override is None:
             raise ValueError("generic marketplace target requires --path PATH")
@@ -176,6 +185,7 @@ def render(source_text: str, dest_existing: str | None, agent: str) -> str:
 
 
 def find_markers(text: str) -> tuple[int, int] | None:
+    """Return (start, end) byte offsets of the managed region, or None if absent."""
     a = text.find(MARKER_BEGIN)
     if a < 0:
         return None
@@ -188,7 +198,8 @@ def find_markers(text: str) -> tuple[int, int] | None:
 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
+    if span is None:
+        raise RuntimeError("overlay: span is None — this is a bug")
     a, b = span
     managed = f"{MARKER_BEGIN}\n{source_body}\n{MARKER_END}"
     return dest_text[:a] + managed + dest_text[b:]
@@ -196,12 +207,15 @@ def overlay(dest_text: str, source_body: str) -> str:
 
 @dataclass
 class Plan:
+    """Pending install action computed by plan_install or plan_marketplace."""
+
     action: str  # "create" | "update" | "skip" | "abort"
     reason: str
     target: Target
     new_content: str | None = None
 
     def write(self) -> None:
+        """Execute the plan: create or update the destination file."""
         if self.action in ("skip", "abort"):
             return
         assert self.new_content is not None
@@ -300,6 +314,7 @@ def install(
     out=None,
     err=None,
 ) -> int:
+    """Run one install operation (skill or marketplace). Returns an EXIT_* code."""
     out = out or sys.stdout
     err = err or sys.stderr
 
@@ -350,6 +365,7 @@ def install(
 
 
 def add_subparser(sub: argparse._SubParsersAction) -> None:
+    """Register the `forerunner install` subcommand onto *sub*."""
     p = sub.add_parser("install", help="install skill(s) into agent-specific directories (D.installer)")
     p.add_argument("agent", choices=["codex", "claude", "generic"], nargs="?",
                    help="target agent (omit with --all to install to all detected agents)")

codeforerunner/mcp_server.py

@@ -27,11 +27,12 @@ def _list_tasks(prompts_root: Path) -> list[Path]:
 
 def _description_for(task_path: Path) -> str:
     """First non-empty markdown line, stripped of leading '#' and whitespace."""
-    for raw in task_path.read_text(encoding="utf-8").splitlines():
-        line = raw.strip()
-        if not line:
-            continue
-        return line.lstrip("#").strip()
+    with task_path.open(encoding="utf-8") as f:
+        for raw in f:
+            line = raw.strip()
+            if not line:
+                continue
+            return line.lstrip("#").strip()
     return task_path.stem
 
 
@@ -68,6 +69,7 @@ def _handle(prompts_root: Path, msg: dict[str, Any], state: dict[str, Any]) -> d
         return None
 
     if method == "initialize":
+        state["initialized"] = True
         return _ok(
             req_id,
             {
@@ -77,13 +79,19 @@ def _handle(prompts_root: Path, msg: dict[str, Any], state: dict[str, Any]) -> d
             },
         )
 
+    if not state.get("initialized"):
+        return _err(req_id, -32002, "Server not initialized")
+
     if method == "tools/list":
         return _ok(req_id, {"tools": _tools(prompts_root)})
 
     if method == "tools/call":
         name = params.get("name")
+        if not isinstance(name, str) or "/" in name or "\\" in name or ".." in name:
+            return _err(req_id, -32602, f"invalid tool name: {name!r}")
         task_path = prompts_root / "tasks" / f"{name}.md"
-        if not isinstance(name, str) or not task_path.is_file():
+        tasks_root = (prompts_root / "tasks").resolve()
+        if not task_path.resolve().is_relative_to(tasks_root) or not task_path.is_file():
             return _err(req_id, -32602, f"unknown tool: {name!r}")
         if name not in SCAN_EXEMPT_TOOLS and not state.get("scan_called"):
             return _err(
@@ -106,7 +114,8 @@ def _handle(prompts_root: Path, msg: dict[str, Any], state: dict[str, Any]) -> d
 
 
 def serve(prompts_root: Path, stdin: Iterable[str] = sys.stdin, stdout=sys.stdout, stderr=sys.stderr) -> int:
-    state: dict[str, Any] = {"scan_called": False}
+    """Run the JSON-RPC 2.0 MCP server loop over *stdin*/*stdout* until EOF."""
+    state: dict[str, Any] = {"scan_called": False, "initialized": False}
     for raw in stdin:
         line = raw.strip()
         if not line:
@@ -133,6 +142,7 @@ def serve(prompts_root: Path, stdin: Iterable[str] = sys.stdin, stdout=sys.stdou
 
 
 def main(argv: list[str] | None = None) -> int:
+    """Locate prompts root and start the MCP server; returns 2 if prompts not found."""
     try:
         prompts_root = find_prompts_root()
     except FileNotFoundError as e:
@@ -141,5 +151,5 @@ def main(argv: list[str] | None = None) -> int:
     return serve(prompts_root)
 
 
-if __name__ == "__main__":
+if __name__ == "__main__":  # pragma: no cover
     raise SystemExit(main())

codeforerunner/providers/__init__.py

@@ -30,6 +30,7 @@ REGISTRY: dict[str, type] = {
 
 
 def get(name: str) -> type:
+    """Return the provider class for *name*, or raise ProviderError if unknown."""
     if name not in REGISTRY:
         raise ProviderError(
             f"unknown provider '{name}' (expected one of {sorted(REGISTRY)})"

codeforerunner/providers/anthropic.py

@@ -11,6 +11,8 @@ from codeforerunner.providers.base import CompletionResult, ProviderError
 
 
 class AnthropicProvider:
+    """Anthropic Messages API provider using stdlib HTTP."""
+
     name = "anthropic"
     default_env_var = "ANTHROPIC_API_KEY"
     default_model = "claude-opus-4-7"
@@ -24,6 +26,7 @@ class AnthropicProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> CompletionResult:
+        """Send *prompt* to the Anthropic Messages API and return the full response."""
         if not api_key:
             raise ProviderError(f"missing API key (set ${self.default_env_var})")
         model = model or self.default_model
@@ -45,7 +48,7 @@ class AnthropicProvider:
             },
         )
         try:
-            with urllib.request.urlopen(req) as resp:
+            with urllib.request.urlopen(req, timeout=120) as resp:
                 raw = resp.read()
         except urllib.error.HTTPError as e:
             snippet = (e.read() or b"")[:500].decode("utf-8", errors="replace")
@@ -68,6 +71,7 @@ class AnthropicProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> Iterator[str]:
+        """Yield text chunks from the Anthropic streaming Messages API."""
         if not api_key:
             raise ProviderError(f"missing API key (set ${self.default_env_var})")
         model = model or self.default_model
@@ -90,7 +94,7 @@ class AnthropicProvider:
             },
         )
         try:
-            resp = urllib.request.urlopen(req)
+            resp = urllib.request.urlopen(req, timeout=120)
         except urllib.error.HTTPError as e:
             snippet = (e.read() or b"")[:500].decode("utf-8", errors="replace")
             raise ProviderError(f"HTTP {e.code}: {snippet}") from e

codeforerunner/providers/base.py

@@ -8,12 +8,16 @@ from typing import Iterator, Protocol
 
 @dataclass(frozen=True)
 class CompletionResult:
+    """Completed text response returned by a provider."""
+
     text: str
     model: str
     usage: dict | None = None  # provider-reported token counts; None if unknown
 
 
 class Provider(Protocol):
+    """Structural protocol that all LLM provider classes must satisfy."""
+
     name: str
     default_env_var: str  # e.g. "ANTHROPIC_API_KEY"
     default_model: str  # provider's recommended default
@@ -24,7 +28,9 @@ class Provider(Protocol):
         prompt: str,
         model: str | None = None,
         api_key: str | None = None,
-    ) -> CompletionResult: ...
+    ) -> CompletionResult:
+        """Send *prompt* and return the full completion result."""
+        ...
 
     def stream(
         self,
@@ -32,7 +38,9 @@ class Provider(Protocol):
         prompt: str,
         model: str | None = None,
         api_key: str | None = None,
-    ) -> Iterator[str]: ...
+    ) -> Iterator[str]:
+        """Yield text chunks from *prompt* as they arrive from the provider."""
+        ...
 
 
 class ProviderError(Exception):

codeforerunner/providers/google.py

@@ -12,10 +12,14 @@ from codeforerunner.providers.base import CompletionResult, ProviderError
 
 
 class GoogleProvider:
+    """Google Gemini generateContent provider using stdlib HTTP."""
+
     name = "google"
     default_env_var = "GOOGLE_API_KEY"
     default_model = "gemini-2.5-pro"
 
+    # Google REST API requires the key in the URL query string — this is the documented
+    # mechanism and cannot be changed. Be aware the key may appear in proxy/server logs.
     endpoint_template = (
         "https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent?key={key}"
     )
@@ -31,6 +35,7 @@ class GoogleProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> CompletionResult:
+        """Send *prompt* to the Gemini generateContent endpoint and return the full response."""
         if not api_key:
             raise ProviderError(f"missing API key (set ${self.default_env_var})")
         model = model or self.default_model
@@ -48,7 +53,7 @@ class GoogleProvider:
             headers={"content-type": "application/json"},
         )
         try:
-            with urllib.request.urlopen(req) as resp:
+            with urllib.request.urlopen(req, timeout=120) as resp:
                 raw = resp.read()
         except urllib.error.HTTPError as e:
             snippet = (e.read() or b"")[:500].decode("utf-8", errors="replace")
@@ -73,6 +78,7 @@ class GoogleProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> Iterator[str]:
+        """Yield text chunks from the Gemini streaming generateContent endpoint."""
         if not api_key:
             raise ProviderError(f"missing API key (set ${self.default_env_var})")
         model = model or self.default_model
@@ -90,7 +96,7 @@ class GoogleProvider:
             headers={"content-type": "application/json"},
         )
         try:
-            resp = urllib.request.urlopen(req)
+            resp = urllib.request.urlopen(req, timeout=120)
         except urllib.error.HTTPError as e:
             snippet = (e.read() or b"")[:500].decode("utf-8", errors="replace")
             raise ProviderError(f"HTTP {e.code}: {snippet}") from e

codeforerunner/providers/ollama.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import os
 import urllib.error
+import urllib.parse
 import urllib.request
 from typing import Iterator
 
@@ -12,11 +13,32 @@ from codeforerunner.providers.base import CompletionResult, ProviderError
 
 DEFAULT_HOST = "http://localhost:11434"
 
+_SAFE_LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+def _validate_ollama_base(base: str) -> None:
+    """Reject URLs that look like cloud metadata endpoints or use unexpected schemes."""
+    try:
+        parsed = urllib.parse.urlparse(base)
+    except Exception as e:  # pragma: no cover - urlparse never raises
+        raise ValueError(f"OLLAMA_HOST: invalid URL: {e}") from e
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(
+            f"OLLAMA_HOST: scheme must be http or https, got {parsed.scheme!r}"
+        )
+    host = parsed.hostname or ""
+    if "169.254." in host:
+        raise ValueError(
+            f"OLLAMA_HOST: refusing connection to link-local address {host!r} "
+            "(looks like a cloud metadata endpoint)"
+        )
+
 
 def is_available(host: str | None = None) -> bool:
     """Return True if an Ollama instance is reachable at the configured host."""
     base = (host or os.environ.get("OLLAMA_HOST") or DEFAULT_HOST).rstrip("/")
     try:
+        _validate_ollama_base(base)
         urllib.request.urlopen(f"{base}/api/tags", timeout=2)
         return True
     except Exception:
@@ -24,6 +46,8 @@ def is_available(host: str | None = None) -> bool:
 
 
 class OllamaProvider:
+    """Ollama local provider using stdlib HTTP."""
+
     name = "ollama"
     default_env_var = "OLLAMA_HOST"
     default_model = "llama3"
@@ -35,9 +59,11 @@ class OllamaProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> CompletionResult:
+        """Send *prompt* to the Ollama /api/generate endpoint and return the full response."""
         # api_key is interpreted as a base URL override; fall back to env then default.
         base = api_key or os.environ.get(self.default_env_var) or DEFAULT_HOST
         base = base.rstrip("/")
+        _validate_ollama_base(base)
         model = model or self.default_model
         url = f"{base}/api/generate"
         body = json.dumps(
@@ -50,7 +76,7 @@ class OllamaProvider:
             headers={"content-type": "application/json"},
         )
         try:
-            with urllib.request.urlopen(req) as resp:
+            with urllib.request.urlopen(req, timeout=120) as resp:
                 raw = resp.read()
         except urllib.error.HTTPError as e:
             snippet = (e.read() or b"")[:500].decode("utf-8", errors="replace")
@@ -73,8 +99,10 @@ class OllamaProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> Iterator[str]:
+        """Yield text chunks from the Ollama /api/generate streaming endpoint."""
         base = api_key or os.environ.get(self.default_env_var) or DEFAULT_HOST
         base = base.rstrip("/")
+        _validate_ollama_base(base)
         model = model or self.default_model
         url = f"{base}/api/generate"
         body = json.dumps(
@@ -87,7 +115,7 @@ class OllamaProvider:
             headers={"content-type": "application/json"},
         )
         try:
-            resp = urllib.request.urlopen(req)
+            resp = urllib.request.urlopen(req, timeout=120)
         except urllib.error.HTTPError as e:
             snippet = (e.read() or b"")[:500].decode("utf-8", errors="replace")
             raise ProviderError(f"HTTP {e.code}: {snippet}") from e

codeforerunner/providers/openai.py

@@ -11,6 +11,8 @@ from codeforerunner.providers.base import CompletionResult, ProviderError
 
 
 class OpenAIProvider:
+    """OpenAI chat completions provider using stdlib HTTP."""
+
     name = "openai"
     default_env_var = "OPENAI_API_KEY"
     default_model = "gpt-4o"
@@ -24,6 +26,7 @@ class OpenAIProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> CompletionResult:
+        """Send *prompt* to the OpenAI chat completions endpoint and return the full response."""
         if not api_key:
             raise ProviderError(f"missing API key (set ${self.default_env_var})")
         model = model or self.default_model
@@ -43,7 +46,7 @@ class OpenAIProvider:
             },
         )
         try:
-            with urllib.request.urlopen(req) as resp:
+            with urllib.request.urlopen(req, timeout=120) as resp:
                 raw = resp.read()
         except urllib.error.HTTPError as e:
             snippet = (e.read() or b"")[:500].decode("utf-8", errors="replace")
@@ -66,6 +69,7 @@ class OpenAIProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> Iterator[str]:
+        """Yield text chunks from the OpenAI streaming chat completions endpoint."""
         if not api_key:
             raise ProviderError(f"missing API key (set ${self.default_env_var})")
         model = model or self.default_model
@@ -86,7 +90,7 @@ class OpenAIProvider:
             },
         )
         try:
-            resp = urllib.request.urlopen(req)
+            resp = urllib.request.urlopen(req, timeout=120)
         except urllib.error.HTTPError as e:
             snippet = (e.read() or b"")[:500].decode("utf-8", errors="replace")
             raise ProviderError(f"HTTP {e.code}: {snippet}") from e

{codeforerunner-0.4.1.dist-info → codeforerunner-0.4.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeforerunner
-Version: 0.4.1
+Version: 0.4.3
 Summary: Model-agnostic repository documentation tooling (prompt-first; thin CLI).
 Author: Derek Palmer
 License-Expression: LicenseRef-Codeforerunner-SAL-0.1
@@ -175,7 +175,7 @@ forerunner check               # run any time or as pre-commit hook
 ## GitHub Action
 
 ```yaml
-- uses: derek-palmer/codeforerunner@v0.3.2
+- uses: derek-palmer/codeforerunner@v0.4.2
 ```
 
 No-op when `forerunner.config.yaml` is absent.

{codeforerunner-0.4.1.dist-info → codeforerunner-0.4.3.dist-info}/RECORD

@@ -1,11 +1,11 @@
-codeforerunner/__init__.py,sha256=4ItVS_FzLddTK77jExpkV3QJ1nHl2Bh-QIujM7Hg_5w,205
-codeforerunner/bundle.py,sha256=wWlhNaja8HPLzN-9pxiSrFD8X0mGi-c1HM9HRyVhmzk,2020
-codeforerunner/check.py,sha256=5sJVwMMSvVCrRmwBIunYbn2pINroUjONrVJAs5ov3O4,8188
-codeforerunner/cli.py,sha256=fBojCOPEEzQdXxYB0Intjhax90l7Rz7sfsgeFpozP58,9633
-codeforerunner/config.py,sha256=REs4FgmSSn7R2tLIwLJPL8VmSCGkTvw8J2SqBOggzho,6206
-codeforerunner/doctor.py,sha256=4VE7nCGdJKpzWtqK3ut-SbrOENdfLNLuvA_wxn-5fcM,10859
-codeforerunner/installer.py,sha256=60CMYbV8di-0iLE8jbsLGScdgU5VSJTOO_PhoBtqYYY,13395
-codeforerunner/mcp_server.py,sha256=oIfuAR7e_rH--B1aLOATVflyWAyGpkyeeXI4SAI4eTg,4657
+codeforerunner/__init__.py,sha256=lDClMqfAXApyQaPIWGp01yvS0zWJC-7sXTCRKPqit9M,292
+codeforerunner/bundle.py,sha256=2GByXu-oFbplWpCJuGnF_qobcHqv8YjyTZX1BU4WoJM,2053
+codeforerunner/check.py,sha256=HhhTuoFUiT2hjeK6JwjZknplJf43GqdSwZnz_V7G8n0,8272
+codeforerunner/cli.py,sha256=yWM72NR8roIM63zBFe3ibzxkDVHpD9X_-HueAdnNvo0,11442
+codeforerunner/config.py,sha256=CC9JhlKv4L3b7cRc4BiB9PHKVRoibbkBGHRBWjoZKpM,6454
+codeforerunner/doctor.py,sha256=GjMJpjXqrn4nCtkbFu22HvApR5dqLp0dMSDlXrxJ1Ys,13164
+codeforerunner/installer.py,sha256=SPBr6Tmfpy3SmKaGQf-P_AhGvjbBz3lRNjGdU3-H-xg,14279
+codeforerunner/mcp_server.py,sha256=DtlR1e9JsRabyB42tboq7hC3yate8M5UoxyAYUQbn0M,5260
 codeforerunner/prompts/partials/context-format.md,sha256=WNfkr4kf2Awj0R8wLOrFotEiYCe6hfKTq5eA3Rt5_Xw,817
 codeforerunner/prompts/partials/output-rules.md,sha256=vfIAX-ImxCa-MVAeNH896uSIO7-cKbJd0KohkgHIiD8,1731
 codeforerunner/prompts/partials/stack-hints.md,sha256=8E2qELhk-hve2ULSdmiFK48LE4Aprhmuasqr6A1K2QU,2001
@@ -22,15 +22,15 @@ codeforerunner/prompts/tasks/review.md,sha256=IRdIXAKvv0JMOE5WtrnlO1Cd4LHXtcJqb1
 codeforerunner/prompts/tasks/scan.md,sha256=hYXf-IL1kgpBPHJapRrwTu88cLZ7y3bCmAq9HY0yG3U,2300
 codeforerunner/prompts/tasks/stack-docs.md,sha256=Dy-JSXpSmHSyhR5shQBXKa_F0PqnjPcmtljthYZpaiM,1923
 codeforerunner/prompts/tasks/version-audit.md,sha256=oK-pcoxt_VcvDOlj1Sz9OlEhXlcViLPn54r-qP5WfiA,5833
-codeforerunner/providers/__init__.py,sha256=hoLODdqQ-beA7-MVFR6aoE29ZUSzxGVPLhwNXNN1xw4,1020
-codeforerunner/providers/anthropic.py,sha256=kECeFMCeSJHcsUPvF93ECv52wXmLR6H21rFNwPzRhaM,4049
-codeforerunner/providers/base.py,sha256=MMrOUVOXHWP1td-TndxhLhDyDPJZGExZCeFopZUSRCo,923
-codeforerunner/providers/google.py,sha256=OWEE0FNupFWmZCeilIrgYUYDHH1iWvIwHEEsHYQoFFY,3979
-codeforerunner/providers/ollama.py,sha256=Q8ACojaeiBgPQgDFxP7KKM5r4Ccu6dDspNFza1vbOzw,3871
-codeforerunner/providers/openai.py,sha256=999ZzIVh0cqW4xDnzK_NACqfJxNziHwpVjwmw9_jjRw,3825
-codeforerunner-0.4.1.dist-info/licenses/LICENSE.md,sha256=iIhmJHib6GbdjcwiDMM-npiNRf3XgASom1WsOJivEdc,2915
-codeforerunner-0.4.1.dist-info/METADATA,sha256=c7yCFeXV3PfXwbJpb1hGe5WmPvA45t4W6A75mzC-F28,9873
-codeforerunner-0.4.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-codeforerunner-0.4.1.dist-info/entry_points.txt,sha256=3p8BbPlq-wfcXk42tsweKePRaGlZ1WXho1gOkuZGyIQ,55
-codeforerunner-0.4.1.dist-info/top_level.txt,sha256=pV1rt0-NIpNEotKXpL_sF2060DHr-_0F86LWhUlvXis,15
-codeforerunner-0.4.1.dist-info/RECORD,,
+codeforerunner/providers/__init__.py,sha256=PYr0Za1gHgAFRExUormDZZlsStI0RUheCgBj71I8b8w,1103
+codeforerunner/providers/anthropic.py,sha256=CYaSDtxIfJR-Z_F17_OfPPWHGEH7l61mQk0fZFsUFzI,4300
+codeforerunner/providers/base.py,sha256=bmOxnzWGGMhIWwuvIm9YQA_tPJyzXoIo1ciGzsDANz4,1220
+codeforerunner/providers/google.py,sha256=_cnidRymoCS32xUXibDTQ4nncwg0k0qI0YvPab2G64E,4434
+codeforerunner/providers/ollama.py,sha256=9ZU110g5qzEP1chC4MfG6zT2pgfl56jREL_dxt25vCw,5032
+codeforerunner/providers/openai.py,sha256=B-c551-NOGazlVVmP6d-hoeH7GKN4-eTEOuhcvhootA,4097
+codeforerunner-0.4.3.dist-info/licenses/LICENSE.md,sha256=iIhmJHib6GbdjcwiDMM-npiNRf3XgASom1WsOJivEdc,2915
+codeforerunner-0.4.3.dist-info/METADATA,sha256=n74THMcrVT-pgL1ZNKljmnVVE1wxu5XeP_O7LvNUlKs,9873
+codeforerunner-0.4.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+codeforerunner-0.4.3.dist-info/entry_points.txt,sha256=3p8BbPlq-wfcXk42tsweKePRaGlZ1WXho1gOkuZGyIQ,55
+codeforerunner-0.4.3.dist-info/top_level.txt,sha256=pV1rt0-NIpNEotKXpL_sF2060DHr-_0F86LWhUlvXis,15
+codeforerunner-0.4.3.dist-info/RECORD,,