feat(query): query doctor readiness probe + Hermes-aware install script (Phase 1)#5
Merged
Conversation
added 2 commits
May 13, 2026 11:01
…l script Phase 1 of the SQL-first retrieval plan. Two additions, both strictly additive: 1. `topline query doctor` — JSON readiness report agents run before deciding SQL vs REST. Reports: queryTokenPresent (via TOPLINE_QUERY_TOKEN / TOPLINE_MCP_ACCESS_TOKEN / TOPLINE_MCP_TOKEN), rawPitRejected, baseUrl, schemaReachable, tableCount, expectedTables (contacts, opportunities, messages, pipelines, pipeline_stages, call_events, appointments, conversations), missingTables, and a recommendation string. Missing tables are surfaced as an os-mcp coverage bug, not a reason to silently fall back to REST. Never prints the token value. 2. `scripts/install-local.sh` — idempotent installer that builds ~/.local/bin/topline-bin and writes a Hermes-friendly wrapper at ~/.local/bin/topline. The wrapper allowlist now includes TOPLINE_QUERY_TOKEN, TOPLINE_QUERY_BASE_URL, TOPLINE_MCP_ACCESS_TOKEN, and TOPLINE_MCP_TOKEN, so a fresh install just works for the SQL surface. No secrets are printed or written by the script — only the env-var keys. Implementation: - internal/topline/query_client.go: add InspectQueryEnv() that reports TokenPresent / RawPITToken without erroring, and refactor LoadQueryConfig to reuse it. Existing error messages and behavior unchanged for callers that hard-fail on missing token. - internal/commands/query.go: register `doctor` subcommand and the queryDoctorReport JSON shape. - internal/commands/query_test.go: four new tests covering missing token, raw PIT rejection, full table presence (recommendation = ready), and missing expected tables (recommendation = coverage gap). - README.md / docs/examples.md: document the new command and install script. go test ./... passes. Existing query commands and the SQL-first skill contract (PR #4) are unchanged.
Records the full Phase 0-6 plan so contributors and downstream agents can pick up tasks. Phase 1 (`query doctor` + install script) lands in this PR; later phases (query template registry, sales-native report commands, os-mcp freshness metadata) reference this doc. No code change in this commit — plan only.
This was referenced May 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 1 of the SQL-first retrieval plan (
docs/plans/2026-05-13-sql-first-retrieval-improvements.md, committed in this PR). Two strictly additive changes — no behavior change to existing commands.1.
topline query doctor— SQL readiness probeOne command, JSON output, agents run it before deciding SQL vs REST.
Reports:
queryTokenPresent(looks atTOPLINE_QUERY_TOKEN→TOPLINE_MCP_ACCESS_TOKEN→TOPLINE_MCP_TOKEN)tokenSourceEnvVar(which env key was actually used)rawPitRejected(true when the token still starts withpit-)baseUrlschemaReachable(calls/query/api/get-overviewif the token looks valid)tableCountexpectedTables— presence ofcontacts,opportunities,messages,pipelines,pipeline_stages,call_events,appointments,conversationsmissingTablesrecommendation— human-readable next stepNever prints the token value. Missing tables surface as an
os-mcpcoverage bug, not a reason to silently fall back to REST — matches the v1.2.0 / v2.2.0 skill contract from #4.2.
scripts/install-local.sh— Hermes-aware installerIdempotent. Builds
~/.local/bin/topline-binand writes a wrapper at~/.local/bin/toplinethat loads only theTOPLINE_*env keys needed by REST and SQL commands (TOPLINE_PIT,TOPLINE_LOCATION_ID,TOPLINE_BRAND_NAME,TOPLINE_BASE_URL,TOPLINE_QUERY_TOKEN,TOPLINE_QUERY_BASE_URL,TOPLINE_MCP_ACCESS_TOKEN,TOPLINE_MCP_TOKEN). No secrets are printed or persisted — only the env-var keys are written into the wrapper.Fixes the local wrapper drift problem from this week: anyone installing os-cli now gets the SQL allowlist for free.
3. Plan doc committed
docs/plans/2026-05-13-sql-first-retrieval-improvements.mdrecords Phase 0–6 so downstream contributors can pick up Phase 2 (query template registry), Phase 3 (sales-native report commands likeactivity rollup), Phase 4 (agent-shaped answer packets), and Phase D (os-mcpfreshness metadata).Test plan
go test ./...— all packages pass, including 4 newquery doctortestsgo build ./...— clean$(mktemp -d)— builds binary, writes valid wrapper,bash -nsyntax-checks clean--agent