feat(packslip): shell completions from a tool's packslip

[jdx]

Summary

Stacked on #12778. A packslip may list what a release ships besides its executables. This PR reads its completion and cli-spec resources for tools installed with the packslip: backend.

• mise completion <shell> --tool <name> prints the tool's completion script for whichever of its versions is active in the current directory. <name> is the tool or one of its executables. Sources are tried in the order the specification gives, most verifiable first: a file inside the artifact or a separate signed asset, a file from the source repository at the release's commit, a script derived from the tool's usage spec with the usage command, and only then a command of the tool's own.
• packslip.exec setting (default off). An exec entry runs a freshly installed binary when the shell first asks for a completion, before the user has run the tool, so it is refused unless this is on; the error says what would have run and how to allow it.
• --install writes a stub, not the script. Completions are global shell state while the active version depends on the directory, so the stub asks mise for the script at completion time and follows version switches without being rewritten. It goes where the shell loads completions by name, through usage's resolver, the same place mise completion zsh --install puts mise's own, and carries the marker that resolver looks for so re-installing replaces it. The zsh stub only calls the loaded function if the script actually redefined it, so an autoload-style vendor script cannot recurse into the stub.
• Fetch at install. Files a vendor keeps outside the artifact are fetched when the tool is installed: a separate release asset must match the digest the packslip signed, and a repository file is pinned by the release's commit (github.com and gitlab.com raw URLs).

Test plan

• clippy, fmt, hk; JSON schema and CLI docs regenerated
• Unit tests: statement read-back and validation, raw-file URLs, source ordering (shipped files first, unfetched assets skipped, spec before exec), stub content per shell
• e2e: mise completion zsh --tool packslip reports that the 0.2.0 packslip declares no completion; an unknown tool is refused

🤖 Generated with Claude Code

---

Note

Medium Risk
New install-time network fetches and completion-time tool execution (when packslip.exec is enabled) touch shell integration and verified packslip data, though paths and digests are constrained and exec is opt-in.

Overview
Adds mise completion <shell> --tool <name> so packslip-installed tools can expose shell completions from their signed manifest resources (completion / cli-spec), using the active version in the current directory. Sources are tried in spec order (shipped files → signed assets → repo files at the release commit → usage-derived scripts → tool exec commands).

Introduces packslip.exec (default off) because exec-based completions run a freshly installed binary at tab time. --install now writes a version-aware stub (via usage’s installer) that calls mise at completion time instead of baking in one script; zsh/bash restore the stub after each completion so directory-based version switches stay correct.

On install, the packslip backend fetches out-of-artifact resources into .mise-packslip/ (digest-checked assets, GitHub/GitLab repo files). Docs, schema, and e2e cover missing completions and unknown tools.

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

Summary by CodeRabbit

• New Features

  • Added --tool <TOOL> to mise completion to generate shell completions for installed tools.
  • Added --install support for version-aware completion stubs that update automatically when tool versions change.
  • Completions can be sourced from packaged files, CLI specifications, or tool-provided commands.
  • Added optional [packslip] exec configuration, disabled by default, for command-based completion generation.

• Documentation

  • Updated CLI help, manual pages, and packslip documentation with usage examples and source-selection details.

• Bug Fixes

  • Added validation for unsupported tools and packslip releases without completion definitions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Team

Run ID: 36f9816a-f1bd-422b-bcdc-53dc3ad1b23f

📥 Commits

Reviewing files that changed from the base of the PR and between e3ce070 and c098baf.

📒 Files selected for processing (11)

• docs/cli/completion.md
• docs/dev-tools/backends/packslip.md
• e2e/backend/test_packslip
• man/man1/mise.1
• mise.usage.kdl
• schema/mise.json
• settings.toml
• src/backend/packslip.rs
• src/cli/completion.rs
• src/main.rs
• src/packslip.rs

Included review availability: Your plan provides up to 10 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

Changes

The mise completion command now generates completions for installed packslip tools. It selects and fetches verified resources, derives scripts from CLI specifications, optionally runs tool commands, and installs shell-specific dynamic stubs. Documentation, settings, schema, and end-to-end coverage were updated.

Packslip resource acquisition

Layer / File(s)	Summary
Resource acquisition and artifact selection src/packslip.rs, src/backend/packslip.rs, src/main.rs	Packslip statements and external resources are validated, selected for the host artifact, fetched into .mise-packslip, and checked against path and digest rules.

Completion resolution

Layer / File(s)	Summary
Completion source resolution and shell loaders src/packslip.rs	Completion resources are filtered by artifact and platform specificity. File, specification, executable, and specification-executable sources are tried in order. Shell-specific stubs defer loading to mise.

CLI integration and supporting updates

Layer / File(s)	Summary
CLI integration, settings, and validation src/cli/completion.rs, mise.usage.kdl, settings.toml, schema/mise.json, docs/..., man/man1/mise.1, e2e/backend/test_packslip	The CLI accepts --tool, installs dynamic stubs, and reports installation results. The packslip.exec setting, documentation, examples, and failure checks were added.

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

Merge Risk: ⚪ Minimal · up to 9c7f0

No actionable merge-blocking risk is established at the current head.

Sequence Diagram(s)

sequenceDiagram
  participant Shell
  participant MiseCompletion
  participant Packslip
  participant Tool
  Shell->>MiseCompletion: request completion for installed tool
  MiseCompletion->>Packslip: resolve active statement and sources
  Packslip->>Tool: run derivation command when packslip.exec is enabled
  Tool-->>Packslip: return completion script
  Packslip-->>MiseCompletion: provide selected script
  MiseCompletion-->>Shell: print or load completion

Loading

Suggested reviewers: risu729

Poem

A rabbit hops through packslip files,
Finds shell scripts in tidy piles.
It checks each path and signed degree,
Then grows a stub beside the tree.
Version switches make it spring,
And fresh completions softly sing.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 80.56% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 36 functions across 4 files. (7 skipped: 7 …
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: adding shell completion support sourced from a tool's packslip.

---

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

This PR adds packslip-provided, active-version-aware tool completions and install-time fetching of completion resources.

• Adds mise completion <shell> --tool <name> and version-aware completion stubs.
• Restores Bash and Zsh stubs after vendor completion scripts run.
• Adds opt-in execution for command-generated completions and verifies fetched release assets.
• Updates generated CLI documentation, configuration schema, and packslip tests.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/packslip.rs	Implements resource fetching, completion source selection, script generation, and Bash/Zsh restoration; the previously reported stale-state and return-handling issues are fixed.
src/cli/completion.rs	Adds tool-specific completion output and installation through usage’s shell completion resolver.
src/backend/packslip.rs	Fetches external packslip resources after installation and exposes selected-artifact resolution.
settings.toml	Adds the default-off packslip execution setting used to gate tool-provided completion commands.
e2e/backend/test_packslip	Covers missing packslip completion declarations and unknown active tools.

_{Reviews (20): Last reviewed commit: "fix(packslip): say when a completion was..." | Re-trigger Greptile}

[cursor]

Zsh stub double-runs vendor scripts

Medium Severity

The zsh stub evals the vendor script inside _{tool}, so usage-style scripts whose funcstack[1] check self-invokes already complete once. The stub then sees the redefined body and calls that function again, producing duplicate candidates and a second generator run on every tab.

 

^{Reviewed by Cursor Bugbot for commit 476f317. Configure here.}

[jdx]

Fixed: the stub reads compstate[nmatches] before and after the eval. A script that completes on its own, as a usage or clap script does when it finds itself inside _tool, changes it, and the stub then does not call the function again.

[cursor]

Asset fetch omits GitHub API headers

Medium Severity

headers_for only treats github.com and raw.githubusercontent.com as GitHub, so a resource url on api.github.com (or GHE) is downloaded with no bearer token and no Accept: application/octet-stream. The artifact installer already uses is_github_api_url for those URLs; without it the response is metadata JSON, the signed digest does not match, and the whole install is aborted.

Additional Locations (1)

• src/packslip.rs#L140-L142

 

^{Reviewed by Cursor Bugbot for commit 476f317. Configure here.}

[jdx]

Fixed: headers_for treats api.github.com like the backend does, so an asset URL on the API host is fetched with the bearer token and the octet-stream media type.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

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

There are 3 total unresolved issues (including 2 from previous reviews).

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

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

[cursor]

Multi-bin completions pick wrong source

Medium Severity

completion_sources selects among every completion and cli-spec together instead of isolating the executable being completed. Entries for other bins stay in play, and applicable can drop another executable's only entry when one bin is more specifically scoped. Completing a second binary can then load the first binary's script or spec.

 

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

[github-actions]

Instruction counts

The comparison never ran — an earlier step failed.

_{c098baf74595 vs `` · measured on the runner, not pushed to the history.}