@kivimedia/kmhub 2.9.1 → 2.10.0

package/bin/kmhub.mjs

@@ -1,896 +1,896 @@
-#!/usr/bin/env node
-/**
- * kmhub - the Terminal Mode command line tool.
- *
- * Three jobs, and only three:
- *
- *   kmhub install <key> [name]   register the connector in this machine's Claude Code
- *   kmhub update  [key] [name]   is this build still one KM Hub serves
- *   kmhub doctor  [key] [name]   why is it not working
- *
- * The whole point of this file is that a client never types an absolute path
- * again. The old instruction was `claude mcp add kmhub -e KEY=... -- node
- * /absolute/path/to/kmhub/mcp-server/index.mjs`, which only works if they cloned
- * a private repo first and then got the path right. Published on npm, the same
- * job is `npx @kivimedia/kmhub install kmh_live_...` and the connector is
- * launched by npx from then on, so it updates itself when Claude Code restarts.
- *
- * Where the work actually happens is worth stating plainly, because it decides
- * what this tool is allowed to do. Terminal Mode runs on the CLIENT machine,
- * inside THEIR Claude Code, on THEIR Claude subscription. Nothing here schedules
- * anything, runs an agent, or phones home. It registers a connector, reads two
- * public-to-the-key endpoints (GET /me and GET /version), and reports.
- *
- * Deliberately dependency free. It imports node builtins and, only where it has
- * something to say about them, the connector's own modules. `doctor` has to be
- * the command that works when everything else is broken, so it cannot rely on
- * the thing it is diagnosing being importable.
- */
-
-import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-
-// The published package name. Every registration points at this, never at a path
-// on the client's disk, which is the entire reason this file exists.
-const PKG_NAME = '@kivimedia/kmhub';
-
-/** The MCP server name a connector is registered under unless the user picks another. */
-const DEFAULT_CONNECTOR = 'kmhub';
-
-/**
- * Mirrors DEFAULT_BASE in tools.mjs. Duplicated on purpose: `doctor` has to be
- * able to reach KM Hub even when tools.mjs is the thing that will not load, and
- * "I cannot tell you anything because my own import failed" is a useless answer
- * to a support ticket. When tools.mjs does load, its value wins.
- */
-const FALLBACK_BASE = 'https://jpwbosrmkibsdgckowsm.supabase.co/functions/v1/kmhub-api';
-
-/** Keys are minted as kmh_live_ plus hex. The API matches the same shape before it looks anything up. */
-const KEY_RE = /^kmh_live_[0-9a-f]+$/i;
-
-/**
- * Where people who use Codex, Cursor or Grok Build are sent. This tool only knows how to
- * register into Claude Code; the installers behind this page wire all four apps.
- */
-const SETUP_URL = 'https://hub.kivimedia.co/terminal/';
-
-/** A connector name has to survive being an argv element and a JSON key. */
-const NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
-
-const HELP = `kmhub, the KM Hub Terminal Mode command line tool.
-
-  npx ${PKG_NAME} install <kmh_live_key> [connector-name]
-      Register the KM Hub connector in Claude Code on this machine.
-      Verifies the key against KM Hub first, so a bad key never gets registered.
-
-  npx ${PKG_NAME} update [kmh_live_key] [connector-name]
-      Ask KM Hub what it publishes today and say whether this build is still one
-      it serves.
-
-  npx ${PKG_NAME} doctor [kmh_live_key] [connector-name]
-      Diagnose a broken install: Claude Code, the registration, the key, the
-      subscription, and whether the connector files load at all.
-
-  The key is optional for update and doctor. They look, in order, at the argument
-  you passed, then KMHUB_API_KEY in the environment, then the key stored in the
-  registration itself.
-
-  Create a key in KM Hub under Settings > Connect > Developer & API.
-  Set KMHUB_API_BASE to point at a different KM Hub.
-
-  This tool registers Claude Code only. For Codex, Cursor or Grok Build, use the
-  KM Hub setup instead, which connects the app you pick and needs no key:
-  ${SETUP_URL}
-`;
-
-// ---------------------------------------------------------------------------
-// small output helpers
-// ---------------------------------------------------------------------------
-
-function say(line = '') {
-  process.stdout.write(`${line}\n`);
-}
-
-function fail(line = '') {
-  process.stderr.write(`${line}\n`);
-}
-
-/** Fixed width labels so a doctor report reads as a column, not a paragraph. */
-function statusLine(status, label, detail) {
-  const tag = { ok: 'ok  ', warn: 'warn', fail: 'FAIL' }[status] || '    ';
-  return `  ${tag}  ${label}${detail ? `: ${detail}` : ''}`;
-}
-
-/** Never print a whole key. Enough to recognise it, not enough to use it. */
-function maskKey(key) {
-  if (typeof key !== 'string' || key.length < 16) return '(unreadable)';
-  return `${key.slice(0, 13)}...${key.slice(-4)}`;
-}
-
-// ---------------------------------------------------------------------------
-// the connector's own modules
-// ---------------------------------------------------------------------------
-
-/** This package's own package.json, read from disk rather than imported. */
-function readPkg() {
-  try {
-    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
-  } catch {
-    return {};
-  }
-}
-
-/**
- * Load tools.mjs, which is where the connector's real identity lives
- * (SERVER_VERSION, the families that loaded, the API base).
- *
- * This is a genuine diagnostic and not just a version read. tools.mjs scans
- * tools/ at import time, so if a family file is missing or a dependency did not
- * install, the import is where that shows up. Failure is captured, never thrown:
- * `doctor` reporting "your install is broken, here is the error" is the answer
- * the support ticket needed.
- */
-async function loadServer() {
-  try {
-    const mod = await import(new URL('../tools.mjs', import.meta.url));
-    return { ok: true, mod };
-  } catch (e) {
-    return { ok: false, error: String(e?.message || e) };
-  }
-}
-
-function apiBase(server) {
-  const fromEnv = typeof process.env.KMHUB_API_BASE === 'string' ? process.env.KMHUB_API_BASE.trim() : '';
-  if (fromEnv) return fromEnv;
-  const fromServer = server?.ok ? server.mod?.DEFAULT_BASE : '';
-  return typeof fromServer === 'string' && fromServer ? fromServer : FALLBACK_BASE;
-}
-
-// ---------------------------------------------------------------------------
-// KM Hub
-// ---------------------------------------------------------------------------
-
-/**
- * One GET against kmhub-api with the org key. Never throws: a dead network is a
- * result to report, not a stack trace to print at somebody who wanted an answer.
- */
-async function api(base, key, path, timeoutMs = 15000) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const r = await fetch(`${base}${path}`, {
-      headers: { Authorization: `Bearer ${key}`, 'content-type': 'application/json' },
-      signal: controller.signal,
-    });
-    const raw = await r.text();
-    let data;
-    try {
-      data = JSON.parse(raw);
-    } catch {
-      data = raw;
-    }
-    return { ok: r.ok, status: r.status, data };
-  } catch (e) {
-    const aborted = e?.name === 'AbortError';
-    return {
-      ok: false,
-      status: 0,
-      data: null,
-      error: aborted ? `no answer within ${Math.round(timeoutMs / 1000)}s` : String(e?.message || e),
-    };
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-/**
- * Turn a failed call into a sentence a working performer can act on.
- *
- * The 402 case is the one that matters most. kmhub-api runs the entitlement gate
- * before every route, so a lapsed subscription answers 402 on everything,
- * including GET /version. Left as a status code that reads like the software
- * broke. It did not, and the wording says so: nothing changed, nothing is gone,
- * here is the one thing to do.
- */
-function explain(res, base) {
-  const body = res && res.data && typeof res.data === 'object' ? res.data : {};
-  const message = typeof body.message === 'string' && body.message.trim() ? body.message.trim() : '';
-
-  if (res.status === 0) {
-    return [
-      `Could not reach KM Hub at ${base} (${res.error || 'no answer'}).`,
-      'That is a network or DNS problem on this machine, not your key. Check the connection and try again.',
-    ].join('\n');
-  }
-  if (res.status === 401) {
-    return [
-      'KM Hub did not accept that key. It is either mistyped or it has been revoked.',
-      'Create a fresh one in KM Hub under Settings > Connect > Developer & API, then run this again with the new key.',
-    ].join('\n');
-  }
-  if (res.status === 402) {
-    return [
-      'Your KM Hub subscription is not active, so the connector is switched off at the server.',
-      'Nothing in your workspace has changed, and none of your data has gone anywhere.',
-      message,
-      'Sign in at https://hub.kivimedia.co and restart the subscription under Settings > Billing. Once that is done this works again on the next call, with nothing to reinstall.',
-    ]
-      .filter(Boolean)
-      .join('\n');
-  }
-  if (res.status === 403) {
-    return [
-      `This key does not carry the scope that call needs${message ? ` (${message})` : ''}.`,
-      'A read-only key can read your workspace but cannot create anything. Mint a key with write scope in Settings > Connect > Developer & API if you need the create tools.',
-    ].join('\n');
-  }
-  if (res.status === 429) {
-    return `KM Hub rate limited this key${message ? `: ${message}` : '.'} Wait a minute and try again.`;
-  }
-  if (res.status >= 500) {
-    return `KM Hub answered ${res.status}${message ? `: ${message}` : '.'} That is a problem on the KM Hub side, not on this machine. Try again shortly.`;
-  }
-  return `KM Hub answered ${res.status}${message ? `: ${message}` : ''}.`;
-}
-
-// ---------------------------------------------------------------------------
-// finding an existing registration
-// ---------------------------------------------------------------------------
-
-/**
- * The files a Claude client stores MCP server registrations in. Read only, and
- * every one of them is optional: a machine with none of these is simply a
- * machine where nothing is registered yet, which is a finding, not an error.
- */
-function candidateConfigs() {
-  const home = homedir();
-  const files = [
-    { file: join(home, '.claude.json'), label: 'Claude Code (user)' },
-    { file: join(process.cwd(), '.mcp.json'), label: 'Claude Code (this project)' },
-  ];
-  if (process.platform === 'win32' && process.env.APPDATA) {
-    files.push({ file: join(process.env.APPDATA, 'Claude', 'claude_desktop_config.json'), label: 'Claude Desktop' });
-  } else if (process.platform === 'darwin') {
-    files.push({
-      file: join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
-      label: 'Claude Desktop',
-    });
-  } else {
-    files.push({ file: join(home, '.config', 'Claude', 'claude_desktop_config.json'), label: 'Claude Desktop' });
-  }
-  return files;
-}
-
-/**
- * Every place a config file can hold a server entry under this name. The file it
- * came from already says which client and which scope, so a top level entry adds
- * nothing and says nothing. Only a per-project entry needs naming, because there
- * can be many and only one of them is the directory the client is working in.
- */
-function entriesInConfig(json, name) {
-  const found = [];
-  const top = json?.mcpServers?.[name];
-  if (top && typeof top === 'object') found.push({ entry: top, where: '' });
-  const projects = json?.projects;
-  if (projects && typeof projects === 'object') {
-    for (const [path, project] of Object.entries(projects)) {
-      const entry = project?.mcpServers?.[name];
-      if (entry && typeof entry === 'object') found.push({ entry, where: `project ${path}` });
-    }
-  }
-  return found;
-}
-
-function findRegistrations(name) {
-  const found = [];
-  for (const candidate of candidateConfigs()) {
-    if (!existsSync(candidate.file)) continue;
-    let json;
-    try {
-      json = JSON.parse(readFileSync(candidate.file, 'utf8'));
-    } catch {
-      found.push({ ...candidate, unreadable: true });
-      continue;
-    }
-    for (const hit of entriesInConfig(json, name)) found.push({ ...candidate, ...hit });
-  }
-  return found;
-}
-
-/** A registration can carry the key as a stdio env var or as a remote Bearer header. */
-function keyFromEntry(entry) {
-  const fromEnv = entry?.env?.KMHUB_API_KEY;
-  if (typeof fromEnv === 'string' && KEY_RE.test(fromEnv.trim())) return fromEnv.trim();
-  const headers = entry?.headers && typeof entry.headers === 'object' ? entry.headers : {};
-  for (const value of Object.values(headers)) {
-    if (typeof value !== 'string') continue;
-    const m = value.match(/Bearer\s+(kmh_live_[0-9a-f]+)/i);
-    if (m) return m[1];
-  }
-  return '';
-}
-
-/**
- * Where the key comes from, most explicit first: the argument, then the
- * environment, then whatever the existing registration already holds. That last
- * one is what makes `doctor` answer a support ticket without asking the client
- * to go and find their key.
- */
-function resolveKey(argKey, registrations) {
-  if (argKey) return { key: argKey, source: 'the key you passed' };
-  const fromEnv = typeof process.env.KMHUB_API_KEY === 'string' ? process.env.KMHUB_API_KEY.trim() : '';
-  if (fromEnv) return { key: fromEnv, source: 'KMHUB_API_KEY in this environment' };
-  for (const reg of registrations) {
-    const key = keyFromEntry(reg.entry);
-    if (key) return { key, source: `the registration in ${reg.label}` };
-  }
-  return { key: '', source: '' };
-}
-
-// ---------------------------------------------------------------------------
-// running the claude CLI
-// ---------------------------------------------------------------------------
-
-/**
- * Windows needs a shell to launch the `claude` .cmd shim, and a shell means argv
- * is re-parsed. Everything this file passes (a key, a connector name, a package
- * name, npx flags) is validated before it gets here rather than escaped after,
- * so quoting is only ever a safety net.
- */
-function quoteArg(arg) {
-  if (/^[A-Za-z0-9_@:.,/=+-]+$/.test(arg)) return arg;
-  return `"${String(arg).replace(/"/g, '\\"')}"`;
-}
-
-/**
- * On Windows the whole thing goes in as ONE already-quoted string. Handing
- * spawnSync an args array together with shell:true is deprecated from Node 22
- * (DEP0190) precisely because the args are concatenated rather than escaped, and
- * it prints a warning at the client that has nothing to do with their problem.
- * Everywhere else there is no shell at all, which is the safer path anyway.
- */
-function runCli(cmd, args, timeoutMs = 120000) {
-  const useShell = process.platform === 'win32';
-  const r = useShell
-    ? spawnSync([cmd, ...args].map(quoteArg).join(' '), {
-        encoding: 'utf8',
-        shell: true,
-        timeout: timeoutMs,
-      })
-    : spawnSync(cmd, args, {
-        encoding: 'utf8',
-        timeout: timeoutMs,
-      });
-  const stdout = (r.stdout || '').trim();
-  const stderr = (r.stderr || '').trim();
-  // ENOENT is how a missing binary surfaces without a shell. With cmd.exe in the
-  // way it comes back as an exit code plus a message instead, so test for both.
-  const missing =
-    (r.error && (r.error.code === 'ENOENT' || /ENOENT/.test(String(r.error.message || '')))) ||
-    /is not recognized as an internal or external command|command not found|no such file or directory/i.test(
-      `${stderr}\n${stdout}`,
-    );
-  return {
-    ok: !r.error && r.status === 0,
-    status: r.status,
-    stdout,
-    stderr,
-    missing: Boolean(missing),
-    error: r.error ? String(r.error.message || r.error) : '',
-  };
-}
-
-/** The argv the connector is registered with. npx resolves the package at launch, never a local path. */
-function connectorCommand() {
-  return ['npx', '-y', '--package', PKG_NAME, 'kmhub-mcp'];
-}
-
-function desktopConfigBlock(name, key) {
-  return JSON.stringify(
-    {
-      mcpServers: {
-        [name]: {
-          command: 'npx',
-          args: ['-y', '--package', PKG_NAME, 'kmhub-mcp'],
-          env: { KMHUB_API_KEY: key },
-        },
-      },
-    },
-    null,
-    2,
-  );
-}
-
-// ---------------------------------------------------------------------------
-// version comparison
-// ---------------------------------------------------------------------------
-
-/**
- * Compare two semver-ish strings. Build metadata after a plus is dropped before
- * comparing, because the rules pack stamps itself as base plus a content hash
- * and the hash is not an ordering. Returns negative, zero or positive.
- */
-function cmpVersion(a, b) {
-  const parts = (v) =>
-    String(v || '')
-      .trim()
-      .split('+')[0]
-      .split('-')[0]
-      .split('.')
-      .map((n) => Number.parseInt(n, 10) || 0);
-  const left = parts(a);
-  const right = parts(b);
-  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
-    const d = (left[i] || 0) - (right[i] || 0);
-    if (d !== 0) return d;
-  }
-  return 0;
-}
-
-// ---------------------------------------------------------------------------
-// install
-// ---------------------------------------------------------------------------
-
-async function cmdInstall(key, name) {
-  if (!key) {
-    fail('kmhub install needs your KM Hub API key.');
-    fail('');
-    fail(`  npx ${PKG_NAME} install kmh_live_xxxxxxxx`);
-    fail('');
-    // Say what was done with what they did type. Anything not shaped like a key
-    // is read as a connector name, and silently doing that to a mistyped key is
-    // how somebody spends ten minutes on a message that looks wrong.
-    if (name !== DEFAULT_CONNECTOR) {
-      fail(`I read "${name}" as the connector name, not as a key. A key starts with kmh_live_.`);
-      fail('');
-    }
-    fail('Create one in KM Hub under Settings > Connect > Developer & API.');
-    return 2;
-  }
-  if (!KEY_RE.test(key)) {
-    fail('That does not look like a KM Hub API key.');
-    fail('A key starts with kmh_live_ and is followed by hex. Copy it again from Settings > Connect > Developer & API.');
-    return 2;
-  }
-  if (!NAME_RE.test(name)) {
-    fail(`"${name}" is not a usable connector name. Use letters, numbers, dash or underscore.`);
-    return 2;
-  }
-
-  const server = await loadServer();
-  const base = apiBase(server);
-
-  // 1. The key, before anything is written anywhere. Registering a dead key just
-  //    moves the failure to the first tool call, where it is much harder to read.
-  say('Checking the key with KM Hub...');
-  const me = await api(base, key, '/me');
-  if (!me.ok) {
-    fail('');
-    fail(explain(me, base));
-    fail('');
-    fail('Nothing was registered. Your Claude Code configuration is untouched.');
-    return 1;
-  }
-
-  const org = me.data?.org && typeof me.data.org === 'object' ? me.data.org : {};
-  const scopes = Array.isArray(me.data?.scopes) ? me.data.scopes : [];
-  const workspace = typeof org.name === 'string' && org.name.trim() ? org.name.trim() : 'your workspace';
-  const plan = typeof org.plan === 'string' && org.plan.trim() ? org.plan.trim() : '';
-
-  say(`Key accepted. Workspace: ${workspace}${plan ? ` (plan ${plan})` : ''}.`);
-  say(`Scopes on this key: ${scopes.length ? scopes.join(', ') : 'none reported'}.`);
-  if (scopes.length && !scopes.includes('write')) {
-    say('');
-    say('Note: this key is read only. The connector will read your workspace, and any tool that');
-    say('creates something will be refused by KM Hub. Mint a key with write scope if you want those.');
-  }
-  say('');
-
-  // 2. Claude Code has to exist before there is anywhere to register.
-  const claude = runCli('claude', ['--version'], 30000);
-  if (claude.missing) {
-    fail('Claude Code is not on this machine, or its `claude` command is not on your PATH.');
-    fail('Install it from https://claude.com/claude-code and run this again.');
-    fail('');
-    fail('If you are setting up Claude Desktop instead, put this in your claude_desktop_config.json:');
-    fail('');
-    fail(desktopConfigBlock(name, key));
-    fail('');
-    fail('Using Codex, Cursor or Grok Build instead? This tool only registers Claude Code.');
-    fail(`The KM Hub setup connects the app you pick: ${SETUP_URL}`);
-    return 1;
-  }
-
-  // 3. Register. The command is npx and the package name, never a path on disk,
-  //    so restarting Claude Code is all it takes to pick up a newer build.
-  const args = ['mcp', 'add', name, '--scope', 'user', '-e', `KMHUB_API_KEY=${key}`, '--', ...connectorCommand()];
-  say(`Registering the connector as "${name}"...`);
-  const add = runCli('claude', args);
-  if (!add.ok) {
-    const output = `${add.stdout}\n${add.stderr}`.trim();
-    fail('');
-    fail(`Claude Code refused to add the connector${add.status ? ` (exit ${add.status})` : ''}.`);
-    if (output) fail(output);
-    if (/already exists|already configured/i.test(output)) {
-      fail('');
-      fail(`A connector called "${name}" is already registered. Remove it and run this again:`);
-      fail('');
-      fail(`  claude mcp remove ${name} --scope user`);
-      fail(`  npx ${PKG_NAME} install ${maskKey(key)} ${name}`);
-      fail('');
-      fail('(use the real key, not the masked one above)');
-    }
-    return 1;
-  }
-
-  say('');
-  say(`Done. ${workspace} is connected to Claude Code on this machine.`);
-  say('');
-  say('Open Claude Code and type this:');
-  say('');
-  say('  Ask KM Hub what needs me today.');
-  say('');
-  say('Two things worth knowing:');
-  say(`  1. The key is stored in your Claude Code config. If it ever leaks, revoke it in KM Hub`);
-  say('     under Settings > Connect > Developer & API and run this install again with a fresh one.');
-  say(`  2. The connector is launched with npx, so restarting Claude Code picks up new builds.`);
-  say(`     Run  npx ${PKG_NAME} doctor  if anything ever looks wrong.`);
-  return 0;
-}
-
-// ---------------------------------------------------------------------------
-// update
-// ---------------------------------------------------------------------------
-
-async function cmdUpdate(argKey, name) {
-  const server = await loadServer();
-  const base = apiBase(server);
-  const pkg = readPkg();
-  const installed = server.ok && typeof server.mod?.SERVER_VERSION === 'string' ? server.mod.SERVER_VERSION : '';
-
-  say('KM Hub connector');
-  say('');
-  if (!server.ok) {
-    say(statusLine('fail', 'this build', 'the connector modules would not load'));
-    say(`        ${server.error}`);
-    say(`        Run  npx ${PKG_NAME} doctor  for the full picture.`);
-  } else {
-    say(statusLine('ok', 'this build', installed || 'unknown'));
-    if (pkg.version && installed && pkg.version !== installed) {
-      say(
-        statusLine(
-          'warn',
-          'version identity',
-          `package says ${pkg.version} and the server says ${installed}. Report that, it is a packaging bug.`,
-        ),
-      );
-    }
-  }
-
-  const registrations = findRegistrations(name).filter((r) => r.entry);
-  const { key, source } = resolveKey(argKey, registrations);
-  if (!key) {
-    say('');
-    fail('No KM Hub API key to ask with.');
-    fail(`Pass one, or set KMHUB_API_KEY, or install the connector first:  npx ${PKG_NAME} install kmh_live_...`);
-    return 2;
-  }
-  if (!KEY_RE.test(key)) {
-    say('');
-    fail(`The key from ${source} is not shaped like a KM Hub key (kmh_live_ then hex).`);
-    return 2;
-  }
-
-  say('');
-  say(`Asking KM Hub what it publishes today (key from ${source})...`);
-  const v = await api(base, key, '/version');
-  if (!v.ok) {
-    say('');
-    fail(explain(v, base));
-    return 1;
-  }
-
-  const d = v.data && typeof v.data === 'object' ? v.data : {};
-  const minClient = typeof d.min_client === 'string' ? d.min_client : '';
-  const rulesVersion = typeof d.rules_version === 'string' ? d.rules_version : '';
-
-  say('');
-  say('KM Hub publishes:');
-  say(statusLine('ok', 'API', d.api_version || 'not reported'));
-  say(statusLine('ok', 'tool catalogue', d.tools_version || 'not reported'));
-  say(statusLine('ok', 'rules pack', rulesVersion || 'not reported'));
-  say(statusLine('ok', 'oldest client it serves', minClient || 'not reported'));
-  say('');
-
-  // The only hard judgement available. min_client is the floor KM Hub refuses to
-  // serve below; there is no "latest client" field, so anything at or above the
-  // floor is reported as still served rather than dressed up as up to date.
-  if (!installed) {
-    say('This build could not be identified, so whether it is out of date cannot be answered here.');
-    say(`Run  npx ${PKG_NAME} doctor  first: something about the install is wrong.`);
-    return 1;
-  }
-  if (minClient && cmpVersion(installed, minClient) < 0) {
-    say(`OUT OF DATE. This connector is ${installed} and KM Hub no longer serves anything below ${minClient}.`);
-    say('It will stop working. Update it now:');
-    say('');
-    say('  1. Quit Claude Code completely and open it again. The connector is launched with npx,');
-    say('     so a restart fetches the current build on its own.');
-    say('  2. If it is still on the old version after that, re-register it:');
-    say('');
-    say(`       claude mcp remove ${name} --scope user`);
-    say(`       npx ${PKG_NAME}@latest install <your kmh_live_ key> ${name}`);
-    if (d.changelog_url) say(`\n  What changed: ${d.changelog_url}`);
-    return 1;
-  }
-
-  say(`Up to date enough. KM Hub still serves ${installed}${minClient ? ` (its floor is ${minClient})` : ''}.`);
-  say('Nothing to run.');
-  say('');
-  say(`The rules pack KM Hub publishes today is ${rulesVersion || 'not reported'}. This tool does not touch`);
-  say('your rules file. To refresh it, open Claude Code and say: check for KM Hub updates.');
-  say('That runs the connector\'s own update tools, which rewrite the KM Hub block in your CLAUDE.md.');
-  if (d.changelog_url) say(`\nChangelog: ${d.changelog_url}`);
-  return 0;
-}
-
-// ---------------------------------------------------------------------------
-// doctor
-// ---------------------------------------------------------------------------
-
-/**
- * The command that answers a support ticket without a call.
- *
- * Every check reports one of three things and, when it is not ok, the single
- * next action. It never stops at the first failure: a client who has three
- * things wrong should learn all three in one paste, not across three emails.
- * Exit code is 1 if anything failed, so it is also usable as a gate.
- */
-async function cmdDoctor(argKey, name) {
-  const checks = [];
-  const record = (status, label, detail, fix) => {
-    checks.push({ status, label, detail, fix });
-    say(statusLine(status, label, detail));
-    if (fix && status !== 'ok') {
-      for (const line of String(fix).split('\n')) say(`        ${line}`);
-    }
-  };
-
-  const pkg = readPkg();
-  say(`kmhub doctor  (${PKG_NAME}${pkg.version ? ` ${pkg.version}` : ''}, connector name "${name}")`);
-  say('');
-
-  // 1. The runtime underneath everything else.
-  const major = Number.parseInt(String(process.versions.node).split('.')[0], 10) || 0;
-  if (major >= 18) {
-    record('ok', 'Node', `${process.version} on ${process.platform}`);
-  } else {
-    record(
-      'fail',
-      'Node',
-      `${process.version} is too old`,
-      'The connector needs Node 18.17 or newer. Install a current Node and run this again.',
-    );
-  }
-
-  // 2. Do the connector's own files load. This is the check that catches a
-  //    half-finished install, a missing dependency, or a broken family file.
-  const server = await loadServer();
-  const installed = server.ok && typeof server.mod?.SERVER_VERSION === 'string' ? server.mod.SERVER_VERSION : '';
-  if (server.ok) {
-    const families = Array.isArray(server.mod?.FAMILY_NAMES) ? server.mod.FAMILY_NAMES : [];
-    const tools = Array.isArray(server.mod?.TOOL_NAMES) ? server.mod.TOOL_NAMES : [];
-    record('ok', 'connector files', `version ${installed || 'unknown'}, ${families.length} families, ${tools.length} tools`);
-  } else {
-    record(
-      'fail',
-      'connector files',
-      'they would not load',
-      `${server.error}\nReinstall the connector:  npx ${PKG_NAME}@latest install <your kmh_live_ key> ${name}`,
-    );
-  }
-
-  // 3. One process, two version numbers. They have disagreed before, so it is a check.
-  if (server.ok && pkg.version && installed) {
-    if (pkg.version === installed) {
-      record('ok', 'version identity', `package and server both say ${installed}`);
-    } else {
-      record(
-        'warn',
-        'version identity',
-        `package says ${pkg.version}, server says ${installed}`,
-        'That is a packaging bug on our side, not something you can fix. Send this report to KM Hub.',
-      );
-    }
-  }
-
-  // 4. Is there a Claude Code to be registered in.
-  const claude = runCli('claude', ['--version'], 30000);
-  if (claude.missing) {
-    record(
-      'fail',
-      'Claude Code',
-      'the `claude` command was not found',
-      'Install it from https://claude.com/claude-code, then run the install again.',
-    );
-  } else if (claude.ok) {
-    record('ok', 'Claude Code', claude.stdout.split('\n')[0] || 'installed');
-  } else {
-    record('warn', 'Claude Code', `\`claude --version\` exited ${claude.status ?? 'oddly'}`, claude.stderr || claude.error);
-  }
-
-  // 5. Is the connector actually registered, and where.
-  const registrations = findRegistrations(name);
-  const usable = registrations.filter((r) => r.entry);
-  if (usable.length) {
-    for (const reg of usable) {
-      const cmd = Array.isArray(reg.entry.args)
-        ? `${reg.entry.command} ${reg.entry.args.join(' ')}`
-        : reg.entry.command || reg.entry.url || 'no command recorded';
-      record('ok', 'registration', `${reg.label}${reg.where ? `, ${reg.where}` : ''}: ${cmd}`);
-    }
-  } else {
-    const unreadable = registrations.filter((r) => r.unreadable);
-    record(
-      'fail',
-      'registration',
-      `no connector called "${name}" in any Claude config on this machine`,
-      `${unreadable.length ? `${unreadable.map((u) => u.file).join(', ')} could not be parsed as JSON.\n` : ''}Register it:  npx ${PKG_NAME} install <your kmh_live_ key> ${name}`,
-    );
-  }
-
-  // 6. A key to test with.
-  const { key, source } = resolveKey(argKey, usable);
-  const base = apiBase(server);
-  if (!key) {
-    record(
-      'fail',
-      'API key',
-      'none found',
-      `Pass it:  npx ${PKG_NAME} doctor <your kmh_live_ key>\nOr set KMHUB_API_KEY in this shell.`,
-    );
-  } else if (!KEY_RE.test(key)) {
-    record(
-      'fail',
-      'API key',
-      `the value from ${source} is not shaped like a KM Hub key`,
-      'A key starts with kmh_live_ and is followed by hex. Copy it again from Settings > Connect > Developer & API.',
-    );
-  } else {
-    record('ok', 'API key', `${maskKey(key)} from ${source}`);
-  }
-
-  // 7 and 8. Authentication and entitlement, in one call. kmhub-api checks the
-  //    key first and the subscription second, so a 401 says nothing about
-  //    billing and a 402 says the key is fine and the subscription is not.
-  if (key && KEY_RE.test(key)) {
-    const me = await api(base, key, '/me');
-    if (me.ok) {
-      const org = me.data?.org && typeof me.data.org === 'object' ? me.data.org : {};
-      const scopes = Array.isArray(me.data?.scopes) ? me.data.scopes : [];
-      const workspace = typeof org.name === 'string' && org.name.trim() ? org.name.trim() : 'unnamed workspace';
-      record('ok', 'key authenticates', `${workspace}${org.plan ? ` (plan ${org.plan})` : ''}`);
-      record('ok', 'subscription', 'active, KM Hub is serving this workspace');
-      if (scopes.length && !scopes.includes('write')) {
-        record(
-          'warn',
-          'scopes',
-          `${scopes.join(', ')} only`,
-          'Read tools work. Anything that creates something will be refused. Mint a key with write scope if you need those.',
-        );
-      } else {
-        record('ok', 'scopes', scopes.length ? scopes.join(', ') : 'none reported');
-      }
-    } else if (me.status === 402) {
-      record('ok', 'key authenticates', 'the key itself is valid, KM Hub recognised it');
-      record('fail', 'subscription', 'not active', explain(me, base));
-    } else {
-      record('fail', 'key authenticates', `KM Hub answered ${me.status || 'nothing'}`, explain(me, base));
-      record('warn', 'subscription', 'cannot be checked until the key works');
-    }
-
-    // 9. Only meaningful once the key works.
-    if (me.ok) {
-      const v = await api(base, key, '/version');
-      if (!v.ok) {
-        record('warn', 'client version floor', 'KM Hub did not answer GET /version', explain(v, base));
-      } else {
-        const minClient = typeof v.data?.min_client === 'string' ? v.data.min_client : '';
-        if (!installed || !minClient) {
-          record('warn', 'client version floor', 'not enough information to judge');
-        } else if (cmpVersion(installed, minClient) < 0) {
-          record(
-            'fail',
-            'client version floor',
-            `this build is ${installed} and KM Hub serves nothing below ${minClient}`,
-            `Restart Claude Code to pull the current build, or re-register:\n  claude mcp remove ${name} --scope user\n  npx ${PKG_NAME}@latest install <your kmh_live_ key> ${name}`,
-          );
-        } else {
-          record('ok', 'client version floor', `${installed} is at or above ${minClient}`);
-        }
-      }
-    }
-  }
-
-  const failed = checks.filter((c) => c.status === 'fail');
-  const warned = checks.filter((c) => c.status === 'warn');
-  say('');
-  if (!failed.length && !warned.length) {
-    say('Everything checks out. If a tool still misbehaves, the problem is in the conversation,');
-    say('not the connection: say what you asked for and what came back.');
-    return 0;
-  }
-  say(`${failed.length} failed, ${warned.length} to be aware of.`);
-  if (failed.length) {
-    say('');
-    say(`Next: ${failed[0].label}.`);
-    if (failed[0].fix) for (const line of String(failed[0].fix).split('\n')) say(`  ${line}`);
-    return 1;
-  }
-  return 0;
-}
-
-// ---------------------------------------------------------------------------
-// argv
-// ---------------------------------------------------------------------------
-
-/**
- * No flags to learn. A KM Hub key is unmistakable, so any argument that looks
- * like one is the key and anything else is the connector name, whatever order
- * they arrive in.
- */
-function parseArgs(argv) {
-  const [command, ...rest] = argv;
-  let key = '';
-  let name = '';
-  for (const arg of rest) {
-    if (!arg) continue;
-    if (/^kmh_live_/i.test(arg)) {
-      if (!key) key = arg.trim();
-    } else if (!name) {
-      name = arg.trim();
-    }
-  }
-  return { command: (command || '').toLowerCase(), key, name: name || DEFAULT_CONNECTOR };
-}
-
-async function main() {
-  const { command, key, name } = parseArgs(process.argv.slice(2));
-
-  if (!command || command === 'help' || command === '-h' || command === '--help') {
-    say(HELP);
-    return command ? 0 : 1;
-  }
-  if (command === 'version' || command === '-v' || command === '--version') {
-    const pkg = readPkg();
-    const server = await loadServer();
-    say(pkg.version || 'unknown');
-    if (server.ok && server.mod?.SERVER_VERSION && server.mod.SERVER_VERSION !== pkg.version) {
-      fail(`warning: the connector inside this package reports ${server.mod.SERVER_VERSION}. Those should match.`);
-      return 1;
-    }
-    return 0;
-  }
-  if (command === 'install') return cmdInstall(key, name);
-  if (command === 'update') return cmdUpdate(key, name);
-  if (command === 'doctor') return cmdDoctor(key, name);
-
-  fail(`kmhub: "${command}" is not a command.`);
-  fail('');
-  fail(HELP);
-  return 2;
-}
-
-main()
-  .then((code) => {
-    process.exitCode = code || 0;
-  })
-  .catch((e) => {
-    // Nothing above is supposed to throw. If something does, say so plainly and
-    // point at the one command that is built to survive a broken install.
-    fail(`kmhub: unexpected failure: ${String(e?.stack || e?.message || e)}`);
-    fail(`If this was install or update, try:  npx ${PKG_NAME} doctor`);
-    process.exitCode = 1;
-  });
+#!/usr/bin/env node
+/**
+ * kmhub - the Terminal Mode command line tool.
+ *
+ * Three jobs, and only three:
+ *
+ *   kmhub install <key> [name]   register the connector in this machine's Claude Code
+ *   kmhub update  [key] [name]   is this build still one KM Hub serves
+ *   kmhub doctor  [key] [name]   why is it not working
+ *
+ * The whole point of this file is that a client never types an absolute path
+ * again. The old instruction was `claude mcp add kmhub -e KEY=... -- node
+ * /absolute/path/to/kmhub/mcp-server/index.mjs`, which only works if they cloned
+ * a private repo first and then got the path right. Published on npm, the same
+ * job is `npx @kivimedia/kmhub install kmh_live_...` and the connector is
+ * launched by npx from then on, so it updates itself when Claude Code restarts.
+ *
+ * Where the work actually happens is worth stating plainly, because it decides
+ * what this tool is allowed to do. Terminal Mode runs on the CLIENT machine,
+ * inside THEIR Claude Code, on THEIR Claude subscription. Nothing here schedules
+ * anything, runs an agent, or phones home. It registers a connector, reads two
+ * public-to-the-key endpoints (GET /me and GET /version), and reports.
+ *
+ * Deliberately dependency free. It imports node builtins and, only where it has
+ * something to say about them, the connector's own modules. `doctor` has to be
+ * the command that works when everything else is broken, so it cannot rely on
+ * the thing it is diagnosing being importable.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// The published package name. Every registration points at this, never at a path
+// on the client's disk, which is the entire reason this file exists.
+const PKG_NAME = '@kivimedia/kmhub';
+
+/** The MCP server name a connector is registered under unless the user picks another. */
+const DEFAULT_CONNECTOR = 'kmhub';
+
+/**
+ * Mirrors DEFAULT_BASE in tools.mjs. Duplicated on purpose: `doctor` has to be
+ * able to reach KM Hub even when tools.mjs is the thing that will not load, and
+ * "I cannot tell you anything because my own import failed" is a useless answer
+ * to a support ticket. When tools.mjs does load, its value wins.
+ */
+const FALLBACK_BASE = 'https://jpwbosrmkibsdgckowsm.supabase.co/functions/v1/kmhub-api';
+
+/** Keys are minted as kmh_live_ plus hex. The API matches the same shape before it looks anything up. */
+const KEY_RE = /^kmh_live_[0-9a-f]+$/i;
+
+/**
+ * Where people who use Codex, Cursor or Grok Build are sent. This tool only knows how to
+ * register into Claude Code; the installers behind this page wire all four apps.
+ */
+const SETUP_URL = 'https://hub.kivimedia.co/terminal/';
+
+/** A connector name has to survive being an argv element and a JSON key. */
+const NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
+const HELP = `kmhub, the KM Hub Terminal Mode command line tool.
+
+  npx ${PKG_NAME} install <kmh_live_key> [connector-name]
+      Register the KM Hub connector in Claude Code on this machine.
+      Verifies the key against KM Hub first, so a bad key never gets registered.
+
+  npx ${PKG_NAME} update [kmh_live_key] [connector-name]
+      Ask KM Hub what it publishes today and say whether this build is still one
+      it serves.
+
+  npx ${PKG_NAME} doctor [kmh_live_key] [connector-name]
+      Diagnose a broken install: Claude Code, the registration, the key, the
+      subscription, and whether the connector files load at all.
+
+  The key is optional for update and doctor. They look, in order, at the argument
+  you passed, then KMHUB_API_KEY in the environment, then the key stored in the
+  registration itself.
+
+  Create a key in KM Hub under Settings > Connect > Developer & API.
+  Set KMHUB_API_BASE to point at a different KM Hub.
+
+  This tool registers Claude Code only. For Codex, Cursor or Grok Build, use the
+  KM Hub setup instead, which connects the app you pick and needs no key:
+  ${SETUP_URL}
+`;
+
+// ---------------------------------------------------------------------------
+// small output helpers
+// ---------------------------------------------------------------------------
+
+function say(line = '') {
+  process.stdout.write(`${line}\n`);
+}
+
+function fail(line = '') {
+  process.stderr.write(`${line}\n`);
+}
+
+/** Fixed width labels so a doctor report reads as a column, not a paragraph. */
+function statusLine(status, label, detail) {
+  const tag = { ok: 'ok  ', warn: 'warn', fail: 'FAIL' }[status] || '    ';
+  return `  ${tag}  ${label}${detail ? `: ${detail}` : ''}`;
+}
+
+/** Never print a whole key. Enough to recognise it, not enough to use it. */
+function maskKey(key) {
+  if (typeof key !== 'string' || key.length < 16) return '(unreadable)';
+  return `${key.slice(0, 13)}...${key.slice(-4)}`;
+}
+
+// ---------------------------------------------------------------------------
+// the connector's own modules
+// ---------------------------------------------------------------------------
+
+/** This package's own package.json, read from disk rather than imported. */
+function readPkg() {
+  try {
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Load tools.mjs, which is where the connector's real identity lives
+ * (SERVER_VERSION, the families that loaded, the API base).
+ *
+ * This is a genuine diagnostic and not just a version read. tools.mjs scans
+ * tools/ at import time, so if a family file is missing or a dependency did not
+ * install, the import is where that shows up. Failure is captured, never thrown:
+ * `doctor` reporting "your install is broken, here is the error" is the answer
+ * the support ticket needed.
+ */
+async function loadServer() {
+  try {
+    const mod = await import(new URL('../tools.mjs', import.meta.url));
+    return { ok: true, mod };
+  } catch (e) {
+    return { ok: false, error: String(e?.message || e) };
+  }
+}
+
+function apiBase(server) {
+  const fromEnv = typeof process.env.KMHUB_API_BASE === 'string' ? process.env.KMHUB_API_BASE.trim() : '';
+  if (fromEnv) return fromEnv;
+  const fromServer = server?.ok ? server.mod?.DEFAULT_BASE : '';
+  return typeof fromServer === 'string' && fromServer ? fromServer : FALLBACK_BASE;
+}
+
+// ---------------------------------------------------------------------------
+// KM Hub
+// ---------------------------------------------------------------------------
+
+/**
+ * One GET against kmhub-api with the org key. Never throws: a dead network is a
+ * result to report, not a stack trace to print at somebody who wanted an answer.
+ */
+async function api(base, key, path, timeoutMs = 15000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const r = await fetch(`${base}${path}`, {
+      headers: { Authorization: `Bearer ${key}`, 'content-type': 'application/json' },
+      signal: controller.signal,
+    });
+    const raw = await r.text();
+    let data;
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      data = raw;
+    }
+    return { ok: r.ok, status: r.status, data };
+  } catch (e) {
+    const aborted = e?.name === 'AbortError';
+    return {
+      ok: false,
+      status: 0,
+      data: null,
+      error: aborted ? `no answer within ${Math.round(timeoutMs / 1000)}s` : String(e?.message || e),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Turn a failed call into a sentence a working performer can act on.
+ *
+ * The 402 case is the one that matters most. kmhub-api runs the entitlement gate
+ * before every route, so a lapsed subscription answers 402 on everything,
+ * including GET /version. Left as a status code that reads like the software
+ * broke. It did not, and the wording says so: nothing changed, nothing is gone,
+ * here is the one thing to do.
+ */
+function explain(res, base) {
+  const body = res && res.data && typeof res.data === 'object' ? res.data : {};
+  const message = typeof body.message === 'string' && body.message.trim() ? body.message.trim() : '';
+
+  if (res.status === 0) {
+    return [
+      `Could not reach KM Hub at ${base} (${res.error || 'no answer'}).`,
+      'That is a network or DNS problem on this machine, not your key. Check the connection and try again.',
+    ].join('\n');
+  }
+  if (res.status === 401) {
+    return [
+      'KM Hub did not accept that key. It is either mistyped or it has been revoked.',
+      'Create a fresh one in KM Hub under Settings > Connect > Developer & API, then run this again with the new key.',
+    ].join('\n');
+  }
+  if (res.status === 402) {
+    return [
+      'Your KM Hub subscription is not active, so the connector is switched off at the server.',
+      'Nothing in your workspace has changed, and none of your data has gone anywhere.',
+      message,
+      'Sign in at https://hub.kivimedia.co and restart the subscription under Settings > Billing. Once that is done this works again on the next call, with nothing to reinstall.',
+    ]
+      .filter(Boolean)
+      .join('\n');
+  }
+  if (res.status === 403) {
+    return [
+      `This key does not carry the scope that call needs${message ? ` (${message})` : ''}.`,
+      'A read-only key can read your workspace but cannot create anything. Mint a key with write scope in Settings > Connect > Developer & API if you need the create tools.',
+    ].join('\n');
+  }
+  if (res.status === 429) {
+    return `KM Hub rate limited this key${message ? `: ${message}` : '.'} Wait a minute and try again.`;
+  }
+  if (res.status >= 500) {
+    return `KM Hub answered ${res.status}${message ? `: ${message}` : '.'} That is a problem on the KM Hub side, not on this machine. Try again shortly.`;
+  }
+  return `KM Hub answered ${res.status}${message ? `: ${message}` : ''}.`;
+}
+
+// ---------------------------------------------------------------------------
+// finding an existing registration
+// ---------------------------------------------------------------------------
+
+/**
+ * The files a Claude client stores MCP server registrations in. Read only, and
+ * every one of them is optional: a machine with none of these is simply a
+ * machine where nothing is registered yet, which is a finding, not an error.
+ */
+function candidateConfigs() {
+  const home = homedir();
+  const files = [
+    { file: join(home, '.claude.json'), label: 'Claude Code (user)' },
+    { file: join(process.cwd(), '.mcp.json'), label: 'Claude Code (this project)' },
+  ];
+  if (process.platform === 'win32' && process.env.APPDATA) {
+    files.push({ file: join(process.env.APPDATA, 'Claude', 'claude_desktop_config.json'), label: 'Claude Desktop' });
+  } else if (process.platform === 'darwin') {
+    files.push({
+      file: join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
+      label: 'Claude Desktop',
+    });
+  } else {
+    files.push({ file: join(home, '.config', 'Claude', 'claude_desktop_config.json'), label: 'Claude Desktop' });
+  }
+  return files;
+}
+
+/**
+ * Every place a config file can hold a server entry under this name. The file it
+ * came from already says which client and which scope, so a top level entry adds
+ * nothing and says nothing. Only a per-project entry needs naming, because there
+ * can be many and only one of them is the directory the client is working in.
+ */
+function entriesInConfig(json, name) {
+  const found = [];
+  const top = json?.mcpServers?.[name];
+  if (top && typeof top === 'object') found.push({ entry: top, where: '' });
+  const projects = json?.projects;
+  if (projects && typeof projects === 'object') {
+    for (const [path, project] of Object.entries(projects)) {
+      const entry = project?.mcpServers?.[name];
+      if (entry && typeof entry === 'object') found.push({ entry, where: `project ${path}` });
+    }
+  }
+  return found;
+}
+
+function findRegistrations(name) {
+  const found = [];
+  for (const candidate of candidateConfigs()) {
+    if (!existsSync(candidate.file)) continue;
+    let json;
+    try {
+      json = JSON.parse(readFileSync(candidate.file, 'utf8'));
+    } catch {
+      found.push({ ...candidate, unreadable: true });
+      continue;
+    }
+    for (const hit of entriesInConfig(json, name)) found.push({ ...candidate, ...hit });
+  }
+  return found;
+}
+
+/** A registration can carry the key as a stdio env var or as a remote Bearer header. */
+function keyFromEntry(entry) {
+  const fromEnv = entry?.env?.KMHUB_API_KEY;
+  if (typeof fromEnv === 'string' && KEY_RE.test(fromEnv.trim())) return fromEnv.trim();
+  const headers = entry?.headers && typeof entry.headers === 'object' ? entry.headers : {};
+  for (const value of Object.values(headers)) {
+    if (typeof value !== 'string') continue;
+    const m = value.match(/Bearer\s+(kmh_live_[0-9a-f]+)/i);
+    if (m) return m[1];
+  }
+  return '';
+}
+
+/**
+ * Where the key comes from, most explicit first: the argument, then the
+ * environment, then whatever the existing registration already holds. That last
+ * one is what makes `doctor` answer a support ticket without asking the client
+ * to go and find their key.
+ */
+function resolveKey(argKey, registrations) {
+  if (argKey) return { key: argKey, source: 'the key you passed' };
+  const fromEnv = typeof process.env.KMHUB_API_KEY === 'string' ? process.env.KMHUB_API_KEY.trim() : '';
+  if (fromEnv) return { key: fromEnv, source: 'KMHUB_API_KEY in this environment' };
+  for (const reg of registrations) {
+    const key = keyFromEntry(reg.entry);
+    if (key) return { key, source: `the registration in ${reg.label}` };
+  }
+  return { key: '', source: '' };
+}
+
+// ---------------------------------------------------------------------------
+// running the claude CLI
+// ---------------------------------------------------------------------------
+
+/**
+ * Windows needs a shell to launch the `claude` .cmd shim, and a shell means argv
+ * is re-parsed. Everything this file passes (a key, a connector name, a package
+ * name, npx flags) is validated before it gets here rather than escaped after,
+ * so quoting is only ever a safety net.
+ */
+function quoteArg(arg) {
+  if (/^[A-Za-z0-9_@:.,/=+-]+$/.test(arg)) return arg;
+  return `"${String(arg).replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * On Windows the whole thing goes in as ONE already-quoted string. Handing
+ * spawnSync an args array together with shell:true is deprecated from Node 22
+ * (DEP0190) precisely because the args are concatenated rather than escaped, and
+ * it prints a warning at the client that has nothing to do with their problem.
+ * Everywhere else there is no shell at all, which is the safer path anyway.
+ */
+function runCli(cmd, args, timeoutMs = 120000) {
+  const useShell = process.platform === 'win32';
+  const r = useShell
+    ? spawnSync([cmd, ...args].map(quoteArg).join(' '), {
+        encoding: 'utf8',
+        shell: true,
+        timeout: timeoutMs,
+      })
+    : spawnSync(cmd, args, {
+        encoding: 'utf8',
+        timeout: timeoutMs,
+      });
+  const stdout = (r.stdout || '').trim();
+  const stderr = (r.stderr || '').trim();
+  // ENOENT is how a missing binary surfaces without a shell. With cmd.exe in the
+  // way it comes back as an exit code plus a message instead, so test for both.
+  const missing =
+    (r.error && (r.error.code === 'ENOENT' || /ENOENT/.test(String(r.error.message || '')))) ||
+    /is not recognized as an internal or external command|command not found|no such file or directory/i.test(
+      `${stderr}\n${stdout}`,
+    );
+  return {
+    ok: !r.error && r.status === 0,
+    status: r.status,
+    stdout,
+    stderr,
+    missing: Boolean(missing),
+    error: r.error ? String(r.error.message || r.error) : '',
+  };
+}
+
+/** The argv the connector is registered with. npx resolves the package at launch, never a local path. */
+function connectorCommand() {
+  return ['npx', '-y', '--package', PKG_NAME, 'kmhub-mcp'];
+}
+
+function desktopConfigBlock(name, key) {
+  return JSON.stringify(
+    {
+      mcpServers: {
+        [name]: {
+          command: 'npx',
+          args: ['-y', '--package', PKG_NAME, 'kmhub-mcp'],
+          env: { KMHUB_API_KEY: key },
+        },
+      },
+    },
+    null,
+    2,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// version comparison
+// ---------------------------------------------------------------------------
+
+/**
+ * Compare two semver-ish strings. Build metadata after a plus is dropped before
+ * comparing, because the rules pack stamps itself as base plus a content hash
+ * and the hash is not an ordering. Returns negative, zero or positive.
+ */
+function cmpVersion(a, b) {
+  const parts = (v) =>
+    String(v || '')
+      .trim()
+      .split('+')[0]
+      .split('-')[0]
+      .split('.')
+      .map((n) => Number.parseInt(n, 10) || 0);
+  const left = parts(a);
+  const right = parts(b);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const d = (left[i] || 0) - (right[i] || 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// install
+// ---------------------------------------------------------------------------
+
+async function cmdInstall(key, name) {
+  if (!key) {
+    fail('kmhub install needs your KM Hub API key.');
+    fail('');
+    fail(`  npx ${PKG_NAME} install kmh_live_xxxxxxxx`);
+    fail('');
+    // Say what was done with what they did type. Anything not shaped like a key
+    // is read as a connector name, and silently doing that to a mistyped key is
+    // how somebody spends ten minutes on a message that looks wrong.
+    if (name !== DEFAULT_CONNECTOR) {
+      fail(`I read "${name}" as the connector name, not as a key. A key starts with kmh_live_.`);
+      fail('');
+    }
+    fail('Create one in KM Hub under Settings > Connect > Developer & API.');
+    return 2;
+  }
+  if (!KEY_RE.test(key)) {
+    fail('That does not look like a KM Hub API key.');
+    fail('A key starts with kmh_live_ and is followed by hex. Copy it again from Settings > Connect > Developer & API.');
+    return 2;
+  }
+  if (!NAME_RE.test(name)) {
+    fail(`"${name}" is not a usable connector name. Use letters, numbers, dash or underscore.`);
+    return 2;
+  }
+
+  const server = await loadServer();
+  const base = apiBase(server);
+
+  // 1. The key, before anything is written anywhere. Registering a dead key just
+  //    moves the failure to the first tool call, where it is much harder to read.
+  say('Checking the key with KM Hub...');
+  const me = await api(base, key, '/me');
+  if (!me.ok) {
+    fail('');
+    fail(explain(me, base));
+    fail('');
+    fail('Nothing was registered. Your Claude Code configuration is untouched.');
+    return 1;
+  }
+
+  const org = me.data?.org && typeof me.data.org === 'object' ? me.data.org : {};
+  const scopes = Array.isArray(me.data?.scopes) ? me.data.scopes : [];
+  const workspace = typeof org.name === 'string' && org.name.trim() ? org.name.trim() : 'your workspace';
+  const plan = typeof org.plan === 'string' && org.plan.trim() ? org.plan.trim() : '';
+
+  say(`Key accepted. Workspace: ${workspace}${plan ? ` (plan ${plan})` : ''}.`);
+  say(`Scopes on this key: ${scopes.length ? scopes.join(', ') : 'none reported'}.`);
+  if (scopes.length && !scopes.includes('write')) {
+    say('');
+    say('Note: this key is read only. The connector will read your workspace, and any tool that');
+    say('creates something will be refused by KM Hub. Mint a key with write scope if you want those.');
+  }
+  say('');
+
+  // 2. Claude Code has to exist before there is anywhere to register.
+  const claude = runCli('claude', ['--version'], 30000);
+  if (claude.missing) {
+    fail('Claude Code is not on this machine, or its `claude` command is not on your PATH.');
+    fail('Install it from https://claude.com/claude-code and run this again.');
+    fail('');
+    fail('If you are setting up Claude Desktop instead, put this in your claude_desktop_config.json:');
+    fail('');
+    fail(desktopConfigBlock(name, key));
+    fail('');
+    fail('Using Codex, Cursor or Grok Build instead? This tool only registers Claude Code.');
+    fail(`The KM Hub setup connects the app you pick: ${SETUP_URL}`);
+    return 1;
+  }
+
+  // 3. Register. The command is npx and the package name, never a path on disk,
+  //    so restarting Claude Code is all it takes to pick up a newer build.
+  const args = ['mcp', 'add', name, '--scope', 'user', '-e', `KMHUB_API_KEY=${key}`, '--', ...connectorCommand()];
+  say(`Registering the connector as "${name}"...`);
+  const add = runCli('claude', args);
+  if (!add.ok) {
+    const output = `${add.stdout}\n${add.stderr}`.trim();
+    fail('');
+    fail(`Claude Code refused to add the connector${add.status ? ` (exit ${add.status})` : ''}.`);
+    if (output) fail(output);
+    if (/already exists|already configured/i.test(output)) {
+      fail('');
+      fail(`A connector called "${name}" is already registered. Remove it and run this again:`);
+      fail('');
+      fail(`  claude mcp remove ${name} --scope user`);
+      fail(`  npx ${PKG_NAME} install ${maskKey(key)} ${name}`);
+      fail('');
+      fail('(use the real key, not the masked one above)');
+    }
+    return 1;
+  }
+
+  say('');
+  say(`Done. ${workspace} is connected to Claude Code on this machine.`);
+  say('');
+  say('Open Claude Code and type this:');
+  say('');
+  say('  Ask KM Hub what needs me today.');
+  say('');
+  say('Two things worth knowing:');
+  say(`  1. The key is stored in your Claude Code config. If it ever leaks, revoke it in KM Hub`);
+  say('     under Settings > Connect > Developer & API and run this install again with a fresh one.');
+  say(`  2. The connector is launched with npx, so restarting Claude Code picks up new builds.`);
+  say(`     Run  npx ${PKG_NAME} doctor  if anything ever looks wrong.`);
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// update
+// ---------------------------------------------------------------------------
+
+async function cmdUpdate(argKey, name) {
+  const server = await loadServer();
+  const base = apiBase(server);
+  const pkg = readPkg();
+  const installed = server.ok && typeof server.mod?.SERVER_VERSION === 'string' ? server.mod.SERVER_VERSION : '';
+
+  say('KM Hub connector');
+  say('');
+  if (!server.ok) {
+    say(statusLine('fail', 'this build', 'the connector modules would not load'));
+    say(`        ${server.error}`);
+    say(`        Run  npx ${PKG_NAME} doctor  for the full picture.`);
+  } else {
+    say(statusLine('ok', 'this build', installed || 'unknown'));
+    if (pkg.version && installed && pkg.version !== installed) {
+      say(
+        statusLine(
+          'warn',
+          'version identity',
+          `package says ${pkg.version} and the server says ${installed}. Report that, it is a packaging bug.`,
+        ),
+      );
+    }
+  }
+
+  const registrations = findRegistrations(name).filter((r) => r.entry);
+  const { key, source } = resolveKey(argKey, registrations);
+  if (!key) {
+    say('');
+    fail('No KM Hub API key to ask with.');
+    fail(`Pass one, or set KMHUB_API_KEY, or install the connector first:  npx ${PKG_NAME} install kmh_live_...`);
+    return 2;
+  }
+  if (!KEY_RE.test(key)) {
+    say('');
+    fail(`The key from ${source} is not shaped like a KM Hub key (kmh_live_ then hex).`);
+    return 2;
+  }
+
+  say('');
+  say(`Asking KM Hub what it publishes today (key from ${source})...`);
+  const v = await api(base, key, '/version');
+  if (!v.ok) {
+    say('');
+    fail(explain(v, base));
+    return 1;
+  }
+
+  const d = v.data && typeof v.data === 'object' ? v.data : {};
+  const minClient = typeof d.min_client === 'string' ? d.min_client : '';
+  const rulesVersion = typeof d.rules_version === 'string' ? d.rules_version : '';
+
+  say('');
+  say('KM Hub publishes:');
+  say(statusLine('ok', 'API', d.api_version || 'not reported'));
+  say(statusLine('ok', 'tool catalogue', d.tools_version || 'not reported'));
+  say(statusLine('ok', 'rules pack', rulesVersion || 'not reported'));
+  say(statusLine('ok', 'oldest client it serves', minClient || 'not reported'));
+  say('');
+
+  // The only hard judgement available. min_client is the floor KM Hub refuses to
+  // serve below; there is no "latest client" field, so anything at or above the
+  // floor is reported as still served rather than dressed up as up to date.
+  if (!installed) {
+    say('This build could not be identified, so whether it is out of date cannot be answered here.');
+    say(`Run  npx ${PKG_NAME} doctor  first: something about the install is wrong.`);
+    return 1;
+  }
+  if (minClient && cmpVersion(installed, minClient) < 0) {
+    say(`OUT OF DATE. This connector is ${installed} and KM Hub no longer serves anything below ${minClient}.`);
+    say('It will stop working. Update it now:');
+    say('');
+    say('  1. Quit Claude Code completely and open it again. The connector is launched with npx,');
+    say('     so a restart fetches the current build on its own.');
+    say('  2. If it is still on the old version after that, re-register it:');
+    say('');
+    say(`       claude mcp remove ${name} --scope user`);
+    say(`       npx ${PKG_NAME}@latest install <your kmh_live_ key> ${name}`);
+    if (d.changelog_url) say(`\n  What changed: ${d.changelog_url}`);
+    return 1;
+  }
+
+  say(`Up to date enough. KM Hub still serves ${installed}${minClient ? ` (its floor is ${minClient})` : ''}.`);
+  say('Nothing to run.');
+  say('');
+  say(`The rules pack KM Hub publishes today is ${rulesVersion || 'not reported'}. This tool does not touch`);
+  say('your rules file. To refresh it, open Claude Code and say: check for KM Hub updates.');
+  say('That runs the connector\'s own update tools, which rewrite the KM Hub block in your CLAUDE.md.');
+  if (d.changelog_url) say(`\nChangelog: ${d.changelog_url}`);
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// doctor
+// ---------------------------------------------------------------------------
+
+/**
+ * The command that answers a support ticket without a call.
+ *
+ * Every check reports one of three things and, when it is not ok, the single
+ * next action. It never stops at the first failure: a client who has three
+ * things wrong should learn all three in one paste, not across three emails.
+ * Exit code is 1 if anything failed, so it is also usable as a gate.
+ */
+async function cmdDoctor(argKey, name) {
+  const checks = [];
+  const record = (status, label, detail, fix) => {
+    checks.push({ status, label, detail, fix });
+    say(statusLine(status, label, detail));
+    if (fix && status !== 'ok') {
+      for (const line of String(fix).split('\n')) say(`        ${line}`);
+    }
+  };
+
+  const pkg = readPkg();
+  say(`kmhub doctor  (${PKG_NAME}${pkg.version ? ` ${pkg.version}` : ''}, connector name "${name}")`);
+  say('');
+
+  // 1. The runtime underneath everything else.
+  const major = Number.parseInt(String(process.versions.node).split('.')[0], 10) || 0;
+  if (major >= 18) {
+    record('ok', 'Node', `${process.version} on ${process.platform}`);
+  } else {
+    record(
+      'fail',
+      'Node',
+      `${process.version} is too old`,
+      'The connector needs Node 18.17 or newer. Install a current Node and run this again.',
+    );
+  }
+
+  // 2. Do the connector's own files load. This is the check that catches a
+  //    half-finished install, a missing dependency, or a broken family file.
+  const server = await loadServer();
+  const installed = server.ok && typeof server.mod?.SERVER_VERSION === 'string' ? server.mod.SERVER_VERSION : '';
+  if (server.ok) {
+    const families = Array.isArray(server.mod?.FAMILY_NAMES) ? server.mod.FAMILY_NAMES : [];
+    const tools = Array.isArray(server.mod?.TOOL_NAMES) ? server.mod.TOOL_NAMES : [];
+    record('ok', 'connector files', `version ${installed || 'unknown'}, ${families.length} families, ${tools.length} tools`);
+  } else {
+    record(
+      'fail',
+      'connector files',
+      'they would not load',
+      `${server.error}\nReinstall the connector:  npx ${PKG_NAME}@latest install <your kmh_live_ key> ${name}`,
+    );
+  }
+
+  // 3. One process, two version numbers. They have disagreed before, so it is a check.
+  if (server.ok && pkg.version && installed) {
+    if (pkg.version === installed) {
+      record('ok', 'version identity', `package and server both say ${installed}`);
+    } else {
+      record(
+        'warn',
+        'version identity',
+        `package says ${pkg.version}, server says ${installed}`,
+        'That is a packaging bug on our side, not something you can fix. Send this report to KM Hub.',
+      );
+    }
+  }
+
+  // 4. Is there a Claude Code to be registered in.
+  const claude = runCli('claude', ['--version'], 30000);
+  if (claude.missing) {
+    record(
+      'fail',
+      'Claude Code',
+      'the `claude` command was not found',
+      'Install it from https://claude.com/claude-code, then run the install again.',
+    );
+  } else if (claude.ok) {
+    record('ok', 'Claude Code', claude.stdout.split('\n')[0] || 'installed');
+  } else {
+    record('warn', 'Claude Code', `\`claude --version\` exited ${claude.status ?? 'oddly'}`, claude.stderr || claude.error);
+  }
+
+  // 5. Is the connector actually registered, and where.
+  const registrations = findRegistrations(name);
+  const usable = registrations.filter((r) => r.entry);
+  if (usable.length) {
+    for (const reg of usable) {
+      const cmd = Array.isArray(reg.entry.args)
+        ? `${reg.entry.command} ${reg.entry.args.join(' ')}`
+        : reg.entry.command || reg.entry.url || 'no command recorded';
+      record('ok', 'registration', `${reg.label}${reg.where ? `, ${reg.where}` : ''}: ${cmd}`);
+    }
+  } else {
+    const unreadable = registrations.filter((r) => r.unreadable);
+    record(
+      'fail',
+      'registration',
+      `no connector called "${name}" in any Claude config on this machine`,
+      `${unreadable.length ? `${unreadable.map((u) => u.file).join(', ')} could not be parsed as JSON.\n` : ''}Register it:  npx ${PKG_NAME} install <your kmh_live_ key> ${name}`,
+    );
+  }
+
+  // 6. A key to test with.
+  const { key, source } = resolveKey(argKey, usable);
+  const base = apiBase(server);
+  if (!key) {
+    record(
+      'fail',
+      'API key',
+      'none found',
+      `Pass it:  npx ${PKG_NAME} doctor <your kmh_live_ key>\nOr set KMHUB_API_KEY in this shell.`,
+    );
+  } else if (!KEY_RE.test(key)) {
+    record(
+      'fail',
+      'API key',
+      `the value from ${source} is not shaped like a KM Hub key`,
+      'A key starts with kmh_live_ and is followed by hex. Copy it again from Settings > Connect > Developer & API.',
+    );
+  } else {
+    record('ok', 'API key', `${maskKey(key)} from ${source}`);
+  }
+
+  // 7 and 8. Authentication and entitlement, in one call. kmhub-api checks the
+  //    key first and the subscription second, so a 401 says nothing about
+  //    billing and a 402 says the key is fine and the subscription is not.
+  if (key && KEY_RE.test(key)) {
+    const me = await api(base, key, '/me');
+    if (me.ok) {
+      const org = me.data?.org && typeof me.data.org === 'object' ? me.data.org : {};
+      const scopes = Array.isArray(me.data?.scopes) ? me.data.scopes : [];
+      const workspace = typeof org.name === 'string' && org.name.trim() ? org.name.trim() : 'unnamed workspace';
+      record('ok', 'key authenticates', `${workspace}${org.plan ? ` (plan ${org.plan})` : ''}`);
+      record('ok', 'subscription', 'active, KM Hub is serving this workspace');
+      if (scopes.length && !scopes.includes('write')) {
+        record(
+          'warn',
+          'scopes',
+          `${scopes.join(', ')} only`,
+          'Read tools work. Anything that creates something will be refused. Mint a key with write scope if you need those.',
+        );
+      } else {
+        record('ok', 'scopes', scopes.length ? scopes.join(', ') : 'none reported');
+      }
+    } else if (me.status === 402) {
+      record('ok', 'key authenticates', 'the key itself is valid, KM Hub recognised it');
+      record('fail', 'subscription', 'not active', explain(me, base));
+    } else {
+      record('fail', 'key authenticates', `KM Hub answered ${me.status || 'nothing'}`, explain(me, base));
+      record('warn', 'subscription', 'cannot be checked until the key works');
+    }
+
+    // 9. Only meaningful once the key works.
+    if (me.ok) {
+      const v = await api(base, key, '/version');
+      if (!v.ok) {
+        record('warn', 'client version floor', 'KM Hub did not answer GET /version', explain(v, base));
+      } else {
+        const minClient = typeof v.data?.min_client === 'string' ? v.data.min_client : '';
+        if (!installed || !minClient) {
+          record('warn', 'client version floor', 'not enough information to judge');
+        } else if (cmpVersion(installed, minClient) < 0) {
+          record(
+            'fail',
+            'client version floor',
+            `this build is ${installed} and KM Hub serves nothing below ${minClient}`,
+            `Restart Claude Code to pull the current build, or re-register:\n  claude mcp remove ${name} --scope user\n  npx ${PKG_NAME}@latest install <your kmh_live_ key> ${name}`,
+          );
+        } else {
+          record('ok', 'client version floor', `${installed} is at or above ${minClient}`);
+        }
+      }
+    }
+  }
+
+  const failed = checks.filter((c) => c.status === 'fail');
+  const warned = checks.filter((c) => c.status === 'warn');
+  say('');
+  if (!failed.length && !warned.length) {
+    say('Everything checks out. If a tool still misbehaves, the problem is in the conversation,');
+    say('not the connection: say what you asked for and what came back.');
+    return 0;
+  }
+  say(`${failed.length} failed, ${warned.length} to be aware of.`);
+  if (failed.length) {
+    say('');
+    say(`Next: ${failed[0].label}.`);
+    if (failed[0].fix) for (const line of String(failed[0].fix).split('\n')) say(`  ${line}`);
+    return 1;
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// argv
+// ---------------------------------------------------------------------------
+
+/**
+ * No flags to learn. A KM Hub key is unmistakable, so any argument that looks
+ * like one is the key and anything else is the connector name, whatever order
+ * they arrive in.
+ */
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  let key = '';
+  let name = '';
+  for (const arg of rest) {
+    if (!arg) continue;
+    if (/^kmh_live_/i.test(arg)) {
+      if (!key) key = arg.trim();
+    } else if (!name) {
+      name = arg.trim();
+    }
+  }
+  return { command: (command || '').toLowerCase(), key, name: name || DEFAULT_CONNECTOR };
+}
+
+async function main() {
+  const { command, key, name } = parseArgs(process.argv.slice(2));
+
+  if (!command || command === 'help' || command === '-h' || command === '--help') {
+    say(HELP);
+    return command ? 0 : 1;
+  }
+  if (command === 'version' || command === '-v' || command === '--version') {
+    const pkg = readPkg();
+    const server = await loadServer();
+    say(pkg.version || 'unknown');
+    if (server.ok && server.mod?.SERVER_VERSION && server.mod.SERVER_VERSION !== pkg.version) {
+      fail(`warning: the connector inside this package reports ${server.mod.SERVER_VERSION}. Those should match.`);
+      return 1;
+    }
+    return 0;
+  }
+  if (command === 'install') return cmdInstall(key, name);
+  if (command === 'update') return cmdUpdate(key, name);
+  if (command === 'doctor') return cmdDoctor(key, name);
+
+  fail(`kmhub: "${command}" is not a command.`);
+  fail('');
+  fail(HELP);
+  return 2;
+}
+
+main()
+  .then((code) => {
+    process.exitCode = code || 0;
+  })
+  .catch((e) => {
+    // Nothing above is supposed to throw. If something does, say so plainly and
+    // point at the one command that is built to survive a broken install.
+    fail(`kmhub: unexpected failure: ${String(e?.stack || e?.message || e)}`);
+    fail(`If this was install or update, try:  npx ${PKG_NAME} doctor`);
+    process.exitCode = 1;
+  });