@xmemo/client 0.4.133 → 0.4.135

package/README.md

@@ -30,10 +30,11 @@ to print the exact command without changing anything.
 ```bash
 xmemo update
 xmemo setup codex
-xmemo setup codex --yes
+xmemo setup codex --dry-run
 xmemo setup cursor
-xmemo setup cursor --yes
+xmemo setup cursor --dry-run
 xmemo setup copilot
+xmemo setup copilot --dry-run
 xmemo doctor
 xmemo discovery show
 xmemo setup
@@ -142,24 +143,23 @@ accepted as a compatibility alias.
 Generate and write a client config from discovery:
 
 ```bash
-xmemo setup codex --yes
-xmemo setup codex --url "https://your-private-service.example" --yes
-xmemo setup cursor --yes
+xmemo setup codex
+xmemo setup codex --url "https://your-private-service.example"
+xmemo setup cursor
 xmemo setup copilot
 ```
 
-`xmemo setup <client>` is the unified setup entry point. Without `--yes` it
-previews what will happen. With `--yes`, write-capable clients apply the
-user-scoped config. Generated config references `XMEMO_KEY`; it does not embed
-the token value. Write-capable client configs also include stable non-secret
-agent identity headers where the client format supports them.
+`xmemo setup <client>` is the unified setup entry point. For write-capable
+clients, it applies the user-scoped config directly; use `--dry-run` to preview
+without writing. Generated config references `XMEMO_KEY`; it does not embed the
+token value. Write-capable client configs also include stable non-secret agent
+identity headers where the client format supports them. `--yes` remains accepted
+for Codex and Cursor as a compatibility no-op.
 
-`xmemo setup codex` is the recommended Codex path. Without `--yes` it
-previews the Codex MCP config and the project-scoped `AGENTS.md` memory profile.
-With `--yes`, it writes the Codex MCP config and installs the profile into the
-current project's `AGENTS.md` marker block. Use `--profile-target <path>` to
-choose a different project instruction file, or `--no-profile` to configure MCP
-only.
+`xmemo setup codex` is the recommended Codex path. It writes the Codex MCP
+config and installs the profile into the current project's `AGENTS.md` marker
+block. Use `--dry-run` to preview, `--profile-target <path>` to choose a
+different project instruction file, or `--no-profile` to configure MCP only.
 
 ## MCP setup
 
@@ -174,24 +174,25 @@ Current write-capable clients:
 ```text
 codex   ~/.codex/config.toml
 cursor  ~/.cursor/mcp.json
+copilot ~/.copilot/mcp-config.json
 ```
 
 For clients without a verified user-scoped write path, generate a read-only
 template and apply it manually after review:
 
 ```bash
-xmemo mcp config --client copilot-cli
 xmemo mcp config --client generic --base-url "https://your-private-service.example" --json
 ```
 
-Only Codex and Cursor currently have write-capable helpers. Other client writes
-should only be added after their official user-scoped config format is verified.
+Codex, Cursor, and Copilot CLI have write-capable setup helpers. Other client
+writes should only be added after their official user-scoped config format is
+verified.
 
 ### Copilot CLI
 
-Copilot CLI has `/mcp` management, but it does not currently document a stable
-cross-platform user config file path/format for third-party tools to edit
-directly. The recommended personal-user path is therefore local proxy mode:
+Copilot CLI has `/mcp` management and reads user MCP configuration from
+`~/.copilot/mcp-config.json` (or `$COPILOT_HOME/mcp-config.json`). XMemo writes
+a local proxy server entry there:
 
 ```bash
 xmemo login
@@ -199,13 +200,13 @@ xmemo setup copilot
 xmemo mcp proxy
 ```
 
-The generated Copilot CLI template points at `http://127.0.0.1:8765/mcp` and
-does not include token or identity headers. `xmemo mcp proxy` reads the token
-saved by `xmemo login` or `xmemo token add --from-stdin`, adds the XMemo bearer
-token and local agent identity, then forwards requests to `https://xmemo.dev/mcp`.
-Copilot CLI does not currently document a stable cross-platform config file for
-third-party tools to edit, so `xmemo setup copilot` prints the template and next
-command instead of writing directly.
+`xmemo setup copilot` writes `memory-os` to Copilot CLI's user MCP config and
+does not include token or identity headers. Use `xmemo setup copilot --dry-run`
+to preview without writing. `xmemo mcp proxy` reads the token saved by
+`xmemo login` or `xmemo token add --from-stdin`, adds the XMemo bearer token and
+local agent identity, then forwards requests to `https://xmemo.dev/mcp`. If
+Copilot CLI is already open, reload MCP config or restart Copilot CLI after
+setup.
 If you specifically want the older environment-variable template, run:
 
 ```bash
@@ -218,14 +219,12 @@ Recommended Codex setup:
 
 ```bash
 xmemo setup codex
-xmemo setup codex --yes
 xmemo smoke --client codex
 ```
 
-`setup codex` is visible and opt-in: the first command previews the writes, and
-`--yes` performs them. The MCP config stays in user-scoped Codex config, while
-the XMemo Codex behavior profile is installed into the current project's
-`AGENTS.md` between these markers:
+`setup codex` writes the MCP config to user-scoped Codex config and installs the
+XMemo Codex behavior profile into the current project's `AGENTS.md` between
+these markers. Use `xmemo setup codex --dry-run` to preview without writing.
 
 ```html
 <!-- memory-os:codex-profile:start -->
@@ -277,11 +276,11 @@ Recommended Cursor setup:
 
 ```bash
 xmemo setup cursor
-xmemo setup cursor --yes
 ```
 
-`setup cursor` previews the Cursor MCP config. `setup cursor --yes` merges it
-into the default Cursor user config path. The lower-level equivalent remains:
+`setup cursor` merges the Cursor MCP config into the default Cursor user config
+path. Use `xmemo setup cursor --dry-run` to preview without writing. The
+lower-level equivalent remains:
 
 ```bash
 xmemo mcp add cursor --url "$XMEMO_URL" --write

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmemo/client",
-  "version": "0.4.133",
+  "version": "0.4.135",
   "description": "Privacy-first CLI and MCP setup helper for XMemo.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -10,7 +10,7 @@ const PACKAGE_NAME = '@xmemo/client';
 const FALLBACK_PACKAGE_NAME = '@yonro/xmemo-client';
 const COMMAND_NAME = 'xmemo';
 const LEGACY_COMMAND_NAME = 'memory-os';
-const CLI_VERSION = '0.4.133';
+const CLI_VERSION = '0.4.135';
 const DEFAULT_SERVICE_URL = 'https://xmemo.dev';
 const TOKEN_ENV_VAR = 'XMEMO_KEY';
 const LEGACY_TOKEN_ENV_VAR = 'MEMORY_OS_MCP_TOKEN';
@@ -157,7 +157,7 @@ function writeHelp(io) {
   writeLine(io.stdout, `  ${COMMAND_NAME} update [--dry-run] [--json]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} doctor [--base-url <https://api.example.com>] [--json]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} discovery show [--base-url <https://api.example.com>] [--json]`);
-  writeLine(io.stdout, `  ${COMMAND_NAME} setup <codex|cursor|copilot> [--url <https://api.example.com>] [--write|--yes] [--json]`);
+  writeLine(io.stdout, `  ${COMMAND_NAME} setup <codex|cursor|copilot> [--url <https://api.example.com>] [--dry-run] [--json]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} login [--from-stdin] [--base-url <url>] [--timeout-ms <ms>] [--http-timeout-ms <ms>] [--json]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} auth status [--verify] [--base-url <url>] [--json]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} status [--url <https://api.example.com>] [--json]`);
@@ -367,8 +367,9 @@ async function setupCommand(args, io) {
   const baseUrl = normalizeBaseUrl(baseUrlOption(optionArgs, io.env));
   const outputJson = hasFlag(optionArgs, '--json');
   const shortClientSetup = Boolean(positionalClientId);
-  const writeConfig = hasFlag(optionArgs, '--write') || (shortClientSetup && hasFlag(optionArgs, '--yes'));
   const clientId = normalizeSetupClientId(positionalClientId ?? optionValue(optionArgs, '--client'));
+  const dryRun = hasFlag(optionArgs, '--dry-run') || hasFlag(optionArgs, '--preview');
+  const writeConfig = !dryRun && (hasFlag(optionArgs, '--write') || hasFlag(optionArgs, '--yes') || shortClientSetup);
   const timeoutMs = parsePositiveInteger(optionValue(optionArgs, '--timeout-ms') ?? '5000', '--timeout-ms');
   const installProfile = shortClientSetup
     && clientId === 'codex'
@@ -391,11 +392,12 @@ async function setupCommand(args, io) {
 
   if (clientId) {
     if (clientId === 'copilot-cli') {
+      const proxyPort = parsePositiveInteger(optionValue(optionArgs, '--port') ?? String(DEFAULT_PROXY_PORT), '--port');
+      setupPlan.selectedClient = copilotSetupPlan(setupPlan.mcpUrl, proxyPort, io.env);
       if (writeConfig) {
-        throw new UsageError(`Copilot CLI setup cannot be written automatically yet. Run \`${COMMAND_NAME} setup copilot\` to print the local proxy template, then add it with Copilot CLI MCP management.`);
+        await mergeCopilotMcpConfig(setupPlan.selectedClient.configPath, setupPlan.selectedClient.proxyUrl);
+        setupPlan.selectedClient.written = true;
       }
-      const proxyPort = parsePositiveInteger(optionValue(optionArgs, '--port') ?? String(DEFAULT_PROXY_PORT), '--port');
-      setupPlan.selectedClient = copilotSetupPlan(setupPlan.mcpUrl, proxyPort);
     } else {
       const client = MCP_CLIENTS.get(clientId);
       if (!client) {
@@ -1425,14 +1427,14 @@ function clientSetupPlan(clientId, client, mcpUrl, env, identity) {
   };
 }
 
-function copilotSetupPlan(mcpUrl, proxyPort) {
+function copilotSetupPlan(mcpUrl, proxyPort, env) {
   const proxyUrl = `http://${DEFAULT_PROXY_HOST}:${proxyPort}/mcp`;
   const template = mcpLocalProxyTemplate('copilot-cli', proxyUrl);
   return {
     id: 'copilot-cli',
     label: 'Copilot CLI',
     configKind: 'local-proxy',
-    configPath: 'Copilot CLI MCP config',
+    configPath: defaultCopilotConfigPath(env),
     serverName: template.serverName,
     mcpUrl,
     proxyUrl,
@@ -1442,7 +1444,7 @@ function copilotSetupPlan(mcpUrl, proxyPort) {
     template: template.snippet,
     agentId: template.agentIdentity.agentId,
     writesTokenValue: false,
-    writeSupported: false,
+    writeSupported: true,
     written: false
   };
 }
@@ -1478,9 +1480,14 @@ function writeSetupSummary(plan, io) {
     }
     if (plan.selectedClient.configKind === 'local-proxy') {
       writeLine(io.stdout, `  Local proxy: ${plan.selectedClient.requiresLocalCommand}`);
-      writeLine(io.stdout, '  MCP template:');
-      writeLine(io.stdout, JSON.stringify(plan.selectedClient.template, null, 2));
-      writeLine(io.stdout, `  Next: add the template with Copilot CLI MCP management, then keep \`${plan.selectedClient.requiresLocalCommand}\` running while you use Copilot CLI.`);
+      if (plan.selectedClient.written) {
+        writeLine(io.stdout, `  Next: keep \`${plan.selectedClient.requiresLocalCommand}\` running while you use Copilot CLI.`);
+        writeLine(io.stdout, '  If Copilot CLI is already open, reload MCP config or restart Copilot CLI.');
+      } else {
+        writeLine(io.stdout, '  MCP template:');
+        writeLine(io.stdout, JSON.stringify(plan.selectedClient.template, null, 2));
+        writeLine(io.stdout, `  Next: ${COMMAND_NAME} setup copilot --url ${plan.baseUrl}`);
+      }
       return;
     }
     if (plan.selectedClient.codexProfile) {
@@ -1493,7 +1500,7 @@ function writeSetupSummary(plan, io) {
       }
     }
     if (!plan.selectedClient.written) {
-      writeLine(io.stdout, `  Next: ${COMMAND_NAME} setup ${plan.selectedClient.id} --url ${plan.baseUrl} --yes`);
+      writeLine(io.stdout, `  Next: ${COMMAND_NAME} setup ${plan.selectedClient.id} --url ${plan.baseUrl}`);
     }
     return;
   }
@@ -1501,7 +1508,7 @@ function writeSetupSummary(plan, io) {
   writeLine(io.stdout, '');
   writeLine(io.stdout, 'Next steps:');
   writeLine(io.stdout, `  1. Create a scoped token in the token portal and store it in ${plan.tokenEnvVar}.`);
-  writeLine(io.stdout, `  2. Configure a client, for example: ${COMMAND_NAME} setup codex --url ${plan.baseUrl} --yes`);
+  writeLine(io.stdout, `  2. Configure a client, for example: ${COMMAND_NAME} setup codex --url ${plan.baseUrl}`);
   writeLine(io.stdout, `  3. Run ${COMMAND_NAME} status to smoke-test the service without sending the token.`);
 }
 
@@ -1566,7 +1573,7 @@ function codexMemoryProfile() {
       'For routine or low-signal output, skip durable writes. Prefer summarized procedural or semantic memories over verbose logs.',
       'Keep XMemo authentication through the XMEMO_KEY environment variable; do not paste token values into prompts, config files, or logs.'
     ],
-    setupCommand: `${COMMAND_NAME} setup codex --url "$XMEMO_URL" --yes`,
+    setupCommand: `${COMMAND_NAME} setup codex --url "$XMEMO_URL"`,
     smokeCommand: `${COMMAND_NAME} smoke --client codex`
   };
 }
@@ -1873,6 +1880,31 @@ async function mergeJsonMcpConfig(configPath, mcpUrl, identity) {
   await bestEffortChmod(configPath, 0o600);
 }
 
+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 = {};
+  }
+
+  parsed.mcpServers['memory-os'] = 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);
+}
+
+function copilotLocalProxyServerConfig(proxyUrl) {
+  return {
+    type: 'http',
+    url: proxyUrl
+  };
+}
+
 function cursorJsonConfig(mcpUrl, identity = envReferenceIdentity('cursor')) {
   return {
     mcpServers: {
@@ -1939,11 +1971,13 @@ function envReferenceIdentity(clientId) {
 }
 
 function supportedMcpClients() {
-  return Array.from(MCP_CLIENTS.entries()).map(([id, client]) => ({
+  const clients = Array.from(MCP_CLIENTS.entries()).map(([id, client]) => ({
     id,
     label: client.label,
     configKind: client.configKind
   }));
+  clients.push({ id: 'copilot-cli', label: 'Copilot CLI', configKind: 'local-proxy' });
+  return clients;
 }
 
 function supportedMcpClientIds() {
@@ -1989,6 +2023,11 @@ function defaultCursorConfigPath(env) {
   return path.join(home, '.cursor', 'mcp.json');
 }
 
+function defaultCopilotConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(env.COPILOT_HOME ?? path.join(home, '.copilot'), 'mcp-config.json');
+}
+
 async function writePlaintextCredential(credentialPath, token, metadata = {}) {
   await fs.mkdir(path.dirname(credentialPath), { recursive: true, mode: 0o700 });
   await bestEffortChmod(path.dirname(credentialPath), 0o700);