feat(core): extract read handlers (doctor, query)

[galligan]

Summary

• Extract doctorHandler and queryHandler to packages/core/src/handlers/
• Both CLI and MCP surfaces call the same handlers
• Handlers return Result<T, E> with typed inputs/outputs
• Move shared query helpers (bot filters, sync scopes, state resolution) into handlers (FIRE-5)

Test plan

• bun run check passes
• bun test passes (288 tests)

🤘🏻 In-collaboration-with: Claude Code

Greptile Summary

Extracts doctorHandler and queryHandler to packages/core/src/handlers/, implementing the handler contract pattern. Both CLI and MCP surfaces now call the same core handlers with typed Result<T, E> return values. Shared query logic (bot filters, sync scopes, state resolution) has been consolidated into the handlers as planned in FIRE-5.

Key changes:

• Created packages/core/src/handlers/doctor.ts with diagnostic checks
• Created packages/core/src/handlers/query.ts with query logic consolidation
• Refactored apps/cli/src/commands/doctor.ts to use doctorHandler (removed 165 lines)
• Refactored apps/mcp/src/index.ts to use doctorHandler with formatting helpers (removed 72 lines)
• Exported new handlers and types from core package

The refactoring successfully eliminates duplication while maintaining the same functionality across both surfaces.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• Clean refactoring that extracts duplicate logic to core handlers. The code moves existing, tested logic without changing behavior. All tests pass (288 tests), and the handler contract pattern is consistently applied.
• No files require special attention

Important Files Changed

Filename	Overview
apps/cli/src/commands/doctor.ts	Refactored to use doctorHandler from core, removed 165 lines of duplicated logic
apps/mcp/src/index.ts	Refactored to use doctorHandler, simplified with formatting helpers, removed 72 lines
packages/core/src/handlers/doctor.ts	New handler implementing diagnostic checks with Result types, 246 lines of well-structured logic
packages/core/src/handlers/query.ts	New handler consolidating query logic with typed inputs/outputs, 342 lines of extraction

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    CLI[CLI doctor command] --> DH[doctorHandler]
    MCP[MCP fw_doctor tool] --> DH
    
    DH --> CH1[checkGithubReachable]
    DH --> CH2[checkAuth]
    DH --> CH3[checkConfigParse]
    DH --> CH4[checkCacheWritable]
    DH --> CH5[checkRepoDetection]
    DH --> CH6[checkGraphiteCli]
    DH --> GI[getGraphiteStackInfo]
    
    DH --> DO[DoctorOutput]
    DO --> |Result<T, E>| CLI
    DO --> |Result<T, E>| MCP
    
    CLI2[CLI query command] -.future.-> QH[queryHandler]
    MCP2[MCP fw_query tool] -.future.-> QH
    
    QH -.-> QE[queryEntries]
    QH -.-> CSF[applyClientSideFilters]
    QH -.-> BW[buildWorklist]
    QH -.-> QO[QueryOutput]
    
    style DH fill:#a8dadc
    style QH fill:#a8dadc
    style DO fill:#f1faee
    style QO fill:#f1faee

Loading

_{Last reviewed commit: e353d4e}

[linear]

FIRE-5 Extract read handlers to core (query, list, view, doctor)

[galligan]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• docs: update architecture docs for Outfitter stack adoption #172
• feat(mcp): adopt @outfitter/mcp with createMcpServer() and defineTool() #171
• refactor(cli): wire exitWithError() across key commands #170
• feat(cli): adopt @outfitter/cli with createCLI() entry point #169
• feat(core): extract sync handler #168
• feat(core): extract PR mutation handlers (approve, reject, edit) #167
• feat(core): extract feedback handlers (reply, comment, ack, close) #166
• feat(core): extract read handlers (doctor, query) #165 👈 (View in Graphite)
• feat(core): define handler contract and extract statusHandler #164
• chore(core): upgrade @outfitter/contracts to ^0.4.1 #163
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e353d4ecb8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Treat viewer lookup failures as auth check failures

fetchViewerLogin() returns a Result, but this branch maps an Err to "unknown" and still reports ok: true; with an expired or invalid token, doctor will incorrectly claim auth is valid. This makes diagnostics unreliable for real auth outages because the failing API call is swallowed instead of surfaced as a failed check.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Reject mine/reviews filtering when username is missing

When mine or reviews is requested but no configured username is available, this returns all entries unchanged, so callers get silently unfiltered results while believing the perspective filter was applied. Existing query flows treat missing user.github_username as an error, so this behavior introduces incorrect query results rather than a clear failure.

Useful? React with 👍 / 👎.