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.mjsindex 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 = falcontent.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.mjsindex 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.mjsindex 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(