fix(cli): run core codemods before loading config in upgrade (with dry-run guidance)

[ejhammond]

Problem

astryx upgrade called Project.load(process.cwd()) up front, before running any codemods. Project.load strict-validates astryx.config.* (unknown keys rejected) and throws on failure. This created a chicken-and-egg:

A consumer whose config still has the legacy layout.components key — exactly what the v0.1.3 codemod migrate-layout-components-to-experimental exists to fix — gets their config rejected at load, so the upgrade aborts and the codemod that would repair it never runs.

Fix

Reorder the upgrade pipeline so core codemods run before the config is loaded:

1. version detect (unchanged)
2. up-to-date check (unchanged)
3. resolve + run CORE codemods (registry getTransformsBetween → runCodemods). Config codemods read astryx.config.* directly via runConfigCodemod; code codemods scan --path. Neither needs the loaded config. In --apply the config codemod writes the repaired config; in dry-run it only previews.
4. load config via Project.load (strict validation unchanged), now wrapped in a graceful dry-run catch:
   • dry-run + a pending core config codemod actually previewed a change → don't abort. Report that the config currently fails validation but a pending config codemod would fix it, print the exact astryx upgrade --from <from> --codemod <name> --apply command to repair it, and finish the dry-run cleanly (exit 0). Integrations are skipped for the preview and noted as deferred to the --apply run.
   • otherwise (apply mode, or dry-run with no config codemod that would fix it — including a no-op or throwing codemod) → genuine config error, abort as before.
5. discover + run integration codemods (only on a successful config load); the integration-issue nudge moves here too.
6. postCodemod hooks + agent-docs refresh (unchanged, still last).

Config strictness is not loosened. The codemod-execution-error gate still aborts on a throwing transform.

Tests

New upgrade.config-ordering.test.mjs (repo-local temp project + chdir):

• dry-run with legacy layout.components → reports the fixable status + suggested --codemod ... --apply command; exit 0; config not written; integrations skipped.
• --apply with the same config → core config codemod rewrites it to experimental.xle.components, strict load then succeeds, upgrade completes.
• dry-run with a genuinely invalid config (integrations: 5) and no fixing codemod → still aborts (exit nonzero).
• happy path (valid config, no config codemod) → unchanged.

All existing upgrade/runner/integration tests stay green.

Before / after (manual smoke)

Config export default { layout: { components: { KpiCard: '@/components/KpiCard' } } }:

• astryx upgrade --from 0.1.2 (dry-run): previews the fix, prints the fixable-config guidance + suggested command, exit 0 (no crash on the legacy key).
• astryx upgrade --from 0.1.2 --apply: rewrites the config to experimental.xle.components, completes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview, Comment	Jun 30, 2026 10:59pm