@astryxdesign/cli 0.1.2 → 0.1.3

package/src/lib/integrations.mjs

@@ -3,95 +3,89 @@
 /**
  * @file Integration manifest loading for Astryx config.
  *
- * Integrations are package names or direct manifest paths listed in
- * astryx.config.mjs. A manifest can contribute docs/discovery metadata,
- * gap-report/template hooks, upgrade codemods, and post-codemod hooks.
+ * Integrations are PACKAGE NAMES listed in astryx.config.{ts,mjs,js}. Each
+ * package declares a single conventional root manifest sibling to its
+ * package.json — astryx.integration.{ts,mjs,js} — which contributes
+ * components/templates/codemods roots and an optional issuesUrl. Identity
+ * (name, version) comes from the package's package.json, not the manifest.
  */
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {pathToFileURL} from 'node:url';
-import {validateIntegration} from './config-schema.mjs';
+import {AstryxIntegrationSchema} from './config-schema.mjs';
+import {loadModuleWithSchema, findPresentFiles} from './module-loader.mjs';
 
-export function isPathSpec(spec) {
-  return (
-    spec.startsWith('.') ||
-    spec.startsWith('/') ||
-    spec.endsWith('.mjs') ||
-    spec.endsWith('.js')
-  );
+/** Conventional manifest basenames, in load-precedence order. */
+export const MANIFEST_BASENAMES = [
+  'astryx.integration.ts',
+  'astryx.integration.mjs',
+  'astryx.integration.js',
+];
+
+/**
+ * Return the conventional root manifest paths present in `dir`, in
+ * load-precedence order. Unlike {@link resolveManifestPath} this never throws —
+ * callers (e.g. validate-integration) decide how to treat zero / multiple.
+ * @param {string} dir
+ * @returns {string[]} absolute manifest paths
+ */
+export function findManifestPaths(dir) {
+  return findPresentFiles(dir, MANIFEST_BASENAMES);
 }
 
+/**
+ * Load and validate a manifest module's default export against the integration
+ * schema. Default export only — `.ts` is loaded via jiti; `.mjs`/`.js` via
+ * dynamic import. Throws if the default export is missing or invalid. Exposed
+ * for validate-integration.
+ * @param {string} file absolute manifest path
+ * @param {string} [label] used in error messages
+ * @returns {Promise<import('../types/integration').AstryxIntegration>}
+ */
+export async function loadManifestObject(file, label = 'integration manifest') {
+  return loadModuleWithSchema(file, AstryxIntegrationSchema, {label});
+}
+
+/**
+ * Resolve the directory of an installed integration package from the consumer's
+ * node_modules.
+ * @param {string} packageName
+ * @param {string} [cwd]
+ */
 export function resolvePackageDir(packageName, cwd = process.cwd()) {
   return path.resolve(cwd, 'node_modules', ...packageName.split('/'));
 }
 
-export function resolveIntegrationFile(spec, cwd = process.cwd()) {
-  if (isPathSpec(spec)) {
-    return path.resolve(cwd, spec);
-  }
-
-  const packageDir = resolvePackageDir(spec, cwd);
-  const pkgPath = path.join(packageDir, 'package.json');
-  let pkg;
-  try {
-    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-  } catch {
+/**
+ * Find the single conventional root manifest sibling of the package's
+ * package.json. Multiple present is a hard error; missing is a hard error.
+ * @param {string} packageDir
+ * @param {string} spec
+ * @returns {string} absolute manifest path
+ */
+function resolveManifestPath(packageDir, spec) {
+  const present = findPresentFiles(packageDir, MANIFEST_BASENAMES);
+  if (present.length === 0) {
     throw new Error(
-      `Could not find installed integration package "${spec}" at ${pkgPath}. Install it first or pass a direct integration file path.`,
+      `Integration package "${spec}" has no conventional root manifest. Add one of: ${MANIFEST_BASENAMES.join(', ')} next to its package.json.`,
     );
   }
-
-  const manifestPath = pkg.astryx?.integration ?? pkg.xds?.integration;
-  if (!manifestPath) {
+  if (present.length > 1) {
     throw new Error(
-      `Package "${spec}" does not declare astryx.integration (or legacy xds.integration) in package.json.`,
+      `Integration package "${spec}" has multiple root manifests (${present
+        .map(file => path.basename(file))
+        .join(', ')}). Keep exactly one.`,
     );
   }
-  return path.resolve(packageDir, manifestPath);
-}
-
-function normalizePackageContribution(integration) {
-  const docs = integration.docs;
-  if (!docs) return null;
-  const packageDir = integration.__packageDir ?? integration.__dir;
-  const docsDir = path.resolve(packageDir, docs);
-  return {
-    name: integration.name ?? integration.__spec,
-    version: integration.version,
-    description: integration.description,
-    displayName: integration.displayName,
-    dir: packageDir,
-    astryx: {
-      docs,
-      category: integration.category,
-      blocks: integration.blocks,
-    },
-    category: integration.category ?? integration.name ?? integration.__spec,
-    docsDir,
-  };
-}
-
-function resolveHookFunction(hook, integration) {
-  if (typeof hook === 'function') return hook;
-  if (typeof hook !== 'string') return hook;
-  const [moduleSpec, exportName = 'default'] = hook.split('#');
-  return async (...args) => {
-    const mod = isPathSpec(moduleSpec)
-      ? await import(
-          pathToFileURL(path.resolve(integration.__dir, moduleSpec)).href
-        )
-      : await import(moduleSpec);
-    const fn = exportName === 'default' ? mod.default : mod[exportName];
-    if (typeof fn !== 'function') {
-      throw new Error(
-        `Integration hook ${hook} did not resolve to a function.`,
-      );
-    }
-    return fn(...args);
-  };
+  return present[0];
 }
 
+/**
+ * Load configured integrations.
+ *
+ * @param {string[]} [specs] package names
+ * @param {{cwd?: string}} [options]
+ */
 export async function loadIntegrations(specs = [], {cwd = process.cwd()} = {}) {
   const integrations = [];
   const seen = new Set();
@@ -100,55 +94,38 @@ export async function loadIntegrations(specs = [], {cwd = process.cwd()} = {}) {
     if (!spec || seen.has(spec)) continue;
     seen.add(spec);
 
-    const file = resolveIntegrationFile(spec, cwd);
-    const mod = await import(pathToFileURL(file).href);
-    const exported = mod.default ?? mod.integration ?? mod;
-    if (!exported || typeof exported !== 'object') {
-      throw new Error(`Integration ${spec} did not export an object.`);
+    const packageDir = resolvePackageDir(spec, cwd);
+    const pkgPath = path.join(packageDir, 'package.json');
+    let pkg;
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    } catch {
+      throw new Error(
+        `Could not find installed integration package "${spec}" at ${pkgPath}. Install it first.`,
+      );
     }
-    const integration = validateIntegration(exported, `Integration ${spec}`);
 
-    const integrationDir = path.dirname(file);
-    const packageDir = isPathSpec(spec)
-      ? integrationDir
-      : resolvePackageDir(spec, cwd);
-    const normalized = {
-      ...integration,
-      __file: file,
-      __dir: integrationDir,
-      __packageDir: packageDir,
-      __spec: spec,
-    };
-
-    if (Array.isArray(normalized.codemods)) {
-      for (const codemod of normalized.codemods) {
-        if (typeof codemod.transform === 'string') {
-          const transformPath = path.resolve(integrationDir, codemod.transform);
-          const transformMod = await import(pathToFileURL(transformPath).href);
-          codemod.transform =
-            transformMod.default ?? transformMod.transform ?? transformMod;
-        }
-      }
-    }
+    const manifestFile = resolveManifestPath(packageDir, spec);
+    const manifest = await loadModuleWithSchema(
+      manifestFile,
+      AstryxIntegrationSchema,
+      {label: `Integration ${spec}`},
+    );
 
-    normalized.package = normalizePackageContribution(normalized);
-    if (
-      normalized.gapReport?.command &&
-      isPathSpec(normalized.gapReport.command)
-    ) {
-      normalized.gapReport = {
-        ...normalized.gapReport,
-        command: path.resolve(packageDir, normalized.gapReport.command),
-      };
-    }
-    if (normalized.template?.get) {
-      normalized.template = {
-        ...normalized.template,
-        get: resolveHookFunction(normalized.template.get, normalized),
-      };
-    }
+    const resolveRoot = value =>
+      value == null ? undefined : path.resolve(packageDir, value);
 
-    integrations.push(normalized);
+    integrations.push({
+      name: pkg.name ?? spec,
+      version: pkg.version,
+      components: resolveRoot(manifest.components),
+      templates: resolveRoot(manifest.templates),
+      codemods: resolveRoot(manifest.codemods),
+      issuesUrl: manifest.issuesUrl,
+      __spec: spec,
+      __packageDir: packageDir,
+      __manifestFile: manifestFile,
+    });
   }
 
   return integrations;

package/src/lib/integrations.test.mjs

@@ -3,91 +3,39 @@
 import {afterEach, beforeEach, describe, expect, it} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {loadConfig} from './config.mjs';
+import {Project} from './project.mjs';
+import {loadIntegrations} from './integrations.mjs';
 import {discover} from '../api/discover.mjs';
-import {loadGapReportConfig} from '../utils/github.mjs';
-import {getTemplateById} from '../api/template.mjs';
 
 let tmpDir;
 let originalCwd;
 
-beforeEach(() => {
-  originalCwd = process.cwd();
-  tmpDir = fs.mkdtempSync(
-    path.join(process.cwd(), '.astryx-integration-test-'),
-  );
-  fs.mkdirSync(path.join(tmpDir, 'node_modules', '@acme', 'widgets'), {
-    recursive: true,
-  });
+function writeManifestPackage(dir, {basename = 'astryx.integration.mjs', body}) {
+  const pkgDir = path.join(dir, 'node_modules', '@acme', 'widgets');
+  fs.mkdirSync(pkgDir, {recursive: true});
   fs.writeFileSync(
-    path.join(tmpDir, 'astryx.config.mjs'),
-    `export default { integrations: '@acme/widgets' };\n`,
-  );
-  fs.writeFileSync(
-    path.join(tmpDir, 'node_modules', '@acme', 'widgets', 'package.json'),
+    path.join(pkgDir, 'package.json'),
     JSON.stringify({
       name: '@acme/widgets',
       version: '1.2.3',
-      displayName: 'Acme Widgets',
-      astryx: {integration: './astryx.integration.mjs'},
     }),
   );
-  fs.writeFileSync(
-    path.join(
-      tmpDir,
-      'node_modules',
-      '@acme',
-      'widgets',
-      'astryx.integration.mjs',
-    ),
-    `export default {
-      name: '@acme/widgets',
-      version: '1.2.3',
-      displayName: 'Acme Widgets',
-      docs: './docs',
-      category: 'Acme',
-      gapReport: {command: './scripts/report-gap.sh'},
-      template: {get: './template.mjs#getTemplate'},
-      codemods: [{name: 'noop', from: '0.0.0', to: '9.0.0', transform: './codemod.mjs'}],
-    };\n`,
-  );
-  fs.mkdirSync(path.join(tmpDir, 'node_modules', '@acme', 'widgets', 'docs'));
-  fs.writeFileSync(
-    path.join(
-      tmpDir,
-      'node_modules',
-      '@acme',
-      'widgets',
-      'docs',
-      'Widget.doc.mjs',
-    ),
-    `export const doc = {
-      name: 'Widget',
-      usage: {description: 'Acme widget'},
-      props: [],
-    };\n`,
-  );
-  fs.mkdirSync(
-    path.join(tmpDir, 'node_modules', '@acme', 'widgets', 'scripts'),
-  );
-  fs.writeFileSync(
-    path.join(
-      tmpDir,
-      'node_modules',
-      '@acme',
-      'widgets',
-      'scripts',
-      'report-gap.sh',
-    ),
-    '#!/bin/sh\ncat >/dev/null\necho ok\n',
+  fs.writeFileSync(path.join(pkgDir, basename), body);
+  return pkgDir;
+}
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  tmpDir = fs.mkdtempSync(
+    path.join(process.cwd(), '.astryx-integration-test-'),
   );
   fs.writeFileSync(
-    path.join(tmpDir, 'node_modules', '@acme', 'widgets', 'template.mjs'),
-    `export async function getTemplate(id) { return 'template:' + id; }\n`,
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'consumer'}),
   );
   fs.writeFileSync(
-    path.join(tmpDir, 'node_modules', '@acme', 'widgets', 'codemod.mjs'),
-    `export default function transform() { return undefined; }\n`,
+    path.join(tmpDir, 'astryx.config.mjs'),
+    `export default { integrations: ['@acme/widgets'] };\n`,
   );
   process.chdir(tmpDir);
 });
@@ -98,57 +46,90 @@ afterEach(() => {
 });
 
 describe('configured integrations', () => {
-  it('load docs/gap/template/codemod metadata from integration manifests', async () => {
-    const config = await loadConfig(tmpDir);
-    expect(config.integrations).toEqual(['@acme/widgets']);
-    expect(config.loadedIntegrations[0].name).toBe('@acme/widgets');
-    expect(config.loadedIntegrations[0].package).toMatchObject({
-      name: '@acme/widgets',
-      category: 'Acme',
+  it('resolves identity from package.json and contribution roots to absolute paths', async () => {
+    const pkgDir = writeManifestPackage(tmpDir, {
+      body: `export default {
+        components: './docs',
+        templates: './blocks',
+        codemods: './codemods',
+        issuesUrl: 'https://example.com/issues',
+      };\n`,
     });
-    expect(config.loadedIntegrations[0].codemods[0].transform).toEqual(
-      expect.any(Function),
-    );
-    expect(config.gapReport.command).toBe(
-      path.join(
-        tmpDir,
-        'node_modules',
-        '@acme',
-        'widgets',
-        'scripts',
-        'report-gap.sh',
-      ),
+    fs.mkdirSync(path.join(pkgDir, 'docs'));
+    fs.writeFileSync(
+      path.join(pkgDir, 'docs', 'Widget.doc.mjs'),
+      `export const doc = {
+        name: 'Widget',
+        usage: {description: 'Acme widget'},
+        props: [],
+      };\n`,
     );
-    await expect(config.template.get('P123')).resolves.toBe('template:P123');
+
+    const project = await Project.load(tmpDir);
+    expect(project.integrations).toEqual(['@acme/widgets']);
+    const loaded = project.loadedIntegrations[0];
+    // Identity comes from package.json, not the manifest.
+    expect(loaded.name).toBe('@acme/widgets');
+    expect(loaded.version).toBe('1.2.3');
+    expect(loaded.components).toBe(path.join(pkgDir, 'docs'));
+    expect(loaded.templates).toBe(path.join(pkgDir, 'blocks'));
+    expect(loaded.codemods).toBe(path.join(pkgDir, 'codemods'));
+    expect(loaded.issuesUrl).toBe('https://example.com/issues');
   });
 
-  it('makes integration docs discoverable without packages config', async () => {
+  it('makes integration components discoverable', async () => {
+    const pkgDir = writeManifestPackage(tmpDir, {
+      body: `export default { components: './docs' };\n`,
+    });
+    fs.mkdirSync(path.join(pkgDir, 'docs'));
+    fs.writeFileSync(
+      path.join(pkgDir, 'docs', 'Widget.doc.mjs'),
+      `export const doc = {
+        name: 'Widget',
+        usage: {description: 'Acme widget'},
+        props: [],
+      };\n`,
+    );
+
     const result = await discover(undefined, {});
     expect(result.type).toBe('discover.list');
     expect(result.data).toEqual([
       expect.objectContaining({
         name: '@acme/widgets',
-        category: 'Acme',
+        category: '@acme/widgets',
         components: ['Widget'],
       }),
     ]);
   });
 
-  it('uses integration gap-report and template hooks', async () => {
-    await expect(loadGapReportConfig()).resolves.toMatchObject({
-      enabled: true,
-      command: path.join(
-        tmpDir,
-        'node_modules',
-        '@acme',
-        'widgets',
-        'scripts',
-        'report-gap.sh',
-      ),
-    });
-    await expect(getTemplateById('P123', {cwd: tmpDir})).resolves.toEqual({
-      type: 'template.get',
-      data: {id: 'P123', source: 'template:P123'},
+  it('errors when the package has no conventional root manifest', async () => {
+    const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+    fs.mkdirSync(pkgDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(pkgDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets'}),
+    );
+    await expect(loadIntegrations(['@acme/widgets'], {cwd: tmpDir})).rejects.toThrow(
+      /no conventional root manifest/,
+    );
+  });
+
+  it('errors when the package has multiple root manifests', async () => {
+    const pkgDir = writeManifestPackage(tmpDir, {
+      body: `export default {};\n`,
     });
+    fs.writeFileSync(
+      path.join(pkgDir, 'astryx.integration.js'),
+      `module.exports = {};\n`,
+    );
+    await expect(loadIntegrations(['@acme/widgets'], {cwd: tmpDir})).rejects.toThrow(
+      /multiple root manifests/,
+    );
+  });
+
+  it('errors when the package is not installed', async () => {
+    await expect(loadIntegrations(['@acme/missing'], {cwd: tmpDir})).rejects.toThrow(
+      /Could not find installed integration package/,
+    );
   });
 });

package/src/lib/manifest.mjs

@@ -56,16 +56,15 @@ export const RESPONSE_TYPES = {
     'template.show',
     'template.skeleton',
     'template.copy',
-    'template.get',
   ],
   hook: ['hook.list', 'hook.brief', 'hook.full', 'hook.detail', 'hook.detail.params'],
   'theme build': ['theme.build'],
   'theme list': ['theme.list'],
   'theme add': ['theme.list', 'theme.add'],
   upgrade: ['upgrade.list', 'upgrade.status', 'upgrade.run'],
-  'gap-report': ['gap-report.categories', 'gap-report.dryRun', 'gap-report.file'],
   manifest: ['manifest'],
   doctor: ['doctor'],
+  'validate-integration': ['integration.validate'],
   'layout expand': ['layout.expand'],
   'layout check': ['layout.check'],
   'layout grammar': ['layout.grammar'],
@@ -89,6 +88,10 @@ const EXAMPLES = {
   upgrade: ['astryx upgrade --json'],
   manifest: ['astryx manifest --json', 'astryx --json'],
   doctor: ['astryx doctor', 'astryx doctor --json'],
+  'validate-integration': [
+    'astryx validate-integration',
+    'astryx validate-integration @acme/widgets --json',
+  ],
   init: ['astryx init'],
   'layout expand': [`astryx layout expand 'V[g6] > C{card-callout}*4' ./src/Page.tsx`],
   'layout check': [`astryx layout check 'A[cp6] > L > LC > S[p6]' --json`],

package/src/lib/module-loader.mjs

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Shared module-loading + conventional-file-discovery primitives.
+ *
+ * Both config loading and integration loading need to (a) import a
+ * user-authored module (`.ts` via jiti, `.mjs`/`.js` via native dynamic
+ * import) and (b) find conventional files by basename in a fixed
+ * load-precedence order. These helpers centralize that so the two callers stay
+ * in lockstep.
+ *
+ * `loadModuleWithSchema` builds on these primitives to provide the single
+ * load/validation boundary shared by config, integration, codemod, and
+ * template discovery: import the module, take its default export, and validate
+ * it against the expected zod schema.
+ */
+
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import * as fs from 'node:fs';
+import {createJiti} from 'jiti';
+import {formatZodError} from './config-schema.mjs';
+
+let jitiInstance;
+function getJiti() {
+  if (!jitiInstance) {
+    jitiInstance = createJiti(import.meta.url);
+  }
+  return jitiInstance;
+}
+
+/**
+ * Import a user-authored module. `.ts` is loaded via jiti; `.mjs`/`.js` via
+ * native dynamic import (file:// URL). Returns the full module namespace.
+ * @param {string} file absolute path
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function importUserModule(file) {
+  if (file.endsWith('.ts')) {
+    return await getJiti().import(file);
+  }
+  return await import(pathToFileURL(file).href);
+}
+
+/**
+ * Return the conventional files (by basename, in the given precedence order)
+ * that exist directly in `dir`, as absolute paths. Never throws.
+ * @param {string} dir
+ * @param {string[]} basenames precedence-ordered
+ * @returns {string[]} absolute paths of present files, in basenames order
+ */
+export function findPresentFiles(dir, basenames) {
+  return basenames
+    .filter(name => fs.existsSync(path.join(dir, name)))
+    .map(name => path.join(dir, name));
+}
+
+/**
+ * Import a user-authored module, take its default export, and validate it
+ * against a zod schema. This is the single load/validation boundary for all
+ * user-authored modules (config, integration, codemod, template): execute the
+ * module, take the default export, validate it against the expected schema.
+ * Throws a clear, readable error if the default export is missing or fails
+ * validation.
+ *
+ * @template {import('zod').ZodType} S
+ * @param {string} file absolute path
+ * @param {S} schema
+ * @param {{label?: string}} [opts] label used in error messages
+ * @returns {Promise<import('zod').infer<S>>} parsed + typed value
+ */
+export async function loadModuleWithSchema(file, schema, {label} = {}) {
+  const mod = await importUserModule(file);
+  const exported = mod?.default;
+  const result = schema.safeParse(exported);
+  if (!result.success) {
+    throw new Error(formatZodError(label ?? file, result.error));
+  }
+  return result.data;
+}