@astryxdesign/cli 0.1.0 → 0.1.1-canary.080d887

package/src/commands/build.mjs

@@ -0,0 +1,196 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file build command — the page-building assistant.
+ *
+ * Two modes:
+ *   astryx build                  → the PLAYBOOK: how to build a page with Astryx
+ *   astryx build "<what>"         → a COMPOSITION KIT for what you're building:
+ *                                   the closest page template (scaffold or layout
+ *                                   reference), the blocks that cover parts, and
+ *                                   the components to fill gaps, plus a one-line
+ *                                   "Compose:" suggestion.
+ *
+ * `build` is the opinionated "assemble a page" verb. For a neutral lookup across
+ * the whole CLI, use `astryx search <query>` instead.
+ */
+
+import {getRunPrefix} from '../utils/package-manager.mjs';
+import {jsonOut, humanLog} from '../lib/json.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {search as searchApi} from '../api/search.mjs';
+
+/** A page scoring at/above this is confident enough to call a direct match. */
+const PAGE_DIRECT = 95;
+/** Below this a page is too weak to even offer as a layout reference. */
+const PAGE_FLOOR = 50;
+/** Below this a block/domain-component match is incidental noise, not surfaced. */
+const DOMAIN_FLOOR = 55;
+
+/**
+ * Always-surfaced primitives. Every page needs a shell + layout/typography/
+ * action atoms, but these never keyword-match an idea ("dashboard" != "Stack"),
+ * so search alone never returns them. We list them unconditionally so an agent
+ * composing from scratch has the whole kit (esp. off-template).
+ */
+const FRAME = ['AppShell', 'TopNav', 'SideNav', 'Layout'];
+const FOUNDATION = [
+  'VStack', 'HStack', 'Grid', 'StackItem', 'Card', 'Section',
+  'Text', 'Heading', 'Button', 'Icon', 'Badge', 'Divider',
+];
+const ALWAYS = new Set([...FRAME, ...FOUNDATION]);
+
+/** Print the build playbook (shown when `build` is run with no query). */
+function printPlaybook(run) {
+  const lines = [
+    '',
+    'How to build a page with Astryx',
+    '',
+    "1. Find a starting point for what you're building:",
+    `     ${run} astryx build "<what you're building>"`,
+    '   → returns the closest [page] template, the [block]s that cover parts,',
+    '     and the [component]s to fill the gaps, with a "Compose:" suggestion.',
+    '',
+    '2. If a [page] template matches → scaffold it and adapt:',
+    `     ${run} astryx template <name> [path]`,
+    '',
+    '3. If nothing matches exactly → compose:',
+    `     ${run} astryx template <name> --skeleton   # study a close page's layout`,
+    `     ${run} astryx template <BlockName>         # drop in each block from the kit`,
+    `     ${run} astryx component <Name>             # fill remaining gaps (read props)`,
+    '',
+    '4. Rules (keep it on-system):',
+    '   - No <div>/raw HTML for layout — use VStack/HStack/Grid/Stack/Card etc.',
+    '   - No style={{}} — use component props; design tokens via `astryx docs tokens`.',
+    '   - Wrap the app in <Theme theme={...}> and import core reset.css + astryx.css.',
+    '',
+    `Tip: \`${run} astryx build "<idea>"\` is the fastest way in. For a neutral`,
+    `lookup of any component/doc/template, use \`${run} astryx search <query>\`.`,
+    '',
+  ];
+  for (const l of lines) humanLog(l);
+}
+
+export function registerBuild(program) {
+  program
+    .command('build [query]')
+    .description('Build a page: composition kit for an idea, or the workflow playbook (no args)')
+    .option('--type <domain>', 'Filter the kit to one domain (component|hook|template)')
+    .option('--limit <n>', 'Max candidates to draw from (default 60)')
+    .option('--detail', 'Verbose output (include import paths and match reason)')
+    .action(async (query, options) => {
+      const run = getRunPrefix();
+      const json = program.opts().json || false;
+
+      // No query → print the playbook (the "how to build" skill).
+      if (!query || !String(query).trim()) {
+        if (json) return jsonOut('build.help', {playbook: true});
+        printPlaybook(run);
+        return;
+      }
+
+      // Default to a deep pool so each role section has candidates after grouping.
+      let limit = 60;
+      if (options.limit != null) {
+        const parsed = Number.parseInt(options.limit, 10);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+          cliError(`Invalid --limit value "${options.limit}". Must be a positive integer.`);
+          return;
+        }
+        limit = parsed;
+      }
+
+      let result;
+      try {
+        result = await searchApi(query, {cwd: process.cwd(), type: options.type, limit});
+      } catch (e) {
+        cliError(e.message, {suggestions: e.suggestions});
+        return;
+      }
+
+      if (json) return jsonOut(result.type, result.data);
+
+      const {query: q, results} = result.data;
+
+      if (results.length === 0) {
+        humanLog('');
+        humanLog(`No matches for "${q}".`);
+        humanLog(`Try a broader term, or browse: ${run} astryx component --list`);
+        humanLog('');
+        return;
+      }
+
+      // ── Group results by role (the build kit) ──────────────────────
+      const pages = results
+        .filter(r => r.domain === 'template' && r.kind !== 'block' && r.score >= PAGE_FLOOR)
+        .slice(0, 3);
+      const blocks = results
+        .filter(r => r.domain === 'template' && r.kind === 'block' && r.score >= DOMAIN_FLOOR)
+        .slice(0, 5);
+      // Idea-specific atoms = matched components/hooks MINUS the always-on kit.
+      const domain = results
+        .filter(r => (r.domain === 'component' || r.domain === 'hook') && r.score >= DOMAIN_FLOOR && !ALWAYS.has(r.name))
+        .slice(0, 6);
+      const directMatch = pages.length > 0 && pages[0].score >= PAGE_DIRECT;
+
+      const printItem = (r, label) => {
+        const display = r.domain === 'template' && r.displayName ? r.displayName : r.name;
+        humanLog('');
+        humanLog(`  [${label}] ${display}`);
+        if (r.description) humanLog(`          ${r.description}`);
+        humanLog(`          → ${run} ${r.command}`);
+        if (options.detail) {
+          if (r.import) humanLog(`          import: ${r.import}`);
+          humanLog(`          match: ${r.reason} (score ${r.score})`);
+        }
+      };
+
+      humanLog('');
+      humanLog(`Building "${q}":`);
+
+      // START — the single recommended path.
+      humanLog('');
+      if (directMatch) {
+        humanLog(`START → Scaffold the \`${pages[0].name}\` page template, then adapt: ${run} astryx template ${pages[0].name} ./src/App.tsx`);
+      } else if (pages.length) {
+        humanLog(`START → No exact page template. Use \`${pages[0].name}\` as a layout reference (${run} astryx template ${pages[0].name} --skeleton) and compose the pieces below.`);
+      } else {
+        humanLog(`START → No page template fits. Frame with AppShell and compose the blocks + components below.`);
+      }
+
+      // PAGE
+      if (pages.length) {
+        humanLog('');
+        humanLog(directMatch ? 'PAGE TEMPLATE — direct match:' : 'CLOSEST PAGE TEMPLATES — layout reference:');
+        pages.forEach(p => printItem(p, directMatch ? 'page' : 'closest'));
+      }
+
+      // FRAME — always (the page shell).
+      humanLog('');
+      humanLog(`FRAME — page shell (always): ${FRAME.join(', ')}`);
+      humanLog(`          full-page → AppShell; or Layout + SideNav/TopNav. ${run} astryx component AppShell`);
+
+      // BLOCKS — idea-specific composed patterns.
+      if (blocks.length) {
+        humanLog('');
+        humanLog('BLOCKS — drop-in patterns that cover parts of it:');
+        blocks.forEach(b => printItem(b, 'block'));
+      }
+
+      // DOMAIN COMPONENTS — idea-specific atoms.
+      if (domain.length) {
+        humanLog('');
+        humanLog('DOMAIN COMPONENTS — specific to this idea:');
+        domain.forEach(c => printItem(c, c.domain === 'hook' ? 'hook' : 'component'));
+      }
+
+      // FOUNDATION — always (layout/typography/actions).
+      humanLog('');
+      humanLog(`FOUNDATION — always available (layout/text/actions): ${FOUNDATION.join(' ')}`);
+
+      // SETUP — so it renders / stays on-system.
+      humanLog('');
+      humanLog('SETUP — import "@astryxdesign/core/reset.css" + "astryx.css". No <div>/style for layout — use Stack/Grid + tokens.');
+      humanLog('');
+    });
+}

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

@@ -65,7 +65,7 @@ export const docs = {
 }
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-pkg-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-pkg-test-'));
   createFixture();
 });
 

package/src/commands/component.test.mjs

@@ -18,7 +18,7 @@ import {
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-component-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-component-test-'));
 });
 
 afterEach(() => {

package/src/commands/docs.test.mjs

@@ -10,7 +10,7 @@ import {registerDocs} from './docs.mjs';
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-docs-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-docs-test-'));
   vi.spyOn(console, 'log').mockImplementation(() => {});
   vi.spyOn(console, 'error').mockImplementation(() => {});
 });

package/src/commands/doctor.test.mjs

@@ -26,7 +26,7 @@ let logCalls;
 let exitCode;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-doctor-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-doctor-test-'));
   logCalls = [];
   exitCode = undefined;
   vi.spyOn(console, 'log').mockImplementation((...args) => {

package/src/commands/external-showcase.test.mjs

@@ -78,7 +78,7 @@ export const doc = {
 }
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-showcase-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-showcase-test-'));
   createFixture();
 });
 

package/src/commands/gap-report.mjs

@@ -132,7 +132,7 @@ export function registerGapReport(program) {
     .action(async () => {
       p.intro('Gap report setup');
 
-      const config = loadGapReportConfig();
+      const config = await loadGapReportConfig();
       const currentMode = !config.enabled
         ? 'disabled'
         : config.command
@@ -252,9 +252,14 @@ export function registerGapReport(program) {
         return;
       }
 
-      const config = loadGapReportConfig();
+      const config = await loadGapReportConfig();
       if (!config.enabled) {
-        if (json) return jsonError('Gap reporting is disabled', undefined, ERROR_CODES.ERR_GAP_REPORT_FAILED);
+        if (json)
+          return jsonError(
+            'Gap reporting is disabled',
+            undefined,
+            ERROR_CODES.ERR_GAP_REPORT_FAILED,
+          );
         humanLog(
           `Gap reporting is disabled (ASTRYX_GAP_REPORT=off or astryx.config.mjs).\n` +
             `Run \`${getRunPrefix()} astryx gap-report setup\` to configure.`,
@@ -295,7 +300,7 @@ export function registerGapReport(program) {
           return;
         }
 
-        const preview = buildGapReportPreview({
+        const preview = await buildGapReportPreview({
           component: options.component,
           category: options.category,
           intention: options.reason,
@@ -326,7 +331,7 @@ export function registerGapReport(program) {
         }
 
         try {
-          const url = createGapReport({
+          const url = await createGapReport({
             component: options.component,
             category: options.category,
             intention: options.reason,
@@ -343,7 +348,9 @@ export function registerGapReport(program) {
             humanLog('\nGap reporting is disabled via configuration.\n');
           }
         } catch (err) {
-          cliError(`Filing gap report failed: ${err.message}`, {code: ERROR_CODES.ERR_GAP_REPORT_FAILED});
+          cliError(`Filing gap report failed: ${err.message}`, {
+            code: ERROR_CODES.ERR_GAP_REPORT_FAILED,
+          });
           return;
         }
         return;
@@ -386,7 +393,8 @@ export function registerGapReport(program) {
           placeholder:
             'e.g. "Need a compact variant for use in dense data tables"',
           validate: val => {
-            if (!val.trim()) return 'Please describe what you were trying to do';
+            if (!val.trim())
+              return 'Please describe what you were trying to do';
           },
         }),
       );
@@ -406,7 +414,7 @@ export function registerGapReport(program) {
         source: 'interactive',
       };
 
-      const preview = buildGapReportPreview(previewArgs);
+      const preview = await buildGapReportPreview(previewArgs);
 
       // Always show the user exactly what would be filed before sending.
       p.note(
@@ -440,7 +448,7 @@ export function registerGapReport(program) {
       s.start('Filing gap report');
 
       try {
-        const url = createGapReport(previewArgs);
+        const url = await createGapReport(previewArgs);
         s.stop(url ? 'Gap report filed' : 'Gap reporting is disabled');
         if (url) {
           p.log.success(url);

package/src/commands/gap-report.test.mjs

@@ -40,9 +40,9 @@ describe('shouldActuallyFile', () => {
   });
 
   it('--dry-run wins over --commit (safety)', () => {
-    expect(
-      shouldActuallyFile({isTTY: true, commit: true, dryRun: true}),
-    ).toBe(false);
+    expect(shouldActuallyFile({isTTY: true, commit: true, dryRun: true})).toBe(
+      false,
+    );
   });
 });
 
@@ -54,7 +54,9 @@ describe('formatPreview', () => {
       title: '[gap] Button: missing compact variant',
       body: '## User Intention\n\nNeed a compact variant',
     });
-    expect(out).toContain('Would file GitHub issue on facebookexperimental/xds');
+    expect(out).toContain(
+      'Would file GitHub issue on facebookexperimental/xds',
+    );
     expect(out).toContain('[gap] Button');
     expect(out).toContain('Need a compact variant');
     expect(out).toContain('Labels: gap-report');
@@ -91,13 +93,14 @@ describe('ASTRYX_GAP_REPORT=off env var', () => {
   it('disables gap reporting when set to "off"', async () => {
     process.env.ASTRYX_GAP_REPORT = 'off';
     vi.resetModules();
-    const {loadGapReportConfig, createGapReport} = await import(
-      '../utils/github.mjs'
-    );
-    expect(loadGapReportConfig().enabled).toBe(false);
+    const {loadGapReportConfig, createGapReport} =
+      await import('../utils/github.mjs');
+    await expect(loadGapReportConfig()).resolves.toMatchObject({
+      enabled: false,
+    });
 
     // createGapReport must return null and never invoke gh.
-    const result = createGapReport({
+    const result = await createGapReport({
       component: 'Button',
       category: 'other',
       intention: 'test',
@@ -109,12 +112,16 @@ describe('ASTRYX_GAP_REPORT=off env var', () => {
     process.env.ASTRYX_GAP_REPORT = 'false';
     vi.resetModules();
     let mod = await import('../utils/github.mjs');
-    expect(mod.loadGapReportConfig().enabled).toBe(false);
+    await expect(mod.loadGapReportConfig()).resolves.toMatchObject({
+      enabled: false,
+    });
 
     process.env.ASTRYX_GAP_REPORT = '0';
     vi.resetModules();
     mod = await import('../utils/github.mjs');
-    expect(mod.loadGapReportConfig().enabled).toBe(false);
+    await expect(mod.loadGapReportConfig()).resolves.toMatchObject({
+      enabled: false,
+    });
   });
 });
 
@@ -133,16 +140,14 @@ describe('buildGapReportPreview', () => {
   it('renders title and body without invoking gh', async () => {
     vi.resetModules();
     const {buildGapReportPreview} = await import('../utils/github.mjs');
-    const preview = buildGapReportPreview({
+    const preview = await buildGapReportPreview({
       component: 'Button',
       category: 'missing_variant',
       intention: 'Need compact variant for tables',
     });
     expect(preview.mode).toBe('github');
     expect(preview.enabled).toBe(true);
-    expect(preview.title).toBe(
-      '[gap] Button: Need compact variant for tables',
-    );
+    expect(preview.title).toBe('[gap] Button: Need compact variant for tables');
     expect(preview.body).toContain('| **Component** | Button |');
     expect(preview.body).toContain('Need compact variant for tables');
     expect(preview.repo).toBe('facebookexperimental/xds');
@@ -152,7 +157,7 @@ describe('buildGapReportPreview', () => {
     process.env.ASTRYX_GAP_REPORT = 'off';
     vi.resetModules();
     const {buildGapReportPreview} = await import('../utils/github.mjs');
-    const preview = buildGapReportPreview({
+    const preview = await buildGapReportPreview({
       component: 'Button',
       category: 'other',
       intention: 'x',

package/src/commands/init.mjs

@@ -29,6 +29,37 @@ import {requireInteractive} from '../utils/interactive.mjs';
 const VALID_FEATURES = ['agents', 'theme', 'template'];
 const run = getRunPrefix();
 
+/**
+ * Build the "Next steps" lines printed at the end of `astryx init`.
+ *
+ * Theme guidance must match the runtime recommendation emitted by core's
+ * <Theme> component (packages/core/src/theme/Theme.tsx): the pre-built theme
+ * path (`/built` import + `theme.css`) plus the base CSS import, so users
+ * don't end up with an unstyled app or the slower runtime style-injection
+ * path. See https://github.com/facebook/astryx/issues/3080.
+ *
+ * Exported for testing.
+ *
+ * @param {string} runPrefix package-manager run prefix (e.g. `npx`)
+ * @returns {string[]} ordered list of human-facing lines
+ */
+export function getNextSteps(runPrefix) {
+  return [
+    '',
+    '  Next steps:',
+    "    1. Import base styles: import '@astryxdesign/core/reset.css'",
+    "       and import '@astryxdesign/core/astryx.css'",
+    "    2. Import components: import { Button } from '@astryxdesign/core'",
+    '    3. Optionally add a theme (use the pre-built path for performance):',
+    "       import { neutralTheme } from '@astryxdesign/theme-neutral/built'",
+    "       import '@astryxdesign/theme-neutral/theme.css'",
+    '       <Theme theme={neutralTheme}>...</Theme>',
+    `       For custom themes, run \`${runPrefix} astryx theme build <file>\` to generate the built artifacts.`,
+    `    4. ${runPrefix} astryx --help for all commands`,
+    '',
+  ];
+}
+
 function isCancel(value) {
   if (p.isCancel(value)) {
     p.cancel('Setup cancelled.');
@@ -100,7 +131,15 @@ async function runTemplate(targetDir, {interactive = true, templateName} = {}) {
 
   if (!interactive) {
     if (!templateName) {
-      humanLog(`✓ Available templates: ${templates.join(', ')}. Use ${run} astryx template <name> [path].`);
+      // Point agents at the build workflow rather than dumping page-template
+      // names — `build` surfaces pages AND blocks AND components for an idea,
+      // and `build` with no args is the full how-to-build playbook.
+      humanLog('✓ To build UI, use these commands:');
+      humanLog('');
+      humanLog(`    ${run} astryx build "<what you're building>"   build a page — kit: closest template + blocks + components`);
+      humanLog(`    ${run} astryx build                            the how-to-build workflow (read this first)`);
+      humanLog(`    ${run} astryx search <query>                   find anything — components, docs, templates, blocks`);
+      humanLog('');
       return;
     }
 
@@ -242,13 +281,8 @@ export function registerInit(program) {
       // Outro
       p.outro('Design system initialized!');
 
-      humanLog('');
-      humanLog('  Next steps:');
-      humanLog("    1. Import components: import { Button } from '@astryxdesign/core'");
-      humanLog('    2. Optionally add a theme:');
-      humanLog("       import { neutralTheme } from '@astryxdesign/theme-neutral'");
-      humanLog('       <Theme theme={neutralTheme}>...</Theme>');
-      humanLog(`    3. ${run} xds --help for all commands`);
-      humanLog('');
+      for (const line of getNextSteps(run)) {
+        humanLog(line);
+      }
     });
 }

package/src/commands/init.next-steps.test.mjs

@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression test for `astryx init` "Next steps" theme guidance.
+ *
+ * The init command previously steered users toward the slower runtime
+ * style-injection path:
+ *
+ *   import { neutralTheme } from '@astryxdesign/theme-neutral'
+ *   <Theme theme={neutralTheme}>...</Theme>
+ *
+ * ...which contradicted the runtime console warning emitted by core's
+ * <Theme> component (packages/core/src/theme/Theme.tsx) recommending the
+ * pre-built path, and left users with an unstyled app because the base CSS
+ * imports were never mentioned (facebook/astryx#3080).
+ *
+ * These assertions lock in the corrected guidance: base CSS imports, the
+ * pre-built (`/built` + `theme.css`) theme path, and the custom-theme build
+ * command.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {getNextSteps} from './init.mjs';
+
+describe('init Next steps theme guidance', () => {
+  const text = getNextSteps('npx').join('\n');
+
+  it('mentions the base CSS imports so the app is not left unstyled', () => {
+    expect(text).toContain("'@astryxdesign/core/reset.css'");
+    expect(text).toContain("'@astryxdesign/core/astryx.css'");
+  });
+
+  it('uses the pre-built theme path matching the runtime recommendation', () => {
+    expect(text).toContain("'@astryxdesign/theme-neutral/built'");
+    expect(text).toContain("'@astryxdesign/theme-neutral/theme.css'");
+  });
+
+  it('mentions building custom themes via `astryx theme build`', () => {
+    expect(text).toContain('astryx theme build <file>');
+  });
+
+  it('does not steer users to the runtime style-injection import', () => {
+    // The bare source import (no `/built`) is the slow runtime-injection path.
+    expect(text).not.toContain("from '@astryxdesign/theme-neutral'");
+  });
+});

package/src/commands/interactive-guard.test.mjs

@@ -35,7 +35,7 @@ function runCli(args) {
 }
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-interactive-guard-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-interactive-guard-'));
 });
 
 afterEach(() => {

package/src/commands/json-contract.test.mjs

@@ -53,7 +53,7 @@ function parseJson(stdout) {
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-json-contract-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-json-contract-'));
 });
 
 afterEach(() => {
@@ -177,9 +177,16 @@ describe('--json contract: supported commands emit valid envelopes', () => {
   });
 
   it('astryx upgrade --json (already up to date) emits upgrade.status', () => {
-    // Force a no-op range: from > to.
+    // Force a no-op range: from > installed target.
+    const coreDir = path.join(tmpDir, 'node_modules', '@astryxdesign', 'core');
+    fs.mkdirSync(coreDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(coreDir, 'package.json'),
+      JSON.stringify({name: '@astryxdesign/core', version: '0.0.1'}, null, 2),
+    );
+
     const {status, stdout} = runCli(
-      ['upgrade', '--json', '--from', '99.0.0', '--to', '0.0.1'],
+      ['upgrade', '--json', '--from', '99.0.0'],
       {cwd: tmpDir},
     );
     expect(status).toBe(0);