ExplorerCommandLineParser.ts

// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.

import process from 'node:process';
import * as path from 'node:path';
import type { ChildProcess } from 'node:child_process';

import express from 'express';
import yaml from 'js-yaml';
import cors from 'cors';

import { Executable, FileSystem, type IPackageJson, JsonFile } from '@rushstack/node-core-library';
import { type ITerminal, Colorize } from '@rushstack/terminal';
import {
  type CommandLineFlagParameter,
  CommandLineParser,
  type IRequiredCommandLineStringParameter
} from '@rushstack/ts-command-line';

import {
  type LfxGraph,
  lfxGraphSerializer,
  type IAppContext,
  type IJsonLfxGraph,
  type IJsonLfxWorkspace
} from '../../../build/lfx-shared';
import * as lockfilePath from '../../graph/lockfilePath';
import type { IAppState } from '../../state';
import { init } from '../../utils/init';
import { PnpmfileRunner } from '../../graph/PnpmfileRunner';
import * as lfxGraphLoader from '../../graph/lfxGraphLoader';
import { LFX_PACKAGE_NAME, LFX_VERSION } from '../../utils/constants';
import { type IPackageUpdateResult, PackageUpdateChecker } from '../../utils/PackageUpdateChecker';

const EXPLORER_TOOL_FILENAME: 'lockfile-explorer' = 'lockfile-explorer';

function printUpdateNotification(
  result: { latestVersion: string; isOutdated: boolean } | undefined,
  terminal: ITerminal
): void {
  if (result?.isOutdated) {
    terminal.writeLine(
      Colorize.yellow(
        `\nUpdate available: ${LFX_VERSION} → ${result.latestVersion}\n` +
          `Run: npm install -g ${LFX_PACKAGE_NAME}\n`
      )
    );
  }
}

export class ExplorerCommandLineParser extends CommandLineParser {
  public readonly globalTerminal: ITerminal;

  readonly #debugParameter: CommandLineFlagParameter;
  readonly #subspaceParameter: IRequiredCommandLineStringParameter;

  public constructor(terminal: ITerminal) {
    super({
      toolFilename: EXPLORER_TOOL_FILENAME,
      toolDescription:
        'Lockfile Explorer is a desktop app for investigating and solving version conflicts in a PNPM workspace.'
    });

    this.#debugParameter = this.defineFlagParameter({
      parameterLongName: '--debug',
      parameterShortName: '-d',
      description: 'Show the full call stack if an error occurs while executing the tool'
    });

    this.#subspaceParameter = this.defineStringParameter({
      parameterLongName: '--subspace',
      argumentName: 'SUBSPACE_NAME',
      description: 'Specifies an individual Rush subspace to check.',
      defaultValue: 'default'
    });

    this.globalTerminal = terminal;
  }

  public get isDebug(): boolean {
    return this.#debugParameter.value;
  }

  protected override async onExecuteAsync(): Promise<void> {
    const terminal: ITerminal = this.globalTerminal;

    terminal.writeLine(
      Colorize.bold(`\nRush Lockfile Explorer ${LFX_VERSION}`) +
        Colorize.cyan(' - https://lfx.rushstack.io/\n')
    );

    // Start the update check now so it runs concurrently with server setup.
    // The result is awaited and displayed inside app.listen once the server is ready.
    const updateChecker: PackageUpdateChecker = new PackageUpdateChecker({
      packageName: LFX_PACKAGE_NAME,
      currentVersion: LFX_VERSION,
      // In debug mode, bypass the cache so the notice appears immediately.
      forceCheck: this.isDebug
    });
    const updateCheckPromise: Promise<IPackageUpdateResult | undefined> = updateChecker.tryGetUpdateAsync();

    const PORT: number = 8091;
    // Must not have a trailing slash
    const SERVICE_URL: string = `http://localhost:${PORT}`;

    const appState: IAppState = init({
      appVersion: LFX_VERSION,
      debugMode: this.isDebug,
      subspaceName: this.#subspaceParameter.value
    });

    const lfxWorkspace: IJsonLfxWorkspace = appState.lfxWorkspace;

    // Important: This must happen after init() reads the current working directory
    process.chdir(appState.lockfileExplorerProjectRoot);

    const distFolderPath: string = `${appState.lockfileExplorerProjectRoot}/dist`;
    const app: express.Application = express();
    app.use(express.json());
    app.use(cors());

    // Variable used to check if the front-end client is still connected
    let awaitingFirstConnect: boolean = true;
    let isClientConnected: boolean = false;
    let disconnected: boolean = false;
    setInterval(() => {
      if (!isClientConnected && !awaitingFirstConnect && !disconnected) {
        terminal.writeLine(Colorize.red('The client has disconnected!'));
        terminal.writeLine(`Please open a browser window at http://localhost:${PORT}/app`);
        disconnected = true;
      } else if (!awaitingFirstConnect) {
        isClientConnected = false;
      }
    }, 4000);

    // This takes precedence over the `/app` static route, which also has an `initappcontext.js` file.
    app.get('/initappcontext.js', (req: express.Request, res: express.Response) => {
      const appContext: IAppContext = {
        serviceUrl: SERVICE_URL,
        appVersion: appState.appVersion,
        debugMode: this.isDebug
      };
      const sourceCode: string = [
        `console.log('Loaded initappcontext.js');`,
        `appContext = ${JSON.stringify(appContext)}`
      ].join('\n');

      res.type('application/javascript').send(sourceCode);
    });

    app.use('/', express.static(distFolderPath));

    app.use('/favicon.ico', express.static(distFolderPath, { index: 'favicon.ico' }));

    app.get('/api/health', (req: express.Request, res: express.Response) => {
      awaitingFirstConnect = false;
      isClientConnected = true;
      if (disconnected) {
        disconnected = false;
        terminal.writeLine(Colorize.green('The client has reconnected!'));
      }
      res.status(200).send();
    });

    app.get('/api/graph', async (req: express.Request, res: express.Response) => {
      const pnpmLockfileText: string = await FileSystem.readFileAsync(appState.pnpmLockfileLocation);
      const lockfile: unknown = yaml.load(pnpmLockfileText) as unknown;

      const graph: LfxGraph = lfxGraphLoader.generateLockfileGraph(lockfile, lfxWorkspace);

      const jsonGraph: IJsonLfxGraph = lfxGraphSerializer.serializeToJson(graph);
      res.type('application/json').send(jsonGraph);
    });

    app.post(
      '/api/package-json',
      async (req: express.Request<{}, {}, { projectPath: string }, {}>, res: express.Response) => {
        const { projectPath } = req.body;
        const fileLocation: string = `${appState.projectRoot}/${projectPath}/package.json`;
        let packageJsonText: string;
        try {
          packageJsonText = await FileSystem.readFileAsync(fileLocation);
        } catch (e) {
          if (FileSystem.isNotExistError(e)) {
            return res.status(404).send({
              message: `Could not load package.json file for this package. Have you installed all the dependencies for this workspace?`,
              error: `No package.json in location: ${projectPath}`
            });
          } else {
            throw e;
          }
        }

        res.send(packageJsonText);
      }
    );

    app.get('/api/pnpmfile', async (req: express.Request, res: express.Response) => {
      const pnpmfilePath: string = lockfilePath.join(
        lfxWorkspace.workspaceRootFullPath,
        lfxWorkspace.rushConfig?.rushPnpmfilePath ?? lfxWorkspace.pnpmfilePath
      );

      let pnpmfile: string;
      try {
        pnpmfile = await FileSystem.readFileAsync(pnpmfilePath);
      } catch (e) {
        if (FileSystem.isNotExistError(e)) {
          return res.status(404).send({
            message: `Could not load .pnpmfile.cjs file in this repo: "${pnpmfilePath}"`,
            error: `No .pnpmifile.cjs found.`
          });
        } else {
          throw e;
        }
      }

      res.send(pnpmfile);
    });

    app.post(
      '/api/package-spec',
      async (req: express.Request<{}, {}, { projectPath: string }, {}>, res: express.Response) => {
        const { projectPath } = req.body;
        const fileLocation: string = `${appState.projectRoot}/${projectPath}/package.json`;
        let packageJson: IPackageJson;
        try {
          packageJson = await JsonFile.loadAsync(fileLocation);
        } catch (e) {
          if (FileSystem.isNotExistError(e)) {
            return res.status(404).send({
              message: `Could not load package.json file in location: ${projectPath}`
            });
          } else {
            throw e;
          }
        }

        let parsedPackage: IPackageJson = packageJson;

        const pnpmfilePath: string = path.join(lfxWorkspace.workspaceRootFullPath, lfxWorkspace.pnpmfilePath);
        if (await FileSystem.existsAsync(pnpmfilePath)) {
          const pnpmFileRunner: PnpmfileRunner = new PnpmfileRunner(pnpmfilePath);
          try {
            parsedPackage = await pnpmFileRunner.transformPackageAsync(packageJson, fileLocation);
          } finally {
            await pnpmFileRunner.disposeAsync();
          }
        }

        res.send(parsedPackage);
      }
    );

    app.listen(PORT, async () => {
      terminal.writeLine(`App launched on ${SERVICE_URL}`);

      printUpdateNotification(await updateCheckPromise, terminal);

      if (!appState.debugMode) {
        try {
          // Launch the default web browser using the platform-native open command.
          let browserCmd: string;
          let browserArgs: string[];
          switch (process.platform) {
            case 'win32': {
              // "start" is a cmd.exe built-in, not a standalone executable.
              // The empty string is the required [title] argument; without it,
              // cmd interprets the URL as the title and ignores it.
              browserCmd = 'cmd';
              browserArgs = ['/c', 'start', '', SERVICE_URL];
              break;
            }

            case 'darwin': {
              browserCmd = 'open';
              browserArgs = [SERVICE_URL];
              break;
            }

            default: {
              // Linux and other Unix-like systems
              browserCmd = 'xdg-open';
              browserArgs = [SERVICE_URL];
              break;
            }
          }

          const browserProcess: ChildProcess = Executable.spawn(browserCmd, browserArgs, { stdio: 'ignore' });
          // Detach from our Node.js process so the browser stays open after we exit
          browserProcess.unref();
        } catch (e) {
          terminal.writeError('Error launching browser: ' + e.toString());
        }
      }
    });
  }
}