dedalus-cli 0.0.0-stage → 0.8.0

package/dist/cjs/cli/upgrade.js

@@ -0,0 +1,1191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addUpgradeCommands = exports.notifyIfOutdated = void 0;
+// Generated by the Scalar SDK Generator. Edits here are overwritten on the next generation.
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/**
+ * Release coordinates and the per-manager upgrade commands, fixed at generation time.
+ *
+ * Injected as one JSON literal rather than field-by-field interpolation: `JSON.stringify` is the
+ * escaper, so a repository or package name carrying a quote or a backslash cannot terminate a
+ * string literal in this file. Absent entries mean the config does not publish that channel.
+ */
+const RELEASE = {
+    repo: 'dedalus-labs/dedalus-cli',
+    npmPackage: 'dedalus-cli',
+    brewFormula: 'dedalus',
+    windowsArchive: true,
+};
+/**
+ * Whether this CLI registers `login`/`logout`, fixed at generation time. `uninstall` names `logout` as
+ * the way to clear a stored credential, and a CLI with no sign-in has neither the command nor the
+ * credential to clear.
+ */
+const HAS_LOGIN = true;
+/**
+ * Whether the release ships `install.sh`, fixed at generation time. That script can append a PATH line
+ * to a shell startup file, which `uninstall` then names as something removing the executable leaves.
+ */
+const HAS_INSTALL_SCRIPT = true;
+/**
+ * npm's package-name charset. The name reaches a spawned argument list, and on Windows that list goes
+ * through `cmd.exe` (a `.cmd` shim cannot be spawned without a shell), so a name outside the charset
+ * is never run. It is fixed at generation time, so this only ever rejects a config npm itself rejects.
+ */
+const NPM_PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/u;
+/** Resolves symlinks, falling back to the path itself when it cannot be read, with `/` separators. */
+const resolvedPath = (path) => {
+    let resolved = path;
+    try {
+        resolved = (0, node_fs_1.realpathSync)(path);
+    }
+    catch {
+        // An unreadable link target is not a reason to refuse; the unresolved path still classifies, and a
+        // replacement that cannot write it fails later with a real permission error.
+    }
+    return resolved.replace(/\\/gu, '/');
+};
+/**
+ * Classifies the running executable's install method from its resolved path.
+ *
+ * There is deliberately no install receipt to read. A receipt written by one channel would be absent
+ * for every other, so the path still has to be classified — and a receipt that drifted from reality
+ * (a binary moved, or a package manager adopting the path) would be believed over the filesystem.
+ *
+ * Symlinks are resolved first because that is what distinguishes the cases: Homebrew links
+ * `/usr/local/bin/<cmd>` into its Cellar, so only the real path shows which manager owns the file.
+ */
+const detectInstall = (binaryName) => {
+    const executable = process.execPath;
+    // A compiled standalone executable *is* the command; running under `node`/`bun` instead means this
+    // is the npm package (or a checkout of it), and the script's own path says which manager owns it.
+    if (!runsCompiled(executable, binaryName))
+        return detectPackageInstall();
+    const path = resolvedPath(executable);
+    // `Caskroom` as well as `Cellar`, and that is not redundant with the `homebrew`/`linuxbrew` segments
+    // beside it: on an **Intel** Mac Homebrew's prefix is `/usr/local`, so a cask stages its executable
+    // at `/usr/local/Caskroom/<token>/<version>/<bin>` — a path carrying none of the other three. Without
+    // this, such an install classified as self-managed and `upgrade` renamed a downloaded binary over the
+    // file inside the Caskroom, which is admin-owned on Intel Homebrew and so writable without `sudo`.
+    // Brew went on recording the old version and reverted the binary on the next `brew upgrade`. Apple
+    // Silicon and Linux casks were caught only because `/opt/homebrew` and `/home/linuxbrew` happen to
+    // contain a matching segment.
+    if (/\/(Cellar|Caskroom|homebrew|linuxbrew)\//u.test(path) && RELEASE.brewFormula) {
+        // A cask is upgraded and removed through `--cask`. The token is the formula's own lowercased name,
+        // which is what the generated cask is declared under, so one value serves both spellings.
+        const cask = /\/Caskroom\//u.test(path);
+        const kind = cask ? ['--cask'] : [];
+        const args = ['upgrade', ...kind, RELEASE.brewFormula];
+        const brew = brewProgram(path);
+        return {
+            kind: 'managed',
+            manager: 'Homebrew',
+            // `brew update` first because `brew upgrade` reads the local clone of the tap, which Homebrew
+            // refreshes at most once a day: without it a release this command has just announced is not
+            // there yet, and `brew upgrade` reports the old version as up to date and exits 0.
+            upgrade: `brew update && brew ${args.join(' ')}`,
+            remove: `brew uninstall ${cask ? '--cask ' : ''}${RELEASE.brewFormula}`,
+            ...(brew
+                ? {
+                    run: {
+                        program: brew,
+                        args,
+                        refresh: ['update'],
+                        installedVersions: ['list', ...kind, '--versions', RELEASE.brewFormula],
+                    },
+                }
+                : {}),
+        };
+    }
+    // `/usr/bin` is where a distro package manager installs; the documented direct download goes to
+    // `/usr/local/bin`, so it does not land here.
+    //
+    // Fails closed, always. Falling through to `self-managed` would overwrite a file dpkg or rpm owns —
+    // the manager's database still records the shipped checksum, so `dpkg -V` reports a mismatch and the
+    // next `apt upgrade` silently reverts the binary. Nothing this config publishes installs to
+    // `/usr/bin`, so a binary found there was put there by something else and is never ours to replace.
+    if (path.startsWith('/usr/bin/')) {
+        return {
+            kind: 'managed',
+            manager: "this system's package manager",
+            upgrade: `upgrade ${binaryName} the way it was installed; ${path} is owned by a package manager, so replacing it in place would corrupt that manager's database`,
+            remove: `remove ${binaryName} with the package manager that installed ${path}`,
+        };
+    }
+    // Windows is never replaced in place from here. Its release asset is a `.zip` rather than the
+    // `.tar.gz` the replace path unpacks, and Windows refuses to overwrite a running executable at all,
+    // so the honest answer is to name the archive and let the user put it in place. Reported as
+    // `managed` because the outcome is the same: someone else does the work.
+    if (process.platform === 'win32') {
+        return RELEASE.windowsArchive
+            ? {
+                kind: 'managed',
+                manager: 'a direct download',
+                upgrade: `download the latest ${binaryName}-windows-x64.zip from https://github.com/${RELEASE.repo}/releases/latest`,
+                remove: `remove ${path}`,
+            }
+            : // No Windows archive is published for this config, so naming one would be a permanent 404.
+                // Reported rather than guessed: whatever put this executable here is what has to replace it.
+                {
+                    kind: 'managed',
+                    manager: 'however it was installed',
+                    upgrade: `reinstall ${binaryName} the way it was installed; no Windows archive is published for it to download`,
+                    remove: `remove ${path}`,
+                };
+    }
+    return { kind: 'self-managed', path };
+};
+/**
+ * Whether this process is the compiled standalone executable rather than the npm package under a
+ * JavaScript runtime.
+ *
+ * The executable's own name says so, unless someone renamed it (`~/bin/wdg`); then the main module
+ * says so, since `bun build --compile` serves it from Bun's embedded filesystem (`/$bunfs/…`, or
+ * `B:/~BUN/…` on Windows) and no installed package ever runs from there.
+ */
+const runsCompiled = (executable, binaryName) => (0, node_path_1.basename)(executable).replace(/\.exe$/iu, '') === binaryName ||
+    /^(?:\/\$bunfs\/|[A-Za-z]:[\\/]~BUN[\\/])/u.test(process.argv[1] ?? '');
+/**
+ * The `brew` belonging to the prefix that owns `path`, or undefined when it cannot be located.
+ *
+ * Taken from the install's own prefix rather than looked up on `PATH`: a machine can carry two
+ * Homebrews (an Intel `/usr/local` one beside an Apple Silicon `/opt/homebrew` one, after a migration),
+ * and only the one whose Cellar holds this executable can upgrade it. Nothing found means the command
+ * is printed rather than run.
+ */
+const brewProgram = (path) => {
+    const prefix = /^(.*?)\/(?:Cellar|Caskroom)\//u.exec(path)?.[1];
+    if (!prefix)
+        return undefined;
+    const brew = `${prefix}/bin/brew`;
+    return (0, node_fs_1.existsSync)(brew) ? brew : undefined;
+};
+/**
+ * Classifies the npm package, run by a JavaScript runtime rather than as a compiled executable.
+ *
+ * Which manager owns it is read off the path of the running *script*, resolved through the bin link
+ * every manager creates, because each one keeps its global packages in its own tree. npm's tree has
+ * no fixed marker — its prefix is configurable — so it is what remains once the others are ruled out,
+ * and whether it is global at all is settled by asking npm when `upgrade` actually runs.
+ */
+const detectPackageInstall = () => {
+    const script = resolvedPath(process.argv[1] ?? '');
+    const pkg = RELEASE.npmPackage;
+    // Not inside any `node_modules`: this is a checkout being run directly, which only git can update.
+    if (!script.includes('/node_modules/') || !pkg) {
+        // Inside a `node_modules` yet not from an npm channel this config publishes: a package manager
+        // installed it from somewhere else, so that manager's command is the only one that can change it.
+        if (script.includes('/node_modules/')) {
+            return {
+                kind: 'managed',
+                manager: 'the package manager that installed it',
+                upgrade: `reinstall ${RELEASE.repo} with the package manager that installed it; no npm package is published for it`,
+                remove: 'remove it with the package manager that installed it',
+            };
+        }
+        return {
+            kind: 'managed',
+            manager: 'this checkout',
+            upgrade: 'git pull && npm install',
+            remove: 'remove the checkout',
+        };
+    }
+    // `npx`, `bunx` and `pnpm dlx` run from a cache rather than an install, and already fetch a newer
+    // release when asked for `@latest`; there is nothing installed to upgrade. `bunx` stages each run
+    // from its own cache in current releases and from `$TMPDIR/bunx-<uid>-<pkg>@<version>` in older ones,
+    // where a scoped name nests a `/` into that directory, so both spellings are matched. pnpm keeps its
+    // dlx cache under `pnpm/dlx`, or `pnpm-cache/dlx` on Windows.
+    const runner = /\/_npx\//u.test(script)
+        ? 'npx'
+        : /\/\.bun\/install\/cache\/|\/bunx-\d+-.*?\/node_modules\//u.test(script)
+            ? 'bunx'
+            : /\/pnpm(?:-cache)?\/dlx\//iu.test(script)
+                ? 'pnpm dlx'
+                : undefined;
+    if (runner) {
+        return {
+            kind: 'managed',
+            manager: runner,
+            upgrade: `${runner} ${pkg}@latest`,
+            remove: `nothing to remove; ${runner} keeps the package only in its cache`,
+        };
+    }
+    // Yarn's Plug'n'Play has no `node_modules` tree: it serves each package out of a zip, in the project's
+    // `.yarn/cache` or (Yarn 4's default) the global `~/.yarn/berry/cache`, and sets `process.versions.pnp`.
+    // Either way the package is a project dependency whose version is the project's lockfile's to set,
+    // and the zip's path says nothing about which project. Yarn exports the project root as `PROJECT_CWD`
+    // for the scripts and bins it runs, which is the best name available for it.
+    if (/\.zip\/node_modules\//u.test(script) || process.versions['pnp']) {
+        const project = process.env['PROJECT_CWD'];
+        return {
+            kind: 'managed',
+            manager: `Yarn Plug'n'Play${project ? ` in ${project}` : ''}`,
+            upgrade: `upgrade ${pkg} in the package.json that lists it, with the project's Yarn`,
+            remove: `remove ${pkg} from the package.json that lists it, with the project's Yarn`,
+        };
+    }
+    const safe = NPM_PACKAGE_NAME.test(pkg);
+    const bunRoot = /^(.*)\/install\/global\/node_modules\//u.exec(script)?.[1];
+    if (bunRoot) {
+        // Bun's own binary sits beside its global tree (`$BUN_INSTALL/bin/bun`); `bun` on PATH otherwise.
+        const local = (0, node_path_1.join)(bunRoot, 'bin', process.platform === 'win32' ? 'bun.exe' : 'bun');
+        const bun = (0, node_fs_1.existsSync)(local) ? local : 'bun';
+        return managerInstall('Bun', bun, ['add', '-g', `${pkg}@latest`], `bun remove -g ${pkg}`, safe);
+    }
+    // pnpm's global tree is `<PNPM_HOME>/global/<layout version>/`, holding its `.pnpm` store or the
+    // `node_modules` linked from it. Matched on that layout rather than on a `pnpm` segment, because
+    // `PNPM_HOME` is whatever the user set (`~/.pnpm-home`, say), and nothing else nests a numbered
+    // directory under `global` — Bun's and Yarn's trees put `node_modules` directly beneath it.
+    if (/\/\.?pnpm\/global\/|\/global\/\d+\/(?:\.pnpm|node_modules)\//iu.test(script)) {
+        return managerInstall('pnpm', 'pnpm', ['add', '-g', `${pkg}@latest`], `pnpm remove -g ${pkg}`, safe);
+    }
+    // Yarn classic keeps its global tree under `~/.config/yarn/global` and, on Windows,
+    // `%LOCALAPPDATA%\Yarn\Data\global`, hence the optional segment and the case-insensitive match.
+    if (/\/yarn\/(?:data\/)?global\/node_modules\//iu.test(script)) {
+        return managerInstall('Yarn', 'yarn', ['global', 'add', `${pkg}@latest`], `yarn global remove ${pkg}`, safe);
+    }
+    // The npm that ships beside the running `node`, which is the one that installed into this runtime's
+    // global tree; `npm` on PATH only when it is not there. It is also no less trusted than the `node`
+    // already executing this file, which the bin link's shebang resolved the same way.
+    const local = (0, node_path_1.join)((0, node_path_1.dirname)(process.execPath), process.platform === 'win32' ? 'npm.cmd' : 'npm');
+    const npm = (0, node_fs_1.existsSync)(local) ? local : 'npm';
+    const install = managerInstall('npm', npm, ['install', '-g', `${pkg}@latest`], `npm uninstall -g ${pkg}`, safe);
+    return install.kind === 'managed' && install.run
+        ? { ...install, run: { ...install.run, npmGlobal: { script, pkg } } }
+        : install;
+};
+/** A managed install whose upgrade `upgrade` runs, unless the package name failed the charset check. */
+const managerInstall = (manager, program, args, remove, safe) => ({
+    kind: 'managed',
+    manager,
+    upgrade: `${(0, node_path_1.basename)(program).replace(/\.(cmd|exe)$/iu, '')} ${args.join(' ')}`,
+    remove,
+    ...(safe ? { run: { program, args } } : {}),
+});
+/**
+ * Where npm keeps global packages, or undefined when npm cannot say.
+ *
+ * Asked rather than derived, because the global prefix is user configuration (`npm config set prefix`
+ * is the documented fix for a root-owned one) and no path rule recovers it.
+ */
+const npmGlobalRoot = (program) => {
+    const result = spawnManager(program, ['root', '-g'], {
+        encoding: 'utf8',
+        timeout: MANAGER_QUERY_TIMEOUT_MS,
+    });
+    const root = result.status === 0 ? String(result.stdout).trim() : '';
+    return root ? resolvedPath(root) : undefined;
+};
+/** How long `npm root -g` may take; it reads config and prints a path, so this is generous. */
+const MANAGER_QUERY_TIMEOUT_MS = 15_000;
+/**
+ * Spawns a package manager with its arguments, the one way that works on each platform.
+ *
+ * macOS and Linux get an argument list and no shell. Windows package-manager shims are `.cmd` files,
+ * which Node refuses to spawn without a shell, so there the command runs through `cmd.exe` as a single
+ * line built here: passing an argument list alongside `shell: true` is deprecated (DEP0190), and
+ * Node would only join it unquoted anyway. The program is always quoted, because a profile path can
+ * carry `&`, `(` or `^` as well as spaces; every argument is a fixed word, the charset-checked package
+ * name, or the formula name, so none of them needs quoting.
+ */
+const spawnManager = (program, args, options) => {
+    if (process.platform !== 'win32')
+        return (0, node_child_process_1.spawnSync)(program, [...args], options);
+    // A `"` cannot be escaped inside a `cmd.exe` quoted string, and no Windows path contains one, so
+    // refusing it costs nothing and keeps the quoting sound.
+    if (program.includes('"'))
+        throw new Error(`refusing to run ${program}: its path contains a quote`);
+    return (0, node_child_process_1.spawnSync)([`"${program}"`, ...args].join(' '), { ...options, shell: true });
+};
+/**
+ * Whether `path` lies inside `directory`.
+ *
+ * Case-insensitive on Windows, whose filesystem is, and where `realpathSync` keeps whatever case the
+ * path was spelled in — so `argv[1]` reached through a PATH entry typed `c:\users` and npm's own
+ * `C:\Users` answer would otherwise never match.
+ */
+const isInside = (path, directory) => process.platform === 'win32'
+    ? path.toLowerCase().startsWith(`${directory.toLowerCase()}/`)
+    : path.startsWith(`${directory}/`);
+/**
+ * The package manager the project at `project` uses, read off what it has on disk: pnpm's `.pnpm`
+ * store in the script's own path, then the lockfile, and npm when nothing else is recorded.
+ *
+ * Named rather than turned into a command. The right command depends on what this cannot see — which
+ * workspace member lists the CLI, and which major version of Yarn the project runs — and a command
+ * that is wrong for either fails or edits a `package.json` other than the one that lists it.
+ */
+const projectManager = (project, script) => {
+    /** Whether the project root holds this file, which is how a lockfile names the manager. */
+    const has = (file) => (0, node_fs_1.existsSync)((0, node_path_1.join)(project, file));
+    if (script.includes('/node_modules/.pnpm/') || has('pnpm-lock.yaml'))
+        return 'pnpm';
+    if (has('yarn.lock'))
+        return 'Yarn';
+    if (has('bun.lock') || has('bun.lockb'))
+        return 'Bun';
+    return 'npm';
+};
+/**
+ * Settles what {@link detectInstall} leaves to a subprocess: whether an npm install is the global one
+ * this runtime's npm owns, a project's dependency, or another npm's global tree.
+ *
+ * npm links a project dependency and a global install the same way, so the path alone cannot tell
+ * them apart; only `npm root -g` can. Asked by `upgrade`, `upgrade --check` and `uninstall` — explicit
+ * commands, where one subprocess is cheap — and never by the daily notice, which only ever says to run
+ * `upgrade`, where this is settled before anything is done.
+ *
+ * A `package.json` beside the `node_modules` makes it a project's dependency: that project's lockfile
+ * decides its version, so neither a global upgrade nor a global uninstall is right for it — the global
+ * command would add a second copy, or remove a different one. Without one it is a global tree belonging
+ * to a different npm (Volta's per-package images, a second Node install): the global command is still
+ * right, but only *that* npm can run it, so it is printed rather than run through this one.
+ */
+const settledInstall = (install) => {
+    if (install.kind !== 'managed' || !install.run?.npmGlobal)
+        return install;
+    const { script, pkg } = install.run.npmGlobal;
+    const root = npmGlobalRoot(install.run.program);
+    if (!root || isInside(script, root))
+        return install;
+    const project = script.slice(0, script.indexOf('/node_modules/'));
+    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(project, 'package.json'))) {
+        const manager = projectManager(project, script);
+        return {
+            kind: 'managed',
+            manager: `${manager}, as a dependency of the project in ${project}`,
+            upgrade: `upgrade ${pkg} in the package.json that lists it, with the project's ${manager}`,
+            remove: `remove ${pkg} from the package.json that lists it, with the project's ${manager}`,
+        };
+    }
+    return {
+        kind: 'managed',
+        manager: `a different npm than the one beside this Node.js, into ${project}`,
+        upgrade: install.upgrade,
+        remove: install.remove,
+    };
+};
+/**
+ * Runs the owning manager's upgrade, with its output on this terminal.
+ *
+ * Delegated rather than reproduced: the manager records what it installed, so only its own upgrade
+ * leaves that record true. A spawn that fails outright (the manager is gone from PATH) prints the
+ * command so the user can run it themselves. Returns whether the manager ran and succeeded.
+ */
+const runManagerUpgrade = (binaryName, install, run) => {
+    process.stderr.write(`${binaryName} was installed with ${install.manager}. Upgrading with:\n  ${install.upgrade}\n\n`);
+    // A failed refresh does not stop the upgrade: the manager has said why on this terminal, the local
+    // copy may already have the release, and `confirmManagerUpgrade` catches the case where it does not.
+    if (run.refresh)
+        spawnManager(run.program, run.refresh, { stdio: 'inherit' });
+    let result;
+    try {
+        result = spawnManager(run.program, run.args, { stdio: 'inherit' });
+    }
+    catch (error) {
+        result = { error: error };
+    }
+    // `cmd.exe` reports a program it cannot find as status 9009 rather than as a spawn error, so on
+    // Windows that status is the same "the manager is not installed" case.
+    if (result.error || (process.platform === 'win32' && result.status === 9009)) {
+        const reason = result.error ? result.error.message : `${(0, node_path_1.basename)(run.program)} was not found`;
+        process.stderr.write(`error: could not run ${install.manager}: ${reason}\nRun it yourself:\n  ${install.upgrade}\n`);
+        process.exitCode = 1;
+        return false;
+    }
+    // The manager has already said why on this terminal. Its own status is named but not passed
+    // through: npm exits 243 for a permission error and anything may exit 2, which a script reading
+    // this command's documented statuses would take for a usage error. 1 is "the command failed".
+    if (result.status !== 0) {
+        process.stderr.write(`error: ${install.manager} exited with ${result.status === null ? `signal ${result.signal}` : `status ${result.status}`}\n`);
+        process.exitCode = 1;
+        return false;
+    }
+    return true;
+};
+/**
+ * Fails an upgrade that the manager reported as a success without installing anything newer.
+ *
+ * `brew upgrade` exits 0 on a formula it believes is current, so a tap behind the release looks like a
+ * successful upgrade to a script chaining `upgrade && …`. Refreshing first cannot rule that out: the
+ * refresh can fail, and a tap published through pull requests lags until the pull request merges.
+ *
+ * The release is only asked for once the version is known not to have moved, and exiting 0 stays right
+ * when nothing newer exists. Not being able to ask is a warning rather than a failure, because the
+ * manager did succeed and most such runs are simply already current.
+ */
+const confirmManagerUpgrade = async (binaryName, version, install, run, query) => {
+    const result = spawnManager(run.program, query, {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: MANAGER_QUERY_TIMEOUT_MS,
+    });
+    // Several versions when Homebrew kept the old keg, so any other version here means one was installed.
+    const installed = result.status === 0 ? String(result.stdout).trim().split(/\s+/u).slice(1) : [];
+    if (installed.length === 0 || installed.some((entry) => entry !== version))
+        return;
+    let tag;
+    try {
+        tag = await withTimeout((signal) => latestTag(signal), UPGRADE_CHECK_TIMEOUT_MS, 'the release check');
+    }
+    catch (error) {
+        process.stderr.write(`warning: could not confirm the upgrade: ${error.message}\n`);
+        return;
+    }
+    if (!isNewerRelease(tag, version))
+        return;
+    process.stderr.write(`error: ${install.manager} still has ${binaryName} ${version}, but ${tag} is released.\n` +
+        `The release may not have reached its tap yet. Try again later, or run:\n  ${install.upgrade}\n`);
+    process.exitCode = 1;
+};
+/** Maps this machine onto the release asset built for it, matching the names the release step packs. */
+const detectTarget = () => {
+    const platforms = { darwin: 'darwin', linux: 'linux' };
+    const architectures = { x64: 'x64', arm64: 'arm64' };
+    const os = platforms[process.platform];
+    const arch = architectures[process.arch];
+    if (!os || !arch) {
+        throw new Error(`no release binary is published for ${process.platform}/${process.arch}`);
+    }
+    return `${os}-${arch}`;
+};
+/** Latest published release tag, read from the GitHub API so the command can report the version. */
+const latestTag = async (signal) => {
+    const response = await fetch(`https://api.github.com/repos/${RELEASE.repo}/releases/latest`, {
+        // `connection: close` because the abort below bounds the *request*, not the process. Node keeps
+        // a pooled keep-alive socket referenced after the response resolves, so an unawaited check still
+        // held the process open for seconds after the command's own work finished — the delay this is
+        // supposed to have no part in. Bun does not exhibit it; the npm channel runs on Node.
+        headers: { accept: 'application/vnd.github+json', connection: 'close' },
+        ...(signal ? { signal } : {}),
+    });
+    if (!response.ok) {
+        // An unauthenticated read past GitHub's per-address limit is refused with 403 or 429, not with the
+        // release missing. Said as such, because the status alone reads like a broken release.
+        if (response.status === 403 || response.status === 429) {
+            throw new Error(`GitHub refused the release lookup (HTTP ${response.status}), usually the unauthenticated API rate limit for this network; try again later`);
+        }
+        throw new Error(`could not read the latest release (HTTP ${response.status})`);
+    }
+    // Capped like the archive read is. A release payload is a few kilobytes of JSON, and this is the
+    // request the *daily notifier* makes unasked — so a redirect or captive proxy answering with an
+    // endless body inside the deadline would buffer it into a CLI the user only ran to do something
+    // else. `json()` offers no way to bound it, so the bytes are read first and parsed after.
+    const body = JSON.parse((await readCapped(response, response.url || 'the latest release', MAX_METADATA_BYTES)).toString('utf8'));
+    if (typeof body.tag_name !== 'string' || body.tag_name.length === 0) {
+        throw new Error('the latest release has no tag');
+    }
+    // Validated here, not only where a *cached* tag is printed. This value goes straight into a download
+    // URL and onto the terminal, and the same reasoning applies to both paths: a git refname cannot hold
+    // a control character, so one that does was not written by a release — and writing it raw would let
+    // cursor-control sequences rewrite the surrounding lines and forge an instruction that appears to
+    // come from the CLI itself. Checking the cache and trusting the live response left the guard on the
+    // path that had already been through it and off the path the value arrives by.
+    if (!RELEASE_TAG.test(body.tag_name)) {
+        throw new Error('the latest release has an unusable tag');
+    }
+    return body.tag_name;
+};
+/**
+ * Fetches one release asset, bounded by both a deadline and a size cap.
+ *
+ * Used for the archive and for `checksums.txt`, so both halves of the integrity check are bounded the
+ * same way — a release that answers one of them slowly cannot leave the command waiting indefinitely.
+ */
+const download = async (url) => 
+// The *whole* read runs inside the deadline, headers and body alike. Bounding only the `fetch` call
+// leaves the body unbounded: a proxy that answers 200 and then stops sending bytes resolves the
+// response, the timer is cleared, and the command hangs forever on the read — the exact failure
+// this exists to prevent, one step later than where it was first looked for.
+withTimeout(async (signal) => {
+    const response = await fetch(url, { signal });
+    if (!response.ok)
+        throw new Error(`could not download ${url} (HTTP ${response.status})`);
+    return readCapped(response, url);
+}, DOWNLOAD_TIMEOUT_MS, url);
+/**
+ * Reads a response body, refusing one larger than {@link MAX_DOWNLOAD_BYTES}.
+ *
+ * Read chunk by chunk with a running total rather than through `arrayBuffer()`: that buffers the
+ * whole body *before* any length can be checked, so a cap applied afterwards has already paid the
+ * memory it was meant to refuse. `content-length` is checked first where the server sends one,
+ * because that refuses the transfer before a byte of it arrives — but it is a claim, not a
+ * guarantee, so the running total is what actually enforces the bound.
+ *
+ * Buffered whole once read, because the checksum is over the whole archive. A compiled executable
+ * for one platform is tens of megabytes, so the cap is loose enough never to reject a real asset.
+ */
+const readCapped = async (response, url, limit = MAX_DOWNLOAD_BYTES) => {
+    // Reported in megabytes against whichever limit is in force, since both are whole megabytes. A unit
+    // switch would be dead code today; add one here if a sub-megabyte cap is ever introduced.
+    /** The refusal, named once because the declared length and the running total both raise it. */
+    const tooLarge = () => new Error(`${url} is larger than the ${Math.round(limit / 1_000_000)}MB limit`);
+    const declared = Number(response.headers.get('content-length') ?? '');
+    if (Number.isFinite(declared) && declared > limit)
+        throw tooLarge();
+    // No body to stream (a HEAD-like response, or a stub in a test) leaves `arrayBuffer` as the only
+    // reader; it is bounded by the same cap on the way out.
+    if (!response.body) {
+        const whole = Buffer.from(await response.arrayBuffer());
+        if (whole.byteLength > limit)
+            throw tooLarge();
+        return whole;
+    }
+    const chunks = [];
+    let total = 0;
+    const reader = response.body.getReader();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > limit) {
+            // Released so the connection is torn down rather than left draining in the background.
+            await reader.cancel().catch(() => { });
+            throw tooLarge();
+        }
+        chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+};
+/** Upper bound on a release asset, so a wrong URL cannot buffer an unbounded body into memory. */
+const MAX_DOWNLOAD_BYTES = 250_000_000;
+/**
+ * Upper bound on an API read, which is the release JSON and nothing else.
+ *
+ * Far tighter than the asset cap because the shape is known: a `releases/latest` payload is a few
+ * kilobytes, and generous room for release notes still leaves this three orders of magnitude below
+ * the archive bound. This is the request the daily check makes without being asked, so it is the one
+ * that most needs a bound the user never has to think about.
+ */
+const MAX_METADATA_BYTES = 2_000_000;
+/** How long the downloaded executable may take to answer `--version` before it counts as broken. */
+const VERSION_PROBE_TIMEOUT_MS = 15_000;
+/** Long enough for a large archive on a slow connection, short enough to fail rather than hang. */
+const DOWNLOAD_TIMEOUT_MS = 120_000;
+/** How long `upgrade` waits on the release API before giving up; it is interactive, so it is short. */
+const UPGRADE_CHECK_TIMEOUT_MS = 10_000;
+/**
+ * Runs one request under a deadline, so a stalled connection fails instead of hanging.
+ *
+ * `fetch` has no default timeout, and a captive portal or a stalled proxy completes the handshake
+ * and then never answers — which left `upgrade` sitting with nothing on screen, indefinitely, while
+ * the daily notifier on the same machine aborted after two seconds. `.agents/security.md` asks for
+ * every request a generated runtime makes to be bounded.
+ */
+const withTimeout = async (run, ms, what) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), ms);
+    try {
+        return await run(controller.signal);
+    }
+    catch (error) {
+        // `AbortError` names the signal, not the cause, so it is reported as what the user experienced.
+        if (controller.signal.aborted)
+            throw new Error(`${what} timed out after ${Math.round(ms / 1000)}s`);
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+/**
+ * Replaces this executable with the one from `tag`, verified against the release's checksums.
+ *
+ * The integrity check the release's own `checksums.txt` exists for, with bounds on both reads: the archive and
+ * the checksum file come from one release, so this catches a corrupted or truncated download rather
+ * than a compromised release.
+ */
+const replaceExecutable = async (executable, tag, binaryName) => {
+    const asset = `${binaryName}-${detectTarget()}.tar.gz`;
+    const base = `https://github.com/${RELEASE.repo}/releases/download/${tag}`;
+    const archive = await download(`${base}/${asset}`);
+    const checksums = (await download(`${base}/checksums.txt`)).toString('utf8');
+    // Same two-field `sha256sum` format the release publishes: "<hash>  <file>".
+    const expected = checksums
+        .split('\n')
+        .map((line) => line.trim().split(/\s+/u))
+        .find((fields) => fields[1] === asset)?.[0];
+    if (!expected)
+        throw new Error(`the release publishes no checksum for ${asset}`);
+    const actual = (0, node_crypto_1.createHash)('sha256').update(archive).digest('hex');
+    if (actual !== expected.toLowerCase()) {
+        throw new Error(`checksum mismatch for ${asset} (expected ${expected}, got ${actual})`);
+    }
+    const staging = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), `${binaryName}-upgrade-`));
+    // Written beside the target rather than in the temp dir, so the final rename is within one
+    // filesystem and therefore atomic — a cross-device rename would fall back to a copy that can be
+    // interrupted halfway, leaving a truncated executable on the user's PATH.
+    const pending = (0, node_path_1.join)((0, node_path_1.dirname)(executable), `.${binaryName}.upgrade`);
+    try {
+        const archivePath = (0, node_path_1.join)(staging, asset);
+        (0, node_fs_1.writeFileSync)(archivePath, archive);
+        // `tar` is present on every platform this upgrades on (macOS and Linux); Windows self-upgrades
+        // are unreachable because its asset is a `.zip` no release publishes a `.tar.gz` for.
+        //
+        // The child's PATH is pinned, and resolving `tar` absolutely is not enough on its own: GNU tar
+        // implements `-z` by *running* `gzip`, looked up through the inherited PATH (verified against GNU
+        // tar 1.35). Under `sudo` on a system whose sudoers has no `secure_path` — several distributions
+        // ship none — the user's own `gzip` would then run as root, which is the hole pinning `tar` was
+        // meant to close, one process along. bsdtar on macOS decompresses in-process and never looks.
+        // The rest of the environment is passed through, so locale and proxy settings still apply.
+        (0, node_child_process_1.execFileSync)(tarProgram(), ['-xzf', archivePath, '-C', staging], {
+            env: { ...process.env, PATH: TRUSTED_TOOL_PATH },
+        });
+        const extracted = (0, node_path_1.join)(staging, binaryName);
+        // The archive layout is a release-time contract this cannot verify ahead of time, and a bare
+        // ENOENT from the read below matches none of the guidance `upgrade` prints, so it is checked
+        // here, naming the archive rather than letting a bare ENOENT surface from the read below.
+        if (!(0, node_fs_1.existsSync)(extracted)) {
+            throw new Error(`${asset} did not contain the expected ${binaryName} executable`);
+        }
+        // `wx` rather than a plain write: the path is a fixed, predictable name in the directory the real
+        // executable lives in, and this command tells the user to re-run it under `sudo`. A plain
+        // `writeFileSync` follows a symlink, so anyone who can create that one name in a group-writable
+        // install directory chooses a file for root to overwrite with content they also control. `wx` is
+        // `O_CREAT|O_EXCL`, which refuses an existing file and a symlink alike, so the only way past it is
+        // a live race rather than a planted link.
+        //
+        // Unlinked first, because `wx` refuses a *stale* file too. The `finally` below cleans up after this
+        // process, but a run killed outright — SIGKILL, OOM, power loss — leaves the name behind with no
+        // cleanup having run, and the next `upgrade` would then fail with a bare `EEXIST` naming a hidden
+        // dotfile the user has no reason to know about. That message matches none of the guidance this
+        // command prints. Removing the link rather than following it keeps the property: a name re-created
+        // between these two lines makes the write fail, which is the right outcome.
+        (0, node_fs_1.rmSync)(pending, { force: true });
+        (0, node_fs_1.writeFileSync)(pending, (0, node_fs_1.readFileSync)(extracted), { flag: 'wx' });
+        (0, node_fs_1.chmodSync)(pending, 0o755);
+        // Run before it replaces anything, exactly as `install.sh` does. The checksum proves the archive
+        // is the one the release published; it says nothing about whether this machine can execute what
+        // came out of it — a 32-bit userland on a 64-bit kernel reports a 64-bit `uname -m`, and a release
+        // can simply be built wrong. Replacing the working binary with one that cannot run takes `upgrade`
+        // with it, so the tool that would recover the install is the one just broken. Failing here leaves
+        // the old executable in place, and the `finally` below removes the staged file.
+        //
+        // The staged path is absolute and `execFileSync` takes no shell, so nothing here is interpreted.
+        // Output is discarded: this asks whether the binary runs, not what it says. The environment is the
+        // real one, not the pinned `PATH` the extraction uses — that pin exists because `tar` resolves
+        // `gzip` through it, while this runs a known absolute path, and stripping the environment would
+        // only risk failing a build that runs perfectly well in the one it is about to be installed into.
+        // Bounded, because a build that hangs instead of failing would otherwise hang `upgrade` with it.
+        // `--version` is answered by the program before any command runs and makes no request — the
+        // update check skips it — so a working build is done in well under a second.
+        try {
+            (0, node_child_process_1.execFileSync)(pending, ['--version'], {
+                stdio: 'ignore',
+                timeout: VERSION_PROBE_TIMEOUT_MS,
+                killSignal: 'SIGKILL',
+            });
+        }
+        catch (error) {
+            const hung = error.code === 'ETIMEDOUT';
+            throw new Error(hung
+                ? `the downloaded ${binaryName} did not answer --version within ${VERSION_PROBE_TIMEOUT_MS / 1000}s; nothing was changed`
+                : `the downloaded ${binaryName} does not run on this machine (${process.platform} ${process.arch}); nothing was changed`);
+        }
+        // Replacing a running executable is legal on POSIX: the running process keeps the old inode
+        // open, and the next invocation resolves the new one.
+        (0, node_fs_1.renameSync)(pending, executable);
+    }
+    finally {
+        (0, node_fs_1.rmSync)(staging, { recursive: true, force: true });
+        // A failure between the write and the rename — ENOSPC, a signal — would otherwise leave a
+        // partial dotfile next to the real executable, owned by root in the `sudo upgrade` flow this
+        // command tells the user to run.
+        (0, node_fs_1.rmSync)(pending, { force: true });
+    }
+};
+/**
+ * The directories a trusted system tool is looked up in, and the `PATH` the extraction runs with.
+ *
+ * Both uses need the same answer, so they share one value: `tar` is resolved from here rather than
+ * through the caller's `PATH`, and the child is given this as its `PATH` because GNU tar implements
+ * `-z` by running `gzip`, which it finds the ordinary way. These two cover macOS and every mainstream
+ * Linux distribution; an image that keeps `tar` elsewhere is handled by the ownership-checked search
+ * below instead of by widening this.
+ */
+const TRUSTED_TOOL_PATH = '/usr/bin:/bin';
+/**
+ * Absolute path to `tar`, so the extraction cannot be redirected by `PATH`.
+ *
+ * `upgrade` tells the user to re-run under `sudo` when the executable is not writable, and macOS
+ * ships no `secure_path` in its default sudoers — so a bare `tar` would resolve through the invoking
+ * user's `PATH` and run a file they control as root. The two standard locations are tried first
+ * because they cover macOS and every mainstream Linux distribution.
+ *
+ * The `PATH` search that follows is for the images that keep `tar` elsewhere (`/usr/local/bin` under
+ * Nix or Homebrew-on-Linux). Absolute entries alone are not enough — `/tmp/evil` is absolute — so a
+ * candidate is accepted only if root owns it and no one else can write it or the directory holding
+ * it. That is the property that matters under `sudo`, and it is what a store path or a distribution
+ * prefix has while an attacker-controlled directory does not. Nothing found means an outright
+ * failure: there is no safe way to run a program this cannot locate.
+ */
+const tarProgram = () => {
+    for (const candidate of TRUSTED_TOOL_PATH.split(':').map((directory) => `${directory}/tar`)) {
+        if ((0, node_fs_1.existsSync)(candidate))
+            return candidate;
+    }
+    for (const entry of (process.env['PATH'] ?? '').split(':')) {
+        if (!entry.startsWith('/'))
+            continue;
+        const candidate = (0, node_path_1.join)(entry, 'tar');
+        if ((0, node_fs_1.existsSync)(candidate) && rootOwnedAndProtected(candidate) && rootOwnedAndProtected(entry))
+            return candidate;
+    }
+    throw new Error('no trusted tar was found on PATH, so the archive cannot be extracted');
+};
+/** Whether root owns the path and neither group nor other can write it — checked without following links. */
+const rootOwnedAndProtected = (path) => {
+    try {
+        const stats = (0, node_fs_1.lstatSync)(path);
+        return stats.uid === 0 && (stats.mode & 0o022) === 0;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Whether `tag` names a release newer than the running `version`.
+ *
+ * "Different" is not "newer". `releases/latest` follows whatever release is currently marked latest,
+ * so deleting a broken release moves it *backwards* — and a bare inequality would then tell a user
+ * on 2.0.1 that "a new release is available: 2.0.1 → v2.0.0". Release-please, which every generated
+ * CLI publishes through, produces strict semver, so that is what is compared; anything else falls
+ * back to the inequality, on the grounds that an imprecise word beats never mentioning a release at
+ * all for a versioning scheme this cannot read.
+ */
+const isNewerRelease = (tag, version) => {
+    const candidate = tag.replace(/^v/u, '');
+    const latest = parseVersion(candidate);
+    const current = parseVersion(version);
+    if (!latest || !current)
+        return candidate !== version;
+    for (let index = 0; index < latest.release.length; index += 1) {
+        const next = latest.release[index] ?? 0;
+        const now = current.release[index] ?? 0;
+        if (next !== now)
+            return next > now;
+    }
+    // Same `major.minor.patch`: semver puts a prerelease below the release it leads to, so `1.2.0` is
+    // newer than `1.2.0-rc.1`.
+    if (latest.prerelease === current.prerelease)
+        return false;
+    if (!latest.prerelease)
+        return true;
+    if (!current.prerelease)
+        return false;
+    return comparePrerelease(latest.prerelease, current.prerelease) > 0;
+};
+/**
+ * Orders two semver prerelease strings, returning >0 when `left` is the newer one.
+ *
+ * Semver's dotted rule, not a string comparison: identifiers are compared field by field, numeric
+ * ones numerically and the rest lexically, with numeric sorting below alphanumeric and a shorter
+ * prefix below its extension. Comparing the whole string instead put `rc.10` *below* `rc.9`, which a
+ * long prerelease train reaches routinely — a user on `rc.9` would then never be told about `rc.10`,
+ * and running `upgrade` would install it while calling the result a move rather than an upgrade.
+ */
+const comparePrerelease = (left, right) => {
+    const a = left.split('.');
+    const b = right.split('.');
+    for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+        const x = a[index];
+        const y = b[index];
+        // A field the other side does not have makes the longer one greater, per semver.
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        if (x === y)
+            continue;
+        const xNumeric = /^\d+$/u.test(x);
+        const yNumeric = /^\d+$/u.test(y);
+        if (xNumeric && yNumeric)
+            return Number(x) - Number(y);
+        // Numeric identifiers always sort below alphanumeric ones.
+        if (xNumeric !== yNumeric)
+            return xNumeric ? -1 : 1;
+        return x < y ? -1 : 1;
+    }
+    return 0;
+};
+/** Splits a strict semver string into its numeric release triple and prerelease text, or undefined. */
+const parseVersion = (value) => {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u.exec(value);
+    if (!match)
+        return undefined;
+    return { release: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease: match[4] ?? '' };
+};
+/**
+ * This command's own opt-out variable, fixed at generation time.
+ *
+ * Substituted rather than derived from `binaryName` here, because the generated README documents it
+ * by name — deriving it twice is how a documented opt-out stops matching the one that is read.
+ */
+const UPDATE_OPT_OUT = 'DEDALUS_NO_UPDATE_NOTIFIER';
+/** Charset a git tag can actually use, applied to anything read back from the cache before printing. */
+const RELEASE_TAG = /^[A-Za-z0-9._+-]{1,64}$/u;
+/** How long a version check is trusted before the next run looks again. */
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/**
+ * Hard bound on the background version check.
+ *
+ * `fetch` keeps its socket referenced, so an unawaited request still holds the process open after
+ * the command's own work is done — a host that accepts the connection and never answers (a captive
+ * portal, a stalled proxy) would otherwise hang the CLI indefinitely on every run. The abort caps
+ * that at this, and the cache write below caps how often it can happen at all.
+ */
+const CHECK_TIMEOUT_MS = 2_000;
+/** One line naming the installed and available versions, shared by `upgrade` and `upgrade --check`. */
+const versionLine = (binaryName, version, tag) => `${binaryName} ${version} is installed; ${tag} is available.\n`;
+/** Resolves the latest tag, reporting and setting a failing exit code rather than throwing. */
+const resolveLatestTag = async () => {
+    try {
+        return await withTimeout((signal) => latestTag(signal), UPGRADE_CHECK_TIMEOUT_MS, 'the release check');
+    }
+    catch (error) {
+        process.stderr.write(`error: ${error.message}\n`);
+        process.exitCode = 1;
+        return undefined;
+    }
+};
+/** Where the last check is remembered, so every invocation does not hit the network. */
+const cachePath = (binaryName) => {
+    // Windows sets neither `HOME` nor `XDG_CACHE_HOME` from cmd or PowerShell, so without this the
+    // cache lands under the temp directory that Disk Cleanup purges — and the throttle it exists to
+    // enforce would reset every time that happened.
+    if (process.platform === 'win32') {
+        const local = process.env['LOCALAPPDATA'];
+        return local ? (0, node_path_1.join)(local, binaryName, 'update-check.json') : undefined;
+    }
+    // A relative `XDG_CACHE_HOME` is invalid per the XDG base directory spec and ignored, which also
+    // keeps the cache off a path that would otherwise be resolved against the working directory: the
+    // throttle would then be per-directory, and a repository could carry a writable one.
+    const xdg = process.env['XDG_CACHE_HOME'];
+    const base = (xdg && (0, node_path_1.isAbsolute)(xdg) ? xdg : undefined) ?? homeCacheBase();
+    return base ? (0, node_path_1.join)(base, binaryName, 'update-check.json') : undefined;
+};
+/** Per-user cache root under `$HOME`, or undefined when there is no home directory to put it in. */
+const homeCacheBase = () => {
+    const home = process.env['HOME'];
+    if (!home)
+        return undefined;
+    return process.platform === 'darwin' ? (0, node_path_1.join)(home, 'Library', 'Caches') : (0, node_path_1.join)(home, '.cache');
+};
+/**
+ * Whether it is safe to print an update hint at all.
+ *
+ * Deliberately conservative. The notice is a courtesy, and every case below is one where printing it
+ * does more harm than the notice is worth:
+ *
+ * - Not a TTY on stderr: the output is being captured or piped, where an unexpected line is noise at
+ *   best and corrupts a parsed stream at worst. This is also why the notice only ever goes to
+ *   stderr — stdout carries the command's real output, which `--format json` callers parse.
+ * - `CI`: build logs are read by machines and by people debugging failures, neither of whom asked.
+ * - `NO_UPDATE_NOTIFIER` or this command's own opt-out variable: an explicit request to stop.
+ */
+const notificationsAllowed = () => {
+    if (process.env['CI'])
+        return false;
+    if (process.env['NO_UPDATE_NOTIFIER'])
+        return false;
+    if (process.env[UPDATE_OPT_OUT])
+        return false;
+    // Never under `sudo`, and the reason is the throttle rather than the notice. `sudo` keeps `HOME` on
+    // macOS, so a root run that lands past the 24h window creates the cache directory owned by root —
+    // and every later run as the real user then fails to write it, silently. With nothing recorded the
+    // throttle never engages, so the unauthenticated API request goes out on *every* invocation, which
+    // is exactly the rate-limit exhaustion recording-before-the-request exists to prevent. `upgrade`
+    // itself tells the user to re-run under `sudo` for a root-owned install, so this is a path they are
+    // actively sent down.
+    //
+    // Keyed on `SUDO_USER` rather than on being root, deliberately. `SUDO_USER` is set only where sudo
+    // elevated from a real user — precisely when `HOME` belongs to somebody else — while plain root
+    // (a container image, a root-only appliance) owns its own `$HOME` and has no such problem. Testing
+    // `getuid() === 0` would switch the notice off for every containerized CLI, which is a large class
+    // of ordinary user, to fix a case they are not in.
+    if (process.env['SUDO_USER'])
+        return false;
+    // Both streams, not just stderr. The documented way to install completions is
+    // `eval "$(<bin> completion bash)"` in a shell rc: that captures stdout while leaving stderr
+    // attached to the terminal, so a stderr-only gate printed the notice into *every new shell* the
+    // user opened. Requiring stdout to be a terminal too is what tells a real interactive run from a
+    // command whose output something else is reading.
+    return Boolean(process.stderr.isTTY) && Boolean(process.stdout.isTTY);
+};
+/**
+ * Tells the user, at most once a day, that a newer release exists.
+ *
+ * Fire-and-forget on purpose: it is started before the command runs and never awaited, so a slow or
+ * unreachable network never delays the command's own work. The process can still be held open for up
+ * to {@link CHECK_TIMEOUT_MS} after it finishes, on a stalled connection, at most once a day. Every failure path is silent — a version check that cannot
+ * reach GitHub is not something the user asked about, and reporting it would turn a courtesy into
+ * noise on every offline run.
+ *
+ * The notice is printed on the *next* run rather than this one when the cache is cold: the check
+ * resolves after the command has usually finished, and interleaving a notice with output already in
+ * flight is worse than telling them a moment later.
+ */
+const notifyIfOutdated = (binaryName, version, argv = process.argv) => {
+    if (!notificationsAllowed())
+        return;
+    // Commander answers these and exits before a request could leave the process, but only after the
+    // attempt below is recorded — so the day's first `--help` would use up the day's check without
+    // making it. Skipped instead, which keeps the throttle and the check.
+    if (answeredWithoutRunning(argv.slice(2)))
+        return;
+    // No private cache directory means no throttle, and an unthrottled check would hit the API on
+    // every invocation. It also means the only remaining location would be a world-writable one:
+    // with `HOME` unset (`su` without `-`, `env -i`, a minimal container) a `/tmp/<command>/` fallback
+    // is a path any local user can create first and then own, and its contents are written to this
+    // terminal below. Skipping the check entirely is the cheap, safe answer.
+    const path = cachePath(binaryName);
+    if (!path)
+        return;
+    let cached = {};
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+        // `JSON.parse` returns `null` for the literal `null` without throwing, and `typeof null` is
+        // `'object'` — so both are checked. Reading `.latest` off `null` would throw *outside* this
+        // catch, and the notifier runs while the program is being built, taking the whole CLI down with
+        // an unhandled stack trace on every invocation until the file is deleted by hand.
+        if (parsed && typeof parsed === 'object')
+            cached = parsed;
+    }
+    catch {
+        // No cache yet, or an unreadable one: treated as "never checked".
+    }
+    // Report what the last check found before starting another, so a known-stale version is surfaced
+    // immediately rather than a day later.
+    // Validated before it reaches the terminal. A real `tag_name` cannot contain control characters —
+    // git refnames forbid them — so anything that does was not written by this code, and writing it
+    // raw would let cursor-control sequences rewrite the surrounding lines and forge an instruction
+    // that appears to come from the CLI itself.
+    if (cached.latest && RELEASE_TAG.test(cached.latest) && isNewerRelease(cached.latest, version)) {
+        const install = detectInstall(binaryName);
+        // `<bin> upgrade` wherever it can do the work itself — in place, or by running the owning manager
+        // — and the manager's own instruction only where it can do neither.
+        const how = install.kind === 'managed' && !install.run ? install.upgrade : `${binaryName} upgrade`;
+        process.stderr.write(`\nA new release of ${binaryName} is available: ${version} → ${cached.latest}\n  ${how}\n\n`);
+    }
+    // A negative delta satisfies a bare `<`, so a `checkedAt` written while the clock was ahead — a
+    // dead RTC battery, a hypervisor clock jump on resume — would suppress every later check for the
+    // whole skew and the user would never hear about another release. Out-of-range in either direction
+    // means "check again".
+    const since = Date.now() - (cached.checkedAt ?? 0);
+    if (cached.checkedAt && since >= 0 && since < CHECK_INTERVAL_MS)
+        return;
+    // The attempt is recorded *before* the request, not when it resolves. Commander exits the process
+    // outright for `--help`, `--version` and any usage error, which kills the in-flight check before
+    // it can write anything — so a user who mostly types `--help` would issue one unauthenticated API
+    // request per invocation forever, never cache a result, and eventually exhaust GitHub's 60/hr
+    // limit for their whole NAT. Writing up front costs one stale-by-a-day notice at worst.
+    recordCheck(path, cached.latest);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS);
+    // The timer itself would hold the event loop open for its full duration; `unref` exists on Node
+    // and Bun timers but not in the DOM typing, hence the guarded call.
+    timeout.unref?.();
+    void latestTag(controller.signal)
+        .then((tag) => recordCheck(path, tag))
+        // Failure needs no second write: the attempt was already recorded above, so the throttle holds
+        // whether the check succeeded, failed, or never finished.
+        .catch(() => { })
+        .finally(() => clearTimeout(timeout));
+};
+exports.notifyIfOutdated = notifyIfOutdated;
+/**
+ * Whether Commander answers these arguments itself — help or the version — and exits without running
+ * a command: no arguments at all (the program prints its help), `help`, `-v`/`--version` on their own,
+ * or `-h`/`--help` anywhere before a `--` that ends option parsing.
+ */
+const answeredWithoutRunning = (args) => {
+    const options = args.includes('--') ? args.slice(0, args.indexOf('--')) : args;
+    if (options.length === 0 || options[0] === 'help')
+        return true;
+    if (options.length === 1 && (options[0] === '-v' || options[0] === '--version'))
+        return true;
+    return options.includes('-h') || options.includes('--help');
+};
+/** Remembers when the check last ran, and what it found, so the throttle above can engage. */
+const recordCheck = (path, latest) => {
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+        (0, node_fs_1.writeFileSync)(path, JSON.stringify({ checkedAt: Date.now(), ...(latest ? { latest } : {}) }));
+    }
+    catch {
+        // An unwritable cache directory is not worth reporting: the check is a courtesy, and the only
+        // consequence is that it runs again next time.
+    }
+};
+/**
+ * Reports `upgrade --check`: already the latest, a newer release and the command that installs it, or
+ * a latest release older than this one.
+ *
+ * "Different" is not "newer" — `releases/latest` moves backwards when a broken release is deleted — so
+ * the ordering decides the wording. `canMove` says whether `how` would install an older release: true
+ * for a self-managed install, which `upgrade` replaces with whatever is latest; false for a managed
+ * one, whose manager never downgrades.
+ */
+const reportCheck = (binaryName, version, tag, how, canMove) => {
+    if (tag.replace(/^v/u, '') === version) {
+        process.stderr.write(`${binaryName} ${version} is already the latest release.\n`);
+        return;
+    }
+    process.stderr.write(versionLine(binaryName, version, tag));
+    if (isNewerRelease(tag, version)) {
+        process.stderr.write(`Upgrade it with:\n  ${how}\n`);
+        return;
+    }
+    process.stderr.write(canMove
+        ? `That is older than what you have. Move to it with:\n  ${how}\n`
+        : 'That is older than what you have, so there is nothing to upgrade.\n');
+};
+/** Whether this process can create and rename files in `directory`. */
+const writableDirectory = (directory) => {
+    try {
+        (0, node_fs_1.accessSync)(directory, node_fs_1.constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Registers `upgrade` and `uninstall`, which both hinge on how this executable was installed.
+ *
+ * `upgrade` upgrades every install it can identify, but never by writing over a file another package
+ * manager owns. Overwriting a Homebrew- or npm-managed binary in place leaves that manager's database
+ * describing a file that is no longer there: `brew` still reports the old version, and the next managed
+ * upgrade silently reverts this one. So a managed install is upgraded by *running* its manager's own
+ * command, and only a download nothing else manages is replaced in place. A binary in `/usr/bin` is
+ * refused outright, because nothing published here installs there — so something else owns it, and
+ * this cannot name what.
+ */
+const addUpgradeCommands = (program, binaryName, version) => {
+    program
+        .command('upgrade')
+        .description('Upgrade to the latest release')
+        .option('--check', 'Report the latest version without installing it')
+        .action(async (options) => {
+        const install = settledInstall(detectInstall(binaryName));
+        // A managed install returns unconditionally, which is also what narrows `install` to the
+        // self-managed variant for the replace below — the alternative, testing `kind` again further
+        // down, reads as a guard against a state that cannot happen.
+        if (install.kind === 'managed') {
+            if (options.check) {
+                const tag = await resolveLatestTag();
+                if (!tag)
+                    return;
+                process.stderr.write(`${binaryName} was installed with ${install.manager}.\n`);
+                // A manager only ever moves forward, so a `releases/latest` that went backwards is nothing
+                // to act on here — unlike a self-managed install, which `upgrade` would move to it.
+                reportCheck(binaryName, version, tag, install.run ? `${binaryName} upgrade` : install.upgrade, false);
+                return;
+            }
+            if (install.run) {
+                const upgraded = runManagerUpgrade(binaryName, install, install.run);
+                if (upgraded && install.run.installedVersions) {
+                    await confirmManagerUpgrade(binaryName, version, install, install.run, install.run.installedVersions);
+                }
+                return;
+            }
+            process.stderr.write(`${binaryName} was installed with ${install.manager}, which owns the installed files.\n` +
+                `Upgrade it with:\n  ${install.upgrade}\n`);
+            return;
+        }
+        const tag = await resolveLatestTag();
+        if (!tag)
+            return;
+        if (options.check) {
+            reportCheck(binaryName, version, tag, `${binaryName} upgrade`, true);
+            return;
+        }
+        // Compared as strings after stripping the tag's `v`: the release tag is the package version,
+        // so whether to act at all is an equality question, not an ordering one.
+        if (tag.replace(/^v/u, '') === version) {
+            process.stderr.write(`${binaryName} ${version} is already the latest release.\n`);
+            return;
+        }
+        // Checked before the download rather than discovered at the rename: a root-owned install
+        // directory otherwise costs the whole archive before failing with the same permission error.
+        if (!writableDirectory((0, node_path_1.dirname)(install.path))) {
+            process.stderr.write(`error: ${(0, node_path_1.dirname)(install.path)} is not writable, so ${install.path} cannot be replaced.\n` +
+                `Try again with elevated permissions.\n`);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            await replaceExecutable(install.path, tag, binaryName);
+            // "moved" rather than "upgraded" when the release moved backwards. `releases/latest` follows
+            // whichever release is marked latest, so deleting a broken one really does point this at an
+            // older build — installing it is right (that is the release the project is publishing), but
+            // calling it an upgrade is not.
+            const direction = isNewerRelease(tag, version) ? 'upgraded' : 'moved';
+            process.stderr.write(`${direction} ${binaryName} to ${tag}\n`);
+        }
+        catch (error) {
+            const message = error.message;
+            // A permission error here is the common case — the binary may sit in a root-owned directory —
+            // so say what to do rather than only what failed.
+            const reinstall = /permission|EACCES|EPERM/iu.test(message)
+                ? 'Try again with elevated permissions.\n'
+                : '';
+            process.stderr.write(`error: ${message}\n${reinstall}`);
+            process.exitCode = 1;
+        }
+    });
+    program
+        .command('uninstall')
+        .description('Show how to remove this installation')
+        .action(() => {
+        const install = settledInstall(detectInstall(binaryName));
+        if (install.kind === 'managed') {
+            process.stderr.write(`${binaryName} was installed with ${install.manager}, which owns the installed files.\n` +
+                `Remove it with:\n  ${install.remove}\n`);
+            return;
+        }
+        // Printed rather than performed: a command that deletes the executable running it cannot
+        // report a failure afterwards, and the one-liner is auditable before it is run.
+        // Single-quoted, because this is the one line in the module that is a shell command the user is
+        // meant to paste. The path comes from `realpathSync(process.execPath)` and can carry spaces —
+        // `~/Library/Application Support/...`, or any directory a user named — and an unquoted `rm`
+        // would then name two paths, neither of them the executable. Nothing expands inside single
+        // quotes, and an embedded `'` is closed, escaped and reopened.
+        // `sudo` only where it is needed: a root-owned `/usr/local/bin` refuses a plain `rm`, and a
+        // user-owned `~/.local/bin` should not be handed a root command it does not need.
+        const sudo = writableDirectory((0, node_path_1.dirname)(install.path)) ? '' : 'sudo ';
+        process.stderr.write(`Remove ${binaryName} with:\n  ${sudo}rm '${install.path.replace(/'/gu, "'\\''")}'\n${leftoverState(binaryName)}`);
+    });
+};
+exports.addUpgradeCommands = addUpgradeCommands;
+/**
+ * The state removing the executable leaves behind, named so a user can clear it too.
+ *
+ * Three things outlive the binary and none is obvious: a stored credential, which `logout` is the
+ * right way to clear because only the CLI knows where its keychain entry or file lives — named only
+ * when the CLI has sign-in at all — the update-check cache, and the PATH line the install script may
+ * have added to a shell startup file, named only when the release ships that script. Printed rather
+ * than deleted for the same reason the executable is: `uninstall` reports, so that what it says can be
+ * read before it is run.
+ */
+const leftoverState = (binaryName) => {
+    const cache = cachePath(binaryName);
+    const leftovers = [
+        ...(HAS_LOGIN ? [`  a stored credential, if you signed in — clear it with: ${binaryName} logout\n`] : []),
+        ...(cache
+            ? [`  the update-check cache — remove it with: rm -rf '${(0, node_path_1.dirname)(cache).replace(/'/gu, "'\\''")}'\n`]
+            : []),
+        ...(HAS_INSTALL_SCRIPT
+            ? [
+                `  a PATH line, if the install script added one — delete the two lines starting at "# Added by the ${binaryName} installer" in your shell startup file (for fish, the file conf.d/${binaryName}.fish)\n`,
+            ]
+            : []),
+    ];
+    return leftovers.length > 0 ? `\nThis leaves no other files behind except:\n${leftovers.join('')}` : '';
+};
+//# sourceMappingURL=upgrade.js.map