19548176196

Committed 20 Nov 2025 07:00PM UTC coverage: 69.114% (+0.2%) from 68.924%

Build # 19548176196

Build Type

Pull #1593

github

Committed by

web-flow

Commit Message

Merge add44c871 into ffcb5d97f

Pull Request Pull Request #1593: #1144: #1145: CVE warnings and suggestions

Run Details

3597 of 5699 branches covered (63.12%)

Branch coverage included in aggregate %.

9357 of 13044 relevant lines covered (71.73%)

3.15 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

73.17

cli/src/main/java/com/devonfw/tools/ide/tool/ToolCommandlet.java

package com.devonfw.tools.ide.tool;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
import java.util.Set;

import com.devonfw.tools.ide.commandlet.Commandlet;
import com.devonfw.tools.ide.common.Tag;
import com.devonfw.tools.ide.common.Tags;
import com.devonfw.tools.ide.context.IdeContext;
import com.devonfw.tools.ide.environment.EnvironmentVariables;
import com.devonfw.tools.ide.environment.EnvironmentVariablesFiles;
import com.devonfw.tools.ide.io.FileCopyMode;
import com.devonfw.tools.ide.log.IdeSubLogger;
import com.devonfw.tools.ide.nls.NlsBundle;
import com.devonfw.tools.ide.os.MacOsHelper;
import com.devonfw.tools.ide.process.EnvironmentContext;
import com.devonfw.tools.ide.process.ProcessContext;
import com.devonfw.tools.ide.process.ProcessErrorHandling;
import com.devonfw.tools.ide.process.ProcessMode;
import com.devonfw.tools.ide.process.ProcessResult;
import com.devonfw.tools.ide.property.StringProperty;
import com.devonfw.tools.ide.security.ToolVersionChoice;
import com.devonfw.tools.ide.step.Step;
import com.devonfw.tools.ide.tool.repository.ToolRepository;
import com.devonfw.tools.ide.url.model.file.json.Cve;
import com.devonfw.tools.ide.url.model.file.json.ToolDependency;
import com.devonfw.tools.ide.url.model.file.json.ToolSecurity;
import com.devonfw.tools.ide.variable.IdeVariables;
import com.devonfw.tools.ide.version.GenericVersionRange;
import com.devonfw.tools.ide.version.VersionIdentifier;

/**
 * {@link Commandlet} for a tool integrated into the IDE.
 */
public abstract class ToolCommandlet extends Commandlet implements Tags {

  /** @see #getName() */
  protected final String tool;

  private final Set<Tag> tags;

  /** The commandline arguments to pass to the tool. */
  public final StringProperty arguments;

  private Path executionDirectory;

  private MacOsHelper macOsHelper;

  /**
   * The constructor.
   *
   * @param context the {@link IdeContext}.
   * @param tool the {@link #getName() tool name}.
   * @param tags the {@link #getTags() tags} classifying the tool. Should be created via {@link Set#of(Object) Set.of} method.
   */
  public ToolCommandlet(IdeContext context, String tool, Set<Tag> tags) {

    super(context);
    this.tool = tool;
    this.tags = tags;
    addKeyword(tool);
    this.arguments = new StringProperty("", false, true, "args");
    initProperties();
  }

  /**
   * Add initial Properties to the tool
   */
  protected void initProperties() {

    add(this.arguments);
  }

  /**
   * @return the name of the tool (e.g. "java", "mvn", "npm", "node").
   */
  @Override
  public final String getName() {

    return this.tool;
  }

  /**
   * @return the name of the binary executable for this tool.
   */
  protected String getBinaryName() {

    return this.tool;
  }

  @Override
  public final Set<Tag> getTags() {

    return this.tags;
  }

  /**
   * @return the execution directory where the tool will be executed. Will be {@code null} by default leading to execution in the users current working
   *     directory where IDEasy was called.
   * @see #setExecutionDirectory(Path)
   */
  public Path getExecutionDirectory() {
    return this.executionDirectory;
  }

  /**
   * @param executionDirectory the new value of {@link #getExecutionDirectory()}.
   */
  public void setExecutionDirectory(Path executionDirectory) {
    this.executionDirectory = executionDirectory;
  }

  /**
   * @return the {@link EnvironmentVariables#getToolVersion(String) tool version}.
   */
  public VersionIdentifier getConfiguredVersion() {

    return this.context.getVariables().getToolVersion(getName());
  }

  /**
   * @return the {@link EnvironmentVariables#getToolEdition(String) tool edition}.
   */
  public String getConfiguredEdition() {

    return this.context.getVariables().getToolEdition(getName());
  }

  /**
   * @return the {@link ToolEdition} with {@link #getName() tool} with its {@link #getConfiguredEdition() edition}.
   */
  protected final ToolEdition getToolWithEdition() {

    return new ToolEdition(this.tool, getConfiguredEdition());
  }

  @Override
  public void run() {

    runTool(this.arguments.asArray());
  }

  /**
   * @param args the command-line arguments to run the tool.
   * @return the {@link ProcessResult result}.
   * @see ToolCommandlet#runTool(ProcessMode, GenericVersionRange, String...)
   */
  public ProcessResult runTool(String... args) {

    return runTool(ProcessMode.DEFAULT, null, args);
  }

  /**
   * Ensures the tool is installed and then runs this tool with the given arguments.
   *
   * @param processMode the {@link ProcessMode}. Should typically be {@link ProcessMode#DEFAULT} or {@link ProcessMode#BACKGROUND}.
   * @param toolVersion the explicit {@link GenericVersionRange version} to run. Typically {@code null} to run the
   *     {@link #getConfiguredVersion() configured version}. Otherwise, the specified version will be used (from the software repository, if not compatible).
   * @param args the command-line arguments to run the tool.
   * @return the {@link ProcessResult result}.
   */
  public final ProcessResult runTool(ProcessMode processMode, GenericVersionRange toolVersion, String... args) {

    return runTool(processMode, toolVersion, ProcessErrorHandling.THROW_CLI, args);
  }

  /**
   * Ensures the tool is installed and then runs this tool with the given arguments.
   *
   * @param processMode the {@link ProcessMode}. Should typically be {@link ProcessMode#DEFAULT} or {@link ProcessMode#BACKGROUND}.
   * @param toolVersion the explicit {@link GenericVersionRange version} to run. Typically {@code null} to run the
   *     {@link #getConfiguredVersion() configured version}. Otherwise, the specified version will be used (from the software repository, if not compatible).
   * @param errorHandling the {@link ProcessErrorHandling}.
   * @param args the command-line arguments to run the tool.
   * @return the {@link ProcessResult result}.
   */
  public ProcessResult runTool(ProcessMode processMode, GenericVersionRange toolVersion, ProcessErrorHandling errorHandling, String... args) {

    if (toolVersion != null) {
      throw new UnsupportedOperationException("Not implemented yet");
    }
    ProcessContext pc = this.context.newProcess().errorHandling(errorHandling);
    install(true, getConfiguredVersion(), pc, null);
    return runTool(processMode, errorHandling, pc, args);
  }

  /**
   * @param processMode the {@link ProcessMode}. Should typically be {@link ProcessMode#DEFAULT} or {@link ProcessMode#BACKGROUND}.
   * @param errorHandling the {@link ProcessErrorHandling}.
   * @param pc the {@link ProcessContext}.
   * @param args the command-line arguments to run the tool.
   * @return the {@link ProcessResult result}.
   */
  public ProcessResult runTool(ProcessMode processMode, ProcessErrorHandling errorHandling, ProcessContext pc, String... args) {

    if (this.executionDirectory != null) {
      pc.directory(this.executionDirectory);
    }
    configureToolBinary(pc, processMode, errorHandling);
    configureToolArgs(pc, processMode, errorHandling, args);
    return pc.run(processMode);
  }

  /**
   * @param pc the {@link ProcessContext}.
   * @param processMode the {@link ProcessMode}.
   * @param errorHandling the {@link ProcessErrorHandling}.
   */
  protected void configureToolBinary(ProcessContext pc, ProcessMode processMode, ProcessErrorHandling errorHandling) {

    pc.executable(Path.of(getBinaryName()));
  }

  /**
   * @param pc the {@link ProcessContext}.
   * @param processMode the {@link ProcessMode}.
   * @param errorHandling the {@link ProcessErrorHandling}.
   * @param args the command-line arguments to {@link ProcessContext#addArgs(Object...) add}.
   */
  protected void configureToolArgs(ProcessContext pc, ProcessMode processMode, ProcessErrorHandling errorHandling, String... args) {

    pc.addArgs(args);
  }

  /**
   * Creates a new {@link ProcessContext} from the given executable with the provided arguments attached.
   *
   * @param binaryPath path to the binary executable for this process
   * @param args the command-line arguments for this process
   * @return {@link ProcessContext}
   */
  protected ProcessContext createProcessContext(Path binaryPath, String... args) {

    return this.context.newProcess().errorHandling(ProcessErrorHandling.THROW_ERR).executable(binaryPath).addArgs(args);
  }

  /**
   * Installs or updates the managed {@link #getName() tool}.
   *
   * @return the {@link ToolInstallation}.
   */
  public ToolInstallation install() {

    return install(true);
  }

  /**
   * Performs the installation of the {@link #getName() tool} managed by this {@link com.devonfw.tools.ide.commandlet.Commandlet}.
   *
   * @param silent - {@code true} if called recursively to suppress verbose logging, {@code false} otherwise.
   * @return the {@link ToolInstallation}.
   */
  public ToolInstallation install(boolean silent) {
    return install(silent, getConfiguredVersion());
  }

  /**
   *
   * @param silent - {@code true} if called recursively to suppress verbose logging, {@code false} otherwise.
   * @param configuredVersion the version to install, typically {@link #getConfiguredVersion()}.
   * @return the {@link ToolInstallation}.
   */
  public ToolInstallation install(boolean silent, VersionIdentifier configuredVersion) {
    ProcessContext pc = this.context.newProcess().errorHandling(ProcessErrorHandling.THROW_CLI);
    return install(silent, configuredVersion, pc, null);
  }


  /**
   * Installs or updates the managed {@link #getName() tool}.
   *
   * @param silent - {@code true} if called recursively to suppress verbose logging, {@code false} otherwise.
   * @param processContext the {@link ProcessContext} used to
   *     {@link LocalToolCommandlet#setEnvironment(EnvironmentContext, ToolInstallation, boolean) configure environment variables}.
   * @param step the {@link Step} to track the installation. May be {@code null} to fail with {@link Exception} on error.
   * @param configuredVersion the version to install, typically {@link #getConfiguredVersion()}.
   * @return the {@link ToolInstallation}.
   */
  public abstract ToolInstallation install(boolean silent, VersionIdentifier configuredVersion, ProcessContext processContext, Step step);

  /**
   * This method is called after a tool was requested to be installed or updated.
   *
   * @param newlyInstalled {@code true} if the tool was installed or updated (at least link to software folder was created/updated), {@code false} otherwise
   *     (configured version was already installed and nothing changed).
   * @param pc the {@link ProcessContext} to use.
   */
  protected void postInstall(boolean newlyInstalled, ProcessContext pc) {

    if (newlyInstalled) {
      postInstall();
    }
  }

  /**
   * This method is called after the tool has been newly installed or updated to a new version.
   */
  protected void postInstall() {

    // nothing to do by default
  }

  protected abstract Path getInstallationPath(String edition, VersionIdentifier resolvedVersion);

  /**
   * @param edition the {@link #getConfiguredEdition() edition}.
   * @param installedVersion the {@link #getConfiguredVersion() version}.
   * @param environmentContext the {@link EnvironmentContext}.
   * @param extraInstallation {@code true} if the {@link ToolInstallation} is an additional installation to the
   *     {@link #getConfiguredVersion() configured version} due to a conflicting version of a {@link ToolDependency}, {@code false} otherwise.
   * @return the {@link ToolInstallation}.
   */
  protected ToolInstallation createExistingToolInstallation(String edition, VersionIdentifier installedVersion, EnvironmentContext environmentContext,
      boolean extraInstallation) {

    Path installationPath = getInstallationPath(edition, installedVersion);
    return createToolInstallation(installationPath, installedVersion, false, environmentContext, extraInstallation);
  }

  /**
   * @param rootDir the {@link ToolInstallation#rootDir() top-level installation directory}.
   * @param version the installed {@link VersionIdentifier}.
   * @param newInstallation {@link ToolInstallation#newInstallation() new installation} flag.
   * @param environmentContext the {@link EnvironmentContext}.
   * @param extraInstallation {@code true} if the {@link ToolInstallation} is an additional installation to the
   *     {@link #getConfiguredVersion() configured version} due to a conflicting version of a {@link ToolDependency}, {@code false} otherwise.
   * @return the {@link ToolInstallation}.
   */
  protected ToolInstallation createToolInstallation(Path rootDir, VersionIdentifier version, boolean newInstallation,
      EnvironmentContext environmentContext, boolean extraInstallation) {

    Path linkDir = rootDir;
    Path binDir = rootDir;
    if (rootDir != null) {
      linkDir = getMacOsHelper().findLinkDir(rootDir, getBinaryName());
      binDir = this.context.getFileAccess().getBinPath(linkDir);
    }
    return createToolInstallation(rootDir, linkDir, binDir, version, newInstallation, environmentContext, extraInstallation);
  }

  /**
   * @param rootDir the {@link ToolInstallation#rootDir() top-level installation directory}.
   * @param linkDir the {@link ToolInstallation#linkDir() link directory}.
   * @param binDir the {@link ToolInstallation#binDir() bin directory}.
   * @param version the installed {@link VersionIdentifier}.
   * @param newInstallation {@link ToolInstallation#newInstallation() new installation} flag.
   * @param environmentContext the {@link EnvironmentContext}.
   * @param extraInstallation {@code true} if the {@link ToolInstallation} is an additional installation to the
   *     {@link #getConfiguredVersion() configured version} due to a conflicting version of a {@link ToolDependency}, {@code false} otherwise.
   * @return the {@link ToolInstallation}.
   */
  protected ToolInstallation createToolInstallation(Path rootDir, Path linkDir, Path binDir, VersionIdentifier version, boolean newInstallation,
      EnvironmentContext environmentContext, boolean extraInstallation) {

    if (linkDir != rootDir) {
      assert (!linkDir.equals(rootDir));
      Path toolVersionFile = rootDir.resolve(IdeContext.FILE_SOFTWARE_VERSION);
      if (Files.exists(toolVersionFile)) {
        this.context.getFileAccess().copy(toolVersionFile, linkDir, FileCopyMode.COPY_FILE_OVERRIDE);
      }
    }
    ToolInstallation toolInstallation = new ToolInstallation(rootDir, linkDir, binDir, version, newInstallation);
    setEnvironment(environmentContext, toolInstallation, extraInstallation);
    return toolInstallation;
  }

  /**
   * Called if tool is already installed and detected before actual {@link #install() install} method was called.
   *
   * @param silent - {@code true} if called recursively to suppress verbose logging, {@code false} otherwise.
   * @param toolEdition the installed {@link ToolEdition}.
   * @param installedVersion the installed {@link VersionIdentifier}.
   * @param pc the {@link ProcessContext} to use.
   * @param extraInstallation {@code true} if the {@link ToolInstallation} is an additional installation to the
   *     {@link #getConfiguredVersion() configured version} due to a conflicting version of a {@link ToolDependency}, {@code false} otherwise.
   * @return the {@link ToolInstallation}.
   */
  protected ToolInstallation toolAlreadyInstalled(boolean silent, ToolEdition toolEdition, VersionIdentifier installedVersion, ProcessContext pc,
      boolean extraInstallation) {

    logToolAlreadyInstalled(silent, toolEdition, installedVersion);
    cveCheck(toolEdition, installedVersion, null, true);
    postInstall(false, pc);
    return createExistingToolInstallation(toolEdition.edition(), installedVersion, pc, extraInstallation);
  }

  /**
   * Called if tool is already installed and detected before actual {@link #install() install} method was called.
   *
   * @param silent - {@code true} if called recursively to suppress verbose logging, {@code false} otherwise.
   * @param toolEdition the installed {@link ToolEdition}.
   * @param installedVersion the installed {@link VersionIdentifier}.
   * @param pc the {@link ProcessContext} to use.
   * @param extraInstallation {@code true} if the {@link ToolInstallation} is an additional installation to the
   *     {@link #getConfiguredVersion() configured version} due to a conflicting version of a {@link ToolDependency}, {@code false} otherwise.
   * @return the {@link ToolInstallation}.
   */
  protected ToolInstallation toolAlreadyInstalled(boolean silent, Path binPath, ToolEdition toolEdition, VersionIdentifier installedVersion, ProcessContext pc,
      boolean extraInstallation) {

    logToolAlreadyInstalled(silent, toolEdition, installedVersion);
    cveCheck(toolEdition, installedVersion, null, true);
    postInstall(false, pc);
    Path rootPath = this.context.getFileAccess().getBinParentPath(binPath);
    return createToolInstallation(rootPath, rootPath, binPath, installedVersion, false, pc, extraInstallation);
  }

  /**
   * Log that the tool is already installed.
   *
   * @param silent - {@code true} if called recursively to suppress verbose logging, {@code false} otherwise.
   * @param toolEdition the installed {@link ToolEdition}.
   * @param installedVersion the installed {@link VersionIdentifier}.
   */
  protected void logToolAlreadyInstalled(boolean silent, ToolEdition toolEdition, VersionIdentifier installedVersion) {
    IdeSubLogger logger;
    if (silent) {
      logger = this.context.debug();
    } else {
      logger = this.context.info();
    }
    logger.log("Version {} of tool {} is already installed", installedVersion, toolEdition);
  }

  /**
   * Method to get the home path of the given {@link ToolInstallation}.
   *
   * @param toolInstallation the {@link ToolInstallation}.
   * @return the Path to the home of the tool
   */
  protected Path getToolHomePath(ToolInstallation toolInstallation) {
    return toolInstallation.linkDir();
  }

  /**
   * Method to set environment variables for the process context.
   *
   * @param environmentContext the {@link EnvironmentContext} where to {@link EnvironmentContext#withEnvVar(String, String) set environment variables} for
   *     this tool.
   * @param toolInstallation the {@link ToolInstallation}.
   * @param extraInstallation {@code true} if the {@link ToolInstallation} is an additional installation to the
   *     {@link #getConfiguredVersion() configured version} due to a conflicting version of a {@link ToolDependency}, {@code false} otherwise.
   */
  public void setEnvironment(EnvironmentContext environmentContext, ToolInstallation toolInstallation, boolean extraInstallation) {

    String pathVariable = EnvironmentVariables.getToolVariablePrefix(this.tool) + "_HOME";
    Path toolHomePath = getToolHomePath(toolInstallation);
    if (toolHomePath != null) {
      environmentContext.withEnvVar(pathVariable, toolHomePath.toString());
    }
    if (extraInstallation) {
      environmentContext.withPathEntry(toolInstallation.binDir());
    }
  }

  /**
   * @return {@code true} to extract (unpack) the downloaded binary file, {@code false} otherwise.
   */
  protected boolean isExtract() {

    return true;
  }

  /**
   * Checks a version to be installed for {@link Cve}s. If at least one {@link Cve} is found, we try to find better/safer versions as alternative. If we find
   * something better, we will suggest this to the user and ask him to make his choice.
   *
   * @param toolEdition the {@link ToolEdition}.
   * @param resolvedVersion the resolved {@link #getConfiguredEdition() version}.
   * @param allowedVersions a {@link GenericVersionRange} that defines which versions are allowed to consider.
   * @param skipSuggestions {@code true} to skip suggestions, {@code false} otherwise (try to find alternative suggestions and ask the user).
   * @return the {@link VersionIdentifier} to install. If there were {@link Cve}s found and better versions available the user made this choice.
   */
  protected VersionIdentifier cveCheck(ToolEdition toolEdition, VersionIdentifier resolvedVersion, GenericVersionRange allowedVersions,
      boolean skipSuggestions) {

    ToolSecurity toolSecurity = this.context.getDefaultToolRepository().findSecurity(this.tool, toolEdition.edition());
    double minSeverity = IdeVariables.CVE_MIN_SEVERITY.get(context);
    Collection<Cve> issues = toolSecurity.findCves(resolvedVersion, this.context, minSeverity);
    ToolVersionChoice currentChoice = ToolVersionChoice.ofCurrent(resolvedVersion, issues);
    if (logCvesAndReturnTrueForNone(toolEdition, resolvedVersion, currentChoice.option(), issues)) {
      return resolvedVersion;
    }
    if (skipSuggestions) {
      // currently for a transitive dependency it does not make sense to suggest alternative versions, since the choice is not stored anywhere,
      // and we then would ask the user again every time the tool having this dependency is started. So we only log the problem and the user needs to react
      // (e.g. upgrade the tool with the dependency that is causing this).
      this.context.interaction("Please run 'ide install {}' to check for update suggestions!", this.tool);
      return resolvedVersion;
    }
    double currentSeveritySum = Cve.severitySum(issues);
    ToolVersionChoice latest = null;
    ToolVersionChoice nearest = null;
    List<VersionIdentifier> toolVersions = getVersions();
    double latestSeveritySum = currentSeveritySum;
    double nearestSeveritySum = currentSeveritySum;
    for (VersionIdentifier version : toolVersions) {
      if (allowedVersions == null || allowedVersions.contains(version)) {
        issues = toolSecurity.findCves(version, this.context, minSeverity);
        double newSeveritySum = Cve.severitySum(issues);
        if (newSeveritySum < latestSeveritySum) {
          // we found a better/safer version
          if (version.isGreater(resolvedVersion)) {
            latest = ToolVersionChoice.ofLatest(version, issues);
            nearest = null;
            latestSeveritySum = newSeveritySum;
          } else {
            // latest = null;
            nearest = ToolVersionChoice.ofNearest(version, issues);
            nearestSeveritySum = newSeveritySum;
          }
        } else if (newSeveritySum < nearestSeveritySum) {
          if (version.isGreater(resolvedVersion)) {
            nearest = ToolVersionChoice.ofNearest(version, issues);
          } else if (nearest == null) {
            nearest = ToolVersionChoice.ofNearest(version, issues);
          }
          nearestSeveritySum = newSeveritySum;
        }
      }
    }
    if ((latest == null) && (nearest == null)) {
      this.context.warning(
          "Could not find any other version resolving your CVEs.\nPlease keep attention to this tool and consider updating as soon as security fixes are available.");
    }
    List<ToolVersionChoice> choices = new ArrayList<>();
    choices.add(currentChoice);
    List<String> skipCveFixTools = IdeVariables.SKIP_CVE_FIX.get(this.context);
    boolean addSuggestions = !skipCveFixTools.contains(this.tool);
    if (nearest != null) {
      if (addSuggestions) {
        choices.add(nearest);
      }
      logCvesAndReturnTrueForNone(toolEdition, nearest.version(), nearest.option(), nearest.issues());
    }
    if (latest != null) {
      if (addSuggestions) {
        choices.add(latest);
      }
      logCvesAndReturnTrueForNone(toolEdition, latest.version(), latest.option(), latest.issues());
    }
    ToolVersionChoice[] choicesArray = choices.toArray(ToolVersionChoice[]::new);
    this.context.warning(
        "Please note that by selecting an unsafe version to install, you accept the risk to be attacked.");
    ToolVersionChoice answer = this.context.question(choicesArray, "Which version do you want to install?");
    return answer.version();
  }

  private boolean logCvesAndReturnTrueForNone(ToolEdition toolEdition, VersionIdentifier version, String option, Collection<Cve> issues) {
    if (issues.isEmpty()) {
      this.context.info("No CVEs found for {} version {} of tool {}.", option, version, toolEdition);
      return true;
    }
    this.context.warning("For {} version {} of tool {} we found {} CVE(s):", option, version, toolEdition, issues.size());
    for (Cve cve : issues) {
      logCve(cve);
    }
    return false;
  }

  private void logCve(Cve cve) {

    this.context.warning("{} with severity {} and affected versions: {} ", cve.id(), cve.severity(), cve.versions());
    this.context.warning("https://nvd.nist.gov/vuln/detail/" + cve.id());
    this.context.info("");
  }

  /**
   * @return the {@link MacOsHelper} instance.
   */
  protected MacOsHelper getMacOsHelper() {

    if (this.macOsHelper == null) {
      this.macOsHelper = new MacOsHelper(this.context);
    }
    return this.macOsHelper;
  }

  /**
   * @return the currently installed {@link VersionIdentifier version} of this tool or {@code null} if not installed.
   */
  public abstract VersionIdentifier getInstalledVersion();

  /**
   * @return {@code true} if this tool is installed, {@code false} otherwise.
   */
  public boolean isInstalled() {

    return getInstalledVersion() != null;
  }

  /**
   * @return the installed edition of this tool or {@code null} if not installed.
   */
  public abstract String getInstalledEdition();

  /**
   * Uninstalls the {@link #getName() tool}.
   */
  public abstract void uninstall();

  /**
   * @return the {@link ToolRepository}.
   */
  public ToolRepository getToolRepository() {

    return this.context.getDefaultToolRepository();
  }

  /**
   * List the available editions of this tool.
   */
  public void listEditions() {

    List<String> editions = getToolRepository().getSortedEditions(getName());
    for (String edition : editions) {
      this.context.info(edition);
    }
  }

  /**
   * List the available versions of this tool.
   */
  public void listVersions() {

    List<VersionIdentifier> versions = getToolRepository().getSortedVersions(getName(), getConfiguredEdition(), this);
    for (VersionIdentifier vi : versions) {
      this.context.info(vi.toString());
    }
  }

  /**
   * @return the {@link com.devonfw.tools.ide.tool.repository.DefaultToolRepository#getSortedVersions(String, String, ToolCommandlet) sorted versions} of this
   *     tool.
   */
  public List<VersionIdentifier> getVersions() {
    return getToolRepository().getSortedVersions(getName(), getConfiguredEdition(), this);
  }

  /**
   * Sets the tool version in the environment variable configuration file.
   *
   * @param version the version (pattern) to set.
   */
  public void setVersion(String version) {

    if ((version == null) || version.isBlank()) {
      throw new IllegalStateException("Version has to be specified!");
    }
    VersionIdentifier configuredVersion = VersionIdentifier.of(version);
    if (!configuredVersion.isPattern() && !configuredVersion.isValid()) {
      this.context.warning("Version {} seems to be invalid", version);
    }
    setVersion(configuredVersion, true);
  }

  /**
   * Sets the tool version in the environment variable configuration file.
   *
   * @param version the version to set. May also be a {@link VersionIdentifier#isPattern() version pattern}.
   * @param hint - {@code true} to print the installation hint, {@code false} otherwise.
   */
  public void setVersion(VersionIdentifier version, boolean hint) {

    setVersion(version, hint, null);
  }

  /**
   * Sets the tool version in the environment variable configuration file.
   *
   * @param version the version to set. May also be a {@link VersionIdentifier#isPattern() version pattern}.
   * @param hint - {@code true} to print the installation hint, {@code false} otherwise.
   * @param destination - the destination for the property to be set
   */
  public void setVersion(VersionIdentifier version, boolean hint, EnvironmentVariablesFiles destination) {

    String edition = getConfiguredEdition();
    ToolRepository toolRepository = getToolRepository();

    EnvironmentVariables variables = this.context.getVariables();
    if (destination == null) {
      //use default location
      destination = EnvironmentVariablesFiles.SETTINGS;
    }
    EnvironmentVariables settingsVariables = variables.getByType(destination.toType());
    String name = EnvironmentVariables.getToolVersionVariable(this.tool);

    toolRepository.resolveVersion(this.tool, edition, version, this); // verify that the version actually exists
    settingsVariables.set(name, version.toString(), false);
    settingsVariables.save();
    EnvironmentVariables declaringVariables = variables.findVariable(name);
    if ((declaringVariables != null) && (declaringVariables != settingsVariables)) {
      this.context.warning("The variable {} is overridden in {}. Please remove the overridden declaration in order to make the change affect.", name,
          declaringVariables.getSource());
    }
    if (hint) {
      this.context.info("To install that version call the following command:");
      this.context.info("ide install {}", this.tool);
    }
  }

  /**
   * Sets the tool edition in the environment variable configuration file.
   *
   * @param edition the edition to set.
   */
  public void setEdition(String edition) {

    setEdition(edition, true);
  }

  /**
   * Sets the tool edition in the environment variable configuration file.
   *
   * @param edition the edition to set
   * @param hint - {@code true} to print the installation hint, {@code false} otherwise.
   */
  public void setEdition(String edition, boolean hint) {

    setEdition(edition, hint, null);
  }

  /**
   * Sets the tool edition in the environment variable configuration file.
   *
   * @param edition the edition to set
   * @param hint - {@code true} to print the installation hint, {@code false} otherwise.
   * @param destination - the destination for the property to be set
   */
  public void setEdition(String edition, boolean hint, EnvironmentVariablesFiles destination) {

    if ((edition == null) || edition.isBlank()) {
      throw new IllegalStateException("Edition has to be specified!");
    }

    if (destination == null) {
      //use default location
      destination = EnvironmentVariablesFiles.SETTINGS;
    }

    if (!getToolRepository().getSortedEditions(this.tool).contains(edition)) {
      this.context.warning("Edition {} seems to be invalid", edition);
    }
    EnvironmentVariables variables = this.context.getVariables();
    EnvironmentVariables settingsVariables = variables.getByType(destination.toType());
    String name = EnvironmentVariables.getToolEditionVariable(this.tool);
    settingsVariables.set(name, edition, false);
    settingsVariables.save();

    this.context.info("{}={} has been set in {}", name, edition, settingsVariables.getSource());
    EnvironmentVariables declaringVariables = variables.findVariable(name);
    if ((declaringVariables != null) && (declaringVariables != settingsVariables)) {
      this.context.warning("The variable {} is overridden in {}. Please remove the overridden declaration in order to make the change affect.", name,
          declaringVariables.getSource());
    }
    if (hint) {
      this.context.info("To install that edition call the following command:");
      this.context.info("ide install {}", this.tool);
    }
  }

  /**
   * Runs the tool's help command to provide the user with usage information.
   */
  @Override
  public void printHelp(NlsBundle bundle) {

    super.printHelp(bundle);
    String toolHelpArgs = getToolHelpArguments();
    if (toolHelpArgs != null && getInstalledVersion() != null) {
      ProcessContext pc = this.context.newProcess().errorHandling(ProcessErrorHandling.LOG_WARNING)
          .executable(Path.of(getBinaryName())).addArgs(toolHelpArgs);
      pc.run(ProcessMode.DEFAULT);
    }
  }

  /**
   * @return the tool's specific help command. Usually help, --help or -h. Return null if not applicable.
   */
  public String getToolHelpArguments() {

    return null;
  }

  /**
   * Creates a start script for the tool using the tool name.
   *
   * @param targetDir the {@link Path} of the installation where to create the script. If a "bin" sub-folder is present, the script will be created there
   *     instead.
   * @param binary name of the binary to execute from the start script.
   */
  protected void createStartScript(Path targetDir, String binary) {

    createStartScript(targetDir, binary, false);
  }

  /**
   * Creates a start script for the tool using the tool name.
   *
   * @param targetDir the {@link Path} of the installation where to create the script. If a "bin" sub-folder is present, the script will be created there
   *     instead.
   * @param binary name of the binary to execute from the start script.
   * @param background {@code true} to run the {@code binary} in background, {@code false} otherwise (foreground).
   */
  protected void createStartScript(Path targetDir, String binary, boolean background) {

    Path binFolder = targetDir.resolve("bin");
    if (!Files.exists(binFolder)) {
      if (this.context.getSystemInfo().isMac()) {
        MacOsHelper macOsHelper = getMacOsHelper();
        Path appDir = macOsHelper.findAppDir(targetDir);
        binFolder = macOsHelper.findLinkDir(appDir, binary);
      } else {
        binFolder = targetDir;
      }
      assert (Files.exists(binFolder));
    }
    Path bashFile = binFolder.resolve(getName());
    String bashFileContentStart = "#!/usr/bin/env bash\n\"$(dirname \"$0\")/";
    String bashFileContentEnd = "\" $@";
    if (background) {
      bashFileContentEnd += " &";
    }
    try {
      Files.writeString(bashFile, bashFileContentStart + binary + bashFileContentEnd);
    } catch (IOException e) {
      throw new RuntimeException(e);
    }
    assert (Files.exists(bashFile));
    context.getFileAccess().makeExecutable(bashFile);
  }

  @Override
  public void reset() {
    super.reset();
    this.executionDirectory = null;
  }

  /**
   * @param step the {@link Step} to get {@link Step#asSuccess() success logger} from. May be {@code null}.
   * @return the {@link IdeSubLogger} from {@link Step#asSuccess()} or {@link IdeContext#success()} as fallback.
   */
  protected IdeSubLogger asSuccess(Step step) {

    if (step == null) {
      return this.context.success();
    } else {
      return step.asSuccess();
    }
  }


  /**
   * @param step the {@link Step} to get {@link Step#asError() error logger} from. May be {@code null}.
   * @return the {@link IdeSubLogger} from {@link Step#asError()} or {@link IdeContext#error()} as fallback.
   */
  protected IdeSubLogger asError(Step step) {

    if (step == null) {
      return this.context.error();
    } else {
      return step.asError();
    }
  }
}

devonfw / IDEasy / 19548176196

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous