@astryxdesign/cli 0.6.4 → 0.6.5-canary.01972bc

package/api/theme/build/build.mjs

@@ -45,7 +45,11 @@ import {fileURLToPath, pathToFileURL} from 'node:url';
 import {parse} from '@babel/parser';
 import {createJiti} from 'jiti';
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
-import {CLI_ROOT, findCoreDir} from '../../../foundation/fs/paths.mjs';
+import {
+  CLI_ROOT,
+  findCoreDir,
+  findInstalledPackage,
+} from '../../../foundation/fs/paths.mjs';
 import {
   assertWithin,
   sanitizeName,
@@ -53,6 +57,7 @@ import {
 } from '../../../foundation/fs/path-safety.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {AstryxError} from '../../error.mjs';
+import {applyWrites} from '../../integration/add-helpers.mjs';
 import {logger} from '../../logger.mjs';
 import {loadComponentDoc} from '../../../foundation/discovery/component-loader.mjs';
 import {
@@ -124,6 +129,232 @@ try {
   _coreImportError = e;
 }
 
+/**
+ * The bindings one Core provides: the namespaces interception spreads, the
+ * functions the build calls, and why the import failed, if it did.
+ * @typedef {{
+ *   themeModule: any,
+ *   rootModule: any,
+ *   importError: any,
+ *   defineTheme: any,
+ *   generateThemeRulesSplit: any,
+ *   generateOnMediaCSS: any,
+ *   generateAdaptationCSS: any,
+ *   dataTokenDefaults: any,
+ * }} CoreBindings
+ */
+
+/**
+ * The bindings exactly as the CLI's own import left them, kept so each build
+ * can choose between them and the project's installed Core.
+ * @type {CoreBindings}
+ */
+const _cliCore = {
+  themeModule: _coreThemeModule,
+  rootModule: _coreRootModule,
+  importError: _coreImportError,
+  defineTheme: _defineTheme,
+  generateThemeRulesSplit: _generateThemeRulesSplit,
+  generateOnMediaCSS: _generateOnMediaCSS,
+  generateAdaptationCSS: _generateAdaptationCSS,
+  dataTokenDefaults: _dataTokenDefaults,
+};
+
+/**
+ * Point the build at one Core: the module-level bindings every step reads.
+ * @param {CoreBindings} core
+ */
+function setCore(core) {
+  _coreThemeModule = core.themeModule;
+  _coreRootModule = core.rootModule;
+  _coreImportError = core.importError;
+  _defineTheme = core.defineTheme;
+  _generateThemeRulesSplit = core.generateThemeRulesSplit;
+  _generateOnMediaCSS = core.generateOnMediaCSS;
+  _generateAdaptationCSS = core.generateAdaptationCSS;
+  _dataTokenDefaults = core.dataTokenDefaults;
+}
+
+/**
+ * The file an `import` of `subpath` reaches through a package's `exports` map,
+ * or null when the map has no entry for it. Conditions are taken in the map's
+ * own order, as Node does, accepting the ones an import matches here: `node`,
+ * `import`, and `default` (so `source` and `types` are skipped).
+ *
+ * @param {string} dir - The package directory.
+ * @param {string} subpath - `'.'` or a subpath such as `'./theme'`.
+ * @returns {string|null}
+ */
+function importTarget(dir, subpath) {
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+  } catch {
+    return null;
+  }
+  const map = pkg?.exports;
+  const bySubpath =
+    map &&
+    typeof map === 'object' &&
+    !Array.isArray(map) &&
+    Object.keys(map).some(key => key.startsWith('.'));
+  const entry = bySubpath ? map[subpath] : subpath === '.' ? map : undefined;
+  /** @param {any} value @returns {string|null} */
+  const pick = value => {
+    if (typeof value === 'string') return value;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+      return null;
+    for (const [condition, target] of Object.entries(value)) {
+      if (
+        condition !== 'node' &&
+        condition !== 'import' &&
+        condition !== 'default'
+      )
+        continue;
+      const picked = pick(target);
+      if (picked) return picked;
+    }
+    return null;
+  };
+  const target = pick(entry);
+  return target ? path.resolve(dir, target) : null;
+}
+
+/** @param {string} file @returns {string} its real path, or itself */
+function realOrSelf(file) {
+  try {
+    return fs.realpathSync(file);
+  } catch {
+    return file;
+  }
+}
+
+/**
+ * The Core the project at `cwd` installed, when it differs from the one the
+ * CLI's own import found and loads. The app's `<Theme>` runs on the app's
+ * Core, so building with it keeps the CSS identical; and a CLI run one-off
+ * (`npx @astryxdesign/cli`) has no Core beside it at all. Null when there is
+ * nothing better than the CLI's own import: no installed Core (the Astryx
+ * repository, a bare directory), the same Core, or one that does not load.
+ *
+ * @param {string} cwd
+ * @returns {Promise<CoreBindings | null>}
+ */
+async function loadProjectCore(cwd) {
+  const dir = findInstalledPackage(cwd, '@astryxdesign/core');
+  const themeFile = dir ? importTarget(dir, './theme') : null;
+  if (!dir || !themeFile) return null;
+  if (_cliCore.themeModule) {
+    try {
+      const own = fileURLToPath(
+        import.meta.resolve('@astryxdesign/core/theme'),
+      );
+      if (realOrSelf(own) === realOrSelf(themeFile)) return null;
+    } catch {
+      // The CLI's own Core cannot be located; load the project's.
+    }
+  }
+  let themeModule;
+  try {
+    themeModule = await import(pathToFileURL(themeFile).href);
+  } catch {
+    return null;
+  }
+  if (!themeModule.defineTheme || !themeModule.generateThemeRulesSplit)
+    return null;
+  let rootModule = null;
+  const rootFile = importTarget(dir, '.');
+  if (rootFile) {
+    try {
+      rootModule = await import(pathToFileURL(rootFile).href);
+    } catch {
+      // As with the CLI's own import, the theme namespace stands in for it.
+    }
+  }
+  return {
+    themeModule,
+    rootModule,
+    importError: null,
+    defineTheme: themeModule.defineTheme,
+    generateThemeRulesSplit: themeModule.generateThemeRulesSplit,
+    generateOnMediaCSS: themeModule.generateOnMediaCSS,
+    generateAdaptationCSS: themeModule.generateAdaptationCSS,
+    dataTokenDefaults: themeModule.dataTokenDefaults,
+  };
+}
+
+/** @type {Map<string, Awaited<ReturnType<typeof loadProjectCore>>>} */
+const _projectCores = new Map();
+
+/**
+ * Choose the Core this build generates with: the project's installed one when
+ * {@link loadProjectCore} finds it, else the CLI's own.
+ * @param {string} cwd
+ */
+async function selectCore(cwd) {
+  if (!_projectCores.has(cwd))
+    _projectCores.set(cwd, await loadProjectCore(cwd));
+  setCore(_projectCores.get(cwd) ?? _cliCore);
+}
+
+/**
+ * Whether `cwd` sits in the Astryx repository, where Core is built from
+ * source rather than installed.
+ * @param {string} cwd
+ */
+function inAstryxRepository(cwd) {
+  let dir = cwd;
+  for (let i = 0; i < 6; i++) {
+    try {
+      const pkg = JSON.parse(
+        fs.readFileSync(
+          path.join(dir, 'packages', 'core', 'package.json'),
+          'utf-8',
+        ),
+      );
+      if (pkg?.name === '@astryxdesign/core') return true;
+    } catch {
+      // Not here; keep walking up.
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}
+
+/**
+ * Why `theme build` has no Core to generate with, and the fix for where it
+ * ran: the Astryx repository builds Core, an app installs it, and an installed
+ * Core that will not load is named.
+ *
+ * @param {string} cwd
+ * @param {any} importError - Why the import failed, when it threw.
+ * @returns {string}
+ */
+export function coreUnavailableMessage(cwd, importError) {
+  const why =
+    '`astryx theme build` generates CSS with @astryxdesign/core, the same code the runtime <Theme> uses';
+  const detail = importError ? `\n  Import error: ${importError.message}` : '';
+  if (inAstryxRepository(cwd)) {
+    return (
+      `Could not load @astryxdesign/core/theme: ${why}. Build @astryxdesign/core ` +
+      `first (e.g. \`pnpm -F @astryxdesign/core build\`).${detail}`
+    );
+  }
+  const installed = findInstalledPackage(cwd, '@astryxdesign/core');
+  if (installed) {
+    return (
+      `Could not load the @astryxdesign/core installed at ` +
+      `${path.relative(cwd, installed) || '.'}: ${why}. Reinstall it.${detail}`
+    );
+  }
+  return (
+    `This project does not have @astryxdesign/core installed: ${why}. Install ` +
+    `it: \`npm install @astryxdesign/core\` (or yarn/pnpm/bun).${detail}`
+  );
+}
+
 /**
  * Read a package's `version` from a resolved directory. Returns `'unknown'`
  * when it can't be read so the header always has a value.
@@ -224,26 +455,15 @@ function staleBuildOutputs(writes, cwd) {
 /** @param {Array<{dest: string, content: string}>} writes */
 function writeBuildOutputs(writes) {
   if (writes.length === 0) return;
-  /** @type {Array<{tmp: string, dest: string}>} */
-  const staged = [];
   try {
-    fs.mkdirSync(path.dirname(writes[0].dest), {recursive: true});
-    for (const write of writes) {
-      const tmp = `${write.dest}.${process.pid}.tmp`;
-      fs.writeFileSync(tmp, write.content);
-      staged.push({tmp, dest: write.dest});
-    }
-    for (const stagedWrite of staged) {
-      fs.renameSync(stagedWrite.tmp, stagedWrite.dest);
-    }
+    applyWrites(
+      writes.map(write => ({
+        path: write.dest,
+        contents: write.content,
+        createOnly: false,
+      })),
+    );
   } catch (error) {
-    for (const stagedWrite of staged) {
-      try {
-        fs.rmSync(stagedWrite.tmp, {force: true});
-      } catch {
-        // Best effort: the command still fails and never reports success.
-      }
-    }
     const message = `Failed to write theme outputs: ${/** @type {Error} */ (error).message}`;
     throw new AstryxError(message, undefined, ERROR_CODES.ERR_WRITE_FAILED);
   }
@@ -2117,6 +2337,8 @@ async function themeBuildInternal(
 
   logger.log(`\nBuilding theme from ${path.relative(cwd, filePath)}...`);
 
+  await selectCore(cwd);
+
   // Standalone builds only need interception when an older Core could erase
   // adaptations. Family preparation always supplies the same recorder as its
   // shared loader so exact authored parent identity stays CLI-private instead
@@ -2243,13 +2465,7 @@ async function themeBuildInternal(
   // capability exports are checked against what the theme actually asks for.
   if (!_defineTheme || !_generateThemeRulesSplit) {
     throw new AstryxError(
-      'Could not load @astryxdesign/core/theme: `astryx theme build` requires a ' +
-        'built, resolvable @astryxdesign/core so it emits the same CSS as the ' +
-        'runtime <Theme>. Build @astryxdesign/core first (e.g. `pnpm -F @astryxdesign/core ' +
-        'build`)' +
-        (_coreImportError
-          ? `.\n  Import error: ${_coreImportError.message}`
-          : '.'),
+      coreUnavailableMessage(cwd, _coreImportError),
       undefined,
       ERROR_CODES.ERR_CORE_NOT_FOUND,
     );
@@ -2817,6 +3033,7 @@ export async function themeBuildFamily(
       error instanceof Error ? error.message : 'Invalid family key.';
     throw new AstryxError(message, undefined, ERROR_CODES.ERR_THEME_INVALID);
   }
+  await selectCore(cwd);
   const familyInterception = interceptCore(_coreThemeModule, _coreRootModule);
   // prettier-ignore
   const familyLoader = createJiti(import.meta.url, {moduleCache: true, interopDefault: false, jsx: true, extensions: THEME_MODULE_EXTENSIONS, virtualModules: familyInterception.modules});

package/api/theme/build/build.project-core.test.mjs

@@ -0,0 +1,165 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `theme build` in an app generates with the Core the app installed.
+ *
+ * A CLI run one-off (`npx @astryxdesign/cli`) has no Core beside it, and the
+ * app's `<Theme>` runs on the app's Core either way, so the build loads the
+ * project's installed `@astryxdesign/core` when it differs from the CLI's own.
+ * When there is no Core to use, the error names the fix for where it ran:
+ * install it in an app, build it in the Astryx repository.
+ */
+
+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 {fileURLToPath, pathToFileURL} from 'node:url';
+import {coreUnavailableMessage, themeBuild} from './build.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '../../../../..');
+const CORE_DIST = path.join(REPO_ROOT, 'packages/core/dist');
+
+/** @type {string[]} */
+const tmpDirs = [];
+const makeDir = () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-project-core-'));
+  tmpDirs.push(dir);
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    '{"name":"app","type":"module"}',
+  );
+  // A plain theme object: the file itself never imports Core, so only the
+  // build's own Core loading can set the marker below.
+  fs.writeFileSync(
+    path.join(dir, 'ocean.mjs'),
+    "export default {name: 'ocean', tokens: {'--color-bg': '#0a0a0a'}};\n",
+  );
+  return dir;
+};
+
+beforeEach(() => {
+  delete globalThis.__astryxProjectCoreLoads;
+});
+afterEach(() => {
+  delete globalThis.__astryxProjectCoreLoads;
+  for (const dir of tmpDirs.splice(0))
+    fs.rmSync(dir, {recursive: true, force: true});
+});
+
+/**
+ * Install a Core in `dir` that is the built one, re-exported, and records each
+ * entry as it is imported. Its `exports` map lists `source` first, as Core's
+ * own does, so the build must skip that condition to find the runtime file.
+ * @param {string} dir
+ * @param {{broken?: boolean}} [options]
+ */
+function installCore(dir, {broken = false} = {}) {
+  const core = path.join(dir, 'node_modules', '@astryxdesign', 'core');
+  fs.mkdirSync(core, {recursive: true});
+  fs.writeFileSync(
+    path.join(core, 'package.json'),
+    JSON.stringify({
+      name: '@astryxdesign/core',
+      version: '0.6.5',
+      type: 'module',
+      exports: {
+        '.': {types: './root.d.ts', default: './root.mjs'},
+        './theme': {
+          source: './src/theme/index.ts',
+          types: './theme.d.ts',
+          default: './theme.mjs',
+        },
+      },
+    }),
+  );
+  /** @param {string} entry @param {string} target */
+  const module = (entry, target) =>
+    broken
+      ? "throw new Error('this Core is broken');\n"
+      : `export * from ${JSON.stringify(pathToFileURL(path.join(CORE_DIST, target)).href)};\n` +
+        `globalThis.__astryxProjectCoreLoads = [...(globalThis.__astryxProjectCoreLoads ?? []), '${entry}'];\n`;
+  fs.writeFileSync(
+    path.join(core, 'theme.mjs'),
+    module('theme', 'theme/index.js'),
+  );
+  fs.writeFileSync(path.join(core, 'root.mjs'), module('root', 'index.js'));
+  return core;
+}
+
+describe('theme build generates with the Core the project installed', () => {
+  it('loads the app’s installed Core when it differs from the CLI’s own', async () => {
+    const app = makeDir();
+    installCore(app);
+    await themeBuild('ocean.mjs', {}, {cwd: app});
+    expect(globalThis.__astryxProjectCoreLoads).toEqual(['theme', 'root']);
+    // The same Core, re-exported, emits the same CSS as the CLI's own. The
+    // generated header differs only in the Core version it records.
+    const bare = makeDir();
+    await themeBuild('ocean.mjs', {}, {cwd: bare});
+    /** @param {string} dir */
+    const rules = dir =>
+      fs
+        .readFileSync(path.join(dir, 'ocean.css'), 'utf-8')
+        .replace(/^\/\*[\s\S]*?\*\/\n/, '');
+    expect(rules(app)).toBe(rules(bare));
+    expect(rules(app)).toContain('#0a0a0a');
+  });
+
+  it('keeps the CLI’s own Core when the project has none', async () => {
+    const bare = makeDir();
+    await themeBuild('ocean.mjs', {}, {cwd: bare});
+    expect(globalThis.__astryxProjectCoreLoads).toBeUndefined();
+    expect(fs.existsSync(path.join(bare, 'ocean.css'))).toBe(true);
+  });
+
+  it('keeps the CLI’s own Core when the installed one does not load', async () => {
+    const app = makeDir();
+    installCore(app, {broken: true});
+    await themeBuild('ocean.mjs', {}, {cwd: app});
+    expect(fs.existsSync(path.join(app, 'ocean.css'))).toBe(true);
+  });
+});
+
+describe('the error when there is no Core to generate with', () => {
+  it('tells an app to install Core, not to build it', () => {
+    const app = makeDir();
+    const message = coreUnavailableMessage(
+      app,
+      new Error("Cannot find package '@astryxdesign/core'"),
+    );
+    expect(message).toContain(
+      'This project does not have @astryxdesign/core installed',
+    );
+    expect(message).toContain('`npm install @astryxdesign/core`');
+    expect(message).not.toContain('pnpm -F');
+    expect(message).toContain(
+      "Import error: Cannot find package '@astryxdesign/core'",
+    );
+  });
+
+  it('names an installed Core that does not load', () => {
+    const app = makeDir();
+    installCore(app, {broken: true});
+    const message = coreUnavailableMessage(
+      app,
+      new Error('this Core is broken'),
+    );
+    expect(message).toContain(
+      `Could not load the @astryxdesign/core installed at ${path.join('node_modules', '@astryxdesign', 'core')}`,
+    );
+    expect(message).toContain('Reinstall it.');
+    expect(message).not.toContain('pnpm -F');
+  });
+
+  it('keeps the build instruction in the Astryx repository', () => {
+    const message = coreUnavailableMessage(
+      path.join(REPO_ROOT, 'packages', 'cli'),
+      undefined,
+    );
+    expect(message).toContain('Build @astryxdesign/core first');
+    expect(message).toContain('`pnpm -F @astryxdesign/core build`');
+    expect(message).not.toContain('Import error');
+  });
+});

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/generateTonalPalette.doc.mjs

@@ -29,7 +29,7 @@ export const doc = {
       name: 'input',
       type: 'TonalPaletteGenerationInput',
       description:
-        'Families and seeds plus optional modes, shared stops, anchors, vibrancy from 0 to 100 (default 50), and neutral profile. Only generate an accent family when one is explicitly requested; clarify whether an ambiguous accent means one theme value or a tonal family.',
+        'Families and seeds plus optional modes, shared stops, anchors, vibrancy from 0 to 100 (default 50), and neutral profile.',
       required: true,
     },
   ],
@@ -72,6 +72,5 @@ export const doc = {
       code: "generateTonalPalette({stops: [12.5, 50], families: [{id: 'blue', seed: '#0074e2'}]});",
     },
   ],
-  command: 'theme palette generate',
   related: ['themePaletteGenerate'],
 };

package/api/theme/listThemes.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   displayName: 'listThemes()',
   summary: 'Read the CLI bundled-theme descriptors.',
   description:
-    '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.',
+    "Synchronously returns the themes bundled with the CLI, including each one's entry file, export name and file list. Bundled themes only; use themeListAvailable() to include themes from installed integrations.",
   importPath: '@astryxdesign/cli/api',
   signature: 'listThemes(): BundledTheme[]',
   keywords: ['theme', 'themes', 'descriptor', 'bundled', 'adapter', 'list'],