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