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

[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