@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/api/template/template.doc.mjs

@@ -102,7 +102,6 @@ export const doc = {
       type: 'string',
       description:
         'Directory to discover templates and resolve the target path from.',
-      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -135,7 +134,7 @@ export const doc = {
   throws: [
     {
       code: 'ERR_UNKNOWN_TEMPLATE',
-      when: 'the named template does not exist, or options.skeleton is set without a name',
+      when: 'the named template does not exist, or --skeleton is run without a name',
     },
     {
       code: 'ERR_AMBIGUOUS_TEMPLATE',

package/api/template/template.mjs

@@ -8,7 +8,7 @@
  * the requested one, and routes to a leaf (list/show/skeleton/copy/cdn). The shared
  * discovery/IO + cross-command helpers live in `foundation/discovery/template-adapter.mjs` and are
  * RE-EXPORTED here so external import paths (`api/template/template.mjs`) —
- * used by component, search, init, discover, Doctor integration, and
+ * used by component, layout, search, init, discover, Doctor integration, and
  * lib/project — keep resolving unchanged.
  *
  * @position api/template — the template dispatcher + barrel; leaves live under

package/api/theme/add/add.mjs

@@ -15,7 +15,6 @@ import {
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {listAvailableThemes, findTheme} from '../_adapter.mjs';
-import {applyWrites} from '../../integration/add-helpers.mjs';
 // Scaffolded files must not carry our repo boilerplate into a consumer's tree.
 import {stripCopyrightHeader} from '../../../foundation/text/copyright-header.mjs';
 
@@ -137,28 +136,37 @@ export async function themeAdd(slug, options = {}) {
     }
   }
 
-  // One transaction: every file publishes, or every replaced file gets its
-  // previous bytes back and every created file is removed. mkdir is inside the
-  // try so a failure (e.g. an ancestor is a file → EEXIST/ENOTDIR) surfaces as
-  // a stable ERR_WRITE_FAILED rather than leaking a raw fs errno + absolute path.
+  // Stage to temp files then rename, rolling back partials on failure so a
+  // failed write never leaves a half-written theme. mkdir is inside the try so
+  // a failure (e.g. an ancestor is a file → EEXIST/ENOTDIR) surfaces as a
+  // stable ERR_WRITE_FAILED rather than leaking a raw fs errno + absolute path.
+  const staged = [];
   try {
     fs.mkdirSync(resolvedDir, {recursive: true});
-    const plans = writes.map(w => {
-      fs.mkdirSync(path.dirname(w.dest), {recursive: true});
-      // Confine again once the directories exist: one may have been swapped
-      // for a link since the destination was first checked.
+    for (const w of writes) {
       const dest = assertWithin(w.name, resolvedDir, {
         label: `theme destination for ${w.name}`,
       });
-      return {
-        path: dest,
-        contents: scaffoldContents(fs.readFileSync(w.src)),
-        createOnly: !overwrite,
-      };
-    });
-    applyWrites(plans);
+      fs.mkdirSync(path.dirname(dest), {recursive: true});
+      // The staging file is an output path too: confine it, and never write
+      // through an entry that already exists under its name.
+      const tmp = assertWithin(`${w.name}.${process.pid}.tmp`, resolvedDir, {
+        label: `theme staging file for ${w.name}`,
+      });
+      fs.writeFileSync(tmp, scaffoldContents(fs.readFileSync(w.src)), {flag: 'wx'});
+      staged.push({tmp, dest});
+    }
+    for (const s of staged) {
+      fs.renameSync(s.tmp, s.dest);
+    }
   } catch (err) {
-    if (err instanceof AstryxError) throw err;
+    for (const s of staged) {
+      try {
+        fs.rmSync(s.tmp, {force: true});
+      } catch {
+        /* best-effort */
+      }
+    }
     if (err instanceof PathSafetyError) {
       throw new AstryxError(
         err.message,

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

@@ -6,15 +6,14 @@ 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(() => {
@@ -23,61 +22,45 @@ afterEach(() => {
 });
 
 /**
- * Where `theme add` writes the first file of `slug`.
+ * Put a symlink where `theme add` stages the first file of `slug`.
  * @param {string} slug
+ * @param {string} target
  */
-function firstDestination(slug) {
+function plantStagingLink(slug, target) {
   const theme = listThemes().find(entry => entry.slug === slug);
   if (!theme) throw new Error(`missing bundled theme ${slug}`);
-  const dest = path.join(tmpDir, 'src', 'themes', slug, theme.files[0]);
+  const first = theme.files[0];
+  const dest = path.join(tmpDir, 'src', 'themes', slug, first);
   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('never writes through a link planted at a predictable staging name', async () => {
+  it('refuses a staging path 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}.${process.pid}.tmp`);
-
-    await themeAdd('stone', {cwd: tmpDir});
+    const dest = plantStagingLink('stone', victim);
 
+    await expect(themeAdd('stone', {cwd: tmpDir})).rejects.toMatchObject({
+      code: 'ERR_PATH_TRAVERSAL',
+    });
     expect(fs.readFileSync(victim, 'utf-8')).toBe('outside\n');
-    expect(fs.lstatSync(dest).isFile()).toBe(true);
+    expect(fs.existsSync(dest)).toBe(false);
   });
 
-  it('never creates a file through a dangling link at a predictable staging name', async () => {
+  it('never creates a file through a dangling staging link', async () => {
     const victim = path.join(outsideDir, 'created.txt');
-    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);
+    plantStagingLink('stone', victim);
 
-    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);
-  });
+    let error;
+    try {
+      await themeAdd('stone', {cwd: tmpDir});
+    } catch (caught) {
+      error = caught;
+    }
 
-  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(isErrorCode(error?.code)).toBe(true);
     expect(fs.existsSync(victim)).toBe(false);
   });
 });

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

@@ -251,18 +251,23 @@ describe('themeBuildFamily()', () => {
     const dir = makeDir();
     const files = writeFamily(dir);
     const outputDir = path.join(dir, 'themes');
-    // 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`));
+    const blockedTmp = path.join(
+      outputDir,
+      `${FAMILY_KEY}.js.${process.pid}.tmp`,
+    );
+    fs.mkdirSync(blockedTmp);
 
     await expect(build(dir, files)).rejects.toThrow(
       /Failed to write theme outputs/,
     );
-    expect(fs.existsSync(path.join(outputDir, `${FAMILY_KEY}.css`))).toBe(false);
-    expect(fs.existsSync(path.join(outputDir, `${FAMILY_KEY}.d.ts`))).toBe(false);
+    for (const output of OUTPUTS) {
+      expect(fs.existsSync(path.join(outputDir, output))).toBe(false);
+    }
     expect(
-      fs.readdirSync(outputDir).filter(name => name.includes('.tmp-')),
-    ).toEqual([]);
+      fs.existsSync(
+        path.join(outputDir, `${FAMILY_KEY}.css.${process.pid}.tmp`),
+      ),
+    ).toBe(false);
   });
 
   it('rejects invalid graphs and keys before touching an existing trio', async () => {

package/api/theme/build/build.mjs

@@ -53,7 +53,6 @@ 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 {
@@ -225,15 +224,26 @@ 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 {
-    applyWrites(
-      writes.map(write => ({
-        path: write.dest,
-        contents: write.content,
-        createOnly: false,
-      })),
-    );
+    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);
+    }
   } 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/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.',
+        '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.',
       required: true,
     },
   ],
@@ -72,5 +72,6 @@ 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:
-    "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.",
+    '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', 'descriptor', 'bundled', 'adapter', 'list'],

package/api/theme/themeAdd.doc.mjs

@@ -44,7 +44,6 @@ export const doc = {
       type: 'string',
       description:
         'Project directory used for integration discovery and target paths.',
-      default: 'process.cwd()',
     },
     {
       name: 'options.package',
@@ -58,6 +57,11 @@ 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: [
     {
@@ -70,10 +74,7 @@ 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: 'the bundled theme descriptors cannot be read, or a theme file to copy 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',
@@ -81,12 +82,12 @@ export const doc = {
     {code: 'ERR_WRITE_FAILED', when: 'writing files fails'},
   ],
   examples: [
-    {label: 'Copy a bundled theme', code: "await themeAdd('butter');"},
+    {label: 'Copy a bundled theme', code: "await themeAdd('ocean');"},
     {
-      label: 'Name the owner package and the destination',
-      code: "await themeAdd('butter', {package: '@astryxdesign/cli', targetPath: 'src/brand-theme'});",
+      label: 'Copy an integration theme',
+      code: "await themeAdd('ocean', {package: '@acme/themes'});",
     },
   ],
   command: 'theme add',
-  related: ['themeListAvailable', 'themeTemplate', 'listThemes'],
+  related: ['themeList', 'listThemes'],
 };

package/api/theme/themeBuild.doc.mjs

@@ -14,13 +14,14 @@ export const doc = {
   name: 'themeBuild',
   namespace: 'cli/api',
   displayName: 'themeBuild()',
-  summary:
-    'Compile a defineTheme() file to scoped CSS, a JS module, and type declarations, or check committed outputs for drift in CI.',
+  summary: 'Compile a defineTheme file to CSS + JS + type declarations.',
   description:
-    '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. " +
+    '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. ' +
     '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',
@@ -47,7 +48,7 @@ export const doc = {
       name: 'options.out',
       type: 'string',
       description:
-        '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.',
+        'Override the output CSS path; the sibling .js and .d.ts derive from it. A relative path must stay within cwd.',
     },
     {
       name: 'options.check',
@@ -60,14 +61,13 @@ export const doc = {
       name: 'options.iconsSpecifier',
       type: 'string',
       description:
-        '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.',
+        'Override the icon-registry import specifier in the generated JS module, for example ./icons.mjs. When omitted, the source specifier is preserved.',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description:
-        'Directory the theme file, a relative out path, and the returned output paths resolve against.',
-      default: 'process.cwd()',
+        'Directory the theme file and @astryxdesign/core resolve against.',
     },
   ],
   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. Resolves to null, like a normal build, when the theme produces no CSS.',
+        '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.',
     },
   ],
   throws: [
@@ -102,7 +102,7 @@ export const doc = {
     },
     {
       code: 'ERR_CORE_INCOMPATIBLE',
-      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)',
+      when: 'the selected theme carries ordered-adaptation intent but the installed @astryxdesign/core does not export generateAdaptationCSS (upgrade core)',
     },
     {
       code: 'ERR_WRITE_FAILED',
@@ -124,5 +124,5 @@ export const doc = {
     },
   ],
   command: 'theme build',
-  related: ['themeTemplate', 'themeAdd', 'themeListAvailable', 'listThemes'],
+  related: ['themeAdd', 'themeList', '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:
-    '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.',
+    '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'],

package/api/theme/themeListAvailable.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   displayName: 'themeListAvailable()',
   summary: 'List bundled and installed integration themes.',
   description:
-    '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.',
+    '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>',
@@ -24,7 +24,6 @@ export const doc = {
       type: 'string',
       description:
         'Project directory whose installed integrations contribute themes.',
-      default: 'process.cwd()',
     },
     {
       name: 'options.package',

package/api/theme/themePaletteGenerate.doc.mjs

@@ -27,34 +27,30 @@ export const doc = {
     {
       name: 'configPath',
       type: 'string',
-      description:
-        'Path to a JSON file holding a TonalPaletteGenerationInput (the object generateTonalPalette() takes), resolved within cwd.',
+      description: 'JSON generation request, resolved within cwd.',
       required: true,
     },
     {
       name: 'options.out',
       type: 'string',
       description:
-        'Where to write the candidate: a path ending in .ts (a TypeScript module) or .json. A sibling <name>.receipt.json is written next to it.',
+        'Optional candidate JSON destination. A sibling .receipt.json path is derived from it.',
     },
     {
       name: 'options.preview',
       type: 'string',
-      description:
-        'Optional path, ending in .html, for a self-contained HTML review page.',
+      description: 'Optional path for a self-contained HTML review artifact.',
     },
     {
       name: 'options.overwrite',
       type: 'boolean',
-      description:
-        "Replace existing candidate, receipt and preview files. Without it, if any target exists, nothing is written and the result has written: false, reason: 'exists'.",
+      description: 'Replace existing candidate and receipt files.',
       default: 'false',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description: 'Directory used to resolve the input and output paths.',
-      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -68,20 +64,17 @@ export const doc = {
     {code: 'ERR_FILE_NOT_FOUND', when: 'the config file does not exist'},
     {
       code: 'ERR_PALETTE_GENERATION',
-      when: 'the config is not valid JSON; the request, seed, stop layout, mode or anchor is invalid; out does not end in .ts or .json; or preview does not end in .html',
+      when: 'the request, seed, stop layout, mode, or anchor constraint is invalid',
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
       when: 'an input or output path escapes cwd, or output would replace input',
     },
-    {
-      code: 'ERR_WRITE_FAILED',
-      when: 'the candidate, receipt or preview file cannot be written',
-    },
+    {code: 'ERR_WRITE_FAILED', when: 'the candidate pair cannot be written'},
   ],
   examples: [
     {
-      label: 'Generate a candidate without writing files',
+      label: 'Preview a candidate',
       code: "themePaletteGenerate('palette.config.json');",
     },
     {
@@ -90,5 +83,5 @@ export const doc = {
     },
   ],
   command: 'theme palette generate',
-  related: ['generateTonalPalette', 'themeBuild', 'themeTemplate'],
+  related: ['themeBuild', 'themeTemplate'],
 };

package/api/theme/themeTargets.doc.mjs

@@ -22,7 +22,7 @@ export const doc = {
     'Same source as the Theming table `astryx component <Name>` prints ' +
     '(the component docs), so the list cannot drift from the components, and `theme build` ' +
     'validates overrides against this exact set. A filter naming a component gives that ' +
-    "component's set; anything else is a case-insensitive substring search over each target's key, class and component.",
+    "component's set; anything else is a substring search over the keys.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'themeTargets(filter?: string, ctx?: {cwd?: string}): Promise<ThemeTargetsResponse>',
@@ -41,14 +41,13 @@ export const doc = {
       name: 'filter',
       type: 'string',
       description:
-        'A component name (exact, case-insensitive), or a substring of a target key, class or component. Omit for the whole surface.',
+        'A component name (exact, case-insensitive) or a substring of a target key. Omit for the whole surface.',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description:
         "Directory the project's @astryxdesign/core is resolved from.",
-      default: 'process.cwd()',
     },
   ],
   returns: [

package/api/theme/themeTemplate.doc.mjs

@@ -43,7 +43,6 @@ export const doc = {
       name: 'options.cwd',
       type: 'string',
       description: 'Directory the target path resolves against.',
-      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -65,5 +64,5 @@ export const doc = {
     },
   ],
   command: 'theme template',
-  related: ['themeAdd', 'themeBuild', 'themeListAvailable', 'themeTargets'],
+  related: ['themeAdd', 'themeBuild', 'themeList'],
 };

package/api/upgrade/run/run.mjs

@@ -114,7 +114,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
   // Resolve the source dir against the API's cwd (not process.cwd()) so a
   // programmatic caller in another directory scans the right tree. Confine it to
   // cwd: --apply rewrites files in place, so a `..`-escaping or out-of-tree
-  // absolute --path must be rejected (parity with template/theme/swizzle,
+  // absolute --path must be rejected (parity with template/theme/swizzle/layout,
   // and this is the most destructive command). allowAbsolute permits an absolute
   // path that still resolves inside cwd.
   let path_;
@@ -437,11 +437,9 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
 
   const registryResult = await reconcileCompositions();
 
-  // A file a core codemod AND an integration codemod both changed is one file.
-  const mergedFilesChanged = new Set([
-    ...(coreResult?.changedFiles ?? []),
-    ...(integrationResult?.changedFiles ?? []),
-  ]).size;
+  const mergedFilesChanged =
+    (coreResult?.totalFilesChanged ?? 0) +
+    (integrationResult?.totalFilesChanged ?? 0);
   const mergedTransformsApplied =
     (coreResult?.totalTransformsApplied ?? 0) +
     (integrationResult?.totalTransformsApplied ?? 0);