merge-steward 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PatchRelay contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,246 @@
+# merge-steward
+
+Serial merge queue service. Rebases PRs onto main one at a time, waits for CI, and merges when green. Evicts on failure and reports incidents via GitHub check runs.
+
+Fully independent of PatchRelay. Communicates through GitHub — PRs, labels, check runs, branches.
+
+## How it works
+
+1. A PR gets the `queue` label (manually, by PatchRelay, or by any automation)
+2. The steward sees the label via GitHub webhook
+3. If the PR is approved and CI is green, it enters the queue
+4. The steward processes the queue head: fetch → rebase onto main → push → wait for CI → merge
+5. On failure: retry (gated on base SHA change), then evict with a durable incident record and GitHub check run
+6. PatchRelay (or any agent) sees the check run failure and can fix the branch
+7. When the branch is fixed and CI passes again, adding the `queue` label re-admits it
+
+## Setup
+
+### Prerequisites
+
+- Node.js 24+
+- `gh` CLI available in `PATH`
+- `git` binary
+
+### Bootstrap
+
+Initialize the machine-level steward home once:
+
+```bash
+merge-steward init https://queue.example.com
+```
+
+That creates:
+
+- `~/.config/merge-steward/runtime.env`
+- `~/.config/merge-steward/service.env`
+- `~/.config/merge-steward/merge-steward.json`
+- `~/.config/merge-steward/repos/`
+- `/etc/systemd/system/merge-steward@.service`
+
+Add one repo-scoped steward instance:
+
+```bash
+merge-steward attach app owner/repo --base-branch main --required-check test,lint
+```
+
+That writes `~/.config/merge-steward/repos/app.json`, enables `merge-steward@app.service`, and prints the repo-specific webhook URL.
+
+Validate the setup:
+
+```bash
+merge-steward doctor --repo app
+merge-steward service status app
+merge-steward queue status --repo app
+```
+
+### Secrets
+
+For dev, `service.env` can contain:
+
+```bash
+MERGE_STEWARD_WEBHOOK_SECRET=replace-with-webhook-secret
+MERGE_STEWARD_GITHUB_TOKEN=replace-with-github-token
+```
+
+For production, prefer `systemd-creds` with:
+
+- `LoadCredentialEncrypted=merge-steward-webhook-secret`
+- `LoadCredentialEncrypted=merge-steward-github-token`
+
+The steward resolves secrets in this order:
+
+1. `$CREDENTIALS_DIRECTORY/<name>`
+2. `${ENV_KEY}_FILE`
+3. `${ENV_KEY}`
+
+### Repo Config
+
+`merge-steward attach` writes a repo-scoped config like:
+
+```json
+{
+  "repoId": "app",
+  "repoFullName": "owner/repo",
+  "baseBranch": "main",
+  "clonePath": "~/.local/state/merge-steward/repos/app",
+  "maxRetries": 2,
+  "flakyRetries": 1,
+  "requiredChecks": ["test", "lint"],
+  "pollIntervalMs": 30000,
+  "admissionLabel": "queue",
+  "webhookPath": "/webhooks/github/queue/app",
+  "server": {
+    "bind": "127.0.0.1",
+    "port": 8790
+  },
+  "database": {
+    "path": "~/.local/state/merge-steward/app.sqlite"
+  }
+}
+```
+
+| Field | Description |
+|-|-|
+| `repoId` | Internal ID for this repo (used in DB keys) |
+| `repoFullName` | GitHub `owner/repo` |
+| `baseBranch` | Target branch for merges (usually `main`) |
+| `clonePath` | Local clone directory (created on first run) |
+| `maxRetries` | Rebase/CI retry attempts before eviction |
+| `flakyRetries` | CI-only retries before counting toward maxRetries |
+| `requiredChecks` | Check names that must pass for admission (empty = any green) |
+| `pollIntervalMs` | Reconciliation loop interval |
+| `admissionLabel` | GitHub label that triggers queue admission |
+| `webhookPath` | Repo-specific webhook endpoint path |
+
+### GitHub Webhook
+
+Configure a webhook on the repository:
+
+- **Payload URL:** the repo-specific URL printed by `merge-steward attach`, for example `https://queue.example.com/webhooks/github/queue/app`
+- **Content type:** `application/json`
+- **Secret:** same as `MERGE_STEWARD_WEBHOOK_SECRET`
+- **Events:** Pull requests, Pull request reviews, Check suites, Pushes
+
+### Running
+
+```bash
+# Happy path
+merge-steward init https://queue.example.com
+merge-steward attach app owner/repo --base-branch main --required-check test,lint
+merge-steward doctor --repo app
+merge-steward service status app
+merge-steward queue status --repo app
+merge-steward queue show --repo app --pr 123
+
+# Manual foreground start
+merge-steward serve --repo app
+
+# Live queue watch TUI
+merge-steward queue watch --repo app
+```
+
+### Watch TUI
+
+`merge-steward queue watch --repo <id>` gives you a terminal view of the queue:
+
+- 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
+
+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
+- `q` — quit
+
+### systemd
+
+```ini
+[Unit]
+Description=merge-steward (%i)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+EnvironmentFile=-/home/your-user/.config/merge-steward/runtime.env
+EnvironmentFile=-/home/your-user/.config/merge-steward/service.env
+LoadCredentialEncrypted=merge-steward-webhook-secret
+LoadCredentialEncrypted=merge-steward-github-token
+ExecStart=/usr/bin/env merge-steward serve --repo %i
+Restart=on-failure
+RestartSec=5s
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## API
+
+| 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 |
+| `/webhooks/github/queue` | POST | GitHub webhook receiver (configurable via `webhookPath`) |
+
+## Queue state machine
+
+```
+queued → preparing_head → validating → merging → merged
+                                              → evicted (on failure after retries)
+```
+
+- **queued**: waiting in line
+- **preparing_head**: fetching + rebasing onto base branch
+- **validating**: CI running
+- **merging**: revalidation + merge
+- **merged**: done
+- **evicted**: failed after retry budget, incident created
+- **dequeued**: manually removed
+
+## Interaction with PatchRelay
+
+The steward and PatchRelay are independent services that communicate through GitHub:
+
+- PatchRelay adds the `queue` label when an issue reaches `awaiting_queue`
+- The steward merges the PR or evicts it (creating a `merge-steward/queue` check run)
+- PatchRelay watches for that check run failure and triggers `queue_repair`
+- After repair, PatchRelay re-adds the `queue` label
+- The steward re-admits the PR
+
+Neither service calls the other's API. GitHub is the shared bus.
+
+## Current scope
+
+What's implemented:
+- **Speculative execution**: cumulative branches (`main+A`, `main+A+B`, `main+A+B+C`) tested in parallel. Configurable depth (default 3, set `speculativeDepth: 1` for serial mode).
+- **Speculative consistency**: when head merges, downstream entries that already passed don't re-test.
+- **Cascade invalidation**: when mid-chain entry fails, downstream speculative branches are rebuilt without it.
+- Non-spinning conflict retry: gated on base SHA change
+- Flaky CI retry budget (separate from retry budget)
+- Revalidation before merge (approval, SHA, external merge)
+- Durable incident records on eviction
+- GitHub check run as eviction signal
+- Label-based admission and re-admission
+- Structured reconciler event stream for observability
+
+What's not built yet (see [design doc](https://github.com/krasnoperov/patchrelay/blob/main/docs/design-docs/merge-steward.md)):
+- Binary bisection on batch failure
+- File-path conflict detection for parallel lanes
+- Flaky test learning (only retry budget, no historical analysis)
+- Priority reordering after enqueue

package/dist/classify.d.ts

@@ -0,0 +1,9 @@
+import type { CheckResult, FailureClass } from "./types.ts";
+/**
+ * Classify a CI failure by comparing branch checks against main baseline.
+ *
+ * - main_broken: the same checks that fail on the branch also fail on main
+ * - branch_local: checks fail on the branch but pass on main (PR's own fault)
+ * - integration_conflict: default when no baseline is available
+ */
+export declare function classifyFailure(branchChecks: CheckResult[], mainChecks: CheckResult[]): FailureClass;

package/dist/classify.js

@@ -0,0 +1,29 @@
+/**
+ * Classify a CI failure by comparing branch checks against main baseline.
+ *
+ * - main_broken: the same checks that fail on the branch also fail on main
+ * - branch_local: checks fail on the branch but pass on main (PR's own fault)
+ * - integration_conflict: default when no baseline is available
+ */
+export function classifyFailure(branchChecks, mainChecks) {
+    const failedOnBranch = branchChecks.filter((c) => c.conclusion === "failure");
+    if (failedOnBranch.length === 0)
+        return "integration_conflict";
+    if (mainChecks.length === 0) {
+        // No baseline — can't distinguish. Default to integration_conflict
+        // since we only classify after rebase.
+        return "integration_conflict";
+    }
+    const failedOnMain = mainChecks.filter((c) => c.conclusion === "failure");
+    const mainFailedNames = new Set(failedOnMain.map((c) => c.name));
+    // If every branch failure also fails on main, main is broken.
+    const allOnMain = failedOnBranch.every((c) => mainFailedNames.has(c.name));
+    if (allOnMain && failedOnMain.length > 0)
+        return "main_broken";
+    // If none of the branch failures appear on main, it's the branch's fault.
+    const noneOnMain = failedOnBranch.every((c) => !mainFailedNames.has(c.name));
+    if (noneOnMain)
+        return "branch_local";
+    // Mixed: some fail on main, some don't. Treat as integration_conflict.
+    return "integration_conflict";
+}

package/dist/cli/args.d.ts

@@ -0,0 +1,7 @@
+import type { ParsedArgs, HelpTopic } from "./types.ts";
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function hasHelpFlag(parsed: ParsedArgs): boolean;
+export declare function assertKnownFlags(parsed: ParsedArgs, helpTopic: HelpTopic, allowedFlags: string[]): void;
+export declare function validateFlags(parsed: ParsedArgs): void;
+export declare function parseCsvFlag(value: string | boolean | undefined): string[];
+export declare function parseIntegerFlag(value: string | boolean | undefined, label: string): number | undefined;

package/dist/cli/args.js

@@ -0,0 +1,118 @@
+import { UsageError } from "./types.js";
+export function parseArgs(argv) {
+    const positionals = [];
+    const flags = new Map();
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index];
+        if (value === "-h" || value === "--help") {
+            flags.set("help", true);
+            continue;
+        }
+        if (!value.startsWith("--")) {
+            positionals.push(value);
+            continue;
+        }
+        const trimmed = value.slice(2);
+        const [name, inline] = trimmed.split("=", 2);
+        if (!name)
+            continue;
+        if (inline !== undefined) {
+            flags.set(name, inline);
+            continue;
+        }
+        const next = argv[index + 1];
+        if (next && !next.startsWith("--")) {
+            flags.set(name, next);
+            index += 1;
+            continue;
+        }
+        flags.set(name, true);
+    }
+    return { positionals, flags };
+}
+export function hasHelpFlag(parsed) {
+    return parsed.flags.get("help") === true;
+}
+export function assertKnownFlags(parsed, helpTopic, allowedFlags) {
+    const allowed = new Set(["help", ...allowedFlags]);
+    const unknownFlags = [...parsed.flags.keys()].filter((flag) => !allowed.has(flag)).sort();
+    if (unknownFlags.length === 0) {
+        return;
+    }
+    throw new UsageError(`Unknown flag${unknownFlags.length === 1 ? "" : "s"}: ${unknownFlags.map((flag) => `--${flag}`).join(", ")}`, helpTopic);
+}
+export function validateFlags(parsed) {
+    const command = parsed.positionals[0] ?? "help";
+    const subcommand = parsed.positionals[1];
+    switch (command) {
+        case "help":
+            assertKnownFlags(parsed, "root", []);
+            return;
+        case "init":
+            assertKnownFlags(parsed, "root", ["force", "json"]);
+            return;
+        case "doctor":
+            assertKnownFlags(parsed, "root", ["repo", "json"]);
+            return;
+        case "serve":
+            assertKnownFlags(parsed, "root", ["config", "repo"]);
+            return;
+        case "attach":
+            assertKnownFlags(parsed, "repos", ["base-branch", "required-check", "label", "json"]);
+            return;
+        case "repos":
+            assertKnownFlags(parsed, "repos", ["json"]);
+            return;
+        case "service":
+            switch (subcommand) {
+                case "install":
+                    assertKnownFlags(parsed, "service", ["force", "json"]);
+                    return;
+                case "restart":
+                    assertKnownFlags(parsed, "service", ["json"]);
+                    return;
+                case "status":
+                    assertKnownFlags(parsed, "service", ["json"]);
+                    return;
+                case "logs":
+                    assertKnownFlags(parsed, "service", ["lines", "json"]);
+                    return;
+                default:
+                    assertKnownFlags(parsed, "service", []);
+                    return;
+            }
+        case "queue":
+            switch (subcommand) {
+                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;
+                default:
+                    assertKnownFlags(parsed, "queue", []);
+                    return;
+            }
+        default:
+            assertKnownFlags(parsed, "root", []);
+    }
+}
+export function parseCsvFlag(value) {
+    if (typeof value !== "string")
+        return [];
+    return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+}
+export function parseIntegerFlag(value, label) {
+    if (typeof value !== "string")
+        return undefined;
+    if (!/^\d+$/.test(value.trim())) {
+        throw new UsageError(`${label} must be a positive integer.`);
+    }
+    return Number(value.trim());
+}

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

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

package/dist/cli/commands/attach.js

@@ -0,0 +1,61 @@
+import { installServiceUnit, upsertRepoConfig } from "../../install.js";
+import { UsageError } from "../types.js";
+import { parseCsvFlag } from "../args.js";
+import { formatJson, writeOutput } from "../output.js";
+import { readHomeConfig, runSystemctl } from "../system.js";
+export async function handleAttach(parsed, stdout, runCommand) {
+    const repoId = parsed.positionals[1];
+    const repoFullName = parsed.positionals[2];
+    if (!repoId || !repoFullName) {
+        throw new UsageError("merge-steward attach requires <id> and <owner/repo>.", "repos");
+    }
+    const baseBranch = typeof parsed.flags.get("base-branch") === "string" ? String(parsed.flags.get("base-branch")) : undefined;
+    const admissionLabel = typeof parsed.flags.get("label") === "string" ? String(parsed.flags.get("label")) : undefined;
+    const result = await upsertRepoConfig({
+        id: repoId,
+        repoFullName,
+        ...(baseBranch ? { baseBranch } : {}),
+        ...(parseCsvFlag(parsed.flags.get("required-check")).length > 0
+            ? { requiredChecks: parseCsvFlag(parsed.flags.get("required-check")) }
+            : {}),
+        ...(admissionLabel ? { admissionLabel } : {}),
+    });
+    const unitInstall = await installServiceUnit();
+    const daemonReload = await runSystemctl(runCommand, ["daemon-reload"]);
+    const enableState = await runSystemctl(runCommand, ["enable", `merge-steward@${repoId}.service`]);
+    const restartState = await runSystemctl(runCommand, ["reload-or-restart", `merge-steward@${repoId}.service`]);
+    const { config: homeConfig } = readHomeConfig();
+    const publicBaseUrl = homeConfig.server.public_base_url;
+    const webhookUrl = publicBaseUrl ? new URL(result.repo.webhookPath, publicBaseUrl).toString() : undefined;
+    const payload = {
+        ...result,
+        unitTemplatePath: unitInstall.unitTemplatePath,
+        daemonReloaded: daemonReload.ok,
+        serviceEnabled: enableState.ok,
+        serviceRestarted: restartState.ok,
+        ...(webhookUrl ? { webhookUrl } : {}),
+        errors: [
+            ...(daemonReload.ok ? [] : [daemonReload.error]),
+            ...(enableState.ok ? [] : [enableState.error]),
+            ...(restartState.ok ? [] : [restartState.error]),
+        ],
+    };
+    if (parsed.flags.get("json") === true) {
+        writeOutput(stdout, formatJson(payload));
+        return daemonReload.ok && enableState.ok && restartState.ok ? 0 : 1;
+    }
+    writeOutput(stdout, [
+        `Repo config: ${result.configPath}`,
+        `${result.status === "created" ? "Attached" : result.status === "updated" ? "Updated" : "Verified"} repo ${result.repo.id} for ${result.repo.repoFullName}`,
+        `Base branch: ${result.repo.baseBranch}`,
+        `Admission label: ${result.repo.admissionLabel}`,
+        `Required checks: ${result.repo.requiredChecks.length > 0 ? result.repo.requiredChecks.join(", ") : "(any green check)"}`,
+        `Local port: ${result.repo.port}`,
+        webhookUrl ? `Webhook URL: ${webhookUrl}` : "Webhook URL: set MERGE_STEWARD_PUBLIC_BASE_URL in runtime.env or merge-steward.json to print this",
+        daemonReload.ok ? "systemd daemon-reload completed." : `systemd daemon-reload failed: ${daemonReload.error}`,
+        enableState.ok ? `Enabled merge-steward@${repoId}.service` : `Enable failed: ${enableState.error}`,
+        restartState.ok ? `Restarted merge-steward@${repoId}.service` : `Restart failed: ${restartState.error}`,
+        "Next: merge-steward service status " + repoId,
+    ].join("\n") + "\n");
+    return daemonReload.ok && enableState.ok && restartState.ok ? 0 : 1;
+}

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

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

package/dist/cli/commands/doctor.js

@@ -0,0 +1,122 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync, mkdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { loadConfig } from "../../config.js";
+import { exec } from "../../exec.js";
+import { resolveSecretWithSource } from "../../resolve-secret.js";
+import { getDefaultConfigPath, getDefaultRepoConfigDir, getDefaultRuntimeEnvPath, getDefaultServiceEnvPath, getDefaultStateDir, getRepoConfigPath, getSystemdUnitTemplatePath, } from "../../runtime-paths.js";
+import { formatJson, writeOutput } from "../output.js";
+import { getHomeEnv } from "../system.js";
+function checkPath(scope, targetPath, writable = false) {
+    if (!existsSync(targetPath)) {
+        return { status: "fail", scope, message: `Missing path: ${targetPath}` };
+    }
+    try {
+        const stats = statSync(targetPath);
+        if (!stats.isDirectory() && !stats.isFile()) {
+            return { status: "fail", scope, message: `Unexpected path type: ${targetPath}` };
+        }
+        if (writable) {
+            accessSync(stats.isDirectory() ? targetPath : path.dirname(targetPath), constants.W_OK);
+        }
+        return { status: "pass", scope, message: writable ? `${targetPath} is writable` : `${targetPath} exists` };
+    }
+    catch (error) {
+        return {
+            status: "fail",
+            scope,
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function checkExecutable(scope, command) {
+    const result = spawnSync(command, ["--version"], { stdio: "ignore" });
+    if (result.status === 0) {
+        return { status: "pass", scope, message: `${command} is available` };
+    }
+    return { status: "fail", scope, message: `${command} is not available in PATH` };
+}
+export async function handleDoctor(parsed, stdout) {
+    const repoId = typeof parsed.flags.get("repo") === "string" ? String(parsed.flags.get("repo")) : undefined;
+    const checks = [];
+    const env = getHomeEnv();
+    checks.push(checkPath("home-config", getDefaultConfigPath()));
+    checks.push(checkPath("runtime-env", getDefaultRuntimeEnvPath()));
+    checks.push(checkPath("service-env", getDefaultServiceEnvPath()));
+    checks.push(checkPath("repo-config-dir", getDefaultRepoConfigDir(), true));
+    checks.push(checkPath("state-dir", getDefaultStateDir(), true));
+    checks.push(checkPath("systemd-unit", getSystemdUnitTemplatePath()));
+    checks.push(await checkExecutable("git", "git"));
+    checks.push(await checkExecutable("gh", "gh"));
+    const webhookSecret = resolveSecretWithSource("merge-steward-webhook-secret", "MERGE_STEWARD_WEBHOOK_SECRET", env);
+    checks.push({
+        status: webhookSecret.value ? "pass" : "warn",
+        scope: "webhook-secret",
+        message: webhookSecret.value
+            ? `Webhook secret resolved from ${webhookSecret.source}`
+            : "Webhook secret is missing; signed webhook verification will be disabled",
+    });
+    const githubToken = resolveSecretWithSource("merge-steward-github-token", "MERGE_STEWARD_GITHUB_TOKEN", env);
+    checks.push({
+        status: githubToken.value ? "pass" : "fail",
+        scope: "github-token",
+        message: githubToken.value
+            ? `GitHub token resolved from ${githubToken.source}`
+            : "GitHub token is missing; steward cannot call gh for merge/check operations",
+    });
+    let repoConfigPath;
+    if (repoId) {
+        repoConfigPath = getRepoConfigPath(repoId);
+        if (!existsSync(repoConfigPath)) {
+            checks.push({ status: "fail", scope: `repo:${repoId}`, message: `Repo config not found: ${repoConfigPath}` });
+        }
+        else {
+            try {
+                const config = loadConfig(repoConfigPath);
+                mkdirSync(path.dirname(config.database.path), { recursive: true });
+                mkdirSync(path.dirname(config.clonePath), { recursive: true });
+                checks.push({ status: "pass", scope: `repo:${repoId}`, message: `Repo config is valid for ${config.repoFullName}` });
+                checks.push(checkPath(`repo:${repoId}:database-dir`, path.dirname(config.database.path), true));
+                checks.push(checkPath(`repo:${repoId}:clone-parent`, path.dirname(config.clonePath), true));
+                if (githubToken.value) {
+                    try {
+                        const auth = await exec("gh", ["api", "user", "--jq", ".login"], {
+                            allowNonZero: true,
+                            env: {
+                                ...process.env,
+                                ...Object.fromEntries(Object.entries(env).filter(([, value]) => value !== undefined)),
+                            },
+                        });
+                        if (auth.exitCode === 0 && auth.stdout.trim()) {
+                            checks.push({ status: "pass", scope: "github-auth", message: `gh authenticated as ${auth.stdout.trim()}` });
+                        }
+                        else {
+                            checks.push({ status: "warn", scope: "github-auth", message: "gh did not confirm the current auth identity" });
+                        }
+                    }
+                    catch (error) {
+                        checks.push({
+                            status: "warn",
+                            scope: "github-auth",
+                            message: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+            }
+            catch (error) {
+                checks.push({
+                    status: "fail",
+                    scope: `repo:${repoId}`,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    const ok = checks.every((check) => check.status !== "fail");
+    if (parsed.flags.get("json") === true) {
+        writeOutput(stdout, formatJson({ ok, checks, ...(repoConfigPath ? { repoConfigPath } : {}) }));
+        return ok ? 0 : 1;
+    }
+    writeOutput(stdout, `${checks.map((check) => `[${check.status}] ${check.scope}: ${check.message}`).join("\n")}\n`);
+    return ok ? 0 : 1;
+}

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

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