ST6RI-823 Support extending Jupyter integration with additional magic commands

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

@@ -30,37 +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\t\tLoad a model from the repository\n"
-			+ "%repo\t Set the api base path for the repository\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"
@@ -72,13 +68,17 @@ 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 [-d] [--project=<PROJECT NAME>] [--branch=<BRANCH NAME>] <NAME>\n\n"
 			+ "Publish the model elements rooted in <NAME> to the repository. <NAME> must be fully qualified.\n"
@@ -90,6 +90,9 @@ public class SysMLInteractiveHelp {
 			+ "If <BRANCH NAME> is given, then the model is written to this branch of the project.\n"
 			+ "If <BRANCH NAME> is not given, the default branch is used.\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"
@@ -107,6 +110,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"
@@ -122,11 +127,14 @@ 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";
 	private static final String LOAD_HELP_STRING =
 			"Usage: %load [--id=<PROJECT ID] [--name=<NAME>] [--branch=<BRANCH_NAME>] [<NAME>]\n\n"
 			+ "Download previously published models from a project in the repository. <NAME> is the full name of the project.\n"
@@ -136,20 +144,33 @@ public class SysMLInteractiveHelp {
 			+ "If <BRANCH NAME> is given, then the model is loaded from this branch of the project.\n"
 			+ "If <BRANCH NAME> is not given, the default branch is used.\n";
 
+	private static final String PROJECTS_HELP_SHORT_STRING = "%projects\tList projects in the repository";
 	private static final String PROJECTS_HELP_STRING =
 			  "Usage: %projects\n\n"
 			+ "Print the name and identifier of all projects in the repository.\n";
 
+	private static final String API_BASE_PATH_HELP_SHORT_STRING ="%repo\tSet the api base path for the repository";
 	private static final String API_BASE_PATH_HELP_STRING =
 			  "Usage: %repo [<BASE PATH>]\n\n"
 			+ "If <BASE PATH> is not given, print the current repository base path.\r\n"
 			+ "If <BASE PATH> is given, set the repository base path.\r\n"
 			+ "\r\n"
 			+ "<BASE PATH> is a URL giving the API base path for the repository access by the %projects, %publish and %load commands. \r\n"
 			+ "For example: https://my.domain.com/sysml_repo";
-
+
+	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() {
@@ -196,23 +217,38 @@ public static String getApiBasePathHelp() {
     	return API_BASE_PATH_HELP_STRING;
 	}
 
-    private static Map<String, String> commandHelpMap = createCommandHelpMap();
-
-    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);
-    	map.put("%repo", API_BASE_PATH_HELP_STRING);
-
-    	return map;
+    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);
+		registerHelpString("%repo", API_BASE_PATH_HELP_SHORT_STRING, API_BASE_PATH_HELP_STRING);
+    }
+
+    /**
+     * 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,46 @@
+/*****************************************************************************
+ * 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 org.omg.sysml.interactive.SysMLInteractiveHelp;
+
+import io.github.spencerpark.jupyter.kernel.magic.registry.Magics;
+
+public interface IMagicCommandRegistrator {
+
+	/**
+	 * Implementors of this method are free to register their extra commands to the
+	 * Jupyter kernel. This method is called when the Jupyter environment is
+	 * initialized and it assumed the registration code will run quickly and without
+	 * exceptions. If the registrator cannot run successfully, it should not
+	 * register anything instead of throwing an exception.
+	 * </p>
+	 * Implementors are recommended to use the register methods of the {@link Magics}
+	 * class. Help is managed by the {@link SysMLInteractiveHelp} class.
+	 *
+	 * @see Magics#registerMagics(Class)
+	 * @see SysMLInteractiveHelp#registerHelpString(String, String, String)
+	 */
+	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 {
 
@@ -84,6 +85,18 @@ public SysMLKernel() {
         this.magics.registerMagics(Load.class);
         this.magics.registerMagics(ApiBasePath.class);
 
+		ServiceLoader.load(IMagicCommandRegistrator.class).forEach(reg -> {
+			try {
+				reg.registerMagicCommand(this.magics);
+			} catch (Exception e) {
+				// Given there is no available logging mechanism and an exception thrown by the
+				// registrator would cause the Jupyter kernel not to start up correctly, errors
+				// are logged to the standard err output, but otherwise ignored.
+				System.err.printf("Error while running the command registrator %s: %s", reg.getClass().getTypeName(),
+						e.getMessage());
+			}
+		});
+
         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",