@iann29/synapse 1.8.8 → 1.8.10

package/lib/commands/https-setup.js

@@ -240,6 +240,34 @@ Examples:
       process.exitCode = 1;
       return;
     }
+
+    // v1.8.10: post-execute verification. Even after every step
+    // reports ✓ the actual end-state can be wrong — most commonly on
+    // Windows where the DNS Client cache holds a negative response
+    // even after the hosts file is updated. Re-scan and verify the
+    // domain ACTUALLY resolves to 127.0.0.1 (when we wrote hosts).
+    // If it doesn't, surface a yellow warning with a concrete
+    // remediation instead of pretending the setup is healthy.
+    const wroteHosts = results.some(
+      (r) => r.id === "hosts" && r.kind === "ok",
+    );
+    const verifyOk = after.resolution.resolvesToLoopback;
+    if (wroteHosts && !verifyOk && !skipHosts) {
+      summary.verifyResolution = false;
+      summary.verifyHint =
+        detection.platform.id === "windows"
+          ? "Windows DNS Client cache is still serving stale NXDOMAIN for this domain. Run `ipconfig /flushdns` from an Administrator PowerShell, then retry `npm run dev:https`. If it still fails, restart your machine."
+          : "Hosts file was written but the OS resolver still doesn't return 127.0.0.1. Try restarting nscd / systemd-resolved if you use one, or open a new shell.";
+      if (!ctx.out.json) {
+        ctx.out.stdout.write("\n");
+        ctx.out.warn(
+          `${domain} doesn't resolve to 127.0.0.1 yet — ${summary.verifyHint}`,
+        );
+      }
+    } else if (wroteHosts && verifyOk) {
+      summary.verifyResolution = true;
+    }
+
     ctx.out.stdout.write(
       `${colors.green("✓")} ${colors.bold(`HTTPS ready for ${domain}`)}\n`,
     );

package/lib/doctor/checks.js

@@ -634,6 +634,238 @@ function makeDeploymentCheck(target) {
   };
 }
 
+// ============================================================
+// v1.8.9: Local HTTPS dev category. Checks the `synapse https setup`
+// surface — mkcert presence, CA trust, cert file presence + expiry,
+// hostname resolution.
+//
+// These checks are CONTEXT-GATED: they only emit a meaningful result
+// when the operator is in a project that uses dev:https OR has
+// generated certs under ~/.config/dev-certs/. When neither is true,
+// every check returns `silentlySkip: true` in its data, and the
+// renderer hides the whole category — operators in a "no HTTPS
+// here" project don't see a section of dim "skipped" lines.
+//
+// We require the https detect helpers; importing them here is a
+// pure dependency (no side effects at require time).
+// ============================================================
+
+const httpsDetect = require("../https/detect");
+
+// Read the cwd's package.json dev:https script (if any) and extract
+// the --hostname / --experimental-https-cert / --experimental-https-key
+// values. Returns null when there's no script, malformed JSON, or
+// the script isn't recognisable.
+function parseDevHttpsScript(cwd) {
+  const info = httpsDetect.detectPackageJson(cwd);
+  if (!info.present || !info.existingDevHttps) return null;
+  const cmd = info.existingDevHttps;
+  const hostMatch = cmd.match(/--hostname[\s=]+(\S+)/);
+  const certMatch = cmd.match(/--experimental-https-cert[\s=]+(\S+)/);
+  const keyMatch = cmd.match(/--experimental-https-key[\s=]+(\S+)/);
+  if (!hostMatch || !certMatch || !keyMatch) return null;
+  return {
+    domain: hostMatch[1],
+    cert: certMatch[1],
+    key: keyMatch[1],
+    raw: cmd,
+  };
+}
+
+// "Does this operator's machine HAVE any local-HTTPS context?"
+// True when either:
+//   - cwd has a dev:https script, OR
+//   - ~/.config/dev-certs/ has at least one cert pair (any shape)
+//
+// Used as the gate for every check in this category — when it's
+// false, the checks silently skip and the category is hidden.
+function hasLocalHttpsContext(cwd) {
+  const dev = parseDevHttpsScript(cwd);
+  if (dev) return true;
+  // Check the cert store.
+  try {
+    const fs = require("node:fs");
+    const root = httpsDetect.certsRoot();
+    if (!fs.existsSync(root)) return false;
+    const entries = fs.readdirSync(root, { withFileTypes: true });
+    // Either a subdir (canonical) or a .pem pair (flat) means context.
+    if (entries.some((e) => e.isDirectory())) return true;
+    const flat = httpsDetect.detectFlatCertsInStore();
+    return flat.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+const checkHttpsMkcert = {
+  id: "https-mkcert",
+  category: "local-https-dev",
+  title: "mkcert installed",
+  autoFix: "never",
+  dependsOn: [],
+  run: safeRun(async (ctx) => {
+    if (!hasLocalHttpsContext(ctx.cwd)) {
+      return { status: "skipped", summary: "no local HTTPS context", data: { silentlySkip: true } };
+    }
+    const m = httpsDetect.detectMkcert();
+    if (m.present) {
+      return { status: "ok", summary: m.version || "(version unknown)", data: { version: m.version, caroot: m.caroot } };
+    }
+    return {
+      status: "issue",
+      summary: "mkcert not found in PATH",
+      remediation: "Install mkcert (apt/pacman/dnf/brew/choco/scoop/winget), then run `synapse https setup <domain>`.",
+      data: { present: false },
+    };
+  }),
+};
+
+const checkHttpsCaTrusted = {
+  id: "https-ca-trusted",
+  category: "local-https-dev",
+  title: "local CA trusted (rootCA.pem present)",
+  autoFix: "never",
+  dependsOn: ["https-mkcert"],
+  run: safeRun(async (ctx) => {
+    if (!hasLocalHttpsContext(ctx.cwd)) {
+      return { status: "skipped", summary: "no local HTTPS context", data: { silentlySkip: true } };
+    }
+    const m = httpsDetect.detectMkcert();
+    if (!m.present) {
+      return { status: "skipped", summary: "mkcert missing", data: {} };
+    }
+    if (httpsDetect.detectCaTrusted(m)) {
+      return { status: "ok", summary: `rootCA in ${m.caroot}`, data: { caroot: m.caroot } };
+    }
+    return {
+      status: "issue",
+      summary: "rootCA.pem not found in mkcert's CAROOT",
+      remediation: "Run `mkcert -install` once (or just `synapse https setup <domain>`).",
+      data: { caroot: m.caroot },
+    };
+  }),
+};
+
+const checkHttpsCertFiles = {
+  id: "https-cert-files",
+  category: "local-https-dev",
+  title: "dev:https cert + key files exist",
+  autoFix: "never",
+  dependsOn: ["https-mkcert"],
+  run: safeRun(async (ctx) => {
+    const dev = parseDevHttpsScript(ctx.cwd);
+    if (!dev) {
+      return { status: "skipped", summary: "no dev:https script in cwd", data: { silentlySkip: true } };
+    }
+    const fs = require("node:fs");
+    const certExists = fs.existsSync(dev.cert);
+    const keyExists = fs.existsSync(dev.key);
+    if (certExists && keyExists) {
+      return {
+        status: "ok",
+        summary: `${dev.domain} ✓ both files present`,
+        data: { domain: dev.domain, cert: dev.cert, key: dev.key },
+      };
+    }
+    const missing = [];
+    if (!certExists) missing.push("cert");
+    if (!keyExists) missing.push("key");
+    return {
+      status: "issue",
+      summary: `${dev.domain}: missing ${missing.join(" + ")}`,
+      remediation: `Run \`synapse https setup ${dev.domain}\` to regenerate.`,
+      data: { domain: dev.domain, cert: dev.cert, key: dev.key, certExists, keyExists },
+    };
+  }),
+};
+
+const checkHttpsDomainResolves = {
+  id: "https-domain-resolves",
+  category: "local-https-dev",
+  title: "dev:https domain resolves to 127.0.0.1",
+  autoFix: "never",
+  dependsOn: [],
+  run: safeRun(async (ctx) => {
+    const dev = parseDevHttpsScript(ctx.cwd);
+    if (!dev) {
+      return { status: "skipped", summary: "no dev:https script in cwd", data: { silentlySkip: true } };
+    }
+    const resolution = await httpsDetect.detectDomainResolution(dev.domain);
+    if (resolution.resolvesToLoopback) {
+      return {
+        status: "ok",
+        summary: `${dev.domain} → 127.0.0.1 (via ${resolution.source})`,
+        data: { domain: dev.domain, source: resolution.source },
+      };
+    }
+    return {
+      status: "issue",
+      summary: `${dev.domain} doesn't resolve to 127.0.0.1 (got: ${resolution.got.join(", ") || "nothing"})`,
+      remediation: `Run \`synapse https setup ${dev.domain}\` to add the hosts entry, OR add a DNS A record pointing the domain at 127.0.0.1.`,
+      data: { domain: dev.domain, got: resolution.got },
+    };
+  }),
+};
+
+const checkHttpsCertExpiry = {
+  id: "https-cert-expiry",
+  category: "local-https-dev",
+  title: "cert not expiring soon (>30 days)",
+  autoFix: "never",
+  dependsOn: ["https-cert-files"],
+  run: safeRun(async (ctx) => {
+    const dev = parseDevHttpsScript(ctx.cwd);
+    if (!dev) {
+      return { status: "skipped", summary: "no dev:https script in cwd", data: { silentlySkip: true } };
+    }
+    const fs = require("node:fs");
+    if (!fs.existsSync(dev.cert)) {
+      return { status: "skipped", summary: "cert file missing", data: {} };
+    }
+    if (!httpsDetect.commandExists("openssl")) {
+      return { status: "skipped", summary: "openssl not available — can't check expiry", data: {} };
+    }
+    const { execFileSync } = require("node:child_process");
+    let expiry;
+    try {
+      const out = execFileSync(
+        "openssl",
+        ["x509", "-in", dev.cert, "-noout", "-enddate"],
+        { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+      );
+      const m = out.match(/notAfter=(.+)/);
+      if (m) expiry = new Date(m[1]);
+    } catch (err) {
+      return { status: "skipped", summary: `openssl read failed: ${err.message}`, data: {} };
+    }
+    if (!expiry || Number.isNaN(expiry.getTime())) {
+      return { status: "skipped", summary: "could not parse cert expiry", data: {} };
+    }
+    const daysLeft = Math.floor((expiry.getTime() - Date.now()) / (1000 * 60 * 60 * 24));
+    if (daysLeft < 0) {
+      return {
+        status: "issue",
+        summary: `${dev.domain}: cert EXPIRED ${-daysLeft} days ago (${expiry.toISOString().slice(0, 10)})`,
+        remediation: `Regenerate: \`synapse https setup ${dev.domain} --force\`.`,
+        data: { domain: dev.domain, expiry: expiry.toISOString(), daysLeft },
+      };
+    }
+    if (daysLeft < 30) {
+      return {
+        status: "warn",
+        summary: `${dev.domain}: cert expires in ${daysLeft} days (${expiry.toISOString().slice(0, 10)})`,
+        remediation: `Regenerate soon: \`synapse https setup ${dev.domain} --force\`.`,
+        data: { domain: dev.domain, expiry: expiry.toISOString(), daysLeft },
+      };
+    }
+    return {
+      status: "ok",
+      summary: `${dev.domain}: ${daysLeft} days left (expires ${expiry.toISOString().slice(0, 10)})`,
+      data: { domain: dev.domain, expiry: expiry.toISOString(), daysLeft },
+    };
+  }),
+};
+
 const ALL_CHECKS = [
   // Tier A
   checkNodeVersion,
@@ -653,6 +885,22 @@ const ALL_CHECKS = [
   // Tier C (per deployment)
   makeDeploymentCheck("dev"),
   makeDeploymentCheck("prod"),
+
+  // Tier D — local HTTPS dev (v1.8.9). Context-gated: if the cwd
+  // doesn't have a dev:https script AND no certs are configured, the
+  // whole category is hidden from the report.
+  checkHttpsMkcert,
+  checkHttpsCaTrusted,
+  checkHttpsCertFiles,
+  checkHttpsDomainResolves,
+  checkHttpsCertExpiry,
 ];
 
-module.exports = { ALL_CHECKS, isBrowserReachable, cmpVer };
+module.exports = {
+  ALL_CHECKS,
+  isBrowserReachable,
+  cmpVer,
+  // exports for tests
+  parseDevHttpsScript,
+  hasLocalHttpsContext,
+};

package/lib/doctor/renderer.js

@@ -21,10 +21,19 @@ const CATEGORY_TITLE = {
   project: "Project",
   backend: "Backend",
   deployments: "Deployments",
+  "local-https-dev": "Local HTTPS dev",
   upstream: "Upstream",
   workspace: "Workspace",
 };
-const CATEGORY_ORDER = ["local-env", "project", "backend", "deployments", "upstream", "workspace"];
+const CATEGORY_ORDER = [
+  "local-env",
+  "project",
+  "backend",
+  "deployments",
+  "local-https-dev",
+  "upstream",
+  "workspace",
+];
 
 function renderHeader(report, write) {
   const parts = ["Synapse doctor"];
@@ -74,8 +83,16 @@ function renderReport(report, { stdout, verbose = false } = {}) {
   for (const cat of CATEGORY_ORDER) {
     const rows = byCategory.get(cat);
     if (!rows || rows.length === 0) continue;
+    // v1.8.9: filter out individual results marked `silentlySkip`
+    // (checks that decided their context is missing — e.g. `dev:https`
+    // checks in a project without that script). Then hide the
+    // category if NOTHING is left.
+    const visibleRows = rows.filter(
+      (r) => !(r.status === "skipped" && r.data && r.data.silentlySkip),
+    );
+    if (visibleRows.length === 0) continue;
     write(`  ${colors.bold(CATEGORY_TITLE[cat] ?? cat)}\n`);
-    for (const r of rows) renderCheck(r, { verbose }, write);
+    for (const r of visibleRows) renderCheck(r, { verbose }, write);
     write("\n");
   }
 

package/lib/doctor/runner.js

@@ -39,13 +39,22 @@ async function runChecks(checks, ctx) {
         return r.status === "issue" || r.status === "skipped";
       });
       if (failedDeps.length > 0) {
+        // v1.8.9: propagate `silentlySkip` from any silent-skipped
+        // prereq so the cascade-skipped child stays hidden too.
+        // Without this, https-cert-expiry would re-surface as a
+        // visible "·" every time its parent (https-cert-files) was
+        // silently skipped for "no dev:https script in cwd".
+        const silentParent = failedDeps.some((d) => {
+          const parent = resultsById.get(d);
+          return parent && parent.data && parent.data.silentlySkip;
+        });
         resultsById.set(id, {
           id,
           category: check.category,
           title: check.title,
           status: "skipped",
           summary: `skipped (prereq failed: ${failedDeps.join(", ")})`,
-          data: { skippedBecause: failedDeps },
+          data: { skippedBecause: failedDeps, silentlySkip: silentParent },
           durationMs: 0,
         });
         pending.delete(id);

package/lib/https/hosts.js

@@ -178,6 +178,26 @@ function readHosts(hostsPath) {
   }
 }
 
+// Best-effort DNS cache flush. On Windows the DNS Client (Dnscache)
+// service caches lookups separately from the hosts file — editing
+// /etc/hosts on Windows does NOT invalidate the cache, so `next dev`
+// and Node's dns.lookup() can both return ENOTFOUND despite the
+// entry being written correctly. This bit Matheus's Windows machine
+// in real-world testing (v1.8.10 bug report).
+//
+// `ipconfig /flushdns` is safe to call without admin elevation on
+// every Windows version since at least Windows 7, but we never let a
+// failure here block the wider flow — it's a hint, not a guarantee.
+function flushDnsCacheIfWindows({ execImpl = execFileSync, platform = process.platform } = {}) {
+  if (platform !== "win32") return { ran: false, reason: "non-windows platform" };
+  try {
+    execImpl("ipconfig", ["/flushdns"], { stdio: "ignore", timeout: 5000 });
+    return { ran: true };
+  } catch (err) {
+    return { ran: false, reason: err.message };
+  }
+}
+
 // Writes content to the hosts file. Three strategies are tried in
 // order based on the platform + the `elevation` knob:
 //
@@ -191,6 +211,13 @@ function readHosts(hostsPath) {
 //   - "never": only try direct write; error if it fails
 //   - "always": skip the direct write attempt
 //
+// On Windows we additionally:
+//   - Normalise line endings to CRLF (the Windows hosts file
+//     traditionally uses CRLF; some Windows components are tolerant
+//     of LF but defensive normalisation costs nothing)
+//   - Run `ipconfig /flushdns` after a successful write so the
+//     DNS Client cache picks up the new entry immediately
+//
 // `writeImpl` is injected for tests.
 function writeHosts(hostsPath, content, {
   elevation = "auto",
@@ -198,11 +225,15 @@ function writeHosts(hostsPath, content, {
   execImpl = execFileSync,
   platform = process.platform,
 } = {}) {
+  const onDiskContent =
+    platform === "win32" ? content.replace(/\r?\n/g, "\r\n") : content;
+
   // Try direct write first (fast path).
+  let result;
   if (elevation !== "always") {
     try {
-      writeImpl(hostsPath, content);
-      return { method: "direct", elevated: false };
+      writeImpl(hostsPath, onDiskContent);
+      result = { method: "direct", elevated: false };
     } catch (err) {
       if (elevation === "never") {
         throw new HostsError(
@@ -214,10 +245,25 @@ function writeHosts(hostsPath, content, {
     }
   }
 
+  if (!result) {
+    if (platform === "win32") {
+      result = writeHostsViaRunAs(hostsPath, onDiskContent, { execImpl });
+    } else {
+      result = writeHostsViaSudo(hostsPath, onDiskContent, { execImpl });
+    }
+  }
+
+  // Post-write DNS cache flush (best-effort, Windows only). The
+  // elevated runas path ALREADY flushes inside its PowerShell script
+  // — see writeHostsViaRunAs. Calling here covers the direct-write
+  // case (operator already in an elevated shell). Doubling up is
+  // harmless: a second flush is a no-op.
   if (platform === "win32") {
-    return writeHostsViaRunAs(hostsPath, content, { execImpl });
+    const flush = flushDnsCacheIfWindows({ execImpl, platform });
+    result.dnsFlushed = flush.ran;
+    if (!flush.ran) result.dnsFlushReason = flush.reason;
   }
-  return writeHostsViaSudo(hostsPath, content, { execImpl });
+  return result;
 }
 
 // Linux/macOS elevated write. We pipe the new content into `sudo
@@ -269,12 +315,18 @@ function writeHostsViaRunAs(hostsPath, content, { execImpl = execFileSync } = {}
   const tmpFile = path.join(os.tmpdir(), `synapse-hosts-${Date.now()}.txt`);
   fs.writeFileSync(tmpFile, content);
   const backupPath = `${hostsPath}.synapse-bak.${Date.now()}`;
-  // PowerShell script (single-line, double-quote-friendly):
-  //   Copy-Item <hosts> <backup>; Move-Item -Force <tmp> <hosts>
+  // PowerShell script — runs ELEVATED via Start-Process RunAs below.
+  //   1. Copy current hosts to backup
+  //   2. Move new content over hosts
+  //   3. ipconfig /flushdns (v1.8.10): WITHOUT this the Windows DNS
+  //      Client cache keeps returning NXDOMAIN for the freshly-added
+  //      entry, breaking `next dev --hostname dev.foo.com` with
+  //      ENOTFOUND despite the hosts file being correct.
   const script = [
     `try {`,
     `  Copy-Item -LiteralPath '${hostsPath}' -Destination '${backupPath}' -ErrorAction Stop;`,
     `  Move-Item -LiteralPath '${tmpFile}' -Destination '${hostsPath}' -Force -ErrorAction Stop;`,
+    `  & ipconfig /flushdns | Out-Null;`,
     `  exit 0`,
     `} catch {`,
     `  Write-Error $_.Exception.Message;`,
@@ -345,6 +397,7 @@ module.exports = {
   MANAGED_BLOCK_START,
   MANAGED_BLOCK_END,
   hostsPathForOS,
+  flushDnsCacheIfWindows,
   planAddEntry,
   planRemoveEntry,
   readHosts,

package/lib/https/planner.js

@@ -182,6 +182,16 @@ function plan(detection, {
   }
 
   // ---- Step: hosts file ----------------------------------------------
+  // Decision tree:
+  //   1. --skip-hosts                            → skip
+  //   2. Resolves via public DNS                  → skip (any machine works)
+  //   3. Hosts has entry + resolution works       → skip (idempotent)
+  //   4. Hosts has entry + resolution still fails → exec ("DNS cache
+  //      stale" fix — re-writing triggers ipconfig /flushdns on Windows).
+  //      This is the v1.8.10 fix for the bug Matheus hit: hosts file
+  //      had the entry but Windows DNS Client kept returning ENOTFOUND.
+  //   5. No entry                                 → exec (write + flush)
+  const hostsHasEntry = detection.hosts.matches.some((m) => m.address === "127.0.0.1");
   if (skipHosts) {
     steps.push({
       id: "hosts",
@@ -202,13 +212,26 @@ function plan(detection, {
       skipReason:
         "no hosts edit needed — DNS A record points at loopback (any machine on any OS resolves correctly)",
     });
-  } else if (detection.hosts.matches.some((m) => m.address === "127.0.0.1")) {
+  } else if (hostsHasEntry && detection.resolution.resolvesToLoopback) {
     steps.push({
       id: "hosts",
       title: "Hosts file entry",
       kind: "skip",
-      reason: `${detection.hosts.path} already maps ${detection.domain} to 127.0.0.1`,
-      skipReason: "entry present",
+      reason: `${detection.hosts.path} already maps ${detection.domain} to 127.0.0.1 and resolution works`,
+      skipReason: "entry present + DNS cache fresh",
+    });
+  } else if (hostsHasEntry && !detection.resolution.resolvesToLoopback) {
+    steps.push({
+      id: "hosts",
+      title: `Refresh DNS cache for ${detection.domain}`,
+      kind: "exec",
+      reason:
+        detection.platform.id === "windows"
+          ? `${detection.hosts.path} has the entry but Windows DNS cache is stale — re-writing to trigger \`ipconfig /flushdns\``
+          : `${detection.hosts.path} has the entry but resolution still fails — re-writing to force a refresh`,
+      async run() {
+        return hostsMod.addEntry(detection.hosts.path, detection.domain);
+      },
     });
   } else {
     const needsElevation = !detection.hosts.writable;

package/package.json

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