@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/update.js

@@ -0,0 +1,571 @@
+import { execFile, spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { link, lstat, mkdir, readFile, readdir, realpath, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { basename, delimiter, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import semver from 'semver';
+import { configDirectory } from './config.js';
+const executeFile = promisify(execFile);
+/** The package `andorra update` installs. */
+export const PACKAGE_NAME = '@andorra-labs/code';
+/** The npm dist-tag the update follows. */
+const RELEASE_TAG = 'latest';
+/** Bounded install attempts; only a failure that still looks transient is retried. */
+const INSTALL_ATTEMPTS = 3;
+const INSTALL_RETRY_DELAY_MS = 1_500;
+/** npm reports a Windows sharing violation as EPERM, EBUSY or errno -4048. */
+const LOCK_FAILURE = /EPERM|EBUSY|resource busy or locked|-4048/;
+/** How much of npm's error output a failure keeps for its message. */
+const OUTPUT_TAIL = 6_000;
+/** Bounded walk: a Windows sharing violation matters on a native module or a launcher. */
+const LOCK_PROBE_SCAN_LIMIT = 10_000;
+/**
+ * How deep inside one package to look. Real prebuilt modules sit at lib/kernel/*.node or
+ * build/Release/*.node, so a shallow limit would miss exactly the file this guard exists for.
+ */
+const LOCK_PROBE_DEPTH = 6;
+const runCommand = async (program, args, cwd, options = {}) => {
+    const pathKey = process.platform === 'win32' ? Object.keys(process.env).find(key => key.toLowerCase() === 'path') ?? 'PATH' : 'PATH';
+    const env = { ...process.env, [pathKey]: dirname(process.execPath) + delimiter + (process.env[pathKey] ?? '') };
+    const command = `${program} ${args.join(' ')}`;
+    if (options.stream) {
+        // npm lifecycle scripts can outlive npm if a timeout kills only its parent, so there is no
+        // timeout here: the updater lock is held until npm actually closes. Its error output is shown
+        // as it arrives and kept, so a failure can still name the file Windows refused to replace.
+        return new Promise((resolvePromise, reject) => {
+            const child = spawn(program, args, { cwd, env, windowsHide: true, stdio: ['inherit', 'inherit', 'pipe'] });
+            let errors = '';
+            child.stderr?.on('data', (chunk) => {
+                process.stderr.write(chunk);
+                errors = (errors + chunk.toString('utf8')).slice(-OUTPUT_TAIL);
+            });
+            child.once('error', error => reject(new Error(`${command} could not start: ${error.message}`)));
+            child.once('close', (code, signal) => {
+                if (code === 0 && !signal) {
+                    resolvePromise('');
+                    return;
+                }
+                const detail = errors.trim();
+                reject(new Error(`${command} exited with ${signal ?? `code ${code}`}${detail ? `:\n${detail}` : '; see the npm output above.'}`));
+            });
+        });
+    }
+    try {
+        const result = await executeFile(program, args, { cwd, env, windowsHide: true, timeout: 600_000, maxBuffer: 8_388_608 });
+        return result.stdout;
+    }
+    catch (error) {
+        const failure = error;
+        const detail = (failure.stderr || failure.stdout || failure.message).trim().slice(-OUTPUT_TAIL);
+        throw new Error(`${command} failed${detail ? `:\n${detail}` : ''}`);
+    }
+};
+async function npmCli() {
+    const nodeDirectory = dirname(await realpath(process.execPath));
+    const candidates = [
+        join(nodeDirectory, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+        resolve(nodeDirectory, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+        resolve(nodeDirectory, '..', 'share', 'nodejs', 'npm', 'bin', 'npm-cli.js'),
+    ];
+    for (const candidate of candidates) {
+        if (await stat(candidate).then(info => info.isFile(), () => false))
+            return candidate;
+    }
+    throw new Error('Cannot find npm beside the Node.js installation running Andorra. Install Node.js with npm, then run andorra update again.');
+}
+/** Keep the opaque, escaped shapes Windows error text can carry when matching it. */
+function normalizePathText(text) {
+    return text.replace(/\\{2,}/g, '\\').replace(/\\/g, '/').toLowerCase();
+}
+function containsPath(text, path) {
+    const target = resolve(path);
+    return normalizePathText(text).includes(normalizePathText(target));
+}
+/** Paths compare case-insensitively on Windows, where the filesystem does. */
+function samePath(a, b) {
+    const left = resolve(a);
+    const right = resolve(b);
+    return process.platform === 'win32' ? normalizePathText(left) === normalizePathText(right) : left === right;
+}
+const exists = (path) => stat(path).then(() => true, () => false);
+const isDirectory = (path) => stat(path).then(info => info.isDirectory(), () => false);
+/** The name and version a package directory declares, or undefined when it holds no readable manifest. */
+async function readManifest(directory) {
+    try {
+        const value = JSON.parse(await readFile(join(directory, 'package.json'), 'utf8'));
+        return value && typeof value === 'object' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The installed release's version, when the directory holds this package. */
+async function installedVersion(directory) {
+    const manifest = await readManifest(directory);
+    return manifest?.name === PACKAGE_NAME && typeof manifest.version === 'string' ? manifest.version : undefined;
+}
+/** npm prints the answer to `root` and `view` on its last line; anything before it is a notice. */
+function lastLine(output) {
+    return output.split(/\r?\n/).map(line => line.trim()).filter(Boolean).at(-1) ?? '';
+}
+function checkoutRefusal(packageRoot) {
+    return new Error([
+        `andorra update installs releases from npm, but this andorra runs from a source checkout at ${packageRoot}, so nothing was changed.`,
+        `To switch to the npm release, run: npm install -g ${PACKAGE_NAME}@latest`,
+        'That replaces an andorra command linked with npm link, and leaves the checkout itself as it is.',
+        'To keep using the checkout, update it from the checkout instead: git pull --ff-only, then npm ci and npm run build.',
+    ].join('\n'));
+}
+function notGlobalRefusal(packageRoot, entry) {
+    return new Error([
+        `andorra update replaces the global npm installation of ${PACKAGE_NAME} (${entry}), but this andorra runs from ${packageRoot}, so nothing was changed.`,
+        `Update that copy the way it was installed, or install the CLI globally with: npm install -g ${PACKAGE_NAME}@latest`,
+    ].join('\n'));
+}
+/**
+ * Walk each installed package directory — the top level and its scope directories — for the files
+ * npm materializes wholesale and Windows can hold open: native modules, which a live process loads
+ * as a DLL. A scope directory does not consume depth, so a scoped package like @scope/pkg/... is
+ * reached. Symlinks are skipped so a linked package is never probed twice.
+ */
+async function lockProbeTargets(modules) {
+    const targets = [];
+    let visited = 0;
+    const walk = async (directory, depth) => {
+        if (visited >= LOCK_PROBE_SCAN_LIMIT)
+            return;
+        const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            visited += 1;
+            if (visited > LOCK_PROBE_SCAN_LIMIT)
+                return;
+            if (entry.name === '.bin' || entry.isSymbolicLink())
+                continue;
+            const full = join(directory, entry.name);
+            if (!entry.isDirectory()) {
+                if (entry.name.endsWith('.node'))
+                    targets.push(full);
+                continue;
+            }
+            if (entry.name.startsWith('@') && depth === 0) {
+                await walk(full, 0);
+                continue;
+            }
+            if (depth < LOCK_PROBE_DEPTH)
+                await walk(full, depth + 1);
+        }
+    };
+    await walk(modules, 0);
+    return targets;
+}
+/** Suffix of the same-directory rename the probe performs and then undoes. */
+const REPLACEABLE_SUFFIX = '.andorra-replaceable';
+/**
+ * Decide whether npm can replace the installed package before it tries. npm replaces a global
+ * package by moving its directory aside and deleting it afterwards. On Windows the move fails while
+ * something inside is open without delete sharing — a process whose working directory is inside the
+ * package, or a file already waiting to be deleted. A native module a live process has loaded does
+ * not stop the move, only the delete afterwards; sweepRetired deals with that copy. A same-directory
+ * rename is exactly the operation that fails, and it changes nothing. Each native module is tried
+ * first, so a refusal can name the file.
+ */
+async function probeReplace(packageRoot) {
+    const modules = join(packageRoot, 'node_modules');
+    if (await isDirectory(modules)) {
+        for (const target of await lockProbeTargets(modules)) {
+            const probe = `${target}${REPLACEABLE_SUFFIX}`;
+            try {
+                await rename(target, probe);
+                await rename(probe, target);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                if (!(await exists(target)))
+                    continue;
+                return { state: 'locked', path: target, detail: error.message };
+            }
+        }
+    }
+    try {
+        const probe = `${packageRoot}${REPLACEABLE_SUFFIX}`;
+        await rename(packageRoot, probe);
+        try {
+            await rename(probe, packageRoot);
+        }
+        catch (error) {
+            throw new Error(`this update moved ${packageRoot} to ${probe} and could not move it back (${error.message}); rename the directory back before retrying.`);
+        }
+    }
+    catch (error) {
+        if (await exists(packageRoot))
+            return { state: 'locked', path: packageRoot, detail: error.message };
+        return { state: 'unknown', detail: error.message, path: packageRoot };
+    }
+    return { state: 'clear', detail: 'the installed package and every native module in it could be replaced' };
+}
+function probeRefusal(packageRoot, probe) {
+    const target = probe.path ?? packageRoot;
+    const where = samePath(target, packageRoot) ? `the installed package directory itself (${target})` : `the installed file ${target}`;
+    const guidance = probe.state === 'locked'
+        ? 'Something has it open in a way Windows will not let it be moved: most often a terminal or program whose working directory is inside the package, or a file that is still waiting to be deleted while a process holds it. Close that program — a plain retry cannot release it — then run andorra update again.'
+        : `The installed package could not be inspected or moved. Close any process using it and check the permissions on ${target}, then run andorra update again.`;
+    return new Error(`Refusing to update ${packageRoot}: ${where} cannot be replaced.\n${guidance}\nNothing was changed: the installed Andorra is untouched.`);
+}
+/**
+ * npm moves the release it replaces aside, as `.<name>-<random>` beside the package, and deletes it
+ * once the new release is in place. On Windows a native module that a running process still has
+ * loaded — another Andorra session, CodeGraph — survives that delete, so the copy stays behind and npm
+ * only warns. Every update deletes whatever such copies it can, its own and earlier ones, and returns
+ * the ones a process still holds. Only directories, never links, and only that exact name pattern.
+ */
+async function sweepRetired(entry) {
+    const scope = dirname(entry);
+    const retired = new RegExp(`^\\.${basename(entry).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-[A-Za-z0-9_-]+$`);
+    const held = [];
+    for (const item of await readdir(scope, { withFileTypes: true }).catch(() => [])) {
+        if (!item.isDirectory() || !retired.test(item.name))
+            continue;
+        const path = join(scope, item.name);
+        try {
+            await rm(path, { recursive: true, force: true });
+        }
+        catch {
+            held.push(path);
+        }
+    }
+    return held;
+}
+function heldNote(held) {
+    const one = held.length === 1;
+    return `npm could not delete ${one ? 'a replaced copy' : `${held.length} replaced copies`} of Andorra because a running process still has a file in ${one ? 'it' : 'them'} loaded: ${held.join(', ')}. The andorra command no longer uses ${one ? 'it' : 'them'}; andorra update deletes ${one ? 'it' : 'them'} once that process has exited.`;
+}
+/** Recover the concrete locked path from the failure npm actually reported, when it named one. */
+function reportedLockedFile(message, packageRoot) {
+    const patterns = [
+        /npm error syscall[^\n]*\n\s*npm error (?:path|dest)\s+(.+)/,
+        /npm error path\s+(.+)/,
+        /\b(?:path|dest)\s*[:=]\s*['"]?([A-Za-z]:[\\/][^\n'"]+|\/[^\n'"]+)/,
+    ];
+    const candidates = [];
+    for (const pattern of patterns) {
+        const match = pattern.exec(message);
+        if (match?.[1])
+            candidates.push(match[1].trim());
+    }
+    for (const match of message.matchAll(/[A-Za-z]:[\\/][^\n'"<>|?*]+/g))
+        candidates.push(match[0].trim().replace(/[.,;:)\]]+$/, ''));
+    for (const candidate of candidates) {
+        const normalized = candidate.replace(/[.,;:)\]]+$/, '');
+        if (containsPath(normalized, packageRoot) || containsPath(normalized, dirname(packageRoot)))
+            return normalized;
+    }
+    return undefined;
+}
+/**
+ * Describe a failed install from what is actually on disk afterwards. npm moves the previous
+ * release back when an install fails, so the old version usually still runs — but the message says
+ * so only after reading it, and never promises that a plain retry releases a locked file.
+ */
+function installFailureMessage(entry, version, outcome, cause) {
+    const front = `npm install --global ${PACKAGE_NAME}@${version} failed, so the update did not complete.`;
+    const blocked = outcome.locked
+        ? `\nThe locked path npm reported is ${outcome.locked}. Windows refused to replace it while a process holds it open. Stop that process; a plain retry cannot release the file.`
+        : '';
+    const state = outcome.installed
+        ? `\nThe installed Andorra at ${entry} is still version ${outcome.installed}, so the andorra command still runs. Fix the reported problem and run andorra update again.`
+        : `\nThe installed Andorra at ${entry} is missing or unreadable, so the andorra command may not run. Fix the reported problem, then reinstall with npm install -g ${PACKAGE_NAME}@latest.`;
+    return `${front}${blocked}${state}\n${cause.message}`;
+}
+/**
+ * Install one exact release globally. A failure that left the previous release in place and still
+ * looks like a transient Windows sharing violation is retried a bounded number of times, after
+ * checking that the package can be moved again; anything else is reported at once.
+ */
+async function installRelease(run, sleep, probe, npm, cwd, packageRoot, entry, version, previous) {
+    for (let attempt = 1; attempt <= INSTALL_ATTEMPTS; attempt += 1) {
+        try {
+            await run(process.execPath, [npm, 'install', '--global', `${PACKAGE_NAME}@${version}`, '--prefer-online', '--no-audit', '--no-fund'], cwd, { stream: true });
+            return { ok: true };
+        }
+        catch (error) {
+            const cause = error;
+            const installed = await installedVersion(entry);
+            const named = reportedLockedFile(cause.message, packageRoot);
+            if (attempt === INSTALL_ATTEMPTS || installed !== previous || !LOCK_FAILURE.test(cause.message)) {
+                return { ok: false, cause, locked: named, installed };
+            }
+            const again = await probe(packageRoot);
+            if (again.state !== 'clear')
+                return { ok: false, cause, locked: named ?? again.path, installed };
+            await sleep(INSTALL_RETRY_DELAY_MS);
+        }
+    }
+    /* c8 ignore next */
+    throw new Error('unreachable: the bounded npm install loop always returns');
+}
+/** True while the process exists; EPERM means it exists but belongs to another account. */
+function processRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function lockOwner(recorded) {
+    try {
+        const { pid, startedAt } = JSON.parse(recorded);
+        if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 0)
+            return undefined;
+        return { pid, startedAt: typeof startedAt === 'string' ? startedAt : undefined };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Polls while another updater holds the short-lived reclaim guard; reclaiming takes milliseconds. */
+const RECLAIM_GUARD_ATTEMPTS = 30;
+const RECLAIM_GUARD_DELAY_MS = 100;
+/** Codes a filesystem without hard links (FAT, exFAT) reports for link(). */
+const NO_HARD_LINKS = new Set(['EPERM', 'ENOTSUP', 'ENOSYS', 'EOPNOTSUPP']);
+/** Write the record beside the lock, so the lock never exists without the record in it. */
+async function stageRecord(lockPath, record) {
+    const staged = `${lockPath}.${randomUUID()}.tmp`;
+    await writeFile(staged, record, { flag: 'wx', mode: 0o600 });
+    return staged;
+}
+/** Create the lock with its record already inside; false when a lock already exists. */
+async function createLock(lockPath, record) {
+    const staged = await stageRecord(lockPath, record);
+    try {
+        await link(staged, lockPath);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'EEXIST')
+            return false;
+        if (!code || !NO_HARD_LINKS.has(code))
+            throw error;
+        // Without hard links fall back to an exclusive create, which leaves the lock empty for the
+        // moment between creating and writing it.
+        try {
+            await writeFile(lockPath, record, { flag: 'wx', mode: 0o600 });
+            return true;
+        }
+        catch (fallback) {
+            if (fallback.code === 'EEXIST')
+                return false;
+            throw fallback;
+        }
+    }
+    finally {
+        await unlink(staged).catch(() => { });
+    }
+}
+/** One reclaimer at a time, so a lock another updater just took over is never judged stale again. */
+async function takeReclaimGuard(guard, lockPath, breakLock, sleep) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            await writeFile(guard, JSON.stringify({ pid: process.pid }) + '\n', { flag: 'wx', mode: 0o600 });
+            return;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        if (attempt < RECLAIM_GUARD_ATTEMPTS) {
+            await sleep(RECLAIM_GUARD_DELAY_MS);
+            continue;
+        }
+        // A guard that outlives every poll was left by an updater killed while reclaiming.
+        if (!breakLock)
+            throw new Error(`Another update is recovering the lock at ${lockPath} (guard file ${guard}). Wait for it to finish. If no update is running, rerun with andorra update --break-lock.`);
+        await unlink(guard).catch(error => { if (error.code !== 'ENOENT')
+            throw error; });
+        breakLock = false;
+        attempt = 0;
+    }
+}
+/**
+ * Take the updater lock and return the record written into it. A lock whose recorded process is
+ * gone was left by an interrupted update (Ctrl+C, a closed terminal, a crash) and is reclaimed; one
+ * whose process still runs, or that does not name a process, is only broken with breakLock, because
+ * a process id can be reused.
+ */
+export async function acquireUpdateLock(lockPath, options = {}) {
+    const breakLock = options.breakLock === true;
+    const isRunning = options.isRunning ?? processRunning;
+    const sleep = options.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+    const record = JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString(), id: randomUUID() }) + '\n';
+    if (await createLock(lockPath, record))
+        return record;
+    const guard = `${lockPath}.reclaim`;
+    await takeReclaimGuard(guard, lockPath, breakLock, sleep);
+    try {
+        // Read the lock only once the guard is held: an updater that reclaimed it first has already
+        // replaced it with its own record, which then names a live process.
+        let recorded;
+        try {
+            recorded = await readFile(lockPath, 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (recorded === undefined) {
+            if (await createLock(lockPath, record))
+                return record;
+            throw new Error(`Another update took the lock at ${lockPath} while this one was checking it. Wait for it to finish.`);
+        }
+        const owner = lockOwner(recorded);
+        const holder = owner ? `process ${owner.pid}${owner.startedAt ? `, started ${owner.startedAt}` : ''}` : undefined;
+        const stale = owner !== undefined && owner.pid !== process.pid && !isRunning(owner.pid);
+        if (!stale && !breakLock) {
+            throw new Error(holder
+                ? `Another update (${holder}) is running and holds ${lockPath}. Wait for it to finish. If that process is not an Andorra update, rerun with andorra update --break-lock.`
+                : `An update lock at ${lockPath} does not record which process holds it, so it cannot be checked. If no update is running, rerun with andorra update --break-lock.`);
+        }
+        // Replace the lock in one rename, so the path never disappears and a new updater's exclusive
+        // create keeps failing throughout.
+        const staged = await stageRecord(lockPath, record);
+        try {
+            await rename(staged, lockPath);
+        }
+        catch (error) {
+            await unlink(staged).catch(() => { });
+            throw error;
+        }
+        options.notify?.(stale
+            ? `Removed a stale update lock left by ${holder}, which is no longer running.`
+            : `Broke the update lock at ${lockPath}${holder ? ` held by ${holder}` : ''}.`);
+        return record;
+    }
+    finally {
+        await unlink(guard).catch(() => { });
+    }
+}
+/**
+ * Remove the lock only while it still holds this updater's record; --break-lock may have replaced
+ * it. The reclaim guard is held across the read and the unlink, because a replacement lands only
+ * under that guard and must not arrive in between.
+ */
+async function releaseUpdateLock(lockPath, record, sleep) {
+    const guard = `${lockPath}.reclaim`;
+    // A guard that is never released leaves this lock behind instead of failing the update: it
+    // names this process, which is about to exit, so the next update reclaims it as stale.
+    try {
+        await takeReclaimGuard(guard, lockPath, false, sleep);
+    }
+    catch {
+        return;
+    }
+    try {
+        let current;
+        try {
+            current = await readFile(lockPath, 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (current === record)
+            await unlink(lockPath);
+    }
+    finally {
+        await unlink(guard).catch(() => { });
+    }
+}
+/**
+ * Replace the global npm installation this command runs from with the latest npm release.
+ *
+ * Only a global npm installation is updated. A source checkout — one that `npm link` exposes as the
+ * global command, or one started directly — is refused without changing anything, and so is any
+ * other copy (a project's own dependency, the desktop client's engine): each is updated the way it
+ * was installed. The release is resolved from the `latest` dist-tag once and installed by its exact
+ * version, so a tag that moves mid-update cannot install something other than what was reported,
+ * and a tag that points below the installed version is never followed down.
+ */
+export async function updateInstallation(options = {}) {
+    const run = options.run ?? runCommand;
+    const sleep = options.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+    const probe = options.probe ?? probeReplace;
+    const modulePath = await realpath(fileURLToPath(options.moduleUrl ?? import.meta.url));
+    const packageRoot = await realpath(resolve(dirname(modulePath), '..', '..'));
+    const manifest = await readManifest(packageRoot);
+    if (!manifest)
+        throw new Error(`This andorra does not run from an installed ${PACKAGE_NAME} package (no readable package.json in ${packageRoot}), so andorra update cannot update it.`);
+    if (manifest.name !== PACKAGE_NAME)
+        throw new Error(`Refusing to update an unrelated package: expected ${PACKAGE_NAME} in ${packageRoot}.`);
+    const current = typeof manifest.version === 'string' ? semver.valid(manifest.version) : null;
+    if (!current)
+        throw new Error(`The installed ${PACKAGE_NAME} at ${packageRoot} declares no valid version, so andorra update cannot compare it with npm's release. Reinstall it with npm install -g ${PACKAGE_NAME}@latest.`);
+    // A checkout is refused before npm is even located: nothing about it is this updater's to change.
+    if (await exists(join(packageRoot, '.git')))
+        throw checkoutRefusal(packageRoot);
+    const npm = options.npm ?? await npmCli();
+    const home = options.lockDirectory ?? configDirectory();
+    await mkdir(home, { recursive: true });
+    // npm runs outside the package it replaces: a working directory inside it would keep Windows from
+    // moving it, and a project's .npmrc in the caller's directory has no say over a global install.
+    const cwd = home;
+    let globalRoot;
+    try {
+        globalRoot = lastLine(await run(process.execPath, [npm, 'root', '--global'], cwd));
+    }
+    catch (error) {
+        throw new Error(`Could not ask npm where global packages are installed, so nothing was changed.\n${error.message}`);
+    }
+    if (!globalRoot)
+        throw new Error('npm did not report where global packages are installed, so nothing was changed.');
+    const entry = join(globalRoot, ...PACKAGE_NAME.split('/'));
+    const linked = await lstat(entry).then(info => info.isSymbolicLink(), () => false);
+    const resolvedEntry = await realpath(entry).catch(() => undefined);
+    const isEntry = resolvedEntry !== undefined && samePath(resolvedEntry, packageRoot);
+    if (isEntry && linked)
+        throw checkoutRefusal(packageRoot);
+    if (!isEntry)
+        throw notGlobalRefusal(packageRoot, entry);
+    const lockPath = join(home, 'update.lock');
+    const lock = await acquireUpdateLock(lockPath, { breakLock: options.breakLock, isRunning: options.isRunning, notify: options.notify, sleep });
+    try {
+        let reported;
+        try {
+            reported = lastLine(await run(process.execPath, [npm, 'view', `${PACKAGE_NAME}@${RELEASE_TAG}`, 'version', '--prefer-online'], cwd));
+        }
+        catch (error) {
+            throw new Error(`Could not look up the latest ${PACKAGE_NAME} release on npm, so nothing was changed. Check the network connection and npm registry settings, then run andorra update again.\n${error.message}`);
+        }
+        const latest = semver.valid(reported);
+        if (!latest)
+            throw new Error(`npm reported "${reported}" as the latest ${PACKAGE_NAME} release, which is not a version, so nothing was changed.`);
+        // Copies an earlier update could not delete are swept whenever the installation ends up current,
+        // so they go on the first run after the process holding them has exited.
+        const withSweep = async (summary) => {
+            const held = await sweepRetired(entry);
+            return held.length ? `${summary}\n${heldNote(held)}` : summary;
+        };
+        if (semver.eq(latest, current))
+            return withSweep(`Andorra ${current} is already the latest release on npm; nothing was installed.`);
+        if (semver.lt(latest, current)) {
+            return `The latest ${PACKAGE_NAME} release on npm is ${latest}, older than the installed ${current}. andorra update never downgrades, so nothing was changed.`;
+        }
+        const replaceable = await probe(packageRoot);
+        if (replaceable.state !== 'clear')
+            throw probeRefusal(packageRoot, replaceable);
+        const outcome = await installRelease(run, sleep, probe, npm, cwd, packageRoot, entry, latest, current);
+        if (!outcome.ok)
+            throw new Error(installFailureMessage(entry, latest, { locked: outcome.locked, installed: outcome.installed }, outcome.cause));
+        const installed = await installedVersion(entry);
+        if (installed !== latest) {
+            throw new Error(`npm reported success, but ${entry} now holds ${installed ? `version ${installed}` : 'no readable release'} instead of ${latest}. Check it with andorra --version, then run andorra update again.`);
+        }
+        return withSweep(`Updated Andorra from ${current} to ${latest}.\nInstalled ${PACKAGE_NAME}@${latest} from npm into ${entry}.`);
+    }
+    finally {
+        await releaseUpdateLock(lockPath, lock, sleep);
+    }
+}

package/dist/src/usage-analytics.d.ts

@@ -0,0 +1,48 @@
+export interface UsageModelRow {
+    /** The raw provider id the calls were journaled under; the aggregation identity. */
+    providerId: string;
+    /** The display name the configuration resolves the id to; `providerId` when it cannot. */
+    provider: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead: number;
+    savedInputEstimate: number;
+    bypassedTurns: number;
+}
+export interface UsageDayRow {
+    date: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead: number;
+    savedInputEstimate: number;
+    bypassedTurns: number;
+    models: UsageModelRow[];
+}
+export interface UsageAnalytics {
+    days: UsageDayRow[];
+    models: UsageModelRow[];
+    totals: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheRead: number;
+        savedInputEstimate: number;
+        bypassedTurns: number;
+        unestimatedTurns: number;
+    };
+    incomplete: boolean;
+    filesScanned: number;
+    windowDays: number;
+}
+/** A streaming collector, also usable with synthetic records in regression tests. */
+export declare function createUsageCollector(windowDays: number, now?: Date, resolveProvider?: (providerId: string) => string): {
+    add(record: unknown): void;
+    finish(filesScanned?: number, incomplete?: boolean): UsageAnalytics;
+};
+/**
+ * Local-only read, bounded by modified time, file count and record size, served from a per-file
+ * cache of the records the collector consumes. The replay visits the captured records in the same
+ * order a full read would — files sorted by name, lines in file order — so the answer is the one
+ * the equivalent full scan produces, whatever the cache happened to hold.
+ */
+export declare function readUsageAnalytics(directory: string, windowDays: number): Promise<UsageAnalytics>;