kubeagent-cli 1.0.0__tar.gz

kubeagent_cli-1.0.0/.dockerignore

@@ -0,0 +1,17 @@
+.git
+.github
+.venv
+.pytest_cache
+.ruff_cache
+__pycache__
+*.pyc
+*.pyo
+tests/
+docs/
+homebrew/
+*.egg-info
+dist/
+build/
+.env
+*.md
+!README.md

kubeagent_cli-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -v --tb=short

kubeagent_cli-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,169 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -v --tb=short
+
+  publish-pypi:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+  publish-docker:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          MAJOR=$(echo $VERSION | cut -d. -f1)
+          MINOR=$(echo $VERSION | cut -d. -f1-2)
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "major=$MAJOR" >> $GITHUB_OUTPUT
+          echo "minor=$MINOR" >> $GITHUB_OUTPUT
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: |
+            ghcr.io/ghostwritten/kubeagent:latest
+            ghcr.io/ghostwritten/kubeagent:${{ steps.version.outputs.version }}
+            ghcr.io/ghostwritten/kubeagent:${{ steps.version.outputs.minor }}
+            ghcr.io/ghostwritten/kubeagent:${{ steps.version.outputs.major }}
+            ghostwritten/kubeagent:latest
+            ghostwritten/kubeagent:${{ steps.version.outputs.version }}
+            ghostwritten/kubeagent:${{ steps.version.outputs.minor }}
+            ghostwritten/kubeagent:${{ steps.version.outputs.major }}
+
+  github-release:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+
+      - name: Generate changelog
+        id: changelog
+        run: |
+          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+          if [ -n "$PREV_TAG" ]; then
+            CHANGES=$(git log ${PREV_TAG}..HEAD --pretty=format:"- %s" --no-merges)
+          else
+            CHANGES=$(git log --pretty=format:"- %s" --no-merges -20)
+          fi
+          echo "changes<<EOF" >> $GITHUB_OUTPUT
+          echo "$CHANGES" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          body: |
+            ## What's Changed
+            ${{ steps.changelog.outputs.changes }}
+
+            ## Installation
+            ```bash
+            pip install kubeagent-cli==${{ github.ref_name }}
+            # or
+            docker pull ghcr.io/ghostwritten/kubeagent:${{ github.ref_name }}
+            ```
+          files: dist/*
+
+  update-homebrew:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
+
+      - name: Wait for PyPI availability
+        run: |
+          for i in $(seq 1 30); do
+            if pip index versions kubeagent-cli 2>/dev/null | grep -q "${{ steps.version.outputs.version }}"; then
+              echo "Version available on PyPI"
+              exit 0
+            fi
+            echo "Waiting for PyPI... ($i/30)"
+            sleep 10
+          done
+          echo "Warning: PyPI version not yet available, proceeding anyway"
+
+      - name: Download sdist and compute sha256
+        id: sha
+        run: |
+          pip download kubeagent-cli==${{ steps.version.outputs.version }} --no-binary :all: --no-deps -d /tmp/dist || true
+          SDIST=$(ls /tmp/dist/kubeagent_cli-*.tar.gz 2>/dev/null | head -1)
+          if [ -n "$SDIST" ]; then
+            SHA=$(sha256sum "$SDIST" | cut -d' ' -f1)
+          else
+            SHA="PLACEHOLDER_SHA256"
+          fi
+          echo "sha256=$SHA" >> $GITHUB_OUTPUT
+
+      - name: Update Homebrew tap
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          repository: Ghostwritten/homebrew-tap
+          event-type: update-formula
+          client-payload: |
+            {
+              "formula": "kubeagent",
+              "version": "${{ steps.version.outputs.version }}",
+              "sha256": "${{ steps.sha.outputs.sha256 }}"
+            }

kubeagent_cli-1.0.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Superpowers
+.superpowers/
+
+# Worktrees
+.worktrees/

kubeagent_cli-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ['--maxkb=500']

kubeagent_cli-1.0.0/AGENTS.md

@@ -0,0 +1,224 @@
+# KubeAgent — AGENTS.md
+
+> This document defines the identity, capabilities, behavior rules, and constraints for the KubeAgent project.
+> It serves as the foundational context for all development and contribution activities.
+
+---
+
+## Project Identity
+
+**Name**: KubeAgent
+**Type**: Open-source CLI intelligent agent
+**Purpose**: Manage Kubernetes clusters through natural language conversation
+**Repository**: github.com/user/kubeagent
+**License**: MIT
+
+---
+
+## Core Architecture
+
+KubeAgent is built on a **four-layer architecture**:
+
+```
+Interface Layer  →  Agent Layer  →  Capability Layer  →  Infrastructure Layer
+```
+
+| Layer | Components |
+|-------|-----------|
+| **Interface** | CLI REPL, Headless mode, Shell passthrough (`!`), Skill dispatch (`/`), Prompt Engine |
+| **Agent** | Main Agent (Pydantic AI), SubAgent Dispatcher, Memory Manager, Hook Engine, Policy Engine |
+| **Capability** | Tool Registry, Skill Registry — Built-in / User-defined / Plugin tools |
+| **Infrastructure** | Model Router (LiteLLM), Cluster Context, K8s Executor (Python Client + kubectl), Storage (SQLite) |
+
+---
+
+## Technology Stack
+
+| Component | Technology |
+|-----------|-----------|
+| Language | Python 3.11+ |
+| Agent Framework | Pydantic AI |
+| Model Interface | LiteLLM (100+ models: Ollama / Claude / GPT / Gemini) |
+| K8s SDK | kubernetes (official Python client) |
+| K8s CLI | kubectl (subprocess, supplementary) |
+| CLI UI | Rich + prompt_toolkit |
+| Config | Pydantic + YAML |
+| Storage | SQLite + local files |
+| Packaging | pip / pipx |
+
+---
+
+## Design Principles
+
+1. **Natural Language First** — Conversation-driven interaction, like Claude Code
+2. **Professional Output** — Rich tables for data, Markdown for analysis, mixed rendering
+3. **Safety by Design** — Three-tier operation classification, RBAC, dry-run, confirmation flows
+4. **Model Agnostic** — Local (Ollama) and cloud (Claude/GPT/Gemini) with intelligent routing
+5. **Open & Extensible** — Plugin system, community Skills, user-defined Tools
+6. **Incremental Delivery** — 12 lightweight phases, each producing a usable increment
+
+---
+
+## Installation
+
+| Method | Command | Note |
+|--------|---------|------|
+| **pipx (recommended)** | `pipx install kubeagent` | Isolated environment, no system pollution |
+| **pip** | `pip install kubeagent` | Traditional |
+| **Homebrew** | `brew install kubeagent` | macOS (later phase) |
+
+## First-Run Experience
+
+**Hybrid mode: auto-detect + guided setup (like Claude Code)**
+
+- **Auto-trigger**: First run detects environment, guides only missing items
+- **`kubeagent init`**: Full re-configuration
+- **`kubeagent doctor`**: Diagnose + fix issues
+
+**Pre-flight check on every run:**
+- Detect `~/.kube/config` and current context
+- Detect API keys via env vars (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `KUBEAGENT_API_KEY`)
+- Detect `~/.kubeagent/config.yaml`
+
+**Configuration storage:**
+- Path: `~/.kubeagent/`
+- Config: `~/.kubeagent/config.yaml`
+- Env var overrides: `KUBEAGENT_API_KEY`, `KUBEAGENT_MODEL_ENDPOINT`, `KUBEAGENT_MODEL`
+
+## Interaction Model
+
+- **Primary**: Conversational dialogue (natural language)
+- **Shell passthrough**: `!command` executes shell commands directly
+- **Skill invocation**: `/skill-name` triggers predefined workflows (e.g., `/diagnose`, `/deploy`)
+- **Headless**: `kubeagent --headless "query"` for CI/CD and scripting
+
+---
+
+## Component Overview
+
+### Prompt Engine
+Composes system prompts from: base template + KUBEAGENT.md rules + cluster context + user preferences.
+Priority: KUBEAGENT.md > config.yaml > defaults.
+
+### Main Agent
+Central reasoning engine using Pydantic AI. Workflow: intent recognition → memory query → policy check → task planning → tool selection → result synthesis.
+
+### SubAgent System
+Dynamic creation at runtime. Independent tool sets and model selection. Parallel execution via asyncio. Ephemeral lifecycle.
+
+### Tool System
+- **Built-in**: get_pods, describe_resource, read_logs, apply_yaml, delete_resource, scale, exec, etc.
+- **User-defined**: custom scripts, kubectl plugins
+- **Plugin**: Helm, Istio, ArgoCD ecosystem tools
+- Each tool declares security level: `safe` / `sensitive` / `dangerous`
+
+### Skill System
+Reusable workflows: `/diagnose`, `/deploy`, `/rollback`, `/security-audit`, `/migrate`, etc.
+Markdown-based definitions, community-contributable.
+
+### Hook Engine
+Event-driven automation: `pre-apply`, `post-deploy`, `on-error`, `on-connect`, etc.
+Can abort operations on failure.
+
+### Memory Manager
+Five types: session context, user preferences, cluster profiles, fault knowledge, audit log.
+SQLite storage with expiration and privacy controls.
+
+### Policy Engine
+- Three-tier: safe (immediate) → sensitive (confirm) → dangerous (double-confirm + warning)
+- RBAC: admin / operator / viewer
+- Whitelist/blacklist per operation and resource
+- Dry-run mode for all mutations
+
+### Model Router
+Four strategies (user-selectable): complexity-based, cost-based, availability-fallback, manual.
+SubAgents can use lighter models than Main Agent.
+
+### K8s Executor
+Unified interface: Python Client (primary) + kubectl (supplementary).
+Auto-detect kubectl, graceful degradation if absent.
+All outputs normalized to structured data models.
+
+---
+
+## Security Rules
+
+1. **Operation classification**: Every K8s operation is tagged safe/sensitive/dangerous
+2. **Confirmation flow**: Sensitive → "Proceed? [y/N]", Dangerous → type resource name to confirm
+3. **Dry-run**: `--dry-run` shows preview without executing any mutations
+4. **No secret storage**: Memory system never stores K8s secrets, tokens, or credentials
+5. **Injection prevention**: kubectl calls use argument lists, never shell string interpolation
+6. **Audit trail**: All mutating operations logged with timestamp, user, cluster, resource, result
+
+---
+
+## Model Configuration
+
+```yaml
+model:
+  default: claude-sonnet-4-20250514
+  fallback: [gpt-4o, ollama/qwen2.5]
+  strategy: complexity  # complexity | cost | availability | manual
+  subagent_model: claude-haiku-4-5-20251001
+  cost:
+    monthly_budget: 50
+    currency: USD
+```
+
+---
+
+## Configuration Hierarchy
+
+| File | Purpose | Format |
+|------|---------|--------|
+| `KUBEAGENT.md` | Project-level behavioral rules | Natural language (Markdown) |
+| `~/.kubeagent/config.yaml` | Global technical settings | Structured YAML |
+| `~/.kubeagent/hooks.yaml` | Hook definitions | Structured YAML |
+
+**Priority**: KUBEAGENT.md > config.yaml > defaults
+
+---
+
+## Implementation Roadmap
+
+12 phases with three milestones:
+
+| Milestone | After Phase | Status |
+|-----------|-------------|--------|
+| **MVP Alpha** | Phase 07 — Prompt Engine + Policy | `pending` |
+| **MVP Beta** | Phase 10 — Skill + Hook + Headless | `pending` |
+| **v1.0 小满贯** | Phase 12 — MCP Server + Ecosystem | `pending` |
+
+**Full plan**: `docs/plans/00-master-plan.md`
+
+---
+
+## File Structure
+
+```
+kubeagent/
+├── src/kubeagent/
+│   ├── cli/           # Interface Layer
+│   ├── agent/         # Agent Layer
+│   ├── tools/         # Capability Layer (builtin/, kubectl.py)
+│   ├── infra/         # Infrastructure Layer
+│   └── config/        # Configuration
+├── skills/            # Built-in skills
+├── plugins/           # Plugin directory
+├── tests/             # unit/, integration/, fixtures/
+└── docs/
+    ├── specs/         # Architecture design (WHY & WHAT)
+    ├── plans/         # Phase plans (HOW & WHEN)
+    └── decisions/     # Architecture Decision Records
+```
+
+---
+
+## Key Documentation
+
+| Document | Purpose |
+|----------|---------|
+| `docs/specs/2026-04-09-kubeagent-design.md` | Architecture design: WHY and WHAT |
+| `docs/plans/00-master-plan.md` | Roadmap: phase overview, dependency graph, execution rules |
+| `docs/plans/Phase-XX_*.md` | Phase details: tasks, acceptance criteria, status |
+| `docs/decisions/` | ADR: architecture decisions and rationale |

kubeagent_cli-1.0.0/Dockerfile

@@ -0,0 +1,27 @@
+# Stage 1: Builder
+FROM python:3.12-slim AS builder
+
+WORKDIR /build
+
+COPY pyproject.toml README.md ./
+COPY src/ src/
+
+RUN pip install --no-cache-dir build \
+    && python -m build --wheel \
+    && pip install --no-cache-dir --prefix=/install dist/*.whl
+
+# Stage 2: Runtime
+FROM python:3.12-slim
+
+LABEL org.opencontainers.image.source="https://github.com/Ghostwritten/kubeagent"
+LABEL org.opencontainers.image.description="Natural language CLI for Kubernetes cluster management"
+LABEL org.opencontainers.image.licenses="MIT"
+
+COPY --from=builder /install /usr/local
+
+# Create non-root user
+RUN useradd --create-home kubeagent
+USER kubeagent
+WORKDIR /home/kubeagent
+
+ENTRYPOINT ["kubeagent"]

kubeagent_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KubeAgent Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 NONINFRINGEMENT. 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.

kubeagent_cli-1.0.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: kubeagent-cli
+Version: 1.0.0
+Summary: A natural language CLI agent for Kubernetes cluster management
+Author: KubeAgent Contributors
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,cli,k8s,kubernetes
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1.0
+Requires-Dist: kubernetes>=31.0.0
+Requires-Dist: litellm>=1.0.0
+Requires-Dist: pydantic-ai>=0.2.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# KubeAgent
+
+> Natural language CLI for Kubernetes cluster management
+
+KubeAgent is an AI-powered CLI tool that lets you manage Kubernetes clusters through natural language conversation.
+
+## Installation
+
+### PyPI (Recommended)
+
+```bash
+pipx install kubeagent
+# or
+pip install kubeagent
+```
+
+### Homebrew (macOS / Linux)
+
+```bash
+brew tap Ghostwritten/tap
+brew install kubeagent
+```
+
+### Docker
+
+```bash
+# GHCR
+docker pull ghcr.io/ghostwritten/kubeagent:latest
+
+# Docker Hub
+docker pull ghostwritten/kubeagent:latest
+
+# Run
+docker run --rm -v ~/.kube:/home/kubeagent/.kube:ro ghcr.io/ghostwritten/kubeagent
+```
+
+### GitHub Releases
+
+Download the latest wheel or source tarball from
+[Releases](https://github.com/Ghostwritten/kubeagent/releases).
+
+```bash
+pip install kubeagent-*.whl
+```
+
+## Quick Start
+
+```bash
+# First run triggers setup wizard
+kubeagent
+
+# Re-configure anytime
+kubeagent init
+
+# Diagnose issues
+kubeagent doctor
+
+# Start MCP server
+kubeagent mcp start
+
+# Check version
+kubeagent --version
+```
+
+## Development
+
+```bash
+# Install with dev dependencies
+just install
+
+# Format, lint, test
+just check
+```
+
+## Architecture
+
+Four-layer architecture: Interface -> Agent -> Capability -> Infrastructure
+
+See [AGENTS.md](AGENTS.md) for full specification.
+
+## License
+
+MIT