runwork 0.10.0 → 0.10.2

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`.

package/dist/git/credentials.js

@@ -1,16 +1,37 @@
 import { execFileSync } from 'child_process';
 import { getCredentials } from '../auth/store.js';
+/**
+ * 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 function buildHelperValue(execPath) {
+    const normalised = execPath.replace(/\\/g, '/');
+    return `!"${normalised}" git-credential-helper`;
+}
 /**
  * Configure git to use the runwork credential helper for our remote.
  * Called by `runwork login` and `runwork init`.
  */
 export async function configureGitCredentials(remoteUrl) {
     const origin = new URL(remoteUrl).origin;
+    const helperValue = buildHelperValue(process.execPath);
     try {
         execFileSync('git', [
             'config', '--global',
             `credential.${origin}.helper`,
-            '!runwork git-credential-helper',
+            helperValue,
         ], { stdio: 'pipe' });
     }
     catch (err) {

package/dist/git/preflight.d.ts

@@ -1,25 +1,54 @@
+export type GitSource = 'PATH' | 'where' | 'registry' | 'canonical';
 export interface GitProbe {
     installed: boolean;
     /** Trimmed `git --version` output when detected; undefined otherwise. */
     version?: string;
+    /** Resolved binary path; 'git' when bare PATH lookup worked, absolute when discovered via fallback. */
+    path?: string;
+    /** How we resolved the binary -- useful for `runwork doctor --verbose` diagnostics. */
+    source?: GitSource;
     /** Underlying error for diagnostics (most often ENOENT on a missing git binary). */
     error?: NodeJS.ErrnoException;
 }
 /**
- * Probe whether `git` is callable from this process. We use `execFileSync`
- * (not `which`/`where.exe`) so the check follows the exact PATH lookup any
- * subsequent git invocation will use -- that way we never report "found"
- * when the real call would fail with ENOENT, and vice versa.
+ * Probe whether `git` is callable from this process.
+ *
+ * Strategy:
+ *   1. Try a bare `git --version` -- the common path on macOS, Linux, and
+ *      most Windows installs.
+ *   2. On Windows, fall back to `where.exe git` (uses the same PATH +
+ *      PATHEXT rules cmd.exe applies, which are more permissive than
+ *      Bun's spawn lookup in standalone-compiled binaries).
+ *   3. On Windows, finally probe canonical install paths under
+ *      %ProgramFiles%, %ProgramFiles(x86)%, %LOCALAPPDATA%\Programs.
+ *
+ * When step 2 or 3 succeeds, we prepend the resolved directory to
+ * process.env.PATH so the ~50 other call sites that do
+ * `execFileSync('git', ...)` automatically benefit, without rewriting
+ * each one. Result is cached for the lifetime of the process.
  */
 export declare function probeGit(): GitProbe;
+/**
+ * Reset the cached probe result. Exposed for tests and for `runwork doctor`
+ * when it wants to re-check after a guided install.
+ */
+export declare function resetGitProbeCache(): void;
+/**
+ * Extract a short numeric version (e.g. "2.43.0") from a `git --version`
+ * output line. Returns null if no number could be parsed.
+ */
+export declare function parseGitVersion(versionLine: string | undefined): string | null;
 /**
  * Build a beginner-friendly message explaining how to recover from a missing
  * git binary. Includes a Windows-specific hint because the most common
  * scenario there is "winget install Git.Git just succeeded but this shell's
  * PATH was cached at launch" -- restarting the shell fixes it without a
  * second install attempt.
+ *
+ * If a probe error is supplied, the underlying message is appended so users
+ * can see *why* detection failed (ENOENT vs EACCES vs something else).
  */
-export declare function buildMissingGitMessage(commandName: string): string;
+export declare function buildMissingGitMessage(commandName: string, probe?: GitProbe): string;
 /**
  * Convenience wrapper for command entry points: probe git, and if it's
  * missing, print the beginner-friendly message and exit with code 1.