/* * Copyright 2026, Salesforce, Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ import fs from 'node:fs'; import { join, dirname, basename } from 'node:path'; import { Messages, SfError } from '@salesforce/core'; import { Env, omit } from '@salesforce/kit'; import type { AnyJson, KeyValue } from '@salesforce/ts-types'; import { Interfaces } from '@oclif/core'; import { Diagnostics, DiagnosticStatus } from './diagnostics.js'; export type SfDoctor = { addCommandName(commandName: string): void; addDiagnosticStatus(status: DiagnosticStatus): void; addPluginData(pluginName: string, data: AnyJson): void; addSuggestion(suggestion: string): void; closeStderr(): void; closeStdout(): void; createStderrWriteStream(fullPath: string): void; createStdoutWriteStream(fullPath: string): void; diagnose(): Array>; getDiagnosis(): SfDoctorDiagnosis; getDoctoredFilePath(filePath: string): string; setExitCode(code: string | number): void; writeFileSync(filePath: string, contents: string): string; writeStderr(contents: string): Promise; writeStdout(contents: string): Promise; }; // oclif has some properties marked as optional in the Interface, but they will be present after Load() is called type CliConfig = Record & { bin: string; nodeEngine: string; windows: boolean; userAgent: string; shell: string; channel: string; }; export type SfDoctorDiagnosis = { versionDetail: Omit & { pluginVersions: string[] }; sfdxEnvVars: Array>; sfEnvVars: Array>; proxyEnvVars: Array>; cliConfig: CliConfig; pluginSpecificData: { [pluginName: string]: AnyJson[] }; diagnosticResults: DiagnosticStatus[]; suggestions: string[]; commandName?: string; commandExitCode?: string | number; logFilePaths: string[]; }; Messages.importMessagesDirectoryFromMetaUrl(import.meta.url); const messages = Messages.loadMessages('@salesforce/plugin-info', 'doctor'); const PINNED_SUGGESTIONS = [ messages.getMessage('pinnedSuggestions.checkGitHubIssues'), messages.getMessage('pinnedSuggestions.checkSfdcStatus'), ]; // private config from the CLI // eslint-disable-next-line no-underscore-dangle let __cliConfig: Interfaces.Config; export class Doctor implements SfDoctor { // singleton instance private static instance: SfDoctor; public readonly id: number; // Contains all gathered data and results of diagnostics. private readonly diagnosis: SfDoctorDiagnosis; private stdoutWriteStream: fs.WriteStream | undefined; private stderrWriteStream: fs.WriteStream | undefined; private constructor(config: Interfaces.Config) { this.id = Date.now(); __cliConfig = config; const sfdxEnvVars = new Env().entries().filter((e) => e[0].startsWith('SFDX_')); const sfEnvVars = new Env().entries().filter((e) => e[0].startsWith('SF_')); const proxyEnvVars = new Env() .entries() .filter((e) => ['http_proxy', 'https_proxy', 'no_proxy'].includes(e[0].toLowerCase())); const cliConfig = omit(config, [ 'plugins', 'pjson', 'userPJSON', 'options', '_commandIDs', 'rootPlugin', ]) as CliConfig; // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access cliConfig.nodeEngine = config.pjson.engines.node as string; const { pluginVersions, ...versionDetails } = config.versionDetails; this.diagnosis = { versionDetail: { ...versionDetails, pluginVersions: formatPlugins(config, pluginVersions ?? {}) }, sfdxEnvVars, sfEnvVars, proxyEnvVars, cliConfig, pluginSpecificData: {}, diagnosticResults: [], suggestions: [...PINNED_SUGGESTIONS], logFilePaths: [], commandExitCode: 0, }; } /** * Returns a singleton instance of an SfDoctor. */ public static getInstance(): SfDoctor { if (!Doctor.instance) { throw new SfError(messages.getMessage('doctorNotInitializedError'), 'SfDoctorInitError'); } return Doctor.instance; } /** * Returns true if Doctor has been initialized. */ public static isDoctorEnabled(): boolean { return !!Doctor.instance; } /** * Initializes a new instance of SfDoctor with CLI config data. * * @param config The oclif config for the CLI * @param versionDetail The result of running a verbose version command * @returns An instance of SfDoctor */ public static init(config: Interfaces.Config): SfDoctor { if (Doctor.instance) { return Doctor.instance; } Doctor.instance = new this(config); return Doctor.instance; } /** * Use the gathered data to discover potential problems by running all diagnostics. * * @returns An array of diagnostic promises. */ public diagnose(): Array> { return new Diagnostics(this, __cliConfig).run(); } /** * Add a suggestion in the form of: * "Because of we recommend to " * * @param suggestion A suggestion for the CLI user to try based on gathered data */ public addSuggestion(suggestion: string): void { this.diagnosis.suggestions.push(suggestion); } /** * Add a diagnostic test status. * * @param status a diagnostic test status */ public addDiagnosticStatus(status: DiagnosticStatus): void { this.diagnosis.diagnosticResults.push(status); } /** * Add diagnostic data that is specific to the passed plugin name. * * @param pluginName The name in the plugin's package.json * @param data Any data to add to the doctor diagnosis that is specific * to the plugin and a valid JSON value. */ public addPluginData(pluginName: string, data: AnyJson): void { const pluginEntry = this.diagnosis.pluginSpecificData[pluginName]; if (pluginEntry) { pluginEntry.push(data); } else { this.diagnosis.pluginSpecificData[pluginName] = [data]; } } /** * Add a command name that the doctor will run to the diagnosis data for * use by diagnostics. * * @param commandName The name of the command that the doctor will run. E.g., "force:org:list" */ public addCommandName(commandName: string): void { this.diagnosis.commandName = commandName; } /** * Returns all the data gathered, paths to doctor files, and recommendations. */ public getDiagnosis(): SfDoctorDiagnosis { return { ...this.diagnosis }; } /** * Write a file with the provided path. The file name will be prepended * with this doctor's id. * * E.g., `name = myContent.json` will write `1658350735579-myContent.json` * * @param filePath The path of the file to write. * @param contents The string contents to write. * @return The full path to the file. */ public writeFileSync(filePath: string, contents: string): string { const fullPath = this.getDoctoredFilePath(filePath); createOutputDir(fullPath); this.diagnosis.logFilePaths.push(fullPath); fs.writeFileSync(fullPath, contents); return fullPath; } public writeStdout(contents: string): Promise { if (!this.stdoutWriteStream) { throw new SfError(messages.getMessage('doctorNotInitializedError'), 'SfDoctorInitError'); } return writeFile(this.stdoutWriteStream, contents); } public writeStderr(contents: string): Promise { if (!this.stderrWriteStream) { throw new SfError(messages.getMessage('doctorNotInitializedError'), 'SfDoctorInitError'); } return writeFile(this.stderrWriteStream, contents); } public createStdoutWriteStream(fullPath: string): void { if (!this.stdoutWriteStream) { createOutputDir(fullPath); this.stdoutWriteStream = fs.createWriteStream(fullPath); } } public createStderrWriteStream(fullPath: string): void { if (!this.stderrWriteStream) { createOutputDir(fullPath); this.stderrWriteStream = fs.createWriteStream(join(fullPath)); } } public closeStderr(): void { this.stderrWriteStream?.end(); this.stderrWriteStream?.close(); } public closeStdout(): void { this.stdoutWriteStream?.end(); this.stdoutWriteStream?.close(); } public getDoctoredFilePath(filePath: string): string { const dir = dirname(filePath); const fileName = `${this.id}-${basename(filePath)}`; const fullPath = join(dir, fileName); this.diagnosis.logFilePaths.push(fullPath); return fullPath; } public setExitCode(code: string | number): void { this.diagnosis.commandExitCode = code; } } export function formatPlugins( config: Interfaces.Config, plugins: Record ): string[] { function getFriendlyName(name: string): string { const scope = config?.pjson?.oclif?.scope; if (!scope) return name; const match = name.match(`@${scope}/plugin-(.+)`); if (!match) return name; return match[1]; } return Object.entries(plugins) .map(([name, plugin]) => ({ name, ...plugin })) .sort((a, b) => (a.name > b.name ? 1 : -1)) .map((plugin) => `${getFriendlyName(plugin.name)} ${plugin.version} (${plugin.type}) ${ plugin.type === 'link' ? plugin.root : '' }`.trim() ); } const createOutputDir = (fullPath: string): void => { const dir = dirname(fullPath); if (!fs.existsSync(dir)) { fs.mkdirSync(dir, { recursive: true }); } }; const writeFile = (stream: fs.WriteStream, contents: string): Promise => Promise.resolve(stream.write(contents));