feat(domain): add cluster entity, agent, cli, and web ui for kubernetes management

[arielshad]

Summary

Introduces a new first-class Cluster domain entity alongside Repository, Application, and Feature. A Cluster represents a managed Kubernetes environment (k3s-in-Docker) that the Shep platform provisions and operates autonomously. This is an XL feature spanning all architecture layers — domain model through web UI.

What's included

• TypeSpec domain model: Cluster entity (extending SoftDeletableEntity), ClusterStatus enum (6 lifecycle states), ClusterRepository and ClusterApplication junction entities for many-to-many relationships
• Persistence layer: 4 SQLite migrations (clusters table, junction tables, feature flag column), cluster mapper with camelCase-to-snake_case conversion, full SQLiteClusterRepository implementation
• Application layer: 12 use cases (CRUD, link/unlink repos and apps, provision, destroy, status), 4 port interfaces (IK3dService, IKubectlService, IArgoCDService, IDockerHealthService)
• Infrastructure services: K3d, Kubectl, ArgoCD, and DockerHealth service implementations wrapping CLI tools via execFile
• Cluster agent: LangGraph state machine with 6 nodes (prerequisite-check, provision, configure-kubectl, install-argocd, health-check, ready), detached worker process with heartbeat reporting
• CLI: shep cluster command group with 7 subcommands (new, ls, show, del, link, unlink, status)
• Web UI: ClusterNode canvas component, ClusterStatusBadge, ClusterCreateDrawer, ClusterDetailDrawer with tabs, sidebar navigation (gated by feature flag), SSE event support, server actions, API routes
• Feature flag: clusters flag wired through all layers (TypeSpec, migration, mapper, repository, settings defaults, web feature-flags, translations in all 9 locales)
• DI wiring: New register-cluster.ts module registering all cluster components in the tsyringe container
• Full test coverage: Unit tests for all use cases, mappers, factories, services; integration tests for SQLite repository and migrations

Key design decisions

• k3d for provisioning (not raw Docker + k3s) — eliminates Docker orchestration code
• Single-node clusters in v1 — multi-node deferred, nodeCount field reserved
• Junction tables for many-to-many relationships (follows work_item_relations pattern)
• ArgoCD opt-in per cluster — avoids overhead for simple dev clusters
• Terraform deferred to v2 — core value is k8s management, not cloud IaC
• Feature flag gates UI only — domain model and persistence always present

Evidence

Artifact	Description
Unit tests	524 test files, 6735 tests passing
Integration tests	59 test files, 793 tests passing
Typecheck	tsc --noEmit passes with zero errors
Build	pnpm build succeeds
Lint	eslint --max-warnings 0 passes
CLI commands	Full cluster workflow (create, list, show, status, delete)
	Clusters feature flag in settings
	All 6 ClusterStatus states in Storybook
	Control center canvas with cluster integration

Test plan

• pnpm typecheck passes (zero errors)
• pnpm lint passes (zero warnings)
• pnpm build succeeds
• pnpm test:unit — 6735 tests pass across 524 files
• pnpm test:int — 793 tests pass across 59 files
• CI pipeline validates all checks
• Manual verification: shep cluster new test-cluster --argocd creates cluster entity
• Manual verification: Settings > Flags shows Clusters toggle
• Manual verification: Storybook renders all cluster components

🐑 Built with Shep.bot

[github-actions]

Dev Release Published

Artifact	Version	Install
npm	1.188.0-pr566.655e28f	npm install -g @shepai/cli@1.188.0-pr566.655e28f

---

_{Published from commit b41f857 | View CI}

[github-actions]

Dev Release Published

Artifact	Version	Install
npm	1.188.0-pr566.0fb60a1	npm install -g @shepai/cli@1.188.0-pr566.0fb60a1

---

_{Published from commit 7e47ccc | View CI}