@iann29/synapse 1.8.6 → 1.8.8

package/lib/commands/deployment-status.js

@@ -0,0 +1,143 @@
+// `synapse deployment status <name> [--watch[=interval]] [--json]`
+//
+// Single-deployment snapshot. Hits GET /v1/deployments/{name}/ +
+// /backend_version (best-effort). `--watch` polls every 2s by default
+// (configurable via --watch=<seconds>) until either:
+//   - the deployment reaches a terminal state (running / failed / deleted)
+//   - the operator hits Ctrl+C
+//   - --json mode is enabled (then we emit ONE snapshot, no polling)
+
+const colors = require("../colors");
+const { extractFlags } = require("./_resource");
+const { SynapseAPIError } = require("../api");
+
+const TERMINAL_STATES = new Set(["running", "failed", "errored", "deleted", "stopped"]);
+
+async function fetchSnapshot(api, name) {
+  const dep = await api.getDeployment(name);
+  let backendVersion = null;
+  // Backend version is only meaningful once the container is running.
+  // We don't await this on every poll if we already saw a transient
+  // 503 — it's not load-bearing for the status check.
+  if (dep.status === "running") {
+    try {
+      const v = await api.getDeploymentBackendVersion(name);
+      backendVersion = v.version || null;
+    } catch {
+      backendVersion = null;
+    }
+  }
+  return { dep, backendVersion };
+}
+
+function renderSnapshot(snap, { stdout }) {
+  const { dep, backendVersion } = snap;
+  const type = (dep.deploymentType || dep.type || "?").toUpperCase();
+  const status = dep.status || "?";
+  stdout.write(
+    `${colors.bold(dep.name)}  ${colors.dim(type)}  ${colors.statusBadge(status)}\n`,
+  );
+  if (dep.deploymentUrl || dep.url) {
+    stdout.write(`  URL: ${dep.deploymentUrl || dep.url}\n`);
+  }
+  if (dep.haEnabled) {
+    stdout.write(
+      `  HA:  enabled${dep.replicaCount ? ` (${dep.replicaCount} replicas)` : ""}\n`,
+    );
+  }
+  if (backendVersion) {
+    stdout.write(colors.dim(`  Convex backend: ${backendVersion}\n`));
+  }
+  if (dep.isDefault) {
+    stdout.write(colors.dim(`  Default for the project.\n`));
+  }
+  if (dep.adopted) {
+    stdout.write(colors.dim(`  Adopted (external — Synapse does not manage credentials).\n`));
+  }
+}
+
+module.exports = {
+  name: "deployment status",
+  summary: "Show a single deployment's status, URL, and HA shape.",
+  usage:
+    "synapse deployment status <name> [--watch[=<seconds>]] [--json]",
+  description: `Fetches GET /v1/deployments/{name} plus a best-effort backend_version probe. --watch polls until the deployment reaches a terminal state (running/failed/deleted/stopped).
+
+Flags:
+  --watch[=<seconds>]  Poll until terminal. Default interval: 2s.
+  --json               One-shot snapshot, no polling.
+
+Examples:
+  synapse deployment status brave-dolphin-1060
+  synapse deployment status fresh-newt-1234 --watch       # tail until ready
+  synapse deployment status brave-dolphin-1060 --json | jq .dep.status`,
+
+  // Re-exports for tests.
+  fetchSnapshot,
+  renderSnapshot,
+  TERMINAL_STATES,
+
+  async run(args, ctx) {
+    const { flags, rest } = extractFlags(args, {
+      // `--watch` alone → true (default interval); `--watch=5` → "5"
+      // (string parsed to number below). Both work because the
+      // boolean branch in extractFlags fires only for the no-`=` form.
+      boolean: ["watch", "json"],
+    });
+    const name = rest[0];
+    if (!name) {
+      throw new Error("Usage: synapse deployment status <name> [--watch]");
+    }
+    if (rest.length > 1) {
+      throw new Error(`Unexpected positional: ${rest[1]}.`);
+    }
+
+    const watch = flags.watch === true || flags.watch === "true"
+      ? 2
+      : typeof flags.watch === "string"
+        ? Math.max(1, Number.parseInt(flags.watch, 10) || 2)
+        : 0;
+
+    // --json + --watch combination doesn't make sense (we'd emit a
+    // never-ending stream of JSON objects). Fail closed.
+    if (ctx.out.json && watch > 0) {
+      throw new Error("--watch is incompatible with --json (would emit an unbounded stream).");
+    }
+
+    let snap;
+    try {
+      snap = await fetchSnapshot(ctx.api, name);
+    } catch (err) {
+      if (err instanceof SynapseAPIError && err.status === 404) {
+        throw new Error(
+          `Deployment "${name}" not found. Run \`synapse list deployments\` to see your deployments.`,
+        );
+      }
+      throw err;
+    }
+
+    if (watch === 0) {
+      ctx.out.result(snap, renderSnapshot);
+      return;
+    }
+
+    // Watch mode (human only — we already barred --json above).
+    renderSnapshot(snap, { stdout: ctx.out.stdout });
+    while (!TERMINAL_STATES.has(snap.dep.status)) {
+      await new Promise((resolve) => setTimeout(resolve, watch * 1000));
+      try {
+        snap = await fetchSnapshot(ctx.api, name);
+      } catch (err) {
+        if (err instanceof SynapseAPIError && err.status === 404) {
+          ctx.out.info(`Deployment "${name}" disappeared mid-watch.`);
+          break;
+        }
+        // Transient errors — log + continue. Operators see one stderr
+        // line per blip; persistent failures escalate via process exit.
+        ctx.out.warn(`probe failed (${err.message}); retrying`);
+        continue;
+      }
+      renderSnapshot(snap, { stdout: ctx.out.stdout });
+    }
+  },
+};

package/lib/commands/env-list.js

@@ -0,0 +1,105 @@
+// `synapse env list [--for=dev|prod|preview] [--project=<id>] [--json]`
+//
+// Lists project-level (default) environment variables. These are
+// injected into the Convex backend container at provision time;
+// changing one only affects deployments that haven't been created yet
+// UNLESS a separate `sync_env_to_deployments` job is triggered (see
+// the dashboard's env panel).
+//
+// The `--for=<type>` filter narrows to vars whose deploymentTypes
+// array includes the type. Omitted = show every var with its type set.
+
+const colors = require("../colors");
+const { extractFlags, resolveProject } = require("./_resource");
+
+const VALID_FORS = new Set(["dev", "prod", "preview"]);
+
+module.exports = {
+  name: "env list",
+  summary: "List project-default environment variables.",
+  usage:
+    "synapse env list [--for=<dev|prod|preview>] [--project=<id>] [--mask] [--json]",
+  description: `Calls GET /v1/projects/{id}/list_default_environment_variables. Default behaviour shows the variable VALUES — pass --mask to redact them (useful when sharing a terminal recording).
+
+Flags:
+  --for=<type>       Filter to vars whose deploymentTypes include <type>.
+  --project=<id>     Override the linked project.
+  --mask             Redact values to "********" (length-preserving).
+  --json             Machine-readable output.
+
+Examples:
+  synapse env list
+  synapse env list --for=prod --mask
+  synapse env list --json | jq '.configs[].name'`,
+
+  async run(args, ctx) {
+    const { flags, rest } = extractFlags(args, {
+      string: ["for", "project"],
+      boolean: ["mask", "json"],
+    });
+    if (rest.length > 0) {
+      throw new Error(`Unexpected positional: ${rest[0]}.`);
+    }
+    const filter = typeof flags.for === "string" ? flags.for.toLowerCase() : null;
+    if (filter && !VALID_FORS.has(filter)) {
+      throw new Error(
+        `Invalid --for: ${filter}. Must be one of: ${[...VALID_FORS].join(", ")}.`,
+      );
+    }
+    const mask = flags.mask === true || flags.mask === "true";
+
+    const resolveArgs = flags.project ? [`--project=${flags.project}`] : [];
+    const { projectId, source } = resolveProject(ctx, resolveArgs);
+
+    const resp = await ctx.api.listProjectEnvVars(projectId);
+    let configs = resp.configs || [];
+    if (filter) {
+      configs = configs.filter(
+        (c) => Array.isArray(c.deploymentTypes) && c.deploymentTypes.includes(filter),
+      );
+    }
+    // Stable order for piping into diff tools.
+    configs.sort((a, b) => a.name.localeCompare(b.name));
+
+    ctx.out.result(
+      {
+        projectId,
+        projectSource: source,
+        count: configs.length,
+        filter,
+        masked: mask,
+        configs: mask
+          ? configs.map((c) => ({ ...c, value: maskValue(c.value) }))
+          : configs,
+      },
+      (_d, { stdout }) => {
+        stdout.write(colors.dim(`Project: ${projectId}${filter ? `  · filter: ${filter}` : ""}\n`));
+        if (configs.length === 0) {
+          stdout.write(colors.dim("(no env vars)\n"));
+          return;
+        }
+        ctx.out.table(
+          configs.map((c) => ({
+            name: colors.bold(c.name),
+            value: mask ? colors.dim(maskValue(c.value)) : c.value,
+            types: (c.deploymentTypes || []).join(",") || colors.dim("(all)"),
+          })),
+          [
+            { key: "name", header: "NAME" },
+            { key: "value", header: "VALUE" },
+            { key: "types", header: "DEPLOYMENT_TYPES" },
+          ],
+        );
+      },
+    );
+  },
+};
+
+// Length-preserving redaction. Operators sometimes screenshot the
+// output to share — a fixed-length blob would leak the length.
+function maskValue(v) {
+  if (v === undefined || v === null || v === "") return "";
+  return "*".repeat(String(v).length);
+}
+
+module.exports.maskValue = maskValue;

package/lib/commands/env-pull.js

@@ -0,0 +1,117 @@
+// `synapse env pull [--out=<path>] [--for=<type>] [--project=<id>] [--json]`
+//
+// Reads project-default env vars + writes them as a .env-shaped file.
+// Output defaults to stdout (so `synapse env pull >> .env.production`
+// works). `--out=<path>` writes to disk with mode 0600.
+//
+// Values are quoted using the same `quoteEnvValue` helper that
+// `.env.local` uses (handles backslashes, double quotes, newlines).
+
+const fs = require("node:fs");
+const colors = require("../colors");
+const { extractFlags, resolveProject } = require("./_resource");
+const { quoteEnvValue } = require("../env-file");
+
+const VALID_FORS = new Set(["dev", "prod", "preview"]);
+
+function formatDotenv(configs, { header = true } = {}) {
+  const lines = [];
+  if (header) {
+    lines.push("# Synapse-managed project-default env vars");
+    lines.push("# Generated by `synapse env pull` — do not edit by hand;");
+    lines.push("# re-run the command after changes upstream.");
+  }
+  for (const c of configs) {
+    lines.push(`${c.name}=${quoteEnvValue(c.value)}`);
+  }
+  return lines.join("\n") + (lines.length > 0 ? "\n" : "");
+}
+
+module.exports = {
+  name: "env pull",
+  summary: "Print or write project-default env vars in .env format.",
+  usage:
+    "synapse env pull [--out=<path>] [--for=<dev|prod|preview>] [--project=<id>] [--json]",
+  description: `Reads the project's default env vars and emits them as KEY="value" lines. Default: writes to stdout. With --out=<path>: writes to that file with mode 0600 (overwrites if exists).
+
+Flags:
+  --out=<path>       Write to a file with mode 0600 instead of stdout.
+  --for=<type>       Filter to vars whose deploymentTypes include <type>.
+  --project=<id>     Override the linked project.
+  --json             Emits { count, body } instead of raw .env text.
+
+Examples:
+  synapse env pull
+  synapse env pull --out=.env.synapse
+  synapse env pull --for=prod > .env.prod`,
+
+  // Re-exports for tests.
+  formatDotenv,
+
+  async run(args, ctx) {
+    const { flags, rest } = extractFlags(args, {
+      string: ["out", "for", "project"],
+      boolean: ["json"],
+    });
+    if (rest.length > 0) {
+      throw new Error(`Unexpected positional: ${rest[0]}.`);
+    }
+    const filter = typeof flags.for === "string" ? flags.for.toLowerCase() : null;
+    if (filter && !VALID_FORS.has(filter)) {
+      throw new Error(
+        `Invalid --for: ${filter}. Must be one of: ${[...VALID_FORS].join(", ")}.`,
+      );
+    }
+    const outPath = typeof flags.out === "string" ? flags.out : null;
+
+    const resolveArgs = flags.project ? [`--project=${flags.project}`] : [];
+    const { projectId, source } = resolveProject(ctx, resolveArgs);
+
+    const resp = await ctx.api.listProjectEnvVars(projectId);
+    let configs = resp.configs || [];
+    if (filter) {
+      configs = configs.filter(
+        (c) => Array.isArray(c.deploymentTypes) && c.deploymentTypes.includes(filter),
+      );
+    }
+    configs.sort((a, b) => a.name.localeCompare(b.name));
+
+    const body = formatDotenv(configs);
+
+    if (outPath) {
+      fs.writeFileSync(outPath, body, { mode: 0o600 });
+      try {
+        fs.chmodSync(outPath, 0o600);
+      } catch {
+        // best-effort on systems without POSIX modes
+      }
+    }
+
+    ctx.out.result(
+      {
+        projectId,
+        projectSource: source,
+        filter,
+        count: configs.length,
+        outPath,
+        body,
+      },
+      (data, { stdout }) => {
+        if (outPath) {
+          ctx.out.info(
+            `Wrote ${data.count} env var${data.count === 1 ? "" : "s"} to ${outPath} (mode 0600).`,
+          );
+          return;
+        }
+        // Plain .env text to stdout — no headers, no colours. The
+        // operator may be piping into another file.
+        stdout.write(body);
+        if (configs.length === 0) {
+          // The body is empty; tell the operator on stderr so they
+          // notice (stdout pipe wouldn't show anything).
+          ctx.out.info(colors.dim(`(no vars matched${filter ? ` --for=${filter}` : ""})`));
+        }
+      },
+    );
+  },
+};

package/lib/commands/env-push.js

@@ -0,0 +1,248 @@
+// `synapse env push [--from=<path>] [--for=<types>] [--project=<id>]
+//                   [--dry-run] [--yes] [--json]`
+//
+// Reads a .env-shaped file and applies it to the project's defaults
+// via op=set on every entry. `--dry-run` prints the diff and exits
+// without calling the backend (RECOMMENDED on first push).
+//
+// Safety:
+//   - Refuses to push CONVEX_SELF_HOSTED_URL / CONVEX_SELF_HOSTED_ADMIN_KEY
+//     (those belong in the operator's local .env.local, not in the
+//     project-default surface that gets injected into containers).
+//   - Refuses to push NEXT_PUBLIC_CONVEX_URL / SITE_URL for the same
+//     reason — they're managed by `synapse select`.
+//   - Without --yes the command shows a diff and prompts.
+
+const fs = require("node:fs");
+const colors = require("../colors");
+const { extractFlags, resolveProject } = require("./_resource");
+const { parseEnvContent } = require("../env-file");
+const { confirm } = require("../prompts");
+
+// Names that MUST NEVER land in the project-default surface. A push
+// that includes any of these is rejected before any backend call.
+const DENY_LIST = new Set([
+  "CONVEX_SELF_HOSTED_URL",
+  "CONVEX_SELF_HOSTED_ADMIN_KEY",
+  "CONVEX_DEPLOYMENT",
+  "NEXT_PUBLIC_CONVEX_URL",
+  "NEXT_PUBLIC_CONVEX_SITE_URL",
+]);
+
+const NAME_RE = /^[A-Z_][A-Z0-9_]*$/;
+const VALID_FORS = new Set(["dev", "prod", "preview"]);
+
+function diffEnv(currentConfigs, parsed) {
+  const current = new Map();
+  for (const c of currentConfigs) current.set(c.name, c.value);
+  const added = [];
+  const changed = [];
+  const unchanged = [];
+  for (const [name, value] of Object.entries(parsed)) {
+    if (!current.has(name)) {
+      added.push({ name, value });
+      continue;
+    }
+    if (current.get(name) !== value) {
+      changed.push({ name, value, from: current.get(name) });
+      continue;
+    }
+    unchanged.push({ name, value });
+  }
+  return { added, changed, unchanged };
+}
+
+module.exports = {
+  name: "env push",
+  summary: "Apply a .env-shaped file to project-default env vars.",
+  usage:
+    "synapse env push [--from=<path>] [--for=<types>] [--project=<id>] [--dry-run] [--yes] [--json]",
+  description: `Reads a .env file and sets each NAME=value as a project-default env var (op=set in batch). Best practice: run with --dry-run FIRST to see what would change.
+
+The file format is the same one \`synapse env pull\` writes. Quoted values, comments, blank lines, and \`export\` prefixes are all tolerated.
+
+The following names are REJECTED with an error (they live in .env.local, not in the project-default surface):
+  CONVEX_SELF_HOSTED_URL, CONVEX_SELF_HOSTED_ADMIN_KEY,
+  CONVEX_DEPLOYMENT, NEXT_PUBLIC_CONVEX_URL, NEXT_PUBLIC_CONVEX_SITE_URL
+
+Flags:
+  --from=<path>      File to read (default: .env in current dir).
+  --for=dev,prod     Stamp the listed deploymentTypes on each var.
+  --project=<id>     Override the linked project.
+  --dry-run          Show the diff and exit; no backend call.
+  --yes              Skip the y/N confirmation prompt.
+  --json             Machine-readable output.
+
+Examples:
+  synapse env push --from=.env.synapse --dry-run
+  synapse env push --from=.env.prod --for=prod --yes`,
+
+  // Re-exports for tests.
+  diffEnv,
+  DENY_LIST,
+
+  async run(args, ctx) {
+    const { flags, rest } = extractFlags(args, {
+      string: ["from", "for", "project"],
+      boolean: ["dry-run", "yes", "json"],
+    });
+    if (rest.length > 0) {
+      throw new Error(`Unexpected positional: ${rest[0]}.`);
+    }
+    const path = typeof flags.from === "string" ? flags.from : ".env";
+    if (!fs.existsSync(path)) {
+      throw new Error(
+        `File not found: ${path}. Pass --from=<path> or create one with \`synapse env pull\`.`,
+      );
+    }
+    const dryRun = flags["dry-run"] === true || flags["dry-run"] === "true";
+    const yes = flags.yes === true || flags.yes === "true";
+
+    // Parse --for. Empty = backend default behaviour (no array sent).
+    let forList = null;
+    if (typeof flags.for === "string" && flags.for.trim() !== "") {
+      forList = [
+        ...new Set(flags.for.split(",").map((s) => s.trim().toLowerCase())),
+      ].filter(Boolean);
+      for (const f of forList) {
+        if (!VALID_FORS.has(f)) {
+          throw new Error(
+            `Invalid --for entry: ${f}. Must be one of: ${[...VALID_FORS].join(", ")}.`,
+          );
+        }
+      }
+    }
+
+    const parsed = parseEnvContent(fs.readFileSync(path, "utf8"));
+    // Reject denied names BEFORE any backend call. Surface ALL of them
+    // so the operator can fix the file once instead of N times.
+    const violations = Object.keys(parsed).filter((n) => DENY_LIST.has(n));
+    if (violations.length > 0) {
+      throw new Error(
+        `Refusing to push: ${violations.join(", ")} are reserved (live in .env.local, not in project-default env). Remove them from ${path} first.`,
+      );
+    }
+    // Validate name shape.
+    for (const name of Object.keys(parsed)) {
+      if (!NAME_RE.test(name)) {
+        throw new Error(
+          `Invalid env name in ${path}: ${JSON.stringify(name)}. Must match [A-Z_][A-Z0-9_]*.`,
+        );
+      }
+    }
+
+    const resolveArgs = flags.project ? [`--project=${flags.project}`] : [];
+    const { projectId, source } = resolveProject(ctx, resolveArgs);
+
+    const current = await ctx.api.listProjectEnvVars(projectId);
+    const diff = diffEnv(current.configs || [], parsed);
+
+    // Dry-run: show diff and exit.
+    if (dryRun) {
+      ctx.out.result(
+        {
+          projectId,
+          projectSource: source,
+          file: path,
+          dryRun: true,
+          ...diff,
+        },
+        (_d, { stdout }) => {
+          stdout.write(colors.dim(`Project: ${projectId}  ·  source: ${path}\n`));
+          if (diff.added.length === 0 && diff.changed.length === 0) {
+            stdout.write(colors.dim("(nothing to do — file matches current state)\n"));
+            return;
+          }
+          for (const a of diff.added) {
+            stdout.write(`${colors.green("+")} ${colors.bold(a.name)}\n`);
+          }
+          for (const c of diff.changed) {
+            stdout.write(`${colors.yellow("~")} ${colors.bold(c.name)}\n`);
+          }
+          if (diff.unchanged.length > 0) {
+            stdout.write(colors.dim(`(${diff.unchanged.length} unchanged)\n`));
+          }
+          stdout.write(colors.dim("\nDry-run — no changes applied. Re-run without --dry-run to push.\n"));
+        },
+      );
+      return;
+    }
+
+    // Real push. Confirm in human mode unless --yes; refuse in
+    // --json mode unless --yes (CI must opt in explicitly).
+    const toApply = diff.added.length + diff.changed.length;
+    if (toApply === 0) {
+      ctx.out.result(
+        {
+          projectId,
+          projectSource: source,
+          file: path,
+          applied: 0,
+          ...diff,
+        },
+        (_d, { stdout }) =>
+          stdout.write(colors.dim("Nothing to push — file matches current state.\n")),
+      );
+      return;
+    }
+    if (!yes && ctx.out.json) {
+      throw new Error(
+        `Refusing to push ${toApply} change${toApply > 1 ? "s" : ""} in --json mode without --yes.`,
+      );
+    }
+    if (!yes && !ctx.out.json) {
+      ctx.out.info(`About to apply ${toApply} change${toApply > 1 ? "s" : ""}:`);
+      for (const a of diff.added) ctx.out.info(`  + ${a.name}`);
+      for (const c of diff.changed) ctx.out.info(`  ~ ${c.name}`);
+      const confirmed = await confirm(
+        `Push to project ${projectId}? [y/N] `,
+        { defaultAnswer: false },
+      );
+      if (!confirmed) {
+        ctx.out.info("Aborted.");
+        process.exitCode = 1;
+        return;
+      }
+    }
+
+    const changes = [];
+    for (const a of diff.added) {
+      changes.push({
+        op: "set",
+        name: a.name,
+        value: a.value,
+        ...(forList ? { deploymentTypes: forList } : {}),
+      });
+    }
+    for (const c of diff.changed) {
+      changes.push({
+        op: "set",
+        name: c.name,
+        value: c.value,
+        ...(forList ? { deploymentTypes: forList } : {}),
+      });
+    }
+    await ctx.api.updateProjectEnvVars(projectId, changes);
+
+    ctx.out.result(
+      {
+        projectId,
+        projectSource: source,
+        file: path,
+        applied: changes.length,
+        ...diff,
+      },
+      (_d, { stdout }) => {
+        for (const a of diff.added) {
+          stdout.write(`${colors.green("+")} ${colors.bold(a.name)}\n`);
+        }
+        for (const c of diff.changed) {
+          stdout.write(`${colors.yellow("~")} ${colors.bold(c.name)}\n`);
+        }
+        if (diff.unchanged.length > 0) {
+          stdout.write(colors.dim(`(${diff.unchanged.length} unchanged)\n`));
+        }
+      },
+    );
+  },
+};