@vcmap/plugin-cli 1.1.1 → 2.0.3

package/README.md

@@ -1,5 +1,11 @@
 # @vcmap/plugin-cli
-The `vcmplugin` cli helps develop and build plugins for the **VC MAP**.
+> Part of the [VC Map Project](https://github.com/virtualcitySYSTEMS/map-ui)
+
+> **Note: This documentation is for version 2, compatible with the [VC Map](https://github.com/virtualcitySYSTEMS/map-ui) v5. 
+> For documentation on version 1 compatible with VC Map v4, see [this tag](https://github.com/virtualcitySYSTEMS/map-plugin-cli/tree/v1.1.1)
+> and be sure to install using `npm i -g @vcmap/plugin-cli@^1.1.0`** 
+
+The `vcmplugin` cli helps develop and build plugins for the **VC Map**.
 
 For more information on plugin development refer to [map plugin examples](https://github.com/virtualcitySYSTEMS/map-plugin-examples),
 which provides documentations and a tutorial on plugin development.
@@ -12,7 +18,8 @@ which provides documentations and a tutorial on plugin development.
 
 ## Prerequisite
 
-You need [nodejs](https://nodejs.org/en/) and npm installed on your system to use this tool.
+You need [nodejs](https://nodejs.org/en/) 16 and npm installed on your system 
+to use this tool.
 
 ## Installation
 To install in your project:
@@ -26,6 +33,15 @@ npm i -g @vcmap/plugin-cli
 ```
 
 ## Usage
+You can use the following workflow to quickly develop plugins. Note, that
+the `@vcmap/plugin-cli` does _not_ directly depend on `@vcmap/ui` to avoid version 
+conflicts in the used API within a plugin. This means, that _all_ commands
+(except for the `create` command) must be executed from within an installed 
+plugin cli _within the plugin itself_ using npx. When using the `create` 
+command, the `@vcmap/plugin-cli` will automatically be installed as a devDependency in 
+its current major version. You can then use either the scripts defined
+by the template in your package.json `npm start`, `npm run pack` etc. or `npx`
+to execute CLI commands.
 
 ### 1. Creating a new plugin
 
@@ -34,61 +50,182 @@ To create a new plugin template, run the following within your projects root:
 vcmplugin create
 ```
 This will open a command prompt helping you to create the basic [structure of a plugin](https://github.com/virtualcitySYSTEMS/map-plugin-examples/blob/main/doc/VCM_Plugin.md#2-structure-of-a-plugin).
-
+Be sure to check out the [peer dependecy section](#about_peer_dependencies) as well.
 
 ### 2. Serving a plugin for development
 
-To serve your project, run the following within your projects root:
+To serve your plugin in dev mode, run the following within your projects root:
 ```
-vcmplugin serve --vcm <url|directory>
+npx vcmplugin serve
 ```
-This will launch a dev server at localhost:8080 using the specified VC MAP application as its base.
-You can either specify a directory or a URL to an application.
+The dev mode gives you complete debug information on all integrated libraries (@vcmap/core, ol etc.)
+By default this command will launch a dev server at localhost:8008 using 
+the @vcmap/ui peer dependency package of your plugin as its base.
+You can provide an alternate map config if you wish.
 
-```bash
-# using a directory
-vcmplugin serve --vcm /home/vcs/virtualcityMAP
-# using a URL
-vcmplugin serve --vcm https://berlin.virtualcitymap.de
+This is the dev mode, only _your_
+plugin will be served. Any other plugins in the config will be stripped. To view how
+your plugin integrates with others, use the `preview` command.
+
+### 3. Serving a plugin for integration
+
+To serve your plugin in preview mode, run the following within your projects root:
 ```
+npx vcmplugin preview
+```
+
+The preview mode allows you to view your plugin _in its destined environment_.
+You can see how it interacts with other plugins & other customizations applied to a map.
+Preview will `build` your plugin continuously and serve the production ready
+code using a base application.
+By default, this will launch a dev server at localhost:5005 using the @vcmap/ui package 
+as its base. Alternatively you can provide a URL to a hosted VC Map application
+and use said application as its base instead.
 
-### 3. Building a plugin
+### 4. Building a plugin
 
 To build your project, run the following from within your projects root:
 ```bash
-vcmplugin build
+npx vcmplugin build
 ```
+This will build your application and place it in the `dist` directory.
 
-### 4. Integrating a plugin in a productive VC MAP
+### 5. Integrating a plugin in a productive VC MAP
 
 To pack your project for productive use, run the following from within your projects root:
 ```bash
-vcmplugin pack
+npx vcmplugin pack
 ```
 
 This will create a folder `dist` with a zip file containing your bundled code and assets.
-To use the plugin productively in a hosted map, unzip this file on your server to `{vcm-root}/plugins` and add an entry to your VC MAP [config](#2-config) plugins section.
+To use the plugin productively in a hosted map, 
+unzip this file on your server to `{vcm-root}/plugins` and add 
+an entry to your VC MAP [config](#2-config) plugins section. This zip file can also be unzipped
+in the VC Publishers `plugins` public directory.
+
+## About Peer Dependencies
+The @vcmap/ui uses some _very large libraries_, notably `CesiumJS`. To reduce the amount
+of traffic generated for loading plugins, all large libraries (see the list below), 
+are _provided_ in production (instead of bundling them into every plugin). This a) guarantees
+a certain amount of type safety (using the @vcsuite/check parameter assertation library for instance),
+b) reduces the amount of traffic required to load an application and c) leverages browser
+caching more readily.
+
+The following libraries are provided by the @vcmap/ui in a deployed application. You should define these
+as peer dependencies if you use them in your plugin:
+- @vcmap/core
+- @vcmap/cesium
+- ol
+- @vcsuite/ui-components
+- vue
+- @vue/composition-api
+- vuetify
+
+During the build step, these libraries are automatically externalized by the vcmplugin-cli and in
+production all plugins & the map core _share_ the same cesium library.
+
+But, to make this work, it is important to define these dependencies as _peer dependencies_ of
+a plugin and _that the provided index files_ are used (over directly importing from the source file).
+
+For instance: 
+```js
+import Cartesian3 from '@vcmap/cesium/Source/Core/Cartesian3.js';
+```
+
+should be rewritten to:
+```js
+import { Cartesian3 } from '@vcmap/cesium';
+```
+
+### What about openlayers?
+openlayers provides a special case, since its modules do not provide a _flat_ namespace.
+To circumvent this limitation, _the @vcmap/ui provides a flat namespaced ol.js_ and a mechanic
+to rewrite openlayers imports. This is automatically applied by the `@vcmap/rollup-plugin-vcs-ol`
+used by the vcmplugin-cli build step. So openlayers imports can be written as:
+```js
+import Feature from 'ol/Feature.js';
+```
+or 
+```js
+import { Feature } from 'ol';
+```
 
-## Non-Global CLI & npm run
-If you only use the `vcmplugin-cli` as a package dependency, you must add the above scripts to
-the `package.json` and use `npm run` to execute:
+## VC Map Plugins
+The following defines a plugin in its rough structure. If you use the `@vcmap/plugin-cli`
+to create your project, a template already adhering to these specs will be created for you.
+- All plugins must provide the following:
+    - `package.json` with name, description, version, author and dependencies.
+    - `config.json` with default parameters for the plugins' configuration.
+    - `README.md` describing the plugins' capabilities and usage.
+    - `src/index.js` JS entry point.
+- Plugin names are defined by the plugins' package name and therefore must obey npm [package name guidelines](https://docs.npmjs.com/package-name-guidelines):
+    - choose a name that
+        - is unique
+        - is descriptive
+        - is lowercase
+        - is uri encode-able
+        - doesn't start with `.`, `_` or a digit
+        - doesn't contain white spaces or any special characters like `~\'!()*"`
+    - do not use scope `@vcmap`, since it is only to be used by official plugins provided 
+      by virtual city systems. But you are encouraged to use your own scope.
+- Plugin dependencies have to be defined in the `package.json`.
+    - `dependency`: all plugin specific dependencies NOT provided by the `@vcmap/ui`.
+    - `peerDependency`: dependencies provided by the `@vcmap/ui`, 
+    - e.g. `@vcmap/core` or `@vcmap/ui` (see [About Peer Dependencies](#About_Peer_Dependencies) for more details)
+    - `devDependency`: all dependencies only required for development, e.g. `eslint`.
+- Plugins can be published to NPM, but should contain both source and minified code 
+to allow seamless integration into the [VC Map UI](https://github.com/virtualcitySYSTEMS/map-ui) environment.
+For this reason the package.json of a plugin defines two exports:
 ```json
 {
-  "name": "plugin-name",
-  "main": "src/index.js",
-  "scripts": {
-    "build": "vcmplugin build",
-    "serve": "vcmplugin serve --vcm ./vcm"
-  },
-  "devDependencies": {
-    "@vcmap/plugin-cli": "^0.1.1"
+  ".": "./src/index.js",
+  "./dist": "./dist/index.js"
+}
+```
+
+
+### Plugin Interface:
+Plugins must provide a function default export which returns an Object complying
+with the VC Map Plugin Interface describe below:
+
+```typescript
+declare interface VcsPlugin<T extends Object> {
+    readonly name: string;
+    readonly version: string;
+    initialize(app: VcsUiApp):void;
+    onVcsAppMounted(app: VcsUiApp):void;
+    toJSON():T;
+    destroy():void;
+}
+
+declare function defaultExport<T extends Object>(config: T):VcsPlugin<T>;
+```
+
+A Simple JavaScript implementation of this interface can be seen below::
+```javascript
+// index.js
+/**
+ * @param {PluginExampleConfig} config
+ * @returns {VcsPlugin}
+ */
+export default function defaultExport(config) {
+  return {
+    get name() {
+      return packageJSON.name;
+    },
+    get version() {
+      return packageJSON.version;
+    },
+    initialize(app) {},
+    onVcsAppMounted(app) {},
+    toJSON() {},
+    destroy() {},
   }
 }
 ```
 
-## Considerations
-The legacy case was not as strict regarding the projects `package.json`. This approach relies
-more heavily on a) the precense of a `package.json` and b) the validity of said package.json. For
-instance the plugin name is directly derived from the `name` field in the package.json as is the 
-entry point from `main`. You can still provide `name` as a CLI argument and `src/index.js` is still 
-used, if `main` is missing from the `package.json`. This is do to change.
+
+## Notes on Developing
+To develop the plugin-cli, be sure to not `npm link` into plugins, since this will
+throw the resolver in resolving the @vcmap/ui peer dependency from the current plugin. 
+Instead run `npm pack` in the plugin cli and install the tarball in the plugin directly.

package/assets/helloWorld/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

package/assets/helloWorld/.gitlab-ci.yml

@@ -0,0 +1,93 @@
+default:
+  image: gitlab.virtualcitysystems.de:5050/vcsuite/devops/gitlabrunner/node:16-bullseye
+
+variables:
+  GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_PROJECT_PATH_SLUG/$CI_COMMIT_REF_SLUG
+
+stages:
+  - build
+  - test
+  - bundle
+  - version
+  - publish
+
+.template: &job_definition
+  only:
+    - /^(feature-.*|hotfix-.*|main|release-.*)$/
+  tags:
+    - linux-2.0
+
+build:
+  <<: *job_definition
+  script:
+    - npm set registry 'http://npmregistry:4873'
+    - npm ci
+  before_script:
+    - mkdir -p ~/.ssh
+    - chmod 700 ~/.ssh
+    - echo "$SSH_RUNNER_KEY" | tr -d '\r' > ~/.ssh/id_rsa
+    - chmod 600 ~/.ssh/id_rsa
+    - ssh-keyscan gitlab.virtualcitysystems.de >> ~/.ssh/known_hosts
+    - chmod 644 ~/.ssh/known_hosts
+    - git config user.name "Gitlab Runner"
+    - git config user.email "gitlab-runner@vc.systems"
+  stage: build
+
+.after_build_template: &after_build_definition
+  <<: *job_definition
+  variables:
+    GIT_STRATEGY: none
+
+lint:
+  <<: *after_build_definition
+  stage: test
+  script:
+    - npm run lint
+
+audit:
+  <<: *after_build_definition
+  stage: test
+  script:
+    - npm audit --production --audit-level=low
+
+bundle:
+  <<: *after_build_definition
+  stage: bundle
+  script:
+    - npm run build
+
+version:
+  <<: *after_build_definition
+  stage: version
+  only:
+    variables:
+      - $PUBLISH
+    refs:
+      - /^(main|release-v.*)$/
+  script:
+    - npm version patch -m "%s [skip-ci]"
+    - TAG=`git describe --abbrev=0`
+    - echo git push git@gitlab:vcsuite/"$CI_PROJECT_PATH".git
+    - git push git@gitlab:vcsuite/"$CI_PROJECT_PATH".git $TAG
+    - git push git@gitlab:vcsuite/"$CI_PROJECT_PATH".git HEAD:$CI_COMMIT_REF_NAME
+  before_script:
+    - mkdir -p ~/.ssh
+    - chmod 700 ~/.ssh
+    - echo "$SSH_RUNNER_KEY" | tr -d '\r' > ~/.ssh/id_rsa
+    - chmod 600 ~/.ssh/id_rsa
+    - ssh-keyscan gitlab >> ~/.ssh/known_hosts
+    - chmod 644 ~/.ssh/known_hosts
+    - git config user.name "Gitlab Runner"
+    - git config user.email "gitlab-runner@vc.systems"
+
+publish:
+  <<: *after_build_definition
+  stage: publish
+  only:
+    refs:
+      - /^(main|release-v.*)$/
+    variables:
+      - $PUBLISH
+  script:
+    - npm config set '//npmregistry:4873/:_authToken' "${VERDACCIO_TOKEN}"
+    - npm publish --registry http://npmregistry:4873

package/assets/helloWorld/src/helloWorld.vue

@@ -0,0 +1,40 @@
+<template>
+  <v-sheet>
+    <v-card class="pa-2 ma-2">
+      <v-container>
+        <v-row class="justify-center mb-4">
+          <h1>Hello World</h1>
+        </v-row>
+        <v-row class="justify-center">
+          <VcsButton
+            icon="mdi-times"
+            @click="closeSelf"
+          >
+            Close Window
+          </VcsButton>
+        </v-row>
+      </v-container>
+    </v-card>
+  </v-sheet>
+</template>
+
+<script>
+  import { inject } from '@vue/composition-api';
+  import { VcsButton } from '@vcsuite/ui-components';
+
+  export const windowId = 'hello_world_window_id';
+
+  export default {
+    name: 'HelloWorld',
+    components: { VcsButton },
+    setup() {
+      const app = inject('vcsApp');
+
+      return {
+        closeSelf() {
+          app.windowManager.remove(windowId);
+        },
+      };
+    },
+  };
+</script>

package/assets/helloWorld/src/index.js

@@ -0,0 +1,35 @@
+import { WindowSlot } from '@vcmap/ui';
+import { version, name } from '../package.json';
+import HelloWorld, { windowId } from './helloWorld.vue';
+
+/**
+ * @param {VcsApp} app - the app from which this plugin is loaded.
+ * @param {Object} config - the configuration of this plugin instance, passed in from the app.
+ * @returns {VcsPlugin}
+ */
+export default function helloWorld(app, config) {
+  return {
+    get name() { return name; },
+    get version() { return version; },
+    initialize: async (vcsUiApp) => {
+      console.log('Called before loading the rest of the current context. Passed in the containing Vcs UI App ');
+      console.log(app, config);
+      console.log(vcsUiApp);
+    },
+    onVcsAppMounted: async (vcsUiApp) => {
+      console.log('Called when the root UI component is mounted and managers are ready to accept components');
+      vcsUiApp.windowManager.add({
+        id: windowId,
+        component: HelloWorld,
+        WindowSlot: WindowSlot.DETACHED,
+        position: {
+          left: '40%',
+          right: '40%',
+        },
+      }, name);
+    },
+    toJSON: async () => {
+      console.log('Called when serializing this plugin instance');
+    },
+  };
+}

package/assets/index.html

@@ -0,0 +1,81 @@
+<!DOCTYPE html>
+<html class="vcs-ui" lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1.0" />
+    <link
+      rel="stylesheet"
+      href="https://fonts.googleapis.com/css?family=Titillium+Web"
+    />
+  </head>
+  <body style="height: 100vH;">
+    <noscript>
+      <strong>...</strong>
+    </noscript>
+    <div id="app">
+      <div id="loading-wrapper">
+        <div id="loading-text">LOADING</div>
+        <div id="loading-content"></div>
+      </div>
+    </div>
+    <style>
+      #loading-wrapper {
+        position: fixed;
+        width: 100%;
+        height: 100%;
+        left: 0;
+        top: 0;
+      }
+
+      #loading-text {
+        display: block;
+        position: absolute;
+        top: 50%;
+        left: 50%;
+        color: #409d76;
+        width: 100px;
+        height: 30px;
+        margin: -7px 0 0 -45px;
+        text-align: center;
+        font-family: 'PT Sans Narrow', sans-serif;
+        font-size: 20px;
+      }
+
+      #loading-content {
+        display: block;
+        position: relative;
+        left: 50%;
+        top: 50%;
+        width: 170px;
+        height: 170px;
+        margin: -85px 0 0 -85px;
+      }
+
+      #loading-content {
+        border: 3px solid transparent;
+        border-top-color: #409d76;
+        border-bottom-color: #409d76;
+        border-radius: 50%;
+        -webkit-animation: loader 2s linear infinite;
+        -moz-animation: loader 2s linear infinite;
+        -o-animation: loader 2s linear infinite;
+        animation: loader 2s linear infinite;
+      }
+
+      @keyframes loader {
+        0% {
+          -webkit-transform: rotate(0deg);
+          -ms-transform: rotate(0deg);
+          transform: rotate(0deg);
+        }
+
+        100% {
+          -webkit-transform: rotate(360deg);
+          -ms-transform: rotate(360deg);
+          transform: rotate(360deg);
+        }
+      }
+    </style>
+    <script type="module" src="./node_modules/@vcmap/ui/start.js"></script>
+  </body>
+</html>

package/cli.js

@@ -1,28 +1,27 @@
 #!/usr/bin/env node
-const program = require('commander');
-require('./src/defaultCommand');
-const { version } = require('./package.json');
-const { create, serve, build, pack } = require('./index');
+import program from 'commander';
+import './src/defaultCommand.js';
+import { create, serve, build, pack, preview } from './index.js';
+import { version } from './src/create.js';
+import setupMapUi from './src/setupMapUi.js';
 
 program.version(version);
 
 program
   .command('create')
+  .defaultOptions()
   .safeAction(create);
 
 program
   .command('pack')
-  .defaultBuildOptions()
+  .defaultOptions()
   .safeAction(pack);
 
 program
-  .command('serve')
+  .command('preview')
   .defaultOptions()
-  .option('-p, --port [port]', 'the port to listen on', /\d+/, '8080')
-  .option('--vcm [dir]', 'the directory path or URL to a virtualcityMAP application', './vcm')
-  .option('--index [index.html]', 'the filename of the index.html to download. only used if vcm is a hosted application', 'index.html')
-  .option('--auth <user:password>', 'an optional auth to append to proxy requests')
-  .option('-c, --config <config>', 'a config override to not use the default plugin config')
+  .defaultServeOptions()
+  .option('--vcm [url]', 'URL to a virtualcityMAP application', val => val.replace(/\/$/, ''))
   .option('--proxyRoute <route>', 'a route to proxy as well (e.g. if you have additional proxies on your server)', (val, prev) => {
     if (!prev) {
       return [val];
@@ -30,13 +29,24 @@ program
     prev.push(val);
     return prev;
   }, [])
+  .safeAction(preview);
+
+program
+  .command('serve')
+  .defaultOptions()
+  .defaultServeOptions()
+  .option('--mapConfig [config]', 'an optional map config (either file or URL) to use')
   .safeAction(serve);
 
 program
   .command('build')
-  .defaultBuildOptions()
+  .defaultOptions()
   .option('--development', 'set mode to development')
   .option('--watch', 'watch file changes')
   .safeAction(build);
 
+program
+  .command('setup-map-ui')
+  .safeAction(setupMapUi);
+
 program.parse(process.argv);

package/index.js

@@ -1,12 +1,7 @@
-const create = require('./src/create');
-const serve = require('./src/serve');
-const build = require('./src/build');
-const pack = require('./src/pack');
+export { default as create } from './src/create.js';
+export { default as serve } from './src/serve.js';
+export { default as build } from './src/build.js';
+export { default as pack } from './src/pack.js';
+export { default as preview } from './src/preview.js';
+export { default as setupMapUi } from './src/setupMapUi.js';
 
-
-module.exports = {
-  create,
-  serve,
-  build,
-  pack,
-};