@iann29/synapse 1.7.0 → 1.8.1

package/lib/commands/doctor.js

@@ -0,0 +1,86 @@
+// `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. Combined with --fix, also
+              cleans up a stale .synapse/project.json — re-links if the
+              project was transferred to another of your teams,
+              otherwise marks the entry stale so \`synapse select\` can
+              start fresh.
+  --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,143 @@
+// `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")
+//
+// For `dashboard` (the default), we do a single cheap GET probe against
+// the linked project before spawning the browser, so an operator with a
+// stale .synapse/project.json gets a warning on stderr instead of
+// landing on a page that cascades "Failed to load X" errors. We never
+// BLOCK the launch — operator may want to see the broken state.
+// `docs` / `deployment <name>` / `url` skip the probe.
+
+const { spawn } = require("node:child_process");
+const { SynapseAPIError } = require("../api");
+
+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 };
+}
+
+// Cheap pre-flight probe: confirm the linked project still exists before
+// launching the browser. Returns one of:
+//   "ok"          — project resolved on the backend
+//   "not_found"   — backend returned 404 (project deleted or transferred)
+//   "unverified"  — couldn't reach backend / non-404 error / no session /
+//                   no linked project
+// Only `dashboard` target calls this — `docs` is external, `deployment
+// <name>` and `url` are operator-supplied + assumed intentional.
+async function checkProjectStatus(ctx, projectConfig) {
+  if (!projectConfig?.project?.id) return "unverified";
+  if (!ctx?.cfgOrNull?.accessToken) return "unverified";
+  if (!ctx.api) return "unverified";
+  try {
+    await ctx.api.getProject(projectConfig.project.id);
+    return "ok";
+  } catch (err) {
+    if (err instanceof SynapseAPIError && err.status === 404) {
+      return "not_found";
+    }
+    return "unverified";
+  }
+}
+
+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,
+  checkProjectStatus,
+
+  async run(args, ctx) {
+    const target = args[0];
+    const url = buildUrl(target, args.slice(1), {
+      cfg: ctx.cfgOrNull,
+      projectConfig: ctx.projectConfig,
+    });
+
+    // Pre-flight only for dashboard (default + explicit). Other targets
+    // either point externally or are intentionally URL-direct.
+    const shouldProbe = target === undefined || target === "dashboard";
+    let projectStatus = "unverified";
+    if (shouldProbe && ctx.projectConfig?.project?.id) {
+      projectStatus = await checkProjectStatus(ctx, ctx.projectConfig);
+    }
+
+    if (ctx.out.json) {
+      ctx.out.result({ url, target: target ?? "dashboard", projectStatus }, () => {});
+      return;
+    }
+
+    if (projectStatus === "not_found") {
+      const projName = ctx.projectConfig?.project?.name || ctx.projectConfig?.project?.id;
+      const base = ctx.cfgOrNull?.baseUrl ?? "";
+      ctx.out.warn(
+        `Linked project ${projName} was not found on ${base}. It may have been deleted. Run \`synapse select\` to relink.`,
+      );
+    } else if (shouldProbe && projectStatus === "unverified" && ctx.projectConfig?.project?.id && ctx.cfgOrNull?.accessToken) {
+      ctx.out.info("Could not verify project state (offline?), opening anyway.");
+    }
+
+    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();
+  },
+};