Class WsAddMojo

java.lang.Object
network.ike.plugin.ws.WsAddMojo
All Implemented Interfaces:
org.apache.maven.api.plugin.Mojo
@Mojo(name="add", projectRequired=false, aggregator=true) public class WsAddMojo extends Object
Add a subproject repository to an existing workspace.

Given a git URL, this goal:

  1. Clones the repository into the workspace
  2. Derives the subproject name from the URL (or accepts -Dsubproject=<name>)
  3. Scans the POM to derive groupId and inter-subproject dependencies (matching dependency/parent groupIds against already-registered workspace subprojects)
  4. Appends a subproject entry to workspace.yaml
  5. Adds a file-activated profile to the reactor POM
  6. Re-scans existing subprojects to discover any that depend on the newly added subproject (backward resolution)

The subproject name is derived from the last path segment of the URL with .git stripped. For example, https://github.com/ikmdev/tinkar-core.git becomes tinkar-core. 

mvn ws:add -Drepo=https://github.com/ikmdev/tinkar-core.git
mvn ws:add -Drepo=https://github.com/ikmdev/rocks-kb.git
mvn ws:add -Drepo=https://github.com/ikmdev/komet.git
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    WsAddMojo()
    Creates this goal instance.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected boolean
    confirm(String label, boolean defaultYes)
    Prompt the user with a yes/no question, accepting "y"/"yes"/"n"/"no" (case-insensitive).
    final void
    execute()
    Run the goal and write its report.
    protected org.apache.maven.api.plugin.Log
    getLog()
    Access the Maven logger.
    protected network.ike.plugin.support.IkePrompter
    getPrompter()
    The IkePrompter for this goal — built lazily from the session's interactive flag, or the test-injected instance.
    protected org.apache.maven.api.Session
    getSession()
    Access the Maven session injected by Maven 4's plugin DI.
    protected String
    gitBranch(File subprojectDir)
    Get the current branch of a subproject directory.
    protected String
    gitShortSha(File subprojectDir)
    Get the short SHA of HEAD for a subproject directory.
    protected String
    gitStatus(File subprojectDir)
    Run git status --porcelain on a subproject directory and return the output (empty string = clean).
    protected String
    header(String goalName)
    Format a goal header line using the workspace name.
    protected boolean
    isWorkspaceMode()
    Check whether a workspace.yaml exists in the directory hierarchy.
    protected network.ike.workspace.WorkspaceGraph
    loadGraph()
    Load the manifest and build the workspace graph.
    protected String
    requireParam(String currentValue, String propertyName, String promptLabel)
    Prompt the user interactively for a required parameter when it was not supplied on the command line.
    protected Path
    resolveManifest()
    Resolve the manifest path — explicit parameter, or search upward.
    protected WorkspaceReportSpec
    runGoal()
    Run this goal's work and return the report it produced.
    protected String
    selectFromList(String label, List<String> options)
    Prompt the user to pick from a numbered list.
    protected void
    setLog(org.apache.maven.api.plugin.Log log)
    Replace the logger.
    protected static network.ike.workspace.FeatureName
    validateFeatureName(String feature)
    Validate a feature-name string with FeatureName.of(String) and surface any rule violation as a clean MojoException (the raw IllegalArgumentException would otherwise bubble up as a Maven internal error).
    protected static network.ike.workspace.MavenVersion
    validateMavenVersion(String version)
    Validate a Maven version string with MavenVersion.of(String) and surface any rule violation as a MojoException (ike-issues#295).
    protected static network.ike.workspace.SubprojectName
    validateSubprojectName(String subproject)
    Validate a subproject-name string with SubprojectName.of(String) and surface any rule violation as a MojoException (ike-issues#295).
    protected String
    workspaceName()
    Read the workspace name from the root POM's artifactId.
    protected File
    workspaceRoot()
    Resolve the workspace root directory (parent of workspace.yaml).

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • WsAddMojo

      public WsAddMojo()
      Creates this goal instance.

  • Method Details

    • runGoal

      protected WorkspaceReportSpec runGoal() throws org.apache.maven.api.plugin.MojoException
      Run this goal's work and return the report it produced.

      Implementations do the goal's actual work here and return a WorkspaceReportSpec — the goal identity and the Markdown body. The base class resolves the workspace root and writes the file. A goal cannot be implemented without producing a report, which is the structural fix for the missing-report bug class (IKE-Network/ike-issues#413 / #407).

      On failure, throw MojoException as usual — a failed goal produces no report, and Maven surfaces the exception.

      Returns:
      the report this goal produced (never null)
      Throws:
      org.apache.maven.api.plugin.MojoException - if the goal fails

    • getLog

      protected org.apache.maven.api.plugin.Log getLog()
      Access the Maven logger.
      Returns:
      the logger instance

    • getSession

      protected org.apache.maven.api.Session getSession()
      Access the Maven session injected by Maven 4's plugin DI.
      Returns:
      the injected session (may be null in unit tests)

    • setLog

      protected void setLog(org.apache.maven.api.plugin.Log log)
      Replace the logger. Used when a mojo is constructed directly (not via Maven's DI container) and so never had a logger injected — WsSyncMojo drives PullWorkspaceMojo and PushMojo instances it created itself.
      Parameters:
      log - the replacement logger

    • getPrompter

      protected network.ike.plugin.support.IkePrompter getPrompter()
      The IkePrompter for this goal — built lazily from the session's interactive flag, or the test-injected instance. Callers that pass it to a static helper (e.g. FeatureFinishSupport.promptStaleBranchCleanup(File, List, String, String, IkePrompter, Log)) use this.
      Returns:
      the prompter (never null)

    • loadGraph

      protected network.ike.workspace.WorkspaceGraph loadGraph()
      Load the manifest and build the workspace graph.
      Returns:
      the workspace dependency graph
      Throws:
      org.apache.maven.api.plugin.MojoException - if the manifest cannot be read

    • resolveManifest

      protected Path resolveManifest()
      Resolve the manifest path — explicit parameter, or search upward.
      Returns:
      path to the workspace manifest file
      Throws:
      org.apache.maven.api.plugin.MojoException - if the manifest cannot be found

    • workspaceRoot

      protected File workspaceRoot()
      Resolve the workspace root directory (parent of workspace.yaml).
      Returns:
      the workspace root directory
      Throws:
      org.apache.maven.api.plugin.MojoException - if the manifest cannot be found

    • gitStatus

      protected String gitStatus(File subprojectDir)
      Run git status --porcelain on a subproject directory and return the output (empty string = clean).
      Parameters:
      subprojectDir - the subproject directory to check
      Returns:
      git status output, empty if clean

    • gitBranch

      protected String gitBranch(File subprojectDir)
      Get the current branch of a subproject directory.
      Parameters:
      subprojectDir - the subproject directory to check
      Returns:
      the current branch name

    • gitShortSha

      protected String gitShortSha(File subprojectDir)
      Get the short SHA of HEAD for a subproject directory.
      Parameters:
      subprojectDir - the subproject directory to check
      Returns:
      the short SHA of HEAD

    • isWorkspaceMode

      protected boolean isWorkspaceMode()
      Check whether a workspace.yaml exists in the directory hierarchy. Does not throw — returns false if no manifest is found.
      Returns:
      true if running inside a workspace, false for a bare repo

    • requireParam

      protected String requireParam(String currentValue, String propertyName, String promptLabel)
      Prompt the user interactively for a required parameter when it was not supplied on the command line.

      Delegates to the IkePrompter (IKE-Network/ike-issues#385): an inline prompt on a real terminal, an own-line prompt in a piped IDE runner. In batch mode it throws a clear error directing the user to pass the property explicitly.

      Parameters:
      currentValue - the value from the @Parameter field (may be null)
      propertyName - the -D property name (for the error message)
      promptLabel - human-readable label shown in the prompt; callers pass it without trailing punctuation (a ": " separator is appended here)
      Returns:
      the resolved value — either the original or user-supplied
      Throws:
      org.apache.maven.api.plugin.MojoException - if no value can be obtained

    • validateFeatureName

      protected static network.ike.workspace.FeatureName validateFeatureName(String feature)
      Validate a feature-name string with FeatureName.of(String) and surface any rule violation as a clean MojoException (the raw IllegalArgumentException would otherwise bubble up as a Maven internal error). Use this anywhere a feature name leaves the -Dfeature= command-line boundary (ike-issues#205).
      Parameters:
      feature - the candidate feature name (must already be resolved — i.e. non-null after requireParam(String, String, String) or auto-detection)
      Returns:
      the validated FeatureName value
      Throws:
      org.apache.maven.api.plugin.MojoException - if feature fails the FeatureName syntax rules

    • validateSubprojectName

      protected static network.ike.workspace.SubprojectName validateSubprojectName(String subproject)
      Validate a subproject-name string with SubprojectName.of(String) and surface any rule violation as a MojoException (ike-issues#295).
      Parameters:
      subproject - the candidate subproject name (already resolved — non-null after requireParam(String, String, String) or POM derivation)
      Returns:
      the validated SubprojectName value
      Throws:
      org.apache.maven.api.plugin.MojoException - if subproject fails the SubprojectName syntax rules

    • validateMavenVersion

      protected static network.ike.workspace.MavenVersion validateMavenVersion(String version)
      Validate a Maven version string with MavenVersion.of(String) and surface any rule violation as a MojoException (ike-issues#295). Per feedback_no_semver_assumption the validator accepts single-segment monotonic, semver-like, calendar-based, and branch-qualified versions; it does not enforce semver.
      Parameters:
      version - the candidate version string
      Returns:
      the validated MavenVersion value
      Throws:
      org.apache.maven.api.plugin.MojoException - if version fails the MavenVersion syntax rules

    • confirm

      protected boolean confirm(String label, boolean defaultYes)
      Prompt the user with a yes/no question, accepting "y"/"yes"/"n"/"no" (case-insensitive). When invoked in a non-interactive context, the default is used.
      Parameters:
      label - the question to display (without trailing punctuation)
      defaultYes - whether true (yes) is the default
      Returns:
      true for yes, false for no
      Throws:
      org.apache.maven.api.plugin.MojoException - if no answer can be obtained

    • selectFromList

      protected String selectFromList(String label, List<String> options)
      Prompt the user to pick from a numbered list. Returns the chosen option, or null when the list is empty.
      Parameters:
      label - prompt header (printed via the Prompter as a message)
      options - ordered list of choices
      Returns:
      the chosen option, or null if options is empty
      Throws:
      org.apache.maven.api.plugin.MojoException - if no valid choice can be obtained

    • workspaceName

      protected String workspaceName()
      Read the workspace name from the root POM's artifactId. Falls back to "Workspace" if the POM cannot be read.
      Returns:
      the workspace name derived from the root POM artifactId

    • header

      protected String header(String goalName)
      Format a goal header line using the workspace name. Example: "komet-ws — Status"
      Parameters:
      goalName - the goal name to display in the header
      Returns:
      the formatted header string

    • execute

      public final void execute() throws org.apache.maven.api.plugin.MojoException
      Run the goal and write its report.

      This method is final: every ws:* goal follows the same template — do the work, then write exactly one report. Subclasses supply the work and the report content by implementing runGoal(); they cannot override execute() to skip the report. That is what makes report-writing structural — a goal that compiles necessarily writes a report, so the #407 bug class (a goal runs fine but silently writes none) becomes compiler-impossible (IKE-Network/ike-issues#413).

      The report lands in its per-goal file at the workspace root (ws꞉goal-name.md); WorkspaceReport self-heals the nearest .gitignore so reports never land in git. A -publish run does not delete the matching -draft report — both are timestamped history (ike-issues#413).

      Specified by:
      execute in interface org.apache.maven.api.plugin.Mojo
      Throws:
      org.apache.maven.api.plugin.MojoException - if the goal fails