Release Fabric Consumers

Release qvac-fabric consumers to npm

Publish the qvac-fabric consumers to npm in one coordinated pass. This is the final phase of a fabric rollout — the step after rollout-phase-b's bundled version-bump PR (vcpkg version>= + package.json + CHANGELOG.md for the full roster) has merged to main. It applies the single-package release workflow to every consumer in the release set at once.

It reuses the same mechanics as /release (cut a release-* branch → dispatch on-merge-nx.yml with the package as an input → the on-merge workflow builds prebuilds, publishes to npm with the latest tag, and creates a git tag), but for the whole release set, and it is aware of the per-consumer quirks and the mandatory human approval gate.

The release set is the full consumer roster (see the table below) minus anything named in --exclude. Every step below operates on the release set, not the roster.

Usage

/release-fabric-consumers [base-branch] [--exclude <pkg>[,<pkg>...]]

/release-fabric-consumers
/release-fabric-consumers main --exclude model-fit
/release-fabric-consumers main --exclude model-fit,vla-ggml

• [base-branch] — optional; the branch the version bumps landed on. Defaults to main.
• --exclude <pkg>[,<pkg>...] — optional; comma-separated packages/ directory names (the first column of the consumer table) to hold back from this pass. Everything else in the roster is released.

Validate --exclude before touching anything. A value that does not match a packages/ dir name in the table is a hard error, not a silent no-op — a typo like --exclude modelfit would otherwise quietly release the very package the user meant to hold back. Report the unmatched name and stop before creating any release branch. Excluding every consumer is likewise an error, not an empty success.

Prerequisites

• The consumer bump is merged to <base-branch> — either rollout-phase-b's own bundled PR (e.g. qvac#3334) or, in --on-top-of-pr mode, the feature PR the bumps rode in on (e.g. qvac#3725). The target versions live on origin/<base-branch>.
• For each consumer in the release set, origin/<base-branch>'s package.json version is higher than the current npm latest (i.e. npm is one bump behind). If not, the version bump PR hasn't merged yet — stop.
• Each release-set consumer's CHANGELOG.md has a ## [<version>] - <date> section (bracketed heading — the release-merge-guard requires this exact format).

These are checked only for the release set — a package held back by --exclude is never inspected, which is the point of excluding it.

Watch for a never-published consumer

The "npm is one bump behind" check can pass for the wrong reason. A package whose npm latest reads 0.0.0 with no release tag has never actually been published — 0.0.0 is a name placeholder, so any real version compares as "higher" and the precondition passes while the package is in a first-publish state this skill otherwise assumes away.

npm view @qvac/<pkg> dist-tags.latest
git -C <repo> ls-remote --tags origin "<tag-prefix>-v*"

Both signals together (0.0.0 and no tag) mean a first release. 0.0.0 here is a sentinel, not a version that drifts — it is npm's placeholder for a name reserved but never published, so it stays literal. Which package is in that state does drift, so run the two commands above across the roster rather than trusting a name written here; model-fit was the instance when this was written and has since published. When a package is in that state, its first release needs two things settled before dispatch:

1. a dated ## [<version>] - <date> entry — a CHANGELOG.md holding only an ## [Unreleased] block is what the release extractor will not accept as a version section;
2. a decision on whether the version already on origin/main publishes as-is, or is superseded by the rollout bump. Do not bump past an unpublished version without asking — that silently burns a version number.

Until both are settled, hold it back with --exclude <pkg> rather than dispatching it and dealing with a failed release-merge-guard. That is the supported way to release the rest of the roster on schedule while a first-publish package waits.

The consumers

This table is the full roster. The release set is this list minus --exclude.

The git-tag column is not uniform. Use the package's entry when checking a release.

classification-ggml is not in this list. It dropped the qvac-fabric vcpkg dependency and now consumes the published npm package @qvac/fabric, so it is not part of a fabric rollout — see Release fabric first below for the one follow-up it needs.

Working repo & the golden guardrail

• Run all git/gh operations in the code working repo (e.g. ~/repo/qvac) — NOT a stale/read-only worktree. Verify the repo is on the right remote (tetherto/qvac).
• Base every release branch on origin/<base-branch>, never on local HEAD (local main is often behind).
• GOLDEN RULE — a release branch modifies ZERO files. It is an exact copy of origin/<base-branch>. Create it without a checkout, then assert an empty diff before pushing. Never edit anything under .github/workflows/**. If the diff is non-empty, STOP and report — do not push.

Workflow

Do the whole release set in parallel unless told otherwise (version-only bumps were already build-validated on the fabric sync PR; a canary-first order is a fine alternative).

Release fabric first

@qvac/fabric is the shared runtime addon the others build against, and it is also a caret dependency of @qvac/classification-ggml. Publish it ahead of the rest so downstream installs resolve against the new build rather than the previous one.

Then check the caret. Read both values rather than assuming either — they move every release, so any version written here would be wrong by the time you read it:

git -C <repo> grep -h "@qvac/fabric" origin/main -- packages/classification-ggml/package.json
git -C <repo> grep -h '"version"' origin/main -- packages/fabric/package.json

On a 0.x version a caret locks the minor: ^0.<m>.<p> absorbs later 0.<m>.x automatically but will not cross to 0.<m+1>.0. So if this release moves @qvac/fabric's minor past the one classification-ggml's caret pins, classification-ggml needs a manual dependency bump — track it as a follow-up after the release, not as part of the rollout PR. This has happened before and is expected to recur; packages/classification-ggml/CHANGELOG.md records each crossing.

If fabric is in --exclude, this ordering step does not apply to that pass and the classification-ggml caret follow-up does not arise — release the rest of the set in parallel and say in the report that the ordering constraint was moot.

Step 1 — Sync and read target versions

git -C <repo> fetch origin <base-branch>

Resolve the release set first (roster minus --exclude, with --exclude validated per Usage), then for each consumer in the release set read the version off origin/<base-branch> (git -C <repo> show origin/<base-branch>:packages/<pkg>/package.json) and confirm npm view @qvac/<pkg> version is lower. Also confirm no target release-* branch already exists on the remote (git -C <repo> ls-remote --heads origin "release-<pkg>-<ver>").

State the resolved release set and the excluded packages before proceeding, so the user can catch a wrong set before any branch is pushed.

Step 2 — Create + assert + push each release branch

git -C <repo> branch release-<pkg>-<ver> origin/<base-branch>    # no checkout
git -C <repo> diff --stat origin/<base-branch>..release-<pkg>-<ver>   # MUST be empty
git -C <repo> push origin release-<pkg>-<ver>                    # non-force, non-main

Step 3 — Dispatch the on-merge workflow

gh workflow run on-merge-nx.yml --repo tetherto/qvac \
  --ref release-<pkg>-<ver> -f package=<pkg>

package is a required choice input and takes the package directory name, the same string the branch carries.

Pushing a fresh release-* branch usually does not auto-trigger (path filter sees no new commits), so the explicit dispatch is the trigger — but check gh run list --branch release-<pkg>-<ver> and, if a push-triggered run already exists, do NOT double-dispatch.