feat: load or unload current project as extension, extn development workflow

Author: abose

docs/How-To-Write-Extensions-And-Themes.md

@@ -0,0 +1 @@
+This document outlines how to write your own extensions and themes for Phoenix Code.

src/command/Menus.js

@@ -525,7 +525,7 @@ define(function (require, exports, module) {
      *
      * @param {!string | Command} command - the command the menu will execute.
      *      Pass Menus.DIVIDER for a menu divider, or just call addMenuDivider() instead.
-     * @param {?string | Array.<{key: string, platform: string}>}  keyBindings - register one
+     * @param {?string | Array.<{key: string, platform: string}>}  [keyBindings] - register one
      *      one or more key bindings to associate with the supplied command.
      * @param {?string} [position] - constant defining the position of new MenuItem relative to
      *      other MenuItems. Values:

src/document/DocumentCommandHandlers.js

@@ -21,6 +21,7 @@
 
 // jshint ignore: start
 /*jslint regexp: true */
+/*globals logger*/
 
 define(function (require, exports, module) {
 
@@ -1777,22 +1778,42 @@ define(function (require, exports, module) {
      * Restarts brackets Handler
      * @param {boolean=} loadWithoutExtensions - true to restart without extensions,
      *                                           otherwise extensions are loadeed as it is durning a typical boot
+     * @param {Array<String>|string} loadDevExtensionPath If specified, will load the extension from the path. IF
+     * and empty array is specified, it will unload all dev extensions on reload.
      */
-    function handleReload(loadWithoutExtensions) {
+    function handleReload(loadWithoutExtensions, loadDevExtensionPath) {
         var href    = window.location.href,
             params  = new UrlParams();
 
         // Make sure the Reload Without User Extensions parameter is removed
         params.parse();
 
+        function _removeLoadDevExtensionPathParam() {
+            if (params.get("loadDevExtensionPath")) {
+                params.remove("loadDevExtensionPath");
+                // only remove logging flag if the flag is set for loadDevExtensionPath
+                if (params.get(logger.loggingOptions.LOCAL_STORAGE_KEYS.LOG_TO_CONSOLE_KEY)) {
+                    params.remove(logger.loggingOptions.LOCAL_STORAGE_KEYS.LOG_TO_CONSOLE_KEY);
+                }
+            }
+        }
+
         if (loadWithoutExtensions) {
             if (!params.get("reloadWithoutUserExts")) {
                 params.put("reloadWithoutUserExts", true);
             }
+            _removeLoadDevExtensionPathParam();
         } else {
             if (params.get("reloadWithoutUserExts")) {
                 params.remove("reloadWithoutUserExts");
             }
+            if(loadDevExtensionPath && loadDevExtensionPath.length){
+                params.put("loadDevExtensionPath", loadDevExtensionPath);
+                // since we are loading a development extension, we have to enable detailed logs too on reload
+                params.put(logger.loggingOptions.LOCAL_STORAGE_KEYS.LOG_TO_CONSOLE_KEY, "true");
+            } else if (loadDevExtensionPath && loadDevExtensionPath.length === 0) {
+                _removeLoadDevExtensionPathParam();
+            }
         }
 
         if (href.indexOf("?") !== -1) {

src/extensions/default/DebugCommands/extensionDevelopment.js

@@ -0,0 +1,100 @@
+/*
+ * GNU AGPL-3.0 License
+ *
+ * Copyright (c) 2021 - present core.ai . All rights reserved.
+ * Original work Copyright (c) 2012 - 2021 Adobe Systems Incorporated. All rights reserved.
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Affero 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 Affero General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see https://opensource.org/licenses/AGPL-3.0.
+ *
+ */
+
+/*globals path, logger*/
+
+define(function (require, exports, module) {
+    const ProjectManager         = brackets.getModule("project/ProjectManager"),
+        Commands                 = brackets.getModule("command/Commands"),
+        CommandManager           = brackets.getModule("command/CommandManager"),
+        Strings                  = brackets.getModule("strings"),
+        StringUtils              = brackets.getModule("utils/StringUtils"),
+        DocumentManager          = brackets.getModule("document/DocumentManager"),
+        DefaultDialogs           = brackets.getModule("widgets/DefaultDialogs"),
+        Dialogs                  = brackets.getModule("widgets/Dialogs"),
+        UrlParams                = brackets.getModule("utils/UrlParams").UrlParams,
+        FileSystem               = brackets.getModule("filesystem/FileSystem");
+
+    function _showError(message, title = Strings.ERROR_LOADING_EXTENSION) {
+        Dialogs.showModalDialog(
+            DefaultDialogs.DIALOG_ID_ERROR,
+            title, message
+        );
+    }
+
+    function _validatePackageJson(docText) {
+        try {
+            let packageJson = JSON.parse(docText);
+            let requiredFields = ["name", "title", "description", "homepage", "version", "author", "license",
+                "engines"];
+            let missingFields = [];
+            for(let requiredField of requiredFields){
+                if(!packageJson[requiredField]){
+                    missingFields.push(requiredField);
+                }
+            }
+            if(missingFields.length){
+                _showError(StringUtils.format(Strings.ERROR_INVALID_EXTENSION_PACKAGE_FIELDS, missingFields));
+                return false;
+            }
+            return true;
+        } catch (e) {
+            console.log("Cannot load extension", Strings.ERROR_INVALID_EXTENSION_PACKAGE);
+            _showError(Strings.ERROR_INVALID_EXTENSION_PACKAGE);
+            return false;
+        }
+    }
+
+    function loadCurrentExtension() {
+        const projectRoot = ProjectManager.getProjectRoot().fullPath;
+        const file = FileSystem.getFileForPath(projectRoot + "package.json");
+        DocumentManager.getDocumentText(file).done(function (docText) {
+            console.log(docText);
+            if(!_validatePackageJson(docText)){
+                return;
+            }
+            CommandManager.execute(Commands.APP_RELOAD, false, projectRoot);
+        }).fail((err)=>{
+            console.log("No extension package.json in ", file.fullPath, err);
+            Dialogs.showModalDialog(
+                DefaultDialogs.DIALOG_ID_ERROR,
+                Strings.ERROR_LOADING_EXTENSION,
+                Strings.ERROR_NO_EXTENSION_PACKAGE
+            );
+        });
+    }
+
+    function unloadCurrentExtension() {
+        CommandManager.execute(Commands.APP_RELOAD, false, []);
+    }
+
+    function isProjectLoadedAsExtension() {
+        const params  = new UrlParams();
+
+        // Make sure the Reload Without User Extensions parameter is removed
+        params.parse();
+        return !!params.get("loadDevExtensionPath");
+    }
+
+    exports.loadCurrentExtension = loadCurrentExtension;
+    exports.unloadCurrentExtension = unloadCurrentExtension;
+    exports.isProjectLoadedAsExtension = isProjectLoadedAsExtension;
+});

src/extensions/default/DebugCommands/main.js

@@ -44,6 +44,7 @@ define(function (require, exports, module) {
         Mustache               = brackets.getModule("thirdparty/mustache/mustache"),
         Locales                = brackets.getModule("nls/strings"),
         ProjectManager         = brackets.getModule("project/ProjectManager"),
+        extensionDevelopment   = require("extensionDevelopment"),
         PerfDialogTemplate     = require("text!htmlContent/perf-dialog.html"),
         LanguageDialogTemplate = require("text!htmlContent/language-dialog.html");
 
@@ -66,7 +67,9 @@ define(function (require, exports, module) {
       * Debug commands IDs
       * @enum {string}
       */
-    const DEBUG_REFRESH_WINDOW                  = "debug.refreshWindow", // string must MATCH string in native code (brackets_extensions)
+    const DEBUG_REFRESH_WINDOW                = "debug.refreshWindow", // string must MATCH string in native code (brackets_extensions)
+        DEBUG_LOAD_CURRENT_EXTENSION          = "debug.loadCurrentExtension",
+        DEBUG_UNLOAD_CURRENT_EXTENSION        = "debug.unloadCurrentExtension",
         DEBUG_RUN_UNIT_TESTS                  = "debug.runUnitTests",
         DEBUG_SHOW_PERF_DATA                  = "debug.showPerfData",
         DEBUG_RELOAD_WITHOUT_USER_EXTS        = "debug.reloadWithoutUserExts",
@@ -725,6 +728,12 @@ define(function (require, exports, module) {
     }
 
     /* Register all the command handlers */
+    let loadOrReloadString = extensionDevelopment.isProjectLoadedAsExtension() ?
+        Strings.CMD_RELOAD_CURRENT_EXTENSION : Strings.CMD_LOAD_CURRENT_EXTENSION;
+    CommandManager.register(loadOrReloadString,     DEBUG_LOAD_CURRENT_EXTENSION,
+        extensionDevelopment.loadCurrentExtension);
+    CommandManager.register(Strings.CMD_UNLOAD_CURRENT_EXTENSION,     DEBUG_UNLOAD_CURRENT_EXTENSION,
+        extensionDevelopment.unloadCurrentExtension);
     CommandManager.register(Strings.CMD_REFRESH_WINDOW,             DEBUG_REFRESH_WINDOW,           handleReload);
     CommandManager.register(Strings.CMD_RELOAD_WITHOUT_USER_EXTS,   DEBUG_RELOAD_WITHOUT_USER_EXTS, handleReloadWithoutUserExts);
     CommandManager.register(Strings.CMD_NEW_BRACKETS_WINDOW,        DEBUG_NEW_BRACKETS_WINDOW,      handleNewBracketsWindow);
@@ -751,6 +760,10 @@ define(function (require, exports, module) {
     var menu = Menus.addMenu(Strings.DEBUG_MENU, DEBUG_MENU, Menus.BEFORE, Menus.AppMenuBar.HELP_MENU);
     menu.addMenuItem(DEBUG_REFRESH_WINDOW, KeyboardPrefs.refreshWindow);
     menu.addMenuItem(DEBUG_RELOAD_WITHOUT_USER_EXTS, KeyboardPrefs.reloadWithoutUserExts);
+    menu.addMenuItem(DEBUG_LOAD_CURRENT_EXTENSION);
+    menu.addMenuItem(DEBUG_UNLOAD_CURRENT_EXTENSION, undefined, undefined, undefined, {
+        hideWhenCommandDisabled: true
+    });
     menu.addMenuItem(DEBUG_NEW_BRACKETS_WINDOW);
     menu.addMenuDivider();
     menu.addMenuItem(DEBUG_SWITCH_LANGUAGE);
@@ -767,6 +780,8 @@ define(function (require, exports, module) {
     menu.addMenuItem(DEBUG_OPEN_PREFERENCES_IN_SPLIT_VIEW); // this command will enable defaultPreferences and brackets preferences to be open side by side in split view.
     menu.addMenuItem(Commands.FILE_OPEN_KEYMAP);      // this command is defined in core, but exposed only in Debug menu for now
 
+    CommandManager.get(DEBUG_UNLOAD_CURRENT_EXTENSION)
+        .setEnabled(extensionDevelopment.isProjectLoadedAsExtension());
     _updateLogToConsoleMenuItemChecked();
     // exposed for convenience, but not official API
     exports._runUnitTests = _runUnitTests;

src/nls/root/strings.js

@@ -671,6 +671,9 @@ define({
     "ERRORS": "Errors",
     "CMD_SHOW_DEV_TOOLS": "Show Developer Tools",
     "CMD_REFRESH_WINDOW": "Reload With Extensions",
+    "CMD_LOAD_CURRENT_EXTENSION": "Load Project As Extension",
+    "CMD_RELOAD_CURRENT_EXTENSION": "Reload Project As Extension",
+    "CMD_UNLOAD_CURRENT_EXTENSION": "Unload Project As Extension",
     "CMD_RELOAD_WITHOUT_USER_EXTS": "Reload Without Extensions",
     "CMD_NEW_BRACKETS_WINDOW": "New {APP_NAME} Window",
     "CMD_LAUNCH_SCRIPT_MAC": "Install Command Line Shortcut",
@@ -689,6 +692,10 @@ define({
     "ERROR_CLTOOLS_SERVFAILED": "Internal error.",
     "ERROR_CLTOOLS_NOTSUPPORTED": "Command line shortcut is not supported on this OS.",
     "LAUNCH_SCRIPT_CREATE_SUCCESS": "Success! Now you can easily launch {APP_NAME} from the command line: <code>brackets myFile.txt</code> to open a file or <code>brackets myFolder</code> to switch projects. <br/><br/><a href='https://github.com/adobe/brackets/wiki/Command-Line-Arguments'>Learn more</a> about using {APP_NAME} from the command line.",
+    "ERROR_LOADING_EXTENSION": "Error Loading Extension",
+    "ERROR_NO_EXTENSION_PACKAGE": "<code>package.json</code> file not detected in current project. Is the current project a valid {APP_NAME} Extension?",
+    "ERROR_INVALID_EXTENSION_PACKAGE": "<code>package.json</code> file is invalid JSON.",
+    "ERROR_INVALID_EXTENSION_PACKAGE_FIELDS": "Required fields missing in <code>package.json</code>: [{0}]",
 
     "LANGUAGE_TITLE": "Switch Language",
     "LANGUAGE_MESSAGE": "Language:",

src/utils/ExtensionLoader.js

@@ -493,6 +493,20 @@ define(function (require, exports, module) {
         return _loadAll(directory, {baseUrl: directory}, "main", loadExtension);
     }
 
+    /**
+     * Loads a given extension at the path from native directory.
+     * @param directory
+     * @return {!Promise}
+     */
+    function loadExtensionFromNativeDirectory(directory) {
+        logger.leaveTrail("loading custom extension from path: " + directory);
+        const extConfig = {
+            baseUrl: window.fsServerUrl.slice(0, -1) + directory
+        };
+        return loadExtension("ext" + directory.replace("/", "-"), // /fs/user/extpath to ext-fs-user-extpath
+            extConfig, 'main');
+    }
+
     /**
      * Runs unit test for the extension that lives at baseUrl into its own Require.js context
      *
@@ -624,6 +638,12 @@ define(function (require, exports, module) {
             } else {
                 paths = [];
             }
+            if(params.get("loadDevExtensionPath")){
+                let customLoadPaths = params.get("loadDevExtensionPath").split(",");
+                for(let customPath of customLoadPaths){
+                    paths.push("custom:" + customPath);
+                }
+            }
         }
 
         // Load extensions before restoring the project
@@ -646,6 +666,8 @@ define(function (require, exports, module) {
         var promise = Async.doInParallel(paths, function (extPath) {
             if(extPath === "default"){
                 return loadAllDefaultExtensions();
+            } else if(extPath.startsWith("custom:")){
+                return loadExtensionFromNativeDirectory(extPath.replace("custom:", ""));
             } else {
                 return loadAllExtensionsInNativeDirectory(extPath);
             }