lucid-package 0.0.3 → 0.0.6

package/README.md

@@ -2,7 +2,76 @@
 
 ## Description
 
-CLI for creating and managing extensibility packages for the products of Lucid Software.
+CLI for creating and managing extension packages for the products of Lucid Software.
+
+## Getting started
+
+### Step 1: Install `lucid-package` and create a new package
+
+An extension package is a set of Lucid product extensions that is installable by a Lucid
+account admin for use by all of their users. In order to start building an extension, you
+need to create a package to contain it.
+
+In a directory that will contain your extension packages:
+
+```
+npm install lucid-package
+npx lucid-package create my-new-package-name
+```
+
+### Step 2: Add an editor extension to your new package
+
+An editor extension is a piece of custom code that executes inside a Lucid product such
+as Lucidchart or Lucidspark. The `lucid-package` CLI provides a quick-start template to
+help you get up and running immediately.
+
+To add a new extension to your package:
+
+```
+cd my-new-package-name
+npx lucid-package create-editor-extension my-extension-name
+```
+
+### Step 3: Serve your extension code in debug mode to test it
+
+You don't need to package, upload, and install your extension in order to run it and
+make sure it works. The following command will start `webpack` on your code in `--watch`
+mode, and start up a local HTTP server that Lucid products can connect to, to load your
+latest code.
+
+To start the debug server:
+
+```
+npx lucid-package test-editor-extension my-extension-name
+```
+
+You can then enable loading of your local plugin in the Developer menu in Lucidchart
+by clicking `Load local extension`. The page will refresh and your extension code will run.
+
+The main entry point to your new editor extension is in `editorextensions/my-extension-name/src/extension.ts`.
+Experiment by changing code in that file and refreshing your browser tab to reload it.
+
+For all published extensions, and by default for this debug server as well, your code
+runs in a sandboxed JavaScript VM for security. However, this makes debugging difficult.
+If you turn on the `Debug local extensions (no sandbox)` option in the Developer menu,
+your code will be run via a scoped `eval`, allowing you to use the standard browser
+debugging tools to examine and step through your code.
+
+We recommend that you do all final validation of your extension with the normal
+sandbox enabled, however, as you may have inadvertently used features not allowed in
+the sandbox that won't work once you release your extension.
+
+### Step 4: Prepare your package for upload
+
+Once your editor extension works the way you want, you can package it for upload to the
+Lucid developer dashboard:
+
+```
+npx lucid-package package
+```
+
+This will create the file `package.zip` which is ready for upload to the [Lucid developer
+dashboard](https://lucid.app/developer).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "lucid-package",
-    "version": "0.0.3",
+    "version": "0.0.6",
     "description": "",
     "main": "index.js",
     "bin": {
@@ -19,11 +19,14 @@
     },
     "dependencies": {
         "argparse": "^2.0.1",
+        "chokidar": "^3.5.3",
         "express": "^4.17.1",
+        "hjson": "^3.2.2",
         "jszip": "^3.7.1",
         "password-prompt": "^1.1.2",
         "ts-loader": "^9.2.6",
         "webpack": "^5.64.4",
-        "webpack-cli": "^4.9.1"
+        "webpack-cli": "^4.9.1",
+        "ws": "^8.5.0"
     }
 }

package/src/editorextension.js

@@ -6,16 +6,17 @@ const filesystemutil_1 = require("./filesystemutil");
 const package_1 = require("./package");
 const express = require("express");
 const child_process = require("child_process");
+const shapelibrary_1 = require("./shapelibrary");
 const WebPackCLI = require('webpack-cli');
 async function createEditorExtension(name, isInternalTesting) {
     console.log('Creating empty editor extension in editorextensions/' + name);
     (0, filesystemutil_1.copyFolderRecursiveSync)(__dirname + '/../templates/editorextension', 'editorextensions/' + name);
     await (0, package_1.modifyManifest)((manifest) => {
-        manifest.extensions.push({
-            name: name,
-            title: name,
-            codePath: `editorextensions/${name}/bin/extension.js`,
-            scopes: ['READ', 'DOWNLOAD'],
+        manifest['extensions'].push({
+            'name': name,
+            'title': name,
+            'codePath': `editorextensions/${name}/bin/extension.js`,
+            'scopes': ['READ', 'DOWNLOAD'],
         });
     });
     console.log(`Installing dependencies`);
@@ -50,13 +51,17 @@ async function debugEditorExtension(name) {
     const cli = new WebPackCLI();
     cli.run(['node', 'webpack', '--watch']);
     const app = express();
-    app.get('/extension.js', async (req, res) => {
+    app.use((req, res, next) => {
         res.header('Access-Control-Allow-Origin', '*');
         res.header('Access-Control-Allow-Methods', 'GET, OPTIONS');
+        next();
+    });
+    app.get('/extension.js', async (req, res) => {
         res.send((await fs.readFile('bin/extension.js')).toString());
     });
     app.listen(9900, () => {
         console.log('Listening at http://localhost:9900/extension.js');
     });
+    (0, shapelibrary_1.debugShapeLibraries)('../..');
 }
 exports.debugEditorExtension = debugEditorExtension;

package/src/index.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const editorextension_1 = require("./editorextension");
 const package_1 = require("./package");
 const argparse_1 = require("argparse");
+const shapelibrary_1 = require("./shapelibrary");
 class LucidSuiteExtensionCLI {
     run(args) {
         const parser = new argparse_1.ArgumentParser({
@@ -35,9 +36,16 @@ class LucidSuiteExtensionCLI {
         });
         buildExtensionParser.add_argument('name');
         const testExtensionParser = subparsers.add_parser('test-editor-extension', {
-            help: 'Compile an editor extension in debug mode, and serve it at localhost:9900. Watch for changes to the code and recompile as needed',
+            help: 'Compile an editor extension in debug mode, and serve it at localhost:9900, along with any shape libraries in this package at localhost:9901. Watch for changes to the code and recompile as needed',
         });
         testExtensionParser.add_argument('name');
+        const testShapeLibraries = subparsers.add_parser('test-shape-libraries', {
+            help: 'Serve any shape libraries in this package at localhost:9901. Watch for changes to the code and live-update as needed',
+        });
+        const createShapeLibrary = subparsers.add_parser('create-shape-library', {
+            help: 'Create a new shape library as part of the current package',
+        });
+        createShapeLibrary.add_argument('name');
         const parsed = parser.parse_args(args);
         //For internal development, creating and operating on a "test" package via bazel
         const isInternalTesting = !!parsed['chdir'];
@@ -88,6 +96,22 @@ class LucidSuiteExtensionCLI {
                     console.error('Not currently in a Lucid extensibility package folder');
                 }
                 break;
+            case 'create-shape-library':
+                if ((0, package_1.currentlyInPackage)()) {
+                    (0, shapelibrary_1.createEmptyShapeLibrary)(parsed['name']);
+                }
+                else {
+                    console.error('Not currently in a Lucid extensibility package folder');
+                }
+                break;
+            case 'test-shape-libraries':
+                if ((0, package_1.currentlyInPackage)()) {
+                    (0, shapelibrary_1.debugShapeLibraries)();
+                }
+                else {
+                    console.error('Not currently in a Lucid extensibility package folder');
+                }
+                break;
             case 'test-editor-extension':
                 if ((0, package_1.currentlyInPackage)()) {
                     (0, editorextension_1.debugEditorExtension)(parsed['name']);

package/src/package.d.ts

@@ -1,16 +1,6 @@
+import { PackageManifest } from './packagemanifest';
 export declare function createEmptyPackage(root: string): Promise<void>;
 export declare function currentlyInPackage(): boolean;
-declare type PackageManifest = {
-    version: string;
-    extensions: {
-        name: string;
-        title: string;
-        codePath: string;
-        scopes: string[];
-    }[];
-};
-export declare function readManifest(): Promise<PackageManifest>;
 export declare function modifyManifest(callback: (manifest: PackageManifest) => void | Promise<void>): Promise<void>;
 export declare function updateAllExtensionSDK(): Promise<void>;
 export declare function writePackage(): Promise<void>;
-export {};

package/src/package.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.writePackage = exports.updateAllExtensionSDK = exports.modifyManifest = exports.readManifest = exports.currentlyInPackage = exports.createEmptyPackage = void 0;
+exports.writePackage = exports.updateAllExtensionSDK = exports.modifyManifest = exports.currentlyInPackage = exports.createEmptyPackage = void 0;
 const fs = require("fs/promises");
 const fsOld = require("fs");
 const filesystemutil_1 = require("./filesystemutil");
 const editorextension_1 = require("./editorextension");
 const child_process = require("child_process");
 const JSZip = require("jszip");
+const shapelibrary_1 = require("./shapelibrary");
+const packagemanifest_1 = require("./packagemanifest");
 async function createEmptyPackage(root) {
     console.log('Creating empty Lucid Suite package in ' + root);
     (0, filesystemutil_1.copyFolderRecursiveSync)(__dirname + '/../templates/package', root);
@@ -17,19 +19,15 @@ function currentlyInPackage() {
 }
 exports.currentlyInPackage = currentlyInPackage;
 const allScopes = new Set(['DOWNLOAD', 'NETWORK', 'READ', 'SHOW_MODAL', 'WRITE']);
-async function readManifest() {
-    return JSON.parse((await fs.readFile('manifest.json')).toString());
-}
-exports.readManifest = readManifest;
 async function modifyManifest(callback) {
-    const manifest = await readManifest();
+    const manifest = await (0, packagemanifest_1.readManifest)();
     await callback(manifest);
     await fs.writeFile('manifest.json', JSON.stringify(manifest, undefined, 2));
 }
 exports.modifyManifest = modifyManifest;
 async function updateAllExtensionSDK() {
-    for (const extension of (await readManifest()).extensions) {
-        const parts = extension.codePath.split('/');
+    for (const extension of (await (0, packagemanifest_1.readManifest)()).extensions) {
+        const parts = extension['codePath'].split('/');
         if (parts[0] === 'editorextensions') {
             await (0, editorextension_1.updateExtensionSDK)(parts[1]);
         }
@@ -40,19 +38,19 @@ async function writePackage() {
     const zip = new JSZip();
     //Increment the patch number automatically on each build
     await modifyManifest(async (manifest) => {
-        const parts = manifest.version.split('.');
+        const parts = manifest['version'].split('.');
         parts[parts.length - 1] = String(parseInt(parts[parts.length - 1], 10) + 1);
-        manifest.version = parts.join('.');
+        manifest['version'] = parts.join('.');
         //For each extension, compile it and add it to the archive
-        for (const extension of manifest.extensions) {
+        for (const extension of manifest['extensions']) {
             //Check that the scopes are valid
-            if (!extension.scopes.every((one) => allScopes.has(one))) {
-                console.error(`Invalid scope specified for extension ${extension.name}: ${extension.scopes
+            if (!extension['scopes'].every((one) => allScopes.has(one))) {
+                console.error(`Invalid scope specified for extension ${extension['name']}: ${extension['scopes']
                     .filter((one) => !allScopes.has(one))
                     .join(', ')}`);
                 process.exit(1);
             }
-            const parts = extension.codePath.split('/');
+            const parts = extension['codePath'].split('/');
             if (parts[0] === 'editorextensions') {
                 //Can't just call the method, as the WebpackCLI class does process.exit(2) :facepalm:
                 console.log(`Compiling editor extension ${parts[1]}`);
@@ -60,7 +58,16 @@ async function writePackage() {
                 console.log(cmd);
                 console.log(child_process.execSync(cmd).toString());
             }
-            zip.file(extension.codePath, await fs.readFile(extension.codePath));
+            zip.file(extension['codePath'], await fs.readFile(extension['codePath']));
+        }
+        //Do the same for each shape library
+        for (const library of manifest['shapeLibraries']) {
+            const parts = library['lcszPath'].split('/');
+            if (parts[0] === 'shapelibraries') {
+                console.log(`Building shape library ${parts[1]}`);
+                await (0, shapelibrary_1.buildShapeLibrary)(parts[1].replace('.lcsz', ''));
+            }
+            zip.file(library['lcszPath'], await fs.readFile(library['lcszPath']));
         }
         //Add the manifest itself
         zip.file('manifest.json', JSON.stringify(manifest, undefined, 2));

package/src/packagemanifest.d.ts

@@ -0,0 +1,15 @@
+export declare type PackageManifest = {
+    'version': string;
+    'extensions': {
+        'name': string;
+        'title': string;
+        'codePath': string;
+        'scopes': string[];
+    }[];
+    'shapeLibraries': {
+        'name': string;
+        'title': string;
+        'lcszPath': string;
+    }[];
+};
+export declare function readManifest(path?: string): Promise<PackageManifest>;

package/src/packagemanifest.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readManifest = void 0;
+const fs = require("fs/promises");
+async function readManifest(path = './') {
+    return JSON.parse((await fs.readFile(path + 'manifest.json')).toString());
+}
+exports.readManifest = readManifest;

package/src/shapelibrary.d.ts

@@ -0,0 +1,4 @@
+export declare function createEmptyShapeLibrary(name: string): Promise<void>;
+export declare function getShapeListJson(name: string, packagePath: string): Promise<string>;
+export declare function buildShapeLibrary(name: string): Promise<void>;
+export declare function debugShapeLibraries(packagePath?: string): Promise<void>;

package/src/shapelibrary.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.debugShapeLibraries = exports.buildShapeLibrary = exports.getShapeListJson = exports.createEmptyShapeLibrary = void 0;
+const fs = require("fs/promises");
+const filesystemutil_1 = require("./filesystemutil");
+const package_1 = require("./package");
+const JSZip = require("jszip");
+const path = require("path");
+const express = require("express");
+const packagemanifest_1 = require("./packagemanifest");
+const http = require("http");
+const hjson = require('hjson');
+const ws = require('ws');
+const chokidar = require('chokidar');
+async function createEmptyShapeLibrary(name) {
+    console.log('Creating shape library in shapelibraries/' + name);
+    (0, filesystemutil_1.copyFolderRecursiveSync)(__dirname + '/../templates/shapelibrary', 'shapelibraries/' + name);
+    await (0, package_1.modifyManifest)((manifest) => {
+        manifest['shapeLibraries'].push({
+            'name': name,
+            'title': name,
+            'lcszPath': `shapelibraries/${name}.lcsz`,
+        });
+    });
+}
+exports.createEmptyShapeLibrary = createEmptyShapeLibrary;
+const defaultNameMap = new Map([
+    ['rounding', 'Rounding'],
+    ['fillColor', 'FillColor'],
+    ['strokeColor', 'LineColor'],
+    ['strokeWidth', 'LineWidth'],
+    ['opacity', 'Opacity'],
+    ['rotation', 'Rotation'],
+]);
+//Produce JSON equivalent to the document service's
+// /shapeLibraries/:name/shapes endpoint
+async function getShapeListJson(name, packagePath) {
+    const rawManifest = await fs.readFile(packagePath + `/shapelibraries/${name}/library.manifest`);
+    const manifest = hjson.parse(rawManifest.toString());
+    return JSON.stringify(await Promise.all(manifest['shapes'].map(async (shapeManifest, index) => {
+        var _a;
+        const rawShapeData = await fs.readFile(packagePath + `/shapelibraries/${name}/shapes/${shapeManifest['shape']}.shape`);
+        const shapeData = hjson.parse(rawShapeData.toString());
+        const properties = {
+            'Base': { 'x': shapeManifest['defaults']['width'] / 2, 'y': shapeManifest['defaults']['height'] / 2 },
+            'BoundingBox': {
+                'x': 0,
+                'y': 0,
+                'w': shapeManifest['defaults']['width'],
+                'h': shapeManifest['defaults']['height'],
+            },
+            'DefaultSize': {
+                'w': shapeManifest['defaults']['width'],
+                'h': shapeManifest['defaults']['height'],
+            },
+            'Stencil': {
+                'lcszVersion': '1',
+                'name': shapeManifest['name'],
+                'i18n': {},
+                'sourcePackage': {
+                    'packageId': '__local__',
+                    'version': '0.0.0',
+                    'library': name,
+                    'shape': shapeManifest['shape'],
+                },
+            },
+        };
+        //Property type enum is case-insensitive during upload; replicate that here
+        if (shapeData['properties']) {
+            for (const property of shapeData['properties']) {
+                if (typeof property['type'] == 'string') {
+                    property['type'] = property['type'].toLowerCase();
+                }
+            }
+        }
+        for (var key in shapeData) {
+            properties['Stencil'][key] = shapeData[key];
+        }
+        const imageMap = properties['Stencil']['images'];
+        if (imageMap) {
+            const finalImageMap = {};
+            for (const key in imageMap) {
+                if (imageMap[key]['type'] == 'url') {
+                    finalImageMap[key] = imageMap[key]['path'];
+                }
+                else if (imageMap[key]['type'] == 'file') {
+                    finalImageMap[key] =
+                        'http://localhost:9901/shapeLibraries/' +
+                            encodeURIComponent(name) +
+                            '/images/' +
+                            encodeURIComponent(imageMap[key]['path']);
+                }
+            }
+            properties['Stencil']['images'] = finalImageMap;
+        }
+        for (var key in shapeManifest['defaults']) {
+            if (key !== 'width' && key !== 'height') {
+                const outName = (_a = defaultNameMap.get(key)) !== null && _a !== void 0 ? _a : key;
+                properties[outName] = shapeManifest['defaults'][key];
+            }
+        }
+        return {
+            'class': 'CustomBlock',
+            'created': new Date().toString(),
+            'name': shapeManifest['name'],
+            'order': index,
+            'properties': JSON.stringify(properties),
+            'shapeLibrary': 'http://localhost:9901/shapeLibraries/' + encodeURIComponent(name),
+            'uri': `http://localhost:9901/shapeLibraries/${encodeURIComponent(name)}/shapes/${encodeURIComponent(shapeManifest['shape'])}`,
+        };
+    })));
+}
+exports.getShapeListJson = getShapeListJson;
+async function buildShapeLibrary(name) {
+    const zip = new JSZip();
+    const addToZip = async (source) => {
+        console.log(source);
+        const stat = await fs.lstat(source);
+        if (stat.isDirectory()) {
+            const dir = await fs.readdir(source);
+            for (const file of dir) {
+                await addToZip(path.join(source, file));
+            }
+        }
+        else {
+            zip.file(source.replace(`shapelibraries/${name}/`, ''), await fs.readFile(source));
+        }
+    };
+    await addToZip(`shapelibraries/${name}`);
+    const zipBytes = await zip.generateAsync({ type: 'uint8array' });
+    console.log(`Writing file ${name}.lcsz`);
+    await fs.writeFile(`shapelibraries/${name}.lcsz`, zipBytes);
+}
+exports.buildShapeLibrary = buildShapeLibrary;
+async function debugShapeLibraries(packagePath = '.') {
+    const app = express();
+    app.use((req, res, next) => {
+        res.header('Access-Control-Allow-Origin', '*');
+        res.header('Access-Control-Allow-Methods', 'GET, OPTIONS');
+        next();
+    });
+    //Having a version number on the shape library URL that changes each time the user updates the code
+    //allows us to refresh the toolbox in the editor mid-editor-session. Unless the URL changes for the
+    //shape library, the toolbox doesn't update.
+    let shapeLibraryVersion = Date.now();
+    app.get('/shapeLibraries', async (req, res) => {
+        var _a;
+        const manifest = await (0, packagemanifest_1.readManifest)(packagePath + '/');
+        const libraries = (_a = manifest['shapeLibraries']) !== null && _a !== void 0 ? _a : [];
+        res.send(JSON.stringify(libraries.map((libraryManifest) => {
+            return {
+                'uri': 'http://localhost:9901/shapeLibraries/' +
+                    encodeURIComponent(libraryManifest['name']) +
+                    '?version=' +
+                    shapeLibraryVersion,
+                'user': '',
+                'created': new Date().toISOString(),
+                'name': libraryManifest['title'],
+                'size': 0,
+                'shapes': 'http://localhost:9901/shapeLibraries/' +
+                    encodeURIComponent(libraryManifest['name']) +
+                    '/shapes',
+                'shared': false,
+                'team-edit': false,
+                'encryption': '',
+            };
+        })));
+    });
+    app.get('/shapeLibraries/:libraryName/shapes', async (req, res) => {
+        //Find all the shapes in the given shape library, and produce JSON for the client
+        res.send(await getShapeListJson(req.params.libraryName, packagePath));
+    });
+    app.get('/shapeLibraries/:libraryName/images/:image', async (req, res) => {
+        const oldcwd = process.cwd();
+        process.chdir(packagePath);
+        //Find all the shapes in the given shape library, and produce JSON for the client
+        res.sendFile('shapelibraries/' + req.params.libraryName + '/images/' + req.params.image, {
+            root: process.cwd(),
+        });
+        process.chdir(oldcwd);
+    });
+    app.get('/shapeLibraries/');
+    const server = http.createServer(app);
+    //Watch for any shape library changes, and inform watchers that they need to refresh them.
+    const wss = new ws.Server({ server, path: '/shapeLibraries/changes' });
+    const sockets = [];
+    wss.on('connection', (ws) => {
+        sockets.push(ws);
+    });
+    chokidar.watch(packagePath + '/shapelibraries').on('all', () => {
+        shapeLibraryVersion = Date.now();
+        for (const socket of sockets) {
+            socket.send('refresh');
+        }
+    });
+    server.listen(9901, () => {
+        console.log('Listening at http://localhost:9901/shapeLibraries');
+    });
+}
+exports.debugShapeLibraries = debugShapeLibraries;

package/templates/package/manifest.json

@@ -1,4 +1,5 @@
 {
   "version": "1.0.0",
-  "extensions": []
+  "extensions": [],
+  "shapeLibraries":[]
 }

package/templates/shapelibrary/images/README

@@ -0,0 +1 @@
+Images used in this shape library should be placed in this directory, and file paths referenced in the image map of any shape are relative to this location.

package/templates/shapelibrary/library.manifest

@@ -0,0 +1,16 @@
+{
+    "name": "Test Library",
+    "shapes": [
+        {
+            "shape": "first",
+            "name": "Test Shape",
+            "defaults": {
+                "fillColor": "#ff0000",
+                "strokeColor": "#00ffff",
+                "strokeWidth": 3,
+                "width": 300,
+                "height": 300
+            }
+        }
+    ]
+}

package/templates/shapelibrary/shapes/first.shape

@@ -0,0 +1,8 @@
+{
+    "properties:": [],
+    "geometry": [
+        {
+            "type": "rect"
+        }
+    ]
+}