@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ebaebc4

package/api/theme/theme.type.mjs

@@ -6,23 +6,23 @@
  * directly (functions own their types); the public `@astryxdesign/cli/api`
  * surface re-exports them via types/theme.d.ts, so consumers see the same names.
  *
- * Invocation                                 -> type discriminator
+ * Invocation                                  -> type discriminator
  * ------------------------------------------------------------------
- * xds --json theme build <file>             -> theme.build
- * xds --json theme build <file> --check     -> theme.build.check
- * xds --json theme build <a> <b> …          -> theme.build.batch
- * xds --json theme list                     -> theme.list
- * xds --json theme add <slug>               -> theme.add
- * xds --json theme template                 -> theme.template
- * xds --json theme targets [filter]         -> theme.targets
- * xds --json theme palette generate <file>  -> theme.palette.generate
- * (file not found / parse error)            -> CLIError
+ * astryx --json theme build <file>            -> theme.build
+ * astryx --json theme build <file> --check    -> theme.build.check
+ * astryx --json theme build <a> <b> …         -> theme.build.batch
+ * astryx --json theme list                    -> theme.list
+ * astryx --json theme add <slug>              -> theme.add
+ * astryx --json theme template                -> theme.template
+ * astryx --json theme targets [filter]        -> theme.targets
+ * astryx --json theme palette generate <file> -> theme.palette.generate
+ * (file not found / parse error)              -> CLIError
  *
  * @position api — colocated typedefs for api/theme/{theme,build,add,list,template,targets,_adapter}
  */
 
 /**
- * xds --json theme build <file>
+ * astryx --json theme build <file>
  * @typedef {object} ThemeBuildResponse
  * @property {'theme.build'} type
  * `warnings` are defects the theme author should fix. `notices` are advisories
@@ -32,14 +32,14 @@
  */
 
 /**
- * xds --json theme build <file> --check
+ * astryx --json theme build <file> --check
  * @typedef {object} ThemeBuildCheckResponse
  * @property {'theme.build.check'} type
  * @property {{name: string, upToDate: boolean, stale: Array<{path: string, reason: 'missing' | 'outdated'}>, checked: string[]}} data
  */
 
 /**
- * xds --json theme build <a> <b> … — several themes in one invocation. Each
+ * astryx --json theme build <a> <b> … — several themes in one invocation. Each
  * result carries the file as it was passed and the receipt a single-file build
  * would have returned (null when that theme produced no CSS). One file still
  * returns the bare theme.build / theme.build.check envelope.
@@ -59,21 +59,21 @@
  */
 
 /**
- * xds --json theme list
+ * astryx --json theme list
  * @typedef {object} ThemeListResponse
  * @property {'theme.list'} type
  * @property {ThemeListEntry[]} data
  */
 
 /**
- * xds --json theme add <slug>
+ * astryx --json theme add <slug>
  * @typedef {object} ThemeAddResponse
  * @property {'theme.add'} type
  * @property {{slug: string, displayName: string, maintained: boolean, package: string, outputDir: string, entry: string, exportName: string, files: string[]}} data
  */
 
 /**
- * xds --json theme template
+ * astryx --json theme template
  * `written: false` with `reason: 'exists'` is a success: the command is safe to
  * re-run, and an edited template is the consumer's file to keep.
  * @typedef {object} ThemeTemplateResponse
@@ -95,19 +95,19 @@
  */
 
 /**
- * xds --json theme targets [filter]
+ * astryx --json theme targets [filter]
  * @typedef {object} ThemeTargetsResponse
  * @property {'theme.targets'} type
  * @property {{filter: string | null, componentCount: number, targets: ThemeTargetEntry[]}} data
  */
 
 /**
- * A generated palette candidate. The palette is still subject to author review
- * and is not connected to runtime theme values.
+ * A color an author pins at one stop of one mode, constraining generation.
  * @typedef {object} TonalPaletteAnchor
  * @property {'light' | 'dark'} mode Mode containing the anchored stop.
  * @property {number} stop Existing requested stop where the anchor applies.
- * @property {string} color
+ * @property {string} color sRGB hex the stop is pulled toward: three or six
+ * digits, with or without `#`; the generator normalizes it.
  * @property {'exact' | 'bounded' | 'flexible'} policy `exact` preserves the
  * chosen color at that stop; `bounded` permits adjustment within `maxDeltaE`;
  * `flexible` treats the color as guidance and blends toward it.
@@ -116,12 +116,16 @@
  */
 
 /**
+ * One requested family: a seed color and the constraints applied to its ramp.
  * @typedef {object} TonalPaletteFamilyInput
- * @property {string} id
- * @property {string} seed
- * @property {string} [name]
- * @property {'chromatic' | 'neutral'} [kind]
- * @property {TonalPaletteAnchor[]} [anchors]
+ * @property {string} id Lower-kebab-case key for the family in the generated
+ * palette. `black` and `white` are reserved for the standalone values.
+ * @property {string} seed sRGB hex the ramp is generated from: three or six
+ * digits, with or without `#`; the generator normalizes it.
+ * @property {string} [name] Display name for review artifacts; defaults to `id`.
+ * @property {'chromatic' | 'neutral'} [kind] `neutral` derives the ramp from
+ * `neutralProfile` instead of the seed hue; defaults to `chromatic`.
+ * @property {TonalPaletteAnchor[]} [anchors] Colors pinned at specific stops.
  */
 
 /**
@@ -130,6 +134,9 @@
  * @property {number} [vibrancy] Chroma control from 0 (most muted) through 50
  * (default) to 100 (most vivid).
  * @property {'neutral-v1' | 'warm-v1' | 'cool-v1' | 'custom'} [neutralProfile]
+ * Hue treatment for `neutral` families: `neutral-v1` is fully achromatic,
+ * `warm-v1` and `cool-v1` add a slight tint, and `custom` derives the hue from
+ * the family's own seed. Defaults to `neutral-v1`.
  * @property {'light-only' | 'dark-only' | 'light-and-dark'} [modeStrategy]
  * @property {number[]} [stops] Ordered stops shared by every requested family;
  * defaults to 0 through 100 in increments of 5. Decimal stops are supported,
@@ -137,6 +144,8 @@
  */
 
 /**
+ * A generated palette candidate. The palette is still subject to author review
+ * and is not connected to runtime theme values.
  * @typedef {object} TonalPaletteCandidate
  * @property {1} schemaVersion
  * @property {'candidate'} status
@@ -148,10 +157,68 @@
  */
 
 /**
- * xds --json theme palette generate <config>
+ * Per-ramp evidence recorded for one family in one mode.
+ * @typedef {object} TonalPaletteRampDiagnostics
+ * @property {boolean} monotonic Whether luminance rises across every stop.
+ * @property {number} minimumAdjacentDeltaE Smallest perceptual gap between
+ * neighboring stops; a small value means two stops read as one color.
+ * @property {number} maximumAdjacentDeltaE Largest gap between neighboring stops.
+ * @property {number} maximumHueDrift Largest hue distance, in degrees, between
+ * a stop and the family's reference hue.
+ * @property {'blue-to-purple' | 'yellow-to-brown' | null} hueIdentityRisk Named
+ * drift the ramp is at risk of, or `null`.
+ * @property {number[]} gamutMappedStops Stops whose ideal color fell outside
+ * sRGB and was mapped back into it.
+ * @property {Array<TonalPaletteAnchor & {generatedColor: string, deltaE: number}>} anchors
+ * Each anchor with the color the stop received after its policy was applied
+ * and the perceptual distance that color still has from the requested target.
+ */
+
+/**
+ * Cross-family evidence for one mode, sampled at the stop nearest 50.
+ * @typedef {object} TonalPaletteCoordinationDiagnostics
+ * @property {'light' | 'dark'} mode Mode these samples come from.
+ * @property {number} stop Sampled stop.
+ * @property {[string, string] | null} closestFamilies The two chromatic
+ * families hardest to tell apart, or `null` with fewer than two.
+ * @property {number | null} minimumFamilyDeltaE Perceptual distance between them.
+ * @property {string | null} strongestFamily Most saturated family at this stop.
+ * @property {string | null} weakestFamily Least saturated family at this stop.
+ * @property {number | null} chromaRatio Strongest chroma over weakest; a large
+ * ratio means the families are unbalanced.
+ */
+
+/**
+ * The request as the generator resolved it, with every default filled in.
+ * @typedef {object} TonalPaletteNormalizedRequest
+ * @property {'astryx-oklch-v1'} recipe
+ * @property {number} vibrancy
+ * @property {'neutral-v1' | 'warm-v1' | 'cool-v1' | 'custom'} neutralProfile
+ * @property {'light-only' | 'dark-only' | 'light-and-dark'} modeStrategy
+ * @property {number[]} stops
+ * @property {Array<{id: string, name: string, seed: string, kind: 'chromatic' | 'neutral', anchors: TonalPaletteAnchor[]}>} families
+ */
+
+/**
+ * The detached receipt written beside a candidate. It records what was asked
+ * for and what the generator observed, so a candidate can be traced back to
+ * its request without rerunning generation.
+ * @typedef {object} TonalPaletteGenerationReceipt
+ * @property {1} schemaVersion
+ * @property {'astryx-oklch-v1'} recipe Recipe that produced the candidate.
+ * @property {string} candidateSha256 SHA-256 over the candidate bytes as written.
+ * @property {{version: string, sha256: string}} [preview] Present when preview
+ * content was generated for the request, even if no file was written because
+ * the target already exists.
+ * @property {TonalPaletteNormalizedRequest} request
+ * @property {{families: Record<string, {light?: TonalPaletteRampDiagnostics, dark?: TonalPaletteRampDiagnostics}>, coordination: TonalPaletteCoordinationDiagnostics[]}} diagnostics
+ */
+
+/**
+ * astryx --json theme palette generate <config>
  * @typedef {object} ThemePaletteGenerateResponse
  * @property {'theme.palette.generate'} type
- * @property {{recipe: 'astryx-oklch-v1', status: 'candidate', familyCount: number, stopCount: number, modes: string[], output: string | null, receipt: string | null, preview: string | null, written: boolean, reason: 'exists' | null, candidate: TonalPaletteCandidate, generationReceipt: Record<string, unknown>}} data
+ * @property {{recipe: 'astryx-oklch-v1', status: 'candidate', familyCount: number, stopCount: number, modes: string[], output: string | null, receipt: string | null, preview: string | null, written: boolean, reason: 'exists' | null, candidate: TonalPaletteCandidate, generationReceipt: TonalPaletteGenerationReceipt}} data
  */
 
 // Make this a module so the @typedefs above are importable as types via

package/api/upgrade/_adapter.mjs

@@ -33,7 +33,10 @@ import {
 } from '../../foundation/agent-docs/agent-docs.mjs';
 import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
 import {Project} from '../../foundation/config/project.mjs';
-import {loadIntegrations} from '../../foundation/integrations/integrations.mjs';
+import {
+  loadIntegrations,
+  markProviderConflicts,
+} from '../../foundation/integrations/integrations.mjs';
 import {warnOnIntegrationIssues} from '../../foundation/integrations/integration-warnings.mjs';
 import {logger} from '../logger.mjs';
 
@@ -308,6 +311,15 @@ export async function runCoreCodemods(versionManifests, {apply, path: srcPath, c
   });
 }
 
+/**
+ * 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.
@@ -321,11 +333,65 @@ export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
   // cache entry; ordinary Project discovery remains cached by default.
   const project = await Project.load(cwd, {fresh: true});
   const postCodemodHooks = project.config.hooks?.postCodemod ?? [];
-  const integrationSpecs = uniqueFiles([
-    ...(project.integrations ?? []),
-    ...(extraIntegrationSpecs ?? []),
+  const configuredSpecs = new Set(project.integrations ?? []);
+  // 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),
+  );
+  // 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.
+  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 extraSpecs = uniqueFiles(extraIntegrationSpecs ?? []).filter(
+    spec => !configuredSpecs.has(spec),
+  );
+  const extras =
+    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,
   ]);
-  const integrations = await loadIntegrations(integrationSpecs);
+  // 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};
 }
 

package/api/upgrade/project-context.test.mjs

@@ -0,0 +1,272 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `loadProjectContext` agrees with Project on provider identity, so
+ * `astryx upgrade` never runs codemods from a package Project set aside.
+ *
+ * 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, selectIntegrationCodemodsFor} from './_adapter.mjs';
+
+let tmpDir;
+let originalCwd;
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-upgrade-context-'));
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * Install an integration package that ships one 0.2.0 codemod.
+ * @param {string} name
+ * @param {string} version
+ * @param {Record<string, unknown>} [manifest]
+ */
+function installWithCodemod(name, version, manifest = {}) {
+  const pkgDir = path.join(tmpDir, 'node_modules', ...name.split('/'));
+  const codemodDir = path.join(pkgDir, 'codemods', '0.2.0');
+  fs.mkdirSync(codemodDir, {recursive: true});
+  fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify({name, version}));
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default ${JSON.stringify({codemods: './codemods', ...manifest})};\n`,
+  );
+  fs.writeFileSync(
+    path.join(codemodDir, 'rename.mjs'),
+    "export default {type: 'code', title: 'Rename', transform: file => file.source};\n",
+  );
+}
+
+/** @param {string[]} integrations */
+function configure(integrations) {
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.config.mjs'),
+    `export default ${JSON.stringify({integrations})};\n`,
+  );
+}
+
+describe('loadProjectContext provider identity', () => {
+  it('keeps codemods from a configured package the authored package sets aside', async () => {
+    installWithCodemod('@acme/widgets', '1.0.0');
+    configure(['@acme/widgets']);
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/renamed', version: '2.0.0-dev'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {providerId: '@acme/widgets'};\n",
+    );
+
+    const {integrations} = await loadProjectContext(tmpDir);
+    expect(
+      integrations.map(integration => [
+        integration.name,
+        Boolean(integration.__providerConflict),
+      ]),
+    ).toEqual([['@acme/widgets', true]]);
+    expect(
+      await selectIntegrationCodemodsFor(integrations, '0.1.0', '0.3.0'),
+    ).toEqual([]);
+  });
+
+  it('still selects codemods from a configured package nothing else claims', async () => {
+    installWithCodemod('@acme/widgets', '1.0.0');
+    configure(['@acme/widgets']);
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
+
+    const {integrations} = await loadProjectContext(tmpDir);
+    const selected = await selectIntegrationCodemodsFor(integrations, '0.1.0', '0.3.0');
+    expect(selected.map(entry => entry.version)).toEqual(['0.2.0']);
+  });
+
+  it('sets aside an --integration extra that claims a configured provider ID', async () => {
+    installWithCodemod('@acme/widgets', '1.0.0');
+    installWithCodemod('@acme/other', '1.0.0', {providerId: '@acme/widgets'});
+    configure(['@acme/widgets']);
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
+    // `--integration` specs resolve from the process cwd, as they always have.
+    process.chdir(tmpDir);
+
+    const {integrations} = await loadProjectContext(tmpDir, ['@acme/other']);
+    expect(
+      integrations.map(integration => [
+        integration.name,
+        integration.__providerConflict?.claimedBy ?? null,
+      ]),
+    ).toEqual([
+      ['@acme/widgets', null],
+      ['@acme/other', '@acme/widgets'],
+    ]);
+  });
+
+  it('runs the installed copy of a package that lists itself, not its work in progress', async () => {
+    installWithCodemod('@acme/widgets', '1.0.0');
+    configure(['@acme/widgets']);
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '3.0.0-dev'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {codemods: './codemods'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'codemods', '0.2.0'), {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, 'codemods', '0.2.0', 'local-wip.mjs'),
+      "export default {type: 'code', title: 'Local WIP', transform: file => file.source};\n",
+    );
+
+    const {integrations} = await loadProjectContext(tmpDir);
+    expect(
+      integrations.map(integration => [
+        integration.name,
+        integration.version,
+        Boolean(integration.__local),
+        Boolean(integration.__providerConflict),
+      ]),
+    ).toEqual([['@acme/widgets', '1.0.0', false, false]]);
+    const selected = JSON.stringify(
+      await selectIntegrationCodemodsFor(integrations, '0.1.0', '0.3.0'),
+    );
+    expect(selected).toContain('rename');
+    expect(selected).not.toContain('local-wip');
+  });
+
+  it('runs the installed copy when the authored package is named with --integration', async () => {
+    installWithCodemod('@acme/widgets', '1.0.0');
+    configure([]);
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '3.0.0-dev'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {codemods: './codemods'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'codemods', '0.2.0'), {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, 'codemods', '0.2.0', 'local-wip.mjs'),
+      "export default {type: 'code', title: 'Local WIP', transform: file => file.source};\n",
+    );
+    process.chdir(tmpDir);
+
+    const {integrations} = await loadProjectContext(tmpDir, ['@acme/widgets']);
+    expect(
+      integrations.map(integration => [
+        integration.name,
+        integration.version,
+        Boolean(integration.__local),
+        integration.__providerConflict?.claimedBy ?? null,
+      ]),
+    ).toEqual([['@acme/widgets', '1.0.0', false, null]]);
+    const selected = JSON.stringify(
+      await selectIntegrationCodemodsFor(integrations, '0.1.0', '0.3.0'),
+    );
+    expect(selected).toContain('rename');
+    expect(selected).not.toContain('local-wip');
+  });
+
+  it("sets aside an --integration extra that claims an autolinked package's ID", async () => {
+    installWithCodemod('@acme/a', '1.0.0');
+    installWithCodemod('@acme/b', '1.0.0', {providerId: '@acme/a'});
+    configure([]);
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'consumer', dependencies: {'@acme/a': '1.0.0'}}),
+    );
+    process.chdir(tmpDir);
+
+    const {integrations} = await loadProjectContext(tmpDir, ['@acme/b']);
+    expect(
+      integrations.map(integration => [
+        integration.name,
+        integration.__providerConflict?.claimedBy ?? null,
+      ]),
+    ).toEqual([['@acme/b', '@acme/a']]);
+    expect(
+      await selectIntegrationCodemodsFor(integrations, '0.1.0', '0.3.0'),
+    ).toEqual([]);
+  });
+
+  it('runs an autolinked package the user names with --integration', async () => {
+    installWithCodemod('@acme/a', '1.0.0');
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'consumer', dependencies: {'@acme/a': '1.0.0'}}),
+    );
+    process.chdir(tmpDir);
+
+    const {integrations} = await loadProjectContext(tmpDir, ['@acme/a']);
+    expect(
+      integrations.map(integration => [
+        integration.name,
+        integration.__providerConflict?.claimedBy ?? null,
+      ]),
+    ).toEqual([['@acme/a', null]]);
+    const selected = await selectIntegrationCodemodsFor(integrations, '0.1.0', '0.3.0');
+    expect(selected.map(entry => entry.version)).toEqual(['0.2.0']);
+  });
+
+  it('never reports a claimant that every other command uses as set aside', async () => {
+    installWithCodemod('@acme/widgets', '1.0.0');
+    installWithCodemod('@acme/renamed', '2.0.0', {providerId: '@acme/widgets'});
+    configure(['@acme/widgets']);
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({
+        name: '@acme/widgets',
+        version: '3.0.0-dev',
+        dependencies: {'@acme/renamed': '2.0.0'},
+      }),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {providerId: '@acme/widgets-next'};\n",
+    );
+
+    const {integrations} = await loadProjectContext(tmpDir);
+    expect(
+      integrations.map(integration => [
+        integration.name,
+        integration.version,
+        integration.__providerConflict?.claimedBy ?? null,
+      ]),
+    ).toEqual([['@acme/widgets', '1.0.0', null]]);
+  });
+
+  it("sets aside an --integration extra that claims the authored package's ID", async () => {
+    installWithCodemod('@acme/widgets', '1.0.0');
+    configure([]);
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/renamed', version: '2.0.0-dev'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {providerId: '@acme/widgets'};\n",
+    );
+    process.chdir(tmpDir);
+
+    const {integrations} = await loadProjectContext(tmpDir, ['@acme/widgets']);
+    expect(
+      integrations.map(integration => [
+        integration.name,
+        integration.__providerConflict?.claimedBy ?? null,
+      ]),
+    ).toEqual([['@acme/widgets', '@acme/renamed']]);
+    expect(
+      await selectIntegrationCodemodsFor(integrations, '0.1.0', '0.3.0'),
+    ).toEqual([]);
+  });
+});

package/api/upgrade/upgrade.doc.mjs

@@ -16,8 +16,9 @@ export const doc = {
   description:
     'Migrates project source from a previous Astryx version to the currently ' +
     'installed one by running the registered codemods, and compares the fully ' +
-    'rendered managed agent-docs block on every path, including same-Core ' +
-    'integration guidance changes. Dry-run previews without writing; `apply` ' +
+    'rendered managed agent-docs block on every migration path, including ' +
+    'same-Core integration guidance changes; list and registry-only modes do not ' +
+    'run migration reconciliation. Dry-run previews without writing; `apply` ' +
     'writes the prepared block only after selected codemods and hooks succeed. ' +
     'Core codemods run before ' +
     'the config is loaded so a config codemod can repair an otherwise-invalid ' +
@@ -68,7 +69,7 @@ export const doc = {
       name: 'options.integration',
       type: 'string[]',
       description:
-        'Explicit integration package names / file paths to process.',
+        'Explicit integration specifiers to process. Resolved beneath node_modules; absolute paths and `.` or `..` segments are rejected.',
     },
     {
       name: 'options.path',

package/api/upgrade/upgrade.type.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json upgrade --list
+ * astryx --json upgrade --list
  */
 export type UpgradeListResponse = {
     type: "upgrade.list";
@@ -121,14 +121,14 @@ export type RegistryCompositionSummary = {
     items: RegistryCompositionItemSummary[];
 };
 /**
- * xds --json upgrade --registry [--apply]
+ * astryx --json upgrade --registry [--apply]
  */
 export type UpgradeRegistryResponse = {
     type: "upgrade.registry";
     data: RegistryCompositionSummary;
 };
 /**
- * xds --json upgrade [--apply]
+ * astryx --json upgrade [--apply]
  */
 export type UpgradeRunResponse = {
     type: "upgrade.run";
@@ -150,7 +150,7 @@ export type UpgradeRunResponse = {
     };
 };
 /**
- * xds --json upgrade — short-circuit status results.
+ * astryx --json upgrade — short-circuit status results.
  *
  * - `up_to_date`: `--from` is >= installed target and `--force` was not passed.
  * - `no_codemods`: no codemods (core or integration) apply to the range.
@@ -211,7 +211,7 @@ export type UpgradeOptions = {
      */
     skipCodemod?: string[] | undefined;
     /**
-     * Explicit integration package names / file paths.
+     * Explicit integration specifiers resolved beneath node_modules; absolute paths and `.` or `..` segments are rejected.
      */
     integration?: string[] | undefined;
     /**