@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/foundation/release/project.test.mjs

@@ -0,0 +1,288 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  findDeclaringPackage,
+  findLockfile,
+  findProjectCli,
+  findReadCore,
+  lockedVersion,
+  readReleaseFacts,
+} from './project.mjs';
+import {
+  cleanupFixtures,
+  installCore,
+  installStandInCli,
+  project,
+  tempDir,
+  writeJson,
+} from '../../test-utils/release-fixtures.mjs';
+
+afterEach(cleanupFixtures);
+
+describe('findReadCore', () => {
+  it('finds the installed Core in the folder or up to four above it, and from the declaring package.json at any depth (b30)', () => {
+    const root = project(tempDir(), {'@astryxdesign/core': '0.6.8'});
+    installCore(root, '0.6.8');
+    const deep = path.join(root, 'a', 'b', 'c', 'd');
+    fs.mkdirSync(deep, {recursive: true});
+    expect(findReadCore(deep)?.version).toBe('0.6.8');
+    const tooDeep = path.join(deep, 'e', 'f', 'g');
+    fs.mkdirSync(tooDeep, {recursive: true});
+    expect(findReadCore(tooDeep)?.version).toBe('0.6.8');
+    // With no package.json that declares Astryx, the reach stays four folders.
+    const plain = tempDir();
+    writeJson(path.join(plain, 'package.json'), {name: 'plain'});
+    installCore(plain, '0.6.8');
+    const plainDeep = path.join(plain, 'a', 'b', 'c', 'd', 'e');
+    fs.mkdirSync(plainDeep, {recursive: true});
+    expect(findReadCore(plainDeep)).toBeNull();
+  });
+
+  it("skips a workspace's packages/core that is another package", () => {
+    const root = tempDir();
+    writeJson(path.join(root, 'packages', 'core', 'package.json'), {
+      name: '@acme/core',
+      version: '1.0.0',
+    });
+    installCore(root, '0.7.1');
+    expect(findReadCore(root)?.version).toBe('0.7.1');
+  });
+
+  it("takes a workspace's own CLI package, at the root and inside it (b13)", () => {
+    const root = tempDir();
+    writeJson(path.join(root, 'package.json'), {name: 'repo', private: true});
+    writeJson(path.join(root, 'packages', 'core', 'package.json'), {
+      name: '@astryxdesign/core',
+      version: '0.7.4',
+    });
+    writeJson(path.join(root, 'packages', 'cli', 'package.json'), {
+      name: '@astryxdesign/cli',
+      version: '0.7.4',
+    });
+    const cliDir = path.join(root, 'packages', 'cli');
+    for (const dir of [root, cliDir, path.join(root, 'apps', 'site')]) {
+      fs.mkdirSync(dir, {recursive: true});
+      expect(findProjectCli(dir)).toEqual({dir: cliDir, version: '0.7.4'});
+    }
+    writeJson(path.join(root, 'packages', 'cli', 'package.json'), {
+      name: 'some-other-cli',
+      version: '1.0.0',
+    });
+    expect(findProjectCli(root)).toBeNull();
+  });
+
+  it("takes a workspace's own Core package", () => {
+    const root = tempDir();
+    writeJson(path.join(root, 'packages', 'core', 'package.json'), {
+      name: '@astryxdesign/core',
+      version: '0.7.2',
+    });
+    expect(findReadCore(root)?.dir).toBe(path.join(root, 'packages', 'core'));
+  });
+});
+
+describe('findDeclaringPackage', () => {
+  it('finds the nearest package.json that declares Core or the CLI', () => {
+    const root = project(tempDir(), {'@astryxdesign/core': '^0.6.8'});
+    const nested = path.join(root, 'tools', 'pkg');
+    writeJson(path.join(nested, 'package.json'), {
+      name: 'pkg',
+      dependencies: {'left-pad': '1'},
+    });
+    expect(findDeclaringPackage(nested)).toEqual({
+      dir: root,
+      core: '^0.6.8',
+      cli: null,
+    });
+  });
+
+  it('stops at the first folder with version-control metadata', () => {
+    const root = project(tempDir(), {'@astryxdesign/core': '0.6.8'});
+    const clone = path.join(root, 'vendor', 'repo');
+    fs.mkdirSync(path.join(clone, '.git'), {recursive: true});
+    expect(findDeclaringPackage(path.join(clone))).toBeNull();
+  });
+
+  it('reads peer and dev dependencies too', () => {
+    const root = tempDir();
+    writeJson(path.join(root, 'package.json'), {
+      name: 'lib',
+      peerDependencies: {'@astryxdesign/core': '>=0.7.0'},
+      devDependencies: {'@astryxdesign/cli': '0.7.1'},
+    });
+    expect(findDeclaringPackage(root)).toEqual({
+      dir: root,
+      core: '>=0.7.0',
+      cli: '0.7.1',
+    });
+  });
+});
+
+describe('lockedVersion', () => {
+  it('reads an npm lockfile, member entry first', () => {
+    const root = tempDir();
+    writeJson(path.join(root, 'package-lock.json'), {
+      lockfileVersion: 3,
+      packages: {
+        'node_modules/@astryxdesign/core': {version: '0.7.1'},
+        'apps/legacy/node_modules/@astryxdesign/core': {version: '0.6.8'},
+      },
+    });
+    const lock = path.join(root, 'package-lock.json');
+    expect(lockedVersion(lock, root, '@astryxdesign/core', '0.7.1')).toBe(
+      '0.7.1',
+    );
+    expect(
+      lockedVersion(
+        lock,
+        path.join(root, 'apps', 'legacy'),
+        '@astryxdesign/core',
+        '0.6.8',
+      ),
+    ).toBe('0.6.8');
+  });
+
+  it('reads a pnpm lockfile importer, dropping the peer suffix', () => {
+    const root = tempDir();
+    const lock = path.join(root, 'pnpm-lock.yaml');
+    fs.writeFileSync(
+      lock,
+      [
+        "lockfileVersion: '9.0'",
+        '',
+        'importers:',
+        '',
+        '  .:',
+        '    dependencies:',
+        "      '@astryxdesign/core':",
+        '        specifier: ^0.6.8',
+        '        version: 0.6.8(react@19.0.0)',
+        '',
+        '  apps/web:',
+        '    dependencies:',
+        "      '@astryxdesign/core':",
+        '        specifier: 0.7.1',
+        '        version: 0.7.1',
+        '',
+        'packages:',
+        '',
+      ].join('\n'),
+    );
+    expect(lockedVersion(lock, root, '@astryxdesign/core', '^0.6.8')).toBe(
+      '0.6.8',
+    );
+    expect(
+      lockedVersion(
+        lock,
+        path.join(root, 'apps', 'web'),
+        '@astryxdesign/core',
+        '0.7.1',
+      ),
+    ).toBe('0.7.1');
+  });
+
+  it('reads classic and Berry yarn lockfiles by the declared range', () => {
+    const root = tempDir();
+    const classic = path.join(root, 'yarn.lock');
+    fs.writeFileSync(
+      classic,
+      [
+        '# yarn lockfile v1',
+        '',
+        '"@astryxdesign/core@^0.6.0":',
+        '  version "0.6.8"',
+        '',
+        '"@astryxdesign/core@0.7.1":',
+        '  version "0.7.1"',
+        '',
+      ].join('\n'),
+    );
+    expect(lockedVersion(classic, root, '@astryxdesign/core', '^0.6.0')).toBe(
+      '0.6.8',
+    );
+    const berryDir = tempDir();
+    const berry = path.join(berryDir, 'yarn.lock');
+    fs.writeFileSync(
+      berry,
+      [
+        '__metadata:',
+        '  version: 8',
+        '',
+        '"@astryxdesign/core@npm:^0.6.8":',
+        '  version: 0.6.8',
+        '  resolution: "@astryxdesign/core@npm:0.6.8"',
+        '',
+      ].join('\n'),
+    );
+    expect(lockedVersion(berry, berryDir, '@astryxdesign/core', '^0.6.8')).toBe(
+      '0.6.8',
+    );
+  });
+
+  it('reads a bun lockfile', () => {
+    const root = tempDir();
+    const lock = path.join(root, 'bun.lock');
+    fs.writeFileSync(
+      lock,
+      '{\n  "lockfileVersion": 1,\n  "packages": {\n    "@astryxdesign/core": ["@astryxdesign/core@0.6.8", "", {}, "sha512-x"],\n  },\n}\n',
+    );
+    expect(lockedVersion(lock, root, '@astryxdesign/core', '^0.6.0')).toBe(
+      '0.6.8',
+    );
+  });
+
+  it('finds the lockfile above a workspace member', () => {
+    const root = tempDir();
+    fs.writeFileSync(
+      path.join(root, 'pnpm-lock.yaml'),
+      "lockfileVersion: '9.0'\n",
+    );
+    const member = path.join(root, 'apps', 'web');
+    fs.mkdirSync(member, {recursive: true});
+    expect(findLockfile(member)).toBe(path.join(root, 'pnpm-lock.yaml'));
+  });
+});
+
+describe('readReleaseFacts', () => {
+  it('reports a fresh clone from its package.json and lockfile', () => {
+    const root = project(tempDir(), {
+      '@astryxdesign/core': '^0.6.0',
+      '@astryxdesign/cli': '^0.6.0',
+    });
+    writeJson(path.join(root, 'package-lock.json'), {
+      lockfileVersion: 3,
+      packages: {
+        'node_modules/@astryxdesign/core': {version: '0.6.8'},
+        'node_modules/@astryxdesign/cli': {version: '0.6.8'},
+      },
+    });
+    expect(readReleaseFacts(root)).toMatchObject({
+      inProject: true,
+      core: null,
+      cli: null,
+      lockedCoreVersion: '0.6.8',
+      lockedCliVersion: '0.6.8',
+    });
+  });
+
+  it('reports the installed Core and CLI', () => {
+    const root = project(tempDir(), {'@astryxdesign/core': '0.7.1'});
+    installCore(root, '0.7.1');
+    installStandInCli(root, '0.6.8');
+    const facts = readReleaseFacts(root);
+    expect(facts.core?.version).toBe('0.7.1');
+    expect(facts.cli?.version).toBe('0.6.8');
+  });
+
+  it('reports a folder with no Astryx as outside a project', () => {
+    const root = tempDir();
+    writeJson(path.join(root, 'package.json'), {
+      name: 'x',
+      dependencies: {react: '19'},
+    });
+    expect(readReleaseFacts(root).inProject).toBe(false);
+  });
+});

package/foundation/release/refresh-worker.d.mts

@@ -0,0 +1,4 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+export {};

package/foundation/release/refresh-worker.mjs

@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The background update check, as its own detached process.
+ *
+ * Started by `maybeStartCheck` (global-state.mjs) with one argument, the
+ * per-user configuration folder. It writes nothing to any stream and never
+ * reaches a person: it is not a command and takes no options. Its whole job
+ * is `runCheck`, which asks the registry for the newest release and installs
+ * nothing.
+ *
+ * @input  argv[2]: the per-user configuration folder
+ * @output the updated state on disk
+ * @position foundation/release — one of the two detached processes the CLI
+ *   starts; the other is agent-text-worker.mjs.
+ */
+
+import {runCheck} from './global-state.mjs';
+
+const stateDir = process.argv[2];
+if (stateDir) {
+  try {
+    runCheck({stateDir});
+  } catch {
+    // A failed check changes nothing.
+  }
+}

package/foundation/release/run-context.d.mts

@@ -0,0 +1,47 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Record the bin's choice for this process.
+ * @param {import('./choose.mjs').ReleaseChoice} choice
+ */
+export function recordRunChoice(choice: import("./choose.mjs").ReleaseChoice): void;
+/**
+ * The choice that applies to `cwd`: the bin's, else one made now.
+ * @param {string} [cwd]
+ * @returns {import('./choose.mjs').ReleaseChoice}
+ */
+export function runChoice(cwd?: string): import("./choose.mjs").ReleaseChoice;
+/** The running CLI's version. */
+export function cliVersion(): string;
+/**
+ * The Core a copy carries: the `@astryxdesign/core` of its own release, beside
+ * the CLI package (a release in the cache, or a package runner that fetched
+ * both), else the cached release of the same version. With `fetch`, a copy
+ * that carries none installs its release into the cache first.
+ *
+ * @param {{fetch?: boolean, cacheDir?: string}} [options]
+ * @returns {{dir: string | null, unavailable: string | null, version?: string, reason?: string}}
+ */
+export function carriedCore(options?: {
+    fetch?: boolean;
+    cacheDir?: string;
+}): {
+    dir: string | null;
+    unavailable: string | null;
+    version?: string;
+    reason?: string;
+};
+/**
+ * `meta.answeredBy` for this run: the answering CLI's version, the Core the
+ * run pairs with (`null` when there is none), and which copy answered.
+ * @param {string} [cwd]
+ * @returns {{cli: string, core: string | null, copy: 'project' | 'starting' | 'matched' | 'carried' | 'fallback'}}
+ */
+export function answeredBy(cwd?: string): {
+    cli: string;
+    core: string | null;
+    copy: "project" | "starting" | "matched" | "carried" | "fallback";
+};
+/** Exported for tests: forget the recorded choice. */
+export function _resetRunChoice(): void;

package/foundation/release/run-context.mjs

@@ -0,0 +1,149 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Who answered this run: the record behind `meta.answeredBy` and the
+ * Core a copy carries for use outside a project (spec AST-081 FR3, FR5).
+ *
+ * The bin records the choice it made (handoff.mjs) before any command runs.
+ * A caller that drives the CLI in-process, such as the test harness or the
+ * programmatic API, never went through the bin, so the choice is made here on
+ * first use from the working folder, without asking the registry.
+ *
+ * @input  the bin's choice, or the working folder
+ * @output `{cli, core, copy}`; the carried Core's folder
+ * @position foundation/release — read by jsonOut and by the Core lookups of
+ *   commands that answer from Core outside a project.
+ */
+
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {chooseRelease, isComputerLevel, runningCopy} from './choose.mjs';
+import {progressLine} from './handoff.mjs';
+import {isJsonMode} from '../response/json.mjs';
+import {cachedRelease, ensureRelease, userCacheDir} from './cache.mjs';
+import {readJson, findReadCore, CORE_PACKAGE_NAME} from './project.mjs';
+
+/** The running CLI package's folder. */
+const CLI_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+);
+
+/** @type {import('./choose.mjs').ReleaseChoice | null} */
+let recorded = null;
+/** @type {string | null} */
+let recordedFor = null;
+
+/**
+ * Record the bin's choice for this process.
+ * @param {import('./choose.mjs').ReleaseChoice} choice
+ */
+export function recordRunChoice(choice) {
+  recorded = choice;
+  recordedFor = process.cwd();
+}
+
+/**
+ * The choice that applies to `cwd`: the bin's, else one made now.
+ * @param {string} [cwd]
+ * @returns {import('./choose.mjs').ReleaseChoice}
+ */
+export function runChoice(cwd = process.cwd()) {
+  if (recorded && recordedFor === path.resolve(cwd)) return recorded;
+  try {
+    const self = runningCopy(CLI_ROOT);
+    const choice = chooseRelease({
+      cwd,
+      self,
+      resolve: () => null,
+      computer: isComputerLevel(process.argv.slice(2)),
+    });
+    if (choice.answer === 'self') return choice;
+    // Driven in-process (the programmatic API, a test harness), nothing hands
+    // the run off: this copy answers, as the copy that started the run.
+    return {
+      ...choice,
+      copy: choice.inProject ? 'starting' : 'carried',
+      answer: 'self',
+      version: self.version,
+      bin: null,
+      unavailable: null,
+    };
+  } catch {
+    return {
+      copy: 'carried',
+      answer: 'self',
+      version: runningCopy(CLI_ROOT).version,
+      bin: null,
+      coreVersion: null,
+      inProject: false,
+      unavailable: null,
+    };
+  }
+}
+
+/** The running CLI's version. */
+export function cliVersion() {
+  return runningCopy(CLI_ROOT).version;
+}
+
+/**
+ * The Core a copy carries: the `@astryxdesign/core` of its own release, beside
+ * the CLI package (a release in the cache, or a package runner that fetched
+ * both), else the cached release of the same version. With `fetch`, a copy
+ * that carries none installs its release into the cache first.
+ *
+ * @param {{fetch?: boolean, cacheDir?: string}} [options]
+ * @returns {{dir: string | null, unavailable: string | null, version?: string, reason?: string}}
+ */
+export function carriedCore(options = {}) {
+  const {fetch = false, cacheDir = userCacheDir()} = options;
+  const version = cliVersion();
+  const beside = path.resolve(CLI_ROOT, '..', 'core');
+  const besidePkg = readJson(path.join(beside, 'package.json'));
+  if (besidePkg?.name === CORE_PACKAGE_NAME && besidePkg.version === version) {
+    return {dir: beside, unavailable: null};
+  }
+  const cached = cachedRelease(version, cacheDir);
+  if (cached) return {dir: cached.coreDir, unavailable: null};
+  if (!fetch) return {dir: null, unavailable: null};
+  const json = isJsonMode() || process.argv.includes('--json');
+  const release = ensureRelease(version, {
+    cacheDir,
+    onProgress: json ? undefined : progressLine,
+  });
+  return 'coreDir' in release
+    ? {dir: release.coreDir, unavailable: null}
+    : {
+        dir: null,
+        unavailable: `Core ${version} could not be installed: ${release.reason}`,
+        version,
+        reason: release.reason,
+      };
+}
+
+/**
+ * `meta.answeredBy` for this run: the answering CLI's version, the Core the
+ * run pairs with (`null` when there is none), and which copy answered.
+ * @param {string} [cwd]
+ * @returns {{cli: string, core: string | null, copy: 'project' | 'starting' | 'matched' | 'carried' | 'fallback'}}
+ */
+export function answeredBy(cwd = process.cwd()) {
+  const choice = runChoice(cwd);
+  const read = findReadCore(cwd);
+  let core = read ? read.version : null;
+  if (!core && choice.copy !== 'project') {
+    const carried = carriedCore();
+    core = carried.dir
+      ? (readJson(path.join(carried.dir, 'package.json'))?.version ?? null)
+      : null;
+  }
+  return {cli: cliVersion(), core, copy: choice.copy};
+}
+
+/** Exported for tests: forget the recorded choice. */
+export function _resetRunChoice() {
+  recorded = null;
+  recordedFor = null;
+}

package/foundation/release/update-notice-env.d.mts

@@ -0,0 +1,28 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file When the environment turns update notices off (spec AST-081 FR6,
+ * FR10): the standard `CI` variable, which continuous integration services
+ * set, and `NO_UPDATE_NOTIFIER`, the variable command-line tools share to
+ * silence update notices (update-notifier, the Vercel CLI). Astryx defines
+ * neither; it reads each for its shared meaning only (`spec:AST-017` FR14).
+ *
+ * @input  the environment
+ * @output whether to skip the update check and every update notice
+ * @position foundation/release — read by global-state.mjs and notices.mjs.
+ */
+/**
+ * Whether `CI` is set to a value that means yes: present, and not empty,
+ * `0`, or `false`, as continuous integration detection usually reads it.
+ * @param {Record<string, string | undefined>} env
+ * @returns {boolean}
+ */
+export function isCi(env: Record<string, string | undefined>): boolean;
+/**
+ * Whether update checks and notices are off in this environment: in
+ * continuous integration, or with `NO_UPDATE_NOTIFIER` set to any value.
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {boolean}
+ */
+export function updateNoticesOff(env?: Record<string, string | undefined>): boolean;

package/foundation/release/update-notice-env.mjs

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file When the environment turns update notices off (spec AST-081 FR6,
+ * FR10): the standard `CI` variable, which continuous integration services
+ * set, and `NO_UPDATE_NOTIFIER`, the variable command-line tools share to
+ * silence update notices (update-notifier, the Vercel CLI). Astryx defines
+ * neither; it reads each for its shared meaning only (`spec:AST-017` FR14).
+ *
+ * @input  the environment
+ * @output whether to skip the update check and every update notice
+ * @position foundation/release — read by global-state.mjs and notices.mjs.
+ */
+
+/**
+ * Whether `CI` is set to a value that means yes: present, and not empty,
+ * `0`, or `false`, as continuous integration detection usually reads it.
+ * @param {Record<string, string | undefined>} env
+ * @returns {boolean}
+ */
+export function isCi(env) {
+  const value = env.CI;
+  return (
+    value !== undefined &&
+    value !== '' &&
+    value !== '0' &&
+    value.toLowerCase() !== 'false'
+  );
+}
+
+/**
+ * Whether update checks and notices are off in this environment: in
+ * continuous integration, or with `NO_UPDATE_NOTIFIER` set to any value.
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {boolean}
+ */
+export function updateNoticesOff(env = process.env) {
+  return isCi(env) || env.NO_UPDATE_NOTIFIER !== undefined;
+}

package/foundation/response/base.d.ts

@@ -45,8 +45,9 @@ export interface CLIUnsupportedError {
 
 /**
  * A success response: a `type` discriminator, the `package` that owns what the
- * response is about, its `data` payload, and an optional `meta` sidecar
- * (emitted as a sibling of `data`, never merged in). `--json` prints it with
+ * response is about, its `data` payload, and an optional `meta` object
+ * (emitted as a sibling of `data`, never merged in) that carries
+ * `answeredBy` and fields such as `deprecations`. `--json` prints it with
  * `apiVersion` added (see `parseResponse`).
  *
  * `package` is present when the response is about one thing: one component,
@@ -56,11 +57,33 @@ export interface CLIUnsupportedError {
  * Structural by design — there is no central union of every response `type`.
  * A specific command narrows `data` via its own return type.
  */
+/**
+ * Which copy of the CLI answered a run (spec AST-081 FR5): carried in `meta`
+ * on every successful machine-readable result of a release that has it.
+ * - `project`: the project's own CLI.
+ * - `starting`: the copy that started the run, in a project with no CLI of
+ *   its own.
+ * - `matched`: the release equal to the project's Core, when the project's
+ *   own CLI cannot start, from the per-user cache or the copy that started
+ *   the run.
+ * - `carried`: outside a project, the copy that started the run, with the Core
+ *   it carries.
+ * - `fallback`: the matched release could not be obtained, so the copy that
+ *   started the run answered instead.
+ */
+export interface AnsweredBy {
+  /** The answering CLI's version. */
+  cli: string;
+  /** The Core the run pairs with, or `null` when there is none. */
+  core: string | null;
+  copy: 'project' | 'starting' | 'matched' | 'carried' | 'fallback';
+}
+
 export interface CLIResponse {
   type: string;
   package?: string;
   data: unknown;
-  meta?: Record<string, unknown>;
+  meta?: {answeredBy?: AnsweredBy} & Record<string, unknown>;
 }
 
 /** Wrap any response type to include possible error shapes. */

package/foundation/response/error-codes.d.mts

@@ -99,6 +99,8 @@ export function allErrorCodes(): string[];
  *   | 'ERR_LAYOUT_INVALID'
  *   | 'ERR_UNCLASSIFIED_EXIT'
  *   | 'ERR_SIGNAL_TERMINATED'
+ *   | 'ERR_VERSIONS_UNAVAILABLE'
+ *   | 'ERR_PROJECT_REQUIRED'
  * )} ErrorCode
  */
 /**
@@ -109,4 +111,4 @@ export const ERROR_CODES: Readonly<Record<ErrorCode, ErrorCode>>;
 /**
  * Stable error-code string union. Append-only.
  */
-export type ErrorCode = ("ERR_UNKNOWN" | "ERR_UNKNOWN_COMMAND" | "ERR_UNKNOWN_SUBCOMMAND" | "ERR_INVALID_OPTION" | "ERR_INVALID_ARGUMENT" | "ERR_MISSING_ARGUMENT" | "ERR_INVALID_LANG" | "ERR_INVALID_DETAIL" | "ERR_NODE_VERSION" | "ERR_CORE_NOT_FOUND" | "ERR_CORE_INCOMPATIBLE" | "ERR_UNKNOWN_COMPONENT" | "ERR_UNKNOWN_HOOK" | "ERR_UNKNOWN_TOPIC" | "ERR_UNKNOWN_SECTION" | "ERR_UNKNOWN_CATEGORY" | "ERR_UNKNOWN_TEMPLATE" | "ERR_AMBIGUOUS_TEMPLATE" | "ERR_AMBIGUOUS_COMPONENT" | "ERR_AMBIGUOUS_THEME" | "ERR_UNKNOWN_THEME" | "ERR_INTEGRATION_ROOT_CONFLICT" | "ERR_INTEGRATION_EXPORT_CONFLICT" | "ERR_UNKNOWN_PACKAGE" | "ERR_UNKNOWN_AGENT" | "ERR_UNKNOWN_FEATURE" | "ERR_UNKNOWN_CODEMOD" | "ERR_CODEMOD_FAILED" | "ERR_CODEMOD_PROTECTED" | "ERR_CODEMOD_PROTECTION_SOURCE" | "ERR_NOT_FOUND" | "ERR_NO_DOC" | "ERR_NO_SHOWCASE" | "ERR_NO_SOURCE" | "ERR_INVALID_DOC" | "ERR_FILE_NOT_FOUND" | "ERR_FILE_EXISTS" | "ERR_PATH_TRAVERSAL" | "ERR_WRITE_FAILED" | "ERR_THEME_INVALID" | "ERR_THEME_LOAD" | "ERR_PALETTE_GENERATION" | "ERR_VERSION_DETECT" | "ERR_INVALID_VERSION" | "ERR_DEP_MISSING" | "ERR_GH_CLI" | "ERR_UNKNOWN_POST" | "ERR_FETCH_FAILED" | "ERR_LAYOUT_PARSE" | "ERR_LAYOUT_INVALID" | "ERR_UNCLASSIFIED_EXIT" | "ERR_SIGNAL_TERMINATED");
+export type ErrorCode = ("ERR_UNKNOWN" | "ERR_UNKNOWN_COMMAND" | "ERR_UNKNOWN_SUBCOMMAND" | "ERR_INVALID_OPTION" | "ERR_INVALID_ARGUMENT" | "ERR_MISSING_ARGUMENT" | "ERR_INVALID_LANG" | "ERR_INVALID_DETAIL" | "ERR_NODE_VERSION" | "ERR_CORE_NOT_FOUND" | "ERR_CORE_INCOMPATIBLE" | "ERR_UNKNOWN_COMPONENT" | "ERR_UNKNOWN_HOOK" | "ERR_UNKNOWN_TOPIC" | "ERR_UNKNOWN_SECTION" | "ERR_UNKNOWN_CATEGORY" | "ERR_UNKNOWN_TEMPLATE" | "ERR_AMBIGUOUS_TEMPLATE" | "ERR_AMBIGUOUS_COMPONENT" | "ERR_AMBIGUOUS_THEME" | "ERR_UNKNOWN_THEME" | "ERR_INTEGRATION_ROOT_CONFLICT" | "ERR_INTEGRATION_EXPORT_CONFLICT" | "ERR_UNKNOWN_PACKAGE" | "ERR_UNKNOWN_AGENT" | "ERR_UNKNOWN_FEATURE" | "ERR_UNKNOWN_CODEMOD" | "ERR_CODEMOD_FAILED" | "ERR_CODEMOD_PROTECTED" | "ERR_CODEMOD_PROTECTION_SOURCE" | "ERR_NOT_FOUND" | "ERR_NO_DOC" | "ERR_NO_SHOWCASE" | "ERR_NO_SOURCE" | "ERR_INVALID_DOC" | "ERR_FILE_NOT_FOUND" | "ERR_FILE_EXISTS" | "ERR_PATH_TRAVERSAL" | "ERR_WRITE_FAILED" | "ERR_THEME_INVALID" | "ERR_THEME_LOAD" | "ERR_PALETTE_GENERATION" | "ERR_VERSION_DETECT" | "ERR_INVALID_VERSION" | "ERR_DEP_MISSING" | "ERR_GH_CLI" | "ERR_UNKNOWN_POST" | "ERR_FETCH_FAILED" | "ERR_LAYOUT_PARSE" | "ERR_LAYOUT_INVALID" | "ERR_UNCLASSIFIED_EXIT" | "ERR_SIGNAL_TERMINATED" | "ERR_VERSIONS_UNAVAILABLE" | "ERR_PROJECT_REQUIRED");

package/foundation/response/error-codes.doc.mjs

@@ -277,5 +277,17 @@ export const doc = {
       description:
         'Recorded in the debug log, never printed: the process was ended by a signal (Ctrl-C, SIGTERM) before the command reached a terminal path.',
     },
+
+    // Global mode
+    {
+      value: 'ERR_VERSIONS_UNAVAILABLE',
+      description:
+        'Nothing could answer this run, and nothing was written: the project\'s own CLI could not start and nothing else could answer, or the Core a command needs outside a project could not be installed.',
+    },
+    {
+      value: 'ERR_PROJECT_REQUIRED',
+      description:
+        'The command needs a project (an app with Astryx installed, or an integration package) and was run outside one. Nothing was written.',
+    },
   ],
 };