@repo-os/repoos 0.5.45

package/dist/commands/screenshots.d.ts

@@ -0,0 +1,7 @@
+export declare const SHOTS_DIR = "screenshots";
+export declare const HASH_FILE: string;
+export declare const SCREENSHOT_NAMES: readonly ["dashboard.png", "work-board.png", "task-drawer.png", "docs-context.png", "settings.png"];
+/** Hash of everything that determines the committed screenshots. */
+export declare function screenshotsHash(root: string): string | null;
+/** True when committed screenshots do not match the current UI source. */
+export declare function screenshotsStale(root: string): boolean;

package/dist/commands/screenshots.js

@@ -0,0 +1,77 @@
+/**
+ * Screenshot freshness guard — shared between `repoos check` and
+ * `scripts/capture-screenshots.mjs`.
+ *
+ * The committed PNGs under `screenshots/` are generated by the capture script
+ * against a controlled fixture repo. This module defines what "fresh" means:
+ * a sha256 over the UI source tree, the fixture repo, the capture script, AND
+ * the committed PNGs themselves, compared against the marker the generator
+ * writes to `screenshots/.ui-hash`. Any drift fails the `repoos check` gate so
+ * the screenshots cannot silently rot.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+export const SHOTS_DIR = "screenshots";
+export const HASH_FILE = join(SHOTS_DIR, ".ui-hash");
+export const SCREENSHOT_NAMES = [
+    "dashboard.png",
+    "work-board.png",
+    "task-drawer.png",
+    "docs-context.png",
+    "settings.png",
+];
+/** Relative paths (sorted) that feed the freshness hash. */
+function uiSources(root) {
+    const dirs = ["src/ui-app", "scripts/screenshot-fixtures"];
+    const extraFiles = [
+        "scripts/capture-screenshots.mjs",
+        ...SCREENSHOT_NAMES.map((n) => join(SHOTS_DIR, n)),
+    ];
+    const out = [];
+    const walk = (dir) => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            const p = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (e.name === "node_modules" || e.name === "dist")
+                    continue;
+                walk(p);
+            }
+            else {
+                out.push(p);
+            }
+        }
+    };
+    for (const d of dirs) {
+        if (existsSync(join(root, d)))
+            walk(join(root, d));
+    }
+    for (const f of extraFiles) {
+        if (existsSync(join(root, f)))
+            out.push(join(root, f));
+    }
+    return out.sort();
+}
+/** Hash of everything that determines the committed screenshots. */
+export function screenshotsHash(root) {
+    if (!existsSync(join(root, "src/ui-app")))
+        return null;
+    const hash = createHash("sha256");
+    for (const f of uiSources(root)) {
+        if (!statSync(f).isFile())
+            continue;
+        hash.update(f.slice(root.length + 1));
+        hash.update("\u0000");
+        hash.update(readFileSync(f));
+    }
+    return hash.digest("hex");
+}
+/** True when committed screenshots do not match the current UI source. */
+export function screenshotsStale(root) {
+    const marker = join(root, HASH_FILE);
+    if (!existsSync(marker))
+        return true;
+    const recorded = readFileSync(marker, "utf8").trim();
+    const current = screenshotsHash(root);
+    return current === null || recorded !== current;
+}

package/dist/commands/serve.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The OS-visible process title for a `repoos serve` instance:
+ * `repoos-<project>`, where `<project>` is the managed root's directory name.
+ * This is the same display name the rest of RepoOS uses (`basename(root)` — the
+ * PWA manifest, login emails, the instance icon), so `ps`/Activity Monitor can
+ * tell which project an instance belongs to without `lsof`/`/api/config`.
+ */
+export declare function serveProcessTitle(root?: string): string;
+type ExecveFn = (file: string, args: readonly string[], env: NodeJS.ProcessEnv) => never;
+/**
+ * Set the OS-visible process title so `ps`/Activity Monitor name the project.
+ *
+ * Node's `process.title` writes through to the OS directly, but Bun's does NOT
+ * (verified on 1.3.x/macOS: the JS property sticks but the kernel argv is
+ * untouched, so `ps` still shows `bun … serve`). The mechanism that does work
+ * under Bun is `process.execve` — a true exec (same PID, same cwd, same stdio)
+ * with a custom argv[0] — so we re-exec once, guarded by {@link TITLE_GUARD}.
+ * On the relabeled second pass the marker is deleted immediately, before any
+ * child is spawned, so reload replacements and preview children start clean and
+ * relabel themselves instead of inheriting a stale "already titled" flag.
+ *
+ * `execve` is injectable purely so tests can observe the call without replacing
+ * the test runner's own process image.
+ */
+export declare function setServeProcessTitle(title: string, execve?: ExecveFn | undefined): void;
+/**
+ * Picks the bind host: an explicit `--host` always wins; otherwise, if
+ * Tailscale is running on this machine, default to 0.0.0.0 (all interfaces)
+ * so the server is reachable both from other Tailscale devices AND from
+ * localhost — binding to the Tailscale IP alone would leave nothing
+ * listening on 127.0.0.1, silently breaking anything on this same machine
+ * that assumes localhost reachability (Cloudflare Tunnel's local origin,
+ * RepoOS's own tunnel readiness check, etc.). Falls back to localhost-only
+ * when Tailscale isn't detected. `tailscaleIP` is surfaced separately (even
+ * though the actual bind is 0.0.0.0) so callers can show the address other
+ * tailnet devices should actually use.
+ */
+export declare function resolveServeHost(explicitHost?: string): {
+    host: string;
+    tailscaleDetected: boolean;
+    tailscaleIP?: string;
+};
+/**
+ * True when this process is a managed agent (REPOOS_AGENT=1) attempting to
+ * launch `repoos serve` directly, as opposed to a preview child or a reload
+ * replacement spawned by the main server. The AgentRunner sets REPOOS_AGENT=1
+ * on every agent spawn; the preview/reload markers are exempt so RepoOS-owned
+ * processes keep working. Exported for the defense-in-depth tests (#0096).
+ */
+export declare function directServeBlockedByAgent(env?: NodeJS.ProcessEnv): boolean;
+export declare function cmdServe(args: string[], opts?: {
+    onShutdown?: () => void;
+    onReady?: (url: string) => void;
+}): Promise<void>;
+export {};

package/dist/commands/serve.js

@@ -0,0 +1,204 @@
+/**
+ * `repoos serve` — start the local RepoOS server: in-memory live index, file
+ * watcher, JSON API, and SSE event stream. Stays running until interrupted.
+ */
+import { basename } from "node:path";
+import { startServer } from "../server/server.js";
+import { PREVIEW_REQUEST_SIGNAL } from "../server/agents.js";
+import { isBun } from "../core/runtime.js";
+import { findRepoRoot } from "../core/config.js";
+import { c, statusColor } from "../cli/colors.js";
+import { detectTailscaleIPv4 } from "../core/tailscale.js";
+/**
+ * The OS-visible process title for a `repoos serve` instance:
+ * `repoos-<project>`, where `<project>` is the managed root's directory name.
+ * This is the same display name the rest of RepoOS uses (`basename(root)` — the
+ * PWA manifest, login emails, the instance icon), so `ps`/Activity Monitor can
+ * tell which project an instance belongs to without `lsof`/`/api/config`.
+ */
+export function serveProcessTitle(root = findRepoRoot()) {
+    return `repoos-${basename(root) || "repoos"}`;
+}
+/** One-shot marker so the Bun re-exec below can never loop. */
+const TITLE_GUARD = "REPOOS_PROCESS_TITLE";
+/**
+ * Set the OS-visible process title so `ps`/Activity Monitor name the project.
+ *
+ * Node's `process.title` writes through to the OS directly, but Bun's does NOT
+ * (verified on 1.3.x/macOS: the JS property sticks but the kernel argv is
+ * untouched, so `ps` still shows `bun … serve`). The mechanism that does work
+ * under Bun is `process.execve` — a true exec (same PID, same cwd, same stdio)
+ * with a custom argv[0] — so we re-exec once, guarded by {@link TITLE_GUARD}.
+ * On the relabeled second pass the marker is deleted immediately, before any
+ * child is spawned, so reload replacements and preview children start clean and
+ * relabel themselves instead of inheriting a stale "already titled" flag.
+ *
+ * `execve` is injectable purely so tests can observe the call without replacing
+ * the test runner's own process image.
+ */
+export function setServeProcessTitle(title, execve = process.execve) {
+    process.title = title;
+    if (process.env[TITLE_GUARD] === "1") {
+        delete process.env[TITLE_GUARD];
+        return;
+    }
+    if (!isBun() || typeof execve !== "function")
+        return; // Node's process.title already reached the OS
+    const script = process.argv[1];
+    if (!script)
+        return; // no entry path to hand to the re-exec — stay put
+    try {
+        execve(process.execPath, [title, script, ...process.argv.slice(2)], {
+            ...process.env,
+            [TITLE_GUARD]: "1",
+        });
+    }
+    catch {
+        // execve failed (platform/permission) — the process is intact and
+        // process.title above still stands. Never let a display-only nicety stop
+        // the server from starting.
+    }
+}
+/**
+ * Picks the bind host: an explicit `--host` always wins; otherwise, if
+ * Tailscale is running on this machine, default to 0.0.0.0 (all interfaces)
+ * so the server is reachable both from other Tailscale devices AND from
+ * localhost — binding to the Tailscale IP alone would leave nothing
+ * listening on 127.0.0.1, silently breaking anything on this same machine
+ * that assumes localhost reachability (Cloudflare Tunnel's local origin,
+ * RepoOS's own tunnel readiness check, etc.). Falls back to localhost-only
+ * when Tailscale isn't detected. `tailscaleIP` is surfaced separately (even
+ * though the actual bind is 0.0.0.0) so callers can show the address other
+ * tailnet devices should actually use.
+ */
+export function resolveServeHost(explicitHost) {
+    if (explicitHost)
+        return { host: explicitHost, tailscaleDetected: false };
+    const tailscaleIP = detectTailscaleIPv4();
+    if (tailscaleIP)
+        return { host: "0.0.0.0", tailscaleDetected: true, tailscaleIP };
+    return { host: "127.0.0.1", tailscaleDetected: false };
+}
+/**
+ * True when this process is a managed agent (REPOOS_AGENT=1) attempting to
+ * launch `repoos serve` directly, as opposed to a preview child or a reload
+ * replacement spawned by the main server. The AgentRunner sets REPOOS_AGENT=1
+ * on every agent spawn; the preview/reload markers are exempt so RepoOS-owned
+ * processes keep working. Exported for the defense-in-depth tests (#0096).
+ */
+export function directServeBlockedByAgent(env = process.env) {
+    return env.REPOOS_AGENT === "1" && env.REPOOS_PREVIEW_CHILD !== "1" && env.REPOOS_RELOAD !== "1";
+}
+export async function cmdServe(args, opts = {}) {
+    // Defense in depth (#0096): a managed agent process must never start its own
+    // `repoos serve`. An agent that ignores the mission and runs `repoos serve`
+    // directly is rejected here BEFORE binding, so it can never grab the main
+    // server port.
+    if (directServeBlockedByAgent()) {
+        console.error(c.red("  ✗ Managed agent processes may not launch `repoos serve`."));
+        console.error(c.dim("    RepoOS owns previews and the control-plane port. Request a managed preview instead:"));
+        console.error(c.dim(`      include this exact line in your response: ${PREVIEW_REQUEST_SIGNAL}`));
+        console.error(c.dim("    RepoOS starts the preview from your worktree, probes it server-side, and records the URL + result in your transcript."));
+        process.exitCode = 1;
+        return;
+    }
+    // Undefined = "no --port flag"; startServer then resolves it from
+    // repoos.toml's `servePort` or a stable per-repo derived port. Explicit
+    // `--port` still wins.
+    let port;
+    let explicitHost;
+    let quiet = false;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--port" || args[i] === "-p")
+            port = Number(args[++i]);
+        else if (args[i] === "--host")
+            explicitHost = args[++i];
+        else if (args[i] === "--quiet" || args[i] === "-q")
+            quiet = true;
+    }
+    const { host, tailscaleDetected, tailscaleIP } = resolveServeHost(explicitHost);
+    let handle;
+    try {
+        // REPOOS_RELOAD=1 marks a replacement spawned by the auto-reload manager:
+        // it retries EADDRINUSE until the old process hands the port over.
+        handle = await startServer({
+            port,
+            host,
+            reloadReplacement: process.env.REPOOS_RELOAD === "1",
+        });
+    }
+    catch (e) {
+        const msg = e.message;
+        if (msg.includes("EADDRINUSE") ||
+            msg.includes("already bound") ||
+            msg.includes("already in use")) {
+            // The message already names the port (node's EADDRINUSE string or
+            // detectConflict's own text).
+            console.error(c.red("  " + msg) + c.dim("  ·  pass --port N to use a different one"));
+        }
+        else {
+            console.error(c.red("  Failed to start server: " + msg));
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const snap = handle.index.snapshot();
+    console.log(c.bold(c.cyan("\n  RepoOS server")) + c.dim("  ·  ") + c.bold(handle.url));
+    console.log(c.dim("  open ") + c.cyan(handle.url) + c.dim(" in your browser for the UI"));
+    console.log(c.dim("  watching ") +
+        snap.taskCount +
+        c.dim(" tasks  ·  SSE stream at ") +
+        c.cyan(handle.url + "/api/events"));
+    const rt = isBun()
+        ? `Bun ${process.versions.bun ?? ""}`.trim()
+        : `Node ${process.versions.node}`;
+    console.log(c.dim("  runtime ") + rt);
+    console.log(c.dim("  api: ") + c.dim("/api/tasks  /api/tasks/:id  /api/counts  /api/index  /api/docs"));
+    if (tailscaleDetected) {
+        console.log(c.dim("  Tailscale detected — listening on all interfaces (") +
+            c.cyan("0.0.0.0") +
+            c.dim("), reachable from other Tailscale devices at ") +
+            c.cyan(`http://${tailscaleIP}:${handle.port}`) +
+            c.dim(". Use ") +
+            c.cyan("--host 127.0.0.1") +
+            c.dim(" to restrict to localhost only."));
+    }
+    console.log(c.dim("  press ^C to stop\n"));
+    // Fires only now that the server is actually listening (handle.url is a
+    // live, bound address) — a caller opening a browser tab any earlier races
+    // the server's own startup and shows connection errors until a manual
+    // reload.
+    opts.onReady?.(handle.url);
+    // Live activity log in the terminal, mirroring the SSE stream.
+    if (!quiet) {
+        handle.index.on((e) => {
+            const t = new Date().toTimeString().slice(0, 8);
+            const stamp = c.dim(t + "  ");
+            if (e.type === "task.created")
+                console.log(stamp + c.green("created ") + c.dim("#" + e.task.id) + " " + e.task.title);
+            else if (e.type === "task.updated") {
+                const changed = Object.keys(e.prev).join(", ");
+                const statusBit = e.prev.status !== undefined ? " → " + statusColor(e.task.status)(e.task.status) : "";
+                console.log(stamp +
+                    c.cyan("updated ") +
+                    c.dim("#" + e.task.id) +
+                    statusBit +
+                    c.dim("  (" + changed + ")"));
+            }
+            else if (e.type === "task.deleted")
+                console.log(stamp + c.red("deleted ") + c.dim("#" + e.id));
+        });
+    }
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log(c.dim(`\n  shutting down after ${signal} (pid ${process.pid}, port ${handle.port})…`));
+        await handle.close(`received ${signal}`);
+        opts.onShutdown?.();
+        process.exit(0);
+    };
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+}

package/dist/commands/status.d.ts

@@ -0,0 +1,140 @@
+import { type RepoOSConfig, type Status } from "../core/types.js";
+export interface StatusServer {
+    /**
+     * True when a serve process for THIS repo is actually reachable: the
+     * lockfile's PID is alive AND names a repoos serve process AND its port is
+     * answering (or /api/health answers with this repo's root). A lock whose
+     * PID was recycled by an unrelated process is NOT running — "running" is
+     * grounded in the port, not just in /proc existence.
+     */
+    running: boolean;
+    /** Port of the primary serve lock (live first, else most recent), else the probed port. */
+    port: number | null;
+    /** PID recorded in the primary lock — may name a dead process when running is false. */
+    pid: number | null;
+    host: string | null;
+    /** ISO start time — from the lockfile, or /api/health when the lock is thin. */
+    startedAt: string | null;
+    startedAtSource: "lockfile" | "health" | null;
+    uptimeSeconds: number | null;
+    /**
+     * Result of probing /api/health on the port:
+     *   "ok"          — answered and its root matches this repo
+     *   "foreign"     — something answered, but it serves a different root
+     *   "unreachable" — nothing answered
+     */
+    health: "ok" | "foreign" | "unreachable";
+    /** The root the health probe reported (when it answered), for the mismatch note. */
+    healthRoot: string | null;
+    /** Number of serve lockfiles present (a repo may run more than one port). */
+    locks: number;
+}
+export interface StatusBuild {
+    /** Same codes as core/build.ts checkBuildForRoot. */
+    code: "fresh" | "stale" | "no-marker" | "no-build" | "corrupt" | "dev-mode" | "published";
+    stale: boolean;
+    /**
+     * Whether RepoOS's build-staleness contract applies to this checkout (see
+     * BuildCheckResult.applicable in core/build.ts). `stale` stays true for a
+     * non-RepoOS-build checkout so build-triggering callers still work — callers
+     * that want to know whether this is a real problem, not just a pipeline that
+     * doesn't use RepoOS's marker, should check `applicable` too rather than
+     * `stale` alone.
+     */
+    applicable: boolean;
+    message: string | null;
+    version: string | null;
+    buildAt: string | null;
+}
+export interface StatusActiveTask {
+    id: string;
+    title: string;
+    branch: string;
+    worktreePath: string | null;
+    /** Branch exists but no usable worktree — the stuck-task signal. */
+    worktreeMissing: boolean;
+    updatedAt: string | null;
+    needsInput: boolean;
+}
+export interface StatusSnapshot {
+    generatedAt: string;
+    root: string;
+    server: StatusServer;
+    build: StatusBuild;
+    board: {
+        taskCount: number;
+        counts: Record<Status, number>;
+        active: StatusActiveTask[];
+    };
+    worktrees: {
+        /** Registered worktrees including the main checkout. */
+        count: number;
+        warnThreshold: number;
+        /** What `repoos gc --dry-run` would collect (same sweep, same inputs). */
+        leaked: Array<{
+            branch: string;
+            path: string;
+        }>;
+        /** What gc would keep, with the reason it is kept. */
+        kept: Array<{
+            branch: string;
+            path: string;
+            reason: string;
+        }>;
+    };
+    tunnel: {
+        configured: boolean;
+        tunnelName: string | null;
+        running: boolean;
+        hostnames: string[];
+    };
+    git: {
+        branch: string | null;
+        clean: boolean;
+        dirtyFiles: number;
+        /** True when the reported branch IS `main`. */
+        isMainBranch: boolean;
+        /** Commits ahead of / behind `main` (null when branch is main or main is missing). */
+        ahead: number | null;
+        behind: number | null;
+    };
+}
+export interface CollectStatusOptions {
+    /** Overrides "now" — for tests. */
+    now?: Date;
+    /** /api/health fetch timeout in ms (default 800 — a status command must never hang). */
+    probeTimeoutMs?: number;
+    /** Overrides the probed port (lockfile → default derivation) — for hermetic tests. */
+    probePort?: number;
+}
+interface ServeLockEntry {
+    file: string;
+    pid: number;
+    port: number | null;
+    host: string | null;
+    startedAt: string | null;
+    alive: boolean;
+}
+/**
+ * Read every `.repoos/serve[-<port>].lock`. Locks are scoped per port (see
+ * ServeReaper), so there can legitimately be more than one; they are ordered
+ * live-first, then newest-first by `startedAt`, so the primary is the one
+ * that matters. Exported for tests.
+ */
+export declare function readServeLocks(root: string, cacheDir: string): ServeLockEntry[];
+/**
+ * Build the full snapshot. Everything is fail-soft: a missing lockfile, a dead
+ * server, an unreadable marker, or absent git degrade the matching section —
+ * never crash the command.
+ */
+export declare function collectStatus(config: RepoOSConfig, opts?: CollectStatusOptions): Promise<StatusSnapshot>;
+/** "42s" | "5m 07s" | "3h 42m" | "2d 4h" */
+export declare function formatUptime(ms: number): string;
+/** Local "14:02" on the same day, else "Sep 2 14:02". */
+export declare function formatSince(iso: string, now: Date): string;
+/** "41s ago" | "5m ago" | "3h 02m ago" | "2d ago" — for last-activity stamps. */
+export declare function formatRel(iso: string | null, now: Date): string;
+export declare function renderStatus(s: StatusSnapshot, now?: Date): void;
+/** `repoos status [--json]` */
+export declare function cmdStatus(argv: string[]): Promise<void>;
+export {};