@empirical-gauzza/cli 1.0.9

package/lib/installWizard.js

@@ -0,0 +1,383 @@
+'use strict';
+
+const { log, warn, uiHeader, uiQuestion, uiSuccess, uiWarn, uiDim, uiLink, ask, askYesNo, parseSelection, formatHeadlessErrorHint } = require('./ui');
+const { getEnv } = require('./env');
+const { summarizeProcessOutput } = require('./fsUtils');
+const {
+  EMPIRICAL_MCP_NAME, EMPIRICAL_MCP_URL,
+  getCliVersion, deriveBaseUrlFromMcpUrl
+} = require('./constants');
+const {
+  readStoredOAuthClient, writeStoredOAuthClient, getLocalOAuthClientPath,
+  persistAccessToken, getHeadlessTokenPath
+} = require('./oauthClient');
+const {
+  oauthPreflight, ensureHeadlessToken, selfProvisionHeadlessCredentials,
+  runMcpOAuthFlow, updateClaudeMcpServerAuth, resolveAccessToken
+} = require('./auth');
+const { performSync, printSyncSummary } = require('./skillSync');
+const {
+  INSTALL_PROMPT_OPTIONS_DEFAULTS, collectInstallerPromptOptions,
+} = require('./installers/promptBlocks');
+const { detectInstallTargets } = require('./installers/detect');
+const { installClaudeHooks } = require('./installers/hooks');
+const { runCodex } = require('./installers/codex');
+const { installNativePlugin, OPTIONAL_PLUGIN_NAMES } = require('./installers/nativePlugin');
+const { policyFromInstallerOptions, savePolicy: persistPolicy } = require('./policyCommands');
+
+function pluginNamesForInstallerOptions(options = {}) {
+  const names = ['empirical-memory'];
+  if (options.recordWorkHistory !== false) names.push('empirical-work-history');
+  if (options.recordScarTissue !== false) names.push('empirical-scar-tissue');
+  if (options.recordTodos === true) names.push('empirical-todo');
+  return names.filter((name) => name === 'empirical-memory' || OPTIONAL_PLUGIN_NAMES.includes(name));
+}
+
+async function runInstallFlow() {
+  log(uiHeader(`Empirical installer v${getCliVersion()}`));
+  log('');
+
+  const targets = detectInstallTargets();
+  if (targets.length === 0) {
+    log('No supported CLI configs detected.');
+    log('Supported installers: Codex CLI, GitHub Copilot CLI, Claude CLI.');
+    process.exitCode = 1;
+    return;
+  }
+
+  log(uiHeader('Detected CLIs (all selected by default):'));
+  targets.forEach((target, index) => {
+    log(`  [x] ${index + 1}. ${target.label}`);
+  });
+  log('');
+
+  const answer = await ask(uiQuestion('Press Enter for all, or select numbers (e.g. 1,2): '));
+  const selectedIndexes = parseSelection(answer, targets.length);
+
+  if (selectedIndexes.length === 0) {
+    log('No valid selection; nothing installed.');
+    process.exitCode = 1;
+    return;
+  }
+
+  log('');
+
+  // Integration mode selection
+  let integrationMode = 1; // default: MCP
+  if (process.stdin.isTTY) {
+    log(uiQuestion('How should agents interact with Empirical?'));
+    log('  1. Via MCP tool (recommended)');
+    log('  2. Via CLI commands');
+    log('  3. Both (MCP primary, CLI fallback)');
+    const modeAnswer = (await ask(uiDim('Enter 1, 2, or 3 [default: 1]: '))).trim();
+    integrationMode = modeAnswer === '2' ? 2 : modeAnswer === '3' ? 3 : 1;
+    log('');
+  }
+
+  let promptOptions;
+  let savePolicyEnabled;
+
+  if (integrationMode === 2) {
+    // CLI-direct mode: skip MCP-specific installer questions
+    promptOptions = { ...INSTALL_PROMPT_OPTIONS_DEFAULTS };
+    savePolicyEnabled = true;
+  } else {
+    const promptSetup = await collectInstallerPromptOptions();
+    promptOptions = promptSetup.promptOptions;
+    savePolicyEnabled = promptSetup.savePolicy !== false;
+  }
+
+  log(uiHeader('Installer auth setup'));
+  log('');
+  const installerBaseUrl = getEnv('EMPIRICAL_BASE_URL', '') || deriveBaseUrlFromMcpUrl() || 'https://empirical.gauzza.com';
+  if (!getEnv('EMPIRICAL_BASE_URL')) {
+    process.env.EMPIRICAL_BASE_URL = installerBaseUrl;
+  }
+  const useHeadlessDefault = getEnv('EMPIRICAL_HEADLESS_DEFAULT', 'true').toLowerCase() !== 'false';
+  const settingsUrl = `${installerBaseUrl.replace(/\/$/, '')}/app/settings`;
+  let headlessToken = null;
+  let policyAccessToken = null;
+  try {
+    const existingClient = readStoredOAuthClient();
+    if (getEnv('EMPIRICAL_CLIENT_ID')) {
+      log('Step 1/2: OAuth client credentials found in environment (EMPIRICAL_CLIENT_ID).');
+    } else if (existingClient?.clientId) {
+      log(`Step 1/2: OAuth client credentials found at ${getLocalOAuthClientPath()}.`);
+    } else {
+      if (process.stdin.isTTY) {
+        log('Step 1/2: No saved headless credentials found. Enter client id/secret or press Enter to self-provision from your account.');
+        const manualClientId = (await ask('OAuth client ID (blank to self-provision): ')).trim();
+        if (manualClientId) {
+          const manualSecret = (await ask('OAuth client secret (optional): ')).trim();
+          writeStoredOAuthClient(manualClientId, manualSecret);
+          log(`  - Saved OAuth client credentials to ${getLocalOAuthClientPath()}.`);
+        } else {
+          log('  - Self-provisioning credentials from your account...');
+          const provisioned = await selfProvisionHeadlessCredentials({ baseUrl: installerBaseUrl });
+          if (provisioned?.clientId) {
+            writeStoredOAuthClient(provisioned.clientId, provisioned.clientSecret || '');
+            log(`  - Saved credentials to ${getLocalOAuthClientPath()}.`);
+          } else {
+            log('  - Skipped (declined, or no existing session to identify the account). Interactive OAuth will be used when required.');
+          }
+        }
+      } else {
+        log('Step 1/2: No saved headless credentials found. Self-provisioning from your account...');
+        const provisioned = await selfProvisionHeadlessCredentials({ baseUrl: installerBaseUrl, allowBrowserLogin: false });
+        if (provisioned?.clientId) {
+          writeStoredOAuthClient(provisioned.clientId, provisioned.clientSecret || '');
+          log(`  - Saved credentials to ${getLocalOAuthClientPath()}.`);
+        } else {
+          log('  - Skipped (no existing session/token found to identify the account non-interactively).');
+        }
+      }
+    }
+  } catch (error) {
+    warn(`Step 1/2 warning: OAuth client provisioning failed: ${error.message}`);
+    warn('Continuing install. You can run "empirical oauth client set" manually.');
+  }
+  log('');
+
+  let shouldBootstrapHeadless = useHeadlessDefault;
+  if (process.stdin.isTTY) {
+    log('Optional credential setup:');
+    log('  Browser OAuth is the normal choice for interactive CLI use.');
+    log('  Headless bootstrap creates reusable credentials for CLI use, automation, containers, and external runtimes.');
+    log('  Headless bootstrap uses Settings client credentials (client ID + client secret).');
+    log('  Client credentials are loaded from env/saved oauth-client.json, with prompt fallback.');
+    log(`  Settings: ${uiLink(settingsUrl)}`);
+    shouldBootstrapHeadless = await askYesNo('Bootstrap headless token now?', useHeadlessDefault);
+    log('');
+  } else {
+    log(`Settings: ${uiLink(settingsUrl)}`);
+  }
+
+  if (shouldBootstrapHeadless) {
+    let bootstrapAttempts = 0;
+    while (bootstrapAttempts < 3) {
+      try {
+        bootstrapAttempts += 1;
+        log(`Headless auth: bootstrapping access token for CLI clients (attempt ${bootstrapAttempts}/3)...`);
+        // Step 1/2 above already loaded or self-provisioned credentials into
+        // oauth-client.json, so don't force a re-prompt here — that just makes
+        // the user paste back the client ID/secret we already have. Only
+        // runHeadlessBootstrap's own fallback (no clientId at all) should prompt.
+        headlessToken = await ensureHeadlessToken({ promptCredentials: false });
+        const persistedToken = headlessToken?.apiKey || headlessToken?.accessToken;
+        if (persistedToken) {
+          persistAccessToken(persistedToken);
+          log(uiSuccess(`Headless token saved at ${getHeadlessTokenPath()}.`));
+        }
+        log('');
+        break;
+      } catch (error) {
+        const hint = formatHeadlessErrorHint(error.message);
+        warn(uiWarn(`Headless auth failed: ${error.message}`));
+        if (hint) {
+          warn(`  ${hint}`);
+        }
+        warn(`  Settings: ${settingsUrl}`);
+        if (!process.stdin.isTTY || bootstrapAttempts >= 3) {
+          warn('Continuing install with interactive OAuth if required.');
+          log('');
+          break;
+        }
+
+        const retry = await askYesNo('Retry headless bootstrap now?', true);
+        log('');
+        if (!retry) {
+          warn('Continuing install with interactive OAuth if required.');
+          log('');
+          break;
+        }
+      }
+    }
+  } else {
+    log('Headless auth: skipped by user choice. Interactive OAuth will be used when required.');
+    log('');
+  }
+
+  if ((integrationMode === 2 || integrationMode === 3) && !resolveAccessToken()) {
+    try {
+      log('CLI auth: no reusable credential found. Opening browser OAuth login...');
+      await runMcpOAuthFlow(installerBaseUrl);
+      log(uiSuccess('CLI OAuth session saved. Empirical CLI commands are ready to use.'));
+      log('');
+    } catch (error) {
+      warn(uiWarn(`CLI OAuth login failed: ${error.message}`));
+      warn('  CLI commands will need a credential later: run "empirical auth login".');
+      log('');
+    }
+  }
+
+  if (integrationMode !== 2) {
+    const preflight = await oauthPreflight(EMPIRICAL_MCP_URL);
+    if (!preflight.ok) {
+      warn(`OAuth preflight warning: ${preflight.message}`);
+      warn('Codex/Claude setup may fail until the hosted OAuth login page is updated.');
+      log('');
+    }
+  }
+
+  let failures = 0;
+  let claudeInstalled = false;
+  let codexInstalled = false;
+  let codexNeedsPostLogin = false;
+
+  for (const index of selectedIndexes) {
+    const target = targets[index];
+    log(uiHeader(`Step 2/2: Installing for ${target.label}...`));
+    try {
+      if (integrationMode === 2) {
+        // CLI-direct: skip MCP registration; the native plugin owns guidance.
+        const pluginNames = pluginNamesForInstallerOptions(promptOptions);
+        installNativePlugin(target.id, pluginNames);
+        log(`  - ${target.label} native plugins installed: ${pluginNames.join(', ')}.`);
+        if (target.id === 'claude') {
+          try {
+            installClaudeHooks();
+          } catch (error) {
+            warn(`  - Could not install Claude hooks for deterministic memory lookups: ${error.message}`);
+          }
+        }
+        log(uiSuccess(`Done: ${target.label} (CLI-direct mode)`));
+      } else {
+        // Mode 1 or 3: run MCP install normally
+        const pluginNames = pluginNamesForInstallerOptions(promptOptions);
+        const installResult = target.install(headlessToken, promptOptions, {
+          writeGlobalInstructions: false,
+          pluginNames
+        });
+        log(uiSuccess(`Done: ${target.label}`));
+        if (target.id === 'codex') {
+          codexInstalled = true;
+          codexNeedsPostLogin = Boolean(installResult?.needsPostLogin);
+        }
+        if (target.id === 'claude') {
+          claudeInstalled = true;
+        }
+      }
+    } catch (error) {
+      failures += 1;
+      warn(uiWarn(`Failed: ${target.label} - ${error.message}`));
+    }
+    log('');
+  }
+
+  if (failures > 0) {
+    warn(`Completed with ${failures} failure(s).`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Authenticate Empirical MCP for Codex automatically after installation.
+  if (codexInstalled && codexNeedsPostLogin && process.stdin.isTTY) {
+    log(uiHeader('Empirical MCP authentication (Codex)'));
+    try {
+      log('');
+      log(uiQuestion('Authenticating Empirical MCP in Codex...'));
+      const loginResult = runCodex(['mcp', 'login', EMPIRICAL_MCP_NAME], { stdio: 'inherit' });
+      if (loginResult.status === 0) {
+        log(uiSuccess('Empirical MCP authenticated successfully in Codex!'));
+      } else {
+        const detail = summarizeProcessOutput(loginResult);
+        warn(uiWarn(`Codex MCP authentication returned a non-zero status${detail ? `: ${detail}` : '.'}`));
+        warn('Re-run `empirical install` to retry automatic authentication.');
+      }
+    } catch (error) {
+      warn(uiWarn(`Codex MCP authentication failed: ${error.message}`));
+      warn('Re-run `empirical install` to retry automatic authentication.');
+    }
+    log('');
+  }
+
+  // Offer to authenticate Empirical MCP after Claude installation.
+  // Prefer the permanent API key from the headless bootstrap (never expires)
+  // over a short-lived JWT from the browser OAuth flow.
+  if (claudeInstalled && process.stdin.isTTY) {
+    log(uiHeader('Empirical MCP authentication'));
+    const permanentToken = headlessToken?.apiKey || '';
+    if (permanentToken) {
+      // Headless bootstrap already ran — write the API key as the Bearer credential.
+      // API keys never expire, so Claude sessions stay authenticated indefinitely.
+      try {
+        updateClaudeMcpServerAuth(EMPIRICAL_MCP_NAME, permanentToken);
+        log(uiSuccess('Empirical MCP configured with a permanent API key — no re-auth needed!'));
+      } catch (error) {
+        warn(uiWarn(`Could not write Claude MCP auth: ${error.message}`));
+      }
+    } else {
+      try {
+        log('');
+        log(uiQuestion('Authenticating Empirical MCP...'));
+        const mcpToken = await runMcpOAuthFlow(installerBaseUrl);
+        policyAccessToken = mcpToken.accessToken;
+        updateClaudeMcpServerAuth(EMPIRICAL_MCP_NAME, mcpToken.accessToken);
+        log(uiSuccess('Empirical MCP authenticated successfully in Claude!'));
+        log('  Note: this OAuth token expires in ~30 days. Re-run the installer with');
+        log('  your Settings client credentials to get a permanent credential instead.');
+      } catch (error) {
+        warn(uiWarn(`MCP authentication failed: ${error.message}`));
+        warn('You can authenticate later from Claude Code by using the /mcp command.');
+      }
+    }
+    log('');
+  }
+
+  // Persist the selected behavior after the installer has had a chance to complete OAuth/MCP
+  // authentication. In MCP-only mode, authentication happens after native installation.
+  try {
+    const accessToken = resolveAccessToken() || policyAccessToken;
+    if (accessToken && savePolicyEnabled) {
+      await persistPolicy(policyFromInstallerOptions(promptOptions), accessToken);
+      log(uiSuccess('Empirical behavior policy saved for native skills.'));
+    } else if (accessToken) {
+      log('Empirical behavior policy not saved by user choice; native skills will use safe defaults.');
+    } else {
+      warn('Empirical behavior policy was not saved: no authenticated CLI credential is available yet.');
+    }
+    log('');
+  } catch (error) {
+    warn(uiWarn(`Empirical behavior policy could not be saved: ${error.message}`));
+    log('');
+  }
+
+  // US-011: independent of whether any Kit exists or `kit use` has ever been run, also sync
+  // the active device's resolved (builtin ∪ Default Kit ∪ active named Kit) Skill set into
+  // every detected agent's skill directory now, so a brand-new device gets the Default Kit's
+  // authored Skills (if any exist yet — likely none for a fresh account, which is fine; the
+  // sync just writes zero non-builtin Skills) immediately. This does NOT touch the
+  // Native plugin installation above owns the empirical-memory Skill. The generalized Kit
+  // writer below must continue to exclude the builtin placeholder with the same name.
+  try {
+    const syncAccessToken = resolveAccessToken();
+    if (syncAccessToken) {
+      log(uiHeader('Syncing Kit skills...'));
+      const syncResult = await performSync({
+        accessToken: syncAccessToken,
+        baseUrl: installerBaseUrl,
+        dryRun: false,
+        force: false
+      });
+      printSyncSummary(syncResult, false);
+      log('');
+    } else {
+      warn('  - Skipped Kit skill sync: no access token available.');
+      log('');
+    }
+  } catch (error) {
+    warn(uiWarn(`Kit skill sync failed: ${error.message}`));
+    log('');
+  }
+
+  const completionMessage = integrationMode === 2
+    ? 'Install complete. Next time you open the selected CLI(s), Empirical CLI commands should be available.'
+    : integrationMode === 3
+      ? 'Install complete. Next time you open the selected CLI(s), Empirical MCP and CLI commands should be available.'
+      : 'Install complete. Next time you open the selected CLI(s), Empirical MCP should be available.';
+  log(uiSuccess(completionMessage));
+}
+
+module.exports = {
+  runInstallFlow
+};

package/lib/installers/claude.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const { log, warn } = require('../ui');
+const { commandExists, runResolvedCommand, summarizeProcessOutput } = require('../fsUtils');
+const { readStoredOAuthClient } = require('../oauthClient');
+const {
+  EMPIRICAL_MCP_NAME, EMPIRICAL_MCP_LEGACY_NAMES, EMPIRICAL_MCP_URL
+} = require('../constants');
+const { INSTALL_PROMPT_OPTIONS_DEFAULTS } = require('./promptBlocks');
+const { installClaudeHooks } = require('./hooks');
+const { installNativePlugin } = require('./nativePlugin');
+
+function runClaude(args, options = {}) {
+  return runResolvedCommand('claude', args, options);
+}
+
+function isClaudeServerConfigured(name) {
+  const result = runClaude(['mcp', 'get', name], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+function installClaude(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DEFAULTS, installOptions = {}) {
+  log('  - Claude global guidance file unchanged; native plugin guidance is authoritative.');
+
+  try {
+    installClaudeHooks();
+  } catch (error) {
+    warn(`  - Could not install Claude hooks for deterministic memory lookups: ${error.message}`);
+  }
+
+  installNativePlugin('claude', installOptions.pluginNames);
+  log(`  - Claude native plugins installed: ${(installOptions.pluginNames || ['empirical-memory']).join(', ')}.`);
+
+  if (!commandExists('claude')) {
+    warn('  - Claude CLI not found on PATH. Skipped Claude MCP registration.');
+    return;
+  }
+
+  const storedClient = readStoredOAuthClient();
+
+  // Keep the server definition deterministic across canonical and legacy names.
+  for (const serverName of [EMPIRICAL_MCP_NAME, ...EMPIRICAL_MCP_LEGACY_NAMES]) {
+    runClaude(['mcp', 'remove', serverName], { stdio: 'ignore' });
+    runClaude(['mcp', 'remove', serverName, '-s', 'user'], { stdio: 'ignore' });
+    runClaude(['mcp', 'remove', serverName, '-s', 'local'], { stdio: 'ignore' });
+    runClaude(['mcp', 'remove', serverName, '-s', 'project'], { stdio: 'ignore' });
+  }
+
+  let lastFailureSummary = '';
+  for (let attempt = 1; attempt <= 2; attempt += 1) {
+    if (attempt > 1) {
+      log('  - Retrying Claude MCP registration...');
+    }
+
+    const addArgs = [
+      'mcp',
+      'add',
+      '--scope',
+      'user',
+      '--transport',
+      'http',
+      EMPIRICAL_MCP_NAME,
+      EMPIRICAL_MCP_URL
+    ];
+    if (storedClient?.clientId) {
+      addArgs.push('--client-id', storedClient.clientId);
+    }
+
+    const addResult = runClaude(addArgs, { stdio: attempt === 1 ? 'inherit' : 'pipe' });
+    if (addResult.status === 0) {
+      return;
+    }
+    lastFailureSummary = summarizeProcessOutput(addResult);
+
+    if (isClaudeServerConfigured(EMPIRICAL_MCP_NAME)) {
+      warn('  - Claude returned a non-zero status, but MCP server is present. Continuing.');
+      return;
+    }
+  }
+
+  const detail = lastFailureSummary ? ` Details: ${lastFailureSummary}` : '';
+  throw new Error(`claude mcp add failed after retry.${detail}`);
+}
+
+module.exports = {
+  runClaude,
+  isClaudeServerConfigured,
+  installClaude
+};

package/lib/installers/codex.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const { log, warn } = require('../ui');
+const { commandExists, runResolvedCommand, summarizeProcessOutput } = require('../fsUtils');
+const { persistAccessToken } = require('../oauthClient');
+const {
+  EMPIRICAL_MCP_NAME, EMPIRICAL_MCP_LEGACY_NAMES, EMPIRICAL_MCP_URL
+} = require('../constants');
+const { INSTALL_PROMPT_OPTIONS_DEFAULTS } = require('./promptBlocks');
+const { installNativePlugin } = require('./nativePlugin');
+
+function runCodex(args, options = {}) {
+  return runResolvedCommand('codex', args, options);
+}
+
+function isCodexServerConfigured(name) {
+  const result = runCodex(['mcp', 'get', name], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+function installCodex(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DEFAULTS, installOptions = {}) {
+  log('  - Codex global AGENTS instructions unchanged; native plugin guidance is authoritative.');
+
+  installNativePlugin('codex', installOptions.pluginNames);
+  log(`  - Codex native plugins installed: ${(installOptions.pluginNames || ['empirical-memory']).join(', ')}.`);
+
+  if (!commandExists('codex')) {
+    warn('  - Codex CLI not found on PATH. Skipped Codex MCP registration.');
+    return;
+  }
+
+  for (const serverName of [EMPIRICAL_MCP_NAME, ...EMPIRICAL_MCP_LEGACY_NAMES]) {
+    if (isCodexServerConfigured(serverName)) {
+      runCodex(['mcp', 'remove', serverName], { stdio: 'ignore' });
+    }
+  }
+
+  const addArgs = ['mcp', 'add', EMPIRICAL_MCP_NAME, '--url', EMPIRICAL_MCP_URL];
+  const permanentToken = headlessToken?.apiKey || '';
+  if (permanentToken) {
+    persistAccessToken(permanentToken);
+    addArgs.push('--bearer-token-env-var', 'EMPIRICAL_ACCESS_TOKEN');
+    log('  - Registering Codex MCP server with permanent environment-backed authentication...');
+  } else {
+    log('  - Registering Codex MCP server (OAuth flow may open in browser)...');
+  }
+
+  let lastFailureSummary = '';
+  for (let attempt = 1; attempt <= 2; attempt += 1) {
+    if (attempt > 1) {
+      log('  - Retrying Codex MCP registration...');
+    }
+
+    const addResult = runCodex(
+      addArgs,
+      { stdio: attempt === 1 ? 'inherit' : 'pipe' }
+    );
+    if (addResult.status === 0) {
+      return { needsPostLogin: false };
+    }
+    lastFailureSummary = summarizeProcessOutput(addResult);
+
+    // Codex OAuth flow can return non-zero even when the server is persisted.
+    if (isCodexServerConfigured(EMPIRICAL_MCP_NAME)) {
+      warn('  - Codex returned a non-zero status, but MCP server is present. Continuing.');
+      return { needsPostLogin: true };
+    }
+  }
+
+  const detail = lastFailureSummary ? ` Details: ${lastFailureSummary}` : '';
+  throw new Error(`codex mcp add failed after retry.${detail}`);
+}
+
+module.exports = {
+  runCodex,
+  isCodexServerConfigured,
+  installCodex
+};

package/lib/installers/copilot.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { log, warn } = require('../ui');
+const { ensureDir, readJsonIfExists, readUtf8IfExists, writeFile } = require('../fsUtils');
+const { getEnv } = require('../env');
+const { readStoredOAuthClient, getLocalOAuthClientPath } = require('../oauthClient');
+const {
+  EMPIRICAL_MCP_NAME, EMPIRICAL_MCP_LEGACY_NAMES, EMPIRICAL_MCP_URL, COPILOT_OAUTH_CLIENT_ID
+} = require('../constants');
+const { INSTALL_PROMPT_OPTIONS_DEFAULTS } = require('./promptBlocks');
+const { installNativePlugin } = require('./nativePlugin');
+
+function installCopilot(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DEFAULTS, installOptions = {}) {
+  const home = os.homedir();
+  const copilotDir = path.join(home, '.copilot');
+  const mcpConfigPath = path.join(copilotDir, 'mcp-config.json');
+  const instructionsPath = path.join(copilotDir, 'copilot-instructions.md');
+
+  ensureDir(copilotDir);
+
+  const mcpConfig = readJsonIfExists(mcpConfigPath) || {};
+  if (!mcpConfig.mcpServers || typeof mcpConfig.mcpServers !== 'object') {
+    mcpConfig.mcpServers = {};
+  }
+
+  for (const legacyName of EMPIRICAL_MCP_LEGACY_NAMES) {
+    if (legacyName && legacyName in mcpConfig.mcpServers) {
+      delete mcpConfig.mcpServers[legacyName];
+    }
+  }
+
+  const storedClient = readStoredOAuthClient();
+  const oauthClientId = getEnv(
+    'EMPIRICAL_COPILOT_OAUTH_CLIENT_ID',
+    storedClient?.clientId || COPILOT_OAUTH_CLIENT_ID
+  );
+  const oauthClientSecret = getEnv(
+    'EMPIRICAL_COPILOT_OAUTH_CLIENT_SECRET',
+    storedClient?.clientSecret || ''
+  );
+
+  mcpConfig.mcpServers[EMPIRICAL_MCP_NAME] = {
+    oauthPublicClient: !oauthClientSecret,
+    type: 'http',
+    tools: ['*'],
+    url: EMPIRICAL_MCP_URL,
+    oauthClientId
+  };
+  if (oauthClientSecret) {
+    mcpConfig.mcpServers[EMPIRICAL_MCP_NAME].oauthClientSecret = oauthClientSecret;
+  } else if ('oauthClientSecret' in mcpConfig.mcpServers[EMPIRICAL_MCP_NAME]) {
+    delete mcpConfig.mcpServers[EMPIRICAL_MCP_NAME].oauthClientSecret;
+  }
+
+  if ('httpHeaders' in mcpConfig.mcpServers[EMPIRICAL_MCP_NAME]) {
+    delete mcpConfig.mcpServers[EMPIRICAL_MCP_NAME].httpHeaders;
+  }
+
+  writeFile(mcpConfigPath, `${JSON.stringify(mcpConfig, null, 2)}\n`);
+
+  log('  - Copilot global instructions unchanged; native plugin guidance is authoritative.');
+
+  installNativePlugin('copilot', installOptions.pluginNames);
+  log(`  - Copilot native plugins installed: ${(installOptions.pluginNames || ['empirical-memory']).join(', ')}.`);
+
+  log('  - Copilot MCP config updated.');
+  if (storedClient?.clientId) {
+    log(`  - Copilot OAuth client loaded from ${getLocalOAuthClientPath()}.`);
+  }
+  log('  - Copilot OAuth is typically completed on first MCP use (no standalone `copilot mcp login` command).');
+}
+
+module.exports = {
+  installCopilot
+};

package/lib/installers/detect.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { commandExists } = require('../fsUtils');
+const { installCodex } = require('./codex');
+const { installCopilot } = require('./copilot');
+const { installClaude } = require('./claude');
+
+function detectInstallTargets() {
+  const home = os.homedir();
+  const targets = [];
+
+  const codexDetected = commandExists('codex') || fs.existsSync(path.join(home, '.codex'));
+  if (codexDetected) {
+    targets.push({
+      id: 'codex',
+      label: 'Codex CLI',
+      install: installCodex
+    });
+  }
+
+  const copilotDetected = commandExists('copilot') || fs.existsSync(path.join(home, '.copilot'));
+  if (copilotDetected) {
+    targets.push({
+      id: 'copilot',
+      label: 'GitHub Copilot CLI',
+      install: installCopilot
+    });
+  }
+
+  const claudeDetected = commandExists('claude') || fs.existsSync(path.join(home, '.claude'));
+  if (claudeDetected) {
+    targets.push({
+      id: 'claude',
+      label: 'Claude CLI',
+      install: installClaude
+    });
+  }
+
+  return targets;
+}
+
+module.exports = {
+  detectInstallTargets
+};