jason.woltje
940ae3cc41
--next now prefers a fast npm @next install (CLI + gateway from the Gitea registry) and falls back to source build at next if the dist-tag is unavailable. Registry lane gated to non-dev, non-explicit-ref next installs; CLI/gateway prerelease versions must share a pipeline suffix. Adds tools/install-next-lane.test.sh (wired into CI). PR-event CI 1635 fully green + review-of-record APPROVE (functional install test, head 2fd7cfc3).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
41 lines
2.2 KiB
Markdown
41 lines
2.2 KiB
Markdown
# 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`.
|