Angular 14 web plugins (#208)

* [web-app] remove deprecated/eol protractor elements

* [web-app] initial components for angular cli integration for building mage plugins

* [web-app] restructure moving cli integration under core-lib

* Revert "[web-app] restructure moving cli integration under core-lib"

This reverts commit ccc2d78.

* [web-app] package-lock update

* [web-app] add prototype builder to devkit

* [web-app] manage devkit dependencies from root workspace file

* [web-app] fix example project references in devkit builder

* [web-app] devkit back under core-lib to make dependency management easier

* [web-app] move devkit code up to core-lib top level

* [web-app] add devkit dependencies to core-lib

* [web-app] add notes on dependencies to core-lib readme

* [web-app] move core-lib builder and schematics under single parent to make typescript build easier

* [web-app] move angular cli descriptors to common root

* [web-app] fix angular-cli tsconfig

* [web-app] add build scripts for core-lib angular cli

* [web-app] change pack scripts to run from root directory

* [web-app] fix angular-cli entries in core-lib package.json

* [web-app] mod core-lib build script to copy resources

* [web-app] fix paths and typos in core-lib angular cli descriptors and generated code

* [web-app] remove references to deprecated angular apis for loading plugin modules

* [web-app] add module import for plugin hooks to core-lib schematic

* [web-app] package-lock

* [web-app] plugin-library schematic adds a peer dependency on the host mage web app, and clears other dependencies, so the dist package dependencies are correct

* [web-app] plugin builder sets main package entry to amd bundle

* readme updates for web plugins

* [web-app] fix plugin service test compile error

* add explicit docs on installing plugin packages

* [web-app] add readme on web plugin angular cli tools

* [plugins/nga-msi] npm i for new package-lock and hopefully fix ci build error

* [plugins/nga-msi] try again to fix fsevents dependency

* [service] upgrade mocha to version 8

* [plugins/nga-msi] sync tsconfig lib and target entries to es2016

* [plugins/nga-msi] install missing types deps

* [ci] use linked local mage.service to build service plugins

* [ci] wip: test linking service to plugin build

* [plugins/nga-msi] wip: test linking service to plugin build

* [ci] remove debug commands so build does not fail

* [service] upgrade mocha to 10

.github/workflows/build_test.service.yaml

@@ -43,6 +43,7 @@ jobs:
         run: |
           cd plugins/nga-msi
           npm ci
+          npm link ../../service
           npm run build
           npm test
       - name: pack nga-msi
@@ -51,6 +52,7 @@ jobs:
         run: |
           cd plugins/image/service
           npm ci
+          npm link ../../../service
           npm run build
           npm test
       - name: pack plugin image.service

README.md

@@ -76,35 +76,43 @@ At the time of this writing, MAGE supports MongoDB version 4.x.
 
 ### Install MAGE server packages
 
-Starting with release [6.2.0](https://github.com/ngageoint/mage-server/releases/tag/6.2.0), MAGE server [releases](https://github.com/ngageoint/mage-server/releases) publish NPM package tarballs.  To install and run MAGE, download the tarball artifacts from the desired
-release to an empty directory, such as `mage-server`, and install them with NPM.
+Starting with release [6.2.2](https://github.com/ngageoint/mage-server/releases/tag/6.2.2), the MAGE server packages
+are available from the [NPM registry](https://npmjs.com).
 ```bash
+mkdir mage
+cd mage
 npm install --omit dev \
-ngageoint-mage.service-*.tgz \
-ngageoint-mage.web-app-*.tgz \
-ngageoint-mage.image.service-*.tgz \
-ngageoint-mage.nga-msi-*.tgz
+@ngageoint/mage.service \
+@ngageoint/mage.web-app \
+@ngageoint/mage.image.service \
 ```
 That will yield a `package.json` file that looks something like
 ```json
 {
   "dependencies": {
-    "@ngageoint/mage.image.service": "file:ngageoint-mage.image.service-1.0.0.tgz",
-    "@ngageoint/mage.nga-msi": "file:ngageoint-mage.nga-msi-1.0.1.tgz",
-    "@ngageoint/mage.service": "file:ngageoint-mage.service-6.2.0.tgz",
-    "@ngageoint/mage.web-app": "file:ngageoint-mage.web-app-6.2.0.tgz"
+    "@ngageoint/mage.image.service": "^1.0.4",
+    "@ngageoint/mage.service": "^6.2.12",
+    "@ngageoint/mage.web-app": "^6.2.12"
   }
 }
 ```
 as well as a `package-lock.json` file and `node_modules` directory containing all of the MAGE server's dependencies.
 
+### Register plugins
+
+As the example instance [configuration](./instance/config.js) demonstrates, you'll need to tell the MAGE service what
+plugins to load.  See the `plugins` entry in the configuration object, as well as the [plugins readme](./plugins/README.md).
+Note that the `@ngageoint/mage.image.service` package in the dependency list above is a plugin package, and
+[resides](./plugins/image/service) in this monorepo.
+
 ### Run `mage.service` script
 
 The `@ngageoint/mage.service` package includes a [`mage.service` [bin script](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#bin) for starting
 the server process.  From the `instance` directory, you can run `npx @ngageoint/mage.service --help` to see the configuration
-options.
+options.  Also, the [`instance`](./instance) directory in this project has an example [configuration script](./instance/config.js)
+which the `mage.service` script would load with the `-C` flag, e.g., `mage.service -C config.js`.
 
-On Windows Server installations, running the command: `node node_modules\@ngageoint\mage.service\bin\mage.service.js` in the `instance` directory, will initialize the `mage.service` script.
+On Windows Server installations, running the command `node node_modules\@ngageoint\mage.service\bin\mage.service.js` in the `instance` directory will execute the `mage.service` script.
 
 #### Configuration merging
 
@@ -155,7 +163,7 @@ For convenience, the MAGE server project contains an [environment script](./serv
 can copy and customize.  You can configure the MAGE system user account to source the script at login.
 
 The Node MAGE server runs on port 4242 by default.  You can access the MAGE web app in your web browser at
-[http://localhost:4242](http://localhost:4242) if you are running MAGE locally.
+[http://127.0.0.1:4242](http://127.0.0.1:4242) if you are running MAGE locally.
 
 ### Running with [Docker](https://www.docker.com/what-docker)
 
@@ -187,6 +195,9 @@ where you have installed the MAGE server packages.
 ```bash
 forever start ./node_modules/.bin/mage.service <...options>
 ```
+NOTE: The `forever` readme now indicates that the project no longer has a dedicated developer and is totally reliant
+on community updates.  Try using the newer tools [pm2](https://pm2.keymetrics.io/) or [nodemon](https://nodemon.io/)
+for running `mage.service` persistently in production.
 
 #### Running as a Windows Service
 To continuously run mage.service on a windows environment, it is recommended to create a windows service using a tool such as [`node-windows`](https://github.com/coreybutler/node-windows).
@@ -247,11 +258,11 @@ in Cloud Foundry, for which Cloud Foundry should supply the connection string an
 
 ### Upgrading MAGE server
 
-Upgrading the MAGE server essentially consists of the same process as [installing for the first time](#install-mage-server-release-packages).
-1. As above, download the package tarballs for the desired version.
-2. Stop your current MAGE server if it is running.
-3. *_[BACK UP YOUR DATABASE](https://docs.mongodb.com/manual/core/backups/)!_* (You already do that regularly, right?)
-5. Start your new MAGE server, which will automatically run any database [migrations](#mage-database-setup) present in
+Upgrading the MAGE server essentially consists of the same process as [installing for the first time](#install-mage-server-packages).
+1. As above, install the desired versions of the packages.
+1. Stop your current MAGE server if it is running.
+1. *_[BACK UP YOUR DATABASE](https://docs.mongodb.com/manual/core/backups/)!_* (You already do that regularly, right?)
+1. Start your new MAGE server, which will automatically run any database [migrations](./service/src/migrations) present in
    the new version.
 
 ## Building from source

plugins/README.md

@@ -163,6 +163,16 @@ command to create a package tarball of your plugin.  This will create a file lik
 Copy the package tarball to a persistent location, like where you have [installed](../README.md#install-mage-server-packages)
 the MAGE server packages.
 
+#### Install the plugin
+
+You install plugin packages as dependencies of your[MAGE instance](../README.md#install-mage-server-packages) package,
+alongside the MAGE core packages.  Assuming you instance package resides in a directory called `mage`, copy your plugin
+package tarball to the `mage` directory.  Then, from the `mage` directory, run the following.
+```
+npm install --omit dev ./examples-mage-service-plugins-1.0.0.tgz
+```
+Your plugin package files should now be present in `mage/node_modules/@examples/mage-service-plugins`.
+
 #### Enable the plugin
 
 To enable your plugin, add the ID of the module that exports your `PluginInitHook` to the `servicePlugins` array in your [configuration object](../README.md#configuration-merging).  You can do this a few ways.
@@ -253,4 +263,45 @@ to also include an entry point to allow the MAGE service to load the `package.js
 
 ## Web UI plugins
 
-More to come soon.
+MAGE provides a library with [Angular CLI ]() integration to help create plugin packages for the MAGE web app.
+Below are the basic steps to create a MAGE web UI plugin.
+
+1. Initialize an Angular workspace.
+   ```bash
+   mkdir example
+   cd example
+   git init . # if you want version control
+   npx @angular/cli@14 new --directory . --create-application false @example/mage-plugins.workspace
+   ```
+1. Add the MAGE web core library.
+   ```bash
+   npm run ng -- add @ngageoint/mage.web-core-lib
+   ```
+1. Generate a new MAGE web UI plugin library.
+   ```bash
+   npm run ng -- generate @ngageoint/mage.web-core-lib:plugin-library @example/mage-plugins.plugin1
+   ```
+   That creates a new Angular library project in `projects/example/mage-plugins.plugin1`
+1. Add content to your plugin library.
+1. Build your plugin bundle.
+   ```bash
+   npm run ng -- build @example/mage-plugins.plugin1
+   ```
+   The output from the build will be in `dist/example/mage-plugins.plugin1`.
+1. Package your plugin.
+   ```
+   npm pack dist/example/mage-plugins.plugin1
+   ```
+   Take note that you must create the package from the project's output subdirectory of the `dist` directory, not from
+   the project root like a typical Node.js project.  This will create an NPM package tarball like
+   `example-mage-plugins.plugin1-0.0.1.tgz`, which contains the AMD module bundle that the MAGE web app can load.  You
+   can publish this tarball to NPM or install the tarball directly to your MAGE instance.
+1. Install your plugin to your MAGE instance.
+   TODO: ref above
+
+
+### Hooks
+See the available plugin [hook definitions](../web-app/projects/core-lib/plugin/plugin.model.ts).
+
+### Testing
+TODO: create a showcase app; run a dev server