feat(go): write an answer the way each shell reads it

[jdx]

RenderAnswer turns candidates into the protocol a shell's completion machinery expects. Stacked on #984.

shell	shape
bash	value
fish, nu, PowerShell	value\tdescription
zsh	value\tdescription\tinsert

zsh takes a third field because what it displays and what it types are not always the same string. Checked against what usage complete-word --shell zsh already emits:

use^IInstalls a tool and adds the version to mise.toml.^Iuse$

Three rules that look like details and are not

Descriptions are all-or-nothing per answer. A column that appears on some rows and not others reads as missing data rather than as an absent description.

A description is collapsed onto one line, not truncated at the first break, so a two-line description still says both halves. The protocols are line-based and a break would look like another candidate. This is why the one-lining moved here from describe in #984, where it was throwing the second half away — Candidates now carries the whole text and the renderer decides how to fit it.

"Paths belong here too" is a whole line, not a flag on the protocol, because every one of the five shells can already split output into lines and look at the last one. \x01 opens it because no candidate can contain a control character.

Naming

RenderAnswer rather than Render, which already belongs to failures. Two things in one package turning a value into text for a terminal is reason enough to say which.

Still to do

Running the complete scripts a spec can declare, which means subprocesses — a decision for the layer above this one.

🤖 Generated with Claude Code

---

Note

Low Risk
Additive completion-output formatting with broad unit tests; no changes to parsing, binding, or security-sensitive paths.

Overview
Adds argv.RenderAnswer so completion Answer values serialize to the line protocol each shell expects: bash values only; fish, nu, and PowerShell use value + tab + description; zsh adds a third insert field with zshQuote for safe typing.

Rendering enforces all-or-nothing description columns (only among candidates that actually emit), collapses multi-line help with oneLine instead of truncating, drops candidates whose values contain control chars/tabs/newlines rather than repairing them, and appends \x01files / \x01dirs marker lines when paths should complete too.

describe in complete.go now attaches the full short help (including newlines); one-lining moved here from candidate building. README documents RenderAnswer; tests cover per-shell shapes and edge cases.

^{Reviewed by Cursor Bugbot for commit f37999a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: ea912eb0-d9d9-422f-a43d-98f669de77c3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

The PR adds shell-specific rendering for Go completion answers and preserves complete help descriptions until the renderer collapses them safely.

• Emits each shell’s expected value, description, and insertion fields.
• Drops candidate values containing protocol-conflicting control characters.
• Adds path markers and focused tests for formatting, quoting, filtering, and descriptions.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; current code drops control-bearing candidate values instead of corrupting protocol framing or silently changing inserted arguments.

Important Files Changed

Filename	Overview
go/argv/complete_shell.go	Adds shell-specific answer rendering, path markers, description collapsing, unsafe-value filtering, and zsh insertion quoting; the previously reported delimiter and value-mutation issues are fixed at current HEAD.
go/argv/complete_shell_test.go	Covers protocol shapes, all-or-nothing descriptions, multiline collapsing, zsh quoting, marker placement, and rejection of values that cannot safely travel through the protocols.
go/argv/complete.go	Preserves full multiline help text in candidates so protocol-specific rendering can collapse it without truncation.
go/argv/complete_test.go	Updates candidate-generation coverage to require preservation of the complete description.
go/README.md	Documents the shell-specific output contracts exposed by RenderAnswer.

_{Reviews (8): Last reviewed commit: "fix(go): decide the description column o..." | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4e301ec. Configure here.}

[github-actions]

Instruction counts

Nothing was compared, and so nothing was gated. No series appears on both sides: either the base has no measurements recorded, or the two were measured on different runner classes, which are deliberately not comparable — counts shift between machine types by more than a real regression does.

New, nothing to compare against: markdown on bamboo-v2-ubuntu24.04-x64-30vcpu-24gb-rust1.97.1, startup on bamboo-v2-ubuntu24.04-x64-30vcpu-24gb-rust1.97.1

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

Shadow comparison

Parsing mise use -g node@20 against a shadow of mise's committed spec.
Reported, not gated: the shadow grows as the derive learns to express more, so
what to watch is the ratio rather than either column.

framework	instructions, cold parse	vs usage
usage	4161	—
argh	6292	1.5x
clap	5895248	1416x
bpaf	21917778	5267x

                                              min       p01       p10    median
usage-rs: argv -> struct                      193       199       203       209  ns
argh: argv -> struct                          285       293       300       309  ns
clap: build tree + parse -> struct         481068    484502    493754    508004  ns
bpaf: build parser + parse -> struct      1568080   1568080   1585072   1653370  ns

usage: argv -> struct                             214 ns      0.21 µs
clap: build tree + parse -> struct             501175 ns    501.17 µs
clap: parse -> struct, tree reused              24092 ns     24.09 µs
clap: build tree only                          310469 ns    310.47 µs

_{f37999a9ad5c vs c5d9ad605c95 · measured on the runner, not pushed to the history.}