@skyelight/mcp 0.4.1 → 0.5.1

package/src/cli.js

@@ -11,6 +11,11 @@
  * It shows the change and waits, like `@skyelight/build init` does. Editing
  * a config somebody else wrote is the kind of help that has to ask first.
  * `--yes` exists for people who have already read it once.
+ *
+ * Several agents used to be a dead end: it printed the list and exited 1, as
+ * though having two editors were an error. Most developers have more than
+ * one, so the commonest case on the first command anybody runs was a refusal.
+ * It asks now, and `--client` still answers in advance for a script.
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
@@ -24,18 +29,26 @@ import {
   findClient,
   addToJson,
   addToToml,
+  removeFromJson,
+  removeFromToml,
 } from "./install.js";
-
-const bold = (s) => `\x1b[1m${s}\x1b[0m`;
-const dim = (s) => `\x1b[2m${s}\x1b[0m`;
-const green = (s) => `\x1b[32m${s}\x1b[0m`;
-const amber = (s) => `\x1b[33m${s}\x1b[0m`;
+import {
+  bold,
+  dim,
+  green,
+  amber,
+  brand,
+  header,
+  heading,
+  pad,
+  MARK,
+} from "./theme.js";
 
 /**
  * Which deployment to register. Production unless told otherwise.
  */
 const ORIGIN = (
-  process.env.SKYELIGHT_URL ?? "https://mellow-zebra-383.convex.site"
+  process.env.SKYELIGHT_URL ?? "https://app.skyelight.ai"
 ).replace(/\/+$/, "");
 
 /**
@@ -64,85 +77,102 @@ async function fetchConfig() {
   return body;
 }
 
-async function confirm(question) {
-  if (!process.stdin.isTTY) return false;
+/** The host being configured, for the header. Not the whole URL — it is the */
+/** part that tells you whether you are pointed somewhere unexpected. */
+function originLabel() {
+  try {
+    return new URL(ORIGIN).host;
+  } catch {
+    return ORIGIN;
+  }
+}
+
+async function ask(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    return /^y(es)?$/i.test((await rl.question(`${question} [y/N] `)).trim());
+    return (await rl.question(`  ${question} ${brand(MARK.arrow)} `)).trim();
   } finally {
     rl.close();
   }
 }
 
-function listClients() {
-  console.log("Say which one with:\n");
-  for (const c of CLIENTS) {
-    console.log(`  ${bold(`npx @skyelight/mcp init --client ${c.id}`)}  ${dim(c.label)}`);
+async function confirm(question) {
+  // No terminal, no question. A CI run should not hang on a prompt nobody is
+  // there to answer, and `--yes` is how it says so deliberately.
+  if (!process.stdin.isTTY) return false;
+  return /^y(es)?$/i.test(await ask(`${question} ${dim("[y/N]")}`));
+}
+
+/**
+ * Which agent, when several are on the machine.
+ *
+ * A numbered prompt rather than a list of commands to go and retype. The
+ * commands are still printed underneath, because somebody scripting this
+ * needs them and because the prompt is unavailable without a terminal.
+ */
+async function choose(found) {
+  console.log(`  Found ${bold(found.length)} agents.\n`);
+  found.forEach((c, i) => {
+    console.log(`    ${brand(String(i + 1))}  ${c.label}`);
+  });
+  console.log(`    ${brand("a")}  ${dim("All of them")}\n`);
+
+  if (!process.stdin.isTTY) {
+    console.log(dim("  Not a terminal, so nothing was chosen. Name one:\n"));
+    listClients();
+    return null;
   }
-  console.log("");
+
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const answer = (
+      await ask(`Which one? ${dim(`[1-${found.length}, a]`)}`)
+    ).toLowerCase();
+    if (answer === "a" || answer === "all") return found;
+    const n = Number(answer);
+    if (Number.isInteger(n) && n >= 1 && n <= found.length) {
+      return [found[n - 1]];
+    }
+    console.log(dim(`  Not one of them.\n`));
+  }
+  return null;
 }
 
-async function init({ yes, clientFlag }) {
-  console.log(`\n${bold("Skyelight MCP")}\n`);
+/** The widest agent id, so the labels line up whatever is in the registry. */
+const ID_WIDTH = Math.max(...CLIENTS.map((c) => c.id.length));
 
-  let config;
-  try {
-    config = await fetchConfig();
-  } catch (err) {
-    console.log(amber(`Could not reach Skyelight: ${err.message}\n`));
+function listClients() {
+  for (const c of CLIENTS) {
     console.log(
-      dim("  Point at another deployment with SKYELIGHT_URL=https://…\n"),
+      `    ${dim("--client")} ${bold(pad(c.id, ID_WIDTH))}  ${dim(c.label)}`,
     );
-    process.exitCode = 1;
-    return;
   }
-  const { url: MCP_URL, clientId: CLIENT_ID, callbackPort } = config;
+  console.log("");
+}
 
-  let client;
-  if (clientFlag) {
-    client = findClient(clientFlag);
-    if (!client) {
-      console.log(amber(`Unknown agent "${clientFlag}".\n`));
-      listClients();
-      process.exitCode = 1;
-      return;
-    }
-  } else {
-    const found = detectClients();
-    if (found.length === 0) {
-      console.log(amber("No coding agent found on this machine.\n"));
-      listClients();
-      process.exitCode = 1;
-      return;
-    }
-    if (found.length > 1) {
-      console.log(
-        `Found ${found.map((c) => bold(c.label)).join(", ")}.\n`,
-      );
-      listClients();
-      process.exitCode = 1;
-      return;
-    }
-    client = found[0];
-    console.log(`Found ${bold(client.label)}.\n`);
-  }
+/**
+ * Register one agent. Returns whether anything changed, so the summary at
+ * the end can tell "added" from "already there" without guessing.
+ */
+async function register(client, config, { yes, quiet }) {
+  const { url: MCP_URL, clientId: CLIENT_ID, callbackPort } = config;
 
   // Claude Code registers through its own CLI — see `install.js`.
   if (client.command) {
     const [bin, args] = client.command(MCP_URL, CLIENT_ID, callbackPort);
-    console.log(dim(`  ${bin} ${args.join(" ")}\n`));
+    console.log(`  ${bold(client.label)}`);
+    console.log(dim(`    ${bin} ${args.join(" ")}\n`));
     if (!yes && !(await confirm("Run it?"))) {
-      console.log(dim("\nNothing changed.\n"));
-      return;
+      console.log(dim("\n  Nothing changed.\n"));
+      return "skipped";
     }
-    const res = spawnSync(bin, args, { stdio: "inherit" });
+    const res = spawnSync(bin, args, { stdio: quiet ? "ignore" : "inherit" });
     if (res.status !== 0) {
-      console.log(amber("\nThat command failed. Run it yourself to see why.\n"));
-      process.exitCode = 1;
-      return;
+      console.log(
+        amber(`\n  That command failed. Run it yourself to see why.\n`),
+      );
+      return "failed";
     }
-    done(client);
-    return;
+    return "added";
   }
 
   const file = client.file();
@@ -153,48 +183,291 @@ async function init({ yes, clientFlag }) {
       : addToToml(before, client.entry(MCP_URL, CLIENT_ID));
 
   if (after === null) {
-    console.log(green(`Already set up in ${file}\n`));
-    return;
+    console.log(
+      `  ${green(MARK.tick)} ${client.label} ${dim("— already set up")}`,
+    );
+    return "already";
   }
 
-  console.log(`${bold(file)}\n`);
+  console.log(`  ${bold(client.label)}`);
+  console.log(dim(`    ${file}`));
   console.log(
     dim(
       client.format === "json"
-        ? `  mcpServers.${SERVER_NAME} → ${MCP_URL}`
-        : `  [mcp_servers.${SERVER_NAME}] → ${MCP_URL}`,
+        ? `    mcpServers.${SERVER_NAME} → ${MCP_URL}\n`
+        : `    [mcp_servers.${SERVER_NAME}] → ${MCP_URL}\n`,
     ),
   );
-  console.log("");
 
   if (!yes && !(await confirm("Write it?"))) {
-    console.log(dim("\nNothing written.\n"));
-    return;
+    console.log(dim("\n  Nothing written.\n"));
+    return "skipped";
   }
 
   mkdirSync(dirname(file), { recursive: true });
   writeFileSync(file, after, "utf8");
-  done(client);
+  return "added";
+}
+
+/**
+ * Take the server back out of one agent.
+ *
+ * Symmetrical with `register` on purpose, including the confirmation: the
+ * file belongs to whoever configured it, and a command that edits it without
+ * showing what it is about to do is the thing `init` deliberately is not.
+ */
+async function unregister(client, { yes, quiet }) {
+  if (client.removeCommand) {
+    const [bin, args] = client.removeCommand();
+    console.log(`  ${bold(client.label)}`);
+    console.log(dim(`    ${bin} ${args.join(" ")}\n`));
+    if (!yes && !(await confirm("Run it?"))) {
+      console.log(dim("\n  Nothing changed.\n"));
+      return "skipped";
+    }
+    const res = spawnSync(bin, args, { stdio: quiet ? "ignore" : "inherit" });
+    // A client that had no such server exits non-zero saying so, which is
+    // the answer rather than a failure — `remove` is meant to be safe to
+    // run twice.
+    return res.status === 0 ? "removed" : "absent";
+  }
+
+  const file = client.file();
+  if (!existsSync(file)) {
+    console.log(
+      `  ${dim(MARK.dot)} ${client.label} ${dim("— nothing to remove")}`,
+    );
+    return "absent";
+  }
+  const before = readFileSync(file, "utf8");
+  const after =
+    client.format === "json" ? removeFromJson(before) : removeFromToml(before);
+
+  if (after === null) {
+    console.log(
+      `  ${dim(MARK.dot)} ${client.label} ${dim("— nothing to remove")}`,
+    );
+    return "absent";
+  }
+
+  console.log(`  ${bold(client.label)}`);
+  console.log(dim(`    ${file}`));
+  console.log(
+    dim(
+      client.format === "json"
+        ? `    mcpServers.${SERVER_NAME} ${MARK.arrow} removed\n`
+        : `    [mcp_servers.${SERVER_NAME}] ${MARK.arrow} removed\n`,
+    ),
+  );
+
+  if (!yes && !(await confirm("Write it?"))) {
+    console.log(dim("\n  Nothing written.\n"));
+    return "skipped";
+  }
+  writeFileSync(file, after, "utf8");
+  return "removed";
+}
+
+/**
+ * Which agents to act on. Shared by `init` and `remove` so the two cannot
+ * disagree about what `--client all` means or how a tie is broken.
+ *
+ * `known` is for removal: an agent whose config directory has since been
+ * deleted still fails detection, and somebody uninstalling wants every place
+ * we ever wrote considered rather than only the ones still standing.
+ */
+async function pickTargets({ clientFlag, known = false }) {
+  if (clientFlag === "all") {
+    const all = known ? CLIENTS : detectClients();
+    if (all.length === 0) {
+      console.log(amber("  No coding agent found on this machine.\n"));
+      listClients();
+      return null;
+    }
+    return all;
+  }
+  if (clientFlag) {
+    const one = findClient(clientFlag);
+    if (!one) {
+      console.log(amber(`  Unknown agent "${clientFlag}".\n`));
+      listClients();
+      return null;
+    }
+    return [one];
+  }
+  const found = detectClients();
+  if (found.length === 0) {
+    console.log(amber("  No coding agent found on this machine.\n"));
+    listClients();
+    return null;
+  }
+  if (found.length === 1) {
+    console.log(`  Found ${bold(found[0].label)}.\n`);
+    return found;
+  }
+  const chosen = await choose(found);
+  if (chosen) console.log("");
+  return chosen;
+}
+
+async function remove({ yes, clientFlag }) {
+  console.log(header());
+
+  // Default to every agent we know, not every agent detected. "Uninstall
+  // Skyelight" means everywhere, and asking which one to forget is a
+  // question with no useful wrong answer.
+  const targets = await pickTargets({
+    clientFlag: clientFlag ?? "all",
+    known: true,
+  });
+  if (!targets) {
+    process.exitCode = 1;
+    return;
+  }
+
+  const results = [];
+  for (const client of targets) {
+    results.push({
+      client,
+      outcome: await unregister(client, { yes, quiet: targets.length > 1 }),
+    });
+  }
+
+  const removed = results.filter((r) => r.outcome === "removed");
+  const skipped = results.filter((r) => r.outcome === "skipped");
+  if (removed.length === 0) {
+    // "Not registered anywhere" and "you declined every prompt" are
+    // different facts, and saying the first when the second happened tells
+    // somebody their agent is clean when it is not.
+    console.log(
+      skipped.length
+        ? `\n  ${dim("Nothing was removed.")}\n`
+        : `\n  ${dim("Skyelight was not registered anywhere.")}\n`,
+    );
+    return;
+  }
+  console.log("");
+  for (const r of removed) {
+    console.log(
+      `  ${green(MARK.tick)} ${bold(r.client.label)} ${dim("— removed")}`,
+    );
+  }
+  console.log(
+    `\n${heading("Note")}\n    ${dim(MARK.dot)} Restart the agent for it to notice.`,
+  );
+  console.log(
+    `    ${dim(MARK.dot)} Your sign-in is still valid; revoke it under Account ${MARK.arrow} API Keys\n      or in the agent's own OAuth settings.\n`,
+  );
+}
+
+async function init({ yes, clientFlag }) {
+  console.log(header(originLabel()));
+
+  let config;
+  try {
+    config = await fetchConfig();
+  } catch (err) {
+    console.log(amber(`  Could not reach Skyelight: ${err.message}\n`));
+    console.log(
+      dim("  Point at another deployment with SKYELIGHT_URL=https://…\n"),
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const targets = await pickTargets({ clientFlag });
+  if (!targets) {
+    process.exitCode = 1;
+    return;
+  }
+
+  const results = [];
+  for (const client of targets) {
+    const outcome = await register(client, config, {
+      yes,
+      quiet: targets.length > 1,
+    });
+    results.push({ client, outcome });
+  }
+
+  done(results);
+}
+
+function done(results) {
+  const added = results.filter((r) => r.outcome === "added");
+  const already = results.filter((r) => r.outcome === "already");
+  const failed = results.filter((r) => r.outcome === "failed");
+
+  if (added.length === 0 && already.length === 0) {
+    if (failed.length) process.exitCode = 1;
+    return;
+  }
+
+  console.log("");
+  for (const r of [...added, ...already]) {
+    console.log(`  ${green(MARK.tick)} ${bold(r.client.label)}`);
+  }
+  for (const r of failed) {
+    console.log(
+      `  ${amber(MARK.bullet)} ${bold(r.client.label)} ${dim("— not changed")}`,
+    );
+  }
+
+  console.log(`\n${heading("Next")}`);
+  console.log(
+    `    ${dim(MARK.dot)} Restart ${added.length + already.length > 1 ? "them" : (added[0] ?? already[0]).client.label}, then ask for your Skyelight items.`,
+  );
+  console.log(
+    `    ${dim(MARK.dot)} A browser opens to sign you in the first time.\n`,
+  );
+
+  if (failed.length) process.exitCode = 1;
 }
 
-function done(client) {
-  console.log(green(`\n✓ Skyelight added to ${client.label}\n`));
-  console.log("Restart it, then ask it to list your Skyelight items.");
+function help() {
+  console.log(header());
   console.log(
-    dim("It will open a browser to sign you in the first time.\n"),
+    `  ${dim("MCP server — your feedback, in your coding agent.")}\n`,
   );
+  console.log(heading("Usage"));
+  const usage = [
+    ["npx @skyelight/mcp init", "set up your coding agent"],
+    ["npx @skyelight/mcp init --client <id>", "skip the question"],
+    ["npx @skyelight/mcp init --client all", "every agent on this machine"],
+    ["npx @skyelight/mcp init --yes", "don't ask before writing"],
+    ["npx @skyelight/mcp remove", "take it out of every agent"],
+  ];
+  const w = Math.max(...usage.map(([u]) => u.length));
+  for (const [u, what] of usage) {
+    console.log(`    ${bold(pad(u, w))}  ${dim(what)}`);
+  }
+  console.log("");
+  console.log(heading("Agents"));
+  listClients();
+  console.log(heading("Environment"));
+  const env = [
+    ["SKYELIGHT_URL", `which deployment to register (${originLabel()})`],
+    ["NO_COLOR", "plain output"],
+  ];
+  const ew = Math.max(...env.map(([n]) => n.length));
+  for (const [n, what] of env) {
+    console.log(`    ${bold(pad(n, ew))}  ${dim(what)}`);
+  }
+  console.log("");
+  console.log(dim("  Running with no command starts the stdio server.\n"));
 }
 
 const argv = process.argv.slice(2);
 const cmd = argv[0];
 
+const yes = argv.includes("--yes") || argv.includes("-y");
+const at = argv.indexOf("--client");
+const clientFlag = at === -1 ? null : argv[at + 1];
+
 if (cmd === "init") {
-  const yes = argv.includes("--yes") || argv.includes("-y");
-  const at = argv.indexOf("--client");
-  await init({ yes, clientFlag: at === -1 ? null : argv[at + 1] });
+  await init({ yes, clientFlag });
+} else if (cmd === "remove" || cmd === "uninstall") {
+  await remove({ yes, clientFlag });
 } else {
-  console.log(`\n${bold("@skyelight/mcp")}\n`);
-  console.log("  npx @skyelight/mcp init            set up your coding agent");
-  console.log("  npx @skyelight/mcp init --client cursor\n");
-  console.log(dim("  Running with no command starts the stdio server.\n"));
+  help();
 }

package/src/client.js

@@ -101,5 +101,14 @@ export function createClient({ apiUrl, token, fetchImpl = fetch }) {
     postUpdate: (body) => post("/api/v1/items/update", body),
     createItem: (body) => post("/api/v1/items/create", body),
     setStatus: (body) => post("/api/v1/items/status", body),
+    listMembers: (params) => request("/api/v1/members", params),
+    assign: (body) => post("/api/v1/items/assign", body),
+    projectReview: (params) => request("/api/v1/review", params),
+    whatsNew: (params) => request("/api/v1/whats-new", params),
+    findBySource: (params) => request("/api/v1/source", params),
+    findSimilar: (body) => post("/api/v1/similar", body),
+    mergeItems: (body) => post("/api/v1/items/merge", body),
+    decisionLog: (params) => request("/api/v1/decisions", params),
+    saveRule: (body) => post("/api/v1/rules", body),
   };
 }

package/src/config.js

@@ -11,11 +11,9 @@
  *
  * The project binding is separate and comes from `.skyelight.json` in the
  * working directory, so a repo can declare which Skyelight project it is
- * without every developer configuring it.
- *
- * A project-bound API KEY (SKY-269) needs none of this — the server already
- * knows its project. `.skyelight.json` is for workspace-wide keys used
- * against several repos.
+ * without every developer configuring it. A personal token reaches every
+ * project its owner can, so the binding is what saves passing a projectId on
+ * every call.
  */
 
 import { readFileSync, existsSync } from "node:fs";
@@ -105,8 +103,8 @@ export function resolveConfig({
   return {
     token,
     apiUrl: apiUrl.replace(/\/+$/, ""),
-    // Named projectId to match the API. A bound key overrides this anyway —
-    // the server ignores a projectId outside the key's binding.
+    // Named projectId to match the API. A projectId the token's owner cannot
+    // reach is refused by the server, whatever this says.
     projectId: project.projectId ?? null,
     projectName: project.projectName ?? null,
   };

package/src/index.js

@@ -15,7 +15,17 @@
 // The static import below is hoisted, so `config.js` is evaluated either
 // way — but `resolveConfig()` is only *called* past this point, and calling
 // it is what throws when there are no credentials. The installer needs none.
-if (process.argv[2] === "init" || process.argv[2] === "--help") {
+/**
+ * Every word that is a command rather than "be the server".
+ *
+ * Listed rather than tested for "not empty", because an unknown word has to
+ * reach the server path: that is where a client passes flags we have never
+ * heard of, and turning those into a help screen would break the client
+ * rather than the typo.
+ */
+const COMMANDS = new Set(["init", "remove", "uninstall", "--help", "-h"]);
+
+if (COMMANDS.has(process.argv[2])) {
   await import("./cli.js");
   process.exit(process.exitCode ?? 0);
 }

package/src/insights.d.ts

@@ -0,0 +1,15 @@
+/** Types for insights.js; see tools.d.ts for why the package ships these. */
+
+import type { ToolDefinition } from "./tools.js";
+
+export declare function insightToolDefinitions(): ToolDefinition[];
+export declare const INSIGHT_TOOLS: Set<string>;
+export declare function renderInsight(
+  name: string,
+  data: unknown,
+): string | null;
+export declare function callInsightTool(
+  name: string,
+  args: Record<string, any>,
+  opts: { client: any; projectId?: string },
+): Promise<unknown> | undefined;