@nexusgpu/repterm-plugin-kubectl 0.1.0

package/dist/matchers.js

@@ -0,0 +1,527 @@
+/**
+ * Kubernetes Matchers for Repterm
+ *
+ * Provides expect() matchers for Kubernetes resources.
+ * All operations are executed through kubectl API (PTY visible).
+ *
+ * @packageDocumentation
+ */
+import { expect } from 'bun:test';
+import { KubectlResult } from './result.js';
+// ===== K8sResource Wrapper =====
+/**
+ * Wrapper class for Kubernetes resources
+ * Holds reference to kubectl methods for matcher operations
+ */
+export class K8sResource {
+    kubectl;
+    kind;
+    name;
+    constructor(kubectl, kind, name) {
+        this.kubectl = kubectl;
+        this.kind = kind;
+        this.name = name;
+    }
+}
+// ===== Helper Functions =====
+/**
+ * Create a Pod resource wrapper
+ */
+export function pod(kubectl, name) {
+    return new K8sResource(kubectl, 'pod', name);
+}
+/**
+ * Create a Deployment resource wrapper
+ */
+export function deployment(kubectl, name) {
+    return new K8sResource(kubectl, 'deployment', name);
+}
+/**
+ * Create a Service resource wrapper
+ */
+export function service(kubectl, name) {
+    return new K8sResource(kubectl, 'service', name);
+}
+/**
+ * Create a StatefulSet resource wrapper
+ */
+export function statefulset(kubectl, name) {
+    return new K8sResource(kubectl, 'statefulset', name);
+}
+/**
+ * Create a Job resource wrapper
+ */
+export function job(kubectl, name) {
+    return new K8sResource(kubectl, 'job', name);
+}
+/**
+ * Create a ConfigMap resource wrapper
+ */
+export function configmap(kubectl, name) {
+    return new K8sResource(kubectl, 'configmap', name);
+}
+/**
+ * Create a Secret resource wrapper
+ */
+export function secret(kubectl, name) {
+    return new K8sResource(kubectl, 'secret', name);
+}
+/**
+ * Create a generic resource wrapper
+ */
+export function resource(kubectl, kind, name) {
+    return new K8sResource(kubectl, kind, name);
+}
+// ===== Tensor Fusion CRD Wrappers =====
+/**
+ * Create a GPUPool resource wrapper (Tensor Fusion CRD)
+ */
+export function gpupool(kubectl, name) {
+    return new K8sResource(kubectl, 'gpupool', name);
+}
+/**
+ * Create a GPU resource wrapper (Tensor Fusion CRD)
+ */
+export function gpu(kubectl, name) {
+    return new K8sResource(kubectl, 'gpu', name);
+}
+/**
+ * Create a TensorFusionWorkload resource wrapper (Tensor Fusion CRD)
+ */
+export function tensorfusionworkload(kubectl, name) {
+    return new K8sResource(kubectl, 'tensorfusionworkload', name);
+}
+/**
+ * Create a TensorFusionConnection resource wrapper (Tensor Fusion CRD)
+ */
+export function tensorfusionconnection(kubectl, name) {
+    return new K8sResource(kubectl, 'tensorfusionconnection', name);
+}
+/**
+ * Create a custom CRD resource wrapper with explicit API group
+ * @param kubectl - kubectl methods instance
+ * @param kind - Resource kind (e.g., 'gpupool.tensor-fusion.ai')
+ * @param name - Resource name
+ */
+export function crd(kubectl, kind, name) {
+    return new K8sResource(kubectl, kind, name);
+}
+// ===== Type Guard =====
+function isK8sResource(value) {
+    return value instanceof K8sResource;
+}
+function isKubectlResult(value) {
+    return value instanceof KubectlResult;
+}
+// ===== Register Matchers =====
+/**
+ * Register K8s matchers with expect
+ */
+export function registerK8sMatchers() {
+    expect.extend({
+        /**
+         * Assert that a kubectl operation succeeded
+         */
+        async toBeSuccessful(received) {
+            if (!isKubectlResult(received)) {
+                return {
+                    pass: false,
+                    message: () => 'Expected value to be a KubectlResult (from kubectl.apply/delete/patch/scale/label)',
+                };
+            }
+            const pass = received.successful;
+            return {
+                pass,
+                message: () => pass
+                    ? 'Expected kubectl command to fail, but it succeeded'
+                    : `Expected kubectl command to succeed, but failed:\n${received.output.slice(0, 500)}`,
+                actual: pass ? 'succeeded' : 'failed',
+                expected: 'succeeded',
+            };
+        },
+        /**
+         * Assert that a Pod is in Running state
+         */
+        async toBeRunning(received, ...args) {
+            const timeout = args[0] ?? 60000;
+            if (!isK8sResource(received)) {
+                return {
+                    pass: false,
+                    message: () => 'Expected value to be a K8sResource',
+                };
+            }
+            const { kubectl, kind, name } = received;
+            if (kind !== 'pod') {
+                return {
+                    pass: false,
+                    message: () => `toBeRunning() is only valid for pods, got ${kind}`,
+                };
+            }
+            try {
+                await kubectl.waitForPod(name, 'Running', timeout);
+                return {
+                    pass: true,
+                    message: () => `Expected pod/${name} not to be Running`,
+                };
+            }
+            catch {
+                return {
+                    pass: false,
+                    message: () => `Expected pod/${name} to be Running within ${timeout}ms`,
+                    actual: 'Not Running',
+                    expected: 'Running',
+                };
+            }
+        },
+        /**
+         * Assert that a Pod has a specific phase
+         */
+        async toHavePhase(received, ...args) {
+            const phase = args[0];
+            if (!isK8sResource(received)) {
+                return {
+                    pass: false,
+                    message: () => 'Expected value to be a K8sResource',
+                };
+            }
+            const { kubectl, kind, name } = received;
+            try {
+                const actualPhase = await kubectl.getJsonPath(kind, name, '.status.phase');
+                const pass = actualPhase === phase;
+                return {
+                    pass,
+                    message: () => pass
+                        ? `Expected ${kind}/${name} not to have phase ${phase}`
+                        : `Expected ${kind}/${name} to have phase ${phase}, got ${actualPhase}`,
+                    actual: actualPhase,
+                    expected: phase,
+                };
+            }
+            catch (e) {
+                return {
+                    pass: false,
+                    message: () => `Failed to get ${kind}/${name}: ${e}`,
+                };
+            }
+        },
+        /**
+         * Assert that a resource has a specific number of replicas
+         */
+        async toHaveReplicas(received, ...args) {
+            const count = args[0];
+            if (!isK8sResource(received)) {
+                return {
+                    pass: false,
+                    message: () => 'Expected value to be a K8sResource',
+                };
+            }
+            const { kubectl, kind, name } = received;
+            try {
+                const actual = await kubectl.getJsonPath(kind, name, '.status.replicas') ?? 0;
+                const pass = actual === count;
+                return {
+                    pass,
+                    message: () => pass
+                        ? `Expected ${kind}/${name} not to have ${count} replicas`
+                        : `Expected ${kind}/${name} to have ${count} replicas, got ${actual}`,
+                    actual,
+                    expected: count,
+                };
+            }
+            catch (e) {
+                return {
+                    pass: false,
+                    message: () => `Failed to get ${kind}/${name}: ${e}`,
+                };
+            }
+        },
+        /**
+         * Assert that a resource has a specific number of available replicas
+         */
+        async toHaveAvailableReplicas(received, ...args) {
+            const count = args[0];
+            if (!isK8sResource(received)) {
+                return {
+                    pass: false,
+                    message: () => 'Expected value to be a K8sResource',
+                };
+            }
+            const { kubectl, kind, name } = received;
+            try {
+                const actual = await kubectl.getJsonPath(kind, name, '.status.availableReplicas') ?? 0;
+                const pass = actual === count;
+                return {
+                    pass,
+                    message: () => pass
+                        ? `Expected ${kind}/${name} not to have ${count} available replicas`
+                        : `Expected ${kind}/${name} to have ${count} available replicas, got ${actual}`,
+                    actual,
+                    expected: count,
+                };
+            }
+            catch (e) {
+                return {
+                    pass: false,
+                    message: () => `Failed to get ${kind}/${name}: ${e}`,
+                };
+            }
+        },
+        /**
+         * Assert that a Deployment is available
+         */
+        async toBeAvailable(received) {
+            if (!isK8sResource(received)) {
+                return {
+                    pass: false,
+                    message: () => 'Expected value to be a K8sResource',
+                };
+            }
+            const { kubectl, kind, name } = received;
+            try {
+                const jsonPath = '.status.conditions[?(@.type=="Available")].status';
+                const statusValue = await kubectl.getJsonPath(kind, name, jsonPath);
+                // JSONPath may return multiple values separated by space, take first
+                const actualStatus = statusValue?.split(' ')?.[0];
+                const pass = actualStatus === 'True';
+                return {
+                    pass,
+                    message: () => pass
+                        ? `Expected ${kind}/${name} not to be available`
+                        : `Expected ${kind}/${name} to be available`,
+                    actual: actualStatus,
+                    expected: 'True',
+                };
+            }
+            catch (e) {
+                return {
+                    pass: false,
+                    message: () => `Failed to get ${kind}/${name}: ${e}`,
+                };
+            }
+        },
+        /**
+         * Assert that a resource exists in the cluster
+         */
+        async toExistInCluster(received) {
+            if (!isK8sResource(received)) {
+                return {
+                    pass: false,
+                    message: () => 'Expected value to be a K8sResource',
+                };
+            }
+            const { kubectl, kind, name } = received;
+            const exists = await kubectl.exists(kind, name);
+            return {
+                pass: exists,
+                message: () => exists
+                    ? `Expected ${kind}/${name} not to exist in cluster`
+                    : `Expected ${kind}/${name} to exist in cluster`,
+            };
+        },
+        /**
+         * Assert that a resource has a specific label
+         */
+        async toHaveLabel(received, ...args) {
+            const key = args[0];
+            const value = args[1];
+            if (!isK8sResource(received)) {
+                return {
+                    pass: false,
+                    message: () => 'Expected value to be a K8sResource',
+                };
+            }
+            const { kubectl, kind, name } = received;
+            try {
+                // Escape dots in label key for JSONPath
+                const escapedKey = key.replace(/\./g, '\\.');
+                const jsonPath = `.metadata.labels.${escapedKey}`;
+                const actualValue = await kubectl.getJsonPath(kind, name, jsonPath);
+                const pass = value !== undefined ? actualValue === value : actualValue !== undefined;
+                return {
+                    pass,
+                    message: () => {
+                        if (value !== undefined) {
+                            return pass
+                                ? `Expected ${kind}/${name} not to have label ${key}=${value}`
+                                : `Expected ${kind}/${name} to have label ${key}=${value}, got ${actualValue}`;
+                        }
+                        return pass
+                            ? `Expected ${kind}/${name} not to have label ${key}`
+                            : `Expected ${kind}/${name} to have label ${key}`;
+                    },
+                    actual: actualValue,
+                    expected: value ?? `label "${key}" exists`,
+                };
+            }
+            catch (e) {
+                return {
+                    pass: false,
+                    message: () => `Failed to get ${kind}/${name}: ${e}`,
+                };
+            }
+        },
+        /**
+         * Assert that a resource has a specific annotation
+         */
+        async toHaveAnnotation(received, ...args) {
+            const key = args[0];
+            const value = args[1];
+            if (!isK8sResource(received)) {
+                return {
+                    pass: false,
+                    message: () => 'Expected value to be a K8sResource',
+                };
+            }
+            const { kubectl, kind, name } = received;
+            try {
+                // Escape dots in annotation key for JSONPath
+                const escapedKey = key.replace(/\./g, '\\.');
+                const jsonPath = `.metadata.annotations.${escapedKey}`;
+                const actualValue = await kubectl.getJsonPath(kind, name, jsonPath);
+                const pass = value !== undefined ? actualValue === value : actualValue !== undefined;
+                return {
+                    pass,
+                    message: () => {
+                        if (value !== undefined) {
+                            return pass
+                                ? `Expected ${kind}/${name} not to have annotation ${key}=${value}`
+                                : `Expected ${kind}/${name} to have annotation ${key}=${value}, got ${actualValue}`;
+                        }
+                        return pass
+                            ? `Expected ${kind}/${name} not to have annotation ${key}`
+                            : `Expected ${kind}/${name} to have annotation ${key}`;
+                    },
+                    actual: actualValue,
+                    expected: value ?? `annotation "${key}" exists`,
+                };
+            }
+            catch (e) {
+                return {
+                    pass: false,
+                    message: () => `Failed to get ${kind}/${name}: ${e}`,
+                };
+            }
+        },
+        /**
+         * Assert that a resource has a specific condition
+         */
+        async toHaveCondition(received, ...args) {
+            const type = args[0];
+            const status = args[1];
+            if (!isK8sResource(received)) {
+                return {
+                    pass: false,
+                    message: () => 'Expected value to be a K8sResource',
+                };
+            }
+            const { kubectl, kind, name } = received;
+            try {
+                const jsonPath = `.status.conditions[?(@.type=="${type}")].status`;
+                const statusValue = await kubectl.getJsonPath(kind, name, jsonPath);
+                // JSONPath may return multiple values separated by space, take first
+                const actualStatus = statusValue?.split(' ')?.[0];
+                const pass = actualStatus === status;
+                return {
+                    pass,
+                    message: () => pass
+                        ? `Expected ${kind}/${name} not to have condition ${type}=${status}`
+                        : `Expected ${kind}/${name} to have condition ${type}=${status}, got ${actualStatus ?? 'not found'}`,
+                    actual: actualStatus,
+                    expected: status,
+                };
+            }
+            catch (e) {
+                return {
+                    pass: false,
+                    message: () => `Failed to get ${kind}/${name}: ${e}`,
+                };
+            }
+        },
+        /**
+         * Assert that a resource does not exist in the cluster
+         */
+        async toNotExistInCluster(received) {
+            if (!isK8sResource(received)) {
+                return {
+                    pass: false,
+                    message: () => 'Expected value to be a K8sResource',
+                };
+            }
+            const { kubectl, kind, name } = received;
+            const exists = await kubectl.exists(kind, name);
+            return {
+                pass: !exists,
+                message: () => !exists
+                    ? `Expected ${kind}/${name} to exist in cluster`
+                    : `Expected ${kind}/${name} not to exist in cluster`,
+            };
+        },
+        /**
+         * Assert that a resource has a specific number of ready replicas
+         */
+        async toHaveReadyReplicas(received, ...args) {
+            const count = args[0];
+            if (!isK8sResource(received)) {
+                return {
+                    pass: false,
+                    message: () => 'Expected value to be a K8sResource',
+                };
+            }
+            const { kubectl, kind, name } = received;
+            try {
+                const actual = await kubectl.getJsonPath(kind, name, '.status.readyReplicas') ?? 0;
+                const pass = actual === count;
+                return {
+                    pass,
+                    message: () => pass
+                        ? `Expected ${kind}/${name} not to have ${count} ready replicas`
+                        : `Expected ${kind}/${name} to have ${count} ready replicas, got ${actual}`,
+                    actual,
+                    expected: count,
+                };
+            }
+            catch (e) {
+                return {
+                    pass: false,
+                    message: () => `Failed to get ${kind}/${name}: ${e}`,
+                };
+            }
+        },
+        /**
+         * Assert that a resource has a specific status field value
+         * Supports dot notation for nested paths (e.g., 'phase', 'available.tflops')
+         */
+        async toHaveStatusField(received, ...args) {
+            const path = args[0];
+            const expectedValue = args[1];
+            if (!isK8sResource(received)) {
+                return {
+                    pass: false,
+                    message: () => 'Expected value to be a K8sResource',
+                };
+            }
+            const { kubectl, kind, name } = received;
+            try {
+                const jsonPath = `.status.${path}`;
+                const actual = await kubectl.getJsonPath(kind, name, jsonPath);
+                const pass = actual === expectedValue;
+                return {
+                    pass,
+                    message: () => pass
+                        ? `Expected ${kind}/${name} not to have status.${path} = ${JSON.stringify(expectedValue)}`
+                        : `Expected ${kind}/${name} to have status.${path} = ${JSON.stringify(expectedValue)}, got ${JSON.stringify(actual)}`,
+                    actual,
+                    expected: expectedValue,
+                };
+            }
+            catch (e) {
+                return {
+                    pass: false,
+                    message: () => `Failed to get ${kind}/${name}: ${e}`,
+                };
+            }
+        },
+    });
+}
+// Auto-register matchers when this module is imported
+registerK8sMatchers();

package/dist/plugin-kubectl/examples/00-simple-demo.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 示例 0: 简单演示（无需 K8s 集群）
+ *
+ * 验证 kubectl 插件基础功能，无需连接 Kubernetes 集群
+ *
+ * 运行方式:
+ *   bun run repterm packages/plugin-kubectl/examples/00-simple-demo.ts
+ */
+export {};
+//# sourceMappingURL=00-simple-demo.d.ts.map

package/dist/plugin-kubectl/examples/00-simple-demo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"00-simple-demo.d.ts","sourceRoot":"","sources":["../../../examples/00-simple-demo.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/plugin-kubectl/examples/00-simple-demo.js

@@ -0,0 +1,51 @@
+/**
+ * 示例 0: 简单演示（无需 K8s 集群）
+ *
+ * 验证 kubectl 插件基础功能，无需连接 Kubernetes 集群
+ *
+ * 运行方式:
+ *   bun run repterm packages/plugin-kubectl/examples/00-simple-demo.ts
+ */
+import { describe, defineConfig, createTestWithPlugins, } from '../../repterm/src/index.js';
+import { kubectlPlugin } from '../src/index.js';
+// 配置插件
+const config = defineConfig({
+    plugins: [kubectlPlugin({ namespace: 'default' })],
+});
+const test = createTestWithPlugins(config);
+describe('Kubectl 插件基础功能', () => {
+    test('验证命名空间配置', async (ctx) => {
+        const { kubectl } = ctx.plugins;
+        // 验证初始命名空间
+        const ns = kubectl.getNamespace();
+        if (ns !== 'default') {
+            throw new Error(`Expected namespace 'default', got '${ns}'`);
+        }
+        // 切换命名空间
+        kubectl.setNamespace('kube-system');
+        if (kubectl.getNamespace() !== 'kube-system') {
+            throw new Error('Namespace switch failed');
+        }
+        // 恢复
+        kubectl.setNamespace('default');
+    });
+    test('验证命令构建', async (ctx) => {
+        const { kubectl } = ctx.plugins;
+        // 验证 command 方法生成正确的命令
+        const cmd = kubectl.command('get pods');
+        if (!cmd.includes('kubectl')) {
+            throw new Error('Command should contain kubectl');
+        }
+        if (!cmd.includes('-n default')) {
+            throw new Error('Command should contain namespace');
+        }
+        if (!cmd.includes('get pods')) {
+            throw new Error('Command should contain get pods');
+        }
+    });
+    test('执行 kubectl version (run API)', async (ctx) => {
+        const { kubectl } = ctx.plugins;
+        // 使用插件的 run 方法执行命令
+        await kubectl.run('version --client');
+    });
+});

package/dist/plugin-kubectl/examples/01-basic-kubectl.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 示例 1: 基础 Kubectl 操作
+ *
+ * 演示 kubectl 插件的基础 API：apply, delete, get, exists, waitForPod
+ *
+ * 运行方式:
+ *   bun run repterm packages/plugin-kubectl/examples/01-basic-kubectl.ts
+ *
+ * 前置条件:
+ *   - 已配置 kubectl 并连接到 Kubernetes 集群
+ */
+export {};
+//# sourceMappingURL=01-basic-kubectl.d.ts.map

package/dist/plugin-kubectl/examples/01-basic-kubectl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"01-basic-kubectl.d.ts","sourceRoot":"","sources":["../../../examples/01-basic-kubectl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/plugin-kubectl/examples/01-basic-kubectl.js

@@ -0,0 +1,86 @@
+/**
+ * 示例 1: 基础 Kubectl 操作
+ *
+ * 演示 kubectl 插件的基础 API：apply, delete, get, exists, waitForPod
+ *
+ * 运行方式:
+ *   bun run repterm packages/plugin-kubectl/examples/01-basic-kubectl.ts
+ *
+ * 前置条件:
+ *   - 已配置 kubectl 并连接到 Kubernetes 集群
+ */
+import { describe, defineConfig, createTestWithPlugins, } from '../../repterm/src/index.js';
+import { kubectlPlugin } from '../src/index.js';
+// 配置插件
+const config = defineConfig({
+    plugins: [kubectlPlugin({ namespace: 'default' })],
+});
+const test = createTestWithPlugins(config);
+// 测试用 Pod YAML
+const nginxPodYaml = `
+apiVersion: v1
+kind: Pod
+metadata:
+  name: nginx-test
+  labels:
+    app: nginx
+    env: test
+spec:
+  containers:
+  - name: nginx
+    image: nginx:alpine
+    ports:
+    - containerPort: 80
+`;
+describe('基础 Kubectl API', { record: true }, () => {
+    // ===== apply - 创建资源 =====
+    test('apply - 创建 Pod', async (ctx) => {
+        const { kubectl } = ctx.plugins;
+        // 使用 apply API 创建 Pod
+        await kubectl.apply(nginxPodYaml);
+    });
+    // ===== waitForPod - 等待 Pod 就绪 =====
+    test('waitForPod - 等待 Pod Running', async (ctx) => {
+        const { kubectl } = ctx.plugins;
+        // 使用 waitForPod API 等待 Pod 进入 Running 状态
+        await kubectl.waitForPod('nginx-test', 'Running', 60000);
+    });
+    // ===== exists - 检查资源是否存在 =====
+    test('exists - 检查 Pod 存在', async (ctx) => {
+        const { kubectl } = ctx.plugins;
+        // 使用 exists API 检查资源
+        const podExists = await kubectl.exists('pod', 'nginx-test');
+        if (!podExists) {
+            throw new Error('Pod should exist');
+        }
+        // 检查不存在的资源
+        const notExists = await kubectl.exists('pod', 'non-existent-pod');
+        if (notExists) {
+            throw new Error('Non-existent pod should not exist');
+        }
+    });
+    // ===== get - 获取资源信息 =====
+    test('get - 获取 Pod 信息', async (ctx) => {
+        const { kubectl } = ctx.plugins;
+        // 使用 get API 获取资源 JSON
+        const pod = await kubectl.get('pod', 'nginx-test');
+        if (pod.metadata.name !== 'nginx-test') {
+            throw new Error(`Expected pod name 'nginx-test', got '${pod.metadata.name}'`);
+        }
+    });
+    // ===== run - 执行原始命令 =====
+    test('run - 执行原始 kubectl 命令', async (ctx) => {
+        const { kubectl } = ctx.plugins;
+        // 使用 run API 执行任意 kubectl 命令
+        await kubectl.run('get pod nginx-test -o wide');
+    });
+    // ===== delete - 删除资源 =====
+    test('delete - 删除 Pod', async (ctx) => {
+        const { kubectl } = ctx.plugins;
+        // 使用 delete API 删除资源
+        await kubectl.delete('pod', 'nginx-test', { force: true });
+        // 验证已删除
+        // 注意：删除可能需要一些时间
+        await new Promise(resolve => setTimeout(resolve, 2000));
+    });
+});