An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): update agent-docs block, add CLAUDE.md support, remove theme command (#458)
Cindy Zhang7832288366a1
diff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjsindex fe55c274b9..c95780738d 100644--- a/packages/cli/src/commands/agent-docs.mjs+++ b/packages/cli/src/commands/agent-docs.mjs@@ -1,7 +1,7 @@/**- * @file agent-docs command — Install/update AGENTS.md+ * @file agent-docs command — Install/update AGENTS.md and CLAUDE.md*- * Injects a compressed XDS component index into AGENTS.md.+ * Injects a compressed XDS component index into AGENTS.md and/or CLAUDE.md.* Component docs are served via `npx xds component <name>` instead of* being copied into the project.*/@@ -11,12 +11,13 @@ import * as path from 'node:path';import {findCoreDir, CLI_ROOT} from '../utils/paths.mjs';const AGENTS_MD = 'AGENTS.md';+const CLAUDE_MD = 'CLAUDE.md';const XDS_MARKER_START = '<!-- XDS:START -->';const XDS_MARKER_END = '<!-- XDS:END -->';/**- * Compressed index for AGENTS.md.+ * Compressed index for agent docs.* Directs agents to use CLI commands for retrieval.*/export function generateCompressedIndex(version) {@@ -27,11 +28,8 @@ export function generateCompressedIndex(version) {|npx xds docs principles Design rules, anti-patterns, StyleX patterns|npx xds docs tokens Token reference (spacing, color, radius, type)|npx xds docs theme Theme system: XDSTheme, custom themes, overrides, nesting-|npx xds swizzle <Name> Copy component source for customization-|npx xds theme Scaffold a custom theme (interactive)-|npx xds theme --list List existing themes in the project|npx xds template <name> [path] Scaffold page (blank, table, login)-|npx xds swizzle <Name> --gap "<reason>" Swizzle + file gap report+|npx xds swizzle <Name> --gap "<reason>" Copy component source for customization + file gap report|npx xds gap-report --component <Name> --category <cat> --reason "<why>" File gap without swizzle|RULE: When swizzling to unblock yourself, ALWAYS use --gap to explain what capability was missing.${XDS_MARKER_END}`;@@ -54,16 +52,18 @@ export function getXdsVersion(coreDir) {}/**- * Inject or update XDS section in AGENTS.md.+ * 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 createIfMissing is true and the file doesn't exist, creates it with a header.+ *+ * @returns {boolean} Whether the file was written*/-export function injectAgentsMd(targetDir, version) {- const agentsPath = path.join(targetDir, AGENTS_MD);- const compressedIndex = generateCompressedIndex(version);-+export function injectXdsBlock(filePath, compressedIndex, {createIfMissing = false, header = ''} = {}) {let content = '';- if (fs.existsSync(agentsPath)) {- content = fs.readFileSync(agentsPath, 'utf-8');+ if (fs.existsSync(filePath)) {+ content = fs.readFileSync(filePath, 'utf-8');const startIdx = content.indexOf(XDS_MARKER_START);const endIdx = content.indexOf(XDS_MARKER_END);@@ -76,44 +76,90 @@ export function injectAgentsMd(targetDir, version) {} else {content = content.trimEnd() + '\n\n' + compressedIndex + '\n';}+ } else if (createIfMissing) {+ content = header ? header + '\n\n' + compressedIndex + '\n' : compressedIndex + '\n';} else {- content = `# AGENTS.md+ return false;+ }++ fs.writeFileSync(filePath, content);+ return true;+}++/**+ * Inject or update XDS section in AGENTS.md.+ * Always creates the file if it doesn't exist.+ */+export function injectAgentsMd(targetDir, version) {+ const agentsPath = path.join(targetDir, AGENTS_MD);+ const compressedIndex = generateCompressedIndex(version);+ injectXdsBlock(agentsPath, compressedIndex, {+ createIfMissing: true,+ header: `# AGENTS.md\n\nProject-specific guidance for AI coding agents.`,+ });+}++/**+ * Inject or update XDS section in CLAUDE.md.+ * Only injects if CLAUDE.md already exists.+ *+ * @returns {boolean} Whether the file was written+ */+export function injectClaudeMd(targetDir, version) {+ const claudePath = path.join(targetDir, CLAUDE_MD);+ const compressedIndex = generateCompressedIndex(version);+ return injectXdsBlock(claudePath, compressedIndex);+}++/**+ * Remove XDS section from a file.+ * If the file becomes empty (only boilerplate header remains), deletes it.+ *+ * @returns {boolean} Whether the XDS section was found and removed+ */+export function removeXdsBlock(filePath, {deleteIfEmpty = false} = {}) {+ if (!fs.existsSync(filePath)) return false;++ let content = fs.readFileSync(filePath, 'utf-8');+ const startIdx = content.indexOf(XDS_MARKER_START);+ const endIdx = content.indexOf(XDS_MARKER_END);-Project-specific guidance for AI coding agents.+ if (startIdx === -1 || endIdx === -1) return false;-${compressedIndex}-`;+ const before = content.slice(0, startIdx).trimEnd();+ const after = content.slice(endIdx + XDS_MARKER_END.length).trimStart();+ content = before + (after ? '\n\n' + after : '') + '\n';++ if (deleteIfEmpty) {+ const stripped = content.replace(/^#.*\n+.*guidance.*\n*/m, '').trim();+ if (!stripped) {+ fs.unlinkSync(filePath);+ return true;+ }}- fs.writeFileSync(agentsPath, content);+ fs.writeFileSync(filePath, content);+ return true;}/**- * Remove XDS section from AGENTS.md.+ * Remove XDS section from AGENTS.md and CLAUDE.md.*/export function removeAgentDocs(targetDir) {const agentsPath = path.join(targetDir, AGENTS_MD);+ const claudePath = path.join(targetDir, CLAUDE_MD);- if (fs.existsSync(agentsPath)) {- let content = fs.readFileSync(agentsPath, 'utf-8');- const startIdx = content.indexOf(XDS_MARKER_START);- const endIdx = content.indexOf(XDS_MARKER_END);-- if (startIdx !== -1 && endIdx !== -1) {- const before = content.slice(0, startIdx).trimEnd();- const after = content.slice(endIdx + XDS_MARKER_END.length).trimStart();- content = before + (after ? '\n\n' + after : '') + '\n';-- const stripped = content.replace(/^#.*\n+.*guidance.*\n*/m, '').trim();- if (!stripped) {- fs.unlinkSync(agentsPath);- console.log(`✓ Removed empty ${AGENTS_MD}`);- } else {- fs.writeFileSync(agentsPath, content);- console.log(`✓ Removed XDS section from ${AGENTS_MD}`);- }+ if (removeXdsBlock(agentsPath, {deleteIfEmpty: true})) {+ if (!fs.existsSync(agentsPath)) {+ console.log(`✓ Removed empty ${AGENTS_MD}`);+ } else {+ console.log(`✓ Removed XDS section from ${AGENTS_MD}`);}}++ if (removeXdsBlock(claudePath)) {+ console.log(`✓ Removed XDS section from ${CLAUDE_MD}`);+ }}/**@@ -124,13 +170,14 @@ export function installAgentDocs(targetDir) {const coreDir = findCoreDir(targetDir);const version = getXdsVersion(coreDir);injectAgentsMd(targetDir, version);+ injectClaudeMd(targetDir, version);}export function registerAgentDocs(program) {program.command('agent-docs')- .description('Install/update XDS component index in AGENTS.md')- .option('--remove', 'Remove XDS section from AGENTS.md')+ .description('Install/update XDS component index in AGENTS.md (and CLAUDE.md if present)')+ .option('--remove', 'Remove XDS section from AGENTS.md and CLAUDE.md').action(options => {const targetDir = process.cwd();const coreDir = findCoreDir(targetDir);@@ -148,11 +195,15 @@ export function registerAgentDocs(program) {injectAgentsMd(targetDir, version);console.log(`✓ Injected compressed index into ${AGENTS_MD}`);+ if (injectClaudeMd(targetDir, version)) {+ console.log(`✓ Injected compressed index into ${CLAUDE_MD}`);+ }+console.log(`✅ XDS agent docs installed!Your AI coding agent will now:- • See the XDS component index in AGENTS.md+ • See the XDS component index in AGENTS.md${fs.existsSync(path.join(targetDir, CLAUDE_MD)) ? ' and CLAUDE.md' : ''}• Run \`npx xds component <name>\` to read detailed docs• Run \`npx xds docs principles\` for design principles• Run \`npx xds docs tokens\` for design token referencediff --git a/packages/cli/src/commands/agent-docs.test.mjs b/packages/cli/src/commands/agent-docs.test.mjsindex ba9a24d597..735fbe2bdf 100644--- a/packages/cli/src/commands/agent-docs.test.mjs+++ b/packages/cli/src/commands/agent-docs.test.mjs@@ -6,7 +6,10 @@ import {generateCompressedIndex,getXdsVersion,injectAgentsMd,+ injectClaudeMd,+ injectXdsBlock,removeAgentDocs,+ removeXdsBlock,} from './agent-docs.mjs';let tmpDir;@@ -27,6 +30,11 @@ describe('generateCompressedIndex', () => {expect(result).toContain('<!-- XDS:START -->');expect(result).toContain('<!-- XDS:END -->');});++ it('does not include theme command references', () => {+ const result = generateCompressedIndex('1.0.0');+ expect(result).not.toContain('npx xds theme');+ });});describe('getXdsVersion', () => {@@ -42,6 +50,56 @@ describe('getXdsVersion', () => {});});+describe('injectXdsBlock', () => {+ it('injects into an existing file without markers', () => {+ const filePath = path.join(tmpDir, 'test.md');+ fs.writeFileSync(filePath, '# Existing content\n');++ const result = injectXdsBlock(filePath, '<!-- XDS:START -->\nnew\n<!-- XDS:END -->');++ expect(result).toBe(true);+ const content = fs.readFileSync(filePath, 'utf-8');+ expect(content).toContain('# Existing content');+ expect(content).toContain('<!-- XDS:START -->');+ });++ it('replaces existing markers', () => {+ const filePath = path.join(tmpDir, 'test.md');+ fs.writeFileSync(filePath, 'before\n<!-- XDS:START -->\nold\n<!-- XDS:END -->\nafter\n');++ injectXdsBlock(filePath, '<!-- XDS:START -->\nnew\n<!-- XDS:END -->');++ const content = fs.readFileSync(filePath, 'utf-8');+ expect(content).toContain('new');+ expect(content).not.toContain('old');+ expect(content).toContain('before');+ expect(content).toContain('after');+ });++ it('returns false and does not create file when createIfMissing is false', () => {+ const filePath = path.join(tmpDir, 'nonexistent.md');++ const result = injectXdsBlock(filePath, '<!-- XDS:START -->\ncontent\n<!-- XDS:END -->');++ expect(result).toBe(false);+ expect(fs.existsSync(filePath)).toBe(false);+ });++ it('creates file when createIfMissing is true', () => {+ const filePath = path.join(tmpDir, 'new.md');++ const result = injectXdsBlock(filePath, '<!-- XDS:START -->\ncontent\n<!-- XDS:END -->', {+ createIfMissing: true,+ header: '# Header',+ });++ expect(result).toBe(true);+ const content = fs.readFileSync(filePath, 'utf-8');+ expect(content).toContain('# Header');+ expect(content).toContain('<!-- XDS:START -->');+ });+});+describe('injectAgentsMd', () => {it('creates new AGENTS.md when none exists', () => {injectAgentsMd(tmpDir, '1.0.0');@@ -91,6 +149,47 @@ Existing agent docs.});});+describe('injectClaudeMd', () => {+ it('injects into existing CLAUDE.md', () => {+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude Config\n\nExisting rules.\n');++ const result = injectClaudeMd(tmpDir, '1.0.0');++ expect(result).toBe(true);+ const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');+ expect(content).toContain('# Claude Config');+ expect(content).toContain('Existing rules.');+ expect(content).toContain('<!-- XDS:START -->');+ expect(content).toContain('[XDS v1.0.0]');+ });++ it('does not create CLAUDE.md when it does not exist', () => {+ const result = injectClaudeMd(tmpDir, '1.0.0');++ expect(result).toBe(false);+ expect(fs.existsSync(path.join(tmpDir, 'CLAUDE.md'))).toBe(false);+ });++ it('updates existing markers in CLAUDE.md', () => {+ const existing = `# Claude Config++<!-- XDS:START -->+old content+<!-- XDS:END -->++Other rules.+`;+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), existing);++ injectClaudeMd(tmpDir, '2.0.0');++ const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');+ expect(content).toContain('[XDS v2.0.0]');+ expect(content).not.toContain('old content');+ expect(content).toContain('Other rules.');+ });+});+describe('removeAgentDocs', () => {it('removes XDS section from AGENTS.md', () => {const content = `# My Project@@ -131,4 +230,23 @@ XDS index stuffexpect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);});++ it('removes XDS section from CLAUDE.md when present', () => {+ fs.writeFileSync(+ path.join(tmpDir, 'AGENTS.md'),+ '# AGENTS.md\n\n<!-- XDS:START -->\nstuff\n<!-- XDS:END -->\n',+ );+ fs.writeFileSync(+ path.join(tmpDir, 'CLAUDE.md'),+ '# Claude\n\nRules.\n\n<!-- XDS:START -->\nstuff\n<!-- XDS:END -->\n\nMore rules.\n',+ );+ vi.spyOn(console, 'log').mockImplementation(() => {});++ removeAgentDocs(tmpDir);++ const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');+ expect(claudeContent).toContain('Rules.');+ expect(claudeContent).toContain('More rules.');+ expect(claudeContent).not.toContain('<!-- XDS:START -->');+ });});diff --git a/packages/cli/src/commands/init.mjs b/packages/cli/src/commands/init.mjsindex e132191e2d..e929703545 100644--- a/packages/cli/src/commands/init.mjs+++ b/packages/cli/src/commands/init.mjs@@ -4,18 +4,16 @@* Orchestrates the full XDS setup flow using @clack/prompts:* 1. Intro* 2. Agent docs installation- * 3. Theme selection- * 4. Swizzle awareness- * 5. Template selection- * 6. Success outro+ * 3. Swizzle awareness+ * 4. Template selection+ * 5. Success outro*/import * as p from '@clack/prompts';import * as path from 'node:path';import * as fs from 'node:fs';-import {findCoreDir, CLI_ROOT} from '../utils/paths.mjs';+import {CLI_ROOT} from '../utils/paths.mjs';import {installAgentDocs} from './agent-docs.mjs';-import {discoverThemes, writeThemeConfig} from './theme.mjs';import {listTemplates} from './template.mjs';function isCancel(value) {@@ -61,51 +59,13 @@ export function registerInit(program) {}}- // Step 3: Theme Selection- const coreDir = findCoreDir(process.cwd());-- if (coreDir) {- const themes = discoverThemes(coreDir);-- if (themes.length > 0) {- const themeOptions = [- ...themes.map(t => ({- value: t.exportName,- label:- t.name === 'default'- ? 'Default — Blue accent, system fonts'- : t.name === 'neutral'- ? 'Neutral — Grayscale, shadcn-inspired'- : t.name,- })),- {value: 'skip', label: 'Skip — Configure later'},- ];-- const themeChoice = isCancel(- await p.select({- message: 'Choose a theme:',- options: themeOptions,- }),- );-- if (themeChoice !== 'skip') {- writeThemeConfig(process.cwd(), themeChoice);- p.log.success(`Theme set to ${themeChoice}`);- p.note(- `import { XDSTheme, ${themeChoice} } from '@xds/core/theme';\n\n<XDSTheme theme={${themeChoice}}>\n {children}\n</XDSTheme>`,- 'Add to your root layout',- );- }- }- }-- // Step 4: Swizzle Awareness+ // Step 3: Swizzle Awarenessp.note('You can customize any component with:\n npx xds swizzle XDSButton\n npx xds swizzle --list','Component Customization',);- // Step 5: Template Selection+ // Step 4: Template Selectionconst templates = listTemplates();if (templates.length > 0) {@@ -151,7 +111,7 @@ export function registerInit(program) {}}- // Step 6: Success+ // Step 5: Successp.outro('XDS initialized!');console.log('');diff --git a/packages/cli/src/index.mjs b/packages/cli/src/index.mjsindex ce7c6ed460..cdda8192e4 100644--- a/packages/cli/src/index.mjs+++ b/packages/cli/src/index.mjs@@ -1,7 +1,7 @@/*** @file XDS CLI — Commander program setup*- * Registers all commands: init, swizzle, agent-docs, component, docs, template, theme.+ * Registers all commands: init, swizzle, agent-docs, component, docs, template.*/import {Command} from 'commander';@@ -11,7 +11,6 @@ import {registerAgentDocs} from './commands/agent-docs.mjs';import {registerComponent} from './commands/component.mjs';import {registerDocs} from './commands/docs.mjs';import {registerTemplate} from './commands/template.mjs';-import {registerTheme} from './commands/theme.mjs';import {registerGapReport} from './commands/gap-report.mjs';export const program = new Command();@@ -31,7 +30,6 @@ registerDocs(program);registerSwizzle(program);registerAgentDocs(program);registerTemplate(program);-registerTheme(program);registerGapReport(program);// Hidden command used by package.json postinstall scripts@@ -51,7 +49,6 @@ program│ npx xds agent-docs Install AI agent docs ││ npx xds component Browse component docs ││ npx xds docs Design system reference │- │ npx xds theme Apply a theme ││ npx xds swizzle Customize a component ││ npx xds template Add a page template ││ │