boshu2__agentops/docs/_hooks/gen_cli_reference.py

"""Generate CLI reference pages at MkDocs build time.

Copies the canonical generated CLI docs from cli/docs/ into docs/cli/ so they
render inside the published site without requiring a symlink (which the repo
bans). Source of truth remains cli/docs/COMMANDS.md, regenerated by
scripts/generate-cli-reference.sh.
"""

from __future__ import annotations

import sys
from pathlib import Path

import mkdocs_gen_files

REPO_ROOT = Path(__file__).resolve().parent.parent.parent
CLI_DOCS = REPO_ROOT / "cli" / "docs"


def emit(src: Path, dest: str, title: str) -> None:
    if not src.is_file():
        # Fail the build rather than silently publishing a "file-not-found"
        # page. CLI reference drift would otherwise ship unnoticed.
        raise SystemExit(
            f"[gen_cli_reference] FATAL: missing source {src.relative_to(REPO_ROOT)}. "
            f"Run scripts/generate-cli-reference.sh to regenerate {title}, "
            f"or remove the docs/_hooks/gen_cli_reference.py emit() call if the "
            f"reference is intentionally retired."
        )

    content = src.read_text(encoding="utf-8")
    # Prepend a short header note that this page is auto-generated.
    header = (
        f"<!-- Auto-generated from {src.relative_to(REPO_ROOT)} at build time. "
        f"Edit the source, not this file. Regenerate with "
        f"`scripts/generate-cli-reference.sh`. -->\n\n"
    )
    with mkdocs_gen_files.open(dest, "w") as fh:
        fh.write(header + content)


def emit_index() -> None:
    body = """# CLI Overview

The `ao` CLI provides deterministic repository checks and optional evidence
utilities. Semantic workflows remain skills rather than CLI lifecycle commands.

<div class="grid cards" markdown>

- :material-console: **[Command Reference](commands.md)**
  Every `ao` command with flags, examples, and exit codes. Auto-generated from
  `ao --help`.

- :material-map: **[CLI Surface](../cli-surface.md)**
  Generated public command inventory and coverage classification.

</div>

## Installation

The CLI is optional — skills install without it via
`npx skills@latest add boshu2/agentops --all -g` or a runtime plugin.

```bash
brew tap boshu2/agentops https://github.com/boshu2/homebrew-agentops
brew install agentops
```

Without Homebrew: `go install github.com/boshu2/agentops/cli/cmd/ao@latest`

To track skills from a source checkout instead, run `ao skills link` from that
checkout (see [Install and day-2 operations](../install-day2-ops.md)).

## Quickstart

```bash
ao version                # Verify install
ao doctor                 # Installation health
ao init                   # Create local evidence directories
ao status                 # Durable loop evidence
ao gate check             # Deterministic repository checks
```

The semantic loop (`rpi`, `plan`, `implement`, `validate`) runs as skills in
your coding agent, not as CLI commands.
"""
    with mkdocs_gen_files.open("cli/index.md", "w") as fh:
        fh.write(body)


def main() -> None:
    emit_index()
    emit(CLI_DOCS / "COMMANDS.md", "cli/commands.md", "Command Reference")
    print("[gen_cli_reference] emitted cli/{index,commands}.md", file=sys.stderr)


main()