@astryxdesign/cli 0.1.2 → 0.1.3

package/src/api/component.mjs

@@ -11,18 +11,48 @@ import * as fs from 'node:fs';
 import {ERROR_CODES} from '../lib/error-codes.mjs';
 import {findCoreDir, discoverExternalPackages} from '../utils/paths.mjs';
 import {
+  CORE_PACKAGE,
   discoverComponents,
   discoverExternalComponentsGrouped,
+  discoverIntegrationComponents,
   findComponentReadme,
   findComponentSource,
   findExternalComponentDoc,
+  findIntegrationComponentDoc,
+  findIntegrationComponentSource,
   resolveImportPath,
 } from '../lib/component-discovery.mjs';
+import {Project} from '../lib/project.mjs';
 import {loadDocs} from '../lib/component-loader.mjs';
 import {searchComponents} from '../lib/string-utils.mjs';
 import {AstryxError} from './error.mjs';
 import {findShowcase, findRelatedBlocks} from './template.mjs';
 
+/**
+ * Load the configured integrations for `cwd`, swallowing any config errors so
+ * component discovery never hard-fails on a malformed/absent integration. An
+ * empty list means "core only".
+ * @param {string} cwd
+ * @returns {Promise<Array<{name: string, components?: string, issuesUrl?: string}>>}
+ */
+async function loadIntegrationsSafely(cwd) {
+  try {
+    const project = await Project.load(cwd);
+    return project.loadedIntegrations;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve a loaded integration by package name.
+ * @param {Array<{name: string}>} loadedIntegrations
+ * @param {string} packageName
+ */
+function findLoadedIntegration(loadedIntegrations, packageName) {
+  return loadedIntegrations.find(i => i.name === packageName) ?? null;
+}
+
 /**
  * Resolve an external package by name from the discovered externals list.
  * @param {string} packageName - e.g. '@acme/xds-widgets'
@@ -131,8 +161,13 @@ export async function component(name, options = {}) {
         return {type: 'component.full', data: {[match[0]]: entries}};
       }
 
-      // Default: brief — names only
-      return {type: 'component.list', data: {[match[0]]: match[1]}};
+      // Default: brief — package-qualified object list for the category.
+      // Pre-1.0 JSON contract: members are {name, package} objects, not bare
+      // strings, so consumers can disambiguate ownership.
+      return {
+        type: 'component.list',
+        data: {[match[0]]: match[1].map(n => ({name: n, package: CORE_PACKAGE}))},
+      };
     }
 
     // All components — merge core + external packages with grouped subcategories
@@ -179,43 +214,189 @@ export async function component(name, options = {}) {
       return {type: 'component.full', data: result};
     }
 
-    // Default: brief — names only (with externals merged in)
+    // Default: brief — package-qualified object list (core + integrations).
+    // Pre-1.0 JSON contract: each group's members are {name, package} objects.
+    /** @type {Record<string, Array<{name: string, package: string}>>} */
+    const listData = {};
+    for (const [cat, comps] of Object.entries(components)) {
+      listData[cat] = comps.map(n => ({name: n, package: CORE_PACKAGE}));
+    }
+
+    // Integration components (authoritative source: loadedIntegrations).
+    const loadedIntegrations = await loadIntegrationsSafely(cwd);
+    const seenIntegration = new Set();
+    for (const integration of loadedIntegrations) {
+      seenIntegration.add(integration.name);
+      const owned = discoverIntegrationComponents(integration);
+      // Group integration components by their doc `group`, falling back to the
+      // package name. Keys are package-qualified so they never collide with
+      // core groups or each other.
+      /** @type {Map<string, Array<{name: string, package: string}>>} */
+      const byGroup = new Map();
+      for (const rec of owned) {
+        const groupLabel = rec.group ?? integration.name;
+        const key = `${groupLabel} (${integration.name})`;
+        if (!byGroup.has(key)) byGroup.set(key, []);
+        byGroup.get(key).push({name: rec.name, package: integration.name});
+      }
+      for (const [key, members] of byGroup) {
+        members.sort((a, b) => a.name.localeCompare(b.name));
+        listData[key] = members;
+      }
+    }
+
+    // Back-compat: node_modules-scanned external packages (pkg.astryx.docs)
+    // that are NOT configured integrations. Preserves existing discovery for
+    // consumers that haven't adopted the config-integration flow.
     const externals = discoverExternalPackages(cwd);
     for (const ext of externals) {
+      if (seenIntegration.has(ext.name)) continue;
       const grouped = discoverExternalComponentsGrouped(ext.docsDir);
       const groupKeys = Object.keys(grouped);
       if (groupKeys.length === 0) continue;
 
-      // If the package has subcategories (groups), emit each as a separate key.
-      // If no groups exist, fall back to the flat list under one key.
       const hasGroups = groupKeys.some(
         k => grouped[k].length > 1 || grouped[k][0] !== k,
       );
 
       if (hasGroups) {
         for (const [group, members] of Object.entries(grouped)) {
-          components[`${group} (${ext.name})`] = members;
+          listData[`${group} (${ext.name})`] = members.map(n => ({
+            name: n,
+            package: ext.name,
+          }));
         }
       } else {
-        // All ungrouped — single flat list under the package category
         const allComps = Object.values(grouped).flat().sort();
         if (allComps.length > 0) {
-          components[`${ext.category} (${ext.name})`] = allComps;
+          listData[`${ext.category} (${ext.name})`] = allComps.map(n => ({
+            name: n,
+            package: ext.name,
+          }));
         }
       }
     }
-    return {type: 'component.list', data: components};
+    return {type: 'component.list', data: listData};
   }
 
   // ── Single component ───────────────────────────────────────────
 
+  if (typeof name !== 'string') {
+    throw new AstryxError(
+      `No component named "${String(name)}"`,
+      undefined,
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+  }
+
   const dirName = name.replace(/^XDS/, '');
 
+  // Ownership-aware resolution. Build the set of OWNER packages that provide a
+  // component with this name across core + every loaded integration. This is
+  // what lets the CLI disambiguate by package and expose the owner's source +
+  // issuesUrl (the inputs the future integration-component swizzle needs).
+  const loadedIntegrations = await loadIntegrationsSafely(cwd);
+  const coreDocPath = findComponentReadme(coreDir, dirName);
+  /**
+   * @type {Array<{
+   *   package: string,
+   *   docPath: string,
+   *   sourcePath: string|null,
+   *   issuesUrl: string|undefined,
+   *   integration: object|null,
+   * }>}
+   */
+  const owners = [];
+  if (coreDocPath) {
+    owners.push({
+      package: CORE_PACKAGE,
+      docPath: coreDocPath,
+      sourcePath: findComponentSource(coreDir, dirName),
+      issuesUrl: undefined,
+      integration: null,
+    });
+  }
+  for (const integration of loadedIntegrations) {
+    const docPath = findIntegrationComponentDoc(integration, dirName);
+    if (!docPath) continue;
+    owners.push({
+      package: integration.name,
+      docPath,
+      sourcePath: findIntegrationComponentSource(integration, dirName),
+      issuesUrl: integration.issuesUrl,
+      integration,
+    });
+  }
+
+  /**
+   * Augment a loaded `component.detail` doc with ownership metadata. Adds
+   * `package`, the resolved `import` specifier, and `sourceAvailable` (whether
+   * a swizzleable source file exists for the owner). Existing doc fields
+   * (name, usage, props, …) are preserved.
+   * @param {object} docs
+   * @param {{package: string, sourcePath: string|null}} owner
+   * @param {string} componentName
+   */
+  function withOwnership(docs, owner, componentName) {
+    const importSpec =
+      owner.package === CORE_PACKAGE
+        ? resolveImportPath(coreDir, componentName)
+        : `${owner.package}/${componentName}`;
+    return {
+      ...docs,
+      package: owner.package,
+      import: importSpec,
+      sourceAvailable: owner.sourcePath != null,
+    };
+  }
+
   // When scoped to a specific package, search that package first.
   // This is critical for components that exist in both core and an external
   // package (e.g. AppShell, Button, SideNav) — the package scope ensures
   // the external package's docs are returned, not core's.
   if (packageScope) {
+    // Core scope: resolve from core directly.
+    if (packageScope === CORE_PACKAGE) {
+      const owner = owners.find(o => o.package === CORE_PACKAGE);
+      if (!owner) {
+        throw new AstryxError(`No component "${name}" in package "${packageScope}"`, undefined, ERROR_CODES.ERR_UNKNOWN_COMPONENT);
+      }
+      if (source) {
+        if (!owner.sourcePath) {
+          throw new AstryxError(`Source for "${name}" not found`, undefined, ERROR_CODES.ERR_NO_SOURCE);
+        }
+        return {type: 'component.detail.source', data: {component: dirName, source: fs.readFileSync(owner.sourcePath, 'utf-8')}};
+      }
+      const docs = await loadDocs(owner.docPath, {zh, dense, lang});
+      if (props) {
+        const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
+        return {type: 'component.detail.props', data: p};
+      }
+      return {type: 'component.detail', data: withOwnership(docs, owner, dirName)};
+    }
+
+    // Integration scope (authoritative): resolve from the loaded integration.
+    const integration = findLoadedIntegration(loadedIntegrations, packageScope);
+    if (integration) {
+      const owner = owners.find(o => o.package === packageScope);
+      if (!owner) {
+        throw new AstryxError(`No component "${name}" in package "${packageScope}"`, undefined, ERROR_CODES.ERR_UNKNOWN_COMPONENT);
+      }
+      if (source) {
+        if (!owner.sourcePath) {
+          throw new AstryxError(`Source for "${name}" not found in package "${packageScope}"`, undefined, ERROR_CODES.ERR_NO_SOURCE);
+        }
+        return {type: 'component.detail.source', data: {component: dirName, source: fs.readFileSync(owner.sourcePath, 'utf-8')}};
+      }
+      const docs = await loadDocs(owner.docPath, {zh, dense, lang});
+      if (props) {
+        const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
+        return {type: 'component.detail.props', data: p};
+      }
+      return {type: 'component.detail', data: withOwnership(docs, owner, dirName)};
+    }
+
+    // Legacy fallback: node_modules `pkg.astryx.docs` external package.
     const ext = resolveExternalPackage(packageScope, cwd);
     if (!ext) {
       throw new AstryxError(`External package "${packageScope}" not found`, undefined, ERROR_CODES.ERR_UNKNOWN_PACKAGE);
@@ -244,11 +425,49 @@ export async function component(name, options = {}) {
         const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
         return {type: 'component.detail.props', data: p};
       }
-      return {type: 'component.detail', data: docs};
+      return {
+        type: 'component.detail',
+        data: withOwnership(docs, {package: ext.name, sourcePath: null}, dirName),
+      };
     }
     throw new AstryxError(`No component "${name}" in package "${packageScope}"`, undefined, ERROR_CODES.ERR_UNKNOWN_COMPONENT);
   }
 
+  // Ambiguity: when the name is owned by MORE THAN ONE package (core and/or
+  // integrations) and the caller did not scope with --package, refuse to guess.
+  // NOTE: legacy `pkg.astryx.docs` externals are intentionally NOT part of this
+  // ambiguity set — they retain their historical core-first fallback below so
+  // existing consumers (and tests) keep working. Only config-driven integration
+  // ownership participates here.
+  if (owners.length > 1) {
+    throw new AstryxError(
+      `Component "${dirName}" is provided by multiple packages. Re-run with --package <pkg> to choose one.`,
+      owners.map(o => ({name: o.package, reason: 'provides this component'})),
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+  }
+
+  // Single non-core owner (an integration provides it, core does not) — resolve
+  // from that integration so the integration component is authoritative.
+  if (owners.length === 1 && owners[0].package !== CORE_PACKAGE) {
+    const owner = owners[0];
+    if (source) {
+      if (!owner.sourcePath) {
+        throw new AstryxError(`Source for "${name}" not found`, undefined, ERROR_CODES.ERR_NO_SOURCE);
+      }
+      return {type: 'component.detail.source', data: {component: dirName, source: fs.readFileSync(owner.sourcePath, 'utf-8')}};
+    }
+    if (showcase) {
+      throw new AstryxError(`No showcase found for "${name}"`, undefined, ERROR_CODES.ERR_NO_SHOWCASE);
+    }
+    const docs = await loadDocs(owner.docPath, {zh, dense, lang});
+    if (props) {
+      const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
+      return {type: 'component.detail.props', data: p};
+    }
+    return {type: 'component.detail', data: withOwnership(docs, owner, dirName)};
+  }
+
   if (source) {
     const sourcePath = findComponentSource(coreDir, dirName);
     if (!sourcePath) {
@@ -274,6 +493,10 @@ export async function component(name, options = {}) {
 
   let readmePath = findComponentReadme(coreDir, dirName);
   let resolvedName = dirName;
+  // Track the resolving owner so the detail payload can carry ownership info.
+  // Defaults to core; the legacy-external fallback below may reassign it.
+  let resolvedOwnerPackage = CORE_PACKAGE;
+  let resolvedSourcePath = readmePath ? findComponentSource(coreDir, dirName) : null;
 
   if (!readmePath) {
     const externals = discoverExternalPackages(cwd);
@@ -281,6 +504,8 @@ export async function component(name, options = {}) {
       const extDocPath = findExternalComponentDoc(ext.docsDir, dirName);
       if (extDocPath) {
         readmePath = extDocPath;
+        resolvedOwnerPackage = ext.name;
+        resolvedSourcePath = null;
         break;
       }
     }
@@ -299,6 +524,8 @@ export async function component(name, options = {}) {
       if (topScore >= 90 && topTied.length === 1 && gap >= 20) {
         resolvedName = topTied[0].name;
         readmePath = findComponentReadme(coreDir, resolvedName);
+        resolvedOwnerPackage = CORE_PACKAGE;
+        resolvedSourcePath = findComponentSource(coreDir, resolvedName);
       } else {
         const threshold = Math.max(topScore - 20, 1);
         const candidates = results.filter(r => r.score >= threshold).slice(0, 5);
@@ -382,7 +609,14 @@ export async function component(name, options = {}) {
     if (props) {
       return {type: 'component.detail.props', data: matchingComponent.props || []};
     }
-    return {type: 'component.detail', data: scoped};
+    return {
+      type: 'component.detail',
+      data: withOwnership(
+        scoped,
+        {package: resolvedOwnerPackage, sourcePath: resolvedSourcePath},
+        dirName,
+      ),
+    };
   }
 
   if (props) {
@@ -390,5 +624,12 @@ export async function component(name, options = {}) {
     return {type: 'component.detail.props', data: p};
   }
 
-  return {type: 'component.detail', data: docs};
+  return {
+    type: 'component.detail',
+    data: withOwnership(
+      docs,
+      {package: resolvedOwnerPackage, sourcePath: resolvedSourcePath},
+      resolvedName,
+    ),
+  };
 }

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/index.mjs

@@ -21,6 +21,7 @@
 
 export {component} from './component.mjs';
 export {docs} from './docs.mjs';
+export {blog} from './blog.mjs';
 export {discover} from './discover.mjs';
 export {template} from './template.mjs';
 export {themeAdd, listThemes} from './theme-add.mjs';

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',