@astryxdesign/cli 0.1.6 → 0.1.7-canary.04cd8f7

package/src/codemods/transforms/v0.1.7/migrate-table-tableprops-to-direct-props.mjs

@@ -0,0 +1,188 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Migrate Table tableProps to direct root props
+ * @see https://github.com/facebook/astryx/issues/3679
+ *
+ * `tableProps` (typed HTMLAttributes<HTMLTableElement>, nesting HTML
+ * attributes one level deep) is deprecated. As of v0.1.7, <Table> honors
+ * className/style/xstyle directly and spreads all other BaseProps
+ * (id, aria-*, data-*, event handlers, ...) onto the root <table>, with
+ * direct props taking precedence over tableProps.
+ *
+ * This codemod lifts object-literal `tableProps` keys into sibling JSX
+ * props:
+ *
+ * - tableProps={{className: 'x', style: s}} → className="x" style={s}
+ * - String-literal keys ('aria-label', 'data-testid') become hyphenated
+ *   JSX attributes.
+ * - Keys that collide with an existing sibling attribute (or fail the
+ *   attribute-name guard) are kept inside a shrunken tableProps with a
+ *   trailing TODO comment for manual migration.
+ * - Dynamic values (tableProps={props}, tableProps={fn()}, objects with
+ *   spreads/computed keys/methods) are left untouched with a TODO comment.
+ *
+ * Only elements whose name resolves to a `Table` import (alias-aware)
+ * from an Astryx core source are rewritten. No import changes are needed.
+ */
+
+export const meta = {
+  title: 'Migrate Table tableProps to direct root props',
+  description:
+    'Lifts object-literal `tableProps` keys on <Table> into sibling JSX props ' +
+    '(className, style, id, aria-*, data-*, event handlers). Dynamic or ' +
+    'colliding entries are kept and annotated with a TODO comment.',
+  pr: '#3679',
+};
+
+/** Import sources that provide the Astryx Table component. */
+const TABLE_IMPORT_SOURCES = new Set([
+  '@astryxdesign/core',
+  '@astryxdesign/core/Table',
+  '@xds/core',
+  '@xds/core/Table',
+]);
+
+/** Keys must be valid JSX attribute names to be lifted. */
+const LIFTABLE_KEY_RE = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+
+const TODO_COMMENT =
+  ' TODO(astryx): tableProps is deprecated — merge these into direct props manually ';
+
+/**
+ * Extract the static key name from an object property, or null when the
+ * property is not a simple liftable entry (spread, computed key, method,
+ * getter/setter, non-string literal key).
+ */
+function getPropertyKeyName(prop) {
+  if (prop.type !== 'ObjectProperty' && prop.type !== 'Property') return null;
+  // espree-style Property nodes: skip methods and accessors
+  if (prop.method || (prop.kind != null && prop.kind !== 'init')) return null;
+  if (prop.computed) return null;
+  const key = prop.key;
+  if (key.type === 'Identifier') return key.name;
+  if (
+    (key.type === 'StringLiteral' || key.type === 'Literal') &&
+    typeof key.value === 'string'
+  ) {
+    return key.value;
+  }
+  return null;
+}
+
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  // --- 1. Track local names for the Table import (alias-aware) ---
+  const tableLocals = new Set();
+  root.find(j.ImportDeclaration).forEach((path) => {
+    if (!TABLE_IMPORT_SOURCES.has(path.node.source.value)) return;
+    for (const spec of path.node.specifiers ?? []) {
+      if (spec.type === 'ImportSpecifier' && spec.imported.name === 'Table') {
+        tableLocals.add(spec.local.name);
+      }
+    }
+  });
+
+  if (tableLocals.size === 0) return undefined;
+
+  function attachTodo(attr) {
+    if (!attr.comments) attr.comments = [];
+    if (attr.comments.some((c) => c.value === TODO_COMMENT)) return;
+    attr.comments.push(j.commentBlock(TODO_COMMENT, false, true));
+    hasChanges = true;
+  }
+
+  function buildAttributeValue(valueNode) {
+    if (
+      valueNode.type === 'StringLiteral' ||
+      (valueNode.type === 'Literal' && typeof valueNode.value === 'string')
+    ) {
+      return j.stringLiteral(valueNode.value);
+    }
+    return j.jsxExpressionContainer(valueNode);
+  }
+
+  // --- 2. Rewrite tableProps on tracked <Table> elements ---
+  root.find(j.JSXOpeningElement).forEach((path) => {
+    const name = path.node.name;
+    const componentName = name.type === 'JSXIdentifier' ? name.name : null;
+    if (!componentName || !tableLocals.has(componentName)) return;
+
+    const attrs = path.node.attributes;
+    const tablePropsAttr = attrs.find(
+      (a) => a.type === 'JSXAttribute' && a.name?.name === 'tableProps',
+    );
+    if (!tablePropsAttr) return;
+
+    const value = tablePropsAttr.value;
+    const isObjectLiteral =
+      value?.type === 'JSXExpressionContainer' &&
+      value.expression.type === 'ObjectExpression';
+
+    // Dynamic case: tableProps={identifier}, tableProps={fn()}, ... —
+    // leave the attribute untouched and warn via a trailing comment
+    // (api.report is a stub; comments are the only warning channel).
+    if (!isObjectLiteral) {
+      attachTodo(tablePropsAttr);
+      return;
+    }
+
+    const obj = value.expression;
+
+    // Objects containing spreads, computed keys, or methods are treated
+    // as dynamic: no partial lift, just the TODO comment.
+    const allSimple = obj.properties.every(
+      (prop) => getPropertyKeyName(prop) !== null,
+    );
+    if (!allSimple) {
+      attachTodo(tablePropsAttr);
+      return;
+    }
+
+    const lifted = [];
+    const kept = [];
+    for (const prop of obj.properties) {
+      const keyName = getPropertyKeyName(prop);
+      const collidesWithSibling = attrs.some(
+        (a) => a.type === 'JSXAttribute' && a.name?.name === keyName,
+      );
+      const collidesWithLifted = lifted.some(
+        (a) => a.name.name === keyName,
+      );
+      if (
+        !LIFTABLE_KEY_RE.test(keyName) ||
+        collidesWithSibling ||
+        collidesWithLifted
+      ) {
+        kept.push(prop);
+        continue;
+      }
+      lifted.push(
+        j.jsxAttribute(
+          j.jsxIdentifier(keyName),
+          buildAttributeValue(prop.value),
+        ),
+      );
+    }
+
+    const tablePropsIdx = attrs.indexOf(tablePropsAttr);
+    if (kept.length === 0) {
+      // All keys lifted — replace tableProps with the sibling attributes.
+      attrs.splice(tablePropsIdx, 1, ...lifted);
+      hasChanges = true;
+    } else {
+      // Some keys collide or fail the name guard — keep only those in a
+      // shrunken tableProps and flag it for manual migration.
+      attrs.splice(tablePropsIdx, 0, ...lifted);
+      obj.properties = kept;
+      attachTodo(tablePropsAttr);
+      if (lifted.length > 0) hasChanges = true;
+    }
+  });
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/src/codemods/transforms/v0.1.7/rename-table-renderprops-styles-to-xstyle.mjs

@@ -0,0 +1,197 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Rename Table render-prop `styles` field to `xstyle`
+ *
+ * As of v0.1.7, the Table plugin render-prop interfaces
+ * (`TableRenderProps`, `HeaderRowRenderProps`, `HeaderCellRenderProps`,
+ * `BodyRowRenderProps`, `BodyCellRenderProps`, `ScrollWrapperRenderProps`)
+ * and the `scrollWrapper` component contract renamed their StyleX array
+ * field `styles` -> `xstyle`, matching the prop name sub-components
+ * receive it under.
+ *
+ * Custom plugin authors read `props.styles` and write `styles: [...]`
+ * inside their transform functions (`transformTable`, `transformHeaderRow`,
+ * `transformHeaderCell`, `transformBodyRow`, `transformBodyCell`,
+ * `transformScrollWrapper`). This codemod renames those reads and writes.
+ *
+ * A blind global `styles` rename is unsafe — `styles` is also the
+ * conventional local name for a `stylex.create({...})` bag, which is
+ * unrelated. So this transform only rewrites `styles` when it is
+ * *scoped to a render-prop object*: a function parameter (or a variable)
+ * whose TypeScript type annotation is one of the render-prop interfaces.
+ * Within such a scope it rewrites:
+ *
+ *   - `<param>.styles`            -> `<param>.xstyle`   (member reads/writes)
+ *   - `{ ..., styles: [...] }`    -> `{ ..., xstyle: [...] }`
+ *     for object literals that carry the render-prop shape (a sibling
+ *     `htmlProps` key), and object literals assigned/spread from the
+ *     tracked render-prop binding.
+ *
+ * Ambiguous cases that can't be resolved from types alone (e.g. a
+ * render-prop object passed through an untyped variable, or a `styles`
+ * bag from `stylex.create`) are left untouched, so the transform never
+ * renames an unrelated `styles`. This mirrors the conservative,
+ * scope-limited approach of the sibling
+ * `migrate-table-tableprops-to-direct-props` codemod.
+ */
+
+export const meta = {
+  title: 'Rename Table render-prop `styles` field to `xstyle`',
+  description:
+    'Renames the `styles` StyleX-array field to `xstyle` on Table plugin ' +
+    'render-prop objects (TableRenderProps, HeaderRowRenderProps, ' +
+    'HeaderCellRenderProps, BodyRowRenderProps, BodyCellRenderProps, ' +
+    'ScrollWrapperRenderProps) inside plugin transform functions. Reads ' +
+    '(`props.styles`) and writes (`styles: [...]`) are renamed; unrelated ' +
+    '`styles` bindings (e.g. from stylex.create) are left untouched.',
+};
+
+/** The render-prop interface type names whose `styles` field became `xstyle`. */
+const RENDER_PROP_TYPES = new Set([
+  'TableRenderProps',
+  'HeaderRowRenderProps',
+  'HeaderCellRenderProps',
+  'BodyRowRenderProps',
+  'BodyCellRenderProps',
+  'ScrollWrapperRenderProps',
+]);
+
+/** Resolve the base type name from a TS type annotation node. */
+function typeNameOf(typeAnnotation) {
+  // `x: TableRenderProps`
+  const t = typeAnnotation?.typeAnnotation ?? typeAnnotation;
+  if (!t) return null;
+  if (t.type === 'TSTypeReference' && t.typeName?.type === 'Identifier') {
+    return t.typeName.name;
+  }
+  return null;
+}
+
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  // --- 1. Collect binding names typed as a render-prop interface. ---
+  // Function/arrow params: (props: TableRenderProps) => ...
+  const renderPropBindings = new Set();
+
+  function collectParam(param) {
+    if (
+      param.type === 'Identifier' &&
+      RENDER_PROP_TYPES.has(typeNameOf(param.typeAnnotation))
+    ) {
+      renderPropBindings.add(param.name);
+    }
+  }
+
+  root
+    .find(j.Function)
+    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+  root
+    .find(j.FunctionDeclaration)
+    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+  root
+    .find(j.FunctionExpression)
+    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+  root
+    .find(j.ArrowFunctionExpression)
+    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+
+  // Variable declarations: `const rp: BodyCellRenderProps = ...`
+  root.find(j.VariableDeclarator).forEach((p) => {
+    const id = p.node.id;
+    if (
+      id?.type === 'Identifier' &&
+      RENDER_PROP_TYPES.has(typeNameOf(id.typeAnnotation))
+    ) {
+      renderPropBindings.add(id.name);
+    }
+  });
+
+  const hasTypedBinding = renderPropBindings.size > 0;
+
+  // Also detect object literals that are structurally a render-prop object.
+  // Two shapes qualify:
+  //  1. An `htmlProps` sibling key alongside a `styles`/`xstyle` key — the
+  //     literal shape a transform function returns from scratch.
+  //  2. A spread of a tracked render-prop binding (`{...props, styles: [...]}`)
+  //     — the common "carry the render-prop object forward, override styles"
+  //     shape. (Only counts when `renderPropBindings` is non-empty.)
+  function isRenderPropShapedObject(objExpr) {
+    if (objExpr.type !== 'ObjectExpression') return false;
+    const keyNames = objExpr.properties
+      .map((pr) =>
+        pr.type === 'ObjectProperty' || pr.type === 'Property'
+          ? pr.key?.name ?? pr.key?.value
+          : null,
+      )
+      .filter(Boolean);
+    if (keyNames.includes('htmlProps') && keyNames.includes('styles')) {
+      return true;
+    }
+    // Spread of a tracked render-prop binding.
+    const spreadsRenderProp = objExpr.properties.some(
+      (pr) =>
+        (pr.type === 'SpreadElement' || pr.type === 'ExperimentalSpreadProperty') &&
+        pr.argument?.type === 'Identifier' &&
+        renderPropBindings.has(pr.argument.name),
+    );
+    return spreadsRenderProp && keyNames.includes('styles');
+  }
+
+  if (!hasTypedBinding) {
+    // Nothing is typed as a render-prop interface. Only rewrite clearly
+    // render-prop-shaped object literals (htmlProps + styles siblings);
+    // never touch bare `styles` in this file (too ambiguous).
+    let touched = false;
+    root.find(j.ObjectExpression).forEach((p) => {
+      if (!isRenderPropShapedObject(p.node)) return;
+      for (const prop of p.node.properties) {
+        if (
+          (prop.type === 'ObjectProperty' || prop.type === 'Property') &&
+          !prop.computed &&
+          prop.key?.type === 'Identifier' &&
+          prop.key.name === 'styles'
+        ) {
+          prop.key.name = 'xstyle';
+          touched = true;
+        }
+      }
+    });
+    if (!touched) return undefined;
+    return root.toSource({quote: 'single'});
+  }
+
+  // --- 2. Rewrite `<binding>.styles` member access -> `.xstyle`. ---
+  root.find(j.MemberExpression).forEach((p) => {
+    const {object, property, computed} = p.node;
+    if (computed) return;
+    if (property?.type !== 'Identifier' || property.name !== 'styles') return;
+    if (object?.type !== 'Identifier' || !renderPropBindings.has(object.name)) {
+      return;
+    }
+    property.name = 'xstyle';
+    hasChanges = true;
+  });
+
+  // --- 3. Rewrite `styles:` keys on render-prop-shaped object literals. ---
+  root.find(j.ObjectExpression).forEach((p) => {
+    if (!isRenderPropShapedObject(p.node)) return;
+    for (const prop of p.node.properties) {
+      if (
+        (prop.type === 'ObjectProperty' || prop.type === 'Property') &&
+        !prop.computed &&
+        prop.key?.type === 'Identifier' &&
+        prop.key.name === 'styles'
+      ) {
+        prop.key.name = 'xstyle';
+        hasChanges = true;
+      }
+    }
+  });
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/src/commands/agent-docs.mjs

@@ -22,7 +22,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {findCoreDir, CLI_ROOT} from '../utils/paths.mjs';
 import {assertWithin, PathSafetyError} from '../utils/path-safety.mjs';
-import {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
 import {discoverComponents} from '../lib/component-discovery.mjs';
 import {humanLog} from '../lib/json.mjs';
 import {cliError} from '../lib/cli-error.mjs';
@@ -144,8 +144,8 @@ export function detectStylingSystem(targetDir) {
  * configured (see {@link detectStylingSystem}) so the agent never reaches for a
  * styling path that isn't compiled here.
  */
-export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPrefix(), stylingSystem = 'css'} = {}) {
-  const run = `${runPrefix} astryx`;
+export function generateCompressedIndex(version, {coreDir, invocation = getCliInvocation(), stylingSystem = 'css'} = {}) {
+  const run = invocation;
   const lines = [MARKER_START];
 
   // Component count from live discovery
@@ -197,6 +197,20 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPre
     lines.push("- Custom styling: component props first; else style/className with tokens — var(--color-*|--spacing-*|--radius-*). No raw hex/px. (No StyleX/Tailwind compiler here — don't use xstyle/utility classes.)");
   }
   lines.push('- Tokens for every value (`astryx docs tokens`). Brand/accent via `astryx theme` — never override --color-* in :root.');
+  // Self-check — post-generation pass. Validated via vibe tests (internal/vibe-tests/
+  // prompt-purity-test): on complex multi-step UIs the rules above alone still leave raw
+  // CSS in ~11-13% of runs; a re-read-and-fix pass cuts that ~4x at negligible token cost.
+  // The fix names the sanctioned escape hatch for the configured system.
+  const selfCheckFix = {
+    stylex:
+      'replace any className=, style={{…}}, raw <div>/<span> layout, imported .css/@apply, or hardcoded #hex/px with the component or the xstyle prop + a token',
+    tailwind:
+      'replace any style={{…}}, raw <div>/<span> layout, imported .css/@apply, or hardcoded/arbitrary value (e.g. bg-[#fff], p-[13px]) with the component or a token-backed utility',
+    css: 'replace any raw <div>/<span> layout, imported .css/@apply, or hardcoded value (#hex, 16px) with the component or a token (var(--color-*|--spacing-*|…))',
+  };
+  lines.push(
+    `- SELF-CHECK before you finish: re-read the file and ${selfCheckFix[stylingSystem] ?? selfCheckFix.css}. If unsure a component/prop exists, run \`astryx component <Name>\` / \`astryx search "<thing>"\`; don't hand-roll CSS.`,
+  );
   lines.push('');
 
   // Command reference — build/template/component are covered in WORKFLOW above.
@@ -378,7 +392,7 @@ export function removeAgentDocs(targetDir) {
 
 /**
  * Programmatic entry point for installing agent docs.
- * Used by the init wizard, upgrade command, and agent-docs command.
+ * Used by the init command, upgrade command, and agent-docs command.
  *
  * Strategy (when no agent/paths specified):
  * - Discover all existing agent doc files and update them
@@ -396,9 +410,9 @@ export function removeAgentDocs(targetDir) {
 export function installAgentDocs(targetDir, {zh = false, lang, agent, paths, onlyReplace = false} = {}) {
   const coreDir = findCoreDir(targetDir);
   const version = getXdsVersion(coreDir);
-  const runPrefix = getRunPrefix(targetDir);
+  const invocation = getCliInvocation(targetDir);
   const stylingSystem = detectStylingSystem(targetDir);
-  const compressedIndex = generateCompressedIndex(version, {coreDir, zh, lang, runPrefix, stylingSystem});
+  const compressedIndex = generateCompressedIndex(version, {coreDir, zh, lang, invocation, stylingSystem});
   const written = [];
 
   // Explicit paths override everything
@@ -524,8 +538,7 @@ export function registerAgentDocs(program) {
         throw err;
       }
 
-      const runPrefix = getRunPrefix(targetDir);
-      const run = `${runPrefix} astryx`;
+      const run = getCliInvocation(targetDir);
 
       for (const t of targets) {
         humanLog(`✓ ${t}`);

package/src/commands/agent-docs.test.mjs

@@ -43,6 +43,26 @@ describe('generateCompressedIndex', () => {
     expect(result).toMatch(/never override --color-/);
   });
 
+  it('includes the post-generation self-check rule', () => {
+    const result = generateCompressedIndex('1.0.0');
+    expect(result).toContain('SELF-CHECK before you finish');
+    expect(result).toMatch(/re-read the file/);
+    expect(result).toMatch(/don't hand-roll CSS/);
+  });
+
+  it('tailors the self-check to the styling system (xstyle for StyleX, not className for Tailwind)', () => {
+    // StyleX path: className/inline style are veers; the fix is the xstyle prop + a token
+    const stylex = generateCompressedIndex('1.0.0', {stylingSystem: 'stylex'});
+    const stylexSelfCheck = stylex.split('\n').find(l => l.includes('SELF-CHECK'));
+    expect(stylexSelfCheck).toMatch(/xstyle/);
+    expect(stylexSelfCheck).toMatch(/className=/);
+    // className IS the system in Tailwind — it must NOT be flagged
+    const tailwind = generateCompressedIndex('1.0.0', {stylingSystem: 'tailwind'});
+    const tailwindSelfCheck = tailwind.split('\n').find(l => l.includes('SELF-CHECK'));
+    expect(tailwindSelfCheck).toBeDefined();
+    expect(tailwindSelfCheck).not.toMatch(/className=/);
+  });
+
   it('defaults to the CSS-variable styling path (no compiler)', () => {
     const result = generateCompressedIndex('1.0.0');
     expect(result).toMatch(/style\/className with tokens/);
@@ -68,17 +88,24 @@ describe('generateCompressedIndex', () => {
     expect(result).toMatch(/after any @astryxdesign\/core bump/);
   });
 
-  it('states the runPrefix once in the CLI header', () => {
-    const result = generateCompressedIndex('1.0.0', {runPrefix: 'yarn'});
+  it('states the invocation once in the CLI header (yarn)', () => {
+    const result = generateCompressedIndex('1.0.0', {invocation: 'yarn astryx'});
     expect(result).toContain('yarn astryx <cmd>');
     expect(result).not.toContain('npx astryx');
   });
 
-  it('uses pnpm exec prefix', () => {
-    const result = generateCompressedIndex('1.0.0', {runPrefix: 'pnpm exec'});
+  it('uses the pnpm exec invocation', () => {
+    const result = generateCompressedIndex('1.0.0', {invocation: 'pnpm exec astryx'});
     expect(result).toContain('pnpm exec astryx <cmd>');
     expect(result).not.toContain('npx astryx');
   });
+
+  it('uses the scoped package for one-off (uninstalled) runs so agents never hit the bare name', () => {
+    const result = generateCompressedIndex('1.0.0', {invocation: 'npx @astryxdesign/cli'});
+    expect(result).toContain('npx @astryxdesign/cli <cmd>');
+    // The header defines the mapping; the bare "run every command as `npx astryx`" footgun must be absent.
+    expect(result).not.toContain('npx astryx <cmd>');
+  });
 });
 
 describe('detectStylingSystem', () => {

package/src/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,16 +17,15 @@ 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';
+import {themeAdd} from '../api/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
@@ -500,7 +499,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}';
@@ -1130,7 +1129,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
@@ -1141,32 +1140,9 @@ Or with a <link> tag:
     .action(async (slug, targetPath, 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.
       let result;
       try {
         result = await themeAdd(slug, {
@@ -1191,7 +1167,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 +1195,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;
-}