pepr 0.22.4 → 0.23.1

package/README.md

@@ -12,13 +12,11 @@
 
 Pepr is on a mission to save Kubernetes from the tyranny of YAML, intimidating glue code, bash scripts, and other makeshift solutions. As a Kubernetes controller, Pepr empowers you to define Kubernetes transformations using TypeScript, without software development expertise thanks to plain-english configurations. Pepr transforms a patchwork of forks, scripts, overlays, and other chaos into a cohesive, well-structured, and maintainable system. With Pepr, you can seamlessly transition IT ops tribal knowledge into code, simplifying documentation, testing, validation, and coordination of changes for a more predictable outcome.
 
-#### _Note: Pepr is still in active development so breaking changes may occur, but will be documented in release notes._
-
 ## Features
 
 - Zero-config K8s webhook mutations and validations
 - Automatic leader-elected K8s resource watching
-- Lightweight async key-value store backed by K8s for stateful operations with the [Pepr Store](./docs/store.md)
+- Lightweight async key-value store backed by K8s for stateful operations with the [Pepr Store](./docs/030_user-guide/050_store.md)
 - Human-readable fluent API for generating [Pepr Capabilities](#capability)
 - A fluent API for creating/modifying/watching and server-side applying K8s resources via [Kubernetes Fluent Client](https://github.com/defenseunicorns/kubernetes-fluent-client)
 - Generate new K8s resources based off of cluster resource changes
@@ -27,12 +25,12 @@ Pepr is on a mission to save Kubernetes from the tyranny of YAML, intimidating g
 - Entire NPM ecosystem available for advanced operations
 - Realtime K8s debugging system for testing/reacting to cluster changes
 - Controller network isolation and tamper-resistent module execution
-- Least-privilege [RBAC](https://github.com/defenseunicorns/pepr/blob/main/docs/rbac.md) generation
+- Least-privilege [RBAC](./docs/030_user-guide/090_rbac.md) generation
 - AMD64 and ARM64 support
 
 ## 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. It also creates a Validating Webhook to make sure the "pepr" label still exists. Finally, after the ConfigMap is created, it logs a message to the Pepr controller and creates or updates a separate ConfigMap with the [kubernetes-fluent-client](https://github.com/defenseunicorns/kubernetes-fluent-client) using server-side apply. For more details see [actions](./docs/actions.md) section.
+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. It also creates a Validating Webhook to make sure the "pepr" label still exists. Finally, after the ConfigMap is created, it logs a message to the Pepr controller and creates or updates a separate ConfigMap with the [kubernetes-fluent-client](https://github.com/defenseunicorns/kubernetes-fluent-client) using server-side apply. For more details see [actions](./docs/030_user-guide/030_actions.md) section.
 
 ```ts
 When(a.ConfigMap)
@@ -80,9 +78,9 @@ When(a.ConfigMap)
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/en/) v18.0.0+ (even-numbered releases only)
-  - To ensure compatability and optimal performance, it is recommended to use even-numbered releases of Node.js as they are stable releases and receive long-term support for three years. Odd-numbered releases are experimental and may not be supported by certain libraries utilized in Pepr.  
+  - To ensure compatability and optimal performance, it is recommended to use even-numbered releases of Node.js as they are stable releases and receive long-term support for three years. Odd-numbered releases are experimental and may not be supported by certain libraries utilized in Pepr.
 
-- [npm](https://www.npmjs.com/) v10.1.0+  
+- [npm](https://www.npmjs.com/) v10.1.0+
 
 - Recommended (optional) tools:
   - [Visual Studio Code](https://code.visualstudio.com/) for inline debugging and [Pepr Capabilities](#capability) creation.
@@ -113,13 +111,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 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.
+See [Module](./docs/030_user-guide/020_pepr-modules.md) for more details.
 
 ### Capability
 
 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.
+See [Capabilities](./docs/030_user-guide/040_capabilities.md) for more details.
 
 ### Action
 
@@ -129,11 +127,11 @@ For example, an action could be responsible for adding a specific label to a Kub
 
 There are both `Mutate()` and `Validate()` Actions that can be used to modify or validate Kubernetes resources within the admission controller lifecycle. There is also a `Watch()` Action that can be used to watch for changes to Kubernetes resources that already exist.
 
-See [actions](./docs/actions.md) for more details.
+See [actions](./docs/030_user-guide/030_actions.md) for more details.
 
 ## Logical Pepr Flow
 
-![Arch Diagram](./_images/pepr-arch.svg)
+![Arch Diagram](_images/pepr-arch.svg)
 [Source Diagram](_images/pepr-arch.svg)
 
 ## TypeScript

package/dist/cli.js

@@ -1357,7 +1357,7 @@ var gitIgnore = "# Ignore node_modules and Pepr build artifacts\nnode_modules\nd
 var readmeMd = '# Pepr Module\n\nThis is a Pepr Module. [Pepr](https://github.com/defenseunicorns/pepr) is a type-safe Kubernetes middleware system.\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\u251C\u2500\u2500 package.json\n\u251C\u2500\u2500 pepr.ts\n\u2514\u2500\u2500 capabilities\n    \u251C\u2500\u2500 example-one.ts\n    \u251C\u2500\u2500 example-three.ts\n    \u2514\u2500\u2500 example-two.ts\n```\n';
 var peprTS = 'import { PeprModule } from "pepr";\n// cfg loads your pepr configuration from package.json\nimport cfg from "./package.json";\n\n// HelloPepr is a demo capability that is included with Pepr. Comment or delete the line below to remove it.\nimport { HelloPepr } from "./capabilities/hello-pepr";\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(cfg, [\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';
 var helloPeprTS = 'import {\n  Capability,\n  K8s,\n  Log,\n  PeprMutateRequest,\n  RegisterKind,\n  a,\n  fetch,\n  fetchStatus,\n  kind,\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 run `pepr dev`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", "pepr-demo-2"],\n});\n\n// Use the \'When\' function to create a new action, use \'Store\' to persist data\nconst { When, Store } = HelloPepr;\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   Mutate Action (Namespace)                                   *\n * ---------------------------------------------------------------------------------------------------\n *\n * This 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  .Mutate(ns => ns.RemoveLabel("remove-me"));\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   Watch Action with K8s SSA (Namespace)                           *\n * ---------------------------------------------------------------------------------------------------\n *\n * This action watches for the `pepr-demo-2` namespace to be created, then creates a ConfigMap with\n * the name `pepr-ssa-demo` and adds the namespace UID to the ConfigMap data. Because Pepr uses\n * server-side apply for this operation, the ConfigMap will be created or updated if it already exists.\n */\nWhen(a.Namespace)\n  .IsCreated()\n  .WithName("pepr-demo-2")\n  .Watch(async ns => {\n    Log.info("Namespace pepr-demo-2 was created.");\n\n    try {\n      // Apply the ConfigMap using K8s server-side apply\n      await K8s(kind.ConfigMap).Apply({\n        metadata: {\n          name: "pepr-ssa-demo",\n          namespace: "pepr-demo-2",\n        },\n        data: {\n          "ns-uid": ns.metadata.uid,\n        },\n      });\n    } catch (error) {\n      // You can use the Log object to log messages to the Pepr controller pod\n      Log.error(error, "Failed to apply ConfigMap using server-side apply.");\n    }\n\n    // You can share data between actions using the Store, including between different types of actions\n    Store.setItem("watch-data", "This data was stored by a Watch Action.");\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   Mutate Action (CM Example 1)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This is a single 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  .Mutate(request => {\n    request\n      .SetLabel("pepr", "was-here")\n      .SetAnnotation("pepr.dev", "annotations-work-too");\n\n    // Use the Store to persist data between requests and Pepr controller pods\n    Store.setItem("example-1", "was-here");\n\n    // This data is written asynchronously and can be read back via `Store.getItem()` or `Store.subscribe()`\n    Store.setItem("example-1-data", JSON.stringify(request.Raw.data));\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   Mutate & Validate Actions (CM Example 2)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This combines 3 different types of actions: \'Mutate\', \'Validate\', and \'Watch\'. The order\n * of the actions is required, but each action is optional. In this example, when a ConfigMap is created\n * with the name `example-2`, then add a label and annotation, validate that the ConfigMap has the label\n * `pepr`, and log the request.\n */\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithName("example-2")\n  .Mutate(request => {\n    // This Mutate Action will mutate the request before it is persisted to the cluster\n\n    // Use `request.Merge()` to merge the new data with the existing data\n    request.Merge({\n      metadata: {\n        labels: {\n          pepr: "was-here",\n        },\n        annotations: {\n          "pepr.dev": "annotations-work-too",\n        },\n      },\n    });\n  })\n  .Validate(request => {\n    // This Validate Action will validate the request before it is persisted to the cluster\n\n    // Approve the request if the ConfigMap has the label \'pepr\'\n    if (request.HasLabel("pepr")) {\n      return request.Approve();\n    }\n\n    // Otherwise, deny the request with an error message (optional)\n    return request.Deny("ConfigMap must have label \'pepr\'");\n  })\n  .Watch((cm, phase) => {\n    // This Watch Action will watch the ConfigMap after it has been persisted to the cluster\n    Log.info(cm, `ConfigMap was ${phase} with the name example-2`);\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   Mutate Action (CM Example 2a)                               *\n * ---------------------------------------------------------------------------------------------------\n *\n * This action shows a simple validation that will deny any ConfigMap that has the\n * annotation `evil`. Note that the `Deny()` function takes an optional second parameter that is a\n * user-defined status code to return.\n */\nWhen(a.ConfigMap)\n  .IsCreated()\n  .Validate(request => {\n    if (request.HasAnnotation("evil")) {\n      return request.Deny("No evil CM annotations allowed.", 400);\n    }\n\n    return request.Approve();\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   Mutate Action (CM Example 3)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This 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  .Mutate(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// This action validates the label `change=by-label` is deleted\nWhen(a.ConfigMap)\n  .IsDeleted()\n  .WithLabel("change", "by-label")\n  .Validate(request => {\n    // Log and then always approve the request\n    Log.info("CM with label \'change=by-label\' was deleted.");\n    return request.Approve();\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   Mutate Action (CM Example 4)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This action show how you can use the `Mutate()` function without an inline function.\n * This is useful if you want to keep your actions small and focused on a single task,\n * or if you want to reuse the same function in multiple actions.\n */\nWhen(a.ConfigMap).IsCreated().WithName("example-4").Mutate(example4Cb);\n\n// This function uses the complete type definition, but is not required.\nfunction example4Cb(cm: PeprMutateRequest<a.ConfigMap>) {\n  cm.SetLabel("pepr.dev/first", "true");\n  cm.SetLabel("pepr.dev/second", "true");\n  cm.SetLabel("pepr.dev/third", "true");\n}\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   Mutate Action (CM Example 4a)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This is the same as Example 4, except this only operates on a CM in the `pepr-demo-2` namespace.\n * Note because the Capability defines namespaces, the namespace specified here must be one of those.\n * Alternatively, you can remove the namespace from the Capability definition and specify it here.\n */\nWhen(a.ConfigMap)\n  .IsCreated()\n  .InNamespace("pepr-demo-2")\n  .WithName("example-4a")\n  .Mutate(example4Cb);\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   Mutate Action (CM Example 5)                                *\n * ---------------------------------------------------------------------------------------------------\n *\n * This 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 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  .Mutate(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 *                                   Mutate Action (Secret Base64 Handling)                      *\n * ---------------------------------------------------------------------------------------------------\n *\n * The K8s JS client provides incomplete support for base64 encoding/decoding handling for secrets,\n * unlike the GO client. To make this less painful, Pepr automatically handles base64 encoding/decoding\n * secret data before and after the action is executed.\n */\nWhen(a.Secret)\n  .IsCreated()\n  .WithName("secret-1")\n  .Mutate(request => {\n    const secret = request.Raw;\n\n    // This will be encoded at the end of all processing back to base64: "Y2hhbmdlLXdpdGhvdXQtZW5jb2Rpbmc="\n    secret.data.magic = "change-without-encoding";\n\n    // You can modify the data directly, and it will be encoded at the end of all processing\n    secret.data.example += " - modified by Pepr";\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   Mutate 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 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 to 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  .Mutate(request => {\n    request.Merge({\n      spec: {\n        message: "Hello Pepr without type data!",\n        counter: Math.random(),\n      },\n    });\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   Mutate 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 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 actions, but we are putting it here for demonstration purposes.\n *\n * You will need to 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  .Mutate(request => {\n    request.Merge({\n      spec: {\n        message: "Hello Pepr with type data!",\n        counter: Math.random(),\n      },\n    });\n  });\n\n/**\n * A callback function that is called once the Pepr Store is fully loaded.\n */\nStore.onReady(data => {\n  Log.info(data, "Pepr Store Ready");\n});\n';
-var packageJSON = { name: "pepr", description: "Kubernetes application engine", author: "Defense Unicorns", homepage: "https://github.com/defenseunicorns/pepr", license: "Apache-2.0", bin: "dist/cli.js", repository: "defenseunicorns/pepr", engines: { node: ">=18.0.0" }, version: "0.22.4", main: "dist/lib.js", types: "dist/lib.d.ts", scripts: { "gen-data-json": "node hack/build-template-data.js", prebuild: "rm -fr dist/* && npm run gen-data-json", build: "tsc && node build.mjs", test: "npm run test:unit && npm run test:journey", "test:unit": "npm run gen-data-json && jest src --coverage --detectOpenHandles --coverageDirectory=./coverage", "test:journey": "npm run test:journey:k3d && npm run test:journey:build && npm run test:journey:image && npm run test:journey:run", "test:journey:prep": "git clone https://github.com/defenseunicorns/pepr-upgrade-test.git", "test:journey-wasm": "npm run test:journey:k3d && npm run test:journey:build && npm run test:journey:image && npm run test:journey:run-wasm", "test:journey:k3d": "k3d cluster delete pepr-dev && k3d cluster create pepr-dev --k3s-arg '--debug@server:0' --wait && kubectl rollout status deployment -n kube-system", "test:journey:build": "npm run build && npm pack", "test:journey:image": "docker buildx build --tag pepr:dev . && k3d image import pepr:dev -c pepr-dev", "test:journey:run": "jest --detectOpenHandles journey/entrypoint.test.ts && npm run test:journey:prep && npm run test:journey:upgrade", "test:journey:run-wasm": "jest --detectOpenHandles journey/entrypoint-wasm.test.ts", "test:journey:upgrade": "npm run test:journey:k3d && npm run test:journey:image && jest --detectOpenHandles journey/pepr-upgrade.test.ts", "format:check": "eslint src && prettier src --check", "format:fix": "eslint src --fix && prettier src --write" }, dependencies: { "@types/ramda": "0.29.9", express: "4.18.2", "fast-json-patch": "3.1.1", "kubernetes-fluent-client": "2.1.0", pino: "8.17.2", "pino-pretty": "10.3.1", "prom-client": "15.1.0", ramda: "0.29.1" }, devDependencies: { "@commitlint/cli": "18.4.4", "@commitlint/config-conventional": "18.4.4", "@jest/globals": "29.7.0", "@types/eslint": "8.56.2", "@types/express": "4.17.21", "@types/node": "18.x.x", "@types/node-forge": "1.3.11", "@types/prompts": "2.4.9", "@types/uuid": "9.0.7", jest: "29.7.0", nock: "13.5.0", "ts-jest": "29.1.1" }, peerDependencies: { "@typescript-eslint/eslint-plugin": "6.15.0", "@typescript-eslint/parser": "6.15.0", commander: "11.1.0", esbuild: "0.19.10", eslint: "8.56.0", "node-forge": "1.3.1", prettier: "3.1.1", prompts: "2.4.2", typescript: "5.3.3", uuid: "9.0.1" } };
+var packageJSON = { name: "pepr", description: "Kubernetes application engine", author: "Defense Unicorns", homepage: "https://github.com/defenseunicorns/pepr", license: "Apache-2.0", bin: "dist/cli.js", repository: "defenseunicorns/pepr", engines: { node: ">=18.0.0" }, version: "0.23.1", main: "dist/lib.js", types: "dist/lib.d.ts", scripts: { "gen-data-json": "node hack/build-template-data.js", prebuild: "rm -fr dist/* && npm run gen-data-json", build: "tsc && node build.mjs", test: "npm run test:unit && npm run test:journey", "test:unit": "npm run gen-data-json && jest src --coverage --detectOpenHandles --coverageDirectory=./coverage", "test:journey": "npm run test:journey:k3d && npm run test:journey:build && npm run test:journey:image && npm run test:journey:run", "test:journey:prep": "git clone https://github.com/defenseunicorns/pepr-upgrade-test.git", "test:journey-wasm": "npm run test:journey:k3d && npm run test:journey:build && npm run test:journey:image && npm run test:journey:run-wasm", "test:journey:k3d": "k3d cluster delete pepr-dev && k3d cluster create pepr-dev --k3s-arg '--debug@server:0' --wait && kubectl rollout status deployment -n kube-system", "test:journey:build": "npm run build && npm pack", "test:journey:image": "docker buildx build --tag pepr:dev . && k3d image import pepr:dev -c pepr-dev", "test:journey:run": "jest --detectOpenHandles journey/entrypoint.test.ts && npm run test:journey:prep && npm run test:journey:upgrade", "test:journey:run-wasm": "jest --detectOpenHandles journey/entrypoint-wasm.test.ts", "test:journey:upgrade": "npm run test:journey:k3d && npm run test:journey:image && jest --detectOpenHandles journey/pepr-upgrade.test.ts", "format:check": "eslint src && prettier src --check", "format:fix": "eslint src --fix && prettier src --write" }, dependencies: { "@types/ramda": "0.29.10", express: "4.18.2", "fast-json-patch": "3.1.1", "kubernetes-fluent-client": "2.1.0", pino: "8.17.2", "pino-pretty": "10.3.1", "prom-client": "15.1.0", ramda: "0.29.1" }, devDependencies: { "@commitlint/cli": "18.5.0", "@commitlint/config-conventional": "18.5.0", "@jest/globals": "29.7.0", "@types/eslint": "8.56.2", "@types/express": "4.17.21", "@types/node": "18.x.x", "@types/node-forge": "1.3.11", "@types/prompts": "2.4.9", "@types/uuid": "9.0.7", jest: "29.7.0", nock: "13.5.0", "ts-jest": "29.1.2" }, peerDependencies: { "@typescript-eslint/eslint-plugin": "6.15.0", "@typescript-eslint/parser": "6.15.0", commander: "11.1.0", esbuild: "0.19.10", eslint: "8.56.0", "node-forge": "1.3.1", prettier: "3.1.1", prompts: "2.4.2", typescript: "5.3.3", uuid: "9.0.1" } };
 
 // src/templates/pepr.code-snippets.json
 var pepr_code_snippets_default = {
@@ -1871,15 +1871,20 @@ var import_client_node3 = require("@kubernetes/client-node");
 var import_kubernetes_fluent_client4 = require("kubernetes-fluent-client");
 var import_stream = __toESM(require("stream"));
 function monitor_default(program2) {
-  program2.command("monitor <module-uuid>").description("Monitor a Pepr Module").action(async (uuid) => {
+  program2.command("monitor [module-uuid]").description("Monitor a Pepr Module").action(async (uuid) => {
+    let labels;
+    let errorMessage;
     if (!uuid) {
-      console.error("Module UUID is required");
-      process.exit(1);
+      labels = ["pepr.dev/controller", "admission"];
+      errorMessage = `No pods found with admission labels`;
+    } else {
+      labels = ["app", `pepr-${uuid}`];
+      errorMessage = `No pods found for module ${uuid}`;
     }
-    const pods = await (0, import_kubernetes_fluent_client4.K8s)(import_kubernetes_fluent_client4.kind.Pod).InNamespace("pepr-system").WithLabel("app", `pepr-${uuid}`).Get();
+    const pods = await (0, import_kubernetes_fluent_client4.K8s)(import_kubernetes_fluent_client4.kind.Pod).InNamespace("pepr-system").WithLabel(labels[0], labels[1]).Get();
     const podNames = pods.items.flatMap((pod) => pod.metadata.name);
     if (podNames.length < 1) {
-      console.error(`No pods found for module ${uuid}`);
+      console.error(errorMessage);
       process.exit(1);
     }
     const kc = new import_client_node3.KubeConfig();

package/dist/controller.js

@@ -48,7 +48,7 @@ if (process.env.LOG_LEVEL) {
 var logger_default = Log;
 
 // src/templates/data.json
-var packageJSON = { name: "pepr", description: "Kubernetes application engine", author: "Defense Unicorns", homepage: "https://github.com/defenseunicorns/pepr", license: "Apache-2.0", bin: "dist/cli.js", repository: "defenseunicorns/pepr", engines: { node: ">=18.0.0" }, version: "0.22.4", main: "dist/lib.js", types: "dist/lib.d.ts", scripts: { "gen-data-json": "node hack/build-template-data.js", prebuild: "rm -fr dist/* && npm run gen-data-json", build: "tsc && node build.mjs", test: "npm run test:unit && npm run test:journey", "test:unit": "npm run gen-data-json && jest src --coverage --detectOpenHandles --coverageDirectory=./coverage", "test:journey": "npm run test:journey:k3d && npm run test:journey:build && npm run test:journey:image && npm run test:journey:run", "test:journey:prep": "git clone https://github.com/defenseunicorns/pepr-upgrade-test.git", "test:journey-wasm": "npm run test:journey:k3d && npm run test:journey:build && npm run test:journey:image && npm run test:journey:run-wasm", "test:journey:k3d": "k3d cluster delete pepr-dev && k3d cluster create pepr-dev --k3s-arg '--debug@server:0' --wait && kubectl rollout status deployment -n kube-system", "test:journey:build": "npm run build && npm pack", "test:journey:image": "docker buildx build --tag pepr:dev . && k3d image import pepr:dev -c pepr-dev", "test:journey:run": "jest --detectOpenHandles journey/entrypoint.test.ts && npm run test:journey:prep && npm run test:journey:upgrade", "test:journey:run-wasm": "jest --detectOpenHandles journey/entrypoint-wasm.test.ts", "test:journey:upgrade": "npm run test:journey:k3d && npm run test:journey:image && jest --detectOpenHandles journey/pepr-upgrade.test.ts", "format:check": "eslint src && prettier src --check", "format:fix": "eslint src --fix && prettier src --write" }, dependencies: { "@types/ramda": "0.29.9", express: "4.18.2", "fast-json-patch": "3.1.1", "kubernetes-fluent-client": "2.1.0", pino: "8.17.2", "pino-pretty": "10.3.1", "prom-client": "15.1.0", ramda: "0.29.1" }, devDependencies: { "@commitlint/cli": "18.4.4", "@commitlint/config-conventional": "18.4.4", "@jest/globals": "29.7.0", "@types/eslint": "8.56.2", "@types/express": "4.17.21", "@types/node": "18.x.x", "@types/node-forge": "1.3.11", "@types/prompts": "2.4.9", "@types/uuid": "9.0.7", jest: "29.7.0", nock: "13.5.0", "ts-jest": "29.1.1" }, peerDependencies: { "@typescript-eslint/eslint-plugin": "6.15.0", "@typescript-eslint/parser": "6.15.0", commander: "11.1.0", esbuild: "0.19.10", eslint: "8.56.0", "node-forge": "1.3.1", prettier: "3.1.1", prompts: "2.4.2", typescript: "5.3.3", uuid: "9.0.1" } };
+var packageJSON = { name: "pepr", description: "Kubernetes application engine", author: "Defense Unicorns", homepage: "https://github.com/defenseunicorns/pepr", license: "Apache-2.0", bin: "dist/cli.js", repository: "defenseunicorns/pepr", engines: { node: ">=18.0.0" }, version: "0.23.1", main: "dist/lib.js", types: "dist/lib.d.ts", scripts: { "gen-data-json": "node hack/build-template-data.js", prebuild: "rm -fr dist/* && npm run gen-data-json", build: "tsc && node build.mjs", test: "npm run test:unit && npm run test:journey", "test:unit": "npm run gen-data-json && jest src --coverage --detectOpenHandles --coverageDirectory=./coverage", "test:journey": "npm run test:journey:k3d && npm run test:journey:build && npm run test:journey:image && npm run test:journey:run", "test:journey:prep": "git clone https://github.com/defenseunicorns/pepr-upgrade-test.git", "test:journey-wasm": "npm run test:journey:k3d && npm run test:journey:build && npm run test:journey:image && npm run test:journey:run-wasm", "test:journey:k3d": "k3d cluster delete pepr-dev && k3d cluster create pepr-dev --k3s-arg '--debug@server:0' --wait && kubectl rollout status deployment -n kube-system", "test:journey:build": "npm run build && npm pack", "test:journey:image": "docker buildx build --tag pepr:dev . && k3d image import pepr:dev -c pepr-dev", "test:journey:run": "jest --detectOpenHandles journey/entrypoint.test.ts && npm run test:journey:prep && npm run test:journey:upgrade", "test:journey:run-wasm": "jest --detectOpenHandles journey/entrypoint-wasm.test.ts", "test:journey:upgrade": "npm run test:journey:k3d && npm run test:journey:image && jest --detectOpenHandles journey/pepr-upgrade.test.ts", "format:check": "eslint src && prettier src --check", "format:fix": "eslint src --fix && prettier src --write" }, dependencies: { "@types/ramda": "0.29.10", express: "4.18.2", "fast-json-patch": "3.1.1", "kubernetes-fluent-client": "2.1.0", pino: "8.17.2", "pino-pretty": "10.3.1", "prom-client": "15.1.0", ramda: "0.29.1" }, devDependencies: { "@commitlint/cli": "18.5.0", "@commitlint/config-conventional": "18.5.0", "@jest/globals": "29.7.0", "@types/eslint": "8.56.2", "@types/express": "4.17.21", "@types/node": "18.x.x", "@types/node-forge": "1.3.11", "@types/prompts": "2.4.9", "@types/uuid": "9.0.7", jest: "29.7.0", nock: "13.5.0", "ts-jest": "29.1.2" }, peerDependencies: { "@typescript-eslint/eslint-plugin": "6.15.0", "@typescript-eslint/parser": "6.15.0", commander: "11.1.0", esbuild: "0.19.10", eslint: "8.56.0", "node-forge": "1.3.1", prettier: "3.1.1", prompts: "2.4.2", typescript: "5.3.3", uuid: "9.0.1" } };
 
 // src/runtime/controller.ts
 var { version } = packageJSON;

package/package.json

@@ -9,7 +9,7 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "version": "0.22.4",
+  "version": "0.23.1",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
   "scripts": {
@@ -31,7 +31,7 @@
     "format:fix": "eslint src --fix && prettier src --write"
   },
   "dependencies": {
-    "@types/ramda": "0.29.9",
+    "@types/ramda": "0.29.10",
     "express": "4.18.2",
     "fast-json-patch": "3.1.1",
     "kubernetes-fluent-client": "2.1.0",
@@ -41,8 +41,8 @@
     "ramda": "0.29.1"
   },
   "devDependencies": {
-    "@commitlint/cli": "18.4.4",
-    "@commitlint/config-conventional": "18.4.4",
+    "@commitlint/cli": "18.5.0",
+    "@commitlint/config-conventional": "18.5.0",
     "@jest/globals": "29.7.0",
     "@types/eslint": "8.56.2",
     "@types/express": "4.17.21",
@@ -52,7 +52,7 @@
     "@types/uuid": "9.0.7",
     "jest": "29.7.0",
     "nock": "13.5.0",
-    "ts-jest": "29.1.1"
+    "ts-jest": "29.1.2"
   },
   "peerDependencies": {
     "@typescript-eslint/eslint-plugin": "6.15.0",

package/BEST_PRACTICES.md

@@ -1,37 +0,0 @@
-# Pepr Best Practices (WIP)
-
-## TOC
-
-- [Store](#pepr-store)
-- [OnSchedule](#onschedule)
-- [Watch](#watch)
-
-
-## Pepr Store
-
-The store is backed by ETCD in a `PeprStore` resource, and updates happen at 5-second intervals when an array of patches is sent to the Kubernetes API Server. The store is intentionally not designed to be `transactional`; instead, it is built to be eventually consistent, meaning that the last operation within the interval will be persisted, potentially overwriting other operations. In simpler terms, changes to the data are made without a guarantee that they will occur simultaneously, so caution is needed in managing errors and ensuring consistency.  
-
-
-## OnSchedule
-
-`OnSchedule` is supported by a `PeprStore` to safeguard against schedule loss following a pod restart. It is utilized at the top level, distinct from being within a `Validate`, `Mutate`, or `Watch`. Recommended intervals are 30 seconds or longer, and jobs are advised to be idempotent, meaning that if the code is applied or executed multiple times, the outcome should be the same as if it had been executed only once. A major use-case for `OnSchedule` is day 2 operations.
-
-## Watch
-
-Pepr streamlines the process of receiving timely change notifications on resources by employing the `Watch` mechanism. It is advisable to opt for `Watch` over `Mutate` or `Validate` when dealing with more extended operations, as `Watch` does not face any [timeout limitations](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#timeouts). Additionally, `Watch` proves particularly advantageous for monitoring previously existing resources within a cluster. One compelling scenario for leveraging `Watch` is when there is a need to chain API calls together, allowing `Watch` operations to be sequentially executed following `Mutate` and `Validate` actions.
-
-```typescript
-When(a.Pod)
-  .IsCreated()
-  .InNamespace("my-app")
-  .WithName("database")
-  .Mutate(pod => // .... )
-  .Validate(pod => // .... )
-  .Watch(async (pod, phase) => {
-    Log.info(pod, `Pod was ${phase}.`);
-
-    // do consecutive api calls
-```
-
-
-[TOP](#pepr-best-practices)

package/CODE_OF_CONDUCT.md

@@ -1,83 +0,0 @@
-
-# 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

@@ -1,70 +0,0 @@
-
-
-# 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.
-