@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/foundation/agent-docs/computer-agent-text.test.mjs

@@ -0,0 +1,602 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The computer-level agent text (spec AST-081 FR7, FR8): its two
+ * renderings, version-free and naming only stable commands; the one file it
+ * writes and the links it makes from the one table; what it keeps; exact
+ * removal; the search-path check behind its warning; and the rule that only
+ * `init --user` and the background step write it. Every test uses a temporary
+ * home folder.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {spawnSync} from 'node:child_process';
+import {createHash} from 'node:crypto';
+import {fileURLToPath} from 'node:url';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {
+  SKILL_LINKS,
+  STABLE_COMMANDS,
+  astryxOnSearchPath,
+  computerSkillFile,
+  computerSkillLinks,
+  inspectComputerAgentText,
+  removeComputerAgentText,
+  renderComputerAgentText,
+  writeComputerAgentText,
+} from './computer-agent-text.mjs';
+import {MARKER_END, MARKER_START} from './agent-doc-state.mjs';
+import {runWithCliDoor} from '../env/cli-command.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
+import {parse as parseYaml} from 'yaml';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const CLI_ROOT = path.resolve(HERE, '../..');
+const CORE_ROOT = path.resolve(CLI_ROOT, '../core');
+
+/**
+ * An Astryx file as some other release would write it: the given text with
+ * its hash line recorded.
+ * @param {string} text
+ * @returns {string}
+ */
+function unedited(text) {
+  const hash = createHash('sha256').update(text).digest('hex');
+  return text.replace(
+    `${MARKER_START}\n`,
+    `${MARKER_START}\n<!-- astryx-managed sha256:${hash} -->\n`,
+  );
+}
+
+/** @type {string[]} */
+const dirs = [];
+/** @param {string} label */
+function tmp(label) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `astryx-user-${label}-`));
+  dirs.push(dir);
+  return dir;
+}
+
+let home = '';
+beforeEach(() => {
+  home = tmp('home');
+  vi.stubEnv('HOME', home);
+  vi.stubEnv('USERPROFILE', home);
+});
+afterEach(() => {
+  vi.unstubAllEnvs();
+  while (dirs.length) {
+    fs.rmSync(/** @type {string} */ (dirs.pop()), {
+      recursive: true,
+      force: true,
+    });
+  }
+});
+
+const FILE = () => computerSkillFile(home);
+const FOLDER = () => path.dirname(FILE());
+const CLAUDE = () => path.join(home, '.claude', 'skills', 'astryx');
+
+/** @param {string} at */
+const isLinkToFolder = at =>
+  fs.lstatSync(at).isSymbolicLink() &&
+  fs.realpathSync(at) === fs.realpathSync(FOLDER());
+
+describe('renderComputerAgentText', () => {
+  it('a skill named astryx with a one-sentence when-to-use description, in strict YAML', () => {
+    {
+      const text = renderComputerAgentText({command: 'astryx'});
+      const [, front] = text.split('---\n');
+      const meta = parseYaml(front);
+      expect(meta.name).toBe('astryx');
+      expect(meta.description).toMatch(/design system and UI library/);
+      expect(meta.description).toMatch(/building or changing UI/);
+      expect(meta.description).toMatch(/@astryxdesign/);
+      expect(
+        meta.description.split(/[.!?](\s|$)/u).filter(Boolean),
+      ).toHaveLength(1);
+      expect(text).toContain(MARKER_START);
+      expect(text).toContain(MARKER_END);
+      expect(text).toContain(
+        'Astryx, a design system and UI library, is available on this computer.',
+      );
+      expect(text).toContain(
+        'Use it when you build or change UI, pick components, or style or theme an app.',
+      );
+      expect(text).toContain("Start with `astryx search '<what you need>'`.");
+    }
+  });
+
+  it('is version-free and names only stable commands', () => {
+    {
+      const text = renderComputerAgentText({command: 'astryx'});
+      // No version string anywhere: not a release, a Node range, or a tag.
+      expect(text).not.toMatch(/\bv?\d+\.\d+(\.\d+)?\b/u);
+      expect(text).not.toMatch(/@(latest|next|canary)\b/u);
+      const commands = [...text.matchAll(/`astryx ([a-z-]+)/gu)].map(m => m[1]);
+      expect(commands.length).toBeGreaterThan(0);
+      expect(commands.filter(c => !STABLE_COMMANDS.includes(c))).toEqual([]);
+    }
+  });
+
+  it('stays short, and tells agents to read docs through the CLI', () => {
+    const text = renderComputerAgentText({command: 'astryx'});
+    expect(text.split('\n').length).toBeLessThanOrEqual(15);
+    expect(text).toContain(
+      "Then read `astryx component <Name>` or `astryx docs <topic>`, not the package's files.",
+    );
+  });
+
+  it("uses the host's door when one is set", () => {
+    const text = runWithCliDoor('acme astryx', () => renderComputerAgentText());
+    expect(text).toContain("`acme astryx search '<what you need>'`");
+    expect(text).not.toMatch(/`astryx /u);
+  });
+});
+
+describe('the link table', () => {
+  it('is data: each entry names a skills folder, the folder it needs, and link or copy; Claude Code always', () => {
+    expect(SKILL_LINKS[0]).toEqual({
+      skills: path.join('.claude', 'skills'),
+      when: null,
+      mode: 'link',
+    });
+    for (const place of SKILL_LINKS) {
+      expect(path.isAbsolute(place.skills)).toBe(false);
+      expect(place.skills.endsWith('skills')).toBe(true);
+      expect(['link', 'copy']).toContain(place.mode);
+    }
+    // Continue's scanner skips links, so it is the one copy.
+    expect(
+      SKILL_LINKS.filter(p => p.mode === 'copy').map(p => p.skills),
+    ).toEqual([path.join('.continue', 'skills')]);
+    // Never a store another tool manages.
+    for (const place of SKILL_LINKS) {
+      expect(place.skills).not.toBe(path.join('.codex', 'skills'));
+      expect(place.skills).not.toBe(path.join('.config', 'muse', 'skills'));
+    }
+    expect(computerSkillLinks(home).map(l => l.wanted)).toEqual(
+      SKILL_LINKS.map(l => l.when == null),
+    );
+  });
+});
+
+describe('links and the copy', () => {
+  it.skipIf(process.platform === 'win32')(
+    'links with a relative target',
+    () => {
+      writeComputerAgentText({home, command: 'astryx'});
+      expect(fs.readlinkSync(CLAUDE())).toBe(
+        path.join('..', '..', '.agents', 'skills', 'astryx'),
+      );
+    },
+  );
+
+  it('links ~/.config/agents/skills only when that folder already exists', () => {
+    const kimi = path.join(home, '.config', 'agents', 'skills');
+    expect(writeComputerAgentText({home, command: 'astryx'}).links).toEqual([
+      CLAUDE(),
+    ]);
+    fs.mkdirSync(kimi, {recursive: true});
+    expect(writeComputerAgentText({home, command: 'astryx'}).links).toEqual([
+      CLAUDE(),
+      path.join(kimi, 'astryx'),
+    ]);
+  });
+
+  it('writes, refreshes, and removes a managed copy for Continue, whose scanner skips links', () => {
+    fs.mkdirSync(path.join(home, '.continue'));
+    const copy = path.join(home, '.continue', 'skills', 'astryx');
+    const {rows, links} = writeComputerAgentText({home, command: 'astryx'});
+    expect(rows).toContainEqual({path: copy, action: 'written'});
+    expect(links).not.toContain(copy);
+    expect(fs.lstatSync(copy).isSymbolicLink()).toBe(false);
+    expect(fs.readFileSync(path.join(copy, 'SKILL.md'), 'utf8')).toBe(
+      fs.readFileSync(FILE(), 'utf8'),
+    );
+    expect(
+      writeComputerAgentText({home, command: 'astryx'}).rows,
+    ).toContainEqual({
+      path: copy,
+      action: 'unchanged',
+    });
+    expect(removeComputerAgentText({home, links})).toContainEqual({
+      path: copy,
+      action: 'removed',
+    });
+    expect(fs.existsSync(copy)).toBe(false);
+  });
+
+  it.skipIf(process.platform === 'win32')(
+    'links from a ~/.claude that is itself a link to a dotfiles folder, with a target that resolves',
+    () => {
+      const dotfiles = path.join(home, 'dotfiles', '.claude');
+      fs.mkdirSync(dotfiles, {recursive: true});
+      fs.symlinkSync(dotfiles, path.join(home, '.claude'), 'dir');
+
+      const {rows, links} = writeComputerAgentText({home, command: 'astryx'});
+
+      expect(rows).toContainEqual({path: CLAUDE(), action: 'linked'});
+      // The system resolves the link from the dotfiles folder, and it reaches
+      // the skill folder.
+      expect(isLinkToFolder(CLAUDE())).toBe(true);
+      expect(fs.readFileSync(path.join(CLAUDE(), 'SKILL.md'), 'utf8')).toBe(
+        fs.readFileSync(FILE(), 'utf8'),
+      );
+      expect(
+        inspectComputerAgentText({home, command: 'astryx', links}),
+      ).toContainEqual({
+        path: CLAUDE(),
+        state: 'linked',
+        link: true,
+      });
+    },
+  );
+
+  it.skipIf(process.platform === 'win32')(
+    'reports a link the system cannot follow as dangling, even when its text names the folder from the path',
+    () => {
+      const dotfiles = path.join(home, 'dotfiles', '.claude');
+      fs.mkdirSync(path.join(dotfiles, 'skills'), {recursive: true});
+      fs.symlinkSync(dotfiles, path.join(home, '.claude'), 'dir');
+      writeComputerAgentText({home, command: 'astryx'});
+      // A link as 0.7.x wrote it: relative to ~/.claude/skills, which the
+      // system reads from ~/dotfiles/.claude/skills, so it dangles.
+      fs.rmSync(CLAUDE());
+      fs.symlinkSync(
+        path.relative(path.dirname(CLAUDE()), FOLDER()),
+        CLAUDE(),
+        'dir',
+      );
+      expect(fs.existsSync(path.join(CLAUDE(), 'SKILL.md'))).toBe(false);
+
+      const rows = inspectComputerAgentText({
+        home,
+        command: 'astryx',
+        links: [CLAUDE()],
+      });
+      expect(rows.find(row => row.path === CLAUDE())?.state).toBe('dangling');
+      // init --user remakes it so that it resolves.
+      expect(
+        writeComputerAgentText({home, command: 'astryx'}).rows,
+      ).toContainEqual({
+        path: CLAUDE(),
+        action: 'linked',
+      });
+      expect(isLinkToFolder(CLAUDE())).toBe(true);
+    },
+  );
+
+  it.skipIf(process.platform === 'win32')(
+    'writes the managed copy into a ~/.continue that is itself a link',
+    () => {
+      const real = path.join(home, 'dotfiles', '.continue');
+      fs.mkdirSync(real, {recursive: true});
+      fs.symlinkSync(real, path.join(home, '.continue'), 'dir');
+      const copy = path.join(home, '.continue', 'skills', 'astryx');
+
+      const {rows} = writeComputerAgentText({home, command: 'astryx'});
+
+      expect(rows).toContainEqual({path: copy, action: 'written'});
+      expect(
+        fs.readFileSync(
+          path.join(real, 'skills', 'astryx', 'SKILL.md'),
+          'utf8',
+        ),
+      ).toBe(fs.readFileSync(FILE(), 'utf8'));
+    },
+  );
+
+  it('reports a link whose folder is missing as dangling', () => {
+    const {links} = writeComputerAgentText({home, command: 'astryx'});
+    fs.rmSync(FOLDER(), {recursive: true});
+    expect(inspectComputerAgentText({home, command: 'astryx', links})).toEqual([
+      {path: FILE(), state: 'absent'},
+      {path: CLAUDE(), state: 'dangling', link: true},
+    ]);
+  });
+});
+
+describe('write, refresh, keep, remove', () => {
+  it('writes one file, links Claude Code to its folder, then reports both unchanged', () => {
+    const first = writeComputerAgentText({home, command: 'astryx'});
+    expect(first.rows).toEqual([
+      {path: FILE(), action: 'written'},
+      {path: CLAUDE(), action: 'linked'},
+    ]);
+    expect(first.links).toEqual([CLAUDE()]);
+    expect(isLinkToFolder(CLAUDE())).toBe(true);
+    // An agent reading the linked folder reads the one file.
+    expect(fs.readFileSync(path.join(CLAUDE(), 'SKILL.md'), 'utf8')).toBe(
+      fs.readFileSync(FILE(), 'utf8'),
+    );
+    expect(writeComputerAgentText({home, command: 'astryx'}).rows).toEqual([
+      {path: FILE(), action: 'unchanged'},
+      {path: CLAUDE(), action: 'unchanged'},
+    ]);
+  });
+
+  it("links another agent's folder only when that agent's folder exists", () => {
+    fs.mkdirSync(path.join(home, '.kiro'));
+    const {links} = writeComputerAgentText({home, command: 'astryx'});
+    expect(links).toEqual([
+      CLAUDE(),
+      path.join(home, '.kiro', 'skills', 'astryx'),
+    ]);
+    expect(fs.existsSync(path.join(home, '.continue'))).toBe(false);
+  });
+
+  it('refreshes only the file; the links follow', () => {
+    writeComputerAgentText({home, command: 'astryx'});
+    fs.writeFileSync(
+      FILE(),
+      unedited(
+        `---\nname: astryx\n---\n\n${MARKER_START}\nold\n${MARKER_END}\n`,
+      ),
+    );
+    expect(inspectComputerAgentText({home, command: 'astryx'})[0].state).toBe(
+      'differs',
+    );
+    expect(writeComputerAgentText({home, command: 'astryx'}).rows).toEqual([
+      {path: FILE(), action: 'written'},
+      {path: CLAUDE(), action: 'unchanged'},
+    ]);
+    expect(fs.readFileSync(path.join(CLAUDE(), 'SKILL.md'), 'utf8')).toBe(
+      renderComputerAgentText({command: 'astryx'}),
+    );
+  });
+
+  it('keeps an edited file, a file without the markers, and anything at a link target Astryx did not create', () => {
+    fs.mkdirSync(FOLDER(), {recursive: true});
+    fs.writeFileSync(FILE(), 'my own notes\n');
+    fs.mkdirSync(CLAUDE(), {recursive: true});
+    fs.writeFileSync(path.join(CLAUDE(), 'SKILL.md'), 'my own skill\n');
+    const {rows, links} = writeComputerAgentText({home, command: 'astryx'});
+    expect(rows).toEqual([
+      {path: FILE(), action: 'kept', reason: 'not-astryx'},
+      {path: CLAUDE(), action: 'kept', reason: 'not-astryx'},
+    ]);
+    expect(links).toEqual([]);
+    expect(fs.readFileSync(FILE(), 'utf8')).toBe('my own notes\n');
+    expect(
+      inspectComputerAgentText({home, command: 'astryx'}).map(e => e.state),
+    ).toEqual(['foreign', 'foreign']);
+
+    fs.writeFileSync(
+      FILE(),
+      `${renderComputerAgentText({command: 'astryx'})}edit\n`,
+    );
+    expect(writeComputerAgentText({home, command: 'astryx'}).rows[0]).toEqual({
+      path: FILE(),
+      action: 'kept',
+      reason: 'edited',
+    });
+  });
+
+  it('keeps a link that points somewhere else', () => {
+    const elsewhere = tmp('elsewhere');
+    fs.mkdirSync(path.dirname(CLAUDE()), {recursive: true});
+    fs.symlinkSync(elsewhere, CLAUDE(), 'dir');
+    const {rows} = writeComputerAgentText({home, command: 'astryx'});
+    expect(rows[1]).toEqual({
+      path: CLAUDE(),
+      action: 'kept',
+      reason: 'not-astryx',
+    });
+    expect(fs.realpathSync(CLAUDE())).toBe(fs.realpathSync(elsewhere));
+  });
+
+  it('replaces an unedited copy an earlier release left at a link target with the link', () => {
+    fs.mkdirSync(CLAUDE(), {recursive: true});
+    fs.writeFileSync(
+      path.join(CLAUDE(), 'SKILL.md'),
+      unedited(
+        `---\nname: astryx\n---\n\n${MARKER_START}\nold\n${MARKER_END}\n`,
+      ),
+    );
+    expect(writeComputerAgentText({home, command: 'astryx'}).rows[1]).toEqual({
+      path: CLAUDE(),
+      action: 'linked',
+    });
+    expect(isLinkToFolder(CLAUDE())).toBe(true);
+  });
+
+  it('removes the file and exactly the links it made, then reports the file absent', () => {
+    const {links} = writeComputerAgentText({home, command: 'astryx'});
+    // A link someone else made to the same folder is not Astryx's to remove.
+    const theirs = path.join(home, 'mine', 'astryx');
+    fs.mkdirSync(path.dirname(theirs), {recursive: true});
+    fs.symlinkSync(FOLDER(), theirs, 'dir');
+    expect(removeComputerAgentText({home, links})).toEqual([
+      {path: FILE(), action: 'removed'},
+      {path: CLAUDE(), action: 'removed'},
+    ]);
+    expect(fs.existsSync(CLAUDE())).toBe(false);
+    expect(fs.existsSync(FOLDER())).toBe(false);
+    expect(fs.lstatSync(theirs).isSymbolicLink()).toBe(true);
+    expect(removeComputerAgentText({home, links: []})).toEqual([
+      {path: FILE(), action: 'absent'},
+    ]);
+  });
+
+  it('keeps an edited file on remove, and a recorded link someone repointed', () => {
+    const {links} = writeComputerAgentText({home, command: 'astryx'});
+    fs.unlinkSync(CLAUDE());
+    fs.symlinkSync(tmp('other'), CLAUDE(), 'dir');
+    fs.appendFileSync(FILE(), 'edit\n');
+    expect(removeComputerAgentText({home, links})).toEqual([
+      {path: FILE(), action: 'kept', reason: 'edited'},
+    ]);
+    expect(fs.existsSync(FILE())).toBe(true);
+    expect(fs.lstatSync(CLAUDE()).isSymbolicLink()).toBe(true);
+  });
+});
+
+describe.skipIf(process.platform === 'win32')('astryxOnSearchPath', () => {
+  /** @param {string} file @param {string} content */
+  function executable(file, content) {
+    fs.mkdirSync(path.dirname(file), {recursive: true});
+    fs.writeFileSync(file, content);
+    fs.chmodSync(file, 0o755);
+  }
+
+  /** A global prefix with the CLI package linked into its bin folder. */
+  function linkedCli() {
+    const prefix = tmp('prefix');
+    const pkg = path.join(
+      prefix,
+      'lib',
+      'node_modules',
+      '@astryxdesign',
+      'cli',
+    );
+    fs.mkdirSync(pkg, {recursive: true});
+    fs.writeFileSync(
+      path.join(pkg, 'package.json'),
+      '{"name":"@astryxdesign/cli","version":"0.0.0"}',
+    );
+    executable(path.join(pkg, 'bin.mjs'), '#!/usr/bin/env node\n');
+    fs.mkdirSync(path.join(prefix, 'bin'));
+    fs.symlinkSync(
+      path.join(pkg, 'bin.mjs'),
+      path.join(prefix, 'bin', 'astryx'),
+    );
+    return path.join(prefix, 'bin');
+  }
+
+  it('finds a linked CLI', () => {
+    expect(
+      astryxOnSearchPath({searchPath: linkedCli(), platform: 'linux'}),
+    ).toBe(true);
+  });
+
+  it("finds a package manager's shim that starts the CLI", () => {
+    const bin = tmp('shim');
+    executable(
+      path.join(bin, 'astryx'),
+      '#!/bin/sh\nexec node "$basedir/global/5/node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs" "$@"\n',
+    );
+    expect(astryxOnSearchPath({searchPath: bin, platform: 'linux'})).toBe(true);
+  });
+
+  it('is false with no astryx, or when the first astryx is another program', () => {
+    expect(
+      astryxOnSearchPath({searchPath: tmp('empty'), platform: 'linux'}),
+    ).toBe(false);
+    const other = tmp('other');
+    executable(path.join(other, 'astryx'), '#!/bin/sh\necho other\n');
+    expect(
+      astryxOnSearchPath({
+        searchPath: [other, linkedCli()].join(path.delimiter),
+        platform: 'linux',
+      }),
+    ).toBe(false);
+  });
+
+  it('skips a file that cannot run', () => {
+    const bin = tmp('noexec');
+    fs.writeFileSync(path.join(bin, 'astryx'), 'not a program');
+    expect(
+      astryxOnSearchPath({
+        searchPath: [bin, linkedCli()].join(path.delimiter),
+        platform: 'linux',
+      }),
+    ).toBe(true);
+  });
+});
+
+describe('only `init --user` writes the computer-level text (FR7)', () => {
+  /** @returns {string[]} the skill paths present in the temp home */
+  const present = () =>
+    [
+      computerSkillFile(home),
+      path.join(home, '.claude', 'skills', 'astryx'),
+    ].filter(p => fs.existsSync(p));
+
+  /** A project that installs this release's Core. */
+  function project() {
+    const dir = tmp('project');
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      JSON.stringify({
+        name: 'app',
+        private: true,
+        dependencies: {'@astryxdesign/core': '*'},
+      }),
+    );
+    fs.mkdirSync(path.join(dir, 'node_modules', '@astryxdesign'), {
+      recursive: true,
+    });
+    fs.symlinkSync(
+      CORE_ROOT,
+      path.join(dir, 'node_modules', '@astryxdesign', 'core'),
+      'dir',
+    );
+    return dir;
+  }
+
+  it('no source outside init --user (its adapter) and the background step imports the write or remove functions', () => {
+    /** @type {string[]} */
+    const importers = [];
+    /** @param {string} dir */
+    const walk = dir => {
+      for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+        if (entry.name === 'node_modules' || entry.name.startsWith('.'))
+          continue;
+        const file = path.join(dir, entry.name);
+        if (entry.isDirectory()) walk(file);
+        else if (
+          /\.m?[jt]s$/.test(entry.name) &&
+          !/\.test\.m?[jt]s$/.test(entry.name) &&
+          // Generated declarations (sync:api-types) import nothing.
+          !/\.d\.m?ts$/.test(entry.name)
+        ) {
+          const text = fs.readFileSync(file, 'utf8');
+          if (
+            /\b(writeComputerAgentText|removeComputerAgentText)\b/.test(text)
+          ) {
+            importers.push(path.relative(CLI_ROOT, file));
+          }
+        }
+      }
+    };
+    for (const top of [
+      'api',
+      'clients',
+      'foundation',
+      'scripts',
+      'authoring',
+    ]) {
+      walk(path.join(CLI_ROOT, top));
+    }
+    expect(importers.sort()).toEqual(
+      [
+        path.join('api', 'init', '_adapter.mjs'),
+        path.join('foundation', 'agent-docs', 'computer-agent-text.mjs'),
+        path.join('foundation', 'release', 'agent-text-worker.mjs'),
+      ].sort(),
+    );
+  });
+
+  it('install (postinstall), project init, and upgrade write none of it', async () => {
+    const dir = project();
+    const postinstall = spawnSync(
+      process.execPath,
+      [path.join(CLI_ROOT, 'scripts', 'postinstall.mjs')],
+      {
+        env: {...process.env, HOME: home, USERPROFILE: home, INIT_CWD: dir},
+        encoding: 'utf8',
+      },
+    );
+    expect(postinstall.status).toBe(0);
+    expect((await runCli(['--json', 'init'], dir)).status).toBe(0);
+    expect((await runCli(['--json', 'init', '--all'], dir)).status).toBe(0);
+    await runCli(['--json', 'upgrade'], dir);
+    await runCli(['--json', 'init'], tmp('outside'));
+    expect(present()).toEqual([]);
+    expect(fs.existsSync(path.join(home, '.agents'))).toBe(false);
+    expect(fs.existsSync(path.join(home, '.claude'))).toBe(false);
+  }, 60_000);
+});

package/foundation/config/project.d.mts

@@ -1,6 +1,24 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * 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?: string): import("../integrations/computer-integrations.mjs").ComputerIntegrationCandidate[];
+/**
+ * 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 function availableComputerIntegrations(cwd: string, installed: Set<string>): Promise<import("../integrations/computer-integrations.mjs").ComputerIntegrationCandidate[]>;
 /**
  * Find astryx.config.{ts,mjs,js} as a sibling of the nearest package.json.
  * Returns the absolute path, or null if none is present. Throws if multiple
@@ -37,13 +55,18 @@ 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 load(cwd?: string, { cache, fresh }?: {
+    static load(cwd?: string, { cache, fresh, core }?: {
         cache?: import("./config-cache.mjs").ConfigCache;
         fresh?: boolean;
+        core?: "any" | "project";
     }): Promise<Project>;
     /**
      * @param {object} init
@@ -54,8 +77,9 @@ 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, configPath, config, integrations, loadedIntegrations, cache, hash, }: {
+    constructor({ cwd, configPath, config, integrations, loadedIntegrations, cache, hash, core, }: {
         cwd: string;
         configPath: string | null;
         config: import("../../authoring/config/type").AstryxConfig;
@@ -63,6 +87,7 @@ export class Project {
         loadedIntegrations: import("../integrations/integrations.mjs").LoadedIntegration[];
         cache: import("./config-cache.mjs").ConfigCache;
         hash: string;
+        core?: "project" | "any" | undefined;
     });
     /**
      * The validated config surface (same data loadConfig returned, minus the
@@ -92,6 +117,13 @@ export class Project {
      * @returns {string|null}
      */
     get configPath(): string | null;
+    /**
+     * 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(): string | null;
     /**
      * Core + integration component ownership records. Wraps
      * discoverOwnedComponents for core and discoverIntegrationComponents (via