@extuitive/skill 0.1.0 → 0.1.1

package/README.md

@@ -45,20 +45,31 @@ Codex — the Codex CLI, the Codex desktop app, and the IDE extension
   Skill       installed      ~/.codex/skills/extuitive
                              /Users/you/.codex/skills/extuitive/SKILL.md
   MCP server  registered     codex mcp add extuitive --url https://www.extuitive.com/mcp
-  Sign-in     needed         codex mcp login extuitive
-                             Opens a browser; only you can complete it.
+  Sign-in     connected      signed in during registration
 
-  The skill is available on your next turn. Codex connects MCP servers when a session
-  starts, so the Extuitive tools appear in a new session once you have signed in.
+  The skill is available on your next turn. You are signed in; the Extuitive tools appear
+  in a new Codex session.
   Try: "Check my Extuitive connection"  ·  "Upload these images to Extuitive"
 ```
 
+On Codex the sign-in is part of the `codex mcp add` step — it opens the person's browser and
+the installer waits for them — so `Sign-in` usually reads `connected` by the time the block
+prints. When the browser flow was closed or ran out of time it reads `needed` instead, with the
+command that finishes it:
+
+```
+  Sign-in     needed         codex mcp login extuitive
+                             codex opened a browser sign-in during registration, but it
+                             was not completed within 10 minutes.
+                             Opens a browser; only you can complete it.
+```
+
 Three facts on three lines, each with its own state, so the summary an agent gives back can be
 short and still true:
 
 > Installed [Extuitive](/Users/you/.codex/skills/extuitive/SKILL.md) in `~/.codex/skills/extuitive`.
 > The skill will be available on your next turn.
-> Sign in with `codex mcp login extuitive`, then start a new session for the Extuitive tools.
+> You are signed in; start a new session for the Extuitive tools.
 > Try: "Check my Extuitive connection."
 
 If you are the agent doing the install, four rules:
@@ -68,6 +79,11 @@ If you are the agent doing the install, four rules:
 - **Report the `Sign-in` line as printed and never run it.** `codex mcp login` opens a browser
   and waits for a redirect your shell cannot receive; `/mcp` belongs to the person's session.
   When it reads `connected`, say so and skip the instruction.
+- **On Codex, expect the install to wait for a browser sign-in.** `codex mcp add` opens the
+  person's browser and does not return until they have signed in, and the installer waits up to
+  ten minutes for that — so tell the person a browser tab is coming and do not kill the command
+  for being slow. If it is cut off anyway, the server is still registered; run
+  `npx extuitive doctor` to see where things stand rather than re-running `install`.
 - **Say what is available when.** The skill is live now (Codex: next turn; Claude Code:
   immediately; Claude Desktop: once uploaded, in new chats). The Extuitive *tools* are not:
   every host connects MCP servers when a session starts, so they appear in a new session, and
@@ -169,9 +185,17 @@ Which does:
 codex mcp add extuitive --url https://www.extuitive.com/mcp
 ```
 
-Then `codex mcp login extuitive` to sign in. The skill itself is picked up on your next turn;
-the Extuitive **tools** appear in a new Codex session, because MCP servers are connected when
-a session starts.
+**The sign-in happens inside that `add`.** Codex writes the config, notices the endpoint
+supports OAuth, and opens your browser on the spot — there is no flag to add without logging
+in. The installer says so before it runs, echoes Codex's output as it goes (including the
+authorize URL, in case no browser opens), and waits up to ten minutes for you to finish: long
+enough to create an Extuitive account and connect Meta on the way. Once you are back in the
+terminal the `Sign-in` line reads `connected`. If the browser flow was closed or timed out,
+the server is still registered — the config was written in the first second — and the line
+reads `needed` with `codex mcp login extuitive` to finish the sign-in on its own.
+
+The skill itself is picked up on your next turn; the Extuitive **tools** appear in a new Codex
+session, because MCP servers are connected when a session starts.
 
 **This is one install for three programs.** The Codex desktop app, the CLI and the IDE
 extension share `~/.codex/config.toml` for MCP and the same skills directories, so there is

package/bin/cli.mjs

@@ -38,9 +38,12 @@ import {
 } from "../src/install.mjs";
 import {
   authInstructions,
+  describeDuration,
   manualSteps,
   registerMcpServer,
+  registrationIncludesSignIn,
   serverAvailabilityNotice,
+  SIGN_IN_TIMEOUT_MS,
   skillAvailabilityNotice,
   unregisterMcpServer,
 } from "../src/mcp-setup.mjs";
@@ -253,6 +256,15 @@ function signInState(host, { registration, server }) {
   if (["skipped_dry_run", "cli_missing", "cli_broken", "failed"].includes(registration.status)) {
     return { state: "after_registration", instruction, inSession: auth.inSession };
   }
+  // What we watched happen outranks what the host's list command says afterwards. Codex
+  // signs in as part of `mcp add`, and its `mcp list` may still say "Unknown" for a token it
+  // wrote a moment ago; a "Successfully logged in." we saw printed is the better witness.
+  if (registration.signIn?.state === "completed") {
+    return { state: "connected", instruction, inSession: auth.inSession, detail: registration.signIn.detail };
+  }
+  if (registration.signIn?.state === "interrupted" || typeof registration.signIn?.detail === "string") {
+    return { state: "needed", instruction, inSession: auth.inSession, detail: registration.signIn.detail };
+  }
   if (server?.state === "connected") {
     return { state: "connected", instruction, inSession: auth.inSession };
   }
@@ -290,6 +302,40 @@ async function placeSkills(host, options) {
   return { ...result, bundle: null };
 }
 
+/**
+ * What to say, and what to echo, while a registration that opens a browser is running.
+ *
+ * Codex's `mcp add --url` writes the config and then opens the person's browser to sign in,
+ * and does not return until they have. That has to be announced *before* it runs — a browser
+ * tab appearing mid-install with no explanation reads as something going wrong — and Codex's
+ * own output has to be shown as it arrives, because it contains the authorize URL for anyone
+ * whose browser did not open, and the "Successfully logged in." that tells them they can
+ * come back to the terminal.
+ *
+ * Nothing is printed in `--json` mode (the output must stay parseable) or in a dry run
+ * (nothing opens), and the announcement is skipped when the CLI is missing, since then
+ * nothing will be run.
+ */
+function registrationProgress(host, options, cliAvailable) {
+  if (
+    registrationIncludesSignIn(host) === false ||
+    options.json === true ||
+    options.dryRun === true ||
+    cliAvailable === false
+  ) {
+    return {};
+  }
+
+  console.log(`\nRegistering the MCP server with ${host.label}.`);
+  console.log(`${host.label} will open your browser to sign in to Extuitive as part of this step.`);
+  console.log("Finish there — create an account and connect Meta if you need to — then come back.");
+  console.log(`Waiting up to ${describeDuration(SIGN_IN_TIMEOUT_MS)} for that. If nothing opens, use the URL ${host.cli} prints below.\n`);
+
+  return {
+    onLine: (line) => console.log(`  ${host.cli} │ ${line}`),
+  };
+}
+
 /**
  * Everything install or update does for one host, returned rather than printed.
  *
@@ -306,6 +352,15 @@ async function setupHost(host, detection, options, { mode }) {
   let server = null;
   let registration;
 
+  const register = () =>
+    registerMcpServer(host, {
+      endpoint: options.endpoint,
+      scope: options.scope,
+      dryRun: options.dryRun,
+      cliAvailable,
+      ...registrationProgress(host, options, cliAvailable),
+    });
+
   if (host.mcpSetup === "connector-ui") {
     // No side effects on either path: registration is a list of steps and the status is
     // "cannot be read from here". Asked the same way in both modes so the summary is too.
@@ -314,22 +369,12 @@ async function setupHost(host, detection, options, { mode }) {
   } else if (mode === "update") {
     server = readHostServerStatus(host, { cliAvailable });
     if (server.state === "absent") {
-      registration = await registerMcpServer(host, {
-        endpoint: options.endpoint,
-        scope: options.scope,
-        dryRun: options.dryRun,
-        cliAvailable,
-      });
+      registration = await register();
     } else {
       registration = { status: server.state === "unknown" ? "unknown" : "already_registered", command: null };
     }
   } else {
-    registration = await registerMcpServer(host, {
-      endpoint: options.endpoint,
-      scope: options.scope,
-      dryRun: options.dryRun,
-      cliAvailable,
-    });
+    registration = await register();
     // Asked even after a fresh registration, because a token from an earlier install may
     // still be in the host's credential store — Codex keeps them in the keychain, keyed by
     // server, and removing the server does not remove the token. Saying "sign in" to someone
@@ -472,11 +517,16 @@ function printServerRow(host, report) {
 function printSignInRow(report) {
   const { signIn } = report;
   if (signIn.state === "connected") {
-    row("Sign-in", "connected", report.server?.detail ?? "");
+    row("Sign-in", "connected", signIn.detail ?? report.server?.detail ?? "");
     return;
   }
   if (signIn.state === "needed") {
     row("Sign-in", "needed", signIn.instruction);
+    if (signIn.detail !== undefined) {
+      // The registration started this sign-in and it did not finish. Said explicitly, since
+      // the person just watched a browser open and may reasonably think it worked.
+      cont(signIn.detail);
+    }
   } else if (signIn.state === "in_app") {
     row("Sign-in", "in the app", signIn.instruction);
   } else if (signIn.state === "after_registration") {
@@ -505,7 +555,7 @@ function printSummary(host, report, options) {
   } else if (report.registration.status === "manual_only") {
     console.log(`  ${report.availability.skill} ${report.availability.server}`);
   } else if (report.signIn.state === "connected") {
-    console.log(`  ${report.availability.skill} The Extuitive tools are connected.`);
+    console.log(`  ${report.availability.skill} You are signed in; the Extuitive tools appear in a new ${host.label} ${host.sessionNoun}.`);
   } else if (serverRegistered === true) {
     console.log(`  ${report.availability.skill} ${report.availability.server}`);
   } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@extuitive/skill",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The Extuitive agent skill and installer for Claude Code, Codex, and Claude Desktop. Run it with `npx extuitive`.",
   "type": "module",
   "license": "MIT",

package/src/exec.mjs

@@ -6,7 +6,7 @@
  * calls, and an argument array cannot be talked into running a second command the way a
  * shell string can.
  */
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 
 /**
@@ -130,6 +130,120 @@ export function run(command, args, options = {}) {
   };
 }
 
+/**
+ * Run a command that a person may be part of, watching its output as it goes.
+ *
+ * `run` is right for commands that finish on their own. This exists for the one that does
+ * not: `codex mcp add --url` writes the config and then opens a browser and waits for the
+ * person to sign in, however long that takes. Buffering that behind `spawnSync` hides the
+ * authorize URL until the command ends, and ending it on a short timeout kills the local
+ * callback listener the browser is about to redirect to — the sign-in the person just
+ * completed fails at the last step, and the installer reports the registration as failed
+ * when the config was written in the first second.
+ *
+ * So output is handed to `onLine` as it arrives, for the caller to echo, and is also
+ * collected so the caller can read what happened afterwards. The timeout is the caller's to
+ * size to the slowest thing inside the command, which here is a person. On timeout the
+ * process gets SIGTERM and, if it ignores that, SIGKILL shortly after.
+ *
+ * Same result shape as `run`, so callers can inspect either the same way.
+ */
+export function runStreaming(command, args, options = {}) {
+  const { timeoutMs = 30_000, onLine = null, env = process.env } = options;
+
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, args, { shell: false, stdio: ["ignore", "pipe", "pipe"], env });
+    } catch (error) {
+      resolve({
+        ok: false,
+        status: null,
+        stdout: "",
+        stderr: String(error.message ?? error),
+        spawnError: true,
+        timedOut: false,
+      });
+      return;
+    }
+
+    let timedOut = false;
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      setTimeout(() => {
+        if (settled === false) {
+          child.kill("SIGKILL");
+        }
+      }, 2_000).unref();
+    }, timeoutMs);
+
+    // Line-buffered per stream so a chunk boundary in the middle of a URL does not hand the
+    // caller half of it.
+    const watch = (stream, stash) => {
+      let pending = "";
+      stream.setEncoding("utf8");
+      stream.on("data", (chunk) => {
+        stash.push(chunk);
+        pending += chunk;
+        let newline = pending.indexOf("\n");
+        while (newline !== -1) {
+          const line = pending.slice(0, newline).replace(/\r$/, "");
+          pending = pending.slice(newline + 1);
+          if (onLine !== null && line.trim() !== "") {
+            onLine(line);
+          }
+          newline = pending.indexOf("\n");
+        }
+      });
+      stream.on("end", () => {
+        if (onLine !== null && pending.trim() !== "") {
+          onLine(pending.replace(/\r$/, ""));
+        }
+      });
+    };
+
+    const outChunks = [];
+    const errChunks = [];
+    watch(child.stdout, outChunks);
+    watch(child.stderr, errChunks);
+
+    const finish = (result) => {
+      if (settled === true) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      resolve({
+        ...result,
+        stdout: outChunks.join(""),
+        stderr: result.stderr ?? errChunks.join(""),
+      });
+    };
+
+    child.on("error", (error) => {
+      finish({
+        ok: false,
+        status: null,
+        stderr: String(error.message ?? error),
+        spawnError: true,
+        timedOut: false,
+      });
+    });
+
+    child.on("close", (status) => {
+      finish({
+        ok: status === 0 && timedOut === false,
+        status,
+        spawnError: false,
+        timedOut,
+      });
+    });
+  });
+}
+
 /** A shell-ready rendering of a command, for printing a step the user has to run by hand. */
 export function formatCommand(command, args) {
   const parts = [command, ...args].map((part) =>

package/src/mcp-setup.mjs

@@ -24,7 +24,32 @@
  * `connectorSteps` for why its config file is left alone even as a fallback.
  */
 import { DEFAULT_MCP_ENDPOINT, MCP_SERVER_NAME, NPX_COMMAND } from "./constants.mjs";
-import { formatCommand, run } from "./exec.mjs";
+import { formatCommand, run, runStreaming } from "./exec.mjs";
+
+/**
+ * How long to wait for a registration that includes a browser sign-in.
+ *
+ * Sized to a person, not a process. Someone signing in for the first time is creating an
+ * Extuitive account, connecting Meta, and picking an ad account before the browser ever
+ * redirects back — a 30-second limit was cut mid-flow and reported "not added" over a
+ * registration that had already been written. Ten minutes is long enough that hitting it
+ * means the tab was closed, and short enough that a closed tab is not an install that never
+ * ends.
+ */
+export const SIGN_IN_TIMEOUT_MS = 10 * 60_000;
+
+/**
+ * Whether registering the server on this host also signs the person in, in the same command.
+ *
+ * True for Codex: `codex mcp add --url` writes the config, discovers that the endpoint
+ * supports OAuth, and starts the login on the spot — it opens a browser and waits for the
+ * redirect. There is no flag to add without logging in. Callers use this to warn before
+ * running that a browser is about to open, and to keep the command running while the person
+ * is in it.
+ */
+export function registrationIncludesSignIn(host) {
+  return host.id === "codex" && host.mcpSetup === "cli";
+}
 
 /**
  * The command that registers the server.
@@ -272,9 +297,24 @@ export function manualConfigSnippet(host, { endpoint = DEFAULT_MCP_ENDPOINT } =
  * `cli_missing` and `cli_broken` are different statuses because they have different fixes:
  * one person has to install the CLI, the other has one that does not run and should be told
  * which file it is.
+ *
+ * On a host where registration includes the sign-in (see `registrationIncludesSignIn`), the
+ * command is run with `onLine` echoing its output as it goes and a timeout sized for a
+ * person, and the result carries a `signIn` field: `completed`, `interrupted` (the browser
+ * flow was started but the command ended before it finished), or `not_started`. The
+ * registration itself is judged by what the CLI printed, not by whether the whole command
+ * exited cleanly — the config is written in the first second, and a sign-in that timed out
+ * or was declined does not unwrite it.
  */
 export async function registerMcpServer(host, options = {}) {
-  const { endpoint = DEFAULT_MCP_ENDPOINT, scope = "user", dryRun = false, cliAvailable } = options;
+  const {
+    endpoint = DEFAULT_MCP_ENDPOINT,
+    scope = "user",
+    dryRun = false,
+    cliAvailable,
+    onLine = null,
+    signInTimeoutMs = SIGN_IN_TIMEOUT_MS,
+  } = options;
 
   // Not a degraded outcome and not a failure — it is how this host is set up, every time.
   // Kept distinct from `cli_missing` so callers can say "here is what to click" instead of
@@ -299,6 +339,10 @@ export async function registerMcpServer(host, options = {}) {
     return { status: "skipped_dry_run", command: rendered };
   }
 
+  if (registrationIncludesSignIn(host) === true) {
+    return registerWithSignIn(host, { command, args, rendered, endpoint, onLine, signInTimeoutMs });
+  }
+
   const timeoutMs = 30_000;
   const result = run(command, args, { timeoutMs });
   if (result.ok === true) {
@@ -319,8 +363,7 @@ export async function registerMcpServer(host, options = {}) {
   // Adding a server that is already configured is a refusal, not a problem: the desired end
   // state is the one we already have. Detected by message because neither CLI gives it a
   // distinct exit code.
-  const output = `${result.stdout}\n${result.stderr}`.toLowerCase();
-  if (output.includes("already exists") === true || output.includes("already configured") === true) {
+  if (saysAlreadyRegistered(result) === true) {
     return { status: "already_registered", command: rendered };
   }
 
@@ -332,6 +375,110 @@ export async function registerMcpServer(host, options = {}) {
   };
 }
 
+function saysAlreadyRegistered(result) {
+  const output = `${result.stdout}\n${result.stderr}`.toLowerCase();
+  return output.includes("already exists") === true || output.includes("already configured") === true;
+}
+
+/**
+ * The phrases Codex prints at each stage of `mcp add --url`, read from its source rather
+ * than guessed. Matched case-insensitively and loosely on purpose: the exact wording is
+ * Codex's to change, and a missed match here degrades to "unverified", not to a wrong claim.
+ */
+const CODEX_ADDED = /added (global )?mcp server/i;
+const CODEX_SIGN_IN_STARTED = /starting oauth flow|open(ing)? this url in your browser/i;
+const CODEX_SIGNED_IN = /successfully logged in/i;
+
+/**
+ * Register on a host whose `add` also runs the browser sign-in.
+ *
+ * Three outcomes have to be told apart, and the exit code alone cannot do it:
+ *
+ * - Exit 0: registered and signed in, in one go.
+ * - Printed "Added" and then timed out, or exited non-zero after starting the sign-in: the
+ *   registration is on disk; the sign-in is what did not finish. That is a *success* for
+ *   the registration and a clear next step for the sign-in, not a failure to be fixed by
+ *   pasting TOML — pasting TOML would produce exactly the state already there.
+ * - Never printed "Added": the add itself failed, and the manual snippet is the right offer.
+ */
+async function registerWithSignIn(host, { command, args, rendered, endpoint, onLine, signInTimeoutMs }) {
+  const result = await runStreaming(command, args, { timeoutMs: signInTimeoutMs, onLine });
+  const output = `${result.stdout}\n${result.stderr}`;
+
+  const added = CODEX_ADDED.test(output) === true;
+  const signInStarted = CODEX_SIGN_IN_STARTED.test(output) === true;
+  const signedIn = CODEX_SIGNED_IN.test(output) === true;
+
+  if (result.ok === true) {
+    return {
+      status: "registered",
+      command: rendered,
+      signIn: signedIn === true
+        ? { state: "completed", detail: "signed in during registration" }
+        : { state: "not_started", detail: null },
+    };
+  }
+
+  if (added === true || (result.timedOut === true && signInStarted === true)) {
+    // The detail names what happened and stops; the caller prints the sign-in command
+    // beside it, so repeating it here would print it twice.
+    const reason = lastLine(result) || `exit ${result.status}`;
+    const detail = result.timedOut === true
+      ? `${host.cli} opened a browser sign-in during registration, but it was not completed within ${describeDuration(signInTimeoutMs)}.`
+      : signInStarted === true
+        ? `${host.cli} opened a browser sign-in during registration, but it did not finish: ${reason}`
+        : `${host.cli} registered the server but then exited early: ${reason}`;
+    return {
+      status: "registered",
+      command: rendered,
+      signIn: { state: signInStarted === true ? "interrupted" : "not_started", detail },
+    };
+  }
+
+  if (saysAlreadyRegistered(result) === true) {
+    return { status: "already_registered", command: rendered, signIn: { state: "not_started", detail: null } };
+  }
+
+  if (result.timedOut === true) {
+    return {
+      status: "failed",
+      command: rendered,
+      detail:
+        `${host.cli} did not finish within ${describeDuration(signInTimeoutMs)} and was stopped. ` +
+        `Run it yourself in a terminal: ${rendered}`,
+      manual: manualConfigSnippet(host, { endpoint }),
+    };
+  }
+
+  return {
+    status: "failed",
+    command: rendered,
+    detail: (result.stderr || result.stdout).trim(),
+    manual: manualConfigSnippet(host, { endpoint }),
+  };
+}
+
+/** A wait, in the unit a person would say it in. */
+export function describeDuration(ms) {
+  if (ms >= 60_000) {
+    const minutes = Math.round(ms / 60_000);
+    return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+  }
+  const seconds = Math.max(1, Math.round(ms / 1000));
+  return `${seconds} second${seconds === 1 ? "" : "s"}`;
+}
+
+/** The last thing the command said, preferring stderr — that is where an error lands. */
+function lastLine(result) {
+  for (const text of [result.stderr, result.stdout]) {
+    const lines = text.split("\n").map((line) => line.trim()).filter(Boolean);
+    if (lines.length > 0) {
+      return lines[lines.length - 1];
+    }
+  }
+  return "";
+}
+
 /**
  * Unregister the server, or explain how to.
  *