runwork 0.13.4 → 0.15.0

package/dist/git/__tests__/classify-sync-error.test.js

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { classifySyncError, diagnoseSyncError } from '../classify-sync-error.js';
+describe('git/classify-sync-error', () => {
+    describe('classifySyncError()', () => {
+        it('detects a missing/misnamed runwork remote', () => {
+            expect(classifySyncError("fatal: 'runwork' does not appear to be a git repository")).toBe('no-remote');
+            expect(classifySyncError('fatal: No such remote: runwork')).toBe('no-remote');
+        });
+        it('detects authentication failures', () => {
+            expect(classifySyncError('fatal: Authentication failed for https://runwork.ai/...')).toBe('auth');
+            expect(classifySyncError('fatal: could not read Username for https://runwork.ai: terminal prompts disabled')).toBe('auth');
+            expect(classifySyncError("fatal: unable to access '...': The requested URL returned error: 403")).toBe('auth');
+        });
+        it('detects network failures', () => {
+            expect(classifySyncError("fatal: unable to access '...': Could not resolve host: runwork.ai")).toBe('network');
+            expect(classifySyncError('fatal: unable to access: Failed to connect to runwork.ai port 443: Connection timed out')).toBe('network');
+        });
+        it('detects merge/rebase conflicts and the stash-conflict sentinel', () => {
+            expect(classifySyncError('CONFLICT (content): Merge conflict in src/App.tsx')).toBe('conflict');
+            expect(classifySyncError('error: Automatic merge failed')).toBe('conflict');
+            expect(classifySyncError('stash-conflict')).toBe('conflict');
+        });
+        it('falls back to unknown for unrecognized errors and empty input', () => {
+            expect(classifySyncError('some unexpected git failure')).toBe('unknown');
+            expect(classifySyncError(undefined)).toBe('unknown');
+            expect(classifySyncError('')).toBe('unknown');
+        });
+        it('is case-insensitive', () => {
+            expect(classifySyncError('AUTHENTICATION FAILED')).toBe('auth');
+            expect(classifySyncError('could not resolve HOST')).toBe('network');
+        });
+    });
+    describe('diagnoseSyncError()', () => {
+        it('points a no-remote failure at doctor --fix, not network/session', () => {
+            const d = diagnoseSyncError("fatal: 'runwork' does not appear to be a git repository");
+            expect(d.reason).toBe('no-remote');
+            expect(d.suggestions.join(' ')).toContain('runwork doctor --fix');
+            // Must NOT regress to the old misleading "session expired / network" advice.
+            expect(d.diagnosis.toLowerCase()).not.toContain('session expired');
+        });
+        it('points an auth failure at credential-helper remediation', () => {
+            const d = diagnoseSyncError('fatal: Authentication failed');
+            expect(d.reason).toBe('auth');
+            expect(d.suggestions.join(' ')).toContain('runwork doctor --fix');
+        });
+        it('gives stash-conflict a restore-specific message', () => {
+            const d = diagnoseSyncError('stash-conflict');
+            expect(d.reason).toBe('conflict');
+            expect(d.message).toContain('restoring local changes');
+        });
+        it('preserves the raw error in the unknown-case message', () => {
+            const d = diagnoseSyncError('weird git explosion');
+            expect(d.reason).toBe('unknown');
+            expect(d.message).toBe('weird git explosion');
+        });
+    });
+});

package/dist/git/__tests__/ensure-git-credential-helper.test.d.ts

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

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

@@ -0,0 +1,133 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('child_process');
+vi.mock('fs', () => ({
+    existsSync: vi.fn(),
+}));
+vi.mock('../../auth/store.js', () => ({
+    getCredentials: vi.fn(),
+}));
+const mockExecFileSync = (await import('child_process')).execFileSync;
+const { existsSync: mockExistsSync } = await import('fs');
+const { lookupCredentialHelper, helperBinaryStatus, ensureGitCredentialHelper, } = await import('../credentials.js');
+/** Build a `git config --get-regexp` stdout block from full config lines. */
+function gitConfigOutput(...lines) {
+    return Buffer.from(lines.join('\n') + '\n');
+}
+/** True when a recorded execFileSync call wrote a credential helper config. */
+function isHelperWrite(call) {
+    const args = call[1];
+    return call[0] === 'git'
+        && Array.isArray(args)
+        && args.includes('--global')
+        && args.some(a => /^credential\..*\.helper$/.test(a))
+        && !args.includes('--get-regexp')
+        && !args.includes('--unset');
+}
+describe('git/credentials lazy-ensure', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('lookupCredentialHelper()', () => {
+        it('returns "none" when git has no matching entries (get-regexp exits non-zero)', () => {
+            mockExecFileSync.mockImplementation(() => {
+                throw new Error('exit 1'); // git config --get-regexp: no match
+            });
+            expect(lookupCredentialHelper('https://runwork.ai')).toEqual({ status: 'none' });
+        });
+        it('returns "unscoped" when entries exist but none match the origin', () => {
+            mockExecFileSync.mockReturnValue(gitConfigOutput('credential.https://runwork-staging.example.com.helper !runwork git-credential-helper'));
+            expect(lookupCredentialHelper('https://runwork.ai')).toEqual({
+                status: 'unscoped',
+                otherCount: 1,
+            });
+        });
+        it('returns "registered" with the helper value when a scoped entry exists', () => {
+            mockExecFileSync.mockReturnValue(gitConfigOutput('credential.https://runwork.ai.helper !"/usr/local/bin/runwork" git-credential-helper'));
+            expect(lookupCredentialHelper('https://runwork.ai')).toEqual({
+                status: 'registered',
+                value: '!"/usr/local/bin/runwork" git-credential-helper',
+            });
+        });
+        it('matches the correct origin among multiple entries', () => {
+            mockExecFileSync.mockReturnValue(gitConfigOutput('credential.https://runwork-staging.example.com.helper !runwork git-credential-helper', 'credential.https://runwork.ai.helper !"/usr/local/bin/runwork" git-credential-helper'));
+            const result = lookupCredentialHelper('https://runwork.ai');
+            expect(result.status).toBe('registered');
+        });
+    });
+    describe('helperBinaryStatus()', () => {
+        it('trusts PATH-relative helper values (no on-disk check)', () => {
+            expect(helperBinaryStatus('!runwork git-credential-helper')).toEqual({ ok: true, path: null });
+            expect(mockExistsSync).not.toHaveBeenCalled();
+        });
+        it('reports ok when an absolute-path binary exists', () => {
+            vi.mocked(mockExistsSync).mockReturnValue(true);
+            expect(helperBinaryStatus('!"/usr/local/bin/runwork" git-credential-helper')).toEqual({
+                ok: true,
+                path: '/usr/local/bin/runwork',
+            });
+        });
+        it('reports not-ok with the path when an absolute-path binary is missing', () => {
+            vi.mocked(mockExistsSync).mockReturnValue(false);
+            expect(helperBinaryStatus('!"/old/path/runwork" git-credential-helper')).toEqual({
+                ok: false,
+                path: '/old/path/runwork',
+            });
+        });
+        it('handles Windows absolute paths', () => {
+            vi.mocked(mockExistsSync).mockReturnValue(true);
+            const result = helperBinaryStatus('!"C:/Users/test/.runwork/bin/runwork.exe" git-credential-helper');
+            expect(result.ok).toBe(true);
+            expect(result.path).toBe('C:/Users/test/.runwork/bin/runwork.exe');
+        });
+    });
+    describe('ensureGitCredentialHelper()', () => {
+        it('is a no-op when a valid scoped helper is already registered', async () => {
+            mockExecFileSync.mockImplementation((_file, args) => {
+                if (args.includes('--get-regexp')) {
+                    return gitConfigOutput('credential.https://runwork.ai.helper !runwork git-credential-helper');
+                }
+                return Buffer.from('');
+            });
+            await ensureGitCredentialHelper('https://runwork.ai/api/git/ws/app');
+            // No registration write should have happened.
+            expect(mockExecFileSync.mock.calls.some(isHelperWrite)).toBe(false);
+        });
+        it('registers the helper when none is present (the get_cli_setup path)', async () => {
+            mockExecFileSync.mockImplementation((_file, args) => {
+                if (args.includes('--get-regexp')) {
+                    throw new Error('exit 1'); // nothing registered yet
+                }
+                return Buffer.from('');
+            });
+            await ensureGitCredentialHelper('https://runwork.ai/api/git/ws/app');
+            const write = mockExecFileSync.mock.calls.find(isHelperWrite);
+            expect(write).toBeDefined();
+            expect(write[1]).toContain('credential.https://runwork.ai.helper');
+        });
+        it('registers when entries exist but none are scoped to this origin', async () => {
+            mockExecFileSync.mockImplementation((_file, args) => {
+                if (args.includes('--get-regexp')) {
+                    return gitConfigOutput('credential.https://other.example.com.helper !runwork git-credential-helper');
+                }
+                return Buffer.from('');
+            });
+            await ensureGitCredentialHelper('https://runwork.ai');
+            expect(mockExecFileSync.mock.calls.some(isHelperWrite)).toBe(true);
+        });
+        it('repairs a stale helper that points at a missing binary', async () => {
+            vi.mocked(mockExistsSync).mockReturnValue(false);
+            mockExecFileSync.mockImplementation((_file, args) => {
+                if (args.includes('--get-regexp')) {
+                    return gitConfigOutput('credential.https://runwork.ai.helper !"/old/path/runwork" git-credential-helper');
+                }
+                return Buffer.from('');
+            });
+            await ensureGitCredentialHelper('https://runwork.ai');
+            expect(mockExecFileSync.mock.calls.some(isHelperWrite)).toBe(true);
+        });
+        it('is a no-op for an unparseable baseUrl', async () => {
+            await ensureGitCredentialHelper('not a url');
+            expect(mockExecFileSync).not.toHaveBeenCalled();
+        });
+    });
+});

package/dist/git/__tests__/ensure-runwork-remote.test.d.ts

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

package/dist/git/__tests__/ensure-runwork-remote.test.js

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('child_process');
+const mockExecFileSync = (await import('child_process')).execFileSync;
+const { normalizeRemoteUrl, listRemotes, ensureRunworkRemote, } = await import('../remote.js');
+/** Build `git remote -v` stdout from name->url pairs (fetch + push lines). */
+function remoteVerbose(pairs) {
+    const lines = [];
+    for (const [name, url] of Object.entries(pairs)) {
+        lines.push(`${name}\t${url} (fetch)`);
+        lines.push(`${name}\t${url} (push)`);
+    }
+    return Buffer.from(lines.join('\n') + '\n');
+}
+/**
+ * Drive ensureRunworkRemote/listRemotes against a fixed `git remote -v`
+ * result, recording any set-url/add mutations.
+ */
+function withRemotes(pairs) {
+    const setUrl = [];
+    const add = [];
+    mockExecFileSync.mockImplementation((_file, args) => {
+        if (args[0] === 'remote' && args[1] === '-v') {
+            return remoteVerbose(pairs);
+        }
+        if (args[0] === 'remote' && args[1] === 'set-url') {
+            setUrl.push(args);
+            return Buffer.from('');
+        }
+        if (args[0] === 'remote' && args[1] === 'add') {
+            add.push(args);
+            return Buffer.from('');
+        }
+        return Buffer.from('');
+    });
+    return { setUrl, add };
+}
+const CANONICAL = 'https://runwork.ai/api/git/ws/app';
+describe('git/remote', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('normalizeRemoteUrl()', () => {
+        it('strips a trailing .git', () => {
+            expect(normalizeRemoteUrl('https://runwork.ai/api/git/ws/app.git')).toBe(CANONICAL);
+        });
+        it('strips trailing slashes and lower-cases the host (path preserved)', () => {
+            expect(normalizeRemoteUrl('https://RunWork.ai/api/git/ws/app/')).toBe(CANONICAL);
+        });
+        it('drops userinfo so embedded creds do not break equality', () => {
+            expect(normalizeRemoteUrl('https://x-access-token:KEY@runwork.ai/api/git/ws/app')).toBe(CANONICAL);
+        });
+        it('falls back to a lower-cased trim for scp-style remotes', () => {
+            expect(normalizeRemoteUrl('git@GitHub.com:Foo/Bar.git')).toBe('git@github.com:foo/bar');
+        });
+    });
+    describe('listRemotes()', () => {
+        it('parses name -> fetch URL, ignoring push duplicates', () => {
+            withRemotes({ origin: 'https://example.com/a', runwork: CANONICAL });
+            expect(listRemotes('/repo')).toEqual({
+                origin: 'https://example.com/a',
+                runwork: CANONICAL,
+            });
+        });
+        it('returns {} when git fails (not a repo)', () => {
+            mockExecFileSync.mockImplementation(() => { throw new Error('not a git repo'); });
+            expect(listRemotes('/repo')).toEqual({});
+        });
+    });
+    describe('ensureRunworkRemote()', () => {
+        it('is a no-op when runwork already points at the canonical URL', () => {
+            const { setUrl, add } = withRemotes({ runwork: CANONICAL });
+            expect(ensureRunworkRemote('/repo', CANONICAL)).toEqual({ action: 'noop' });
+            expect(setUrl).toHaveLength(0);
+            expect(add).toHaveLength(0);
+        });
+        it('treats a .git-suffixed existing runwork remote as a match (no rewrite)', () => {
+            const { setUrl, add } = withRemotes({ runwork: `${CANONICAL}.git` });
+            expect(ensureRunworkRemote('/repo', CANONICAL)).toEqual({ action: 'noop' });
+            expect(setUrl).toHaveLength(0);
+            expect(add).toHaveLength(0);
+        });
+        it('repoints an existing runwork remote that points elsewhere', () => {
+            const { setUrl, add } = withRemotes({ runwork: 'https://runwork.ai/api/git/OLD/app' });
+            expect(ensureRunworkRemote('/repo', CANONICAL)).toEqual({ action: 'updated' });
+            expect(setUrl).toHaveLength(1);
+            expect(setUrl[0]).toEqual(['remote', 'set-url', 'runwork', CANONICAL]);
+            expect(add).toHaveLength(0);
+        });
+        it('adds the runwork remote when missing (clean repo)', () => {
+            const { setUrl, add } = withRemotes({});
+            expect(ensureRunworkRemote('/repo', CANONICAL)).toEqual({ action: 'added' });
+            expect(add).toHaveLength(1);
+            expect(add[0]).toEqual(['remote', 'add', 'runwork', CANONICAL]);
+            expect(setUrl).toHaveLength(0);
+        });
+        it('recognizes a matching origin (manual git clone) via reusedFrom and still adds the runwork alias', () => {
+            const { setUrl, add } = withRemotes({ origin: CANONICAL });
+            expect(ensureRunworkRemote('/repo', CANONICAL)).toEqual({ action: 'added', reusedFrom: 'origin' });
+            expect(add).toHaveLength(1);
+            expect(add[0]).toEqual(['remote', 'add', 'runwork', CANONICAL]);
+            expect(setUrl).toHaveLength(0);
+        });
+        it('does not set reusedFrom when no existing remote matches', () => {
+            withRemotes({ origin: 'https://github.com/someone/fork' });
+            const result = ensureRunworkRemote('/repo', CANONICAL);
+            expect(result).toEqual({ action: 'added' });
+        });
+    });
+});

package/dist/git/__tests__/repo-config.test.d.ts

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

package/dist/git/__tests__/repo-config.test.js

@@ -0,0 +1,26 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('child_process');
+const mockExecFileSync = (await import('child_process')).execFileSync;
+const { hardenRepoForRestrictedFs } = await import('../repo-config.js');
+describe('git/repo-config hardenRepoForRestrictedFs', () => {
+    beforeEach(() => vi.clearAllMocks());
+    it('disables gc.auto and maintenance.auto in the repo (local scope)', () => {
+        mockExecFileSync.mockReturnValue(Buffer.from(''));
+        hardenRepoForRestrictedFs('/repo');
+        const configCalls = mockExecFileSync.mock.calls
+            .filter((c) => c[0] === 'git' && c[1][0] === 'config')
+            .map((c) => c[1].slice(1));
+        expect(configCalls).toContainEqual(['gc.auto', '0']);
+        expect(configCalls).toContainEqual(['maintenance.auto', 'false']);
+        // Repo scope, not --global.
+        expect(configCalls.every((args) => !args.includes('--global'))).toBe(true);
+        // Run against the given cwd.
+        for (const call of mockExecFileSync.mock.calls) {
+            expect(call[2].cwd).toBe('/repo');
+        }
+    });
+    it('never throws when git config fails (best-effort)', () => {
+        mockExecFileSync.mockImplementation(() => { throw new Error('git unavailable'); });
+        expect(() => hardenRepoForRestrictedFs('/repo')).not.toThrow();
+    });
+});

package/dist/git/classify-sync-error.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Classify a git sync failure from the raw stderr that `syncWithRemote`
+ * captures, so `runwork dev`/`deploy` can show an accurate cause and fix
+ * instead of the old catch-all "the sandbox session expired or the network
+ * connection was interrupted" (which pointed users away from the real
+ * problem, e.g. a missing `runwork` remote -- see friction log #3).
+ */
+export type SyncErrorReason = 'no-remote' | 'auth' | 'network' | 'conflict' | 'unknown';
+export interface SyncErrorDiagnosis {
+    reason: SyncErrorReason;
+    /** One-line summary suitable for an `error.message` field. */
+    message: string;
+    /** Plain explanation of the likely cause. */
+    diagnosis: string;
+    /** Actionable next steps, most-likely-fix first. */
+    suggestions: string[];
+}
+/** Map raw git stderr (or the stash-conflict sentinel) to a coarse reason. */
+export declare function classifySyncError(raw: string | undefined): SyncErrorReason;
+/** Build a full, user-facing diagnosis from the raw git stderr. */
+export declare function diagnoseSyncError(raw: string | undefined): SyncErrorDiagnosis;

package/dist/git/classify-sync-error.js

@@ -0,0 +1,111 @@
+/**
+ * The sentinel `syncWithRemote` returns when a stash pop conflicts after an
+ * otherwise-successful fetch/rebase. Routed through the classifier so the
+ * diagnosis stays in one place.
+ */
+const STASH_CONFLICT = 'stash-conflict';
+/** Map raw git stderr (or the stash-conflict sentinel) to a coarse reason. */
+export function classifySyncError(raw) {
+    if (!raw)
+        return 'unknown';
+    const s = raw.toLowerCase();
+    if (raw === STASH_CONFLICT)
+        return 'conflict';
+    // Missing/!misnamed remote. A plain `git clone` names the remote `origin`,
+    // so `git fetch runwork` fails with this before auth ever matters.
+    if (s.includes('does not appear to be a git repository') ||
+        s.includes("'runwork' does not appear") ||
+        s.includes('no such remote') ||
+        (s.includes('remote') && s.includes('not found'))) {
+        return 'no-remote';
+    }
+    // Authentication / authorization.
+    if (s.includes('authentication failed') ||
+        s.includes('could not read username') ||
+        s.includes('could not read password') ||
+        s.includes('terminal prompts disabled') ||
+        s.includes('permission denied') ||
+        s.includes('error: 403') ||
+        s.includes('error: 401') ||
+        s.includes('http basic: access denied') ||
+        s.includes('invalid username or password')) {
+        return 'auth';
+    }
+    // Network / connectivity.
+    if (s.includes('could not resolve host') ||
+        s.includes('failed to connect') ||
+        s.includes("couldn't connect to server") ||
+        s.includes('connection timed out') ||
+        s.includes('operation timed out') ||
+        s.includes('network is unreachable') ||
+        s.includes('temporary failure in name resolution')) {
+        return 'network';
+    }
+    // Merge/rebase conflicts.
+    if (s.includes('conflict') ||
+        s.includes('needs merge') ||
+        s.includes('automatic merge failed') ||
+        s.includes('patch failed')) {
+        return 'conflict';
+    }
+    return 'unknown';
+}
+/** Build a full, user-facing diagnosis from the raw git stderr. */
+export function diagnoseSyncError(raw) {
+    const reason = classifySyncError(raw);
+    switch (reason) {
+        case 'no-remote':
+            return {
+                reason,
+                message: "git remote 'runwork' is missing or misconfigured",
+                diagnosis: "The sync targets a remote named 'runwork', but it doesn't exist in this repository (a plain `git clone` names the remote 'origin').",
+                suggestions: [
+                    'Run `runwork doctor --fix` to add/repair the runwork remote',
+                    'Or add it manually: `git remote add runwork <app git URL>`',
+                ],
+            };
+        case 'auth':
+            return {
+                reason,
+                message: 'git could not authenticate to the runwork remote',
+                diagnosis: 'The runwork git credential helper is not registered (or the stored credentials were rejected), so git could not authenticate.',
+                suggestions: [
+                    'Run `runwork doctor --fix` to register the git credential helper',
+                    'If it persists, re-authenticate with `runwork login`',
+                ],
+            };
+        case 'network':
+            return {
+                reason,
+                message: 'network error while syncing with the runwork remote',
+                diagnosis: 'git could not reach the runwork host. This is usually a connectivity or DNS issue.',
+                suggestions: [
+                    'Check your network connection',
+                    'Confirm outbound access to runwork.ai, then run `runwork dev` again',
+                ],
+            };
+        case 'conflict':
+            return {
+                reason,
+                message: raw === STASH_CONFLICT
+                    ? 'merge conflicts after restoring local changes'
+                    : 'merge conflicts while syncing with the remote',
+                diagnosis: 'Local changes could not be automatically merged with the remote state; the conflict needs manual resolution.',
+                suggestions: [
+                    'Resolve the conflicts in the affected files (`git status` lists them)',
+                    'Run `git add` on resolved files, then `git commit`',
+                    'Run `runwork dev` again after resolving',
+                ],
+            };
+        default:
+            return {
+                reason,
+                message: raw || 'file sync failed',
+                diagnosis: 'Could not sync files to the sandbox.',
+                suggestions: [
+                    'Run `runwork doctor` to diagnose environment issues',
+                    'Run `runwork dev` again to start a fresh session',
+                ],
+            };
+    }
+}

package/dist/git/credentials.d.ts

@@ -20,6 +20,49 @@ export declare function buildHelperValue(execPath: string): string;
  * Called by `runwork login` and `runwork init`.
  */
 export declare function configureGitCredentials(remoteUrl: string): Promise<void>;
+/**
+ * Result of looking up the git credential helper registered for a given
+ * origin in the user's global git config. Shared by `runwork doctor`
+ * (reporting) and the lazy-ensure path (clone/dev/deploy) so the detection
+ * logic never drifts between the two.
+ */
+export type CredentialHelperLookup = {
+    status: 'none';
+} | {
+    status: 'unscoped';
+    otherCount: number;
+} | {
+    status: 'registered';
+    value: string;
+};
+/**
+ * Read the git credential helper (if any) registered for `origin` in the
+ * global git config. Mirrors the scoped lookup `runwork doctor` performs: an
+ * entry only counts when its scope matches the user's baseUrl origin, so a
+ * stale staging origin from a previous login doesn't mask a missing entry.
+ */
+export declare function lookupCredentialHelper(origin: string): CredentialHelperLookup;
+/**
+ * Inspect the binary a credential-helper value points at. Only absolute-path
+ * helper values (`!"/abs/path" git-credential-helper`) can be validated on
+ * disk; PATH-relative entries are trusted to resolve at git-invocation time
+ * (reported `ok` with a null path). Shared so the doctor check and the
+ * lazy-ensure path agree on what "stale" means.
+ */
+export declare function helperBinaryStatus(value: string): {
+    ok: boolean;
+    path: string | null;
+};
+/**
+ * Idempotently make sure the runwork git credential helper is registered for
+ * the given baseUrl's origin -- registering it when absent, or repairing it
+ * when it points at a binary that no longer exists (e.g. after the CLI moved
+ * on upgrade). This is the bridge that lets headless auth paths -- the
+ * `get_cli_setup` MCP tool or a hand-written `~/.runwork/.credentials` --
+ * work with git without a separate `runwork login`. Safe (and cheap) to call
+ * before every git operation in clone/dev/deploy.
+ */
+export declare function ensureGitCredentialHelper(baseUrl: string): Promise<void>;
 /**
  * Remove the git credential helper configuration for our remote.
  */

package/dist/git/credentials.js

@@ -1,3 +1,4 @@
+import { existsSync } from 'fs';
 import { execFileSync } from '../utils/subprocess.js';
 import { getCredentials } from '../auth/store.js';
 /**
@@ -44,6 +45,72 @@ export async function configureGitCredentials(remoteUrl) {
         throw err;
     }
 }
+/**
+ * Read the git credential helper (if any) registered for `origin` in the
+ * global git config. Mirrors the scoped lookup `runwork doctor` performs: an
+ * entry only counts when its scope matches the user's baseUrl origin, so a
+ * stale staging origin from a previous login doesn't mask a missing entry.
+ */
+export function lookupCredentialHelper(origin) {
+    // `--get-regexp` exits 1 (printing nothing) when no entry matches, which
+    // surfaces here as a thrown error -- a normal "not registered" signal.
+    let helperConfig;
+    try {
+        const buf = execFileSync('git', ['config', '--global', '--get-regexp', 'credential\\..*runwork.*\\.helper'], { stdio: ['ignore', 'pipe', 'ignore'] });
+        helperConfig = buf.toString();
+    }
+    catch {
+        return { status: 'none' };
+    }
+    const lines = helperConfig.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+    const escapedOrigin = origin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const scopedRegex = new RegExp(`^credential\\.${escapedOrigin}\\.helper\\s+(.+)$`);
+    const matchedLine = lines.find(line => scopedRegex.test(line));
+    if (!matchedLine) {
+        return { status: 'unscoped', otherCount: lines.length };
+    }
+    return { status: 'registered', value: scopedRegex.exec(matchedLine)?.[1] ?? '' };
+}
+/**
+ * Inspect the binary a credential-helper value points at. Only absolute-path
+ * helper values (`!"/abs/path" git-credential-helper`) can be validated on
+ * disk; PATH-relative entries are trusted to resolve at git-invocation time
+ * (reported `ok` with a null path). Shared so the doctor check and the
+ * lazy-ensure path agree on what "stale" means.
+ */
+export function helperBinaryStatus(value) {
+    const absoluteHelperRegex = /^!"?(\/|[A-Za-z]:[\\/])/;
+    if (!absoluteHelperRegex.test(value))
+        return { ok: true, path: null };
+    const pathMatch = value.match(/^!"([^"]+)"|^!(\S+)/);
+    const helperPath = pathMatch?.[1] ?? pathMatch?.[2] ?? '';
+    if (!helperPath)
+        return { ok: true, path: null };
+    return { ok: existsSync(helperPath), path: helperPath };
+}
+/**
+ * Idempotently make sure the runwork git credential helper is registered for
+ * the given baseUrl's origin -- registering it when absent, or repairing it
+ * when it points at a binary that no longer exists (e.g. after the CLI moved
+ * on upgrade). This is the bridge that lets headless auth paths -- the
+ * `get_cli_setup` MCP tool or a hand-written `~/.runwork/.credentials` --
+ * work with git without a separate `runwork login`. Safe (and cheap) to call
+ * before every git operation in clone/dev/deploy.
+ */
+export async function ensureGitCredentialHelper(baseUrl) {
+    let origin;
+    try {
+        origin = new URL(baseUrl).origin;
+    }
+    catch {
+        return; // Unparseable baseUrl -- nothing actionable.
+    }
+    const lookup = lookupCredentialHelper(origin);
+    if (lookup.status === 'registered' && helperBinaryStatus(lookup.value).ok) {
+        return; // Already registered and valid -- no-op.
+    }
+    await configureGitCredentials(baseUrl);
+}
 /**
  * Remove the git credential helper configuration for our remote.
  */

package/dist/git/remote.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The git remote name runwork uses for all sync/push operations. The sync
+ * loop (git/sync.ts) references this remote by name, so clone/dev/deploy must
+ * guarantee it exists and points at the app's canonical URL before syncing.
+ */
+export declare const RUNWORK_REMOTE = "runwork";
+export type EnsureRemoteResult = {
+    action: 'noop';
+} | {
+    action: 'updated';
+} | {
+    action: 'added';
+    reusedFrom?: string;
+};
+/**
+ * Normalize a git remote URL for equality comparison. Strips a trailing
+ * `.git`, trailing slashes, and userinfo; lower-cases the host (case-
+ * insensitive) while preserving the path (case-sensitive). Falls back to a
+ * lower-cased trim for scp-style / non-URL remotes.
+ */
+export declare function normalizeRemoteUrl(raw: string): string;
+/** Map of remote name -> fetch URL, parsed from `git remote -v`. */
+export declare function listRemotes(cwd: string): Record<string, string>;
+/**
+ * Ensure a `runwork` remote exists and points at the app's canonical git URL,
+ * so the sync loop's `runwork`-named git calls succeed regardless of how the
+ * repo was obtained. A plain `git clone <url>` names the remote `origin`,
+ * which previously made `runwork dev`/`deploy` fail with
+ * `fatal: 'runwork' does not appear to be a git repository`.
+ *
+ * We don't require the remote to literally be named `runwork`: if another
+ * remote (e.g. `origin`) already points at the canonical URL, we recognize it
+ * (reported via `reusedFrom`) and still register the `runwork` alias so the
+ * hardcoded sync path keeps working. Idempotent: a no-op when `runwork`
+ * already points at the canonical URL.
+ */
+export declare function ensureRunworkRemote(cwd: string, canonicalUrl: string): EnsureRemoteResult;