runwork 0.14.0 → 0.15.0

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/utils/__tests__/help-json.test.d.ts

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

package/dist/utils/__tests__/help-json.test.js

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { Command } from 'commander';
+import { buildCommandHelpJson } from '../help-json.js';
+function optByFlags(cmd, flags) {
+    const json = buildCommandHelpJson(cmd, '1.0.0');
+    const opt = json.options.find(o => o.flags === flags);
+    if (!opt)
+        throw new Error(`option ${flags} not found`);
+    return opt;
+}
+describe('help-json option required semantics', () => {
+    const cmd = new Command('demo')
+        .option('--workspace <id>', 'workspace id (optional; defaults from credentials)')
+        .option('--flag', 'a boolean flag')
+        .option('--maybe [value]', 'an optional value')
+        .requiredOption('--token <t>', 'a genuinely required option');
+    it('marks a value-taking-but-optional option as NOT required (the --workspace bug)', () => {
+        const o = optByFlags(cmd, '--workspace <id>');
+        expect(o.required).toBe(false); // the option itself is not mandatory
+        expect(o.valueRequired).toBe(true); // but its value is required when present
+        expect(o.optional).toBe(false);
+    });
+    it('marks a boolean flag as neither required nor value-required', () => {
+        const o = optByFlags(cmd, '--flag');
+        expect(o.required).toBe(false);
+        expect(o.valueRequired).toBe(false);
+    });
+    it('marks an optional-value option correctly', () => {
+        const o = optByFlags(cmd, '--maybe [value]');
+        expect(o.required).toBe(false);
+        expect(o.valueRequired).toBe(false);
+        expect(o.optional).toBe(true);
+    });
+    it('marks a genuinely mandatory option as required AND value-required', () => {
+        const o = optByFlags(cmd, '--token <t>');
+        expect(o.required).toBe(true);
+        expect(o.valueRequired).toBe(true);
+    });
+});

package/dist/utils/__tests__/ignore-matcher.test.js

@@ -2,7 +2,7 @@ import { describe, it, expect, afterEach } from 'vitest';
 import { mkdtempSync, writeFileSync, rmSync } from 'fs';
 import { join } from 'path';
 import { tmpdir } from 'os';
-import { buildIgnoreSets, defaultIgnoreSets, isPathIgnored, parseGitignoreContent, } from '../ignore-matcher.js';
+import { buildIgnoreSets, defaultIgnoreSets, isPathIgnored, isRelPathIgnored, parseGitignoreContent, } from '../ignore-matcher.js';
 const tempDirs = [];
 function makeTempDir(prefix) {
     const dir = mkdtempSync(join(tmpdir(), `runwork-ignore-${prefix}-`));
@@ -26,6 +26,23 @@ describe('defaultIgnoreSets()', () => {
         expect(sets.dirs.has('.runwork')).toBe(true);
         expect(sets.dirs.has('.bun-cache')).toBe(true);
     });
+    it('excludes every .runwork/ state file from deploy/dev auto-commit staging', () => {
+        // commitWorkingTree() filters untracked files through isRelPathIgnored,
+        // so any path with a .runwork segment must be excluded -- including the
+        // local deploy-state/status files written before the detached child
+        // commits (Codex review P1).
+        const sets = defaultIgnoreSets();
+        for (const p of [
+            '.runwork/deploy-status.json',
+            '.runwork/last-deploy.json',
+            '.runwork/deploy-stdout.log',
+            '.runwork/dev-session.json',
+            '.runwork/setup.json',
+            '.runwork/preview-url',
+        ]) {
+            expect(isRelPathIgnored(p, sets), `${p} must be ignored`).toBe(true);
+        }
+    });
     it('includes .dev.vars and .env file defaults', () => {
         const sets = defaultIgnoreSets();
         expect(sets.files.has('.dev.vars')).toBe(true);

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

@@ -11,7 +11,21 @@ import type { Command } from 'commander';
 interface JsonOption {
     flags: string;
     description: string;
+    /**
+     * Whether the OPTION itself must be supplied (Commander's `mandatory`, set
+     * via `.makeOptionMandatory()`). This is what an agent reasoning about
+     * "do I have to pass this?" wants. Most options are false here even when
+     * they take a value -- e.g. `--workspace <id>` is optional (defaults from
+     * credentials). Previously this field was wrongly mapped to Commander's
+     * `required` (value-required), which marked nearly every option as required.
+     */
     required: boolean;
+    /**
+     * Whether the option's VALUE is required when the flag is present, i.e. it
+     * was declared with `<value>` (vs `[value]` or a boolean flag). Independent
+     * of whether the option itself must be supplied.
+     */
+    valueRequired: boolean;
     optional: boolean;
     variadic: boolean;
     defaultValue?: unknown;

package/dist/utils/help-json.js

@@ -11,7 +11,10 @@ function serializeOption(opt) {
     const result = {
         flags: opt.flags,
         description: opt.description,
-        required: opt.required,
+        // Commander's `mandatory` = the option must be supplied; `required` = the
+        // option's value is required when present. Expose both, correctly named.
+        required: opt.mandatory,
+        valueRequired: opt.required,
         optional: opt.optional,
         variadic: opt.variadic,
     };

package/dist/validate/__tests__/validate.test.d.ts

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

package/dist/validate/__tests__/validate.test.js

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import { summarizeFreshness } from '../freshness.js';
+import { detectViteError } from '../preview.js';
+describe('validate/freshness summarizeFreshness()', () => {
+    const base = { localSha: 'a', remoteSha: 'a', ahead: 0, behind: 0, uncommitted: false };
+    it('is in-sync when local==remote, no ahead/behind, clean tree', () => {
+        expect(summarizeFreshness(base).inSync).toBe(true);
+    });
+    it('is not in-sync with uncommitted changes', () => {
+        expect(summarizeFreshness({ ...base, uncommitted: true }).inSync).toBe(false);
+    });
+    it('is not in-sync when ahead of the remote', () => {
+        expect(summarizeFreshness({ ...base, ahead: 2 }).inSync).toBe(false);
+    });
+    it('is not in-sync when behind the remote', () => {
+        expect(summarizeFreshness({ ...base, behind: 1 }).inSync).toBe(false);
+    });
+    it('is not in-sync when there is no remote ref', () => {
+        expect(summarizeFreshness({ ...base, remoteSha: null }).inSync).toBe(false);
+    });
+    it('is not in-sync when there is no local HEAD', () => {
+        expect(summarizeFreshness({ ...base, localSha: null }).inSync).toBe(false);
+    });
+    it('passes through the raw counts', () => {
+        const f = summarizeFreshness({ localSha: 'x', remoteSha: 'y', ahead: 3, behind: 1, uncommitted: true });
+        expect(f).toMatchObject({ ahead: 3, behind: 1, uncommitted: true, inSync: false });
+    });
+});
+describe('validate/preview detectViteError()', () => {
+    it('detects the Vite error overlay element', () => {
+        expect(detectViteError('<vite-error-overlay></vite-error-overlay>')).toBe(true);
+    });
+    it('detects a plugin transform error', () => {
+        expect(detectViteError('[plugin:vite:react-babel] Unexpected token')).toBe(true);
+    });
+    it('detects a failed import resolution', () => {
+        expect(detectViteError('Failed to resolve import "./missing" from "src/App.tsx"')).toBe(true);
+    });
+    it('returns false for a healthy HTML document', () => {
+        expect(detectViteError('<!DOCTYPE html><html><body><div id="root"></div></body></html>')).toBe(false);
+    });
+});

package/dist/validate/freshness.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Git sync-freshness: how the local working tree relates to the deploy remote
+ * (`runwork/main`). Answers "do I have changes that aren't synced/deployed?"
+ * without scraping the sandbox (friction log #10).
+ */
+export interface Freshness {
+    localSha: string | null;
+    remoteSha: string | null;
+    ahead: number;
+    behind: number;
+    uncommitted: boolean;
+    /** true when local == remote and the tree is clean. */
+    inSync: boolean;
+}
+export interface FreshnessInput {
+    localSha: string | null;
+    remoteSha: string | null;
+    ahead: number;
+    behind: number;
+    uncommitted: boolean;
+}
+/** Pure: derive the in-sync verdict from the raw git counts/flags. */
+export declare function summarizeFreshness(input: FreshnessInput): Freshness;
+/**
+ * Collect git freshness for `cwd`. Best-effort fetches `runwork/main` first so
+ * the comparison reflects the real remote tip; tolerates offline/no-remote.
+ */
+export declare function getGitFreshness(cwd: string): Freshness;

package/dist/validate/freshness.js

@@ -0,0 +1,48 @@
+import { execFileSync } from '../utils/subprocess.js';
+/** Pure: derive the in-sync verdict from the raw git counts/flags. */
+export function summarizeFreshness(input) {
+    const inSync = input.localSha !== null &&
+        input.remoteSha !== null &&
+        input.ahead === 0 &&
+        input.behind === 0 &&
+        !input.uncommitted;
+    return { ...input, inSync };
+}
+function gitOut(cwd, args) {
+    try {
+        return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Collect git freshness for `cwd`. Best-effort fetches `runwork/main` first so
+ * the comparison reflects the real remote tip; tolerates offline/no-remote.
+ */
+export function getGitFreshness(cwd) {
+    // Best-effort: refresh the remote-tracking ref. Failure (offline, no remote)
+    // just means we compare against whatever ref we already have.
+    try {
+        execFileSync('git', ['fetch', 'runwork', 'main'], { cwd, stdio: 'pipe' });
+    }
+    catch {
+        /* offline or no runwork remote -- non-fatal */
+    }
+    const localSha = gitOut(cwd, ['rev-parse', 'HEAD']);
+    const remoteSha = gitOut(cwd, ['rev-parse', 'runwork/main']);
+    let ahead = 0;
+    let behind = 0;
+    if (localSha && remoteSha) {
+        // `<behind>\t<ahead>` relative to runwork/main...HEAD
+        const counts = gitOut(cwd, ['rev-list', '--left-right', '--count', 'runwork/main...HEAD']);
+        if (counts) {
+            const [b, a] = counts.split(/\s+/).map(n => parseInt(n, 10));
+            behind = Number.isFinite(b) ? b : 0;
+            ahead = Number.isFinite(a) ? a : 0;
+        }
+    }
+    const porcelain = gitOut(cwd, ['status', '--porcelain']);
+    const uncommitted = porcelain !== null && porcelain.length > 0;
+    return summarizeFreshness({ localSha, remoteSha, ahead, behind, uncommitted });
+}

package/dist/validate/preview.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Liveness of the preview deployment: does it respond, and is it serving a
+ * working build (vs a Vite error overlay)? This is the cheap "is my change
+ * live and compiling" signal the friction log (#10) reached for by hand.
+ */
+export interface PreviewLiveness {
+    url: string | null;
+    responds: boolean;
+    status: number | null;
+    /** A Vite/build error overlay was detected in the served HTML. */
+    errorDetected: boolean;
+    error?: string;
+}
+/**
+ * Heuristically detect a Vite dev-server error overlay / transform error in
+ * served HTML. These are the markers Vite injects when a module fails to
+ * compile, so their presence means the preview is serving a broken build.
+ */
+export declare function detectViteError(html: string): boolean;
+/** Fetch the preview URL and report whether it's live and error-free. */
+export declare function checkPreview(url: string | null): Promise<PreviewLiveness>;

package/dist/validate/preview.js

@@ -0,0 +1,39 @@
+import { httpFetch } from '../utils/http.js';
+/**
+ * Heuristically detect a Vite dev-server error overlay / transform error in
+ * served HTML. These are the markers Vite injects when a module fails to
+ * compile, so their presence means the preview is serving a broken build.
+ */
+export function detectViteError(html) {
+    const markers = [
+        'vite-error-overlay',
+        'class="vite-error',
+        '[vite] Internal Server Error',
+        '[plugin:vite:',
+        'Pre-transform error',
+        'Failed to resolve import',
+        'Internal server error:',
+    ];
+    return markers.some(m => html.includes(m));
+}
+/** Fetch the preview URL and report whether it's live and error-free. */
+export async function checkPreview(url) {
+    if (!url) {
+        return { url: null, responds: false, status: null, errorDetected: false };
+    }
+    try {
+        const res = await httpFetch(url, { method: 'GET' });
+        let errorDetected = false;
+        try {
+            const body = await res.text();
+            errorDetected = detectViteError(body);
+        }
+        catch {
+            /* body read failed -- treat as no overlay detected */
+        }
+        return { url, responds: res.status > 0 && res.status < 500, status: res.status, errorDetected };
+    }
+    catch (err) {
+        return { url, responds: false, status: null, errorDetected: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runwork",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "CLI for Runwork: develop, preview, and deploy Runwork apps from your local machine.",
   "license": "UNLICENSED",
   "author": "Runwork <info@runwork.ai> (https://www.runwork.ai)",