An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): configurable agent docs with tool presets and lockfile-based command prefix (#874)
Cindy Zhang02c2b1375385
diff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjsindex 24448758f5..d21acdd160 100644--- a/packages/cli/src/commands/agent-docs.mjs+++ b/packages/cli/src/commands/agent-docs.mjs@@ -1,10 +1,18 @@/**- * @file agent-docs — Install/update AGENTS.md and CLAUDE.md+ * @file agent-docs — Install/update agent docs for AI coding tools** Generates a CLI cheat sheet from actual command metadata and injects- * it into AGENTS.md and/or CLAUDE.md. Format optimized for AI coding- * agents (Claude, Copilot, Cursor): one line per command, copy-pasteable,- * minimal tokens.+ * it into agent doc files. Supports multiple tools with auto-detection:+ *+ * - Claude Code: CLAUDE.md (root) or .claude/CLAUDE.md+ * - Cursor: .cursorrules+ * - Codex/generic: AGENTS.md+ *+ * Auto-detect: discovers existing files and updates them in place.+ * Default (no existing files): creates .claude/CLAUDE.md.+ *+ * --agent <tool>: target a specific tool preset (claude, cursor, codex, all)+ * --agent-docs-path <path>: explicit file path(s)*/import * as fs from 'node:fs';@@ -15,10 +23,67 @@ import {discoverComponents} from '../lib/component-discovery.mjs';const AGENTS_MD = 'AGENTS.md';const CLAUDE_MD = 'CLAUDE.md';+const CLAUDE_DIR_MD = path.join('.claude', 'CLAUDE.md');const XDS_MARKER_START = '<!-- XDS:START -->';const XDS_MARKER_END = '<!-- XDS:END -->';+/**+ * Agent tool presets — maps tool names to their file search paths.+ * Order matters: first existing file wins, last entry is the default (created if none exist).+ */+const AGENT_PRESETS = {+ claude: [CLAUDE_MD, CLAUDE_DIR_MD],+ cursor: ['.cursorrules', AGENTS_MD],+ codex: [AGENTS_MD],+};++/**+ * Find all existing agent doc files in a directory.+ * Searches all known locations (AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, .cursorrules).+ * @param {string} targetDir+ * @returns {string[]} Relative paths of existing agent doc files+ */+export function discoverAgentDocs(targetDir) {+ const allPaths = [AGENTS_MD, CLAUDE_MD, CLAUDE_DIR_MD, '.cursorrules'];+ return allPaths.filter(p => fs.existsSync(path.join(targetDir, p)));+}++/**+ * Resolve which file(s) to write for a given agent tool preset.+ * Searches for existing files first, falls back to default creation path.+ *+ * @param {string} targetDir+ * @param {string} agent - Preset name: 'claude', 'cursor', 'codex', 'all'+ * @returns {{inject: string[], create: string[]}} Files to inject into vs create fresh+ */+export function resolveAgentPaths(targetDir, agent) {+ if (agent === 'all') {+ // Inject into all existing files, create defaults for each tool+ const existing = discoverAgentDocs(targetDir);+ if (existing.length > 0) {+ return {inject: existing, create: []};+ }+ // Nothing exists — create default for each tool+ return {inject: [], create: [AGENTS_MD, CLAUDE_DIR_MD]};+ }++ const searchPaths = AGENT_PRESETS[agent];+ if (!searchPaths) {+ return {inject: [], create: [AGENTS_MD]};+ }++ // Find first existing file from search order+ for (const p of searchPaths) {+ if (fs.existsSync(path.join(targetDir, p))) {+ return {inject: [p], create: []};+ }+ }++ // None found — create the last entry (default location)+ return {inject: [], create: [searchPaths[searchPaths.length - 1]]};+}+/*** Generate the agent cheat sheet from live CLI metadata.*@@ -141,10 +206,9 @@ export function injectXdsBlock(filePath, compressedIndex, {createIfMissing = fal* Inject or update XDS section in AGENTS.md.* Always creates the file if it doesn't exist.*/-export function injectAgentsMd(targetDir, version, {zh = false, lang, runPrefix} = {}) {+export function injectAgentsMd(targetDir, version, {zh = false, lang} = {}) {const agentsPath = path.join(targetDir, AGENTS_MD);- const prefix = runPrefix ?? getRunPrefix(targetDir);- const compressedIndex = generateCompressedIndex(version, {coreDir: findCoreDir(targetDir), runPrefix: prefix});+ const compressedIndex = generateCompressedIndex(version, {coreDir: findCoreDir(targetDir)});injectXdsBlock(agentsPath, compressedIndex, {createIfMissing: true,header: `# AGENTS.md\n\nProject-specific guidance for AI coding agents.`,@@ -157,10 +221,9 @@ export function injectAgentsMd(targetDir, version, {zh = false, lang, runPrefix}** @returns {boolean} Whether the file was written*/-export function injectClaudeMd(targetDir, version, {zh = false, lang, runPrefix} = {}) {+export function injectClaudeMd(targetDir, version, {zh = false, lang} = {}) {const claudePath = path.join(targetDir, CLAUDE_MD);- const prefix = runPrefix ?? getRunPrefix(targetDir);- const compressedIndex = generateCompressedIndex(version, {coreDir: findCoreDir(targetDir), runPrefix: prefix});+ const compressedIndex = generateCompressedIndex(version, {coreDir: findCoreDir(targetDir)});return injectXdsBlock(claudePath, compressedIndex);}@@ -196,56 +259,118 @@ export function removeXdsBlock(filePath, {deleteIfEmpty = false} = {}) {}/**- * Remove XDS section from AGENTS.md and CLAUDE.md.+ * Remove XDS section from all known agent doc files.*/export function removeAgentDocs(targetDir) {- const agentsPath = path.join(targetDir, AGENTS_MD);- const claudePath = path.join(targetDir, CLAUDE_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}`);+ const allPaths = discoverAgentDocs(targetDir);++ for (const p of allPaths) {+ const filePath = path.join(targetDir, p);+ // Delete if empty for files we created (AGENTS.md, .claude/CLAUDE.md)+ const deleteIfEmpty = p === AGENTS_MD || p === CLAUDE_DIR_MD;+ if (removeXdsBlock(filePath, {deleteIfEmpty})) {+ if (!fs.existsSync(filePath)) {+ console.log(`✓ Removed empty ${p}`);+ } else {+ console.log(`✓ Removed XDS section from ${p}`);+ }}}-- if (removeXdsBlock(claudePath)) {- console.log(`✓ Removed XDS section from ${CLAUDE_MD}`);- }}/*** Programmatic entry point for installing agent docs.- * Used by the init wizard.+ * Used by the init wizard, upgrade command, and agent-docs command.*- * Strategy:- * - If CLAUDE.md exists, inject there (don't create AGENTS.md)- * - If only AGENTS.md exists (or neither), inject into AGENTS.md- * - If both exist, inject into both+ * Strategy (when no agent/paths specified):+ * - Discover all existing agent doc files and update them+ * - If nothing found, create .claude/CLAUDE.md as default+ *+ * @param {string} targetDir+ * @param {object} [options]+ * @param {boolean} [options.zh]+ * @param {string} [options.lang]+ * @param {string} [options.agent] - Tool preset: 'claude', 'cursor', 'codex', 'all'+ * @param {string[]} [options.paths] - Explicit paths (overrides agent/auto-detect)+ * @returns {string[]} List of files written*/-export function installAgentDocs(targetDir, {zh = false, lang} = {}) {+export function installAgentDocs(targetDir, {zh = false, lang, agent, paths} = {}) {const coreDir = findCoreDir(targetDir);const version = getXdsVersion(coreDir);const runPrefix = getRunPrefix(targetDir);- const hasClaudeMd = fs.existsSync(path.join(targetDir, CLAUDE_MD));- const hasAgentsMd = fs.existsSync(path.join(targetDir, AGENTS_MD));+ const compressedIndex = generateCompressedIndex(version, {coreDir, zh, lang, runPrefix});+ const written = [];++ // Explicit paths override everything+ if (paths && paths.length > 0) {+ for (const p of paths) {+ const filePath = path.join(targetDir, p);+ const dir = path.dirname(filePath);+ if (dir !== targetDir) {+ fs.mkdirSync(dir, {recursive: true});+ }+ injectXdsBlock(filePath, compressedIndex, {+ createIfMissing: true,+ header: `# ${path.basename(p, path.extname(p))}\n\nProject-specific guidance for AI coding agents.`,+ });+ written.push(p);+ }+ return written;+ }- if (hasClaudeMd) {- injectClaudeMd(targetDir, version, {zh, lang, runPrefix});- if (hasAgentsMd) {- injectAgentsMd(targetDir, version, {zh, lang, runPrefix});+ // Agent preset+ if (agent) {+ const {inject, create} = resolveAgentPaths(targetDir, agent);+ for (const p of inject) {+ injectXdsBlock(path.join(targetDir, p), compressedIndex);+ written.push(p);}- } else {- injectAgentsMd(targetDir, version, {zh, lang, runPrefix});+ for (const p of create) {+ const filePath = path.join(targetDir, p);+ const dir = path.dirname(filePath);+ if (dir !== targetDir) {+ fs.mkdirSync(dir, {recursive: true});+ }+ injectXdsBlock(filePath, compressedIndex, {+ createIfMissing: true,+ header: `# ${path.basename(p, path.extname(p))}\n\nProject-specific guidance for AI coding agents.`,+ });+ written.push(p);+ }+ return written;}++ // Auto-detect: update all existing agent doc files+ const existing = discoverAgentDocs(targetDir);++ if (existing.length > 0) {+ for (const p of existing) {+ injectXdsBlock(path.join(targetDir, p), compressedIndex);+ written.push(p);+ }+ return written;+ }++ // Nothing exists — create .claude/CLAUDE.md as default+ const defaultPath = CLAUDE_DIR_MD;+ fs.mkdirSync(path.join(targetDir, '.claude'), {recursive: true});+ injectXdsBlock(path.join(targetDir, defaultPath), compressedIndex, {+ createIfMissing: true,+ header: `# CLAUDE.md\n\nProject-specific guidance for AI coding agents.`,+ });+ written.push(defaultPath);+ return written;}+const VALID_AGENTS = ['claude', 'cursor', 'codex', 'all'];+export function registerAgentDocs(program) {program.command('agent-docs')- .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')+ .description('Install/update XDS component index for AI coding agents')+ .option('--remove', 'Remove XDS section from all agent doc files')+ .option('--agent <tool>', 'Target tool: claude, cursor, codex, all')+ .option('--agent-docs-path <path...>', 'Explicit file path(s) to write to').action(options => {const targetDir = process.cwd();const coreDir = findCoreDir(targetDir);@@ -260,29 +385,36 @@ export function registerAgentDocs(program) {return;}- const runPrefix = getRunPrefix(targetDir);+ // Validate --agent+ if (options.agent && !VALID_AGENTS.includes(options.agent)) {+ console.error(`Error: Unknown agent "${options.agent}". Valid: ${VALID_AGENTS.join(', ')}`);+ process.exitCode = 1;+ return;+ }+console.log(`\n📚 Installing XDS agent docs (v${version})...\n`);- const hasClaudeMd = fs.existsSync(path.join(targetDir, CLAUDE_MD));- const hasAgentsMd = fs.existsSync(path.join(targetDir, AGENTS_MD));- const targets = [];-- if (hasClaudeMd) {- injectClaudeMd(targetDir, version, {zh, lang, runPrefix});- console.log(`✓ Injected compressed index into ${CLAUDE_MD}`);- targets.push(CLAUDE_MD);- if (hasAgentsMd) {- injectAgentsMd(targetDir, version, {zh, lang, runPrefix});- console.log(`✓ Injected compressed index into ${AGENTS_MD}`);- targets.push(AGENTS_MD);- }- } else {- injectAgentsMd(targetDir, version, {zh, lang, runPrefix});- console.log(`✓ Injected compressed index into ${AGENTS_MD}`);- targets.push(AGENTS_MD);- }+ // Collect explicit paths from --agent-docs-path (commander parses variadic as array or single)+ const explicitPaths = options.agentDocsPath+ ? Array.isArray(options.agentDocsPath)+ ? options.agentDocsPath+ : [options.agentDocsPath]+ : undefined;+ const targets = installAgentDocs(targetDir, {+ zh,+ lang,+ agent: options.agent,+ paths: explicitPaths,+ });++ const runPrefix = getRunPrefix(targetDir);const run = `${runPrefix} xds`;++ for (const t of targets) {+ console.log(`✓ ${t}`);+ }+console.log(`✅ XDS agent docs installed!diff --git a/packages/cli/src/commands/agent-docs.test.mjs b/packages/cli/src/commands/agent-docs.test.mjsindex 896e5e650c..1ce6b2589d 100644--- a/packages/cli/src/commands/agent-docs.test.mjs+++ b/packages/cli/src/commands/agent-docs.test.mjs@@ -11,6 +11,8 @@ import {injectXdsBlock,removeAgentDocs,removeXdsBlock,+ discoverAgentDocs,+ resolveAgentPaths,} from './agent-docs.mjs';let tmpDir;@@ -284,37 +286,146 @@ describe('installAgentDocs', () => {);}- it('creates AGENTS.md when neither file exists', () => {+ it('creates .claude/CLAUDE.md when no agent docs exist', () => {setupCorePackage(tmpDir);- installAgentDocs(tmpDir);+ const written = installAgentDocs(tmpDir);- expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);- expect(fs.existsSync(path.join(tmpDir, 'CLAUDE.md'))).toBe(false);+ expect(written).toEqual(['.claude/CLAUDE.md']);+ expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(true);+ expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);+ const content = fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8');+ expect(content).toContain('<!-- XDS:START -->');});- it('injects into CLAUDE.md and skips creating AGENTS.md when only CLAUDE.md exists', () => {+ it('injects into CLAUDE.md at root when it exists', () => {setupCorePackage(tmpDir);fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nProject rules.\n');- installAgentDocs(tmpDir);+ const written = installAgentDocs(tmpDir);+ expect(written).toEqual(['CLAUDE.md']);expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');expect(claudeContent).toContain('<!-- XDS:START -->');expect(claudeContent).toContain('Project rules.');});- it('injects into both when both files exist', () => {+ it('injects into all existing agent doc files', () => {setupCorePackage(tmpDir);fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n\nAgent rules.\n');fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nClaude rules.\n');- installAgentDocs(tmpDir);+ const written = installAgentDocs(tmpDir);+ expect(written).toContain('AGENTS.md');+ expect(written).toContain('CLAUDE.md');const agentsContent = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');expect(agentsContent).toContain('<!-- XDS:START -->');expect(claudeContent).toContain('<!-- XDS:START -->');});++ it('updates existing .claude/CLAUDE.md', () => {+ setupCorePackage(tmpDir);+ fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});+ fs.writeFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), '# Project\n\nExisting content.\n');++ const written = installAgentDocs(tmpDir);++ expect(written).toEqual(['.claude/CLAUDE.md']);+ const content = fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8');+ expect(content).toContain('Existing content.');+ expect(content).toContain('<!-- XDS:START -->');+ });++ it('respects --agent claude preset: finds existing CLAUDE.md', () => {+ setupCorePackage(tmpDir);+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nRules.\n');++ const written = installAgentDocs(tmpDir, {agent: 'claude'});++ expect(written).toEqual(['CLAUDE.md']);+ });++ it('respects --agent claude preset: creates .claude/CLAUDE.md when nothing exists', () => {+ setupCorePackage(tmpDir);++ const written = installAgentDocs(tmpDir, {agent: 'claude'});++ expect(written).toEqual(['.claude/CLAUDE.md']);+ expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(true);+ });++ it('respects --agent codex preset: creates AGENTS.md', () => {+ setupCorePackage(tmpDir);++ const written = installAgentDocs(tmpDir, {agent: 'codex'});++ expect(written).toEqual(['AGENTS.md']);+ expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);+ });++ it('respects explicit --paths', () => {+ setupCorePackage(tmpDir);++ const written = installAgentDocs(tmpDir, {paths: ['custom/AGENT.md']});++ expect(written).toEqual(['custom/AGENT.md']);+ expect(fs.existsSync(path.join(tmpDir, 'custom', 'AGENT.md'))).toBe(true);+ });+});++describe('discoverAgentDocs', () => {+ it('finds AGENTS.md and CLAUDE.md at root', () => {+ fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '');+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '');++ const found = discoverAgentDocs(tmpDir);++ expect(found).toContain('AGENTS.md');+ expect(found).toContain('CLAUDE.md');+ });++ it('finds .claude/CLAUDE.md', () => {+ fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});+ fs.writeFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), '');++ const found = discoverAgentDocs(tmpDir);++ expect(found).toContain('.claude/CLAUDE.md');+ });++ it('returns empty when nothing exists', () => {+ expect(discoverAgentDocs(tmpDir)).toEqual([]);+ });+});++describe('resolveAgentPaths', () => {+ it('claude preset finds existing CLAUDE.md at root', () => {+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '');+ const result = resolveAgentPaths(tmpDir, 'claude');+ expect(result).toEqual({inject: ['CLAUDE.md'], create: []});+ });++ it('claude preset falls back to .claude/CLAUDE.md', () => {+ const result = resolveAgentPaths(tmpDir, 'claude');+ expect(result).toEqual({inject: [], create: ['.claude/CLAUDE.md']});+ });++ it('all preset discovers existing files', () => {+ fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '');+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '');+ const result = resolveAgentPaths(tmpDir, 'all');+ expect(result.inject).toContain('AGENTS.md');+ expect(result.inject).toContain('CLAUDE.md');+ expect(result.create).toEqual([]);+ });++ it('all preset creates defaults when nothing exists', () => {+ const result = resolveAgentPaths(tmpDir, 'all');+ expect(result.inject).toEqual([]);+ expect(result.create).toContain('AGENTS.md');+ expect(result.create).toContain('.claude/CLAUDE.md');+ });});diff --git a/packages/cli/src/commands/init.mjs b/packages/cli/src/commands/init.mjsindex 179c6dc86e..2597f87563 100644--- a/packages/cli/src/commands/init.mjs+++ b/packages/cli/src/commands/init.mjs@@ -30,13 +30,19 @@ function isCancel(value) {// ─── Feature: agents ─────────────────────────────────────────────────────────-function runAgents(targetDir, {interactive = true} = {}) {+function runAgents(targetDir, {interactive = true, agent, agentDocsPath} = {}) {try {- installAgentDocs(targetDir);+ const paths = agentDocsPath+ ? Array.isArray(agentDocsPath)+ ? agentDocsPath+ : [agentDocsPath]+ : undefined;+ const written = installAgentDocs(targetDir, {agent, paths});+ const summary = written.join(', ');if (interactive) {- p.log.success('AI agent docs installed');+ p.log.success(`AI agent docs installed → ${summary}`);} else {- console.log('✓ AI agent docs installed');+ console.log(`✓ AI agent docs installed → ${summary}`);}} catch {const msg = 'Could not install agent docs. Try again with `npx xds init --features agents`.';@@ -144,7 +150,9 @@ export function registerInit(program) {.description('Initialize XDS in your project').option('--features <list>', 'Comma-separated features to install (agents, theme, template)').option('--all', 'Install all features, no prompts')- .option('--remove-agents', 'Remove AI agent docs from AGENTS.md/CLAUDE.md')+ .option('--remove-agents', 'Remove AI agent docs from all agent doc files')+ .option('--agent <tool>', 'Target AI tool for agent docs: claude, cursor, codex, all')+ .option('--agent-docs-path <path...>', 'Explicit file path(s) for agent docs').action(async (options) => {const targetDir = process.cwd();@@ -169,7 +177,11 @@ export function registerInit(program) {}for (const feature of features) {- if (feature === 'agents') runAgents(targetDir, {interactive: false});+ if (feature === 'agents') runAgents(targetDir, {+ interactive: false,+ agent: options.agent,+ agentDocsPath: options.agentDocsPath,+ });if (feature === 'theme') await runTheme({interactive: false});if (feature === 'template') await runTemplate(targetDir, {interactive: false});}