Skip to content

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.mjs
index 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 @@ program
program.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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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');
+ });
+});