feat(min)!: split completions into print and install verbs by norrietaylor · Pull Request #1009 · gominimal/minimal

norrietaylor · 2026-07-29T01:31:29Z

Breaking change to the min command surface. Part of the <noun> <verb>
sweep started by #976.

Before / after

min completions bash              →  min completions print bash
source <(min completions bash)    →  source <(min completions print bash)
                                  +  min completions install [bash|zsh|fish]

completions also accepts completion, per the singular/plural alias rule.

Why `install` exists

All the bookkeeping around actually installing a completion file — the target
directory per shell, the atomic write, tolerating an unwritable directory,
invalidating a stale zsh compinit dump — lived in scripts/install.sh. That
made it reachable only by people who installed via curl | sh. It now lives in
the binary, and the installer delegates.

install writes to:

Shell	Path
`bash`	`$XDG_DATA_HOME/bash-completion/completions/min`
`zsh`	`$XDG_DATA_HOME/zsh/completions/_min`
`fish`	`$XDG_CONFIG_HOME/fish/completions/min.fish`

With no shell argument it installs all three. print still accepts every shell
clap supports, including elvish; install covers only the three with a
conventional per-user completion path.

The stdout contract

install prints every path it wrote to stdout, one per line. scripts/install.sh
records exactly those paths in its install record — it derives no paths of its
own, so uninstall stays correct even if the binary's target paths change.
Warnings (unwritable directory) and notices (dropped compinit dump) go to
stderr, which the installer relays in its own voice.

An unwritable completion directory is a warning, not a failure: the remaining
shells still install and the exit status is still 0. The binaries are already
correctly installed at that point; completions regenerate on the next run.

Verification

Check	Result
`just test-installer`	green — 225 assertions per shell, 0 failed
`cargo build -p minimal`	green

The harness gained a test that drives a mock min which installs completions
somewhere the installer would never derive, asserting the installer records
that path and none of its own — the contract above, tested adversarially.

Because the harness drives a mock, the real implementation was also exercised
by hand against throwaway HOMEs:

min completions install with no args → installed all three, printed all
three paths, clean stderr, exit 0
with ~/.config/fish/completions chmod'd 500 → bash and zsh installed and
printed, fish warned on stderr, exit 0, no fish file written, no raw
permission denied leak
min completions print bash → emits the _clap_complete_min shim

Follow-up

mip completions still has the old single-verb shape. Same treatment applies;
not done here to keep this reviewable.

Refs #1005

🤖 Generated with Claude Code

Note

Split `min completions` into `print` and `install` subcommands

Replaces the single min completions <shell> argument with two subcommands: print (writes the registration shim to stdout) and install (atomically installs completions into XDG autoload paths).
install performs best-effort installation across Bash, Zsh, and Fish, printing installed paths on stdout and warnings on stderr without failing on unwritable directories; it also drops the zsh compinit cache after install.
scripts/install.sh is updated to delegate completion installation to min completions install <shell>, recording exactly the paths reported on stdout and relaying stderr warnings.
Behavioral Change: callers using min completions <shell> must switch to min completions print <shell>; min completion is added as a visible alias.

^{Macroscope summarized 2a28979.}

Summary by CodeRabbit

New Features
- Added min completions print to output shell completion scripts.
- Added min completions install for Bash, Zsh, and Fish.
- Installations now use shell-specific locations, atomic writes, and report installed paths.
- Zsh completion caches are refreshed automatically.
Documentation
- Updated CLI documentation with the new completion commands and installation behavior.
Bug Fixes
- Improved handling of unwritable completion directories with non-fatal warnings.

coderabbitai · 2026-07-29T01:31:37Z

📝 Walkthrough

Walkthrough

The min completions command now supports print and install subcommands. Completion installation handles shell-specific paths, atomic writes, warnings, stdout path reporting, and zsh cache invalidation. The installer, documentation, logging, and integration tests were updated accordingly.

Changes

Completion installation flow

Layer / File(s)	Summary
CLI contract and dispatch `crates/minimal/src/lib.rs`, `crates/minimal/src/main.rs`	The completions command now dispatches nested `print` and `install` subcommands, while completion output remains isolated on stdout.
Shell rendering and installation `crates/minimal/src/completions.rs`, `docs/reference/cli-min.md`	Shell shims are rendered and installed using XDG fallback paths, atomic sibling-file replacement, per-shell warnings, stdout path reporting, and zsh cache removal.
Installer bookkeeping integration `scripts/install.sh`	The installer invokes the binary’s install command, records paths emitted on stdout, and relays stderr warnings.
Installer test coverage `scripts/install_test.sh`	Mocks and assertions cover emitted-path recording, zsh behavior, reusable mock binaries, and unwritable completion directories.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related issues

gominimal/minimal#1005 — Directly covers the min completions print/install command surface and binary-owned installation logic.

Possibly related PRs

gominimal/minimal#966 — Both changes modify completion registration-shim plumbing and dynamic completion behavior.

Suggested reviewers: twitchyliquid64

Poem

A rabbit hops where completions bloom,
Bash, zsh, and fish make room.
Atomic paths land neat and bright,
Zsh dumps vanish overnight.
“Print or install!” the bunny sings,
While stdout tracks the useful things.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	Conventional commit subject is concise, specific, and matches the main breaking change.
Description check	✅ Passed	It covers the change, rationale, verification, and breaking impact; only the template's explicit Summary/Testing/Checklist headings are missing.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

Create stacked PR
Commit on current branch

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

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/reference/cli-min.md`:
- Around line 169-172: Declare the fenced code block language for the completion
commands by changing the fence around the min completions examples to use sh,
preserving the existing command text unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c69916a6-7cdb-4554-8527-c7a87a2b6ff4

📥 Commits

Reviewing files that changed from the base of the PR and between 5aba97a and df8d664.

📒 Files selected for processing (6)

crates/minimal/src/completions.rs
crates/minimal/src/lib.rs
crates/minimal/src/main.rs
docs/reference/cli-min.md
scripts/install.sh
scripts/install_test.sh

coderabbitai · 2026-07-29T03:23:05Z

 ```
-min completions <SHELL>
+min completions print <SHELL>
+min completions install [<SHELL>...]
 ```


📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Declare the command fence language.

This triggers markdownlint MD040.

Proposed fix

-``` +```sh min completions print <SHELL> min completions install [<SHELL>...]

</details>  <details> <summary>📝 Committable suggestion</summary> > ‼️ **IMPORTANT** > Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements. ```suggestion

🧰 Tools

🪛 markdownlint-cli2 (0.23.1)

[warning] 169-169: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/cli-min.md` around lines 169 - 172, Declare the fenced code block language for the completion commands by changing the fence around the min completions examples to use sh, preserving the existing command text unchanged.

Source: Linters/SAST tools

Move the installer's completion bookkeeping — per-shell target path, atomic write, unwritable-dir tolerance, zsh compinit invalidation — out of scripts/install.sh and into the binary, so it is reachable by everyone rather than only by users who installed via curl | sh. The installer now delegates and records the paths install reports. install prints every path it wrote on stdout, one per line; that is the contract between the two halves, and the installer derives no paths of its own. BREAKING CHANGE: min completions <shell> is now min completions print <shell>. Refs: #1005 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The naming convention requires both spellings of a noun to show in --help; clap's `alias` is hidden, `visible_alias` is not. Refs: #1005 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

#1009 split `min completions <shell>` into `completions print` and `completions install`; the release job still called the flat form, so `Generate completions` exited 2 on run 30425725370 and the release never reached GCS or the GitHub Release. Switch the three `min` lines to `completions print <shell>`, and name their outputs after the `min` binary (`min`, `_min`, `min.fish`) rather than the crate: the shim `min` prints registers the command `min`, so a shell only ever autoloads it from a file of that name — the `minimal`/`_minimal` files shipped in `completions.tar.gz` since the binary rename (#737) were dead on arrival. `mip` and `minimald` keep the flat verb; only the `min` CLI changed. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

norrietaylor mentioned this pull request Jul 29, 2026

feat(cli): finish the <noun> <verb> command-surface sweep for min and mip #1005

Closed

norrietaylor force-pushed the feat/min-completions-install branch from f657cae to 4e876f9 Compare July 29, 2026 01:36

norrietaylor changed the title ~~feat!(min): split completions into print and install verbs~~ feat(min)!: split completions into print and install verbs Jul 29, 2026

norrietaylor force-pushed the feat/min-completions-install branch from 4e876f9 to fec83ff Compare July 29, 2026 01:39

coderabbitai Bot reviewed Jul 29, 2026

View reviewed changes

msample approved these changes Jul 29, 2026

View reviewed changes

norrietaylor and others added 2 commits July 28, 2026 21:40

fix(min): make the completions singular alias visible in help

2a28979

The naming convention requires both spellings of a noun to show in --help; clap's `alias` is hidden, `visible_alias` is not. Refs: #1005 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

norrietaylor force-pushed the feat/min-completions-install branch from df8d664 to 2a28979 Compare July 29, 2026 04:41

norrietaylor enabled auto-merge (squash) July 29, 2026 04:46

norrietaylor merged commit 3eeb498 into main Jul 29, 2026
31 checks passed

norrietaylor deleted the feat/min-completions-install branch July 29, 2026 05:29

This was referenced Jul 29, 2026

fix(release): call min completions print in the release job #1034

Merged

Release-job CLI invocations have no pre-merge coverage — a breaking min/mip change only surfaces on a release run #1035

Open

This was referenced Jul 29, 2026

test(common): gate the release job's CLI invocations pre-merge #1044

Closed

test(common): gate the release job's completions pre-merge #1048

Closed

coderabbitai Bot mentioned this pull request Jul 31, 2026

feat(installer): brand the curl|sh run with a mark, table, and card #1122

Merged

Navigation Menu

Uh oh!

feat(min)!: split completions into print and install verbs - #1009

feat(min)!: split completions into print and install verbs#1009
norrietaylor merged 2 commits into
mainfrom
feat/min-completions-install

norrietaylor commented Jul 29, 2026 •

edited by macroscopeapp Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 29, 2026 •

edited

Loading

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

coderabbitai Bot Jul 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

norrietaylor commented Jul 29, 2026 • edited by macroscopeapp Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Before / after

Why install exists

The stdout contract

Verification

Follow-up

Split min completions into print and install subcommands

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

norrietaylor commented Jul 29, 2026 •

edited by macroscopeapp Bot

Loading

Why `install` exists

Split `min completions` into `print` and `install` subcommands

coderabbitai Bot commented Jul 29, 2026 •

edited

Loading