@astryxdesign/cli 0.6.4 → 0.6.5-canary.031021b

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

@@ -0,0 +1,158 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * `theme add` writes a theme as one transaction: when a later file fails to
+ * publish, every file it already replaced gets its previous bytes back and
+ * every file 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.
+ */
+
+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,
+  /** Also fail every rollback restore. */
+  restore: false,
+  count: 0,
+}));
+
+vi.mock('node:fs', async importOriginal => {
+  const actual = /** @type {typeof import('node:fs')} */ (
+    await importOriginal()
+  );
+  /** @param {string} source */
+  const isStaged = source => path.basename(String(source)).includes('.tmp');
+  /** @param {string} source */
+  const isRestore = source =>
+    path.basename(String(source)).includes('.restore-');
+  /** @param {string} source @param {string} op */
+  const maybeFail = (source, op) => {
+    if (isStaged(source) && failures.publish > 0) {
+      failures.count++;
+      if (failures.count === failures.publish) {
+        throw Object.assign(new Error(`EIO: forced ${op} failure`), {
+          code: 'EIO',
+        });
+      }
+    }
+    if (isRestore(source) && failures.restore) {
+      throw Object.assign(new Error(`EIO: forced restore 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 {themeAdd} = await import('./add.mjs');
+const {listThemes} = await import('../_adapter.mjs');
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-themeadd-rollback-'));
+  failures.publish = 0;
+  failures.restore = false;
+  failures.count = 0;
+});
+
+afterEach(() => {
+  failures.publish = 0;
+  failures.restore = false;
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+function stoneFiles() {
+  const theme = listThemes().find(entry => entry.slug === 'stone');
+  if (!theme) throw new Error('missing bundled theme stone');
+  expect(theme.files.length).toBeGreaterThanOrEqual(2);
+  return theme.files.map(name =>
+    path.join(tmpDir, 'src', 'themes', 'stone', name),
+  );
+}
+
+/** Entries staging or rollback left behind in the theme directory. */
+function strays() {
+  const dir = path.join(tmpDir, 'src', 'themes', 'stone');
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, {recursive: true})
+    .map(String)
+    .filter(name => name.includes('.tmp') || name.includes('.restore-'));
+}
+
+describe('themeAdd rolls back a partial write', () => {
+  it('removes every created file when the second publish fails', async () => {
+    const files = stoneFiles();
+    failures.publish = 2;
+
+    await expect(themeAdd('stone', {cwd: tmpDir})).rejects.toMatchObject({
+      code: 'ERR_WRITE_FAILED',
+    });
+
+    for (const file of files) expect(fs.existsSync(file)).toBe(false);
+    expect(strays()).toEqual([]);
+  });
+
+  it('restores every replaced byte when the second publish fails', async () => {
+    const files = stoneFiles();
+    fs.mkdirSync(path.dirname(files[0]), {recursive: true});
+    const before = Buffer.from([0x00, 0xff, 0x0a, 0x62, 0x65, 0x66]);
+    fs.writeFileSync(files[0], before);
+    failures.publish = 2;
+
+    await expect(
+      themeAdd('stone', {cwd: tmpDir, overwrite: true}),
+    ).rejects.toMatchObject({code: 'ERR_WRITE_FAILED'});
+
+    expect(fs.readFileSync(files[0]).equals(before)).toBe(true);
+    for (const file of files.slice(1)) expect(fs.existsSync(file)).toBe(false);
+    expect(strays()).toEqual([]);
+  });
+
+  it('names a file it could not restore', async () => {
+    const files = stoneFiles();
+    fs.mkdirSync(path.dirname(files[0]), {recursive: true});
+    fs.writeFileSync(files[0], 'before\n');
+    failures.publish = 2;
+    failures.restore = true;
+
+    let error;
+    try {
+      await themeAdd('stone', {cwd: tmpDir, overwrite: true});
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error?.code).toBe('ERR_WRITE_FAILED');
+    expect(error?.message).toContain('Could not restore');
+    expect(error?.message).toContain(files[0]);
+  });
+
+  it('writes every file when nothing fails', async () => {
+    const files = stoneFiles();
+
+    const result = await themeAdd('stone', {cwd: tmpDir});
+
+    expect(result.type).toBe('theme.add');
+    for (const file of files) expect(fs.existsSync(file)).toBe(true);
+    expect(strays()).toEqual([]);
+  });
+});

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

@@ -6,14 +6,15 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import {themeAdd} from './add.mjs';
 import {listThemes} from '../_adapter.mjs';
-import {isErrorCode} from '../../../foundation/response/error-codes.mjs';
 
 let tmpDir;
 let outsideDir;
 
 beforeEach(() => {
   tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-themeadd-staging-'));
-  outsideDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-themeadd-outside-'));
+  outsideDir = fs.mkdtempSync(
+    path.join(os.tmpdir(), 'astryx-themeadd-outside-'),
+  );
 });
 
 afterEach(() => {
@@ -22,45 +23,61 @@ afterEach(() => {
 });
 
 /**
- * Put a symlink where `theme add` stages the first file of `slug`.
+ * Where `theme add` writes the first file of `slug`.
  * @param {string} slug
- * @param {string} target
  */
-function plantStagingLink(slug, target) {
+function firstDestination(slug) {
   const theme = listThemes().find(entry => entry.slug === slug);
   if (!theme) throw new Error(`missing bundled theme ${slug}`);
-  const first = theme.files[0];
-  const dest = path.join(tmpDir, 'src', 'themes', slug, first);
+  const dest = path.join(tmpDir, 'src', 'themes', slug, theme.files[0]);
   fs.mkdirSync(path.dirname(dest), {recursive: true});
-  fs.symlinkSync(target, `${dest}.${process.pid}.tmp`);
   return dest;
 }
 
+// Staging names are unpredictable and created exclusively, so an entry planted
+// at a predictable name beside the destination is never written through.
 describe('themeAdd staging writes stay inside the project', () => {
-  it('refuses a staging path that links outside the project', async () => {
+  it('never writes through a link planted at a predictable staging name', async () => {
     const victim = path.join(outsideDir, 'victim.txt');
     fs.writeFileSync(victim, 'outside\n');
-    const dest = plantStagingLink('stone', victim);
+    const dest = firstDestination('stone');
+    fs.symlinkSync(victim, `${dest}.${process.pid}.tmp`);
+
+    await themeAdd('stone', {cwd: tmpDir});
 
-    await expect(themeAdd('stone', {cwd: tmpDir})).rejects.toMatchObject({
-      code: 'ERR_PATH_TRAVERSAL',
-    });
     expect(fs.readFileSync(victim, 'utf-8')).toBe('outside\n');
-    expect(fs.existsSync(dest)).toBe(false);
+    expect(fs.lstatSync(dest).isFile()).toBe(true);
   });
 
-  it('never creates a file through a dangling staging link', async () => {
+  it('never creates a file through a dangling link at a predictable staging name', async () => {
     const victim = path.join(outsideDir, 'created.txt');
-    plantStagingLink('stone', victim);
+    fs.symlinkSync(victim, `${firstDestination('stone')}.${process.pid}.tmp`);
+
+    await themeAdd('stone', {cwd: tmpDir});
+
+    expect(fs.existsSync(victim)).toBe(false);
+  });
+
+  it('refuses to replace a destination that links outside the project', async () => {
+    const victim = path.join(outsideDir, 'victim.txt');
+    fs.writeFileSync(victim, 'outside\n');
+    const dest = firstDestination('stone');
+    fs.symlinkSync(victim, dest);
 
-    let error;
-    try {
-      await themeAdd('stone', {cwd: tmpDir});
-    } catch (caught) {
-      error = caught;
-    }
+    await expect(
+      themeAdd('stone', {cwd: tmpDir, overwrite: true}),
+    ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+    expect(fs.readFileSync(victim, 'utf-8')).toBe('outside\n');
+    expect(fs.lstatSync(dest).isSymbolicLink()).toBe(true);
+  });
 
-    expect(isErrorCode(error?.code)).toBe(true);
+  it('never creates a file through a dangling destination link', async () => {
+    const victim = path.join(outsideDir, 'created.txt');
+    fs.symlinkSync(victim, firstDestination('stone'));
+
+    await expect(themeAdd('stone', {cwd: tmpDir})).rejects.toMatchObject({
+      code: 'ERR_PATH_TRAVERSAL',
+    });
     expect(fs.existsSync(victim)).toBe(false);
   });
 });

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

@@ -251,23 +251,18 @@ describe('themeBuildFamily()', () => {
     const dir = makeDir();
     const files = writeFamily(dir);
     const outputDir = path.join(dir, 'themes');
-    const blockedTmp = path.join(
-      outputDir,
-      `${FAMILY_KEY}.js.${process.pid}.tmp`,
-    );
-    fs.mkdirSync(blockedTmp);
+    // A directory where the JS output goes fails its staging after the CSS
+    // output was already staged.
+    fs.mkdirSync(path.join(outputDir, `${FAMILY_KEY}.js`));
 
     await expect(build(dir, files)).rejects.toThrow(
       /Failed to write theme outputs/,
     );
-    for (const output of OUTPUTS) {
-      expect(fs.existsSync(path.join(outputDir, output))).toBe(false);
-    }
+    expect(fs.existsSync(path.join(outputDir, `${FAMILY_KEY}.css`))).toBe(false);
+    expect(fs.existsSync(path.join(outputDir, `${FAMILY_KEY}.d.ts`))).toBe(false);
     expect(
-      fs.existsSync(
-        path.join(outputDir, `${FAMILY_KEY}.css.${process.pid}.tmp`),
-      ),
-    ).toBe(false);
+      fs.readdirSync(outputDir).filter(name => name.includes('.tmp-')),
+    ).toEqual([]);
   });
 
   it('rejects invalid graphs and keys before touching an existing trio', async () => {

package/api/theme/build/build.mjs

@@ -53,6 +53,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 {
@@ -224,26 +225,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);
   }

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'],

package/api/theme/themeAdd.doc.mjs

@@ -44,6 +44,7 @@ export const doc = {
       type: 'string',
       description:
         'Project directory used for integration discovery and target paths.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.package',
@@ -57,11 +58,6 @@ export const doc = {
       description:
         'Copy receipt with slug, displayName, maintained flag, owner package, outputDir, entry, exportName, and files.',
     },
-    {
-      type: 'theme.list',
-      description:
-        'The CLI list affordance routes a bare `astryx theme add` or `--list` to themeListAvailable() and returns every available theme with its owner.',
-    },
   ],
   throws: [
     {
@@ -74,7 +70,10 @@ export const doc = {
       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 theme file to copy is missing'},
+    {
+      code: 'ERR_NO_SOURCE',
+      when: 'the bundled theme descriptors cannot be read, or a theme file to copy is missing',
+    },
     {
       code: 'ERR_FILE_EXISTS',
       when: 'a destination exists and overwrite is not set',
@@ -82,12 +81,12 @@ export const doc = {
     {code: 'ERR_WRITE_FAILED', when: 'writing files fails'},
   ],
   examples: [
-    {label: 'Copy a bundled theme', code: "await themeAdd('ocean');"},
+    {label: 'Copy a bundled theme', code: "await themeAdd('butter');"},
     {
-      label: 'Copy an integration theme',
-      code: "await themeAdd('ocean', {package: '@acme/themes'});",
+      label: 'Name the owner package and the destination',
+      code: "await themeAdd('butter', {package: '@astryxdesign/cli', targetPath: 'src/brand-theme'});",
     },
   ],
   command: 'theme add',
-  related: ['themeList', 'listThemes'],
+  related: ['themeListAvailable', 'themeTemplate', 'listThemes'],
 };

package/api/theme/themeBuild.doc.mjs

@@ -14,14 +14,13 @@ export const doc = {
   name: 'themeBuild',
   namespace: 'cli/api',
   displayName: 'themeBuild()',
-  summary: 'Compile a defineTheme file to CSS + JS + type declarations.',
+  summary:
+    'Compile a defineTheme() file to scoped CSS, a JS module, and type declarations, or check committed outputs for drift in CI.',
   description:
-    'The compiler behind `astryx theme build`. Reads a file that calls defineTheme() and, ' +
-    "via @astryxdesign/core's shared generator (the single source of truth, so the build " +
-    'emits the exact CSS the <Theme> runtime does), writes a scoped CSS file, a JS module ' +
-    'that re-exports the built theme, and a .d.ts (plus an optional .variants.d.ts when the ' +
-    'theme adds custom prop values). When another build step emits the icon registry, ' +
-    '{iconsSpecifier} declares the fully specified module path for the generated JS import. ' +
+    'The compiler behind `astryx theme build`. Reads a file that calls defineTheme() and ' +
+    'writes a scoped CSS file, a JS module that re-exports the built theme, and a .d.ts ' +
+    '(plus an optional .variants.d.ts when the theme adds custom prop values). It uses ' +
+    "@astryxdesign/core's own generator, so the CSS matches what the <Theme> runtime emits. " +
     'With {check: true} it writes nothing and instead compares ' +
     'each output against disk, returning the drift: the CI guard for committed, generated theme CSS.',
   importPath: '@astryxdesign/cli/api',
@@ -48,7 +47,7 @@ export const doc = {
       name: 'options.out',
       type: 'string',
       description:
-        'Override the output CSS path; the sibling .js and .d.ts derive from it. A relative path must stay within cwd.',
+        'Override the output CSS path. The .js, .d.ts and any .variants.d.ts are written in the same directory, named after the theme (<name>.js), not after the CSS file. A relative path must stay within cwd.',
     },
     {
       name: 'options.check',
@@ -61,13 +60,14 @@ export const doc = {
       name: 'options.iconsSpecifier',
       type: 'string',
       description:
-        'Override the icon-registry import specifier in the generated JS module, for example ./icons.mjs. When omitted, the source specifier is preserved.',
+        'Override the import specifier of the icon registry in the generated JS module, for example ./icons.mjs. Takes effect only when the theme sets icons: to a named import; when omitted, the source specifier is kept.',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description:
-        'Directory the theme file and @astryxdesign/core resolve against.',
+        'Directory the theme file, a relative out path, and the returned output paths resolve against.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -79,7 +79,7 @@ export const doc = {
     {
       type: 'theme.build.check',
       description:
-        'The {check: true} receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: "missing" | "outdated"}), and the full list of checked paths. Writes nothing.',
+        'The {check: true} receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: "missing" | "outdated"}), and the full list of checked paths. Writes nothing. Resolves to null, like a normal build, when the theme produces no CSS.',
     },
   ],
   throws: [
@@ -102,7 +102,7 @@ export const doc = {
     },
     {
       code: 'ERR_CORE_INCOMPATIBLE',
-      when: 'the selected theme carries ordered-adaptation intent but the installed @astryxdesign/core does not export generateAdaptationCSS (upgrade core)',
+      when: 'the installed @astryxdesign/core does not export generateAdaptationCSS and the theme either declares ordered adaptations or has lineage whose adaptation use could not be observed (upgrade core)',
     },
     {
       code: 'ERR_WRITE_FAILED',
@@ -124,5 +124,5 @@ export const doc = {
     },
   ],
   command: 'theme build',
-  related: ['themeAdd', 'themeList', 'listThemes'],
+  related: ['themeTemplate', 'themeAdd', 'themeListAvailable', 'listThemes'],
 };

package/api/theme/themeList.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   displayName: 'themeList()',
   summary: 'List themes bundled with this CLI build.',
   description:
-    '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.',
+    'Synchronous list of the themes bundled with the CLI. It does not include themes from installed integrations; use themeListAvailable() for the list `astryx theme list` shows.',
   importPath: '@astryxdesign/cli/api',
   signature: 'themeList(): ThemeListResponse',
   keywords: ['theme', 'list', 'themes', 'bundled', 'available'],

package/api/theme/themeListAvailable.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   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 descriptors.',
+    'Lists the bundled themes plus source themes from integrations installed in cwd, each with its owner package. If the project configuration cannot be read, it falls back to the bundled themes.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'themeListAvailable(options?: {cwd?: string, package?: string}): Promise<ThemeListResponse>',
@@ -24,6 +24,7 @@ export const doc = {
       type: 'string',
       description:
         'Project directory whose installed integrations contribute themes.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.package',