runwork 0.15.0 → 0.15.2

package/dist/dev/detach.js

@@ -1,292 +0,0 @@
-/**
- * `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

@@ -1,35 +0,0 @@
-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

@@ -1,50 +0,0 @@
-/**
- * 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

@@ -1,175 +0,0 @@
-/**
- * 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.
- */
-import type { StartupSyncSummary } from './startup-sync.js';
-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;
-    /**
-     * Whether this session runs in no-sync mode (no file watcher, no
-     * auto-commit, no working-tree-mutating startup). Optional for
-     * back-compat with v1 session files that predate the field; absent is
-     * treated as `false`.
-     */
-    noSync?: boolean;
-    /**
-     * Startup sync outcome, so a detached parent can relay stale-code warnings
-     * to the caller instead of those signals only living in the child's log
-     * (friction log #2). Optional for back-compat with session files that
-     * predate the field.
-     */
-    startupSync?: StartupSyncSummary;
-}
-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;
-    noSync?: boolean;
-    startupSync?: StartupSyncSummary;
-    startedAt?: number;
-    deps?: SessionDeps;
-}): SessionFile;