runwork 0.10.1 → 0.10.3

package/dist/git/__tests__/credential-helper-e2e.test.js

@@ -0,0 +1,195 @@
+/**
+ * End-to-end auth test.
+ *
+ * Spins up a tiny HTTP server that mimics the runwork.ai git endpoint's
+ * auth contract (HTTP Basic, any username, password = API key) and runs a
+ * real `git ls-remote` against it through a credential-helper script. This
+ * verifies the entire chain we depend on:
+ *
+ *   git -> credential.<origin>.helper -> our helper script -> our helper's
+ *   protocol output -> git constructs Basic auth -> server accepts it.
+ *
+ * Catches the class of bugs we've burned hours on (Pass 1's PATH issues,
+ * Pass 2's "logged in but no helper registered") *before* a user hits them.
+ *
+ * Note: this test exercises the contract our credential helper depends on,
+ * not the helper function itself -- credentials.test.ts already covers
+ * `handleGitCredentialRequest()` in isolation. Together they prove that
+ * (a) the helper produces the right protocol output and (b) git+server
+ * accept that output as Basic auth.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { mkdtempSync, writeFileSync, rmSync, chmodSync, existsSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { createServer } from 'http';
+import { probeGit } from '../preflight.js';
+const execFileAsync = promisify(execFile);
+const EXPECTED_API_KEY = 'test-api-key-abcd1234';
+/**
+ * Minimal HTTP server that:
+ *   - Returns 401 + WWW-Authenticate when no Basic auth is supplied
+ *   - Returns 401 when password (the API key) is wrong; username is ignored
+ *   - Returns 200 + a valid empty-refs pkt-line response when auth is correct
+ *
+ * The pkt-line response is the smallest valid output for `info/refs?
+ * service=git-upload-pack` -- the service announcement plus a flush packet.
+ * That's enough for `git ls-remote` to terminate successfully.
+ */
+function createBasicAuthGitServer(attempts) {
+    return new Promise((resolve) => {
+        const server = createServer((req, res) => {
+            const authHeader = req.headers['authorization'];
+            if (!authHeader || !authHeader.startsWith('Basic ')) {
+                attempts.push({ hasAuthHeader: false });
+                res.writeHead(401, {
+                    'WWW-Authenticate': 'Basic realm="Test"',
+                    'Content-Type': 'text/plain',
+                });
+                res.end('Authentication required');
+                return;
+            }
+            const decoded = Buffer.from(authHeader.slice(6), 'base64').toString('utf-8');
+            const colonIdx = decoded.indexOf(':');
+            const username = colonIdx >= 0 ? decoded.slice(0, colonIdx) : decoded;
+            const password = colonIdx >= 0 ? decoded.slice(colonIdx + 1) : '';
+            attempts.push({ hasAuthHeader: true, username, password });
+            if (password !== EXPECTED_API_KEY) {
+                res.writeHead(401, {
+                    'WWW-Authenticate': 'Basic realm="Test"',
+                    'Content-Type': 'text/plain',
+                });
+                res.end('Invalid API key');
+                return;
+            }
+            // Minimal valid info/refs response for git-upload-pack with no refs.
+            // Shape:
+            //   001e# service=git-upload-pack\n
+            //   0000
+            //   0000   (no refs)
+            const service = '# service=git-upload-pack\n';
+            const pktServiceLength = (service.length + 4).toString(16).padStart(4, '0');
+            const flush = '0000';
+            const body = `${pktServiceLength}${service}${flush}${flush}`;
+            res.writeHead(200, {
+                'Content-Type': 'application/x-git-upload-pack-advertisement',
+                'Cache-Control': 'no-cache',
+            });
+            res.end(body);
+        });
+        server.listen(0, '127.0.0.1', () => resolve(server));
+    });
+}
+/**
+ * Write a credential helper script into `dir` and return its path. The
+ * script ignores stdin (test fixtures don't need to honour git's
+ * action/host inputs) and prints the test's API key. Bash on macOS/Linux
+ * and Git Bash on Windows both run the resulting `!"<path>"` invocation
+ * the same way.
+ */
+function writeHelperScript(dir, apiKey) {
+    const scriptPath = join(dir, 'fake-helper.sh');
+    const body = [
+        '#!/usr/bin/env bash',
+        '# Test fixture: emits the git credential helper "get" protocol output',
+        '# with a hardcoded API key. The "get" arg is the only one git invokes',
+        '# during a fetch; "store"/"erase" are no-ops.',
+        'if [ "$1" != "get" ]; then exit 0; fi',
+        '# Drain stdin so git\'s pipe doesn\'t stall.',
+        'cat > /dev/null',
+        'echo "username=runwork"',
+        `echo "password=${apiKey}"`,
+        '',
+    ].join('\n');
+    writeFileSync(scriptPath, body, { mode: 0o755 });
+    // chmod is no-op on Windows but won't error.
+    chmodSync(scriptPath, 0o755);
+    return scriptPath;
+}
+describe('git credential helper e2e (Basic auth contract)', () => {
+    const gitProbe = probeGit();
+    const skipReason = !gitProbe.installed ? 'git not installed' : null;
+    let tmpDir;
+    let homeDir;
+    let xdgConfigHome;
+    let scriptPath;
+    let server;
+    let serverUrl;
+    let attempts = [];
+    beforeAll(async () => {
+        if (skipReason)
+            return;
+        tmpDir = mkdtempSync(join(tmpdir(), 'runwork-helper-e2e-'));
+        homeDir = join(tmpDir, 'home');
+        xdgConfigHome = join(homeDir, '.config');
+        // git -c gc.auto=0 needs ~/.gitconfig to exist when GIT_CONFIG_GLOBAL is
+        // pointed at a path that doesn't yet exist; pre-create the dir and
+        // empty file.
+        const gitConfigGlobal = join(homeDir, '.gitconfig');
+        require('fs').mkdirSync(homeDir, { recursive: true });
+        writeFileSync(gitConfigGlobal, '');
+        scriptPath = writeHelperScript(tmpDir, EXPECTED_API_KEY);
+        server = await createBasicAuthGitServer(attempts);
+        const addr = server.address();
+        serverUrl = `http://127.0.0.1:${addr.port}`;
+        // Register the credential helper globally in the isolated git config.
+        // We use the unscoped `credential.helper` (not `credential.<url>.helper`)
+        // because (a) the test config is fully isolated so we don't risk
+        // bleeding into other host auth flows and (b) git's URL matching for
+        // scoped helpers has subtleties that aren't what we're testing here --
+        // we're testing the helper *contract*, not git's URL matcher.
+        const gitBin = gitProbe.path ?? 'git';
+        await execFileAsync(gitBin, [
+            'config', '--file', gitConfigGlobal,
+            'credential.helper', `!"${scriptPath}"`,
+        ]);
+    });
+    afterAll(() => {
+        if (server)
+            server.close();
+        if (tmpDir && existsSync(tmpDir))
+            rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it.skipIf(skipReason)('git ls-remote authenticates via the credential helper end-to-end', async () => {
+        const gitBin = gitProbe.path ?? 'git';
+        // Use GIT_CONFIG_GLOBAL to isolate from the user's real ~/.gitconfig
+        // (which may have an auth helper registered for some other host).
+        const env = {
+            ...process.env,
+            GIT_CONFIG_GLOBAL: join(homeDir, '.gitconfig'),
+            GIT_CONFIG_SYSTEM: '/dev/null',
+            XDG_CONFIG_HOME: xdgConfigHome,
+            HOME: homeDir,
+            // Force git to never prompt -- if the helper fails, we want the
+            // command to exit non-zero, not hang.
+            GIT_TERMINAL_PROMPT: '0',
+        };
+        const path = '/test-workspace/test-app';
+        const url = `${serverUrl}${path}`;
+        // ls-remote against the fake server. Should exit 0 (server accepted
+        // auth and returned a valid -- empty -- ref advertisement).
+        const result = await execFileAsync(gitBin, ['ls-remote', url], { env });
+        expect(result.stdout).toBe('');
+        // No refs in the test response, so stdout is empty.
+        // Verify the server actually saw a Basic-auth attempt with our key.
+        const successAttempt = attempts.find((a) => a.hasAuthHeader && a.password === EXPECTED_API_KEY);
+        expect(successAttempt).toBeDefined();
+        expect(successAttempt.username).toBe('runwork');
+    }, 20_000);
+    it.skipIf(skipReason)('server rejects requests with no auth (sanity: contract is enforced)', async () => {
+        // Direct fetch with no Authorization header should 401.
+        const response = await fetch(`${serverUrl}/whatever`);
+        expect(response.status).toBe(401);
+        expect(response.headers.get('www-authenticate')).toContain('Basic');
+    });
+    it.skipIf(skipReason)('server rejects requests with the wrong API key (sanity: contract is enforced)', async () => {
+        const response = await fetch(`${serverUrl}/whatever`, {
+            headers: {
+                authorization: `Basic ${Buffer.from('runwork:wrong-key').toString('base64')}`,
+            },
+        });
+        expect(response.status).toBe(401);
+    });
+});

package/dist/git/__tests__/credentials.test.js

@@ -5,38 +5,51 @@ vi.mock('../../auth/store.js', () => ({
 }));
 const mockExecFileSync = (await import('child_process')).execFileSync;
 const { getCredentials: mockGetCredentials } = await import('../../auth/store.js');
-const { configureGitCredentials, removeGitCredentials, handleGitCredentialRequest, } = await import('../credentials.js');
+const { configureGitCredentials, removeGitCredentials, handleGitCredentialRequest, buildHelperValue, } = await import('../credentials.js');
 describe('git/credentials', () => {
     beforeEach(() => {
         vi.clearAllMocks();
     });
+    describe('buildHelperValue()', () => {
+        it('wraps the execPath in quotes and prefixes with !', () => {
+            expect(buildHelperValue('/usr/local/bin/runwork')).toBe('!"/usr/local/bin/runwork" git-credential-helper');
+        });
+        it('normalises Windows backslashes to forward slashes for .gitconfig safety', () => {
+            expect(buildHelperValue('C:\\Users\\test\\.runwork\\bin\\runwork.exe')).toBe('!"C:/Users/test/.runwork/bin/runwork.exe" git-credential-helper');
+        });
+        it('survives spaces in install paths via quoting', () => {
+            expect(buildHelperValue('C:\\Program Files\\Runwork\\runwork.exe')).toBe('!"C:/Program Files/Runwork/runwork.exe" git-credential-helper');
+        });
+    });
     describe('configureGitCredentials()', () => {
-        it('calls git config with correct args', async () => {
+        it('registers the helper using process.execPath, not bare "runwork"', async () => {
             await configureGitCredentials('https://runwork.ai/api/git/ws/app');
-            expect(mockExecFileSync).toHaveBeenCalledWith('git', [
-                'config',
-                '--global',
-                'credential.https://runwork.ai.helper',
-                '!runwork git-credential-helper',
-            ], { stdio: 'pipe' });
+            // Don't pin process.execPath itself (varies per machine), but
+            // assert the value follows the absolute-path shape so PATH-relative
+            // regressions are caught.
+            const call = mockExecFileSync.mock.calls.find((c) => c[0] === 'git' && c[1]?.includes('--global'));
+            expect(call).toBeDefined();
+            const args = call[1];
+            expect(args).toContain('config');
+            expect(args).toContain('--global');
+            expect(args).toContain('credential.https://runwork.ai.helper');
+            const helperValue = args[args.length - 1];
+            expect(helperValue).toMatch(/^!"[^"]+" git-credential-helper$/);
+            expect(helperValue).not.toBe('!runwork git-credential-helper');
+            // The path inside the quotes should be process.execPath, normalised.
+            expect(helperValue).toContain(process.execPath.replace(/\\/g, '/'));
         });
         it('extracts origin from full URL', async () => {
             await configureGitCredentials('https://custom.runwork.dev/api/git/ws-1/app-1');
-            expect(mockExecFileSync).toHaveBeenCalledWith('git', [
-                'config',
-                '--global',
-                'credential.https://custom.runwork.dev.helper',
-                '!runwork git-credential-helper',
-            ], { stdio: 'pipe' });
+            const call = mockExecFileSync.mock.calls[0];
+            const args = call[1];
+            expect(args[2]).toBe('credential.https://custom.runwork.dev.helper');
         });
         it('handles URL with port', async () => {
             await configureGitCredentials('https://localhost:8787/api/git/ws/app');
-            expect(mockExecFileSync).toHaveBeenCalledWith('git', [
-                'config',
-                '--global',
-                'credential.https://localhost:8787.helper',
-                '!runwork git-credential-helper',
-            ], { stdio: 'pipe' });
+            const call = mockExecFileSync.mock.calls[0];
+            const args = call[1];
+            expect(args[2]).toBe('credential.https://localhost:8787.helper');
         });
     });
     describe('removeGitCredentials()', () => {

package/dist/git/__tests__/preflight-resolution.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/git/__tests__/preflight-resolution.test.js

@@ -0,0 +1,366 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+// Mocks must be declared before imports of the module under test so vitest
+// hoists them above the static import.
+vi.mock('child_process', async () => {
+    const actual = await vi.importActual('child_process');
+    return { ...actual, execFileSync: vi.fn() };
+});
+vi.mock('fs', async () => {
+    const actual = await vi.importActual('fs');
+    return { ...actual, existsSync: vi.fn() };
+});
+vi.mock('os', async () => {
+    const actual = await vi.importActual('os');
+    return { ...actual, homedir: vi.fn(() => 'C:\\Users\\test') };
+});
+import { execFileSync } from 'child_process';
+import { existsSync } from 'fs';
+import { probeGit, resetGitProbeCache, buildMissingGitMessage, parseGitVersion, } from '../preflight.js';
+const mockedExec = vi.mocked(execFileSync);
+const mockedExists = vi.mocked(existsSync);
+function enoent(file) {
+    const err = new Error(`spawn ${file} ENOENT`);
+    err.code = 'ENOENT';
+    err.errno = -2;
+    err.syscall = `spawn ${file}`;
+    err.path = file;
+    return err;
+}
+describe('probeGit -- Windows fallback resolution', () => {
+    let originalPlatform;
+    let originalPath;
+    let originalProgramFiles;
+    let originalProgramFilesX86;
+    let originalLocalAppData;
+    beforeEach(() => {
+        resetGitProbeCache();
+        originalPlatform = Object.getOwnPropertyDescriptor(process, 'platform');
+        Object.defineProperty(process, 'platform', { value: 'win32', writable: true, configurable: true });
+        originalPath = process.env.PATH;
+        originalProgramFiles = process.env.ProgramFiles;
+        originalProgramFilesX86 = process.env['ProgramFiles(x86)'];
+        originalLocalAppData = process.env.LOCALAPPDATA;
+        process.env.PATH = 'C:\\Windows\\system32;C:\\Windows';
+        process.env.ProgramFiles = 'C:\\Program Files';
+        process.env['ProgramFiles(x86)'] = 'C:\\Program Files (x86)';
+        process.env.LOCALAPPDATA = 'C:\\Users\\test\\AppData\\Local';
+        mockedExec.mockReset();
+        mockedExists.mockReset();
+    });
+    afterEach(() => {
+        if (originalPlatform)
+            Object.defineProperty(process, 'platform', originalPlatform);
+        if (originalPath !== undefined)
+            process.env.PATH = originalPath;
+        else
+            delete process.env.PATH;
+        if (originalProgramFiles !== undefined)
+            process.env.ProgramFiles = originalProgramFiles;
+        else
+            delete process.env.ProgramFiles;
+        if (originalProgramFilesX86 !== undefined)
+            process.env['ProgramFiles(x86)'] = originalProgramFilesX86;
+        else
+            delete process.env['ProgramFiles(x86)'];
+        if (originalLocalAppData !== undefined)
+            process.env.LOCALAPPDATA = originalLocalAppData;
+        else
+            delete process.env.LOCALAPPDATA;
+        delete process.env.Path;
+    });
+    it('resolves via where.exe when bare git lookup fails', () => {
+        const realGitPath = 'C:\\Program Files\\Git\\cmd\\git.exe';
+        mockedExec.mockImplementation((file) => {
+            if (file === 'git')
+                throw enoent('git');
+            if (file === 'where.exe')
+                return Buffer.from(`${realGitPath}\r\n`);
+            if (file === realGitPath)
+                return Buffer.from('git version 2.43.0.windows.1');
+            throw enoent(file);
+        });
+        mockedExists.mockImplementation((p) => p === realGitPath);
+        const probe = probeGit();
+        expect(probe.installed).toBe(true);
+        expect(probe.source).toBe('where');
+        expect(probe.path).toBe(realGitPath);
+        expect(probe.version).toContain('git version 2.43.0');
+    });
+    it('prepends the resolved git directory to PATH', () => {
+        const realGitPath = 'C:\\Program Files\\Git\\cmd\\git.exe';
+        mockedExec.mockImplementation((file) => {
+            if (file === 'git')
+                throw enoent('git');
+            if (file === 'where.exe')
+                return Buffer.from(`${realGitPath}\r\n`);
+            if (file === realGitPath)
+                return Buffer.from('git version 2.43.0');
+            throw enoent(file);
+        });
+        mockedExists.mockReturnValue(true);
+        probeGit();
+        expect(process.env.PATH?.split(';')[0]).toBe('C:\\Program Files\\Git\\cmd');
+    });
+    it('also mirrors the new value into Path (case variant) when present', () => {
+        process.env.Path = process.env.PATH; // simulate Windows where Path is set
+        const realGitPath = 'C:\\Program Files\\Git\\cmd\\git.exe';
+        mockedExec.mockImplementation((file) => {
+            if (file === 'git')
+                throw enoent('git');
+            if (file === 'where.exe')
+                return Buffer.from(`${realGitPath}\r\n`);
+            if (file === realGitPath)
+                return Buffer.from('git version 2.43.0');
+            throw enoent(file);
+        });
+        mockedExists.mockReturnValue(true);
+        probeGit();
+        expect(process.env.Path).toBe(process.env.PATH);
+    });
+    it('prefers .exe match when where.exe lists multiple candidates', () => {
+        const exePath = 'C:\\Program Files\\Git\\cmd\\git.exe';
+        const cmdShim = 'C:\\Users\\test\\.runwork\\bin\\git';
+        mockedExec.mockImplementation((file) => {
+            if (file === 'git')
+                throw enoent('git');
+            if (file === 'where.exe')
+                return Buffer.from(`${cmdShim}\r\n${exePath}\r\n`);
+            if (file === exePath)
+                return Buffer.from('git version 2.43.0');
+            throw enoent(file);
+        });
+        mockedExists.mockImplementation((p) => p === exePath || p === cmdShim);
+        const probe = probeGit();
+        expect(probe.path).toBe(exePath);
+    });
+    it('falls back to the registry when where.exe fails', () => {
+        const installRoot = 'C:\\Program Files\\Git';
+        const gitExe = 'C:\\Program Files\\Git\\cmd\\git.exe';
+        mockedExec.mockImplementation((file, args) => {
+            if (file === 'git')
+                throw enoent('git');
+            if (file === 'where.exe')
+                throw enoent('where.exe');
+            if (file === 'reg.exe') {
+                // Only HKLM has a value; HKCU returns nothing (we throw to mimic).
+                const key = args?.[1] ?? '';
+                if (key.includes('HKLM')) {
+                    return Buffer.from('HKEY_LOCAL_MACHINE\\SOFTWARE\\GitForWindows\r\n' +
+                        `    InstallPath    REG_SZ    ${installRoot}\r\n`);
+                }
+                throw enoent('reg.exe');
+            }
+            if (file === gitExe)
+                return Buffer.from('git version 2.43.0');
+            throw enoent(file);
+        });
+        mockedExists.mockImplementation((p) => p === gitExe);
+        const probe = probeGit();
+        expect(probe.installed).toBe(true);
+        expect(probe.source).toBe('registry');
+        expect(probe.path).toBe(gitExe);
+        expect(process.env.PATH?.split(';')[0]).toBe('C:\\Program Files\\Git\\cmd');
+    });
+    it('honours HKCU\\Software\\GitForWindows when HKLM is empty', () => {
+        const installRoot = 'C:\\Users\\test\\AppData\\Local\\Programs\\Git';
+        const gitExe = 'C:\\Users\\test\\AppData\\Local\\Programs\\Git\\cmd\\git.exe';
+        mockedExec.mockImplementation((file, args) => {
+            if (file === 'git')
+                throw enoent('git');
+            if (file === 'where.exe')
+                throw enoent('where.exe');
+            if (file === 'reg.exe') {
+                const key = args?.[1] ?? '';
+                if (key.includes('HKLM'))
+                    throw enoent('reg.exe');
+                if (key.includes('HKCU')) {
+                    return Buffer.from('HKEY_CURRENT_USER\\Software\\GitForWindows\r\n' +
+                        `    InstallPath    REG_SZ    ${installRoot}\r\n`);
+                }
+                throw enoent('reg.exe');
+            }
+            if (file === gitExe)
+                return Buffer.from('git version 2.43.0');
+            throw enoent(file);
+        });
+        mockedExists.mockImplementation((p) => p === gitExe);
+        const probe = probeGit();
+        expect(probe.installed).toBe(true);
+        expect(probe.source).toBe('registry');
+        expect(probe.path).toBe(gitExe);
+    });
+    it('falls back to canonical install path when where.exe and registry both fail', () => {
+        const canonical = 'C:\\Program Files\\Git\\cmd\\git.exe';
+        mockedExec.mockImplementation((file) => {
+            if (file === 'git')
+                throw enoent('git');
+            if (file === 'where.exe')
+                throw enoent('where.exe');
+            if (file === 'reg.exe')
+                throw enoent('reg.exe');
+            if (file === canonical)
+                return Buffer.from('git version 2.43.0');
+            throw enoent(file);
+        });
+        mockedExists.mockImplementation((p) => p === canonical);
+        const probe = probeGit();
+        expect(probe.installed).toBe(true);
+        expect(probe.source).toBe('canonical');
+        expect(probe.path).toBe(canonical);
+        expect(process.env.PATH?.split(';')[0]).toBe('C:\\Program Files\\Git\\cmd');
+    });
+    it('finds a portable MinGit dropped under ~/.runwork/tools/mingit', () => {
+        const portable = 'C:\\Users\\test\\.runwork\\tools\\mingit\\cmd\\git.exe';
+        mockedExec.mockImplementation((file) => {
+            if (file === 'git')
+                throw enoent('git');
+            if (file === 'where.exe')
+                throw enoent('where.exe');
+            if (file === 'reg.exe')
+                throw enoent('reg.exe');
+            if (file === portable)
+                return Buffer.from('git version 2.45.0.windows.1');
+            throw enoent(file);
+        });
+        mockedExists.mockImplementation((p) => p === portable);
+        const probe = probeGit();
+        expect(probe.installed).toBe(true);
+        expect(probe.source).toBe('canonical');
+        expect(probe.path).toBe(portable);
+    });
+    it('finds a Scoop install at ~/scoop/apps/git/current/cmd/git.exe', () => {
+        const scoop = 'C:\\Users\\test\\scoop\\apps\\git\\current\\cmd\\git.exe';
+        mockedExec.mockImplementation((file) => {
+            if (file === 'git')
+                throw enoent('git');
+            if (file === 'where.exe')
+                throw enoent('where.exe');
+            if (file === 'reg.exe')
+                throw enoent('reg.exe');
+            if (file === scoop)
+                return Buffer.from('git version 2.45.0');
+            throw enoent(file);
+        });
+        mockedExists.mockImplementation((p) => p === scoop);
+        const probe = probeGit();
+        expect(probe.installed).toBe(true);
+        expect(probe.path).toBe(scoop);
+    });
+    it('returns installed=false when nothing resolves and preserves the bare-call error', () => {
+        mockedExec.mockImplementation((file) => { throw enoent(file); });
+        mockedExists.mockReturnValue(false);
+        const probe = probeGit();
+        expect(probe.installed).toBe(false);
+        expect(probe.error?.code).toBe('ENOENT');
+        expect(probe.error?.path).toBe('git');
+        // No PATH side-effect when nothing was resolved.
+        expect(process.env.PATH?.startsWith('C:\\Windows\\system32')).toBe(true);
+    });
+    it('caches the probe result across calls and stops re-spawning git', () => {
+        const realGitPath = 'C:\\Program Files\\Git\\cmd\\git.exe';
+        mockedExec.mockImplementation((file) => {
+            if (file === 'git')
+                throw enoent('git');
+            if (file === 'where.exe')
+                return Buffer.from(`${realGitPath}\r\n`);
+            if (file === realGitPath)
+                return Buffer.from('git version 2.43.0');
+            throw enoent(file);
+        });
+        mockedExists.mockReturnValue(true);
+        const first = probeGit();
+        const callsAfterFirst = mockedExec.mock.calls.length;
+        const second = probeGit();
+        expect(second).toBe(first);
+        expect(mockedExec.mock.calls.length).toBe(callsAfterFirst);
+    });
+    it('does not double-prepend PATH on repeat probes after a cache reset', () => {
+        const realGitPath = 'C:\\Program Files\\Git\\cmd\\git.exe';
+        mockedExec.mockImplementation((file) => {
+            if (file === 'git')
+                throw enoent('git');
+            if (file === 'where.exe')
+                return Buffer.from(`${realGitPath}\r\n`);
+            if (file === realGitPath)
+                return Buffer.from('git version 2.43.0');
+            throw enoent(file);
+        });
+        mockedExists.mockReturnValue(true);
+        probeGit();
+        const pathAfterFirst = process.env.PATH;
+        resetGitProbeCache();
+        probeGit();
+        expect(process.env.PATH).toBe(pathAfterFirst);
+    });
+    it('skips canonical paths whose env var is unset', () => {
+        delete process.env.ProgramFiles;
+        delete process.env['ProgramFiles(x86)'];
+        delete process.env.LOCALAPPDATA;
+        // Only the hard-coded "C:\\Program Files\\Git\\cmd\\git.exe" default
+        // remains. Make existsSync reject it too -- nothing should resolve.
+        mockedExec.mockImplementation((file) => { throw enoent(file); });
+        mockedExists.mockReturnValue(false);
+        const probe = probeGit();
+        expect(probe.installed).toBe(false);
+    });
+});
+describe('probeGit -- non-Windows hosts skip the fallback', () => {
+    let originalPlatform;
+    beforeEach(() => {
+        resetGitProbeCache();
+        originalPlatform = Object.getOwnPropertyDescriptor(process, 'platform');
+        Object.defineProperty(process, 'platform', { value: 'darwin', writable: true, configurable: true });
+        mockedExec.mockReset();
+        mockedExists.mockReset();
+    });
+    afterEach(() => {
+        if (originalPlatform)
+            Object.defineProperty(process, 'platform', originalPlatform);
+    });
+    it('does not invoke where.exe on macOS when bare lookup fails', () => {
+        mockedExec.mockImplementation((file) => { throw enoent(file); });
+        mockedExists.mockReturnValue(true);
+        const probe = probeGit();
+        expect(probe.installed).toBe(false);
+        const calledFiles = mockedExec.mock.calls.map((c) => c[0]);
+        expect(calledFiles).toContain('git');
+        expect(calledFiles).not.toContain('where.exe');
+    });
+    it('returns immediately on bare-call success without further probing', () => {
+        mockedExec.mockImplementation((file) => {
+            if (file === 'git')
+                return Buffer.from('git version 2.45.0');
+            throw enoent(file);
+        });
+        mockedExists.mockReturnValue(false);
+        const probe = probeGit();
+        expect(probe.installed).toBe(true);
+        expect(probe.source).toBe('PATH');
+        expect(probe.path).toBe('git');
+        expect(mockedExists).not.toHaveBeenCalled();
+    });
+});
+describe('parseGitVersion', () => {
+    it('extracts a semver-ish number from `git --version` output', () => {
+        expect(parseGitVersion('git version 2.43.0')).toBe('2.43.0');
+        expect(parseGitVersion('git version 2.43.0.windows.1')).toBe('2.43.0');
+        expect(parseGitVersion('git version 2.45')).toBe('2.45');
+    });
+    it('returns null for unparsable input', () => {
+        expect(parseGitVersion(undefined)).toBeNull();
+        expect(parseGitVersion('')).toBeNull();
+        expect(parseGitVersion('not a version')).toBeNull();
+    });
+});
+describe('buildMissingGitMessage with a probe error', () => {
+    it('appends the underlying error message when one is present', () => {
+        const err = new Error('spawn git ENOENT');
+        err.code = 'ENOENT';
+        const msg = buildMissingGitMessage('clone', { installed: false, error: err });
+        expect(msg).toContain('Underlying error: spawn git ENOENT');
+    });
+    it('omits the underlying-error footer when no probe is supplied', () => {
+        const msg = buildMissingGitMessage('clone');
+        expect(msg).not.toContain('Underlying error');
+    });
+});

package/dist/git/credentials.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Build the value we hand to `git config credential.<origin>.helper`.
+ *
+ * Git invokes credential helpers via its bash shell (Git Bash on Windows,
+ * /bin/sh elsewhere). A leading `!` tells git to treat the value as a raw
+ * shell command. We embed the absolute path of the *currently running*
+ * runwork binary so the helper invocation never depends on PATH at the
+ * moment git happens to call it -- which used to be a real failure mode
+ * on Windows when runwork.exe sits in `~/.runwork/bin` and that directory
+ * isn't picked up by git's bash subshell.
+ *
+ * The path is wrapped in quotes (handles spaces in install paths) and on
+ * Windows we normalise backslashes to forward slashes -- bash on Windows
+ * accepts both, but forward slashes avoid escaping issues in the .gitconfig
+ * file itself.
+ */
+export declare function buildHelperValue(execPath: string): string;
 /**
  * Configure git to use the runwork credential helper for our remote.
  * Called by `runwork login` and `runwork init`.