@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/src/commands/build.mjs

@@ -1,196 +0,0 @@
-// 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/init.mjs

@@ -1,288 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file init command — Interactive initialization wizard + feature installer
- *
- * Interactive: `astryx init` walks through all features
- * Non-interactive: `astryx init --features agents,theme,template`
- * Re-runnable: safe to run multiple times, idempotent
- *
- * Features:
- *   agents   — Install AGENTS.md/CLAUDE.md cheat sheet for AI coding agents
- *   theme    — Scaffold a custom theme file
- *   template — Copy a starter page template
- */
-
-import * as p from '@clack/prompts';
-import * as path from 'node:path';
-import * as fs from 'node:fs';
-import {CLI_ROOT} from '../utils/paths.mjs';
-import {PathSafetyError} from '../utils/path-safety.mjs';
-import {getRunPrefix} from '../utils/package-manager.mjs';
-import {installAgentDocs, removeAgentDocs} from './agent-docs.mjs';
-import {listTemplates} from './template.mjs';
-import {humanLog} from '../lib/json.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-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.');
-    process.exit(0);
-  }
-  return value;
-}
-
-// ─── Feature: agents ─────────────────────────────────────────────────────────
-
-function runAgents(targetDir, {interactive = true, agent, agentDocsPath} = {}) {
-  try {
-    const paths = agentDocsPath
-      ? Array.isArray(agentDocsPath)
-        ? agentDocsPath
-        : [agentDocsPath]
-      : undefined;
-    const written = installAgentDocs(targetDir, {agent, paths});
-    const summary = written.join(', ');
-    if (interactive) {
-      p.log.success(`AI agent docs installed → ${summary}`);
-    } else {
-      humanLog(`✓ AI agent docs installed → ${summary}`);
-    }
-  } catch (err) {
-    // PathSafetyError carries a precise, user-actionable message —
-    // surface it instead of the generic "could not install" warning so
-    // misconfigured --agent-docs-path values aren't silently swallowed.
-    if (err instanceof PathSafetyError) {
-      const msg = `Error: ${err.message}`;
-      if (interactive) {
-        p.log.error(msg);
-      } else {
-        console.error(msg);
-      }
-      process.exitCode = 1;
-      return;
-    }
-    const msg = `Could not install agent docs. Try again with \`${run} astryx init --features agents\`.`;
-    if (interactive) {
-      p.log.warning(msg);
-    } else {
-      console.error(msg);
-    }
-  }
-}
-
-// ─── Feature: theme ──────────────────────────────────────────────────────────
-
-async function runTheme({interactive = true} = {}) {
-  if (!interactive) {
-    humanLog(`✓ Theme scaffolding requires interactive mode. Run \`${run} astryx theme\` instead.`);
-    return;
-  }
-
-  p.note(
-    'Create a custom theme with your brand colors.\n' +
-    `Run \`${run} astryx theme\` for the full theme wizard.\n` +
-    `Run \`${run} astryx theme --list\` to see existing themes.`,
-    'Themes',
-  );
-}
-
-// ─── Feature: template ───────────────────────────────────────────────────────
-
-async function runTemplate(targetDir, {interactive = true, templateName} = {}) {
-  const templates = listTemplates();
-  if (templates.length === 0) return;
-
-  if (!interactive) {
-    if (!templateName) {
-      // 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;
-    }
-
-    if (!templates.includes(templateName)) {
-      cliError(`Unknown template "${templateName}". Available: ${templates.join(', ')}`, {code: ERROR_CODES.ERR_UNKNOWN_TEMPLATE});
-      return;
-    }
-
-    const outputDir = path.resolve(targetDir, `./src/pages/${templateName}`);
-    const srcPath = path.join(CLI_ROOT, 'templates', 'pages', templateName, 'page.tsx');
-    fs.mkdirSync(outputDir, {recursive: true});
-    fs.copyFileSync(srcPath, path.join(outputDir, 'page.tsx'));
-    humanLog(`✓ Template created at ${path.relative(targetDir, outputDir)}/page.tsx`);
-    return;
-  }
-
-  const TEMPLATE_OPTIONS = [
-    {value: 'skip', label: 'Skip — No template'},
-    {value: 'blank', label: 'Blank Page — Minimal scaffold'},
-    {value: 'table', label: 'Table Page — Data table with actions'},
-    {value: 'login', label: 'Login Page — Auth form with inputs'},
-  ];
-
-  const templateChoice = isCancel(
-    await p.select({
-      message: 'Start with a page template?',
-      options: TEMPLATE_OPTIONS,
-    }),
-  );
-
-  if (templateChoice === 'skip') return;
-
-  const targetPath = isCancel(
-    await p.text({
-      message: 'Where should the template be created?',
-      initialValue: `./src/pages/${templateChoice}`,
-      placeholder: `./src/pages/${templateChoice}`,
-    }),
-  );
-
-  const outputDir = path.resolve(targetDir, targetPath);
-  const srcPath = path.join(CLI_ROOT, 'templates', 'pages', templateChoice, 'page.tsx');
-
-  fs.mkdirSync(outputDir, {recursive: true});
-  fs.copyFileSync(srcPath, path.join(outputDir, 'page.tsx'));
-
-  p.log.success(`Template created at ${path.relative(targetDir, outputDir)}/page.tsx`);
-}
-
-// ─── Command ─────────────────────────────────────────────────────────────────
-
-export function registerInit(program) {
-  program
-    .command('init')
-    .description('Initialize the design system in your project')
-    .option('--features <list>', 'Comma-separated features to install (agents, theme, template)')
-    .option('--all', 'Install all features, no prompts')
-    .option('--remove-agents', 'Remove AI agent docs from all agent doc files')
-    .option('--agent <tool>', 'Target AI tool for agent docs: claude, cursor, codex, hermes, all')
-    .option('--agent-docs-path <path...>', 'Explicit file path(s) for agent docs')
-    .action(async (options) => {
-      const targetDir = process.cwd();
-
-      // Remove mode
-      if (options.removeAgents) {
-        removeAgentDocs(targetDir);
-        humanLog('✓ AI agent docs removed.');
-        return;
-      }
-
-      // Non-interactive: --features or --all
-      if (options.features || options.all) {
-        const features = options.all
-          ? VALID_FEATURES
-          : options.features.split(',').map(f => f.trim().toLowerCase());
-
-        const invalid = features.filter(f => !VALID_FEATURES.includes(f));
-        if (invalid.length > 0) {
-          cliError(`Unknown features: ${invalid.join(', ')}. Valid features: ${VALID_FEATURES.join(', ')}`, {code: ERROR_CODES.ERR_UNKNOWN_FEATURE});
-          return;
-        }
-
-        for (const feature of features) {
-          if (feature === 'agents') runAgents(targetDir, {
-            interactive: false,
-            agent: options.agent,
-            agentDocsPath: options.agentDocsPath,
-          });
-          if (feature === 'theme') await runTheme({interactive: false});
-          if (feature === 'template') await runTemplate(targetDir, {interactive: false});
-        }
-        return;
-      }
-
-      // Interactive wizard
-      //
-      // Guard: this wizard blocks on prompts. In a non-interactive context
-      // (CI, piped stdin/stdout, no TTY) it would hang forever. Fail fast
-      // with actionable guidance via the shared interactivity contract.
-      requireInteractive({
-        command: 'init',
-        hint: `\`${run} astryx init --all\` or \`--features agents,theme,template\``,
-      });
-
-      p.intro('Welcome to the design system');
-
-      p.note(
-        'A design system for building internal tools\nwith 300+ React components.',
-        'About',
-      );
-
-      // Feature: agents
-      const shouldInstallAgents = isCancel(
-        await p.confirm({
-          message: 'Install AI agent support? (adds a design system cheat sheet to AGENTS.md)',
-          initialValue: true,
-        }),
-      );
-
-      if (shouldInstallAgents) {
-        const s = p.spinner();
-        s.start('Installing agent docs');
-        runAgents(targetDir);
-        s.stop('Done');
-      }
-
-      // Feature: swizzle awareness
-      p.note(
-        `You can customize any component with:\n  ${run} astryx swizzle Button\n  ${run} astryx swizzle --list`,
-        'Component Customization',
-      );
-
-      // Feature: template
-      await runTemplate(targetDir);
-
-      // Feature: theme awareness
-      await runTheme();
-
-      // Outro
-      p.outro('Design system initialized!');
-
-      for (const line of getNextSteps(run)) {
-        humanLog(line);
-      }
-    });
-}

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

@@ -1,69 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Subprocess no-hang tests for the interactivity contract.
- *
- * The wizard command `init` blocks on @clack/prompts. In a
- * non-interactive context it must fail fast (exit 1) instead of hanging.
- * These tests spawn the CLI as a real subprocess with stdin/stdout NOT a TTY
- * (stdio 'ignore'/'pipe'), which is exactly the CI / piped condition. If the
- * guard were missing, spawnSync would hit the timeout (signal SIGTERM,
- * status null) — so asserting `signal === null && status === 1` proves the
- * process exited cleanly rather than hanging.
- */
-
-import {describe, it, expect, beforeEach, afterEach} from 'vitest';
-import {spawnSync} 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 = path.resolve(__dirname, '..', '..', 'bin', 'astryx.mjs');
-
-let tmpDir;
-
-function runCli(args) {
-  return spawnSync(process.execPath, [CLI, ...args], {
-    cwd: tmpDir,
-    encoding: 'utf8',
-    timeout: 20_000,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    env: {...process.env, FORCE_COLOR: '0', CI: ''},
-  });
-}
-
-beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-interactive-guard-'));
-});
-
-afterEach(() => {
-  fs.rmSync(tmpDir, {recursive: true, force: true});
-});
-
-describe('init non-interactive safety', () => {
-  it('fails fast (exit 1, no hang) and writes no files', () => {
-    const r = runCli(['init']);
-    expect(r.signal).toBeNull();
-    expect(r.status).toBe(1);
-    expect(fs.readdirSync(tmpDir)).toEqual([]);
-  });
-
-  it('prints actionable guidance (--all / --features)', () => {
-    const out = (() => {
-      const r = runCli(['init']);
-      return r.stderr + r.stdout;
-    })();
-    expect(out).toMatch(/requires a TTY/i);
-    expect(out).toMatch(/--all/);
-    expect(out).toMatch(/--features/);
-  });
-
-  it('still runs --features agents non-interactively (guard does not over-catch)', () => {
-    const r = runCli(['init', '--features', 'agents']);
-    expect(r.signal).toBeNull();
-    expect(r.status).toBe(0);
-    expect(fs.readdirSync(tmpDir).length).toBeGreaterThan(0);
-  });
-});