@iann29/synapse 1.6.17 → 1.8.0

package/lib/doctor/renderer.js

@@ -0,0 +1,93 @@
+// Human-mode renderer for the DoctorReport. JSON mode lives in the
+// command file; this is purely the terminal pretty-printer.
+
+const colors = require("../colors");
+
+const SYMBOL = {
+  ok: "✓",
+  warn: "!",
+  issue: "✗",
+  skipped: "·",
+};
+const TONE = {
+  ok: colors.green,
+  warn: colors.yellow,
+  issue: colors.red,
+  skipped: colors.dim,
+};
+
+const CATEGORY_TITLE = {
+  "local-env": "Local environment",
+  project: "Project",
+  backend: "Backend",
+  deployments: "Deployments",
+  upstream: "Upstream",
+  workspace: "Workspace",
+};
+const CATEGORY_ORDER = ["local-env", "project", "backend", "deployments", "upstream", "workspace"];
+
+function renderHeader(report, write) {
+  const parts = ["Synapse doctor"];
+  if (report.env.synapseUrl) parts.push(colors.dim(`· ${report.env.synapseUrl}`));
+  if (report.env.user) parts.push(colors.dim(`· ${report.env.user}`));
+  write(parts.join(" ") + "\n\n");
+}
+
+function renderCheck(r, { verbose }, write) {
+  const sym = TONE[r.status](SYMBOL[r.status]);
+  write(`    ${sym} ${r.title}`);
+  if (r.summary) write(colors.dim(` — ${r.summary}`));
+  if (r.fixedBy) write(`  ${colors.cyan ? colors.cyan("↻ " + r.fixedBy) : "↻ " + r.fixedBy}`);
+  write("\n");
+  if (r.remediation && (r.status === "issue" || r.status === "warn")) {
+    write(colors.dim(`        → ${r.remediation}\n`));
+  }
+  if (verbose && r.detail) {
+    write(colors.dim(`        ${r.detail.replace(/\n/g, "\n        ")}\n`));
+  }
+}
+
+function renderReport(report, { stdout, verbose = false } = {}) {
+  const write = (s) => stdout.write(s);
+  renderHeader(report, write);
+
+  const byCategory = new Map();
+  for (const r of report.results) {
+    if (!byCategory.has(r.category)) byCategory.set(r.category, []);
+    byCategory.get(r.category).push(r);
+  }
+
+  for (const cat of CATEGORY_ORDER) {
+    const rows = byCategory.get(cat);
+    if (!rows || rows.length === 0) continue;
+    write(`  ${colors.bold(CATEGORY_TITLE[cat] ?? cat)}\n`);
+    for (const r of rows) renderCheck(r, { verbose }, write);
+    write("\n");
+  }
+
+  // Categories outside the canonical order (defensive — keeps the
+  // report honest if a check is added without updating CATEGORY_ORDER).
+  for (const [cat, rows] of byCategory) {
+    if (CATEGORY_ORDER.includes(cat)) continue;
+    write(`  ${colors.bold(cat)}\n`);
+    for (const r of rows) renderCheck(r, { verbose }, write);
+    write("\n");
+  }
+
+  const t = report.totals;
+  const summary = [
+    t.ok > 0 ? colors.green(`${t.ok} ok`) : null,
+    t.warn > 0 ? colors.yellow(`${t.warn} warn`) : null,
+    t.issue > 0 ? colors.red(`${t.issue} issue${t.issue > 1 ? "s" : ""}`) : null,
+    t.skipped > 0 ? colors.dim(`${t.skipped} skipped`) : null,
+    t.fixed > 0 ? colors.cyan ? colors.cyan(`${t.fixed} fixed`) : `${t.fixed} fixed` : null,
+  ]
+    .filter(Boolean)
+    .join(" · ");
+  write(`  ${summary} · ${report.durationMs}ms\n`);
+  if (report.exitCode !== 0) {
+    write(`  ${colors.dim("exit " + report.exitCode)}\n`);
+  }
+}
+
+module.exports = { renderReport };

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/lib/prompts.js

@@ -1,5 +1,10 @@
 const readline = require("node:readline");
 
+// Sentinel returned by `choose` when the user asks to go back to the
+// previous step. Use a Symbol so it can never collide with a legitimate
+// choice payload.
+const BACK = Symbol("synapse-choose-back");
+
 function ask(question, { input = process.stdin, output = process.stderr } = {}) {
   const rl = readline.createInterface({ input, output });
   return new Promise((resolve) => {
@@ -89,12 +94,69 @@ async function askCredentials({ input = process.stdin, output = process.stderr }
   };
 }
 
-async function choose(label, choices, { input = process.stdin, output = process.stderr } = {}) {
+// confirm prompts the user with a yes/no question and resolves to a boolean.
+//
+// - Empty answer applies `defaultAnswer` (so `[y/N]` matches "no by default"
+//   and `[Y/n]` matches "yes by default"). The hint in the question is the
+//   caller's responsibility — we render the prompt literally.
+// - "y" / "yes" / "n" / "no" (case-insensitive) are accepted.
+// - Anything else re-prompts with a tip, capped at `maxAttempts` to keep
+//   pasted-shell-history scenarios from looping forever.
+// - Non-interactive callers (no TTY) cannot disambiguate — they must use a
+//   skip-confirmation flag at the call site instead of relying on `confirm`.
+//
+// We open a single readline interface for the whole prompt session.
+// Calling `ask()` multiple times would re-create the interface and re-bind
+// `data` listeners on the input stream — which is fine for real stdin but
+// produces flaky behaviour on a buffered PassThrough where the second
+// listener can't see data the first consumed. One rl, multiple questions.
+async function confirm(question, {
+  input = process.stdin,
+  output = process.stderr,
+  defaultAnswer = false,
+  maxAttempts = 3,
+} = {}) {
+  const rl = readline.createInterface({ input, output });
+  try {
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      const raw = await new Promise((resolve) => rl.question(question, resolve));
+      const answer = raw.trim().toLowerCase();
+      if (answer === "") return defaultAnswer;
+      if (answer === "y" || answer === "yes") return true;
+      if (answer === "n" || answer === "no") return false;
+      output.write("Please answer y or n.\n");
+    }
+    throw new Error("Confirmation prompt cancelled after too many invalid answers");
+  } finally {
+    rl.close();
+  }
+}
+
+// choose prompts the user to pick one of `choices`.
+//
+// - `label` is the plural noun used for the menu header ("dev deployments").
+// - `singularLabel` defaults to `label` stripped of a trailing "s" — it's
+//   the noun used when only one option exists and we auto-select silently.
+//   Pass a custom value when the strip heuristic produces something
+//   awkward ("members" → "member" is fine; "people" → "peopl" is not).
+// - `allowBack` lets the user type "b" / "back" / "0" to return the BACK
+//   sentinel, which the caller maps to a previous step.
+// - `maxInvalid` caps how many garbage answers in a row we tolerate
+//   before throwing. Protects against pasted shell history / broken
+//   stdin where the loop would otherwise spin forever.
+async function choose(label, choices, {
+  input = process.stdin,
+  output = process.stderr,
+  singularLabel,
+  allowBack = false,
+  maxInvalid = 3,
+} = {}) {
   if (!Array.isArray(choices) || choices.length === 0) {
     throw new Error(`No ${label} available.`);
   }
+  const singular = singularLabel || label.replace(/s$/, "") || label;
   if (choices.length === 1) {
-    output.write(`Using ${label}: ${choices[0].label}\n`);
+    output.write(`Auto-selected ${singular}: ${choices[0].label} (only one available)\n`);
     return choices[0].value;
   }
 
@@ -103,20 +165,34 @@ async function choose(label, choices, { input = process.stdin, output = process.
     output.write(`  ${index + 1}. ${choice.label}\n`);
   });
 
+  const hint = allowBack
+    ? `[1-${choices.length}, b=back]`
+    : `[1-${choices.length}]`;
+
+  let invalid = 0;
   while (true) {
-    const answer = await ask(`Choose ${label} [1-${choices.length}]: `, { input, output });
+    const answer = (await ask(`Choose ${label} ${hint}: `, { input, output })).trim();
+    if (allowBack && (answer === "b" || answer === "B" || answer === "back" || answer === "0")) {
+      return BACK;
+    }
     const n = Number.parseInt(answer, 10);
     if (Number.isInteger(n) && n >= 1 && n <= choices.length) {
       return choices[n - 1].value;
     }
-    output.write(`Enter a number from 1 to ${choices.length}.\n`);
+    invalid += 1;
+    if (invalid >= maxInvalid) {
+      throw new Error(`Cancelled ${label} prompt after ${invalid} invalid answers`);
+    }
+    output.write(`Enter a number from 1 to ${choices.length}${allowBack ? " (or 'b' to go back)" : ""}.\n`);
   }
 }
 
 module.exports = {
+  BACK,
   ask,
   askCredentials,
   askHidden,
   choose,
+  confirm,
   parseCredentialsInput,
 };

package/package.json

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