@astryxdesign/cli 0.1.2 → 0.1.3

package/src/commands/swizzle.routing.test.mjs

@@ -0,0 +1,279 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Integration-routing tests for `astryx swizzle`.
+ *
+ * `rewriteImports` is unit-tested in swizzle.test.mjs. These tests exercise the
+ * end-to-end command behavior by spawning the CLI bin against hermetic
+ * fixtures: a fake @astryxdesign/core under node_modules plus, for the
+ * integration cases, a configured integration package (astryx.config.mjs +
+ * astryx.integration.mjs + a `components` dir) — all under node_modules so the
+ * config/manifest loaders resolve normally.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+
+/**
+ * Build a fake @astryxdesign/core under <project>/node_modules with a single
+ * swizzleable Button component (bare `Button.tsx`, no doc).
+ */
+function buildFakeCore(project) {
+  const core = path.join(project, 'node_modules', '@astryxdesign', 'core');
+  const buttonDir = path.join(core, 'src', 'Button');
+  fs.mkdirSync(buttonDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(core, 'package.json'),
+    '{"name":"@astryxdesign/core","version":"0.0.13"}',
+  );
+  fs.writeFileSync(
+    path.join(buttonDir, 'Button.tsx'),
+    [
+      `import {tokens} from '../theme/tokens.stylex';`,
+      `import {helper} from './helper';`,
+      `export const Button = () => null;`,
+      '',
+    ].join('\n'),
+  );
+  fs.writeFileSync(
+    path.join(buttonDir, 'helper.ts'),
+    `export const helper = 1;\n`,
+  );
+  return core;
+}
+
+/**
+ * Build a configured integration package `@test/meta` under
+ * <project>/node_modules with a same-stem component (source + doc) and an
+ * escaping import, plus a colocated test file. Writes astryx.config.mjs at the
+ * project root listing the integration.
+ *
+ * @param {string} project
+ * @param {{issuesUrl?: string|null, componentName?: string}} [opts]
+ */
+function buildIntegration(project, {issuesUrl, componentName = 'MetaAppShell'} = {}) {
+  const intDir = path.join(project, 'node_modules', '@test', 'meta');
+  const compRoot = path.join(intDir, 'components');
+  const compDir = path.join(compRoot, componentName);
+  fs.mkdirSync(compDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(intDir, 'package.json'),
+    JSON.stringify({name: '@test/meta', version: '1.2.3'}),
+  );
+  const manifest = {components: './components'};
+  if (issuesUrl) manifest.issuesUrl = issuesUrl;
+  fs.writeFileSync(
+    path.join(intDir, 'astryx.integration.mjs'),
+    `export default ${JSON.stringify(manifest)};\n`,
+  );
+  fs.writeFileSync(
+    path.join(compDir, `${componentName}.tsx`),
+    [
+      `import x from '../utils/foo';`,
+      `import {sib} from './sibling';`,
+      `export function ${componentName}() { return x; }`,
+      '',
+    ].join('\n'),
+  );
+  fs.writeFileSync(
+    path.join(compDir, 'sibling.ts'),
+    `export const sib = 1;\n`,
+  );
+  fs.writeFileSync(
+    path.join(compDir, `${componentName}.doc.mjs`),
+    `export const docs = {name: '${componentName}', usage: {description: 'x'}};\n`,
+  );
+  fs.writeFileSync(
+    path.join(compDir, `${componentName}.test.tsx`),
+    `it('noop', () => {});\n`,
+  );
+  fs.writeFileSync(
+    path.join(project, 'astryx.config.mjs'),
+    `export default {integrations: ['@test/meta']};\n`,
+  );
+  return {intDir, compDir};
+}
+
+function writeProjectPackageJson(project, extra = {}) {
+  fs.writeFileSync(
+    path.join(project, 'package.json'),
+    JSON.stringify({name: 'consumer', version: '1.0.0', ...extra}),
+  );
+}
+
+function runCli(args, cwd) {
+  try {
+    const out = execFileSync('node', [CLI_BIN, ...args], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {...process.env, FORCE_COLOR: '0'},
+    });
+    return {code: 0, stdout: out, stderr: ''};
+  } catch (e) {
+    return {
+      code: e.status ?? 1,
+      stdout: e.stdout?.toString() ?? '',
+      stderr: e.stderr?.toString() ?? '',
+    };
+  }
+}
+
+let tmpDir;
+let project;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-swizzle-routing-'));
+  project = path.join(tmpDir, 'project');
+  fs.mkdirSync(project, {recursive: true});
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('swizzle — core feedback routing via config', () => {
+  it('routes core feedback to config.issuesUrl when set', () => {
+    buildFakeCore(project);
+    writeProjectPackageJson(project);
+    fs.writeFileSync(
+      path.join(project, 'astryx.config.mjs'),
+      `export default {issuesUrl: 'https://github.com/acme/ds/issues'};\n`,
+    );
+
+    const result = runCli(['--json', 'swizzle', 'Button', '-f'], project);
+    expect(result.code).toBe(0);
+    const env = JSON.parse(result.stdout);
+    expect(env.type).toBe('swizzle.copy');
+    expect(env.data.package).toBe('@astryxdesign/core');
+    expect(env.data.feedback.issuesUrl).toBe('https://github.com/acme/ds/issues');
+    // Escaping import rewritten to core; sibling import preserved.
+    const out = fs.readFileSync(
+      path.join(project, 'components', 'astryx', 'Button', 'Button.tsx'),
+      'utf-8',
+    );
+    expect(out).toContain(`from '@astryxdesign/core/theme'`);
+    expect(out).toContain(`from './helper'`);
+  });
+
+  it('falls back to the default issues URL when config has none', () => {
+    buildFakeCore(project);
+    writeProjectPackageJson(project);
+
+    const result = runCli(['--json', 'swizzle', 'Button', '-f'], project);
+    expect(result.code).toBe(0);
+    const env = JSON.parse(result.stdout);
+    expect(env.data.feedback.issuesUrl).toBe(
+      'https://github.com/facebook/astryx/issues/new',
+    );
+  });
+});
+
+describe('swizzle — integration-owned components', () => {
+  it('copies the component dir (excluding test/doc), rewrites escaping imports to the owner package, routes feedback to the integration issuesUrl', () => {
+    buildFakeCore(project);
+    writeProjectPackageJson(project);
+    buildIntegration(project, {issuesUrl: 'https://example.com/meta/issues'});
+
+    const result = runCli(['--json', 'swizzle', 'MetaAppShell', '-f'], project);
+    expect(result.code).toBe(0);
+    const env = JSON.parse(result.stdout);
+    expect(env.type).toBe('swizzle.copy');
+    expect(env.data.package).toBe('@test/meta');
+    // Doc + test excluded from the copy.
+    expect(env.data.files).toContain('MetaAppShell.tsx');
+    expect(env.data.files).toContain('sibling.ts');
+    expect(env.data.files).not.toContain('MetaAppShell.doc.mjs');
+    expect(env.data.files.some(f => f.includes('.test.'))).toBe(false);
+    // Feedback routed to the integration's issues URL.
+    expect(env.data.feedback.issuesUrl).toBe('https://example.com/meta/issues');
+
+    const outDir = path.join(project, 'components', 'astryx', 'MetaAppShell');
+    expect(fs.existsSync(path.join(outDir, 'MetaAppShell.doc.mjs'))).toBe(false);
+    const out = fs.readFileSync(path.join(outDir, 'MetaAppShell.tsx'), 'utf-8');
+    expect(out).toContain(`from '@test/meta/utils'`);
+    expect(out).toContain(`from './sibling'`);
+  });
+
+  it('omits the feedback note when the integration ships no issuesUrl', () => {
+    buildFakeCore(project);
+    writeProjectPackageJson(project);
+    buildIntegration(project, {issuesUrl: null});
+
+    const result = runCli(['--json', 'swizzle', 'MetaAppShell', '-f'], project);
+    expect(result.code).toBe(0);
+    const env = JSON.parse(result.stdout);
+    expect(env.type).toBe('swizzle.copy');
+    expect(env.data.package).toBe('@test/meta');
+    expect(env.data.feedback).toBeUndefined();
+  });
+});
+
+describe('swizzle — ambiguous ownership', () => {
+  it('errors when a name is owned by core + an integration and no --package is given', () => {
+    buildFakeCore(project);
+    writeProjectPackageJson(project);
+    // Integration also provides "Button" (collides with core).
+    buildIntegration(project, {
+      issuesUrl: 'https://example.com/meta/issues',
+      componentName: 'Button',
+    });
+
+    const result = runCli(['--json', 'swizzle', 'Button', '-f'], project);
+    expect(result.code).not.toBe(0);
+    const env = JSON.parse(result.stdout);
+    expect(env.code).toBe('ERR_AMBIGUOUS_COMPONENT');
+    const pkgs = (env.suggestions ?? []).map(s => s.name);
+    expect(pkgs).toContain('@astryxdesign/core');
+    expect(pkgs).toContain('@test/meta');
+  });
+
+  it('--package resolves an ambiguous name to the integration', () => {
+    buildFakeCore(project);
+    writeProjectPackageJson(project);
+    buildIntegration(project, {
+      issuesUrl: 'https://example.com/meta/issues',
+      componentName: 'Button',
+    });
+
+    const result = runCli(
+      ['--json', 'swizzle', 'Button', '--package', '@test/meta', '-f'],
+      project,
+    );
+    expect(result.code).toBe(0);
+    const env = JSON.parse(result.stdout);
+    expect(env.data.package).toBe('@test/meta');
+    const out = fs.readFileSync(
+      path.join(project, 'components', 'astryx', 'Button', 'Button.tsx'),
+      'utf-8',
+    );
+    expect(out).toContain(`from '@test/meta/utils'`);
+  });
+
+  it('--package resolves an ambiguous name to core', () => {
+    buildFakeCore(project);
+    writeProjectPackageJson(project);
+    buildIntegration(project, {
+      issuesUrl: 'https://example.com/meta/issues',
+      componentName: 'Button',
+    });
+
+    const result = runCli(
+      ['--json', 'swizzle', 'Button', '--package', '@astryxdesign/core', '-f'],
+      project,
+    );
+    expect(result.code).toBe(0);
+    const env = JSON.parse(result.stdout);
+    expect(env.data.package).toBe('@astryxdesign/core');
+    const out = fs.readFileSync(
+      path.join(project, 'components', 'astryx', 'Button', 'Button.tsx'),
+      'utf-8',
+    );
+    expect(out).toContain(`from '@astryxdesign/core/theme'`);
+  });
+});

package/src/commands/template.mjs

@@ -11,9 +11,11 @@ import {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 {template as templateApi, getTemplateById} from '../api/template.mjs';
+import {template as templateApi} from '../api/template.mjs';
+import {Project} from '../lib/project.mjs';
+import {warnOnIntegrationIssues} from '../lib/integration-warnings.mjs';
 
-export {discoverTemplates, listTemplates, getTemplateById} from '../api/template.mjs';
+export {discoverTemplates, listTemplates} from '../api/template.mjs';
 
 function isCancel(value) {
   if (p.isCancel(value)) {
@@ -24,16 +26,27 @@ function isCancel(value) {
 }
 
 export function registerTemplate(program) {
-  const templateCmd = program
+  program
     .command('template [name] [path]')
     .description('Inject a page or block template')
     .option('--list', 'List available templates')
     .option('--type <type>', 'Filter by template type: page or block')
+    .option('--package <pkg>', 'Narrow to templates from a specific package')
     .option('--skeleton', 'Show layout skeleton with spatial annotations (padding, gap, nesting)')
     .option('-f, --overwrite', 'Overwrite existing files without prompting')
     .action(async (name, targetPath, options) => {
       const json = program.opts().json || false;
 
+      // Non-blocking nudge: if any configured integration has validation
+      // issues, print one compact line to stderr pointing at
+      // validate-integration. Best-effort; suppressed in --json mode.
+      try {
+        const project = await Project.load(process.cwd());
+        await warnOnIntegrationIssues(project.loadedIntegrations, {json});
+      } catch {
+        // Never let the nudge break the command.
+      }
+
       // Pre-flight overwrite check (only when we'd actually copy a file).
       // The API resolves the destination; we need to mirror its logic
       // narrowly enough to detect collisions before invoking it.
@@ -72,6 +85,7 @@ export function registerTemplate(program) {
           list: options.list,
           skeleton: options.skeleton,
           type: options.type,
+          package: options.package,
           targetPath,
           cwd: process.cwd(),
         });
@@ -88,26 +102,28 @@ export function registerTemplate(program) {
         case 'template.list': {
           const pages = result.data.filter(t => t.type === 'page');
           const blocks = result.data.filter(t => t.type === 'block');
+          const renderEntry = t => {
+            const status = t.isReady ? '' : ' (WIP)';
+            const pkg =
+              t.package && t.package !== '@astryxdesign/core'
+                ? `  [${t.package}]`
+                : '';
+            humanLog(`  ${t.name}${status}${pkg}`);
+            if (t.description) humanLog(`    ${t.description}`);
+          };
           if (pages.length > 0) {
             humanLog('\nPage Templates:\n');
-            for (const t of pages) {
-              const status = t.isReady ? '' : ' (WIP)';
-              humanLog(`  ${t.name}${status}`);
-              if (t.description) humanLog(`    ${t.description}`);
-            }
+            for (const t of pages) renderEntry(t);
           }
           if (blocks.length > 0) {
             humanLog('\nBlock Templates:\n');
-            for (const t of blocks) {
-              const status = t.isReady ? '' : ' (WIP)';
-              humanLog(`  ${t.name}${status}`);
-              if (t.description) humanLog(`    ${t.description}`);
-            }
+            for (const t of blocks) renderEntry(t);
           }
           humanLog('\nUsage:');
-          humanLog('  astryx template <name> [target-path]   Scaffold page or block');
-          humanLog('  astryx template <name> --skeleton      Layout reference');
-          humanLog('  astryx template --list --type block    List only blocks\n');
+          humanLog('  astryx template <id> [target-path]     Scaffold page or block');
+          humanLog('  astryx template <id> --skeleton        Layout reference');
+          humanLog('  astryx template --list --type block    List only blocks');
+          humanLog('  astryx template --list --package <pkg> List from one package\n');
           break;
         }
 
@@ -131,26 +147,6 @@ export function registerTemplate(program) {
         }
       }
     });
-
-  templateCmd
-    .command('get')
-    .description('Fetch a template by ID via the astryx.config.mjs hook')
-    .requiredOption('--id <id>', 'Template identifier to fetch')
-    .action(async (options) => {
-      const json = program.opts().json || false;
-
-      let result;
-      try {
-        result = await getTemplateById(options.id, {cwd: process.cwd()});
-      } catch (e) {
-        cliError(e.message, {suggestions: e.suggestions, code: e.code});
-        return;
-      }
-
-      if (json) return jsonOut(result.type, result.data);
-
-      humanLog(result.data.source);
-    });
 }
 
 /**
@@ -168,7 +164,7 @@ async function detectTemplateCollision(name, targetPath) {
   const {discoverTemplates} = await import('../api/template.mjs');
   let templates;
   try {
-    templates = await discoverTemplates();
+    templates = await discoverTemplates(process.cwd());
   } catch {
     return null;
   }

package/src/commands/upgrade.config-ordering.test.mjs

@@ -0,0 +1,273 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Upgrade config-codemod-ordering tests.
+ *
+ * Verifies that CORE codemods run BEFORE the consumer's config is loaded, so a
+ * config codemod (v0.1.3 migrate-layout-components, meta.codemodType==='config')
+ * can repair an otherwise-invalid config that strict `Project.load` would reject.
+ *
+ * Like the integration-policy tests, these scaffold a real consumer project
+ * (package.json + astryx.config.mjs) under a REPO-LOCAL temp dir (so Vite
+ * permits dynamic import of the config module — it blocks /tmp) and chdir in.
+ *
+ * Cases:
+ *   1. dry-run, legacy layout.components, v0.1.3 config codemod in range →
+ *      does NOT abort; reports "fixable, re-run with --apply" + the suggested
+ *      `--codemod ... --apply` command; exit 0; integrations skipped.
+ *   2. --apply, same config → core config codemod writes the repaired config,
+ *      then config loads strictly OK and the upgrade completes; on-disk config
+ *      is migrated to experimental.xle.components.
+ *   3. dry-run, config genuinely invalid (integrations: 5) with NO pending
+ *      config codemod → still ABORTS (exit nonzero).
+ *   4. happy path (valid config, no config codemod) → unchanged behavior.
+ */
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {Command} from 'commander';
+import {registerUpgrade} from './upgrade.mjs';
+
+let tmpDir;
+let originalCwd;
+let logCalls;
+let stdoutCalls;
+let exitCode;
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  // Repo-local temp dir: under cwd so Vite allows the astryx.config import.
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-upgrade-order-'));
+  process.chdir(tmpDir);
+  logCalls = [];
+  stdoutCalls = [];
+  exitCode = undefined;
+  vi.spyOn(console, 'log').mockImplementation((...a) => logCalls.push(a.join(' ')));
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+  vi.spyOn(process.stdout, 'write').mockImplementation(chunk => {
+    stdoutCalls.push(typeof chunk === 'string' ? chunk : chunk.toString());
+    return true;
+  });
+  vi.spyOn(process, 'exit').mockImplementation(code => {
+    exitCode = code;
+    throw new Error(`__exit ${code}`);
+  });
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+  vi.restoreAllMocks();
+});
+
+function writePkg() {
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'consumer'}),
+  );
+}
+
+function writeInstalledCore(version) {
+  const dir = path.join(tmpDir, 'node_modules', '@astryxdesign', 'core');
+  fs.mkdirSync(dir, {recursive: true});
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name: '@astryxdesign/core', version}),
+  );
+}
+
+function writeConfig(body) {
+  fs.writeFileSync(path.join(tmpDir, 'astryx.config.mjs'), body);
+}
+
+function writeSource() {
+  fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});
+  fs.writeFileSync(path.join(tmpDir, 'src', 'index.ts'), 'const foo = 1;\n');
+}
+
+const LEGACY_CONFIG = `export default {
+  layout: {
+    components: {
+      KpiCard: '@/components/KpiCard',
+    },
+  },
+};
+`;
+
+function createProgram() {
+  const program = new Command();
+  program.exitOverride();
+  program.option('--json', 'Output as typed JSON');
+  registerUpgrade(program);
+  return program;
+}
+
+async function runJson(args) {
+  const program = createProgram();
+  try {
+    await program.parseAsync(['node', 'astryx', ...args]);
+  } catch (err) {
+    if (!String(err?.message || '').startsWith('__exit')) throw err;
+  }
+  for (let i = logCalls.length - 1; i >= 0; i--) {
+    const line = logCalls[i];
+    if (line.startsWith('{')) {
+      try {
+        return JSON.parse(line);
+      } catch {
+        // keep looking
+      }
+    }
+  }
+  return null;
+}
+
+async function runHuman(args) {
+  const program = createProgram();
+  try {
+    await program.parseAsync(['node', 'astryx', ...args]);
+  } catch (err) {
+    if (!String(err?.message || '').startsWith('__exit')) throw err;
+  }
+  return stdoutCalls.join('') + '\n' + logCalls.join('\n');
+}
+
+describe('upgrade — core codemods run before config load', () => {
+  it('dry-run: legacy layout.components is reported as fixable, not an abort', async () => {
+    // 0.1.2 -> 0.1.3 brings the migrate-layout-components config codemod.
+    writePkg();
+    writeInstalledCore('0.1.3');
+    writeConfig(LEGACY_CONFIG);
+    writeSource();
+
+    const result = await runJson([
+      '--json',
+      'upgrade',
+      '--from',
+      '0.1.2',
+      '--path',
+      'src',
+    ]);
+
+    expect(result).not.toBeNull();
+    // Did NOT abort with a config-validation error.
+    expect(result.error).toBeUndefined();
+    expect(exitCode).not.toBe(1);
+    // Reported as the fixable case with the suggested apply command.
+    expect(result.type).toBe('upgrade.status');
+    expect(result.data.status).toBe('config_fixable');
+    expect(result.data.configCodemods).toContain(
+      'migrate-layout-components-to-experimental',
+    );
+    expect(result.data.suggestedCommand).toBe(
+      'astryx upgrade --from 0.1.2 --codemod migrate-layout-components-to-experimental --apply',
+    );
+    expect(result.data.message).toMatch(/--apply/);
+    // Integrations skipped for the preview.
+    expect(result.data.note).toMatch(/--apply run/i);
+    // Dry-run did not write the config.
+    const onDisk = fs.readFileSync(
+      path.join(tmpDir, 'astryx.config.mjs'),
+      'utf-8',
+    );
+    expect(onDisk).toContain('layout');
+    expect(onDisk).not.toContain('experimental');
+  });
+
+  it('human dry-run prints the fixable guidance + suggested command', async () => {
+    writePkg();
+    writeInstalledCore('0.1.3');
+    writeConfig(LEGACY_CONFIG);
+    writeSource();
+
+    const out = await runHuman(['upgrade', '--from', '0.1.2', '--path', 'src']);
+    expect(out).toMatch(/fails strict validation/i);
+    expect(out).toContain(
+      'astryx upgrade --from 0.1.2 --codemod migrate-layout-components-to-experimental --apply',
+    );
+    expect(exitCode).not.toBe(1);
+  });
+
+  it('--apply: core config codemod repairs the config, then the upgrade completes', async () => {
+    writePkg();
+    writeInstalledCore('0.1.3');
+    writeConfig(LEGACY_CONFIG);
+    writeSource();
+
+    const result = await runJson([
+      '--json',
+      'upgrade',
+      '--from',
+      '0.1.2',
+      '--path',
+      'src',
+      '--apply',
+    ]);
+
+    expect(result).not.toBeNull();
+    expect(result.error).toBeUndefined();
+    expect(exitCode).not.toBe(1);
+    expect(result.type).toBe('upgrade.run');
+    expect(result.data.filesChanged).toBeGreaterThan(0);
+
+    // The on-disk config was migrated to experimental.xle.components.
+    const onDisk = fs.readFileSync(
+      path.join(tmpDir, 'astryx.config.mjs'),
+      'utf-8',
+    );
+    expect(onDisk).toContain('experimental');
+    expect(onDisk).toContain('xle');
+    expect(onDisk).toMatch(
+      /KpiCard:\s*\{\s*from:\s*['"]@\/components\/KpiCard['"]/,
+    );
+    expect(onDisk).not.toMatch(/layout\s*:/);
+  });
+
+  it('dry-run: a genuinely invalid config with NO fixing codemod still aborts', async () => {
+    writePkg();
+    writeInstalledCore('0.1.3');
+    // `integrations: 5` is invalid AND no config codemod in 0.1.2->0.1.3 fixes it.
+    writeConfig(`export default { integrations: 5 };\n`);
+    writeSource();
+
+    const result = await runJson([
+      '--json',
+      'upgrade',
+      '--from',
+      '0.1.2',
+      '--path',
+      'src',
+    ]);
+
+    expect(result).not.toBeNull();
+    // Aborts with a config-validation error (not the fixable status).
+    expect(result.error).toBeTruthy();
+    expect(result.type).not.toBe('upgrade.status');
+    expect(exitCode).toBe(1);
+  });
+
+  it('happy path: valid config with no config codemod behaves normally', async () => {
+    writePkg();
+    writeInstalledCore('0.1.3');
+    // A valid, already-migrated config; no relocation needed.
+    writeConfig(`export default { integrations: [] };\n`);
+    writeSource();
+
+    const result = await runJson([
+      '--json',
+      'upgrade',
+      '--from',
+      '0.1.2',
+      '--path',
+      'src',
+      '--apply',
+    ]);
+
+    expect(result).not.toBeNull();
+    expect(result.error).toBeUndefined();
+    expect(exitCode).not.toBe(1);
+    // Completed as a run (the config codemod is a no-op on an already-migrated config).
+    expect(result.type).toBe('upgrade.run');
+  });
+});