@iann29/synapse 1.8.6 → 1.8.8

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`,
+        ),
+      );
+    }
+  },
+};

package/lib/commands/https-status.js

@@ -0,0 +1,154 @@
+// `synapse https status [domain]` — diagnose what's already
+// configured. With a domain: deep dive on that one. Without: list
+// every domain under ~/.config/dev-certs/.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const colors = require("../colors");
+const { extractFlags } = require("./_resource");
+const detectMod = require("../https/detect");
+
+function renderDomainStatus(detection, { stdout }) {
+  const sym = (b) => (b ? colors.green("✓") : colors.dim("·"));
+  stdout.write(`${colors.bold(detection.domain)}\n`);
+  stdout.write(
+    `  ${sym(detection.mkcert.present)} mkcert ${
+      detection.mkcert.present ? colors.dim(detection.mkcert.version) : colors.red("missing")
+    }\n`,
+  );
+  stdout.write(
+    `  ${sym(detection.caTrusted)} CA trusted${
+      detection.caTrusted ? "" : colors.red(" (run `mkcert -install`)")
+    }\n`,
+  );
+  const certPresent = detection.existingCerts && detection.existingCerts.present;
+  stdout.write(
+    `  ${sym(certPresent)} cert pair ${
+      certPresent ? colors.dim(detection.existingCerts.certPath) : colors.dim("(not generated yet)")
+    }\n`,
+  );
+  if (certPresent && detection.existingCerts.expiry) {
+    stdout.write(colors.dim(`     expires ${detection.existingCerts.expiry}\n`));
+  }
+  const resolves = detection.resolution.resolvesToLoopback;
+  const src = detection.resolution.source;
+  stdout.write(
+    `  ${sym(resolves)} resolves to 127.0.0.1 ${
+      resolves ? colors.dim(`(via ${src})`) : colors.red("(no — add to hosts or DNS A record)")
+    }\n`,
+  );
+  const scriptOk = !!detection.pkg.existingDevHttps;
+  stdout.write(
+    `  ${sym(scriptOk)} package.json dev:https ${
+      scriptOk
+        ? colors.dim("set")
+        : detection.pkg.present
+          ? colors.dim("(missing in cwd's package.json)")
+          : colors.dim("(no package.json in cwd)")
+    }\n`,
+  );
+}
+
+module.exports = {
+  name: "https status",
+  summary: "Show local-HTTPS state for one domain or every configured domain.",
+  usage: "synapse https status [domain] [--json]",
+  description: `Without a domain: lists every cert directory in ~/.config/dev-certs/.
+With a domain: prints a deep diagnostic (mkcert, CA trust, cert presence + expiry, DNS resolution, package.json script).`,
+
+  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) {
+      // List mode. We accept TWO layouts in the cert store:
+      //   1. Canonical (v1.8.8+): `<root>/<domain>/<domain>.pem` + `-key.pem`
+      //   2. Flat (operator's pre-existing intermediate layout):
+      //      `<root>/<domain>.pem` + `<domain>{-,.}key.pem`
+      // Flat-format certs aren't moved automatically — they show up
+      // here with a `flat: true` hint so `https migrate --root` can
+      // reorganise them.
+      const root = detectMod.certsRoot();
+      let entries = [];
+      try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+      } catch {
+        entries = [];
+      }
+      const domains = new Set();
+      const flatDomains = new Set();
+      // (1) Subdirectories (canonical).
+      for (const e of entries) {
+        if (e.isDirectory()) domains.add(e.name);
+      }
+      // (2) Flat pairs in the root.
+      const flat = detectMod.detectFlatCertsInStore();
+      for (const p of flat) {
+        domains.add(p.domain);
+        flatDomains.add(p.domain);
+      }
+      const rows = await Promise.all(
+        [...domains].sort().map(async (d) => {
+          const det = await detectMod.scan({ domain: d, cwd: ctx.cwd });
+          return {
+            domain: d,
+            cert: det.existingCerts?.present ?? false,
+            expiry: det.existingCerts?.expiry ?? null,
+            resolves: det.resolution.resolvesToLoopback,
+            resolutionSource: det.resolution.source,
+            flat: flatDomains.has(d),
+          };
+        }),
+      );
+      ctx.out.result(
+        { root, count: rows.length, domains: rows },
+        (_d, { stdout }) => {
+          stdout.write(colors.dim(`Cert store: ${root}\n`));
+          if (rows.length === 0) {
+            stdout.write(
+              colors.dim("(no certs configured — run `synapse https setup <domain>`)\n"),
+            );
+            return;
+          }
+          ctx.out.table(
+            rows.map((r) => ({
+              domain: colors.bold(r.domain) + (r.flat ? colors.dim(" (flat)") : ""),
+              cert: r.cert ? colors.green("yes") : colors.dim("no"),
+              expiry: r.expiry ? colors.dim(r.expiry.slice(0, 10)) : colors.dim("?"),
+              resolves: r.resolves
+                ? colors.green(r.resolutionSource)
+                : colors.red("no"),
+            })),
+            [
+              { key: "domain", header: "DOMAIN" },
+              { key: "cert", header: "CERT" },
+              { key: "expiry", header: "EXPIRES" },
+              { key: "resolves", header: "LOOPBACK" },
+            ],
+          );
+          if (rows.some((r) => r.flat)) {
+            stdout.write(
+              colors.dim(
+                "\n(flat) = cert lives directly in ~/.config/dev-certs/ instead of a subdirectory. Run `synapse https migrate --root=~/.config/dev-certs` to reorganise.\n",
+              ),
+            );
+          }
+        },
+      );
+      return;
+    }
+
+    // Single-domain detail mode.
+    const det = await detectMod.scan({ domain, cwd: ctx.cwd });
+    ctx.out.result(det, (d, { stdout }) => renderDomainStatus(d, { stdout }));
+  },
+
+  // Exports for tests.
+  renderDomainStatus,
+};

package/lib/commands/list.js

@@ -0,0 +1,186 @@
+// `synapse list [deployments|projects|teams]` — read-only catalog
+// dumper. Single-arg subcommand that mirrors what you'd see in the
+// dashboard, but scriptable (every subcommand supports --json).
+//
+// Resolution rules:
+//   - `list teams`        → no flag needed (always lists the operator's teams)
+//   - `list projects`     → uses linked team OR --team=<slug|id>
+//   - `list deployments`  → uses linked project OR --project=<id>
+
+const colors = require("../colors");
+const { extractTeamFlag, extractProjectFlag } = require("./_resource");
+
+const KINDS = ["deployments", "projects", "teams"];
+
+async function listTeams(ctx) {
+  const teams = await ctx.api.teams();
+  ctx.out.result(
+    { kind: "teams", count: teams.length, teams },
+    (_d, { stdout }) => {
+      if (teams.length === 0) {
+        stdout.write(colors.dim("(no teams — create one in the dashboard)\n"));
+        return;
+      }
+      ctx.out.table(
+        teams.map((t) => ({
+          name: colors.bold(t.name || t.slug || t.id),
+          slug: t.slug || colors.dim("?"),
+          id: colors.dim(t.id),
+        })),
+        [
+          { key: "name", header: "NAME" },
+          { key: "slug", header: "SLUG" },
+          { key: "id", header: "ID" },
+        ],
+      );
+    },
+  );
+}
+
+async function listProjects(ctx, args) {
+  const { teamRef: explicit, rest } = extractTeamFlag(args);
+  if (rest.length > 0) {
+    throw new Error(
+      `Unexpected positional: ${rest[0]}. Usage: synapse list projects [--team=<slug|id>]`,
+    );
+  }
+  // Linked-project fallback uses ctx.projectConfig.team.slug.
+  let teamRef = explicit;
+  let source = "flag";
+  if (!teamRef) {
+    const linked = ctx.projectConfig;
+    if (linked && linked.team && (linked.team.slug || linked.team.id)) {
+      teamRef = linked.team.slug || linked.team.id;
+      source = "linked";
+    }
+  }
+  if (!teamRef) {
+    throw new Error(
+      "No linked team. Pass --team=<slug|id> or run `synapse select` first.",
+    );
+  }
+  const projects = await ctx.api.projects(teamRef);
+  ctx.out.result(
+    { kind: "projects", team: teamRef, teamSource: source, count: projects.length, projects },
+    (_d, { stdout }) => {
+      stdout.write(colors.dim(`Team: ${teamRef}\n`));
+      if (projects.length === 0) {
+        stdout.write(colors.dim("(no projects)\n"));
+        return;
+      }
+      ctx.out.table(
+        projects.map((p) => ({
+          name: colors.bold(p.name || p.slug),
+          slug: p.slug || colors.dim("?"),
+          id: colors.dim(p.id),
+        })),
+        [
+          { key: "name", header: "NAME" },
+          { key: "slug", header: "SLUG" },
+          { key: "id", header: "ID" },
+        ],
+      );
+    },
+  );
+}
+
+async function listDeployments(ctx, args) {
+  const { projectId: explicit, rest } = extractProjectFlag(args);
+  if (rest.length > 0) {
+    throw new Error(
+      `Unexpected positional: ${rest[0]}. Usage: synapse list deployments [--project=<id>]`,
+    );
+  }
+  let projectId = explicit;
+  let source = "flag";
+  if (!projectId) {
+    const linked = ctx.projectConfig;
+    if (linked && linked.project && linked.project.id) {
+      projectId = linked.project.id;
+      source = "linked";
+    }
+  }
+  if (!projectId) {
+    throw new Error(
+      "No linked project. Pass --project=<id> or run `synapse select` first.",
+    );
+  }
+  const deployments = await ctx.api.deployments(projectId);
+  ctx.out.result(
+    { kind: "deployments", projectId, projectSource: source, count: deployments.length, deployments },
+    (_d, { stdout }) => {
+      stdout.write(colors.dim(`Project: ${projectId}\n`));
+      if (deployments.length === 0) {
+        stdout.write(colors.dim("(no deployments — create one with `synapse deployment create`)\n"));
+        return;
+      }
+      ctx.out.table(
+        deployments.map((d) => ({
+          name: colors.bold(d.name),
+          type: typeBadge(d.deploymentType || d.type),
+          status: colors.statusBadge(d.status || ""),
+          url: d.deploymentUrl || d.url || colors.dim("(no url)"),
+        })),
+        [
+          { key: "name", header: "NAME" },
+          { key: "type", header: "TYPE" },
+          { key: "status", header: "STATUS" },
+          { key: "url", header: "URL" },
+        ],
+      );
+    },
+  );
+}
+
+function typeBadge(t) {
+  switch (t) {
+    case "prod":
+      return colors.yellow((t || "").toUpperCase());
+    case "dev":
+      return colors.cyan ? colors.cyan(t.toUpperCase()) : t.toUpperCase();
+    case "preview":
+      return colors.dim((t || "").toUpperCase());
+    default:
+      return t ? colors.dim(t) : "";
+  }
+}
+
+module.exports = {
+  name: "list",
+  summary: "List teams, projects, or deployments visible to your session.",
+  usage: "synapse list <deployments|projects|teams> [--project=<id>] [--team=<slug>] [--json]",
+  description: `Catalogs the resource of the chosen kind. All subcommands support --json for scripting.
+
+Resource resolution:
+  list teams        always lists every team you're a member of
+  list projects     uses the linked team if no --team flag
+  list deployments  uses the linked project if no --project flag
+
+Examples:
+  synapse list teams
+  synapse list projects --team=amageia
+  synapse list deployments --project=00000000-0000-0000-0000-000000000000
+  synapse list deployments --json | jq '.deployments[] | .name'`,
+
+  // Exports for tests.
+  KINDS,
+  listTeams,
+  listProjects,
+  listDeployments,
+
+  async run(args, ctx) {
+    const kind = args[0];
+    if (!kind) {
+      throw new Error(`Usage: synapse list <${KINDS.join("|")}>`);
+    }
+    if (!KINDS.includes(kind)) {
+      throw new Error(
+        `Unknown list kind: ${kind}. Try: ${KINDS.join(" | ")}.`,
+      );
+    }
+    const rest = args.slice(1);
+    if (kind === "teams") return listTeams(ctx);
+    if (kind === "projects") return listProjects(ctx, rest);
+    return listDeployments(ctx, rest);
+  },
+};