loderunner · loderunner · Oct 28, 2025
diff --git a/K8S_IMPLEMENTATION_SUMMARY.md b/K8S_IMPLEMENTATION_SUMMARY.md
@@ -0,0 +1,230 @@
+# Kubernetes Remote Implementation Summary
+
+## Overview
+Successfully implemented a Kubernetes remote package (`@agent-remote/k8s`) that provides tools for executing commands and managing files on Kubernetes pods, mirroring the functionality of the existing Docker remote implementation.
+
+## What Was Implemented
+
+### 1. Package Structure (`packages/k8s/`)
+- ✅ `package.json` - Package configuration with all dependencies
+- ✅ `tsconfig.json` - TypeScript configuration with core package reference
+- ✅ `tsdown.config.ts` - Build configuration for ESM, CJS, and server targets
+- ✅ `vitest.config.ts` - Test configuration for unit, integration, and e2e tests
+- ✅ `README.md` - Documentation with usage examples
+- ✅ `CHANGELOG.md` - Version history
+
+### 2. Core Tool Implementations (`packages/k8s/src/lib/`)
+
+#### BashTool (`bash.ts`)
+- Executes commands via `kubectl exec`
+- Supports foreground and background execution
+- Persistent shell sessions for foreground commands
+- Background process management with shell IDs
+- Timeout support
+- Signal handling for killing background shells
+
+#### FileTool (`file.ts`)
+- Read files with optional offset/limit
+- Write files with content
+- Edit files with search/replace and diff generation
+- Uses kubectl exec for all operations
+
+#### GrepTool (`grep.ts`)
+- Search for patterns in files
+- Multiple output modes: content, files_with_matches, count
+- Context lines support (-A, -B, -C)
+- Case-insensitive search
+- Glob pattern filtering
+
+#### GlobTool (`glob.ts`)
+- Find files matching glob patterns
+- Recursive search with `**` support
+- Hidden file inclusion option
+- Uses find command with minimatch filtering
+
+#### Remote Class (`remote.ts`)
+- Unified interface to all tools
+- Configuration for pod, namespace, container, shell
+- MCP server integration via Claude Agent SDK
+- Proper error handling and formatting
+
+### 3. MCP Server (`packages/k8s/src/server/`)
+- Standalone MCP server (`server.ts`)
+- CLI with yargs for configuration
+- Environment variable support (K8S_POD, K8S_NAMESPACE, etc.)
+- Stdio transport for MCP protocol
+- Debug logging with pino
+
+### 4. Testing Infrastructure
+
+#### Unit Tests
+- `bash.unit.test.ts` - Event listener leak prevention tests
+- Designed to run without kubectl (tests internal logic)
+
+#### Integration Tests (updated)
+- Updated all integration test files to include k8s implementation:
+  - `bash-foreground.test.ts` - Foreground command execution
+  - `bash-background.test.ts` - Background process management
+  - `file.test.ts` - File operations (read, write, edit)
+  - `glob.test.ts` - File pattern matching
+  - `grep.test.ts` - Pattern searching
+- Added `getK8sConfig()` helper in `setup.ts`
+- Tests run against all three implementations: ssh, docker, k8s
+
+### 5. Sandbox Environment (updated)
+
+#### Docker Compose (`sandbox/docker-compose.yml`)
+- Added kind (Kubernetes in Docker) control plane service
+- Runs `kindest/node:v1.31.0` as a local k8s cluster
+- Privileged mode for running containers
+- Shared network for communication
+
+#### Setup Script (`sandbox/setup-kind.sh`)
+- Automated kind cluster initialization
+- Builds and loads sandbox image into kind
+- Creates sandbox pod in default namespace
+- Copies fixture files into pod
+- Validates pod is ready
+
+#### Configuration Files
+- `kind-config.yaml` - Kind cluster configuration
+- `k8s-pod.yaml` - Sandbox pod specification
+- Updated `README.md` with k8s setup and troubleshooting
+
+## Configuration
+
+### Remote Configuration
+```typescript
+type RemoteConfig = {
+  pod: string;           // Required: Pod name
+  namespace?: string;    // Optional: Namespace (default: 'default')
+  container?: string;    // Optional: Container name within pod
+  shell?: string;        // Optional: Shell to use (default: 'sh')
+};
+```
+
+### Key Differences from Docker
+1. Uses `kubectl exec` instead of `docker exec`
+2. Requires namespace specification
+3. Optional container name for multi-container pods
+4. Spawns processes with: `kubectl exec -n <namespace> -i <pod> [-c <container>] -- <command>`
+
+## How to Use
+
+### As a Library
+```typescript
+import { Remote } from '@agent-remote/k8s';
+
+const remote = new Remote({
+  pod: 'my-app-pod',
+  namespace: 'production',
+  container: 'main',
+  shell: 'bash',
+});
+
+await remote.bash.handler({ command: 'ls -la' });
+```
+
+### As an MCP Server
+```bash
+# Via CLI
+remote-k8s-mcp --pod my-app --namespace default
+
+# Via environment variables
+export K8S_POD=my-app
+export K8S_NAMESPACE=default
+remote-k8s-mcp
+```
+
+## Testing
+
+### Run All Tests
+```bash
+cd sandbox
+docker-compose up -d
+./setup-kind.sh
+
+cd ..
+pnpm -r test:integration
+```
+
+### Run K8s-Specific Tests
+```bash
+pnpm --filter @agent-remote/k8s test:unit
+pnpm --filter integration-tests test:k8s
+```
+
+### Verify Environment
+```bash
+# Check Docker container
+docker exec sandbox echo "Docker ready"
+
+# Check Kind cluster
+docker exec kind-control-plane kubectl get nodes
+docker exec kind-control-plane kubectl get pods
+
+# Check pod access
+docker exec kind-control-plane kubectl exec sandbox -- echo "K8s ready"
+```
+
+## Build Status
+✅ Package builds successfully
+✅ Generates ESM, CJS, and type declarations
+✅ MCP server executable created
+✅ No linter errors
+
+## Integration Test Coverage
+All integration tests now run against three implementations:
+- SSH (via ssh2)
+- Docker (via docker exec)
+- **K8s (via kubectl exec)** ← NEW
+
+This ensures consistent behavior across all remote types.
+
+## Known Limitations
+1. Unit tests require kubectl to be installed (expected to fail in some environments)
+2. Integration tests require a running kind cluster
+3. kubectl must be installed and configured on the host
+
+## Next Steps
+To actually run the k8s integration tests:
+1. Ensure kubectl is installed
+2. Start the sandbox environment: `docker-compose up -d`
+3. Run setup script: `./sandbox/setup-kind.sh`
+4. Run tests: `pnpm --filter integration-tests test`
+
+## Files Modified/Created
+
+### Created
+- `packages/k8s/` - Complete new package
+  - `package.json`
+  - `tsconfig.json`
+  - `vitest.config.ts`
+  - `tsdown.config.ts`
+  - `README.md`
+  - `CHANGELOG.md`
+  - `src/lib/bash.ts`
+  - `src/lib/file.ts`
+  - `src/lib/grep.ts`
+  - `src/lib/glob.ts`
+  - `src/lib/remote.ts`
+  - `src/lib/index.ts`
+  - `src/lib/bash.unit.test.ts`
+  - `src/server/server.ts`
+- `sandbox/kind-config.yaml`
+- `sandbox/k8s-pod.yaml`
+- `sandbox/setup-kind.sh`
+- `sandbox/README.md`
+
+### Modified
+- `packages/integration-tests/package.json` - Added k8s dependency and test scripts
+- `packages/integration-tests/src/setup.ts` - Added getK8sConfig()
+- `packages/integration-tests/src/bash-foreground.test.ts` - Added k8s implementation
+- `packages/integration-tests/src/bash-background.test.ts` - Added k8s implementation
+- `packages/integration-tests/src/file.test.ts` - Added k8s implementation
+- `packages/integration-tests/src/glob.test.ts` - Added k8s implementation
+- `packages/integration-tests/src/grep.test.ts` - Added k8s implementation
+- `sandbox/docker-compose.yml` - Added kind service
+
+## Summary
+The Kubernetes remote implementation is complete and follows the same patterns as the Docker remote. All integration tests have been updated to include k8s, and the sandbox environment now supports running tests against a local Kubernetes cluster using kind.
diff --git a/packages/integration-tests/package.json b/packages/integration-tests/package.json
@@ -22,11 +22,14 @@
     "test:ssh": "vitest run --testNamePattern ssh",
     "test:watch:ssh": "vitest --testNamePattern ssh",
     "test:docker": "vitest run --testNamePattern docker",
-    "test:watch:docker": "vitest --testNamePattern docker"
+    "test:watch:docker": "vitest --testNamePattern docker",
+    "test:k8s": "vitest run --testNamePattern k8s",
+    "test:watch:k8s": "vitest --testNamePattern k8s"
   },
   "dependencies": {
     "@agent-remote/core": "workspace:*",
     "@agent-remote/docker": "workspace:*",
+    "@agent-remote/k8s": "workspace:*",
     "@agent-remote/ssh": "workspace:*",
     "ssh2": "^1.17.0"
   },

diff --git a/packages/integration-tests/src/bash-background.test.ts b/packages/integration-tests/src/bash-background.test.ts
@@ -1,9 +1,11 @@
 import { BashTool as DockerBashTool } from '@agent-remote/docker';
+import { BashTool as K8sBashTool } from '@agent-remote/k8s';
 import { BashOutputOutput, BashTool as SSHBashTool } from '@agent-remote/ssh';
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 
 import {
   getDockerContainer,
+  getK8sConfig,
   getSSHClient,
   setupSSH,
   teardownSSH,
@@ -20,7 +22,7 @@ describe('Integration Tests', () => {
 
   const implementations: Array<{
     name: string;
-    createBashTool: () => SSHBashTool | DockerBashTool;
+    createBashTool: () => SSHBashTool | DockerBashTool | K8sBashTool;
   }> = [
     {
       name: 'ssh',
@@ -31,12 +33,16 @@ describe('Integration Tests', () => {
       createBashTool: () =>
         new DockerBashTool({ container: getDockerContainer(), shell: 'bash' }),
     },
+    {
+      name: 'k8s',
+      createBashTool: () => new K8sBashTool({ ...getK8sConfig(), shell: 'bash' }),
+    },
   ];
 
   describe.each(implementations)(
     'BashTool Background ($name)',
     ({ name: _name, createBashTool }) => {
-      let bashTool: SSHBashTool | DockerBashTool;
+      let bashTool: SSHBashTool | DockerBashTool | K8sBashTool;
 
       const waitForStatus = async (
         shellId: string,

diff --git a/packages/integration-tests/src/bash-foreground.test.ts b/packages/integration-tests/src/bash-foreground.test.ts
@@ -1,9 +1,11 @@
 import { BashTool as DockerBashTool } from '@agent-remote/docker';
+import { BashTool as K8sBashTool } from '@agent-remote/k8s';
 import { BashTool as SSHBashTool } from '@agent-remote/ssh';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 
 import {
   getDockerContainer,
+  getK8sConfig,
   getSSHClient,
   setupSSH,
   teardownSSH,
@@ -20,7 +22,7 @@ describe('Integration Tests', () => {
 
   const implementations: Array<{
     name: string;
-    createBashTool: () => SSHBashTool | DockerBashTool;
+    createBashTool: () => SSHBashTool | DockerBashTool | K8sBashTool;
   }> = [
     {
       name: 'ssh',
@@ -31,12 +33,16 @@ describe('Integration Tests', () => {
       createBashTool: () =>
         new DockerBashTool({ container: getDockerContainer(), shell: 'bash' }),
     },
+    {
+      name: 'k8s',
+      createBashTool: () => new K8sBashTool({ ...getK8sConfig(), shell: 'bash' }),
+    },
   ];
 
   describe.each(implementations)(
     'BashTool Foreground ($name)',
     ({ name: _name, createBashTool }) => {
-      let bashTool: SSHBashTool | DockerBashTool;
+      let bashTool: SSHBashTool | DockerBashTool | K8sBashTool;
 
       beforeAll(() => {
         bashTool = createBashTool();

diff --git a/packages/integration-tests/src/file.test.ts b/packages/integration-tests/src/file.test.ts
@@ -1,11 +1,13 @@
 import fs from 'fs/promises';
 
 import { FileTool as DockerFileTool } from '@agent-remote/docker';
+import { FileTool as K8sFileTool } from '@agent-remote/k8s';
 import { FileTool as SSHFileTool } from '@agent-remote/ssh';
 import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
 
 import {
   getDockerContainer,
+  getK8sConfig,
   getSSHClient,
   getSSHSFTP,
   setupSSH,
@@ -32,7 +34,7 @@ describe('Integration Tests', () => {
 
   const implementations: Array<{
     name: string;
-    createFileTool: () => SSHFileTool | DockerFileTool;
+    createFileTool: () => SSHFileTool | DockerFileTool | K8sFileTool;
   }> = [
     {
       name: 'ssh-sftp',
@@ -47,12 +49,17 @@ describe('Integration Tests', () => {
       createFileTool: () =>
         new DockerFileTool({ container: getDockerContainer(), shell: 'sh' }),
     },
+    {
+      name: 'k8s',
+      createFileTool: () =>
+        new K8sFileTool({ ...getK8sConfig(), shell: 'sh' }),
+    },
   ];
 
   describe.each(implementations)(
     'FileTool ($name)',
     ({ name, createFileTool }) => {
-      let fileTool: SSHFileTool | DockerFileTool;
+      let fileTool: SSHFileTool | DockerFileTool | K8sFileTool;
 
       beforeAll(() => {
         fileTool = createFileTool();