@astryxdesign/cli 0.1.2-canary.b712653 → 0.1.2-canary.bbf77ea

package/src/api/discover.mjs

@@ -4,7 +4,7 @@
  * @file Programmatic API for the discover command.
  */
 
-import {loadConfig} from '../lib/config.mjs';
+import {Project} from '../lib/project.mjs';
 import {
   scanAllPackages,
   findComponentInPackages,
@@ -40,7 +40,7 @@ function validateDocs(docs) {
  */
 export async function discover(query, options = {}) {
   const {lang = null, zh = false} = options;
-  const config = await loadConfig();
+  const project = await Project.load();
   const toEntry = pkg => ({
     name: pkg.name,
     category: pkg.category,
@@ -50,14 +50,21 @@ export async function discover(query, options = {}) {
     displayName: pkg.displayName,
   });
 
-  const explicitPackages = (config.loadedIntegrations ?? [])
-    .map(integration => integration.package)
-    .filter(Boolean);
-  if (config.packages.length === 0 && explicitPackages.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, explicitPackages);
+  const packages = scanAllPackages([], explicitPackages);
 
   if (packages.length === 0) {
     return {type: 'discover.list', data: [], meta: {configured: true}};

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);
@@ -240,7 +240,7 @@ export function checkThemes(ctx) {
       label: 'Theme packages',
       status: 'warn',
       message: 'No @astryxdesign/theme-* packages are installed.',
-      fix: 'Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set xds.theme.',
+      fix: 'Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set astryx.theme.',
     };
   }
 
@@ -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',
@@ -369,7 +354,7 @@ export function checkAgentDocs(ctx) {
       label: 'AI agent docs',
       status: 'warn',
       message: `Agent docs present (${present.join(', ')}) but no Astryx section markers found.`,
-      fix: 'Add the XDS section to your agent docs with `astryx init --features agents`.',
+      fix: 'Add the Astryx section to your agent docs with `astryx init --features agents`.',
     };
   }
 
@@ -377,7 +362,7 @@ export function checkAgentDocs(ctx) {
     id: 'agent-docs',
     label: 'AI agent docs',
     status: 'pass',
-    message: `XDS agent docs section present in ${withMarkers.join(', ')}.`,
+    message: `Astryx agent docs section present in ${withMarkers.join(', ')}.`,
   };
 }
 
@@ -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/layout.mjs

@@ -25,13 +25,14 @@ 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 {loadConfig} from '../lib/config.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 `layout.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.
+ * 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 = [];
@@ -42,20 +43,20 @@ async function loadBlocks(cwd) {
     // discovery is best-effort
   }
   try {
-    const config = await loadConfig(cwd);
-    const components = config.layout?.components || {};
+    const project = await Project.load(cwd);
+    const components = project.config.experimental?.xle?.components ?? {};
     for (const [name, spec] of Object.entries(components)) {
-      const importPath = typeof spec === 'string' ? spec : spec.from;
+      const importPath = spec.from;
       if (!importPath) continue;
       blocks.push({
         type: 'block',
         kind: 'component',
         dirName: name,
         name,
-        description: typeof spec === 'object' ? spec.description || '' : '',
+        description: spec.description ?? '',
         category: 'app',
         importPath,
-        isDefault: typeof spec === 'object' ? Boolean(spec.default) : false,
+        isDefault: Boolean(spec.default),
       });
     }
   } catch {
@@ -281,7 +282,7 @@ TEMPLATE REFERENCING  ({hint} pulls in real content — this is how XLE reaches
   {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 {layout: {components: {KpiCard: '@/components/KpiCard'}}}
+                                 export default {experimental: {xle: {components: {KpiCard: {from: '@/components/KpiCard'}}}}}
                                then {kpi-card} → import {KpiCard} + <KpiCard /> (kebab ↔ Pascal)
 
 STRUCTURE THE EXPANDER HANDLES

package/src/api/layout.test.mjs

@@ -196,11 +196,14 @@ describe('template referencing', () => {
 
   it('imports app-registered local components (the local-component bridge)', async () => {
     // Inside the workspace so @astryxdesign/core resolves; cleaned up after.
+    // A package.json beside the config makes Project.load resolve it as the
+    // sibling-of-nearest-package.json (the standard config resolution).
     const cwd = mkdtempSync(join(process.cwd(), '.xle-imp-test-'));
     try {
+      writeFileSync(join(cwd, 'package.json'), '{"name": "xle-imp-fixture"}\n');
       writeFileSync(
         join(cwd, 'astryx.config.mjs'),
-        `export default {layout: {components: {KpiCard: '@/components/KpiCard', TimeRangePicker: {from: '@/components/TimeRangePicker'}}}};\n`,
+        `export default {experimental: {xle: {components: {KpiCard: {from: '@/components/KpiCard'}, TimeRangePicker: {from: '@/components/TimeRangePicker'}}}}};\n`,
       );
       const result = await layoutExpand('S[p6] > (G[c4 g4] > {kpi-card}*4) + {time-range-picker}', {
         name: 'Demo',

package/src/api/template-integration.test.mjs

@@ -0,0 +1,225 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Integration-provided template discovery (same-stem + type-driven).
+ *
+ * These tests stand up a temp consumer project with an astryx.config and an
+ * installed integration package that contributes templates, then exercise the
+ * public `template()` API to verify discovery, package/type scoping, ambiguity
+ * errors, and copy-to-dir naming.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {template} from './template.mjs';
+
+let tmpDir;
+let originalCwd;
+
+/** Absolute path to the CLI package so integrations can import /template. */
+const CLI_PKG = path.resolve(import.meta.dirname, '..', '..');
+
+function makeConsumer() {
+  const dir = fs.mkdtempSync(
+    path.join(process.cwd(), '.astryx-template-it-'),
+  );
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name: 'consumer'}),
+  );
+  fs.writeFileSync(
+    path.join(dir, 'astryx.config.mjs'),
+    `export default { integrations: ['@acme/widgets'] };\n`,
+  );
+  return dir;
+}
+
+/**
+ * Install an @acme/widgets integration package that declares a templates root.
+ * @returns the package dir.
+ */
+function installWidgets(consumerDir) {
+  const pkgDir = path.join(consumerDir, 'node_modules', '@acme', 'widgets');
+  fs.mkdirSync(pkgDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({name: '@acme/widgets', version: '2.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default { templates: './templates' };\n`,
+  );
+  fs.mkdirSync(path.join(pkgDir, 'templates'));
+  return pkgDir;
+}
+
+/** Write a template doc + same-stem source under the templates root. */
+function writeTemplate(pkgDir, id, {kind, body, withSource = true}) {
+  const docPath = path.join(pkgDir, 'templates', `${id}.doc.mjs`);
+  fs.mkdirSync(path.dirname(docPath), {recursive: true});
+  const create = kind === 'page' ? 'createPageTemplate' : 'createBlockTemplate';
+  fs.writeFileSync(
+    docPath,
+    body ??
+      `import {${create}} from '${CLI_PKG}/src/template.mjs';\n` +
+        `export default ${create}({name: '${id} name', description: '${id} desc'});\n`,
+  );
+  if (withSource) {
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', `${id}.tsx`),
+      `export default function ${id.replace(/[^a-zA-Z0-9]/g, '')}() { return null; }\n`,
+    );
+  }
+}
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  tmpDir = makeConsumer();
+  process.chdir(tmpDir);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('integration template discovery', () => {
+  it('discovers and lists an integration template with package + type', async () => {
+    const pkgDir = installWidgets(tmpDir);
+    writeTemplate(pkgDir, 'pricing', {kind: 'page'});
+
+    const result = await template(undefined, {list: true, cwd: tmpDir});
+    expect(result.type).toBe('template.list');
+    const entry = result.data.find(t => t.id === 'pricing');
+    expect(entry).toBeTruthy();
+    expect(entry.type).toBe('page');
+    expect(entry.package).toBe('@acme/widgets');
+    expect(entry.name).toBe('pricing name');
+    expect(entry.description).toBe('pricing desc');
+  });
+
+  it('lists nested-id templates (kebab path under root)', async () => {
+    const pkgDir = installWidgets(tmpDir);
+    writeTemplate(pkgDir, 'marketing/hero', {kind: 'block'});
+
+    const result = await template(undefined, {list: true, cwd: tmpDir});
+    const entry = result.data.find(t => t.id === 'marketing/hero');
+    expect(entry).toBeTruthy();
+    expect(entry.type).toBe('block');
+    expect(entry.package).toBe('@acme/widgets');
+  });
+
+  it('always reports core templates under @astryxdesign/core', async () => {
+    const result = await template(undefined, {list: true, cwd: tmpDir});
+    const core = result.data.filter(t => t.package === '@astryxdesign/core');
+    expect(core.length).toBeGreaterThan(0);
+  });
+
+  it('--package narrows the listing', async () => {
+    const pkgDir = installWidgets(tmpDir);
+    writeTemplate(pkgDir, 'pricing', {kind: 'page'});
+
+    const result = await template(undefined, {
+      list: true,
+      package: '@acme/widgets',
+      cwd: tmpDir,
+    });
+    expect(result.data.length).toBe(1);
+    expect(result.data[0].id).toBe('pricing');
+  });
+
+  it('skips a template whose same-stem source is missing', async () => {
+    const pkgDir = installWidgets(tmpDir);
+    writeTemplate(pkgDir, 'orphan', {kind: 'page', withSource: false});
+
+    const result = await template(undefined, {list: true, cwd: tmpDir});
+    expect(result.data.find(t => t.id === 'orphan')).toBeUndefined();
+  });
+
+  it('skips a raw doc that is missing a type', async () => {
+    const pkgDir = installWidgets(tmpDir);
+    writeTemplate(pkgDir, 'untyped', {
+      kind: 'page',
+      body: `export default {name: 'Untyped', description: 'no type'};\n`,
+    });
+
+    const result = await template(undefined, {list: true, cwd: tmpDir});
+    expect(result.data.find(t => t.id === 'untyped')).toBeUndefined();
+  });
+
+  it('errors with candidates when an id is ambiguous across type/package', async () => {
+    const pkgDir = installWidgets(tmpDir);
+    // Same id "hero" as both a page and a block within the integration.
+    writeTemplate(pkgDir, 'hero', {kind: 'page'});
+    // Add a sibling block doc with the same stem in a different file is not
+    // possible (same file). Instead install a second package with a "hero".
+    const pkg2 = path.join(tmpDir, 'node_modules', '@acme', 'extra');
+    fs.mkdirSync(path.join(pkg2, 'templates'), {recursive: true});
+    fs.writeFileSync(
+      path.join(pkg2, 'package.json'),
+      JSON.stringify({name: '@acme/extra', version: '1.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(pkg2, 'astryx.integration.mjs'),
+      `export default { templates: './templates' };\n`,
+    );
+    fs.writeFileSync(
+      path.join(pkg2, 'templates', 'hero.doc.mjs'),
+      `import {createBlockTemplate} from '${CLI_PKG}/src/template.mjs';\n` +
+        `export default createBlockTemplate({name: 'Hero block', description: 'b'});\n`,
+    );
+    fs.writeFileSync(
+      path.join(pkg2, 'templates', 'hero.tsx'),
+      `export default function Hero() { return null; }\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.config.mjs'),
+      `export default { integrations: ['@acme/widgets', '@acme/extra'] };\n`,
+    );
+
+    await expect(
+      template('hero', {targetPath: './out', cwd: tmpDir}),
+    ).rejects.toMatchObject({code: 'ERR_AMBIGUOUS_TEMPLATE'});
+  });
+
+  it('--type and --package narrow an ambiguous id to a single match', async () => {
+    const pkgDir = installWidgets(tmpDir);
+    writeTemplate(pkgDir, 'pricing', {kind: 'page'});
+
+    const result = await template('pricing', {
+      type: 'page',
+      package: '@acme/widgets',
+      show: true,
+      cwd: tmpDir,
+    });
+    expect(result.type).toBe('template.show');
+    expect(result.data.type).toBe('page');
+  });
+
+  it('copies a page template into a directory as page.tsx', async () => {
+    const pkgDir = installWidgets(tmpDir);
+    writeTemplate(pkgDir, 'pricing', {kind: 'page'});
+
+    const result = await template('pricing', {
+      targetPath: './dest',
+      cwd: tmpDir,
+    });
+    expect(result.type).toBe('template.copy');
+    expect(result.data.fileName).toBe('page.tsx');
+    expect(fs.existsSync(path.join(tmpDir, 'dest', 'page.tsx'))).toBe(true);
+  });
+
+  it('copies a block template into a directory as <id-basename>.tsx', async () => {
+    const pkgDir = installWidgets(tmpDir);
+    writeTemplate(pkgDir, 'marketing/hero', {kind: 'block'});
+
+    const result = await template('marketing/hero', {
+      targetPath: './dest',
+      cwd: tmpDir,
+    });
+    expect(result.type).toBe('template.copy');
+    expect(result.data.fileName).toBe('hero.tsx');
+    expect(fs.existsSync(path.join(tmpDir, 'dest', 'hero.tsx'))).toBe(true);
+  });
+});