@astryxdesign/cli 0.0.0-bootstrap.0 → 0.1.0-canary.0b5b49f

package/src/commands/build-theme.path-safety.test.mjs

@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Path-safety regression tests for `astryx theme build`.
+ *
+ * Covers:
+ *   - Theme name with `..` segments cannot escape the output directory.
+ *   - Theme name with `/` is rejected with a clear error (vs. ENOENT).
+ *   - Multi-file write is atomic: if one file fails, none are left behind.
+ *
+ * Runs the CLI via execFileSync against a tiny synthetic theme file.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+
+function runCli(args, cwd) {
+  try {
+    const out = execFileSync('node', [CLI_BIN, ...args], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {...process.env, FORCE_COLOR: '0'},
+    });
+    return {code: 0, stdout: out, stderr: ''};
+  } catch (e) {
+    return {
+      code: e.status ?? 1,
+      stdout: e.stdout?.toString() ?? '',
+      stderr: e.stderr?.toString() ?? '',
+    };
+  }
+}
+
+function writeTheme(dir, name) {
+  fs.mkdirSync(dir, {recursive: true});
+  const file = path.join(dir, 'theme.mjs');
+  // Plain object literal so the legacy regex+eval path can parse it
+  // without needing jiti / TS, and without depending on @astryxdesign/core being
+  // built. The eval path explicitly supports this shape.
+  fs.writeFileSync(
+    file,
+    `export default { name: ${JSON.stringify(name)}, tokens: { '--color-bg': '#fff' } };\n`,
+  );
+  return file;
+}
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-build-theme-paths-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('theme build path safety', () => {
+  it('rejects a theme name containing ../ traversal and writes no JS outside the input dir', () => {
+    const project = path.join(tmpDir, 'project');
+    const themesDir = path.join(project, 'themes');
+    const outside = path.join(tmpDir, 'outside');
+    fs.mkdirSync(outside, {recursive: true});
+
+    const themeFile = writeTheme(themesDir, '../../escaped');
+
+    const result = runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).not.toBe(0);
+    expect(result.stderr + result.stdout).toMatch(/path separator|invalid theme name/i);
+
+    // The traversal target must not exist.
+    expect(fs.existsSync(path.join(tmpDir, 'escaped.js'))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, 'escaped.css'))).toBe(false);
+    expect(fs.readdirSync(outside)).toEqual([]);
+  });
+
+  it('rejects a theme name containing /', () => {
+    const project = path.join(tmpDir, 'project');
+    const themesDir = path.join(project, 'themes');
+
+    const themeFile = writeTheme(themesDir, 'bad/name');
+
+    const result = runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).not.toBe(0);
+    expect(result.stderr + result.stdout).toMatch(/path separator/i);
+
+    // No partial output — neither bad nor bad/name files should exist.
+    expect(fs.existsSync(path.join(themesDir, 'bad.js'))).toBe(false);
+    expect(fs.existsSync(path.join(themesDir, 'bad', 'name.js'))).toBe(false);
+  });
+
+  it('does not leave partial output (no CSS without JS) on a sanitized rejection', () => {
+    const project = path.join(tmpDir, 'project');
+    const themesDir = path.join(project, 'themes');
+
+    const themeFile = writeTheme(themesDir, '../leak');
+
+    runCli(['theme', 'build', path.relative(project, themeFile)], project);
+
+    // Neither the CSS nor any sibling JS should have been written.
+    const entries = fs.readdirSync(themesDir).sort();
+    expect(entries).toEqual(['theme.mjs']);
+  });
+});

package/src/commands/build-theme.prose.test.mjs

@@ -0,0 +1,135 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression test for prose output of `astryx theme build`.
+ *
+ * `astryx theme build` has a single CSS-generation path — @astryxdesign/core's generator,
+ * the same one the <Theme> runtime uses (generateThemeCSS). It always emits
+ * prose element defaults (h1–h6, p, small, code, hr) so unstyled HTML inherits
+ * the theme's typography, exactly like the runtime. There is intentionally no
+ * way to omit them (the old `--no-prose` flag was removed: it let the build
+ * emit something the runtime never would, breaking the build⇄runtime parity).
+ *
+ * Covers:
+ *   - prose defaults ship in `@layer reset` (zero-specificity :where()), NOT
+ *     `@layer astryx-theme`, so component/Markdown StyleX always wins;
+ *   - no raw element margins are emitted (reset.css zeroes them and the
+ *     components own block spacing — see the docsite Markdown regression);
+ *   - paragraphs use the body font, not the heading font.
+ *
+ * Building `astryx theme build` requires a compiled @astryxdesign/core (there is no in-CLI
+ * fallback generator), so this suite builds core once in beforeAll — mirroring
+ * scripts/build-css.test.mjs — to stay self-sufficient regardless of CI job
+ * ordering.
+ */
+
+import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+const REPO_ROOT = path.resolve(__dirname, '../../../..');
+const CORE_THEME_ENTRY = path.join(
+  REPO_ROOT,
+  'packages/core/dist/theme/index.js',
+);
+
+function runCli(args, cwd) {
+  try {
+    const out = execFileSync('node', [CLI_BIN, ...args], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {...process.env, FORCE_COLOR: '0'},
+    });
+    return {code: 0, stdout: out, stderr: ''};
+  } catch (e) {
+    return {
+      code: e.status ?? 1,
+      stdout: e.stdout?.toString() ?? '',
+      stderr: e.stderr?.toString() ?? '',
+    };
+  }
+}
+
+function writeTheme(dir, name) {
+  fs.mkdirSync(dir, {recursive: true});
+  // The CLI writes <basename>.css next to the source file, so use the
+  // theme name as the filename for unambiguous fixtures.
+  const file = path.join(dir, `${name}.mjs`);
+  fs.writeFileSync(
+    file,
+    `export default { name: ${JSON.stringify(name)}, tokens: { '--color-bg': '#fff' } };\n`,
+  );
+  return file;
+}
+
+// `astryx theme build` imports the compiled @astryxdesign/core/theme entry. Build core
+// once if it isn't already present so the suite works in any CI job.
+beforeAll(() => {
+  if (!fs.existsSync(CORE_THEME_ENTRY)) {
+    execFileSync('pnpm', ['-F', '@astryxdesign/core', 'build'], {
+      cwd: REPO_ROOT,
+      stdio: 'pipe',
+      timeout: 180_000,
+    });
+  }
+}, 200_000);
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-build-theme-prose-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('theme build prose output', () => {
+  it('always emits prose mappings in @layer reset', () => {
+    const project = path.join(tmpDir, 'project');
+    const themesDir = path.join(project, 'themes');
+    const themeFile = writeTheme(themesDir, 'with-prose');
+
+    const result = runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).toBe(0);
+
+    const cssPath = path.join(themesDir, 'with-prose.css');
+    expect(fs.existsSync(cssPath)).toBe(true);
+    const css = fs.readFileSync(cssPath, 'utf-8');
+
+    // Prose defaults are zero-specificity :where() rules in @layer reset,
+    // NOT @layer astryx-theme, so Markdown/component StyleX always wins.
+    expect(css).toMatch(/@layer reset/);
+    expect(css).toMatch(/:where\(h1, h2, h3, h4, h5, h6\)/);
+    // Paragraphs use the body font (regression: they used the heading font).
+    expect(css).toMatch(/:where\(p\)[^}]*font-family: var\(--font-family-body\)/);
+    // No raw element margins — reset.css + component StyleX own spacing.
+    const proseBlock = css.slice(
+      css.indexOf('@layer reset'),
+      css.indexOf('@layer astryx-theme'),
+    );
+    expect(proseBlock).not.toMatch(/margin/);
+
+    // Layer placement: prose (reset) must come before component overrides
+    // (astryx-theme) so the cascade resolves correctly.
+    const resetIndex = css.indexOf('@layer reset');
+    const themeIndex = css.indexOf('@layer astryx-theme');
+    expect(resetIndex).toBeGreaterThanOrEqual(0);
+    expect(themeIndex).toBeGreaterThan(resetIndex);
+    expect(css.indexOf(':where(p)')).toBeLessThan(themeIndex);
+  });
+
+  it('has no --no-prose flag (prose is non-optional)', () => {
+    const result = runCli(['theme', 'build', '--help'], process.cwd());
+    // The flag was removed; build always emits prose to match the runtime.
+    expect(result.stdout + result.stderr).not.toContain('--no-prose');
+  });
+});

package/src/commands/component/index.mjs

@@ -0,0 +1,224 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file component command — List components and print component docs
+ *
+ * Global options: --detail full|compact|brief, --lang en|zh|dense
+ */
+
+import {findCoreDir} from '../../utils/paths.mjs';
+import {
+  resolveImportPath,
+} from '../../lib/component-discovery.mjs';
+import {
+  formatFull,
+  formatCompact,
+  formatBrief,
+  formatProps,
+  formatBriefAll,
+} from '../../lib/component-format.mjs';
+import {resolveTheme} from '../../lib/resolve-theme.mjs';
+import {getRunPrefix} from '../../utils/package-manager.mjs';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {component as componentApi} from '../../api/component.mjs';
+import {findRelatedBlocks} from '../../api/template.mjs';
+
+export function registerComponent(program) {
+  program
+    .command('component [name]')
+    .description('List components or print component docs')
+    .option('--list', 'List all components grouped by category')
+    .option('--category <category>', 'List components in a specific category')
+    .option('--props', 'Print only the props table')
+    .option('--source', 'Print component source code')
+    .option('--showcase', 'Print showcase source code')
+    .option('--blocks', 'List example blocks: showcase, examples, and related')
+    .option('--package <name>', 'Scope lookup to an external package (e.g. @acme/xds-widgets)')
+    .action(async (name, options) => {
+      const run = getRunPrefix();
+      const zh = program.opts().zh || false;
+      const dense = program.opts().dense || false;
+      const lang = program.opts().lang || null;
+      const detailSource = program.getOptionValueSource('detail');
+      const isListView = options.list || options.category || !name;
+      // Default detail level is full for single-component view, brief for list views.
+      // (List views are scannable name lists; users can opt into compact/full.)
+      let detail = program.opts().detail || 'full';
+      if (isListView && detailSource === 'default') detail = 'brief';
+      const json = program.opts().json || false;
+
+      const validDetails = ['full', 'compact', 'brief'];
+      if (!validDetails.includes(detail)) {
+        cliError(`Invalid --detail value "${detail}". Valid levels: ${validDetails.join(', ')}`, {code: ERROR_CODES.ERR_INVALID_DETAIL});
+        return;
+      }
+
+      let result;
+      try {
+        result = await componentApi(name, {
+          cwd: process.cwd(),
+          list: options.list,
+          category: options.category,
+          package: options.package,
+          props: options.props,
+          source: options.source,
+          showcase: options.showcase,
+          blocks: options.blocks,
+          detail,
+          lang, zh, dense,
+        });
+      } catch (e) {
+        cliError(e.message, {suggestions: e.suggestions, code: e.code});
+        return;
+      }
+
+      if (json) return jsonOut(result.type, result.data);
+
+      // ── Text output ────────────────────────────────────────────
+      const coreDir = findCoreDir(process.cwd());
+      const themeData = resolveTheme(process.cwd());
+
+      switch (result.type) {
+        case 'component.list': {
+          // --detail brief (default for list views) — names with import paths.
+          if (options.category) {
+            const [cat, comps] = Object.entries(result.data)[0];
+            humanLog(`\n${cat}:`);
+            for (const comp of comps) {
+              const importPath = resolveImportPath(coreDir, comp);
+              humanLog(`  ${comp}  ← ${importPath}`);
+            }
+            humanLog('');
+          } else {
+            humanLog('');
+            for (const [key, comps] of Object.entries(result.data)) {
+              const isUngrouped = comps.length === 1 && comps[0] === key;
+              if (isUngrouped) {
+                const importPath = resolveImportPath(coreDir, key);
+                humanLog(`${key}  ← ${importPath}`);
+              } else {
+                humanLog(`${key} (group)`);
+                for (const comp of comps) {
+                  const importPath = resolveImportPath(coreDir, comp);
+                  humanLog(`  ${comp}  ← ${importPath}`);
+                }
+              }
+            }
+            humanLog('');
+            humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);
+            humanLog(`Usage: ${run} astryx component <name>`);
+            humanLog('');
+          }
+          break;
+        }
+
+        case 'component.brief': {
+          // --detail compact — name + 1-line description per entry.
+          humanLog('');
+          const entries = Object.entries(result.data);
+          for (const [cat, items] of entries) {
+            // Skip the synthetic group header when there's only one ungrouped category
+            const isUngrouped =
+              entries.length === 1 && items.length === 1 && items[0]?.name === cat;
+            if (!isUngrouped) humanLog(`${cat} (group)`);
+            for (const item of items) {
+              const importHint = item.import ? `  ← ${item.import}` : '';
+              const desc = item.description ? ` — ${item.description}` : '';
+              humanLog(`  XDS${item.name}${importHint}${desc}`);
+            }
+            humanLog('');
+          }
+          humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);
+          humanLog(`Usage: ${run} astryx component <name>`);
+          humanLog('');
+          break;
+        }
+
+        case 'component.full': {
+          // --detail full — dense per-component docs (signature, props, theming, examples).
+          humanLog(await formatBriefAll(coreDir, {zh, lang, themeData}));
+          break;
+        }
+
+        case 'component.detail': {
+          if (detail === 'brief') {
+            const resolvedName = (name || '').replace(/^XDS/, '');
+            const importHint = resolveImportPath(coreDir, resolvedName);
+            humanLog(formatBrief(result.data, resolvedName, importHint, {themeData}));
+          } else if (detail === 'compact') {
+            const resolvedName = (name || '').replace(/^XDS/, '');
+            const importHint = resolveImportPath(coreDir, resolvedName);
+            humanLog(formatCompact(result.data, resolvedName, importHint));
+          } else {
+            const resolvedName = (name || '').replace(/^XDS/, '');
+            const importHint = resolveImportPath(coreDir, resolvedName);
+            humanLog(formatFull(result.data, {themeData, importHint}));
+          }
+          const compName = (name || '').replace(/^XDS/, '');
+          const related = await findRelatedBlocks(compName);
+          if (related.length > 0) {
+            humanLog('\nRelated block templates:\n');
+            for (const b of related) {
+              humanLog(`  ${b.dirName}`);
+              if (b.description) humanLog(`    ${b.description}`);
+            }
+            humanLog('');
+          }
+          break;
+        }
+
+        case 'component.detail.props': {
+          const resolvedName = (name || '').replace(/^XDS/, '');
+          humanLog(formatProps({props: result.data}, resolvedName));
+          break;
+        }
+
+        case 'component.detail.source': {
+          humanLog(result.data.source);
+          break;
+        }
+
+        case 'component.detail.showcase': {
+          humanLog(result.data.source);
+          break;
+        }
+
+        case 'component.detail.blocks': {
+          const {showcase, examples, related} = result.data;
+          if (showcase) {
+            humanLog(`\nShowcase: ${showcase.displayName}`);
+            if (showcase.description) humanLog(`  ${showcase.description}`);
+          }
+          if (examples.length > 0) {
+            humanLog('\nExamples:\n');
+            for (const b of examples) {
+              humanLog(`  ${b.name}`);
+              if (b.description) humanLog(`    ${b.description}`);
+            }
+          }
+          if (related.length > 0) {
+            humanLog(`\nRelated: ${related.length} blocks that use ${result.data.component}\n`);
+            for (const b of related) {
+              humanLog(`  ${b.name}`);
+            }
+          }
+          if (!showcase && examples.length === 0 && related.length === 0) {
+            humanLog(`\nNo blocks found for ${result.data.component}`);
+          }
+          humanLog('');
+          break;
+        }
+      }
+    });
+}
+
+
+// Re-export lib functions for backward compatibility
+// (agent-docs.mjs, tests, and generate-skill-doc.sh import from here)
+export {discoverComponents, discoverExternalComponents, discoverExternalComponentsGrouped, findComponentReadme, findComponentSource, findExternalComponentDoc, resolveImportPath} from '../../lib/component-discovery.mjs';
+export {discoverExternalPackages} from '../../utils/paths.mjs';
+export {loadDocs} from '../../lib/component-loader.mjs';
+export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../../lib/component-format.mjs';
+export {levenshteinDistance, findClosestComponents, searchComponents} from '../../lib/string-utils.mjs';

package/src/commands/component-package.test.mjs

@@ -0,0 +1,123 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {component} from '../api/component.mjs';
+
+// These tests create a minimal monorepo fixture with:
+// - packages/core (symlinked to real @astryxdesign/core for loadDocs compatibility)
+// - node_modules/@test/ext with a Button + ProfileCard component (external package)
+//
+// This tests the --package option for disambiguating overlapping component names.
+
+let tmpDir;
+
+function createFixture() {
+  // Symlink real core package so loadDocs (dynamic import) works with Vite
+  const realCoreDir = path.resolve(import.meta.dirname, '..', '..', '..', 'core');
+  const coreDir = path.join(tmpDir, 'packages', 'core');
+  fs.mkdirSync(path.dirname(coreDir), {recursive: true});
+  fs.symlinkSync(realCoreDir, coreDir);
+
+  // External package with Button (different docs) + ProfileCard (unique)
+  const extDir = path.join(tmpDir, 'node_modules', '@test', 'ext');
+  const extSrc = path.join(extDir, 'src');
+  fs.mkdirSync(path.join(extSrc, 'Button'), {recursive: true});
+  fs.mkdirSync(path.join(extSrc, 'ProfileCard'), {recursive: true});
+
+  // Blocks directory with a ProfileCard showcase
+  const blocksDir = path.join(extDir, 'blocks', 'components', 'ProfileCard');
+  fs.mkdirSync(blocksDir, {recursive: true});
+  fs.writeFileSync(path.join(blocksDir, 'ProfileCardShowcase.doc.mjs'), `
+export const doc = {
+  type: 'block',
+  name: 'ProfileCard — Showcase',
+  description: 'ProfileCard showcase.',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['ProfileCard'],
+};
+`);
+  fs.writeFileSync(path.join(blocksDir, 'ProfileCardShowcase.tsx'),
+    "'use client';\nexport default function ProfileCardShowcase() { return <div>ProfileCard</div>; }");
+
+  fs.writeFileSync(path.join(extDir, 'package.json'), JSON.stringify({
+    name: '@test/ext',
+    astryx: {docs: './src', category: 'Common', blocks: './blocks/components'},
+  }));
+  fs.writeFileSync(path.join(extSrc, 'Button', 'Button.doc.mjs'), `
+export const docs = {
+  name: 'AcmeButton',
+  usage: { description: 'Common button with platform features.' },
+  props: [{ name: 'label', type: 'string', description: 'Button label' }, { name: 'isLoading', type: 'boolean', description: 'Shows spinner' }],
+};
+`);
+  fs.writeFileSync(path.join(extSrc, 'ProfileCard', 'ProfileCard.doc.mjs'), `
+export const docs = {
+  name: 'AcmeProfileCard',
+  usage: { description: 'Profile card component.' },
+  props: [{ name: 'userId', type: 'string', description: 'User identifier' }],
+};
+`);
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-pkg-test-'));
+  createFixture();
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('component() with --package option', () => {
+  it('returns external package docs when --package is specified', async () => {
+    const result = await component('Button', {cwd: tmpDir, package: '@test/ext'});
+    expect(result.type).toBe('component.detail');
+    expect(result.data.name).toBe('AcmeButton');
+    expect(result.data.usage.description).toContain('platform features');
+  });
+
+  it('returns core docs when no --package is specified (default behavior)', async () => {
+    const result = await component('Button', {cwd: tmpDir});
+    expect(result.type).toBe('component.detail');
+    // Core's Button doc has name 'Button', not 'AcmeButton'
+    expect(result.data.name).toBe('Button');
+  });
+
+  it('resolves unique external components without --package', async () => {
+    const result = await component('ProfileCard', {cwd: tmpDir});
+    expect(result.type).toBe('component.detail');
+    expect(result.data.name).toBe('AcmeProfileCard');
+  });
+
+  it('returns props for package-scoped component', async () => {
+    const result = await component('Button', {cwd: tmpDir, package: '@test/ext', props: true});
+    expect(result.type).toBe('component.detail.props');
+    expect(result.data).toHaveLength(2);
+    expect(result.data.some(p => p.name === 'isLoading')).toBe(true);
+  });
+
+  it('throws for unknown package name', async () => {
+    await expect(
+      component('Button', {cwd: tmpDir, package: '@test/nonexistent'}),
+    ).rejects.toThrow('not found');
+  });
+
+  it('throws for component not in the specified package', async () => {
+    await expect(
+      component('Avatar', {cwd: tmpDir, package: '@test/ext'}),
+    ).rejects.toThrow('No component "Avatar" in package');
+  });
+
+  it('returns showcase from external package when --package + --showcase', async () => {
+    const result = await component('ProfileCard', {cwd: tmpDir, package: '@test/ext', showcase: true});
+    expect(result.type).toBe('component.detail.showcase');
+    expect(result.data.component).toBe('ProfileCard');
+    expect(result.data.source).toContain('ProfileCardShowcase');
+    expect(result.data.aspectRatio).toBeCloseTo(16 / 9);
+  });
+});