@super-hands/connect 0.1.16 → 0.1.18

package/README.md

@@ -3,12 +3,20 @@
 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.
@@ -71,10 +79,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`;
@@ -41,7 +42,7 @@ function codexConfigBlock(args) {
 }
 
 // lib/connect-skill.ts
-var CONNECT_SKILL_VERSION = 11;
+var CONNECT_SKILL_VERSION = 12;
 var CONNECT_SKILL_DIR = MCP_SERVER_KEY;
 var CONNECT_SKILL_FILENAME = "SKILL.md";
 var VERSION_MARKER = `[//]: # (superhands-skill-version: ${CONNECT_SKILL_VERSION})`;
@@ -75,9 +76,6 @@ Before you build, change, or restyle any UI:
      example \`["app/marketing/pricing.tsx"]\`. The team writes down where
      Instructions apply, and a path answers that far better than a description
      does. Leave it out if you do not know yet; it narrows nothing away.
-   - If that tool is not available on this server, it is an older deployment:
-     call \`superhands_get_guidance\` and \`superhands_get_skill\` instead,
-     with the same \`intent\` \u2014 those two are older and take no \`paths\`.
 2. Plan against what comes back, and note which parts of your plan each set of
    keys covers. The first answer renders what to read first, then names
    under **Reachable** the modules judged to matter to parts you have not
@@ -87,7 +85,7 @@ Before you build, change, or restyle any UI:
    the team has written down; say so rather than quietly using your own
    defaults.
 3. As you start each part \u2014 the sidebar, then the table, then the form \u2014 call
-   \`superhands_get_playbook_modules\` with the reachable keys covering the
+   \`superhands_get_instruction_modules\` with the reachable keys covering the
    part you are starting now and \`part\` set to that part in a few words,
    for example \`"the form's validation errors"\`. A key ending in \`*\` takes
    everything under it, so \`better-ui/*\` is a whole skill and
@@ -101,27 +99,32 @@ Before you build, change, or restyle any UI:
      the start. These are instructions to follow, not facts to know, so modules
      for a part you are not building are a page of directions about the wrong
      thing sitting in your context while you work.
-   - Team-authored decision entries from step 1 need no such loop. They are
+   - Review-enforced decision entries from step 1 need no such loop. They are
      concise enough to stay in the opening brief, so one read at the start is
      the right read.
-   - If that tool is not available on this server, it is an older deployment:
+   - If that tool is not available on this server,
      build from what step 1 already returned and skip this step. Do not ask
      for the whole library instead \u2014 that is the wall of text step 1 avoided.
 4. Build to what comes back. Use the selected Instructions together. When two
    entries pull in different directions, prefer the more specific instruction,
    preserve explicit exceptions, and call out any conflict you cannot honestly
    resolve.
-5. When you have finished \u2014 not part-way through \u2014 send the files you wrote or
+5. As your work reaches files your opening intent never mentioned, call
+   \`superhands_possible_misses\` with the \`paths\` you are actually in. It is
+   a free, instant, advisory list of checks those files usually need \u2014 not a
+   review, not a gate \u2014 so call it as the work moves and once before your
+   summary, passing \`handled\` for anything you already covered.
+6. When you have finished \u2014 not part-way through \u2014 send the files you wrote or
    changed with \`superhands_report_completed_build\`, naming the \`route\` if
    you know it. The team looks at what their agents build there; it records
    and does not review, so a failed report costs the work nothing.
-6. When you finish, say you followed the team's Instructions \u2014 never that your
+7. When you finish, say you followed the team's Instructions \u2014 never that your
    work was checked. Reading Instructions is not a check, reporting a build is
    not a review, and nothing has looked at what you built.
 
-If the tool answers \`no-instructions\` (or \`no-guidance\` from an older
-server), carry on with what you were asked for and mention that the team
-adds its Instructions on the Superhands Instructions page.
+If the tool answers \`no-instructions\`, carry on with what you were asked for
+and mention that the team adds its Instructions on the Superhands Instructions
+page.
 
 If the \`${MCP_SERVER_KEY}\` MCP server is not reachable in this session, say
 so rather than guessing at the team's decisions \u2014 it is configured on this
@@ -326,6 +329,59 @@ function writeSkill(clientDir) {
 function connectReportUrl(endpoint) {
   return `${endpoint.replace(/\/+$/, "")}/connect`;
 }
+function connectExchangeUrl(endpoint) {
+  return `${connectReportUrl(endpoint)}/exchange`;
+}
+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 reportSkillVersion(args) {
   try {
     await fetch(connectReportUrl(args.endpoint), {
@@ -425,7 +481,7 @@ 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);
@@ -435,14 +491,19 @@ async function main() {
       `unknown command "${command}". This tool takes "install" (the default), "update" or "uninstall".`
     );
   }
-  return install(flags);
+  return install(flags, code);
 }
-async function install(flags) {
-  const token = process.env[CONNECT_TOKEN_ENV]?.trim();
+async function install(flags, code) {
   const endpoint = process.env[CONNECT_URL_ENV]?.trim() || CONNECT_DEFAULT_MCP_URL;
+  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.`
     );
   }
   const wanted = chosenClients(flags);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-hands/connect",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "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.",
   "bin": {
     "superhands-connect": "client.mjs"