@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/api/integration/integrationPackCheck.doc.mjs

@@ -7,13 +7,13 @@ export const doc = {
   name: 'integrationPackCheck',
   namespace: 'cli/api',
   displayName: 'integrationPackCheck()',
-  summary: 'Check an integration package the way npm will publish it.',
+  summary: 'Prove an integration package survives npm packing.',
   description:
     "Validates the local integration, runs the package lifecycle, packs with npm, checks required files against npm's authoritative tarball list, extracts the real tarball into a scratch consumer, compares local and packed contribution inventories, and resolves every packed component through its documented public import to verify that module exports the component. A package that ships a namespace doc or a placed guide, or has a template that sets `replaces`, fails unless its `@astryxdesign/cli` peer range admits only CLIs that read them.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'integrationPackCheck(options?: IntegrationPackCheckOptions): Promise<IntegrationPackCheckResponse>',
-  keywords: ['verify', 'pack', 'publish', 'tarball', 'consumer'],
+  keywords: ['integration', 'pack', 'check', 'publish', 'tarball', 'consumer'],
   params: [
     {
       name: 'options.cwd',
@@ -31,6 +31,6 @@ export const doc = {
   examples: [
     {label: 'Check the local package', code: 'await integrationPackCheck();'},
   ],
-  command: 'integration verify',
+  command: 'integration pack',
   related: ['integrationAdd', 'validateIntegration'],
 };

package/api/integration/pack-check.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx integration verify` — verify an integration package is
+ * @file `astryx integration pack --check` — verify an integration package is
  * ready to publish by cross-referencing its declared contributions against the
  * real npm tarball.
  *
@@ -30,13 +30,8 @@ import {resolvePackageDir} from '../../foundation/integrations/integrations.mjs'
 import {
   docsTreeCliProblem,
   replacesCliProblem,
-  sectionIdsCliProblem,
-  themesCliProblem,
 } from '../../foundation/integrations/cli-requirement.mjs';
-import {
-  discoverIntegrationDocs,
-  loadTopicModule,
-} from '../../foundation/discovery/docs-discovery.mjs';
+import {discoverIntegrationDocs} from '../../foundation/discovery/docs-discovery.mjs';
 import {
   discoverIntegrationComponents,
   resolveIntegrationImportPath,
@@ -167,22 +162,6 @@ export function parseNpmPackOutput(output) {
   };
 }
 
-/**
- * Summarize the JSON error npm prints on stdout when `--json` pack fails.
- * @param {string} output
- * @returns {string}
- */
-function npmPackErrorDetail(output) {
-  try {
-    const error = JSON.parse(output)?.error;
-    return [error?.summary, error?.detail]
-      .filter(part => typeof part === 'string' && part.trim() !== '')
-      .join(': ');
-  } catch {
-    return (output || '').trim();
-  }
-}
-
 /**
  * Run `npm pack --json` with output directed to `destDir` so no preexisting
  * tgz is overwritten. This intentionally runs the package lifecycle, matching
@@ -196,25 +175,16 @@ function npmPackErrorDetail(output) {
 function runNpmPack(packageDir, destDir) {
   const result = spawnSync(
     'npm',
-    [
-      'pack',
-      '--json',
-      '--silent',
-      // Lifecycle scripts still run; background mode keeps their output off
-      // the stdout that carries the JSON result.
-      '--foreground-scripts=false',
-      `--pack-destination=${destDir}`,
-    ],
+    ['pack', '--json', '--silent', `--pack-destination=${destDir}`],
     {cwd: packageDir, encoding: 'utf-8', timeout: 60_000},
   );
   if (result.error) {
     throw new Error(`Could not start npm pack: ${result.error.message}`);
   }
   if (result.status !== 0) {
-    const detail =
-      (result.stderr || '').trim() || npmPackErrorDetail(result.stdout);
+    const stderr = (result.stderr || '').trim();
     throw new Error(
-      `npm pack failed (exit ${result.status})${detail ? `: ${detail}` : ''}.`,
+      `npm pack failed (exit ${result.status})${stderr ? `: ${stderr}` : ''}.`,
     );
   }
   return parseNpmPackOutput(result.stdout);
@@ -338,23 +308,6 @@ function moduleExportsName(file, exportName, seen = new Set()) {
   return found;
 }
 
-/**
- * Whether any of these doc files has a section that sets `id`.
- * @param {string[]} files
- * @returns {Promise<boolean>}
- */
-async function setsSectionIds(files) {
-  for (const file of files) {
-    if (typeof file !== 'string') continue;
-    const doc = /** @type {any} */ (await loadTopicModule(file).catch(() => null));
-    const sections = Array.isArray(doc?.sections) ? doc.sections : [];
-    if (sections.some((/** @type {any} */ section) => section?.id != null)) {
-      return true;
-    }
-  }
-  return false;
-}
-
 /**
  * Resolve package specifiers through Node's real ESM resolver from the scratch
  * consumer. Resolution does not execute the target module, so source `.tsx`
@@ -647,31 +600,19 @@ export async function integrationPackCheck(options = {}) {
   // (spec:AST-046 FR11): an older CLI can hide every doc topic the package
   // ships, so the declared CLI range must admit only CLIs that read it.
   if (loaded.docs) {
-    const {records, namespaces, guides} = await discoverIntegrationDocs(
-      loaded,
-    ).catch(() => ({records: [], namespaces: [], guides: []}));
+    const {namespaces, guides} = await discoverIntegrationDocs(loaded).catch(
+      () => ({namespaces: [], guides: []}),
+    );
     const problem =
       namespaces.length > 0 || guides.length > 0
         ? docsTreeCliProblem(pkg)
         : null;
     if (problem != null) {
       issues.push(error('docs_tree_needs_cli', problem));
-    } else if (
-      await setsSectionIds([
-        ...records.map(record => record.path),
-        ...guides.map(guide => /** @type {any} */ (guide.ref).topicFile),
-      ])
-    ) {
-      // A section `id` is also a field an older CLI rejects, hiding the
-      // package's doc topics; the same peer range fixes both.
-      const idProblem = sectionIdsCliProblem(pkg);
-      if (idProblem != null) {
-        issues.push(error('section_ids_need_cli', idProblem));
-      }
     }
   }
   // A template that sets `replaces` needs a CLI that reads the field
-  // (spec:AST-035): an older CLI drops that template and hides the package's docs.
+  // (spec:AST-035): an older CLI withholds the package's templates and docs.
   if (loaded.templates) {
     const found = await discoverIntegrationTemplatesForOne(loaded).catch(
       () => ({templates: [], errors: []}),
@@ -684,12 +625,6 @@ export async function integrationPackCheck(options = {}) {
     const problem = setsReplaces ? replacesCliProblem(pkg) : null;
     if (problem != null) issues.push(error('replaces_needs_cli', problem));
   }
-  // A theme needs a CLI that reads typed theme descriptors: an older CLI
-  // rejects the themes root and withholds the package's themes and docs.
-  if (localIdentities.themes.length > 0) {
-    const problem = themesCliProblem(pkg);
-    if (problem != null) issues.push(error('themes_need_cli', problem));
-  }
 
   // Temp resources — always cleaned up
   const tgzTmpDir = fs.mkdtempSync(
@@ -722,14 +657,6 @@ export async function integrationPackCheck(options = {}) {
     // package's already-installed dependencies. The unique suffix makes
     // concurrent checks independent.
     scratchBase = fs.mkdtempSync(path.join(packageDir, '.astryx-pack-check-'));
-    // The consumer's own package.json makes it the package scope for its
-    // imports. Without one, Node resolves the package's name through the
-    // SOURCE package.json (self-reference), so an export target left out of
-    // the tarball would still resolve.
-    fs.writeFileSync(
-      path.join(scratchBase, 'package.json'),
-      `${JSON.stringify({name: 'astryx-verify-consumer', private: true})}\n`,
-    );
 
     // Cross-reference file inventory vs pack list
     if (!packResult.packedPaths.has(fileInv.manifest)) {

package/api/integration/pack-check.test.mjs

@@ -36,8 +36,6 @@ function writePackage({
   scripts,
 } = {}) {
   const pkg = {name, version};
-  // A theme needs a CLI that reads typed theme descriptors.
-  if (themes) pkg.peerDependencies = {'@astryxdesign/cli': '>=0.7.0'};
   if (files !== undefined) pkg.files = files;
   if (scripts !== undefined) pkg.scripts = scripts;
   fs.writeFileSync(
@@ -96,30 +94,6 @@ describe('integrationPackCheck', () => {
     );
   });
 
-  it('fails a package that ships a theme on a CLI range that cannot read it', async () => {
-    writePackage({files: ['astryx.integration.mjs', 'themes']});
-    const pkgFile = path.join(tmpDir, 'package.json');
-    const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
-    delete pkg.peerDependencies;
-    fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
-
-    const missing = await integrationPackCheck({cwd: tmpDir});
-    expect(missing.data.packable).toBe(false);
-    expect(missing.data.issues).toContainEqual(
-      expect.objectContaining({
-        code: 'themes_need_cli',
-        message: expect.stringContaining('ships a theme'),
-      }),
-    );
-
-    pkg.peerDependencies = {'@astryxdesign/cli': '^0.6.3'};
-    fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
-    const old = await integrationPackCheck({cwd: tmpDir});
-    expect(old.data.issues).toContainEqual(
-      expect.objectContaining({code: 'themes_need_cli'}),
-    );
-  });
-
   it('fails when a theme entry omits its inferred runtime export', async () => {
     writePackage({files: ['astryx.integration.mjs', 'themes']});
     fs.writeFileSync(
@@ -219,39 +193,6 @@ describe('integrationPackCheck', () => {
     );
   });
 
-  it('resolves public imports in the packed package, not the source', async () => {
-    // The root export's target is left out of `files`: the source package
-    // resolves it, but an app that installs the tarball cannot.
-    fs.writeFileSync(
-      path.join(tmpDir, 'package.json'),
-      `${JSON.stringify({
-        name: '@acme/widgets',
-        version: '1.0.0',
-        files: ['astryx.integration.mjs'],
-        exports: {'.': './index.mjs'},
-      })}\n`,
-    );
-    fs.writeFileSync(
-      path.join(tmpDir, 'index.mjs'),
-      "export {AcmeWidget} from './components/AcmeWidget.tsx';\n",
-    );
-    await integrationAddComponent('AcmeWidget', {cwd: tmpDir});
-    const docFile = path.join(tmpDir, 'components', 'AcmeWidget.doc.mjs');
-    const doc = fs.readFileSync(docFile, 'utf-8');
-    expect(doc).toContain('@acme/widgets/components/AcmeWidget');
-    fs.writeFileSync(
-      docFile,
-      doc.replace('@acme/widgets/components/AcmeWidget', '@acme/widgets'),
-    );
-
-    const result = await integrationPackCheck({cwd: tmpDir});
-
-    expect(result.data.packable).toBe(false);
-    expect(result.data.issues).toContainEqual(
-      expect.objectContaining({code: 'component_export_missing'}),
-    );
-  });
-
   it('fails when packed template source is hidden by package exports', async () => {
     writePackage({
       manifest: "export default {templates: './templates'};\n",
@@ -395,37 +336,6 @@ describe('integrationPackCheck', () => {
     expect(await codes()).not.toContain('docs_tree_needs_cli');
   }, 120_000);
 
-  it('fails a package whose doc section sets id on a CLI range that rejects the field', async () => {
-    writePackage({manifest: "export default {docs: './docs'};\n", themes: false});
-    fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
-    const topic = (/** @type {string} */ section) =>
-      `export default {type: 'generic', name: 'notes', title: 'Notes', description: 'Notes.', sections: [${section}]};\n`;
-    const file = path.join(tmpDir, 'docs', 'notes.doc.mjs');
-    const codes = async () =>
-      (await integrationPackCheck({cwd: tmpDir})).data.issues.map(
-        (/** @type {{code: string}} */ issue) => issue.code,
-      );
-    fs.writeFileSync(
-      file,
-      topic("{title: 'Take notes', content: [{type: 'prose', text: 'Notes.'}]}"),
-    );
-    expect(await codes()).not.toContain('section_ids_need_cli');
-    // A fresh file name: the module loader caches a path once it is imported.
-    fs.rmSync(file);
-    fs.writeFileSync(
-      path.join(tmpDir, 'docs', 'notes-with-ids.doc.mjs'),
-      topic(
-        "{id: 'take-notes', title: 'Take notes', content: [{type: 'prose', text: 'Notes.'}]}",
-      ),
-    );
-    expect(await codes()).toContain('section_ids_need_cli');
-    const pkgFile = path.join(tmpDir, 'package.json');
-    const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
-    pkg.peerDependencies = {'@astryxdesign/cli': '>=0.7.0'};
-    fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
-    expect(await codes()).not.toContain('section_ids_need_cli');
-  }, 120_000);
-
   it('fails a package with a template that sets replaces on a CLI range that rejects the field', async () => {
     writePackage({manifest: "export default {templates: './templates'};\n", themes: false});
     fs.mkdirSync(path.join(tmpDir, 'templates'), {recursive: true});

package/api/integration/pack-check.type.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Colocated types for `astryx integration verify`.
+ * @file Colocated types for `astryx integration pack --check`.
  */
 
 /**

package/api/json/assertResponse.doc.mjs

@@ -49,7 +49,7 @@ export const doc = {
   throws: [
     {
       code: 'Error',
-      when: 'a plain Error with no code: the CLI returned an error envelope (its message is rethrown; code and suggestions are dropped), or the response `type` is not expectedType',
+      when: 'the CLI returned an error envelope (the CLI message is rethrown), or the response `type` is not expectedType',
     },
   ],
   examples: [

package/api/json/index.ts

@@ -26,6 +26,7 @@ export type * from '../gap-report/gap-report.type.mjs';
 export type * from '../upgrade/upgrade.type.mjs';
 export type * from '../init/init.type.mjs';
 export type * from '../doctor/doctor.type.mjs';
+export type * from '../layout/layout.type.mjs';
 export type * from '../integration/validate-integration.type.mjs';
 export type * from '../integration/authoring-checks.type.mjs';
 export type * from '../integration/pack-check.type.mjs';

package/api/json/isError.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   displayName: 'isError()',
   summary: 'Did the CLI return an error envelope?',
   description:
-    'Tests a parsed response for an `error` key. Branch on this before touching `data`, ' +
+    'Tests a parsed response for an `error` key. Branch on this before touching `data`: ' +
     'and prefer the stable `code` field over matching the human-readable message, which is ' +
     'not a contract. Note this returns a plain boolean, not a TypeScript type predicate, so ' +
     'it does not narrow on its own: cast to the matching *Response type to get typed access.',

package/api/layout/_adapter.d.mts

@@ -0,0 +1,34 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/** @param {import('../../foundation/xle/xle-ast').RawIssue} issue */
+export function formatIssue(issue: import("../../foundation/xle/xle-ast").RawIssue): string;
+/**
+ * Parse + validate, throwing structured XDSErrors on failure.
+ * Returns {doc, registry, blocks, warnings}.
+ *
+ * @param {string} expression
+ * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]
+ */
+export function analyze(expression: string, { form, loose, cwd }?: {
+    form?: "compact" | "outline" | "auto";
+    loose?: boolean;
+    cwd?: string;
+}): Promise<{
+    doc: import("../../foundation/xle/xle-ast").XLEDoc;
+    registry: import("../../foundation/xle/xle-ast").Registry;
+    blocks: LayoutBlock[];
+    errors: import("../../foundation/xle/xle-ast").RawIssue[];
+    warnings: import("../../foundation/xle/xle-ast").RawIssue[];
+}>;
+export type LayoutBlock = {
+    dirName: string;
+    name: string;
+    kind: "template" | "component";
+    type?: string | undefined;
+    description?: string | undefined;
+    category?: string | undefined;
+    importPath?: string | undefined;
+    filePath?: string | undefined;
+    isDefault?: boolean | undefined;
+};

package/api/layout/_adapter.mjs

@@ -0,0 +1,148 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Shared analysis layer for the `layout` command's expand/check leaves.
+ *
+ * Loads the block catalog (template blocks + app-registered components), builds
+ * the branch registry, and parses+validates a layout expression into a doc +
+ * issues. Both the expand and check leaves sit on `analyze`; neither parses or
+ * validates directly. (The grammar leaf needs none of this — it only reads the
+ * registry alias table.)
+ *
+ * @input  expression string (+ options)
+ * @output analyze() -> {doc, registry, blocks, errors, warnings}; formatIssue()
+ * @position api — shared core over lib/xle; leaves in expand/ + check/ project it
+ */
+
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
+import {parse, XLEParseError} from '../../foundation/xle/parse.mjs';
+import {validate} from '../../foundation/xle/validate.mjs';
+import {buildRegistry} from '../../foundation/xle/registry.mjs';
+import {discoverTemplates} from '../template/template.mjs';
+import {Project} from '../../foundation/config/project.mjs';
+
+/**
+ * @typedef {object} LayoutBlock
+ * @property {string} dirName
+ * @property {string} name
+ * @property {'template'|'component'} kind
+ * @property {string} [type]
+ * @property {string} [description]
+ * @property {string} [category]
+ * @property {string} [importPath]
+ * @property {string} [filePath]
+ * @property {boolean} [isDefault]
+ */
+
+/**
+ * The catalog a `{hint}` can resolve to: template blocks (spliced inline) plus
+ * 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.
+ *
+ * @param {string} cwd
+ * @returns {Promise<LayoutBlock[]>}
+ */
+async function loadBlocks(cwd) {
+  /** @type {LayoutBlock[]} */
+  const blocks = [];
+  try {
+    const all = await discoverTemplates(cwd);
+    const templates = all.filter(template => template.type === 'block');
+    /** @type {Map<string, import('../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate>} */
+    const byId = new Map();
+    // Exact ids are the fallback. Active replacement aliases override them in a
+    // second pass, matching template() regardless of discovery/display order.
+    for (const template of templates) byId.set(template.dirName, template);
+    for (const template of templates) {
+      if (template.replaces != null) byId.set(template.replaces, template);
+    }
+    for (const [id, template] of byId) {
+      blocks.push({...template, dirName: id, kind: 'template'});
+    }
+  } catch {
+    // discovery is best-effort
+  }
+  try {
+    const project = await Project.load(cwd);
+    /** @type {Record<string, {from?: string, description?: string, default?: boolean}>} */
+    const components = project.config.experimental?.xle?.components ?? {};
+    for (const [name, spec] of Object.entries(components)) {
+      const importPath = spec.from;
+      if (!importPath) continue;
+      blocks.push({
+        type: 'block',
+        kind: 'component',
+        dirName: name,
+        name,
+        description: spec.description ?? '',
+        category: 'app',
+        importPath,
+        isDefault: Boolean(spec.default),
+      });
+    }
+  } catch {
+    // config is optional
+  }
+  return blocks;
+}
+
+/** @param {import('../../foundation/xle/xle-ast').RawIssue} issue */
+export function formatIssue(issue) {
+  const where = issue.line != null ? `line ${issue.line}: ` : '';
+  return `${where}${issue.message}`;
+}
+
+/**
+ * Parse + validate, throwing structured XDSErrors on failure.
+ * Returns {doc, registry, blocks, warnings}.
+ *
+ * @param {string} expression
+ * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]
+ */
+export async function analyze(
+  expression,
+  {form = 'auto', loose = false, cwd = process.cwd()} = {},
+) {
+  // Validate inputs in the API (not just the CLI): an empty expression or an
+  // unknown --form must error, not silently parse as an empty/compact layout.
+  if (typeof expression !== 'string' || expression.trim() === '') {
+    throw new AstryxError(
+      'Layout expression is empty.',
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+  if (form !== 'compact' && form !== 'outline' && form !== 'auto') {
+    throw new AstryxError(
+      `Invalid form "${form}". Must be one of: compact, outline, auto.`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_OPTION,
+    );
+  }
+  const registry =
+    /** @type {import('../../foundation/xle/xle-ast').Registry} */ (
+      /** @type {unknown} */ (await buildRegistry({cwd}))
+    );
+  const blocks = await loadBlocks(cwd);
+
+  /** @type {import('../../foundation/xle/xle-ast').XLEDoc} */
+  let doc;
+  try {
+    doc = parse(expression, {form});
+  } catch (e) {
+    if (e instanceof XLEParseError) {
+      throw new AstryxError(
+        `Layout expression syntax error at line ${e.line}, col ${e.col}: ${e.message}`,
+        undefined,
+        ERROR_CODES.ERR_LAYOUT_PARSE,
+      );
+    }
+    throw e;
+  }
+
+  const {errors, warnings} = validate(doc, registry, blocks, {loose});
+  return {doc, registry, blocks, errors, warnings};
+}

package/api/layout/check/check.d.mts

@@ -0,0 +1,16 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * `astryx layout check "<expr>" [--form compact|outline]`
+ * Validates without expanding; echoes both canonical surfaces.
+ *
+ * @param {string} expression
+ * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]
+ * @returns {Promise<import('../layout.type.mjs').LayoutCheckResponse>}
+ */
+export function layoutCheck(expression: string, options?: {
+    form?: "compact" | "outline" | "auto";
+    loose?: boolean;
+    cwd?: string;
+}): Promise<import("../layout.type.mjs").LayoutCheckResponse>;

package/api/layout/check/check.mjs

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx layout check` leaf — validate a layout expression without
+ * expanding, echoing both canonical surfaces (compact + outline). Resolution +
+ * validation come from ../_adapter.mjs (analyze); this leaf projects the
+ * `layout.check` envelope.
+ *
+ * @input  expression string (+ options)
+ * @output {type:'layout.check', data}
+ * @position api — leaf over ../_adapter.mjs + lib/xle/print
+ */
+
+import {toCompact, toOutline} from '../../../foundation/xle/print.mjs';
+import {analyze, formatIssue} from '../_adapter.mjs';
+
+/**
+ * `astryx layout check "<expr>" [--form compact|outline]`
+ * Validates without expanding; echoes both canonical surfaces.
+ *
+ * @param {string} expression
+ * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]
+ * @returns {Promise<import('../layout.type.mjs').LayoutCheckResponse>}
+ */
+export async function layoutCheck(expression, options = {}) {
+  const {form = 'auto', loose = false, cwd = process.cwd()} = options;
+  const {doc, errors, warnings} = await analyze(expression, {form, loose, cwd});
+
+  return {
+    type: 'layout.check',
+    data: {
+      valid: errors.length === 0,
+      form: doc.form,
+      errors: errors.map(e => ({...e, formatted: formatIssue(e)})),
+      warnings: warnings.map(formatIssue),
+      compact: toCompact(doc),
+      outline: toOutline(doc),
+    },
+  };
+}

package/api/layout/expand/expand.d.mts

@@ -0,0 +1,22 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * `astryx layout expand "<expr>" [path]`
+ *
+ * @param {string} expression
+ * @param {object} [options]
+ * @param {string} [options.targetPath] - write TSX here (validated against cwd)
+ * @param {'compact'|'outline'|'auto'} [options.form]
+ * @param {boolean} [options.loose] - downgrade unknown {hints} to TODO warnings
+ * @param {string} [options.name] - generated component name
+ * @param {string} [options.cwd]
+ * @returns {Promise<import('../layout.type.mjs').LayoutExpandResponse>}
+ */
+export function layoutExpand(expression: string, options?: {
+    targetPath?: string | undefined;
+    form?: "compact" | "auto" | "outline" | undefined;
+    loose?: boolean | undefined;
+    name?: string | undefined;
+    cwd?: string | undefined;
+}): Promise<import("../layout.type.mjs").LayoutExpandResponse>;