stack/docs/design/prerelease-next-dist-tag-pipeline.md

Planned Design — npm @next prerelease lane

Status: PLANNED / not yet built

Current state

tools/install.sh --next provides a prerelease integration lane by building the Mosaic CLI and gateway from source at the permanent next branch. This is correct for validating integration-branch source, but it is slower than the stable npm lane because it downloads the archive, installs workspace dependencies, builds packages, packs local tarballs, and installs those tarballs globally.

Medium-term target

Publish every accepted next integration build to the npm registry under the @next dist-tag, for example:

@mosaicstack/mosaic@0.0.49-next.1
@mosaicstack/mosaic@0.0.49-next.2

Then move tools/install.sh --next from source-build behavior to a fast npm install:

npm install -g @mosaicstack/mosaic@next

The framework archive should still resolve from the matching next source/ref until framework packaging has a registry-backed equivalent.

Pipeline shape

1. Trigger on successful CI for next.
2. Compute the next prerelease version from the upcoming stable version plus a monotonic prerelease counter (0.0.49-next.N).
3. Build and pack publishable packages in CI.
4. Publish to the Mosaic Gitea npm registry with dist-tag next.
5. Keep latest untouched; only main/release promotion can update latest.
6. Teach the installer to prefer @next for the CLI/gateway prerelease lane once the registry tag is reliable.

Guardrails

• @next is mutable prerelease convenience, not a deployment pin.
• Stable installs continue to use @latest.
• Contributor validation remains available through --dev --ref <branch>.
• Pipeline must be reproducible and trace every prerelease package back to the source commit on next.