feat: added tool descriptions (jdx#3571)

build.rs

@@ -107,7 +107,7 @@ fn codegen_registry() {
         let rt = format!(
             r#"RegistryTool{{short: "{short}", description: {description}, backends: vec!["{backends}"], aliases: &[{aliases}], test: &{test}, os: &[{os}], depends: &[{depends}], idiomatic_files: &[{idiomatic_files}]}}"#,
             description = description
-                .map(|d| format!("Some(\"{}\")", d))
+                .map(|d| format!("Some(r###\"{}\"###)", d))
                 .unwrap_or("None".to_string()),
             backends = fulls.join("\", \""),
             aliases = aliases

docs/cli/tool.md

@@ -21,6 +21,10 @@ Output in JSON format
 
 Only show backend field
 
+### `--description`
+
+Only show description field
+
 ### `--installed`
 
 Only show installed versions

mise.lock

@@ -39,6 +39,10 @@ backend = "cargo:cargo-show"
 version = "2.7.0"
 backend = "cargo:git-cliff"
 
+[tools."cargo:toml-cli"]
+version = "0.2.3"
+backend = "cargo:toml-cli"
+
 [tools."cargo:usage-cli"]
 version = "1.6.0"
 backend = "cargo:usage-cli"

mise.toml

@@ -12,6 +12,7 @@ cargo-binstall = "1.10.15"
 "cargo:cargo-insta" = "latest"
 "cargo:cargo-show" = { version = "latest", os = ["linux", "macos"] }
 "cargo:git-cliff" = "latest"
+"cargo:toml-cli" = "latest"
 "cargo:usage-cli" = { version = "latest", os = ["linux", "macos"] }
 cosign = "latest"
 "jq" = "latest"

mise.usage.kdl

@@ -1441,6 +1441,7 @@ cmd "tool" help="Gets information about a tool" {
 "
     flag "-J --json" help="Output in JSON format"
     flag "--backend" help="Only show backend field"
+    flag "--description" help="Only show description field"
     flag "--installed" help="Only show installed versions"
     flag "--active" help="Only show active versions"
     flag "--requested" help="Only show requested versions"

registry.toml

@@ -145,6 +145,7 @@ calendarsync.backends = ["ubi:inovex/CalendarSync", "asdf:FeryET/asdf-calendarsy
 calendarsync.test = ["CalendarSync --version", "Version: {{version}}"]
 calicoctl.backends = ["aqua:projectcalico/calico/calicoctl", "asdf:TheCubicleJockey/asdf-calicoctl"]
 cargo-binstall.backends = ["aqua:cargo-bins/cargo-binstall", 'ubi:cargo-bins/cargo-binstall[tag_regex=^\\d\\.]', "cargo:cargo-binstall"]
+cargo-binstall.description = "Binary installation for rust projects"
 # cargo-binstall.test = ["cargo binstall -V", "{{version}}"] # flaky on windows CI
 cargo-insta.backends = ["ubi:mitsuhiko/insta"]
 cargo-make.backends = ["ubi:sagiegurari/cargo-make", "asdf:mise-plugins/asdf-cargo-make"]
@@ -230,6 +231,7 @@ coredns.backends = ["ubi:coredns/coredns", "asdf:s3than/asdf-coredns"]
 coredns.test = ["coredns --version", "CoreDNS-{{version}}"]
 cosign.backends = ["aqua:sigstore/cosign", "asdf:https://gitlab.com/wt0f/asdf-cosign"]
 cosign.test = ["cosign version", "v{{version}}"]
+cosign.description = "Container Signing"
 coursier.backends = ["ubi:coursier/coursier[exe=cs]", "asdf:jiahuili430/asdf-coursier"]
 # ls-remote not available for aqua
 cowsay.backends = ["npm:cowsay"]
@@ -385,6 +387,7 @@ gitconfig.backends = ["ubi:0ghny/gitconfig", "asdf:0ghny/asdf-gitconfig"]
 gitconfig.test = ["gitconfig --version", "gitconfig version {{version}}"]
 github-cli.aliases = ["gh"]
 github-cli.backends = ["aqua:cli/cli", "ubi:cli/cli[exe=gh]", "asdf:bartlomiejdanek/asdf-github-cli"]
+github-cli.description = "GitHub’s official command line tool"
 github-cli.test = ["gh --version", "gh version {{version}}"]
 github-markdown-toc.backends = ["aqua:ekalinin/github-markdown-toc", "asdf:skyzyx/asdf-github-markdown-toc"]
 gitleaks.backends = ["aqua:gitleaks/gitleaks", "asdf:jmcvetta/asdf-gitleaks"]
@@ -507,6 +510,7 @@ jmespath.backends = ["asdf:skyzyx/asdf-jmespath"]
 jmeter.backends = ["asdf:comdotlinux/asdf-jmeter"]
 jnv.backends = ["aqua:ynqa/jnv", "asdf:raimon49/asdf-jnv"]
 jq.backends = ["aqua:jqlang/jq", "asdf:mise-plugins/asdf-jq"]
+jq.description = "Command-line JSON processor"
 jqp.backends = ["aqua:noahgorstein/jqp", "asdf:https://gitlab.com/wt0f/asdf-jqp"]
 jreleaser.backends = ["aqua:jreleaser/jreleaser", "asdf:joschi/asdf-jreleaser"]
 jsonnet.backends = ["asdf:Banno/asdf-jsonnet"]
@@ -731,6 +735,7 @@ pipenv.depends = ["python"]
 pipx.backends = ["asdf:yozachar/asdf-pipx"]
 pipx.depends = ["python"]
 pitchfork.backends = ["ubi:jdx/pitchfork"]
+pitchfork.description = "Daemon manager"
 pitchfork.test = ["pitchfork --version", "pitchfork {{version}}"]
 pivnet.backends = ["aqua:pivotal-cf/pivnet-cli", "asdf:vmware-tanzu/tanzu-plug-in-for-asdf"]
 pivnet.test = ["pivnet version", ""] # version returns "dev" on windows
@@ -749,6 +754,7 @@ powerline-go.backends = ["asdf:dex4er/asdf-powerline-go"]
 powerpipe.backends = ["aqua:turbot/powerpipe", "asdf:jc00ke/asdf-powerpipe"]
 powershell-core.backends = ["asdf:daveneeley/asdf-powershell-core"]
 pre-commit.backends = ["aqua:pre-commit/pre-commit", "asdf:jonathanmorley/asdf-pre-commit"]
+pre-commit.description = "A framework for managing and maintaining multi-language pre-commit hooks"
 promtool.backends = ["asdf:asdf-community/asdf-promtool"]
 protobuf.backends = ["vfox:ahai-code/vfox-protobuf"]
 protoc.backends = ["aqua:protocolbuffers/protobuf/protoc", "asdf:paxosglobal/asdf-protoc"]
@@ -795,6 +801,7 @@ riff.backends = ["asdf:abinet/asdf-riff"]
 ripgrep.aliases = ["rg"]
 ripgrep.backends = ["aqua:BurntSushi/ripgrep", "ubi:BurntSushi/ripgrep[exe=rg]", "asdf:https://gitlab.com/wt0f/asdf-ripgrep"]
 ripgrep.test = ["rg --version", "ripgrep {{version}}"]
+ripgrep.description = "ripgrep recursively searches directories for a regex pattern while respecting your gitignore"
 ripgrep-all.backends = ["aqua:phiresky/ripgrep-all"]
 ripgrep-all.test = ["rga --version", "ripgrep-all {{version}}"]
 ripsecret.backends = ["aqua:sirwart/ripsecrets", "asdf:https://github.com/boris-smidt-klarrio/asdf-ripsecrets"]
@@ -835,6 +842,7 @@ setup-envtest.backends = ["asdf:pmalek/mise-setup-envtest"]
 shell2http.backends = ["aqua:msoap/shell2http", "asdf:ORCID/asdf-shell2http"]
 shellcheck.backends = ["aqua:koalaman/shellcheck", "ubi:koalaman/shellcheck", "asdf:luizm/asdf-shellcheck"]
 shellcheck.os = ["linux", "macos"]
+shellcheck.description = "ShellCheck, a static analysis tool for shell scripts"
 shellspec.backends = ["aqua:shellspec/shellspec", "asdf:poikilotherm/asdf-shellspec"]
 shfmt.backends = ["aqua:mvdan/sh", "asdf:luizm/asdf-shfmt"]
 shfmt.os = ["linux", "macos"]
@@ -882,6 +890,7 @@ stylua.test = ["stylua --version", "stylua {{version}}"]
 sui.backends = ["asdf:placeholder-soft/asdf-sui"]
 superfile.backends = ["aqua:yorukot/superfile"]
 superfile.test = ["spf --version", "superfile version v{{version}}"]
+superfile.description = "Pretty fancy and modern terminal file manager"
 sver.backends = ["aqua:mitoma/sver", "asdf:robzr/asdf-sver"]
 svu.backends = ["aqua:caarlos0/svu", "asdf:asdf-community/asdf-svu"]
 swag.backends = ["aqua:swaggo/swag", "asdf:behoof4mind/asdf-swag"]

src/aqua/aqua_registry.rs

@@ -2,7 +2,7 @@ use crate::aqua::aqua_template;
 use crate::backend::aqua;
 use crate::backend::aqua::{arch, os};
 use crate::config::SETTINGS;
-use crate::duration::DAILY;
+use crate::duration::{DAILY, WEEKLY};
 use crate::git::Git;
 use crate::{dirs, file, hashmap, http};
 use expr::{Context, Parser, Program, Value};
@@ -208,7 +208,7 @@ impl AquaRegistry {
 }
 
 fn fetch_latest_repo(repo: &Git) -> Result<()> {
-    if file::modified_duration(&repo.dir)? < DAILY {
+    if file::modified_duration(&repo.dir)? < WEEKLY {
         return Ok(());
     }
     info!("updating aqua registry repo");

src/backend/aqua.rs

@@ -31,6 +31,13 @@ impl Backend for AquaBackend {
         BackendType::Aqua
     }
 
+    fn description(&self) -> Option<String> {
+        AQUA_REGISTRY
+            .package(&self.ba.tool_name)
+            .ok()
+            .and_then(|p| p.description.clone())
+    }
+
     fn ba(&self) -> &BackendArg {
         &self.ba
     }
@@ -79,11 +86,7 @@ impl Backend for AquaBackend {
         }
     }
 
-    fn install_version_(
-        &self,
-        ctx: &InstallContext,
-        mut tv: ToolVersion,
-    ) -> eyre::Result<ToolVersion> {
+    fn install_version_(&self, ctx: &InstallContext, mut tv: ToolVersion) -> Result<ToolVersion> {
         let mut v = format!("v{}", tv.version);
         let pkg = AQUA_REGISTRY.package_with_version(&self.id, &v)?;
         if let Some(prefix) = &pkg.version_prefix {

src/backend/mod.rs

@@ -154,6 +154,9 @@ pub trait Backend: Debug + Send + Sync {
         BackendType::Core
     }
     fn ba(&self) -> &BackendArg;
+    fn description(&self) -> Option<String> {
+        None
+    }
     fn get_plugin_type(&self) -> Option<PluginType> {
         None
     }

src/cli/tool.rs

@@ -28,6 +28,10 @@ pub struct ToolInfoFilter {
     #[clap(long)]
     backend_: bool,
 
+    /// Only show description field
+    #[clap(long)]
+    description: bool,
+
     /// Only show installed versions
     #[clap(long)]
     installed: bool,
@@ -56,8 +60,10 @@ impl Tool {
         let tvl = ts.versions.get(&self.backend);
         let tv = tvl.map(|tvl| tvl.versions.first().unwrap());
         let ba = tv.map(|tv| tv.ba()).unwrap_or_else(|| &self.backend);
+        let backend = ba.backend().ok();
         let info = ToolInfo {
             backend: ba.full(),
+            description: backend.and_then(|b| b.description()),
             installed_versions: ts
                 .list_installed_versions()?
                 .into_iter()
@@ -90,6 +96,8 @@ impl Tool {
     fn output_json(&self, info: ToolInfo) -> Result<()> {
         if self.filter.backend_ {
             miseprintln!("{}", serde_json::to_string_pretty(&info.backend)?);
+        } else if self.filter.description {
+            miseprintln!("{}", serde_json::to_string_pretty(&info.description)?);
         } else if self.filter.installed {
             miseprintln!(
                 "{}",
@@ -115,6 +123,12 @@ impl Tool {
     fn output_user(&self, info: ToolInfo) -> Result<()> {
         if self.filter.backend_ {
             miseprintln!("{}", info.backend);
+        } else if self.filter.description {
+            if let Some(description) = info.description {
+                miseprintln!("{}", description);
+            } else {
+                miseprintln!("[none]");
+            }
         } else if self.filter.installed {
             miseprintln!("{}", info.installed_versions.join(" "));
         } else if self.filter.active {
@@ -146,6 +160,9 @@ impl Tool {
         } else {
             let mut table = vec![];
             table.push(("Backend:", info.backend));
+            if let Some(description) = info.description {
+                table.push(("Description:", description));
+            }
             table.push(("Installed Versions:", info.installed_versions.join(" ")));
             if let Some(active_versions) = info.active_versions {
                 table.push(("Active Version:", active_versions.join(" ")));
@@ -179,6 +196,7 @@ impl Tool {
 #[derive(Serialize)]
 struct ToolInfo {
     backend: String,
+    description: Option<String>,
     installed_versions: Vec<String>,
     requested_versions: Option<Vec<String>>,
     active_versions: Option<Vec<String>>,

src/cli/use.rs

@@ -256,7 +256,7 @@ impl Use {
             .description("Select a tasks to run")
             .filtering(true)
             .filterable(true);
-        for rt in REGISTRY.values() {
+        for rt in REGISTRY.values().unique_by(|r| r.short) {
             if let Some(backend) = rt.backends().first() {
                 // TODO: populate registry with descriptions from aqua and other sources
                 // TODO: use the backend from the lockfile if available

src/duration.rs

@@ -2,4 +2,4 @@ pub use std::time::Duration;
 
 pub const HOURLY: Duration = Duration::from_secs(60 * 60);
 pub const DAILY: Duration = Duration::from_secs(60 * 60 * 24);
-// pub const WEEKLY: Duration = Duration::from_secs(60 * 60 * 24 * 7);
+pub const WEEKLY: Duration = Duration::from_secs(60 * 60 * 24 * 7);

tasks.md

@@ -270,6 +270,10 @@ run end-to-end tests
 
 run unit tests
 
+## `update-descriptions`
+
+- **Usage**: `update-descriptions`
+
 ## `xxx`
 
 - **Usage**: `xxx`

xtasks/fig/src/mise.ts

@@ -2745,6 +2745,13 @@ const completionSpec: Fig.Spec = {
                     "description": "Only show backend field",
                     "isRepeatable": false
                 },
+                {
+                    "name": [
+                        "--description"
+                    ],
+                    "description": "Only show description field",
+                    "isRepeatable": false
+                },
                 {
                     "name": [
                         "--installed"

xtasks/update-descriptions

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euxo pipefail
+
+for tool in $(mise registry | awk '{print $1}'); do
+  description="$(mise tool --description "$tool")"
+  if [ "$description" != "[none]" ]; then
+    toml set registry.toml "tools.$tool.description" "$description" > registry.toml.tmp
+    mv registry.toml.tmp registry.toml
+  fi
+done