@super-hands/connect 0.1.18 → 0.1.20

package/README.md

@@ -21,6 +21,33 @@ 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`.

package/client.mjs

@@ -42,7 +42,7 @@ function codexConfigBlock(args) {
 }
 
 // lib/connect-skill.ts
-var CONNECT_SKILL_VERSION = 12;
+var CONNECT_SKILL_VERSION = 13;
 var CONNECT_SKILL_DIR = MCP_SERVER_KEY;
 var CONNECT_SKILL_FILENAME = "SKILL.md";
 var VERSION_MARKER = `[//]: # (superhands-skill-version: ${CONNECT_SKILL_VERSION})`;
@@ -71,6 +71,10 @@ Before you build, change, or restyle any UI:
    \`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 corpus comes
    back narrowed to that work, with everything not chosen still named.
+   - Keep the instruction activity visible in your working log as terse progress:
+     say "Searching instructions" while this call runs, then replace it with the
+     names selected when the answer arrives. Update that temporary status in
+     place instead of posting a second conclusion.
    - 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
@@ -91,6 +95,8 @@ Before you build, change, or restyle any UI:
    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.
+   - In your working log, say "Checking: [part]", then replace that status with
+     "[module] picked up" when the call returns. Keep it factual and brief.
    - **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
@@ -117,8 +123,15 @@ Before you build, change, or restyle any UI:
 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.
-7. When you finish, say you followed the team's Instructions \u2014 never that your
+   and does not review, so a failed report costs the work nothing. A successful
+   response ends with the run's Instructions receipt; include it once in your
+   final response so the person can see what was handed over up front, picked
+   up during the work, or only named for later. It is context provenance, not
+   proof that anything was applied.
+7. In that final response, state the concrete output change each picked-up
+   Instruction caused. If one caused no change, say so. This is your account of
+   the work, not a Superhands review or verification.
+8. 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.
 
@@ -332,6 +345,12 @@ function connectReportUrl(endpoint) {
 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;
@@ -382,6 +401,36 @@ async function exchangeSetupCode(args) {
     `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), {
@@ -486,15 +535,62 @@ async function main() {
   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, 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, code) {
-  const endpoint = process.env[CONNECT_URL_ENV]?.trim() || CONNECT_DEFAULT_MCP_URL;
+  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.`
@@ -503,9 +599,12 @@ async function install(flags, code) {
   const token = code ? await exchangeSetupCode({ endpoint, code }) : process.env[CONNECT_TOKEN_ENV]?.trim();
   if (!token) {
     stop(
-      `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.`
+      `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.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.",
+  "version": "0.1.20",
+  "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"
   },