An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): generate agent cheat sheet from live CLI metadata (#640)
Joeyb1202f56c762
diff --git a/CLAUDE.md b/CLAUDE.mdindex 72fe1bf765..b181ba85b3 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -119,3 +119,15 @@ Look for `<!-- SYNC: ... -->` comments and `SYNC:` in file headers as reminders.|VERIFY: node internal/stylex-capabilities/scan.mjs<!-- STYLEX-CAPS:END -->++<!-- XDS-CLI:START -->+XDS v0.0.4|Always run npx xds component <Name> before writing XDS component code.+npx xds component <Name> props, usage, examples for any component+npx xds component --list 95 components by category+npx xds template <name> [path] scaffold page (blank, login, table)+npx xds swizzle <Name> eject component source (use --gap to report why)+npx xds upgrade --apply run version migration codemods+--detail compact|brief less output | --lang dense|zh translation+RULE: after @xds/core bump, always run npx xds upgrade --apply+RULE: when swizzling, always use --gap to report missing capabilities+<!-- XDS-CLI:END -->diff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjsindex 00ad6ca072..0fadad73aa 100644--- a/packages/cli/src/commands/agent-docs.mjs+++ b/packages/cli/src/commands/agent-docs.mjs@@ -1,14 +1,16 @@/**- * @file agent-docs command — Install/update AGENTS.md and CLAUDE.md+ * @file agent-docs — Install/update AGENTS.md and CLAUDE.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.+ * 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.*/import * as fs from 'node:fs';import * as path from 'node:path';import {findCoreDir, CLI_ROOT} from '../utils/paths.mjs';+import {discoverComponents} from '../lib/component-discovery.mjs';const AGENTS_MD = 'AGENTS.md';const CLAUDE_MD = 'CLAUDE.md';@@ -17,28 +19,69 @@ const XDS_MARKER_START = '<!-- XDS:START -->';const XDS_MARKER_END = '<!-- XDS:END -->';/**- * Compressed index for agent docs.- * Directs agents to use CLI commands for retrieval.- * When zh=true, outputs a Chinese Simplified version (placeholder: same content for now).+ * Generate the agent cheat sheet from live CLI metadata.+ *+ * Format C (one-liner per command) chosen after testing three formats+ * against Claude Opus for AI agent usability (scored 5/5).*/-export function generateCompressedIndex(version, {zh = false, lang} = {}) {- // TODO: Replace with actual Chinese Simplified translations- // For now, zh mode outputs the same English content as a placeholder- return `${XDS_MARKER_START}-[XDS v${version}]|IMPORTANT: Prefer retrieval-led reasoning. Run CLI to read docs before generating code.-|npx xds --detail compact component <Name> Docs (props, usage) — or --source for code-|npx xds component --list All components by category-|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 template <name> [path] Scaffold page (blank, table, login)-|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-|npx xds upgrade Preview API migrations for your version-|npx xds upgrade --apply Apply codemods to update breaking API changes-|RULE: After bumping @xds/core version, ALWAYS run npx xds upgrade --apply to migrate breaking API changes.-|RULE: When swizzling to unblock yourself, ALWAYS use --gap to explain what capability was missing.-${XDS_MARKER_END}`;+export function generateCompressedIndex(version, {coreDir, zh = false, lang} = {}) {+ const lines = [XDS_MARKER_START];++ lines.push(`XDS v${version}|Always run npx xds component <Name> before writing XDS component code.`);++ // Component count from live discovery+ let componentCount = '90+';+ if (coreDir) {+ try {+ const comps = discoverComponents(coreDir);+ let total = 0;+ for (const list of Object.values(comps)) total += list.length;+ if (total > 0) componentCount = String(total);+ } catch {}+ }++ lines.push(`npx xds component <Name> props, usage, examples for any component`);+ lines.push(`npx xds component --list ${componentCount} components by category`);++ // Doc topics from live discovery+ const docsDir = path.join(CLI_ROOT, 'docs');+ if (fs.existsSync(docsDir)) {+ for (const file of fs.readdirSync(docsDir).sort()) {+ const match = file.match(/^(\w+)\.doc\.mjs$/);+ if (!match) continue;+ const topic = match[1];++ let desc = topic;+ try {+ const fileContent = fs.readFileSync(path.join(docsDir, file), 'utf-8');+ const descMatch = fileContent.match(/description:\s*['"](.+?)['"]/);+ if (descMatch) desc = descMatch[1];+ } catch {}++ lines.push(`npx xds docs ${topic.padEnd(20)} ${desc}`);+ }+ }++ // Templates from live discovery+ const templatesDir = path.join(CLI_ROOT, 'templates');+ if (fs.existsSync(templatesDir)) {+ const templates = fs.readdirSync(templatesDir, {withFileTypes: true})+ .filter(e => e.isDirectory())+ .map(e => e.name)+ .sort();+ if (templates.length > 0) {+ lines.push(`npx xds template <name> [path] scaffold page (${templates.join(', ')})`);+ }+ }++ lines.push(`npx xds swizzle <Name> eject component source (use --gap to report why)`);+ lines.push(`npx xds upgrade --apply run version migration codemods`);+ lines.push(`--detail compact|brief less output | --lang dense|zh translation`);+ lines.push(`RULE: after @xds/core bump, always run npx xds upgrade --apply`);+ lines.push(`RULE: when swizzling, always use --gap to report missing capabilities`);+ lines.push(XDS_MARKER_END);++ return lines.join('\n');}/**@@ -98,7 +141,7 @@ export function injectXdsBlock(filePath, compressedIndex, {createIfMissing = fal*/export function injectAgentsMd(targetDir, version, {zh = false, lang} = {}) {const agentsPath = path.join(targetDir, AGENTS_MD);- const compressedIndex = generateCompressedIndex(version, {zh, lang});+ const compressedIndex = generateCompressedIndex(version, {coreDir: findCoreDir(targetDir)});injectXdsBlock(agentsPath, compressedIndex, {createIfMissing: true,header: `# AGENTS.md\n\nProject-specific guidance for AI coding agents.`,@@ -113,7 +156,7 @@ export function injectAgentsMd(targetDir, version, {zh = false, lang} = {}) {*/export function injectClaudeMd(targetDir, version, {zh = false, lang} = {}) {const claudePath = path.join(targetDir, CLAUDE_MD);- const compressedIndex = generateCompressedIndex(version, {zh, lang});+ const compressedIndex = generateCompressedIndex(version, {coreDir: findCoreDir(targetDir)});return injectXdsBlock(claudePath, compressedIndex);}diff --git a/packages/cli/src/commands/agent-docs.test.mjs b/packages/cli/src/commands/agent-docs.test.mjsindex d02ea33301..32938e2211 100644--- a/packages/cli/src/commands/agent-docs.test.mjs+++ b/packages/cli/src/commands/agent-docs.test.mjs@@ -27,7 +27,7 @@ afterEach(() => {describe('generateCompressedIndex', () => {it('includes the version number', () => {const result = generateCompressedIndex('1.2.3');- expect(result).toContain('[XDS v1.2.3]');+ expect(result).toContain('XDS v1.2.3');expect(result).toContain('<!-- XDS:START -->');expect(result).toContain('<!-- XDS:END -->');});@@ -41,7 +41,7 @@ describe('generateCompressedIndex', () => {const result = generateCompressedIndex('1.0.0');expect(result).toContain('npx xds upgrade');expect(result).toContain('npx xds upgrade --apply');- expect(result).toContain('ALWAYS run npx xds upgrade --apply to migrate breaking API changes');+ expect(result).toContain('after @xds/core bump, always run npx xds upgrade --apply');});});@@ -115,7 +115,7 @@ describe('injectAgentsMd', () => {const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');expect(content).toContain('# AGENTS.md');expect(content).toContain('<!-- XDS:START -->');- expect(content).toContain('[XDS v1.0.0]');+ expect(content).toContain('XDS v1.0.0');expect(content).toContain('<!-- XDS:END -->');});@@ -135,7 +135,7 @@ More stuff.injectAgentsMd(tmpDir, '2.0.0');const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');- expect(content).toContain('[XDS v2.0.0]');+ expect(content).toContain('XDS v2.0.0');expect(content).not.toContain('old content');expect(content).toContain('Some content.');expect(content).toContain('More stuff.');@@ -153,7 +153,7 @@ Existing agent docs.const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');expect(content).toContain('Existing agent docs.');expect(content).toContain('<!-- XDS:START -->');- expect(content).toContain('[XDS v1.0.0]');+ expect(content).toContain('XDS v1.0.0');});});@@ -168,7 +168,7 @@ describe('injectClaudeMd', () => {expect(content).toContain('# Claude Config');expect(content).toContain('Existing rules.');expect(content).toContain('<!-- XDS:START -->');- expect(content).toContain('[XDS v1.0.0]');+ expect(content).toContain('XDS v1.0.0');});it('does not create CLAUDE.md when it does not exist', () => {@@ -192,7 +192,7 @@ Other rules.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).toContain('XDS v2.0.0');expect(content).not.toContain('old content');expect(content).toContain('Other rules.');});