Skip to content

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

TypeScript

feat(cli): upgrade bumps @xds/* deps, installs, and refreshes agent docs (#897)

Cindy Zhang5ea14a892ec4
diff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjs
index d21acdd160..96c079bf31 100644
--- a/packages/cli/src/commands/agent-docs.mjs
+++ b/packages/cli/src/commands/agent-docs.mjs
@@ -142,7 +142,7 @@ export function generateCompressedIndex(version, {coreDir, zh = false, lang, run
}
lines.push(`${run} swizzle <Name> eject component source (use --gap to report why)`);
- lines.push(`${run} upgrade --apply run version migration codemods`);
+ lines.push(`${run} upgrade --apply [--from <v> --to ${version}] run version migration codemods`);
lines.push(`--detail compact|brief less output | --lang dense|zh translation`);
lines.push(`RULE: after @xds/core bump, always run ${run} upgrade --apply`);
lines.push(`RULE: when swizzling, always use --gap to report missing capabilities`);
diff --git a/packages/cli/src/commands/upgrade.mjs b/packages/cli/src/commands/upgrade.mjs
index 226c75c6f6..6c4f54c9b3 100644
--- a/packages/cli/src/commands/upgrade.mjs
+++ b/packages/cli/src/commands/upgrade.mjs
@@ -1,8 +1,16 @@
/**
- * @file upgrade command — Run version-to-version codemods
+ * @file upgrade command — Full version-to-version upgrade pipeline
*
- * `xds upgrade` detects the consumer's @xds/core version and runs
- * all codemods needed to migrate to the target version.
+ * `xds upgrade` detects the consumer's @xds/core version, bumps all
+ * @xds/* dependencies, installs them, and runs codemods to migrate
+ * breaking API changes.
+ *
+ * Pipeline (--apply):
+ * 1. Detect current version from package.json (or --from)
+ * 2. Bump all @xds/* deps in package.json to --to version
+ * 3. Run package manager install (yarn/npm/pnpm/bun)
+ * 4. Run codemods for the version range
+ * 5. Refresh agent docs (AGENTS.md / CLAUDE.md) if present
*
* Options:
* --apply Write changes to disk (default: dry-run)
@@ -16,6 +24,7 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
+import {execSync} from 'node:child_process';
import * as p from '@clack/prompts';
import {ensureJscodeshift} from '../codemods/ensure-jscodeshift.mjs';
import {
@@ -24,7 +33,8 @@ import {
versions,
} from '../codemods/registry.mjs';
import {runCodemods} from '../codemods/runner.mjs';
-import {installAgentDocs} from './agent-docs.mjs';
+import {installAgentDocs, discoverAgentDocs} from './agent-docs.mjs';
+import {detectPackageManager} from '../utils/package-manager.mjs';
/**
* Detect the installed @xds/core version from the consumer's package.json.
@@ -47,6 +57,63 @@ function detectCurrentVersion() {
}
}
+/**
+ * Bump all @xds/* dependencies in the consumer's package.json to the target version.
+ * Preserves the existing semver range prefix (^, ~, etc.).
+ *
+ * @param {string} targetVersion - Version to bump to (e.g. '0.0.5')
+ * @returns {{bumped: string[], pkgPath: string}|null} List of bumped package names, or null if no package.json
+ */
+function bumpXdsDeps(targetVersion) {
+ const pkgPath = path.resolve(process.cwd(), 'package.json');
+ if (!fs.existsSync(pkgPath)) return null;
+
+ const raw = fs.readFileSync(pkgPath, 'utf-8');
+ const pkg = JSON.parse(raw);
+ const bumped = [];
+
+ for (const depField of ['dependencies', 'devDependencies']) {
+ const deps = pkg[depField];
+ if (!deps) continue;
+
+ for (const name of Object.keys(deps)) {
+ if (!name.startsWith('@xds/')) continue;
+
+ const current = deps[name];
+ // Preserve range prefix (^, ~, >=, etc.)
+ const prefix = current.match(/^([^\d]*)/)?.[1] ?? '^';
+ const newRange = `${prefix}${targetVersion}`;
+
+ if (current !== newRange) {
+ deps[name] = newRange;
+ bumped.push(name);
+ }
+ }
+ }
+
+ if (bumped.length === 0) return {bumped: [], pkgPath};
+
+ // Write back with same formatting (detect indent from original)
+ const indent = raw.match(/^(\s+)"/m)?.[1] ?? ' ';
+ fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + '\n');
+ return {bumped, pkgPath};
+}
+
+/**
+ * Get the install command for the detected package manager.
+ * @returns {string}
+ */
+function getInstallCommand() {
+ const pm = detectPackageManager();
+ switch (pm) {
+ case 'yarn': return 'yarn install';
+ case 'pnpm': return 'pnpm install';
+ case 'bun': return 'bun install';
+ case 'npm':
+ default: return 'npm install';
+ }
+}
+
/**
* List all available codemods across all versions.
*/
@@ -147,6 +214,23 @@ export function registerUpgrade(program) {
`${totalTransforms} codemod${totalTransforms === 1 ? '' : 's'} to run${options.apply ? '' : ' (dry run)'}`,
);
+ // Bump @xds/* deps and install before running codemods
+ if (options.apply && !skipVersionCheck) {
+ const result = bumpXdsDeps(targetVersion);
+ if (result && result.bumped.length > 0) {
+ p.log.info(`Bumped ${result.bumped.join(', ')} → ${targetVersion}`);
+
+ const installCmd = getInstallCommand();
+ p.log.step(`Running ${installCmd}...`);
+ try {
+ execSync(installCmd, {stdio: 'inherit', cwd: process.cwd()});
+ p.log.success('Dependencies installed.');
+ } catch {
+ p.log.warn('Install failed — codemods will still run against existing code.');
+ }
+ }
+ }
+
// Ensure jscodeshift is available
const ready = await ensureJscodeshift({installDeps: options.installDeps});
if (!ready) {
@@ -162,14 +246,17 @@ export function registerUpgrade(program) {
codemod: options.codemod,
});
- // Refresh agent docs (AGENTS.md / CLAUDE.md) with updated component index
- if (options.apply) {
+ // Refresh agent docs if any exist (AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, etc.)
+ // Always update after --apply; also update during dry-run if files exist,
+ // since the index reflects the installed CLI version, not the codemods.
+ const existingDocs = discoverAgentDocs(process.cwd());
+ if (existingDocs.length > 0) {
try {
- installAgentDocs(process.cwd());
- p.log.success('Agent docs updated to match new version.');
+ const written = installAgentDocs(process.cwd());
+ p.log.success(`Agent docs updated: ${written.join(', ')}`);
} catch {
p.log.warn(
- 'Could not update agent docs. Run `npx xds init --features agents` to update manually.',
+ 'Could not update agent docs. Run `npx xds agent-docs` to update manually.',
);
}
}