runwork 0.15.1 → 0.15.2

package/dist/dev/session.js

@@ -1,258 +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 * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-export 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 const BOOT_TIME_TOLERANCE_MS = 60_000;
-const realDeps = {
-    bootTime: currentBootTime,
-    pidAlive: isPidAlive,
-};
-/**
- * Resolve a `SessionDeps` against the real defaults, ignoring any
- * `undefined` values in the caller-supplied object. Spreading
- * `{ ...realDeps, ...deps }` directly would let `{ bootTime: undefined }`
- * overwrite the real default with `undefined`, which then crashes when we
- * try to call it. This helper keeps the defaults intact.
- */
-function resolveDeps(deps) {
-    if (!deps)
-        return realDeps;
-    return {
-        bootTime: deps.bootTime ?? realDeps.bootTime,
-        pidAlive: deps.pidAlive ?? realDeps.pidAlive,
-    };
-}
-export function getSessionPaths(appDir) {
-    const dir = path.join(appDir, '.runwork');
-    return {
-        dir,
-        file: path.join(dir, 'dev-session.json'),
-        tmpFile: path.join(dir, 'dev-session.json.tmp'),
-        stdoutLog: path.join(dir, 'dev-stdout.log'),
-        stderrLog: path.join(dir, 'dev-stderr.log'),
-    };
-}
-/**
- * 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 function currentBootTime() {
-    return Date.now() - os.uptime() * 1000;
-}
-export function isBootTimeStale(stored, deps = {}) {
-    const d = resolveDeps(deps);
-    return Math.abs(d.bootTime() - stored) > BOOT_TIME_TOLERANCE_MS;
-}
-/**
- * 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 function isPidAlive(pid) {
-    if (!Number.isInteger(pid) || pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Validate that a parsed value matches `SessionFile`. Catches schema drift,
- * truncated writes, and tampered files. Anything other than a perfect match
- * is reported as `malformed` -- we don't try to repair partial files.
- */
-function validateSessionFile(raw) {
-    if (!raw || typeof raw !== 'object')
-        return false;
-    const r = raw;
-    return (typeof r.version === 'number' &&
-        typeof r.pid === 'number' &&
-        typeof r.sessionId === 'string' &&
-        typeof r.appId === 'string' &&
-        typeof r.previewUrl === 'string' &&
-        typeof r.startedAt === 'number' &&
-        typeof r.bootTime === 'number' &&
-        typeof r.cliVersion === 'string' &&
-        (r.mode === 'foreground' || r.mode === 'detached') &&
-        // Optional for back-compat: v1 files lack the field. Accept absent or boolean.
-        (r.noSync === undefined || typeof r.noSync === 'boolean') &&
-        // Optional: absent on older files; otherwise an object (shape from buildStartupSyncSummary).
-        (r.startupSync === undefined || (typeof r.startupSync === 'object' && r.startupSync !== null)));
-}
-/**
- * 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 function readSessionFile(appDir) {
-    const { file } = getSessionPaths(appDir);
-    let raw;
-    try {
-        raw = fs.readFileSync(file, 'utf-8');
-    }
-    catch {
-        return null;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-    if (!validateSessionFile(parsed))
-        return null;
-    return parsed;
-}
-/**
- * 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 function writeSessionFile(appDir, data) {
-    const paths = getSessionPaths(appDir);
-    fs.mkdirSync(paths.dir, { recursive: true });
-    // We hold the JSON in memory before writing, so a serialization error
-    // never leaves a half-written tmp file on disk.
-    const json = JSON.stringify(data, null, 2);
-    fs.writeFileSync(paths.tmpFile, json, { encoding: 'utf-8' });
-    fs.renameSync(paths.tmpFile, paths.file);
-}
-/**
- * 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 function removeSessionFileIfOwned(appDir, pid) {
-    const file = readSessionFile(appDir);
-    if (!file)
-        return false;
-    if (file.pid !== pid)
-        return false;
-    removeSessionFile(appDir);
-    return true;
-}
-/**
- * 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 function removeSessionFile(appDir) {
-    const { file, tmpFile } = getSessionPaths(appDir);
-    for (const p of [file, tmpFile]) {
-        try {
-            fs.unlinkSync(p);
-        }
-        catch {
-            // ENOENT is the happy path; any other error is also intentionally
-            // swallowed -- removal is best-effort cleanup, not a load-bearing
-            // step. The next `runwork dev` will detect a stale file via the
-            // PID/bootTime checks regardless.
-        }
-    }
-}
-/**
- * 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 function getSessionState(appDir, expectedAppId, deps = {}) {
-    const { file: filePath } = getSessionPaths(appDir);
-    if (!fs.existsSync(filePath))
-        return { state: 'none' };
-    const file = readSessionFile(appDir);
-    if (!file)
-        return { state: 'stale', reason: 'malformed' };
-    if (file.version !== SESSION_FILE_SCHEMA_VERSION) {
-        return { state: 'stale', reason: 'version-mismatch', file };
-    }
-    if (file.appId !== expectedAppId) {
-        return { state: 'stale', reason: 'app-id-mismatch', file };
-    }
-    if (isBootTimeStale(file.bootTime, deps)) {
-        return { state: 'stale', reason: 'boot-time-mismatch', file };
-    }
-    const d = resolveDeps(deps);
-    if (!d.pidAlive(file.pid)) {
-        return { state: 'stale', reason: 'pid-dead', file };
-    }
-    return { state: 'alive', file };
-}
-/**
- * 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 function buildSessionFile(input) {
-    const d = resolveDeps(input.deps);
-    return {
-        version: SESSION_FILE_SCHEMA_VERSION,
-        pid: input.pid,
-        sessionId: input.sessionId,
-        appId: input.appId,
-        previewUrl: input.previewUrl,
-        startedAt: input.startedAt ?? Date.now(),
-        bootTime: d.bootTime(),
-        cliVersion: input.cliVersion,
-        mode: input.mode,
-        noSync: input.noSync ?? false,
-        ...(input.startupSync ? { startupSync: input.startupSync } : {}),
-    };
-}

package/dist/dev/startup-sync.d.ts

@@ -1,23 +0,0 @@
-import type { SyncResult } from '../git/sync.js';
-/**
- * Summary of the startup sync outcome, surfaced on the `session_started`
- * event so agents can tell whether the preview reflects their latest edits.
- * `staleCode` is the key signal: when true, the initial sync failed and the
- * preview is serving the last good state, NOT the current working tree
- * (friction log #2).
- */
-export interface StartupSyncSummary {
-    syncStatus: SyncResult['status'] | 'no-sync';
-    syncFailed: boolean;
-    staleCode: boolean;
-}
-/**
- * Derive the startup sync summary from how dev started:
- * - no-sync mode never mutates the tree, so it's neither failed nor stale.
- * - otherwise it mirrors the syncWithRemote() status; a `sync-failed` status
- *   means the preview is stale.
- */
-export declare function buildStartupSyncSummary(input: {
-    noSync: boolean;
-    status?: SyncResult['status'];
-}): StartupSyncSummary;

package/dist/dev/startup-sync.js

@@ -1,14 +0,0 @@
-/**
- * Derive the startup sync summary from how dev started:
- * - no-sync mode never mutates the tree, so it's neither failed nor stale.
- * - otherwise it mirrors the syncWithRemote() status; a `sync-failed` status
- *   means the preview is stale.
- */
-export function buildStartupSyncSummary(input) {
-    if (input.noSync) {
-        return { syncStatus: 'no-sync', syncFailed: false, staleCode: false };
-    }
-    const status = input.status ?? 'skipped';
-    const failed = status === 'sync-failed';
-    return { syncStatus: status, syncFailed: failed, staleCode: failed };
-}

package/dist/dev/stop.d.ts

@@ -1,52 +0,0 @@
-/**
- * Stop a running dev session, identified by the on-disk session file.
- *
- * Termination is platform-aware but the design does NOT depend on the
- * child's cleanup handler running. We always remove the session file
- * ourselves at the end so the next `runwork dev` invocation sees a clean
- * slate even on Windows (no SIGTERM equivalent) or on a kill-9'd Unix
- * process.
- */
-import { type SessionDeps, type SessionStaleReason } from './session.js';
-export type StopOutcome = {
-    result: 'no-session';
-} | {
-    result: 'stale-cleaned';
-    reason: SessionStaleReason;
-    pid?: number;
-} | {
-    result: 'stopped';
-    pid: number;
-    gracefully: boolean;
-} | {
-    result: 'kill-failed';
-    pid: number;
-    error: unknown;
-};
-export interface StopDeps extends SessionDeps {
-    killProcess?: (pid: number, signal?: NodeJS.Signals | 0) => void;
-    sleep?: (ms: number) => Promise<void>;
-    platform?: NodeJS.Platform;
-    /**
-     * Maximum total time to wait for the SIGTERM'd child to exit gracefully
-     * before falling back to SIGKILL. Unix-only; ignored on Windows.
-     */
-    graceTimeoutMs?: number;
-    /** Polling interval while waiting for the process to die. */
-    pollIntervalMs?: number;
-}
-/**
- * Stop a dev session that may or may not exist for the given app dir.
- *
- *   - `state: 'none'`  -> exit-code-0 no-op, no session to stop.
- *   - `state: 'stale'` -> remove the file, no kill needed (the PID is
- *     either dead, mismatched, or a different app altogether).
- *   - `state: 'alive'` -> Unix: SIGTERM, wait up to graceTimeoutMs,
- *     SIGKILL fallback. Windows: TerminateProcess (signal-less kill);
- *     Node has no graceful-shutdown signal that survives the cross-process
- *     boundary on Windows.
- *
- * In every "found a file" path the file is removed before returning, so
- * the next `runwork dev` sees a clean slate regardless of how things went.
- */
-export declare function stopSession(appDir: string, expectedAppId: string, deps?: StopDeps): Promise<StopOutcome>;

package/dist/dev/stop.js

@@ -1,101 +0,0 @@
-/**
- * Stop a running dev session, identified by the on-disk session file.
- *
- * Termination is platform-aware but the design does NOT depend on the
- * child's cleanup handler running. We always remove the session file
- * ourselves at the end so the next `runwork dev` invocation sees a clean
- * slate even on Windows (no SIGTERM equivalent) or on a kill-9'd Unix
- * process.
- */
-import { getSessionPaths, getSessionState, isPidAlive as defaultIsPidAlive, removeSessionFile, } from './session.js';
-import * as fs from 'fs';
-const defaultStopDeps = {
-    killProcess: (pid, signal) => {
-        process.kill(pid, signal);
-    },
-    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
-    platform: process.platform,
-    graceTimeoutMs: 5_000,
-    pollIntervalMs: 100,
-};
-/**
- * Stop a dev session that may or may not exist for the given app dir.
- *
- *   - `state: 'none'`  -> exit-code-0 no-op, no session to stop.
- *   - `state: 'stale'` -> remove the file, no kill needed (the PID is
- *     either dead, mismatched, or a different app altogether).
- *   - `state: 'alive'` -> Unix: SIGTERM, wait up to graceTimeoutMs,
- *     SIGKILL fallback. Windows: TerminateProcess (signal-less kill);
- *     Node has no graceful-shutdown signal that survives the cross-process
- *     boundary on Windows.
- *
- * In every "found a file" path the file is removed before returning, so
- * the next `runwork dev` sees a clean slate regardless of how things went.
- */
-export async function stopSession(appDir, expectedAppId, deps = {}) {
-    const d = { ...defaultStopDeps, ...deps };
-    // StopDeps extends SessionDeps, so we can pass `deps` straight through
-    // to getSessionState. Constructing a separate `{ bootTime, pidAlive }`
-    // object would smuggle in `undefined` values when the caller didn't
-    // override them, which then overwrite the real defaults in getSessionState's
-    // own spread. Forwarding the object as-is keeps the defaults intact.
-    const state = getSessionState(appDir, expectedAppId, deps);
-    if (state.state === 'none') {
-        return { result: 'no-session' };
-    }
-    if (state.state === 'stale') {
-        removeSessionFile(appDir);
-        return { result: 'stale-cleaned', reason: state.reason, pid: state.file?.pid };
-    }
-    const { file } = state;
-    const pid = file.pid;
-    // Unix: SIGTERM, wait, SIGKILL fallback.
-    // Windows: signal-less kill (== TerminateProcess via Node).
-    const isWindows = d.platform === 'win32';
-    const livenessProbe = deps.pidAlive ?? defaultIsPidAlive;
-    try {
-        if (isWindows) {
-            d.killProcess(pid);
-        }
-        else {
-            d.killProcess(pid, 'SIGTERM');
-        }
-    }
-    catch (err) {
-        // Even if the kill failed (PID died between state-read and kill, or
-        // permission denied), we still want to remove the file so the user
-        // isn't stuck. Surface the error as a warning-grade outcome, but
-        // clean up.
-        removeSessionFile(appDir);
-        return { result: 'kill-failed', pid, error: err };
-    }
-    let gracefully = false;
-    if (!isWindows) {
-        const deadline = Date.now() + d.graceTimeoutMs;
-        while (Date.now() < deadline) {
-            if (!livenessProbe(pid)) {
-                gracefully = true;
-                break;
-            }
-            // The child cleans up its own session file on SIGTERM, so the file
-            // disappearing is also an acceptable "we're done" signal.
-            if (!fs.existsSync(getSessionPaths(appDir).file)) {
-                gracefully = true;
-                break;
-            }
-            await d.sleep(d.pollIntervalMs);
-        }
-        if (!gracefully) {
-            try {
-                d.killProcess(pid, 'SIGKILL');
-            }
-            catch {
-                // Already dead, race-condition'd, or no permission. Either way,
-                // we proceed to remove the file -- the goal is "this session is
-                // gone from this machine's perspective."
-            }
-        }
-    }
-    removeSessionFile(appDir);
-    return { result: 'stopped', pid, gracefully };
-}

package/dist/devtools/registry-data.d.ts

@@ -1,46 +0,0 @@
-/**
- * Developer tool registry — non-AI prerequisites Runwork users need installed
- * locally (git today, more later if needed).
- *
- * Extends the shared `InstallableTool` base so the desktop can detect and
- * render devtools alongside AI agents using the same icon/detection plumbing.
- *
- * Browser-safe: no node-only imports.
- */
-import type { InstallableTool } from '../tools/types.js';
-/**
- * How the desktop should attempt to install the tool. Each platform either
- * has an automated install command (run via the platform shell) or falls
- * back to opening the tool's `downloadUrl` in the browser.
- */
-export type DevToolInstallStrategy = {
-    kind: 'shell';
-    shell: 'powershell' | 'zsh' | 'bash';
-    command: string;
-    postInstallNote?: string;
-} | {
-    kind: 'open-url';
-    url: string;
-};
-export interface DevToolDefinition extends InstallableTool {
-    /** Beginner-friendly explanation shown in the install card. */
-    longDescription: string;
-    /**
-     * When true, the desktop must block onboarding "Continue" until this tool
-     * is detected (or explicitly skipped only after an attempted install).
-     * Use sparingly: this is reserved for tools whose absence guarantees the
-     * core CLI loop (init / clone / dev / deploy) will fail.
-     */
-    required?: boolean;
-    /**
-     * Per-platform install strategy. Missing platforms fall back to opening
-     * `downloadUrl` in the browser.
-     */
-    install: {
-        macos?: DevToolInstallStrategy;
-        windows?: DevToolInstallStrategy;
-        linux?: DevToolInstallStrategy;
-    };
-}
-export declare function getDevTools(): DevToolDefinition[];
-export declare function getDevTool(slug: string): DevToolDefinition | undefined;

package/dist/devtools/registry-data.js

@@ -1,40 +0,0 @@
-/**
- * Developer tool registry — non-AI prerequisites Runwork users need installed
- * locally (git today, more later if needed).
- *
- * Extends the shared `InstallableTool` base so the desktop can detect and
- * render devtools alongside AI agents using the same icon/detection plumbing.
- *
- * Browser-safe: no node-only imports.
- */
-const DEV_TOOL_REGISTRY = [
-    {
-        slug: 'git',
-        name: 'Git',
-        description: 'Version control system',
-        longDescription: 'Git tracks changes to your code and is required for Runwork commands that sync your work with the platform (init, clone, dev, deploy).',
-        required: true,
-        detection: { method: 'binary', target: 'git' },
-        downloadUrl: 'https://git-scm.com/downloads',
-        install: {
-            windows: {
-                kind: 'shell',
-                shell: 'powershell',
-                command: 'winget install --id Git.Git -e --source winget --accept-package-agreements --accept-source-agreements',
-            },
-            macos: {
-                kind: 'shell',
-                shell: 'zsh',
-                command: 'xcode-select --install',
-                postInstallNote: 'A macOS installer window has opened. Finish the install there, then click Re-detect.',
-            },
-            linux: { kind: 'open-url', url: 'https://git-scm.com/download/linux' },
-        },
-    },
-];
-export function getDevTools() {
-    return DEV_TOOL_REGISTRY;
-}
-export function getDevTool(slug) {
-    return DEV_TOOL_REGISTRY.find((t) => t.slug === slug);
-}

package/dist/generated/bundled-types.d.ts

@@ -1 +0,0 @@
-export declare const BUNDLED_TYPES: Record<string, string>;