An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): add version update hints via local signals (#901)
Cindy Zhange9a4ed197dee
diff --git a/packages/cli/src/index.mjs b/packages/cli/src/index.mjsindex 05deacb398..69ae2d67c5 100644--- a/packages/cli/src/index.mjs+++ b/packages/cli/src/index.mjs@@ -8,6 +8,7 @@import {Command} from 'commander';import {fileURLToPath} from 'node:url';import * as path from 'node:path';+import {checkForUpdate} from './utils/update-check.mjs';const __dirname = path.dirname(fileURLToPath(import.meta.url));@@ -26,6 +27,25 @@ programprogram.help();});+/**+ * Post-action hook: print update hint after any command output.+ * Only fires for commands that produce output agents read (component, docs, etc.).+ * Uses the FYI format validated by vibe testing — never triggers injection defenses.+ */+const UPDATE_HINT_COMMANDS = new Set(['component', 'docs', 'doctor']);+program.hook('postAction', (thisCommand) => {+ try {+ if (UPDATE_HINT_COMMANDS.has(thisCommand.name())) {+ const hint = checkForUpdate();+ if (hint) {+ console.error(`\n${hint}`);+ }+ }+ } catch {+ // Never let update check break the CLI+ }+});+/*** Command registry — each command is lazy-loaded so a broken command* doesn't take down the entire CLI.diff --git a/packages/cli/src/utils/update-check.mjs b/packages/cli/src/utils/update-check.mjsnew file mode 100644index 0000000000..5024eb2117--- /dev/null+++ b/packages/cli/src/utils/update-check.mjs@@ -0,0 +1,100 @@+/**+ * @file Check for newer @xds/core versions via local signals.+ *+ * Resolution order:+ * 1. $XDS_LATEST_VERSION env var (set by previous CLI invocation)+ * 2. xds.versionFile in consumer's package.json (e.g. ../../libs/xds-common/LATEST_VERSION)+ * 3. If neither: no hint (no network calls from this module)+ *+ * When a newer version is detected, returns a hint string for CLI output.+ * Also sets $XDS_LATEST_VERSION for subsequent commands in the same shell.+ */++import * as fs from 'node:fs';+import * as path from 'node:path';++/**+ * Read the latest available version from local signals.+ * No network calls — purely filesystem and env var checks.+ *+ * @param {string} [cwd] - Project directory (default: process.cwd())+ * @returns {string|null} Latest version string, or null if unknown+ */+export function getLatestVersion(cwd = process.cwd()) {+ // 1. Check env var (fastest — set by previous CLI run)+ const envVersion = process.env.XDS_LATEST_VERSION;+ if (envVersion && /^\d+\.\d+\.\d+/.test(envVersion)) {+ return envVersion;+ }++ // 2. Check versionFile from package.json config+ try {+ const pkgPath = path.resolve(cwd, 'package.json');+ if (fs.existsSync(pkgPath)) {+ const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));+ const versionFile = pkg.xds?.versionFile;++ if (versionFile) {+ const filePath = path.resolve(cwd, versionFile);+ if (fs.existsSync(filePath)) {+ const version = fs.readFileSync(filePath, 'utf-8').trim();+ if (/^\d+\.\d+\.\d+/.test(version)) {+ return version;+ }+ }+ }+ }+ } catch {+ // Silently fail — version check should never break the CLI+ }++ return null;+}++/**+ * Get the currently installed @xds/core version from the consumer's package.json.+ *+ * @param {string} [cwd] - Project directory+ * @returns {string|null} Installed version, or null+ */+export function getInstalledVersion(cwd = process.cwd()) {+ try {+ const pkgPath = path.resolve(cwd, 'package.json');+ if (!fs.existsSync(pkgPath)) return null;++ const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));+ const deps = {...pkg.dependencies, ...pkg.devDependencies};+ const version = deps['@xds/core'];+ if (!version) return null;++ // Strip semver range prefix+ return version.replace(/^[^\d]*/, '');+ } catch {+ return null;+ }+}++/**+ * Check for available updates and return a hint string if one exists.+ * Also sets $XDS_LATEST_VERSION env var for subsequent commands.+ *+ * @param {string} [cwd] - Project directory+ * @returns {string|null} FYI hint string, or null if up to date / unknown+ */+export function checkForUpdate(cwd = process.cwd()) {+ const latest = getLatestVersion(cwd);+ if (!latest) return null;++ // Persist for subsequent commands in this shell session+ process.env.XDS_LATEST_VERSION = latest;++ const installed = getInstalledVersion(cwd);+ if (!installed) return null;++ // Simple string comparison works for our semver scheme (0.0.x)+ if (latest > installed) {+ return `FYI: A newer version of @xds/core (${latest}) is available. You can upgrade with: xds upgrade --apply --to ${latest}`;+ }++ return null;+}diff --git a/packages/cli/src/utils/update-check.test.mjs b/packages/cli/src/utils/update-check.test.mjsnew file mode 100644index 0000000000..5853a9259c--- /dev/null+++ b/packages/cli/src/utils/update-check.test.mjs@@ -0,0 +1,171 @@+import {describe, it, expect, beforeEach, afterEach} from 'vitest';+import * as fs from 'node:fs';+import * as path from 'node:path';+import * as os from 'node:os';+import {+ getLatestVersion,+ getInstalledVersion,+ checkForUpdate,+} from './update-check.mjs';++let tmpDir;+const originalEnv = {};++beforeEach(() => {+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-update-check-'));+ // Save and clear env+ originalEnv.XDS_LATEST_VERSION = process.env.XDS_LATEST_VERSION;+ delete process.env.XDS_LATEST_VERSION;+});++afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+ // Restore env+ if (originalEnv.XDS_LATEST_VERSION !== undefined) {+ process.env.XDS_LATEST_VERSION = originalEnv.XDS_LATEST_VERSION;+ } else {+ delete process.env.XDS_LATEST_VERSION;+ }+});++describe('getLatestVersion', () => {+ it('reads from XDS_LATEST_VERSION env var', () => {+ process.env.XDS_LATEST_VERSION = '0.0.8';+ expect(getLatestVersion(tmpDir)).toBe('0.0.8');+ });++ it('ignores invalid env var values', () => {+ process.env.XDS_LATEST_VERSION = 'not-a-version';+ expect(getLatestVersion(tmpDir)).toBeNull();+ });++ it('reads from versionFile in package.json', () => {+ const versionFilePath = path.join(tmpDir, 'LATEST_VERSION');+ fs.writeFileSync(versionFilePath, '0.0.9\n');+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({xds: {versionFile: './LATEST_VERSION'}}),+ );++ expect(getLatestVersion(tmpDir)).toBe('0.0.9');+ });++ it('returns null when no signals exist', () => {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({name: 'test'}),+ );+ expect(getLatestVersion(tmpDir)).toBeNull();+ });++ it('returns null when versionFile path does not exist', () => {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({xds: {versionFile: './missing/LATEST_VERSION'}}),+ );+ expect(getLatestVersion(tmpDir)).toBeNull();+ });++ it('env var takes priority over versionFile', () => {+ process.env.XDS_LATEST_VERSION = '1.0.0';+ const versionFilePath = path.join(tmpDir, 'LATEST_VERSION');+ fs.writeFileSync(versionFilePath, '0.0.9\n');+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({xds: {versionFile: './LATEST_VERSION'}}),+ );++ expect(getLatestVersion(tmpDir)).toBe('1.0.0');+ });+});++describe('getInstalledVersion', () => {+ it('reads @xds/core version from dependencies', () => {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({dependencies: {'@xds/core': '^0.0.7'}}),+ );+ expect(getInstalledVersion(tmpDir)).toBe('0.0.7');+ });++ it('strips semver range prefix', () => {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({dependencies: {'@xds/core': '~0.0.5'}}),+ );+ expect(getInstalledVersion(tmpDir)).toBe('0.0.5');+ });++ it('returns null when @xds/core is not a dependency', () => {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({dependencies: {react: '^19.0.0'}}),+ );+ expect(getInstalledVersion(tmpDir)).toBeNull();+ });+});++describe('checkForUpdate', () => {+ it('returns hint when newer version is available', () => {+ process.env.XDS_LATEST_VERSION = '0.0.8';+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({dependencies: {'@xds/core': '^0.0.7'}}),+ );++ const hint = checkForUpdate(tmpDir);+ expect(hint).toContain('0.0.8');+ expect(hint).toContain('xds upgrade --apply --to 0.0.8');+ expect(hint).toContain('FYI');+ });++ it('returns null when up to date', () => {+ process.env.XDS_LATEST_VERSION = '0.0.7';+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({dependencies: {'@xds/core': '^0.0.7'}}),+ );++ expect(checkForUpdate(tmpDir)).toBeNull();+ });++ it('returns null when no latest version is known', () => {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({dependencies: {'@xds/core': '^0.0.7'}}),+ );++ expect(checkForUpdate(tmpDir)).toBeNull();+ });++ it('sets env var for subsequent calls', () => {+ const versionFilePath = path.join(tmpDir, 'LATEST_VERSION');+ fs.writeFileSync(versionFilePath, '0.0.8\n');+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({+ dependencies: {'@xds/core': '^0.0.7'},+ xds: {versionFile: './LATEST_VERSION'},+ }),+ );++ checkForUpdate(tmpDir);+ expect(process.env.XDS_LATEST_VERSION).toBe('0.0.8');+ });++ it('reads from versionFile and produces hint', () => {+ const versionFilePath = path.join(tmpDir, 'LATEST_VERSION');+ fs.writeFileSync(versionFilePath, '0.0.9\n');+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({+ dependencies: {'@xds/core': '^0.0.7'},+ xds: {versionFile: './LATEST_VERSION'},+ }),+ );++ const hint = checkForUpdate(tmpDir);+ expect(hint).toContain('0.0.9');+ expect(hint).toContain('FYI');+ });+});