stack/docs/scratchpads/installer-next-fast-npm-20260625.md

Installer --next fast npm lane — 2026-06-25

Scope

Flip tools/install.sh --next from source-build-first to fast npm @next first, with source fallback.

Registry reality check

Gitea npm registry: https://git.mosaicstack.dev/api/packages/mosaicstack/npm/

Verified before implementation:

• @mosaicstack/mosaic@next resolves to 0.0.49-next.1633.
• @mosaicstack/gateway@next resolves to 0.0.7-next.1633.
• @mosaicstack/gateway dist-tags include latest: 0.0.6 and next: 0.0.7-next.1633.
• apps/gateway/package.json is non-private and has Gitea npm publishConfig.

Conclusion: the installer can fast-install both CLI and gateway npm packages for --next. The gateway Docker gateway:sha-<short> remains the deployment/harness artifact; the npm gateway package is valid for the installer global package path.

Behavior

• --next with no explicit ref:
  1. framework archive from next;
  2. resolve @mosaicstack/gateway@next and @mosaicstack/mosaic@next;
  3. require both resolved versions to share the same next.<pipeline> suffix;
  4. install the exact resolved package versions;
  5. set MOSAIC_GATEWAY_SKIP_NPM_INSTALL=1 so wizard does not overwrite the prerelease gateway;
  6. if either package is missing/unreachable/mismatched/fails, fall back to existing source build at next.
• --dev remains pure source build.
• explicit --ref / MOSAIC_REF still wins over --next and uses the source path for that exact ref.

Install detail

The installer writes the scoped npmrc mapping (@mosaicstack:registry=...) and then runs npm install without overriding npm's default registry. Passing --registry=<gitea> to npm install forces public transitive dependencies (for example @anthropic-ai/sdk) to resolve from Gitea and breaks the fast path; the scoped npmrc mapping is the correct split-registry behavior.

Verification notes

• Added tools/install-next-lane.test.sh with a fake npm/source harness for exact-version fast install, registry failure source fallback, explicit-ref precedence, and mismatched suffix warning.
• Wired the installer harness into pnpm test via pnpm run test:installer.
• Real temp-prefix fast install succeeded with @mosaicstack/gateway@0.0.7-next.1633 and @mosaicstack/mosaic@0.0.49-next.1633.