@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/foundation/config/project.mjs

@@ -43,6 +43,16 @@ import {
   resolvePackageDir,
 } from '../integrations/integrations.mjs';
 import {loadAutolinkCandidates} from '../integrations/autolink.mjs';
+import {
+  computerInstallRoots,
+  loadComputerIntegrations,
+  scanComputerIntegrations,
+} from '../integrations/computer-integrations.mjs';
+import {relativeWithin, samePath} from '../fs/path-compare.mjs';
+import {isOutsideProject} from '../env/project-scope.mjs';
+import {cliVersion} from '../release/run-context.mjs';
+import {isGlobalCopy} from '../release/choose.mjs';
+import {astryxCommandsOnSearchPath} from '../env/search-path.mjs';
 import {resolveProviders} from '../integrations/provider-resolution.mjs';
 import {
   setProject as setDebugProject,
@@ -55,7 +65,7 @@ import {
   discoverValidIntegrationComponents,
 } from '../discovery/component-discovery.mjs';
 import {resolveComponentReplacements} from '../discovery/component-replacement.mjs';
-import {findCoreDir} from '../fs/paths.mjs';
+import {CLI_ROOT, findCoreDir, findProjectCoreDir} from '../fs/paths.mjs';
 import {
   applyTemplateReplacements,
   effectiveTemplateDiscovery,
@@ -78,6 +88,7 @@ import {
   selectIntegrationCodemods,
 } from '../../assets/codemods/integration-discovery.mjs';
 import {validateLoadedIntegration} from '../integrations/validate-contributions.mjs';
+import {recordDeclaredCliCommands} from '../env/cli-command.mjs';
 import {
   InMemoryConfigCache,
   cacheKey,
@@ -100,6 +111,80 @@ function errorMessage(err) {
   return message == null ? String(err) : String(message);
 }
 
+/**
+ * The computer-level integrations (spec AST-081 FR12), read from package.json
+ * files only. Outside a project, those installed beside the running CLI;
+ * inside one, where the project's own CLI may be the copy that answers, those
+ * installed beside the CLI installed for the computer (see globalCliRoot).
+ * @param {string} [cwd]
+ * @returns {import('../integrations/computer-integrations.mjs').ComputerIntegrationCandidate[]}
+ */
+export function computerIntegrationCandidates(cwd = process.cwd()) {
+  try {
+    const cliRoot = isOutsideProject(cwd) ? CLI_ROOT : globalCliRoot(cwd);
+    return cliRoot
+      ? scanComputerIntegrations({cliRoot, release: cliVersion()})
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The CLI package whose install root holds the computer-level integrations
+ * for a folder inside a project: this copy when it was installed outside the
+ * project (installed for the computer, or in a tool's package set), else the
+ * first `astryx` on the search path that is installed for the computer. A
+ * project's own CLI and a release from the per-user cache are neither.
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+function globalCliRoot(cwd) {
+  let folder = path.resolve(cwd);
+  try {
+    folder = fs.realpathSync(folder);
+  } catch {
+    // A folder that cannot be resolved is compared as written.
+  }
+  const own = computerInstallRoots(CLI_ROOT);
+  if (
+    own.length > 0 &&
+    !own.some(
+      root => samePath(root, folder) || relativeWithin(root, folder) != null,
+    )
+  ) {
+    return CLI_ROOT;
+  }
+  for (const command of astryxCommandsOnSearchPath()) {
+    if (command.cliRoot && isGlobalCopy(command.cliRoot)) {
+      return command.cliRoot;
+    }
+  }
+  return null;
+}
+
+/**
+ * The computer-level integrations a project could add (spec AST-081 FR12):
+ * those it does not install, whose peer ranges admit the release that
+ * answers, and whose manifest loads.
+ * @param {string} cwd
+ * @param {Set<string>} installed package names the project loads or declares
+ * @returns {Promise<import('../integrations/computer-integrations.mjs').ComputerIntegrationCandidate[]>}
+ */
+export async function availableComputerIntegrations(cwd, installed) {
+  const candidates = computerIntegrationCandidates(cwd).filter(
+    c => !c.incompatible && !installed.has(c.name),
+  );
+  if (candidates.length === 0) return [];
+  const loaded = await loadComputerIntegrations(candidates);
+  const usable = new Set(
+    loaded.flatMap(entry =>
+      entry.integration && !entry.integration.__loadError ? [entry.spec] : [],
+    ),
+  );
+  return candidates.filter(c => usable.has(c.name));
+}
+
 /**
  * Load the configured integrations one at a time, so a package that cannot
  * load at all (not installed, no manifest, more than one manifest, not a bare
@@ -338,6 +423,12 @@ export class Project {
   #cache;
   /** @type {string} */
   #hash;
+  /**
+   * Which Core the project reads: `any`, its installed Core else the Core the
+   * answering release carries, or `project`, its installed Core only.
+   * @type {'any' | 'project'}
+   */
+  #core = 'any';
   /** @type {ProjectIntegrationIssue[]} */
   #issues = [];
   /**
@@ -360,6 +451,7 @@ export class Project {
    * @param {import('../integrations/integrations.mjs').LoadedIntegration[]} init.loadedIntegrations
    * @param {import('./config-cache.mjs').ConfigCache} init.cache
    * @param {string} init.hash config content hash
+   * @param {'any' | 'project'} [init.core] which Core it reads
    */
   constructor({
     cwd,
@@ -369,7 +461,9 @@ export class Project {
     loadedIntegrations,
     cache,
     hash,
+    core = 'any',
   }) {
+    this.#core = core;
     this.#cwd = cwd;
     this.#configPath = configPath;
     this.#config = config;
@@ -384,11 +478,15 @@ export class Project {
    * and loads the configured integrations. Discovery is NOT run here — it is
    * lazy and memoized on the returned instance.
    *
+   * `core: 'project'` reads only the project's installed Core, never the Core
+   * the answering release carries: the commands that judge or change a
+   * project (`doctor`, `swizzle`, `upgrade`) load it so (spec AST-081 FR3).
+   *
    * @param {string} [cwd]
-   * @param {{cache?: import('./config-cache.mjs').ConfigCache, fresh?: boolean}} [options]
+   * @param {{cache?: import('./config-cache.mjs').ConfigCache, fresh?: boolean, core?: 'any' | 'project'}} [options]
    * @returns {Promise<Project>}
    */
-  static async load(cwd = process.cwd(), {cache, fresh = false} = {}) {
+  static async load(cwd = process.cwd(), {cache, fresh = false, core = 'any'} = {}) {
     const resolvedCache = fresh
       ? new InMemoryConfigCache()
       : (cache ?? new InMemoryConfigCache());
@@ -440,7 +538,26 @@ export class Project {
     // existing consumer command doubles as the author's preview. A local copy
     // replaces the same installed package in place, preserving configured
     // precedence while making the source being edited authoritative.
-    const localIntegration = await loadLocalIntegrationSafely(projectDir, fresh);
+    const localIntegration = await loadLocalIntegrationSafely(
+      projectDir,
+      fresh,
+    );
+
+    // Outside a project, the integrations installed beside the running CLI
+    // load too (spec AST-081 FR12); a package the folder already loads keeps
+    // its own copy. Inside a project they never load.
+    const computer = isOutsideProject(cwd)
+      ? await loadComputerIntegrations(computerIntegrationCandidates(cwd), {
+          fresh,
+          exclude: [
+            ...loadedIntegrations.map(integration => integration.name),
+            ...autolinked.flatMap(candidate =>
+              candidate.integration ? [candidate.integration.name] : [],
+            ),
+            ...(localIntegration ? [localIntegration.name] : []),
+          ],
+        })
+      : [];
 
     // Autolinked and local packages can claim a provider ID that a configured
     // package already holds, so identity is resolved once over the final set.
@@ -451,6 +568,7 @@ export class Project {
         spec: integration.__spec,
       })),
       ...autolinked,
+      ...computer,
       ...(localIntegration
         ? [
             {
@@ -462,6 +580,9 @@ export class Project {
         : []),
     ]);
     loadedIntegrations = resolution.integrations;
+    // The picker (getCliInvocation) is synchronous, so the commands these
+    // integrations declare are recorded here, where they become known.
+    recordDeclaredCliCommands(projectDir, loadedIntegrations);
 
     // The debug recorder resolves its settings synchronously, long before any
     // command gets here, so this is where a project's `debug` block gets a
@@ -500,6 +621,7 @@ export class Project {
       loadedIntegrations,
       cache: resolvedCache,
       hash,
+      core,
     });
     PROVIDER_LEDGERS.set(project, resolution.ledger);
     return project;
@@ -634,6 +756,18 @@ export class Project {
     }
   }
 
+  /**
+   * The Core this project reads: its installed Core, else, unless it was
+   * loaded with `core: 'project'`, the Core the answering release carries
+   * (spec AST-081 FR3). Null when there is none.
+   * @returns {string | null}
+   */
+  coreDir() {
+    return this.#core === 'project'
+      ? findProjectCoreDir(this.#cwd)
+      : findCoreDir(this.#cwd);
+  }
+
   /**
    * Core + integration component ownership records. Wraps
    * discoverOwnedComponents for core and discoverIntegrationComponents (via
@@ -645,7 +779,7 @@ export class Project {
    */
   async components() {
     return this.#memo('components', async () => {
-      const coreDir = findCoreDir(this.#cwd);
+      const coreDir = this.coreDir();
       /** @type {Array<{name: string, package: string, group: string|null, docPath: string|null, sourcePath: string|null, issuesUrl: string|undefined}>} */
       const records = [];
 
@@ -696,7 +830,7 @@ export class Project {
   async componentReplacements() {
     return this.#memo('componentReplacements', async () => {
       const replacements = await resolveComponentReplacements(
-        findCoreDir(this.#cwd),
+        this.coreDir(),
         this.#loadedIntegrations,
       );
       for (const finding of replacements.findings) {
@@ -846,7 +980,7 @@ export class Project {
     const replacing = new Map();
     if (this.#loadedIntegrations.length > 0) {
       const {active} = await resolveComponentReplacements(
-        findCoreDir(this.#cwd),
+        this.coreDir(),
         this.#loadedIntegrations,
       );
       for (const each of active) {
@@ -943,7 +1077,10 @@ export class Project {
           // nothing and a reader gets the topic it was meant to replace.
           if (errors.length > 0) {
             for (const e of errors) {
-              catalog.addIssue({package: integration.name ?? pkg, message: e.message});
+              catalog.addIssue({
+                package: integration.name ?? pkg,
+                message: e.message,
+              });
             }
             continue;
           }

package/foundation/config/project.test.mjs

@@ -2,9 +2,11 @@
 
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import {Project, DEFAULT_ISSUES_URL, findConfigPath} from './project.mjs';
 import {InMemoryConfigCache} from './config-cache.mjs';
+import {getCliInvocation} from '../env/package-manager.mjs';
 import * as componentDiscovery from '../discovery/component-discovery.mjs';
 import {discoverCoreTemplates} from '../discovery/template-adapter.mjs';
 
@@ -31,6 +33,7 @@ function scaffold({
   docs = null,
   unknownKeys = null,
   agentDocs = null,
+  cliCommand = null,
   integrationIssuesUrl = 'https://example.com/widgets/issues',
 } = {}) {
   fs.writeFileSync(
@@ -57,6 +60,7 @@ function scaffold({
   if (withCodemods) manifest.codemods = './codemods';
   if (docs) manifest.docs = './docs';
   if (agentDocs != null) manifest.agentDocs = agentDocs;
+  if (cliCommand != null) manifest.cliCommand = cliCommand;
   if (unknownKeys) Object.assign(manifest, unknownKeys);
   if (integrationIssuesUrl) manifest.issuesUrl = integrationIssuesUrl;
   fs.writeFileSync(
@@ -287,6 +291,68 @@ describe('Project.load', () => {
   });
 });
 
+describe('Project.load and the cliCommand an integration declares', () => {
+  it('records it, so the picker prints commands with it', async () => {
+    scaffold({cliCommand: 'acme astryx'});
+    const project = await Project.load(tmpDir);
+    expect(project.loadedIntegrations[0].cliCommand).toBe('acme astryx');
+    expect(getCliInvocation(tmpDir)).toBe('acme astryx');
+  });
+
+  it('ignores an invalid one with a warning and keeps the rest of the package', async () => {
+    scaffold({cliCommand: ' acme astryx\n'});
+    const project = await Project.load(tmpDir);
+    const [widgets] = project.loadedIntegrations;
+    expect(widgets.__loadError).toBeUndefined();
+    expect(widgets.cliCommand).toBeUndefined();
+    expect(widgets.components).toBeDefined();
+    expect(getCliInvocation(tmpDir)).not.toContain('acme astryx');
+    const issues = await project.issues();
+    expect(issues).toContainEqual(
+      expect.objectContaining({
+        code: 'invalid_cli_command',
+        severity: 'warning',
+      }),
+    );
+  });
+
+  it('drops a previous load once the declaration is gone', async () => {
+    scaffold({cliCommand: 'acme astryx'});
+    await Project.load(tmpDir);
+    scaffold();
+    await Project.load(tmpDir, {fresh: true});
+    expect(getCliInvocation(tmpDir)).not.toBe('acme astryx');
+  });
+});
+
+describe("Project.load({core: 'project'})", () => {
+  it('reads only the installed Core, never the Core the answering release carries', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-project-core-'));
+    try {
+      fs.writeFileSync(
+        path.join(dir, 'package.json'),
+        JSON.stringify({name: 'a', dependencies: {'@astryxdesign/core': '^0.7.0'}}),
+      );
+      const any = await Project.load(dir);
+      const own = await Project.load(dir, {core: 'project'});
+      // The CLI in this repository carries the Core beside it.
+      expect(any.coreDir()).not.toBeNull();
+      expect(own.coreDir()).toBeNull();
+      expect((await own.components()).filter(c => c.package === '@astryxdesign/core')).toEqual([]);
+
+      const core = path.join(dir, 'node_modules', '@astryxdesign', 'core');
+      fs.mkdirSync(core, {recursive: true});
+      fs.writeFileSync(
+        path.join(core, 'package.json'),
+        JSON.stringify({name: '@astryxdesign/core', version: '0.7.0'}),
+      );
+      expect((await Project.load(dir, {core: 'project'})).coreDir()).toBe(fs.realpathSync(core));
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  });
+});
+
 describe('findConfigPath', () => {
   it('rejects multiple config files at the same root', () => {
     fs.writeFileSync(

package/foundation/config/theme-state.mjs

@@ -16,6 +16,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {assertWithin, PathSafetyError} from '../fs/path-safety.mjs';
+import {formatCliCommand} from '../env/package-manager.mjs';
 
 export const LOCAL_THEME_ROOT = './src/themes';
 export const THEME_MODULE_BASENAME = 'astryx-themes';
@@ -106,7 +107,7 @@ export function themeModuleCandidates(projectDir) {
 function validThemeRecord(value, label) {
   if (!isRecord(value) || !isRecord(value.themes)) {
     throw new ThemeStateError(
-      `${label} must carry a static ${THEME_RECORD_MARKER} header. Regenerate it with \`astryx theme add <slug>\`.`,
+      `${label} must carry a static ${THEME_RECORD_MARKER} header. Regenerate it with \`${formatCliCommand('theme add <slug>')}\`.`,
     );
   }
   const keys = Object.keys(value);
@@ -139,7 +140,7 @@ function validThemeRecord(value, label) {
     !THEME_SLUG_RE.test(value.defaultThemeSlug)
   ) {
     throw new ThemeStateError(
-      `${label} defaultThemeSlug must be a lowercase kebab-case slug. Regenerate it with \`astryx theme use <slug>\`.`,
+      `${label} defaultThemeSlug must be a lowercase kebab-case slug. Regenerate it with \`${formatCliCommand('theme use <slug>')}\`.`,
     );
   }
   return {themes, defaultSlug: value.defaultThemeSlug};
@@ -159,7 +160,7 @@ export function parseThemeModuleRecord(source, label = 'theme module') {
     .filter(line => /^\s*\*\s*@astryx-theme-record\s+/u.test(line));
   if (recordLines.length !== 1) {
     throw new ThemeStateError(
-      `${label} must carry exactly one static ${THEME_RECORD_MARKER} header. Regenerate it with \`astryx theme add <slug>\`.`,
+      `${label} must carry exactly one static ${THEME_RECORD_MARKER} header. Regenerate it with \`${formatCliCommand('theme add <slug>')}\`.`,
     );
   }
   const payload = recordLines[0].replace(
@@ -318,7 +319,7 @@ export function readThemeState(cwd = process.cwd()) {
 export function renderThemeModule(themes, defaultSlug, typescript) {
   if (!themes.some(theme => theme.slug === defaultSlug)) {
     throw new ThemeStateError(
-      `Default theme "${defaultSlug}" is not added. Run \`astryx theme add ${defaultSlug}\` first.`,
+      `Default theme "${defaultSlug}" is not added. Run \`${formatCliCommand(`theme add ${defaultSlug}`)}\` first.`,
     );
   }
   /** @type {string[]} */

package/foundation/discovery/authoring-self-docs.mjs

@@ -193,7 +193,7 @@ export function buildAuthoringReferenceDoc(docs) {
     title: 'Authoring Reference',
     category: 'guide',
     description:
-      'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type.',
+      'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type. The step-by-step guides are under `astryx docs cli/integrations`.',
     sections: docs.map(selfDocSection),
   });
 }

package/foundation/discovery/cli-self-docs.mjs

@@ -25,6 +25,7 @@ import {
   oversizedDocSections,
 } from './docs-output-budget.mjs';
 import {routeSegment} from './docs-section-key.mjs';
+import {formatCliCommand} from '../env/package-manager.mjs';
 
 /** The directories, relative to the CLI root, that hold the CLI's own docs. */
 export const CLI_SELF_DOC_DIRS = [
@@ -187,6 +188,19 @@ function sentence(text, more) {
   return more && text !== '' && !/[.!?:]$/.test(text) ? `${text}.` : text;
 }
 
+/**
+ * The line a command doc prints for what it does outside a project (spec
+ * AST-081 FR4). A group that only holds subcommands declares nothing and
+ * prints nothing.
+ * @type {Record<string, string>}
+ */
+const OUTSIDE_PROJECT_TEXT = {
+  same: "Outside a project (`same`): it answers as it would in a new project on this release, reading this release's Core, as it does in a project with nothing installed: the one installed beside the CLI, else one in the per-user cache, which a global install downloads in the background after a command run online (in CI, the first command that needs it downloads it).",
+  refuse:
+    'Outside a project (`refuse`): it writes nothing and fails, naming the app project or integration package it needs.',
+  own: 'Outside a project (`own`): it does what the description above says it does outside a project.',
+};
+
 /** @param {any[]} notes */
 function noteBlocks(notes) {
   return (notes ?? []).filter(note => TOPIC_BLOCKS.has(note?.type));
@@ -251,6 +265,8 @@ function commandSection(cmd, index) {
       rows: exitCodes.map((/** @type {any} */ e) => [String(e.code), e.when]),
     });
   }
+  const outside = OUTSIDE_PROJECT_TEXT[cmd.outsideProject];
+  if (outside) content.push({type: 'prose', text: outside});
   // Links name docs by identity; the route in each command is derived when
   // the doc is read (spec:AST-047 FR9).
   const subcommands = (cmd.subcommands ?? []).filter(
@@ -318,7 +334,8 @@ function functionSection(fn, index) {
     // A Default column only when some parameter declares a default, so a
     // function with none keeps a three-column table.
     const defaults = params.some(
-      (/** @type {any} */ p) => typeof p.default === 'string' && p.default !== '',
+      (/** @type {any} */ p) =>
+        typeof p.default === 'string' && p.default !== '',
     );
     content.push({
       type: 'table',
@@ -475,13 +492,13 @@ export async function auditCliSelfDocs({
       else {
         misfiled.push({
           source,
-          message: `${source} has namespace "authoring", but \`astryx docs authoring\` does not list it`,
+          message: `${source} has namespace "authoring", but \`${formatCliCommand('docs authoring')}\` does not list it`,
         });
       }
     } else if (inAuthoring) {
       misfiled.push({
         source,
-        message: `${source} is read in \`astryx docs authoring\`, but its namespace is "${namespace}"`,
+        message: `${source} is read in \`${formatCliCommand('docs authoring')}\`, but its namespace is "${namespace}"`,
       });
     } else {
       treeDocs.push(doc);

package/foundation/discovery/cli-self-docs.test.mjs

@@ -25,6 +25,7 @@ import {
   discoverCliSelfDocSources,
 } from './cli-self-docs.mjs';
 import {routeSegment} from './docs-section-key.mjs';
+import {formatCliCommand} from '../env/package-manager.mjs';
 
 const SLOW = 60_000;
 
@@ -145,8 +146,8 @@ describe('auditCliSelfDocs', () => {
     });
     const result = await audit(root, ['y/y.doc.mjs', 'z/z.doc.mjs']);
     expect(result.misfiled.map(entry => entry.message)).toEqual([
-      'authoring/x/x.doc.mjs has namespace "authoring", but `astryx docs authoring` does not list it',
-      'authoring/y/y.doc.mjs is read in `astryx docs authoring`, but its namespace is "cli/api"',
+      `authoring/x/x.doc.mjs has namespace "authoring", but \`${formatCliCommand('docs authoring')}\` does not list it`,
+      `authoring/y/y.doc.mjs is read in \`${formatCliCommand('docs authoring')}\`, but its namespace is "cli/api"`,
     ]);
     expect(result.authoring).toBe(1);
     expect(result.tree).toBe(0);

package/foundation/discovery/component-replacement.mjs

@@ -30,6 +30,7 @@ import {
   COMPONENT_REPLACES_CLI,
   componentReplacesCliProblem,
 } from '../integrations/cli-requirement.mjs';
+import {formatCliCommand} from '../env/package-manager.mjs';
 
 /**
  * @typedef {import('../integrations/integrations.mjs').LoadedIntegration} LoadedIntegration
@@ -292,7 +293,7 @@ export async function resolveComponentReplacements(
         'missing_component_replacement_target',
         differentCase
           ? `Component "${name}" replaces "${replaces}", which is not a Core component name. Core names it "${differentCase}".`
-          : `Component "${name}" replaces "${replaces}", which is not a Core component. Run \`astryx component --list\` for Core component names.`,
+          : `Component "${name}" replaces "${replaces}", which is not a Core component. Run \`${formatCliCommand('component --list')}\` for Core component names.`,
       );
       if (declaration.optedIn) {
         const key = differentCase ?? replaces;