@aipermission/mcp 0.2.38 → 0.2.39

package/dist/init.js

@@ -1,13 +1,16 @@
 import fs from "node:fs/promises";
 import { execFile } from "node:child_process";
 import { createRequire } from "node:module";
-import os from "node:os";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { promisify } from "node:util";
 import { pathToFileURL } from "node:url";
 import { stdin as input, stdout as output } from "node:process";
+import { parse as parseTOML } from "smol-toml";
+import { parseCommandFlags } from "./cli-flags.js";
 import { DEFAULT_API_URL, normalizeLocalAPIURL } from "./local-url.js";
+import { adaptMCPServerConfig, getClient, MCP_PROVIDERS, resolveMCPConfigTarget, resolveMCPPrintTarget } from "./client-registry.js";
+import { commitSkillInstallation, prepareSkillInstallation } from "./install-skill.js";
 import {
   atomicWritePrivateFile,
   privateLockPath,
@@ -35,78 +38,61 @@ const color = {
   yellow: useColor ? "\x1b[33m" : "",
 };
 
-const providers = [
-  {
-    id: "codex",
-    label: "OpenAI Codex",
-    description: "Writes ~/.codex/config.toml",
-  },
-  {
-    id: "claude-code",
-    label: "Claude Code",
-    description: "Writes .mcp.json in the current project",
-  },
-  {
-    id: "cursor",
-    label: "Cursor",
-    description: "Writes .cursor/mcp.json in the current project",
-  },
-  {
-    id: "vscode",
-    label: "VS Code",
-    description: "Writes .vscode/mcp.json in the current project",
-  },
-  {
-    id: "windsurf",
-    label: "Windsurf",
-    description: "Writes ~/.codeium/windsurf/mcp_config.json",
-  },
-  {
-    id: "antigravity",
-    label: "Google Antigravity",
-    description: "Writes ~/.gemini/antigravity/mcp_config.json",
-  },
-  {
-    id: "gemini",
-    label: "Gemini CLI",
-    description: "Writes ~/.gemini/settings.json",
-  },
-  {
-    id: "custom",
-    label: "Custom / copy-paste",
-    description: "Prints config snippets only",
-  },
-];
-
 export async function runInit(argv = []) {
-  const flags = parseFlags(argv);
-  assertProviderSelectionAvailable(flags.provider, Boolean(input.isTTY && output.isTTY));
-  const stdinToken = flags.tokenStdin ? (await readStdin()).trim() : "";
+  return runConfiguration("init", argv);
+}
+
+export async function runSetup(argv = []) {
+  return runConfiguration("setup", argv);
+}
+
+async function runConfiguration(command, argv) {
+  const flags = parseCommandFlags(command, argv);
+  const interactive = Boolean(input.isTTY && output.isTTY);
+  assertProviderSelectionAvailable(flags.provider, interactive);
   const rl = readline.createInterface({ input, output });
   try {
     const provider = flags.provider
       ? findProvider(flags.provider)
-      : await selectProvider("Which AI client should use this token?", providers);
-    const name = sanitizeName(flags.name || (await ask(rl, "MCP server name", "aipermission")));
+      : await selectProvider("Which AI client should use this token?", MCP_PROVIDERS);
+    const name = sanitizeName(flags.name || (interactive ? await ask(rl, "MCP server name", "aipermission") : "aipermission"));
     const apiUrl = normalizeURL(flags.apiUrl || DEFAULT_API_URL);
-    const token = await resolveToken({ ...flags, stdinToken }, rl);
+    const outputTarget =
+      provider.id === "custom"
+        ? undefined
+        : flags.print
+          ? resolveMCPPrintTarget(provider.id, flags.scope)
+          : resolveMCPConfigTarget(provider.id, flags.scope);
+    const shouldPrepareSkill = command === "setup" && (!flags.print || provider.id === "custom");
+    const preparedSkill = shouldPrepareSkill ? await prepareSetupSkill(provider.id, flags) : undefined;
+    if (provider.id === "custom" || flags.print) {
+      const skillResult = preparedSkill ? await reportInstalledSkill(preparedSkill) : undefined;
+      printPlaceholderConfigNotice();
+      printProviderConfig(name, provider.id, apiUrl, outputTarget);
+      if (command === "setup" && flags.print && provider.id !== "custom") {
+        console.error("No files were changed. Run install-skill separately to install the native operator skill.");
+      }
+      return { provider: provider.id, name, printed: true, skill: skillResult };
+    }
 
+    const stdinToken = flags.tokenStdin ? (await readStdin()).trim() : "";
+    const token = await resolveToken({ ...flags, stdinToken }, rl);
     if (!token) {
       throw new Error("API token is required.");
     }
-
-    const config = buildMCPServerConfig({ apiUrl, token });
-    if (provider.id === "custom" || flags.print) {
-      printTokenConfigWarning();
-      printCustomConfig(name, config);
-      return;
-    }
-
-    const result = await writeProviderConfig(provider.id, name, config, { force: Boolean(flags.force) });
+    const config = adaptMCPServerConfig(provider.id, buildMCPServerConfig({ apiUrl, token }));
+    const skillResult = preparedSkill ? await reportInstalledSkill(preparedSkill) : undefined;
+    const result = await writeProviderConfig(provider.id, name, config, {
+      force: Boolean(flags.force),
+      scope: flags.scope,
+      homeDir: flags.home,
+      projectDir: flags.projectDir,
+    });
     console.log("");
     console.log(`${color.green}Configured ${provider.label}${color.reset}`);
     console.log(`${color.dim}Name:${color.reset} ${name}`);
     console.log(`${color.dim}Path:${color.reset} ${result.path}`);
+    console.log(`${color.dim}Scope:${color.reset} ${result.scope}`);
     if (result.gitExcluded) {
       console.log(`${color.dim}Git:${color.reset} added ${result.gitExcludeEntry} to .git/info/exclude`);
     }
@@ -115,6 +101,7 @@ export async function runInit(argv = []) {
       `${color.yellow}Keep this config private:${color.reset} it contains an AIPermission bearer token. If it is committed, revoke the token.`,
     );
     console.log(`${color.yellow}Restart the AI client so it reloads MCP servers.${color.reset}`);
+    return { provider: provider.id, name, config: result, skill: skillResult };
   } finally {
     rl.close();
   }
@@ -127,44 +114,39 @@ export function assertProviderSelectionAvailable(provider, interactive) {
 }
 
 export function parseFlags(argv) {
-  const result = {};
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (!arg.startsWith("--")) {
-      continue;
-    }
-    const [rawKey, inlineValue] = arg.slice(2).split("=", 2);
-    const key = rawKey.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
-    if (key === "print") {
-      result.print = true;
-      continue;
-    }
-    if (key === "force") {
-      result.force = true;
-      continue;
-    }
-    if (key === "tokenStdin") {
-      result.tokenStdin = true;
-      continue;
-    }
-    if (key === "token") {
-      throw new Error("--token is not supported; use the hidden prompt or --token-stdin");
-    }
-    result[key] = inlineValue ?? argv[i + 1] ?? "";
-    if (inlineValue === undefined) {
-      i += 1;
-    }
+  return parseCommandFlags("init", argv);
+}
+
+async function prepareSetupSkill(client, flags) {
+  return prepareSkillInstallation({
+    client,
+    scope: flags.skillScope || flags.scope,
+    source: flags.skillSource,
+    homeDir: flags.home,
+    projectDir: flags.projectDir,
+  });
+}
+
+async function reportInstalledSkill(prepared) {
+  const result = await commitSkillInstallation(prepared);
+  if (!result.path) {
+    console.log("");
+    console.log(result.content);
+    return result;
   }
+  console.log("");
+  console.log(`${color.green}Installed native operator skill${color.reset}`);
+  console.log(`${color.dim}Path:${color.reset} ${result.path}`);
+  console.log(`${color.dim}Scope:${color.reset} ${result.scope}`);
   return result;
 }
 
 function findProvider(idOrLabel) {
-  const normalized = String(idOrLabel).trim().toLowerCase();
-  const provider = providers.find((item) => item.id === normalized || item.label.toLowerCase() === normalized);
-  if (!provider) {
+  try {
+    return getClient(idOrLabel);
+  } catch {
     throw new Error(`Unknown provider: ${idOrLabel}`);
   }
-  return provider;
 }
 
 async function selectProvider(title, items) {
@@ -314,62 +296,51 @@ export function buildMCPServerConfig({ apiUrl, token }) {
 }
 
 export async function writeProviderConfig(providerID, name, config, options = {}) {
-  const projectRoot = process.cwd();
-  const homeRoot = os.homedir();
-  if (providerID === "codex") {
-    const filePath = path.join(homeRoot, ".codex", "config.toml");
-    await writeCodexConfig(filePath, name, config, { trustedRoot: homeRoot });
-    return { path: filePath };
-  }
-  if (providerID === "claude-code") {
-    const filePath = path.join(projectRoot, ".mcp.json");
-    await assertProjectConfigWritable(filePath, options);
-    const protection = await protectGitIgnoredConfig(filePath);
-    await writeJSONMCPConfig(filePath, name, config, "mcpServers", { trustedRoot: projectRoot });
-    return { path: filePath, ...protection };
-  }
-  if (providerID === "cursor") {
-    const filePath = path.join(projectRoot, ".cursor", "mcp.json");
-    await assertProjectConfigWritable(filePath, options);
-    const protection = await protectGitIgnoredConfig(filePath);
-    await writeJSONMCPConfig(filePath, name, config, "mcpServers", { trustedRoot: projectRoot });
-    return { path: filePath, ...protection };
-  }
-  if (providerID === "vscode") {
-    const filePath = path.join(projectRoot, ".vscode", "mcp.json");
-    await assertProjectConfigWritable(filePath, options);
-    const protection = await protectGitIgnoredConfig(filePath);
-    await writeJSONMCPConfig(filePath, name, config, "servers", { trustedRoot: projectRoot });
-    return { path: filePath, ...protection };
-  }
-  if (providerID === "windsurf") {
-    const filePath = path.join(homeRoot, ".codeium", "windsurf", "mcp_config.json");
-    await writeJSONMCPConfig(filePath, name, config, "mcpServers", { trustedRoot: homeRoot });
-    return { path: filePath };
-  }
-  if (providerID === "antigravity") {
-    const filePath = path.join(homeRoot, ".gemini", "antigravity", "mcp_config.json");
-    await writeJSONMCPConfig(filePath, name, config, "mcpServers", { trustedRoot: homeRoot });
-    return { path: filePath };
-  }
-  if (providerID === "gemini") {
-    const filePath = path.join(homeRoot, ".gemini", "settings.json");
-    await writeJSONMCPConfig(filePath, name, config, "mcpServers", { trustedRoot: homeRoot });
-    return { path: filePath };
-  }
-  throw new Error(`Unsupported provider: ${providerID}`);
+  const projectRoot = options.projectDir || process.cwd();
+  const target = resolveMCPConfigTarget(providerID, options.scope, {
+    homeDir: options.homeDir,
+    projectDir: projectRoot,
+    env: options.env,
+  });
+  const providerConfig = adaptMCPServerConfig(providerID, config);
+  let protection = {};
+  if (target.projectConfig) {
+    await assertProjectConfigWritable(target.path, options);
+    protection = await protectGitIgnoredConfig(target.path, projectRoot, { allowTracked: Boolean(options.force) });
+  }
+  const trustedRoot = target.trustedRoot;
+  const writeOptions = {
+    trustedRoot,
+    beforeWrite: target.projectConfig
+      ? async () => {
+          await assertProjectConfigWritable(target.path, options);
+          await options.beforeWrite?.();
+          await assertProjectConfigWritable(target.path, options);
+        }
+      : options.beforeWrite,
+  };
+  if (target.format === "toml") {
+    await writeTOMLMCPConfig(target.path, name, providerConfig, writeOptions);
+  } else {
+    await writeJSONMCPConfig(target.path, name, providerConfig, target.rootKey, writeOptions);
+  }
+  return { path: target.path, scope: target.scope, ...protection };
 }
 
 export async function writeJSONMCPConfig(filePath, name, config, rootKey, options = {}) {
   await withPrivateFileLock(
     filePath,
     async () => {
+      await options.beforeWrite?.();
       let root = {};
       try {
         root = JSON.parse(await fs.readFile(filePath, "utf8"));
       } catch (error) {
         if (error.code !== "ENOENT") {
-          throw new Error(`Could not read JSON config at ${filePath}: ${error.message}`, { cause: error });
+          redactParseError(error);
+          throw new Error(`Could not parse JSON config at ${filePath}; the existing file was left unchanged`, {
+            cause: error,
+          });
         }
       }
       if (!root || typeof root !== "object" || Array.isArray(root)) root = {};
@@ -380,6 +351,7 @@ export async function writeJSONMCPConfig(filePath, name, config, rootKey, option
           : Object.create(null);
       Object.defineProperty(servers, name, { value: config, enumerable: true, configurable: true, writable: true });
       root[rootKey] = servers;
+      await options.beforeWrite?.();
       await writePrivateFile(filePath, `${JSON.stringify(root, null, 2)}\n`, options);
     },
     options,
@@ -400,19 +372,23 @@ function splitInputKeys(value) {
   return keys;
 }
 
-async function writeCodexConfig(filePath, name, config, options = {}) {
+export async function writeTOMLMCPConfig(filePath, name, config, options = {}) {
   await withPrivateFileLock(
     filePath,
     async () => {
+      await options.beforeWrite?.();
       let current = "";
       try {
         current = await fs.readFile(filePath, "utf8");
       } catch (error) {
         if (error.code !== "ENOENT") throw error;
       }
-      const next = removeCodexServer(current, name).trimEnd();
-      const block = codexServerBlock(name, config);
-      await writePrivateFile(filePath, `${next ? `${next}\n\n` : ""}${block}\n`, options);
+      const next = removeTOMLServer(current, name).trimEnd();
+      const block = tomlServerBlock(name, config);
+      const outputContent = `${next ? `${next}\n\n` : ""}${block}\n`;
+      parseTOMLDocument(outputContent, filePath);
+      await options.beforeWrite?.();
+      await writePrivateFile(filePath, outputContent, options);
     },
     options,
   );
@@ -426,7 +402,7 @@ async function assertProjectConfigWritable(filePath, options = {}) {
   if (options.force) {
     return;
   }
-  const tracked = await gitTrackedPath(filePath);
+  const tracked = await gitTrackedPath(filePath, options.projectDir || process.cwd());
   if (!tracked) {
     return;
   }
@@ -438,8 +414,8 @@ async function assertProjectConfigWritable(filePath, options = {}) {
   );
 }
 
-async function protectGitIgnoredConfig(filePath) {
-  const repository = await discoverGitRepository(process.cwd());
+async function protectGitIgnoredConfig(filePath, startDir = process.cwd(), options = {}) {
+  const repository = await discoverGitRepository(startDir);
   if (!repository) {
     return {};
   }
@@ -478,7 +454,7 @@ async function protectGitIgnoredConfig(filePath) {
       { trustedRoot: path.dirname(excludePath) },
     );
     await assertGitIgnored(repository, [
-      relativePath,
+      ...(options.allowTracked ? [] : [relativePath]),
       privateTemporaryCheckPath(filePath, repository.workTree),
       privateStagingCheckPath(filePath, repository.workTree),
       lockRelativePath,
@@ -495,8 +471,24 @@ async function protectGitIgnoredConfig(filePath) {
   };
 }
 
-async function gitTrackedPath(filePath) {
-  const repository = await discoverGitRepository(process.cwd());
+export async function inspectProjectConfigProtection(filePath, startDir = process.cwd()) {
+  const repository = await discoverGitRepository(startDir);
+  if (!repository) return { repository: false };
+  const relativePath = path.relative(repository.workTree, filePath).split(path.sep).join("/");
+  if (relativePath.startsWith("../") || path.isAbsolute(relativePath)) return { repository: false };
+  const tracked = await gitTrackedPath(filePath, startDir);
+  if (tracked) throw new Error(`MCP config is tracked by Git: ${tracked}`);
+  await assertGitIgnored(repository, [
+    relativePath,
+    privateTemporaryCheckPath(filePath, repository.workTree),
+    privateStagingCheckPath(filePath, repository.workTree),
+    path.relative(repository.workTree, privateLockPath(filePath)).split(path.sep).join("/"),
+  ]);
+  return { repository: true, relativePath };
+}
+
+async function gitTrackedPath(filePath, startDir = process.cwd()) {
+  const repository = await discoverGitRepository(startDir);
   if (!repository) {
     return "";
   }
@@ -542,7 +534,7 @@ async function discoverGitRepository(startDir) {
 async function assertGitIgnored(repository, relativePaths) {
   for (const relativePath of relativePaths) {
     try {
-      await execFileAsync("git", ["-C", repository.workTree, "check-ignore", "--no-index", "-q", "--", relativePath], {
+      await execFileAsync("git", ["-C", repository.workTree, "check-ignore", "-q", "--", relativePath], {
         windowsHide: true,
       });
     } catch (error) {
@@ -586,20 +578,27 @@ function gitErrorMessage(error) {
   return String(error.stderr || error.message || error).trim();
 }
 
-function removeCodexServer(source, name) {
-  const main = `[mcp_servers.${tomlKey(name)}]`;
-  const env = `[mcp_servers.${tomlKey(name)}.env]`;
+function redactParseError(error, format = "JSON") {
+  error.message = `${format} parsing failed`;
+  error.stack = `${error.name || "Error"}: ${error.message}`;
+  return error;
+}
+
+function removeTOMLServer(source, name) {
+  if (!source.trim()) return source;
+  parseTOMLDocument(source, "existing TOML config");
   const lines = source.split(/\r?\n/);
   const kept = [];
   let skipping = false;
+  const scanState = { multiline: "" };
   for (const line of lines) {
-    const trimmed = line.trim();
-    const isHeader = trimmed.startsWith("[") && trimmed.endsWith("]");
-    if (trimmed === main || trimmed === env) {
+    const header = scanTOMLHeader(line, scanState);
+    const selected = header?.[0] === "mcp_servers" && header?.[1] === name;
+    if (selected) {
       skipping = true;
       continue;
     }
-    if (isHeader && skipping) {
+    if (header && skipping) {
       skipping = false;
     }
     if (!skipping) {
@@ -609,10 +608,57 @@ function removeCodexServer(source, name) {
   return kept.join("\n");
 }
 
-function codexServerBlock(name, config) {
+function scanTOMLHeader(line, state) {
+  if (state.multiline) {
+    if (hasMultilineDelimiter(line, state.multiline)) state.multiline = "";
+    return null;
+  }
+  const trimmed = line.trimStart();
+  if (trimmed.startsWith("[") && !trimmed.startsWith("[[")) {
+    try {
+      return findMarkerPath(parseTOML(`${line}\n__aipermission_header_marker = true\n`));
+    } catch {
+      return null;
+    }
+  }
+  for (const delimiter of ['"""', "'''"]) {
+    if (!hasMultilineDelimiter(line, delimiter)) continue;
+    if ((line.split(delimiter).length - 1) % 2 === 1) state.multiline = delimiter;
+    break;
+  }
+  return null;
+}
+
+function hasMultilineDelimiter(line, delimiter) {
+  const comment = line.indexOf("#");
+  return (comment < 0 ? line : line.slice(0, comment)).includes(delimiter);
+}
+
+function findMarkerPath(value, pathParts = []) {
+  if (!value || typeof value !== "object") return null;
+  if (value.__aipermission_header_marker === true) return pathParts;
+  for (const [key, nested] of Object.entries(value)) {
+    const match = findMarkerPath(nested, [...pathParts, key]);
+    if (match) return match;
+  }
+  return null;
+}
+
+function parseTOMLDocument(contents, location) {
+  try {
+    return parseTOML(contents);
+  } catch (error) {
+    redactParseError(error, "TOML");
+    throw new Error(`Could not parse TOML config at ${location}; the existing file was left unchanged`, { cause: error });
+  }
+}
+
+function tomlServerBlock(name, config) {
+  const fields = Object.entries(config)
+    .filter(([key]) => key !== "env")
+    .map(([key, value]) => `${key} = ${tomlValue(value)}`);
   return `[mcp_servers.${tomlKey(name)}]
-command = ${tomlString(config.command)}
-args = [${config.args.map(tomlString).join(", ")}]
+${fields.join("\n")}
 enabled = true
 
 [mcp_servers.${tomlKey(name)}.env]
@@ -621,17 +667,38 @@ AIPERMISSION_API_URL = ${tomlString(config.env.AIPERMISSION_API_URL)}
 AIPERMISSION_API_TOKEN = ${tomlString(config.env.AIPERMISSION_API_TOKEN)}`;
 }
 
-function printCustomConfig(name, config) {
+function printProviderConfig(name, provider, apiUrl, target) {
+  const baseConfig = buildMCPServerConfig({ apiUrl, token: "YOUR_TOKEN_HERE" });
+  const previewConfig = provider === "custom" ? baseConfig : adaptMCPServerConfig(provider, baseConfig);
   console.log("");
   console.log(`${color.bold}${color.cyan}Copy-paste config:${color.reset}`);
   console.log("");
-  console.log(JSON.stringify({ mcpServers: { [name]: config } }, null, 2));
+  if (target?.format === "toml") {
+    console.log(tomlPreviewServerBlock(name, previewConfig));
+    return;
+  }
+  console.log(JSON.stringify({ [target?.rootKey || "mcpServers"]: { [name]: previewConfig } }, null, 2));
 }
 
-function printTokenConfigWarning() {
+// Keep stdout rendering separate from the secret-bearing TOML writer.
+function tomlPreviewServerBlock(name, config) {
+  const fields = Object.entries(config)
+    .filter(([key]) => key !== "env")
+    .map(([key, value]) => `${key} = ${tomlValue(value)}`);
+  return `[mcp_servers.${tomlKey(name)}]
+${fields.join("\n")}
+enabled = true
+
+[mcp_servers.${tomlKey(name)}.env]
+NODE_ENV = "production"
+AIPERMISSION_API_URL = ${tomlString(config.env.AIPERMISSION_API_URL)}
+AIPERMISSION_API_TOKEN = "YOUR_TOKEN_HERE"`;
+}
+
+function printPlaceholderConfigNotice() {
   console.log("");
-  console.log(`${color.yellow}Warning:${color.reset} the printed config contains an AIPermission bearer token.`);
-  console.log(`${color.yellow}Keep it private and revoke the token if it is shared or committed.${color.reset}`);
+  console.log(`${color.yellow}Preview:${color.reset} the printed config uses YOUR_TOKEN_HERE and contains no bearer token.`);
+  console.log(`${color.yellow}Replace the placeholder through the client's private environment or config mechanism.${color.reset}`);
 }
 
 export function sanitizeName(value) {
@@ -663,6 +730,13 @@ export function tomlString(value) {
   return JSON.stringify(String(value));
 }
 
+function tomlValue(value) {
+  if (typeof value === "string") return tomlString(value);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return `[${value.map(tomlValue).join(", ")}]`;
+  throw new Error(`Unsupported TOML MCP config value: ${typeof value}`);
+}
+
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   await runInit(process.argv.slice(2));
 }