kubeagent 0.1.0

package/LICENSE

@@ -0,0 +1,72 @@
+KubeAgent Commercial License
+Copyright (c) 2025 KubeAgent (kubeagent.net). All rights reserved.
+
+TERMS AND CONDITIONS
+
+1. DEFINITIONS
+
+   "Software" means the KubeAgent software and associated documentation files.
+   "Licensor" means KubeAgent (kubeagent.net).
+   "You" means the individual or legal entity exercising rights under this License.
+   "Commercial Use" means any use of the Software for commercial advantage or
+   monetary compensation, including use within a business or organization.
+
+2. GRANT OF LICENSE
+
+   Subject to the terms of this License, Licensor grants You a non-exclusive,
+   non-transferable, limited license to:
+
+   a. Use the Software for personal, non-commercial evaluation purposes.
+   b. Access and modify the source code for the purpose of contributing to the
+      official KubeAgent repository via pull request.
+
+3. RESTRICTIONS
+
+   You may NOT, without explicit written permission from the Licensor:
+
+   a. Use the Software for Commercial Use.
+   b. Distribute, sublicense, sell, resell, transfer, assign, or otherwise
+      commercially exploit or make available the Software or any derivative works.
+   c. Copy or use the Software for any purpose other than as permitted in Section 2.
+   d. Remove or alter any proprietary notices, labels, or marks on the Software.
+   e. Use the KubeAgent name, logo, or trademarks to endorse or promote products
+      derived from this Software without prior written consent.
+
+4. COMMERCIAL LICENSING
+
+   Commercial use of the Software requires a separate commercial license agreement
+   with the Licensor. To obtain a commercial license, please contact:
+
+   Email:   hello@kubeagent.net
+   Website: https://kubeagent.net
+
+   Paid plans that include a commercial license are available at:
+   https://kubeagent.net/#pricing
+
+5. CONTRIBUTIONS
+
+   By submitting a pull request or patch to the official KubeAgent repository,
+   You grant the Licensor a perpetual, worldwide, non-exclusive, royalty-free,
+   irrevocable license to use, reproduce, modify, distribute, and sublicense
+   your contribution as part of the Software under any license the Licensor chooses.
+
+6. DISCLAIMER OF WARRANTIES
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. IN NO EVENT SHALL
+   THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+   THE SOFTWARE.
+
+7. TERMINATION
+
+   This License is effective until terminated. Your rights under this License
+   terminate automatically if You fail to comply with any of its terms. Upon
+   termination, You must destroy all copies of the Software in your possession.
+
+8. GOVERNING LAW
+
+   This License shall be governed by and construed in accordance with applicable
+   law, without regard to conflict of law principles.

package/README.md

@@ -0,0 +1,154 @@
+# KubeAgent
+
+AI-powered Kubernetes monitoring, diagnosis, and remediation CLI. Uses Claude to investigate cluster issues, determine root causes, and apply fixes — with human approval for risky actions.
+
+Built for solo DevOps engineers and small teams who want an intelligent on-call assistant.
+
+## How It Works
+
+```
+Monitor (kubectl polling) --> Diagnoser (Claude API) --> Verifier (re-check)
+```
+
+1. **Monitor** polls your cluster for issues (CrashLoopBackOff, OOM, ImagePullBackOff, node pressure, etc.) — no LLM involved.
+2. **Diagnoser** sends issues to Claude with your cluster's knowledge base as context. Claude investigates using kubectl tools (logs, describe, events) in an agentic loop.
+3. **Verifier** re-checks the cluster after a fix to confirm the issue is resolved.
+
+Safe actions (pod restart, rollout restart, scale up) are auto-applied. Risky actions (rollback, delete, scale to zero) require your approval.
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Set your API key
+export ANTHROPIC_API_KEY=sk-...
+
+# Check cluster health (no LLM)
+npx tsx src/cli.ts status
+
+# Onboard — scan cluster, detect tech stacks, build knowledge base
+npx tsx src/cli.ts onboard
+
+# Watch mode — continuous monitoring with auto-remediation
+npx tsx src/cli.ts watch
+
+# One-shot diagnosis of a specific resource
+npx tsx src/cli.ts diagnose my-pod -n production
+
+# Ask a freeform question about your cluster
+npx tsx src/cli.ts "why is the retime API returning 503s?"
+```
+
+## Install Globally
+
+```bash
+npm run build
+npm link
+kubeagent status
+```
+
+## Commands
+
+| Command | Description | Uses LLM |
+|---------|-------------|----------|
+| `status` | Quick cluster health check | No |
+| `onboard` | Scan cluster + codebases, interview, generate knowledge base | Yes |
+| `watch` | Continuous monitoring with auto-remediation | Yes |
+| `diagnose <resource>` | One-shot diagnosis of a pod/deployment/service | Yes |
+| `<prompt>` | Freeform question about your cluster | Yes |
+
+### Common Options
+
+- `-c, --context <name>` — Kubernetes context (defaults to current)
+- `-n, --namespace <name>` — Namespace (for `diagnose`)
+- `-i, --interval <seconds>` — Check interval for `watch` (default: 60)
+
+## Knowledge Base
+
+KubeAgent builds a per-cluster knowledge base at `~/.kubeagent/clusters/<context>/` during onboarding:
+
+```
+~/.kubeagent/
+  config.yaml              # Global config (clusters, webhooks, intervals)
+  clusters/
+    hetzner-prod/
+      cluster.md           # Nodes, namespaces, deployments, services
+      projects/
+        retime.md          # Tech stack, dependencies, notes
+        dove.md
+      runbooks/            # Custom runbooks (manually added)
+      incidents/           # Auto-logged incident reports
+```
+
+This context is injected into Claude's system prompt during diagnosis, giving it awareness of your specific infrastructure.
+
+## Action Safety
+
+Actions are classified into tiers:
+
+| Tier | Actions | Behavior |
+|------|---------|----------|
+| **Safe** | `get_logs`, `describe_resource`, `get_events`, `restart_pod`, `rollout_restart`, `scale_deployment` | Auto-executed |
+| **Risky** | `rollback_deployment`, `scale_to_zero`, `delete_resource`, `edit_configmap`, `apply_manifest` | Requires approval |
+| **Never** | `delete namespace`, `delete node`, etc. | Refused |
+
+## Notifications
+
+Configure webhooks in `~/.kubeagent/config.yaml` to get alerts in Slack, Mattermost, or Discord:
+
+```yaml
+webhooks:
+  - url: https://hooks.slack.com/services/T.../B.../xxx
+    type: slack
+    severityFilter: critical
+```
+
+## Architecture
+
+```
+src/
+  cli.ts                 # Commander.js CLI entry point
+  config.ts              # YAML config (~/.kubeagent/config.yaml)
+  kubectl.ts             # kubectl exec wrapper
+  orchestrator.ts        # Monitor -> Diagnose -> Verify pipeline
+  verifier.ts            # Post-fix verification
+  monitor/
+    types.ts             # Issue types (Severity, IssueKind, Issue)
+    checks.ts            # Pod and node issue detection
+    index.ts             # Polling loop
+  diagnoser/
+    tools.ts             # Zod-defined kubectl tools for Claude
+    index.ts             # Claude API agentic loop
+  kb/
+    loader.ts            # Read KB into system prompt
+    writer.ts            # Write cluster/project/runbook/incident markdown
+  notify/
+    index.ts             # Notification dispatcher
+    webhook.ts           # Slack/Mattermost/Discord webhooks
+  onboard/
+    cluster-scan.ts      # Auto-discover K8s resources
+    code-scan.ts         # Detect tech stack from project files
+    interview.ts         # Claude-generated clarifying questions
+    index.ts             # Full onboarding flow
+```
+
+## Requirements
+
+- Node.js >= 20
+- `kubectl` configured with cluster access
+- `ANTHROPIC_API_KEY` environment variable (for LLM features)
+
+## Development
+
+```bash
+npm test              # Run all tests
+npm run test:watch    # Watch mode
+npm run build         # Compile TypeScript
+npx tsx src/cli.ts    # Run without building
+```
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,23 @@
+export interface AuthState {
+    serverUrl: string;
+    appUrl: string;
+    token: string;
+    email?: string;
+    name?: string;
+    apiKey?: string;
+}
+export declare function loadAuth(): AuthState | null;
+export declare function saveAuth(auth: AuthState): void;
+export declare function clearAuth(): void;
+export declare function loginBrowser(serverUrl: string, appUrl: string): Promise<AuthState>;
+export declare function createApiKey(auth: AuthState, name: string): Promise<{
+    key: string;
+    prefix: string;
+}>;
+export declare function showAccount(auth: AuthState): Promise<{
+    balance: {
+        monthlyRemaining: number;
+        extraRemaining: number;
+        totalRemaining: number;
+    };
+}>;

package/dist/auth.js

@@ -0,0 +1,162 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { configDir } from "./config.js";
+import { dbg } from "./debug.js";
+function authPath() {
+    return join(configDir(), "auth.json");
+}
+export function loadAuth() {
+    const path = authPath();
+    if (!existsSync(path)) {
+        dbg("auth", "no auth file found", { path });
+        return null;
+    }
+    try {
+        const auth = JSON.parse(readFileSync(path, "utf-8"));
+        dbg("auth", "loaded", {
+            serverUrl: auth.serverUrl,
+            email: auth.email,
+            keyPrefix: auth.apiKey ? auth.apiKey.slice(0, 12) + "..." : "(none)",
+            hasToken: !!auth.token,
+        });
+        return auth;
+    }
+    catch {
+        dbg("auth", "failed to parse auth file");
+        return null;
+    }
+}
+export function saveAuth(auth) {
+    const dir = configDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(authPath(), JSON.stringify(auth, null, 2));
+}
+export function clearAuth() {
+    const path = authPath();
+    if (existsSync(path))
+        unlinkSync(path);
+}
+// Browser-based login flow (like Tailscale / GitHub CLI):
+// 1. Generate random state + start local HTTP listener on a free port
+// 2. Open browser to <appUrl>/auth/cli?state=<s>&port=<p>
+// 3. User logs in (if needed) and clicks "Authorize"
+// 4. Server redirects to http://localhost:<p>/callback?token=...&email=...
+// 5. CLI saves token and resolves
+export async function loginBrowser(serverUrl, appUrl) {
+    const state = randomBytes(16).toString("hex");
+    const { token, email, name } = await new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            if (!req.url?.startsWith("/callback")) {
+                res.end();
+                return;
+            }
+            const url = new URL(req.url, "http://localhost");
+            const receivedState = url.searchParams.get("state");
+            const token = url.searchParams.get("token");
+            const email = url.searchParams.get("email") ?? "";
+            const name = url.searchParams.get("name") ?? "";
+            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            res.end(`<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>KubeAgent — Authorized</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { background: #0a0a0a; color: #e5e5e5; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; }
+    .card { background: #141414; border: 1px solid #262626; border-radius: 12px; padding: 2.5rem 3rem; text-align: center; max-width: 420px; width: 90%; }
+    .icon { font-size: 3rem; margin-bottom: 1.25rem; }
+    h1 { font-size: 1.4rem; font-weight: 700; margin-bottom: 0.6rem; color: #f5f5f5; }
+    p { color: #737373; font-size: 0.95rem; line-height: 1.6; }
+    .check { display: inline-flex; align-items: center; justify-content: center; width: 64px; height: 64px; border-radius: 50%; background: #052e16; margin-bottom: 1.25rem; }
+    .check svg { width: 32px; height: 32px; stroke: #34d399; }
+  </style>
+  <script>setTimeout(() => window.close(), 2000);</script>
+</head>
+<body>
+  <div class="card">
+    <div class="check">
+      <svg fill="none" viewBox="0 0 24 24" stroke-width="2.5" stroke="currentColor">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M4.5 12.75l6 6 9-13.5" />
+      </svg>
+    </div>
+    <h1>CLI Authorized</h1>
+    <p>You're logged in. Return to your terminal — this tab will close automatically.</p>
+  </div>
+</body>
+</html>`);
+            server.close();
+            if (receivedState !== state || !token) {
+                reject(new Error("Invalid callback — state mismatch or missing token"));
+            }
+            else {
+                resolve({ token, email, name });
+            }
+        });
+        server.listen(0, "127.0.0.1", async () => {
+            const port = server.address().port;
+            const authUrl = `${appUrl}/auth/cli?state=${state}&port=${port}`;
+            // Open browser cross-platform
+            const { execSync } = await import("node:child_process");
+            const cmd = process.platform === "darwin" ? `open "${authUrl}"`
+                : process.platform === "win32" ? `start "" "${authUrl}"`
+                    : `xdg-open "${authUrl}"`;
+            try {
+                execSync(cmd);
+            }
+            catch {
+                // fallback: just print the URL
+            }
+            console.log(`\nOpening browser for authentication...`);
+            console.log(`If the browser didn't open, visit:\n  ${authUrl}\n`);
+        });
+        // Timeout after 5 minutes
+        const timeoutId = setTimeout(() => {
+            server.close();
+            reject(new Error("Login timed out (5 minutes)"));
+        }, 5 * 60 * 1000);
+        // Unref so the timeout doesn't keep Node alive if something else exits first
+        timeoutId.unref();
+    });
+    const auth = { serverUrl, appUrl, token, email, name };
+    saveAuth(auth);
+    return auth;
+}
+export async function createApiKey(auth, name) {
+    const url = `${auth.serverUrl}/keys`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${auth.token}`,
+            },
+            body: JSON.stringify({ name }),
+        });
+    }
+    catch (err) {
+        throw new Error(`Could not reach server at ${url} — is it running?\n  (${err.message})`);
+    }
+    if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        throw new Error(body.error ?? `Failed to create API key (${res.status})`);
+    }
+    const data = (await res.json());
+    auth.apiKey = data.key;
+    saveAuth(auth);
+    return data;
+}
+export async function showAccount(auth) {
+    const res = await fetch(`${auth.serverUrl}/v1/balance`, {
+        headers: { Authorization: `ApiKey ${auth.apiKey ?? auth.token}` },
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch account info (${res.status})`);
+    }
+    return { balance: (await res.json()) };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};