@appthrust/kest 0.1.0

package/ts/bdd/index.ts

@@ -0,0 +1,30 @@
+const given: Fn =
+  ({ recorder }) =>
+  (description) =>
+    recorder.record("BDDGiven", { description });
+
+const when: Fn =
+  ({ recorder }) =>
+  (description) =>
+    recorder.record("BDDWhen", { description });
+
+const then: Fn =
+  ({ recorder }) =>
+  (description) =>
+    recorder.record("BDDThen", { description });
+
+const and: Fn =
+  ({ recorder }) =>
+  (description) =>
+    recorder.record("BDDAnd", { description });
+
+const but: Fn =
+  ({ recorder }) =>
+  (description) =>
+    recorder.record("BDBut", { description });
+
+type Fn = (env: {
+  readonly recorder: import("../recording").Recorder;
+}) => (description: string) => void;
+
+export default { given, when, then, and, but };

package/ts/duration/index.ts

@@ -0,0 +1,171 @@
+const MS_PER_S = 1_000n;
+const MS_PER_M = 60n * MS_PER_S;
+const MS_PER_H = 60n * MS_PER_M;
+
+function pow10(exp: number): bigint {
+  let x = 1n;
+  for (let i = 0; i < exp; i++) {
+    x *= 10n;
+  }
+  return x;
+}
+
+function parseDecimalToMilliseconds(value: string, unitMs: bigint): bigint {
+  // value is like "12" or "12.34"
+  const dot = value.indexOf(".");
+  if (dot === -1) {
+    return BigInt(value) * unitMs;
+  }
+
+  const intPartStr = value.slice(0, dot);
+  const fracPartStr = value.slice(dot + 1);
+  if (fracPartStr.length === 0) {
+    throw new Error("invalid duration");
+  }
+
+  const intPart = BigInt(intPartStr);
+  const fracScale = pow10(fracPartStr.length);
+  const frac = BigInt(fracPartStr);
+
+  // Truncate toward zero at millisecond precision.
+  return intPart * unitMs + (frac * unitMs) / fracScale;
+}
+
+function unitToMilliseconds(unit: string): bigint {
+  switch (unit) {
+    case "ms":
+      return 1n;
+    case "s":
+      return MS_PER_S;
+    case "m":
+      return MS_PER_M;
+    case "h":
+      return MS_PER_H;
+    default:
+      throw new Error("invalid duration");
+  }
+}
+
+export class Duration {
+  static readonly zero = new Duration(0);
+
+  readonly milliseconds: number;
+
+  constructor(milliseconds: number) {
+    if (!Number.isFinite(milliseconds)) {
+      throw new Error("invalid duration");
+    }
+    if (!Number.isInteger(milliseconds)) {
+      throw new Error("invalid duration");
+    }
+    if (milliseconds < 0) {
+      throw new Error("invalid duration");
+    }
+    this.milliseconds = milliseconds;
+  }
+
+  toMilliseconds(): number {
+    return this.milliseconds;
+  }
+
+  toString(): string {
+    const ms = this.milliseconds;
+    if (ms === 0) {
+      return "0";
+    }
+
+    let absMs = ms;
+    if (absMs < 1000) {
+      return `${absMs}ms`;
+    }
+
+    const MS_PER_S_NUM = 1000;
+    const MS_PER_M_NUM = 60_000;
+    const MS_PER_H_NUM = 3_600_000;
+
+    const hours = Math.floor(absMs / MS_PER_H_NUM);
+    absMs -= hours * MS_PER_H_NUM;
+    const minutes = Math.floor(absMs / MS_PER_M_NUM);
+    absMs -= minutes * MS_PER_M_NUM;
+    const seconds = Math.floor(absMs / MS_PER_S_NUM);
+    const remMs = absMs - seconds * MS_PER_S_NUM;
+
+    let out = "";
+    if (hours > 0) {
+      out += `${hours}h`;
+    }
+    if (minutes > 0) {
+      out += `${minutes}m`;
+    }
+
+    if (seconds > 0 || remMs > 0 || out === "") {
+      if (remMs === 0) {
+        out += `${seconds}s`;
+      } else {
+        const frac = String(remMs).padStart(3, "0").replace(/0+$/, "");
+        out += `${seconds}.${frac}s`;
+      }
+    }
+
+    return out;
+  }
+}
+
+/**
+ * Parses a duration string like Go's time.ParseDuration.
+ *
+ * Examples:
+ * - "300ms"
+ * - "1.5h"
+ * - "-2h45m"
+ * - "1h30m"
+ */
+export function parseDuration(input: string): Duration {
+  if (input.length === 0) {
+    throw new Error("invalid duration");
+  }
+  // Keep it strict (Go-like): no leading/trailing whitespace.
+  if (input.trim() !== input) {
+    throw new Error("invalid duration");
+  }
+
+  if (input[0] === "-" || input[0] === "+") {
+    throw new Error("invalid duration");
+  }
+
+  const s = input;
+
+  if (s === "0") {
+    return Duration.zero;
+  }
+
+  // token: <number><unit>
+  // number: \d+(\.\d+)?
+  // NOTE: millisecond precision for Date interop: no ns/us.
+  const re = /(\d+(?:\.\d+)?)(ms|s|m|h)/gy;
+  let totalMs = 0n;
+  let matchedAny = false;
+  let consumed = 0;
+  while (true) {
+    const m = re.exec(s);
+    if (!m) {
+      break;
+    }
+    matchedAny = true;
+    consumed = re.lastIndex;
+    const value = m[1];
+    const unit = m[2];
+    const unitMs = unitToMilliseconds(unit as string);
+    totalMs += parseDecimalToMilliseconds(value as string, unitMs);
+  }
+
+  if (!matchedAny || consumed !== s.length) {
+    throw new Error("invalid duration");
+  }
+
+  const msNumber = Number(totalMs);
+  if (!Number.isSafeInteger(msNumber)) {
+    throw new Error("invalid duration");
+  }
+  return new Duration(msNumber);
+}

package/ts/index.ts

@@ -0,0 +1,3 @@
+/** biome-ignore-all lint/performance/noBarrelFile: that's ok */
+export type * from "./apis";
+export { test } from "./test";

package/ts/k8s-resource/index.ts

@@ -0,0 +1,120 @@
+import type { K8sResource } from "../apis";
+import { parseYaml } from "../yaml";
+
+export function parseK8sResource(value: unknown): ParseResult<K8sResource> {
+  const violations: Array<string> = [];
+
+  // Check if value is an object
+  if (value === null || typeof value !== "object") {
+    return { ok: false, violations: ["value must be an object"] };
+  }
+
+  const obj = value as Record<string, unknown>;
+
+  // Check apiVersion
+  if (typeof obj["apiVersion"] !== "string" || obj["apiVersion"] === "") {
+    violations.push("apiVersion is required");
+  }
+
+  // Check kind
+  if (typeof obj["kind"] !== "string" || obj["kind"] === "") {
+    violations.push("kind is required");
+  }
+
+  // Check metadata
+  if (obj["metadata"] === null || typeof obj["metadata"] !== "object") {
+    violations.push("metadata is required");
+  } else {
+    const metadata = obj["metadata"] as Record<string, unknown>;
+    if (typeof metadata["name"] !== "string" || metadata["name"] === "") {
+      violations.push("metadata.name is required");
+    }
+  }
+
+  if (violations.length > 0) {
+    return { ok: false, violations };
+  }
+
+  return {
+    ok: true,
+    value: obj as K8sResource,
+  };
+}
+
+export type ParseResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; violations: Array<string> };
+
+export function parseK8sResourceYaml(yaml: string): ParseResult<K8sResource> {
+  const parsed = parseYaml(yaml);
+  return parseK8sResource(parsed);
+}
+
+export function parseK8sResourceList(
+  value: unknown
+): ParseResult<Array<K8sResource>> {
+  if (value === null || typeof value !== "object") {
+    return { ok: false, violations: ["value must be an object"] };
+  }
+
+  const obj = value as Record<string, unknown>;
+  const items = obj["items"];
+  if (!Array.isArray(items)) {
+    return { ok: false, violations: ["items must be an array"] };
+  }
+
+  const violations: Array<string> = [];
+  const parsedItems: Array<K8sResource> = [];
+  for (const [i, item] of items.entries()) {
+    const result = parseK8sResource(item);
+    if (!result.ok) {
+      violations.push(
+        ...result.violations.map((v) => `items[${i}]: ${v}` satisfies string)
+      );
+      continue;
+    }
+    parsedItems.push(result.value);
+  }
+
+  if (violations.length > 0) {
+    return { ok: false, violations };
+  }
+
+  return { ok: true, value: parsedItems };
+}
+
+export function parseK8sResourceListYaml(
+  yaml: string
+): ParseResult<Array<K8sResource>> {
+  const parsed = parseYaml(yaml);
+  return parseK8sResourceList(parsed);
+}
+
+function parseK8sResourceFromESM(esm: ESM): ParseResult<K8sResource> {
+  const result = parseK8sResource(esm.default);
+  if (!result.ok) {
+    return { ok: false, violations: result.violations };
+  }
+  return { ok: true, value: result.value };
+}
+
+export async function parseK8sResourceAny(
+  value: unknown
+): Promise<ParseResult<K8sResource>> {
+  if (typeof value === "string") {
+    return parseK8sResourceYaml(value);
+  }
+  const awatedValue = await value;
+  if (isESM(awatedValue)) {
+    return parseK8sResourceFromESM(awatedValue);
+  }
+  return parseK8sResource(awatedValue);
+}
+
+export interface ESM {
+  readonly default: unknown;
+}
+
+function isESM(value: unknown): value is ESM {
+  return typeof value === "object" && value !== null && "default" in value;
+}

package/ts/kubectl/index.ts

@@ -0,0 +1,351 @@
+import type { K8sResource } from "../apis";
+import type { Recorder } from "../recording";
+import { stringifyYaml } from "../yaml";
+
+export interface KubectlContext {
+  readonly namespace?: undefined | string;
+  readonly context?: undefined | string;
+  readonly kubeconfig?: undefined | string;
+  /**
+   * Field manager name used for server-side apply operations.
+   *
+   * Ref: `kubectl apply --server-side --field-manager=<name>`
+   */
+  readonly fieldManagerName?: undefined | string;
+}
+
+export type KubectlPatch =
+  | Record<string, unknown>
+  | ReadonlyArray<unknown>
+  | string;
+
+export type KubectlPatchType = "json" | "merge" | "strategic";
+
+export interface KubectlPatchOptions {
+  readonly type?: undefined | KubectlPatchType;
+  readonly context?: undefined | KubectlContext;
+}
+
+export interface KubectlDeps {
+  readonly recorder: Recorder;
+  /**
+   * Working directory for kubectl command execution.
+   * Typically scenario/workspace root.
+   */
+  readonly cwd?: undefined | string;
+}
+
+/**
+ * Kubernetes CLI (kubectl) wrapper for executing kubectl commands.
+ */
+export interface Kubectl {
+  /**
+   * Returns a new Kubectl instance with merged context settings.
+   * The returned instance inherits the current default context,
+   * with the provided overrides applied on top.
+   *
+   * @param overrideContext - Context settings to merge (namespace, context, kubeconfig)
+   * @returns A new Kubectl instance with the merged context
+   */
+  extends(overrideContext: KubectlContext): Kubectl;
+
+  /**
+   * Applies a Kubernetes resource using `kubectl apply -f -`.
+   * The resource is serialized to YAML and passed via stdin.
+   *
+   * @param resource - The K8s resource object to apply
+   * @param context - Optional context overrides for this call
+   * @returns The trimmed stdout from kubectl (e.g., "configmap/my-config created")
+   * @throws Error if kubectl exits with non-zero code
+   */
+  apply(resource: K8sResource, context?: KubectlContext): Promise<string>;
+
+  /**
+   * Applies the `status` subresource using server-side apply:
+   *
+   * `kubectl apply --server-side --field-manager=<name> --subresource=status -f -`
+   *
+   * @param resource - The K8s resource object (must include `status`)
+   * @param context - Optional context overrides for this call
+   * @returns The trimmed stdout from kubectl
+   * @throws Error if fieldManagerName is missing or kubectl exits with non-zero code
+   */
+  applyStatus(resource: K8sResource, context?: KubectlContext): Promise<string>;
+
+  /**
+   * Creates a Kubernetes resource using `kubectl create -f -`.
+   * The resource is serialized to YAML and passed via stdin.
+   *
+   * @param resource - The K8s resource object to create
+   * @param context - Optional context overrides for this call
+   * @returns The trimmed stdout from kubectl (e.g., "configmap/my-config created")
+   * @throws Error if kubectl exits with non-zero code
+   */
+  create(resource: K8sResource, context?: KubectlContext): Promise<string>;
+
+  /**
+   * Retrieves a Kubernetes resource using `kubectl get <resource>/<name> -o yaml`.
+   *
+   * @param type - The resource type (e.g., "Pod", "Pod.v1", "Some.v1.custom-resource-group.example.com")
+   * @param name - The name of the resource to get
+   * @param context - Optional context overrides for this call
+   * @returns The resource as YAML string
+   * @throws Error if kubectl exits with non-zero code
+   */
+  get(type: string, name: string, context?: KubectlContext): Promise<string>;
+
+  /**
+   * Lists Kubernetes resources using `kubectl get <resource> -o yaml`.
+   *
+   * @param type - The resource type (e.g., "pods", "deployments.v1.apps")
+   * @param context - Optional context overrides for this call
+   * @returns The resource list as YAML string
+   * @throws Error if kubectl exits with non-zero code
+   */
+  list(type: string, context?: KubectlContext): Promise<string>;
+
+  /**
+   * Patches a Kubernetes resource using `kubectl patch <resource>/<name>`.
+   *
+   * @param resource - The resource type (e.g., "configmap", "deployment.v1.apps")
+   * @param name - The name of the resource to patch
+   * @param patch - Patch body (object/array will be JSON-encoded)
+   * @param options - Optional patch options (type, context)
+   * @returns The trimmed stdout from kubectl (e.g., "configmap/my-config patched")
+   * @throws Error if kubectl exits with non-zero code
+   */
+  patch(
+    resource: string,
+    name: string,
+    patch: KubectlPatch,
+    options?: KubectlPatchOptions
+  ): Promise<string>;
+
+  /**
+   * Deletes a Kubernetes resource using `kubectl delete <resource>/<name>`.
+   *
+   * @param resource - The resource type (e.g., "configmap", "namespace")
+   * @param name - The name of the resource to delete
+   * @param context - Optional context overrides for this call
+   * @returns The trimmed stdout from kubectl (e.g., "configmap \"my-config\" deleted")
+   * @throws Error if kubectl exits with non-zero code
+   */
+  delete(
+    resource: string,
+    name: string,
+    context?: KubectlContext
+  ): Promise<string>;
+}
+
+export class RealKubectl implements Kubectl {
+  private readonly recorder: Recorder;
+  private readonly cwd: undefined | string;
+  private readonly defaultContext: KubectlContext;
+
+  constructor(deps: KubectlDeps, defaultContext: KubectlContext = {}) {
+    this.recorder = deps.recorder;
+    this.cwd = deps.cwd;
+    this.defaultContext = { fieldManagerName: "kest", ...defaultContext };
+  }
+
+  extends(overrideContext: KubectlContext): Kubectl {
+    return new RealKubectl(
+      { recorder: this.recorder, cwd: this.cwd },
+      {
+        ...this.defaultContext,
+        ...overrideContext,
+      }
+    );
+  }
+
+  async apply(
+    resource: K8sResource,
+    context?: KubectlContext
+  ): Promise<string> {
+    const yaml = stringifyYaml(resource);
+    return await this.runKubectl({
+      args: ["apply", "-f", "-"],
+      stdin: { content: yaml, language: "yaml" },
+      stdoutLanguage: "text",
+      stderrLanguage: "text",
+      overrideContext: context,
+    });
+  }
+
+  async applyStatus(
+    resource: K8sResource,
+    context?: KubectlContext
+  ): Promise<string> {
+    const yaml = stringifyYaml(resource);
+    const ctx = { ...this.defaultContext, ...context };
+    const fieldManagerName = ctx.fieldManagerName;
+    if (!fieldManagerName) {
+      throw new Error(
+        "kubectl applyStatus requires `fieldManagerName` to be set"
+      );
+    }
+    return await this.runKubectl({
+      args: [
+        "apply",
+        "--server-side",
+        "--field-manager",
+        fieldManagerName,
+        "--subresource=status",
+        "-f",
+        "-",
+      ],
+      stdin: { content: yaml, language: "yaml" },
+      stdoutLanguage: "text",
+      stderrLanguage: "text",
+      overrideContext: context,
+    });
+  }
+
+  async create(
+    resource: K8sResource,
+    context?: KubectlContext
+  ): Promise<string> {
+    const yaml = stringifyYaml(resource);
+    return await this.runKubectl({
+      args: ["create", "-f", "-"],
+      stdin: { content: yaml, language: "yaml" },
+      stdoutLanguage: "text",
+      stderrLanguage: "text",
+      overrideContext: context,
+    });
+  }
+
+  async get(
+    type: string,
+    name: string,
+    context?: KubectlContext
+  ): Promise<string> {
+    return await this.runKubectl({
+      args: ["get", type, name, "-o", "yaml"],
+      stdoutLanguage: "yaml",
+      stderrLanguage: "text",
+      overrideContext: context,
+    });
+  }
+
+  async list(type: string, context?: KubectlContext): Promise<string> {
+    return await this.runKubectl({
+      args: ["get", type, "-o", "yaml"],
+      stdoutLanguage: "yaml",
+      stderrLanguage: "text",
+      overrideContext: context,
+    });
+  }
+
+  async patch(
+    resource: string,
+    name: string,
+    patch: KubectlPatch,
+    options?: KubectlPatchOptions
+  ): Promise<string> {
+    const patchContent = stringifyPatch(patch);
+    const args = ["patch", `${resource}/${name}`] as [string, ...Array<string>];
+    if (options?.type) {
+      args.push("--type", options.type);
+    }
+    args.push("-p", patchContent);
+    return await this.runKubectl({
+      args,
+      stdoutLanguage: "text",
+      stderrLanguage: "text",
+      overrideContext: options?.context,
+    });
+  }
+
+  async delete(
+    resource: string,
+    name: string,
+    context?: KubectlContext
+  ): Promise<string> {
+    return await this.runKubectl({
+      args: ["delete", `${resource}/${name}`],
+      stdoutLanguage: "text",
+      stderrLanguage: "text",
+      overrideContext: context,
+    });
+  }
+
+  private async runKubectl(params: ExecParams): Promise<string> {
+    const cmd = "kubectl";
+    const ctx = { ...this.defaultContext, ...params.overrideContext };
+    const ctxArgs: Array<string> = [];
+    if (ctx.namespace) {
+      ctxArgs.push("-n", ctx.namespace);
+    }
+    if (ctx.context) {
+      ctxArgs.push("--context", ctx.context);
+    }
+    if (ctx.kubeconfig) {
+      ctxArgs.push("--kubeconfig", ctx.kubeconfig);
+    }
+    const args = [...params.args, ...ctxArgs];
+    const stdin = params.stdin?.content;
+    this.recorder.record("CommandRun", {
+      cmd,
+      args,
+      stdin,
+      stdinLanguage: params.stdin?.language,
+    });
+    const proc = Bun.spawn([cmd, ...args], {
+      ...(this.cwd && { cwd: this.cwd }),
+      stdin: stdin ? new TextEncoder().encode(stdin) : undefined,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    await proc.exited;
+    const { exitCode, stdout, stderr } = {
+      exitCode: proc.exitCode ?? 0,
+      stdout: (await proc.stdout?.text())?.trim() ?? "",
+      stderr: (await proc.stderr?.text())?.trim() ?? "",
+    };
+    this.recorder.record("CommandResult", {
+      exitCode,
+      stdout,
+      stderr,
+      stdoutLanguage: params.stdoutLanguage,
+      stderrLanguage: params.stderrLanguage,
+    });
+    if (exitCode !== 0) {
+      const details = stderr || stdout;
+      const [subcommand] = params.args;
+      throw new Error(
+        `kubectl ${subcommand} failed (exit code ${exitCode})${
+          details ? `: ${details}` : ""
+        }`
+      );
+    }
+    return stdout;
+  }
+}
+
+interface ExecParams {
+  readonly args: readonly [subcommand: string, ...args: ReadonlyArray<string>];
+  readonly stdin?:
+    | undefined
+    | {
+        readonly language?: undefined | string;
+        readonly content: string;
+      };
+  readonly stdoutLanguage?: undefined | string;
+  readonly stderrLanguage?: undefined | string;
+  readonly overrideContext?: undefined | KubectlContext;
+}
+
+function stringifyPatch(patch: KubectlPatch): string {
+  if (typeof patch === "string") {
+    return patch;
+  }
+  return JSON.stringify(patch);
+}
+
+export function createKubectl(
+  deps: KubectlDeps,
+  context: KubectlContext = {}
+): Kubectl {
+  return new RealKubectl(deps, context);
+}