@astryxdesign/cli 0.1.8-canary.0c4d8d7 → 0.1.8-canary.0db5dfd

package/{src → cli}/commands/hook/index.mjs

@@ -11,14 +11,29 @@ import {
   formatHookCompact,
   formatHookBrief,
   formatHookParams,
-} from '../../lib/hook-format.mjs';
-import {getCliInvocation} 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 {hook as hookApi} from '../../api/hook.mjs';
-import {findRelatedBlocks} from '../../api/template.mjs';
+} from '../../../lib/hook-format.mjs';
+import {getCliInvocation} 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 {hook as hookApi} from '../../../api/hook/hook.mjs';
+import {findRelatedBlocks} from '../../../api/template/template.mjs';
 
+/**
+ * The api layer's hook() widens its return to `{type: string, data: unknown}`,
+ * so annotate the command-local result with the precise discriminated union from
+ * src/types/hook to get narrowing + typed data.
+ *
+ * @typedef {(
+ *   | import('../../../types/hook').HookListResponse
+ *   | import('../../../types/hook').HookBriefResponse
+ *   | import('../../../types/hook').HookFullResponse
+ *   | import('../../../types/hook').HookDetailResponse
+ *   | import('../../../types/hook').HookDetailParamsResponse
+ * )} HookResult
+ */
+
+/** @param {import('commander').Command} program */
 export function registerHook(program) {
   program
     .command('hook [name]')
@@ -26,7 +41,12 @@ export function registerHook(program) {
     .option('--list', 'List all hooks grouped by category')
     .option('--category <category>', 'List hooks in a specific category')
     .option('--params', 'Print only the parameters table')
-    .action(async (name, options) => {
+    .action(
+      /**
+       * @param {string|undefined} name
+       * @param {{list?: boolean, category?: string, params?: boolean}} options
+       */
+      async (name, options) => {
       const run = getCliInvocation();
       const zh = program.opts().zh || false;
       const lang = program.opts().lang || null;
@@ -43,18 +63,20 @@ export function registerHook(program) {
         return;
       }
 
+      /** @type {HookResult} */
       let result;
       try {
-        result = await hookApi(name, {
+        result = /** @type {HookResult} */ (await hookApi(name, {
           cwd: process.cwd(),
           list: options.list,
           category: options.category,
           params: options.params,
           detail,
           lang, zh,
-        });
+        }));
       } catch (e) {
-        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;
       }
 
@@ -123,6 +145,7 @@ export function registerHook(program) {
           }
           // Show related block templates from relatedComponents
           const relatedComps = result.data.relatedComponents || [];
+          /** @type {import('../../../api/template/template.mjs').DiscoveredTemplate[]} */
           const allBlocks = [];
           for (const comp of relatedComps) {
             const blocks = await findRelatedBlocks(comp);
@@ -152,12 +175,12 @@ export function registerHook(program) {
 }
 
 // Re-export lib functions for external consumers
-export {discoverHooks, findHookDoc, getAllHookNames} from '../../lib/hook-discovery.mjs';
-export {loadDocs} from '../../lib/component-loader.mjs';
+export {discoverHooks, findHookDoc, getAllHookNames} from '../../../lib/hook-discovery.mjs';
+export {loadDocs} from '../../../lib/component-loader.mjs';
 export {
   formatHookFull,
   formatHookCompact,
   formatHookBrief,
   formatHookBriefAll,
   formatHookParams,
-} from '../../lib/hook-format.mjs';
+} from '../../../lib/hook-format.mjs';

package/{src → cli}/commands/import-hint-correctness.test.mjs

@@ -23,7 +23,7 @@ import {
   discoverComponents,
   findComponentSource,
 } from './component/index.mjs';
-import {findCoreDir} from '../utils/paths.mjs';
+import {findCoreDir} from '../../utils/paths.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');

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

@@ -17,14 +17,14 @@
 
 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 {getCliInvocation} from '../utils/package-manager.mjs';
-import {installAgentDocs, removeAgentDocs} from './agent-docs.mjs';
+import {CLI_ROOT} from '../../utils/paths.mjs';
+import {PathSafetyError} from '../../utils/path-safety.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
+import {installAgentDocs, removeAgentDocs} from '../../lib/agent-docs/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 {humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
 const VALID_FEATURES = ['agents', 'theme', 'template'];
 const run = getCliInvocation();
@@ -62,6 +62,10 @@ export function getNextSteps(invocation) {
 
 // ─── Feature: agents ─────────────────────────────────────────────────────────
 
+/**
+ * @param {string} targetDir
+ * @param {{agent?: string, agentDocsPath?: string | string[]}} [opts]
+ */
 function runAgents(targetDir, {agent, agentDocsPath} = {}) {
   try {
     const paths = agentDocsPath
@@ -93,6 +97,10 @@ function runTheme() {
 
 // ─── Feature: template ───────────────────────────────────────────────────────
 
+/**
+ * @param {string} targetDir
+ * @param {{templateName?: string}} [opts]
+ */
 function runTemplate(targetDir, {templateName} = {}) {
   const templates = listTemplates();
   if (templates.length === 0) return;
@@ -124,6 +132,9 @@ function runTemplate(targetDir, {templateName} = {}) {
 
 // ─── Command ─────────────────────────────────────────────────────────────────
 
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerInit(program) {
   program
     .command('init')
@@ -133,7 +144,7 @@ export function registerInit(program) {
     .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((options) => {
+    .action((/** @type {{features?: string, all?: boolean, removeAgents?: boolean, agent?: string, agentDocsPath?: string | string[]}} */ options) => {
       const targetDir = process.cwd();
 
       // Remove mode
@@ -147,7 +158,7 @@ export function registerInit(program) {
       if (options.features || options.all) {
         const features = options.all
           ? VALID_FEATURES
-          : options.features.split(',').map(f => f.trim().toLowerCase());
+          : /** @type {string} */ (options.features).split(',').map(f => f.trim().toLowerCase());
 
         const invalid = features.filter(f => !VALID_FEATURES.includes(f));
         if (invalid.length > 0) {

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

@@ -13,21 +13,55 @@
  */
 
 import * as fs from 'node:fs';
-import {jsonOut, humanLog} from '../lib/json.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {layoutExpand, layoutCheck, layoutGrammar} from '../api/layout.mjs';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {layoutExpand, layoutCheck, layoutGrammar} from '../../api/layout/layout.mjs';
 
-/** Resolve the expression from arg, --file, or stdin ('-'). */
-async function readExpression(expr, options) {
+/**
+ * The api layer's @returns for these functions widen the `type` discriminator
+ * to `string`, so annotate the command-local result with the precise response
+ * shapes from src/types/layout so narrowing + jsonOut typecheck.
+ *
+ * @typedef {import('../../types/layout').LayoutExpandResponse} LayoutExpandResponse
+ * @typedef {import('../../types/layout').LayoutCheckResponse} LayoutCheckResponse
+ * @typedef {import('../../types/layout').LayoutGrammarResponse} LayoutGrammarResponse
+ */
+
+/**
+ * @typedef {object} LayoutExpandOptions
+ * @property {string} [file]
+ * @property {'compact'|'outline'|'auto'} [form]
+ * @property {string} [name]
+ * @property {boolean} [loose]
+ */
+
+/**
+ * @typedef {object} LayoutCheckOptions
+ * @property {string} [file]
+ * @property {'compact'|'outline'|'auto'} [form]
+ * @property {boolean} [loose]
+ */
+
+/**
+ * Resolve the expression from arg, --file, or stdin ('-').
+ * @param {string} [expr]
+ * @param {{file?: string}} [options]
+ * @returns {Promise<string>}
+ */
+async function readExpression(expr, options = {}) {
   if (options.file) return fs.readFileSync(options.file, 'utf-8');
   if (expr === '-') {
+    /** @type {Buffer[]} */
     const chunks = [];
-    for await (const chunk of process.stdin) chunks.push(chunk);
+    for await (const chunk of process.stdin) chunks.push(/** @type {Buffer} */ (chunk));
     return Buffer.concat(chunks).toString('utf-8');
   }
-  return expr;
+  return expr ?? '';
 }
 
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerLayout(program) {
   const layoutCmd = program
     .command('layout')
@@ -40,24 +74,26 @@ export function registerLayout(program) {
     .option('--form <form>', 'Input surface: compact, outline, or auto', 'auto')
     .option('--name <name>', 'Generated component name (PascalCase)', 'GeneratedLayout')
     .option('--loose', 'Downgrade unknown {block} hints to TODO placeholders')
-    .action(async (expression, targetPath, options) => {
+    .action(async (/** @type {string} */ expression, /** @type {string} */ targetPath, /** @type {LayoutExpandOptions} */ options) => {
       const json = program.opts().json || false;
       const source = await readExpression(expression, options);
       if (!source || source.trim() === '') {
         cliError('No layout expression given — pass it as an argument, via --file, or on stdin');
         return;
       }
+      /** @type {LayoutExpandResponse} */
       let result;
       try {
-        result = await layoutExpand(source, {
+        result = /** @type {LayoutExpandResponse} */ (await layoutExpand(source, {
           targetPath,
           form: options.form,
           loose: options.loose || false,
           name: options.name,
           cwd: process.cwd(),
-        });
+        }));
       } catch (e) {
-        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;
       }
       if (json) return jsonOut(result.type, result.data);
@@ -81,22 +117,24 @@ export function registerLayout(program) {
     .option('--file <file>', 'Read the expression from a file')
     .option('--form <form>', 'Input surface: compact, outline, or auto', 'auto')
     .option('--loose', 'Downgrade unknown {block} hints to TODO placeholders')
-    .action(async (expression, options) => {
+    .action(async (/** @type {string} */ expression, /** @type {LayoutCheckOptions} */ options) => {
       const json = program.opts().json || false;
       const source = await readExpression(expression, options);
       if (!source || source.trim() === '') {
         cliError('No layout expression given — pass it as an argument, via --file, or on stdin');
         return;
       }
+      /** @type {LayoutCheckResponse} */
       let result;
       try {
-        result = await layoutCheck(source, {
+        result = /** @type {LayoutCheckResponse} */ (await layoutCheck(source, {
           form: options.form,
           loose: options.loose || false,
           cwd: process.cwd(),
-        });
+        }));
       } catch (e) {
-        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;
       }
       if (json) return jsonOut(result.type, result.data);
@@ -106,7 +144,7 @@ export function registerLayout(program) {
         humanLog(`\n✗ Invalid (${errors.length} error${errors.length === 1 ? '' : 's'}):`);
         for (const e of errors) {
           humanLog(`  - ${e.formatted}`);
-          if (e.suggestions?.length > 0) humanLog(`    did you mean: ${e.suggestions.join(', ')}?`);
+          if (e.suggestions && e.suggestions.length > 0) humanLog(`    did you mean: ${e.suggestions.join(', ')}?`);
         }
         humanLog('');
         process.exitCode = 1;
@@ -126,11 +164,13 @@ export function registerLayout(program) {
     .description('Print the XLE/XLO cheatsheet (alias table generated from this branch)')
     .action(async () => {
       const json = program.opts().json || false;
+      /** @type {LayoutGrammarResponse} */
       let result;
       try {
-        result = await layoutGrammar({cwd: process.cwd()});
+        result = /** @type {LayoutGrammarResponse} */ (await layoutGrammar({cwd: process.cwd()}));
       } catch (e) {
-        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;
       }
       if (json) return jsonOut(result.type, result.data);

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

@@ -16,10 +16,10 @@
  *   astryx search button --json          Typed JSON envelope
  */
 
-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.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,15 +51,19 @@ 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;
       }
 
@@ -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/{src → cli}/commands/setup-nudge.test.mjs

@@ -18,7 +18,7 @@ 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 './agent-docs.mjs';
+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');

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('');
+      }
+    });
+}