@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/foundation/release/lock-lease.mjs

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The lease on a release install's lock in the per-user cache (spec
+ * AST-081 FR11).
+ *
+ * A lock folder records its holder in `owner.json`: the process id and the
+ * computer's name. On the same computer a waiting run checks whether that
+ * process still runs. A cache shared between computers cannot check another
+ * computer's processes, so the holder renews its record every
+ * `LEASE_RENEW_MS` while the package manager works, and a waiting run takes
+ * a lock from another computer over once it has seen the record go unrenewed
+ * for `LEASE_SILENCE_MS`. The waiting run judges by change it observes, never
+ * by comparing clocks, so computers whose clocks differ agree.
+ *
+ * @input  the lock folder
+ * @output the renewed record, and whether a foreign record has gone silent
+ * @position foundation/release — renewed by npm-guard.mjs, read by cache.mjs.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** How often the holder renews its record while the package manager works. */
+export const LEASE_RENEW_MS = 10_000;
+
+/** How long a record from another computer may go unrenewed, as observed. */
+export const LEASE_SILENCE_MS = 60_000;
+
+/**
+ * Renew the holder's record: the same process and computer, with a counter
+ * that changes on every renewal. Never throws.
+ * @param {string} lockDir
+ */
+export function renewLock(lockDir) {
+  const file = path.join(lockDir, 'owner.json');
+  try {
+    const owner = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    const next = {...owner, beat: (Number(owner.beat) || 0) + 1};
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(next));
+    fs.renameSync(tmp, file);
+  } catch {
+    // A lock that was taken over or removed has no record to renew.
+  }
+}
+
+/**
+ * What this process last saw of each foreign lock: the record's text and
+ * when that text was first seen.
+ * @type {Map<string, {text: string, since: number}>}
+ */
+const observed = new Map();
+
+/**
+ * Whether a lock held from another computer has gone silent: its record has
+ * not changed for `LEASE_SILENCE_MS` of this process's own observation.
+ * @param {string} lockDir
+ * @param {number} [now]
+ * @returns {boolean}
+ */
+export function foreignLockIsSilent(lockDir, now = Date.now()) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(lockDir, 'owner.json'), 'utf-8');
+  } catch {
+    text = '';
+  }
+  const seen = observed.get(lockDir);
+  if (!seen || seen.text !== text) {
+    observed.set(lockDir, {text, since: now});
+    return false;
+  }
+  return now - seen.since >= LEASE_SILENCE_MS;
+}
+
+/** Forget what this process observed (tests). */
+export function forgetObservedLocks() {
+  observed.clear();
+}

package/foundation/release/notices.d.mts

@@ -0,0 +1,253 @@
+// @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 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.
+ * @param {{cwd: string, cli: string, core: string}} options
+ * @returns {string}
+ */
+export function alignCliAndCore({ cwd, cli, core }: {
+    cwd: string;
+    cli: string;
+    core: string;
+}): string;
+/**
+ * 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.
+ * @param {{cwd: string, answered: string, core: string}} options
+ * @returns {{root: string, line: string}}
+ */
+export function noCliHint({ cwd, answered, core }: {
+    cwd: string;
+    answered: string;
+    core: string;
+}): {
+    root: string;
+    line: string;
+};
+/**
+ * The hint's text.
+ * @param {string} answered
+ * @param {string} core
+ * @param {string} command the command that adds the CLI at Core's version
+ * @returns {string}
+ */
+export function noCliHintLine(answered: string, core: string, command: string): 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, 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;
+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;
+};