@intentius/behold 0.5.0 → 0.7.0

package/demos.json

@@ -17,6 +17,15 @@
       "setup": "bash scripts/local/local-up.sh",
       "serve": { "local": true, "env": "local" }
     },
+    {
+      "name": "flux-estate",
+      "description": "A GitOps estate: a Flux control plane (GitRepository + Kustomizations) plus two app projects, served as one composed estate — cross-stack sourceRef edges, estate-wide drift, and the namespace-mismatch note on purpose (app-b uses targetNamespace). k3d + Flux, no cloud. scripts/estate-down.sh removes the cluster.",
+      "source": "bundled",
+      "dir": "example-flux-estate",
+      "requires": ["docker", "k3d", "kubectl"],
+      "setup": "bash scripts/estate-up.sh",
+      "serve": { "env": "local", "dirs": ["control-plane", "app-a", "app-b"] }
+    },
     {
       "name": "fountain",
       "description": "The mature estate: self-hosted fountain (a real app) on a throwaway k3d cluster — tiers (try the ha tier picker), seams, drift, runtime Pods. Clones INTENTIUS/fountain-ops; ~5 minutes, mostly image pulls. `just down` in the clone removes the cluster.",

package/dist/cli.js

@@ -1972,6 +1972,12 @@ import { join as join6 } from "node:path";
 function overlayBoxTitle(name) {
   return `overlay ${name}`;
 }
+var ROOT_ANNOTATION = "chant.intentius.io/kustomize-root";
+function annotatedRoot(node) {
+  const metadata2 = node.attrs?.metadata;
+  const v = metadata2?.annotations?.[ROOT_ANNOTATION];
+  return typeof v === "string" && v ? v : void 0;
+}
 function dirOf2(node) {
   const file = node.sourceLoc?.file;
   if (typeof file !== "string") return "";
@@ -2002,12 +2008,15 @@ function projectKustomizeLogical(ir, sourceRoots, exists = existsSync5) {
   };
   const rootCache = /* @__PURE__ */ new Map();
   for (const n of k8s) {
-    const dir = dirOf2(n);
-    if (dir === "") continue;
-    if (!rootCache.has(dir)) rootCache.set(dir, kustomizationRoot(bases, dir, exists));
-    const root = rootCache.get(dir);
+    let root = annotatedRoot(n);
+    if (root === void 0) {
+      const dir = dirOf2(n);
+      if (dir === "") continue;
+      if (!rootCache.has(dir)) rootCache.set(dir, kustomizationRoot(bases, dir, exists));
+      root = rootCache.get(dir);
+    }
     if (root === void 0) continue;
-    const name = root.split("/").pop() || root;
+    const name = root.replace(/\/+$/, "").split("/").pop() || root;
     child(overlayBoxTitle(name), n.id);
   }
   return { ir: { nodes: [], edges: [], groups: {} }, byContainer };
@@ -2593,7 +2602,7 @@ function namespaceMismatchNote(nodes) {
   const k8s = nodes.filter((n) => n?.lexicon === "k8s");
   if (k8s.length === 0) return void 0;
   const pending = k8s.filter((n) => n.attrs?._status === "accent" && !CLUSTER_SCOPED.has(n.kind ?? ""));
-  if (pending.length < 3) return void 0;
+  if (pending.length < 2) return void 0;
   if (pending.some((n) => typeof n.attrs?.metadata?.namespace === "string" && n.attrs.metadata.namespace)) return void 0;
   if (!k8s.some((n) => n.attrs?._status === "good")) return void 0;
   return `${pending.length} pending k8s objects declare no metadata.namespace \u2014 if a controller stamps it at apply time (e.g. Flux's targetNamespace), the live read looked in "default", not where they run`;
@@ -2984,16 +2993,19 @@ function nodeDiff(json, nodeId) {
     if (drift) return { category: "drifted", changes: drift.changes ?? [] };
     const unobserved = r.unobserved?.find((u) => u.name === nodeId);
     if (unobserved) {
+      const queried = unobserved.queried ?? r.queried?.[nodeId];
       return {
         category: "unobserved",
         changes: [],
         unobservedReason: unobserved.reason,
-        ...unobserved.detail ? { unobservedDetail: unobserved.detail } : {}
+        ...unobserved.detail ? { unobservedDetail: unobserved.detail } : {},
+        ...queried ? { queried } : {}
       };
     }
     const runtimeChild = r.runtimeChildren?.find((rc) => rc.name === nodeId);
     if (runtimeChild) return { category: "runtime", changes: [], runtimeOwner: runtimeChild.owner };
-    if (r.missing?.includes(nodeId)) return { category: "missing", changes: [] };
+    if (r.missing?.includes(nodeId))
+      return { category: "missing", changes: [], ...r.queried?.[nodeId] ? { queried: r.queried[nodeId] } : {} };
     if (r.orphan?.includes(nodeId)) return { category: "orphan", changes: [] };
     if (r.disappeared?.includes(nodeId)) return { category: "disappeared", changes: [] };
     if (r.newlyObserved?.includes(nodeId)) return { category: "newlyObserved", changes: [] };
@@ -4742,6 +4754,8 @@ function loadDemoRegistry(pkgRoot) {
     }
     if (!Array.isArray(d.requires) || d.requires.some((r) => typeof r !== "string")) return false;
     if (!d.serve || typeof d.serve !== "object") return false;
+    if (d.serve.dirs !== void 0 && (!Array.isArray(d.serve.dirs) || d.serve.dirs.some((x) => typeof x !== "string") || !d.serve.dirs.length))
+      return false;
     return true;
   });
 }
@@ -5173,7 +5187,8 @@ async function runDemo(rest) {
   }
   process.stdout.write(`behold demo ${entry.name} \u2192 serving. Blue = declared; Deploy turns it green.
 `);
-  const serveArgs = ["serve", target, "--port", String(port)];
+  const serveDirs = entry.serve.dirs?.length ? entry.serve.dirs.map((d) => join13(target, d)) : [target];
+  const serveArgs = ["serve", ...serveDirs, "--port", String(port)];
   if (entry.serve.local) serveArgs.push("--local");
   if (entry.serve.env) serveArgs.push("--env", entry.serve.env);
   await run3(serveArgs);

package/example-flux-estate/README.md

@@ -0,0 +1,41 @@
+# flux-estate — behold's GitOps estate demo (#211)
+
+Three chant projects served as one composed estate:
+
+- **control-plane/** — the Flux machinery: a `GitRepository` pointing at
+  behold's own public repo and one `Kustomization` per app. The reconcilers
+  deploy the apps; this project never applies a workload itself.
+- **app-a/** — a small web workload with explicit `metadata.namespace` on
+  every object: the fully-resolved half.
+- **app-b/** — the same workload with **no** namespace anywhere: the control
+  plane's `targetNamespace` stamps it at apply time. Idiomatic Flux, and the
+  deliberate exhibit of behold's namespace-mismatch note (behold#192) — a
+  plain live read scopes to `default`, finds nothing, and behold explains the
+  all-pending paint instead of letting it read as "not deployed".
+
+```sh
+npx @intentius/behold demo flux-estate
+```
+
+That stands up a throwaway k3d cluster (`behold-flux-demo`), installs Flux's
+controllers straight from the pinned release manifest (no `flux` CLI needed),
+applies the control plane, waits for the reconcilers to deploy both apps from
+this repo, and serves the three projects composed. What to look at:
+
+- The **estate**: per-project boundary boxes, and the `sourceRef` edges wiring
+  Kustomization → GitRepository across stacks.
+- The **overlay** (env `local`): app-a green, the control plane's CRs green,
+  app-b pending **with the note explaining why**.
+- The **runtime tier** on the control plane alone
+  (`behold serve control-plane --env local`, zoom: runtime): the workloads
+  Flux deployed, attributed back to the declaring Kustomization via its
+  labels (chant#1549).
+
+The app `manifests/` are committed `chant build` output — Flux syncs them
+from GitHub `main`, so changes to an app's source need a rebuild
+(`npm run build` in the app) and a merge before the cluster follows. To
+verify an unmerged branch: `BEHOLD_FLUX_REF=<branch> bash scripts/estate-up.sh`
+patches the live `GitRepository` (the declared source stays `main`).
+
+`bash scripts/estate-down.sh` deletes the cluster and restores your previous
+kubectl context.

package/example-flux-estate/app-a/chant.config.ts

@@ -0,0 +1,18 @@
+import type { ChantConfig } from "@intentius/chant";
+import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
+
+// App project A. Deployed by the control plane's Flux Kustomization, never by
+// this project — its committed manifests/ (chant build output) are what Flux
+// syncs from the repo. behold serves it as part of the estate; the live
+// overlay reads the cluster through the same binding as every other member.
+export default {
+  lexicons: ["k8s"],
+  sourceDir: "src",
+  environments: ["local"],
+  ownership: { stack: "app-a", env: "local" },
+  k8s: {
+    profiles: {
+      local: { context: "k3d-behold-flux-demo" },
+    },
+  } satisfies K8sChantConfig,
+} satisfies ChantConfig;

package/example-flux-estate/app-a/manifests/app.yaml

@@ -0,0 +1,56 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: app-a
+  namespace: app-a
+  labels:
+    app.kubernetes.io/managed-by: chant
+    chant.intentius.io/stack: app-a
+    chant.intentius.io/env: local
+    app: app-a
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: app-a
+  template:
+    metadata:
+      labels:
+        app: app-a
+    spec:
+      containers:
+        - name: web
+          image: nginxinc/nginx-unprivileged:1.27-alpine
+          ports:
+            - containerPort: 8080
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 101
+            allowPrivilegeEscalation: false
+            capabilities:
+              drop:
+                - ALL
+          resources:
+            requests:
+              cpu: '25m'
+              memory: '32Mi'
+            limits:
+              cpu: '100m'
+              memory: '64Mi'
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: app-a
+  namespace: app-a
+  labels:
+    app.kubernetes.io/managed-by: chant
+    chant.intentius.io/stack: app-a
+    chant.intentius.io/env: local
+spec:
+  selector:
+    app: app-a
+  ports:
+    - port: 80
+      targetPort: 8080

package/example-flux-estate/app-a/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "behold-example-flux-app-a",
+  "private": true,
+  "type": "module",
+  "description": "App project A: declares its workload WITH explicit namespaces \u2014 the fully-resolved half of the estate.",
+  "scripts": {
+    "build": "chant build src -o manifests/app.yaml --format yaml"
+  },
+  "dependencies": {
+    "@intentius/chant": "^0.44.2",
+    "@intentius/chant-lexicon-k8s": "^0.44.2"
+  }
+}

package/example-flux-estate/app-a/src/app.ts

@@ -0,0 +1,35 @@
+// App A: one small web workload, namespace declared EXPLICITLY on every
+// object. Contrast app-b, which leaves namespace to the control plane's
+// targetNamespace — the two apps together show both halves of the Flux
+// namespace story (behold#192).
+import { Deployment, Service } from "@intentius/chant-lexicon-k8s";
+
+const labels = { app: "app-a" };
+const image = "nginxinc/nginx-unprivileged:1.27-alpine";
+
+export const deployment = new Deployment({
+  metadata: { name: "app-a", namespace: "app-a", labels },
+  spec: {
+    replicas: 1,
+    selector: { matchLabels: labels },
+    template: {
+      metadata: { labels },
+      spec: {
+        containers: [
+          {
+            name: "web",
+            image,
+            ports: [{ containerPort: 8080 }],
+            securityContext: { runAsNonRoot: true, runAsUser: 101, allowPrivilegeEscalation: false, capabilities: { drop: ["ALL"] } },
+            resources: { requests: { cpu: "25m", memory: "32Mi" }, limits: { cpu: "100m", memory: "64Mi" } },
+          },
+        ],
+      },
+    },
+  },
+});
+
+export const service = new Service({
+  metadata: { name: "app-a", namespace: "app-a" },
+  spec: { selector: labels, ports: [{ port: 80, targetPort: 8080 }] },
+});

package/example-flux-estate/app-a/tsconfig.json

@@ -0,0 +1 @@
+{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "Bundler", "strict": true, "skipLibCheck": true, "noEmit": true }, "include": ["src/**/*", "ops/**/*", "chant.config.ts"] }

package/example-flux-estate/app-b/chant.config.ts

@@ -0,0 +1,20 @@
+import type { ChantConfig } from "@intentius/chant";
+import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
+
+// App project B — the targetNamespace half of the estate: its objects declare
+// no metadata.namespace (see src/app.ts), so the control plane's
+// Kustomization stamps `app-b` at apply time. That is idiomatic Flux, AND it
+// means a plain live read scopes to `default` and finds nothing — behold's
+// namespace-mismatch note (behold#192) names exactly this, on purpose, in
+// this demo.
+export default {
+  lexicons: ["k8s"],
+  sourceDir: "src",
+  environments: ["local"],
+  ownership: { stack: "app-b", env: "local" },
+  k8s: {
+    profiles: {
+      local: { context: "k3d-behold-flux-demo" },
+    },
+  } satisfies K8sChantConfig,
+} satisfies ChantConfig;

package/example-flux-estate/app-b/manifests/app.yaml

@@ -0,0 +1,54 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: app-b
+  labels:
+    app.kubernetes.io/managed-by: chant
+    chant.intentius.io/stack: app-b
+    chant.intentius.io/env: local
+    app: app-b
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: app-b
+  template:
+    metadata:
+      labels:
+        app: app-b
+    spec:
+      containers:
+        - name: web
+          image: nginxinc/nginx-unprivileged:1.27-alpine
+          ports:
+            - containerPort: 8080
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 101
+            allowPrivilegeEscalation: false
+            capabilities:
+              drop:
+                - ALL
+          resources:
+            requests:
+              cpu: '25m'
+              memory: '32Mi'
+            limits:
+              cpu: '100m'
+              memory: '64Mi'
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: app-b
+  labels:
+    app.kubernetes.io/managed-by: chant
+    chant.intentius.io/stack: app-b
+    chant.intentius.io/env: local
+spec:
+  selector:
+    app: app-b
+  ports:
+    - port: 80
+      targetPort: 8080

package/example-flux-estate/app-b/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "behold-example-flux-app-b",
+  "private": true,
+  "type": "module",
+  "description": "App project B: declares NO metadata.namespace \u2014 Flux's targetNamespace stamps it at apply time (the behold#192 shape).",
+  "scripts": {
+    "build": "chant build src -o manifests/app.yaml --format yaml"
+  },
+  "dependencies": {
+    "@intentius/chant": "^0.44.2",
+    "@intentius/chant-lexicon-k8s": "^0.44.2"
+  }
+}

package/example-flux-estate/app-b/src/app.ts

@@ -0,0 +1,37 @@
+// App B: same small workload as app-a, with NO metadata.namespace anywhere —
+// the control plane's Kustomization stamps targetNamespace: app-b at apply
+// time. Idiomatic Flux (that's what the field is for), and the deliberate
+// exhibit of behold's namespace-mismatch note (behold#192): a plain live read
+// scopes to `default`, finds nothing, and behold explains the all-pending
+// paint instead of letting it read as "not deployed".
+import { Deployment, Service } from "@intentius/chant-lexicon-k8s";
+
+const labels = { app: "app-b" };
+const image = "nginxinc/nginx-unprivileged:1.27-alpine";
+
+export const deployment = new Deployment({
+  metadata: { name: "app-b", labels },
+  spec: {
+    replicas: 1,
+    selector: { matchLabels: labels },
+    template: {
+      metadata: { labels },
+      spec: {
+        containers: [
+          {
+            name: "web",
+            image,
+            ports: [{ containerPort: 8080 }],
+            securityContext: { runAsNonRoot: true, runAsUser: 101, allowPrivilegeEscalation: false, capabilities: { drop: ["ALL"] } },
+            resources: { requests: { cpu: "25m", memory: "32Mi" }, limits: { cpu: "100m", memory: "64Mi" } },
+          },
+        ],
+      },
+    },
+  },
+});
+
+export const service = new Service({
+  metadata: { name: "app-b" },
+  spec: { selector: labels, ports: [{ port: 80, targetPort: 8080 }] },
+});

package/example-flux-estate/app-b/tsconfig.json

@@ -0,0 +1 @@
+{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "Bundler", "strict": true, "skipLibCheck": true, "noEmit": true }, "include": ["src/**/*", "ops/**/*", "chant.config.ts"] }

package/example-flux-estate/control-plane/chant.config.ts

@@ -0,0 +1,19 @@
+import type { ChantConfig } from "@intentius/chant";
+import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
+
+// The estate's control plane: it declares the Flux machinery (GitRepository +
+// one Kustomization per app), and the reconcilers deploy the app projects —
+// this project never applies a workload itself. Bound to the demo's own
+// cluster (scripts/estate-up.sh creates it) so a live read can never observe
+// whatever kubectl context happens to be ambient (chant#1100).
+export default {
+  lexicons: ["k8s"],
+  sourceDir: "src",
+  environments: ["local"],
+  ownership: { stack: "flux-control-plane", env: "local" },
+  k8s: {
+    profiles: {
+      local: { context: "k3d-behold-flux-demo" },
+    },
+  } satisfies K8sChantConfig,
+} satisfies ChantConfig;

package/example-flux-estate/control-plane/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "behold-example-flux-control-plane",
+  "private": true,
+  "type": "module",
+  "description": "The estate's control plane: the Flux CRs (GitRepository + Kustomizations) that deploy the app projects.",
+  "scripts": {
+    "build": "chant build src -o dist/control-plane.yaml --format yaml"
+  },
+  "dependencies": {
+    "@intentius/chant": "^0.44.2",
+    "@intentius/chant-lexicon-k8s": "^0.44.2"
+  }
+}

package/example-flux-estate/control-plane/src/flux.ts

@@ -0,0 +1,51 @@
+// The control plane, GitOps-style: Flux reconcilers deploy the app projects
+// FROM THIS REPO. The GitRepository points at behold's own public repo; each
+// Kustomization applies one app project's committed manifests into that app's
+// namespace via targetNamespace — which is why app-b's objects declare no
+// metadata.namespace (see ../../app-b/src/app.ts): Flux stamps it at apply
+// time. That is the normal Flux estate shape, and exactly the shape behold's
+// namespace-mismatch note (behold#192) exists to explain.
+//
+// scripts/estate-up.sh applies the BUILT form of this project (chant build →
+// dist/control-plane.yaml) once, after installing Flux; from then on the
+// reconcilers own the apps.
+import { Namespace, GitRepository, Kustomization } from "@intentius/chant-lexicon-k8s";
+
+// The app namespaces are control-plane concerns: a Kustomization's
+// targetNamespace must already exist — Flux does not create it.
+export const nsAppA = new Namespace({ metadata: { name: "app-a" } });
+export const nsAppB = new Namespace({ metadata: { name: "app-b" } });
+
+export const source = new GitRepository({
+  metadata: { name: "behold", namespace: "flux-system" },
+  spec: {
+    interval: "1m",
+    url: "https://github.com/INTENTIUS/behold",
+    // main is where the committed manifests live once merged. Verifying a
+    // not-yet-merged branch: estate-up.sh patches the LIVE object's ref when
+    // BEHOLD_FLUX_REF is set — the declared source stays main.
+    ref: { branch: "main" },
+  },
+});
+
+export const appA = new Kustomization({
+  metadata: { name: "app-a", namespace: "flux-system" },
+  spec: {
+    interval: "1m",
+    prune: true,
+    targetNamespace: "app-a",
+    sourceRef: { kind: "GitRepository", name: "behold" },
+    path: "./example-flux-estate/app-a/manifests",
+  },
+});
+
+export const appB = new Kustomization({
+  metadata: { name: "app-b", namespace: "flux-system" },
+  spec: {
+    interval: "1m",
+    prune: true,
+    targetNamespace: "app-b",
+    sourceRef: { kind: "GitRepository", name: "behold" },
+    path: "./example-flux-estate/app-b/manifests",
+  },
+});

package/example-flux-estate/control-plane/tsconfig.json

@@ -0,0 +1 @@
+{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "Bundler", "strict": true, "skipLibCheck": true, "noEmit": true }, "include": ["src/**/*", "ops/**/*", "chant.config.ts"] }