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

package/api/template/template.mjs

@@ -24,6 +24,7 @@ import {
 } from '../../foundation/discovery/template-adapter.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
+import {orderByAffinity} from '../../foundation/text/suggest-order.mjs';
 import {templateList} from './list/list.mjs';
 import {templateShow} from './show/show.mjs';
 import {templateSkeleton} from './skeleton/skeleton.mjs';
@@ -188,7 +189,10 @@ export async function template(name, options = {}) {
   if (name && candidates.length === 0) {
     throw new AstryxError(
       `Unknown template "${name}"`,
-      templates.map(t => ({name: t.dirName, reason: `${t.type} template`})),
+      orderByAffinity(name, templates, t => [t.dirName, t.name]).map(t => ({
+        name: t.dirName,
+        reason: `${t.type} template`,
+      })),
       ERROR_CODES.ERR_UNKNOWN_TEMPLATE,
     );
   }

package/api/theme/build/build.packed-old-core.test.mjs

@@ -51,6 +51,7 @@ const PACKED_DIRS = ['clients', 'api', 'assets', 'authoring', 'foundation'];
 const RUNTIME_DEPS = [
   '@babel/parser',
   'commander',
+  'ignore',
   'jiti',
   'jscodeshift',
   'zod',

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}
  */
@@ -84,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.
@@ -288,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,6 +30,8 @@ import {
 } from '../../assets/codemods/integration-discovery.mjs';
 import {runIntegrationCodemods} from '../../assets/codemods/integration-runner.mjs';
 import {
+  AgentDocsHomeError,
+  assertAgentDocsTarget,
   installAgentDocs,
   inspectAgentDocs,
   renderAgentDocsBlock,
@@ -42,7 +44,11 @@ import {
   quoteCommandArgument,
 } from '../../foundation/env/package-manager.mjs';
 import {isValidSemver, semverGt} from '../../foundation/env/semver.mjs';
-import {CLI_ROOT} from '../../foundation/fs/paths.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';
@@ -82,26 +88,125 @@ 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;
   }
-  return null;
 }
 
 /**
@@ -282,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({
@@ -299,6 +435,7 @@ export async function prepareAgentDocsRefresh({
   installedVersion,
   apply,
   fresh = false,
+  origin,
 }) {
   const initial = inspectAgentDocs(cwd, installedVersion);
   /** @type {import('./upgrade.type.mjs').AgentDocsSummary} */
@@ -312,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;
@@ -329,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) {
@@ -346,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};
 }
 
 /**
@@ -355,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;
 
@@ -363,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;
@@ -371,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;
 }

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;

package/api/upgrade/registry/registry.mjs

@@ -414,8 +414,9 @@ async function fetchLatestReceipt(
 /**
  * @param {string} receiptPath
  * @param {string} root
+ * @param {string} [display] the folder reported paths are relative to
  */
-function loadInstalledReceipt(receiptPath, root) {
+function loadInstalledReceipt(receiptPath, root, display = root) {
   let receipt;
   let receiptText;
   try {
@@ -436,7 +437,7 @@ function loadInstalledReceipt(receiptPath, root) {
     }
   } catch (error) {
     throw new Error(
-      `Invalid receipt ${relativePath(receiptPath, root)}: ${error instanceof Error ? error.message : String(error)}`,
+      `Invalid receipt ${relativePath(receiptPath, display)}: ${error instanceof Error ? error.message : String(error)}`,
       {cause: error},
     );
   }
@@ -445,7 +446,7 @@ function loadInstalledReceipt(receiptPath, root) {
     const candidates = receiptFileCandidates(receipt, file).map(candidate => {
       if (registryContentHash(candidate.content) !== candidate.sha256) {
         throw new Error(
-          `Invalid receipt ${relativePath(receiptPath, root)}: stored hash does not match ${file.registryPath} (${candidate.format})`,
+          `Invalid receipt ${relativePath(receiptPath, display)}: stored hash does not match ${file.registryPath} (${candidate.format})`,
         );
       }
       let sourcePath;
@@ -458,7 +459,7 @@ function loadInstalledReceipt(receiptPath, root) {
       } catch (error) {
         if (error instanceof PathSafetyError) {
           throw new Error(
-            `Invalid receipt ${relativePath(receiptPath, root)}: ${error.message}`,
+            `Invalid receipt ${relativePath(receiptPath, display)}: ${error.message}`,
             {cause: error},
           );
         }
@@ -471,7 +472,7 @@ function loadInstalledReceipt(receiptPath, root) {
     );
     if (existing.length > 1) {
       throw new Error(
-        `Invalid receipt ${relativePath(receiptPath, root)}: multiple install variants exist for ${file.registryPath}`,
+        `Invalid receipt ${relativePath(receiptPath, display)}: multiple install variants exist for ${file.registryPath}`,
       );
     }
     return existing[0] ?? candidates[0];
@@ -483,12 +484,14 @@ function loadInstalledReceipt(receiptPath, root) {
 /**
  * @param {string} receiptPath
  * @param {string} root
- * @param {{fetchImpl: typeof fetch, registryOrigin: string, expectedVersion?: string}} options
+ * @param {{fetchImpl: typeof fetch, registryOrigin: string, expectedVersion?: string, display?: string}} options
+ *   `display` is the folder reported paths are relative to, `root` by default
  */
 async function planReceipt(receiptPath, root, options) {
+  const display = options.display ?? root;
   let installed;
   try {
-    installed = loadInstalledReceipt(receiptPath, root);
+    installed = loadInstalledReceipt(receiptPath, root, display);
   } catch (error) {
     return {
       receiptPath,
@@ -584,7 +587,7 @@ async function planReceipt(receiptPath, root, options) {
           oldReceiptText,
         };
       }
-      const displayPath = relativePath(sourcePath, root);
+      const displayPath = relativePath(sourcePath, display);
       try {
         if (!fs.existsSync(sourcePath)) {
           plannedFiles.push({
@@ -636,7 +639,7 @@ async function planReceipt(receiptPath, root, options) {
     const newFile = newReceiptFile
       ? receiptFileForFormat(newReceipt, newReceiptFile, oldFile.format)
       : null;
-    const displayPath = relativePath(oldFile.sourcePath, root);
+    const displayPath = relativePath(oldFile.sourcePath, display);
     if (!newReceiptFile) {
       plannedFiles.push({
         id: oldFile.id,
@@ -856,8 +859,12 @@ function publicAction(action, apply) {
   return action;
 }
 
-/** @param {any} item @param {string} root @param {boolean} apply */
-function publicItem(item, root, apply) {
+/**
+ * @param {any} item
+ * @param {string} display the folder reported paths are relative to
+ * @param {boolean} apply
+ */
+function publicItem(item, display, apply) {
   return {
     item: item.item,
     path: item.itemPath,
@@ -870,7 +877,7 @@ function publicItem(item, root, apply) {
         action: publicAction(file.action, apply),
         ...(file.message ? {message: file.message} : {}),
         ...(file.action === 'conflict' && file.conflictPath
-          ? {conflictFile: relativePath(file.conflictPath, root)}
+          ? {conflictFile: relativePath(file.conflictPath, display)}
           : {}),
       }),
     ),
@@ -968,13 +975,17 @@ function applyPlan(plan) {
 }
 
 /**
+ * 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 async function reconcileRegistryCompositions(
   options = {},
   {
     cwd = process.cwd(),
+    origin,
     fetchImpl = globalThis.fetch,
     registryOrigin = PUBLIC_SHADCN_REGISTRY_ORIGIN,
     expectedVersion,
@@ -998,6 +1009,7 @@ export async function reconcileRegistryCompositions(
     throw error;
   }
 
+  const display = origin ?? root;
   const apply = options.apply ?? false;
   const receipts = discoverRegistryReceipts(root);
   const summary = emptySummary(apply);
@@ -1019,6 +1031,7 @@ export async function reconcileRegistryCompositions(
         fetchImpl,
         registryOrigin,
         expectedVersion,
+        display,
       }),
   );
 
@@ -1031,7 +1044,7 @@ export async function reconcileRegistryCompositions(
         summary.invalid++;
       }
     }
-    recordItem(summary, publicItem(plan, root, apply), plan.action, apply);
+    recordItem(summary, publicItem(plan, display, apply), plan.action, apply);
     if (!apply) continue;
 
     try {
@@ -1119,13 +1132,17 @@ export function logRegistryCompositionSummary(summary) {
 }
 
 /**
- * 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 async function registryUpgrade(options = {}, ctx = {}) {
   const cwd = ctx.cwd ?? process.cwd();
+  if (ctx.origin != null) {
+    logger.log(`Project root: ${path.relative(ctx.origin, cwd) || '.'}`);
+  }
   const installed = detectInstalledTargetVersion(cwd);
   const expectedVersion =
     ctx.expectedVersion ??