@moor-sh/mcp 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moor-sh/mcp",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "MCP server for moor - lets AI agents (Claude Code, Cursor, etc.) manage your moor projects via the moor HTTP API.",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -810,22 +810,27 @@ server.registerTool(
   },
 );
 
-// #80 PR #4: moor_update_apply — kick off a transient-respawner update of
+// #80: moor_update_apply — kick off a transient-respawner update of
 // moor itself. The respawner runs async; this tool returns the audit_id
-// immediately. Poll moor_update_status (or, eventually, moor_update_audit)
-// for the outcome.
+// immediately. Poll moor_update_audit (history of attempts) or
+// moor_update_status (version change) for the outcome.
 //
-// IMPORTANT: PR #4 has no rollback. A failed compose-up / --wait timeout /
-// health check writes a `failed` marker and exits; compose state is left
-// as Compose left it. Recovery: manual `docker compose up`, OR wait for the
-// 30-min stale-in_progress sweep to reclaim the audit row. Automatic
-// rollback (retag + `--pull never`) lands in PR #5.
+// Outcomes (encoded in the audit row's `state` field, surfaced by
+// moor_update_audit):
+//   - success         : new image is healthy.
+//   - failed          : pull failed before moor was replaced (no rollback).
+//   - rolled_back     : up/health failed; rollback to prev image succeeded.
+//   - rollback_failed : up/health failed AND rollback also failed —
+//                       operator must investigate (manual recovery).
+//   - in_progress     : respawner still running.
+//   - crashed         : 30-min grace elapsed without a marker
+//                       (respawner died or moor never read the marker).
 server.registerTool(
   "moor_update_apply",
   {
     title: "Apply moor update (transient respawner)",
     description:
-      "Update moor in-place via a transient respawner container. Runs preflight, enables drain, takes a fresh DB backup, then launches a one-shot Compose-aware respawner that pulls + re-creates the moor service. The respawner writes a marker file when done; this tool returns the audit_id immediately so the caller can poll. PR #4 happy path ONLY — no automatic rollback. A failed up/health writes `failed` and leaves the compose state; recovery may require manual `docker compose up`. Bypass is per-blocker: pass {bypass:['active_work']} to interrupt in-flight builds/execs/crons via the existing shutdown coordinator; {bypass:['unknown_digest']} when the registry comparison was inconclusive. Backup is mandatory and not bypassable.",
+      "Update moor in-place via a transient respawner container. Runs preflight, enables drain, takes a fresh DB backup, then launches a one-shot Compose-aware respawner that pulls + re-creates the moor service. The respawner writes a marker file when done; this tool returns the audit_id immediately so the caller can poll via moor_update_audit. Outcomes: success | failed (pull failed pre-replacement) | rolled_back (up/health failed, automatic rollback succeeded) | rollback_failed (rollback also failed — manual recovery needed) | crashed (no marker after 30-min grace). Bypass is per-blocker: pass {bypass:['active_work']} to interrupt in-flight builds/execs/crons via the existing shutdown coordinator; {bypass:['unknown_digest']} when the registry comparison was inconclusive. Backup is mandatory and not bypassable.",
     inputSchema: z.object({
       target_digest: z
         .string()
@@ -850,7 +855,13 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: `Update started: audit_id=${audit_id}. Respawner is running async. Poll moor_update_status to watch the version change. Expected transitions: in_progress → success (clean apply) or → failed (compose/health failure; PR #4 has no rollback so the compose state is left where Compose left it). If the new moor never becomes healthy enough to ingest the marker, the audit row may stay in_progress until the 30-min stale sweep marks it crashed — at which point manual recovery (docker compose up) may be required.`,
+            text: `Update started: audit_id=${audit_id}. Respawner is running async. Poll moor_update_audit to watch the outcome, or moor_update_status to watch the version. Possible terminal states:
+  - success         (new image healthy)
+  - failed          (pull failed before moor was replaced)
+  - rolled_back     (up/health failed; automatic rollback succeeded; drain stays on)
+  - rollback_failed (up/health failed AND rollback failed; manual recovery)
+  - crashed         (no marker after 30-min grace; respawner died)
+Recovery: rolled_back means moor is on the previous image again; the failed update is captured in error_log. rollback_failed or crashed mean an operator should investigate (likely manual docker compose up).`,
           },
         ],
       };
@@ -868,6 +879,57 @@ server.registerTool(
   },
 );
 
+// #80 PR #6: moor_update_audit — recent history of moor_update_apply
+// attempts. Read-only diagnostic; the orchestration lives entirely on
+// the moor side. Tail-truncates error_log / rollback_error per-field
+// so a crashed update with a long error doesn't blow up the token
+// budget; opt in to a larger tail when actively debugging.
+//
+// Rendering helpers (shortDigest / fmtDuration / tailLog / renderAuditRow
+// / renderAuditList) live in ./update-audit-render and are unit-tested
+// directly — this tool is a thin shell around them.
+import { MAX_LOG_TAIL_BYTES, renderAuditList, type UpdateAuditApiRow } from "./update-audit-render";
+
+server.registerTool(
+  "moor_update_audit",
+  {
+    title: "Update history (audit log)",
+    description:
+      "Read-only: recent moor_update_apply attempts and their outcomes. Each row shows audit_id, state (success | failed | rolled_back | rollback_failed | in_progress | crashed), duration, digest deltas, backup path, and any error logs. error_log preserves the ORIGINAL apply failure (never overwritten by rollback step details); rollback_error is set only on rollback_failed. Default tail is 4 KiB per log field; pass tail_bytes=0 to omit log bodies entirely (keeps the metadata line and replaces the body with a sized marker), or up to 16384 to read more.",
+    inputSchema: z.object({
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe("How many most-recent attempts to return. Default 20, max 200."),
+      tail_bytes: z
+        .number()
+        .int()
+        .min(0)
+        .max(MAX_LOG_TAIL_BYTES)
+        .optional()
+        .describe(
+          "Max bytes of error_log and rollback_error returned inline per row. Default 4096 (4 KiB). 0 to omit log bodies entirely; 16384 max.",
+        ),
+    }),
+  },
+  async ({ limit, tail_bytes }) => {
+    const qs = new URLSearchParams();
+    if (limit !== undefined) qs.set("limit", String(limit));
+    const path = qs.toString()
+      ? `/api/server/update/audit?${qs.toString()}`
+      : "/api/server/update/audit";
+    const res = await apiGet(path);
+    if (!res.ok) throw new Error(`update audit failed: ${res.status} ${await res.text()}`);
+    const { rows } = (await res.json()) as { rows: UpdateAuditApiRow[] };
+    return {
+      content: [{ type: "text", text: renderAuditList(rows, { tail_bytes }) }],
+    };
+  },
+);
+
 server.registerTool(
   "moor_cleanup_plan",
   {

package/src/update-audit-render.test.ts

@@ -0,0 +1,171 @@
+// Tests for the moor_update_audit renderer. Pure functions — no
+// network, no DB. Lives next to its consumer so the formatting
+// operators actually see has direct test coverage.
+
+import { describe, expect, test } from "bun:test";
+import {
+  DEFAULT_LOG_TAIL_BYTES,
+  fmtDuration,
+  MAX_LOG_TAIL_BYTES,
+  renderAuditList,
+  renderAuditRow,
+  shortDigest,
+  tailLog,
+  type UpdateAuditApiRow,
+} from "./update-audit-render";
+
+function row(overrides: Partial<UpdateAuditApiRow> = {}): UpdateAuditApiRow {
+  return {
+    id: 1,
+    state: "success",
+    started_at: "2026-05-25 00:00:00",
+    duration_ms: 50_000,
+    from_digest: `sha256:${"a".repeat(64)}`,
+    to_digest: `sha256:${"b".repeat(64)}`,
+    prev_image_id: `sha256:${"c".repeat(64)}`,
+    backup_path: "/app/data/moor.db.backup-1",
+    error_log: null,
+    rollback_error: null,
+    ...overrides,
+  };
+}
+
+describe("shortDigest", () => {
+  test("formats sha256:<64 hex> as sha256:<7>…<7>", () => {
+    expect(shortDigest(`sha256:${"a".repeat(64)}`)).toBe(
+      `sha256:${"a".repeat(7)}…${"a".repeat(7)}`,
+    );
+  });
+  test("strips the repo prefix from repo@sha256:... form", () => {
+    expect(shortDigest(`ghcr.io/caiopizzol/moor@sha256:${"b".repeat(64)}`)).toBe(
+      `sha256:${"b".repeat(7)}…${"b".repeat(7)}`,
+    );
+  });
+  test("non-digest input passes through unchanged", () => {
+    expect(shortDigest("sha256:short")).toBe("sha256:short");
+    expect(shortDigest("not-a-digest")).toBe("not-a-digest");
+  });
+  test("null/undefined → '(none)'", () => {
+    expect(shortDigest(null)).toBe("(none)");
+    expect(shortDigest(undefined)).toBe("(none)");
+  });
+});
+
+describe("fmtDuration", () => {
+  test("null → em dash", () => expect(fmtDuration(null)).toBe("—"));
+  test("sub-second values in ms", () => expect(fmtDuration(420)).toBe("420ms"));
+  test("seconds for [1s, 60s)", () => expect(fmtDuration(50_000)).toBe("50s"));
+  test("minutes+seconds at and above 60s", () => {
+    expect(fmtDuration(60_000)).toBe("1m0s");
+    expect(fmtDuration(125_000)).toBe("2m5s");
+  });
+});
+
+describe("tailLog", () => {
+  test("null/undefined → '' (no field rendered by caller)", () => {
+    expect(tailLog(null, 100)).toBe("");
+    expect(tailLog(undefined, 100)).toBe("");
+  });
+  test("short string passes through unchanged", () => {
+    expect(tailLog("short", 100)).toBe("short");
+  });
+  test("long string is tail-truncated with a visible marker", () => {
+    const big = "x".repeat(10_000);
+    const out = tailLog(big, 1000);
+    expect(out).toContain("[...9000 earlier bytes truncated]");
+    expect(out.endsWith("x".repeat(1000))).toBe(true);
+  });
+  test("tail_bytes=0 elides the field body entirely with a sized marker", () => {
+    const out = tailLog("hello world", 0);
+    expect(out).toBe("[...11 bytes elided (tail_bytes=0)]");
+  });
+  test("tail_bytes=0 on null/undefined → ''", () => {
+    expect(tailLog(null, 0)).toBe("");
+    expect(tailLog(undefined, 0)).toBe("");
+  });
+});
+
+describe("renderAuditRow", () => {
+  test("success: includes id, state, duration, from/to, backup; no error_log line", () => {
+    const out = renderAuditRow(row());
+    expect(out).toContain("audit_id=1");
+    expect(out).toContain("state=success");
+    expect(out).toContain("duration=50s");
+    expect(out).toContain("from: sha256:aaaaaaa");
+    expect(out).toContain("to: sha256:bbbbbbb");
+    expect(out).toContain("prev_image_id: sha256:ccccccc");
+    expect(out).toContain("backup: /app/data/moor.db.backup-1");
+    expect(out).not.toContain("error_log");
+    expect(out).not.toContain("rollback_error");
+  });
+
+  test("rolled_back: error_log shown, rollback_error omitted", () => {
+    const out = renderAuditRow(row({ state: "rolled_back", error_log: "health check failed" }));
+    expect(out).toContain("state=rolled_back");
+    expect(out).toContain("error_log: health check failed");
+    expect(out).not.toContain("rollback_error");
+  });
+
+  test("rollback_failed: BOTH error_log and rollback_error rendered", () => {
+    const out = renderAuditRow(
+      row({
+        state: "rollback_failed",
+        error_log: "apply up failed",
+        rollback_error: "rollback tag failed",
+      }),
+    );
+    expect(out).toContain("state=rollback_failed");
+    expect(out).toContain("error_log: apply up failed");
+    expect(out).toContain("rollback_error: rollback tag failed");
+  });
+
+  test("tail_bytes truncates long error_log per-field with marker", () => {
+    const long = "X".repeat(5000);
+    const out = renderAuditRow(row({ error_log: long }), { tail_bytes: 100 });
+    expect(out).toContain("[...4900 earlier bytes truncated]");
+  });
+
+  test("tail_bytes=0 elides log body but keeps the field line", () => {
+    const out = renderAuditRow(row({ error_log: "anything" }), { tail_bytes: 0 });
+    expect(out).toContain("error_log: [...");
+    expect(out).toContain("bytes elided (tail_bytes=0)");
+    expect(out).not.toContain("anything");
+  });
+
+  test("tail_bytes is clamped to MAX_LOG_TAIL_BYTES", () => {
+    // No assertion against the actual byte count; just verify the
+    // constant is honored and the function tolerates an over-cap input.
+    expect(MAX_LOG_TAIL_BYTES).toBeGreaterThan(DEFAULT_LOG_TAIL_BYTES);
+    const long = "Y".repeat(MAX_LOG_TAIL_BYTES + 1000);
+    const out = renderAuditRow(row({ error_log: long }), { tail_bytes: 999_999 });
+    expect(out).toContain("earlier bytes truncated");
+  });
+
+  test("prev_image_id null → no prev line", () => {
+    const out = renderAuditRow(row({ prev_image_id: null }));
+    expect(out).not.toContain("prev_image_id");
+  });
+
+  test("backup_path null → no backup line", () => {
+    const out = renderAuditRow(row({ backup_path: null }));
+    expect(out).not.toContain("backup:");
+  });
+
+  test("non-digest from/to (rare edge) passes through via shortDigest fallback", () => {
+    const out = renderAuditRow(row({ from_digest: "weird", to_digest: null }));
+    expect(out).toContain("from: weird");
+    expect(out).toContain("to: (none)");
+  });
+});
+
+describe("renderAuditList", () => {
+  test("empty → friendly hint", () => {
+    expect(renderAuditList([])).toContain("no update attempts recorded yet");
+  });
+  test("multi-row separated by blank line", () => {
+    const out = renderAuditList([row({ id: 2 }), row({ id: 1 })]);
+    expect(out.split("\n\n").length).toBe(2);
+    expect(out).toContain("audit_id=2");
+    expect(out).toContain("audit_id=1");
+  });
+});

package/src/update-audit-render.ts

@@ -0,0 +1,94 @@
+// #80 PR #6: pure renderers for moor_update_audit. Lives next to its
+// consumer (the MCP tool) so the formatting that operators actually
+// see has direct test coverage.
+//
+// Each row renders as a multi-line block with id, state, duration,
+// digest deltas, prev_image_id, backup path, and per-field tailed
+// error_log / rollback_error.
+
+/** API row shape returned by GET /api/server/update/audit. Subset of
+ *  the full DB row — only what the renderer needs. */
+export type UpdateAuditApiRow = {
+  id: number;
+  state: string;
+  started_at: string;
+  duration_ms: number | null;
+  from_digest: string | null;
+  to_digest: string | null;
+  prev_image_id: string | null;
+  backup_path: string | null;
+  error_log: string | null;
+  rollback_error: string | null;
+};
+
+export const DEFAULT_LOG_TAIL_BYTES = 4096;
+export const MAX_LOG_TAIL_BYTES = 16384;
+
+/** Pure: short-form a sha256 digest for compact rendering (first 7 +
+ *  last 7). Accepts both raw `sha256:<hex>` and `repo@sha256:<hex>`
+ *  forms; returns the input unchanged on anything else. */
+export function shortDigest(s: string | null | undefined): string {
+  if (!s) return "(none)";
+  const m = s.match(/^(?:[^@]+@)?sha256:([0-9a-f]{64})$/);
+  if (!m) return s;
+  const hex = m[1];
+  return `sha256:${hex.slice(0, 7)}…${hex.slice(-7)}`;
+}
+
+/** Pure: human-readable duration. Mirrors the format moor_runs uses. */
+export function fmtDuration(ms: number | null): string {
+  if (ms == null) return "—";
+  if (ms < 1000) return `${ms}ms`;
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  const rem = s % 60;
+  return `${m}m${rem}s`;
+}
+
+/** Pure: tail-truncate a string to maxBytes with a visible marker.
+ *  maxBytes=0 means omit the field body entirely (returns the marker
+ *  alone). Used per-field for error_log + rollback_error so a
+ *  crashed update with a long log doesn't blow up the token budget. */
+export function tailLog(s: string | null | undefined, maxBytes: number): string {
+  if (s == null) return "";
+  if (maxBytes <= 0) {
+    const enc = new TextEncoder();
+    return `[...${enc.encode(s).length} bytes elided (tail_bytes=0)]`;
+  }
+  const enc = new TextEncoder();
+  const bytes = enc.encode(s);
+  if (bytes.length <= maxBytes) return s;
+  const dropped = bytes.length - maxBytes;
+  const tail = new TextDecoder("utf-8", { fatal: false }).decode(bytes.subarray(dropped));
+  return `[...${dropped} earlier bytes truncated]\n${tail}`;
+}
+
+/** Pure: render one audit row. tail_bytes applies separately to
+ *  error_log and rollback_error; absent fields are skipped. */
+export function renderAuditRow(row: UpdateAuditApiRow, opts: { tail_bytes?: number } = {}): string {
+  const tail = Math.min(opts.tail_bytes ?? DEFAULT_LOG_TAIL_BYTES, MAX_LOG_TAIL_BYTES);
+  const lines: string[] = [
+    `audit_id=${row.id} state=${row.state} duration=${fmtDuration(row.duration_ms)} started=${row.started_at}`,
+    `  from: ${shortDigest(row.from_digest)} → to: ${shortDigest(row.to_digest)}`,
+  ];
+  if (row.prev_image_id) lines.push(`  prev_image_id: ${shortDigest(row.prev_image_id)}`);
+  if (row.backup_path) lines.push(`  backup: ${row.backup_path}`);
+  if (row.error_log) lines.push(`  error_log: ${tailLog(row.error_log, tail)}`);
+  if (row.rollback_error) {
+    lines.push(`  rollback_error: ${tailLog(row.rollback_error, tail)}`);
+  }
+  return lines.join("\n");
+}
+
+/** Pure: render a list of rows separated by a blank line. Empty list
+ *  returns the documented "no updates yet" string. */
+export function renderAuditList(
+  rows: UpdateAuditApiRow[],
+  opts: { tail_bytes?: number } = {},
+): string {
+  if (rows.length === 0) {
+    return "no update attempts recorded yet. Run moor_update_apply to start one.";
+  }
+  return rows.map((r) => renderAuditRow(r, opts)).join("\n\n");
+}