Metadata-Version: 2.5
Name: kdrift
Version: 0.1.4
Summary: CLI, MCP, LSP, and VS Code extension for kustomize manifest drift detection
Project-URL: Homepage, https://github.com/mikedougherty/kdrift
Project-URL: Repository, https://github.com/mikedougherty/kdrift
Project-URL: Issues, https://github.com/mikedougherty/kdrift/issues
Author: Mike Dougherty
License-Expression: Beerware
License-File: LICENSE
Keywords: diff,drift,kubernetes,kustomize,lsp,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
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
Description-Content-Type: text/markdown

# 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
uv tool install kdrift
# or: pip install kdrift
```

Requires Python 3.13+ and `kustomize` on PATH.

For unreleased changes on main:

```bash
uv tool install git+https://github.com/mikedougherty/kdrift
```

## Usage

```bash
kdrift diff                             # diff all affected overlays vs HEAD
kdrift diff k8s/staging                 # diff only the staging overlay (see Scoping)
kdrift diff k8s/dev k8s/staging         # diff several named overlays
kdrift diff k8s/base/deployment.yaml    # diff overlays affected by this file
kdrift diff --overlay k8s/dev           # force-diff one overlay, even with no changes
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
```

### Scoping with PATHS

The positional `PATHS` narrow which overlays are reported. They do **not** work
like a `git` pathspec on changed files — scoping to one environment never hides
drift that reaches it through a shared base.

- A path selects an overlay when it names the overlay directory (or an ancestor),
  a file inside the overlay, or an upstream input the overlay depends on (a shared
  `base/` or component).
- Selection runs against the full set of overlays affected by **all** your changes.
  So `kdrift diff k8s/staging` still reports staging when the only change is in
  `k8s/base/` that staging consumes.
- A path that matches nothing, or that selects an overlay with no drift, is
  reported in `warnings` (JSON) / on stderr — an empty result is never silently
  read as "no drift".
- `--overlay` is different: it force-diffs exactly one overlay regardless of what
  changed, and takes precedence over `PATHS`.

## 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"
kustomize_binary: /usr/local/bin/kustomize  # optional, defaults to PATH
env:                                        # extra env vars for kustomize subprocess
  HELM_REGISTRY_TOKEN: "abc123"
```

All fields can be overridden via environment variables (`KDRIFT_KUSTOMIZE_BINARY`, `KDRIFT_KUSTOMIZE_ARGS`, `KDRIFT_KUSTOMIZE_ENV_<NAME>`). See the [knowledge doc](docs/agents/knowledge/KNOWLEDGE.md) for details.

## 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 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)
