codeforerunner 0.4.4__tar.gz → 0.4.6__tar.gz

{codeforerunner-0.4.4/src/codeforerunner.egg-info → codeforerunner-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeforerunner
-Version: 0.4.4
+Version: 0.4.6
 Summary: Model-agnostic repository documentation tooling (prompt-first; thin CLI).
 Author: Derek Palmer
 License-Expression: LicenseRef-Codeforerunner-SAL-0.1
@@ -29,7 +29,7 @@ Dynamic: license-file
 
 # codeForerunner
 
-[![Socket Badge](https://badge.socket.dev/npm/package/codeforerunner/0.4.3)](https://badge.socket.dev/npm/package/codeforerunner/0.4.3)
+[![Socket Badge](https://badge.socket.dev/npm/package/codeforerunner/0.4.6)](https://socket.dev/npm/package/codeforerunner)
 
 Model-agnostic repository documentation tooling. Ships a prompt pack for codebase analysis and doc generation, a thin Python CLI, an MCP server, drift-detection rules that keep docs honest — and native slash-command skills for Claude Code, Codex, Gemini CLI, and other agent CLIs.
 
@@ -44,10 +44,15 @@ Install forerunner's prompt pack as skills into your agent CLI. Each documentati
 # One-liner (auto-detects Claude Code, Codex, Gemini CLI)
 curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
 
+# npm
+npx -y codeforerunner
+npm install -g codeforerunner
+
 # Windows
 irm https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.ps1 | iex
 
-# Via forerunner CLI (after pip install)
+# Via Python CLI
+pip install codeforerunner
 forerunner install --all claude
 forerunner install --all codex
 ```
@@ -70,6 +75,7 @@ Then in your agent:
 | `/forerunner-api-docs` | `api-docs` | Generate API reference docs |
 | `/forerunner-diagrams` | `diagrams` | Generate Mermaid architecture diagrams |
 | `/forerunner-flows` | `flows` | Document system flows |
+| `/forerunner-arch-review` | `arch-review` | Rank architecture improvement candidates, inspired by Matt Pocock's [`/improve-codebase-architecture`](https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture) |
 | `/forerunner-stack-docs` | `stack-docs` | Stack-specific developer docs |
 | `/forerunner-version-audit` | `version-audit` | Audit pinned versions vs EOL |
 | `/forerunner-check` | `check` | Check docs for staleness |
@@ -118,6 +124,9 @@ pip install codeforerunner
 # Install skills into Claude Code
 curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
 
+# Or via npm
+# npx -y codeforerunner
+
 # In Claude Code:
 # /forerunner-scan     → scans your repo
 # /forerunner-readme   → generates README.md
@@ -139,7 +148,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6.0.2
-      - uses: derek-palmer/codeforerunner@v0.4.3
+      - uses: derek-palmer/codeforerunner@v0.4.6
         with:
           fail-on-drift: "true"   # set "false" to warn-only
 ```
@@ -224,13 +233,13 @@ prompts/
     ├── scan.md          api-docs.md    audit.md
     ├── readme.md        diagrams.md    changelog.md
     ├── check.md         flows.md       version-audit.md
-    ├── review.md        stack-docs.md  refresh.md
+    ├── review.md        stack-docs.md  arch-review.md
+    ├── refresh.md
     └── init-agent-onboarding.md
 ```
 
-## Docs and spec
+## Docs
 
-- `SPEC.md` — canonical phase/task tracker
 - `docs/getting-started.md` — manual prompt use
 - `docs/prompt-guide.md` — how system, partial, and task prompts compose
 - `docs/editor-agent-setup.md` — adapting prompts to local agents

{codeforerunner-0.4.4 → codeforerunner-0.4.6}/README.md

@@ -2,7 +2,7 @@
 
 # codeForerunner
 
-[![Socket Badge](https://badge.socket.dev/npm/package/codeforerunner/0.4.3)](https://badge.socket.dev/npm/package/codeforerunner/0.4.3)
+[![Socket Badge](https://badge.socket.dev/npm/package/codeforerunner/0.4.6)](https://socket.dev/npm/package/codeforerunner)
 
 Model-agnostic repository documentation tooling. Ships a prompt pack for codebase analysis and doc generation, a thin Python CLI, an MCP server, drift-detection rules that keep docs honest — and native slash-command skills for Claude Code, Codex, Gemini CLI, and other agent CLIs.
 
@@ -17,10 +17,15 @@ Install forerunner's prompt pack as skills into your agent CLI. Each documentati
 # One-liner (auto-detects Claude Code, Codex, Gemini CLI)
 curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
 
+# npm
+npx -y codeforerunner
+npm install -g codeforerunner
+
 # Windows
 irm https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.ps1 | iex
 
-# Via forerunner CLI (after pip install)
+# Via Python CLI
+pip install codeforerunner
 forerunner install --all claude
 forerunner install --all codex
 ```
@@ -43,6 +48,7 @@ Then in your agent:
 | `/forerunner-api-docs` | `api-docs` | Generate API reference docs |
 | `/forerunner-diagrams` | `diagrams` | Generate Mermaid architecture diagrams |
 | `/forerunner-flows` | `flows` | Document system flows |
+| `/forerunner-arch-review` | `arch-review` | Rank architecture improvement candidates, inspired by Matt Pocock's [`/improve-codebase-architecture`](https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture) |
 | `/forerunner-stack-docs` | `stack-docs` | Stack-specific developer docs |
 | `/forerunner-version-audit` | `version-audit` | Audit pinned versions vs EOL |
 | `/forerunner-check` | `check` | Check docs for staleness |
@@ -91,6 +97,9 @@ pip install codeforerunner
 # Install skills into Claude Code
 curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
 
+# Or via npm
+# npx -y codeforerunner
+
 # In Claude Code:
 # /forerunner-scan     → scans your repo
 # /forerunner-readme   → generates README.md
@@ -112,7 +121,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6.0.2
-      - uses: derek-palmer/codeforerunner@v0.4.3
+      - uses: derek-palmer/codeforerunner@v0.4.6
         with:
           fail-on-drift: "true"   # set "false" to warn-only
 ```
@@ -197,13 +206,13 @@ prompts/
     ├── scan.md          api-docs.md    audit.md
     ├── readme.md        diagrams.md    changelog.md
     ├── check.md         flows.md       version-audit.md
-    ├── review.md        stack-docs.md  refresh.md
+    ├── review.md        stack-docs.md  arch-review.md
+    ├── refresh.md
     └── init-agent-onboarding.md
 ```
 
-## Docs and spec
+## Docs
 
-- `SPEC.md` — canonical phase/task tracker
 - `docs/getting-started.md` — manual prompt use
 - `docs/prompt-guide.md` — how system, partial, and task prompts compose
 - `docs/editor-agent-setup.md` — adapting prompts to local agents

{codeforerunner-0.4.4 → codeforerunner-0.4.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codeforerunner"
-version = "0.4.4"
+version = "0.4.6"
 description = "Model-agnostic repository documentation tooling (prompt-first; thin CLI)."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -50,7 +50,7 @@ forerunner = "codeforerunner.cli:main"
 where = ["src"]
 
 [tool.setuptools.package-data]
-codeforerunner = ["py.typed", "prompts/**/*.md"]
+codeforerunner = ["py.typed", "prompts/**/*.md", "tasks.json", "release_surfaces.json"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{codeforerunner-0.4.4 → codeforerunner-0.4.6}/src/codeforerunner/cli.py

@@ -1,4 +1,4 @@
-"""Thin CLI orchestration. Product logic lives in prompts/. See SPEC.md §D.cli."""
+"""Thin CLI orchestration. Product logic lives in prompts/."""
 
 from __future__ import annotations
 
@@ -8,77 +8,86 @@ import sys
 from pathlib import Path
 from typing import Sequence
 
-from codeforerunner.bundle import find_prompts_root, resolve_bundle as _resolve_bundle
-
-SCAN_EXEMPT_TASKS = frozenset({"scan", "init-agent-onboarding"})
+from codeforerunner.bundle import find_prompts_root
+from codeforerunner.prompt_session import OutcomeKind, PromptSession
+from codeforerunner.tasks import refresh_tasks as _refresh_tasks
 SCAN_DONE_ENV = "FORERUNNER_SCAN_DONE"
 
 
-def _get_bundle(args: argparse.Namespace) -> tuple[str, int]:
-    """Resolve bundle for args.task. Returns (bundle_text, exit_code). exit_code != 0 on error."""
+def _scan_satisfied(repo_root: Path) -> bool:
+    """CLI scan-first signal: scan artifact present, env override set, or no config to gate."""
+    return (
+        (repo_root / ".forerunner" / "scan.md").is_file()
+        or bool(os.environ.get(SCAN_DONE_ENV))
+        or not (repo_root / "forerunner.config.yaml").is_file()
+    )
+
+
+def _resolve_bundle(repo, task: str) -> tuple[str, int]:
+    """Resolve bundle text for *task* under *repo*. Returns (text, exit_code).
+
+    Encodes the session's closed Outcome into CLI exit codes; the gate/order
+    lives in the Prompt Session, this is just the encoder.
+    """
     try:
-        prompts_root = find_prompts_root(args.repo)
+        prompts_root = find_prompts_root(repo)
     except FileNotFoundError as e:
         print(f"error: {e}", file=sys.stderr)
         return "", 2
 
-    task_path = prompts_root / "tasks" / f"{args.task}.md"
-    if not task_path.is_file():
-        print(f"error: unknown task '{args.task}' (no {task_path})", file=sys.stderr)
+    repo_root = Path(repo).resolve() if repo else Path.cwd()
+    session = PromptSession(prompts_root, _scan_satisfied(repo_root))
+    outcome = session.resolve(task)
+    if outcome.kind is OutcomeKind.ALLOWED:
+        return outcome.text, 0
+    if outcome.kind is OutcomeKind.UNKNOWN_TASK:
+        print(f"error: unknown task '{task}'", file=sys.stderr)
         return "", 2
-
-    repo_root = Path(args.repo) if args.repo else Path.cwd()
-    if (
-        args.task not in SCAN_EXEMPT_TASKS
-        and (repo_root / "forerunner.config.yaml").is_file()
-        and not os.environ.get(SCAN_DONE_ENV)
-    ):
+    if outcome.kind is OutcomeKind.SCAN_REQUIRED:
         print(
-            f"warning: SPEC V2 scan-first — run `forerunner scan` first, "
-            f"then export {SCAN_DONE_ENV}=1 to silence this warning.",
+            f"error: scan-first required — run `forerunner scan` first "
+            f"(writes .forerunner/scan.md). Set {SCAN_DONE_ENV}=1 to skip.",
             file=sys.stderr,
         )
-
-    try:
-        return _resolve_bundle(prompts_root, args.task), 0
-    except FileNotFoundError as e:
-        print(f"error: {e}", file=sys.stderr)
-        return "", 2
+        return "", 1
+    # MISSING
+    print(f"error: {outcome.message}", file=sys.stderr)
+    return "", 2
 
 
-def cmd_doc(args: argparse.Namespace) -> int:
-    """Resolve base + partials + task bundle to stdout."""
-    bundle, rc = _get_bundle(args)
+def _emit_task(repo, task: str) -> int:
+    """Resolve *task* under *repo* and write its bundle to stdout. Returns rc."""
+    bundle, rc = _resolve_bundle(repo, task)
     if rc != 0:
         return rc
     sys.stdout.write(bundle)
     return 0
 
 
-def _doc_for(args: argparse.Namespace, task: str) -> int:
-    """Emit bundle for *task* by delegating to cmd_doc with a synthetic Namespace."""
-    ns = argparse.Namespace(repo=getattr(args, "repo", None), task=task)
-    return cmd_doc(ns)
+def cmd_doc(args: argparse.Namespace) -> int:
+    """Resolve base + partials + task bundle to stdout."""
+    return _emit_task(args.repo, args.task)
 
 
 def cmd_init(args: argparse.Namespace) -> int:
     """Emit onboarding bundle; prepend scan bundle when --full is given."""
+    repo = getattr(args, "repo", None)
     if getattr(args, "full", False):
         sys.stdout.write("<!-- forerunner init --full: section 1/2 (scan) -->\n")
-        rc = _doc_for(args, "scan")
+        rc = _emit_task(repo, "scan")
         if rc != 0:
             return rc
         sys.stdout.write("\n<!-- forerunner init --full: section 2/2 (onboarding) -->\n")
-    return _doc_for(args, "init-agent-onboarding")
+    return _emit_task(repo, "init-agent-onboarding")
 
 
 def cmd_scan(args: argparse.Namespace) -> int:
-    """Emit the scan prompt bundle and hint about FORERUNNER_SCAN_DONE."""
-    rc = _doc_for(args, "scan")
+    """Emit the scan prompt bundle and hint about scan artifact."""
+    rc = _emit_task(getattr(args, "repo", None), "scan")
     if rc == 0:
         print(
-            f"hint: export {SCAN_DONE_ENV}=1 in this shell to silence "
-            "scan-first warnings on follow-up `forerunner doc`/`init` calls.",
+            "hint: write the scan result to .forerunner/scan.md to satisfy the "
+            f"scan-first gate on follow-up calls. Or set {SCAN_DONE_ENV}=1 to skip.",
             file=sys.stderr,
         )
     return rc
@@ -111,19 +120,19 @@ def cmd_mcp_server(args: argparse.Namespace) -> int:
     except FileNotFoundError as e:
         print(f"mcp_server: {e}", file=sys.stderr)
         return 2
-    return mcp_server.serve(prompts_root)
+    repo_root = Path(args.repo).resolve() if args.repo else Path.cwd()
+    return mcp_server.serve(prompts_root, repo_root=repo_root)
 
 
 def cmd_refresh(args: argparse.Namespace) -> int:
     """Emit scan + check + all doc-task bundles to stdout for a full doc refresh."""
-    tasks = ["scan", "check", "readme", "api-docs", "stack-docs",
-             "diagrams", "flows", "version-audit", "audit"]
-    for i, task in enumerate(tasks):
-        ns = argparse.Namespace(repo=getattr(args, "repo", None), task=task)
-        rc = cmd_doc(ns)
+    repo = getattr(args, "repo", None)
+    task_names = [t.name for t in _refresh_tasks()]
+    for i, task in enumerate(task_names):
+        rc = _emit_task(repo, task)
         if rc != 0:
             return rc
-        if i < len(tasks) - 1:
+        if i < len(task_names) - 1:
             sys.stdout.write("\n---\n\n")
     return 0
 

{codeforerunner-0.4.4 → codeforerunner-0.4.6}/src/codeforerunner/config.py

@@ -1,4 +1,4 @@
-"""`forerunner.config.yaml` schema + loader. See SPEC.md §T25."""
+"""`forerunner.config.yaml` schema + loader."""
 
 from __future__ import annotations
 

codeforerunner-0.4.6/src/codeforerunner/distribution.py

@@ -0,0 +1,56 @@
+"""Distribution Inventory — single source of truth for distribution artifact
+identity and install policy.
+
+Owns the packaging facts that were previously duplicated across the installer,
+doctor, and validation scripts: the canonical skill path, its distributed copy
+paths, the Codex marketplace manifest path, the managed-region markers, and the
+default install-destination templates. Consumers consult this module instead of
+re-declaring constants, so a packaging change is one edit here.
+
+Mirrors the Task Registry (``tasks.py``) and Release Surface Manifest
+(``release_surfaces.py``) single-source pattern.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# --- artifact identity (repo-relative) ------------------------------------
+
+# Source of truth for the codeforerunner skill body; copies derive from it.
+CANONICAL_SKILL_REL = Path("agent/codeforerunner.skill.md")
+
+# Distributed copies whose bodies must match the canonical (V10 body parity).
+DISTRIBUTED_SKILL_COPIES_REL: tuple[Path, ...] = (
+    Path("plugins/codeforerunner/skills/codeforerunner/SKILL.md"),
+    Path("skills/codeforerunner/SKILL.md"),
+)
+
+# Codex marketplace manifest shipped as a release asset.
+MARKETPLACE_MANIFEST_REL = Path("plugins/codex/marketplace.json")
+
+# --- managed-region markers -----------------------------------------------
+
+# Delimit the installer-owned region in a destination file so re-runs are
+# idempotent and unmanaged content is never clobbered.
+MARKER_BEGIN = "<!-- forerunner:begin managed=codeforerunner.skill -->"
+MARKER_END = "<!-- forerunner:end -->"
+
+# --- install-destination templates ----------------------------------------
+
+# Agents whose default skill destination the inventory can resolve.
+SKILL_DEST_AGENTS: tuple[str, ...] = ("codex", "claude")
+
+
+def skill_destination(agent: str, slug: str, home: Path) -> Path:
+    """Default install path for skill ``slug`` under ``agent``, relative to ``home``."""
+    if agent == "codex":
+        return home / f".codex/skills/{slug}/SKILL.md"
+    if agent == "claude":
+        return home / f".claude/plugins/codeforerunner/skills/{slug}/SKILL.md"
+    raise ValueError(f"no default skill destination for agent {agent!r} (expected: {', '.join(SKILL_DEST_AGENTS)})")
+
+
+def marketplace_destination(home: Path) -> Path:
+    """Default install path for the Codex marketplace manifest, relative to ``home``."""
+    return home / ".codex/marketplaces/codeforerunner.json"

{codeforerunner-0.4.4 → codeforerunner-0.4.6}/src/codeforerunner/doctor.py

@@ -1,4 +1,4 @@
-"""`forerunner doctor` — single-screen health report. See SPEC.md §T35."""
+"""`forerunner doctor` — single-screen health report."""
 
 from __future__ import annotations
 
@@ -11,17 +11,18 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Callable
 
+from codeforerunner import distribution as _dist
+from codeforerunner import skill_parity as _parity
 from codeforerunner.config import CONFIG_FILENAME, ConfigError, load_from_repo
 
-CANONICAL_REL = Path("agent/codeforerunner.skill.md")
-SKILL_COPIES_REL: tuple[Path, ...] = (
-    Path("plugins/codeforerunner/skills/codeforerunner/SKILL.md"),
-    Path("skills/codeforerunner/SKILL.md"),
-)
-MARKETPLACE_REL = Path("plugins/codex/marketplace.json")
+# Distribution artifact identity and markers come from the Distribution
+# Inventory; re-exported here for callers/tests that import them off doctor.
+CANONICAL_REL = _dist.CANONICAL_SKILL_REL
+SKILL_COPIES_REL: tuple[Path, ...] = _dist.DISTRIBUTED_SKILL_COPIES_REL
+MARKETPLACE_REL = _dist.MARKETPLACE_MANIFEST_REL
 
-MARKER_BEGIN = "<!-- forerunner:begin managed=codeforerunner.skill -->"
-MARKER_END = "<!-- forerunner:end -->"
+MARKER_BEGIN = _dist.MARKER_BEGIN
+MARKER_END = _dist.MARKER_END
 
 
 @dataclass(frozen=True)
@@ -37,14 +38,14 @@ def _installed_skill_destinations() -> list[Path]:
     """Return default install paths for the codeforerunner skill across supported agents."""
     home = Path(os.path.expanduser("~"))
     return [
-        home / ".codex/skills/codeforerunner/SKILL.md",
-        home / ".claude/plugins/codeforerunner/skills/codeforerunner/SKILL.md",
+        _dist.skill_destination(agent, "codeforerunner", home)
+        for agent in _dist.SKILL_DEST_AGENTS
     ]
 
 
 def _installed_marketplace_destination() -> Path:
     """Return default install path for the Codex marketplace manifest."""
-    return Path(os.path.expanduser("~")) / ".codex/marketplaces/codeforerunner.json"
+    return _dist.marketplace_destination(Path(os.path.expanduser("~")))
 
 
 def _load_script_module(repo: Path, relpath: str, module_name: str):
@@ -62,25 +63,14 @@ def _load_script_module(repo: Path, relpath: str, module_name: str):
 
 
 def _check_skill_body_parity(repo: Path, run_scripts: bool = False) -> list[Finding]:
-    """Verify that all distributed skill copies match the canonical body."""
-    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"
-        )
-        strip_frontmatter: Callable[[str], str] = skill_mod.strip_frontmatter
-    except Exception as exc:  # pragma: no cover - defensive
-        return [Finding("error", "skill-body-parity", f"loader failure: {exc}")]
-
-    canonical_path = repo / CANONICAL_REL
-    if not canonical_path.is_file():
+    """Verify that all distributed skill copies match the canonical body.
+
+    Body parity is owned by the Skill Body Parity module, which only reads
+    files (no target-repo code is executed), so this runs regardless of
+    ``run_scripts`` — that flag still gates checks that load repo scripts.
+    """
+    result = _parity.check_skill_body_parity(repo)
+    if result.missing_canonical:
         return [
             Finding(
                 "error",
@@ -88,21 +78,12 @@ def _check_skill_body_parity(repo: Path, run_scripts: bool = False) -> list[Find
                 f"canonical skill missing: {CANONICAL_REL}",
             )
         ]
-    canonical_body = strip_frontmatter(canonical_path.read_text(encoding="utf-8"))
 
     findings: list[Finding] = []
-    for rel in SKILL_COPIES_REL:
-        p = repo / rel
-        if not p.is_file():
-            findings.append(
-                Finding("error", "skill-body-parity", f"copy missing: {rel}")
-            )
-            continue
-        body = strip_frontmatter(p.read_text(encoding="utf-8"))
-        if body != canonical_body:
-            findings.append(
-                Finding("error", "skill-body-parity", f"body drift in {rel}")
-            )
+    for rel in result.missing_copies:
+        findings.append(Finding("error", "skill-body-parity", f"copy missing: {rel}"))
+    for rel in result.drifted_copies:
+        findings.append(Finding("error", "skill-body-parity", f"body drift in {rel}"))
     if not findings:
         findings.append(
             Finding(