An open source design system that's fully customizable and agent ready
TypeScript
feat(core): docs.mjs redirects to the CLI (converge agents on init) (#4207)
Joey7ceccc13d13c
diff --git a/packages/core/README.md b/packages/core/README.mdindex ce84cf4327..7962582248 100644--- a/packages/core/README.md+++ b/packages/core/README.md@@ -13,14 +13,16 @@ Core UI components, theme system, and utilities for the Astryx design system. Fo## Component Docs-Look up any component's full API (props, types, best practices, and theming):+Look up any component's full API (props, variants, examples, best practices, and theming) via the Astryx CLI:```bash-node node_modules/@astryxdesign/core/docs.mjs Button # full docs for a component-node node_modules/@astryxdesign/core/docs.mjs --list # list all components-node node_modules/@astryxdesign/core/docs.mjs --list --brief # brief summaries+npx @astryxdesign/cli init # one-time: writes the component guide into AGENTS.md / CLAUDE.md+npx @astryxdesign/cli component Button # full docs for a component+npx @astryxdesign/cli component --list # list all components```+> Use the scoped `@astryxdesign/cli` to run without installing; bare `npx astryx` only resolves once the CLI is a dependency.+## Page LayoutsBuilding a full page? Start with a template rather than composing from scratch.diff --git a/packages/core/docs.mjs b/packages/core/docs.mjsindex 9dd0aa916a..2acf45df9b 100644--- a/packages/core/docs.mjs+++ b/packages/core/docs.mjs@@ -1,472 +1,43 @@-#!/usr/bin/env node// Copyright (c) Meta Platforms, Inc. and affiliates./**- * @file Lightweight XDS component docs — zero dependencies, ships with @astryxdesign/core.+ * @file docs.mjs — Astryx component docs are served by the Astryx CLI.*- * Usage:- * node node_modules/@astryxdesign/core/docs.mjs Button- * node node_modules/@astryxdesign/core/docs.mjs --list- * node node_modules/@astryxdesign/core/docs.mjs --list --brief+ * Component docs (props, variants, examples), page templates, design rules, and+ * tokens are provided by the Astryx CLI — always current and richer than a+ * bundled snapshot. This script intentionally redirects there instead of+ * printing docs, so agents and humans converge on the CLI + `init` (which writes+ * the full guide into AGENTS.md / CLAUDE.md) rather than treating a static doc+ * dump as the whole story.+ *+ * ==========================================================================+ * AI AGENT: do NOT guess component APIs or hand-write CSS. Run:+ * npx @astryxdesign/cli init+ * Use the SCOPED name `@astryxdesign/cli` — bare `npx astryx` resolves to an+ * unrelated package until the CLI is a dependency. Then, per component:+ * npx @astryxdesign/cli component <Name>+ * npx @astryxdesign/cli component --list+ * ==========================================================================*/-import * as fs from 'node:fs';-import * as path from 'node:path';-import {fileURLToPath, pathToFileURL} from 'node:url';--const coreDir = path.dirname(fileURLToPath(import.meta.url));-const srcDir = path.join(coreDir, 'src');--// ── Discovery ────────────────────────────────────────────────────────--const CATEGORY_MAP = {- AspectRatio: 'Layout', Center: 'Layout', CollapsibleGroup: 'Layout',- Grid: 'Layout', Layout: 'Layout', Stack: 'Layout',- Avatar: 'Display', Badge: 'Display', Divider: 'Display',- Icon: 'Display', Skeleton: 'Display', Table: 'Display', Text: 'Display',- CheckboxInput: 'Form', DateInput: 'Form', Field: 'Form',- NumberInput: 'Form', RadioList: 'Form', Selector: 'Form',- Slider: 'Form', Switch: 'Form', TextArea: 'Form', TextInput: 'Form',- TimeInput: 'Form',- Button: 'Action', CloseButton: 'Action', DropdownMenu: 'Action', Link: 'Action',- TabList: 'Navigation', TopNav: 'Navigation',- Calendar: 'Overlay', Dialog: 'Overlay', Layer: 'Overlay',-};-const CATEGORY_ORDER = ['Layout', 'Display', 'Form', 'Action', 'Navigation', 'Overlay', 'Other'];-const SKIP = new Set(['theme', 'hooks', 'utils', '__tests__', 'node_modules']);--function discoverDocs() {- const results = [];- if (!fs.existsSync(srcDir)) return results;- for (const entry of fs.readdirSync(srcDir, {withFileTypes: true})) {- if (!entry.isDirectory() || SKIP.has(entry.name)) continue;- const docPath = findDocFile(entry.name);- if (docPath) results.push({dir: entry.name, docPath});- }- return results;-}--function findDocFile(name) {- const direct = path.join(srcDir, name, `${name}.doc.mjs`);- if (fs.existsSync(direct)) return direct;- const dir = path.join(srcDir, name);- if (!fs.existsSync(dir)) return null;- for (const sub of fs.readdirSync(dir, {withFileTypes: true})) {- if (sub.isDirectory()) {- const nested = path.join(dir, sub.name, `${sub.name}.doc.mjs`);- if (fs.existsSync(nested)) return nested;- }- }- return null;-}--function findDocByComponent(name) {- let docPath = findDocFile(name);- if (docPath) return docPath;- for (const entry of fs.readdirSync(srcDir, {withFileTypes: true})) {- if (!entry.isDirectory() || SKIP.has(entry.name)) continue;- const nested = path.join(srcDir, entry.name, name, `${name}.doc.mjs`);- if (fs.existsSync(nested)) return nested;- }- // Fuzzy: find XDS{Name}.tsx and use parent doc- for (const entry of fs.readdirSync(srcDir, {withFileTypes: true})) {- if (!entry.isDirectory() || SKIP.has(entry.name)) continue;- const dir = path.join(srcDir, entry.name);- if (hasXDSFile(dir, name)) {- const doc = findDocInDir(dir);- if (doc) return doc;- }- }- return null;-}--function hasXDSFile(dir, name) {- // Match the current `XDS{Name}.tsx` convention and the post-migration bare- // `{Name}.tsx` form (XDS-prefix migration P2380608025, P4).- const targets = [`XDS${name}.tsx`, `${name}.tsx`];- try {- for (const f of fs.readdirSync(dir, {withFileTypes: true})) {- if (targets.includes(f.name)) return true;- if (f.isDirectory() && hasXDSFile(path.join(dir, f.name), name)) return true;- }- } catch {}- return false;-}--function findDocInDir(dir) {- try {- for (const f of fs.readdirSync(dir)) {- if (f.endsWith('.doc.mjs')) return path.join(dir, f);- }- } catch {}- return null;-}--// ── Loading ──────────────────────────────────────────────────────────--async function loadDoc(docPath) {- const mod = await import(pathToFileURL(docPath).href);- return mod.docs;-}--// ── Example extraction ───────────────────────────────────────────────--function extractExamples(docPath) {- const dir = path.dirname(docPath);- const examples = [];- try {- for (const file of fs.readdirSync(dir)) {- if (!file.endsWith('.tsx') || file.includes('.test')) continue;- const content = fs.readFileSync(path.join(dir, file), 'utf-8');- const regex = /@example\s*\n\s*\*\s*```[\w]*\n([\s\S]*?)```/g;- let match;- while ((match = regex.exec(content)) !== null) {- const code = match[1]- .split('\n')- .map(line => line.replace(/^\s*\*\s?/, ''))- .join('\n')- .trim();- if (code.includes('declare module')) continue;- if (code.includes('stylex.create') && !code.includes('XDS')) continue;- if (code.length > 0) examples.push(code);- }- }- } catch {}- return examples;-}--// ── Formatting ───────────────────────────────────────────────────────--function dataAttrForName(name) {- return `data-${name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()}`;-}--function getTargetDataAttributes(target) {- return [- ...(target.visualProps || []).map(dataAttrForName),- ...(target.states || []).map(dataAttrForName),- ];-}--function formatPropsTable(props) {- if (!props?.length) return '';- const lines = ['| Prop | Type | Default | Description |', '|------|------|---------|-------------|'];- for (const p of props) {- const def = p.default ? `\`${p.default}\`` : '—';- const req = p.required ? ' **(required)**' : '';- lines.push(`| \`${p.name}\` | \`${p.type}\` | ${def} | ${p.description}${req} |`);- }- return lines.join('\n');-}--function formatFull(docs, docPath) {- const s = [];- s.push(`# ${docs.name}\n`);- s.push((docs.usage?.description || '') + '\n');-- // Examples from @example JSDoc blocks in component source- if (docPath) {- const examples = extractExamples(docPath);- if (examples.length) {- s.push('## Example\n');- s.push('```tsx');- s.push(examples.join('\n\n'));- s.push('```\n');- }- }-- if (docs.usage?.anatomy?.length) {- s.push('## Anatomy\n');- s.push('| Element | Required | Description |');- s.push('|---------|----------|-------------|');- for (const el of docs.usage.anatomy)- s.push(`| ${el.name} | ${el.required ? 'Yes' : 'No'} | ${el.description} |`);- s.push('');- }-- if (docs.usage?.bestPractices?.length) {- s.push('## Best Practices\n');- for (const bp of docs.usage.bestPractices)- s.push(`- ${bp.guidance ? '**Do:**' : "**Don't:**"} ${bp.description}`);- s.push('');- }-- if ('props' in docs) {- s.push('## Props\n');- s.push(formatPropsTable(docs.props) + '\n');- }-- if ('components' in docs) {- s.push('## Components\n');- for (const comp of docs.components) {- s.push(`### ${comp.name}\n`);- s.push(comp.description + '\n');- s.push(formatPropsTable(comp.props) + '\n');- }- }-- if (docs.theming?.targets?.length) {- s.push('## Theming\n');- s.push('| Component class | Preferred data attributes | Props | States |');- s.push('|-----------------|---------------------------|-------|--------|');- for (const t of docs.theming.targets) {- const dataAttrs = getTargetDataAttributes(t);- const attrs = dataAttrs.length ? dataAttrs.map(attr => `\`${attr}\``).join(', ') : '—';- const variants = t.visualProps?.join(', ') || '—';- const states = t.states?.join(', ') || '—';- s.push(`| \`${t.className}\` | ${attrs} | ${variants} | ${states} |`);- }- s.push('');- const publicVars = docs.theming.vars?.filter(v => !v.private && !v.derived) || [];- if (publicVars.length) {- s.push('| CSS Variable | Default | Description |');- s.push('|-------------|---------|-------------|');- for (const v of publicVars)- s.push(`| \`${v.name}\` | \`${v.default}\` | ${v.description} |`);- s.push('');- }- }-- return s.join('\n');-}--function formatBrief(docs) {- const desc = docs.usage?.description || '';- const short = desc.length > 80 ? desc.slice(0, 77) + '...' : desc;- const props = docs.props || docs.components?.[0]?.props || [];- const sig = props- .filter(p => p.type.includes('|') && !p.type.includes('ReactNode'))- .map(p => `${p.name}: ${p.type.replace(/['"]/g, '').split('|').map(v => v.trim()).join('|')}`)- .join(', ');- return sig ? `${docs.name}(${sig}) ${short}` : `${docs.name} ${short}`;-}--// ── Main ─────────────────────────────────────────────────────────────---// ── Hook Support ─────────────────────────────────────────────────────--const HOOK_CATEGORY_MAP = {- useFocusTrap: 'Focus',- useGridFocus: 'Focus',- useListFocus: 'Focus',- useMediaQuery: 'Media',- useOverflow: 'Layout',- useScrollOverflow: 'Layout',- useScrollLock: 'Layout',- useEntryAnimation: 'Animation',- useStreamingText: 'Streaming',- useImageMode: 'Media',- useClickableContainer: 'Interaction',- useInputContainer: 'Interaction',-};-const HOOK_CATEGORY_ORDER = ['Focus', 'Layout', 'Animation', 'Interaction', 'Media', 'Streaming', 'Other'];--function discoverHookDocs() {- const results = [];- const hooksDir = path.join(srcDir, 'hooks');- if (fs.existsSync(hooksDir)) {- for (const file of fs.readdirSync(hooksDir)) {- if (file.endsWith('.doc.mjs')) {- results.push({name: file.replace('.doc.mjs', ''), docPath: path.join(hooksDir, file)});- }- }- }- // Also scan component directories for use*.doc.mjs- if (fs.existsSync(srcDir)) {- for (const entry of fs.readdirSync(srcDir, {withFileTypes: true})) {- if (!entry.isDirectory() || SKIP.has(entry.name)) continue;- const dir = path.join(srcDir, entry.name);- try {- for (const file of fs.readdirSync(dir)) {- if (file.startsWith('use') && file.endsWith('.doc.mjs')) {- results.push({name: file.replace('.doc.mjs', ''), docPath: path.join(dir, file)});- }- }- } catch {}- }- }- return results;-}--function findHookDocByName(hookName) {- const normalized = hookName.replace(/^use/i, '');- const hooksDir = path.join(srcDir, 'hooks');-- // Direct match in hooks/- for (const variant of [hookName, `use${normalized}`, `useXDS${normalized}`]) {- const p = path.join(hooksDir, `${variant}.doc.mjs`);- if (fs.existsSync(p)) return p;- }-- // Search component directories- if (fs.existsSync(srcDir)) {- for (const entry of fs.readdirSync(srcDir, {withFileTypes: true})) {- if (!entry.isDirectory() || SKIP.has(entry.name)) continue;- const dir = path.join(srcDir, entry.name);- for (const variant of [hookName, `use${normalized}`, `useXDS${normalized}`]) {- const p = path.join(dir, `${variant}.doc.mjs`);- if (fs.existsSync(p)) return p;- }- }- }- return null;-}--function formatHookParamsTable(params) {- if (!params?.length) return '';- const lines = ['| Param | Type | Default | Description |', '|-------|------|---------|-------------|'];- for (const p of params) {- const def = p.default ? `\`${p.default}\`` : '\u2014';- const req = p.required ? ' **(required)**' : '';- lines.push(`| \`${p.name}\` | \`${p.type}\` | ${def} | ${p.description}${req} |`);- }- return lines.join('\n');-}--function formatHookReturnsTable(returns) {- if (!returns?.length) return '';- const lines = ['| Field | Type | Description |', '|-------|------|-------------|'];- for (const r of returns) {- lines.push(`| \`${r.name}\` | \`${r.type}\` | ${r.description} |`);- }- return lines.join('\n');-}--function formatHookFull(docs) {- const s = [];- s.push(`# ${docs.name}\n`);- s.push((docs.usage?.description || '') + '\n');-- if (docs.params?.length) {- s.push('## Parameters\n');- s.push(formatHookParamsTable(docs.params) + '\n');- }-- if (docs.returns?.length) {- s.push('## Returns\n');- s.push(formatHookReturnsTable(docs.returns) + '\n');- }-- if (docs.usage?.bestPractices?.length) {- s.push('## Best Practices\n');- for (const bp of docs.usage.bestPractices)- s.push(`- ${bp.guidance ? '**Do:**' : "**Don't:**"} ${bp.description}`);- s.push('');- }-- const refs = [];- if (docs.relatedComponents?.length) refs.push(`Components: ${docs.relatedComponents.map(c => c).join(', ')}`);- if (docs.relatedHooks?.length) refs.push(`Hooks: ${docs.relatedHooks.join(', ')}`);- if (docs.importPath) refs.push(`Import: ${docs.importPath}`);- if (refs.length) {- s.push('## Related\n');- for (const r of refs) s.push(r);- s.push('');- }+const BANNER = `+==========================================================================+ Astryx component docs are served by the Astryx CLI (accurate + current).+ Do not guess component APIs or hand-write CSS — set up first (one time):- return s.join('\n');-}+ npx @astryxdesign/cli init-function formatHookBrief(docs) {- const desc = docs.usage?.description || '';- const short = desc.length > 80 ? desc.slice(0, 77) + '...' : desc;- const params = (docs.params || []).filter(p => p.required).map(p => `${p.name}: ${p.type}`).join(', ');- const ret = (docs.returns || []).map(r => r.type).join(' | ');- const sig = params ? `${docs.name}(${params})` : docs.name;- return ret ? `${sig}: ${ret} ${short}` : `${sig} ${short}`;-}+ (Use the scoped name @astryxdesign/cli. Bare \`npx astryx\` resolves to an+ unrelated package until the CLI is installed as a dependency.)-// ── Main ─────────────────────────────────────────────────────────────+ init writes the full component guide, page templates, design rules & tokens+ into your AGENTS.md / CLAUDE.md. Then, for any component:-const args = process.argv.slice(2);-const isList = args.includes('--list');-const isBrief = args.includes('--brief');-const isHooks = args.includes('--hooks');-const name = args.find(a => !a.startsWith('--'));+ npx @astryxdesign/cli component <Name> # full props, variants, examples+ npx @astryxdesign/cli component --list # every component+ npx @astryxdesign/cli build "<what you're building>" # starter kit+==========================================================================+`;-if (isHooks) {- // Hook listing mode- const hookDocs = discoverHookDocs();- const grouped = {};- for (const {name: hookName, docPath} of hookDocs) {- const cat = HOOK_CATEGORY_MAP[hookName] || 'Other';- if (!grouped[cat]) grouped[cat] = [];- grouped[cat].push({name: hookName, docPath});- }- for (const cat of HOOK_CATEGORY_ORDER) {- if (!grouped[cat]) continue;- console.log(`\n${cat}:`);- for (const {name: hookName, docPath} of grouped[cat]) {- if (isBrief) {- try {- const d = await loadDoc(docPath);- console.log(' ' + formatHookBrief(d));- } catch {- console.log(` ${hookName} (error loading docs)`);- }- } else {- console.log(` ${hookName}`);- }- }- }-} else if (isList) {- const docs = discoverDocs();- const grouped = {};- for (const {dir, docPath} of docs) {- const cat = CATEGORY_MAP[dir] || 'Other';- if (!grouped[cat]) grouped[cat] = [];- grouped[cat].push({dir, docPath});- }- for (const cat of CATEGORY_ORDER) {- if (!grouped[cat]) continue;- console.log(`\n${cat}:`);- for (const {dir, docPath} of grouped[cat]) {- if (isBrief) {- try {- const d = await loadDoc(docPath);- console.log(' ' + formatBrief(d));- } catch {- console.log(` ${dir} (error loading docs)`);- }- } else {- console.log(` ${dir}`);- }- }- }-} else if (name) {- // Try hook lookup first for names starting with 'use'- if (name.startsWith('use') || name.startsWith('Use')) {- const hookDocPath = findHookDocByName(name);- if (hookDocPath) {- const docs = await loadDoc(hookDocPath);- console.log(formatHookFull(docs));- } else {- // Fall through to component lookup- const docPath = findDocByComponent(name);- if (!docPath) {- console.error(`Hook or component "${name}" not found.`);- console.error('Run with --list to see components, or --hooks to see hooks.');- process.exit(1);- }- const docs = await loadDoc(docPath);- console.log(formatFull(docs, docPath));- }- } else {- const docPath = findDocByComponent(name);- if (!docPath) {- console.error(`Component "${name}" not found. Run with --list to see available components.`);- process.exit(1);- }- const docs = await loadDoc(docPath);- console.log(formatFull(docs, docPath));- }-} else {- console.log('Usage:');- console.log(' node docs.mjs <ComponentName> Show full component docs');- console.log(' node docs.mjs <hookName> Show full hook docs');- console.log(' node docs.mjs --list List all components');- console.log(' node docs.mjs --list --brief List with brief descriptions');- console.log(' node docs.mjs --hooks List all hooks');- console.log(' node docs.mjs --hooks --brief List hooks with brief descriptions');-}+console.log(BANNER);+process.exit(0);diff --git a/packages/core/src/docs-script.test.mjs b/packages/core/src/docs-script.test.mjsindex c57694d27d..cd1e0a6dbd 100644--- a/packages/core/src/docs-script.test.mjs+++ b/packages/core/src/docs-script.test.mjs@@ -3,12 +3,13 @@/*** @file Subprocess smoke tests for the zero-dependency docs script.*- * `docs.mjs` resolves the package directory from `import.meta.url`. Using- * `new URL(...).pathname` there breaks on Windows (drive-letter paths come- * back as `/D:/...`), which made `--list` print nothing and component- * lookups crash with ENOENT. These tests spawn the script as a real- * subprocess from a neutral cwd, so resolution can only come from the- * module URL, and assert it finds the component catalog on every platform.+ * `docs.mjs` no longer prints component docs itself — it intentionally+ * redirects to the Astryx CLI (`npx @astryxdesign/cli init`) so agents and+ * humans converge on the CLI + `init` rather than a stale bundled snapshot.+ * These tests spawn the script as a real subprocess from a neutral cwd and+ * assert that, regardless of the arguments passed, it prints the redirect+ * banner and exits 0 instead of rendering a component catalog or per-component+ * docs.*/import {describe, it, expect} from 'vitest';@@ -29,22 +30,26 @@ function runDocs(args) {});}-describe('docs.mjs component discovery', () => {- it('--list discovers the component catalog', () => {+describe('docs.mjs redirects to the Astryx CLI', () => {+ it('redirects to the CLI instead of printing a component catalog for --list', () => {const r = runDocs(['--list']);expect(r.error).toBeUndefined();expect(r.signal).toBeNull();expect(r.status).toBe(0);- expect(r.stdout).toMatch(/\bButton\b/);- expect(r.stdout).toMatch(/\bDialog\b/);+ // Prints the redirect banner, not a component list.+ expect(r.stdout).toMatch(/docs are served by the Astryx CLI/);+ expect(r.stdout).toMatch(/npx @astryxdesign\/cli init/);+ expect(r.stdout).toMatch(/npx @astryxdesign\/cli component --list/);});- it('renders docs for a single component', () => {+ it('redirects to the CLI instead of rendering docs for a single component', () => {const r = runDocs(['Button']);expect(r.error).toBeUndefined();expect(r.signal).toBeNull();expect(r.status).toBe(0);- expect(r.stdout).toMatch(/^# Button$/m);- expect(r.stdout).toMatch(/## Props/);+ // A pure redirect: it must not render the component's docs.+ expect(r.stdout).not.toMatch(/^# Button$/m);+ expect(r.stdout).not.toMatch(/## Props/);+ expect(r.stdout).toMatch(/npx @astryxdesign\/cli component <Name>/);});});