chore: align release readiness commands

Author: mars

Makefile

@@ -33,7 +33,7 @@ help:
 	@printf "  make test-api       [runtime mutating] Run the API pytest suite\n"
 	@printf "  make test-browser   [runtime mutating] Run the Playwright smoke test\n"
 	@printf "  make verify-persistence  [runtime mutating] Verify saved settings survive restart and rebuild\n"
-	@printf "  make doctor         [tracked-source read-only] Probe the supported upstream checkout and local tooling\n"
+	@printf "  make doctor         [tracked-source read-only] Probe supported upstream checkouts and local tooling\n"
 
 .PHONY: help validate validate-lite validate-config secret-scan local-state-report drift-check patch-audit audit release-evidence sync-upstream build run dashboard e2e verify-submit-replay verify-release patch-check patch-check-upstream test-ci test-api test-browser verify-persistence doctor
 

docs/command-contract.md

@@ -54,7 +54,7 @@ right gate without guessing.
 | `make test-api` | runtime mutating | Runs API validation against a local virtual runtime. |
 | `make test-browser` | runtime mutating | Runs browser smoke validation against a local virtual runtime. |
 | `make verify-persistence` | runtime mutating | Verifies settings persistence across restart/rebuild. |
-| `make doctor` | tracked-source read-only | Probes configured source and local tool availability. |
+| `make doctor` | tracked-source read-only | Probes canonical configured sources and local tool availability. |
 
 ## Release Rule
 

scripts/drift-check.py

@@ -50,6 +50,40 @@ def git_output(args: list[str], cwd: Path = ROOT_DIR) -> tuple[int, str, str]:
     return result.returncode, result.stdout.strip(), result.stderr.strip()
 
 
+def resolve_source_ref(source_dir: Path, ref: str) -> tuple[str, str]:
+    if not (source_dir / ".git").is_dir():
+        return "", "local source cache missing"
+    rc, resolved, error = git_output(["git", "-C", str(source_dir), "rev-parse", f"{ref}^{{commit}}"])
+    if rc != 0:
+        return "", error or f"git rev-parse failed for {ref}"
+    return resolved, ""
+
+
+def sync_source_cache(source_name: str, ref: str, *, reason: str) -> dict[str, Any]:
+    env = {
+        **os.environ,
+        "SOURCE": source_name,
+        "SOURCE_NAME": source_name,
+        "UPSTREAM_REF": ref,
+    }
+    result = subprocess.run(
+        [str(ROOT_DIR / "scripts" / "sync-upstream.sh")],
+        cwd=ROOT_DIR,
+        env=env,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    return {
+        "status": "passed" if result.returncode == 0 else "failed",
+        "classification": "ok" if result.returncode == 0 else "external source sync failed",
+        "reason": reason,
+        "returncode": result.returncode,
+        "stdout": result.stdout.strip(),
+        "stderr": result.stderr.strip(),
+    }
+
+
 def run_patch_apply(source_name: str, source_dir: Path, ref: str) -> dict[str, Any]:
     if not (source_dir / ".git").is_dir():
         return {
@@ -117,9 +151,25 @@ def drift_check(include_upstream_head: bool = False) -> dict[str, Any]:
     entry = sources["sources"][source_name]
     ref = entry["ref"]
     source_dir = ROOT_DIR / ".sources" / source_name
-    _rc, resolved, ref_error = git_output(["git", "-C", str(source_dir), "rev-parse", f"{ref}^{{commit}}"]) if source_dir.exists() else (1, "", "local source cache missing")
+    resolved, ref_error = resolve_source_ref(source_dir, ref)
+    source_sync = {
+        "status": "skipped",
+        "classification": "ok",
+        "reason": "configured source ref already resolved locally",
+    }
+    if not resolved:
+        source_sync = sync_source_cache(source_name, ref, reason=ref_error)
+        if source_sync["status"] == "passed":
+            resolved, ref_error = resolve_source_ref(source_dir, ref)
     series_digest = patch_series_hash(source_name)
-    configured_pin = run_patch_apply(source_name, source_dir, ref)
+    if source_sync["status"] == "failed":
+        configured_pin = {
+            "status": "skipped",
+            "classification": "external check skipped",
+            "reason": "source sync failed before patch apply",
+        }
+    else:
+        configured_pin = run_patch_apply(source_name, source_dir, ref)
     upstream_head = {"status": "skipped", "classification": "external check skipped", "reason": "run with --upstream-head"}
     if include_upstream_head:
         upstream_ref = "origin/master"
@@ -148,13 +198,16 @@ def drift_check(include_upstream_head: bool = False) -> dict[str, Any]:
     release_blockers = []
     if configured_pin["classification"] == "release-blocking drift":
         release_blockers.append("configured pin patch stack does not apply")
+    if source_sync["status"] == "failed":
+        release_blockers.append("configured source sync failed")
     if not resolved:
         release_blockers.append(f"configured source ref is not resolved locally: {ref_error}")
     return {
         "status": "passed" if not release_blockers else "failed",
         "source": source_name,
         "configuredRef": ref,
         "resolvedConfiguredRef": resolved,
+        "sourceSync": source_sync,
         "patchSeriesSha256": series_digest,
         "patchCount": len(series(source_name)),
         "configuredPinPatchCheck": configured_pin,

scripts/virtualaxe.py

@@ -1059,7 +1059,7 @@ def ensure_matching_build(
 
 
 def command_doctor(args: argparse.Namespace) -> int:
-    sources = load_sources()
+    sources = source_registry().as_legacy_payload(include_aliases=False)
     payload: dict[str, Any] = {"sources": {}, "profiles": sorted(p.stem for p in PROFILES_DIR.glob("*.json"))}
     for name, entry in sources["sources"].items():
         try:

tests/api/test_settings_update.py

@@ -10,6 +10,12 @@
 SOURCE_NAME = os.environ.get("SOURCE_NAME", "bitaxe")
 
 
+def require_explicit_settings_api():
+    if not os.environ.get("BASE_URL"):
+        pytest.skip("set BASE_URL to run mutating API settings checks")
+    require_virtualaxe_api(BASE_URL)
+
+
 def require_bitaxe_settings_api():
     if SOURCE_NAME != "bitaxe":
         pytest.skip(f"{SOURCE_NAME} exposes a source-specific settings API")
@@ -37,7 +43,7 @@ def setting_matches(actual: object, expected: object) -> bool:
 
 
 def test_system_settings_patch_roundtrip():
-    require_virtualaxe_api(BASE_URL, env_vars=("BASE_URL",))
+    require_explicit_settings_api()
     require_bitaxe_settings_api()
 
     system_info = get_json(f"{BASE_URL}/api/system/info", timeout=10)
@@ -66,7 +72,7 @@ def test_system_settings_patch_roundtrip():
 
 
 def test_system_settings_patch_accepts_large_form_payload():
-    require_virtualaxe_api(BASE_URL, env_vars=("BASE_URL",))
+    require_explicit_settings_api()
     require_bitaxe_settings_api()
 
     system_info = get_json(f"{BASE_URL}/api/system/info", timeout=10)
@@ -96,7 +102,7 @@ def test_system_settings_patch_accepts_large_form_payload():
 
 
 def test_pool_settings_patch_keeps_system_info_responsive():
-    require_virtualaxe_api(BASE_URL, env_vars=("BASE_URL",))
+    require_explicit_settings_api()
     require_bitaxe_settings_api()
 
     system_info = get_json(f"{BASE_URL}/api/system/info", timeout=10)

tests/test_repo_readiness_tools.py

@@ -56,6 +56,91 @@ def test_local_state_report_is_read_only_and_classifies_known_paths():
     assert by_path["out"]["canAffectBuildRunReview"] is True
 
 
+def test_drift_check_prepares_missing_source_cache(monkeypatch):
+    module = load_script("drift-check.py")
+    resolved_ref = "c" * 40
+    resolve_calls = iter(
+        [
+            ("", "local source cache missing"),
+            (resolved_ref, ""),
+        ]
+    )
+    sync_calls = []
+
+    def fake_resolve(_source_dir, ref):
+        assert ref == "ce44b2bbfef60ef8830ab17b321cc295e0c0edc8"
+        return next(resolve_calls)
+
+    def fake_sync(source_name, ref, *, reason):
+        sync_calls.append((source_name, ref, reason))
+        return {
+            "status": "passed",
+            "classification": "ok",
+            "reason": reason,
+            "returncode": 0,
+            "stdout": ".sources/bitaxe",
+            "stderr": "",
+        }
+
+    def fake_patch_apply(source_name, _source_dir, ref):
+        return {
+            "status": "passed",
+            "classification": "ok",
+            "source": source_name,
+            "requestedRef": ref,
+        }
+
+    monkeypatch.setattr(module, "resolve_source_ref", fake_resolve)
+    monkeypatch.setattr(module, "sync_source_cache", fake_sync)
+    monkeypatch.setattr(module, "run_patch_apply", fake_patch_apply)
+    monkeypatch.setattr(module, "manifest_status", lambda _source, _digest: {"status": "missing"})
+
+    payload = module.drift_check()
+
+    assert payload["status"] == "passed"
+    assert payload["sourceSync"]["status"] == "passed"
+    assert payload["resolvedConfiguredRef"] == resolved_ref
+    assert sync_calls == [
+        ("bitaxe", "ce44b2bbfef60ef8830ab17b321cc295e0c0edc8", "local source cache missing")
+    ]
+
+
+def test_drift_check_reports_source_sync_failure(monkeypatch):
+    module = load_script("drift-check.py")
+
+    monkeypatch.setattr(
+        module,
+        "resolve_source_ref",
+        lambda _source_dir, _ref: ("", "local source cache missing"),
+    )
+    monkeypatch.setattr(
+        module,
+        "sync_source_cache",
+        lambda _source, _ref, *, reason: {
+            "status": "failed",
+            "classification": "external source sync failed",
+            "reason": reason,
+            "returncode": 128,
+            "stdout": "",
+            "stderr": "network unavailable",
+        },
+    )
+
+    def fail_patch_apply(*_args, **_kwargs):
+        raise AssertionError("patch apply should not run when source sync fails")
+
+    monkeypatch.setattr(module, "run_patch_apply", fail_patch_apply)
+    monkeypatch.setattr(module, "manifest_status", lambda _source, _digest: {"status": "missing"})
+
+    payload = module.drift_check()
+
+    assert payload["status"] == "failed"
+    assert payload["sourceSync"]["status"] == "failed"
+    assert payload["configuredPinPatchCheck"]["status"] == "skipped"
+    assert "configured source sync failed" in payload["releaseBlockers"]
+    assert any("configured source ref is not resolved locally" in blocker for blocker in payload["releaseBlockers"])
+
+
 def test_validate_full_gate_prepares_local_state_and_avoids_live_pools():
     module = load_script("validate.py")
 

tests/test_vaxe.py

@@ -1191,6 +1191,43 @@ def test_virtualaxe_patch_check_metadata_supports_nerdnos_submit_replay_series()
     assert metadata[5]["patch"] == "0006-nerdnos-brand-virtualaxe-header.patch"
 
 
+def test_virtualaxe_doctor_reports_canonical_sources_only(monkeypatch: pytest.MonkeyPatch, capsys):
+    module = load_virtualaxe_module()
+
+    class Registry:
+        def as_legacy_payload(self, *, include_aliases: bool = True):
+            assert include_aliases is False
+            return {
+                "sources": {
+                    "bitaxe": {"ref": "bitaxe-pin"},
+                    "nerdnos": {"ref": "nerdnos-pin"},
+                }
+            }
+
+    monkeypatch.setattr(module, "source_registry", lambda: Registry())
+    monkeypatch.setattr(module, "ensure_git_source", lambda name, entry, **_kwargs: (Path(f"/tmp/{name}"), entry))
+    monkeypatch.setattr(
+        module,
+        "source_probe",
+        lambda _source_dir: {
+            "capabilities": {"supportsGammaProfiles": False},
+            "missingRequiredCapabilities": [],
+        },
+    )
+    monkeypatch.setattr(
+        module,
+        "run",
+        lambda command, **_kwargs: subprocess.CompletedProcess(command, 0, "tool version\n", ""),
+    )
+
+    args = type("Args", (), {"json": True})()
+
+    assert module.command_doctor(args) == 0
+
+    payload = json.loads(capsys.readouterr().out)
+    assert set(payload["sources"]) == {"bitaxe", "nerdnos"}
+
+
 def test_virtualaxe_patch_check_applies_resolved_upstream_commit(monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys):
     module = load_virtualaxe_module()
     source_dir = tmp_path / "source"