feat: node extension scaffolding

Author: abose

.gitignore

@@ -0,0 +1,3 @@
+node_modules
+node/node_modules
+.idea

README.md

@@ -1,12 +1,24 @@
 # Extension Template
 
-Quick start and create a new extension by using this template. Follow the below 4 steps:
+Quick start and create a new `node.js extension` by using this template. This
+template extension works in browser as well as desktop builds.
 
-Refer this [link](https://github.com/phcode-dev/phoenix/wiki/How-To-Write-Extensions-And-Themes) for detailed extension docs after following the below steps:
+In desktop builds, there is an additional capability to execute node.js code. This
+is helpful if you want to extend the functionality of Phoenix Code using the
+vast npm library.
+
+For creating extensions that do not need node, follow this link:
+https://github.com/phcode-dev/extension-template
+
+Follow the below 4 steps to start using this template:
+
+Refer this
+[link](https://github.com/phcode-dev/phoenix/wiki/How-To-Write-Extensions-And-Themes)
+for detailed extension docs after following the below steps:
 
 ## step 1
 
-Login with github: https://github.com/login
+Login with GitHub: https://github.com/login
 
 ## step 2
 
@@ -15,26 +27,35 @@ Create a new repository using this template.
 
 ## step 3
 
-* Clone your GitHub Repo created from `step 2`. See [this link](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) to lean how to clone a repository from GitHub.
+-   Clone your GitHub Repo created from `step 2`. See
+    [this link](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
+    to lean how to clone a repository from GitHub.
 
 ## step 4
 
-* Go to https://create.phcode.dev .This is a special development centric website of phcode.dev which shows non minified js/css files in the browser developer tools.
-* Open the cloned folder and select `Debug > Load Project As Extension`
+-   Go to https://create.phcode.dev .This is a special development centric
+    website of phcode.dev which shows non minified js/css files in the browser
+    developer tools.
+-   Open the cloned folder and select `Debug > Load Project As Extension`
 
 ![image](https://user-images.githubusercontent.com/5336369/224746152-0416a862-891a-4fe1-b9dd-09add25a6cc0.png)
 
-
-* You can now make code changes to your extension and select `Debug> Reload With Extensions` to test the new code changes.
-* When you are done developing the extension/theme, select `Debug> Unload Project As Extension` to unload the extension.
+-   You can now make code changes to your extension and select
+    `Debug> Reload With Extensions` to test the new code changes.
+-   When you are done developing the extension/theme, select
+    `Debug> Unload Project As Extension` to unload the extension.
 
 ![image](https://user-images.githubusercontent.com/5336369/224747590-556dff1d-5b29-41c3-88a0-3ce72ab643d0.png)
 
 # Detailed Documentation
 
-Please go to https://github.com/phcode-dev/phoenix/wiki/How-To-Write-Extensions-And-Themes for more documentation/community support links.
+Please go to
+https://github.com/phcode-dev/phoenix/wiki/How-To-Write-Extensions-And-Themes
+for more documentation/community support links.
 
 # Publishing your extension to the repository
 
-Once you have built your extension/theme, you can publish the extension to phcode.dev extension repository in a single step directly from this repo.
-Please see publish section in this link for more details: https://github.com/phcode-dev/phoenix/wiki/How-To-Write-Extensions-And-Themes
+Once you have built your extension/theme, you can publish the extension to
+phcode.dev extension repository in a single step directly from this repo. Please
+see publish section in this link for more details:
+https://github.com/phcode-dev/phoenix/wiki/How-To-Write-Extensions-And-Themes

main.js

@@ -1,9 +1,14 @@
+/**
+ * A simple extension that downloads an image and then converts it to grey scale using `sharp` node.js lib via
+ * Phoenix Code node.js Extension. Extension can be activated using menu: `file->Download Image & Greyscale`.
+ * */
+
 /*global define, brackets, $ */
 
 // See detailed docs in https://github.com/phcode-dev/phoenix/wiki/How-To-Write-Extensions-And-Themes
 // A good place to look for code examples for extensions: https://github.com/phcode-dev/phoenix/tree/main/src/extensions/default
 
-// A simple extension that adds an entry in "file menu> hello world"
+
 define(function (require, exports, module) {
     "use strict";
 
@@ -12,32 +17,78 @@ define(function (require, exports, module) {
         DefaultDialogs = brackets.getModule("widgets/DefaultDialogs"),
         Dialogs = brackets.getModule("widgets/Dialogs"),
         CommandManager = brackets.getModule("command/CommandManager"),
-        Menus = brackets.getModule("command/Menus");
+        Menus = brackets.getModule("command/Menus"),
+        NodeConnector = brackets.getModule("NodeConnector");
+
+    const nodeConnector = NodeConnector.createNodeConnector(
+        "your-extension-id-1",
+        exports
+    );
+
+    async function fetchImage() {
+        const imageUrl = "https://picsum.photos/536/354";
+        const response = await fetch(imageUrl);
+
+        if (!response.ok) {
+            throw new Error(
+                `Failed to fetch image (status ${response.status})`
+            );
+        }
+
+        return response.arrayBuffer();
+    }
 
     // Function to run when the menu item is clicked
-    function handleHelloWorld() {
-        Dialogs.showModalDialog(
-            DefaultDialogs.DIALOG_ID_INFO,
-            "hello",
-            "world"
-        );
+    async function handleHelloWorld() {
+        let html = "<b>Image conversion failed</b>";
+        try {
+            alert("downloading image...");
+            // Fetch the image and get its array buffer
+            const imageArrayBuffer = await fetchImage();
+
+            // Call the nodeConnector to convert the image to grayscale
+            const { buffer, success } = await nodeConnector.execPeer(
+                "convertToGreyScale",
+                { imageName: "imageName" },
+                imageArrayBuffer
+            );
+
+            if (!success) {
+                alert("Image conversion failed in Node.");
+                return;
+            }
+
+            // Construct HTML with the grayscale image array buffer
+            // For example, you can use the buffer as a base64 data URL
+            html = `<img src="data:image/jpeg;base64,${Buffer.from(buffer).toString("base64")}">`;
+        } catch (error) {
+            console.error("Error:", error);
+        }
+        Dialogs.showModalDialog(DefaultDialogs.DIALOG_ID_INFO, "Image to greyscale with node.js", html);
     }
-    
-      // First, register a command - a UI-less object associating an id to a handler
-    var MY_COMMAND_ID = "helloworld.sayhello";   // package-style naming to avoid collisions
-    CommandManager.register("Hello World", MY_COMMAND_ID, handleHelloWorld);
+
+    // First, register a command - a UI-less object associating an id to a handler
+    var MY_COMMAND_ID = "helloworld.imageConvert"; // package-style naming to avoid collisions
+    CommandManager.register("Download Image & Greyscale", MY_COMMAND_ID, handleHelloWorld);
 
     // Then create a menu item bound to the command
     // The label of the menu item is the name we gave the command (see above)
     var menu = Menus.getMenu(Menus.AppMenuBar.FILE_MENU);
     menu.addMenuItem(MY_COMMAND_ID);
-    
+
     // We could also add a key binding at the same time:
     //menu.addMenuItem(MY_COMMAND_ID, "Ctrl-Alt-W");
     // (Note: "Ctrl" is automatically mapped to "Cmd" on Mac)
-    
+
     // Initialize extension once shell is finished initializing.
     AppInit.appReady(function () {
+        // nb: Please enable `Debug menu> Phoenix code diagnostic tools> enable detailed logs` to view all console logs.`
         console.log("hello world");
+
+        if (Phoenix.isNativeApp) {
+            // you can also execute nodejs code in dekstop builds
+            // below code will execute the function `echoTest` defined in `node/index.js`
+            nodeConnector.execPeer("echoTest", "yo!").then(console.log);
+        }
     });
 });

node/README.md

@@ -0,0 +1,56 @@
+## Setting up node extensions
+
+In package.json, add the following section
+
+```json
+{
+    "nodeConfig": {
+        "nodeIsRequired": false,
+        "main": "node/index.js",
+        "npmInstall": "node/"
+    }
+}
+```
+
+#### `nodeConfig` Object
+
+The `nodeConfig` object indicates that this is a Node extension.
+
+#### `nodeIsRequired` Field
+
+-   Set this field to `true` if the extension relies on Node and won't function
+    without it.
+-   If set to `false` or omitted, the extension can still be loaded in browser
+    versions of Phoenix code without Node support, But will use node in native
+    builds.
+-   It will be shown in the extension manager dialog in browser builds as well.
+
+#### `main` Field
+
+-   Specifies the main entry point for the Node.js component of the extension.
+-   Should point to the main JavaScript file for the Node part of the extension.
+-   Example: `"main": "node/index.js"`
+
+#### `npmInstall` Field (Optional)
+
+-   Specifies the path to run `npm install` when the user installs the extension
+    from the extension manager.
+-   It's advisable not to package `node_modules` inside the extension. Only the
+    package lock file should be distributed.
+-   Example: `"npmInstall": "node/"`
+
+## Communicating between node.js and Phoenix Code
+
+### NodeConnector-API
+
+create
+[NodeConnector-API](https://github.com/phcode-dev/phoenix/wiki/NodeConnector-API)
+to call functions and send events between your node.js and Phoenix Code
+extension components.
+
+-   This is available as a global object `global.createNodeConnector`. See above
+    link for API docs.
+-   Another API -
+    [EventDispatcher-API](https://github.com/phcode-dev/phoenix/wiki/EventDispatcher-API)
+    is also available in the global context as `global.EventDispatcher` for
+    event trigger/listen within node.

node/index.js

@@ -0,0 +1,42 @@
+/**
+ * This is an optional node extension that is available only in desktop builds. This code will be run in node. You can
+ * bring in any third party node modules using package.json in folder `node/package.json`
+ *
+ * nb: Please note that you should not package `node_modules` folder when you care creating the extension zip file.
+ * Zip `node/package-lock.json`, but not node modules.
+ *
+ * To communicate between this node file and the phoenix extension use: NodeConnector-API -
+ * See. https://github.com/phcode-dev/phoenix/wiki/NodeConnector-API for detailed docs.
+ **/
+console.log("hello world node extension");
+
+const sharp = require("sharp");
+
+const extnNodeConnector = global.createNodeConnector(
+    "your-extension-id-1",
+    exports
+);
+
+async function echoTest(name) {
+    return "hello from node " + name;
+}
+
+async function convertToGreyScale(imageName, imageArrayBuffer) {
+    try {
+        // Convert the image buffer to grayscale using sharp
+        const outputBuffer = await sharp(imageArrayBuffer)
+            .grayscale() // Convert to grayscale
+            .toBuffer(); // Convert to buffer
+
+        // Return the output buffer
+        return {
+            success: true,
+            buffer: outputBuffer // a single binary array buffer can be transmitted, it should use key buffer
+        };
+    } catch (error) {
+        throw new Error("Error converting image to black and white:", error);
+    }
+}
+
+exports.echoTest = echoTest;
+exports.convertToGreyScale = convertToGreyScale;