Add clap shell completions and prepare v0.3.0

.github/workflows/ci.yml

@@ -45,6 +45,10 @@ jobs:
           cmp "$CARGO_TARGET_DIR/release/codex-commit" "$executable"
           "$executable" --help
           "$executable" --version
+          "$executable" --completions zsh > "$RUNNER_TEMP/expected-completion"
+          cmp "$RUNNER_TEMP/expected-completion" "$staging/usr/local/share/zsh/site-functions/_codex-commit"
+          test -s "$staging/usr/local/share/bash-completion/completions/codex-commit"
+          test -s "$staging/usr/local/share/fish/vendor_completions.d/codex-commit.fish"
 
   lint:
     name: Lint

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.0
+
+- Use clap for argument parsing and generate shell completions from the same command definition.
+- Add `--completions` for zsh, bash, fish, PowerShell, and Elvish without requiring Git or Codex.
+- Install zsh, bash, and fish completions automatically through Homebrew and `make install`; document setup for Cargo and prebuilt downloads.
+
 ## 0.2.2
 
 - Find unpublished GitHub releases through authenticated release listings and bind asset validation and publication to the release ID, avoiding draft-by-tag API lookup failures.

CONTRIBUTING.md

@@ -16,7 +16,7 @@ cargo publish -p codex-commit --dry-run --locked
 
 `make test` runs `cargo test --workspace --locked`, including the Rust mock Codex executable, disposable local Git remotes, real terminal signal handling, and release-helper validation. Tests do not need Codex login or network push credentials. CI also checks installation on Linux, Apple Silicon macOS, and Intel macOS. Put manual-test artifacts in one scratch directory and remove them after testing.
 
-The runtime has no third-party Rust dependencies. Test and private `xtask` dependencies are locked in `Cargo.lock`; use Cargo to update and verify them rather than adding a second language or package manager to the tooling.
+The CLI uses `clap` and `clap_complete` to keep parsing, help, and shell completions in one command definition. Runtime, test, and private `xtask` dependencies are locked in `Cargo.lock`; use Cargo to update and verify them rather than adding a second language or package manager to the tooling.
 
 Create a branch and open a pull request against `main`. The protected branch requires passing CI before merging. Describe the user-visible change and how you verified it; include only sanitized output. Do not commit credentials or private repository content.
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "codex-commit"
-version = "0.2.2"
+version = "0.3.0"
 edition = "2024"
 rust-version = "1.85"
 description = "Commit Git changes with Codex Luna at Max reasoning, with optional push"
@@ -17,6 +17,10 @@ include = ["Cargo.toml", "Cargo.lock", "src/**", "tests/**/*.rs", "README.md", "
 members = ["xtask"]
 resolver = "3"
 
+[dependencies]
+clap = { version = "4.6.7", default-features = false, features = ["std", "help", "usage", "error-context"] }
+clap_complete = "4.6.11"
+
 [dev-dependencies]
 nix = { version = "0.31.3", features = ["fs", "ioctl", "process", "signal", "term"] }
 serde_json = "1.0.154"

Makefile

@@ -14,6 +14,10 @@ release:
 install: release
 	install -d "$(DESTDIR)$(PREFIX)/bin"
 	install -m 755 "$(CARGO_TARGET_DIR)/release/codex-commit" "$(DESTDIR)$(PREFIX)/bin/codex-commit"
+	install -d "$(DESTDIR)$(PREFIX)/share/zsh/site-functions" "$(DESTDIR)$(PREFIX)/share/bash-completion/completions" "$(DESTDIR)$(PREFIX)/share/fish/vendor_completions.d"
+	"$(CARGO_TARGET_DIR)/release/codex-commit" --completions zsh > "$(DESTDIR)$(PREFIX)/share/zsh/site-functions/_codex-commit"
+	"$(CARGO_TARGET_DIR)/release/codex-commit" --completions bash > "$(DESTDIR)$(PREFIX)/share/bash-completion/completions/codex-commit"
+	"$(CARGO_TARGET_DIR)/release/codex-commit" --completions fish > "$(DESTDIR)$(PREFIX)/share/fish/vendor_completions.d/codex-commit.fish"
 
 check:
 	cargo fmt --all -- --check

README.md

@@ -9,7 +9,7 @@ One command to inspect and commit your existing Git changes with **GPT-6 Luna at
 codex-commit
 ```
 
-Each run creates a saved Codex CLI session. The Rust executable has no third-party Rust dependencies and supports macOS and Linux.
+Each task run creates a saved Codex CLI session. The Rust executable supports macOS and Linux and uses clap for argument parsing and shell completions.
 
 ## Install
 
@@ -39,18 +39,18 @@ Cargo compiles the published source for your machine and normally installs into
 
 ### Prebuilt macOS downloads
 
-Download the matching archive and `SHA256SUMS` from [v0.2.2](https://github.com/syz51/codex-commit/releases/tag/v0.2.2):
+Download the matching archive and `SHA256SUMS` from [v0.3.0](https://github.com/syz51/codex-commit/releases/tag/v0.3.0):
 
 | Mac | Archive |
 | --- | --- |
-| Apple Silicon (M-series) | [`codex-commit-v0.2.2-aarch64-apple-darwin.tar.gz`](https://github.com/syz51/codex-commit/releases/download/v0.2.2/codex-commit-v0.2.2-aarch64-apple-darwin.tar.gz) |
-| Intel | [`codex-commit-v0.2.2-x86_64-apple-darwin.tar.gz`](https://github.com/syz51/codex-commit/releases/download/v0.2.2/codex-commit-v0.2.2-x86_64-apple-darwin.tar.gz) |
+| Apple Silicon (M-series) | [`codex-commit-v0.3.0-aarch64-apple-darwin.tar.gz`](https://github.com/syz51/codex-commit/releases/download/v0.3.0/codex-commit-v0.3.0-aarch64-apple-darwin.tar.gz) |
+| Intel | [`codex-commit-v0.3.0-x86_64-apple-darwin.tar.gz`](https://github.com/syz51/codex-commit/releases/download/v0.3.0/codex-commit-v0.3.0-x86_64-apple-darwin.tar.gz) |
 
 For example, on Apple Silicon:
 
 ```sh
-release=https://github.com/syz51/codex-commit/releases/download/v0.2.2
-archive=codex-commit-v0.2.2-aarch64-apple-darwin.tar.gz
+release=https://github.com/syz51/codex-commit/releases/download/v0.3.0
+archive=codex-commit-v0.3.0-aarch64-apple-darwin.tar.gz
 curl -fLO "$release/$archive"
 curl -fLO "$release/SHA256SUMS"
 grep "  $archive\$" SHA256SUMS | shasum -a 256 -c -
@@ -69,7 +69,28 @@ cd codex-commit
 cargo install --path . --locked
 ```
 
-Alternatively, `make install` builds a release executable and installs into `~/.local/bin`. `PREFIX` and `DESTDIR` are supported for custom locations and packaging. No Codex or shell configuration is changed.
+Alternatively, `make install` builds a release executable and installs into `~/.local/bin`, with zsh, bash, and fish completions under `~/.local/share`. `PREFIX` and `DESTDIR` are supported for custom locations and packaging. Shell startup files and Codex configuration are not changed.
+
+### Shell completions
+
+Homebrew installs zsh, bash, and fish completions automatically. Zsh must have Homebrew's `share/zsh/site-functions` on its `fpath` before `compinit`; see [Homebrew's shell setup](https://docs.brew.sh/Shell-Completion#configuring-completions-in-zsh).
+
+For Cargo or prebuilt installs, generate zsh completions into a directory on your `fpath`:
+
+```sh
+mkdir -p ~/.local/share/zsh/site-functions
+codex-commit --completions zsh > ~/.local/share/zsh/site-functions/_codex-commit
+```
+
+Add the following to `~/.zshrc` before your existing `compinit` call or shell framework initialization. If neither initializes completions, also add `autoload -Uz compinit && compinit` afterward:
+
+```zsh
+fpath=(~/.local/share/zsh/site-functions $fpath)
+```
+
+Start a new shell after setup. Regenerate the file after upgrading a Cargo or prebuilt install; `make install` regenerates it automatically. Flags include descriptions, and `-C` completes directories.
+
+`codex-commit --completions SHELL` also supports `bash`, `fish`, `powershell`, and `elvish`. It prints the script to stdout without requiring Git, a repository, or Codex. Install generated files using your shell's completion setup.
 
 ## Use
 
@@ -108,7 +129,7 @@ make check  # rustfmt and Clippy
 make test   # Rust workspace unit, integration, terminal, and packaging tests
 ```
 
-Development and release tooling use the pinned Rust 1.99.1 toolchain. Runtime code has no third-party Rust dependencies; tests and the private `xtask` release helper use development dependencies recorded in `Cargo.lock`. Run `cargo test --workspace --locked` directly if you do not use Make.
+Development and release tooling use the pinned Rust 1.99.1 toolchain. Runtime code uses `clap` and `clap_complete`; all dependencies, including tests and the private `xtask` release helper, are recorded in `Cargo.lock`. Run `cargo test --workspace --locked` directly if you do not use Make.
 
 CI tests native Linux, Apple Silicon macOS, and Intel macOS, including installation. Automated Rust tests use a mock Codex executable, real disposable Git repositories, and real terminal signals; they do not call a model or require credentials. Release builds execute and check each native Mac binary before packaging with `cargo xtask`.
 

docs/RELEASING.md

@@ -21,7 +21,7 @@ The tag must match the Cargo version and point to a commit reachable from `main`
 The `Release` workflow checks the exact tagged commit's latest required GitHub Actions check results before any publication. It then:
 
 1. Builds on native Apple Silicon and Intel runners, checks Mach-O architecture, and executes each binary's help and version commands.
-2. Uses the Rust `xtask` helper to package each executable, `LICENSE`, and `README.md`, create `SHA256SUMS`, and upload a GitHub release draft.
+2. Uses the Rust `xtask` helper to package each executable, `LICENSE`, and `README.md`, create `SHA256SUMS`, and upload a GitHub release draft. Each executable generates its own completion scripts with `--completions SHELL`; no separate completion download is required.
 3. Compiles and checks the Cargo package before requesting short-lived crates.io credentials through GitHub OIDC. It publishes the exact tagged source.
 4. Downloads the public crate, checks its registry checksum and embedded Git commit, installs it from crates.io, and runs the Rust CLI integration tests against that installed executable, including terminal cancellation.
 5. Publishes the GitHub release only after Cargo verification succeeds, then verifies release immutability and all asset attestations. GitHub creates release attestations asynchronously, so verification retries for up to 30 attempts with five-second delays and fails if verification still cannot succeed. Publication is serialized across versions, and an older version cannot replace a newer version as Latest.
@@ -42,7 +42,7 @@ The [Homebrew tap](https://github.com/syz51/homebrew-tap) checks for a new publi
 
 The tap verifies the immutable upstream release and its checksums, generates the formula with the released Rust helper, and opens an update PR using a short-lived GitHub App installation token. Normal PR events run native Mac CI. Auto-merge waits for both Apple Silicon and Intel installation, system-Git, style, and audit checks. Branch protection remains enforced; [manually dispatched checks do not qualify as required PR checks](https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks#checks-from-some-workflow-jobs-are-not-evaluated).
 
-After that PR merges, users receive the update through `brew update` and `brew upgrade syz51/tap/codex-commit`. A source push without a new version tag runs CI but does not publish a new package.
+After that PR merges, users receive the update through `brew update` and `brew upgrade syz51/tap/codex-commit`. The formula generates and installs zsh, bash, and fish completions from the installed executable and tests the installed files. A source push without a new version tag runs CI but does not publish a new package.
 
 ## One-time configuration