@iann29/synapse 1.6.17 → 1.8.0

package/lib/commands/doctor.js

@@ -0,0 +1,82 @@
+// `synapse doctor` — the health-check battery. Walks ~12 checks
+// across 4 categories (local-env, project, backend, deployments)
+// in parallel where possible, then renders a panorama.
+//
+// Output is either a pretty terminal report (default) or a stable
+// machine-readable JSON tree (--json). Exit codes: 0 ok, 1 warnings
+// only, 2 at least one issue.
+
+const path = require("node:path");
+const os = require("node:os");
+const { configPath } = require("../config");
+const { generateReport, SCHEMA_VERSION } = require("../doctor/runner");
+const { renderReport } = require("../doctor/renderer");
+
+function parseFlags(args) {
+  let fix = false;
+  let yes = false;
+  let verbose = false;
+  const rest = [];
+  for (const a of args) {
+    if (a === "--fix") fix = true;
+    else if (a === "--yes" || a === "-y") yes = true;
+    else if (a === "--verbose" || a === "-v") verbose = true;
+    else rest.push(a);
+  }
+  return { fix, yes, verbose, rest };
+}
+
+module.exports = {
+  name: "doctor",
+  summary: "Run a health-check panorama on your local setup + Synapse backend + deployments.",
+  usage: "synapse doctor [--fix] [--yes] [--verbose] [--json]",
+  description: `Runs ~12 checks across local environment, project metadata, backend connectivity, and per-deployment health. Reports each check, the bottom-line totals, and exits with status:
+
+  0  everything ok
+  1  at least one warning (still functional)
+  2  at least one issue (probably blocks your next deploy)
+
+Flags:
+  --fix       apply safe fixes automatically (chmod, gitignore appends, etc).
+              Checks marked 'prompt' require --yes too.
+  --yes       upgrade 'prompt' fixes to auto.
+  --verbose   show detailed data per check.
+  --json      stable schema (current: v${SCHEMA_VERSION}); CI-friendly.
+
+The --json output schema is documented in cli/schema/doctor-v${SCHEMA_VERSION}.json.`,
+
+  async run(args, ctx) {
+    const { fix, yes, verbose } = parseFlags(args);
+    // Build doctor's ctx — augment the dispatcher ctx with helpers
+    // checks expect (cfgPath for the home config, env for shell vars).
+    let api = null;
+    try {
+      // ctx.api throws if not logged in; we want checks to handle the
+      // "not logged in" case gracefully via cfgOrNull, so build the
+      // api lazily and only when we have a session.
+      if (ctx.cfgOrNull && ctx.cfgOrNull.accessToken) {
+        api = ctx.api;
+      }
+    } catch {
+      api = null;
+    }
+
+    const doctorCtx = {
+      cwd: ctx.cwd,
+      env: ctx.env,
+      cfg: ctx.cfgOrNull,
+      api,
+      projectConfig: ctx.projectConfig,
+      cfgPath: configPath(),
+      homedir: os.homedir(),
+    };
+
+    const report = await generateReport(doctorCtx, { fix, allowPrompt: yes });
+
+    ctx.out.result(report, (d, { stdout }) => {
+      renderReport(d, { stdout, verbose });
+    });
+
+    process.exitCode = report.exitCode;
+  },
+};

package/lib/commands/login.js

@@ -0,0 +1,43 @@
+// `synapse login <url>` — register the operator's session against a
+// Synapse instance. The flow is intentionally minimal so it works
+// over piped stdin (CI bootstrap): the prompts library detects a
+// non-TTY and accepts `email\npassword\n` instead of rendering the
+// hidden-password prompt.
+
+const { askCredentials } = require("../prompts");
+const { SynapseAPI } = require("../api");
+const { normalizeBaseUrl, writeConfig } = require("../config");
+
+module.exports = {
+  name: "login",
+  summary: "Authenticate against a Synapse instance and save the session locally.",
+  usage: "synapse login <url>",
+  description: `Prompts for email + password (or reads them piped on stdin) and writes the resulting session to ~/.synapse/config.json (mode 0600).
+
+The saved session carries both the access token (1h TTL) and a refresh token (30d TTL); subsequent commands silent-refresh on 401 transparently — operators don't see /login prompts mid-task.`,
+
+  async run(args, ctx) {
+    const url = args[0];
+    if (!url) {
+      throw new Error("Usage: synapse login <url>");
+    }
+    const baseUrl = normalizeBaseUrl(url);
+    const { email, password } = await askCredentials();
+    const api = new SynapseAPI({ baseUrl });
+    const session = await api.login(email, password);
+    if (!session.accessToken) {
+      throw new Error("Synapse login response did not include accessToken");
+    }
+    const file = writeConfig({
+      baseUrl,
+      accessToken: session.accessToken,
+      refreshToken: session.refreshToken || null,
+      tokenType: session.tokenType || "Bearer",
+      user: session.user || null,
+    });
+    ctx.out.result(
+      { baseUrl, user: session.user || null, configPath: file },
+      () => ctx.out.info(`Saved Synapse session to ${file}`),
+    );
+  },
+};

package/lib/commands/logout.js

@@ -0,0 +1,20 @@
+// `synapse logout` — clear the saved session from ~/.synapse/config.json.
+// No backend call (the JWT stays technically valid until exp; the
+// point is to delete the refresh token from this machine so future
+// 401s can't silent-refresh into a fresh session).
+
+const { clearConfig } = require("../config");
+
+module.exports = {
+  name: "logout",
+  summary: "Clear the saved Synapse session from this machine.",
+  usage: "synapse logout",
+  description: `Deletes ~/.synapse/config.json. Does not contact the backend — tokens stay technically valid until their natural exp, but the refresh token is gone so silent-refresh can no longer pick up where you left off.`,
+
+  async run(_args, ctx) {
+    const removed = clearConfig();
+    ctx.out.result({ removed }, () =>
+      ctx.out.info(removed ? "Logged out of Synapse." : "No Synapse session was saved."),
+    );
+  },
+};

package/lib/commands/open.js

@@ -0,0 +1,96 @@
+// `synapse open [target]` — launches a URL in the operator's default
+// browser. Cross-platform via the right `open` / `xdg-open` / `start`
+// command per OS.
+//
+// Targets:
+//   (default)        the linked project's page in the Synapse dashboard
+//   dashboard        same as default
+//   docs             docs.convex.dev (the upstream Convex docs)
+//   deployment <n>   /embed/<name> — the dashboard with Convex Dashboard iframe
+//   url              just the synapse base URL (for "open the dashboard root")
+//
+// No backend call; everything is built client-side from the saved cfg
+// + projectConfig.
+
+const { spawn } = require("node:child_process");
+
+function buildUrl(target, restArgs, { cfg, projectConfig }) {
+  const base = cfg?.baseUrl ?? "";
+  switch (target) {
+    case undefined:
+    case "dashboard": {
+      if (projectConfig?.team?.slug && projectConfig?.project?.id) {
+        return `${base}/teams/${encodeURIComponent(projectConfig.team.slug)}/${encodeURIComponent(projectConfig.project.id)}`;
+      }
+      // Fall back to /teams (operator picks the project visually).
+      return `${base}/teams`;
+    }
+    case "docs":
+      return "https://docs.convex.dev";
+    case "deployment": {
+      const name = restArgs[0];
+      if (!name) {
+        throw new Error("Usage: synapse open deployment <name>");
+      }
+      return `${base}/embed/${encodeURIComponent(name)}`;
+    }
+    case "url":
+      return base || "https://docs.convex.dev";
+    default:
+      throw new Error(
+        `Unknown target: ${target}. Try: dashboard | docs | deployment <name> | url`,
+      );
+  }
+}
+
+function launcher(platform = process.platform) {
+  if (platform === "darwin") return { cmd: "open", shell: false };
+  if (platform === "win32") return { cmd: "start", shell: true };
+  // Linux + others
+  return { cmd: "xdg-open", shell: false };
+}
+
+module.exports = {
+  name: "open",
+  summary: "Open a Synapse-related URL in your default browser.",
+  usage: "synapse open [dashboard|docs|deployment <name>|url] [--json]",
+  description: `Launches a browser. With no argument, opens the linked project's page in the dashboard.
+
+Targets:
+  dashboard       project page on the Synapse dashboard (default)
+  docs            https://docs.convex.dev
+  deployment <n>  /embed/<n> — Convex Dashboard iframe shell
+  url             the saved Synapse base URL`,
+
+  // Exports for tests.
+  buildUrl,
+  launcher,
+
+  async run(args, ctx) {
+    const target = args[0];
+    const url = buildUrl(target, args.slice(1), {
+      cfg: ctx.cfgOrNull,
+      projectConfig: ctx.projectConfig,
+    });
+
+    if (ctx.out.json) {
+      ctx.out.result({ url, target: target ?? "dashboard" }, () => {});
+      return;
+    }
+
+    const { cmd, shell } = launcher();
+    ctx.out.info(`Opening ${url}`);
+    try {
+      const child = spawn(cmd, [url], { stdio: "ignore", detached: true, shell });
+      child.unref();
+    } catch (err) {
+      // If the launcher isn't on PATH (rare — xdg-open is part of
+      // xdg-utils, ships on every desktop Linux), the operator can
+      // still see the URL we tried.
+      ctx.out.error(`Could not launch browser: ${err.message}`, {
+        hint: `Open this URL manually: ${url}`,
+      });
+      process.exitCode = 1;
+    }
+  },
+};

package/lib/commands/select.js

@@ -0,0 +1,239 @@
+// `synapse select` — link the current directory to a Synapse project +
+// pick a dev/prod deployment, then write the local artifacts
+// (.synapse/project.json + .env.local).
+//
+// The picker walks team → project → dev → prod as a state machine so
+// the operator can type `b` at any level to step back one. Auto-
+// selects each level when only one option exists. DEBUG_SYNAPSE=1
+// dumps the underlying lists at every step — useful when a real
+// deployment is mysteriously missing from the menu.
+
+const colors = require("../colors");
+const { writeProjectEnv } = require("../env-file");
+const {
+  buildProjectConfig,
+  writeProjectConfig,
+} = require("../project");
+const { BACK, choose } = require("../prompts");
+
+function labelName(item) {
+  const name = item.name || item.slug || item.id;
+  const slug = item.slug && item.slug !== name ? ` (${item.slug})` : "";
+  return `${name}${slug}`;
+}
+
+function teamRef(team) {
+  return team.slug || team.id;
+}
+
+function deploymentType(deployment) {
+  return deployment.deploymentType || deployment.type || "";
+}
+
+function deploymentLabel(deployment) {
+  const bits = [colors.bold(deployment.name)];
+  const type = deploymentType(deployment);
+  if (type) bits.push(colors.dim(type));
+  if (deployment.status) bits.push(colors.statusBadge(deployment.status));
+  return bits.filter(Boolean).join(" - ");
+}
+
+function sortDeploymentsForChoice(deployments) {
+  return [...deployments].sort((a, b) => {
+    if (!!a.isDefault !== !!b.isDefault) {
+      return a.isDefault ? -1 : 1;
+    }
+    return String(b.createTime || b.createdAt || "").localeCompare(
+      String(a.createTime || a.createdAt || ""),
+    );
+  });
+}
+
+function debugLog(msg) {
+  if (process.env.DEBUG_SYNAPSE) {
+    process.stderr.write(`[DEBUG] ${msg}\n`);
+  }
+}
+
+async function chooseDeploymentForType(type, deployments, chooseOpts = {}) {
+  const matches = sortDeploymentsForChoice(
+    deployments.filter(
+      (d) => deploymentType(d) === type && d.status !== "deleted",
+    ),
+  );
+  debugLog(
+    `chooseDeploymentForType(${type}): matched ${matches.length} of ${deployments.length} ` +
+      `(types: ${deployments.map((d) => deploymentType(d) || "?").join(",")})`,
+  );
+  if (matches.length === 0) return null;
+  return await choose(
+    `${type} deployments`,
+    matches.map((d) => ({ label: deploymentLabel(d), value: d })),
+    { singularLabel: `${type} deployment`, ...chooseOpts },
+  );
+}
+
+module.exports = {
+  name: "select",
+  summary: "Link this directory to a Synapse project and pick its dev/prod deployments.",
+  usage: "synapse select",
+  description: `Walks an interactive picker (team → project → dev → prod) and writes:
+  .synapse/project.json   refs only — no secrets, safe to commit
+  .env.local              CONVEX_SELF_HOSTED_URL + CONVEX_SELF_HOSTED_ADMIN_KEY
+
+Auto-selects levels where only one option exists. Type 'b' at any
+prompt to step back. Set DEBUG_SYNAPSE=1 to print the raw lists
+returned at every step (useful when an expected deployment doesn't
+show up in the menu).`,
+
+  // Exported for legacy test imports.
+  chooseDeploymentForType,
+  deploymentLabel,
+  deploymentType,
+  labelName,
+  sortDeploymentsForChoice,
+
+  async run(_args, ctx) {
+    const { api } = ctx;
+    const cfg = ctx.cfg;
+
+    const cache = {
+      teamsList: null,
+      projectsByTeamKey: new Map(),
+      deploymentsByProjectId: new Map(),
+    };
+    async function fetchTeams() {
+      if (!cache.teamsList) {
+        cache.teamsList = await api.teams();
+        debugLog(`teams loaded: ${cache.teamsList.length}`);
+      }
+      return cache.teamsList;
+    }
+    async function fetchProjects(team) {
+      const key = team.id || team.slug || team.name;
+      if (!cache.projectsByTeamKey.has(key)) {
+        const projects = await api.projects(teamRef(team));
+        cache.projectsByTeamKey.set(key, projects);
+        debugLog(`projects for team ${key}: ${projects.length}`);
+      }
+      return cache.projectsByTeamKey.get(key);
+    }
+    async function fetchDeployments(project) {
+      if (!cache.deploymentsByProjectId.has(project.id)) {
+        const deployments = await api.deployments(project.id);
+        cache.deploymentsByProjectId.set(project.id, deployments);
+        debugLog(`deployments for project ${project.id}: ${deployments.length}`);
+      }
+      return cache.deploymentsByProjectId.get(project.id);
+    }
+
+    let team = null;
+    let project = null;
+    let dev = null;
+    let prod = null;
+    let step = "team";
+    while (step !== "done") {
+      if (step === "team") {
+        const teams = await fetchTeams();
+        const picked = await choose(
+          "teams",
+          teams.map((t) => ({ label: labelName(t), value: t })),
+          { singularLabel: "team", allowBack: false },
+        );
+        team = picked;
+        step = "project";
+      } else if (step === "project") {
+        const projects = await fetchProjects(team);
+        const picked = await choose(
+          "projects",
+          projects.map((p) => ({ label: labelName(p), value: p })),
+          { singularLabel: "project", allowBack: true },
+        );
+        if (picked === BACK) {
+          step = "team";
+          continue;
+        }
+        project = picked;
+        step = "dev";
+      } else if (step === "dev") {
+        const deployments = await fetchDeployments(project);
+        const picked = await chooseDeploymentForType("dev", deployments, {
+          allowBack: true,
+        });
+        if (picked === BACK) {
+          step = "project";
+          continue;
+        }
+        if (picked === null) {
+          throw new Error(
+            "No dev deployments available in this project. Create one first in the dashboard.",
+          );
+        }
+        dev = picked;
+        step = "prod";
+      } else if (step === "prod") {
+        const deployments = await fetchDeployments(project);
+        const picked = await chooseDeploymentForType("prod", deployments, {
+          allowBack: true,
+        });
+        if (picked === BACK) {
+          step = "dev";
+          continue;
+        }
+        prod = picked; // null is valid (no prod yet)
+        step = "done";
+      }
+    }
+
+    const projectPath = writeProjectConfig(
+      ctx.cwd,
+      buildProjectConfig({
+        synapseUrl: cfg.baseUrl,
+        team,
+        project,
+        deployments: { dev, prod },
+      }),
+    );
+    const creds = await api.cliCredentials(dev.name);
+    const envPath = writeProjectEnv(ctx.cwd, creds);
+
+    ctx.out.result(
+      {
+        synapseUrl: cfg.baseUrl,
+        team: { id: team.id, slug: team.slug, name: team.name },
+        project: { id: project.id, slug: project.slug, name: project.name },
+        deployments: {
+          dev: { name: dev.name, type: deploymentType(dev), status: dev.status },
+          prod: prod
+            ? { name: prod.name, type: deploymentType(prod), status: prod.status }
+            : null,
+        },
+        files: { projectConfig: projectPath, envLocal: envPath },
+      },
+      () => {
+        ctx.out.info(`\nLinked ${labelName(project)} to ${projectPath}.`);
+        ctx.out.info(
+          `Selected dev deployment ${colors.bold(dev.name)}. Updated ${envPath}.`,
+        );
+        if (prod) {
+          ctx.out.info(`Selected prod deployment ${colors.bold(prod.name)}.`);
+        } else {
+          ctx.out.warn(
+            "no prod deployment found. `synapse deploy` (and `synapse convex deploy`) will fail with a clear error until you create a prod deployment and run `synapse select` again.",
+          );
+        }
+        if (process.env.CONVEX_DEPLOYMENT) {
+          ctx.out.warn(
+            "shell CONVEX_DEPLOYMENT is set. Use `synapse dev` / `synapse deploy` / `synapse convex ...` or unset CONVEX_DEPLOYMENT before running `npx convex` directly.",
+          );
+        }
+        ctx.out.info(
+          `\nNext step: run ${colors.bold("synapse dev")} (or ${colors.bold("npx convex dev")}) once in this directory to push your schema and watch for changes.`,
+        );
+      },
+    );
+    // Force ctx.projectConfig to re-read on next access (commands chained
+    // after select within the same process should see the new file).
+    ctx.refreshProjectConfig();
+  },
+};

package/lib/commands/status.js

@@ -0,0 +1,173 @@
+// `synapse status` — quick summary of every deployment in the linked
+// project. Status icon + type badge + URL + URL form chip. Mirrors
+// what the dashboard's project page shows, in 1 terminal screen.
+//
+// Works without `synapse select` IF --project=<id> is passed. Otherwise
+// reads .synapse/project.json from cwd.
+
+const colors = require("../colors");
+
+// Same heuristic as dashboard/app/embed/[name]/page.tsx:isBrowserReachableURL.
+// We classify the URL form so the operator knows at a glance which
+// deployments are reachable from the browser vs which fall back to
+// the host:port form that needs SYNAPSE_BASE_DOMAIN or a custom domain.
+function urlForm(rawUrl, publicUrl) {
+  if (!rawUrl) return "unknown";
+  let u;
+  try {
+    u = new URL(rawUrl);
+  } catch {
+    return "unknown";
+  }
+  if (u.pathname.startsWith("/d/")) return "path";
+  const STANDARD = new Set(["", "443", "80", "6791"]);
+  if (
+    !STANDARD.has(u.port) &&
+    u.hostname !== "localhost" &&
+    u.hostname !== "127.0.0.1"
+  ) {
+    return "host";
+  }
+  if (!publicUrl) return "custom";
+  try {
+    const pu = new URL(publicUrl);
+    if (u.hostname === pu.hostname) return "custom";
+    if (u.hostname.endsWith("." + pu.hostname)) return "wildcard";
+    return "custom";
+  } catch {
+    return "custom";
+  }
+}
+
+function parseFlags(args) {
+  let projectId = null;
+  const rest = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--project") {
+      projectId = args[i + 1];
+      i += 1;
+    } else if (arg.startsWith("--project=")) {
+      projectId = arg.slice("--project=".length);
+    } else {
+      rest.push(arg);
+    }
+  }
+  return { projectId, rest };
+}
+
+module.exports = {
+  name: "status",
+  summary: "List deployments in the linked project with status + URL form.",
+  usage: "synapse status [--project=<id>] [--json]",
+  description: `Lists every deployment in the linked project (or the project given by --project=<id>) along with its status, URL, and URL form ('custom' / 'wildcard' / 'path' / 'host').
+
+The URL form tells you whether the deployment is reachable from a browser:
+  custom    bound to a custom domain (api.client.com) — reachable
+  wildcard  uses SYNAPSE_BASE_DOMAIN subdomain — reachable
+  path      /d/<name>/* via the proxy — browser-reachable but CLI-broken
+            (the Convex CLI strips paths from base URLs)
+  host      host:port form — NOT reachable from a normal browser
+            (Caddy doesn't TLS-front dynamic ports)
+
+Run \`synapse doctor\` for a deeper health check.`,
+
+  // Re-exports for tests.
+  urlForm,
+  parseFlags,
+
+  async run(args, ctx) {
+    const { projectId: explicitProjectId } = parseFlags(args);
+    let projectId = explicitProjectId;
+    let projectLabel = null;
+    if (!projectId) {
+      const pc = ctx.requireProject();
+      projectId = pc.project.id;
+      projectLabel = pc.project.name || pc.project.slug;
+    }
+
+    const deployments = await ctx.api.deployments(projectId);
+    const baseUrl = ctx.cfg.baseUrl;
+
+    const rows = deployments.map((d) => {
+      const type = d.deploymentType || d.type || "";
+      const url = d.deploymentUrl || d.url || "";
+      return {
+        name: d.name,
+        type,
+        status: d.status,
+        url,
+        urlForm: urlForm(url, baseUrl),
+        isDefault: !!d.isDefault,
+        adopted: !!d.adopted,
+        haEnabled: !!d.haEnabled,
+        replicaCount: d.replicaCount,
+      };
+    });
+
+    ctx.out.result(
+      { projectId, project: projectLabel, deployments: rows },
+      (data, { stdout }) => {
+        if (data.project) {
+          stdout.write(colors.bold(`Project: ${data.project}\n`));
+        }
+        if (rows.length === 0) {
+          stdout.write(colors.dim("(no deployments)\n"));
+          return;
+        }
+        const tag = (form) => {
+          switch (form) {
+            case "custom":
+              return colors.green("custom");
+            case "wildcard":
+              return colors.green("wildcard");
+            case "path":
+              return colors.dim("path");
+            case "host":
+              return colors.red("no-domain");
+            default:
+              return colors.dim("?");
+          }
+        };
+        ctx.out.table(
+          rows.map((r) => ({
+            name: colors.bold(r.name),
+            type: typeBadge(r.type),
+            status: colors.statusBadge(r.status || ""),
+            urlForm: tag(r.urlForm),
+            url: r.url,
+          })),
+          [
+            { key: "name", header: "NAME" },
+            { key: "type", header: "TYPE" },
+            { key: "status", header: "STATUS" },
+            { key: "urlForm", header: "FORM" },
+            { key: "url", header: "URL" },
+          ],
+        );
+        const broken = rows.filter((r) => r.urlForm === "host").length;
+        if (broken > 0) {
+          stdout.write("\n");
+          ctx.out.warn(
+            `${broken} deployment${broken > 1 ? "s" : ""} not browser-reachable — set SYNAPSE_BASE_DOMAIN on the server OR add a custom domain per deployment. Run \`synapse doctor\` for the full diagnosis.`,
+          );
+        }
+      },
+    );
+  },
+};
+
+// Tiny tone helper that mirrors the dashboard's envTone() so colors
+// stay consistent across UI surfaces.
+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) : "";
+  }
+}