@iann29/synapse 1.6.17 → 1.8.0

package/README.md

@@ -15,6 +15,26 @@ npm install -g @iann29/synapse
 synapse --help
 ```
 
+### Windows: ensure the npm global bin directory is in PATH
+
+On a fresh Node.js install, Windows does **not** always add
+`%APPDATA%\npm` to the user PATH. After `npm install -g`, the
+`synapse` binary exists but `synapse --help` errors with
+*"not recognised as the name of a cmdlet"*. Fix once in PowerShell:
+
+```powershell
+[Environment]::SetEnvironmentVariable(
+  'PATH',
+  "$([Environment]::GetEnvironmentVariable('PATH','User'));$env:APPDATA\npm",
+  'User'
+)
+```
+
+Close every terminal (and your IDE — VS Code caches the env at launch)
+and reopen. `synapse --help` should now print the usage. This is a
+one-time, Node-installer-version-dependent issue; it is not specific
+to this package.
+
 For one app/project:
 
 ```bash

package/bin/synapse.js

@@ -1,372 +1,98 @@
 #!/usr/bin/env node
 
-const { SynapseAPI, SynapseAPIError } = require("../lib/api");
-const { clearConfig, normalizeBaseUrl, requireConfig, writeConfig } = require("../lib/config");
-const { quoteEnvValue, writeProjectEnv } = require("../lib/env-file");
-const {
-  buildProjectConfig,
-  deploymentNameForTarget,
-  readProjectConfig,
-  writeProjectConfig,
-} = require("../lib/project");
-const { askCredentials, choose } = require("../lib/prompts");
-const { runConvex } = require("../lib/convex");
+// Thin dispatcher. Every command's logic lives in lib/commands/*.js;
+// this file's only jobs are:
+//   1. Parse argv into (cmd, rest) via the two-then-one registry.
+//   2. Short-circuit --help / help.
+//   3. Construct the runtime ctx (output layer, lazy session+API).
+//   4. Catch top-level errors and emit a consistent stderr message.
+//
+// Legacy named exports at the bottom are kept ONLY for backwards-
+// compatibility with test/bin.test.js — production code paths never
+// need to require this file as a library.
+
+const { buildRegistry, resolve, wantsHelp } = require("../lib/commands/_dispatcher");
+const { renderRootHelp, renderCommandHelp } = require("../lib/commands/_help");
+const { createContext } = require("../lib/commands/_context");
+const { createOutput, extractJsonFlag } = require("../lib/output");
+const { SynapseAPIError } = require("../lib/api");
+
+const REGISTRY = buildRegistry();
 
-function usage() {
-  return `Usage:
-  synapse login <url>
-  synapse logout
-  synapse whoami
-  synapse select
-  synapse credentials <deployment> [--format env|shell|json]
-  synapse convex [--target dev|prod] [...args]
-`;
-}
-
-function clientFromConfig() {
-  const cfg = requireConfig();
-  const api = new SynapseAPI({ baseUrl: cfg.baseUrl, accessToken: cfg.accessToken });
-  const refreshable = new Proxy(api, {
-    get(target, prop) {
-      const value = target[prop];
-      if (typeof value !== "function") {
-        return value;
-      }
-      return async (...args) => {
-        try {
-          return await value.apply(target, args);
-        } catch (err) {
-          if (!(err instanceof SynapseAPIError) || err.status !== 401 || !cfg.refreshToken) {
-            throw err;
-          }
-          const session = await new SynapseAPI({ baseUrl: cfg.baseUrl }).refresh(cfg.refreshToken);
-          if (!session.accessToken) {
-            throw err;
-          }
-          cfg.accessToken = session.accessToken;
-          cfg.refreshToken = session.refreshToken || cfg.refreshToken;
-          cfg.tokenType = session.tokenType || cfg.tokenType || "Bearer";
-          if (session.user) {
-            cfg.user = session.user;
-          }
-          writeConfig(cfg);
-          target.accessToken = cfg.accessToken;
-          return await value.apply(target, args);
-        }
-      };
-    },
-  });
-  return {
-    cfg,
-    api: refreshable,
-  };
-}
-
-function labelName(item) {
-  const name = item.name || item.slug || item.id;
-  const slug = item.slug && item.slug !== name ? ` (${item.slug})` : "";
-  return `${name}${slug}`;
-}
-
-function teamRef(team) {
-  return team.slug || team.id;
-}
-
-function deploymentLabel(deployment) {
-  const bits = [deployment.name];
-  if (deployment.deploymentType || deployment.type) {
-    bits.push(deployment.deploymentType || deployment.type);
-  }
-  if (deployment.status) {
-    bits.push(deployment.status);
-  }
-  return bits.filter(Boolean).join(" - ");
-}
-
-function deploymentType(deployment) {
-  return deployment.deploymentType || deployment.type || "";
-}
-
-function sortDeploymentsForChoice(deployments) {
-  return [...deployments].sort((a, b) => {
-    if (!!a.isDefault !== !!b.isDefault) {
-      return a.isDefault ? -1 : 1;
-    }
-    return String(b.createTime || b.createdAt || "").localeCompare(String(a.createTime || a.createdAt || ""));
-  });
-}
-
-async function chooseDeploymentForType(type, deployments) {
-  const matches = sortDeploymentsForChoice(
-    deployments.filter((d) => deploymentType(d) === type && d.status !== "deleted"),
-  );
-  if (matches.length === 0) {
-    return null;
-  }
-  return await choose(
-    `${type} deployments`,
-    matches.map((d) => ({ label: deploymentLabel(d), value: d })),
-  );
-}
+async function main(argv) {
+  // Strip --json from any position so commands see clean positionals.
+  const { json, rest: cleanArgv } = extractJsonFlag(argv);
 
-function parseConvexTarget(args) {
-  let target = null;
-  let index = 0;
-  while (index < args.length) {
-    const arg = args[index];
-    if (arg === "--target") {
-      target = args[index + 1];
-      if (!target) {
-        throw new Error("--target requires dev or prod");
-      }
-      index += 2;
-      continue;
-    }
-    if (arg && arg.startsWith("--target=")) {
-      target = arg.slice("--target=".length);
-      index += 1;
-      continue;
-    }
-    break;
-  }
-  if (target && target !== "dev" && target !== "prod") {
-    throw new Error("--target must be dev or prod");
+  // help / no-args → root help.
+  if (cleanArgv.length === 0 || cleanArgv[0] === "help" || cleanArgv[0] === "-h" || cleanArgv[0] === "--help") {
+    return renderRootHelp(REGISTRY);
   }
-  return {
-    explicitTarget: Boolean(target),
-    target,
-    args: args.slice(index),
-  };
-}
 
-function inferConvexTarget(args) {
-  const command = args.find((arg) => arg && !arg.startsWith("-")) || "";
-  return command === "deploy" ? "prod" : "dev";
-}
-
-function parseConvexInvocation(args) {
-  const parsed = parseConvexTarget(args);
-  return {
-    ...parsed,
-    target: parsed.target || inferConvexTarget(parsed.args),
-  };
-}
-
-async function resolveConvexInvocation(args, { cfg = null, api = null, projectDir = process.cwd() } = {}) {
-  const parsed = parseConvexInvocation(args);
-  const projectConfig = readProjectConfig(projectDir);
-  if (!projectConfig) {
-    if (parsed.explicitTarget) {
-      throw new Error("No Synapse project metadata found. Run `synapse select` first.");
-    }
-    return {
-      ...parsed,
-      credentials: null,
-      deploymentName: "",
-      projectConfig: null,
-      target: null,
-    };
+  const { cmd, rest } = resolve(REGISTRY, cleanArgv);
+  if (!cmd) {
+    process.stderr.write(`Unknown command: ${cleanArgv.join(" ")}\n\nRun \`synapse help\` for the full list.\n`);
+    process.exitCode = 1;
+    return;
   }
 
-  if (!cfg || !api) {
-    throw new Error("Not logged in. Run `synapse login <url>` first.");
-  }
-  if (
-    projectConfig.synapseUrl &&
-    cfg.baseUrl &&
-    normalizeBaseUrl(projectConfig.synapseUrl) !== normalizeBaseUrl(cfg.baseUrl)
-  ) {
-    throw new Error(
-      `This project is linked to ${projectConfig.synapseUrl}, but the saved Synapse session is for ${cfg.baseUrl}. Run \`synapse login ${projectConfig.synapseUrl}\` or \`synapse select\` again.`,
-    );
+  if (wantsHelp(rest)) {
+    return renderCommandHelp(cmd);
   }
 
-  const deploymentName = deploymentNameForTarget(projectConfig, parsed.target);
-  if (!deploymentName) {
-    throw new Error(`No ${parsed.target} deployment saved for this project. Run \`synapse select\` again.`);
-  }
-  const credentials = await api.cliCredentials(deploymentName);
-  return {
-    ...parsed,
-    credentials,
-    deploymentName,
-    projectConfig,
-  };
+  const out = createOutput({ json });
+  const ctx = createContext({ out });
+  return await cmd.run(rest, ctx);
 }
 
-function formatCredentials(creds, format) {
-  switch (format) {
-    case "json":
-      return JSON.stringify(creds, null, 2);
-    case "shell":
-      return creds.exportSnippet;
-    case "env":
-      return creds.envSnippet || `CONVEX_SELF_HOSTED_URL=${quoteEnvValue(creds.convexUrl)}\nCONVEX_SELF_HOSTED_ADMIN_KEY=${quoteEnvValue(creds.adminKey)}`;
-    default:
-      throw new Error("format must be one of: env, shell, json");
-  }
-}
-
-function parseFormat(args) {
-  let format = "env";
-  const rest = [];
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-    if (arg === "--format") {
-      format = args[i + 1];
-      i += 1;
-    } else if (arg.startsWith("--format=")) {
-      format = arg.slice("--format=".length);
-    } else {
-      rest.push(arg);
+if (require.main === module) {
+  main(process.argv.slice(2)).catch((err) => {
+    process.stderr.write(`${err.message}\n`);
+    if (err && err.code === "network_error") {
+      process.stderr.write(
+        "Hint: double-check the URL is reachable from this machine (try `curl <url>/v1/install_status`) and that the Synapse server is running.\n",
+      );
     }
-  }
-  return { format, rest };
-}
-
-async function login(args) {
-  const url = args[0];
-  if (!url) {
-    throw new Error("Usage: synapse login <url>");
-  }
-  const baseUrl = normalizeBaseUrl(url);
-  const { email, password } = await askCredentials();
-  const api = new SynapseAPI({ baseUrl });
-  const session = await api.login(email, password);
-  if (!session.accessToken) {
-    throw new Error("Synapse login response did not include accessToken");
-  }
-  const file = writeConfig({
-    baseUrl,
-    accessToken: session.accessToken,
-    refreshToken: session.refreshToken || null,
-    tokenType: session.tokenType || "Bearer",
-    user: session.user || null,
+    process.exitCode = 1;
   });
-  process.stderr.write(`Saved Synapse session to ${file}\n`);
 }
 
-async function logout() {
-  const removed = clearConfig();
-  process.stderr.write(removed ? "Logged out of Synapse.\n" : "No Synapse session was saved.\n");
-}
+// ---- Legacy exports (test/bin.test.js consumes these) --------------
+//
+// Re-export the helpers the existing tests already import. Adding new
+// commands does NOT add to this list — new code lives in lib/commands/
+// and is tested directly there.
 
-async function whoami() {
-  const { cfg, api } = clientFromConfig();
-  const me = await api.me();
-  const email = me.email || me.user?.email || "(unknown email)";
-  const name = me.name || me.user?.name || "";
-  process.stdout.write(`${name ? `${name} ` : ""}<${email}> on ${cfg.baseUrl}\n`);
-}
+const _convexCmd = require("../lib/commands/convex");
+const _deployCmd = require("../lib/commands/deploy");
+const _devCmd = require("../lib/commands/dev");
+const _credentialsCmd = require("../lib/commands/credentials");
+const _selectCmd = require("../lib/commands/select");
+const _ctxModule = require("../lib/commands/_context");
 
-async function selectDeployment() {
-  const { cfg, api } = clientFromConfig();
-  const teams = await api.teams();
-  const team = await choose("teams", teams.map((t) => ({ label: labelName(t), value: t })));
-  const projects = await api.projects(teamRef(team));
-  const project = await choose("projects", projects.map((p) => ({ label: labelName(p), value: p })));
-  const deployments = await api.deployments(project.id);
-  const dev = await chooseDeploymentForType("dev", deployments);
-  if (!dev) {
-    throw new Error("No dev deployments available in this project. Create one first.");
-  }
-  const prod = await chooseDeploymentForType("prod", deployments);
-  const projectPath = writeProjectConfig(
-    process.cwd(),
-    buildProjectConfig({
-      synapseUrl: cfg.baseUrl,
-      team,
-      project,
-      deployments: { dev, prod },
-    }),
-  );
-  const creds = await api.cliCredentials(dev.name);
-  const envPath = writeProjectEnv(process.cwd(), creds);
-  process.stderr.write(`Linked ${labelName(project)} to ${projectPath}.\n`);
-  process.stderr.write(`Selected dev deployment ${dev.name}. Updated ${envPath}.\n`);
-  if (prod) {
-    process.stderr.write(`Selected prod deployment ${prod.name}.\n`);
-  } else {
-    process.stderr.write("Warning: no prod deployment found. `synapse convex deploy` will require a prod deployment saved by `synapse select`.\n");
-  }
-  if (process.env.CONVEX_DEPLOYMENT) {
-    process.stderr.write("Warning: shell CONVEX_DEPLOYMENT is set. Use `synapse convex ...` or unset it before running `npx convex` directly.\n");
-  }
-}
-
-async function credentials(args) {
-  const { format, rest } = parseFormat(args);
-  const deployment = rest[0];
-  if (!deployment) {
-    throw new Error("Usage: synapse credentials <deployment> [--format env|shell|json]");
-  }
-  if (!["env", "shell", "json"].includes(format)) {
-    throw new Error("format must be one of: env, shell, json");
-  }
-  const { api } = clientFromConfig();
-  const creds = await api.cliCredentials(deployment);
-  process.stdout.write(formatCredentials(creds, format) + "\n");
-}
-
-async function convex(args) {
-  const projectConfig = readProjectConfig(process.cwd());
-  let resolved = {
-    args,
-    credentials: null,
-    deploymentName: "",
-    target: null,
-  };
-  if (projectConfig) {
-    const { cfg, api } = clientFromConfig();
-    resolved = await resolveConvexInvocation(args, { cfg, api });
-    process.stderr.write(`Using Synapse ${resolved.target} deployment ${resolved.deploymentName}.\n`);
-  } else {
-    resolved = await resolveConvexInvocation(args);
-  }
-  const code = await runConvex(resolved.args, { credentials: resolved.credentials });
-  process.exitCode = code;
-}
-
-async function main(argv) {
-  const [command, ...args] = argv;
-  switch (command) {
-    case "login":
-      return await login(args);
-    case "logout":
-      return await logout();
-    case "whoami":
-      return await whoami();
-    case "select":
-      return await selectDeployment();
-    case "credentials":
-      return await credentials(args);
-    case "convex":
-      return await convex(args);
-    case "-h":
-    case "--help":
-    case "help":
-    case undefined:
-      process.stdout.write(usage());
-      return;
-    default:
-      throw new Error(`Unknown command: ${command}\n\n${usage()}`);
-  }
-}
-
-if (require.main === module) {
-  main(process.argv.slice(2)).catch((err) => {
-    process.stderr.write(`${err.message}\n`);
-    process.exitCode = 1;
-  });
+// `clientFromConfig` was the pre-refactor entry point that returned
+// { cfg, api } for any command that needed auth. Kept here as a thin
+// shim around the same underlying helper so test/bin.test.js's
+// "clientFromConfig refreshes an expired access token" still passes.
+function clientFromConfig() {
+  const { requireConfig } = require("../lib/config");
+  const cfg = requireConfig();
+  const api = _ctxModule.makeRefreshableApi(cfg);
+  return { cfg, api };
 }
 
 module.exports = {
-  chooseDeploymentForType,
-  clientFromConfig,
-  formatCredentials,
-  inferConvexTarget,
   main,
-  parseConvexInvocation,
-  parseFormat,
-  resolveConvexInvocation,
+  clientFromConfig,
+  // dev / deploy keep their pre-refactor signatures for test injectors.
+  deploy: _deployCmd.deploy,
+  dev: _devCmd.dev,
+  extractYesFlag: _deployCmd.extractYesFlag,
+  formatCredentials: _credentialsCmd.formatCredentials,
+  parseFormat: _credentialsCmd.parseFormat,
+  // convex command exposes the pure parsers used by tests.
+  inferConvexTarget: _convexCmd.inferConvexTarget,
+  parseConvexInvocation: _convexCmd.parseConvexInvocation,
+  resolveConvexInvocation: _convexCmd.resolveConvexInvocation,
+  // select command's helpers.
+  chooseDeploymentForType: _selectCmd.chooseDeploymentForType,
 };

package/lib/api.js

@@ -75,10 +75,23 @@ class SynapseAPI {
         pageURL.searchParams.set("cursor", cursor);
       }
       const page = await this.request("GET", `${pageURL.pathname}${pageURL.search}`, undefined, { includeHeaders: true });
-      if (!Array.isArray(page.data)) {
-        throw new SynapseAPIError(0, "bad_response", `Expected ${path} to return a JSON array`);
+      // Backend currently returns a bare JSON array for every paginated
+      // endpoint, but the dashboard already tolerates both `[...]` and
+      // `{ <noun>: [...] }` (see `collectPaginated` in dashboard/lib/api.ts).
+      // Mirror that resilience here so a future server-side reshape doesn't
+      // brick `synapse select` for every CLI user simultaneously.
+      const arr = extractListPayload(page.data);
+      if (arr === null) {
+        const shape = page.data && typeof page.data === "object"
+          ? `object with keys [${Object.keys(page.data).join(", ")}]`
+          : typeof page.data;
+        throw new SynapseAPIError(
+          0,
+          "bad_response",
+          `Expected ${path} to return a JSON array (got ${shape})`,
+        );
       }
-      items.push(...page.data);
+      items.push(...arr);
       cursor = page.headers.get("x-next-cursor") || "";
     } while (cursor);
     return items;
@@ -113,7 +126,36 @@ class SynapseAPI {
   }
 }
 
+// Known envelope keys, in priority order. We try these explicitly before
+// falling back to a generic "first array-valued property" lookup so a
+// future endpoint that wraps results in `{ items: [...] }` (or similar)
+// keeps working. The fallback handles the unlikely case of a renamed
+// envelope without crashing the CLI.
+const KNOWN_LIST_KEYS = [
+  "teams",
+  "projects",
+  "deployments",
+  "members",
+  "items",
+  "data",
+  "results",
+];
+
+function extractListPayload(data) {
+  if (Array.isArray(data)) return data;
+  if (data && typeof data === "object") {
+    for (const key of KNOWN_LIST_KEYS) {
+      if (Array.isArray(data[key])) return data[key];
+    }
+    for (const value of Object.values(data)) {
+      if (Array.isArray(value)) return value;
+    }
+  }
+  return null;
+}
+
 module.exports = {
   SynapseAPI,
   SynapseAPIError,
+  extractListPayload,
 };

package/lib/colors.js

@@ -0,0 +1,51 @@
+// Zero-dependency ANSI helpers. Each helper returns its argument as-is when
+// the terminal does not support colour (stdout is not a TTY) or the user
+// opted out via NO_COLOR (https://no-color.org). Checked at call time, not
+// at require time, so tests that toggle `process.env.NO_COLOR` or that run
+// under `node --test` (no TTY) get plain output without further wiring.
+//
+// We deliberately do not depend on `chalk` / `kleur` / etc — the @iann29/
+// synapse package ships zero runtime deps, and a handful of escape codes
+// don't justify breaking that.
+
+function enabled(stream = process.stdout) {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR === "1" || process.env.FORCE_COLOR === "true") return true;
+  return Boolean(stream && stream.isTTY);
+}
+
+function wrap(code) {
+  return (value, stream) =>
+    enabled(stream) ? `\x1b[${code}m${value}\x1b[0m` : String(value);
+}
+
+// Renders the status portion of a deployment row. `running` reads as success,
+// `failed` as error, `provisioning` as in-flight, anything else as dim noise.
+// Falls through to the plain string when colour is off so logs grep cleanly.
+function statusBadge(status, stream) {
+  switch (status) {
+    case "running":
+      return module.exports.green(status, stream);
+    case "failed":
+    case "errored":
+      return module.exports.red(status, stream);
+    case "provisioning":
+      return module.exports.yellow(status, stream);
+    case "stopped":
+    case "deleted":
+      return module.exports.dim(status, stream);
+    default:
+      return String(status || "");
+  }
+}
+
+module.exports = {
+  enabled,
+  bold: wrap("1"),
+  dim: wrap("2"),
+  red: wrap("31"),
+  green: wrap("32"),
+  yellow: wrap("33"),
+  cyan: wrap("36"),
+  statusBadge,
+};