An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file The per-user update state, and the background check that keeps it
* current (spec AST-081 FR6).
*
* The CLI never installs a newer release for the computer; it tells its user
* one exists, the way `gh` and the Vercel CLI do (notices.mjs). At most once a
* day, never in the first day after the first run, a run starts a detached
* check of the release the registry tags `latest`; no run waits for it. No
* check starts when the standard `CI` variable is set, or when
* `NO_UPDATE_NOTIFIER` is (update-notice-env.mjs).
*
* <user config>/astryx/state.json
* firstRunAt when a run first kept this state (no check before a day)
* checkedAt when the last check started
* checkOkAt when a check last reached the registry
* latest the version `latest` named then
* latestNode the Node range that release declares, or null
* agentText the computer-level agent text: {writtenBy, attemptFor,
* attemptAt}, the release that last wrote it and the last
* background attempt (spec AST-081 FR8)
* notifiedAt when each update notice last printed (notices.mjs)
*
* @input the clock, the registry's `latest` tag (in the worker)
* @output the newest release known, for notices and doctor
* @position foundation/release — read by the bin and doctor; the check runs
* in refresh-worker.mjs.
*/
import * as fs from 'node:fs';
import * as path from 'node:path';
import {spawn} from 'node:child_process';
import {fileURLToPath} from 'node:url';
import {
cachedRelease,
isReleaseVersion,
recentFailedInstall,
releasesDir,
resolveLatestRelease,
tryLock,
} from './cache.mjs';
import {readJson} from './project.mjs';
import {userConfigDir} from '../env/user-dirs.mjs';
import {computerAgentTextSettings} from '../env/user-settings.mjs';
import {isCi, updateNoticesOff} from './update-notice-env.mjs';
/** How often a check may start: once a day, as `gh` and update-notifier do. */
export const CHECK_INTERVAL_MS = 24 * 60 * 60_000;
/**
* @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 = userConfigDir()) {
return path.join(stateDir, 'state.json');
}
/**
* The saved state; `{}` when there is none or it cannot be read.
* @param {string} [stateDir]
* @returns {GlobalState}
*/
export function readGlobalState(stateDir = userConfigDir()) {
const state = readJson(stateFile(stateDir));
return state && typeof state === 'object' && !Array.isArray(state)
? state
: {};
}
/** How long a run waits for another run's change to the state file. */
const STATE_LOCK_WAIT_MS = 2000;
/** Sleep the thread without spinning. @param {number} ms */
function sleep(ms) {
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
}
/**
* 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(stateDir, change) {
const outcome = tryStateLock(stateDir, change);
return outcome.ran ? outcome.value : 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 = userConfigDir()) {
const lockDir = path.join(stateDir, '.lock-state');
try {
const since = fs.statSync(lockDir).mtimeMs;
const owner = readJson(path.join(lockDir, 'owner.json'));
return {
pid: Number.isInteger(owner?.pid) ? owner.pid : null,
host: typeof owner?.host === 'string' ? owner.host : null,
since,
};
} catch {
return 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(stateDir, change) {
const lockDir = path.join(stateDir, '.lock-state');
const deadline = Date.now() + STATE_LOCK_WAIT_MS;
try {
while (!tryLock(lockDir)) {
if (Date.now() > deadline) return {ran: false, reason: 'lock-timeout'};
sleep(10);
}
} catch {
return {ran: false, reason: 'state-unwritable'};
}
try {
return {ran: true, value: change()};
} finally {
fs.rmSync(lockDir, {recursive: true, force: true});
}
}
/**
* 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, stateDir) {
const file = stateFile(stateDir);
try {
const tmp = `${file}.${process.pid}.tmp`;
fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
fs.renameSync(tmp, file);
return true;
} catch {
return false;
}
}
/**
* 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, stateDir = userConfigDir()) {
try {
fs.mkdirSync(stateDir, {recursive: true});
} catch {
// Unwritable: nothing is kept.
}
return (
withStateLock(stateDir, () => {
const next = {...readGlobalState(stateDir), ...patch};
writeGlobalState(next, stateDir);
return next;
}) ?? {...readGlobalState(stateDir), ...patch}
);
}
/**
* 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 = userConfigDir()) {
const state = readGlobalState(stateDir);
if (typeof state.checkOkAt !== 'number' || !isReleaseVersion(state.latest)) {
return null;
}
return {
version: state.latest,
node: typeof state.latestNode === 'string' ? state.latestNode : null,
};
}
/**
* The version of the newest release known, or null.
* @param {string} [stateDir]
* @returns {string | null}
*/
export function knownLatestRelease(stateDir = userConfigDir()) {
return knownLatest(stateDir)?.version ?? null;
}
/**
* Record the release that last wrote the computer-level agent text.
* @param {string | null} version
* @param {string} [stateDir]
*/
export function recordAgentTextWritten(version, stateDir = userConfigDir()) {
if (!isReleaseVersion(version)) return;
updateGlobalState({agentText: {writtenBy: version}}, stateDir);
}
/** A background attempt to write the agent text is retried after an hour. */
export const AGENT_TEXT_RETRY_MS = 60 * 60_000;
/**
* 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 = userConfigDir(),
configDir,
now = Date.now(),
start = startWorker,
}) {
if (!computerAgentTextSettings(configDir).install) return false;
const {agentText} = readGlobalState(stateDir);
if (agentText?.writtenBy === release.version) return false;
if (
agentText?.attemptFor === release.version &&
typeof agentText.attemptAt === 'number' &&
now - agentText.attemptAt < AGENT_TEXT_RETRY_MS
) {
return false;
}
const worker = path.join(
release.root,
'foundation',
'release',
'agent-text-worker.mjs',
);
// A release without the step predates it; it never writes the text.
if (!fs.existsSync(worker)) return false;
updateGlobalState(
{agentText: {...agentText, attemptFor: release.version, attemptAt: now}},
stateDir,
);
// An attempt that cannot be recorded would start again on every run.
if (readGlobalState(stateDir).agentText?.attemptAt !== now) return false;
start(worker, stateDir);
return true;
}
/**
* 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 = process.env,
start = startWorker,
platform = process.platform,
}) {
if (isCi(env) || platform === 'win32') return false;
if (!isReleaseVersion(release.version)) return false;
const beside = readJson(
path.join(release.root, '..', 'core', 'package.json'),
);
if (
beside?.name === '@astryxdesign/core' &&
beside.version === release.version
) {
return false;
}
if (cachedRelease(release.version, cacheDir)) return false;
if (recentFailedInstall(release.version, cacheDir)) return false;
if (
fs.existsSync(path.join(releasesDir(cacheDir), `.lock-${release.version}`))
) {
return false;
}
const worker = path.join(
release.root,
'foundation',
'release',
'core-worker.mjs',
);
// A release without the step predates it.
if (!fs.existsSync(worker)) return false;
start(worker, cacheDir);
return true;
}
/**
* 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 = {}) {
const {
stateDir = userConfigDir(),
now = Date.now(),
env = process.env,
start = startWorker,
} = options;
if (updateNoticesOff(env)) return false;
const state = readGlobalState(stateDir);
if (typeof state.firstRunAt !== 'number') {
updateGlobalState({firstRunAt: now}, stateDir);
return false;
}
const last = Math.max(state.firstRunAt, state.checkedAt ?? 0);
if (now - last < CHECK_INTERVAL_MS) return false;
updateGlobalState({checkedAt: now}, stateDir);
// A start time that cannot be recorded would start a check on every run.
if (readGlobalState(stateDir).checkedAt !== now) return false;
start(
fileURLToPath(new URL('./refresh-worker.mjs', import.meta.url)),
stateDir,
);
return true;
}
/**
* 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 = userConfigDir()) {
const state = readGlobalState(stateDir);
const failed = state.checkFailed;
if (
!failed ||
typeof failed.at !== 'number' ||
typeof failed.reason !== 'string'
) {
return null;
}
return typeof state.checkOkAt === 'number' && state.checkOkAt > failed.at
? null
: {at: failed.at, reason: failed.reason};
}
/**
* Start a detached worker that outlives this run and reaches no stream.
* @param {string} worker
* @param {string} stateDir
*/
function startWorker(worker, stateDir) {
try {
const child = spawn(process.execPath, [worker, stateDir], {
detached: true,
stdio: 'ignore',
windowsHide: true,
});
child.on('error', () => {});
child.unref();
} catch {
// A check that cannot start is the same as a failed check.
}
}
/**
* 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 = {}) {
const {stateDir = userConfigDir(), resolve = resolveLatestRelease} = options;
const lockDir = path.join(stateDir, '.lock-check');
try {
if (!tryLock(lockDir)) return readGlobalState(stateDir);
} catch {
return readGlobalState(stateDir);
}
try {
/** @type {string} */
let reason = 'unknown';
const latest = resolve({
onFailure: why => {
reason = why;
},
});
if (!latest) {
// Recorded so doctor can say why notices stopped (diagnosis only).
return updateGlobalState(
{checkFailed: {at: Date.now(), reason}},
stateDir,
);
}
return updateGlobalState(
{
latest: latest.version,
latestNode: latest.node,
checkOkAt: Date.now(),
checkFailed: undefined,
},
stateDir,
);
} finally {
fs.rmSync(lockDir, {recursive: true, force: true});
}
}