Harden launch/doctor MCP readiness gates with async execution, typed outcomes, and portable docs

[Copilot]

This PR addresses review feedback on the launch/doctor readiness flow by verifying each finding against current code and applying only required fixes. The updates focus on making MCP gate behavior deterministic, non-blocking, and failure-tolerant, while aligning docs/tests with actual CLI behavior.

• CLI gate typing and flow hardening

  • launch.ts now uses a dedicated LaunchNextAction enum instead of string literals for nextAction.
  • doctor.ts introduces an exported MCPProfile enum and derives default MCP profiles from it.
  • doctor.ts now catches per-profile failures (e.g., unknown profile) and emits a failed mcp.<profile> check instead of crashing.

• Non-blocking command/file operations

  • Replaced sync command execution in launch.ts/doctor.ts with async spawn wrappers (Promise<{status, stdout, stderr}>).
  • Updated call sites to await command execution (node ... --help, codex login status, codex mcp ...).
  • Replaced sync existence checks in launch with async fs/promises.access.
  • Converted env bootstrap file loading to async (loadEnvFile, bootstrapCliEnv) and updated CLI startup to await env loading.

• Typed error behavior for MCP/docker paths

  • parseCodexMcpNames now throws BridgeError(ErrorCode.MCP_ERROR, ...) for unsupported JSON shapes.
  • service-manager.ts now returns CodexSynapticError from compose start wrapping, with structured context (diagnosis/remediation/exit status/compose command/output/service/profile).
  • dockerLogin was refactored to async spawn('docker', ['login', registry]) (no shell interpolation), and CLI caller now awaits it.

• Docs portability and JSON correctness

  • docs/guides/quick-start.md launch JSON snippet was corrected to valid JSON.
  • docs/uat/UAT_READINESS_TRACKER.md absolute local paths were replaced with repo-relative paths for portability.

• Targeted test alignment

  • Updated CLI tests to async dependency mocks where spawn/file/env helpers became async.
  • Stabilized remediation assertions by mocking registriesForProfiles in MCP failure-path tests.
  • Fixed env-bootstrap temp-dir cleanup robustness via onTestFinished(...).
  • Made launch test DoctorReport fixture internally consistent (summary aligned with checks).

export enum LaunchNextAction {
  Continue = 'continue',
  Stop = 'stop'
}

export interface LaunchReport {
  ok: boolean;
  steps: LaunchStep[];
  doctor: DoctorReport;
  nextAction: LaunchNextAction;
}

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

---

Continue Tasks: ✅ 1 no changes — View all

[notion-workspace]

🧬 [PAP-17] codex-synaptic

[github-actions]

Codex PR Review

Findings

• P1 – .env flags no longer respected before CLI setup (src/cli/index.ts:92-103, src/cli/index.ts:5088-5096): Environment bootstrap now runs inside the async IIFE at the bottom of the file, but flags such as CODEX_CLI_SILENT and CODEX_CLI_AUTO_SHUTDOWN are read earlier during module initialization. Because the .env file is only loaded later, those flags stay at their default values and the CLI ignores the repo’s configured behaviour (e.g., banners/log levels meant to be suppressed remain visible). The prior version called bootstrapCliEnv synchronously before inspecting these vars, so this is a regression in launch/doctor gating.

Suggested Fixes

• Env preload: Move the bootstrapCliEnv call (or the logic that depends on its results) ahead of the cliSilent/cliAutoShutdown reads—e.g., run the async bootstrap before computing those constants or restructure to await the env load prior to CLI initialization.

MCP Usage

• deepwiki: attempted but unavailable (missing DEEPWIKI_API_KEY).
• context7: attempted but server returned “method not found”.
• brave: attempted but handshake failed.
• jina: attempted but unavailable (missing JINA_API_KEY).
• firecrawl: attempted but handshake failed.