@webstir-io/webstir 0.1.1 → 0.1.2

package/src/cli.ts

@@ -4,30 +4,30 @@ import path from 'node:path';
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
-import { runAddPageCommand, runAddTestCommand } from './add.ts';
-import { runAddJobCommand, runAddRouteCommand } from './add-backend.ts';
-import { runBackendInspect } from './backend-inspect.ts';
-import { runEnable } from './enable.ts';
 import {
   formatAddSummary,
+  formatAgentJson,
+  formatAgentSummary,
+  formatBackendInspectJson,
   formatBackendInspectSummary,
   formatBuildSummary,
+  formatDoctorJson,
+  formatDoctorSummary,
   formatEnableSummary,
+  formatFrontendInspectJson,
+  formatFrontendInspectSummary,
   formatInitSummary,
+  formatInspectJson,
+  formatInspectSummary,
+  formatOperationsJson,
+  formatOperationsSummary,
   formatPublishSummary,
+  formatRepairJson,
   formatRepairSummary,
   formatRefreshSummary,
   formatSmokeSummary,
   formatTestSummary,
 } from './format.ts';
-import { runInit } from './init.ts';
-import { runRepair } from './repair.ts';
-import { runRefresh } from './refresh.ts';
-import { runBuild } from './build.ts';
-import { runPublish } from './publish.ts';
-import { runSmoke } from './smoke.ts';
-import { runTest } from './test.ts';
-import { runWatch } from './watch.ts';
 
 interface CliStream {
   write(message: string): void;
@@ -43,13 +43,19 @@ const HELP_TEXT = `Usage:
   webstir init <directory>
   webstir add-page <name> --workspace <path>
   webstir add-test <name-or-path> --workspace <path>
-  webstir add-route <name> --workspace <path> [--method <METHOD>] [--path <path>] [--fastify]
+  webstir add-route <name> --workspace <path> [--method <METHOD>] [--path <path>] [--interaction <navigation|mutation>] [--session <optional|required>] [--session-write] [--form-urlencoded] [--csrf] [--fragment-target <target>] [--fragment-selector <selector>] [--fragment-mode <replace|append|prepend>]
   webstir add-job <name> --workspace <path> [--schedule <expression>]
+  webstir operations
+  webstir mcp
+  webstir agent <inspect|validate|repair|scaffold-page|scaffold-route|scaffold-job> [...]
+  webstir inspect --workspace <path>
+  webstir frontend-inspect --workspace <path>
   webstir backend-inspect --workspace <path>
+  webstir doctor --workspace <path>
   webstir test --workspace <path> [--runtime <frontend|backend|all>]
   webstir smoke [--workspace <path>]
   webstir build --workspace <path>
-  webstir publish --workspace <path>
+  webstir publish --workspace <path> [--frontend-mode <bundle|ssg>]
   webstir enable <feature> [feature-args...] --workspace <path>
   webstir repair --workspace <path> [--dry-run]
   webstir refresh <mode> --workspace <path>
@@ -61,7 +67,13 @@ Commands:
   add-test   Scaffold a test file in an existing workspace.
   add-route  Scaffold a backend route in an existing workspace.
   add-job    Scaffold a backend job in an existing workspace.
+  operations  List the stable Webstir framework operations.
+  mcp        Run the Webstir MCP server over stdio.
+  agent      Orchestrate stable Webstir operations for a narrow goal.
+  inspect    Diagnose and surface stable frontend and backend contract data.
+  frontend-inspect  Inspect stable frontend workspace facts for an existing workspace.
   backend-inspect  Inspect the backend manifest for an existing workspace.
+  doctor     Diagnose scaffold drift and backend health for an existing workspace.
   test       Build and run workspace tests with the Bun orchestrator.
   smoke      Run an end-to-end Bun orchestrator verification flow.
   build      Build a Webstir workspace with the Bun orchestrator.
@@ -75,7 +87,9 @@ Options:
   -w, --workspace <path>   Workspace root to operate on.
   --host <host>            Dev host or bind address (default: 127.0.0.1).
   --port <port>            Dev port (SPA default: 8088, API default: 4321).
+  --frontend-mode <mode>   Frontend publish mode for publish (defaults to bundle; bundle or ssg).
   --dry-run                Report repair changes without writing files.
+  --json                   Emit machine-readable JSON for supported commands.
   -v, --verbose            Enable verbose frontend watch diagnostics.
   --hmr-verbose            Enable detailed hot-update diagnostics.
   -h, --help               Show this help text.
@@ -89,27 +103,33 @@ export async function runCli(argv: readonly string[], io: CliIo = defaultIo): Pr
 
   const [command, ...rest] = argv;
   if (
-    command !== 'init'
-    && command !== 'add-page'
-    && command !== 'add-test'
-    && command !== 'add-route'
-    && command !== 'add-job'
-    && command !== 'backend-inspect'
-    && command !== 'test'
-    && command !== 'smoke'
-    && command !== 'build'
-    && command !== 'publish'
-    && command !== 'enable'
-    && command !== 'repair'
-    && command !== 'refresh'
-    && command !== 'watch'
+    command !== 'init' &&
+    command !== 'add-page' &&
+    command !== 'add-test' &&
+    command !== 'add-route' &&
+    command !== 'add-job' &&
+    command !== 'operations' &&
+    command !== 'mcp' &&
+    command !== 'agent' &&
+    command !== 'inspect' &&
+    command !== 'frontend-inspect' &&
+    command !== 'backend-inspect' &&
+    command !== 'doctor' &&
+    command !== 'test' &&
+    command !== 'smoke' &&
+    command !== 'build' &&
+    command !== 'publish' &&
+    command !== 'enable' &&
+    command !== 'repair' &&
+    command !== 'refresh' &&
+    command !== 'watch'
   ) {
     io.stderr.write(`Unknown command "${command}".\n\n${HELP_TEXT}`);
     return 1;
   }
 
   const options = parseCommandOptions(rest, {
-    allowUnknownOptions: command === 'add-route' || command === 'add-job',
+    allowUnknownOptions: command === 'add-route' || command === 'add-job' || command === 'agent',
   });
   if (options.help) {
     io.stdout.write(HELP_TEXT);
@@ -126,8 +146,35 @@ export async function runCli(argv: readonly string[], io: CliIo = defaultIo): Pr
     return 1;
   }
 
+  if (
+    options.json &&
+    command !== 'operations' &&
+    command !== 'agent' &&
+    command !== 'inspect' &&
+    command !== 'frontend-inspect' &&
+    command !== 'backend-inspect' &&
+    command !== 'doctor' &&
+    command !== 'repair'
+  ) {
+    io.stderr.write(
+      `Only operations, agent, inspect, frontend-inspect, backend-inspect, doctor, and repair accept --json.\n\n${HELP_TEXT}`,
+    );
+    return 1;
+  }
+
+  if (options.frontendMode && command !== 'publish') {
+    io.stderr.write(`Only publish accepts --frontend-mode.\n\n${HELP_TEXT}`);
+    return 1;
+  }
+
   const workspaceRoot = options.workspaceRoot;
-  if (command !== 'init' && command !== 'smoke' && !workspaceRoot) {
+  if (
+    command !== 'init' &&
+    command !== 'smoke' &&
+    command !== 'operations' &&
+    command !== 'mcp' &&
+    !workspaceRoot
+  ) {
     io.stderr.write(`Missing required --workspace <path>.\n\n${HELP_TEXT}`);
     return 1;
   }
@@ -139,6 +186,7 @@ export async function runCli(argv: readonly string[], io: CliIo = defaultIo): Pr
         return 1;
       }
 
+      const { runInit } = await import('./init.ts');
       const result = await runInit({
         args: options.positionals,
         workspaceRoot,
@@ -148,18 +196,63 @@ export async function runCli(argv: readonly string[], io: CliIo = defaultIo): Pr
     }
 
     const resolvedWorkspaceRoot = workspaceRoot ? path.resolve(workspaceRoot) : undefined;
+    const requireWorkspaceRoot = (): string => {
+      if (!resolvedWorkspaceRoot) {
+        throw new Error('Missing required --workspace <path>.');
+      }
+
+      return resolvedWorkspaceRoot;
+    };
+    if (command === 'operations') {
+      if (options.host || options.port !== undefined || options.verbose || options.hmrVerbose) {
+        io.stderr.write(`Operations does not accept watch options.\n\n${HELP_TEXT}`);
+        return 1;
+      }
+
+      if (options.positionals.length > 0) {
+        io.stderr.write(`Operations does not accept positional arguments.\n\n${HELP_TEXT}`);
+        return 1;
+      }
+
+      const { listOperations } = await import('./operations.ts');
+      const operations = listOperations();
+      io.stdout.write(
+        `${options.json ? formatOperationsJson(operations) : formatOperationsSummary(operations)}\n`,
+      );
+      return 0;
+    }
+
+    if (command === 'mcp') {
+      if (
+        options.host ||
+        options.port !== undefined ||
+        options.verbose ||
+        options.hmrVerbose ||
+        options.positionals.length > 0 ||
+        options.workspaceRoot ||
+        options.json
+      ) {
+        io.stderr.write(`MCP does not accept CLI options.\n\n${HELP_TEXT}`);
+        return 1;
+      }
+
+      const { runMcpServer } = await import('./mcp/server.ts');
+      await runMcpServer();
+      return 0;
+    }
     if (command === 'add-page') {
       if (options.host || options.port !== undefined || options.verbose || options.hmrVerbose) {
         io.stderr.write(`Add-page does not accept watch options.\n\n${HELP_TEXT}`);
         return 1;
       }
 
+      const { runAddPageCommand } = await import('./add.ts');
       const result = await runAddPageCommand({
-        workspaceRoot: resolvedWorkspaceRoot!,
+        workspaceRoot: requireWorkspaceRoot(),
         args: options.positionals,
       });
       io.stdout.write(
-        `${formatAddSummary('[webstir] add-page complete', result.target, result.workspaceRoot, result.changes, result.note)}\n`
+        `${formatAddSummary('[webstir] add-page complete', result.target, result.workspaceRoot, result.changes, result.note)}\n`,
       );
       return 0;
     }
@@ -170,12 +263,13 @@ export async function runCli(argv: readonly string[], io: CliIo = defaultIo): Pr
         return 1;
       }
 
+      const { runAddTestCommand } = await import('./add.ts');
       const result = await runAddTestCommand({
-        workspaceRoot: resolvedWorkspaceRoot!,
+        workspaceRoot: requireWorkspaceRoot(),
         args: options.positionals,
       });
       io.stdout.write(
-        `${formatAddSummary('[webstir] add-test complete', result.target, result.workspaceRoot, result.changes, result.note)}\n`
+        `${formatAddSummary('[webstir] add-test complete', result.target, result.workspaceRoot, result.changes, result.note)}\n`,
       );
       return 0;
     }
@@ -186,12 +280,13 @@ export async function runCli(argv: readonly string[], io: CliIo = defaultIo): Pr
         return 1;
       }
 
+      const { runAddRouteCommand } = await import('./add-backend.ts');
       const result = await runAddRouteCommand({
-        workspaceRoot: resolvedWorkspaceRoot!,
+        workspaceRoot: requireWorkspaceRoot(),
         rawArgs: options.rawArgs,
       });
       io.stdout.write(
-        `${formatAddSummary('[webstir] add-route complete', result.target, result.workspaceRoot, result.changes, result.note)}\n`
+        `${formatAddSummary('[webstir] add-route complete', result.target, result.workspaceRoot, result.changes, result.note)}\n`,
       );
       return 0;
     }
@@ -202,12 +297,13 @@ export async function runCli(argv: readonly string[], io: CliIo = defaultIo): Pr
         return 1;
       }
 
+      const { runAddJobCommand } = await import('./add-backend.ts');
       const result = await runAddJobCommand({
-        workspaceRoot: resolvedWorkspaceRoot!,
+        workspaceRoot: requireWorkspaceRoot(),
         rawArgs: options.rawArgs,
       });
       io.stdout.write(
-        `${formatAddSummary('[webstir] add-job complete', result.target, result.workspaceRoot, result.changes, result.note)}\n`
+        `${formatAddSummary('[webstir] add-job complete', result.target, result.workspaceRoot, result.changes, result.note)}\n`,
       );
       return 0;
     }
@@ -223,21 +319,130 @@ export async function runCli(argv: readonly string[], io: CliIo = defaultIo): Pr
         return 1;
       }
 
-      const result = await runBackendInspect({
-        workspaceRoot: resolvedWorkspaceRoot!,
+      const { runBackendInspect } = await import('./backend-inspect.ts');
+      const result = options.json
+        ? await withSuppressedStdout(() =>
+            runBackendInspect({
+              workspaceRoot: requireWorkspaceRoot(),
+            }),
+          )
+        : await runBackendInspect({
+            workspaceRoot: requireWorkspaceRoot(),
+          });
+      io.stdout.write(
+        `${options.json ? formatBackendInspectJson(result) : formatBackendInspectSummary(result)}\n`,
+      );
+      return 0;
+    }
+
+    if (command === 'frontend-inspect') {
+      if (options.host || options.port !== undefined || options.verbose || options.hmrVerbose) {
+        io.stderr.write(`Frontend-inspect does not accept watch options.\n\n${HELP_TEXT}`);
+        return 1;
+      }
+
+      if (options.positionals.length > 0) {
+        io.stderr.write(`Frontend-inspect does not accept positional arguments.\n\n${HELP_TEXT}`);
+        return 1;
+      }
+
+      const { runFrontendInspect } = await import('./frontend-inspect.ts');
+      const result = await runFrontendInspect({
+        workspaceRoot: requireWorkspaceRoot(),
       });
-      io.stdout.write(`${formatBackendInspectSummary(result)}\n`);
+      io.stdout.write(
+        `${options.json ? formatFrontendInspectJson(result) : formatFrontendInspectSummary(result)}\n`,
+      );
       return 0;
     }
 
+    if (command === 'doctor') {
+      if (options.host || options.port !== undefined || options.verbose || options.hmrVerbose) {
+        io.stderr.write(`Doctor does not accept watch options.\n\n${HELP_TEXT}`);
+        return 1;
+      }
+
+      if (options.positionals.length > 0) {
+        io.stderr.write(`Doctor does not accept positional arguments.\n\n${HELP_TEXT}`);
+        return 1;
+      }
+
+      const { runDoctor } = await import('./doctor.ts');
+      const result = await withSuppressedStdout(() =>
+        runDoctor({
+          workspaceRoot: requireWorkspaceRoot(),
+        }),
+      );
+      io.stdout.write(`${options.json ? formatDoctorJson(result) : formatDoctorSummary(result)}\n`);
+      return result.healthy ? 0 : 1;
+    }
+
+    if (command === 'inspect') {
+      if (options.host || options.port !== undefined || options.verbose || options.hmrVerbose) {
+        io.stderr.write(`Inspect does not accept watch options.\n\n${HELP_TEXT}`);
+        return 1;
+      }
+
+      if (options.positionals.length > 0) {
+        io.stderr.write(`Inspect does not accept positional arguments.\n\n${HELP_TEXT}`);
+        return 1;
+      }
+
+      const { runInspect } = await import('./inspect.ts');
+      const result = await withSuppressedStdout(() =>
+        runInspect({
+          workspaceRoot: requireWorkspaceRoot(),
+        }),
+      );
+      io.stdout.write(
+        `${options.json ? formatInspectJson(result) : formatInspectSummary(result)}\n`,
+      );
+      return result.success ? 0 : 1;
+    }
+
+    if (command === 'agent') {
+      if (options.host || options.port !== undefined || options.verbose || options.hmrVerbose) {
+        io.stderr.write(`Agent does not accept watch options.\n\n${HELP_TEXT}`);
+        return 1;
+      }
+
+      const goal = options.positionals[0];
+      if (
+        goal !== 'inspect' &&
+        goal !== 'validate' &&
+        goal !== 'repair' &&
+        goal !== 'scaffold-page' &&
+        goal !== 'scaffold-route' &&
+        goal !== 'scaffold-job'
+      ) {
+        io.stderr.write(
+          `Agent requires one of: inspect, validate, repair, scaffold-page, scaffold-route, scaffold-job.\n\n${HELP_TEXT}`,
+        );
+        return 1;
+      }
+
+      const { runAgent } = await import('./agent.ts');
+      const result = await withSuppressedStdout(() =>
+        runAgent({
+          workspaceRoot: requireWorkspaceRoot(),
+          goal,
+          rawArgs: options.rawArgs,
+          positionals: options.positionals,
+        }),
+      );
+      io.stdout.write(`${options.json ? formatAgentJson(result) : formatAgentSummary(result)}\n`);
+      return result.success ? 0 : 1;
+    }
+
     if (command === 'test') {
       if (options.host || options.port !== undefined || options.verbose || options.hmrVerbose) {
         io.stderr.write(`Test does not accept watch options.\n\n${HELP_TEXT}`);
         return 1;
       }
 
+      const { runTest } = await import('./test.ts');
       const result = await runTest({
-        workspaceRoot: resolvedWorkspaceRoot!,
+        workspaceRoot: requireWorkspaceRoot(),
         rawArgs: options.rawArgs,
       });
       io.stdout.write(`${formatTestSummary(result)}\n`);
@@ -255,6 +460,7 @@ export async function runCli(argv: readonly string[], io: CliIo = defaultIo): Pr
         return 1;
       }
 
+      const { runSmoke } = await import('./smoke.ts');
       const result = await runSmoke({
         workspaceRoot: resolvedWorkspaceRoot,
       });
@@ -268,8 +474,9 @@ export async function runCli(argv: readonly string[], io: CliIo = defaultIo): Pr
         return 1;
       }
 
+      const { runBuild } = await import('./build.ts');
       const result = await runBuild({
-        workspaceRoot: resolvedWorkspaceRoot!,
+        workspaceRoot: requireWorkspaceRoot(),
       });
       io.stdout.write(`${formatBuildSummary(result)}\n`);
       return 0;
@@ -281,16 +488,19 @@ export async function runCli(argv: readonly string[], io: CliIo = defaultIo): Pr
         return 1;
       }
 
+      const { runPublish } = await import('./publish.ts');
       const result = await runPublish({
-        workspaceRoot: resolvedWorkspaceRoot!,
+        workspaceRoot: requireWorkspaceRoot(),
+        env: options.frontendMode ? { WEBSTIR_FRONTEND_MODE: options.frontendMode } : undefined,
       });
       io.stdout.write(`${formatPublishSummary(result)}\n`);
       return 0;
     }
 
     if (command === 'enable') {
+      const { runEnable } = await import('./enable.ts');
       const result = await runEnable({
-        workspaceRoot: resolvedWorkspaceRoot!,
+        workspaceRoot: requireWorkspaceRoot(),
         args: options.positionals,
       });
       io.stdout.write(`${formatEnableSummary(result)}\n`);
@@ -308,11 +518,12 @@ export async function runCli(argv: readonly string[], io: CliIo = defaultIo): Pr
         return 1;
       }
 
+      const { runRepair } = await import('./repair.ts');
       const result = await runRepair({
-        workspaceRoot: resolvedWorkspaceRoot!,
+        workspaceRoot: requireWorkspaceRoot(),
         rawArgs: options.rawArgs,
       });
-      io.stdout.write(`${formatRepairSummary(result)}\n`);
+      io.stdout.write(`${options.json ? formatRepairJson(result) : formatRepairSummary(result)}\n`);
       return 0;
     }
 
@@ -322,8 +533,9 @@ export async function runCli(argv: readonly string[], io: CliIo = defaultIo): Pr
         return 1;
       }
 
+      const { runRefresh } = await import('./refresh.ts');
       const result = await runRefresh({
-        workspaceRoot: resolvedWorkspaceRoot!,
+        workspaceRoot: requireWorkspaceRoot(),
         args: options.positionals,
       });
       io.stdout.write(`${formatRefreshSummary(result)}\n`);
@@ -335,8 +547,9 @@ export async function runCli(argv: readonly string[], io: CliIo = defaultIo): Pr
       return 1;
     }
 
+    const { runWatch } = await import('./watch.ts');
     await runWatch({
-      workspaceRoot: resolvedWorkspaceRoot!,
+      workspaceRoot: requireWorkspaceRoot(),
       host: options.host,
       port: options.port,
       verbose: options.verbose,
@@ -355,7 +568,9 @@ interface ParsedCommandOptions {
   readonly workspaceRoot?: string;
   readonly host?: string;
   readonly port?: number;
+  readonly frontendMode?: 'bundle' | 'ssg';
   readonly dryRun: boolean;
+  readonly json: boolean;
   readonly verbose: boolean;
   readonly hmrVerbose: boolean;
   readonly positionals: readonly string[];
@@ -366,12 +581,14 @@ interface ParsedCommandOptions {
 
 function parseCommandOptions(
   args: readonly string[],
-  options: { readonly allowUnknownOptions?: boolean } = {}
+  options: { readonly allowUnknownOptions?: boolean } = {},
 ): ParsedCommandOptions {
   let workspaceRoot: string | undefined;
   let host: string | undefined;
   let port: number | undefined;
+  let frontendMode: 'bundle' | 'ssg' | undefined;
   let dryRun = false;
+  let json = false;
   let verbose = false;
   let hmrVerbose = false;
   const positionals: string[] = [];
@@ -390,7 +607,9 @@ function parseCommandOptions(
           workspaceRoot,
           host,
           port,
+          frontendMode,
           dryRun,
+          json,
           verbose,
           hmrVerbose,
           positionals,
@@ -405,6 +624,89 @@ function parseCommandOptions(
       continue;
     }
 
+    if (arg === '--frontend-mode') {
+      const next = args[index + 1];
+      if (!next || next.startsWith('-')) {
+        return {
+          workspaceRoot,
+          host,
+          port,
+          frontendMode,
+          dryRun,
+          json,
+          verbose,
+          hmrVerbose,
+          positionals,
+          rawArgs: args,
+          help: false,
+          error: 'Missing value for --frontend-mode.',
+        };
+      }
+
+      const normalizedMode = next.toLowerCase();
+      if (normalizedMode !== 'bundle' && normalizedMode !== 'ssg') {
+        return {
+          workspaceRoot,
+          host,
+          port,
+          frontendMode,
+          dryRun,
+          json,
+          verbose,
+          hmrVerbose,
+          positionals,
+          rawArgs: args,
+          help: false,
+          error: `Invalid --frontend-mode value "${next}". Expected bundle or ssg.`,
+        };
+      }
+
+      frontendMode = normalizedMode;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--frontend-mode=')) {
+      const rawMode = arg.slice('--frontend-mode='.length);
+      if (rawMode.length === 0) {
+        return {
+          workspaceRoot,
+          host,
+          port,
+          frontendMode,
+          dryRun,
+          json,
+          verbose,
+          hmrVerbose,
+          positionals,
+          rawArgs: args,
+          help: false,
+          error: 'Missing value for --frontend-mode.',
+        };
+      }
+
+      const normalizedMode = rawMode.toLowerCase();
+      if (normalizedMode !== 'bundle' && normalizedMode !== 'ssg') {
+        return {
+          workspaceRoot,
+          host,
+          port,
+          frontendMode,
+          dryRun,
+          json,
+          verbose,
+          hmrVerbose,
+          positionals,
+          rawArgs: args,
+          help: false,
+          error: `Invalid --frontend-mode value "${rawMode}". Expected bundle or ssg.`,
+        };
+      }
+
+      frontendMode = normalizedMode;
+      continue;
+    }
+
     if (arg === '--host') {
       const next = args[index + 1];
       if (!next || next.startsWith('-')) {
@@ -413,6 +715,7 @@ function parseCommandOptions(
           host,
           port,
           dryRun,
+          json,
           verbose,
           hmrVerbose,
           positionals,
@@ -436,6 +739,7 @@ function parseCommandOptions(
           host,
           port,
           dryRun,
+          json,
           verbose,
           hmrVerbose,
           positionals,
@@ -458,6 +762,7 @@ function parseCommandOptions(
           host,
           port,
           dryRun,
+          json,
           verbose,
           hmrVerbose,
           positionals,
@@ -480,6 +785,11 @@ function parseCommandOptions(
       continue;
     }
 
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
+
     if (arg === '--hmr-verbose') {
       hmrVerbose = true;
       continue;
@@ -491,6 +801,7 @@ function parseCommandOptions(
         host,
         port,
         dryRun,
+        json,
         verbose,
         hmrVerbose,
         positionals,
@@ -513,6 +824,7 @@ function parseCommandOptions(
       host,
       port,
       dryRun,
+      json,
       verbose,
       hmrVerbose,
       positionals,
@@ -526,7 +838,9 @@ function parseCommandOptions(
     workspaceRoot,
     host,
     port,
+    frontendMode,
     dryRun,
+    json,
     verbose,
     hmrVerbose,
     positionals,
@@ -567,3 +881,20 @@ function resolveRealpath(filePath: string): string {
     return path.resolve(filePath);
   }
 }
+
+async function withSuppressedStdout<T>(callback: () => Promise<T>): Promise<T> {
+  const originalWrite = process.stdout.write.bind(process.stdout);
+  const originalLog = console.log;
+  const originalInfo = console.info;
+  process.stdout.write = (() => true) as typeof process.stdout.write;
+  console.log = (() => undefined) as typeof console.log;
+  console.info = (() => undefined) as typeof console.info;
+
+  try {
+    return await callback();
+  } finally {
+    process.stdout.write = originalWrite;
+    console.log = originalLog;
+    console.info = originalInfo;
+  }
+}