@bridge4dev/runner 0.22.1 → 0.26.0

package/dist/environment.js

@@ -0,0 +1,409 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { knownWorkspacesPath } from './paths.js';
+const execFileAsync = promisify(execFile);
+export function runnerIdentity() {
+    const uid = typeof process.getuid === 'function' ? process.getuid() : -1;
+    const gid = typeof process.getgid === 'function' ? process.getgid() : -1;
+    let user = process.env['USER'] ?? process.env['LOGNAME'] ?? '';
+    if (!user) {
+        try {
+            user = os.userInfo().username;
+        }
+        catch {
+            user = uid === 0 ? 'root' : String(uid);
+        }
+    }
+    return { user, uid, gid, home: os.homedir(), isRoot: uid === 0 };
+}
+/** As root every access check passes, which is true and worth saying out loud. */
+function canAccess(target, mode) {
+    try {
+        fs.accessSync(target, mode);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function inspectPath(target) {
+    const me = runnerIdentity();
+    const base = {
+        path: target,
+        exists: false,
+        isDirectory: false,
+        ownerUid: -1,
+        ownedByUs: false,
+        readable: false,
+        writable: false,
+        unreachable: false,
+    };
+    let stat;
+    try {
+        stat = fs.statSync(target);
+    }
+    catch (error) {
+        const code = error.code;
+        return code === 'ENOENT' || code === 'ENOTDIR' ? base : { ...base, unreachable: true };
+    }
+    return {
+        path: target,
+        exists: true,
+        isDirectory: stat.isDirectory(),
+        ownerUid: stat.uid,
+        ownedByUs: me.uid < 0 || stat.uid === me.uid,
+        readable: canAccess(target, fs.constants.R_OK),
+        writable: canAccess(target, fs.constants.W_OK),
+        unreachable: false,
+    };
+}
+/**
+ * The first directory on this path the runner cannot enter.
+ *
+ * «Permission denied» on `/srv/apps/shop` is usually not about `shop` at all —
+ * it is about `/srv/apps`, and naming the wrong one sends the person to chmod
+ * a directory that was never the problem.
+ */
+export function firstUnreachableAncestor(target) {
+    const parts = path.resolve(target).split(path.sep).filter(Boolean);
+    let current = path.sep;
+    for (const part of parts) {
+        current = path.join(current, part);
+        try {
+            fs.statSync(current);
+        }
+        catch (error) {
+            const code = error.code;
+            // ENOENT here means the path simply ends — not a permission problem.
+            return code === 'ENOENT' || code === 'ENOTDIR' ? null : current;
+        }
+        if (!canAccess(current, fs.constants.X_OK))
+            return current;
+    }
+    return null;
+}
+/**
+ * Git refuses to work in a repository owned by somebody else — since 2022, and
+ * with no exception for root. So the "obvious" fix for a dedicated user (chown
+ * the project to it) breaks git for the person who was committing there before,
+ * and the exception has to be added on BOTH sides.
+ */
+export function safeDirectoryCommand(repoPath) {
+    return `git config --global --add safe.directory ${repoPath}`;
+}
+export function looksLikeDubiousOwnership(message) {
+    return /dubious ownership|safe\.directory/i.test(message);
+}
+/** Is this path already excused in the current user's git config? */
+export async function hasSafeDirectory(repoPath) {
+    try {
+        const { stdout } = await execFileAsync('git', ['config', '--global', '--get-all', 'safe.directory'], { timeout: 10_000 });
+        const entries = stdout.split('\n').map((line) => line.trim());
+        return entries.includes(repoPath) || entries.includes('*');
+    }
+    catch {
+        // No git config at all (exit 1) — nothing is excused.
+        return false;
+    }
+}
+export async function addSafeDirectory(repoPath) {
+    await execFileAsync('git', ['config', '--global', '--add', 'safe.directory', repoPath], {
+        timeout: 10_000,
+    });
+}
+function countAllowRules(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        const allow = parsed.permissions?.allow;
+        return Array.isArray(allow) ? allow.length : 0;
+    }
+    catch {
+        return null;
+    }
+}
+function countCommands(dir) {
+    let total = 0;
+    const walk = (current, depth) => {
+        if (depth > 3)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                walk(path.join(current, entry.name), depth + 1);
+            else if (entry.name.endsWith('.md'))
+                total += 1;
+        }
+    };
+    walk(dir, 0);
+    return total;
+}
+export function agentConfigContour(home = os.homedir()) {
+    const claudeDir = path.join(home, '.claude');
+    const settings = path.join(claudeDir, 'settings.json');
+    const localSettings = path.join(claudeDir, 'settings.local.json');
+    const commandsDir = path.join(claudeDir, 'commands');
+    const codexDir = path.join(home, '.codex');
+    return {
+        home,
+        claudeDir: fs.existsSync(claudeDir),
+        settings: fs.existsSync(settings),
+        localSettings: fs.existsSync(localSettings),
+        allowRules: fs.existsSync(localSettings)
+            ? countAllowRules(localSettings)
+            : fs.existsSync(settings)
+                ? countAllowRules(settings)
+                : null,
+        commands: fs.existsSync(commandsDir) ? countCommands(commandsDir) : 0,
+        plugins: fs.existsSync(path.join(claudeDir, 'plugins')),
+        codexDir: fs.existsSync(codexDir),
+        codexConfig: fs.existsSync(path.join(codexDir, 'config.toml')),
+    };
+}
+/**
+ * Another user's home that already has an agent set up.
+ *
+ * Only reported, never copied: a copied OAuth credential means two accounts
+ * share one refresh token, and a rotation in either one silently invalidates
+ * the other. Signing in as the runner's own user is the clean answer; the copy
+ * is the fast one, and the person choosing between them deserves to be told
+ * which is which.
+ */
+export function otherHomeWithAgents(me = runnerIdentity()) {
+    const candidates = me.isRoot ? [] : ['/root'];
+    for (const home of candidates) {
+        if (home === me.home)
+            continue;
+        if (fs.existsSync(path.join(home, '.claude')) || fs.existsSync(path.join(home, '.codex'))) {
+            return home;
+        }
+    }
+    return null;
+}
+/**
+ * `systemctl --user` talks over a per-user D-Bus socket, and finds it through
+ * `XDG_RUNTIME_DIR`. Under `sudo -iu <user>` that variable is not set, and the
+ * failure is worse than an error: it prints «Failed to connect to bus» and
+ * exits **0**, so a health check reads it as success.
+ */
+export function systemdUserEnv() {
+    const env = { ...process.env };
+    if (!env['XDG_RUNTIME_DIR']) {
+        const uid = runnerIdentity().uid;
+        if (uid >= 0)
+            env['XDG_RUNTIME_DIR'] = `/run/user/${uid}`;
+    }
+    if (!env['DBUS_SESSION_BUS_ADDRESS'] && env['XDG_RUNTIME_DIR']) {
+        env['DBUS_SESSION_BUS_ADDRESS'] = `unix:path=${env['XDG_RUNTIME_DIR']}/bus`;
+    }
+    return env;
+}
+/** True when the user bus is actually reachable — `systemctl --user` lies with exit 0. */
+export async function systemdUserBusReachable() {
+    const dir = systemdUserEnv()['XDG_RUNTIME_DIR'];
+    if (!dir || !fs.existsSync(path.join(dir, 'bus')))
+        return false;
+    try {
+        const { stdout, stderr } = await execFileAsync('systemctl', ['--user', 'is-system-running'], {
+            timeout: 10_000,
+            env: systemdUserEnv(),
+        });
+        return !/Failed to connect to bus/i.test(`${stdout}${stderr}`);
+    }
+    catch (error) {
+        // A non-zero exit is normal here (`degraded`, `starting`); only a bus
+        // failure means we could not talk to systemd at all.
+        const text = String(error?.stderr ?? error);
+        return !/Failed to connect to bus|No medium found/i.test(text);
+    }
+}
+/** The command form that works under `sudo -iu <user>` — printed in hints. */
+export function systemctlHint(args) {
+    const me = runnerIdentity();
+    if (me.isRoot)
+        return `systemctl --user ${args}`;
+    return `sudo -iu ${me.user} env XDG_RUNTIME_DIR=/run/user/${me.uid} DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/${me.uid}/bus systemctl --user ${args}`;
+}
+// ─── Which project directories this machine actually works in ────────
+/**
+ * Remembered from binding and from session starts, so `doctor` can check the
+ * permissions of real projects instead of asking the person to name them.
+ * Best-effort on purpose: a runner that cannot write its own state directory
+ * has bigger problems than a diagnostic list, and none of them should turn a
+ * session start into an error.
+ */
+export function rememberWorkspacePath(workspacePath) {
+    try {
+        const file = knownWorkspacesPath();
+        const known = knownWorkspacePaths();
+        if (known.includes(workspacePath))
+            return;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        // Newest last, capped: this is a diagnostic aid, not a registry.
+        const next = [...known, workspacePath].slice(-32);
+        fs.writeFileSync(file, JSON.stringify(next, null, 2), { mode: 0o600 });
+    }
+    catch {
+        /* diagnostics only */
+    }
+}
+export function knownWorkspacePaths() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(knownWorkspacesPath(), 'utf8'));
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((entry) => typeof entry === 'string' && entry.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+function whichExecutable(name) {
+    for (const dir of (process.env['PATH'] ?? '').split(path.delimiter).filter(Boolean)) {
+        const candidate = path.join(dir, name);
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return candidate;
+        }
+        catch {
+            /* keep looking */
+        }
+    }
+    return null;
+}
+/**
+ * Node, as THIS user sees it.
+ *
+ * A dedicated user does not automatically inherit a Node installed for
+ * somebody else — fnm, nvm and a root-only prefix are all per-user by design.
+ * The runner itself is running, so node clearly exists somewhere; the question
+ * this answers is whether it is on the daemon user's own PATH, because that is
+ * what agent tooling and `npm install -g` will look at.
+ */
+export async function nodeCheck() {
+    const found = whichExecutable('node');
+    if (!found)
+        return { path: null, problem: 'node is not on this user’s PATH' };
+    try {
+        const { stdout } = await execFileAsync(found, ['--version'], { timeout: 10_000 });
+        const version = stdout.trim();
+        const major = Number(version.replace(/^v/, '').split('.')[0]);
+        return {
+            path: found,
+            version,
+            ...(Number.isFinite(major) && major < 20 ? { problem: 'Node 20 or newer is required' } : {}),
+        };
+    }
+    catch (error) {
+        return { path: found, problem: String(error instanceof Error ? error.message : error) };
+    }
+}
+/**
+ * Docker, as THIS user sees it.
+ *
+ * Reported rather than judged: plenty of projects never touch it. But when the
+ * project's own workflow is `docker compose`, a dedicated user without access
+ * to the socket produces a session that fails on its first command, and the
+ * error will be about a socket rather than about a group nobody was added to.
+ *
+ * Worth stating where it is stated: being in the `docker` group is equivalent
+ * to root on this machine. That is a fact for the owner to accept knowingly.
+ */
+export async function dockerCheck() {
+    const found = whichExecutable('docker');
+    if (!found)
+        return { path: null };
+    const socket = '/var/run/docker.sock';
+    if (fs.existsSync(socket) && !canAccess(socket, fs.constants.R_OK | fs.constants.W_OK)) {
+        const me = runnerIdentity();
+        return {
+            path: found,
+            problem: `${me.user} cannot use the docker socket (membership of the docker group is equivalent to root here)`,
+        };
+    }
+    try {
+        await execFileAsync(found, ['info', '--format', '{{.ServerVersion}}'], { timeout: 15_000 });
+        return { path: found };
+    }
+    catch (error) {
+        return {
+            path: found,
+            problem: `docker is installed but did not answer: ${String(error instanceof Error ? error.message : error).slice(0, 160)}`,
+        };
+    }
+}
+/**
+ * Does the service survive a logout?
+ *
+ * `loginctl enable-linger` is what keeps a user's systemd services running with
+ * nobody logged in. `install-service` turns it on, but a unit installed by hand
+ * — or a user created afterwards — can miss it, and the failure looks like
+ * «the server goes offline whenever I close the terminal».
+ */
+export async function lingerEnabled() {
+    const me = runnerIdentity();
+    try {
+        const { stdout } = await execFileAsync('loginctl', ['show-user', me.user, '--property=Linger'], { timeout: 10_000 });
+        return stdout.trim().endsWith('=yes');
+    }
+    catch {
+        // No loginctl, or the user has no session recorded — unknown, not false.
+        return null;
+    }
+}
+/**
+ * Make the agent CLIs findable, without taking anything away.
+ *
+ * A systemd user service starts with the manager's PATH, which is the
+ * distribution default — `/usr/bin` and friends. Both agent CLIs are commonly
+ * installed somewhere else: `~/.local/bin` for a per-user install, and a
+ * node managed by fnm/nvm/volta lives under its own version directory. When
+ * `codex` sits there, the runner scans PATH, does not find it, and reports to
+ * the dashboard that this machine has no Codex at all — the agent the person
+ * installed simply never appears.
+ *
+ * Deliberately APPEND-ONLY, and deliberately in the process rather than in the
+ * unit file. Writing `Environment=PATH=…` into the unit would REPLACE whatever
+ * systemd gives the service today (`/snap/bin`, anything set through
+ * `environment.d`), trading something that works for something that is
+ * missing. Here nothing can be lost: entries are only added when they are
+ * absent and the directory actually exists.
+ *
+ * Returns what it added, so the caller can say so once at startup.
+ */
+export function ensureAgentPath() {
+    const entries = (process.env['PATH'] ?? '').split(path.delimiter).filter(Boolean);
+    const added = [];
+    for (const candidate of [
+        path.join(os.homedir(), '.local', 'bin'),
+        // The directory of the node running us — under fnm/nvm the agent CLIs and
+        // other globally installed tools sit next to it.
+        path.dirname(process.execPath),
+    ]) {
+        if (!candidate || entries.includes(candidate))
+            continue;
+        let usable;
+        try {
+            usable = fs.statSync(candidate).isDirectory();
+        }
+        catch {
+            usable = false;
+        }
+        if (!usable)
+            continue;
+        entries.push(candidate);
+        added.push(candidate);
+    }
+    if (added.length > 0)
+        process.env['PATH'] = entries.join(path.delimiter);
+    return added;
+}
+//# sourceMappingURL=environment.js.map

package/dist/git.d.ts

@@ -5,6 +5,16 @@ export interface PathValidation {
     branch?: string;
     error?: string;
 }
+/**
+ * Can this runner actually work in this directory — as the user it runs as?
+ *
+ * Everything here answers with the fix rather than the symptom. Binding a
+ * project is the moment the two legitimate install choices (root / dedicated
+ * user) start to differ, and until now the second one failed by forwarding
+ * git's own words to a dashboard the person may have no shell behind:
+ * «git check failed: fatal: detected dubious ownership in repository at
+ * '/opt/ids'». That sentence is true and unactionable.
+ */
 export declare function validateWorkspacePath(workspacePath: string): Promise<PathValidation>;
 export declare function sessionShortId(sessionId: string): string;
 export declare function sessionWorktreePath(sessionId: string): string;

package/dist/git.js

@@ -3,32 +3,121 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { previewsDir, worktreesDir } from './paths.js';
+import { firstUnreachableAncestor, inspectPath, looksLikeDubiousOwnership, runnerIdentity, safeDirectoryCommand, } from './environment.js';
 const execFileAsync = promisify(execFile);
 const GIT_TIMEOUT_MS = 30_000;
 async function git(cwd, ...args) {
     const { stdout } = await execFileAsync('git', args, { cwd, timeout: GIT_TIMEOUT_MS });
     return stdout.trim();
 }
+/**
+ * Can this runner actually work in this directory — as the user it runs as?
+ *
+ * Everything here answers with the fix rather than the symptom. Binding a
+ * project is the moment the two legitimate install choices (root / dedicated
+ * user) start to differ, and until now the second one failed by forwarding
+ * git's own words to a dashboard the person may have no shell behind:
+ * «git check failed: fatal: detected dubious ownership in repository at
+ * '/opt/ids'». That sentence is true and unactionable.
+ */
 export async function validateWorkspacePath(workspacePath) {
-    if (!fs.existsSync(workspacePath) || !fs.statSync(workspacePath).isDirectory()) {
-        return { ok: false, exists: false, isGitRepo: false, error: 'Directory does not exist' };
+    const me = runnerIdentity();
+    const dir = inspectPath(workspacePath);
+    // «Cannot look» and «is not there» are opposite instructions to whoever reads
+    // this, and both arrive as a thrown `statSync`. A dedicated-user install hits
+    // the first one constantly — usually on a directory ABOVE the project, which
+    // is why the blocking one is named rather than the one that was asked about.
+    if (dir.unreachable) {
+        const blocked = firstUnreachableAncestor(workspacePath) ?? workspacePath;
+        return {
+            ok: false,
+            exists: true,
+            isGitRepo: false,
+            error: `The runner runs as ${me.user} and is not allowed into ${blocked}, so it cannot reach ${workspacePath}. ` +
+                `Grant that user access to the directory (for example \`chmod o+x ${blocked}\`, ` +
+                `or \`setfacl -m u:${me.user}:x ${blocked}\`), then try again.`,
+        };
+    }
+    if (!dir.exists || !dir.isDirectory) {
+        return {
+            ok: false,
+            exists: dir.exists,
+            isGitRepo: false,
+            error: dir.exists
+                ? `${workspacePath} is not a directory`
+                : `${workspacePath} does not exist on this server`,
+        };
+    }
+    // A directory we cannot even enter: as a non-root runner this is the most
+    // common outcome of pointing at somebody else's project, and git's error for
+    // it says nothing about permissions.
+    if (!dir.readable) {
+        return {
+            ok: false,
+            exists: true,
+            isGitRepo: false,
+            error: `The runner runs as ${me.user} and cannot read ${workspacePath}. ` +
+                `Give that user access (for example \`setfacl -R -m u:${me.user}:rX ${workspacePath}\`, ` +
+                `or \`chown -R ${me.user} ${workspacePath}\` if the directory is meant to be theirs), then try again.`,
+        };
     }
     try {
         const inside = await git(workspacePath, 'rev-parse', '--is-inside-work-tree');
         if (inside !== 'true') {
             return { ok: false, exists: true, isGitRepo: false, error: 'Not a git work tree' };
         }
-        const branch = await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD');
-        return { ok: true, exists: true, isGitRepo: true, branch };
     }
     catch (error) {
+        const message = String(error instanceof Error ? error.message : error);
+        if (looksLikeDubiousOwnership(message)) {
+            // The single most common failure of a dedicated-user install, and the one
+            // whose fix is one line — which is why we print the line.
+            const owner = dir.ownerUid >= 0 ? ` (it belongs to uid ${dir.ownerUid})` : '';
+            return {
+                ok: false,
+                exists: true,
+                isGitRepo: false,
+                error: `Git refuses to use ${workspacePath} because the runner runs as ${me.user} and does not own it${owner}. ` +
+                    `Run this on the server as ${me.user}: ${safeDirectoryCommand(workspacePath)} — ` +
+                    `or run \`devbridge-runner doctor --fix\`, which does it for every bound project. ` +
+                    `Note: if you instead hand the directory over with \`chown\`, add the same line for its previous owner, ` +
+                    `who will otherwise lose git in that repository.`,
+            };
+        }
         return {
             ok: false,
             exists: true,
             isGitRepo: false,
-            error: `git check failed: ${String(error instanceof Error ? error.message : error).slice(0, 300)}`,
+            error: `git check failed: ${message.slice(0, 300)}`,
         };
     }
+    // Sessions write here: a worktree registers itself inside `.git/worktrees`,
+    // and a DIRECT-mode session commits in the tree itself. Read-only access
+    // binds fine and then fails on the first session, which is the worst place
+    // to learn about it.
+    const gitDir = await resolveGitDir(workspacePath);
+    const gitAccess = gitDir ? inspectPath(gitDir) : null;
+    if (gitAccess && gitAccess.exists && !gitAccess.writable) {
+        return {
+            ok: false,
+            exists: true,
+            isGitRepo: true,
+            error: `The runner runs as ${me.user} and cannot write to ${gitDir}, so it could not create a branch or a worktree here. ` +
+                `Give that user write access to the repository (for example \`chown -R ${me.user} ${workspacePath}\`), then try again.`,
+        };
+    }
+    const branch = await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD');
+    return { ok: true, exists: true, isGitRepo: true, branch };
+}
+/** The real `.git` directory of a work tree (a linked worktree has a file there). */
+async function resolveGitDir(workspacePath) {
+    try {
+        const common = await git(workspacePath, 'rev-parse', '--git-common-dir');
+        return path.resolve(workspacePath, common);
+    }
+    catch {
+        return null;
+    }
 }
 export function sessionShortId(sessionId) {
     return sessionId.replace(/-/g, '').slice(0, 8);