@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.ddb63c3

package/api/upgrade/_adapter.d.mts

@@ -104,13 +104,14 @@ export function ensureCodemodDeps({ installDeps }?: {
  * Run the CORE registry codemods. Runs BEFORE the config is loaded so a core
  * CONFIG codemod can repair a config the strict loader would otherwise reject.
  * @param {CoreVersionManifest[]} versionManifests
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string}} options
  */
-export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply, path: srcPath, codemod, skipCodemods }: {
+export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply, path: srcPath, codemod, skipCodemods, root }: {
     apply: boolean;
     path: string;
     codemod?: string;
     skipCodemods: Set<string>;
+    root?: string;
 }): Promise<{
     totalFilesChanged: number;
     totalTransformsApplied: number;
@@ -139,13 +140,21 @@ export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply
 /**
  * Load the consumer project's config + integrations. Throws on invalid config;
  * the run leaf decides between the config_fixable preview and a hard abort.
+ *
+ * Provider identity is resolved by the same resolver Project uses, on top of
+ * Project's ledger, under the codemod policy: a package that lists itself runs
+ * its installed copy's released codemods, never the work in progress being
+ * authored, and autolinked and local packages claim provider IDs without
+ * running codemods.
+ *
  * @param {string} cwd
  * @param {string[]} [extraIntegrationSpecs] explicit `--integration` specs
- * @returns {Promise<{postCodemodHooks: import('../../authoring/config/type').PostCodemodHook[], integrations: import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]}>}
+ * @returns {Promise<{postCodemodHooks: import('../../authoring/config/type').PostCodemodHook[], integrations: import('../../foundation/integrations/integrations.mjs').LoadedIntegration[], ledger: import('../../foundation/integrations/provider-resolution.mjs').ProviderLedger}>}
  */
 export function loadProjectContext(cwd: string, extraIntegrationSpecs?: string[]): Promise<{
     postCodemodHooks: import("../../authoring/config/type").PostCodemodHook[];
     integrations: import("../../foundation/integrations/integrations.mjs").LoadedIntegration[];
+    ledger: import("../../foundation/integrations/provider-resolution.mjs").ProviderLedger;
 }>;
 /**
  * Non-blocking nudge for integration validation issues. Never throws (a broken

package/api/upgrade/_adapter.mjs

@@ -19,7 +19,10 @@ import * as path from 'node:path';
 import {execFile} from 'node:child_process';
 import {promisify} from 'node:util';
 import {ensureJscodeshift} from '../../assets/codemods/ensure-jscodeshift.mjs';
-import {getTransformsBetween, latestVersion} from '../../assets/codemods/registry.mjs';
+import {
+  getTransformsBetween,
+  latestVersion,
+} from '../../assets/codemods/registry.mjs';
 import {runCodemods} from '../../assets/codemods/runner.mjs';
 import {
   discoverIntegrationCodemods,
@@ -32,17 +35,15 @@ import {
   renderAgentDocsBlock,
 } from '../../foundation/agent-docs/agent-docs.mjs';
 import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
-import {Project} from '../../foundation/config/project.mjs';
-import {
-  loadIntegrations,
-  markProviderConflicts,
-} from '../../foundation/integrations/integrations.mjs';
+import {Project, providerLedgerOf} from '../../foundation/config/project.mjs';
+import {loadIntegrations} from '../../foundation/integrations/integrations.mjs';
+import {resolveProviders} from '../../foundation/integrations/provider-resolution.mjs';
 import {warnOnIntegrationIssues} from '../../foundation/integrations/integration-warnings.mjs';
 import {logger} from '../logger.mjs';
 
 // Re-exported for the run leaf's lightweight agent-docs inspection path
 // (config_fixable short-circuit, where the full render cannot load config).
-export { inspectAgentDocs };
+export {inspectAgentDocs};
 
 const execFileAsync = promisify(execFile);
 
@@ -291,7 +292,13 @@ export async function collectAllCodemods() {
   );
   for (const {version, transforms} of manifests) {
     for (const {name, meta, optional} of transforms) {
-      codemods.push({name, title: meta.title, version, pr: meta.pr, optional: !!optional});
+      codemods.push({
+        name,
+        title: meta.title,
+        version,
+        pr: meta.pr,
+        optional: !!optional,
+      });
     }
   }
   return codemods;
@@ -322,33 +329,35 @@ export async function ensureCodemodDeps({installDeps} = {}) {
  * Run the CORE registry codemods. Runs BEFORE the config is loaded so a core
  * CONFIG codemod can repair a config the strict loader would otherwise reject.
  * @param {CoreVersionManifest[]} versionManifests
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string}} options
  */
-export async function runCoreCodemods(versionManifests, {apply, path: srcPath, codemod, skipCodemods}) {
+export async function runCoreCodemods(
+  versionManifests,
+  {apply, path: srcPath, codemod, skipCodemods, root},
+) {
   return runCodemods(versionManifests, {
     apply,
     path: srcPath,
     codemod,
     skipCodemods,
     silent: logger.silent,
+    root,
   });
 }
 
-/**
- * One installed package at one version; two specs that reach it share this.
- * @param {{name: string, version?: string}} integration
- * @returns {string}
- */
-function packageIdentity(integration) {
-  return `${integration.name}\u0000${integration.version ?? ''}`;
-}
-
 /**
  * Load the consumer project's config + integrations. Throws on invalid config;
  * the run leaf decides between the config_fixable preview and a hard abort.
+ *
+ * Provider identity is resolved by the same resolver Project uses, on top of
+ * Project's ledger, under the codemod policy: a package that lists itself runs
+ * its installed copy's released codemods, never the work in progress being
+ * authored, and autolinked and local packages claim provider IDs without
+ * running codemods.
+ *
  * @param {string} cwd
  * @param {string[]} [extraIntegrationSpecs] explicit `--integration` specs
- * @returns {Promise<{postCodemodHooks: import('../../authoring/config/type').PostCodemodHook[], integrations: import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]}>}
+ * @returns {Promise<{postCodemodHooks: import('../../authoring/config/type').PostCodemodHook[], integrations: import('../../foundation/integrations/integrations.mjs').LoadedIntegration[], ledger: import('../../foundation/integrations/provider-resolution.mjs').ProviderLedger}>}
  */
 export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
   // The CLI debug preflight may already have imported this config before core
@@ -360,23 +369,38 @@ export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
   // Configured packages come from Project, which has already resolved provider
   // identity over configured, autolinked, and local packages. Loading them
   // again here would let upgrade run codemods from a package Project set aside.
-  const configured = project.loadedIntegrations.filter(
-    integration =>
-      !integration.__autolinked && configuredSpecs.has(integration.__spec),
-  );
+  // Autolinked packages and the package being authored join only as claimants:
+  // every other command uses them for their provider IDs, but upgrade has
+  // never run their codemods.
+  const candidates = project.loadedIntegrations.flatMap(integration => {
+    const source =
+      !integration.__autolinked && configuredSpecs.has(integration.__spec)
+        ? /** @type {const} */ ('configured')
+        : integration.__autolinked
+          ? /** @type {const} */ ('autolinked')
+          : integration.__local
+            ? /** @type {const} */ ('local')
+            : null;
+    return source == null
+      ? []
+      : [{source, integration, spec: integration.__spec}];
+  });
   // A package that lists itself runs its installed copy's released codemods,
-  // never the work in progress being authored, so that copy stands in for it.
+  // never the work in progress being authored; the resolver puts that copy in
+  // its place. Naming the package being authored with --integration asks for
+  // the installed copy too.
   const local = project.loadedIntegrations.find(
     integration => integration.__local,
   );
-  const selfListed = local != null && configured.includes(local);
-  if (local != null && selfListed && project.configPath) {
-    const installed = await loadIntegrations([local.__spec], {
-      cwd: path.dirname(project.configPath),
-      resolveProviders: false,
-    });
-    configured.splice(configured.indexOf(local), 1, ...installed);
-  }
+  const selfListed =
+    local != null && !local.__autolinked && configuredSpecs.has(local.__spec);
+  const installed =
+    local != null && selfListed && project.configPath
+      ? await loadIntegrations([local.__spec], {
+          cwd: path.dirname(project.configPath),
+          resolveProviders: false,
+        })
+      : [];
   const extraSpecs = uniqueFiles(extraIntegrationSpecs ?? []).filter(
     spec => !configuredSpecs.has(spec),
   );
@@ -384,38 +408,23 @@ export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
     extraSpecs.length === 0
       ? []
       : await loadIntegrations(extraSpecs, {resolveProviders: false});
-  // Naming the package being authored with --integration asks for its
-  // installed copy too, so the local package must not claim against it.
-  const localStandsIn =
-    local != null &&
-    (selfListed || extras.some(extra => extra.name === local.name));
-  // Autolinked packages and the package being authored join the pass only as
-  // claimants: every other command uses them for their provider IDs, but
-  // upgrade has never run their codemods and still does not. An extra that
-  // names one of them opts it in, so the extra stands in for that claimant.
-  const extraIdentities = new Set(extras.map(packageIdentity));
-  const claimantsOnly = project.loadedIntegrations.filter(
-    integration =>
-      (integration.__autolinked || (integration.__local && !localStandsIn)) &&
-      !extraIdentities.has(packageIdentity(integration)),
-  );
-  const resolved = markProviderConflicts([
-    ...configured,
-    ...claimantsOnly,
-    ...extras,
-  ]);
-  // Claimants leave by package directory, not object identity: the pass can
-  // return one as a new conflict entry, and upgrade must not warn that a
-  // package every other command uses contributes nothing.
-  const claimantDirs = new Set(
-    claimantsOnly.map(integration => integration.__packageDir),
-  );
-  const integrations = resolved.filter(
-    integration =>
-      integration.__packageDir == null ||
-      !claimantDirs.has(integration.__packageDir),
+  const {integrations, ledger} = resolveProviders(
+    [
+      ...candidates,
+      ...installed.map(integration => ({
+        source: /** @type {const} */ ('installed'),
+        integration,
+        spec: integration.__spec,
+      })),
+      ...extras.map(integration => ({
+        source: /** @type {const} */ ('extra'),
+        integration,
+        spec: integration.__spec,
+      })),
+    ],
+    {codemods: true, prior: providerLedgerOf(project)},
   );
-  return {postCodemodHooks, integrations};
+  return {postCodemodHooks, integrations, ledger};
 }
 
 /**
@@ -450,7 +459,10 @@ export async function selectIntegrationCodemodsFor(integrations, from, to) {
     try {
       const byVersion = await discoverIntegrationCodemods([integration]);
       for (const [version, rawList] of byVersion) {
-        const list = /** @type {Array<import('../../authoring/codemod/type').CodemodEntry>} */ (/** @type {unknown} */ (rawList));
+        const list =
+          /** @type {Array<import('../../authoring/codemod/type').CodemodEntry>} */ (
+            /** @type {unknown} */ (rawList)
+          );
         const existing = integrationCodemodsByVersion.get(version);
         if (existing) existing.push(...list);
         else integrationCodemodsByVersion.set(version, [...list]);
@@ -469,7 +481,10 @@ export async function selectIntegrationCodemodsFor(integrations, from, to) {
  * @param {Array<{version: string, codemods: import('../../authoring/codemod/type').CodemodEntry[]}>} versionGroups
  * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>}} options
  */
-export async function runIntegrationCodemodsStep(versionGroups, {apply, path: srcPath, codemod, skipCodemods}) {
+export async function runIntegrationCodemodsStep(
+  versionGroups,
+  {apply, path: srcPath, codemod, skipCodemods},
+) {
   const jscodeshift = (await import('jscodeshift')).default;
   return runIntegrationCodemods(versionGroups, {
     apply,

package/api/upgrade/provider-agreement.test.mjs

@@ -0,0 +1,152 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Where `upgrade` and Project still disagree on a provider ID's winner.
+ *
+ * Both repros are `it.fails`: each asserts the agreeing result, and fails
+ * today. `upgrade` lets an `--integration` extra of the same name@version stand
+ * in for an autolinked package, from any directory, and orders that extra with
+ * the extras. So another extra can take the provider ID in `upgrade` while
+ * every other command gives it to the autolinked package. The provider ledger
+ * property test carves out exactly this shape.
+ *
+ * Fixtures live under a repo-local temp dir, not /tmp, because Vite refuses to
+ * dynamically import a module from outside the project root.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {loadProjectContext} from './_adapter.mjs';
+import {Project, providerLedgerOf} from '../../foundation/config/project.mjs';
+
+let tmpDir;
+let originalCwd;
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  tmpDir = fs.mkdtempSync(
+    path.join(process.cwd(), '.astryx-upgrade-agreement-'),
+  );
+  process.chdir(tmpDir);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * Install a package under node_modules/<dir>.
+ * @param {string} dir
+ * @param {{name: string, version: string}} pkg
+ * @param {string} manifest manifest module source
+ */
+function install(dir, pkg, manifest) {
+  const pkgDir = path.join(tmpDir, 'node_modules', ...dir.split('/'));
+  fs.mkdirSync(pkgDir, {recursive: true});
+  fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify(pkg));
+  fs.writeFileSync(path.join(pkgDir, 'astryx.integration.mjs'), manifest);
+}
+
+/** An autolinked `@acme/a` and an `@acme/other` that claims its provider ID. */
+function autolinkedWithRival() {
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'consumer', dependencies: {'@acme/a': '1.0.0'}}),
+  );
+  install(
+    '@acme/a',
+    {name: '@acme/a', version: '1.0.0'},
+    'export default {};\n',
+  );
+  install(
+    '@acme/other',
+    {name: '@acme/other', version: '1.0.0'},
+    "export default {providerId: '@acme/a'};\n",
+  );
+}
+
+/**
+ * The package each resolution lets contribute under a provider ID.
+ * @param {Map<string, any>} ledger
+ * @param {string} providerId
+ */
+function winnerOf(ledger, providerId) {
+  return [...ledger.values()].find(
+    entry => entry.outcome === 'contributes' && entry.providerId === providerId,
+  )?.key;
+}
+
+/** @param {Array<import('../../foundation/integrations/integrations.mjs').LoadedIntegration>} integrations */
+function claims(integrations) {
+  return integrations.map(integration => [
+    integration.name,
+    integration.__providerConflict?.claimedBy ?? null,
+  ]);
+}
+
+describe('upgrade and Project on an autolinked package named with --integration', () => {
+  it('agree when the autolinked package is named first', async () => {
+    autolinkedWithRival();
+    const project = await Project.load(tmpDir, {fresh: true});
+    const upgrade = await loadProjectContext(tmpDir, [
+      '@acme/a',
+      '@acme/other',
+    ]);
+
+    expect(claims(upgrade.integrations)).toEqual([
+      ['@acme/a', null],
+      ['@acme/other', '@acme/a'],
+    ]);
+    expect(winnerOf(upgrade.ledger, '@acme/a')).toBe(
+      winnerOf(providerLedgerOf(project), '@acme/a'),
+    );
+  });
+
+  it.fails(
+    'agree when an extra that claims its ID is named first',
+    async () => {
+      autolinkedWithRival();
+      const project = await Project.load(tmpDir, {fresh: true});
+      // Today upgrade runs @acme/other and reports @acme/a, which every other
+      // command uses, as contributing nothing.
+      const upgrade = await loadProjectContext(tmpDir, [
+        '@acme/other',
+        '@acme/a',
+      ]);
+
+      expect(winnerOf(upgrade.ledger, '@acme/a')).toBe(
+        winnerOf(providerLedgerOf(project), '@acme/a'),
+      );
+      expect(claims(upgrade.integrations)).toEqual([
+        ['@acme/other', '@acme/a'],
+        ['@acme/a', null],
+      ]);
+    },
+  );
+
+  it.fails(
+    'agree when a copy of it in another directory is named',
+    async () => {
+      autolinkedWithRival();
+      // The same name@version in another directory, with a manifest that fails.
+      install(
+        '@acme/a-copy',
+        {name: '@acme/a', version: '1.0.0'},
+        "throw new Error('broken copy');\n",
+      );
+      const project = await Project.load(tmpDir, {fresh: true});
+      // Today the broken copy stands in for @acme/a by name@version, so upgrade
+      // has no claimant left for the ID and @acme/other takes it.
+      const upgrade = await loadProjectContext(tmpDir, [
+        '@acme/a-copy',
+        '@acme/other',
+      ]);
+
+      expect(winnerOf(upgrade.ledger, '@acme/a')).toBe(
+        winnerOf(providerLedgerOf(project), '@acme/a'),
+      );
+    },
+  );
+});

package/api/upgrade/run/run.mjs

@@ -171,6 +171,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
     path: path_,
     codemod: options.codemod,
     skipCodemods,
+    root: cwd,
   });
   const coreResult = codemodResult && 'totalFilesChanged' in codemodResult ? codemodResult : null;
 

package/api/upgrade/upgrade.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'upgrade',
+  namespace: 'cli/api',
   displayName: 'upgrade()',
   summary: 'Run version migrations and reconcile copied compositions.',
   description:

package/assets/codemods/integration-discovery.mjs

@@ -106,7 +106,7 @@ function collectCodemodFiles(versionDir) {
 /**
  * Discover file-based codemods contributed by configured integrations.
  *
- * @param {Array<{name?: string, codemods?: string, __spec?: string}>} loadedIntegrations
+ * @param {Array<{name?: string, codemods?: string, __spec?: string, __packageDir?: string}>} loadedIntegrations
  * @returns {Promise<Map<string, Array<{id: string, type: 'code'|'config', codemod: object, package: string}>>>}
  *   Map keyed by version string; each value is the list of discovered codemods
  *   for that version (across all integrations).
@@ -145,7 +145,13 @@ export async function discoverIntegrationCodemods(loadedIntegrations = []) {
       const seenInVersion = new Set();
 
       for (const {id, file} of files) {
-        const label = `Integration "${pkgLabel}" codemod ${version}/${id} (${file})`;
+        const shown = integration.__packageDir
+          ? path
+              .relative(integration.__packageDir, file)
+              .split(path.sep)
+              .join('/')
+          : file;
+        const label = `Integration "${pkgLabel}" codemod ${version}/${id} (${shown})`;
 
         if (seenInVersion.has(id)) {
           throw new Error(

package/assets/codemods/integration-discovery.test.mjs

@@ -163,6 +163,21 @@ describe('integration codemod discovery', () => {
     ).rejects.toThrow(/is invalid/i);
   });
 
+  it('names a broken codemod by its path inside the package', async () => {
+    scaffold({
+      '1.1.0/no-default.mjs': `export const nope = 1;\n`,
+    });
+    const project = await Project.load(tmpDir);
+    const failure = await discoverIntegrationCodemods(
+      project.loadedIntegrations,
+    ).then(
+      () => null,
+      error => error,
+    );
+    expect(failure?.message).toContain('(codemods/1.1.0/no-default.mjs)');
+    expect(failure?.message).not.toContain(tmpDir);
+  });
+
   it('fails discovery when default export is not a codemod envelope', async () => {
     scaffold({
       '0.2.0/bad.mjs': `export default { title: 'x', transform: () => null };\n`,

package/assets/codemods/runner.mjs

@@ -194,6 +194,89 @@ function toUnifiedEntry(transformEntry, version) {
   };
 }
 
+/**
+ * What a core PROJECT codemod plans: whole files to write and delete under the
+ * project root, or the problems that stop it. Paths in `writes` and `deletes`
+ * are absolute; `problems` name package-relative files.
+ *
+ * @typedef {object} ProjectCodemodPlan
+ * @property {Array<{path: string, contents: string}>} writes
+ * @property {string[]} deletes
+ * @property {Array<{file: string, message: string}>} problems
+ */
+
+/**
+ * Run one core PROJECT codemod (`meta.codemodType === 'project'`): instead of
+ * rewriting the files it is handed, it reads the project and plans whole-file
+ * writes and deletions, which this applies (or previews) as one unit. A plan
+ * that names a problem changes nothing. Core-only: integration codemods keep
+ * the file contract.
+ *
+ * @param {{name: string, transform: unknown}} transformEntry
+ * @param {{apply: boolean, root: string, log: {success: (m: string) => void, warn: (m: string) => void, error: (m: string) => void}}} options
+ * @returns {Promise<{filesChanged: number, writtenFiles: string[], errors: Array<{file: string, codemod: string, error: string}>}>}
+ */
+async function runProjectCodemod({name, transform}, {apply, root, log}) {
+  /** @param {string} file */
+  const rel = file => path.relative(root, file).split(path.sep).join('/');
+  /** @type {ProjectCodemodPlan} */
+  let plan;
+  try {
+    plan = await /** @type {(root: string) => Promise<ProjectCodemodPlan>} */ (
+      transform
+    )(root);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error(`    ✗ ${message}`);
+    return {
+      filesChanged: 0,
+      writtenFiles: [],
+      errors: [{file: '.', codemod: name, error: message}],
+    };
+  }
+  if (plan.problems.length > 0) {
+    for (const {file, message} of plan.problems) {
+      log.error(`    ✗ ${file} — ${message}`);
+    }
+    return {
+      filesChanged: 0,
+      writtenFiles: [],
+      errors: plan.problems.map(({file, message}) => ({
+        file,
+        codemod: name,
+        error: message,
+      })),
+    };
+  }
+  /** @type {string[]} */
+  const writtenFiles = [];
+  for (const write of plan.writes) {
+    if (apply) {
+      fs.mkdirSync(path.dirname(write.path), {recursive: true});
+      fs.writeFileSync(write.path, write.contents, 'utf-8');
+      writtenFiles.push(write.path);
+      log.success(`    ✓ ${rel(write.path)}`);
+    } else {
+      log.warn(`    ~ ${rel(write.path)} (would write)`);
+    }
+  }
+  // Deletions go last, so a failed write leaves a state a rerun completes.
+  for (const file of plan.deletes) {
+    if (apply) {
+      fs.rmSync(file);
+      writtenFiles.push(file);
+      log.success(`    ✓ ${rel(file)} (removed)`);
+    } else {
+      log.warn(`    ~ ${rel(file)} (would remove)`);
+    }
+  }
+  return {
+    filesChanged: plan.writes.length + plan.deletes.length,
+    writtenFiles,
+    errors: [],
+  };
+}
+
 /**
  * Run codemods against source files.
  *
@@ -204,11 +287,19 @@ function toUnifiedEntry(transformEntry, version) {
  * @param {string|undefined} options.codemod - Run only this specific transform
  * @param {Set<string>} [options.skipCodemods] - Transform names to exclude
  * @param {boolean} [options.silent] - Suppress all human-facing output (for --json)
+ * @param {string} [options.root] - Project root a project codemod reads (default: the process cwd)
  * @returns {Promise<{totalFilesChanged: number, totalTransformsApplied: number, totalValidationBlocked: number, writtenFiles: string[], errors: Array<{file: string, codemod: string, error: string}>, skippedOptional: Array<{name: string, meta: {title: string, description?: string, fileExtensions?: string[], codemodType?: string}, version: string}>} | {ok: false, reason: string, resolvedPath: string}>}
  */
 export async function runCodemods(
   versionManifests,
-  {apply, path: srcPath, codemod, skipCodemods, silent = false},
+  {
+    apply,
+    path: srcPath,
+    codemod,
+    skipCodemods,
+    silent = false,
+    root = process.cwd(),
+  },
 ) {
   // No-op stub object so silent mode skips log output entirely without
   // littering the body with `if (!silent)` guards.
@@ -221,11 +312,14 @@ export async function runCodemods(
 
   const resolvedPath = path.resolve(srcPath);
 
-  // Config codemods target the consumer's astryx.config.* and never read
-  // source files, so a missing --path should not block them. Only hard-fail
-  // on a missing source path when there is at least one CODE codemod to run.
+  // Config and project codemods never read the files under --path, so a
+  // missing --path should not block them. Only hard-fail on a missing source
+  // path when there is at least one CODE codemod to run.
   const hasCodeCodemod = versionManifests.some(({transforms}) =>
-    transforms.some(t => t.meta?.codemodType !== 'config'),
+    transforms.some(
+      t =>
+        t.meta?.codemodType !== 'config' && t.meta?.codemodType !== 'project',
+    ),
   );
   const sourcePathExists = fs.existsSync(resolvedPath);
 
@@ -290,6 +384,22 @@ export async function runCodemods(
       // `(file, api)` contract and targets the consumer's astryx.config.*.
       // A core entry signals "config" via `meta.codemodType === 'config'`
       // (see toUnifiedEntry).
+      if (meta?.codemodType === 'project') {
+        const result = await runProjectCodemod(transformEntry, {
+          apply,
+          root,
+          log,
+        });
+        if (result.errors.length > 0) {
+          errors.push(...result.errors);
+        } else if (result.filesChanged > 0) {
+          totalFilesChanged += result.filesChanged;
+          totalTransformsApplied += 1;
+          writtenFiles.push(...result.writtenFiles);
+        }
+        continue;
+      }
+
       if (meta?.codemodType === 'config') {
         const result = runConfigCodemod(toUnifiedEntry(transformEntry, version), {
           apply,