@astryxdesign/cli 0.6.4-canary.06c8fa3 → 0.6.4-canary.2982c61

package/README.md

@@ -89,6 +89,7 @@ Options:
 | `hook`        | List hooks or print hook docs                                                 |
 | `init`        | Initialize the design system in your project                                  |
 | `integration` | Author and verify an Astryx integration package                               |
+| `layout`      | Generate XDS layouts from compressed expressions (XLE/XLO)                    |
 | `search`      | Search components, hooks, docs, and templates in one ranked list              |
 | `swizzle`     | Copy component source for customization                                       |
 | `template`    | Inject a page or block template                                               |
@@ -474,6 +475,9 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `integration.template-conflicts`  | The integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `integration.component-conflicts` | The integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command.                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `integration.doc-conflicts`       | The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`).                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `layout.expand`                   | 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).                                                                                                                                                                                                                                                                                                                                                                                  |
+| `layout.check`                    | 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).                                                                                                                                                                                                                                                                                                                                                                                              |
+| `layout.grammar`                  | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
 <!-- END GENERATED: response-types -->
 <!-- Generated by scripts/generate-cli-readme.mjs from the response-types EnumDoc. Run `pnpm -F @astryxdesign/cli readme`. -->
@@ -574,12 +578,12 @@ There is no factory: write a plain object. For editor autocomplete and
 type-checking, annotate it with the `AstryxConfig` type exported from
 `@astryxdesign/cli/authoring`.
 
-| Field                         | Type                           | Purpose                                                                                                                  |
-| ----------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
-| `integrations`                | `string[]`                     | Integration package names to load (see [Integrations](#integrations)).                                                   |
-| `issuesUrl`                   | `string`                       | Where "report an issue" links point for your project. Defaults to the core issue tracker.                                |
-| `hooks.postCodemod`           | `PostCodemodHook[]`            | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat).                             |
-| `experimental.xle.components` | `Record<string, XleComponent>` | No effect. Its only reader was the removed `layout` command. Still accepted so existing configs keep loading; delete it. |
+| Field                         | Type                           | Purpose                                                                                         |
+| ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `integrations`                | `string[]`                     | Integration package names to load (see [Integrations](#integrations)).                          |
+| `issuesUrl`                   | `string`                       | Where "report an issue" links point for your project. Defaults to the core issue tracker.       |
+| `hooks.postCodemod`           | `PostCodemodHook[]`            | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat).    |
+| `experimental.xle.components` | `Record<string, XleComponent>` | Register app-local components so layout (XLE) expressions can reference them by name. Unstable. |
 
 The config is validated against a strict schema when the CLI loads it, so an
 unknown field is a hard error rather than a silent no-op. `astryx doctor`

package/api/doctor/doctor.d.mts

@@ -257,20 +257,15 @@ export type DoctorContext = {
      * could not be built, when it could not.
      */
     docsCatalogError?: string | null | undefined;
+    /**
+     * Combined project-level integration issues, including cross-package template replacement warnings.
+     */
     integrationIssues?: {
         package: string;
         code: string;
         severity: "warning" | "error";
         message: string;
     }[] | null | undefined;
-    /**
-     * installed dependencies whose integration manifest could not be loaded
-     * Combined project-level integration issues, including cross-package template replacement warnings.
-     */
-    autolinkFailures?: {
-        spec: string;
-        error: string;
-    }[] | null | undefined;
     /**
      * - Error thrown while resolving the config
      * path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.

package/api/doctor/doctor.mjs

@@ -26,11 +26,7 @@ import * as path from 'node:path';
 import {MIN_NODE_VERSION, isNodeVersionSupported} from '../../foundation/env/node-version.mjs';
 import {CLI_ROOT, findCoreDir, findInstalledPackage} from '../../foundation/fs/paths.mjs';
 import {explainPackageManager, getCliInvocation} from '../../foundation/env/package-manager.mjs';
-import {
-  findConfigPath,
-  Project,
-  providerLedgerOf,
-} from '../../foundation/config/project.mjs';
+import {findConfigPath, Project} from '../../foundation/config/project.mjs';
 import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';
 import {buildDocsIndexData} from '../../foundation/discovery/docs-section-key.mjs';
 import {
@@ -80,8 +76,6 @@ import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env
  * @property {string|null} [docsCatalogError] - Why the project's docs catalog
  *   could not be built, when it could not.
  * @property {Array<{package: string, code: string, severity: 'warning'|'error', message: string}>|null} [integrationIssues]
- * @property {Array<{spec: string, error: string}>|null} [autolinkFailures]
- *   installed dependencies whose integration manifest could not be loaded
  *   Combined project-level integration issues, including cross-package template replacement warnings.
  * @property {Error|null} [configError] - Error thrown while resolving the config
  *   path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.
@@ -423,9 +417,6 @@ export function checkImplicitIntegrations(ctx) {
   const implicit = ctx.integrations.filter(
     integration => integration.__autolinked,
   );
-  // A dependency whose manifest cannot be loaded leaves no loaded record, so
-  // without this line doctor would say no dependency ships a manifest at all.
-  const unreadable = describeUnreadableManifests(ctx.autolinkFailures ?? []);
 
   if (implicit.length === 0) {
     return {
@@ -433,12 +424,9 @@ export function checkImplicitIntegrations(ctx) {
       label,
       status: 'info',
       message:
-        (ctx.integrations.length > 0
+        ctx.integrations.length > 0
           ? 'None — every loaded integration is named in astryx.config.'
-          : unreadable
-            ? 'None loaded.'
-            : 'None — no installed dependency ships an astryx.integration.* manifest.') +
-        unreadable,
+          : 'None — no installed dependency ships an astryx.integration.* manifest.',
     };
   }
 
@@ -451,25 +439,11 @@ export function checkImplicitIntegrations(ctx) {
       integration.__spec && integration.__spec !== integration.name
         ? ` (declared as "${integration.__spec}")`
         : '';
-    // A declared root counts only when it exists: the manifest's keys are a
-    // claim, and `integration-issues` reports the ones that are not true.
-    const declared = ['components', 'templates', 'themes', 'docs', 'codemods'].filter(
+    const roots = ['components', 'templates', 'themes', 'docs', 'codemods'].filter(
       root => integration[/** @type {'components'} */ (root)],
     );
-    const missing = declared.filter(root => {
-      const dir = integration[/** @type {'components'} */ (root)];
-      if (typeof dir !== 'string') return false;
-      const base =
-        typeof integration.__packageDir === 'string'
-          ? integration.__packageDir
-          : (ctx.cwd ?? process.cwd());
-      return !fs.existsSync(path.isAbsolute(dir) ? dir : path.resolve(base, dir));
-    });
-    const roots = declared.filter(root => !missing.includes(root));
     const contributes = roots.length > 0 ? roots.join(', ') : 'nothing';
-    const absent =
-      missing.length > 0 ? ` (declared ${missing.join(', ')} missing on disk)` : '';
-    return `${integration.name}${version}${alias} from ${integration.__dependencyField}, contributing ${contributes}${absent}`;
+    return `${integration.name}${version}${alias} from ${integration.__dependencyField}, contributing ${contributes}`;
   });
 
   const plural = implicit.length === 1 ? '' : 's';
@@ -479,8 +453,7 @@ export function checkImplicitIntegrations(ctx) {
     status: 'info',
     message:
       `${implicit.length} integration${plural} loaded from installed ` +
-      `dependencies with no astryx.config entry: ${described.join('; ')}.` +
-      unreadable,
+      `dependencies with no astryx.config entry: ${described.join('; ')}.`,
     fix:
       'Nothing to fix. Keep these dependencies installed. The CLI links them ' +
       'from package.json, so an unused-dependency check that looks only for ' +
@@ -489,30 +462,6 @@ export function checkImplicitIntegrations(ctx) {
   };
 }
 
-/**
- * The sentence `implicit-integrations` adds for dependencies whose manifest
- * could not be loaded, or '' when there are none. Still informational: the
- * package is a dependency's own bug, which `doctor integration validate`
- * diagnoses, but doctor must not report it as absent.
- * @param {Array<{spec: string, error: string}>} failures
- * @returns {string}
- */
-function describeUnreadableManifests(failures) {
-  if (failures.length === 0) return '';
-  const one = failures.length === 1;
-  const listed = failures
-    .map(({spec, error}) => {
-      const reason = String(error).split('\n')[0].slice(0, 160);
-      return `${spec} (${reason})`;
-    })
-    .join('; ');
-  return (
-    ` ${failures.length} installed ${one ? 'dependency ships' : 'dependencies ship'} ` +
-    `an astryx.integration.* manifest that could not be loaded, so ${one ? 'it contributes' : 'they contribute'} ` +
-    `nothing: ${listed}. Run \`astryx doctor integration validate <package>\` for details.`
-  );
-}
-
 /**
  * Check 7 — agent docs exist and contain the Astryx section markers.
  * @param {DoctorContext} ctx
@@ -789,26 +738,12 @@ export function checkProviderIdentity(ctx) {
     integration =>
       integration.providerId != null && integration.__loadError == null,
   ).length;
-  // An integration that could not be read has no provider ID to check, so the
-  // count above is not a complete survey. Say so instead of counting silently.
-  const unread = ctx.integrations.filter(
-    integration => integration.__loadError != null,
-  ).length;
-  const unreadNote =
-    unread === 0
-      ? ''
-      : unread === 1
-        ? ' 1 loaded integration could not be read, so its provider ID is unknown.'
-        : ` ${unread} loaded integrations could not be read, so their provider IDs are unknown.`;
   if (count === 0) {
     return {
       id,
       label,
       status: 'info',
-      message:
-        (unread === 0
-          ? 'None — no loaded integration has a provider identity.'
-          : 'No readable integration has a provider identity.') + unreadNote,
+      message: 'None — no loaded integration has a provider identity.',
     };
   }
   return {
@@ -816,10 +751,9 @@ export function checkProviderIdentity(ctx) {
     label,
     status: 'pass',
     message:
-      (count === 1
+      count === 1
         ? '1 loaded integration has its own provider ID.'
-        : `${count} loaded integrations each have their own provider ID.`) +
-      unreadNote,
+        : `${count} loaded integrations each have their own provider ID.`,
   };
 }
 
@@ -1264,25 +1198,11 @@ export async function runChecks(options = {}) {
   let docsCatalogError = null;
   /** @type {Array<{package: string, code: string, severity: 'warning'|'error', message: string}>|null} */
   let integrationIssues = null;
-  /** @type {Array<{spec: string, error: string}>|null} */
-  let autolinkFailures = null;
   try {
     const project = await Project.load(cwd);
     configTheme =
       /** @type {{theme?: string}} */ (project.config ?? {}).theme ?? null;
     integrations = project.loadedIntegrations;
-    // An installed dependency whose manifest cannot be loaded is kept out of
-    // loadedIntegrations on purpose. The provider ledger still records it.
-    autolinkFailures = [...providerLedgerOf(project).values()]
-      .filter(
-        entry =>
-          entry.outcome === 'load-failed' &&
-          entry.candidate.source === 'autolinked',
-      )
-      .map(entry => ({
-        spec: entry.candidate.spec ?? entry.label,
-        error: entry.error ?? 'its manifest could not be loaded',
-      }));
     try {
       docsCatalog = await project.docs();
       docsCatalogIssues = (await project.issues()).filter(
@@ -1309,7 +1229,6 @@ export async function runChecks(options = {}) {
     docsCatalogIssues,
     docsCatalogError,
     integrationIssues,
-    autolinkFailures,
     configError,
   };
 

package/api/doctor/doctor.test.mjs

@@ -354,31 +354,16 @@ describe('checkImplicitIntegrations', () => {
   });
 
   it('names the package, the field, and what it contributes', () => {
-    // Roots count only when they exist, so this one gives them real folders.
-    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-implicit-'));
-    try {
-      const dir = name => {
-        fs.mkdirSync(path.join(root, name));
-        return path.join(root, name);
-      };
-      const c = checkImplicitIntegrations({
-        integrations: [
-          autolinked({
-            components: dir('components'),
-            templates: dir('templates'),
-            themes: dir('themes'),
-          }),
-        ],
-      });
-      expect(c.message).toContain('@acme/widgets@1.0.0');
-      expect(c.message).toContain('from dependencies');
-      expect(c.message).toContain(
-        'contributing components, templates, themes',
-      );
-      expect(c.message).not.toContain('missing on disk');
-    } finally {
-      fs.rmSync(root, {recursive: true, force: true});
-    }
+    const c = checkImplicitIntegrations({
+      integrations: [
+        autolinked({templates: '/abs/templates', themes: '/abs/themes'}),
+      ],
+    });
+    expect(c.message).toContain('@acme/widgets@1.0.0');
+    expect(c.message).toContain('from dependencies');
+    expect(c.message).toContain(
+      'contributing components, templates, themes',
+    );
   });
 
   it('names the declared key too when an npm alias makes them differ', () => {
@@ -921,100 +906,3 @@ describe('checkDocsProgressiveDisclosure languages', () => {
     expect(c.message).not.toMatch(/deploying overview:/);
   });
 });
-
-describe('doctor says what it could not check', () => {
-  const CORE = {
-    'node_modules/@astryxdesign/core/package.json': JSON.stringify({
-      name: '@astryxdesign/core',
-      version: '0.6.3',
-    }),
-  };
-
-  /** Installed dependency whose manifest declares roots that do not exist. */
-  const dangling = {
-    'node_modules/@acme/dangling/package.json': JSON.stringify({
-      name: '@acme/dangling',
-      version: '2.0.0',
-    }),
-    'node_modules/@acme/dangling/astryx.integration.mjs':
-      "export default {providerId: 'acme-dangling', components: './components', templates: './templates', docs: './docs'};\n",
-  };
-
-  /** Installed dependency whose manifest cannot be parsed at all. */
-  const broken = {
-    'node_modules/@acme/broken/package.json': JSON.stringify({
-      name: '@acme/broken',
-      version: '1.0.0',
-    }),
-    'node_modules/@acme/broken/astryx.integration.mjs':
-      'export default {  this is not valid javascript ((\n',
-  };
-
-  /** @param {Record<string, string>} extra @param {string[]} deps */
-  const project = (extra, deps) =>
-    mkProject({
-      'package.json': JSON.stringify({
-        name: 'consumer',
-        version: '1.0.0',
-        dependencies: Object.fromEntries(
-          ['@astryxdesign/core', ...deps].map(d => [d, '1.0.0']),
-        ),
-      }),
-      ...CORE,
-      ...extra,
-    });
-
-  // An unparseable manifest is kept out of the loaded set on purpose, and
-  // doctor used to report that no installed dependency ships a manifest.
-  it('names an installed dependency whose manifest cannot be loaded', async () => {
-    const report = (await doctor({cwd: project(broken, ['@acme/broken'])})).data;
-    const check = report.checks.find(c => c.id === 'implicit-integrations');
-
-    expect(check.status).toBe('info');
-    expect(check.message).toContain('@acme/broken');
-    expect(check.message).toContain('could not be loaded');
-    expect(check.message).not.toContain('no installed dependency ships');
-    expect(report.summary.fail).toBe(0);
-  }, SLOW);
-
-  it('does not claim contributions from roots that are missing on disk', async () => {
-    const report = (await doctor({cwd: project(dangling, ['@acme/dangling'])}))
-      .data;
-    const implicit = report.checks.find(c => c.id === 'implicit-integrations');
-    const issues = report.checks.find(c => c.id === 'integration-issues');
-
-    expect(implicit.message).toContain('contributing nothing');
-    expect(implicit.message).toContain('missing on disk');
-    expect(implicit.message).not.toContain('contributing components');
-    expect(issues.status).toBe('warn');
-    expect(issues.message).toContain('@acme/dangling');
-  }, SLOW);
-
-  it('still says no dependency ships a manifest when none does', async () => {
-    const report = (await doctor({cwd: project({}, [])})).data;
-    const check = report.checks.find(c => c.id === 'implicit-integrations');
-
-    expect(check.message).toBe(
-      'None — no installed dependency ships an astryx.integration.* manifest.',
-    );
-  }, SLOW);
-
-  it('says how many integrations could not be read, rather than counting silently', () => {
-    /** @type {any} */
-    const ctx = {
-      cwd: '/x',
-      nodeVersion: process.versions.node,
-      coreDir: null,
-      configPath: null,
-      configTheme: null,
-      integrations: [
-        {name: '@acme/ok', __spec: '@acme/ok', providerId: 'ok'},
-        {name: '@acme/bad', __spec: '@acme/bad', __loadError: 'boom'},
-      ],
-    };
-    const check = checkProviderIdentity(ctx);
-
-    expect(check.message).toContain('1 loaded integration has its own provider ID.');
-    expect(check.message).toContain('could not be read');
-  });
-});

package/api/index.d.mts

@@ -33,12 +33,14 @@ export * from "./gap-report/gap-report.type.mjs";
 export * from "./upgrade/upgrade.type.mjs";
 export * from "./init/init.type.mjs";
 export * from "./doctor/doctor.type.mjs";
+export * from "./layout/layout.type.mjs";
 export * from "./integration/integration-authoring.type.mjs";
 export * from "./integration/pack-check.type.mjs";
 export * from "./integration/validate-integration.type.mjs";
 export * from "./integration/authoring-checks.type.mjs";
 export type Logger = import("./logger.mjs").Logger;
 export { themeBuild, themeAdd, themeTemplate, themeList, themeListAvailable, themeTargets, themePaletteGenerate, generateTonalPalette, listThemes } from "./theme/theme.mjs";
+export { layoutExpand, layoutCheck, layoutGrammar } from "./layout/layout.mjs";
 export { integrationAdd, integrationAddAgentDoc, integrationAddCodemod, integrationAddComponent, integrationAddDoc, integrationAddTemplate } from "./integration/add-contribution.mjs";
 export { validateIntegration, summarizeIssues } from "./integration/validate-integration.mjs";
 export { integrationTemplateConflicts, integrationComponentConflicts, integrationDocConflicts } from "./integration/authoring-checks.mjs";

package/api/index.mjs

@@ -44,6 +44,7 @@ export {gapReport} from './gap-report/gap-report.mjs';
 export {upgrade} from './upgrade/upgrade.mjs';
 export {init} from './init/init.mjs';
 export {doctor} from './doctor/doctor.mjs';
+export {layoutExpand, layoutCheck, layoutGrammar} from './layout/layout.mjs';
 export {
   integrationAdd,
   integrationAddAgentDoc,
@@ -92,6 +93,7 @@ export * from './gap-report/gap-report.type.mjs';
 export * from './upgrade/upgrade.type.mjs';
 export * from './init/init.type.mjs';
 export * from './doctor/doctor.type.mjs';
+export * from './layout/layout.type.mjs';
 export * from './integration/integration-authoring.type.mjs';
 export * from './integration/pack-check.type.mjs';
 export * from './integration/validate-integration.type.mjs';

package/api/integration/pack-check.mjs

@@ -162,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
@@ -191,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);

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/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;
+};