Skip to content

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

TypeScript
10.4 KB
Raw Blame
// 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);
  });
}