#!/usr/bin/env python3
"""Offline HTML wrapper for the LLM wiki (REQ-109).
Reads every canonical wiki page through the page contract (prd_tools wiki
list/read) and emits ONE self-contained HTML file: a page list, a rendered
view, and two controls top-right — Copy Markdown (clipboard) and Download .md
(saves the exact source to the browser's download folder). No remote, no
server, no CDN: open the file in any browser.
Usage:
python scripts/wiki_html_export.py [--repo-root .] [--output PATH]
Default output: .prd_plugin/local/wiki-html/index.html (per-clone runtime,
already gitignored downstream).
"""
from __future__ import annotations
import argparse
import json
import re
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
import prd_tools
DEFAULT_REL = Path(".prd_plugin") / "local" / "wiki-html" / "index.html"
_TEMPLATE = """
__TITLE__
"""
def build_html(root, hub_link=None):
"""The complete standalone viewer for one repo's wiki."""
listing = prd_tools.run_tool("wiki", str(root), {"action": "list"})
pages = []
for page in listing["pages"]:
pages.append(prd_tools.run_tool(
"wiki", str(root), {"action": "read", "path": page["path"]}))
for page in pages:
page.pop("text", None)
payload = json.dumps(
{"repo_id": listing["repo_id"], "contract_version": listing["contract_version"],
"pages": pages},
ensure_ascii=False)
# A literal inside page markdown would terminate the JSON block
# early in the browser; escape the slash (harmless inside JSON strings).
payload = payload.replace("⌂ All wikis (all-wikis.html)'
if hub_link else "")
return (_TEMPLATE
.replace("__TITLE__", title)
.replace("__HUB_LINK__", hub_html)
.replace("__PAYLOAD__", payload))
def export(root, output=None, hub_link=None):
root = Path(root)
target = Path(output) if output else root / DEFAULT_REL
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text(build_html(root, hub_link=hub_link),
encoding="utf-8", newline="\n")
return str(target)
def discover_repos(workspace_root):
"""Immediate children of the workspace whose wiki follows the LLM-wiki
convention (wiki/index.md). PRD Plugin installation is NOT required —
core repos like Fork keep convention wikis without the plugin (REQ-111)."""
repos = []
for child in sorted(Path(workspace_root).iterdir()):
if child.is_dir() and (child / "wiki" / "index.md").is_file():
repos.append(child)
return repos
_LOG_HEADING = re.compile(r"^## \[(\d{4}-\d{2}-\d{2})\]\s*(.*)$")
def parse_wiki_log(root):
"""Entries from a repo's wiki/log.md: {date, heading, body, is_lint}.
Every workspace log shares the '## [YYYY-MM-DD] mode | text' convention
(REQ-112 grounded survey); repos without a log yield []."""
log = Path(root) / "wiki" / "log.md"
if not log.is_file():
return []
entries = []
for line in log.read_text(encoding="utf-8-sig").splitlines():
match = _LOG_HEADING.match(line)
if match:
heading = match.group(2).strip()
entries.append({"date": match.group(1), "heading": heading,
"body": [],
"is_lint": heading.startswith("lint |")})
elif entries and line.strip() and not line.startswith("# "):
entries[-1]["body"].append(line.rstrip())
return entries
def _html_escape(text):
return (text.replace("&", "&").replace("<", "<").replace(">", ">"))
_SUPER_TEMPLATE = """
All wikis
All wikis
Every repo in this workspace with a convention knowledge base.
Click a repo to open its wiki index (copy/download buttons top right).
__CARDS__
Every wiki's log, combined — newest day first. Entries link to the repo's
own wiki log.
__CHANGELOG__
"""
def _changelog_html(log_entries):
"""Grouped-by-date (newest first) HTML for the combined changelog.
log_entries: [(repo_name, viewer_uri, entry), ...]"""
by_date = {}
for repo_name, viewer_uri, entry in log_entries:
by_date.setdefault(entry["date"], []).append((repo_name, viewer_uri, entry))
sections = []
for date in sorted(by_date, reverse=True):
rows = []
for repo_name, viewer_uri, entry in by_date[date]:
body = _html_escape("\n".join(entry["body"]))
rows.append(
f'
')
return "\n".join(sections)
def export_all(workspace_root, host_repo, output=None):
"""Generate every repo's viewer plus the workspace super index. The super
index lands in the host repo's local runtime dir; each generated viewer
links back to it."""
host = Path(host_repo)
target = Path(output) if output else (
host / ".prd_plugin" / "local" / "wiki-html" / "all-wikis.html")
target.parent.mkdir(parents=True, exist_ok=True)
hub_uri = target.resolve().as_uri()
cards = []
log_entries = []
for repo in discover_repos(workspace_root):
if (repo / ".prd_plugin").is_dir():
viewer = Path(export(repo, hub_link=hub_uri))
else:
# Guest repo (no PRD Plugin, e.g. Fork): never plant plugin dirs
# in its tree — host its viewer beside the super index.
viewer = Path(export(repo, output=target.parent / f"{repo.name}.html",
hub_link=hub_uri))
viewer_uri = viewer.resolve().as_uri()
count = len(prd_tools.run_tool("wiki", str(repo), {"action": "list"})["pages"])
cards.append(
f''
f"{repo.name}{count} pages")
for entry in parse_wiki_log(repo):
log_entries.append((repo.name, viewer_uri, entry))
target.write_text(
_SUPER_TEMPLATE
.replace("__CARDS__", "\n".join(cards))
.replace("__CHANGELOG__", _changelog_html(log_entries)),
encoding="utf-8", newline="\n")
return str(target)
def main(argv=None):
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--repo-root", default=".")
parser.add_argument("--output", default=None)
parser.add_argument("--all", action="store_true",
help="Generate every workspace repo's viewer plus the "
"all-wikis super index (REQ-110).")
parser.add_argument("--workspace-root", default=None,
help="Workspace to scan with --all (default: the "
"repo root's parent directory).")
args = parser.parse_args(argv)
if args.all:
workspace = args.workspace_root or str(Path(args.repo_root).resolve().parent)
target = export_all(workspace, args.repo_root, args.output)
print(f"workspace super index written to {target}")
print("Open it in a browser: click a repo to open its wiki index.")
return 0
target = export(args.repo_root, args.output)
print(f"wiki viewer written to {target}")
print("Open it in a browser: page list on the left, Copy Markdown / "
"Download .md top right.")
return 0
if __name__ == "__main__":
sys.exit(main())