@iann29/synapse 1.8.3 → 1.8.5

package/lib/commands/select.js

@@ -222,8 +222,11 @@ show up in the menu).`,
         if (prod) {
           ctx.out.info(`Selected prod deployment ${colors.bold(prod.name)}.`);
         } else {
+          // v1.8.5: surface the dashboard URL so the operator can click
+          // straight to "New deployment" instead of hunting for it.
+          const projectUrl = `${cfg.baseUrl}/teams/${encodeURIComponent(team.slug || team.id)}/${encodeURIComponent(project.id)}`;
           ctx.out.warn(
-            "no prod deployment found. `synapse deploy` (and `synapse convex deploy`) will fail with a clear error until you create a prod deployment and run `synapse select` again.",
+            `no prod deployment found. Create one at ${projectUrl} → "New deployment" → mark as PROD, then run \`synapse select\` again. \`synapse deploy\` fails until then.`,
           );
         }
         if (process.env.CONVEX_DEPLOYMENT) {
@@ -234,6 +237,9 @@ show up in the menu).`,
         ctx.out.info(
           `\nNext step: run ${colors.bold("synapse dev")} (or ${colors.bold("npx convex dev")}) once in this directory to push your schema and watch for changes.`,
         );
+        ctx.out.info(
+          `Or run ${colors.bold("synapse doctor")} first to confirm everything is healthy (add ${colors.bold("--fix")} to auto-clean .gitignore + file modes).`,
+        );
       },
     );
     // Force ctx.projectConfig to re-read on next access (commands chained

package/lib/commands/status.js

@@ -146,12 +146,27 @@ Run \`synapse doctor\` for a deeper health check.`,
           ],
         );
         const broken = rows.filter((r) => r.urlForm === "host").length;
+        const hasProd = rows.some((r) => r.type === "prod");
+        const hasDev = rows.some((r) => r.type === "dev");
+
         if (broken > 0) {
           stdout.write("\n");
           ctx.out.warn(
-            `${broken} deployment${broken > 1 ? "s" : ""} not browser-reachable — set SYNAPSE_BASE_DOMAIN on the server OR add a custom domain per deployment. Run \`synapse doctor\` for the full diagnosis.`,
+            `${broken} deployment${broken > 1 ? "s" : ""} not browser-reachable — instance admin can enable wildcard at ${baseUrl}/admin/host-domain, or add a custom domain per deployment.`,
           );
         }
+        // v1.8.5 hints: when nothing's broken, surface the next-step
+        // bread-crumb so first-time operators know what to do next.
+        if (broken === 0 && rows.length > 0) {
+          stdout.write("\n");
+          if (!hasProd && hasDev) {
+            ctx.out.info(
+              `No prod deployment yet. Create one at ${baseUrl}/teams/<team>/${projectId} → "New deployment" → PROD, then \`synapse select\` again.`,
+            );
+          } else if (hasDev) {
+            ctx.out.info("Run `synapse dev` to start a Convex dev session in this directory.");
+          }
+        }
       },
     );
   },

package/lib/doctor/renderer.js

@@ -33,6 +33,18 @@ function renderHeader(report, write) {
   write(parts.join(" ") + "\n\n");
 }
 
+// v1.8.5: inline-tag formatter for the fix hint. Mirrors the cyan-on-dim
+// rest of the remediation line; falls back to plain text if colors.cyan
+// isn't defined (the `colors` shim is a no-op on non-tty stdouts).
+function fixableTag(r) {
+  if (!r.fixable) return "";
+  if (r.fixedBy) return ""; // already fixed; no nudge needed
+  const text = r.fixable === "auto"
+    ? " [run `synapse doctor --fix`]"
+    : " [run `synapse doctor --fix --yes`]";
+  return colors.cyan ? colors.cyan(text) : text;
+}
+
 function renderCheck(r, { verbose }, write) {
   const sym = TONE[r.status](SYMBOL[r.status]);
   write(`    ${sym} ${r.title}`);
@@ -40,7 +52,9 @@ function renderCheck(r, { verbose }, write) {
   if (r.fixedBy) write(`  ${colors.cyan ? colors.cyan("↻ " + r.fixedBy) : "↻ " + r.fixedBy}`);
   write("\n");
   if (r.remediation && (r.status === "issue" || r.status === "warn")) {
-    write(colors.dim(`        → ${r.remediation}\n`));
+    write(colors.dim(`        → ${r.remediation}`));
+    write(fixableTag(r));
+    write("\n");
   }
   if (verbose && r.detail) {
     write(colors.dim(`        ${r.detail.replace(/\n/g, "\n        ")}\n`));
@@ -88,6 +102,39 @@ function renderReport(report, { stdout, verbose = false } = {}) {
   if (report.exitCode !== 0) {
     write(`  ${colors.dim("exit " + report.exitCode)}\n`);
   }
+
+  // v1.8.5: actionable tip footer. Surfaces the right `--fix` invocation
+  // for whichever class of fixable issues remains, so an operator who
+  // just sees a wall of `! ...` warnings knows exactly which command
+  // would clean them up — no need to memorise the auto-vs-prompt split.
+  const autoCount = t.fixableAuto || 0;
+  const promptCount = t.fixablePrompt || 0;
+  const tip = (msg) =>
+    `  ${colors.cyan ? colors.cyan("💡 Tip:") : "Tip:"} ${msg}\n`;
+  if (autoCount + promptCount > 0) {
+    write("\n");
+    if (autoCount > 0 && promptCount > 0) {
+      write(tip(
+        `${autoCount} auto-fixable + ${promptCount} prompt-fixable — run \`synapse doctor --fix --yes\` to apply both.`,
+      ));
+    } else if (autoCount > 0) {
+      write(tip(
+        `${autoCount} ${autoCount === 1 ? "issue is" : "issues are"} auto-fixable — run \`synapse doctor --fix\`.`,
+      ));
+    } else {
+      write(tip(
+        `${promptCount} ${promptCount === 1 ? "issue needs" : "issues need"} confirmation — run \`synapse doctor --fix --yes\`.`,
+      ));
+    }
+  } else if (t.warn + t.issue === 0 && t.ok > 0) {
+    // Clean bill of health → point at the next step. Operators who run
+    // doctor first thing after `synapse select` shouldn't have to wonder
+    // what's next.
+    write("\n");
+    write(tip(
+      "everything healthy — run `synapse dev` to start working, or `synapse status` to list deployments.",
+    ));
+  }
 }
 
 module.exports = { renderReport };

package/lib/doctor/runner.js

@@ -53,10 +53,21 @@ async function runChecks(checks, ctx) {
         continue;
       }
       const result = await check.run(ctx);
+      // `fixable` carries the autoFix kind into the result so the
+      // renderer (and --json consumers) can surface a "this is
+      // fixable, here's the right flag" hint without re-importing
+      // the check catalog. Skipped checks aren't marked fixable —
+      // the fix wouldn't have ctx to operate on anyway.
+      const fixable =
+        typeof check.fix === "function" &&
+        (check.autoFix === "auto" || check.autoFix === "prompt")
+          ? check.autoFix
+          : null;
       resultsById.set(id, {
         id,
         category: check.category,
         title: check.title,
+        fixable,
         ...result,
       });
       pending.delete(id);
@@ -83,13 +94,28 @@ async function runChecks(checks, ctx) {
 }
 
 function totalize(results) {
-  const t = { ok: 0, warn: 0, issue: 0, skipped: 0, fixed: 0 };
+  const t = {
+    ok: 0,
+    warn: 0,
+    issue: 0,
+    skipped: 0,
+    fixed: 0,
+    // v1.8.5: count of results still in warn/issue that have a
+    // registered fix. Splits auto vs prompt so the renderer can show
+    // the right CLI hint at the bottom.
+    fixableAuto: 0,
+    fixablePrompt: 0,
+  };
   for (const r of results) {
     if (r.fixedBy) t.fixed += 1;
     if (r.status === "ok") t.ok += 1;
     else if (r.status === "warn") t.warn += 1;
     else if (r.status === "issue") t.issue += 1;
     else if (r.status === "skipped") t.skipped += 1;
+    if ((r.status === "warn" || r.status === "issue") && !r.fixedBy) {
+      if (r.fixable === "auto") t.fixableAuto += 1;
+      else if (r.fixable === "prompt") t.fixablePrompt += 1;
+    }
   }
   return t;
 }

package/lib/env-file.js

@@ -1,12 +1,13 @@
 // Writes / reads `.env.local` for Synapse-linked projects.
 //
-// As of v1.8.2 the file is drop-in compatible with Convex Cloud
-// tutorials:
+// As of v1.8.4 the file is drop-in compatible with Convex Cloud
+// tutorials (cloud-style NEXT_PUBLIC_* vars) while keeping CONVEX_DEPLOYMENT
+// commented so the Convex CLI's mode picker doesn't see both modes active:
 //
 //   # 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>
+//   # 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"
@@ -17,10 +18,16 @@
 // 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.
+// CONVEX_DEPLOYMENT stays commented in self-hosted mode. The Convex
+// CLI errors with "CONVEX_DEPLOYMENT must not be set when
+// CONVEX_SELF_HOSTED_URL and CONVEX_SELF_HOSTED_ADMIN_KEY are set" if
+// both are present at runtime. Our wrapper deletes CONVEX_DEPLOYMENT
+// from process.env before spawning npx convex, but the convex CLI
+// invokes dotenv.config() on its own and re-reads .env.local, which
+// would resurrect the var. Keeping the line commented preserves the
+// human-readable context (team/project, deployment kind) without
+// triggering the conflict. v1.8.2-v1.8.3 wrote it active — that
+// regression broke `synapse dev` and is fixed in v1.8.4.
 
 const fs = require("node:fs");
 const path = require("node:path");
@@ -115,10 +122,18 @@ function readProjectEnv(projectDir) {
   return parseEnvContent(fs.readFileSync(file, "utf8"));
 }
 
-// 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.
+// Build the (commented) CONVEX_DEPLOYMENT line. Returns null when we
+// don't have enough info (legacy caller with no deploymentName).
+//
+// REGRESSION FIX v1.8.4: this line MUST be commented. Convex CLI rejects
+// the combination of CONVEX_DEPLOYMENT + CONVEX_SELF_HOSTED_URL/ADMIN_KEY
+// — the two modes are mutually exclusive. v1.8.2 wrote it ACTIVE, which
+// broke `npx convex` (and therefore `synapse dev`) because Convex's
+// internal dotenv re-loads .env.local after our wrapper deletes the
+// var from the child env. Keeping it commented preserves the human
+// context (team/project label) while never showing up in the parsed
+// env. See https://github.com/Iann29/convex-synapse/issues for the
+// real-world report from the user's session.
 function buildDeploymentLine({ deploymentName, target, teamName, projectName, teamSlug, projectSlug }) {
   if (!deploymentName) return null;
   const safeTarget = target === "prod" ? "prod" : "dev";
@@ -128,7 +143,7 @@ function buildDeploymentLine({ deploymentName, target, teamName, projectName, te
   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}`;
+  return `# ${CONVEX_DEPLOYMENT}=${safeTarget}:${deploymentName}${comment}`;
 }
 
 function updateEnvContent(content, opts) {

package/package.json

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