@xmemo/client 0.4.155 → 0.4.157

package/src/core/runtime.js

@@ -0,0 +1,144 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+
+import { UsageError } from './errors.js';
+import { writeLine } from './io.js';
+
+export function npmExecutable() {
+  return os.platform() === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+export async function runProcess(command, args, io, { stream = true } = {}) {
+  const spawnFn = io.spawn ?? spawn;
+  return await new Promise((resolve, reject) => {
+    const child = spawnFn(command, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: os.platform() === 'win32'
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (chunk) => {
+      const text = String(chunk);
+      stdout += text;
+      if (stream) {
+        io.stdout.write(text);
+      }
+    });
+    child.stderr?.on('data', (chunk) => {
+      const text = String(chunk);
+      stderr += text;
+      if (stream) {
+        io.stderr.write(text);
+      }
+    });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      resolve({ code: code ?? 0, stdout, stderr });
+    });
+  });
+}
+
+export async function waitForShutdown(server, io) {
+  await new Promise((resolve) => {
+    let resolved = false;
+    const finish = async () => {
+      if (resolved) {
+        return;
+      }
+      resolved = true;
+      await closeServer(server);
+      resolve();
+    };
+    const onSigint = () => {
+      writeLine(io.stdout, 'Shutting down XMemo MCP proxy...');
+      void finish();
+    };
+    process.once('SIGINT', onSigint);
+    process.once('SIGTERM', onSigint);
+    server.once('close', () => {
+      process.off('SIGINT', onSigint);
+      process.off('SIGTERM', onSigint);
+      if (!resolved) {
+        resolved = true;
+        resolve();
+      }
+    });
+  });
+}
+
+export async function closeServer(server) {
+  await new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+export async function readAll(stream) {
+  let content = '';
+  for await (const chunk of stream) {
+    content += chunk;
+  }
+  return content;
+}
+
+export async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readTextIfExists(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return '';
+    }
+    throw error;
+  }
+}
+
+export function parseJsonConfig(content, configPath) {
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    throw new UsageError(`Invalid JSON in ${configPath}: ${error.message}`);
+  }
+}
+
+export async function bestEffortChmod(filePath, mode) {
+  try {
+    await fs.chmod(filePath, mode);
+  } catch {
+    // Windows and managed environments may ignore POSIX chmod.
+  }
+}
+
+export function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function escapeTomlString(value) {
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+export function unescapeTomlString(value) {
+  return value.replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+}
+
+export function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/core/version.js

@@ -0,0 +1 @@
+export const CLI_VERSION = '0.4.156';

package/src/mcp/clients/detect.js

@@ -0,0 +1,51 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { fileExists } from '../../core/runtime.js';
+import { defaultCopilotConfigPath } from '../identity/paths.js';
+
+export async function detectClient(clientId, env, mcpClients) {
+  let filePaths = [];
+  if (clientId === 'copilot-cli' || clientId === 'copilot') {
+    if (process.platform === 'win32' && env.APPDATA) {
+      filePaths.push(path.join(env.APPDATA, 'Code', 'User', 'mcp.json'));
+    } else {
+      const home = env.HOME || os.homedir();
+      if (process.platform === 'darwin') {
+        filePaths.push(path.join(home, 'Library', 'Application Support', 'Code', 'User', 'mcp.json'));
+      }
+      filePaths.push(path.join(home, '.config', 'Code', 'User', 'mcp.json'));
+    }
+    filePaths.push(defaultCopilotConfigPath(env));
+  } else {
+    const client = mcpClients.get(clientId);
+    if (client) {
+      filePaths.push(client.defaultConfigPath(env));
+    }
+  }
+
+  if (clientId === 'cline') {
+    if (process.platform === 'win32' && env.APPDATA) {
+      filePaths.push(path.join(env.APPDATA, 'Code', 'User', 'globalStorage', 'saoudrizwan.claude-dev', 'settings', 'cline_mcp_settings.json'));
+    } else {
+      const home = env.HOME || os.homedir();
+      if (process.platform === 'darwin') {
+        filePaths.push(path.join(home, 'Library', 'Application Support', 'Code', 'User', 'globalStorage', 'saoudrizwan.claude-dev', 'settings', 'cline_mcp_settings.json'));
+      }
+      filePaths.push(path.join(home, '.config', 'Code', 'User', 'globalStorage', 'saoudrizwan.claude-dev', 'settings', 'cline_mcp_settings.json'));
+    }
+  }
+
+  for (const filePath of filePaths) {
+    if (await fileExists(filePath)) {
+      return { detected: true, path: filePath };
+    }
+    const parentDir = path.dirname(filePath);
+    if (await fileExists(parentDir)) {
+      return { detected: true, path: filePath };
+    }
+  }
+
+  return { detected: false };
+}
+

package/src/mcp/clients/registry.js

@@ -0,0 +1,68 @@
+import { JSON_MCP_CLIENT_DEFINITIONS } from '../formats/json.js';
+
+export function createMcpClients(deps) {
+  const clients = new Map();
+
+  clients.set('codex', {
+    label: 'Codex',
+    defaultConfigPath: deps.defaultCodexConfigPath,
+    buildSnippet: deps.codexTomlSnippet,
+    writeConfig: deps.appendTomlServerConfig,
+    configKind: 'toml'
+  });
+
+  for (const definition of deps.JSON_MCP_CLIENT_DEFINITIONS) {
+    if (definition.id === 'qwen') {
+      clients.set('hermes', hermesClient(deps));
+    }
+    clients.set(definition.id, jsonClient(definition, deps));
+  }
+
+  if (!clients.has('hermes')) {
+    clients.set('hermes', hermesClient(deps));
+  }
+
+  return clients;
+}
+
+function jsonClient(definition, deps) {
+  return {
+    label: definition.label,
+    defaultConfigPath: deps[definition.defaultConfigPath],
+    buildSnippet: (mcpUrl, identity) => deps.jsonClientSnippet(definition.id, mcpUrl, identity),
+    writeConfig: (configPath, mcpUrl, identity) => deps.mergeJsonClientMcpConfig(definition.id, configPath, mcpUrl, identity),
+    configKind: definition.configKind,
+    authentication: definition.authentication
+  };
+}
+
+function hermesClient(deps) {
+  return {
+    label: 'Hermes',
+    defaultConfigPath: deps.defaultHermesConfigPath,
+    buildSnippet: deps.hermesYamlSnippet,
+    writeConfig: deps.mergeHermesMcpConfig,
+    configKind: 'yaml'
+  };
+}
+
+export function supportedMcpClients(mcpClients) {
+  const clients = Array.from(mcpClients.entries()).map(([id, client]) => ({
+    id,
+    label: client.label,
+    configKind: client.configKind
+  }));
+  clients.push({ id: 'copilot-cli', label: 'Copilot CLI', configKind: 'local-proxy' });
+  return clients;
+}
+
+export function supportedMcpClientIds(mcpClients) {
+  return Array.from(mcpClients.keys());
+}
+
+export function usesClientOAuth(clientId) {
+  return JSON_MCP_CLIENT_DEFINITIONS.some(
+    (definition) => definition.id === clientId && definition.authentication === 'oauth'
+  );
+}
+

package/src/mcp/clients.js

@@ -0,0 +1,81 @@
+import {
+  appendTomlServerConfig,
+  codexTomlSnippet
+} from './formats/toml.js';
+import {
+  hermesYamlSnippet,
+  mergeHermesMcpConfig
+} from './formats/yaml.js';
+import {
+  JSON_MCP_CLIENT_DEFINITIONS,
+  jsonClientSnippet,
+  mergeJsonClientMcpConfig
+} from './formats/json.js';
+import {
+  defaultAntigravity2ConfigPath,
+  defaultAntigravityCliConfigPath,
+  defaultAntigravityConfigPath,
+  defaultAntigravityIdeConfigPath,
+  defaultClaudeConfigPath,
+  defaultClaudecodeConfigPath,
+  defaultClineConfigPath,
+  defaultCodexConfigPath,
+  defaultContinueConfigPath,
+  defaultCursorConfigPath,
+  defaultGeminiConfigPath,
+  defaultHermesConfigPath,
+  defaultJetbrainsConfigPath,
+  defaultKiroConfigPath,
+  defaultOpencodeConfigPath,
+  defaultOpenclawConfigPath,
+  defaultQwenConfigPath,
+  defaultTraeConfigPath,
+  defaultTraeSoloConfigPath,
+  defaultWindsurfConfigPath,
+  defaultZedConfigPath
+} from '../config/paths.js';
+import {
+  createMcpClients,
+  supportedMcpClientIds as registrySupportedMcpClientIds,
+  supportedMcpClients as registrySupportedMcpClients
+} from './clients/registry.js';
+
+export const MCP_CLIENTS = createMcpClients({
+  JSON_MCP_CLIENT_DEFINITIONS,
+  defaultCodexConfigPath,
+  codexTomlSnippet,
+  appendTomlServerConfig,
+  defaultHermesConfigPath,
+  hermesYamlSnippet,
+  mergeHermesMcpConfig,
+  jsonClientSnippet,
+  mergeJsonClientMcpConfig,
+  defaultCursorConfigPath,
+  defaultGeminiConfigPath,
+  defaultAntigravityConfigPath,
+  defaultAntigravityIdeConfigPath,
+  defaultAntigravity2ConfigPath,
+  defaultAntigravityCliConfigPath,
+  defaultWindsurfConfigPath,
+  defaultClineConfigPath,
+  defaultContinueConfigPath,
+  defaultClaudeConfigPath,
+  defaultOpenclawConfigPath,
+  defaultKiroConfigPath,
+  defaultZedConfigPath,
+  defaultJetbrainsConfigPath,
+  defaultOpencodeConfigPath,
+  defaultQwenConfigPath,
+  defaultTraeConfigPath,
+  defaultTraeSoloConfigPath,
+  defaultClaudecodeConfigPath
+});
+
+export function supportedMcpClients() {
+  return registrySupportedMcpClients(MCP_CLIENTS);
+}
+
+export function supportedMcpClientIds() {
+  return registrySupportedMcpClientIds(MCP_CLIENTS);
+}
+

package/src/mcp/core/names.js

@@ -0,0 +1,13 @@
+import {
+  LEGACY_MCP_SERVER_NAMES,
+  MCP_SERVER_NAME
+} from '../../core/constants.js';
+
+export function knownMcpServerNames() {
+  return [MCP_SERVER_NAME, ...LEGACY_MCP_SERVER_NAMES];
+}
+
+export function existingJsonMcpServerName(mcpServers) {
+  return knownMcpServerNames().find((name) => mcpServers[name]);
+}
+

package/src/mcp/core/templates.js

@@ -0,0 +1,156 @@
+import {
+  AGENT_ID_HEADER,
+  AGENT_INSTANCE_ENV_VAR,
+  AGENT_INSTANCE_HEADER,
+  COMMAND_NAME,
+  DEFAULT_PROXY_PORT,
+  MCP_SERVER_NAME,
+  TOKEN_ENV_VAR
+} from '../../core/constants.js';
+import { codexTomlSnippet } from '../formats/toml.js';
+import {
+  jsonClientConfig,
+  jsonMcpClientDefinition
+} from '../formats/json.js';
+
+export function mcpConfigTemplate(clientId, mcpUrl, options = {}) {
+  if (clientId === 'codex') {
+    return {
+      client: clientId,
+      serverName: MCP_SERVER_NAME,
+      snippetFormat: 'toml',
+      snippet: codexTomlSnippet(mcpUrl),
+      requiresEnv: [TOKEN_ENV_VAR],
+      optionalEnv: [AGENT_INSTANCE_ENV_VAR],
+      agentIdentity: {
+        agentId: 'codex',
+        agentIdHeader: AGENT_ID_HEADER,
+        agentInstanceEnvVar: AGENT_INSTANCE_ENV_VAR,
+        agentInstanceHeader: AGENT_INSTANCE_HEADER
+      },
+      agentInstanceGeneration: agentInstanceGenerationPolicy(clientId, options),
+      writesTokenValue: false
+    };
+  }
+
+  const jsonDefinition = jsonMcpClientDefinition(clientId);
+  if (jsonDefinition) {
+    return jsonDefinition.authentication === 'oauth'
+      ? oauthJsonMcpTemplate(clientId, mcpUrl, jsonClientConfig(clientId, mcpUrl), options)
+      : bearerJsonMcpTemplate(clientId, mcpUrl, jsonClientConfig(clientId, mcpUrl), options);
+  }
+
+  return {
+    client: clientId,
+    serverName: MCP_SERVER_NAME,
+    snippetFormat: 'json',
+    snippet: {
+      mcpServers: {
+        [MCP_SERVER_NAME]: {
+          type: 'http',
+          url: mcpUrl,
+          headers: {
+            Authorization: `Bearer \${${TOKEN_ENV_VAR}}`,
+            [AGENT_ID_HEADER]: clientId,
+            [AGENT_INSTANCE_HEADER]: `\${${AGENT_INSTANCE_ENV_VAR}}`
+          }
+        }
+      }
+    },
+    requiresEnv: [TOKEN_ENV_VAR],
+    optionalEnv: [AGENT_INSTANCE_ENV_VAR],
+    agentIdentity: {
+      agentId: clientId,
+      agentIdHeader: AGENT_ID_HEADER,
+      agentInstanceEnvVar: AGENT_INSTANCE_ENV_VAR,
+      agentInstanceHeader: AGENT_INSTANCE_HEADER
+    },
+    agentInstanceGeneration: agentInstanceGenerationPolicy(clientId, options),
+    writesTokenValue: false
+  };
+}
+
+export function mcpLocalProxyTemplate(clientId, proxyUrl, options = {}) {
+  return {
+    client: clientId,
+    serverName: MCP_SERVER_NAME,
+    snippetFormat: 'json',
+    snippet: {
+      mcpServers: {
+        [MCP_SERVER_NAME]: {
+          type: 'http',
+          url: proxyUrl
+        }
+      }
+    },
+    requiresCredential: [`${COMMAND_NAME} login`, `${COMMAND_NAME} token add --from-stdin`],
+    requiresLocalCommand: `${COMMAND_NAME} mcp proxy --port ${new URL(proxyUrl).port || DEFAULT_PROXY_PORT}`,
+    agentIdentity: {
+      agentId: clientId,
+      agentIdHeader: AGENT_ID_HEADER,
+      agentInstanceEnvVar: AGENT_INSTANCE_ENV_VAR,
+      agentInstanceHeader: AGENT_INSTANCE_HEADER
+    },
+    agentInstanceGeneration: agentInstanceGenerationPolicy(clientId, options),
+    writesTokenValue: false
+  };
+}
+
+export function agentInstanceGenerationPolicy(clientId, options = {}) {
+  const automaticCommand = options.mcpClients?.has(clientId)
+    ? `${COMMAND_NAME} mcp add ${clientId} --write`
+    : clientId === 'copilot-cli'
+      ? `${COMMAND_NAME} setup copilot --write`
+      : null;
+  return {
+    requiredForHeaders: true,
+    stablePerInstall: true,
+    automaticCommand,
+    generatedPattern: `xmemo-${clientId}-<uuid>`,
+    storagePath: `~/.config/xmemo/agent-instances/${clientId}.json`,
+    manualEnvVar: AGENT_INSTANCE_ENV_VAR
+  };
+}
+
+function bearerJsonMcpTemplate(clientId, mcpUrl, snippet, options) {
+  return {
+    client: clientId,
+    serverName: MCP_SERVER_NAME,
+    snippetFormat: 'json',
+    snippet,
+    requiresEnv: [TOKEN_ENV_VAR],
+    optionalEnv: [AGENT_INSTANCE_ENV_VAR],
+    authentication: 'env-bearer',
+    agentIdentity: {
+      agentId: clientId,
+      agentIdHeader: AGENT_ID_HEADER,
+      agentInstanceEnvVar: AGENT_INSTANCE_ENV_VAR,
+      agentInstanceHeader: AGENT_INSTANCE_HEADER
+    },
+    agentInstanceGeneration: agentInstanceGenerationPolicy(clientId, options),
+    mcpUrl,
+    writesTokenValue: false
+  };
+}
+
+function oauthJsonMcpTemplate(clientId, mcpUrl, snippet, options) {
+  return {
+    client: clientId,
+    serverName: MCP_SERVER_NAME,
+    snippetFormat: 'json',
+    snippet,
+    requiresEnv: [],
+    optionalEnv: [AGENT_INSTANCE_ENV_VAR],
+    authentication: 'oauth',
+    agentIdentity: {
+      agentId: clientId,
+      agentIdHeader: AGENT_ID_HEADER,
+      agentInstanceEnvVar: AGENT_INSTANCE_ENV_VAR,
+      agentInstanceHeader: AGENT_INSTANCE_HEADER
+    },
+    agentInstanceGeneration: agentInstanceGenerationPolicy(clientId, options),
+    mcpUrl,
+    writesTokenValue: false
+  };
+}
+