@iann29/synapse 1.7.0 → 1.8.0

package/lib/doctor/runner.js

@@ -0,0 +1,148 @@
+// Runs the doctor checks with the DAG defined in checks.js (each
+// check declares its `dependsOn` ids). Within a tier, checks run in
+// parallel via Promise.all; dependent checks wait on their prereqs.
+//
+// The orchestrator produces a stable DoctorReport — same tree feeds
+// both the human renderer and `--json`.
+
+const { ALL_CHECKS } = require("./checks");
+
+const SCHEMA_VERSION = "1.0";
+
+async function runChecks(checks, ctx) {
+  // Topological execution: for each check, wait for its dependencies
+  // (already-resolved CheckResults) before invoking run(). Failed or
+  // skipped prereqs cascade to skipped state (don't run the dependent).
+  const resultsById = new Map();
+  const order = []; // preserve insertion order for the final report
+  // Resolve sequentially through the catalog — checks declared earlier
+  // become available as deps for later ones. Inside a "tier" we still
+  // get the parallel benefit because awaiting an already-resolved
+  // result is a microtask, not a roundtrip.
+  for (const check of checks) {
+    order.push(check.id);
+  }
+
+  // First pass: kick off every check whose dependencies are all "ok"
+  // or "warn"; cascade-skip the rest.
+  const pending = new Map();
+  for (const check of checks) {
+    pending.set(check.id, check);
+  }
+  while (pending.size > 0) {
+    let advanced = false;
+    for (const [id, check] of pending) {
+      const depsResolved = (check.dependsOn || []).every((d) => resultsById.has(d));
+      if (!depsResolved) continue;
+      const failedDeps = (check.dependsOn || []).filter((d) => {
+        const r = resultsById.get(d);
+        return r.status === "issue" || r.status === "skipped";
+      });
+      if (failedDeps.length > 0) {
+        resultsById.set(id, {
+          id,
+          category: check.category,
+          title: check.title,
+          status: "skipped",
+          summary: `skipped (prereq failed: ${failedDeps.join(", ")})`,
+          data: { skippedBecause: failedDeps },
+          durationMs: 0,
+        });
+        pending.delete(id);
+        advanced = true;
+        continue;
+      }
+      const result = await check.run(ctx);
+      resultsById.set(id, {
+        id,
+        category: check.category,
+        title: check.title,
+        ...result,
+      });
+      pending.delete(id);
+      advanced = true;
+    }
+    if (!advanced) {
+      // Cycle in deps — should never happen; bail to avoid an infinite
+      // loop. Mark anything still pending as a hard error.
+      for (const [id, check] of pending) {
+        resultsById.set(id, {
+          id,
+          category: check.category,
+          title: check.title,
+          status: "issue",
+          summary: `cycle in dependsOn: ${(check.dependsOn || []).join(", ")}`,
+          durationMs: 0,
+        });
+      }
+      break;
+    }
+  }
+
+  return order.map((id) => resultsById.get(id));
+}
+
+function totalize(results) {
+  const t = { ok: 0, warn: 0, issue: 0, skipped: 0, fixed: 0 };
+  for (const r of results) {
+    if (r.fixedBy) t.fixed += 1;
+    if (r.status === "ok") t.ok += 1;
+    else if (r.status === "warn") t.warn += 1;
+    else if (r.status === "issue") t.issue += 1;
+    else if (r.status === "skipped") t.skipped += 1;
+  }
+  return t;
+}
+
+function exitCodeFor(totals) {
+  if (totals.issue > 0) return 2;
+  if (totals.warn > 0) return 1;
+  return 0;
+}
+
+async function applyAutoFixes(results, checks, ctx, { allowPrompt = false } = {}) {
+  // Walk results, find non-ok ones whose check has autoFix=auto (or
+  // prompt + allowPrompt=true), invoke the fix, re-run THAT check.
+  // Stays simple: one fix pass, no recursive heal-then-recheck loops.
+  const byId = new Map(checks.map((c) => [c.id, c]));
+  for (const r of results) {
+    if (r.status === "ok" || r.status === "skipped") continue;
+    const check = byId.get(r.id);
+    if (!check || typeof check.fix !== "function") continue;
+    if (check.autoFix === "never") continue;
+    if (check.autoFix === "prompt" && !allowPrompt) continue;
+    const fixOutcome = await check.fix(ctx, r);
+    if (fixOutcome.kind === "applied") {
+      // Re-run the check; if it's green now, mark fixedBy.
+      const fresh = await check.run(ctx);
+      Object.assign(r, fresh, { fixedBy: fixOutcome.message });
+    } else if (fixOutcome.kind === "failed") {
+      r.detail = (r.detail ? r.detail + "\n" : "") + `fix attempt failed: ${fixOutcome.message}`;
+    }
+  }
+}
+
+async function generateReport(ctx, { fix = false, allowPrompt = false } = {}) {
+  const t0 = Date.now();
+  const results = await runChecks(ALL_CHECKS, ctx);
+  if (fix) {
+    await applyAutoFixes(results, ALL_CHECKS, ctx, { allowPrompt });
+  }
+  const totals = totalize(results);
+  const exitCode = exitCodeFor(totals);
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    cliVersion: require("../../package.json").version,
+    env: {
+      cwd: ctx.cwd,
+      synapseUrl: ctx.cfg?.baseUrl ?? null,
+      user: ctx.cfg?.user?.email ?? null,
+    },
+    results,
+    totals,
+    durationMs: Date.now() - t0,
+    exitCode,
+  };
+}
+
+module.exports = { runChecks, totalize, exitCodeFor, applyAutoFixes, generateReport, SCHEMA_VERSION };

package/lib/output.js

@@ -0,0 +1,140 @@
+// Shared output layer for every synapse CLI command.
+//
+// Every handler writes through `createOutput()` instead of poking
+// process.stdout directly. This is the only thing that makes `--json`
+// honest: in JSON mode the renderer never emits ANSI codes, partial
+// human strings, or stray progress lines that would corrupt a piped
+// script's parse.
+//
+// Contract:
+//   - `result(data, renderHuman)` is THE command result. In JSON mode
+//     emits `JSON.stringify(data)` to stdout. In human mode invokes
+//     renderHuman(data, ctx).
+//   - `info`/`warn` are side-channel status (progress, hints). They go
+//     to stderr and are SUPPRESSED entirely in JSON mode so a piped
+//     `--json` stream stays parse-clean.
+//   - `error(msg, { hint })` writes to stderr. In JSON mode emits
+//     `{error, hint}` so scripts can branch on it.
+//   - `table(rows, columns)` is a small helper that lays out aligned
+//     columns in human mode; in JSON mode the caller passes `rows`
+//     directly to `result()` instead.
+
+const colors = require("./colors");
+
+function createOutput({
+  json = false,
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  function writeOut(s) {
+    stdout.write(s);
+  }
+  function writeErr(s) {
+    stderr.write(s);
+  }
+
+  return {
+    json,
+    stdout,
+    stderr,
+
+    // The command's structured result. JSON mode emits a single line.
+    // Human mode delegates rendering — the renderer is free to write
+    // tables, multi-line copy, colors, anything. Callers MUST supply
+    // a renderer; commands with no useful human output should pass a
+    // no-op (`() => {}`) explicitly so the JSON-vs-human split stays
+    // obvious in code review.
+    result(data, renderHuman) {
+      if (this.json) {
+        writeOut(JSON.stringify(data) + "\n");
+        return;
+      }
+      renderHuman(data, { stdout, stderr });
+    },
+
+    // Progress / status. Suppressed under --json so a piped consumer
+    // never sees mixed JSON and prose on stdout.
+    info(msg) {
+      if (this.json) return;
+      writeErr(msg + "\n");
+    },
+
+    warn(msg) {
+      if (this.json) return;
+      writeErr(colors.yellow("Warning: ") + msg + "\n");
+    },
+
+    // Fatal-ish error message. Returns nothing — callers throw or
+    // set process.exitCode on their own to control control flow.
+    // The dispatcher's top-level catch is the canonical exit path.
+    error(msg, { hint } = {}) {
+      if (this.json) {
+        writeErr(JSON.stringify({ error: msg, ...(hint ? { hint } : {}) }) + "\n");
+        return;
+      }
+      writeErr(colors.red("Error: ") + msg + "\n");
+      if (hint) writeErr(colors.dim("Hint: ") + hint + "\n");
+    },
+
+    // Lightweight column-aligned table renderer for human mode.
+    // `columns` is [{ key, header, align?, color? }]. `align` is
+    // "left" (default) or "right". `color` is a colors.* function
+    // applied per-cell after the value is stringified.
+    //
+    // In JSON mode the function is a no-op — callers should hand the
+    // raw rows array to `result()` instead.
+    table(rows, columns) {
+      if (this.json) return;
+      if (!rows || rows.length === 0) {
+        writeOut(colors.dim("(no rows)\n"));
+        return;
+      }
+      const widths = columns.map((c) => c.header.length);
+      const cells = rows.map((row) =>
+        columns.map((c, i) => {
+          const raw = row[c.key];
+          const text = raw == null ? "" : String(raw);
+          if (text.length > widths[i]) widths[i] = text.length;
+          return text;
+        }),
+      );
+      const fmt = (text, w, align) =>
+        align === "right" ? text.padStart(w) : text.padEnd(w);
+      const header = columns
+        .map((c, i) => colors.dim(fmt(c.header, widths[i], c.align)))
+        .join("  ");
+      writeOut(header + "\n");
+      writeOut(
+        colors.dim(widths.map((w) => "─".repeat(w)).join("  ")) + "\n",
+      );
+      for (const row of cells) {
+        const line = row
+          .map((cell, i) => {
+            const padded = fmt(cell, widths[i], columns[i].align);
+            return columns[i].color ? columns[i].color(padded) : padded;
+          })
+          .join("  ");
+        writeOut(line + "\n");
+      }
+    },
+  };
+}
+
+// Detects `--json` from an args vector and returns
+// `{ json: boolean, rest: string[] }` so handlers can strip the flag
+// before parsing their own positionals. Bash/CI scripts commonly
+// pass `--json` in any position; we accept it anywhere.
+function extractJsonFlag(argv) {
+  const rest = [];
+  let json = false;
+  for (const a of argv) {
+    if (a === "--json") {
+      json = true;
+    } else {
+      rest.push(a);
+    }
+  }
+  return { json, rest };
+}
+
+module.exports = { createOutput, extractJsonFlag };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iann29/synapse",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Thin CLI wrapper for using the official Convex CLI with Synapse-managed deployments.",
   "license": "Apache-2.0",
   "repository": {