@bridge4dev/runner 0.46.1 → 0.48.0

package/dist/agent-install.js

@@ -0,0 +1,475 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { AGENT_VERSION_PATTERN, agentByWireKey, compareAgentVersions, } from './agent-registry.js';
+import { measureAgent } from './agent-versions.js';
+import { ensureAgentPath, whichExecutable } from './environment.js';
+import { log } from './log.js';
+import { stateDir } from './paths.js';
+import { describeCommandFailure, installIsWritable, installPrefixFor, resolveInstalledPackageDir, } from './self-update.js';
+/**
+ * Run a child and wait for it, with stdin closed.
+ *
+ * The EOF is not decoration: `agent-versions.ts` had to learn it because
+ * `claude doctor` reads stdin and sits there until the timeout otherwise
+ * (measured, not assumed). This path spawns the same vendor CLI twice —
+ * `bash install.sh` execs `claude install <version>`, and the rollback runs it
+ * directly — and a block there would cost the full install timeout with the
+ * install lock held.
+ */
+const runChild = (file, args, options) => new Promise((resolve, reject) => {
+    const child = execFile(file, args, { timeout: options.timeout, env: options.env, maxBuffer: 4_000_000 }, (error, stdout, stderr) => {
+        if (error)
+            reject(error);
+        else
+            resolve({ stdout, stderr });
+    });
+    child.stdin?.end();
+});
+/**
+ * Generous on purpose. The API stops waiting after 240s and reports «installing,
+ * waiting for the report», with the `agent_versions` frame as the late source of
+ * truth — so the runner giving up early would turn a slow 300 MB download into a
+ * failure that never happened.
+ */
+const INSTALL_TIMEOUT_MS = 600_000;
+/**
+ * Both agents ship 200–330 MB, and the native installer needs room for the new
+ * file beside the old one. Below this we refuse with a number rather than let
+ * the machine fill up — `self-update.ts` has no such check, and this is the
+ * first install path in the runner that downloads that much.
+ */
+const MIN_FREE_BYTES = 1024 * 1024 * 1024;
+/** A shell script is a few kilobytes; a minute is a slow network, not a hang. */
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+/**
+ * Anthropic's native installer keeps every version it has ever downloaded as a
+ * separate file here and switches a launcher between them; `claude install
+ * <version>` is how you move the launcher, and that is what makes a rollback
+ * possible at all for a `script`-kind agent.
+ *
+ * Deliberately NOT a registry field: the registry is mirrored character for
+ * character into `@devbridge/shared`, and today `script` has exactly one member.
+ * When a second one arrives (Antigravity ships a script installer too) this
+ * becomes a per-agent field and the mirror grows with it.
+ */
+export const NATIVE_VERSIONS_DIR = ['.local', 'share', 'claude', 'versions'];
+/**
+ * How the network is reached, on a machine that does not reach it directly.
+ *
+ * npm reads a proxy out of its own config as well; `curl` inside a vendor's
+ * `install.sh` reads ONLY the environment. Stripping these was the difference
+ * between «Update runner» working behind an outbound proxy and «Install Claude»
+ * failing there with a bare network error nobody could act on (QA of stage B,
+ * m8).
+ *
+ * Passed through rather than invented, and only these: they say WHERE to go, not
+ * who we are. No credential of ours is in this list, and the payload is still
+ * the registry's — the URL and the package name come from the build.
+ */
+const NETWORK_ENV_KEYS = [
+    'HTTP_PROXY',
+    'HTTPS_PROXY',
+    'http_proxy',
+    'https_proxy',
+    'NO_PROXY',
+    'no_proxy',
+    'ALL_PROXY',
+    'all_proxy',
+    'NODE_EXTRA_CA_CERTS',
+    'SSL_CERT_FILE',
+    'SSL_CERT_DIR',
+];
+/**
+ * npm and the vendor scripts need PATH, HOME and a writable cache; everything
+ * else is stripped so provider credentials never reach a child that touches the
+ * network, and a stray `npm_config_prefix` cannot redirect the install.
+ */
+function installEnv(homeDir) {
+    const env = {
+        PATH: process.env['PATH'] ?? '/usr/local/bin:/usr/bin:/bin',
+        HOME: homeDir,
+        npm_config_progress: 'false',
+        npm_config_fund: 'false',
+        npm_config_audit: 'false',
+    };
+    if (process.env['XDG_CACHE_HOME'])
+        env['XDG_CACHE_HOME'] = process.env['XDG_CACHE_HOME'];
+    for (const key of NETWORK_ENV_KEYS) {
+        const value = process.env[key];
+        if (value)
+            env[key] = value;
+    }
+    return env;
+}
+/**
+ * `--include=optional` is not a copy-paste slip next to C5, which takes the flag
+ * OFF the runner's own install. The two say the same thing about different
+ * packages: the runner no longer wants Claude's optional platform binary, while
+ * `@openai/codex` keeps its 320 MB executable in exactly such an optional
+ * package (`@openai/codex-linux-x64`). Dropping it here would install a shim
+ * that cannot run, and npm would still exit 0 — гоча #297, second helping.
+ *
+ * `--ignore-scripts` is safe and checked: neither agent package declares any
+ * lifecycle script.
+ */
+function npmInstallArgs(packageName, version, prefix) {
+    return [
+        'install',
+        '-g',
+        '--ignore-scripts',
+        '--include=optional',
+        '--loglevel=error',
+        ...(prefix ? ['--prefix', prefix] : []),
+        `${packageName}@${version}`,
+    ];
+}
+/**
+ * The command a human runs when we will not: an agent someone else's package
+ * manager owns, or a machine this daemon cannot write to.
+ */
+export function manualAgentInstallCommand(runtime, version) {
+    return runtime.install.kind === 'npm-global'
+        ? `npm install -g --include=optional ${runtime.install.package}@${version}`
+        : `curl -fsSL ${runtime.install.url} | bash -s ${version}`;
+}
+/** Free bytes on the filesystem `target` lives on; null when we cannot tell. */
+function freeBytesFor(target) {
+    try {
+        const stat = fs.statfsSync(target);
+        return Number(stat.bavail) * Number(stat.bsize);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The first existing directory of the chain — statfs needs a path that is
+ * actually there, and the place we are about to write into may not be yet.
+ */
+function existingAncestor(candidates) {
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/** Where this kind of install writes, for the space and ownership checks. */
+function installTarget(runtime, homeDir, prefix) {
+    if (runtime.install.kind === 'npm-global') {
+        const lib = prefix ? path.join(prefix, 'lib', 'node_modules') : null;
+        return {
+            probe: existingAncestor([...(lib ? [lib] : []), ...(prefix ? [prefix] : []), homeDir]),
+            describe: prefix ?? 'the npm prefix',
+        };
+    }
+    const share = path.join(homeDir, '.local', 'share');
+    return {
+        probe: existingAncestor([share, path.join(homeDir, '.local'), homeDir]),
+        describe: homeDir,
+    };
+}
+/**
+ * Can this daemon write where this agent has to go?
+ *
+ * Checked per kind because the two kinds land in different places: a global npm
+ * package goes into the runner's own npm prefix (so the runner's own writability
+ * check is exactly the right question), while the native installer writes only
+ * into the daemon user's home.
+ */
+function targetIsWritable(runtime, homeDir, packageDir) {
+    if (runtime.install.kind === 'npm-global')
+        return installIsWritable(packageDir);
+    // The native installer creates these if they are missing, so an ABSENT
+    // directory is not a refusal — but an existing one owned by somebody else is,
+    // and that is the real shape: Claude first installed as root, the daemon
+    // later moved to a dedicated user. Checking only `$HOME` passed that machine
+    // and let it fail with an EACCES from inside the vendor's script, which is
+    // precisely the error this section exists to replace with our own.
+    for (const target of [
+        homeDir,
+        path.join(homeDir, '.local', 'bin'),
+        path.join(homeDir, ...NATIVE_VERSIONS_DIR.slice(0, -1)),
+    ]) {
+        if (target !== homeDir && !fs.existsSync(target))
+            continue;
+        try {
+            fs.accessSync(target, fs.constants.W_OK);
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+/** Versions the native installer has on disk, newest first. */
+export function nativeVersionsOnDisk(homeDir) {
+    const dir = path.join(homeDir, ...NATIVE_VERSIONS_DIR);
+    try {
+        return fs
+            .readdirSync(dir)
+            .filter((name) => new RegExp(AGENT_VERSION_PATTERN).test(name))
+            .sort((a, b) => compareAgentVersions(b, a) ?? 0);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Fetch the vendor's installer script to a file.
+ *
+ * `curl` rather than Node's `fetch`, and behind an outbound proxy that is the
+ * whole difference between working and not: undici reads no proxy from the
+ * environment, so a machine that reaches the internet only through
+ * `HTTPS_PROXY` failed here — while the script it was fetching would itself
+ * have reached the network perfectly well, because `curl` inside it does read
+ * the environment. Fixing one half and not the other would have been an
+ * improvement nobody could use.
+ *
+ * `curl` is not an extra dependency: the vendor's script runs it on the next
+ * line, so a machine without it cannot install this agent either way.
+ *
+ * Downloaded to a file and never piped into a shell, exactly as before — a
+ * truncated transfer then fails to parse instead of running half a script.
+ * `--fail` turns an HTTP error into a non-zero exit rather than an error page
+ * saved as an installer; `--proto =https` refuses a redirect that leaves TLS.
+ */
+async function downloadToFile(url, destination, exec, env) {
+    await exec('curl', [
+        '--fail',
+        '--silent',
+        '--show-error',
+        '--location',
+        '--proto',
+        '=https',
+        '--output',
+        destination,
+        url,
+    ], { timeout: DOWNLOAD_TIMEOUT_MS, env });
+    const written = fs.statSync(destination);
+    if (written.size === 0)
+        throw new Error('the installer script came back empty');
+    fs.chmodSync(destination, 0o700);
+}
+/**
+ * Install or update one agent CLI.
+ *
+ * Never throws: every failure comes back as an outcome, because the caller is a
+ * command handler whose reply is the only thing the dashboard will ever see.
+ */
+export async function installAgent(options) {
+    const exec = options.exec ?? runChild;
+    const measure = options.measure ?? ((runtime) => measureAgent(runtime));
+    const homeDir = options.homeDir ?? process.env['HOME'] ?? os.homedir();
+    const free = options.freeBytes ?? freeBytesFor;
+    const download = options.download ??
+        ((url, destination) => downloadToFile(url, destination, exec, installEnv(homeDir)));
+    const refreshPath = options.refreshPath ?? ensureAgentPath;
+    const fail = (detail, extra = {}) => ({
+        ok: false,
+        agent: options.agent,
+        fromVersion: null,
+        detail,
+        ...extra,
+    });
+    // ── Refusals, all of them before anything is touched ──────────────────────
+    const runtime = agentByWireKey(options.agent);
+    if (!runtime)
+        return fail(`\`${options.agent}\` is not an agent this runner knows`);
+    if (!new RegExp(AGENT_VERSION_PATTERN).test(options.version)) {
+        return fail(`\`${options.version}\` is not a version number`);
+    }
+    const packageDir = options.packageDir === undefined ? resolveInstalledPackageDir() : options.packageDir;
+    const prefix = installPrefixFor(packageDir);
+    const before = await measure(runtime);
+    const fromVersion = before.version;
+    // A binary that is there but would not answer. Installing over it would throw
+    // away a version we cannot name, and «roll back to null» is not a rollback.
+    if (before.probeFailed) {
+        return fail(`${runtime.label} is installed on this server but does not report its version, ` +
+            'so there would be no way back if the new one turned out to be broken. ' +
+            `Check it on the server with \`${runtime.bin} ${runtime.versionProbe.argv.join(' ')}\`.`, { fromVersion });
+    }
+    // Someone else's package manager owns this copy. Replacing it would leave two
+    // installations racing for the same command name.
+    if (fromVersion !== null && before.managedBy !== runtime.install.managedBy) {
+        return fail(`${runtime.label} on this server was installed with ${before.managedBy}, ` +
+            'and this runner only manages its own installs. Update it on the server with:\n  ' +
+            manualAgentInstallCommand(runtime, options.version), { fromVersion });
+    }
+    if (fromVersion === options.version) {
+        return {
+            ok: true,
+            agent: runtime.wireKey,
+            fromVersion,
+            toVersion: options.version,
+            detail: `${runtime.label} is already ${options.version}`,
+        };
+    }
+    if (fromVersion !== null &&
+        !options.allowDowngrade &&
+        (compareAgentVersions(options.version, fromVersion) ?? 0) < 0) {
+        return fail(`${options.version} is older than the ${fromVersion} already on this server`, {
+            fromVersion,
+        });
+    }
+    if (!targetIsWritable(runtime, homeDir, packageDir)) {
+        return fail(`${runtime.label} would be installed into ${installTarget(runtime, homeDir, prefix).describe}, ` +
+            `which does not belong to ${os.userInfo().username} — the user this runner runs as. ` +
+            'Run this on the server instead:\n  ' +
+            manualAgentInstallCommand(runtime, options.version), { fromVersion });
+    }
+    const target = installTarget(runtime, homeDir, prefix);
+    const freeBytes = target.probe ? free(target.probe) : null;
+    // null means «this platform cannot tell», which is a reason to go ahead rather
+    // than to refuse every install — the same call the verify runner makes.
+    if (freeBytes !== null && freeBytes < MIN_FREE_BYTES) {
+        return fail(`Only ${Math.round(freeBytes / 1024 / 1024)} MB free where ${runtime.label} would go — ` +
+            `it needs at least ${Math.round(MIN_FREE_BYTES / 1024 / 1024)} MB. Free some space and try again.`, { fromVersion });
+    }
+    // ── The install itself ────────────────────────────────────────────────────
+    // What a rollback would restore. For `npm-global` this is the version number,
+    // not a packed tarball: the plan wrote `npm pack`, copying the runner's own
+    // update, but the runner packs itself because the registry has no copy of the
+    // build it is replacing. An agent version DID come from the registry, and
+    // packing its installed directory would produce an 8 KB shim without the
+    // platform binary anyway — so the number is both the honest artefact and the
+    // sufficient one. The safety property the plan asked for is kept exactly:
+    // nothing is installed over a version we could not name (see `probeFailed`).
+    const rollbackVersion = fromVersion;
+    try {
+        if (runtime.install.kind === 'npm-global') {
+            await exec('npm', npmInstallArgs(runtime.install.package, options.version, prefix), {
+                timeout: INSTALL_TIMEOUT_MS,
+                env: installEnv(homeDir),
+            });
+        }
+        else {
+            const scriptDir = path.join(stateDir(), 'agent-install');
+            fs.mkdirSync(scriptDir, { recursive: true, mode: 0o700 });
+            const scriptPath = path.join(scriptDir, `${runtime.wireKey}-install.sh`);
+            // Downloaded to a file and executed, never piped into a shell: a truncated
+            // transfer then fails to parse instead of running half a script.
+            await download(runtime.install.url, scriptPath);
+            try {
+                await exec('bash', [scriptPath, options.version], {
+                    timeout: INSTALL_TIMEOUT_MS,
+                    env: installEnv(homeDir),
+                });
+            }
+            finally {
+                // In a `finally`, or every failed install leaves a vendor script behind
+                // in the runner's state directory.
+                fs.rmSync(scriptPath, { force: true });
+            }
+        }
+    }
+    catch (error) {
+        const detail = describeCommandFailure(error);
+        log.warn('agent-install: install failed', { agent: runtime.wireKey, error: detail });
+        return fail(`Installing ${runtime.label} ${options.version} failed: ${detail}`, {
+            fromVersion,
+        });
+    }
+    // ── The smoke test: ask the binary, not npm ───────────────────────────────
+    // Look again for directories the install has just created. `ensureAgentPath`
+    // runs once at daemon start and adds `~/.local/bin` only if it EXISTS then —
+    // and on a machine getting Claude for the first time it does not. Without
+    // this the smoke test below would search a PATH that cannot contain the file
+    // we just wrote, call a good install a failure, and roll it back. That is the
+    // headline case of this whole feature (Р11), not a corner of it.
+    refreshPath();
+    const after = await measure(runtime);
+    const landed = after.version === options.version && !after.probeFailed;
+    if (landed) {
+        log.info('agent-install: installed', {
+            agent: runtime.wireKey,
+            from: fromVersion,
+            to: options.version,
+        });
+        return {
+            ok: true,
+            agent: runtime.wireKey,
+            fromVersion,
+            toVersion: options.version,
+        };
+    }
+    const wrong = after.probeFailed
+        ? `${runtime.label} does not run after the install`
+        : after.version === null
+            ? `${runtime.label} is not on this server after the install`
+            : `${runtime.label} reports ${after.version} after installing ${options.version}`;
+    log.error('agent-install: the new version did not come up', {
+        agent: runtime.wireKey,
+        wanted: options.version,
+        got: after.version,
+    });
+    const rolledBack = await rollBack({
+        runtime,
+        version: rollbackVersion,
+        exec,
+        prefix,
+        homeDir,
+        measure,
+    });
+    return fail(rollbackVersion === null
+        ? `${wrong}. Nothing was replaced — the server is as it was.`
+        : rolledBack
+            ? `${wrong}. The previous version (${rollbackVersion}) was put back.`
+            : `${wrong}, and putting ${rollbackVersion} back failed too. Fix it on the server with:\n  ` +
+                manualAgentInstallCommand(runtime, rollbackVersion), { fromVersion, ...(rollbackVersion !== null ? { rolledBack } : {}) });
+}
+/**
+ * Put the previous version back, by the route its own installer understands.
+ *
+ * Returns whether the machine really ended up on that version — asked of the
+ * binary again, because a rollback that silently failed is the one state worse
+ * than the broken install it was meant to undo.
+ */
+async function rollBack(input) {
+    const { runtime, version, exec, prefix, homeDir, measure } = input;
+    if (version === null)
+        return false;
+    try {
+        if (runtime.install.kind === 'npm-global') {
+            await exec('npm', npmInstallArgs(runtime.install.package, version, prefix), {
+                timeout: INSTALL_TIMEOUT_MS,
+                env: installEnv(homeDir),
+            });
+        }
+        else {
+            // The native installer keeps the file; `claude install <version>` only has
+            // to point the launcher back at it. Prefer the version file itself over
+            // the launcher, which is exactly what the failed install may have broken.
+            const onDisk = nativeVersionsOnDisk(homeDir).includes(version)
+                ? path.join(homeDir, ...NATIVE_VERSIONS_DIR, version)
+                : whichExecutable(runtime.bin);
+            if (!onDisk)
+                return false;
+            await exec(onDisk, ['install', version], {
+                timeout: INSTALL_TIMEOUT_MS,
+                env: installEnv(homeDir),
+            });
+        }
+    }
+    catch (error) {
+        log.error('agent-install: rollback failed', {
+            agent: runtime.wireKey,
+            version,
+            error: describeCommandFailure(error),
+        });
+        return false;
+    }
+    const restored = await measure(runtime);
+    return restored.version === version;
+}
+export const AGENT_INSTALL_INTERNALS = {
+    INSTALL_TIMEOUT_MS,
+    MIN_FREE_BYTES,
+    downloadToFile,
+    installEnv,
+    nativeVersionsOnDisk,
+    npmInstallArgs,
+};
+//# sourceMappingURL=agent-install.js.map