Unified CLI syntax for projects/packages/exports

[kylewlacy]

Today, we use -p or -r flags to reference projects locally or from the registry, respectively:

# Run curl locally
brioche run -p ./packages/curl -- -v

# Run curl from registry
brioche run -r curl -- -v

We also have a separate -e flag to specify a different export:

# Build `export function test` from curl
brioche build -p ./packages/curl -e test

Finally, we have a -c flag to specify a command to run:

# Run `bin/psql` from Postgres project
brioche run -p ./packages/postgresql -c bin/psql

This syntax is both a bit cumbersome, and also limits what you can do with one command! For example, you can't build both default and test across 2 packages in one command:

# INVALID!
brioche build \
  -p ./packages/postgresql -e default -e test \
  -p ./packages/curl -e default -e test

It would be nice if we could figure out a way to handle this more consistently, especially to allow building multiple packages+exports at once

[kylewlacy]

To me, the "obvious" idea is to replace -p / -r / -e with normal positional arguments, disambiguating with syntax, something like this:

# Build local curl
brioche build ./packages/curl

# Build remote curl
brioche build curl

# Build curl test export
brioche build ./packages/curl#test

So basically, a local package must be specified by absolute path, or a relative path starting with ./ or ../. A registry package is specified by name (optionally with @{version} to specify a version in the future). And an export name can optionally be specified with #{exportName}.

This would also mean that the CLI would use the same syntax for specifying packages as import statements from .bri TypeScript files! I feel like keeping these in sync would help new users, as there would be one shared syntax for specifying Brioche projects.

As for the -c flag for brioche run, I think that makes sense to keep as-is. There would be no need to specify multiple things to run at once, and run is the only subcommand that would use a command to run. It would also further complicate the syntax above for a less-used feature.

---

There are a few downsides with this approach:

1. Relative paths have to start with ./ or ../ (meaning brioche build ./packages/curl is valid but brioche build packages/curl is not). We could at least give a good hint if the argument looks like it was meant to be a local path, but this will be a point of friction since many users will likely try the latter using shell tab-completion (especially since we don't have custom Brioche shell completions today)
2. Shell quoting issues with #. A user might try to write brioche build #test in their shell to build the test export for project in the current dir. This would get interpreted as a comment, meaning they'd either need to do brioche build .#test or brioche build '#test' instead. And since the shell is what handles a comment here, we have no way to even detect that the user tried this.

[kylewlacy]

Oh, a slight tweak that might be interesting: using + instead of # for the export name. So like this:

# Build curl test export
brioche build ./packages/curl+test

Kinda nice because + doesn't have special meaning (at least in Bash / zsh I'm pretty sure, I'm guessing also not in POSIX sh, not sure about other shells though). # has the footgun around an export in the current dir, but this should work fine with +:

brioche build +test
# (equivalent to `brioche build -e test` today)

I think in practice, + is still not very likely to conflict with a folder name (unlike, say, -, _, or .). It seems like + might be a pretty good choice for this syntax

[jaudiger]

There is one downside to use +. This character is used in semver for build metadata (like in
1.0.0+build.123). If package@version syntax is ever introduced, there is a
direct conflict: curl@1.0.0+build.123+test which will be ambiguous.

If I'm not mistaken Nix handles this use case differently to prevent collision by using the ^ character, so the previous example would be transformed to: curl@1.0.0+build.123^test.

And normally ^ is not interpreted by the most common shells.

Anyway, we need to take a decision on which character to use before further updating the CLI of Brioche.

[kylewlacy]

Oh that's a good point about +

^ has a similar downside (but not as bad) related to semver constraints, e.g. ^1.0.0 means "1.0.0 or a later compatible version (and can also be written as >=1.0.0, <2). But yeah, between the two, I'd definitely lean towards breaking semver constraint syntax over plain semver version syntax

[jaudiger]

Right, ^ will conflict with semver range syntax, but it won't conflict with semver spec itself: MAJOR.MINOR.PATCH[-prerelease][+buildmetadata].

So if we don't authorise semver range syntax and strictly follow the normal specification, we are safe with brioche build curl@1.0.0+build.123^test.

[nz366]

IMO brioche build <thing> <from> syntax can be more simpler and easier to follow.

brioche build
biroche build test 
brioche build test ./packages/curl                             
brioche build curl,test ./packages/curl
brioche build default,test  ./packages/postgresql,./packages/curl

[jaudiger]

We could build multiple exports per project by using the , character as you suggest. It would enable to reduce the number of Brioche arguments:

brioche build ./curl+test ./curl+default

to:

brioche build ./curl+test,default

[nz366]

Yeah, this is even better. I was more focused about repeated args when building multiple packages at once

brioche build +default ./packages/postgresql+test ./packages/curl