pepr 0.48.1 → 0.49.0

package/package.json

@@ -16,7 +16,7 @@
     "!src/fixtures/**",
     "!dist/**/*.test.d.ts*"
   ],
-  "version": "0.48.1",
+  "version": "0.49.0",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
   "scripts": {
@@ -54,12 +54,13 @@
     "heredoc": "^1.3.1",
     "http-status-codes": "^2.3.0",
     "json-pointer": "^0.6.2",
-    "kubernetes-fluent-client": "3.4.10",
+    "kubernetes-fluent-client": "3.5.1",
     "pino": "9.6.0",
     "pino-pretty": "13.0.0",
     "prom-client": "15.1.3",
     "ramda": "0.30.1",
-    "sigstore": "3.1.0"
+    "sigstore": "3.1.0",
+    "ts-morph": "^25.0.1"
   },
   "devDependencies": {
     "@commitlint/cli": "19.8.0",
@@ -78,7 +79,7 @@
     "jest": "29.7.0",
     "js-yaml": "^4.1.0",
     "shellcheck": "^3.0.0",
-    "ts-jest": "29.3.1",
+    "ts-jest": "29.3.2",
     "undici": "^7.0.1"
   },
   "overrides": {

package/src/cli/build.helpers.ts

@@ -192,18 +192,23 @@ export async function generateYamlAndWriteToDisk(obj: {
   const yamlFile = `pepr-module-${uuid}.yaml`;
   const chartPath = `${uuid}-chart`;
   const yamlPath = resolve(outputDir, yamlFile);
-  const yaml = await assets.allYaml(generateAllYaml, getDeployment, getWatcher, imagePullSecret);
-  const zarfPath = resolve(outputDir, "zarf.yaml");
+  try {
+    const yaml = await assets.allYaml(generateAllYaml, getDeployment, getWatcher, imagePullSecret);
+    const zarfPath = resolve(outputDir, "zarf.yaml");
+
+    let localZarf = "";
+    if (zarf === "chart") {
+      localZarf = assets.zarfYamlChart(generateZarfYamlGeneric, chartPath);
+    } else {
+      localZarf = assets.zarfYaml(generateZarfYamlGeneric, yamlFile);
+    }
+    await fs.writeFile(yamlPath, yaml);
+    await fs.writeFile(zarfPath, localZarf);
 
-  let localZarf = "";
-  if (zarf === "chart") {
-    localZarf = assets.zarfYamlChart(generateZarfYamlGeneric, chartPath);
-  } else {
-    localZarf = assets.zarfYaml(generateZarfYamlGeneric, yamlFile);
+    await assets.generateHelmChart(webhookConfigGenerator, getWatcher, getModuleSecret, outputDir);
+    console.info(`✅ K8s resource for the module saved to ${yamlPath}`);
+  } catch (error) {
+    console.error(`Error generating YAML: ${error}`);
+    process.exit(1);
   }
-  await fs.writeFile(yamlPath, yaml);
-  await fs.writeFile(zarfPath, localZarf);
-
-  await assets.generateHelmChart(webhookConfigGenerator, getWatcher, getModuleSecret, outputDir);
-  console.info(`✅ K8s resource for the module saved to ${yamlPath}`);
 }

package/src/cli/build.ts

@@ -120,6 +120,12 @@ export default function (program: RootCmd): void {
         ["admin", "scoped"],
       ),
     )
+    .addOption(
+      new Option(
+        "--custom-name [name]",
+        "Specify a custom name for zarf component and service monitors in helm charts.",
+      ),
+    )
     .action(async opts => {
       // assign custom output directory if provided
       outputDir = await handleCustomOutputDir(opts.outputDir);
@@ -127,7 +133,12 @@ export default function (program: RootCmd): void {
       // Build the module
       const buildModuleResult = await buildModule(undefined, opts.entryPoint, opts.embed);
 
-      const { cfg, path, uuid } = buildModuleResult!;
+      const { cfg, path } = buildModuleResult!;
+      // override the name if provided
+      if (opts.customName) {
+        process.env.PEPR_CUSTOM_BUILD_NAME = opts.customName;
+      }
+
       const image = assignImage({
         customImage: opts.customImage,
         registryInfo: opts.registryInfo,
@@ -182,7 +193,7 @@ export default function (program: RootCmd): void {
 
       handleValidCapabilityNames(assets.capabilities);
       await generateYamlAndWriteToDisk({
-        uuid,
+        uuid: cfg.pepr.uuid,
         outputDir,
         imagePullSecret: opts.withPullSecret,
         zarf: opts.zarf,

package/src/cli/crd/create.ts

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { Command } from "commander";
+import { createDirectoryIfNotExists } from "../../lib/filesystemService";
+import { promises as fs } from "fs";
+import path from "path";
+
+// Scaffolds a new CRD TypeScript definition
+const create = new Command("create")
+  .description("Create a new CRD TypeScript definition")
+  .requiredOption("--group <group>", "API group (e.g. cache)")
+  .requiredOption("--version <version>", "API version (e.g. v1alpha1)")
+  .requiredOption("--kind <kind>", "Kind name (e.g. Memcached)")
+  .option("--domain <domain>", "Optional domain (e.g. pepr.dev)", "pepr.dev")
+  .option(
+    "--scope <Namespaced | Cluster>",
+    "Whether the resulting custom resource is cluster- or namespace-scoped",
+    validateScope,
+    "Namespaced",
+  )
+  .option("--plural <plural>", "Plural name (e.g. memcacheds)", "")
+  .option("--shortName <shortName>", "Short name (e.g. mc)", "")
+  .action(async ({ group, version, kind, domain, scope, plural, shortName }) => {
+    console.log("This feature is currently in alpha.\n");
+    const outputDir = path.resolve(`./api/${version}`);
+    await createDirectoryIfNotExists(outputDir);
+
+    // create file in directory with kind
+    await fs.writeFile(
+      `./api/${version}/${kind.toLowerCase()}_types.ts`,
+      generateCRDScaffold(group, version, kind, { domain, scope, plural, shortName }),
+    );
+    console.log(`✔ Created ${kind} TypeScript definition in ${outputDir}`);
+  });
+
+export default create;
+
+export const generateCRDScaffold = (
+  group: string,
+  version: string,
+  kind: string,
+  data: {
+    domain: string;
+    plural: string;
+    scope: string;
+    shortName: string;
+  },
+): string => {
+  return `// Auto-generated CRD TypeScript definition
+// Kind: ${kind}
+// Group: ${group}
+// Version: ${version}
+// Domain: ${data.domain}
+
+export interface ${kind}Spec {
+  // INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
+  // Important: Run "npx pepr crd generate" to regenerate code after modifying this file
+
+  /** 
+   * Size defines the number of Memcache instances 
+   */
+  Size?: number[];
+
+  /** 
+   * Port defines the port that will be used to init the container with the image 
+   */
+  ContainerPort: number;
+
+  /** 
+   * Application specific configuration 
+   */
+  Config?: {
+    language: string[];
+    timezone: number;
+    zone: {
+      state: string;
+      areaCode: string[];
+    };
+  };
+}
+
+export interface ${kind}Status {
+  conditions: ${kind}StatusCondition[];
+}
+
+export const details = {
+  plural: "${data.plural}",
+  scope: "${data.scope}",
+  shortName: "${data.shortName}",
+};
+
+type ${kind}StatusCondition = {
+  /**
+   * lastTransitionTime is the last time the condition transitioned from one status to another. This is not guaranteed to be set in happensBefore order across different conditions for a given object. It may be unset in some circumstances.
+   */
+  lastTransitionTime: Date;
+  /**
+   * message is a human readable message indicating details about the transition. This may be an empty string.
+   */
+  message: string;
+  /**
+   * observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.
+   */
+  observedGeneration?: number;
+  /**
+   * reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.
+   */
+  reason: string;
+  /**
+   * status of the condition, one of True, False, Unknown.
+   */
+  status: string;
+  /**
+   * VM location.
+   */
+  vm: {
+    name: string;
+    region: string;
+    status: string;
+    message: string;
+  }
+};
+
+
+`;
+};
+
+export function validateScope(value: string): "Cluster" | "Namespaced" {
+  if (value !== "Cluster" && value !== "Namespaced") {
+    throw new Error("Scope must be either 'Cluster' or 'Namespaced'");
+  }
+  return value;
+}

package/src/cli/crd/generate.ts

@@ -0,0 +1,317 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { Command } from "commander";
+import fs from "fs";
+import path from "path";
+import { stringify as toYAML } from "yaml";
+import {
+  Project,
+  InterfaceDeclaration,
+  TypeAliasDeclaration,
+  SyntaxKind,
+  Node,
+  SourceFile,
+  Type,
+} from "ts-morph";
+import { createDirectoryIfNotExists } from "../../lib/filesystemService";
+import { kind as k } from "kubernetes-fluent-client";
+import { V1JSONSchemaProps } from "@kubernetes/client-node";
+
+export default new Command("generate")
+  .description("Generate CRD manifests from TypeScript definitions")
+  .option("--output <output>", "Output directory for generated CRDs", "./crds")
+  .action(generateCRDs);
+
+export function extractCRDDetails(
+  content: string,
+  sourceFile: SourceFile,
+): {
+  kind: string | undefined;
+  fqdn: string;
+  scope: "Cluster" | "Namespaced";
+  plural: string;
+  shortNames?: string[];
+} {
+  const kind = extractSingleLineComment(content, "Kind");
+  const group = extractSingleLineComment(content, "Group") ?? "example";
+  const domain = extractSingleLineComment(content, "Domain") ?? "pepr.dev";
+  const details = extractDetails(sourceFile);
+
+  const fqdn = `${group}.${domain}`;
+
+  const { plural, scope } = details;
+
+  const shortNames = details.shortName ? [details.shortName] : undefined;
+  return { kind, plural, scope, shortNames, fqdn };
+}
+
+export async function generateCRDs(options: { output: string }): Promise<void> {
+  console.log("This feature is currently in alpha.\n");
+  const outputDir = path.resolve(options.output);
+  await createDirectoryIfNotExists(outputDir);
+
+  const project = new Project();
+  const apiRoot = path.resolve("api");
+  const versions = getAPIVersions(apiRoot);
+
+  for (const version of versions) {
+    const sourceFiles = loadVersionFiles(project, path.join(apiRoot, version));
+    for (const sourceFile of sourceFiles) {
+      processSourceFile(sourceFile, version, outputDir);
+    }
+  }
+}
+
+export function getAPIVersions(apiRoot: string): string[] {
+  return fs.readdirSync(apiRoot).filter(v => fs.statSync(path.join(apiRoot, v)).isDirectory());
+}
+
+export function loadVersionFiles(project: Project, versionDir: string): SourceFile[] {
+  const files = fs.readdirSync(versionDir).filter(f => f.endsWith(".ts"));
+  const filePaths = files.map(f => path.join(versionDir, f));
+  return project.addSourceFilesAtPaths(filePaths);
+}
+
+export function processSourceFile(
+  sourceFile: SourceFile,
+  version: string,
+  outputDir: string,
+): void {
+  const content = sourceFile.getFullText();
+  const { kind, fqdn, scope, plural, shortNames } = extractCRDDetails(content, sourceFile);
+
+  if (!kind) {
+    console.warn(`Skipping ${sourceFile.getBaseName()}: missing '// Kind: <KindName>' comment`);
+    return;
+  }
+
+  const spec = sourceFile.getInterface(`${kind}Spec`);
+  if (!spec) {
+    console.warn(`Skipping ${sourceFile.getBaseName()}: missing interface ${kind}Spec`);
+    return;
+  }
+
+  const condition = sourceFile.getTypeAlias(`${kind}StatusCondition`);
+  const specSchema = getSchemaFromType(spec);
+  const conditionSchema = condition ? getSchemaFromType(condition) : emptySchema();
+
+  const crd = buildCRD({
+    kind,
+    fqdn,
+    version,
+    plural,
+    scope,
+    shortNames,
+    specSchema,
+    conditionSchema,
+  });
+
+  const outPath = path.join(outputDir, `${kind.toLowerCase()}.yaml`);
+  fs.writeFileSync(outPath, toYAML(crd), "utf8");
+  console.log(`✔ Created ${outPath}`);
+}
+
+// Extracts a comment from the content of a file based on a label.
+export function extractSingleLineComment(content: string, label: string): string | undefined {
+  // https://regex101.com/r/oLFaHP/1
+  const match = content.match(new RegExp(`//\\s+${label}:\\s+(.*)`));
+  return match?.[1].trim();
+}
+
+export function extractDetails(sourceFile: SourceFile): {
+  plural: string;
+  scope: "Cluster" | "Namespaced";
+  shortName: string;
+} {
+  const decl = sourceFile.getVariableDeclaration("details");
+  if (!decl) {
+    throw new Error(`Missing 'details' variable declaration.`);
+  }
+
+  const init = decl.getInitializerIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+
+  const getStr = (key: string): string => {
+    const prop = init.getProperty(key);
+    const value = prop?.getFirstChildByKind(SyntaxKind.StringLiteral)?.getLiteralText();
+    if (!value) {
+      throw new Error(`Missing or invalid value for required key: '${key}'`);
+    }
+    return value;
+  };
+
+  const scope = getStr("scope");
+  if (scope === "Cluster" || scope === "Namespaced") {
+    return {
+      plural: getStr("plural"),
+      scope,
+      shortName: getStr("shortName"),
+    };
+  }
+
+  throw new Error(`'scope' must be either "Cluster" or "Namespaced", got "${scope}"`);
+}
+
+export function getJsDocDescription(node: Node): string {
+  if (!Node.isPropertySignature(node) && !Node.isPropertyDeclaration(node)) return "";
+  return node
+    .getJsDocs()
+    .map(doc => doc.getComment())
+    .filter(Boolean)
+    .join(" ")
+    .trim();
+}
+
+export function getSchemaFromType(decl: InterfaceDeclaration | TypeAliasDeclaration): {
+  properties: Record<string, V1JSONSchemaProps>;
+  required: string[];
+} {
+  const type = decl.getType();
+  const properties: Record<string, V1JSONSchemaProps> = {};
+  const required: string[] = [];
+
+  for (const prop of type.getProperties()) {
+    const name = uncapitalize(prop.getName());
+    const declarations = prop.getDeclarations();
+    if (!declarations.length) continue;
+
+    const declaration = declarations[0];
+    const description = getJsDocDescription(declaration);
+    const valueType = declaration.getType();
+
+    properties[name] = {
+      ...mapTypeToSchema(valueType),
+      ...(description ? { description } : {}),
+    };
+
+    if (!prop.isOptional()) required.push(name);
+  }
+
+  return { properties, required };
+}
+
+export function mapTypeToSchema(type: Type): V1JSONSchemaProps {
+  if (type.getText() === "Date") return { type: "string", format: "date-time" };
+  if (type.isString()) return { type: "string" };
+  if (type.isNumber()) return { type: "number" };
+  if (type.isBoolean()) return { type: "boolean" };
+  if (type.isArray()) {
+    return {
+      type: "array",
+      items: mapTypeToSchema(type.getArrayElementTypeOrThrow()),
+    };
+  }
+
+  if (type.isObject()) return buildObjectSchema(type);
+  return { type: "string" };
+}
+
+export function buildObjectSchema(type: Type): V1JSONSchemaProps {
+  const props: Record<string, V1JSONSchemaProps> = {};
+  const required: string[] = [];
+
+  for (const prop of type.getProperties()) {
+    const name = uncapitalize(prop.getName());
+    const declarations = prop.getDeclarations();
+    if (!declarations.length) continue;
+
+    const decl = declarations[0];
+    const description = getJsDocDescription(decl);
+    const subType = decl.getType();
+
+    props[name] = {
+      ...mapTypeToSchema(subType),
+      ...(description ? { description } : {}),
+    };
+
+    if (!prop.isOptional()) required.push(name);
+  }
+
+  return {
+    type: "object",
+    properties: props,
+    ...(required.length > 0 ? { required } : {}),
+  };
+}
+
+export function uncapitalize(str: string): string {
+  return str.charAt(0).toLowerCase() + str.slice(1);
+}
+
+export function emptySchema(): {
+  properties: Record<string, V1JSONSchemaProps>;
+  required: string[];
+} {
+  return { properties: {}, required: [] };
+}
+
+interface CRDConfig {
+  kind: string;
+  fqdn: string;
+  version: string;
+  plural: string;
+  scope: "Cluster" | "Namespaced";
+  shortNames?: string[];
+  specSchema: ReturnType<typeof getSchemaFromType>;
+  conditionSchema: ReturnType<typeof getSchemaFromType>;
+}
+
+export function buildCRD(config: CRDConfig): k.CustomResourceDefinition {
+  return {
+    apiVersion: "apiextensions.k8s.io/v1",
+    kind: "CustomResourceDefinition",
+    metadata: {
+      name: `${config.plural}.${config.fqdn}`,
+    },
+    spec: {
+      group: config.fqdn,
+      names: {
+        kind: config.kind,
+        plural: config.plural,
+        singular: config.kind.toLowerCase(),
+        ...(config.shortNames ? { shortNames: config.shortNames } : {}),
+      },
+      scope: config.scope,
+      versions: [
+        {
+          name: config.version,
+          served: true,
+          storage: true,
+          schema: {
+            openAPIV3Schema: {
+              type: "object",
+              properties: {
+                spec: {
+                  type: "object",
+                  description: `${config.kind}Spec defines the desired state of ${config.kind}`,
+                  properties: config.specSchema.properties,
+                  required: config.specSchema.required,
+                },
+                status: {
+                  type: "object",
+                  description: `${config.kind}Status defines the observed state of ${config.kind}`,
+                  properties: {
+                    conditions: {
+                      type: "array",
+                      description: "Conditions describing the current state",
+                      items: {
+                        type: "object",
+                        description:
+                          "Condition contains details for one aspect of the current state of this API Resource.",
+                        properties: config.conditionSchema.properties,
+                        required: config.conditionSchema.required,
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          subresources: {
+            status: {},
+          },
+        },
+      ],
+    },
+  };
+}

package/src/cli/crd/index.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { RootCmd } from "../root";
+import createCmd from "./create";
+import generateCmd from "./generate";
+
+export default function (program: RootCmd): void {
+  const crd = program
+    .command("crd")
+    .description("Scaffold and generate Kubernetes CRDs from structured TypeScript definitions");
+
+  crd.addCommand(createCmd);
+  crd.addCommand(generateCmd);
+}

package/src/cli.ts

@@ -15,6 +15,7 @@ import { version } from "./cli/init/templates";
 import { RootCmd } from "./cli/root";
 import update from "./cli/update";
 import kfc from "./cli/kfc";
+import crd from "./cli/crd";
 
 if (process.env.npm_lifecycle_event !== "npx") {
   console.info("Pepr should be run via `npx pepr <command>` instead of `pepr <command>`.");
@@ -25,6 +26,7 @@ if (!process.env.PEPR_NODE_WARNINGS) {
   process.removeAllListeners("warning");
 }
 program
+  .enablePositionalOptions()
   .version(version)
   .description(`Pepr (v${version}) - Type safe K8s middleware for humans`)
   .action(() => {
@@ -47,4 +49,5 @@ format(program);
 monitor(program);
 uuid(program);
 kfc(program);
+crd(program);
 program.parse();

package/src/lib/assets/assets.ts

@@ -128,7 +128,14 @@ export class Assets {
       );
       await fs.writeFile(
         helm.files.admissionServiceMonitorYaml,
-        dedent(serviceMonitorTemplate("admission")),
+        dedent(
+          serviceMonitorTemplate(
+            process.env.PEPR_CUSTOM_BUILD_NAME
+              ? `admission-${process.env.PEPR_CUSTOM_BUILD_NAME}`
+              : "admission",
+            `admission`,
+          ),
+        ),
       );
     }
 
@@ -232,7 +239,14 @@ export class Assets {
         );
         await fs.writeFile(
           helm.files.watcherServiceMonitorYaml,
-          dedent(serviceMonitorTemplate("watcher")),
+          dedent(
+            serviceMonitorTemplate(
+              process.env.PEPR_CUSTOM_BUILD_NAME
+                ? `watcher-${process.env.PEPR_CUSTOM_BUILD_NAME}`
+                : "watcher",
+              `watcher`,
+            ),
+          ),
         );
       }
     } catch (err) {

package/src/lib/assets/helm.ts

@@ -245,22 +245,23 @@ export function admissionDeployTemplate(buildTimestamp: string): string {
               {{- end }}
     `;
 }
-
-export function serviceMonitorTemplate(name: string): string {
+type ControllerType = "admission" | "watcher";
+export function serviceMonitorTemplate(name: string, type: ControllerType): string {
   return `
-      {{- if .Values.${name}.serviceMonitor.enabled }}
+      {{- if .Values.${type}.serviceMonitor.enabled }}
       apiVersion: monitoring.coreos.com/v1
       kind: ServiceMonitor
       metadata:
         name: ${name}
+        namespace: pepr-system
         annotations:
-          {{- toYaml .Values.${name}.serviceMonitor.annotations | nindent 4 }}
+          {{- toYaml .Values.${type}.serviceMonitor.annotations | nindent 4 }}
         labels:
-          {{- toYaml .Values.${name}.serviceMonitor.labels | nindent 4 }}
+          {{- toYaml .Values.${type}.serviceMonitor.labels | nindent 4 }}
       spec:
         selector:
           matchLabels:
-            pepr.dev/controller: ${name}
+            pepr.dev/controller: ${type}
         namespaceSelector:
           matchNames:
             - pepr-system

package/src/lib/assets/pods.ts

@@ -348,8 +348,7 @@ export function getModuleSecret(name: string, data: Buffer, hash: string): kind.
   const compressedData = compressed.toString("base64");
   if (secretOverLimit(compressedData)) {
     const error = new Error(`Module secret for ${name} is over the 1MB limit`);
-    console.error("Uncaught Exception:", error);
-    process.exit(1);
+    throw error;
   } else {
     return {
       apiVersion: "v1",

package/src/lib/assets/yaml/generateZarfYaml.ts

@@ -4,20 +4,21 @@ import { Assets } from "../assets";
 type ConfigType = "manifests" | "charts";
 
 export function generateZarfYamlGeneric(assets: Assets, path: string, type: ConfigType): string {
+  const zarfComponentName = process.env.PEPR_CUSTOM_BUILD_NAME ?? "module";
   const manifestSettings = {
-    name: "module",
+    name: zarfComponentName,
     namespace: "pepr-system",
     files: [path],
   };
   const chartSettings = {
-    name: "module",
+    name: zarfComponentName,
     namespace: "pepr-system",
     version: `${assets.config.appVersion || "0.0.1"}`,
     localPath: path,
   };
 
   const component = {
-    name: "module",
+    name: zarfComponentName,
     required: true,
     images: [assets.image],
     [type]: [type === "manifests" ? manifestSettings : chartSettings],