@bridge4dev/runner 0.11.0 → 0.22.1

package/dist/recipe.js

@@ -0,0 +1,238 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { PROJECT_RECIPE_PATH, canonicalRecipeJson, parseProjectRecipe, recipeSteps, } from './recipe-schema.js';
+import { evaluateRecipeCommand, maskString } from './policy.js';
+/**
+ * `.devbridge/project.json` — read, never executed (session 14).
+ *
+ * The file in a repository is a PROPOSAL. Nothing in this module runs anything:
+ * it reads the file, says whether it parses, and hands back a fingerprint. The
+ * executable copy lives on the DevBridge side and gets there only when a human
+ * with manager rights approves it — because an agent can edit files in its own
+ * branch, and «the runner does what the file says» would be arbitrary command
+ * execution by diff.
+ */
+/** A recipe file bigger than this is not a recipe. */
+const RECIPE_MAX_BYTES = 64 * 1024;
+/**
+ * A stable fingerprint of a recipe.
+ *
+ * `verify_start` carries it and the runner refuses a run whose recipe does not
+ * match: an approval is an approval of specific commands, and «the approved
+ * recipe» has to mean the same bytes on both sides.
+ */
+export function recipeFingerprint(recipe) {
+    return crypto.createHash('sha256').update(canonicalRecipeJson(recipe)).digest('hex').slice(0, 32);
+}
+/**
+ * Read the proposal out of a checkout.
+ *
+ * `lstat` and not `stat`: a symlink at `.devbridge/project.json` pointing at
+ * `~/.aws/credentials` would otherwise be read and shown verbatim on the
+ * approval screen.
+ *
+ * The DIRECTORY is checked the same way, and separately (session 15): `lstat`
+ * on the file follows every symlink above it, so `.devbridge` itself being a
+ * link to somewhere else in the filesystem walked straight past the guard while
+ * the guard's own comment said it did not.
+ */
+export function readRecipeProposal(root) {
+    const file = path.join(root, PROJECT_RECIPE_PATH);
+    const empty = {
+        path: file,
+        present: false,
+        raw: null,
+        recipe: null,
+        error: null,
+        sha: null,
+        steps: [],
+        commands: [],
+        refusals: [],
+    };
+    // Everything read here is shown to a human and hashed into an approval, so
+    // it has to come from inside the checkout — not from wherever a link points.
+    const insideCheckout = (() => {
+        try {
+            const realRoot = fs.realpathSync(root);
+            const realDir = fs.realpathSync(path.dirname(file));
+            const rel = path.relative(realRoot, realDir);
+            return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+        }
+        catch {
+            // No `.devbridge` directory at all — the ordinary case, and the read
+            // below reports it as «no recipe» on its own.
+            return true;
+        }
+    })();
+    if (!insideCheckout) {
+        return {
+            ...empty,
+            present: true,
+            error: `${PROJECT_RECIPE_PATH} points outside the repository`,
+        };
+    }
+    let raw;
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile()) {
+            return { ...empty, present: true, error: `${PROJECT_RECIPE_PATH} is not a regular file` };
+        }
+        if (stat.size > RECIPE_MAX_BYTES) {
+            return {
+                ...empty,
+                present: true,
+                error: `${PROJECT_RECIPE_PATH} is larger than ${Math.round(RECIPE_MAX_BYTES / 1024)} KB`,
+            };
+        }
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return empty;
+    }
+    const masked = maskString(raw).slice(0, RECIPE_MAX_BYTES);
+    let parsedJson;
+    try {
+        // JSONC in the plan's example is illustrative; the file itself is JSON.
+        // Comments are stripped rather than refused — a recipe people hand-write is
+        // exactly the kind of file that grows a `// why` line.
+        parsedJson = JSON.parse(stripJsonComments(raw));
+    }
+    catch (error) {
+        return {
+            ...empty,
+            present: true,
+            raw: masked,
+            error: `${PROJECT_RECIPE_PATH} is not valid JSON: ${String(error instanceof Error ? error.message : error).slice(0, 200)}`,
+        };
+    }
+    const parsed = parseProjectRecipe(parsedJson);
+    if (!parsed.ok) {
+        return { ...empty, present: true, raw: masked, error: parsed.error };
+    }
+    return {
+        path: file,
+        present: true,
+        raw: masked,
+        recipe: parsed.recipe,
+        error: null,
+        sha: recipeFingerprint(parsed.recipe),
+        steps: recipeSteps(parsed.recipe),
+        commands: recipeCommands(parsed.recipe),
+        refusals: recipeRefusals(parsed.recipe),
+    };
+}
+/**
+ * Every command in the recipe, in the order a person should read them —
+ * `preview.run` and `preview.stop` included, exactly as the refusal check
+ * already covers them.
+ */
+export function recipeCommands(recipe) {
+    const entries = [];
+    for (const name of recipeSteps(recipe)) {
+        const run = recipe.steps?.[name]?.run;
+        if (run)
+            entries.push({ step: name, run });
+    }
+    if (recipe.preview?.run)
+        entries.push({ step: 'preview.run', run: recipe.preview.run });
+    if (recipe.preview?.stop)
+        entries.push({ step: 'preview.stop', run: recipe.preview.stop });
+    return entries.map(({ step, run }) => {
+        const masked = maskString(run);
+        return { step, run: masked, redacted: masked !== run };
+    });
+}
+/**
+ * Every command in the recipe that layer 1 would refuse, named by its step.
+ *
+ * Answered at read time, not at run time. A recipe whose `deploy` step contains
+ * `sudo systemctl restart` must fail the person reading the approval screen, not
+ * a build twenty minutes into a release.
+ */
+export function recipeRefusals(recipe) {
+    const refusals = [];
+    // A command a person cannot read is a command they cannot approve. Masking is
+    // a rewrite, and the executed copy is the unmasked one — so a redaction here
+    // is not a cosmetic detail, it is the gap between what was shown and what
+    // will run. Blocking approval closes it, and moving the secret into `env`
+    // (which is never a command) is the way out.
+    for (const command of recipeCommands(recipe)) {
+        if (!command.redacted)
+            continue;
+        refusals.push({
+            step: command.step,
+            reason: 'the command contains something that looks like a secret, so it cannot be shown in full — move it into `env` and approve a command you can read',
+        });
+    }
+    for (const name of recipeSteps(recipe)) {
+        const run = recipe.steps?.[name]?.run;
+        if (!run)
+            continue;
+        const decision = evaluateRecipeCommand(run);
+        if (!decision.allowed)
+            refusals.push({ step: name, reason: decision.reason ?? 'refused' });
+    }
+    if (recipe.preview?.run) {
+        const decision = evaluateRecipeCommand(recipe.preview.run);
+        if (!decision.allowed) {
+            refusals.push({ step: 'preview.run', reason: decision.reason ?? 'refused' });
+        }
+    }
+    if (recipe.preview?.stop) {
+        const decision = evaluateRecipeCommand(recipe.preview.stop, {
+            isPreviewStop: true,
+            ...(recipe.preview.project ? { dockerProject: recipe.preview.project } : {}),
+        });
+        if (!decision.allowed) {
+            refusals.push({ step: 'preview.stop', reason: decision.reason ?? 'refused' });
+        }
+    }
+    return refusals;
+}
+/**
+ * Drop `//` and `/* *\/` comments without touching what is inside strings.
+ *
+ * A hand-rolled scanner rather than a regex: a regex that ignores string
+ * context eats the `//` in a URL, which is exactly what `health.url` is.
+ */
+export function stripJsonComments(text) {
+    let out = '';
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            out += ch;
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            continue;
+        }
+        if (ch === '/' && text[i + 1] === '/') {
+            while (i < text.length && text[i] !== '\n')
+                i++;
+            out += '\n';
+            continue;
+        }
+        if (ch === '/' && text[i + 1] === '*') {
+            i += 2;
+            while (i < text.length && !(text[i] === '*' && text[i + 1] === '/'))
+                i++;
+            i++;
+            continue;
+        }
+        out += ch;
+    }
+    // A trailing comma is the other thing a hand-written file grows.
+    return out.replace(/,(\s*[}\]])/g, '$1');
+}
+//# sourceMappingURL=recipe.js.map

package/dist/self-update.d.ts

@@ -45,6 +45,13 @@ export interface SelfUpdateOptions {
     packageDir?: string | null;
     /** Test seam: is this process supervised (defaults to autodetect). */
     supervised?: boolean;
+    /**
+     * Test seam for the resource-limits drop-in. Injected rather than called
+     * directly because the real one writes into `$HOME` — a test that exercised
+     * the update path would otherwise reconfigure the developer's own service.
+     * Returns true when it wrote something (and therefore needs a daemon-reload).
+     */
+    writeLimits?: () => boolean;
 }
 /**
  * Directory of the installed runner package, or null when it is running from a

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, limitsOverridePath, unitIsBroken, unitPath, writeLimitsOverride, LIMITS_VERSION, } 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,55 @@ 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 } : {}) });
+        }
+    }
+    // The resource policy is versioned separately from the code, because the unit
+    // is written once at install time and the numbers baked into it before 0.21.0
+    // are what killed live sessions (QA-112 BLOCKER-1). An update is the only
+    // moment we are guaranteed to be running on the server with the right to fix
+    // that, so it happens here — and the restart below is what makes it effective.
+    //
+    // Deliberately NOT fatal: a runner that refuses to update because it could not
+    // improve its own limits is strictly worse than one that updates without the
+    // improvement. It is logged loudly and `doctor` reports it.
+    try {
+        if ((options.writeLimits ?? writeLimitsOverride)()) {
+            await exec('systemctl', ['--user', 'daemon-reload'], {
+                timeout: VERIFY_TIMEOUT_MS,
+                env: npmEnv(),
+            });
+            log.warn('self-update: resource limits drop-in written', {
+                path: limitsOverridePath(),
+                version: LIMITS_VERSION,
+            });
+        }
+    }
+    catch (error) {
+        log.error('self-update: could not write the resource limits drop-in', {
+            error: describe(error),
+            hint: 'run `devbridge-runner doctor --fix` on the server',
+        });
+    }
     log.info('self-update: installed', { fromVersion, toVersion });
     return {
         ok: true,
@@ -210,12 +339,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,79 @@
+/**
+ * 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(home?: string): string;
+export declare function buildUnit(execStart?: string): string;
+/**
+ * Resource policy for the service, and why it does not live in the unit above.
+ *
+ * The unit is written ONCE, at install time. Until 0.21.0 it carried
+ * `CPUQuota=80%` and `MemoryMax=2G` — and those two lines cost a production
+ * server every session it was running (QA-112 BLOCKER-1, 2026-07-30):
+ *
+ *  - every agent the runner starts, and every `pnpm build`/`tsc`/`vitest` that
+ *    agent runs, is a CHILD of this service and therefore inside this cgroup.
+ *    Three measured `claude` processes are 512/577/646 MB and one workspace
+ *    `pnpm -r typecheck` peaks at 1571 MB, against a ceiling of 2048 MB;
+ *  - `OOMPolicy` defaults to `stop`, so the kernel killing ONE of those children
+ *    tore down the whole service — and with it every other session on the
+ *    machine. `Restart=always` then brought the daemon back with an empty
+ *    session map, which is what the user sees as
+ *    «Runner reconnected. The session was resumed»;
+ *  - `CPUQuota=80%` is 0.8 of ONE core for all of the above, which is separately
+ *    what starves the event loop until the gateway's heartbeat gives up on it.
+ *
+ * So the policy is versioned and shipped as a drop-in instead. A drop-in can
+ * RESET a directive the main unit set (`MemoryMax=` with no value clears it),
+ * which is the only way to fix the servers that already have the bad numbers
+ * baked in — and it never overwrites a unit the operator edited by hand.
+ */
+export declare const LIMITS_VERSION = 2;
+export declare function limitsOverridePath(home?: string): string;
+/**
+ * `CPUQuota` worth keeping: enough headroom that a runaway build cannot make the
+ * box unreachable, but never so little that ordinary work is throttled.
+ *
+ * One core is reserved for the system (sshd, journald, the runner's own event
+ * loop). Below four cores there is nothing to reserve without crippling the
+ * agents, so no quota is set at all — an unusable dev server is a worse failure
+ * than a busy one.
+ */
+export declare function cpuQuotaPercent(cpuCount?: number): number | null;
+export declare function buildLimitsOverride(cpuCount?: number): string;
+/**
+ * Is the shipped resource policy missing or from an older runner?
+ *
+ * Deliberately version-based rather than content-based: an operator may add
+ * their own directives to our file, and re-writing on every start would fight
+ * them. Only the version number decides.
+ */
+export declare function limitsOverrideIsOutdated(readFile?: (p: string) => string, home?: string): boolean;
+/** Write the drop-in. Returns false when nothing needed doing. */
+export declare function writeLimitsOverride(force?: boolean, home?: string): boolean;
+/**
+ * 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