@iann29/synapse 1.6.17

package/README.md

@@ -0,0 +1,78 @@
+# @iann29/synapse
+
+Thin CLI wrapper for using the official Convex CLI with Synapse-managed
+self-hosted deployments.
+
+The package name is scoped because `synapse` is already taken on npm, but the
+installed binary is still named `synapse`.
+
+## Install
+
+For one machine:
+
+```bash
+npm install -g @iann29/synapse
+synapse --help
+```
+
+For one app/project:
+
+```bash
+npm install -D @iann29/synapse
+npx synapse --help
+```
+
+Without installing into the project first:
+
+```bash
+npm exec --package @iann29/synapse -- synapse --help
+```
+
+Until the package is published to npm, install from a release tarball:
+
+```bash
+npm install -D https://github.com/Iann29/convex-synapse/releases/download/v1.6.2/iann29-synapse-1.6.2.tgz
+npx synapse --help
+```
+
+For local development from this repository:
+
+```bash
+cd /path/to/convex-synapse/cli
+npm link
+
+cd /path/to/your-convex-app
+synapse --help
+```
+
+Or install this checkout into a single app without a global link:
+
+```bash
+cd /path/to/your-convex-app
+npm install -D /path/to/convex-synapse/cli
+npx synapse --help
+```
+
+## Usage
+
+```bash
+synapse login https://synapse.example.com
+synapse select
+synapse convex dev --once
+synapse convex deploy
+```
+
+`synapse select` stores non-secret project metadata in
+`.synapse/project.json`. It also writes `.env.local` with the selected dev
+deployment credentials for compatibility with direct Convex CLI use.
+
+`synapse convex ...` is the safer project-aware path:
+
+- `synapse convex dev` uses the linked dev deployment.
+- `synapse convex deploy` uses the linked prod deployment.
+- `synapse convex --target dev deploy` forces the dev target.
+- Other Convex commands default to dev unless `--target prod` is passed.
+
+At runtime the wrapper fetches fresh deployment credentials from Synapse,
+sets `CONVEX_SELF_HOSTED_URL` and `CONVEX_SELF_HOSTED_ADMIN_KEY`, removes
+`CONVEX_DEPLOYMENT`, and delegates to the official `npx convex ...` command.

package/bin/synapse.js

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+
+const { SynapseAPI, SynapseAPIError } = require("../lib/api");
+const { clearConfig, normalizeBaseUrl, requireConfig, writeConfig } = require("../lib/config");
+const { quoteEnvValue, writeProjectEnv } = require("../lib/env-file");
+const {
+  buildProjectConfig,
+  deploymentNameForTarget,
+  readProjectConfig,
+  writeProjectConfig,
+} = require("../lib/project");
+const { askCredentials, choose } = require("../lib/prompts");
+const { runConvex } = require("../lib/convex");
+
+function usage() {
+  return `Usage:
+  synapse login <url>
+  synapse logout
+  synapse whoami
+  synapse select
+  synapse credentials <deployment> [--format env|shell|json]
+  synapse convex [--target dev|prod] [...args]
+`;
+}
+
+function clientFromConfig() {
+  const cfg = requireConfig();
+  const api = new SynapseAPI({ baseUrl: cfg.baseUrl, accessToken: cfg.accessToken });
+  const refreshable = 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);
+        }
+      };
+    },
+  });
+  return {
+    cfg,
+    api: refreshable,
+  };
+}
+
+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 deploymentLabel(deployment) {
+  const bits = [deployment.name];
+  if (deployment.deploymentType || deployment.type) {
+    bits.push(deployment.deploymentType || deployment.type);
+  }
+  if (deployment.status) {
+    bits.push(deployment.status);
+  }
+  return bits.filter(Boolean).join(" - ");
+}
+
+function deploymentType(deployment) {
+  return deployment.deploymentType || deployment.type || "";
+}
+
+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 || ""));
+  });
+}
+
+async function chooseDeploymentForType(type, deployments) {
+  const matches = sortDeploymentsForChoice(
+    deployments.filter((d) => deploymentType(d) === type && d.status !== "deleted"),
+  );
+  if (matches.length === 0) {
+    return null;
+  }
+  return await choose(
+    `${type} deployments`,
+    matches.map((d) => ({ label: deploymentLabel(d), value: d })),
+  );
+}
+
+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,
+  };
+}
+
+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");
+  }
+}
+
+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 };
+}
+
+async function login(args) {
+  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,
+  });
+  process.stderr.write(`Saved Synapse session to ${file}\n`);
+}
+
+async function logout() {
+  const removed = clearConfig();
+  process.stderr.write(removed ? "Logged out of Synapse.\n" : "No Synapse session was saved.\n");
+}
+
+async function whoami() {
+  const { cfg, api } = clientFromConfig();
+  const me = await api.me();
+  const email = me.email || me.user?.email || "(unknown email)";
+  const name = me.name || me.user?.name || "";
+  process.stdout.write(`${name ? `${name} ` : ""}<${email}> on ${cfg.baseUrl}\n`);
+}
+
+async function selectDeployment() {
+  const { cfg, api } = clientFromConfig();
+  const teams = await api.teams();
+  const team = await choose("teams", teams.map((t) => ({ label: labelName(t), value: t })));
+  const projects = await api.projects(teamRef(team));
+  const project = await choose("projects", projects.map((p) => ({ label: labelName(p), value: p })));
+  const deployments = await api.deployments(project.id);
+  const dev = await chooseDeploymentForType("dev", deployments);
+  if (!dev) {
+    throw new Error("No dev deployments available in this project. Create one first.");
+  }
+  const prod = await chooseDeploymentForType("prod", deployments);
+  const projectPath = writeProjectConfig(
+    process.cwd(),
+    buildProjectConfig({
+      synapseUrl: cfg.baseUrl,
+      team,
+      project,
+      deployments: { dev, prod },
+    }),
+  );
+  const creds = await api.cliCredentials(dev.name);
+  const envPath = writeProjectEnv(process.cwd(), creds);
+  process.stderr.write(`Linked ${labelName(project)} to ${projectPath}.\n`);
+  process.stderr.write(`Selected dev deployment ${dev.name}. Updated ${envPath}.\n`);
+  if (prod) {
+    process.stderr.write(`Selected prod deployment ${prod.name}.\n`);
+  } else {
+    process.stderr.write("Warning: no prod deployment found. `synapse convex deploy` will require a prod deployment saved by `synapse select`.\n");
+  }
+  if (process.env.CONVEX_DEPLOYMENT) {
+    process.stderr.write("Warning: shell CONVEX_DEPLOYMENT is set. Use `synapse convex ...` or unset it before running `npx convex` directly.\n");
+  }
+}
+
+async function credentials(args) {
+  const { format, rest } = parseFormat(args);
+  const deployment = rest[0];
+  if (!deployment) {
+    throw new Error("Usage: synapse credentials <deployment> [--format env|shell|json]");
+  }
+  if (!["env", "shell", "json"].includes(format)) {
+    throw new Error("format must be one of: env, shell, json");
+  }
+  const { api } = clientFromConfig();
+  const creds = await api.cliCredentials(deployment);
+  process.stdout.write(formatCredentials(creds, format) + "\n");
+}
+
+async function convex(args) {
+  const projectConfig = readProjectConfig(process.cwd());
+  let resolved = {
+    args,
+    credentials: null,
+    deploymentName: "",
+    target: null,
+  };
+  if (projectConfig) {
+    const { cfg, api } = clientFromConfig();
+    resolved = await resolveConvexInvocation(args, { cfg, api });
+    process.stderr.write(`Using Synapse ${resolved.target} deployment ${resolved.deploymentName}.\n`);
+  } else {
+    resolved = await resolveConvexInvocation(args);
+  }
+  const code = await runConvex(resolved.args, { credentials: resolved.credentials });
+  process.exitCode = code;
+}
+
+async function main(argv) {
+  const [command, ...args] = argv;
+  switch (command) {
+    case "login":
+      return await login(args);
+    case "logout":
+      return await logout();
+    case "whoami":
+      return await whoami();
+    case "select":
+      return await selectDeployment();
+    case "credentials":
+      return await credentials(args);
+    case "convex":
+      return await convex(args);
+    case "-h":
+    case "--help":
+    case "help":
+    case undefined:
+      process.stdout.write(usage());
+      return;
+    default:
+      throw new Error(`Unknown command: ${command}\n\n${usage()}`);
+  }
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).catch((err) => {
+    process.stderr.write(`${err.message}\n`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  chooseDeploymentForType,
+  clientFromConfig,
+  formatCredentials,
+  inferConvexTarget,
+  main,
+  parseConvexInvocation,
+  parseFormat,
+  resolveConvexInvocation,
+};

package/lib/api.js

@@ -0,0 +1,119 @@
+class SynapseAPIError extends Error {
+  constructor(status, code, message) {
+    super(message || code || `Synapse API returned ${status}`);
+    this.name = "SynapseAPIError";
+    this.status = status;
+    this.code = code || "request_failed";
+  }
+}
+
+class SynapseAPI {
+  constructor({ baseUrl, accessToken, fetchImpl = globalThis.fetch }) {
+    if (!fetchImpl) {
+      throw new Error("This Node version does not provide fetch()");
+    }
+    this.baseUrl = String(baseUrl || "").replace(/\/+$/, "");
+    this.accessToken = accessToken || "";
+    this.fetch = fetchImpl;
+  }
+
+  async request(method, path, body, { auth = true, includeHeaders = false } = {}) {
+    const url = new URL(path, `${this.baseUrl}/`);
+    const headers = {
+      "Accept": "application/json",
+    };
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+    }
+    if (auth && this.accessToken) {
+      headers.Authorization = `Bearer ${this.accessToken}`;
+    }
+    let res;
+    try {
+      res = await this.fetch(url, {
+        method,
+        headers,
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      });
+    } catch (err) {
+      const detail = err && err.message ? err.message : String(err);
+      throw new SynapseAPIError(0, "network_error", `Could not reach Synapse at ${this.baseUrl}: ${detail}`);
+    }
+    if (!res.ok) {
+      let code = "request_failed";
+      let message = `${method} ${url.pathname} failed with ${res.status}`;
+      try {
+        const data = await res.json();
+        code = data.code || data.error || code;
+        message = data.message || data.error || message;
+      } catch {
+        // Keep the generic message if the server didn't return JSON.
+      }
+      throw new SynapseAPIError(res.status, code, message);
+    }
+    let data = null;
+    if (res.status !== 204) {
+      try {
+        data = await res.json();
+      } catch {
+        throw new SynapseAPIError(res.status, "bad_response", `${method} ${url.pathname} did not return JSON`);
+      }
+    }
+    if (includeHeaders) {
+      return { data, headers: res.headers };
+    }
+    return data;
+  }
+
+  async listAll(path) {
+    const items = [];
+    let cursor = "";
+    do {
+      const pageURL = new URL(path, "http://synapse.local");
+      pageURL.searchParams.set("limit", "500");
+      if (cursor) {
+        pageURL.searchParams.set("cursor", cursor);
+      }
+      const page = await this.request("GET", `${pageURL.pathname}${pageURL.search}`, undefined, { includeHeaders: true });
+      if (!Array.isArray(page.data)) {
+        throw new SynapseAPIError(0, "bad_response", `Expected ${path} to return a JSON array`);
+      }
+      items.push(...page.data);
+      cursor = page.headers.get("x-next-cursor") || "";
+    } while (cursor);
+    return items;
+  }
+
+  login(email, password) {
+    return this.request("POST", "/v1/auth/login", { email, password }, { auth: false });
+  }
+
+  refresh(refreshToken) {
+    return this.request("POST", "/v1/auth/refresh", { refreshToken }, { auth: false });
+  }
+
+  me() {
+    return this.request("GET", "/v1/me/");
+  }
+
+  teams() {
+    return this.listAll("/v1/teams/");
+  }
+
+  projects(teamRef) {
+    return this.listAll(`/v1/teams/${encodeURIComponent(teamRef)}/list_projects`);
+  }
+
+  deployments(projectId) {
+    return this.listAll(`/v1/projects/${encodeURIComponent(projectId)}/list_deployments`);
+  }
+
+  cliCredentials(deploymentName) {
+    return this.request("GET", `/v1/deployments/${encodeURIComponent(deploymentName)}/cli_credentials`);
+  }
+}
+
+module.exports = {
+  SynapseAPI,
+  SynapseAPIError,
+};

package/lib/config.js

@@ -0,0 +1,87 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+function configPath() {
+  if (process.env.SYNAPSE_CLI_CONFIG) {
+    return process.env.SYNAPSE_CLI_CONFIG;
+  }
+  return path.join(os.homedir(), ".synapse", "config.json");
+}
+
+function normalizeBaseUrl(raw) {
+  const value = String(raw || "").trim();
+  if (!value) {
+    throw new Error("Synapse URL is required");
+  }
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(`Invalid Synapse URL: ${value}`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("Synapse URL must start with http:// or https://");
+  }
+  parsed.hash = "";
+  parsed.search = "";
+  parsed.pathname = parsed.pathname.replace(/\/+$/, "");
+  return parsed.toString().replace(/\/+$/, "");
+}
+
+function readConfig() {
+  const file = configPath();
+  if (!fs.existsSync(file)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (err) {
+    throw new Error(`Could not read ${file}: ${err.message}`);
+  }
+}
+
+function requireConfig() {
+  const cfg = readConfig();
+  if (!cfg || !cfg.baseUrl || !cfg.accessToken) {
+    throw new Error("Not logged in. Run `synapse login <url>` first.");
+  }
+  return cfg;
+}
+
+function writeConfig(config) {
+  const file = configPath();
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try {
+    fs.chmodSync(dir, 0o700);
+  } catch {
+    // Best-effort on filesystems that do not support POSIX modes.
+  }
+  const payload = JSON.stringify(config, null, 2) + "\n";
+  fs.writeFileSync(file, payload, { mode: 0o600 });
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    // Best-effort on filesystems that do not support POSIX modes.
+  }
+  return file;
+}
+
+function clearConfig() {
+  const file = configPath();
+  if (fs.existsSync(file)) {
+    fs.rmSync(file);
+    return true;
+  }
+  return false;
+}
+
+module.exports = {
+  clearConfig,
+  configPath,
+  normalizeBaseUrl,
+  readConfig,
+  requireConfig,
+  writeConfig,
+};

package/lib/convex.js

@@ -0,0 +1,56 @@
+const { spawn } = require("node:child_process");
+const { readProjectEnv } = require("./env-file");
+
+function envFromCredentials(credentials) {
+  if (!credentials) {
+    return {};
+  }
+  return {
+    CONVEX_SELF_HOSTED_URL: credentials.convexUrl,
+    CONVEX_SELF_HOSTED_ADMIN_KEY: credentials.adminKey,
+  };
+}
+
+function buildConvexEnv(source = process.env, projectEnv = {}, overrides = {}) {
+  const env = { ...source };
+  for (const key of ["CONVEX_SELF_HOSTED_URL", "CONVEX_SELF_HOSTED_ADMIN_KEY"]) {
+    if (!env[key] && projectEnv[key]) {
+      env[key] = projectEnv[key];
+    }
+  }
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value) {
+      env[key] = value;
+    }
+  }
+  if (env.CONVEX_SELF_HOSTED_URL && env.CONVEX_SELF_HOSTED_ADMIN_KEY) {
+    delete env.CONVEX_DEPLOYMENT;
+  }
+  return env;
+}
+
+function runConvex(args, { env = process.env, stdio = "inherit", credentials = null, spawnImpl = spawn } = {}) {
+  const executable = process.platform === "win32" ? "npx.cmd" : "npx";
+  const projectEnv = readProjectEnv(process.cwd());
+  const child = spawnImpl(executable, ["convex", ...args], {
+    env: buildConvexEnv(env, projectEnv, envFromCredentials(credentials)),
+    stdio,
+  });
+
+  return new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code, signal) => {
+      if (signal) {
+        resolve(1);
+        return;
+      }
+      resolve(code ?? 1);
+    });
+  });
+}
+
+module.exports = {
+  buildConvexEnv,
+  envFromCredentials,
+  runConvex,
+};

package/lib/env-file.js

@@ -0,0 +1,133 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const SELF_HOSTED_URL = "CONVEX_SELF_HOSTED_URL";
+const SELF_HOSTED_ADMIN_KEY = "CONVEX_SELF_HOSTED_ADMIN_KEY";
+const CONVEX_DEPLOYMENT = "CONVEX_DEPLOYMENT";
+
+function quoteEnvValue(value) {
+  return `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n")}"`;
+}
+
+function envAssignment(name, value) {
+  return `${name}=${quoteEnvValue(value)}`;
+}
+
+function keyFromLine(line) {
+  const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+  return match ? match[1] : null;
+}
+
+function commentDeploymentLine(line) {
+  if (/^\s*#/.test(line)) {
+    return line;
+  }
+  return `# ${line} # disabled by synapse CLI for self-hosted Convex`;
+}
+
+function unquoteEnvValue(raw) {
+  const value = String(raw || "").trim();
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function parseEnvContent(content) {
+  const out = {};
+  for (const line of String(content || "").split(/\r?\n/)) {
+    if (/^\s*(?:#|$)/.test(line)) {
+      continue;
+    }
+    const key = keyFromLine(line);
+    if (!key) {
+      continue;
+    }
+    const valueStart = line.indexOf("=");
+    if (valueStart < 0) {
+      continue;
+    }
+    out[key] = unquoteEnvValue(line.slice(valueStart + 1));
+  }
+  return out;
+}
+
+function readProjectEnv(projectDir) {
+  const file = path.join(projectDir, ".env.local");
+  if (!fs.existsSync(file)) {
+    return {};
+  }
+  return parseEnvContent(fs.readFileSync(file, "utf8"));
+}
+
+function updateEnvContent(content, { convexUrl, adminKey }) {
+  const lines = content ? content.split(/\r?\n/) : [];
+  if (lines.length > 0 && lines[lines.length - 1] === "") {
+    lines.pop();
+  }
+
+  const replacements = new Map([
+    [SELF_HOSTED_URL, envAssignment(SELF_HOSTED_URL, convexUrl)],
+    [SELF_HOSTED_ADMIN_KEY, envAssignment(SELF_HOSTED_ADMIN_KEY, adminKey)],
+  ]);
+  const seen = new Set();
+  const out = [];
+
+  for (const line of lines) {
+    const key = keyFromLine(line);
+    if (key === CONVEX_DEPLOYMENT) {
+      out.push(commentDeploymentLine(line));
+      continue;
+    }
+    if (replacements.has(key)) {
+      if (!seen.has(key)) {
+        out.push(replacements.get(key));
+        seen.add(key);
+      }
+      continue;
+    }
+    out.push(line);
+  }
+
+  if (out.length > 0 && out[out.length - 1] !== "") {
+    out.push("");
+  }
+  for (const [key, line] of replacements.entries()) {
+    if (!seen.has(key)) {
+      out.push(line);
+    }
+  }
+
+  return out.join("\n") + "\n";
+}
+
+function writeProjectEnv(projectDir, credentials) {
+  const file = path.join(projectDir, ".env.local");
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const next = updateEnvContent(existing, {
+    convexUrl: credentials.convexUrl,
+    adminKey: credentials.adminKey,
+  });
+  fs.writeFileSync(file, next, { mode: 0o600 });
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    // Best-effort on filesystems that do not support POSIX modes.
+  }
+  return file;
+}
+
+module.exports = {
+  CONVEX_DEPLOYMENT,
+  SELF_HOSTED_ADMIN_KEY,
+  SELF_HOSTED_URL,
+  keyFromLine,
+  parseEnvContent,
+  quoteEnvValue,
+  readProjectEnv,
+  updateEnvContent,
+  writeProjectEnv,
+};

package/lib/project.js

@@ -0,0 +1,113 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const PROJECT_DIR = ".synapse";
+const PROJECT_FILE = "project.json";
+
+function projectConfigPath(projectDir = process.cwd()) {
+  return path.join(projectDir, PROJECT_DIR, PROJECT_FILE);
+}
+
+function compactObject(value) {
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (item !== undefined && item !== null && item !== "") {
+      out[key] = item;
+    }
+  }
+  return out;
+}
+
+function entityRef(entity) {
+  if (!entity) {
+    return undefined;
+  }
+  return compactObject({
+    id: entity.id,
+    slug: entity.slug,
+    name: entity.name,
+  });
+}
+
+function deploymentRef(deployment) {
+  if (!deployment) {
+    return undefined;
+  }
+  return compactObject({
+    id: deployment.id,
+    name: deployment.name,
+    deploymentType: deployment.deploymentType || deployment.type,
+    isDefault: deployment.isDefault,
+    status: deployment.status,
+  });
+}
+
+function sanitizeProjectConfig(input) {
+  const deployments = {};
+  if (input.deployments?.dev) {
+    deployments.dev = deploymentRef(input.deployments.dev);
+  }
+  if (input.deployments?.prod) {
+    deployments.prod = deploymentRef(input.deployments.prod);
+  }
+  return compactObject({
+    version: 1,
+    synapseUrl: input.synapseUrl,
+    team: entityRef(input.team),
+    project: entityRef(input.project),
+    deployments,
+  });
+}
+
+function buildProjectConfig({ synapseUrl, team, project, deployments }) {
+  return sanitizeProjectConfig({
+    synapseUrl,
+    team,
+    project,
+    deployments,
+  });
+}
+
+function writeProjectConfig(projectDir, config) {
+  const file = projectConfigPath(projectDir);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const safe = sanitizeProjectConfig(config);
+  fs.writeFileSync(file, JSON.stringify(safe, null, 2) + "\n", { mode: 0o600 });
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    // Best-effort on filesystems that do not support POSIX modes.
+  }
+  return file;
+}
+
+function readProjectConfig(projectDir = process.cwd()) {
+  const file = projectConfigPath(projectDir);
+  if (!fs.existsSync(file)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (err) {
+    throw new Error(`Could not read ${file}: ${err.message}`);
+  }
+}
+
+function deploymentNameForTarget(config, target) {
+  const deployment = config?.deployments?.[target];
+  if (!deployment) {
+    return "";
+  }
+  return typeof deployment === "string" ? deployment : deployment.name || "";
+}
+
+module.exports = {
+  PROJECT_DIR,
+  PROJECT_FILE,
+  buildProjectConfig,
+  deploymentNameForTarget,
+  projectConfigPath,
+  readProjectConfig,
+  sanitizeProjectConfig,
+  writeProjectConfig,
+};

package/lib/prompts.js

@@ -0,0 +1,122 @@
+const readline = require("node:readline");
+
+function ask(question, { input = process.stdin, output = process.stderr } = {}) {
+  const rl = readline.createInterface({ input, output });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function askHidden(question, { input = process.stdin, output = process.stderr } = {}) {
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== "function") {
+    return ask(question, { input, output });
+  }
+
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const wasRaw = input.isRaw;
+
+    function cleanup() {
+      input.off("data", onData);
+      input.setRawMode(wasRaw);
+      output.write("\n");
+    }
+
+    function onData(buffer) {
+      const text = buffer.toString("utf8");
+      for (const ch of text) {
+        if (ch === "\u0003") {
+          cleanup();
+          reject(new Error("Cancelled"));
+          return;
+        }
+        if (ch === "\r" || ch === "\n") {
+          cleanup();
+          resolve(value);
+          return;
+        }
+        if (ch === "\u007f" || ch === "\b") {
+          value = value.slice(0, -1);
+          continue;
+        }
+        if (ch >= " ") {
+          value += ch;
+        }
+      }
+    }
+
+    output.write(question);
+    input.setRawMode(true);
+    input.resume();
+    input.on("data", onData);
+  });
+}
+
+function parseCredentialsInput(text) {
+  const lines = String(text || "").split(/\r?\n/);
+  return {
+    email: (lines[0] || "").trim(),
+    password: lines[1] || "",
+  };
+}
+
+function readAll(input) {
+  return new Promise((resolve, reject) => {
+    let text = "";
+    input.setEncoding("utf8");
+    input.on("data", (chunk) => {
+      text += chunk;
+    });
+    input.on("error", reject);
+    input.on("end", () => resolve(text));
+  });
+}
+
+async function askCredentials({ input = process.stdin, output = process.stderr } = {}) {
+  if (!input.isTTY) {
+    const parsed = parseCredentialsInput(await readAll(input));
+    if (!parsed.email || !parsed.password) {
+      throw new Error("Non-interactive login expects email and password on stdin, one per line.");
+    }
+    return parsed;
+  }
+  return {
+    email: await ask("Email: ", { input, output }),
+    password: await askHidden("Password: ", { input, output }),
+  };
+}
+
+async function choose(label, choices, { input = process.stdin, output = process.stderr } = {}) {
+  if (!Array.isArray(choices) || choices.length === 0) {
+    throw new Error(`No ${label} available.`);
+  }
+  if (choices.length === 1) {
+    output.write(`Using ${label}: ${choices[0].label}\n`);
+    return choices[0].value;
+  }
+
+  output.write(`${label}:\n`);
+  choices.forEach((choice, index) => {
+    output.write(`  ${index + 1}. ${choice.label}\n`);
+  });
+
+  while (true) {
+    const answer = await ask(`Choose ${label} [1-${choices.length}]: `, { input, output });
+    const n = Number.parseInt(answer, 10);
+    if (Number.isInteger(n) && n >= 1 && n <= choices.length) {
+      return choices[n - 1].value;
+    }
+    output.write(`Enter a number from 1 to ${choices.length}.\n`);
+  }
+}
+
+module.exports = {
+  ask,
+  askCredentials,
+  askHidden,
+  choose,
+  parseCredentialsInput,
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@iann29/synapse",
+  "version": "1.6.17",
+  "description": "Thin CLI wrapper for using the official Convex CLI with Synapse-managed deployments.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Iann29/convex-synapse.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/Iann29/convex-synapse/issues"
+  },
+  "homepage": "https://github.com/Iann29/convex-synapse#readme",
+  "keywords": [
+    "convex",
+    "synapse",
+    "convex-synapse",
+    "self-hosted",
+    "cli"
+  ],
+  "bin": {
+    "synapse": "bin/synapse.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}