@super-hands/connect 0.1.2 → 0.1.5

package/README.md

@@ -6,9 +6,13 @@ Connect the coding agents on this machine to your team's
 Superhands setup generates the command for you, credential included:
 
 ```
-SUPERHANDS_MCP_TOKEN="…" SUPERHANDS_MCP_URL="…" npx -y @super-hands/connect@latest
+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.
+
 ## What it does
 
 - **Cursor** — merges the `superhands` server into `~/.cursor/mcp.json`.

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_DEFAULT_MCP_URL = "https://app.superhands.ai/api/mcp";
 var CONNECT_CLIENT_PACKAGE = "@super-hands/connect";
 var CONNECT_CLIENT_SPEC = `${CONNECT_CLIENT_PACKAGE}@latest`;
 var MCP_SERVER_KEY = "superhands";
@@ -31,10 +32,58 @@ function codexConfigBlock(args) {
   return [
     `[mcp_servers.${MCP_SERVER_KEY}]`,
     `url = "${args.endpoint}"`,
-    `bearer_token = "${args.token}"`
+    `http_headers = { "Authorization" = "${mcpAuthorizationHeader(args.token)}" }`
   ].join("\n");
 }
 
+// lib/connect-skill.ts
+var CONNECT_SKILL_VERSION = 2;
+var CONNECT_SKILL_DIR = MCP_SERVER_KEY;
+var CONNECT_SKILL_FILENAME = "SKILL.md";
+var VERSION_MARKER = `[//]: # (superhands-skill-version: ${CONNECT_SKILL_VERSION})`;
+var CONNECT_SKILL_DESCRIPTION = `Build UI the way this team has decided it should be built. Use BEFORE building, changing, or restyling any page, screen, view, form, or component \u2014 "build a page", "add a screen", "create a form", "make a dashboard", "redesign this", "new landing page" \u2014 and when asked how this product should look or behave. Reads the team's written product decisions from their Superhands MCP server.`;
+var CONNECT_SKILL_CONTENT = `---
+name: ${CONNECT_SKILL_DIR}
+description: ${CONNECT_SKILL_DESCRIPTION}
+---
+
+${VERSION_MARKER}
+
+# Superhands
+
+This machine is connected to the team's Superhands server over MCP (server
+key \`${MCP_SERVER_KEY}\`). It holds the decisions the team has written down
+about how their product should look and behave \u2014 the same decisions their
+engineers' pull requests are reviewed against.
+
+Before you build, change, or restyle any UI:
+
+1. Call the \`superhands_get_guidance\` MCP tool with \`intent\` set to what
+   you have been asked to build, in plain language \u2014 for example "a sign-in
+   page with email and password and an error state". The decisions that govern
+   that work come back in full, ahead of the rest.
+2. Build to what comes back. Where a decision names a case it deliberately
+   does not govern, your own judgment resumes there.
+3. 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.
+4. When you finish, say you followed the team's guidance \u2014 never that your
+   work passes it or was checked. Reading guidance is not a review, reporting
+   a build is not a review, and nothing has looked at what you built.
+
+If the tool answers \`no-guidance\`, carry on with what you were asked for and
+mention that the team writes its guidance on the Superhands Guidance 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
+machine, so a missing connection is worth telling the person about.
+`;
+function installedSkillVersion(contents) {
+  const match = contents.match(/superhands-skill-version:\s*(\d+)/);
+  return match ? Number.parseInt(match[1], 10) : 0;
+}
+
 // lib/connect-client-entry.ts
 function say(line) {
   process.stdout.write(`superhands: ${line}
@@ -71,12 +120,39 @@ function mergedCursorConfig(existing, args) {
 `, replaced };
 }
 function appendedCodexConfig(existing, args) {
+  const staleOwnBlock = new RegExp(
+    `\\[mcp_servers\\.${MCP_SERVER_KEY}\\]\\nurl = "[^"\\n]*"\\nbearer_token = "[^"\\n]*"`
+  );
+  if (staleOwnBlock.test(existing)) {
+    return {
+      text: existing.replace(staleOwnBlock, codexConfigBlock(args)),
+      alreadyPresent: false,
+      repaired: true
+    };
+  }
   if (existing.includes(`[mcp_servers.${MCP_SERVER_KEY}]`)) {
-    return { text: existing, alreadyPresent: true };
+    return { text: existing, alreadyPresent: true, repaired: false };
   }
   const sep = existing === "" || existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
   return { text: `${existing}${sep}${codexConfigBlock(args)}
-`, alreadyPresent: false };
+`, alreadyPresent: false, repaired: false };
+}
+function writeSkill(clientDir) {
+  const skillPath = join(clientDir, "skills", CONNECT_SKILL_DIR, CONNECT_SKILL_FILENAME);
+  try {
+    let existing = "";
+    try {
+      existing = readFileSync(skillPath, "utf8");
+    } catch {
+      existing = "";
+    }
+    if (existing !== "" && installedSkillVersion(existing) >= CONNECT_SKILL_VERSION) return;
+    mkdirSync(dirname(skillPath), { recursive: true });
+    writeFileSync(skillPath, CONNECT_SKILL_CONTENT);
+    say(`  Wrote the ${CONNECT_SKILL_DIR} skill to ${skillPath} \u2014 it routes UI work through the team's guidance.`);
+  } catch {
+    say(`  Could not write the ${CONNECT_SKILL_DIR} skill at ${skillPath}. The connection works without it.`);
+  }
 }
 function hasCli(bin) {
   try {
@@ -99,10 +175,10 @@ function openCursor() {
 }
 async function main() {
   const token = process.env[CONNECT_TOKEN_ENV]?.trim();
-  const endpoint = process.env[CONNECT_URL_ENV]?.trim();
-  if (!token || !endpoint) {
+  const endpoint = process.env[CONNECT_URL_ENV]?.trim() || CONNECT_DEFAULT_MCP_URL;
+  if (!token) {
     stop(
-      `this command needs ${CONNECT_TOKEN_ENV} and ${CONNECT_URL_ENV} set on the same line. Copy the whole command from Superhands setup and run it unchanged.`
+      `this command needs ${CONNECT_TOKEN_ENV} set on the same line. Copy the whole command from Superhands setup and run it unchanged.`
     );
   }
   const flags = new Set(process.argv.slice(2));
@@ -136,6 +212,7 @@ async function main() {
       } else {
         say(`  Open Cursor (restart it if it was running), then enable ${MCP_SERVER_KEY} under Settings \u2192 MCP.`);
       }
+      writeSkill(cursorDir);
       connected += 1;
     } catch {
       say(`Cursor \u2014 ${configPath} is not valid JSON, so it was left untouched.`);
@@ -169,6 +246,7 @@ async function main() {
       );
       say(`Claude Code \u2014 added the ${MCP_SERVER_KEY} server (user scope).`);
       say("  Open a new claude session and it connects on start.");
+      writeSkill(join(homedir(), ".claude"));
       connected += 1;
     } catch {
       say("Claude Code \u2014 `claude mcp add` failed. Run it by hand from the Superhands MCP page.");
@@ -187,13 +265,17 @@ async function main() {
     const result = appendedCodexConfig(existing, { endpoint, token });
     if (result.alreadyPresent) {
       say(`Codex \u2014 ${configPath} already names a ${MCP_SERVER_KEY} server, so it was left as it is.`);
-      say("  If that connection is stale, update bearer_token there by hand.");
+      say("  If that connection is stale, update the http_headers Authorization value there by hand.");
+      writeSkill(codexDir);
       connected += 1;
     } else {
       mkdirSync(dirname(configPath), { recursive: true });
       writeFileSync(configPath, result.text);
-      say(`Codex \u2014 added the ${MCP_SERVER_KEY} server to ${configPath}.`);
+      say(
+        result.repaired ? `Codex \u2014 replaced the ${MCP_SERVER_KEY} entry in ${configPath}: its old bearer_token spelling makes current Codex reject the whole config.` : `Codex \u2014 added the ${MCP_SERVER_KEY} server to ${configPath}.`
+      );
       say("  The app and the CLI both read this config \u2014 open either and it connects when a session starts.");
+      writeSkill(codexDir);
       connected += 1;
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-hands/connect",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Connect the coding agents on this machine to your team's Superhands MCP server. Writes each client's own config; reads no repository, uploads nothing.",
   "bin": {
     "superhands-connect": "client.mjs"