Passthrough commands

[paularmstrong]

Looking at #554 and #555, there are too many unknowns with passing through to commands like vite and astro (and webpack, next, etc, for that matter). It doesn't seem sustainable to attempt to curate plugins to every single npx command available. Nor does it seem helpful for users of oneRepo to leave them to need to write the entire passthrough on their own.

Passthrough commands

Which opens the idea for "passthrough commands". This would be a way for Workspace configurations to declare commands that should pass through to run with the graph.packageManager.run (essentially: cd <workspace> && npx <command...> [options...]

export default {
  commands: {
    passthrough: {
      /**
       * Use `true` to just expose the key as the command to run
       */
      astro: true,
      /**
       * Alternatively, define a command name that passes through to a full command string
       */
      start: 'astro dev'
    },
  },
} satisfies Config;

Using the previous configuration, users can enter either:

one ws docs astro -- build
# Runs `cd <docs-location> && npx astro build`

one ws docs start
# Runs `cd <docs-location> && npx astro dev`

Downsides

This is essentially "npm package.json scripts", with some extra helpers (documentation, etc).

Open questions

1. Should we keep yargs in strict mode for these commands?

   This is our default behavior, which prevents unknown/undefined arguments in the command string – and requires the use of -- to use passthrough arguments. Turning strict mode off would enable one ws docs astro build for the first config scenario, but could reduce clarity and feedback for what is possible.

[jakeleveroni]

agreed, maintaining plugins for every possible command is not sustainable. I think exposing a passthrough to the underlying package manager command would be useful for sure. 👍

As for yargs strict mode my vote is to turn it off for these commands if possible i think its clearer than having to use -- to passthrough

[paularmstrong]

One problem with non-strict args, you potentially overload global defaults from one.

Things that will immediately conflict:

• --help
• --dry-run
• --silent
• -v (-vvvv, etc)

So now there would be another decision: do you filter those out and not pass them through to the underlying command, or do you also pass them through? There may be negative consequences in either direction.

It's much safer to use the standard -- passthrough, which means anything you put here won't be documented via --help and may or may not work with the underlying command.

[paularmstrong]

For example, Astro's verbosity flag is --verbose, but that's not always the case for every command, so if you truly want full verbosity, you'll need to include both oneRepo's verbosity flags + the Astro flag:

This is clearer from the standpoint of "-vvvv is for one" and "--verbose is for the underlying command.

one ws docs start -vvvv -- --verbose

For help, because it's the same flag, if you disable the global -h flag for oneRepo, you can never get the help information for one ws docs start, you would only ever be able to get the astro dev help information.

one ws docs start -h
one ws docs start

Run "astro dev" in "docs".

Global:
      --dry-run        Run without actually making modifications or destructive operations                                            [boolean] [default: false]
  -v, --verbosity      Set the verbosity of the script output. Increase verbosity with `-vvv`, `-vvvv`, or `-vvvvv`. Reduce verbosity with `-v` or `--silent`
                                                                                                                                            [count] [default: 2]
      --show-advanced  Pair with `--help` to show advanced options.                                                                                    [boolean]
  -h, --help           Show this help screen                                                                                                           [boolean]

Positionals:
  workspace-name  The name or alias of a Workspace.                                                                                                     [string]
  command         Command to run.                                                                                                                       [string]

one ws docs start -- -h
  astro dev [...flags]

   Flags
                   --port  Specify which port to run on. Defaults to 4321.
                   --host  Listen on all addresses, including LAN and public addresses.
  --host <custom-address>  Expose on a network IP address at <custom-address>
                   --open  Automatically open the app in the browser on server start
              --help (-h)  See all available flags.

Check https://docs.astro.build/en/reference/cli-reference/#astro-dev for more information.
 ┌ Run astro dev
 └ ✔ 784ms
 ■ ✔ Completed 808ms

[jakeleveroni]

hmm if thats the case it sounds like not using -- to passthrough args just adds unnecessary headaches. The -- passthrough pattern is already understood by one cli users anyways, shouldnt be a problem to continue to use it for passthroughs to package manager commands then as well

[paularmstrong]

Perhaps some extra documentation around that wouldn't hurt as well.