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

package/api/template/template-suffix.test.mjs

@@ -1,25 +1,20 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file The canonical `.template.{ts,mjs,js}` suffix is discovered identically
- * to the legacy `.doc.{ts,mjs,js}` suffix.
+ * @file The canonical `.doc.{mjs,ts,js}` suffix is discovered identically
+ * to the released `.template.{ts,mjs,js}` compatibility suffix.
  *
- * Template-spec files are named for what they are: a scaffoldable TEMPLATE
- * stamped with `type: 'page' | 'block'`. The `.doc.*` suffix was
- * inherited from the component-doc convention and is still accepted during the
- * transition. These tests stand up integration templates and external blocks in
- * both families and assert byte-for-byte-equivalent discovery + scaffolding.
+ * New authoring writes `.doc.mjs`, the canonical typed descriptor. Stable
+ * 0.6.0 already accepted `.template.*`, so these tests
+ * keep that family as a compatibility input and assert equivalent discovery +
+ * scaffolding.
  */
 
 import {afterEach, beforeEach, describe, expect, it} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {
-  template,
-  findShowcase,
-  findRelatedBlocks,
-} from './template.mjs';
+import {template, findShowcase, findRelatedBlocks} from './template.mjs';
 
 let tmpDir;
 let originalCwd;
@@ -82,8 +77,8 @@ afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});
 });
 
-describe('integration templates: .template.* discovered like legacy .doc.*', () => {
-  for (const suffix of ['.template.ts', '.template.mjs', '.doc.mjs']) {
+describe('integration templates: canonical .doc.* plus released .template.* compatibility', () => {
+  for (const suffix of ['.doc.mjs', '.doc.ts', '.template.mjs']) {
     it(`discovers + lists a page template authored as ${suffix}`, async () => {
       const pkgDir = installWidgets(tmpDir);
       writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix});
@@ -124,7 +119,7 @@ describe('integration templates: .template.* discovered like legacy .doc.*', ()
     });
   }
 
-  it('treats a .template.ts and a legacy .doc.mjs identically (same shape)', async () => {
+  it('treats canonical .doc.mjs and released .template.ts identically (same shape)', async () => {
     const pkgDir = installWidgets(tmpDir);
     writeTemplate(pkgDir, 'gauge', {kind: 'block', suffix: '.template.ts'});
     writeTemplate(pkgDir, 'chip', {kind: 'block', suffix: '.doc.mjs'});
@@ -143,12 +138,33 @@ describe('integration templates: .template.* discovered like legacy .doc.*', ()
     expect(gauge.type).toBe(chip.type);
     expect(gauge.package).toBe(chip.package);
   });
+  it('lists both same-stem specs and reads the id as ambiguous', async () => {
+    for (const [first, second] of [
+      ['.doc.mjs', '.template.ts'],
+      ['.doc.ts', '.doc.mjs'],
+    ]) {
+      const pkgDir = installWidgets(tmpDir);
+      fs.rmSync(path.join(pkgDir, 'templates'), {recursive: true, force: true});
+      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix: first});
+      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix: second});
+
+      const result = await template(undefined, {list: true, cwd: tmpDir});
+      expect(
+        result.data.filter(entry => entry.id === 'pricing'),
+        `${first} + ${second}`,
+      ).toHaveLength(2);
+      await expect(
+        template('pricing', {cwd: tmpDir}),
+        `${first} + ${second}`,
+      ).rejects.toMatchObject({code: 'ERR_AMBIGUOUS_TEMPLATE'});
+    }
+  });
 });
 
-describe('external showcase blocks: .template.* discovered like legacy .doc.*', () => {
+describe('external showcase blocks: canonical .doc.* plus released .template.* compatibility', () => {
   /**
    * Create a consumer whose @test/ext package contributes two showcase blocks,
-   * one authored as `Foo.template.ts` and one as legacy `Bar.doc.mjs`.
+   * one authored with released `Foo.template.ts` and one with canonical `Bar.doc.mjs`.
    */
   function makeShowcaseFixture() {
     // Symlink the real core package (needed by findCoreDir during discovery).
@@ -166,7 +182,7 @@ describe('external showcase blocks: .template.* discovered like legacy .doc.*',
     const extDir = path.join(tmpDir, 'node_modules', '@test', 'ext');
     const blocksDir = path.join(extDir, 'blocks', 'components');
 
-    // Foo showcase — canonical .template.ts (stamped type: 'block' default export).
+    // Foo showcase — released .template.ts compatibility input.
     const fooDir = path.join(blocksDir, 'Foo');
     fs.mkdirSync(fooDir, {recursive: true});
     fs.writeFileSync(
@@ -185,7 +201,7 @@ describe('external showcase blocks: .template.* discovered like legacy .doc.*',
       "'use client';\nexport default function FooShowcase() { return <div>Foo</div>; }",
     );
 
-    // Bar showcase — legacy .doc.mjs (export const doc).
+    // Bar showcase — canonical .doc.mjs (historical named export).
     const barDir = path.join(blocksDir, 'Bar');
     fs.mkdirSync(barDir, {recursive: true});
     fs.writeFileSync(
@@ -209,7 +225,11 @@ describe('external showcase blocks: .template.* discovered like legacy .doc.*',
       path.join(extDir, 'package.json'),
       JSON.stringify({
         name: '@test/ext',
-        astryx: {docs: './src', category: 'Common', blocks: './blocks/components'},
+        astryx: {
+          docs: './src',
+          category: 'Common',
+          blocks: './blocks/components',
+        },
       }),
     );
     fs.mkdirSync(path.join(extDir, 'src'), {recursive: true});
@@ -223,7 +243,7 @@ describe('external showcase blocks: .template.* discovered like legacy .doc.*',
     expect(result.filePath).toContain('FooShowcase.tsx');
   });
 
-  it('findShowcase resolves a legacy .doc.mjs external block by componentsUsed', async () => {
+  it('findShowcase resolves a canonical .doc.mjs external block by componentsUsed', async () => {
     makeShowcaseFixture();
     const result = await findShowcase('Bar', tmpDir);
     expect(result).not.toBeNull();

package/api/template/template.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'template',
+  namespace: 'cli/api',
   displayName: 'template()',
   summary: 'List, inspect, or scaffold page and block templates.',
   description:

package/api/theme/_adapter.d.mts

@@ -13,7 +13,7 @@
 export function listThemes(): BundledTheme[];
 /**
  * Bundled themes plus source themes from integrations installed in `cwd`.
- * A project/config load failure degrades to the bundled catalog, preserving the
+ * A project/config load failure degrades to the bundled set, preserving the
  * command's historical usefulness outside a configured project.
  * @param {string} [cwd]
  * @returns {Promise<import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme[]>}
@@ -35,6 +35,5 @@ export function findTheme(slug?: string, options?: {
  */
 export type BundledTheme = Pick<import("../../foundation/discovery/theme-discovery.mjs").DiscoveredTheme, "slug" | "displayName" | "description" | "maintained" | "entry" | "exportName" | "files">;
 import { BUNDLED_THEME_PACKAGE } from '../../foundation/discovery/theme-discovery.mjs';
-import { MANIFEST_PATH } from '../../foundation/discovery/theme-discovery.mjs';
 import { THEMES_DIR } from '../../foundation/discovery/theme-discovery.mjs';
-export { BUNDLED_THEME_PACKAGE, MANIFEST_PATH, THEMES_DIR };
+export { BUNDLED_THEME_PACKAGE, THEMES_DIR };

package/api/theme/_adapter.mjs

@@ -5,20 +5,19 @@
  *
  * `listThemes()` intentionally keeps its historical synchronous, bundled-only
  * contract. Project-aware callers use `listAvailableThemes()`, which asks
- * Project for the bundled catalog plus every installed integration catalog.
+ * Project for the bundled themes plus every installed integration theme root.
  */
 
 import {Project} from '../../foundation/config/project.mjs';
 import {
   BUNDLED_THEME_PACKAGE,
-  MANIFEST_PATH,
   THEMES_DIR,
   discoverBundledThemes,
 } from '../../foundation/discovery/theme-discovery.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
-export {BUNDLED_THEME_PACKAGE, MANIFEST_PATH, THEMES_DIR};
+export {BUNDLED_THEME_PACKAGE, THEMES_DIR};
 
 /**
  * A bundled theme entry kept for the historical public `listThemes()` helper.
@@ -55,7 +54,7 @@ function availableBundledThemes() {
 /**
  * Load available themes with any package-owned integration issues found while
  * discovering them. The issue set lets a package-scoped lookup distinguish an
- * absent theme from an installed package whose catalog is broken.
+ * absent theme from an installed package whose theme descriptors are broken.
  * @param {string} cwd
  * @returns {Promise<{themes: import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme[], issues: Array<import('../../foundation/integrations/issue').AstryxIntegrationIssue & {package: string}>}>}
  */
@@ -71,7 +70,7 @@ async function availableThemeState(cwd) {
 
 /**
  * Bundled themes plus source themes from integrations installed in `cwd`.
- * A project/config load failure degrades to the bundled catalog, preserving the
+ * A project/config load failure degrades to the bundled set, preserving the
  * command's historical usefulness outside a configured project.
  * @param {string} [cwd]
  * @returns {Promise<import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme[]>}

package/api/theme/add/add.binary.test.mjs

@@ -37,21 +37,10 @@ beforeEach(() => {
     "export default {themes: './themes'};\n",
   );
   fs.writeFileSync(
-    path.join(packageDir, 'themes', 'manifest.json'),
-    JSON.stringify({
-      version: 1,
-      themes: [
-        {
-          slug: 'ocean',
-          displayName: 'Ocean',
-          description: 'Integration theme that ships a font.',
-          maintained: true,
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts', 'fonts/ocean.woff2'],
-        },
-      ],
-    }),
+    path.join(themeDir, 'oceanTheme.doc.mjs'),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {type: 'theme', name: 'ocean', displayName: 'Ocean', description: 'Integration theme that ships a font.', maintained: true};
+`,
   );
   fs.writeFileSync(
     path.join(themeDir, 'oceanTheme.ts'),
@@ -64,14 +53,18 @@ afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});
 });
 
-describe('themeAdd copies every listed file', () => {
+describe('themeAdd copies every file of the theme', () => {
   it('copies a binary file byte for byte', async () => {
     const result = await themeAdd('ocean', {
       cwd: tmpDir,
       package: '@acme/themes',
     });
 
-    expect(result.data.files).toEqual(['oceanTheme.ts', 'fonts/ocean.woff2']);
+    expect(result.data.files).toEqual([
+      'oceanTheme.ts',
+      'fonts/ocean.woff2',
+      'oceanTheme.doc.mjs',
+    ]);
     const copied = fs.readFileSync(
       path.join(tmpDir, 'src', 'themes', 'ocean', 'fonts', 'ocean.woff2'),
     );

package/api/theme/add/add.test.mjs

@@ -30,7 +30,20 @@ describe('themeAdd (api/theme/add)', () => {
     expect(result.data.slug).toBe('neutral');
     expect(result.data.package).toBe('@astryxdesign/cli');
     expect(result.data.outputDir).toBe(path.join('src', 'themes', 'neutral'));
-    expect(result.data.files.length).toBeGreaterThan(0);
+    // Exactly what the bundle has always copied, in that order: the CLI's own
+    // descriptor stays behind.
+    expect(result.data.files).toEqual([
+      'neutralTheme.ts',
+      'icons.tsx',
+      'neutralPalettes.ts',
+      'neutralPalettes.generated.ts',
+      'neutralPaletteRefs.generated.ts',
+      'neutralPalettes.generated.receipt.json',
+      'palette.config.json',
+    ]);
+    expect(
+      fs.readdirSync(path.join(tmpDir, 'src', 'themes', 'neutral')).sort(),
+    ).toEqual([...result.data.files].sort());
     for (const f of result.data.files) {
       expect(
         fs.existsSync(path.join(tmpDir, 'src', 'themes', 'neutral', f)),

package/api/theme/generateTonalPalette.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'generateTonalPalette',
+  namespace: 'cli/api',
   displayName: 'generateTonalPalette()',
   summary: 'Generate candidate tonal palette data without filesystem effects.',
   description:

package/api/theme/integration-themes.test.mjs

@@ -7,18 +7,14 @@ import {themeAdd} from './add/add.mjs';
 
 let tmpDir;
 
-function installThemeIntegration(
-  packageName,
-  slug,
-  source = 'export const oceanTheme = {};\n',
-  extraFiles = {},
-) {
+function installThemeIntegration(packageName, slug, source, extraFiles = {}) {
   const packageDir = path.join(
     tmpDir,
     'node_modules',
     ...packageName.split('/'),
   );
   const themeDir = path.join(packageDir, 'themes', slug);
+  const stem = `${slug.replace(/-([a-z0-9])/gu, (_, character) => character.toUpperCase())}Theme`;
   fs.mkdirSync(themeDir, {recursive: true});
   fs.writeFileSync(
     path.join(packageDir, 'package.json'),
@@ -26,26 +22,21 @@ function installThemeIntegration(
   );
   fs.writeFileSync(
     path.join(packageDir, 'astryx.integration.mjs'),
-    `export default {themes: './themes'};\n`,
+    `export default {themes: './themes'};
+`,
   );
   fs.writeFileSync(
-    path.join(packageDir, 'themes', 'manifest.json'),
-    JSON.stringify({
-      version: 1,
-      themes: [
-        {
-          slug,
-          displayName: slug === 'neutral' ? 'Neutral Plus' : 'Ocean',
-          description: 'Integration-owned theme.',
-          maintained: true,
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts', ...Object.keys(extraFiles)],
-        },
-      ],
-    }),
+    path.join(themeDir, `${stem}.doc.mjs`),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {type: 'theme', name: '${slug}', displayName: '${slug === 'neutral' ? 'Neutral Plus' : 'Ocean'}', description: 'Integration-owned theme.', maintained: true};
+`,
+  );
+  fs.writeFileSync(
+    path.join(themeDir, `${stem}.ts`),
+    source ??
+      `export const ${stem} = {};
+`,
   );
-  fs.writeFileSync(path.join(themeDir, 'oceanTheme.ts'), source);
   for (const [relativePath, contents] of Object.entries(extraFiles)) {
     const file = path.join(themeDir, relativePath);
     fs.mkdirSync(path.dirname(file), {recursive: true});
@@ -85,23 +76,43 @@ describe('themeAdd with integration themes', () => {
     ).toContain('oceanTheme');
   });
 
-  it('copies nested files listed by an integration theme catalog', async () => {
+  it('copies the complete nested integration theme directory', async () => {
     installThemeIntegration(
       '@acme/themes',
       'ocean',
       "import {oceanBlue} from './tokens/colors';\nexport const oceanTheme = {oceanBlue};\n",
-      {'tokens/colors.ts': "export const oceanBlue = '#0064e0';\n"},
+      {
+        'tokens/colors.ts': "export const oceanBlue = '#0064e0';\n",
+        'receipts/palette.json': '{"version":1}\n',
+      },
     );
 
     const result = await themeAdd('ocean', {cwd: tmpDir});
 
-    expect(result.data.files).toEqual(['oceanTheme.ts', 'tokens/colors.ts']);
+    expect(result.data.files).toEqual([
+      'oceanTheme.ts',
+      'oceanTheme.doc.mjs',
+      'receipts/palette.json',
+      'tokens/colors.ts',
+    ]);
+    expect(
+      fs.readFileSync(
+        path.join(tmpDir, 'src', 'themes', 'ocean', 'oceanTheme.doc.mjs'),
+        'utf-8',
+      ),
+    ).toContain("type: 'theme'");
     expect(
       fs.readFileSync(
         path.join(tmpDir, 'src', 'themes', 'ocean', 'tokens', 'colors.ts'),
         'utf-8',
       ),
     ).toContain('oceanBlue');
+    expect(
+      fs.readFileSync(
+        path.join(tmpDir, 'src', 'themes', 'ocean', 'receipts', 'palette.json'),
+        'utf-8',
+      ),
+    ).toBe('{"version":1}\n');
   });
 
   it('rejects a nested destination symlink that escapes the project', async () => {
@@ -146,7 +157,7 @@ describe('themeAdd with integration themes', () => {
     expect(result.data.package).toBe('@acme/themes');
   });
 
-  it('reports a selected installed package with a corrupted theme catalog', async () => {
+  it('reports a selected installed package with a corrupted theme directory', async () => {
     installThemeIntegration(
       '@acme/themes',
       'ocean',
@@ -170,7 +181,7 @@ describe('themeAdd with integration themes', () => {
       themeAdd('ocean', {cwd: tmpDir, package: '@acme/themes'}),
     ).rejects.toMatchObject({
       code: 'ERR_THEME_INVALID',
-      message: expect.stringContaining('tokens/colors.ts'),
+      message: expect.stringContaining('./tokens/colors'),
     });
   });
 

package/api/theme/list/list.test.mjs

@@ -9,8 +9,13 @@ import {BUNDLED_THEME_PACKAGE} from '../../../foundation/discovery/theme-discove
 let tmpDir;
 
 function installThemeIntegration(packageName = '@acme/themes', slug = 'ocean') {
-  const packageDir = path.join(tmpDir, 'node_modules', ...packageName.split('/'));
+  const packageDir = path.join(
+    tmpDir,
+    'node_modules',
+    ...packageName.split('/'),
+  );
   const themeDir = path.join(packageDir, 'themes', slug);
+  const stem = `${slug.replace(/-([a-z0-9])/gu, (_, character) => character.toUpperCase())}Theme`;
   fs.mkdirSync(themeDir, {recursive: true});
   fs.writeFileSync(
     path.join(packageDir, 'package.json'),
@@ -18,28 +23,19 @@ function installThemeIntegration(packageName = '@acme/themes', slug = 'ocean') {
   );
   fs.writeFileSync(
     path.join(packageDir, 'astryx.integration.mjs'),
-    `export default {themes: './themes'};\n`,
+    `export default {themes: './themes'};
+`,
   );
   fs.writeFileSync(
-    path.join(packageDir, 'themes', 'manifest.json'),
-    JSON.stringify({
-      version: 1,
-      themes: [
-        {
-          slug,
-          displayName: 'Ocean',
-          description: 'Blue and calm.',
-          maintained: true,
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts'],
-        },
-      ],
-    }),
+    path.join(themeDir, `${stem}.doc.mjs`),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {type: 'theme', name: '${slug}', displayName: 'Ocean', description: 'Blue and calm.', maintained: true};
+`,
   );
   fs.writeFileSync(
-    path.join(themeDir, 'oceanTheme.ts'),
-    'export const oceanTheme = {};\n',
+    path.join(themeDir, `${stem}.ts`),
+    `export const ${stem} = {};
+`,
   );
 }
 
@@ -47,7 +43,10 @@ beforeEach(() => {
   tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-theme-list-'));
   fs.writeFileSync(
     path.join(tmpDir, 'package.json'),
-    JSON.stringify({name: 'consumer', dependencies: {'@acme/themes': '^1.0.0'}}),
+    JSON.stringify({
+      name: 'consumer',
+      dependencies: {'@acme/themes': '^1.0.0'},
+    }),
   );
 });
 

package/api/theme/listThemes.doc.mjs

@@ -9,25 +9,26 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'listThemes',
+  namespace: 'cli/api',
   displayName: 'listThemes()',
-  summary: 'Read the CLI bundled-theme manifest.',
+  summary: 'Read the CLI bundled-theme descriptors.',
   description:
-    'Reads templates/themes/manifest.json and returns its raw entries synchronously. This low-level helper keeps its historical bundled-only contract; project-aware themeList() and themeAdd() also discover source themes from installed integrations.',
+    'Reads the typed same-stem descriptors under templates/themes and returns normalized entries synchronously. This low-level helper keeps its historical bundled-only contract; project-aware themeList() and themeAdd() also discover source themes from installed integrations.',
   importPath: '@astryxdesign/cli/api',
   signature: 'listThemes(): BundledTheme[]',
-  keywords: ['theme', 'themes', 'manifest', 'bundled', 'adapter', 'list'],
+  keywords: ['theme', 'themes', 'descriptor', 'bundled', 'adapter', 'list'],
   params: [],
   returns: [
     {
       type: 'BundledTheme[]',
       description:
-        'The bundled manifest entries: slug, displayName, description, maintained, entry, exportName, and files.',
+        'The normalized bundled descriptor entries: slug, displayName, description, maintained, entry, exportName, and files.',
     },
   ],
   throws: [
     {
       code: 'ERR_NO_SOURCE',
-      when: 'the bundled catalog is missing, invalid, or references missing source files',
+      when: 'the bundled descriptors are missing, invalid, or have missing source files',
     },
   ],
   examples: [

package/api/theme/themeAdd.doc.mjs

@@ -9,10 +9,11 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'themeAdd',
+  namespace: 'cli/api',
   displayName: 'themeAdd()',
   summary: 'Copy an available theme into a project as editable source.',
   description:
-    'Resolves a theme from the CLI bundle or an installed integration and copies every catalog-listed source file into the consumer project. Writes are staged and existing files require explicit overwrite. Duplicate slugs fail closed until the caller selects an owner package.',
+    "Resolves a theme from the CLI bundle or an installed integration and copies it into the consumer project: a bundled theme's source files, or an integration theme's complete directory with its descriptor. Writes are staged and existing files require explicit overwrite. Duplicate slugs fail closed until the caller selects an owner package.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'themeAdd(slug: string, options?: {targetPath?: string, overwrite?: boolean, cwd?: string, package?: string}): Promise<ThemeAddResponse>',
@@ -70,10 +71,10 @@ export const doc = {
     {code: 'ERR_AMBIGUOUS_THEME', when: 'more than one package owns the slug'},
     {
       code: 'ERR_THEME_INVALID',
-      when: 'the selected installed package has a blocking integration or theme-catalog error',
+      when: 'the selected installed package has a blocking integration or theme-descriptor error',
     },
     {code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'},
-    {code: 'ERR_NO_SOURCE', when: 'a catalog-listed source file is missing'},
+    {code: 'ERR_NO_SOURCE', when: 'a theme file to copy is missing'},
     {
       code: 'ERR_FILE_EXISTS',
       when: 'a destination exists and overwrite is not set',

package/api/theme/themeBuild.doc.mjs

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'themeBuild',
+  namespace: 'cli/api',
   displayName: 'themeBuild()',
   summary: 'Compile a defineTheme file to CSS + JS + type declarations.',
   description:

package/api/theme/themeList.doc.mjs

@@ -9,10 +9,11 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'themeList',
+  namespace: 'cli/api',
   displayName: 'themeList()',
   summary: 'List themes bundled with this CLI build.',
   description:
-    'Projects the bundled-theme manifest into a synchronous theme.list envelope. This preserves the original programmatic API contract. The CLI command uses themeListAvailable() so installed integrations also appear.',
+    'Projects the bundled typed theme descriptors into a synchronous theme.list envelope. This preserves the original programmatic API contract. The CLI command uses themeListAvailable() so installed integrations also appear.',
   importPath: '@astryxdesign/cli/api',
   signature: 'themeList(): ThemeListResponse',
   keywords: ['theme', 'list', 'themes', 'bundled', 'available'],
@@ -27,9 +28,11 @@ export const doc = {
   throws: [
     {
       code: 'ERR_NO_SOURCE',
-      when: 'the bundled-theme manifest cannot be read or parsed',
+      when: 'the bundled theme descriptors cannot be read or parsed',
     },
   ],
-  examples: [{label: 'List bundled themes', code: 'const {data} = themeList();'}],
+  examples: [
+    {label: 'List bundled themes', code: 'const {data} = themeList();'},
+  ],
   related: ['themeListAvailable', 'themeAdd', 'listThemes'],
 };

package/api/theme/themeListAvailable.doc.mjs

@@ -9,10 +9,11 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'themeListAvailable',
+  namespace: 'cli/api',
   displayName: 'themeListAvailable()',
   summary: 'List bundled and installed integration themes.',
   description:
-    'Loads Project for the requested directory, combines the CLI bundle with source themes from installed integrations, and projects each entry with its owner package. An unreadable project configuration degrades to the bundled catalog.',
+    'Loads Project for the requested directory, combines the CLI bundle with source themes from installed integrations, and projects each entry with its owner package. An unreadable project configuration degrades to the bundled descriptors.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'themeListAvailable(options?: {cwd?: string, package?: string}): Promise<ThemeListResponse>',
@@ -21,7 +22,8 @@ export const doc = {
     {
       name: 'options.cwd',
       type: 'string',
-      description: 'Project directory whose installed integrations contribute themes.',
+      description:
+        'Project directory whose installed integrations contribute themes.',
     },
     {
       name: 'options.package',
@@ -39,7 +41,7 @@ export const doc = {
   throws: [
     {
       code: 'ERR_NO_SOURCE',
-      when: 'the CLI bundled-theme manifest cannot be read or parsed',
+      when: 'the CLI bundled-theme descriptors cannot be read or parsed',
     },
   ],
   examples: [

package/api/theme/themePaletteGenerate.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'themePaletteGenerate',
+  namespace: 'cli/api',
   displayName: 'themePaletteGenerate()',
   summary: 'Generate an author-reviewable palette candidate from JSON input.',
   description:

package/api/theme/themeTargets.doc.mjs

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'themeTargets',
+  namespace: 'cli/api',
   displayName: 'themeTargets()',
   summary: 'List every component theming target a theme can override.',
   description:

package/api/theme/themeTemplate.doc.mjs

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'themeTemplate',
+  namespace: 'cli/api',
   displayName: 'themeTemplate()',
   summary: 'Write the annotated theme template into a project.',
   description: