Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

ci(release): publish canaries at most hourly from main's tip, plus an on-demand canary dispatch (#9659)

Cindy Zhangcbda0753d90c
diff --git a/.github/scripts/release-publish-workflow.test.mjs b/.github/scripts/release-publish-workflow.test.mjs
index 2c7d908d59..dff6ae158b 100644
--- a/.github/scripts/release-publish-workflow.test.mjs
+++ b/.github/scripts/release-publish-workflow.test.mjs
@@ -42,6 +42,7 @@ function writeExecutable(root, name, contents) {
*/
function withPublisher(root) {
for (const file of [
+ 'canary-pending.mjs',
'publish-order.mjs',
'publish-package.mjs',
'registry.mjs',
@@ -163,7 +164,7 @@ async function runCanaryPublish({
...publisherEnv,
FAIL_ONCE: failOnce,
FAIL_PACKAGE: failingPackage,
- GITHUB_SHA: 'abcdef1234567890',
+ CANARY_VERSION: '0.7.4-canary.abcdef1',
PATH: `${path.join(root, 'bin')}:${process.env.PATH}`,
PUBLISH_LOG: publishLog,
RUNNER_TEMP: runnerTemp,
@@ -250,6 +251,94 @@ function runStablePublish({
}
}
+const STABLE_INPUTS = [
+ 'release-branch',
+ 'release-version',
+ 'release-tag',
+ 'expected-head',
+ 'plan-digest',
+];
+
+/*
+ * Runs the canary's "canaries all published" step against a local registry
+ * stand-in. `answers` maps a request path to its status (`000` drops the
+ * connection); any other path answers 404. The scratch root holds a public
+ * Core and a private canary-only Native. Returns the step's `publish=` output.
+ */
+async function runFreshCheck(answers) {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-canary-fresh-'));
+ const server = spawn(
+ process.execPath,
+ [
+ '--input-type=module',
+ '-e',
+ `import http from 'node:http';
+const answers = JSON.parse(process.argv[1]);
+const server = http.createServer((request, response) => {
+ const status = answers[decodeURIComponent(request.url)] ?? '404';
+ if (status === '000') return request.socket.destroy();
+ response.writeHead(Number(status)).end('{}');
+});
+server.listen(0, '127.0.0.1', () => console.log(server.address().port));`,
+ JSON.stringify(answers),
+ ],
+ {stdio: ['ignore', 'pipe', 'inherit']},
+ );
+ try {
+ const port = await new Promise((resolve, reject) => {
+ server.once('error', reject);
+ server.stdout.once('data', data => resolve(String(data).trim()));
+ });
+ writeJson(root, 'packages/core/package.json', {
+ name: '@astryxdesign/core',
+ version: '0.7.8',
+ });
+ writeJson(root, 'packages/native/package.json', {
+ name: '@astryxdesign/native',
+ version: '0.7.8',
+ private: true,
+ astryx: {canaryOnly: true},
+ });
+ fs.mkdirSync(path.join(root, 'packages/themes'), {recursive: true});
+ for (const file of [
+ 'canary-pending.mjs',
+ 'publish-package.mjs',
+ 'registry.mjs',
+ ]) {
+ const target = path.join(root, 'scripts/npm', file);
+ fs.mkdirSync(path.dirname(target), {recursive: true});
+ fs.copyFileSync(path.join(ROOT, 'scripts/npm', file), target);
+ }
+ const githubOutput = path.join(root, 'github-output');
+ fs.writeFileSync(githubOutput, '');
+ const result = spawnSync(
+ 'bash',
+ ['-c', step(canary, 'Skip a tip whose canaries are all published').run],
+ {
+ cwd: root,
+ encoding: 'utf8',
+ env: {
+ ...process.env,
+ ASTRYX_PUBLISH_REGISTRY: `http://127.0.0.1:${port}`,
+ GITHUB_OUTPUT: githubOutput,
+ GITHUB_SHA: 'abcdef1234567890',
+ },
+ },
+ );
+ expect(result.status).toBe(0);
+ const output = fs.readFileSync(githubOutput, 'utf8');
+ expect(output).toContain('version=0.7.8-canary.abcdef1');
+ return output.match(/^publish=\w+$/mu)[0];
+ } finally {
+ server.kill();
+ fs.rmSync(root, {recursive: true, force: true});
+ }
+}
+
+const CORE_CANARY = '/@astryxdesign/core/0.7.8-canary.abcdef1';
+const NATIVE_CANARY = '/@astryxdesign/native/0.7.8-canary.abcdef1';
+const NATIVE_LATEST = '/@astryxdesign/native/latest';
+
/** A registry verifier stand-in that exits with `code`. */
function writeVerifierStub(root, code) {
const file = path.join(root, 'scripts/npm/verify-published.mjs');
@@ -284,21 +373,153 @@ function runFollowUp(job, verifyExit) {
}
describe('stable and canary publication authority', () => {
- it('keeps stable explicit and canary limited to main pushes', () => {
- expect(stable.if).toBe("github.event_name == 'workflow_dispatch'");
- expect(canary.if).toBe("github.event_name == 'push'");
- expect(workflow.on.push.branches).toEqual(['main']);
- for (const name of [
- 'release-branch',
- 'release-version',
- 'release-tag',
- 'expected-head',
- 'plan-digest',
- ]) {
- expect(workflow.on.workflow_dispatch.inputs[name].required).toBe(true);
+ it('keeps stable explicit and runs canaries hourly or on demand, never on each push', () => {
+ expect(stable.if).toBe(
+ "github.event_name == 'workflow_dispatch' && inputs.channel != 'canary'",
+ );
+ expect(canary.if).toBe(
+ "github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.channel == 'canary')",
+ );
+ expect(workflow.on.push).toBeUndefined();
+ expect(workflow.on.schedule).toEqual([{cron: '17 * * * *'}]);
+ expect(workflow.on.workflow_dispatch.inputs.channel).toMatchObject({
+ type: 'choice',
+ options: ['stable', 'canary'],
+ default: 'stable',
+ });
+ // Optional only so a canary dispatch can omit them: the stable job's
+ // first step requires every one.
+ const guard = stable.steps[0];
+ expect(guard.name).toBe('Require every stable release input');
+ for (const name of STABLE_INPUTS) {
+ expect(workflow.on.workflow_dispatch.inputs[name].required).toBe(false);
+ expect(JSON.stringify(guard.env)).toContain(`inputs['${name}']`);
}
});
+ it('refuses a stable dispatch that leaves out any release input', () => {
+ const complete = {
+ RELEASE_BRANCH: 'release/v0.7.7',
+ RELEASE_VERSION: '0.7.7',
+ RELEASE_TAG: 'v0.7.7',
+ EXPECTED_HEAD: 'a'.repeat(40),
+ PLAN_DIGEST: 'b'.repeat(64),
+ };
+ const run = env =>
+ spawnSync(
+ 'bash',
+ ['-c', step(stable, 'Require every stable release input').run],
+ {
+ encoding: 'utf8',
+ env: {...process.env, ...env},
+ },
+ );
+
+ expect(run(complete).status).toBe(0);
+ const missing = run({...complete, RELEASE_TAG: '', PLAN_DIGEST: ''});
+ expect(missing.status).toBe(1);
+ expect(missing.stdout).toContain('missing: release-tag plan-digest');
+ });
+
+ it('publishes canaries only from main', () => {
+ const run = (ref, dryRun = 'false') =>
+ spawnSync(
+ 'bash',
+ ['-c', step(canary, 'Require main and no dry run').run],
+ {
+ encoding: 'utf8',
+ env: {...process.env, GITHUB_REF: ref, DRY_RUN: dryRun},
+ },
+ );
+ expect(
+ canary.steps
+ .map(candidate => candidate.name)
+ .indexOf('Require main and no dry run'),
+ ).toBe(1);
+ expect(run('refs/heads/main').status).toBe(0);
+ const branch = run('refs/heads/feature');
+ expect(branch.status).toBe(1);
+ expect(branch.stdout).toContain('Canaries publish only from main');
+ });
+
+ it('lets one package list drive the skip check, the stamp and the publish loop', () => {
+ const publish = step(canary, 'Publish canary versions').run;
+ expect(publish).toContain(
+ 'CANARY_DIRS=$(node scripts/npm/canary-pending.mjs --list-dirs)',
+ );
+ expect(publish.match(/for pkg_dir in \$CANARY_DIRS; do/gu)).toHaveLength(2);
+ expect(publish).not.toMatch(/for pkg(_dir)? in packages\//u);
+
+ // The list holds exactly the packages the publish loop's own rule admits.
+ const listed = spawnSync(
+ process.execPath,
+ ['scripts/npm/canary-pending.mjs', '--list-dirs'],
+ {cwd: ROOT, encoding: 'utf8'},
+ )
+ .stdout.trim()
+ .split('\n');
+ const admitted = ['packages', 'packages/themes'].flatMap(parent =>
+ fs
+ .readdirSync(path.join(ROOT, parent), {withFileTypes: true})
+ .filter(entry => entry.isDirectory())
+ .map(entry => `${parent}/${entry.name}`)
+ .filter(dir => fs.existsSync(path.join(ROOT, dir, 'package.json')))
+ .filter(dir => {
+ const p = JSON.parse(
+ fs.readFileSync(path.join(ROOT, dir, 'package.json'), 'utf8'),
+ );
+ return (
+ (!p.private || p.astryx?.canaryOnly) &&
+ p.name?.startsWith('@astryxdesign/')
+ );
+ }),
+ );
+ expect([...listed].sort()).toEqual([...admitted].sort());
+ });
+
+ it('refuses a canary dispatch marked as a dry run, which would still publish', () => {
+ const result = spawnSync(
+ 'bash',
+ ['-c', step(canary, 'Require main and no dry run').run],
+ {
+ encoding: 'utf8',
+ env: {...process.env, GITHUB_REF: 'refs/heads/main', DRY_RUN: 'true'},
+ },
+ );
+ expect(result.status).toBe(1);
+ expect(result.stdout).toContain(
+ 'A canary dispatch publishes; it has no dry run.',
+ );
+ expect(step(canary, 'Require main and no dry run').env.DRY_RUN).toBe(
+ '${{ inputs.dry-run }}',
+ );
+ });
+
+ it("publishes nothing only when every package already has this tip's canary", async () => {
+ expect(
+ await runFreshCheck({[CORE_CANARY]: '200', [NATIVE_CANARY]: '200'}),
+ ).toBe('publish=false');
+ // Core landed but a later package did not: publish again.
+ expect(
+ await runFreshCheck({[CORE_CANARY]: '200', [NATIVE_LATEST]: '200'}),
+ ).toBe('publish=true');
+ // A private canary-only package whose npm name does not exist is skipped
+ // by the loop, so it does not keep the tip pending.
+ expect(await runFreshCheck({[CORE_CANARY]: '200'})).toBe('publish=false');
+ });
+
+ it('publishes on any answer the registry cannot give', async () => {
+ expect(
+ await runFreshCheck({[CORE_CANARY]: '503', [NATIVE_CANARY]: '200'}),
+ ).toBe('publish=true');
+ expect(
+ await runFreshCheck({[CORE_CANARY]: '000', [NATIVE_CANARY]: '200'}),
+ ).toBe('publish=true');
+ expect(
+ await runFreshCheck({[CORE_CANARY]: '200', [NATIVE_LATEST]: '401'}),
+ ).toBe('publish=true');
+ });
+
it('binds stable publication to marker, tag, branch, head, version, and plan', () => {
const gateInputs = ci.on.workflow_dispatch.inputs;
expect(gateInputs['release-version']).toBeDefined();
@@ -388,14 +609,23 @@ describe('stable and canary publication authority', () => {
'Prune old canary versions',
]) {
expect(step(canary, name).if).toBe(
- "steps.canary-scope.outputs.publish == 'true'",
+ "steps.fresh.outputs.publish == 'true'",
);
}
- const publish = step(canary, 'Publish canary versions').run;
- expect(publish).toContain(
- 'DECLARED_VERSION=$(node -p "require(\'./packages/core/package.json\').version")',
+ expect(step(canary, 'Skip a tip whose canaries are all published').if).toBe(
+ "steps.canary-scope.outputs.publish == 'true'",
+ );
+ // The canary version is computed once and handed to the publish step.
+ const fresh = step(canary, 'Skip a tip whose canaries are all published');
+ expect(fresh.run).toContain(
+ 'CANARY_VERSION="$(node -p "require(\'./packages/core/package.json\').version")-canary.${GITHUB_SHA:0:7}"',
);
- expect(publish).toContain('CANARY_VERSION="${DECLARED_VERSION}-canary.');
+ expect(fresh.run).toContain('echo "version=${CANARY_VERSION}"');
+ expect(step(canary, 'Publish canary versions').env.CANARY_VERSION).toBe(
+ '${{ steps.fresh.outputs.version }}',
+ );
+ const publish = step(canary, 'Publish canary versions').run;
+ expect(publish).not.toContain('GITHUB_SHA');
expect(publish).toContain('--tag canary');
expect(publish).not.toContain('--tag latest');
const canaryText = JSON.stringify(canary);
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index dbe0389733..e1688b554b 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -13,7 +13,8 @@
# node scripts/npm/setup-trusted-publishing.mjs --setup-trust --replace --workflow release.yml
#
# Two jobs, selected by trigger:
-# - publish (stable): workflow_dispatch only. Publishes the `latest` dist-tag.
+# - publish (stable): workflow_dispatch with channel=stable (the default)
+# only. Publishes the `latest` dist-tag.
# The release flow is:
# 1. Cut and mark one release/vX.Y.Z branch from exact window-time main;
# X.Y.Z is the version main's package.json declares at that commit.
@@ -31,10 +32,13 @@
# waits for this workflow run's conclusion, never the publish job's: while
# packages are still propagating, the publish job passes and a follow-up
# job decides the run.
-# - canary: push to main only. Main normally declares the next planned version,
-# so this publishes <declared>-canary.<short-sha> to the `canary` dist-tag.
-# The trusted release merge-back briefly leaves main equal to the stable tag;
-# that push publishes no canary and waits for the separate next-plan PR:
+# - canary: at most hourly from main's tip (schedule), or on demand from main
+# (workflow_dispatch with channel=canary, for example the release-time
+# provenance proof). A tip that already has its canary publishes nothing.
+# Main normally declares the next planned version, so this publishes
+# <declared>-canary.<short-sha> to the `canary` dist-tag. The trusted
+# release merge-back briefly leaves main equal to the stable tag; that tip
+# publishes no canary and waits for the separate next-plan PR:
# npm install @astryxdesign/core@canary
#
# Why both jobs live here instead of in deploy.yml:
@@ -46,8 +50,8 @@
# published tarball matches the released commit and carries provenance.
#
# Concurrency is per-JOB (deliberately NOT a single workflow-level group): a
-# busy main firing many canary pushes must NEVER cancel or starve a pending
-# stable dispatch. Stable and canary therefore use independent concurrency
+# canary run must NEVER cancel or starve a pending stable dispatch, and a
+# stable dispatch never waits for the hourly canary. Stable and canary therefore use independent concurrency
# groups (see each job below).
#
# Provenance requires a PUBLIC repo (meta/astryx is public).
@@ -57,6 +61,11 @@ run-name: Release (${{ github.sha }})
on:
workflow_dispatch:
inputs:
+ channel:
+ description: 'stable publishes the release below; canary publishes main now'
+ type: choice
+ options: [stable, canary]
+ default: stable
dry-run:
description: 'Build and resolve what would publish, but do not publish'
type: boolean
@@ -64,35 +73,37 @@ on:
release-branch:
description: 'Single marked release/vX.Y.Z branch'
type: string
- required: true
+ required: false
release-version:
description: 'Exact X.Y.Z version recorded by the active marker'
type: string
- required: true
+ required: false
release-tag:
description: 'Exact immutable vX.Y.Z tag checked out by this run'
type: string
- required: true
+ required: false
expected-head:
description: 'Exact full release branch SHA carried by this tag'
type: string
- required: true
+ required: false
plan-digest:
description: 'Exact SHA-256 digest recorded by the active marker'
type: string
- required: true
- push:
- branches: [main]
+ required: false
+ # Hourly canary from main's tip. A pending hourly run is replaced by the
+ # next one rather than queued behind it (the canary concurrency group).
+ schedule:
+ - cron: '17 * * * *'
permissions: {}
jobs:
# Stable publish — manual dispatch only. Publishes the `latest` dist-tag.
publish:
- if: github.event_name == 'workflow_dispatch'
+ if: github.event_name == 'workflow_dispatch' && inputs.channel != 'canary'
runs-on: 4-core-ubuntu
# Dedicated, non-cancelling group. Independent of the canary group so a
- # canary push can never cancel or queue ahead of a stable release.
+ # canary run can never cancel or queue ahead of a stable release.
concurrency:
group: npm-release-stable
cancel-in-progress: false
@@ -104,6 +115,28 @@ jobs:
outputs:
verified: ${{ steps.publish.outputs.verified }}
steps:
+ # The release inputs are optional only so a canary dispatch can omit
+ # them; a stable dispatch needs every one.
+ - name: Require every stable release input
+ env:
+ RELEASE_BRANCH: ${{ inputs['release-branch'] }}
+ RELEASE_VERSION: ${{ inputs['release-version'] }}
+ RELEASE_TAG: ${{ inputs['release-tag'] }}
+ EXPECTED_HEAD: ${{ inputs['expected-head'] }}
+ PLAN_DIGEST: ${{ inputs['plan-digest'] }}
+ run: |
+ set -eu
+ missing=""
+ [ -n "$RELEASE_BRANCH" ] || missing="$missing release-branch"
+ [ -n "$RELEASE_VERSION" ] || missing="$missing release-version"
+ [ -n "$RELEASE_TAG" ] || missing="$missing release-tag"
+ [ -n "$EXPECTED_HEAD" ] || missing="$missing expected-head"
+ [ -n "$PLAN_DIGEST" ] || missing="$missing plan-digest"
+ if [ -n "$missing" ]; then
+ echo "::error::A stable release needs every release input; missing:$missing"
+ exit 1
+ fi
+
- name: Checkout immutable release tag
uses: actions/checkout@v7
with:
@@ -333,19 +366,21 @@ jobs:
fi
exit "$STATUS"
- # Canary publish — runs on every push to main. The @canary dist-tag always
- # points to the latest main commit:
+ # Canary publish — hourly from main's tip, or on demand. The @canary
+ # dist-tag points to main's tip as of the last canary:
# npm install @astryxdesign/core@canary
canary:
name: Publish canary to npm
- if: github.event_name == 'push'
+ if: >-
+ github.event_name == 'schedule' ||
+ (github.event_name == 'workflow_dispatch' && inputs.channel == 'canary')
runs-on: ubuntu-latest
# Dedicated group, independent of the stable group, so this can never
# cancel or starve a stable dispatch. Never cancel in progress: a canary
# that has started may already have published some packages, and
# cancelling it mid-loop leaves a partial canary set on npm. Bursts still
- # coalesce: while one canary runs, a newer push waits as the single pending
- # run, and a later push replaces that pending run before it starts.
+ # coalesce: while one canary runs, a newer run waits as the single pending
+ # run, and a later one replaces that pending run before it starts.
concurrency:
group: npm-release-canary
cancel-in-progress: false
@@ -358,6 +393,20 @@ jobs:
with:
fetch-depth: 0
+ - name: Require main and no dry run
+ env:
+ DRY_RUN: ${{ inputs.dry-run }}
+ run: |
+ set -eu
+ if [ "$GITHUB_REF" != "refs/heads/main" ]; then
+ echo "::error::Canaries publish only from main, not $GITHUB_REF."
+ exit 1
+ fi
+ if [ "${DRY_RUN:-false}" = "true" ]; then
+ echo "::error::A canary dispatch publishes; it has no dry run."
+ exit 1
+ fi
+
- name: Decide whether main may publish a canary
id: canary-scope
run: |
@@ -365,28 +414,46 @@ jobs:
git fetch origin 'refs/tags/v*:refs/tags/v*'
node scripts/release/active-release.mjs canary-eligibility
+ # The hourly run publishes nothing when every package the loop would
+ # publish already has this tip's canary. A package still missing, or a
+ # read the registry cannot answer, publishes; the per-package publisher
+ # skips versions already there.
+ - name: Skip a tip whose canaries are all published
+ if: steps.canary-scope.outputs.publish == 'true'
+ id: fresh
+ run: |
+ set -eu
+ CANARY_VERSION="$(node -p "require('./packages/core/package.json').version")-canary.${GITHUB_SHA:0:7}"
+ echo "version=${CANARY_VERSION}" >> "$GITHUB_OUTPUT"
+ node scripts/npm/canary-pending.mjs --version "$CANARY_VERSION"
+ if grep -qx 'pending=0' "$GITHUB_OUTPUT"; then
+ echo "publish=false" >> "$GITHUB_OUTPUT"
+ else
+ echo "publish=true" >> "$GITHUB_OUTPUT"
+ fi
+
# registry-url makes setup-node write the auth config `npm publish` reads.
# The Node line in .nvmrc must stay >= 24 so npm >= 11.5.1 ships with it,
# which OIDC trusted publishing requires.
- name: Setup Node and pnpm
- if: steps.canary-scope.outputs.publish == 'true'
+ if: steps.fresh.outputs.publish == 'true'
uses: ./.github/actions/setup
with:
registry-url: 'https://registry.npmjs.org'
- name: Build all packages
- if: steps.canary-scope.outputs.publish == 'true'
+ if: steps.fresh.outputs.publish == 'true'
run: pnpm build
- name: Publish canary versions
- if: steps.canary-scope.outputs.publish == 'true'
- # Pure OIDC trusted publishing — no NPM_TOKEN.
+ if: steps.fresh.outputs.publish == 'true'
+ # Pure OIDC trusted publishing — no NPM_TOKEN. The canary version is
+ # main's declared next version plus this commit, computed once above.
+ env:
+ CANARY_VERSION: ${{ steps.fresh.outputs.version }}
run: |
set -eu
- SHORT_SHA="${GITHUB_SHA:0:7}"
- # Main's package.json carries the next planned version.
- DECLARED_VERSION=$(node -p "require('./packages/core/package.json').version")
- CANARY_VERSION="${DECLARED_VERSION}-canary.${SHORT_SHA}"
+ [ -n "$CANARY_VERSION" ] || { echo "::error::No canary version was computed."; exit 1; }
echo "Publishing canary ${CANARY_VERSION}"
@@ -401,7 +468,11 @@ jobs:
# packages (for example Native) stay `private: true` in git as npm's hard
# guarantee against a stable publish; here — in the ephemeral CI
# checkout ONLY — we strip `private` so they publish to @canary.
- for pkg in packages/*/package.json packages/themes/*/package.json; do
+ # One list of the packages this job publishes drives the stamp, the
+ # publish loop and the skip check above.
+ CANARY_DIRS=$(node scripts/npm/canary-pending.mjs --list-dirs)
+ for pkg_dir in $CANARY_DIRS; do
+ pkg="$pkg_dir/package.json"
node -e "
const fs = require('fs');
const p = JSON.parse(fs.readFileSync('$pkg','utf8'));
@@ -431,7 +502,7 @@ jobs:
# their canaries. Publishes are per-package and idempotent, so attempting
# the rest is always safe.
FAILED=""
- for pkg_dir in packages/* packages/themes/*; do
+ for pkg_dir in $CANARY_DIRS; do
[ -f "$pkg_dir/package.json" ] || continue
# canaryOnly packages are publishable here (the stamp step above
# already stripped their `private` flag in this ephemeral checkout).
@@ -474,7 +545,7 @@ jobs:
echo "Canary published: npm install @astryxdesign/core@${CANARY_VERSION}"
- name: Prune old canary versions
- if: steps.canary-scope.outputs.publish == 'true'
+ if: steps.fresh.outputs.publish == 'true'
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
run: |
diff --git a/docs/release.md b/docs/release.md
index 1055b95709..42685b3dda 100644
--- a/docs/release.md
+++ b/docs/release.md
@@ -77,7 +77,8 @@ one trusted GitHub workflow per package.
- **Stable:** explicit dispatch from the immutable `vX.Y.Z` tag with the exact
release branch, version, head, tag, and plan digest. It publishes `latest`.
-- **Canary:** automatic main push. It publishes
+- **Canary:** at most hourly from main's tip, or on demand from `main` (a
+ dispatch with `channel: canary`). It publishes
`<declared-version>-canary.<short-sha>` to `canary` only while the declaration is
strictly above the newest stable tag. It never authorizes or mutates stable release
state.
@@ -126,8 +127,9 @@ finish: add a GitHub Actions publisher with owner `meta`, repository
`astryx`, workflow `release.yml`, no environment, and `npm publish` allowed.
npm expires a new trusted publisher that no publish has validated within 48
-hours. The next push to `main` publishes the package's canary and validates it.
-If no canary publishes in that window, recreate the publisher.
+hours. The next canary (the hourly run, or a canary dispatch from `main`)
+publishes the package's canary and validates it. If no canary publishes in that
+window, recreate the publisher.
Registry reads can keep reporting a just-created package as missing for a few
minutes. A re-run of `--bootstrap` in that window gets `409` for the placeholder
diff --git a/packages/charts/README.md b/packages/charts/README.md
index 29ff0b595e..9e53e520d5 100644
--- a/packages/charts/README.md
+++ b/packages/charts/README.md
@@ -46,7 +46,7 @@ import '@astryxdesign/charts/charts.css';
npm install @astryxdesign/charts@canary @astryxdesign/core@canary
```
-> Canary builds track the latest commit on `main` (`0.x.y-canary.<sha>`). They can break between any two versions — pin an exact version if you need stability.
+> Canary builds follow `main`'s tip, published at most once an hour and on demand (`0.x.y-canary.<sha>`). They can break between any two versions — pin an exact version if you need stability.
## Why no stable release?
diff --git a/packages/lab/README.md b/packages/lab/README.md
index e7bbe3e147..86ac3c45e4 100644
--- a/packages/lab/README.md
+++ b/packages/lab/README.md
@@ -48,7 +48,7 @@ import '@astryxdesign/core/astryx.css';
import '@astryxdesign/lab/lab.css';
```
-> Canary builds track the latest commit on `main` (`0.x.y-canary.<sha>`). They can break between any two versions — pin an exact version if you need stability.
+> Canary builds follow `main`'s tip, published at most once an hour and on demand (`0.x.y-canary.<sha>`). They can break between any two versions — pin an exact version if you need stability.
## Documenting a Lab component (canary docsite)
diff --git a/packages/vega/README.md b/packages/vega/README.md
index 154cfcfcec..a14f89f435 100644
--- a/packages/vega/README.md
+++ b/packages/vega/README.md
@@ -29,7 +29,7 @@ Vega is published **only** under the `@canary` dist-tag, so you must request tha
npm install @astryxdesign/vega@canary vega vega-lite
```
-> Canary builds track the latest commit on `main` (`0.x.y-canary.<sha>`). They can break between any two versions — pin an exact version if you need stability.
+> Canary builds follow `main`'s tip, published at most once an hour and on demand (`0.x.y-canary.<sha>`). They can break between any two versions — pin an exact version if you need stability.
## Usage
@@ -264,7 +264,7 @@ pnpm -F @astryxdesign/vega build
`package.json` keeps `"private": true` plus an `"astryx": { "canaryOnly": true }` marker. The release workflow (`.github/workflows/release.yml`) handles both dist-tags:
- The **stable (`latest`) job** skips every package that is `private` **or** `canaryOnly`, so Vega can never be published as a stable release by accident.
-- The **canary job** runs on every push to `main`. In its ephemeral CI checkout only (never in git) it strips the `private` flag from `canaryOnly` packages and publishes them to the `@canary` dist-tag as `0.x.y-canary.<short-sha>`, with npm OIDC trusted publishing + provenance.
+- The **canary job** runs at most hourly from `main`'s tip, and on demand from `main`. In its ephemeral CI checkout only (never in git) it strips the `private` flag from `canaryOnly` packages and publishes them to the `@canary` dist-tag as `0.x.y-canary.<short-sha>`, with npm OIDC trusted publishing + provenance.
The committed `private: true` is npm's hard guarantee that no stable publish can ever happen — **do not remove it until the graduation steps below are intentionally taken.**
@@ -289,7 +289,7 @@ When Vega is ready to be published publicly as a stable release, take these step
```
5. **Land the change, then version + publish** through the normal release flow:
- - Merge the PR that removes the gating (a canary publishes automatically on that push to `main`).
+ - Merge the PR that removes the gating (the next hourly canary, or a canary dispatch from `main`, publishes it).
- Run the version-bump PR (`pnpm version-packages`, refresh the lockfile, merge) — this bumps versions on `main` but publishes nothing.
- Dispatch the stable Release workflow to publish the `latest` dist-tag:
diff --git a/scripts/npm/canary-pending.mjs b/scripts/npm/canary-pending.mjs
new file mode 100644
index 0000000000..915292cb0a
--- /dev/null
+++ b/scripts/npm/canary-pending.mjs
@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Decide whether main's tip still needs canaries: which packages the
+ * canary loop would publish that the registry does not have yet.
+ * @input `--version <canary version>`, or `--list-dirs` to print the package
+ * directories the canary job publishes, one per line; the package manifests under
+ * `packages/` and `packages/themes/`. `ASTRYX_PUBLISH_REGISTRY` overrides
+ * the registry for tests.
+ * @output Prints each pending package; writes `pending=<count>` to
+ * `$GITHUB_OUTPUT` when set. A read the registry cannot answer counts as
+ * pending, so an unknown answer never skips a publish.
+ * @position The canary job in .github/workflows/release.yml runs it before it
+ * builds anything, so an hourly run at a tip whose canaries are all
+ * published stops early, and a tip with any package missing publishes again.
+ * The job's stamp and publish loops walk `--list-dirs`, so the check and the
+ * loops always mean the same packages.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
+
+import {packageExists, registryHas} from './publish-package.mjs';
+
+/**
+ * The packages the canary loop publishes: public `@astryxdesign` packages,
+ * plus private ones marked canary-only. `privateCanary` marks the latter,
+ * which the loop skips while their npm name does not exist.
+ */
+export function canaryPackages(root) {
+ const dirs = ['packages', 'packages/themes'].flatMap(parent =>
+ fs
+ .readdirSync(path.join(root, parent), {withFileTypes: true})
+ .filter(entry => entry.isDirectory())
+ .map(entry => `${parent}/${entry.name}`)
+ .sort(),
+ );
+ return dirs
+ .filter(dir => fs.existsSync(path.join(root, dir, 'package.json')))
+ .map(dir => ({
+ dir,
+ manifest: JSON.parse(
+ fs.readFileSync(path.join(root, dir, 'package.json'), 'utf8'),
+ ),
+ }))
+ .filter(
+ ({manifest}) =>
+ manifest.name?.startsWith('@astryxdesign/') &&
+ (!manifest.private || manifest.astryx?.canaryOnly),
+ )
+ .map(({dir, manifest}) => ({
+ dir,
+ name: manifest.name,
+ privateCanary: Boolean(manifest.private),
+ }));
+}
+
+/**
+ * The packages still to publish at `version`. A package counts as done when
+ * the registry has that version, or when it is a private canary-only package
+ * whose npm name does not exist (the loop skips it). Anything else, an
+ * unknown answer included, is pending.
+ */
+export async function pendingPackages({
+ packages,
+ version,
+ isPublished,
+ exists,
+}) {
+ const pending = [];
+ for (const pkg of packages) {
+ if ((await isPublished(pkg.name, version)) === true) continue;
+ if (pkg.privateCanary && (await exists(pkg.name)) === false) continue;
+ pending.push(pkg.name);
+ }
+ return pending;
+}
+
+async function main() {
+ if (process.argv.includes('--list-dirs')) {
+ for (const pkg of canaryPackages(process.cwd())) console.log(pkg.dir);
+ return;
+ }
+ const flag = process.argv.indexOf('--version');
+ const version = flag > 0 ? process.argv[flag + 1] : undefined;
+ if (!version) throw new Error('--version is required');
+ const registry = process.env.ASTRYX_PUBLISH_REGISTRY || undefined;
+ const pending = await pendingPackages({
+ packages: canaryPackages(process.cwd()),
+ version,
+ isPublished: (name, packageVersion) =>
+ registryHas({name, version: packageVersion, registry}),
+ exists: name => packageExists({name, registry}),
+ });
+ for (const name of pending)
+ console.log(`Not yet published: ${name}@${version}`);
+ if (pending.length === 0) {
+ console.log(`Every canary package is already published at ${version}.`);
+ }
+ if (process.env.GITHUB_OUTPUT) {
+ fs.appendFileSync(process.env.GITHUB_OUTPUT, `pending=${pending.length}\n`);
+ }
+}
+
+if (
+ process.argv[1] &&
+ import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+ main().catch(error => {
+ console.error(error.message);
+ process.exit(1);
+ });
+}
diff --git a/scripts/npm/canary-pending.test.mjs b/scripts/npm/canary-pending.test.mjs
new file mode 100644
index 0000000000..ff48249abc
--- /dev/null
+++ b/scripts/npm/canary-pending.test.mjs
@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Which canary packages main's tip still needs
+ * (scripts/npm/canary-pending.mjs).
+ */
+
+import path from 'node:path';
+import {describe, expect, it} from 'vitest';
+
+import {canaryPackages, pendingPackages} from './canary-pending.mjs';
+
+const ROOT = path.resolve(import.meta.dirname, '../..');
+
+describe('canaryPackages', () => {
+ it('lists public packages and private canary-only ones, never other private packages', () => {
+ const packages = canaryPackages(ROOT);
+ const byName = new Map(packages.map(pkg => [pkg.name, pkg]));
+
+ expect(byName.get('@astryxdesign/core')).toEqual({
+ dir: 'packages/core',
+ name: '@astryxdesign/core',
+ privateCanary: false,
+ });
+ expect(byName.get('@astryxdesign/theme-neutral')?.dir).toBe(
+ 'packages/themes/neutral',
+ );
+ expect(byName.get('@astryxdesign/vega')?.privateCanary).toBe(true);
+ expect(byName.has('@astryxdesign/theme-probe')).toBe(false);
+ });
+});
+
+describe('pendingPackages', () => {
+ const packages = [
+ {name: 'core', privateCanary: false},
+ {name: 'vega', privateCanary: true},
+ ];
+ const run = ({published, exists}) =>
+ pendingPackages({
+ packages,
+ version: '1.0.0-canary.abc1234',
+ isPublished: async name => published[name] ?? false,
+ exists: async name => exists[name] ?? true,
+ });
+
+ it('is empty when every package has the version', async () => {
+ expect(
+ await run({published: {core: true, vega: true}, exists: {}}),
+ ).toEqual([]);
+ });
+
+ it('keeps a package the registry does not have, or cannot answer for', async () => {
+ expect(await run({published: {core: true}, exists: {}})).toEqual(['vega']);
+ expect(
+ await run({published: {core: null, vega: true}, exists: {}}),
+ ).toEqual(['core']);
+ });
+
+ it('drops a private canary-only package only when its name certainly does not exist', async () => {
+ expect(await run({published: {core: true}, exists: {vega: false}})).toEqual(
+ [],
+ );
+ expect(await run({published: {core: true}, exists: {vega: null}})).toEqual([
+ 'vega',
+ ]);
+ });
+
+ it('never drops a public package for a missing name', async () => {
+ expect(await run({published: {vega: true}, exists: {core: false}})).toEqual(
+ ['core'],
+ );
+ });
+});