gabriel / musehub public
test_doc_gs.py python
370 lines 18.1 KB
Raw
sha256:c2ee54efa85fcbdeea4ffc84a2dd1b8fcd4623463b22e35765df3013a26834aa merge: #276 public URLs + muse#181 docs onto dev (#313 present) Opus 5.5 minor ⚠ breaking 1 day ago
1 """DOC_GS — /muse/getting-started first-run contract (musehub#244).
2
3 Each claim below was walked against the installed muse 0.2.1rc20 CLI in a disposable sandbox
4 (2026-11-06): a commit is signed only with ``--sign`` or ``commit.sign = true``, and
5 ``verify-commit --strict`` confirms it; a new repo starts on ``main``; keys are derived at a
6 hub-scoped HD path; ``muse hub connect`` rejects non-loopback ``http://``; the edge redirects
7 ``http://…/install.sh`` with a 301. Rendering is the shared in-process fixture (no database).
8 """
9
10 from __future__ import annotations
11
12 import re
13 from collections.abc import Iterator
14 from pathlib import Path
15 from unittest.mock import patch
16 from urllib.parse import urlsplit
17
18 import pytest
19 from fastapi.testclient import TestClient
20
21 from musehub.api.routes.musehub.ui_docs import _PHASES
22 from musehub.config import settings
23 from musehub.main import app
24 from musehub.api.routes.musehub import ui_docs
25 from tests.docs_contract import registry_check as rc
26 from tests.docs_contract.cli_check import extract_commands
27 from tests.docs_contract.pages import _render
28
29 PAGE = rc.phase_path("getting-started")
30
31
32 @pytest.fixture(scope="module")
33 def html(rendered: dict[str, str]) -> str:
34 return rendered[PAGE].replace("'", "'")
35
36
37 def _render_on(base_url: str) -> str:
38 """The page as served from ``base_url`` (host-dependent examples; same version pin as ``rendered``).
39
40 A host outside ``allowed_hosts`` is never reflected (#276): a self-hosted hub names itself through
41 ``public_url``, so that is what serving from one sets.
42 """
43 with patch.object(settings, "public_url", base_url):
44 return _render(TestClient(app, base_url=base_url), [PAGE])[PAGE].replace("'", "'")
45
46
47 @pytest.fixture(scope="module")
48 def staging_html() -> str:
49 return _render_on("https://staging.musehub.ai")
50
51
52 @pytest.fixture(scope="module")
53 def commands(html: str) -> list[str]:
54 """Documented ``muse …`` lines in first-appearance order."""
55 return [c.line for c in extract_commands(html)]
56
57
58 def _section(html: str, section_id: str) -> str:
59 """One ``<section>``'s HTML, whitespace-collapsed so wrapped prose matches."""
60 return " ".join(html.split(f'id="{section_id}"', 1)[1].split("</section>", 1)[0].split())
61
62
63 # ── DOC_GS_02: "What's next" is the registry ────────────────────────────────
64
65
66 def test_whats_next_lists_every_other_section_in_registry_order(html: str) -> None:
67 rows = re.findall(r'<a href="(/muse/[\w-]+)">([^<]+)</a>', _section(html, "next"))
68 expected = [(rc.phase_path(s), f"{n} — {t}") for s, n, t, _ in _PHASES if s != "getting-started"]
69 assert rows == expected
70
71
72 # ── DOC_GS_03: sample output follows the request host ───────────────────────
73
74
75 def test_identity_sample_output_does_not_hard_code_a_hub_host(html: str) -> None:
76 assert "staging.musehub.ai" not in _section(html, "identity")
77
78
79 # ── DOC_GS_07: the first-run path never teaches an unsigned commit ──────────
80
81
82 def test_every_documented_commit_and_merge_signs(commands: list[str]) -> None:
83 writes = [c for c in commands if c.startswith(("muse commit ", "muse merge "))]
84 assert writes, "the page documents no commit"
85 assert [c for c in writes if "--sign" not in c.split()] == []
86
87
88 def test_signing_is_confirmed_with_strict_verification(commands: list[str]) -> None:
89 assert any(c.startswith("muse verify-commit ") and "--strict" in c.split() for c in commands)
90
91
92 def test_no_signing_output_the_cli_does_not_print(html: str) -> None:
93 # rc20 `commit --sign` prints the commit line and file summary only; there is no "signed with" line.
94 assert "signed with ed25519:" not in html
95
96
97 def test_bridge_note_does_not_claim_native_commits_are_always_signed(html: str) -> None:
98 assert "all commits made natively in Muse going forward will" not in _section(html, "migrate")
99
100
101 # ── DOC_GS_08: examples run in a brand-new repo, in order ───────────────────
102
103
104 def test_branch_cycle_creates_dev_before_checking_it_out(commands: list[str]) -> None:
105 # `muse init` creates `main` only; `muse checkout dev` fails until dev exists.
106 assert "muse checkout -b dev" in commands
107 assert commands.index("muse checkout -b dev") < commands.index("muse checkout dev")
108
109
110 def test_hd_paths_include_the_hub_level(html: str) -> None:
111 # Since hub scoping, identity keys sit at m/1075233755'/1660078172'/0'/0'/0'/<hub>'/0'.
112 assert "m/1075233755'/1660078172'/0'/0'/0'/0'" not in html
113
114
115 # ── DOC_GS_09: troubleshooting matches the deployed edge and CLI ────────────
116
117
118 def test_troubleshooting_has_no_stale_http_522_row(html: str) -> None:
119 assert "error: 522" not in html
120
121
122 # ── DOC_GS_10–12: hub-side QA findings on staging (2026-11-06, rc19 = rc20 for these paths) ──
123
124
125 def _hub_of(cmd: str) -> str | None:
126 toks = cmd.split()
127 return toks[toks.index("--hub") + 1] if "--hub" in toks[:-1] else None
128
129
130 def _add_remote_html(html: str) -> str:
131 return html.split('id="add-remote"', 1)[1].split("</section>", 1)[0]
132
133
134 def test_whoami_targets_the_registration_hub(html: str, commands: list[str]) -> None:
135 # GS-17: outside a repo, `muse auth whoami` falls back to https://localhost:1337 and finds no identity.
136 reg = {_hub_of(c) for c in commands if c.startswith(("muse auth keygen ", "muse auth register "))}
137 assert len(reg) == 1 and None not in reg
138 hub = next(iter(reg))
139 # The test client's Host ("testserver") is not allow-listed, so the page names the canonical public base (#276).
140 assert hub == settings.public_url.rstrip("/"), "hub must come from the public base, never an unlisted request host"
141 sec = html.split('id="identity"', 1)[1].split("</section>", 1)[0]
142 shown = [c.line for c in extract_commands(sec) if c.in_pre and c.line.startswith("muse auth whoami")]
143 shown += re.findall(r'devdocs-code-label">(muse auth whoami[^<]*)<', sec) # e.g. the --json example's label
144 assert shown, "the identity section documents whoami"
145 assert all(f"--hub {hub}" in s for s in shown), shown
146
147
148 def test_remote_setup_accounts_for_remotes_created_by_init(staging_html: str) -> None:
149 # GS-18: after registration, `muse init` writes local/staging/production remotes as <hub>/<handle>/<directory>.
150 sec = _add_remote_html(staging_html)
151 text = " ".join(re.sub(r"<[^>]+>", " ", sec).split())
152 runnable = [c.line for c in extract_commands(sec) if c.in_pre]
153 assert not [c for c in runnable if re.match(r"muse remote add (local|staging|production)\b", c)], runnable
154 assert "muse init" in text and all(n in text for n in ("local", "staging", "production")), "explain init's remotes"
155 assert "directory" in text, "explain that the remote URL is derived from the directory name"
156 assert "muse remote -v" in runnable and any(c.startswith("muse remote set-url staging ") for c in runnable)
157 assert runnable.index("muse remote -v") < next(i for i, c in enumerate(runnable) if c.startswith("muse remote set-url"))
158 created = next(c for c in runnable if c.startswith("muse hub repo create "))
159 name = created.split("--name", 1)[1].split()[0]
160 target = next(c for c in runnable if c.startswith("muse remote set-url staging ")).split()[-1]
161 assert target.rstrip("/").endswith(f"/your-handle/{name}"), (target, name)
162
163
164 def test_push_404_troubleshooting_checks_the_remote_url(html: str) -> None:
165 # GS-19: a 404 is a missing repo OR a remote URL pointing at one; a missing login is a 401, not a 404.
166 callout = next(" ".join(re.sub(r"<[^>]+>", " ", c.split("</div>", 1)[0]).split())
167 for c in html.split('class="devdocs-callout') if "Repository not found on remote" in c.split("</div>", 1)[0])
168 assert "muse remote -v" in callout and "muse remote set-url" in callout
169 assert "muse hub repo create" in callout
170 assert "401" in callout and "muse auth" in callout, "distinguish authentication failures"
171
172
173 # ── DOC_GS_06: no verified release → the page stays readable, nothing is installable ──
174 # Owner ruling 2026-11-07 (#244 "Getting Started without an active release"): 200 with an explicit
175 # notice and no version string; /install.sh keeps failing closed. The real selector runs against an
176 # empty releases directory (no active.json), so this is the production code path, not a patch.
177
178 _UNAVAILABLE = 'data-release-state="unavailable"'
179
180
181 @pytest.fixture
182 def no_release(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Iterator[tuple[TestClient, Path]]:
183 from musehub.config import settings
184
185 monkeypatch.setattr(settings, "musehub_releases_dir", str(tmp_path))
186 yield TestClient(app), tmp_path # no context manager → no lifespan → no database
187
188
189 def test_page_renders_without_an_active_release(no_release: tuple[TestClient, Path]) -> None:
190 client, releases = no_release
191 r = client.get(PAGE)
192 assert r.status_code == 200
193 page = r.text
194 assert page.count(_UNAVAILABLE) == 2, "both the install step and the version sample say so"
195 assert "No verified Muse release is available on this instance" in page
196 for section in ("prerequisites", "install", "identity", "new-repo", "workflow", "migrate", "next"):
197 assert f'id="{section}"' in page, f"static content stays readable: #{section}"
198 assert str(releases) not in page, "the selector's message names server paths; it must not reach the page"
199
200
201 def test_no_version_is_shown_without_an_active_release(no_release: tuple[TestClient, Path]) -> None:
202 from musehub.protocol.version import MUSE_VERSION
203
204 r = no_release[0].get(PAGE)
205 assert r.status_code == 200, "an error page shows no version vacuously"
206 page = r.text
207 assert re.search(r"<pre>\s*muse \S", page) is None, "no `muse <version>` sample output"
208 assert f"muse {MUSE_VERSION}" not in page, "never musehub's own app version (musehub#191)"
209
210
211 def test_install_script_still_fails_closed_without_an_active_release(no_release: tuple[TestClient, Path]) -> None:
212 r = no_release[0].get("/install.sh")
213 assert r.status_code == 503
214 assert "MUSE_VERSION=" not in r.text
215
216
217 def test_active_release_shows_its_version_and_no_notice(html: str) -> None:
218 # The shared fixture pins the pointer to 0.0.0-docs-contract (pages.py).
219 assert "<pre>muse 0.0.0-docs-contract</pre>" in html
220 assert _UNAVAILABLE not in html
221
222
223 # ── DOC_GS_13: the workflow pushes to the remote for the hub that serves the page (GS-20) ──
224 # Identity commands follow the request host, so a reader registered on musehub.ai must not be told to
225 # push to `staging` (staging.musehub.ai, where they hold no identity).
226
227
228 def test_init_remote_table_matches_muse_init() -> None:
229 from muse.cli.commands.init import _DEFAULT_REMOTES
230
231 assert ui_docs._INIT_REMOTES == {urlsplit(url).netloc: (name, url) for name, url in _DEFAULT_REMOTES.items()}
232
233
234 @pytest.mark.parametrize(("base_url", "remote"), [
235 ("https://musehub.ai", "production"),
236 ("https://staging.musehub.ai", "staging"),
237 ("https://localhost:1337", "local"),
238 ("https://hub.example.org", "hub"), # self-hosted: init wires no remote for it
239 ])
240 def test_push_examples_use_the_remote_for_the_serving_hub(base_url: str, remote: str) -> None:
241 runnable = [c.line for c in extract_commands(_render_on(base_url)) if c.in_pre]
242 pushes = [c for c in runnable if c.startswith("muse push ")]
243 assert pushes and {c.split()[2] for c in pushes} == {remote}, pushes
244 if remote == "hub":
245 assert f"muse remote add hub {base_url}/your-handle/my-project" in runnable
246 assert not [c for c in runnable if c.startswith("muse remote set-url ")]
247 else:
248 assert f"muse remote set-url {remote} {base_url}/your-handle/my-project" in runnable
249
250
251 # ── DOC_GS_04: the installer description matches the script /install.sh serves ──
252
253
254 def test_installer_options_are_the_ones_the_served_script_reads(html: str) -> None:
255 from musehub.api.routes.musehub import install
256
257 script = install.generate_install_script("https://musehub.ai", "0.0.0-docs-contract")
258 header = "\n".join(line for line in script.splitlines() if line.startswith("#"))
259 supported = set(re.findall(r"\bMUSE_[A-Z_]+", header))
260 documented = set(re.findall(r"<code>(MUSE_[A-Z_]+)", _section(html, "install")))
261 assert documented <= supported, documented - supported
262 # MUSE_EXTRAS=swift cannot install on any supported Python yet (2026-11-07 QA), so it stays undocumented.
263 assert supported - documented == {"MUSE_EXTRAS"}
264 for default in ("$HOME/.local/share/muse/venv", "$HOME/.local/bin"):
265 assert default in script and default.replace("$HOME", "~") in _section(html, "install")
266
267
268 def test_installer_outline_does_not_claim_pypi_is_never_used(html: str) -> None:
269 # The sdist comes from the hub; its dependencies and build backend come from PyPI unless MUSE_WHEELHOUSE is set.
270 text = _section(html, "prerequisites") + _section(html, "install")
271 assert "No PyPI involved" not in text and "not from PyPI" in text and "MUSE_WHEELHOUSE" in text
272
273
274 # ── DOC_GS_14: claims corrected by the 2026-11-07 end-to-end QA run (rc20) ──
275
276
277 @pytest.mark.parametrize("stale", [
278 "curl -I ", # HEAD /healthz is 405 on both hosts
279 "/releases</code>", # not a version list (profile catch-all)
280 "see the local dev setup guide", # no such page
281 "recreates the venv in place", # the venv is reused; muse is reinstalled into it
282 "always prints a reminder", # printed only after a successful install
283 "uploading objects", # rc20 push prints no progress lines
284 "Identity ID: ident_", # register prints sha256:…
285 "required before pushing", # push signs with the identity for the remote's host
286 "authenticated via a signed Ed25519 challenge-response", # only registration; requests carry MSign
287 "exactly as in Git", # diff3-style markers with Muse labels + muse resolve
288 "will be a drop-in swap", # forward-looking guarantee with no roadmap reference
289 "cannot be changed after init", # init --force --domain switches it
290 "produced by the agent holding the matching private key", # agent commits carry the human's key
291 ])
292 def test_corrected_claims_stay_corrected(html: str, stale: str) -> None:
293 assert stale not in " ".join(html.split())
294
295
296 def test_whoami_explains_the_repository_hub_not_a_default_lookup(html: str) -> None:
297 sec = _section(html, "identity")
298 assert "Outside a repository it lists every identity you have stored" in sec
299 assert "until you run <code>muse hub connect</code>" in sec
300
301
302 # ── DOC_GS_15: the first-push figure (V1) is drawn from verified behaviour ──
303 # Each row was checked against muse 0.2.1rc20 and the 2026-11-07 staging run (#244): register, repo create
304 # and push are the only steps that reach the hub; every step that signs reads the keychain.
305
306
307 def test_first_push_steps_name_real_muse_symbols() -> None:
308 import importlib
309
310 for step in ui_docs._FIRST_PUSH:
311 module, symbol = step.implemented_by.split(":")
312 assert callable(getattr(importlib.import_module(module), symbol)), step.implemented_by
313
314
315 def test_first_push_steps_are_documented_commands(html: str) -> None:
316 import argparse
317
318 from tests.docs_contract import cli_check as cc
319
320 parser: argparse.ArgumentParser = cc.capture_parser()
321 for step in ui_docs._FIRST_PUSH:
322 assert cc.check_line(parser, cc.DocCommand(step.command, in_pre=False)).kind == "ok", step.command
323 assert f'id="{step.anchor}"' in html, step.anchor
324
325
326 def test_first_push_figure_matches_the_verified_calls() -> None:
327 steps = {s.command: s for s in ui_docs._FIRST_PUSH}
328 assert [c for c, s in steps.items() if s.network] == ["muse auth register", "muse hub repo create", "muse push"]
329 assert all(s.keychain for s in steps.values() if s.signs), "signing always reads the keychain"
330 assert not steps["muse hub connect"].network and not steps["muse init"].keychain
331
332
333 def test_first_push_figure_renders_as_an_accessible_figure(html: str) -> None:
334 fig = html.split('id="first-push-figure"', 1)[1].split("</figure>", 1)[0]
335 assert 'aria-labelledby="first-push-figure-title"' in html and 'id="first-push-figure-title"' in fig
336 assert fig.count('class="seqfig__step"') == len(ui_docs._FIRST_PUSH)
337 assert fig.count("seqfig__cell--hub seqfig__cell--idle") == len(ui_docs._FIRST_PUSH) - 3
338 assert "<script" not in fig, "complete without JavaScript"
339
340
341 # ── DOC_GS_16: the Git bridge section matches the GS-BR-01…13 run (isolated sandbox, rc20, 2026-11-07) ──
342
343
344 def test_bridge_examples_do_not_teach_a_signing_flag_that_does_nothing(commands: list[str]) -> None:
345 imports = [c for c in commands if c.startswith("muse bridge git-import ")]
346 assert imports and not [c for c in imports if "--sign" in c.split()], imports # muse#139
347
348
349 @pytest.mark.parametrize("stale", [
350 "bidirectional Git interoperability layer", # import replays history; export writes one snapshot per run
351 "keep both in sync indefinitely", # re-importing the mirror duplicates native work
352 "Author names, emails, and timestamps are preserved verbatim", # names/emails/committer are not stored
353 "walks a Git repo's DAG and writes equivalent", # merges flattened, intermediate snapshots differ (muse#140)
354 "Add it to <code>.museignore</code>", # .muse/ is never snapshotted; a plain line breaks the TOML file
355 "Imported commits are signed only when you pass", # --sign is a no-op (muse#139)
356 ])
357 def test_bridge_claims_corrected_by_the_run_stay_corrected(html: str, stale: str) -> None:
358 assert stale not in " ".join(html.split())
359
360
361 def test_bridge_status_example_passes_the_git_dir_that_drift_needs(html: str) -> None:
362 sec = _section(html, "migrate")
363 assert "muse bridge git-status --git-dir /path/to/git-repo --json" in sec
364 assert '"drift"' in sec
365
366
367 @pytest.mark.parametrize(("issue", "topic"), [(77, "full history"), (139, "--sign"), (140, "single parent"), (141, "untracked")])
368 def test_bridge_known_limitations_link_their_tickets(html: str, issue: int, topic: str) -> None:
369 sec = _section(html, "migrate")
370 assert f'href="https://staging.musehub.ai/gabriel/muse/issues/{issue}"' in sec and topic in sec
File History 7 commits
sha256:c2ee54efa85fcbdeea4ffc84a2dd1b8fcd4623463b22e35765df3013a26834aa merge: #276 public URLs + muse#181 docs onto dev (#313 present) Opus 5.5 minor ⚠ 1 day ago
sha256:c777acd5605d4a83bbf9d2903bff0b0d419325b7bc49317700e4037b56594e8e fix(web): absolute public URLs come from the canonical publ… Opus 5.5 minor ⚠ 1 day ago
sha256:71e7849472a1545f06b42a349e127eb355fd30953cb39a182a5ae0c5e2da7fb0 docs(getting-started): QA contract v2 audit — no-release pa… Opus 5.5 minor ⚠ 9 days ago
sha256:f7413c1abec6d6a8e5bdabcd4cc7ad5fcd059ce6a6f50f566e2b0118a0a8b578 tests: make tests/docs_contract/ database-free by directory… Opus 5.5 10 days ago
sha256:0ce2a1580273a4939c58cc0f18ad5ae19a56c6c352b56cfb3ce87fd9283b0f07 Merge task/244-gs17-19 (#244 GS-17/18/19 Getting Started fi… Opus 5.5 patch 10 days ago
sha256:ec087989520c874c2febaba20b9bcedffe03ff8fcd78e9c0eb92b36d64f2e2a7 docs(getting-started): whoami targets the hub; account for … Opus 5.5 patch 10 days ago
sha256:5745f056592123707326093fbe1c8fb6430304821fa6edf5263606624fc45883 docs(getting-started): teach a signed, verifiable first-run… Opus 5.5 minor ⚠ 10 days ago