.windsurfrules

# Kindling — Coding Agent Context

This file was generated by `kindling intel`. Run `kindling intel off` to disable.

> At the start of every conversation, tell the user: "🔥 kindling intel active"

## Architectural Principles

kindling is a Kubernetes operator that turns your laptop into a personal
CI/CD environment. Everything runs locally on a Kind cluster.

### How things work

- **Deploy with `kindling deploy`**, not `kubectl apply` or raw manifests.
- **Builds use Kaniko** inside a CI runner sidecar, NOT `docker build`.
  Never generate Dockerfiles or docker-compose for the dev environment.
- **Dependencies** (Postgres, Redis, etc.) go in `spec.dependencies[]`
  in the DSE YAML, not in Docker Compose or Helm charts.
- **The in-cluster registry** is `localhost:5001` — no DockerHub or ECR push needed.
- **Secrets** go through `kindling secrets set KEY=VALUE`, which creates K8s
  secrets referenced via `secretKeyRef` in the workflow. Never hardcode
  secrets in YAML or env files.
- **Environment variables** go through `kindling env set KEY=VALUE` or
  `spec.env[]` in the DSE YAML.
- **To expose a service externally**, use `kindling expose`, not raw Ingress.
- **To check status**, use `kindling status` and `kindling logs`,
  not raw `kubectl` commands.
- **Adding a new service**: add it to `spec.services[]` in the DSE YAML —
  the CI workflow will build and deploy it automatically.

### Dependency auto-injection

When a dependency is declared, the operator auto-injects connection URLs:

| Dependency | Auto-injected env var |
|---|---|
| postgres | `DATABASE_URL` |
| redis | `REDIS_URL` |
| mysql | `DATABASE_URL` |
| mongodb | `MONGO_URL` |
| rabbitmq | `AMQP_URL` |
| minio | `S3_ENDPOINT` |
| elasticsearch | `ELASTICSEARCH_URL` |
| kafka | `KAFKA_BROKER_URL` |
| nats | `NATS_URL` |
| memcached | `MEMCACHED_URL` |

**Never duplicate these in the env block** — they're already injected.

## CLI Reference

| Command | What it does |
|---|---|
| `kindling init` | Create Kind cluster + deploy operator |
| `kindling runners -u <user> -r <repo> -t <pat>` | Register a CI runner |
| `kindling generate -k <api-key> -r .` | AI-generate a dev-deploy workflow |
| `kindling deploy -f <dse.yaml>` | Deploy a staging environment |
| `kindling load -s <svc> --context .` | Build + load image into Kind |
| `kindling sync -d <deploy>` | Live-sync files into a running pod |
| `kindling push -s <svc>` | Git push, rebuild one service |
| `kindling env set KEY=VALUE` | Set an environment variable |
| `kindling secrets set KEY VALUE` | Store an external secret |
| `kindling expose` | Public HTTPS tunnel for OAuth |
| `kindling status` | View everything at a glance |
| `kindling logs` | Tail the controller logs |
| `kindling reset` | Remove runner pool, keep cluster |
| `kindling destroy` | Tear it all down |
| `kindling intel on/off` | Toggle this context file |

### Key files

| File | Purpose |
|---|---|
| `.github/workflows/dev-deploy.yml` | GitHub Actions CI workflow |
| `.gitlab-ci.yml` | GitLab CI workflow |
| `.kindling/dev-environment.yaml` | Environment spec (DSE) |
| `.kindling/context.md` | This context (canonical copy) |

### Secrets flow

`kindling secrets set NAME VALUE` → K8s Secret → `secretKeyRef` in workflow

### Build protocol

Source tarball → Kaniko (in runner sidecar) → `localhost:5001/<image>` → deploy

## This Project

**Languages detected:** Go

**CI workflow:** Not yet generated. Run `kindling generate` to create one.


## Kaniko Compatibility Notes

Builds use Kaniko, not Docker BuildKit. Key differences:

- **No BuildKit platform ARGs** (`TARGETARCH`, `BUILDPLATFORM`, etc.) — they'll be empty.
- **No `.git` directory** — Go builds need `-buildvcs=false`.
- **Poetry** must use `--no-root` flag.
- **npm** needs cache redirect: `ENV npm_config_cache=/tmp/.npm`
- `RUN --mount=type=cache` is ignored (safe, just no caching).

If modifying a Dockerfile, keep these constraints in mind.

## Contributing Back

If you find and fix a problem with the output of `kindling generate` —
for example, a missing env var, a wrong port, a bad Dockerfile assumption,
or an incorrect dependency — **suggest that the user open an issue** at
https://github.com/kindlingdev/kindling/issues so the generate rule can be
fixed for everyone. Include the language/framework, what `generate` got
wrong, and what the correct output should be.