@iann29/synapse 1.8.0 → 1.8.2

package/lib/api.js

@@ -117,6 +117,13 @@ class SynapseAPI {
     return this.listAll(`/v1/teams/${encodeURIComponent(teamRef)}/list_projects`);
   }
 
+  // Single-project lookup by ID. Cheaper than listing a team's projects
+  // (no pagination) and FK cascade team→projects means this also detects
+  // a deleted team — backend returns 404 in both cases.
+  getProject(projectId) {
+    return this.request("GET", `/v1/projects/${encodeURIComponent(projectId)}/`);
+  }
+
   deployments(projectId) {
     return this.listAll(`/v1/projects/${encodeURIComponent(projectId)}/list_deployments`);
   }

package/lib/commands/doctor.js

@@ -39,7 +39,11 @@ module.exports = {
 Flags:
   --fix       apply safe fixes automatically (chmod, gitignore appends, etc).
               Checks marked 'prompt' require --yes too.
-  --yes       upgrade 'prompt' fixes to auto.
+  --yes       upgrade 'prompt' fixes to auto. Combined with --fix, also
+              cleans up a stale .synapse/project.json — re-links if the
+              project was transferred to another of your teams,
+              otherwise marks the entry stale so \`synapse select\` can
+              start fresh.
   --verbose   show detailed data per check.
   --json      stable schema (current: v${SCHEMA_VERSION}); CI-friendly.
 

package/lib/commands/open.js

@@ -9,10 +9,15 @@
 //   deployment <n>   /embed/<name> — the dashboard with Convex Dashboard iframe
 //   url              just the synapse base URL (for "open the dashboard root")
 //
-// No backend call; everything is built client-side from the saved cfg
-// + projectConfig.
+// For `dashboard` (the default), we do a single cheap GET probe against
+// the linked project before spawning the browser, so an operator with a
+// stale .synapse/project.json gets a warning on stderr instead of
+// landing on a page that cascades "Failed to load X" errors. We never
+// BLOCK the launch — operator may want to see the broken state.
+// `docs` / `deployment <name>` / `url` skip the probe.
 
 const { spawn } = require("node:child_process");
+const { SynapseAPIError } = require("../api");
 
 function buildUrl(target, restArgs, { cfg, projectConfig }) {
   const base = cfg?.baseUrl ?? "";
@@ -50,6 +55,29 @@ function launcher(platform = process.platform) {
   return { cmd: "xdg-open", shell: false };
 }
 
+// Cheap pre-flight probe: confirm the linked project still exists before
+// launching the browser. Returns one of:
+//   "ok"          — project resolved on the backend
+//   "not_found"   — backend returned 404 (project deleted or transferred)
+//   "unverified"  — couldn't reach backend / non-404 error / no session /
+//                   no linked project
+// Only `dashboard` target calls this — `docs` is external, `deployment
+// <name>` and `url` are operator-supplied + assumed intentional.
+async function checkProjectStatus(ctx, projectConfig) {
+  if (!projectConfig?.project?.id) return "unverified";
+  if (!ctx?.cfgOrNull?.accessToken) return "unverified";
+  if (!ctx.api) return "unverified";
+  try {
+    await ctx.api.getProject(projectConfig.project.id);
+    return "ok";
+  } catch (err) {
+    if (err instanceof SynapseAPIError && err.status === 404) {
+      return "not_found";
+    }
+    return "unverified";
+  }
+}
+
 module.exports = {
   name: "open",
   summary: "Open a Synapse-related URL in your default browser.",
@@ -65,6 +93,7 @@ Targets:
   // Exports for tests.
   buildUrl,
   launcher,
+  checkProjectStatus,
 
   async run(args, ctx) {
     const target = args[0];
@@ -73,11 +102,29 @@ Targets:
       projectConfig: ctx.projectConfig,
     });
 
+    // Pre-flight only for dashboard (default + explicit). Other targets
+    // either point externally or are intentionally URL-direct.
+    const shouldProbe = target === undefined || target === "dashboard";
+    let projectStatus = "unverified";
+    if (shouldProbe && ctx.projectConfig?.project?.id) {
+      projectStatus = await checkProjectStatus(ctx, ctx.projectConfig);
+    }
+
     if (ctx.out.json) {
-      ctx.out.result({ url, target: target ?? "dashboard" }, () => {});
+      ctx.out.result({ url, target: target ?? "dashboard", projectStatus }, () => {});
       return;
     }
 
+    if (projectStatus === "not_found") {
+      const projName = ctx.projectConfig?.project?.name || ctx.projectConfig?.project?.id;
+      const base = ctx.cfgOrNull?.baseUrl ?? "";
+      ctx.out.warn(
+        `Linked project ${projName} was not found on ${base}. It may have been deleted. Run \`synapse select\` to relink.`,
+      );
+    } else if (shouldProbe && projectStatus === "unverified" && ctx.projectConfig?.project?.id && ctx.cfgOrNull?.accessToken) {
+      ctx.out.info("Could not verify project state (offline?), opening anyway.");
+    }
+
     const { cmd, shell } = launcher();
     ctx.out.info(`Opening ${url}`);
     try {

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

@@ -11,6 +11,7 @@ const path = require("node:path");
 const os = require("node:os");
 const { SynapseAPI, SynapseAPIError } = require("../api");
 const { readProjectEnv } = require("../env-file");
+const { writeProjectConfig } = require("../project");
 
 const REQUIRED_NODE = "18.17.0";
 
@@ -110,16 +111,40 @@ const checkInProjectDir = {
   dependsOn: [],
   run: safeRun(async (ctx) => {
     const exists = ctx.projectConfig !== null && ctx.projectConfig !== undefined;
+    if (!exists) {
+      return {
+        status: "warn",
+        summary: "no project metadata in this directory",
+        remediation: "Run `synapse select` to link this directory.",
+        data: { cwd: ctx.cwd, linked: false, project: null },
+      };
+    }
+    // v1.8.1: `doctor --fix --yes` may have written a stale marker into
+    // project.json. Detect it explicitly so the next doctor run says
+    // "linked-but-stale" instead of confidently claiming a healthy link.
+    if (ctx.projectConfig.staleReason === "project-not-found") {
+      const date = ctx.projectConfig.staleAt
+        ? ctx.projectConfig.staleAt.slice(0, 10)
+        : "previously";
+      return {
+        status: "warn",
+        summary: `directory was unlinked by doctor — staleReason: project-not-found (${date})`,
+        remediation: "Run `synapse select` to re-link.",
+        data: {
+          cwd: ctx.cwd,
+          linked: false,
+          stale: true,
+          previous: ctx.projectConfig.previous ?? null,
+        },
+      };
+    }
     return {
-      status: exists ? "ok" : "warn",
-      summary: exists
-        ? `linked to ${ctx.projectConfig.project?.name || "?"}`
-        : "no project metadata in this directory",
-      remediation: exists ? null : "Run `synapse select` to link this directory.",
+      status: "ok",
+      summary: `linked to ${ctx.projectConfig.project?.name || "?"}`,
       data: {
         cwd: ctx.cwd,
-        linked: exists,
-        project: exists ? ctx.projectConfig.project?.id : null,
+        linked: true,
+        project: ctx.projectConfig.project?.id,
       },
     };
   }),
@@ -175,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",
@@ -323,12 +386,21 @@ const checkProjectStillExists = {
   id: "project-still-exists",
   category: "backend",
   title: "linked project exists on backend",
-  autoFix: "never",
+  // v1.8.1: was "never" — promoted to "prompt" so `doctor --fix --yes`
+  // can auto-remediate stale .synapse/project.json. See Bug 3 in
+  // docs/V1_8_1_STALE_LINK_FIXES.md for the design (B-then-C hybrid).
+  autoFix: "prompt",
   dependsOn: ["auth-token-valid", "in-project-dir"],
   run: safeRun(async (ctx) => {
     if (!ctx.projectConfig || !ctx.api) {
       return { status: "skipped", summary: "no linked project or no session", data: {} };
     }
+    // The marker case (stale link written by a prior --fix) has no
+    // project.id to look up — checkInProjectDir already warned about
+    // it. Skip the network call.
+    if (!ctx.projectConfig.project?.id) {
+      return { status: "skipped", summary: "no project id (stale marker?)", data: {} };
+    }
     const teamRef = ctx.projectConfig.team?.slug || ctx.projectConfig.team?.id;
     if (!teamRef) {
       return { status: "warn", summary: "linked project has no team ref", data: {} };
@@ -346,8 +418,13 @@ const checkProjectStillExists = {
       return {
         status: "issue",
         summary: "project not found in team — deleted or transferred?",
-        remediation: "Run `synapse select` to re-link.",
-        data: { teamRef, projectId: ctx.projectConfig.project?.id },
+        remediation: "Run `synapse select` to re-link, or `synapse doctor --fix --yes`.",
+        data: {
+          teamRef,
+          projectId: ctx.projectConfig.project?.id,
+          teamSlug: ctx.projectConfig.team?.slug,
+          projectSlug: ctx.projectConfig.project?.slug,
+        },
       };
     } catch (err) {
       return {
@@ -358,6 +435,102 @@ const checkProjectStillExists = {
       };
     }
   }),
+  // Two-phase fix (Bug 3 design):
+  //   B) If exactly one other team owns a project with the same slug,
+  //      auto-relink (project was transferred). Deployments are reset
+  //      because the old refs are stale — operator runs `synapse
+  //      select` once if they want specific dev/prod refs.
+  //   C) Otherwise (no match, ambiguous match, or any API error):
+  //      mark project.json as stale and keep the operator's previous
+  //      block for forensics. Append an idempotent comment marker to
+  //      .env.local so the bogus admin key isn't silently trusted.
+  // Both paths are reachable only under `--fix --yes` (autoFix=prompt
+  // + allowPrompt=true at runner.js applyAutoFixes).
+  fix: async (ctx) => {
+    if (!ctx.projectConfig || !ctx.api) {
+      return { kind: "failed", message: "no project config or no API session" };
+    }
+    const savedProjectId = ctx.projectConfig.project?.id;
+    const savedProjectSlug = ctx.projectConfig.project?.slug;
+    const previous = {
+      team: ctx.projectConfig.team,
+      project: ctx.projectConfig.project,
+    };
+    // Fresh listing — never trust the upstream check's stale data.
+    let teams;
+    try {
+      teams = await ctx.api.teams();
+    } catch (err) {
+      return { kind: "failed", message: `could not list teams: ${err.message}` };
+    }
+    const candidates = [];
+    if (savedProjectSlug) {
+      for (const team of teams) {
+        let projects;
+        try {
+          projects = await ctx.api.projects(team.slug || team.id);
+        } catch {
+          continue; // one team's lookup failed; try the rest
+        }
+        for (const p of projects) {
+          if (p.slug === savedProjectSlug && p.id !== savedProjectId) {
+            candidates.push({ team, project: p });
+          }
+        }
+      }
+    }
+    if (candidates.length === 1) {
+      // Heuristic B: unambiguous re-link (most likely a transfer).
+      const { team, project } = candidates[0];
+      const newConfig = {
+        synapseUrl: ctx.projectConfig.synapseUrl,
+        team,
+        project,
+        deployments: {},
+      };
+      writeProjectConfig(ctx.cwd, newConfig);
+      // Sync in-memory ctx so the runner's recheck sees the new state.
+      // Without this, `Object.assign(r, fresh, {fixedBy})` overwrites
+      // with another "issue" because run() still reads the old project.id.
+      ctx.projectConfig = newConfig;
+      return {
+        kind: "applied",
+        message: `re-linked to ${team.slug || team.name}/${project.slug || project.name} (project was transferred)`,
+      };
+    }
+    // Fallback C: write a stale marker. Keep synapseUrl + the previous
+    // block so the operator can audit what was there.
+    const staleAt = new Date().toISOString();
+    const staleConfig = {
+      synapseUrl: ctx.projectConfig.synapseUrl,
+      staleReason: "project-not-found",
+      staleAt,
+      previous,
+    };
+    writeProjectConfig(ctx.cwd, staleConfig);
+    ctx.projectConfig = staleConfig;
+    // Idempotent comment marker on .env.local. The admin key inside is
+    // still bogus, but deletion would lose info the operator may want
+    // to grep, so just annotate. Marker string is stable so re-running
+    // fix doesn't keep appending.
+    try {
+      const envPath = path.join(ctx.cwd, ".env.local");
+      if (fs.existsSync(envPath)) {
+        const content = fs.readFileSync(envPath, "utf8");
+        const marker = "# stale — admin key invalid";
+        if (!content.includes(marker)) {
+          const banner = `${marker} since ${staleAt.slice(0, 10)}, run \`synapse select\`\n`;
+          fs.writeFileSync(envPath, banner + content);
+        }
+      }
+    } catch {
+      // Best-effort; project.json marker is the source of truth.
+    }
+    return {
+      kind: "applied",
+      message: "marked stale — run `synapse select` to re-link",
+    };
+  },
 };
 
 // -------- deployments ----------------------------------------------
@@ -474,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/lib/project.js

@@ -50,12 +50,20 @@ function sanitizeProjectConfig(input) {
   if (input.deployments?.prod) {
     deployments.prod = deploymentRef(input.deployments.prod);
   }
+  // v1.8.1: `doctor --fix --yes` can mark a project.json stale when the
+  // linked project was deleted/transferred (see Bug 3). The marker
+  // fields (staleReason / staleAt / previous) need to round-trip
+  // through writeProjectConfig — without these allowlist entries
+  // sanitizeProjectConfig would strip them on every write.
   return compactObject({
     version: 1,
     synapseUrl: input.synapseUrl,
     team: entityRef(input.team),
     project: entityRef(input.project),
     deployments,
+    staleReason: input.staleReason,
+    staleAt: input.staleAt,
+    previous: input.previous,
   });
 }
 

package/package.json

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