// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. // See LICENSE in the project root for license information. // IMPORTANT: This file is bundled into install-run-rush.js and must use only Node.js built-ins. import * as crypto from 'node:crypto'; import * as fs from 'node:fs'; import * as os from 'node:os'; import * as path from 'node:path'; import type { CommandJson, ICommandLineJson } from '../api/CommandLineJson'; import { NATIVE_RUSH_COMMANDS } from '../logic/RushCommandLineConstants'; import type { ILogger, LogPrivacyClassification } from '../utilities/npmrcUtilities'; import { BOOTSTRAP_BUFFER_MAX_BYTES, BOOTSTRAP_BUFFER_TRUNCATED_EXTENSION_NAME, BOOTSTRAP_EXTERNAL_CHUNK_MAX_BYTES, BOOTSTRAP_PROTOCOL_MAJOR, RUSH_REPORTER_BOOTSTRAP_HANDOFF_ENV_VAR, RUSH_REPORTER_BOOTSTRAP_NONCE_ENV_VAR, encodeBootstrapEnvelope } from './generated/BootstrapProtocol'; const TRUNCATION_NOTICE_RESERVE_BYTES: number = 512; const BOOTSTRAP_HANDOFF_FILE_PREFIX: string = 'rush-reporter-bootstrap-'; const BOOTSTRAP_HANDOFF_FILE_SUFFIX: string = '.ndjson'; const SUPPORTED_REPORTERS: ReadonlySet = new Set([ 'default', 'ai', 'json', 'plaintext', 'file', 'legacy' ]); const SUPPORTED_LOG_LEVELS: ReadonlySet = new Set(['quiet', 'normal', 'verbose', 'debug']); type BootstrapStream = 'stdout' | 'stderr'; interface IBootstrapEventInput { readonly type: string; readonly privacy: 'public' | 'local-sensitive'; readonly payload: unknown; } interface IBufferedBootstrapEntry { readonly line: string; readonly bytes: number; readonly required: boolean; readonly fallbackWrite?: IFallbackWrite; } interface IFallbackWrite { readonly stream: BootstrapStream; readonly text: string; } export interface IInstallRunRushBootstrapOptions { readonly argv: readonly string[]; readonly env: Record; readonly rushJsonFolder: string; readonly rushVersion: string; readonly bootstrapVersion: string; readonly commandName: 'rush' | 'rush-pnpm' | 'rushx'; readonly quiet: boolean; readonly stdout?: (text: string) => void; readonly stderr?: (text: string) => void; readonly handoffDirectory?: string; readonly maxBytes?: number; readonly now?: () => string; readonly randomUUID?: () => string; } export interface IInstallRunRushBootstrap { readonly enabled: boolean; readonly logger: ILogger; readonly externalOutputCaptureMaxBytes: number | undefined; readonly externalOutputHandler: | ((stream: BootstrapStream, text: string, wasRendered: boolean) => void) | undefined; readonly externalOutputLiveStreams: Readonly<{ stdout: boolean; stderr: boolean }> | undefined; readonly externalOutputOverflowHandler: (() => void) | undefined; readonly prepareToRun: (() => void) | undefined; } function readFlagValues(argv: readonly string[], flag: string, strict: boolean): string[] { const result: string[] = []; const prefix: string = `${flag}=`; for (let index: number = 0; index < argv.length; index++) { const argument: string = argv[index]; if (argument === '--') { break; } let value: string | undefined; if (argument.startsWith(prefix)) { value = argument.slice(prefix.length); } else if (argument === flag) { value = argv[index + 1]; if (!value || value.startsWith('-')) { if (strict) { throw new Error(`${flag} requires a value.`); } continue; } index++; } if (value !== undefined) { if (!value) { if (strict) { throw new Error(`${flag} requires a value.`); } continue; } if (strict && result.length > 0) { throw new Error(`${flag} may be specified only once.`); } result.push(value); } } return result; } function readMultipleFlagValues(argv: readonly string[], flag: string): string[] { const result: string[] = []; const prefix: string = `${flag}=`; for (let index: number = 0; index < argv.length; index++) { const argument: string = argv[index]; if (argument === '--') { break; } let value: string | undefined; if (argument.startsWith(prefix)) { value = argument.slice(prefix.length); } else if (argument === flag) { value = argv[index + 1]; if (!value || value.startsWith('-')) { throw new Error(`${flag} requires a value.`); } index++; } if (value !== undefined) { if (!value) { throw new Error(`${flag} requires a value.`); } result.push(value); } } return result; } function readBootstrapConfiguration(filePath: string): T | undefined { let contents: string; try { contents = fs.readFileSync(filePath, 'utf8'); } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') { return undefined; } throw error; } // Remove trailing commas only outside quoted strings, after stripping comments. return JSON.parse( stripJsonComments(contents).replace( /("(?:\\.|[^"\\])*")|,\s*(?=[}\]])/g, (match: string, quoted: string | undefined) => (quoted === undefined ? '' : match) ) ) as T; } function ownsImplicitOutput(options: IInstallRunRushBootstrapOptions): boolean { let actionName: string | undefined; for (let index: number = 0; index < options.argv.length; index++) { const argument: string = options.argv[index]; if (argument === '--') break; if (argument === '--reporter' || argument === '--log-level' || argument === '--output') { if (options.argv[index + 1] && !options.argv[index + 1].startsWith('-')) index++; } else if (!argument.startsWith('-')) { actionName = argument; break; } } if (!actionName) return false; if (NATIVE_RUSH_COMMANDS.has(actionName)) return true; const configFolder: string = path.join(options.rushJsonFolder, 'common', 'config', 'rush'); const plugins: { plugins?: readonly unknown[] } | undefined = readBootstrapConfiguration( path.join(configFolder, 'rush-plugins.json') ); if (plugins?.plugins?.length) return false; const commandLine: ICommandLineJson | undefined = readBootstrapConfiguration( path.join(configFolder, 'command-line.json') ); const command: CommandJson | undefined = commandLine?.commands?.find( (candidate) => candidate.name === actionName ); if (!command && actionName !== 'build' && actionName !== 'rebuild') return false; const usesBuildParameters: boolean = actionName === 'rebuild' && !command; return !commandLine?.parameters?.some( (parameter) => parameter.longName === '--output' && (parameter.associatedCommands?.includes(actionName) || (usesBuildParameters && parameter.associatedCommands?.includes('build'))) ); } function repositoryUsesRushReporter(rushJsonFolder: string): boolean { const experimentsPath: string = path.join(rushJsonFolder, 'common', 'config', 'rush', 'experiments.json'); let contents: string; try { contents = fs.readFileSync(experimentsPath, 'utf8'); } catch (error) { const code: unknown = (error as NodeJS.ErrnoException).code; if (code === 'ENOENT') { return false; } throw error; } const matches: RegExpMatchArray[] = [ ...stripJsonComments(contents).matchAll(/"useRushReporter"\s*:\s*(true|false)/g) ]; return matches.length > 0 && matches[matches.length - 1][1] === 'true'; } function stripJsonComments(text: string): string { let result: string = ''; let inString: boolean = false; let escaped: boolean = false; let lineComment: boolean = false; let blockComment: boolean = false; for (let index: number = 0; index < text.length; index++) { const character: string = text[index]; const nextCharacter: string | undefined = text[index + 1]; if (lineComment) { if (character === '\n' || character === '\r') { lineComment = false; result += character; } continue; } if (blockComment) { if (character === '*' && nextCharacter === '/') { blockComment = false; index++; } else if (character === '\n' || character === '\r') { result += character; } continue; } if (inString) { result += character; if (escaped) { escaped = false; } else if (character === '\\') { escaped = true; } else if (character === '"') { inString = false; } continue; } if (character === '"') { inString = true; result += character; } else if (character === '/' && nextCharacter === '/') { lineComment = true; index++; } else if (character === '/' && nextCharacter === '*') { blockComment = true; index++; } else { result += character; } } return result; } interface IParsedVersion { readonly core: readonly [number, number, number]; readonly prerelease: readonly string[] | undefined; } function parseVersion(version: string): IParsedVersion | undefined { const match: RegExpMatchArray | null = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version); if (!match) { return undefined; } return { core: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease: match[4]?.split('.') }; } function comparePrerelease( left: readonly string[] | undefined, right: readonly string[] | undefined ): number { if (!left) { return right ? 1 : 0; } if (!right) { return -1; } const length: number = Math.max(left.length, right.length); for (let index: number = 0; index < length; index++) { const leftPart: string | undefined = left[index]; const rightPart: string | undefined = right[index]; if (leftPart === undefined) { return -1; } if (rightPart === undefined) { return 1; } if (leftPart === rightPart) { continue; } const leftNumeric: boolean = /^\d+$/.test(leftPart); const rightNumeric: boolean = /^\d+$/.test(rightPart); if (leftNumeric && rightNumeric) { return Number(leftPart) - Number(rightPart); } if (leftNumeric !== rightNumeric) { return leftNumeric ? -1 : 1; } return leftPart < rightPart ? -1 : 1; } return 0; } function supportsBootstrapHandoff(rushVersion: string, bootstrapVersion: string): boolean { const rush: IParsedVersion | undefined = parseVersion(rushVersion); const bootstrap: IParsedVersion | undefined = parseVersion(bootstrapVersion); if (!rush || !bootstrap) { return false; } for (let index: number = 0; index < rush.core.length; index++) { if (rush.core[index] !== bootstrap.core[index]) { return rush.core[index] > bootstrap.core[index]; } } return comparePrerelease(rush.prerelease, bootstrap.prerelease) >= 0; } function* chunkUtf8Text(text: string, maxChunkBytes: number): Iterable { let chunkStart: number = 0; let chunkBytes: number = 0; let offset: number = 0; while (offset < text.length) { const codePoint: number = text.codePointAt(offset)!; const codeUnits: number = codePoint > 0xffff ? 2 : 1; const codePointBytes: number = codePoint <= 0x7f ? 1 : codePoint <= 0x7ff ? 2 : codePoint <= 0xffff ? 3 : 4; if (chunkBytes > 0 && chunkBytes + codePointBytes > maxChunkBytes) { yield text.slice(chunkStart, offset); chunkStart = offset; chunkBytes = 0; } chunkBytes += codePointBytes; offset += codeUnits; } if (chunkStart < text.length) { yield text.slice(chunkStart); } } class InstallRunRushBootstrap implements IInstallRunRushBootstrap { public readonly enabled: boolean = true; public readonly logger: ILogger; public readonly externalOutputCaptureMaxBytes: number; public readonly externalOutputHandler: ( stream: BootstrapStream, text: string, wasRendered: boolean ) => void; public readonly externalOutputLiveStreams: Readonly<{ stdout: boolean; stderr: boolean }>; public readonly externalOutputOverflowHandler: () => void; public readonly prepareToRun: () => void; readonly #entries: IBufferedBootstrapEntry[]; readonly #env: Record; readonly #stdout: (text: string) => void; readonly #stderr: (text: string) => void; readonly #handoffDirectory: string; readonly #maxBytes: number; readonly #now: () => string; readonly #randomUUID: () => string; readonly #sessionId: string; readonly #sourceVersion: string; readonly #entryLimit: number; readonly #fallbackStdoutStream: BootstrapStream; #usedBytes: number; #nextSequence: number; #nextEventNumber: number; #droppedReplaceable: number; #droppedRequired: number; #failureFlushed: boolean; public constructor(options: IInstallRunRushBootstrapOptions, liveStdout: boolean) { this.#entries = []; this.#env = options.env; this.#stdout = options.stdout ?? ((text: string) => process.stdout.write(text)); this.#stderr = options.stderr ?? ((text: string) => process.stderr.write(text)); this.#handoffDirectory = options.handoffDirectory ?? os.tmpdir(); this.#maxBytes = options.maxBytes ?? BOOTSTRAP_BUFFER_MAX_BYTES; this.#now = options.now ?? (() => new Date().toISOString()); this.#randomUUID = options.randomUUID ?? (() => crypto.randomUUID()); this.#sessionId = `rush_bootstrap_${process.pid}_${this.#randomUUID()}`; this.#sourceVersion = options.bootstrapVersion; this.#entryLimit = this.#maxBytes - TRUNCATION_NOTICE_RESERVE_BYTES; this.#fallbackStdoutStream = liveStdout ? 'stdout' : 'stderr'; if (this.#entryLimit <= 0) { throw new RangeError(`maxBytes must be greater than ${TRUNCATION_NOTICE_RESERVE_BYTES}.`); } this.#usedBytes = 0; this.#nextSequence = 1; this.#nextEventNumber = 1; this.#droppedReplaceable = 0; this.#droppedRequired = 0; this.#failureFlushed = false; this.externalOutputCaptureMaxBytes = this.#maxBytes; this.externalOutputLiveStreams = { stdout: liveStdout, stderr: true }; this.#addEvent({ type: 'sessionStarted', privacy: 'public', payload: { rushVersion: options.rushVersion } }); this.logger = { info: (text: string, privacy: LogPrivacyClassification = 'public') => { this.#addEvent( { type: 'activityChanged', privacy, payload: { kind: 'bootstrap', text } }, { stream: this.#fallbackStdoutStream, text: `${text}\n` } ); }, error: (text: string) => { const droppedRequiredBefore: number = this.#droppedRequired; this.#addExternalOutput('stderr', `${text}\n`, false); this.#flushFailureOutput(); if (this.#droppedRequired > droppedRequiredBefore) { this.#stderr(`${text}\n`); } }, warning: (text: string) => { this.#stderr(`${text}\n`); } }; this.externalOutputHandler = (stream: BootstrapStream, text: string, wasRendered: boolean) => { this.#addExternalOutput(stream, text, wasRendered); }; this.externalOutputOverflowHandler = () => { this.#droppedRequired++; }; this.prepareToRun = () => { this.#writeHandoff(); }; } #addEvent(event: IBootstrapEventInput, fallbackWrite?: IFallbackWrite): void { const required: boolean = event.type !== 'activityChanged'; const line: string = encodeBootstrapEnvelope({ eventId: `boot_${this.#nextEventNumber++}`, sessionId: this.#sessionId, sequence: this.#nextSequence++, timestamp: this.#now(), source: { packageName: 'install-run-rush', packageVersion: this.#sourceVersion }, privacy: event.privacy, required, type: event.type, payload: event.payload }); const bytes: number = Buffer.byteLength(line, 'utf8') + 1; if (this.#usedBytes + bytes <= this.#entryLimit) { this.#entries.push({ line, bytes, required, fallbackWrite }); this.#usedBytes += bytes; return; } if (!required) { this.#droppedReplaceable++; return; } for ( let index: number = 0; this.#usedBytes + bytes > this.#entryLimit && index < this.#entries.length; ) { const entry: IBufferedBootstrapEntry = this.#entries[index]; if (entry.required) { index++; } else { this.#entries.splice(index, 1); this.#usedBytes -= entry.bytes; this.#droppedReplaceable++; } } if (this.#usedBytes + bytes <= this.#entryLimit) { this.#entries.push({ line, bytes, required, fallbackWrite }); this.#usedBytes += bytes; } else { this.#droppedRequired++; } } #addExternalOutput(stream: BootstrapStream, text: string, wasRendered: boolean): void { if (!text) { return; } for (const chunk of chunkUtf8Text(text, BOOTSTRAP_EXTERNAL_CHUNK_MAX_BYTES)) { this.#addEvent( { type: 'externalOutput', privacy: 'local-sensitive', payload: { stream, text: chunk, ...(wasRendered ? { wasRendered: true } : {}) } }, wasRendered ? undefined : { stream: stream === 'stdout' ? this.#fallbackStdoutStream : stream, text: chunk } ); } } #flushFailureOutput(): void { if (this.#failureFlushed) { return; } this.#failureFlushed = true; for (const entry of this.#entries) { const write: IFallbackWrite | undefined = entry.fallbackWrite; if (write) { (write.stream === 'stdout' ? this.#stdout : this.#stderr)(write.text); } } } #writeHandoff(): void { const serialized: string = this.#serializeEvents(); const nonce: string = this.#randomUUID(); const fileName: string = `${BOOTSTRAP_HANDOFF_FILE_PREFIX}${process.pid}-${nonce}${BOOTSTRAP_HANDOFF_FILE_SUFFIX}`; const handoffPath: string = path.join(this.#handoffDirectory, fileName); fs.mkdirSync(this.#handoffDirectory, { recursive: true }); fs.writeFileSync(handoffPath, `${JSON.stringify({ kind: 'bootstrapHandoff', nonce })}\n${serialized}`, { encoding: 'utf8', mode: 0o600, flag: 'wx' }); if (process.platform !== 'win32') { fs.chmodSync(handoffPath, 0o600); } this.#env[RUSH_REPORTER_BOOTSTRAP_HANDOFF_ENV_VAR] = handoffPath; this.#env[RUSH_REPORTER_BOOTSTRAP_NONCE_ENV_VAR] = nonce; } #serializeEvents(): string { const truncated: boolean = this.#droppedReplaceable + this.#droppedRequired > 0; if (truncated) { const notice: string = encodeBootstrapEnvelope({ eventId: 'boot_bufferTruncated', sessionId: this.#sessionId, sequence: this.#nextSequence++, timestamp: this.#now(), source: { packageName: 'install-run-rush', packageVersion: this.#sourceVersion }, privacy: 'public', required: true, type: 'extension', payload: { name: BOOTSTRAP_BUFFER_TRUNCATED_EXTENSION_NAME, droppedReplaceable: this.#droppedReplaceable, droppedOther: 0, droppedRequired: this.#droppedRequired, failed: this.#droppedRequired > 0 } }); if (Buffer.byteLength(notice, 'utf8') + 1 > TRUNCATION_NOTICE_RESERVE_BYTES) { throw new Error('The bootstrap truncation notice exceeded its reserved capacity.'); } this.#entries.push({ line: notice, bytes: Buffer.byteLength(notice, 'utf8') + 1, required: true }); } if (this.#droppedRequired > 0) { throw new Error( `The Rush reporter bootstrap buffer exceeded ${this.#maxBytes} bytes and could not preserve ` + `${this.#droppedRequired} required event(s).` ); } return this.#entries.length > 0 ? `${this.#entries.map((entry: IBufferedBootstrapEntry) => entry.line).join('\n')}\n` : ''; } } function createLegacyBootstrap(options: IInstallRunRushBootstrapOptions): IInstallRunRushBootstrap { const stdout: (text: string) => void = options.stdout ?? ((text: string) => process.stdout.write(text)); const stderr: (text: string) => void = options.stderr ?? ((text: string) => process.stderr.write(text)); const warning: (text: string) => void = (text: string) => stderr(`${text}\n`); return { enabled: false, // Legacy mode cannot create npm captures because it exposes no external output handler. // Keep warning routing available so future diagnostic finalization remains stderr-only. logger: options.quiet ? { info: () => {}, error: (text: string) => stderr(`${text}\n`), warning } : { info: (text: string) => stdout(`${text}\n`), error: (text: string) => stderr(`${text}\n`), warning }, externalOutputHandler: undefined, externalOutputCaptureMaxBytes: undefined, externalOutputLiveStreams: undefined, externalOutputOverflowHandler: undefined, prepareToRun: undefined }; } export function createInstallRunRushBootstrap( options: IInstallRunRushBootstrapOptions ): IInstallRunRushBootstrap { if (BOOTSTRAP_PROTOCOL_MAJOR < 1) { throw new Error('The generated Rush reporter bootstrap protocol is invalid.'); } delete options.env[RUSH_REPORTER_BOOTSTRAP_HANDOFF_ENV_VAR]; delete options.env[RUSH_REPORTER_BOOTSTRAP_NONCE_ENV_VAR]; if (options.commandName !== 'rush') { return createLegacyBootstrap(options); } const environmentReporter: string | undefined = options.env.RUSH_REPORTER?.trim().toLowerCase(); if (environmentReporter === 'legacy') { return createLegacyBootstrap(options); } const repositoryOptIn: boolean = repositoryUsesRushReporter(options.rushJsonFolder); const reporterControlsOwned: boolean = repositoryOptIn || readFlagValues(options.argv, '--reporter', false).some((value: string) => SUPPORTED_REPORTERS.has(value)); if (!reporterControlsOwned) { return createLegacyBootstrap(options); } const explicitReporter: string | undefined = readFlagValues(options.argv, '--reporter', true)[0]; if (explicitReporter !== undefined && !SUPPORTED_REPORTERS.has(explicitReporter)) { throw new Error( `Unsupported reporter ${JSON.stringify(explicitReporter)}. ` + 'Supported values are default, ai, json, plaintext, file, and legacy.' ); } if (explicitReporter === 'legacy') { return createLegacyBootstrap(options); } const logLevelProbe: string[] = readFlagValues(options.argv, '--log-level', false); const logLevelOwned: boolean = explicitReporter !== undefined || (logLevelProbe.length > 0 && logLevelProbe.every((value: string) => SUPPORTED_LOG_LEVELS.has(value))); const explicitLogLevel: string | undefined = logLevelOwned ? readFlagValues(options.argv, '--log-level', true)[0] : undefined; if (explicitLogLevel !== undefined && !SUPPORTED_LOG_LEVELS.has(explicitLogLevel)) { throw new Error( `Unsupported log level ${JSON.stringify(explicitLogLevel)}. ` + 'Supported values are quiet, normal, verbose, and debug.' ); } const explicitOptIn: boolean = explicitReporter !== undefined; if (!supportsBootstrapHandoff(options.rushVersion, options.bootstrapVersion)) { if (explicitOptIn) { throw new Error( `Rush version ${options.rushVersion} does not support the reporter bootstrap requested by ` + `${JSON.stringify(`--reporter=${explicitReporter}`)}. Update the repository Rush version or ` + 'use --reporter=legacy.' ); } return createLegacyBootstrap(options); } const separatorIndex: number = options.argv.indexOf('--'); const commandArgs: readonly string[] = separatorIndex < 0 ? options.argv : options.argv.slice(0, separatorIndex); const isHelp: boolean = commandArgs.includes('--help') || commandArgs.includes('-h'); const outputs: readonly string[] = !isHelp && (explicitOptIn || ownsImplicitOutput(options)) ? readMultipleFlagValues(options.argv, '--output') : []; const outputOwnsStdout: boolean = outputs.some((output: string) => { const match: RegExpExecArray | null = /^([a-z][a-z0-9]*):\/\/(.*)$/i.exec(output); if (!match) { throw new Error(`Invalid --output control: ${JSON.stringify(output)}`); } return match[2].split('?', 1)[0] === 'stdout'; }); const stdoutReserved: boolean = explicitReporter === 'json' || explicitReporter === 'ai' || explicitReporter === 'file' || commandArgs.includes('--json') || outputOwnsStdout; return new InstallRunRushBootstrap(options, !stdoutReserved); }