From ab13a897441e886a81f46ffdcbf4a9ceef02ef6d Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sat, 29 Nov 2025 17:11:50 +0100 Subject: [PATCH] cli-common: polish API surface for run Signed-off-by: Patrik Oldsberg --- packages/cli-common/report.api.md | 6 ++-- packages/cli-common/src/index.ts | 2 +- packages/cli-common/src/run.ts | 33 ++++++++----------- .../build/lib/packager/createDistWorkspace.ts | 4 +-- packages/cli/src/modules/migrate/lib/utils.ts | 4 +-- .../techdocs-cli/src/commands/serve/mkdocs.ts | 8 ++--- .../techdocs-cli/src/commands/serve/serve.ts | 8 ++--- packages/techdocs-cli/src/lib/mkdocsServer.ts | 14 ++++---- 8 files changed, 37 insertions(+), 42 deletions(-) diff --git a/packages/cli-common/report.api.md b/packages/cli-common/report.api.md index a2aba06228..175ec3cb2b 100644 --- a/packages/cli-common/report.api.md +++ b/packages/cli-common/report.api.md @@ -53,13 +53,13 @@ export interface RunChildProcess extends ChildProcess { } // @public -export type RunLogFunc = (data: Buffer) => void; +export type RunOnOutput = (data: Buffer) => void; // @public export type RunOptions = Omit & { env?: Partial; - stdoutLogFunc?: RunLogFunc; - stderrLogFunc?: RunLogFunc; + onStdout?: RunOnOutput; + onStderr?: RunOnOutput; stdio?: SpawnOptions['stdio']; }; diff --git a/packages/cli-common/src/index.ts b/packages/cli-common/src/index.ts index 632aff9eb6..d11601b044 100644 --- a/packages/cli-common/src/index.ts +++ b/packages/cli-common/src/index.ts @@ -30,6 +30,6 @@ export { runCheck, type RunChildProcess, type RunOptions, - type RunLogFunc, + type RunOnOutput, } from './run'; export { ExitCodeError } from './errors'; diff --git a/packages/cli-common/src/run.ts b/packages/cli-common/src/run.ts index 9a0a0975c1..b64d2bb94b 100644 --- a/packages/cli-common/src/run.ts +++ b/packages/cli-common/src/run.ts @@ -24,7 +24,7 @@ import { assertError } from '@backstage/errors'; * * @public */ -export type RunLogFunc = (data: Buffer) => void; +export type RunOnOutput = (data: Buffer) => void; /** * Options for running a child process with {@link run} or related functions. @@ -33,8 +33,8 @@ export type RunLogFunc = (data: Buffer) => void; */ export type RunOptions = Omit & { env?: Partial; - stdoutLogFunc?: RunLogFunc; - stderrLogFunc?: RunLogFunc; + onStdout?: RunOnOutput; + onStderr?: RunOnOutput; stdio?: SpawnOptions['stdio']; }; @@ -69,12 +69,7 @@ export function run(args: string[], options: RunOptions = {}): RunChildProcess { const [name, ...cmdArgs] = args; - const { - stdoutLogFunc, - stderrLogFunc, - stdio: customStdio, - ...spawnOptions - } = options; + const { onStdout, onStderr, stdio: customStdio, ...spawnOptions } = options; const env: NodeJS.ProcessEnv = { ...process.env, FORCE_COLOR: 'true', @@ -85,8 +80,8 @@ export function run(args: string[], options: RunOptions = {}): RunChildProcess { customStdio ?? ([ 'inherit', - stdoutLogFunc ? 'pipe' : 'inherit', - stderrLogFunc ? 'pipe' : 'inherit', + onStdout ? 'pipe' : 'inherit', + onStderr ? 'pipe' : 'inherit', ] as ('inherit' | 'pipe')[]); const child = spawn(name, cmdArgs, { @@ -95,11 +90,11 @@ export function run(args: string[], options: RunOptions = {}): RunChildProcess { env, }) as RunChildProcess; - if (stdoutLogFunc && child.stdout) { - child.stdout.on('data', stdoutLogFunc); + if (onStdout && child.stdout) { + child.stdout.on('data', onStdout); } - if (stderrLogFunc && child.stderr) { - child.stderr.on('data', stderrLogFunc); + if (onStderr && child.stderr) { + child.stderr.on('data', onStderr); } const commandName = args.join(' '); @@ -175,13 +170,13 @@ export async function runOutput( try { await run(args, { ...options, - stdoutLogFunc: data => { + onStdout: data => { stdoutChunks.push(data); - options?.stdoutLogFunc?.(data); + options?.onStdout?.(data); }, - stderrLogFunc: data => { + onStderr: data => { stderrChunks.push(data); - options?.stderrLogFunc?.(data); + options?.onStderr?.(data); }, }).waitForExit(); diff --git a/packages/cli/src/modules/build/lib/packager/createDistWorkspace.ts b/packages/cli/src/modules/build/lib/packager/createDistWorkspace.ts index cde4d666d0..90635f1a73 100644 --- a/packages/cli/src/modules/build/lib/packager/createDistWorkspace.ts +++ b/packages/cli/src/modules/build/lib/packager/createDistWorkspace.ts @@ -230,8 +230,8 @@ export async function createDistWorkspace( worker: async ({ name, dir, args }) => { await run(['yarn', 'run', 'build', ...(args || [])], { cwd: dir, - stdoutLogFunc: prefixLogFunc(`${name}: `, 'stdout'), - stderrLogFunc: prefixLogFunc(`${name}: `, 'stderr'), + onStdout: prefixLogFunc(`${name}: `, 'stdout'), + onStderr: prefixLogFunc(`${name}: `, 'stderr'), }).waitForExit(); }, }); diff --git a/packages/cli/src/modules/migrate/lib/utils.ts b/packages/cli/src/modules/migrate/lib/utils.ts index 955cefde1d..c85f56dabb 100644 --- a/packages/cli/src/modules/migrate/lib/utils.ts +++ b/packages/cli/src/modules/migrate/lib/utils.ts @@ -39,8 +39,8 @@ export async function runYarnInstall() { ), ), }, - stdoutLogFunc: data => installOutput.push(data), - stderrLogFunc: data => installOutput.push(data), + onStdout: data => installOutput.push(data), + onStderr: data => installOutput.push(data), }).waitForExit(); spinner.succeed(); } catch (error) { diff --git a/packages/techdocs-cli/src/commands/serve/mkdocs.ts b/packages/techdocs-cli/src/commands/serve/mkdocs.ts index 3938764fed..cd1072a88f 100644 --- a/packages/techdocs-cli/src/commands/serve/mkdocs.ts +++ b/packages/techdocs-cli/src/commands/serve/mkdocs.ts @@ -18,7 +18,7 @@ import { OptionValues } from 'commander'; import openBrowser from 'react-dev-utils/openBrowser'; import { createLogger } from '../../lib/utility'; import { runMkdocsServer } from '../../lib/mkdocsServer'; -import { RunLogFunc } from '@backstage/cli-common'; +import { RunOnOutput } from '@backstage/cli-common'; import { getMkdocsYml } from '@backstage/plugin-techdocs-node'; import fs from 'fs-extra'; import { checkIfDockerIsOperational } from './utils'; @@ -45,7 +45,7 @@ export default async function serveMkdocs(opts: OptionValues) { // We want to open browser only once based on a log. let boolOpenBrowserTriggered = false; - const logFunc: RunLogFunc = data => { + const logFunc: RunOnOutput = data => { // Sometimes the lines contain an unnecessary extra new line in between const logLines = data.toString().split('\n'); const logPrefix = opts.docker ? '[docker/mkdocs]' : '[mkdocs]'; @@ -80,8 +80,8 @@ export default async function serveMkdocs(opts: OptionValues) { dockerEntrypoint: opts.dockerEntrypoint, dockerOptions: opts.dockerOption, useDocker: opts.docker, - stdoutLogFunc: logFunc, - stderrLogFunc: logFunc, + onStdout: logFunc, + onStderr: logFunc, }); // Keep waiting for user to cancel the process diff --git a/packages/techdocs-cli/src/commands/serve/serve.ts b/packages/techdocs-cli/src/commands/serve/serve.ts index c325a99871..a0d0030c6b 100644 --- a/packages/techdocs-cli/src/commands/serve/serve.ts +++ b/packages/techdocs-cli/src/commands/serve/serve.ts @@ -17,7 +17,7 @@ import { OptionValues } from 'commander'; import path from 'path'; import openBrowser from 'react-dev-utils/openBrowser'; -import { findPaths, RunLogFunc } from '@backstage/cli-common'; +import { findPaths, RunOnOutput } from '@backstage/cli-common'; import HTTPServer from '../../lib/httpServer'; import { runMkdocsServer } from '../../lib/mkdocsServer'; import { createLogger } from '../../lib/utility'; @@ -82,7 +82,7 @@ export default async function serve(opts: OptionValues) { } let mkdocsServerHasStarted = false; - const mkdocsLogFunc: RunLogFunc = data => { + const mkdocsLogFunc: RunOnOutput = data => { // Sometimes the lines contain an unnecessary extra new line const logLines = data.toString().split('\n'); const logPrefix = opts.docker ? '[docker/mkdocs]' : '[mkdocs]'; @@ -112,8 +112,8 @@ export default async function serve(opts: OptionValues) { dockerEntrypoint: opts.dockerEntrypoint, dockerOptions: opts.dockerOption, useDocker: opts.docker, - stdoutLogFunc: mkdocsLogFunc, - stderrLogFunc: mkdocsLogFunc, + onStdout: mkdocsLogFunc, + onStderr: mkdocsLogFunc, mkdocsConfigFileName: mkdocsYmlPath, mkdocsParameterClean: opts.mkdocsParameterClean, mkdocsParameterDirtyReload: opts.mkdocsParameterDirtyreload, diff --git a/packages/techdocs-cli/src/lib/mkdocsServer.ts b/packages/techdocs-cli/src/lib/mkdocsServer.ts index 929ee77fb1..c557015256 100644 --- a/packages/techdocs-cli/src/lib/mkdocsServer.ts +++ b/packages/techdocs-cli/src/lib/mkdocsServer.ts @@ -14,7 +14,7 @@ * limitations under the License. */ -import { run, RunChildProcess, RunLogFunc } from '@backstage/cli-common'; +import { run, RunChildProcess, RunOnOutput } from '@backstage/cli-common'; export const runMkdocsServer = (options: { port?: string; @@ -22,8 +22,8 @@ export const runMkdocsServer = (options: { dockerImage?: string; dockerEntrypoint?: string; dockerOptions?: string[]; - stdoutLogFunc?: RunLogFunc; - stderrLogFunc?: RunLogFunc; + onStdout?: RunOnOutput; + onStderr?: RunOnOutput; mkdocsConfigFileName?: string; mkdocsParameterClean?: boolean; mkdocsParameterDirtyReload?: boolean; @@ -62,8 +62,8 @@ export const runMkdocsServer = (options: { ...(options.mkdocsParameterStrict ? ['--strict'] : []), ], { - stdoutLogFunc: options.stdoutLogFunc, - stderrLogFunc: options.stderrLogFunc, + onStdout: options.onStdout, + onStderr: options.onStderr, }, ); } @@ -82,8 +82,8 @@ export const runMkdocsServer = (options: { ...(options.mkdocsParameterStrict ? ['--strict'] : []), ], { - stdoutLogFunc: options.stdoutLogFunc, - stderrLogFunc: options.stderrLogFunc, + onStdout: options.onStdout, + onStderr: options.onStderr, }, ); };