@vcmap/plugin-cli 2.1.5 → 2.1.7

package/README.md

@@ -1,9 +1,10 @@
 # @vcmap/plugin-cli
+
 > 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. 
+> **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`** 
+> and be sure to install using `npm i -g @vcmap/plugin-cli@^1.1.0`**
 
 The `@vcmap/plugin-cli` helps develop and build plugins for the **VC Map**.
 
@@ -17,41 +18,47 @@ The `@vcmap/plugin-cli` helps develop and build plugins for the **VC Map**.
 
 ## Prerequisite
 
-You need [nodejs](https://nodejs.org/en/) 16 and npm installed on your system 
+You need [nodejs](https://nodejs.org/en/) 16 and npm installed on your system
 to use this tool.
 
 ## Installation
+
 To install in your project:
+
 ```shell
 npm i -D @vcmap/plugin-cli
 ```
 
 To install globally:
+
 ```shell
 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 
+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 
+(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.
 
 All commands have (optional) cli options. Run `vcmplugin --help` or `vcmplugin help [command]` for more information.
-For `serve` and `preview` you can alternatively define a `vcs.config.js` in your plugin's root directory. 
+For `serve` and `preview` you can alternatively define a `vcs.config.js` in your plugin's root directory.
 For more information see [here](#vcm-config-js).
 
 ### 1. Creating a new plugin
 
 To create a new plugin template, run the following:
+
 ```
 vcmplugin create
 ```
+
 This will open a command prompt helping you to create the basic [structure of a plugin](#vc-map-plugins).
 Be sure to check out the [peer dependecy section](#about-peer-dependencies) as well.
 
@@ -60,13 +67,15 @@ Optionally, in step 7 of the create-prompt you can choose an existing plugin [@v
 ### 2. Serving a plugin for development
 
 To serve your plugin in dev mode, run the following within your projects root:
+
 ```
 npx vcmplugin serve
 ```
+
 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 
+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.
+You can provide an alternate app config if you wish.
 
 This is the dev mode, only _your_
 plugin will be served. Any other plugins in the config will be stripped. To view how
@@ -75,6 +84,7 @@ 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
 ```
@@ -83,28 +93,32 @@ 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 
+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.
 
-### 4. Building a plugin staging application 
+### 4. Building a plugin staging application
 
 A staging application creates a full deployable VC Map in the `dist` folder with the following components.
+
 - compiled @vcmap/ui library and all dependencies
 - default @vcmap/ui configurations
 - default @vcmap/ui plugins
-- compiled plugin which is in development. 
+- compiled plugin which is in development.
 
 Building the staging application will collect all parts and will inject the plugin in development in the default
-map configuration. The staging application can for example be used to deploy the App in an Apache in a postCommit 
+app configuration. The staging application can for example be used to deploy the App in an Apache in a postCommit
 Pipeline. (See .gitlab-ci.yml for an example).
+
 ```bash
 npx vcmplugin buildStagingApp
 ```
+
 To start a webserver to serve the content of the `dist` folder call `npx vite preview`; This will start a static webserver
 on the port 4173.
 
 The Dockerfile in `build/staging/Dockerfile` can be used to create a Docker Container which serves the content of the dist folder.
+
 ```bash
 npx vcmplugin buildStagingApp
 cd dist
@@ -115,21 +129,24 @@ docker run --rm -p 5000:80 vcmap:staging
 ### 5. Building a plugin
 
 To build your project, run the following from within your projects root:
+
 ```bash
 npx vcmplugin build
 ```
+
 This will build your application and place it in the `dist` directory.
 
 ### 6. Integrating a plugin in a productive VC MAP
 
 To pack your project for productive use, run the following from within your projects root:
+
 ```bash
 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 
+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` plugins section. This zip file can also be unzipped
 in the VC Publishers `plugins` public directory.
 
@@ -142,6 +159,7 @@ In order to do so just save a `vcm.config.js` in your plugin's root directory.
 This file has to return a js object as default export.
 
 Example `vcm.config.js` defining proxy and port:
+
 ```js
 export default {
   // server.proxy see https://vitejs.dev/config/server-options.html#server-proxy
@@ -150,26 +168,26 @@ export default {
     '/foo': 'https://vc.systems',
   },
   port: 5005,
-}
+};
 ```
 
 The following parameters are valid:
 
 | parameter | type               | description                                                                                   |
-|-----------|--------------------|-----------------------------------------------------------------------------------------------|
+| --------- | ------------------ | --------------------------------------------------------------------------------------------- |
 | config    | string|Object | an optional configObject or fileName to use for configuring the plugin                        |
 | auth      | string             | potential auth string to download assets (index.html, config) with                            |
 | port      | number             | optional alternative port (default 8008)                                                      |
 | https     | boolean            | whether to use http (default) or https                                                        |
-| mapConfig | string|Object | an optional configObject resp. fileName or URL to a map config (for `serve` command)          |
+| appConfig | string|Object | an optional configObject resp. fileName or URL to an app config (for `serve` command)         |
 | vcm       | string             | a filename or URL to a map (for `preview` command)                                            |
 | proxy     | Object             | a server proxy (see [vitejs.dev](https://vitejs.dev/config/server-options.html#server-proxy)) |
 
-
 ## About Peer Dependencies
+
 The [@vcmap/ui](https://github.com/virtualcitySYSTEMS/map-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 
+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](https://www.npmjs.com/package/@vcsuite/check) parameter assertion library for instance),
 b) reduces the amount of traffic required to load an application and
 c) leverages browser
@@ -177,6 +195,7 @@ 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/engine
 - ol
@@ -185,9 +204,11 @@ as peer dependencies if you use them in your plugin:
 
 If you want to update your plugin to a newer version of `@vcmap/ui`, the `@vcmap/plugin-cli` provides a update tool.
 Just change to your plugin's directory and run:
+
 ```bash
 vcmplugin update
 ```
+
 This will automatically update all peer dependencies defined in your plugin to the corresponding version of the latest `@vcmap/ui`.
 
 During the build step, these libraries are automatically externalized by the `@vcmap/plugin-cli` and in
@@ -196,56 +217,65 @@ 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: 
+For instance:
+
 ```js
 import Cartesian3 from '@vcmap-cesium/engine/Source/Core/Cartesian3.js';
 ```
 
 should be rewritten to:
+
 ```js
 import { Cartesian3 } from '@vcmap-cesium/engine';
 ```
 
 ### 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 `@vcmap/plugin-cli` build step. So openlayers imports can be written as:
+
 ```js
 import Feature from 'ol/Feature.js';
 ```
-or 
+
+or
+
 ```js
 import { Feature } from 'ol';
 ```
 
 ## 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.
+  - `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.
 - A plugin _may_ provide static plugin assets in a `plugin-assets` directory. (See [About Plugin Assets](#About-Plugin-Assets)
 - 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.
+  - 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:
+  - `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
 {
   ".": "./src/index.js",
@@ -254,6 +284,7 @@ For this reason the package.json of a plugin defines two exports:
 ```
 
 ### Plugin Interface:
+
 Plugins must provide a function default export which returns an Object complying
 with the VC Map Plugin Interface describe below. This function is passed the current
 configuration of the plugin as its first argument and the base URL (without the filename)
@@ -261,19 +292,23 @@ from which the plugin was loaded as its second argument.
 
 ```typescript
 declare interface VcsPlugin<T extends Object, S extends Object> {
-    readonly name: string;
-    readonly version: string;
-    initialize(app: VcsUiApp, state?: S):Promise<void>;
-    onVcsAppMounted(app: VcsUiApp):Promise<void>;
-    getState():Promise<S>;
-    toJSON():Promise<T>;
-    destroy():void;
+  readonly name: string;
+  readonly version: string;
+  initialize(app: VcsUiApp, state?: S): Promise<void>;
+  onVcsAppMounted(app: VcsUiApp): Promise<void>;
+  getState(): Promise<S>;
+  toJSON(): Promise<T>;
+  destroy(): void;
 }
 
-declare function defaultExport<T extends Object, S extends Object>(config: T, baseUrl: string):VcsPlugin<T, S>;
+declare function defaultExport<T extends Object, S extends Object>(
+  config: T,
+  baseUrl: string,
+): VcsPlugin<T, S>;
 ```
 
 A Simple JavaScript implementation of this interface can be seen below::
+
 ```javascript
 // index.js
 /**
@@ -287,26 +322,32 @@ export default function defaultExport(config, baseUrl) {
     },
     get version() {
       return packageJSON.version;
-    }, 
-    async initialize (app, state) {
+    },
+    async initialize(app, state) {
       console.log('I was loaded from ', baseUrl);
     },
-    async onVcsAppMounted(app) {}, 
-    async getState() { return {}; },
-    async toJSON() { return {}; },
+    async onVcsAppMounted(app) {},
+    async getState() {
+      return {};
+    },
+    async toJSON() {
+      return {};
+    },
     destroy() {},
-  }
+  };
 }
 ```
 
 ### About Plugin Assets
+
 Plugin assets are considered to be static files, such as images, fonts etc. which shall be
-access from within the plugin. Since plugins have no knowledge of _where_ they will 
+access from within the plugin. Since plugins have no knowledge of _where_ they will
 be deployed, the `@vcmap/ui` provides the `getPluginAssetUrl` helper function
 which allows you to generate an asset URL at runtime.
 
 Place all your assets into the `plugin-assets` directory in your plugin (top level). Your
 plugin structure should look something like this:
+
 ```
 -| my-plugin/
 ---| src/
@@ -317,13 +358,10 @@ plugin structure should look something like this:
 ```
 
 To access the `icon.png` from within your code, you would do the following:
+
 ```vue
 <template>
-  <v-img
-    :src="icon"
-    alt="plugin-icon"
-    max-width="200"
-  />
+  <v-img :src="icon" alt="plugin-icon" max-width="200" />
 </template>
 
 <script>
@@ -346,9 +384,10 @@ To access the `icon.png` from within your code, you would do the following:
   };
 </script>
 ```
+
 You can of course, use `fetch` to retrieve assets in the same fashion. Should you
 wish to use assets (such as images) in your _css_ make sure that they are embedded or
-you will have to use an inline style & a bound vue property, since the helper 
+you will have to use an inline style & a bound vue property, since the helper
 cannot handle css resources.
 
 If you have to access assets _before_ your plugin is created (in the exported function of
@@ -357,12 +396,13 @@ your plugin code), you will have to use the `baseUrl` provided to you to generat
 ## About testing plugins
 
 To test your plugin's API you can use [vitest](https://vitest.dev/).
-The `@vcmap/hello-world` plugin contains a basic setup of a test environment including example spec using vitest. 
+The `@vcmap/hello-world` plugin contains a basic setup of a test environment including example spec using vitest.
 You will find the required setup in your created plugin, if you chose to add `test` as script to your `package.json` during the create-prompt.
 
 As for now, we don't do any components testing.
 
 ## 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. 
+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/.gitlab-ci.yml

@@ -93,7 +93,7 @@ deployStaging:
     on_stop: stopEnvironment
   image:
     name: gcr.io/kaniko-project/executor:debug
-    entrypoint: [ "" ]
+    entrypoint: ['']
   script:
     - /kaniko/executor --context dist/ --dockerfile build/staging/Dockerfile --destination $CI_REGISTRY_IMAGE/staging:$CI_COMMIT_REF_SLUG
   before_script:
@@ -106,7 +106,7 @@ stopEnvironment:
     GIT_STRATEGY: none
   image:
     name: bitnami/kubectl:latest
-    entrypoint: [""]
+    entrypoint: ['']
   tags:
     - linux-2.0
   script:

package/assets/index.html

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

package/assets/index.js

@@ -15,8 +15,12 @@ export default function plugin(config, baseUrl) {
   // eslint-disable-next-line no-console
   console.log(config, baseUrl);
   return {
-    get name() { return name; },
-    get version() { return version; },
+    get name() {
+      return name;
+    },
+    get version() {
+      return version;
+    },
     /**
      * @param {import("@vcmap/ui").VcsUiApp} vcsUiApp
      * @param {PluginState=} state
@@ -24,7 +28,11 @@ export default function plugin(config, baseUrl) {
      */
     initialize: async (vcsUiApp, state) => {
       // eslint-disable-next-line no-console
-      console.log('Called before loading the rest of the current context. Passed in the containing Vcs UI App ', vcsUiApp, state);
+      console.log(
+        'Called before loading the rest of the current context. Passed in the containing Vcs UI App ',
+        vcsUiApp,
+        state,
+      );
     },
     /**
      * @param {import("@vcmap/ui").VcsUiApp} vcsUiApp
@@ -32,7 +40,10 @@ export default function plugin(config, baseUrl) {
      */
     onVcsAppMounted: async (vcsUiApp) => {
       // eslint-disable-next-line no-console
-      console.log('Called when the root UI component is mounted and managers are ready to accept components', vcsUiApp);
+      console.log(
+        'Called when the root UI component is mounted and managers are ready to accept components',
+        vcsUiApp,
+      );
     },
     /**
      * @returns {T}

package/cli.js

@@ -1,37 +1,34 @@
 #!/usr/bin/env node
 import program from 'commander';
 import './src/defaultCommand.js';
-import {
-  create, serve, build, pack, preview, update,
-} from './index.js';
+import { create, serve, build, pack, preview, update } from './index.js';
 import { version } from './src/pluginCliHelper.js';
 import setupMapUi from './src/setupMapUi.js';
 import buildStagingApp from './src/buildStagingApp.js';
 
 program.version(version);
 
-program
-  .command('create')
-  .defaultOptions()
-  .safeAction(create);
+program.command('create').defaultOptions().safeAction(create);
 
-program
-  .command('pack')
-  .defaultOptions()
-  .safeAction(pack);
+program.command('pack').defaultOptions().safeAction(pack);
 
 program
   .command('preview')
   .defaultOptions()
   .defaultServeOptions()
-  .option('--vcm [url]', 'URL to a virtualcityMAP application', val => val.replace(/\/$/, ''))
+  .option('--vcm [url]', 'URL to a virtualcityMAP application', (val) =>
+    val.replace(/\/$/, ''),
+  )
   .safeAction(preview);
 
 program
   .command('serve')
   .defaultOptions()
   .defaultServeOptions()
-  .option('--mapConfig [config]', 'an optional map config (either file or URL) to use')
+  .option(
+    '--appConfig [config]',
+    'an optional app config (either file or URL) to use',
+  )
   .safeAction(serve);
 
 program
@@ -41,18 +38,10 @@ program
   .option('--watch', 'watch file changes')
   .safeAction(build);
 
-program
-  .command('buildStagingApp')
-  .defaultOptions()
-  .safeAction(buildStagingApp);
+program.command('buildStagingApp').defaultOptions().safeAction(buildStagingApp);
 
-program
-  .command('setup-map-ui')
-  .safeAction(setupMapUi);
+program.command('setup-map-ui').safeAction(setupMapUi);
 
-program
-  .command('update')
-  .defaultOptions()
-  .safeAction(update);
+program.command('update').defaultOptions().safeAction(update);
 
 program.parse(process.argv);

package/index.js

@@ -6,4 +6,3 @@ export { default as preview } from './src/preview.js';
 export { default as buildStagingApp } from './src/buildStagingApp.js';
 export { default as update } from './src/update.js';
 export { default as setupMapUi } from './src/setupMapUi.js';
-