@iann29/synapse 1.8.5 → 1.8.7

package/lib/commands/deployment-rotate-key.js

@@ -0,0 +1,173 @@
+// `synapse deployment rotate-key <name> [--yes] [--confirm=<name>] [--write] [--json]`
+//
+// Calls POST /v1/deployments/{name}/reissue_admin_key. Re-mints the
+// admin_key from the current INSTANCE_SECRET (no container restart).
+//
+// What this does NOT do:
+//   - It does NOT rotate INSTANCE_SECRET (so existing deploy keys keep
+//     working). To actually invalidate a leaked credential you'd need
+//     to recreate the deployment.
+//   - It does NOT auto-update the operator's .env.local. We surface a
+//     --write flag that opt-in does it (using the same writer as
+//     `synapse select`), but the default is "show the key and let the
+//     operator paste it".
+//
+// Safety:
+//   - prod deployments REQUIRE typed-confirm (--confirm=<name>) since
+//     rotating mid-flight breaks the iframed Convex Dashboard until the
+//     operator hits "Refresh credentials".
+//   - dev: `--yes` suffices.
+
+const colors = require("../colors");
+const { extractFlags } = require("./_resource");
+const { confirm, typedConfirm } = require("../prompts");
+const { SynapseAPIError } = require("../api");
+const { writeProjectEnv } = require("../env-file");
+
+module.exports = {
+  name: "deployment rotate-key",
+  summary: "Re-mint a deployment's admin key (cures stale credentials).",
+  usage:
+    "synapse deployment rotate-key <name> [--yes] [--confirm=<name>] [--write] [--json]",
+  description: `Calls POST /v1/deployments/{name}/reissue_admin_key. Used when the stored admin_key drifts out of sync with the running container (symptom: "deployment URL or admin key is invalid" inside the Convex Dashboard iframe).
+
+The deployment's INSTANCE_SECRET is NOT rotated — existing deploy keys keep working. If you need to invalidate a leaked credential, delete + recreate the deployment.
+
+Flags:
+  --yes               Skip the y/N prompt (dev only).
+  --confirm=<name>    Pre-supply the typed confirmation for prod.
+  --write             Also rewrite .env.local in the current directory
+                      IF this is the linked dev deployment.
+  --json              Machine-readable output.
+
+Examples:
+  synapse deployment rotate-key brave-dolphin-1060 --yes
+  synapse deployment rotate-key wise-otter-2200 --confirm=wise-otter-2200 --write`,
+
+  async run(args, ctx) {
+    const { flags, rest } = extractFlags(args, {
+      string: ["confirm"],
+      boolean: ["yes", "write", "json"],
+    });
+    const name = rest[0];
+    if (!name) {
+      throw new Error(
+        "Usage: synapse deployment rotate-key <name> [--yes|--confirm=<name>]",
+      );
+    }
+    if (rest.length > 1) {
+      throw new Error(`Unexpected positional: ${rest[1]}.`);
+    }
+    const yes = flags.yes === true || flags.yes === "true";
+    const write = flags.write === true || flags.write === "true";
+    const typed = typeof flags.confirm === "string" ? flags.confirm : null;
+
+    let dep;
+    try {
+      dep = await ctx.api.getDeployment(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;
+    }
+    const type = dep.deploymentType || dep.type || "unknown";
+
+    // Adopted deployments can't be rotated — backend will 400, but we
+    // catch it earlier with a clearer message.
+    if (dep.adopted) {
+      throw new Error(
+        `Cannot rotate key for "${name}" — it's an adopted (external) deployment. Rotate the admin key on the source side and re-adopt.`,
+      );
+    }
+
+    if (type === "prod") {
+      if (!typed && ctx.out.json) {
+        throw new Error(
+          `Refusing to rotate prod key for "${name}" in --json mode without --confirm=${name}.`,
+        );
+      }
+      const ok = await typedConfirm("rotate-key", name, { typed });
+      if (!ok) {
+        ctx.out.info(`Aborted (confirmation didn't match "${name}").`);
+        process.exitCode = 1;
+        return;
+      }
+    } else {
+      if (!yes && !typed && !ctx.out.json) {
+        const confirmed = await confirm(
+          `Rotate admin key for ${type} deployment ${colors.bold(name)}? [y/N] `,
+          { defaultAnswer: false },
+        );
+        if (!confirmed) {
+          ctx.out.info("Aborted.");
+          process.exitCode = 1;
+          return;
+        }
+      }
+      if (!yes && !typed && ctx.out.json) {
+        throw new Error(
+          `Refusing to rotate "${name}" in --json mode without --yes.`,
+        );
+      }
+    }
+
+    if (!ctx.out.json) {
+      ctx.out.info(`Rotating admin key for ${name}…`);
+    }
+    const res = await ctx.api.reissueAdminKey(name);
+
+    // Optional .env.local rewrite. Only fires when:
+    //   - --write was passed
+    //   - the rotated deployment is the linked dev deployment in CWD
+    //   - we can fetch fresh credentials to wire in the new url+key
+    let envWritten = null;
+    if (write) {
+      const linked = ctx.projectConfig;
+      const matchedDev = linked?.deployments?.dev?.name === name;
+      if (!matchedDev) {
+        if (!ctx.out.json) {
+          ctx.out.warn(
+            "--write skipped: this is not the linked dev deployment in the current directory.",
+          );
+        }
+      } else {
+        const creds = await ctx.api.cliCredentials(name);
+        envWritten = writeProjectEnv(ctx.cwd, creds, {
+          team: { slug: linked.team?.slug, name: linked.team?.name },
+          project: { slug: linked.project?.slug, name: linked.project?.name },
+          target: "dev",
+        });
+      }
+    }
+
+    ctx.out.result(
+      {
+        rotated: true,
+        deploymentName: res.deploymentName || name,
+        prefix: res.prefix,
+        // Full new key. Same exposure profile as `synapse credentials`
+        // — operator already had this on disk before rotation; the
+        // surface is unchanged.
+        adminKey: res.adminKey,
+        envWritten,
+      },
+      (_d, { stdout }) => {
+        stdout.write(
+          `${colors.green("Rotated")} ${colors.bold(name)} ${colors.dim(`(prefix ${res.prefix})`)}\n`,
+        );
+        stdout.write(colors.dim("New admin key (paste into .env.local or pass --write):\n"));
+        stdout.write(res.adminKey + "\n");
+        if (envWritten) {
+          stdout.write(colors.green(`Updated ${envWritten}\n`));
+        } else if (write) {
+          stdout.write(
+            colors.dim("Hint: pass --write only when rotating the linked dev deployment.\n"),
+          );
+        }
+      },
+    );
+  },
+};

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}` : ""})`));
+        }
+      },
+    );
+  },
+};