@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.ddb63c3

package/assets/codemods/transforms/next/__tests__/migrate-theme-catalog-to-descriptors.test.mjs

@@ -0,0 +1,216 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import manifest from '../index.mjs';
+import migrate from '../migrate-theme-catalog-to-descriptors.mjs';
+import {runCodemods} from '../../../runner.mjs';
+import {discoverThemeDirectory} from '../../../../../foundation/discovery/theme-discovery.mjs';
+
+let root;
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-theme-catalog-'));
+});
+
+afterEach(() => {
+  fs.rmSync(root, {recursive: true, force: true});
+});
+
+/** A catalog entry exactly as `astryx integration add theme <slug>` wrote it in 0.6. */
+function entry(slug, overrides = {}) {
+  const identifier = slug.replace(/-([a-z0-9])/gu, (_, c) => c.toUpperCase());
+  const displayName = slug
+    .split('-')
+    .map(part => part[0].toUpperCase() + part.slice(1))
+    .join(' ');
+  return {
+    slug,
+    displayName,
+    description: `${displayName} theme.`,
+    maintained: true,
+    entry: `${identifier}Theme.ts`,
+    exportName: `${identifier}Theme`,
+    files: [`${identifier}Theme.ts`],
+    ...overrides,
+  };
+}
+
+/** @param {ReturnType<typeof entry>[]} themes */
+function writeKit(themes, {sources = true} = {}) {
+  fs.writeFileSync(
+    path.join(root, 'package.json'),
+    '{"name":"@acme/kit","version":"1.0.0"}\n',
+  );
+  fs.writeFileSync(
+    path.join(root, 'astryx.integration.mjs'),
+    "export default {themes: './themes'};\n",
+  );
+  for (const theme of themes) {
+    const source = path.join(root, 'themes', theme.slug, theme.entry);
+    fs.mkdirSync(path.dirname(source), {recursive: true});
+    if (sources) {
+      fs.writeFileSync(
+        source,
+        `import {defineTheme} from '@astryxdesign/core/theme';\n\nexport const ${theme.exportName} = defineTheme({\n  name: '${theme.slug}',\n});\n`,
+      );
+    }
+  }
+  fs.mkdirSync(path.join(root, 'themes'), {recursive: true});
+  fs.writeFileSync(
+    path.join(root, 'themes', 'manifest.json'),
+    `${JSON.stringify({version: 1, themes}, null, 2)}\n`,
+  );
+}
+
+const catalog = () => path.join(root, 'themes', 'manifest.json');
+
+/** @param {boolean} apply @param {string} [srcPath] */
+const run = (apply, srcPath = root) =>
+  runCodemods([{version: 'next', transforms: manifest}], {
+    apply,
+    path: srcPath,
+    codemod: undefined,
+    silent: true,
+    root,
+  });
+
+describe('migrate-theme-catalog-to-descriptors', () => {
+  it('is staged for the next release as a project codemod', () => {
+    expect(manifest.map(t => [t.name, t.meta.codemodType])).toEqual([
+      ['migrate-theme-catalog-to-descriptors', 'project'],
+    ]);
+  });
+
+  it('writes one typed descriptor per catalog theme and removes the catalog', async () => {
+    writeKit([
+      entry('ocean'),
+      entry('deep-sea', {
+        displayName: "Deep 'Sea'",
+        description: 'Line one\nline two \\ done.',
+        maintained: false,
+      }),
+    ]);
+
+    const result = await run(true);
+
+    expect(result).toMatchObject({errors: [], totalFilesChanged: 3});
+    expect(fs.existsSync(catalog())).toBe(false);
+    expect(
+      fs.readFileSync(
+        path.join(root, 'themes/ocean/oceanTheme.doc.mjs'),
+        'utf-8',
+      ),
+    ).toBe(
+      "/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {\n  type: 'theme',\n  name: 'ocean',\n  displayName: 'Ocean',\n  description: 'Ocean theme.',\n  maintained: true,\n};\n",
+    );
+    const themes = discoverThemeDirectory(
+      path.join(root, 'themes'),
+      '@acme/kit',
+    );
+    expect(
+      themes.map(({slug, displayName, description, maintained}) => ({
+        slug,
+        displayName,
+        description,
+        maintained,
+      })),
+    ).toEqual([
+      {
+        slug: 'deep-sea',
+        displayName: "Deep 'Sea'",
+        description: 'Line one\nline two \\ done.',
+        maintained: false,
+      },
+      {
+        slug: 'ocean',
+        displayName: 'Ocean',
+        description: 'Ocean theme.',
+        maintained: true,
+      },
+    ]);
+  });
+
+  it('previews without writing, even with no source folder', async () => {
+    writeKit([entry('ocean')]);
+
+    const result = await run(false, path.join(root, 'src'));
+
+    expect(result).toMatchObject({
+      errors: [],
+      totalFilesChanged: 2,
+      writtenFiles: [],
+    });
+    expect(fs.existsSync(catalog())).toBe(true);
+    expect(
+      fs.existsSync(path.join(root, 'themes/ocean/oceanTheme.doc.mjs')),
+    ).toBe(false);
+  });
+
+  it('keeps a descriptor that already exists and still removes the catalog', async () => {
+    writeKit([entry('ocean'), entry('reef')]);
+    const kept = path.join(root, 'themes/ocean/oceanTheme.doc.mjs');
+    fs.writeFileSync(
+      kept,
+      "export default {type: 'theme', name: 'ocean', displayName: 'Mine', description: '', maintained: true};\n",
+    );
+
+    const result = await run(true);
+
+    expect(result.errors).toEqual([]);
+    expect(fs.readFileSync(kept, 'utf-8')).toContain("displayName: 'Mine'");
+    expect(
+      fs.existsSync(path.join(root, 'themes/reef/reefTheme.doc.mjs')),
+    ).toBe(true);
+    expect(fs.existsSync(catalog())).toBe(false);
+  });
+
+  it('changes nothing and names each entry that cannot convert', async () => {
+    writeKit([
+      entry('ocean'),
+      entry('sea', {exportName: 'oceanBlue'}),
+      entry('nested', {
+        entry: 'src/nestedTheme.ts',
+        files: ['src/nestedTheme.ts'],
+      }),
+    ]);
+    fs.rmSync(path.join(root, 'themes/ocean/oceanTheme.ts'));
+    const before = fs.readFileSync(catalog(), 'utf-8');
+
+    const result = await run(true);
+
+    expect(result.errors.map(e => [e.file, e.error])).toEqual([
+      ['themes/ocean', 'holds no oceanTheme.ts for theme "ocean".'],
+      [
+        'themes/manifest.json',
+        'theme "sea" exports "oceanBlue" from seaTheme.ts; a descriptor takes the export name from the file name, so rename the export or the file to match.',
+      ],
+      [
+        'themes/manifest.json',
+        'theme "nested" has entry "src/nestedTheme.ts"; a descriptor sits beside a .ts, .tsx, .mjs, or .js source directly in themes/nested/.',
+      ],
+    ]);
+    expect(fs.readFileSync(catalog(), 'utf-8')).toBe(before);
+    expect(fs.existsSync(path.join(root, 'themes/sea/seaTheme.doc.mjs'))).toBe(
+      false,
+    );
+  });
+
+  it('leaves a package with no catalog to convert alone', async () => {
+    const empty = {writes: [], deletes: [], problems: []};
+    await expect(migrate(root)).resolves.toEqual(empty);
+    fs.writeFileSync(
+      path.join(root, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+    await expect(migrate(root)).resolves.toEqual(empty);
+    fs.writeFileSync(
+      path.join(root, 'astryx.integration.mjs'),
+      "export default {themes: './themes'};\n",
+    );
+    fs.mkdirSync(path.join(root, 'themes'));
+    await expect(migrate(root)).resolves.toEqual(empty);
+  });
+});

package/assets/codemods/transforms/next/index.mjs

@@ -7,4 +7,14 @@
  * this file into the resolved version folder.
  */
 
-export default [];
+import migrateThemeCatalogToDescriptors, {
+  meta as migrateThemeCatalogToDescriptorsMeta,
+} from './migrate-theme-catalog-to-descriptors.mjs';
+
+export default [
+  {
+    name: 'migrate-theme-catalog-to-descriptors',
+    transform: migrateThemeCatalogToDescriptors,
+    meta: migrateThemeCatalogToDescriptorsMeta,
+  },
+];

package/assets/codemods/transforms/next/migrate-theme-catalog-to-descriptors.mjs

@@ -0,0 +1,141 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Give each integration theme a typed descriptor instead of the
+ *   `manifest.json` theme catalog.
+ *
+ * Astryx 0.6 scaffolded integration themes into one catalog,
+ * `<themes root>/manifest.json`. Each theme now carries a strongly typed
+ * same-stem `.doc.mjs` descriptor, and a themes root that still holds the
+ * catalog is refused. This project codemod reads the package's integration
+ * manifest, plans one descriptor per catalog entry beside that theme's source,
+ * and removes the catalog. When any entry cannot convert, it plans nothing and
+ * names the entry, so the package is never left half converted.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {loadManifestObject} from '../../../../foundation/integrations/integrations.mjs';
+import {findLocalIntegrationManifestOrNull} from '../../../../foundation/integrations/manifest-writer.mjs';
+import {themeDescriptorSource} from '../../../../foundation/integrations/theme-descriptor.mjs';
+
+export const meta = {
+  title:
+    'Give each integration theme a typed descriptor instead of the manifest.json catalog',
+  description:
+    'Writes <name>Theme.doc.mjs beside each theme the catalog lists, then removes the catalog.',
+  codemodType: 'project',
+};
+
+const SLUG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
+const SOURCE = /\.(?:ts|tsx|mjs|js)$/u;
+
+/**
+ * @param {string} root the package directory
+ * @returns {Promise<import('../../runner.mjs').ProjectCodemodPlan>}
+ */
+export default async function migrateThemeCatalogToDescriptors(root) {
+  /** @type {import('../../runner.mjs').ProjectCodemodPlan} */
+  const plan = {writes: [], deletes: [], problems: []};
+  /** @param {string} file @returns {string} */
+  const rel = file => path.relative(root, file).split(path.sep).join('/');
+  /** @param {string} file @param {string} message */
+  const problem = (file, message) => plan.problems.push({file, message});
+
+  const manifestFile = findLocalIntegrationManifestOrNull(root);
+  if (!manifestFile) return plan;
+  const manifest = await loadManifestObject(
+    manifestFile,
+    `Integration manifest ${path.basename(manifestFile)}`,
+    {fresh: true},
+  );
+  if (typeof manifest.themes !== 'string') return plan;
+  const themesRoot = path.resolve(root, manifest.themes);
+  const fromRoot = path.relative(root, themesRoot);
+  if (fromRoot.startsWith('..') || path.isAbsolute(fromRoot)) return plan;
+  const catalogFile = path.join(themesRoot, 'manifest.json');
+  if (!fs.existsSync(catalogFile)) return plan;
+  const catalogPath = rel(catalogFile);
+
+  let catalog;
+  try {
+    catalog = JSON.parse(fs.readFileSync(catalogFile, 'utf-8'));
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    problem(catalogPath, `is not valid JSON (${reason}).`);
+    return plan;
+  }
+  if (
+    !catalog ||
+    typeof catalog !== 'object' ||
+    catalog.version !== 1 ||
+    !Array.isArray(catalog.themes)
+  ) {
+    problem(catalogPath, 'is not a version 1 theme catalog.');
+    return plan;
+  }
+
+  for (const [index, entry] of catalog.themes.entries()) {
+    const slug = entry?.slug;
+    if (typeof slug !== 'string' || !SLUG.test(slug)) {
+      problem(
+        catalogPath,
+        `themes[${index}] has no lowercase kebab-case slug; fix the entry or add that theme's descriptor by hand.`,
+      );
+      continue;
+    }
+    const themeDir = path.join(themesRoot, slug);
+    const source = entry.entry;
+    if (
+      typeof source !== 'string' ||
+      !SOURCE.test(source) ||
+      source !== path.basename(source)
+    ) {
+      problem(
+        catalogPath,
+        `theme "${slug}" has entry ${JSON.stringify(source)}; a descriptor sits beside a .ts, .tsx, .mjs, or .js source directly in ${rel(themeDir)}/.`,
+      );
+      continue;
+    }
+    const stem = source.replace(SOURCE, '');
+    if (entry.exportName !== stem) {
+      problem(
+        catalogPath,
+        `theme "${slug}" exports ${JSON.stringify(entry.exportName)} from ${source}; a descriptor takes the export name from the file name, so rename the export or the file to match.`,
+      );
+      continue;
+    }
+    if (typeof entry.displayName !== 'string' || !entry.displayName.trim()) {
+      problem(catalogPath, `theme "${slug}" has no displayName.`);
+      continue;
+    }
+    if (typeof entry.description !== 'string') {
+      problem(catalogPath, `theme "${slug}" has no description string.`);
+      continue;
+    }
+    if (typeof entry.maintained !== 'boolean') {
+      problem(catalogPath, `theme "${slug}" has no maintained flag.`);
+      continue;
+    }
+    if (!fs.existsSync(path.join(themeDir, source))) {
+      problem(rel(themeDir), `holds no ${source} for theme "${slug}".`);
+      continue;
+    }
+    const descriptor = path.join(themeDir, `${stem}.doc.mjs`);
+    if (fs.existsSync(descriptor)) continue;
+    plan.writes.push({
+      path: descriptor,
+      contents: themeDescriptorSource({
+        type: 'theme',
+        name: slug,
+        displayName: entry.displayName,
+        description: entry.description,
+        maintained: entry.maintained,
+      }),
+    });
+  }
+  if (plan.problems.length > 0)
+    return {writes: [], deletes: [], problems: plan.problems};
+  plan.deletes.push(catalogFile);
+  return plan;
+}

package/assets/docs/cli-integrations.doc.mjs

@@ -84,7 +84,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'A useful theme package usually ships more than colors. Start with the source theme, author the palette request at `themes/ocean/palette.config.json`, then add the guides its consumers need. The `integration add` commands keep the package manifest in sync; add palette outputs to the theme catalog after generation.',
+          text: 'A useful theme package usually ships more than colors. Start with the source theme, author the palette request at `themes/ocean/palette.config.json`, then add the guides its consumers need. The `integration add` commands keep the package manifest in sync. Palette outputs live inside the theme directory, which ships as one unit, so there is nothing to register after generation.',
         },
         {
           type: 'code',
@@ -94,7 +94,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "Edit the generated theme and guide files before publishing. The shown palette command writes `themes/ocean/tokens/ocean.palette.ts` and its sibling `themes/ocean/tokens/ocean.palette.receipt.json`. The TypeScript candidate directly exports `black`, `white`, and `palette`; import what the theme uses from `./tokens/ocean.palette`. Keep the request at `themes/ocean/palette.config.json`, and list the theme source, request, candidate, and receipt in the catalog entry's `files` array. Add any optional wrapper, refs, icon, or preview modules only when you author them, and list each one too. `integration pack --check` runs the real package lifecycle and compares local discovery with the npm tarball, so a missing source file or files allowlist entry fails before a consumer sees it.",
+          text: 'Edit the generated theme descriptor, source, and guide files before publishing. The shown palette command writes `themes/ocean/tokens/ocean.palette.ts` and its sibling `themes/ocean/tokens/ocean.palette.receipt.json`, a reproducibility receipt. The TypeScript candidate directly exports `black`, `white`, and `palette`; import what the theme uses from `./tokens/ocean.palette`. Keep the request at `themes/ocean/palette.config.json`. The whole theme directory is copied and packed as one unit, so an optional wrapper, refs, icon, or preview module you add inside it ships with the theme. `integration pack --check` runs the real package lifecycle and compares local discovery with the npm tarball, so a missing source or descriptor fails before a consumer sees it.',
         },
         {
           type: 'code',
@@ -104,7 +104,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'The package must be a direct dependency for automatic discovery. No `astryx.config` entry is needed unless the app must control integration order. `theme add` copies every file listed by the selected catalog entry, including nested token modules, and refuses to overwrite existing project files.',
+          text: "The package must be a direct dependency for automatic discovery. No `astryx.config` entry is needed unless the app must control integration order. `theme add` copies the selected theme's complete directory, including its typed `.doc.mjs`, nested token modules, and receipts, and refuses to overwrite existing project files.",
         },
       ],
     },
@@ -119,7 +119,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'text',
-          code: "Kind        Metadata suffix            type stamp     Source file\n────────    ─────────────────────────  ─────────────  ──────────────────────\nComponent   Name.doc.{ts,mjs,js}       'component'    Name.tsx (same stem)\nTemplate    Name.template.{ts,mjs,js}  'page'/'block' Name.tsx (same stem)\nDoc topic   topic.doc.{ts,mjs,js}      'generic'      (none — docs are prose)\nCodemod     <version>/<id>.{ts,mjs,js} 'code'/'config' (the codemod IS the source)\nTheme       manifest.json entry         —             <slug>/<entry>.ts",
+          code: "Kind        Metadata file              type stamp     Source file\n────────    ─────────────────────────  ─────────────  ──────────────────────\nComponent   Name.doc.mjs               'component'    Name.tsx (same stem)\nTemplate    Name.doc.mjs               'page'/'block' Name.tsx (same stem)\nDoc topic   topic.doc.mjs              'generic'      (none — docs are prose)\nCodemod     <version>/<id>.{ts,mjs,js} 'code'/'config' (the codemod IS the source)\nTheme       <slug>/nameTheme.doc.mjs   'theme'        <slug>/nameTheme.ts (same stem)\n\nReleased .doc.js files, template .doc.ts files, and .template.{ts,mjs,js}\ntemplates still load. A component or topic .doc.ts loads only from a package\nlinked from outside node_modules; installed, it is listed but cannot be read.",
         },
         {
           type: 'prose',
@@ -152,7 +152,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "Export your components from your library however you like, and consumers still import them from your package. For each component the CLI should document, ship a `.doc.{ts,mjs,js}` file with the same stem, for example `AcmeCarousel.tsx` alongside `AcmeCarousel.doc.ts`. The doc file must default-export an object with `type: 'component'` — not `'generic'` (that is for reference docs) and not `'page'`/`'block'` (those are for templates).",
+          text: "Export your components from your library however you like, and consumers still import them from your package. For each component the CLI should document, ship a strongly typed `.doc.mjs` file with the same stem, for example `AcmeCarousel.tsx` alongside `AcmeCarousel.doc.mjs`. The doc file must default-export an object with `type: 'component'` — not `'generic'` (that is for reference docs) and not `'page'`/`'block'` (those are for templates). Released `.doc.js` docs remain readable for compatibility. A `.doc.ts` component doc reads only when the package is linked from outside node_modules, not once it is installed. New authoring uses `.doc.mjs`.",
         },
         {
           type: 'prose',
@@ -161,7 +161,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'typescript',
-          code: "// AcmeCarousel.doc.ts\nexport default {\n  type: 'component',\n  name: 'AcmeCarousel',\n  description: 'A carousel that cycles through slides.',\n  // props, usage, examples, ...\n} satisfies import('@astryxdesign/cli/authoring').ComponentDoc;",
+          code: "// AcmeCarousel.doc.mjs\n/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */\nexport default {\n  type: 'component',\n  name: 'AcmeCarousel',\n  displayName: 'Acme Carousel',\n  usage: {description: 'A carousel that cycles through slides.'},\n  props: [],\n};",
         },
       ],
     },
@@ -171,7 +171,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "Templates are usually not exported from the package directly. Instead, consumers browse them through the CLI and materialize them into their app. Define a template as a plain object with `type: 'page'` (full pages) or `type: 'block'` (smaller chunks) as its default export in a `.template.{ts,mjs,js}` file next to the source, for example `AcmeLandingPage.tsx` and `AcmeLandingPage.template.ts`. Do not use the `.doc.{ts,mjs,js}` suffix — that is for component docs and reference docs.",
+          text: "Templates are usually not exported from the package directly. Instead, consumers browse them through the CLI and materialize them into their app. Define a template as a strongly typed plain object stamped with `type: 'page'` (full pages) or `type: 'block'` (smaller chunks) in a same-stem `.doc.mjs`, for example `AcmeLandingPage.tsx` and `AcmeLandingPage.doc.mjs`. Released `.template.*` files remain readable for compatibility.",
         },
         {
           type: 'prose',
@@ -180,7 +180,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'typescript',
-          code: "// AcmeLandingPage.template.ts\nexport default {\n  type: 'page',\n  // name, description, preview, ...\n};",
+          code: "// AcmeLandingPage.doc.mjs\n/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */\nexport default {\n  type: 'page',\n  name: 'acme-landing-page',\n  displayName: 'Acme Landing Page',\n  description: 'A complete product landing page.',\n};",
         },
         {
           type: 'prose',
@@ -194,12 +194,12 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "Point the integration file's `docs` field at a directory of reference docs and every `{topic}.doc.{ts,mjs,js}` under it becomes a topic the CLI serves: `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object with `type: 'generic'` as its default export — not `'component'` (that is for component docs with a same-stem source file). This is the same shape core's own topics use.",
+          text: "Point the integration file's `docs` field at a directory of reference docs and every strongly typed `{topic}.doc.mjs` under it becomes a topic the CLI serves: `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object stamped `type: 'generic'` — not `'component'` (that is for component docs with a same-stem source file) — the same shape core's own topics use.",
         },
         {
           type: 'code',
           lang: 'typescript',
-          code: "// docs/deploying.doc.ts\nexport default {\n  type: 'generic',\n  name: 'deploying',\n  title: 'Deploying',\n  description: 'Ship an app built with Acme widgets.',\n  category: 'guide',\n  sections: [\n    {title: 'Overview', content: [{type: 'prose', text: '...'}]},\n  ],\n};",
+          code: "// docs/deploying.doc.mjs\n/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */\nexport default {\n  type: 'generic',\n  name: 'deploying',\n  title: 'Deploying',\n  description: 'Ship an app built with Acme widgets.',\n  category: 'guide',\n  sections: [\n    {title: 'Overview', content: [{type: 'prose', text: '...'}]},\n  ],\n};",
         },
         {
           type: 'prose',
@@ -212,7 +212,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "`extends: 'x'` merges onto a topic instead of owning it: a section with the same key as one in the base (its `id`, or the key its title derives) or the same title replaces that section, and a section the base does not have is appended. Reach for it to correct or add to a topic you do not want to fork: a fork of someone else's guide stops receiving their fixes the day you write it.",
+          text: "`extends: 'x'` merges onto a topic instead of owning it: a section with the same key as one in the base (its `id`, or the key its title derives) or the same title replaces that section, and a section the base does not have is appended. The topic keeps its own title and description; only `replaces` renames it. Reach for it to correct or add to a topic you do not want to fork: a fork of someone else's guide stops receiving their fixes the day you write it.",
         },
         {
           type: 'list',
@@ -233,38 +233,25 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "A theme contribution is editable `defineTheme` source, not compiled CSS. Add `themes: './themes'` to `astryx.integration.*`, place the source under one directory per slug, and list it in `themes/manifest.json`. If package.json has a `files` allowlist, include both the integration manifest and the themes root; packages with no allowlist already publish both. Do not add an `exports` map only for theme discovery.",
+          text: "A theme contribution is editable `defineTheme` source, not compiled CSS. Add `themes: './themes'` to `astryx.integration.*`. Give each lower-kebab slug its own directory containing a theme source and mandatory same-stem, strongly typed `.doc.mjs`. If package.json has a `files` allowlist, include both the integration manifest and the themes root; packages with no allowlist already publish both. Do not add an `exports` map only for theme discovery.",
         },
         {
           type: 'code',
           lang: 'text',
-          code: 'themes/\n  manifest.json\n  ocean/\n    oceanTheme.ts\n    palette.config.json\n    tokens/\n      ocean.palette.ts\n      ocean.palette.receipt.json',
+          code: 'themes/\n  ocean/\n    oceanTheme.ts\n    oceanTheme.doc.mjs\n    palette.config.json\n    tokens/\n      ocean.palette.ts\n      ocean.palette.receipt.json',
         },
         {
           type: 'prose',
-          text: 'The root catalog `manifest.json` must be `{ "version": 1, "themes": [...] }`. Each entry in the `themes` array requires every field shown below — omitting any one is a hard validation error:',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            '`slug` — lowercase kebab-case starting with a letter (e.g. `"ocean"`). Must be unique within the catalog.',
-            '`displayName` — human-readable label (e.g. `"Ocean"`).',
-            '`description` — string description of the theme.',
-            '`maintained` — boolean indicating active maintenance.',
-            '`entry` — source file relative to `themes/<slug>/` (e.g. `"oceanTheme.ts"`).',
-            '`exportName` — a valid JS identifier naming the runtime export in the entry file (e.g. `"oceanTheme"`). Astryx parses the source without executing it and rejects missing or type-only exports.',
-            '`files` — non-empty array of filenames relative to `themes/<slug>/`. Must include the entry file and every local static import the entry source uses. Astryx validates that every listed file exists on disk and that every local import in the entry names a file in this list.',
-          ],
+          text: '`ThemeDoc` owns `name` (the slug), `displayName`, `description`, and `maintained`. The descriptor/source stem supplies the source entry and required named runtime export. Astryx parses the source without executing it, confines every local static import and re-export to the theme directory, copies that complete directory, and rejects missing or type-only exports.',
         },
         {
           type: 'code',
-          lang: 'json',
-          code: '{\n  "version": 1,\n  "themes": [{\n    "slug": "ocean",\n    "displayName": "Ocean",\n    "description": "Ocean theme with OKLCH palettes.",\n    "maintained": true,\n    "entry": "oceanTheme.ts",\n    "exportName": "oceanTheme",\n    "files": [\n      "oceanTheme.ts",\n      "palette.config.json",\n      "tokens/ocean.palette.ts",\n      "tokens/ocean.palette.receipt.json"\n    ]\n  }]\n}',
+          lang: 'javascript',
+          code: "/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {\n  type: 'theme',\n  name: 'ocean',\n  displayName: 'Ocean',\n  description: 'Ocean theme.',\n  maintained: true,\n};",
         },
         {
           type: 'prose',
-          text: 'The generated candidate is already importable: it exports `black`, `white`, `palette`, and a default palette value. Import it directly from `./tokens/ocean.palette`. A wrapper or palette-refs module is optional application code, not generator output; list it only if you create it.',
+          text: 'The generated palette candidate is already importable: it exports `black`, `white`, `palette`, and a default palette value. Import it directly from `./tokens/ocean.palette`. A wrapper or palette-refs module is optional application code, not generator output.',
         },
         {
           type: 'prose',

package/assets/docs/cli.doc.mjs

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli`: every command, API function, output schema, and
+ * enum the CLI documents, one section each.
+ *
+ * Built from the docs whose `namespace` is `cli/commands` or `cli/api`, so it
+ * cannot drift from the commands and functions it describes. `astryx doctor`
+ * names a CLI doc with no namespace, or one no topic reads.
+ */
+
+import {buildCliTopic} from '../../foundation/discovery/cli-self-docs.mjs';
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = await buildCliTopic();

package/assets/docs/theme.doc.mjs

@@ -152,7 +152,7 @@ function App() {
         },
         {
           type: 'prose',
-          text: 'The copy is editable project source, not a reference back into node_modules. Every file named by the theme catalog comes with it, including nested token or palette modules. A second add refuses to overwrite those files unless you pass `--overwrite`.',
+          text: 'The copy is editable project source, not a reference back into node_modules. The complete theme directory comes with it, including its typed `.doc.mjs`, nested token and palette modules, and receipts. A second add refuses to overwrite those files unless you pass `--overwrite`.',
         },
       ],
     },

package/assets/templates/themes/butter/butterTheme.doc.mjs

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'butter',
+  displayName: 'Butter',
+  description:
+    'Warm, creamy yellows with a friendly blue accent. Playful enough for consumer surfaces, soft enough to stay readable.',
+  maintained: false,
+};

package/assets/templates/themes/chocolate/chocolateTheme.doc.mjs

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'chocolate',
+  displayName: 'Chocolate',
+  description:
+    'Warm chocolate theme for Astryx — rich brown palette with Fraunces headings, Albert Sans body, and Lucide icons',
+  maintained: false,
+};

package/assets/templates/themes/gothic/gothicTheme.doc.mjs

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'gothic',
+  displayName: 'Gothic',
+  description:
+    'Deep blue-grays and a signature display serif. Dramatic and editorial, for surfaces that want to be remembered.',
+  maintained: false,
+};

package/assets/templates/themes/matcha/matchaTheme.doc.mjs

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'matcha',
+  displayName: 'Matcha',
+  description:
+    'Earthy greens with a calm, organic feel. Naturalistic and grounded, great for wellness or content-first apps.',
+  maintained: false,
+};

package/assets/templates/themes/neutral/neutralTheme.doc.mjs

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'neutral',
+  displayName: 'Neutral',
+  description:
+    'Restrained warm grays. Minimal and quiet, so the content stays the focus.',
+  maintained: true,
+};

package/assets/templates/themes/stone/stoneTheme.doc.mjs

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'stone',
+  displayName: 'Stone',
+  description:
+    'Warm stone and slate, earthy and understated, with just enough character to feel handcrafted.',
+  maintained: false,
+};

package/assets/templates/themes/y2k/y2kTheme.doc.mjs

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'y2k',
+  displayName: 'Y2K',
+  description:
+    'Hot pinks, lime greens, and Poppins. Bubbly, playful, and unmistakably retro.',
+  maintained: false,
+};

package/authoring/codemod/codemod.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'schema',
   name: 'codemod',
   displayName: 'Astryx Codemod',
-  namespace: 'cli',
+  namespace: 'authoring',
   description:
     'A codemod module the CLI runs during `astryx upgrade`. Default-export a ' +
     "plain object with a `type` discriminant: 'code' rewrites source files, " +