merge-steward 0.9.7 → 0.10.1

package/README.md

@@ -1,9 +1,11 @@
 # merge-steward
 
-Speculative merge queue service. It admits approved PRs whose required checks
-are green, builds cumulative speculative branches, waits for CI on those exact
-integrated SHAs, and then fast-forwards `main` to the tested result. On
-failure, it evicts with a durable incident record and GitHub check run.
+`merge-steward` is a self-hosted merge queue for bot-managed and human-managed
+GitHub pull requests. It admits approved PRs whose required checks are green,
+builds cumulative speculative branches, waits for CI on those exact integrated
+SHAs, and then fast-forwards `main` to the tested result. On failure, it evicts
+with a durable incident record and GitHub check run so an agent or human can
+repair the branch and re-queue it.
 
 Fully independent of PatchRelay. Communicates through GitHub — PRs, reviews,
 checks, labels, branches.
@@ -209,34 +211,68 @@ merge-steward doctor --repo repo
 merge-steward service status
 merge-steward queue status --repo repo
 merge-steward queue show --repo repo --pr 123
+merge-steward dashboard
 
 # Manual foreground start
 merge-steward serve
 
-# Live queue watch TUI
-merge-steward queue watch --repo app
+# Open one project directly in the dashboard
+merge-steward dashboard --repo app
 ```
 
-### Watch TUI
+### Dashboard
 
-`merge-steward queue watch --repo <id>` gives you a terminal view of the queue:
+`merge-steward dashboard` is the operator surface for day-to-day queue work.
 
-- which PRs are currently queued
-- which PR is head-of-line
-- current steward tick state
-- recent queue transitions
-- per-PR detail with incidents and event history
+The first screen shows all configured projects with:
+
+- project-level queue health
+- readable queue stats
+- a compact queue chain like `#123 ●  #124 ○`
+- clear bad states such as blocked, stuck, or needs attention
+
+Press `Enter` on a project to open the second screen. That project detail view shows:
+
+- the same top-level queue stats for that project
+- a readable list of PRs in the queue
+- recent queue activity in plain language
+- incidents for evicted PRs
+- direct actions like reconcile and dequeue
+
+Use `merge-steward dashboard --repo <id>` to open the project detail screen directly. Use `--pr <number>` to preselect a PR when you already know what you need to inspect.
 
 Controls:
 
 - `j` / `k` or arrows — move selection
-- `Enter` — open selected PR detail
-- `Esc` — return to queue view
-- `a` — toggle `active` vs `all`
-- `r` — run a reconcile tick now
-- `d` — dequeue the selected PR
+- `Enter` — open the selected project from overview
+- `Esc` — return to the overview
+- `a` — toggle `active` vs `all` in project view
+- `r` — run a reconcile tick for the selected project
+- `d` — dequeue the selected PR in project view
 - `q` — quit
 
+### Validation, Visibility, And Troubleshooting
+
+These are the first commands to reach for after setup or when a queue looks wrong:
+
+```bash
+merge-steward doctor --repo app
+merge-steward service status
+merge-steward service restart
+merge-steward dashboard
+merge-steward queue status --repo app
+merge-steward queue show --repo app --pr 123
+merge-steward service logs --lines 100
+```
+
+Use them this way:
+
+- `doctor` checks config, GitHub auth, branch rules, and required checks.
+- `dashboard` is the best live operator view across all configured projects.
+- `queue status` is the fastest text snapshot when you need one repo in a shell script or over SSH.
+- `queue show --pr <number>` is the most direct way to inspect one PR's queue events and incidents.
+- `service logs` helps when the queue is not reacting to webhooks, GitHub auth is failing, or reconcile ticks are erroring.
+
 ### systemd
 
 ```ini
@@ -264,15 +300,15 @@ WantedBy=multi-user.target
 | Endpoint | Method | Description |
 |-|-|-|
 | `/health` | GET | Liveness check |
-| `/queue/status` | GET | All queue entries |
-| `/queue/watch` | GET | Queue snapshot for the operator TUI |
-| `/queue/enqueue` | POST | Manually enqueue a PR |
-| `/queue/reconcile` | POST | Trigger one reconcile tick immediately |
-| `/queue/entries/:id/detail` | GET | Entry detail with recent events and incidents |
-| `/queue/entries/:id/dequeue` | POST | Remove from queue (non-destructive) |
-| `/queue/entries/:id/update-head` | POST | Update head SHA (force-push) |
-| `/queue/incidents/:id` | GET | Get incident details |
-| `/queue/entries/:id/incidents` | GET | List incidents for an entry |
+| `/repos/:repoId/queue/status` | GET | All queue entries for one configured repo |
+| `/repos/:repoId/queue/watch` | GET | Queue snapshot used by the dashboard |
+| `/repos/:repoId/queue/enqueue` | POST | Manually enqueue a PR |
+| `/repos/:repoId/queue/reconcile` | POST | Trigger one reconcile tick immediately |
+| `/repos/:repoId/queue/entries/:id/detail` | GET | Entry detail with recent events and incidents |
+| `/repos/:repoId/queue/entries/:id/dequeue` | POST | Remove from queue (non-destructive) |
+| `/repos/:repoId/queue/entries/:id/update-head` | POST | Update head SHA (force-push) |
+| `/repos/:repoId/queue/incidents/:id` | GET | Get incident details |
+| `/repos/:repoId/queue/entries/:id/incidents` | GET | List incidents for an entry |
 | `/webhooks/github` | POST | GitHub webhook receiver for all configured repos |
 
 ## Queue state machine

package/dist/cli/args.js

@@ -57,6 +57,11 @@ export function validateFlags(parsed) {
         case "serve":
             assertKnownFlags(parsed, "root", []);
             return;
+        case "dashboard":
+        case "dash":
+        case "d":
+            assertKnownFlags(parsed, "root", ["repo", "pr"]);
+            return;
         case "attach":
             assertKnownFlags(parsed, "repos", ["base-branch", "required-check", "label", "merge-queue-check-name", "refresh", "json"]);
             return;
@@ -97,15 +102,15 @@ export function validateFlags(parsed) {
             }
         case "queue":
             switch (subcommand) {
+                case "dashboard":
+                    assertKnownFlags(parsed, "queue", ["repo", "pr"]);
+                    return;
                 case "status":
                     assertKnownFlags(parsed, "queue", ["repo", "events", "json"]);
                     return;
                 case "show":
                     assertKnownFlags(parsed, "queue", ["repo", "entry", "pr", "events", "json"]);
                     return;
-                case "watch":
-                    assertKnownFlags(parsed, "queue", ["repo", "pr"]);
-                    return;
                 case "reconcile":
                     assertKnownFlags(parsed, "queue", ["repo", "json"]);
                     return;

package/dist/cli/commands/dashboard.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from "../types.ts";
+export declare function handleDashboard(parsed: ParsedArgs): Promise<number>;

package/dist/cli/commands/dashboard.js

@@ -0,0 +1,24 @@
+import { parseIntegerFlag } from "../args.js";
+import { loadRepoConfigById } from "../system.js";
+export async function handleDashboard(parsed) {
+    const initialRepoRef = typeof parsed.flags.get("repo") === "string"
+        ? String(parsed.flags.get("repo"))
+        : undefined;
+    const initialPrNumber = parseIntegerFlag(parsed.flags.get("pr"), "--pr");
+    const options = {};
+    if (initialRepoRef) {
+        loadRepoConfigById(initialRepoRef);
+        options.initialRepoRef = initialRepoRef;
+    }
+    if (initialPrNumber !== undefined) {
+        options.initialPrNumber = initialPrNumber;
+    }
+    if (!process.stdin.isTTY || typeof process.stdin.setRawMode !== "function") {
+        process.stderr.write("merge-steward dashboard requires an interactive TTY.\n");
+        process.stderr.write("Use `merge-steward queue status --repo <id>` or run the dashboard from a terminal.\n");
+        return 1;
+    }
+    const { startDashboard } = await import("../../watch/index.js");
+    await startDashboard(options);
+    return 0;
+}

package/dist/cli/commands/queue.js

@@ -117,11 +117,11 @@ export async function handleQueue(parsed, stdout) {
         throw new UsageError("merge-steward queue requires a subcommand.", "queue");
     }
     if (subcommand === "watch") {
-        const repoId = resolveRepoId(parsed, 2, "queue");
-        const { configPath } = loadRepoConfigById(repoId);
-        const { startWatch } = await import("../../watch/index.js");
-        await startWatch(configPath, parseIntegerFlag(parsed.flags.get("pr"), "--pr"));
-        return 0;
+        throw new UsageError("`merge-steward queue watch` was replaced by `merge-steward dashboard [--repo <id>] [--pr <number>]`.", "queue");
+    }
+    if (subcommand === "dashboard") {
+        const { handleDashboard } = await import("./dashboard.js");
+        return await handleDashboard(parsed);
     }
     const repoId = resolveRepoId(parsed, 2, "queue");
     const { config } = loadRepoConfigById(repoId);

package/dist/cli/commands/service.js

@@ -2,7 +2,7 @@ import { installServiceUnit } from "../../install.js";
 import { UsageError } from "../types.js";
 import { parseIntegerFlag } from "../args.js";
 import { formatJson, writeOutput } from "../output.js";
-import { formatCommandFailure, parseSystemctlShowOutput, runSystemctl } from "../system.js";
+import { fetchServiceHealthStatus, formatCommandFailure, parseSystemctlShowOutput, runSystemctl } from "../system.js";
 const UNIT_NAME = "merge-steward.service";
 export async function handleService(parsed, stdout, runCommand) {
     const subcommand = parsed.positionals[1];
@@ -31,6 +31,8 @@ export async function handleService(parsed, stdout, runCommand) {
         const restart = await runSystemctl(runCommand, ["reload-or-restart", UNIT_NAME]);
         if (parsed.flags.get("json") === true) {
             writeOutput(stdout, formatJson({
+                service: "merge-steward",
+                unit: UNIT_NAME,
                 daemonReloaded: daemonReload.ok,
                 restarted: restart.ok,
                 errors: [
@@ -55,8 +57,9 @@ export async function handleService(parsed, stdout, runCommand) {
             throw new Error(status.error);
         }
         const properties = parseSystemctlShowOutput(status.result.stdout);
+        const health = await fetchServiceHealthStatus();
         if (parsed.flags.get("json") === true) {
-            writeOutput(stdout, formatJson({ unit: UNIT_NAME, systemd: properties }));
+            writeOutput(stdout, formatJson({ service: "merge-steward", unit: UNIT_NAME, systemd: properties, health }));
             return 0;
         }
         writeOutput(stdout, [
@@ -65,6 +68,9 @@ export async function handleService(parsed, stdout, runCommand) {
             `Enabled: ${properties.UnitFileState ?? "unknown"}`,
             `Active: ${properties.ActiveState ?? "unknown"}${properties.SubState ? ` (${properties.SubState})` : ""}`,
             properties.ExecMainPID ? `Main PID: ${properties.ExecMainPID}` : undefined,
+            health.reachable
+                ? `Health: ${health.ok ? "ok" : "unhealthy"} (HTTP ${health.status})`
+                : `Health: not reachable (${health.error})`,
         ]
             .filter(Boolean)
             .join("\n") + "\n");

package/dist/cli/help.js

@@ -20,12 +20,12 @@ function rootHelpText() {
         "  repo list [--json]                                     List attached repositories",
         "  repo show <id> [--json]                                Show one repo config",
         "  doctor [--repo <id>] [--json]                          Validate config, secrets, auth, and required binaries",
-        "  service status [--json]                                Show systemd state",
+        "  service status [--json]                                Show systemd state and local health",
         "  service logs [--lines <count>] [--json]                Show recent journal logs",
         "  queue status --repo <id> [--json]                      Show queue summary and current entries",
         "  queue show --repo <id> (--entry <id> | --pr <num>) [--events <count>] [--json]",
         "                                                          Show one queue entry with events and incidents",
-        "  queue watch --repo <id> [--pr <number>]                Open the queue watch TUI",
+        "  dashboard [--repo <id>] [--pr <number>]                Open the multi-repo merge queue dashboard",
         "",
         "Service management:",
         "  service install [--force] [--json]                     Reinstall the systemd unit",
@@ -83,7 +83,7 @@ function serviceHelpText() {
         "Commands:",
         "  install [--force] [--json]    Reinstall the systemd unit",
         "  restart [--json]              Reload-or-restart the service",
-        "  status [--json]               Show systemd state",
+        "  status [--json]               Show systemd state and local health",
         "  logs [--lines <count>] [--json]",
         "                                Show recent journal logs",
     ].join("\n");
@@ -94,9 +94,9 @@ function queueHelpText() {
         "  merge-steward queue <command> [options]",
         "",
         "Commands:",
+        "  dashboard [--repo <id>] [--pr <number>]            Open the multi-repo merge queue dashboard",
         "  status --repo <id>                                 Show queue summary and entries",
         "  show --repo <id> (--entry <id> | --pr <num>)       Show one queue entry with events and incidents",
-        "  watch --repo <id> [--pr <number>]                  Open the queue watch TUI",
         "  reconcile --repo <id> [--json]                     Ask the service to reconcile immediately",
     ].join("\n");
 }

package/dist/cli/system.d.ts

@@ -40,6 +40,14 @@ export declare function fetchGatewayJson<T>(relativePath: string, options?: {
     method?: string;
     body?: unknown;
 }): Promise<T>;
+export declare function fetchServiceHealthStatus(): Promise<{
+    reachable: true;
+    ok: boolean;
+    status: number;
+} | {
+    reachable: false;
+    error: string;
+}>;
 export declare function fetchLocalJson<T>(repoId: string, relativePath: string, options?: {
     method?: string;
 }): Promise<T>;

package/dist/cli/system.js

@@ -161,7 +161,7 @@ export function getGatewayBaseUrl() {
         throw new Error("merge-steward home not initialized.");
     }
     const homeConfig = parseHomeConfigObject(readFileSync(homeConfigPath, "utf8"), homeConfigPath);
-    const bind = homeConfig.server.bind;
+    const bind = homeConfig.server.bind === "0.0.0.0" ? "127.0.0.1" : homeConfig.server.bind;
     const port = homeConfig.server.gateway_port ?? (homeConfig.server.port_base - 1);
     return `http://${bind}:${port}`;
 }
@@ -193,6 +193,34 @@ export async function fetchGatewayJson(relativePath, options) {
     const base = getGatewayBaseUrl();
     return await requestGatewayJson(`${base}${relativePath}`, options);
 }
+export async function fetchServiceHealthStatus() {
+    try {
+        const response = await fetch(`${getGatewayBaseUrl()}/health`, {
+            signal: AbortSignal.timeout(2_000),
+        });
+        let ok = response.ok;
+        try {
+            const body = await response.json();
+            if (typeof body.ok === "boolean") {
+                ok = response.ok && body.ok;
+            }
+        }
+        catch {
+            ok = response.ok;
+        }
+        return {
+            reachable: true,
+            ok,
+            status: response.status,
+        };
+    }
+    catch (error) {
+        return {
+            reachable: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 export async function fetchLocalJson(repoId, relativePath, options) {
     return await fetchGatewayJson(`/repos/${repoId}${relativePath}`, options);
 }

package/dist/cli.js

@@ -21,7 +21,10 @@ export async function runCli(argv, options) {
             return 0;
         }
         validateFlags(parsed);
-        const command = parsed.positionals[0] ?? "help";
+        const requestedCommand = parsed.positionals[0] ?? "help";
+        const command = requestedCommand === "dash" || requestedCommand === "d"
+            ? "dashboard"
+            : requestedCommand;
         if (hasHelpFlag(parsed) || command === "help") {
             const topic = command === "help"
                 ? (parsed.positionals[1] ?? "root")
@@ -64,6 +67,8 @@ export async function runCli(argv, options) {
             }
             case "doctor":
                 return await (await import("./cli/commands/doctor.js")).handleDoctor(parsed, stdout);
+            case "dashboard":
+                return await (await import("./cli/commands/dashboard.js")).handleDashboard(parsed);
             case "service":
                 return await (await import("./cli/commands/service.js")).handleService(parsed, stdout, runCommand);
             case "queue":

package/dist/watch/App.d.ts

@@ -1,6 +1,9 @@
+import type { DashboardRepoConfig } from "./dashboard-model.ts";
 interface AppProps {
-    baseUrl: string;
+    gatewayBaseUrl: string;
+    repos: DashboardRepoConfig[];
+    initialRepoRef?: string | undefined;
     initialPrNumber?: number | undefined;
 }
-export declare function App({ baseUrl, initialPrNumber }: AppProps): React.JSX.Element;
+export declare function App({ gatewayBaseUrl, repos, initialRepoRef, initialPrNumber }: AppProps): React.JSX.Element;
 export {};