cpyany 0.2.5

package/README.md

@@ -0,0 +1,56 @@
+# cpyany
+
+One-command installer for the PingHumans MCP server.
+
+```bash
+npx cpyany setup
+```
+
+Auto-detects every supported AI client installed on your machine (Claude Code,
+Claude Desktop, Cursor), opens a browser to authorize, and writes the resulting
+bearer token into each client's MCP config from a single OAuth flow. Restart
+the affected clients to load `ping_humans` and `get_ping`.
+
+## Install paths
+
+| Client | MCP config we patch | Rule + skill we install | Auto-detected via |
+|---|---|---|---|
+| Claude Code | runs `claude mcp add --scope user --transport http …` (writes `~/.claude.json`) | `~/.claude/rules/pinghumans.md` + `~/.claude/skills/pinghumans-qa/SKILL.md` | `claude` on `PATH` |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (mac) / `%APPDATA%\Claude\claude_desktop_config.json` (win) — bridged via `mcp-remote` | _(none — Claude Desktop has no rules/skills mechanism)_ | the per-platform Claude config dir exists |
+| Cursor | `~/.cursor/mcp.json` | `~/.cursor/rules/pinghumans.mdc` (`alwaysApply: true`) + `~/.cursor/skills/pinghumans-qa/SKILL.md` | `~/.cursor` exists |
+
+Guidance is two-tier (the same layout Context7 uses): a short always-loaded
+rule telling the agent _when_ to reach for PingHumans, and a `pinghumans-qa`
+skill with the full QA workflow that the agent loads only when it actually
+files or collects a human test. Installs that predate 0.1.0 (which appended a
+marker block to `~/.claude/CLAUDE.md`) are migrated automatically on any CLI
+invocation. `cpyany remove` cleans everything up. The published package
+also keeps `copyanything` and `pinghumans` as legacy binary aliases during
+the rename.
+
+## Restrict to one client
+
+```bash
+npx cpyany setup --client claude-code
+```
+
+`--client` accepts `claude-code`, `claude-desktop`, or `cursor`. Aliases:
+`--claude` (= `--claude-desktop`), `--code` (= `--claude-code`).
+
+## Skip the browser
+
+If you'd rather paste the snippet manually, sign in at
+[pinghumans.com/dashboard](https://pinghumans.com/dashboard) and copy the
+config block from the **MCP integration** section.
+
+## Remove
+
+```bash
+npx cpyany remove          # removes from every detected client
+npx cpyany remove --client claude-desktop   # just one
+```
+
+## License
+
+UNLICENSED — the CLI is published for ease of installation, but the source
+of the PingHumans server is not open-licensed.

package/index.mjs

@@ -0,0 +1,1110 @@
+#!/usr/bin/env node
+// pinghumans — install the PingHumans MCP server in your AI client.
+// One command: shows a one-time code, you approve it in the browser
+// (RFC 8628 device flow), your client configs get patched, you're done.
+
+import { writeFile, readFile, mkdir, stat } from "node:fs/promises";
+import { homedir, platform, hostname, userInfo } from "node:os";
+import { join, dirname } from "node:path";
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import open from "open";
+
+const VERSION = "0.2.5";
+const execFileP = promisify(execFile);
+const APP_URL = process.env.PINGHUMANS_APP_URL ?? "https://pinghumans.com";
+// Hoisted with the other top-of-module consts — the entry try-block runs
+// setup()/refreshStaleRules() via top-level await BEFORE lower const
+// declarations initialize (the 0.0.4 TDZ lesson). validateStoredToken
+// reaches NUDGE_INTERVAL_MS transitively from that path, so it lives here.
+const CLI_CLIENT_ID = "pinghumans-cli";
+const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+const SUPPORTED_CLIENTS = ["claude-desktop", "claude-code", "cursor"];
+// Throttle the passive token-health check to once/day so it neither spams
+// the nudge nor adds a whoami round-trip to every incidental invocation.
+const NUDGE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+// ─── Telemetry ────────────────────────────────────────────────────────────
+//
+// Fire-and-forget POST to /api/cli/telemetry so /admin/usage can see real
+// installs vs npm's bot-heavy download counter. No PII: a stable hash of
+// (hostname + username) is the only identifier sent pre-auth. Honors the
+// DO_NOT_TRACK env var (https://consoledonottrack.com) and a --no-telemetry
+// flag. Never blocks setup, never throws.
+const TELEMETRY_OFF =
+  process.env.DO_NOT_TRACK === "1" ||
+  process.argv.includes("--no-telemetry");
+const ANON_ID = (() => {
+  try {
+    return createHash("sha256")
+      .update(`${hostname()}|${userInfo().username}`)
+      .digest("hex")
+      .slice(0, 16);
+  } catch {
+    return null;
+  }
+})();
+// Capture the bearer once setup completes so subsequent events (remove)
+// can attach to the user server-side. Module-scoped: lives only for this
+// process.
+let _bearerForTelemetry = null;
+
+function track(eventType, extra = {}) {
+  if (TELEMETRY_OFF) return Promise.resolve();
+  const body = {
+    event_type: eventType,
+    cli_version: VERSION,
+    client_os: platform(),
+    node_version: process.version,
+    anon_id: ANON_ID,
+    ...extra,
+  };
+  const headers = { "content-type": "application/json" };
+  if (_bearerForTelemetry) {
+    headers.authorization = `Bearer ${_bearerForTelemetry}`;
+  }
+  // Best-effort: short timeout, swallow every error so telemetry can never
+  // fail a user's `cpyany setup`.
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 3000);
+  return fetch(`${APP_URL}/api/cli/telemetry`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    signal: ctrl.signal,
+  })
+    .catch(() => {})
+    .finally(() => clearTimeout(timer));
+}
+
+// Hoisted to the top of the module so they're initialized before the
+// entry-point `try` block below calls setup() → patchRules(). Function
+// declarations hoist; `const` does not, and 0.0.4 hit a TDZ ReferenceError
+// because these lived alongside their consumer functions further down.
+const RULES_MARKER_START =
+  "<!-- pinghumans-mcp:start (managed by `npx pinghumans` — do not edit) -->";
+const RULES_MARKER_END = "<!-- pinghumans-mcp:end -->";
+
+// Two-tier guidance (Context7-style):
+//   RULE_BODY  — short, always-loaded: WHEN to reach for PingHumans.
+//   SKILL_BODY — full workflow, loaded on demand when the agent does QA.
+const RULE_BODY = `Use the PingHumans MCP to put a real human in the verification loop whenever you build or change something you can't verify yourself — rendered UI, animation smoothness, real-device behavior, real third-party side-effects (OAuth round-trips, receipt emails, payments), or judgment calls about taste, clarity, and confusion. Even when the code looks right: you can't see the page, a human can. Don't caveat with "I'm guessing" — file a test or a poll instead.
+
+Do not use for: anything verifiable with code, tests, or a local browser; objective questions answerable from docs or search.
+
+## Steps
+
+1. Built/changed a UI? Deploy or tunnel it to a PUBLICLY reachable URL (localhost won't work — a remote human opens it), make sure \`<script src="https://pinghumans.com/qa-toolbar.js"></script>\` is in the preview build's HTML, then call \`request_human_test\` with structured \`steps\` — machine-verifiable \`check\` rules plus inline \`options\` (e.g. \`["Smooth","Janky"]\`) for qualitative steps
+2. Quick taste/preference read with no build to test? Call \`ping_humans\` (blocks ~50s)
+3. File tests early and keep working while the human tests — collect results with \`get_test_results\` at checkpoints, \`wait_for_results\` when blocked, or \`npx cpyany wait <ping_id>\` as a background task (foreground in one-shot runs)
+4. When results arrive, treat the human's verdict/comments as acceptance criteria. Use browser/Chrome checks to implement and confirm those criteria, not to overrule the worker.
+5. For the full QA workflow (verifiable steps, evidence, waiting modes, acting on results), use the pinghumans-qa skill
+`;
+
+const SKILL_BODY = `---
+name: pinghumans-qa
+description: This skill should be used when the user has built or changed a UI and wants it verified by a real human, asks for human QA / human testing / human feedback on a build, or wants to check the results of a previously filed human test. Also activates for subjective gut-checks (taste, copy, design preference) via PingHumans.
+---
+
+When you've built or changed something you can't verify yourself, use PingHumans to have a real human test it and return structured results — a verdict, pinned component comments with CSS selectors, a per-step proof-of-work report, and screenshots you can open.
+
+## When to Use This Skill
+
+- You shipped a UI change and can't see the rendered result ("does this look right on a real phone?", "is this animation smooth or janky?")
+- The check needs real-world reach a sandbox doesn't have ("sign in with Google — did it actually log you in?", "did the test purchase email a receipt?")
+- Sense-making ("complete the checkout — anything confusing or broken?")
+- A previously filed test needs its results collected
+- A quick subjective read with no build to test ("which logo looks more professional?") — use \`ping_humans\` for these
+
+## How to File a Test
+
+### Step 1: Make the build reachable and instrumented
+
+The \`url\` must be PUBLICLY reachable — a remote human opens it, so localhost won't work: tunnel it first (ngrok, cloudflared) or deploy a preview. The toolbar script is REQUIRED for pinned comments and step auto-verification — one line, once per project, in the preview build's HTML (root layout / index template), preview/dev only:
+
+\`\`\`html
+<script src="https://pinghumans.com/qa-toolbar.js"></script>
+\`\`\`
+
+No per-task id needed — the tester's claim link carries the task token. \`request_human_test\`'s result reports whether the script was detected (\`toolbar_detected\`) — if it warns, fix the build and redeploy before testers arrive.
+
+### Step 2: File with verifiable steps
+
+Call \`request_human_test\` with a \`url\`, structured \`steps\`, and optional \`verdict_options\` / \`require_evidence\`. You wrote the code, so you know what "done" looks like — attach a \`check\` rule to every step you can:
+
+- \`{type:"url", pattern:"/pricing"}\` — tester actually navigated there
+- \`{type:"click", selector:".checkout button"}\` — tester actually clicked it
+- \`{type:"fill", selector:"input[type=email]"}\` — tester actually typed
+- \`{type:"comment"}\` — tester pinned at least one comment
+
+The toolbar observes the page and auto-verifies them; results report each step as ✓ auto (machine-verified), ✓ manual, or ✗ not done — your proof the tester did the work. Leave \`check\` null only for pure-judgment steps.
+
+When a step asks a question rather than performs an action, add \`options\` (2–4 short labels, e.g. \`{text:"Scroll the homepage — smooth or janky?", options:["Smooth","Janky"]}\`): the tester answers with one tap right on the step and the pick comes back in \`steps_result[].answer\` — far richer than a bare checkmark. A step with a \`selector\` in its check also gets highlighted on the page for the tester, so prefer real selectors.
+
+### Step 3: Wait the right way
+
+The call does NOT block (QA takes minutes) — it returns \`status='pending'\` immediately. In order of preference:
+
+1. **File early, keep working.** The human tests in parallel — their time is free to you.
+2. **Interactive session with background shell tasks:** launch \`npx cpyany wait <ping_id>\` in the background — it exits the moment results land, waking you with the results.
+3. **One-shot run (subagent / final answer due this run):** do NOT end your run while results are pending — nothing can wake you afterwards, and a backgrounded waiter dies with you. Run \`npx cpyany wait <ping_id>\` in the FOREGROUND, or call \`wait_for_results(ping_id)\` in a loop until complete.
+4. **Checkpoint checks:** \`get_test_results(ping_id)\` at natural pauses.
+5. **Genuinely blocked:** \`wait_for_results(ping_id)\` blocks server-side (~45s per call, free) and returns early on news. Never hand-roll sleep loops.
+
+### Step 4: Act on the results
+
+Each result has a verdict, notes, pinned comments, per-step truth, and a screenshot URL — open and look at it. Comments carry CSS selectors that point at the exact component to change. Treat the human's verdict/comments as acceptance criteria, not suggestions. Browser, Chrome, screenshots, source checks, and getComputedStyle are implementation aids: use them to satisfy and confirm the worker's requested changes, never to decide the worker was wrong.
+
+**Clone-compare tasks** (filed with both \`url\` = the original and \`draft_url\` = your clone): before you touch the clone, call \`check_og_source(ping_id)\`. It reads the ORIGINAL's authored HTML source for exactly the elements a human flagged and diffs each against your clone. The worker's alignment feedback is the acceptance criteria: modify HTML/CSS so every requested move/match/delete is met with reasonable visual accuracy. Allow small manual error in hand-placed move/align markers, but preserve the worker's intended direction and target. Use the returned authored classes to implement the feedback; only fall back to measuring/live inspection for pairs marked \`needs_live_inspection\`, and only to satisfy the human request, not to replace it with your own visual judgment.
+
+## Guidelines
+
+- **Pricing**: ~$0.05 per response received; filing is free, results are charged
+- **Quick polls**: \`ping_humans\` for taste questions blocks ~50s; poll \`get_ping(ping_id)\` for late arrivals
+- **Pending isn't dead**: "a tester has claimed the task and is testing right now" means results are imminent — keep waiting
+`;
+
+// ─── Entry ────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+try {
+  if (cmd === "setup") {
+    await setup(parseClient(args.slice(1)));
+  } else if (cmd === "remove" || cmd === "uninstall") {
+    await remove(parseClient(args.slice(1)));
+  } else if (cmd === "wait") {
+    await waitForResultsCli(args.slice(1));
+  } else if (cmd === "whoami") {
+    await whoamiCli();
+  } else if (cmd === "rules") {
+    await refreshStaleRules({ verbose: true });
+  } else if (cmd === "version" || cmd === "--version" || cmd === "-v") {
+    console.log(VERSION);
+    track("version");
+    await refreshStaleRules().catch(() => {});
+  } else {
+    // Even a bare/unknown invocation heals stale rules — `npx cpyany`
+    // always runs the newest package, so this is the "auto-update on
+    // package update" path.
+    await refreshStaleRules().catch(() => {});
+    printHelp();
+    process.exit(cmd ? 1 : 0);
+  }
+} catch (err) {
+  if (cmd === "setup") {
+    await track("setup_failed", {
+      failure_reason: String(err?.message ?? err).slice(0, 500),
+    });
+  }
+  console.error(`\n✗ ${err.message}\n`);
+  process.exit(1);
+}
+
+// ─── Commands ─────────────────────────────────────────────────────────────
+
+async function setup(client) {
+  track("setup_start", { client_label: client ?? null });
+  if (!TELEMETRY_OFF) {
+    console.log(
+      "(anonymous usage stats — opt out with DO_NOT_TRACK=1 or --no-telemetry)"
+    );
+  }
+  // Resolve targets: explicit --client X wins; otherwise detect what's
+  // installed and (Context7-style) let the user multi-select, defaulting to
+  // everything. Non-interactive shells skip the prompt and take all.
+  let targets;
+  if (client) {
+    targets = [client];
+  } else {
+    const detected = await detectClients();
+    if (detected.length === 0) {
+      throw new Error(
+        "Couldn't find Claude Code, Claude Desktop, or Cursor on this machine. " +
+          "Install one of them first, or pass --client to specify manually."
+      );
+    }
+    if (detected.length > 1 && process.stdin.isTTY && process.stdout.isTTY) {
+      const { checkbox } = await import("@inquirer/prompts");
+      targets = await checkbox({
+        message: "Which agents do you want to set up?",
+        choices: detected.map((c) => ({
+          name: prettyClient(c),
+          value: c,
+          checked: true,
+        })),
+        validate: (sel) => sel.length > 0 || "Pick at least one agent.",
+      });
+    } else {
+      targets = detected;
+      console.log(`Detected ${targets.map(prettyClient).join(", ")}.`);
+    }
+  }
+
+  // One device-code sign-in regardless of how many configs we'll patch
+  // (RFC 8628 — works over SSH too, no localhost listener needed).
+  const token = await performDeviceLogin();
+  if (!token) process.exit(1);
+  _bearerForTelemetry = token;
+  const pc0 = await import("picocolors").then((m) => m.default);
+  console.log(`${pc0.green("✔")} Authenticated`);
+  await saveLocalToken(token); // lets `cpyany wait`/`whoami` authenticate later
+
+  // Install everything, then print a Context7-style per-client summary.
+  const pc = await import("picocolors").then((m) => m.default);
+  const summary = [];
+  let desktopDetected = false;
+  for (const t of targets) {
+    // Claude Desktop can't use a remote MCP server from its config file, so we
+    // do NOT write the old `npx mcp-remote` bridge (the brittle path: plaintext
+    // token in args + an OAuth race when the token dies). Desktop gets the
+    // one-click extension or the native OAuth connector instead — point there.
+    if (t === "claude-desktop") {
+      desktopDetected = true;
+      continue;
+    }
+    await patchConfig(t, token);
+    const entries = [
+      {
+        label: "MCP server configured with Bearer token",
+        path:
+          t === "claude-code"
+            ? join(homedir(), ".claude.json")
+            : configPath(t),
+      },
+      ...(await patchRules(t)),
+    ];
+    summary.push({ client: t, entries });
+    track("setup_complete", { client_label: t });
+  }
+
+  console.log(`\n${pc.green("✔")} PingHumans setup complete\n`);
+  for (const { client: c, entries } of summary) {
+    console.log(`  ${pc.bold(prettyClient(c))}`);
+    for (const e of entries) {
+      console.log(`    ${pc.green("+")} ${e.label}`);
+      console.log(`      ${pc.dim(e.path)}`);
+    }
+  }
+
+  if (desktopDetected) {
+    console.log(`  ${pc.bold("Claude Desktop")}`);
+    console.log(
+      `    ${pc.dim("Desktop uses a one-click extension or a connector, not a config file.")}`
+    );
+    console.log(`    Set it up here:  ${pc.cyan(`${APP_URL}/connect`)}`);
+  }
+
+  const restartList = summary.map((s) => prettyClient(s.client)).join(" / ");
+  if (restartList) {
+    console.log(`\nRestart ${restartList} to load the MCP server.`);
+  }
+  console.log(`Try it: ask your agent to "use ping_humans to ask if pizza is cooler than tacos."`);
+}
+
+async function remove(client) {
+  // If --client given, remove only from that one. Else remove from every
+  // detected client (matches the setup command's auto-multi behavior).
+  let targets;
+  if (client) {
+    targets = [client];
+  } else {
+    targets = await detectClients();
+    if (targets.length === 0) {
+      console.log("Nothing to remove — no supported AI clients detected.");
+      return;
+    }
+  }
+  for (const t of targets) {
+    await unpatchConfig(t);
+    console.log(`✓ Removed pinghumans from ${prettyClient(t)} config.`);
+    await unpatchRules(t);
+    track("remove", { client_label: t });
+  }
+  // Full removal (no --client) also signs this machine out.
+  if (!client) {
+    const { unlink } = await import("node:fs/promises");
+    await unlink(credsPath()).catch(() => {});
+  }
+}
+
+// ─── Client detection ─────────────────────────────────────────────────────
+
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isOnPath(cmd) {
+  const which = platform() === "win32" ? "where" : "which";
+  try {
+    await execFileP(which, [cmd]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Quick, low-fidelity check for which AI clients are installed locally.
+ * Returns a subset of SUPPORTED_CLIENTS in install-order preference.
+ *
+ * Detection rules (deliberately loose — better to surface a client we'll
+ * ask the user about than to skip a real install):
+ *   - claude-code: `claude` binary on PATH
+ *   - claude-desktop: the per-platform config directory exists (created on
+ *     first launch; absent if the app was never opened)
+ *   - cursor: ~/.cursor exists
+ */
+async function detectClients() {
+  const home = homedir();
+  const isMac = platform() === "darwin";
+  const isWin = platform() === "win32";
+
+  const [hasClaudeCode, hasClaudeDesktop, hasCursor] = await Promise.all([
+    isOnPath("claude"),
+    pathExists(
+      isMac
+        ? join(home, "Library", "Application Support", "Claude")
+        : isWin
+          ? join(process.env.APPDATA || join(home, "AppData", "Roaming"), "Claude")
+          : join(home, ".config", "Claude")
+    ),
+    pathExists(join(home, ".cursor")),
+  ]);
+
+  const out = [];
+  if (hasClaudeCode) out.push("claude-code");
+  if (hasClaudeDesktop) out.push("claude-desktop");
+  if (hasCursor) out.push("cursor");
+  return out;
+}
+
+// ─── Device-code sign-in (RFC 8628) ──────────────────────────────────────
+//
+// The CLI mints a short code, the user approves at /oauth/device in any
+// signed-in browser (works over SSH — no localhost listener), and we poll
+// until the approval delivers a bearer. Flow and presentation mirror the
+// Context7 CLI.
+
+async function startDeviceAuthorization() {
+  const params = new URLSearchParams({ client_id: CLI_CLIENT_ID });
+  try {
+    // Shown on the approval page so the user can confirm which machine is
+    // asking (RFC 8628 §5.4 phishing resistance). Best-effort.
+    const h = hostname();
+    if (h) params.set("hostname", h);
+  } catch {}
+  const res = await fetch(`${APP_URL}/api/oauth/device/code`, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: params.toString(),
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err.error_description || err.error || "Failed to start sign-in.");
+  }
+  return res.json();
+}
+
+async function pollDeviceToken(deviceCode) {
+  let res;
+  try {
+    res = await fetch(`${APP_URL}/api/oauth/device/token`, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: DEVICE_CODE_GRANT,
+        device_code: deviceCode,
+        client_id: CLI_CLIENT_ID,
+      }).toString(),
+    });
+  } catch {
+    return { status: "transient" }; // network blip — keep polling
+  }
+  if (res.ok) {
+    const tokens = await res.json();
+    return { status: "approved", token: tokens.access_token };
+  }
+  if (res.status >= 500) return { status: "transient" };
+  const err = await res.json().catch(() => ({}));
+  switch (err.error) {
+    case "authorization_pending":
+      return { status: "pending" };
+    case "slow_down":
+      return { status: "slow_down" };
+    case "access_denied":
+      return { status: "denied" };
+    case "expired_token":
+      return { status: "expired" };
+    default:
+      throw new Error(err.error_description || err.error || "Sign-in poll failed.");
+  }
+}
+
+/** Prints a prompt and resolves on the next keypress. No-op when stdin isn't a TTY. */
+function waitForEnter(prompt) {
+  if (!process.stdin.isTTY) return Promise.resolve();
+  return new Promise((resolve) => {
+    process.stdout.write(`  ${prompt} `);
+    const onData = (chunk) => {
+      process.stdin.removeListener("data", onData);
+      process.stdin.setRawMode?.(false);
+      process.stdin.pause();
+      process.stdout.write("\n");
+      if (chunk[0] === 0x03) process.exit(130); // Ctrl-C
+      resolve();
+    };
+    process.stdin.setRawMode?.(true);
+    process.stdin.resume();
+    process.stdin.on("data", onData);
+  });
+}
+
+async function fetchWhoami(token) {
+  const res = await fetch(`${APP_URL}/api/cli/whoami`, {
+    headers: { authorization: `Bearer ${token}` },
+  });
+  if (!res.ok) throw new Error("whoami failed");
+  return res.json();
+}
+
+async function performDeviceLogin() {
+  const [pc, { default: boxen }, { default: ora }] = await Promise.all([
+    import("picocolors").then((m) => m.default),
+    import("boxen"),
+    import("ora"),
+  ]);
+
+  let authorization;
+  try {
+    authorization = await startDeviceAuthorization();
+  } catch (err) {
+    console.error(pc.red(`✗ ${err.message}`));
+    return null;
+  }
+
+  const codeLine = `${pc.dim("Your one-time code:")}\n\n    ${pc.green(pc.bold(authorization.user_code))}`;
+  const linkLine = `${pc.dim("Open this link to approve:")}\n${pc.cyan(authorization.verification_uri_complete)}\n\n${pc.dim("Or visit")} ${pc.cyan(authorization.verification_uri)} ${pc.dim("and enter the code above.")}`;
+  console.log(
+    boxen(`${codeLine}\n\n${linkLine}`, {
+      title: "Sign in to PingHumans",
+      titleAlignment: "left",
+      padding: 1,
+      margin: { top: 1, bottom: 1, left: 2, right: 2 },
+      borderStyle: "round",
+      borderColor: "gray",
+    })
+  );
+
+  await waitForEnter(pc.dim("Press Enter to open the browser, or Ctrl-C to quit..."));
+  try {
+    await open(authorization.verification_uri_complete);
+  } catch {
+    console.log(pc.dim("  Couldn't open a browser — visit the link above manually."));
+  }
+
+  const spinner = ora({ text: "Waiting for authorization...", indent: 2 }).start();
+  const deadline = Date.now() + authorization.expires_in * 1000;
+  let intervalMs = (authorization.interval ?? 5) * 1000;
+
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, intervalMs));
+    let result;
+    try {
+      result = await pollDeviceToken(authorization.device_code);
+    } catch (err) {
+      spinner.fail(pc.red("Sign-in failed"));
+      console.error(pc.red(err.message));
+      return null;
+    }
+    if (result.status === "approved") {
+      let successText = "Login successful!";
+      try {
+        const who = await fetchWhoami(result.token);
+        const name = who.email || who.name;
+        if (name) successText = `Logged in as ${pc.bold(name)}`;
+      } catch {}
+      spinner.succeed(pc.green(successText));
+      return result.token;
+    }
+    if (result.status === "denied") {
+      spinner.fail(pc.red("Authorization denied."));
+      return null;
+    }
+    if (result.status === "expired") {
+      spinner.fail(pc.red("Code expired. Run setup again."));
+      return null;
+    }
+    // slow_down / transient: RFC 8628 §3.5 — back off 5s. pending: keep cadence.
+    if (result.status === "slow_down" || result.status === "transient") {
+      intervalMs += 5000;
+    }
+  }
+  spinner.fail(pc.red("Code expired without approval."));
+  return null;
+}
+
+// ─── Client config patching ───────────────────────────────────────────────
+
+function configPath(client) {
+  const home = homedir();
+  const isMac = platform() === "darwin";
+  const isWin = platform() === "win32";
+  switch (client) {
+    case "claude-desktop": {
+      if (isMac) {
+        return join(
+          home,
+          "Library",
+          "Application Support",
+          "Claude",
+          "claude_desktop_config.json"
+        );
+      }
+      if (isWin) {
+        return join(
+          process.env.APPDATA || join(home, "AppData", "Roaming"),
+          "Claude",
+          "claude_desktop_config.json"
+        );
+      }
+      return join(home, ".config", "Claude", "claude_desktop_config.json");
+    }
+    case "cursor":
+      return join(home, ".cursor", "mcp.json");
+    case "claude-code":
+      return null; // managed via `claude mcp add`
+    default:
+      throw new Error(`Unknown client: ${client}`);
+  }
+}
+
+async function patchConfig(client, token) {
+  if (client === "claude-code") {
+    return patchClaudeCodeViaCli(token);
+  }
+  const path = configPath(client);
+  await mkdir(dirname(path), { recursive: true });
+  let config = {};
+  try {
+    const text = await readFile(path, "utf8");
+    config = JSON.parse(text);
+  } catch {
+    /* missing or empty */
+  }
+  if (!config.mcpServers || typeof config.mcpServers !== "object") {
+    config.mcpServers = {};
+  }
+
+  if (client === "claude-desktop") {
+    // Claude Desktop doesn't natively support Streamable HTTP MCP servers
+    // (only stdio). Bridge via the community mcp-remote package, which spawns
+    // a stdio server that proxies to our hosted HTTP MCP.
+    config.mcpServers.pinghumans = {
+      command: "npx",
+      args: [
+        "-y",
+        "mcp-remote",
+        `${APP_URL}/api/mcp`,
+        "--header",
+        `Authorization: Bearer ${token}`,
+      ],
+    };
+  } else {
+    // Cursor + others: native streamable-HTTP works.
+    config.mcpServers.pinghumans = {
+      url: `${APP_URL}/api/mcp`,
+      headers: { Authorization: `Bearer ${token}` },
+    };
+  }
+
+  await writeFile(path, JSON.stringify(config, null, 2) + "\n");
+}
+
+async function unpatchConfig(client) {
+  if (client === "claude-code") {
+    try {
+      await execFileP("claude", ["mcp", "remove", "pinghumans", "--scope", "user"]);
+    } catch (err) {
+      console.error(`Couldn't run \`claude mcp remove\`: ${err.message}`);
+    }
+    return;
+  }
+  const path = configPath(client);
+  try {
+    const text = await readFile(path, "utf8");
+    const config = JSON.parse(text);
+    if (config?.mcpServers?.pinghumans) {
+      delete config.mcpServers.pinghumans;
+      await writeFile(path, JSON.stringify(config, null, 2) + "\n");
+    }
+  } catch {
+    /* nothing to remove */
+  }
+}
+
+// ─── Agent rules ──────────────────────────────────────────────────────────
+//
+// In addition to MCP tool descriptions, we install a short prose "rule"
+// telling the agent WHEN to reach for ping_humans. Tool descriptions only
+// fire during tool selection; rules sit in the agent's persistent
+// instructions and bias it toward the tool earlier in reasoning.
+//
+// Per-client landing spots:
+//   - Claude Code → ~/.claude/CLAUDE.md (the canonical user-memory file
+//     Claude Code auto-loads at session start). Marker tags so re-install
+//     and remove are clean even if the user hand-edits the file.
+//   - Cursor → ~/.cursor/rules/pinghumans.mdc (Cursor's auto-loaded
+//     rules dir, with `alwaysApply: true` frontmatter).
+//   - Claude Desktop → no equivalent; skipped.
+//
+// (RULES_MARKER_START / RULES_MARKER_END / RULES_BODY constants are
+// declared near the top of the module — they're consumed indirectly via
+// the entry-point try block, which runs before this section is even
+// parsed in module-execution order.)
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function stripMarkerBlock(text) {
+  const re = new RegExp(
+    `\\n*${escapeRegExp(RULES_MARKER_START)}[\\s\\S]*?${escapeRegExp(RULES_MARKER_END)}\\n*`,
+    "g"
+  );
+  return text.replace(re, "\n").trimStart();
+}
+
+// Where each client's rule + skill live. Claude Desktop has neither
+// mechanism, so it gets MCP config only.
+function rulePath(client) {
+  if (client === "claude-code")
+    return join(homedir(), ".claude", "rules", "pinghumans.md");
+  if (client === "cursor")
+    return join(homedir(), ".cursor", "rules", "pinghumans.mdc");
+  return null;
+}
+
+function skillPath(client) {
+  if (client === "claude-code")
+    return join(homedir(), ".claude", "skills", "pinghumans-qa", "SKILL.md");
+  if (client === "cursor")
+    return join(homedir(), ".cursor", "skills", "pinghumans-qa", "SKILL.md");
+  return null;
+}
+
+function ruleContent(client) {
+  // Cursor's rules dir requires frontmatter; Claude Code's takes plain md.
+  if (client === "cursor") return "---\nalwaysApply: true\n---\n\n" + RULE_BODY;
+  return RULE_BODY;
+}
+
+// Installs/refreshes the rule + skill for a client. Returns
+// [{label, path}, ...] for the setup summary. Also migrates pre-0.1.0
+// installs by stripping our legacy managed block out of ~/.claude/CLAUDE.md
+// — the agent guidance lives in its own files now, not the user's memory.
+async function patchRules(client) {
+  const installed = [];
+  const rp = rulePath(client);
+  if (!rp) return installed;
+
+  if (client === "claude-code") await stripLegacyClaudeMdBlock();
+
+  await mkdir(dirname(rp), { recursive: true });
+  await writeFile(rp, ruleContent(client));
+  installed.push({ label: "Rule installed", path: rp });
+
+  const sp = skillPath(client);
+  await mkdir(dirname(sp), { recursive: true });
+  await writeFile(sp, SKILL_BODY);
+  installed.push({ label: "Skill installed", path: sp });
+
+  return installed;
+}
+
+async function stripLegacyClaudeMdBlock() {
+  const path = join(homedir(), ".claude", "CLAUDE.md");
+  try {
+    const text = await readFile(path, "utf8");
+    if (!text.includes(RULES_MARKER_START)) return false;
+    const next = stripMarkerBlock(text);
+    await writeFile(path, next.trim().length === 0 ? "" : next);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Stale-rules self-healing ───────────────────────────────────────────────
+//
+// The rules text evolves with the product, but installs only rewrote it on
+// `setup`. Now ANY invocation of the CLI (npx fetches the latest package)
+// silently refreshes a previously-installed-but-outdated block. Files we
+// never touched are left alone — presence of our marker (Claude Code) or our
+// dedicated file (Cursor) is the consent signal.
+async function refreshStaleRules({ verbose = false } = {}) {
+  const updated = [];
+
+  for (const client of ["claude-code", "cursor"]) {
+    // Consent signal: our rule file exists (current installs) or our legacy
+    // managed block sits in ~/.claude/CLAUDE.md (pre-0.1.0 installs, which
+    // migrate to the rules-dir + skill layout on this refresh).
+    const rp = rulePath(client);
+    let installedHere = await pathExists(rp);
+    if (!installedHere && client === "claude-code") {
+      try {
+        const text = await readFile(join(homedir(), ".claude", "CLAUDE.md"), "utf8");
+        installedHere = text.includes(RULES_MARKER_START);
+      } catch {
+        /* no file → never installed */
+      }
+    }
+    if (!installedHere) continue;
+
+    const ruleCurrent =
+      (await readFile(rp, "utf8").catch(() => "")) === ruleContent(client);
+    const skillCurrent =
+      (await readFile(skillPath(client), "utf8").catch(() => "")) === SKILL_BODY;
+    if (!ruleCurrent || !skillCurrent) {
+      const files = await patchRules(client);
+      updated.push(...files.map((f) => f.path));
+    }
+  }
+
+  if (updated.length > 0) {
+    console.log(`↻ Refreshed PingHumans agent rules (v${VERSION}):`);
+    for (const p of updated) console.log(`   ${p}`);
+    track("rules_refresh");
+  } else if (verbose) {
+    console.log(`✓ Agent rules already current (v${VERSION}).`);
+  }
+
+  // Same always-run path also catches a silently-dead token before a
+  // downstream client (Claude Desktop) fails cryptically. Never throws.
+  try {
+    await validateStoredToken();
+  } catch {
+    /* validation is best-effort */
+  }
+  return updated.length;
+}
+
+async function unpatchRules(client) {
+  // Legacy installs: clear our managed block out of ~/.claude/CLAUDE.md.
+  if (client === "claude-code") await stripLegacyClaudeMdBlock();
+
+  const { unlink, rm } = await import("node:fs/promises");
+  const rp = rulePath(client);
+  if (rp) await unlink(rp).catch(() => {});
+  const sp = skillPath(client);
+  if (sp) await rm(dirname(sp), { recursive: true, force: true }).catch(() => {});
+}
+
+async function patchClaudeCodeViaCli(token) {
+  // The official `claude mcp add` CLI is the recommended path.
+  // It writes to ~/.claude.json (or similar) for us.
+  try {
+    // Remove any existing config first, otherwise `mcp add` errors on dupes.
+    await execFileP("claude", [
+      "mcp",
+      "remove",
+      "pinghumans",
+      "--scope",
+      "user",
+    ]).catch(() => {});
+    // Order matters: `--header` is variadic in `claude mcp add`, so it has to
+    // come AFTER the positional <name> and <url> args, otherwise commander
+    // eats them as additional headers and bails with "missing argument name".
+    await execFileP("claude", [
+      "mcp",
+      "add",
+      "--scope",
+      "user",
+      "--transport",
+      "http",
+      "pinghumans",
+      `${APP_URL}/api/mcp`,
+      "--header",
+      `Authorization: Bearer ${token}`,
+    ]);
+  } catch (err) {
+    throw new Error(
+      `\`claude mcp add\` failed. Is the Claude Code CLI installed on your PATH? (https://docs.claude.com/en/docs/claude-code)\n  ${err.message}`
+    );
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+
+function parseClient(args) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--client" && args[i + 1]) {
+      const c = String(args[i + 1]).toLowerCase();
+      if (SUPPORTED_CLIENTS.includes(c)) return c;
+      throw new Error(
+        `Unknown --client "${c}". Supported: ${SUPPORTED_CLIENTS.join(", ")}.`
+      );
+    }
+    if (args[i] === "--claude" || args[i] === "--claude-desktop")
+      return "claude-desktop";
+    if (args[i] === "--code" || args[i] === "--claude-code")
+      return "claude-code";
+    if (args[i] === "--cursor") return "cursor";
+  }
+  return null;
+}
+
+function prettyClient(client) {
+  return (
+    {
+      "claude-desktop": "Claude Desktop",
+      "claude-code": "Claude Code",
+      cursor: "Cursor",
+    }[client] || client
+  );
+}
+
+function printHelp() {
+  console.log(`cpyany — install the PingHumans MCP server in your AI client.
+
+Usage:
+  cpyany setup [--client claude-code|claude-desktop|cursor]
+  cpyany remove [--client claude-code|claude-desktop|cursor]
+  cpyany wait <ping_id> [--timeout <seconds>]
+                       # block until a human test has results (exit 0 = news,
+                       # 2 = timed out). Run it in the background after filing
+                       # a test so your agent gets woken when results land.
+  cpyany whoami    # show which PingHumans account this machine's token belongs to
+  cpyany rules     # refresh the installed agent rules to this version
+  cpyany version
+
+Without --client, setup auto-detects every supported AI client installed on
+this machine (Claude Code, Claude Desktop, Cursor) and patches all of their
+configs from a single OAuth flow. Use --client to restrict to one.
+
+Setup opens your browser to ${APP_URL}/cli-auth, generates a fresh bearer
+token after you sign in, and writes it into each client's MCP config.
+
+Aliases: --claude (= --claude-desktop), --code (= --claude-code).
+Legacy binary alias: pinghumans.
+`);
+}
+
+// ─── `cpyany wait` — background-friendly result waiting ────────────────
+//
+// Turn-based coding agents can't poll on a timer. But harnesses with
+// background shell tasks (Claude Code etc.) re-invoke the agent when a
+// background command EXITS — so this command is the bridge to true async:
+// launch it in the background right after filing a test; it polls the MCP
+// endpoint client-side and exits the moment there's news.
+//
+// Exit codes: 0 = news (new result, or task complete/expired) — output has
+// the full results text; 2 = timed out still pending; 1 = error.
+
+// Hoisted as a function — the entry dispatch runs before bottom-of-module
+// consts initialize (the 0.0.4 TDZ lesson, again).
+function credsPath() {
+  return join(homedir(), ".config", "pinghumans", "credentials.json");
+}
+
+async function readCreds() {
+  try {
+    return JSON.parse(await readFile(credsPath(), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function writeCreds(obj) {
+  try {
+    await mkdir(dirname(credsPath()), { recursive: true });
+    await writeFile(credsPath(), JSON.stringify(obj, null, 2), { mode: 0o600 });
+  } catch {
+    /* best-effort — `wait` falls back to client configs */
+  }
+}
+
+async function saveLocalToken(token) {
+  // Fresh token from setup → reset any throttle/nudge state.
+  await writeCreds({ token });
+}
+
+// Passive token-health check. A dead token (revoked, or the account was
+// deleted — its mcp_tokens cascade-removed) otherwise sits silently in
+// every client config until something like Claude Desktop fails with a
+// cryptic OAuth race. Hooked into the always-run self-heal so any
+// `npx cpyany` invocation catches it. Strict rules: only nudge on an
+// EXPLICIT auth failure (401/403 or {success:false}); stay silent on
+// offline/timeout/5xx (no false alarms); throttle to once/day; stderr only.
+async function validateStoredToken() {
+  const token = await resolveLocalToken();
+  if (!token) return; // nothing stored → nothing to validate
+
+  const creds = await readCreds();
+  if (creds && typeof creds.checkedAt === "number" &&
+      Date.now() - creds.checkedAt < NUDGE_INTERVAL_MS) {
+    return; // checked recently — don't re-probe or re-nudge
+  }
+
+  let dead = false;
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 3000);
+    const res = await fetch(`${APP_URL}/api/cli/whoami`, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: ctrl.signal,
+    }).finally(() => clearTimeout(timer));
+    if (res.status === 401 || res.status === 403) {
+      dead = true;
+    } else if (res.ok) {
+      const j = await res.json().catch(() => ({}));
+      if (j && j.success === false) dead = true;
+    }
+    // 5xx / other → inconclusive; fall through without recording or nudging.
+    if (res.status >= 500) return;
+  } catch {
+    return; // offline / aborted → never false-alarm, retry next run
+  }
+
+  // Record the (reachable) check so we throttle — only when creds.json
+  // already exists (every install since 0.0.10); ancient config-only
+  // installs just pay the cheap check each run.
+  if (creds) await writeCreds({ ...creds, checkedAt: Date.now() });
+
+  if (dead) {
+    const pc = await import("picocolors").then((m) => m.default).catch(() => null);
+    const warn = (s) => (pc ? pc.yellow(s) : s);
+    console.error(
+      "\n" +
+        warn("⚠ Your PingHumans token is no longer valid") +
+        " (revoked, or the account was deleted).\n" +
+        "  Re-link this machine:  " +
+        (pc ? pc.cyan("npx cpyany setup") : "npx cpyany setup") +
+        "\n"
+    );
+  }
+}
+
+async function resolveLocalToken() {
+  // 1) Our own stash (written by setup since 0.0.10).
+  try {
+    const creds = JSON.parse(await readFile(credsPath(), "utf8"));
+    if (creds.token) return creds.token;
+  } catch {}
+  // 2) Older installs: fish the bearer out of a client config we wrote.
+  const candidates = [
+    join(homedir(), ".claude.json"),
+    configPath("claude-desktop"),
+    configPath("cursor"),
+  ];
+  for (const p of candidates) {
+    try {
+      const cfg = JSON.parse(await readFile(p, "utf8"));
+      const entry = cfg?.mcpServers?.pinghumans;
+      const header = entry?.headers?.Authorization ?? entry?.headers?.authorization;
+      const m = /Bearer\s+(\S+)/.exec(header ?? "");
+      if (m) return m[1];
+    } catch {}
+  }
+  return null;
+}
+
+async function waitForResultsCli(rest) {
+  const pingId = rest.find((a) => !a.startsWith("--"));
+  if (!pingId || !/^[0-9a-f-]{36}$/i.test(pingId)) {
+    throw new Error("usage: cpyany wait <ping_id> [--timeout <seconds>]");
+  }
+  const tIdx = rest.indexOf("--timeout");
+  const timeoutSec = tIdx >= 0 ? Math.max(30, parseInt(rest[tIdx + 1], 10) || 1800) : 1800;
+
+  const token = await resolveLocalToken();
+  if (!token) {
+    throw new Error(
+      "No PingHumans token found. Run `npx cpyany setup` first."
+    );
+  }
+
+  const deadline = Date.now() + timeoutSec * 1000;
+  let baseline = null;
+  for (;;) {
+    const res = await fetch(`${APP_URL}/api/mcp`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+        authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "get_test_results", arguments: { ping_id: pingId } },
+      }),
+    });
+    const raw = await res.text();
+    const m = raw.match(/data: (.*)/);
+    const payload = JSON.parse(m ? m[1] : raw);
+    if (payload.error) throw new Error(payload.error.message ?? "MCP error");
+    const result = payload.result;
+    const sc = result.structuredContent ?? {};
+    const status = sc.status ?? "pending";
+    const received = sc.n_received ?? 0;
+
+    if (baseline === null) baseline = received;
+
+    if (status === "not_found") {
+      throw new Error(
+        "Ping not found for this account. Results are asker-scoped — `wait` only works on tests filed with the same PingHumans account."
+      );
+    }
+    if (status !== "pending" || received > baseline) {
+      // News — print the agent-readable result and exit 0 so a background
+      // harness wakes the agent up.
+      console.log(result.content?.[0]?.text ?? JSON.stringify(sc, null, 2));
+      process.exit(0);
+    }
+    if (Date.now() >= deadline) {
+      console.log(
+        `Timed out after ${timeoutSec}s — still pending (${received}/${sc.n_target ?? "?"} results). ` +
+          `Run \`cpyany wait ${pingId}\` again or check later with get_test_results.`
+      );
+      process.exit(2);
+    }
+    process.stderr.write(
+      `… pending ${received}/${sc.n_target ?? "?"} (${Math.round((deadline - Date.now()) / 1000)}s left)\n`
+    );
+    await new Promise((r) => setTimeout(r, 20000));
+  }
+}
+
+// ─── `cpyany whoami` ───────────────────────────────────────────────────
+//
+// Which account does this machine's token belong to? Results are
+// asker-scoped server-side, so "Ping not found" almost always means
+// wrong-account token — this is the 10-second way to check.
+
+async function whoamiCli() {
+  const pc = await import("picocolors").then((m) => m.default);
+  const token = await resolveLocalToken();
+  if (!token) {
+    console.log(pc.yellow("Not logged in."));
+    console.log(pc.dim("Run `npx cpyany setup` to authenticate."));
+    return;
+  }
+  try {
+    const who = await fetchWhoami(token);
+    console.log(pc.green("Logged in"));
+    if (who.name) console.log(`${pc.dim("Name:".padEnd(13))}${who.name}`);
+    if (who.email) console.log(`${pc.dim("Email:".padEnd(13))}${who.email}`);
+  } catch {
+    console.log(pc.yellow("Token present but not accepted by the server."));
+    console.log(pc.dim("Run `npx cpyany setup` to re-authenticate."));
+  }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "cpyany",
+  "version": "0.2.5",
+  "description": "Install the PingHumans MCP server in Claude Desktop, Claude Code, or Cursor with one command.",
+  "type": "module",
+  "main": "index.mjs",
+  "bin": {
+    "cpyany": "index.mjs",
+    "copyanything": "index.mjs",
+    "pinghumans": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test:setup": "node index.mjs setup --client claude-code"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.5.2",
+    "boxen": "^8.0.1",
+    "open": "^10.1.2",
+    "ora": "^9.4.0",
+    "picocolors": "^1.1.1"
+  },
+  "homepage": "https://pinghumans.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alex-durango/pinghumans.git",
+    "directory": "cli"
+  },
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "ai",
+    "humans",
+    "cpyany",
+    "copyanything",
+    "pinghumans"
+  ]
+}