@intentius/behold 0.8.0 → 0.9.0

package/example-argo-estate/README.md

@@ -14,25 +14,31 @@ Three chant projects served as one composed estate, the Argo mirror of
 npx @intentius/behold demo argo-estate
 ```
 
-Unlike flux-estate this one is **declared only** — no cluster, no Argo install,
-no Docker. It copies out, `npm install`s, and serves. What to look at:
+The demo path is **declared only** — no cluster, no Argo install, no Docker. It
+copies out, `npm install`s, and serves. (There is a live lane, but it is an
+acceptance run rather than part of the demo: see "Live" below.) What to look
+at:
 
 - The **estate**: per-project boundary boxes, and the `project` edges joining
   both Applications to the AppProject they name (behold#222) — the join chant
   lints as ARGO002, so an estate whose lint passes cannot be drawn wrong.
   The entity graph carries them at the attributes tier (`?detail=3`).
-- The **logical lens** on the control plane alone
-  (`behold serve control-plane`, zoom: logical): `namespace app-a` and
-  `namespace app-b` drawn as boxes even though the control plane declares no
-  `Namespace` object anywhere. They come from each Application's
-  `spec.destination.namespace` — a namespace Argo will own objects in is a
-  namespace the estate is committed to. Serve all three members and the apps'
-  Deployments and Services sit inside those boxes.
-
-That last one is the Argo/Flux difference worth noticing: flux-estate's control
-plane must declare the app namespaces itself (a Kustomization's
-`targetNamespace` must already exist), while here `CreateNamespace=true` means
-Argo makes them — so the box exists on the strength of the destination alone.
+- The **logical lens** (zoom: logical): cluster ⊃ `namespace app-a` and
+  `namespace app-b`, each holding that app's Deployment + Service, plus
+  `namespace argocd` holding both Applications and the AppProject — drawn
+  even though the control plane declares no `Namespace` object anywhere. The
+  app namespaces come from each Application's `spec.destination.namespace`; a
+  namespace Argo will own objects in is a namespace the estate is committed
+  to, and behold#224 taught the composed estate to draw that projection.
+  Serve `control-plane` alone (`behold serve control-plane`, zoom: logical)
+  and the same boxes appear empty — the destination harvest still names them,
+  but there is nothing from app-a/app-b in the graph to fill them with.
+
+That alone-vs-composed split is the Argo/Flux difference worth noticing:
+flux-estate's control plane must declare the app namespaces itself (a
+Kustomization's `targetNamespace` must already exist), while here
+`CreateNamespace=true` means Argo makes them — so the box exists on the
+strength of the destination alone.
 
 Argo's ordering is the `argocd.argoproj.io/sync-wave` annotation, so unlike
 Flux's `dependsOn` (behold#223) there is no edge to draw for it: app-a is wave
@@ -40,7 +46,26 @@ Flux's `dependsOn` (behold#223) there is no edge to draw for it: app-a is wave
 
 The app `manifests/` are committed `chant build` output — the path each
 Application syncs. Changing an app's source means a rebuild (`npm run build` in
-the app). `chant build` in the control plane warns ARGO005 on both
-Applications: `source.path` is repo-relative (that's what Argo resolves it
-against), not relative to the build root, so it doesn't resolve locally. Fine
-here, and the check's own message says so.
+the app), and the rebuilt manifests have to be on `main` before Argo can sync
+them. `chant build` in the control plane warns ARGO005 on both Applications:
+`source.path` is repo-relative (that's what Argo resolves it against), not
+relative to the build root, so it doesn't resolve locally. Fine here, and the
+check's own message says so.
+
+## Live
+
+Nothing above needs a cluster, but the estate as committed does reconcile
+against a real one — the Applications point at this repo on `main` and the app
+`manifests/` are already there, so an Argo CD install has everything it needs.
+`just e2e-argo-estate` (behold#269) is that run: a scratch k3d cluster, Argo
+from the pinned `core-install` manifest, the control plane applied once, and
+then the composed estate served against the result — the destination-namespace
+boxes filled with live cards, #238's health verdicts read off each
+Application's health/sync pair, and the unhappy arm (an Application pointed at
+a path that does not exist, then restored). It creates and deletes its own
+cluster and touches no other context.
+
+Each member's `chant.config.ts` therefore binds a `local` profile to the
+context `k3d-behold-argo-demo`, which is what that run aliases its scratch
+cluster to. Serving without `--env` — what `behold demo argo-estate` does —
+reads none of it.

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

@@ -1,10 +1,18 @@
 import type { ChantConfig } from "@intentius/chant";
+import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
 
 // App project A. Argo syncs its committed manifests/ (chant build output) from
-// the repo; this project applies nothing itself. Declared-only demo, so no
-// kube context is bound — see ../control-plane/chant.config.ts.
+// the repo; this project applies nothing itself. behold serves it as part of
+// the estate, and the live overlay reads the cluster through the same binding
+// as every other member — see ../control-plane/chant.config.ts.
 export default {
   lexicons: ["k8s"],
   sourceDir: "src",
+  environments: ["local"],
   ownership: { stack: "argo-app-a" },
+  k8s: {
+    profiles: {
+      local: { context: "k3d-behold-argo-demo" },
+    },
+  } satisfies K8sChantConfig,
 } satisfies ChantConfig;

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

@@ -7,7 +7,7 @@
     "build": "chant build src -o manifests/app.yaml --format yaml"
   },
   "dependencies": {
-    "@intentius/chant": "^0.44.3",
-    "@intentius/chant-lexicon-k8s": "^0.44.3"
+    "@intentius/chant": "^0.44.6",
+    "@intentius/chant-lexicon-k8s": "^0.44.6"
   }
 }

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

@@ -1,9 +1,18 @@
 import type { ChantConfig } from "@intentius/chant";
+import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
 
-// App project B — same shape as app-a, second sync wave. Declared-only demo,
-// so no kube context is bound; see ../control-plane/chant.config.ts.
+// App project B — same shape as app-a, second sync wave. Unlike flux-estate's
+// app-b this one declares its own namespace on every object (Argo has no
+// targetNamespace to stamp one at apply time), so a live read resolves it
+// straight away. See ../control-plane/chant.config.ts for the binding.
 export default {
   lexicons: ["k8s"],
   sourceDir: "src",
+  environments: ["local"],
   ownership: { stack: "argo-app-b" },
+  k8s: {
+    profiles: {
+      local: { context: "k3d-behold-argo-demo" },
+    },
+  } satisfies K8sChantConfig,
 } satisfies ChantConfig;

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

@@ -7,7 +7,7 @@
     "build": "chant build src -o manifests/app.yaml --format yaml"
   },
   "dependencies": {
-    "@intentius/chant": "^0.44.3",
-    "@intentius/chant-lexicon-k8s": "^0.44.3"
+    "@intentius/chant": "^0.44.6",
+    "@intentius/chant-lexicon-k8s": "^0.44.6"
   }
 }

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

@@ -1,14 +1,29 @@
 import type { ChantConfig } from "@intentius/chant";
+import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
 
 // The estate's control plane: it declares the Argo machinery (an AppProject +
-// one Application per app), and Argo's controller deploys the app projects —
-// this project never applies a workload itself.
+// one Application per app), and Argo's application controller deploys the app
+// projects — this project never applies a workload itself.
 //
-// No k8s profile block, unlike the flux-estate demo's: argo-estate is the
-// DECLARED story only. Nothing here binds a kube context because nothing here
-// reads one — `behold demo argo-estate` needs no cluster and installs no Argo.
+// `npx @intentius/behold demo argo-estate` still needs no cluster: it serves
+// the source graph with no `--env`, and nothing below is read on that path.
+// The `local` profile exists for the live lane (behold#269,
+// `just e2e-argo-estate`), which stands up a scratch k3d cluster and aliases
+// its context to the name pinned here — so a live read resolves the DECLARED
+// binding and can never observe whatever kubectl context happens to be
+// ambient (chant#1100).
+//
+// Deliberately no `ownership.env`: the app members' committed manifests/ are
+// what Argo syncs from `main`, so a label that changes their build output
+// would have to be merged before any live run could agree with the cluster.
 export default {
   lexicons: ["k8s"],
   sourceDir: "src",
+  environments: ["local"],
   ownership: { stack: "argo-control-plane" },
+  k8s: {
+    profiles: {
+      local: { context: "k3d-behold-argo-demo" },
+    },
+  } satisfies K8sChantConfig,
 } satisfies ChantConfig;

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

@@ -7,7 +7,7 @@
     "build": "chant build src -o dist/control-plane.yaml --format yaml"
   },
   "dependencies": {
-    "@intentius/chant": "^0.44.3",
-    "@intentius/chant-lexicon-k8s": "^0.44.3"
+    "@intentius/chant": "^0.44.6",
+    "@intentius/chant-lexicon-k8s": "^0.44.6"
   }
 }

package/example-argo-estate/package-lock.json

@@ -14,22 +14,22 @@
     "app-a": {
       "name": "behold-example-argo-app-a",
       "dependencies": {
-        "@intentius/chant": "^0.44.3",
-        "@intentius/chant-lexicon-k8s": "^0.44.3"
+        "@intentius/chant": "^0.44.6",
+        "@intentius/chant-lexicon-k8s": "^0.44.6"
       }
     },
     "app-b": {
       "name": "behold-example-argo-app-b",
       "dependencies": {
-        "@intentius/chant": "^0.44.3",
-        "@intentius/chant-lexicon-k8s": "^0.44.3"
+        "@intentius/chant": "^0.44.6",
+        "@intentius/chant-lexicon-k8s": "^0.44.6"
       }
     },
     "control-plane": {
       "name": "behold-example-argo-control-plane",
       "dependencies": {
-        "@intentius/chant": "^0.44.3",
-        "@intentius/chant-lexicon-k8s": "^0.44.3"
+        "@intentius/chant": "^0.44.6",
+        "@intentius/chant-lexicon-k8s": "^0.44.6"
       }
     },
     "node_modules/@dagrejs/dagre": {
@@ -464,9 +464,9 @@
       }
     },
     "node_modules/@intentius/chant": {
-      "version": "0.44.3",
-      "resolved": "https://registry.npmjs.org/@intentius/chant/-/chant-0.44.3.tgz",
-      "integrity": "sha512-OVqkUberFaCGn0yrHQn5afzs9i6kRbArZU/AA68pfhh2O8gEfVkVqRO2z4pcF/1W+Lolp1o5aaxj51vqa6yrXA==",
+      "version": "0.44.6",
+      "resolved": "https://registry.npmjs.org/@intentius/chant/-/chant-0.44.6.tgz",
+      "integrity": "sha512-VFqPKe2WsSAJoUvfyghVTlIcj+QRNn//JgSHToq6PDDuKPU7F34V/4f+EZpX4MF3gvwVkZc9d6FUwKio6t0uqg==",
       "license": "Apache-2.0",
       "dependencies": {
         "@dagrejs/dagre": "^3.0.0",
@@ -482,9 +482,9 @@
       }
     },
     "node_modules/@intentius/chant-k8s-client": {
-      "version": "0.44.3",
-      "resolved": "https://registry.npmjs.org/@intentius/chant-k8s-client/-/chant-k8s-client-0.44.3.tgz",
-      "integrity": "sha512-BWNatONqGzPDnZIlBk/5Dze9ANk8NgynvLYcjPJMuBg5EfyUZETt17fq3PsKP2IiOR/fm+ZWHb2mZ3+qEEkfgA==",
+      "version": "0.44.6",
+      "resolved": "https://registry.npmjs.org/@intentius/chant-k8s-client/-/chant-k8s-client-0.44.6.tgz",
+      "integrity": "sha512-Do3zY0Bd2nIITDDrXYePwdOBdnNf59xn5J1aJA6gsg3dzXxR3dZ25YBAh+SQxKbRPuXIbu9rKd5lodaM8ZQDng==",
       "license": "Apache-2.0",
       "optional": true,
       "dependencies": {
@@ -492,19 +492,19 @@
       }
     },
     "node_modules/@intentius/chant-lexicon-k8s": {
-      "version": "0.44.3",
-      "resolved": "https://registry.npmjs.org/@intentius/chant-lexicon-k8s/-/chant-lexicon-k8s-0.44.3.tgz",
-      "integrity": "sha512-7JNg5Hlrqr3vl0iEhQcwUopandy1g4FCkGipFikbDp1KoXyp8QOJaovOOR0nUQ/wRhiRXYJX5Cg13cs0FsNbjQ==",
+      "version": "0.44.6",
+      "resolved": "https://registry.npmjs.org/@intentius/chant-lexicon-k8s/-/chant-lexicon-k8s-0.44.6.tgz",
+      "integrity": "sha512-JP2Lo4fFV7FPbSTHapKuDgpvrsm3dbNBT9pMW9NQB2MoE/ZkMGf3z3/wsPnygLdjbYq29abVYmw7DzPqBmA1tw==",
       "license": "Apache-2.0",
       "dependencies": {
         "@types/js-yaml": "^4.0.9",
         "js-yaml": "^4.1.1"
       },
       "optionalDependencies": {
-        "@intentius/chant-k8s-client": "^0.44.3"
+        "@intentius/chant-k8s-client": "^0.44.6"
       },
       "peerDependencies": {
-        "@intentius/chant": "^0.44.3",
+        "@intentius/chant": "^0.44.6",
         "typescript": "^5.9.3",
         "zod": "^4.3.6"
       }

package/example-carve/README.md

@@ -0,0 +1,194 @@
+# example-carve — the mixed estate the peeling demo runs on
+
+A migration caught half-done. `app/` is chant; `legacy-tf/` is Terraform; both
+describe one AWS account, and the walkthrough carves one more resource across
+the line while the camera is running.
+
+Run it:
+
+```sh
+behold demo carve          # copies this directory, installs, advises, serves
+```
+
+The boot does three things before a port opens: `npm install` in `app/` (whose
+chant every step of the walkthrough shells), `@cdktf/hcl2json` into the copy's
+root `node_modules` (chant lazy-loads the HCL parser from its own install
+upward, so `<copy>/node_modules` is where it resolves — not beside the `.tf`
+files), and `chant carve advise --report` over the copy's own Terraform. If any
+of that fails, the committed `carve-report.json` is served instead and the
+reason is on screen; a blank graph is the one outcome that's never allowed.
+
+```
+example-carve/
+  app/                     a small chant project — the pieces already carved
+    carveout/              where Emit and Bridge write, in a copy (gitignored)
+  legacy-tf/               the Terraform half, still Terraform-owned
+    terraform.tfstate      synthetic state (fake account, fake ARNs)
+    floci-override.tf.disabled   provider endpoints for the --live tier, inert
+    modules/cdn/           a local module, so module.cdn resolves offline
+  carve-report.json        the committed `carve advise` output
+```
+
+`carveout/` sits INSIDE `app/` rather than beside it, and that is load-bearing:
+the emitted source imports `@intentius/chant-lexicon-aws`, and Node resolves
+that from the file's own directory upward. From `app/carveout/src/assets.ts` it
+reaches `app/node_modules`; from a sibling `carveout/` it would reach nothing,
+and the Emit step's `chant lint` would fail on an install problem rather than
+on the source.
+
+## The estate is mixed from the first frame
+
+`app/src/carved.ts` holds a CloudWatch log group and an SSM parameter that came
+out of `legacy-tf/` last month. The source says so, and `legacy-tf/cdn.tf` still
+carries the other half of that carve: a `data "aws_ssm_parameter"` block reading
+back the value chant now owns. That is the data-source rewrite `carve bridge`
+generates, sitting in the estate a month later and working.
+
+So the estate view opens on a chant box beside a Terraform box. The morph at the
+end of the walkthrough has somewhere to land.
+
+## Bands
+
+Real output, from `chant carve advise` at chant 0.44.6. Reproduce it with:
+
+```sh
+npm install -D @cdktf/hcl2json          # once, anywhere on your PATH resolution
+chant carve advise --from example-carve/legacy-tf \
+                   --state example-carve/legacy-tf/terraform.tfstate
+```
+
+| score | address | band | why | role in the script |
+|---|---|---|---|---|
+| 100 | `aws_cloudwatch_log_group.worker` | clean leaf | clean 1:1 native map, no boundary edges | the free first move: named, not carved |
+| 88 | `aws_s3_bucket.assets` | clean leaf | 1 inbound | **the star** — the resource we carve on camera |
+| 71 | `module.cdn` | carvable w/ edits | 1 outbound, tier 2, data present | one module, so module scoring appears |
+| 69 | `aws_iam_role.api` | carvable w/ edits | 1 inbound, 1 outbound, tier 2 | what an inbound edge costs |
+| 69 | `aws_vpc_endpoint.ssm` | carvable w/ edits | 4 outbound, tier 2 | outbound edges are cheap, but they add up |
+| 65 | `aws_lambda_function.api` | carvable w/ edits | 5 outbound, tier 2 | the honest yellow: next month, not today |
+| 46 | `aws_subnet.private_a` | leave in Terraform | 3 inbound, 2 outbound, data present | |
+| 46 | `aws_subnet.private_b` | leave in Terraform | 3 inbound, 2 outbound, data present | |
+| 43 | `aws_security_group.lambda` | leave in Terraform | 2 inbound, 2 outbound, tier 2, data present | |
+| 36 | `aws_vpc.main` | leave in Terraform | 5 inbound, 1 outbound | the grey anchor: this stays, and that's fine |
+| 0 | `aws_network_acl.private` | leave in Terraform | no known native mapping | |
+| 0 | `random_pet.suffix` | leave in Terraform | no known native mapping | the long tail, stated plainly |
+
+Bands: 80-100 carve now, 50-79 carve with boundary edits, 0-49 leave in Terraform.
+
+The scoring model is `100 - 12*inbound - 4*outbound - 15*(tier-1) - 10*dynamic
+- 3*(instances-1)`, clamped, with unmapped types pinned at 0. Every number
+above is that arithmetic on the edges in `legacy-tf/`, which is why the estate
+is shaped the way it is:
+
+- The bucket has exactly one inbound edge, `aws_lambda_function.api`'s
+  `ASSETS_BUCKET` environment variable. One edge, one patch, 88.
+- `aws_s3_bucket_versioning.assets` and `aws_s3_bucket_public_access_block.assets`
+  share the bucket's name, so they fold into its carve set. They are not ranked
+  separately and their edges to the bucket are not counted against it.
+- Five resources point at the VPC. Carving it would mean patching all five at
+  once, and 36 says so.
+- The subnets and the security group each read a data source, which costs 10.
+  That is what pushes them under the line rather than sitting awkwardly in the
+  middle band next to the star.
+
+No resource uses `count` or `for_each`, so the instance-count penalty is zero
+and `--state` produces byte-identical scores to a `.tf`-only parse. The bands do
+not move depending on which way the walkthrough invokes the advisor.
+
+### carve-report.json
+
+`carve-report.json` is the `--report` output of exactly the command above,
+committed so the walkthrough and #252's carve lens have an artifact to read
+without shelling anything. JSON carries no comments, so this is its header:
+regenerate it, unchanged, with
+
+```sh
+chant carve advise --from example-carve/legacy-tf \
+                   --state example-carve/legacy-tf/terraform.tfstate \
+                   --report example-carve/carve-report.json
+```
+
+from the repository root, so the `from` field stays a relative path.
+
+`app/` pins chant ^0.44.6 and that floor is load-bearing, not housekeeping: the
+advisor only publishes a top-level `version: 1` and per-resource `boundary` edge
+lists from 0.44.6 (chant#1636). Run the same command on 0.44.4 and every score
+is identical but no resource carries a `boundary` field at all, so the Pick step
+falls back to naming inbound/outbound COUNTS instead of highlighting the one
+`aws_lambda_function.api` edge the carve severs. The committed report above is
+byte-identical to what 0.44.6 regenerates, which is why the demo's fallback path
+and its fresh-run path show the same picture.
+
+## The six beats
+
+These are the six steps on the panel's Carve tab. behold runs beats 4 and 5
+itself, into `app/carveout/` in the copy; beat 6 is copy buttons, on purpose.
+
+1. **The green star.** The estate view, banded. Two resources are green; the
+   100 is a log group nobody will miss, so the eye lands on the 88 next to it.
+2. **The arithmetic.** Open `aws_s3_bucket.assets`: 100 minus 12 for one
+   inbound edge. The score is not a vibe, it is a subtraction, and the inspect
+   pane shows the terms.
+3. **The cut edge.** Highlight the one dependency the carve severs:
+   `aws_lambda_function.api` reads the bucket name. One line of Terraform.
+4. **Emit.** `carve emit --from legacy-tf --state legacy-tf/terraform.tfstate
+   --select aws_s3_bucket.assets` adopts the bucket from state into typed chant
+   source, folds both sub-resources into the carve set, and writes a boundary
+   report. Nothing is applied, nothing is destroyed, and `chant lint` on the
+   result exits clean.
+5. **The bridge.** One `data "aws_s3_bucket" "assets"` block in the surviving
+   Terraform, and `aws_lambda_function.api` reads from that instead. The
+   surviving plan is whole again.
+6. **The handoff.** Two commands: `terraform state rm aws_s3_bucket.assets`,
+   then chant takes the observe position. `terraform plan` shows no destroy.
+
+Then the box slides out of the Terraform half and into `app/`, beside the log
+group and the SSM parameter that made the same trip last month. Around two
+minutes end to end.
+
+## Two tiers
+
+**Offline is the default.** The synthetic `terraform.tfstate` is committed, so
+`carve advise` and `carve emit --state` run with no Docker, no terraform binary,
+no AWS account and no network. The only dependency beyond this directory is
+`@cdktf/hcl2json`, which chant lazy-loads and names in its error if absent. This
+tier guarantees the first thirty seconds of the video.
+
+**`--live` is the full video.** Boot a scratch Floci, arm
+`legacy-tf/floci-override.tf.disabled` (see its header), and `terraform apply`
+the estate into it, so the state is one terraform really wrote. Then the observe
+beats become footage rather than caption: after Emit, `chant lifecycle diff
+--live` reads the bucket out of Floci, clean, while Terraform still owns it; the
+handoff runs a real `terraform plan` showing no destroy; and behold's overlay
+flips the bucket green afterwards. The line it exists for is "Terraform forgot
+it, chant adopted it, and it never blinked."
+
+The live tier needs `docker` and `terraform` on PATH, boots its own throwaway
+Floci and deletes it after, and never touches an existing `floci*` container.
+Floci's emulation bounds it: S3 and CloudWatch Logs, the two types the
+walkthrough actually carves, are covered (chant's `just carve-emit-e2e` is the
+prior art). The VPC, lambda and CloudFront blocks are scenery for the advisor's
+grey band, so expect `-target` rather than one apply of the whole estate.
+
+## Known rough edge in emit
+
+`carve emit --state --select aws_s3_bucket.assets` reports "Folded in:
+`aws_s3_bucket_public_access_block.assets`, `aws_s3_bucket_versioning.assets`"
+and then emits a `Bucket` carrying neither. Only `bucket` and `tags` are in the
+AWS carve-out table's field map for `aws_s3_bucket`; versioning, public-access
+block and the state's server-side encryption block come out in the "unmapped
+Terraform attributes" comment instead. `chant lint` on the emitted project
+passes with warnings, but `chant build` fails on two AWS policy rules
+(`PublicAccessBlockConfiguration` missing, no TLS-deny bucket policy) even
+though the Terraform declared the first of those.
+
+Verified against chant 0.44.6. The walkthrough's Emit beat shows `lint`, not
+`build`, until the fold is applied as well as reported — the step's "why lint
+and not build?" note says the same thing on screen, so nobody reads a lint pass
+as a build pass. That is chant#1637.
+
+## Values
+
+Every name here is a boring-realistic stand-in for a small production estate,
+because the video pauses on the inspect pane. There is no `foo` and no `bar`.
+The account id is `000000000000` and every ARN, id and hostname is fake; the
+state file says so in its `_fixture_note` output.

package/example-carve/app/chant.config.ts

@@ -0,0 +1,6 @@
+export default {
+  lexicons: ["aws"],
+  sourceDir: "src",
+  environments: ["prod"],
+  ownership: { stack: "acme-platform-carved", env: "prod" },
+};