@bridge4dev/runner 0.11.0 → 0.13.1

package/dist/index.js

@@ -14,6 +14,7 @@ import { Supervisor } from './supervisor.js';
 import { readStatusFile, isPidAlive, writeStatusFile, STATUS_FRESH_MS } from './status-file.js';
 import { RunnerWsClient } from './ws-client.js';
 import { RUNNER_VERSION } from './version.js';
+import { buildUnit, unitExecTarget, unitPath } from './service-unit.js';
 const execFileAsync = promisify(execFile);
 function print(line) {
     process.stdout.write(line + '\n');
@@ -236,17 +237,34 @@ async function cmdDaemon() {
     await new Promise(() => undefined);
 }
 // ─── status ──────────────────────────────────────────────────────────
-function cmdStatus() {
+/** Long enough for a just-started daemon to connect and write its first record. */
+const STATUS_WAIT_MS = 10_000;
+const STATUS_POLL_MS = 250;
+function currentStatus() {
+    const status = readStatusFile();
+    const fresh = status &&
+        isPidAlive(status.pid) &&
+        Date.now() - new Date(status.updatedAt).getTime() < STATUS_FRESH_MS;
+    return fresh ? status : null;
+}
+async function cmdStatus() {
     const config = loadConfig();
     if (!config) {
         print('NOT PAIRED — run: devbridge-runner pair <code> --api <url>');
         process.exit(1);
     }
-    const status = readStatusFile();
-    const fresh = status &&
-        isPidAlive(status.pid) &&
-        Date.now() - new Date(status.updatedAt).getTime() < STATUS_FRESH_MS;
-    if (!fresh) {
+    // `install-service` ends by telling the user to run this, and people run it
+    // right away — usually chained with `&&`, a fraction of a second after systemd
+    // started the daemon, before it has connected or written its first record. It
+    // then answered «NOT RUNNING» about a runner that was starting perfectly well.
+    // So: wait briefly for the daemon to say something before declaring it dead.
+    let status = currentStatus();
+    const deadline = Date.now() + STATUS_WAIT_MS;
+    while (!status && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, STATUS_POLL_MS));
+        status = currentStatus();
+    }
+    if (!status) {
         print(`NOT RUNNING — server "${config.server.name}" (${config.api.url})`);
         print('Start with: devbridge-runner install-service   (or: devbridge-runner daemon)');
         process.exit(1);
@@ -262,33 +280,20 @@ function cmdStatus() {
     process.exit(1);
 }
 // ─── install-service ─────────────────────────────────────────────────
-function systemdUnit() {
-    const script = fs.realpathSync(process.argv[1] ?? '');
-    return [
-        '[Unit]',
-        'Description=DevBridge Dev Runner',
-        'After=network-online.target',
-        '',
-        '[Service]',
-        `ExecStart=${process.execPath} ${script} daemon`,
-        'Restart=always',
-        'RestartSec=5',
-        'CPUQuota=80%',
-        'MemoryMax=2G',
-        '',
-        '[Install]',
-        'WantedBy=default.target',
-    ].join('\n');
-}
 async function cmdInstallService() {
     requireConfig(); // fail early if not paired
     if (process.platform !== 'linux')
         fail('install-service supports Linux/systemd only');
-    const unitDir = path.join(os.homedir(), '.config', 'systemd', 'user');
-    fs.mkdirSync(unitDir, { recursive: true });
-    const unitPath = path.join(unitDir, 'devbridge-runner.service');
-    fs.writeFileSync(unitPath, systemdUnit() + '\n');
-    print(`Wrote ${unitPath}`);
+    const target = unitPath();
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const exec = unitExecTarget();
+    fs.writeFileSync(target, buildUnit(exec.execStart));
+    print(`Wrote ${target}`);
+    if (!exec.viaCommand) {
+        // Worth saying out loud: a unit pinned to a file inside the package directory
+        // breaks if that directory ever moves (which a package rename does).
+        print(`note: the service runs ${exec.execStart} directly — re-run install-service after reinstalling the package.`);
+    }
     try {
         await execFileAsync('systemctl', ['--user', 'daemon-reload']);
         await execFileAsync('systemctl', ['--user', 'enable', '--now', 'devbridge-runner']);

package/dist/self-update.js

@@ -5,6 +5,7 @@ import { promisify } from 'node:util';
 import { log } from './log.js';
 import { stateDir } from './paths.js';
 import { RUNNER_VERSION } from './version.js';
+import { buildUnit, unitIsBroken, unitPath } from './service-unit.js';
 const execFileAsync = promisify(execFile);
 const NPM_TIMEOUT_MS = 180_000;
 const VERIFY_TIMEOUT_MS = 30_000;
@@ -82,19 +83,100 @@ export function isTrustedTarballUrl(tarballUrl, apiUrl) {
     }
     return target.origin === api.origin && target.pathname.endsWith('.tgz');
 }
-function readVersion(packageDir) {
+function readManifest(packageDir) {
     try {
-        const parsed = JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8'));
-        return typeof parsed.version === 'string' ? parsed.version : null;
+        return JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8'));
     }
     catch {
         return null;
     }
 }
+function readVersion(packageDir) {
+    const value = readManifest(packageDir)?.version;
+    return typeof value === 'string' ? value : null;
+}
 /** The CLI entry point of an installed package, used to smoke-test the update. */
 function binPath(packageDir) {
     return path.join(packageDir, 'dist', 'index.js');
 }
+/** The command every systemd unit on every user's machine points at. */
+const COMMAND_NAME = 'devbridge-runner';
+/**
+ * Which installed package currently owns the `devbridge-runner` command.
+ *
+ * Asked instead of assumed, because an update may RENAME the package (it did:
+ * `@devbridge/runner` → `@bridge4dev/runner`). After that the directory this
+ * process is running from belongs to the version being retired, while the
+ * command — the stable thing, referenced by a unit file we do not control —
+ * points at the new one. So we follow the command.
+ */
+async function commandOwner(exec) {
+    let prefix;
+    try {
+        const result = await exec('npm', ['prefix', '-g'], {
+            timeout: VERIFY_TIMEOUT_MS,
+            env: npmEnv(),
+        });
+        prefix = result.stdout.trim();
+    }
+    catch {
+        return null;
+    }
+    if (!prefix)
+        return null;
+    const command = path.join(prefix, 'bin', COMMAND_NAME);
+    try {
+        if (!fs.existsSync(command))
+            return null;
+        // <dir>/dist/index.js → <dir>
+        const dir = path.resolve(path.dirname(fs.realpathSync(command)), '..');
+        const name = readManifest(dir)?.name;
+        return typeof name === 'string' ? { name, dir, command } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function installArgs(source) {
+    // `--ignore-scripts` matches the documented install: this package and its whole
+    // tree have no install/postinstall scripts, so nothing legitimate is skipped —
+    // and an update pulled over the network gets no chance to run anything at
+    // install time. `--loglevel=error` because npm's ERESOLVE warning about zod is
+    // expected, harmless and long enough to bury the line that matters.
+    return ['install', '-g', '--ignore-scripts', '--loglevel=error', source];
+}
+/**
+ * Install a global package, clearing the way if a DIFFERENTLY-NAMED build of this
+ * same runner still owns the command.
+ *
+ * npm refuses to take over an existing bin symlink (`EEXIST`) — which is exactly
+ * what happens when the package is renamed: the new name cannot claim
+ * `devbridge-runner` while the old name holds it, so «Update runner» failed with
+ * a wall of unrelated zod warnings. Retiring the previous package first leaves
+ * one owner instead of two, which is also the only state the NEXT update can
+ * work from.
+ */
+async function installGlobal(exec, source) {
+    try {
+        await exec('npm', installArgs(source), { timeout: NPM_TIMEOUT_MS, env: npmEnv() });
+        return;
+    }
+    catch (error) {
+        if (!/EEXIST/i.test(describe(error)))
+            throw error;
+        const owner = await commandOwner(exec);
+        if (!owner)
+            throw error;
+        log.warn('self-update: the command belongs to another package — retiring it', {
+            package: owner.name,
+        });
+        await exec('npm', ['uninstall', '-g', '--loglevel=error', owner.name], {
+            timeout: NPM_TIMEOUT_MS,
+            env: npmEnv(),
+        });
+        await exec('npm', installArgs(source), { timeout: NPM_TIMEOUT_MS, env: npmEnv() });
+    }
+}
 /**
  * npm needs PATH/HOME and a writable cache; everything else is stripped, both to
  * keep provider credentials out of a child process that touches the network and
@@ -160,24 +242,22 @@ export async function selfUpdate(options) {
         return fail('Could not prepare a rollback copy of the current version — update aborted');
     }
     try {
-        // `--ignore-scripts` matches the documented install: this package and its
-        // whole tree have no install/postinstall scripts, so nothing legitimate is
-        // skipped — and an update pulled over the network gets no chance to run
-        // anything at install time.
-        await exec('npm', ['install', '-g', '--ignore-scripts', options.tarballUrl], {
-            timeout: NPM_TIMEOUT_MS,
-            env: npmEnv(),
-        });
+        await installGlobal(exec, options.tarballUrl);
     }
     catch (error) {
         return fail(`Install failed: ${describe(error)}`, { rollbackTarball });
     }
-    const toVersion = readVersion(packageDir) ?? undefined;
+    // Where the new build actually landed. After a rename `packageDir` is the
+    // directory we just retired, so its manifest would report the OLD version —
+    // and the smoke test below would run code that no longer exists.
+    const installed = await commandOwner(exec);
+    const newPackageDir = installed?.dir ?? packageDir;
+    const toVersion = readVersion(newPackageDir) ?? undefined;
     // The real test: does the newly installed build start? `--version` loads the
     // whole module graph, so a half-downloaded package or a missing dependency
     // fails here rather than after the restart, when nobody could see it.
     try {
-        const probe = await exec(process.execPath, [binPath(packageDir), '--version'], {
+        const probe = await exec(process.execPath, [binPath(newPackageDir), '--version'], {
             timeout: VERIFY_TIMEOUT_MS,
             env: npmEnv(),
         });
@@ -190,10 +270,10 @@ export async function selfUpdate(options) {
         const detail = describe(error);
         log.error('self-update: the new build did not start — rolling back', { error: detail });
         try {
-            await exec('npm', ['install', '-g', '--ignore-scripts', rollbackTarball], {
-                timeout: NPM_TIMEOUT_MS,
-                env: npmEnv(),
-            });
+            // Through the same door as the install above: if the failed update renamed
+            // the package, the command now belongs to the new name and putting the old
+            // one back hits the very same EEXIST.
+            await installGlobal(exec, rollbackTarball);
             return fail(`The new version did not start (${detail}). The previous version was restored and the runner keeps working.`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
         }
         catch (rollbackError) {
@@ -201,6 +281,28 @@ export async function selfUpdate(options) {
                 `Restore it on the server with: npm install -g ${rollbackTarball}`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
         }
     }
+    // The service unit may be pinned to a file inside the directory this update
+    // just replaced — early versions wrote the resolved script path, and a package
+    // rename moves it. Then the restart we are about to ask for would fail with
+    // ENOENT and the runner would never come back. Repair it here, while the
+    // process is still alive to do it.
+    if (installed?.command && unitIsBroken()) {
+        try {
+            fs.mkdirSync(path.dirname(unitPath()), { recursive: true });
+            fs.writeFileSync(unitPath(), buildUnit(installed.command));
+            await exec('systemctl', ['--user', 'daemon-reload'], {
+                timeout: VERIFY_TIMEOUT_MS,
+                env: npmEnv(),
+            });
+            log.warn('self-update: the service unit pointed at the previous location — rewritten', {
+                execStart: installed.command,
+            });
+        }
+        catch (error) {
+            return fail(`The new version is installed, but the service still points at the previous location and ` +
+                `could not be repaired (${describe(error)}). Run \`devbridge-runner install-service\` on the server.`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
+        }
+    }
     log.info('self-update: installed', { fromVersion, toVersion });
     return {
         ok: true,
@@ -210,12 +312,31 @@ export async function selfUpdate(options) {
         rollbackTarball,
     };
 }
+/**
+ * The reason a child process failed, in 400 characters that are actually about
+ * the failure.
+ *
+ * npm puts its diagnosis at the END of stderr and everything it merely wants to
+ * mention at the beginning. Taking the first 400 characters is therefore exactly
+ * backwards: a real `npm error code EEXIST` was reported to the owner as a wall
+ * of ERESOLVE peer-dependency warnings about zod, which are harmless and always
+ * present. So: keep the `npm error` lines when there are any, and otherwise keep
+ * the tail rather than the head.
+ */
 function describe(error) {
-    if (error instanceof Error) {
-        const withStderr = error;
-        const stderr = typeof withStderr.stderr === 'string' ? withStderr.stderr.trim() : '';
-        return (stderr || error.message).slice(0, 400);
-    }
-    return String(error).slice(0, 400);
+    const raw = error instanceof Error
+        ? (() => {
+            const withStderr = error;
+            const stderr = typeof withStderr.stderr === 'string' ? withStderr.stderr.trim() : '';
+            return stderr || error.message;
+        })()
+        : String(error);
+    const npmErrors = raw
+        .split('\n')
+        .filter((line) => /^\s*npm (error|ERR!)/i.test(line))
+        .join('\n')
+        .trim();
+    const meaningful = npmErrors || raw;
+    return meaningful.length > 400 ? `…${meaningful.slice(-400)}` : meaningful;
 }
 //# sourceMappingURL=self-update.js.map

package/dist/service-unit.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The systemd user unit, and the one decision inside it that matters: what to
+ * exec.
+ *
+ * The first version baked `realpathSync(process.argv[1])` — the resolved file
+ * inside the installed package directory. That pins the service to a directory
+ * that a package RENAME deletes: `@devbridge/runner` → `@bridge4dev/runner` moved
+ * the file, the unit kept pointing at the old path, and `systemctl restart`
+ * failed with ENOENT. The runner simply never came back and the server went
+ * offline until someone logged in — the one outcome an update must never produce.
+ *
+ * So the unit execs the COMMAND (`<prefix>/bin/devbridge-runner`), which npm
+ * re-creates on every install whatever the package is called. A source checkout
+ * has no such symlink, and there the resolved script is the honest answer.
+ */
+export declare const SERVICE_NAME = "devbridge-runner";
+/** `<prefix>/bin/devbridge-runner` for an installed package, else the script. */
+export declare function unitExecTarget(argv1?: string): {
+    execStart: string;
+    viaCommand: boolean;
+};
+export declare function unitPath(): string;
+export declare function buildUnit(execStart?: string): string;
+/**
+ * Does the installed unit point at something that no longer exists?
+ *
+ * Used after an update: if the package moved (a rename), a unit pinned to the old
+ * directory would kill the runner on the very restart the update asks for. Only a
+ * missing target counts — a unit the user edited on purpose is left alone.
+ */
+export declare function unitIsBroken(readFile?: (p: string) => string): boolean;
+//# sourceMappingURL=service-unit.d.ts.map

package/dist/service-unit.js

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * The systemd user unit, and the one decision inside it that matters: what to
+ * exec.
+ *
+ * The first version baked `realpathSync(process.argv[1])` — the resolved file
+ * inside the installed package directory. That pins the service to a directory
+ * that a package RENAME deletes: `@devbridge/runner` → `@bridge4dev/runner` moved
+ * the file, the unit kept pointing at the old path, and `systemctl restart`
+ * failed with ENOENT. The runner simply never came back and the server went
+ * offline until someone logged in — the one outcome an update must never produce.
+ *
+ * So the unit execs the COMMAND (`<prefix>/bin/devbridge-runner`), which npm
+ * re-creates on every install whatever the package is called. A source checkout
+ * has no such symlink, and there the resolved script is the honest answer.
+ */
+export const SERVICE_NAME = 'devbridge-runner';
+const COMMAND_NAME = 'devbridge-runner';
+/** `<prefix>/bin/devbridge-runner` for an installed package, else the script. */
+export function unitExecTarget(argv1 = process.argv[1] ?? '') {
+    // Invoked through the command itself: that is already the stable path.
+    try {
+        if (fs.lstatSync(argv1).isSymbolicLink()) {
+            return { execStart: path.resolve(argv1), viaCommand: true };
+        }
+    }
+    catch {
+        /* fall through to the resolved script */
+    }
+    let script;
+    try {
+        script = fs.realpathSync(argv1);
+    }
+    catch {
+        return { execStart: argv1, viaCommand: false };
+    }
+    // Invoked as the script inside a global install: find the prefix that owns the
+    // command. `<prefix>/lib/node_modules/@scope/runner/dist/index.js` → `<prefix>`.
+    if (script.split(path.sep).includes('node_modules')) {
+        let dir = path.dirname(script);
+        for (let i = 0; i < 6; i++) {
+            const candidate = path.join(dir, 'bin', COMMAND_NAME);
+            if (fs.existsSync(candidate))
+                return { execStart: candidate, viaCommand: true };
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return { execStart: script, viaCommand: false };
+}
+export function unitPath() {
+    return path.join(os.homedir(), '.config', 'systemd', 'user', `${SERVICE_NAME}.service`);
+}
+export function buildUnit(execStart) {
+    const target = execStart ?? unitExecTarget().execStart;
+    // The command carries a `#!/usr/bin/env node` shebang, so it is exec'd directly;
+    // a bare script path needs the interpreter spelled out.
+    const command = target.endsWith('.js')
+        ? `${process.execPath} ${target} daemon`
+        : `${target} daemon`;
+    return ([
+        '[Unit]',
+        'Description=DevBridge Dev Runner',
+        'After=network-online.target',
+        '',
+        '[Service]',
+        `ExecStart=${command}`,
+        'Restart=always',
+        'RestartSec=5',
+        'CPUQuota=80%',
+        'MemoryMax=2G',
+        '',
+        '[Install]',
+        'WantedBy=default.target',
+    ].join('\n') + '\n');
+}
+/**
+ * Does the installed unit point at something that no longer exists?
+ *
+ * Used after an update: if the package moved (a rename), a unit pinned to the old
+ * directory would kill the runner on the very restart the update asks for. Only a
+ * missing target counts — a unit the user edited on purpose is left alone.
+ */
+export function unitIsBroken(readFile = (p) => fs.readFileSync(p, 'utf8')) {
+    let contents;
+    try {
+        contents = readFile(unitPath());
+    }
+    catch {
+        return false; // no unit of ours — nothing to repair
+    }
+    const line = contents.split('\n').find((l) => l.startsWith('ExecStart='));
+    if (!line)
+        return false;
+    const parts = line.slice('ExecStart='.length).trim().split(/\s+/);
+    // `ExecStart=/usr/bin/node /path/index.js daemon` or `ExecStart=/path/cmd daemon`
+    const target = parts[0]?.endsWith('node') ? parts[1] : parts[0];
+    if (!target)
+        return false;
+    return !fs.existsSync(target);
+}
+//# sourceMappingURL=service-unit.js.map

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.11.0";
+export declare const RUNNER_VERSION = "0.13.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in sync with package.json by the release script (manual for now).
-export const RUNNER_VERSION = '0.11.0';
+export const RUNNER_VERSION = '0.13.1';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@bridge4dev/runner",
-  "version": "0.11.0",
+  "version": "0.13.1",
   "description": "DevBridge dev runner — connects a dev server to DevBridge and runs agent sessions (Claude Code / Codex)",
   "homepage": "https://bridge4.dev",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {
-    "devbridge-runner": "./dist/index.js"
+    "devbridge-runner": "dist/index.js"
   },
   "keywords": [
     "devbridge",