diff --git a/.yarn/versions/8e4c715c.yml b/.yarn/versions/8e4c715c.yml new file mode 100644 index 00000000000..1f2a5d9c201 --- /dev/null +++ b/.yarn/versions/8e4c715c.yml @@ -0,0 +1,9 @@ +releases: + "@moonrepo/cli": patch + "@moonrepo/core-linux-arm64-gnu": patch + "@moonrepo/core-linux-arm64-musl": patch + "@moonrepo/core-linux-x64-gnu": patch + "@moonrepo/core-linux-x64-musl": patch + "@moonrepo/core-macos-arm64": patch + "@moonrepo/core-macos-x64": patch + "@moonrepo/core-windows-x64-msvc": patch diff --git a/Cargo.lock b/Cargo.lock index 2fb70193564..5670687fe4b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4562,9 +4562,9 @@ dependencies = [ [[package]] name = "proto_core" -version = "0.22.5" +version = "0.23.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7d9a5d9c3dd0b60d7c1edaf3b034aa8df9a5e8fd80274f267877a78adf974e3e" +checksum = "63710d7e61a6d1113dee8247dcf7feb046185e61a902b3ef1f10966540603d16" dependencies = [ "cached", "extism", @@ -4593,9 +4593,9 @@ dependencies = [ [[package]] name = "proto_pdk_api" -version = "0.10.3" +version = "0.10.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "21bbe68a00cf53fea3cede44415daac87e994024bc9c67138c1870c17d7fbef7" +checksum = "cde8df4fbd8eeea007157df37376c24bf1cde6bffb3638aeefa95583911b15a5" dependencies = [ "anyhow", "semver", diff --git a/Cargo.toml b/Cargo.toml index 8f8e023a3bb..87a09763695 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -38,7 +38,7 @@ pathdiff = "0.2.1" petgraph = { version = "0.6.4", default-features = false, features = [ "serde-1", ] } -proto_core = "0.22.5" +proto_core = "0.23.1" relative-path = { version = "1.9.0", features = ["serde"] } regex = "1.10.2" reqwest = { version = "0.11.22", default-features = false, features = [ diff --git a/nextgen/config/src/toolchain/node_config.rs b/nextgen/config/src/toolchain/node_config.rs index 17211a39a2f..299e3b9a6cc 100644 --- a/nextgen/config/src/toolchain/node_config.rs +++ b/nextgen/config/src/toolchain/node_config.rs @@ -195,12 +195,6 @@ impl NodeConfig { } self.inherit_proto_yarn(proto_tools)?; - - if let Some(yarn) = &mut self.yarn { - yarn.plugin = Some(PluginLocator::SourceUrl { - url: "https://github.com/moonrepo/node-plugin/releases/download/v0.5.1/node_depman_plugin.wasm".into() - }); - } } }; @@ -225,7 +219,7 @@ impl NodeConfig { if self.plugin.is_none() { self.plugin = Some(PluginLocator::SourceUrl { - url: "https://github.com/moonrepo/node-plugin/releases/download/v0.5.0/node_plugin.wasm".into() + url: "https://github.com/moonrepo/node-plugin/releases/download/v0.5.2/node_plugin.wasm".into() }); } diff --git a/nextgen/config/tests/toolchain_config_test.rs b/nextgen/config/tests/toolchain_config_test.rs index 6ce18d6df0a..588270e90ec 100644 --- a/nextgen/config/tests/toolchain_config_test.rs +++ b/nextgen/config/tests/toolchain_config_test.rs @@ -221,7 +221,7 @@ node: assert_eq!( config.node.unwrap().plugin.unwrap(), PluginLocator::SourceUrl { - url: "https://github.com/moonrepo/node-plugin/releases/download/v0.5.0/node_plugin.wasm".into() + url: "https://github.com/moonrepo/node-plugin/releases/download/v0.5.2/node_plugin.wasm".into() } ); } @@ -322,7 +322,7 @@ node: assert_eq!( config.node.unwrap().npm.plugin.unwrap(), PluginLocator::SourceUrl { - url: "https://github.com/moonrepo/node-plugin/releases/download/v0.5.0/node_depman_plugin.wasm".into() + url: "https://github.com/moonrepo/node-plugin/releases/download/v0.5.2/node_depman_plugin.wasm".into() } ); } @@ -413,7 +413,7 @@ node: assert_eq!( config.node.unwrap().pnpm.unwrap().plugin.unwrap(), PluginLocator::SourceUrl { - url: "https://github.com/moonrepo/node-plugin/releases/download/v0.5.0/node_depman_plugin.wasm".into() + url: "https://github.com/moonrepo/node-plugin/releases/download/v0.5.2/node_depman_plugin.wasm".into() } ); } @@ -437,7 +437,7 @@ node: assert_eq!( config.node.unwrap().pnpm.unwrap().plugin.unwrap(), PluginLocator::SourceUrl { - url: "https://github.com/moonrepo/node-plugin/releases/download/v0.5.0/node_depman_plugin.wasm".into() + url: "https://github.com/moonrepo/node-plugin/releases/download/v0.5.2/node_depman_plugin.wasm".into() } ); } @@ -537,7 +537,7 @@ node: assert_eq!( config.node.unwrap().yarn.unwrap().plugin.unwrap(), PluginLocator::SourceUrl { - url: "https://github.com/moonrepo/node-plugin/releases/download/v0.5.1/node_depman_plugin.wasm".into() + url: "https://github.com/moonrepo/node-plugin/releases/download/v0.5.2/node_depman_plugin.wasm".into() } ); } @@ -561,7 +561,7 @@ node: assert_eq!( config.node.unwrap().yarn.unwrap().plugin.unwrap(), PluginLocator::SourceUrl { - url: "https://github.com/moonrepo/node-plugin/releases/download/v0.5.1/node_depman_plugin.wasm".into() + url: "https://github.com/moonrepo/node-plugin/releases/download/v0.5.2/node_depman_plugin.wasm".into() } ); } diff --git a/website/blog/2023-07-21_proto-v0.13.mdx b/website/blog/2023-07-21_proto-v0.13.mdx index 10998717fa6..c8316918052 100644 --- a/website/blog/2023-07-21_proto-v0.13.mdx +++ b/website/blog/2023-07-21_proto-v0.13.mdx @@ -54,7 +54,7 @@ bun = "github:moonrepo/bun-plugin" With the advent of plugins, we thought it would be nice to know which plugins are actually configured and in use, without having to manually search config files across the file system, and as -such, have added a new [`proto plugins`](/docs/proto/commands/plugins) command. +such, have added a new [`proto plugins`](/docs/proto/commands/tool/list-plugins) command. This command is simple. It will list all plugins that are currently configured for the current project, by loading all `.prototools` files up the tree, and loading the user @@ -75,7 +75,7 @@ go - Go Tag: latest ``` -[Learn more about this new command!](/docs/proto/commands/plugins) +[Learn more about this new command!](/docs/proto/commands/tool/list-plugins) ## Other changes diff --git a/website/blog/2023-09-04_proto-v0.16.mdx b/website/blog/2023-09-04_proto-v0.16.mdx index 96d900d29c0..fc66786741c 100644 --- a/website/blog/2023-09-04_proto-v0.16.mdx +++ b/website/blog/2023-09-04_proto-v0.16.mdx @@ -13,8 +13,8 @@ This release adds functionality for managing plugins and purging the proto store Now that proto has fully embraced a plugin based architecture, we thought it'd be nice to support the management of these plugins through the CLI. This release adds two new commands: -[`proto add-plugin`](/docs/proto/commands/add-plugin) and -[`proto remove-plugin`](/docs/proto/commands/remove-plugin). +[`proto add-plugin`](/docs/proto/commands/tool/add) and +[`proto remove-plugin`](/docs/proto/commands/tool/remove). Adding a plugin requires a unique ID and what we call a locator, which is a string that dictates where to locate and download the plugin from. Here's an example for Node.js, but this isn't diff --git a/website/blog/2023-09-18_proto-v0.18.mdx b/website/blog/2023-09-18_proto-v0.18.mdx index 84fc74a1d11..422b40b01e2 100644 --- a/website/blog/2023-09-18_proto-v0.18.mdx +++ b/website/blog/2023-09-18_proto-v0.18.mdx @@ -14,8 +14,8 @@ Today we've got a small release that includes some helpful features. Are you curious what tools you have installed? And more specifically, which versions? What about configured aliases? Until now, you had to manually check the `~/.proto/tools` directory for this -information, but now, you can simply run [`proto tools`](/docs/proto/commands/tools) to get a list -of all installed tools. +information, but now, you can simply run [`proto tools`](/docs/proto/commands/tool/list) to get a +list of all installed tools. This command will list all tools that have been installed, along with their installed versions, relevant timestamps, available aliases, and store location. diff --git a/website/blog/2023-11-16_proto-v0.23.mdx b/website/blog/2023-11-16_proto-v0.23.mdx new file mode 100644 index 00000000000..9a63e79fa18 --- /dev/null +++ b/website/blog/2023-11-16_proto-v0.23.mdx @@ -0,0 +1,81 @@ +--- +slug: proto-v0.23 +title: proto v0.23 - New detection strategy, tool commands, and more +authors: [milesj] +tags: [proto] +image: ./img/proto/v0.23.png +--- + +With this release, we've reorganized our commands, improved version detection, and Windows support. + + + +## New `detect-strategy` setting + +Up until now, when proto would attempt to detect a version, it would use a version from the closest +`.prototools` file, or tool specific file (`package.json`, `.nvmrc`, etc), which ever matched first. +For the most part, this works great, but what if you wanted `.prototools` to take precedence over +other files, even if found in a higher parent directory? You unfortunately couldn't. + +To support this new flow, we're introducing a new +[`~/.proto/config.toml`](/docs/proto/config#user-configuration) setting called +[`detect-strategy`](/docs/proto/config#detect-strategy). This setting supports the following values, +with more possibly in the future! + +- `first-available` (default) - Will use the first available version that is found. Either from + `.prototools` or a tool specific file. +- `prefer-prototools` - Prefer a `.prototools` version, even if found in a parent directory. If none + found, falls back to tool specific file. + +```toml title="~/.proto/config.toml" +detect-strategy = "prefer-prototools" +``` + +## New `proto tool` command group (breaking) + +Our CLI surface area has been growing and we felt it was time to start grouping commands, starting +with the new [`proto tool`](/docs/proto/commands/tool) command. This command will contain "not used +very often" subcommands in relation to tools and their plugins, primarily for managing plugins, and +viewing tool information and inventory. As such, we've deprecated and moved the following top-level +commands: + +- Moved `proto add-plugin` to `proto tool add`. +- Moved `proto remove-plugin` to `proto tool remove`. +- Moved `proto plugins` to `proto tool list-plugins`. +- Moved `proto tools` to `proto tool list`. + +## New `proto tool info` command + +Continuing with the changes above, we're also introducing a new command, +[`proto tool info`](/docs/proto/commands/tool/info), which displays detailed information about a +tool and its backing plugin. For example: + +``` +$ proto tool info node + +node - Node.js + +Inventory + Store: ~/.proto/tools/node + Executable: ~/.proto/tools/node/20.0.0/bin/node + Globals directory: ~/.proto/tools/node/globals/bin + Binaries: + - ~/.proto/bin/node (primary) + Shims: + - ~/.proto/shims/node (primary) + +Plugin + Version: 0.5.2 + Source: https://github.com/moonrepo/node-plugin/releases/download/v0.5.2/node_plugin.wasm +``` + +> This command also supports JSON output via `--json`. + +## Other changes + +View the [official release](https://github.com/moonrepo/proto/releases/tag/v0.23.0) for a full list +of changes. + +- Added support to plugins to ignore certain paths when detecting a version. +- Updated Windows to create 3 shim files for each tool: `.cmd` (cmd.exe), `.ps1` (powershell), and + no extension (bash). diff --git a/website/blog/img/proto/v0.23.png b/website/blog/img/proto/v0.23.png new file mode 100644 index 00000000000..5f76dd95f21 Binary files /dev/null and b/website/blog/img/proto/v0.23.png differ diff --git a/website/docs/install.mdx b/website/docs/install.mdx index d3bf821c294..a2b7db75b16 100644 --- a/website/docs/install.mdx +++ b/website/docs/install.mdx @@ -25,7 +25,7 @@ moon can be installed and managed in [proto's toolchain](/proto) using a TOML pl install moon to `~/.proto/tools/moon` and make the binary available at `~/.proto/bin`. ```shell -proto add-plugin moon "source:https://raw.githubusercontent.com/moonrepo/moon/master/proto-plugin.toml" +proto tool add moon "source:https://raw.githubusercontent.com/moonrepo/moon/master/proto-plugin.toml" proto install moon ``` diff --git a/website/docs/proto/commands/add-plugin.mdx b/website/docs/proto/commands/add-plugin.mdx deleted file mode 100644 index 258665fc33e..00000000000 --- a/website/docs/proto/commands/add-plugin.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: add-plugin ---- - -import VersionLabel from '@site/src/components/Docs/VersionLabel'; - - - -The `proto add-plugin ` (or `proto ap`) command will add the provided plugin ID and -locator string to the `[plugins]` section of the local (`.prototools`) or global -(`~/.proto/config.toml`) config file. - -```shell -$ proto add-plugin node source:https://github.com/moonrepo/node-plugin/releases/latest/download/node_plugin.wasm -``` - -> Learn more about [plugin locator strings](../plugins#enabling-plugins). - -### Arguments - -- `` - ID of the plugin. -- `` - How to locate the plugin. - -### Options - -- `--global` - Add to the global config instead of local. diff --git a/website/docs/proto/commands/bin.mdx b/website/docs/proto/commands/bin.mdx index 5db6ac781a7..ca7743a01a5 100644 --- a/website/docs/proto/commands/bin.mdx +++ b/website/docs/proto/commands/bin.mdx @@ -19,4 +19,5 @@ $ proto bin node 16.10.0 ### Options -- `--shim` - When applicable, return an absolute path to a tool's local shim file. +- `--bin` - When applicable, return the `~/.proto/bin` path. +- `--shim` - When applicable, return the `~/.proto/shims` path. diff --git a/website/docs/proto/commands/remove-plugin.mdx b/website/docs/proto/commands/remove-plugin.mdx deleted file mode 100644 index f496bec2324..00000000000 --- a/website/docs/proto/commands/remove-plugin.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: remove-plugin ---- - -import VersionLabel from '@site/src/components/Docs/VersionLabel'; - - - -The `proto remove-plugin ` (or `proto rp`) command will remove the provided plugin ID from to -the `[plugins]` section of the local (`.prototools`) or global (`~/.proto/config.toml`) config file. - -```shell -$ proto remove-plugin node -``` - -> Built-in plugins _cannot_ be removed! - -### Arguments - -- `` - ID of the plugin. - -### Options - -- `--global` - Remove from the global config instead of local. diff --git a/website/docs/proto/commands/tool/add.mdx b/website/docs/proto/commands/tool/add.mdx new file mode 100644 index 00000000000..9716cc9d567 --- /dev/null +++ b/website/docs/proto/commands/tool/add.mdx @@ -0,0 +1,27 @@ +--- +title: tool add +sidebar_label: add +--- + +import VersionLabel from '@site/src/components/Docs/VersionLabel'; + + + +The `proto tool add ` command (formerly `proto add-plugin`) will add the provided ID +and plugin locator string to the `[plugins]` section of the local (`.prototools`) or global +(`~/.proto/config.toml`) config file. + +```shell +$ proto tool add node "source:https://github.com/moonrepo/node-plugin/releases/latest/download/node_plugin.wasm" +``` + +> Learn more about [plugin locator strings](../../plugins#enabling-plugins). + +### Arguments + +- `` - ID of the tool. +- `` - How to locate the plugin. + +### Options + +- `--global` - Add to the global config instead of local. diff --git a/website/docs/proto/commands/tool/info.mdx b/website/docs/proto/commands/tool/info.mdx new file mode 100644 index 00000000000..c7f5825940a --- /dev/null +++ b/website/docs/proto/commands/tool/info.mdx @@ -0,0 +1,37 @@ +--- +title: tool info +sidebar_label: info +--- + +import VersionLabel from '@site/src/components/Docs/VersionLabel'; + + + +The `proto tool info ` command will display information about a tool and its plugin. + +``` +$ proto tool info node + +node - Node.js + +Inventory + Store: ~/.proto/tools/node + Executable: ~/.proto/tools/node/20.0.0/bin/node + Globals directory: ~/.proto/tools/node/globals/bin + Binaries: + - ~/.proto/bin/node (primary) + Shims: + - ~/.proto/shims/node (primary) + +Plugin + Version: 0.5.2 + Source: https://github.com/moonrepo/node-plugin/releases/download/v0.5.2/node_plugin.wasm +``` + +### Arguments + +- `` - ID of tool. + +### Options + +- `--json` - Print the info in JSON format. diff --git a/website/docs/proto/commands/plugins.mdx b/website/docs/proto/commands/tool/list-plugins.mdx similarity index 50% rename from website/docs/proto/commands/plugins.mdx rename to website/docs/proto/commands/tool/list-plugins.mdx index 85d53e375e7..ec1c2c9663d 100644 --- a/website/docs/proto/commands/plugins.mdx +++ b/website/docs/proto/commands/tool/list-plugins.mdx @@ -1,16 +1,18 @@ --- -title: plugins +title: tool list-plugins +sidebar_label: list-plugins --- import VersionLabel from '@site/src/components/Docs/VersionLabel'; - + -The `proto plugins` command will list all available and configured plugins. Will load all -`.prototools` traversing upwards, and the `~/.proto/config.toml` file. +The `proto tool list-plugins` command (formerly `proto plugins`) will list all available and +configured plugins, for both third-party and built-in tools. Will load all `.prototools` traversing +upwards, and the `~/.proto/config.toml` file. ``` -$ proto plugins +$ proto tool list-plugins bun - Bun v1.2 Source: https://github.com/moonrepo/bun-plugin/releases/latest/download/bun_plugin.wasm diff --git a/website/docs/proto/commands/tools.mdx b/website/docs/proto/commands/tool/list.mdx similarity index 67% rename from website/docs/proto/commands/tools.mdx rename to website/docs/proto/commands/tool/list.mdx index 243a52cdd76..d551c493c44 100644 --- a/website/docs/proto/commands/tools.mdx +++ b/website/docs/proto/commands/tool/list.mdx @@ -1,16 +1,17 @@ --- -title: tools +title: tool list +sidebar_label: list --- import VersionLabel from '@site/src/components/Docs/VersionLabel'; - + -The `proto tools` command will list all tools that have been installed, along with their installed -versions, relevant timestamps, available aliases, and store location. +The `proto tool list` command (formerly `proto tools`) will list all tools that have been installed, +along with their installed versions, relevant timestamps, available aliases, and store location. ``` -$ proto tools +$ proto tool list go - Go Store: ~/.proto/tools/go @@ -21,7 +22,7 @@ go - Go node - Node.js Store: ~/.proto/tools/node Aliases: - ~20 = stable + ~20 - stable Versions: 18.0.0 - installed 09/03/23, last used 09/18/23, default version 18.14.0 - installed 09/04/23, last used 09/04/23 @@ -34,12 +35,12 @@ node - Node.js A list of tool IDs can be provided to filter the output list. ```shell -$ proto tools node npm +$ proto tool list node npm ``` ### Arguments -- `[id...]` - IDs of plugins. +- `[id...]` - IDs of tools. ### Options diff --git a/website/docs/proto/commands/tool/remove.mdx b/website/docs/proto/commands/tool/remove.mdx new file mode 100644 index 00000000000..c26c26f316b --- /dev/null +++ b/website/docs/proto/commands/tool/remove.mdx @@ -0,0 +1,26 @@ +--- +title: tool remove +sidebar_label: remove +--- + +import VersionLabel from '@site/src/components/Docs/VersionLabel'; + + + +The `proto tool remove ` command (formerly `proto remove-plugin`) will remove the provided tool +ID from the `[plugins]` section of the local (`.prototools`) or global (`~/.proto/config.toml`) +config file. + +```shell +$ proto tool remove node +``` + +> Built-in plugins _cannot_ be removed! + +### Arguments + +- `` - ID of the tool. + +### Options + +- `--global` - Remove from the global config instead of local. diff --git a/website/docs/proto/commands/uninstall.mdx b/website/docs/proto/commands/uninstall.mdx index 6a4c0a13944..055d3025f33 100644 --- a/website/docs/proto/commands/uninstall.mdx +++ b/website/docs/proto/commands/uninstall.mdx @@ -6,10 +6,14 @@ The `proto uninstall ` (or `proto ui`) command will uninstall and remove a `~/.proto/tools/`. If the tool has not been installed, the command will exit early. ```shell +# Remove a specific version $ proto uninstall deno 1.31 + +# Remove all versions +$ proto uninstall deno ``` ### Arguments - `` - Type of tool. -- `[version]` - Version of tool. Defaults to "latest". +- `[version]` - Version of tool. diff --git a/website/docs/proto/config.mdx b/website/docs/proto/config.mdx index 6e0c456697d..3aa44ab3b45 100644 --- a/website/docs/proto/config.mdx +++ b/website/docs/proto/config.mdx @@ -73,6 +73,19 @@ Defaults to `false`. auto-clean = true ``` +### `detect-strategy` + +The strategy to use when [detecting versions](./detection). Defaults to `first-available`. + +- `first-available` - Will use the first available version that is found. Either from `.prototools` + or a tool specific file (`.nvmrc`, etc). +- `prefer-prototools` - Prefer a `.prototools` version, even if found in a parent directory. If none + found, falls back to tool specific file. + +```toml title="~/.proto/config.toml" +detect-strategy = "prefer-prototools" +``` + ### `node-intercept-globals` When enabled, will intercept global package installs for node/npm/pnpm/yarn and suggest using diff --git a/website/docs/proto/detection.mdx b/website/docs/proto/detection.mdx index d1a765ca360..46d1d1526c2 100644 --- a/website/docs/proto/detection.mdx +++ b/website/docs/proto/detection.mdx @@ -30,7 +30,8 @@ $ PROTO_NODE_VERSION=18.0.0 proto run node #### 3. Version is located by traversing the file system This step will attempt to find a configuration or manifest file in the current working directory, -and traverse upwards through parent directories until a file is found. +and traverse upwards through parent directories (stops at the user's home directory) until a file is +found. ##### 3.1. Version is defined locally in `.prototools` diff --git a/website/docs/proto/faq.mdx b/website/docs/proto/faq.mdx index 5c8b0c9ad5e..5aa3e98f617 100644 --- a/website/docs/proto/faq.mdx +++ b/website/docs/proto/faq.mdx @@ -22,6 +22,24 @@ letters are circle shaped. Double points for proto having two o's like the other Nah. +### What is a tool? + +A tool in the context of proto is either a language, dependency/package manager (typically for a +language), or third-party CLI. The tool is something that can be downloaded and installed _by +version_ onto a machine. + +Furthermore, a tool should have a primary executable file that can be executed with `proto run` or +through proto's shims. Additionally, a tool can also provide secondary executable files. For +example, `npm` (the primary) also provides `npx` and `node-gyp` (secondaries). + +### What is a plugin? + +A plugin is a WASM (or TOML) file for a tool. + +The terms tool and plugin are often used interchangeably, but plugin primarily refers to the WASM +portion of a tool, while tool refers to the entire package: metadata, business logic, branding, so +on an so forth. + ### Will you support more languages? Yes! We'd love to support as many as possible, and if you'd like to help, join our Discord diff --git a/website/docs/proto/index.mdx b/website/docs/proto/index.mdx index 1352f33f979..e5a02e3901b 100644 --- a/website/docs/proto/index.mdx +++ b/website/docs/proto/index.mdx @@ -89,20 +89,20 @@ tools can be supported through [third-party plugins](./proto/plugins). Because proto is written in Rust, we only support targets that are explicitly compiled for, which are currently: -| Operating system | Architecture | Target | -| :--------------- | :----------- | :------------------------- | -| macOS 64-bit | Intel | `x86_64-apple-darwin` | -| macOS 64-bit | ARM | `aarch64-apple-darwin` | -| Linux 64-bit | Intel GNU | `x86_64-unknown-linux-gnu` | -| Windows 64-bit | Intel | `x86_64-pc-windows-msvc` | +| Operating system | Architecture | Target | +| :--------------- | :----------- | :-------------------------- | +| macOS 64-bit | Intel | `x86_64-apple-darwin` | +| macOS 64-bit | ARM | `aarch64-apple-darwin` | +| Linux 64-bit | Intel GNU | `x86_64-unknown-linux-gnu` | +| Linux 64-bit | Intel musl | `x86_64-unknown-linux-musl` | +| Windows 64-bit | Intel | `x86_64-pc-windows-msvc` | ## Roadmap -- Linux ARM/musl support. +- Linux ARM support. - Build from source for existing languages. - New languages. diff --git a/website/docs/proto/plugins.mdx b/website/docs/proto/plugins.mdx index d73fd8d4e2b..d0a8a0b1d21 100644 --- a/website/docs/proto/plugins.mdx +++ b/website/docs/proto/plugins.mdx @@ -10,10 +10,10 @@ their needs. ## Enabling plugins Plugins can be enabled by configuring them in -[`.prototools` or `~/.proto/config.toml`](./config#plugins) files, within the `[plugins]` section, -which maps a plugin to a locator string. The map key is the plugin name _in kebab-case_, which is -used as the binary/tool name in proto, and also the name for configuration and cache purposes. The -map value is a locator string that defines a scope and source location. +[`.prototools` or `~/.proto/config.toml`](./config#plugins) files, within the `[plugins]` section. +The map key is the plugin name _in kebab-case_, which is used as the binary/tool name in proto, and +also the name for configuration and cache purposes. The map value is a plugin locator string that +defines a scope and source location. ```toml title=".prototools" [plugins] diff --git a/website/docs/proto/toml-plugin.mdx b/website/docs/proto/toml-plugin.mdx index 9efac4a83fb..a967c1eff73 100644 --- a/website/docs/proto/toml-plugin.mdx +++ b/website/docs/proto/toml-plugin.mdx @@ -140,9 +140,9 @@ resolve with: Git tags or a JSON manifest. To resolve a list of available versions using Git tags, the following settings are available: -- `git-url` - The remote URL to fetch tags from. -- `git-tag-pattern` - A regular expression to filter and match with. Defaults to - `^v?((\\d+)\\.(\\d+)\\.(\\d+))`. The capture group `1` will be extracted as the version. +- `git-url` (required) - The remote URL to fetch tags from. +- `git-tag-pattern` - A regular expression to filter and match with. The capture group `1` will be + extracted as the version. ```toml title="protostar.toml" # ... @@ -156,8 +156,8 @@ git-tag-pattern = "^@protostar/cli@((\\d+)\\.(\\d+)\\.(\\d+))" To resolve a list of available versions using a JSON manifest, the following settings are available: -- `manifest-url` - A URL that returns a JSON response of all versions. This response _must be_ an - array of strings, or an array of objects. +- `manifest-url` (required) - A URL that returns a JSON response of all versions. This response + _must be_ an array of strings, or an array of objects. - `manifest-version-key` - If the response is an array of objects, this is the key to extract the version from. If the response is an array of strings, this setting can be omitted. Defaults to `version`. diff --git a/website/docs/proto/wasm-plugin.mdx b/website/docs/proto/wasm-plugin.mdx index 74f16d4946c..1ef6e337a14 100644 --- a/website/docs/proto/wasm-plugin.mdx +++ b/website/docs/proto/wasm-plugin.mdx @@ -365,42 +365,48 @@ pub fn unpack_archive(Json(input): Json) -> FnResult<()> { } ``` -### Locating binaries +### Locating executables Even though a tool has been installed, we must inform proto of where to find the binary to execute. -This can be achieved with the optional `locate_bins` function. If this function is not defined, -proto will assume the binary is named `` (`.exe` on Windows), relative from the installation -directory. +This can be achieved with the required `locate_executables` function. The `primary` field defines +the location of the executable, relative from the installation directory. ```rust #[plugin_fn] -pub fn locate_bins(Json(_): Json) -> FnResult> { +pub fn locate_executables( + Json(_): Json, +) -> FnResult> { let env = get_proto_environment()?; - Ok(Json(LocateBinsOutput { - bin_path: Some(if env.os == HostOS::Windows { - "node.exe".into() - } else { - "bin/node".into() - }), - ..LocateBinsOutput::default() + Ok(Json(LocateExecutablesOutput { + primary: Some(ExecutableConfig::new( + // Helper that chooses between distinct Unix or Windows values + env.os.for_native("bin/node", "node.exe"), + // Or the same value with optional Windows extension + // env.os.get_file_name("node", "exe") + )), + ..LocateExecutablesOutput::default() })) } ``` -Furthermore, the `locate_bins` function can define a list of lookups for the globals installation -directory. proto will loop through each lookup, and return the first directory that exists on the -current file system. proto will also expand environment variables in the format of `$VAR_NAME`. If a -variable is not defined, or has an empty value, the lookup will be skipped. To demonstrate this, -we'll use [Deno](https://deno.land/manual@v1.35.0/tools/script_installer). +Furthermore, the `locate_executables` function can define a list of lookups for the globals +installation directory. proto will loop through each lookup, and return the first directory that +exists on the current file system. proto will also expand environment variables in the format of +`$VAR_NAME`. If a variable is not defined, or has an empty value, the lookup will be skipped. To +demonstrate this, we'll use [Deno](https://deno.land/manual@v1.35.0/tools/script_installer). ```rust #[plugin_fn] -pub fn locate_bins(Json(_): Json) -> FnResult> { - Ok(Json(LocateBinsOutput { - fallback_last_globals_dir: true, +pub fn locate_executables( + Json(_): Json, +) -> FnResult> { + let env = get_proto_environment()?; + + Ok(Json(LocateExecutablesOutput { globals_lookup_dirs: vec!["$DENO_INSTALL_ROOT/bin".into(), "$HOME/.deno/bin".into()], - ..LocateBinsOutput::default() + // ... + ..LocateExecutablesOutput::default() })) } ``` @@ -443,18 +449,23 @@ pub fn resolve_version( ) -> FnResult> { let mut output = ResolveVersionOutput::default(); - if input.initial == "node" { - output.candidate = Some("latest".into()); - - } else if input.initial == "lts-*" || input.initial == "lts/*" { - output.candidate = Some("stable".into()); + if let UnresolvedVersionSpec::Alias(alias) = input.initial { + let candidate = if alias == "node" { + "latest" + } else if alias == "lts-*" || alias == "lts/*" { + "stable" + } else if alias.starts_with("lts-") || alias.starts_with("lts/") { + &alias[4..] + } else { + return Ok(Json(output)); + }; - } else if input.initial.starts_with("lts-") || input.initial.starts_with("lts/") { - output.candidate = Some(input.initial[4..].to_owned()); + output.candidate = Some(UnresolvedVersionSpec::Alias(candidate.to_owned())); } Ok(Json(output)) } + ``` ### Detecting versions @@ -493,64 +504,17 @@ pub fn parse_version_file(Json(input): Json) -> FnResult< if let Some(engines) = json.engines { if let Some(constraint) = engines.get("node") { - version = Some(constraint.to_owned()); + version = Some(UnresolvedVersionSpec::parse(constraint)?); } } } else { - version = Some(input.content.trim().to_owned()); + version = Some(UnresolvedVersionSpec::parse(input.content.trim())?); } Ok(Json(ParseVersionFileOutput { version })) } ``` -### Creating shims - -Tools within proto wouldn't function without shims, and as such, plugins can register their own -shims to be created. By default, proto _will always_ create a global shim of the plugin at -`~/.proto/bin/`, but you can also register additional shims with the `create_shims` function. - -#### Global shims - -Global shims are optional scripts that are available on `PATH` as they are generated in the -`~/.proto/bin` directory, and can be defined with the `global_shims` parameter. This param is a hash -map, where the key is the shim file name, and the value is a configuration object. - -```rust -#[plugin_fn] -pub fn create_shims(Json(_): Json) -> FnResult> { - let env = get_proto_environment()?; - let mut global_shims = HashMap::new(); - - global_shims.insert( - "npx".into(), - ShimConfig::global_with_alt_bin(if env.os == HostOS::Windows { - "npx.cmd".into() - } else { - "bin/npx".into() - }), - ); - - Ok(Json(CreateShimsOutput { - global_shims, - ..CreateShimsOutput::default() - })) -} -``` - -Furthermore, if you'd prefer to _not_ create a primary global shim at all, enable the -`no_primary_global` field. - -```rust -#[plugin_fn] -pub fn create_shims(Json(_): Json) -> FnResult> { - Ok(Json(CreateShimsOutput { - no_primary_global: true, - ..CreateShimsOutput::default() - })) -} -``` - ### Installing and uninstalling globals Most languages support the concept of installing packages/dependencies globally, and making them @@ -692,19 +656,16 @@ plugin ID, the dependency to install, and an optional environment variable to th generate_globals_test!("id", "dependency", "GLOBAL_INSTALL_ROOT"); ``` -And lastly, to test shims, use `generate_global_shims_test!` or `generate_local_shims_test!`. Both -macros require a plugin ID, but also support additional arguments when creating more than 1 shim. -These macros generate snapshots using [Insta](https://insta.rs/). +And lastly, to test shims, use `generate_shims_test!`. This requires a plugin ID, but also supports +additional arguments when creating more than 1 shim. This macro generates snapshots using +[Insta](https://insta.rs/). ```rust // Only the single binary -generate_global_shims_test!("id"); +generate_shims_test!("id"); // When creating alternate/additional globals -generate_global_shims_test!("id", ["other", "another"]); - -// When creating local shims, each file required in the list -generate_local_shims_test!("id", ["a", "b", "c"]); +generate_shims_test!("id", ["other", "another"]); ``` ## Building and publishing @@ -716,9 +677,16 @@ to publish a GitHub release and include the `.wasm` file as an asset. ### Building, optimizing, and stripping WASM files are pretty fat, even when compiling in release mode. To reduce the size of these files, -we can use `wasm-opt` and `wasm-strip`, both of which are provided by -[WebAssembly](https://github.com/WebAssembly). The following script is what we use to build our own -plugins. +we can use `wasm-opt` and `wasm-strip`, both of which are provided by the +[WebAssembly](https://github.com/WebAssembly) group. The following script is what we use to build +our own plugins. + +:::info + +This functionality is natively supported in our +[build-proto-plugin](https://github.com/moonrepo/build-proto-plugin) GitHub Action! + +::: ```bash title="build-wasm" #!/usr/bin/env bash @@ -766,25 +734,21 @@ build-wasm ### Automate releases -Coming soon! +If you're using GitHub Actions, you can automate the release process with our official +[build-proto-plugin](https://github.com/moonrepo/build-proto-plugin) action. - + +3. The action will automatically build the plugin, create a release, and attach the built file as an + asset. ## Resources diff --git a/website/sidebars.js b/website/sidebars.js index 346a5822d06..2201c726b68 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -277,7 +277,6 @@ const sidebars = { type: 'category', label: 'Commands', items: [ - 'proto/commands/add-plugin', 'proto/commands/alias', 'proto/commands/bin', 'proto/commands/clean', @@ -289,11 +288,26 @@ const sidebars = { 'proto/commands/list-remote', 'proto/commands/outdated', 'proto/commands/pin', - 'proto/commands/plugins', - 'proto/commands/remove-plugin', 'proto/commands/run', 'proto/commands/setup', - 'proto/commands/tools', + { + type: 'category', + label: 'tool', + items: [ + 'proto/commands/tool/add', + 'proto/commands/tool/info', + 'proto/commands/tool/list', + 'proto/commands/tool/list-plugins', + 'proto/commands/tool/remove', + ], + link: { + type: 'generated-index', + title: 'tool', + description: 'Operations for managing tools and plugins.', + slug: '/proto/commands/tool', + keywords: ['cli', 'commands', 'tool', 'plugin'], + }, + }, 'proto/commands/unalias', 'proto/commands/uninstall', 'proto/commands/uninstall-global', diff --git a/website/src/components/Products/Proto/ToolCard.tsx b/website/src/components/Products/Proto/ToolCard.tsx index f2e7d0085a3..c56fd4c142a 100644 --- a/website/src/components/Products/Proto/ToolCard.tsx +++ b/website/src/components/Products/Proto/ToolCard.tsx @@ -22,11 +22,11 @@ export default function ToolCard({ id, tool }: ToolCardProps) { let usage = `proto install ${usageId}`; if (tool.pluginLocator) { - usage = `proto add-plugin ${usageId} "${tool.pluginLocator}"\n${usage}`; + usage = `proto tool add ${usageId} "${tool.pluginLocator}"\n${usage}`; } return ( -
+
{tool.pluginType === 'toml' && } {tool.pluginType === 'wasm' && } diff --git a/website/src/components/Products/Proto/ToolsGrid.tsx b/website/src/components/Products/Proto/ToolsGrid.tsx index 22d4e2926ae..e197089dcfc 100644 --- a/website/src/components/Products/Proto/ToolsGrid.tsx +++ b/website/src/components/Products/Proto/ToolsGrid.tsx @@ -2,6 +2,12 @@ import React from 'react'; import clsx from 'clsx'; import Link from '@docusaurus/Link'; import Text from '@site/src/ui/typography/Text'; +import Bun from '@site/static/img/tools/bun.svg'; +import Deno from '@site/static/img/tools/deno.svg'; +import Go from '@site/static/img/tools/go.svg'; +import Node from '@site/static/img/tools/node.svg'; +import Python from '@site/static/img/tools/python.svg'; +import Rust from '@site/static/img/tools/rust.svg'; export interface ToolsGridProps { cols?: number; @@ -12,25 +18,25 @@ export default function ToolsGrid({ cols = 3 }: ToolsGridProps) {
- +
- +
- +
- + @@ -40,13 +46,13 @@ export default function ToolsGrid({ cols = 3 }: ToolsGridProps) {
- +
- +
diff --git a/website/src/data/proto-tools.tsx b/website/src/data/proto-tools.tsx index ed11943a561..128b3db8958 100644 --- a/website/src/data/proto-tools.tsx +++ b/website/src/data/proto-tools.tsx @@ -148,7 +148,7 @@ export const THIRD_PARTY_TOOLS: Record = { }, helm: { bins: ['helm'], - description: 'The Kubernetes Package Manager', + description: 'The Kubernetes Package Manager.', homepageUrl: 'https://helm.sh', name: 'helm', pluginLocator: @@ -158,7 +158,7 @@ export const THIRD_PARTY_TOOLS: Record = { }, helmfile: { bins: ['helmfile'], - description: 'Deploy Kubernetes Helm Charts', + description: 'Deploy Kubernetes Helm Charts.', homepageUrl: 'https://helmfile.readthedocs.io/en/latest', name: 'helmfile', pluginLocator: