PDX-505: detect missing provar plugin with PROVAR_PLUGIN_NOT_FOUND

[mrdailey99]

Summary

• When the @provartesting/provardx-cli sf plugin is not installed (the sf CLI has no provar topic), the automation tools previously failed opaquely with AUTOMATION_*_FAILED carrying Command provar not found. Users had to recognize that text to realize the root cause.
• Adds a dedicated PROVAR_PLUGIN_NOT_FOUND error code with actionable remediation (details.suggestion: sf plugins install @provartesting/provardx-cli), mirroring the SfNotFoundError / SF_NOT_FOUND pattern.
• New in sfSpawn.ts: ProvarPluginNotFoundError, PROVAR_PLUGIN_INSTALL_HINT, an isProvarPluginMissing(stdout, stderr) detector (matches command provar … not found, oclif provar is not a sf command, etc.), and a non-throwing probeProvarTopic(sfPath?) health-check.
• All five provar_automation_* tools (config_load, testrun, compile, metadata_download, setup) run a shared pre-flight: when an sf command exits non-zero and the output matches the missing-plugin pattern, they return PROVAR_PLUGIN_NOT_FOUND instead of the generic _FAILED. A genuine failure (or exit 0) is unaffected.

Jira

https://provartesting.atlassian.net/browse/PDX-505

Test plan

• yarn compile passes
• yarn test:only passes (1339 passing; 14 new tests)
• mcp-smoke.cjs passes (58/58, unaffected)
• yarn lint passes

Tests

• sfSpawn.test.ts: ProvarPluginNotFoundError shape; isProvarPluginMissing positive (3 phrasings) + negatives (unrelated error, benign update warning); probeProvarTopic true/false/sf-missing.
• automationTools.test.ts: config_load surfaces PROVAR_PLUGIN_NOT_FOUND with remediation (positive); command provar not found phrasing; negative — a generic config-load failure stays AUTOMATION_CONFIG_LOAD_FAILED; testrun also maps; no-fire on exit 0.

Changes

• src/mcp/tools/sfSpawn.ts: error class, install hint, detector, probe.
• src/mcp/tools/automationTools.ts: shared provarPluginErrorResponse pre-flight wired into all 5 automation failure paths.
• docs/mcp.md: PROVAR_PLUGIN_NOT_FOUND added to the 5 automation tools' error-code lists + a definition note.
• Tests as above.

[github-actions]

Quality Orchestrator

🟢 LOW · 4 / 100 · All changed files have mapped tests.

---

🧪 Tests to Run · Running 2 of 54 tests

• unit/mcp/automationTools.test.ts
• unit/mcp/sfSpawn.test.ts

▶ Run command

npx vitest run \
  unit/mcp/automationTools.test.ts \
  unit/mcp/sfSpawn.test.ts

---

_{⚡ quality-orchestrator  ·  /qo stub <file>  ·  qo analyze-local}

[Copilot]

Pull request overview

This pull request improves failure diagnostics for the provar_automation_* MCP tools by detecting when the Salesforce CLI is installed but the @provartesting/provardx-cli sf plugin (the provar topic) is missing, and returning a dedicated PROVAR_PLUGIN_NOT_FOUND error with clear remediation instead of opaque AUTOMATION_*_FAILED errors.

Changes:

• Added PROVAR_PLUGIN_NOT_FOUND support in sfSpawn.ts via a missing-plugin detector (isProvarPluginMissing), an install hint constant, an error class, and a non-throwing probeProvarTopic helper.
• Wired a shared pre-flight in automationTools.ts so all 5 automation tools map missing-plugin failures to PROVAR_PLUGIN_NOT_FOUND with details.suggestion.
• Updated docs and added unit tests covering positive/negative detection and tool-level error-code mapping.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/mcp/tools/sfSpawn.ts	Introduces detection + helpers for identifying a missing provar topic and providing an install hint.
src/mcp/tools/automationTools.ts	Adds a shared error-mapping helper so automation tools return PROVAR_PLUGIN_NOT_FOUND when appropriate.
docs/mcp.md	Documents the new error code for relevant tools and explains remediation.
test/unit/mcp/sfSpawn.test.ts	Adds unit coverage for the new error, detector, and probing helper.
test/unit/mcp/automationTools.test.ts	Adds end-to-end-ish unit coverage proving automation tools surface PROVAR_PLUGIN_NOT_FOUND only when intended.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.