pepr 0.1.30 → 0.1.32

package/README.md

@@ -18,6 +18,8 @@ Capabilities are logical groupings of actions, which are the atomic units of cha
 
 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
@@ -26,7 +28,7 @@ A module is the top-level collection of capabilities. It is a single, complete T
 
 ### 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. 
 
 ### CapabilityAction
 
@@ -36,26 +38,22 @@ For example, a CapabilityAction could be responsible for adding a specific label
 
 ## Example
 
-Define a new capability:
-
-```
-pepr new hello-world -d demo
-```
+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.
 
-This will create a new directory tree called `demo/hello-world` with the following structure:
+https://user-images.githubusercontent.com/882485/230897379-0bb57dff-9832-479f-8733-79e103703135.mp4
 
-### demo/hello-world/index.ts
+Alternatively, you can use the `pepr new <capability-name>` command to this:
 
-```typescript
-import "./test-mutations";
+```
+pepr new hello-world
 ```
 
-### demo/hello-world/index.ts
+This will create a new file called `capabilities/hello-world.ts` with the following contents:
 
 ```typescript
 import { Capability, a } from "pepr";
 
-const { When } = new Capability({
+export const HelloWorld = new Capability({
   // The unique name of the capability
   name: "hello-world",
   // A short description of the capability
@@ -63,6 +61,9 @@ const { When } = new Capability({
   // 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:

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pepr",
-    "version": "0.1.30",
+    "version": "0.1.32",
     "description": "Kubernetes application engine",
     "author": "Defense Unicorns",
     "homepage": "https://github.com/defenseunicorns/pepr",

package/dist/src/cli/index.js

@@ -26,8 +26,9 @@ program
 });
 (0, init_1.default)(program);
 (0, build_1.default)(program);
-(0, capability_1.default)(program);
-(0, test_1.default)(program);
 (0, deploy_1.default)(program);
 (0, dev_1.default)(program);
+// @todo: finish/re-evaluate these commands
+(0, test_1.default)(program);
+(0, capability_1.default)(program);
 program.parse();

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

@@ -15,7 +15,9 @@ function default_1(program) {
     program
         .command("init")
         .description("Initialize a new Pepr Module")
-        .action(async () => {
+        // skip auto npm install and git init
+        .option("--skip-post-init", "Skip npm install, git init and VSCode launch")
+        .action(async (opts) => {
         const response = await (0, walkthrough_1.walkthrough)();
         const dirName = (0, utils_1.sanitizeName)(response.name);
         const packageJSON = (0, templates_1.genPkgJSON)(response);
@@ -33,13 +35,29 @@ function default_1(program) {
                 await (0, utils_1.write)((0, path_1.resolve)(dirName, templates_1.readme.path), templates_1.readme.data);
                 await (0, utils_1.write)((0, path_1.resolve)(dirName, templates_1.tsConfig.path), templates_1.tsConfig.data);
                 await (0, utils_1.write)((0, path_1.resolve)(dirName, peprTS.path), peprTS.data);
-                await (0, utils_1.write)((0, path_1.resolve)(dirName, ".vscode", templates_1.capabilitySnippet.path), templates_1.capabilitySnippet.data);
-                await (0, utils_1.write)((0, path_1.resolve)(dirName, "capabilities", templates_1.capabilityHelloPeprTS.path), templates_1.capabilityHelloPeprTS.data);
-                // run npm install from the new directory
-                process.chdir(dirName);
-                (0, child_process_1.execSync)("npm install", {
-                    stdio: "inherit",
-                });
+                await (0, utils_1.write)((0, path_1.resolve)(dirName, ".vscode", templates_1.snippet.path), templates_1.snippet.data);
+                await (0, utils_1.write)((0, path_1.resolve)(dirName, "capabilities", templates_1.samplesYaml.path), templates_1.samplesYaml.data);
+                await (0, utils_1.write)((0, path_1.resolve)(dirName, "capabilities", templates_1.helloPeprTS.path), templates_1.helloPeprTS.data);
+                if (!opts.skipPostInit) {
+                    // run npm install from the new directory
+                    process.chdir(dirName);
+                    (0, child_process_1.execSync)("npm install", {
+                        stdio: "inherit",
+                    });
+                    // setup git
+                    (0, child_process_1.execSync)("git init", {
+                        stdio: "inherit",
+                    });
+                    // try to open vscode
+                    try {
+                        (0, child_process_1.execSync)("code .", {
+                            stdio: "inherit",
+                        });
+                    }
+                    catch (e) {
+                        // vscode not found, do nothing
+                    }
+                }
                 console.log(`New Pepr module created at ${dirName}`);
                 console.log(`Open VSCode or your editor of choice in ${dirName} to get started!`);
             }

package/dist/src/cli/init/templates.d.ts

@@ -72,11 +72,15 @@ export declare const readme: {
     path: string;
     data: string;
 };
-export declare const capabilityHelloPeprTS: {
+export declare const samplesYaml: {
     path: string;
     data: string;
 };
-export declare const capabilitySnippet: {
+export declare const helloPeprTS: {
+    path: string;
+    data: string;
+};
+export declare const snippet: {
     path: string;
     data: string;
 };

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

@@ -2,11 +2,12 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.capabilitySnippet = exports.capabilityHelloPeprTS = exports.readme = exports.prettierRC = exports.gitIgnore = exports.tsConfig = exports.genPkgJSON = exports.genPeprTS = void 0;
+exports.snippet = exports.helloPeprTS = exports.samplesYaml = exports.readme = exports.prettierRC = exports.gitIgnore = exports.tsConfig = exports.genPkgJSON = exports.genPeprTS = void 0;
 const util_1 = require("util");
 const uuid_1 = require("uuid");
 const package_json_1 = require("../../../package.json");
 const utils_1 = require("./utils");
+const client_node_1 = require("@kubernetes/client-node");
 function genPeprTS() {
     return {
         path: "pepr.ts",
@@ -23,7 +24,7 @@ new PeprModule(cfg, [
   HelloPepr,
 
   // Your additional capabilities go here
-]);    
+]);
 `,
     };
 }
@@ -85,9 +86,10 @@ exports.tsConfig = {
 };
 exports.gitIgnore = {
     path: ".gitignore",
-    data: `# Ignore node_modules
-  node_modules
-  dist
+    data: `# Ignore node_modules and Pepr build artifacts
+node_modules
+dist
+insecure*
 `,
 };
 exports.prettierRC = {
@@ -131,10 +133,65 @@ Module Root
 \`\`\`
 `,
 };
-exports.capabilityHelloPeprTS = {
+exports.samplesYaml = {
+    path: "hello-pepr.samples.yaml",
+    data: [
+        {
+            apiVersion: "v1",
+            kind: "Namespace",
+            metadata: {
+                name: "pepr-demo",
+            },
+        },
+        {
+            apiVersion: "v1",
+            kind: "ConfigMap",
+            metadata: {
+                name: "example-1",
+                namespace: "pepr-demo",
+            },
+            data: {
+                key: "ex-1-val",
+            },
+        },
+        {
+            apiVersion: "v1",
+            kind: "ConfigMap",
+            metadata: {
+                name: "example-2",
+                namespace: "pepr-demo",
+            },
+            data: {
+                key: "ex-2-val",
+            },
+        },
+        {
+            apiVersion: "v1",
+            kind: "ConfigMap",
+            metadata: {
+                name: "example-3",
+                namespace: "pepr-demo",
+                labels: {
+                    change: "by-label",
+                },
+            },
+            data: {
+                key: "ex-3-val",
+            },
+        },
+    ]
+        .map(r => (0, client_node_1.dumpYaml)(r, { noRefs: true }))
+        .join("---\n"),
+};
+exports.helloPeprTS = {
     path: "hello-pepr.ts",
     data: `import { Capability, a } from "pepr";
 
+/**
+ *  The HelloPepr is an example capability to demonstrate some general concepts of Pepr.
+ *  To test this capability you can run \`pepr dev\` and then run the following command:
+ *  \`kubectl apply -f capabilities/hello-pepr.samples.yaml\`
+ */ 
 export const HelloPepr = new Capability({
   name: "hello-pepr",
   description: "A simple example capability to show how things work.",
@@ -181,11 +238,12 @@ When(a.ConfigMap)
 
 /**
  * This Capability Action combines different styles. Unlike the previous actions, this one will look for any ConfigMap
- * in the \`pepr-demo\` namespace that has the label \`change=by-label\`. Note that all conditions added such as \`WithName()\`,
- * \`WithLabel()\`, \`InNamespace()\`, are ANDs so all conditions must be true for the request to be procssed.
+ * in the \`pepr-demo\` namespace that has the label \`change=by-label\` during either CREATE or UPDATE. Note that all 
+ * conditions added such as \`WithName()\`, \`WithLabel()\`, \`InNamespace()\`, are ANDs so all conditions must be true 
+ * for the request to be procssed.
  */
 When(a.ConfigMap)
-  .IsCreated()
+  .IsCreatedOrUpdated()
   .WithLabel("change", "by-label")
   .Then(request => {
     // The K8s object e are going to mutate
@@ -203,7 +261,7 @@ When(a.ConfigMap)
   });    
 `,
 };
-exports.capabilitySnippet = {
+exports.snippet = {
     path: "pepr.code-snippets",
     data: `{
   "Create a new Pepr capability": {

package/dist/src/lib/controller.js

@@ -53,17 +53,13 @@ class Controller {
                 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`);
-                // @todo: make this actually do something
                 const response = (0, processor_1.processor)(this.config, this.capabilities, req.body.request);
                 console.debug(response);
                 // Send a no prob bob response
                 res.send({
                     apiVersion: "admission.k8s.io/v1",
                     kind: "AdmissionReview",
-                    response: {
-                        uid: req.body.request.uid,
-                        allowed: true,
-                    },
+                    response,
                 });
             }
             catch (err) {

package/dist/src/lib/processor.js

@@ -14,7 +14,6 @@ function processor(config, capabilities, req) {
     const wrapped = new request_1.RequestWrapper(req);
     const response = {
         uid: req.uid,
-        patchType: "JSONPatch",
         warnings: [],
         allowed: false,
     };
@@ -61,6 +60,7 @@ function processor(config, capabilities, req) {
     const patches = (0, fast_json_patch_1.compare)(req.object, wrapped.Raw);
     // Only add the patch if there are patches to apply
     if (patches.length > 0) {
+        response.patchType = "JSONPatch";
         response.patch = JSON.stringify(patches);
     }
     // Remove the warnings array if it's empty

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pepr",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "Kubernetes application engine",
   "author": "Defense Unicorns",
   "homepage": "https://github.com/defenseunicorns/pepr",

package/cli.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-
-import "./src/cli";