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

package/api/docs/namespace-section.test.mjs

@@ -157,13 +157,13 @@ describe('a section read on a namespace', () => {
       expect(names).toContain('layout/side-panels');
       expect(names.every(name => name.startsWith('layout/'))).toBe(true);
       // At any depth: guides under nested namespaces are named, namespaces are not.
-      const cli = await docs('cli', 'zzzz-nope').catch(e => e);
-      expect(cli.code).toBe('ERR_UNKNOWN_SECTION');
-      expect(cli.suggestions.map(s => s.name)).toContain(
-        'cli/integrations/quick-start',
+      const authoring = await docs('authoring', 'zzzz-nope').catch(e => e);
+      expect(authoring.code).toBe('ERR_UNKNOWN_SECTION');
+      expect(authoring.suggestions.map(s => s.name)).toContain(
+        'authoring/building-blocks/components/add-a-component',
       );
-      expect(cli.suggestions.map(s => s.name)).not.toContain(
-        'cli/integrations',
+      expect(authoring.suggestions.map(s => s.name)).not.toContain(
+        'authoring/building-blocks',
       );
     },
     SLOW,

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,
   );
@@ -302,11 +300,11 @@ describe('a reference block that includes what it names', () => {
 });
 
 describe('what a reference block names', () => {
-  it('resolves a CLI authoring schema by identity, to its section of `astryx docs authoring`', async () => {
+  it('resolves a CLI authoring schema by identity, to its section of the field reference', async () => {
     const resolve = await linkResolver(builtinCatalog(), CLI_PROVIDER_ID);
     expect(await resolve('schema:integration')).toMatchObject({
       id: createDocId(CLI_PROVIDER_ID, 'schema', 'integration'),
-      route: 'authoring',
+      route: 'authoring/field-reference',
       title: 'Astryx Integration',
       command: 'astryx docs authoring integration',
     });

package/api/doctor/_adapter.d.mts

@@ -43,8 +43,136 @@ 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, its state on disk, and the command
+ * the skill file tells agents to run and the install step it records for when
+ * that command is not found (each null when there is no file, or it names
+ * none).
+ * @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}>, command: string | null, install: string | null}}
+ */
+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;
+    }>;
+    command: string | null;
+    install: string | null;
+};
+/**
+ * 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, runner: boolean}>}}
+ */
+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;
+        runner: boolean;
+    }>;
+};
+/** 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. Null when no
+ * command fits (see `alignCliAndCore`).
+ * @param {string} cwd
+ * @param {string} cli
+ * @param {string} core
+ * @returns {string | null}
+ */
+export function alignCommand(cwd: string, cli: string, core: string): string | null;
+/**
+ * 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, and the Core it matches: from a folder whose package.json declares
+ * no Astryx package, in the Astryx project above at that project's Core; null
+ * when there is none (see `cliInstallAdvice`).
+ * @param {string} cwd
+ * @param {string} version
+ * @returns {{command: string, core: string} | null}
+ */
+export function addCliCommandFor(cwd: string, version: string): {
+    command: string;
+    core: string;
+} | null;
+/**
+ * The command that adds a package to the project of `cwd`; null in a folder
+ * that belongs to no project or whose package.json is not the project's (see
+ * `projectAddCommand`).
+ * @param {string} cwd
+ * @returns {((name: string) => string) | null}
+ */
+export function installCommandFor(cwd: string): ((name: string) => string) | null;
+/**
+ * Whether `cwd` is inside a project whose package.json is not the project's,
+ * so advice points at the project's folder (see `installFolder`).
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function insideProjectElsewhere(cwd: string): boolean;
 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,56 @@
 
 /** @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 {
+  alignCliAndCore,
+  cliInstallAdvice,
+  installFolder,
+  projectAddCommand,
+  globalBehind,
+  globalUpgradeCommand,
+  lastNoticeSkip,
+  projectLag,
+} from '../../foundation/release/notices.mjs';
+import {
+  coreVersionOf,
+  installPlaceOf,
+  isGlobalCopy,
+} from '../../foundation/release/choose.mjs';
+import {readReleaseFacts} from '../../foundation/release/project.mjs';
+import {astryxCommandsOnSearchPath} from '../../foundation/env/search-path.mjs';
+import {readDeclaredDependencies} from '../../foundation/integrations/autolink.mjs';
+import {
+  computerSkillFile,
+  displayHomePath,
+  inspectComputerAgentText,
+  skillCommandOf,
+  skillInstallStepOf,
+} 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 +145,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 +165,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 +229,211 @@ 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, its state on disk, and the command
+ * the skill file tells agents to run and the install step it records for when
+ * that command is not found (each null when there is no file, or it names
+ * none).
+ * @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}>, command: string | null, install: string | null}}
+ */
+export function computerAgentTextState() {
+  const settings = computerAgentTextSettings();
+  let command = null;
+  let install = null;
+  try {
+    const text = fs.readFileSync(computerSkillFile(), 'utf8');
+    command = skillCommandOf(text);
+    install = skillInstallStepOf(text);
+  } catch {
+    // No skill file, or one that cannot be read: no command to check.
+  }
+  return {
+    settings,
+    entries: inspectComputerAgentText({links: settings.links}),
+    command,
+    install,
+  };
+}
+
+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, runner: boolean}>}}
+ */
+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,
+      // A package runner's temporary install, which it puts first on the
+      // search path only for the run it starts.
+      runner: row.cliRoot ? installPlaceOf(row.cliRoot).runner : false,
+    })),
+  };
+}
+
+/** 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. Null when no
+ * command fits (see `alignCliAndCore`).
+ * @param {string} cwd
+ * @param {string} cli
+ * @param {string} core
+ * @returns {string | null}
+ */
+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, and the Core it matches: from a folder whose package.json declares
+ * no Astryx package, in the Astryx project above at that project's Core; null
+ * when there is none (see `cliInstallAdvice`).
+ * @param {string} cwd
+ * @param {string} version
+ * @returns {{command: string, core: string} | null}
+ */
+export function addCliCommandFor(cwd, version) {
+  const advice = cliInstallAdvice({cwd, core: version});
+  return advice?.command ? {command: advice.command, core: advice.core} : null;
+}
+
+/**
+ * The command that adds a package to the project of `cwd`; null in a folder
+ * that belongs to no project or whose package.json is not the project's (see
+ * `projectAddCommand`).
+ * @param {string} cwd
+ * @returns {((name: string) => string) | null}
+ */
+export function installCommandFor(cwd) {
+  return projectAddCommand(cwd);
+}
+
+/**
+ * Whether `cwd` is inside a project whose package.json is not the project's,
+ * so advice points at the project's folder (see `installFolder`).
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function insideProjectElsewhere(cwd) {
+  return installFolder(cwd)?.moved === true;
+}