@kbediako/codex-orchestrator 0.1.0 → 0.1.1

package/README.md

@@ -196,10 +196,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 availability).
+
 ## 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

@@ -28,6 +28,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;
@@ -155,6 +158,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];
@@ -467,6 +525,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.

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

@@ -1,3 +1,6 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import process from 'node:process';
 import { resolveOptionalDependency } from './utils/optionalDeps.js';
 const OPTIONAL_DEPENDENCIES = [
@@ -9,6 +12,7 @@ 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);
@@ -22,11 +26,36 @@ 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 devtools = {
+        status: skillInstalled ? 'ok' : 'missing',
+        skill: {
+            name: DEVTOOLS_SKILL_NAME,
+            status: skillInstalled ? 'ok' : 'missing',
+            path: skillPath,
+            install: skillInstalled
+                ? undefined
+                : [
+                    `Copy the ${DEVTOOLS_SKILL_NAME} skill into ${join(codexHome, 'skills', DEVTOOLS_SKILL_NAME)}`,
+                    `Expected file: ${skillPath}`
+                ]
+        },
+        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 (!skillInstalled) {
+        missing.push(DEVTOOLS_SKILL_NAME);
+    }
     return {
         status: missing.length === 0 ? 'ok' : 'warning',
         missing,
-        dependencies
+        dependencies,
+        devtools
     };
 }
 export function formatDoctorSummary(result) {
@@ -44,5 +73,25 @@ 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}`);
+        }
+    }
+    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/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,18 @@
+import { EnvUtils } from '../../../../packages/shared/config/env.js';
+export const DEVTOOLS_CONFIG_OVERRIDE = 'mcp_servers.chrome-devtools.enabled=true';
+export function isDevtoolsEnabled(env = process.env) {
+    const raw = env.CODEX_REVIEW_DEVTOOLS;
+    if (!raw) {
+        return false;
+    }
+    return EnvUtils.isTrue(raw.trim().toLowerCase());
+}
+export function resolveCodexCommand(args, env = process.env) {
+    if (!isDevtoolsEnabled(env)) {
+        return { command: 'codex', args };
+    }
+    return {
+        command: 'codex',
+        args: ['-c', DEVTOOLS_CONFIG_OVERRIDE, ...args]
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbediako/codex-orchestrator",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {