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

package/authoring/discover/parse.test.mjs

@@ -0,0 +1,124 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the discover source and catalog checks.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {
+  DISCOVER_KINDS,
+  parseDiscoverCatalog,
+  parseDiscoverSource,
+} from './parse.mjs';
+
+function catalog(overrides = {}) {
+  return {
+    schemaVersion: 1,
+    source: {
+      name: 'Acme catalog',
+      generatedAt: '2026-09-30T14:00:00.000Z',
+      complete: true,
+    },
+    packages: [
+      {
+        package: '@acme/ui',
+        integration: 'acme-ui',
+        aliases: [],
+        latest: '2.0.0',
+        versions: [
+          {
+            version: '2.0.0',
+            publishedAt: '2026-09-29T00:00:00.000Z',
+            prerelease: false,
+            status: 'ok',
+          },
+        ],
+        contributions: [{kind: 'component', name: 'Button'}],
+      },
+    ],
+    ...overrides,
+  };
+}
+
+describe('parseDiscoverCatalog', () => {
+  it('accepts a catalog', () => {
+    expect(parseDiscoverCatalog(catalog())).toEqual(catalog());
+  });
+
+  it('drops fields it does not know, so a newer source still works', () => {
+    const parsed = parseDiscoverCatalog({...catalog(), cursor: 'next'});
+    expect(parsed).not.toHaveProperty('cursor');
+  });
+
+  it('drops items of a kind it does not know', () => {
+    const value = catalog();
+    value.packages[0].contributions.push({kind: 'widget', name: 'Spinner'});
+    expect(parseDiscoverCatalog(value).packages[0].contributions).toEqual([
+      {kind: 'component', name: 'Button'},
+    ]);
+  });
+
+  it('puts versions newest first whatever order the source used', () => {
+    const value = catalog();
+    value.packages[0].versions = [
+      {
+        version: '1.0.0',
+        publishedAt: '2026-01-05T00:00:00.000Z',
+        prerelease: false,
+        status: 'ok',
+      },
+      {version: '1.5.0', publishedAt: null, prerelease: false, status: 'ok'},
+      {
+        version: '2.0.0',
+        publishedAt: '2026-09-29T00:00:00.000Z',
+        prerelease: false,
+        status: 'ok',
+      },
+      {
+        version: '2.0.0-rc.1',
+        publishedAt: '2026-09-01T00:00:00.000Z',
+        prerelease: true,
+        status: 'ok',
+      },
+    ];
+    expect(
+      parseDiscoverCatalog(value).packages[0].versions.map(v => v.version),
+    ).toEqual(['2.0.0', '2.0.0-rc.1', '1.0.0', '1.5.0']);
+  });
+
+  it('refuses a schemaVersion it does not read', () => {
+    expect(() => parseDiscoverCatalog(catalog({schemaVersion: 2}))).toThrow(
+      'this CLI reads schemaVersion 1',
+    );
+  });
+
+  it('names the first problem and where it is', () => {
+    expect(() =>
+      parseDiscoverCatalog(catalog({packages: [{package: ''}]}), 'the source'),
+    ).toThrow(/^the source returned an invalid catalog at packages\.0\./);
+  });
+
+  it('lists the kinds in display order', () => {
+    expect(DISCOVER_KINDS).toEqual([
+      'component',
+      'template',
+      'doc',
+      'theme',
+      'codemod',
+      'agent-doc',
+    ]);
+  });
+});
+
+describe('parseDiscoverSource', () => {
+  it('accepts a function', () => {
+    const source = async () => catalog();
+    expect(parseDiscoverSource(source, 'discover')).toBe(source);
+  });
+
+  it('refuses anything else, such as a URL', () => {
+    expect(() =>
+      parseDiscoverSource('https://example.com/catalog.json', 'discover'),
+    ).toThrow('discover must be a function');
+  });
+});

package/authoring/discover/type.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Public type surface for discover sources.
+ *
+ * A discover source tells `astryx discover` which integrations exist beyond the
+ * ones a project already has. A project sets one as `discover` in
+ * `astryx.config`; an integration exports one as a `discover` NAMED export from
+ * its manifest. Discover calls every source, checks each answer, keeps a saved
+ * copy of the last good one, and never installs, enables, or runs anything a
+ * catalog names.
+ */
+
+/** Kinds of item a package can add. */
+export type DiscoverKind =
+  'component' | 'template' | 'doc' | 'theme' | 'codemod' | 'agent-doc';
+
+/** One item a package version adds. */
+export interface DiscoverContribution {
+  kind: DiscoverKind;
+  /**
+   * The name the CLI uses for it: a component name, template id, doc topic,
+   * theme slug, or codemod id.
+   */
+  name: string;
+  title?: string;
+  summary?: string;
+  keywords?: string[];
+}
+
+/** One published version of a package. */
+export interface DiscoverVersion {
+  version: string;
+  /** ISO 8601 publish time, or null when the source does not know it. */
+  publishedAt: string | null;
+  prerelease: boolean;
+  /** `ok`, or why the source could not read this version. */
+  status: string;
+}
+
+/** One npm package a source knows about. */
+export interface DiscoverPackage {
+  package: string;
+  /** Shared by every npm name that publishes the same integration. */
+  integration: string;
+  /** The integration's other npm names. Discover never offers one the project has. */
+  aliases: string[];
+  description?: string;
+  /** The latest release, or null when the package has only prereleases. */
+  latest: string | null;
+  /** Every version, newest first. */
+  versions: DiscoverVersion[];
+  /** What the requested version adds, or the latest when none was requested. */
+  contributions: DiscoverContribution[];
+}
+
+/** What a discover source returns. */
+export interface DiscoverCatalog {
+  schemaVersion: 1;
+  source: {
+    /** Shown to people, for example "Acme catalog". */
+    name: string;
+    /** ISO 8601 time the source's data was produced. */
+    generatedAt: string;
+    /** False when the source knows its list is partial. */
+    complete: boolean;
+  };
+  packages: DiscoverPackage[];
+}
+
+/** One call to a discover source. */
+export interface DiscoverSourceContext {
+  /** Aborted when the source exceeds its 30-second budget. */
+  readonly signal: AbortSignal;
+  /** Asks for one package: every version, and `version`'s contributions. */
+  readonly package?: string;
+  /** With `package`: the version whose contributions to return. Defaults to the latest. */
+  readonly version?: string;
+}
+
+/**
+ * A discover source: an async function, like `debug`. Set it as `discover` in
+ * astryx.config, or export it as `discover` from an integration manifest.
+ */
+export type DiscoverSource = (
+  context: DiscoverSourceContext,
+) => Promise<DiscoverCatalog>;

package/authoring/doctypes/_schema.d.mts

@@ -216,6 +216,7 @@ export const ComponentDocKindSchema: z.ZodObject<{
     theming: z.ZodOptional<z.ZodUnknown>;
     playground: z.ZodOptional<z.ZodUnknown>;
     examples: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    replaces: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
     displayName: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
@@ -316,6 +317,7 @@ export const FunctionDocKindSchema: z.ZodObject<{
 export const GenericDocKindSchema: z.ZodObject<{
     type: z.ZodLiteral<"generic">;
     title: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
     sections: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         title: z.ZodString;
@@ -384,7 +386,6 @@ export const GenericDocKindSchema: z.ZodObject<{
     import: z.ZodOptional<z.ZodString>;
     group: z.ZodOptional<z.ZodString>;
     category: z.ZodOptional<z.ZodString>;
-    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
     parent: z.ZodOptional<z.ZodString>;
     relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     hidden: z.ZodOptional<z.ZodBoolean>;
@@ -840,7 +841,6 @@ export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
     displayName: z.ZodOptional<z.ZodString>;
     group: z.ZodOptional<z.ZodString>;
     category: z.ZodOptional<z.ZodString>;
-    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
     isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
     hidden: z.ZodOptional<z.ZodBoolean>;
     hiddenComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -865,6 +865,7 @@ export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
     }>>;
     title: z.ZodString;
     description: z.ZodString;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
     sections: z.ZodArray<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         title: z.ZodString;

package/authoring/doctypes/_schema.mjs

@@ -307,6 +307,7 @@ const ComponentBaseSchema = z
     theming: z.unknown().optional(),
     playground: z.unknown().optional(),
     examples: z.array(z.unknown()).optional(),
+    replaces: z.string().min(1).optional(),
   })
   .passthrough();
 
@@ -414,6 +415,9 @@ export const GenericDocKindSchema = z
     ...BaseDocFields,
     type: z.literal('generic'),
     title: nonEmptyString.optional(),
+    // Search terms the title and sections do not use; `astryx search` matches
+    // them as keywords of the whole topic (ReferenceDoc `keywords`).
+    keywords: z.array(z.string()).optional(),
     sections: z.array(ReferenceSectionSchema).min(1).optional(),
     replaces: nonEmptyString.optional(),
     extends: nonEmptyString.optional(),
@@ -730,6 +734,8 @@ const LegacyBaseDocSchema = z.object({
 const LegacyReferenceDocSchema = LegacyBaseDocSchema.extend({
   title: nonEmptyString,
   description: z.string(),
+  // As on the stamped schema: search terms for the whole topic.
+  keywords: z.array(z.string()).optional(),
   sections: z.array(ReferenceSectionSchema).min(1),
   replaces: nonEmptyString.optional(),
   extends: nonEmptyString.optional(),

package/authoring/doctypes/base/graph-fields.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   displayName: 'Authored doc graph fields',
   namespace: 'authoring',
   description:
-    "Placement, compatibility aliases, and audience: fields every authored doc kind declares for the docs tree. The docs tree reads `placement` for every guide, the CLI's and each integration's; aliases and audience are not built yet. A reference topic outside the docs tree that sets one fails to load, and other doc kinds accept them and ignore them.",
+    "Fields every authored doc kind can declare for the docs tree: `placement`, plus two reserved fields, `aliases` and `audience`. The docs tree reads `placement` for every guide, the CLI's and each integration's. Nothing reads `aliases` or `audience` today: a reference topic outside the docs tree that sets one fails to load, and other doc kinds accept them and ignore them.",
   appliesTo: 'Every supported .doc.mjs object',
   fields: [
     {
@@ -45,13 +45,13 @@ export const doc = {
       name: 'aliases',
       type: 'string[]',
       description:
-        'Prior names or routes the docs tree will keep resolving to this doc, without creating another identity. Not read yet: a topic that sets it fails to load.',
+        'Reserved: prior names or routes the docs tree will keep resolving to this doc, without creating another identity. Nothing reads it today, and a topic that sets it fails to load.',
     },
     {
       name: 'audience',
       type: "'public' | 'internal'",
       description:
-        "Which docs bundle includes this doc ('public' when omitted). Not read yet: a topic that sets it fails to load.",
+        "Reserved: which docs bundle includes this doc ('public' when omitted). Nothing reads it today, and a topic that sets it fails to load.",
       default: "'public'",
     },
   ],

package/authoring/doctypes/base/type.ts

@@ -39,9 +39,11 @@ export interface DocPlacement {
 export interface AuthoredDocGraphFields {
   /** The doc's one parent in the docs tree: a namespace of its own package. */
   placement?: DocPlacement;
-  /** Prior routes or names the docs tree will keep resolving. Not read yet. */
+  /** Reserved: prior routes or names the docs tree will keep resolving.
+   *  Nothing reads it yet. */
   aliases?: string[];
-  /** Docs bundle audience; omit for public docs. Not read yet. */
+  /** Reserved: docs bundle audience; omit for public docs. Nothing reads it
+   *  yet. */
   audience?: DocAudience;
 }
 

package/authoring/doctypes/component/component.doc.mjs

@@ -52,6 +52,12 @@ export const doc = {
       description:
         'Exact public package specifier consumers use to import an integration-owned component. The packed-package gate resolves this specifier and verifies it exports the component name.',
     },
+    {
+      name: 'replaces',
+      type: 'string',
+      description:
+        "Integration components only: the exact `name` of the Core ComponentDoc this component takes over for unqualified lookup, so every app that loads the integration gets it from component detail, lists, search, swizzle, and issue routing. The Core original stays reachable with `--package @astryxdesign/core`. Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.",
+    },
     {
       name: 'keywords',
       type: 'string[]',

package/authoring/doctypes/component/type.ts

@@ -48,6 +48,14 @@ export interface ComponentBaseDoc extends AuthoredDocGraphFields {
   displayName: string;
   /** Exact consumer import specifier for integration-owned components. */
   import?: string;
+  /** Integration components only: the exact `name` of the Core ComponentDoc
+   *  this component takes over for unqualified lookup, so every app that loads
+   *  the integration gets this component from component detail, lists, search,
+   *  swizzle, and issue routing. The Core original stays reachable with
+   *  `--package @astryxdesign/core`. Set it only to intentionally own a Core
+   *  identity; give an alternative or variant its own name instead. Older CLIs
+   *  that do not read `replaces` keep the component under its own name. */
+  replaces?: string;
   /** Search keywords for CLI discovery. Terms a developer might type when
    *  looking for this component: synonyms, related UI concepts, and common
    *  names from other design systems (MUI, Chakra, Radix, and others).

package/authoring/doctypes/reference/reference.doc.mjs

@@ -51,6 +51,13 @@ export const doc = {
       type: 'string',
       description: "Navigation category: 'guide' or 'foundations'.",
     },
+    {
+      name: 'keywords',
+      type: 'string[]',
+      description:
+        "Words a reader may search for that the title and sections do not use: a synonym, a task, or another library's name for the same thing. `astryx search` matches each as a keyword of the whole topic, so an exact one ranks the topic like its own title does.",
+      example: "['dark mode', 'color scheme']",
+    },
     {
       name: 'replaces',
       type: 'string',

package/authoring/doctypes/reference/type.ts

@@ -127,6 +127,11 @@ export interface ReferenceDoc extends AuthoredDocGraphFields {
   description: string;
   /** Navigation category: 'guide' or 'foundations'. */
   category?: string;
+  /** Words a reader may search for that the title and sections do not use:
+   *  a synonym, a task ("dark mode"), or another library's name for the same
+   *  thing. `astryx search` matches each as a keyword of the whole topic, so
+   *  an exact one ranks the topic like its own title does. */
+  keywords?: string[];
   /** Name of an existing topic this doc takes the place of. Authored by an
    *  integration whose guide should be served instead of the built-in one —
    *  `replaces: 'getting-started'` on a doc named `getting-started` swaps the

package/authoring/doctypes/schema/schema.doc.mjs

@@ -49,7 +49,7 @@ export const doc = {
       name: 'namespace',
       type: 'string',
       description:
-        "The group that reads this doc: 'authoring' for a file an author writes (a section of `astryx docs authoring`), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
+        "The group that reads this doc: 'authoring' for a file an author writes (a section of {@link generic:authoring}), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
     },
     {
       name: 'aliases',
@@ -162,7 +162,7 @@ export const doc = {
       type: '{ dir: string }',
       description: 'Where component sources live.',
       fields: [
-        {name: 'components.dir', type: 'string', description: 'Glob root for XDS*.tsx files.', required: true},
+        {name: 'components.dir', type: 'string', description: 'Glob root for Acme*.tsx files.', required: true},
       ],
     },
   ],

package/authoring/doctypes/template/template.doc.mjs

@@ -56,7 +56,7 @@ export const doc = {
       name: 'replaces',
       type: 'string',
       description:
-        "Integration templates only: the exact id of the Core template this one replaces for unqualified lookup. Find it with `astryx --json template --list --package @astryxdesign/core`; the Core original stays selectable with `--package @astryxdesign/core`. A page replaces only a Core page and a block only a Core block. Needs @astryxdesign/cli 0.7.0 or later: earlier CLIs reject the field and withhold the package's templates and doc topics.",
+        "Integration templates only: the exact id of the Core template this one replaces for unqualified lookup. Find it with `astryx --json template --list --package @astryxdesign/core`; the Core original stays selectable with `--package @astryxdesign/core`. A page replaces only a Core page and a block only a Core block. Needs @astryxdesign/cli 0.7.0 or later: earlier CLIs reject the field, drop that template, and hide the package's doc topics.",
     },
     {
       name: 'isReady',

package/authoring/doctypes/template/type.ts

@@ -33,8 +33,8 @@ export interface BaseTemplateDoc extends AuthoredDocGraphFields {
    *  replaces for unqualified lookup (find it with
    *  `astryx --json template --list --package @astryxdesign/core`). The Core
    *  original stays selectable with `--package @astryxdesign/core`. Needs
-   *  `@astryxdesign/cli` 0.7.0 or later: earlier CLIs reject the field and
-   *  withhold the package's templates and doc topics. */
+   *  `@astryxdesign/cli` 0.7.0 or later: earlier CLIs reject the field,
+   *  drop that template, and hide the package's doc topics. */
   replaces?: string;
   /** Whether this template is ready for use. Templates with
    *  isReady: false show as "(WIP)" in the gallery and CLI. */

package/authoring/index.d.mts

@@ -3,6 +3,7 @@
 
 export { parseConfig } from "./config/parse.mjs";
 export { parseIntegration } from "./integration/parse.mjs";
+export { parseDiscoverCatalog } from "./discover/parse.mjs";
 export { parseCodemod } from "./codemod/parse.mjs";
 export { parseDebugEvent } from "./debug/parse.mjs";
 export { parseDoc } from "./doctypes/parse.mjs";

package/authoring/index.d.ts

@@ -44,6 +44,15 @@ export type {
   GapReportTarget,
   GapReportHandlerReceipt,
 } from './gap-report/type.js'; // gap-report handler contract
+export type {
+  DiscoverSource,
+  DiscoverSourceContext,
+  DiscoverCatalog,
+  DiscoverPackage,
+  DiscoverVersion,
+  DiscoverContribution,
+  DiscoverKind,
+} from './discover/type.js'; // discover source contract
 export type {AstryxCodemod, AstryxConfigCodemod} from './codemod/type.js'; // codemods/*
 
 // ═══════════════════════════════════════════════════════════════════════
@@ -67,6 +76,7 @@ export {
   parseGapReportHandler,
   parseGapReportReceipt,
 } from './gap-report/parse.mjs';
+export {parseDiscoverCatalog} from './discover/parse.mjs';
 export {parseCodemod} from './codemod/parse.mjs';
 export {parseDebugEvent} from './debug/parse.mjs';
 

package/authoring/index.mjs

@@ -20,6 +20,7 @@ export {
   parseGapReportHandler,
   parseGapReportReceipt,
 } from './gap-report/parse.mjs';
+export {parseDiscoverCatalog} from './discover/parse.mjs';
 export {parseCodemod} from './codemod/parse.mjs';
 export {parseDebugEvent} from './debug/parse.mjs';
 export {parseDoc} from './doctypes/parse.mjs';

package/authoring/integration/integration.doc.mjs

@@ -23,48 +23,49 @@ export const doc = {
       name: 'providerId',
       type: 'string',
       description:
-        'Stable logical provider ID. Omit to use package.json#name; set it to the prior package name only when an explicit rename must preserve artifact IDs. If two packages claim the same ID, the package being authored is used, otherwise the first-loaded one, and the CLI warns about the other.',
+        'The name that marks this package as the source of everything it contributes. Leave it out to use the package name from package.json. Set it to the old name only during a rename, so the IDs of what the package already contributed stay the same. If two packages use the same name here, the one you are working on wins; otherwise the one the CLI reads first wins, and the CLI warns about the other.',
       example: "'@acme/widgets'",
     },
     {
       name: 'components',
       type: 'string',
       description:
-        'Relative path to the components/docs root (resolved to absolute).',
+        'The folder that holds your components and their docs, relative to package.json.',
       example: "'./src/components'",
     },
     {
       name: 'templates',
       type: 'string',
       description:
-        'Relative path to the templates root (resolved to absolute).',
+        'The folder that holds your templates, relative to package.json.',
       example: "'./src/templates'",
     },
     {
       name: 'codemods',
       type: 'string',
-      description: 'Relative path to the codemods root (resolved to absolute).',
+      description:
+        'The folder that holds your codemods, relative to package.json.',
       example: "'./codemods'",
     },
     {
       name: 'docs',
       type: 'string',
       description:
-        'Relative path to the reference-docs (topics) root (resolved to absolute). Every {topic}.doc.{ts,mjs,js} under it is served by `astryx docs` beside the built-in topics; a topic may also declare `replaces` or `extends` to take the place of a built-in one or merge onto it.',
+        'The folder that holds your doc topics, relative to package.json. Every {topic}.doc.{ts,mjs,js} in it shows up in `astryx docs` next to the built-in topics; a topic can also set `replaces` or `extends` to take over a built-in topic or add to it.',
       example: "'./docs'",
     },
     {
       name: 'themes',
       type: 'string',
       description:
-        'Relative path to a source-theme root with one directory per theme slug. Each directory contains a source module and mandatory same-stem, strongly typed .doc.mjs descriptor. Installed themes appear in `astryx theme list` and can be copied with `astryx theme add`.',
+        'The folder that holds your themes, relative to package.json, with one folder per theme. Each theme folder has the theme source and a matching .doc.mjs file with the same name. Installed themes show up in `astryx theme list` and can be copied with `astryx theme add`.',
       example: "'./themes'",
     },
     {
       name: 'agentDocs',
       type: '{ append?: readonly string[] }',
       description:
-        'Static package guidance appended to the end of the managed agent block. The CLI owns the section heading, package labels, bullets, target files, and writes.',
+        'Lines of guidance your package adds to the end of the agent instructions the CLI manages. The CLI owns the heading, labels, bullets, and which files it writes.',
       example: "{ append: ['Run acme verify.'] }",
     },
     {
@@ -94,9 +95,10 @@ export const doc = {
     {
       type: 'prose',
       text:
-        'Provider identity defaults to package.json#name. During an explicit ' +
-        'package rename, set `providerId` to the prior canonical package name so ' +
-        'existing artifact IDs remain stable. Package version always comes from package.json.',
+        'The provider name defaults to the package name in package.json. ' +
+        'During a rename, set `providerId` to the old package name so the IDs ' +
+        'of what the package already contributed stay the same. The package ' +
+        'version always comes from package.json.',
     },
     {
       type: 'prose',