Skip to content

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

TypeScript

fix(cli): don't inject XDS block into files without markers during upgrade (#1495)

Cindy Zhange5196e43f7f3
diff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjs
index ef840dd612..8ba185ed80 100644
--- a/packages/cli/src/commands/agent-docs.mjs
+++ b/packages/cli/src/commands/agent-docs.mjs
@@ -191,12 +191,18 @@ export function getXdsVersion(coreDir) {
/**
* Inject or update XDS section in a file using XDS markers.
* If the file has existing markers, replaces the content between them.
- * If the file exists without markers, appends the block.
+ * If the file exists without markers, appends the block (unless onlyReplace is true).
* If createIfMissing is true and the file doesn't exist, creates it with a header.
*
+ * @param {string} filePath
+ * @param {string} compressedIndex
+ * @param {object} [options]
+ * @param {boolean} [options.createIfMissing] - Create the file if it doesn't exist
+ * @param {string} [options.header] - Header for newly created files
+ * @param {boolean} [options.onlyReplace] - Only write if XDS markers already exist (skip files without markers)
* @returns {boolean} Whether the file was written
*/
-export function injectXdsBlock(filePath, compressedIndex, {createIfMissing = false, header = ''} = {}) {
+export function injectXdsBlock(filePath, compressedIndex, {createIfMissing = false, header = '', onlyReplace = false} = {}) {
let content = '';
if (fs.existsSync(filePath)) {
@@ -210,6 +216,9 @@ export function injectXdsBlock(filePath, compressedIndex, {createIfMissing = fal
content.slice(0, startIdx) +
compressedIndex +
content.slice(endIdx + XDS_MARKER_END.length);
+ } else if (onlyReplace) {
+ // File exists but has no XDS markers — skip it
+ return false;
} else {
content = content.trimEnd() + '\n\n' + compressedIndex + '\n';
}
@@ -313,9 +322,10 @@ export function removeAgentDocs(targetDir) {
* @param {string} [options.lang]
* @param {string} [options.agent] - Tool preset: 'claude', 'cursor', 'codex', 'all'
* @param {string[]} [options.paths] - Explicit paths (overrides agent/auto-detect)
+ * @param {boolean} [options.onlyReplace] - Only update files that already have XDS markers (for upgrades)
* @returns {string[]} List of files written
*/
-export function installAgentDocs(targetDir, {zh = false, lang, agent, paths} = {}) {
+export function installAgentDocs(targetDir, {zh = false, lang, agent, paths, onlyReplace = false} = {}) {
const coreDir = findCoreDir(targetDir);
const version = getXdsVersion(coreDir);
const runPrefix = getRunPrefix(targetDir);
@@ -366,13 +376,15 @@ export function installAgentDocs(targetDir, {zh = false, lang, agent, paths} = {
if (existing.length > 0) {
for (const p of existing) {
- injectXdsBlock(path.join(targetDir, p), compressedIndex);
- written.push(p);
+ const didWrite = injectXdsBlock(path.join(targetDir, p), compressedIndex, {onlyReplace});
+ if (didWrite) written.push(p);
}
return written;
}
- // Nothing exists — create .claude/CLAUDE.md as default
+ // Nothing exists — create .claude/CLAUDE.md as default (skip if onlyReplace)
+ if (onlyReplace) return written;
+
const defaultPath = CLAUDE_DIR_MD;
fs.mkdirSync(path.join(targetDir, '.claude'), {recursive: true});
injectXdsBlock(path.join(targetDir, defaultPath), compressedIndex, {
diff --git a/packages/cli/src/commands/agent-docs.test.mjs b/packages/cli/src/commands/agent-docs.test.mjs
index e98c415223..f742624b95 100644
--- a/packages/cli/src/commands/agent-docs.test.mjs
+++ b/packages/cli/src/commands/agent-docs.test.mjs
@@ -110,6 +110,30 @@ describe('injectXdsBlock', () => {
expect(fs.existsSync(filePath)).toBe(false);
});
+ it('skips files without markers when onlyReplace is true', () => {
+ const filePath = path.join(tmpDir, 'test.md');
+ fs.writeFileSync(filePath, '# Existing content\n\nNo XDS markers here.\n');
+
+ const result = injectXdsBlock(filePath, '<!-- XDS:START -->\nnew\n<!-- XDS:END -->', {onlyReplace: true});
+
+ expect(result).toBe(false);
+ const content = fs.readFileSync(filePath, 'utf-8');
+ expect(content).not.toContain('<!-- XDS:START -->');
+ expect(content).toBe('# Existing content\n\nNo XDS markers here.\n');
+ });
+
+ it('replaces existing markers even when onlyReplace is true', () => {
+ const filePath = path.join(tmpDir, 'test.md');
+ fs.writeFileSync(filePath, 'before\n<!-- XDS:START -->\nold\n<!-- XDS:END -->\nafter\n');
+
+ const result = injectXdsBlock(filePath, '<!-- XDS:START -->\nnew\n<!-- XDS:END -->', {onlyReplace: true});
+
+ expect(result).toBe(true);
+ const content = fs.readFileSync(filePath, 'utf-8');
+ expect(content).toContain('new');
+ expect(content).not.toContain('old');
+ });
+
it('creates file when createIfMissing is true', () => {
const filePath = path.join(tmpDir, 'new.md');
@@ -375,6 +399,43 @@ describe('installAgentDocs', () => {
expect(written).toEqual(['custom/AGENT.md']);
expect(fs.existsSync(path.join(tmpDir, 'custom', 'AGENT.md'))).toBe(true);
});
+
+ it('onlyReplace: skips files without XDS markers', () => {
+ setupCorePackage(tmpDir);
+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nProject rules only.\n');
+
+ const written = installAgentDocs(tmpDir, {onlyReplace: true});
+
+ expect(written).toEqual([]);
+ const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+ expect(content).not.toContain('<!-- XDS:START -->');
+ expect(content).toBe('# Claude\n\nProject rules only.\n');
+ });
+
+ it('onlyReplace: updates files that have XDS markers', () => {
+ setupCorePackage(tmpDir, '2.0.0');
+ fs.writeFileSync(
+ path.join(tmpDir, 'CLAUDE.md'),
+ '# Claude\n\n<!-- XDS:START -->\nPLACEHOLDER_STALE_CONTENT\n<!-- XDS:END -->\n\nOther rules.\n',
+ );
+
+ const written = installAgentDocs(tmpDir, {onlyReplace: true});
+
+ expect(written).toEqual(['CLAUDE.md']);
+ const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+ expect(content).toContain('XDS v2.0.0');
+ expect(content).not.toContain('PLACEHOLDER_STALE_CONTENT');
+ expect(content).toContain('Other rules.');
+ });
+
+ it('onlyReplace: does not create default .claude/CLAUDE.md when nothing exists', () => {
+ setupCorePackage(tmpDir);
+
+ const written = installAgentDocs(tmpDir, {onlyReplace: true});
+
+ expect(written).toEqual([]);
+ expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
+ });
});
describe('discoverAgentDocs', () => {
diff --git a/packages/cli/src/commands/upgrade.mjs b/packages/cli/src/commands/upgrade.mjs
index 080fdf8e25..e7eb2dd19d 100644
--- a/packages/cli/src/commands/upgrade.mjs
+++ b/packages/cli/src/commands/upgrade.mjs
@@ -294,9 +294,11 @@ export function registerUpgrade(program) {
const existingDocs = discoverAgentDocs(process.cwd());
if (existingDocs.length > 0) {
try {
- const written = installAgentDocs(process.cwd());
- receipt.agentDocsRefreshed = true;
- if (!json) p.log.success(`Agent docs updated: ${written.join(', ')}`);
+ // onlyReplace: only update files that already have XDS markers.
+ // Don't inject into files that never had XDS content.
+ const written = installAgentDocs(process.cwd(), {onlyReplace: true});
+ receipt.agentDocsRefreshed = written.length > 0;
+ if (!json && written.length > 0) p.log.success(`Agent docs updated: ${written.join(', ')}`);
} catch {
if (!json) {
p.log.warn(