@xmemo/client 0.4.132 → 0.4.134

package/README.md

@@ -30,8 +30,10 @@ to print the exact command without changing anything.
 ```bash
 xmemo update
 xmemo setup codex
-xmemo setup codex --yes
-xmemo smoke --client codex
+xmemo setup codex --dry-run
+xmemo setup cursor
+xmemo setup cursor --dry-run
+xmemo setup copilot
 xmemo doctor
 xmemo discovery show
 xmemo setup
@@ -44,7 +46,7 @@ xmemo env example --shell bash
 xmemo mcp list
 xmemo mcp config --client generic
 xmemo profile status codex
-xmemo mcp add cursor --url "https://your-private-service.example"
+xmemo smoke --client codex
 xmemo privacy
 ```
 
@@ -140,23 +142,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 --url "https://your-private-service.example" --client codex --write
-xmemo setup --url "https://your-private-service.example" --client cursor --write
+xmemo setup codex
+xmemo setup codex --url "https://your-private-service.example"
+xmemo setup cursor
+xmemo setup copilot
 ```
 
-`--write` requires an explicit `--client` so the CLI never performs broad config
-writes implicitly. 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
 
@@ -192,7 +194,7 @@ directly. The recommended personal-user path is therefore local proxy mode:
 
 ```bash
 xmemo login
-xmemo mcp config --client copilot-cli
+xmemo setup copilot
 xmemo mcp proxy
 ```
 
@@ -200,6 +202,9 @@ 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.
 If you specifically want the older environment-variable template, run:
 
 ```bash
@@ -212,14 +217,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 -->
@@ -267,13 +270,15 @@ absence of embedded token values.
 
 ### Cursor
 
-Generate a Cursor MCP config snippet:
+Recommended Cursor setup:
 
 ```bash
-xmemo mcp add cursor --url "$XMEMO_URL"
+xmemo setup cursor
 ```
 
-Merge it into the default Cursor user config path:
+`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.132",
+  "version": "0.4.134",
   "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.132';
+const CLI_VERSION = '0.4.134';
 const DEFAULT_SERVICE_URL = 'https://xmemo.dev';
 const TOKEN_ENV_VAR = 'XMEMO_KEY';
 const LEGACY_TOKEN_ENV_VAR = 'MEMORY_OS_MCP_TOKEN';
@@ -44,6 +44,13 @@ const MCP_CLIENTS = new Map([
   }]
 ]);
 
+const SETUP_CLIENT_ALIASES = new Map([
+  ['codex', 'codex'],
+  ['cursor', 'cursor'],
+  ['copilot', 'copilot-cli'],
+  ['copilot-cli', 'copilot-cli']
+]);
+
 class UsageError extends Error {
   constructor(message) {
     super(message);
@@ -150,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] [--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]`);
@@ -360,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 = positionalClientId ?? optionValue(optionArgs, '--client');
+  const clientId = normalizeSetupClientId(positionalClientId ?? optionValue(optionArgs, '--client'));
+  const dryRun = hasFlag(optionArgs, '--dry-run') || hasFlag(optionArgs, '--preview');
+  const writeConfig = !dryRun && (hasFlag(optionArgs, '--write') || (shortClientSetup && clientId !== 'copilot-cli'));
   const timeoutMs = parsePositiveInteger(optionValue(optionArgs, '--timeout-ms') ?? '5000', '--timeout-ms');
   const installProfile = shortClientSetup
     && clientId === 'codex'
@@ -383,24 +391,32 @@ async function setupCommand(args, io) {
   const setupPlan = buildSetupPlan({ baseUrl, discoveryUrl, statusUrl, discovery, status });
 
   if (clientId) {
-    const client = MCP_CLIENTS.get(clientId);
-    if (!client) {
-      throw new UsageError(`Unsupported MCP client: ${clientId}. Supported clients: ${supportedMcpClientIds().join(', ')}.`);
-    }
+    if (clientId === 'copilot-cli') {
+      if (hasFlag(optionArgs, '--write') || hasFlag(optionArgs, '--yes')) {
+        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.`);
+      }
+      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) {
+        throw new UsageError(`Unsupported MCP client: ${clientId}. Supported clients: ${supportedSetupClientIds().join(', ')}.`);
+      }
 
-    const identity = writeConfig ? await agentIdentity(clientId, io.env) : envReferenceIdentity(clientId);
-    setupPlan.selectedClient = clientSetupPlan(clientId, client, setupPlan.mcpUrl, io.env, identity);
-    if (writeConfig) {
-      await client.writeConfig(setupPlan.selectedClient.configPath, setupPlan.mcpUrl, identity);
-      setupPlan.selectedClient.written = true;
-    }
+      const identity = writeConfig ? await agentIdentity(clientId, io.env) : envReferenceIdentity(clientId);
+      setupPlan.selectedClient = clientSetupPlan(clientId, client, setupPlan.mcpUrl, io.env, identity);
+      if (writeConfig) {
+        await client.writeConfig(setupPlan.selectedClient.configPath, setupPlan.mcpUrl, identity);
+        setupPlan.selectedClient.written = true;
+      }
 
-    if (clientId === 'codex' && shortClientSetup) {
-      const profileTarget = optionValue(optionArgs, '--profile-target')
-        ?? optionValue(optionArgs, '--target')
-        ?? defaultCodexProfileTarget();
-      const profileResult = await codexProfileInstallResult(profileTarget, { write: installProfile });
-      setupPlan.selectedClient.codexProfile = profileResult;
+      if (clientId === 'codex' && shortClientSetup) {
+        const profileTarget = optionValue(optionArgs, '--profile-target')
+          ?? optionValue(optionArgs, '--target')
+          ?? defaultCodexProfileTarget();
+        const profileResult = await codexProfileInstallResult(profileTarget, { write: installProfile });
+        setupPlan.selectedClient.codexProfile = profileResult;
+      }
     }
   }
 
@@ -1410,6 +1426,28 @@ function clientSetupPlan(clientId, client, mcpUrl, env, identity) {
   };
 }
 
+function copilotSetupPlan(mcpUrl, proxyPort) {
+  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',
+    serverName: template.serverName,
+    mcpUrl,
+    proxyUrl,
+    tokenEnvVar: TOKEN_ENV_VAR,
+    requiresCredential: template.requiresCredential,
+    requiresLocalCommand: template.requiresLocalCommand,
+    template: template.snippet,
+    agentId: template.agentIdentity.agentId,
+    writesTokenValue: false,
+    writeSupported: false,
+    written: false
+  };
+}
+
 function writeSetupSummary(plan, io) {
   writeLine(io.stdout, `${PRODUCT_NAME} setup discovery: ${plan.baseUrl}`);
   writeLine(io.stdout, `  API: ${plan.apiBase}`);
@@ -1436,7 +1474,16 @@ function writeSetupSummary(plan, io) {
     writeLine(io.stdout, `  Written: ${plan.selectedClient.written}`);
     writeLine(io.stdout, `  Token value embedded: ${plan.selectedClient.writesTokenValue}`);
     writeLine(io.stdout, `  Agent ID: ${plan.selectedClient.agentId}`);
-    writeLine(io.stdout, `  Agent instance ID stored: ${plan.selectedClient.agentInstanceIdPath}`);
+    if (plan.selectedClient.agentInstanceIdPath) {
+      writeLine(io.stdout, `  Agent instance ID stored: ${plan.selectedClient.agentInstanceIdPath}`);
+    }
+    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.`);
+      return;
+    }
     if (plan.selectedClient.codexProfile) {
       const profile = plan.selectedClient.codexProfile;
       writeLine(io.stdout, `  Codex profile target: ${profile.targetPath}`);
@@ -1447,7 +1494,7 @@ function writeSetupSummary(plan, io) {
       }
     }
     if (!plan.selectedClient.written) {
-      writeLine(io.stdout, `  Next: ${COMMAND_NAME} mcp add ${plan.selectedClient.id} --url ${plan.apiBase} --write`);
+      writeLine(io.stdout, `  Next: ${COMMAND_NAME} setup ${plan.selectedClient.id} --url ${plan.baseUrl}`);
     }
     return;
   }
@@ -1455,7 +1502,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 --url ${plan.baseUrl} --client codex --write`);
+  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.`);
 }
 
@@ -1520,7 +1567,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`
   };
 }
@@ -1904,6 +1951,10 @@ function supportedMcpClientIds() {
   return Array.from(MCP_CLIENTS.keys());
 }
 
+function supportedSetupClientIds() {
+  return ['codex', 'cursor', 'copilot'];
+}
+
 function credentialsPath(env) {
   return path.join(configRoot(env), 'credentials.json');
 }
@@ -1990,11 +2041,20 @@ function positionalClientArg(args) {
     return null;
   }
 
-  if (!MCP_CLIENTS.has(candidate)) {
-    throw new UsageError(`Unsupported setup client: ${candidate}. Supported clients: ${supportedMcpClientIds().join(', ')}.`);
+  return normalizeSetupClientId(candidate);
+}
+
+function normalizeSetupClientId(candidate) {
+  if (!candidate) {
+    return null;
+  }
+
+  const normalized = SETUP_CLIENT_ALIASES.get(candidate);
+  if (!normalized) {
+    throw new UsageError(`Unsupported setup client: ${candidate}. Supported clients: ${supportedSetupClientIds().join(', ')}.`);
   }
 
-  return candidate;
+  return normalized;
 }
 
 function optionValue(args, name) {