@astryxdesign/cli 0.1.0-canary.7f46cdb → 0.1.0-canary.9745d0a

package/bin/astryx.mjs

@@ -12,10 +12,25 @@
 //
 // `node-version.mjs` is intentionally dependency-free so it loads on the
 // unsupported runtimes this guard protects against.
-import {
-  isNodeVersionSupported,
-  unsupportedNodeMessage,
-} from '../src/lib/node-version.mjs';
+//
+// Sibling `src/` modules are resolved by this bin's REAL path. When the CLI is
+// installed as a package, `npx astryx` runs this file through the
+// `node_modules/.bin/astryx` symlink, and some Node versions resolve relative
+// specifiers from the symlink's directory (→ `node_modules/src/...`) rather
+// than the real package — breaking bare `../src/...` imports with a cryptic
+// ERR_MODULE_NOT_FOUND. realpath-ing `import.meta.url` makes these imports
+// resolve correctly however the bin is invoked (symlink, copy, or Windows
+// shim). Uses only built-ins, so the version gate below still runs first.
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {realpathSync} from 'node:fs';
+import {dirname, join} from 'node:path';
+
+const binDir = dirname(realpathSync(fileURLToPath(import.meta.url)));
+const importSrc = rel =>
+  import(pathToFileURL(join(binDir, '..', 'src', rel)).href);
+
+const {isNodeVersionSupported, unsupportedNodeMessage} =
+  await importSrc('lib/node-version.mjs');
 
 if (!isNodeVersionSupported(process.versions.node)) {
   const msg = unsupportedNodeMessage(process.versions.node);
@@ -39,9 +54,9 @@ if (!isNodeVersionSupported(process.versions.node)) {
 
 // Imports that transitively load `styleText` must happen AFTER the gate above,
 // so they are dynamically imported here rather than at the top of the module.
-const {program} = await import('../src/index.mjs');
-const {isJsonMode, toErrorEnvelope} = await import('../src/lib/json.mjs');
-const {handleCommanderError} = await import('../src/lib/json-shim.mjs');
+const {program} = await importSrc('index.mjs');
+const {isJsonMode, toErrorEnvelope} = await importSrc('lib/json.mjs');
+const {handleCommanderError} = await importSrc('lib/json-shim.mjs');
 
 /**
  * Top-level error boundary (contract guarantee #4): an uncaught throw must

package/docs/icons.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Icons reference doc: semantic icon names available in XDS
+ * @file Icons reference doc: semantic icon names available in Astryx
  */
 
 /** @type {import('../../core/src/docs-types').ReferenceDoc} */

package/docs/migration.doc.mjs

@@ -234,7 +234,7 @@ export function AppRoot({children}: {children: React.ReactNode}) {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: `We are migrating this existing Tailwind/shadcn app to XDS incrementally.
+          code: `We are migrating this existing Tailwind/shadcn app to Astryx incrementally.
 
 First run:
 - npx astryx docs migration --dense
@@ -242,7 +242,7 @@ First run:
 - npx astryx docs styling --dense
 - npx astryx template AppShellTopNavWithSideNav --skeleton
 
-Then migrate one route or shell surface at a time. Keep business logic and routing intact. Replace shadcn/Radix/Tailwind primitives with XDS components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.`,
+Then migrate one route or shell surface at a time. Keep business logic and routing intact. Replace shadcn/Radix/Tailwind primitives with Astryx components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.`,
         },
       ],
     },

package/docs/shape.doc.mjs

@@ -44,7 +44,7 @@ export const docs = {
           type: 'code',
           lang: 'css',
           label: 'Concentric radius formula',
-          code: `/* Automatic in XDS Card */
+          code: `/* Automatic in Astryx Card */
 --card-concentric-radius: max(0px, calc(var(--_card-radius) - var(--card-padding)));`,
         },
       ],

package/docs/styling.doc.mjs

@@ -231,7 +231,7 @@ const overrides = stylex.create({
       content: [
         {
           type: 'prose',
-          text: 'When external CSS needs to target an XDS component by prop or state, combine the stable component class with reflected data attributes. The component class identifies the component (`.astryx-button`, `.astryx-card`); data attributes identify the axis and value (`data-variant`, `data-size`, `data-level`, etc.). This is the preferred selector surface for new CSS because it is explicit and collision-resistant.',
+          text: 'When external CSS needs to target an Astryx component by prop or state, combine the stable component class with reflected data attributes. The component class identifies the component (`.astryx-button`, `.astryx-card`); data attributes identify the axis and value (`data-variant`, `data-size`, `data-level`, etc.). This is the preferred selector surface for new CSS because it is explicit and collision-resistant.',
         },
         {
           type: 'code',
@@ -273,7 +273,7 @@ const overrides = stylex.create({
       content: [
         {
           type: 'prose',
-          text: 'XDS still emits legacy bare prop/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked` for compatibility with existing apps and built themes. Do not write new CSS against these bare classes. The stable base component classes (`.astryx-button`, `.astryx-card`, etc.) are not deprecated; only the unprefixed prop/state classes are the legacy surface.',
+          text: 'Astryx still emits legacy bare prop/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked` for compatibility with existing apps and built themes. Do not write new CSS against these bare classes. The stable base component classes (`.astryx-button`, `.astryx-card`, etc.) are not deprecated; only the unprefixed prop/state classes are the legacy surface.',
         },
         {
           type: 'code',

package/docs/theme.doc.dense.mjs

@@ -5,8 +5,8 @@
 export const docsDense = {
   description: 'Theme provider, custom themes, light/dark, component overrides',
   sections: [
-    { title: 'Quick Start', content: [null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },
-    { title: 'Themes', content: [null, { type: 'prose', text: 'published: neutral (start here), butter, chocolate, gothic (dark-only), matcha, stone, y2k. @astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },
+    { title: 'Quick Start', content: [null, null, null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },
+    { title: 'Themes', content: [null, null, { type: 'prose', text: 'published: neutral (start here), butter, chocolate, gothic (dark-only), matcha, stone, y2k. @astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },
     { title: 'Props', content: [null] },
     { title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },
     { title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (color, typography, radius, motion) + explicit token overrides + component overrides. color derives full palette from accent hex via HCT.' }, null, null] },

package/docs/theme.doc.mjs

@@ -14,6 +14,12 @@ export const docs = {
       title: 'Quick Start',
   category: 'guide',
       content: [
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Install a theme package',
+          code: 'npm install @astryxdesign/theme-neutral',
+        },
         {
           type: 'code',
           lang: 'tsx',
@@ -45,6 +51,10 @@ function App() {
   );
 }`,
         },
+        {
+          type: 'prose',
+          text: 'Each theme ships as its own npm package. Install the one you want, then wrap your app in `<Theme>` — the same pattern works for every theme; just swap the package and import name.',
+        },
         {
           type: 'prose',
           text: 'The default import uses runtime style injection, which works everywhere with no build step. The `/built` import skips injection and relies on the pre-compiled CSS file for better performance and SSR support.',
@@ -55,6 +65,10 @@ function App() {
       title: 'Available Themes',
   category: 'guide',
       content: [
+        {
+          type: 'prose',
+          text: 'Install the theme package you want with `npm install @astryxdesign/theme-{name}`, then import its theme object as shown below.',
+        },
         {
           type: 'table',
           headers: ['Theme', 'Import', 'Description'],

package/docs/theme.doc.zh.mjs

@@ -5,8 +5,8 @@
 export const docsZh = {
   description: 'Theme 提供者、自定义主题、亮/暗模式和组件样式覆盖。',
   sections: [
-    { title: '快速开始', content: [null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS（需配合 theme.css）。' }] },
-    { title: '可用主题', content: [null, { type: 'prose', text: '已发布主题：neutral（推荐起点）、butter、chocolate、gothic（仅暗色）、matcha、stone、y2k。@astryxdesign/theme-{name} = 源码版（运行时注入）。@astryxdesign/theme-{name}/built = 优化版（配合 theme.css）。' }] },
+    { title: '快速开始', content: [null, null, null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS（需配合 theme.css）。' }] },
+    { title: '可用主题', content: [null, null, { type: 'prose', text: '已发布主题：neutral（推荐起点）、butter、chocolate、gothic（仅暗色）、matcha、stone、y2k。@astryxdesign/theme-{name} = 源码版（运行时注入）。@astryxdesign/theme-{name}/built = 优化版（配合 theme.css）。' }] },
     { title: 'Theme 属性', content: [null] },
     { title: '创建自定义主题', content: [{ type: 'prose', text: '使用 CLI 向导（推荐）或手动 defineTheme。只覆盖与默认值不同的令牌。' }, null] },
     { title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置（typography、radius、motion）+ 显式令牌覆盖 + 组件覆盖。' }, null, null] },

package/docs/working-with-ai.doc.mjs

@@ -34,7 +34,7 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: 'Install @astryxdesign/cli and run `npx astryx agent-docs` to set up your XDS context. Read the generated file.',
+          code: 'Install @astryxdesign/cli and run `npx astryx agent-docs` to set up your Astryx context. Read the generated file.',
         },
         {
           type: 'prose',
@@ -103,7 +103,7 @@ npx astryx agent-docs --agent-docs-path ~/.cursor/rules/xds.mdc`,
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: `Before writing any XDS code, check your knowledge:
+          code: `Before writing any Astryx code, check your knowledge:
 
 1. What is the correct import path for Button?
 2. How do you make an Dialog non-dismissible?
@@ -165,7 +165,7 @@ npx astryx docs tokens --dense`,
       content: [
         {
           type: 'prose',
-          text: 'XDS ships a Model Context Protocol (MCP) server that any MCP-compatible AI tool can connect to. Instead of manually pasting CLI output, the AI can query the XDS design system directly, searching for components, reading full documentation, and pulling code examples on demand.',
+          text: 'Astryx ships a Model Context Protocol (MCP) server that any MCP-compatible AI tool can connect to. Instead of manually pasting CLI output, the AI can query the Astryx design system directly, searching for components, reading full documentation, and pulling code examples on demand.',
         },
         {
           type: 'prose',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.0-canary.7f46cdb",
+  "version": "0.1.0-canary.9745d0a",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -15,7 +15,7 @@
     "url": "https://github.com/facebook/astryx/issues"
   },
   "keywords": [
-    "xds",
+    "astryx",
     "cli",
     "design-system",
     "init",
@@ -54,9 +54,9 @@
     "jscodeshift": "^17.3.0"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.1.0-canary.7f46cdb",
-    "@astryxdesign/lab": "0.1.0-canary.7f46cdb",
-    "@astryxdesign/theme-neutral": "0.1.0-canary.7f46cdb"
+    "@astryxdesign/core": "0.1.0-canary.9745d0a",
+    "@astryxdesign/lab": "0.1.0-canary.9745d0a",
+    "@astryxdesign/theme-neutral": "0.1.0-canary.9745d0a"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {
@@ -70,9 +70,9 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "0.1.0-canary.7f46cdb",
-    "@astryxdesign/lab": "0.1.0-canary.7f46cdb",
-    "@astryxdesign/theme-neutral": "0.1.0-canary.7f46cdb"
+    "@astryxdesign/core": "0.1.0-canary.9745d0a",
+    "@astryxdesign/lab": "0.1.0-canary.9745d0a",
+    "@astryxdesign/theme-neutral": "0.1.0-canary.9745d0a"
   },
   "scripts": {
     "astryx": "node bin/astryx.mjs",

package/src/codemods/__tests__/registry.test.mjs

@@ -16,6 +16,7 @@ describe('registry', () => {
         '0.0.13',
         '0.0.14',
         '0.0.15',
+        '0.1.0',
       ]);
     });
   });

package/src/codemods/registry.mjs

@@ -17,6 +17,7 @@ const registry = new Map([
   ['0.0.13', () => import('./transforms/v0.0.13/index.mjs')],
   ['0.0.14', () => import('./transforms/v0.0.14/index.mjs')],
   ['0.0.15', () => import('./transforms/v0.0.15/index.mjs')],
+  ['0.1.0', () => import('./transforms/v0.1.0/index.mjs')],
 ]);
 
 // Re-export from the shared utility so registry callers and other consumers

package/src/codemods/runner.mjs

@@ -11,7 +11,6 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as p from '@clack/prompts';
-import {getRunPrefix} from '../utils/package-manager.mjs';
 import {humanLog} from '../lib/json.mjs';
 
 // Known corruption patterns that indicate a broken transform.
@@ -87,39 +86,6 @@ function findSourceFiles(dir) {
   return results.sort();
 }
 
-/**
- * Detect the project's formatter and run it on changed files.
- * Tries prettier, then biome. Silently skips if none found.
- *
- * @param {string[]} files - Absolute paths to files that were modified
- * @param {boolean} [silent] - Suppress human-facing output
- */
-async function formatChangedFiles(files, silent = false) {
-  if (files.length === 0) return;
-
-  const {execSync} = await import('node:child_process');
-  const fileArgs = files.map(f => `"${f}"`).join(' ');
-  const prefix = getRunPrefix();
-
-  const formatters = [
-    {name: 'prettier', cmd: `${prefix} prettier --write ${fileArgs}`},
-    {name: 'biome', cmd: `${prefix} biome format --write ${fileArgs}`},
-  ];
-
-  for (const {name, cmd} of formatters) {
-    try {
-      execSync(cmd, {stdio: 'pipe', timeout: 30000});
-      if (!silent)
-        p.log.info(
-          `Formatted ${files.length} file${files.length === 1 ? '' : 's'} with ${name}`,
-        );
-      return;
-    } catch {
-      // Formatter not available or failed — try next
-    }
-  }
-}
-
 /**
  * Validate transform output before writing to disk.
  *
@@ -162,6 +128,86 @@ export function validateOutput(result, source, j, {parse = true} = {}) {
   return {valid: true};
 }
 
+function isConfigCodemod(transformEntry) {
+  return transformEntry.meta?.codemodType === 'config';
+}
+
+const CONFIG_CODEMOD_PATHS = new Set([
+  'package.json',
+  'astryx.config.mjs',
+  'xds.config.mjs',
+]);
+
+function resolveConfigPath(relativePath) {
+  if (!CONFIG_CODEMOD_PATHS.has(relativePath)) {
+    throw new Error(`unsupported config codemod path: ${relativePath}`);
+  }
+  return path.resolve(process.cwd(), relativePath);
+}
+
+function readOptionalConfigFile(relativePath) {
+  const fullPath = resolveConfigPath(relativePath);
+  if (!fs.existsSync(fullPath)) return null;
+  return {path: relativePath, source: fs.readFileSync(fullPath, 'utf-8')};
+}
+
+function getConfigCodemodContext() {
+  return {
+    packageJson: readOptionalConfigFile('package.json'),
+    astryxConfig: readOptionalConfigFile('astryx.config.mjs'),
+    xdsConfig: readOptionalConfigFile('xds.config.mjs'),
+  };
+}
+
+async function runConfigCodemod(transformEntry, {apply, log}) {
+  const {transform} = transformEntry;
+  const api = {config: getConfigCodemodContext()};
+  const result = await transform({path: process.cwd(), source: ''}, api);
+  const errors = result?.errors ?? [];
+  if (errors.length > 0) {
+    for (const error of errors) {
+      log.error(`    ✗ ${error.file ?? 'config'} — ${error.error}`);
+    }
+    return {filesChanged: 0, errors};
+  }
+
+  const changes = result?.changes ?? [];
+  if (changes.length === 0) return {filesChanged: 0, errors: []};
+
+  for (const change of changes) {
+    const fullPath = resolveConfigPath(change.path);
+    if (change.delete) {
+      if (apply) fs.rmSync(fullPath, {force: true});
+      log[apply ? 'success' : 'warn'](
+        `    ${apply ? '✓' : '~'} ${change.path} (delete${apply ? '' : ', dry run'})`,
+      );
+      continue;
+    }
+
+    if (apply) {
+      fs.writeFileSync(fullPath, change.source, 'utf-8');
+    }
+    log[apply ? 'success' : 'warn'](
+      `    ${apply ? '✓' : '~'} ${change.path}${apply ? '' : ' (would change)'}`,
+    );
+  }
+
+  if (changes.length > 0) {
+    const verb = apply ? 'Updated' : 'Would update';
+    log.info(
+      `  ${verb} ${changes.length} config file${changes.length === 1 ? '' : 's'}`,
+    );
+  }
+
+  return {
+    filesChanged: changes.length,
+    writtenFiles: changes
+      .filter(change => !change.delete && path.extname(change.path) !== '.json')
+      .map(change => resolveConfigPath(change.path)),
+    errors: [],
+  };
+}
+
 /**
  * Run codemods against source files.
  *
@@ -197,18 +243,12 @@ export async function runCodemods(
 
   if (files.length === 0) {
     log.warn('No source files found.');
-    return {
-      ok: true,
-      totalFilesChanged: 0,
-      totalTransformsApplied: 0,
-      errors: [],
-      writtenFiles: [],
-      skippedOptional: [],
-    };
+  } else {
+    log.info(
+      `Found ${files.length} source file${files.length === 1 ? '' : 's'}`,
+    );
   }
 
-  log.info(`Found ${files.length} source file${files.length === 1 ? '' : 's'}`);
-
   // Dynamically import jscodeshift
   const jscodeshift = (await import('jscodeshift')).default;
 
@@ -239,6 +279,24 @@ export async function runCodemods(
 
       log.info(`  ${meta.title}`);
 
+      if (isConfigCodemod(transformEntry)) {
+        const result = await runConfigCodemod(transformEntry, {apply, log});
+        if (result.errors.length > 0) {
+          for (const error of result.errors) {
+            errors.push({
+              file: error.file ?? 'config',
+              codemod: name,
+              error: error.error,
+            });
+          }
+        } else if (result.filesChanged > 0) {
+          totalFilesChanged += result.filesChanged;
+          totalTransformsApplied += result.filesChanged;
+          writtenFiles.push(...(result.writtenFiles ?? []));
+        }
+        continue;
+      }
+
       let filesChanged = 0;
 
       for (const filePath of files) {
@@ -323,12 +381,6 @@ export async function runCodemods(
     }
   }
 
-  // Post-codemod formatting: run the project's formatter on changed files
-  // so codemods don't introduce style drift (jscodeshift may change quotes, etc.)
-  if (apply && writtenFiles.length > 0) {
-    await formatChangedFiles(writtenFiles, silent);
-  }
-
   if (totalValidationBlocked > 0) {
     log.warn(
       `${totalValidationBlocked} file${totalValidationBlocked === 1 ? ' was' : 's were'} blocked by validation — no changes written to ${totalValidationBlocked === 1 ? 'that file' : 'those files'}.`,
@@ -366,7 +418,9 @@ export async function runCodemods(
       if (meta.description) {
         log.info(`    ${meta.description}`);
       }
-      log.info(`    Run: astryx upgrade --codemod ${name} --path <dir> --apply`);
+      log.info(
+        `    Run: astryx upgrade --codemod ${name} --path <dir> --apply`,
+      );
     }
   }
 

package/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-config-surfaces.test.mjs

@@ -0,0 +1,116 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyConfigCodemod(files) {
+  const {default: transform} =
+    await import('../migrate-xds-config-surfaces.mjs');
+  const config = {
+    packageJson: files['package.json']
+      ? {path: 'package.json', source: files['package.json']}
+      : null,
+    astryxConfig: files['astryx.config.mjs']
+      ? {path: 'astryx.config.mjs', source: files['astryx.config.mjs']}
+      : null,
+    xdsConfig: files['xds.config.mjs']
+      ? {path: 'xds.config.mjs', source: files['xds.config.mjs']}
+      : null,
+  };
+  return transform({path: process.cwd(), source: ''}, {config});
+}
+
+describe('migrate-xds-config-surfaces', () => {
+  it('extracts package.json xds config into astryx.config.mjs and removes the package key in place', async () => {
+    const input = `{
+    "dependencies": {"@xds/core":"^0.0.15"},
+    "xds"  : {"theme":"neutral","docs":"./src"}
+}
+`;
+
+    const result = await applyConfigCodemod({'package.json': input});
+    expect(result.errors ?? []).toEqual([]);
+    expect(result.changes).toEqual([
+      {
+        path: 'package.json',
+        source: `{
+    "dependencies": {"@xds/core":"^0.0.15"}
+}
+`,
+      },
+      {
+        path: 'astryx.config.mjs',
+        source: `export default {
+  "theme": "neutral",
+  "docs": "./src"
+};
+`,
+      },
+    ]);
+  });
+
+  it('extracts package.json astryx config into astryx.config.mjs too', async () => {
+    const result = await applyConfigCodemod({
+      'package.json': `{"astryx":{"theme":"neutral"}}\n`,
+    });
+    expect(result.changes).toEqual([
+      {path: 'package.json', source: `{}\n`},
+      {
+        path: 'astryx.config.mjs',
+        source: `export default {
+  "theme": "neutral"
+};
+`,
+      },
+    ]);
+  });
+
+  it('bails when package.json contains both xds and astryx config keys', async () => {
+    const result = await applyConfigCodemod({
+      'package.json': `{"xds":{"theme":"default"},"astryx":{"theme":"neutral"}}\n`,
+    });
+    expect(result.errors?.[0]?.error).toMatch(/both xds and astryx/);
+  });
+
+  it('does not rewrite dependency keys in package.json', async () => {
+    const input = `{"dependencies":{"@xds/core":"^0.0.15"}}\n`;
+    const result = await applyConfigCodemod({'package.json': input});
+    expect(result.changes).toEqual([]);
+  });
+
+  it('bails when package config and astryx.config.mjs both exist', async () => {
+    const result = await applyConfigCodemod({
+      'package.json': `{"xds":{"theme":"neutral"}}\n`,
+      'astryx.config.mjs': `export default {};\n`,
+    });
+    expect(result.errors?.[0]?.error).toMatch(/migrate the config manually/);
+  });
+
+  it('bails when package config and xds.config.mjs both exist', async () => {
+    const result = await applyConfigCodemod({
+      'package.json': `{"xds":{"theme":"neutral"}}\n`,
+      'xds.config.mjs': `export default {};\n`,
+    });
+    expect(result.errors?.[0]?.error).toMatch(/migrate the config manually/);
+  });
+
+  it('renames xds.config.mjs to astryx.config.mjs when no package config exists', async () => {
+    const result = await applyConfigCodemod({
+      'xds.config.mjs': "export default { theme: 'neutral' };\n",
+    });
+    expect(result.changes).toEqual([
+      {
+        path: 'astryx.config.mjs',
+        source: "export default { theme: 'neutral' };\n",
+      },
+      {path: 'xds.config.mjs', delete: true},
+    ]);
+  });
+
+  it('bails when xds.config.mjs and astryx.config.mjs both exist', async () => {
+    const result = await applyConfigCodemod({
+      'xds.config.mjs': `export default {};\n`,
+      'astryx.config.mjs': `export default {};\n`,
+    });
+    expect(result.errors?.[0]?.error).toMatch(/migrate the config manually/);
+  });
+});

package/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-module-specifiers.test.mjs

@@ -0,0 +1,51 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source, filePath = 'test.tsx') {
+  const {default: transform} =
+    await import('../migrate-xds-module-specifiers.mjs');
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const file = {source, path: filePath};
+  const result = transform(file, api);
+  return result ?? source;
+}
+
+describe('migrate-xds-module-specifiers', () => {
+  it('renames import and export source paths including subpaths', async () => {
+    const input = [
+      "import {Button} from '@xds/core/Button';",
+      "import '@xds/theme-default/theme.css';",
+      "export {LabThing} from '@xds/lab/Thing';",
+      "export * from '@xds/core/theme';",
+    ].join('\n');
+
+    const output = await applyTransform(input);
+    expect(output).toContain('@astryxdesign/core/Button');
+    expect(output).toContain('@astryxdesign/theme-neutral/theme.css');
+    expect(output).toContain('@astryxdesign/lab/Thing');
+    expect(output).toContain('@astryxdesign/core/theme');
+    expect(output).not.toContain('@xds/');
+  });
+
+  it('renames dynamic import and require string literals', async () => {
+    const output = await applyTransform(
+      [
+        "const mod = await import('@xds/core/theme');",
+        "const core = require('@xds/core');",
+      ].join('\n'),
+      'test.ts',
+    );
+    expect(output).toContain('@astryxdesign/core/theme');
+    expect(output).toContain('@astryxdesign/core');
+    expect(output).not.toContain('@xds/');
+  });
+
+  it('does not rewrite ordinary string literals', async () => {
+    const input = "const packageName = '@xds/core';";
+    const output = await applyTransform(input, 'test.ts');
+    expect(output).toBe(input);
+  });
+});

package/src/codemods/transforms/v0.1.0/index.mjs

@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file v0.1.0 transform manifest
+ *
+ * Lists all codemods for the v0.1.0 release in the order they should run.
+ */
+
+import migrateXdsConfigSurfaces, {
+  meta as migrateXdsConfigSurfacesMeta,
+} from './migrate-xds-config-surfaces.mjs';
+
+import migrateXdsModuleSpecifiers, {
+  meta as migrateXdsModuleSpecifiersMeta,
+} from './migrate-xds-module-specifiers.mjs';
+
+export default [
+  {
+    name: 'migrate-xds-config-surfaces',
+    transform: migrateXdsConfigSurfaces,
+    meta: migrateXdsConfigSurfacesMeta,
+  },
+  {
+    name: 'migrate-xds-module-specifiers',
+    transform: migrateXdsModuleSpecifiers,
+    meta: migrateXdsModuleSpecifiersMeta,
+  },
+];