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

package/foundation/release/notices.d.mts

@@ -0,0 +1,307 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Whether notice `key` may print now; when it may, its time is recorded
+ * first, and a time that cannot be recorded keeps it from printing.
+ * @param {string} key
+ * @param {{stateDir?: string, now?: number}} [options]
+ * @returns {boolean}
+ */
+export function takeNotice(key: string, { stateDir, now }?: {
+    stateDir?: string;
+    now?: number;
+}): boolean;
+/**
+ * Record why notice `key` did not print (state `noticeSkips`), for diagnosis
+ * only. It adds to a state file that already exists and never creates one, so
+ * a run that keeps no state (a project's own CLI before any check) writes
+ * nothing. It is written only while this run holds the state file's lock:
+ * when the lock stays taken or the file cannot be written, nothing is
+ * recorded, and a run never fails because of it.
+ * @param {string} key
+ * @param {import('./global-state.mjs').NoticeSkip['reason']} reason
+ * @param {{stateDir?: string, now?: number}} [options]
+ */
+export function recordNoticeSkip(key: string, reason: import("./global-state.mjs").NoticeSkip["reason"], { stateDir, now }?: {
+    stateDir?: string;
+    now?: number;
+}): void;
+/**
+ * The newest notice skip the state file records, with the notice it was for.
+ * @param {{stateDir?: string}} [options]
+ * @returns {({key: string} & import('./global-state.mjs').NoticeSkip) | null}
+ */
+export function lastNoticeSkip({ stateDir }?: {
+    stateDir?: string;
+}): ({
+    key: string;
+} & import("./global-state.mjs").NoticeSkip) | null;
+/**
+ * The command that upgrades a CLI installed for the computer, by the package
+ * manager whose global folder holds it (the Vercel CLI reads it the same
+ * way); npm when none is recognized. A CLI that npm installed under a prefix
+ * of its own (`npm i -g --prefix ~/.local`, `NPM_CONFIG_PREFIX`, or `prefix=`
+ * in an `.npmrc`) is upgraded into that same prefix, named with `--prefix`,
+ * so the upgrade lands where the running copy is whatever npm's settings are
+ * when it runs. pnpm, Yarn, and Bun read their global folder from their own
+ * settings, so their plain command reinstalls in place.
+ * @param {string} cliRoot the CLI package's folder
+ * @param {{execPath?: string, home?: string, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv}} [where]
+ * @returns {string}
+ */
+export function globalUpgradeCommand(cliRoot: string, where?: {
+    execPath?: string;
+    home?: string;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+}): string;
+/**
+ * The second line of a notice: the command, after the Node it needs when the
+ * computer runs an older one.
+ * @param {string} command
+ * @param {string | null} node the Node range the newest release declares
+ * @param {string} [nodeVersion]
+ * @returns {string}
+ */
+export function upgradeLine(command: string, node: string | null, nodeVersion?: string): string;
+/**
+ * The first line of a newer-release notice.
+ * @param {string} current
+ * @param {string} newest
+ * @returns {string}
+ */
+export function availableLine(current: string, newest: string): string;
+/**
+ * @typedef {object} GlobalBehind
+ * @property {string} current the global copy's version
+ * @property {string} newest the newest release known
+ * @property {string | null} node the Node range it declares
+ * @property {string} command the command that upgrades the global copy
+ */
+/**
+ * Whether the global copy is older than the newest release known.
+ * @param {{self: {version: string, root: string}, stateDir?: string}} options
+ * @returns {GlobalBehind | null}
+ */
+export function globalBehind({ self, stateDir }: {
+    self: {
+        version: string;
+        root: string;
+    };
+    stateDir?: string;
+}): GlobalBehind | null;
+/**
+ * The command that adds a package to the project of a run in `cwd`, with the
+ * project's package manager (spec AST-081 FR12). Null when `cwd` belongs to
+ * no project `spec:AST-040` FR9 defines, and in a folder inside the project
+ * whose package.json is not the project's (see {@link installFolder}): a run
+ * there loads integrations from that package.json, so a package added to the
+ * project would stay unused there, and the advice is
+ * {@link RUN_FROM_PROJECT}.
+ * @param {string} cwd
+ * @returns {((name: string) => string) | null}
+ */
+export function projectAddCommand(cwd: string): ((name: string) => string) | null;
+/**
+ * The commands that bring a project's own CLI and Core to one release, with
+ * the project's package manager: when the CLI is newer, Core up to it and then
+ * the codemods from Core's release; otherwise the CLI to Core's release.
+ * Null in a folder that belongs to no project, or whose package.json is not
+ * the project's (see {@link installFolder}).
+ * @param {{cwd: string, cli: string, core: string}} options
+ * @returns {string | null}
+ */
+export function alignCliAndCore({ cwd, cli, core }: {
+    cwd: string;
+    cli: string;
+    core: string;
+}): string | null;
+/**
+ * Where a command that adds an Astryx package runs, for a run in `cwd`: in
+ * the project `spec:AST-040` FR9 defines, which stops at a repository root
+ * and never counts the home folder (spec AST-081 FR2, FR10). Null when `cwd`
+ * belongs to no such project, so no command adds anything. When `cwd`'s
+ * nearest package.json is not the project's, as in a tool folder that
+ * installs its own Core, a package manager would add to the tool's
+ * package.json, so `moved` says the command runs in the project's folder.
+ * @param {string} cwd
+ * @returns {{dir: string, moved: boolean} | null}
+ */
+export function installFolder(cwd: string): {
+    dir: string;
+    moved: boolean;
+} | null;
+/**
+ * The command that adds the CLI at Core's version, for a run in `cwd` whose
+ * Core is `core`, with the project's package manager in the project root.
+ * `command` is null in a folder inside the project whose package.json is not
+ * the project's (see {@link installFolder}), where the advice is
+ * {@link RUN_FROM_PROJECT}. Null when the folder belongs to no project.
+ * @param {{cwd: string, core: string}} options
+ * @returns {{root: string, core: string, command: string | null} | null}
+ */
+export function cliInstallAdvice({ cwd, core }: {
+    cwd: string;
+    core: string;
+}): {
+    root: string;
+    core: string;
+    command: string | null;
+} | null;
+/**
+ * The hint for a project with no CLI of its own, answered by `answered` while
+ * its Core is `core`: the command that adds the CLI at Core's version, with
+ * the project's package manager (see {@link cliInstallAdvice}). Null when no
+ * command fits, or when the project the command adds to already matches.
+ * @param {{cwd: string, answered: string, core: string}} options
+ * @returns {{root: string, line: string} | null}
+ */
+export function noCliHint({ cwd, answered, core }: {
+    cwd: string;
+    answered: string;
+    core: string;
+}): {
+    root: string;
+    line: string;
+} | null;
+/**
+ * The hint's text.
+ * @param {string} answered
+ * @param {string} core
+ * @param {string | null} command the command that adds the CLI at Core's
+ *   version; null in a folder whose package.json is not the project's
+ * @returns {string}
+ */
+export function noCliHintLine(answered: string, core: string, command: string | null): string;
+/**
+ * The command that installs the CLI at `version` in the project at `root`,
+ * with its package manager.
+ * @param {string} root
+ * @param {string} version
+ * @returns {string}
+ */
+export function addCliCommand(root: string, version: string): string;
+/**
+ * Whether the project's release is older than the newest release known, and
+ * the commands that upgrade it.
+ * @param {{cwd: string, current: string, stateDir?: string}} options
+ * @returns {ProjectLag | null}
+ */
+export function projectLag({ cwd, current: given, stateDir }: {
+    cwd: string;
+    current: string;
+    stateDir?: string;
+}): ProjectLag | null;
+/**
+ * The first `astryx` on the search path, when it is an Astryx CLI release
+ * that predates the hand-off and is not the running copy.
+ * @param {{selfRoot?: string, searchPath?: string, platform?: NodeJS.Platform}} [options]
+ * @returns {{file: string, version: string | null, command: string} | null}
+ */
+export function oldGlobalCommand({ selfRoot, ...options }?: {
+    selfRoot?: string;
+    searchPath?: string;
+    platform?: NodeJS.Platform;
+}): {
+    file: string;
+    version: string | null;
+    command: string;
+} | null;
+/**
+ * The two lines about a global copy that predates the hand-off.
+ * @param {{version: string | null, command: string}} old
+ * @returns {string[]}
+ */
+export function oldGlobalLines(old: {
+    version: string | null;
+    command: string;
+}): string[];
+/**
+ * The notice lines to print after a command, each notice recorded as shown.
+ * Empty in machine-readable runs and when the environment turns notices off.
+ * Never throws.
+ * @param {{
+ *   cwd: string,
+ *   self: {version: string, root: string},
+ *   choice: {inProject: boolean, version: string, copy?: string, coreVersion?: string | null},
+ *   json?: boolean,
+ *   stateDir?: string,
+ *   cacheDir?: string,
+ *   now?: number,
+ *   env?: Record<string, string | undefined>,
+ *   searchPath?: string,
+ * }} options
+ * @returns {string[]}
+ */
+export function noticeLines({ cwd, self, choice, json, stateDir, cacheDir, now, env, searchPath, }: {
+    cwd: string;
+    self: {
+        version: string;
+        root: string;
+    };
+    choice: {
+        inProject: boolean;
+        version: string;
+        copy?: string;
+        coreVersion?: string | null;
+    };
+    json?: boolean;
+    stateDir?: string;
+    cacheDir?: string;
+    now?: number;
+    env?: Record<string, string | undefined>;
+    searchPath?: string;
+}): string[];
+/** A notice prints at most once in this long. */
+export const NOTICE_INTERVAL_MS: number;
+/**
+ * What to tell a run in a folder inside a project whose package.json is not
+ * the project's: run from the project's folder, since adding there would make
+ * the folder a project of its own (spec AST-081 FR2).
+ */
+export const RUN_FROM_PROJECT: "Run this from the Astryx project's folder, or declare an Astryx package in this folder's package.json to make it a project of its own.";
+export type GlobalBehind = {
+    /**
+     * the global copy's version
+     */
+    current: string;
+    /**
+     * the newest release known
+     */
+    newest: string;
+    /**
+     * the Node range it declares
+     */
+    node: string | null;
+    /**
+     * the command that upgrades the global copy
+     */
+    command: string;
+};
+export type ProjectLag = {
+    /**
+     * the project's folder
+     */
+    root: string;
+    /**
+     * the release that answers it
+     */
+    current: string;
+    /**
+     * the newest release known
+     */
+    newest: string;
+    /**
+     * the Node range the newest release declares
+     */
+    node: string | null;
+    /**
+     * the command that installs the newest release
+     */
+    install: string;
+    /**
+     * the command that migrates the project
+     */
+    upgrade: string;
+};