runwork 0.10.0 → 0.10.2

package/dist/commands/__tests__/clone-args.test.d.ts

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

package/dist/commands/__tests__/clone-args.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { normalizeCloneArgs } from '../clone.js';
+describe('normalizeCloneArgs', () => {
+    it('passes through both args unchanged when --app is not provided', () => {
+        expect(normalizeCloneArgs('app-id', 'C:/dir', undefined)).toEqual({
+            appId: 'app-id',
+            directory: 'C:/dir',
+        });
+        expect(normalizeCloneArgs('app-id', 'C:/dir', {})).toEqual({
+            appId: 'app-id',
+            directory: 'C:/dir',
+        });
+    });
+    it('passes through both args unchanged when --app is set but directory is also explicit', () => {
+        expect(normalizeCloneArgs('app-id', 'C:/dir', { app: 'foo' })).toEqual({ appId: 'app-id', directory: 'C:/dir' });
+    });
+    it('shifts the first positional to directory when --app is set and only one positional arg is present', () => {
+        // The reproducer from the field:
+        //   runwork clone --app academic-grade-conversion C:\Users\Oytun\Desktop\agc-test
+        // commander binds rawAppId = "C:\Users\..." and rawDirectory = undefined.
+        expect(normalizeCloneArgs('C:\\Users\\Oytun\\Desktop\\agc-test', undefined, {
+            app: 'academic-grade-conversion',
+        })).toEqual({
+            appId: undefined,
+            directory: 'C:\\Users\\Oytun\\Desktop\\agc-test',
+        });
+    });
+    it('does not shift when --app is set and no positional args are provided', () => {
+        expect(normalizeCloneArgs(undefined, undefined, { app: 'foo' })).toEqual({
+            appId: undefined,
+            directory: undefined,
+        });
+    });
+    it('does not shift when --app is set with only the directory positional (rawAppId already undefined)', () => {
+        // commander binds positional arguments left-to-right; if only one is
+        // given, it's always rawAppId. So this case shouldn't arise in practice
+        // -- but if a future commander upgrade changes that, we should leave
+        // already-correct args alone.
+        expect(normalizeCloneArgs(undefined, 'C:/dir', { app: 'foo' })).toEqual({
+            appId: undefined,
+            directory: 'C:/dir',
+        });
+    });
+});

package/dist/commands/__tests__/info-merge.test.d.ts

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

package/dist/commands/__tests__/info-merge.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import { __testing } from '../info.js';
+const { mergeSources, padName } = __testing;
+describe('mergeSources — bad data resilience', () => {
+    it('drops blueprint entries with missing name', () => {
+        const map = mergeSources([
+            { name: 'good', extra: {} },
+            { name: undefined, extra: {} },
+            { name: '', extra: {} },
+        ], [], (item) => item.name ?? '', 'app-1');
+        expect(Array.from(map.keys())).toEqual(['good']);
+    });
+    it('drops server items whose name resolver returns undefined or empty', () => {
+        const map = mergeSources([], [
+            { name: 'good', appId: 'app-1', appName: 'My App', deploymentMode: 'preview' },
+            { name: undefined, appId: 'app-1', appName: 'My App', deploymentMode: 'preview' },
+            { name: '', appId: 'app-1', appName: 'My App', deploymentMode: 'preview' },
+        ], (item) => item.name ?? '', 'app-1');
+        expect(Array.from(map.keys())).toEqual(['good']);
+    });
+    it('skips server items belonging to other apps', () => {
+        const map = mergeSources([], [
+            { name: 'mine', appId: 'app-1', appName: 'A', deploymentMode: 'preview' },
+            { name: 'theirs', appId: 'app-2', appName: 'B', deploymentMode: 'preview' },
+        ], (item) => item.name ?? '', 'app-1');
+        expect(Array.from(map.keys())).toEqual(['mine']);
+    });
+    it('merges blueprint and server entries by name', () => {
+        const map = mergeSources([{ name: 'agent-x', extra: { type: 'task' } }], [
+            { name: 'agent-x', appId: 'app-1', appName: 'A', deploymentMode: 'production' },
+            { name: 'agent-y', appId: 'app-1', appName: 'A', deploymentMode: 'preview' },
+        ], (item) => item.name ?? '', 'app-1');
+        const x = map.get('agent-x');
+        const y = map.get('agent-y');
+        expect(x?.sources).toEqual(['blueprint', 'production']);
+        expect(x?.blueprintExtra).toEqual({ type: 'task' });
+        expect(y?.sources).toEqual(['preview']);
+    });
+});
+describe('padName — defensive printer', () => {
+    it('pads valid names to the requested width', () => {
+        expect(padName('foo', 8)).toBe('foo     ');
+    });
+    it('returns a placeholder for undefined / null / empty inputs', () => {
+        expect(padName(undefined, 12)).toContain('(unnamed)');
+        expect(padName(null, 12)).toContain('(unnamed)');
+        expect(padName('', 12)).toContain('(unnamed)');
+        // Placeholder is also padded to the requested width.
+        expect(padName(undefined, 12).length).toBe(12);
+    });
+    it('does not throw on non-string inputs', () => {
+        expect(() => padName(42, 8)).not.toThrow();
+        expect(() => padName({}, 8)).not.toThrow();
+    });
+});

package/dist/commands/clone.d.ts

@@ -10,4 +10,18 @@ export interface CloneResult {
     workspaceName: string;
 }
 export declare function execClone(client: ApiClient, app: AppInfo, directory?: string, creds?: Credentials | null): Promise<CloneResult>;
+/**
+ * Reconcile positional args with --app. When --app is provided, the first
+ * positional argument is intended as the *directory* -- not another appId
+ * -- because the app is already disambiguated by the option. Without this,
+ * `runwork clone --app foo C:\path\to\dir` ends up parsing `C:\path\to\dir`
+ * as `appId` (which is then ignored because `--app` wins), leaving
+ * `directory` undefined and silently cloning into the slug under cwd.
+ */
+export declare function normalizeCloneArgs(appId: string | undefined, directory: string | undefined, options: {
+    app?: string;
+} | undefined): {
+    appId: string | undefined;
+    directory: string | undefined;
+};
 export declare const cloneCommand: Command;

package/dist/commands/clone.js

@@ -109,13 +109,28 @@ export async function execClone(client, app, directory, creds) {
         workspaceName: app.workspaceName,
     };
 }
+/**
+ * Reconcile positional args with --app. When --app is provided, the first
+ * positional argument is intended as the *directory* -- not another appId
+ * -- because the app is already disambiguated by the option. Without this,
+ * `runwork clone --app foo C:\path\to\dir` ends up parsing `C:\path\to\dir`
+ * as `appId` (which is then ignored because `--app` wins), leaving
+ * `directory` undefined and silently cloning into the slug under cwd.
+ */
+export function normalizeCloneArgs(appId, directory, options) {
+    if (options?.app && appId && !directory) {
+        return { appId: undefined, directory: appId };
+    }
+    return { appId, directory };
+}
 export const cloneCommand = new Command('clone')
     .description('Clone a Runwork app to local development')
     .argument('[appId]', 'App ID to clone (interactive if omitted)')
     .argument('[directory]', 'Target directory')
     .option('--app <name-or-id>', 'App name or ID (skips interactive selection)')
-    .action(async (appId, directory, options) => {
+    .action(async (rawAppId, rawDirectory, options) => {
     requireGit('clone');
+    const { appId, directory } = normalizeCloneArgs(rawAppId, rawDirectory, options);
     const creds = requireAuth();
     const client = new ApiClient(creds);
     const useJson = shouldOutputJson(undefined);
@@ -151,7 +166,10 @@ export const cloneCommand = new Command('clone')
         jsonOut(response);
         return;
     }
-    console.log(`\nApp "${cloneResult.appName}" cloned to ${cloneResult.directory}/`);
+    // No trailing separator: cloneResult.directory is already an absolute
+    // path. Appending '/' here mixed with Windows '\' separators produced
+    // confusing output like `C:\Users\...\app/` on Windows.
+    console.log(`\nApp "${cloneResult.appName}" cloned to ${cloneResult.directory}`);
     console.log(`Remote: ${client.getGitRemoteUrl(cloneResult.workspaceId, cloneResult.appId)}`);
     await runAgentWizard(cloneResult.directory);
     console.log(`Next: cd ${cloneResult.slug} && runwork dev`);

package/dist/commands/info.d.ts

@@ -1,3 +1,144 @@
 import { Command } from 'commander';
+import type { WorkspaceAllData } from '../types.js';
+interface BlueprintEntity {
+    entityName: string;
+    schema?: Record<string, unknown>;
+}
+interface BlueprintSchedule {
+    name: string;
+    schedule?: string;
+    description?: string;
+}
+interface BlueprintWorkflow {
+    name: string;
+    description?: string;
+}
+interface BlueprintAgent {
+    name: string;
+    type?: string;
+    description?: string;
+}
+interface BlueprintEndpoint {
+    path: string;
+    method?: string;
+    description?: string;
+}
+interface BlueprintComponent {
+    componentName: string;
+}
+interface Blueprint {
+    entities?: BlueprintEntity[];
+    schedules?: BlueprintSchedule[];
+    scheduledJobs?: BlueprintSchedule[];
+    workflows?: BlueprintWorkflow[];
+    agents?: BlueprintAgent[];
+    endpoints?: BlueprintEndpoint[];
+    publicEndpoints?: BlueprintEndpoint[];
+    components?: BlueprintComponent[];
+    fileStorage?: boolean | {
+        enabled?: boolean;
+    };
+}
+interface MergedEntity {
+    name: string;
+    sources: string[];
+    schema?: Record<string, unknown>;
+}
+interface MergedScheduledJob {
+    name: string;
+    sources: string[];
+    schedule?: string;
+    description?: string;
+}
+interface MergedWorkflow {
+    name: string;
+    sources: string[];
+    description?: string;
+}
+interface MergedAgent {
+    name: string;
+    sources: string[];
+    type?: string;
+    description?: string;
+}
+interface MergedEndpoint {
+    path: string;
+    method?: string;
+    sources: string[];
+    description?: string;
+}
+interface MergedComponent {
+    name: string;
+    sources: string[];
+}
+interface MergedFileStorage {
+    enabled: boolean;
+    sources: string[];
+}
+interface InfoOutput {
+    app: {
+        id: string;
+        name: string;
+        slug: string;
+    } | null;
+    workspace: {
+        id: string;
+        name: string;
+    };
+    preview: {
+        url: string | null;
+        active: boolean;
+    };
+    production: {
+        url: null;
+        deployed: boolean;
+    };
+    integrations: Array<{
+        id: string;
+        status: string;
+    }> | null;
+    registries: {
+        entities: MergedEntity[];
+        workflows: MergedWorkflow[];
+        scheduledJobs: MergedScheduledJob[];
+        agents: MergedAgent[];
+        publicEndpoints: MergedEndpoint[];
+        components: MergedComponent[];
+        fileStorage: MergedFileStorage;
+    } | null;
+    cli: {
+        version: string;
+        commands: Array<{
+            name: string;
+            description: string;
+        }>;
+    };
+}
+interface ServerRegistryItem {
+    appId: string;
+    appName: string;
+    deploymentMode?: 'preview' | 'production';
+}
+declare function mergeSources<T extends ServerRegistryItem>(blueprintItems: Array<{
+    name: string;
+    extra?: Record<string, unknown>;
+}>, serverItems: T[], getServerName: (item: T) => string, appId: string): Map<string, {
+    sources: string[];
+    serverItem?: T;
+    blueprintExtra?: Record<string, unknown>;
+}>;
+declare function buildRegistries(blueprint: Blueprint | null, serverData: WorkspaceAllData | null, appId: string): InfoOutput['registries'];
+/**
+ * Pad a possibly-missing string to a fixed width. Returns a visible
+ * placeholder when the value isn't a usable string so the human-readable
+ * printer can never crash on an unexpectedly-undefined field.
+ */
+declare function padName(value: unknown, width: number): string;
 export declare function formatSources(sources: string[]): string;
+export declare const __testing: {
+    mergeSources: typeof mergeSources;
+    padName: typeof padName;
+    buildRegistries: typeof buildRegistries;
+};
 export declare const infoCommand: Command;
+export {};

package/dist/commands/info.js

@@ -32,13 +32,22 @@ function readBlueprint(cwd) {
 }
 function mergeSources(blueprintItems, serverItems, getServerName, appId) {
     const map = new Map();
+    // Skip nameless entries so we never store an `undefined` key. A bad
+    // blueprint or a partially-populated server-side row would otherwise
+    // produce a registry entry with `name === undefined`, which then crashes
+    // the human-readable printer at `a.name.padEnd(24)` and yields ugly
+    // `"undefined": ...` keys in JSON output.
     for (const bp of blueprintItems) {
+        if (typeof bp.name !== 'string' || bp.name.length === 0)
+            continue;
         map.set(bp.name, { sources: ['blueprint'], blueprintExtra: bp.extra });
     }
     for (const serverItem of serverItems) {
         if (serverItem.appId !== appId)
             continue;
         const name = getServerName(serverItem);
+        if (typeof name !== 'string' || name.length === 0)
+            continue;
         const mode = serverItem.deploymentMode;
         const source = mode === 'production' ? 'production' : 'preview';
         const existing = map.get(name);
@@ -171,6 +180,16 @@ function getCliCommands(command) {
         return { name, description: cmd.description() };
     });
 }
+/**
+ * Pad a possibly-missing string to a fixed width. Returns a visible
+ * placeholder when the value isn't a usable string so the human-readable
+ * printer can never crash on an unexpectedly-undefined field.
+ */
+function padName(value, width) {
+    if (typeof value === 'string' && value.length > 0)
+        return value.padEnd(width);
+    return '(unnamed)'.padEnd(width);
+}
 export function formatSources(sources) {
     return sources
         .map(s => {
@@ -240,7 +259,7 @@ function printHumanOutput(data) {
             if (reg.entities.length > 0) {
                 console.log(`  ${bold('Entities:')}`);
                 for (const e of reg.entities) {
-                    console.log(`    ${e.name.padEnd(24)} ${formatSources(e.sources)}`);
+                    console.log(`    ${padName(e.name, 24)} ${formatSources(e.sources)}`);
                 }
                 console.log('');
             }
@@ -248,7 +267,7 @@ function printHumanOutput(data) {
                 console.log(`  ${bold('Workflows:')}`);
                 for (const w of reg.workflows) {
                     const desc = w.description ? `  ${dim(w.description)}` : '';
-                    console.log(`    ${w.name.padEnd(24)} ${formatSources(w.sources)}${desc}`);
+                    console.log(`    ${padName(w.name, 24)} ${formatSources(w.sources)}${desc}`);
                 }
                 console.log('');
             }
@@ -256,7 +275,7 @@ function printHumanOutput(data) {
                 console.log(`  ${bold('Scheduled Jobs:')}`);
                 for (const s of reg.scheduledJobs) {
                     const schedule = s.schedule ? `  ${gray(s.schedule)}` : '';
-                    console.log(`    ${s.name.padEnd(24)} ${formatSources(s.sources)}${schedule}`);
+                    console.log(`    ${padName(s.name, 24)} ${formatSources(s.sources)}${schedule}`);
                 }
                 console.log('');
             }
@@ -264,22 +283,22 @@ function printHumanOutput(data) {
                 console.log(`  ${bold('Agents:')}`);
                 for (const a of reg.agents) {
                     const type = a.type ? `  ${dim(a.type)}` : '';
-                    console.log(`    ${a.name.padEnd(24)} ${formatSources(a.sources)}${type}`);
+                    console.log(`    ${padName(a.name, 24)} ${formatSources(a.sources)}${type}`);
                 }
                 console.log('');
             }
             if (reg.publicEndpoints.length > 0) {
                 console.log(`  ${bold('Public Endpoints:')}`);
                 for (const e of reg.publicEndpoints) {
-                    const label = e.method ? `${e.method} ${e.path}` : e.path;
-                    console.log(`    ${label.padEnd(24)} ${formatSources(e.sources)}`);
+                    const label = e.method && e.path ? `${e.method} ${e.path}` : (e.path || '');
+                    console.log(`    ${padName(label, 24)} ${formatSources(e.sources)}`);
                 }
                 console.log('');
             }
             if (reg.components.length > 0) {
                 console.log(`  ${bold('Components:')}`);
                 for (const c of reg.components) {
-                    console.log(`    ${c.name.padEnd(24)} ${formatSources(c.sources)}`);
+                    console.log(`    ${padName(c.name, 24)} ${formatSources(c.sources)}`);
                 }
                 console.log('');
             }
@@ -298,6 +317,9 @@ function printHumanOutput(data) {
     console.log(dim(`  CLI version: ${data.cli.version}`));
     console.log('');
 }
+// Internal helpers exposed for unit tests; do not import from anywhere
+// other than `__tests__/`.
+export const __testing = { mergeSources, padName, buildRegistries };
 export const infoCommand = new Command('info')
     .description('Show app context, registries, and CLI reference (use --json for agent discovery)')
     .action(async (_opts, command) => {

package/dist/generated/version.d.ts

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

package/dist/generated/version.js

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

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

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+export {};

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);
+    });
+});