ST6RI-823 Allow external magic command defininitions in Jupyter

This commit adds a service registration based mechanism that can be used
to register additional magic commands to the system.

Furthermore, to allow these commands to add new items to the built-in
help system, and appropriate extension method was added to
SysMLInteractiveHelp

Author: ujhelyiz

org.omg.sysml.interactive/src/org/omg/sysml/interactive/SysMLInteractiveHelp.java

@@ -30,36 +30,33 @@
 
 import java.util.HashMap;
 import java.util.Map;
+import java.util.TreeMap;
 
 import org.omg.sysml.plantuml.SysML2PlantUMLStyle;
 
+import com.google.common.base.Preconditions;
+
 public class SysMLInteractiveHelp {
 
-	private static final String GENERAL_HELP_STRING =
+
+	private static final String GENERAL_HELP_STRING_PREFIX =
 			  "The following SysML v2 magic commands are available.\n"
 			+ "For help on a specific command, use \"%help <COMMAND>\" or \"%<cmd> -h\".\n\n"
-			+ "%eval\t\tEvaluate a given expression.\n"
-			+ "%export\t\tSave a file of the JSON representation of the abstract syntax tree rooted in the named element.\n"
-			+ "%help\t\tGet a list of available commands or help on a specific command\n"
-			+ "%list\t\tList loaded library packages or the results of a given query\n"
-			+ "%load\tLoads a model from the repository and adds it to the Xtext index\n"
-			+ "%show\t\tPrint the abstract syntax tree rooted in a named element\n"
-			+ "%projects\tList projects in the repository\n"
-			+ "%publish\tPublish to the repository the modele elements rooted in a named element\n"
-			+ "%view\t\tRender the view specified by the named view usage\n"
-			+ "%viz\t\tVisualize the name model elements\n"
 			;
 
+	private static final String HELP_HELP_SHORT_STRING = "%help\t\tGet a list of available commands or help on a specific command";
 	private static final String HELP_HELP_STRING =
 			  "Usage: %help [<COMMAND>]\n\n"
 			+ "Print help information on the named SysML v2 magic <COMMAND>.\n"
 			+ "If no <COMMAND> is given, then list the available commands.\n";
 
+	private static final String EVAL_HELP_SHORT_STRING = "%eval\t\tEvaluate a given expression.";
 	private static final String EVAL_HELP_STRING =
 			  "Usage: %eval [--target=<NAME>] <EXPR>\n\n"
 			+ "Print the results of evaluating <EXPR> on the target given by <NAME>, which must be fully qualified.\n"
 			+ "If a target is not given, then evaluate <EXPR> in global scope.\n";
 
+	private static final String LIST_HELP_SHORT_STRING = "%list\t\tList loaded library packages or the results of a given query";
 	private static final String LIST_HELP_STRING =
 			  "Usage: %list [<QUERY>]\n\n"
 			+ "If <QUERY> is not given, then list all loaded library packages.\n"
@@ -71,17 +68,24 @@ public class SysMLInteractiveHelp {
 			+ "    <NAME>::**\t\tall members of the namespace <NAME> and, recursively, members of owned namespaces.\n" 
 			+ "The last two forms may be optionally followed by a filter expression in square brackets.\n";
 
+	private static final String SHOW_HELP_SHORT_STRING = 
+			"%show\t\tPrint the abstract syntax tree rooted in a named element";
 	private static final String SHOW_HELP_STRING =
 			  "Usage: %show [--style=<STYLE>] <NAME>\n\n"
 			+ "Print the abstract syntax tree rooted in <NAME>. <NAME> must be fully qualified.\n\n"
 			+ "<STYLE> is also case insensitive. The possible style names are:\n"
     	    + "   TREE\t\tHierarchically indented representation with only identifying information\n"
     	    + "   JSON\t\tComplete JSON representation of the tree\n";
 
+	private static final String PUBLISH_HELP_SHORT_STRING =
+			"%publish\tPublish to the repository the modele elements rooted in a named element";
 	private static final String PUBLISH_HELP_STRING =
 			  "Usage: %publish <NAME>\n\n"
 			+ "Publish the model elements rooted in <NAME> to the repository. <NAME> must be fully qualified.\n";
 
+	
+	private static final String VIZ_HELP_SHORT_STRING =
+			"%viz\t\tVisualize the name model elements";
     private static final String VIZ_HELP_STRING =
     	      "Usage: %viz [--view=<VIEW>] [--style=<STYLE>...] <NAME> [<NAME>...]\n\n"
     	    + "Visualize model elements of <NAME>(s). <NAME>s must be fully qualified.\n\n"
@@ -99,6 +103,8 @@ public class SysMLInteractiveHelp {
     	    + "\t%viz --view Tree --style LR --style ortholine Pkg1::PartDef Pkg1::Pkg2::partUsage\n"
     	    + "should visualize Pkg1::PartDef and Pkg1::Pkg2::partUsage with a tree view ordered in the left-to-right direction with orthogonal lines.\n";
 
+    private static final String VIEW_HELP_SHORT_STRING =
+			"%view\t\tRender the view specified by the named view usage";
     private static final String VIEW_HELP_STRING =
     	      "Usage: %view [--render=<RENDERING>] [--style=<STYLE>...] <NAME>\n\n"
     	    + "Render the view specified by the view usage <NAME>. <NAME> must be fully qualified.\n"
@@ -114,23 +120,38 @@ public class SysMLInteractiveHelp {
             + SysML2PlantUMLStyle.getStyleHelp();
 
 
+    private static final String EXPORT_HELP_SHORT_STRING = 
+    		"%export\t\tSave a file of the JSON representation of the abstract syntax tree rooted in the named element.";
 	private static final String EXPORT_HELP_STRING =
 			  "Usage: %export <NAME>\n\n"
 			+ "Save a file containing the complete JSON representation of the abstract syntax tree rooted in <NAME>.\n"
 		    + "<NAME> must be fully qualified.\n";
 
+	private static final String LOAD_HELP_SHORT_STRING = "%load\t\tLoads a model from the repository and adds it to the Xtext index"; 
 	private static final String LOAD_HELP_STRING =
 			  "Usage: %load [--id=<PROJECT ID] [--name=<NAME>] [<NAME>]\n\n"
-			+ "Downloads previously published models from the repository. <NAME> must be the full name of the project.\n"
+			+ "Downloads previously published models from the repository. <NAME> must be the full name of the project."
 			+ "Use --id=<PROJECT ID> to load projects by id.\n"		  
 			+ "Use %projects to view repository contents.\n";
 
+	private static final String PROJECTS_HELP_SHORT_STRING = "%load\t\tLoads a model from the repository and adds it to the Xtext index"; 
 	private static final String PROJECTS_HELP_STRING =
 			  "Usage: %projects\n\n"
 			+ "Returns the name and identifier from the repository for all publications\n";
 
+	private static String generalHelpCached;
+	
 	public static String getGeneralHelp() {
-		return GENERAL_HELP_STRING;
+		if (generalHelpCached == null) {
+			StringBuilder sb = new StringBuilder();
+			sb.append(GENERAL_HELP_STRING_PREFIX);
+			for (var entry: commandShortHelpMap.entrySet()) {
+				sb.append(entry.getValue());
+				sb.append(System.lineSeparator());
+			}
+			generalHelpCached = sb.toString();
+		}
+		return generalHelpCached;
 	}
 
 	public static String getHelpHelp() {
@@ -173,22 +194,37 @@ public static String getLoadHelp() {
     	return LOAD_HELP_STRING;
     }
 
-    private static Map<String, String> commandHelpMap = createCommandHelpMap();
+    private static Map<String, String> commandShortHelpMap = new TreeMap<>();
+    private static Map<String, String> commandHelpMap = new HashMap<>();
+    static {
+    	registerHelpString("%help", HELP_HELP_SHORT_STRING, HELP_HELP_STRING);
+    	registerHelpString("%eval", EVAL_HELP_SHORT_STRING, EVAL_HELP_STRING);
+    	registerHelpString("%list", LIST_HELP_SHORT_STRING, LIST_HELP_STRING);    	
+    	registerHelpString("%show", SHOW_HELP_SHORT_STRING, SHOW_HELP_STRING);    	
+    	registerHelpString("%publish", PUBLISH_HELP_SHORT_STRING, PUBLISH_HELP_STRING);    	
+    	registerHelpString("%viz", VIZ_HELP_SHORT_STRING, VIZ_HELP_STRING);    	
+    	registerHelpString("%view", VIEW_HELP_SHORT_STRING, VIEW_HELP_STRING);    	
+    	registerHelpString("%export", EXPORT_HELP_SHORT_STRING, EXPORT_HELP_STRING);
+    	registerHelpString("%load", LOAD_HELP_SHORT_STRING, LOAD_HELP_STRING);
+    	registerHelpString("%projects", PROJECTS_HELP_SHORT_STRING, PROJECTS_HELP_STRING);
+    }
 
-    private static Map<String, String> createCommandHelpMap() {
-    	Map<String, String> map = new HashMap<>();
-    	map.put("%help", HELP_HELP_STRING);    	
-    	map.put("%eval", EVAL_HELP_STRING);    	
-    	map.put("%list", LIST_HELP_STRING);    	
-    	map.put("%show", SHOW_HELP_STRING);    	
-    	map.put("%publish", PUBLISH_HELP_STRING);    	
-    	map.put("%viz", VIZ_HELP_STRING);    	
-    	map.put("%view", VIEW_HELP_STRING);    	
-    	map.put("%export", EXPORT_HELP_STRING);
-    	map.put("%load", LOAD_HELP_STRING);
-    	map.put("%projects", PROJECTS_HELP_STRING);
-    	
-    	return map;
+    /**
+     * Adds command helps to the centralized store.
+     * @param command The name of the magic command, including the '%' prefix
+     * @param shortDescription
+     * 		A one-line description of a command, including the command name with the '%' prefix
+     * 		one or two tabs to make the output of the %help command nicely formatted.
+     * @param detailedHelp
+     * 		A multi-line help for a given command, expected to also detail the parameter formatting
+     * 
+     * @throws IllegalStateException when help for a command is being re-registered
+     */
+    public static void registerHelpString(String command, String shortDescription, String detailedHelp) {
+    	Preconditions.checkState(!commandHelpMap.containsKey(command), "Help is already registered for command %s", command);
+    	commandShortHelpMap.put(command, shortDescription);
+    	commandHelpMap.put(command, detailedHelp);
+    	generalHelpCached = null;
     }
 
     public static String getHelpString(String command) {

org.omg.sysml.jupyter.kernel/.classpath

@@ -21,7 +21,6 @@
 	</classpathentry>
 	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-17">
 		<attributes>
-			<attribute name="module" value="true"/>
 			<attribute name="maven.pomderived" value="true"/>
 		</attributes>
 	</classpathentry>
@@ -37,12 +36,6 @@
 			<attribute name="maven.pomderived" value="true"/>
 		</attributes>
 	</classpathentry>
-	<classpathentry kind="src" output="target/classes" path="target/kernel">
-		<attributes>
-			<attribute name="optional" value="true"/>
-			<attribute name="maven.pomderived" value="true"/>
-		</attributes>
-	</classpathentry>
 	<classpathentry combineaccessrules="false" kind="src" path="/org.omg.sysml.interactive"/>
 	<classpathentry combineaccessrules="false" kind="src" path="/org.omg.sysml"/>
 	<classpathentry kind="output" path="target/classes"/>

org.omg.sysml.jupyter.kernel/pom.xml

@@ -200,25 +200,6 @@
                 </execution>
             </executions>
         </plugin>
-
-        <!-- Needed for updating the version number in the kernel.json. This is used to copy the resources to the unzipped kernel.-->
-		<plugin>
-			<groupId>org.codehaus.mojo</groupId>
-			<artifactId>templating-maven-plugin</artifactId>
-			<version>3.0.0</version>
-			<executions>
-				<execution>
-					<phase>prepare-package</phase>
-					<goals>
-						<goal>filter-sources</goal>
-					</goals>
-				</execution>
-			</executions>
-			<configuration>
-				<sourceDirectory>src/main/resources</sourceDirectory>
-				<outputDirectory>target/kernel</outputDirectory>
-			</configuration>
-		</plugin>
 
        <plugin>
         <groupId>org.apache.maven.plugins</groupId>

org.omg.sysml.jupyter.kernel/src/main/java/org/omg/sysml/jupyter/kernel/IMagicCommandRegistrator.java

@@ -0,0 +1,31 @@
+/*****************************************************************************
+ * SysML 2 Pilot Implementation
+ * Copyright (c) 2025 Model Driven Solutions, Inc.
+ *    
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of theGNU Lesser General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * @license LGPL-3.0-or-later <http://spdx.org/licenses/LGPL-3.0-or-later>
+ * 
+ * Contributors:
+ *  Zoltan Ujhelyi, MDS
+ * 
+ *****************************************************************************/
+package org.omg.sysml.jupyter.kernel;
+
+import io.github.spencerpark.jupyter.kernel.magic.registry.Magics;
+
+public interface IMagicCommandRegistrator {
+
+	void registerMagicCommand(Magics magics);
+}

org.omg.sysml.jupyter.kernel/src/main/java/org/omg/sysml/jupyter/kernel/SysMLKernel.java

@@ -36,6 +36,7 @@
 import java.util.Arrays;
 import java.util.List;
 import java.util.Optional;
+import java.util.ServiceLoader;
 
 public class SysMLKernel extends BaseKernel {
 
@@ -82,6 +83,8 @@ public SysMLKernel() {
         this.magics.registerMagics(Export.class);
         this.magics.registerMagics(Projects.class);
         this.magics.registerMagics(Load.class);
+        
+        ServiceLoader.load(IMagicCommandRegistrator.class).forEach(reg -> reg.registerMagicCommand(this.magics));
 
         this.magicParser = new MyMagicParser();
     }

org.omg.sysml.jupyter.kernel/src/main/resources/sysml/kernel.json

@@ -1,8 +1,9 @@
 {
     "argv": [
         "java",
-        "-jar",
-        "@KERNEL_INSTALL_DIRECTORY@/jupyter-sysml-kernel-${project.version}-all.jar",
+		"-cp",
+		"@KERNEL_INSTALL_DIRECTORY@/*",
+		"org.omg.sysml.jupyter.kernel.ISysML",
         "{connection_file}"
     ],
     "display_name": "SysML",