@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/foundation/response/response.doc.mjs

@@ -39,13 +39,16 @@ export const doc = {
           name: 'type',
           type: 'string',
           description:
-            'Names the payload shape. Every value is listed in the response-types enum.',
+            'Discriminator naming the payload shape. Each command guarantees ' +
+            'its own `type` at its return; there is no central union.',
           required: true,
         },
         {
           name: 'data',
           type: 'unknown',
-          description: "The command's payload; its shape depends on `type`.",
+          description:
+            "The command's payload. Structural by design, narrowed by the " +
+            'per-command return type, not by a map in the serializer.',
           required: true,
         },
         {
@@ -61,7 +64,7 @@ export const doc = {
       type: '{ apiVersion: number; error: string; code: ErrorCode; suggestions?: Suggestion[] }',
       description:
         'Emitted for every failure in --json mode, including uncaught throws ' +
-        'and command-line parse errors, which are converted to this shape.',
+        'and Commander parse errors, which are converted to this shape.',
       fields: [
         {
           name: 'apiVersion',
@@ -118,7 +121,7 @@ export const doc = {
       label: 'Success',
       code: `{
   "apiVersion": 1,
-  "type": "component.detail",
+  "type": "component",
   "data": { "name": "Button" }
 }`,
     },
@@ -150,13 +153,9 @@ export const doc = {
     {
       type: 'prose',
       text:
-        'The process exit code is part of the contract too. Exit 0 means success, ' +
-        'and every error envelope exits 1. Some commands also exit 1 with a success ' +
-        'envelope when what they report failed: a failed check (layout check, doctor ' +
-        'and its integration subcommands, integration verify, theme build ' +
-        '--check), a gap report that was not delivered, an upgrade left incomplete, ' +
-        'or init agent docs refused for a path outside the project. Read the ' +
-        'envelope, not the exit code, to tell them apart.',
+        'The process exit code is part of the contract too: successful commands ' +
+        'exit 0, and a JSON error envelope is accompanied by a non-zero exit ' +
+        '(jsonError exits 1).',
     },
   ],
 };

package/foundation/xle/browser.d.mts

@@ -2,8 +2,8 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * Validate an expression and return both canonical surfaces. Never throws on
- * invalid input; returns the errors.
+ * Validate an expression and return both canonical surfaces — the browser
+ * twin of `layout check`. Never throws on invalid input; returns the errors.
  *
  * @param {string} expression
  * @param {import('./xle-ast').Registry | import('./browser').SerializedRegistry | object} registry - serialized or hydrated
@@ -19,7 +19,7 @@ export function checkExpression(expression: string, registry: import("./xle-ast"
     loose?: boolean | undefined;
 }): import("./browser").CheckResult;
 /**
- * Validate + expand to TSX.
+ * Validate + expand to TSX — the browser twin of `layout expand`.
  * Returns either {code, ...} or {errors} (never writes files).
  *
  * @param {string} expression

package/foundation/xle/browser.mjs

@@ -44,8 +44,8 @@ function formatIssue(issue) {
 }
 
 /**
- * Validate an expression and return both canonical surfaces. Never throws on
- * invalid input; returns the errors.
+ * Validate an expression and return both canonical surfaces — the browser
+ * twin of `layout check`. Never throws on invalid input; returns the errors.
  *
  * @param {string} expression
  * @param {import('./xle-ast').Registry | import('./browser').SerializedRegistry | object} registry - serialized or hydrated
@@ -85,7 +85,7 @@ export function checkExpression(expression, registry, opts = {}) {
 }
 
 /**
- * Validate + expand to TSX.
+ * Validate + expand to TSX — the browser twin of `layout expand`.
  * Returns either {code, ...} or {errors} (never writes files).
  *
  * @param {string} expression

package/foundation/xle/expand.mjs

@@ -13,7 +13,7 @@
  *
  * @input  validated doc (nodes carry .bound) + registry
  * @output expand() → {code, componentsUsed, states, todos}
- * @position lib/xle — last stage; the browser barrel orchestrates
+ * @position lib/xle — last stage; api/layout.mjs orchestrates
  */
 
 import {PAYLOAD_PROPS} from './validate.mjs';
@@ -751,7 +751,7 @@ export function expand(doc, registry, options = {}) {
     : [];
 
   const code = [
-    `// Generated by the Astryx XLE expander — this file is the artifact; edit freely.`,
+    `// Generated by \`astryx layout expand\` — this file is the artifact; edit freely.`,
     ...importLines,
     ...blockSection,
     '',

package/foundation/xle/parse.mjs

@@ -302,7 +302,7 @@ function parseAttrToken(token, line) {
  * Guard against unbounded recursion in the compact parser. A layout tree this
  * deep is never hand-authored; without the cap the recursive descent blows the
  * JS call stack and surfaces a raw RangeError (→ ERR_UNKNOWN, no line/col)
- * instead of a located parse error. The counter is module-level so it
+ * instead of a located ERR_LAYOUT_PARSE. The counter is module-level so it
  * spans group / attribute sub-streams; each parse entry point resets it.
  */
 const MAX_COMPACT_DEPTH = 512;

package/foundation/xle/print.mjs

@@ -3,8 +3,8 @@
 /**
  * @file XLE canonical printers — AST → compact (XLE) or outline (XLO) text.
  *
- * Used by `checkExpression` so either party (agent or human) can request the
- * other surface, and by round-trip conformance tests.
+ * Used by `astryx layout check --form …` so either party (agent or human)
+ * can request the other surface, and by round-trip conformance tests.
  * Printing is best-effort canonical: spelling variants the lexer
  * normalized are emitted in canonical form.
  *

package/foundation/xle/splice.mjs

@@ -18,7 +18,7 @@
  *
  * @input  block TSX source (splice) or a name+importPath (import)
  * @output prepareSpliceModule / parseImportStatements + import-merge helpers
- * @position lib/xle — used by expand.mjs; sources gathered by the caller
+ * @position lib/xle — used by expand.mjs; sources gathered in api/layout.mjs
  */
 
 const IMPORT_RE =

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.6.4-canary.f0355e3",
+  "version": "0.6.4",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -101,10 +101,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.6.4-canary.f0355e3",
-    "@astryxdesign/core": "0.6.4-canary.f0355e3",
-    "@astryxdesign/lab": "0.6.4-canary.f0355e3",
-    "@astryxdesign/theme-neutral": "0.6.4-canary.f0355e3"
+    "@astryxdesign/charts": "*",
+    "@astryxdesign/core": "*",
+    "@astryxdesign/lab": "*",
+    "@astryxdesign/theme-neutral": "*"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/charts": {
@@ -121,10 +121,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.6.4-canary.f0355e3",
-    "@astryxdesign/core": "0.6.4-canary.f0355e3",
-    "@astryxdesign/lab": "0.6.4-canary.f0355e3",
-    "@astryxdesign/theme-neutral": "0.6.4-canary.f0355e3",
+    "@astryxdesign/charts": "*",
+    "@astryxdesign/core": "*",
+    "@astryxdesign/lab": "*",
+    "@astryxdesign/theme-neutral": "*",
     "@heroicons/react": "^2.2.0",
     "@stylexjs/stylex": "^0.19.0",
     "@types/babel__core": "^7.20.5",

package/api/discover/_adapter.test.mjs

@@ -1,215 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Tests for how the discover adapter calls discover sources: order,
- * failure isolation, timeouts, and the saved copy. Sources are plain functions
- * on a stand-in project, and the saved copies go to a temp directory.
- */
-
-import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-import {callSources} from './_adapter.mjs';
-
-/**
- * @param {string} name
- * @param {object[]} packages
- */
-function catalog(name, packages) {
-  return {
-    schemaVersion: 1,
-    source: {name, generatedAt: '2026-09-30T00:00:00.000Z', complete: true},
-    packages,
-  };
-}
-
-/**
- * @param {string} name
- * @param {object} [extra]
- */
-function pkg(name, extra = {}) {
-  return {
-    package: name,
-    integration: name,
-    aliases: [],
-    latest: '1.0.0',
-    versions: [
-      {version: '1.0.0', publishedAt: null, prerelease: false, status: 'ok'},
-    ],
-    contributions: [],
-    ...extra,
-  };
-}
-
-/**
- * @param {{config?: object, integrations?: object[]}} parts
- * @returns {any}
- */
-function project({config = {}, integrations = []}) {
-  return {config, loadedIntegrations: integrations, cwd: '/virtual/project'};
-}
-
-let cacheDir;
-
-beforeEach(() => {
-  cacheDir = fs.mkdtempSync(path.join(os.tmpdir(), 'discover-cache-'));
-});
-
-afterEach(() => {
-  fs.rmSync(cacheDir, {recursive: true, force: true});
-});
-
-describe('callSources', () => {
-  it('asks the project source first, then each integration in load order, once per function', async () => {
-    /** @type {string[]} */
-    const calls = [];
-    const shared = vi.fn(async () => {
-      calls.push('shared');
-      return catalog('Shared', [pkg('@a/one')]);
-    });
-    const own = vi.fn(async () => {
-      calls.push('own');
-      return catalog('Own', [pkg('@a/one', {latest: '9.9.9'}), pkg('@a/two')]);
-    });
-
-    const result = await callSources(
-      project({
-        config: {discover: own},
-        integrations: [
-          {name: '@x/first', __discover: shared},
-          {name: '@x/second', __discover: shared},
-        ],
-      }),
-      {},
-      {cacheDir},
-    );
-
-    expect(calls).toEqual(['own', 'shared']);
-    expect(result.sources.map(s => [s.name, s.from, s.status])).toEqual([
-      ['Own', 'astryx.config', 'fresh'],
-      ['Shared', '@x/first', 'fresh'],
-    ]);
-    expect(result.packages.map(p => [p.package, p.latest, p.source])).toEqual([
-      ['@a/one', '9.9.9', 'Own'],
-      ['@a/two', '1.0.0', 'Own'],
-    ]);
-  });
-
-  it('passes the package and version it wants, with an abort signal', async () => {
-    const source = vi.fn(async () => catalog('S', []));
-
-    await callSources(
-      project({integrations: [{name: '@x/src', __discover: source}]}),
-      {package: '@a/one', version: '1.0.0'},
-      {cacheDir},
-    );
-
-    expect(source).toHaveBeenCalledWith({
-      signal: expect.any(globalThis.AbortSignal),
-      package: '@a/one',
-      version: '1.0.0',
-    });
-  });
-
-  it('keeps every other source when one throws, returns bad data, or is not a function', async () => {
-    const result = await callSources(
-      project({
-        integrations: [
-          {
-            name: '@x/throws',
-            __discover: async () => {
-              throw new Error('offline');
-            },
-          },
-          {name: '@x/bad', __discover: async () => ({schemaVersion: 2})},
-          {
-            name: '@x/broken',
-            __discoverError: 'named export "discover" must be a function',
-          },
-          {
-            name: '@x/good',
-            __discover: async () => catalog('Good', [pkg('@a/one')]),
-          },
-        ],
-      }),
-      {},
-      {cacheDir},
-    );
-
-    expect(result.sources.map(s => [s.from, s.status])).toEqual([
-      ['@x/throws', 'failed'],
-      ['@x/bad', 'failed'],
-      ['@x/broken', 'failed'],
-      ['@x/good', 'fresh'],
-    ]);
-    expect(result.sources[0].error).toContain('offline');
-    expect(result.sources[1].error).toContain('schemaVersion 2');
-    expect(result.sources[2].error).toContain('must be a function');
-    expect(result.packages.map(p => p.package)).toEqual(['@a/one']);
-  });
-
-  it('gives up on a source after the timeout and aborts its signal', async () => {
-    /** @type {AbortSignal | undefined} */
-    let seen;
-    const slow = ({signal}) => {
-      seen = signal;
-      return new Promise(() => {});
-    };
-
-    const result = await callSources(
-      project({integrations: [{name: '@x/slow', __discover: slow}]}),
-      {},
-      {cacheDir, timeoutMs: 20},
-    );
-
-    expect(result.sources[0]).toMatchObject({
-      status: 'failed',
-      error: expect.stringContaining('did not answer'),
-    });
-    expect(seen?.aborted).toBe(true);
-  });
-
-  it('uses the copy saved for the same request when a source fails, and says when it was saved', async () => {
-    let online = true;
-    const source = async () => {
-      if (!online) throw new Error('offline');
-      return catalog('S', [pkg('@a/one')]);
-    };
-    const p = project({integrations: [{name: '@x/src', __discover: source}]});
-
-    await callSources(p, {}, {cacheDir});
-    online = false;
-    const offline = await callSources(p, {}, {cacheDir});
-
-    expect(offline.sources[0]).toMatchObject({
-      name: 'S',
-      status: 'saved',
-      error: 'offline',
-      savedAt: expect.any(String),
-    });
-    expect(offline.packages.map(x => x.package)).toEqual(['@a/one']);
-
-    const otherRequest = await callSources(p, {package: '@a/one'}, {cacheDir});
-    expect(otherRequest.sources[0].status).toBe('failed');
-  });
-
-  it('keeps the saved copy in the cache directory, not in the project', async () => {
-    await callSources(
-      project({
-        integrations: [
-          {name: '@x/src', __discover: async () => catalog('S', [])},
-        ],
-      }),
-      {},
-      {cacheDir},
-    );
-
-    expect(fs.readdirSync(path.join(cacheDir, 'discover'))).toHaveLength(1);
-    expect(fs.existsSync('/virtual/project')).toBe(false);
-  });
-
-  it('returns nothing when there is no project', async () => {
-    expect(await callSources(undefined)).toEqual({sources: [], packages: []});
-  });
-});

package/api/discover/_catalog-view.d.mts

@@ -1,115 +0,0 @@
-// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
-// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
-
-/**
- * @typedef {import('./_adapter.mjs').InstalledPackage} InstalledPackage
- * @typedef {import('./_adapter.mjs').CatalogResult} CatalogResult
- * @typedef {CatalogResult['packages'][number]} CatalogPackage
- * @typedef {import('../../authoring/discover/type').DiscoverKind} DiscoverKind
- */
-/**
- * An item search looks through. `kind: 'package'` is a package itself.
- * @typedef {object} SearchItem
- * @property {string} package
- * @property {DiscoverKind | 'package'} kind
- * @property {string} name
- * @property {boolean} installed
- * @property {string} [title]
- * @property {string} [summary]
- * @property {string[]} [keywords]
- * @property {string} [description]
- */
-/**
- * Group a version's contributions into the entry fields, one list per kind.
- * `components` is always present, like on an installed entry.
- * @param {CatalogPackage['contributions']} contributions
- * @returns {Record<string, string[]>}
- */
-export function kindLists(contributions: CatalogPackage["contributions"]): Record<string, string[]>;
-/**
- * Whether an entry adds at least one item of `kind`.
- * @param {Record<string, unknown>} entry
- * @param {DiscoverKind} kind
- * @returns {boolean}
- */
-export function hasKind(entry: Record<string, unknown>, kind: DiscoverKind): boolean;
-/**
- * Where a catalog package stands against the project.
- * @param {CatalogPackage} pkg
- * @param {Set<string>} installedNames
- * @param {Set<string>} declared
- * @returns {{state: 'installed' | 'declared' | 'alias' | 'available', installedAs?: string}}
- */
-export function catalogState(pkg: CatalogPackage, installedNames: Set<string>, declared: Set<string>): {
-    state: "installed" | "declared" | "alias" | "available";
-    installedAs?: string;
-};
-/**
- * The version a catalog package shows by default.
- * @param {CatalogPackage} pkg
- * @returns {string | undefined}
- */
-export function defaultVersion(pkg: CatalogPackage): string | undefined;
-/**
- * Project a catalog package into the entry shape installed packages use.
- * @param {CatalogPackage} pkg
- * @param {string | undefined} version
- */
-export function catalogEntry(pkg: CatalogPackage, version: string | undefined): {
-    description?: string | undefined;
-    version?: string | undefined;
-    name: string;
-    category: string;
-    components: string[];
-};
-/**
- * What the project could add: every catalog package it does not have, once per
- * integration (the first name a source lists), never an alias of one it has.
- * @param {CatalogResult} catalog
- * @param {InstalledPackage[]} installed
- * @param {Set<string>} declared
- */
-export function availableEntries(catalog: CatalogResult, installed: InstalledPackage[], declared: Set<string>): {
-    source: string;
-    aliases?: string[] | undefined;
-    description?: string | undefined;
-    version?: string | undefined;
-    name: string;
-    components: string[];
-}[];
-/**
- * Installed packages with the latest release a source knows for each.
- * @param {InstalledPackage[]} installed
- * @param {CatalogResult} catalog
- * @returns {Array<InstalledPackage & {latest?: string}>}
- */
-export function withLatest(installed: InstalledPackage[], catalog: CatalogResult): Array<InstalledPackage & {
-    latest?: string;
-}>;
-/**
- * Everything search looks through besides installed components (which the
- * search leaf keeps resolving the way it always has): installed packages and
- * their other items, and every package the project could add with its items.
- * @param {InstalledPackage[]} installed
- * @param {CatalogResult} catalog
- * @param {Set<string>} declared
- * @returns {SearchItem[]}
- */
-export function searchItems(installed: InstalledPackage[], catalog: CatalogResult, declared: Set<string>): SearchItem[];
-export type InstalledPackage = import("./_adapter.mjs").InstalledPackage;
-export type CatalogResult = import("./_adapter.mjs").CatalogResult;
-export type CatalogPackage = CatalogResult["packages"][number];
-export type DiscoverKind = import("../../authoring/discover/type").DiscoverKind;
-/**
- * An item search looks through. `kind: 'package'` is a package itself.
- */
-export type SearchItem = {
-    package: string;
-    kind: DiscoverKind | "package";
-    name: string;
-    installed: boolean;
-    title?: string | undefined;
-    summary?: string | undefined;
-    keywords?: string[] | undefined;
-    description?: string | undefined;
-};