@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/{src → cli}/commands/build-theme.mjs

@@ -8,8 +8,8 @@
  * - An updated JS module that references the built className
  *
  * Usage:
- *   npx astryx theme build ./src/themes/ocean.ts
- *   npx astryx theme build ./src/themes/ocean.ts --out ./dist/ocean.css
+ *   astryx theme build ./src/themes/ocean.ts
+ *   astryx theme build ./src/themes/ocean.ts --out ./dist/ocean.css
  */
 
 import * as fs from 'node:fs';
@@ -17,26 +17,27 @@ import * as path from 'node:path';
 import {pathToFileURL, fileURLToPath} from 'node:url';
 import {spawn} from 'node:child_process';
 import {createJiti} from 'jiti';
-import {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
 import {
   sanitizeName,
   PathSafetyError,
-  isNonInteractive,
-} from '../utils/path-safety.mjs';
-import {jsonOut, humanLog} from '../lib/json.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {themeAdd, listThemes} from '../api/theme-add.mjs';
+} from '../../utils/path-safety.mjs';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {themeAdd} from '../../api/theme/theme-add.mjs';
 
 // Import shared theme processing from core. `astryx theme build` MUST produce the
 // exact same CSS as the `<Theme>` runtime, so it has exactly one generation
 // path: core's generator. There is no in-CLI fallback implementation — if this
 // import fails, the build fails (see the ERR_CORE_NOT_FOUND guard in the theme
 // action). A built, resolvable `@astryxdesign/core` is a hard requirement.
-let _defineTheme = null;
-let _generateThemeRulesSplit = null;
-let _generateOnMediaCSS = null;
-let _coreImportError = null;
+// A built, resolvable `@astryxdesign/core` is a hard requirement. These are
+// populated from a dynamic import (a runtime boundary), so `any` is intentional.
+/** @type {any} */ let _defineTheme = null;
+/** @type {any} */ let _generateThemeRulesSplit = null;
+/** @type {any} */ let _generateOnMediaCSS = null;
+/** @type {any} */ let _coreImportError = null;
 try {
   const coreTheme = await import('@astryxdesign/core/theme');
   _defineTheme = coreTheme.defineTheme;
@@ -76,9 +77,11 @@ function generatedHeader(sourceFile, lang = 'js', command) {
 /**
  * Convert a theme name to a valid JS identifier.
  * e.g. 'default-minimal' → 'defaultMinimal', 'ocean' → 'ocean'
+ * @param {string} name
+ * @returns {string}
  */
 function toIdentifier(name) {
-  return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  return name.replace(/-([a-z])/g, (/** @type {string} */ _, /** @type {string} */ c) => c.toUpperCase());
 }
 
 /**
@@ -86,6 +89,9 @@ function toIdentifier(name) {
  * from the cwd-relative dir (most consumers import from a file under src/) but
  * keeps the rest of the path (e.g. `themes/gothic`). Callers note the path is
  * relative to the consumer's file.
+ * @param {string} relDir
+ * @param {string} base
+ * @returns {string}
  */
 function importSpecifier(relDir, base) {
   const normalized = relDir === '.' ? '' : relDir;
@@ -96,11 +102,13 @@ function importSpecifier(relDir, base) {
 /**
  * Convert a kebab-case component name to PascalCase.
  * e.g. 'button' → 'Button', 'progress-bar' → 'ProgressBar', 'avatar-status-dot' → 'AvatarStatusDot'
+ * @param {string} name
+ * @returns {string}
  */
 function toPascalCase(name) {
   return name
     .split('-')
-    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .map((/** @type {string} */ part) => part.charAt(0).toUpperCase() + part.slice(1))
     .join('');
 }
 
@@ -108,6 +116,8 @@ function toPascalCase(name) {
  * Load known built-in values for a component's visual props from its .doc.mjs file.
  * Parses the type string (e.g. "'info' | 'warning' | 'error' | 'success'") to extract values.
  * Returns a map of { propName: string[] } for props that are visual (listed in theming targets).
+ * @param {string} componentName
+ * @returns {Promise<Record<string, string[]>>}
  */
 async function loadKnownValues(componentName) {
   // Resolve core src relative to the CLI package, not cwd (which may be a theme package)
@@ -141,6 +151,7 @@ async function loadKnownValues(componentName) {
     if (allProps.length === 0) return {};
 
     // Collect visual prop names from theming targets
+    /** @type {Set<string>} */
     const visualProps = new Set();
     for (const target of doc.theming.targets) {
       if (target.visualProps) {
@@ -149,6 +160,7 @@ async function loadKnownValues(componentName) {
     }
 
     // Extract values from prop type strings
+    /** @type {Record<string, string[]>} */
     const result = {};
     for (const prop of allProps) {
       if (!visualProps.has(prop.name)) continue;
@@ -157,7 +169,7 @@ async function loadKnownValues(componentName) {
       // Parse union type: "'info' | 'warning' | 'error' | 'success'" → ['info', 'warning', 'error', 'success']
       const matches = prop.type.match(/'([^']+)'/g);
       if (matches) {
-        result[prop.name] = matches.map(m => m.replace(/'/g, ''));
+        result[prop.name] = matches.map((/** @type {string} */ m) => m.replace(/'/g, ''));
       }
     }
     return result;
@@ -167,12 +179,17 @@ async function loadKnownValues(componentName) {
 }
 
 // Cache for loaded known values
+/** @type {Map<string, Record<string, string[]>>} */
 const _knownValuesCache = new Map();
+/**
+ * @param {string} componentName
+ * @returns {Promise<Record<string, string[]>>}
+ */
 async function getKnownValues(componentName) {
   if (!_knownValuesCache.has(componentName)) {
     _knownValuesCache.set(componentName, await loadKnownValues(componentName));
   }
-  return _knownValuesCache.get(componentName);
+  return _knownValuesCache.get(componentName) ?? {};
 }
 
 /**
@@ -196,10 +213,15 @@ function resolveCoreRoot() {
  * actually sees), falling back to the `src/<Component>/index.ts` in the
  * monorepo. Returns the file contents, or '' if nothing is found.
  */
+/** @type {Map<string, string>} */
 const _componentDeclCache = new Map();
+/**
+ * @param {string} pascalName
+ * @returns {string}
+ */
 function readComponentDeclarations(pascalName) {
   if (_componentDeclCache.has(pascalName)) {
-    return _componentDeclCache.get(pascalName);
+    return _componentDeclCache.get(pascalName) ?? '';
   }
   let contents = '';
   const coreRoot = resolveCoreRoot();
@@ -231,6 +253,9 @@ function readComponentDeclarations(pascalName) {
  * `HeadingType`, `ButtonSize`) are NOT augmentable, so a generated augmentation
  * against them is dead code. We check that the name is exported (directly or
  * re-exported) as a type/interface.
+ * @param {string} pascalName
+ * @param {string} interfaceName
+ * @returns {boolean}
  */
 function componentHasAugmentableInterface(pascalName, interfaceName) {
   const decl = readComponentDeclarations(pascalName);
@@ -255,7 +280,7 @@ function componentHasAugmentableInterface(pascalName, interfaceName) {
  * generating a `declare module` block for them would be dead code — those are
  * skipped.
  *
- * @param {object} themeDef - Theme definition (resolved by defineTheme)
+ * @param {{components?: Record<string, Record<string, Record<string, unknown>>>}} themeDef - Theme definition (resolved by defineTheme)
  * @returns {Promise<string|null>} TypeScript declaration content, or null if no augmentations needed
  */
 async function generateVariantDeclarationsAsync(themeDef) {
@@ -264,6 +289,7 @@ async function generateVariantDeclarationsAsync(themeDef) {
   }
 
   // Collect custom values: { component: { prop: [value, ...] } }
+  /** @type {Record<string, Record<string, Set<string>>>} */
   const customValues = {};
 
   for (const [component, rules] of Object.entries(themeDef.components)) {
@@ -337,6 +363,8 @@ async function generateVariantDeclarationsAsync(themeDef) {
 
 /**
  * Resolve a token value — [light, dark] tuple becomes light-dark()
+ * @param {unknown} value
+ * @returns {unknown}
  */
 function resolveTokenValue(value) {
   if (Array.isArray(value)) {
@@ -348,12 +376,14 @@ function resolveTokenValue(value) {
 // Theme @scope selector helpers. Keep the `astryx` literal in sync with
 // packages/core/src/naming.ts (NAMESPACE) and generateThemeRules.ts.
 // Theme scopes to data-astryx-theme; the static build path must match.
-const themeScopeStart = name => `[data-astryx-theme="${name}"]`;
+const themeScopeStart = (/** @type {string} */ name) => `[data-astryx-theme="${name}"]`;
 const THEME_SCOPE_TO = `[data-astryx-theme]`;
 
 /**
  * Import a theme module using jiti and find the defineTheme() result.
  * Returns the resolved DefinedTheme object.
+ * @param {string} filePath
+ * @returns {Promise<any>}
  */
 async function importThemeModule(filePath) {
   const jiti = createJiti(import.meta.url, {
@@ -377,6 +407,10 @@ async function importThemeModule(filePath) {
   );
 }
 
+/**
+ * @param {any} value
+ * @returns {boolean}
+ */
 function isThemeObject(value) {
   return (
     value &&
@@ -390,6 +424,8 @@ function isThemeObject(value) {
 /**
  * Extract the theme definition from a JS/TS file.
  * Tries jiti first (full TS support), falls back to regex+eval.
+ * @param {string} filePath
+ * @returns {Promise<any>}
  */
 async function extractThemeDefinition(filePath) {
   try {
@@ -398,8 +434,9 @@ async function extractThemeDefinition(filePath) {
     try {
       return extractThemeDefinitionLegacy(filePath);
     } catch {
+      const je = /** @type {Error} */ (jitiError);
       throw new Error(
-        `Failed to load theme from ${filePath}: ${jitiError.message}\n` +
+        `Failed to load theme from ${filePath}: ${je.message}\n` +
         `Make sure all imports in the theme file are resolvable.`,
       );
     }
@@ -409,6 +446,8 @@ async function extractThemeDefinition(filePath) {
 /**
  * Fallback extraction via regex + eval.
  * Only works for plain object literals — can't follow imports or variables.
+ * @param {string} filePath
+ * @returns {any}
  */
 function extractThemeDefinitionLegacy(filePath) {
   const content = fs.readFileSync(filePath, 'utf8');
@@ -434,8 +473,9 @@ function extractThemeDefinitionLegacy(filePath) {
      
     return eval(`(${objStr})`);
   } catch (e) {
+    const err = /** @type {Error} */ (e);
     throw new Error(
-      `Failed to parse theme definition in ${filePath}: ${e.message}\n` +
+      `Failed to parse theme definition in ${filePath}: ${err.message}\n` +
       `Make sure the defineTheme() argument is a plain object literal.`,
       {cause: e},
     );
@@ -449,6 +489,8 @@ function extractThemeDefinitionLegacy(filePath) {
  * Looks for patterns like:
  *   import { defaultIconRegistry } from './icons';
  *   icons: defaultIconRegistry,
+ * @param {string} filePath
+ * @returns {{exportName: string, importPath: string} | null}
  */
 function extractIconInfo(filePath) {
   const content = fs.readFileSync(filePath, 'utf8');
@@ -457,7 +499,7 @@ function extractIconInfo(filePath) {
   const iconsMatch = content.match(/icons:\s*([a-zA-Z_][a-zA-Z0-9_]*)/);
   if (!iconsMatch) return null;
 
-  const varName = iconsMatch[1];
+  const varName = /** @type {string} */ (iconsMatch[1]);
 
   // Find the import for that variable
   const importRegex = new RegExp(
@@ -468,7 +510,7 @@ function extractIconInfo(filePath) {
 
   return {
     exportName: varName,
-    importPath: importMatch[1],
+    importPath: /** @type {string} */ (importMatch[1]),
   };
 }
 
@@ -476,6 +518,9 @@ function extractIconInfo(filePath) {
  * Generate a minimal JS module for a built theme.
  * Includes the theme name, marker, and re-exports the icon registry.
  * All styling is in the CSS file.
+ * @param {any} themeDef
+ * @param {{exportName: string, importPath: string} | null} iconInfo
+ * @returns {string}
  */
 function generateBuiltModule(themeDef, iconInfo) {
   const iconImport = iconInfo
@@ -487,6 +532,7 @@ function generateBuiltModule(themeDef, iconInfo) {
     : '';
 
   // Resolve token values — tuples become light-dark() strings
+  /** @type {Record<string, unknown>} */
   const resolvedTokens = {};
   if (themeDef.tokens) {
     for (const [key, value] of Object.entries(themeDef.tokens)) {
@@ -500,7 +546,7 @@ function generateBuiltModule(themeDef, iconInfo) {
     .join('\n');
 
   return `${iconImport}/**
- * ${themeDef.name} theme — built by \`${getRunPrefix()} astryx theme build\`
+ * ${themeDef.name} theme — built by \`${getCliInvocation()} theme build\`
  * Import the CSS file alongside this module:
  *
  *   import { ${toIdentifier(themeDef.name)}Theme } from './${themeDef.name}';
@@ -517,6 +563,10 @@ ${iconReExport}`;
 
 /**
  * Generate TypeScript declarations for a built theme module.
+ * @param {any} themeDef
+ * @param {{exportName: string, importPath: string} | null} iconInfo
+ * @param {string | null} variantsFileName
+ * @returns {string}
  */
 function generateBuiltTypes(themeDef, iconInfo, variantsFileName) {
   const iconType = iconInfo
@@ -544,6 +594,7 @@ ${iconType}export declare const ${toIdentifier(themeDef.name)}Theme: DefinedThem
 /**
  * Known Astryx component names and their visual props.
  * Used to warn on typos in defineTheme component overrides.
+ * @type {Record<string, string[]>}
  */
 const KNOWN_COMPONENTS = {
   appshell: ['position'],
@@ -605,8 +656,11 @@ const KNOWN_COMPONENTS = {
  * Validate component overrides in a theme definition.
  * Warns on unknown component names and unknown prop names.
  * Returns array of warning strings.
+ * @param {{components?: Record<string, Record<string, unknown>>}} themeDef
+ * @returns {string[]}
  */
 function validateComponentOverrides(themeDef) {
+  /** @type {string[]} */
   const warnings = [];
   if (!themeDef.components) return warnings;
 
@@ -669,8 +723,11 @@ function validateComponentOverrides(themeDef) {
  * (e.g. borderRadius, padding) instead.
  *
  * Returns array of error strings.
+ * @param {{components?: Record<string, Record<string, Record<string, unknown>>>}} themeDef
+ * @returns {string[]}
  */
 function validatePrivateVars(themeDef) {
+  /** @type {string[]} */
   const errors = [];
   if (!themeDef.components) return errors;
 
@@ -707,14 +764,14 @@ function resolveCliBin() {
  * Resolves with the child's exit code; never rejects.
  *
  * @param {string} file - The theme file argument, as the user passed it.
- * @param {object} options - Parsed command options (only `out` is forwarded).
+ * @param {{out?: string}} options - Parsed command options (only `out` is forwarded).
  * @returns {Promise<number>}
  */
 function runThemeBuildOnceChild(file, options) {
   const cliBin = resolveCliBin();
   const args = [cliBin, 'theme', 'build', file];
   if (options.out) args.push('--out', options.out);
-  return new Promise(resolve => {
+  return new Promise((/** @type {(code: number) => void} */ resolve) => {
     const child = spawn(process.execPath, args, {
       stdio: 'inherit',
       env: process.env,
@@ -733,7 +790,7 @@ function runThemeBuildOnceChild(file, options) {
  *
  * @param {string} file - The theme file argument, as the user passed it.
  * @param {string} filePath - Absolute path to the theme file.
- * @param {object} options - Parsed command options.
+ * @param {{out?: string}} options - Parsed command options.
  * @returns {Promise<void>} Resolves when the watcher is stopped (Ctrl-C).
  */
 async function runThemeBuildWatch(file, filePath, options) {
@@ -746,7 +803,8 @@ async function runThemeBuildWatch(file, filePath, options) {
 
   let building = false;
   let queued = false;
-  let debounce = null;
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let debounce;
 
   const rebuild = async () => {
     if (building) {
@@ -777,7 +835,7 @@ async function runThemeBuildWatch(file, filePath, options) {
     debounce = setTimeout(rebuild, 100);
   });
 
-  await new Promise(resolve => {
+  await new Promise((/** @type {(value?: void) => void} */ resolve) => {
     const stop = () => {
       clearTimeout(debounce);
       watcher.close();
@@ -789,11 +847,14 @@ async function runThemeBuildWatch(file, filePath, options) {
   });
 }
 
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerTheme(program) {
   const theme = program
     .command('theme')
     .description('Theme tools — build, export, and manage themes')
-    .action((options, cmd) => {
+    .action((/** @type {unknown} */ options, /** @type {import('commander').Command} */ cmd) => {
       // Parent group has no default behaviour. If the user passed an
       // unknown subcommand (e.g. `astryx theme bogus`), Commander hands it to
       // us as a positional in cmd.args — exit 1 with a clear error.
@@ -817,7 +878,7 @@ export function registerTheme(program) {
       '-w, --watch',
       'Rebuild automatically when the theme file changes (Ctrl-C to stop)',
     )
-    .action(async (file, options) => {
+    .action(async (/** @type {string} */ file, /** @type {{out?: string, watch?: boolean}} */ options) => {
       const filePath = path.resolve(process.cwd(), file);
       const json = program.opts().json || false;
 
@@ -847,7 +908,8 @@ export function registerTheme(program) {
       try {
         themeDef = await extractThemeDefinition(filePath);
       } catch (e) {
-        cliError(e.message, {code: ERROR_CODES.ERR_THEME_LOAD});
+        const err = /** @type {Error} */ (e);
+        cliError(err.message, {code: ERROR_CODES.ERR_THEME_LOAD});
         return;
       }
 
@@ -993,7 +1055,10 @@ export function registerTheme(program) {
       const augmentationSource = resolvedTheme || themeDef;
       const variantDecl = await generateVariantDeclarationsAsync(augmentationSource);
       const variantsFileName = variantDecl ? `${baseName}.variants.d.ts` : null;
-      const variantDtsPath = variantDecl ? path.join(outDir, variantsFileName) : null;
+      const variantDtsPath =
+        variantDecl && variantsFileName
+          ? path.join(outDir, variantsFileName)
+          : null;
       const variantContent = variantDecl
         ? generatedHeader(sourceRelative, 'ts', buildCommand) + variantDecl
         : null;
@@ -1014,11 +1079,12 @@ export function registerTheme(program) {
         {dest: jsPath, content: jsContent},
         {dest: dtsPath, content: dtsContent},
       ];
-      if (variantDtsPath) {
+      if (variantDtsPath && variantContent) {
         writes.push({dest: variantDtsPath, content: variantContent});
       }
 
       fs.mkdirSync(outDir, {recursive: true});
+      /** @type {Array<{tmp: string, dest: string}>} */
       const staged = [];
       try {
         for (const w of writes) {
@@ -1034,7 +1100,7 @@ export function registerTheme(program) {
         for (const s of staged) {
           try { fs.rmSync(s.tmp, {force: true}); } catch { /* best-effort */ }
         }
-        const msg = `Failed to write theme outputs: ${err.message}`;
+        const msg = `Failed to write theme outputs: ${/** @type {Error} */ (err).message}`;
         cliError(msg, {code: ERROR_CODES.ERR_WRITE_FAILED});
         return;
       }
@@ -1045,7 +1111,7 @@ export function registerTheme(program) {
         humanLog(`  ${size} KB`);
         humanLog(`✓ ${path.relative(process.cwd(), jsPath)}`);
         humanLog(`✓ ${path.relative(process.cwd(), dtsPath)}`);
-        if (variantDtsPath) {
+        if (variantDtsPath && variantDecl) {
           const augCount = (variantDecl.match(/': true;/g) || []).length;
           humanLog(`✓ ${path.relative(process.cwd(), variantDtsPath)} (${augCount} type augmentations)`);
         }
@@ -1061,7 +1127,7 @@ export function registerTheme(program) {
             css: path.relative(process.cwd(), outPath),
             js: path.relative(process.cwd(), jsPath),
             dts: path.relative(process.cwd(), dtsPath),
-            ...(variantDecl ? {variantsDts: path.relative(process.cwd(), variantDtsPath)} : {}),
+            ...(variantDecl && variantDtsPath ? {variantsDts: path.relative(process.cwd(), variantDtsPath)} : {}),
           },
           warnings: warningMessages,
         });
@@ -1108,15 +1174,21 @@ Or with a <link> tag:
     .description('List themes available to add')
     .action(async () => {
       const json = program.opts().json || false;
+      /** @type {import('../../types/theme').ThemeListResponse} */
       let result;
       try {
-        result = await themeAdd(undefined, {list: true, cwd: process.cwd()});
+        result = /** @type {import('../../types/theme').ThemeListResponse} */ (
+          await themeAdd(undefined, {list: true, cwd: process.cwd()})
+        );
       } catch (e) {
-        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
+        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
         return;
       }
 
-      if (json) return jsonOut(result.type, result.data);
+      // theme.list is not registered in CLIResponseType (base.d.ts, owned by the
+      // coordinator) — cast the discriminant until it is added there.
+      if (json) return jsonOut(/** @type {any} */ (result.type), result.data);
 
       const themes = result.data;
       if (themes.length === 0) {
@@ -1130,7 +1202,7 @@ Or with a <link> tag:
         if (t.description) humanLog(`    ${t.description}`);
       }
       humanLog('\nUsage:');
-      humanLog('  astryx theme add <slug> [target-path]   Scaffold a theme file you own\n');
+      humanLog(`  ${getCliInvocation()} theme add <slug> [target-path]   Scaffold a theme file you own\n`);
     });
 
   theme
@@ -1138,49 +1210,32 @@ Or with a <link> tag:
     .description('Scaffold a theme into your project as editable source')
     .option('-f, --overwrite', 'Overwrite existing files without prompting')
     .option('--list', 'List available themes')
-    .action(async (slug, targetPath, options) => {
+    .action(async (/** @type {string | undefined} */ slug, /** @type {string | undefined} */ targetPath, /** @type {{list?: boolean, overwrite?: boolean}} */ options) => {
       const json = program.opts().json || false;
 
-      // Only prompt with a real TTY on stdin — a piped/redirected stdin would
-      // make clack hang. Non-interactive callers fall through to the API's
-      // ERR_FILE_EXISTS guard.
-      const interactive =
-        !json && !isNonInteractive({json}) && Boolean(process.stdin.isTTY);
-      if (slug && !options.list && !options.overwrite && interactive) {
-        const collision = await detectThemeCollision(slug, targetPath);
-        if (collision) {
-          const rel = path.relative(process.cwd(), collision) || collision;
-          const p = await import('@clack/prompts');
-          const confirmed = await p.confirm({
-            message: `Overwrite existing file ${rel}?`,
-            initialValue: false,
-          });
-          if (p.isCancel(confirmed)) {
-            p.cancel('Cancelled.');
-            return;
-          }
-          if (!confirmed) {
-            humanLog('Aborted. Re-run with --overwrite to replace the file.');
-            return;
-          }
-          options.overwrite = true;
-        }
-      }
-
+      // The CLI is non-interactive: never prompt to confirm an overwrite.
+      // Existing files require an explicit --overwrite; otherwise themeAdd's
+      // ERR_FILE_EXISTS guard rejects the write.
+      /** @type {import('../../types/theme').ThemeListResponse | import('../../types/theme').ThemeAddResponse} */
       let result;
       try {
-        result = await themeAdd(slug, {
-          list: options.list,
-          targetPath,
-          overwrite: options.overwrite,
-          cwd: process.cwd(),
-        });
+        result = /** @type {import('../../types/theme').ThemeListResponse | import('../../types/theme').ThemeAddResponse} */ (
+          await themeAdd(slug, {
+            list: options.list,
+            targetPath,
+            overwrite: options.overwrite,
+            cwd: process.cwd(),
+          })
+        );
       } catch (e) {
-        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
+        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
         return;
       }
 
-      if (json) return jsonOut(result.type, result.data);
+      // theme.list/theme.add are not registered in CLIResponseType (base.d.ts,
+      // owned by the coordinator) — cast the discriminant until they are added.
+      if (json) return jsonOut(/** @type {any} */ (result.type), result.data);
 
       if (result.type === 'theme.list') {
         const themes = result.data;
@@ -1191,7 +1246,7 @@ Or with a <link> tag:
           if (t.description) humanLog(`    ${t.description}`);
         }
         humanLog('\nUsage:');
-        humanLog('  astryx theme add <slug> [target-path]   Scaffold a theme file you own\n');
+        humanLog(`  ${getCliInvocation()} theme add <slug> [target-path]   Scaffold a theme file you own\n`);
         return;
       }
 
@@ -1219,40 +1274,3 @@ This is your copy of the ${displayName} theme — edit ${entry} to make it your
     });
 }
 
-/**
- * First existing file that scaffolding <slug> into <targetPath> would clobber,
- * or null. Used to prompt before invoking the API; the API re-validates and
- * owns any authoritative error.
- *
- * @param {string} slug
- * @param {string} [targetPath]
- * @returns {Promise<string|null>}
- */
-async function detectThemeCollision(slug, targetPath) {
-  let themes;
-  try {
-    themes = listThemes();
-  } catch {
-    return null;
-  }
-  const match = themes.find(t => t.slug.toLowerCase() === slug.toLowerCase());
-  if (!match) return null;
-
-  const rawTarget = targetPath || path.join('src', 'themes', match.slug);
-  let resolvedDir;
-  try {
-    // Fail soft (null) on traversal; the API surfaces the real error.
-    const {assertWithin} = await import('../utils/path-safety.mjs');
-    resolvedDir = assertWithin(rawTarget, process.cwd(), {
-      label: 'theme target path',
-    });
-  } catch {
-    return null;
-  }
-
-  for (const name of match.files) {
-    const dest = path.join(resolvedDir, name);
-    if (fs.existsSync(dest)) return dest;
-  }
-  return null;
-}