@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/api/upgrade/_adapter.d.mts

@@ -23,7 +23,55 @@
  * @property {boolean} [registry]
  */
 /**
- * Detect the installed target version from node_modules.
+ * Where an upgrade runs: the root of the Astryx project `cwd` belongs to, the
+ * nearest folder at or above it whose package.json declares an Astryx
+ * package or that an Astryx workspace lists as a member, so a run from any
+ * folder inside a project upgrades that project exactly as a run from its
+ * root does. Its source, config, agent docs and
+ * protection declarations all live there. The search stops at a repository
+ * root and ends at the home folder without counting it (see
+ * `findAstryxProject`). A `path` the caller names, in any spelling (`./src`,
+ * `src`, `src/`), is read from `cwd`, where they typed it. With no `path`,
+ * the upgrade scans `./src` at the project root. With no Astryx project, the
+ * upgrade runs in `cwd` as released versions did.
+ * @param {UpgradeOptions} options
+ * @param {string} cwd
+ * @returns {{options: UpgradeOptions, cwd: string, origin?: string}} `origin`
+ *   is the folder the command ran in, when the project root is above it
+ */
+export function scopeToProject(options: UpgradeOptions, cwd: string): {
+    options: UpgradeOptions;
+    cwd: string;
+    origin?: string;
+};
+/**
+ * The result of an upgrade that ran at a project root above the folder the
+ * command ran in, with its file paths made relative to that folder, so each
+ * resolves from where the command ran: `modifiedFiles`, `agentDocs.files`, and
+ * the `file` of each `protectedFiles`, `declinedCandidates` and `errors`
+ * entry. The registry step names copied-composition paths from that folder
+ * itself (see `reconcileRegistryCompositions`), so they pass through. A
+ * result of a run at the project root is returned as it is.
+ * @template {{type: string, data: object}} T
+ * @param {T} result
+ * @param {{cwd: string, origin?: string}} scope from `scopeToProject`
+ * @returns {T}
+ */
+export function relativeToOrigin<T extends {
+    type: string;
+    data: object;
+}>(result: T, { cwd: root, origin }: {
+    cwd: string;
+    origin?: string;
+}): T;
+/**
+ * Detect the installed target version: the Core the Astryx project of `cwd`
+ * installed, in its own node_modules or, for a member its workspace lists, in
+ * a folder up to the workspace root. The nearest folder wins, the current
+ * name before the legacy one, then Yarn Plug'n'Play. A Core above a project
+ * no workspace lists does not count, so a nested project that has not
+ * installed its own reports nothing installed. With no Astryx project, only
+ * the node_modules of `cwd` itself is read, as released versions did.
  * @param {string} cwd
  * @returns {{version: string, packageName: string}|null}
  */
@@ -31,6 +79,43 @@ export function detectInstalledTargetVersion(cwd: string): {
     version: string;
     packageName: string;
 } | null;
+/**
+ * Whether the installed Core is newer than this CLI, so part of the requested
+ * range has no codemods here.
+ *
+ * Core codemods ship inside the CLI. A CLI older than the installed
+ * `@astryxdesign/core` has none for the releases after its own version, so it
+ * can find no codemods, or stop partway, while the code still needs those
+ * releases' migrations. The returned command repeats this upgrade with the CLI
+ * release that matches the installed Core.
+ *
+ * Where an upgrade runs decides what it finds: the installed Core is read
+ * from that folder, and `--path` must stay inside it. So the command first
+ * changes to `cwd`, the folder this run used, then names `sourcePath`, the
+ * directory this run scanned, as an absolute `--path`. Both are named by their
+ * physical paths, with every symbolic link resolved: a shell's `cd` follows a
+ * link, but the CLI it starts reads its folder with every link resolved and
+ * checks `--path` against that. Pasted from any folder, the command finds the
+ * same Core and scans the same directory, even after a package runner moved
+ * this run (Yarn 1 runs `yarn astryx` at the project root). It is written for
+ * a POSIX shell, or for PowerShell on Windows (cmd.exe is not a target), with
+ * every argument quoted for that shell.
+ *
+ * Returns null when the CLI covers the whole range (`to` is not newer than
+ * both the CLI and `from`), when the CLI's own version cannot be read, or when
+ * the target is legacy `@xds/core`, which no CLI release shares a version with.
+ *
+ * @param {{from: string, to: string, packageName: string, options: UpgradeOptions, cwd: string, sourcePath: string}} input
+ * @returns {import('./upgrade.type.mjs').CliBehindCore | null}
+ */
+export function detectCliBehindCore({ from, to, packageName, options, cwd, sourcePath, }: {
+    from: string;
+    to: string;
+    packageName: string;
+    options: UpgradeOptions;
+    cwd: string;
+    sourcePath: string;
+}): import("./upgrade.type.mjs").CliBehindCore | null;
 /**
  * @param {(string | null | undefined | false)[] | undefined} files
  * @returns {string[]}
@@ -47,25 +132,20 @@ export function runPostCodemodHooks(hooks: import("../../authoring/config/type")
     files: string[];
     apply: boolean;
 }): Promise<void>;
-/**
- * @typedef {object} AgentDocsRefreshPlan
- * @property {string} cwd
- * @property {string|null} renderedBlock
- * @property {import('./upgrade.type.mjs').AgentDocsSummary} summary
- */
 /**
  * Compute the expected managed block and report staleness without writing.
  * Apply-mode callers commit the prepared bytes only after codemods and hooks
  * succeed.
  *
- * @param {{cwd: string, installedVersion: string, apply: boolean, fresh?: boolean}} ctx
+ * @param {{cwd: string, installedVersion: string, apply: boolean, fresh?: boolean, origin?: string}} ctx
  * @returns {Promise<AgentDocsRefreshPlan>}
  */
-export function prepareAgentDocsRefresh({ cwd, installedVersion, apply, fresh, }: {
+export function prepareAgentDocsRefresh({ cwd, installedVersion, apply, fresh, origin, }: {
     cwd: string;
     installedVersion: string;
     apply: boolean;
     fresh?: boolean;
+    origin?: string;
 }): Promise<AgentDocsRefreshPlan>;
 /**
  * Commit a prepared agent-doc refresh.
@@ -104,9 +184,9 @@ 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>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean}} 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, coversTarget?: boolean}} options
  */
-export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply, path: srcPath, codemod, skipCodemods, root, protection, silent }: {
+export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply, path: srcPath, codemod, skipCodemods, root, protection, silent, coversTarget, }: {
     apply: boolean;
     path: string;
     codemod?: string;
@@ -117,6 +197,7 @@ export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply
         classify: (file: string) => import("../../foundation/fs/file-protection.mjs").FileProtection[];
     };
     silent?: boolean;
+    coversTarget?: boolean;
 }): Promise<{
     totalFilesChanged: number;
     totalTransformsApplied: number;
@@ -250,6 +331,11 @@ export type UpgradeOptions = {
 };
 export type AgentDocsRefreshPlan = {
     cwd: string;
+    /**
+     * the folder the command ran in, when the upgrade
+     * runs at a project root above it
+     */
+    origin?: string | undefined;
     renderedBlock: string | null;
     summary: import("./upgrade.type.mjs").AgentDocsSummary;
 };

package/api/upgrade/_adapter.mjs

@@ -30,11 +30,25 @@ import {
 } from '../../assets/codemods/integration-discovery.mjs';
 import {runIntegrationCodemods} from '../../assets/codemods/integration-runner.mjs';
 import {
+  AgentDocsHomeError,
+  assertAgentDocsTarget,
   installAgentDocs,
   inspectAgentDocs,
   renderAgentDocsBlock,
 } from '../../foundation/agent-docs/agent-docs.mjs';
-import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
+import {
+  CLI_PACKAGE,
+  commandInFolder,
+  formatCliCommand,
+  getDlxPrefix,
+  quoteCommandArgument,
+} from '../../foundation/env/package-manager.mjs';
+import {isValidSemver, semverGt} from '../../foundation/env/semver.mjs';
+import {
+  CLI_ROOT,
+  findAstryxProject,
+  findProjectPackageOf,
+} from '../../foundation/fs/paths.mjs';
 import {Project, providerLedgerOf} from '../../foundation/config/project.mjs';
 import {loadIntegrations} from '../../foundation/integrations/integrations.mjs';
 import {resolveProviders} from '../../foundation/integrations/provider-resolution.mjs';
@@ -74,26 +88,218 @@ const execFileAsync = promisify(execFile);
  */
 
 /**
- * Detect the installed target version from node_modules.
+ * Where an upgrade runs: the root of the Astryx project `cwd` belongs to, the
+ * nearest folder at or above it whose package.json declares an Astryx
+ * package or that an Astryx workspace lists as a member, so a run from any
+ * folder inside a project upgrades that project exactly as a run from its
+ * root does. Its source, config, agent docs and
+ * protection declarations all live there. The search stops at a repository
+ * root and ends at the home folder without counting it (see
+ * `findAstryxProject`). A `path` the caller names, in any spelling (`./src`,
+ * `src`, `src/`), is read from `cwd`, where they typed it. With no `path`,
+ * the upgrade scans `./src` at the project root. With no Astryx project, the
+ * upgrade runs in `cwd` as released versions did.
+ * @param {UpgradeOptions} options
+ * @param {string} cwd
+ * @returns {{options: UpgradeOptions, cwd: string, origin?: string}} `origin`
+ *   is the folder the command ran in, when the project root is above it
+ */
+export function scopeToProject(options, cwd) {
+  const here = path.resolve(cwd);
+  const root = findAstryxProject(here) ?? here;
+  if (root === here) return {options, cwd};
+  const namedPath =
+    options.path == null ? {} : {path: path.resolve(here, options.path)};
+  return {options: {...options, ...namedPath}, cwd: root, origin: here};
+}
+
+/**
+ * The result of an upgrade that ran at a project root above the folder the
+ * command ran in, with its file paths made relative to that folder, so each
+ * resolves from where the command ran: `modifiedFiles`, `agentDocs.files`, and
+ * the `file` of each `protectedFiles`, `declinedCandidates` and `errors`
+ * entry. The registry step names copied-composition paths from that folder
+ * itself (see `reconcileRegistryCompositions`), so they pass through. A
+ * result of a run at the project root is returned as it is.
+ * @template {{type: string, data: object}} T
+ * @param {T} result
+ * @param {{cwd: string, origin?: string}} scope from `scopeToProject`
+ * @returns {T}
+ */
+export function relativeToOrigin(result, {cwd: root, origin}) {
+  if (origin == null) return result;
+  /** @param {string} file */
+  const rebase = file =>
+    path.relative(origin, path.resolve(root, file)).split(path.sep).join('/') ||
+    '.';
+  /** @type {Record<string, any>} */
+  const data = {...result.data};
+  if (data.agentDocs) {
+    data.agentDocs = {
+      ...data.agentDocs,
+      files: data.agentDocs.files.map(rebase),
+    };
+  }
+  if (data.modifiedFiles) data.modifiedFiles = data.modifiedFiles.map(rebase);
+  for (const key of ['protectedFiles', 'declinedCandidates', 'errors']) {
+    if (data[key]) {
+      data[key] = data[key].map(
+        (/** @type {{file: string, declarations?: string[]}} */ entry) => ({
+          ...entry,
+          file: rebase(entry.file),
+          ...(Array.isArray(entry.declarations)
+            ? {declarations: entry.declarations.map(rebaseDeclaration(rebase))}
+            : {}),
+        }),
+      );
+    }
+  }
+  return /** @type {T} */ ({...result, data});
+}
+
+/**
+ * The project-relative file a protection declaration names, and the text
+ * around it: the ignore or attributes file that protects a file (and its
+ * line), or the symbolic link on its path. Other declarations name no file.
+ */
+const DECLARATION_PATHS = [
+  /^(excluded by )(.+?)(:\d+)?$/u,
+  /^(linguist-(?:generated|vendored) in )(.+?)(:\d+)$/u,
+  /^(symbolic link at )(.+)()$/u,
+];
+
+/**
+ * A protection declaration with the file it names rebased, as `rebase` does
+ * for result paths.
+ * @param {(file: string) => string} rebase
+ * @returns {(declaration: string) => string}
+ */
+function rebaseDeclaration(rebase) {
+  return declaration => {
+    for (const pattern of DECLARATION_PATHS) {
+      const match = pattern.exec(declaration);
+      if (match) return `${match[1]}${rebase(match[2])}${match[3] ?? ''}`;
+    }
+    return declaration;
+  };
+}
+
+/**
+ * Detect the installed target version: the Core the Astryx project of `cwd`
+ * installed, in its own node_modules or, for a member its workspace lists, in
+ * a folder up to the workspace root. The nearest folder wins, the current
+ * name before the legacy one, then Yarn Plug'n'Play. A Core above a project
+ * no workspace lists does not count, so a nested project that has not
+ * installed its own reports nothing installed. With no Astryx project, only
+ * the node_modules of `cwd` itself is read, as released versions did.
  * @param {string} cwd
  * @returns {{version: string, packageName: string}|null}
  */
 export function detectInstalledTargetVersion(cwd) {
-  for (const packageName of ['@astryxdesign/core', '@xds/core']) {
-    const pkgPath = path.resolve(
-      cwd,
-      'node_modules',
-      ...packageName.split('/'),
-      'package.json',
+  const found = findProjectPackageOf(cwd, ['@astryxdesign/core', '@xds/core']);
+  if (!found) return null;
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(found.packageDir, 'package.json'), 'utf-8'),
     );
-    try {
-      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-      if (pkg.version) return {version: pkg.version, packageName};
-    } catch {
-      // Missing/unreadable — try the next supported package name.
-    }
+    return pkg.version ? {version: pkg.version, packageName: found.name} : null;
+  } catch {
+    // Unreadable package.json: no version to target.
+    return null;
+  }
+}
+
+/**
+ * The running CLI's own version, read from its package.json.
+ * @returns {string | null} null when it cannot be read or is not semver
+ */
+function readRunningCliVersion() {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(CLI_ROOT, 'package.json'), 'utf-8'),
+    );
+    return isValidSemver(pkg.version) ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether the installed Core is newer than this CLI, so part of the requested
+ * range has no codemods here.
+ *
+ * Core codemods ship inside the CLI. A CLI older than the installed
+ * `@astryxdesign/core` has none for the releases after its own version, so it
+ * can find no codemods, or stop partway, while the code still needs those
+ * releases' migrations. The returned command repeats this upgrade with the CLI
+ * release that matches the installed Core.
+ *
+ * Where an upgrade runs decides what it finds: the installed Core is read
+ * from that folder, and `--path` must stay inside it. So the command first
+ * changes to `cwd`, the folder this run used, then names `sourcePath`, the
+ * directory this run scanned, as an absolute `--path`. Both are named by their
+ * physical paths, with every symbolic link resolved: a shell's `cd` follows a
+ * link, but the CLI it starts reads its folder with every link resolved and
+ * checks `--path` against that. Pasted from any folder, the command finds the
+ * same Core and scans the same directory, even after a package runner moved
+ * this run (Yarn 1 runs `yarn astryx` at the project root). It is written for
+ * a POSIX shell, or for PowerShell on Windows (cmd.exe is not a target), with
+ * every argument quoted for that shell.
+ *
+ * Returns null when the CLI covers the whole range (`to` is not newer than
+ * both the CLI and `from`), when the CLI's own version cannot be read, or when
+ * the target is legacy `@xds/core`, which no CLI release shares a version with.
+ *
+ * @param {{from: string, to: string, packageName: string, options: UpgradeOptions, cwd: string, sourcePath: string}} input
+ * @returns {import('./upgrade.type.mjs').CliBehindCore | null}
+ */
+export function detectCliBehindCore({
+  from,
+  to,
+  packageName,
+  options,
+  cwd,
+  sourcePath,
+}) {
+  if (packageName !== '@astryxdesign/core') return null;
+  const cliVersion = readRunningCliVersion();
+  if (!cliVersion || !semverGt(to, cliVersion) || !semverGt(to, from)) {
+    return null;
+  }
+  const runFolder = path.resolve(cwd);
+  const folder = physicalFolder(runFolder);
+  const scanned = path.join(folder, path.relative(runFolder, sourcePath));
+  const args = ['upgrade', '--from', from, '--path', scanned];
+  if (options.codemod) args.push('--codemod', options.codemod);
+  for (const name of options.skipCodemod ?? []) {
+    args.push('--skip-codemod', name);
+  }
+  for (const spec of options.integration ?? []) {
+    args.push('--integration', spec);
+  }
+  if (options.force) args.push('--force');
+  if (options.installDeps) args.push('--install-deps');
+  if (options.apply) args.push('--apply');
+  const upgrade = [
+    getDlxPrefix(cwd),
+    ...[`${CLI_PACKAGE}@${to}`, ...args].map(arg => quoteCommandArgument(arg)),
+  ].join(' ');
+  return {cliVersion, command: commandInFolder(folder, upgrade)};
+}
+
+/**
+ * A folder as the operating system reports it to a process that runs there,
+ * with every symbolic link on the way resolved. Falls back to the path as
+ * given when it cannot be resolved.
+ * @param {string} dir an absolute folder
+ * @returns {string}
+ */
+function physicalFolder(dir) {
+  try {
+    return fs.realpathSync(dir);
+  } catch {
+    return dir;
   }
-  return null;
 }
 
 /**
@@ -181,16 +387,47 @@ export async function runPostCodemodHooks(hooks, context) {
 /**
  * @typedef {object} AgentDocsRefreshPlan
  * @property {string} cwd
+ * @property {string} [origin] the folder the command ran in, when the upgrade
+ *   runs at a project root above it
  * @property {string|null} renderedBlock
  * @property {import('./upgrade.type.mjs').AgentDocsSummary} summary
  */
 
+/**
+ * The advice to run `init`, phrased for where the command ran: when the
+ * upgrade runs at a project root above that folder, it names the root, so the
+ * agent docs are installed beside the project's package.json.
+ * @param {string} cwd the folder the upgrade runs at
+ * @param {string} [origin] the folder the command ran in
+ * @returns {string}
+ */
+function initAdvice(cwd, origin) {
+  const command = `\`${formatCliCommand('astryx init --features agents')}\``;
+  if (origin == null) return command;
+  return `${command} in ${path.relative(origin, cwd) || '.'} (the project root)`;
+}
+
+/**
+ * Why upgrade leaves the agent docs of a project at the home folder or the
+ * top of a settings folder, and what to do instead. init refuses the same
+ * folder, so the line never points at it.
+ * @param {AgentDocsHomeError} err
+ * @param {'stale' | 'missing'} [state] whether a block is there to refresh
+ * @returns {string}
+ */
+function homeRefusalLine(err, state = 'stale') {
+  const where = `${err.dir} is the home folder or a settings folder in it, which every project's agents read.`;
+  return state === 'missing'
+    ? `Agent docs not installed: ${where} To have agent docs, move the project into a folder of its own, or add the Astryx block to its agent file by hand.`
+    : `Agent docs not refreshed: ${where} To keep agent docs, move the project into a folder of its own; otherwise update or remove the Astryx block there by hand.`;
+}
+
 /**
  * Compute the expected managed block and report staleness without writing.
  * Apply-mode callers commit the prepared bytes only after codemods and hooks
  * succeed.
  *
- * @param {{cwd: string, installedVersion: string, apply: boolean, fresh?: boolean}} ctx
+ * @param {{cwd: string, installedVersion: string, apply: boolean, fresh?: boolean, origin?: string}} ctx
  * @returns {Promise<AgentDocsRefreshPlan>}
  */
 export async function prepareAgentDocsRefresh({
@@ -198,6 +435,7 @@ export async function prepareAgentDocsRefresh({
   installedVersion,
   apply,
   fresh = false,
+  origin,
 }) {
   const initial = inspectAgentDocs(cwd, installedVersion);
   /** @type {import('./upgrade.type.mjs').AgentDocsSummary} */
@@ -211,11 +449,21 @@ export async function prepareAgentDocsRefresh({
   };
 
   if (initial.status === 'missing') {
+    // init writes nothing in a project at the home folder or the top of a
+    // settings folder, so it is not the remedy there (INV31).
+    try {
+      assertAgentDocsTarget(cwd);
+    } catch (err) {
+      if (!(err instanceof AgentDocsHomeError)) throw err;
+      summary.action = 'error';
+      logger.warn(homeRefusalLine(err, 'missing'));
+      return {cwd, origin, renderedBlock: null, summary};
+    }
     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 ${initAdvice(cwd, origin)} to install it.`,
     );
-    return {cwd, renderedBlock: null, summary};
+    return {cwd, origin, renderedBlock: null, summary};
   }
 
   let renderedBlock;
@@ -228,16 +476,30 @@ export async function prepareAgentDocsRefresh({
     summary.action = 'error';
     summary.files = initial.files.map(file => file.path);
     logger.warn(
-      `Could not render the expected agent docs. Run \`${formatCliCommand('astryx init --features agents')}\` to update them manually.`,
+      `Could not render the expected agent docs. Run ${initAdvice(cwd, origin)} to update them manually.`,
     );
-    return {cwd, renderedBlock: null, summary};
+    return {cwd, origin, renderedBlock: null, summary};
   }
 
   const inspection = inspectAgentDocs(cwd, installedVersion, renderedBlock);
   summary.status = inspection.status;
   summary.fromVersions = inspection.blockVersions;
   summary.files = inspection.staleFiles;
-  if (inspection.status === 'current') return {cwd, renderedBlock, summary};
+  if (inspection.status === 'current') {
+    return {cwd, origin, renderedBlock, summary};
+  }
+
+  // A project at the home folder or the top of a settings folder is never
+  // refreshed (INV31): the dry run says so, as --apply does, rather than
+  // offering a refresh that would be refused.
+  try {
+    assertAgentDocsTarget(cwd);
+  } catch (err) {
+    if (!(err instanceof AgentDocsHomeError)) throw err;
+    summary.action = 'error';
+    logger.warn(homeRefusalLine(err));
+    return {cwd, origin, renderedBlock: null, summary};
+  }
 
   summary.action = 'would-refresh';
   if (!apply) {
@@ -245,7 +507,7 @@ export async function prepareAgentDocsRefresh({
       `Agent docs differ from the installed Astryx and integration configuration. Re-run with --apply to refresh (${summary.files.join(', ')}).`,
     );
   }
-  return {cwd, renderedBlock, summary};
+  return {cwd, origin, renderedBlock, summary};
 }
 
 /**
@@ -254,7 +516,7 @@ export async function prepareAgentDocsRefresh({
  * @returns {import('./upgrade.type.mjs').AgentDocsSummary}
  */
 export function applyAgentDocsRefresh(plan) {
-  const {cwd, renderedBlock, summary} = plan;
+  const {cwd, origin, renderedBlock, summary} = plan;
   if (summary.action !== 'would-refresh' || renderedBlock == null)
     return summary;
 
@@ -262,6 +524,9 @@ export function applyAgentDocsRefresh(plan) {
     const written = installAgentDocs(cwd, {
       onlyReplace: true,
       renderedBlock,
+      // A GEMINI.md that resolves outside the project is left as it is.
+      onSkipped: (file, reason) =>
+        logger.warn(`Note: ${file} left as it is (${reason}).`),
     });
     summary.refreshed = written.length > 0;
     summary.files = written;
@@ -270,15 +535,21 @@ export function applyAgentDocsRefresh(plan) {
       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.`,
+        `Agent docs look stale but couldn't be refreshed. Run ${initAdvice(cwd, origin)} to reinstall the block.`,
       );
     }
-  } catch {
+  } catch (err) {
     summary.action = 'error';
     summary.refreshed = false;
-    logger.warn(
-      `Could not refresh agent docs. Run \`${formatCliCommand('astryx init --features agents')}\` to update them manually.`,
-    );
+    if (err instanceof AgentDocsHomeError) {
+      // init refuses this folder too, so pointing at it would loop: say why,
+      // and what to do instead.
+      logger.warn(homeRefusalLine(err));
+    } else {
+      logger.warn(
+        `Could not refresh agent docs. Run ${initAdvice(cwd, origin)} to update them manually.`,
+      );
+    }
   }
   return summary;
 }
@@ -332,11 +603,20 @@ 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>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean}} 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, coversTarget?: boolean}} options
  */
 export async function runCoreCodemods(
   versionManifests,
-  {apply, path: srcPath, codemod, skipCodemods, root, protection, silent},
+  {
+    apply,
+    path: srcPath,
+    codemod,
+    skipCodemods,
+    root,
+    protection,
+    silent,
+    coversTarget,
+  },
 ) {
   return runCodemods(versionManifests, {
     apply,
@@ -346,6 +626,7 @@ export async function runCoreCodemods(
     silent: silent ?? logger.silent,
     root,
     protection,
+    coversTarget,
   });
 }
 
@@ -367,7 +648,7 @@ export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
   // The CLI debug preflight may already have imported this config before core
   // CONFIG codemods run. Upgrade needs the bytes now on disk, not that module
   // cache entry; ordinary Project discovery remains cached by default.
-  const project = await Project.load(cwd, {fresh: true});
+  const project = await Project.load(cwd, {fresh: true, core: 'project'});
   const postCodemodHooks = project.config.hooks?.postCodemod ?? [];
   const configuredSpecs = new Set(project.integrations ?? []);
   // Configured packages come from Project, which has already resolved provider
@@ -411,7 +692,9 @@ export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
   const extras =
     extraSpecs.length === 0
       ? []
-      : await loadIntegrations(extraSpecs, {resolveProviders: false});
+      : // Resolved from the project, as --integration names a package it
+        // installed, not from whichever folder the process started in.
+        await loadIntegrations(extraSpecs, {cwd, resolveProviders: false});
   const {integrations, ledger} = resolveProviders(
     [
       ...candidates,

package/api/upgrade/registry/registry.d.mts

@@ -4,14 +4,18 @@
 /** @param {string} root */
 export function discoverRegistryReceipts(root: string): string[];
 /**
+ * Reported paths are relative to the scanned source folder, or, when `origin`
+ * names the folder the command ran in below the project root `cwd`, to that
+ * folder, so they resolve from where the command ran.
  * @param {{apply?: boolean, path?: string}} options
- * @param {{cwd?: string, fetchImpl?: typeof fetch, registryOrigin?: string, expectedVersion?: string, requireExpectedVersion?: boolean}} [ctx]
+ * @param {{cwd?: string, origin?: string, fetchImpl?: typeof fetch, registryOrigin?: string, expectedVersion?: string, requireExpectedVersion?: boolean}} [ctx]
  */
 export function reconcileRegistryCompositions(options?: {
     apply?: boolean;
     path?: string;
-}, { cwd, fetchImpl, registryOrigin, expectedVersion, requireExpectedVersion, }?: {
+}, { cwd, origin, fetchImpl, registryOrigin, expectedVersion, requireExpectedVersion, }?: {
     cwd?: string;
+    origin?: string;
     fetchImpl?: typeof fetch;
     registryOrigin?: string;
     expectedVersion?: string;
@@ -23,9 +27,10 @@ export function reconcileRegistryCompositions(options?: {
 /** @param {import('../upgrade.type.mjs').RegistryCompositionSummary} summary */
 export function logRegistryCompositionSummary(summary: import("../upgrade.type.mjs").RegistryCompositionSummary): void;
 /**
- * Standalone `astryx upgrade --registry` leaf.
+ * Standalone `astryx upgrade --registry` leaf. `ctx.origin` is the folder the
+ * command ran in, when `ctx.cwd` is the project root above it.
  * @param {{apply?: boolean, path?: string}} options
- * @param {{cwd?: string, fetchImpl?: typeof fetch, registryOrigin?: string, expectedVersion?: string, requireExpectedVersion?: boolean}} [ctx]
+ * @param {{cwd?: string, origin?: string, fetchImpl?: typeof fetch, registryOrigin?: string, expectedVersion?: string, requireExpectedVersion?: boolean}} [ctx]
  * @returns {Promise<import('../upgrade.type.mjs').UpgradeRegistryResponse>}
  */
 export function registryUpgrade(options?: {
@@ -33,6 +38,7 @@ export function registryUpgrade(options?: {
     path?: string;
 }, ctx?: {
     cwd?: string;
+    origin?: string;
     fetchImpl?: typeof fetch;
     registryOrigin?: string;
     expectedVersion?: string;