@iann29/synapse 1.8.0 → 1.8.1

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/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,
       },
     };
   }),
@@ -323,12 +348,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 +380,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 +397,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 ----------------------------------------------

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.1",
   "description": "Thin CLI wrapper for using the official Convex CLI with Synapse-managed deployments.",
   "license": "Apache-2.0",
   "repository": {