@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

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>;

package/clients/cli/commands/component-batch.test.mjs

@@ -1,341 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Multi-selector component lookup contract: one ordered batch envelope,
- * complete per-selector states, unchanged single-selector responses, and matching
- * text/JSON exit behavior.
- */
-
-import {describe, it, expect} from 'vitest';
-import * as path from 'node:path';
-import {
-  component,
-  COMPONENT_BATCH_SELECTOR_LIMIT,
-} from '../../../api/component/component.mjs';
-import {runCli} from '../../../test-utils/run-cli.mjs';
-
-const REPO_ROOT = path.resolve(import.meta.dirname, '../../../../..');
-const SLOW = 60_000;
-
-describe('component() batch lookup', () => {
-  it(
-    'keeps one found row per selector, in order, including duplicates',
-    async () => {
-      const result = await component(['Button', 'Badge', 'Button'], {
-        cwd: REPO_ROOT,
-        detail: 'brief',
-      });
-
-      expect(result.type).toBe('component.batch');
-      expect(result.data.count).toBe(3);
-      expect(result.data.results.map(row => row.selector)).toEqual([
-        'Button',
-        'Badge',
-        'Button',
-      ]);
-      expect(result.data.results.map(row => row.status)).toEqual([
-        'found',
-        'found',
-        'found',
-      ]);
-      expect(
-        result.data.results.map(row =>
-          row.status === 'found' ? row.result.type : null,
-        ),
-      ).toEqual(['component.detail', 'component.detail', 'component.detail']);
-    },
-    SLOW,
-  );
-
-  it(
-    'applies every focused projection to each found row',
-    async () => {
-      const projections = [
-        {options: {props: true}, expectedType: 'component.detail.props'},
-        {options: {source: true}, expectedType: 'component.detail.source'},
-        {options: {showcase: true}, expectedType: 'component.detail.showcase'},
-        {options: {blocks: true}, expectedType: 'component.detail.blocks'},
-      ];
-      for (const projection of projections) {
-        const result = await component(['Button', 'Card'], {
-          cwd: REPO_ROOT,
-          ...projection.options,
-        });
-        expect(result.type).toBe('component.batch');
-        expect(
-          result.data.results.map(row =>
-            row.status === 'found' ? row.result.type : null,
-          ),
-        ).toEqual([projection.expectedType, projection.expectedType]);
-      }
-    },
-    SLOW,
-  );
-
-  it(
-    'uses input shape to distinguish catalog, single, and batch calls',
-    async () => {
-      expect((await component(undefined, {cwd: REPO_ROOT})).type).toBe(
-        'component.list',
-      );
-      expect((await component('Button', {cwd: REPO_ROOT})).type).toBe(
-        'component.detail',
-      );
-
-      const emptyBatch = await component([], {cwd: REPO_ROOT});
-      expect(emptyBatch).toEqual({
-        type: 'component.batch',
-        data: {count: 0, results: []},
-      });
-      expect(
-        await component([], {
-          cwd: REPO_ROOT,
-          list: true,
-          category: 'Form',
-        }),
-      ).toEqual(emptyBatch);
-
-      const oneRowBatch = await component(['Button'], {
-        cwd: REPO_ROOT,
-        detail: 'brief',
-      });
-      expect(oneRowBatch).toMatchObject({
-        type: 'component.batch',
-        data: {
-          count: 1,
-          results: [
-            {
-              selector: 'Button',
-              status: 'found',
-              result: {type: 'component.detail'},
-            },
-          ],
-        },
-      });
-    },
-    SLOW,
-  );
-
-  it('rejects an oversized array before component resolution starts', async () => {
-    const selectors = Array.from(
-      {length: COMPONENT_BATCH_SELECTOR_LIMIT + 1},
-      () => 'Button',
-    );
-    await expect(
-      component(selectors, {
-        cwd: path.join(REPO_ROOT, 'missing-batch-cwd'),
-      }),
-    ).rejects.toMatchObject({
-      code: 'ERR_INVALID_ARGUMENT',
-      message: `Component batch accepts at most ${COMPONENT_BATCH_SELECTOR_LIMIT} selectors; received ${selectors.length}`,
-    });
-  });
-
-  it(
-    'keeps receipt invariants across a deterministic selector chaos matrix',
-    async () => {
-      const found = new Set(['Button', 'Card']);
-      const selectorCases = [
-        [],
-        ['Button'],
-        ['ZzzNope99'],
-        ['Button', 'Button'],
-        ['ZzzNope98', 'ZzzNope99'],
-        ['Button', 'ZzzNope99', 'Card'],
-        ['ZzzNope99', 'Button', 'ZzzNope99', 'Button'],
-        ['Card', 'Button', 'Card', 'ZzzNope98', 'Button'],
-      ];
-
-      for (const selectors of selectorCases) {
-        const result = await component(selectors, {
-          cwd: REPO_ROOT,
-          detail: 'brief',
-        });
-        expect(result.type).toBe('component.batch');
-        expect(result.data.count).toBe(selectors.length);
-        expect(result.data.results.map(row => row.selector)).toEqual(selectors);
-        expect(result.data.results.map(row => row.status)).toEqual(
-          selectors.map(selector =>
-            found.has(selector) ? 'found' : 'not_found',
-          ),
-        );
-        for (const row of result.data.results) {
-          if (row.status === 'found') {
-            expect(row.result.type).toBe('component.detail');
-          } else {
-            expect(row.code).toBe('ERR_UNKNOWN_COMPONENT');
-          }
-        }
-      }
-    },
-    SLOW,
-  );
-
-  it(
-    'composes every detail and language control over a batch',
-    async () => {
-      /** @type {Array<{detail?: 'full'|'compact'|'brief'; lang?: string; zh?: boolean; dense?: boolean}>} */
-      const controls = [
-        {detail: 'brief'},
-        {detail: 'compact'},
-        {detail: 'full'},
-        {lang: 'en'},
-        {lang: 'dense'},
-        {zh: true},
-        {dense: true},
-      ];
-      for (const control of controls) {
-        const result = await component(['Button', 'Card'], {
-          cwd: REPO_ROOT,
-          ...control,
-        });
-        expect(result.type).toBe('component.batch');
-        expect(result.data.results).toHaveLength(2);
-        expect(
-          result.data.results.every(
-            row =>
-              row.status === 'found' && row.result.type === 'component.detail',
-          ),
-        ).toBe(true);
-      }
-    },
-    SLOW,
-  );
-});
-
-describe('astryx component batch lookup', () => {
-  it('documents variadic selector grammar in --help', async () => {
-    const run = await runCli(['component', '--help'], REPO_ROOT);
-    expect(run.code).toBe(0);
-    expect(run.stdout).toContain(
-      'Usage: astryx component [options] [names...]',
-    );
-    expect(run.stdout).toContain('@scope/package@version/Name');
-    expect(run.stdout).toContain('Two or more return one ordered batch');
-    expect(run.stdout).toContain('At most 100 selectors');
-  });
-
-  it(
-    'keeps catalog and single-result CLI envelopes at zero and one selectors',
-    async () => {
-      const catalog = await runCli(['--json', 'component'], REPO_ROOT);
-      expect(catalog.code).toBe(0);
-      expect(JSON.parse(catalog.stdout).type).toBe('component.list');
-
-      const single = await runCli(
-        ['--json', '--detail', 'brief', 'component', 'Button'],
-        REPO_ROOT,
-      );
-      expect(single.code).toBe(0);
-      expect(JSON.parse(single.stdout).type).toBe('component.detail');
-    },
-    SLOW,
-  );
-
-  it(
-    'emits one component.batch JSON envelope for several found selectors',
-    async () => {
-      const run = await runCli(
-        ['--json', '--detail', 'brief', 'component', 'Button', 'Badge'],
-        REPO_ROOT,
-      );
-      expect(run.code).toBe(0);
-      const envelope = JSON.parse(run.stdout);
-      expect(envelope.type).toBe('component.batch');
-      expect(envelope.data.count).toBe(2);
-      expect(envelope.data.results.map(row => row.selector)).toEqual([
-        'Button',
-        'Badge',
-      ]);
-      expect(envelope.data.results.every(row => row.status === 'found')).toBe(
-        true,
-      );
-    },
-    SLOW,
-  );
-
-  it(
-    'rejects an oversized batch before emitting JSON or text results',
-    async () => {
-      const selectors = Array.from(
-        {length: COMPONENT_BATCH_SELECTOR_LIMIT + 1},
-        () => 'Button',
-      );
-      const json = await runCli(
-        ['--json', 'component', ...selectors],
-        REPO_ROOT,
-      );
-      expect(json.code).toBe(1);
-      expect(JSON.parse(json.stdout)).toMatchObject({
-        code: 'ERR_INVALID_ARGUMENT',
-        error: `Component batch accepts at most ${COMPONENT_BATCH_SELECTOR_LIMIT} selectors; received ${selectors.length}`,
-      });
-      expect(JSON.parse(json.stdout).type).toBeUndefined();
-
-      const text = await runCli(['component', ...selectors], REPO_ROOT);
-      expect(text.code).toBe(1);
-      expect(text.stdout + text.stderr).toContain(
-        `accepts at most ${COMPONENT_BATCH_SELECTOR_LIMIT} selectors`,
-      );
-    },
-    SLOW,
-  );
-
-  it(
-    'emits every row and exits 1 when one selector is not found',
-    async () => {
-      const run = await runCli(
-        ['--json', '--detail', 'brief', 'component', 'Button', 'ZzzNope99'],
-        REPO_ROOT,
-      );
-      expect(run.code).toBe(1);
-      const envelope = JSON.parse(run.stdout);
-      expect(envelope.type).toBe('component.batch');
-      expect(envelope.data.results).toMatchObject([
-        {selector: 'Button', status: 'found'},
-        {
-          selector: 'ZzzNope99',
-          status: 'not_found',
-          code: 'ERR_UNKNOWN_COMPONENT',
-        },
-      ]);
-    },
-    SLOW,
-  );
-
-  it(
-    'emits every failed row and exits 1 when no selector resolves',
-    async () => {
-      const run = await runCli(
-        ['--json', 'component', 'ZzzNope98', 'ZzzNope99'],
-        REPO_ROOT,
-      );
-      expect(run.code).toBe(1);
-      const envelope = JSON.parse(run.stdout);
-      expect(envelope.type).toBe('component.batch');
-      expect(envelope.data.count).toBe(2);
-      expect(envelope.data.results).toMatchObject([
-        {selector: 'ZzzNope98', status: 'not_found'},
-        {selector: 'ZzzNope99', status: 'not_found'},
-      ]);
-    },
-    SLOW,
-  );
-
-  it(
-    'projects every row in text and keeps the same failing exit status',
-    async () => {
-      const run = await runCli(
-        ['--detail', 'brief', 'component', 'Button', 'ZzzNope99'],
-        REPO_ROOT,
-      );
-      expect(run.code).toBe(1);
-      expect(run.stdout).toContain('count: 2');
-      expect(run.stdout).toMatch(/selector: Button\nstatus:\s+found/);
-      expect(run.stdout).toMatch(
-        /selector: ZzzNope99\nstatus:\s+not_found\ncode:\s+ERR_UNKNOWN_COMPONENT/,
-      );
-    },
-    SLOW,
-  );
-});