@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

package/api/theme/build/build.receipt-doc.test.mjs

@@ -0,0 +1,111 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Every field `themeBuild()` returns is named in its FunctionDoc and in the
+ * response-types doc.
+ *
+ * The receipt is a stable machine-readable response, so each field needs
+ * consumer documentation, not only a typedef. The fields are read off a real
+ * build, so a field added to the receipt without documentation fails here.
+ */
+
+import {describe, it, expect, beforeAll, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {themeBuild} from './build.mjs';
+import {doc} from '../themeBuild.doc.mjs';
+import {doc as responseTypes} from '../../../foundation/response/response-types.doc.mjs';
+import {ensureCoreBuilt} from '../../../clients/cli/commands/ensure-core-built.mjs';
+
+/** @type {string[]} */
+const dirs = [];
+
+beforeAll(() => {
+  ensureCoreBuilt();
+}, 200_000);
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) {
+    fs.rmSync(dir, {recursive: true, force: true});
+  }
+});
+
+/** @returns {string} a temp dir holding a theme that exercises every field */
+function themeDir() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-receipt-doc-'));
+  dirs.push(dir);
+  fs.writeFileSync(
+    path.join(dir, 'ocean.mjs'),
+    `export default {
+  name: 'ocean',
+  tokens: {'--color-background-body': '#ffffff', '--font-family-body': '"Inter", sans-serif'},
+  components: {progressbar: {base: {color: 'red'}}},
+};
+`,
+  );
+  return dir;
+}
+
+/** @param {string} type */
+function returnsDescription(type) {
+  const entry = doc.returns?.find(r => r.type === type);
+  expect(entry, `themeBuild doc has no ${type} return`).toBeDefined();
+  return /** @type {{description: string}} */ (entry).description;
+}
+
+/** @param {string} description @param {string[]} fields */
+function undocumented(description, fields) {
+  return fields.filter(
+    field => !new RegExp(String.raw`\b${field}\b`).test(description),
+  );
+}
+
+describe('themeBuild() consumer docs name every receipt field', () => {
+  it('theme.build', async () => {
+    const dir = themeDir();
+    const result = await themeBuild('ocean.mjs', {}, {cwd: dir});
+
+    expect(result?.type).toBe('theme.build');
+    const data = /** @type {Record<string, any>} */ (result?.data);
+    // The theme is chosen so the optional arrays are non-empty.
+    expect(data.warnings.length).toBeGreaterThan(0);
+    expect(data.notices.length).toBeGreaterThan(0);
+
+    const fields = [
+      ...Object.keys(data),
+      ...Object.keys(data.outputs),
+      'variantsDts',
+    ];
+    expect(undocumented(returnsDescription('theme.build'), fields)).toEqual([]);
+  });
+
+  it('theme.build in the response-types doc', async () => {
+    const dir = themeDir();
+    const result = await themeBuild('ocean.mjs', {}, {cwd: dir});
+    const data = /** @type {Record<string, any>} */ (result?.data);
+    const member = responseTypes.members.find(m => m.value === 'theme.build');
+    expect(member, 'response-types has no theme.build member').toBeDefined();
+
+    const fields = [
+      ...Object.keys(data),
+      ...Object.keys(data.outputs),
+      'variantsDts',
+    ];
+    expect(
+      undocumented(/** @type {{description: string}} */ (member).description, fields),
+    ).toEqual([]);
+  });
+
+  it('theme.build.check', async () => {
+    const dir = themeDir();
+    const result = await themeBuild('ocean.mjs', {check: true}, {cwd: dir});
+
+    expect(result?.type).toBe('theme.build.check');
+    const data = /** @type {Record<string, any>} */ (result?.data);
+    const fields = [...Object.keys(data), ...Object.keys(data.stale[0])];
+    expect(
+      undocumented(returnsDescription('theme.build.check'), fields),
+    ).toEqual([]);
+  });
+});

package/api/theme/build/build.rollback.test.mjs

@@ -0,0 +1,148 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * `theme build` writes its CSS, JS, and declarations as one transaction: when
+ * a later output fails to publish, every output it already replaced gets its
+ * previous bytes back and every output it created is removed. Publishing is
+ * forced to fail by wrapping the two calls that publish a staged file:
+ * `linkSync` for a new file and `renameSync` for a replacement.
+ *
+ * Separate file because vi.mock is hoisted and affects the whole module.
+ * `themeBuild` needs a built core; the `node` project's globalSetup builds it.
+ */
+
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+const failures = vi.hoisted(() => ({
+  /** Fail the Nth staged-file publish (1-based); 0 disables. */
+  publish: 0,
+  count: 0,
+}));
+
+vi.mock('node:fs', async importOriginal => {
+  const actual = /** @type {typeof import('node:fs')} */ (
+    await importOriginal()
+  );
+  /** @param {string} source @param {string} op */
+  const maybeFail = (source, op) => {
+    if (!path.basename(String(source)).includes('.tmp')) return;
+    if (failures.publish === 0) return;
+    failures.count++;
+    if (failures.count === failures.publish) {
+      throw Object.assign(new Error(`EIO: forced ${op} failure`), {
+        code: 'EIO',
+      });
+    }
+  };
+  return {
+    ...actual,
+    linkSync: vi.fn((source, destination) => {
+      maybeFail(source, 'link');
+      return actual.linkSync(source, destination);
+    }),
+    renameSync: vi.fn((source, destination) => {
+      maybeFail(source, 'rename');
+      return actual.renameSync(source, destination);
+    }),
+  };
+});
+
+const fs = await import('node:fs');
+const {themeBuild} = await import('./build.mjs');
+
+vi.setConfig({testTimeout: 30000});
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(
+    path.join(os.tmpdir(), 'astryx-theme-build-rollback-'),
+  );
+  failures.publish = 0;
+  failures.count = 0;
+});
+
+afterEach(() => {
+  failures.publish = 0;
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * Write a source for the theme named `rollbacktheme`. Each call uses a new
+ * file so the loader cannot serve an earlier version from its cache.
+ * @param {string} file @param {string} background
+ */
+function writeTheme(file, background) {
+  fs.writeFileSync(
+    path.join(tmpDir, file),
+    `export default { name: 'rollbacktheme', tokens: { '--color-bg': '${background}' } };\n`,
+  );
+  return file;
+}
+
+const OUTPUTS = ['rollbacktheme.css', 'rollbacktheme.js', 'rollbacktheme.d.ts'];
+
+/** @returns {Map<string, Buffer | null>} */
+function readOutputs() {
+  return new Map(
+    OUTPUTS.map(name => {
+      const file = path.join(tmpDir, name);
+      return [name, fs.existsSync(file) ? fs.readFileSync(file) : null];
+    }),
+  );
+}
+
+function strays() {
+  return fs
+    .readdirSync(tmpDir)
+    .filter(name => name.includes('.tmp') || name.includes('.restore-'));
+}
+
+describe('themeBuild rolls back a partial write', () => {
+  it('removes every created output when the second publish fails', async () => {
+    const source = writeTheme('first.mjs', '#0a0a0a');
+    failures.publish = 2;
+
+    await expect(themeBuild(source, {}, {cwd: tmpDir})).rejects.toMatchObject({
+      code: 'ERR_WRITE_FAILED',
+    });
+
+    for (const bytes of readOutputs().values()) expect(bytes).toBeNull();
+    expect(strays()).toEqual([]);
+  });
+
+  it('restores every replaced output when the second publish fails', async () => {
+    const first = await themeBuild(
+      writeTheme('first.mjs', '#0a0a0a'),
+      {},
+      {cwd: tmpDir},
+    );
+    expect(first?.type).toBe('theme.build');
+    const before = readOutputs();
+    for (const bytes of before.values()) expect(bytes).not.toBeNull();
+
+    const next = writeTheme('next.mjs', '#fafafa');
+    failures.publish = 2;
+    await expect(themeBuild(next, {}, {cwd: tmpDir})).rejects.toMatchObject({
+      code: 'ERR_WRITE_FAILED',
+    });
+
+    const after = readOutputs();
+    for (const name of OUTPUTS) {
+      expect(
+        after.get(name)?.equals(/** @type {Buffer} */ (before.get(name))),
+      ).toBe(true);
+    }
+
+    // The failed build really had different bytes to write.
+    failures.publish = 0;
+    await themeBuild(next, {}, {cwd: tmpDir});
+    const css = readOutputs().get('rollbacktheme.css');
+    expect(
+      css?.equals(/** @type {Buffer} */ (before.get('rollbacktheme.css'))),
+    ).toBe(false);
+    expect(strays()).toEqual([]);
+  });
+});

package/api/theme/build/build.test.mjs

@@ -206,6 +206,133 @@ describe('themeBuild() — receipt', () => {
   });
 });
 
+describe('themeBuild() — dropped declarations reach the receipt', () => {
+  // Core's generator refuses a declaration whose value would end it early
+  // (an unquoted `;` or brace, an unclosed string/comment/url). The runtime
+  // says so on the console; a build has a receipt, so every drop must land in
+  // `warnings` — a programmatic caller otherwise sees `warnings: []` while the
+  // CSS silently omits a value the generated JS still carries.
+  it('reports every dropped declaration, from every generator path, in warnings', async () => {
+    const themeFile = path.join(tmpDir, 'dropped.mjs');
+    fs.writeFileSync(
+      themeFile,
+      `export default {
+        name: 'dropped',
+        tokens: {
+          '--color-bg': '#0a0a0a } body { background: url(https://example.com/token) ',
+        },
+        components: {
+          button: {
+            'variant:secondary': {
+              backgroundColor: 'red; background-image: url(https://example.com/component)',
+              ':hover': {color: '"https://example.com/pseudo'},
+            },
+          },
+        },
+        onDark: {
+          tokens: {'--color-bg': 'url(https://example.com/dark'},
+        },
+        adaptations: {
+          rules: [
+            {
+              when: {pointer: 'coarse'},
+              value: {tokens: {'--color-bg': 'red /* https://example.com/adaptation'}},
+            },
+          ],
+        },
+      };\n`,
+    );
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    let result;
+    try {
+      result = await themeBuild('dropped.mjs', {}, {cwd: tmpDir});
+      // Drops are collected, not printed: the programmatic API stays silent.
+      expect(warnSpy).not.toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+
+    const css = fs.readFileSync(path.join(tmpDir, 'dropped.css'), 'utf8');
+    expect(css).not.toContain('example.com');
+
+    const warnings = result?.data.warnings ?? [];
+    expect(warnings).toHaveLength(5);
+    expect(warnings).toEqual(
+      expect.arrayContaining([
+        expect.stringMatching(
+          /^Declaration dropped "--color-bg" in tokens: an unquoted "}" would close the rule/,
+        ),
+        expect.stringMatching(
+          /^Declaration dropped "background-color" in components\.button\["variant:secondary"\]: an unquoted ";" would end the declaration/,
+        ),
+        expect.stringMatching(
+          /^Declaration dropped "color" in components\.button\["variant:secondary"\]\[":hover"\]: an unclosed " string/,
+        ),
+        expect.stringMatching(
+          /^Declaration dropped "--color-bg" in onDark\.tokens: an unclosed url\(/,
+        ),
+        expect.stringMatching(
+          /^Declaration dropped "--color-bg" in adaptations\[0\]\.tokens: an unclosed \/\* comment/,
+        ),
+      ]),
+    );
+    for (const w of warnings) {
+      expect(w).toContain('The generated CSS omits it');
+    }
+  });
+
+  it('generates CSS for legacy null tokens without losing neighboring declarations', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'legacy.mjs'),
+      `export default {
+        name: 'legacy',
+        tokens: {'--color-background-body': null, '--spacing-4': 12},
+        onDark: {tokens: {'--color-background-body': null}},
+        components: {button: {base: {borderRadius: '4px'}}},
+      };\n`,
+    );
+
+    const result = await themeBuild('legacy.mjs', {}, {cwd: tmpDir});
+    const css = fs.readFileSync(path.join(tmpDir, 'legacy.css'), 'utf8');
+    expect(css).toContain('--color-background-body: null;');
+    expect(css).toContain('--spacing-4: 12;');
+    expect(css).toContain('border-radius: 4px;');
+    expect(result?.data.warnings).toEqual([]);
+  });
+
+  it('keeps valid CSS that carries semicolons, and reports nothing', async () => {
+    const themeFile = path.join(tmpDir, 'kept.mjs');
+    fs.writeFileSync(
+      themeFile,
+      `export default {
+        name: 'kept',
+        tokens: {'--font-family-body': 'Gill\\\\ Sans, "Segoe;UI", serif /* ; */'},
+        components: {
+          button: {
+            'variant:secondary': {
+              backgroundImage: 'URL(data:image/svg+xml;base64,PHN2Zz4=)',
+              WebkitLineClamp: '2',
+            },
+          },
+        },
+      };\n`,
+    );
+
+    const result = await themeBuild('kept.mjs', {}, {cwd: tmpDir});
+    const css = fs.readFileSync(path.join(tmpDir, 'kept.css'), 'utf8');
+
+    expect(css).toContain(
+      '--font-family-body: Gill\\ Sans, "Segoe;UI", serif /* ; */;',
+    );
+    expect(css).toContain(
+      'background-image: URL(data:image/svg+xml;base64,PHN2Zz4=);',
+    );
+    expect(css).toContain('-webkit-line-clamp: 2;');
+    expect(result?.data.warnings).toEqual([]);
+  });
+});
+
 describe('themeBuild() — nothing to build', () => {
   it('returns null and writes nothing when the generator yields no CSS', async () => {
     const themeFile = path.join(tmpDir, 'empty.mjs');

package/api/theme/build/font-warning.mjs

@@ -211,11 +211,11 @@ export function formatFontLoadingHelp(themeName, families) {
   const first = families[0];
   const slug = first.toLowerCase().replace(/ /g, '-');
   return `
-⚠ Theme "${themeName}" names fonts it does not load: ${named}
-  The built CSS only sets font-family — load these in your app, or every
+[note] Theme "${themeName}" names fonts it does not load: ${named}
+  The built CSS only sets font-family; load these in your app, or every
   browser quietly falls back.
 
-  Google Fonts (add :wght@… axes as your theme's weights require):
+  Google Fonts (add :wght@... axes as your theme's weights require):
 
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />

package/api/theme/build/font-warning.test.mjs

@@ -227,12 +227,15 @@ describe('formatFontLoadingHelp', () => {
   const help = formatFontLoadingHelp('ocean', ['Fraunces', 'JetBrains Mono']);
 
   it('names the theme and every family in the headline', () => {
-    expect(help).toContain('⚠');
-    expect(help).toContain('ocean');
+    expect(help).toContain('[note] Theme "ocean"');
     expect(help).toContain('"Fraunces"');
     expect(help).toContain('"JetBrains Mono"');
   });
 
+  it('is plain ASCII', () => {
+    expect(help).not.toMatch(/[\u0080-\uffff]/);
+  });
+
   it('includes the Google Fonts recipe: preconnect pair + the exact css2 URL', () => {
     expect(help).toContain(
       '<link rel="preconnect" href="https://fonts.googleapis.com"',

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: [