feat(cli): let embedders reuse parsed arguments (#43941)

Co-authored-by: microsoft-playwright-automation[bot] <203992400+microsoft-playwright-automation[bot]@users.noreply.github.com>

Author: microsoft-playwright-automation[bot]

.claude/skills/playwright-dev/tools.md

@@ -312,6 +312,14 @@ test('my-command', async ({ cli, server }) => {
 
 ---
 
+### Embedding the CLI Client
+
+The `playwright-core/lib/tools/cli-client/program` entry point exports `parseArgs(argv)`
+and `program(options?)`. An embedder can parse once, inspect `args._[0]`, then call
+`program({ args, embedderVersion })`. `parseArgs` uses the CLI's boolean options and normalizes
+`-s` to `session` and `-g` to `global`. Without `args`, `program` parses
+`process.argv.slice(2)` as usual. `program` can mutate `args`, so inspect it before the call.
+
 ## Adding Config Options
 
 When you need to add a new config option, update these files in order:

packages/playwright-core/src/tools/cli-client/program.ts

@@ -73,11 +73,8 @@ const booleanOptions: (keyof (GlobalOptions & OpenOptions & AttachOptions & { al
   'version',
 ];
 
-export async function program(options?: { embedderVersion?: string}) {
-  const clientInfo = createClientInfo();
+export function parseArgs(argv: string[]): MinimistArgs {
   const help = require(libPath('tools', 'cli-client', 'help.json'));
-
-  const argv = process.argv.slice(2);
   const boolean = [...help.booleanOptions, ...booleanOptions];
   const args: MinimistArgs = minimist(argv, { boolean, string: ['_'] });
   // Normalize -s alias to --session
@@ -90,6 +87,13 @@ export async function program(options?: { embedderVersion?: string}) {
     args.global = true;
     delete args.g;
   }
+  return args;
+}
+
+export async function program(options?: { args?: MinimistArgs, embedderVersion?: string }) {
+  const clientInfo = createClientInfo();
+  const help = require(libPath('tools', 'cli-client', 'help.json'));
+  const args = options?.args ?? parseArgs(process.argv.slice(2));
 
   const output: Output = args.json ? new JsonOutput() : new TextOutput();
   const commandName = args._?.[0];