@iann29/synapse 1.8.5 → 1.8.7

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

package/lib/commands/env-set.js

@@ -0,0 +1,129 @@
+// `synapse env set NAME=value [NAME2=value2 ...] [--for=dev,prod] [--project=<id>] [--json]`
+//
+// Batch-sets project-default env vars. Multiple positionals = single
+// transactional update on the backend (the handler wraps the whole
+// `changes` array in a BEGIN/COMMIT). If any value is rejected the
+// whole batch rolls back.
+//
+// Value parsing: split on the FIRST `=`. So `FOO=a=b` sets FOO to "a=b".
+// Names must match /^[A-Z_][A-Z0-9_]*$/ — same shape the Convex backend
+// accepts (uppercase letters, digits, underscore; leading non-digit).
+
+const colors = require("../colors");
+const { extractFlags, resolveProject } = require("./_resource");
+
+const NAME_RE = /^[A-Z_][A-Z0-9_]*$/;
+const VALID_FORS = new Set(["dev", "prod", "preview"]);
+
+// Splits `NAME=value` on the FIRST `=`. Returns { name, value } or
+// throws when the shape is wrong. Empty value is OK ("FOO=" sets to "").
+function parsePair(arg) {
+  const eq = arg.indexOf("=");
+  if (eq <= 0) {
+    throw new Error(
+      `Invalid env assignment: ${JSON.stringify(arg)}. Expected NAME=value.`,
+    );
+  }
+  const name = arg.slice(0, eq);
+  const value = arg.slice(eq + 1);
+  if (!NAME_RE.test(name)) {
+    throw new Error(
+      `Invalid env name: ${JSON.stringify(name)}. Names must match [A-Z_][A-Z0-9_]*.`,
+    );
+  }
+  return { name, value };
+}
+
+// Comma-split + trim + dedupe a `--for=dev,prod` argument. Empty
+// returns null (= "use default"). Errors on unknown types.
+function parseFor(raw) {
+  if (raw === undefined || raw === null || raw === true) return null;
+  const trimmed = String(raw).trim();
+  if (trimmed === "") return null;
+  const parts = [
+    ...new Set(trimmed.split(",").map((s) => s.trim().toLowerCase())),
+  ].filter(Boolean);
+  for (const p of parts) {
+    if (!VALID_FORS.has(p)) {
+      throw new Error(
+        `Invalid --for entry: ${p}. Must be one of: ${[...VALID_FORS].join(", ")}.`,
+      );
+    }
+  }
+  return parts;
+}
+
+module.exports = {
+  name: "env set",
+  summary: "Set one or more project-default environment variables.",
+  usage:
+    "synapse env set NAME=value [NAME2=value2 ...] [--for=dev,prod] [--project=<id>] [--json]",
+  description: `Calls POST /v1/projects/{id}/update_default_environment_variables with op=set. Multiple pairs are applied in a single transaction. Names follow the [A-Z_][A-Z0-9_]* convention; values are byte-preserved (whitespace, quotes, '=' all OK).
+
+Flags:
+  --for=dev,prod     Limit the var to specific deploymentTypes
+                     (comma-separated). Omitted: backend defaults
+                     (typically: all types).
+  --project=<id>     Override the linked project.
+  --json             Machine-readable output.
+
+Examples:
+  synapse env set OPENAI_API_KEY=sk-abc...
+  synapse env set FOO=bar BAZ=qux --for=prod
+  synapse env set REDIS_URL='rediss://user:pass@host:6379/0'`,
+
+  // Re-exports for tests.
+  parsePair,
+  parseFor,
+  NAME_RE,
+
+  async run(args, ctx) {
+    const { flags, rest } = extractFlags(args, {
+      string: ["for", "project"],
+      boolean: ["json"],
+    });
+    if (rest.length === 0) {
+      throw new Error(
+        "Usage: synapse env set NAME=value [NAME2=value2 ...] [--for=...]",
+      );
+    }
+    const forList = parseFor(flags.for);
+    const pairs = rest.map(parsePair);
+
+    const resolveArgs = flags.project ? [`--project=${flags.project}`] : [];
+    const { projectId, source } = resolveProject(ctx, resolveArgs);
+
+    const changes = pairs.map(({ name, value }) => ({
+      op: "set",
+      name,
+      value,
+      ...(forList ? { deploymentTypes: forList } : {}),
+    }));
+
+    if (!ctx.out.json) {
+      ctx.out.info(
+        `Setting ${pairs.length} env var${pairs.length > 1 ? "s" : ""} on project ${projectId}${forList ? ` (for: ${forList.join(",")})` : ""}…`,
+      );
+    }
+    await ctx.api.updateProjectEnvVars(projectId, changes);
+
+    ctx.out.result(
+      {
+        projectId,
+        projectSource: source,
+        applied: changes.length,
+        changes: changes.map((c) => ({ name: c.name, deploymentTypes: c.deploymentTypes ?? null })),
+      },
+      (_d, { stdout }) => {
+        for (const { name } of pairs) {
+          stdout.write(`${colors.green("+")} ${colors.bold(name)}\n`);
+        }
+        stdout.write(
+          colors.dim(
+            "These defaults are injected into NEW deployments. To apply to existing deployments, run `synapse convex env set` per deployment, or re-create them.\n",
+          ),
+        );
+      },
+    );
+  },
+};

package/lib/commands/env-unset.js

@@ -0,0 +1,77 @@
+// `synapse env unset NAME [NAME2 ...] [--project=<id>] [--json]`
+//
+// Batch-deletes project-default env vars. Sends op=delete for each
+// name in a single transactional update. Unknown names are not an
+// error server-side (the DELETE is idempotent), but we surface a
+// warning when ALL passed names were unknown — usually a typo.
+
+const colors = require("../colors");
+const { extractFlags, resolveProject } = require("./_resource");
+
+const NAME_RE = /^[A-Z_][A-Z0-9_]*$/;
+
+module.exports = {
+  name: "env unset",
+  summary: "Delete one or more project-default environment variables.",
+  usage: "synapse env unset NAME [NAME2 ...] [--project=<id>] [--json]",
+  description: `Calls POST /v1/projects/{id}/update_default_environment_variables with op=delete. Idempotent — deleting a name that doesn't exist is silent.
+
+Flags:
+  --project=<id>     Override the linked project.
+  --json             Machine-readable output.
+
+Examples:
+  synapse env unset OLD_API_KEY
+  synapse env unset FOO BAR BAZ`,
+
+  async run(args, ctx) {
+    const { flags, rest } = extractFlags(args, {
+      string: ["project"],
+      boolean: ["json"],
+    });
+    if (rest.length === 0) {
+      throw new Error("Usage: synapse env unset NAME [NAME2 ...]");
+    }
+    for (const name of rest) {
+      if (!NAME_RE.test(name)) {
+        throw new Error(
+          `Invalid env name: ${JSON.stringify(name)}. Names must match [A-Z_][A-Z0-9_]*.`,
+        );
+      }
+    }
+
+    const resolveArgs = flags.project ? [`--project=${flags.project}`] : [];
+    const { projectId, source } = resolveProject(ctx, resolveArgs);
+
+    // We could pre-fetch the existing var list to warn about unknown
+    // names. Skipping: an extra GET on every unset doubles latency for
+    // the common case where the operator typed the right name. The
+    // backend's op=delete is idempotent.
+    const changes = rest.map((name) => ({ op: "delete", name }));
+    if (!ctx.out.json) {
+      ctx.out.info(
+        `Unsetting ${rest.length} env var${rest.length > 1 ? "s" : ""} on project ${projectId}…`,
+      );
+    }
+    await ctx.api.updateProjectEnvVars(projectId, changes);
+
+    ctx.out.result(
+      {
+        projectId,
+        projectSource: source,
+        deleted: rest.length,
+        names: rest,
+      },
+      (_d, { stdout }) => {
+        for (const name of rest) {
+          stdout.write(`${colors.red("-")} ${colors.bold(name)}\n`);
+        }
+        stdout.write(
+          colors.dim(
+            "Existing deployments keep their cached value until they're recreated.\n",
+          ),
+        );
+      },
+    );
+  },
+};

package/lib/commands/list.js

@@ -0,0 +1,186 @@
+// `synapse list [deployments|projects|teams]` — read-only catalog
+// dumper. Single-arg subcommand that mirrors what you'd see in the
+// dashboard, but scriptable (every subcommand supports --json).
+//
+// Resolution rules:
+//   - `list teams`        → no flag needed (always lists the operator's teams)
+//   - `list projects`     → uses linked team OR --team=<slug|id>
+//   - `list deployments`  → uses linked project OR --project=<id>
+
+const colors = require("../colors");
+const { extractTeamFlag, extractProjectFlag } = require("./_resource");
+
+const KINDS = ["deployments", "projects", "teams"];
+
+async function listTeams(ctx) {
+  const teams = await ctx.api.teams();
+  ctx.out.result(
+    { kind: "teams", count: teams.length, teams },
+    (_d, { stdout }) => {
+      if (teams.length === 0) {
+        stdout.write(colors.dim("(no teams — create one in the dashboard)\n"));
+        return;
+      }
+      ctx.out.table(
+        teams.map((t) => ({
+          name: colors.bold(t.name || t.slug || t.id),
+          slug: t.slug || colors.dim("?"),
+          id: colors.dim(t.id),
+        })),
+        [
+          { key: "name", header: "NAME" },
+          { key: "slug", header: "SLUG" },
+          { key: "id", header: "ID" },
+        ],
+      );
+    },
+  );
+}
+
+async function listProjects(ctx, args) {
+  const { teamRef: explicit, rest } = extractTeamFlag(args);
+  if (rest.length > 0) {
+    throw new Error(
+      `Unexpected positional: ${rest[0]}. Usage: synapse list projects [--team=<slug|id>]`,
+    );
+  }
+  // Linked-project fallback uses ctx.projectConfig.team.slug.
+  let teamRef = explicit;
+  let source = "flag";
+  if (!teamRef) {
+    const linked = ctx.projectConfig;
+    if (linked && linked.team && (linked.team.slug || linked.team.id)) {
+      teamRef = linked.team.slug || linked.team.id;
+      source = "linked";
+    }
+  }
+  if (!teamRef) {
+    throw new Error(
+      "No linked team. Pass --team=<slug|id> or run `synapse select` first.",
+    );
+  }
+  const projects = await ctx.api.projects(teamRef);
+  ctx.out.result(
+    { kind: "projects", team: teamRef, teamSource: source, count: projects.length, projects },
+    (_d, { stdout }) => {
+      stdout.write(colors.dim(`Team: ${teamRef}\n`));
+      if (projects.length === 0) {
+        stdout.write(colors.dim("(no projects)\n"));
+        return;
+      }
+      ctx.out.table(
+        projects.map((p) => ({
+          name: colors.bold(p.name || p.slug),
+          slug: p.slug || colors.dim("?"),
+          id: colors.dim(p.id),
+        })),
+        [
+          { key: "name", header: "NAME" },
+          { key: "slug", header: "SLUG" },
+          { key: "id", header: "ID" },
+        ],
+      );
+    },
+  );
+}
+
+async function listDeployments(ctx, args) {
+  const { projectId: explicit, rest } = extractProjectFlag(args);
+  if (rest.length > 0) {
+    throw new Error(
+      `Unexpected positional: ${rest[0]}. Usage: synapse list deployments [--project=<id>]`,
+    );
+  }
+  let projectId = explicit;
+  let source = "flag";
+  if (!projectId) {
+    const linked = ctx.projectConfig;
+    if (linked && linked.project && linked.project.id) {
+      projectId = linked.project.id;
+      source = "linked";
+    }
+  }
+  if (!projectId) {
+    throw new Error(
+      "No linked project. Pass --project=<id> or run `synapse select` first.",
+    );
+  }
+  const deployments = await ctx.api.deployments(projectId);
+  ctx.out.result(
+    { kind: "deployments", projectId, projectSource: source, count: deployments.length, deployments },
+    (_d, { stdout }) => {
+      stdout.write(colors.dim(`Project: ${projectId}\n`));
+      if (deployments.length === 0) {
+        stdout.write(colors.dim("(no deployments — create one with `synapse deployment create`)\n"));
+        return;
+      }
+      ctx.out.table(
+        deployments.map((d) => ({
+          name: colors.bold(d.name),
+          type: typeBadge(d.deploymentType || d.type),
+          status: colors.statusBadge(d.status || ""),
+          url: d.deploymentUrl || d.url || colors.dim("(no url)"),
+        })),
+        [
+          { key: "name", header: "NAME" },
+          { key: "type", header: "TYPE" },
+          { key: "status", header: "STATUS" },
+          { key: "url", header: "URL" },
+        ],
+      );
+    },
+  );
+}
+
+function typeBadge(t) {
+  switch (t) {
+    case "prod":
+      return colors.yellow((t || "").toUpperCase());
+    case "dev":
+      return colors.cyan ? colors.cyan(t.toUpperCase()) : t.toUpperCase();
+    case "preview":
+      return colors.dim((t || "").toUpperCase());
+    default:
+      return t ? colors.dim(t) : "";
+  }
+}
+
+module.exports = {
+  name: "list",
+  summary: "List teams, projects, or deployments visible to your session.",
+  usage: "synapse list <deployments|projects|teams> [--project=<id>] [--team=<slug>] [--json]",
+  description: `Catalogs the resource of the chosen kind. All subcommands support --json for scripting.
+
+Resource resolution:
+  list teams        always lists every team you're a member of
+  list projects     uses the linked team if no --team flag
+  list deployments  uses the linked project if no --project flag
+
+Examples:
+  synapse list teams
+  synapse list projects --team=amageia
+  synapse list deployments --project=00000000-0000-0000-0000-000000000000
+  synapse list deployments --json | jq '.deployments[] | .name'`,
+
+  // Exports for tests.
+  KINDS,
+  listTeams,
+  listProjects,
+  listDeployments,
+
+  async run(args, ctx) {
+    const kind = args[0];
+    if (!kind) {
+      throw new Error(`Usage: synapse list <${KINDS.join("|")}>`);
+    }
+    if (!KINDS.includes(kind)) {
+      throw new Error(
+        `Unknown list kind: ${kind}. Try: ${KINDS.join(" | ")}.`,
+      );
+    }
+    const rest = args.slice(1);
+    if (kind === "teams") return listTeams(ctx);
+    if (kind === "projects") return listProjects(ctx, rest);
+    return listDeployments(ctx, rest);
+  },
+};

package/lib/commands/login.js

@@ -37,7 +37,20 @@ The saved session carries both the access token (1h TTL) and a refresh token (30
     });
     ctx.out.result(
       { baseUrl, user: session.user || null, configPath: file },
-      () => ctx.out.info(`Saved Synapse session to ${file}`),
+      () => {
+        ctx.out.info(`Saved Synapse session to ${file}`);
+        // v1.8.6 (A2): post-login next-step hint. Without this, the
+        // operator just sees "saved" and stares at the prompt — login
+        // is step 1 of a 3-step onboarding (login → select → dev),
+        // and the absence of step 2 was the most common first-run
+        // dead-end reported.
+        ctx.out.info(
+          `\nNext step: \`cd\` into your app directory and run \`synapse select\` to link it to a project + deployment.`,
+        );
+        ctx.out.info(
+          `Then run \`synapse doctor\` to confirm everything is healthy, or \`synapse open\` to browse the dashboard.`,
+        );
+      },
     );
   },
 };