runwork 0.13.4 → 0.15.0

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>;

package/dist/health/checks.js

@@ -8,6 +8,8 @@ import { ApiClient } from '../api/client.js';
 import { detectAgents, getAdapterBySlug } from '../agents/detect.js';
 import { httpFetch } from '../utils/http.js';
 import { probeGit, parseGitVersion } from '../git/preflight.js';
+import { lookupCredentialHelper, helperBinaryStatus } from '../git/credentials.js';
+import { getDeploySummary } from '../deploy/deploy-state.js';
 // First-party distribution endpoints. Defaults match the plan, can be
 // overridden via RUNWORK_DOWNLOAD_BASE_URL for staging or debugging.
 const BASE_URL = process.env.RUNWORK_DOWNLOAD_BASE_URL || 'https://runwork.ai';
@@ -283,56 +285,40 @@ export async function checkGitCredentialHelper(ctx) {
             fix: 'runwork login',
         };
     }
-    // `--get-regexp` returns 1 (and prints nothing) when no entry matches,
-    // so a non-zero exit is a normal "not registered" signal -- not an error.
-    let helperConfig;
-    try {
-        const buf = execFileSync('git', ['config', '--global', '--get-regexp', 'credential\\..*runwork.*\\.helper'], { stdio: ['ignore', 'pipe', 'ignore'] });
-        helperConfig = buf.toString('utf-8');
-    }
-    catch {
+    // The scoped lookup (get-regexp + origin match) is shared with the
+    // lazy-ensure path in git/credentials.ts so the two can't drift. We only
+    // need to map its result onto doctor's richer status messages here.
+    const lookup = lookupCredentialHelper(origin);
+    if (lookup.status === 'none') {
         return {
             name: 'git-credential-helper',
             status: 'fail',
             message: `no credential helper registered for ${origin}`,
-            fix: 'runwork login',
+            fix: 'runwork doctor --fix',
         };
     }
-    // Each line is `credential.<scope>.helper <value>`. We want a line whose
-    // <scope> matches the user's actual baseUrl origin (not e.g. a stale
-    // staging origin from a previous login).
-    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) {
+    if (lookup.status === 'unscoped') {
         return {
             name: 'git-credential-helper',
             status: 'fail',
-            message: `no credential helper registered for ${origin} (found ${lines.length} other runwork helper entries)`,
-            fix: 'runwork login',
+            message: `no credential helper registered for ${origin} (found ${lookup.otherCount} other runwork helper entries)`,
+            fix: 'runwork doctor --fix',
         };
     }
-    const value = scopedRegex.exec(matchedLine)?.[1] ?? '';
     // Helper values starting with `!` are shell commands. Common shapes:
     //   `!runwork git-credential-helper`                 (PATH-relative)
     //   `!"/abs/path/to/runwork" git-credential-helper`  (post-Pass-2 hardening, POSIX)
     //   `!"C:/.../runwork.exe" git-credential-helper`    (post-Pass-2 hardening, Windows)
-    // We only validate "absolute path" entries by existsSync() because that's
-    // the unambiguous case. PATH-relative entries we trust git+bash to resolve
-    // at invocation time (no good way to simulate that without running it).
-    const absoluteHelperRegex = /^!"?(\/|[A-Za-z]:[\\/])/;
-    if (absoluteHelperRegex.test(value)) {
-        const pathMatch = value.match(/^!"([^"]+)"|^!(\S+)/);
-        const helperPath = pathMatch?.[1] ?? pathMatch?.[2] ?? '';
-        if (helperPath && !existsSync(helperPath)) {
-            return {
-                name: 'git-credential-helper',
-                status: 'fail',
-                message: `helper registered but binary not found at ${helperPath}`,
-                fix: 'runwork login (re-registers with the current binary path)',
-            };
-        }
+    // helperBinaryStatus() validates only absolute-path entries on disk; it
+    // trusts PATH-relative entries to resolve at git-invocation time.
+    const binary = helperBinaryStatus(lookup.value);
+    if (!binary.ok && binary.path) {
+        return {
+            name: 'git-credential-helper',
+            status: 'fail',
+            message: `helper registered but binary not found at ${binary.path}`,
+            fix: 'runwork doctor --fix (re-registers with the current binary path)',
+        };
     }
     return {
         name: 'git-credential-helper',
@@ -441,9 +427,37 @@ export async function checkGitRemote(ctx) {
             name: 'git-remote',
             status: 'fail',
             message: 'remote "runwork" not configured',
-            fix: `git remote add runwork ${expectedUrl}`,
+            fix: `runwork doctor --fix (or: git remote add runwork ${expectedUrl})`,
+        };
+    }
+}
+// ── 7a. Deploy freshness ─────────────────────────────────────────────
+/**
+ * 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 async function checkDeployFreshness(ctx) {
+    if (!ctx.config) {
+        return { name: 'deploy-freshness', status: 'skip', message: 'skipped (no project)' };
+    }
+    const summary = getDeploySummary(ctx.cwd);
+    if (!summary.deployedShortSha) {
+        return { name: 'deploy-freshness', status: 'skip', message: 'no deploy recorded from this machine' };
+    }
+    if (summary.inSync === true) {
+        return { name: 'deploy-freshness', status: 'pass', message: `local HEAD matches last deploy (${summary.deployedShortSha})` };
+    }
+    if (summary.inSync === false) {
+        return {
+            name: 'deploy-freshness',
+            status: 'warn',
+            message: `local (${summary.localShortSha}) has commits not in the last deploy (${summary.deployedShortSha})`,
+            fix: 'runwork deploy',
         };
     }
+    return { name: 'deploy-freshness', status: 'skip', message: 'local HEAD unknown' };
 }
 // ── 8. Agent setup ───────────────────────────────────────────────────
 function loadSetupState() {

package/dist/health/fix.d.ts

@@ -0,0 +1,22 @@
+import type { DoctorContext } from './checks.js';
+/** Check names `runwork doctor --fix` knows how to auto-remediate. */
+export declare const FIXABLE_CHECKS: readonly string[];
+export interface FixOutcome {
+    /** The check name this outcome corresponds to. */
+    name: string;
+    /** Whether a remediation was actually applied (false = couldn't, with a reason). */
+    applied: boolean;
+    /** Human-readable description of what was done, or why it couldn't be. */
+    message: string;
+}
+/**
+ * Apply auto-remediations for the failing checks doctor knows how to fix.
+ * Only acts on `failingNames` that are in FIXABLE_CHECKS; everything else is
+ * left for the user (with the `fix` hint each check already carries).
+ *
+ * - git-credential-helper -> register the runwork git helper for the logged-in
+ *   origin (the B1 ensure-path), so headless-auth'd sessions can use git.
+ * - git-remote -> point the `runwork` remote at the app's canonical URL (the
+ *   B2 ensure-path), using the correct `/api/git/...` URL from the API client.
+ */
+export declare function applyDoctorFixes(ctx: DoctorContext, failingNames: string[]): Promise<FixOutcome[]>;

package/dist/health/fix.js

@@ -0,0 +1,62 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { ensureGitCredentialHelper } from '../git/credentials.js';
+import { ensureRunworkRemote } from '../git/remote.js';
+/** Check names `runwork doctor --fix` knows how to auto-remediate. */
+export const FIXABLE_CHECKS = ['git-credential-helper', 'git-remote'];
+/**
+ * Apply auto-remediations for the failing checks doctor knows how to fix.
+ * Only acts on `failingNames` that are in FIXABLE_CHECKS; everything else is
+ * left for the user (with the `fix` hint each check already carries).
+ *
+ * - git-credential-helper -> register the runwork git helper for the logged-in
+ *   origin (the B1 ensure-path), so headless-auth'd sessions can use git.
+ * - git-remote -> point the `runwork` remote at the app's canonical URL (the
+ *   B2 ensure-path), using the correct `/api/git/...` URL from the API client.
+ */
+export async function applyDoctorFixes(ctx, failingNames) {
+    const failing = new Set(failingNames);
+    const outcomes = [];
+    if (failing.has('git-credential-helper')) {
+        if (ctx.credentials?.baseUrl) {
+            await ensureGitCredentialHelper(ctx.credentials.baseUrl);
+            outcomes.push({
+                name: 'git-credential-helper',
+                applied: true,
+                message: 'registered the runwork git credential helper',
+            });
+        }
+        else {
+            outcomes.push({
+                name: 'git-credential-helper',
+                applied: false,
+                message: 'not logged in -- run `runwork login` first',
+            });
+        }
+    }
+    if (failing.has('git-remote')) {
+        if (!ctx.config || !ctx.client) {
+            outcomes.push({
+                name: 'git-remote',
+                applied: false,
+                message: 'no project config -- run inside an app directory',
+            });
+        }
+        else if (!existsSync(join(ctx.cwd, '.git'))) {
+            outcomes.push({
+                name: 'git-remote',
+                applied: false,
+                message: 'not a git repository -- run `git init` first',
+            });
+        }
+        else {
+            ensureRunworkRemote(ctx.cwd, ctx.client.getGitRemoteUrl(ctx.config.workspaceId, ctx.config.appId));
+            outcomes.push({
+                name: 'git-remote',
+                applied: true,
+                message: 'configured the `runwork` remote at the canonical URL',
+            });
+        }
+    }
+    return outcomes;
+}

package/dist/health/runner.d.ts

@@ -1,2 +1,8 @@
 import type { DoctorReport } from './types.js';
-export declare function runAllChecks(): Promise<DoctorReport>;
+/** Every check name doctor knows about, in run order. Used to validate `--check`. */
+export declare const ALL_CHECK_NAMES: readonly string[];
+export interface RunChecksOptions {
+    /** When set, run only the named checks (skips unrelated work like network). */
+    only?: string[];
+}
+export declare function runAllChecks(options?: RunChecksOptions): Promise<DoctorReport>;

package/dist/health/runner.js

@@ -1,32 +1,45 @@
-import { buildContext, checkSystemDeps, checkCliVersion, checkCliArtifactReachable, checkCliInstallLocation, checkAuthAndNetwork, checkGitCredentialHelper, checkProjectConfig, checkAppExists, checkGitRemote, checkAgentSetup, } from './checks.js';
-export async function runAllChecks() {
+import { buildContext, checkSystemDeps, checkCliVersion, checkCliArtifactReachable, checkCliInstallLocation, checkAuthAndNetwork, checkGitCredentialHelper, checkProjectConfig, checkAppExists, checkGitRemote, checkDeployFreshness, checkAgentSetup, } from './checks.js';
+const CHECK_RUNNERS = [
+    { names: ['system-deps'], run: async () => [await checkSystemDeps()] },
+    { names: ['cli-version'], run: async () => [await checkCliVersion()] },
+    { names: ['cli-artifact'], run: async () => [await checkCliArtifactReachable()] },
+    { names: ['cli-install-location'], run: async () => [await checkCliInstallLocation()] },
+    // Auth + Network come from one combined call (network reuses the auth probe).
+    {
+        names: ['auth', 'network'],
+        run: async (ctx) => {
+            const { auth, network } = await checkAuthAndNetwork(ctx);
+            return [auth, network];
+        },
+    },
+    // Catches "logged in but git auth not wired up" -- on Windows this surfaces
+    // as a Git Credential Manager popup mid-clone with no obvious cause.
+    { names: ['git-credential-helper'], run: async (ctx) => [await checkGitCredentialHelper(ctx)] },
+    { names: ['project-config'], run: async (ctx) => [await checkProjectConfig(ctx)] },
+    { names: ['app-exists'], run: async (ctx) => [await checkAppExists(ctx)] },
+    { names: ['git-remote'], run: async (ctx) => [await checkGitRemote(ctx)] },
+    { names: ['deploy-freshness'], run: async (ctx) => [await checkDeployFreshness(ctx)] },
+    { names: ['agent-setup'], run: async () => [await checkAgentSetup()] },
+];
+/** Every check name doctor knows about, in run order. Used to validate `--check`. */
+export const ALL_CHECK_NAMES = CHECK_RUNNERS.flatMap(r => r.names);
+export async function runAllChecks(options) {
     const ctx = buildContext();
+    const only = options?.only && options.only.length ? new Set(options.only) : null;
     const checks = [];
-    // 1. System deps
-    checks.push(await checkSystemDeps());
-    // 2. CLI version (runwork.ai/cli/latest.json)
-    checks.push(await checkCliVersion());
-    // 2a. CLI artifact reachability for this host platform
-    checks.push(await checkCliArtifactReachable());
-    // 2b. Canonical install location
-    checks.push(await checkCliInstallLocation());
-    // 3 & 4. Auth + Network (combined call)
-    const { auth, network } = await checkAuthAndNetwork(ctx);
-    checks.push(auth);
-    checks.push(network);
-    // 4a. Git credential helper -- catches "logged in but git auth not wired
-    //     up" state that surfaces on Windows as a Git Credential Manager
-    //     popup mid-clone with no obvious cause.
-    checks.push(await checkGitCredentialHelper(ctx));
-    // 5. Project config
-    checks.push(await checkProjectConfig(ctx));
-    // 6. App exists
-    checks.push(await checkAppExists(ctx));
-    // 7. Git remote
-    checks.push(await checkGitRemote(ctx));
-    // 8. Agent setup
-    checks.push(await checkAgentSetup());
-    // Overall status: worst of all checks
+    for (const runner of CHECK_RUNNERS) {
+        // Skip a runner entirely unless at least one of its names was requested.
+        if (only && !runner.names.some(n => only.has(n)))
+            continue;
+        const results = await runner.run(ctx);
+        for (const result of results) {
+            // For multi-result runners (auth+network), include only the requested
+            // names when scoped -- e.g. `--check auth` shouldn't print network.
+            if (only && !only.has(result.name))
+                continue;
+            checks.push(result);
+        }
+    }
     const hasFailure = checks.some(c => c.status === 'fail');
     const hasWarning = checks.some(c => c.status === 'warn');
     const status = hasFailure ? 'fail' : hasWarning ? 'warn' : 'pass';

package/dist/index.js

@@ -5,6 +5,7 @@ import { initCommand } from './commands/init.js';
 import { cloneCommand } from './commands/clone.js';
 import { devCommand } from './commands/dev.js';
 import { deployCommand } from './commands/deploy.js';
+import { validateCommand } from './commands/validate.js';
 import { logsCommand } from './commands/logs.js';
 import { upgradeCommand } from './commands/upgrade.js';
 import { logoutCommand } from './commands/logout.js';
@@ -62,6 +63,7 @@ program.addCommand(initCommand);
 program.addCommand(cloneCommand);
 program.addCommand(devCommand);
 program.addCommand(deployCommand);
+program.addCommand(validateCommand);
 program.addCommand(logsCommand);
 program.addCommand(upgradeCommand);
 program.addCommand(logoutCommand);

package/dist/tools/types.d.ts

@@ -16,6 +16,9 @@ export type PlatformString = string | {
  * Detection strategy. Supports simple binary/path checks plus richer
  * Windows-specific methods and a nested `any` combinator for tools that
  * ship as both GUI app and CLI binary.
+ *
+ * `always` means "no local probe; treat as available." Used by web-only
+ * agents (e.g. ChatGPT Web) that have no local footprint to detect.
  */
 export type Detection = {
     method: 'binary' | 'path';
@@ -26,6 +29,8 @@ export type Detection = {
 } | {
     method: 'any';
     target: Detection[];
+} | {
+    method: 'always';
 };
 /**
  * Common shape for anything that can be detected and installed locally.

package/dist/types.d.ts

@@ -115,6 +115,7 @@ export interface ExternalSkillRegistration {
     importedAt: number;
     importedBy: string;
 }
+export type McpAuthType = 'none' | 'oauth' | 'header';
 export interface McpServerConfig {
     id: string;
     name: string;
@@ -125,6 +126,8 @@ export interface McpServerConfig {
     addedBy: string;
     lastConnectedAt?: number;
     toolCount?: number;
+    authType?: McpAuthType;
+    headerNames?: string[];
 }
 /**
  * Per-agent state tracking baked-in default permission rules that the CLI

package/dist/utils/__tests__/help-json.test.d.ts

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