pepr 0.2.6 → 0.2.8

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/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,9 +70,13 @@ 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
 
@@ -56,81 +84,7 @@ CapabilityAction is a discrete set of behaviors defined in a single function tha
 
 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
 

package/dist/package.json

@@ -9,7 +9,7 @@
     "engines": {
         "node": ">=18.0.0"
     },
-    "version": "0.2.6",
+    "version": "0.2.8",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "pepr": {

package/dist/src/cli/init/templates/data.json

@@ -1 +1 @@
-{ "gitignore": "# Ignore node_modules and Pepr build artifacts\nnode_modules\ndist\ninsecure*\n", "readme": "# Pepr Module\n\nThis is a Pepr Module. [Pepr](https://github.com/defenseunicorns/pepr) is a Kubernetes transformation system\nwritten in Typescript.\n\nThe `capabilities` directory contains all the capabilities for this module. By default,\na capability is a single typescript file in the format of `capability-name.ts` that is\nimported in the root `pepr.ts` file as `import { HelloPepr } from \"./capabilities/hello-pepr\";`.\nBecause this is typescript, you can organize this however you choose, e.g. creating a sub-folder\nper-capability or common logic in shared files or folders.\n\nExample Structure:\n\n```\nModule Root\n├── package.json\n├── pepr.ts\n└── capabilities\n    ├── example-one.ts\n    ├── example-three.ts\n    └── example-two.ts\n```\n", "peprTS": "import { PeprModule } from \"pepr\";\nimport { HelloPepr } from \"./capabilities/hello-pepr\";\nimport cfg from \"./package.json\";\n\n/**\n * This is the main entrypoint for the Pepr module. It is the file that is run when the module is started.\n * This is where you register your configurations and capabilities with the module.\n */\nnew PeprModule(cfg, [\n  // \"HelloPepr\" is a demo capability that is included with Pepr. You can remove it if you want.\n  HelloPepr,\n\n  // Your additional capabilities go here\n]);\n", "helloPeprTS": "import { Capability, PeprRequest, RegisterKind, a, fetch } from \"pepr\";\n\n/**\n *  The HelloPepr Capability is an example capability to demonstrate some general concepts of Pepr.\n *  To test this capability you can run `pepr dev` or `npm start` and then run the following command:\n *  `kubectl apply -f capabilities/hello-pepr.samples.yaml`\n */\nexport const HelloPepr = new Capability({\n  name: \"hello-pepr\",\n  description: \"A simple example capability to show how things work.\",\n  namespaces: [\"pepr-demo\"],\n});\n\n// Use the 'When' function to create a new Capability Action\nconst { When } = HelloPepr;\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (Namespace)                                   *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action removes the label `remove-me` when a Namespace is created.\n * Note we don't need to specify the namespace here, because we've already specified\n * it in the Capability definition above.\n */\nWhen(a.Namespace)\n  .IsCreated()\n  .Then(ns => ns.RemoveLabel(\"remove-me\"));\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (CM Example 1)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This is a single Capability Action. They can be in the same file or put imported from other files.\n * In this example, when a ConfigMap is created with the name `example-1`, then add a label and annotation.\n *\n * Equivalent to manually running:\n * `kubectl label configmap example-1 pepr=was-here`\n * `kubectl annotate configmap example-1 pepr.dev=annotations-work-too`\n */\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithName(\"example-1\")\n  .Then(request =>\n    request\n      .SetLabel(\"pepr\", \"was-here\")\n      .SetAnnotation(\"pepr.dev\", \"annotations-work-too\")\n  );\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (CM Example 2)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action does the exact same changes for example-2, except this time it uses\n * the `.ThenSet()` feature. You can stack multiple `.Then()` calls, but only a single `.ThenSet()`\n */\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithName(\"example-2\")\n  .ThenSet({\n    metadata: {\n      labels: {\n        pepr: \"was-here\",\n      },\n      annotations: {\n        \"pepr.dev\": \"annotations-work-too\",\n      },\n    },\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (CM Example 3)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action combines different styles. Unlike the previous actions, this one will look\n * for any ConfigMap in the `pepr-demo` namespace that has the label `change=by-label` during either\n * CREATE or UPDATE. Note that all conditions added such as `WithName()`, `WithLabel()`, `InNamespace()`,\n * are ANDs so all conditions must be true for the request to be processed.\n */\nWhen(a.ConfigMap)\n  .IsCreatedOrUpdated()\n  .WithLabel(\"change\", \"by-label\")\n  .Then(request => {\n    // The K8s object e are going to mutate\n    const cm = request.Raw;\n\n    // Get the username and uid of the K8s request\n    const { username, uid } = request.Request.userInfo;\n\n    // Store some data about the request in the configmap\n    cm.data[\"username\"] = username;\n    cm.data[\"uid\"] = uid;\n\n    // You can still mix other ways of making changes too\n    request.SetAnnotation(\"pepr.dev\", \"making-waves\");\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (CM Example 4)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action show how you can use the `Then()` function to make multiple changes to the\n * same object from different functions. This is useful if you want to keep your Capability Actions\n * small and focused on a single task, or if you want to reuse the same function in multiple\n * Capability Actions.\n *\n * Note that the order of the `.Then()` calls matters. The first call will be executed first,\n * then the second, and so on. Also note the functions are not called until the Capability Action\n * is triggered.\n */\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithName(\"example-4\")\n  .Then(cm => cm.SetLabel(\"pepr.dev/first\", \"true\"))\n  .Then(addSecond)\n  .Then(addThird);\n\n//This function uses the complete type definition, but is not required.\nfunction addSecond(cm: PeprRequest<a.ConfigMap>) {\n  cm.SetLabel(\"pepr.dev/second\", \"true\");\n}\n\n// This function has no type definition, so you won't have intellisense in the function body.\nfunction addThird(cm) {\n  cm.SetLabel(\"pepr.dev/third\", \"true\");\n}\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (CM Example 5)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action is a bit more complex. It will look for any ConfigMap in the `pepr-demo`\n * namespace that has the label `chuck-norris` during CREATE. When it finds one, it will fetch a\n * random Chuck Norris joke from the API and add it to the ConfigMap. This is a great example of how\n * you can use Pepr to make changes to your K8s objects based on external data.\n *\n * Note the use of the `async` keyword. This is required for any Capability Action that uses `await` or `fetch()`.\n *\n * Also note we are passing a type to the `fetch()` function. This is optional, but it will help you\n * avoid mistakes when working with the data returned from the API. You can also use the `as` keyword to\n * cast the data returned from the API.\n *\n * These are equivalent:\n * ```ts\n * const joke = await fetch<TheChuckNorrisJoke>(\"https://api.chucknorris.io/jokes/random?category=dev\");\n * const joke = await fetch(\"https://api.chucknorris.io/jokes/random?category=dev\") as TheChuckNorrisJoke;\n * ```\n *\n * Alternatively, you can drop the type completely:\n *\n * ```ts\n * fetch(\"https://api.chucknorris.io/jokes/random?category=dev\")\n * ```\n */\ninterface TheChuckNorrisJoke {\n  icon_url: string;\n  id: string;\n  url: string;\n  value: string;\n}\n\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithLabel(\"chuck-norris\")\n  .Then(async change => {\n    const response = await fetch<TheChuckNorrisJoke>(\n      \"https://api.chucknorris.io/jokes/random?category=dev\"\n    );\n\n    if (response.ok) {\n      // Add the Chuck Norris joke to the configmap\n      change.Raw.data[\"chuck-says\"] = response.data.value;\n    }\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (Untyped Custom Resource)                     *\n * ---------------------------------------------------------------------------------------------------\n *\n * Out of the box, Pepr supports all the standard Kubernetes objects. However, you can also create\n * your own types. This is useful if you are working with an Operator that creates custom resources.\n * There are two ways to do this, the first is to use the `When()` function with a `GenericKind`,\n * the second is to create a new class that extends `GenericKind` and use the `RegisterKind()` function.\n *\n * This example shows how to use the `When()` function with a `GenericKind`. Note that you\n * must specify the `group`, `version`, and `kind` of the object (if applicable). This is how Pepr knows\n * if the Capability Action should be triggered or not. Since we are using a `GenericKind`,\n * Pepr will not be able to provide any intellisense for the object, so you will need to refer to the\n * Kubernetes API documentation for the object you are working with.\n *\n * You will need ot wait for the CRD in `hello-pepr.samples.yaml` to be created, then you can apply\n *\n * ```yaml\n * apiVersion: pepr.dev/v1\n * kind: Unicorn\n * metadata:\n *   name: example-1\n *   namespace: pepr-demo\n * spec:\n *   message: replace-me\n *   counter: 0\n * ```\n */\nWhen(a.GenericKind, {\n  group: \"pepr.dev\",\n  version: \"v1\",\n  kind: \"Unicorn\",\n})\n  .IsCreated()\n  .WithName(\"example-1\")\n  .ThenSet({\n    spec: {\n      message: \"Hello Pepr without type data!\",\n      counter: Math.random(),\n    },\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (Typed Custom Resource)                       *\n * ---------------------------------------------------------------------------------------------------\n *\n * This example shows how to use the `RegisterKind()` function to create a new type. This is useful\n * if you are working with an Operator that creates custom resources and you want to have intellisense\n * for the object. Note that you must specify the `group`, `version`, and `kind` of the object (if applicable)\n * as this is how Pepr knows if the Capability Action should be triggered or not.\n *\n * Once you register a new Kind with Pepr, you can use the `When()` function with the new Kind. Ideally,\n * you should register custom Kinds at the top of your Capability file or Pepr Module so they are available\n * to all Capability Actions, but we are putting it here for demonstration purposes.\n *\n * You will need ot wait for the CRD in `hello-pepr.samples.yaml` to be created, then you can apply\n *\n * ```yaml\n * apiVersion: pepr.dev/v1\n * kind: Unicorn\n * metadata:\n *   name: example-2\n *   namespace: pepr-demo\n * spec:\n *   message: replace-me\n *   counter: 0\n * ```*\n */\nclass UnicornKind extends a.GenericKind {\n  spec: {\n    /**\n     * JSDoc comments can be added to explain more details about the field.\n     *\n     * @example\n     * ```ts\n     * request.Raw.spec.message = \"Hello Pepr!\";\n     * ```\n     * */\n    message: string;\n    counter: number;\n  };\n}\n\nRegisterKind(UnicornKind, {\n  group: \"pepr.dev\",\n  version: \"v1\",\n  kind: \"Unicorn\",\n});\n\nWhen(UnicornKind)\n  .IsCreated()\n  .WithName(\"example-2\")\n  .ThenSet({\n    spec: {\n      message: \"Hello Pepr now with type data!\",\n      counter: Math.random(),\n    },\n  });\n" }
+{ "gitignore": "# Ignore node_modules and Pepr build artifacts\nnode_modules\ndist\ninsecure*\n", "readme": "# Pepr Module\n\nThis is a Pepr Module. [Pepr](https://github.com/defenseunicorns/pepr) is a Kubernetes transformation system\nwritten in Typescript.\n\nThe `capabilities` directory contains all the capabilities for this module. By default,\na capability is a single typescript file in the format of `capability-name.ts` that is\nimported in the root `pepr.ts` file as `import { HelloPepr } from \"./capabilities/hello-pepr\";`.\nBecause this is typescript, you can organize this however you choose, e.g. creating a sub-folder\nper-capability or common logic in shared files or folders.\n\nExample Structure:\n\n```\nModule Root\n├── package.json\n├── pepr.ts\n└── capabilities\n    ├── example-one.ts\n    ├── example-three.ts\n    └── example-two.ts\n```\n", "peprTS": "import { Log, PeprModule } from \"pepr\";\nimport { HelloPepr } from \"./capabilities/hello-pepr\";\n// cfg loads your pepr configuration from package.json\nimport cfg from \"./package.json\";\n\n/**\n * This is the main entrypoint for this Pepr module. It is run when the module is started.\n * This is where you register your Pepr configurations and capabilities.\n */\nnew PeprModule(\n  cfg,\n  [\n    // \"HelloPepr\" is a demo capability that is included with Pepr. Comment or delete the line below to remove it.\n    HelloPepr,\n\n    // Your additional capabilities go here\n  ],\n  {\n    // Any actions you want to perform before the request is processed, including modifying the request.\n    // Comment out or delete the line below to remove the default beforeHook.\n    beforeHook: req => Log.debug(`beforeHook: ${req.uid}`),\n\n    // Any actions you want to perform after the request is processed, including modifying the response.\n    // Comment out or delete the line below to remove the default afterHook.\n    afterHook: res => Log.debug(`afterHook: ${res.uid}`),\n  }\n);\n", "helloPeprTS": "import {\n  Capability,\n  PeprRequest,\n  RegisterKind,\n  a,\n  fetch,\n  fetchStatus,\n} from \"pepr\";\n\n/**\n *  The HelloPepr Capability is an example capability to demonstrate some general concepts of Pepr.\n *  To test this capability you can run `pepr dev` or `npm start` and then run the following command:\n *  `kubectl apply -f capabilities/hello-pepr.samples.yaml`\n */\nexport const HelloPepr = new Capability({\n  name: \"hello-pepr\",\n  description: \"A simple example capability to show how things work.\",\n  namespaces: [\"pepr-demo\"],\n});\n\n// Use the 'When' function to create a new Capability Action\nconst { When } = HelloPepr;\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (Namespace)                                   *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action removes the label `remove-me` when a Namespace is created.\n * Note we don't need to specify the namespace here, because we've already specified\n * it in the Capability definition above.\n */\nWhen(a.Namespace)\n  .IsCreated()\n  .Then(ns => ns.RemoveLabel(\"remove-me\"));\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (CM Example 1)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This is a single Capability Action. They can be in the same file or put imported from other files.\n * In this example, when a ConfigMap is created with the name `example-1`, then add a label and annotation.\n *\n * Equivalent to manually running:\n * `kubectl label configmap example-1 pepr=was-here`\n * `kubectl annotate configmap example-1 pepr.dev=annotations-work-too`\n */\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithName(\"example-1\")\n  .Then(request =>\n    request\n      .SetLabel(\"pepr\", \"was-here\")\n      .SetAnnotation(\"pepr.dev\", \"annotations-work-too\")\n  );\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (CM Example 2)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action does the exact same changes for example-2, except this time it uses\n * the `.ThenSet()` feature. You can stack multiple `.Then()` calls, but only a single `.ThenSet()`\n */\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithName(\"example-2\")\n  .ThenSet({\n    metadata: {\n      labels: {\n        pepr: \"was-here\",\n      },\n      annotations: {\n        \"pepr.dev\": \"annotations-work-too\",\n      },\n    },\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (CM Example 3)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action combines different styles. Unlike the previous actions, this one will look\n * for any ConfigMap in the `pepr-demo` namespace that has the label `change=by-label` during either\n * CREATE or UPDATE. Note that all conditions added such as `WithName()`, `WithLabel()`, `InNamespace()`,\n * are ANDs so all conditions must be true for the request to be processed.\n */\nWhen(a.ConfigMap)\n  .IsCreatedOrUpdated()\n  .WithLabel(\"change\", \"by-label\")\n  .Then(request => {\n    // The K8s object e are going to mutate\n    const cm = request.Raw;\n\n    // Get the username and uid of the K8s request\n    const { username, uid } = request.Request.userInfo;\n\n    // Store some data about the request in the configmap\n    cm.data[\"username\"] = username;\n    cm.data[\"uid\"] = uid;\n\n    // You can still mix other ways of making changes too\n    request.SetAnnotation(\"pepr.dev\", \"making-waves\");\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (CM Example 4)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action show how you can use the `Then()` function to make multiple changes to the\n * same object from different functions. This is useful if you want to keep your Capability Actions\n * small and focused on a single task, or if you want to reuse the same function in multiple\n * Capability Actions.\n *\n * Note that the order of the `.Then()` calls matters. The first call will be executed first,\n * then the second, and so on. Also note the functions are not called until the Capability Action\n * is triggered.\n */\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithName(\"example-4\")\n  .Then(cm => cm.SetLabel(\"pepr.dev/first\", \"true\"))\n  .Then(addSecond)\n  .Then(addThird);\n\n//This function uses the complete type definition, but is not required.\nfunction addSecond(cm: PeprRequest<a.ConfigMap>) {\n  cm.SetLabel(\"pepr.dev/second\", \"true\");\n}\n\n// This function has no type definition, so you won't have intellisense in the function body.\nfunction addThird(cm) {\n  cm.SetLabel(\"pepr.dev/third\", \"true\");\n}\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (CM Example 5)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action is a bit more complex. It will look for any ConfigMap in the `pepr-demo`\n * namespace that has the label `chuck-norris` during CREATE. When it finds one, it will fetch a\n * random Chuck Norris joke from the API and add it to the ConfigMap. This is a great example of how\n * you can use Pepr to make changes to your K8s objects based on external data.\n *\n * Note the use of the `async` keyword. This is required for any Capability Action that uses `await` or `fetch()`.\n *\n * Also note we are passing a type to the `fetch()` function. This is optional, but it will help you\n * avoid mistakes when working with the data returned from the API. You can also use the `as` keyword to\n * cast the data returned from the API.\n *\n * These are equivalent:\n * ```ts\n * const joke = await fetch<TheChuckNorrisJoke>(\"https://api.chucknorris.io/jokes/random?category=dev\");\n * const joke = await fetch(\"https://api.chucknorris.io/jokes/random?category=dev\") as TheChuckNorrisJoke;\n * ```\n *\n * Alternatively, you can drop the type completely:\n *\n * ```ts\n * fetch(\"https://api.chucknorris.io/jokes/random?category=dev\")\n * ```\n */\ninterface TheChuckNorrisJoke {\n  icon_url: string;\n  id: string;\n  url: string;\n  value: string;\n}\n\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithLabel(\"chuck-norris\")\n  .Then(async change => {\n    // Try/catch is not needed as a response object will always be returned\n    const response = await fetch<TheChuckNorrisJoke>(\n      \"https://api.chucknorris.io/jokes/random?category=dev\"\n    );\n\n    // Instead, check the `response.ok` field\n    if (response.ok) {\n      // Add the Chuck Norris joke to the configmap\n      change.Raw.data[\"chuck-says\"] = response.data.value;\n      return;\n    }\n\n    // You can also assert on different HTTP response codes\n    if (response.status === fetchStatus.NOT_FOUND) {\n      // Do something else\n      return;\n    }\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (Untyped Custom Resource)                     *\n * ---------------------------------------------------------------------------------------------------\n *\n * Out of the box, Pepr supports all the standard Kubernetes objects. However, you can also create\n * your own types. This is useful if you are working with an Operator that creates custom resources.\n * There are two ways to do this, the first is to use the `When()` function with a `GenericKind`,\n * the second is to create a new class that extends `GenericKind` and use the `RegisterKind()` function.\n *\n * This example shows how to use the `When()` function with a `GenericKind`. Note that you\n * must specify the `group`, `version`, and `kind` of the object (if applicable). This is how Pepr knows\n * if the Capability Action should be triggered or not. Since we are using a `GenericKind`,\n * Pepr will not be able to provide any intellisense for the object, so you will need to refer to the\n * Kubernetes API documentation for the object you are working with.\n *\n * You will need ot wait for the CRD in `hello-pepr.samples.yaml` to be created, then you can apply\n *\n * ```yaml\n * apiVersion: pepr.dev/v1\n * kind: Unicorn\n * metadata:\n *   name: example-1\n *   namespace: pepr-demo\n * spec:\n *   message: replace-me\n *   counter: 0\n * ```\n */\nWhen(a.GenericKind, {\n  group: \"pepr.dev\",\n  version: \"v1\",\n  kind: \"Unicorn\",\n})\n  .IsCreated()\n  .WithName(\"example-1\")\n  .ThenSet({\n    spec: {\n      message: \"Hello Pepr without type data!\",\n      counter: Math.random(),\n    },\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION (Typed Custom Resource)                       *\n * ---------------------------------------------------------------------------------------------------\n *\n * This example shows how to use the `RegisterKind()` function to create a new type. This is useful\n * if you are working with an Operator that creates custom resources and you want to have intellisense\n * for the object. Note that you must specify the `group`, `version`, and `kind` of the object (if applicable)\n * as this is how Pepr knows if the Capability Action should be triggered or not.\n *\n * Once you register a new Kind with Pepr, you can use the `When()` function with the new Kind. Ideally,\n * you should register custom Kinds at the top of your Capability file or Pepr Module so they are available\n * to all Capability Actions, but we are putting it here for demonstration purposes.\n *\n * You will need ot wait for the CRD in `hello-pepr.samples.yaml` to be created, then you can apply\n *\n * ```yaml\n * apiVersion: pepr.dev/v1\n * kind: Unicorn\n * metadata:\n *   name: example-2\n *   namespace: pepr-demo\n * spec:\n *   message: replace-me\n *   counter: 0\n * ```*\n */\nclass UnicornKind extends a.GenericKind {\n  spec: {\n    /**\n     * JSDoc comments can be added to explain more details about the field.\n     *\n     * @example\n     * ```ts\n     * request.Raw.spec.message = \"Hello Pepr!\";\n     * ```\n     * */\n    message: string;\n    counter: number;\n  };\n}\n\nRegisterKind(UnicornKind, {\n  group: \"pepr.dev\",\n  version: \"v1\",\n  kind: \"Unicorn\",\n});\n\nWhen(UnicornKind)\n  .IsCreated()\n  .WithName(\"example-2\")\n  .ThenSet({\n    spec: {\n      message: \"Hello Pepr now with type data!\",\n      counter: Math.random(),\n    },\n  });\n" }

package/dist/src/cli/init/templates.js

@@ -11,9 +11,9 @@ const util_1 = require("util");
 const uuid_1 = require("uuid");
 const package_json_1 = require("../../../package.json");
 const _prettierrc_json_1 = __importDefault(require("./templates/.prettierrc.json"));
+const hello_pepr_samples_json_1 = __importDefault(require("./templates/capabilities/hello-pepr.samples.json"));
 const data_json_1 = __importDefault(require("./templates/data.json"));
 const pepr_code_snippets_json_1 = __importDefault(require("./templates/pepr.code-snippets.json"));
-const samples_json_1 = __importDefault(require("./templates/samples.json"));
 const tsconfig_module_json_1 = __importDefault(require("./templates/tsconfig.module.json"));
 const utils_1 = require("./utils");
 function genPkgJSON(opts, pgkVerOverride) {
@@ -79,7 +79,7 @@ exports.gitIgnore = {
 };
 exports.samplesYaml = {
     path: "hello-pepr.samples.yaml",
-    data: samples_json_1.default.map(r => (0, client_node_1.dumpYaml)(r, { noRefs: true })).join("---\n"),
+    data: hello_pepr_samples_json_1.default.map(r => (0, client_node_1.dumpYaml)(r, { noRefs: true })).join("---\n"),
 };
 exports.snippet = {
     path: "pepr.code-snippets",

package/dist/src/lib/controller.d.ts

@@ -1,11 +1,14 @@
-import { ModuleConfig } from "./types";
 import { Capability } from "./capability";
+import { Request, Response } from "./k8s/types";
+import { ModuleConfig } from "./types";
 export declare class Controller {
     private readonly config;
     private readonly capabilities;
+    private readonly beforeHook?;
+    private readonly afterHook?;
     private readonly app;
     private running;
-    constructor(config: ModuleConfig, capabilities: Capability[]);
+    constructor(config: ModuleConfig, capabilities: Capability[], beforeHook?: (req: Request) => void, afterHook?: (res: Response) => void);
     /** Start the webhook server */
     startServer: (port: number) => void;
     private logger;

package/dist/src/lib/controller.js

@@ -16,9 +16,11 @@ const options = {
     cert: fs_1.default.readFileSync(process.env.SSL_CERT_PATH || "/etc/certs/tls.crt"),
 };
 class Controller {
-    constructor(config, capabilities) {
+    constructor(config, capabilities, beforeHook, afterHook) {
         this.config = config;
         this.capabilities = capabilities;
+        this.beforeHook = beforeHook;
+        this.afterHook = afterHook;
         this.app = (0, express_1.default)();
         this.running = false;
         /** Start the webhook server */
@@ -54,12 +56,18 @@ class Controller {
         };
         this.mutate = async (req, res) => {
             try {
+                // Run the before hook if it exists
+                this.beforeHook && this.beforeHook(req.body?.request || {});
                 const name = req.body?.request?.name || "";
                 const namespace = req.body?.request?.namespace || "";
                 const gvk = req.body?.request?.kind || { group: "", version: "", kind: "" };
                 console.log(`Mutate request: ${gvk.group}/${gvk.version}/${gvk.kind}`);
                 name && console.log(`                ${namespace}/${name}\n`);
+                // Process the request
                 const response = await (0, processor_1.processor)(this.config, this.capabilities, req.body.request);
+                // Run the after hook if it exists
+                this.afterHook && this.afterHook(response);
+                // Log the response
                 console.debug(response);
                 // Send a no prob bob response
                 res.send({
@@ -81,6 +89,12 @@ class Controller {
         this.app.get("/healthz", this.healthz);
         // Mutate endpoint
         this.app.post("/mutate", this.mutate);
+        if (beforeHook) {
+            console.info(`Using beforeHook: ${beforeHook}`);
+        }
+        if (afterHook) {
+            console.info(`Using afterHook: ${afterHook}`);
+        }
     }
 }
 exports.Controller = Controller;

package/dist/src/lib/fetch.d.ts

@@ -1,6 +1,12 @@
 /// <reference types="node" />
 import f, { RequestInfo, RequestInit } from "node-fetch";
 export { f as fetchRaw };
+export type FetchResponse<T> = {
+    data: T;
+    ok: boolean;
+    status: number;
+    statusText: string;
+};
 /**
  * Perform an async HTTP call and return the parsed JSON response, optionally
  * as a specific type.
@@ -14,14 +20,4 @@ export { f as fetchRaw };
  * @param init Additional options for the request
  * @returns
  */
-export declare function fetch<T>(url: URL | RequestInfo, init?: RequestInit): Promise<{
-    data: T;
-    ok: boolean;
-    status: number;
-    statusText: string;
-} | {
-    data: any;
-    ok: boolean;
-    status: any;
-    statusText: any;
-}>;
+export declare function fetch<T>(url: URL | RequestInfo, init?: RequestInit): Promise<FetchResponse<T>>;

package/dist/src/lib/fetch.js

@@ -27,9 +27,17 @@ async function fetch(url, init) {
     try {
         logger_1.default.debug(`Fetching ${url}`);
         const resp = await (0, node_fetch_1.default)(url, init);
+        const contentType = resp.headers.get("content-type") || "";
         let data;
         if (resp.ok) {
-            data = await resp.json();
+            // Parse the response as JSON if the content type is JSON
+            if (contentType.includes("application/json")) {
+                data = await resp.json();
+            }
+            else {
+                // Otherwise, return however the response was read
+                data = (await resp.text());
+            }
         }
         return {
             data,

package/dist/src/lib/module.d.ts

@@ -1,11 +1,18 @@
 import { Capability } from "./capability";
+import { Request, Response } from "./k8s/types";
 import { ModuleConfig } from "./types";
 export type PackageJSON = {
     description: string;
     pepr: ModuleConfig;
 };
+export type PeprModuleOptions = {
+    deferStart?: boolean;
+    /** A user-defined callback to pre-process or intercept a Pepr request from K8s immediately before it is processed */
+    beforeHook?: (req: Request) => void;
+    /** A user-defined callback to post-process or intercept a Pepr response just before it is returned to K8s */
+    afterHook?: (res: Response) => void;
+};
 export declare class PeprModule {
-    private readonly _deferStart;
     private _controller;
     /**
      * Create a new Pepr runtime
@@ -14,7 +21,7 @@ export declare class PeprModule {
      * @param capabilities The capabilities to be loaded into the Pepr runtime
      * @param _deferStart (optional) If set to `true`, the Pepr runtime will not be started automatically. This can be used to start the Pepr runtime manually with `start()`.
      */
-    constructor({ description, pepr }: PackageJSON, capabilities?: Capability[], _deferStart?: boolean);
+    constructor({ description, pepr }: PackageJSON, capabilities?: Capability[], opts?: PeprModuleOptions);
     /**
      * Start the Pepr runtime manually.
      * Normally this is called automatically when the Pepr module is instantiated, but can be called manually if `deferStart` is set to `true` in the constructor.

package/dist/src/lib/module.js

@@ -20,14 +20,15 @@ class PeprModule {
      * @param capabilities The capabilities to be loaded into the Pepr runtime
      * @param _deferStart (optional) If set to `true`, the Pepr runtime will not be started automatically. This can be used to start the Pepr runtime manually with `start()`.
      */
-    constructor({ description, pepr }, capabilities = [], _deferStart = false) {
-        this._deferStart = _deferStart;
+    constructor({ description, pepr }, capabilities = [], opts = {}) {
         const config = ramda_1.default.mergeDeepWith(ramda_1.default.concat, pepr, alwaysIgnore);
         config.description = description;
-        this._controller = new controller_1.Controller(config, capabilities);
-        if (!_deferStart) {
-            this.start();
+        this._controller = new controller_1.Controller(config, capabilities, opts.beforeHook, opts.afterHook);
+        // Stop processing if deferStart is set to true
+        if (opts.deferStart) {
+            return;
         }
+        this.start();
     }
     /**
      * Start the Pepr runtime manually.

package/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
+}

package/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.

package/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._

package/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")

package/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();
+```

package/package.json

@@ -9,7 +9,7 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "version": "0.2.6",
+  "version": "0.2.8",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "pepr": {