Proto use nitpicks

[rotu]

What version?

0.24.0

Which command?

No response

What happened?

Installing multiple tools with proto use has brought up some issues. More logs available and I'm sure I could split these out into different issues

0. The error output for an unresolved version doesn't mention which tool errored which makes troubleshooting slightly harder. The tools are logged in an arbitrary order and proto bails on first failure, so it's not contextually clear.

   > proto use
   ━━━        Installing 7 tools: deno, node, npm, pnpm, python, rust, yarn
   [ INFO 2023-12-07 11:53:58] proto::commands::install  Node.js has already been installed at ~\.proto\tools\node\20.10.0
   [ INFO 53:59.659] proto::commands::install  Rust has been installed to ~/.rustup/toolchains\stable-x86_64-pc-windows-msvc!
   Error: proto::version::unresolved
   
     × Failed to resolve stable to a valid supported version.
     help: Does this version exist and has it been released?

1. python, deno, npm, yarn, pnpm don't have a version aliased "stable"

2. proto use with $env:PROTO_PIN_LATEST=1 rewrites versions in the global config e.g. deno = "latest" becomes deno = "1.38.5". I'm not sure if this is intentional. This seems to happen for node "stable"/"latest"/"canary", but NOT "iron" nor ("lts-latest" (lol))

3. The error message for missing a "canary" version differs in form from missing "stable":

   > proto install npm canary
   Error: plugin::call_func::failed
   
     × npm does not support canary/nightly versions.
   
   > proto install npm stable
   Error: proto::version::unresolved
   
     × Failed to resolve stable to a valid supported version.
     help: Does this version exist and has it been released?

Trace logs?

No response

Operating system?

Windows

Architecture?

x64

[milesj]

@rotu

The error output for an unresolved version doesn't mention which tool errored which makes troubleshooting slightly harder. The tools are logged in an arbitrary order and proto bails on first failure, so it's not contextually clear.

Some errors happen outside the context of the tool, and that's usually why there's no info. Let me dig into this one.

python, deno, npm, yarn, pnpm don't have a version aliased "stable"

Stable isn't guaranteed to exist, only "latest". Stable only exists for languages that actually follow an LTS like release schedule.

proto use with $env:PROTO_PIN_LATEST=1 rewrites versions in the global config e.g. deno = "latest" becomes deno = "1.38.5". I'm not sure if this is intentional. This seems to happen for node "stable"/"latest"/"canary", but NOT "iron" nor ("lts-latest" (lol))

PROTO_PIN_LATEST should be "global" or "local", not "1". I'm surprised this doesn't actually fail.

This seems to be (mostly) working correctly though? The entire point of the pin-latest setting is to pin the version that "latest" resolves to into the global or local config. It happening for stable/canary seems like a bug though.

The error message for missing a "canary" version differs in form from missing "stable":

Canary isn't a version or alias like stable is. It's a special and separate release channel that changes where to find binaries/archives to download.

[milesj]

That env var does fail for me...

Error: config::env::invalid

  × Invalid environment variable PROTO_PIN_LATEST. Failed to parse "1" into the correct type.

[rotu]

PROTO_PIN_LATEST should be "global" or "local", not "1". I'm surprised this doesn't actually fail.

Sorry, it probably was "global". setting it to 1 does cause the expected failure.

[rotu]

Stable isn't guaranteed to exist, only "latest". Stable only exists for languages that actually follow an LTS like release schedule.
Canary isn't a version or alias like stable is. It's a special and separate release channel that changes where to find binaries/archives to download.

I think the semantics are currently as follows:

1. The latest version possible (canary)
2. The latest version recommended for general consumption (latest)
3. The version that will be recommended generally for the longest (stable)

But, after latest, and canary is the most discoverable option since it's the only one that gets its own flag in proto install!

---

This seems to be (mostly) working correctly though? The entire point of the pin-latest setting is to pin the version that "latest" resolves to into the global or local config. It happening for stable/canary seems like a bug though.

I was puzzled by the behavior mostly because I forgot I had set PROTO_PIN_LATEST in my shell profile 🤦. Realizing this, I surprised this took effect on proto use - not just proto install.

[milesj]

Canary is very unique. It acts like a version and an alias, and how it's handled is different per tool.

For example, Bun is git tag: https://github.com/oven-sh/bun/releases/tag/canary There's only ever 1 canary version, and it constantly gets replaced.

And Deno uses commit hashes and separate download URLs: https://dl.deno.land/ This supports multiple versions but we only support the "latest".

We can maybe support "stable" in the future, but I'm not sure how that would really work for some tools. Most tools fetch the available versions via git tags and nothing else.

I was puzzled by the behavior mostly because I forgot I had set PROTO_PIN_LATEST in my shell profile 🤦. Realizing this, I surprised this took effect on proto use - not just proto install.

Well proto use is just a parallel proto install :P

[rotu]

I'm sure part of my confusion with pinning is due with different meanings and scopes of the word "pin".

• proto install --pin is documented as globally pinning the package "Pin version as the global default and create a binary symlink". So here, the word "pin" implies global config.
• proto pin has a --global flag to determine whether it is pinned globally or locally (good!). It does not resolve a tag like "latest" to a version number. So here "pin" does not imply resolving a semantic tag to a specific version.
• $env:PROTO_PIN_LATEST=local with proto use creates a .prototools files which shadow the global config. proto run with $env:PROTO_PIN_LATEST=local and auto-install=true does not. I'm not sure that a .prototools file should ever be implicitly and silently created.

[milesj]

Aliases or versions can be pinned, hence why it doesn't resolve. The exception is proto install --pin since we have the resolved version at that point.

$env:PROTO_PIN_LATEST=local with proto use creates a .prototools files which shadow the global config. proto run with $env:PROTO_PIN_LATEST=local and auto-install=true does not. I'm not sure that a .prototools file should ever be implicitly and silently created.

It does not. It traverses up and loads all .prototools and installs anything it finds. PROTO_PIN_LATEST doesn't make sense here unless you have node = "latest" or something in the .prototools file.

I think there's a bug though that it's also grabbing ~/.proto/.prototools. Which makes it a little over zealous.

Edit: It was #326

[milesj]

Give 0.24.2 a shot. Fixed some of these.

[rotu]

I gave it a shot and I'm still pretty confused how this is supposed to work.

I can see that now proto use doesn't install from .proto/.prototools and copy that to a local .prototools.

But with $env:PROTO_PIN_LATEST = 'local', proto install node latest writes to the local .prototools whereas proto install node stable does not.

Aliases or versions can be pinned, hence why it doesn't resolve.

I think a big part of my issue is terminology. There are three questions that are being blurred by the implicit meaning of the word "pin":

1. Are we writing some tool requirement to a config file?
2. Which config file?
3. Is that saved requirement the unresolved "floating" specifier or the resolved, "frozen" version number at time of installation?

[milesj]

Are we writing some tool requirement to a config file?

Yeah pin is always writing to a config file. It's either pinning an alias or version, depending on the command.

Which config file?

By default it's the .prototools in cwd, unless --global is passed, which is then ~/.proto/prototools. For proto install --pin, it uses proto pin under the hood.

PROTO_PIN_LATEST = 'local' = cwd .prototools
PROTO_PIN_LATEST = 'global' = ~/.proto/.prototools

Is that saved requirement the unresolved "floating" specifier or the resolved, "frozen" version number at time of installation?

It depends. proto install --pin and PROTO_PIN_LATEST is always the resolved version, since pinning the literal alias "latest" seems dumb.

proto pin is whatever the user puts.

[rotu]

I think I must have communicated this incorrectly! These questions are ambiguities of the use of the word "pin" in various places in the software. I'm sure sorting out some of the bugs and inconsistencies will clear this up!

---

Here's a very concrete example:

> $env:PROTO_PIN_LATEST='local'
> proto install node latest
> proto install node stable
> proto run node

Surprisingly to me, this runs node 21.4.0 because proto install node stable does NOT locally pin the version, even if I pass the (poorly named?) --pin flag.

---

pinning the literal alias "latest" seems dumb.

Then I'm dumb because that's what I use for most tools! This is so I can proto use to install all my tools at once.

But I suppose that's why proto outdated presents tools with "latest" as having updates available:

> proto outdated
deno - current version 1.38.5 (via latest), newer version 1.38.5
node - current version 21.4.0 (via 21.4.0), latest version 21.4.0
...

[milesj]

Some history on why things exist.

So --pin was added so that when users do proto install node 20.1.0 --pin, they install that specific version and set it as the global version in 1 flow, instead of having to call proto pin after the install manually. The proto install node --pin is basically equivalent to "upgrade to the latest version and use that as the new global version". It's the suggested flow for upgrading.

The pin-latest setting was added to automate that even further by making --pin optional when installing the latest version. It only works for the "latest" alias, hence the name pin-latest. This is why "stable" and others don't pin.

Pinning = save some value to a file.

Then I'm dumb because that's what I use for most tools! This is so I can proto use to install all my tools at once.

You should use proto pin node latest then, not --pin or pin-latest.

[milesj]

Gonna close this as the pin stuff is working as intended. For 0, this will solve it: #358

[rotu]

Gonna close this as the pin stuff is working as intended. For 0, this will solve it: #358

Definitely much better! I'm still scratching my head why proto install node 20.1.0 --pin updates the global-level instead of the project-level pinned version but I won't belabor the point any more.