fix(lint): provision the mermaid browser in install-lint, not in the parallel lint run

make lint runs install-lint once and then dispatches its fifteen targets
in parallel. scripts/lint/mermaid.sh provisioned chrome-headless-shell
inside that parallel phase with `npx puppeteer browsers install
--install-deps`, whose `apt-get satisfy` carries no lock timeout. In a
fresh stack container another target held the apt lock, the shared
libraries stayed missing, the script only warned, and all 289 Markdown
files then failed on libnspr4.so (#795).

utils/install/lint/mermaid_cli.py now provisions the browser right after
mmdc, inside the serial install-lint step, as root with --install-deps
and as a user without it, because puppeteer refuses to install libraries
without root. A failed install deletes the chrome-headless-shell cache
folder and retries once under a 900 second timeout per attempt; a cut-off
download otherwise leaves a folder without its executable, and puppeteer
refuses every later install of that build. The install-lint stamp counts
as fresh only while the browser executable exists, so a recreated
container provisions it again.

mermaid.sh no longer calls apt-get or npx. It renders one minimal diagram
first and, when that fails, exits with mmdc's output instead of reporting
every Markdown file.

Verified: tests/unit/python/scripts/lint/test_mermaid.py stubs mmdc,
npx and apt-get. With a browser that cannot load libnspr4.so the script
exits 1 with that line, before any Markdown file renders, and mmdc is the
only tool it calls. Against main's mermaid.sh the same test fails: it
calls apt-get and npx and reports the files one by one. The installer and
stamp cases pass, shellcheck is clean.

Not verified: a full make lint in a recreated stack container. The race
reproduced in one of two runs in the issue.

feature/store-i18n changed the provisioning in mermaid.sh with 2f5f52bd1a
and dc67bce5f0 (timeout, deleting a cut-off browser). Both behaviours
moved into mermaid_cli.py here, so its merge takes this version of
mermaid.sh.

Closes #795

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

tests/unit/python/utils/install/lint/test_main.py

@@ -34,12 +34,30 @@ class TestStampLogic(unittest.TestCase):
             with (
                 mock.patch.object(cli, "PROJECT_ROOT", root),
                 mock.patch.object(cli.shutil, "which", return_value="/usr/bin/x"),
+                mock.patch.object(
+                    cli.mermaid_cli, "browser_installed", return_value=True
+                ),
                 mock.patch.object(cli, "_install_all") as inst,
             ):
                 rc = cli.main([])
             self.assertEqual(rc, 0)
             inst.assert_not_called()
 
+    def test_missing_mermaid_browser_invalidates_stamp(self) -> None:
+        with TemporaryDirectory() as tmp:
+            root = _make_repo_root(tmp, stamp_age_offset=60.0)
+            with (
+                mock.patch.object(cli, "PROJECT_ROOT", root),
+                mock.patch.object(cli.shutil, "which", return_value="/usr/bin/x"),
+                mock.patch.object(
+                    cli.mermaid_cli, "browser_installed", return_value=False
+                ),
+                mock.patch.object(cli, "_install_all") as inst,
+            ):
+                rc = cli.main([])
+            self.assertEqual(rc, 0)
+            inst.assert_called_once()
+
     def test_missing_tool_invalidates_stamp(self) -> None:
         with TemporaryDirectory() as tmp:
             root = _make_repo_root(tmp, stamp_age_offset=60.0)

tests/unit/python/utils/install/lint/test_mermaid_cli.py

@@ -0,0 +1,111 @@
+"""Unit tests for :mod:`utils.install.lint.mermaid_cli`."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import unittest
+import unittest.mock as mock
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from utils.install.lint import mermaid_cli
+
+
+def _done(returncode: int) -> subprocess.CompletedProcess[str]:
+    return subprocess.CompletedProcess([], returncode, stdout="out\n", stderr="err\n")
+
+
+class TestBrowserProvisioning(unittest.TestCase):
+    def provision(self, *, euid: int, results: list[int]) -> tuple[list, list[str]]:
+        """Run ``ensure()`` with mmdc present and a stubbed puppeteer.
+
+        Args:
+            euid: effective uid the run pretends to have.
+            results: exit codes the successive puppeteer calls return.
+
+        Returns:
+            The recorded subprocess calls and the warnings emitted.
+        """
+        warnings: list[str] = []
+        with (
+            TemporaryDirectory() as cache,
+            mock.patch.dict(os.environ, {"PUPPETEER_CACHE_DIR": cache}),
+            mock.patch.object(mermaid_cli, "which", return_value=True),
+            mock.patch.object(mermaid_cli.os, "geteuid", return_value=euid),
+            mock.patch.object(mermaid_cli, "warn", side_effect=warnings.append),
+            mock.patch.object(
+                mermaid_cli.subprocess,
+                "run",
+                side_effect=[_done(code) for code in results],
+            ) as run,
+        ):
+            mermaid_cli.ensure()
+        return run.call_args_list, warnings
+
+    def test_root_installs_the_browser_with_its_libraries(self) -> None:
+        calls, warnings = self.provision(euid=0, results=[0])
+        self.assertEqual(len(calls), 1)
+        self.assertEqual(calls[0].args[0][-2:], ["chrome-headless-shell", "--install-deps"])
+        self.assertEqual(warnings, [])
+
+    def test_a_user_installs_the_browser_without_libraries(self) -> None:
+        calls, _ = self.provision(euid=1000, results=[0])
+        self.assertNotIn("--install-deps", calls[0].args[0])
+
+    def test_the_browser_install_downloads_despite_the_mmdc_skip_flag(self) -> None:
+        with mock.patch.dict(os.environ, {"PUPPETEER_SKIP_DOWNLOAD": "1"}):
+            calls, _ = self.provision(euid=0, results=[0])
+        self.assertNotIn("PUPPETEER_SKIP_DOWNLOAD", calls[0].kwargs["env"])
+
+    def test_a_failed_install_clears_the_browser_cache_and_retries_once(self) -> None:
+        with TemporaryDirectory() as cache:
+            folder = Path(cache) / "chrome-headless-shell" / "linux-1"
+            folder.mkdir(parents=True)
+            seen: list[bool] = []
+
+            def run(*_args, **_kwargs):
+                seen.append(folder.exists())
+                return _done(1 if len(seen) == 1 else 0)
+
+            with (
+                mock.patch.dict(os.environ, {"PUPPETEER_CACHE_DIR": cache}),
+                mock.patch.object(mermaid_cli, "which", return_value=True),
+                mock.patch.object(mermaid_cli.subprocess, "run", side_effect=run),
+            ):
+                mermaid_cli.ensure()
+        self.assertEqual(seen, [True, False])
+
+    def test_a_second_failure_warns_with_puppeteers_output(self) -> None:
+        calls, warnings = self.provision(euid=0, results=[1, 1])
+        self.assertEqual(len(calls), 2)
+        self.assertEqual(len(warnings), 1)
+        self.assertIn("out\nerr\n", warnings[0])
+
+    def test_a_timeout_warns_instead_of_raising(self) -> None:
+        with (
+            mock.patch.object(mermaid_cli, "which", return_value=True),
+            mock.patch.object(
+                mermaid_cli.subprocess,
+                "run",
+                side_effect=subprocess.TimeoutExpired("npx", 900),
+            ),
+            mock.patch.object(mermaid_cli, "warn") as warn,
+        ):
+            mermaid_cli.ensure()
+        warn.assert_called_once()
+
+
+class TestBrowserInstalled(unittest.TestCase):
+    def test_the_executable_in_the_puppeteer_cache_counts(self) -> None:
+        with TemporaryDirectory() as cache:
+            build = Path(cache) / "chrome-headless-shell" / "linux-1" / "linux64"
+            build.mkdir(parents=True)
+            with mock.patch.dict(os.environ, {"PUPPETEER_CACHE_DIR": cache}):
+                self.assertFalse(mermaid_cli.browser_installed())
+                (build / "chrome-headless-shell").write_text("", encoding="utf-8")
+                self.assertTrue(mermaid_cli.browser_installed())
+
+
+if __name__ == "__main__":
+    unittest.main()