runwork 0.9.4 → 0.10.0

package/dist/commands/init.js

@@ -5,6 +5,9 @@ import { join, resolve } from 'path';
 import { homedir } from 'os';
 import { requireAuth } from '../auth/store.js';
 import { ApiClient } from '../api/client.js';
+import { ensureGitIdentity } from '../git/identity.js';
+import { requireGit } from '../git/preflight.js';
+import { formatError } from '../utils/format-error.js';
 import { promptSelect, promptInput } from '../utils/prompt.js';
 import { resolveWorkspace } from '../utils/resolve.js';
 import { generateManifest, saveManifest } from '../template/manifest.js';
@@ -15,7 +18,7 @@ import { shouldOutputJson, jsonOut } from '../utils/output.js';
 import { buildInitGuide, buildErrorResponse } from '../utils/agent-guidance.js';
 /** Default parent directory for new apps when --here is not passed. */
 export const DEFAULT_APPS_DIR = join(homedir(), '.runwork', 'apps');
-export async function execInit(client, appName, workspace, options = {}) {
+export async function execInit(client, appName, workspace, options = {}, creds) {
     const app = await client.initApp(workspace.id, appName);
     const slug = app.slug || appName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
     const parentDir = options.here ? process.cwd() : DEFAULT_APPS_DIR;
@@ -54,10 +57,29 @@ export async function execInit(client, appName, workspace, options = {}) {
         appName: app.name,
     };
     writeFileSync(join(dir, '.runwork.json'), JSON.stringify(config, null, 2));
-    // Initialize git
+    // Initialize git. `stdio: 'pipe'` swallows git's stderr, so we have to
+    // print any failure ourselves -- otherwise this fails silently and the
+    // user is left with an empty directory and no clue what happened.
     if (!existsSync(join(dir, '.git'))) {
-        execFileSync('git', ['init'], { cwd: dir, stdio: 'pipe' });
+        try {
+            execFileSync('git', ['init'], { cwd: dir, stdio: 'pipe' });
+        }
+        catch (err) {
+            console.error(`git init failed in ${dir}: ${formatError(err)}`);
+            throw err;
+        }
+        // Force the initial branch to `main` regardless of the user's
+        // `init.defaultBranch` config (older Git installs default to
+        // `master`). symbolic-ref works before any commits exist; `git
+        // branch -M main` would not.
+        try {
+            execFileSync('git', ['symbolic-ref', 'HEAD', 'refs/heads/main'], { cwd: dir, stdio: 'pipe' });
+        }
+        catch { /* best-effort: push uses HEAD:main so this is just cleanliness */ }
     }
+    // Seed a local git identity so the initial commit cannot fail on machines
+    // (commonly fresh Windows installs) without `git config --global user.email`.
+    ensureGitIdentity(dir, creds);
     // Add runwork remote
     const remoteUrl = client.getGitRemoteUrl(workspace.id, app.id);
     try {
@@ -78,7 +100,13 @@ export async function execInit(client, appName, workspace, options = {}) {
     catch {
         // Nothing to commit is fine
     }
-    execFileSync('git', ['push', '-u', 'runwork', 'main'], { cwd: dir, stdio: 'pipe' });
+    try {
+        execFileSync('git', ['push', '-u', 'runwork', 'main'], { cwd: dir, stdio: 'pipe' });
+    }
+    catch (err) {
+        console.error(`git push to runwork remote failed: ${formatError(err)}`);
+        throw err;
+    }
     console.log(`\nApp "${app.name}" initialized in ${dir}`);
     return {
         appId: app.id,
@@ -92,6 +120,7 @@ export async function execInit(client, appName, workspace, options = {}) {
 /** Full create flow: prompt for name/workspace, init, and run agent wizard */
 export async function runCreateFlow(name, workspaceFlag, options = {}) {
     const useJson = shouldOutputJson(undefined);
+    requireGit('init');
     const creds = requireAuth();
     const client = new ApiClient(creds);
     const appName = name || await promptInput('App name');
@@ -132,7 +161,7 @@ export async function runCreateFlow(name, workspaceFlag, options = {}) {
     if (!useJson) {
         console.log(`Creating "${appName}" in workspace "${workspace.name}"...`);
     }
-    const initResult = await execInit(client, appName, workspace, options);
+    const initResult = await execInit(client, appName, workspace, options, creds);
     if (useJson) {
         const response = {
             success: true,

package/dist/commands/upgrade.js

@@ -4,13 +4,14 @@ import { platform as osPlatform, tmpdir } from 'os';
 import { mkdtempSync, writeFileSync, rmSync } from 'fs';
 import { join } from 'path';
 import { VERSION } from '../generated/version.js';
+import { httpFetch } from '../utils/http.js';
 const BASE_URL = 'https://runwork.ai';
 const LATEST_JSON_URL = `${BASE_URL}/cli/latest.json`;
 const INSTALL_SH_URL = `${BASE_URL}/install.sh`;
 const INSTALL_PS1_URL = `${BASE_URL}/install.ps1`;
 async function fetchLatestVersion() {
     try {
-        const response = await fetch(LATEST_JSON_URL, { cache: 'no-store' });
+        const response = await httpFetch(LATEST_JSON_URL, { cache: 'no-store' });
         if (!response.ok)
             return null;
         const data = await response.json();
@@ -57,7 +58,7 @@ async function upgradeBinary() {
     const isWindows = osPlatform() === 'win32';
     if (isWindows) {
         console.log('\nUpgrading via PowerShell installer...\n');
-        const response = await fetch(INSTALL_PS1_URL, { cache: 'no-store' });
+        const response = await httpFetch(INSTALL_PS1_URL, { cache: 'no-store' });
         if (!response.ok) {
             throw new Error(`Failed to download install.ps1: HTTP ${response.status}`);
         }
@@ -83,7 +84,7 @@ async function upgradeBinary() {
         return;
     }
     console.log('\nUpgrading via install.sh...\n');
-    const response = await fetch(INSTALL_SH_URL, { cache: 'no-store' });
+    const response = await httpFetch(INSTALL_SH_URL, { cache: 'no-store' });
     if (!response.ok) {
         throw new Error(`Failed to download install.sh: HTTP ${response.status}`);
     }

package/dist/commands/welcome.js

@@ -51,7 +51,7 @@ export async function runWelcomeWizard() {
         console.log('');
         console.log(`Creating ${cyan(appName)} in workspace ${cyan(workspace.name)}...`);
         const { execInit } = await import('./init.js');
-        const initResult = await execInit(client, appName, workspace);
+        const initResult = await execInit(client, appName, workspace, {}, creds);
         appDir = initResult.directory;
     }
     else {
@@ -62,7 +62,7 @@ export async function runWelcomeWizard() {
         }
         const choice = await promptSelect('Select app to clone:', apps.map(a => ({ label: `${a.name} (${a.workspaceName})`, value: a })));
         const { execClone } = await import('./clone.js');
-        const cloneResult = await execClone(client, choice.value);
+        const cloneResult = await execClone(client, choice.value, undefined, creds);
         appDir = cloneResult.directory;
     }
     // Step 4: Agent guidance

package/dist/devtools/registry-data.d.ts

@@ -25,6 +25,13 @@ export type DevToolInstallStrategy = {
 export interface DevToolDefinition extends InstallableTool {
     /** Beginner-friendly explanation shown in the install card. */
     longDescription: string;
+    /**
+     * When true, the desktop must block onboarding "Continue" until this tool
+     * is detected (or explicitly skipped only after an attempted install).
+     * Use sparingly: this is reserved for tools whose absence guarantees the
+     * core CLI loop (init / clone / dev / deploy) will fail.
+     */
+    required?: boolean;
     /**
      * Per-platform install strategy. Missing platforms fall back to opening
      * `downloadUrl` in the browser.

package/dist/devtools/registry-data.js

@@ -13,6 +13,7 @@ const DEV_TOOL_REGISTRY = [
         name: 'Git',
         description: 'Version control system',
         longDescription: 'Git tracks changes to your code and is required for Runwork commands that sync your work with the platform (init, clone, dev, deploy).',
+        required: true,
         detection: { method: 'binary', target: 'git' },
         downloadUrl: 'https://git-scm.com/downloads',
         install: {

package/dist/generated/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.9.4";
+export declare const VERSION = "0.10.0";

package/dist/generated/version.js

@@ -1,2 +1,2 @@
 // Auto-generated by scripts/embed-types.ts -- do not edit
-export const VERSION = "0.9.4";
+export const VERSION = "0.10.0";

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

@@ -18,7 +18,7 @@ describe('git/credentials', () => {
                 '--global',
                 'credential.https://runwork.ai.helper',
                 '!runwork git-credential-helper',
-            ]);
+            ], { stdio: 'pipe' });
         });
         it('extracts origin from full URL', async () => {
             await configureGitCredentials('https://custom.runwork.dev/api/git/ws-1/app-1');
@@ -27,7 +27,7 @@ describe('git/credentials', () => {
                 '--global',
                 'credential.https://custom.runwork.dev.helper',
                 '!runwork git-credential-helper',
-            ]);
+            ], { stdio: 'pipe' });
         });
         it('handles URL with port', async () => {
             await configureGitCredentials('https://localhost:8787/api/git/ws/app');
@@ -36,7 +36,7 @@ describe('git/credentials', () => {
                 '--global',
                 'credential.https://localhost:8787.helper',
                 '!runwork git-credential-helper',
-            ]);
+            ], { stdio: 'pipe' });
         });
     });
     describe('removeGitCredentials()', () => {
@@ -47,7 +47,7 @@ describe('git/credentials', () => {
                 '--global',
                 '--unset',
                 'credential.https://runwork.ai.helper',
-            ]);
+            ], { stdio: 'pipe' });
         });
         it('ignores errors silently', async () => {
             mockExecFileSync.mockImplementation(() => {

package/dist/git/__tests__/identity.test.d.ts

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

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

@@ -0,0 +1,146 @@
+import { describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest';
+import { execFileSync } from 'child_process';
+import { mkdtempSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { ensureGitIdentity, __testing } from '../identity.js';
+const tempDirs = [];
+// Isolate every git invocation in this file from the developer's real
+// `~/.gitconfig` (and any system-level config). Without this, anyone running
+// the suite locally with `git config --global user.email` already set would
+// see the helper short-circuit (correctly) and the "fresh machine" assertions
+// would never exercise the write path. We point GIT_CONFIG_GLOBAL/SYSTEM at
+// paths that don't exist; git treats missing config files as empty.
+const ISOLATION_DIR = mkdtempSync(join(tmpdir(), 'runwork-identity-isolation-'));
+const NON_EXISTENT = join(ISOLATION_DIR, 'no-such-config');
+const PREVIOUS_ENV = {};
+beforeAll(() => {
+    for (const key of ['GIT_CONFIG_GLOBAL', 'GIT_CONFIG_SYSTEM', 'HOME', 'XDG_CONFIG_HOME']) {
+        PREVIOUS_ENV[key] = process.env[key];
+    }
+    process.env.GIT_CONFIG_GLOBAL = NON_EXISTENT;
+    process.env.GIT_CONFIG_SYSTEM = NON_EXISTENT;
+    // Some git builds still consult $HOME/.gitconfig even with GIT_CONFIG_GLOBAL
+    // set. Pointing HOME at the empty isolation directory closes that hole.
+    process.env.HOME = ISOLATION_DIR;
+    process.env.XDG_CONFIG_HOME = ISOLATION_DIR;
+});
+afterAll(() => {
+    for (const [key, value] of Object.entries(PREVIOUS_ENV)) {
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+    try {
+        rmSync(ISOLATION_DIR, { recursive: true, force: true });
+    }
+    catch { /* best-effort */ }
+});
+function makeRepo() {
+    const dir = mkdtempSync(join(tmpdir(), 'runwork-identity-test-'));
+    tempDirs.push(dir);
+    execFileSync('git', ['init', dir]);
+    return dir;
+}
+function readConfig(cwd, key) {
+    try {
+        return execFileSync('git', ['config', '--local', '--get', key], { cwd }).toString('utf-8').trim();
+    }
+    catch {
+        return '';
+    }
+}
+afterEach(() => {
+    for (const dir of tempDirs) {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+    }
+    tempDirs.length = 0;
+});
+describe('deriveNameFromEmail', () => {
+    it('uppercases the local part', () => {
+        expect(__testing.deriveNameFromEmail('oytun@motaword.com')).toBe('Oytun');
+    });
+    it('splits separators into words', () => {
+        expect(__testing.deriveNameFromEmail('anna.maria@example.com')).toBe('Anna Maria');
+        expect(__testing.deriveNameFromEmail('jean-luc@example.com')).toBe('Jean Luc');
+        expect(__testing.deriveNameFromEmail('user_name@example.com')).toBe('User Name');
+    });
+    it('falls back to default when local part is empty', () => {
+        expect(__testing.deriveNameFromEmail('@example.com')).toBe(__testing.FALLBACK_NAME);
+    });
+});
+describe('pickIdentity', () => {
+    it('uses the credentials email when it looks like an email', () => {
+        expect(__testing.pickIdentity({ apiKey: 'k', email: 'oytun@motaword.com', baseUrl: '' }))
+            .toEqual({ email: 'oytun@motaword.com', name: 'Oytun' });
+    });
+    it('falls back when email is the api-key-auth placeholder', () => {
+        expect(__testing.pickIdentity({ apiKey: 'k', email: 'api-key-auth', baseUrl: '' }))
+            .toEqual({ email: __testing.FALLBACK_EMAIL, name: __testing.FALLBACK_NAME });
+    });
+    it('falls back when no credentials are passed', () => {
+        expect(__testing.pickIdentity(null))
+            .toEqual({ email: __testing.FALLBACK_EMAIL, name: __testing.FALLBACK_NAME });
+    });
+});
+describe('ensureGitIdentity', () => {
+    it('writes local user.email and user.name when none are configured', () => {
+        const dir = makeRepo();
+        expect(readConfig(dir, 'user.email')).toBe('');
+        expect(readConfig(dir, 'user.name')).toBe('');
+        ensureGitIdentity(dir, { apiKey: 'k', email: 'oytun@motaword.com', baseUrl: '' });
+        expect(readConfig(dir, 'user.email')).toBe('oytun@motaword.com');
+        expect(readConfig(dir, 'user.name')).toBe('Oytun');
+    });
+    it('overwrites local config with Runwork credentials when they are usable', () => {
+        // Commits to a Runwork remote should always be attributed to the
+        // authenticated Runwork user, even if the developer set a local identity
+        // earlier (e.g. a stale value from a previous account).
+        const dir = makeRepo();
+        execFileSync('git', ['config', '--local', 'user.email', 'preset@example.com'], { cwd: dir });
+        execFileSync('git', ['config', '--local', 'user.name', 'Preset User'], { cwd: dir });
+        ensureGitIdentity(dir, { apiKey: 'k', email: 'oytun@motaword.com', baseUrl: '' });
+        expect(readConfig(dir, 'user.email')).toBe('oytun@motaword.com');
+        expect(readConfig(dir, 'user.name')).toBe('Oytun');
+    });
+    it('respects existing local config when no Runwork credentials are available', () => {
+        // Without a real Runwork identity to attribute the commit to, leave any
+        // pre-existing local identity (or anything inherited from --global) alone.
+        const dir = makeRepo();
+        execFileSync('git', ['config', '--local', 'user.email', 'preset@example.com'], { cwd: dir });
+        execFileSync('git', ['config', '--local', 'user.name', 'Preset User'], { cwd: dir });
+        ensureGitIdentity(dir, null);
+        expect(readConfig(dir, 'user.email')).toBe('preset@example.com');
+        expect(readConfig(dir, 'user.name')).toBe('Preset User');
+    });
+    it('respects existing local config when credentials carry only a placeholder email', () => {
+        const dir = makeRepo();
+        execFileSync('git', ['config', '--local', 'user.email', 'preset@example.com'], { cwd: dir });
+        execFileSync('git', ['config', '--local', 'user.name', 'Preset User'], { cwd: dir });
+        ensureGitIdentity(dir, { apiKey: 'k', email: 'api-key-auth', baseUrl: '' });
+        expect(readConfig(dir, 'user.email')).toBe('preset@example.com');
+        expect(readConfig(dir, 'user.name')).toBe('Preset User');
+    });
+    it('falls back to a synthetic identity when credentials are missing', () => {
+        const dir = makeRepo();
+        ensureGitIdentity(dir, null);
+        expect(readConfig(dir, 'user.email')).toBe(__testing.FALLBACK_EMAIL);
+        expect(readConfig(dir, 'user.name')).toBe(__testing.FALLBACK_NAME);
+    });
+    it('lets a real commit succeed on a fresh repo (windows-style "no identity" path)', () => {
+        const dir = makeRepo();
+        ensureGitIdentity(dir, { apiKey: 'k', email: 'oytun@motaword.com', baseUrl: '' });
+        execFileSync('git', ['commit', '--allow-empty', '-m', 'identity probe'], { cwd: dir, stdio: 'pipe' });
+        const log = execFileSync('git', ['log', '--pretty=%an <%ae>'], { cwd: dir }).toString('utf-8').trim();
+        expect(log).toContain('Oytun <oytun@motaword.com>');
+    });
+    it('is a no-op for non-git directories', () => {
+        const dir = mkdtempSync(join(tmpdir(), 'runwork-identity-non-git-'));
+        tempDirs.push(dir);
+        expect(() => ensureGitIdentity(dir, null)).not.toThrow();
+    });
+});

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

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

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

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import { probeGit, buildMissingGitMessage } from '../preflight.js';
+describe('probeGit', () => {
+    it('reports installed=true when git is on PATH (CI invariant)', () => {
+        // The CLI test suite already shells out to git in many other tests, so
+        // we treat git as a hard prerequisite for this package's own tests.
+        const probe = probeGit();
+        expect(probe.installed).toBe(true);
+        expect(probe.version).toMatch(/^git version /);
+    });
+});
+describe('buildMissingGitMessage', () => {
+    it('mentions the failing command name', () => {
+        const msg = buildMissingGitMessage('clone');
+        expect(msg).toContain('runwork clone');
+    });
+    it('lists install hints for all three OSes', () => {
+        const msg = buildMissingGitMessage('dev');
+        expect(msg).toMatch(/macOS/);
+        expect(msg).toMatch(/Windows/);
+        expect(msg).toMatch(/Linux/);
+    });
+    it('ends with a verification command', () => {
+        const msg = buildMissingGitMessage('init');
+        expect(msg).toContain('git --version');
+    });
+    it('only includes the Windows-shell-PATH hint when running on Windows', () => {
+        const msg = buildMissingGitMessage('clone');
+        if (process.platform === 'win32') {
+            expect(msg).toMatch(/cached when it opened/);
+        }
+        else {
+            expect(msg).not.toMatch(/cached when it opened/);
+        }
+    });
+});

package/dist/git/auto-commit.js

@@ -188,12 +188,18 @@ function commitAndPush() {
                 return;
             }
         }
+        // Push the current HEAD to the remote's `main` branch regardless of
+        // what the local branch is named. This way `git init` defaults of
+        // `master` (older Git) or any other custom branch name still sync
+        // cleanly to runwork's `main`. Without `HEAD:main`, `git push runwork
+        // main` fails with "src refspec main does not match any" when the
+        // local branch isn't called `main`.
         try {
             execFileSync('git', ['rev-parse', '--abbrev-ref', '@{u}'], { stdio: 'pipe' });
-            execFileSync('git', ['push', 'runwork', 'main'], { stdio: 'pipe' });
+            execFileSync('git', ['push', 'runwork', 'HEAD:main'], { stdio: 'pipe' });
         }
         catch {
-            execFileSync('git', ['push', '-u', 'runwork', 'main'], { stdio: 'pipe' });
+            execFileSync('git', ['push', '-u', 'runwork', 'HEAD:main'], { stdio: 'pipe' });
         }
         console.log(dim(`  Pushed ${stagedFiles.length} file(s) to git.`));
         activeCallbacks?.onGitPush?.(stagedFiles.length);

package/dist/git/credentials.js

@@ -32,7 +32,7 @@ export async function removeGitCredentials(baseUrl) {
         execFileSync('git', [
             'config', '--global', '--unset',
             `credential.${origin}.helper`,
-        ]);
+        ], { stdio: 'pipe' });
     }
     catch {
         // Ignore errors if the config key doesn't exist

package/dist/git/identity.d.ts

@@ -0,0 +1,44 @@
+import type { Credentials } from '../types.js';
+/**
+ * Derive a human-friendly display name from an email address. Used when the
+ * credentials store only has the email (which is the common case). e.g.
+ * "oytun@motaword.com" -> "Oytun"; "anna.maria@example.com" -> "Anna Maria".
+ */
+declare function deriveNameFromEmail(email: string): string;
+declare function pickIdentity(creds?: Credentials | null): {
+    email: string;
+    name: string;
+};
+/**
+ * Ensure the repository at `cwd` has a usable git identity (user.email and
+ * user.name) and that, whenever possible, commits are attributed to the
+ * authenticated Runwork user.
+ *
+ * Precedence:
+ *   1. If we have usable Runwork credentials, always write local-scoped
+ *      `user.email` / `user.name` from those credentials. Commits to a
+ *      Runwork remote should be attributable to the logged-in Runwork user,
+ *      not to whatever generic identity the developer uses for unrelated
+ *      personal repos.
+ *   2. If credentials are missing or are an unusable placeholder
+ *      (e.g. API-key login), fall back to any existing global / system
+ *      configuration so the user's pre-existing identity still works.
+ *   3. If neither credentials nor any existing config are available, write a
+ *      synthetic local identity so the inevitable `git commit` does not fail
+ *      on a fresh Windows / minimal-container install with the classic
+ *      `unable to auto-detect email address` error.
+ *
+ * Local scope (`git config --local`) is mandatory: we never touch the user's
+ * global config so we cannot disturb identities they use elsewhere.
+ *
+ * Safe to call multiple times; it short-circuits when the desired identity
+ * is already in place.
+ */
+export declare function ensureGitIdentity(cwd: string, creds?: Credentials | null): void;
+export declare const __testing: {
+    deriveNameFromEmail: typeof deriveNameFromEmail;
+    pickIdentity: typeof pickIdentity;
+    FALLBACK_EMAIL: string;
+    FALLBACK_NAME: string;
+};
+export {};

package/dist/git/identity.js

@@ -0,0 +1,133 @@
+import { execFileSync } from 'child_process';
+/**
+ * Default identity used when we cannot derive anything better from the
+ * authenticated credentials. Local-scoped, never written to global config,
+ * so it does not leak into other repositories on the user's machine.
+ */
+const FALLBACK_EMAIL = 'runwork-cli@runwork.local';
+const FALLBACK_NAME = 'Runwork User';
+/**
+ * Derive a human-friendly display name from an email address. Used when the
+ * credentials store only has the email (which is the common case). e.g.
+ * "oytun@motaword.com" -> "Oytun"; "anna.maria@example.com" -> "Anna Maria".
+ */
+function deriveNameFromEmail(email) {
+    const local = email.split('@')[0] ?? '';
+    if (!local)
+        return FALLBACK_NAME;
+    const cleaned = local.replace(/[._+-]+/g, ' ').trim();
+    if (!cleaned)
+        return FALLBACK_NAME;
+    return cleaned
+        .split(/\s+/)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+}
+function isUsableEmail(value) {
+    if (!value)
+        return false;
+    // Reject the "api-key-auth" placeholder used by API-key login flows.
+    if (!value.includes('@'))
+        return false;
+    return true;
+}
+function pickIdentity(creds) {
+    const email = isUsableEmail(creds?.email) ? creds.email : FALLBACK_EMAIL;
+    const name = email === FALLBACK_EMAIL ? FALLBACK_NAME : deriveNameFromEmail(email);
+    return { email, name };
+}
+function readGitConfig(cwd, key) {
+    try {
+        const value = execFileSync('git', ['config', '--get', key], { cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+        return value.toString('utf-8').trim();
+    }
+    catch {
+        return '';
+    }
+}
+function readLocalGitConfig(cwd, key) {
+    try {
+        const value = execFileSync('git', ['config', '--local', '--get', key], { cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+        return value.toString('utf-8').trim();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Ensure the repository at `cwd` has a usable git identity (user.email and
+ * user.name) and that, whenever possible, commits are attributed to the
+ * authenticated Runwork user.
+ *
+ * Precedence:
+ *   1. If we have usable Runwork credentials, always write local-scoped
+ *      `user.email` / `user.name` from those credentials. Commits to a
+ *      Runwork remote should be attributable to the logged-in Runwork user,
+ *      not to whatever generic identity the developer uses for unrelated
+ *      personal repos.
+ *   2. If credentials are missing or are an unusable placeholder
+ *      (e.g. API-key login), fall back to any existing global / system
+ *      configuration so the user's pre-existing identity still works.
+ *   3. If neither credentials nor any existing config are available, write a
+ *      synthetic local identity so the inevitable `git commit` does not fail
+ *      on a fresh Windows / minimal-container install with the classic
+ *      `unable to auto-detect email address` error.
+ *
+ * Local scope (`git config --local`) is mandatory: we never touch the user's
+ * global config so we cannot disturb identities they use elsewhere.
+ *
+ * Safe to call multiple times; it short-circuits when the desired identity
+ * is already in place.
+ */
+export function ensureGitIdentity(cwd, creds) {
+    // Only act on actual git repos; refuse silently if `cwd` has no .git.
+    try {
+        execFileSync('git', ['rev-parse', '--git-dir'], { cwd, stdio: 'pipe' });
+    }
+    catch {
+        return;
+    }
+    const credsUsable = isUsableEmail(creds?.email);
+    // Path 1: real Runwork credentials -- always overwrite local config so the
+    // commit is attributed to the Runwork user, regardless of global state.
+    if (credsUsable) {
+        const { email, name } = pickIdentity(creds);
+        const existingLocalEmail = readLocalGitConfig(cwd, 'user.email');
+        const existingLocalName = readLocalGitConfig(cwd, 'user.name');
+        if (existingLocalEmail !== email) {
+            try {
+                execFileSync('git', ['config', '--local', 'user.email', email], { cwd, stdio: 'pipe' });
+            }
+            catch { /* read-only fs */ }
+        }
+        if (existingLocalName !== name) {
+            try {
+                execFileSync('git', ['config', '--local', 'user.name', name], { cwd, stdio: 'pipe' });
+            }
+            catch { /* read-only fs */ }
+        }
+        return;
+    }
+    // Path 2: no usable creds. Respect any pre-existing identity (global/local).
+    const existingEmail = readGitConfig(cwd, 'user.email');
+    const existingName = readGitConfig(cwd, 'user.name');
+    if (existingEmail && existingName)
+        return;
+    // Path 3: no creds AND no existing identity -- seed a synthetic fallback
+    // so commits do not fail on a fresh machine.
+    const { email, name } = pickIdentity(creds);
+    if (!existingEmail) {
+        try {
+            execFileSync('git', ['config', '--local', 'user.email', email], { cwd, stdio: 'pipe' });
+        }
+        catch { /* read-only fs */ }
+    }
+    if (!existingName) {
+        try {
+            execFileSync('git', ['config', '--local', 'user.name', name], { cwd, stdio: 'pipe' });
+        }
+        catch { /* read-only fs */ }
+    }
+}
+// Exported for unit tests so we do not have to re-derive expectations there.
+export const __testing = { deriveNameFromEmail, pickIdentity, FALLBACK_EMAIL, FALLBACK_NAME };

package/dist/git/preflight.d.ts

@@ -0,0 +1,28 @@
+export interface GitProbe {
+    installed: boolean;
+    /** Trimmed `git --version` output when detected; undefined otherwise. */
+    version?: string;
+    /** 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.
+ */
+export declare function probeGit(): GitProbe;
+/**
+ * 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.
+ */
+export declare function buildMissingGitMessage(commandName: string): string;
+/**
+ * Convenience wrapper for command entry points: probe git, and if it's
+ * missing, print the beginner-friendly message and exit with code 1.
+ * Returns void on success so callers can early-return on failure.
+ */
+export declare function requireGit(commandName: string): void;