@astryxdesign/cli 0.1.1 → 0.1.2-canary.2149fa3

package/src/commands/swizzle.mjs

@@ -15,7 +15,11 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as p from '@clack/prompts';
 import {findCoreDir, listComponents} from '../utils/paths.mjs';
-import {assertWithin, PathSafetyError, isNonInteractive} from '../utils/path-safety.mjs';
+import {
+  assertWithin,
+  PathSafetyError,
+  isNonInteractive,
+} from '../utils/path-safety.mjs';
 import {isInteractive} from '../utils/interactive.mjs';
 import {jsonOut, humanLog} from '../lib/json.mjs';
 import {cliError} from '../lib/cli-error.mjs';
@@ -104,7 +108,9 @@ export function registerSwizzle(program) {
         }
         humanLog(`\nUsage: astryx swizzle <component>\n`);
         humanLog('Example: astryx swizzle Button');
-        humanLog('         astryx swizzle XDSButton  (XDS prefix also works)\n');
+        humanLog(
+          '         astryx swizzle XDSButton  (XDS prefix also works)\n',
+        );
         return;
       }
 
@@ -112,10 +118,10 @@ export function registerSwizzle(program) {
       const componentDir = path.join(coreDir, 'src', dirName);
 
       if (!fs.existsSync(componentDir)) {
-        cliError(
-          `Component "${component}" not found.`,
-          {suggestions: components.slice(0, 10).map((n) => ({name: n})), code: ERROR_CODES.ERR_UNKNOWN_COMPONENT},
-        );
+        cliError(`Component "${component}" not found.`, {
+          suggestions: components.slice(0, 10).map(n => ({name: n})),
+          code: ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+        });
         return;
       }
 
@@ -196,11 +202,16 @@ export function registerSwizzle(program) {
       }
 
       const relOutput = path.relative(process.cwd(), outputDir);
-      const copiedFiles = files.filter(f => !f.includes('.test.') && f !== 'README.md' && fs.statSync(path.join(componentDir, f)).isFile());
+      const copiedFiles = files.filter(
+        f =>
+          !f.includes('.test.') &&
+          f !== 'README.md' &&
+          fs.statSync(path.join(componentDir, f)).isFile(),
+      );
 
       // --- Gap reporting ---
 
-      const gapConfig = loadGapReportConfig();
+      const gapConfig = await loadGapReportConfig();
       let gapReportUrl = null;
       let gapDryRunPreview = null;
 
@@ -224,7 +235,7 @@ export function registerSwizzle(program) {
           json,
         });
 
-        const preview = buildGapReportPreview(previewArgs);
+        const preview = await buildGapReportPreview(previewArgs);
 
         if (!willFile) {
           // Dry-run: do NOT call gh. Surface what would have been filed.
@@ -239,10 +250,12 @@ export function registerSwizzle(program) {
           };
         } else if (gapConfig.command || checkGhCli()) {
           try {
-            gapReportUrl = createGapReport(previewArgs);
+            gapReportUrl = await createGapReport(previewArgs);
           } catch (err) {
             if (!json)
-              console.error(`Warning: Could not file gap report: ${err.message}`);
+              console.error(
+                `Warning: Could not file gap report: ${err.message}`,
+              );
           }
         }
       }
@@ -259,17 +272,23 @@ export function registerSwizzle(program) {
             gapReportSuppressed: reportingSuppressed || !gapConfig.enabled,
           });
         humanLog(`\n✓ Copied ${copied} files to ${relOutput}/\n`);
-        humanLog('Relative imports have been rewritten to use @astryxdesign/core.');
+        humanLog(
+          'Relative imports have been rewritten to use @astryxdesign/core.',
+        );
         humanLog('You can now customize the component source freely.\n');
         if (gapReportUrl) {
           humanLog(`✓ Gap report filed: ${gapReportUrl}\n`);
         } else if (gapDryRunPreview) {
-          humanLog(formatPreview(buildGapReportPreview({
-            component: dirName,
-            category: options.gapCategory || 'other',
-            intention: options.gap,
-            source: 'llm-auto',
-          })));
+          humanLog(
+            formatPreview(
+              await buildGapReportPreview({
+                component: dirName,
+                category: options.gapCategory || 'other',
+                intention: options.gap,
+                source: 'llm-auto',
+              }),
+            ),
+          );
           humanLog(
             '\n[dry-run] No gap report was filed. Re-run with --commit to file.',
           );
@@ -283,10 +302,18 @@ export function registerSwizzle(program) {
         return;
       }
 
-      if (json) return jsonOut('swizzle.copy', {component: dirName, outputDir: relOutput, filesCopied: copied, files: copiedFiles.map(f => f)});
+      if (json)
+        return jsonOut('swizzle.copy', {
+          component: dirName,
+          outputDir: relOutput,
+          filesCopied: copied,
+          files: copiedFiles.map(f => f),
+        });
 
       humanLog(`\n✓ Copied ${copied} files to ${relOutput}/\n`);
-      humanLog('Relative imports have been rewritten to use @astryxdesign/core.');
+      humanLog(
+        'Relative imports have been rewritten to use @astryxdesign/core.',
+      );
       humanLog('You can now customize the component source freely.\n');
 
       if (reportingSuppressed || !gapConfig.enabled) {
@@ -330,7 +357,8 @@ export function registerSwizzle(program) {
           placeholder:
             'e.g. "Need a compact variant for use in dense data tables"',
           validate: val => {
-            if (!val.trim()) return 'Please describe what you were trying to do';
+            if (!val.trim())
+              return 'Please describe what you were trying to do';
           },
         }),
       );
@@ -350,7 +378,7 @@ export function registerSwizzle(program) {
         source: 'interactive',
       };
 
-      const preview = buildGapReportPreview(previewArgs);
+      const preview = await buildGapReportPreview(previewArgs);
 
       p.note(
         `${preview.mode === 'github' ? `Repo: ${preview.repo}` : `Custom command: ${preview.command}`}\n\n` +
@@ -378,7 +406,7 @@ export function registerSwizzle(program) {
       s.start('Filing gap report');
 
       try {
-        const url = createGapReport(previewArgs);
+        const url = await createGapReport(previewArgs);
         s.stop('Gap report filed');
         humanLog(`✓ ${url}\n`);
       } catch (err) {

package/src/commands/upgrade.mjs

@@ -26,7 +26,6 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {pathToFileURL} from 'node:url';
 import {execFile} from 'node:child_process';
 import {promisify} from 'node:util';
 import * as p from '@clack/prompts';
@@ -38,6 +37,7 @@ import {getRunPrefix} from '../utils/package-manager.mjs';
 import {isValidSemver, semverGte, semverGt} from '../utils/semver.mjs';
 import {jsonOut, jsonError} from '../lib/json.mjs';
 import {loadConfig} from '../lib/config.mjs';
+import {loadIntegrations} from '../lib/integrations.mjs';
 import {ERROR_CODES} from '../lib/error-codes.mjs';
 
 const execFileAsync = promisify(execFile);
@@ -64,75 +64,6 @@ function detectInstalledTargetVersion() {
   return null;
 }
 
-function isPathSpec(spec) {
-  return (
-    spec.startsWith('.') ||
-    spec.startsWith('/') ||
-    spec.endsWith('.mjs') ||
-    spec.endsWith('.js')
-  );
-}
-
-function resolvePackageDir(packageName) {
-  const parts = packageName.split('/');
-  return path.resolve(process.cwd(), 'node_modules', ...parts);
-}
-
-function resolveIntegrationFile(spec) {
-  if (isPathSpec(spec)) {
-    return path.resolve(process.cwd(), spec);
-  }
-
-  const packageDir = resolvePackageDir(spec);
-  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 or pass a direct integration file path.`,
-    );
-  }
-
-  const manifestPath = pkg.astryx?.integration ?? pkg.xds?.integration;
-  if (!manifestPath) {
-    throw new Error(
-      `Package "${spec}" does not declare astryx.integration (or legacy xds.integration) in package.json.`,
-    );
-  }
-  return path.resolve(packageDir, manifestPath);
-}
-
-async function loadIntegrations(specs) {
-  const integrations = [];
-  for (const spec of specs) {
-    const file = resolveIntegrationFile(spec);
-    const mod = await import(pathToFileURL(file).href);
-    const integration = mod.default ?? mod.integration ?? mod;
-    if (!integration || typeof integration !== 'object') {
-      throw new Error(`Integration ${spec} did not export an object.`);
-    }
-    const integrationDir = path.dirname(file);
-    if (Array.isArray(integration.codemods)) {
-      for (const codemod of integration.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;
-        }
-      }
-    }
-    integrations.push({
-      ...integration,
-      __file: file,
-      __dir: integrationDir,
-      __spec: spec,
-    });
-  }
-  return integrations;
-}
-
 function normalizeIntegrationTransforms(integration, from, to) {
   const transforms = [];
   for (const entry of integration.codemods ?? []) {
@@ -507,7 +438,7 @@ export function registerUpgrade(program) {
         } catch {
           if (!json) {
             p.log.warn(
-              `Could not update agent docs. Run \`${getRunPrefix()} astryx agent-docs\` to update manually.`,
+              `Could not update agent docs. Run \`${getRunPrefix()} astryx init --features agents\` to update manually.`,
             );
           }
         }

package/src/config.mjs

@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {validateConfig, validateIntegration} from './lib/config-schema.mjs';
+
+/**
+ * Type-preserving helpers for Astryx config and integration manifests.
+ *
+ * These are intentionally tiny runtime identity functions. Their value is the
+ * exported TypeScript surface from `@astryxdesign/cli/config`, so config files
+ * can get editor/type feedback without coupling to CLI internals.
+ */
+
+/**
+ * @template {import('./types/config').AstryxConfig} T
+ * @param {T} config
+ * @returns {T}
+ */
+export function createConfig(config) {
+  validateConfig(config);
+  return config;
+}
+
+/**
+ * @template {import('./types/config').AstryxIntegration} T
+ * @param {T} integration
+ * @returns {T}
+ */
+export function createIntegration(integration) {
+  validateIntegration(integration);
+  return integration;
+}

package/src/config.test.mjs

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {createConfig, createIntegration} from './config.mjs';
+
+describe('config helpers', () => {
+  it('return config and integration objects unchanged', () => {
+    const config = {integrations: ['@acme/widgets']};
+    const integration = {name: '@acme/widgets', docs: './docs'};
+    expect(createConfig(config)).toBe(config);
+    expect(createIntegration(integration)).toBe(integration);
+  });
+
+  it('validates config and integration shapes', () => {
+    expect(() => createConfig({integrations: [42]})).toThrow(/integrations/);
+    expect(() => createIntegration({docs: './docs'})).toThrow(/name/);
+    expect(() =>
+      createIntegration({
+        name: '@acme/widgets',
+        postCodemod: [{name: 'empty'}],
+      }),
+    ).toThrow(/postCodemod/);
+  });
+});

package/src/index.mjs

@@ -59,10 +59,15 @@ export const JSON_SUPPORTED = new Set([
   'template',
   'hook',
   'theme build',
+  'theme list',
+  'theme add',
   'gap-report',
   'upgrade',
   'manifest',
   'doctor',
+  'layout expand',
+  'layout check',
+  'layout grammar',
 ]);
 
 program
@@ -243,6 +248,7 @@ const commands = [
   {name: 'swizzle', path: './commands/swizzle.mjs', register: 'registerSwizzle'},
   // agent-docs folded into init — functions still importable from agent-docs.mjs
   {name: 'template', path: './commands/template.mjs', register: 'registerTemplate'},
+  {name: 'layout', path: './commands/layout.mjs', register: 'registerLayout'},
   {name: 'gap-report', path: './commands/gap-report.mjs', register: 'registerGapReport'},
   {name: 'upgrade', path: './commands/upgrade.mjs', register: 'registerUpgrade'},
   {name: 'theme', path: './commands/build-theme.mjs', register: 'registerTheme'},

package/src/lib/config-schema.mjs

@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Runtime schemas for Astryx config and integration manifests. */
+
+import {z} from 'zod';
+
+const Fn = z.custom(value => typeof value === 'function', {
+  message: 'Expected function',
+});
+
+const StringOrStringArray = z.union([z.string(), z.array(z.string())]);
+const GapReportSchema = z.union([
+  z.literal(false),
+  z.object({command: z.string()}).passthrough(),
+]);
+
+export const AstryxConfigSchema = z
+  .object({
+    packages: StringOrStringArray.optional(),
+    integrations: StringOrStringArray.optional(),
+    gapReport: GapReportSchema.optional(),
+    template: z
+      .object({
+        get: Fn.optional(),
+      })
+      .passthrough()
+      .optional(),
+  })
+  .passthrough();
+
+export const AstryxIntegrationCodemodSchema = z
+  .object({
+    name: z.string(),
+    from: z.string().optional(),
+    to: z.string().optional(),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    pr: z.string().optional(),
+    optional: z.boolean().optional(),
+    fileExtensions: z.array(z.string()).optional(),
+    transform: z.union([z.string(), Fn]),
+  })
+  .passthrough();
+
+export const AstryxPostCodemodHookSchema = z
+  .object({
+    name: z.string().optional(),
+    run: Fn.optional(),
+    command: Fn.optional(),
+  })
+  .passthrough()
+  .refine(value => value.run || value.command, {
+    message: 'postCodemod hook must define run() or command()',
+  });
+
+export const AstryxIntegrationSchema = z
+  .object({
+    name: z.string(),
+    version: z.string().optional(),
+    displayName: z.string().optional(),
+    description: z.string().optional(),
+    docs: z.string().optional(),
+    category: z.string().optional(),
+    blocks: z.string().optional(),
+    gapReport: GapReportSchema.optional(),
+    template: z
+      .object({
+        get: z.union([z.string(), Fn]).optional(),
+      })
+      .passthrough()
+      .optional(),
+    codemods: z.array(AstryxIntegrationCodemodSchema).optional(),
+    postCodemod: z.array(AstryxPostCodemodHookSchema).optional(),
+  })
+  .passthrough();
+
+/**
+ * @param {string} label
+ * @param {import('zod').ZodError} error
+ */
+function formatZodError(label, error) {
+  const issues = error.issues
+    .map(issue => {
+      const path = issue.path.length ? issue.path.join('.') : '(root)';
+      return `${path}: ${issue.message}`;
+    })
+    .join('; ');
+  return `${label} is invalid: ${issues}`;
+}
+
+/**
+ * @param {unknown} config
+ * @returns {import('../types/config').AstryxConfig}
+ */
+export function validateConfig(config) {
+  const result = AstryxConfigSchema.safeParse(config);
+  if (!result.success) {
+    throw new Error(
+      formatZodError('astryx.config.mjs default export', result.error),
+    );
+  }
+  return result.data;
+}
+
+/**
+ * @param {unknown} integration
+ * @param {string} [label]
+ * @returns {import('../types/config').AstryxIntegration}
+ */
+export function validateIntegration(
+  integration,
+  label = 'integration manifest',
+) {
+  const result = AstryxIntegrationSchema.safeParse(integration);
+  if (!result.success) {
+    throw new Error(formatZodError(label, result.error));
+  }
+  return result.data;
+}

package/src/lib/config.mjs

@@ -10,6 +10,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {pathToFileURL} from 'node:url';
+import {loadIntegrations} from './integrations.mjs';
+import {validateConfig} from './config-schema.mjs';
 
 const DEFAULTS = {
   packages: [],
@@ -40,18 +42,30 @@ export async function loadConfig(startDir = process.cwd()) {
   const configPath = findConfigPath(startDir);
   if (!configPath) return {...DEFAULTS};
 
+  let rawConfig;
   try {
     const mod = await import(pathToFileURL(configPath).href);
-    const config = mod.default || {};
-    return {
-      ...DEFAULTS,
-      ...config,
-      packages: normalizePackages(config.packages, path.dirname(configPath)),
-      integrations: normalizeIntegrations(config.integrations),
-    };
+    rawConfig = mod.default || {};
   } catch {
     return {...DEFAULTS};
   }
+
+  const config = validateConfig(rawConfig);
+  const configDir = path.dirname(configPath);
+  const integrationSpecs = normalizeIntegrations(config.integrations);
+  const loadedIntegrations = await loadIntegrations(integrationSpecs, {
+    cwd: configDir,
+  });
+  return {
+    ...DEFAULTS,
+    ...config,
+    packages: normalizePackages(config.packages, configDir),
+    integrations: integrationSpecs,
+    loadedIntegrations,
+    gapReport:
+      config.gapReport ?? firstDefined(loadedIntegrations, 'gapReport'),
+    template: mergeTemplateConfig(config.template, loadedIntegrations),
+  };
 }
 
 /**
@@ -84,3 +98,16 @@ function normalizeIntegrations(integrations) {
   const arr = Array.isArray(integrations) ? integrations : [integrations];
   return arr.filter(value => typeof value === 'string' && value !== '');
 }
+
+function firstDefined(integrations, key) {
+  for (const integration of integrations) {
+    if (integration[key] !== undefined) return integration[key];
+  }
+  return undefined;
+}
+
+function mergeTemplateConfig(template, integrations) {
+  if (template?.get) return template;
+  const integrationTemplate = firstDefined(integrations, 'template');
+  return integrationTemplate ?? template;
+}

package/src/lib/config.test.mjs

@@ -15,10 +15,25 @@ afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});
 });
 
+function installIntegrationPackage(dir, name = '@nest/xds-meta') {
+  const packageDir = path.join(dir, 'node_modules', ...name.split('/'));
+  fs.mkdirSync(packageDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(packageDir, 'package.json'),
+    JSON.stringify({name, astryx: {integration: './astryx.integration.mjs'}}),
+  );
+  fs.writeFileSync(
+    path.join(packageDir, 'astryx.integration.mjs'),
+    `export default { name: '${name}' };
+`,
+  );
+}
+
 describe('loadConfig', () => {
   it('normalizes integrations from astryx.config.mjs', async () => {
     const dir = path.join(tmpDir, 'one');
     fs.mkdirSync(dir);
+    installIntegrationPackage(dir);
     fs.writeFileSync(
       path.join(dir, 'astryx.config.mjs'),
       `export default { integrations: '@nest/xds-meta' };\n`,
@@ -28,15 +43,49 @@ describe('loadConfig', () => {
     });
   });
 
-  it('normalizes integration arrays and filters non-strings', async () => {
+  it('rejects invalid integration package manifests', async () => {
+    const dir = path.join(tmpDir, 'bad');
+    fs.mkdirSync(dir);
+    const packageDir = path.join(dir, 'node_modules', '@bad', 'widgets');
+    fs.mkdirSync(packageDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(dir, 'astryx.config.mjs'),
+      `export default { integrations: '@bad/widgets' };\n`,
+    );
+    fs.writeFileSync(
+      path.join(packageDir, 'package.json'),
+      JSON.stringify({
+        name: '@bad/widgets',
+        astryx: {integration: './astryx.integration.mjs'},
+      }),
+    );
+    fs.writeFileSync(
+      path.join(packageDir, 'astryx.integration.mjs'),
+      `export default { docs: './docs' };\n`,
+    );
+    await expect(loadConfig(dir)).rejects.toThrow(/name/);
+  });
+
+  it('normalizes integration arrays', async () => {
     const dir = path.join(tmpDir, 'two');
     fs.mkdirSync(dir);
+    installIntegrationPackage(dir);
     fs.writeFileSync(
       path.join(dir, 'astryx.config.mjs'),
-      `export default { integrations: ['@nest/xds-meta', '', 42] };\n`,
+      `export default { integrations: ['@nest/xds-meta', ''] };\n`,
     );
     await expect(loadConfig(dir)).resolves.toMatchObject({
       integrations: ['@nest/xds-meta'],
     });
   });
+
+  it('rejects invalid config shapes', async () => {
+    const dir = path.join(tmpDir, 'invalid');
+    fs.mkdirSync(dir);
+    fs.writeFileSync(
+      path.join(dir, 'astryx.config.mjs'),
+      `export default { integrations: [42] };\n`,
+    );
+    await expect(loadConfig(dir)).rejects.toThrow(/integrations/);
+  });
 });

package/src/lib/error-codes.mjs

@@ -52,6 +52,7 @@
  *   | 'ERR_UNKNOWN_SECTION'
  *   | 'ERR_UNKNOWN_CATEGORY'
  *   | 'ERR_UNKNOWN_TEMPLATE'
+ *   | 'ERR_UNKNOWN_THEME'
  *   | 'ERR_UNKNOWN_PACKAGE'
  *   | 'ERR_UNKNOWN_AGENT'
  *   | 'ERR_UNKNOWN_FEATURE'
@@ -75,6 +76,8 @@
  *   | 'ERR_DEP_MISSING'
  *   | 'ERR_GH_CLI'
  *   | 'ERR_GAP_REPORT_FAILED'
+ *   | 'ERR_LAYOUT_PARSE'
+ *   | 'ERR_LAYOUT_INVALID'
  * )} ErrorCode
  */
 
@@ -122,6 +125,8 @@ export const ERROR_CODES = Object.freeze({
   ERR_UNKNOWN_CATEGORY: 'ERR_UNKNOWN_CATEGORY',
   /** No template matched the requested name. */
   ERR_UNKNOWN_TEMPLATE: 'ERR_UNKNOWN_TEMPLATE',
+  /** No theme matched the requested slug (theme add). */
+  ERR_UNKNOWN_THEME: 'ERR_UNKNOWN_THEME',
   /** No package matched the requested name (discover). */
   ERR_UNKNOWN_PACKAGE: 'ERR_UNKNOWN_PACKAGE',
   /** An unrecognized `--agent` value was passed to agent-docs/init. */
@@ -180,6 +185,12 @@ export const ERROR_CODES = Object.freeze({
   ERR_GH_CLI: 'ERR_GH_CLI',
   /** Filing a gap report failed at the command/integration boundary. */
   ERR_GAP_REPORT_FAILED: 'ERR_GAP_REPORT_FAILED',
+
+  // ── Layout expressions (XLE/XLO) ─────────────────────────────────
+  /** A layout expression failed to parse (syntax error, with line/col). */
+  ERR_LAYOUT_PARSE: 'ERR_LAYOUT_PARSE',
+  /** A layout expression parsed but failed validation (unknown component/prop/enum/block). */
+  ERR_LAYOUT_INVALID: 'ERR_LAYOUT_INVALID',
 });
 
 /**