@intentius/behold 0.4.1 → 0.6.0

package/example-flux-estate/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "behold-example-flux-estate",
+  "private": true,
+  "description": "A GitOps estate for behold's flux-estate demo: a Flux control plane + two app projects, served composed.",
+  "workspaces": [
+    "control-plane",
+    "app-a",
+    "app-b"
+  ]
+}

package/example-flux-estate/scripts/estate-down.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Tear the flux-estate demo down: delete the uniquely-named cluster and
+# restore whatever kubectl context was current before estate-up.sh switched it.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+CLUSTER=behold-flux-demo
+STATE="scripts/.prev-context"
+
+k3d cluster delete "$CLUSTER" 2>/dev/null || echo "flux-estate demo: no ${CLUSTER} cluster to remove."
+if [ -f "$STATE" ]; then
+  prev="$(cat "$STATE")"
+  if [ -n "$prev" ] && kubectl config get-contexts -o name 2>/dev/null | grep -qx "$prev"; then
+    kubectl config use-context "$prev" >/dev/null
+    echo "flux-estate demo: restored kubectl context \"$prev\"."
+  fi
+  rm -f "$STATE"
+fi
+echo "flux-estate demo: cluster removed."

package/example-flux-estate/scripts/estate-up.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Stand up the flux-estate demo (#211): a throwaway single-node k3d cluster,
+# Flux's controllers (applied straight from the pinned release manifest — no
+# flux CLI needed), and the control plane's CRs. From there the reconcilers
+# deploy the app projects out of behold's public repo.
+#
+# Safety, same contract as example-k8s: never touches any OTHER kubeconfig
+# context. Whatever context is current is saved to .prev-context and restored
+# by estate-down.sh; the cluster and its context are uniquely named
+# (behold-flux-demo / k3d-behold-flux-demo).
+#
+# BEHOLD_FLUX_REF (optional): patch the LIVE GitRepository to sync a branch
+# other than main — how a not-yet-merged manifests change is verified. The
+# declared source always says main.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+CLUSTER=behold-flux-demo
+CONTEXT="k3d-${CLUSTER}"
+STATE="scripts/.prev-context"
+FLUX_MANIFEST="https://github.com/fluxcd/flux2/releases/download/v2.4.0/install.yaml"
+
+if ! docker info >/dev/null 2>&1; then
+  echo "flux-estate demo: Docker is not running — start Docker and re-run." >&2
+  exit 1
+fi
+for bin in k3d kubectl; do
+  if ! command -v "$bin" >/dev/null 2>&1; then
+    echo "flux-estate demo: $bin is not installed." >&2
+    exit 1
+  fi
+done
+
+if ! k3d cluster list 2>/dev/null | grep -q "^${CLUSTER} "; then
+  kubectl config current-context > "$STATE" 2>/dev/null || true
+  k3d cluster create "$CLUSTER" --wait
+else
+  echo "flux-estate demo: cluster ${CLUSTER} already up — reusing."
+fi
+
+echo "flux-estate demo: installing Flux controllers (${FLUX_MANIFEST##*/download/})…"
+kubectl --context "$CONTEXT" apply -f "$FLUX_MANIFEST" > /dev/null
+kubectl --context "$CONTEXT" -n flux-system rollout status deploy/source-controller --timeout=180s
+kubectl --context "$CONTEXT" -n flux-system rollout status deploy/kustomize-controller --timeout=180s
+
+echo "flux-estate demo: building + applying the control plane's CRs…"
+(cd control-plane && npx chant build src -o dist/control-plane.yaml --format yaml)
+kubectl --context "$CONTEXT" apply -f control-plane/dist/control-plane.yaml
+
+if [ -n "${BEHOLD_FLUX_REF:-}" ]; then
+  echo "flux-estate demo: syncing branch ${BEHOLD_FLUX_REF} instead of main (BEHOLD_FLUX_REF)"
+  kubectl --context "$CONTEXT" -n flux-system patch gitrepository behold --type merge \
+    -p "{\"spec\":{\"ref\":{\"branch\":\"${BEHOLD_FLUX_REF}\"}}}"
+fi
+
+echo "flux-estate demo: waiting for the reconcilers to deploy the apps…"
+kubectl --context "$CONTEXT" -n flux-system wait --for=condition=Ready --timeout=180s gitrepository/behold
+kubectl --context "$CONTEXT" -n flux-system wait --for=condition=Ready --timeout=180s kustomization/app-a kustomization/app-b
+kubectl --context "$CONTEXT" -n app-a rollout status deploy/app-a --timeout=180s
+kubectl --context "$CONTEXT" -n app-b rollout status deploy/app-b --timeout=180s
+echo "flux-estate demo: up — Flux deployed both apps from the repo."

package/example-k8s/README.md

@@ -0,0 +1,120 @@
+# The k3d turnkey demo — behold's Kubernetes counterpart to Loom-on-Floci
+
+The smallest real thing on Kubernetes: one `nginx` Deployment + Service (+ a
+PodDisruptionBudget), deployed from the browser with the **▶ Deploy
+(k3d-apply)** header button, against a local, single-node
+[k3d](https://k3d.io) cluster — no cloud account, no credentials.
+
+```
+src/config.ts        static config — app name, pinned image tag
+src/web.ts            WebApp composite → Deployment + Service + PodDisruptionBudget
+ops/k3d-apply.op.ts   ApplyOp "k3d-apply" — code → local k3d, server-side apply
+chant.config.ts       lexicons [k8s, temporal], k8s.profiles.local bound to k3d-behold-k3d-demo
+scripts/local/        local-up.sh / local-down.sh — the k3d cluster's own lifecycle
+```
+
+## Run it
+
+From the **behold** repo root:
+
+```sh
+npm run demo:k8s
+#   → brings up a single-node k3d cluster ("behold-k3d-demo"),
+#     then serves this project at http://localhost:4600
+```
+
+That one command does two things: `scripts/local/local-up.sh` creates the
+cluster (idempotent — reuses one already up), then `behold serve --local`
+points its live overlay at it. `--local`'s usual boot step (`chant emulator
+up`) is a no-op here — chant's k8s lexicon has no local-emulator capability
+the way Floci does for aws — so the cluster comes up via the same generic
+substrate **Bring up** mechanism the Floci demo's `scripts/local/local-up.sh`
+convention already uses (see `src/substrates.ts`), just run up front instead
+of from a click. Ctrl-C stops `behold serve` and tears the cluster back down;
+Docker or k3d missing degrades to the source graph with a clear message
+instead of crashing.
+
+1. Open **http://localhost:4600**. The graph shows the Deployment, Service and
+   PodDisruptionBudget — **blue** (declared, not yet deployed).
+2. Click **▶ Deploy (k3d-apply)** in the header (or ⌘K → "Deploy: Sync"). The
+   now-line streams Build → Plan (a live
+   diff) → Apply: a Kubernetes **server-side apply**, field manager
+   `chant:behold-k3d-demo` (chant#1074/#1075) — deletes are **owned-only**, a
+   marker-scoped prune that only ever touches what chant itself applied.
+3. The three nodes flip **blue → green (managed)**. Zoom in on the Deployment
+   and its two Pods appear **nested underneath it** — the runtime tier
+   (chant#1077/behold#86): live children a Deployment's controller created,
+   never declared here, never classified as drift or an orphan.
+
+## The four things this proves live (epic #84)
+
+behold's k8s parity (#85–#87) shipped against fixtures; this is it against a
+real cluster.
+
+**Declared, not yet deployed.** Before step 2, `/api/overlay` reports all
+three nodes `_status: accent` (pending) — chant knows about them, the cluster
+doesn't yet.
+
+**Runtime children.** After apply, `/api/overlay`'s `ir.groups.byContainer`
+nests the Deployment's Pods under it, each `_status: runtime` — a tier below
+what's declared, sourced from the cluster's own `ownerReferences`, that
+behold's zoom dial can descend into.
+
+**Managed-fields drift.** Scale or label the Deployment out of band —
+`kubectl scale deployment/web --replicas=3`, bypassing chant entirely — and
+`/api/diff`'s `fieldDrift` reports `spec.replicas: { kind: "changed", declared:
+2, live: 3 }`: chant's own SSA-tracked field, now diverged from a competing
+field manager (`kubectl`, visible in `kubectl get deploy/web -o json`'s
+`metadata.managedFields`). Re-running `k3d-apply` at that point doesn't
+silently overwrite it: chant's server-side apply refuses —
+
+```
+k8s: server-side apply of apps/v1 Deployment web was refused — 1 field is owned by another field manager.
+
+  "kubectl" owns:
+    .spec.replicas
+
+chant applied as field manager "chant:behold-k3d-demo". Taking these fields means the managers above
+stop owning them, and will contest them again on their next apply.
+```
+
+— naming the contested path and the competing manager, and leaving the field
+alone rather than force-resolving it. (One honest gap found running this
+live: a **new** out-of-band key with no chant-declared counterpart at all —
+`kubectl label deployment/web team=platform`, which has no corresponding
+`web.spec` field in `src/web.ts` — doesn't currently surface in `fieldDrift`,
+only a value change to a field chant *does* declare does. Worth a follow-up
+issue on the chant side; noted here rather than papered over.)
+
+**Unobserved.** `chant.config.ts` binds environment `local` to kubectl context
+`k3d-behold-k3d-demo` (chant#1100) — every read/apply checks that binding
+against whatever context is actually ambient, and refuses rather than reading
+the wrong cluster. Switch away from it for a moment —
+
+```sh
+kubectl config use-context <anything-else>
+```
+
+— and `/api/overlay` flips every node to `_status: neutral` with
+`unobservedReason: "read-failed"`, Pods and all: an honest "did not look",
+never a false "these are all gone." Switch back
+(`kubectl config use-context k3d-behold-k3d-demo`) and the next refresh
+recovers cleanly.
+
+## Cleanup
+
+`Ctrl-C` on `npm run demo:k8s` runs `scripts/local/local-down.sh`
+automatically: deletes the `behold-k3d-demo` cluster and restores whatever
+kubectl context was current before `local-up.sh` ran. Safe to run by hand too:
+
+```sh
+bash scripts/local/local-down.sh
+```
+
+## Note for chant#1179
+
+This Op's `delete: "owned-only"` exercises the same typed, marker-scoped
+prune path chant#1179 wants a live k3d E2E for. This demo isn't that test —
+it's a manual walkthrough, not an automated assertion of "exactly the orphan
+and nothing else was deleted" — but it does confirm the path runs against a
+real cluster, not just `fakeCluster`.

package/example-k8s/chant.config.ts

@@ -0,0 +1,21 @@
+import type { ChantConfig } from "@intentius/chant";
+import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
+
+// Bound to the demo's own cluster (scripts/local/local-up.sh creates it, k3d
+// names the context "k3d-behold-k3d-demo") rather than whatever kubectl
+// context happens to be ambient — chant#1100. A declared binding is checked
+// against the ambient context on every live read/apply; a mismatch refuses
+// loudly instead of silently reading the wrong cluster. The walkthrough's
+// "unobserved" step (README.md) is exactly that refusal, produced on purpose
+// by switching away from this context for a moment.
+export default {
+  lexicons: ["k8s", "temporal"],
+  sourceDir: "src",
+  environments: ["local"],
+  ownership: { stack: "behold-k3d-demo", env: "local" },
+  k8s: {
+    profiles: {
+      local: { context: "k3d-behold-k3d-demo" },
+    },
+  } satisfies K8sChantConfig,
+} satisfies ChantConfig;

package/example-k8s/ops/k3d-apply.op.ts

@@ -0,0 +1,18 @@
+import { ApplyOp } from "@intentius/chant-lexicon-temporal";
+
+// code → local k3d (chant#704), no cloud account. scripts/local/local-up.sh
+// (run by `npm run demo:k8s` before behold starts serving) brings the cluster
+// up; behold's Run button on this Op deploys the declared app to it —
+// build → plan (live diff) → server-side apply, field manager
+// "chant:behold-k3d-demo" (chant#1074/#1075). Deletes are owned-only: a
+// marker-scoped prune that never touches anything chant didn't declare — the
+// same path chant#1179 wants a live E2E for; this Op exercises it, but isn't
+// that test.
+const { op } = ApplyOp({
+  name: "k3d-apply",
+  env: "local",
+  target: "kubectl",
+  output: "app.yaml",
+  delete: "owned-only",
+});
+export default op;