@astryxdesign/cli 0.6.4-canary.ed2e54e → 0.6.4

package/authoring/discover/discover.doc.mjs

@@ -1,138 +0,0 @@
-// 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

@@ -1,24 +0,0 @@
-// @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

@@ -1,128 +0,0 @@
-// 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);
-}

package/authoring/discover/parse.test.mjs

@@ -1,124 +0,0 @@
-// 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

@@ -1,87 +0,0 @@
-// 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>;