pepr 0.48.1-nightly.10 → 0.48.1-nightly.12

package/package.json

@@ -16,7 +16,7 @@
     "!src/fixtures/**",
     "!dist/**/*.test.d.ts*"
   ],
-  "version": "0.48.1-nightly.10",
+  "version": "0.48.1-nightly.12",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
   "scripts": {
@@ -59,7 +59,8 @@
     "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",

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/controller/createHooks.ts

@@ -0,0 +1,34 @@
+import { ControllerHooks } from ".";
+import { resolveIgnoreNamespaces } from "../assets/webhooks";
+import { Capability } from "../core/capability";
+import { isWatchMode, isDevMode } from "../core/envChecks";
+import { setupWatch } from "../processors/watch-processor";
+import { PeprModuleOptions } from "../types";
+
+/**
+ * Creates controller hooks with proper handling of watch setup
+ *
+ * @param opts Module options including hooks
+ * @param capabilities List of capabilities
+ * @param ignoreNamespaces Namespaces to ignore
+ * @returns Controller hooks configuration
+ */
+export function createControllerHooks(
+  opts: PeprModuleOptions,
+  capabilities: Capability[],
+  ignoreNamespaces: string[] = [],
+): ControllerHooks {
+  return {
+    beforeHook: opts.beforeHook,
+    afterHook: opts.afterHook,
+    onReady: async (): Promise<void> => {
+      if (isWatchMode() || isDevMode()) {
+        try {
+          setupWatch(capabilities, resolveIgnoreNamespaces(ignoreNamespaces));
+        } catch (error) {
+          throw new Error(`WatchError: Could not set up watch.`, { cause: error });
+        }
+      }
+    },
+  };
+}

package/src/lib/core/module.ts

@@ -2,14 +2,12 @@
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 import { clone } from "ramda";
 import { Capability } from "./capability";
-import { Controller, ControllerHooks } from "../controller";
+import { Controller } from "../controller";
 import { ValidateError } from "../errors";
 import { CapabilityExport } from "../types";
-import { setupWatch } from "../processors/watch-processor";
-import Log from "../../lib/telemetry/logger";
-import { resolveIgnoreNamespaces } from "../assets/webhooks";
-import { isBuildMode, isDevMode, isWatchMode } from "./envChecks";
+import { isBuildMode } from "./envChecks";
 import { PackageJSON, PeprModuleOptions, ModuleConfig } from "../types";
+import { createControllerHooks } from "../controller/createHooks";
 
 export class PeprModule {
   #controller!: Controller;
@@ -59,21 +57,11 @@ export class PeprModule {
       return;
     }
 
-    const controllerHooks: ControllerHooks = {
-      beforeHook: opts.beforeHook,
-      afterHook: opts.afterHook,
-      onReady: async (): Promise<void> => {
-        // Wait for the controller to be ready before setting up watches
-        if (isWatchMode() || isDevMode()) {
-          try {
-            setupWatch(capabilities, resolveIgnoreNamespaces(pepr?.alwaysIgnore?.namespaces));
-          } catch (e) {
-            Log.error(e, "Error setting up watch");
-            process.exit(1);
-          }
-        }
-      },
-    };
+    const controllerHooks = createControllerHooks(
+      opts,
+      capabilities,
+      pepr?.alwaysIgnore?.namespaces,
+    );
 
     this.#controller = new Controller(config, capabilities, controllerHooks);