@kbediako/codex-orchestrator 0.1.0 → 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.
 
@@ -196,10 +197,28 @@ Use an explicit handoff note for reviewers. `NOTES` is required for review runs;
 
 Template: `Goal: ... | Summary: ... | Risks: ... | Questions (optional): ...`
 
-To enable Chrome DevTools for review runs, set `CODEX_REVIEW_DEVTOOLS=1` (uses `scripts/codex-devtools.sh` when executable; otherwise falls back to `codex -c ...`).
+To enable Chrome DevTools for review runs, set `CODEX_REVIEW_DEVTOOLS=1` (uses a codex config override; no repo scripts required).
 Default to the standard `implementation-gate` for general reviews; use `implementation-gate-devtools` only when the review needs Chrome DevTools capabilities (visual/layout checks, network/perf diagnostics). After fixing review feedback, rerun the same gate and include any follow-up questions in `NOTES`.
 To run the full implementation gate with DevTools-enabled review, use `npx codex-orchestrator start implementation-gate-devtools --format json --no-interactive --task <task-id>`.
 
+## Frontend Testing
+Frontend testing is a first-class pipeline with DevTools off by default. The shipped pipelines already set `CODEX_NON_INTERACTIVE=1`; add it explicitly for custom automation or when you want the `frontend-test` shortcut to suppress Codex prompts:
+- `CODEX_NON_INTERACTIVE=1 npx codex-orchestrator start frontend-testing --format json --no-interactive --task <task-id>`
+- `CODEX_NON_INTERACTIVE=1 npx codex-orchestrator start frontend-testing-devtools --format json --no-interactive --task <task-id>` (DevTools enabled)
+- `CODEX_NON_INTERACTIVE=1 codex-orchestrator frontend-test` (shortcut; add `--devtools` to enable DevTools)
+
+If you run the pipelines from this repo, run `npm run build` first so `dist/` stays current (the pipeline executes the compiled runner).
+
+Note: the frontend-testing pipelines toggle the shared `CODEX_REVIEW_DEVTOOLS` flag under the hood; prefer `--devtools` or the devtools pipeline instead of setting it manually.
+
+Optional prompt overrides:
+- `CODEX_FRONTEND_TEST_PROMPT` (inline prompt)
+- `CODEX_FRONTEND_TEST_PROMPT_PATH` (path to a prompt file)
+
+`--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 + 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).
 - `npm run mirror:serve -- --project <name> [--port <port>] [--csp <self|strict|off>] [--no-range]`: shared local-mirror server with traversal guard, HTML no-cache/asset immutability, optional CSP, optional Range support, and directory-listing blocks.

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() {
@@ -28,6 +29,9 @@ async function main() {
             case 'start':
                 await handleStart(orchestrator, args);
                 break;
+            case 'frontend-test':
+                await handleFrontendTest(orchestrator, args);
+                break;
             case 'plan':
                 await handlePlan(orchestrator, args);
                 break;
@@ -49,6 +53,9 @@ async function main() {
             case 'doctor':
                 await handleDoctor(args);
                 break;
+            case 'devtools':
+                await handleDevtools(args);
+                break;
             case 'mcp':
                 await handleMcp(args);
                 break;
@@ -155,6 +162,61 @@ async function handleStart(orchestrator, rawArgs) {
         runEvents.dispose();
     }
 }
+async function handleFrontendTest(orchestrator, rawArgs) {
+    const { positionals, flags } = parseArgs(rawArgs);
+    const format = flags['format'] === 'json' ? 'json' : 'text';
+    const devtools = Boolean(flags['devtools']);
+    const interactiveRequested = Boolean(flags['interactive'] || flags['ui']);
+    const interactiveDisabled = Boolean(flags['no-interactive']);
+    const runEvents = new RunEventEmitter();
+    const gate = evaluateInteractiveGate({
+        requested: interactiveRequested,
+        disabled: interactiveDisabled,
+        format,
+        stdoutIsTTY: process.stdout.isTTY === true,
+        stderrIsTTY: process.stderr.isTTY === true,
+        term: process.env.TERM ?? null
+    });
+    const hud = await maybeStartHud(gate, runEvents);
+    if (!gate.enabled && interactiveRequested && !interactiveDisabled && gate.reason) {
+        console.error(`[HUD disabled] ${gate.reason}`);
+    }
+    if (positionals.length > 0) {
+        console.error(`[frontend-test] ignoring extra arguments: ${positionals.join(' ')}`);
+    }
+    try {
+        const pipelineId = devtools ? 'frontend-testing-devtools' : 'frontend-testing';
+        const result = await orchestrator.start({
+            pipelineId,
+            taskId: typeof flags['task'] === 'string' ? flags['task'] : undefined,
+            parentRunId: typeof flags['parent-run'] === 'string' ? flags['parent-run'] : undefined,
+            approvalPolicy: typeof flags['approval-policy'] === 'string' ? flags['approval-policy'] : undefined,
+            targetStageId: resolveTargetStageId(flags),
+            runEvents
+        });
+        hud?.stop();
+        const payload = {
+            run_id: result.manifest.run_id,
+            status: result.manifest.status,
+            artifact_root: result.manifest.artifact_root,
+            manifest: `${result.manifest.artifact_root}/manifest.json`,
+            log_path: result.manifest.log_path
+        };
+        if (format === 'json') {
+            console.log(JSON.stringify(payload, null, 2));
+        }
+        else {
+            console.log(`Run started: ${payload.run_id}`);
+            console.log(`Status: ${payload.status}`);
+            console.log(`Manifest: ${payload.manifest}`);
+            console.log(`Log: ${payload.log_path}`);
+        }
+    }
+    finally {
+        hud?.stop();
+        runEvents.dispose();
+    }
+}
 async function handlePlan(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     const pipelineId = positionals[0];
@@ -330,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();
@@ -467,6 +553,16 @@ Commands:
     --interactive | --ui    Enable read-only HUD when running in a TTY.
     --no-interactive        Force disable HUD (default is off unless requested).
 
+  frontend-test             Run frontend testing pipeline.
+    --devtools             Enable Chrome DevTools MCP for this run.
+    --task <id>             Override task identifier (defaults to MCP_RUNNER_TASK_ID).
+    --parent-run <id>       Link run to parent run id.
+    --approval-policy <p>   Record approval policy metadata.
+    --format json           Emit machine-readable output.
+    --target <stage-id>     Focus plan/build metadata on a specific stage (alias: --target-stage).
+    --interactive | --ui    Enable read-only HUD when running in a TTY.
+    --no-interactive        Force disable HUD (default is off unless requested).
+
   plan [pipeline]           Preview pipeline stages without executing.
     --task <id>             Override task identifier.
     --format json           Emit machine-readable output.
@@ -494,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,4 +1,5 @@
 import process from 'node:process';
+import { buildDevtoolsSetupPlan, DEVTOOLS_SKILL_NAME, resolveDevtoolsReadiness } from './utils/devtools.js';
 import { resolveOptionalDependency } from './utils/optionalDeps.js';
 const OPTIONAL_DEPENDENCIES = [
     {
@@ -22,11 +23,53 @@ export function runDoctor(cwd = process.cwd()) {
             install: entry.install
         };
     });
+    const readiness = resolveDevtoolsReadiness();
+    const setupPlan = buildDevtoolsSetupPlan();
+    const devtools = {
+        status: readiness.status,
+        skill: {
+            name: DEVTOOLS_SKILL_NAME,
+            status: readiness.skill.status,
+            path: readiness.skill.path,
+            install: readiness.skill.status === 'ok'
+                ? undefined
+                : [
+                    `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: [
+            'Enable DevTools for a run with CODEX_REVIEW_DEVTOOLS=1',
+            "Or run Codex with: codex -c 'mcp_servers.chrome-devtools.enabled=true' ..."
+        ]
+    };
     const missing = dependencies.filter((dep) => dep.status === 'missing').map((dep) => dep.name);
+    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,
-        dependencies
+        dependencies,
+        devtools
     };
 }
 export function formatDoctorSummary(result) {
@@ -44,5 +87,36 @@ export function formatDoctorSummary(result) {
             }
         }
     }
+    lines.push(`DevTools: ${result.devtools.status}`);
+    if (result.devtools.skill.status === 'ok') {
+        lines.push(`  - ${result.devtools.skill.name}: ok (${result.devtools.skill.path})`);
+    }
+    else {
+        lines.push(`  - ${result.devtools.skill.name}: missing`);
+        for (const instruction of result.devtools.skill.install ?? []) {
+            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;
 }

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

@@ -0,0 +1,94 @@
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { logger } from '../logger.js';
+import { resolveCodexCommand } from './utils/devtools.js';
+const DEFAULT_PROMPT = [
+    'You are running frontend testing for the current project.',
+    '',
+    'Goals:',
+    '- Validate critical user flows and layout responsiveness.',
+    '- Check the browser console and network panels for errors.',
+    '- If Chrome DevTools MCP is enabled, use it.',
+    '',
+    'Output a concise report with:',
+    '- Summary',
+    '- Steps executed',
+    '- Issues (severity, repro)',
+    '- Follow-up recommendations',
+    '',
+    'Do not modify code unless explicitly asked.'
+].join('\n');
+export async function loadFrontendTestingPrompt(env = process.env) {
+    const promptPath = env.CODEX_FRONTEND_TEST_PROMPT_PATH?.trim();
+    if (promptPath) {
+        const raw = await readFile(resolve(promptPath), 'utf8');
+        const trimmed = raw.trim();
+        if (!trimmed) {
+            throw new Error(`Frontend testing prompt file is empty: ${promptPath}`);
+        }
+        return trimmed;
+    }
+    const inlinePrompt = env.CODEX_FRONTEND_TEST_PROMPT?.trim();
+    if (inlinePrompt) {
+        return inlinePrompt;
+    }
+    return DEFAULT_PROMPT;
+}
+export function resolveFrontendTestingCommand(prompt, env = process.env) {
+    const args = ['exec', prompt];
+    return resolveCodexCommand(args, env);
+}
+function envFlagEnabled(value) {
+    if (!value) {
+        return false;
+    }
+    const normalized = value.trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes';
+}
+function shouldForceNonInteractive(env) {
+    const stdinIsTTY = process.stdin?.isTTY === true;
+    return (!stdinIsTTY ||
+        envFlagEnabled(env.CI) ||
+        envFlagEnabled(env.CODEX_REVIEW_NON_INTERACTIVE) ||
+        envFlagEnabled(env.CODEX_NON_INTERACTIVE) ||
+        envFlagEnabled(env.CODEX_NONINTERACTIVE) ||
+        envFlagEnabled(env.CODEX_NO_INTERACTIVE));
+}
+export async function runFrontendTesting(env = process.env) {
+    const prompt = await loadFrontendTestingPrompt(env);
+    const { command, args } = resolveFrontendTestingCommand(prompt, env);
+    const nonInteractive = shouldForceNonInteractive(env);
+    const childEnv = { ...process.env, ...env };
+    if (nonInteractive) {
+        childEnv.CODEX_NON_INTERACTIVE = childEnv.CODEX_NON_INTERACTIVE ?? '1';
+        childEnv.CODEX_NO_INTERACTIVE = childEnv.CODEX_NO_INTERACTIVE ?? '1';
+        childEnv.CODEX_INTERACTIVE = childEnv.CODEX_INTERACTIVE ?? '0';
+    }
+    const stdio = nonInteractive ? ['ignore', 'inherit', 'inherit'] : 'inherit';
+    const child = spawn(command, args, { stdio, env: childEnv });
+    await new Promise((resolvePromise, reject) => {
+        child.once('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
+        child.once('exit', (code) => {
+            if (code === 0) {
+                resolvePromise();
+            }
+            else {
+                reject(new Error(`codex exec exited with code ${code ?? 'unknown'}`));
+            }
+        });
+    });
+}
+async function main() {
+    await runFrontendTesting();
+}
+const entry = process.argv[1] ? resolve(process.argv[1]) : null;
+const self = resolve(fileURLToPath(import.meta.url));
+if (entry && entry === self) {
+    main().catch((error) => {
+        logger.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    });
+}

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

@@ -0,0 +1,196 @@
+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) {
+        return false;
+    }
+    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.0",
+  "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"