@iann29/synapse 1.8.7 → 1.8.9

package/lib/commands/_help.js

@@ -20,6 +20,7 @@ function renderRootHelp(registry, { stdout = process.stdout } = {}) {
     ["Teams", "team"],
     ["Env vars", "env"],
     ["Domains", "domain"],
+    ["Local HTTPS dev", "https"],
     ["Escape hatch", ["convex"]],
   ];
 

package/lib/commands/https-doctor.js

@@ -0,0 +1,73 @@
+// `synapse https doctor [domain]` — read-only sanity checks that
+// tell the operator WHAT to fix without changing anything. This
+// mirrors `synapse doctor` but is scoped to the HTTPS-dev surface.
+//
+// Useful when an operator runs the wizard and the dev server still
+// doesn't work — `doctor` re-scans + flags every drift from the
+// expected state.
+
+const colors = require("../colors");
+const { extractFlags } = require("./_resource");
+const detectMod = require("../https/detect");
+const plannerMod = require("../https/planner");
+
+module.exports = {
+  name: "https doctor",
+  summary: "Diagnose local-HTTPS setup without changing anything.",
+  usage: "synapse https doctor [domain] [--json]",
+  description: `Runs the same detection as \`https setup\` but in read-only mode. Prints the plan that WOULD run, plus any warnings (legacy certs in cwd, NSS missing, etc).`,
+
+  async run(args, ctx) {
+    const { flags, rest } = extractFlags(args, {
+      string: [],
+      boolean: ["json"],
+    });
+    const domain = rest[0];
+    if (rest.length > 1) {
+      throw new Error(`Unexpected positional: ${rest[1]}.`);
+    }
+    if (!domain) {
+      throw new Error(
+        "Usage: synapse https doctor <domain>\n\nExample: synapse https doctor dev.myproject.com",
+      );
+    }
+    const detection = await detectMod.scan({ domain, cwd: ctx.cwd });
+    const steps = plannerMod.plan(detection, {});
+    const blocker = steps.find((s) => s.kind === "blocker");
+    const warnings = steps.filter((s) => s.kind === "warn");
+    const willExec = steps.filter((s) => s.kind === "exec");
+    const willSkip = steps.filter((s) => s.kind === "skip");
+    const summary = {
+      domain,
+      platform: detection.platform.id,
+      blocker: blocker ? blocker.blocker || blocker.reason : null,
+      warnings: warnings.map((w) => ({ id: w.id, reason: w.reason, hint: w.skipReason })),
+      wouldExec: willExec.map((s) => ({ id: s.id, title: s.title, reason: s.reason })),
+      skipped: willSkip.map((s) => ({ id: s.id, title: s.title, reason: s.reason })),
+    };
+    ctx.out.result(summary, (s, { stdout }) => {
+      stdout.write(`${colors.bold("HTTPS doctor")} ${colors.dim(`· ${s.domain} · ${s.platform}`)}\n\n`);
+      if (s.blocker) {
+        stdout.write(colors.red(`Blocker: ${s.blocker}\n`));
+        return;
+      }
+      if (s.wouldExec.length === 0) {
+        stdout.write(colors.green("Healthy. Nothing to do.\n"));
+      } else {
+        stdout.write(colors.yellow(`${s.wouldExec.length} step${s.wouldExec.length > 1 ? "s" : ""} would run:\n`));
+        for (const x of s.wouldExec) {
+          stdout.write(`  ${colors.cyan("●")} ${x.title}\n`);
+          if (x.reason) stdout.write(colors.dim(`     ${x.reason}\n`));
+        }
+        stdout.write(colors.dim("\nRun `synapse https setup <domain>` to apply.\n"));
+      }
+      if (s.warnings.length > 0) {
+        stdout.write(`\n${colors.yellow("Warnings:")}\n`);
+        for (const w of s.warnings) {
+          stdout.write(`  ${colors.yellow("!")} ${w.reason}\n`);
+          if (w.hint) stdout.write(colors.dim(`     ${w.hint}\n`));
+        }
+      }
+    });
+  },
+};

package/lib/commands/https-migrate.js

@@ -0,0 +1,168 @@
+// `synapse https migrate [--cwd] [--all] [--yes] [--dry-run] [--json]`
+//
+// Migrates legacy cert layouts to the canonical ~/.config/dev-certs/
+// store. Two modes:
+//
+//   1. cwd mode (default): scans the current directory for legacy
+//      `dev.*.pem` + `-key.pem` pairs and migrates them.
+//   2. --all: scans EVERY known project root (operator-supplied via
+//      --root flag, default: ~/Documents and the cwd). This is more
+//      ambitious and gated behind explicit opt-in.
+//
+// Migration per cert pair:
+//   - Move the .pem files into ~/.config/dev-certs/<domain>/
+//   - Set mode 0600 on the key
+//   - Rewrite package.json dev:https to point at the new paths
+//   - Leave the original files in place ONLY if --keep-old; default
+//     is to delete them once they've been moved successfully.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const colors = require("../colors");
+const { extractFlags } = require("./_resource");
+const { confirm } = require("../prompts");
+const detectMod = require("../https/detect");
+const nextjsMod = require("../https/nextjs");
+
+module.exports = {
+  name: "https migrate",
+  summary: "Move legacy cert pairs from project roots into ~/.config/dev-certs/.",
+  usage: "synapse https migrate [--cwd | --root=<path>] [--keep-old] [--dry-run] [--yes] [--json]",
+  description: `Some projects have their .pem files in the project root (left over from the manual setup era). This command moves them into the canonical ~/.config/dev-certs/<domain>/ store, then rewrites the project's package.json dev:https script to reference the new paths.
+
+Flags:
+  --cwd               only the current directory (default)
+  --root=<path>       a specific directory to scan
+  --keep-old          leave the original .pem files in place after moving
+  --dry-run           show what would happen, don't change anything
+  --yes               skip the per-pair confirmation
+  --json              machine-readable output
+
+The cwd is scanned non-recursively. Subdirectories are ignored —
+if you want to migrate every project on disk, run this command in
+each project root (or write a small loop).`,
+
+  async run(args, ctx) {
+    const { flags, rest } = extractFlags(args, {
+      string: ["root"],
+      boolean: ["cwd", "keep-old", "dry-run", "yes", "json"],
+    });
+    if (rest.length > 0) {
+      throw new Error(`Unexpected positional: ${rest[0]}.`);
+    }
+    const root = typeof flags.root === "string" ? flags.root : ctx.cwd;
+    const dryRun = flags["dry-run"] === true;
+    const keepOld = flags["keep-old"] === true;
+    const yes = flags.yes === true;
+    const legacy = detectMod.detectLegacyCertsInCwd(root);
+
+    if (legacy.length === 0) {
+      ctx.out.result(
+        { root, migrated: [], skipped: [], count: 0 },
+        () =>
+          ctx.out.stdout.write(
+            colors.dim(`No legacy cert pairs found in ${root}.\n`),
+          ),
+      );
+      return;
+    }
+
+    if (!ctx.out.json) {
+      ctx.out.stdout.write(
+        `${colors.bold(`Found ${legacy.length} legacy cert pair${legacy.length > 1 ? "s" : ""} in ${root}:`)}\n`,
+      );
+      for (const p of legacy) {
+        ctx.out.stdout.write(`  · ${colors.bold(p.domain)}\n`);
+        ctx.out.stdout.write(colors.dim(`      ${p.cert}\n`));
+        ctx.out.stdout.write(colors.dim(`      ${p.key}\n`));
+      }
+      ctx.out.stdout.write("\n");
+    }
+    if (dryRun) {
+      ctx.out.info("(dry-run — no changes applied)");
+      ctx.out.result({ root, found: legacy, dryRun: true }, () => {});
+      return;
+    }
+    if (!yes && !ctx.out.json) {
+      const ok = await confirm(`Migrate ${legacy.length} pair(s)? [Y/n] `, { defaultAnswer: true });
+      if (!ok) {
+        ctx.out.info("Aborted.");
+        process.exitCode = 1;
+        return;
+      }
+    }
+    if (!yes && ctx.out.json) {
+      throw new Error("Refusing to migrate in --json mode without --yes.");
+    }
+
+    const migrated = [];
+    const skipped = [];
+    const failed = [];
+    for (const p of legacy) {
+      try {
+        const target = detectMod.certFilesFor(p.domain);
+        // Skip pairs whose canonical location is already populated
+        // unless --force (which we don't expose here — re-running
+        // setup --force is the right way to regenerate).
+        if (fs.existsSync(target.cert) && fs.existsSync(target.key)) {
+          skipped.push({ domain: p.domain, reason: "target already exists in cert store" });
+          continue;
+        }
+        fs.mkdirSync(target.dir, { recursive: true, mode: 0o700 });
+        fs.copyFileSync(p.cert, target.cert);
+        fs.copyFileSync(p.key, target.key);
+        try {
+          fs.chmodSync(target.key, 0o600);
+        } catch {
+          // ignore
+        }
+        if (!keepOld) {
+          fs.rmSync(p.cert, { force: true });
+          fs.rmSync(p.key, { force: true });
+        }
+        // Rewrite package.json dev:https if present + still references
+        // the project-root form.
+        const pkgPath = path.join(root, "package.json");
+        if (fs.existsSync(pkgPath)) {
+          const info = nextjsMod.readPackageJson(pkgPath);
+          if (info.parsed && info.parsed.scripts && info.parsed.scripts["dev:https"]) {
+            const current = info.parsed.scripts["dev:https"];
+            // Replace any reference to the project-root pem paths
+            // with the canonical ones.
+            const newCommand = current
+              .replace(p.cert.replace(/\\/g, "/"), target.cert.replace(/\\/g, "/"))
+              .replace(p.key.replace(/\\/g, "/"), target.key.replace(/\\/g, "/"))
+              .replace(`./${path.basename(p.cert)}`, target.cert.replace(/\\/g, "/"))
+              .replace(`./${path.basename(p.key)}`, target.key.replace(/\\/g, "/"));
+            if (newCommand !== current) {
+              nextjsMod.setDevHttpsScript(pkgPath, newCommand);
+            }
+          }
+        }
+        migrated.push({
+          domain: p.domain,
+          from: { cert: p.cert, key: p.key },
+          to: { cert: target.cert, key: target.key },
+        });
+      } catch (err) {
+        failed.push({ domain: p.domain, error: err.message });
+      }
+    }
+
+    ctx.out.result(
+      { root, migrated, skipped, failed, count: migrated.length },
+      (_d, { stdout }) => {
+        for (const m of migrated) {
+          stdout.write(`${colors.green("✓")} ${colors.bold(m.domain)} → ${colors.dim(m.to.cert)}\n`);
+        }
+        for (const s of skipped) {
+          stdout.write(`${colors.dim("○")} ${colors.bold(s.domain)} skipped: ${s.reason}\n`);
+        }
+        for (const f of failed) {
+          stdout.write(`${colors.red("✗")} ${colors.bold(f.domain)}: ${f.error}\n`);
+        }
+      },
+    );
+    if (failed.length > 0) process.exitCode = 1;
+  },
+};

package/lib/commands/https-remove.js

@@ -0,0 +1,103 @@
+// `synapse https remove <domain> [--keep-certs] [--keep-script]
+//   [--keep-hosts] [--yes] [--json]`
+//
+// Symmetric undo to `https setup`. Removes:
+//   - The cert pair at ~/.config/dev-certs/<domain>/
+//   - The hosts file entry inside the managed block
+//   - The dev:https script from package.json (if it matches the
+//     canonical form — never deletes operator-customised scripts)
+
+const colors = require("../colors");
+const { extractFlags } = require("./_resource");
+const { confirm } = require("../prompts");
+const detectMod = require("../https/detect");
+const plannerMod = require("../https/planner");
+const executorMod = require("../https/executor");
+
+module.exports = {
+  name: "https remove",
+  summary: "Undo `synapse https setup` for a domain (cert + hosts + script).",
+  usage:
+    "synapse https remove <domain> [--keep-certs] [--keep-script] [--keep-hosts] [--yes] [--json]",
+  description: `Reverses what \`synapse https setup\` did. Idempotent — running on a domain that was never set up is a no-op.
+
+Flags:
+  --keep-certs    don't delete the cert pair from ~/.config/dev-certs/
+  --keep-script   don't touch package.json
+  --keep-hosts    don't touch the hosts file
+  --yes           skip the y/N confirmation
+  --json          machine-readable output
+
+Examples:
+  synapse https remove dev.oldproject.com
+  synapse https remove dev.test.com --keep-certs   # keep the cert, just untangle hosts + script`,
+
+  async run(args, ctx) {
+    const { flags, rest } = extractFlags(args, {
+      string: [],
+      boolean: ["keep-certs", "keep-script", "keep-hosts", "yes", "json"],
+    });
+    const domain = rest[0];
+    if (!domain) {
+      throw new Error("Usage: synapse https remove <domain>");
+    }
+    if (rest.length > 1) {
+      throw new Error(`Unexpected positional: ${rest[1]}.`);
+    }
+    const yes = flags.yes === true;
+    const detection = await detectMod.scan({ domain, cwd: ctx.cwd });
+    const steps = plannerMod.planRemove(detection, {
+      keepCerts: flags["keep-certs"] === true,
+      keepScript: flags["keep-script"] === true,
+      keepHosts: flags["keep-hosts"] === true,
+    });
+    if (!plannerMod.planIsExecutable(steps)) {
+      const blocker = steps.find((s) => s.kind === "blocker");
+      throw new Error(blocker?.blocker || "Plan is blocked.");
+    }
+    const willChange = steps.some((s) => s.kind === "exec");
+    if (!willChange) {
+      ctx.out.result(
+        { domain, executedAny: false, results: [] },
+        () => ctx.out.stdout.write(colors.dim("Nothing to remove.\n")),
+      );
+      return;
+    }
+
+    if (!ctx.out.json) {
+      ctx.out.stdout.write(`${colors.bold("Will remove:")}\n`);
+      for (const s of steps) {
+        if (s.kind === "exec") {
+          ctx.out.stdout.write(`  ${colors.red("✗")} ${s.title}\n`);
+        }
+      }
+      ctx.out.stdout.write("\n");
+    }
+    if (!yes && !ctx.out.json) {
+      const ok = await confirm(
+        `Remove HTTPS setup for ${colors.bold(domain)}? [y/N] `,
+        { defaultAnswer: false },
+      );
+      if (!ok) {
+        ctx.out.info("Aborted.");
+        process.exitCode = 1;
+        return;
+      }
+    }
+    if (!yes && ctx.out.json) {
+      throw new Error("Refusing to remove in --json mode without --yes.");
+    }
+    const { results, failedAny } = await executorMod.execute(steps, { out: ctx.out });
+    ctx.out.result(
+      { domain, results, failedAny },
+      (_d, { stdout }) => {
+        for (const r of results) {
+          if (r.kind === "ok") {
+            stdout.write(`${colors.green("✓")} ${r.title}\n`);
+          }
+        }
+      },
+    );
+    if (failedAny) process.exitCode = 1;
+  },
+};

package/lib/commands/https-setup.js

@@ -0,0 +1,263 @@
+// `synapse https setup <domain>` — the wizard.
+//
+// Flow (all idempotent — re-running is a no-op on a healthy machine):
+//   1. SCAN     — read 16 detection vars (read-only, ~50ms)
+//   2. PLAN     — turn detections into a list of steps
+//   3. PREVIEW  — print the plan; ask "ok?" unless --yes
+//   4. EXECUTE  — run each step; stop on failure (steps converge on
+//                  re-run because each is independently idempotent)
+//   5. VERIFY   — re-scan + print summary
+//
+// Flags:
+//   --force         regenerate the cert even if present
+//   --yes           skip the preview confirm prompt
+//   --dry-run       SCAN + PLAN + PREVIEW; never execute
+//   --skip-hosts    skip the hosts file step
+//   --skip-script   skip the package.json mutation
+//   --json          machine-readable output
+//   --verbose       print per-step duration + outcome details
+
+const colors = require("../colors");
+const { extractFlags } = require("./_resource");
+const { confirm } = require("../prompts");
+const detectMod = require("../https/detect");
+const plannerMod = require("../https/planner");
+const executorMod = require("../https/executor");
+
+function renderPlan(steps, { stdout }) {
+  for (const step of steps) {
+    const symbol = symbolFor(step.kind);
+    stdout.write(`  ${symbol} ${step.title}\n`);
+    if (step.kind === "blocker") {
+      stdout.write(colors.red(`     blocker: ${step.blocker || step.reason}\n`));
+      continue;
+    }
+    if (step.reason) {
+      stdout.write(colors.dim(`     ${step.reason}\n`));
+    }
+    if (step.skipReason && step.kind !== "exec") {
+      stdout.write(colors.dim(`     ${step.skipReason}\n`));
+    }
+  }
+}
+
+function symbolFor(kind) {
+  switch (kind) {
+    case "exec":
+      return colors.cyan("●");
+    case "skip":
+      return colors.dim("○");
+    case "warn":
+      return colors.yellow("!");
+    case "blocker":
+      return colors.red("✗");
+    default:
+      return " ";
+  }
+}
+
+function renderResults(results, { stdout }) {
+  for (const r of results) {
+    const sym =
+      r.kind === "ok"
+        ? colors.green("✓")
+        : r.kind === "failed"
+          ? colors.red("✗")
+          : r.kind === "blocker"
+            ? colors.red("✗")
+            : r.kind === "warn"
+              ? colors.yellow("!")
+              : colors.dim("○");
+    const tail =
+      r.kind === "ok"
+        ? colors.dim(`  ${r.durationMs}ms`)
+        : r.kind === "failed"
+          ? colors.red(`  ${r.outcome.error || "failed"}`)
+          : "";
+    stdout.write(`  ${sym} ${r.title}${tail}\n`);
+  }
+}
+
+module.exports = {
+  name: "https setup",
+  summary: "Configure local HTTPS for a Next.js dev domain (mkcert + hosts + package.json).",
+  usage:
+    "synapse https setup <domain> [--force] [--yes] [--dry-run] [--skip-hosts] [--skip-script] [--verbose] [--json]",
+  description: `Sets up self-signed HTTPS for a custom dev domain (e.g. dev.myproject.com) so \`next dev --experimental-https\` works without browser warnings.
+
+Does six things in one pass:
+  1. Detects mkcert + your OS + DNS state + cwd's package.json
+  2. Ensures the local CA is trusted (mkcert -install, idempotent)
+  3. Generates a cert pair at ~/.config/dev-certs/<domain>/
+  4. Adds a 127.0.0.1 entry to your hosts file (sudo/UAC prompt if needed)
+     — skipped automatically if your public DNS already resolves to loopback
+  5. Adds/updates the dev:https script in package.json
+  6. Verifies + prints "now run \`npm run dev:https\`"
+
+Re-running is safe (every step is idempotent). The whole thing works
+identically on Linux, macOS, Windows, and WSL.
+
+Flags:
+  --force         regenerate the cert even if one exists
+  --yes           skip the preview confirmation prompt
+  --dry-run       show the plan, don't execute (useful for partners
+                  on Windows who want to see what will happen first)
+  --skip-hosts    don't touch the hosts file
+  --skip-script   don't touch package.json
+  --verbose       per-step duration + outcome details
+  --json          machine-readable output for CI
+
+Examples:
+  synapse https setup dev.myproject.com
+  synapse https setup dev.myproject.com --dry-run --verbose
+  synapse https setup dev.myproject.com --force --yes`,
+
+  // Exports for tests
+  renderPlan,
+  renderResults,
+  symbolFor,
+
+  async run(args, ctx) {
+    const { flags, rest } = extractFlags(args, {
+      string: [],
+      boolean: ["force", "yes", "dry-run", "skip-hosts", "skip-script", "verbose", "json"],
+    });
+    const domain = rest[0];
+    if (!domain) {
+      throw new Error(
+        "Usage: synapse https setup <domain>\n\nExample: synapse https setup dev.myproject.com",
+      );
+    }
+    if (rest.length > 1) {
+      throw new Error(`Unexpected positional: ${rest[1]}.`);
+    }
+
+    const force = flags.force === true;
+    const yes = flags.yes === true;
+    const dryRun = flags["dry-run"] === true;
+    const skipHosts = flags["skip-hosts"] === true;
+    const skipScript = flags["skip-script"] === true;
+    const verbose = flags.verbose === true;
+
+    // ---- Phase 1: SCAN ------------------------------------------------
+    if (!ctx.out.json) ctx.out.info("Scanning environment…");
+    const detection = await detectMod.scan({ domain, cwd: ctx.cwd });
+
+    // ---- Phase 2: PLAN ------------------------------------------------
+    const steps = plannerMod.plan(detection, { force, skipHosts, skipScript });
+    const executable = plannerMod.planIsExecutable(steps);
+
+    // ---- Phase 3: PREVIEW --------------------------------------------
+    if (!ctx.out.json) {
+      ctx.out.stdout.write(
+        `\n${colors.bold("Plan")} ${colors.dim(`for ${domain} on ${detection.platform.id}`)}\n`,
+      );
+      renderPlan(steps, { stdout: ctx.out.stdout });
+      ctx.out.stdout.write("\n");
+    }
+
+    if (!executable) {
+      const blocker = steps.find((s) => s.kind === "blocker");
+      if (ctx.out.json) {
+        ctx.out.result(
+          { domain, blocked: true, steps, blocker: blocker?.blocker || blocker?.reason },
+          () => {},
+        );
+        process.exitCode = 1;
+        return;
+      }
+      ctx.out.error(blocker?.blocker || "Plan is blocked.");
+      process.exitCode = 1;
+      return;
+    }
+
+    if (dryRun) {
+      if (ctx.out.json) {
+        ctx.out.result({ domain, dryRun: true, steps }, () => {});
+        return;
+      }
+      ctx.out.info("(dry-run — not executing)");
+      return;
+    }
+
+    const willChange = steps.some((s) => s.kind === "exec");
+    if (!willChange) {
+      if (ctx.out.json) {
+        ctx.out.result({ domain, executedAny: false, steps }, () => {});
+        return;
+      }
+      ctx.out.stdout.write(
+        colors.green("Nothing to do — everything already in the desired state.\n"),
+      );
+      return;
+    }
+
+    if (!yes && !ctx.out.json) {
+      const ok = await confirm(`Apply this plan? [Y/n] `, { defaultAnswer: true });
+      if (!ok) {
+        ctx.out.info("Aborted.");
+        process.exitCode = 1;
+        return;
+      }
+    }
+    if (!yes && ctx.out.json) {
+      throw new Error("Refusing to execute in --json mode without --yes.");
+    }
+
+    // ---- Phase 4: EXECUTE --------------------------------------------
+    const { results, failedAny } = await executorMod.execute(steps, {
+      out: ctx.out,
+      verbose,
+    });
+
+    // ---- Phase 5: VERIFY ---------------------------------------------
+    const after = await detectMod.scan({ domain, cwd: ctx.cwd });
+
+    const summary = {
+      domain,
+      platform: detection.platform.id,
+      certPath: after.existingCerts?.certPath ?? null,
+      keyPath: after.existingCerts?.keyPath ?? null,
+      hostsEntry: after.hosts.matches.length > 0,
+      devHttpsScript: after.pkg.existingDevHttps,
+      results,
+      failedAny,
+    };
+
+    if (ctx.out.json) {
+      ctx.out.result(summary, () => {});
+      if (failedAny) process.exitCode = 1;
+      return;
+    }
+
+    ctx.out.stdout.write("\n");
+    renderResults(results, { stdout: ctx.out.stdout });
+    ctx.out.stdout.write("\n");
+    if (failedAny) {
+      ctx.out.error(
+        "One or more steps failed. Fix the cause and re-run — every step is idempotent so safe steps won't re-do.",
+      );
+      process.exitCode = 1;
+      return;
+    }
+    ctx.out.stdout.write(
+      `${colors.green("✓")} ${colors.bold(`HTTPS ready for ${domain}`)}\n`,
+    );
+    if (after.pkg.hasNext) {
+      ctx.out.stdout.write(colors.dim(`Next: run \`npm run dev:https\` in ${ctx.cwd}\n`));
+    } else {
+      ctx.out.stdout.write(
+        colors.dim(
+          `Cert lives at: ${after.existingCerts?.certPath}\nPair it with:\n  next dev --experimental-https --experimental-https-cert <cert> --experimental-https-key <key> --hostname ${domain}\n`,
+        ),
+      );
+    }
+    if (after.resolution.source === "dns") {
+      ctx.out.stdout.write(
+        colors.dim(
+          `(Public DNS A record points ${domain} → 127.0.0.1, so no /etc/hosts edit was needed. Partners on other machines also need no setup.)\n`,
+        ),
+      );
+    }
+  },
+};