@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @xds/cli
 
+# 0.1.8
+
+#### Breaking Changes
+
+- Avatar and AvatarGroup adopt Icon's abbreviated size scale — `size` now takes `xsm`/`sm`/`md`/`lg`/`xl` instead of `tiny`/`xsmall`/`small`/`medium`/`large`. Pixel values are unchanged (20/24/36/48/128px) and the default is now `md` (still 36px, formerly `small`). Avatar's tiers stay larger than Icon's because avatars align with media rather than glyphs. Run `astryx upgrade` to migrate call sites. (#2672)
+
+#### New Features
+
+- `astryx init --features agents` now defaults to creating root `AGENTS.md` — the tool-agnostic standard that Codex/Copilot, Cursor, and most agents read — instead of the Claude-specific `.claude/CLAUDE.md`. Claude output is now opt-in via `--agent claude` (→ `.claude/CLAUDE.md`), and `--agent all` still writes both. Projects with existing agent-doc files are unaffected: init still discovers and updates every file already present, so this only changes the from-scratch default. (#4216)
+- "Foolproof init": both `@astryxdesign/core` and `@astryxdesign/cli` now print a postinstall nudge pointing you to `npx @astryxdesign/cli init`, `astryx` commands nudge you to finish setup until init has run, and `astryx init` runs non-interactively (no TTY required) so it works in CI and agent environments. (#4147, #4153, #4154, #4155)
+
+#### Fixes
+
+- Stop suggesting bare `npx astryx` before the CLI is installed — it resolves to an unrelated package on the npm registry.
+  The CLI now emits an install-aware invocation everywhere it prints a command:
+- Extend the v0.1.0 upgrade codemods to cover test files that mock `@xds/core` modules, which were previously left half-migrated and broke after upgrade:
+- `astryx upgrade` now keeps the managed agent-docs block (`<!-- ASTRYX:START --> … <!-- ASTRYX:END -->`) in sync with the installed version on **every** path — including the up-to-date and no-codemods short-circuits that previously returned before any refresh, leaving AI agents reading a stale component index and superseded rules. The block documents the installed library, so it's now refreshed up front (independent of codemods) and reported in the `--json` receipt as `agentDocs`. One detection pass covers three cases: a stale block is rewritten (`--apply`) or reported as a pending change (dry-run, which no longer writes); a project with core installed but no managed block is nudged to run `astryx init --features agents`; an already-current block stays silent. (#4168, #4169)
+
+#### Documentation
+
+- Add a `cli-integrations` CLI docs topic (`astryx docs cli-integrations`) so the integration-authoring guide (originally written by @ejhammond) is discoverable through the CLI and docsite instead of an unreferenced markdown file. Rewrite the CLI README's Configuration section to match the current strict config schema (`integrations`, `issuesUrl`, `hooks.postCodemod`, `experimental.xle`) and reframe the Integrations section around the two-file API.
+
+#### Other Changes
+
+- Installed / global / dev runs suggest `<pm> astryx <cmd>` (e.g. `pnpm exec astryx …`), unchanged.
+- One-off runs (launched via `npx`/`pnpm dlx`/`yarn dlx`/`bunx`) suggest the scoped package `<dlx> @astryxdesign/cli <cmd>`, which always resolves to us.
+- **migrate-xds-module-specifiers**: rewrite the mocked-module path in `vi.mock`/`vi.doMock`/`jest.mock`/`jest.doMock` (and bare `mock`) calls, plus `import(...)` specifiers used in TS type positions (`typeof import('@xds/core/Text')`), so the mock still intercepts the renamed `@astryxdesign/*` import.
+- **drop-xds-prefix-imports**: un-prefix partial-mock override keys inside an `@xds/core` mock factory (e.g. `useXDSTruncation` → `useTruncation`) so the override matches the renamed export instead of silently overriding nothing. Scoped to recognized `@xds/core` mock factories only; unrelated object keys are untouched.
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @cixzhang
+- @ejhammond
+- @joeyfarina
+- @josephfarina
+
+---
+
 # 0.1.7
 
 #### New Features

package/README.md

@@ -2,15 +2,19 @@
 
 The CLI is the primary interface for working with the design system, for humans and machines alike. It provides component documentation, design tokens, page templates, theming tools, and upgrade codemods, all accessible via terminal commands, a typed JSON API, or programmatic imports. AI agents and build tools use the same API that powers the CLI, enabling end-to-end frontend development loops.
 
+Run it one-off with the scoped package (works whether or not it's installed):
+
 ```bash
-npx astryx --help
-npx astryx search button
-npx astryx component Button
-npx astryx docs tokens
-npx astryx docs migration
-npx astryx template --list
+npx @astryxdesign/cli --help
+npx @astryxdesign/cli search button
+npx @astryxdesign/cli component Button
+npx @astryxdesign/cli docs tokens
+npx @astryxdesign/cli docs migration
+npx @astryxdesign/cli template --list
 ```
 
+Once it's a project dependency (`npm install -D @astryxdesign/cli`), drop the scope and use the shorter `astryx` — e.g. `npx astryx component Button` or `pnpm exec astryx component Button`. Bare `astryx` resolves to an unrelated npm package until the CLI is installed, so prefer the scoped form above for first-run/one-off use.
+
 ## Finding things: `astryx search`
 
 When you don't know whether what you need is a component, a hook, a docs topic,
@@ -20,27 +24,29 @@ fuzzy matching for typos) and tagged with their domain plus the follow-up
 command to run:
 
 ```bash
-$ npx astryx search button
+$ astryx search button
 
 Results for "button" (20):
 
   [component]  Button
                Button triggers an action when clicked. Use it for form submissions…
-               → npx astryx component Button
+               → astryx component Button
 
   [component]  IconButton
                A button that shows only an icon with no visible text…
-               → npx astryx component IconButton
+               → astryx component IconButton
 
   [hook]       useClickableContainer
                Makes a container element clickable while preserving nested…
-               → npx astryx hook useClickableContainer
+               → astryx hook useClickableContainer
 
   [template]   Banner — Collapsible
                Combine an action button, dismiss control, and expandable detail area…
-               → npx astryx template BannerCollapsibleContent
+               → astryx template BannerCollapsibleContent
 ```
 
+(The CLI prints the follow-up commands with your actual runner — `npx astryx …` when installed, or `npx @astryxdesign/cli …` when run one-off.)
+
 Options:
 
 - `--type <component|hook|doc|template>`: restrict to a single domain
@@ -415,7 +421,7 @@ failures (warnings are fine) and `1` when any check fails. That makes it
 usable directly as a CI step:
 
 ```yaml
-- run: npx astryx doctor
+- run: npx @astryxdesign/cli doctor
 ```
 
 Use `--json` for a structured envelope (`{ apiVersion, type: "doctor",
@@ -423,13 +429,103 @@ data: { checks, summary } }`) that AI agents and scripts can parse.
 
 ## Configuration
 
-The CLI reads from an optional `astryx.config.mjs` in your project root:
+The CLI reads an optional `astryx.config.{ts,mjs,js}` from your project root
+(a sibling of `package.json`). Every field is optional; with no config file the
+CLI runs on defaults.
 
-```javascript
-export default {
-  templates: {
-    get: async id => fetchTemplateFromAPI(id),
-  },
+```typescript
+import {createConfig} from '@astryxdesign/core/config';
+
+export default createConfig({
+  integrations: ['@acme/astryx-widgets'],
   issuesUrl: 'https://github.com/your-org/your-repo/issues',
-};
+});
+```
+
+`createConfig` is a type-preserving helper: it returns its argument unchanged
+and exists only to give the config file editor autocomplete and type-checking. A
+plain `export default {}` object works identically. It's exported from
+`@astryxdesign/core` (not the CLI) so your config file gets type feedback
+without depending on the CLI; the same helper is re-exported from
+`@astryxdesign/cli/config` for back-compat.
+
+| 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`
+reports whether the config loads cleanly.
+
+## Integrations
+
+An **integration** is any npm package that contributes its own components,
+templates, and upgrade codemods to Astryx. The CLI surfaces them next to core's,
+through the same commands, so a consumer can `astryx component`,
+`astryx template`, and `astryx upgrade` across core and every integration
+uniformly. Use it to ship a first-party add-on, publish a third-party component
+library, or share an internal design-system package across apps.
+
+The system runs on two files, each with a small typed API:
+
+| File                             | Written by | Role                                      |
+| -------------------------------- | ---------- | ----------------------------------------- |
+| `astryx.config.{ts,mjs,js}`      | Consumer   | Lists which integration packages to load. |
+| `astryx.integration.{ts,mjs,js}` | Author     | Declares what a package contributes.      |
+
+The consumer side is the `integrations` field of [`astryx.config`](#configuration).
+The author side is the integration manifest below.
+
+### The integration manifest
+
+A package becomes an integration by exporting a manifest from
+`astryx.integration.{ts,mjs,js}` at its root (a sibling of `package.json`). The
+manifest points at where each kind of contribution lives; identity (name,
+version) comes from `package.json`, not the manifest.
+
+```typescript
+import {createIntegration} from '@astryxdesign/core/authoring';
+
+export default createIntegration({
+  components: './components',
+  templates: './templates',
+  codemods: './codemods',
+  issuesUrl: 'https://github.com/acme/widgets/issues',
+});
+```
+
+| Field        | Type     | Purpose                                                               |
+| ------------ | -------- | --------------------------------------------------------------------- |
+| `components` | `string` | Directory holding the package's components and their `.doc.*` files.  |
+| `templates`  | `string` | Directory holding the package's page/block templates.                 |
+| `codemods`   | `string` | Directory holding upgrade codemods run by `astryx upgrade`.           |
+| `issuesUrl`  | `string` | Where "report an issue" links for this package's contributions point. |
+
+Every field is optional; declare only the roots the package ships.
+`createIntegration` is a type-preserving helper (editor autocomplete and
+type-checking); it lives in `@astryxdesign/core/authoring` and is re-exported
+from `@astryxdesign/cli/integration` for back-compat.
+
+### How it works
+
+Every command loads the consumer's `astryx.config`, resolves each listed
+integration's manifest from `node_modules`, and discovers its contributions.
+Everything is validated against one strict schema at the load boundary, so the
+CLI presents core and integration contributions through a single, uniform
+surface.
+
+Discovery is resilient: a broken or misconfigured integration is skipped with a
+one-line warning on stderr instead of crashing the CLI, and it never corrupts a
+`--json` envelope. To inspect problems, run
+`astryx validate-integration <package>` for a detailed report on one package, or
+`astryx doctor` for an overall health check.
+
+For the full authoring walkthrough (component doc format, template packaging
+and `exports` requirements, and codemod authoring), see the guide:
+
+```bash
+astryx docs cli-integrations
 ```

package/{src/api → api/blog}/blog.mjs

@@ -10,9 +10,9 @@
  * blog's structure can change freely without touching the CLI.
  */
 
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {SITE_URL, SITE_ORIGIN} from '../lib/site.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {SITE_URL, SITE_ORIGIN} from '../../lib/site.mjs';
 
 /** Abort a feed/post fetch that hangs, and cap how much we'll read. */
 const FETCH_TIMEOUT_MS = 15000;
@@ -20,6 +20,10 @@ const MAX_BYTES = 5 * 1024 * 1024; // 5 MB — a blog feed is never larger.
 
 const FEED_URL = new URL('/rss.xml', SITE_URL).toString();
 
+/**
+ * @param {string} url
+ * @returns {Promise<string>}
+ */
 async function fetchText(url) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
@@ -31,7 +35,12 @@ async function fetchText(url) {
     });
   } catch (e) {
     clearTimeout(timer);
-    const reason = e.name === 'AbortError' ? 'timed out' : e.message;
+    const reason =
+      e instanceof Error
+        ? e.name === 'AbortError'
+          ? 'timed out'
+          : e.message
+        : String(e);
     throw new AstryxError(
       `Could not reach ${url}: ${reason}`,
       [],
@@ -61,6 +70,7 @@ async function fetchText(url) {
  * Defense in depth: a post's plaintext URL comes from feed content. Require it
  * to live on the canonical origin so even a tampered feed can't redirect the
  * CLI to another host.
+ * @param {string} target
  */
 function assertCanonicalOrigin(target) {
   let targetOrigin;
@@ -82,6 +92,10 @@ function assertCanonicalOrigin(target) {
   }
 }
 
+/**
+ * @param {string} value
+ * @returns {string}
+ */
 function unescapeXml(value) {
   return value
     .replace(/&lt;/g, '<')
@@ -91,12 +105,23 @@ function unescapeXml(value) {
     .replace(/&amp;/g, '&');
 }
 
+/**
+ * @param {string} item
+ * @param {string} name
+ * @returns {string}
+ */
 function tag(item, name) {
   const m = item.match(new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`));
   return m ? unescapeXml(m[1].trim()) : '';
 }
 
+/**
+ * @param {string} item
+ * @param {string} name
+ * @returns {string[]}
+ */
 function tagAll(item, name) {
+  /** @type {string[]} */
   const out = [];
   const re = new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`, 'g');
   let m;
@@ -104,7 +129,11 @@ function tagAll(item, name) {
   return out;
 }
 
-/** Extract the plaintext alternate href from an <item>. */
+/**
+ * Extract the plaintext alternate href from an <item>.
+ * @param {string} item
+ * @returns {string | null}
+ */
 function textHref(item) {
   // Match the atom:link alternate regardless of attribute order/quoting; then
   // confirm it's the text/plain alternate before trusting the href.
@@ -121,7 +150,11 @@ function textHref(item) {
   return null;
 }
 
-/** Derive a slug from a post link (last path segment). */
+/**
+ * Derive a slug from a post link (last path segment).
+ * @param {string} link
+ * @returns {string}
+ */
 function slugFromLink(link) {
   try {
     const path = new URL(link).pathname.replace(/\/$/, '');
@@ -131,6 +164,9 @@ function slugFromLink(link) {
   }
 }
 
+/**
+ * @param {string} xml
+ */
 function parseFeed(xml) {
   const items = [];
   const re = /<item>([\s\S]*?)<\/item>/g;

package/{src/api → api/blog}/blog.test.mjs

@@ -9,8 +9,8 @@
 
 import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import {blog} from './blog.mjs';
-import {AstryxError} from './error.mjs';
-import {SITE_URL} from '../lib/site.mjs';
+import {AstryxError} from '../error.mjs';
+import {SITE_URL} from '../../lib/site.mjs';
 
 const FEED = `<?xml version="1.0" encoding="UTF-8"?>
 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">

package/api/build/build.mjs

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file build API — the "assemble a page" assistant, as data.
+ *
+ * `build()` with no query signals the workflow playbook (`build.help`). With a
+ * query it runs the unified search and groups the results into a composition
+ * KIT (`build.kit`): the closest page templates, the blocks that cover parts,
+ * and the domain components to fill gaps, plus the always-on frame + foundation.
+ *
+ * The kit carries RAW `SearchResultEntry` objects and static name arrays only —
+ * never pre-formatted command strings. All CLI prefixing (formatCliCommand /
+ * getCliInvocation) and the section prose live in the command renderer, so the
+ * JSON shape stays package-manager-agnostic and stable across environments.
+ */
+
+import {search} from '../search/search.mjs';
+
+/** A page at/above this score is a confident direct match. */
+const PAGE_DIRECT = 95;
+/** Below this a page is too weak to offer even as a layout reference. */
+const PAGE_FLOOR = 50;
+/** Below this a block/domain-component match is incidental noise. */
+const DOMAIN_FLOOR = 55;
+
+/**
+ * Always-surfaced primitives. Every page needs a shell + layout/typography/
+ * action atoms, but these never keyword-match an idea ("dashboard" != "Stack"),
+ * so search alone never returns them. Kept here (not the renderer) because they
+ * are ALSO used to exclude these names from the idea-specific `domain` group.
+ */
+const FRAME = ['AppShell', 'TopNav', 'SideNav', 'Layout'];
+const FOUNDATION = [
+  'VStack', 'HStack', 'Grid', 'StackItem', 'Card', 'Section',
+  'Text', 'Heading', 'Button', 'Icon', 'Badge', 'Divider',
+];
+const ALWAYS = new Set([...FRAME, ...FOUNDATION]);
+
+/**
+ * The page-building assistant. No query → the playbook signal; a query → the
+ * grouped composition kit.
+ *
+ * @param {string} [query] what you're building (e.g. "analytics dashboard")
+ * @param {{cwd?: string, type?: import('../../types/search').SearchDomain, limit?: number}} [options]
+ * @returns {Promise<import('../../types/build').BuildHelpResponse | import('../../types/build').BuildKitResponse>}
+ */
+export async function build(query, options = {}) {
+  if (!query || !String(query).trim()) {
+    return {type: 'build.help', data: {playbook: true}};
+  }
+
+  const {cwd = process.cwd(), type, limit = 60} = options;
+  // search()'s JSDoc @returns widens results to object[]; the SearchResponse
+  // shape is the contract (api.d.ts). Cast locally rather than tightening the
+  // search @returns (a separate follow-up).
+  const result = /** @type {import('../../types/search').SearchResponse} */ (
+    await search(query, {cwd, type, limit})
+  );
+  const results = result.data.results;
+
+  const pages = results
+    .filter(r => r.domain === 'template' && r.kind !== 'block' && r.score >= PAGE_FLOOR)
+    .slice(0, 3);
+  const blocks = results
+    .filter(r => r.domain === 'template' && r.kind === 'block' && r.score >= DOMAIN_FLOOR)
+    .slice(0, 5);
+  const domain = results
+    .filter(
+      r =>
+        (r.domain === 'component' || r.domain === 'hook') &&
+        r.score >= DOMAIN_FLOOR &&
+        !ALWAYS.has(r.name),
+    )
+    .slice(0, 6);
+  const directMatch = pages.length > 0 && pages[0].score >= PAGE_DIRECT;
+
+  return {
+    type: 'build.kit',
+    data: {
+      query: result.data.query,
+      // Distinguishes "search found nothing" (renderer shows "No matches")
+      // from a weak-but-non-empty result set (renderer still shows the kit).
+      hasResults: results.length > 0,
+      directMatch,
+      pages,
+      blocks,
+      domain,
+      frame: FRAME,
+      foundation: FOUNDATION,
+    },
+  };
+}

package/api/build/build.test.mjs

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the build API (playbook signal + composition kit).
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {build} from './build.mjs';
+
+// api/build/ -> up 3 = packages/cli, up 4 = repo root (has packages/core).
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+
+// build() delegates to search(), whose first (cold) call is slow under vitest.
+vi.setConfig({testTimeout: 30000});
+
+describe('build API', () => {
+  it('no query → build.help playbook signal', async () => {
+    const r = await build();
+    expect(r.type).toBe('build.help');
+    expect(r.data).toEqual({playbook: true});
+  });
+
+  it('query → build.kit with raw entries + static frame/foundation', async () => {
+    const r = await build('dashboard', {cwd: REPO});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.query).toBe('dashboard');
+    expect(r.data.hasResults).toBe(true);
+    expect(r.data.frame).toContain('AppShell');
+    expect(r.data.foundation).toContain('Button');
+    expect(Array.isArray(r.data.pages)).toBe(true);
+
+    // Entries are RAW SearchResultEntry objects — never package-manager-prefixed
+    // command strings (that formatting is the CLI renderer's job).
+    for (const e of [...r.data.pages, ...r.data.blocks, ...r.data.domain]) {
+      expect(typeof e.name).toBe('string');
+      expect(typeof e.score).toBe('number');
+      expect(e.command).not.toMatch(/^(pnpm|npm|yarn|bun|npx)\b/);
+    }
+  });
+
+  it('excludes always-on frame/foundation names from the domain group', async () => {
+    const r = await build('dashboard', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error('expected build.kit');
+    const names = r.data.domain.map(d => d.name);
+    expect(names).not.toContain('Button');
+    expect(names).not.toContain('AppShell');
+  });
+
+  it('applies grouping caps, score floors, and directMatch threshold', async () => {
+    const r = await build('dashboard', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error('expected build.kit');
+    const {pages, blocks, domain, directMatch} = r.data;
+
+    // Caps: pages ≤ 3, blocks ≤ 5, domain ≤ 6.
+    expect(pages.length).toBeLessThanOrEqual(3);
+    expect(blocks.length).toBeLessThanOrEqual(5);
+    expect(domain.length).toBeLessThanOrEqual(6);
+
+    // Score floors: pages ≥ PAGE_FLOOR(50); blocks/domain ≥ DOMAIN_FLOOR(55).
+    for (const p of pages) expect(p.score).toBeGreaterThanOrEqual(50);
+    for (const b of blocks) expect(b.score).toBeGreaterThanOrEqual(55);
+    for (const d of domain) expect(d.score).toBeGreaterThanOrEqual(55);
+
+    // directMatch iff the top page is a confident match (PAGE_DIRECT = 95).
+    expect(directMatch).toBe(pages.length > 0 && pages[0].score >= 95);
+
+    // Domain partitioning: pages = non-block templates, blocks = block templates,
+    // domain = components/hooks.
+    for (const p of pages) {
+      expect(p.domain).toBe('template');
+      expect(p.kind).not.toBe('block');
+    }
+    for (const b of blocks) {
+      expect(b.domain).toBe('template');
+      expect(b.kind).toBe('block');
+    }
+    for (const d of domain) expect(['component', 'hook']).toContain(d.domain);
+  });
+
+  it('no matches → build.kit with hasResults=false and empty groups', async () => {
+    const r = await build('zzznomatch99', {cwd: REPO});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.hasResults).toBe(false);
+    expect(r.data.pages).toHaveLength(0);
+    expect(r.data.blocks).toHaveLength(0);
+    expect(r.data.domain).toHaveLength(0);
+  });
+});