@iann29/synapse 1.8.4 → 1.8.6

package/lib/commands/_context.js

@@ -23,6 +23,24 @@ const {
 } = require("../config");
 const { readProjectConfig } = require("../project");
 
+// v1.8.6 (A3): SessionExpiredError carries an operator-actionable
+// message when the refresh token itself is rejected (>30d old or
+// revoked at server side). bin/synapse.js prints err.message verbatim,
+// so a clear "your session expired, run `synapse login <url>`" lands
+// directly in front of the operator instead of a cryptic
+// "Synapse API returned 401" message.
+class SessionExpiredError extends Error {
+  constructor(baseUrl, cause) {
+    super(
+      `Your Synapse session expired. Run \`synapse login ${baseUrl}\` to sign in again.` +
+        (cause ? ` (refresh failed: ${cause})` : ""),
+    );
+    this.name = "SessionExpiredError";
+    this.baseUrl = baseUrl;
+    this.cause = cause;
+  }
+}
+
 // Wraps an API client so any 401 transparently retries against
 // /v1/auth/refresh once. Mirrors what bin/synapse.js had before the
 // refactor; lives here so every command shares it.
@@ -43,10 +61,30 @@ function makeRefreshableApi(cfg) {
           ) {
             throw err;
           }
-          const session = await new SynapseAPI({ baseUrl: cfg.baseUrl }).refresh(
-            cfg.refreshToken,
-          );
-          if (!session.accessToken) throw err;
+          // v1.8.6 (A3): catch refresh failures and surface a clear
+          // re-login instruction instead of the raw upstream 401.
+          // Refresh tokens expire (30d default) or get revoked
+          // server-side; either way the operator needs to log in
+          // again and the bare "Synapse API returned 401" gave them
+          // no path forward.
+          let session;
+          try {
+            session = await new SynapseAPI({ baseUrl: cfg.baseUrl }).refresh(
+              cfg.refreshToken,
+            );
+          } catch (refreshErr) {
+            const detail =
+              refreshErr instanceof SynapseAPIError
+                ? `${refreshErr.code} ${refreshErr.status}`
+                : String(refreshErr.message || refreshErr);
+            throw new SessionExpiredError(cfg.baseUrl, detail);
+          }
+          if (!session.accessToken) {
+            throw new SessionExpiredError(
+              cfg.baseUrl,
+              "no access token in refresh response",
+            );
+          }
           cfg.accessToken = session.accessToken;
           cfg.refreshToken = session.refreshToken || cfg.refreshToken;
           cfg.tokenType = session.tokenType || cfg.tokenType || "Bearer";
@@ -84,10 +122,19 @@ function createContext({ out, cwd = process.cwd(), env = process.env } = {}) {
 
     // Throws "Not logged in" with a helpful message when no session
     // exists. Commands that REQUIRE auth call this.
+    //
+    // v1.8.6 (A1): copy now points operators who don't know the URL
+    // at their admin instead of leaving them stuck. This message
+    // cascades through 7+ commands (whoami / status / select /
+    // credentials / dev / deploy / convex) because the error
+    // propagates verbatim through bin/synapse.js's top-level
+    // try/catch.
     get cfg() {
       const c = cfgLoad();
       if (!c || !c.baseUrl || !c.accessToken) {
-        throw new Error("Not logged in. Run `synapse login <url>` first.");
+        throw new Error(
+          "Not logged in. Run `synapse login <your-synapse-url>` (e.g. `synapse login https://synapsepanel.com`). If you don't know the URL, ask the admin who set up your Synapse host.",
+        );
       }
       _cfg = c;
       return c;
@@ -130,4 +177,9 @@ function createContext({ out, cwd = process.cwd(), env = process.env } = {}) {
   };
 }
 
-module.exports = { createContext, makeRefreshableApi, normalizeBaseUrl };
+module.exports = {
+  createContext,
+  makeRefreshableApi,
+  normalizeBaseUrl,
+  SessionExpiredError,
+};

package/lib/commands/convex.js

@@ -117,10 +117,27 @@ async function runConvexCommand(args, ctx) {
     ctx.out.info(
       `Using Synapse ${resolved.target} deployment ${resolved.deploymentName}.`,
     );
+    // v1.8.6 (A5): the upstream Convex CLI emits "Can't safely modify
+    // .env.local for NEXT_PUBLIC_CONVEX_SITE_URL, please edit manually."
+    // because our value is a self-hosted URL that doesn't match its
+    // `.convex.site` pattern. The warning is benign (the file IS
+    // correct — we wrote it), but it's confusing without context.
+    // Pre-announce so the operator knows it's expected.
+    ctx.out.info(
+      "(npx convex may warn it can't modify NEXT_PUBLIC_CONVEX_SITE_URL — benign; Synapse owns those values.)",
+    );
   } else {
     resolved = await resolveConvexInvocation(args, { projectDir: ctx.cwd });
   }
   const code = await runConvex(resolved.args, { credentials: resolved.credentials });
+  // v1.8.6 (A5): when npx convex exits non-zero, surface a hint about
+  // where the failure came from — operators see a `[X]` from convex
+  // and assume Synapse broke. Point them at the right `--help`.
+  if (code !== 0) {
+    ctx.out.info(
+      `\n(npx convex exited ${code}. If this looks like an unknown-command typo, run \`synapse convex --help\` for the upstream Convex help.)`,
+    );
+  }
   process.exitCode = code;
 }
 

package/lib/commands/credentials.js

@@ -63,7 +63,28 @@ Formats:
     const { format, rest } = parseFormat(args);
     const deployment = rest[0];
     if (!deployment) {
-      throw new Error("Usage: synapse credentials <deployment> [--format env|shell|json]");
+      // v1.8.6 (A4): the operator already linked a project — we know
+      // which deployment names exist. Surfacing them turns a dead-end
+      // Usage line into an actionable hint without an extra API call.
+      // The plain Usage line stays as the fallback for unlinked
+      // directories.
+      const linked = ctx.projectConfig;
+      let hint = "";
+      if (linked && linked.deployments) {
+        const names = [];
+        if (linked.deployments.dev?.name) {
+          names.push(`dev=${linked.deployments.dev.name}`);
+        }
+        if (linked.deployments.prod?.name) {
+          names.push(`prod=${linked.deployments.prod.name}`);
+        }
+        if (names.length > 0) {
+          hint = `\n\nThis project has: ${names.join(", ")}. Try \`synapse credentials ${linked.deployments.dev?.name || linked.deployments.prod?.name}\`. Run \`synapse status\` to see them all.`;
+        }
+      }
+      throw new Error(
+        `Usage: synapse credentials <deployment> [--format env|shell|json]${hint}`,
+      );
     }
     if (!FORMATS.has(format)) {
       throw new Error("format must be one of: env, shell, json");

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

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/package.json

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