kdrift 0.1.0__tar.gz

kdrift-0.1.0/.cruft.json

@@ -0,0 +1,21 @@
+{
+  "template": "https://github.com/missionlane/templates",
+  "commit": "81b9e092d4929564ea2805dc3f6c357765b2b6ee",
+  "checkout": null,
+  "context": {
+    "cookiecutter": {
+      "project_name": "kdrift",
+      "project_slug": "kdrift",
+      "package_name": "kdrift",
+      "description": "Kustomize manifest drift detection tool",
+      "python_version": "3.13",
+      "sonarqube_project_key": "mikedougherty.kdrift",
+      "has_web_server": "no",
+      "has_cli": "yes",
+      "needs_k8s_access": "no",
+      "_template": "https://github.com/missionlane/templates",
+      "_commit": "81b9e092d4929564ea2805dc3f6c357765b2b6ee"
+    }
+  },
+  "directory": "python-service"
+}

kdrift-0.1.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{yaml,yml,json,toml}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

kdrift-0.1.0/.env.example

@@ -0,0 +1,6 @@
+# kdrift Configuration
+# Copy to .env and fill in values: cp .env.example .env
+
+# --- Optional ---
+# APP_LOG_LEVEL=INFO
+# APP_LOG_FORMAT=json

kdrift-0.1.0/.github/workflows/build.yaml

@@ -0,0 +1,48 @@
+name: Build
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - "*.md"
+      - "!README.md"
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - "*.md"
+      - "!README.md"
+
+permissions:
+  contents: read
+  pull-requests: write
+  checks: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: Lint, Type Check, Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run mypy src/kdrift
+
+      - name: Test
+        run: uv run pytest

kdrift-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

kdrift-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+
+.venv/
+.env
+
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+coverage.xml
+htmlcov/
+test-results/
+.coverage
+
+.scannerwork/
+.claude/
+
+*.db
+*.sqlite3

kdrift-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+repos:
+  - 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-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.12
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run mypy src/kdrift
+        language: system
+        types: [python]
+        pass_filenames: false
+
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.0.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]

kdrift-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

kdrift-0.1.0/AGENTS.md

@@ -0,0 +1,123 @@
+# kdrift
+
+Kustomize manifest drift detection tool
+
+## Quick Reference
+
+```bash
+make deps        # Install dependencies
+make validate    # Run all checks (lint + typecheck + test)
+make test        # Run tests
+make typecheck   # Run mypy
+```
+
+## Architecture
+
+- **Package layout:** `src/kdrift/` (src layout)
+- **Config:** `pydantic-settings` BaseSettings in `config.py`, env vars with `KDRIFT_` prefix
+- **Project config:** `.kdrift.yaml` with upward directory walking (project > org > user XDG)
+- **Logging:** structlog with JSON output (production) / console (development)
+- **Testing:** pytest with `unit`/`integration` markers, 80% coverage minimum
+
+### Module Map
+
+| Module | Purpose |
+|--------|---------|
+| `cli.py` | click entry point, --watch/--check/--format flags |
+| `discover.py` | Parse kustomization.yaml files, build reverse dependency DAG, find affected overlays |
+| `render.py` | Run kustomize build as subprocess, baseline caching, parallel rendering |
+| `diff.py` | Two-phase resource matching (exact GVK+ns+name, then generator-aware), unified diff |
+| `pipeline.py` | Shared discover->render->diff orchestration for all frontends |
+| `git.py` | Ref resolution, changed files, temporary worktree management |
+| `models.py` | Pydantic models (ResourceId, OverlayResult, DiffResult, RenderResult) |
+| `config.py` | AppConfig (env vars) + ProjectConfig (.kdrift.yaml hierarchy) |
+| `watch.py` | Filesystem monitoring with debouncing via watchfiles |
+| `logging.py` | structlog configuration |
+
+### Key Design Decisions
+
+- **Kustomize as subprocess, not library:** decouples from kustomize version, user controls the binary
+- **Git-status-driven discovery:** `git diff --name-only` determines changed files, dependency graph maps to overlays
+- **Two-phase resource matching:** Phase 1 exact GVK+ns+name, Phase 2 generator-aware with kustomize hash charset (`bcdfghjklmnpqrstvwxz2456789`)
+- **Baseline caching:** keyed by ref+overlay+kustomize-args+version, stored in `~/.cache/kdrift/`
+- **Read-only git operations only:** worktrees for baseline rendering (separate index, no locks)
+
+## Conventions
+
+- All tool config in `pyproject.toml` (ruff, mypy, pytest, coverage)
+- mypy strict mode -- avoid `type: ignore` unless no alternative exists
+- Use `pydantic.SecretStr` for credential fields in config
+- Pre-commit hooks enforce formatting and type checking on every commit
+
+## CLI
+
+- click-based CLI registered as `kdrift` entrypoint
+- Run via `uv run kdrift` or `make run`
+- Supports `-C`/`--repo` flag to target external repositories
+
+## Verification Commands
+
+```bash
+make validate    # Full CI-equivalent check
+make test        # Tests with coverage
+make typecheck   # mypy strict mode
+make lint        # ruff linter
+```
+
+## CI/CD
+
+- CI runs on push to main and PRs: lint -> format-check -> typecheck -> test
+- ubuntu-latest runners (not self-hosted)
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/kdrift/config.py` | Application config (pydantic-settings) |
+| `src/kdrift/logging.py` | structlog configuration |
+| `src/kdrift/lsp_server.py` | LSP server (pygls) |
+| `src/kdrift/mcp_server.py` | MCP server (FastMCP) |
+| `tests/conftest.py` | Shared test fixtures |
+| `tests/test_mcp_integration.py` | MCP integration test harness |
+| `Makefile` | Standard development targets |
+| `pyproject.toml` | All tool configuration |
+
+## Agent Development Loop
+
+When iterating on kdrift itself, use `--debug` to enable file logging and verbose output:
+
+### LSP development
+
+```bash
+# Configure VS Code: glspc.serverCommand="kdrift", glspc.serverCommandArguments=["lsp", "--debug"]
+# Or without debug: glspc.serverCommandArguments=["lsp"]
+
+# Hot-reload after code changes (no VS Code restart needed):
+pkill -USR1 -f "kdrift lsp"
+
+# Full reinstall (needed if lsp_server.py itself changes):
+uv tool install -e ~/src/github.com/mikedougherty/kdrift --force
+pkill -f "kdrift lsp"  # VS Code auto-restarts
+
+# Monitor logs:
+tail -f ~/.cache/kdrift/kdrift.log
+```
+
+### MCP development
+
+```bash
+# Run integration tests (self-contained, no session restart):
+uv run python tests/test_mcp_integration.py
+
+# Or test against a specific repo:
+uv run python tests/test_mcp_integration.py /path/to/kustomize-repo
+```
+
+### Debug flag behavior
+
+`--debug` on `lsp` and `mcp` subcommands enables:
+- DEBUG log level (all internal events logged)
+- File logging to `~/.cache/kdrift/kdrift.log`
+- Full-repo diff on SIGUSR1 reload (LSP only)
+
+Without `--debug`, LSP/MCP run quietly with WARNING level, no file log.

kdrift-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@./AGENTS.md

kdrift-0.1.0/Makefile

@@ -0,0 +1,43 @@
+.PHONY: deps run lint format format-check typecheck test test-unit test-integration validate clean help
+
+deps: ## Install/sync all dependencies
+	@uv sync --all-groups
+
+run: ## Run the CLI
+	@uv run kdrift
+
+lint: ## Run linter
+	@uv run ruff check .
+
+format: ## Format code and fix auto-fixable lint issues
+	@uv run ruff format .
+	@uv run ruff check --fix .
+
+format-check: ## Check formatting without modifying files
+	@uv run ruff format --check .
+
+typecheck: ## Run type checker
+	@uv run mypy src/kdrift
+
+test: ## Run all tests
+	@uv run pytest
+
+test-unit: ## Run unit tests only
+	@uv run pytest -m unit
+
+test-integration: ## Run integration tests only
+	@uv run pytest -m integration
+
+validate: ## Run all checks (CI equivalent)
+	@$(MAKE) lint
+	@$(MAKE) format-check
+	@$(MAKE) typecheck
+	@$(MAKE) test
+
+clean: ## Remove build artifacts
+	@rm -rf .mypy_cache .pytest_cache .ruff_cache htmlcov coverage.xml test-results/ .coverage
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+.DEFAULT_GOAL := help

kdrift-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: kdrift
+Version: 0.1.0
+Summary: Kustomize manifest drift detection tool
+Requires-Python: >=3.13
+Requires-Dist: click>=8.0
+Requires-Dist: mcp>=1.27.2
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pygls>=2.1.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: structlog>=24.0
+Requires-Dist: watchfiles>=1.2.0

kdrift-0.1.0/README.md

@@ -0,0 +1,115 @@
+# kdrift
+
+CLI, MCP, LSP, and VS Code extension for kustomize manifest drift detection. Discovers which overlays are affected by your changes, renders baselines and candidates, and diffs per-resource.
+
+## Install
+
+```bash
+# From GitHub (recommended for now)
+uv tool install git+https://github.com/mikedougherty/kdrift
+
+# From PyPI (once published)
+uv tool install kdrift
+```
+
+Requires Python 3.13+ and `kustomize` on PATH.
+
+## Usage
+
+```bash
+kdrift diff                             # diff all affected overlays vs HEAD
+kdrift diff k8s/base/deployment.yaml    # diff overlays affected by this file
+kdrift diff --overlay k8s/dev           # diff only this overlay
+kdrift diff --ref main~3                # diff against a specific ref
+kdrift diff --ref main~5..main~2        # compare two commits
+kdrift diff -C /path/to/repo            # target a different repository
+kdrift diff --format json               # structured JSON output
+kdrift diff --check                     # exit non-zero if drift exists (CI/pre-commit)
+kdrift diff --watch                     # continuous mode: re-diff on file save
+```
+
+## How It Works
+
+1. `git diff --name-only HEAD` finds changed files
+2. Dependency graph maps changes to affected leaf overlays (parses all `kustomization.yaml` reference types)
+3. `kustomize build` renders baseline (via git worktree, cached) and candidate (working tree)
+4. Two-phase per-resource diff: exact GVK+namespace+name match, then generator-aware matching for hash-suffixed ConfigMap/Secret names
+5. Output as unified diff or structured JSON
+
+## Configuration
+
+Create `.kdrift.yaml` anywhere in your directory tree (searched upward from CWD):
+
+```yaml
+kustomize_args:
+  - "--enable-helm"
+  - "--load-restrictor"
+  - "LoadRestrictionsNone"
+```
+
+## Development
+
+```bash
+make deps        # Install dependencies
+make validate    # Run all checks (lint + typecheck + test)
+make test        # Tests only
+make typecheck   # mypy strict mode
+```
+
+See [docs/development.md](docs/development.md) for detailed setup.
+
+## Quick Start: MCP Server for Claude Code
+
+Give your AI agent kustomize drift detection in two steps:
+
+**1. Install kdrift:**
+
+```bash
+uv tool install git+https://github.com/mikedougherty/kdrift
+```
+
+**2. Add to your Claude Code MCP config** (`.claude.json` or project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "kdrift": {
+      "command": "kdrift",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+That's it. Your agent now has four tools: `kdrift_diff`, `kdrift_discover`, `kdrift_affected`, `kdrift_render`. Ask it to "check what my kustomize changes affect" and it will use them.
+
+**3. (Optional) Add agent instructions** for deeper context on how to use kdrift:
+
+```markdown
+@path/to/kdrift/docs/agents/AGENTS.md
+```
+
+Or copy `docs/agents/` into your project's agent instructions directory. The files are self-contained and agent-agnostic.
+
+## Agent Integration
+
+kdrift ships with agent-readable instructions in `docs/agents/`. These work with any AI coding assistant that supports `AGENTS.md` or similar instruction files.
+
+### VS Code Extension
+
+The `vscode-kdrift/` directory contains a VS Code extension that shows drift diffs in a side panel, modeled after the built-in Markdown Preview. See [vscode-kdrift/README.md](vscode-kdrift/README.md) for setup and development.
+
+### LSP Server (IDE integration)
+
+```bash
+kdrift lsp          # stdio transport, configure in your LSP client
+kdrift lsp --debug  # enable file logging to ~/.cache/kdrift/kdrift.log
+```
+
+Provides diagnostics on save, CodeLens annotations, and hover info.
+
+## Documentation
+
+- [Development Guide](docs/development.md)
+- [Configuration](docs/configuration.md)
+- [Agent Instructions](docs/agents/AGENTS.md)

kdrift-0.1.0/docs/agents/AGENTS.md

@@ -0,0 +1,21 @@
+# kdrift Agent Instructions
+
+Agent-readable instructions for using kdrift in kustomize repositories.
+
+## Load When
+
+- Working in a repository with `kustomization.yaml` files
+- Using kustomize, kubectl, or Helm to manage Kubernetes manifests
+- Reviewing PRs that touch kustomize overlays, bases, or patches
+
+## Knowledge
+
+Concepts, architecture, configuration, and tool reference:
+
+@./knowledge/KNOWLEDGE.md
+
+## Skills
+
+How to use kdrift (MCP tools and CLI) to detect manifest drift:
+
+@./skills/SKILL.md

kdrift-0.1.0/docs/agents/knowledge/KNOWLEDGE.md

@@ -0,0 +1,129 @@
+# kdrift Knowledge
+
+Kustomize manifest drift detection. Shows exactly what your kustomize edits will change in rendered Kubernetes manifests before you commit, push, or apply.
+
+## Core Concepts
+
+**Leaf overlay**: A kustomization directory that no other kustomization references. These are deployment targets (e.g., `k8s/dev`, `k8s/prod`). Base directories that get referenced by overlays are not leaves.
+
+**Dependency graph**: kdrift builds a reverse dependency map from every file to the leaf overlays that transitively include it. When you edit `k8s/base/deployment.yaml`, kdrift knows which overlays (`k8s/dev`, `k8s/staging`, `k8s/prod`) are affected.
+
+**Baseline vs candidate**: The baseline is the rendered output at a git ref (default: HEAD). The candidate is the rendered output from the working tree (or a second ref). kdrift diffs them per-resource.
+
+**Two-phase resource matching**: Phase 1 matches resources by exact GVK + namespace + name. Phase 2 handles configMapGenerator/secretGenerator hash-suffixed names using the kustomize hash charset (`bcdfghjklmnpqrstvwxz2456789`).
+
+**Two-ref comparison**: Compare any two git refs (`--ref main~5..main~2`) instead of working tree vs HEAD. Uses two temporary worktrees.
+
+## Delivery Surfaces
+
+| Surface | Invocation | Best for |
+|---------|-----------|----------|
+| **CLI** | `kdrift diff` | Terminal workflows, CI/CD, pre-commit hooks |
+| **MCP** | `kdrift mcp` (stdio) | AI agents (Claude Code, etc.) with structured JSON |
+| **LSP** | `kdrift lsp` (stdio) | IDE integration (VS Code, Neovim) with diagnostics on save |
+
+## Configuration
+
+### Project config (`.kdrift.yaml`)
+
+kdrift searches upward from CWD for `.kdrift.yaml`:
+
+```yaml
+kustomize_args:
+  - "--enable-helm"
+  - "--load-restrictor"
+  - "LoadRestrictionsNone"
+```
+
+Search order: project directory, parent directories, `$XDG_CONFIG_HOME/kdrift/`.
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `KDRIFT_LOG_LEVEL` | `WARNING` | Log level (DEBUG, INFO, WARNING, ERROR) |
+| `KDRIFT_LOG_FORMAT` | `json` | Log format (`json` or `console`) |
+
+### MCP configuration
+
+Add to your agent's MCP config (e.g., `.claude.json`, `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "kdrift": {
+      "command": "kdrift",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### LSP configuration (VS Code)
+
+Using the Generic LSP Client (glspc) extension:
+
+```json
+{
+  "glspc.serverCommand": "kdrift",
+  "glspc.serverCommandArguments": ["lsp"]
+}
+```
+
+Add `--debug` to enable file logging to `~/.cache/kdrift/kdrift.log`.
+
+## MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| `kdrift_diff` | Diff overlays against a baseline ref. Returns per-overlay, per-resource structured JSON. Supports `target_ref` for two-ref comparison. |
+| `kdrift_discover` | Find leaf overlays. Defaults to git-changed overlays; `show_all=true` for the full list. |
+| `kdrift_affected` | Given a list of changed files, find which overlays are affected. |
+| `kdrift_render` | Render a single overlay to YAML. |
+
+## Output Structure
+
+All tools return JSON. The diff result structure:
+
+```json
+{
+  "ref": "abc1234",
+  "target_ref": null,
+  "overlays": [
+    {
+      "path": "k8s/dev",
+      "changes": [
+        {
+          "resource_id": {
+            "group": "apps", "version": "v1", "kind": "Deployment",
+            "namespace": "myapp", "name": "api-server"
+          },
+          "status": "modified",
+          "diff_text": "...",
+          "lines_added": 1,
+          "lines_removed": 1
+        }
+      ],
+      "error": null
+    }
+  ]
+}
+```
+
+Status values: `modified`, `added`, `removed`.
+
+## Error Handling
+
+When `kustomize build` fails for one overlay, kdrift reports the error and continues with others. The `error` field is set per-overlay. Exit code is non-zero if any overlay errored.
+
+Baseline build failures (the ref version was already broken) are reported as `"baseline build failed (pre-existing)"` to distinguish from regressions you introduced.
+
+## Caching
+
+Baseline renders are cached at `~/.cache/kdrift/` keyed by ref SHA + overlay path + kustomize version + args. Working tree renders are never cached.
+
+## Prerequisites
+
+- `kustomize` binary on PATH (kdrift shells out to it, does not embed kustomize)
+- Git repository with at least one commit
+- Python 3.13+ (for installation via `uv tool install`)