@iann29/synapse 1.8.1 → 1.8.2

package/lib/commands/select.js

@@ -195,7 +195,11 @@ show up in the menu).`,
       }),
     );
     const creds = await api.cliCredentials(dev.name);
-    const envPath = writeProjectEnv(ctx.cwd, creds);
+    const envPath = writeProjectEnv(ctx.cwd, creds, {
+      team: { slug: team.slug, name: team.name },
+      project: { slug: project.slug, name: project.name },
+      target: "dev",
+    });
 
     ctx.out.result(
       {

package/lib/doctor/checks.js

@@ -200,6 +200,44 @@ const checkEnvLocalHasVars = {
   }),
 };
 
+// v1.8.2: separate check for the Cloud-compatible NEXT_PUBLIC_* vars.
+// Self-hosted auth (above) is REQUIRED. These public vars are
+// convenience for code that imports CONVEX_URL the way Cloud
+// tutorials do — missing them only warns, never blocks (the CLI
+// still works without them).
+const checkEnvLocalHasPublicVars = {
+  id: "env-local-has-public-convex-vars",
+  category: "project",
+  title: "NEXT_PUBLIC_CONVEX_URL + NEXT_PUBLIC_CONVEX_SITE_URL in .env.local",
+  autoFix: "never",
+  dependsOn: ["env-local-present"],
+  run: safeRun(async (ctx) => {
+    if (!ctx.projectConfig) {
+      return { status: "skipped", summary: "no linked project", data: {} };
+    }
+    const env = readProjectEnv(ctx.cwd);
+    const hasUrl = !!env.NEXT_PUBLIC_CONVEX_URL;
+    const hasSite = !!env.NEXT_PUBLIC_CONVEX_SITE_URL;
+    if (hasUrl && hasSite) {
+      return {
+        status: "ok",
+        summary: "both public vars present",
+        data: { hasUrl, hasSite },
+      };
+    }
+    const missing = [];
+    if (!hasUrl) missing.push("NEXT_PUBLIC_CONVEX_URL");
+    if (!hasSite) missing.push("NEXT_PUBLIC_CONVEX_SITE_URL");
+    return {
+      status: "warn",
+      summary: `missing: ${missing.join(", ")} (Cloud-style vars; CLI still works)`,
+      remediation:
+        "Run `synapse select` to regenerate .env.local with Cloud-compatible vars (CLI v1.8.2+).",
+      data: { hasUrl, hasSite, missing },
+    };
+  }),
+};
+
 const checkGitignoreProtectsEnv = {
   id: "gitignore-protects-env",
   category: "project",
@@ -609,6 +647,7 @@ const ALL_CHECKS = [
   checkAuthTokenValid,
   checkEnvLocalPresent,
   checkEnvLocalHasVars,
+  checkEnvLocalHasPublicVars,
   checkProjectStillExists,
 
   // Tier C (per deployment)

package/lib/env-file.js

@@ -1,9 +1,48 @@
+// Writes / reads `.env.local` for Synapse-linked projects.
+//
+// As of v1.8.2 the file is drop-in compatible with Convex Cloud
+// tutorials:
+//
+//   # Convex (Synapse self-hosted — drop-in compatible with Cloud tutorials)
+//   NEXT_PUBLIC_CONVEX_URL="https://<name>.app.synapsepanel.com"
+//   NEXT_PUBLIC_CONVEX_SITE_URL="https://<name>.app.synapsepanel.com"
+//   CONVEX_DEPLOYMENT=dev:<name> # team: <team>, project: <project>
+//
+//   # Self-hosted auth (Synapse cannot use Cloud account session)
+//   CONVEX_SELF_HOSTED_URL="https://<name>.app.synapsepanel.com"
+//   CONVEX_SELF_HOSTED_ADMIN_KEY="<name>|..."
+//
+// In Cloud, NEXT_PUBLIC_CONVEX_URL points at `.convex.cloud` and
+// NEXT_PUBLIC_CONVEX_SITE_URL at `.convex.site` — two different
+// origins. In self-hosted both point at the same URL; the backend
+// container routes API calls and HTTP actions on the same host.
+//
+// CONVEX_DEPLOYMENT is kept uncommented for cosmetic familiarity —
+// the synapse wrapper around `npx convex` (`runConvex` in
+// lib/convex.js) deletes it from the child env when self-hosted
+// vars are present, so it never accidentally triggers Cloud auth.
+
 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";
+const NEXT_PUBLIC_CONVEX_URL = "NEXT_PUBLIC_CONVEX_URL";
+const NEXT_PUBLIC_CONVEX_SITE_URL = "NEXT_PUBLIC_CONVEX_SITE_URL";
+
+const PUBLIC_HEADER = "# Convex (Synapse self-hosted — drop-in compatible with Cloud tutorials)";
+const AUTH_HEADER = "# Self-hosted auth (Synapse cannot use Cloud account session)";
+
+// Keys whose VALUE we own. The CONVEX_DEPLOYMENT line is special-cased
+// (it's a bare assignment with an inline comment, not a quoted value),
+// so it's not in this map.
+const MANAGED_VALUE_KEYS = [
+  NEXT_PUBLIC_CONVEX_URL,
+  NEXT_PUBLIC_CONVEX_SITE_URL,
+  SELF_HOSTED_URL,
+  SELF_HOSTED_ADMIN_KEY,
+];
 
 function quoteEnvValue(value) {
   return `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n")}"`;
@@ -18,11 +57,24 @@ function keyFromLine(line) {
   return match ? match[1] : null;
 }
 
-function commentDeploymentLine(line) {
-  if (/^\s*#/.test(line)) {
-    return line;
-  }
-  return `# ${line} # disabled by synapse CLI for self-hosted Convex`;
+// Detects a CONVEX_DEPLOYMENT line whether it's:
+//   - Bare:        `CONVEX_DEPLOYMENT=dev:x`
+//   - Exported:    `export CONVEX_DEPLOYMENT=dev:x`
+//   - Commented:   `# CONVEX_DEPLOYMENT=... # disabled by synapse CLI...` (v1.8.1-)
+// Returns true for any of these so `synapse select` can authoritatively
+// replace a previously-commented form with the new uncommented line.
+function isDeploymentLine(line) {
+  if (keyFromLine(line) === CONVEX_DEPLOYMENT) return true;
+  return /^\s*#\s*(?:export\s+)?CONVEX_DEPLOYMENT\s*=/.test(line);
+}
+
+// Trim any character that would break a single-line trailing comment.
+// We're not parsing it back as a value (it lives in a `# ...` tail),
+// but a literal newline in a team/project name would split the line and
+// poison subsequent parsing. Defensive normalization only.
+function sanitizeForComment(value) {
+  if (value === undefined || value === null) return "";
+  return String(value).replace(/[\r\n]+/g, " ").replace(/#/g, "·").trim();
 }
 
 function unquoteEnvValue(raw) {
@@ -63,53 +115,135 @@ function readProjectEnv(projectDir) {
   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();
+// Build the authoritative CONVEX_DEPLOYMENT line. Returns null when we
+// don't have enough info to write one (e.g. legacy caller with no
+// deploymentName) — caller should skip writing instead of writing a
+// half-formed line.
+function buildDeploymentLine({ deploymentName, target, teamName, projectName, teamSlug, projectSlug }) {
+  if (!deploymentName) return null;
+  const safeTarget = target === "prod" ? "prod" : "dev";
+  const teamLabel = sanitizeForComment(teamName || teamSlug);
+  const projectLabel = sanitizeForComment(projectName || projectSlug);
+  const parts = [];
+  if (teamLabel) parts.push(`team: ${teamLabel}`);
+  if (projectLabel) parts.push(`project: ${projectLabel}`);
+  const comment = parts.length > 0 ? ` # ${parts.join(", ")}` : "";
+  return `${CONVEX_DEPLOYMENT}=${safeTarget}:${deploymentName}${comment}`;
+}
+
+function updateEnvContent(content, opts) {
+  const { convexUrl, adminKey } = opts || {};
+  if (!convexUrl || !adminKey) {
+    throw new Error("updateEnvContent requires convexUrl + adminKey");
   }
+  const deploymentLine = buildDeploymentLine(opts || {});
+
+  const lines = content ? content.split(/\r?\n/) : [];
+  // Drop trailing empty lines — we'll re-add a single newline via join.
+  while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+
+  // Canonical assignments by key.
+  const assignments = {
+    [NEXT_PUBLIC_CONVEX_URL]: envAssignment(NEXT_PUBLIC_CONVEX_URL, convexUrl),
+    [NEXT_PUBLIC_CONVEX_SITE_URL]: envAssignment(NEXT_PUBLIC_CONVEX_SITE_URL, convexUrl),
+    [SELF_HOSTED_URL]: envAssignment(SELF_HOSTED_URL, convexUrl),
+    [SELF_HOSTED_ADMIN_KEY]: envAssignment(SELF_HOSTED_ADMIN_KEY, adminKey),
+  };
 
-  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 = [];
+  let seenDeployment = false;
 
   for (const line of lines) {
     const key = keyFromLine(line);
-    if (key === CONVEX_DEPLOYMENT) {
-      out.push(commentDeploymentLine(line));
+
+    // CONVEX_DEPLOYMENT handling (incl. legacy `# CONVEX_DEPLOYMENT=...
+    // # disabled by synapse CLI` form):
+    //   - new API (caller passed deploymentName)  → first match becomes
+    //     the authoritative line; subsequent matches are dropped.
+    //   - legacy API (no deploymentName)          → leave existing lines
+    //     untouched so callers still using the old shape don't surprise
+    //     their users.
+    if (isDeploymentLine(line)) {
+      if (deploymentLine) {
+        if (!seenDeployment) {
+          out.push(deploymentLine);
+          seenDeployment = true;
+        }
+        continue;
+      }
+      out.push(line);
       continue;
     }
-    if (replacements.has(key)) {
-      if (!seen.has(key)) {
-        out.push(replacements.get(key));
-        seen.add(key);
-      }
+
+    if (assignments[key] && !seen.has(key)) {
+      out.push(assignments[key]);
+      seen.add(key);
+      continue;
+    }
+    if (assignments[key] && seen.has(key)) {
+      // Duplicate of a key we already wrote — drop to keep file canonical.
       continue;
     }
     out.push(line);
   }
 
-  if (out.length > 0 && out[out.length - 1] !== "") {
-    out.push("");
+  // Append any unseen managed keys, grouped under section headers so a
+  // brand-new file gets a tidy layout. On idempotent rewrites the loop
+  // above will have replaced everything in place; only the first-time
+  // write hits this block.
+  const newPublicLines = [];
+  if (!seen.has(NEXT_PUBLIC_CONVEX_URL)) {
+    newPublicLines.push(assignments[NEXT_PUBLIC_CONVEX_URL]);
+    seen.add(NEXT_PUBLIC_CONVEX_URL);
   }
-  for (const [key, line] of replacements.entries()) {
-    if (!seen.has(key)) {
-      out.push(line);
+  if (!seen.has(NEXT_PUBLIC_CONVEX_SITE_URL)) {
+    newPublicLines.push(assignments[NEXT_PUBLIC_CONVEX_SITE_URL]);
+    seen.add(NEXT_PUBLIC_CONVEX_SITE_URL);
+  }
+  if (deploymentLine && !seenDeployment) {
+    newPublicLines.push(deploymentLine);
+    seenDeployment = true;
+  }
+
+  const newAuthLines = [];
+  if (!seen.has(SELF_HOSTED_URL)) {
+    newAuthLines.push(assignments[SELF_HOSTED_URL]);
+    seen.add(SELF_HOSTED_URL);
+  }
+  if (!seen.has(SELF_HOSTED_ADMIN_KEY)) {
+    newAuthLines.push(assignments[SELF_HOSTED_ADMIN_KEY]);
+    seen.add(SELF_HOSTED_ADMIN_KEY);
+  }
+
+  if (newPublicLines.length > 0 || newAuthLines.length > 0) {
+    if (out.length > 0) out.push("");
+    if (newPublicLines.length > 0) {
+      out.push(PUBLIC_HEADER);
+      out.push(...newPublicLines);
+    }
+    if (newAuthLines.length > 0) {
+      if (newPublicLines.length > 0) out.push("");
+      out.push(AUTH_HEADER);
+      out.push(...newAuthLines);
     }
   }
 
   return out.join("\n") + "\n";
 }
 
-function writeProjectEnv(projectDir, credentials) {
+function writeProjectEnv(projectDir, credentials, opts = {}) {
   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,
+    deploymentName: credentials.deploymentName || opts.deploymentName,
+    target: opts.target,
+    teamName: opts.team?.name,
+    teamSlug: opts.team?.slug,
+    projectName: opts.project?.name,
+    projectSlug: opts.project?.slug,
   });
   fs.writeFileSync(file, next, { mode: 0o600 });
   try {
@@ -122,12 +256,20 @@ function writeProjectEnv(projectDir, credentials) {
 
 module.exports = {
   CONVEX_DEPLOYMENT,
+  NEXT_PUBLIC_CONVEX_URL,
+  NEXT_PUBLIC_CONVEX_SITE_URL,
   SELF_HOSTED_ADMIN_KEY,
   SELF_HOSTED_URL,
+  MANAGED_VALUE_KEYS,
+  PUBLIC_HEADER,
+  AUTH_HEADER,
+  buildDeploymentLine,
+  isDeploymentLine,
   keyFromLine,
   parseEnvContent,
   quoteEnvValue,
   readProjectEnv,
+  sanitizeForComment,
   updateEnvContent,
   writeProjectEnv,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iann29/synapse",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "Thin CLI wrapper for using the official Convex CLI with Synapse-managed deployments.",
   "license": "Apache-2.0",
   "repository": {