stack/docs/scratchpads/installer-next-lane-20260624.md

Scratchpad — installer --next lane

Objective

Add a prerelease installer lane for the permanent next integration branch.

Scope

• tools/install.sh
• README/install documentation
• Follow-up design note for future npm @next prerelease publishing

Plan

1. Add --next and MOSAIC_NEXT=1 as source-build shorthand for next.
2. Preserve explicit ref precedence: MOSAIC_REF and --ref win over --next.
3. Update installer source display/help text.
4. Document three lanes:
   • stable npm @latest
   • prerelease --next
   • contributor --dev --ref X
5. Run shell and repo gates locally, then hold before push/PR until runner serialization greenlight.

Verification

• bash -n tools/install.sh — pass.
• docker run --rm -v "$PWD:/mnt" -w /mnt koalaman/shellcheck:stable tools/install.sh — pass.
• bash tools/install.sh --check --framework --next — source display shows ref: next, --next prerelease lane.
• bash tools/install.sh --check --cli --next --ref feature-x — source display shows explicit ref wins.
• MOSAIC_NEXT=1 MOSAIC_REF=feature-env bash tools/install.sh --check --cli — source display shows explicit env ref wins.
• pnpm install --frozen-lockfile --prefer-offline --store-dir /home/jarvis/.local/share/pnpm/store — pass (local override for repo .npmrc CI store path).
• pnpm typecheck — pass (41 successful tasks).
• pnpm lint — pass (23 successful tasks).
• pnpm format:check — pass.
• bash tools/e2e-install-test.sh — attempted; current baseline fails during gateway health after stable registry install because Valkey is unavailable in the clean container. The tools/install.sh --yes --no-auto-launch stage itself completed before the downstream gateway verification failure.