@distributionos/cli 0.1.16 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@distributionos/cli",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "DistributionOS repo setup CLI for agent onboarding and first-party analytics.",
   "homepage": "https://distributionos.dev",
   "repository": {

package/src/cli.js

@@ -1,4 +1,8 @@
-import { CLI_LOCAL_VERSION, DEFAULT_API_BASE } from './constants.js';
+import { spawn } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { CLI_LOCAL_VERSION, DEFAULT_API_BASE } from './constants.js';
 import {
   ensureAnalyticsSite,
   reportSetupInstallation,
@@ -13,6 +17,10 @@ import { submitInitialization } from './initialization.js';
 import { compareValidationResults, inspectInstallArtifacts, runValidationPlan } from './validation.js';
 import { buildSetupReport } from './setup-report.js';
 
+const DISTRIBUTIONOS_MCP_URL = 'https://distributionos.dev/api/mcp';
+const DISTRIBUTIONOS_MCP_NAME = 'distributionos';
+const AGENT_CHOICES = new Set(['codex', 'claude', 'terminal', 'other']);
+
 export async function runCli(argv, runtime) {
   const stdout = runtime.stdout;
   const stderr = runtime.stderr;
@@ -136,6 +144,9 @@ export async function runCli(argv, runtime) {
     return 1;
   }
 
+  const agentSetup = await ensureRequestedAgentSetup({ args, runtime, stdout, stderr });
+  if (!agentSetup.ok) return 1;
+
   if (!args.noFetch) {
     const authReady = await ensureCliAuth({ args, runtime, stderr });
     if (!authReady) return 1;
@@ -239,11 +250,12 @@ export async function runCli(argv, runtime) {
       phase: 'apply_completed',
       details: {
         changes,
-        validation,
-        inspection,
-        requiresAgentRestart: changes.some((change) => (change.type === 'mcp' || change.type === 'codex-mcp') && change.changed),
-      },
-    });
+        validation,
+        inspection,
+        requiresAgentRestart: Boolean(agentSetup.requiresAgentRestart) ||
+          changes.some((change) => (change.type === 'mcp' || change.type === 'codex-mcp') && change.changed),
+      },
+    });
     const token = await resolveAuthToken({
       env: runtime.env,
       apiBase: args.apiBase ?? DEFAULT_API_BASE,
@@ -347,7 +359,9 @@ export function parseArgs(rawArgs) {
     noOpen: false,
     noLogin: false,
     skipSetupReport: false,
+    skipAgentSetup: false,
     yes: false,
+    agent: null,
     url: null,
     contentId: null,
     contractVersion: null,
@@ -383,7 +397,10 @@ export function parseArgs(rawArgs) {
     else if (arg === '--no-open') parsed.noOpen = true;
     else if (arg === '--no-login') parsed.noLogin = true;
     else if (arg === '--skip-setup-report') parsed.skipSetupReport = true;
+    else if (arg === '--skip-agent-setup') parsed.skipAgentSetup = true;
     else if (arg === '--yes' || arg === '-y') parsed.yes = true;
+    else if (arg === '--agent') parsed.agent = parseAgent(args[++index] ?? null);
+    else if (arg.startsWith('--agent=')) parsed.agent = parseAgent(arg.slice('--agent='.length));
     else if (arg === '--app') parsed.appId = args[++index] ?? null;
     else if (arg.startsWith('--app=')) parsed.appId = arg.slice('--app='.length);
     else if (arg === '--cwd') parsed.cwd = args[++index] ?? null;
@@ -417,13 +434,14 @@ function helpText() {
     'DistributionOS CLI',
     '',
     'Usage:',
-    '  distributionos setup --app <appId> [--api-base <url>] [--cwd <path>] [--json] [--no-fetch]',
-    '  distributionos setup --app <appId> --apply [--domain <domain>] [--allow-dirty] [--skip-setup-report]',
+    '  distributionos setup --app <appId> [--agent codex|claude|terminal|other] [--api-base <url>] [--cwd <path>] [--json] [--no-fetch]',
+    '  distributionos setup --app <appId> --apply [--agent codex|claude|terminal|other] [--domain <domain>] [--allow-dirty] [--skip-agent-setup] [--skip-setup-report]',
     '  distributionos login --app <appId> [--api-base <url>]',
     '  distributionos verify --app <appId> --url <liveUrl> [--content-id <id>]',
     '  distributionos report-implementation --app <appId> --artifact <artifactId> [--url <liveUrl>] [--summary <text>]',
     '',
     'Default mode reviews the setup plan without changing files. Run again with --apply after the plan looks right.',
+    'For Codex, --agent codex registers the DistributionOS MCP server, uses the Codex Desktop CLI when available, and runs MCP login before repo setup.',
     'If the repo has existing uncommitted changes, commit/stash first or use --allow-dirty when you recognize them.',
     '',
     'Authentication:',
@@ -434,6 +452,262 @@ function helpText() {
   ].join('\n');
 }
 
+function parseAgent(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  if (!AGENT_CHOICES.has(normalized)) {
+    throw new Error('Invalid --agent value. Use codex, claude, terminal, or other.');
+  }
+  return normalized;
+}
+
+async function ensureRequestedAgentSetup({ args, runtime, stdout, stderr }) {
+  if (args.skipAgentSetup || args.agent !== 'codex') {
+    return { ok: true, requiresAgentRestart: false };
+  }
+
+  stdout.write('Codex MCP setup\n');
+  const codexCommand = resolveCodexCommand(runtime);
+  stdout.write(`- Using ${codexCommand.label}.\n`);
+  const getResult = await runCodexCommand(runtime, codexCommand, ['mcp', 'get', DISTRIBUTIONOS_MCP_NAME]);
+  if (getResult.ok) {
+    if (!getResult.stdout.includes(DISTRIBUTIONOS_MCP_URL)) {
+      stderr.write([
+        'Codex already has a distributionos MCP server, but it does not point to the expected DistributionOS URL.',
+        `Expected: ${DISTRIBUTIONOS_MCP_URL}`,
+        `Codex CLI used: ${codexCommand.command}`,
+        'Remove the old distributionos MCP server from Codex, then rerun this setup command.',
+        '',
+      ].join('\n'));
+      return { ok: false, requiresAgentRestart: false };
+    }
+    stdout.write('- DistributionOS MCP server is already registered in Codex.\n');
+  } else if (isCommandMissing(getResult.error)) {
+    stderr.write([
+      'Codex CLI was not found, so DistributionOS cannot connect Codex automatically.',
+      'Open this repo in Codex Desktop or install the Codex CLI, then rerun setup.',
+      '',
+    ].join('\n'));
+    return { ok: false, requiresAgentRestart: false };
+  } else {
+    stdout.write('- Adding DistributionOS MCP server to Codex.\n');
+    const addResult = await runCodexCommand(runtime, codexCommand, ['mcp', 'add', DISTRIBUTIONOS_MCP_NAME, '--url', DISTRIBUTIONOS_MCP_URL], { stream: true });
+    if (!addResult.ok) {
+      stderr.write(formatCodexCommandFailure('Codex MCP add', addResult, codexCommand));
+      return { ok: false, requiresAgentRestart: false };
+    }
+  }
+
+  stdout.write('- Starting Codex MCP OAuth. Approve the browser sign-in if Codex asks.\n');
+  const loginResult = await runCodexCommand(runtime, codexCommand, ['mcp', 'login', DISTRIBUTIONOS_MCP_NAME], { stream: true });
+  if (!loginResult.ok) {
+    stderr.write(formatCodexCommandFailure('Codex MCP login', loginResult, codexCommand));
+    return { ok: false, requiresAgentRestart: true };
+  }
+  const listResult = await runCodexCommand(runtime, codexCommand, ['mcp', 'list']);
+  if (!listResult.ok) {
+    stderr.write(formatCodexCommandFailure('Codex MCP verification', listResult, codexCommand));
+    return { ok: false, requiresAgentRestart: true };
+  }
+  if (!codexMcpListShowsDistributionOs(listResult.stdout)) {
+    stderr.write([
+      'Codex MCP login finished, but this Codex runtime does not list DistributionOS yet.',
+      `Codex CLI used: ${codexCommand.command}`,
+      'Fully quit and reopen Codex Desktop, then rerun the Codex setup message from the app repo.',
+      '',
+    ].join('\n'));
+    return { ok: false, requiresAgentRestart: true };
+  }
+  if (codexMcpListShowsDistributionOsNotLoggedIn(listResult.stdout)) {
+    stderr.write([
+      'Codex MCP login finished, but this Codex runtime still reports DistributionOS as Not logged in.',
+      `Codex CLI used: ${codexCommand.command}`,
+      'Rerun the Codex setup message and approve the current browser sign-in while the command is waiting.',
+      '',
+    ].join('\n'));
+    return { ok: false, requiresAgentRestart: true };
+  }
+  stdout.write('- Codex MCP OAuth step completed and verified.\n\n');
+  return { ok: true, requiresAgentRestart: true };
+}
+
+function formatCodexCommandFailure(label, result, codexCommand) {
+  const output = oneLine(result.stderr || result.stdout || result.error?.message || '');
+  return [
+    `${label} did not complete, so Codex cannot use DistributionOS tools yet.`,
+    output ? `Last output: ${output}` : '',
+    codexCommand?.command ? `Codex CLI used: ${codexCommand.command}` : '',
+    'Rerun the Codex setup message, approve the browser sign-in, and wait for the command to say the Codex MCP OAuth step completed and verified.',
+    '',
+  ].filter(Boolean).join('\n');
+}
+
+function isCommandMissing(error) {
+  const message = error?.message ?? '';
+  const stderr = error?.stderr ?? '';
+  return (
+    error?.code === 'ENOENT' ||
+    error?.code === 'EPERM' ||
+    /spawn\s+(ENOENT|EPERM)/i.test(message) ||
+    /not recognized as an internal/i.test(message) ||
+    /not recognized as an internal/i.test(stderr)
+  );
+}
+
+function resolveCodexCommand(runtime) {
+  const env = runtime?.env ?? process.env;
+  const configured = typeof env.CODEX_CLI_PATH === 'string' ? env.CODEX_CLI_PATH.trim() : '';
+  if (configured) {
+    return { command: configured, label: `Codex CLI at ${configured}` };
+  }
+
+  const desktopCommand = findCodexDesktopCommand(runtime);
+  if (desktopCommand) {
+    return { command: desktopCommand, label: `Codex Desktop CLI at ${desktopCommand}` };
+  }
+
+  return { command: 'codex', label: 'Codex CLI from PATH' };
+}
+
+function findCodexDesktopCommand(runtime) {
+  if (Array.isArray(runtime?.codexCommandCandidates)) {
+    return runtime.codexCommandCandidates.find((candidate) => typeof candidate === 'string' && candidate.trim()) ?? null;
+  }
+
+  const env = runtime?.env ?? process.env;
+  const homeDir = typeof env.USERPROFILE === 'string' && env.USERPROFILE
+    ? env.USERPROFILE
+    : os.homedir();
+  const localAppData = typeof env.LOCALAPPDATA === 'string' && env.LOCALAPPDATA
+    ? env.LOCALAPPDATA
+    : path.join(homeDir, 'AppData', 'Local');
+  const codexBinRoot = path.join(localAppData, 'OpenAI', 'Codex', 'bin');
+  const executableName = process.platform === 'win32' ? 'codex.exe' : 'codex';
+  const candidates = [];
+
+  const directCandidate = path.join(codexBinRoot, executableName);
+  if (existsSync(directCandidate)) {
+    candidates.push(directCandidate);
+  }
+
+  try {
+    for (const entry of readdirSync(codexBinRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const candidate = path.join(codexBinRoot, entry.name, executableName);
+      if (existsSync(candidate)) {
+        candidates.push(candidate);
+      }
+    }
+  } catch {
+    return candidates[0] ?? null;
+  }
+
+  candidates.sort((left, right) => fileModifiedAt(right) - fileModifiedAt(left));
+  return candidates[0] ?? null;
+}
+
+function fileModifiedAt(filePath) {
+  try {
+    return statSync(filePath).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+function codexMcpListShowsDistributionOs(output) {
+  return Boolean(findCodexMcpListDistributionOsLine(output));
+}
+
+function codexMcpListShowsDistributionOsNotLoggedIn(output) {
+  const line = findCodexMcpListDistributionOsLine(output);
+  return Boolean(line && /not\s+logged\s+in/i.test(line));
+}
+
+function findCodexMcpListDistributionOsLine(output) {
+  return String(output)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => /\bdistributionos\b/i.test(line)) ?? null;
+}
+
+async function runCodexCommand(runtime, codexCommand, args, options = {}) {
+  return runExternalCommand(runtime, codexCommand.command, args, options);
+}
+
+async function runExternalCommand(runtime, command, args, options = {}) {
+  if (typeof runtime.execFile === 'function') {
+    try {
+      const result = await runtime.execFile(command, args, options);
+      return {
+        ok: true,
+        stdout: result?.stdout ?? '',
+        stderr: result?.stderr ?? '',
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        stdout: error?.stdout ?? '',
+        stderr: error?.stderr ?? '',
+        error,
+      };
+    }
+  }
+
+  const resolved = resolveCommand(command, args, runtime);
+  return new Promise((resolve) => {
+    let stdoutText = '';
+    let stderrText = '';
+    let child;
+    try {
+      child = spawn(resolved.command, resolved.args, {
+        cwd: runtime.cwd,
+        env: runtime.env,
+        windowsHide: true,
+        stdio: ['inherit', 'pipe', 'pipe'],
+      });
+    } catch (error) {
+      resolve({ ok: false, stdout: '', stderr: '', error });
+      return;
+    }
+
+    child.stdout?.on('data', (chunk) => {
+      const text = String(chunk);
+      stdoutText += text;
+      if (options.stream) runtime.stdout?.write(text);
+    });
+    child.stderr?.on('data', (chunk) => {
+      const text = String(chunk);
+      stderrText += text;
+      if (options.stream) runtime.stderr?.write(text);
+    });
+    child.on('error', (error) => {
+      resolve({ ok: false, stdout: stdoutText, stderr: stderrText, error });
+    });
+    child.on('close', (code) => {
+      const ok = code === 0;
+      resolve({
+        ok,
+        stdout: stdoutText,
+        stderr: stderrText,
+        error: ok ? null : Object.assign(new Error(`${command} exited with code ${code}`), { code }),
+      });
+    });
+  });
+}
+
+function resolveCommand(command, args, runtime) {
+  const platform = runtime.platform ?? process.platform;
+  if (platform === 'win32') {
+    if (path.isAbsolute(command) && /\.(exe|com)$/i.test(command)) {
+      return { command, args };
+    }
+    return {
+      command: runtime.env?.ComSpec ?? process.env.ComSpec ?? 'cmd.exe',
+      args: ['/d', '/s', '/c', command, ...args],
+    };
+  }
+  return { command, args };
+}
+
 async function ensureCliAuth({ args, runtime, stderr }) {
   const existingToken = await resolveAuthToken({
     env: runtime.env,
@@ -586,10 +860,11 @@ function formatApplyResult(plan, changes, initialization, validation, inspection
     lines.push(
       '- Open this DistributionOS review page now:',
       `  ${reviewUrl}`,
-      '- Codex users: make sure `codex mcp add distributionos --url https://distributionos.dev/api/mcp` and `codex mcp login distributionos` have run, then fully quit and reopen Codex Desktop before checking the connection.',
+      '- Codex users: if you used the Codex setup option, the CLI already ran MCP add/login against the Codex runtime and verified it did not report DistributionOS as Not logged in.',
+      '- Then fully quit and reopen Codex Desktop before checking the connection.',
       '- Claude Code users: if .mcp.json was created or updated, restart or reconnect Claude Code and approve the project MCP server if asked.',
-      '- Other MCP-aware agents: reconnect the agent from this repo so it can load the DistributionOS MCP server.',
-      '- On the review page, copy the connection check prompt into the fresh/reconnected agent chat.',
+      '- Other MCP-aware agents: reconnect the agent from this repo so it can load the DistributionOS MCP server.',
+      '- On the review page, copy the connection check prompt into the fresh/reconnected agent chat.',
       '- If your agent only sees DistributionOS authentication tools, copy the auth prompt from the review page and complete OAuth before continuing.',
       '- Then copy the verification prompt from the review page and ask your agent to call check_distributionos_connection, get_agent_instructions, and get_analytics_summary.',
       '- DistributionOS will wait for a successful app-scoped MCP call before you continue to Brain Doc review.',

package/src/constants.js

@@ -8,7 +8,7 @@ export const DEFAULT_API_BASE = 'https://distributionos.dev';
 export const MCP_SERVER_URL = 'https://distributionos.dev/api/mcp';
 export const CURRENT_BOOTSTRAP_VERSION = '2026.06.27';
 export const CURRENT_ANALYTICS_CONTRACT_VERSION = '2026.06.20';
-export const CURRENT_SETUP_CONTRACT_VERSION = '2026.07.01';
+export const CURRENT_SETUP_CONTRACT_VERSION = '2026.07.01';
 
 export const TOKEN_ENV_NAMES = [
   'DISTRIBUTIONOS_API_KEY',

package/src/setup-report.js

@@ -35,24 +35,24 @@ export async function buildSetupReport(plan, phase = 'plan', details = {}) {
     reason: plan.bootstrap.reason,
   });
 
-  if (plan.mcp?.action === 'none') {
-    detectedCapabilities.add('agent.mcp.remoteConfig');
-  }
-  if (plan.codexMcp?.action === 'none') {
-    detectedCapabilities.add('agent.mcp.codexConfig');
-  }
-  if (plan.codexMcp?.action === 'manual') {
-    blockedReason = plan.codexMcp.reason;
-  } else if (plan.mcp?.action === 'manual') {
-    blockedReason = plan.mcp.reason;
-  }
-  if (plan.codexMcp) {
-    managedFiles.push({
-      path: plan.codexMcp.path,
-      type: 'agent.mcp.codexConfig',
-      action: plan.codexMcp.action,
-      status: plan.codexMcp.action === 'none' ? 'current' : plan.codexMcp.action === 'manual' ? 'blocked_manual' : 'planned',
-      reason: plan.codexMcp.reason,
+  if (plan.mcp?.action === 'none') {
+    detectedCapabilities.add('agent.mcp.remoteConfig');
+  }
+  if (plan.codexMcp?.action === 'none') {
+    detectedCapabilities.add('agent.mcp.codexConfig');
+  }
+  if (plan.codexMcp?.action === 'manual') {
+    blockedReason = plan.codexMcp.reason;
+  } else if (plan.mcp?.action === 'manual') {
+    blockedReason = plan.mcp.reason;
+  }
+  if (plan.codexMcp) {
+    managedFiles.push({
+      path: plan.codexMcp.path,
+      type: 'agent.mcp.codexConfig',
+      action: plan.codexMcp.action,
+      status: plan.codexMcp.action === 'none' ? 'current' : plan.codexMcp.action === 'manual' ? 'blocked_manual' : 'planned',
+      reason: plan.codexMcp.reason,
     });
   }
   if (plan.mcp) {