Add before & after hooks + start of Pepr docs (#65)

Fixes #17

README.md

@@ -10,7 +10,31 @@ Pepr is on a mission to save Kubernetes from the tyranny of YAML, intimidating g
 - Write capabilities in TypeScript and bundle them for in-cluster processing in [NodeJS](https://nodejs.org/).
 - React to cluster resources by mutating them, creating new Kubernetes resources, or performing arbitrary exec/API operations.
 
+## Example Pepr CapabilityAction
+
+This quick sample shows how to react to a ConfigMap being created or updated in the cluster. It adds a label and annotation to the ConfigMap and adds some data to the ConfigMap. Finally, it logs a message to the Pepr controller logs. For more see [CapabilityActions](./docs/actions.md).
+
+```ts
+When(a.ConfigMap)
+  .IsCreatedOrUpdated()
+  .InNamespace("pepr-demo")
+  .WithLabel("unicorn", "rainbow")
+  .Then(request => {
+    // Add a label and annotation to the ConfigMap
+    request
+      .SetLabel("pepr", "was-here")
+      .SetAnnotation("pepr.dev", "annotations-work-too");
+
+    // Add some data to the ConfigMap
+    request.Raw.data["doug-says"] = "Pepr is awesome!";
+
+    // Log a message to the Pepr controller logs
+    Log.info("A 🦄 ConfigMap was created or updated:");
+  });
+```
+
 ## Wow too many words! tl;dr;
+
 ```bash
 # Install Pepr (you can also use npx)
 npm i -g pepr
@@ -25,7 +49,7 @@ npm run k3d-setup
 
 # Start playing with Pepr now
 pepr dev
-kubectl apply -f capabilities/hello-pepr.samples.yaml 
+kubectl apply -f capabilities/hello-pepr.samples.yaml
 
 # Be amazed and ⭐️ this repo
 ```
@@ -46,91 +70,21 @@ https://user-images.githubusercontent.com/882485/230895880-c5623077-f811-4870-bb
 
 A module is the top-level collection of capabilities. It is a single, complete TypeScript project that includes an entry point to load all the configuration and capabilities, along with their CapabilityActions. During the Pepr build process, each module produces a unique Kubernetes MutatingWebhookConfiguration and ValidatingWebhookConfiguration, along with a secret containing the transpiled and compressed TypeScript code. The webhooks and secret are deployed into the Kubernetes cluster for processing by a common Pepr controller.
 
+See [Module](./docs/module.md) for more details.
+
 ### Capability
 
-A capability is set of related CapabilityActions that work together to achieve a specific transformation or operation on Kubernetes resources. Capabilities are user-defined and can include one or more CapabilityActions. They are defined within a Pepr module and can be used in both MutatingWebhookConfigurations and ValidatingWebhookConfigurations. A Capability can have a specific scope, such as mutating or validating, and can be reused in multiple Pepr modules. 
+A capability is set of related CapabilityActions that work together to achieve a specific transformation or operation on Kubernetes resources. Capabilities are user-defined and can include one or more CapabilityActions. They are defined within a Pepr module and can be used in both MutatingWebhookConfigurations and ValidatingWebhookConfigurations. A Capability can have a specific scope, such as mutating or validating, and can be reused in multiple Pepr modules.
+
+See [Capabilities](./docs/capabilities.md) for more details.
 
 ### CapabilityAction
 
 CapabilityAction is a discrete set of behaviors defined in a single function that acts on a given Kubernetes GroupVersionKind (GVK) passed in from Kubernetes. CapabilityActions are the atomic operations that are performed on Kubernetes resources by Pepr.
 
 For example, a CapabilityAction could be responsible for adding a specific label to a Kubernetes resource, or for modifying a specific field in a resource's metadata. CapabilityActions can be grouped together within a Capability to provide a more comprehensive set of operations that can be performed on Kubernetes resources.
 
-## Example
-
-Define a new capability can be done via [VSCode Snippet](https://code.visualstudio.com/docs/editor/userdefinedsnippets): create a file `capabilities/your-capability-name.ts` and then type `create` in the file, a suggestion should prompt you to generate the content from there.
-
-https://user-images.githubusercontent.com/882485/230897379-0bb57dff-9832-479f-8733-79e103703135.mp4
-
-Alternatively, you can use the `pepr new <capability-name>` command to this:
-
-```
-pepr new hello-world
-```
-
-This will create a new file called `capabilities/hello-world.ts` with the following contents:
-
-```typescript
-import { Capability, a } from "pepr";
-
-export const HelloWorld = new Capability({
-  // The unique name of the capability
-  name: "hello-world",
-  // A short description of the capability
-  description: "Type a useful description here 🦄",
-  // Limit what namespaces the capability can be used in (optional)
-  namespaces: [],
-});
-
-// Use the 'When' function to create a new Capability Action
-const { When } = HelloWorld;
-```
-
-Next, we need to define some actions to perform when specific Kubernetes resources are created, updated or deleted in the cluster. Pepr provides a set of actions that can be used to react to Kubernetes resources, such as `a.Pod`, `a.Deployment`, `a.CronJob`, etc. These actions can be chained together to create complex conditions, such as `a.Pod.IsCreated().InNamespace("default")` or `a.Deployment.IsUpdated().WithLabel("changeme=true")`. Below is an example of a capability that reacts to the creation of a Deployment resource:
-
-```typescript
-When(a.Deployment)
-  .IsCreated()
-  .ThenSet({
-    spec: {
-      minReadySeconds: 3,
-    },
-  });
-```
-
-Here's a more complex example that reacts to the creation of a Deployment resource:
-
-```typescript
-When(a.Deployment)
-  .IsCreatedOrUpdated()
-  .InNamespace("ns1", "ns2")
-  .WithLabel("changeme", "true")
-  .Then(request => {
-    request
-      .SetLabel("mutated", "true")
-      .SetLabel("test", "thing")
-      .SetAnnotation("test2", "thing")
-      .RemoveLabel("test3");
-
-    if (request.HasLabel("test")) {
-      request.SetLabel("test5", "thing");
-    }
-
-    const { spec } = request.Raw;
-    spec.strategy.type = "Recreate";
-    spec.minReadySeconds = 3;
-
-    if (request.PermitSideEffects) {
-      // Do side-effect inducing things
-    }
-  });
-```
-
-Now you can build and bundle your capability:
-
-```
-pepr build hello-world
-```
+See [CapabilityActions](./docs/actions.md) for more details.
 
 ## Logical Pepr Flow
 

docs/.prettierrc.json

@@ -0,0 +1,13 @@
+{
+  "arrowParens": "avoid",
+  "bracketSameLine": false,
+  "bracketSpacing": true,
+  "embeddedLanguageFormatting": "auto",
+  "insertPragma": false,
+  "printWidth": 80,
+  "quoteProps": "as-needed",
+  "requirePragma": false,
+  "semi": true,
+  "tabWidth": 2,
+  "useTabs": false
+}

docs/actions.md

@@ -0,0 +1,58 @@
+# CapabilityActions
+
+A CapabilityAction is a discrete set of behaviors defined in a single function that acts on a given Kubernetes GroupVersionKind (GVK) passed in from Kubernetes. CapabilityActions are the atomic operations that are performed on Kubernetes resources by Pepr.
+
+For example, a CapabilityAction could be responsible for adding a specific label to a Kubernetes resource, or for modifying a specific field in a resource's metadata. CapabilityActions can be grouped together within a Capability to provide a more comprehensive set of operations that can be performed on Kubernetes resources.
+
+Let's look at some example CapabilityActions that are included in the `HelloPepr` capability that is created for you when you [`pepr init`](./cli.md#pepr-init):
+
+---
+
+In this first example, Pepr is adding a label and annotation to a ConfigMap with tne name `example-1` when it is created. Comments are added to each line to explain in more detail what is happening.
+
+```ts
+// When(a.<Kind>) tells Pepr what K8s GroupVersionKind (GVK) this CapabilityAction should act on.
+When(a.ConfigMap)
+  // Next we tell Pepr to only act on new ConfigMaps that are created.
+  .IsCreated()
+  // Then we tell Pepr to only act on ConfigMaps with the name "example-1".
+  .WithName("example-1")
+  // Then() is where we define the actual behavior of this CapabilityAction.
+  .Then(request => {
+    // The request object is a wrapper around the K8s resource that Pepr is acting on.
+    request
+      // Here we are adding a label to the ConfigMap.
+      .SetLabel("pepr", "was-here")
+      // And here we are adding an annotation.
+      .SetAnnotation("pepr.dev", "annotations-work-too");
+
+    // Note that we are not returning anything here. This is because Pepr is tracking the changes in each CapabilityAction automatically.
+  });
+```
+
+---
+
+This example is identical to the previous one, except we are acting on a different CongigMap name and using the `ThenSet()` shorthand to merge changes into the resource.
+
+```ts
+// Once again, we tell Pepr what K8s GVK this CapabilityAction should act on.
+When(a.ConfigMap)
+  // Next we tell Pepr to only act on new ConfigMaps that are created.
+  .IsCreated()
+  // This time we are acting on a ConfigMap with the name "example-2".
+  .WithName("example-2")
+  // Instead of using Then(), we are using ThenSet() to merge changes into the resource without a function call.
+  .ThenSet({
+    // Using Typescript, we will get intellisense for the ConfigMap object and immediate type-validation for the values we are setting.
+    metadata: {
+      labels: {
+        pepr: "was-here",
+      },
+      annotations: {
+        "pepr.dev": "annotations-work-too",
+      },
+    },
+  });
+```
+
+There are many more examples in the `HelloPepr` capability that you can use as a reference when creating your own CapabilityActions. Note that each time you run [`pepr update`](./cli.md#pepr-update), Pepr will automatically update the `HelloPepr` capability with the latest examples and best practices for you to reference and test directly in your Pepr Module.

docs/capabilities.md

@@ -0,0 +1,17 @@
+# Capabilities
+
+A capability is set of related [CapabilityActions](./actions.md) that work together to achieve a specific transformation or operation on Kubernetes resources. Capabilities are user-defined and can include one or more CapabilityActions. They are defined within a Pepr module and can be used in both MutatingWebhookConfigurations and ValidatingWebhookConfigurations. A Capability can have a specific scope, such as mutating or validating, and can be reused in multiple Pepr modules.
+
+When you [`pepr init`](./cli.md#pepr-init), a `capabilities` directory is created for you. This directory is where you will define your capabilities. You can create as many capabilities as you need, and each capability can contain one or more CapabilityActions. Pepr also automatically creates a `HelloPepr` capability with a number of example CapabilityActions to help you get started.
+
+## Creating a Capability
+
+Define a new capability can be done via a [VSCode Snippet](https://code.visualstudio.com/docs/editor/userdefinedsnippets) generated during [`pepr init`](./cli.md#pepr-init).
+
+1. Create a new file in the `capabilities` directory with the name of your capability. For example, `capabilities/my-capability.ts`.
+
+1. Open the new file in VSCode and type `create` in the file. A suggestion should prompt you to generate the content from there.
+
+https://user-images.githubusercontent.com/882485/230897379-0bb57dff-9832-479f-8733-79e103703135.mp4
+
+_If you prefer not to use VSCode, you can also modify or copy the `HelloPepr` capability to meet your needs instead._

docs/cli.md

@@ -0,0 +1,54 @@
+# Pepr CLI
+
+## `pepr init`
+
+Initialize a new Pepr Module.
+
+**Options:**
+
+- `-l, --log-level [level]` - Log level: debug, info, warn, error (default: "info")
+- `--skip-post-init` - Skip npm install, git init and VSCode launch
+
+---
+## `pepr update`
+
+Update the current Pepr Module to the latest SDK version and update the global Pepr CLI to the same version.
+
+**Options:**
+
+- `-l, --log-level [level]` - Log level: debug, info, warn, error (default: "info")
+- `--skip-template-update` - Skip updating the template files
+
+---
+
+## `pepr dev`
+
+Connect a local cluster to a local version of the Pepr Controller to do real-time debugging of your module.
+
+**Options:**
+
+- `-l, --log-level [level]` - Log level: debug, info, warn, error (default: "info")
+- `-h, --host [host]` - Host to listen on (default: "host.docker.internal")
+- `--confirm` - Skip confirmation prompt
+
+---
+
+## `pepr deploy`
+
+Deploy the current module into a Kubernetes cluster, useful for CI systems. Not recommended for production use.
+
+**Options:**
+
+- `-l, --log-level [level]` - Log level: debug, info, warn, error (default: "info")
+- `-i, --image [image]` - Override the image tag
+- `--confirm` - Skip confirmation prompt
+
+---
+
+## `pepr build`
+
+Create a [zarf.yaml](https://zarf.dev) and K8s manifest for the current module. This includes everything needed to deploy Pepr and the current module into production environments.
+
+**Options:**
+
+- `-l, --log-level [level]` - Log level: debug, info, warn, error (default: "info")

docs/module.md

@@ -0,0 +1,89 @@
+# Pepr Module
+
+Each Pepr Module is it's own Typescript project, produced by [`pepr init`](./cli.md#pepr-init). Typically a module is maintained by a unique group or system. For example, a module for internal [Zarf](https://zarf.dev/) mutations would be different from a module for [Big Bang](https://p1.dso.mil/products/big-bang). An important idea with modules is that they are _wholly independent of one another_. This means that 2 different modules can be on completely different versions of Pepr and any other dependencies; their only interaction is through the standard K8s interfaces like any other webhook or controller.
+
+## Module development lifecycle
+
+1. **Create the module**:
+
+   Use [`pepr init`](./cli.md#pepr-init) to generate a new module.
+
+1. **Quickly validate system setup**:
+
+   Every new module includes a sample Pepr Capability called `HelloPepr`. By default,
+   this capability is deployed and monitoring the `pepr-demo` namespace. There is a sample
+   yaml also included you can use to see Pepr in your cluster. Here's the quick steps to do
+   that after `pepr init`:
+
+   ```bash
+   # cd to the newly-created Pepr module folder
+   cd my-module-name
+
+   # If you don't already have a local K8s cluster, you can set one up with k3d
+   npm run k3d-setup
+
+   # Launch pepr dev mode (npm start or pepr dev)
+   pepr dev
+
+   # From another terminal, apply the sample yaml
+   kubectl apply -f capabilities/hello-pepr.samples.yaml
+
+   # Verify the configmaps were transformed using kubectl, k9s or another tool
+   ```
+
+1. **Create your custom Pepr Capabilities**
+
+   Now that you have confirmed Pepr is working, you can now create new [capabilities](./capabilities.md). You'll also want to disable the `HelloPepr` capability in your module (`pepr.ts`) before pushing to production. You can disable by commenting out or deleting the `HelloPepr` variable below:
+
+   ```typescript
+   new PeprModule(cfg, [
+     // Remove or comment the line below to disable the HelloPepr capability
+     HelloPepr,
+
+     // Your additional capabilities go here
+   ]);
+   ```
+
+   _Note: if you also delete the `capabilities/hello-pepr.ts` file, it will be added again on the next [`pepr update`](./cli.md#pepr-update) so you have the latest examples usages from the Pepr SDK. Therefore, it is sufficient to remove the entry from your `pepr.ts` module
+   config._
+
+1. **Build and deploy the Pepr Module**
+
+   Most of the time, you'll likely be iterating on a module with `perp dev` for real-time feedback and validation Once you are ready to move beyond the local dev environment, Pepr provides deployment and build tools you can use.
+
+   `pepr deploy` - you can use this command to build your module and deploy it into any K8s cluster your current `kubecontext` has access to. This setup is ideal for CI systems during testing, but is not recommended for production use. See [`pepr deploy`](./cli.md#pepr-deploy) for more info.
+
+## Advanced Module Configuration
+
+By default, when you run `pepr init`, the module is not configured with any additional options. Currently, there are 3 options you can configure:
+
+- `deferStart` - if set to `true`, the module will not start automatically. You will need to call `start()` manually. This is useful if you want to do some additional setup before the module controller starts. You can also use this to change the default port that the controller listens on.
+
+- `beforeHook` - an optional callback that will be called before every request is processed. This is useful if you want to do some additional logging or validation before the request is processed.
+
+- `afterHook` - an optional callback that will be called after every request is processed. This is useful if you want to do some additional logging or validation after the request is processed.
+
+You can configure each of these by modifying the `pepr.ts` file in your module. Here's an example of how you would configure each of these options:
+
+```typescript
+const module = new PeprModule(
+  cfg,
+  [
+    // Your capabilities go here
+  ],
+  {
+    deferStart: true,
+
+    beforeHook: req => {
+      // Any actions you want to perform before the request is processed, including modifying the request.
+    },
+
+    afterHook: res => {
+      // Any actions you want to perform after the request is processed, including modifying the response.
+    },
+  }
+);
+
+// Do any additional setup before starting the controller
+module.start();
+```

hack/e2e.test.js

@@ -21,6 +21,8 @@ let expectedLines = [
   "hello-pepr: V1ConfigMap Binding created",
   "hello-pepr: V1ConfigMap Binding action created",
   "Server listening on port 3000",
+  "Using beforeHook: req => pepr_1.Log.debug(`beforeHook: ${req.uid}`)",
+  "Using afterHook: res => pepr_1.Log.debug(`afterHook: ${res.uid}`)",
 ];
 
 function stripAnsiCodes(input) {

src/cli/init/templates.ts

@@ -6,9 +6,9 @@ import { inspect } from "util";
 import { v4 as uuidv4, v5 as uuidv5 } from "uuid";
 import { dependencies, scripts, version } from "../../../package.json";
 import prettierRCJSON from "./templates/.prettierrc.json";
+import samplesJSON from "./templates/capabilities/hello-pepr.samples.json";
 import generatedJSON from "./templates/data.json";
 import peprSnippetsJSON from "./templates/pepr.code-snippets.json";
-import samplesJSON from "./templates/samples.json";
 import tsConfigJSON from "./templates/tsconfig.module.json";
 import { sanitizeName } from "./utils";
 import { InitOptions } from "./walkthrough";