FrameBridge 0.3.1 community source release

source/expanded/framebridge_expanded/guide.py

@@ -0,0 +1,63 @@
+"""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