fix(cli): emptyHint statico dei tool ora arriva anche via CLI

[aborruso]

Problema

emit() in src/cli.ts scriveva su stderr solo l'hint dinamico (result.hint), mai l'emptyHint statico definito dai tool. Il server MCP invece li unisce (src/server.ts: result.hint ?? emptyHint ?? DEFAULT_EMPTY). Scollamento CLI↔MCP: chi usava la CLI su una finestra vuota — caso reale, le fiducie COVID 2020 assenti dal LOD Senato — riceveva un CSV vuoto, exit 0, senza alcuna spiegazione, pur essendo già scritta nel codice del tool.

Fix

runTool() ora applica withEmptyHint(), un helper puro in src/core/empty-hint.ts: su risultato vuoto e senza hint dinamico, valorizza result.hint con l'emptyHint statico del tool (stessa precedenza result.hint ?? emptyHint del path MCP). emit() resta invariato — già scrive result.hint su stderr — e i ~50 call site non cambiano.

Beneficiano i 6 tool con emptyHint statico: senato-votes, bill-progress, amendments, bills, sindacato-ispettivo, votes.

Verifica

• Caso reale (buco Cura Italia, 10 mar–16 apr 2020): stdout solo header, emptyHint completo su stderr, exit 0.
• Spot check su bill-progress, bills, sindacato-ispettivo, votes: hint ora visibile via CLI.
• tsc --noEmit pulito; 136/136 test passano (6 nuovi sull'helper: 4 casi della spec + non-mutazione + parità con la risoluzione MCP).

Note

• Nessun breaking change: stdout ed exit code invariati; cambia solo un messaggio informativo su stderr in caso di risultato vuoto.
• Include gli artefatti spec-driven in openspec/ (proposta, design, spec, tasks) e la spec principale openspec/specs/cli-empty-result-hint/.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR aligns CLI empty-result hints with the existing MCP behavior.

• Adds a withEmptyHint() helper for static tool hints.
• Applies the helper in the CLI runTool() path.
• Adds unit tests for hint precedence, empty results, and immutability.
• Adds OpenSpec documentation for the new CLI behavior.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
src/cli.ts	Routes CLI tool results through the empty-hint fallback before emitting output.
src/core/empty-hint.ts	Adds a pure helper that applies a static empty hint only when an empty result has no dynamic hint.
src/core/empty-hint.test.ts	Adds focused coverage for static fallback behavior and MCP-style hint precedence.
openspec/specs/cli-empty-result-hint/spec.md	Documents the CLI behavior for empty-result hint resolution.

_{Reviews (3): Last reviewed commit: "docs(openspec): allinea design/spec al f..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Allinea il comportamento della CLI con quello del server MCP quando un tool produce un risultato vuoto: se manca un hint dinamico (result.hint), la CLI deve poter mostrare su stderr l’emptyHint statico del tool, senza contaminare lo stdout (CSV/JSONL) né cambiare exit code.

Changes:

• Introdotto l’helper puro withEmptyHint() per valorizzare result.hint con emptyHint solo nel caso di risultato vuoto e assenza di hint dinamico.
• Aggiornato runTool() in CLI per applicare withEmptyHint() prima di passare il risultato a emit().
• Aggiunta copertura test e documentazione/spec in openspec/ per il requisito “CLI empty result hint”.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/core/empty-hint.ts	Helper per applicare il fallback emptyHint al ToolResult in caso di risultato vuoto.
src/core/empty-hint.test.ts	Test unitari per la semantica e la parità con la risoluzione lato MCP.
src/cli.ts	Applica withEmptyHint() nel path CLI (in runTool) per propagare l’hint su stderr via emit().
openspec/specs/cli-empty-result-hint/spec.md	Specifica del requisito e scenari attesi per la CLI su risultato vuoto.
openspec/config.yaml	Config di base per OpenSpec (spec-driven).
openspec/changes/archive/2026-07-11-fix-cli-emptyhint-fallback/tasks.md	Checklist di implementazione/verifica dell’intervento.
openspec/changes/archive/2026-07-11-fix-cli-emptyhint-fallback/specs/cli-empty-result-hint/spec.md	Snapshot dei requisiti aggiunti per l’archivio change.
openspec/changes/archive/2026-07-11-fix-cli-emptyhint-fallback/proposal.md	Motivazione e impatto del cambiamento CLI↔MCP.
openspec/changes/archive/2026-07-11-fix-cli-emptyhint-fallback/design.md	Decisioni di design (punto di modifica: runTool, precedenza, immutabilità).
openspec/changes/archive/2026-07-11-fix-cli-emptyhint-fallback/.openspec.yaml	Metadati change OpenSpec (schema + data).

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

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