Skip to content

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

TypeScript

chore(npm): prune old canary versions (#4660)

Cindy Zhang297756f39282
diff --git a/.github/workflows/npm-canary-cleanup.yml b/.github/workflows/npm-canary-cleanup.yml
new file mode 100644
index 0000000000..f43fafc40a
--- /dev/null
+++ b/.github/workflows/npm-canary-cleanup.yml
@@ -0,0 +1,90 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+
+# Manual cleanup for stale npm canary versions.
+#
+# npm trusted publishing covers `npm publish`; destructive registry maintenance
+# such as `npm unpublish` still needs an npm automation token. Keep dry-run on
+# unless you have confirmed the package/version set and configured NPM_TOKEN with
+# the minimum required package permissions.
+name: npm canary cleanup
+
+on:
+ workflow_dispatch:
+ inputs:
+ dry-run:
+ description: 'Report what would be unpublished without changing npm'
+ type: boolean
+ default: true
+ current-version:
+ description: 'Optional base version whose canaries should be retained'
+ type: string
+ required: false
+ default: ''
+ max-unpublish-age-hours:
+ description: 'Skip versions older than this unless include-older is true'
+ type: number
+ default: 72
+ include-older:
+ description: 'Attempt versions outside the ordinary npm unpublish window'
+ type: boolean
+ default: false
+ package:
+ description: 'Optional single package name, e.g. @astryxdesign/core'
+ type: string
+ required: false
+ default: ''
+
+permissions:
+ contents: read
+
+jobs:
+ prune:
+ name: Prune canary versions
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v7
+
+ - name: Setup Node and pnpm
+ uses: ./.github/actions/setup
+ with:
+ install: 'false'
+ registry-url: 'https://registry.npmjs.org'
+
+ - name: Prune canaries
+ env:
+ DRY_RUN: ${{ inputs.dry-run }}
+ INCLUDE_OLDER: ${{ inputs.include-older }}
+ CURRENT_VERSION: ${{ inputs.current-version }}
+ MAX_UNPUBLISH_AGE_HOURS: ${{ inputs.max-unpublish-age-hours }}
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+ PACKAGE_NAME: ${{ inputs.package }}
+ run: |
+ set -eu
+ args=(
+ --max-unpublish-age-hours "${MAX_UNPUBLISH_AGE_HOURS}"
+ )
+
+ if [ -n "${CURRENT_VERSION}" ]; then
+ args+=(--current-version "${CURRENT_VERSION}")
+ fi
+
+ if [ -n "${PACKAGE_NAME}" ]; then
+ args+=(--package "${PACKAGE_NAME}")
+ fi
+
+ if [ "${INCLUDE_OLDER}" = "true" ]; then
+ args+=(--include-older)
+ fi
+
+ if [ "${DRY_RUN}" = "true" ]; then
+ args+=(--dry-run)
+ else
+ if [ -z "${NODE_AUTH_TOKEN:-}" ]; then
+ echo "::error::NPM_TOKEN is required when dry-run is false."
+ exit 1
+ fi
+ args+=(--yes)
+ fi
+
+ node scripts/npm/prune-canaries.mjs "${args[@]}"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 1d5003824a..9e6b6c9017 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -204,3 +204,14 @@ jobs:
fi
echo "Canary published: npm install @astryxdesign/core@${CANARY_VERSION}"
+
+ - name: Prune old canary versions
+ env:
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+ run: |
+ set -eu
+ if [ -z "${NODE_AUTH_TOKEN:-}" ]; then
+ echo "::notice::Skipping canary cleanup because NPM_TOKEN is not configured."
+ exit 0
+ fi
+ node scripts/npm/prune-canaries.mjs --yes
diff --git a/package.json b/package.json
index 0b1b059891..2b33074a93 100644
--- a/package.json
+++ b/package.json
@@ -36,7 +36,8 @@
"release": "pnpm build && changeset publish",
"prepare": "husky install",
"dev:sandbox": "pnpm -F @astryxdesign/core build && pnpm -F @astryxdesign/sandbox dev",
- "dev:sandbox:source": "ASTRYX_SOURCE=1 pnpm -F @astryxdesign/sandbox dev"
+ "dev:sandbox:source": "ASTRYX_SOURCE=1 pnpm -F @astryxdesign/sandbox dev",
+ "npm:prune-canaries": "node scripts/npm/prune-canaries.mjs"
},
"devDependencies": {
"@axe-core/playwright": "^4.12.1",
diff --git a/scripts/npm/prune-canaries.mjs b/scripts/npm/prune-canaries.mjs
new file mode 100644
index 0000000000..5dc700907b
--- /dev/null
+++ b/scripts/npm/prune-canaries.mjs
@@ -0,0 +1,329 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file prune-canaries.mjs
+ *
+ * Removes old npm canary versions for @astryxdesign/* packages.
+ *
+ * npm keeps every published version visible on the Versions tab. Canary builds
+ * are useful while they point at recent main commits, but old canaries are not a
+ * compatibility contract. This script keeps the newest canaries and optionally
+ * unpublishes the older ones that still fit npm's ordinary 72-hour unpublish
+ * window. Older canaries are reported but skipped by default because npm may
+ * reject those removals under its registry policy.
+ *
+ * @input npm registry metadata for @astryxdesign/* packages
+ * @output dry-run report, or npm unpublish calls when --yes is passed
+ * @position leaf — invoked manually or by the canary cleanup workflow
+ */
+
+import {spawnSync} from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {expandWorkspaceDirs} from '../lib/workspace-globs.mjs';
+
+export const DEFAULT_TAG = 'canary';
+export const DEFAULT_MAX_UNPUBLISH_AGE_HOURS = 72;
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '../..');
+
+function usage() {
+ return `Usage: node scripts/npm/prune-canaries.mjs [options]
+
+Options:
+ --yes Actually run npm unpublish. Default is dry-run.
+ --dry-run Report only. This is the default.
+ --current-version <version> Keep all canaries for this base version. Defaults
+ to the package's latest stable version from npm.
+ --tag <tag> Prerelease/dist-tag name to prune. Default: ${DEFAULT_TAG}.
+ --package <name> Limit to one package. Can be repeated.
+ --registry <url> npm registry URL. Default: https://registry.npmjs.org.
+ --max-unpublish-age-hours <n> Skip versions older than this many hours unless
+ --include-older is set. Default: ${DEFAULT_MAX_UNPUBLISH_AGE_HOURS}.
+ --include-older Attempt versions outside the ordinary npm
+ unpublish window. Use only after confirming the
+ package satisfies npm's policy for older versions.
+ --help Show this help.
+`;
+}
+
+function readNumber(value, flag) {
+ const n = Number(value);
+ if (!Number.isInteger(n) || n < 0) {
+ throw new Error(`${flag} must be a non-negative integer, got "${value}"`);
+ }
+ return n;
+}
+
+export function parseArgs(argv) {
+ const options = {
+ dryRun: true,
+ includeOlder: false,
+ currentVersion: undefined,
+ maxUnpublishAgeHours: DEFAULT_MAX_UNPUBLISH_AGE_HOURS,
+ packageNames: [],
+ registry: 'https://registry.npmjs.org',
+ tag: DEFAULT_TAG,
+ };
+
+ for (let i = 0; i < argv.length; i++) {
+ const arg = argv[i];
+ switch (arg) {
+ case '--yes':
+ options.dryRun = false;
+ break;
+ case '--dry-run':
+ options.dryRun = true;
+ break;
+ case '--include-older':
+ options.includeOlder = true;
+ break;
+ case '--current-version':
+ options.currentVersion = argv[++i];
+ break;
+ case '--max-unpublish-age-hours':
+ options.maxUnpublishAgeHours = readNumber(argv[++i], arg);
+ break;
+ case '--package':
+ options.packageNames.push(argv[++i]);
+ break;
+ case '--registry':
+ options.registry = argv[++i];
+ break;
+ case '--tag':
+ options.tag = argv[++i];
+ break;
+ case '--help':
+ case '-h':
+ options.help = true;
+ break;
+ default:
+ throw new Error(`Unknown option: ${arg}`);
+ }
+ }
+
+ if (!options.tag) throw new Error('--tag must be non-empty');
+ if (options.packageNames.some(name => !name)) {
+ throw new Error('--package must be followed by a package name');
+ }
+
+ return options;
+}
+
+function registryPackageUrl(registry, packageName) {
+ const base = registry.replace(/\/+$/, '');
+ const encodedName = encodeURIComponent(packageName).replace(/^%40/, '@');
+ return `${base}/${encodedName}`;
+}
+
+export function getCanaryBaseVersion(version, tag = DEFAULT_TAG) {
+ const marker = `-${tag}.`;
+ const markerIndex = version.indexOf(marker);
+ return markerIndex === -1 ? null : version.slice(0, markerIndex);
+}
+
+export function isTaggedCanaryVersion(version, tag = DEFAULT_TAG) {
+ return getCanaryBaseVersion(version, tag) !== null;
+}
+
+function ageHours(isoTimestamp, nowMs) {
+ return (nowMs - Date.parse(isoTimestamp)) / (1000 * 60 * 60);
+}
+
+export function selectCanaryVersions(metadata, options = {}) {
+ const tag = options.tag ?? DEFAULT_TAG;
+ const includeOlder = options.includeOlder ?? false;
+ const maxUnpublishAgeHours =
+ options.maxUnpublishAgeHours ?? DEFAULT_MAX_UNPUBLISH_AGE_HOURS;
+ const nowMs = options.nowMs ?? Date.now();
+
+ const versions = Array.isArray(metadata.versions)
+ ? metadata.versions
+ : Object.keys(metadata.versions ?? {});
+ const time = metadata.time ?? {};
+ const activeTaggedVersion = metadata['dist-tags']?.[tag];
+ const currentVersion =
+ options.currentVersion ?? metadata['dist-tags']?.latest;
+
+ const canaries = versions
+ .filter(version => isTaggedCanaryVersion(version, tag))
+ .map(version => ({
+ version,
+ baseVersion: getCanaryBaseVersion(version, tag),
+ publishedAt: time[version],
+ }))
+ .filter(entry => entry.publishedAt)
+ .sort((a, b) => Date.parse(a.publishedAt) - Date.parse(b.publishedAt));
+
+ const retained = new Set();
+ for (const entry of canaries) {
+ if (entry.baseVersion === currentVersion) retained.add(entry.version);
+ }
+ if (activeTaggedVersion) retained.add(activeTaggedVersion);
+
+ const candidates = canaries.filter(entry => !retained.has(entry.version));
+ const toUnpublish = [];
+ const skippedTooOld = [];
+
+ for (const entry of candidates) {
+ const hours = ageHours(entry.publishedAt, nowMs);
+ const candidate = {...entry, ageHours: hours};
+ if (!includeOlder && hours > maxUnpublishAgeHours) {
+ skippedTooOld.push(candidate);
+ } else {
+ toUnpublish.push(candidate);
+ }
+ }
+
+ return {
+ activeTaggedVersion,
+ canaries,
+ currentVersion,
+ retainedVersions: [...retained],
+ skippedTooOld,
+ toUnpublish,
+ };
+}
+
+function getWorkspacePackageVersionMap(root) {
+ const versions = new Map();
+ for (const dir of expandWorkspaceDirs(root)) {
+ const manifestPath = path.join(dir, 'package.json');
+ if (!fs.existsSync(manifestPath)) continue;
+
+ const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+ if (!manifest.name?.startsWith('@astryxdesign/')) continue;
+ if (manifest.private && !manifest.astryx?.canaryOnly) continue;
+ if (manifest.version) versions.set(manifest.name, manifest.version);
+ }
+ return versions;
+}
+
+function getWorkspacePackageNames(root) {
+ return [...getWorkspacePackageVersionMap(root).keys()].sort();
+}
+
+function getWorkspaceCurrentCanaryBaseVersion(root) {
+ const coreManifestPath = path.join(root, 'packages/core/package.json');
+ if (!fs.existsSync(coreManifestPath)) return undefined;
+
+ const coreManifest = JSON.parse(fs.readFileSync(coreManifestPath, 'utf8'));
+ return coreManifest.version;
+}
+
+async function fetchPackageMetadata(packageName, registry) {
+ const response = await fetch(registryPackageUrl(registry, packageName), {
+ headers: {accept: 'application/json'},
+ });
+ if (!response.ok) {
+ throw new Error(
+ `Failed to fetch ${packageName} metadata: ${response.status} ${response.statusText}`,
+ );
+ }
+ return response.json();
+}
+
+function npmUnpublish(packageName, version, registry) {
+ return spawnSync(
+ 'npm',
+ ['unpublish', `${packageName}@${version}`, '--registry', registry],
+ {stdio: 'inherit'},
+ );
+}
+
+function plural(count, singular, pluralForm = `${singular}s`) {
+ return `${count} ${count === 1 ? singular : pluralForm}`;
+}
+
+export async function pruneCanaries(options) {
+ const packageNames =
+ options.packageNames.length > 0
+ ? options.packageNames
+ : getWorkspacePackageNames(ROOT);
+
+ const workspaceVersions = getWorkspacePackageVersionMap(ROOT);
+ const currentCanaryBaseVersion = getWorkspaceCurrentCanaryBaseVersion(ROOT);
+
+ let unpublished = 0;
+ let failures = 0;
+
+ for (const packageName of packageNames) {
+ const metadata = await fetchPackageMetadata(packageName, options.registry);
+ const selection = selectCanaryVersions(metadata, {
+ ...options,
+ currentVersion:
+ options.currentVersion ??
+ currentCanaryBaseVersion ??
+ workspaceVersions.get(packageName),
+ });
+
+ console.log(`\n${packageName}`);
+ console.log(
+ ` ${plural(selection.canaries.length, 'canary', 'canaries')} found; keeping ${plural(selection.retainedVersions.length, 'version')}`,
+ );
+
+ console.log(
+ ` Retention: keeping ${selection.currentVersion ? `all ${selection.currentVersion} canaries` : 'only the active dist-tag canary'}; pruning older base versions`,
+ );
+
+ if (selection.skippedTooOld.length > 0) {
+ console.log(
+ ` Skipping ${plural(selection.skippedTooOld.length, 'version')} older than ${options.maxUnpublishAgeHours}h; use --include-older only after checking npm policy.`,
+ );
+ }
+
+ if (selection.toUnpublish.length === 0) {
+ console.log(' Nothing to unpublish.');
+ continue;
+ }
+
+ for (const entry of selection.toUnpublish) {
+ const spec = `${packageName}@${entry.version}`;
+ const age = `${entry.ageHours.toFixed(1)}h`;
+ if (options.dryRun) {
+ console.log(` [dry-run] Would unpublish ${spec} (${age} old)`);
+ continue;
+ }
+
+ console.log(` Unpublishing ${spec} (${age} old)`);
+ const result = npmUnpublish(packageName, entry.version, options.registry);
+ if (result.status === 0) {
+ unpublished += 1;
+ } else {
+ failures += 1;
+ console.error(` Failed to unpublish ${spec}`);
+ }
+ }
+ }
+
+ if (options.dryRun) {
+ console.log(
+ '\nDry run complete. Re-run with --yes to unpublish eligible versions.',
+ );
+ } else {
+ console.log(`\nUnpublished ${plural(unpublished, 'version')}.`);
+ }
+
+ if (failures > 0) {
+ throw new Error(`Failed to unpublish ${plural(failures, 'version')}`);
+ }
+}
+
+async function main() {
+ const options = parseArgs(process.argv.slice(2));
+ if (options.help) {
+ console.log(usage());
+ return;
+ }
+ await pruneCanaries(options);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+ main().catch(error => {
+ console.error(`\n✗ ${error.message}`);
+ process.exit(1);
+ });
+}
diff --git a/scripts/npm/prune-canaries.test.mjs b/scripts/npm/prune-canaries.test.mjs
new file mode 100644
index 0000000000..ff7e243af5
--- /dev/null
+++ b/scripts/npm/prune-canaries.test.mjs
@@ -0,0 +1,155 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file prune-canaries.test.mjs
+ * Unit tests for npm canary retention selection.
+ */
+
+import {describe, expect, it} from 'vitest';
+
+import {
+ getCanaryBaseVersion,
+ isTaggedCanaryVersion,
+ parseArgs,
+ selectCanaryVersions,
+} from './prune-canaries.mjs';
+
+const NOW = Date.parse('2026-08-02T12:00:00.000Z');
+
+function metadata() {
+ return {
+ versions: [
+ '0.2.0',
+ '0.2.0-canary.current1',
+ '0.2.0-canary.current2',
+ '0.1.9-canary.old1',
+ '0.1.9-canary.old2',
+ '0.2.0-beta.1',
+ ],
+ time: {
+ '0.2.0': '2026-08-01T00:00:00.000Z',
+ '0.2.0-canary.current1': '2026-07-20T00:00:00.000Z',
+ '0.2.0-canary.current2': '2026-08-02T00:00:00.000Z',
+ '0.1.9-canary.old1': '2026-07-20T00:00:00.000Z',
+ '0.1.9-canary.old2': '2026-08-02T00:00:00.000Z',
+ '0.2.0-beta.1': '2026-08-02T01:00:00.000Z',
+ },
+ 'dist-tags': {
+ latest: '0.2.0',
+ canary: '0.2.0-canary.current2',
+ },
+ };
+}
+
+describe('canary version parsing', () => {
+ it('matches only the requested prerelease tag', () => {
+ expect(isTaggedCanaryVersion('0.2.1-canary.abc1234')).toBe(true);
+ expect(isTaggedCanaryVersion('0.2.1-beta.1')).toBe(false);
+ expect(isTaggedCanaryVersion('0.2.1')).toBe(false);
+ });
+
+ it('extracts the base version from a tagged canary', () => {
+ expect(getCanaryBaseVersion('0.2.1-canary.abc1234')).toBe('0.2.1');
+ expect(getCanaryBaseVersion('0.2.1-beta.1')).toBe(null);
+ });
+});
+
+describe('selectCanaryVersions', () => {
+ it('keeps every canary for the current stable version', () => {
+ const result = selectCanaryVersions(metadata(), {nowMs: NOW});
+
+ expect(result.currentVersion).toBe('0.2.0');
+ expect(result.retainedVersions.sort()).toEqual([
+ '0.2.0-canary.current1',
+ '0.2.0-canary.current2',
+ ]);
+ });
+
+ it('selects recent older-base canaries for unpublish', () => {
+ const result = selectCanaryVersions(metadata(), {nowMs: NOW});
+
+ expect(result.toUnpublish.map(entry => entry.version)).toEqual([
+ '0.1.9-canary.old2',
+ ]);
+ expect(result.skippedTooOld.map(entry => entry.version)).toEqual([
+ '0.1.9-canary.old1',
+ ]);
+ });
+
+ it('can include older older-base canaries when explicitly requested', () => {
+ const result = selectCanaryVersions(metadata(), {
+ includeOlder: true,
+ nowMs: NOW,
+ });
+
+ expect(result.toUnpublish.map(entry => entry.version)).toEqual([
+ '0.1.9-canary.old1',
+ '0.1.9-canary.old2',
+ ]);
+ expect(result.skippedTooOld).toEqual([]);
+ });
+
+ it('retains the active dist-tag version even if its base is older', () => {
+ const data = metadata();
+ data['dist-tags'].canary = '0.1.9-canary.old2';
+
+ const result = selectCanaryVersions(data, {
+ includeOlder: true,
+ nowMs: NOW,
+ });
+
+ expect(result.retainedVersions.sort()).toEqual([
+ '0.1.9-canary.old2',
+ '0.2.0-canary.current1',
+ '0.2.0-canary.current2',
+ ]);
+ expect(result.toUnpublish.map(entry => entry.version)).toEqual([
+ '0.1.9-canary.old1',
+ ]);
+ });
+
+ it('allows callers to override the current version', () => {
+ const result = selectCanaryVersions(metadata(), {
+ currentVersion: '0.1.9',
+ includeOlder: true,
+ nowMs: NOW,
+ });
+
+ expect(result.retainedVersions.sort()).toEqual([
+ '0.1.9-canary.old1',
+ '0.1.9-canary.old2',
+ '0.2.0-canary.current2',
+ ]);
+ expect(result.toUnpublish.map(entry => entry.version)).toEqual([
+ '0.2.0-canary.current1',
+ ]);
+ });
+});
+
+describe('parseArgs', () => {
+ it('defaults to dry-run pruning of older base versions', () => {
+ expect(parseArgs([])).toMatchObject({
+ currentVersion: undefined,
+ dryRun: true,
+ tag: 'canary',
+ });
+ });
+
+ it('parses destructive mode and package filters', () => {
+ expect(
+ parseArgs([
+ '--yes',
+ '--current-version',
+ '0.2.0',
+ '--package',
+ '@astryxdesign/core',
+ '--include-older',
+ ]),
+ ).toMatchObject({
+ currentVersion: '0.2.0',
+ dryRun: false,
+ includeOlder: true,
+ packageNames: ['@astryxdesign/core'],
+ });
+ });
+});