Add Usage CLI spec for shell completions and docs

[alexey1312]

Description

• Add exfig.usage.kdl — full Usage specification covering all 19 CLI commands, flags, arguments, and defaults
• Add usage tool to mise.toml with completions:bash, completions:zsh, completions:fish, and docs:cli-reference tasks
• Generate and attach shell completions (bash, zsh, fish) as GitHub Release assets in release.yml
• Update CLAUDE.md with new completion commands in Quick Reference and a reminder to keep exfig.usage.kdl in sync when modifying CLI

Additional notes

• The KDL spec is static and must be manually updated when CLI flags or subcommands change
• Shell completions require the usage CLI at runtime for dynamic completion resolution
• Experimental flags like --experimental-granular-cache are marked hide=true in the spec

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the ExFig CLI's usability and maintainability by introducing a centralized usage specification. This specification now powers the automatic generation of shell completions and comprehensive CLI documentation, ensuring consistency and reducing manual effort. It also integrates these generated assets into the GitHub release process, making them readily available to users.

Highlights

• CLI Usage Specification: A new file, exfig.usage.kdl, was added to provide a comprehensive usage specification for all 19 ExFig CLI commands, flags, arguments, and their defaults.
• Automated Completions and Docs Generation: The mise.toml configuration was updated to include the usage tool and new tasks (completions:bash, completions:zsh, completions:fish, docs:cli-reference) for generating shell completions and CLI documentation directly from the exfig.usage.kdl spec.
• GitHub Release Integration: Shell completions (bash, zsh, fish) will now be generated and attached as GitHub Release assets, streamlining distribution.
• Documentation Updates: CLAUDE.md was updated to include the new completion commands in the Quick Reference section and a crucial reminder to keep exfig.usage.kdl synchronized with any CLI modifications.

Changelog

• CLAUDE.md
  • Added new commands for generating shell completions and CLI reference documentation.
  • Added an important note reminding developers to update exfig.usage.kdl when modifying CLI flags or subcommands.
• exfig.usage.kdl
  • Added a new file defining the complete usage specification for the ExFig CLI, including all commands, flags, arguments, and their descriptions.
• mise.lock
  • Added the usage tool, version 2.18.2, with its platform-specific checksums and download URL.
• mise.toml
  • Added the usage tool as a dependency.
  • Added new mise tasks for generating bash, zsh, and fish shell completions, and CLI reference documentation using the usage tool and exfig.usage.kdl.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/release.yml

Activity

• No human activity has occurred on this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a significant improvement by adding a exfig.usage.kdl file to serve as a single source of truth for the CLI's structure. This enables auto-generation of shell completions and reference documentation, which greatly enhances developer and user experience. The implementation is well-executed, with corresponding updates to mise.toml for tooling and CLAUDE.md for project documentation. My review focuses on refining the new KDL specification to ensure its accuracy and descriptiveness aligns with the existing command definitions.

[alexey1312]

Thanks for the review! All comments addressed in d09c23c:\n\n- version: Fixed to \"v2.8.0\" to match ExFigCommand.version\n- filter help texts: Updated colors, icons, and images filter args with more descriptive help matching the Swift source (single/multiple/wildcard examples)\n- release.yml: Hardened curl with --fail + pipefail, pinned usage to v2.18.2, added non-empty file validation\n- mise.toml: Pinned usage = \"2.18.2\" (was \"latest\")\n- schemas default: Removed trailing slash from \".exfig/schemas/\"