@astryxdesign/cli 0.1.0 → 0.1.1-canary.13763f6

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/init.mjs

@@ -100,7 +100,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;
     }
 
@@ -248,7 +256,7 @@ export function registerInit(program) {
       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(`    3. ${run} astryx --help for all commands`);
       humanLog('');
     });
 }

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);

package/src/commands/swizzle-gap-safety.test.mjs

@@ -36,7 +36,7 @@ let markerFile;
 let baseEnv;
 
 beforeAll(() => {
-  shimDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-gh-shim-'));
+  shimDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-gh-shim-'));
   markerFile = path.join(shimDir, 'gh-issue-create-was-called.marker');
 
   // Sabotaged `gh` shim. Records ONLY `gh issue create` invocations to the

package/src/commands/swizzle.path-safety.test.mjs

@@ -58,7 +58,7 @@ function runCli(args, cwd) {
 
 let tmpDir;
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-swizzle-paths-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-swizzle-paths-'));
 });
 afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});

package/src/commands/template.path-safety.test.mjs

@@ -17,7 +17,7 @@ let tmpDir;
 let templateApi;
 
 beforeEach(async () => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-template-paths-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-paths-'));
   templateApi = (await import('../api/template.mjs')).template;
 });
 afterEach(() => {

package/src/commands/template.test.mjs

@@ -12,7 +12,7 @@ import * as os from 'node:os';
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-template-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-test-'));
 });
 
 afterEach(() => {