Build spind VM orchestration tooling

Author: suin

.editorconfig

@@ -0,0 +1,20 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = tab
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{js,jsx,ts,tsx}]
+indent_style = space
+max_line_length = 100
+
+[*.{json,yaml,yml,toml}]
+indent_style = space
+
+[*.md]
+trim_trailing_whitespace = false
+indent_style = space

.envrc

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+# Automatically sets up your devbox environment whenever you cd into this
+# directory via our direnv integration:
+
+eval "$(devbox generate direnv --print-envrc)"
+
+# check out https://www.jetify.com/docs/devbox/ide_configuration/direnv/
+# for more details

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: jetify-com/devbox-install-action@8c6a66ed6273138b1915457069de78cb52fe3bd7 # v0.15.0
+        with:
+          enable-cache: "true"
+      - run: devbox run -- task ci
+
+  ci-macos:
+    runs-on: macos-15-intel
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: jetify-com/devbox-install-action@8c6a66ed6273138b1915457069de78cb52fe3bd7 # v0.15.0
+        with:
+          enable-cache: "true"
+      - run: devbox run -- task ci:macos

.gitignore

@@ -0,0 +1,18 @@
+bin/
+node_modules/
+js/
+dist/
+*.tsbuildinfo
+coverage/
+*.lcov
+logs/
+*.log
+.env
+.env.*
+!.env.example
+!.envrc
+.cache/
+.DS_Store
+.review/
+result
+.devbox/

README.md

@@ -0,0 +1,129 @@
+# spind
+
+spind is a fast local development environment for people who build web applications that use the Kubernetes API, and for people who build Kubernetes Operators.
+
+It supports kind-based Kubernetes environments and makes clean environments fast to create, reset, and start.
+
+## Why spind?
+
+Kubernetes development and testing often need a clean Kubernetes environment. Creating that environment every time is slow.
+
+Common setup steps can take seconds or minutes:
+
+- `kind create cluster` can take about 30 seconds.
+- `helm install` can take several minutes.
+- End-to-end tests and integration tests often need a clean cluster.
+- CI runs can spend several minutes only preparing the environment.
+
+During development, you often create an environment, test something, break it, delete it, and create it again. That wait makes the development loop slow.
+
+spind reduces setup time from minutes to less than 1000 ms by restoring a ready VM snapshot.
+
+This makes development, manual checks, end-to-end tests, integration tests, CI, and CD faster.
+
+## How it works
+
+spind is built around microVMs and snapshots.
+
+On macOS, spind starts a small Linux VM with Virtualization.framework. On Linux, spind starts a small Linux VM with Cloud Hypervisor.
+
+The Linux VM is not a special Kubernetes system. It is a small Docker machine. You can use your normal Docker client, kind, kubectl, and helm.
+
+spind sets up the runtime VM once, then saves that ready state as a snapshot. After that, spind restores from the snapshot. This lets you start an environment where the kind cluster and Helm charts are already prepared.
+
+## Use cases
+
+- Web applications that use the Kubernetes API
+- Kubernetes Operator development
+- Local Kubernetes development with kind
+- Clean environments for end-to-end tests and integration tests
+- Faster Kubernetes environment setup in CI/CD
+
+## Install
+
+Install spind with `go install`.
+
+```sh
+go install github.com/suin/spind/cmd/spind@latest
+```
+
+After installing, check your host dependencies.
+
+```sh
+spind doctor
+```
+
+## Dependencies
+
+`spind doctor` checks the dependencies needed on your current host. This section gives the basic list.
+
+Common:
+
+- Go
+- Docker CLI
+
+macOS:
+
+- Apple Swift compiler
+- `codesign`
+- Xcode Command Line Tools
+- A macOS environment that supports Virtualization.framework
+
+Linux:
+
+- A Linux environment with KVM support
+- `/dev/kvm`
+- `cloud-hypervisor`
+- `passt`
+- `virtiofsd`
+
+Docker image builds need the Docker CLI. On Linux, `passt` and `virtiofsd` are also used for Docker host support, snapshot restore support, and host path sharing.
+
+## Basic usage
+
+Put `spind.yaml` in your project root.
+
+```yaml
+name: sample
+image: docker
+kind: true
+setup:
+  - "kind create cluster"
+  - "kubectl --context kind-kind wait node --all --for=condition=Ready --timeout=180s"
+```
+
+Start the development environment.
+
+```sh
+spind up
+```
+
+On the first run, spind creates a VM, runs the commands in `setup`, and saves the ready state as a snapshot. Later runs restore from that snapshot.
+
+## Development
+
+Use these commands when working on this repository.
+
+```sh
+task build
+task check
+task test
+task test:ts
+```
+
+Run end-to-end tests:
+
+```sh
+task e2e
+```
+
+## Design docs
+
+Detailed design notes are in `docs/design/`.
+
+- `docs/design/minimum-cli.md`
+- `docs/design/project-up.md`
+- `docs/design/docker-host.md`
+- `docs/design/kind-ready-snapshot.md`
+- `docs/design/snapshot.md`
+- `docs/design/roadmap.md`

Taskfile.yml

@@ -0,0 +1,99 @@
+version: "3"
+
+vars:
+  BIN_DIR: bin
+  SPIND_BIN: "{{.BIN_DIR}}/spind"
+  GUEST_AGENT_BIN: "{{.BIN_DIR}}/spind-guest-agent"
+
+tasks:
+  default:
+    desc: List available tasks
+    cmds:
+      - task --list
+
+  # Quality gates
+  check:
+    desc: Run all checks
+    cmds:
+      - task: format:check
+      - task: lint
+      - task: typecheck
+      - task: test
+
+  ci:
+    desc: Run CI pipeline (frozen install + all checks)
+    cmds:
+      - bun install --frozen-lockfile
+      - task: check
+
+  ci:macos:
+    desc: Run macOS CI pipeline (frozen install + e2e)
+    cmds:
+      - bun install --frozen-lockfile
+      - task: e2e
+
+  format:
+    desc: Format source files
+    cmds:
+      - bunx oxfmt --write .
+
+  format:check:
+    desc: Check source formatting
+    cmds:
+      - bunx oxfmt --check .
+
+  lint:
+    desc: Run the linter
+    cmds:
+      - bunx oxlint
+
+  test:
+    desc: Run Go tests
+    cmds:
+      - go list ./... | grep -v '/node_modules/' | xargs go test
+
+  typecheck:
+    desc: Type check without emitting
+    cmds:
+      - bunx tsc -b --noEmit
+
+  # Build tasks
+  build:
+    desc: Build local spind binaries
+    cmds:
+      - mkdir -p {{.BIN_DIR}}
+      - go build -o {{.SPIND_BIN}} ./cmd/spind
+      - CGO_ENABLED=0 GOOS=linux GOARCH="$(go env GOARCH)" go build -o {{.GUEST_AGENT_BIN}} ./cmd/agent
+      - |
+        if [ "$(uname -s)" = "Darwin" ]; then
+          {{.SPIND_BIN}} prepare-vz-runner
+        else
+          echo "skipping managed Virtualization.framework runner build on $(uname -s)"
+        fi
+
+  build:ts:
+    desc: Build TypeScript files
+    cmds:
+      - bunx tsc -b
+
+  build-image-docker:
+    desc: Build the Docker image
+    deps:
+      - build
+    cmds:
+      - "{{.SPIND_BIN}} image build docker --force"
+
+  clean:
+    desc: Clean build artifacts
+    cmds:
+      - rm -rf js *.tsbuildinfo
+
+  # End-to-end tests
+  e2e:
+    desc: Run end-to-end tests
+    deps:
+      - build-image-docker
+    cmds:
+      - bun test tests/e2e --timeout 2700000 --bail
+    env:
+      EXECA_VERBOSE: short # "short" | "full" | "none"