@astryxdesign/cli 0.6.4-canary.ed2e54e → 0.6.4

package/clients/cli/commands/layout.text-fields.test.mjs

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `layout expand` text output names its fields after the JSON keys, so
+ * the two views stay greppable against each other.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const SLOW = 60_000;
+
+describe('layout expand text fields mirror the JSON keys', () => {
+  let cwd;
+  beforeEach(() => {
+    // Inside the workspace so @astryxdesign/core resolves.
+    cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-text-fields-'));
+  });
+  afterEach(() => fs.rmSync(cwd, {recursive: true, force: true}));
+
+  it('labels every record field with a key of the layout.expand data', async () => {
+    const expr = 'V > B + {not-a-real-block}';
+    const json = await runCli(['layout', 'expand', expr, './a', '--loose', '--json'], cwd);
+    expect(json.status).toBe(0);
+    const {data} = JSON.parse(json.stdout);
+    expect(data.todos.length).toBeGreaterThan(0);
+
+    const human = await runCli(['layout', 'expand', expr, './b', '--loose'], cwd);
+    expect(human.status).toBe(0);
+    const fields = human.stdout
+      .split('\n')
+      .map(line => /^([A-Za-z]+):\s/.exec(line)?.[1])
+      .filter(Boolean);
+    expect(fields).toEqual(['componentsUsed', 'todos']);
+    for (const field of fields) expect(Object.keys(data)).toContain(field);
+  }, SLOW);
+});

package/clients/cli/commands/text-json-parity.test.mjs

@@ -377,6 +377,23 @@ const CASES = [
     // Needs a packable project; pack itself may exit differently.
     skipFieldChecks: true,
   },
+  // ── Layout command: remove these cases when the layout command is deleted ──
+  {
+    name: 'layout check',
+    args: ['layout', 'check', 'Button'],
+    skipFieldChecks: true,
+  },
+  {
+    name: 'layout expand',
+    args: ['layout', 'expand', 'Button'],
+    skipFieldChecks: true,
+  },
+  {
+    name: 'layout grammar',
+    args: ['layout', 'grammar'],
+    skipFieldChecks: true,
+  },
+  // ── End layout cases ──
   {
     name: 'manifest',
     args: ['manifest'],

package/clients/cli/index.mjs

@@ -103,6 +103,9 @@ export const JSON_SUPPORTED = new Set([
   'doctor integration templates',
   'doctor integration components',
   'doctor integration docs',
+  'layout expand',
+  'layout check',
+  'layout grammar',
 ]);
 
 /**
@@ -261,6 +264,7 @@ const commands = [
   {name: 'gap-report', path: './commands/gap-report.mjs', register: 'registerGapReport'},
   // 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: 'upgrade', path: './commands/upgrade.mjs', register: 'registerUpgrade'},
   {name: 'theme', path: './commands/build-theme.mjs', register: 'registerTheme'},
   {name: 'integration', path: './commands/integration.mjs', register: 'registerIntegration'},

package/clients/cli/lib/exit-codes.test.mjs

@@ -34,7 +34,7 @@ manifest.commands.forEach(walk);
 
 describe('command exit codes', () => {
   it('every CommandDoc documents its exit codes', () => {
-    expect(commandDocs.length).toBeGreaterThan(25);
+    expect(commandDocs.length).toBeGreaterThan(30);
     for (const doc of commandDocs) {
       expect(doc.exitCodes?.length, doc.name).toBeGreaterThan(0);
     }
@@ -54,6 +54,13 @@ describe('command exit codes', () => {
     },
   );
 
+  it('bare `astryx layout` exits 1 in both modes, as documented', async () => {
+    const doc = commandDocs.find((d) => d.name === 'layout');
+    expect(doc.exitCodes.find((e) => e.code === 1)?.when).toMatch(/^no subcommand/);
+    expect((await runCli(['layout'])).status).toBe(1);
+    expect((await runCli(['layout', '--json'])).status).toBe(1);
+  });
+
   it('`astryx discover` with a blank query exits 1 only when packages are discovered', async () => {
     const doc = commandDocs.find((d) => d.name === 'discover');
     expect(doc.exitCodes.find((e) => e.code === 1)?.when).toMatch(/blank query when packages are discovered/);

package/clients/cli/lib/json-shim.mjs

@@ -33,12 +33,10 @@
  *      shows help because the invocation failed (`help <unknown>`, or a
  *      command group with no subcommand), which exits 1.
  *
- * Commander writes its own "error: ..." line via configureOutput.writeErr.
- * The shim drops that line in both modes. Under --json the error envelope
- * replaces it; in text mode `handleCommanderError` writes the Astryx line
- * instead (`Error: <message>`, the same message the envelope carries), so
- * a parse failure reads like every other CLI error. Other stderr output,
- * such as help printed as the failure report, still passes through.
+ * Non-JSON behavior is preserved exactly: every code path that printed
+ * to stderr before still prints to stderr. Commander writes its
+ * "error: ..." line via configureOutput.writeErr, which we pass
+ * through verbatim outside of --json mode.
  */
 
 import {API_VERSION, isJsonMode, toErrorEnvelope} from '../../../foundation/response/json.mjs';
@@ -251,20 +249,11 @@ function applyShimRecursively(cmd) {
   });
   cmd.configureOutput({
     writeOut: (str) => process.stdout.write(str),
-    // Commander's own "error: ..." line never reaches the user. Under --json a
-    // consumer parsing both streams must not see it alongside the envelope;
-    // in text mode it is Commander's format, not Astryx's, so an invalid
-    // global option (`--lang zh-Hans`) printed `error: option '--lang
-    // <locale>' argument 'zh-Hans' is invalid…` where every other CLI error
-    // prints `Error: …`. handleCommanderError writes the Astryx line below,
-    // for both modes, from the same message.
-    //
-    // ONLY that line. Commander also writes HELP through this channel when it
-    // shows help because the invocation failed (a command group with no
-    // subcommand), and that output is still wanted in text mode.
     writeErr: (str) => {
+      // Suppress Commander's "error: ..." stderr line when --json is
+      // active, so a JSON consumer parsing both streams doesn't see
+      // it alongside the envelope. Non-JSON callers are unaffected.
       if (jsonActive()) return;
-      if (/^error:\s/i.test(str)) return;
       process.stderr.write(str);
     },
   });
@@ -443,15 +432,16 @@ export function handleCommanderError(err) {
     code: commanderCodeToErrorCode(code, message),
   });
 
-  // Real error paths. Strip Commander's "error: " prefix once: in the envelope
-  // the key is already `error`, and in text mode the Astryx prefix replaces it.
-  const cleaned = message.replace(/^error:\s*/i, '');
+  // Real error paths.
   if (jsonActive()) {
+    // Strip Commander's "error: " prefix — the envelope key is `error`
+    // already, doubled "error" is noise.
+    const cleaned = message.replace(/^error:\s*/i, '');
     emitJsonError(cleaned, undefined, commanderCodeToErrorCode(code, cleaned));
   } else {
-    // Commander's own line was suppressed above, so a parse failure reads the
-    // same as every other CLI error — the `Error: …` line cliError prints.
-    process.stderr.write(`Error: ${cleaned}\n`);
+    // Non-JSON mode: Commander already wrote the "error: ..." line
+    // to stderr via configureOutput.writeErr before throwing the
+    // CommanderError. Nothing to do — exit with the original code.
   }
   process.exit(exitCode || 1);
 }

package/clients/cli/lib/json-shim.test.mjs

@@ -225,6 +225,23 @@ describe('--json shim: help shown for a failed invocation is an error envelope',
     expect(parsed.error).toMatch(/bogus/);
   });
 
+  it('astryx layout --json (group, no subcommand) emits ERR_MISSING_ARGUMENT, exit 1', async () => {
+    const {status, stdout, stderr} = await runCli(['layout', '--json']);
+    expect(status).toBe(1);
+    expect(stderr).toBe('');
+    const parsed = parseJson(stdout);
+    expect(parsed).not.toHaveProperty('type');
+    expect(parsed.code).toBe('ERR_MISSING_ARGUMENT');
+    expect(parsed.suggestions.map((s) => s.name)).toContain('layout expand');
+  });
+
+  it('astryx layout (no --json) still prints help to stderr, exit 1', async () => {
+    const {status, stdout, stderr} = await runCli(['layout']);
+    expect(status).toBe(1);
+    expect(stdout).toBe('');
+    expect(stderr).toMatch(/Usage: astryx layout/);
+  });
+
   it('the real binary emits the same envelope for help bogus --json', () => {
     // One program per process, so the root's own outputHelp patch is used here.
     const bin = fileURLToPath(new URL('../bin/astryx.mjs', import.meta.url));
@@ -240,9 +257,6 @@ describe('--json shim: help shown for a failed invocation is an error envelope',
   });
 
   it('a group added after install gets the same error envelope', () => {
-    // This is the only coverage of the no-subcommand path: every group the CLI
-    // ships has an action of its own (see command-result-coverage.test.mjs), so
-    // a group without one has to be built here.
     const program = new Command('astryx');
     installJsonShim(program);
     // Added later, so only the prototype-level patch covers its outputHelp.
@@ -268,11 +282,11 @@ describe('--json shim: help shown for a failed invocation is an error envelope',
     expect(parsed.suggestions).toEqual([{name: 'late child', reason: 'available subcommand'}]);
   });
 
-  it('astryx help theme --json still emits the help envelope, exit 0', async () => {
-    const {status, stdout} = await runCli(['help', 'theme', '--json']);
+  it('astryx help layout --json still emits the help envelope, exit 0', async () => {
+    const {status, stdout} = await runCli(['help', 'layout', '--json']);
     expect(status).toBe(0);
     const parsed = parseJson(stdout);
     expect(parsed.type).toBe('help');
-    expect(parsed.data.command).toBe('astryx theme');
+    expect(parsed.data.command).toBe('astryx layout');
   });
 });

package/clients/cli/lib/manifest.mjs

@@ -51,7 +51,6 @@ export const RESPONSE_TYPES = {
   init: ['init.run', 'init.remove'],
   component: [
     'component.list',
-    'component.batch',
     'component.detail',
     'component.detail.props',
     'component.detail.source',
@@ -70,7 +69,6 @@ export const RESPONSE_TYPES = {
     'discover.list',
     'discover.detail',
     'discover.detail.doc',
-    'discover.item',
     'discover.search',
   ],
   search: ['search'],
@@ -100,6 +98,9 @@ export const RESPONSE_TYPES = {
   'doctor integration templates': ['integration.template-conflicts'],
   'doctor integration components': ['integration.component-conflicts'],
   'doctor integration docs': ['integration.doc-conflicts'],
+  'layout expand': ['layout.expand'],
+  'layout check': ['layout.check'],
+  'layout grammar': ['layout.grammar'],
 };
 
 /**
@@ -110,7 +111,6 @@ const EXAMPLES = {
   component: [
     'astryx component',
     'astryx component XDSButton',
-    'astryx component Button Badge Text',
     'astryx component XDSButton --props --json',
   ],
   docs: [
@@ -180,6 +180,11 @@ const EXAMPLES = {
     'astryx doctor integration docs @acme/widgets --json',
   ],
   init: ['astryx init', 'astryx init --all --json'],
+  '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`],
+  'layout grammar': ['astryx layout grammar'],
 };
 
 /**

package/clients/cli/lib/manifest.test.mjs

@@ -156,10 +156,7 @@ describe('manifest: shape', () => {
 
   it('derives arguments from Commander metadata', () => {
     const component = allEntries.find((c) => c.name === 'component');
-    const names = component.arguments.find((a) => a.name === 'names');
-    expect(names.required).toBe(false);
-    expect(names.variadic).toBe(true);
-    expect(names.description).toContain('Two or more return one ordered batch');
+    expect(component.arguments.map((a) => a.name)).toContain('name');
     const themeBuild = allEntries.find((c) => c.name === 'theme build');
     expect(themeBuild.arguments.map((a) => a.name)).toContain('files');
     const files = themeBuild.arguments.find((a) => a.name === 'files');
@@ -196,7 +193,7 @@ describe('manifest: e2e', () => {
     // Enriched: the full structured manifest is embedded.
     expect(parsed.data.manifest).toBeDefined();
     expect(parsed.data.manifest.commands.find((c) => c.name === 'component').responseTypes)
-      .toEqual(expect.arrayContaining(['component.list', 'component.batch']));
+      .toContain('component.list');
   });
 });
 

package/foundation/discovery/authoring-self-docs.mjs

@@ -33,7 +33,6 @@ export const AUTHORING_SELF_DOCS = [
   'config/config.doc.mjs',
   'debug/debug.doc.mjs',
   'gap-report/gap-report.doc.mjs',
-  'discover/discover.doc.mjs',
   'codemod/codemod.doc.mjs',
   'identity/identity.doc.mjs',
   'doctypes/base/graph-fields.doc.mjs',

package/foundation/discovery/template-adapter.mjs

@@ -4,7 +4,7 @@
  * @file Shared template discovery + IO.
  *
  * Owns everything the template leaves (list/show/skeleton/copy) AND other
- * commands (component, search, init, discover, Doctor integration)
+ * commands (component, layout, search, init, discover, Doctor integration)
  * share: template discovery across core/external/integration sources, the
  * template-spec loaders, and the cross-command helpers (stripTemplateAssetRefs,
  * findShowcase, findRelatedBlocks, extractComponents, listTemplates). The

package/foundation/doc-compiler/doc-loads.test.mjs

@@ -191,6 +191,18 @@ const RUNNERS = {
       'import ./integration.doc.mjs',
     ],
   },
+  'clients/cli/commands/layout.mjs': {
+    runs: SELF_DOCS,
+    sites: [
+      'import ../../../api/layout/layoutCheck.doc.mjs',
+      'import ../../../api/layout/layoutExpand.doc.mjs',
+      'import ../../../api/layout/layoutGrammar.doc.mjs',
+      'import ./layout-check.doc.mjs',
+      'import ./layout-expand.doc.mjs',
+      'import ./layout-grammar.doc.mjs',
+      'import ./layout.doc.mjs',
+    ],
+  },
   'clients/cli/commands/search.mjs': {
     runs: SELF_DOCS,
     sites: [

package/foundation/doc-compiler/tree.test.mjs

@@ -497,14 +497,7 @@ describe("the CLI's own docs tree", () => {
       expect(
         tree.get('cli')?.slots.map(slot => [slot.name, slot.children]),
       ).toEqual([
-        [
-          'guides',
-          [
-            'cli/component-lookups',
-            'cli/integrations',
-            'cli/writing-docs',
-          ],
-        ],
+        ['guides', ['cli/integrations', 'cli/writing-docs']],
         ['reference', ['cli/commands', 'cli/api']],
       ]);
       expect(tree.get('cli/api')?.slots[0].children).toEqual([
@@ -573,7 +566,6 @@ describe("the CLI's own docs tree", () => {
         'commands',
       ]);
       expect(inputs.docs.map(d => [d.name, d.placement?.parent])).toEqual([
-        ['component-lookups', 'namespace:cli'],
         ['integrations', 'namespace:cli'],
         ['writing-docs', 'namespace:cli'],
       ]);

package/foundation/integrations/integrations.d.mts

@@ -45,7 +45,7 @@ export function findManifestPaths(dir: string): string[];
  * @param {string} file absolute manifest path
  * @param {string} [label] used in error messages
  * @param {{fresh?: boolean}} [options]
- * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string}>}
+ * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, agentDocsError?: string}>}
  */
 export function loadManifest(file: string, label?: string, { fresh }?: {
     fresh?: boolean;
@@ -55,8 +55,6 @@ export function loadManifest(file: string, label?: string, { fresh }?: {
     debug?: import("../../authoring/debug/type").DebugEventHandler;
     gapReport?: import("../../authoring/gap-report/type").GapReportHandler;
     gapReportError?: string;
-    discover?: import("../../authoring/discover/type").DiscoverSource;
-    discoverError?: string;
     agentDocsError?: string;
 }>;
 /**
@@ -156,9 +154,6 @@ export function loadIntegrations(specs?: string[], { cwd, fresh, resolveProvider
  *   validated package-owned handler from the `gapReport` NAMED export.
  * @property {string} [__gapReportError] isolated named-handler validation error.
  *   Named exports are not manifest keys — see {@link loadManifest}.
- * @property {import('../../authoring/discover/type').DiscoverSource} [__discover]
- *   validated catalog source from the `discover` NAMED export.
- * @property {string} [__discoverError] isolated discover-source validation error.
  */
 /** Conventional manifest basenames, in load-precedence order. */
 export const MANIFEST_BASENAMES: string[];
@@ -250,12 +245,4 @@ export type LoadedIntegration = {
      * Named exports are not manifest keys — see {@link loadManifest}.
      */
     __gapReportError?: string | undefined;
-    /**
-     * validated catalog source from the `discover` NAMED export.
-     */
-    __discover?: import("../../authoring/discover/type").DiscoverSource | undefined;
-    /**
-     * isolated discover-source validation error.
-     */
-    __discoverError?: string | undefined;
 };

package/foundation/integrations/integrations.mjs

@@ -29,7 +29,6 @@ import {
 } from '../../authoring/integration/schema.mjs';
 import {importUserModule, findPresentFiles} from '../fs/module-loader.mjs';
 import {parseGapReportHandler} from '../../authoring/gap-report/parse.mjs';
-import {parseDiscoverSource} from '../../authoring/discover/parse.mjs';
 import {resolveProviders} from './provider-resolution.mjs';
 
 /**
@@ -81,9 +80,6 @@ import {resolveProviders} from './provider-resolution.mjs';
  *   validated package-owned handler from the `gapReport` NAMED export.
  * @property {string} [__gapReportError] isolated named-handler validation error.
  *   Named exports are not manifest keys — see {@link loadManifest}.
- * @property {import('../../authoring/discover/type').DiscoverSource} [__discover]
- *   validated catalog source from the `discover` NAMED export.
- * @property {string} [__discoverError] isolated discover-source validation error.
  */
 
 /** Conventional manifest basenames, in load-precedence order. */
@@ -171,23 +167,6 @@ function parseGapReportHandlerExport(value, label) {
   }
 }
 
-/**
- * Parse the optional named discover source the same way: a malformed one is
- * isolated from every other contribution and reported by `astryx discover`.
- *
- * @param {unknown} value
- * @param {string} label
- * @returns {{source?: import('../../authoring/discover/type').DiscoverSource, error?: string}}
- */
-function parseDiscoverSourceExport(value, label) {
-  if (value === undefined) return {};
-  try {
-    return {source: parseDiscoverSource(value, `${label} named export "discover"`)};
-  } catch (error) {
-    return {error: error instanceof Error ? error.message : String(error)};
-  }
-}
-
 /**
  * Load and validate a manifest module's default export, while isolating the
  * optional `agentDocs` contribution from the manifest's other fields.
@@ -204,7 +183,7 @@ function parseDiscoverSourceExport(value, label) {
  * @param {string} file absolute manifest path
  * @param {string} [label] used in error messages
  * @param {{fresh?: boolean}} [options]
- * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string}>}
+ * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, agentDocsError?: string}>}
  */
 export async function loadManifest(
   file,
@@ -215,7 +194,6 @@ export async function loadManifest(
   const raw = mod?.default;
   const baseManifest = parseIntegrationBase(raw, label);
   const gapReport = parseGapReportHandlerExport(mod?.gapReport, label);
-  const discover = parseDiscoverSourceExport(mod?.discover, label);
   const hasAgentDocs =
     raw != null &&
     typeof raw === 'object' &&
@@ -250,8 +228,6 @@ export async function loadManifest(
         : undefined,
     gapReport: gapReport.handler,
     gapReportError: gapReport.error,
-    discover: discover.source,
-    discoverError: discover.error,
     agentDocsError,
   };
 }
@@ -369,10 +345,6 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
   let gapReportHandler;
   /** @type {string | undefined} */
   let gapReportError;
-  /** @type {import('../../authoring/discover/type').DiscoverSource | undefined} */
-  let discoverSource;
-  /** @type {string | undefined} */
-  let discoverError;
   /** @type {string | undefined} */
   let agentDocsError;
   try {
@@ -382,8 +354,6 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
       debug: debugHandler,
       gapReport: gapReportHandler,
       gapReportError,
-      discover: discoverSource,
-      discoverError,
       agentDocsError,
     } = await loadManifest(manifestFile, `Integration ${spec}`, {fresh}));
   } catch (err) {
@@ -427,8 +397,6 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
     __debug: debugHandler,
     __gapReport: gapReportHandler,
     __gapReportError: gapReportError,
-    __discover: discoverSource,
-    __discoverError: discoverError,
     __spec: spec,
     __packageDir: packageDir,
     __packageExports: pkg.exports ?? null,
@@ -480,10 +448,6 @@ export async function loadIntegrations(
     let gapReportHandler;
     /** @type {string | undefined} */
     let gapReportError;
-    /** @type {import('../../authoring/discover/type').DiscoverSource | undefined} */
-    let discoverSource;
-    /** @type {string | undefined} */
-    let discoverError;
     /** @type {string | undefined} */
     let agentDocsError;
     try {
@@ -493,8 +457,6 @@ export async function loadIntegrations(
         debug: debugHandler,
         gapReport: gapReportHandler,
         gapReportError,
-        discover: discoverSource,
-        discoverError,
         agentDocsError,
       } = await loadManifest(manifestFile, `Integration ${spec}`, {fresh}));
     } catch (err) {
@@ -545,8 +507,6 @@ export async function loadIntegrations(
       __debug: debugHandler,
       __gapReport: gapReportHandler,
       __gapReportError: gapReportError,
-      __discover: discoverSource,
-      __discoverError: discoverError,
       __spec: spec,
       __packageDir: packageDir,
       __packageExports: pkg.exports ?? null,

package/foundation/integrations/integrations.test.mjs

@@ -785,34 +785,3 @@ describe('the `gapReport` named export', () => {
     expect(loaded.__unknownKeys).toEqual(['gapReport']);
   });
 });
-
-describe('the `discover` named export', () => {
-  it('is carried out of the manifest module as __discover', async () => {
-    writeManifestPackage(tmpDir, {
-      body:
-        `export async function discover() { return {schemaVersion: 1}; }\n` +
-        `export default {issuesUrl: 'https://example.com/i'};\n`,
-    });
-
-    const [loaded] = await loadIntegrations(['@acme/widgets'], {cwd: tmpDir});
-
-    expect(typeof loaded.__discover).toBe('function');
-    expect(loaded.__discoverError).toBeUndefined();
-    expect(loaded.__unknownKeys).toEqual([]);
-    expect(loaded.issuesUrl).toBe('https://example.com/i');
-  });
-
-  it('keeps the manifest and records why when the export is not a function', async () => {
-    writeManifestPackage(tmpDir, {
-      body:
-        `export const discover = {url: 'https://example.com/catalog.json'};\n` +
-        `export default {issuesUrl: 'https://example.com/i'};\n`,
-    });
-
-    const [loaded] = await loadIntegrations(['@acme/widgets'], {cwd: tmpDir});
-
-    expect(loaded.__discover).toBeUndefined();
-    expect(loaded.__discoverError).toContain('must be a function');
-    expect(loaded.issuesUrl).toBe('https://example.com/i');
-  });
-});

package/foundation/response/response-types.doc.mjs

@@ -37,11 +37,6 @@ export const doc = {
       description:
         'The component catalog grouped by category: `detail` (the level: names | compact | full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.',
     },
-    {
-      value: 'component.batch',
-      description:
-        'The component specialization of the shared `BatchResponse` and `BatchRow` types. An explicit programmatic selector array, or two or more CLI selectors, returns one ordered receipt: `count` plus `results`, one row per selector including duplicates. Every row carries `selector` and `status` (found | not_found | ambiguous | error). A found row carries `result`, the same {type, data} response as one selector. An ambiguous row carries `code`, `error`, and `candidates` ({package, component, kind, installed}). Other failed rows carry `code`, `error`, and optional `suggestions` ({name, reason}).',
-    },
     {
       value: 'component.detail',
       description:
@@ -109,27 +104,21 @@ export const doc = {
     {
       value: 'discover.list',
       description:
-        'The integrations the project loads (name, category, components, version, a list per other kind they add, and latest when a source knows it); with a discover source, meta.available lists what the project could add and meta.sources reports each source; when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".',
+        'The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".',
     },
     {
       value: 'discover.detail',
-      description:
-        'One package, for an @scope/name or @scope/name@version query: what the shown version adds, whether the project has it, and, when a source knows the package, its versions, latest release, and the command that adds it.',
+      description: 'A single external package entry, for an @scope/name query.',
     },
     {
       value: 'discover.detail.doc',
       description:
-        'The validated ComponentDoc for one installed component, for an @scope/name/Component query.',
-    },
-    {
-      value: 'discover.item',
-      description:
-        'One item that is not an installed component, for an @scope/name/<item> query: its kind, name, package, version, and whether the project has the package.',
+        'The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.',
     },
     {
       value: 'discover.search',
       description:
-        'The echoed query plus every matching item and package across all packages, each with its kind and whether the project has it, even when only one matches; total is set when --limit cut the list.',
+        'The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.',
     },
 
     // search
@@ -318,5 +307,22 @@ export const doc = {
       description:
         'The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` | `error`) and `relationship` (`replaces` | `extends` | `accidental`).',
     },
+
+    // layout (XLE/XLO)
+    {
+      value: 'layout.expand',
+      description:
+        'The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written).',
+    },
+    {
+      value: 'layout.check',
+      description:
+        'The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).',
+    },
+    {
+      value: 'layout.grammar',
+      description:
+        "The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.",
+    },
   ],
 };

package/foundation/response/response-types.doc.test.mjs

@@ -53,29 +53,6 @@ function expectNamed(type, fields) {
 }
 
 describe('response-types EnumDoc names every field', () => {
-  it('component.batch names every row field and state', async () => {
-    const res = await data(['component', 'Button', 'Badge']);
-    expect(res.type).toBe('component.batch');
-    expect(describedAs('component.batch')).toMatch(/BatchResponse.*BatchRow/);
-    expectNamed('component.batch', [
-      'count',
-      'results',
-      'selector',
-      'status',
-      'result',
-      'code',
-      'error',
-      'candidates',
-      'package',
-      'component',
-      'kind',
-      'installed',
-      'suggestions',
-      'name',
-      'reason',
-    ]);
-  });
-
   it('component.detail: the ownership fields and parentDoc', async () => {
     const res = await data(['component', 'HStack']);
     expect(res.type).toBe('component.detail');