codeforerunner 0.4.1__tar.gz → 0.4.3__tar.gz

{codeforerunner-0.4.1/src/codeforerunner.egg-info → codeforerunner-0.4.3}/PKG-INFO

@@ -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 → codeforerunner-0.4.3}/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.1 → codeforerunner-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codeforerunner"
-version = "0.4.1"
+version = "0.4.3"
 description = "Model-agnostic repository documentation tooling (prompt-first; thin CLI)."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -54,3 +54,9 @@ codeforerunner = ["py.typed", "prompts/**/*.md"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pydocstyle>=6.3.0",
+    "pytest-cov>=7.1.0",
+]

{codeforerunner-0.4.1 → codeforerunner-0.4.3}/src/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-0.4.1 → codeforerunner-0.4.3}/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.1 → codeforerunner-0.4.3}/src/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-0.4.1 → codeforerunner-0.4.3}/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
 
 
@@ -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-0.4.1 → codeforerunner-0.4.3}/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
@@ -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-0.4.1 → codeforerunner-0.4.3}/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
@@ -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