codeforerunner 0.4.0__tar.gz → 0.4.2__tar.gz

{codeforerunner-0.4.0/src/codeforerunner.egg-info → codeforerunner-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeforerunner
-Version: 0.4.0
+Version: 0.4.2
 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.0 → codeforerunner-0.4.2}/README.md

@@ -148,7 +148,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.0 → codeforerunner-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codeforerunner"
-version = "0.4.0"
+version = "0.4.2"
 description = "Model-agnostic repository documentation tooling (prompt-first; thin CLI)."
 readme = "README.md"
 requires-python = ">=3.11"

{codeforerunner-0.4.0 → codeforerunner-0.4.2}/src/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-0.4.0 → codeforerunner-0.4.2}/src/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
 
 
@@ -104,13 +112,27 @@ 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 +140,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 +150,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 +179,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
@@ -183,7 +203,7 @@ 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
 
@@ -236,6 +256,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 +270,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

{codeforerunner-0.4.0 → codeforerunner-0.4.2}/src/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
@@ -37,9 +36,6 @@ class VersionAuditConfig:
 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)
@@ -117,13 +113,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 +150,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-0.4.0 → codeforerunner-0.4.2}/src/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
@@ -50,17 +51,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 +115,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 +243,19 @@ def _check_config_loadable(repo: Path) -> list[Finding]:
     return [Finding("ok", "config-loadable", f"{CONFIG_FILENAME} parses cleanly")]
 
 
+def _skill_mode_active() -> bool:
+    """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 +269,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:
@@ -279,7 +319,12 @@ def _check_provider_api_key(repo: Path) -> list[Finding]:
         Finding(
             "warn",
             "provider-api-key",
-            f"{provider}: ${env_var} is not set; `forerunner generate` will refuse to run",
+            f"{provider}: ${env_var} is not set; `forerunner generate` will refuse to run"
+            + (
+                " (use `--prompt-only` for key-free bundle output)"
+                if _skill_mode_active()
+                else ""
+            ),
         )
     ]
 
@@ -288,15 +333,17 @@ _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: []
 """
 
 
@@ -304,11 +351,11 @@ def starter_config() -> str:
     return _STARTER_CONFIG
 
 
-def run(repo: Path) -> list[Finding]:
+def run(repo: Path, run_scripts: bool = False) -> list[Finding]:
     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))
@@ -317,14 +364,10 @@ def run(repo: Path) -> list[Finding]:
 
 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}
+    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"
-    )
+    summary = f"summary: {counts['ok']} ok, {counts['warn']} warn, {counts['error']} error"
     lines.append(summary)
     return "\n".join(lines)
 
@@ -340,9 +383,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-0.4.0 → codeforerunner-0.4.2}/src/codeforerunner/installer.py

@@ -95,6 +95,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,7 +117,11 @@ 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
 
 
@@ -188,7 +193,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:]

{codeforerunner-0.4.0 → codeforerunner-0.4.2}/src/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,7 @@ 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}
+    state: dict[str, Any] = {"scan_called": False, "initialized": False}
     for raw in stdin:
         line = raw.strip()
         if not line:

{codeforerunner-0.4.0 → codeforerunner-0.4.2}/src/codeforerunner/providers/anthropic.py

@@ -45,7 +45,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")
@@ -90,7 +90,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-0.4.0 → codeforerunner-0.4.2}/src/codeforerunner/providers/google.py

@@ -16,6 +16,8 @@ class GoogleProvider:
     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}"
     )
@@ -48,7 +50,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")
@@ -90,7 +92,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-0.4.0 → codeforerunner-0.4.2}/src/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:
+        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:
@@ -38,6 +60,7 @@ class OllamaProvider:
         # 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 +73,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")
@@ -75,6 +98,7 @@ class OllamaProvider:
     ) -> Iterator[str]:
         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 +111,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-0.4.0 → codeforerunner-0.4.2}/src/codeforerunner/providers/openai.py

@@ -43,7 +43,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")
@@ -86,7 +86,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.0 → codeforerunner-0.4.2/src/codeforerunner.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeforerunner
-Version: 0.4.0
+Version: 0.4.2
 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.0 → codeforerunner-0.4.2}/tests/test_cli.py

@@ -392,10 +392,11 @@ def test_generate_no_fallback_when_config_provider_set_and_key_missing(
     assert "missing API key" in cap.err
 
 
-def test_generate_missing_key_includes_ollama_hint_when_ollama_absent(
+def test_generate_no_key_no_ollama_no_explicit_provider_emits_bundle(
     tmp_path, capsys, monkeypatch
 ):
-    """No explicit provider, no API key, Ollama not running → error + Ollama hint."""
+    """No explicit provider, no API key, Ollama not running → skill-mode auto-detect:
+    emit bundle to stdout and return 0 (the calling agent is the model)."""
     _seed_repo_with_config(tmp_path)
     (tmp_path / "forerunner.config.yaml").unlink()
 
@@ -407,9 +408,8 @@ def test_generate_missing_key_includes_ollama_hint_when_ollama_absent(
         rc = main(["--repo", str(tmp_path), "generate", "readme"])
 
     cap = capsys.readouterr()
-    assert rc == 3
-    assert "missing API key" in cap.err
-    assert "Ollama" in cap.err
+    assert rc == 0
+    assert "system: base.md" in cap.out
 
 
 def test_generate_ollama_fallback_uses_explicit_model(tmp_path, capsys, monkeypatch):
@@ -437,3 +437,92 @@ def test_generate_ollama_fallback_uses_explicit_model(tmp_path, capsys, monkeypa
 
     assert rc == 0
     assert calls[0]["model"] == "llama3.2"
+
+
+# ── --prompt-only and skill-mode auto-detect ─────────────────────────────────
+
+def test_generate_prompt_only_outputs_bundle_without_api_call(tmp_path, capsys, monkeypatch):
+    """--prompt-only emits the bundle and returns 0; no model is invoked."""
+    _seed_repo_with_config(tmp_path)
+    monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+    monkeypatch.setenv("FORERUNNER_SCAN_DONE", "1")  # silence scan-first warning
+
+    rc = main(["--repo", str(tmp_path), "generate", "--prompt-only", "readme"])
+
+    cap = capsys.readouterr()
+    assert rc == 0
+    assert "system: base.md" in cap.out
+    assert "missing API key" not in cap.err  # no provider error messages
+
+
+def test_generate_prompt_only_scan_task(tmp_path, capsys, monkeypatch):
+    """--prompt-only works for the scan task (scan is exempt from scan-first warning)."""
+    _seed_repo_with_config(tmp_path)
+    monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+
+    rc = main(["--repo", str(tmp_path), "generate", "--prompt-only", "scan"])
+
+    cap = capsys.readouterr()
+    assert rc == 0
+    assert "scan task" in cap.out  # stub scan.md content present
+
+
+def test_generate_skill_mode_autodetect_no_tty(tmp_path, capsys, monkeypatch):
+    """No key + no Ollama + no explicit provider + non-TTY stdout → bundle emitted cleanly."""
+    _seed_repo_with_config(tmp_path)
+    (tmp_path / "forerunner.config.yaml").unlink()
+
+    from unittest.mock import patch
+
+    monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+
+    with patch("codeforerunner.providers.ollama_available", return_value=False):
+        rc = main(["--repo", str(tmp_path), "generate", "readme"])
+
+    cap = capsys.readouterr()
+    assert rc == 0
+    assert "system: base.md" in cap.out
+    # Non-TTY: no "info:" message on stderr
+    assert "info:" not in cap.err
+
+
+def test_generate_explicit_provider_no_key_still_errors(tmp_path, capsys, monkeypatch):
+    """Explicit --provider with no key → error (not silent bundle output)."""
+    _seed_repo_with_config(tmp_path)
+    (tmp_path / "forerunner.config.yaml").unlink()
+
+    from unittest.mock import patch
+
+    monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+
+    with patch("codeforerunner.providers.ollama_available", return_value=False):
+        rc = main(["--repo", str(tmp_path), "generate", "--provider", "anthropic", "readme"])
+
+    cap = capsys.readouterr()
+    assert rc == 3
+    assert "missing API key" in cap.err
+
+
+def test_generate_stream_flag_yields_chunks(tmp_path, capsys, monkeypatch):
+    """--stream calls provider.stream() and writes chunks to stdout."""
+    _seed_repo_with_config(tmp_path)
+    (tmp_path / "forerunner.config.yaml").unlink()
+    chunks = ["hello", " ", "world"]
+
+    class FakeProvider:
+        default_env_var = "FAKE_API_KEY"
+        default_model = "fake-stream"
+
+        def stream(self, *, prompt, model=None, api_key=None):
+            yield from chunks
+
+    from codeforerunner import providers
+
+    monkeypatch.setitem(providers.REGISTRY, "fake", FakeProvider)
+    monkeypatch.setenv("FAKE_API_KEY", "secret")
+
+    rc = main(["--repo", str(tmp_path), "generate", "--provider", "fake", "--stream", "readme"])
+    cap = capsys.readouterr()
+
+    assert rc == 0
+    assert cap.out == "hello world\n"

{codeforerunner-0.4.0 → codeforerunner-0.4.2}/tests/test_config.py

@@ -33,8 +33,6 @@ def test_load_full_example_shape(tmp_path):
         """
 provider: openai
 model: gpt-x
-output_dir: documents
-context_max_files: 50
 ignore_patterns:
   - "*.test.ts"
 tasks:
@@ -52,8 +50,6 @@ tasks:
     assert cfg is not None
     assert cfg.provider == "openai"
     assert cfg.model == "gpt-x"
-    assert cfg.output_dir == Path("documents")
-    assert cfg.context_max_files == 50
     assert cfg.ignore_patterns == ("*.test.ts",)
     assert cfg.check.block_on == ("HIGH",)
     assert cfg.check.warn_on == ("MEDIUM", "LOW")

{codeforerunner-0.4.0 → codeforerunner-0.4.2}/tests/test_doctor.py

@@ -46,7 +46,7 @@ def test_skill_body_drift_reported(tmp_path: Path):
     text = drifted.read_text(encoding="utf-8")
     drifted.write_text(text + "\n\nINJECTED DRIFT LINE\n", encoding="utf-8")
 
-    findings = run(repo)
+    findings = run(repo, run_scripts=True)
     parity_errors = [
         f for f in findings if f.check == "skill-body-parity" and f.severity == "error"
     ]
@@ -58,7 +58,7 @@ def test_marketplace_invalid_reported(tmp_path: Path):
     bad = repo / "plugins/codex/marketplace.json"
     bad.write_text(json.dumps({"marketplace": {"id": "x", "name": "x", "version": "1.0.0"}}), encoding="utf-8")
 
-    findings = run(repo)
+    findings = run(repo, run_scripts=True)
     mp_errors = [
         f for f in findings if f.check == "codex-marketplace" and f.severity == "error"
     ]
@@ -81,10 +81,13 @@ def test_main_exits_zero_when_no_errors(capsys):
 
 
 def test_provider_api_key_finding_present_with_config(tmp_path: Path, monkeypatch):
+    from unittest.mock import patch
     repo = _copy_repo_layout(tmp_path)
     (repo / "forerunner.config.yaml").write_text("", encoding="utf-8")
     monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
-    findings = run(repo)
+    # Force skill mode off so warn path is exercised
+    with patch("codeforerunner.doctor._skill_mode_active", return_value=False):
+        findings = run(repo)
     matches = [f for f in findings if f.check == "provider-api-key"]
     assert len(matches) == 1
     assert matches[0].severity == "warn"
@@ -132,7 +135,7 @@ def test_main_exits_one_when_error_present(tmp_path: Path, capsys):
     drifted.write_text(
         drifted.read_text(encoding="utf-8") + "\nDRIFT\n", encoding="utf-8"
     )
-    rc = main(["--repo", str(repo)])
+    rc = main(["--repo", str(repo), "--run-scripts"])
     capsys.readouterr()
     assert rc == 1
 
@@ -193,13 +196,14 @@ def test_provider_api_key_local_mode_when_ollama_running_no_config(tmp_path: Pat
 def test_provider_api_key_hint_when_ollama_absent_no_config(tmp_path: Path):
     from unittest.mock import patch
     repo = _copy_repo_layout(tmp_path)
-    # no forerunner.config.yaml
-    with patch("codeforerunner.providers.ollama.is_available", return_value=False):
+    # no forerunner.config.yaml; no skill installed → fallback message mentions prompt-only
+    with patch("codeforerunner.providers.ollama.is_available", return_value=False), \
+         patch("codeforerunner.doctor._skill_mode_active", return_value=False):
         findings = run(repo)
     matches = [f for f in findings if f.check == "provider-api-key"]
     assert len(matches) == 1
     assert matches[0].severity == "ok"
-    assert "Ollama" in matches[0].message
+    assert "prompt-only" in matches[0].message
 
 
 def test_provider_api_key_ollama_config_shows_local_mode(tmp_path: Path, monkeypatch):

{codeforerunner-0.4.0 → codeforerunner-0.4.2}/tests/test_mcp_server.py

@@ -127,7 +127,8 @@ def test_tools_call_unknown(server: _Server) -> None:
 
 
 def test_unknown_method(server: _Server) -> None:
-    resp = server.request({"jsonrpc": "2.0", "id": 1, "method": "no/such/method", "params": {}})
+    server.request({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}})
+    resp = server.request({"jsonrpc": "2.0", "id": 2, "method": "no/such/method", "params": {}})
     assert "error" in resp
     assert resp["error"]["code"] == -32601