codeforerunner 0.3.0__tar.gz

codeforerunner-0.3.0/LICENSE.md

@@ -0,0 +1,71 @@
+Codeforerunner Source-Available License v0.1
+===========================================
+
+Copyright (c) 2026 Derek Palmer
+
+1. Grant of rights
+
+Subject to the terms of this license, you are permitted to:
+
+1.1 Use this software for personal, educational, and commercial purposes.
+
+1.2 Modify this software for your own internal use, including within your
+    personal projects, your employer's internal systems, or client work,
+    provided that the modified software is not itself sold, licensed,
+    hosted as a commercial offering, or otherwise offered as a product or
+    service to third parties.
+
+1.3 Redistribute unmodified copies of this software, provided that you
+    include this license and all copyright notices.
+
+2. Restrictions
+
+You may NOT, under any circumstance:
+
+2.1 Sell, license, sublicense, host, distribute for a fee, or otherwise
+    offer this software, or any modified version of it, as a standalone
+    product, hosted product, or primary service offering.
+
+2.2 Modify, adapt, extend, or integrate this software into another
+    product or service and then sell, license, sublicense, host, or
+    otherwise commercially offer that product or service where this
+    software or any derivative of it provides material functionality.
+
+2.3 Rebrand this software, or any modified version of it, as your own
+    competing product, or present it in a way that suggests it is your
+    original creation.
+
+2.4 Remove or alter any attribution, copyright, or license notices
+    included with the software, except as necessary to add your own,
+    clearly subordinate notices for internal tracking.
+
+3. No trademark license
+
+The names "codeforerunner", "forerunner", and any associated project
+logos or branding are not licensed for use as your own product or
+service names. You may refer to the software by its name in truthful
+descriptions, such as "powered by codeforerunner", but you may not use
+these names or logos in a way that suggests official endorsement or
+affiliation without prior written permission from the copyright holder.
+
+4. No warranty
+
+THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+5. Termination
+
+Any violation of this license automatically terminates your rights under
+it. Upon termination, you must stop using and distributing the software
+and any derivative works, except where otherwise allowed by applicable
+law.
+
+6. Miscellaneous
+
+If any provision of this license is held to be unenforceable, the
+remaining provisions will remain in full force and effect.

codeforerunner-0.3.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: codeforerunner
+Version: 0.3.0
+Summary: Model-agnostic repository documentation tooling (prompt-first; thin CLI).
+Author: Derek Palmer
+License-Expression: LicenseRef-Codeforerunner-SAL-0.1
+Project-URL: Repository, https://github.com/derek-palmer/codeforerunner
+Project-URL: Issues, https://github.com/derek-palmer/codeforerunner/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+![codeForerunner — your codebase gets a Forerunner; your docs finally see the light](images/readme_banner.png)
+
+# codeForerunner
+
+CodeForerunner is a model-agnostic documentation agent that acts as overwatch for your repository, automatically analyzing code and maintaining docs, diagrams, and architecture knowledge as your codebase evolves over time.
+
+The current repo is the prompt-first foundation for that agent: it ships prompt assets for understanding a codebase and generating developer docs. A thin Python CLI (including `forerunner mcp-server` and a scoped `forerunner init --full / --agents-only`), an idempotent skill installer, pre-commit + CI hooks, and a PyPI publish workflow now wrap those prompts; the first published PyPI release remains pending.
+
+## Current State
+
+- Core product: Markdown prompts in `prompts/`.
+- Agent package artifacts: Codex plugin files under `plugins/codeforerunner/` and Claude Code plugin files under `.claude-plugin/` plus `skills/codeforerunner/`.
+- Python package: `pyproject.toml` + `src/codeforerunner/` expose a `forerunner` console script. `forerunner doc <task>` resolves the prompt bundle (base + partials + task) to stdout; `forerunner install <agent>` idempotently writes the canonical skill into agent-specific directories; `forerunner init` resolves the agent-onboarding bundle (with `--full` to prepend a scan or `--agents-only` for the default scope); `forerunner scan` resolves the scan bundle; `forerunner mcp-server` serves prompt bundles as MCP tools over stdio.
+- Hooks: `.pre-commit-hooks.yaml` exposes a `forerunner-check` hook; `.github/workflows/forerunner-check.yml` mirrors it in CI. Both no-op when `forerunner.config.yaml` is absent.
+- Current config: `forerunner.config.yaml.example` documents the schema now parsed by `src/codeforerunner/config.py`; see "Configuration" below.
+- Not currently present: Docker image, Makefile, published PyPI release.
+
+## Install
+
+After the first PyPI release:
+
+```bash
+pipx install codeforerunner   # recommended; isolated environment
+pip install codeforerunner    # alternative
+```
+
+From source:
+
+```bash
+git clone https://github.com/derek-palmer/codeForerunner
+cd codeForerunner
+python -m pip install -e .
+```
+
+Then `forerunner --help` should print the subcommand list.
+
+## Prompt Layout
+
+```text
+prompts/
+├── system/
+│   └── base.md
+├── partials/
+│   ├── context-format.md
+│   ├── output-rules.md
+│   └── stack-hints.md
+└── tasks/
+    ├── scan.md
+    ├── init-agent-onboarding.md
+    ├── readme.md
+    ├── api-docs.md
+    ├── stack-docs.md
+    ├── diagrams.md
+    ├── flows.md
+    ├── version-audit.md
+    ├── check.md
+    └── review.md
+```
+
+## Quick Start
+
+1. Open `prompts/system/base.md` and use it as the agent system or project instruction.
+2. Assemble repo context using the shape in `prompts/partials/context-format.md`.
+3. For documentation generation, run `prompts/tasks/scan.md` first.
+4. For agent onboarding only, run `prompts/tasks/init-agent-onboarding.md` directly.
+5. Pass the scan result into one downstream documentation prompt, such as `prompts/tasks/readme.md` or `prompts/tasks/stack-docs.md`.
+6. Apply generated docs only after checking that every claim is grounded in provided files.
+
+## What The Prompts Do
+
+| Prompt | Purpose |
+| --- | --- |
+| `prompts/system/base.md` | Defines the codeforerunner role, quality bar, Markdown rules, and accuracy constraints. |
+| `prompts/tasks/scan.md` | Produces the first structured repo scan used by downstream tasks. |
+| `prompts/tasks/init-agent-onboarding.md` | Generates or updates `AGENTS.md` from repo evidence plus files such as `CLAUDE.md`, `.cursor/rules/*`, `.cursorrules`, `.github/copilot-instructions.md`, and `opencode.json`. |
+| `prompts/tasks/readme.md` | Generates or rewrites a top-level README from scan output and selected files. |
+| `prompts/tasks/api-docs.md` | Documents public APIs when endpoints/interfaces are evident. |
+| `prompts/tasks/stack-docs.md` | Documents stack-specific areas of a repo. |
+| `prompts/tasks/diagrams.md` | Generates Mermaid architecture or flow diagrams. |
+| `prompts/tasks/flows.md` | Documents user, request, job, or data flows. |
+| `prompts/tasks/version-audit.md` | Audits pinned versions from manifests, lockfiles, Dockerfiles, workflows, or IaC. |
+| `prompts/tasks/check.md` | Checks existing docs for staleness against a fresh scan. |
+| `prompts/tasks/review.md` | Summarizes documentation impact for review. |
+
+## Docs And Spec
+
+- `SPEC.md` tracks phases, invariants, and tasks so future PRs can make small status updates instead of broad rewrites.
+- `docs/getting-started.md` explains manual prompt use.
+- `docs/prompt-guide.md` explains how system, partial, and task prompts compose.
+- `docs/editor-agent-setup.md` explains how to adapt prompts to local agents.
+- `docs/roadmap.md` mirrors the `SPEC.md` phase status in human-readable form.
+- `docs/agent-distribution-design.md` records the design that backs the Codex/Claude packages and `forerunner install`.
+
+## Configuration
+
+`forerunner.config.yaml.example` documents the loaded schema. Copy it to `forerunner.config.yaml` to opt in; without that file, `forerunner check` is a silent no-op. The schema has top-level provider/model fields (`provider`, `model`, `api_key_env`, `output_dir`, `context_max_files`, `context_max_lines_per_file`, `approaching_eol_threshold_months`), `ignore_patterns`, `tasks.version_audit`, and `tasks.check`. `forerunner check` honors `tasks.check.enabled_rules` (allowlist of rule IDs, default all) and `tasks.check.ignore_paths` (fnmatch globs applied to scanned docs). Invalid YAML, unknown providers, unknown `api_key_env` providers, or unknown severities surface as a `ConfigError` and exit non-zero.
+
+### MCP Server
+
+`forerunner mcp-server` speaks JSON-RPC 2.0 over stdio and exposes one tool per `prompts/tasks/*.md` (tool name = filename stem). Each `tools/call` returns the resolved `base + partials + task` bundle as text. A scan-first gate enforces SPEC V2: any tool other than `scan` or `init-agent-onboarding` returns an error until `scan` has been called in the same session. Point any MCP-compatible client at `forerunner mcp-server` as a stdio server (running from the target repo so `prompts/tasks/` resolves).
+
+See `examples/mcp/` for Claude Desktop and mcp-cli wiring examples.
+
+## Roadmap
+
+See `SPEC.md` for the canonical phase/task tracker and `docs/roadmap.md` for the human-readable roadmap.

codeforerunner-0.3.0/README.md

@@ -0,0 +1,106 @@
+![codeForerunner — your codebase gets a Forerunner; your docs finally see the light](images/readme_banner.png)
+
+# codeForerunner
+
+CodeForerunner is a model-agnostic documentation agent that acts as overwatch for your repository, automatically analyzing code and maintaining docs, diagrams, and architecture knowledge as your codebase evolves over time.
+
+The current repo is the prompt-first foundation for that agent: it ships prompt assets for understanding a codebase and generating developer docs. A thin Python CLI (including `forerunner mcp-server` and a scoped `forerunner init --full / --agents-only`), an idempotent skill installer, pre-commit + CI hooks, and a PyPI publish workflow now wrap those prompts; the first published PyPI release remains pending.
+
+## Current State
+
+- Core product: Markdown prompts in `prompts/`.
+- Agent package artifacts: Codex plugin files under `plugins/codeforerunner/` and Claude Code plugin files under `.claude-plugin/` plus `skills/codeforerunner/`.
+- Python package: `pyproject.toml` + `src/codeforerunner/` expose a `forerunner` console script. `forerunner doc <task>` resolves the prompt bundle (base + partials + task) to stdout; `forerunner install <agent>` idempotently writes the canonical skill into agent-specific directories; `forerunner init` resolves the agent-onboarding bundle (with `--full` to prepend a scan or `--agents-only` for the default scope); `forerunner scan` resolves the scan bundle; `forerunner mcp-server` serves prompt bundles as MCP tools over stdio.
+- Hooks: `.pre-commit-hooks.yaml` exposes a `forerunner-check` hook; `.github/workflows/forerunner-check.yml` mirrors it in CI. Both no-op when `forerunner.config.yaml` is absent.
+- Current config: `forerunner.config.yaml.example` documents the schema now parsed by `src/codeforerunner/config.py`; see "Configuration" below.
+- Not currently present: Docker image, Makefile, published PyPI release.
+
+## Install
+
+After the first PyPI release:
+
+```bash
+pipx install codeforerunner   # recommended; isolated environment
+pip install codeforerunner    # alternative
+```
+
+From source:
+
+```bash
+git clone https://github.com/derek-palmer/codeForerunner
+cd codeForerunner
+python -m pip install -e .
+```
+
+Then `forerunner --help` should print the subcommand list.
+
+## Prompt Layout
+
+```text
+prompts/
+├── system/
+│   └── base.md
+├── partials/
+│   ├── context-format.md
+│   ├── output-rules.md
+│   └── stack-hints.md
+└── tasks/
+    ├── scan.md
+    ├── init-agent-onboarding.md
+    ├── readme.md
+    ├── api-docs.md
+    ├── stack-docs.md
+    ├── diagrams.md
+    ├── flows.md
+    ├── version-audit.md
+    ├── check.md
+    └── review.md
+```
+
+## Quick Start
+
+1. Open `prompts/system/base.md` and use it as the agent system or project instruction.
+2. Assemble repo context using the shape in `prompts/partials/context-format.md`.
+3. For documentation generation, run `prompts/tasks/scan.md` first.
+4. For agent onboarding only, run `prompts/tasks/init-agent-onboarding.md` directly.
+5. Pass the scan result into one downstream documentation prompt, such as `prompts/tasks/readme.md` or `prompts/tasks/stack-docs.md`.
+6. Apply generated docs only after checking that every claim is grounded in provided files.
+
+## What The Prompts Do
+
+| Prompt | Purpose |
+| --- | --- |
+| `prompts/system/base.md` | Defines the codeforerunner role, quality bar, Markdown rules, and accuracy constraints. |
+| `prompts/tasks/scan.md` | Produces the first structured repo scan used by downstream tasks. |
+| `prompts/tasks/init-agent-onboarding.md` | Generates or updates `AGENTS.md` from repo evidence plus files such as `CLAUDE.md`, `.cursor/rules/*`, `.cursorrules`, `.github/copilot-instructions.md`, and `opencode.json`. |
+| `prompts/tasks/readme.md` | Generates or rewrites a top-level README from scan output and selected files. |
+| `prompts/tasks/api-docs.md` | Documents public APIs when endpoints/interfaces are evident. |
+| `prompts/tasks/stack-docs.md` | Documents stack-specific areas of a repo. |
+| `prompts/tasks/diagrams.md` | Generates Mermaid architecture or flow diagrams. |
+| `prompts/tasks/flows.md` | Documents user, request, job, or data flows. |
+| `prompts/tasks/version-audit.md` | Audits pinned versions from manifests, lockfiles, Dockerfiles, workflows, or IaC. |
+| `prompts/tasks/check.md` | Checks existing docs for staleness against a fresh scan. |
+| `prompts/tasks/review.md` | Summarizes documentation impact for review. |
+
+## Docs And Spec
+
+- `SPEC.md` tracks phases, invariants, and tasks so future PRs can make small status updates instead of broad rewrites.
+- `docs/getting-started.md` explains manual prompt use.
+- `docs/prompt-guide.md` explains how system, partial, and task prompts compose.
+- `docs/editor-agent-setup.md` explains how to adapt prompts to local agents.
+- `docs/roadmap.md` mirrors the `SPEC.md` phase status in human-readable form.
+- `docs/agent-distribution-design.md` records the design that backs the Codex/Claude packages and `forerunner install`.
+
+## Configuration
+
+`forerunner.config.yaml.example` documents the loaded schema. Copy it to `forerunner.config.yaml` to opt in; without that file, `forerunner check` is a silent no-op. The schema has top-level provider/model fields (`provider`, `model`, `api_key_env`, `output_dir`, `context_max_files`, `context_max_lines_per_file`, `approaching_eol_threshold_months`), `ignore_patterns`, `tasks.version_audit`, and `tasks.check`. `forerunner check` honors `tasks.check.enabled_rules` (allowlist of rule IDs, default all) and `tasks.check.ignore_paths` (fnmatch globs applied to scanned docs). Invalid YAML, unknown providers, unknown `api_key_env` providers, or unknown severities surface as a `ConfigError` and exit non-zero.
+
+### MCP Server
+
+`forerunner mcp-server` speaks JSON-RPC 2.0 over stdio and exposes one tool per `prompts/tasks/*.md` (tool name = filename stem). Each `tools/call` returns the resolved `base + partials + task` bundle as text. A scan-first gate enforces SPEC V2: any tool other than `scan` or `init-agent-onboarding` returns an error until `scan` has been called in the same session. Point any MCP-compatible client at `forerunner mcp-server` as a stdio server (running from the target repo so `prompts/tasks/` resolves).
+
+See `examples/mcp/` for Claude Desktop and mcp-cli wiring examples.
+
+## Roadmap
+
+See `SPEC.md` for the canonical phase/task tracker and `docs/roadmap.md` for the human-readable roadmap.

codeforerunner-0.3.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "codeforerunner"
+version = "0.3.0"
+description = "Model-agnostic repository documentation tooling (prompt-first; thin CLI)."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "LicenseRef-Codeforerunner-SAL-0.1"
+license-files = ["LICENSE.md"]
+authors = [{ name = "Derek Palmer" }]
+dependencies = [
+  "PyYAML>=6.0",
+]
+
+[project.urls]
+Repository = "https://github.com/derek-palmer/codeforerunner"
+Issues = "https://github.com/derek-palmer/codeforerunner/issues"
+
+[project.scripts]
+forerunner = "codeforerunner.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+codeforerunner = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

codeforerunner-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

codeforerunner-0.3.0/src/codeforerunner/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

codeforerunner-0.3.0/src/codeforerunner/check.py

@@ -0,0 +1,156 @@
+"""Drift detection for docs that claim files don't exist when they do."""
+from __future__ import annotations
+
+import fnmatch
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from codeforerunner.config import CheckConfig
+
+
+@dataclass(frozen=True)
+class Violation:
+    path: Path
+    line: int
+    rule_id: str
+    message: str
+
+
+_RULES = [
+    (
+        "R1-no-cli",
+        re.compile(
+            r"(?i)no\s+CLI\s+exists"
+            r"|CLI\s+does\s+not\s+exist"
+            r"|not\s+currently\s+present:[^.]*\bCLI\b"
+            r"|Do\s+not\s+run\s+`forerunner`"
+        ),
+        ("src/codeforerunner/cli.py",),
+        "doc claims no CLI exists, but src/codeforerunner/cli.py is present",
+    ),
+    (
+        "R2-no-pre-commit",
+        re.compile(r"(?i)no\s+pre[- ]commit(\s+hook)?"),
+        (".pre-commit-hooks.yaml",),
+        "doc claims no pre-commit hook, but .pre-commit-hooks.yaml is present",
+    ),
+    (
+        "R3-no-ci",
+        re.compile(r"(?i)no\s+CI(\s+workflow)?"),
+        (".github/workflows/*.yml",),
+        "doc claims no CI workflow, but .github/workflows/*.yml is present",
+    ),
+    (
+        "R4-no-installer",
+        re.compile(r"(?i)no\s+installer"),
+        ("src/codeforerunner/installer.py",),
+        "doc claims no installer, but src/codeforerunner/installer.py is present",
+    ),
+    (
+        "R5-no-python-package",
+        re.compile(r"(?i)no\s+Python\s+package"),
+        ("pyproject.toml",),
+        "doc claims no Python package, but pyproject.toml is present",
+    ),
+    (
+        "R6-no-docker",
+        re.compile(r"(?i)no\s+Docker(\s+image)?|no\s+Dockerfile"),
+        ("Dockerfile", "compose.yml", "docker-compose.yml"),
+        "doc claims no Docker, but Dockerfile/compose file is present",
+    ),
+    (
+        "R6b-no-makefile",
+        re.compile(r"(?i)no\s+Makefile"),
+        ("Makefile",),
+        "doc claims no Makefile, but Makefile is present",
+    ),
+    (
+        "R7-no-mcp",
+        re.compile(r"(?i)no\s+MCP(\s+server)?"),
+        ("src/codeforerunner/mcp_server.py",),
+        "doc claims no MCP server, but src/codeforerunner/mcp_server.py is present",
+    ),
+    (
+        "R8-no-marketplace",
+        re.compile(r"(?i)no\s+marketplace(\s+manifest)?"),
+        ("plugins/codex/marketplace.json",),
+        "doc claims no marketplace, but plugins/codex/marketplace.json is present",
+    ),
+]
+
+
+def _trigger_exists(repo: Path, patterns: tuple[str, ...]) -> bool:
+    for pat in patterns:
+        if "*" in pat:
+            parent = repo / Path(pat).parent
+            name = Path(pat).name
+            if parent.is_dir() and any(parent.glob(name)):
+                return True
+        else:
+            if (repo / pat).exists():
+                return True
+    return False
+
+
+def _scanned_docs(repo: Path) -> list[Path]:
+    docs: list[Path] = []
+    readme = repo / "README.md"
+    if readme.is_file():
+        docs.append(readme)
+    docs_dir = repo / "docs"
+    if docs_dir.is_dir():
+        docs.extend(sorted(p for p in docs_dir.rglob("*.md") if p.is_file()))
+    return docs
+
+
+def _path_ignored(repo: Path, doc: Path, ignore_patterns: tuple[str, ...]) -> bool:
+    if not ignore_patterns:
+        return False
+    try:
+        rel = doc.relative_to(repo).as_posix()
+    except ValueError:
+        rel = doc.as_posix()
+    return any(fnmatch.fnmatch(rel, pat) for pat in ignore_patterns)
+
+
+def run(repo: Path, config: CheckConfig | None = None) -> list[Violation]:
+    """Scan repo docs for drift; return list of violations.
+
+    `config` filters rules via `enabled_rules` and skips docs matching `ignore_paths`.
+    `None` config (default) preserves the pre-T25 behavior: all rules, no ignores.
+    """
+    repo = Path(repo)
+    enabled = set(config.enabled_rules) if (config and config.enabled_rules is not None) else None
+    ignore_patterns = config.ignore_paths if config else ()
+
+    active_rules = [
+        (rid, rx, msg)
+        for rid, rx, triggers, msg in _RULES
+        if _trigger_exists(repo, triggers) and (enabled is None or rid in enabled)
+    ]
+    if not active_rules:
+        return []
+
+    violations: list[Violation] = []
+    for doc in _scanned_docs(repo):
+        if _path_ignored(repo, doc, ignore_patterns):
+            continue
+        try:
+            text = doc.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        for lineno, line in enumerate(text.splitlines(), start=1):
+            for rid, rx, msg in active_rules:
+                if rx.search(line):
+                    violations.append(
+                        Violation(path=doc, line=lineno, rule_id=rid, message=msg)
+                    )
+    return violations
+
+
+def format_violations(vs: list[Violation]) -> str:
+    """Format violations one per line for stderr."""
+    return "\n".join(
+        f"{v.path}:{v.line}: {v.rule_id}: {v.message}" for v in vs
+    )