Make upstream startup failures actionable

[mohanagy]

Closes #347.

What changed

• capture bounded, secret-redacted stderr and child exit metadata during stdio upstream startup
• attach a structured safe diagnostic to startup failures for machine-readable consumers
• make miftah test-profile print the cause, exit metadata, remediation, and a shell-safe retry command
• include safe startup diagnostics in miftah doctor output
• keep serve-mode warnings concise while pointing users to the exact test-profile command
• recognize uvx --with ... package invocations correctly in doctor pinning checks

Root cause

Miftah previously discarded the useful child-process failure context at the startup boundary. Users received only UPSTREAM_INIT_FAILED, even when the upstream had already explained the failure on stderr or exited with a meaningful status.

User impact

Users can now diagnose missing runtimes, incompatible dependencies, and upstream command failures directly, without exposing raw unbounded stderr or configured secrets in serve-mode warnings.

Validation

• npm test — 1,827 passed, 33 skipped
• npm run lint
• npm run typecheck
• npm run build
• focused CLI, doctor, upstream-manager, MCP warning, package-contract, redaction, truncation, and shell-quoting regressions

Summary by CodeRabbit

• New Features

  • Added clearer upstream startup failure details, including causes, exit codes, signals, timeouts, and truncation notices.
  • Added actionable remediation guidance and profile-specific retry commands in CLI errors and capability warnings.
  • Added support for validating pinned packages launched through uvx, including --from options.

• Bug Fixes

  • Improved cleanup after profile testing and tool-listing operations.
  • Prevented sensitive or excessive upstream output from appearing in diagnostics while preserving useful failure context.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 16db0089-f1f4-4085-ba76-d7d26b3cd094

📥 Commits

Reviewing files that changed from the base of the PR and between b8fd59f and b1be698.

📒 Files selected for processing (15)

• src/cli/doctor-report.ts
• src/cli/doctor.ts
• src/cli/error-output.ts
• src/cli/main.ts
• src/mcp/server/miftah-server.ts
• src/runtime/create-miftah-runtime.ts
• src/upstream/contained-stdio-transport.ts
• src/upstream/startup-diagnostic.ts
• src/upstream/upstream-process-manager.ts
• tests/cli-error-output.test.ts
• tests/doctor-report.test.ts
• tests/doctor.test.ts
• tests/helpers/upstream-manager-contracts.ts
• tests/mcp-wrapper.test.ts
• tests/package-contract.test.ts

---

📝 Walkthrough

Walkthrough

Upstream startup failures now capture sanitized, bounded diagnostics and exit metadata. CLI output, doctor reports, and MCP warnings expose structured causes and remediation. Doctor also recognizes uvx package arguments, while runtime cleanup remains guaranteed for relevant commands.

Changes

Upstream startup diagnostics

Layer / File(s)	Summary
Capture and classify startup failures src/upstream/contained-stdio-transport.ts, src/upstream/startup-diagnostic.ts, src/upstream/upstream-process-manager.ts, tests/helpers/upstream-manager-contracts.ts	Startup stderr is sanitized and bounded. Unexpected exits provide exit metadata. Startup failures expose validated diagnostic kinds, causes, truncation state, and remediation.
Expose diagnostics in CLI and doctor src/cli/doctor-report.ts, src/cli/doctor.ts, src/cli/error-output.ts, src/cli/main.ts, tests/cli-error-output.test.ts, tests/doctor-report.test.ts, tests/doctor.test.ts, tests/package-contract.test.ts	Doctor preserves and formats diagnostics, parses uvx arguments, and reports startup causes. test-profile formats failures and preserves exit codes while runtime cleanup runs in finally.
Add profile remediation to MCP warnings src/mcp/server/miftah-server.ts, src/runtime/create-miftah-runtime.ts, tests/mcp-wrapper.test.ts	MCP capability warnings include a quoted profile diagnostic command when the runtime configuration path and failed profile are available.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• mohanagy/miftah#48: Shares MiftahServer changes related to upstream startup diagnostics.
• mohanagy/miftah#58: Shares CLI error handling and packed CLI contract changes.
• mohanagy/miftah#263: Shares transport and upstream process lifecycle changes.

Poem

A rabbit saw stderr, neatly bound,
With secrets hidden, safe and sound.
“Run this profile test,” it said,
“The cause is clear, not broadly spread!”
Then hopped through uvx flags with glee. 🐇

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/issue-347-actionable-upstream-diagnostics

---

_{Comment @coderabbitai help to get the list of available commands.}