mosaicstack/stack
16
0
Fork 1
Code Issues 330 Pull Requests 12 Actions Packages Projects Releases 15 Wiki Activity

tooling: switch release channel stable ⇄ next via mosaic CLI / install.sh (consumer-side channel selector) #843

New Issue
Open
opened 2026-07-19 19:50:03 +00:00 by jason.woltje · 0 comments
jason.woltje commented 2026-07-19 19:50:03 +00:00
Owner
Copy Link
Copy Source

Summary

Add first-class release-channel switching to the Mosaic tooling so an end
user can move between the stable (latest) and next (pre-release)
channels — and back — with a single supported command, instead of hand-rolling
npm install -g @mosaicstack/mosaic@next plus a raw framework/install.sh
reseed.

This is the tooling half of the channel story. The docs half is tracked
in #805 (README should document both install paths). #805 also lists
installer: add --channel next|stable as a prerequisite "separate lane" — this
issue is that lane, tracked as a first-class deliverable.

Current state (verified on a workstation, 2026-07-19)

The publish-side split that #805 described as "recommended, not yet done" has
since materialized. The Gitea npm registry now exposes both dist-tags:

$ npm dist-tag ls @mosaicstack/mosaic
latest: 0.0.48
next:   0.0.49-next.1666

So the channel distinction is real at the registry level today. What's
missing is entirely consumer-side:

  1. mosaic update only ever follows latest. With 0.0.49-next.1666
    published on next, mosaic update --check still reports 0.0.48 as
    "✔ up to date". There is no --channel / --next / --tag option on the
    command.
  2. tools/install.sh has no channel selector. (grep -niE 'channel|@next|--tag' tools/install.sh → no matches.) --dev --ref <branch> is a build-from-source
    developer path, not an end-user channel toggle.
  3. Reaching next therefore requires manual, undocumented steps: 
    npm install -g '@mosaicstack/mosaic@next'
bash "$(npm root -g)/@mosaicstack/mosaic/framework/install.sh"   # reseed; CLI's own reseed won't fire
    The CLI's built-in reseed (runFrameworkReseed) only triggers from
    mosaic update's own flow, which never sees next — so a manual @next
    install leaves framework files un-reseeded unless the user knows to run the
    bundled install.sh directly.
  4. No supported way back. Returning to stable is an equally manual
    npm install -g @mosaicstack/mosaic@latest + reseed. Nothing records which
    channel the workstation is on.

Proposed tooling behavior

  • mosaic update --channel next|stable (persist the choice), or a dedicated
    mosaic channel <next|stable> / mosaic channel status.
  • Persist the selected channel (e.g. in ~/.config/mosaic config or the
    install manifest) so mosaic update thereafter tracks the chosen dist-tag
    and --check compares against the right tag.
  • Whichever command changes the channel must also run the framework reseed
    (same data-safe path as a normal update) so CLI + ~/.config/mosaic never
    drift across a channel switch.
  • tools/install.sh --channel next|stable (default stable) for first
    install, matching the CLI verb.
  • Update .install-manifest.json on channel switch (a raw framework/install.sh
    reseed currently leaves cliVersion/frameworkVersion stale).

Prerelease-slack note (surfaced while testing the manual path)

On 0.0.49-next.1666, mosaic doctor emits 7 "Missing Mosaic skill" warnings
(mosaic-board, mosaic-forge, mosaic-prdy, mosaic-macp, mosaic-standards,
mosaic-prd, mosaic-setup-cicd) plus an "AGENTS.md missing CRITICAL HARD GATES
override block" warning. The RECOMMENDED_SKILLS set in dist/constants.js
references those skills, but the package ships none of them (0 matches in the
package tree). Not blocking, but the next doctor's expectations are ahead of
what the next build bundles — worth reconciling so next users don't chase
phantom warnings. (Possibly its own issue; noted here for context.)

Acceptance criteria

  • A supported command switches channel stable ⇄ next and persists it.
  • mosaic update / --check tracks the selected channel's dist-tag.
  • Channel switch runs the data-safe framework reseed automatically.
  • tools/install.sh accepts --channel next|stable (default stable).
  • .install-manifest.json reflects the active channel + versions after a switch.
  • Round-trip verified: stable → next → stable, mosaic doctor clean modulo
    known prerelease slack.

Related

  • #805 — docs(readme): document both stable and "next" install paths (docs half;
    its "current state" section predates the registry now carrying both dist-tags).

Filed from a workstation upgrade to next on 2026-07-19; requested by Jason.

## Summary Add first-class **release-channel switching** to the Mosaic tooling so an end user can move between the **stable** (`latest`) and **next** (pre-release) channels — and back — with a single supported command, instead of hand-rolling `npm install -g @mosaicstack/mosaic@next` plus a raw `framework/install.sh` reseed. This is the **tooling half** of the channel story. The **docs half** is tracked in #805 (README should document both install paths). #805 also lists `installer: add --channel next|stable` as a prerequisite "separate lane" — this issue is that lane, tracked as a first-class deliverable. ## Current state (verified on a workstation, 2026-07-19) The publish-side split that #805 described as *"recommended, not yet done"* has since materialized. The Gitea npm registry now exposes **both** dist-tags: ``` $ npm dist-tag ls @mosaicstack/mosaic latest: 0.0.48 next: 0.0.49-next.1666 ``` So the channel distinction is **real at the registry level today**. What's missing is entirely **consumer-side**: 1. **`mosaic update` only ever follows `latest`.** With `0.0.49-next.1666` published on `next`, `mosaic update --check` still reports `0.0.48` as "✔ up to date". There is no `--channel` / `--next` / `--tag` option on the command. 2. **`tools/install.sh` has no channel selector.** (`grep -niE 'channel|@next|--tag' tools/install.sh` → no matches.) `--dev --ref <branch>` is a build-from-source developer path, not an end-user channel toggle. 3. **Reaching `next` therefore requires manual, undocumented steps:** ``` npm install -g '@mosaicstack/mosaic@next' bash "$(npm root -g)/@mosaicstack/mosaic/framework/install.sh" # reseed; CLI's own reseed won't fire ``` The CLI's built-in reseed (`runFrameworkReseed`) only triggers from `mosaic update`'s own flow, which never sees `next` — so a manual `@next` install leaves framework files un-reseeded unless the user knows to run the bundled `install.sh` directly. 4. **No supported way back.** Returning to stable is an equally manual `npm install -g @mosaicstack/mosaic@latest` + reseed. Nothing records which channel the workstation is on. ## Proposed tooling behavior - `mosaic update --channel next|stable` (persist the choice), or a dedicated `mosaic channel <next|stable>` / `mosaic channel status`. - Persist the selected channel (e.g. in `~/.config/mosaic` config or the install manifest) so `mosaic update` thereafter tracks the chosen dist-tag and `--check` compares against the right tag. - Whichever command changes the channel must **also run the framework reseed** (same data-safe path as a normal update) so CLI + `~/.config/mosaic` never drift across a channel switch. - `tools/install.sh --channel next|stable` (default `stable`) for first install, matching the CLI verb. - Update `.install-manifest.json` on channel switch (a raw `framework/install.sh` reseed currently leaves `cliVersion`/`frameworkVersion` stale). ## Prerelease-slack note (surfaced while testing the manual path) On `0.0.49-next.1666`, `mosaic doctor` emits 7 "Missing Mosaic skill" warnings (`mosaic-board`, `mosaic-forge`, `mosaic-prdy`, `mosaic-macp`, `mosaic-standards`, `mosaic-prd`, `mosaic-setup-cicd`) plus an "AGENTS.md missing CRITICAL HARD GATES override block" warning. The `RECOMMENDED_SKILLS` set in `dist/constants.js` references those skills, but the package ships **none** of them (0 matches in the package tree). Not blocking, but the `next` doctor's expectations are ahead of what the `next` build bundles — worth reconciling so `next` users don't chase phantom warnings. (Possibly its own issue; noted here for context.) ## Acceptance criteria - [ ] A supported command switches channel `stable` ⇄ `next` and persists it. - [ ] `mosaic update` / `--check` tracks the selected channel's dist-tag. - [ ] Channel switch runs the data-safe framework reseed automatically. - [ ] `tools/install.sh` accepts `--channel next|stable` (default `stable`). - [ ] `.install-manifest.json` reflects the active channel + versions after a switch. - [ ] Round-trip verified: stable → next → stable, `mosaic doctor` clean modulo known prerelease slack. ## Related - #805 — docs(readme): document both stable and "next" install paths (docs half; its "current state" section predates the registry now carrying both dist-tags). _Filed from a workstation upgrade to `next` on 2026-07-19; requested by Jason._
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
code-be-01 (Mosaic fleet seat code-be-01) code-be-02 (Mosaic fleet seat code-be-02) code-infra-01 (Mosaic fleet seat code-infra-01) fargo fred gate-merge-01 (Mosaic fleet seat gate-merge-01) happy jason.woltje (Jason Woltje) merge-gate ops-01 (Mosaic fleet seat ops-01) ops-02 (Mosaic fleet seat ops-02) ops-03 (Mosaic fleet seat ops-03) ops-ci-01 (Mosaic fleet seat ops-ci-01) ops-deploy-01 (Mosaic fleet seat ops-deploy-01) pepper rev-code-01 rev-code-02 rev-security-01 rev-security-02 rev-security-03 (Mosaic fleet seat rev-security-03) sanity scooby (Scooby) scrappy shaggy tiny velma veronica (Mosaic fleet seat veronica) vision woodpecker
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#843