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

package/api/doctor/doctor.test.mjs

@@ -21,6 +21,7 @@ import {docs} from '../docs/docs.mjs';
 import {auditCliSelfDocs} from '../../foundation/discovery/cli-self-docs.mjs';
 import {
   doctor,
+  checkCliCommand,
   checkAuthoringDocs,
   checkCliDocs,
   checkDocsTree,
@@ -30,7 +31,11 @@ import {
   checkIntegrationIssues,
   checkVersionAlignment,
   checkPackageManager,
+  checkComputerIntegrationsAvailable,
 } from './doctor.mjs';
+import {installCommandFor} from './_adapter.mjs';
+import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
+import {Project} from '../../foundation/config/project.mjs';
 
 const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
 const cwd = REPO;
@@ -86,6 +91,30 @@ describe('doctor leaf', () => {
   }, SLOW);
 });
 
+describe('doctor never reads the carried Core (spec AST-081 FR3)', () => {
+  it('loads the project to read only its installed Core, in a project with nothing installed', async () => {
+    const dir = mkProject({
+      'package.json': JSON.stringify({
+        name: 'fresh-clone',
+        dependencies: {'@astryxdesign/core': '^0.7.0'},
+      }),
+    });
+    const load = vi.spyOn(Project, 'load');
+    const coreDir = vi.spyOn(Project.prototype, 'coreDir');
+    try {
+      await doctor({cwd: dir});
+      // Doctor's own project reads only the installed Core, and no Core a
+      // project read during the run is the carried one.
+      expect(load.mock.calls.some(([, options]) => options?.core === 'project')).toBe(true);
+      expect(coreDir).toHaveBeenCalled();
+      for (const result of coreDir.mock.results) expect(result.value).toBeNull();
+    } finally {
+      load.mockRestore();
+      coreDir.mockRestore();
+    }
+  });
+});
+
 describe('integration issue check', () => {
   it('surfaces cross-package replacement warnings', () => {
     const check = checkIntegrationIssues({
@@ -110,7 +139,7 @@ describe('integration issue check', () => {
 describe('doctor leaf — degradation & error paths', () => {
   it('does not crash on multiple config files; reports a config FAIL', async () => {
     const dir = mkProject({
-      'package.json': '{"name":"x"}',
+      'package.json': '{"name":"x","dependencies":{"@astryxdesign/core":"*"}}',
       'astryx.config.mjs': 'export default {};',
       'astryx.config.js': 'export default {};',
     });
@@ -123,7 +152,7 @@ describe('doctor leaf — degradation & error paths', () => {
 
   it('reports a config FAIL (not a crash) when astryx.config.mjs throws on import', async () => {
     const dir = mkProject({
-      'package.json': '{"name":"x"}',
+      'package.json': '{"name":"x","dependencies":{"@astryxdesign/core":"*"}}',
       'astryx.config.mjs': 'throw new Error("boom");\nexport default {};',
     });
     const r = await doctor({cwd: dir});
@@ -134,7 +163,7 @@ describe('doctor leaf — degradation & error paths', () => {
 
   it('flags a non-object config default export as FAIL', async () => {
     const dir = mkProject({
-      'package.json': '{"name":"x"}',
+      'package.json': '{"name":"x","dependencies":{"@astryxdesign/core":"*"}}',
       'astryx.config.mjs': 'export default 42;',
     });
     const r = await doctor({cwd: dir});
@@ -190,6 +219,158 @@ describe('doctor — checkVersionAlignment', () => {
   });
 });
 
+describe("doctor — the project's own CLI and Core on different releases", () => {
+  const cli = JSON.parse(
+    fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8'),
+  ).version;
+  /** @param {string} core */
+  const at = core => {
+    // A project as spec:AST-040 FR9 defines it: its package.json declares
+    // an Astryx package.
+    const dir = mkProject({
+      'package.json': JSON.stringify({
+        name: 'app',
+        dependencies: {'@astryxdesign/core': core},
+      }),
+      'package-lock.json': '{}',
+      'node_modules/@astryxdesign/core/package.json': JSON.stringify({
+        name: '@astryxdesign/core',
+        version: core,
+      }),
+    });
+    return checkVersionAlignment({
+      cwd: dir,
+      coreDir: path.join(dir, 'node_modules/@astryxdesign/core'),
+      nodeVersion: '',
+      configPath: null,
+      configTheme: null,
+    });
+  };
+
+  it('warns on any difference, patch included, and names the align command', () => {
+    const older = at('0.0.1');
+    expect(older.status).toBe('warn');
+    expect(older.message).toContain(
+      `This project's CLI ${cli} answers it, but its Core is 0.0.1`,
+    );
+    expect(older.fix).toBe(
+      `To align them, run: npm install @astryxdesign/core@${cli}, then npx astryx upgrade --from 0.0.1 --apply.`,
+    );
+    const newer = at('99.0.0');
+    expect(newer.fix).toBe(
+      'To align them, run: npm install @astryxdesign/cli@99.0.0.',
+    );
+    expect(at(cli).status).toBe('pass');
+  });
+
+  it('in a project with no CLI of its own, warns that the started copy answered and names the command that adds the CLI at Core', () => {
+    const dir = mkProject({
+      'package.json': JSON.stringify({
+        name: 'app',
+        dependencies: {'@astryxdesign/core': '0.0.1'},
+      }),
+      'package-lock.json': '{}',
+      'node_modules/@astryxdesign/core/package.json': JSON.stringify({
+        name: '@astryxdesign/core',
+        version: '0.0.1',
+      }),
+    });
+    const c = checkVersionAlignment({
+      cwd: dir,
+      coreDir: path.join(dir, 'node_modules/@astryxdesign/core'),
+      nodeVersion: '',
+      configPath: null,
+      configTheme: null,
+      ownCli: false,
+    });
+    expect(c.status).toBe('warn');
+    expect(c.message).toBe(
+      `This project has no Astryx CLI installed; CLI ${cli}, the one you started, answered while its Core is 0.0.1.`,
+    );
+    expect(c.fix).toBe('To match, run: npm install @astryxdesign/cli@0.0.1.');
+  });
+});
+
+describe('the command that adds an integration installed for the computer', () => {
+  const app = () =>
+    mkProject({
+      'package.json': JSON.stringify({
+        name: 'app',
+        dependencies: {'@astryxdesign/core': '0.7.0'},
+      }),
+      'pnpm-lock.yaml': '',
+      'tools/codegen/package.json': JSON.stringify({name: 'codegen'}),
+    });
+
+  it('adds it in the project, with its package manager', () => {
+    const dir = app();
+    expect(installCommandFor(dir)?.('@acme/a')).toBe('pnpm add @acme/a');
+  });
+
+  // A package.json that is not the project's (spec AST-040 FR9): a run
+  // there loads integrations from it, so a package added to the project
+  // stays unused there. No command; the fix points at the project.
+  it("from a tool folder inside the project, names no command and points at the project's folder", () => {
+    const dir = app();
+    expect(installCommandFor(path.join(dir, 'tools', 'codegen'))).toBeNull();
+    const c = checkComputerIntegrationsAvailable({
+      installed: new Set(),
+      candidates: [/** @type {any} */ ({name: '@acme/a'})],
+      install: null,
+      elsewhere: true,
+    });
+    expect(c.fix).toBe(
+      "Run this from the Astryx project's folder, or declare an Astryx package in this folder's package.json to make it a project of its own.",
+    );
+  });
+
+  it('in a folder that belongs to no project, names no command', () => {
+    const dir = mkProject({'package.json': JSON.stringify({name: 'tool'})});
+    expect(installCommandFor(dir)).toBeNull();
+    const c = checkComputerIntegrationsAvailable({
+      installed: new Set(),
+      candidates: [/** @type {any} */ ({name: '@acme/a'})],
+      install: null,
+    });
+    expect(c.status).toBe('info');
+    expect(c).not.toHaveProperty('fix');
+  });
+});
+
+describe('checkCliCommand', () => {
+  it('is informational when no integration declares a command', () => {
+    const dir = mkProject({'pnpm-lock.yaml': ''});
+    const c = checkCliCommand({cwd: dir, integrations: [{name: '@acme/a'}]});
+    expect(c).toMatchObject({id: 'cli-command', status: 'info'});
+  });
+
+  it('passes and names the command and who declared it', () => {
+    const c = checkCliCommand({
+      cwd: mkProject({}),
+      integrations: [{name: '@acme/a', cliCommand: 'acme astryx'}],
+    });
+    expect(c).toMatchObject({id: 'cli-command', status: 'pass'});
+    expect(c.message).toContain('`acme astryx`');
+    expect(c.message).toContain('@acme/a');
+  });
+
+  it('warns when integrations declare different commands', () => {
+    const dir = mkProject({'pnpm-lock.yaml': ''});
+    const c = checkCliCommand({
+      cwd: dir,
+      integrations: [
+        {name: '@acme/a', cliCommand: 'acme astryx'},
+        {name: '@acme/b', cliCommand: 'other astryx'},
+      ],
+    });
+    expect(c).toMatchObject({id: 'cli-command', status: 'warn'});
+    expect(c.message).toContain('@acme/a (`acme astryx`)');
+    expect(c.message).toContain('@acme/b (`other astryx`)');
+    expect(c.message).toContain('pnpm dlx @astryxdesign/cli');
+    expect(c.fix).toContain('cliCommand');
+  });
+});
+
 describe('checkPackageManager', () => {
   it('is informational when one lockfile answers', () => {
     const dir = mkProject({'pnpm-lock.yaml': ''});
@@ -353,6 +534,49 @@ describe('checkImplicitIntegrations', () => {
     expect(c.message).toContain('named in astryx.config');
   });
 
+  // A package with no astryx.config that loads its own manifest: there is no
+  // config file, so the message must not say anything is named in one.
+  it("names the package's own manifest instead of a config that does not exist", () => {
+    const c = checkImplicitIntegrations({
+      integrations: [autolinked({__autolinked: false, __local: true, name: '@acme/kit'})],
+    });
+    expect(c.status).toBe('info');
+    expect(c.message).toBe(
+      "None — the only loaded integration is this package's own manifest (@acme/kit).",
+    );
+    expect(c.message).not.toContain('astryx.config');
+  });
+
+  // An own manifest that failed to load keeps a `__local` record carrying
+  // `__loadError`; it loaded nothing, so it is never named as loaded.
+  it("does not name the package's own manifest as loaded when it failed to load", () => {
+    const failed = autolinked({
+      __autolinked: false,
+      __local: true,
+      name: '@acme/kit',
+      __loadError: 'astryx.integration.mjs threw: boom',
+    });
+    const alone = checkImplicitIntegrations({integrations: [failed]});
+    expect(alone.status).toBe('info');
+    expect(alone.message).toBe('None loaded.');
+    const beside = checkImplicitIntegrations({
+      integrations: [autolinked({__autolinked: false}), failed],
+    });
+    expect(beside.message).toBe('None — every loaded integration is named in astryx.config.');
+  });
+
+  it('names both when configured integrations load beside the own manifest', () => {
+    const c = checkImplicitIntegrations({
+      integrations: [
+        autolinked({__autolinked: false}),
+        autolinked({__autolinked: false, __local: true, name: '@acme/kit'}),
+      ],
+    });
+    expect(c.message).toBe(
+      "None — every loaded integration is named in astryx.config or is this package's own manifest (@acme/kit).",
+    );
+  });
+
   it('names the package, the field, and what it contributes', () => {
     // Roots count only when they exist, so this one gives them real folders.
     const root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-implicit-'));
@@ -486,7 +710,7 @@ describe('checkAuthoringDocs', () => {
   it('passes when every authoring self-doc is reachable and fits one read', async () => {
     const c = await checkAuthoringDocs();
     expect(c).toMatchObject({id: 'authoring-docs', status: 'pass'});
-    expect(c.message).toContain('astryx docs authoring');
+    expect(c.message).toContain(formatCliCommand('docs authoring/field-reference'));
   }, SLOW);
 });
 
@@ -514,7 +738,7 @@ describe('checkCliDocs', () => {
         id: 'cli-docs',
         label: 'CLI docs',
         status: 'pass',
-        message: `All ${audit.docs} CLI docs are readable: ${audit.tree} in the \`astryx docs cli\` tree and ${audit.authoring} in \`astryx docs authoring\`.`,
+        message: `All ${audit.docs} CLI docs are readable: ${audit.tree} in the \`${formatCliCommand('docs cli')}\` tree and ${audit.authoring} in \`${formatCliCommand('docs authoring/field-reference')}\`.`,
       });
     },
     SLOW,
@@ -548,7 +772,7 @@ describe('checkCliDocs', () => {
         label: 'CLI docs',
         status: 'fail',
         message:
-          '2 problems: api/alpha/alpha.doc.mjs has no namespace, so no `astryx docs` topic reads it; clients/cli/commands/beta.doc.mjs has namespace "cli", which no `astryx docs` topic reads',
+          `2 problems: api/alpha/alpha.doc.mjs has no namespace, so no \`${formatCliCommand('docs')}\` topic reads it; clients/cli/commands/beta.doc.mjs has namespace "cli", which no \`${formatCliCommand('docs')}\` topic reads`,
         fix: CLI_DOCS_FIX,
       });
     },
@@ -624,7 +848,7 @@ describe('checkDocsTree', () => {
 describe('checkAuthoringDocs against the public authoring surface', () => {
   const NAMESPACE = 'doctypes/namespace/namespace.doc.mjs';
   const NAMESPACE_TYPES =
-    'NamespaceDoc, NamespaceProviderScope, NamespaceSlotAcceptance, NamespaceSlot, NamespaceAdoptionSource, NamespaceAdoptionRule from doctypes/namespace/type.ts have no doc in `astryx docs authoring`';
+    `NamespaceDoc, NamespaceProviderScope, NamespaceSlotAcceptance, NamespaceSlot, NamespaceAdoptionSource, NamespaceAdoptionRule from doctypes/namespace/type.ts have no doc in \`${formatCliCommand('docs authoring/field-reference')}\``;
   const SURFACE_FIX =
     'Put a self-doc beside each module whose types @astryxdesign/cli/authoring exports and list it in AUTHORING_SELF_DOCS; export what each listed self-doc documents, or remove that self-doc.';
 
@@ -654,7 +878,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
         id: 'authoring-docs',
         label: 'Authoring docs',
         status: 'pass',
-        message: `All ${AUTHORING_SELF_DOCS.length} authoring schemas are readable in \`astryx docs authoring\`.`,
+        message: `All ${AUTHORING_SELF_DOCS.length} authoring schemas are readable in \`${formatCliCommand('docs authoring/field-reference')}\`.`,
       });
     },
     SLOW,
@@ -683,7 +907,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
       });
       expect(c.status).toBe('fail');
       expect(c.message).toBe(
-        `2 problems: ${NAMESPACE} is not in \`astryx docs authoring\`; ${NAMESPACE_TYPES}: ${NAMESPACE} is not listed in AUTHORING_SELF_DOCS`,
+        `2 problems: ${NAMESPACE} is not in \`${formatCliCommand('docs authoring/field-reference')}\`; ${NAMESPACE_TYPES}: ${NAMESPACE} is not listed in AUTHORING_SELF_DOCS`,
       );
     },
     SLOW,
@@ -692,7 +916,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
   it(
     "fails when the topic's index no longer exposes the NamespaceDoc section",
     async () => {
-      const index = await docs('authoring', undefined, {index: true});
+      const index = await docs('authoring/field-reference', undefined, {index: true});
       const topicKeys = new Set(
         index.data.sections
           .map((/** @type {any} */ s) => s.id)
@@ -781,7 +1005,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
       expect(c.fix).toBe(SURFACE_FIX);
       expect(c.message).toMatch(
         new RegExp(
-          `^[A-Za-z, ]+ from ${escape(module)} have no doc in \`astryx docs authoring\`: no self-doc sits beside ${escape(module)}$`,
+          `^[A-Za-z, ]+ from ${escape(module)} have no doc in \`${escape(formatCliCommand('docs authoring/field-reference'))}\`: no self-doc sits beside ${escape(module)}$`,
         ),
       );
       for (const name of names) {
@@ -824,7 +1048,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
         expect(await checkAuthoringDocs()).toMatchObject({
           status: 'fail',
           message:
-            '`astryx docs authoring` could not be read: no built-in docs',
+            `\`${formatCliCommand('docs authoring/field-reference')}\` could not be read: no built-in docs`,
           fix: SURFACE_FIX,
         });
       } finally {
@@ -845,7 +1069,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
       const c = await checkAuthoringDocs(undefined, {root});
       expect(c.status).toBe('fail');
       expect(c.message).toContain(
-        '@astryxdesign/cli/authoring exports no types, so nothing was compared with `astryx docs authoring`',
+        `@astryxdesign/cli/authoring exports no types, so nothing was compared with \`${formatCliCommand('docs authoring/field-reference')}\``,
       );
     },
     SLOW,
@@ -1055,7 +1279,7 @@ describe('doctor says why it skipped and what it checked', () => {
       expect(by.config.message).toMatch(
         /^astryx\.config\.mjs loads, but the CLI could not load the project from it: .*integrations/,
       );
-      expect(by.config.fix).toContain('astryx docs authoring config');
+      expect(by.config.fix).toContain(' docs authoring config`');
       for (const id of ['implicit-integrations', 'provider-identity']) {
         expect(by[id].message).toMatch(
           /^Skipped — the project configuration could not be read: .*integrations/,
@@ -1151,8 +1375,12 @@ describe('a configured integration that cannot load fails the gate', () => {
     'astryx.config.mjs': "export default { integrations: ['@acme/widgets'] };\n",
   };
 
-  /** Run doctor on a project under the working directory. */
-  async function report(files) {
+  /**
+   * Run doctor on a project under the working directory, in its folder `at`.
+   * @param {Record<string, string>} files
+   * @param {string} [at]
+   */
+  async function report(files, at = '.') {
     const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doctor-gate-'));
     tmpDirs.push(dir);
     for (const [rel, content] of Object.entries(files)) {
@@ -1160,7 +1388,7 @@ describe('a configured integration that cannot load fails the gate', () => {
       fs.mkdirSync(path.dirname(abs), {recursive: true});
       fs.writeFileSync(abs, content);
     }
-    const {checks, summary} = (await doctor({cwd: dir})).data;
+    const {checks, summary} = (await doctor({cwd: path.join(dir, at)})).data;
     return {by: Object.fromEntries(checks.map(c => [c.id, c])), summary};
   }
 
@@ -1182,12 +1410,33 @@ describe('a configured integration that cannot load fails the gate', () => {
         /^1 of 1 integration named in astryx\.config could not be loaded, so it contributes nothing: @acme\/widgets \(/,
       );
       expect(check.message).toMatch(reason);
-      expect(check.fix).toContain('astryx doctor integration validate <package>');
+      expect(check.fix).toContain(' doctor integration validate <package>`');
       expect(summary.fail).toBe(1);
     },
     SLOW,
   );
 
+  it(
+    'passes in a workspace member whose configured integration is hoisted to the root',
+    async () => {
+      const {by} = await report(
+        {
+          'package.json': JSON.stringify({name: 'root', private: true, workspaces: ['apps/*']}),
+          ...CORE_STUB,
+          ...widgets(),
+          'apps/web/package.json': '{"name":"web"}',
+          'apps/web/astryx.config.mjs': "export default { integrations: ['@acme/widgets'] };\n",
+        },
+        'apps/web',
+      );
+      expect(by['configured-integrations'].status).toBe('pass');
+      expect(by['configured-integrations'].message).toBe(
+        '1 integration named in astryx.config loaded: @acme/widgets.',
+      );
+    },
+    SLOW,
+  );
+
   it(
     'counts the package being authored when its own config names it',
     async () => {

package/api/doctor/release-checks.test.mjs

@@ -0,0 +1,156 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file doctor's release checks (spec AST-081 FR10, FR11): the newest
+ * release beside a project's or the global copy's, with the fix, and the
+ * `astryx` commands on the search path.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {checkCliOnPath, checkNewestRelease} from './doctor.mjs';
+
+const answeredBy = {cli: '0.7.1', core: '0.7.1', copy: 'project'};
+
+/** @param {Partial<import('../../foundation/env/search-path.mjs').SearchPathCommand>} row */
+const row = row => ({
+  file: '/bin/astryx',
+  astryx: true,
+  cliRoot: '/lib/cli',
+  version: '0.8.0',
+  handsOff: true,
+  ...row,
+});
+
+describe('checkNewestRelease', () => {
+  it("names a project's install and upgrade commands", () => {
+    const check = checkNewestRelease({
+      nodeVersion: '24.0.0',
+      answeredBy,
+      latest: '0.7.3',
+      projectLag: {
+        root: '/app',
+        current: '0.7.1',
+        newest: '0.7.3',
+        install: 'npm install @astryxdesign/core@0.7.3 @astryxdesign/cli@0.7.3',
+        upgrade: 'npx astryx upgrade --from 0.7.1 --apply',
+      },
+    });
+    expect(check).toEqual({
+      id: 'newest-release',
+      label: 'Newest release',
+      status: 'info',
+      message: 'This project uses Astryx 0.7.1; 0.7.3 is the newest.',
+      fix: 'To upgrade, run: npm install @astryxdesign/core@0.7.3 @astryxdesign/cli@0.7.3, then npx astryx upgrade --from 0.7.1 --apply.',
+    });
+  });
+
+  it('adds the last notice skip and a held state lock, for diagnosis', () => {
+    const check = checkNewestRelease({
+      nodeVersion: '24.0.0',
+      answeredBy,
+      latest: '0.7.1',
+      lastNoticeSkip: {
+        key: 'global',
+        reason: 'already-shown',
+        at: Date.UTC(2026, 9, 20, 18),
+      },
+      stateLock: {pid: 42, host: 'mac', since: Date.UTC(2026, 9, 20, 17)},
+    });
+    expect(check.message).toBe(
+      'No newer release is known: the newest is 0.7.1. ' +
+        'Last update notice skipped 2026-10-20T18:00:00.000Z (global): it had already printed that day. ' +
+        "The state file's lock is held by process 42 on mac since 2026-10-20T17:00:00.000Z.",
+    );
+  });
+
+  it('says when the last update check did not reach the registry, and why', () => {
+    const check = checkNewestRelease({
+      nodeVersion: '24.0.0',
+      answeredBy,
+      latest: null,
+      lastCheckFailure: {
+        at: Date.UTC(2026, 9, 20, 18),
+        reason: 'npm-failed: ECONNREFUSED',
+      },
+    });
+    expect(check.message).toContain(
+      'The last update check, 2026-10-20T18:00:00.000Z, did not reach the registry: npm failed (ECONNREFUSED); its registry and proxy settings decide where it asks.',
+    );
+    expect(
+      checkNewestRelease({
+        nodeVersion: '24.0.0',
+        answeredBy,
+        latest: null,
+        lastCheckFailure: {at: 0, reason: 'npm-missing'},
+      }).message,
+    ).toContain('did not reach the registry: npm could not be started.');
+  });
+
+  it("names the global copy's upgrade, after the Node the newest release needs", () => {
+    const check = checkNewestRelease({
+      nodeVersion: '22.13.0',
+      answeredBy: {...answeredBy, copy: 'carried'},
+      latest: '0.8.0',
+      globalBehind: {
+        current: '0.7.1',
+        newest: '0.8.0',
+        node: '>=99',
+        command: 'pnpm add -g @astryxdesign/cli@latest',
+      },
+    });
+    expect(check).toEqual({
+      id: 'newest-release',
+      label: 'Newest release',
+      status: 'info',
+      message:
+        'A new release of Astryx is available: 0.7.1 → 0.8.0. The CLI installed for the computer stays on its release until you upgrade it.',
+      fix: `To upgrade, install Node >=99 (this computer runs Node ${process.versions.node}), then run: pnpm add -g @astryxdesign/cli@latest.`,
+    });
+  });
+});
+
+describe('checkCliOnPath', () => {
+  const base = {nodeVersion: '24.0.0', answeredBy, latest: null};
+
+  it('passes for a release that hands off, and lists the later ones', () => {
+    const check = checkCliOnPath({
+      ...base,
+      searchPathCommands: [
+        row({}),
+        row({file: '/other/astryx', version: '0.7.1', handsOff: false}),
+      ],
+    });
+    expect(check).toMatchObject({
+      status: 'pass',
+      message:
+        '`astryx` runs /bin/astryx (CLI 0.8.0). Later on the search path: /other/astryx (CLI 0.7.1).',
+    });
+  });
+
+  it('warns about a first release that predates the hand-off, naming the replacement', () => {
+    expect(
+      checkCliOnPath({
+        ...base,
+        searchPathCommands: [row({version: '0.7.1', handsOff: false})],
+      }),
+    ).toMatchObject({
+      status: 'warn',
+      fix: 'To upgrade, run: `npm i -g @astryxdesign/cli@latest`.',
+    });
+  });
+
+  it('warns about another program first, and informs when there is none', () => {
+    expect(
+      checkCliOnPath({
+        ...base,
+        searchPathCommands: [
+          row({astryx: false, cliRoot: null, version: null, handsOff: null}),
+        ],
+      }),
+    ).toMatchObject({status: 'warn'});
+    expect(checkCliOnPath({...base, searchPathCommands: []})).toMatchObject({
+      status: 'info',
+      fix: 'To run the CLI in any folder, install it for the computer: `npm i -g @astryxdesign/cli`.',
+    });
+  });
+});

package/api/doctor/theme-checks.mjs

@@ -32,7 +32,10 @@ import {
   themeRecordOwner,
   validateThemePrivateInputs,
 } from './_adapter.mjs';
-import {getCliInvocation} from '../../foundation/env/package-manager.mjs';
+import {
+  getCliInvocation,
+  formatCliCommand,
+} from '../../foundation/env/package-manager.mjs';
 import {satisfiesRange} from '../../foundation/env/semver.mjs';
 import {logger} from '../logger.mjs';
 
@@ -69,7 +72,7 @@ function unavailableChecks(message, moduleError = null) {
       moduleError && id === 'theme-module' ? moduleError.message : message,
     ...(moduleError && id === 'theme-module'
       ? {
-          fix: 'Keep one CLI-generated astryx-themes.ts or astryx-themes.js file, then run `astryx theme add <slug>`.',
+          fix: `Keep one CLI-generated astryx-themes.ts or astryx-themes.js file, then run \`${formatCliCommand('theme add <slug>')}\`.`,
         }
       : {}),
   }));
@@ -736,7 +739,7 @@ export async function checkAppThemes(cwd) {
       label: 'App imports the theme module',
       status: 'warn',
       message: `Could not prove that project source imports ${state.module.path}${importEvidence.parseFailures ? `; ${importEvidence.parseFailures} source file(s) could not be parsed` : ''}.`,
-      fix: `Import {themes, defaultThemeSlug} from the generated module and {Theme} from '@astryxdesign/core', then render <Theme theme={themes[defaultThemeSlug]}>.`,
+      fix: `Import {themes, defaultThemeSlug} from the generated module and {Theme} from '@astryxdesign/core/theme', then render <Theme theme={themes[defaultThemeSlug]}>.`,
     });
   }
 
@@ -794,6 +797,16 @@ export async function checkAppThemes(cwd) {
       message:
         'Could not check local build freshness until every local output resolves.',
     });
+  } else if (localThemes.length > 0 && !findDoctorCoreDir(state.projectDir)) {
+    // A build reads Core, and doctor reads only the Core the project
+    // installed, never the one the answering copy carries (spec AST-081 FR3).
+    checks.push({
+      id: 'theme-local-builds',
+      label: 'Local theme build freshness',
+      status: 'info',
+      message:
+        "The project's Core isn't installed, so local theme builds were not checked. Install the project's dependencies, then run doctor again.",
+    });
   } else if (localThemes.length === 0) {
     checks.push({
       id: 'theme-local-builds',
@@ -817,7 +830,7 @@ export async function checkAppThemes(cwd) {
           const receipt = await themeBuild(
             path.join(availableTheme.sourceDir, availableTheme.entry),
             {check: true},
-            {cwd: state.projectDir},
+            {cwd: state.projectDir, projectCore: true},
           );
           if (
             receipt == null ||