@sealant/mend 0.4.0 → 0.6.0

package/README.md

@@ -17,6 +17,58 @@ diffs, reveal whitespace, select line ranges, add line or whole-change comments,
 evidence, and draft a follow-up for the same session. Press `y` to deliver a pending follow-up and
 relaunch that session, or `o` to continue the review in the web app.
 
+## Getting started
+
+Once per machine, in this order:
+
+```sh
+mend login                       # sign in to the server; the token is saved 0600
+mend connect codex               # send this machine's codex (or claude, github) credential
+mend adopt                       # adopt the repository you are standing in
+mend codex "fix the flaky test"  # new session worktree, harness running in it
+mend pair                        # hand a phone the same server
+mend doctor                      # every fact above, on one screen
+```
+
+`mend help` prints the same sequence under `start`, then everything else.
+
+### mend pair
+
+```
+mend pair [--url <base url>]
+```
+
+Asks the server for a pairing code and prints it three ways: a QR of the `mend://pair` deep link,
+the code grouped as `ABCD-EFGH`, and the base URL the device should reach — the machine's tailnet
+address when it has one, otherwise a LAN address (`--url` overrides the choice). Scan it in the Mend
+app, or type the URL and the code in by hand. The code is single use and expires in 10 minutes; the
+device's own token is minted when it claims the code, and can be revoked from the Mend app later.
+The device names itself when it claims the code.
+
+### mend doctor
+
+```
+mend doctor
+```
+
+Reads, and changes nothing: server reachable, token accepted, the Sealant connection, each connected
+account, adopted projects, the `claude` / `codex` / `gh` CLIs on PATH and whether their credentials
+exist on this machine, and the tailnet address. One line per fact — `✓` observed, `○` not set up
+yet, `✗` a blocker — and every line that needs an action ends with the one command that takes it:
+
+```
+✓ server      http://localhost:3105 · mend 0.5.0
+✓ signed in   token accepted
+✓ sealant     connected · http://127.0.0.1:4000
+✓ claude      connected · you@example.com
+○ codex       not connected → mend connect codex
+✓ projects    2 adopted
+○ gh cli      on PATH · no credential here → gh auth login
+○ tailnet     not detected
+```
+
+It exits 1 when a `✗` is printed, so a setup script can gate on it. No request waits longer than 3s.
+
 ## Commands
 
 ```
@@ -29,6 +81,8 @@ mend resume [session-id] [--with h]   rejoin a settled session (state restored;
 mend rejoin [session-id] [--harness h] attach if live, otherwise resume; newest live wins
 mend sessions [--all] [--project p] [--json]
 mend status                           active sessions (alias of mend sessions)
+mend pair [--url <base url>]          pair a phone or a second machine: QR + code + URL
+mend doctor                           read-only checklist of this machine's setup
 ```
 
 ## Signing in

package/dist/dashboard.js

@@ -5,7 +5,7 @@ import { QueryClient, QueryClientProvider, useQuery, useQueryClient } from "@tan
 import { useEffect, useRef, useState } from "react";
 import { reviewTargetForSession } from "./review-workflow.js";
 import { ReviewScreen } from "./review.js";
-import { HARNESS_COMMANDS, LIVE_STATUSES, matchProjectByCwd } from "./shared.js";
+import { cwdFacts, HARNESS_COMMANDS, LIVE_STATUSES, matchProjectByCwd } from "./shared.js";
 import { openUrl } from "./terminal.js";
 import { AMBER, BG, COBALT, FAINT, GREEN, INK, MUTED, RED, RULE, WASH } from "./tui-theme.js";
 const STATUS_GLYPH = {
@@ -66,7 +66,7 @@ const itemKey = (item) => item.kind === "session"
         : String(item.harness);
 const itemHeight = (view) => (view.kind === "sessions" ? 2 : 1);
 const homeView = (cwd, data) => {
-    const home = matchProjectByCwd(data.projects, cwd);
+    const home = matchProjectByCwd(data.projects, cwdFacts(cwd));
     return home === undefined ? { kind: "projects" } : { kind: "sessions", projectId: home.id };
 };
 const deriveItems = (view, data) => {

package/dist/doctor.js

@@ -0,0 +1,233 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * `mend doctor`: one read-only pass over everything a first run depends on, printed
+ * as mono status lines (DESIGN.md §4 — a mark plus a word, never a badge). Every
+ * line states what was observed; a line that needs an action ends with the single
+ * command that takes it. Nothing here writes, launches, or repairs anything.
+ *
+ * No request waits longer than 3s: a doctor that hangs is worse than a doctor that
+ * reports "not checked".
+ */
+const TIMEOUT_MS = 3_000;
+const MARKS = { ok: "✓", todo: "○", failed: "✗" };
+const LABEL_WIDTH = 11;
+/** One status line. The mark is painted by the caller so the formatter stays testable. */
+export const formatCheck = (check, paint = (_state, mark) => mark) => `${paint(check.state, MARKS[check.state])} ${check.label.padEnd(LABEL_WIDTH)} ${check.detail}${check.fix === null ? "" : ` → ${check.fix}`}`;
+/** A read that never throws and never blocks: the outcome is a value the checklist can print. */
+const getJson = async (config, route) => {
+    try {
+        const response = await fetch(`${config.url}/api${route}`, {
+            headers: config.token === null ? {} : { authorization: `Bearer ${config.token}` },
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return { value: null, status: response.status };
+        return { value: (await response.json()), status: response.status };
+    }
+    catch {
+        return { value: null, status: null };
+    }
+};
+/** Where each provider's own CLI writes the credential Mend forwards (mirrors `mend connect`). */
+const LOGIN_COMMANDS = {
+    claude: "claude setup-token",
+    codex: "codex login",
+    github: "gh auth login",
+};
+const HARNESS_CLIS = [
+    { command: "claude", provider: "claude" },
+    { command: "codex", provider: "codex" },
+    { command: "gh", provider: "github" },
+];
+const notChecked = (label) => ({
+    label,
+    state: "todo",
+    detail: "not checked",
+    fix: null,
+});
+const identityOf = (account) => {
+    const meta = account.metadata;
+    for (const key of ["login", "email", "accountEmail", "accountId"]) {
+        const value = meta[key];
+        if (typeof value === "string" && value !== "")
+            return value;
+    }
+    return null;
+};
+/** Every fact the checklist prints, in the order a first run needs them. */
+export const runChecks = async (config, probes) => {
+    const checks = [];
+    const health = await getJson(config, "/health");
+    checks.push(health.value === null
+        ? {
+            label: "server",
+            state: "failed",
+            detail: `cannot reach ${config.url}`,
+            fix: "start the Mend server",
+        }
+        : {
+            label: "server",
+            state: "ok",
+            detail: `${config.url} · mend ${health.value.version}`,
+            fix: null,
+        });
+    // Projects double as the cheapest authenticated read there is: it proves the token
+    // without asking the platform anything.
+    const projects = health.value !== null && config.token !== null
+        ? await getJson(config, "/projects")
+        : null;
+    if (health.value === null)
+        checks.push(notChecked("signed in"));
+    else if (config.token === null) {
+        checks.push({
+            label: "signed in",
+            state: "failed",
+            detail: "no token saved",
+            fix: "mend login",
+        });
+    }
+    else if (projects !== null && projects.value !== null) {
+        checks.push({ label: "signed in", state: "ok", detail: "token accepted", fix: null });
+    }
+    else {
+        const status = projects === null ? null : projects.status;
+        checks.push(status === 401 || status === 403
+            ? { label: "signed in", state: "failed", detail: "token rejected", fix: "mend login" }
+            : {
+                label: "signed in",
+                state: "failed",
+                detail: `GET /projects → ${status ?? "no answer"}`,
+                fix: null,
+            });
+    }
+    const signedIn = projects !== null && projects.value !== null;
+    const connection = signedIn ? await getJson(config, "/sealant/connection") : null;
+    if (connection === null)
+        checks.push(notChecked("sealant"));
+    else if (connection.value === null) {
+        // 404 is a server older than the endpoint: nothing was observed, so nothing is claimed.
+        checks.push(connection.status === 404
+            ? notChecked("sealant")
+            : {
+                label: "sealant",
+                state: "failed",
+                detail: `GET /sealant/connection → ${connection.status ?? "no answer"}`,
+                fix: null,
+            });
+    }
+    else if (connection.value.status === "connected") {
+        checks.push({
+            label: "sealant",
+            state: "ok",
+            detail: `connected · ${connection.value.baseUrl}`,
+            fix: null,
+        });
+    }
+    else {
+        checks.push({
+            label: "sealant",
+            state: "failed",
+            detail: `${connection.value.status} · ${connection.value.detail ?? connection.value.baseUrl}`,
+            fix: null,
+        });
+    }
+    const identity = signedIn ? await getJson(config, "/me/sealant") : null;
+    const platform = identity === null ? null : identity.value;
+    for (const { provider } of HARNESS_CLIS) {
+        if (platform === null) {
+            checks.push(notChecked(provider));
+            continue;
+        }
+        const account = platform.accounts.find((row) => row.provider === provider && row.name === "default") ??
+            platform.accounts.find((row) => row.provider === provider);
+        if (account === undefined) {
+            checks.push({
+                label: provider,
+                state: "todo",
+                detail: "not connected",
+                fix: `mend connect ${provider}`,
+            });
+            continue;
+        }
+        const who = identityOf(account);
+        checks.push(account.status === "active"
+            ? {
+                label: provider,
+                state: "ok",
+                detail: who === null ? "connected" : `connected · ${who}`,
+                fix: null,
+            }
+            : {
+                label: provider,
+                state: "todo",
+                detail: account.status,
+                fix: `mend connect ${provider}`,
+            });
+    }
+    const adopted = projects === null ? null : projects.value;
+    if (adopted === null)
+        checks.push(notChecked("projects"));
+    else if (adopted.length === 0) {
+        checks.push({ label: "projects", state: "todo", detail: "none adopted", fix: "mend adopt" });
+    }
+    else {
+        checks.push({ label: "projects", state: "ok", detail: `${adopted.length} adopted`, fix: null });
+    }
+    for (const { command, provider } of HARNESS_CLIS) {
+        const label = `${command} cli`;
+        if (!probes.onPath(command)) {
+            checks.push({ label, state: "todo", detail: "not on PATH", fix: null });
+            continue;
+        }
+        const credential = probes.localCredential(provider);
+        checks.push(credential === null
+            ? {
+                label,
+                state: "todo",
+                detail: "on PATH · no credential here",
+                fix: LOGIN_COMMANDS[provider],
+            }
+            : { label, state: "ok", detail: "on PATH · credential present", fix: null });
+    }
+    const machine = signedIn ? await getJson(config, "/machine") : null;
+    const tailnet = machine === null || machine.value === null ? null : machine.value.tailnet;
+    if (tailnet === null)
+        checks.push(notChecked("tailnet"));
+    else if (tailnet.status === "reachable" && tailnet.address !== null) {
+        checks.push({ label: "tailnet", state: "ok", detail: tailnet.address, fix: null });
+    }
+    else {
+        checks.push({ label: "tailnet", state: "todo", detail: "not detected", fix: null });
+    }
+    return checks;
+};
+/** An executable of that name on PATH — the question `command -v` asks, without a subprocess. */
+export const onPath = (command) => {
+    for (const directory of (process.env["PATH"] ?? "").split(path.delimiter)) {
+        if (directory === "")
+            continue;
+        try {
+            fs.accessSync(path.join(directory, command), fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            // keep looking
+        }
+    }
+    return false;
+};
+/** Green observed · amber not started · red a blocker (DESIGN.md §4); plain text on a pipe. */
+const paintMark = (state, mark) => {
+    if (process.stdout.isTTY !== true)
+        return mark;
+    const code = state === "ok" ? "32" : state === "todo" ? "33" : "31";
+    return `[${code}m${mark}`;
+};
+export const doctorCommand = async (config, localCredential) => {
+    const checks = await runChecks(config, { localCredential, onPath });
+    for (const check of checks)
+        process.stdout.write(`${formatCheck(check, paintMark)}\n`);
+    if (checks.some((check) => check.state === "failed"))
+        process.exitCode = 1;
+};