claude/.claude/tasks/contracts/2026-09-13-gstack-playwright-lib-2220.md

CONTRACT — gstack-playwright-lib

• date: 2026-09-13 | flow: feat | branch: feature/gstack-playwright-lib
• status: active

REQUEST (verbatim — IMMUTABLE)

Message 1:

l'installation de chromium, c'est une version fix ou en latest ? Il faudrait mettre en lateste, et d'ailleurs son update est pris en compt dans l'update ? quelq version a besoin gstack ? Ca serait pas plus simple d'installer perplexity a la place ?

Message 2 (after the assistant proposed fix A + fix B):

les deux

Message 3 (answer to the scope question on fix B, after the "654 Mo orphelins" premise was proven wrong):

Check read-only dans doctor.sh

CLARIFICATIONS

Q: "mettre en latest" — pin Chromium to latest? A: Not actionable as asked. Playwright downloads the browser revision its own version pins (1.61.1 → chromium 1228); the CDP client is coupled to that build. "Latest" = track the latest Playwright, which is what BDR-029's bump already does. No change to the pinning mechanism is in scope.

Q: Volet B — purge the orphan Playwright revisions? A: Superseded by evidence. ~/.cache/ms-playwright/.links/ registers THREE playwright installs (gstack 1.61.1 → rev 1228; gsd-pi nvm 1.61.0 → 1228; gsd-pi ~/.local 1.63.0 → 1243). Every directory on disk is referenced; zero bytes reclaimable. Playwright already GCs correctly on every install (_deleteStaleBrowsers, unions across all registered installs). User chose: read-only report in doctor.sh, NO deletion anywhere.

ACCEPTANCE CRITERIA

1. lib/gstack-playwright.sh exists, is source-safe (sourcing prints nothing and runs no side effect), and its verb dispatcher works when executed. CHECK: out=$( . lib/gstack-playwright.sh; echo READY ); [ "$out" = READY ] && bash lib/gstack-playwright.sh 2>&1 | grep -q 'usage:' && echo LIB_OK EXPECT: LIB_OK EVIDENCE: MET exit=0 marker-found :: LIB_OK

2. The bump logic lives ONLY in the lib: install-plugins.sh no longer defines gstack_bump_playwright_if_unsupported, sources the lib instead, and still calls it BEFORE gstack ./setup (BDR-029 behavior unchanged: OS-gated, idempotent, non-fatal). CHECK: grep -q '^gstack_bump_playwright_if_unsupported() {' install-plugins.sh && exit 1; grep -q 'lib/gstack-playwright.sh' install-plugins.sh || exit 1; c=$(grep -n 'gstack_bump_playwright_if_unsupported' install-plugins.sh | grep -v '::space:*#' | tail -1 | cut -d: -f1); s=$(grep -n '&& ./setup)' install-plugins.sh | head -1 | cut -d: -f1); [ -n "$c" ] && [ -n "$s" ] && [ "$c" -lt "$s" ] && echo EXTRACT_OK EXPECT: EXTRACT_OK EVIDENCE: MET exit=0 marker-found :: EXTRACT_OK

3. update-all.sh delegates the gstack submodule update to the lib (gstack_submodule_update_with_bump) instead of calling git submodule update --remote bare, so the bump is re-applied after every successful update. CHECK: grep -q 'gstack_submodule_update_with_bump' update-all.sh && grep -q 'lib/gstack-playwright.sh' update-all.sh && ! grep -qE '^:space:*if git submodule update --remote skills-external/gstack' update-all.sh && echo WIRED_OK EXPECT: WIRED_OK EVIDENCE: MET exit=0 marker-found :: WIRED_OK

4. [gated 2026-09-15] gstack_submodule_update_with_bump NEVER modifies the submodule working tree. On a successful git submodule update --remote it re-applies the bump; on failure it returns non-zero, touches nothing, and emits git's own message plus a hint naming the local Playwright bump when package.json/bun.lock are the dirty files. The conflict-RECOVERY branch of the earlier revision (discard, retry, backup, restore) is withdrawn: it could leave the bump discarded and un-reapplied, regressing a working browser into BLK-008, which the pre-existing behavior never did. CHECK: sed 's/#.//' lib/gstack-playwright.sh | grep -qE 'git [^|;](checkout|reset|clean|stash)' && exit 1; bash lib/tests/gstack-playwright.test.sh 2>&1 | grep -q 'update-conflict' && bash lib/tests/gstack-playwright.test.sh 2>&1 | grep -qE '^PASS=[0-9]+ FAIL=0$' && echo NONDESTRUCTIVE_OK EXPECT: NONDESTRUCTIVE_OK EVIDENCE: MET exit=0 marker-found :: NONDESTRUCTIVE_OK

5. doctor.sh prints a Playwright-browsers section: total cache size, one line per browser directory naming the registered playwright install(s) that reference it, plus counts of unreferenced directories and broken links. CHECK: bash doctor.sh 2>/dev/null | grep -qi 'playwright browsers' && bash lib/gstack-playwright.sh browsers-report | grep -qE 'chromium-[0-9]+' && bash lib/gstack-playwright.sh browsers-report | grep -qi 'unreferenced' && echo REPORT_OK EXPECT: REPORT_OK EVIDENCE: MET exit=0 marker-found :: REPORT_OK

6. The report is provably read-only: no destructive verb anywhere in the lib, and the cache directory listing is identical before and after a report run. CHECK: sed 's/#.*//' lib/gstack-playwright.sh | grep -qwE '(rm|rmdir|unlink|truncate|mv)' && exit 1; b=$(ls -la ~/.cache/ms-playwright ~/.cache/ms-playwright/.links 2>/dev/null | cksum); bash lib/gstack-playwright.sh browsers-report >/dev/null 2>&1; a=$(ls -la ~/.cache/ms-playwright ~/.cache/ms-playwright/.links 2>/dev/null | cksum); [ "$b" = "$a" ] && echo READONLY_OK EXPECT: READONLY_OK EVIDENCE: MET exit=0 marker-found :: READONLY_OK

7. lib/tests/gstack-playwright.test.sh exists, passes, and covers at least: bump skipped when the OS tag is already supported; bump fired when it is not; submodule-update conflict recovery; browsers-report on a fixture cache holding a referenced revision, an unreferenced one and a broken link. CHECK: bash lib/tests/gstack-playwright.test.sh | tail -1 | grep -qE '^PASS=[0-9]+ FAIL=0$' && echo TESTS_OK EXPECT: TESTS_OK EVIDENCE: MET exit=0 marker-found :: TESTS_OK

8. shellcheck clean on every touched shell file. CHECK: shellcheck lib/gstack-playwright.sh lib/tests/gstack-playwright.test.sh install-plugins.sh update-all.sh doctor.sh >/dev/null 2>&1 && echo SHELLCHECK_OK EXPECT: SHELLCHECK_OK EVIDENCE: MET exit=0 marker-found :: SHELLCHECK_OK

9. [gated 2026-09-15] (judgement) No new dependency; the report degrades silently when ~/.cache/ms-playwright is absent, when its .links directory is absent, when PLAYWRIGHT_BROWSERS_PATH is 0 or not a directory, or when no playwright install is registered — doctor must stay green on a machine that never installed a browser. The lib's printers are named _gspw_ok/_gspw_warn/_gspw_info and it defines NO bare ok/warn/info/pass/fail: doctor.sh sources the lib before every check, so bare names would override its own printers and silently disconnect its ERRORS/WARNS counters.

FILE SCOPE

• lib/gstack-playwright.sh (new)
• lib/tests/gstack-playwright.test.sh (new)
• install-plugins.sh (remove inline fn, source + call lib)
• update-all.sh (call bump + conflict recovery)
• doctor.sh (new read-only report section)

Out of scope: the gstack submodule itself, the pinning mechanism, any deletion of cached browsers, the GSTACK_CHROMIUM_NO_SANDBOX layer (LRN-040 layer 2, unchanged).