fix(docs): publish directly from LangBot before archiving docs repository

Co-authored-by: multica-agent <[email protected]>

docs/README.md

@@ -1,6 +1,6 @@
 # [LangBot](https://github.com/langbot-app/LangBot) 官方文档
 
-> 文档源码位于 [LangBot/docs](https://github.com/langbot-app/LangBot/tree/main/docs)，[langbot-docs](https://github.com/langbot-app/langbot-docs) 仅作为发布 mirror。
+> 文档源码位于 [LangBot/docs](https://github.com/langbot-app/LangBot/tree/master/docs)，[langbot-docs](https://github.com/langbot-app/langbot-docs) 将作为历史归档保留。
 > [LangBot 代码仓库](https://github.com/langbot-app/LangBot)  
 > 这是 LangBot 4.0 的文档，3.0 文档请见 [langbot-docs 的 v3 分支](https://github.com/langbot-app/langbot-docs/tree/v3)
 

docs/README_EN.md

@@ -1,4 +1,4 @@
-> Edit documentation in [LangBot/docs](https://github.com/langbot-app/LangBot/tree/main/docs). The [langbot-docs repository](https://github.com/langbot-app/langbot-docs) is a generated publication mirror. Run the commands below from `LangBot/docs/`.
+> Edit documentation in [LangBot/docs](https://github.com/langbot-app/LangBot/tree/master/docs). The [langbot-docs repository](https://github.com/langbot-app/langbot-docs) is retained as a historical archive. Run the commands below from `LangBot/docs/`.
 
 # [LangBot](https://github.com/langbot-app/LangBot) Official Documentation
 

docs/context7.json

@@ -1,4 +0,0 @@
-{
-  "url": "https://context7.com/langbot-app/langbot-docs",
-  "public_key": "pk_lYnjPxdPQabvC87DxU34F"
-}

docs/node_modules

@@ -0,0 +1 @@
+../../LangBot/docs/node_modules

docs/scripts/build-github-wiki.py

@@ -73,7 +73,7 @@ def rewrite_url(source: PurePosixPath, target: str, *, image: bool = False) -> s
         return target
     if image:
         path = parsed.path.lstrip("/") if parsed.path.startswith("/") else (source.parent / parsed.path).as_posix()
-        return urlunsplit(("https", "raw.githubusercontent.com", f"/langbot-app/langbot-docs/main/{path}", parsed.query, parsed.fragment))
+        return urlunsplit(("https", "raw.githubusercontent.com", f"/langbot-app/LangBot/master/docs/{path}", parsed.query, parsed.fragment))
     return resolve_doc_target(source, target) or target
 
 
@@ -235,7 +235,7 @@ def build(root: Path, output: Path) -> int:
     home = [
         "# LangBot Documentation",
         "",
-        "This GitHub Wiki is automatically synchronized from [langbot-app/langbot-docs](https://github.com/langbot-app/langbot-docs).",
+        "This GitHub Wiki is automatically synchronized from [LangBot/docs](https://github.com/langbot-app/LangBot/tree/master/docs).",
         "",
     ]
     for language, label in LANGUAGES.items():
@@ -246,7 +246,7 @@ def build(root: Path, output: Path) -> int:
     (output / "Home.md").write_text("\n".join(home).rstrip() + "\n", encoding="utf-8")
     (output / "_Sidebar.md").write_text(build_sidebar(root, titles), encoding="utf-8")
     (output / "_Footer.md").write_text(
-        "Automatically synchronized from [langbot-app/langbot-docs](https://github.com/langbot-app/langbot-docs).\n",
+        "Automatically synchronized from [LangBot/docs](https://github.com/langbot-app/LangBot/tree/master/docs).\n",
         encoding="utf-8",
     )
     return len(documents)

docs/scripts/sync-landing-submodule.py

@@ -1,12 +1,14 @@
 #!/usr/bin/env python3
 """Advance only the landing docs gitlink, then sync its production fork."""
 import argparse
+import base64
+import configparser
 import json
 import os
 import urllib.error
 import urllib.request
 
-SOURCE = "langbot-app/langbot-docs"
+SOURCE = "langbot-app/LangBot"
 TARGET = "langbot-app/langbot-landing-page"
 DEPLOY = "RockChinQ/LangBot-LandingPage-Vue"
 
@@ -25,14 +27,24 @@ def api(method, path, data=None):
         return json.load(response)
 
 
-def head(call, repo):
-    return call("GET", repo + "/git/ref/heads/main")["object"]["sha"]
+def head(call, repo, branch="main"):
+    return call("GET", repo + "/git/ref/heads/" + branch)["object"]["sha"]
 
 
 def sync(call=api, dry_run=False):
     for attempt in range(5):
-        source = head(call, SOURCE)  # Coalesce queued events onto current main.
+        source = head(call, SOURCE, "master")
         parent = head(call, TARGET)
+        # Check the same target revision used to build the candidate tree. Never
+        # put a LangBot SHA into a gitlink still configured for the old repository.
+        modules = call("GET", TARGET + "/contents/.gitmodules?ref=" + parent)
+        config = configparser.ConfigParser(interpolation=None)
+        config.read_string(base64.b64decode(modules["content"]).decode("utf-8"))
+        section = 'submodule "docs"'
+        if (config.get(section, "path", fallback=None) != "docs"
+                or config.get(section, "url", fallback=None) != "https://github.com/langbot-app/LangBot.git"
+                or config.get(section, "branch", fallback=None) != "master"):
+            raise RuntimeError("Landing docs must point to LangBot/master before synchronization")
         commit = call("GET", TARGET + "/git/commits/" + parent)
         tree = call("GET", TARGET + "/git/trees/" + commit["tree"]["sha"])
         entry = next(item for item in tree["tree"] if item["path"] == "docs")
@@ -52,7 +64,7 @@ def sync(call=api, dry_run=False):
             "tree": [{"path": "docs", "mode": "160000", "type": "commit", "sha": source}],
         })
         candidate = call("POST", TARGET + "/git/commits", {
-            "message": "docs: sync langbot-docs@" + source[:12],
+            "message": "docs: sync LangBot@" + source[:12],
             "tree": updated["sha"], "parents": [parent],
             "author": {"name": "github-actions[bot]", "email": "41898282+github-actions[bot]@users.noreply.github.com"},
         })

docs/tests/test_build_github_wiki.py

@@ -36,7 +36,7 @@ description: "ignored"
         self.assertIn("> **提示**", output)
         self.assertIn("[模型文档](zh-usage-models-readme)", output)
         self.assertIn(
-            "https://raw.githubusercontent.com/langbot-app/langbot-docs/main/images/ui.png",
+            "https://raw.githubusercontent.com/langbot-app/LangBot/master/docs/images/ui.png",
             output,
         )
 

docs/tests/test_sync_landing_submodule.py

@@ -1,4 +1,5 @@
 """Offline API-contract tests; the workflow run verifies real GitHub writes."""
+import base64
 import importlib.util
 from pathlib import Path
 import unittest
@@ -10,8 +11,9 @@ spec.loader.exec_module(sync)
 
 
 class FakeAPI:
-    def __init__(self, already=False, conflict=False, status="ahead"):
+    def __init__(self, already=False, conflict=False, status="ahead", migrated=True):
         self.calls = []
+        self.migrated = migrated
         self.pin = "new-docs" if already else "old-docs"
         self.landing = "landing-parent"
         self.deploy = "old-deploy"
@@ -20,7 +22,12 @@ class FakeAPI:
 
     def __call__(self, method, path, data=None):
         self.calls.append((method, path, data))
-        if path.endswith("/git/ref/heads/main"):
+        if "/contents/.gitmodules?ref=" in path:
+            repo = "LangBot" if self.migrated else "langbot-docs"
+            branch = "master" if self.migrated else "main"
+            content = f'[submodule "docs"]\npath = docs\nurl = https://github.com/langbot-app/{repo}.git\nbranch = {branch}\n'
+            return {"content": base64.b64encode(content.encode()).decode()}
+        if "/git/ref/heads/" in path:
             sha = "new-docs" if path.startswith(sync.SOURCE + "/") else self.deploy if path.startswith(sync.DEPLOY + "/") else self.landing
             return {"object": {"sha": sha}}
         if method == "GET" and "/git/commits/" in path:
@@ -83,3 +90,16 @@ class SyncTests(unittest.TestCase):
             with self.assertRaises(RuntimeError):
                 sync.sync(api)
             self.assertTrue(all(m == "GET" for m, p, d in api.calls))
+
+    def test_reads_master_and_does_not_contact_archived_repository(self):
+        api = FakeAPI()
+        sync.sync(api)
+        self.assertIn(("GET", "langbot-app/LangBot/git/ref/heads/master", None), api.calls)
+        self.assertFalse(any("langbot-app/langbot-docs/" in p for _, p, _ in api.calls))
+
+    def test_old_submodule_configuration_fails_before_any_write(self):
+        for already in [False, True]:
+            api = FakeAPI(already=already, migrated=False)
+            with self.assertRaisesRegex(RuntimeError, "must point to LangBot/master"):
+                sync.sync(api)
+            self.assertTrue(all(m == "GET" for m, _, _ in api.calls))