@xmemo/client 0.4.155 → 0.4.156

package/src/http.js

@@ -0,0 +1,160 @@
+import {
+  CLI_VERSION,
+  COMMAND_NAME
+} from './constants.js';
+import { UsageError } from './errors.js';
+
+export async function verifyTokenWithMcp(baseUrl, token, timeoutMs, io) {
+  const url = endpointUrl(baseUrl, '/mcp');
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await io.fetch(url, {
+      method: 'POST',
+      headers: {
+        accept: 'application/json, text/event-stream',
+        'content-type': 'application/json',
+        authorization: `Bearer ${token}`,
+        'user-agent': `XMemo-CLI/${CLI_VERSION} (+https://github.com/yonro/memory-os-cli)`
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2024-11-05',
+          capabilities: {},
+          clientInfo: { name: COMMAND_NAME, version: CLI_VERSION }
+        }
+      }),
+      signal: controller.signal
+    });
+    return {
+      ok: response.ok,
+      detail: response.ok ? `HTTP ${response.status}` : `HTTP ${response.status}`
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      detail: error.name === 'AbortError' ? `timeout after ${timeoutMs}ms` : error.message
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function probe(url, timeoutMs, io) {
+  if (typeof io.fetch !== 'function') {
+    return { url, ok: false, error: 'fetch unavailable in this Node runtime' };
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await io.fetch(url, {
+      headers: { accept: 'application/json' },
+      signal: controller.signal
+    });
+    return { url, ok: response.ok, status: response.status };
+  } catch (error) {
+    return {
+      url,
+      ok: false,
+      error: error.name === 'AbortError' ? `timeout after ${timeoutMs}ms` : error.message
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function fetchJson(url, timeoutMs, io) {
+  if (typeof io.fetch !== 'function') {
+    throw new UsageError('This Node runtime does not provide fetch; use Node.js 20 or newer.');
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await io.fetch(url, {
+      headers: { accept: 'application/json' },
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      throw new UsageError(`Discovery request failed with HTTP ${response.status}: ${url}`);
+    }
+    return await response.json();
+  } catch (error) {
+    if (error instanceof UsageError) {
+      throw error;
+    }
+    const reason = error.name === 'AbortError' ? `timeout after ${timeoutMs}ms` : error.message;
+    throw new UsageError(`Discovery request failed: ${url} (${reason})`);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function postJson(url, payload, timeoutMs, io, options = {}) {
+  if (typeof io.fetch !== 'function') {
+    throw new UsageError('This Node runtime does not provide fetch; use Node.js 20 or newer.');
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await io.fetch(url, {
+      method: 'POST',
+      headers: {
+        accept: 'application/json',
+        'content-type': 'application/json'
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal
+    });
+    const responsePayload = await response.json();
+    if (!response.ok) {
+      const error = responsePayload?.error ?? responsePayload?.detail ?? `HTTP ${response.status}`;
+      if (options.allowDevicePending && (error === 'authorization_pending' || error === 'slow_down')) {
+        return { error };
+      }
+      throw new UsageError(`Request failed with HTTP ${response.status}: ${url} (${error})`);
+    }
+    return responsePayload;
+  } catch (error) {
+    if (error instanceof UsageError) {
+      throw error;
+    }
+    const reason = error.name === 'AbortError' ? `timeout after ${timeoutMs}ms` : error.message;
+    throw new UsageError(`Request failed: ${url} (${reason})`);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function normalizeBaseUrl(input) {
+  try {
+    const parsed = new URL(input);
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+      throw new UsageError('URL must use http or https.');
+    }
+    parsed.hash = '';
+    parsed.search = '';
+    return parsed.toString().replace(/\/$/, '');
+  } catch (error) {
+    if (error instanceof UsageError) {
+      throw error;
+    }
+    throw new UsageError(`Invalid URL: ${input}`);
+  }
+}
+
+export function endpointUrl(baseUrl, pathname) {
+  const url = new URL(baseUrl);
+  url.pathname = pathname;
+  url.hash = '';
+  url.search = '';
+  return url.toString();
+}

package/src/io.js

@@ -0,0 +1,16 @@
+import { spawn } from 'node:child_process';
+
+export function defaultIo() {
+  return {
+    env: process.env,
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr,
+    fetch: globalThis.fetch,
+    spawn
+  };
+}
+
+export function writeLine(stream, line) {
+  stream.write(`${line}\n`);
+}

package/src/mcp/clients.js

@@ -0,0 +1,80 @@
+import {
+  appendTomlServerConfig,
+  codexTomlSnippet
+} from './codex.js';
+import {
+  hermesYamlSnippet,
+  mergeHermesMcpConfig
+} from './hermes.js';
+import {
+  JSON_MCP_CLIENT_DEFINITIONS,
+  jsonClientSnippet,
+  mergeJsonClientMcpConfig
+} from './json-clients.js';
+import {
+  defaultAntigravity2ConfigPath,
+  defaultAntigravityCliConfigPath,
+  defaultAntigravityConfigPath,
+  defaultAntigravityIdeConfigPath,
+  defaultClaudeConfigPath,
+  defaultClaudecodeConfigPath,
+  defaultClineConfigPath,
+  defaultCodexConfigPath,
+  defaultContinueConfigPath,
+  defaultCursorConfigPath,
+  defaultGeminiConfigPath,
+  defaultHermesConfigPath,
+  defaultJetbrainsConfigPath,
+  defaultKiroConfigPath,
+  defaultOpencodeConfigPath,
+  defaultOpenclawConfigPath,
+  defaultQwenConfigPath,
+  defaultTraeConfigPath,
+  defaultTraeSoloConfigPath,
+  defaultWindsurfConfigPath,
+  defaultZedConfigPath
+} from '../path-config.js';
+import {
+  createMcpClients,
+  supportedMcpClientIds as registrySupportedMcpClientIds,
+  supportedMcpClients as registrySupportedMcpClients
+} from './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/codex.js

@@ -0,0 +1,147 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  COMMAND_NAME,
+  LEGACY_MCP_SERVER_NAMES,
+  MCP_SERVER_NAME,
+  TOKEN_ENV_VAR
+} from '../constants.js';
+import { UsageError } from '../errors.js';
+import {
+  bestEffortChmod,
+  escapeRegExp,
+  escapeTomlString,
+  fileExists,
+  readTextIfExists,
+  unescapeTomlString
+} from '../runtime.js';
+import { agentInstanceIdentityPath } from './identity.js';
+
+export function codexTomlSnippet(mcpUrl) {
+  return `[mcp_servers.${MCP_SERVER_NAME}]
+url = "${escapeTomlString(mcpUrl)}"
+bearer_token_env_var = "${TOKEN_ENV_VAR}"
+`;
+}
+
+export async function codexSmokeReport(configPath, env) {
+  const configText = await readTextIfExists(configPath);
+  const serverBlock = findTomlServerBlock(configText);
+  const block = serverBlock.block;
+  const mcpUrl = block ? tomlStringValue(block, 'url') : null;
+  const bearerTokenEnvVar = block ? tomlStringValue(block, 'bearer_token_env_var') : null;
+  const tokenValue = env[TOKEN_ENV_VAR] ?? '';
+  const identityPath = agentInstanceIdentityPath(env, 'codex');
+  const identityPresent = await fileExists(identityPath);
+  const checks = [
+    {
+      name: 'config_present',
+      ok: configText.trim().length > 0,
+      required: true,
+      detail: configText.trim().length > 0 ? 'found' : 'missing'
+    },
+    {
+      name: 'memory_os_server_present',
+      ok: Boolean(block),
+      required: true,
+      detail: block ? `[mcp_servers.${serverBlock.name}]` : `missing [mcp_servers.${MCP_SERVER_NAME}]`
+    },
+    {
+      name: 'mcp_url_present',
+      ok: Boolean(mcpUrl),
+      required: true,
+      detail: mcpUrl ?? 'missing url'
+    },
+    {
+      name: 'bearer_token_env_var',
+      ok: bearerTokenEnvVar === TOKEN_ENV_VAR,
+      required: true,
+      detail: bearerTokenEnvVar ?? 'missing bearer_token_env_var'
+    },
+    {
+      name: 'token_env_present',
+      ok: Boolean(env[TOKEN_ENV_VAR]),
+      required: true,
+      detail: env[TOKEN_ENV_VAR] ? 'present' : `missing ${TOKEN_ENV_VAR}`
+    },
+    {
+      name: 'token_not_embedded_in_config',
+      ok: !tokenValue || !configText.includes(tokenValue),
+      required: true,
+      detail: 'token value not printed or embedded'
+    },
+    {
+      name: 'agent_instance_identity_file',
+      ok: identityPresent,
+      required: false,
+      detail: identityPresent ? identityPath : `optional; create with ${COMMAND_NAME} mcp add codex --write (${identityPath})`
+    }
+  ];
+
+  return {
+    ok: checks.every((check) => !check.required || check.ok),
+    client: 'codex',
+    configPath,
+    serverName: serverBlock.name ?? MCP_SERVER_NAME,
+    mcpUrl,
+    tokenEnvVar: TOKEN_ENV_VAR,
+    agentInstanceIdPath: identityPath,
+    checks
+  };
+}
+
+export async function appendTomlServerConfig(configPath, mcpUrl) {
+  const snippet = codexTomlSnippet(mcpUrl);
+  const existing = await readTextIfExists(configPath);
+  const existingName = existingTomlMcpServerName(existing);
+  if (existingName) {
+    throw new UsageError(`MCP config already contains [mcp_servers.${existingName}]. Edit ${configPath} manually to avoid duplicate server definitions.`);
+  }
+
+  await fs.mkdir(path.dirname(configPath), { recursive: true, mode: 0o700 });
+  const prefix = existing.trim().length === 0 ? '' : '\n\n';
+  await fs.appendFile(configPath, `${prefix}${snippet}`, { mode: 0o600 });
+  await bestEffortChmod(configPath, 0o600);
+}
+
+function knownMcpServerNames() {
+  return [MCP_SERVER_NAME, ...LEGACY_MCP_SERVER_NAMES];
+}
+
+function existingTomlMcpServerName(content) {
+  return knownMcpServerNames().find((name) => content.includes(`[mcp_servers.${name}]`));
+}
+
+function findTomlServerBlock(content) {
+  const name = existingTomlMcpServerName(content);
+  return {
+    name: name ?? null,
+    block: name ? tomlServerBlock(content, name) : ''
+  };
+}
+
+function tomlServerBlock(content, serverName) {
+  const header = `[mcp_servers.${serverName}]`;
+  const lines = content.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.trim() === header);
+  if (start === -1) {
+    return '';
+  }
+
+  const block = [];
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (/^\s*\[/.test(line)) {
+      break;
+    }
+    block.push(line);
+  }
+  return block.join('\n');
+}
+
+function tomlStringValue(block, key) {
+  const pattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=\\s*"((?:\\\\.|[^"\\\\])*)"\\s*$`, 'm');
+  const match = block.match(pattern);
+  return match ? unescapeTomlString(match[1]) : null;
+}

package/src/mcp/copilot-proxy.js

@@ -0,0 +1,43 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { MCP_SERVER_NAME } from '../constants.js';
+import { UsageError } from '../errors.js';
+import {
+  bestEffortChmod,
+  isPlainObject,
+  parseJsonConfig,
+  readTextIfExists
+} from '../runtime.js';
+import { existingJsonMcpServerName } from './names.js';
+export { mcpProxyCommand } from './proxy.js';
+
+export async function mergeCopilotMcpConfig(configPath, proxyUrl) {
+  const existing = await readTextIfExists(configPath);
+  const parsed = existing.trim().length === 0 ? {} : parseJsonConfig(existing, configPath);
+
+  if (!isPlainObject(parsed)) {
+    throw new UsageError(`Copilot MCP JSON config must be an object: ${configPath}`);
+  }
+
+  if (!isPlainObject(parsed.mcpServers)) {
+    parsed.mcpServers = {};
+  }
+
+  const existingName = existingJsonMcpServerName(parsed.mcpServers);
+  if (existingName) {
+    throw new UsageError(`MCP config already contains mcpServers.${existingName}. Edit ${configPath} manually to avoid duplicate server definitions.`);
+  }
+
+  parsed.mcpServers[MCP_SERVER_NAME] = copilotLocalProxyServerConfig(proxyUrl);
+  await fs.mkdir(path.dirname(configPath), { recursive: true, mode: 0o700 });
+  await fs.writeFile(configPath, `${JSON.stringify(parsed, null, 2)}\n`, { mode: 0o600 });
+  await bestEffortChmod(configPath, 0o600);
+}
+
+export function copilotLocalProxyServerConfig(proxyUrl) {
+  return {
+    type: 'http',
+    url: proxyUrl
+  };
+}

package/src/mcp/detect.js

@@ -0,0 +1,50 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { fileExists } from '../runtime.js';
+import { defaultCopilotConfigPath } from './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/hermes.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  AGENT_INSTANCE_ENV_VAR,
+  MCP_SERVER_NAME,
+  TOKEN_ENV_VAR
+} from '../constants.js';
+import { UsageError } from '../errors.js';
+import {
+  bestEffortChmod,
+  readTextIfExists
+} from '../runtime.js';
+import { envReferenceIdentity } from './identity.js';
+
+export function hermesYamlSnippet(mcpUrl, identity = envReferenceIdentity('hermes')) {
+  return `mcp_servers:
+  ${MCP_SERVER_NAME}:
+    command: npx
+    args:
+      - -y
+      - mcp-remote
+      - ${mcpUrl}
+      - --header
+      - "Authorization:Bearer \${${TOKEN_ENV_VAR}}"
+      - --header
+      - "X-Memory-OS-Agent-ID:${identity.agentId}"
+      - --header
+      - "X-Memory-OS-Agent-Instance-ID:\${${AGENT_INSTANCE_ENV_VAR}}"
+    env:
+      ${TOKEN_ENV_VAR}: "\${env:${TOKEN_ENV_VAR}}"
+      ${AGENT_INSTANCE_ENV_VAR}: "${identity.agentInstanceId}"
+`;
+}
+
+export async function mergeHermesMcpConfig(configPath, mcpUrl, identity) {
+  const existing = await readTextIfExists(configPath);
+
+  if (existing.includes(`${MCP_SERVER_NAME}:`) || existing.includes('memory_os:') || existing.includes('memory-os:')) {
+    throw new UsageError(`MCP config already contains ${MCP_SERVER_NAME} in mcp_servers. Edit ${configPath} manually to avoid duplicate server definitions.`);
+  }
+
+  await fs.mkdir(path.dirname(configPath), { recursive: true, mode: 0o700 });
+
+  if (existing.trim().length === 0) {
+    await fs.writeFile(configPath, hermesYamlSnippet(mcpUrl, identity), { mode: 0o600 });
+  } else if (existing.includes('mcp_servers:')) {
+    const replacement = `mcp_servers:
+  ${MCP_SERVER_NAME}:
+    command: npx
+    args:
+      - -y
+      - mcp-remote
+      - ${mcpUrl}
+      - --header
+      - "Authorization:Bearer \${${TOKEN_ENV_VAR}}"
+      - --header
+      - "X-Memory-OS-Agent-ID:${identity.agentId}"
+      - --header
+      - "X-Memory-OS-Agent-Instance-ID:\${${AGENT_INSTANCE_ENV_VAR}}"
+    env:
+      ${TOKEN_ENV_VAR}: "\${env:${TOKEN_ENV_VAR}}"
+      ${AGENT_INSTANCE_ENV_VAR}: "${identity.agentInstanceId}"`;
+    const updated = existing.replace('mcp_servers:', replacement);
+    await fs.writeFile(configPath, updated, { mode: 0o600 });
+  } else {
+    const prefix = existing.endsWith('\n') ? '' : '\n';
+    await fs.appendFile(configPath, `${prefix}${hermesYamlSnippet(mcpUrl, identity)}`, { mode: 0o600 });
+  }
+  await bestEffortChmod(configPath, 0o600);
+}

package/src/mcp/identity.js

@@ -0,0 +1,62 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+import { AGENT_INSTANCE_ENV_VAR } from '../constants.js';
+import { bestEffortChmod, parseJsonConfig, readTextIfExists } from '../runtime.js';
+import { stringValue } from '../args.js';
+import { configRoot } from './paths.js';
+
+function identityClientId(clientId) {
+  return (clientId === 'antigravity-ide' || clientId === 'antigravity2' || clientId === 'antigravity-cli')
+    ? 'antigravity'
+    : clientId;
+}
+
+export async function agentIdentity(clientId, env) {
+  const targetClientId = identityClientId(clientId);
+  const configuredInstanceId = env[AGENT_INSTANCE_ENV_VAR];
+  if (configuredInstanceId) {
+    return {
+      agentId: targetClientId,
+      agentInstanceId: configuredInstanceId,
+      path: `${AGENT_INSTANCE_ENV_VAR} environment variable`
+    };
+  }
+
+  const identityPath = agentInstanceIdentityPath(env, targetClientId);
+  const existing = await readAgentInstanceIdentity(identityPath);
+  if (existing) {
+    return { agentId: targetClientId, agentInstanceId: existing, path: identityPath };
+  }
+
+  const generated = `xmemo-${targetClientId}-${randomUUID()}`;
+  await fs.mkdir(path.dirname(identityPath), { recursive: true, mode: 0o700 });
+  await bestEffortChmod(path.dirname(identityPath), 0o700);
+  await fs.writeFile(identityPath, `${JSON.stringify({ version: 1, agentId: targetClientId, agentInstanceId: generated }, null, 2)}\n`, { mode: 0o600 });
+  await bestEffortChmod(identityPath, 0o600);
+  return { agentId: targetClientId, agentInstanceId: generated, path: identityPath };
+}
+
+export async function readAgentInstanceIdentity(identityPath) {
+  const existing = await readTextIfExists(identityPath);
+  if (!existing.trim()) {
+    return null;
+  }
+  const parsed = parseJsonConfig(existing, identityPath);
+  const value = stringValue(parsed, ['agentInstanceId']);
+  return value || null;
+}
+
+export function agentInstanceIdentityPath(env, clientId) {
+  return path.join(configRoot(env), 'agent-instances', `${clientId}.json`);
+}
+
+export function envReferenceIdentity(clientId) {
+  const targetClientId = identityClientId(clientId);
+  return {
+    agentId: targetClientId,
+    agentInstanceId: `\${${AGENT_INSTANCE_ENV_VAR}}`,
+    path: `${AGENT_INSTANCE_ENV_VAR} environment variable`
+  };
+}