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

package/foundation/release/global-state.d.mts

@@ -0,0 +1,263 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @typedef {object} GlobalState
+ * @property {number} [firstRunAt]
+ * @property {number} [checkedAt]
+ * @property {number} [checkOkAt]
+ * @property {string} [latest]
+ * @property {string | null} [latestNode]
+ * @property {{at: number, reason: string}} [checkFailed] why the last check
+ *   did not reach the registry, for diagnosis only (`astryx doctor`); cleared
+ *   by a check that does. Not part of any contract.
+ * @property {{writtenBy?: string, attemptFor?: string, attemptAt?: number}} [agentText]
+ * @property {Record<string, number>} [notifiedAt] when each update notice
+ *   last printed (notices.mjs)
+ * @property {Record<string, NoticeSkip>} [noticeSkips] why each update notice
+ *   last did not print, for diagnosis only: `astryx doctor` shows the newest.
+ *   Not part of any contract; its shape may change in any release.
+ */
+/**
+ * Why an update notice did not print: `already-shown` (it printed within the
+ * day), `no-newer` (nothing newer is known), or `no-project` (the folder
+ * installs Core but belongs to no Astryx project, so no install command
+ * fits). Recorded only while the run
+ * holds the state file's lock.
+ * @typedef {{reason: 'already-shown' | 'no-newer' | 'no-project', at: number}} NoticeSkip
+ */
+/**
+ * The state file.
+ * @param {string} [stateDir] the per-user configuration folder
+ * @returns {string}
+ */
+export function stateFile(stateDir?: string): string;
+/**
+ * The saved state; `{}` when there is none or it cannot be read.
+ * @param {string} [stateDir]
+ * @returns {GlobalState}
+ */
+export function readGlobalState(stateDir?: string): GlobalState;
+/**
+ * Run `change` while holding the state file's lock, so runs that finish at
+ * the same moment change the state one at a time: each reads what the one
+ * before it wrote. Returns `change`'s result, or `undefined` when the lock
+ * cannot be taken in time or the folder cannot be written, in which case
+ * nothing changes.
+ * @template T
+ * @param {string} stateDir
+ * @param {() => T} change
+ * @returns {T | undefined}
+ */
+export function withStateLock<T>(stateDir: string, change: () => T): T | undefined;
+/**
+ * Who holds the state file's lock now, read from its owner record, for
+ * diagnosis: null when it is free. `since` is when the lock folder was made.
+ * @param {string} [stateDir]
+ * @returns {{pid: number | null, host: string | null, since: number} | null}
+ */
+export function stateLockHolder(stateDir?: string): {
+    pid: number | null;
+    host: string | null;
+    since: number;
+} | null;
+/**
+ * {@link withStateLock}, saying why `change` did not run: the lock stayed
+ * taken past the wait (`lock-timeout`), or the folder cannot hold it
+ * (`state-unwritable`).
+ * @template T
+ * @param {string} stateDir
+ * @param {() => T} change
+ * @returns {{ran: true, value: T} | {ran: false, reason: 'lock-timeout' | 'state-unwritable'}}
+ */
+export function tryStateLock<T>(stateDir: string, change: () => T): {
+    ran: true;
+    value: T;
+} | {
+    ran: false;
+    reason: "lock-timeout" | "state-unwritable";
+};
+/**
+ * Write the whole state, atomically. Call only while holding the lock.
+ * @param {GlobalState} state
+ * @param {string} stateDir
+ * @returns {boolean} whether it was written
+ */
+export function writeGlobalState(state: GlobalState, stateDir: string): boolean;
+/**
+ * Merge `patch` into the saved state under the lock. An unwritable folder
+ * never fails a run; the state is simply not kept.
+ * @param {Partial<GlobalState>} patch
+ * @param {string} [stateDir]
+ * @returns {GlobalState}
+ */
+export function updateGlobalState(patch: Partial<GlobalState>, stateDir?: string): GlobalState;
+/**
+ * The newest release the last check found, and the Node range it declares;
+ * null when no check has reached the registry.
+ * @param {string} [stateDir]
+ * @returns {{version: string, node: string | null} | null}
+ */
+export function knownLatest(stateDir?: string): {
+    version: string;
+    node: string | null;
+} | null;
+/**
+ * The version of the newest release known, or null.
+ * @param {string} [stateDir]
+ * @returns {string | null}
+ */
+export function knownLatestRelease(stateDir?: string): string | null;
+/**
+ * Record the release that last wrote the computer-level agent text.
+ * @param {string | null} version
+ * @param {string} [stateDir]
+ */
+export function recordAgentTextWritten(version: string | null, stateDir?: string): void;
+/**
+ * The global copy keeps the computer-level agent text installed (spec
+ * AST-081 FR8): when the person has not turned it off and the running global
+ * version has not written it yet, as after the person upgraded the global
+ * copy, that release's own background step writes it, detached, so no command
+ * waits. Returns whether a step was started.
+ *
+ * @param {{
+ *   release: {version: string, root: string},
+ *   stateDir?: string,
+ *   configDir?: string,
+ *   now?: number,
+ *   start?: (worker: string, stateDir: string) => void,
+ * }} options
+ * @returns {boolean}
+ */
+export function maybeKeepAgentText({ release, stateDir, configDir, now, start, }: {
+    release: {
+        version: string;
+        root: string;
+    };
+    stateDir?: string;
+    configDir?: string;
+    now?: number;
+    start?: (worker: string, stateDir: string) => void;
+}): boolean;
+/**
+ * Start the background step that installs this release's Core into the
+ * per-user cache, so commands that read Core work offline outside a project
+ * after one online run (spec AST-081 FR3, FR6): when the global copy carries
+ * no Core beside it and none is cached for its release, no install of it is
+ * under way, no recent attempt failed (the release cache's backoff), and
+ * `CI` is not set. It never blocks a command, prints nothing, and a failure
+ * is retried by a later run's step. Returns whether it was started.
+ *
+ * Never on Windows: a detached child there inherits the caller's open handles,
+ * such as the pipes a tool or agent reads this run's output from, and the
+ * caller would wait for the download to end. A component read on Windows
+ * fetches the Core itself when it first needs it.
+ * @param {{release: {version: string, root: string}, cacheDir: string, env?: NodeJS.ProcessEnv, start?: typeof startWorker, platform?: NodeJS.Platform}} options
+ * @returns {boolean}
+ */
+export function maybeFetchCore({ release, cacheDir, env, start, platform, }: {
+    release: {
+        version: string;
+        root: string;
+    };
+    cacheDir: string;
+    env?: NodeJS.ProcessEnv;
+    start?: typeof startWorker;
+    platform?: NodeJS.Platform;
+}): boolean;
+/**
+ * Start the background check when one is due: never when the environment
+ * turns update notices off (`CI`, `NO_UPDATE_NOTIFIER`), never in the first
+ * day after the first run, and at most once a day. Returns whether a check
+ * was started.
+ *
+ * @param {{
+ *   stateDir?: string,
+ *   now?: number,
+ *   env?: Record<string, string | undefined>,
+ *   start?: (worker: string, stateDir: string) => void,
+ * }} [options]
+ * @returns {boolean}
+ */
+export function maybeStartCheck(options?: {
+    stateDir?: string;
+    now?: number;
+    env?: Record<string, string | undefined>;
+    start?: (worker: string, stateDir: string) => void;
+}): boolean;
+/**
+ * Why the last update check did not reach the registry, when it failed after
+ * the last one that did; null otherwise. For diagnosis only.
+ * @param {string} [stateDir]
+ * @returns {{at: number, reason: string} | null}
+ */
+export function lastCheckFailure(stateDir?: string): {
+    at: number;
+    reason: string;
+} | null;
+/**
+ * The check itself: ask the registry for `latest` and save what it says. It
+ * installs nothing. At most one check runs at a time.
+ * @param {{stateDir?: string, resolve?: typeof resolveLatestRelease}} [options]
+ * @returns {GlobalState}
+ */
+export function runCheck(options?: {
+    stateDir?: string;
+    resolve?: typeof resolveLatestRelease;
+}): GlobalState;
+/** How often a check may start: once a day, as `gh` and update-notifier do. */
+export const CHECK_INTERVAL_MS: number;
+/** A background attempt to write the agent text is retried after an hour. */
+export const AGENT_TEXT_RETRY_MS: number;
+export type GlobalState = {
+    firstRunAt?: number | undefined;
+    checkedAt?: number | undefined;
+    checkOkAt?: number | undefined;
+    latest?: string | undefined;
+    latestNode?: string | null | undefined;
+    /**
+     * why the last check
+     * did not reach the registry, for diagnosis only (`astryx doctor`); cleared
+     * by a check that does. Not part of any contract.
+     */
+    checkFailed?: {
+        at: number;
+        reason: string;
+    } | undefined;
+    agentText?: {
+        writtenBy?: string;
+        attemptFor?: string;
+        attemptAt?: number;
+    } | undefined;
+    /**
+     * when each update notice
+     * last printed (notices.mjs)
+     */
+    notifiedAt?: Record<string, number> | undefined;
+    /**
+     * why each update notice
+     * last did not print, for diagnosis only: `astryx doctor` shows the newest.
+     * Not part of any contract; its shape may change in any release.
+     */
+    noticeSkips?: Record<string, NoticeSkip> | undefined;
+};
+/**
+ * Why an update notice did not print: `already-shown` (it printed within the
+ * day), `no-newer` (nothing newer is known), or `no-project` (the folder
+ * installs Core but belongs to no Astryx project, so no install command
+ * fits). Recorded only while the run
+ * holds the state file's lock.
+ */
+export type NoticeSkip = {
+    reason: "already-shown" | "no-newer" | "no-project";
+    at: number;
+};
+/**
+ * Start a detached worker that outlives this run and reaches no stream.
+ * @param {string} worker
+ * @param {string} stateDir
+ */
+declare function startWorker(worker: string, stateDir: string): void;
+import { resolveLatestRelease } from './cache.mjs';
+export {};