@super-hands/connect 0.1.9 → 0.1.16

package/README.md

@@ -27,7 +27,27 @@ variable too.
   carries no credential.
 
 With no flags it connects every client it finds; `--cursor`, `--claude` or
-`--codex` narrow it to one.
+`--codex` narrow it to one. Re-running it later to pick up a newer skill needs
+no credential — see `update`, below.
+
+## Updating it
+
+```
+npx -y @super-hands/connect@latest update
+```
+
+Brings the skill on an already-connected machine up to whatever this build
+ships. It takes **no token**: it reads the endpoint and the credential back out
+of the configs the install wrote, so there is nothing to fetch from Superhands
+and nothing new is minted. It touches no MCP entry — the entry is how the
+credential was found, so it is already right.
+
+A client counts as connected when its own config names the `superhands` server;
+anything else is skipped, and a machine with no Superhands entry at all is told
+to install first rather than half-connected. An installed skill at the same
+version or newer is left alone, so your own edits survive an update and the run
+says which files it left as they were. The same `--cursor` / `--claude` /
+`--codex` flags narrow it to one client.
 
 ## Removing it
 
@@ -57,6 +77,6 @@ into the client configs above. The token can be revoked at any time from the
 Superhands MCP page.
 
 This file is generated from
-[`lib/connect-client-entry.ts`](https://github.com/superhandsai/superhandsmcp/blob/main/lib/connect-client-entry.ts)
+[`lib/connect-client-entry.ts`](https://github.com/superhandsai/superhands/blob/main/lib/connect-client-entry.ts)
 in the Superhands repository — the published bytes are that commit's, and are
 not minified.

package/client.mjs

@@ -24,6 +24,7 @@ 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 CONNECT_UPDATE_COMMAND = `npx -y ${CONNECT_CLIENT_SPEC} update`;
 var MCP_SERVER_KEY = "superhands";
 function mcpAuthorizationHeader(token) {
   return `Bearer ${token}`;
@@ -40,11 +41,11 @@ function codexConfigBlock(args) {
 }
 
 // lib/connect-skill.ts
-var CONNECT_SKILL_VERSION = 4;
+var CONNECT_SKILL_VERSION = 11;
 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_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 build-time Instructions from their Superhands MCP server.`;
 var CONNECT_SKILL_CONTENT = `---
 name: ${CONNECT_SKILL_DIR}
 description: ${CONNECT_SKILL_DESCRIPTION}
@@ -55,35 +56,96 @@ ${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.
+key \`${MCP_SERVER_KEY}\`). It holds the team's build-time **Instructions**:
+team-authored decisions, imported procedures, examples and conventions that all
+describe how agents should build in this product. Source labels tell you where
+an instruction came from and how to read it; they are not a choice about which
+half to follow.
 
 Before you build, change, or restyle any UI:
 
-1. Call the \`superhands_get_guidance\` MCP tool with \`intent\` set to what
+1. Call the \`superhands_get_instructions\` 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", and
    \`skill_version: ${CONNECT_SKILL_VERSION}\` \u2014 the version of this file, so
-   the server can tell you when this file is out of date. 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
+   the server can tell you when this file is out of date. The corpus comes
+   back narrowed to that work, with everything not chosen still named.
+   - Pass \`paths\` too, when you already know which files this work touches \u2014
+     the handful you have open or are about to edit, repository-relative, for
+     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
+   started \u2014 those keys are what the next step asks with \u2014 and ends with an
+   index of the modules it did **not** choose, for anything the selection
+   missed. A part of your plan with no keys against it is a real gap in what
+   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
+   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
+   \`better-ui/SKILL#*\` is one file. It runs no selection and makes no model
+   call, so it is a plain, fast lookup and it returns exactly what you named.
+   - **Expect to make this call several times in one task.** A contact form is
+     not one part: it is the form, then its inputs, then its buttons, then its
+     validation errors, then its loading and empty states. One read at the
+     start and nothing after it is the mistake this step exists to prevent.
+   - Fetch each part's modules **when you reach that part**, not all of them at
+     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
+     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:
+     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
    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.
+6. 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-guidance\`, carry on with what you were asked for and
-mention that the team writes its guidance on the Superhands Guidance page.
+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 \`${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.
 
+## Updating Superhands on this machine
+
+If the person asks to update or upgrade Superhands, or if a Superhands tool
+tells you this file is out of date, run:
+
+\`\`\`
+${CONNECT_UPDATE_COMMAND}
+\`\`\`
+
+and tell them what it printed. It reuses the credential already configured on
+this machine, so it needs no token and mints nothing \u2014 it only brings this file
+up to whatever the team's server now expects. Add \`--claude\`, \`--cursor\` or
+\`--codex\` to update one client and leave the rest.
+
+Run it when you are asked, or when you have finished the work in front of you \u2014
+never in the middle of a build. The guidance you were given came from the
+server, not from this file, so it is current either way and there is nothing to
+redo.
+
 ## Removing Superhands from this machine
 
 If the person asks to uninstall, remove, or disconnect Superhands, run:
@@ -171,6 +233,21 @@ function cursorConfigWithoutServer(existing) {
   return { text: `${JSON.stringify(config, null, 2)}
 `, removed: true };
 }
+function cursorNamesServer(existing) {
+  if (!existing || existing.trim() === "") return false;
+  let parsed;
+  try {
+    parsed = JSON.parse(existing);
+  } catch {
+    return false;
+  }
+  const servers = parsed?.mcpServers;
+  if (typeof servers !== "object" || servers === null || Array.isArray(servers)) return false;
+  return MCP_SERVER_KEY in servers;
+}
+function codexNamesServer(existing) {
+  return existing.includes(`[mcp_servers.${MCP_SERVER_KEY}]`);
+}
 function cursorConnection(existing) {
   if (!existing || existing.trim() === "") return null;
   let parsed;
@@ -220,24 +297,30 @@ function appendedCodexConfig(existing, args) {
   return { text: `${existing}${sep}${codexConfigBlock(args)}
 `, alreadyPresent: false, repaired: false };
 }
-function writeSkill(clientDir) {
-  const skillPath = join(clientDir, "skills", CONNECT_SKILL_DIR, CONNECT_SKILL_FILENAME);
-  let existing = "";
+function skillPathIn(clientDir) {
+  return join(clientDir, "skills", CONNECT_SKILL_DIR, CONNECT_SKILL_FILENAME);
+}
+function installedSkillVersionIn(clientDir) {
   try {
-    existing = readFileSync(skillPath, "utf8");
+    return installedSkillVersion(readFileSync(skillPathIn(clientDir), "utf8"));
   } catch {
-    existing = "";
+    return 0;
+  }
+}
+function writeSkill(clientDir) {
+  const skillPath = skillPathIn(clientDir);
+  const existingVersion = installedSkillVersionIn(clientDir);
+  if (existingVersion >= CONNECT_SKILL_VERSION) {
+    return { version: existingVersion, state: "current" };
   }
-  const existingVersion = existing === "" ? 0 : installedSkillVersion(existing);
-  if (existingVersion >= CONNECT_SKILL_VERSION) return existingVersion;
   try {
     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.`);
-    return CONNECT_SKILL_VERSION;
+    return { version: CONNECT_SKILL_VERSION, state: "wrote" };
   } catch {
     say(`  Could not write the ${CONNECT_SKILL_DIR} skill at ${skillPath}. The connection works without it.`);
-    return existingVersion;
+    return { version: existingVersion, state: "blocked" };
   }
 }
 function connectReportUrl(endpoint) {
@@ -310,6 +393,11 @@ function claudeConnection() {
     return null;
   }
 }
+function claudeRegistration() {
+  const result = spawnSync("claude", ["mcp", "get", MCP_SERVER_KEY], { encoding: "utf8" });
+  if (result.error || result.status !== 0) return { registered: false, connection: null };
+  return { registered: true, connection: claudeConnectionFrom(result.stdout ?? "") };
+}
 function hasCli(bin) {
   try {
     execFileSync(bin, ["--version"], { stdio: "ignore" });
@@ -341,8 +429,11 @@ async function main() {
   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 !== "install") {
-    stop(`unknown command "${command}". This tool takes "install" (the default) or "uninstall".`);
+    stop(
+      `unknown command "${command}". This tool takes "install" (the default), "update" or "uninstall".`
+    );
   }
   return install(flags);
 }
@@ -389,7 +480,7 @@ async function install(flags) {
         } else {
           say(`  Open Cursor (restart it if it was running), then enable ${MCP_SERVER_KEY} under Settings \u2192 MCP.`);
         }
-        skillVersions.push(writeSkill(cursorDir));
+        skillVersions.push(writeSkill(cursorDir).version);
         connected += 1;
       } catch {
         say(`Cursor \u2014 ${configPath} could not be written, so it was left as it was.`);
@@ -430,7 +521,7 @@ async function install(flags) {
       );
       say(`Claude Code \u2014 added the ${MCP_SERVER_KEY} server (user scope).`);
       say("  Open a new claude session and it connects on start.");
-      skillVersions.push(writeSkill(join(homedir(), ".claude")));
+      skillVersions.push(writeSkill(join(homedir(), ".claude")).version);
       connected += 1;
     } catch {
       say("Claude Code \u2014 `claude mcp add` failed. Run it by hand from the Superhands MCP page.");
@@ -450,7 +541,7 @@ async function install(flags) {
     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 the http_headers Authorization value there by hand.");
-      skillVersions.push(writeSkill(codexDir));
+      skillVersions.push(writeSkill(codexDir).version);
       connected += 1;
     } else {
       try {
@@ -460,7 +551,7 @@ async function install(flags) {
           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.");
-        skillVersions.push(writeSkill(codexDir));
+        skillVersions.push(writeSkill(codexDir).version);
         connected += 1;
       } catch {
         say(`Codex \u2014 ${configPath} could not be written, so it was left as it was.`);
@@ -483,6 +574,74 @@ async function install(flags) {
   }
   say("Done. Superhands notices the moment an agent connects \u2014 setup ticks by itself.");
 }
+async function update(flags) {
+  const wanted = chosenClients(flags);
+  const cursorDir = join(homedir(), ".cursor");
+  const claudeDir = join(homedir(), ".claude");
+  const codexDir = join(homedir(), ".codex");
+  const found = [];
+  const skillVersions = [];
+  let configured = 0;
+  let rewritten = 0;
+  function refresh(product, clientDir, connection) {
+    configured += 1;
+    if (connection) found.push(connection);
+    const before = installedSkillVersionIn(clientDir);
+    if (before >= CONNECT_SKILL_VERSION) {
+      say(
+        `${product} \u2014 its ${CONNECT_SKILL_DIR} skill is already at version ${before}, so it was left as it is.`
+      );
+    } else if (before === 0) {
+      say(
+        `${product} \u2014 connected, but has no ${CONNECT_SKILL_DIR} skill; writing version ${CONNECT_SKILL_VERSION}.`
+      );
+    } else {
+      say(`${product} \u2014 updating its ${CONNECT_SKILL_DIR} skill from version ${before} to ${CONNECT_SKILL_VERSION}.`);
+    }
+    const result = writeSkill(clientDir);
+    skillVersions.push(result.version);
+    if (result.state === "wrote") rewritten += 1;
+  }
+  if (wanted.cursor) {
+    let text = null;
+    try {
+      text = readFileSync(join(cursorDir, "mcp.json"), "utf8");
+    } catch {
+      text = null;
+    }
+    if (cursorNamesServer(text)) refresh("Cursor", cursorDir, cursorConnection(text));
+  }
+  if (wanted.claude) {
+    const claude = claudeRegistration();
+    if (claude.registered) refresh("Claude Code", claudeDir, claude.connection);
+  }
+  if (wanted.codex) {
+    let text = "";
+    try {
+      text = readFileSync(join(codexDir, "config.toml"), "utf8");
+    } catch {
+      text = "";
+    }
+    if (codexNamesServer(text)) refresh("Codex", codexDir, codexConnection(text));
+  }
+  if (configured === 0) {
+    say(
+      wanted.explicit ? "Nothing to update \u2014 none of the clients you named has a Superhands server configured." : "Nothing to update \u2014 no client on this machine has a Superhands server configured."
+    );
+    say("  Connect one first with the command on the Superhands Agents page; it carries the credential.");
+    return;
+  }
+  const installed = skillVersions.length > 0 ? Math.min(...skillVersions) : 0;
+  if (installed > 0) {
+    const unique = new Map(found.map((c) => [`${c.endpoint}\0${c.token}`, c]));
+    for (const connection of unique.values()) {
+      await reportSkillVersion({ ...connection, version: installed });
+    }
+  }
+  say(
+    rewritten > 0 ? "Done. Open a new session in any client that was already running \u2014 a skill is read when a session starts." : "Done. Everything on this machine was already up to date."
+  );
+}
 async function uninstall(flags) {
   const wanted = chosenClients(flags);
   const cursorDir = join(homedir(), ".cursor");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@super-hands/connect",
-  "version": "0.1.9",
-  "description": "Connect the coding agents on this machine to your team's Superhands MCP server, and take it back off again with `uninstall`. Writes each client's own config; reads no repository, uploads nothing.",
+  "version": "0.1.16",
+  "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"
   },
@@ -16,7 +16,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/superhandsai/superhandsmcp.git",
+    "url": "git+https://github.com/superhandsai/superhands.git",
     "directory": "packages/connect-client"
   },
   "homepage": "https://app.superhands.ai",