@bridge4dev/runner 0.13.1 → 0.26.0

package/dist/git.js

@@ -2,33 +2,122 @@ import { execFile } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { promisify } from 'node:util';
-import { worktreesDir } from './paths.js';
+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);
@@ -92,7 +181,8 @@ export async function ensureSessionWorktree(workspacePath, sessionId, branchHint
     // A ticket group gets a branch named after its tickets so the work reads as
     // one thing in git history. The worktree DIRECTORY stays id-derived — it is
     // the collision guard below, and two sessions must never share one.
-    const branch = sanitizeBranch(branchHint) ?? `devbridge/s-${short}`;
+    const planned = options.plan ? sanitizeBranch(options.plan.branch) : null;
+    const branch = planned ?? sanitizeBranch(branchHint) ?? `devbridge/s-${short}`;
     const worktreePath = sessionWorktreePath(sessionId);
     if (fs.existsSync(path.join(worktreePath, '.git'))) {
         // Runner restart — reuse, but verify the worktree really is ours: a
@@ -109,19 +199,198 @@ export async function ensureSessionWorktree(workspacePath, sessionId, branchHint
     const branchExists = await git(workspacePath, 'rev-parse', '--verify', '--quiet', branch)
         .then(() => true)
         .catch(() => false);
+    // With a plan, both mismatches are failures worth stopping for. Without one
+    // (an API from before session 13) the historical guesswork is kept exactly as
+    // it was, so an old server does not start failing after a runner update.
+    const plan = planned ? options.plan : undefined;
+    if (plan?.source === 'NEW' && branchExists) {
+        throw new Error(`branch ${branch} already exists in ${workspacePath} — a new session must not silently continue somebody else's work`);
+    }
+    if (plan?.source === 'CONTINUE' && !branchExists) {
+        throw new Error(`branch ${branch} no longer exists in ${workspacePath}`);
+    }
     if (branchExists) {
+        // Git refuses to check one branch out in two worktrees. Saying which
+        // worktree holds it beats the raw «is already checked out» from git.
+        const holder = await worktreeHolding(workspacePath, branch);
+        if (holder) {
+            throw new Error(`branch ${branch} is already checked out in ${holder}`);
+        }
         await git(workspacePath, 'worktree', 'add', worktreePath, branch);
+        return { branch, worktreePath };
     }
-    else {
-        if (options.requireExistingBranch) {
-            // The caller is restoring a session that already produced work. Creating
-            // a fresh branch off HEAD here would look like success while quietly
-            // hiding every commit the agent made — fail loudly instead.
-            throw new Error(`session branch ${branch} no longer exists in ${workspacePath}`);
+    if (options.requireExistingBranch) {
+        // The caller is restoring a session that already produced work. Creating
+        // a fresh branch off HEAD here would look like success while quietly
+        // hiding every commit the agent made — fail loudly instead.
+        throw new Error(`session branch ${branch} no longer exists in ${workspacePath}`);
+    }
+    // Fork point: the sha the API pinned, then the branch it named, then HEAD.
+    // A pinned sha that is not in this repository is not worth guessing around —
+    // branching off the wrong commit is the failure this whole plan removes.
+    const startPoint = await resolveStartPoint(workspacePath, plan);
+    // What HEAD points at, read BEFORE the worktree is added. This is the only
+    // chance to learn the fork point for a session created while the runner was
+    // offline: the API had nobody to ask, so `branchPlan.baseBranch` is empty and
+    // without this the base is never pinned at all — which switches off the drift
+    // guard for that session's whole life (QA-107).
+    const headBranch = plan?.baseBranch
+        ? plan.baseBranch
+        : await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD')
+            .then((name) => (name && name !== 'HEAD' ? name : undefined))
+            .catch(() => undefined);
+    await git(workspacePath, 'worktree', 'add', '-b', branch, worktreePath, startPoint);
+    const baseSha = await git(workspacePath, 'rev-parse', startPoint).catch(() => undefined);
+    return {
+        branch,
+        worktreePath,
+        ...(headBranch ? { baseBranch: headBranch } : {}),
+        ...(baseSha ? { baseSha } : {}),
+    };
+}
+/**
+ * DIRECT mode (session 16): the session's workplace IS the project folder.
+ *
+ * Nothing is created and nothing is moved. The folder stays on the branch it is
+ * on, and that branch is the session's branch — which is the whole point: the
+ * work the agent does is already where the person expects to find it, with no
+ * «Apply» step in between and nothing to lose if the session is never applied.
+ *
+ * The two refusals are both about NOT guessing:
+ *
+ *  - not a git work tree — every git surface downstream would fail one call at
+ *    a time instead of once, here, with a sentence that names the folder;
+ *  - a detached HEAD — commits would land on no branch at all and be reachable
+ *    only by sha. A person who checked out a tag to look at something must not
+ *    discover an agent committed onto it.
+ *
+ * The path returned is the repository ROOT, not necessarily the folder that was
+ * configured. Every path in the Source Control panel is repo-root-relative
+ * because that is what `git status` prints, so the root is the only place the
+ * paths and the commands agree — and it is also the confinement root layer 1
+ * hands the agent.
+ */
+export async function prepareDirectWorkspace(workspacePath) {
+    const inside = await git(workspacePath, 'rev-parse', '--is-inside-work-tree').catch(() => null);
+    if (inside !== 'true') {
+        throw new Error(`${workspacePath} is not a git work tree`);
+    }
+    const branch = await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD').catch(() => null);
+    if (!branch || branch === 'HEAD') {
+        throw new Error('The project folder is not on a branch (detached HEAD) — check a branch out there before starting a session');
+    }
+    const top = await git(workspacePath, 'rev-parse', '--show-toplevel').catch(() => null);
+    const baseSha = await git(workspacePath, 'rev-parse', 'HEAD').catch(() => undefined);
+    return {
+        branch,
+        worktreePath: top || workspacePath,
+        baseBranch: branch,
+        ...(baseSha ? { baseSha } : {}),
+    };
+}
+async function resolveStartPoint(workspacePath, plan) {
+    if (plan?.baseSha && /^[0-9a-f]{7,64}$/i.test(plan.baseSha)) {
+        const exists = await git(workspacePath, 'rev-parse', '--verify', '--quiet', `${plan.baseSha}^{commit}`)
+            .then(() => true)
+            .catch(() => false);
+        if (exists)
+            return plan.baseSha;
+        throw new Error(`base commit ${plan.baseSha} is not in ${workspacePath}`);
+    }
+    const baseBranch = plan?.baseBranch ? sanitizeBranch(plan.baseBranch) : null;
+    if (baseBranch) {
+        const exists = await git(workspacePath, 'rev-parse', '--verify', '--quiet', baseBranch)
+            .then(() => true)
+            .catch(() => false);
+        if (exists)
+            return baseBranch;
+        throw new Error(`base branch ${baseBranch} is not in ${workspacePath}`);
+    }
+    return 'HEAD';
+}
+/** Which worktree, if any, currently has `branch` checked out. */
+async function worktreeHolding(workspacePath, branch) {
+    const raw = await git(workspacePath, 'worktree', 'list', '--porcelain').catch(() => '');
+    let current = null;
+    for (const line of raw.split('\n')) {
+        if (line.startsWith('worktree '))
+            current = line.slice('worktree '.length).trim();
+        else if (line.startsWith('branch ') && current) {
+            if (line
+                .slice('branch '.length)
+                .trim()
+                .replace(/^refs\/heads\//, '') === branch) {
+                return current;
+            }
         }
-        await git(workspacePath, 'worktree', 'add', '-b', branch, worktreePath, 'HEAD');
     }
-    return { branch, worktreePath };
+    return null;
+}
+// ─── Preview worktree (session 14) ───────────────────────────────────
+/**
+ * One preview checkout per repository, and never the project folder itself.
+ *
+ * The honest constraint behind «show me branch B while branch A is running»:
+ * the docker build context IS the project folder, so a rebuild there replaces
+ * the single running copy. A second worktree is the only way to have both — and
+ * the runner NEVER switches the branch in the project folder, because that
+ * silently moves the base, and the target of «Apply», for every session of the
+ * project at once.
+ *
+ * Checked out DETACHED at a sha rather than on the branch: git refuses to have
+ * one branch checked out twice, and a preview is a snapshot of a commit, not a
+ * place anybody commits.
+ */
+export function previewWorktreePath(workspaceKey) {
+    const safe = workspaceKey.replace(/[^A-Za-z0-9_-]/g, '-').slice(-60) || 'preview';
+    return path.join(previewsDir(), safe);
+}
+export async function ensurePreviewWorktree(input) {
+    const branch = sanitizeBranch(input.branch);
+    if (!branch)
+        throw new Error('Invalid branch name');
+    const sha = await git(input.workspacePath, 'rev-parse', `${branch}^{commit}`).catch(() => null);
+    if (!sha)
+        throw new Error(`Branch ${branch} is not in this repository`);
+    const worktreePath = previewWorktreePath(input.workspaceKey);
+    fs.mkdirSync(previewsDir(), { recursive: true, mode: 0o700 });
+    await git(input.workspacePath, 'worktree', 'prune').catch(() => undefined);
+    if (fs.existsSync(path.join(worktreePath, '.git'))) {
+        // Reuse the slot: a preview is a place, not a history. `--detach` keeps it
+        // out of the branch namespace, so moving it cannot collide with a session.
+        await git(worktreePath, 'checkout', '--detach', sha);
+        await git(worktreePath, 'reset', '--hard', sha);
+        await git(worktreePath, 'clean', '-fd').catch(() => undefined);
+        return { worktreePath, branch, sha };
+    }
+    await git(input.workspacePath, 'worktree', 'add', '--detach', worktreePath, sha);
+    return { worktreePath, branch, sha };
+}
+/** Give the slot back. The branch is untouched — it was never checked out. */
+export async function removePreviewWorktree(workspaceKey) {
+    const worktreePath = previewWorktreePath(workspaceKey);
+    if (!fs.existsSync(worktreePath))
+        return false;
+    const gitFile = path.join(worktreePath, '.git');
+    let mainRepo = null;
+    if (fs.existsSync(gitFile) && fs.statSync(gitFile).isFile()) {
+        const pointer = fs
+            .readFileSync(gitFile, 'utf8')
+            .match(/^gitdir:\s*(.+)$/m)?.[1]
+            ?.trim();
+        if (pointer) {
+            const dotGit = path.resolve(pointer, '..', '..');
+            if (path.basename(dotGit) === '.git')
+                mainRepo = path.dirname(dotGit);
+        }
+    }
+    if (mainRepo) {
+        await git(mainRepo, 'worktree', 'remove', '--force', worktreePath);
+    }
+    else {
+        fs.rmSync(worktreePath, { recursive: true, force: true });
+    }
+    return true;
 }
 /**
  * Drop a session branch after its worktree is gone. Only ever called when the
@@ -133,6 +402,23 @@ export async function deleteSessionBranch(workspacePath, branch) {
     const safe = sanitizeBranch(branch);
     if (!safe)
         throw new Error(`refusing to delete an unsafe branch name: ${branch}`);
+    // Session 16: a DIRECT session's «session branch» is the branch the PERSON is
+    // working on, and deleting a session must never be able to delete that. The
+    // API already refuses to ask, and git itself refuses to drop a branch that is
+    // checked out — but this is the line that would run the command, so it is the
+    // line that checks. Three cheap reads against an operation with no undo.
+    // The worktree this branch lived in was removed a moment ago; without a prune
+    // its stale registration would answer «still checked out» and leave a branch
+    // behind on every ordinary purge.
+    await git(workspacePath, 'worktree', 'prune').catch(() => undefined);
+    const current = await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD').catch(() => null);
+    if (current === safe) {
+        throw new Error(`refusing to delete ${safe}: the project folder is on it`);
+    }
+    const holder = await worktreeHolding(workspacePath, safe);
+    if (holder) {
+        throw new Error(`refusing to delete ${safe}: it is checked out in ${holder}`);
+    }
     await git(workspacePath, 'branch', '-D', safe);
 }
 /**