runwork 0.14.0 → 0.15.0

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;

package/dist/git/remote.js

@@ -0,0 +1,75 @@
+import { execFileSync } from '../utils/subprocess.js';
+/**
+ * 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 const RUNWORK_REMOTE = 'runwork';
+//                                               existing remote, e.g. `origin`, already at this URL)
+/**
+ * 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 function normalizeRemoteUrl(raw) {
+    const trimmed = raw.trim().replace(/\.git$/, '').replace(/\/+$/, '');
+    try {
+        const u = new URL(trimmed);
+        const host = u.host.toLowerCase();
+        const path = u.pathname.replace(/\/+$/, '');
+        return `${u.protocol}//${host}${path}`;
+    }
+    catch {
+        return trimmed.toLowerCase();
+    }
+}
+/** Map of remote name -> fetch URL, parsed from `git remote -v`. */
+export function listRemotes(cwd) {
+    const remotes = {};
+    let output;
+    try {
+        output = execFileSync('git', ['remote', '-v'], { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+    }
+    catch {
+        return remotes; // not a git repo, or git unavailable
+    }
+    for (const line of output.split(/\r?\n/)) {
+        // Format: `<name>\t<url> (fetch)` / `<name>\t<url> (push)`
+        const match = line.match(/^(\S+)\s+(\S+)\s+\((fetch|push)\)$/);
+        if (match && match[3] === 'fetch') {
+            remotes[match[1]] = match[2];
+        }
+    }
+    return remotes;
+}
+/**
+ * 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 function ensureRunworkRemote(cwd, canonicalUrl) {
+    const remotes = listRemotes(cwd);
+    const target = normalizeRemoteUrl(canonicalUrl);
+    const existing = remotes[RUNWORK_REMOTE];
+    if (existing && normalizeRemoteUrl(existing) === target) {
+        return { action: 'noop' };
+    }
+    if (existing) {
+        execFileSync('git', ['remote', 'set-url', RUNWORK_REMOTE, canonicalUrl], { cwd, stdio: 'pipe' });
+        return { action: 'updated' };
+    }
+    // `runwork` is missing. Note if any other remote already points at the same
+    // URL (the manual `git clone` case, where it's typically `origin`).
+    const reusedFrom = Object.entries(remotes).find(([, url]) => normalizeRemoteUrl(url) === target)?.[0];
+    execFileSync('git', ['remote', 'add', RUNWORK_REMOTE, canonicalUrl], { cwd, stdio: 'pipe' });
+    return reusedFrom ? { action: 'added', reusedFrom } : { action: 'added' };
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Disable git's background gc/maintenance for the repo at `cwd`. This is set
+ * locally (repo scope), is harmless on normal filesystems -- these app repos
+ * are small and centrally managed -- and avoids the pack-unlink failures that
+ * restricted mounts produce. Applied cross-platform with no FS detection, so
+ * it never risks a false positive (notably on Windows). Best-effort.
+ */
+export declare function hardenRepoForRestrictedFs(cwd: string): void;

package/dist/git/repo-config.js

@@ -0,0 +1,29 @@
+import { execFileSync } from '../utils/subprocess.js';
+/**
+ * Git config keys we disable on a freshly cloned app repo, with values.
+ * Background gc/maintenance rewrite pack files, which on restricted
+ * filesystems (some AI-agent "outputs" mounts disallow certain unlinks) fail
+ * with `unable to unlink '.git/objects/pack/...': Operation not permitted`,
+ * leaving git state unreliable (friction log #9).
+ */
+const HARDENING = [
+    ['gc.auto', '0'],
+    ['maintenance.auto', 'false'],
+];
+/**
+ * Disable git's background gc/maintenance for the repo at `cwd`. This is set
+ * locally (repo scope), is harmless on normal filesystems -- these app repos
+ * are small and centrally managed -- and avoids the pack-unlink failures that
+ * restricted mounts produce. Applied cross-platform with no FS detection, so
+ * it never risks a false positive (notably on Windows). Best-effort.
+ */
+export function hardenRepoForRestrictedFs(cwd) {
+    for (const [key, value] of HARDENING) {
+        try {
+            execFileSync('git', ['config', key, value], { cwd, stdio: 'pipe' });
+        }
+        catch {
+            // Best-effort: failing to set a hardening config must not fail a clone.
+        }
+    }
+}

package/dist/health/__tests__/checks.test.js

@@ -130,7 +130,7 @@ describe('checkGitCredentialHelper', () => {
         const ctx = makeCtx();
         const result = await checkGitCredentialHelper(ctx);
         expect(result.status).toBe('fail');
-        expect(result.fix).toBe('runwork login');
+        expect(result.fix).toBe('runwork doctor --fix');
     });
     it('fails when entries exist but none match the credentials origin', async () => {
         const { checkGitCredentialHelper } = await import('../checks.js');
@@ -165,7 +165,7 @@ describe('checkGitCredentialHelper', () => {
         const result = await checkGitCredentialHelper(ctx);
         expect(result.status).toBe('fail');
         expect(result.message).toContain('binary not found');
-        expect(result.fix).toContain('runwork login');
+        expect(result.fix).toContain('runwork doctor --fix');
     });
     it('passes when the registered absolute path still exists', async () => {
         const { checkGitCredentialHelper } = await import('../checks.js');

package/dist/health/__tests__/fix.test.d.ts

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

package/dist/health/__tests__/fix.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('fs', () => ({ existsSync: vi.fn() }));
+vi.mock('../../git/credentials.js', () => ({ ensureGitCredentialHelper: vi.fn(async () => { }) }));
+vi.mock('../../git/remote.js', () => ({ ensureRunworkRemote: vi.fn(() => ({ action: 'added' })) }));
+const { existsSync: mockExistsSync } = await import('fs');
+const { ensureGitCredentialHelper } = await import('../../git/credentials.js');
+const { ensureRunworkRemote } = await import('../../git/remote.js');
+const { applyDoctorFixes, FIXABLE_CHECKS } = await import('../fix.js');
+const creds = { apiKey: 'k', email: 'u@e.com', baseUrl: 'https://runwork.ai' };
+const config = { workspaceId: 'ws', appId: 'app', workspaceName: 'WS', appName: 'App' };
+function makeCtx(overrides = {}) {
+    return {
+        credentials: creds,
+        client: { getGitRemoteUrl: (ws, app) => `https://runwork.ai/api/git/${ws}/${app}` },
+        config,
+        cwd: '/repo',
+        ...overrides,
+    };
+}
+describe('health/fix applyDoctorFixes', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.mocked(mockExistsSync).mockReturnValue(true); // .git present by default
+    });
+    it('only advertises the two fixable checks', () => {
+        expect(FIXABLE_CHECKS).toEqual(['git-credential-helper', 'git-remote']);
+    });
+    it('registers the git credential helper when that check is failing', async () => {
+        const outcomes = await applyDoctorFixes(makeCtx(), ['git-credential-helper']);
+        expect(ensureGitCredentialHelper).toHaveBeenCalledWith('https://runwork.ai');
+        expect(outcomes).toEqual([
+            { name: 'git-credential-helper', applied: true, message: expect.stringContaining('registered') },
+        ]);
+    });
+    it('cannot fix the credential helper when not logged in', async () => {
+        const outcomes = await applyDoctorFixes(makeCtx({ credentials: null }), ['git-credential-helper']);
+        expect(ensureGitCredentialHelper).not.toHaveBeenCalled();
+        expect(outcomes[0]).toMatchObject({ name: 'git-credential-helper', applied: false });
+        expect(outcomes[0].message).toContain('runwork login');
+    });
+    it('configures the runwork remote with the canonical /api/git URL', async () => {
+        const outcomes = await applyDoctorFixes(makeCtx(), ['git-remote']);
+        expect(ensureRunworkRemote).toHaveBeenCalledWith('/repo', 'https://runwork.ai/api/git/ws/app');
+        expect(outcomes[0]).toMatchObject({ name: 'git-remote', applied: true });
+    });
+    it('cannot fix the remote outside a project (no config)', async () => {
+        const outcomes = await applyDoctorFixes(makeCtx({ config: null }), ['git-remote']);
+        expect(ensureRunworkRemote).not.toHaveBeenCalled();
+        expect(outcomes[0]).toMatchObject({ name: 'git-remote', applied: false });
+        expect(outcomes[0].message).toContain('project');
+    });
+    it('cannot fix the remote when the directory is not a git repo', async () => {
+        vi.mocked(mockExistsSync).mockReturnValue(false);
+        const outcomes = await applyDoctorFixes(makeCtx(), ['git-remote']);
+        expect(ensureRunworkRemote).not.toHaveBeenCalled();
+        expect(outcomes[0]).toMatchObject({ name: 'git-remote', applied: false });
+        expect(outcomes[0].message).toContain('git init');
+    });
+    it('ignores failing checks it cannot remediate', async () => {
+        const outcomes = await applyDoctorFixes(makeCtx(), ['auth', 'network', 'cli-version']);
+        expect(ensureGitCredentialHelper).not.toHaveBeenCalled();
+        expect(ensureRunworkRemote).not.toHaveBeenCalled();
+        expect(outcomes).toEqual([]);
+    });
+    it('applies both fixes when both checks fail', async () => {
+        const outcomes = await applyDoctorFixes(makeCtx(), ['git-credential-helper', 'git-remote']);
+        expect(ensureGitCredentialHelper).toHaveBeenCalledOnce();
+        expect(ensureRunworkRemote).toHaveBeenCalledOnce();
+        expect(outcomes.map(o => o.name)).toEqual(['git-credential-helper', 'git-remote']);
+        expect(outcomes.every(o => o.applied)).toBe(true);
+    });
+});

package/dist/health/__tests__/runner-filter.test.d.ts

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

package/dist/health/__tests__/runner-filter.test.js

@@ -0,0 +1,61 @@
+import { describe, it, expect, vi } from 'vitest';
+// Mock the check implementations so we test ONLY the runner's selection logic
+// (no network, no git, no fs). Each returns a trivial passing result tagged
+// with its own name.
+function pass(name) {
+    return { name, status: 'pass', message: '' };
+}
+vi.mock('../checks.js', () => ({
+    buildContext: vi.fn(() => ({ credentials: null, client: null, config: null, cwd: '/repo' })),
+    checkSystemDeps: vi.fn(async () => pass('system-deps')),
+    checkCliVersion: vi.fn(async () => pass('cli-version')),
+    checkCliArtifactReachable: vi.fn(async () => pass('cli-artifact')),
+    checkCliInstallLocation: vi.fn(async () => pass('cli-install-location')),
+    checkAuthAndNetwork: vi.fn(async () => ({ auth: pass('auth'), network: pass('network') })),
+    checkGitCredentialHelper: vi.fn(async () => pass('git-credential-helper')),
+    checkProjectConfig: vi.fn(async () => pass('project-config')),
+    checkAppExists: vi.fn(async () => pass('app-exists')),
+    checkGitRemote: vi.fn(async () => pass('git-remote')),
+    checkDeployFreshness: vi.fn(async () => pass('deploy-freshness')),
+    checkAgentSetup: vi.fn(async () => pass('agent-setup')),
+}));
+const { runAllChecks, ALL_CHECK_NAMES } = await import('../runner.js');
+describe('health/runner check selection', () => {
+    it('ALL_CHECK_NAMES lists every check in run order', () => {
+        expect(ALL_CHECK_NAMES).toEqual([
+            'system-deps',
+            'cli-version',
+            'cli-artifact',
+            'cli-install-location',
+            'auth',
+            'network',
+            'git-credential-helper',
+            'project-config',
+            'app-exists',
+            'git-remote',
+            'deploy-freshness',
+            'agent-setup',
+        ]);
+    });
+    it('runs every check when no filter is given', async () => {
+        const report = await runAllChecks();
+        expect(report.checks.map(c => c.name)).toEqual(ALL_CHECK_NAMES);
+    });
+    it('runs only the requested check when scoped', async () => {
+        const report = await runAllChecks({ only: ['git-credential-helper'] });
+        expect(report.checks.map(c => c.name)).toEqual(['git-credential-helper']);
+    });
+    it('includes only the requested name from a multi-result runner (auth without network)', async () => {
+        const report = await runAllChecks({ only: ['auth'] });
+        expect(report.checks.map(c => c.name)).toEqual(['auth']);
+    });
+    it('can request both halves of a combined runner', async () => {
+        const report = await runAllChecks({ only: ['auth', 'network'] });
+        expect(report.checks.map(c => c.name)).toEqual(['auth', 'network']);
+    });
+    it('returns an empty pass report when the filter matches nothing', async () => {
+        const report = await runAllChecks({ only: ['does-not-exist'] });
+        expect(report.checks).toEqual([]);
+        expect(report.status).toBe('pass');
+    });
+});

package/dist/health/checks.d.ts

@@ -32,4 +32,11 @@ export declare function checkGitCredentialHelper(ctx: DoctorContext): Promise<Ch
 export declare function checkProjectConfig(ctx: DoctorContext): Promise<CheckResult>;
 export declare function checkAppExists(ctx: DoctorContext): Promise<CheckResult>;
 export declare function checkGitRemote(ctx: DoctorContext): Promise<CheckResult>;
+/**
+ * Compare the current local HEAD against the last deploy recorded from this
+ * machine (`.runwork/last-deploy.json`). Surfaces "you have undeployed
+ * commits" so a deploy can be verified at a glance (friction log #8). Silent
+ * (skip) outside a project or before the first local deploy.
+ */
+export declare function checkDeployFreshness(ctx: DoctorContext): Promise<CheckResult>;
 export declare function checkAgentSetup(): Promise<CheckResult>;