@astryxdesign/cli 0.1.1 → 0.1.2-canary.043f3fd

package/src/api/discover.mjs

@@ -4,20 +4,29 @@
  * @file Programmatic API for the discover command.
  */
 
-import {loadConfig} from '../lib/config.mjs';
-import {scanAllPackages, findComponentInPackages} from '../lib/package-scanner.mjs';
+import {Project} from '../lib/project.mjs';
+import {
+  scanAllPackages,
+  findComponentInPackages,
+} from '../lib/package-scanner.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';
 
 function validateDocs(docs) {
-  if (!docs || typeof docs !== 'object') return 'docs export is missing or not an object';
-  if (typeof docs.name !== 'string' || !docs.name) return 'docs.name is missing or not a string';
-  if (!docs.usage || typeof docs.usage.description !== 'string') return 'docs.usage.description is missing or not a string';
-  if (docs.props && !Array.isArray(docs.props)) return 'docs.props must be an array';
-  if (docs.components && !Array.isArray(docs.components)) return 'docs.components must be an array';
-  if (docs.usage?.bestPractices && !Array.isArray(docs.usage.bestPractices)) return 'docs.usage.bestPractices must be an array';
+  if (!docs || typeof docs !== 'object')
+    return 'docs export is missing or not an object';
+  if (typeof docs.name !== 'string' || !docs.name)
+    return 'docs.name is missing or not a string';
+  if (!docs.usage || typeof docs.usage.description !== 'string')
+    return 'docs.usage.description is missing or not a string';
+  if (docs.props && !Array.isArray(docs.props))
+    return 'docs.props must be an array';
+  if (docs.components && !Array.isArray(docs.components))
+    return 'docs.components must be an array';
+  if (docs.usage?.bestPractices && !Array.isArray(docs.usage.bestPractices))
+    return 'docs.usage.bestPractices must be an array';
   return null;
 }
 
@@ -31,8 +40,8 @@ function validateDocs(docs) {
  */
 export async function discover(query, options = {}) {
   const {lang = null, zh = false} = options;
-  const config = await loadConfig();
-  const toEntry = (pkg) => ({
+  const project = await Project.load();
+  const toEntry = pkg => ({
     name: pkg.name,
     category: pkg.category,
     components: pkg.components,
@@ -41,11 +50,21 @@ export async function discover(query, options = {}) {
     displayName: pkg.displayName,
   });
 
-  if (config.packages.length === 0) {
+  // External packages come from configured integrations that declare a
+  // components root. Each becomes a scannable package keyed by its docsDir.
+  const explicitPackages = project.loadedIntegrations
+    .filter(integration => integration.components)
+    .map(integration => ({
+      name: integration.name,
+      version: integration.version,
+      category: integration.name,
+      docsDir: integration.components,
+    }));
+  if (explicitPackages.length === 0) {
     return {type: 'discover.list', data: [], meta: {configured: false}};
   }
 
-  const packages = scanAllPackages(config.packages);
+  const packages = scanAllPackages([], explicitPackages);
 
   if (packages.length === 0) {
     return {type: 'discover.list', data: [], meta: {configured: true}};
@@ -61,7 +80,10 @@ export async function discover(query, options = {}) {
     if (slashIdx > 0) {
       const pkgName = query.slice(0, slashIdx);
       const compName = query.slice(slashIdx + 1);
-      return await resolveComponentDocs(packages, compName, pkgName, {lang, zh});
+      return await resolveComponentDocs(packages, compName, pkgName, {
+        lang,
+        zh,
+      });
     }
 
     const pkg = packages.find(p => p.name === query);
@@ -99,7 +121,16 @@ export async function discover(query, options = {}) {
   }
 
   if (substringMatches.length > 1) {
-    return {type: 'discover.search', data: {query, matches: substringMatches.map(m => ({package: m.pkg.name, component: m.comp}))}};
+    return {
+      type: 'discover.search',
+      data: {
+        query,
+        matches: substringMatches.map(m => ({
+          package: m.pkg.name,
+          component: m.comp,
+        })),
+      },
+    };
   }
 
   // Fuzzy fallback
@@ -110,7 +141,10 @@ export async function discover(query, options = {}) {
     }
   }
   const fuzzyMatches = allComponents
-    .map(item => ({...item, distance: levenshteinDistance(lower, item.comp.toLowerCase())}))
+    .map(item => ({
+      ...item,
+      distance: levenshteinDistance(lower, item.comp.toLowerCase()),
+    }))
     .filter(m => m.distance <= 3)
     .sort((a, b) => a.distance - b.distance)
     .slice(0, 5);
@@ -118,30 +152,46 @@ export async function discover(query, options = {}) {
   if (fuzzyMatches.length > 0) {
     throw new AstryxError(
       `"${query}" not found`,
-      fuzzyMatches.map(m => ({name: m.pkg.name + '/' + m.comp, reason: 'similar name'})),
+      fuzzyMatches.map(m => ({
+        name: m.pkg.name + '/' + m.comp,
+        reason: 'similar name',
+      })),
       ERROR_CODES.ERR_NOT_FOUND,
     );
   }
 
-  throw new AstryxError(`"${query}" not found in any package`, undefined, ERROR_CODES.ERR_NOT_FOUND);
+  throw new AstryxError(
+    `"${query}" not found in any package`,
+    undefined,
+    ERROR_CODES.ERR_NOT_FOUND,
+  );
 }
 
 async function resolveComponentDocs(packages, compName, pkgName, {lang, zh}) {
   const pkg = packages.find(p => p.name === pkgName);
-  if (!pkg) throw new AstryxError(`Package "${pkgName}" not found`, undefined, ERROR_CODES.ERR_UNKNOWN_PACKAGE);
+  if (!pkg)
+    throw new AstryxError(
+      `Package "${pkgName}" not found`,
+      undefined,
+      ERROR_CODES.ERR_UNKNOWN_PACKAGE,
+    );
 
   const result = findComponentInPackages([pkg], compName);
   if (!result) {
     const lower = compName.toLowerCase();
     const hits = pkg.components.filter(c => c.toLowerCase().includes(lower));
-    const suggestions = hits.length > 0
-      ? hits
-      : pkg.components
-        .map(c => ({name: c, distance: levenshteinDistance(lower, c.toLowerCase())}))
-        .filter(m => m.distance <= 3)
-        .sort((a, b) => a.distance - b.distance)
-        .slice(0, 5)
-        .map(m => m.name);
+    const suggestions =
+      hits.length > 0
+        ? hits
+        : pkg.components
+            .map(c => ({
+              name: c,
+              distance: levenshteinDistance(lower, c.toLowerCase()),
+            }))
+            .filter(m => m.distance <= 3)
+            .sort((a, b) => a.distance - b.distance)
+            .slice(0, 5)
+            .map(m => m.name);
     throw new AstryxError(
       `Component "${compName}" not found in ${pkgName}`,
       suggestions.map(s => ({name: s, reason: 'similar name'})),
@@ -157,9 +207,18 @@ async function loadAndValidate(result, {lang, zh}) {
   try {
     docs = await loadDocs(result.docPath, {zh, lang});
   } catch (e) {
-    throw new AstryxError(`Failed to load docs for ${result.componentName}: ${e.message}`, undefined, ERROR_CODES.ERR_INVALID_DOC);
+    throw new AstryxError(
+      `Failed to load docs for ${result.componentName}: ${e.message}`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_DOC,
+    );
   }
   const err = validateDocs(docs);
-  if (err) throw new AstryxError(`Invalid docs for ${result.componentName}: ${err}`, undefined, ERROR_CODES.ERR_INVALID_DOC);
+  if (err)
+    throw new AstryxError(
+      `Invalid docs for ${result.componentName}: ${err}`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_DOC,
+    );
   return {type: 'discover.detail.doc', data: docs};
 }

package/src/api/doctor.mjs

@@ -27,7 +27,7 @@ import {createRequire} from 'node:module';
 import {MIN_NODE_VERSION, isNodeVersionSupported} from '../lib/node-version.mjs';
 import {CLI_ROOT, findCoreDir} from '../utils/paths.mjs';
 import {detectPackageManager} from '../utils/package-manager.mjs';
-import {findConfigPath, loadConfig} from '../lib/config.mjs';
+import {findConfigPath, Project} from '../lib/project.mjs';
 import {semverCompare} from '../utils/semver.mjs';
 
 const _require = createRequire(import.meta.url);
@@ -279,8 +279,9 @@ export async function checkConfig(ctx) {
     };
   }
 
-  // loadConfig swallows errors and returns defaults, so re-import directly to
-  // surface a genuine load failure as a FAIL.
+  // Project.load swallows nothing — it surfaces a genuine load failure — but
+  // the config check wants to report a bad default export precisely, so we
+  // re-import directly to surface a genuine load failure as a FAIL.
   try {
     const {pathToFileURL} = await import('node:url');
     const mod = await import(pathToFileURL(ctx.configPath).href);
@@ -291,25 +292,9 @@ export async function checkConfig(ctx) {
         label: 'astryx.config.mjs',
         status: 'fail',
         message: `astryx.config.mjs default export is not an object (got ${typeof config}).`,
-        fix: 'Export a default object from astryx.config.mjs, e.g. `export default { theme: "default" };`.',
+        fix: 'Export a default object from astryx.config.mjs, e.g. `export default { integrations: [] };`.',
       };
     }
-    // Validate that `packages`, if present, is a string or array of strings.
-    if (config?.packages !== undefined) {
-      const arr = Array.isArray(config.packages)
-        ? config.packages
-        : [config.packages];
-      const bad = arr.some(p => typeof p !== 'string');
-      if (bad) {
-        return {
-          id: 'config',
-          label: 'astryx.config.mjs',
-          status: 'fail',
-          message: 'astryx.config.mjs `packages` must be a string or array of strings.',
-          fix: 'Set `packages` to a path string or array of path strings.',
-        };
-      }
-    }
     return {
       id: 'config',
       label: 'astryx.config.mjs',
@@ -493,8 +478,8 @@ export async function runChecks(options = {}) {
   // Resolve a possible theme key from config (best-effort; never throws).
   let configTheme = null;
   try {
-    const loaded = await loadConfig(cwd);
-    configTheme = loaded?.theme ?? null;
+    const project = await Project.load(cwd);
+    configTheme = project.config?.theme ?? null;
   } catch {
     // Best-effort: a missing/invalid config leaves configTheme null.
   }

package/src/api/index.mjs

@@ -23,6 +23,7 @@ export {component} from './component.mjs';
 export {docs} from './docs.mjs';
 export {discover} from './discover.mjs';
 export {template} from './template.mjs';
+export {themeAdd, listThemes} from './theme-add.mjs';
 export {hook} from './hook.mjs';
 export {search} from './search.mjs';
 export {doctor} from './doctor.mjs';

package/src/api/layout.mjs

@@ -0,0 +1,302 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Programmatic API for the layout command (XLE/XLO).
+ *
+ * `astryx layout` turns token-compressed layout expressions into validated
+ * XDS TSX. Two input surfaces — compact (Emmet-derived XLE) and outline
+ * (indentation-based XLO) — share one AST, one validator, and one
+ * expander. See the research: pastes P2376666892 (spec) and P2376717669
+ * (outline surface).
+ *
+ * @input  expression string (+ options)
+ * @output {type, data} envelopes: layout.expand / layout.check / layout.grammar
+ * @position api — pure orchestration over lib/xle; command wrapper in commands/layout.mjs
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {AstryxError} from './error.mjs';
+import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {assertWithin, isFilePathArg, PathSafetyError} from '../utils/path-safety.mjs';
+import {parse, detectForm, XLEParseError} from '../lib/xle/parse.mjs';
+import {validate} from '../lib/xle/validate.mjs';
+import {expand} from '../lib/xle/expand.mjs';
+import {toCompact, toOutline} from '../lib/xle/print.mjs';
+import {buildRegistry, ALIAS_TABLE} from '../lib/xle/registry.mjs';
+import {discoverTemplates, stripTemplateAssetRefs} from './template.mjs';
+import {Project} from '../lib/project.mjs';
+
+/**
+ * The catalog a `{hint}` can resolve to: template blocks (spliced inline) plus
+ * any app-registered local components from astryx.config.mjs
+ * `experimental.xle.components` (imported by name). App components are how XLE
+ * reaches domain pieces — the KpiCard/chart/drawer set that the
+ * @astryxdesign/core registry can't see.
+ */
+async function loadBlocks(cwd) {
+  const blocks = [];
+  try {
+    const all = await discoverTemplates(cwd);
+    for (const t of all) if (t.type === 'block') blocks.push({...t, kind: 'template'});
+  } catch {
+    // discovery is best-effort
+  }
+  try {
+    const project = await Project.load(cwd);
+    const components = project.config.experimental?.xle?.components ?? {};
+    for (const [name, spec] of Object.entries(components)) {
+      const importPath = spec.from;
+      if (!importPath) continue;
+      blocks.push({
+        type: 'block',
+        kind: 'component',
+        dirName: name,
+        name,
+        description: spec.description ?? '',
+        category: 'app',
+        importPath,
+        isDefault: Boolean(spec.default),
+      });
+    }
+  } catch {
+    // config is optional
+  }
+  return blocks;
+}
+
+const normKey = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+/** Collect the block names referenced by {hints} anywhere in the doc. */
+function collectHintNames(doc) {
+  const names = new Set();
+  const visitNode = (node) => {
+    if (!node || node.kind === 'group') {
+      (node?.children || []).forEach(visit);
+      return;
+    }
+    if (node.hint?.block) names.add(node.hint.block.name);
+    for (const slot of node.slots || []) {
+      if (slot.value?.hint?.block) names.add(slot.value.hint.block.name);
+      (slot.value?.subexpr || []).forEach(visit);
+    }
+    (node.children || []).forEach(visit);
+  };
+  const visit = (item) => (item?.kind === 'group' ? item.children.forEach(visit) : visitNode(item));
+  doc.roots.forEach(visit);
+  doc.overlays.forEach(visit);
+  return names;
+}
+
+/**
+ * Build the blockModules map expand() needs: import-mode for app components,
+ * splice-mode (reading + asset-stripping the block source) for template blocks.
+ * Only blocks actually referenced are read.
+ */
+function buildBlockModules(doc, blocks) {
+  const referenced = collectHintNames(doc);
+  if (referenced.size === 0) return new Map();
+  const byKey = new Map(blocks.map(b => [normKey(b.dirName), b]));
+  const modules = new Map();
+  for (const name of referenced) {
+    const block = byKey.get(normKey(name));
+    if (!block) continue;
+    if (block.kind === 'component') {
+      modules.set(name, {mode: 'import', componentName: block.name, importPath: block.importPath, isDefault: block.isDefault});
+    } else if (block.filePath && fs.existsSync(block.filePath)) {
+      modules.set(name, {mode: 'splice', componentName: block.dirName, source: stripTemplateAssetRefs(fs.readFileSync(block.filePath, 'utf-8'))});
+    }
+  }
+  return modules;
+}
+
+function formatIssue(issue) {
+  const where = issue.line != null ? `line ${issue.line}: ` : '';
+  return `${where}${issue.message}`;
+}
+
+/**
+ * Parse + validate, throwing structured XDSErrors on failure.
+ * Returns {doc, registry, blocks, warnings}.
+ */
+async function analyze(expression, {form = 'auto', loose = false, cwd = process.cwd()} = {}) {
+  const registry = await buildRegistry({cwd});
+  const blocks = await loadBlocks(cwd);
+
+  let doc;
+  try {
+    doc = parse(expression, {form});
+  } catch (e) {
+    if (e instanceof XLEParseError) {
+      throw new AstryxError(
+        `Layout expression syntax error at line ${e.line}, col ${e.col}: ${e.message}`,
+        undefined,
+        ERROR_CODES.ERR_LAYOUT_PARSE,
+      );
+    }
+    throw e;
+  }
+
+  const {errors, warnings} = validate(doc, registry, blocks, {loose});
+  return {doc, registry, blocks, errors, warnings};
+}
+
+/**
+ * `astryx layout expand "<expr>" [path]`
+ *
+ * @param {string} expression
+ * @param {object} [options]
+ * @param {string} [options.targetPath] - write TSX here (validated against cwd)
+ * @param {'compact'|'outline'|'auto'} [options.form]
+ * @param {boolean} [options.loose] - downgrade unknown {hints} to TODO warnings
+ * @param {string} [options.name] - generated component name
+ * @param {string} [options.cwd]
+ */
+export async function layoutExpand(expression, options = {}) {
+  const {targetPath, form = 'auto', loose = false, name, cwd = process.cwd()} = options;
+  const {doc, registry, blocks, errors, warnings} = await analyze(expression, {form, loose, cwd});
+
+  if (errors.length > 0) {
+    throw new AstryxError(
+      `Layout expression is invalid:\n` + errors.map(e => `  - ${formatIssue(e)}`).join('\n'),
+      errors.flatMap(e => (e.suggestions || []).map(s => ({name: s, reason: 'did you mean this?'}))),
+      ERROR_CODES.ERR_LAYOUT_INVALID,
+    );
+  }
+
+  const componentName = name || 'GeneratedLayout';
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(componentName)) {
+    throw new AstryxError(
+      `--name must be a PascalCase component name, got '${componentName}'`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+  const blockModules = buildBlockModules(doc, blocks);
+  const result = expand(doc, registry, {componentName, blockModules});
+
+  let written = null;
+  if (targetPath) {
+    let resolved;
+    try {
+      resolved = assertWithin(targetPath, cwd, {label: 'layout target path'});
+    } catch (err) {
+      if (err instanceof PathSafetyError) {
+        throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
+      }
+      throw err;
+    }
+    const filePath = isFilePathArg(targetPath)
+      ? resolved
+      : path.join(resolved, `${componentName}.tsx`);
+    fs.mkdirSync(path.dirname(filePath), {recursive: true});
+    fs.writeFileSync(filePath, result.code);
+    written = path.relative(cwd, filePath);
+  }
+
+  return {
+    type: 'layout.expand',
+    data: {
+      form: form === 'auto' ? detectForm(expression) : form,
+      code: result.code,
+      componentsUsed: result.componentsUsed,
+      states: result.states,
+      todos: result.todos,
+      blocksReferenced: [...blockModules.entries()].map(([name, m]) => ({name, mode: m.mode})),
+      warnings: warnings.map(formatIssue),
+      written,
+    },
+  };
+}
+
+/**
+ * `astryx layout check "<expr>" [--form compact|outline]`
+ * Validates without expanding; echoes both canonical surfaces.
+ */
+export async function layoutCheck(expression, options = {}) {
+  const {form = 'auto', loose = false, cwd = process.cwd()} = options;
+  const {doc, errors, warnings} = await analyze(expression, {form, loose, cwd});
+
+  return {
+    type: 'layout.check',
+    data: {
+      valid: errors.length === 0,
+      form: doc.form,
+      errors: errors.map(e => ({...e, formatted: formatIssue(e)})),
+      warnings: warnings.map(formatIssue),
+      compact: toCompact(doc),
+      outline: toOutline(doc),
+    },
+  };
+}
+
+/**
+ * `astryx layout grammar` — the agent cheatsheet, with the alias table
+ * generated from this branch's registry (never hand-maintained).
+ */
+export async function layoutGrammar(options = {}) {
+  const {cwd = process.cwd()} = options;
+  const registry = await buildRegistry({cwd});
+
+  const aliasLines = [];
+  const byTarget = new Map();
+  for (const [alias, target] of registry.aliases) {
+    if (!byTarget.has(target)) byTarget.set(target, []);
+    byTarget.get(target).push(alias);
+  }
+  for (const [target, aliases] of [...byTarget.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    aliasLines.push(`${aliases.join('/')}=${target}`);
+  }
+
+  const text = `XLE/XLO — XDS layout expressions (branch-generated; aliases reflect this install)
+
+WORKFLOW
+  astryx layout check "<expr>"           validate; echoes canonical compact + outline forms
+  astryx layout expand "<expr>" [path]   emit validated TSX (path optional; --name <Pascal>)
+  Errors carry line/col + suggestions. Fix and resubmit; nothing is guessed.
+
+TWO SURFACES, ONE LANGUAGE (autodetected; --form to force)
+  compact: A[cp6 @topNav=TN] > L > LC > S[p6] > (C{card-callout}*4) + T
+  outline: indentation = nesting · same-indent = siblings · "repeat N:" block = (...)*N
+           slot lines:  topNav: TN     (or a block:  topNav:\\n    TN ...)
+
+NODE ANATOMY   Name#id.enum"payload"[attrs]{hint}*N > children
+  .enum        unique enum value of any prop:  Bd.success  Tx.lg  B.primary
+  "payload"    primary text prop (label/title/heading) or text child:  TI"Email"  B"Save"
+  {hint}       kebab-case template/component reference (see TEMPLATE REFERENCING) — NEVER text
+  *N / xN      repeat (use $ for the counter:  Tk"item-$"*3)
+  trailing !   initial selection for scaffolded state:  Tab"Overview"!
+
+ATTRS [...] (outline: bare tokens after the name, no brackets)
+  fused        p6 g4 c4 w240 h2 cp2 mw960 rg2 cg2  (per-component: padding lives on Card/Section/AppShell.cp — p6 on AppShell/Layout/VStack errors with a correction)
+  key=value    t=email href='/x' c{min:340} dv=[top,bottom] — keys validated per component
+  flags        req opt dis striped hover divider … (isX/hasX props) · negate: !scroll
+  align        j= main axis, a= cross axis — expander picks hAlign/vAlign per stack direction
+  slots        @slotName=Node | @slotName=(sub > expr) | @slotName='text' | @slotName=#id
+  trigger      opens=#id  (a plain attr, no @ — binds an onClick that opens the overlay)
+  fill         on a stack child → wraps in <StackItem size="fill">
+
+TEMPLATE REFERENCING  ({hint} pulls in real content — this is how XLE reaches past the @astryxdesign/core shell)
+  C{card-callout}              splice a template block (astryx template --list --type block):
+                              the block is co-defined once in the file, referenced, imports merged
+  {kpi-card}                   standalone reference (no wrapper element) — place a component directly
+  {kpi-card}*4                 repeat a reference; the definition/import is emitted once
+  app components               register local ones in astryx.config.mjs to import them by name:
+                                 export default {experimental: {xle: {components: {KpiCard: {from: '@/components/KpiCard'}}}}}
+                               then {kpi-card} → import {KpiCard} + <KpiCard /> (kebab ↔ Pascal)
+
+STRUCTURE THE EXPANDER HANDLES
+  Layout > LH + LC + LF + LP   children auto-route into header/content/footer/start slots
+  T > (TR>THC*4) + (TR>TC*4)*6 rows partition into TableHeader/TableBody automatically
+  TabList/inputs               required value+onChange scaffold typed useState automatically
+  overlays                     compact: tree ;; Dlg#confirm[...] · outline: overlays: section
+                               trigger: B"Delete"[opens=#confirm]
+
+ALIASES (full component names always valid; XDS prefix optional)
+  ${aliasLines.join('  ')}
+`;
+
+  return {type: 'layout.grammar', data: {text, aliases: Object.fromEntries(registry.aliases)}};
+}
+
+export {ALIAS_TABLE};