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

package/foundation/release/choose.d.mts

@@ -0,0 +1,207 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The global folders the package managers' own settings name on this
+ * computer, read the way each package manager reads them, never guessed from
+ * a folder's layout:
+ * - Bun: `$BUN_INSTALL/install/global`, else `~/.bun/install/global`, and a
+ *   `globalDir` in `~/.bunfig.toml` or `$XDG_CONFIG_HOME/.bunfig.toml`.
+ * - Yarn 1: the `global-folder` setting (`YARN_GLOBAL_FOLDER`,
+ *   `npm_config_global_folder`, or `global-folder` in `~/.yarnrc`), else
+ *   `<data folder>/global`: `%LOCALAPPDATA%\Yarn\Data` on Windows,
+ *   `$XDG_DATA_HOME/yarn`, else `~/.config/yarn`.
+ * - pnpm: `<PNPM_HOME>/global`, else `<data folder>/global` (`$XDG_DATA_HOME/pnpm`,
+ *   else `%LOCALAPPDATA%\pnpm`, `~/Library/pnpm`, or `~/.local/share/pnpm`), and a
+ *   `global-dir` in `~/.npmrc` or pnpm's `rc` file; a global install is a
+ *   numbered folder below it.
+ * @param {GlobalWhere} [where]
+ * @returns {Array<{manager: 'bun' | 'yarn' | 'pnpm', folder: string}>}
+ */
+export function configuredGlobalFolders(where?: GlobalWhere): Array<{
+    manager: "bun" | "yarn" | "pnpm";
+    folder: string;
+}>;
+/**
+ * The package manager's global folder that holds the CLI at `root`, when the
+ * package manager's own settings name that folder (configuredGlobalFolders);
+ * null otherwise. A folder that only looks like one, such as an app made with
+ * `yarn add` alone or one under a folder named `install/global`, is not.
+ * @param {string} root the CLI package's real folder
+ * @param {GlobalWhere} [where]
+ * @returns {{manager: 'bun' | 'pnpm' | 'yarn', folder: string} | null}
+ */
+export function globalFolderOf(root: string, where?: GlobalWhere): {
+    manager: "bun" | "pnpm" | "yarn";
+    folder: string;
+} | null;
+/**
+ * Where an installed CLI package lives: its owner, the folder that holds the
+ * `node_modules` it is in (above pnpm's `.pnpm` store), and whether that owner
+ * is named like a package manager's default global folder (`knownGlobal`, a
+ * hint only: isGlobalCopy decides from the package managers' settings). Pure:
+ * reads no file, and
+ * accepts either separator, so Windows paths read the same on every platform.
+ * @param {string} root the package's real folder
+ * @returns {{runner: boolean, owner: string | null, knownGlobal: boolean}}
+ */
+export function installPlaceOf(root: string): {
+    runner: boolean;
+    owner: string | null;
+    knownGlobal: boolean;
+};
+/**
+ * Is the running copy the CLI package installed for the computer
+ * (`npm i -g`, `pnpm add -g`, `yarn global add`, `bun add -g`, Volta)?
+ *
+ * Read from where the package lives: in a `node_modules` folder whose owner
+ * holds no package.json (npm's global folder), or whose owner is a global
+ * folder a package manager's own settings name (globalFolderOf). A copy in a
+ * project, in a package runner's temporary install, or in the release cache
+ * is not, and when unsure the answer is no: a copy that is not global runs no
+ * update check and writes no agent skill.
+ *
+ * @param {string} cliRoot
+ * @param {string} [cacheDir]
+ * @param {GlobalWhere} [where]
+ * @returns {boolean}
+ */
+export function isGlobalCopy(cliRoot: string, cacheDir?: string, where?: GlobalWhere): boolean;
+/**
+ * The Core release a project records, without asking the registry: the Core
+ * the folder reads, else the version its lockfile records, else an exact
+ * declared version; null for a range.
+ * @param {import('./project.mjs').ReleaseFacts} facts
+ * @returns {string | null}
+ */
+export function coreVersionOf(facts: import("./project.mjs").ReleaseFacts): string | null;
+/**
+ * The release that matches a project's facts, before any registry question.
+ * @param {import('./project.mjs').ReleaseFacts} facts
+ * @returns {{version: string | null, range: {name: string, spec: string} | null}}
+ */
+export function matchedVersionOf(facts: import("./project.mjs").ReleaseFacts): {
+    version: string | null;
+    range: {
+        name: string;
+        spec: string;
+    } | null;
+};
+/**
+ * Choose who answers a run started by `self` in `cwd`.
+ *
+ * A command that acts on the computer rather than the folder is chosen as
+ * outside a project wherever it runs (`computer`), so a project's older CLI
+ * never answers it.
+ *
+ * @param {{cwd: string, self: RunningCopy, cacheDir?: string, resolve?: typeof resolvePublishedVersion, computer?: boolean}} input
+ * @returns {ReleaseChoice}
+ */
+export function chooseRelease({ cwd, self, resolve, computer, }: {
+    cwd: string;
+    self: RunningCopy;
+    cacheDir?: string;
+    resolve?: typeof resolvePublishedVersion;
+    computer?: boolean;
+}): ReleaseChoice;
+/**
+ * The folder a project's facts point at: the declaring package.json's folder,
+ * else the folder that holds the Core (the one above its node_modules, or the
+ * workspace root above `packages/core`).
+ * @param {import('./project.mjs').ReleaseFacts} facts
+ * @returns {string | null}
+ */
+export function projectRootOf(facts: import("./project.mjs").ReleaseFacts): string | null;
+/**
+ * Is this run a command that acts on the computer rather than the folder it
+ * runs in? `astryx init --user`, which writes the computer-level agent text,
+ * and `astryx docs global[/…]`, the docs of global mode itself, which the copy
+ * that started the run answers, so they are readable inside a project whose
+ * release predates them (spec AST-081 FR8, FR9).
+ * @param {string[]} argv arguments after `astryx`
+ * @returns {boolean}
+ */
+export function isComputerLevel(argv: string[]): boolean;
+/**
+ * The running copy, from its package folder.
+ * @param {string} root
+ * @returns {RunningCopy}
+ */
+export function runningCopy(root: string): RunningCopy;
+/**
+ * Does the package at `cliDir` print its own who-answered line? Releases that
+ * carry this module do; older ones answer silently, so the copy that hands a
+ * run to them prints the line for them.
+ * @param {string} cliDir
+ * @returns {boolean}
+ */
+export function namesWhoAnswered(cliDir: string): boolean;
+/**
+ * The CLI package folder an entry file belongs to.
+ * @param {string} bin
+ * @returns {string}
+ */
+export function packageRootOf(bin: string): string;
+/**
+ * The copy that is running.
+ */
+export type RunningCopy = {
+    /**
+     * its package version
+     */
+    version: string;
+    /**
+     * its package folder
+     */
+    root: string;
+};
+/**
+ * Who answers the run.
+ */
+export type ReleaseChoice = {
+    /**
+     *   the kind of copy that answers (`meta.answeredBy.copy`): `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; `carried`, outside a
+     *   project; `fallback`, the copy that started the run when the matched
+     *   release could not be obtained (spec AST-081 FR2, FR5)
+     */
+    copy: "project" | "starting" | "matched" | "carried" | "fallback";
+    /**
+     * `self`: this copy;
+     * `project-cli`: hand off to the project's CLI; `release`: hand off to the
+     * cached release `version`
+     */
+    answer: "self" | "project-cli" | "release";
+    /**
+     * the release that answers
+     */
+    version: string;
+    /**
+     * the entry file to hand off to (`project-cli`
+     * and a cached `release` that is already installed)
+     */
+    bin: string | null;
+    /**
+     * the Core the answering release pairs
+     * with, when known now
+     */
+    coreVersion: string | null;
+    inProject: boolean;
+    /**
+     * why the release cannot answer, when it
+     * cannot
+     */
+    unavailable: string | null;
+};
+/**
+ * Where a global install's settings come from: the home folder, the
+ * environment, and the platform. Defaults to this process's.
+ */
+export type GlobalWhere = {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+};
+import { resolvePublishedVersion } from './cache.mjs';