@intentius/behold 0.18.0 → 0.20.0

package/example-terraform-estate/README.md

@@ -0,0 +1,109 @@
+# example-terraform-estate
+
+A multi-root Terraform estate, declared only. No cloud account, no Docker, no
+`terraform` binary — behold reads the HCL through chant's terraform lexicon and
+draws what it finds.
+
+```sh
+npx @intentius/behold demo terraform-estate
+```
+
+## What it declares
+
+Two roots that are applied separately, plus the shared module both are built
+on. 25 resources, drawing 37 cards and 31 edges at the `resources` zoom.
+
+| directory | what it is |
+|---|---|
+| `envs/prod` | The environment root: a VPC with three subnets, a route table and an edge security group, an artifacts bucket with its versioning/public-access/encryption siblings, and two calls to the shared service module. |
+| `platform` | The estate-wide root, applied separately: the permissions boundary every service role attaches, a deploy role, the KMS key and alias, an audit log group. It declares **no provider block** — it inherits one where it is used. |
+| `modules/service` | The shared module `envs/prod` calls twice. An IAM role and inline policy, a log group, a work queue with its dead-letter queue, a task security group. |
+| `backends` | A backend fragment, copied into a root when one is initialised. |
+| `envs/dev` | Not built yet. A README and no `.tf`. |
+
+## What each directory is there to show
+
+Discovery has to tell five things apart, and this estate is built to be each of
+them. A root is a directory with a `.tf` declaring a line-start `terraform {` or
+`provider "` block beside a `resource`, `data` or `module` block, a regex probe
+at depth, never an HCL parse.
+
+**`envs/prod` is the obvious root.** Provider block, resources, module calls.
+
+**`platform` is the root that has no provider block.** The naive reading of "a
+root configures a provider" would miss it. It is a root because it declares
+resources beside a `terraform` block, and it is applied on its own.
+
+**`modules/service` is the case that defeats the probe.** Its `versions.tf` is
+byte-for-byte `envs/prod/versions.tf`, the same `required_version`, the same
+`required_providers`. Nothing in the file's content says which of the two is a
+root. What separates them is that this one sits under a `modules/` segment,
+Terraform's own standard module structure, and the roots that call it draw its
+blocks already. Drawing it again would double every card in it.
+
+**`backends` has a `terraform` block and nothing to draw.** No resource, no
+data source, no module call. It is reported as skipped rather than drawn as an
+empty box, a box with nothing in it is a question, and the note answers it.
+
+**`envs/dev` is neither drawn nor reported.** It holds no `.tf` at all, so
+there is nothing here that looks like Terraform and nothing to say about it.
+Silence is the right answer; reporting it would be noise about every directory
+in every repository.
+
+The graph's status line says all of this:
+
+```
+2 roots — prod, platform; skipped backends (no resource, data or module block —
+nothing to draw), modules/service (called as a module, never applied on its own)
+```
+
+## The edge that is not drawn
+
+`platform` declares the KMS key and its alias. `envs/prod` reads it back:
+
+```hcl
+data "aws_kms_key" "estate" {
+  key_id = "alias/${var.name}-estate"
+}
+```
+
+That is a real cross-root reference, and it is how a multi-root estate is
+actually wired — two roots applied separately, neither a module of the other,
+joined by a name one publishes and the other looks up.
+
+**behold draws no edge for it**, and that is deliberate. Both ends carry the
+same unresolved `${var.name}` interpolation, so matching them would be a
+coincidence of variable naming rather than a relationship either root states.
+It was measured on a real estate and refused ([#381]). The data source card says
+what it reads instead, which is a claim the estate does make.
+
+Module calls *do* draw: each `module` block expands into its own contents under
+`module.checkout/…`, with the reference edges chant's lexicon resolves from the
+HCL.
+
+## It needs the lexicon
+
+behold parses no HCL and ships no HCL parser. The reading goes through
+`@intentius/chant-lexicon-terraform`, which loads `@cdktn/hcl2json` underneath —
+a ~1.8 MB wasm blob. Both are declared as optional peers and behold does not
+install them, so that every user who serves an ordinary chant project does not
+carry an HCL parser they will never run:
+
+```sh
+npm install --no-save @intentius/chant-lexicon-terraform @cdktn/hcl2json
+```
+
+Without them the demo refuses with that exact line and says where it looked.
+
+## Not the carve demo
+
+`behold demo carve` also involves Terraform and answers a different question.
+This estate asks **what is in my Terraform** — draw it, box it by root, tell the
+roots from the modules. The carve demo asks **what would it cost to leave**:
+`chant carve advise` ranks each resource by peelability and the walkthrough
+carves one across the line.
+
+Nothing here is being migrated. There is no chant project beside it, no
+peelability score on any card, and no stepper.
+
+[#381]: https://github.com/INTENTIUS/behold/issues/381

package/example-terraform-estate/backends/backend.s3.tf

@@ -0,0 +1,10 @@
+# A backend fragment, copied into a root when one is initialised. It declares
+# a `terraform` block and nothing to draw, which is why discovery reports it as
+# skipped rather than drawing an empty box for it.
+terraform {
+  backend "s3" {
+    bucket = "waterline-tfstate"
+    key    = "prod/terraform.tfstate"
+    region = "us-east-1"
+  }
+}

package/example-terraform-estate/chant.workspace.json

@@ -0,0 +1,22 @@
+{
+  "name": "example-terraform-estate",
+  "schema": 1,
+  "pins": [
+    {
+      "package": "@intentius/chant-lexicon-terraform",
+      "version": "0.95.0"
+    }
+  ],
+  "members": [
+    {
+      "name": "prod",
+      "dir": "envs/prod",
+      "kind": "terraform"
+    },
+    {
+      "name": "platform",
+      "dir": "platform",
+      "kind": "terraform"
+    }
+  ]
+}

package/example-terraform-estate/envs/dev/README.md

@@ -0,0 +1,5 @@
+# envs/dev
+
+Not built yet. This directory holds no `.tf` at all, which is why discovery
+neither draws it nor reports it as skipped: there is nothing here that looks
+like Terraform, so there is nothing to say about it.

package/example-terraform-estate/envs/prod/data.tf

@@ -0,0 +1,18 @@
+data "aws_caller_identity" "current" {}
+
+data "aws_region" "current" {}
+
+# The cross-root read, and what behold does with it.
+#
+# `platform` declares this key and its alias; this root reads it back by alias
+# rather than by a reference Terraform could resolve, because the two roots are
+# applied separately and neither is a module of the other. That is how a real
+# multi-root estate is wired, and it is also why NO EDGE is drawn between them:
+# both ends carry the same unresolved `${var.name}` interpolation, so a match
+# would be a coincidence of variable naming rather than a stated relationship.
+# behold measured that and refused it (INTENTIUS/behold#381). What you get
+# instead is this card, saying exactly what it reads — which is a claim the
+# estate actually makes.
+data "aws_kms_key" "estate" {
+  key_id = "alias/${var.name}-estate"
+}

package/example-terraform-estate/envs/prod/network.tf

@@ -0,0 +1,80 @@
+resource "aws_vpc" "main" {
+  cidr_block           = var.vpc_cidr
+  enable_dns_hostnames = true
+  enable_dns_support   = true
+
+  tags = { Name = "${var.name}-vpc" }
+}
+
+resource "aws_internet_gateway" "main" {
+  vpc_id = aws_vpc.main.id
+
+  tags = { Name = "${var.name}-igw" }
+}
+
+resource "aws_subnet" "public_a" {
+  vpc_id                  = aws_vpc.main.id
+  cidr_block              = cidrsubnet(var.vpc_cidr, 8, 0)
+  availability_zone       = "${var.region}a"
+  map_public_ip_on_launch = true
+
+  tags = { Name = "${var.name}-public-a" }
+}
+
+resource "aws_subnet" "public_b" {
+  vpc_id                  = aws_vpc.main.id
+  cidr_block              = cidrsubnet(var.vpc_cidr, 8, 1)
+  availability_zone       = "${var.region}b"
+  map_public_ip_on_launch = true
+
+  tags = { Name = "${var.name}-public-b" }
+}
+
+resource "aws_subnet" "private_a" {
+  vpc_id            = aws_vpc.main.id
+  cidr_block        = cidrsubnet(var.vpc_cidr, 8, 10)
+  availability_zone = "${var.region}a"
+
+  tags = { Name = "${var.name}-private-a" }
+}
+
+resource "aws_route_table" "public" {
+  vpc_id = aws_vpc.main.id
+
+  route {
+    cidr_block = "0.0.0.0/0"
+    gateway_id = aws_internet_gateway.main.id
+  }
+
+  tags = { Name = "${var.name}-public" }
+}
+
+resource "aws_route_table_association" "public_a" {
+  subnet_id      = aws_subnet.public_a.id
+  route_table_id = aws_route_table.public.id
+}
+
+resource "aws_route_table_association" "public_b" {
+  subnet_id      = aws_subnet.public_b.id
+  route_table_id = aws_route_table.public.id
+}
+
+resource "aws_security_group" "edge" {
+  name        = "${var.name}-edge"
+  description = "Ingress for the public tier."
+  vpc_id      = aws_vpc.main.id
+
+  ingress {
+    from_port   = 443
+    to_port     = 443
+    protocol    = "tcp"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+
+  egress {
+    from_port   = 0
+    to_port     = 0
+    protocol    = "-1"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+}

package/example-terraform-estate/envs/prod/outputs.tf

@@ -0,0 +1,13 @@
+output "vpc_id" {
+  description = "The network everything in this environment sits in."
+  value       = aws_vpc.main.id
+}
+
+output "artifacts_bucket" {
+  value = aws_s3_bucket.artifacts.bucket
+}
+
+output "service_role_arns" {
+  description = "One per service module, for the platform root to reference back."
+  value       = [module.checkout.role_arn, module.ledger.role_arn]
+}

package/example-terraform-estate/envs/prod/provider.tf

@@ -0,0 +1,10 @@
+provider "aws" {
+  region = var.region
+
+  default_tags {
+    tags = {
+      Estate      = "waterline"
+      Environment = "prod"
+    }
+  }
+}

package/example-terraform-estate/envs/prod/services.tf

@@ -0,0 +1,21 @@
+module "checkout" {
+  source = "../../modules/service"
+
+  name            = "${var.name}-checkout"
+  subnet_ids      = [aws_subnet.private_a.id]
+  boundary_arn    = data.aws_iam_policy.boundary.arn
+  log_kms_key_arn = data.aws_kms_key.estate.arn
+}
+
+module "ledger" {
+  source = "../../modules/service"
+
+  name            = "${var.name}-ledger"
+  subnet_ids      = [aws_subnet.private_a.id]
+  boundary_arn    = data.aws_iam_policy.boundary.arn
+  log_kms_key_arn = data.aws_kms_key.estate.arn
+}
+
+data "aws_iam_policy" "boundary" {
+  name = "${var.name}-boundary"
+}

package/example-terraform-estate/envs/prod/storage.tf

@@ -0,0 +1,31 @@
+resource "aws_s3_bucket" "artifacts" {
+  bucket = "${var.name}-artifacts"
+}
+
+resource "aws_s3_bucket_versioning" "artifacts" {
+  bucket = aws_s3_bucket.artifacts.id
+
+  versioning_configuration {
+    status = "Enabled"
+  }
+}
+
+resource "aws_s3_bucket_public_access_block" "artifacts" {
+  bucket = aws_s3_bucket.artifacts.id
+
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+}
+
+resource "aws_s3_bucket_server_side_encryption_configuration" "artifacts" {
+  bucket = aws_s3_bucket.artifacts.id
+
+  rule {
+    apply_server_side_encryption_by_default {
+      sse_algorithm     = "aws:kms"
+      kms_master_key_id = data.aws_kms_key.estate.arn
+    }
+  }
+}

package/example-terraform-estate/envs/prod/variables.tf

@@ -0,0 +1,17 @@
+variable "region" {
+  description = "The region every resource in this root is created in."
+  type        = string
+  default     = "us-east-1"
+}
+
+variable "name" {
+  description = "Prefix for every resource this root names."
+  type        = string
+  default     = "waterline-prod"
+}
+
+variable "vpc_cidr" {
+  description = "The network this environment sits in."
+  type        = string
+  default     = "10.40.0.0/16"
+}

package/example-terraform-estate/envs/prod/versions.tf

@@ -0,0 +1,10 @@
+terraform {
+  required_version = ">= 1.9.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 6.0"
+    }
+  }
+}

package/example-terraform-estate/modules/service/main.tf

@@ -0,0 +1,58 @@
+resource "aws_iam_role" "this" {
+  name                 = "${var.name}-role"
+  permissions_boundary = var.boundary_arn
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect    = "Allow"
+      Principal = { Service = "ecs-tasks.amazonaws.com" }
+      Action    = "sts:AssumeRole"
+    }]
+  })
+}
+
+resource "aws_iam_role_policy" "this" {
+  name = "${var.name}-inline"
+  role = aws_iam_role.this.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect   = "Allow"
+      Action   = ["sqs:ReceiveMessage", "sqs:DeleteMessage", "sqs:GetQueueAttributes"]
+      Resource = aws_sqs_queue.work.arn
+    }]
+  })
+}
+
+resource "aws_cloudwatch_log_group" "this" {
+  name              = "/service/${var.name}"
+  retention_in_days = 14
+  kms_key_id        = var.log_kms_key_arn
+}
+
+resource "aws_sqs_queue" "work" {
+  name                       = "${var.name}-work"
+  visibility_timeout_seconds = 60
+  redrive_policy = jsonencode({
+    deadLetterTargetArn = aws_sqs_queue.dead.arn
+    maxReceiveCount     = 5
+  })
+}
+
+resource "aws_sqs_queue" "dead" {
+  name = "${var.name}-dead"
+}
+
+resource "aws_security_group" "task" {
+  name        = "${var.name}-task"
+  description = "Egress only; the task reaches the queue and the log group."
+
+  egress {
+    from_port   = 0
+    to_port     = 0
+    protocol    = "-1"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+}

package/example-terraform-estate/modules/service/outputs.tf

@@ -0,0 +1,7 @@
+output "role_arn" {
+  value = aws_iam_role.this.arn
+}
+
+output "queue_url" {
+  value = aws_sqs_queue.work.url
+}

package/example-terraform-estate/modules/service/variables.tf

@@ -0,0 +1,16 @@
+variable "name" {
+  type = string
+}
+
+variable "subnet_ids" {
+  type = list(string)
+}
+
+variable "boundary_arn" {
+  description = "The platform root's permissions boundary."
+  type        = string
+}
+
+variable "log_kms_key_arn" {
+  type = string
+}

package/example-terraform-estate/modules/service/versions.tf

@@ -0,0 +1,10 @@
+terraform {
+  required_version = ">= 1.9.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 6.0"
+    }
+  }
+}

package/example-terraform-estate/platform/iam.tf

@@ -0,0 +1,40 @@
+# The permissions boundary every service role in the estate attaches. Declared
+# once here; each environment root reads it back by name as a data source.
+resource "aws_iam_policy" "boundary" {
+  name        = "${var.name}-boundary"
+  description = "Ceiling for every role the service module creates."
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect   = "Allow"
+        Action   = ["s3:GetObject", "s3:PutObject", "logs:PutLogEvents", "sqs:*"]
+        Resource = "*"
+      },
+      {
+        Effect   = "Deny"
+        Action   = ["iam:*", "organizations:*"]
+        Resource = "*"
+      },
+    ]
+  })
+}
+
+resource "aws_iam_role" "deploy" {
+  name = "${var.name}-deploy"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect    = "Allow"
+      Principal = { Service = "codebuild.amazonaws.com" }
+      Action    = "sts:AssumeRole"
+    }]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "deploy_boundary" {
+  role       = aws_iam_role.deploy.name
+  policy_arn = aws_iam_policy.boundary.arn
+}

package/example-terraform-estate/platform/kms.tf

@@ -0,0 +1,16 @@
+resource "aws_kms_key" "estate" {
+  description             = "Estate-wide key: artifact encryption and log group encryption."
+  deletion_window_in_days = 14
+  enable_key_rotation     = true
+}
+
+resource "aws_kms_alias" "estate" {
+  name          = "alias/${var.name}-estate"
+  target_key_id = aws_kms_key.estate.key_id
+}
+
+resource "aws_cloudwatch_log_group" "audit" {
+  name              = "/${var.name}/audit"
+  retention_in_days = var.log_retention_days
+  kms_key_id        = aws_kms_key.estate.arn
+}

package/example-terraform-estate/platform/outputs.tf

@@ -0,0 +1,7 @@
+output "boundary_arn" {
+  value = aws_iam_policy.boundary.arn
+}
+
+output "kms_key_arn" {
+  value = aws_kms_key.estate.arn
+}

package/example-terraform-estate/platform/variables.tf

@@ -0,0 +1,10 @@
+variable "name" {
+  description = "Prefix for every resource this root names."
+  type        = string
+  default     = "waterline-prod"
+}
+
+variable "log_retention_days" {
+  type    = number
+  default = 30
+}

package/example-terraform-estate/platform/versions.tf

@@ -0,0 +1,10 @@
+terraform {
+  required_version = ">= 1.9.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 6.0"
+    }
+  }
+}

package/example-writes/README.md

@@ -10,7 +10,7 @@ src/bucket.ts        one S3 Bucket + a TLS-only policy (the whole "infra")
 ops/apply.op.ts      ApplyOp "prod-apply" — code → real AWS (aws cloudformation deploy)
 ops/floci.op.ts      Op "floci-apply" — code → local Floci (CloudFormation API), no account
 ops/reconcile.op.ts  ReconcileOp "prod-reconcile" — cloud → code PR (the Adopt button)
-chant.config.ts      lexicons [aws, temporal], environments [prod]
+chant.config.ts      lexicons [aws], environments [prod]
 ```
 
 The **Sync** button appears because a project declares an `ApplyOp`. A project with
@@ -19,7 +19,7 @@ no `*.op.ts` (like `../example`) shows no Sync — that's expected, not a bug.
 ## Creds-free: deploy to a local emulator (`--local`)
 
 No AWS account? Serve with `--local` and behold boots a local Floci emulator
-(needs Docker), then the **floci-apply** Op deploys the bucket to it — the same
+(needs Docker), then the **floci-apply** Op deploys the bucket to it, the same
 delegated-write path, zero cloud creds:
 
 ```sh
@@ -36,7 +36,7 @@ you Ctrl-C. Everything below uses real AWS instead.
 ## Prerequisites
 
 - Node 20+, and **AWS credentials** in your environment (`aws sts get-caller-identity`
-  should work). The apply creates a real S3 bucket via CloudFormation — a few cents,
+  should work). The apply creates a real S3 bucket via CloudFormation, a few cents,
   torn down at the end. behold holds no creds; `chant` uses yours on this machine.
 - One edit: S3 bucket names are **globally unique**, so change `BucketName` in
   [`src/bucket.ts`](src/bucket.ts) to something of your own (e.g. include your AWS
@@ -59,10 +59,10 @@ npm run dev -- serve example-writes --env prod
    colour flip.)
 2. In the header, click **Sync**. The now-line streams the Op's phases:
    `▶ chant run prod-apply` → Build → Plan → **Apply** (`aws cloudformation deploy`).
-   `prod-apply` is **ungated**, so it applies straight away — no approval step.
+   `prod-apply` is **ungated**, so it applies straight away, no approval step.
 3. When it finishes, the `store` node flips **blue → green (managed)**. Click it: the
    inspect panel's **live** section shows the bucket's observed **physical id** and
-   status. That's the hydration — the cloud's view of your declared resource.
+   status. That's the hydration, the cloud's view of your declared resource.
 4. Click **Refresh** any time to re-check drift and drop a lanes frame.
 
 ## What "gated" looks like

package/example-writes/chant.config.ts

@@ -1,7 +1,7 @@
 import type { TemporalChantConfig } from "@intentius/chant-lexicon-temporal";
 
 export default {
-  lexicons: ["aws", "temporal"],
+  lexicons: ["aws"],
   sourceDir: "src",
   environments: ["prod"],
   ownership: { stack: "behold-writes", env: "prod" },

package/example-writes/ops/apply.op.ts

@@ -1,4 +1,4 @@
-import { ApplyOp } from "@intentius/chant-lexicon-temporal";
+import { ApplyOp } from "@intentius/chant/op";
 
 // code → cloud. Additive apply (no gate) runs one-shot on the local executor —
 // behold's Sync button shells `chant run prod-apply`. Target cloudformation;

package/example-writes/ops/floci.op.ts

@@ -1,4 +1,5 @@
-import { Op, phase, build, awsApply, httpCheck } from "@intentius/chant-lexicon-temporal";
+import { Op, phase, build, httpCheck } from "@intentius/chant/op";
+import { awsApply } from "@intentius/chant-lexicon-aws";
 
 // Deploy the S3 bucket to the local Floci emulator via the CloudFormation API
 // (awsApply — direct create-or-update + poll, no aws CLI, honours the endpoint).
@@ -8,7 +9,6 @@ import { Op, phase, build, awsApply, httpCheck } from "@intentius/chant-lexicon-
 export default Op({
   name: "floci-apply",
   overview: "S3 bucket → local Floci (CloudFormation API), no cloud account",
-  taskQueue: "behold-local",
   phases: [
     phase("Build", [build(".", { script: "build" })]),
     // Stack name = the env ("prod"), so `serve --local --env prod`'s overlay —

package/example-writes/ops/reconcile.op.ts

@@ -1,4 +1,4 @@
-import { ReconcileOp } from "@intentius/chant-lexicon-temporal";
+import { ReconcileOp } from "@intentius/chant/op";
 
 // cloud → code. Snapshot live prod, diff vs source, open a PR for drift/orphans.
 // Scoped to chant-owned resources. behold's Adopt button triggers this.