@xmemo/client 0.4.155 → 0.4.157

package/src/commands/auth.js

@@ -0,0 +1,230 @@
+import { hasFlag, optionValue, parsePositiveInteger } from '../core/args.js';
+import {
+  formatAccount,
+  pollDeviceLogin,
+  readStoredCredential,
+  resolveCredentialToken,
+  startDeviceLogin,
+  storeTokenFromStdin,
+  storeTokenValue,
+  validateToken
+} from '../network/auth.js';
+import { baseUrlOption } from '../network/base-url.js';
+import {
+  COMMAND_NAME,
+  LEGACY_TOKEN_ENV_VAR,
+  PRODUCT_NAME,
+  TOKEN_ENV_VAR
+} from '../core/constants.js';
+import { UsageError } from '../core/errors.js';
+import { normalizeBaseUrl, verifyTokenWithMcp } from '../network/http.js';
+import { writeLine } from '../core/io.js';
+import { readAll } from '../core/runtime.js';
+
+export async function loginCommand(args, io) {
+  const outputJson = hasFlag(args, '--json');
+  const fromStdin = hasFlag(args, '--from-stdin') || hasFlag(args, '--token-stdin');
+  const baseUrl = normalizeBaseUrl(baseUrlOption(args, io.env));
+  const httpTimeoutMs = parsePositiveInteger(optionValue(args, '--http-timeout-ms') ?? '30000', '--http-timeout-ms');
+  const loginTimeoutOption = optionValue(args, '--timeout-ms');
+  const pollOnce = hasFlag(args, '--poll-once');
+
+  if (fromStdin) {
+    const result = await storeTokenFromStdin(io, { source: 'stdin' });
+    if (outputJson) {
+      writeLine(io.stdout, JSON.stringify(result, null, 2));
+    } else {
+      writeLine(io.stdout, `${PRODUCT_NAME} login complete.`);
+      writeLine(io.stdout, `Stored token in user-scoped credential file: ${result.credentialPath}`);
+      writeLine(io.stdout, 'Token value was not printed. Project files were not modified.');
+    }
+    return 0;
+  }
+
+  const start = await startDeviceLogin(baseUrl, httpTimeoutMs, io);
+  const loginTimeoutMs = loginTimeoutOption
+    ? parsePositiveInteger(loginTimeoutOption, '--timeout-ms')
+    : Math.max(1000, start.expiresIn * 1000);
+  if (!outputJson) {
+    writeLine(io.stdout, `${PRODUCT_NAME} device login`);
+    writeLine(io.stdout, `Open: ${start.verificationUriComplete ?? start.verificationUri}`);
+    if (start.userCode) {
+      writeLine(io.stdout, `Code: ${start.userCode}`);
+    }
+    writeLine(io.stdout, 'Waiting for authorization...');
+  }
+
+  const token = await pollDeviceLogin(baseUrl, start, loginTimeoutMs, httpTimeoutMs, io, { pollOnce });
+  const result = await storeTokenValue(token.accessToken, { source: 'device-login', account: token.account }, io.env);
+  const payload = {
+    ...result,
+    baseUrl,
+    verificationUri: start.verificationUri,
+    account: token.account,
+    deviceLogin: true
+  };
+
+  if (outputJson) {
+    writeLine(io.stdout, JSON.stringify(payload, null, 2));
+  } else {
+    writeLine(io.stdout, 'Login complete. Token stored securely in the user-scoped XMemo CLI config directory.');
+    if (token.account) {
+      writeLine(io.stdout, `Signed in as: ${formatAccount(token.account)}`);
+    }
+    writeLine(io.stdout, `Credential path: ${result.credentialPath}`);
+    writeLine(io.stdout, 'No extra token configuration is required.');
+    writeLine(io.stdout, `Optional check: ${COMMAND_NAME} token status --verify`);
+  }
+  return 0;
+}
+
+export async function authCommand(args, io) {
+  const subcommand = args[0] ?? 'help';
+
+  if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+    writeLine(io.stdout, 'Auth commands:');
+    writeLine(io.stdout, `  ${COMMAND_NAME} auth status [--verify] [--base-url <url>] [--json]`);
+    writeLine(io.stdout, '');
+    writeLine(io.stdout, `Use \`${COMMAND_NAME} login\` to sign in and \`${COMMAND_NAME} token add --from-stdin\` to store an existing token.`);
+    return 0;
+  }
+
+  if (subcommand === 'status') {
+    return await credentialStatusCommand(args.slice(1), io, { mode: 'auth' });
+  }
+
+  throw new UsageError(`Unknown auth command: ${subcommand}`);
+}
+
+export async function tokenCommand(args, io) {
+  const subcommand = args[0] ?? 'help';
+
+  if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+    writeLine(io.stdout, 'Token commands:');
+    writeLine(io.stdout, `  ${COMMAND_NAME} token status [--verify]`);
+    writeLine(io.stdout, `  ${COMMAND_NAME} token add --from-stdin`);
+    writeLine(io.stdout, `  ${COMMAND_NAME} token set --from-stdin [--allow-plaintext]`);
+    writeLine(io.stdout, '');
+    writeLine(io.stdout, `${COMMAND_NAME} login is the recommended personal-user path.`);
+    writeLine(io.stdout, `${COMMAND_NAME} token add --from-stdin stores a token in the user-scoped XMemo CLI config directory.`);
+    return 0;
+  }
+
+  if (subcommand === 'status') {
+    return await credentialStatusCommand(args.slice(1), io, { mode: 'token' });
+  }
+
+  if (subcommand === 'add') {
+    if (!hasFlag(args, '--from-stdin')) {
+      throw new UsageError('Refusing command-line token input. Pipe the token through stdin with --from-stdin.');
+    }
+    const result = await storeTokenFromStdin(io, { source: 'token-add' });
+    if (hasFlag(args, '--json')) {
+      writeLine(io.stdout, JSON.stringify(result, null, 2));
+    } else {
+      writeLine(io.stdout, `Stored token in user-scoped credential file: ${result.credentialPath}`);
+      writeLine(io.stdout, 'Token value was not printed. Project files were not modified.');
+    }
+    return 0;
+  }
+
+  if (subcommand === 'set') {
+    if (!hasFlag(args, '--from-stdin')) {
+      throw new UsageError('Refusing command-line token input. Pipe the token through stdin with --from-stdin.');
+    }
+    const token = (await readAll(io.stdin)).trim();
+    validateToken(token);
+    if (!hasFlag(args, '--allow-plaintext')) {
+      writeLine(io.stderr, 'Token was read from stdin but was not stored.');
+      writeLine(io.stderr, 'Enterprise default refuses plaintext token storage without --allow-plaintext.');
+      writeLine(io.stderr, `Preferred personal-user path: ${COMMAND_NAME} login or ${COMMAND_NAME} token add --from-stdin.`);
+      return 2;
+    }
+
+    const result = await storeTokenValue(token, { source: 'token-set' }, io.env);
+    writeLine(io.stdout, `Stored token in user-scoped credential file: ${result.credentialPath}`);
+    writeLine(io.stdout, 'Token value was not printed. Do not commit this file.');
+    return 0;
+  }
+
+  throw new UsageError(`Unknown token command: ${subcommand}`);
+}
+
+async function credentialStatusCommand(args, io, { mode }) {
+  const outputJson = hasFlag(args, '--json');
+  const verify = hasFlag(args, '--verify');
+  const credential = await readStoredCredential(io.env);
+  const environmentToken = io.env[TOKEN_ENV_VAR] ?? io.env[LEGACY_TOKEN_ENV_VAR] ?? '';
+  const hasEnvironmentToken = Boolean(environmentToken);
+  const hasUserCredential = Boolean(credential.token);
+  const tokenSource = hasEnvironmentToken ? 'environment' : hasUserCredential ? 'user-credential-file' : 'missing';
+  const report = {
+    loggedIn: hasEnvironmentToken || hasUserCredential,
+    tokenSource,
+    environmentToken: {
+      present: hasEnvironmentToken,
+      variable: hasEnvironmentToken && io.env[TOKEN_ENV_VAR] ? TOKEN_ENV_VAR : hasEnvironmentToken ? LEGACY_TOKEN_ENV_VAR : TOKEN_ENV_VAR
+    },
+    userCredentialFile: {
+      present: hasUserCredential,
+      path: credential.path,
+      storage: credential.storage ?? null
+    },
+    account: credential.account ?? null,
+    privacy: {
+      tokenPrinted: false,
+      projectFilesModified: false
+    }
+  };
+
+  if (verify) {
+    const token = await resolveCredentialToken(io.env);
+    if (!token) {
+      if (outputJson) {
+        writeLine(io.stdout, JSON.stringify({ ...report, verification: { ok: false, detail: 'no token found' } }, null, 2));
+      } else {
+        writeCredentialStatus(report, io, { mode });
+        writeLine(io.stderr, `No token found. Run \`${COMMAND_NAME} login\` or \`${COMMAND_NAME} token add --from-stdin\`.`);
+      }
+      return 1;
+    }
+    const baseUrl = normalizeBaseUrl(baseUrlOption(args, io.env));
+    const timeoutMs = parsePositiveInteger(optionValue(args, '--timeout-ms') ?? '10000', '--timeout-ms');
+    const verification = await verifyTokenWithMcp(baseUrl, token, timeoutMs, io);
+    report.verification = verification;
+    if (outputJson) {
+      writeLine(io.stdout, JSON.stringify(report, null, 2));
+      return verification.ok ? 0 : 1;
+    }
+    writeCredentialStatus(report, io, { mode });
+    writeLine(io.stdout, `Remote token verification: ${verification.ok ? 'ok' : 'failed'} (${verification.detail})`);
+    return verification.ok ? 0 : 1;
+  }
+
+  if (outputJson) {
+    writeLine(io.stdout, JSON.stringify(report, null, 2));
+  } else {
+    writeCredentialStatus(report, io, { mode });
+  }
+  return report.loggedIn ? 0 : 1;
+}
+
+function writeCredentialStatus(report, io, { mode }) {
+  if (mode === 'auth') {
+    writeLine(io.stdout, `${PRODUCT_NAME} auth status`);
+    writeLine(io.stdout, `Logged in: ${report.loggedIn ? 'yes' : 'no'}`);
+    writeLine(io.stdout, `Credential source: ${report.tokenSource}`);
+    if (report.account) {
+      writeLine(io.stdout, `Account: ${formatAccount(report.account)}`);
+    }
+    writeLine(io.stdout, report.loggedIn ? 'Credential is ready; token value remains hidden.' : `Run \`${COMMAND_NAME} login\` to sign in.`);
+    return;
+  }
+  writeLine(io.stdout, `Environment token: ${report.environmentToken.present ? 'present' : 'missing'} (${report.environmentToken.variable})`);
+  writeLine(io.stdout, `User credential file: ${report.userCredentialFile.present ? 'present' : 'missing'} (${report.userCredentialFile.path})`);
+  if (report.account) {
+    writeLine(io.stdout, `Account: ${formatAccount(report.account)}`);
+  }
+  writeLine(io.stdout, report.loggedIn ? 'Credential is ready; token value remains hidden.' : `Run \`${COMMAND_NAME} login\` to sign in.`);
+}
+

package/src/commands/diagnostics.js

@@ -0,0 +1,197 @@
+import {
+  booleanValue,
+  hasFlag,
+  optionValue,
+  parsePositiveInteger,
+  sameMajorMinor,
+  stringValue
+} from '../core/args.js';
+import { baseUrlOption } from '../network/base-url.js';
+import {
+  CLI_VERSION,
+  COMMAND_NAME,
+  PACKAGE_NAME,
+  PRODUCT_NAME
+} from '../core/constants.js';
+import { UsageError } from '../core/errors.js';
+import {
+  agentDiscoveryClientIds,
+  bestEffortRootVersion,
+  discoveryMcpUrl,
+  ensureDiscoveryService
+} from '../network/discovery.js';
+import {
+  endpointUrl,
+  fetchJson,
+  normalizeBaseUrl,
+  probe
+} from '../network/http.js';
+import { writeLine } from '../core/io.js';
+import { codexSmokeReport } from '../mcp/formats/toml.js';
+import { defaultCodexConfigPath } from '../config/paths.js';
+
+export async function doctorCommand(args, io) {
+  const baseUrl = normalizeBaseUrl(baseUrlOption(args, io.env));
+  const outputJson = hasFlag(args, '--json');
+  const timeoutMs = parsePositiveInteger(optionValue(args, '--timeout-ms') ?? '5000', '--timeout-ms');
+  const nodeVersion = io.nodeVersion ?? process.versions.node;
+  const discoveryUrl = endpointUrl(baseUrl, '/.well-known/agent-discovery.json');
+  const discovery = await fetchJson(discoveryUrl, timeoutMs, io);
+  ensureDiscoveryService(discovery, discoveryUrl);
+
+  const rootVersion = await bestEffortRootVersion(discovery, timeoutMs, io);
+  const mcpUrl = discoveryMcpUrl(discovery, baseUrl);
+  const checks = [
+    { name: 'node_version', ok: Number.parseInt(nodeVersion.split('.')[0], 10) >= 20, detail: nodeVersion },
+    { name: 'discovery_reachable', ok: true, detail: discoveryUrl },
+    { name: 'mcp_url_present', ok: Boolean(mcpUrl), detail: mcpUrl ?? 'missing' },
+    { name: 'no_remote_code_execution', ok: booleanValue(discovery, ['security', 'no_remote_code_execution']) === true, detail: String(booleanValue(discovery, ['security', 'no_remote_code_execution'])) },
+    {
+      name: 'token_not_in_discovery',
+      ok: booleanValue(discovery, ['security', 'token_in_discovery']) === false && booleanValue(discovery, ['auth', 'token_in_discovery']) === false,
+      detail: `security=${booleanValue(discovery, ['security', 'token_in_discovery'])} auth=${booleanValue(discovery, ['auth', 'token_in_discovery'])}`
+    },
+    {
+      name: 'service_version_compatible',
+      ok: rootVersion.version ? sameMajorMinor(CLI_VERSION, rootVersion.version) : true,
+      detail: rootVersion.version ? `service=${rootVersion.version} cli=${CLI_VERSION}` : `service version unavailable${rootVersion.error ? `: ${rootVersion.error}` : ''}`
+    }
+  ];
+  const report = {
+    ok: checks.every((check) => check.ok),
+    cli: { package: PACKAGE_NAME, version: CLI_VERSION, node: nodeVersion },
+    discovery: {
+      url: discoveryUrl,
+      schemaVersion: stringValue(discovery, ['schema_version']),
+      protocol: stringValue(discovery, ['protocol']),
+      service: stringValue(discovery, ['service']),
+      serviceVersion: rootVersion.version ?? null,
+      mcpUrl,
+      supportedClients: agentDiscoveryClientIds(discovery)
+    },
+    checks
+  };
+
+  if (outputJson) {
+    writeLine(io.stdout, JSON.stringify(report, null, 2));
+    return report.ok ? 0 : 1;
+  }
+
+  writeLine(io.stdout, `${PRODUCT_NAME} CLI ${CLI_VERSION}`);
+  writeLine(io.stdout, `Discovery: ${discoveryUrl}`);
+  writeLine(io.stdout, `MCP: ${mcpUrl ?? 'missing'}`);
+  if (rootVersion.version) {
+    writeLine(io.stdout, `Service version: ${rootVersion.version}`);
+  }
+  writeLine(io.stdout, `Supported clients: ${report.discovery.supportedClients.join(', ') || 'unknown'}`);
+  for (const check of checks) {
+    writeLine(io.stdout, `${check.ok ? 'OK' : 'FAIL'} ${check.name}: ${check.detail}`);
+  }
+  return report.ok ? 0 : 1;
+}
+
+export async function discoveryCommand(args, io) {
+  const subcommand = args[0] ?? 'help';
+  if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+    writeLine(io.stdout, 'Discovery commands:');
+    writeLine(io.stdout, `  ${COMMAND_NAME} discovery show [--base-url <https://api.example.com>] [--json]`);
+    return 0;
+  }
+  if (subcommand !== 'show') {
+    throw new UsageError(`Unknown discovery command: ${subcommand}`);
+  }
+
+  const baseUrl = normalizeBaseUrl(baseUrlOption(args.slice(1), io.env));
+  const outputJson = hasFlag(args, '--json');
+  const timeoutMs = parsePositiveInteger(optionValue(args, '--timeout-ms') ?? '5000', '--timeout-ms');
+  const discoveryUrl = endpointUrl(baseUrl, '/.well-known/agent-discovery.json');
+  const discovery = await fetchJson(discoveryUrl, timeoutMs, io);
+  ensureDiscoveryService(discovery, discoveryUrl);
+
+  if (outputJson) {
+    writeLine(io.stdout, JSON.stringify(discovery, null, 2));
+    return 0;
+  }
+
+  writeLine(io.stdout, `${stringValue(discovery, ['name']) ?? PRODUCT_NAME} discovery`);
+  writeLine(io.stdout, `URL: ${discoveryUrl}`);
+  writeLine(io.stdout, `Protocol: ${stringValue(discovery, ['protocol']) ?? 'unknown'}`);
+  writeLine(io.stdout, `MCP: ${discoveryMcpUrl(discovery, baseUrl) ?? 'missing'}`);
+  writeLine(io.stdout, `Docs: ${stringValue(discovery, ['urls', 'docs']) ?? 'unknown'}`);
+  writeLine(io.stdout, `Clients: ${agentDiscoveryClientIds(discovery).join(', ') || 'unknown'}`);
+  writeLine(io.stdout, 'Security: read-only discovery; tokens are not returned; remote code execution is not advertised.');
+  return 0;
+}
+
+export async function statusCommand(args, io) {
+  const baseUrl = normalizeBaseUrl(baseUrlOption(args, io.env));
+  const outputJson = hasFlag(args, '--json');
+  const timeoutMs = parsePositiveInteger(optionValue(args, '--timeout-ms') ?? '5000', '--timeout-ms');
+  const endpoints = [
+    endpointUrl(baseUrl, '/.well-known/memory-os.json'),
+    endpointUrl(baseUrl, '/health'),
+    endpointUrl(baseUrl, '/ready')
+  ];
+
+  const probes = [];
+  for (const url of endpoints) {
+    probes.push(await probe(url, timeoutMs, io));
+  }
+
+  const result = {
+    ok: probes.some((item) => item.ok),
+    baseUrl,
+    privacy: {
+      telemetry: false,
+      tokenSent: false,
+      tokenSource: 'not-used-by-status'
+    },
+    probes
+  };
+
+  if (outputJson) {
+    writeLine(io.stdout, JSON.stringify(result, null, 2));
+    return result.ok ? 0 : 1;
+  }
+
+  writeLine(io.stdout, `${PRODUCT_NAME} status for ${baseUrl}`);
+  writeLine(io.stdout, 'Privacy: telemetry disabled; no token sent.');
+  for (const item of probes) {
+    if (item.ok) {
+      writeLine(io.stdout, `  OK   ${item.status} ${item.url}`);
+    } else {
+      writeLine(io.stdout, `  FAIL ${item.status ?? 'ERR'} ${item.url} ${item.error ?? ''}`.trimEnd());
+    }
+  }
+
+  return result.ok ? 0 : 1;
+}
+
+export async function smokeCommand(args, io) {
+  const clientId = optionValue(args, '--client');
+  const outputJson = hasFlag(args, '--json');
+  if (!clientId) {
+    throw new UsageError('Smoke requires --client codex for this MCP-depth release.');
+  }
+  if (clientId !== 'codex') {
+    throw new UsageError('Only Codex smoke checks are available in this MCP-depth release.');
+  }
+
+  const configPath = optionValue(args, '--config') ?? defaultCodexConfigPath(io.env);
+  const report = await codexSmokeReport(configPath, io.env);
+
+  if (outputJson) {
+    writeLine(io.stdout, JSON.stringify(report, null, 2));
+    return report.ok ? 0 : 1;
+  }
+
+  writeLine(io.stdout, `${PRODUCT_NAME} Codex MCP smoke: ${report.ok ? 'ok' : 'failed'}`);
+  writeLine(io.stdout, `Config: ${report.configPath}`);
+  writeLine(io.stdout, `Token env: ${report.tokenEnvVar}`);
+  for (const check of report.checks) {
+    const status = check.ok ? 'OK' : check.required ? 'FAIL' : 'WARN';
+    writeLine(io.stdout, `  ${status} ${check.name}: ${check.detail}`);
+  }
+  return report.ok ? 0 : 1;
+}
+

package/src/commands/mcp.js

@@ -0,0 +1,188 @@
+import { hasFlag, optionValue, parsePositiveInteger } from '../core/args.js';
+import { baseUrlOption } from '../network/base-url.js';
+import {
+  AGENT_INSTANCE_ENV_VAR,
+  COMMAND_NAME,
+  DEFAULT_PROXY_HOST,
+  DEFAULT_PROXY_PORT,
+  MCP_SERVER_NAME,
+  PRODUCT_NAME,
+  TOKEN_ENV_VAR
+} from '../core/constants.js';
+import { UsageError } from '../core/errors.js';
+import { endpointUrl, normalizeBaseUrl } from '../network/http.js';
+import { writeLine } from '../core/io.js';
+import {
+  MCP_CLIENTS,
+  supportedMcpClientIds,
+  supportedMcpClients
+} from '../mcp/clients.js';
+import { mcpProxyCommand } from '../mcp/proxy/copilot.js';
+import {
+  agentIdentity,
+  envReferenceIdentity
+} from '../mcp/identity/device.js';
+import {
+  agentInstanceGenerationPolicy,
+  mcpConfigTemplate,
+  mcpLocalProxyTemplate
+} from '../mcp/core/templates.js';
+import { usesClientOAuth } from '../mcp/clients/registry.js';
+import {
+  codexMemoryProfile,
+  writeCodexMemoryProfile
+} from '../config/profile.js';
+
+export async function mcpCommand(args, io) {
+  const subcommand = args[0] ?? 'help';
+
+  if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+    writeLine(io.stdout, 'MCP commands:');
+    writeLine(io.stdout, `  ${COMMAND_NAME} mcp list`);
+    writeLine(io.stdout, `  ${COMMAND_NAME} mcp config --client <codex|cursor|copilot-cli|antigravity|generic> [--base-url <url>] [--json]`);
+    writeLine(io.stdout, `  ${COMMAND_NAME} mcp proxy [--port ${DEFAULT_PROXY_PORT}] [--base-url <url>]`);
+    writeLine(io.stdout, `  ${COMMAND_NAME} mcp profile codex [--json]`);
+    writeLine(io.stdout, `  ${COMMAND_NAME} mcp add <${supportedMcpClientIds().join('|')}> [--url <https://api.example.com>]`);
+    writeLine(io.stdout, `  ${COMMAND_NAME} mcp add <${supportedMcpClientIds().join('|')}> [--url <https://api.example.com>] --write [--config <path>]`);
+    return 0;
+  }
+
+  if (subcommand === 'list') {
+    if (hasFlag(args, '--json')) {
+      writeLine(io.stdout, JSON.stringify(supportedMcpClients(), null, 2));
+      return 0;
+    }
+
+    writeLine(io.stdout, 'Supported MCP clients:');
+    for (const client of supportedMcpClients()) {
+      writeLine(io.stdout, `  ${client.id.padEnd(8)} ${client.label} (${client.configKind})`);
+    }
+    writeLine(io.stdout, `Generated configs never embed token values; OAuth clients do not require ${TOKEN_ENV_VAR} in their config.`);
+    return 0;
+  }
+
+  if (subcommand === 'config') {
+    const clientId = optionValue(args, '--client') ?? args[1] ?? 'generic';
+    const baseUrl = normalizeBaseUrl(baseUrlOption(args, io.env));
+    const mcpUrl = endpointUrl(baseUrl, '/mcp');
+    const useLocalProxy = clientId === 'copilot-cli' && !hasFlag(args, '--remote-env');
+    const proxyPort = parsePositiveInteger(optionValue(args, '--port') ?? String(DEFAULT_PROXY_PORT), '--port');
+    const proxyUrl = `http://${DEFAULT_PROXY_HOST}:${proxyPort}/mcp`;
+    const templateOptions = { mcpClients: MCP_CLIENTS };
+    const template = useLocalProxy
+      ? mcpLocalProxyTemplate(clientId, proxyUrl, templateOptions)
+      : mcpConfigTemplate(clientId, mcpUrl, templateOptions);
+
+    if (hasFlag(args, '--json')) {
+      writeLine(io.stdout, JSON.stringify(template, null, 2));
+      return 0;
+    }
+
+    writeLine(io.stdout, `${PRODUCT_NAME} MCP config template for ${clientId}`);
+    if (useLocalProxy) {
+      writeLine(io.stdout, `Requires credential: ${COMMAND_NAME} login or ${COMMAND_NAME} token add --from-stdin`);
+      writeLine(io.stdout, `Run local proxy: ${template.requiresLocalCommand}`);
+    } else {
+      if (template.requiresEnv?.length > 0) {
+        writeLine(io.stdout, `Requires env: ${template.requiresEnv.join(', ')}`);
+      } else if (template.authentication === 'oauth') {
+        writeLine(io.stdout, 'Requires auth: complete the client MCP OAuth flow after setup.');
+      }
+    }
+    if (typeof template.snippet === 'string') {
+      writeLine(io.stdout, template.snippet.trimEnd());
+    } else {
+      writeLine(io.stdout, JSON.stringify(template.snippet, null, 2));
+    }
+    if (template.optionalEnv?.includes(AGENT_INSTANCE_ENV_VAR)) {
+      writeLine(io.stdout, '');
+      writeLine(io.stdout, `${AGENT_INSTANCE_ENV_VAR} must be stable per local client install.`);
+      if (template.agentInstanceGeneration?.automaticCommand) {
+        writeLine(io.stdout, `Use ${template.agentInstanceGeneration.automaticCommand} to generate and persist it, or set it to a unique value such as xmemo-${clientId}-<uuid>.`);
+      } else {
+        writeLine(io.stdout, `Set it to a unique value such as xmemo-${clientId}-<uuid> and persist it outside git.`);
+      }
+    }
+    writeLine(io.stdout, 'Review the template before applying it. Token values are not included.');
+    return 0;
+  }
+
+  if (subcommand === 'proxy') {
+    return await mcpProxyCommand(args.slice(1), io, { agentIdentity });
+  }
+
+  if (subcommand === 'profile') {
+    const clientId = args[1] ?? 'codex';
+    if (clientId !== 'codex') {
+      throw new UsageError('Only the Codex memory behavior profile is available in this MCP-depth release.');
+    }
+
+    const profile = codexMemoryProfile();
+    if (hasFlag(args, '--json')) {
+      writeLine(io.stdout, JSON.stringify(profile, null, 2));
+      return 0;
+    }
+
+    writeCodexMemoryProfile(profile, io);
+    return 0;
+  }
+
+  const target = args[1] ?? '';
+  const client = MCP_CLIENTS.get(target);
+
+  if (subcommand !== 'add' || !client) {
+    throw new UsageError(`Supported MCP setup command: ${COMMAND_NAME} mcp add <${supportedMcpClientIds().join('|')}> [--url <url>]`);
+  }
+
+  const baseUrl = normalizeBaseUrl(baseUrlOption(args, io.env));
+  const configPath = optionValue(args, '--config') ?? client.defaultConfigPath(io.env);
+  const mcpUrl = endpointUrl(baseUrl, '/mcp');
+
+  if (hasFlag(args, '--json')) {
+    const identity = envReferenceIdentity(target);
+    const oauthClient = usesClientOAuth(target);
+    writeLine(io.stdout, JSON.stringify({
+      client: target,
+      label: client.label,
+      configKind: client.configKind,
+      configPath,
+      serverName: MCP_SERVER_NAME,
+      url: mcpUrl,
+      tokenEnvVar: oauthClient ? null : TOKEN_ENV_VAR,
+      authentication: oauthClient ? 'oauth' : 'env-bearer',
+      agentId: identity.agentId,
+      agentInstanceId: identity.agentInstanceId,
+      agentInstanceIdPath: identity.path,
+      agentInstanceGeneration: agentInstanceGenerationPolicy(target, { mcpClients: MCP_CLIENTS }),
+      writesTokenValue: false
+    }, null, 2));
+    return 0;
+  }
+
+  const identity = hasFlag(args, '--write') ? await agentIdentity(target, io.env) : envReferenceIdentity(target);
+  if (hasFlag(args, '--write')) {
+    await client.writeConfig(configPath, mcpUrl, identity);
+    writeLine(io.stdout, `Updated ${client.label} MCP config: ${configPath}`);
+    if (usesClientOAuth(target)) {
+      writeLine(io.stdout, `Token value was not written. ${client.label} will complete MCP OAuth on first use.`);
+    } else {
+      writeLine(io.stdout, `Token value was not written. ${client.label} will read ${TOKEN_ENV_VAR} from the environment.`);
+    }
+    writeLine(io.stdout, `Agent instance ID stored outside git: ${identity.path}`);
+    return 0;
+  }
+
+  const snippet = client.buildSnippet(mcpUrl, identity);
+  writeLine(io.stdout, `Add this to your ${client.label} config (${configPath}):`);
+  writeLine(io.stdout, '');
+  writeLine(io.stdout, snippet.trimEnd());
+  writeLine(io.stdout, '');
+  if (usesClientOAuth(target)) {
+    writeLine(io.stdout, `Restart ${client.label} and complete its MCP OAuth flow. No token value is included here.`);
+  } else {
+    writeLine(io.stdout, `Set ${TOKEN_ENV_VAR} in your user environment or secret manager. The token value is not included here.`);
+  }
+  writeLine(io.stdout, `${AGENT_INSTANCE_ENV_VAR} must be stable per local ${client.label} install; run ${COMMAND_NAME} mcp add ${target} --write to generate it automatically.`);
+  return 0;
+}
+

package/src/commands/profile.js

@@ -0,0 +1,57 @@
+import { hasFlag, optionValue } from '../core/args.js';
+import { COMMAND_NAME } from '../core/constants.js';
+import { UsageError } from '../core/errors.js';
+import { writeLine } from '../core/io.js';
+import { MCP_CLIENTS } from '../mcp/clients.js';
+import {
+  defaultProfileTarget,
+  profileClientConfig,
+  profileInstallResult,
+  profileStatusResult,
+  profileUninstallResult,
+  supportedProfileClientIds,
+  writeProfileResult
+} from '../config/profile.js';
+import { normalizeSetupClientId } from '../ui/setup.js';
+
+export async function profileCommand(args, io) {
+  const subcommand = args[0] ?? 'help';
+  if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+    writeLine(io.stdout, 'Profile commands:');
+    writeLine(io.stdout, `  ${COMMAND_NAME} profile install <codex|cursor|gemini|antigravity|qwen|opencode> [--target <path>] [--dry-run|--json]`);
+    writeLine(io.stdout, `  ${COMMAND_NAME} profile status <codex|cursor|gemini|antigravity|qwen|opencode> [--target <path>] [--json]`);
+    writeLine(io.stdout, `  ${COMMAND_NAME} profile uninstall <codex|cursor|gemini|antigravity|qwen|opencode> [--target <path>] [--json]`);
+    writeLine(io.stdout, '');
+    writeLine(io.stdout, 'Profile installs are marker-scoped and never write token values.');
+    return 0;
+  }
+
+  const clientId = normalizeSetupClientId(args[1], MCP_CLIENTS);
+  if (!profileClientConfig(clientId)) {
+    throw new UsageError(`Unsupported profile client: ${args[1] ?? 'missing'}. Supported clients: ${supportedProfileClientIds().join(', ')}.`);
+  }
+
+  const optionArgs = args.slice(2);
+  const outputJson = hasFlag(optionArgs, '--json');
+  const targetPath = optionValue(optionArgs, '--target') ?? defaultProfileTarget(clientId, io.env);
+  let result;
+
+  if (subcommand === 'install') {
+    result = await profileInstallResult(clientId, targetPath, { write: !hasFlag(optionArgs, '--dry-run') });
+  } else if (subcommand === 'status') {
+    result = await profileStatusResult(clientId, targetPath);
+  } else if (subcommand === 'uninstall') {
+    result = await profileUninstallResult(clientId, targetPath, { write: !hasFlag(optionArgs, '--dry-run') });
+  } else {
+    throw new UsageError(`Unknown profile command: ${subcommand}`);
+  }
+
+  if (outputJson) {
+    writeLine(io.stdout, JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  writeProfileResult(subcommand, result, io);
+  return 0;
+}
+