@super-hands/connect 0.1.17 → 0.1.19

package/README.md

@@ -3,16 +3,51 @@
 Connect the coding agents on this machine to your team's
 [Superhands](https://app.superhands.ai) MCP server, in one command.
 
-Superhands setup generates the command for you, credential included:
+Superhands generates the command for you, with a short-lived setup code on
+the end of it:
 
 ```
-SUPERHANDS_MCP_TOKEN="…" npx -y @super-hands/connect@latest
+npx -y @super-hands/connect@latest --code shsetup_…
 ```
 
+The client exchanges that code for the credential over one request to your
+deployment and writes the credential into the clients below. The code is
+worth nothing twenty minutes later; the token it becomes never appears in the
+command, the prompt you pasted it from, or your shell history. A command
+written by hand around a token from the Agents page still works:
+`SUPERHANDS_MCP_TOKEN="…" npx -y @super-hands/connect@latest`.
+
 It connects to `https://app.superhands.ai/api/mcp` unless `SUPERHANDS_MCP_URL`
 says otherwise — a command from a preview or local deployment carries that
 variable too.
 
+## Starting without an account
+
+If you have never used Superhands, you do not need a setup code, a browser or
+an account. This command works on its own:
+
+```
+npx -y @super-hands/connect@latest start --claude
+```
+
+It creates a Superhands team for this machine, with the baseline Instructions
+already in it, mints the credential, and writes the configs and the skill just
+as an install does. Nobody owns the team yet: after your agent's first
+Superhands tool call, its reply carries a link you can open to claim the team
+whenever you want it in the app. `--cursor` and `--codex` do the same for those
+clients; with no client flag it connects every client it finds.
+
+Because this makes a team, it refuses to run twice by accident: on a machine
+that already holds a Superhands credential it stops and tells you to use
+`update`, or `install` with a setup code, instead. Pass `--new` if you really
+do want a separate team.
+
+The homepage adds one more thing to this command — `--code shwatch_…`. That is
+a **watch handle**, not a credential and not a setup code. It buys exactly one
+thing: the page you copied the command from can show your agent arriving and
+list its first few calls. The team you get is identical without it, and every
+run carrying the same handle lands on one team rather than making several.
+
 ## What it does
 
 - **Cursor** — merges the `superhands` server into `~/.cursor/mcp.json`.
@@ -71,10 +106,11 @@ remove one client and leave the rest.
 
 ## What it does not do
 
-It reads no repository, runs none of your code, and uploads nothing. The one
-secret it holds is the token in its own environment, and it is written only
-into the client configs above. The token can be revoked at any time from the
-Superhands MCP page.
+It reads no repository, runs none of your code, and uploads nothing but the
+setup code it was given, once, to the deployment that issued it. The one
+secret it then holds is the token that came back, and it is written only into
+the client configs above. The token can be revoked at any time from the
+Superhands Agents page.
 
 This file is generated from
 [`lib/connect-client-entry.ts`](https://github.com/superhandsai/superhands/blob/main/lib/connect-client-entry.ts)

package/client.mjs

@@ -21,6 +21,7 @@ var MCP_ACCESS_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
 // lib/mcp-clients.ts
 var CONNECT_TOKEN_ENV = "SUPERHANDS_MCP_TOKEN";
 var CONNECT_URL_ENV = "SUPERHANDS_MCP_URL";
+var CONNECT_CODE_FLAG = "--code";
 var CONNECT_DEFAULT_MCP_URL = "https://app.superhands.ai/api/mcp";
 var CONNECT_CLIENT_PACKAGE = "@super-hands/connect";
 var CONNECT_CLIENT_SPEC = `${CONNECT_CLIENT_PACKAGE}@latest`;
@@ -328,6 +329,95 @@ function writeSkill(clientDir) {
 function connectReportUrl(endpoint) {
   return `${endpoint.replace(/\/+$/, "")}/connect`;
 }
+function connectExchangeUrl(endpoint) {
+  return `${connectReportUrl(endpoint)}/exchange`;
+}
+function connectStartUrl(endpoint) {
+  return `${connectReportUrl(endpoint)}/start`;
+}
+function appOrigin(endpoint) {
+  return endpoint.replace(/\/api\/mcp\/?$/, "") || endpoint;
+}
+function takeCodeArgument(argv) {
+  const rest = [];
+  let code = null;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === CONNECT_CODE_FLAG) {
+      const next = argv[i + 1];
+      if (next !== void 0 && !next.startsWith("--")) {
+        code = next;
+        i += 1;
+      } else {
+        code = "";
+      }
+      continue;
+    }
+    if (arg.startsWith(`${CONNECT_CODE_FLAG}=`)) {
+      code = arg.slice(CONNECT_CODE_FLAG.length + 1);
+      continue;
+    }
+    rest.push(arg);
+  }
+  return { code, rest };
+}
+async function exchangeSetupCode(args) {
+  let response;
+  try {
+    response = await fetch(connectExchangeUrl(args.endpoint), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ code: args.code }),
+      signal: AbortSignal.timeout(1e4)
+    });
+  } catch {
+    return stop(
+      `Superhands at ${args.endpoint} could not be reached to turn the setup code into a credential. Check the connection and run this command again.`
+    );
+  }
+  const body = await response.json().catch(() => null);
+  if (response.ok && body?.ok && typeof body.token === "string" && body.token) {
+    return body.token;
+  }
+  if (response.status === 401 || response.status === 400) {
+    return stop(
+      "this setup code has expired or has been used up. Get a fresh command from Superhands and run it unchanged."
+    );
+  }
+  return stop(
+    `Superhands answered ${response.status} to the setup code. Try again in a moment, or get a fresh command from Superhands.`
+  );
+}
+async function startTeam(args) {
+  let response;
+  try {
+    response = await fetch(connectStartUrl(args.endpoint), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(args.code ? { code: args.code } : {}),
+      signal: AbortSignal.timeout(1e4)
+    });
+  } catch {
+    return stop(
+      `Superhands at ${args.endpoint} could not be reached. Nothing was created. Check the connection and run this command again.`
+    );
+  }
+  const body = await response.json().catch(() => null);
+  if (response.ok && body?.ok && typeof body.token === "string" && body.token) {
+    return body.token;
+  }
+  if (response.status === 429) {
+    return stop(
+      `Superhands has started too many teams from this network in the last hour. Nothing was created. Try again later, or create an account at ${appOrigin(args.endpoint)} and use the connect command from Setup.`
+    );
+  }
+  if (response.status === 401) {
+    return stop(
+      `that watch code has expired or is not one Superhands issued. Run the same command without ${CONNECT_CODE_FLAG} \u2014 you get the same team, the homepage just will not show it arriving.`
+    );
+  }
+  return stop("Superhands could not start a team just now. Nothing was created \u2014 try again in a moment.");
+}
 async function reportSkillVersion(args) {
   try {
     await fetch(connectReportUrl(args.endpoint), {
@@ -427,26 +517,81 @@ function chosenClients(flags) {
   return explicit ? { cursor, claude, codex, explicit } : { cursor: true, claude: true, codex: true, explicit };
 }
 async function main() {
-  const argv = process.argv.slice(2);
+  const { code, rest: argv } = takeCodeArgument(process.argv.slice(2));
   const flags = new Set(argv.filter((arg) => arg.startsWith("--")));
   const command = argv.find((arg) => !arg.startsWith("--")) ?? "install";
   if (command === "uninstall") return uninstall(flags);
   if (command === "update") return update(flags);
+  if (command === "start") return start(flags, code);
   if (command !== "install") {
     stop(
-      `unknown command "${command}". This tool takes "install" (the default), "update" or "uninstall".`
+      `unknown command "${command}". This tool takes "install" (the default), "start", "update" or "uninstall".`
     );
   }
-  return install(flags);
+  return install(flags, code);
+}
+function chosenEndpoint() {
+  return process.env[CONNECT_URL_ENV]?.trim() || CONNECT_DEFAULT_MCP_URL;
+}
+async function start(flags, code) {
+  const endpoint = chosenEndpoint();
+  if (code === "") {
+    stop(
+      `${CONNECT_CODE_FLAG} needs the watch code after it. Copy the whole command from the Superhands homepage and run it unchanged, or drop ${CONNECT_CODE_FLAG} entirely \u2014 the command works without it.`
+    );
+  }
+  const existing = existingConnections(endpoint);
+  if (!code && existing.length > 0 && !flags.has("--new")) {
+    stop(
+      `this machine is already connected to Superhands at ${endpoint}. Run \`update\` to refresh it, add the client flag to \`install\` with a setup code from your Agents page to connect another client to the same team, or pass --new to start a separate team.`
+    );
+  }
+  const token = await startTeam({ endpoint, code });
+  await connectWithToken(flags, token, endpoint);
+  if (existing.length === 0) {
+    say(
+      "A Superhands team was created for this machine, with the baseline Instructions already in it. Nobody owns it yet: your agent's first answer after calling a Superhands tool carries the link to claim it."
+    );
+  }
+}
+function existingConnections(endpoint) {
+  const found = [];
+  let cursorText = null;
+  try {
+    cursorText = readFileSync(join(homedir(), ".cursor", "mcp.json"), "utf8");
+  } catch {
+    cursorText = null;
+  }
+  const cursor = cursorConnection(cursorText);
+  if (cursor) found.push(cursor);
+  const claude = claudeRegistration().connection;
+  if (claude) found.push(claude);
+  let codexText = "";
+  try {
+    codexText = readFileSync(join(homedir(), ".codex", "config.toml"), "utf8");
+  } catch {
+    codexText = "";
+  }
+  const codex = codexConnection(codexText);
+  if (codex) found.push(codex);
+  return found.filter((connection) => connection.endpoint === endpoint);
 }
-async function install(flags) {
-  const token = process.env[CONNECT_TOKEN_ENV]?.trim();
-  const endpoint = process.env[CONNECT_URL_ENV]?.trim() || CONNECT_DEFAULT_MCP_URL;
+async function install(flags, code) {
+  const endpoint = chosenEndpoint();
+  if (code === "") {
+    stop(
+      `${CONNECT_CODE_FLAG} needs the setup code after it. Copy the whole command from Superhands and run it unchanged.`
+    );
+  }
+  const token = code ? await exchangeSetupCode({ endpoint, code }) : process.env[CONNECT_TOKEN_ENV]?.trim();
   if (!token) {
     stop(
-      `this command needs ${CONNECT_TOKEN_ENV} set on the same line. Copy the whole command from Superhands setup and run it unchanged.`
+      `this command needs a setup code after ${CONNECT_CODE_FLAG}, or ${CONNECT_TOKEN_ENV} set on the same line. Copy the whole command from Superhands and run it unchanged. If you have no Superhands account yet, run \`start\` instead \u2014 it needs nothing.`
     );
   }
+  return connectWithToken(flags, token, endpoint);
+}
+async function connectWithToken(flags, token, endpoint) {
   const wanted = chosenClients(flags);
   let connected = 0;
   let attempted = 0;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@super-hands/connect",
-  "version": "0.1.17",
-  "description": "Connect the coding agents on this machine to your team's Superhands MCP server, refresh it later with `update` (no token needed), and take it back off again with `uninstall`. Writes each client's own config; reads no repository, uploads nothing.",
+  "version": "0.1.19",
+  "description": "Connect the coding agents on this machine to your team's Superhands MCP server — with `start`, from a machine that has no Superhands account at all. Refresh it later with `update` (no token needed), and take it back off again with `uninstall`. Writes each client's own config; reads no repository, uploads nothing.",
   "bin": {
     "superhands-connect": "client.mjs"
   },