@iann29/synapse 1.8.5 → 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/package.json

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