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.mjsindex 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.ymlindex 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: stabledry-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: falserelease-version:description: 'Exact X.Y.Z version recorded by the active marker'type: string- required: true+ required: falserelease-tag:description: 'Exact immutable vX.Y.Z tag checked out by this run'type: string- required: true+ required: falseexpected-head:description: 'Exact full release branch SHA carried by this tag'type: string- required: true+ required: falseplan-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-stablecancel-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 taguses: actions/checkout@v7with:@@ -333,19 +366,21 @@ jobs:fiexit "$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@canarycanary: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-canarycancel-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 canaryid: canary-scoperun: |@@ -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/setupwith: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.mdindex 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 exactrelease 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 isstrictly above the newest stable tag. It never authorizes or mutates stable releasestate.@@ -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 fewminutes. A re-run of `--bootstrap` in that window gets `409` for the placeholderdiff --git a/packages/charts/README.md b/packages/charts/README.mdindex 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.mdindex 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.mdindex 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 thanpm 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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'],+ );+ });+});