Merge pull request #811 from finos/hotfix/sample-module

fix: ERR_MODULE_NOT_FOUND when sample plugins ran

Author: JamieSlome

packages/git-proxy-notify-hello/package.json

@@ -0,0 +1,14 @@
+# GitProxy plugins & samples
+GitProxy supports extensibility in the form of plugins. These plugins are specified via [configuration](https://git-proxy.finos.org/docs/category/configuration) as NPM packages or JavaScript code on disk. For each plugin configured, GitProxy will attempt to load each package or file as a standard [Node module](https://nodejs.org/api/modules.html). Plugin authors will create instances of the extension classes exposed by GitProxy and use these objects to implement custom functionality.
+
+For detailed documentation, please refer to the [GitProxy development resources on the project's site](https://git-proxy.finos.org/docs/development/plugins)
+
+## Included plugins
+These plugins are maintained by the core GitProxy team. As a future roadmap item, organizations can choose to omit
+certain features of GitProxy by simply removing the dependency from a deployed version of the application.
+
+- `git-proxy-plugin-samples`: "hello world" examples of the GitProxy plugin system
+
+## Contributing
+
+Please refer to the [CONTRIBUTING.md](https://git-proxy.finos.org/docs/development/contributing) file for information on how to contribute to the GitProxy project.

plugins/README.md

@@ -4,8 +4,8 @@
  */
 
 // Peer dependencies; its expected that these deps exist on Node module path if you've installed @finos/git-proxy
-import { PullActionPlugin } from "@finos/git-proxy/src/plugin";
-import { Step } from "@finos/git-proxy/src/proxy/actions";
+import { PullActionPlugin } from "@finos/git-proxy/src/plugin.js";
+import { Step } from "@finos/git-proxy/src/proxy/actions/index.js";
 
 class RunOnPullPlugin extends PullActionPlugin {
   constructor() {

plugins/git-proxy-plugin-samples/README.md

@@ -1,6 +1,6 @@
 {
   "name": "@finos/git-proxy-plugin-samples",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A set of sample (dummy) plugins for GitProxy to demonstrate how plugins are authored.",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"

plugins/git-proxy-plugin-samples/index.js

@@ -32,17 +32,18 @@ The below instructions are using the [`@finos/git-proxy-plugin-samples`](https:/
 1. Install both `@finos/git-proxy` and the `@finos/git-proxy-plugin-samples` package to the local `node_modules/` directory using the following command:
 
 ```bash
-$ npm install -g @finos/git-proxy@latest @finos/git-proxy-plugin-samples@0.1.0
+$ npm install -g @finos/git-proxy @finos/git-proxy-plugin-samples
 ```
 
 Alternatively, you can create local packages from source and install those instead.
 ```bash
 $ git clone https://github.com/finos/git-proxy
 $ cd git-proxy
 $ npm pack
-$ npm install -g ./finos-git-proxy-1.3.5.tgz
 $ (cd plugins/git-proxy-plugin-samples && npm pack)
-$ npm install -g plugins/git-proxy-plugin-samples/finos-git-proxy-plugin-samples-0.1.0.tgz
+$ npm install -g \
+  ./finos-git-proxy-1.7.0.tgz \
+  ./plugins/git-proxy-plugin-samples/finos-git-proxy-plugin-samples-0.1.1.tgz
 ```
 
 2. Create or edit an existing `proxy.config.json` file to configure the plugin(s) to load. You must include the full import path that would typically be used in a `import {}` (ESM) or `require()` (CJS) statement:
@@ -85,7 +86,7 @@ $ cat package.json
   "name": "foo-plugin",
   ...
   "dependencies": {
-    "@finos/git-proxy": "^1.3.5"
+    "@finos/git-proxy": "^1.7.0"
   }
 }
 # Alternatively, add git-proxy that is cloned locally as a file-based dependency
@@ -122,29 +123,42 @@ Loaded plugin: FooPlugin
 
 ## Developing new plugins
 
-To develop a new plugin, you must add `@finos/git-proxy` as a [peer dependency](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#peerdependencies). The main app (also known as the "host application") exports the following extension points:
+To develop a new plugin, you must add `@finos/git-proxy` as a [peer dependency](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#peerdependencies). The plugin & proxy classes can then be imported from `@finos/git-proxy` via the following extension points:
 
-- `@finos/git-proxy/src/plugin/PushActionPlugin`: execute as an action in the proxy chain during a `git push`
-- `@finos/git-proxy/src/plugin/PullActionPlugin`: execute as an action in the proxy chain during a `git fetch`
-- `@finos/git-proxy/src/proxy/actions/Step` and `@finos/git-proxy/src/proxy/actions/Action`: internal classes which act as carriers for `git` state during proxying. Plugins should modify the passed in `action` for affecting any global state of the git operation and add its own custom `Step` object to capture the plugin's own internal state (logs, errored/blocked status, etc.)
+```js
+import { PushActionPlugin } from '@finos/git-proxy/src/plugin.js'
+```
+- Use this class to execute as an action in the proxy chain during a `git push`
+
+
+```js
+import { PullActionPlugin } from '@finos/git-proxy/src/plugin.js'
+```
+- Use this class to execute as an action in the proxy chain during a `git fetch`
+
+
+```js
+import { Step, Action } from '@finos/git-proxy/src/proxy/actions/index.js'
+```
+- These are internal classes which act as carriers for `git` state during proxying. Plugins should modify the passed in `Action` for affecting any global state of the git operation and add its own custom `Step` object to capture the plugin's own internal state (logs, errored/blocked status, etc).
 
-GitProxy will load your plugin only if it extends one of the two plugin classes above. It is also important that your package has [`exports`](https://nodejs.org/api/packages.html#exports) defined for the plugin loader to properly load your module(s).
+GitProxy will load your plugin only if it extends one of the two plugin classes above.
 
 Please see the [sample plugin package included in the repo](https://github.com/finos/git-proxy/tree/main/plugins/git-proxy-plugin-samples) for details on how to structure your plugin package.
 
 If your plugin relies on custom state, it is recommended to create subclasses in the following manner:
 
 ```javascript
-import { PushActionPlugin } from "@finos/git-proxy/src/plugin";
+import { PushActionPlugin } from "@finos/git-proxy/src/plugin.js";
 
 class FooPlugin extends PushActionPlugin {
   constructor() {
     super(); // don't pass any function to the parent class - let the parent's this.exec function be undefined
-    this.displayName = 'FooPlugin';
+    this.someProperty = 'Hello from the FooPlugin';
     // overwrite the parent's exec function which is executed as part of GitProxy's action chain.
     // use an arrow function if you require access to the instances's state (properties, methods, etc.)
     this.exec = async (req, action) => {
-      console.log(this.displayName);
+      console.log(this.someProperty);
       this.utilMethod();
       // do something
       return action;
@@ -157,40 +171,20 @@ class FooPlugin extends PushActionPlugin {
 }
 ```
 
-### Example
+### Instructions for creating a new plugin package
 
+1. Create a new directory for your plugin package and initialize a new npm package:
 ```bash
 $ npm init
 # ...
-$ npm install --save-peer @finos/git-proxy@latest
+$ npm install --save-peer @finos/git-proxy
 ```
 
-`package.json`
-
-```json
-{
-  "name": "bar",
-  "version": "1.0.0",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "author": "",
-  "license": "ISC",
-  "description": "",
-  "exports": {
-    ".": "./bar.js"
-  },
-  "peerDependencies": {
-    "@finos/git-proxy": "^1.3.5"
-  }
-}
-```
+2. Create a new JavaScript file for your plugin. The file should export an instance of `PushActionPlugin` or `PullActionPlugin`:
 
-`bar.js`
 ```javascript
-import { PushActionPlugin } from "@finos/git-proxy/src/plugin";
-import { Step } from "@finos/git-proxy/src/proxy/actions";
+import { PushActionPlugin } from "@finos/git-proxy/src/plugin.js";
+import { Step } from "@finos/git-proxy/src/proxy/actions/index.js";
 
 //Note: Only use a default export if you do not rely on any state. Otherwise, create a sub-class of [Push/Pull]ActionPlugin
 export default new PushActionPlugin(function(req, action) {
@@ -206,3 +200,21 @@ export default new PushActionPlugin(function(req, action) {
   return action; // always return the action - even in the case of errors
 });
 ```
+
+3. In your GitProxy installation, install your plugin package & update the `proxy.config.json` file to include the path to your plugin module(s):
+
+```bash
+$ npm install @finos/git-proxy /path/to/your/plugin/package
+$ cat proxy.config.json
+{
+  "plugins": [
+    "/path/to/your/plugin/package/index.js"
+  ]
+}
+$ git-proxy
+Service Listening on 8080
+HTTP Proxy Listening on 8000
+HTTPS Proxy Listening on 8443
+Found 1 plugin modules
+Loaded plugin: PushActionPlugin
+```