@astryxdesign/cli 0.6.4 → 0.6.5-canary.031021b

package/assets/docs/working-with-ai.doc.mjs

@@ -8,6 +8,7 @@ export const docs = {
   category: 'guide',
   description:
     'How to set up AI coding tools to generate correct component code.',
+  keywords: ['claude', 'cursor', 'codex', 'copilot', 'agents', 'mcp'],
 
   sections: [
     {
@@ -24,7 +25,8 @@ export const docs = {
       ],
     },
     {
-      title: 'Quick Start',
+      id: 'quick-start',
+      title: 'Set up agent docs',
       content: [
         {
           type: 'prose',
@@ -38,7 +40,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "That's it. The `init --features agents` command generates everything your AI needs (component index, behavioral rules, CLI reference, and package guidance from configured integrations) from the installed project. After a dependency bump, `astryx upgrade` reports a stale block and `astryx upgrade --apply` refreshes it.",
+          text: "That's it. The `init --features agents` command generates everything your AI needs (component index, behavioral rules, CLI reference, and package guidance from configured integrations) from the installed project. After a dependency bump, `astryx upgrade --from <old version>` reports a stale block and adding `--apply` refreshes it.",
         },
         {
           type: 'prose',
@@ -48,10 +50,12 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           label: 'Manual options',
-          code: `npx @astryxdesign/cli init --features agents --agent claude    # .claude/CLAUDE.md
-npx @astryxdesign/cli init --features agents --agent cursor    # .cursorrules
+          code: `npx @astryxdesign/cli init --features agents --agent claude    # CLAUDE.md if present, else .claude/CLAUDE.md
+npx @astryxdesign/cli init --features agents --agent cursor    # .cursorrules if present, else AGENTS.md
 npx @astryxdesign/cli init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)
-npx @astryxdesign/cli init --features agents --agent muse      # AGENTS.md (Muse)`,
+npx @astryxdesign/cli init --features agents --agent hermes    # .hermes.md or HERMES.md if present, else AGENTS.md
+npx @astryxdesign/cli init --features agents --agent muse      # AGENTS.md (Muse)
+npx @astryxdesign/cli init --features agents --agent all       # every agent file present, else AGENTS.md and .claude/CLAUDE.md`,
         },
       ],
     },
@@ -82,14 +86,17 @@ npx @astryxdesign/cli init --features agents --agent muse      # AGENTS.md (Muse
       content: [
         {
           type: 'prose',
-          text: 'Cursor project rules aren\'t always picked up; it selects which rules to apply based on relevance. For reliable inclusion, install the design system context as a User Rule instead. User Rules live at ~/.cursor/rules/ and apply across all projects.',
+          text: 'Cursor reads project rules from `.cursor/rules/`. To keep the Astryx context in a rule of its own, write it there. Give a path relative to the project root, such as `.cursor/rules/astryx.mdc`; an absolute path is refused.',
         },
         {
           type: 'code',
           lang: 'bash',
-          label: 'Install as a Cursor user rule',
-          code: `mkdir -p ~/.cursor/rules
-npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
+          label: 'Install as a Cursor project rule',
+          code: `npx @astryxdesign/cli init --features agents --agent-docs-path .cursor/rules/astryx.mdc`,
+        },
+        {
+          type: 'prose',
+          text: 'Rerunning the same command rewrites only the Astryx block, so frontmatter you add above it (such as `alwaysApply: true`) stays.',
         },
       ],
     },
@@ -98,7 +105,7 @@ npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/x
       content: [
         {
           type: 'prose',
-          text: 'Paste this into your AI before writing any component code. These three questions have a 0% pass rate without docs; models confidently guess wrong on all of them. If your AI can\'t answer them, it\'ll know to install the agent docs first.',
+          text: 'Paste this into your AI before writing any component code. If your AI can\'t answer these questions, it\'ll know to install the agent docs first.',
         },
         {
           type: 'code',
@@ -107,7 +114,7 @@ npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/x
           code: `Before writing any Astryx code, check your knowledge:
 
 1. What is the correct import path for Button?
-2. How do you make an Dialog non-dismissible?
+2. How do you make a Dialog non-dismissible?
 3. What prop does Selector use for its items?
 
 If you don't know all three, run \`npx @astryxdesign/cli init --features agents\` to generate agent docs, then read the generated file.`,
@@ -131,33 +138,34 @@ If you don't know all three, run \`npx @astryxdesign/cli init --features agents\
         },
         {
           type: 'prose',
-          text: 'With this alias, agents use `astryx component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
+          text: 'With this alias, agents run `npm run astryx -- component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Reliable CLI invocation',
-          code: `astryx component --list
-astryx component Dialog --dense
-astryx docs styling --dense
-astryx docs tokens --dense`,
+          code: `npm run astryx -- component --list
+npm run astryx -- component Dialog --dense
+npm run astryx -- docs styling --full --detail brief
+npm run astryx -- docs tokens --dense`,
         },
       ],
     },
     {
-      title: 'The --dense Flag',
+      id: 'the-dense-flag',
+      title: 'Shorter output: --detail and --dense',
       content: [
         {
           type: 'prose',
-          text: 'Every CLI command supports --dense, which outputs a token-efficient format designed for AI context windows. Use it when pasting CLI output into a web-based AI tool like ChatGPT or Claude.',
+          text: 'For a shorter read, add `--detail brief` (one line per section) or `--detail compact`. `--dense` swaps in a shorter text where a doc ships one. Use them when pasting CLI output into a web-based AI tool like ChatGPT or Claude.',
         },
         {
           type: 'code',
           lang: 'bash',
-          label: 'Dense output for pasting into AI conversations',
-          code: `astryx component Dialog --dense
-astryx docs styling --dense
-astryx docs tokens --dense`,
+          label: 'Short output for pasting into AI conversations',
+          code: `astryx docs styling --full --detail brief
+astryx component Dialog --detail compact
+astryx docs principles --dense`,
         },
       ],
     },

package/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsx

@@ -4,7 +4,7 @@
 
 import {useState} from 'react';
 import {InternationalizationProvider} from '@astryxdesign/core/i18n';
-import frFR from '@astryxdesign/core/locales/fr-FR.json';
+import frFR from '@astryxdesign/core/locales/fr-FR.generated.js';
 import {Stack} from '@astryxdesign/core/Layout';
 import {
   SegmentedControl,

package/authoring/config/config.doc.mjs

@@ -10,7 +10,7 @@
 export const doc = {
   type: 'schema',
   name: 'config',
-  displayName: 'Astryx Config',
+  displayName: 'astryx.config',
   namespace: 'authoring',
   description:
     'The optional astryx.config.* file at your project root. Declares which ' +
@@ -60,6 +60,14 @@ export const doc = {
       example:
         "{ audience: 'internal', async handle(report, {signal}) { return sendGap(report, {signal}); } }",
     },
+    {
+      name: 'discover',
+      type: 'DiscoverSource',
+      description:
+        'Tell `astryx discover` which integrations this project could add: an async function that returns a catalog. An integration can provide one too, as a `discover` named export from its manifest. Discover calls every source, yours first, and one that fails never hides the others. Discover only reads; your package manager installs.',
+      example:
+        "async ({signal, package: name, version}) => fetchCatalog({signal, name, version})",
+    },
     {
       name: 'experimental',
       type: '{ xle?: { components?: Record<string, XleComponent> } }',

package/authoring/config/parse.d.mts

@@ -30,6 +30,7 @@ export type XleComponent = import("./type.js").XleComponent;
 export type DebugConfig = import("./type.js").DebugConfig;
 export type DebugEventHandler = import("../debug/type.js").DebugEventHandler;
 export type GapReportHandler = import("../gap-report/type.js").GapReportHandler;
+export type DiscoverSource = import("../discover/type.js").DiscoverSource;
 import { z } from 'zod';
 declare const configSchema: z.ZodObject<{
     integrations: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -48,6 +49,7 @@ declare const configSchema: z.ZodObject<{
     }, z.core.$strict>>;
     debug: z.ZodOptional<z.ZodType<import("../debug/type.js").DebugEventHandler, any, z.core.$ZodTypeInternals<import("../debug/type.js").DebugEventHandler, any>>>;
     gapReport: z.ZodOptional<z.ZodType<import("../gap-report/type.js").GapReportHandler, any, z.core.$ZodTypeInternals<import("../gap-report/type.js").GapReportHandler, any>>>;
+    discover: z.ZodOptional<z.ZodType<import("../discover/type.js").DiscoverSource, any, z.core.$ZodTypeInternals<import("../discover/type.js").DiscoverSource, any>>>;
     experimental: z.ZodOptional<z.ZodObject<{
         xle: z.ZodOptional<z.ZodObject<{
             components: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{

package/authoring/config/parse.mjs

@@ -12,6 +12,7 @@
 import {z} from 'zod';
 import {formatZodError} from '../_shared/errors.mjs';
 import {parseGapReportHandler} from '../gap-report/parse.mjs';
+import {parseDiscoverSource} from '../discover/parse.mjs';
 
 /** @typedef {import('./type.js').AstryxConfig} AstryxConfig */
 /** @typedef {import('./type.js').PostCodemodHook} PostCodemodHook */
@@ -19,6 +20,7 @@ import {parseGapReportHandler} from '../gap-report/parse.mjs';
 /** @typedef {import('./type.js').DebugConfig} DebugConfig */
 /** @typedef {import('../debug/type.js').DebugEventHandler} DebugEventHandler */
 /** @typedef {import('../gap-report/type.js').GapReportHandler} GapReportHandler */
+/** @typedef {import('../discover/type.js').DiscoverSource} DiscoverSource */
 
 // Typed `z.custom` so `z.infer` reproduces the real function type (not `unknown`).
 const buildCommand = /** @type {z.ZodType<PostCodemodHook['buildCommand']>} */ (
@@ -66,6 +68,22 @@ const gapReportHandlerSchema = /** @type {z.ZodType<GapReportHandler>} */ (
   )
 );
 
+// The same check an integration's `discover` named export passes. Typed
+// z.custom preserves the public function type.
+const discoverSourceSchema = /** @type {z.ZodType<DiscoverSource>} */ (
+  z.custom(
+    value => {
+      try {
+        parseDiscoverSource(value, 'discover');
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    {message: 'Expected a discover source function'},
+  )
+);
+
 const configSchema = z
   .object({
     integrations: z.array(z.string()).optional(),
@@ -76,6 +94,7 @@ const configSchema = z
       .optional(),
     debug: debugSchema.optional(),
     gapReport: gapReportHandlerSchema.optional(),
+    discover: discoverSourceSchema.optional(),
     experimental: z
       .object({
         xle: z

package/authoring/config/parse.test.mjs

@@ -63,6 +63,14 @@ describe('parseConfig (load boundary)', () => {
     ).toEqual({audience: 'internal', handle});
   });
 
+  it('accepts a discover source function and refuses anything else', () => {
+    const discover = async () => ({});
+    expect(parseConfig({discover}).discover).toBe(discover);
+    expect(reason({discover: 'https://example.com/catalog.json'})).toContain(
+      'discover',
+    );
+  });
+
   it('rejects obsolete or extended gap-report handler shapes', () => {
     expect(reason({gapReport: {command: './report.mjs'}})).toContain(
       'gapReport',

package/authoring/config/type.ts

@@ -11,6 +11,7 @@
 
 import type {DebugEventHandler} from '../debug/type.js';
 import type {GapReportHandler} from '../gap-report/type.js';
+import type {DiscoverSource} from '../discover/type.js';
 
 /**
  * A command to run as part of a post-codemod hook. Returned by a hook's
@@ -96,6 +97,16 @@ export interface AstryxConfig {
   debug?: DebugConfig;
   /** Route gap reports through a project-owned handler. See {@link GapReportHandler}. */
   gapReport?: GapReportHandler;
+  /**
+   * Tell `astryx discover` about integrations this project could add. See
+   * {@link DiscoverSource}.
+   *
+   * An integration can provide a source too, as a `discover` named export from
+   * its `astryx.integration.*` module. Discover calls every source: this one
+   * first, then each integration's in load order, and one that fails never
+   * hides the others.
+   */
+  discover?: DiscoverSource;
   /**
    * EXPERIMENTAL — shape may change and is not part of the stable config
    * contract. Provisional home for features still being proven out.

package/authoring/discover/discover.doc.d.mts

@@ -0,0 +1,13 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for DiscoverSource, the function `astryx discover` calls to
+ * learn which integrations a project could add.
+ * @input The DiscoverSource type and the catalog types beside it (`type.ts`),
+ *   which `parse.mjs` validates.
+ * @output The `discover-source` section of `astryx docs authoring`.
+ * @position packages/cli/authoring/discover — schema documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

package/authoring/discover/discover.doc.mjs

@@ -0,0 +1,138 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SchemaDoc for DiscoverSource, the function `astryx discover` calls to
+ * learn which integrations a project could add.
+ * @input The DiscoverSource type and the catalog types beside it (`type.ts`),
+ *   which `parse.mjs` validates.
+ * @output The `discover-source` section of `astryx docs authoring`.
+ * @position packages/cli/authoring/discover — schema documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc = {
+  type: 'schema',
+  name: 'discover-source',
+  displayName: 'DiscoverSource',
+  namespace: 'authoring',
+  description:
+    'A source for `astryx discover`: an async function that returns a catalog of packages a project could add, their versions, and what each version adds. Set it as `discover` in astryx.config, or export it as `discover` from an integration manifest. Discover calls every source, the project one first, and one that throws, runs past 30 seconds, or returns an invalid catalog never hides the others; discover then uses the last good answer it saved for that source. Discover only reads: it prints the command that adds a package and never runs it.',
+  appliesTo:
+    '`discover` in astryx.config.*, or the `discover` named export of astryx.integration.*',
+  fields: [
+    {
+      name: 'context',
+      type: 'DiscoverSourceContext',
+      description: 'The one argument the source is called with.',
+      required: true,
+      fields: [
+        {
+          name: 'context.signal',
+          type: 'AbortSignal',
+          description: 'Aborted when the source runs past 30 seconds.',
+          required: true,
+        },
+        {
+          name: 'context.package',
+          type: 'string',
+          description:
+            'Set when discover shows one package: return that package with every version.',
+        },
+        {
+          name: 'context.version',
+          type: 'string',
+          description:
+            "With `package`: return that version's contributions. Without it, the latest release's.",
+        },
+      ],
+    },
+    {
+      name: 'returns',
+      type: 'Promise<DiscoverCatalog>',
+      description:
+        'The catalog. Discover checks it, ignores fields and item kinds it does not know, and refuses any schemaVersion but 1.',
+      required: true,
+      fields: [
+        {
+          name: 'schemaVersion',
+          type: '1',
+          description: 'Version of the catalog shape.',
+          required: true,
+        },
+        {
+          name: 'source',
+          type: '{name: string, generatedAt: string, complete: boolean}',
+          description:
+            'Who answered, when the data was produced (ISO 8601), and false when the source knows its list is partial.',
+          required: true,
+        },
+        {
+          name: 'packages',
+          type: 'DiscoverPackage[]',
+          description:
+            'One entry per npm package. When two sources list the same package, the earlier source wins.',
+          required: true,
+          fields: [
+            {
+              name: 'packages[].package',
+              type: 'string',
+              description: 'The npm name.',
+              required: true,
+            },
+            {
+              name: 'packages[].integration',
+              type: 'string',
+              description:
+                'Shared by every npm name that publishes the same integration. Discover lists an integration once.',
+              required: true,
+            },
+            {
+              name: 'packages[].aliases',
+              type: 'string[]',
+              description:
+                "The integration's other npm names. Discover never offers a package the project has under another name.",
+              required: true,
+            },
+            {
+              name: 'packages[].description',
+              type: 'string',
+              description: 'One line, for the list and search.',
+            },
+            {
+              name: 'packages[].latest',
+              type: 'string | null',
+              description: 'The latest release. Null when there are only prereleases.',
+              required: true,
+            },
+            {
+              name: 'packages[].versions',
+              type: 'DiscoverVersion[]',
+              description:
+                'Every version, newest first: `{version, publishedAt, prerelease, status}`, where status is `ok` or why the version could not be read.',
+              required: true,
+            },
+            {
+              name: 'packages[].contributions',
+              type: 'DiscoverContribution[]',
+              description:
+                "What the requested (else latest) version adds: `{kind, name, title?, summary?, keywords?}`, where kind is `component`, `template`, `doc`, `theme`, `codemod`, or `agent-doc` (a DiscoverKind) and name is the name the CLI uses for it.",
+              required: true,
+            },
+          ],
+        },
+      ],
+    },
+  ],
+  examples: [
+    {
+      label: 'A project source in astryx.config',
+      code:
+        'export default {\n' +
+        '  async discover({signal, package: name, version}) {\n' +
+        '    const res = await fetch(catalogUrl(name, version), {signal});\n' +
+        '    return res.json();\n' +
+        '  },\n' +
+        '};',
+    },
+  ],
+};

package/authoring/discover/parse.d.mts

@@ -0,0 +1,24 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Check a catalog a discover source returned. Throws an Error naming the first
+ * problem. Items of a kind this CLI does not know are dropped, and versions are
+ * put newest first whatever order the source used.
+ *
+ * @param {unknown} value
+ * @param {string} [label]
+ * @returns {import('./type.js').DiscoverCatalog}
+ */
+export function parseDiscoverCatalog(value: unknown, label?: string): import("./type.js").DiscoverCatalog;
+/**
+ * Check a discover source itself: an async function, like `debug`, that takes
+ * `{signal, package?, version?}` and resolves to a catalog.
+ *
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {import('./type.js').DiscoverSource}
+ */
+export function parseDiscoverSource(value: unknown, label: string): import("./type.js").DiscoverSource;
+/** Item kinds a catalog may list, in display order. */
+export const DISCOVER_KINDS: readonly ["component", "template", "doc", "theme", "codemod", "agent-doc"];

package/authoring/discover/parse.mjs

@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Runtime checks for discover sources and the catalogs they return.
+ *
+ * The catalog schema is deliberately not strict: a source may add fields this
+ * CLI does not know, and they are dropped. An unknown `schemaVersion` is
+ * refused, and an item of a kind this CLI does not know is skipped, so a newer
+ * source never breaks an older CLI.
+ *
+ * @position packages/cli/authoring/discover — parse + validate, no I/O.
+ */
+
+import {z} from 'zod';
+
+/** Item kinds a catalog may list, in display order. */
+export const DISCOVER_KINDS = /** @type {const} */ ([
+  'component',
+  'template',
+  'doc',
+  'theme',
+  'codemod',
+  'agent-doc',
+]);
+
+const text = (/** @type {number} */ max) => z.string().min(1).max(max);
+
+const contributionSchema = z.object({
+  kind: text(32),
+  name: text(512),
+  title: z.string().max(512).optional(),
+  summary: z.string().max(4096).optional(),
+  keywords: z.array(z.string().max(128)).max(64).optional(),
+});
+
+const versionSchema = z.object({
+  version: text(256),
+  publishedAt: z.string().max(64).nullable(),
+  prerelease: z.boolean(),
+  status: text(64),
+});
+
+const packageSchema = z.object({
+  package: text(214),
+  integration: text(214),
+  aliases: z.array(text(214)).max(64),
+  description: z.string().max(1024).optional(),
+  latest: text(256).nullable(),
+  versions: z.array(versionSchema).max(50_000),
+  contributions: z.array(contributionSchema).max(50_000),
+});
+
+const catalogSchema = z.object({
+  schemaVersion: z.literal(1),
+  source: z.object({
+    name: text(256),
+    generatedAt: text(64),
+    complete: z.boolean(),
+  }),
+  packages: z.array(packageSchema).max(20_000),
+});
+
+/**
+ * Newest first by publish time. A version with no known publish time goes
+ * last, and ties fall back to the version number.
+ * @param {{version: string, publishedAt: string | null}} a
+ * @param {{version: string, publishedAt: string | null}} b
+ */
+function newestFirst(a, b) {
+  const at = Date.parse(a.publishedAt ?? '');
+  const bt = Date.parse(b.publishedAt ?? '');
+  if (Number.isNaN(at) !== Number.isNaN(bt)) return Number.isNaN(at) ? 1 : -1;
+  if (!Number.isNaN(at) && at !== bt) return bt - at;
+  return b.version.localeCompare(a.version, 'en', {numeric: true});
+}
+
+/**
+ * Check a catalog a discover source returned. Throws an Error naming the first
+ * problem. Items of a kind this CLI does not know are dropped, and versions are
+ * put newest first whatever order the source used.
+ *
+ * @param {unknown} value
+ * @param {string} [label]
+ * @returns {import('./type.js').DiscoverCatalog}
+ */
+export function parseDiscoverCatalog(value, label = 'discover source') {
+  const version =
+    value != null && typeof value === 'object'
+      ? /** @type {{schemaVersion?: unknown}} */ (value).schemaVersion
+      : undefined;
+  if (version !== undefined && version !== 1) {
+    throw new Error(
+      `${label} returned schemaVersion ${String(version)}; this CLI reads schemaVersion 1`,
+    );
+  }
+  const parsed = catalogSchema.safeParse(value);
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0];
+    const where = issue?.path.length ? ` at ${issue.path.join('.')}` : '';
+    throw new Error(
+      `${label} returned an invalid catalog${where}: ${issue?.message}`,
+    );
+  }
+  const known = /** @type {readonly string[]} */ (DISCOVER_KINDS);
+  return /** @type {import('./type.js').DiscoverCatalog} */ ({
+    ...parsed.data,
+    packages: parsed.data.packages.map(pkg => ({
+      ...pkg,
+      versions: [...pkg.versions].sort(newestFirst),
+      contributions: pkg.contributions.filter(c => known.includes(c.kind)),
+    })),
+  });
+}
+
+/**
+ * Check a discover source itself: an async function, like `debug`, that takes
+ * `{signal, package?, version?}` and resolves to a catalog.
+ *
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {import('./type.js').DiscoverSource}
+ */
+export function parseDiscoverSource(value, label) {
+  if (typeof value !== 'function') {
+    throw new Error(`${label} must be a function`);
+  }
+  return /** @type {import('./type.js').DiscoverSource} */ (value);
+}