@kbediako/codex-orchestrator 0.1.1 → 0.1.2

package/README.md

@@ -80,6 +80,7 @@ Use `npx codex-orchestrator resume --run <run-id>` to continue interrupted runs;
 - `codex-orchestrator mcp serve [--repo <path>] [--dry-run] [-- <extra args>]`: launch the MCP stdio server (delegates to `codex mcp-server`; stdout guard keeps protocol-only output, logs to stderr).
 - `codex-orchestrator init codex [--cwd <path>] [--force]`: copy starter templates into a repo (no overwrite unless `--force`).
 - `codex-orchestrator doctor [--format json]`: check optional tooling dependencies and print install commands.
+- `codex-orchestrator devtools setup [--yes]`: print DevTools MCP setup instructions (`--yes` applies `codex mcp add ...`).
 - `codex-orchestrator self-check --format json`: emit a safe JSON health payload for smoke tests.
 - `codex-orchestrator --version`: print the package version.
 
@@ -216,7 +217,7 @@ Optional prompt overrides:
 
 `--no-interactive` disables the HUD only; set `CODEX_NON_INTERACTIVE=1` when you need to suppress Codex prompts (e.g., shortcut runs or custom automation).
 
-Check readiness with `codex-orchestrator doctor --format json` (reports DevTools skill availability).
+Check readiness with `codex-orchestrator doctor --format json` (reports DevTools skill + MCP config availability). Use `codex-orchestrator devtools setup` to print setup steps.
 
 ## Mirror Workflows
 - `npm run mirror:fetch -- --project <name> [--dry-run] [--force]`: reads `packages/<project>/mirror.config.json` (origin, routes, asset roots, rewrite/block/allow lists), caches downloads **per project** under `.runs/<task>/mirror/<project>/cache`, strips tracker patterns, rewrites externals to `/external/<host>/...`, localizes OG/twitter preview images, rewrites share links off tracker-heavy hosts, and stages into `.runs/<task>/mirror/<project>/<timestamp>/staging/public` before promoting to `packages/<project>/public`. Non-origin assets fall back to Web Archive when the primary host is down; promotion is skipped if errors are detected unless `--force` is set. Manifests live at `.runs/<task>/mirror/<project>/<timestamp>/manifest.json` (warns when `MCP_RUNNER_TASK_ID` is unset; honors `compliance/permit.json` when present).

package/dist/bin/codex-orchestrator.js

@@ -9,6 +9,7 @@ import { evaluateInteractiveGate } from '../orchestrator/src/cli/utils/interacti
 import { buildSelfCheckResult } from '../orchestrator/src/cli/selfCheck.js';
 import { initCodexTemplates, formatInitSummary } from '../orchestrator/src/cli/init.js';
 import { runDoctor, formatDoctorSummary } from '../orchestrator/src/cli/doctor.js';
+import { formatDevtoolsSetupSummary, runDevtoolsSetup } from '../orchestrator/src/cli/devtoolsSetup.js';
 import { loadPackageInfo } from '../orchestrator/src/cli/utils/packageInfo.js';
 import { serveMcp } from '../orchestrator/src/cli/mcp.js';
 async function main() {
@@ -52,6 +53,9 @@ async function main() {
             case 'doctor':
                 await handleDoctor(args);
                 break;
+            case 'devtools':
+                await handleDevtools(args);
+                break;
             case 'mcp':
                 await handleMcp(args);
                 break;
@@ -388,6 +392,30 @@ async function handleDoctor(rawArgs) {
         console.log(line);
     }
 }
+async function handleDevtools(rawArgs) {
+    const { positionals, flags } = parseArgs(rawArgs);
+    const subcommand = positionals.shift();
+    if (!subcommand) {
+        throw new Error('devtools requires a subcommand (setup).');
+    }
+    if (subcommand !== 'setup') {
+        throw new Error(`Unknown devtools subcommand: ${subcommand}`);
+    }
+    const format = flags['format'] === 'json' ? 'json' : 'text';
+    const apply = Boolean(flags['yes']);
+    if (format === 'json' && apply) {
+        throw new Error('devtools setup does not support --format json with --yes.');
+    }
+    const result = await runDevtoolsSetup({ apply });
+    if (format === 'json') {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    const summary = formatDevtoolsSetupSummary(result);
+    for (const line of summary) {
+        console.log(line);
+    }
+}
 async function handleMcp(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     const subcommand = positionals.shift();
@@ -562,6 +590,9 @@ Commands:
   self-check [--format json]
   init codex [--cwd <path>] [--force]
   doctor [--format json]
+  devtools setup          Print DevTools MCP setup instructions.
+    --yes                 Apply setup by running "codex mcp add ...".
+    --format json         Emit machine-readable output (dry-run only).
   mcp serve [--repo <path>] [--dry-run] [-- <extra args>]
   version | --version
 

package/dist/orchestrator/src/cli/devtoolsSetup.js

@@ -0,0 +1,66 @@
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+import { buildDevtoolsSetupPlan, resolveDevtoolsReadiness } from './utils/devtools.js';
+export async function runDevtoolsSetup(options = {}) {
+    const env = options.env ?? process.env;
+    const plan = buildDevtoolsSetupPlan(env);
+    const readiness = resolveDevtoolsReadiness(env);
+    if (!options.apply) {
+        return { status: 'planned', plan, readiness };
+    }
+    if (readiness.config.status === 'ok') {
+        return {
+            status: 'skipped',
+            reason: 'DevTools MCP is already configured.',
+            plan,
+            readiness
+        };
+    }
+    if (readiness.config.status === 'invalid') {
+        throw new Error(`Cannot apply DevTools setup because config.toml is invalid: ${readiness.config.path}`);
+    }
+    await applyDevtoolsSetup(plan, env);
+    return { status: 'applied', plan, readiness };
+}
+export function formatDevtoolsSetupSummary(result) {
+    const lines = [];
+    lines.push(`DevTools setup: ${result.status}`);
+    if (result.reason) {
+        lines.push(`Note: ${result.reason}`);
+    }
+    lines.push(`- Codex home: ${result.plan.codexHome}`);
+    lines.push(`- Skill: ${result.readiness.skill.status} (${result.readiness.skill.path})`);
+    const configLabel = result.readiness.config.status === 'invalid'
+        ? `invalid (${result.readiness.config.path})`
+        : `${result.readiness.config.status} (${result.readiness.config.path})`;
+    lines.push(`- Config: ${configLabel}`);
+    if (result.readiness.config.detail) {
+        lines.push(`  detail: ${result.readiness.config.detail}`);
+    }
+    if (result.readiness.config.error) {
+        lines.push(`  error: ${result.readiness.config.error}`);
+    }
+    lines.push(`- Command: ${result.plan.commandLine}`);
+    lines.push('- Config snippet:');
+    for (const line of result.plan.configSnippet.split('\n')) {
+        lines.push(`  ${line}`);
+    }
+    if (result.status === 'planned') {
+        lines.push('Run with --yes to apply this setup.');
+    }
+    return lines;
+}
+async function applyDevtoolsSetup(plan, env) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(plan.command, plan.args, { stdio: 'inherit', env });
+        child.once('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
+        child.once('exit', (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`codex mcp add exited with code ${code ?? 'unknown'}`));
+            }
+        });
+    });
+}

package/dist/orchestrator/src/cli/doctor.js

@@ -1,7 +1,5 @@
-import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
 import process from 'node:process';
+import { buildDevtoolsSetupPlan, DEVTOOLS_SKILL_NAME, resolveDevtoolsReadiness } from './utils/devtools.js';
 import { resolveOptionalDependency } from './utils/optionalDeps.js';
 const OPTIONAL_DEPENDENCIES = [
     {
@@ -12,7 +10,6 @@ const OPTIONAL_DEPENDENCIES = [
     { name: 'pixelmatch', install: 'npm install --save-dev pixelmatch' },
     { name: 'cheerio', install: 'npm install --save-dev cheerio' }
 ];
-const DEVTOOLS_SKILL_NAME = 'chrome-devtools';
 export function runDoctor(cwd = process.cwd()) {
     const dependencies = OPTIONAL_DEPENDENCIES.map((entry) => {
         const resolved = resolveOptionalDependency(entry.name, cwd);
@@ -26,20 +23,34 @@ export function runDoctor(cwd = process.cwd()) {
             install: entry.install
         };
     });
-    const codexHome = resolveCodexHome();
-    const skillPath = join(codexHome, 'skills', DEVTOOLS_SKILL_NAME, 'SKILL.md');
-    const skillInstalled = existsSync(skillPath);
+    const readiness = resolveDevtoolsReadiness();
+    const setupPlan = buildDevtoolsSetupPlan();
     const devtools = {
-        status: skillInstalled ? 'ok' : 'missing',
+        status: readiness.status,
         skill: {
             name: DEVTOOLS_SKILL_NAME,
-            status: skillInstalled ? 'ok' : 'missing',
-            path: skillPath,
-            install: skillInstalled
+            status: readiness.skill.status,
+            path: readiness.skill.path,
+            install: readiness.skill.status === 'ok'
                 ? undefined
                 : [
-                    `Copy the ${DEVTOOLS_SKILL_NAME} skill into ${join(codexHome, 'skills', DEVTOOLS_SKILL_NAME)}`,
-                    `Expected file: ${skillPath}`
+                    `Copy the ${DEVTOOLS_SKILL_NAME} skill into ${setupPlan.codexHome}/skills/${DEVTOOLS_SKILL_NAME}`,
+                    `Expected file: ${readiness.skill.path}`
+                ]
+        },
+        config: {
+            status: readiness.config.status,
+            path: readiness.config.path,
+            detail: readiness.config.detail,
+            error: readiness.config.error,
+            install: readiness.config.status === 'ok'
+                ? undefined
+                : [
+                    'Run: codex-orchestrator devtools setup',
+                    `Run: ${setupPlan.commandLine}`,
+                    `Config path: ${setupPlan.configPath}`,
+                    'Config snippet:',
+                    ...setupPlan.configSnippet.split('\n')
                 ]
         },
         enablement: [
@@ -48,9 +59,12 @@ export function runDoctor(cwd = process.cwd()) {
         ]
     };
     const missing = dependencies.filter((dep) => dep.status === 'missing').map((dep) => dep.name);
-    if (!skillInstalled) {
+    if (readiness.skill.status === 'missing') {
         missing.push(DEVTOOLS_SKILL_NAME);
     }
+    if (readiness.config.status !== 'ok') {
+        missing.push(`${DEVTOOLS_SKILL_NAME}-config`);
+    }
     return {
         status: missing.length === 0 ? 'ok' : 'warning',
         missing,
@@ -83,15 +97,26 @@ export function formatDoctorSummary(result) {
             lines.push(`    install: ${instruction}`);
         }
     }
+    if (result.devtools.config.status === 'ok') {
+        lines.push(`  - config.toml: ok (${result.devtools.config.path})`);
+    }
+    else {
+        const label = result.devtools.config.status === 'invalid'
+            ? `invalid (${result.devtools.config.path})`
+            : `missing (${result.devtools.config.path})`;
+        lines.push(`  - config.toml: ${label}`);
+        if (result.devtools.config.detail) {
+            lines.push(`    detail: ${result.devtools.config.detail}`);
+        }
+        if (result.devtools.config.error) {
+            lines.push(`    error: ${result.devtools.config.error}`);
+        }
+        for (const instruction of result.devtools.config.install ?? []) {
+            lines.push(`    install: ${instruction}`);
+        }
+    }
     for (const line of result.devtools.enablement) {
         lines.push(`  - ${line}`);
     }
     return lines;
 }
-function resolveCodexHome() {
-    const override = process.env.CODEX_HOME?.trim();
-    if (override) {
-        return override;
-    }
-    return join(homedir(), '.codex');
-}

package/dist/orchestrator/src/cli/utils/devtools.js

@@ -1,5 +1,29 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import process from 'node:process';
 import { EnvUtils } from '../../../../packages/shared/config/env.js';
+export const DEVTOOLS_SKILL_NAME = 'chrome-devtools';
 export const DEVTOOLS_CONFIG_OVERRIDE = 'mcp_servers.chrome-devtools.enabled=true';
+const DEVTOOLS_CONFIG_FILENAME = 'config.toml';
+const DEVTOOLS_MCP_COMMAND = [
+    'mcp',
+    'add',
+    DEVTOOLS_SKILL_NAME,
+    '--',
+    'npx',
+    '-y',
+    'chrome-devtools-mcp@latest',
+    '--categoryEmulation',
+    '--categoryPerformance',
+    '--categoryNetwork'
+];
+const DEVTOOLS_CONFIG_SNIPPET = [
+    '[mcp_servers.chrome-devtools]',
+    'command = "npx"',
+    'args = ["-y", "chrome-devtools-mcp@latest", "--categoryEmulation", "--categoryPerformance", "--categoryNetwork"]',
+    'enabled = false'
+].join('\n');
 export function isDevtoolsEnabled(env = process.env) {
     const raw = env.CODEX_REVIEW_DEVTOOLS;
     if (!raw) {
@@ -7,12 +31,166 @@ export function isDevtoolsEnabled(env = process.env) {
     }
     return EnvUtils.isTrue(raw.trim().toLowerCase());
 }
+export function resolveCodexHome(env = process.env) {
+    const override = env.CODEX_HOME?.trim();
+    if (override) {
+        return override;
+    }
+    return join(homedir(), '.codex');
+}
+export function resolveCodexConfigPath(env = process.env) {
+    return join(resolveCodexHome(env), DEVTOOLS_CONFIG_FILENAME);
+}
+export function resolveDevtoolsReadiness(env = process.env) {
+    const codexHome = resolveCodexHome(env);
+    const skillPath = join(codexHome, 'skills', DEVTOOLS_SKILL_NAME, 'SKILL.md');
+    const skillInstalled = existsSync(skillPath);
+    const config = inspectDevtoolsConfig(env);
+    const configReady = config.status === 'ok';
+    let status;
+    if (config.status === 'invalid') {
+        status = 'invalid-config';
+    }
+    else if (!skillInstalled && !configReady) {
+        status = 'missing-both';
+    }
+    else if (!skillInstalled) {
+        status = 'missing-skill';
+    }
+    else if (!configReady) {
+        status = 'missing-config';
+    }
+    else {
+        status = 'ok';
+    }
+    return {
+        status,
+        skill: {
+            status: skillInstalled ? 'ok' : 'missing',
+            path: skillPath
+        },
+        config
+    };
+}
+export function buildDevtoolsSetupPlan(env = process.env) {
+    const codexHome = resolveCodexHome(env);
+    const configPath = resolveCodexConfigPath(env);
+    const args = [...DEVTOOLS_MCP_COMMAND];
+    return {
+        codexHome,
+        configPath,
+        command: 'codex',
+        args,
+        commandLine: ['codex', ...args].join(' '),
+        configSnippet: DEVTOOLS_CONFIG_SNIPPET
+    };
+}
 export function resolveCodexCommand(args, env = process.env) {
     if (!isDevtoolsEnabled(env)) {
         return { command: 'codex', args };
     }
+    const readiness = resolveDevtoolsReadiness(env);
+    if (readiness.status !== 'ok') {
+        throw new Error(formatDevtoolsPreflightError(readiness));
+    }
     return {
         command: 'codex',
         args: ['-c', DEVTOOLS_CONFIG_OVERRIDE, ...args]
     };
 }
+export function formatDevtoolsPreflightError(readiness) {
+    const lines = ['DevTools MCP is not ready for this run.'];
+    lines.push(`- Skill: ${readiness.skill.status} (${readiness.skill.path})`);
+    const configStatus = readiness.config.status === 'invalid'
+        ? `invalid (${readiness.config.path})`
+        : `${readiness.config.status} (${readiness.config.path})`;
+    lines.push(`- Config: ${configStatus}`);
+    if (readiness.config.detail) {
+        lines.push(`  detail: ${readiness.config.detail}`);
+    }
+    if (readiness.config.error) {
+        lines.push(`  error: ${readiness.config.error}`);
+    }
+    lines.push('Run `codex-orchestrator doctor --format json` for details.');
+    lines.push('Run `codex-orchestrator devtools setup` to configure the MCP server.');
+    return lines.join('\n');
+}
+function inspectDevtoolsConfig(env = process.env) {
+    const configPath = resolveCodexConfigPath(env);
+    if (!existsSync(configPath)) {
+        return { status: 'missing', path: configPath, detail: 'config.toml not found' };
+    }
+    let raw;
+    try {
+        raw = readFileSync(configPath, 'utf8');
+    }
+    catch (error) {
+        return {
+            status: 'invalid',
+            path: configPath,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+    const hasEntry = hasDevtoolsConfigEntry(raw);
+    if (hasEntry) {
+        return { status: 'ok', path: configPath };
+    }
+    return {
+        status: 'missing',
+        path: configPath,
+        detail: 'chrome-devtools entry not found'
+    };
+}
+function hasDevtoolsConfigEntry(raw) {
+    const lines = raw.split('\n');
+    let currentTable = null;
+    for (const line of lines) {
+        const trimmed = stripTomlComment(line).trim();
+        if (!trimmed) {
+            continue;
+        }
+        const tableMatch = trimmed.match(/^\[(.+)\]$/);
+        if (tableMatch) {
+            currentTable = tableMatch[1]?.trim() ?? null;
+            if (currentTable === 'mcp_servers.chrome-devtools' ||
+                currentTable === 'mcp_servers."chrome-devtools"' ||
+                currentTable === "mcp_servers.'chrome-devtools'") {
+                return true;
+            }
+            continue;
+        }
+        if (trimmed.startsWith('mcp_servers.')) {
+            if (trimmed.startsWith('mcp_servers."chrome-devtools".')) {
+                return true;
+            }
+            if (trimmed.startsWith("mcp_servers.'chrome-devtools'.")) {
+                return true;
+            }
+            if (trimmed.startsWith('mcp_servers.chrome-devtools.')) {
+                return true;
+            }
+            if (trimmed.startsWith('mcp_servers."chrome-devtools"=')) {
+                return true;
+            }
+            if (trimmed.startsWith("mcp_servers.'chrome-devtools'=")) {
+                return true;
+            }
+            if (trimmed.startsWith('mcp_servers.chrome-devtools=')) {
+                return true;
+            }
+        }
+        if (currentTable === 'mcp_servers') {
+            if (/^"?chrome-devtools"?\s*=/.test(trimmed)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function stripTomlComment(line) {
+    const index = line.indexOf('#');
+    if (index === -1) {
+        return line;
+    }
+    return line.slice(0, index);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbediako/codex-orchestrator",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
@@ -80,10 +80,18 @@
     "pngjs": "^7.0.0"
   },
   "peerDependenciesMeta": {
-    "cheerio": { "optional": true },
-    "pixelmatch": { "optional": true },
-    "playwright": { "optional": true },
-    "pngjs": { "optional": true }
+    "cheerio": {
+      "optional": true
+    },
+    "pixelmatch": {
+      "optional": true
+    },
+    "playwright": {
+      "optional": true
+    },
+    "pngjs": {
+      "optional": true
+    }
   },
   "overrides": {
     "esbuild": "^0.25.11"