fix: lefthook-hooks, template-lint, per-command --help

[christian-at-sevenlab]

Drie tooling-gaten uit een retrospective op recente sessies. Elk punt eerst gereproduceerd op origin/main (een verse nuxt4-ai/nuxt4-fullstack scaffold); geen ervan was al opgelost. Eén commit per punt.

1. Lefthook-hooks worden nooit geïnstalleerd (shared:ci 1.1.2)

Oorzaak: lefthook's eigen postinstall draait tijdens de scaffold-install, als het project nog geen .git heeft (battlestack scaffoldt met --no-gitInit). Daarna draait hij niet meer.

• package.json krijgt "prepare": "lefthook install || exit 0". || exit 0 is nodig: de Docker build-stage heeft geen .git en geen git, en zonder de fallback faalt pnpm install daar (lokaal geverifieerd: image bouwt). exit 0 werkt ook in cmd.exe.
• Een bestaande eigen prepare blijft staan, met een note bij pull.
• Bij pull draait update() het prepare-script één keer zelf: de install van pull neemt pnpm's fast path ("Already up to date"), die prepare overslaat. Zo krijgen odu-zzs, HERA en ECHO de hook bij hun eerstvolgende battlestack pull.

2. Templates voldoen niet aan de eigen ESLint-config

Oorzaak: de scaffold eindigt met eslint --fix, waardoor de lint-stap in CI groen bleef, terwijl 49 templatebestanden de stijl van het project braken (operator-linebreak, member-delimiter-style, max-attributes-per-line, …). pull merget de ruwe template in de geformatteerde kopie van de gebruiker, en elk stijlverschil werd zo een conflict (odu-zzs had die regels daarom uitgezet).

• Templates zijn ge-eslint --fixt met de config van een gegenereerd project. Alleen opmaak, geen placeholders geraakt.
• CI (verify-scaffold): nieuwe stap die de ruwe packages/preset-nuxt4/templates in het gescaffolde project kopieert en daar lint met de config van het project. vue/multi-word-component-names staat in die stap uit, omdat pages/layouts daar buiten de paden vallen die ze uitzonderen.
• Patch-bumps voor de 20 features waarvan templates veranderd zijn. build-info en landing-shell met de hand gebumpt: bump:check ziet hun templates niet (zie open punten).

3. battlestack <cmd> --help toont de usage van dat commando

• battlestack own --help (en pull, disown, doctor, remove, …) print nu usage, label en de extra aanroepen van dat commando.
• battlestack --help binnen een project print nu de projecthulp, die de core commands lijst. Daarvoor kwam alleen de lijst met feature-commando's.

Teruggedraaid: Playwright MCP --browser chromium

Stond eerst in deze PR (11729b2), teruggedraaid in a109c38. Een CLI-flag wint van PLAYWRIGHT_MCP_BROWSER, dus wie Chrome heeft kon niet meer terug, en .mcp.json wordt bij elke pull herschreven. Wie geen systeem-Chrome heeft (linux-arm64) zet export PLAYWRIGHT_MCP_BROWSER=chromium in de eigen shell. shared:ai-tool-config blijft op 1.1.9.

Hoe het bij bestaande projecten landt

battlestack pull ziet de nieuwe versies en draait update(). package.json#scripts.prepare wordt bijgewerkt, de hook wordt geïnstalleerd en de geformatteerde templates komen overeen met wat de gebruiker al had.

Conflicten met open PR's

• fix(ai-tool-config): ship Claude Code rules in a format Claude Code loads #72 (ai-tool-config): bumpt ook chat en mastra, dus versieconflicten. Wie als tweede merget, rebumpt.
• feat(docs): keep the generated AGENTS.md an index #73 (AGENTS.md): geen overlap in bestanden. Deze PR raakt collectDocs niet, dus geen nuxt4:docs-bump.
• perf(db): index every foreign key in the scaffold's schema #71, fix(auth): refuse revoked sessions on every request #65, fix(health): keep the database error out of the public health responses #70: versieregel-conflicten op auth*/storage/audit-log/vitest/health. fix(health): keep the database error out of the public health responses #70 en fix(auth): refuse revoked sessions on every request #65 raken ook health.get.ts en vitest/.../auth.test.ts, die hier geformatteerd zijn.

Checks

pnpm tsc ✓, pnpm test ✓ (behalve de bekende WSL-only fout in browser.test.ts, "uses xdg-open on plain Linux"), pnpm bump:check origin/main ✓. Lokaal ook: verse nuxt4-fullstack scaffold → pnpm run lint ✓, ruwe template-lint ✓, git init && pnpm install --force installeert pre-commit ✓, docker build ✓.

Open punten

• bump:check mist features die emitTemplate(ctx, this.id, …) gebruiken (build-info, landing-shell). Een kleine aanpassing aan de regex; die zit niet in deze PR.
• Bij een verse scaffold staat de hook er pas na de eerste echte pnpm install die volgt op git init. De docs zeggen nog "Install hooks once: lefthook install". Dat aanpassen zou een nuxt4:docs-bump vragen, en die laat ik aan feat(docs): keep the generated AGENTS.md an index #73.

[christian-at-sevenlab]

Vier tooling-fixes. Lefthook, template-formatting en --help breken niets. Het Playwright-punt heb ik teruggedraaid in a109c38.

Teruggedraaid: Playwright MCP --browser chromium

• @playwright/mcp leest de browser ook uit PLAYWRIGHT_MCP_BROWSER, maar een CLI-flag wint van die env var. Met de hardcoded flag kan iemand mét Chrome (Mac, Windows) dus niet meer terug naar Chrome. .mcp.json met de hand aanpassen helpt ook niet, want pull herschrijft het elke keer.
• Wie de bundled Chromium nodig heeft (linux-arm64, waar geen Google Chrome bestaat), zet in de eigen shell export PLAYWRIGHT_MCP_BROWSER=chromium. Claude Code geeft die door aan de MCP-server.
• shared:ai-tool-config staat daarmee weer op 1.1.9, gelijk aan main. Dat scheelt ook een versieconflict met #72.

Gecontroleerd

• Lefthook prepare:
  • || exit 0 vangt Docker (geen .git) en installs zonder dev deps op.
  • Een eigen prepare blijft staan, met een note.
  • SITE, ECHO en HERA hebben geen prepare, alleen postinstall: nuxt prepare.
  • writeJson schrijft met 4 spaties, net als de projecten, dus package.json wordt niet heropgemaakt.
• Template-formatting:
  • Op whitespace na verschillen alleen drie auth-2fa-bestanden: twee keer Pragma → 'Pragma', en in totp.ts een string-concatenatie met de operator op een andere plek en andere quotes. De betekenis is gelijk.
  • pull heeft een converged-staat: een geformatteerde kopie die gelijk is aan de nieuwe template wordt geaccepteerd, niet als merge klaargezet.
• --help: een gereserveerd commando toont zijn eigen usage. Binnen een project toont --help de projecthulp in plaats van projectCommand te draaien.
• Alle CI-checks waren groen. Na de revert: mcp-json.test.ts slaagt en pnpm bump:check origin/main is OK.

Merge-risico

Deur: tweerichtingsdeur. Alleen tooling, templates en scripts. Een revert plus pull zet het terug.
Blast radius: platform. Elk project krijgt prepare en de geformatteerde templates bij de volgende pull. Er verandert niets aan het runtime-gedrag.