@astryxdesign/cli 0.0.0-bootstrap.0 → 0.0.15

package/src/api/error.mjs

@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file API error class — carries structured error info matching CLIError shape.
+ *
+ * `AstryxError` is what the API layer throws. Alongside the human-readable
+ * message and optional `suggestions`, it carries a stable machine-readable
+ * `code` (see ../lib/error-codes.mjs). When the CLI catches an AstryxError and
+ * routes it through `cliError`, it propagates `e.code` so the JSON error
+ * envelope's `code` field matches the API contract exactly. The code defaults
+ * to `ERR_UNKNOWN` so older throw sites still produce a valid envelope.
+ */
+
+import {ERROR_CODES} from '../lib/error-codes.mjs';
+
+export class AstryxError extends Error {
+  /** @type {Array<{name: string, reason: string}> | undefined} */
+  suggestions;
+
+  /**
+   * Stable, machine-readable error code (error-codes.mjs). Consumers branch
+   * on this, never on the message text.
+   * @type {string}
+   */
+  code;
+
+  /**
+   * @param {string} message
+   * @param {Array<{name: string, reason: string}>} [suggestions]
+   * @param {string} [code] - Stable error code. Defaults to ERR_UNKNOWN.
+   */
+  constructor(message, suggestions, code) {
+    super(message);
+    this.name = 'AstryxError';
+    this.code = code || ERROR_CODES.ERR_UNKNOWN;
+    if (suggestions?.length) this.suggestions = suggestions;
+  }
+}

package/src/api/hook.mjs

@@ -0,0 +1,196 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Programmatic API for the hook command.
+ *
+ * Returns the same typed envelope { type, data } that `astryx --json hook` outputs.
+ * The CLI command handler is a thin wrapper around this function.
+ */
+
+import {findCoreDir} from '../utils/paths.mjs';
+import {discoverHooks, findHookDoc, getAllHookNames} from '../lib/hook-discovery.mjs';
+import {loadDocs} from '../lib/component-loader.mjs';
+import {levenshteinDistance} from '../lib/string-utils.mjs';
+import {AstryxError} from './error.mjs';
+import {ERROR_CODES} from '../lib/error-codes.mjs';
+
+/**
+ * @param {string} [name]
+ * @param {object} [options]
+ * @param {string} [options.cwd]
+ * @param {boolean} [options.list]
+ * @param {string} [options.category]
+ * @param {boolean} [options.params]
+ * @param {'full'|'compact'|'brief'} [options.detail] - Defaults to 'full' for a single hook, 'brief' for list views (list/category/no name), matching the CLI.
+ * @param {string} [options.lang]
+ * @param {boolean} [options.zh]
+ * @returns {Promise<{type: string, data: unknown}>}
+ */
+export async function hook(name, options = {}) {
+  const {
+    cwd = process.cwd(),
+    list = false,
+    category,
+    params = false,
+    detail: detailOption,
+    lang = null,
+    zh = false,
+  } = options;
+
+  // Default detail level mirrors the CLI (see commands/hook/index.mjs):
+  // single-hook views default to 'full', list-style views (--list,
+  // --category, or no name) default to 'brief' (scannable name lists).
+  // Keeping this in sync with the CLI is what the API↔CLI parity test checks.
+  const isListView = list || category != null || !name;
+  const detail = detailOption ?? (isListView ? 'brief' : 'full');
+
+  const coreDir = findCoreDir(cwd);
+  if (!coreDir) {
+    throw new AstryxError('Could not find @astryxdesign/core package', undefined, ERROR_CODES.ERR_CORE_NOT_FOUND);
+  }
+
+  // ── List mode ──────────────────────────────────────────────────
+
+  if (category || list || !name) {
+    const hooks = discoverHooks(coreDir);
+
+    if (category) {
+      const match = Object.entries(hooks).find(
+        ([key]) => key.toLowerCase() === category.toLowerCase(),
+      );
+      if (!match) {
+        throw new AstryxError(
+          `Unknown category "${category}"`,
+          Object.keys(hooks).map(k => ({name: k, reason: 'valid category'})),
+          ERROR_CODES.ERR_UNKNOWN_CATEGORY,
+        );
+      }
+
+      if (detail === 'compact') {
+        const entries = [];
+        for (const hookName of match[1]) {
+          const docPath = findHookDoc(coreDir, hookName);
+          if (docPath) {
+            try {
+              const docs = await loadDocs(docPath, {zh, lang});
+              entries.push({
+                name: hookName,
+                description: docs.usage?.description || '',
+                import: docs.importPath || '@astryxdesign/core/hooks',
+              });
+            } catch {
+              entries.push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+            }
+          } else {
+            entries.push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+          }
+        }
+        return {type: 'hook.brief', data: {[match[0]]: entries}};
+      }
+
+      if (detail === 'full') {
+        const entries = [];
+        for (const hookName of match[1]) {
+          const docPath = findHookDoc(coreDir, hookName);
+          if (docPath) {
+            try {
+              entries.push(await loadDocs(docPath, {zh, lang}));
+            } catch {
+              entries.push({name: hookName});
+            }
+          } else {
+            entries.push({name: hookName});
+          }
+        }
+        return {type: 'hook.full', data: {[match[0]]: entries}};
+      }
+
+      // Default: brief — names only
+      return {type: 'hook.list', data: {[match[0]]: match[1]}};
+    }
+
+    // All hooks
+    if (detail === 'compact') {
+      /** @type {Record<string, Array<{name: string, description: string, import: string}>>} */
+      const result = {};
+      for (const [cat, hookNames] of Object.entries(hooks)) {
+        result[cat] = [];
+        for (const hookName of hookNames) {
+          const docPath = findHookDoc(coreDir, hookName);
+          if (docPath) {
+            try {
+              const docs = await loadDocs(docPath, {zh, lang});
+              result[cat].push({
+                name: hookName,
+                description: docs.usage?.description || '',
+                import: docs.importPath || '@astryxdesign/core/hooks',
+              });
+            } catch {
+              result[cat].push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+            }
+          } else {
+            result[cat].push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+          }
+        }
+      }
+      return {type: 'hook.brief', data: result};
+    }
+
+    if (detail === 'full') {
+      /** @type {Record<string, Array<unknown>>} */
+      const result = {};
+      for (const [cat, hookNames] of Object.entries(hooks)) {
+        result[cat] = [];
+        for (const hookName of hookNames) {
+          const docPath = findHookDoc(coreDir, hookName);
+          if (docPath) {
+            try {
+              result[cat].push(await loadDocs(docPath, {zh, lang}));
+            } catch {
+              result[cat].push({name: hookName});
+            }
+          } else {
+            result[cat].push({name: hookName});
+          }
+        }
+      }
+      return {type: 'hook.full', data: result};
+    }
+
+    // Default: brief — names only
+    return {type: 'hook.list', data: hooks};
+  }
+
+  // ── Single hook ────────────────────────────────────────────────
+
+  const docPath = findHookDoc(coreDir, name);
+
+  if (!docPath) {
+    // Fuzzy search for suggestions
+    const allNames = getAllHookNames(coreDir);
+    const needle = name.toLowerCase();
+    const suggestions = allNames
+      .map(hookName => ({
+        name: hookName,
+        distance: levenshteinDistance(needle, hookName.toLowerCase()),
+      }))
+      .filter(m => m.distance <= 5)
+      .sort((a, b) => a.distance - b.distance)
+      .slice(0, 5)
+      .map(m => ({name: m.name, reason: `similar name (distance ${m.distance})`}));
+
+    throw new AstryxError(
+      `No hook named "${name}"`,
+      suggestions,
+      ERROR_CODES.ERR_UNKNOWN_HOOK,
+    );
+  }
+
+  const docs = await loadDocs(docPath, {zh, lang});
+
+  if (params) {
+    return {type: 'hook.detail.params', data: docs.params || []};
+  }
+
+  return {type: 'hook.detail', data: docs};
+}

package/src/api/index.mjs

@@ -0,0 +1,29 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Programmatic API for the Astryx CLI.
+ *
+ * Every function returns the same { type, data } envelope that `xds --json` outputs.
+ * Errors throw AstryxError (with optional .suggestions).
+ *
+ * @example
+ * import { component, docs, hook, AstryxError } from '@astryxdesign/cli/api';
+ *
+ * const result = await component('Button');
+ * // { type: 'component.detail', data: { name: 'Button', ... } }
+ *
+ * const list = await component(undefined, { list: true });
+ * // { type: 'component.list', data: { Layout: [...], ... } }
+ *
+ * const useMediaQuery = await hook('useMediaQuery');
+ * // { type: 'hook.detail', data: { name: 'useMediaQuery', ... } }
+ */
+
+export {component} from './component.mjs';
+export {docs} from './docs.mjs';
+export {discover} from './discover.mjs';
+export {template} from './template.mjs';
+export {hook} from './hook.mjs';
+export {search} from './search.mjs';
+export {doctor} from './doctor.mjs';
+export {AstryxError} from './error.mjs';

package/src/api/search.mjs

@@ -0,0 +1,363 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Programmatic API for the unified `search` command.
+ *
+ * Returns the same typed envelope { type, data } that `xds --json search`
+ * outputs. The CLI command handler is a thin wrapper around this function.
+ *
+ * `search(query)` is the single "I'm looking for X" entry point across ALL
+ * content domains — components, hooks, docs topics, and templates (page +
+ * block). Today, finding the right thing requires four separate list calls
+ * (`component --list`, `hook --list`, `docs`, `template --list`) plus manual
+ * scanning; this collapses them into one ranked, typed result set.
+ *
+ * Scoring is keyword + fuzzy ranking (NOT semantic / embeddings — that is a
+ * deliberate future follow-up). It reuses the same signal weighting as the
+ * component fuzzy resolver in lib/string-utils.mjs:
+ *
+ *   100  exact name match
+ *    90  exact keyword match
+ *    80  name Levenshtein distance 1
+ *    70  keyword substring / distance 1
+ *    60  name substring (>=4 chars, >=50% coverage)
+ *    50  description / prose mentions the term
+ *    40  name Levenshtein distance 2
+ *    30  keyword Levenshtein distance 2
+ *    20  name Levenshtein distance 3
+ *
+ * Name + keyword signals always outweigh description/prose, so an exact match
+ * sorts above an incidental mention.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {findCoreDir, CLI_ROOT} from '../utils/paths.mjs';
+import {
+  discoverComponents,
+  findComponentReadme,
+  resolveImportPath,
+} from '../lib/component-discovery.mjs';
+import {discoverHooks, findHookDoc} from '../lib/hook-discovery.mjs';
+import {levenshteinDistance} from '../lib/string-utils.mjs';
+import {discoverTemplates} from './template.mjs';
+import {AstryxError} from './error.mjs';
+
+const DOCS_DIR = path.join(CLI_ROOT, 'docs');
+
+/** Valid domain filters for `--type`. */
+export const SEARCH_DOMAINS = ['component', 'hook', 'doc', 'template'];
+
+/**
+ * Score a single candidate against the search term across name, keywords,
+ * and prose signals. Returns the best (highest) score plus a human reason,
+ * or null if nothing matched above the floor.
+ *
+ * @param {string} term - Lowercased search term.
+ * @param {object} candidate
+ * @param {string} candidate.name - Primary identifier (component/hook name, topic, template name).
+ * @param {string[]} [candidate.keywords]
+ * @param {string} [candidate.description]
+ * @param {string[]} [candidate.prose] - Extra free-text blobs (doc section text, best practices).
+ * @returns {{score: number, reason: string} | null}
+ */
+export function scoreCandidate(term, {name, keywords = [], description = '', prose = []}) {
+  let best = 0;
+  let reason = '';
+  const consider = (score, why) => {
+    if (score > best) {
+      best = score;
+      reason = why;
+    }
+  };
+
+  const nameLower = name.toLowerCase();
+
+  // ── Name signals ────────────────────────────────────────────────
+  if (nameLower === term) {
+    consider(100, 'exact name');
+  } else {
+    // Substring (both directions), min 4 chars, >=50% coverage.
+    const shorter = term.length < nameLower.length ? term : nameLower;
+    const longer = term.length < nameLower.length ? nameLower : term;
+    if (shorter.length >= 4 && longer.includes(shorter) && shorter.length / longer.length >= 0.5) {
+      consider(60, `name contains "${shorter}"`);
+    }
+    const dist = levenshteinDistance(term, nameLower);
+    if (dist === 1) consider(80, `similar name (distance ${dist})`);
+    else if (dist === 2) consider(40, `similar name (distance ${dist})`);
+    else if (dist === 3) consider(20, `similar name (distance ${dist})`);
+  }
+
+  // ── Keyword signals ─────────────────────────────────────────────
+  for (const kw of keywords) {
+    const kwLower = String(kw).toLowerCase();
+    if (kwLower === term) {
+      consider(90, `keyword "${kw}"`);
+      continue;
+    }
+    const s = term.length < kwLower.length ? term : kwLower;
+    const l = term.length < kwLower.length ? kwLower : term;
+    if (s.length >= 4 && l.includes(s) && s.length / l.length >= 0.5) {
+      consider(70, `keyword "${kw}"`);
+    }
+    const dist = levenshteinDistance(term, kwLower);
+    if (dist === 1) consider(70, `keyword "${kw}" (distance ${dist})`);
+    else if (dist === 2) consider(30, `keyword "${kw}" (distance ${dist})`);
+  }
+
+  // ── Prose / description signals (whole-word boundary) ───────────
+  if (term.length >= 3) {
+    const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`\\b${escaped}\\b`);
+    if (description && re.test(description.toLowerCase())) {
+      consider(50, `description mentions "${term}"`);
+    } else {
+      for (const blob of prose) {
+        if (blob && re.test(String(blob).toLowerCase())) {
+          consider(50, `docs mention "${term}"`);
+          break;
+        }
+      }
+    }
+  }
+
+  return best > 0 ? {score: best, reason} : null;
+}
+
+/** Load a doc module's `docs`/`doc` export, swallowing errors. */
+async function loadModuleDoc(docPath, exportName = 'docs') {
+  try {
+    const mod = await import(pathToFileURL(docPath).href);
+    return mod[exportName] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build component candidates: name + keywords + usage/description from the
+ * component's .doc.mjs.
+ * @param {string} coreDir
+ */
+async function gatherComponents(coreDir) {
+  const grouped = discoverComponents(coreDir);
+  const names = Object.values(grouped).flat();
+  const candidates = [];
+  for (const comp of names) {
+    const readme = findComponentReadme(coreDir, comp);
+    let keywords = [];
+    let description = '';
+    if (readme && readme.endsWith('.doc.mjs')) {
+      const doc = await loadModuleDoc(readme);
+      if (doc) {
+        keywords = Array.isArray(doc.keywords) ? doc.keywords : [];
+        description = doc.usage?.description || doc.description || '';
+      }
+    }
+    candidates.push({
+      domain: 'component',
+      name: comp,
+      keywords,
+      description,
+      _import: resolveImportPath(coreDir, comp),
+    });
+  }
+  return candidates;
+}
+
+/**
+ * Build hook candidates: name + keywords + usage/description from the hook's
+ * .doc.mjs.
+ * @param {string} coreDir
+ */
+async function gatherHooks(coreDir) {
+  const grouped = discoverHooks(coreDir);
+  const names = Object.values(grouped).flat();
+  const candidates = [];
+  for (const hookName of names) {
+    const docPath = findHookDoc(coreDir, hookName);
+    let keywords = [];
+    let description = '';
+    let importPath = '@astryxdesign/core/hooks';
+    if (docPath) {
+      const doc = await loadModuleDoc(docPath);
+      if (doc) {
+        keywords = Array.isArray(doc.keywords) ? doc.keywords : [];
+        description = doc.usage?.description || doc.description || '';
+        importPath = doc.importPath || importPath;
+      }
+    }
+    candidates.push({
+      domain: 'hook',
+      name: hookName,
+      keywords,
+      description,
+      _import: importPath,
+    });
+  }
+  return candidates;
+}
+
+/** Build doc-topic candidates: topic name + description + section prose. */
+async function gatherDocs() {
+  if (!fs.existsSync(DOCS_DIR)) return [];
+  const candidates = [];
+  for (const file of fs.readdirSync(DOCS_DIR)) {
+    const match = file.match(/^([\w-]+)\.doc\.mjs$/);
+    if (!match) continue;
+    const topic = match[1];
+    const doc = await loadModuleDoc(path.join(DOCS_DIR, file));
+    let description = '';
+    const prose = [];
+    if (doc) {
+      description = doc.description || '';
+      for (const section of doc.sections || []) {
+        if (section.title) prose.push(section.title);
+        for (const block of section.content || []) {
+          if (block.type === 'prose' && block.text) prose.push(block.text);
+        }
+      }
+    }
+    candidates.push({
+      domain: 'doc',
+      name: topic,
+      keywords: [],
+      description,
+      prose,
+      _title: doc?.title || topic,
+    });
+  }
+  return candidates;
+}
+
+/** Build template candidates (page + block) from the template discovery API. */
+async function gatherTemplates(cwd) {
+  let templates;
+  try {
+    templates = await discoverTemplates(cwd);
+  } catch {
+    return [];
+  }
+  return templates.map(t => ({
+    domain: 'template',
+    name: t.dirName,
+    keywords: Array.isArray(t.componentsUsed) ? t.componentsUsed : [],
+    description: t.description || '',
+    _displayName: t.name,
+    _kind: t.type, // 'page' | 'block'
+  }));
+}
+
+/**
+ * Map a scored candidate to its public, actionable result shape. Each result
+ * carries enough to act on it: the domain, name, a one-line description, and
+ * the follow-up command (and import path where relevant).
+ *
+ * @param {object} c - candidate
+ * @param {number} score
+ * @param {string} reason
+ */
+function toResult(c, score, reason) {
+  const base = {
+    domain: c.domain,
+    name: c.name,
+    score,
+    reason,
+    description: c.description || '',
+  };
+  switch (c.domain) {
+    case 'component':
+      return {
+        ...base,
+        import: c._import,
+        command: `astryx component ${c.name}`,
+      };
+    case 'hook':
+      return {
+        ...base,
+        import: c._import,
+        command: `astryx hook ${c.name}`,
+      };
+    case 'doc':
+      return {
+        ...base,
+        title: c._title,
+        command: `astryx docs ${c.name}`,
+      };
+    case 'template':
+      return {
+        ...base,
+        displayName: c._displayName,
+        kind: c._kind,
+        command: `astryx template ${c.name}`,
+      };
+    default:
+      return base;
+  }
+}
+
+/**
+ * Unified ranked search across components, hooks, docs, and templates.
+ *
+ * @param {string} query - Free-text search term.
+ * @param {object} [options]
+ * @param {string} [options.cwd]
+ * @param {'component'|'hook'|'doc'|'template'} [options.type] - Restrict to one domain.
+ * @param {number} [options.limit] - Max results (default 20).
+ * @returns {Promise<{type: 'search', data: {query: string, results: Array<object>}}>}
+ */
+export async function search(query, options = {}) {
+  const {cwd = process.cwd(), type, limit = 20} = options;
+
+  if (!query || !String(query).trim()) {
+    throw new AstryxError('A search query is required', [
+      {name: 'astryx search button', reason: 'example'},
+    ]);
+  }
+
+  if (type && !SEARCH_DOMAINS.includes(type)) {
+    throw new AstryxError(
+      `Unknown --type "${type}"`,
+      SEARCH_DOMAINS.map(d => ({name: d, reason: 'valid type'})),
+    );
+  }
+
+  const term = String(query).trim().toLowerCase();
+
+  const coreDir = findCoreDir(cwd);
+  if (!coreDir) {
+    throw new AstryxError('Could not find @astryxdesign/core package');
+  }
+
+  // Gather candidates from each requested domain in parallel.
+  const wants = d => !type || type === d;
+  const [components, hooks, docTopics, templates] = await Promise.all([
+    wants('component') ? gatherComponents(coreDir) : [],
+    wants('hook') ? gatherHooks(coreDir) : [],
+    wants('doc') ? gatherDocs() : [],
+    wants('template') ? gatherTemplates(cwd) : [],
+  ]);
+
+  const all = [...components, ...hooks, ...docTopics, ...templates];
+
+  const scored = [];
+  for (const candidate of all) {
+    const hit = scoreCandidate(term, candidate);
+    if (hit) scored.push(toResult(candidate, hit.score, hit.reason));
+  }
+
+  // Sort by score desc, then domain (stable order), then name.
+  const domainOrder = {component: 0, hook: 1, doc: 2, template: 3};
+  scored.sort(
+    (a, b) =>
+      b.score - a.score ||
+      (domainOrder[a.domain] ?? 9) - (domainOrder[b.domain] ?? 9) ||
+      a.name.localeCompare(b.name),
+  );
+
+  const limited = limit > 0 ? scored.slice(0, limit) : scored;
+
+  return {type: 'search', data: {query: String(query).trim(), results: limited}};
+}