64 lines
2.7 KiB
Python
64 lines
2.7 KiB
Python
"""Versioned, read-only English guide shared by CLI, MCP and website documentation."""
|
|
from __future__ import annotations
|
|
import copy
|
|
import hashlib
|
|
import json
|
|
from . import __version__
|
|
|
|
PRODUCT = "FrameBridge"
|
|
GUIDE_SCHEMA = 1
|
|
from .guide_data import GUIDE as _GUIDE
|
|
|
|
def topics():
|
|
"""Return the bounded public guide-topic names."""
|
|
return tuple(_GUIDE)
|
|
|
|
def _digest(value):
|
|
raw = json.dumps(value, sort_keys=True, ensure_ascii=True, separators=(",", ":")).encode()
|
|
return hashlib.sha256(raw).hexdigest()
|
|
|
|
def get_guide(topic="start"):
|
|
"""Read static help without touching profiles, credentials, processes or network."""
|
|
if not isinstance(topic, str) or len(topic) > 64:
|
|
return {"ok": False, "error": "HELP_TOPIC_INVALID", "topics": list(topics())}
|
|
topic = topic.strip().lower()
|
|
if topic == "all":
|
|
sections = []
|
|
for name, entry in _GUIDE.items():
|
|
sections.append({"heading": entry["title"], "body": "Guide topic: " + name, "commands": []})
|
|
sections.extend(copy.deepcopy(entry["sections"]))
|
|
title = "FrameBridge complete command guide"
|
|
elif topic in _GUIDE:
|
|
entry = _GUIDE[topic]
|
|
title, sections = entry["title"], copy.deepcopy(entry["sections"])
|
|
else:
|
|
return {"ok": False, "error": "HELP_TOPIC_UNKNOWN", "topic": topic, "topics": list(topics()),
|
|
"product": PRODUCT, "version": __version__, "guide_schema": GUIDE_SCHEMA}
|
|
value = {"ok": True, "product": PRODUCT, "version": __version__, "guide_schema": GUIDE_SCHEMA,
|
|
"topic": topic, "title": title, "sections": sections, "topics": list(topics()),
|
|
"read_only": True, "capabilities_verified": False}
|
|
value["guide_sha256"] = _digest(value)
|
|
return value
|
|
|
|
def render_text(topic="start"):
|
|
"""Render the same guide as a navigable offline text reference."""
|
|
guide = get_guide(topic)
|
|
if not guide["ok"]:
|
|
raise ValueError("Unknown help topic. Choose: " + ", ".join(topics()))
|
|
lines = [guide["title"], "FrameBridge " + guide["version"] + " | guide schema " + str(GUIDE_SCHEMA), ""]
|
|
for section in guide["sections"]:
|
|
lines.extend([section["heading"], section["body"], ""])
|
|
lines.extend(" " + command for command in section["commands"])
|
|
if section["commands"]:
|
|
lines.append("")
|
|
if topic != "all":
|
|
lines.append("More help: fb help " + " | ".join(topics()))
|
|
return "\n".join(lines).rstrip() + "\n"
|
|
|
|
def export_guide():
|
|
"""Return the versioned static export used to generate website documentation."""
|
|
value = {"product": PRODUCT, "version": __version__, "guide_schema": GUIDE_SCHEMA,
|
|
"topics": {name: get_guide(name) for name in topics()}}
|
|
value["guide_sha256"] = _digest(value)
|
|
return value
|