docs: more friendly plugin dev docs

Signed-off-by: Thomas Cooper <[email protected]>

Signed-off-by: Thomas Cooper <[email protected]>

website/docs/development/plugins.mdx

@@ -86,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
@@ -123,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;
@@ -158,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) {
@@ -207,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
+```