@astryxdesign/cli 0.6.4-canary.ed2e54e → 0.6.4

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.ed2e54e",
+  "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.ed2e54e",
-    "@astryxdesign/core": "0.6.4-canary.ed2e54e",
-    "@astryxdesign/lab": "0.6.4-canary.ed2e54e",
-    "@astryxdesign/theme-neutral": "0.6.4-canary.ed2e54e"
+    "@astryxdesign/charts": "*",
+    "@astryxdesign/core": "*",
+    "@astryxdesign/lab": "*",
+    "@astryxdesign/theme-neutral": "*"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/charts": {
@@ -121,10 +121,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.6.4-canary.ed2e54e",
-    "@astryxdesign/core": "0.6.4-canary.ed2e54e",
-    "@astryxdesign/lab": "0.6.4-canary.ed2e54e",
-    "@astryxdesign/theme-neutral": "0.6.4-canary.ed2e54e",
+    "@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;
-};

package/api/discover/_catalog-view.mjs

@@ -1,203 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Pure views over discover sources' catalogs: which catalog packages the
- * project already has, what it could add, and the items search looks through.
- * No I/O; the adapter supplies every input.
- *
- * @position api/discover — shared by the list, detail, item, and search leaves.
- */
-
-import {KIND_FIELDS} from './_adapter.mjs';
-
-/**
- * @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) {
-  /** @type {Record<string, string[]>} */
-  const lists = {components: []};
-  for (const [kind, field] of KIND_FIELDS) {
-    const names = contributions.filter(c => c.kind === kind).map(c => c.name);
-    if (names.length > 0 || field === 'components') lists[field] = names;
-  }
-  return lists;
-}
-
-/**
- * Whether an entry adds at least one item of `kind`.
- * @param {Record<string, unknown>} entry
- * @param {DiscoverKind} kind
- * @returns {boolean}
- */
-export function hasKind(entry, kind) {
-  const field = KIND_FIELDS.find(([k]) => k === kind)?.[1];
-  const values = field == null ? undefined : entry[field];
-  return Array.isArray(values) && values.length > 0;
-}
-
-/**
- * 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, installedNames, declared) {
-  if (installedNames.has(pkg.package)) return {state: 'installed'};
-  if (declared.has(pkg.package)) return {state: 'declared'};
-  const installedAs = pkg.aliases.find(
-    name => installedNames.has(name) || declared.has(name),
-  );
-  if (installedAs != null) return {state: 'alias', installedAs};
-  return {state: 'available'};
-}
-
-/**
- * The version a catalog package shows by default.
- * @param {CatalogPackage} pkg
- * @returns {string | undefined}
- */
-export function defaultVersion(pkg) {
-  return pkg.latest ?? pkg.versions[0]?.version;
-}
-
-/**
- * Project a catalog package into the entry shape installed packages use.
- * @param {CatalogPackage} pkg
- * @param {string | undefined} version
- */
-export function catalogEntry(pkg, version) {
-  const {components, ...others} = kindLists(pkg.contributions);
-  return {
-    name: pkg.package,
-    category: pkg.package,
-    components,
-    ...(version ? {version} : {}),
-    ...(pkg.description ? {description: pkg.description} : {}),
-    ...others,
-  };
-}
-
-/**
- * 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, installed, declared) {
-  const installedNames = new Set(installed.map(p => p.name));
-  /** @type {Set<string>} */
-  const integrations = new Set();
-  const entries = [];
-  for (const pkg of catalog.packages) {
-    if (catalogState(pkg, installedNames, declared).state !== 'available')
-      continue;
-    if (integrations.has(pkg.integration)) continue;
-    integrations.add(pkg.integration);
-    const version = defaultVersion(pkg);
-    const {category: _category, ...entry} = catalogEntry(pkg, version);
-    entries.push({
-      ...entry,
-      ...(pkg.aliases.length > 0 ? {aliases: pkg.aliases} : {}),
-      source: pkg.source,
-    });
-  }
-  return entries;
-}
-
-/**
- * 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, catalog) {
-  const byName = new Map(catalog.packages.map(p => [p.package, p]));
-  return installed.map(pkg => {
-    const latest = byName.get(pkg.name)?.latest;
-    return latest ? {...pkg, latest} : pkg;
-  });
-}
-
-/**
- * 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, catalog, declared) {
-  /** @type {SearchItem[]} */
-  const items = [];
-  for (const pkg of installed) {
-    items.push({
-      package: pkg.name,
-      kind: 'package',
-      name: pkg.name,
-      installed: true,
-      ...(pkg.description ? {description: pkg.description} : {}),
-    });
-    for (const [kind, field] of KIND_FIELDS) {
-      if (kind === 'component') continue;
-      const names = /** @type {Record<string, unknown>} */ (pkg)[field];
-      if (!Array.isArray(names)) continue;
-      for (const name of names) {
-        items.push({package: pkg.name, kind, name, installed: true});
-      }
-    }
-  }
-  const installedNames = new Set(installed.map(p => p.name));
-  /** @type {Set<string>} */
-  const integrations = new Set();
-  for (const pkg of catalog.packages) {
-    if (catalogState(pkg, installedNames, declared).state !== 'available')
-      continue;
-    if (integrations.has(pkg.integration)) continue;
-    integrations.add(pkg.integration);
-    items.push({
-      package: pkg.package,
-      kind: 'package',
-      name: pkg.package,
-      installed: false,
-      ...(pkg.description ? {description: pkg.description} : {}),
-    });
-    for (const c of pkg.contributions) {
-      items.push({
-        package: pkg.package,
-        kind: c.kind,
-        name: c.name,
-        installed: false,
-        ...(c.title ? {title: c.title} : {}),
-        ...(c.summary ? {summary: c.summary} : {}),
-        ...(c.keywords ? {keywords: c.keywords} : {}),
-      });
-    }
-  }
-  return items;
-}