@super-hands/connect 0.1.1 → 0.1.4

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

@@ -10,7 +10,7 @@
 // carries arrived in its own environment. Read on — it is not minified.
 
 // lib/connect-client-entry.ts
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -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";
@@ -35,6 +36,54 @@ function codexConfigBlock(args) {
   ].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}
@@ -78,6 +127,23 @@ function appendedCodexConfig(existing, args) {
   return { text: `${existing}${sep}${codexConfigBlock(args)}
 `, alreadyPresent: 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 {
     execFileSync(bin, ["--version"], { stdio: "ignore" });
@@ -86,12 +152,23 @@ function hasCli(bin) {
     return false;
   }
 }
+function openCursor() {
+  const attempts = process.platform === "darwin" ? [
+    ["cursor", []],
+    ["open", ["-a", "Cursor"]]
+  ] : [["cursor", []]];
+  for (const [bin, args] of attempts) {
+    const result = spawnSync(bin, args, { stdio: "ignore" });
+    if (!result.error && result.status === 0) return true;
+  }
+  return false;
+}
 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));
@@ -118,7 +195,14 @@ async function main() {
       say(
         merged.replaced ? `Cursor \u2014 updated the ${MCP_SERVER_KEY} server in ${configPath}.` : `Cursor \u2014 added the ${MCP_SERVER_KEY} server to ${configPath}.`
       );
-      say("  Restart Cursor, then enable superhands under Settings \u2192 MCP.");
+      if (openCursor()) {
+        say(
+          `  Cursor is opening \u2014 enable ${MCP_SERVER_KEY} under Settings \u2192 MCP. If it was already running, restart it first.`
+        );
+      } 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.`);
@@ -152,6 +236,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.");
@@ -171,12 +256,14 @@ async function main() {
     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.");
+      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("  Start a new codex session and it connects on start.");
+      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.1",
+  "version": "0.1.4",
   "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"