runwork 0.10.2 → 0.10.4

package/dist/dev/detach.js

@@ -0,0 +1,292 @@
+/**
+ * `runwork dev --detach` orchestration.
+ *
+ * The detach contract:
+ *
+ *   1. Parent spawns the child via `process.execPath` with the same args
+ *      plus `--internal-detached-child`. Child stdout/stderr are routed to
+ *      log files in `.runwork/`. Parent calls `child.unref()` and exits as
+ *      soon as the rendezvous signal arrives.
+ *
+ *   2. Child runs the same `runwork dev` code path as foreground, but in
+ *      "detached" mode: no TUI, no keypress listener, JSON event stream
+ *      to stdout (which is the log file).
+ *
+ *   3. Rendezvous channel is the session file, NOT a pipe. The child
+ *      writes `.runwork/dev-session.json` once it has a `previewUrl`. The
+ *      parent polls. When the parent observes a file whose `pid` matches
+ *      the spawned child AND `previewUrl` is non-empty, parent prints +
+ *      emits the URL and exits 0.
+ *
+ *   4. On timeout, parent attempts a single kill of the child, removes
+ *      any partial session file, and exits 1 with a structured error.
+ *
+ * The file-as-IPC choice is intentional: pipes don't survive parent exit,
+ * and Node IPC has historical Bun-on-Windows quirks. The session file is
+ * already our durable lifecycle truth; reusing it for the handshake is
+ * free.
+ */
+import * as fs from 'fs';
+import * as child_process from 'child_process';
+import { getSessionPaths, readSessionFile, removeSessionFileIfOwned, } from './session.js';
+/**
+ * Internal flag passed to the child. Hidden from `--help`. The child uses
+ * its presence to skip the parent-spawn branch and run the actual dev
+ * work in detached mode.
+ */
+export const INTERNAL_DETACHED_CHILD_FLAG = '--internal-detached-child';
+const realPollDeps = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+};
+function resolvePollDeps(deps) {
+    if (!deps)
+        return realPollDeps;
+    return {
+        now: deps.now ?? realPollDeps.now,
+        sleep: deps.sleep ?? realPollDeps.sleep,
+    };
+}
+/**
+ * Poll the session file until either:
+ *   - a file appears whose pid matches `expectedPid` AND has a non-empty
+ *     `previewUrl` -> `ready`
+ *   - the timeout elapses -> `timeout`
+ *
+ * If a file appears with a different pid (some other process won a write
+ * race), we treat it as the user's intent being satisfied and return
+ * `wrong-pid` so the caller can decide how to handle it -- usually that's
+ * "another `runwork dev` invocation already had a session running, fine."
+ *
+ * The function does not validate `bootTime` or `appId` -- those are the
+ * caller's job once they know which file matters. We only care about the
+ * shape of the file and the pid match here.
+ */
+export async function pollForSession(appDir, expectedPid, expectedAppId, opts = {}) {
+    const intervalMs = opts.intervalMs ?? 250;
+    const timeoutMs = opts.timeoutMs ?? 90_000;
+    const d = resolvePollDeps(opts.deps);
+    const deadline = d.now() + timeoutMs;
+    while (d.now() < deadline) {
+        if (opts.isChildAlive && !opts.isChildAlive()) {
+            return { result: 'child-exited' };
+        }
+        const file = readSessionFile(appDir);
+        if (file && file.previewUrl && file.appId === expectedAppId) {
+            if (file.pid === expectedPid) {
+                return { result: 'ready', file };
+            }
+            // Another process wrote a session file before our child did. The
+            // user's intent ("have a dev session running") is satisfied. Caller
+            // decides whether to log this and exit success or kill our child.
+            return { result: 'wrong-pid', file };
+        }
+        await d.sleep(intervalMs);
+    }
+    // One last child-alive probe before declaring timeout: a child that
+    // exited just before the deadline would otherwise be reported as
+    // "timeout" instead of "child-exited", losing diagnostic information.
+    if (opts.isChildAlive && !opts.isChildAlive()) {
+        return { result: 'child-exited' };
+    }
+    return { result: 'timeout' };
+}
+/**
+ * Open the stdout/stderr log files in truncating mode and return their
+ * descriptors. We truncate (not append) so each new dev session starts
+ * fresh -- log rotation across sessions is out of scope.
+ *
+ * The descriptors must be closed by the caller after `spawn` so the
+ * parent process doesn't keep them open (which would prevent the child
+ * from being the sole owner).
+ */
+export function openLogFds(appDir) {
+    const paths = getSessionPaths(appDir);
+    fs.mkdirSync(paths.dir, { recursive: true });
+    const stdoutFd = fs.openSync(paths.stdoutLog, 'w');
+    const stderrFd = fs.openSync(paths.stderrLog, 'w');
+    return { stdoutFd, stderrFd };
+}
+/**
+ * The parent half of `runwork dev --detach`. Returns a structured outcome
+ * the caller can translate into stdout text and an exit code.
+ *
+ * IMPORTANT: this function does NOT print anything. It only orchestrates.
+ * The caller (in `dev.ts`) decides how to render the outcome -- human
+ * banner vs. JSON event vs. error stream.
+ */
+export async function runAsDetachedParent(opts) {
+    let child;
+    try {
+        child = (opts.spawn ?? defaultSpawnDetachedChild)(opts.childArgs);
+    }
+    catch (err) {
+        return { result: 'spawn-failed', error: err };
+    }
+    if (!child.pid) {
+        return { result: 'spawn-failed', error: new Error('Spawned child has no PID') };
+    }
+    const outcome = await pollForSession(opts.appDir, child.pid, opts.expectedAppId, {
+        intervalMs: opts.intervalMs,
+        timeoutMs: opts.timeoutMs,
+        deps: opts.pollDeps,
+        isChildAlive: child.isAlive,
+    });
+    if (outcome.result === 'ready') {
+        return { result: 'started', file: outcome.file };
+    }
+    if (outcome.result === 'wrong-pid') {
+        // Another process wrote a session file with a different PID before
+        // our child did. Our child is still happily running its own dev
+        // setup -- left alone, it will eventually overwrite the winner's
+        // session file with its own PID, defeating the duplicate-session
+        // guard. SIGTERM our child so the winner remains the unique owner.
+        // Best-effort: if the kill fails (race, EPERM), we still surface
+        // wrong-pid -- the user/agent will see two sessions briefly and
+        // can resolve via `runwork dev stop`.
+        try {
+            child.kill('SIGTERM');
+        }
+        catch { /* best-effort */ }
+        return { result: 'wrong-pid', file: outcome.file, ourPid: child.pid };
+    }
+    // For both timeout and child-exited, kill the child (no-op if already
+    // gone), clean up any partial session file we own, and surface the
+    // stderr tail for diagnostics.
+    try {
+        child.kill('SIGTERM');
+    }
+    catch { /* best-effort */ }
+    // Only remove the session file if it's ours -- a wrong-pid race could
+    // have replaced it with the winner's file between our last probe and
+    // here. removeSessionFileIfOwned guards against that.
+    try {
+        removeSessionFileIfOwned(opts.appDir, child.pid);
+    }
+    catch { /* best-effort */ }
+    const childLogTail = readChildStderrTail(opts.appDir);
+    if (outcome.result === 'child-exited') {
+        return { result: 'child-exited', ourPid: child.pid, childLogTail };
+    }
+    return { result: 'timeout', ourPid: child.pid, childLogTail };
+}
+function readChildStderrTail(appDir) {
+    try {
+        const paths = getSessionPaths(appDir);
+        if (!fs.existsSync(paths.stderrLog))
+            return undefined;
+        const raw = fs.readFileSync(paths.stderrLog, 'utf-8');
+        return raw.slice(-2000); // last ~2KB of stderr
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Cross-platform detached self-spawn. Uses `process.execPath` so we never
+ * depend on PATH lookup -- a known failure mode for Bun standalone on
+ * Windows. The child gets the user-supplied args plus the internal child
+ * marker.
+ */
+export function defaultSpawnDetachedChild(childArgs) {
+    const cwd = process.cwd();
+    const { stdoutFd, stderrFd } = openLogFds(cwd);
+    try {
+        const proc = child_process.spawn(process.execPath, childArgs, {
+            cwd,
+            env: process.env,
+            detached: true,
+            stdio: ['ignore', stdoutFd, stderrFd],
+            windowsHide: true,
+        });
+        if (proc.pid !== undefined) {
+            proc.unref();
+        }
+        // Track exit via the 'exit' event. We can't depend on `proc.exitCode`
+        // alone because that's null until the process actually exits.
+        let exited = proc.exitCode !== null || proc.signalCode !== null;
+        proc.on('exit', () => { exited = true; });
+        proc.on('error', () => { exited = true; });
+        return {
+            pid: proc.pid ?? 0,
+            kill: (signal) => proc.kill(signal),
+            isAlive: () => !exited,
+        };
+    }
+    finally {
+        // The child has dup'd these descriptors; the parent should close its
+        // copies so it isn't holding onto the log files. Failure here is
+        // non-fatal -- the FDs will be reaped on parent exit anyway.
+        try {
+            fs.closeSync(stdoutFd);
+        }
+        catch { /* ignore */ }
+        try {
+            fs.closeSync(stderrFd);
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Detect whether the current `runwork dev` invocation is the detached
+ * child. Used by `dev.ts` to pick between the parent-spawn branch and
+ * the actual dev work.
+ */
+export function isInternalDetachedChild(argv = process.argv) {
+    return argv.includes(INTERNAL_DETACHED_CHILD_FLAG);
+}
+/**
+ * Strip the internal marker from a list of args. Used when constructing
+ * the child's args from the parent's own args -- the parent already has
+ * the marker, the child needs it, but we want to avoid duplicates if for
+ * any reason the parent was itself launched with the marker (e.g., a
+ * misconfigured wrapper).
+ */
+export function stripInternalChildFlag(args) {
+    return args.filter((a) => a !== INTERNAL_DETACHED_CHILD_FLAG);
+}
+/**
+ * Detect a Bun standalone virtual-filesystem path. Bun's compile mode
+ * on Windows injects the in-bundle script path as `process.argv[1]`
+ * (e.g., `B:/~BUN/root/runwork-windows-x64.exe`). When we self-spawn,
+ * the child Bun runtime re-injects an equivalent entry on its own --
+ * forwarding ours causes a duplicate that downstream parsers (commander
+ * here) misread as a stray positional command. macOS and Linux Bun
+ * standalone do NOT inject this entry, but the prefix is documented in
+ * Bun source as `/$bunfs/` if it ever appears, so we detect that too
+ * defensively.
+ */
+export function looksLikeBunStandaloneArtifact(p) {
+    // Windows: drive-letter paths under \~BUN\, e.g. "B:/~BUN/root/..." or "B:\~BUN\root\..."
+    if (/^[a-z]:[/\\]~BUN[/\\]/i.test(p))
+        return true;
+    // Linux/macOS bunfs prefix (documented; not currently emitted in user-visible argv).
+    if (p.startsWith('/$bunfs/'))
+        return true;
+    return false;
+}
+/**
+ * Construct the args we should forward to the spawned child so it
+ * re-runs the same `runwork dev` invocation as the parent. Drops
+ * elements that the child runtime will re-inject on its own (notably
+ * the Bun-on-Windows virtual-FS path) and drops any pre-existing copy
+ * of the internal-child marker before we re-add exactly one.
+ *
+ * Pure function for testability -- accepts the parent's argv and returns
+ * what to hand to `spawn`. Real callers pass `process.argv`.
+ */
+export function buildChildArgs(parentArgv) {
+    // argv[0] is always the binary; the child gets it back via spawn's
+    // execPath argument. We start scanning from argv[1].
+    const rest = [];
+    for (let i = 1; i < parentArgv.length; i++) {
+        if (i === 1 && looksLikeBunStandaloneArtifact(parentArgv[i])) {
+            // Skip Bun-on-Windows's auto-injected virtual-FS path; the child
+            // runtime injects its own equivalent entry. Forwarding ours would
+            // duplicate it in the child's argv.
+            continue;
+        }
+        rest.push(parentArgv[i]);
+    }
+    return [...stripInternalChildFlag(rest), INTERNAL_DETACHED_CHILD_FLAG];
+}

package/dist/dev/preview-url-poller.d.ts

@@ -0,0 +1,35 @@
+import type { ApiClient } from '../api/client.js';
+export interface PreviewUrlPollerOptions {
+    client: ApiClient;
+    appId: string;
+    initialUrl: string;
+    /**
+     * Polling interval in ms. Defaults to 15s -- low enough to catch a
+     * sandbox URL rotation within one keypress's worth of attention, high
+     * enough that an idle dev session isn't generating noticeable API load.
+     */
+    intervalMs?: number;
+    onChange: (next: string, prev: string) => void;
+    onError?: (err: unknown) => void;
+}
+export interface PreviewUrlPoller {
+    getCurrent(): string;
+    stop(): void;
+}
+/**
+ * Periodically refreshes the preview URL from `GET /api/dev/status` so the
+ * `runwork dev` UI stays in agreement with `runwork info` even when the
+ * sandbox tunnel rotates mid-session.
+ *
+ * Two intentional behaviours:
+ *
+ *   1. Empty server responses are NOT propagated. The DO clears its
+ *      preview-URL cache to "" while a sandbox is being replaced; flipping
+ *      the status line to empty and back would just be flicker. We keep
+ *      the last known good URL until the server reports a real new one.
+ *
+ *   2. Overlapping ticks are skipped. If a fetch takes longer than the
+ *      interval (slow network, sandbox spin-up), we don't pile up requests
+ *      -- the next tick simply no-ops until the in-flight one resolves.
+ */
+export declare function startPreviewUrlPoller(opts: PreviewUrlPollerOptions): PreviewUrlPoller;

package/dist/dev/preview-url-poller.js

@@ -0,0 +1,50 @@
+/**
+ * Periodically refreshes the preview URL from `GET /api/dev/status` so the
+ * `runwork dev` UI stays in agreement with `runwork info` even when the
+ * sandbox tunnel rotates mid-session.
+ *
+ * Two intentional behaviours:
+ *
+ *   1. Empty server responses are NOT propagated. The DO clears its
+ *      preview-URL cache to "" while a sandbox is being replaced; flipping
+ *      the status line to empty and back would just be flicker. We keep
+ *      the last known good URL until the server reports a real new one.
+ *
+ *   2. Overlapping ticks are skipped. If a fetch takes longer than the
+ *      interval (slow network, sandbox spin-up), we don't pile up requests
+ *      -- the next tick simply no-ops until the in-flight one resolves.
+ */
+export function startPreviewUrlPoller(opts) {
+    let current = opts.initialUrl;
+    const interval = opts.intervalMs ?? 15000;
+    let stopped = false;
+    let inFlight = false;
+    const tick = async () => {
+        if (stopped || inFlight)
+            return;
+        inFlight = true;
+        try {
+            const status = await opts.client.getDevStatus(opts.appId);
+            const next = status.previewUrl ?? '';
+            if (next && next !== current) {
+                const prev = current;
+                current = next;
+                opts.onChange(next, prev);
+            }
+        }
+        catch (err) {
+            opts.onError?.(err);
+        }
+        finally {
+            inFlight = false;
+        }
+    };
+    const handle = setInterval(() => { void tick(); }, interval);
+    return {
+        getCurrent: () => current,
+        stop: () => {
+            stopped = true;
+            clearInterval(handle);
+        },
+    };
+}

package/dist/dev/session.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Per-app `runwork dev` session lifecycle primitives.
+ *
+ * The session file at `<app-dir>/.runwork/dev-session.json` is the durable
+ * truth about whether a dev session is running for the current app, on the
+ * current machine. Every dev-related command reads from it, writes to it,
+ * or treats it as the IPC channel during detach.
+ *
+ * This module is intentionally pure: it does not start, stop, or signal
+ * processes. It only reads/writes the file and reports whether what it
+ * finds is alive, stale, or absent. Callers (dev.ts, dev stop, etc.) act
+ * on that information.
+ *
+ * See `docs/plans/2026-05-06-runwork-dev-lifecycle-design.md` for the full
+ * lifecycle contract.
+ */
+export declare const SESSION_FILE_SCHEMA_VERSION = 1;
+/**
+ * Tolerance (ms) when comparing the stored bootTime to the currently
+ * computed one. NTP corrections can shift `Date.now()` by a few seconds
+ * relative to `os.uptime()`. A reboot is always orders of magnitude
+ * larger than this tolerance.
+ */
+export declare const BOOT_TIME_TOLERANCE_MS = 60000;
+export type SessionMode = 'foreground' | 'detached';
+export interface SessionFile {
+    version: number;
+    pid: number;
+    sessionId: string;
+    appId: string;
+    previewUrl: string;
+    startedAt: number;
+    bootTime: number;
+    cliVersion: string;
+    mode: SessionMode;
+}
+export type SessionStaleReason = 'malformed' | 'version-mismatch' | 'app-id-mismatch' | 'boot-time-mismatch' | 'pid-dead';
+export type SessionState = {
+    state: 'none';
+} | {
+    state: 'alive';
+    file: SessionFile;
+} | {
+    state: 'stale';
+    reason: SessionStaleReason;
+    file?: SessionFile;
+};
+export interface SessionPaths {
+    /** `<app-dir>/.runwork` */
+    dir: string;
+    /** `<app-dir>/.runwork/dev-session.json` */
+    file: string;
+    /** `<app-dir>/.runwork/dev-session.json.tmp` -- staging path for atomic writes */
+    tmpFile: string;
+    /** `<app-dir>/.runwork/dev-stdout.log` -- detached child's stdout sink */
+    stdoutLog: string;
+    /** `<app-dir>/.runwork/dev-stderr.log` -- detached child's stderr sink */
+    stderrLog: string;
+}
+/**
+ * Inject-able dependencies for testing. The defaults call into real OS
+ * primitives. Tests pass overrides to simulate dead PIDs, reboots, or
+ * arbitrary clocks without monkey-patching `process` or `os`.
+ */
+export interface SessionDeps {
+    bootTime?: () => number;
+    pidAlive?: (pid: number) => boolean;
+}
+export declare function getSessionPaths(appDir: string): SessionPaths;
+/**
+ * System boot timestamp in ms. Computed purely from Node's `os.uptime()`
+ * (monotonic seconds since boot, available on every platform Node runs
+ * on) and the wall clock. No spawning, no native modules.
+ *
+ * Drift between `Date.now()` and `os.uptime()` from NTP corrections is
+ * absorbed by `BOOT_TIME_TOLERANCE_MS` at the comparison site.
+ */
+export declare function currentBootTime(): number;
+export declare function isBootTimeStale(stored: number, deps?: SessionDeps): boolean;
+/**
+ * Cross-platform PID liveness probe.
+ *
+ *   - Unix: `process.kill(pid, 0)` is signal-zero, a permissions+existence
+ *     probe. ESRCH for dead, EPERM for "alive but not ours."
+ *   - Windows: Node maps signal 0 to `OpenProcess(PROCESS_QUERY_LIMITED_-`
+ *     `INFORMATION)`. Returns success iff the PID exists and the caller
+ *     has rights, throws otherwise.
+ *
+ * On any error we return `false`. EPERM in particular ("alive but
+ * unprivileged") means the PID belongs to someone else now, so it's not
+ * our session even if it's a real process. The bootTime guard catches the
+ * rare "PID got reused after a reboot, we still own it" case.
+ */
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * Read and parse the session file. Returns `null` for a missing file or
+ * any IO/parse error. The caller decides what "missing" vs "malformed"
+ * means -- use `getSessionState()` for that distinction.
+ */
+export declare function readSessionFile(appDir: string): SessionFile | null;
+/**
+ * Write the session file atomically. Writes to `<file>.tmp` first then
+ * renames into place. POSIX `rename()` and Windows `MoveFileEx` are both
+ * atomic on the same volume, which a sibling temp file always is.
+ *
+ * Creates `.runwork/` if it doesn't exist. The directory is gitignored at
+ * the project-template level.
+ */
+export declare function writeSessionFile(appDir: string, data: SessionFile): void;
+/**
+ * Conditional removal: only deletes the session file when its `pid`
+ * field matches the caller's. Use this from per-process cleanup paths
+ * where another process (e.g., the winner of a startup race) may have
+ * overwritten the file with a different owner. Returns `true` when we
+ * actually removed it.
+ *
+ * `removeSessionFile` is the unconditional primitive; this is the
+ * "be-a-good-citizen" wrapper for in-process cleanup handlers.
+ */
+export declare function removeSessionFileIfOwned(appDir: string, pid: number): boolean;
+/**
+ * Idempotent removal. Missing file is not an error. We also clear any
+ * leftover temp file from a crashed mid-write -- those aren't load-bearing
+ * but they're noise and they confuse `ls -la .runwork/`.
+ */
+export declare function removeSessionFile(appDir: string): void;
+/**
+ * Determine the live state of the session file in the given app directory.
+ *
+ * Checks are ordered cheap-to-expensive. The `pidAlive` syscall is last
+ * so a malformed or wrong-version file short-circuits before we touch
+ * the OS at all.
+ *
+ *   1. File missing                    -> `none`
+ *   2. File malformed / truncated      -> `stale: malformed`
+ *   3. Schema version mismatch         -> `stale: version-mismatch`
+ *   4. App ID mismatch                 -> `stale: app-id-mismatch`
+ *   5. Boot time outside tolerance     -> `stale: boot-time-mismatch`
+ *   6. PID not alive                   -> `stale: pid-dead`
+ *   7. Otherwise                       -> `alive`
+ */
+export declare function getSessionState(appDir: string, expectedAppId: string, deps?: SessionDeps): SessionState;
+/**
+ * Convenience constructor for a fresh session file. Fills in version,
+ * startedAt, and bootTime from the runtime; everything else is supplied
+ * by the caller. Test code can pass a `deps.bootTime` override to inject
+ * a deterministic value.
+ */
+export declare function buildSessionFile(input: {
+    pid: number;
+    sessionId: string;
+    appId: string;
+    previewUrl: string;
+    cliVersion: string;
+    mode: SessionMode;
+    startedAt?: number;
+    deps?: SessionDeps;
+}): SessionFile;