# npm `@next` prerelease lane

Status: **IMPLEMENTED**

## Current behavior

`tools/install.sh --next` provides the prerelease integration lane for the permanent `next` branch.

The lane is fast-by-default:

1. Install framework files from the `next` source archive.
2. Resolve the Gitea npm registry `next` dist-tag for the globally installed packages:

   ```bash
   npm view @mosaicstack/gateway@next version
   npm view @mosaicstack/mosaic@next version
   ```

3. Require both resolved versions to share the same `next.<pipeline>` suffix, then install the exact resolved versions.
4. If either `@next` package is missing, unreachable, mismatched, or fails to install, fall back to the source-build path at `next`.

`--next` never hard-fails solely because the prerelease npm dist-tag is unavailable.

## Published packages

The `next` publish pipeline publishes non-private `@mosaicstack/*` packages to the Mosaic Gitea npm registry:

```text
https://git.mosaicstack.dev/api/packages/mosaicstack/npm/
```

Observed `next` dist-tags after enabling the pipeline:

```text
@mosaicstack/mosaic@next  -> 0.0.49-next.1633
@mosaicstack/gateway@next -> 0.0.7-next.1633
```

The gateway also publishes a Docker image as `gateway:sha-<short>` on `next` merges. The installer fast path uses the npm gateway package when available; the Docker image is for deployed gateway/runtime harness flows.

## Explicit source lanes

Source builds remain available and are still the authority for explicit ref validation:

- `--dev` always builds from source.
- `--ref <ref>` / `MOSAIC_REF=<ref>` wins over `--next` and uses the source path for that exact ref.

## Pipeline shape

1. Trigger on `next` merges.
2. Compute the next prerelease version from the upcoming stable version plus the Woodpecker pipeline number (`<target-stable>-next.<CI_PIPELINE_NUMBER>`).
3. Build and publish non-private 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. Publish gateway Docker images from `next` as `gateway:sha-<short>` only.

## 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 output traces every prerelease package back to the source commit on `next`.
- The installer falls back to source rather than hard-failing on prerelease registry issues.