@distributionos/cli 0.1.16 → 0.1.17

package/package.json

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

package/src/cli.js

@@ -1,4 +1,5 @@
-import { CLI_LOCAL_VERSION, DEFAULT_API_BASE } from './constants.js';
+import { spawn } from 'node:child_process';
+import { CLI_LOCAL_VERSION, DEFAULT_API_BASE } from './constants.js';
 import {
   ensureAnalyticsSite,
   reportSetupInstallation,
@@ -11,7 +12,11 @@ import { createSetupPlan, formatPlanText } from './plan.js';
 import { applySetupPlan } from './mutate.js';
 import { submitInitialization } from './initialization.js';
 import { compareValidationResults, inspectInstallArtifacts, runValidationPlan } from './validation.js';
-import { buildSetupReport } from './setup-report.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;
@@ -130,15 +135,18 @@ export async function runCli(argv, runtime) {
     return 1;
   }
 
-  if (!args.appId) {
-    stderr.write('Missing required --app <appId>.\n\n');
-    stderr.write(helpText());
-    return 1;
-  }
-
-  if (!args.noFetch) {
-    const authReady = await ensureCliAuth({ args, runtime, stderr });
-    if (!authReady) return 1;
+  if (!args.appId) {
+    stderr.write('Missing required --app <appId>.\n\n');
+    stderr.write(helpText());
+    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;
   }
 
   let plan = await createSetupPlan({
@@ -241,7 +249,8 @@ export async function runCli(argv, runtime) {
         changes,
         validation,
         inspection,
-        requiresAgentRestart: changes.some((change) => (change.type === 'mcp' || change.type === 'codex-mcp') && change.changed),
+        requiresAgentRestart: Boolean(agentSetup.requiresAgentRestart) ||
+          changes.some((change) => (change.type === 'mcp' || change.type === 'codex-mcp') && change.changed),
       },
     });
     const token = await resolveAuthToken({
@@ -345,10 +354,12 @@ export function parseArgs(rawArgs) {
     skipAnalytics: false,
     skipValidate: false,
     noOpen: false,
-    noLogin: false,
-    skipSetupReport: false,
-    yes: false,
-    url: null,
+    noLogin: false,
+    skipSetupReport: false,
+    skipAgentSetup: false,
+    yes: false,
+    agent: null,
+    url: null,
     contentId: null,
     contractVersion: null,
     artifactId: null,
@@ -380,10 +391,13 @@ export function parseArgs(rawArgs) {
     else if (arg === '--allow-dirty') parsed.allowDirty = true;
     else if (arg === '--skip-analytics') parsed.skipAnalytics = true;
     else if (arg === '--skip-validate') parsed.skipValidate = true;
-    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 === '--yes' || arg === '-y') parsed.yes = true;
+    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;
@@ -412,27 +426,178 @@ export function parseArgs(rawArgs) {
   return parsed;
 }
 
-function helpText() {
-  return [
-    '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]',
+function helpText() {
+  return [
+    'DistributionOS CLI',
+    '',
+    'Usage:',
+    '  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.',
-    'If the repo has existing uncommitted changes, commit/stash first or use --allow-dirty when you recognize them.',
+    '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 and runs codex mcp login before repo setup.',
+    'If the repo has existing uncommitted changes, commit/stash first or use --allow-dirty when you recognize them.',
     '',
     'Authentication:',
     '  Happy path uses DistributionOS MCP OAuth and stores app-scoped credentials outside the repo.',
     '  DISTRIBUTIONOS_API_KEY, DOS_API_KEY, or DISTRIBUTIONOS_TOKEN are advanced fallbacks.',
     '  Tokens are never printed or written to committed files.',
     '',
-  ].join('\n');
-}
+  ].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 getResult = await runCodexCommand(runtime, ['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}`,
+        'Run `codex mcp remove distributionos`, 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, ['mcp', 'add', DISTRIBUTIONOS_MCP_NAME, '--url', DISTRIBUTIONOS_MCP_URL], { stream: true });
+    if (!addResult.ok) {
+      stderr.write(formatCodexCommandFailure('codex mcp add distributionos', addResult));
+      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, ['mcp', 'login', DISTRIBUTIONOS_MCP_NAME], { stream: true });
+  if (!loginResult.ok) {
+    stderr.write(formatCodexCommandFailure('codex mcp login distributionos', loginResult));
+    return { ok: false, requiresAgentRestart: true };
+  }
+  stdout.write('- Codex MCP OAuth step completed.\n\n');
+  return { ok: true, requiresAgentRestart: true };
+}
+
+function formatCodexCommandFailure(label, result) {
+  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}` : '',
+    'Run the command above manually, approve the browser sign-in, then rerun DistributionOS setup.',
+    '',
+  ].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)
+  );
+}
+
+async function runCodexCommand(runtime, args, options = {}) {
+  return runExternalCommand(runtime, 'codex', 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') {
+    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({
@@ -584,12 +749,12 @@ function formatApplyResult(plan, changes, initialization, validation, inspection
   lines.push('', 'Next step');
   if (reviewUrl) {
     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.',
-      '- 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.',
+      '- 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.',
+      '- 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.',
       '- 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) {