@iann29/synapse 1.6.17 → 1.8.0

package/lib/commands/_context.js

@@ -0,0 +1,133 @@
+// Runtime context handed to every command's `run(rest, ctx)`.
+//
+// The dispatcher constructs one of these per invocation. It carries:
+//   - cfg / api: the operator's session and a refresh-aware API client,
+//     lazily built (commands like `version` that don't need a session
+//     can read ctx.cfgOrNull without forcing the user to log in first).
+//   - out: the shared output layer (createOutput()), already aware of
+//     whether --json was on the argv.
+//   - projectDir / projectConfig: convenience accessors for commands
+//     that need the linked project metadata (.synapse/project.json).
+//
+// Commands MUST go through ctx instead of touching process.stdout /
+// process.cwd directly — otherwise --json piping and the test fakes
+// stop working.
+
+const { SynapseAPI, SynapseAPIError } = require("../api");
+const {
+  clearConfig: _clearConfig,
+  normalizeBaseUrl,
+  readConfig,
+  requireConfig,
+  writeConfig,
+} = require("../config");
+const { readProjectConfig } = require("../project");
+
+// Wraps an API client so any 401 transparently retries against
+// /v1/auth/refresh once. Mirrors what bin/synapse.js had before the
+// refactor; lives here so every command shares it.
+function makeRefreshableApi(cfg) {
+  const api = new SynapseAPI({ baseUrl: cfg.baseUrl, accessToken: cfg.accessToken });
+  return new Proxy(api, {
+    get(target, prop) {
+      const value = target[prop];
+      if (typeof value !== "function") return value;
+      return async (...args) => {
+        try {
+          return await value.apply(target, args);
+        } catch (err) {
+          if (
+            !(err instanceof SynapseAPIError) ||
+            err.status !== 401 ||
+            !cfg.refreshToken
+          ) {
+            throw err;
+          }
+          const session = await new SynapseAPI({ baseUrl: cfg.baseUrl }).refresh(
+            cfg.refreshToken,
+          );
+          if (!session.accessToken) throw err;
+          cfg.accessToken = session.accessToken;
+          cfg.refreshToken = session.refreshToken || cfg.refreshToken;
+          cfg.tokenType = session.tokenType || cfg.tokenType || "Bearer";
+          if (session.user) cfg.user = session.user;
+          writeConfig(cfg);
+          target.accessToken = cfg.accessToken;
+          return await value.apply(target, args);
+        }
+      };
+    },
+  });
+}
+
+function createContext({ out, cwd = process.cwd(), env = process.env } = {}) {
+  let _cfg = null;
+  let _api = null;
+  let _projectConfig;
+  const cfgLoad = () => {
+    if (_cfg === undefined || _cfg === null) {
+      _cfg = readConfig(); // may be null if not logged in
+    }
+    return _cfg;
+  };
+
+  return {
+    out,
+    cwd,
+    env,
+
+    // Returns the saved config or null. Commands that don't need a
+    // session (version, doctor's local checks) use this.
+    get cfgOrNull() {
+      return cfgLoad();
+    },
+
+    // Throws "Not logged in" with a helpful message when no session
+    // exists. Commands that REQUIRE auth call this.
+    get cfg() {
+      const c = cfgLoad();
+      if (!c || !c.baseUrl || !c.accessToken) {
+        throw new Error("Not logged in. Run `synapse login <url>` first.");
+      }
+      _cfg = c;
+      return c;
+    },
+
+    // Builds an auth+refresh-aware API client on demand.
+    get api() {
+      if (_api) return _api;
+      const c = this.cfg; // throws if not logged in
+      _api = makeRefreshableApi(c);
+      return _api;
+    },
+
+    // Re-reads the project metadata from disk on first access only —
+    // commands that mutate it (synapse select) call this AFTER writing.
+    get projectConfig() {
+      if (_projectConfig === undefined) {
+        _projectConfig = readProjectConfig(cwd);
+      }
+      return _projectConfig;
+    },
+
+    // Convenience for commands that need to verify a project is linked.
+    requireProject() {
+      const p = this.projectConfig;
+      if (!p) {
+        throw new Error(
+          "No Synapse project metadata found in this directory. Run `synapse select` first.",
+        );
+      }
+      return p;
+    },
+
+    // Force a re-read of the project config (e.g. after `synapse select`
+    // wrote a new file mid-handler).
+    refreshProjectConfig() {
+      _projectConfig = readProjectConfig(cwd);
+      return _projectConfig;
+    },
+  };
+}
+
+module.exports = { createContext, makeRefreshableApi, normalizeBaseUrl };

package/lib/commands/_dispatcher.js

@@ -0,0 +1,75 @@
+// Command registry + two-word-then-one-word dispatcher.
+//
+// The CLI ships ~28 commands across both flat shortcuts (`synapse dev`,
+// `synapse login`) and resource subcommands (`synapse deployment create`,
+// `synapse env set`). A registry keyed by the literal command path
+// ("dev" or "deployment create") makes routing predictable, keeps each
+// handler in its own file, and avoids a 2k-line nested switch.
+//
+// Resolution order, applied left-to-right against argv:
+//   1. Two-word lookup ("deployment create") — wins when present so
+//      subcommand groups override any bare top-level synonym.
+//   2. One-word lookup ("dev") — falls through for legacy shortcuts.
+//   3. Miss → caller surfaces "unknown command" with help.
+//
+// Each command module exports:
+//   {
+//     name:        string,    // canonical id, e.g. "deployment create"
+//     summary:     string,    // 1-line description for root help
+//     usage:       string,    // exact usage line for per-command help
+//     description?: string,   // multi-paragraph help body
+//     run:         async (rest, ctx) => void | number
+//   }
+//
+// `ctx` is the runtime context (see context.js) — gives every handler
+// access to the resolved config, an API client, the output layer, and
+// process I/O without each one re-bootstrapping.
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+function buildRegistry() {
+  const dir = __dirname;
+  const map = new Map();
+  for (const file of fs.readdirSync(dir)) {
+    if (!file.endsWith(".js")) continue;
+    if (file.startsWith("_")) continue; // dispatcher.js, context.js, etc
+    if (file === "index.js") continue;
+    const mod = require(path.join(dir, file));
+    if (!mod || typeof mod.name !== "string" || typeof mod.run !== "function") {
+      throw new Error(
+        `commands/${file} does not export the { name, run } shape`,
+      );
+    }
+    if (map.has(mod.name)) {
+      throw new Error(
+        `Duplicate command registered: ${mod.name} (in ${file})`,
+      );
+    }
+    map.set(mod.name, mod);
+  }
+  return map;
+}
+
+// Resolve argv into { cmd, rest } using the two-then-one rule.
+// Returns { cmd: null, rest: argv } on miss so the caller can surface
+// the unknown-command error consistently.
+function resolve(registry, argv) {
+  if (!argv || argv.length === 0) return { cmd: null, rest: argv ?? [] };
+  if (argv.length >= 2) {
+    const two = `${argv[0]} ${argv[1]}`;
+    if (registry.has(two)) return { cmd: registry.get(two), rest: argv.slice(2) };
+  }
+  if (registry.has(argv[0])) return { cmd: registry.get(argv[0]), rest: argv.slice(1) };
+  return { cmd: null, rest: argv };
+}
+
+// Detect `--help` / `-h` anywhere in the args (positional-tolerant).
+// Returns boolean; doesn't mutate argv — handlers don't see the flag
+// because the dispatcher short-circuits to help rendering first.
+function wantsHelp(argv) {
+  if (!argv) return false;
+  return argv.some((a) => a === "--help" || a === "-h");
+}
+
+module.exports = { buildRegistry, resolve, wantsHelp };

package/lib/commands/_help.js

@@ -0,0 +1,105 @@
+// Root and per-command help rendering.
+//
+// `synapse help` and `synapse <cmd> --help` are routed here from the
+// dispatcher; no parser library, no template engine. We group commands
+// by their first space-delimited word so the root listing reads as
+// "top-level shortcuts" + "deployment.*", "project.*", "team.*", etc.
+
+const colors = require("../colors");
+
+function renderRootHelp(registry, { stdout = process.stdout } = {}) {
+  // Stable section order so the help page stays predictable across
+  // releases. Groups not listed here fall to the bottom alphabetically.
+  const SECTION_ORDER = [
+    ["Session", ["login", "logout", "whoami"]],
+    ["Project linking", ["select", "credentials"]],
+    ["Day-to-day", ["dev", "deploy"]],
+    ["Visibility", ["version", "status", "doctor", "open", "logs"]],
+    ["Deployments", "deployment"],
+    ["Projects", "project"],
+    ["Teams", "team"],
+    ["Env vars", "env"],
+    ["Domains", "domain"],
+    ["Escape hatch", ["convex"]],
+  ];
+
+  const used = new Set();
+  const lines = [
+    colors.bold("Synapse CLI") + colors.dim(" — manage Synapse-self-hosted Convex deployments"),
+    "",
+    "Usage:",
+    "  " + colors.bold("synapse") + " <command> [...args] [--json] [--help]",
+    "",
+  ];
+
+  for (const [title, spec] of SECTION_ORDER) {
+    const cmds = [];
+    if (Array.isArray(spec)) {
+      // Explicit command names.
+      for (const name of spec) {
+        if (registry.has(name)) {
+          cmds.push(registry.get(name));
+          used.add(name);
+        }
+      }
+    } else {
+      // Prefix-match (every command whose name starts with `<spec> `).
+      const prefix = spec + " ";
+      for (const [name, cmd] of registry) {
+        if (name.startsWith(prefix) && !used.has(name)) {
+          cmds.push(cmd);
+          used.add(name);
+        }
+      }
+      cmds.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    if (cmds.length === 0) continue;
+    lines.push(colors.dim(title));
+    const widest = Math.max(...cmds.map((c) => c.name.length));
+    for (const c of cmds) {
+      lines.push("  " + colors.bold(c.name.padEnd(widest)) + "  " + (c.summary || ""));
+    }
+    lines.push("");
+  }
+
+  // Any leftover registered commands fall here — keeps the help honest
+  // when someone adds a command without updating SECTION_ORDER.
+  const leftover = [];
+  for (const [name, cmd] of registry) {
+    if (!used.has(name)) leftover.push(cmd);
+  }
+  if (leftover.length > 0) {
+    lines.push(colors.dim("Other"));
+    leftover.sort((a, b) => a.name.localeCompare(b.name));
+    const widest = Math.max(...leftover.map((c) => c.name.length));
+    for (const c of leftover) {
+      lines.push("  " + colors.bold(c.name.padEnd(widest)) + "  " + (c.summary || ""));
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "Run " + colors.bold("synapse <command> --help") + " for command-specific help.",
+  );
+  lines.push("");
+  stdout.write(lines.join("\n"));
+}
+
+function renderCommandHelp(cmd, { stdout = process.stdout } = {}) {
+  const lines = [];
+  lines.push(colors.bold("synapse " + cmd.name));
+  if (cmd.summary) {
+    lines.push(colors.dim(cmd.summary));
+  }
+  lines.push("");
+  lines.push("Usage:");
+  lines.push("  " + (cmd.usage || `synapse ${cmd.name}`));
+  if (cmd.description) {
+    lines.push("");
+    lines.push(cmd.description.trimEnd());
+  }
+  lines.push("");
+  stdout.write(lines.join("\n"));
+}
+
+module.exports = { renderRootHelp, renderCommandHelp };

package/lib/commands/convex.js

@@ -0,0 +1,151 @@
+// `synapse convex [--target dev|prod] [...args]` — escape hatch that
+// delegates to `npx convex <args>` while wiring up Synapse credentials
+// transparently. Used directly when the operator needs a Convex
+// subcommand without a Synapse shortcut (run, env list, import, etc).
+//
+// `synapse dev` and `synapse deploy` are thin wrappers around this
+// same flow with the target pre-set and (for deploy) a confirmation
+// prompt.
+
+const { runConvex } = require("../convex");
+const { normalizeBaseUrl } = require("../config");
+const {
+  deploymentNameForTarget,
+  readProjectConfig,
+} = require("../project");
+
+function parseConvexTarget(args) {
+  let target = null;
+  let index = 0;
+  while (index < args.length) {
+    const arg = args[index];
+    if (arg === "--target") {
+      target = args[index + 1];
+      if (!target) {
+        throw new Error("--target requires dev or prod");
+      }
+      index += 2;
+      continue;
+    }
+    if (arg && arg.startsWith("--target=")) {
+      target = arg.slice("--target=".length);
+      index += 1;
+      continue;
+    }
+    break;
+  }
+  if (target && target !== "dev" && target !== "prod") {
+    throw new Error("--target must be dev or prod");
+  }
+  return {
+    explicitTarget: Boolean(target),
+    target,
+    args: args.slice(index),
+  };
+}
+
+function inferConvexTarget(args) {
+  const command = args.find((arg) => arg && !arg.startsWith("-")) || "";
+  return command === "deploy" ? "prod" : "dev";
+}
+
+function parseConvexInvocation(args) {
+  const parsed = parseConvexTarget(args);
+  return {
+    ...parsed,
+    target: parsed.target || inferConvexTarget(parsed.args),
+  };
+}
+
+async function resolveConvexInvocation(
+  args,
+  { cfg = null, api = null, projectDir = process.cwd() } = {},
+) {
+  const parsed = parseConvexInvocation(args);
+  const projectConfig = readProjectConfig(projectDir);
+  if (!projectConfig) {
+    if (parsed.explicitTarget) {
+      throw new Error(
+        "No Synapse project metadata found. Run `synapse select` first.",
+      );
+    }
+    return {
+      ...parsed,
+      credentials: null,
+      deploymentName: "",
+      projectConfig: null,
+      target: null,
+    };
+  }
+
+  if (!cfg || !api) {
+    throw new Error("Not logged in. Run `synapse login <url>` first.");
+  }
+  if (
+    projectConfig.synapseUrl &&
+    cfg.baseUrl &&
+    normalizeBaseUrl(projectConfig.synapseUrl) !== normalizeBaseUrl(cfg.baseUrl)
+  ) {
+    throw new Error(
+      `This project is linked to ${projectConfig.synapseUrl}, but the saved Synapse session is for ${cfg.baseUrl}. Run \`synapse login ${projectConfig.synapseUrl}\` or \`synapse select\` again.`,
+    );
+  }
+
+  const deploymentName = deploymentNameForTarget(projectConfig, parsed.target);
+  if (!deploymentName) {
+    throw new Error(
+      `No ${parsed.target} deployment saved for this project. Run \`synapse select\` again.`,
+    );
+  }
+  const credentials = await api.cliCredentials(deploymentName);
+  return {
+    ...parsed,
+    credentials,
+    deploymentName,
+    projectConfig,
+  };
+}
+
+async function runConvexCommand(args, ctx) {
+  const projectConfig = readProjectConfig(ctx.cwd);
+  let resolved;
+  if (projectConfig) {
+    // Need an authenticated session to fetch fresh credentials.
+    const cfg = ctx.cfg;
+    const api = ctx.api;
+    resolved = await resolveConvexInvocation(args, { cfg, api, projectDir: ctx.cwd });
+    ctx.out.info(
+      `Using Synapse ${resolved.target} deployment ${resolved.deploymentName}.`,
+    );
+  } else {
+    resolved = await resolveConvexInvocation(args, { projectDir: ctx.cwd });
+  }
+  const code = await runConvex(resolved.args, { credentials: resolved.credentials });
+  process.exitCode = code;
+}
+
+module.exports = {
+  name: "convex",
+  summary: "Run any `convex` subcommand with Synapse credentials injected.",
+  usage: "synapse convex [--target dev|prod] [...args]",
+  description: `Escape hatch for any \`convex\` invocation that doesn't have a Synapse shortcut. Resolves the right deployment from the linked project, fetches fresh credentials from the backend, scrubs CONVEX_DEPLOYMENT from the child env, and spawns \`npx convex\` with the rest of the args.
+
+Examples:
+  synapse convex --help                     # show convex's help
+  synapse convex run messages:list          # run a function against dev
+  synapse convex --target prod env list     # list prod env vars
+  synapse convex import data.snapshot.gz    # restore a snapshot to dev
+
+By default the target is inferred: \`deploy\` → prod, everything else → dev.`,
+
+  // Exports kept for the legacy test imports.
+  inferConvexTarget,
+  parseConvexInvocation,
+  parseConvexTarget,
+  resolveConvexInvocation,
+  runConvexCommand,
+
+  async run(args, ctx) {
+    return await runConvexCommand(args, ctx);
+  },
+};

package/lib/commands/credentials.js

@@ -0,0 +1,85 @@
+// `synapse credentials <deployment> [--format env|shell|json]` — fetch a
+// deployment's CONVEX_SELF_HOSTED_* pair from the backend and emit it
+// in the requested format. Read-only; doesn't touch any local file.
+//
+// Operators mostly use --format env (pasteable into .env.local) and
+// --format shell (eval-able to export the vars). --format json is for
+// CI scripts that want machine-parseable output.
+
+const { quoteEnvValue } = require("../env-file");
+
+const FORMATS = new Set(["env", "shell", "json"]);
+
+function parseFormat(args) {
+  let format = "env";
+  const rest = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--format") {
+      format = args[i + 1];
+      i += 1;
+    } else if (arg.startsWith("--format=")) {
+      format = arg.slice("--format=".length);
+    } else {
+      rest.push(arg);
+    }
+  }
+  return { format, rest };
+}
+
+function formatCredentials(creds, format) {
+  switch (format) {
+    case "json":
+      return JSON.stringify(creds, null, 2);
+    case "shell":
+      return creds.exportSnippet;
+    case "env":
+      return (
+        creds.envSnippet ||
+        `CONVEX_SELF_HOSTED_URL=${quoteEnvValue(creds.convexUrl)}\nCONVEX_SELF_HOSTED_ADMIN_KEY=${quoteEnvValue(creds.adminKey)}`
+      );
+    default:
+      throw new Error("format must be one of: env, shell, json");
+  }
+}
+
+module.exports = {
+  name: "credentials",
+  summary: "Print a deployment's CONVEX_SELF_HOSTED_* pair in env/shell/json form.",
+  usage: "synapse credentials <deployment> [--format env|shell|json]",
+  description: `Hits /v1/deployments/{name}/cli_credentials and renders the result. No local file is written — pipe the output where you want it.
+
+Formats:
+  env    KEY=value pairs, single-quoted (default; .env.local-ready)
+  shell  export KEY=value pairs (paste into a shell or eval $(...))
+  json   the full response body, including envSnippet/exportSnippet`,
+
+  // Re-exported for legacy test imports; the dispatcher path doesn't
+  // need either helper directly.
+  formatCredentials,
+  parseFormat,
+
+  async run(args, ctx) {
+    const { format, rest } = parseFormat(args);
+    const deployment = rest[0];
+    if (!deployment) {
+      throw new Error("Usage: synapse credentials <deployment> [--format env|shell|json]");
+    }
+    if (!FORMATS.has(format)) {
+      throw new Error("format must be one of: env, shell, json");
+    }
+    const creds = await ctx.api.cliCredentials(deployment);
+    if (format === "json") {
+      // json format already prints the structured response; keep raw
+      // CLI output identical to pre-refactor (stdout, no newline tax).
+      ctx.out.result(creds, (d, { stdout }) =>
+        stdout.write(formatCredentials(d, "json") + "\n"),
+      );
+      return;
+    }
+    // env/shell — emit the snippet verbatim to stdout.
+    ctx.out.result(creds, (d, { stdout }) =>
+      stdout.write(formatCredentials(d, format) + "\n"),
+    );
+  },
+};

package/lib/commands/deploy.js

@@ -0,0 +1,72 @@
+// `synapse deploy [--yes] [args]` — alias for `synapse convex --target
+// prod deploy` with a confirmation gate. Refuses to run in non-TTY
+// contexts unless --yes is passed so a CI script doesn't deadlock on a
+// readline prompt.
+
+const { confirm } = require("../prompts");
+const { deploymentNameForTarget, readProjectConfig } = require("../project");
+const convexCmd = require("./convex");
+
+function extractYesFlag(args) {
+  let yes = false;
+  const rest = [];
+  for (const arg of args) {
+    if (arg === "--yes" || arg === "-y") {
+      yes = true;
+    } else {
+      rest.push(arg);
+    }
+  }
+  return { yes, rest };
+}
+
+// Signature kept at (args, opts) — not (args, ctx, opts) — so the
+// existing test/bin.test.js callers that pass `{ convexImpl, ... }`
+// as the second positional arg keep working. The dispatcher's `run()`
+// below adapts ctx → opts.
+async function deploy(
+  args,
+  {
+    input = process.stdin,
+    output = process.stderr,
+    confirmImpl = confirm,
+    convexImpl,
+    cwd = process.cwd(),
+    ctx,
+  } = {},
+) {
+  const impl = convexImpl ?? ((a) => convexCmd.runConvexCommand(a, ctx));
+  const { yes, rest } = extractYesFlag(args);
+  const projectConfig = readProjectConfig(cwd);
+  const deploymentName = deploymentNameForTarget(projectConfig, "prod");
+  if (deploymentName && !yes) {
+    if (!input.isTTY) {
+      throw new Error(
+        "synapse deploy needs confirmation. Pass --yes to skip in non-interactive contexts (CI, scripts), or run `synapse deploy` again inside a regular terminal.",
+      );
+    }
+    const ok = await confirmImpl(
+      `About to run \`convex deploy\` against PROD deployment ${deploymentName}. Continue? [y/N] `,
+      { input, output, defaultAnswer: false },
+    );
+    if (!ok) {
+      output.write("Deploy cancelled.\n");
+      return;
+    }
+  }
+  return await impl(["--target", "prod", "deploy", ...rest]);
+}
+
+module.exports = {
+  name: "deploy",
+  summary: "Confirm + run `convex deploy` against the linked prod deployment.",
+  usage: "synapse deploy [--yes] [...args]",
+  description: `Sugar for \`synapse convex --target prod deploy [...args]\` with a confirmation prompt. The first deploy of the session asks \`Continue? [y/N]\` — pass \`--yes\` (or \`-y\`) to skip in CI. Refuses in non-TTY contexts without --yes so a hung readline doesn't deadlock pipelines.`,
+
+  deploy,
+  extractYesFlag,
+
+  async run(args, ctx) {
+    return await deploy(args, { cwd: ctx.cwd, ctx });
+  },
+};

package/lib/commands/dev.js

@@ -0,0 +1,24 @@
+// `synapse dev [args]` — thin alias for `synapse convex --target dev dev`.
+// We don't replicate the credentials/spawn pipeline here; just call
+// the convex command with the target hard-coded.
+
+const convexCmd = require("./convex");
+
+// Same (args, opts) signature as deploy — preserves the test seam.
+async function dev(args, { convexImpl, ctx } = {}) {
+  const impl = convexImpl ?? ((a) => convexCmd.runConvexCommand(a, ctx));
+  return await impl(["--target", "dev", "dev", ...args]);
+}
+
+module.exports = {
+  name: "dev",
+  summary: "Run `convex dev` against the linked dev deployment.",
+  usage: "synapse dev [...args]",
+  description: `Sugar for \`synapse convex --target dev dev [...args]\`. Watches and pushes schema/functions to the dev deployment selected by \`synapse select\`. Pass \`--once\` (a convex flag) to run a single push and exit.`,
+
+  dev,
+
+  async run(args, ctx) {
+    return await dev(args, { ctx });
+  },
+};