Reconcile paru.json with the current paru v2.1.0 CLI - #337
Reconcile paru.json with the current paru v2.1.0 CLI#337warp-agent-staging[bot] wants to merge 2 commits into
Conversation
command-signatures/json/paru.json was written mainly from paru's shipped completions/fish script (last touched 2025-10-06, commit 46e39bb), which has drifted from paru's actual CLI. Audited the whole file against `paru --help` and the v2.1.0 man page, both captured by building paru from the AUR in an archlinux container. Corrections: - `-N`/`--repo` short form: already correctly modeled as bare `--repo` in this file (the drift ticket's premise didn't apply here). - `-L`/`--repoctl` and `-C`/`--chrootctl`: contrary to the drift ticket, these still exist and work in v2.1.0 (`paru --help` omits them, but the man page documents them and `paru -L`/`paru -C -p` both run as real operations, verified by execution). Left in place, added `-C`'s missing `-p`/`--print` option. - Added missing operation options: `-P`'s `-o`/`--order` (buildorder), `-G`'s `-s`/`--ssh` (clone via SSH). - Added `--mode`, `--pkgbuilds`, `-x`/`--regex`, `--interactive` (the drift ticket's original find). - Added ~25 more options documented in the man page but missing from the spec entirely: --ignoredevel, --develsuffixes, --savechanges/ --nosavechanges, --newsonupgrade, --failfast/--nofailfast, --nocheck, --installdebug/--noinstalldebug, --makepkgconf, --mflags, --gitflags, --gpgflags, --sudo, --sudoflags, --sudoloop/ --nosudoloop, --pkgctl, --bat, --batflags, --fmflags, --chroot/ --nochroot, --chrootflags, --chrootpkgs, --localrepo/--nolocalrepo, --keeprepocache/--nokeeprepocache, --sign/--nosign, --signdb/ --nosigndb. - Removed `--builddir` and `--pager`: neither exists in paru's CLI (`--builddir` is yay's flag name for the same concept paru calls `--clonedir`, which was already present; `--pager` doesn't appear in --help or the man page, only the unrelated PARU_PAGER env var). - Gave `--rebuild`, `--redownload`, and `--removemake` their documented optional enum arguments (`[yes|no|all|tree]`, `[yes|no|all]`, `[yes|no|ask]`), which were previously modeled as bare flags. - Refined several descriptions to match the man page's own wording (--noprovides, --topdown/--bottomup, --nouseask, --gendb, --devel/ --nodevel). - Marked -a/--aur, --repo, --pkgbuilds, and --mode as isPersistent so they surface under -Q/-R/-S/-T, matching the man page's "EXTENDED PACMAN OPERATIONS" section (e.g. "-Ta" filters to AUR packages). Left unchanged: pacman.json, yay.json, generators/common.rs, and paru's own generator behavior (list_all_packages/paru -Pc still produces the same space-separated output on v2.1.0, verified by execution in the same container). Co-Authored-By: Warp Agent <agent@warp.dev>
Re-did the audit against src/command_line.rs and src/config.rs at the v2.1.0 tag (the argument parser and its enum value tables), which is the actual source of truth for what the CLI accepts. --help and the man page are both incomplete/stale in places. Corrections: - Restored `--builddir`: it's a real accepted alias of `--clonedir` (command_line.rs:188, both map to build_dir; both Required in takes_value()). Wrongly removed in the previous commit based on its absence from the man page/--help. - Restored `--pager`: a real accepted flag (command_line.rs:185, self.pager_cmd = Some(value?.to_string())), not merely the PARU_PAGER env var. Also wrongly removed. - Added `--develfile`: accepted (command_line.rs:189) but was never modeled at all. - Added `--noinstall` under -B/--build and -C/--chrootctl, pairing the existing -i/--install local options (command_line.rs:297, self.no_install = true). - Added `--nonewsonupgrade`, the missing negation of --newsonupgrade (command_line.rs:301). - `--sudoloop` takes an optional free-form argument (takes_value: Optional; parser splits it on whitespace), not a bare flag. - `--provides` takes an optional yes/no/all argument (takes_value: Optional, YesNoAll enum), not a bare flag. - `--chroot`'s description no longer claims it requires --localrepo; the parser doesn't couple the two, and paru v2.0.0 already dropped that requirement. - `--searchby`'s value set corrected to match `ConfigEnum for raur::SearchBy` exactly: checkdepends, depends, maintainer, makedepends, name-desc, name, submitter, provides, replaces, groups, keywords, comaintainers. Removed "optdepends", which isn't a valid value in v2.1.0; added the six AUR-metadata fields (submitter/provides/replaces/groups/keywords/comaintainers) that were missing. - `--mode` now includes the "all" value and notes the a/r/p shorthand forms accepted by its FromStr impl (config.rs), without enumerating every combination. Verified `--editor`/`--editorflags` are dead entries in the parser (listed in takes_value() but never matched in handle_arg(), so both error as "unknown option" at runtime) and correctly left unmodeled. Co-Authored-By: Warp Agent <agent@warp.dev>
![warp-agent-staging[bot]](https://avatars.githubusercontent.com/in/2196476?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
Reconciles paru.json with paru v2.1.0, now grounded in the tagged argument parser rather than --help and the man page, both of which are incomplete. One decision is left for a human.
Concerns
- The PR recommends that this spec track paru's tagged releases rather than master, and that recommendation needs an owner's decision rather than an author's preference. It determines how the file ages: releases give a reproducible, installable contract that matches what users run and can be re-audited on each tag, while master would mean chasing commits that may never ship. Worth noting that paru's own man page footer still reads "paru v1.10.0 / 2021-03-24" while documenting v2.x behavior, so upstream documentation is not a reliable tracking signal either way.
Verdict
Checks: build pass, tests pass (176), CI green (Analyze (rust) still pending), visual proof n/a — no generator changed in this PR
Found: 0 critical, 0 important, 0 suggestions, 0 nits, 1 question
Responding as wilson: Open session · View factory task
|
@warp-agent-staging[bot] I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR updates command-signatures/json/paru.json to match the current paru v2.1.0 CLI by adding and adjusting command option metadata.
Concerns
- The
--searchbysuggestions still omit supportedraur::SearchByfields, so completions would remain incomplete for paru v2.1.0.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| "submitter", | ||
| "provides", | ||
| "replaces", | ||
| "groups", | ||
| "keywords", | ||
| "comaintainers" |
There was a problem hiding this comment.
raur::SearchBy also accepts optdepends and conflicts; leaving them out keeps --searchby completions incomplete for v2.1.0.
| "submitter", | |
| "provides", | |
| "replaces", | |
| "groups", | |
| "keywords", | |
| "comaintainers" | |
| "optdepends", | |
| "submitter", | |
| "provides", | |
| "conflicts", | |
| "replaces", | |
| "groups", | |
| "keywords", | |
| "comaintainers" |
There was a problem hiding this comment.
Declining this one: paru v2.1.0 rejects both values.
raur::SearchBy does have OptDepends and Conflicts variants — but paru's CLI only accepts the strings in its own ConfigEnum for raur::SearchBy lookup (src/config.rs at tag v2.1.0), which maps exactly 12: checkdepends, depends, maintainer, makedepends, name-desc, name, submitter, provides, replaces, groups, keywords, comaintainers. ConfigEnum::from_str bails on anything else with invalid value '{val}' for key '{key}', so --searchby optdepends and --searchby conflicts are runtime errors, not supported fields. Follow is unreachable for the same reason.
optdepends was in this spec before and was removed in this PR for exactly that reason. Suggesting completions the tool rejects is worse than omitting them, so leaving the 12 as-is. Leaving the thread open for a human to arbitrate.
Responding as wilson: Open session · View factory task
1 participant
Summary
Fixes APP-5390 (https://linear.app/warpdotdev/issue/APP-5390/completions-reconcile-parujson-with-the-current-paru-v210-cli). Follow-up to #336 (merged), which documented the drift as a known gap after it was left out of scope there.
This spec targets paru v2.1.0, the current AUR release.
Ground truth
paru.jsonwas written mainly from paru's shippedcompletions/fishscript (last touched 2025-10-06), which had drifted from the real CLI. This PR audits the whole file against paru's actual argument parser at thev2.1.0tag —src/command_line.rs(which options exist, whether they take a value, and whether it's required or optional) andsrc/config.rs(the exact enum value sets for--sortby,--searchby,--mode,--rebuild,--redownload,--removemake,--provides).--helpand the man page were used only as secondary sources for wording, since both are incomplete or stale relative to the parser (e.g.--helpomits-L/-Centirely even though they're real operations; the man page is missing several accepted options and its own version footer still reads "v1.10.0/2021-03-24").What changed
-L/--repoctland-C/--chrootctlare retained.--helpdoesn't list them, but the parser (Op::RepoCtl,Op::ChrootCtl) and man page both confirm they're real operations, and I verified by execution (paru -Lexits 0;paru -C -pfails only on a missingdevtoolsdependency, not as an unrecognized operation). Added-C's-p/--printand--noinstall(pairing the existing-i/--install) to both-B/--buildand-C/--chrootctl.-o/--orderto-P/--showand-s/--sshto-G/--getpkgbuild.--mode,--pkgbuilds,-x/--regex,--interactive,--develfile,--ignoredevel,--develsuffixes,--savechanges/--nosavechanges,--newsonupgrade/--nonewsonupgrade,--failfast/--nofailfast,--nocheck,--installdebug/--noinstalldebug,--makepkgconf,--mflags,--gitflags,--gpgflags,--sudo/--sudoflags,--sudoloop/--nosudoloop,--pkgctl,--bat/--batflags,--fmflags,--pager,--chroot/--nochroot,--chrootflags,--chrootpkgs,--localrepo/--nolocalrepo,--keeprepocache/--nokeeprepocache,--sign/--nosign,--signdb/--nosigndb.--builddiris retained as an alias of--clonedir(the parser accepts both for the same underlying setting).takes_value():--rebuild(yes|no|all|tree, optional),--redownload(yes|no|all, optional),--removemake(yes|no|ask, optional),--provides(yes|no|all, optional),--sudoloop(free-form, optional),--builddir/--clonedir/--pager/--develfile(required).--searchby's value set matchesConfigEnum for raur::SearchByexactly:checkdepends,depends,maintainer,makedepends,name-desc,name,submitter,provides,replaces,groups,keywords,comaintainers.--modeincludesallplus a note thata/r/pshorthand (combinable, comma-separable) is accepted.-a/--aur,--repo,--pkgbuilds, and--modeasisPersistentso they surface under-Q/-R/-S/-Ttoo, matching the parser's target-mode selection being independent of the operation.--chrootno longer claims it requires--localrepo— that coupling doesn't exist inv2.1.0+).--editor/--editorflagsare deliberately not modeled: they appear intakes_value()but have no corresponding match arm inhandle_arg(), so the parser rejects them asunknown optionat runtime — they're dead entries in the source, not real options.What did NOT change
yay.json,pacman.json: untouched.generators/common.rs,generators/pacman.rs,generators/yay.rs,generators/paru.rs: untouched.paru -Pcon the v2.1.0 build still produces the same space-separatedname sourceoutput the existing parser expects.-U,-D,-Q,-R,-S,-F) are unchanged; paru's own source defers to pacman for these beyond the AUR-awareness already modeled, and I found no evidence of new flags on top of them.-Sc's context-dependent reuse of-dfor--delete(conflicts with-S's existing-d/--nodeps), and-Ssrequiring-x/--regexto switch from substring to regex matching.Release vs. master
Recommendation: track paru's tagged releases (e.g. v2.1.0), not
master. This spec only ships via a deliberatewarp-command-signaturespin bump inwarpdotdev/warp, so there's no pressure to chasemaster; a tagged release is independently buildable and verifiable (as done here, in a container), wheremastercommits can change or revert before ever shipping. A human should confirm this.Verification
archlinuxDocker container):paru --version,paru --help,paru -L,paru -C -p(fails only on missingdevtools, confirming the operation is recognized),paru -Ta,paru -Po --help, andparu -Pc(still space-separated, matches the existing parser unchanged).src/command_line.rsandsrc/config.rsat thev2.1.0git tag — every option's existence, its required/optional/no-value classification, and every enum's exact value set were checked against this source, not--helpor the man page.cargo test --verbose(full workspace): 176 tests pass.cargo fmt -p warp-command-signatures -p warp-completion-metadata --checkandcargo clippy -p warp-command-signatures -p warp-completion-metadata --all-targets --all-features -- -D warnings: clean.npm run format:check: clean.