fix: make search output compact and scannable by jlitola · Pull Request #317 · githits-com/githits-cli

jlitola · 2026-08-27T07:49:36Z

Summary

use one shared CLI and MCP text-v1 formatter for search and search-status
group indexing readiness once per target, followed by one session row and one next action
preserve production-strength, ranked hit locators so agents can hand results directly to docs_read and code_read
keep formatter punctuation ASCII while preserving backend Unicode verbatim
adapt CLI wrapping to terminal width while MCP keeps the deterministic 80-column default

User-visible outcome

Indexing with no ready results becomes:

Indexing - no results yet

- npm:n8n -> 2.36.7
  Indexing: code, repository docs | Available now: n8n.io docs (<pages> pages;
  capped), versions 2.26.9, 2.26.5, 2.23.2 +2, refs HEAD, master

Search <search-ref> | 0/1 target ready
Next: githits search-status <search-ref> --wait 20

A live Express query now starts:

10 results | 5 repo docs, 5 docs pages | next_offset=10

Sources: expressjs.com; expressjs/express@dbac741a

[1] npm:express@5.2.1 History.md:169-179 [repo doc] - 5.0.0-alpha.4 / 2017-03-01
  This is the fourth Express 5.0 alpha release, based off 4.15.0 and includes
  changes from 5.0.0-alpha.3.

[2] 1460625 [docs page] npm:express - expressjs.com/en/api/router/#routeruse -
  router.use()

At wider terminal widths, a fitting title stays on the locator line. At narrower widths, only the free-form title tail wraps; page IDs, targets, paths, ranges, and URLs remain intact. A docs title may contain | or - without changing the fixed field boundaries.

Architecture

unified-search-presentation.ts owns transport-neutral target grouping and readiness semantics. unified-search-text.ts owns shared wording, ranking, locator anatomy, provenance, pagination, ANSI hierarchy, and wrapping. CLI and MCP supply color capability, action syntax, and output width only. Other text-v1 tool formatters are unchanged.

Hit headers use locator-first, type-tagged, title-last grammar. Documentation page IDs remain visible because they are the docs_read locator; repository target/path/range identities remain visible for code_read. JSON remains unchanged and retains the full structured locator.

Verification

full post-runtime suite: 3,461 pass, 0 fail
final validator suites: MCP 41 pass; CLI 53 pass
bun run typecheck
bun run build
Biome and git diff --check
authenticated bun run smoke:cli: 89 steps passed
authenticated bun run smoke:mcp: 46 steps passed
built Node CLI and MCP smokes passed
live Express output inspected after the final formatter change
Luna preflight clean; retained Opus findings resolved

Release impact

Patch releases for both githits and @githits/mcp; recorded in changes/search-output-hierarchy.changed.md.

Project the backend partialResults boolean into initial and stored status result envelopes so consumers can distinguish interim snapshots from partial evidence. Keep progress-only responses snapshot-free and cover both boolean values across all result-bearing paths.

Project lifecycle, availability, trust, source readiness, bounded alternatives, warnings, and primary actions from structured search payloads. Keep the projection pure and free of renderer prose, ANSI styling, and backend calls.

Retain completed mutable-evidence continuations, contributor source identities, and the ordered applicable rewrite pivots in the shared presentation projection. Keep the model data-only and preserve conservative suppression for limited evidence.

Keep requested, fresh, served, and freshness identities for every progress target while excluding internal diagnostics and alternative arrays. Preserve completed mutable-evidence continuations and ordered applicable rewrite pivots in the shared model.

Include the disclosed pending code source in the n8n presentation fixture and assert grouped readiness for code and documentation contributors.

Render search and search-status text from the shared lifecycle, availability, trust, source, alternative, and action projection. Keep hit anatomy and the CLI helper exports while removing duplicated MCP lifecycle prose.

Update tool and parity expectations for additive partialResults, and enforce concise outcome-first MCP search text with action-contained references in smoke coverage.

Make the smoke invariant catch either legacy search header spelling regardless of trailing whitespace.

Keep suggested site targets as bounded presentation facts with safe retry actions, and retain source identity and target context when grouping readiness. Consolidate alternative bounding in the shared model and remove redundant renderer projection machinery.

Record the in-place text-v1 evolution policy, MCP search lifecycle and action hierarchy, and additive partial-result JSON parity. Add the Phase 1a patch fragment for both public artifacts while keeping CLI human output documented as unchanged.

Route source readiness, indexed alternatives, and site recovery facts through the existing bounded text wrapper while preserving exact identifiers. Make the shared presentation projection authoritative for pagination so initial and stored status renderers cannot disagree about more results.

Preserve parser warnings from initial progress-only queries and use canonical site URL paths before site keys in MCP text. Align permanent documentation with the current in-place text contract and MCP source identity fallback.

Remove the unused legacy unified-search trailer and its private-only helpers after the MCP presentation migration. Keep exported CLI helpers and correct the remaining lint findings.

Map symbol source-status entries to the code readiness group so MCP output reflects the evidence taxonomy. Add presentation and text regressions for the exact symbol source shape.

Classify unknown source states conservatively, avoid unsupported single-target claims, and deduplicate stale evidence. Keep neutral documentation labels, remove dead text helpers, and separate hit blocks from follow-up actions.

Reduce duplicate snapshot, identity, coverage, constraint, alternative, and action plumbing while preserving source-state safety, provenance distinctions, trust deduplication, and multi-target behavior.

Keep served target attribution for stale hits, package context for lone documentation contributors, and deduplicated site-suggestion groups. Use an exhaustive contributor-state mapping and keep renderer internals private.

Remove the unrequested alternative Map rewrite and retain the established array merge while preserving the typed contributor mapping and search-target fixes.

Replace the overloaded source context field with an explicit searched target so provenance identity and package attribution remain distinct across source readiness and result headlines.

Classify divergent hit snapshots as stale evidence while indexing, and avoid repeating standalone site identities when target context already names them.

Use exact undecorated source identities when deciding multi-target suffixes, preserving disambiguation for code and distinct documentation provenance.

Bring the search output plan in line with the verified Phase 1a implementation, evidence, review decisions, and remaining Phase 1b and Phase 2 work.

…put-refresh

Update the search output plan with merged-main test, build, package, smoke, and production-delta evidence while preserving the completed Phase 1a and pending Phase 1b/2 status.

Route CLI search and search-status through the shared outcome-first renderer with ANSI and command-dialect options. Remove the duplicated CLI formatter and keep CLI follow-up actions directly executable.

Document CLI as the inspectable MCP text harness, update the single-formatter ownership boundary, and mark the CLI search-output phase implemented in the existing patch fragment.

Assert outcome-first search text, hide internal lifecycle metadata, and require CLI-native follow-up actions in the live product smoke.

Render executable CLI pagination flags while preserving MCP parameter syntax, and remove the obsolete formatter helpers left behind by the shared-renderer migration.

Unit-test the live CLI search smoke predicate, reject MCP pagination syntax, and document pagination as an intentional surface-native difference.

Keep the structural smoke strict while allowing completed-empty and terminal responses that provide an explicit next action.

Record the final test, smoke, package-validation, size, and retained review evidence for the completed CLI/MCP formatter increment.

…put-refresh # Conflicts: # docs/implementation/tools.md

Update final verification, package-version, delta-size, and conflict-resolution evidence after integrating the current main branch.

Render CLI and MCP search status through target-centric blocks with compact session actions. Preserve exact aliases for grouping and strengthen smoke coverage for the shared hierarchy.

Keep requested targets distinct across shared aliases, attach readiness by exact requested identity, and always render a positive action for limited empty results. Normalize freshness in presentation and tighten CLI/MCP smoke symmetry.

Render status only from explicit freshness, preserve contributor identities in alias matching, and resolve ambiguous source rows by unique requested target. Document the resulting status and recovery anatomy.

Use the shared formatter's width option for CLI output, simplify available-source wording, and render versionless alternatives as refs.

Keep named refs ahead of unmapped commit identifiers in bounded search alternatives and align CLI smoke validation and parity documentation with the Available now wording and terminal-aware wrapping.

Keep CLI and MCP text-v1 on one shared formatter while restoring ranked, human-readable result anatomy. Collapse ordinary completed provenance and pagination without changing JSON locators or readiness detail.

Keep pagination on non-final snapshots, attribute multi-target docs, disclose unavailable human locators, and preserve long exact tokens without exposing opaque IDs.

Keep the shared CLI and MCP unified-search text contract readable across clients while preserving Unicode returned by the backend.

Keep the formatter separator assertion scoped to exact headers so backend-owned punctuation remains lossless.

Render every unified-search hit with locator-first, type-tagged, title-last anatomy. Keep documentation page IDs and readable source URLs in shared CLI/MCP text so docs_read follow-ups remain actionable, and align smoke validators and durable output docs with the contract.

Update direct CLI consumer coverage for the shared locator-first search grammar, including documentation page IDs, scheme-free source URLs, ranked repo-code headers, and ANSI output.

Clarify that formatter-authored search punctuation is ASCII across both pipe and hyphen separators while backend payload Unicode remains unchanged.

Keep fixed hit locators intact while wrapping only long title tails, and restore semantic ANSI emphasis for locators and title matches. Align result breakdown labels and document unavailable repository locations so CLI and MCP output remain consistent.

Accept the shared formatter's wrapped title tails in both CLI and MCP smoke validators while keeping locator metadata and unavailable-field checks strict.

Teach both CLI and MCP smoke validators to recognize repository hit headers whose title continues on indented lines, and cover repository-only wrapped result pages.

jlitola added 24 commits August 27, 2026 07:00

feat: add unified search presentation model

2269026

Project lifecycle, availability, trust, source readiness, bounded alternatives, warnings, and primary actions from structured search payloads. Keep the projection pure and free of renderer prose, ANSI styling, and backend calls.

test: align n8n source readiness fixture

458e3ca

Include the disclosed pending code source in the n8n presentation fixture and assert grouped readiness for code and documentation contributors.

feat: migrate MCP search text to presentation model

ce5b201

Render search and search-status text from the shared lifecycle, availability, trust, source, alternative, and action projection. Keep hit anatomy and the CLI helper exports while removing duplicated MCP lifecycle prose.

test: align tool and smoke search contracts

1c70d5e

Update tool and parity expectations for additive partialResults, and enforce concise outcome-first MCP search text with action-contained references in smoke coverage.

test: reject all legacy search headers

42ea820

Make the smoke invariant catch either legacy search header spelling regardless of trailing whitespace.

fix: retain unified search query and site context

982cc78

Preserve parser warnings from initial progress-only queries and use canonical site URL paths before site keys in MCP text. Align permanent documentation with the current in-place text contract and MCP source identity fallback.

chore: remove dead unified search trailer

7a32352

Remove the unused legacy unified-search trailer and its private-only helpers after the MCP presentation migration. Keep exported CLI helpers and correct the remaining lint findings.

fix: classify symbol readiness as code

b17adbe

Map symbol source-status entries to the code readiness group so MCP output reflects the evidence taxonomy. Add presentation and text regressions for the exact symbol source shape.

fix: harden unified search provenance

b1aa34a

Classify unknown source states conservatively, avoid unsupported single-target claims, and deduplicate stale evidence. Keep neutral documentation labels, remove dead text helpers, and separate hit blocks from follow-up actions.

refactor: simplify unified search projection

0467e7b

Reduce duplicate snapshot, identity, coverage, constraint, alternative, and action plumbing while preserving source-state safety, provenance distinctions, trust deduplication, and multi-target behavior.

fix: preserve unified search target context

fa73ef9

Keep served target attribution for stale hits, package context for lone documentation contributors, and deduplicated site-suggestion groups. Use an exhaustive contributor-state mapping and keep renderer internals private.

refactor: restore alternative merge behavior

f37df0a

Remove the unrequested alternative Map rewrite and retain the established array merge while preserving the typed contributor mapping and search-target fixes.

refactor: separate searched source targets

704815a

Replace the overloaded source context field with an explicit searched target so provenance identity and package attribution remain distinct across source readiness and result headlines.

fix: preserve indexing freshness evidence

53d8eb0

Classify divergent hit snapshots as stale evidence while indexing, and avoid repeating standalone site identities when target context already names them.

fix: avoid duplicate readiness targets

53c710d

Use exact undecorated source identities when deciding multi-target suffixes, preserving disambiguation for code and distinct documentation provenance.

docs: record completed search output phase

3dcb5cc

Bring the search output plan in line with the verified Phase 1a implementation, evidence, review decisions, and remaining Phase 1b and Phase 2 work.

Merge remote-tracking branch 'origin/main' into jlitola/ux-search-out…

78fdfcf

…put-refresh

docs: record integrated search verification

a57d44d

Update the search output plan with merged-main test, build, package, smoke, and production-delta evidence while preserving the completed Phase 1a and pending Phase 1b/2 status.

jlitola added enhancement New feature or request fix labels Aug 27, 2026

jlitola added 4 commits August 27, 2026 17:14

refactor: share search text across CLI and MCP

911f67d

Route CLI search and search-status through the shared outcome-first renderer with ANSI and command-dialect options. Remove the duplicated CLI formatter and keep CLI follow-up actions directly executable.

docs: record shared search formatter contract

16df3d5

Document CLI as the inspectable MCP text harness, update the single-formatter ownership boundary, and mark the CLI search-output phase implemented in the existing patch fragment.

test: strengthen CLI search smoke contract

19ce936

Assert outcome-first search text, hide internal lifecycle metadata, and require CLI-native follow-up actions in the live product smoke.

fix: keep search pagination surface-native

49e495b

Render executable CLI pagination flags while preserving MCP parameter syntax, and remove the obsolete formatter helpers left behind by the shared-renderer migration.

jlitola added 8 commits August 27, 2026 17:41

test: lock CLI search text dialect

e1c0e00

Unit-test the live CLI search smoke predicate, reject MCP pagination syntax, and document pagination as an intentional surface-native difference.

test: accept terminal search smoke outcomes

9157eae

Keep the structural smoke strict while allowing completed-empty and terminal responses that provide an explicit next action.

docs: close shared search formatter verification

79afea3

Record the final test, smoke, package-validation, size, and retained review evidence for the completed CLI/MCP formatter increment.

Merge remote-tracking branch 'origin/main' into jlitola/ux-search-out…

720c641

…put-refresh # Conflicts: # docs/implementation/tools.md

docs: record latest main integration

7d4dbbd

Update final verification, package-version, delta-size, and conflict-resolution evidence after integrating the current main branch.

fix: group search readiness by target

d93d36a

Render CLI and MCP search status through target-centric blocks with compact session actions. Preserve exact aliases for grouping and strengthen smoke coverage for the shared hierarchy.

fix: preserve search target boundaries

a687e8c

Keep requested targets distinct across shared aliases, attach readiness by exact requested identity, and always render a positive action for limited empty results. Normalize freshness in presentation and tighten CLI/MCP smoke symmetry.

fix: report exact search target state

d714cfc

Render status only from explicit freshness, preserve contributor identities in alias matching, and resolve ambiguous source rows by unique requested target. Document the resulting status and recovery anatomy.

jlitola changed the title ~~feat: make search status output outcome-first~~ fix: group search readiness by target Aug 27, 2026

jlitola added 4 commits August 28, 2026 08:38

fix: adapt search output to terminal width

5577670

Use the shared formatter's width option for CLI output, simplify available-source wording, and render versionless alternatives as refs.

fix: preserve useful indexed refs

256a6db

Keep named refs ahead of unmapped commit identifiers in bounded search alternatives and align CLI smoke validation and parity documentation with the Available now wording and terminal-aware wrapping.

fix: compact completed search results

8f05cca

Keep CLI and MCP text-v1 on one shared formatter while restoring ranked, human-readable result anatomy. Collapse ordinary completed provenance and pagination without changing JSON locators or readiness detail.

fix: preserve compact result edge cases

24ff6db

Keep pagination on non-final snapshots, attribute multi-target docs, disclose unavailable human locators, and preserve long exact tokens without exposing opaque IDs.

jlitola changed the title ~~fix: group search readiness by target~~ fix: make search output compact and scannable Aug 28, 2026

jlitola added 8 commits August 28, 2026 10:39

fix: use ASCII search hit separators

ef74408

Keep the shared CLI and MCP unified-search text contract readable across clients while preserving Unicode returned by the backend.

test: preserve Unicode search payload punctuation

a0633d0

Keep the formatter separator assertion scoped to exact headers so backend-owned punctuation remains lossless.

test: align CLI search output expectations

83cde61

Update direct CLI consumer coverage for the shared locator-first search grammar, including documentation page IDs, scheme-free source URLs, ranked repo-code headers, and ANSI output.

docs: document unified search separators

2556232

Clarify that formatter-authored search punctuation is ASCII across both pipe and hyphen separators while backend payload Unicode remains unchanged.

fix: validate wrapped search hit headers

ab46bea

Accept the shared formatter's wrapped title tails in both CLI and MCP smoke validators while keeping locator metadata and unavailable-field checks strict.

fix: accept repository title wrapping

b736444

Teach both CLI and MCP smoke validators to recognize repository hit headers whose title continues on indented lines, and cover repository-only wrapped result pages.

jlitola marked this pull request as ready for review August 28, 2026 09:43

jlitola merged commit 0585e92 into main Aug 28, 2026
10 checks passed

Navigation Menu

Uh oh!

fix: make search output compact and scannable - #317

fix: make search output compact and scannable#317
jlitola merged 48 commits into
mainfrom
jlitola/ux-search-output-refresh

jlitola commented Aug 27, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

jlitola commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

User-visible outcome

Architecture

Verification

Release impact

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jlitola commented Aug 27, 2026 •

edited

Loading