@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/api/docs/docs.doc.mjs

@@ -34,7 +34,8 @@ export const doc = {
     'for a typed doc, `related` to the docs it names (its command or function, ' +
     'and its related docs); `previous` and `next` ' +
     'to the section or node before and after it. ' +
-    'Overlay options select localized or dense variants.',
+    'Overlay options select localized or dense variants.' +
+    " In global mode: with `cwd` outside a project, doc topics from integrations installed next to this CLI package globally are listed too; inside a project, only the project's own integrations count. See {@link namespace:global} and {@link generic:computer-integrations}.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'docs(topic?: string, section?: string, options?: DocsOptions): Promise<DocsListResponse | DocsIndexResponse | DocsDetailResponse | DocsDetailSectionResponse | DocsNodeResponse>',

package/api/docs/docs.mjs

@@ -34,6 +34,7 @@ import {node as nodeLeaf, nodeView} from './node/node.mjs';
 import {resolveDocsArgument} from './_adapter.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
+import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
 
 export {list, index, detail, sectionLeaf as section, nodeLeaf as node};
 
@@ -108,7 +109,7 @@ export async function docs(topic, section, options = {}) {
         return namespaceSection(found.tree, found.node, section, options);
       }
       throw new AstryxError(
-        `"${found.node.route}" has no sections. Read it whole: astryx docs ${found.node.route}.`,
+        `"${found.node.route}" has no sections. Read it whole: ${formatCliCommand(`docs ${found.node.route}`)}.`,
         [{name: found.node.route, reason: found.node.summary}],
         ERROR_CODES.ERR_UNKNOWN_SECTION,
       );

package/api/docs/docs.test.mjs

@@ -11,6 +11,7 @@
 import {describe, it, expect} from 'vitest';
 import {docs} from './docs.mjs';
 import {AstryxError} from '../error.mjs';
+import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
 
 const SLOW = 30_000;
 
@@ -92,7 +93,7 @@ describe('docs() dispatcher routing', () => {
 
   it("lists the docs tree's namespaces in meta, so every data entry reads as a topic", async () => {
     const res = await docs();
-    expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['cli', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography', 'unorganized']);
+    expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['cli', 'global', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography', 'unorganized']);
     for (const entry of res.data) {
       expect((await docs(entry.topic)).type).toBe('docs.detail');
     }
@@ -107,7 +108,9 @@ describe('docs() dispatcher routing', () => {
   it('a section of a typed doc -> ERR_UNKNOWN_SECTION, suggesting the doc itself', async () => {
     const err = await docs('cli/api/functions/search', 'x').catch(e => e);
     expect(err.code).toBe('ERR_UNKNOWN_SECTION');
-    expect(err.message).toContain('astryx docs cli/api/functions/search');
+    expect(err.message).toContain(
+      formatCliCommand('docs cli/api/functions/search'),
+    );
     expect(err.suggestions.map(s => s.name)).toEqual(['cli/api/functions/search']);
   }, SLOW);
 

package/api/docs/integration-tree.test.mjs

@@ -569,4 +569,26 @@ describe('integration docs in the docs tree', () => {
     expect(check.status).toBe('warn');
     expect(check.message).toContain('both have the route "cli"');
   }, SLOW);
+
+  it('says what to write for a link that names a doc by its bare name, and when no doc has that name', async () => {
+    scaffold({
+      ...kit(),
+      'bare.doc.mjs': guide('bare', {
+        sections: [
+          {
+            title: 'Overview',
+            content: [{type: 'prose', text: 'Read {@link deploy}, then {@link nosuchtopic}.'}],
+          },
+        ],
+      }),
+    });
+    const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
+    const graph = result.data.issues.filter(issue => issue.code === 'invalid_doc_graph').map(issue => issue.message);
+    expect(graph).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining('"deploy" is a topic: write `{@link generic:deploy}`.'),
+        expect.stringContaining('no topic is named "nosuchtopic"'),
+      ]),
+    );
+  }, SLOW);
 });

package/api/docs/integrationDocs.test.mjs

@@ -22,6 +22,7 @@ import {docs} from './docs.mjs';
 import {search} from '../search/search.mjs';
 import {loadDocsCatalog} from './_adapter.mjs';
 import {AstryxError} from '../error.mjs';
+import {discoverCoreTemplates} from '../../foundation/discovery/template-adapter.mjs';
 
 const SLOW = 30_000;
 
@@ -110,6 +111,129 @@ describe('integration-contributed topics', () => {
     expect(section.data.title).toBe('Overview');
   }, SLOW);
 
+  it('reads a link to a component or a template as the command that opens it', async () => {
+    scaffold({
+      'using-widgets.doc.mjs': topic({
+        name: 'using-widgets',
+        title: 'Using widgets',
+        sections: [
+          {
+            title: 'Overview',
+            content: [
+              {
+                type: 'prose',
+                text: 'Start with {@link component:AcmeButton} or {@link block:acme-card}, built on {@link @astryxdesign/core:component:Button}.',
+              },
+            ],
+          },
+        ],
+      }),
+    });
+    const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+    fs.writeFileSync(
+      path.join(pkgDir, 'astryx.integration.mjs'),
+      "export default {components: './components', templates: './templates', docs: './docs'};\n",
+    );
+    fs.mkdirSync(path.join(pkgDir, 'components'));
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'AcmeButton.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeButton', displayName: 'Acme Button', description: 'A button.', props: []};\n",
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'AcmeButton.tsx'),
+      'export function AcmeButton() { return null; }\n',
+    );
+    fs.mkdirSync(path.join(pkgDir, 'templates'));
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', 'acme-card.doc.mjs'),
+      "export default {type: 'block', name: 'Acme card', description: 'A card.'};\n",
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', 'acme-card.tsx'),
+      'export default function Fixture() { return null; }\n',
+    );
+
+    const detail = await docs('using-widgets', undefined, {cwd: tmpDir, full: true});
+
+    const prose = JSON.stringify(detail.data.sections);
+    expect(prose).toContain('`astryx component AcmeButton --package @acme/widgets`');
+    expect(prose).toContain(
+      '`astryx template acme-card --type block --package @acme/widgets`',
+    );
+    expect(prose).toContain('`astryx component Button`');
+    expect(prose).not.toContain('{@link');
+  }, SLOW);
+
+  it('selects Core in a link only where the bare name would open something else', async () => {
+    const core = await discoverCoreTemplates();
+    const page = core.find(template => template.type === 'page')?.dirName;
+    const block = core.find(template => template.type === 'block')?.dirName;
+    scaffold({
+      'using-widgets.doc.mjs': topic({
+        name: 'using-widgets',
+        title: 'Using widgets',
+        sections: [
+          {
+            title: 'Overview',
+            content: [
+              {
+                type: 'prose',
+                text:
+                  'Core: {@link @astryxdesign/core:component:Button}, {@link @astryxdesign/core:component:Badge}, ' +
+                  `{@link @astryxdesign/core:page:${page}}, {@link @astryxdesign/core:block:${block}}.`,
+              },
+            ],
+          },
+        ],
+      }),
+    });
+    const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+    // The CLI range that turns component replacement on.
+    fs.writeFileSync(
+      path.join(pkgDir, 'package.json'),
+      JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        peerDependencies: {'@astryxdesign/cli': '>=0.6.7'},
+        peerDependenciesMeta: {'@astryxdesign/cli': {optional: true}},
+      }),
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'astryx.integration.mjs'),
+      "export default {components: './components', templates: './templates', docs: './docs'};\n",
+    );
+    fs.mkdirSync(path.join(pkgDir, 'components'));
+    // AcmeButton replaces Core's Button, so bare `Button` opens AcmeButton.
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'AcmeButton.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeButton', displayName: 'Acme Button', description: 'A button.', replaces: 'Button', props: []};\n",
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'AcmeButton.tsx'),
+      'export function AcmeButton() { return null; }\n',
+    );
+    // A page template with a Core page's id makes the bare id ambiguous.
+    fs.mkdirSync(path.join(pkgDir, 'templates'));
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', `${page}.doc.mjs`),
+      "export default {type: 'page', name: 'Acme page', displayName: 'Acme page', description: 'A page.'};\n",
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', `${page}.tsx`),
+      'export default function Fixture() { return null; }\n',
+    );
+
+    const detail = await docs('using-widgets', undefined, {cwd: tmpDir, full: true});
+
+    const prose = JSON.stringify(detail.data.sections);
+    expect(prose).toContain('`astryx component Button --package @astryxdesign/core`');
+    expect(prose).toContain('`astryx component Badge`');
+    expect(prose).toContain(
+      `\`astryx template ${page} --type page --package @astryxdesign/core\``,
+    );
+    expect(prose).toContain(`\`astryx template ${block} --type block\``);
+  }, SLOW);
+
   it('is invisible to a project that does not configure the integration', async () => {
     scaffold({'deploying.doc.mjs': topic()}, {config: 'export default {};\n'});
     const listed = await docs(undefined, undefined, {cwd: tmpDir});

package/api/docs/list/list.mjs

@@ -15,7 +15,12 @@
  */
 
 import {loadTopicFile} from '../../../foundation/doc-compiler/read.mjs';
-import {holdsOwnName, loadDocsCatalog, projectTree} from '../_adapter.mjs';
+import {
+  holdsOwnName,
+  linkDocText,
+  loadDocsCatalog,
+  projectTree,
+} from '../_adapter.mjs';
 
 /**
  * @param {object} [options]
@@ -39,7 +44,12 @@ export async function list({cwd} = {}) {
     /** @type {import('../docs.type.mjs').DocsListEntry} */
     const listed = {
       topic: entry.name,
-      description,
+      // A link in the description reads as the command that opens its doc.
+      description: await linkDocText(
+        catalog,
+        entry.providerId ?? entry.package,
+        description,
+      ),
       package: entry.package,
     };
     if (entry.replaces != null) listed.replaces = entry.replaces;

package/api/docs/reference-blocks.test.mjs

@@ -276,9 +276,7 @@ describe('a reference block in a topic section', () => {
       expect(status).toBe(0);
       expect(stdout).toMatch(/^Field +\| Type +\| Required +\| Description/m);
       expect(stdout).toMatch(/^components +\| string +\| no +\| /m);
-      expect(stdout).toContain(
-        'From Astryx Integration: `astryx docs authoring integration`',
-      );
+      expect(stdout).toContain(' docs authoring integration`');
     },
     SLOW,
   );

package/api/doctor/_adapter.d.mts

@@ -43,8 +43,116 @@ export function findDoctorInstalledPackage(projectDir: string, packageName: stri
 export function listDoctorThemePackages(cwd: string): string[];
 /** @param {string} file */
 export function readPackageJson(file: string): any;
+/**
+ * The integrations installed for the computer, and, outside a project, which
+ * of them the folder loads (spec AST-081 FR12): those it uses, and the names
+ * of the integrations the folder loads itself, whose copies win.
+ * @param {string} cwd
+ * @returns {Promise<{computerIntegrations: import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[], loadedComputerIntegrations: string[], folderIntegrations: string[]}>}
+ */
+export function computerIntegrationsOutside(cwd: string): Promise<{
+    computerIntegrations: import("../../foundation/integrations/computer-integrations.mjs").ComputerIntegrationCandidate[];
+    loadedComputerIntegrations: string[];
+    folderIntegrations: string[];
+}>;
+/**
+ * Inside a project: the integrations installed for the computer it could add
+ * (spec AST-081 FR12), leaving out every package it loads or declares.
+ * @param {string} cwd
+ * @param {string[]} loadedNames the integrations the project loads
+ * @returns {Promise<import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[]>}
+ */
+export function computerIntegrationsToAdd(cwd: string, loadedNames: string[]): Promise<import("../../foundation/integrations/computer-integrations.mjs").ComputerIntegrationCandidate[]>;
+/**
+ * The computer-level agent text's setting and its state on disk.
+ * @returns {{settings: import('../../foundation/env/user-settings.mjs').ComputerAgentTextSettings, entries: Array<{path: string, state: import('../../foundation/agent-docs/computer-agent-text.mjs').ComputerAgentTextState, link?: true}>}}
+ */
+export function computerAgentTextState(): {
+    settings: import("../../foundation/env/user-settings.mjs").ComputerAgentTextSettings;
+    entries: Array<{
+        path: string;
+        state: import("../../foundation/agent-docs/computer-agent-text.mjs").ComputerAgentTextState;
+        link?: true;
+    }>;
+};
+/**
+ * The release facts doctor reports, read here so the checks stay pure
+ * (spec AST-081 FR5, FR6, FR10; architecture:cli-surface INV21): who
+ * answered, the newest release the computer knows of, how far the global copy
+ * or the project is behind, and every `astryx` on the search path with the
+ * command that upgrades it.
+ * @param {string} cwd
+ * @param {{project: boolean}} options
+ * @returns {{answeredBy: {cli: string, core: string | null, copy: string}, latest: string | null, globalBehind: ReturnType<typeof globalBehind> | null, projectLag: ReturnType<typeof projectLag> | null, lastNoticeSkip: ReturnType<typeof lastNoticeSkip>, lastCheckFailure: ReturnType<typeof lastCheckFailure>, stateLock: ReturnType<typeof stateLockHolder>, searchPathCommands: Array<import('../../foundation/env/search-path.mjs').SearchPathCommand & {upgrade: string | null}>}}
+ */
+export function releaseFacts(cwd: string, { project }: {
+    project: boolean;
+}): {
+    answeredBy: {
+        cli: string;
+        core: string | null;
+        copy: string;
+    };
+    latest: string | null;
+    globalBehind: ReturnType<typeof globalBehind> | null;
+    projectLag: ReturnType<typeof projectLag> | null;
+    lastNoticeSkip: ReturnType<typeof lastNoticeSkip>;
+    lastCheckFailure: ReturnType<typeof lastCheckFailure>;
+    stateLock: ReturnType<typeof stateLockHolder>;
+    searchPathCommands: Array<import("../../foundation/env/search-path.mjs").SearchPathCommand & {
+        upgrade: string | null;
+    }>;
+};
+/** Whether `cwd` is outside every project. */
+export function outsideProject(cwd: string): boolean;
+/**
+ * The commands that bring a project's own CLI and Core to one release, with
+ * the project's package manager: Core up to the CLI, then its codemods, when
+ * the CLI is newer; else the CLI to the Core's release.
+ * @param {string} cwd
+ * @param {string} cli
+ * @param {string} core
+ * @returns {string}
+ */
+export function alignCommand(cwd: string, cli: string, core: string): string;
+/**
+ * The Core release the project at `cwd` names: installed, else locked, else
+ * declared; the version the daily hint and notice compare against (spec
+ * AST-081 FR2). Null outside a project or when it names none.
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+export function projectCoreVersion(cwd: string): string | null;
+/**
+ * Whether the project at `cwd` installs its own CLI (spec AST-081 FR2).
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function projectHasOwnCli(cwd: string): boolean;
+/**
+ * The command that adds the CLI at `version` with the project's package
+ * manager.
+ * @param {string} cwd
+ * @param {string} version
+ * @returns {string}
+ */
+export function addCliCommandFor(cwd: string, version: string): string;
+/**
+ * The command that adds a package with the folder's package manager, read
+ * from its lockfiles and `packageManager` field.
+ * @param {string} cwd
+ * @returns {(name: string) => string}
+ */
+export function installCommandFor(cwd: string): (name: string) => string;
 export { resolveRecordedTheme } from "../theme/theme.mjs";
 export { collectUnloadedFonts } from "../theme/build/font-warning.mjs";
 export const SOURCE_EXTENSIONS: Set<string>;
+export { displayHomePath };
+import { globalBehind } from '../../foundation/release/notices.mjs';
+import { projectLag } from '../../foundation/release/notices.mjs';
+import { lastNoticeSkip } from '../../foundation/release/notices.mjs';
+import { lastCheckFailure } from '../../foundation/release/global-state.mjs';
+import { stateLockHolder } from '../../foundation/release/global-state.mjs';
+import { displayHomePath } from '../../foundation/agent-docs/computer-agent-text.mjs';
 export { isLocalThemeOwner, planThemeAppWrite, readThemeState, resolveThemeModule } from "../../foundation/config/theme-state.mjs";
 export { themeBuild, validateThemePrivateInputs } from "../theme/build/build.mjs";

package/api/doctor/_adapter.mjs

@@ -2,15 +2,52 @@
 
 /** @file Environment adapter for app-theme doctor evidence. */
 
+import {isOutsideProject} from '../../foundation/env/project-scope.mjs';
+import {answeredBy} from '../../foundation/release/run-context.mjs';
+import {
+  knownLatestRelease,
+  lastCheckFailure,
+  stateLockHolder,
+} from '../../foundation/release/global-state.mjs';
+import {
+  addCliCommand,
+  alignCliAndCore,
+  globalBehind,
+  globalUpgradeCommand,
+  lastNoticeSkip,
+  projectLag,
+} from '../../foundation/release/notices.mjs';
+import {
+  coreVersionOf,
+  isGlobalCopy,
+  projectRootOf,
+} from '../../foundation/release/choose.mjs';
+import {readReleaseFacts} from '../../foundation/release/project.mjs';
+import {detectPackageManager} from '../../foundation/env/package-manager.mjs';
+import {astryxCommandsOnSearchPath} from '../../foundation/env/search-path.mjs';
+import {readDeclaredDependencies} from '../../foundation/integrations/autolink.mjs';
+import {
+  displayHomePath,
+  inspectComputerAgentText,
+} from '../../foundation/agent-docs/computer-agent-text.mjs';
+import {computerAgentTextSettings} from '../../foundation/env/user-settings.mjs';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {Project} from '../../foundation/config/project.mjs';
+import {
+  Project,
+  availableComputerIntegrations,
+  computerIntegrationCandidates,
+} from '../../foundation/config/project.mjs';
 import {
   discoverUnmigratedThemeCopies,
   themeImportPackage,
 } from '../../foundation/discovery/theme-discovery.mjs';
 import {resolveThemeImports} from '../../foundation/discovery/theme-imports.mjs';
-import {findCoreDir, findInstalledPackage} from '../../foundation/fs/paths.mjs';
+import {
+  CLI_ROOT,
+  findProjectCoreDir,
+  findInstalledPackage,
+} from '../../foundation/fs/paths.mjs';
 export {
   isLocalThemeOwner,
   planThemeAppWrite,
@@ -104,7 +141,7 @@ export function listProjectSourceFiles(root, generatedModule) {
 
 /** @param {string} projectDir */
 export async function discoverDoctorThemes(projectDir) {
-  const project = await Project.load(projectDir);
+  const project = await Project.load(projectDir, {core: 'project'});
   return project.themes();
 }
 
@@ -124,7 +161,7 @@ export function discoverDoctorUnmigratedCopies(projectDir) {
 
 /** @param {string} projectDir */
 export function findDoctorCoreDir(projectDir) {
-  return findCoreDir(projectDir);
+  return findProjectCoreDir(projectDir);
 }
 
 /** @param {string} projectDir @param {string} packageName */
@@ -188,3 +225,185 @@ export function readPackageJson(file) {
     return null;
   }
 }
+
+/**
+ * The integrations installed for the computer, and, outside a project, which
+ * of them the folder loads (spec AST-081 FR12): those it uses, and the names
+ * of the integrations the folder loads itself, whose copies win.
+ * @param {string} cwd
+ * @returns {Promise<{computerIntegrations: import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[], loadedComputerIntegrations: string[], folderIntegrations: string[]}>}
+ */
+export async function computerIntegrationsOutside(cwd) {
+  const computerIntegrations = computerIntegrationCandidates(cwd);
+  if (computerIntegrations.length === 0) {
+    return {
+      computerIntegrations,
+      loadedComputerIntegrations: [],
+      folderIntegrations: [],
+    };
+  }
+  try {
+    const project = await Project.load(cwd, {core: 'project'});
+    /** @type {Array<{name: string, __computer?: boolean, __loadError?: string}>} */
+    const loaded = project.loadedIntegrations;
+    return {
+      computerIntegrations,
+      loadedComputerIntegrations: loaded
+        .filter(i => i.__computer && !i.__loadError)
+        .map(i => i.name),
+      folderIntegrations: loaded.filter(i => !i.__computer).map(i => i.name),
+    };
+  } catch {
+    return {
+      computerIntegrations,
+      loadedComputerIntegrations: [],
+      folderIntegrations: [],
+    };
+  }
+}
+
+/**
+ * Inside a project: the integrations installed for the computer it could add
+ * (spec AST-081 FR12), leaving out every package it loads or declares.
+ * @param {string} cwd
+ * @param {string[]} loadedNames the integrations the project loads
+ * @returns {Promise<import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[]>}
+ */
+export async function computerIntegrationsToAdd(cwd, loadedNames) {
+  const installed = new Set([...loadedNames, ...declaredPackageNames(cwd)]);
+  return availableComputerIntegrations(cwd, installed);
+}
+
+/**
+ * The package names the folder's package.json declares, nearest first.
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+function declaredPackageNames(cwd) {
+  for (let dir = path.resolve(cwd); ;) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) {
+      return readDeclaredDependencies(dir).map(d => d.name);
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return [];
+    dir = parent;
+  }
+}
+
+/**
+ * The computer-level agent text's setting and its state on disk.
+ * @returns {{settings: import('../../foundation/env/user-settings.mjs').ComputerAgentTextSettings, entries: Array<{path: string, state: import('../../foundation/agent-docs/computer-agent-text.mjs').ComputerAgentTextState, link?: true}>}}
+ */
+export function computerAgentTextState() {
+  const settings = computerAgentTextSettings();
+  return {settings, entries: inspectComputerAgentText({links: settings.links})};
+}
+
+export {displayHomePath};
+
+/**
+ * The release facts doctor reports, read here so the checks stay pure
+ * (spec AST-081 FR5, FR6, FR10; architecture:cli-surface INV21): who
+ * answered, the newest release the computer knows of, how far the global copy
+ * or the project is behind, and every `astryx` on the search path with the
+ * command that upgrades it.
+ * @param {string} cwd
+ * @param {{project: boolean}} options
+ * @returns {{answeredBy: {cli: string, core: string | null, copy: string}, latest: string | null, globalBehind: ReturnType<typeof globalBehind> | null, projectLag: ReturnType<typeof projectLag> | null, lastNoticeSkip: ReturnType<typeof lastNoticeSkip>, lastCheckFailure: ReturnType<typeof lastCheckFailure>, stateLock: ReturnType<typeof stateLockHolder>, searchPathCommands: Array<import('../../foundation/env/search-path.mjs').SearchPathCommand & {upgrade: string | null}>}}
+ */
+export function releaseFacts(cwd, {project}) {
+  const answered = answeredBy(cwd);
+  return {
+    answeredBy: answered,
+    latest: knownLatestRelease(),
+    lastNoticeSkip: lastNoticeSkip(),
+    lastCheckFailure: lastCheckFailure(),
+    stateLock: stateLockHolder(),
+    globalBehind:
+      !project && isGlobalCopy(CLI_ROOT)
+        ? globalBehind({self: {version: answered.cli, root: CLI_ROOT}})
+        : null,
+    // The project's version is its own CLI's, or, with none, its Core's:
+    // installed, else locked, else declared, as the daily notice reads it.
+    projectLag: project
+      ? projectLag({
+          cwd,
+          current:
+            (answered.copy === 'starting' && projectCoreVersion(cwd)) ||
+            answered.cli,
+        })
+      : null,
+    searchPathCommands: astryxCommandsOnSearchPath().map(row => ({
+      ...row,
+      upgrade: row.cliRoot ? globalUpgradeCommand(row.cliRoot) : null,
+    })),
+  };
+}
+
+/** Whether `cwd` is outside every project. */
+export function outsideProject(/** @type {string} */ cwd) {
+  return isOutsideProject(cwd);
+}
+
+/**
+ * The commands that bring a project's own CLI and Core to one release, with
+ * the project's package manager: Core up to the CLI, then its codemods, when
+ * the CLI is newer; else the CLI to the Core's release.
+ * @param {string} cwd
+ * @param {string} cli
+ * @param {string} core
+ * @returns {string}
+ */
+export function alignCommand(cwd, cli, core) {
+  return alignCliAndCore({cwd, cli, core});
+}
+
+/**
+ * The Core release the project at `cwd` names: installed, else locked, else
+ * declared; the version the daily hint and notice compare against (spec
+ * AST-081 FR2). Null outside a project or when it names none.
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+export function projectCoreVersion(cwd) {
+  return coreVersionOf(readReleaseFacts(cwd));
+}
+
+/**
+ * Whether the project at `cwd` installs its own CLI (spec AST-081 FR2).
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function projectHasOwnCli(cwd) {
+  return Boolean(readReleaseFacts(cwd).cli);
+}
+
+/**
+ * The command that adds the CLI at `version` with the project's package
+ * manager.
+ * @param {string} cwd
+ * @param {string} version
+ * @returns {string}
+ */
+export function addCliCommandFor(cwd, version) {
+  return addCliCommand(projectRootOf(readReleaseFacts(cwd)) ?? cwd, version);
+}
+
+/**
+ * The command that adds a package with the folder's package manager, read
+ * from its lockfiles and `packageManager` field.
+ * @param {string} cwd
+ * @returns {(name: string) => string}
+ */
+export function installCommandFor(cwd) {
+  const pm = detectPackageManager(cwd);
+  const verb =
+    pm === 'pnpm'
+      ? 'pnpm add'
+      : pm === 'yarn'
+        ? 'yarn add'
+        : pm === 'bun'
+          ? 'bun add'
+          : 'npm install';
+  return name => `${verb} ${name}`;
+}