pepr 0.12.2 → 0.13.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+`pepr-complaints` `@` `defenseunicorns.com`.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

package/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+
+
+# Contributing to Pepr
+
+Thank you for your interest in contributing to Pepr! We welcome all contributions and are grateful for your help. This guide outlines how to get started with contributing to this project.
+
+## Table of Contents
+
+1. [Code of Conduct](#code-of-conduct)
+2. [Getting Started](#getting-started)
+3. [Submitting a Pull Request](#submitting-a-pull-request)
+4. [Coding Guidelines](#coding-guidelines)
+5. [Running Tests](#running-tests)
+6. [Contact](#contact)
+
+## Code of Conduct
+
+Please follow our [Code of Conduct](CODE_OF_CONDUCT.md) to maintain a respectful and collaborative environment.
+
+## Getting Started
+
+- **Repository**: [https://github.com/defenseunicorns/pepr/](https://github.com/defenseunicorns/pepr/)
+- **npm package**: [https://www.npmjs.com/package/pepr](https://www.npmjs.com/package/pepr)
+- **Required Node version**: `>=18.0.0`
+
+### Setup
+
+1. Fork the repository.
+2. Clone your fork locally: `git clone https://github.com/your-username/pepr.git`.
+3. Install dependencies: `npm ci`.
+4. Create a new branch for your feature or fix: `git checkout -b my-feature-branch`.
+
+## Submitting a Pull Request
+
+1. **Create an Issue**: For significant changes, please create an issue first, describing the problem or feature proposal. Trivial fixes do not require an issue.
+2. **Commit Your Changes**: Make your changes and commit them. All commits must be signed.
+3. **Run Tests**: Ensure that your changes pass all tests by running `npm test`.
+4. **Push Your Branch**: Push your branch to your fork on GitHub.
+5. **Create a Pull Request**: Open a pull request against the `main` branch of the Pepr repository. Please make sure that your PR passes all CI checks.
+
+### PR Requirements
+
+- PRs must be against the `main` branch.
+- PRs must pass CI checks.
+- All commits must be signed.
+- PRs should have a related issue, except for trivial fixes.
+
+## Coding Guidelines
+
+Please follow the coding conventions and style used in the project. Use ESLint and Prettier for linting and formatting:
+
+- Check formatting: `npm run format:check`
+- Fix formatting: `npm run format:fix`
+
+## Running Tests
+
+### Run Tests Locally
+
+- Run all tests: `npm test`
+
+### Test a Local Development Version
+
+1. Run `npm test` and wait for completion.
+2. Change to the test module directory: `cd pepr-test-module`.
+3. You can now run any of the `npx pepr` commands.
+
+## Contact
+
+For any questions or concerns, please open an issue on GitHub or contact the maintainers.
+

package/README.md

@@ -6,8 +6,7 @@
 [![Npm package version](https://badgen.net/npm/v/pepr)](https://npmjs.com/package/pepr)
 [![Npm package total downloads](https://badgen.net/npm/dt/pepr)](https://npmjs.com/package/pepr)
 
-
-#### __*Type safe Kubernetes middleware for humans*__
+#### **_Type safe Kubernetes middleware for humans_**
 
 <img align="right" width="40%" src=".images/pepr.png" />
 
@@ -15,7 +14,7 @@ Pepr is on a mission to save Kubernetes from the tyranny of YAML, intimidating g
 
 ## Features
 
-- Zero-config K8s webhook mutations and [validations soon](https://github.com/defenseunicorns/pepr/issues/73).
+- Zero-config K8s webhook mutations and validations.
 - Human-readable fluent API for generating [Pepr Capabilities](#capability)
 - Generate new K8s resources based off of cluster resource changes
 - Perform other exec/API calls based off of cluster resources changes or any other arbitrary schedule
@@ -26,26 +25,35 @@ Pepr is on a mission to save Kubernetes from the tyranny of YAML, intimidating g
 - Automatic least-privilege RBAC generation [soon](https://github.com/defenseunicorns/pepr/issues/31)
 - AMD64 and ARM64 support
 
-## Example Pepr CapabilityAction
+## Example Pepr Action
 
-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).
+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 [actions](./docs/actions.md).
 
 ```ts
 When(a.ConfigMap)
   .IsCreatedOrUpdated()
   .InNamespace("pepr-demo")
   .WithLabel("unicorn", "rainbow")
-  .Then(request => {
+  // Create a Mutate Action for the ConfigMap
+  .Mutate(request => {
     // Add a label and annotation to the ConfigMap
-    request
-      .SetLabel("pepr", "was-here")
-      .SetAnnotation("pepr.dev", "annotations-work-too");
+    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:");
+  })
+  // Create a Validate Action for the ConfigMap
+  .Validate(request => {
+    // Validate the ConfigMap has a specific label
+    if (request.HasLabel("pepr")) {
+      return request.Approve();
+    }
+
+    // Reject the ConfigMap if it doesn't have the label
+    return request.Deny("ConfigMap must have a unicorn label");
   });
 ```
 
@@ -60,7 +68,7 @@ When(a.ConfigMap)
 ## Wow too many words! tl;dr;
 
 ```bash
-# Initialize a new Pepr Module, you can also use `npx pepr@latest init` to make sure you have the latest version
+# Create a new Pepr Module
 npx pepr init
 
 # If you already have a Kind or K3d cluster you want to use, skip this step
@@ -74,48 +82,38 @@ kubectl apply -f capabilities/hello-pepr.samples.yaml
 # Be amazed and ⭐️ this repo
 ```
 
-Pepr is an open-source project that helps IT Ops teams of all skill levels manage and modify resources in a Kubernetes (K8s) cluster using TypeScript. Kubernetes simplifies the management of multiple computers working together to run and scale applications. Pepr acts as a smart assistant, automatically changing or validating parts of the system as needed.
-
-TypeScript is used to create Pepr capabilities, benefiting from its error-catching and clean code features, but without requiring specialized software engineering experience or prior Typescript knowledge. Pepr also provides a user-friendly interface for writing commands in plain English in a [Fluent Interface](https://en.wikipedia.org/wiki/Fluent_interface) style.
-
-Capabilities are logical groupings of actions, which are the atomic units of change within Pepr. Actions _modify_, _create_, or _interact_ with resources in response to events. Pepr's capabilities and actions work together in the cluster, offering a versatile and customizable tool that enhances Kubernetes by building glue code or plumbing for system interactions. This makes Pepr useful for various tasks such as creating robust policy engines or seamlessly connecting applications.
-
-Imagine Pepr as a smart home system where different devices communicate with each other. Pepr provides instructions, simplifying the management of the smart home. The project enables both expert and novice capability authors to improve management and interactions within the Kubernetes environment, making its features accessible to everyone.
-
 https://user-images.githubusercontent.com/882485/230895880-c5623077-f811-4870-bb9f-9bb8e5edc118.mp4
 
 ## Concepts
 
 ### Module
 
-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 with their own isolated controller.
+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 actions. 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 with their own isolated 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 actions that work together to achieve a specific transformation or operation on Kubernetes resources. Capabilities are user-defined and can include one or more actions. 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
+### Action
+
+Action is a discrete set of behaviors defined in a single function that acts on a given Kubernetes GroupVersionKind (GVK) passed in from Kubernetes. Actions are the atomic operations that are performed on Kubernetes resources by Pepr.
 
-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, an action could be responsible for adding a specific label to a Kubernetes resource, or for modifying a specific field in a resource's metadata. Actions can be grouped together within a Capability to provide a more comprehensive set of operations that can be performed on Kubernetes resources.
 
-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.
+There are both `Mutate()` and `Validate()` Actions that can be used to modify or validate Kubernetes resources.
 
-See [CapabilityActions](./docs/actions.md) for more details.
+See [actions](./docs/actions.md) for more details.
 
 ## Logical Pepr Flow
 
-![Module Diagram](./.images/modules.svg)
+![Arch Diagram](./.images/pepr-arch.svg)
+[Source Diagram](./.images/pepr-arch.svg)
 
 ## TypeScript
 
 [TypeScript](https://www.typescriptlang.org/) is a strongly typed, object-oriented programming language built on top of JavaScript. It provides optional static typing and a rich type system, allowing developers to write more robust code. TypeScript is transpiled to JavaScript, enabling it to run in any environment that supports JavaScript. Pepr allows you to use JavaScript or TypeScript to write capabilities, but TypeScript is recommended for its type safety and rich type system. You can learn more about TypeScript [here](https://www.typescriptlang.org/docs/handbook/typescript-from-scratch.html).
 
-## Kubernetes Mutating Webhooks
-
-[Kubernetes mutating webhooks](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/) are a powerful feature that allows users to intercept and modify Kubernetes API requests, such as resource creation or updates, before they are persisted to the cluster. They can be used to enforce security policies, default values, or perform custom transformations on resources.
-
-Pepr uses Kubernetes mutating webhooks to react to cluster resource events and apply user-defined capabilities, which are sets of Kubernetes transformations/actions.