@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

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);
 
@@ -104,6 +105,27 @@ export function uniqueFiles(files) {
   ];
 }
 
+/**
+ * Run app code with its stdout writes sent to stderr. Stdout carries only the
+ * command's own output, so a hook that prints cannot corrupt `--json`.
+ * @template T
+ * @param {() => T | Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+async function withStdoutOnStderr(fn) {
+  const realWrite = process.stdout.write;
+  process.stdout.write = /** @type {any} */ (
+    function (/** @type {any} */ chunk, /** @type {any[]} */ ...rest) {
+      return process.stderr.write(chunk, ...rest);
+    }
+  );
+  try {
+    return await fn();
+  } finally {
+    process.stdout.write = realWrite;
+  }
+}
+
 /**
  * Run the app config's post-codemod hooks (config.hooks.postCodemod).
  * Dry-run PREVIEWS (buildCommand still called, so a throw fails); apply executes.
@@ -123,7 +145,9 @@ export async function runPostCodemodHooks(hooks, context) {
       );
     }
 
-    const cmd = await hook.buildCommand({packageDir, files});
+    const cmd = await withStdoutOnStderr(() =>
+      hook.buildCommand({packageDir, files}),
+    );
     if (!cmd) {
       logger.log(`Post-codemod hook ${label} produced no command; skipping.`);
       continue;
@@ -147,7 +171,7 @@ export async function runPostCodemodHooks(hooks, context) {
         env: {...process.env, ...(cmd.options?.env ?? {})},
       }),
     );
-    logger.log(`✓ Post-codemod hook ${label} completed.`);
+    logger.log(`[ok] Post-codemod hook ${label} completed.`);
   }
 }
 
@@ -186,7 +210,7 @@ export async function prepareAgentDocsRefresh({
   if (initial.status === 'missing') {
     summary.action = 'nudge-init';
     logger.warn(
-      `No Astryx agent-docs block found — AI agents have no component index. Run \`${formatCliCommand('astryx init --features agents')}\` to install it.`,
+      `No Astryx agent-docs block found - AI agents have no component index. Run \`${formatCliCommand('astryx init --features agents')}\` to install it.`,
     );
     return {cwd, renderedBlock: null, summary};
   }
@@ -240,7 +264,7 @@ export function applyAgentDocsRefresh(plan) {
     summary.files = written;
     summary.action = summary.refreshed ? 'refreshed' : 'error';
     if (summary.refreshed) {
-      logger.log(`✓ Agent docs refreshed → ${written.join(', ')}`);
+      logger.log(`[ok] Agent docs refreshed -> ${written.join(', ')}`);
     } else {
       logger.warn(
         `Agent docs look stale but couldn't be refreshed. Run \`${formatCliCommand('astryx init --features agents')}\` to reinstall the block.`,
@@ -268,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;
@@ -299,33 +329,36 @@ 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, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean}} options
  */
-export async function runCoreCodemods(versionManifests, {apply, path: srcPath, codemod, skipCodemods}) {
+export async function runCoreCodemods(
+  versionManifests,
+  {apply, path: srcPath, codemod, skipCodemods, root, protection, silent},
+) {
   return runCodemods(versionManifests, {
     apply,
     path: srcPath,
     codemod,
     skipCodemods,
-    silent: logger.silent,
+    silent: silent ?? logger.silent,
+    root,
+    protection,
   });
 }
 
-/**
- * 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
@@ -337,23 +370,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),
   );
@@ -361,38 +409,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 {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)},
   );
-  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),
-  );
-  return {postCodemodHooks, integrations};
+  return {postCodemodHooks, integrations, ledger};
 }
 
 /**
@@ -427,7 +460,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]);
@@ -444,9 +480,21 @@ export async function selectIntegrationCodemodsFor(integrations, from, to) {
 /**
  * Run the file-based INTEGRATION codemods (config codemods first, then code).
  * @param {Array<{version: string, codemods: import('../../authoring/codemod/type').CodemodEntry[]}>} versionGroups
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, contents?: Map<string, string>, silent?: boolean}} options
  */
-export async function runIntegrationCodemodsStep(versionGroups, {apply, path: srcPath, codemod, skipCodemods}) {
+export async function runIntegrationCodemodsStep(
+  versionGroups,
+  {
+    apply,
+    path: srcPath,
+    codemod,
+    skipCodemods,
+    root,
+    protection,
+    contents,
+    silent,
+  },
+) {
   const jscodeshift = (await import('jscodeshift')).default;
   return runIntegrationCodemods(versionGroups, {
     apply,
@@ -454,6 +502,9 @@ export async function runIntegrationCodemodsStep(versionGroups, {apply, path: sr
     codemod,
     skipCodemods,
     jscodeshift,
-    silent: logger.silent,
+    silent: silent ?? logger.silent,
+    root,
+    protection,
+    contents,
   });
 }

package/api/upgrade/list/list.mjs

@@ -10,6 +10,7 @@
 
 import {collectAllCodemods} from '../_adapter.mjs';
 import {logger} from '../../logger.mjs';
+import {toAscii} from '../../../assets/codemods/term-log.mjs';
 
 /**
  * List every available codemod (oldest→newest).
@@ -19,7 +20,7 @@ export async function list() {
   const codemods = await collectAllCodemods();
   logger.log('Available codemods:');
   for (const {name, title, pr, optional} of codemods) {
-    logger.log(`  ${name} — ${title}${optional ? ' (optional)' : ''} (${pr})`);
+    logger.log(`  ${name} - ${toAscii(title)}${optional ? ' (optional)' : ''} (${pr})`);
   }
   logger.log('Done\n');
   return {

package/api/upgrade/list/list.test.mjs

@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated tests for the upgrade.list leaf: every field an entry
+ * carries is declared on the canonical `UpgradeListEntry` type, and every
+ * declared field is present on every entry.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import ts from 'typescript';
+import {list} from './list.mjs';
+
+const TYPE_FILE = fileURLToPath(
+  new URL('../upgrade.type.mjs', import.meta.url),
+);
+
+/**
+ * Property names a JSDoc `@typedef {object}` declares, parsed from the file.
+ * @param {string} typedefName
+ * @returns {string[]}
+ */
+function declaredProperties(typedefName) {
+  const source = ts.createSourceFile(
+    TYPE_FILE,
+    fs.readFileSync(TYPE_FILE, 'utf8'),
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.JS,
+  );
+  /** @type {string[]} */
+  const names = [];
+  for (const statement of source.statements) {
+    for (const doc of /** @type {any} */ (statement).jsDoc ?? []) {
+      for (const tag of doc.tags ?? []) {
+        if (
+          !ts.isJSDocTypedefTag(tag) ||
+          tag.name?.getText(source) !== typedefName
+        ) {
+          continue;
+        }
+        const literal = tag.typeExpression;
+        if (literal && ts.isJSDocTypeLiteral(literal)) {
+          for (const property of literal.jsDocPropertyTags ?? []) {
+            names.push(property.name.getText(source));
+          }
+        }
+      }
+    }
+  }
+  return names.sort();
+}
+
+describe('upgrade.list entries', () => {
+  it('carry exactly the fields UpgradeListEntry declares', async () => {
+    const declared = declaredProperties('UpgradeListEntry');
+    expect(declared.length).toBeGreaterThan(0);
+
+    const {type, data} = await list();
+    expect(type).toBe('upgrade.list');
+    expect(data.length).toBeGreaterThan(0);
+    for (const entry of data) {
+      expect(Object.keys(entry).sort()).toEqual(declared);
+    }
+  });
+
+  it('marks optional codemods with a boolean', async () => {
+    const {data} = await list();
+    for (const entry of data) expect(typeof entry.optional).toBe('boolean');
+    expect(data.some(entry => entry.optional)).toBe(true);
+  });
+});

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'),
+      );
+    },
+  );
+});