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

package/{src → cli}/commands/search.mjs

@@ -16,10 +16,10 @@
  *   astryx search button --json          Typed JSON envelope
  */
 
-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, SEARCH_DOMAINS} from '../api/search.mjs';
+import {getCliInvocation, formatCliCommand} from '../../utils/package-manager.mjs';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {search as searchApi, SEARCH_DOMAINS} from '../../api/search/search.mjs';
 
 const DOMAIN_LABEL = {
   component: 'component',
@@ -28,6 +28,9 @@ const DOMAIN_LABEL = {
   template: 'template',
 };
 
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerSearch(program) {
   program
     .command('search <query>')
@@ -35,7 +38,7 @@ export function registerSearch(program) {
     .option('--type <domain>', `Filter to one domain (${SEARCH_DOMAINS.join('|')})`)
     .option('--limit <n>', 'Max number of results (default 20)')
     .option('--detail', 'Verbose output (include import paths and match reason)')
-    .action(async (query, options) => {
+    .action(async (/** @type {string} */ query, /** @type {{type?: import('../../types/search').SearchDomain, limit?: string, detail?: boolean}} */ options) => {
       const json = program.opts().json || false;
 
       let limit = 20;
@@ -48,22 +51,26 @@ export function registerSearch(program) {
         limit = parsed;
       }
 
+      /** @type {import('../../types/search').SearchResponse} */
       let result;
       try {
-        result = await searchApi(query, {
-          cwd: process.cwd(),
-          type: options.type,
-          limit,
-        });
+        result = /** @type {import('../../types/search').SearchResponse} */ (
+          await searchApi(query, {
+            cwd: process.cwd(),
+            type: options.type,
+            limit,
+          })
+        );
       } catch (e) {
-        cliError(e.message, {suggestions: e.suggestions});
+        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {suggestions: err.suggestions});
         return;
       }
 
       if (json) return jsonOut(result.type, result.data);
 
       // ── Text output ──────────────────────────────────────────────
-      const run = getRunPrefix();
+      const run = getCliInvocation();
       const {query: q, results} = result.data;
 
       // No matches is a valid, successful outcome — clean message, exit 0.
@@ -71,7 +78,7 @@ export function registerSearch(program) {
         humanLog('');
         humanLog(`No results for "${q}".`);
         humanLog('');
-        humanLog(`Try a broader term, or browse: ${run} astryx component --list`);
+        humanLog(`Try a broader term, or browse: ${run} component --list`);
         humanLog('');
         return;
       }
@@ -86,7 +93,7 @@ export function registerSearch(program) {
         if (r.description) {
           humanLog(`               ${r.description}`);
         }
-        humanLog(`               → ${run} ${r.command}`);
+        humanLog(`               → ${formatCliCommand(r.command)}`);
         if (options.detail) {
           if (r.import) humanLog(`               import: ${r.import}`);
           humanLog(`               match: ${r.reason} (score ${r.score})`);
@@ -97,4 +104,4 @@ export function registerSearch(program) {
 }
 
 // Re-export the API for external consumers.
-export {search, SEARCH_DOMAINS} from '../api/search.mjs';
+export {search, SEARCH_DOMAINS} from '../../api/search/search.mjs';

package/{src → cli}/commands/search.test.mjs

@@ -14,7 +14,7 @@ import {describe, it, expect} from 'vitest';
 import {spawnSync} from 'node:child_process';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
-import {search, scoreCandidate, SEARCH_DOMAINS} from '../api/search.mjs';
+import {search, scoreCandidate, SEARCH_DOMAINS} from '../../api/search/search.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');

package/cli/commands/setup-nudge.test.mjs

@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Guardrail tests — the centralized setup check + enforcement layer 3.
+ *
+ * Unit: isAstryxInitialized() detects the Astryx marker across EVERY agent-doc
+ * location (including the previously-missed Hermes files) and legacy XDS blocks.
+ *
+ * Integration: the CLI nudges (stderr) before a command when the project hasn't
+ * run init — INCLUDING in --json mode (agents pass --json, and stderr never
+ * corrupts the stdout JSON envelope). Quiet once set up, outside a project, and
+ * for the installer command itself.
+ */
+
+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';
+import {isAstryxInitialized} from '../../lib/agent-docs/agent-docs.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI = path.resolve(__dirname, '..', '..', 'bin', 'astryx.mjs');
+const MARKER = '<!-- ASTRYX:START -->';
+const NUDGE = /finish setup and install the Astryx agent prompt/;
+
+let tmp;
+beforeEach(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-setup-nudge-'));
+});
+afterEach(() => {
+  fs.rmSync(tmp, {recursive: true, force: true});
+});
+
+function write(rel, body) {
+  const p = path.join(tmp, rel);
+  fs.mkdirSync(path.dirname(p), {recursive: true});
+  fs.writeFileSync(p, body);
+}
+
+function run(args, cwd = tmp) {
+  return spawnSync(process.execPath, [CLI, ...args], {
+    cwd,
+    encoding: 'utf8',
+    timeout: 30_000,
+    env: {...process.env, FORCE_COLOR: '0'},
+  });
+}
+
+describe('isAstryxInitialized — centralized setup check (one place)', () => {
+  it('is false in an empty project', () => {
+    expect(isAstryxInitialized(tmp)).toBe(false);
+  });
+
+  // Covers EVERY location a preset can write — .hermes.md/HERMES.md were the gap.
+  it.each(['AGENTS.md', 'CLAUDE.md', '.claude/CLAUDE.md', '.cursorrules', '.hermes.md', 'HERMES.md'])(
+    'detects the marker in %s',
+    file => {
+      write(file, `# doc\n${MARKER}\nbody`);
+      expect(isAstryxInitialized(tmp)).toBe(true);
+    },
+  );
+
+  it('detects the legacy XDS marker for back-compat', () => {
+    write('AGENTS.md', '<!-- XDS:START -->');
+    expect(isAstryxInitialized(tmp)).toBe(true);
+  });
+
+  it('is false when a doc file exists WITHOUT the marker', () => {
+    write('AGENTS.md', 'project notes, no astryx block');
+    expect(isAstryxInitialized(tmp)).toBe(false);
+  });
+});
+
+describe('enforcement layer 3 — per-command setup nudge', () => {
+  const asProject = () => write('package.json', '{"name":"t"}');
+
+  it('nudges on stderr after a command when not set up', () => {
+    asProject();
+    const r = run(['docs', 'tokens']);
+    expect(r.stderr).toMatch(NUDGE);
+  });
+
+  it('is suppressed in --json (machine mode stays clean), stdout valid JSON', () => {
+    asProject();
+    const r = run(['--json', 'docs', 'tokens']);
+    // --json is machine output with a clean stdout+stderr contract; the human
+    // nudge must NOT leak into it (json-shim: error envelopes have empty stderr).
+    expect(r.stderr).not.toMatch(NUDGE);
+    expect(() => JSON.parse(r.stdout)).not.toThrow();
+  });
+
+  it('is quiet once set up (marker present)', () => {
+    asProject();
+    write('AGENTS.md', MARKER);
+    expect(run(['docs', 'tokens']).stderr).not.toMatch(NUDGE);
+  });
+
+  it('is quiet outside a project (no package.json)', () => {
+    expect(run(['docs', 'tokens']).stderr).not.toMatch(NUDGE);
+  });
+
+  it('does not nudge for the installer command itself', () => {
+    asProject();
+    expect(run(['init']).stderr).not.toMatch(NUDGE);
+  });
+});

package/cli/commands/swizzle.mjs

@@ -0,0 +1,103 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file swizzle command — thin wrapper around api/swizzle.
+ *
+ * Copies a component's source into the consumer project for customization
+ * (imports rewritten to the owner package's subpaths). All logic — owner
+ * resolution, copy, import rewriting, StyleX detection, maintainer feedback —
+ * lives in api/swizzle; this file only parses flags, prints, and prefixes
+ * commands for the caller's package manager.
+ */
+
+import {jsonOut, humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
+import {swizzle as swizzleApi} from '../../api/swizzle/swizzle.mjs';
+
+/**
+ * @param {import('commander').Command} program
+ */
+export function registerSwizzle(program) {
+  program
+    .command('swizzle [component]')
+    .description('Copy component source for customization')
+    .option('--output <dir>', 'Output directory', './components/astryx')
+    .option('--package <pkg>', 'Scope to a specific owning package')
+    .option('--list', 'List available components')
+    .option('-f, --overwrite', 'Overwrite existing files without prompting')
+    .action(async (/** @type {string | undefined} */ component, /** @type {{output: string, package?: string, list?: boolean, overwrite?: boolean}} */ options) => {
+      const json = program.opts().json || false;
+      const run = getCliInvocation();
+
+      /** @type {import('../../types/swizzle').SwizzleListResponse | import('../../types/swizzle').SwizzleCopyResponse} */
+      let result;
+      try {
+        result = await swizzleApi(component, {
+          cwd: process.cwd(),
+          output: options.output,
+          package: options.package,
+          list: options.list,
+          overwrite: options.overwrite,
+        });
+      } catch (e) {
+        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {suggestions: err.suggestions, code: err.code});
+        return;
+      }
+
+      if (json) return jsonOut(result.type, result.data);
+
+      if (result.type === 'swizzle.list') {
+        const components = result.data;
+        humanLog('\nAvailable components:\n');
+        for (const name of components) {
+          humanLog(`  ${name}`);
+        }
+        humanLog(`\nUsage: ${run} swizzle <component>\n`);
+        humanLog(`Example: ${run} swizzle Button`);
+        humanLog(`         ${run} swizzle XDSButton  (XDS prefix also works)\n`);
+        return;
+      }
+
+      const {package: ownerPackage, outputDir, filesCopied, usesStyleX, feedback} =
+        result.data;
+
+      humanLog(`\n✓ Copied ${filesCopied} files to ${outputDir}/\n`);
+      humanLog(`Relative imports have been rewritten to use ${ownerPackage}.`);
+      humanLog('You can now customize the component source freely.\n');
+
+      // StyleX build requirement — swizzled StyleX source renders unstyled with
+      // no error unless the consumer's build runs a StyleX compiler.
+      if (usesStyleX) {
+        humanLog(
+          '⚠ These components use StyleX and require a StyleX compiler in your build.',
+        );
+        humanLog(
+          '  Without one they render unstyled (no error). See setup per framework:',
+        );
+        humanLog(`  ${run} docs styling`);
+        humanLog(
+          '  Next.js note: the StyleX Babel plugin disables SWC and breaks next/font —',
+        );
+        humanLog(
+          '  use an SWC-based StyleX transform instead (covered in the guide).',
+        );
+        humanLog('');
+      }
+
+      // Maintainer feedback note (skipped when the owner ships no issues URL).
+      if (feedback) {
+        humanLog(
+          'Customizing a component often signals a gap in the design system.',
+        );
+        humanLog('Let the maintainers know what you needed:');
+        if (feedback.ghCommand) {
+          humanLog(`  ${feedback.ghCommand}`);
+        } else {
+          humanLog(`  ${feedback.issuesUrl}`);
+        }
+        humanLog('');
+      }
+    });
+}

package/{src → cli}/commands/template.mjs

@@ -6,25 +6,44 @@
 
 import * as path from 'node:path';
 import * as fs from 'node:fs';
-import * as p from '@clack/prompts';
-import {isNonInteractive} from '../utils/path-safety.mjs';
-import {jsonOut, humanLog} from '../lib/json.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {template as templateApi} from '../api/template.mjs';
-import {Project} from '../lib/project.mjs';
-import {warnOnIntegrationIssues} from '../lib/integration-warnings.mjs';
-
-export {discoverTemplates, listTemplates} from '../api/template.mjs';
-
-function isCancel(value) {
-  if (p.isCancel(value)) {
-    p.cancel('Cancelled.');
-    process.exit(0);
-  }
-  return value;
-}
+import {jsonOut, humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {template as templateApi} from '../../api/template/template.mjs';
+import {Project} from '../../lib/project.mjs';
+import {warnOnIntegrationIssues} from '../../lib/integration-warnings.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
+
+export {discoverTemplates, listTemplates} from '../../api/template/template.mjs';
+
+/**
+ * A template entry as produced by the discover* helpers in api/template.mjs.
+ * The api layer returns these as `object[]`; this local shape captures the
+ * fields the command consumes. Remove once api/template.mjs exports a precise
+ * type for its discovered templates.
+ * @typedef {object} DiscoveredTemplate
+ * @property {'page' | 'block'} type
+ * @property {string} dirName
+ * @property {string} name
+ * @property {string} filePath
+ */
+
+/**
+ * The discriminated response returned by the template API. The api layer
+ * currently declares `{type: string, data: unknown}`; narrow it here to the
+ * precise union so the switch below type-checks. Replace with the api's own
+ * return type once it is tightened.
+ * @typedef {(
+ *   import('../../types/template').TemplateListResponse |
+ *   import('../../types/template').TemplateShowResponse |
+ *   import('../../types/template').TemplateSkeletonResponse |
+ *   import('../../types/template').TemplateCopyResponse
+ * )} TemplateResponse
+ */
 
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerTemplate(program) {
   program
     .command('template [name] [path]')
@@ -34,15 +53,27 @@ export function registerTemplate(program) {
     .option('--package <pkg>', 'Narrow to templates from a specific package')
     .option('--skeleton', 'Show layout skeleton with spatial annotations (padding, gap, nesting)')
     .option('-f, --overwrite', 'Overwrite existing files without prompting')
-    .action(async (name, targetPath, options) => {
+    .action(
+      /**
+       * @param {string | undefined} name
+       * @param {string | undefined} targetPath
+       * @param {{list?: boolean, type?: string, package?: string, skeleton?: boolean, overwrite?: boolean}} options
+       */
+      async (name, targetPath, options) => {
       const json = program.opts().json || false;
+      const run = getCliInvocation();
 
       // Non-blocking nudge: if any configured integration has validation
       // issues, print one compact line to stderr pointing at
       // validate-integration. Best-effort; suppressed in --json mode.
       try {
         const project = await Project.load(process.cwd());
-        await warnOnIntegrationIssues(project.loadedIntegrations, {json});
+        await warnOnIntegrationIssues(
+          /** @type {Array<import('../../lib/integrations.mjs').LoadedIntegration>} */ (
+            project.loadedIntegrations
+          ),
+          {json},
+        );
       } catch {
         // Never let the nudge break the command.
       }
@@ -59,40 +90,32 @@ export function registerTemplate(program) {
         const collision = await detectTemplateCollision(name, targetPath);
         if (collision && !options.overwrite) {
           const rel = path.relative(process.cwd(), collision) || collision;
-          if (json || isNonInteractive({json})) {
-            const msg =
-              `Refusing to overwrite existing file ${rel}. ` +
-              `Re-run with --overwrite (or -f) to replace it.`;
-            cliError(msg, {code: ERROR_CODES.ERR_FILE_EXISTS});
-            return;
-          }
-          const confirmed = isCancel(
-            await p.confirm({
-              message: `Overwrite existing file ${rel}?`,
-              initialValue: false,
-            }),
-          );
-          if (!confirmed) {
-            humanLog('Aborted. Re-run with --overwrite to replace the file.');
-            return;
-          }
+          const msg =
+            `Refusing to overwrite existing file ${rel}. ` +
+            `Re-run with --overwrite (or -f) to replace it.`;
+          cliError(msg, {code: ERROR_CODES.ERR_FILE_EXISTS});
+          return;
         }
       }
 
+      /** @type {TemplateResponse} */
       let result;
       try {
-        result = await templateApi(name, {
-          list: options.list,
-          skeleton: options.skeleton,
-          type: options.type,
-          package: options.package,
-          targetPath,
-          cwd: process.cwd(),
-        });
+        result = /** @type {TemplateResponse} */ (
+          await templateApi(name, {
+            list: options.list,
+            skeleton: options.skeleton,
+            type: /** @type {'page' | 'block' | undefined} */ (options.type),
+            package: options.package,
+            targetPath,
+            cwd: process.cwd(),
+          })
+        );
       } catch (e) {
         // template API throws structured errors with {name, reason} suggestions —
         // pass them through untouched so the CLI envelope matches the API.
-        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
+        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
         return;
       }
 
@@ -102,6 +125,7 @@ export function registerTemplate(program) {
         case 'template.list': {
           const pages = result.data.filter(t => t.type === 'page');
           const blocks = result.data.filter(t => t.type === 'block');
+          /** @param {import('../../types/template').TemplateListEntry} t */
           const renderEntry = t => {
             const status = t.isReady ? '' : ' (WIP)';
             const pkg =
@@ -120,10 +144,10 @@ export function registerTemplate(program) {
             for (const t of blocks) renderEntry(t);
           }
           humanLog('\nUsage:');
-          humanLog('  astryx template <id> [target-path]     Scaffold page or block');
-          humanLog('  astryx template <id> --skeleton        Layout reference');
-          humanLog('  astryx template --list --type block    List only blocks');
-          humanLog('  astryx template --list --package <pkg> List from one package\n');
+          humanLog(`  ${run} template <id> [target-path]     Scaffold page or block`);
+          humanLog(`  ${run} template <id> --skeleton        Layout reference`);
+          humanLog(`  ${run} template --list --type block    List only blocks`);
+          humanLog(`  ${run} template --list --package <pkg> List from one package\n`);
           break;
         }
 
@@ -159,12 +183,19 @@ export function registerTemplate(program) {
  * Path-safety enforcement happens inside the API; here we only need
  * enough precision to check existence — a false negative just means the
  * API will catch the issue and abort.
+ *
+ * @param {string} name
+ * @param {string} targetPath
+ * @returns {Promise<string | null>}
  */
 async function detectTemplateCollision(name, targetPath) {
-  const {discoverTemplates} = await import('../api/template.mjs');
+  const {discoverTemplates} = await import('../../api/template/template.mjs');
+  /** @type {DiscoveredTemplate[]} */
   let templates;
   try {
-    templates = await discoverTemplates(process.cwd());
+    templates = /** @type {DiscoveredTemplate[]} */ (
+      await discoverTemplates(process.cwd())
+    );
   } catch {
     return null;
   }
@@ -177,7 +208,7 @@ async function detectTemplateCollision(name, targetPath) {
   const resolved = path.resolve(process.cwd(), targetPath);
 
   // File-arg branch: targetPath looks like `./foo.tsx`.
-  const {isFilePathArg} = await import('../utils/path-safety.mjs');
+  const {isFilePathArg} = await import('../../utils/path-safety.mjs');
   let dest;
   if (isFilePathArg(targetPath)) {
     dest = resolved;

package/{src → cli}/commands/template.path-safety.test.mjs

@@ -18,7 +18,7 @@ let templateApi;
 
 beforeEach(async () => {
   tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-paths-'));
-  templateApi = (await import('../api/template.mjs')).template;
+  templateApi = (await import('../../api/template/template.mjs')).template;
 });
 afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});
@@ -57,7 +57,7 @@ describe('template path safety', () => {
     fs.mkdirSync(cwd, {recursive: true});
 
     // Use a real template name from the discovered set.
-    const {discoverTemplates} = await import('../api/template.mjs');
+    const {discoverTemplates} = await import('../../api/template/template.mjs');
     const all = await discoverTemplates();
     const page = all.find(t => t.type === 'page');
     if (!page) {

package/{src → cli}/commands/upgrade.integration-policy.test.mjs

@@ -26,7 +26,7 @@ let errCalls;
 let exitCode;
 
 const codemodModuleUrl = pathToFileURL(
-  path.resolve(process.cwd(), 'packages/cli/src/codemod.mjs'),
+  path.resolve(process.cwd(), 'packages/cli/authoring/codemod.mjs'),
 ).href;
 
 beforeEach(() => {