runwork 0.10.2 → 0.10.4

package/dist/dev/attach.js

@@ -0,0 +1,269 @@
+/**
+ * `runwork dev attach` -- read-only join on a running dev session.
+ *
+ * Attach is the handover affordance: an agent starts `runwork dev --detach`,
+ * a human (or another agent) later runs `runwork dev attach` to see the
+ * URL and the live log feed without disturbing the running session.
+ *
+ * Hard rule: attach NEVER kills the session except in response to an
+ * explicit `s` keypress (or `runwork dev stop` in another terminal).
+ * Ctrl+C and `q` exit attach but leave the session running. This is the
+ * inverted cleanup contract from foreground `runwork dev`, so we keep
+ * the keyboard switch local to this module rather than reusing dev.ts's
+ * dispatcher.
+ */
+import * as fs from 'fs';
+import { getSessionPaths, getSessionState, readSessionFile, removeSessionFile, } from './session.js';
+const identityColors = {
+    dim: (s) => s,
+    green: (s) => s,
+    yellow: (s) => s,
+    red: (s) => s,
+    cyan: (s) => s,
+};
+/**
+ * Turn one raw log-file line into a rendered `RenderedEvent`. The line
+ * may be NDJSON (the format the detached child writes) or plain text.
+ *
+ *   - Known NDJSON `event` types get a friendly one-line summary.
+ *   - Unknown JSON shapes pass through as compact JSON with dim styling.
+ *   - Non-JSON text passes through verbatim, with stderr lines reddened.
+ *
+ * Pure function: no I/O, no globals, no color env. Tests pass identity
+ * color fns to assert exact output without ANSI noise.
+ */
+export function renderLogLine(line, source, colors = identityColors) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return { text: line, level: 'info' };
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return {
+            text: source === 'stderr' ? colors.red(line) : line,
+            level: source === 'stderr' ? 'error' : 'info',
+        };
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return { text: colors.dim(JSON.stringify(parsed)), level: 'info' };
+    }
+    const ev = parsed.event;
+    if (typeof ev !== 'string') {
+        return { text: colors.dim(JSON.stringify(parsed)), level: 'info' };
+    }
+    const obj = parsed;
+    switch (ev) {
+        case 'session_started': {
+            const url = typeof obj.previewUrl === 'string' ? obj.previewUrl : '';
+            return {
+                text: colors.green('Dev session started') + (url ? ' ' + colors.dim(`(preview ${url})`) : ''),
+                level: 'info',
+            };
+        }
+        case 'preview_url_changed': {
+            const next = typeof obj.previewUrl === 'string' ? obj.previewUrl : '?';
+            const prev = typeof obj.previousUrl === 'string' ? obj.previousUrl : '?';
+            return {
+                text: colors.yellow('Preview URL changed') + ' ' + colors.dim(`${prev} -> ${next}`),
+                level: 'warn',
+            };
+        }
+        case 'files_synced': {
+            const count = typeof obj.count === 'number' ? obj.count : 0;
+            const target = typeof obj.target === 'string' ? obj.target : 'preview';
+            return { text: colors.cyan(`Synced ${count} file(s) -> ${target}`), level: 'info' };
+        }
+        case 'files_pushed': {
+            const count = typeof obj.count === 'number' ? obj.count : 0;
+            return { text: colors.cyan(`Pushed ${count} file(s) -> git`), level: 'info' };
+        }
+        case 'startup': {
+            const phase = typeof obj.phase === 'string' ? obj.phase : '';
+            return { text: colors.dim(`[startup] ${phase}`), level: 'info' };
+        }
+        case 'sync_restored_critical_files': {
+            const files = Array.isArray(obj.files) ? obj.files.filter((f) => typeof f === 'string').join(', ') : '';
+            return { text: colors.yellow(`Restored critical files: ${files}`), level: 'warn' };
+        }
+        case 'error': {
+            const errObj = obj.error;
+            const msg = typeof errObj?.message === 'string' ? errObj.message : 'unknown error';
+            const phase = typeof obj.phase === 'string' ? obj.phase : 'unknown';
+            const diag = typeof errObj?.diagnosis === 'string' ? `\n  ${colors.dim(errObj.diagnosis)}` : '';
+            return { text: colors.red(`ERROR (${phase}): ${msg}${diag}`), level: 'error' };
+        }
+        default:
+            return { text: colors.dim(JSON.stringify(parsed)), level: 'info' };
+    }
+}
+/**
+ * Poll-based tail of stdout/stderr log files. Cross-platform by design
+ * (no `fs.watch`, no native deps, identical behavior on macOS/Linux/
+ * Windows). Reads the last `initialLines` lines on start to give the
+ * attaching user immediate context, then watches for appends.
+ */
+export function startLogTail(stdoutPath, stderrPath, opts) {
+    const intervalMs = opts.intervalMs ?? 500;
+    const initialLines = opts.initialLines ?? 50;
+    let stopped = false;
+    const offsets = { stdout: 0, stderr: 0 };
+    const paths = { stdout: stdoutPath, stderr: stderrPath };
+    // Initial replay: last N lines from each file (most recent at the bottom).
+    for (const source of ['stdout', 'stderr']) {
+        const p = paths[source];
+        if (!fs.existsSync(p))
+            continue;
+        try {
+            const stat = fs.statSync(p);
+            const buf = fs.readFileSync(p, 'utf-8');
+            const lines = buf.split('\n');
+            // Strip the trailing empty entry from a final `\n`.
+            const cleaned = lines[lines.length - 1] === '' ? lines.slice(0, -1) : lines;
+            const tail = cleaned.slice(-initialLines);
+            for (const line of tail) {
+                opts.onLine(line, source);
+            }
+            offsets[source] = stat.size;
+        }
+        catch (err) {
+            opts.onError?.(err);
+        }
+    }
+    const tickOne = (source) => {
+        const p = paths[source];
+        if (!fs.existsSync(p))
+            return;
+        let stat;
+        try {
+            stat = fs.statSync(p);
+        }
+        catch (err) {
+            opts.onError?.(err);
+            return;
+        }
+        if (stat.size < offsets[source]) {
+            // Truncation: a new dev session started and re-opened the log file
+            // in 'w' mode. Tell the caller; they decide whether to exit or
+            // reset offsets and continue.
+            opts.onTruncated?.();
+            offsets[source] = 0;
+            return;
+        }
+        if (stat.size === offsets[source])
+            return;
+        try {
+            const fd = fs.openSync(p, 'r');
+            try {
+                const length = stat.size - offsets[source];
+                const buf = Buffer.alloc(length);
+                fs.readSync(fd, buf, 0, length, offsets[source]);
+                offsets[source] = stat.size;
+                const text = buf.toString('utf-8');
+                const lines = text.split('\n');
+                const cleaned = lines[lines.length - 1] === '' ? lines.slice(0, -1) : lines;
+                for (const line of cleaned) {
+                    opts.onLine(line, source);
+                }
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch (err) {
+            opts.onError?.(err);
+        }
+    };
+    const handle = setInterval(() => {
+        if (stopped)
+            return;
+        tickOne('stdout');
+        tickOne('stderr');
+    }, intervalMs);
+    return {
+        stop: () => {
+            stopped = true;
+            clearInterval(handle);
+        },
+    };
+}
+/**
+ * Format a "started X ago" string for human display. Pure function, no
+ * locale handling -- this is a developer tool, not a UI.
+ */
+export function formatStartedAgo(startedAt, now = Date.now()) {
+    const sec = Math.max(0, Math.round((now - startedAt) / 1000));
+    if (sec < 60)
+        return `${sec}s ago`;
+    if (sec < 3600)
+        return `${Math.floor(sec / 60)}m ago`;
+    return `${Math.floor(sec / 3600)}h ago`;
+}
+export function startSessionFileWatch(appDir, initial, opts) {
+    const intervalMs = opts.intervalMs ?? 2_000;
+    let stopped = false;
+    let lastUrl = initial.previewUrl;
+    const lastPid = initial.pid;
+    const handle = setInterval(() => {
+        if (stopped)
+            return;
+        const file = readSessionFile(appDir);
+        if (!file) {
+            // The file disappeared. Either the session ended cleanly (its
+            // cleanup handler removed it) or someone called `dev stop`. Either
+            // way, the session this attach was tracking is gone.
+            opts.onSessionGone?.();
+            return;
+        }
+        if (file.appId !== opts.expectedAppId || file.pid !== lastPid) {
+            // A different session took over (e.g., user did `dev --restart`
+            // somewhere). Treat the original session as gone -- attach was
+            // following a specific PID, not the whole app.
+            opts.onSessionGone?.();
+            return;
+        }
+        if (file.previewUrl && file.previewUrl !== lastUrl) {
+            const prev = lastUrl;
+            lastUrl = file.previewUrl;
+            opts.onUrlChanged?.(file.previewUrl, prev);
+        }
+    }, intervalMs);
+    return {
+        stop: () => {
+            stopped = true;
+            clearInterval(handle);
+        },
+    };
+}
+/**
+ * Resolve what attach can/should do based on the session file alone.
+ * Pure logic; the caller decides what to render and whether to keep
+ * running. Split out so the resolution can be unit-tested separately
+ * from the long-running tail loop.
+ */
+export function resolveAttachTarget(appDir, expectedAppId) {
+    const state = getSessionState(appDir, expectedAppId);
+    if (state.state === 'none')
+        return { result: 'no-session' };
+    if (state.state === 'stale') {
+        removeSessionFile(appDir);
+        return { result: 'stale-cleaned', reason: state.reason };
+    }
+    return { result: 'attached', file: state.file };
+}
+/**
+ * Helper exposed for the orchestrator: returns the current preview URL
+ * the user should "open" if they press `o`. We re-read the session file
+ * each time so URL rotations are honored without plumbing watchers
+ * through the keyboard handler.
+ */
+export function getCurrentPreviewUrl(appDir, fallback) {
+    const file = readSessionFile(appDir);
+    return file?.previewUrl || fallback;
+}
+/** Convenience: the log file paths for the given app dir. */
+export function getAttachLogPaths(appDir) {
+    const paths = getSessionPaths(appDir);
+    return { stdout: paths.stdoutLog, stderr: paths.stderrLog };
+}

package/dist/dev/detach.d.ts

@@ -0,0 +1,187 @@
+/**
+ * `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 { type SessionDeps, type SessionFile } 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 declare const INTERNAL_DETACHED_CHILD_FLAG = "--internal-detached-child";
+export type PollOutcome = {
+    result: 'ready';
+    file: SessionFile;
+} | {
+    result: 'timeout';
+} | {
+    result: 'wrong-pid';
+    file: SessionFile;
+} | {
+    result: 'child-exited';
+};
+export interface PollDeps extends SessionDeps {
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * 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 declare function pollForSession(appDir: string, expectedPid: number, expectedAppId: string, opts?: {
+    intervalMs?: number;
+    timeoutMs?: number;
+    deps?: PollDeps;
+    /**
+     * Optional: probe whether the spawned child is still running. If
+     * provided and it ever returns false, polling aborts immediately
+     * with `child-exited`. Lets the caller distinguish "child died
+     * before writing the file" (fast fail, ~one tick) from "child is
+     * just slow" (wait for timeout). Without this hook the parent
+     * would hang for the full timeout on a fast-failing child.
+     */
+    isChildAlive?: () => boolean;
+}): Promise<PollOutcome>;
+/**
+ * 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 declare function openLogFds(appDir: string): {
+    stdoutFd: number;
+    stderrFd: number;
+};
+export interface SpawnedChildHandle {
+    pid: number;
+    kill: (signal?: NodeJS.Signals) => boolean;
+    /**
+     * Returns false once the child has exited. Lets `pollForSession`
+     * abort early instead of waiting the full timeout when the child
+     * fails fast (missing auth, sync conflict, sandbox-boot error).
+     */
+    isAlive: () => boolean;
+}
+export interface DetachParentOptions {
+    appDir: string;
+    expectedAppId: string;
+    childArgs: string[];
+    intervalMs?: number;
+    timeoutMs?: number;
+    /**
+     * Optional spawn override for tests. Real callers pass nothing and get
+     * the cross-platform spawn defined below.
+     */
+    spawn?: (args: string[]) => SpawnedChildHandle;
+    pollDeps?: PollDeps;
+}
+export type DetachParentOutcome = {
+    result: 'started';
+    file: SessionFile;
+} | {
+    result: 'wrong-pid';
+    file: SessionFile;
+    ourPid: number;
+} | {
+    result: 'timeout';
+    ourPid: number;
+    childLogTail?: string;
+} | {
+    result: 'child-exited';
+    ourPid: number;
+    childLogTail?: string;
+} | {
+    result: 'spawn-failed';
+    error: unknown;
+};
+/**
+ * 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 declare function runAsDetachedParent(opts: DetachParentOptions): Promise<DetachParentOutcome>;
+/**
+ * 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 declare function defaultSpawnDetachedChild(childArgs: string[]): SpawnedChildHandle;
+/**
+ * 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 declare function isInternalDetachedChild(argv?: readonly string[]): boolean;
+/**
+ * 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 declare function stripInternalChildFlag(args: readonly string[]): string[];
+/**
+ * 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 declare function looksLikeBunStandaloneArtifact(p: string): boolean;
+/**
+ * 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 declare function buildChildArgs(parentArgv: readonly string[]): string[];