feat(mcp): let doctor --exit-code gate CI with a non-zero exit on failure

[glorydavid03023]

Summary

gittensory-mcp doctor already computes a status (ok / warnings / needs_attention), but the process always exits 0 — so it cannot gate a CI step or a pre-commit hook. This adds an opt-in --exit-code flag:

# In CI / a git hook: fail the step if the local MCP setup is broken.
gittensory-mcp doctor --exit-code

When a diagnostic check fails (status: "needs_attention"), the process exits 1. The diagnostic report is still printed — only the exit code changes.

Behavior / compatibility

• Default is unchanged. Without --exit-code, doctor still exits 0, so existing scripts that ignore the exit code keep working.
• Warnings stay exit 0. Only hard failures (needs_attention) produce a non-zero code, so transient/advisory warnings don't break pipelines.

Why no linked issue

Additive, opt-in CLI ergonomics with no change to default behavior. No public-behavior, auth/session, schema, deploy, or frontend-architecture change, so per CONTRIBUTING this does not require an issue first. Happy to file one if maintainers prefer.

Implementation

runCli's command result now carries an optional numeric exit code, and the entry point uses it: process.exit(typeof exitCode === "number" ? exitCode : 0). doctor is the only command that returns a number; every other command resolves to undefined and therefore still exits 0.

Changes

• packages/gittensory-mcp/bin/gittensory-mcp.js — thread an optional exit code through the CLI entry point; doctor returns 1 only under --exit-code on needs_attention; help-text usage line.
• test/unit/mcp-cli.test.ts — cover (1) default exit-0 even when a check fails, (2) non-zero exit under --exit-code on failure, (3) exit 0 under --exit-code when checks pass.
• packages/gittensory-mcp/README.md — document the flag and its semantics.

Contract notes

No MCP tool or HTTP/OpenAPI contract changes. Local CLI behavior only; stdout output shape is unchanged.

Validation

Intended gate (CONTRIBUTING required checks):

npm run build:mcp
npm run test:mcp-pack
npm run typecheck
npm run test:coverage
npm run test:ci

Transparency note: my local authoring environment had no Node runtime available, so I could not execute the gate locally before opening this PR. The change was prepared against the existing CLI dispatch/doctor/test patterns and is intended to be validated by CI on this PR (I will also run the full gate locally). If any check needs adjustment I'll follow up promptly.

Security / privacy

No auth, cookie, CORS, GitHub App output, identity, or contributor-evidence changes. Only an exit-code signal is added; no new data is printed or transmitted.

[JSONbored]

@glorydavid03023 the doctor --exit-code behavior is useful, but this branch is mechanically blocked.

A few notes:

• The default-exit compatibility behavior is the right compatibility choice.
• validate is failing in test/unit/mcp-cli.test.ts.
• The branch also conflicts with current MCP CLI tests.

Required changes:

• Fix the TypeScript errors in the new async execFile test.
• Rebase and resolve the test/unit/mcp-cli.test.ts conflict.
• Add the missing Safety section for MCP CLI stdout/stderr/JSON behavior.

Validation expected:

• Rerun npm run typecheck, the focused MCP CLI test file, npm run build:mcp, and npm run test:mcp-pack.

[glorydavid03023]

Rebased onto the latest main (resolved the test-file overlap with the merged version/completion commands) and validated locally on Node v20.18.1 (CI runs Node 22):

• npm run build:mcp → pass (exit 0)
• npm run typecheck → pass (exit 0)
• Focused test/unit/mcp-cli.test.ts → the 3 doctor --exit-code cases pass

While validating, I caught and fixed a real TypeScript error in the exit-code test: the async execFile callback left error/out implicitly any. I rewrote it to use execFileSync + try/catch (capturing .status/.stdout), matching the existing run() helper pattern. npm run typecheck is now clean. (This had not been caught before because the original PR was authored without a local Node runtime.)

The only locally-failing test is the pre-existing rejects unsafe server-provided packet markdown timeout, which is environment-only and passes on CI.

[gittensory]

Important

Gittensory found maintainer review notes

Scoped related-work signals were found for this PR. They are advisory unless the gate reports a blocker.

Readiness score: 68/100

Signal	Result	Evidence	Action
Linked issue	⚠️ Missing	No linked issue or no-issue rationale found.	Explain no-issue PR.
Related work	⚠️ 3 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.	Review top overlaps.
Review load	❌ 8/20	Readiness component derived from cached public PR metadata and labels; size label size:XS.	Add scope summary.
Validation evidence	✅ 25/25	PR body includes validation/test evidence.	No action.
Open PR queue	❌ 3/10	17 open PR(s), 15 likely reviewable.	Expect slower review.
Contributor context	✅ Confirmed Gittensor contributor	glorydavid03023; Gittensor profile; 75 PR(s), 6 issue(s).	No action.
Gate result	✅ Passing	No configured blocker found.	No action.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Review load = cached public PR metadata such as size labels, changed paths, and preflight status.
• Open PR queue = repo-wide review pressure; it is not a PR quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

Review context

• Author: glorydavid03023
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, TypeScript, C++, JavaScript
• Official Gittensor activity: 75 PR(s), 6 issue(s).
• Related work: Items reference the same linked issue feat(signals): add repo-owner contribution policy snapshots #111. (issue #111, PR #369)
• Related work: Items reference the same linked issue feat(raycast): scaffold Gittensory Raycast extension #113. (issue #113, PR #356)
• Related work: Items reference the same linked issue feat(registration): create Gittensory self-dogfood registration pack #117. (issue #117, PR #388)
• Additional title-only matches omitted; title-only overlap does not block.

Maintainer notes

• No linked issue detected: The planned PR does not reference a closing issue or explicit linked issue number.
• Possible duplicate or overlapping work: 26 related open work cluster(s) were detected.

Contributor next steps

• Explain no-issue PR.
• Review top overlaps.
• Add scope summary.
• Expect slower review.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.
• Check active issues and PRs before submitting.

• Re-run Gittensory review

---

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers. Learn more about Gittensor contribution workflows.

[JSONbored]

@glorydavid03023 this is good to land, after fixing merge conflicts.

A few notes:

• The default doctor exit behavior stays compatible.
• --exit-code gives CI/pre-commit users the stricter behavior they need without changing existing scripts.
• The tests cover default exit 0, failure exit 1 under the flag, and passing exit 0 under the flag.
• Fix merge conflicts, then I'll approve once done.