runwork 0.15.0 → 0.15.2

package/dist/dev/attach.d.ts

@@ -1,120 +0,0 @@
-/**
- * `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 { type SessionFile } from './session.js';
-export interface RenderedEvent {
-    /** Pre-styled human-readable line ready to print to a TTY. */
-    text: string;
-    /** Severity hint, useful for filtering or color. */
-    level: 'info' | 'warn' | 'error';
-}
-interface ColorFns {
-    dim: (s: string) => string;
-    green: (s: string) => string;
-    yellow: (s: string) => string;
-    red: (s: string) => string;
-    cyan: (s: string) => string;
-}
-/**
- * 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 declare function renderLogLine(line: string, source: 'stdout' | 'stderr', colors?: ColorFns): RenderedEvent;
-export interface LogTailOptions {
-    /** Number of trailing lines to replay on attach. Default 50. */
-    initialLines?: number;
-    /** Poll interval. Default 500ms. */
-    intervalMs?: number;
-    /** Called for each new line. */
-    onLine: (line: string, source: 'stdout' | 'stderr') => void;
-    /**
-     * Called when we detect file truncation (size shrunk) on either file.
-     * The orchestrator decides whether this is a "session restarted -- exit
-     * attach" or "spurious -- reset and continue."
-     */
-    onTruncated?: () => void;
-    onError?: (err: unknown) => void;
-}
-export interface LogTail {
-    stop(): void;
-}
-/**
- * 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 declare function startLogTail(stdoutPath: string, stderrPath: string, opts: LogTailOptions): LogTail;
-/**
- * Format a "started X ago" string for human display. Pure function, no
- * locale handling -- this is a developer tool, not a UI.
- */
-export declare function formatStartedAgo(startedAt: number, now?: number): string;
-/**
- * Watch the session file for `previewUrl` rotations or for the file
- * disappearing (the session ended). Polls instead of `fs.watch` for
- * cross-platform consistency.
- */
-export interface SessionWatchOptions {
-    intervalMs?: number;
-    expectedAppId: string;
-    onUrlChanged?: (next: string, prev: string) => void;
-    onSessionGone?: () => void;
-    onError?: (err: unknown) => void;
-}
-export interface SessionWatch {
-    stop(): void;
-}
-export declare function startSessionFileWatch(appDir: string, initial: SessionFile, opts: SessionWatchOptions): SessionWatch;
-/**
- * Result returned to `dev.ts` so it can pick a top-level message + exit
- * code. The orchestrator function never calls `process.exit` itself --
- * tests can drive it without spawning a child.
- */
-export type AttachResult = {
-    result: 'no-session';
-} | {
-    result: 'stale-cleaned';
-    reason: string;
-} | {
-    result: 'attached';
-    file: SessionFile;
-};
-/**
- * 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 declare function resolveAttachTarget(appDir: string, expectedAppId: string): AttachResult;
-/**
- * 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 declare function getCurrentPreviewUrl(appDir: string, fallback: string): string;
-/** Convenience: the log file paths for the given app dir. */
-export declare function getAttachLogPaths(appDir: string): {
-    stdout: string;
-    stderr: string;
-};
-export {};

package/dist/dev/attach.js

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

@@ -1,187 +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 { 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[];