parallel-codex-tui 0.1.3 → 0.1.5

package/dist/doctor.js

@@ -1,11 +1,23 @@
+import { execFile } from "node:child_process";
 import { constants } from "node:fs";
 import { access } from "node:fs/promises";
+import { createConnection } from "node:net";
 import { delimiter, join } from "node:path";
 import { prepareAppRoot } from "./core/app-root.js";
-import { configPath, loadConfig } from "./core/config.js";
-import { pathExists } from "./core/file-store.js";
+import { formatConfigErrorMessage } from "./core/config-errors.js";
+import { configPath, loadConfig, withUiThemeOverride } from "./core/config.js";
+import { ensureDir, pathExists } from "./core/file-store.js";
+import { routerRuntimeDir } from "./core/paths.js";
+import { diagnoseRouterFailure } from "./core/router-audit.js";
+import { routeRequestWithCodex, routerProxyConfigured } from "./core/router.js";
 import { prepareWorkspace } from "./core/workspace.js";
-export async function runDoctor(appRoot, workspaceRoot, env = process.env) {
+import { auditTuiThemeContrast, TUI_THEME_MIN_CONTRAST_RATIO } from "./tui/theme-contrast.js";
+import { formatTuiThemePreview } from "./tui/theme-preview.js";
+import { resolveTuiTheme } from "./tui/theme.js";
+import { diagnoseAgentCapabilities } from "./workers/capabilities.js";
+import { runLiveAgentProbes } from "./workers/live-probe.js";
+import { workerProvider } from "./workers/provider.js";
+export async function runDoctor(appRoot, workspaceRoot, env = process.env, options = {}) {
     const lines = ["parallel-codex-tui doctor"];
     let ok = true;
     await prepareAppRoot(appRoot);
@@ -15,7 +27,7 @@ export async function runDoctor(appRoot, workspaceRoot, env = process.env) {
     }
     else {
         ok = false;
-        lines.push(`Node.js: unsupported (${process.versions.node}; need 26+)`);
+        lines.push(`Node.js: unsupported (${process.versions.node}; need 24.15+)`);
     }
     lines.push(`workspace: ok (${preparedWorkspace})`);
     const localConfigPath = configPath(appRoot);
@@ -29,19 +41,78 @@ export async function runDoctor(appRoot, workspaceRoot, env = process.env) {
     }
     let config;
     try {
-        config = await loadConfig(appRoot);
+        const loadedConfig = await loadConfig(appRoot);
+        config = withUiThemeOverride(loadedConfig, options.theme ?? null);
         lines.push(`config: ok (${localConfigPath})`);
+        lines.push(`theme: ok (${themeSummary(config.ui.theme, loadedConfig.ui.theme, options.theme ?? null)}; ${themeOverrideSummary(config.ui.colors)})`);
+        const theme = resolveTuiTheme({ theme: config.ui.theme, colors: config.ui.colors });
+        lines.push(`palette: ${themePaletteSummary(theme)}`);
+        lines.push(...formatTuiThemePreview(theme));
+        lines.push(...formatThemeContrastAudit(auditTuiThemeContrast(theme)));
     }
     catch (error) {
         ok = false;
-        lines.push(`config: invalid (${localConfigPath}; ${error.message})`);
+        lines.push(`config: invalid (${localConfigPath})`);
+        lines.push(...formatConfigErrorMessage(error).split("\n").map((line) => `config error: ${line}`));
         return {
             ok,
             text: `${lines.join("\n")}\n`
         };
     }
-    for (const command of configuredCommands(config)) {
+    const includeRouter = config.router.defaultMode === "auto" || options.probeRouter === true;
+    if (includeRouter) {
+        lines.push(`router retry: ${config.router.codex.maxAttempts} attempts; transient only; ${config.router.codex.retryDelayMs}ms backoff (TUI routing; live probe runs once)`);
+        lines.push(`router budget: total ${config.router.codex.timeoutMs}ms; follow-up ${config.router.codex.followUpTimeoutMs}ms; first output ${config.router.codex.firstOutputTimeoutMs}ms; idle ${config.router.codex.idleTimeoutMs}ms`);
+    }
+    const preflight = await runRuntimePreflight(config, preparedWorkspace, env, {
+        includeRouter,
+        ...(options.capabilityRunner ? { capabilityRunner: options.capabilityRunner } : {}),
+        ...(options.capabilityTimeoutMs ? { capabilityTimeoutMs: options.capabilityTimeoutMs } : {})
+    });
+    lines.push(...preflight.lines);
+    ok = ok && preflight.ok;
+    if (options.probeAgents) {
+        if (ok) {
+            const liveAgents = await runLiveAgentProbes(config, preparedWorkspace, configuredWorkerEngines(config), options.liveAgentProbeOptions);
+            lines.push(...liveAgents.lines);
+            ok = ok && liveAgents.ok;
+        }
+        else {
+            lines.push("agent live probe: skipped (preflight failed)");
+        }
+    }
+    else {
+        lines.push("agent live probe: not run (add --probe-agents; may use model quota)");
+    }
+    if (options.probeRouter) {
+        const probe = await runRouterProbe(config, appRoot, options.routeRunner);
+        lines.push(probe.line);
+        ok = ok && probe.ok;
+    }
+    else if (config.router.defaultMode === "auto") {
+        lines.push("router live probe: not run (add --probe-router)");
+    }
+    return {
+        ok,
+        text: `${lines.join("\n")}\n`
+    };
+}
+export async function runRuntimePreflight(config, workspaceRoot, env = process.env, options = {}) {
+    const includeRouter = options.includeRouter ?? config.router.defaultMode === "auto";
+    const lines = [];
+    let ok = true;
+    try {
+        await access(workspaceRoot, constants.R_OK | constants.W_OK | constants.X_OK);
+        lines.push("workspace permissions: ok (read/write/search)");
+    }
+    catch {
+        ok = false;
+        lines.push(`workspace permissions: denied (${workspaceRoot}; need read/write/search)`);
+    }
+    const availableCommands = new Set();
+    for (const command of configuredCommands(config, includeRouter)) {
         if (await commandExists(command, env)) {
+            availableCommands.add(command);
             lines.push(`${command}: ok`);
         }
         else {
@@ -49,7 +120,7 @@ export async function runDoctor(appRoot, workspaceRoot, env = process.env) {
             lines.push(`${command}: missing`);
         }
     }
-    for (const check of configuredWorkerModelEnvChecks(config, env)) {
+    for (const check of configuredEnvironmentChecks(config, env, includeRouter)) {
         if (check.ok) {
             lines.push(`${check.label}: ok`);
         }
@@ -58,39 +129,204 @@ export async function runDoctor(appRoot, workspaceRoot, env = process.env) {
             lines.push(`${check.label}: missing env ${check.envName}`);
         }
     }
-    return {
-        ok,
-        text: `${lines.join("\n")}\n`
+    const capabilityDiagnostics = await diagnoseAgentCapabilities(config, env, {
+        includeRouter,
+        workerEngines: configuredWorkerEngines(config),
+        availableCommands,
+        ...(options.capabilityRunner ? { runner: options.capabilityRunner } : {}),
+        ...(options.capabilityTimeoutMs ? { timeoutMs: options.capabilityTimeoutMs } : {})
+    });
+    lines.push(...capabilityDiagnostics.lines);
+    ok = ok && capabilityDiagnostics.ok;
+    const systemProxy = options.systemProxy !== undefined
+        ? options.systemProxy
+        : await detectMacSystemProxy();
+    const proxyDiagnostics = await diagnoseProxyEnvironment(config, env, systemProxy, options.proxyConnector ?? canConnectProxy, { includeRouter });
+    lines.push(...proxyDiagnostics.lines);
+    ok = ok && proxyDiagnostics.ok;
+    return { ok, lines };
+}
+export async function diagnoseProxyEnvironment(config, env, systemProxy, connect = canConnectProxy, options = {}) {
+    const contexts = [];
+    if (options.includeRouter ?? config.router.defaultMode === "auto") {
+        contexts.push({ label: "router proxy", env: config.router.codex.env, table: "router.codex.env" });
+    }
+    for (const engine of configuredWorkerEngines(config)) {
+        contexts.push({
+            label: `workers.${engine} proxy`,
+            env: workerProvider(config, engine).config.model.env,
+            table: `workers.${engine}.model.env`
+        });
+    }
+    const connectionCache = new Map();
+    const lines = [];
+    let ok = true;
+    for (const context of contexts) {
+        const endpoint = configuredProxyEndpoint(context.env, env);
+        if (!endpoint) {
+            if (systemProxy) {
+                lines.push(`${context.label}: warning (macOS system proxy ${formatProxyEndpoint(systemProxy)} is not inherited; configure [${context.table}])`);
+            }
+            else {
+                lines.push(`${context.label}: direct (no proxy configured)`);
+            }
+            continue;
+        }
+        if (endpoint === "invalid") {
+            ok = false;
+            lines.push(`${context.label}: invalid proxy URL`);
+            continue;
+        }
+        const key = formatProxyEndpoint(endpoint);
+        const reachable = await cachedProxyConnection(connectionCache, key, () => connect(endpoint.host, endpoint.port));
+        if (reachable) {
+            lines.push(`${context.label}: reachable (${key}; local endpoint only)`);
+        }
+        else {
+            ok = false;
+            lines.push(`${context.label}: unreachable (${key})`);
+        }
+    }
+    return { ok, lines };
+}
+async function runRouterProbe(config, appRoot, runner) {
+    const cwd = routerRuntimeDir(appRoot, config.dataDir);
+    await ensureDir(cwd);
+    const probeConfig = {
+        ...config,
+        router: {
+            ...config.router,
+            defaultMode: "auto"
+        }
     };
+    try {
+        const route = await routeRequestWithCodex("hello", probeConfig, runner, cwd);
+        if (route.source === "codex") {
+            const trace = formatRouterProbeTrace(route, false);
+            return {
+                ok: true,
+                line: `router live probe: ok (${route.mode} in ${Math.round(route.duration_ms ?? 0)}ms${trace ? `; ${trace}` : ""})`
+            };
+        }
+        const trace = formatRouterProbeTrace(route, true);
+        const diagnosis = diagnoseRouterFailure({
+            ...route,
+            reason: route.reason,
+            proxy_configured: routerProxyConfigured(config.router.codex.env)
+        });
+        return {
+            ok: false,
+            line: `router live probe: failed (${sanitizeDiagnosticText(route.reason)}${trace ? `; ${trace}` : ""}; diagnosis ${diagnosis.summary}; next ${diagnosis.action})`
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            line: `router live probe: failed (${sanitizeDiagnosticText(message)})`
+        };
+    }
+}
+function formatRouterProbeTrace(route, includeStage) {
+    return [
+        ...(includeStage && route.router_failure_stage ? [`stage ${route.router_failure_stage}`] : []),
+        ...(includeStage && route.router_timeout_kind ? [`timeout ${route.router_timeout_kind}`] : []),
+        ...(typeof route.router_dispatch_ms === "number" ? [`dispatch ${Math.round(route.router_dispatch_ms)}ms`] : []),
+        ...(typeof route.router_spawn_ms === "number" ? [`spawn ${Math.round(route.router_spawn_ms)}ms`] : []),
+        ...formatRouterProbeFirstOutput(route),
+        ...(typeof route.router_process_ms === "number" ? [`process ${Math.round(route.router_process_ms)}ms`] : []),
+        ...(typeof route.router_parse_ms === "number" ? [`parse ${Math.round(route.router_parse_ms)}ms`] : []),
+        ...(typeof route.duration_ms === "number" ? [`total ${Math.round(route.duration_ms)}ms`] : []),
+        ...(typeof route.router_stdout_bytes === "number" ? [`stdout ${formatRouterProbeBytes(route.router_stdout_bytes)}`] : []),
+        ...(typeof route.router_stderr_bytes === "number" ? [`stderr ${formatRouterProbeBytes(route.router_stderr_bytes)}`] : [])
+    ].join("; ");
+}
+function formatRouterProbeFirstOutput(route) {
+    const streams = [
+        ...(typeof route.router_first_stdout_ms === "number"
+            ? [{ at: route.router_first_stdout_ms, text: `first stdout ${Math.round(route.router_first_stdout_ms)}ms` }]
+            : []),
+        ...(typeof route.router_first_stderr_ms === "number"
+            ? [{ at: route.router_first_stderr_ms, text: `first stderr ${Math.round(route.router_first_stderr_ms)}ms` }]
+            : [])
+    ];
+    if (streams.length > 0) {
+        return streams.sort((left, right) => left.at - right.at).map((stream) => stream.text);
+    }
+    if (typeof route.router_first_output_ms === "number") {
+        return [`first output ${Math.round(route.router_first_output_ms)}ms`];
+    }
+    return route.router_failure_stage === "waiting-output" ? ["first output none"] : [];
+}
+function formatRouterProbeBytes(bytes) {
+    if (bytes < 1024) {
+        return `${Math.round(bytes)}B`;
+    }
+    return `${(bytes / 1024).toFixed(bytes < 10 * 1024 ? 1 : 0)}KB`;
+}
+function sanitizeDiagnosticText(value) {
+    return value
+        .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+        .replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, "")
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ")
+        .replace(/\b([a-z][a-z0-9+.-]*:\/\/)([^@\s/]+)@/gi, "$1***@")
+        .replace(/\b(api[-_\s]?key|token|authorization)(\s*[:=]\s*)(\S+)/gi, "$1$2***")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 400) || "unknown error";
 }
 export function isSupportedNodeVersion(version) {
     const [majorRaw = "0", minorRaw = "0"] = version.split(".");
     const major = Number.parseInt(majorRaw, 10);
     const minor = Number.parseInt(minorRaw, 10);
-    return major >= 26;
+    return major > 24 || (major === 24 && minor >= 15);
 }
-function configuredCommands(config) {
-    return Array.from(new Set(configuredEngines(config, { includeRouter: true })
-        .map((engine) => commandForEngine(config, engine))
-        .filter((command) => Boolean(command) && command !== "mock")));
+function configuredCommands(config, includeRouter) {
+    const commands = includeRouter ? [config.router.codex.command] : [];
+    for (const engine of configuredWorkerEngines(config)) {
+        const worker = config.workers[engine];
+        commands.push(worker.command);
+        if (worker.nativeSession.enabled) {
+            commands.push(worker.interactive.command);
+        }
+    }
+    return [...new Set(commands.filter((command) => command && command !== "mock"))];
 }
-function commandForEngine(config, engine) {
-    if (engine === "router-codex") {
-        return config.router.codex.command;
+function themeOverrideSummary(colors) {
+    const entries = Object.entries(colors).sort(([left], [right]) => left.localeCompare(right));
+    if (entries.length === 0) {
+        return "no color overrides";
     }
-    if (engine === "codex") {
-        return config.workers.codex.command;
+    return `colors: ${entries.map(([key, value]) => `${key}=${value}`).join(", ")}`;
+}
+function themePaletteSummary(theme) {
+    return [
+        `chrome=${theme.chrome}`,
+        `surface=${theme.surface}`,
+        `rail=${theme.rail}`,
+        `accent=${theme.accent}`
+    ].join(", ");
+}
+function formatThemeContrastAudit(audit) {
+    if (audit.issues.length === 0) {
+        return [`theme contrast: ok (minimum ${formatContrastRatio(audit.minimumRatio)}:1 across ${audit.measurements.length} rendered pairs)`];
     }
-    if (engine === "claude") {
-        return config.workers.claude.command;
+    return [
+        `theme contrast: warning (${audit.issues.length} of ${audit.measurements.length} rendered pairs below ${TUI_THEME_MIN_CONTRAST_RATIO}:1)`,
+        ...audit.issues.map(({ foreground, background, ratio }) => `theme contrast issue: ${foreground}/${background} ${formatContrastRatio(ratio)}:1`)
+    ];
+}
+function formatContrastRatio(ratio) {
+    return ratio.toFixed(2);
+}
+function themeSummary(effectiveTheme, configTheme, cliTheme) {
+    if (cliTheme && cliTheme !== configTheme) {
+        return `${effectiveTheme} via --theme; config ${configTheme}`;
     }
-    return null;
+    return effectiveTheme;
 }
-function configuredEngines(config, options) {
+function configuredWorkerEngines(config) {
     const engines = new Set();
-    if (config.router.defaultMode === "auto" && options.includeRouter) {
-        engines.add("router-codex");
-    }
     if (config.router.defaultMode === "auto") {
         engines.add(config.pairing.main);
         engines.add(config.pairing.judge);
@@ -105,15 +341,23 @@ function configuredEngines(config, options) {
         engines.add(config.pairing.actor);
         engines.add(config.pairing.critic);
     }
-    return Array.from(engines);
+    return [...engines].filter((engine) => engine !== "mock");
 }
-function configuredWorkerEngines(config) {
-    return configuredEngines(config, { includeRouter: false }).filter((engine) => engine === "codex" || engine === "claude");
-}
-function configuredWorkerModelEnvChecks(config, env) {
+function configuredEnvironmentChecks(config, env, includeRouter) {
     const checks = [];
+    if (includeRouter) {
+        for (const [key, value] of Object.entries(config.router.codex.env)) {
+            for (const envName of referencedEnvNames(value)) {
+                checks.push({
+                    label: `router.codex.env.${key}`,
+                    envName,
+                    ok: Boolean(env[envName])
+                });
+            }
+        }
+    }
     for (const engine of configuredWorkerEngines(config)) {
-        const worker = engine === "codex" ? config.workers.codex : config.workers.claude;
+        const worker = workerProvider(config, engine).config;
         for (const [key, value] of Object.entries(worker.model.env)) {
             for (const envName of referencedEnvNames(value)) {
                 checks.push({
@@ -153,3 +397,98 @@ async function canExecute(path) {
         return false;
     }
 }
+function configuredProxyEndpoint(configured, processEnvironment) {
+    const effective = {
+        ...processEnvironment,
+        ...Object.fromEntries(Object.entries(configured).map(([name, value]) => [name, renderEnvironmentValue(value, processEnvironment)]))
+    };
+    const value = [
+        effective.HTTPS_PROXY,
+        effective.https_proxy,
+        effective.ALL_PROXY,
+        effective.all_proxy,
+        effective.HTTP_PROXY,
+        effective.http_proxy
+    ].find((candidate) => candidate?.trim())?.trim();
+    if (!value) {
+        return null;
+    }
+    try {
+        const url = new URL(value.includes("://") ? value : `http://${value}`);
+        const port = url.port ? Number(url.port) : defaultProxyPort(url.protocol);
+        if (!url.hostname || !Number.isInteger(port) || port <= 0 || port > 65535) {
+            return "invalid";
+        }
+        return { host: url.hostname, port };
+    }
+    catch {
+        return "invalid";
+    }
+}
+function renderEnvironmentValue(value, env) {
+    return value.replace(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => env[name] ?? "");
+}
+function defaultProxyPort(protocol) {
+    if (protocol === "https:") {
+        return 443;
+    }
+    if (protocol.startsWith("socks")) {
+        return 1080;
+    }
+    return 80;
+}
+function formatProxyEndpoint(endpoint) {
+    const host = endpoint.host.includes(":") ? `[${endpoint.host}]` : endpoint.host;
+    return `${host}:${endpoint.port}`;
+}
+async function cachedProxyConnection(cache, key, connect) {
+    const existing = cache.get(key);
+    if (existing) {
+        return existing;
+    }
+    const pending = connect();
+    cache.set(key, pending);
+    return pending;
+}
+async function detectMacSystemProxy() {
+    if (process.platform !== "darwin") {
+        return null;
+    }
+    const output = await execFileText("scutil", ["--proxy"]);
+    if (!output) {
+        return null;
+    }
+    const https = parseScutilProxy(output, "HTTPS");
+    return https ?? parseScutilProxy(output, "HTTP");
+}
+function parseScutilProxy(output, prefix) {
+    const enabled = output.match(new RegExp(`${prefix}Enable\\s*:\\s*(\\d+)`))?.[1] === "1";
+    const host = output.match(new RegExp(`${prefix}Proxy\\s*:\\s*(\\S+)`))?.[1];
+    const port = Number(output.match(new RegExp(`${prefix}Port\\s*:\\s*(\\d+)`))?.[1]);
+    return enabled && host && Number.isInteger(port) && port > 0 ? { host, port } : null;
+}
+function execFileText(command, args) {
+    return new Promise((resolve) => {
+        execFile(command, args, { timeout: 1000 }, (error, stdout) => {
+            resolve(error ? "" : stdout);
+        });
+    });
+}
+function canConnectProxy(host, port) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ host, port });
+        let settled = false;
+        const finish = (reachable) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            socket.destroy();
+            resolve(reachable);
+        };
+        socket.setTimeout(750);
+        socket.once("connect", () => finish(true));
+        socket.once("error", () => finish(false));
+        socket.once("timeout", () => finish(false));
+    });
+}