@intentius/chant-lexicon-aws 0.124.52 → 0.124.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/dist/api/credential-chain.d.ts +3 -3
  2. package/dist/api/credential-chain.d.ts.map +1 -1
  3. package/dist/api/credential-chain.js +2 -2
  4. package/dist/api/read-client.d.ts +2 -2
  5. package/dist/api/read-client.d.ts.map +1 -1
  6. package/dist/api/read-client.js +2 -2
  7. package/dist/api/{sigv4.d.ts → signing.d.ts} +14 -34
  8. package/dist/api/signing.d.ts.map +1 -0
  9. package/dist/api/signing.js +95 -0
  10. package/dist/codegen/generate-lexicon.d.ts +2 -0
  11. package/dist/codegen/generate-lexicon.d.ts.map +1 -1
  12. package/dist/codegen/generate-lexicon.js +1 -0
  13. package/dist/components/__tests__/mock-cloud-executor.d.ts +4 -0
  14. package/dist/components/__tests__/mock-cloud-executor.d.ts.map +1 -1
  15. package/dist/components/__tests__/mock-cloud-executor.js +18 -1
  16. package/dist/components/apply.d.ts +46 -2
  17. package/dist/components/apply.d.ts.map +1 -1
  18. package/dist/components/apply.js +266 -30
  19. package/dist/components/cfn-adopt-run.d.ts +37 -0
  20. package/dist/components/cfn-adopt-run.d.ts.map +1 -0
  21. package/dist/components/cfn-adopt-run.js +104 -0
  22. package/dist/components/cfn-adopt.d.ts +99 -0
  23. package/dist/components/cfn-adopt.d.ts.map +1 -0
  24. package/dist/components/cfn-adopt.js +278 -0
  25. package/dist/components/cfn-imports.d.ts +84 -0
  26. package/dist/components/cfn-imports.d.ts.map +1 -0
  27. package/dist/components/cfn-imports.js +239 -0
  28. package/dist/components/cloud-executor.d.ts +38 -2
  29. package/dist/components/cloud-executor.d.ts.map +1 -1
  30. package/dist/components/cloud-executor.js +84 -2
  31. package/dist/health.js +1 -1
  32. package/dist/importable.d.ts +30 -0
  33. package/dist/importable.d.ts.map +1 -0
  34. package/dist/importable.js +72 -0
  35. package/dist/index-identity.d.ts +19 -0
  36. package/dist/index-identity.d.ts.map +1 -0
  37. package/dist/index-identity.js +79 -0
  38. package/dist/index-import.d.ts +25 -0
  39. package/dist/index-import.d.ts.map +1 -0
  40. package/dist/index-import.js +132 -0
  41. package/dist/index.d.ts +1 -1
  42. package/dist/index.d.ts.map +1 -1
  43. package/dist/index.js +1 -1
  44. package/dist/integrity.json +4 -4
  45. package/dist/listed-types.d.ts +11 -0
  46. package/dist/listed-types.d.ts.map +1 -0
  47. package/dist/listed-types.js +52 -0
  48. package/dist/manifest.json +1 -1
  49. package/dist/meta.json +13206 -1237
  50. package/dist/plugin.d.ts.map +1 -1
  51. package/dist/plugin.js +12 -3
  52. package/dist/reference-catalog.d.ts.map +1 -1
  53. package/dist/reference-catalog.js +62 -20
  54. package/dist/skills/chant-aws-carve-terraform.md +21 -14
  55. package/dist/spec/fetch.d.ts +5 -0
  56. package/dist/spec/fetch.d.ts.map +1 -1
  57. package/dist/spec/parse.d.ts +8 -0
  58. package/dist/spec/parse.d.ts.map +1 -1
  59. package/dist/spec/parse.js +3 -0
  60. package/package.json +2 -2
  61. package/src/api/credential-chain.ts +3 -3
  62. package/src/api/read-client.test.ts +2 -2
  63. package/src/api/read-client.ts +3 -3
  64. package/src/api/{sigv4.test.ts → signing.test.ts} +84 -96
  65. package/src/api/signing.ts +130 -0
  66. package/src/codegen/generate-lexicon.ts +3 -0
  67. package/src/components/__tests__/mock-cloud-executor.ts +20 -1
  68. package/src/components/apply.ts +288 -30
  69. package/src/components/cfn-adopt-run.test.ts +227 -0
  70. package/src/components/cfn-adopt-run.ts +141 -0
  71. package/src/components/cfn-adopt.test.ts +284 -0
  72. package/src/components/cfn-adopt.ts +340 -0
  73. package/src/components/cfn-exports-in-use.test.ts +146 -0
  74. package/src/components/cfn-imports-preview.test.ts +178 -0
  75. package/src/components/cfn-imports-three-stacks.test.ts +107 -0
  76. package/src/components/cfn-imports.test.ts +213 -0
  77. package/src/components/cfn-imports.ts +246 -0
  78. package/src/components/cfn-plan-shape-conformance.test.ts +83 -0
  79. package/src/components/cloud-executor.ts +127 -5
  80. package/src/components/demo-composed-stacks-floci.e2e.test.ts +235 -0
  81. package/src/derived-edges.test.ts +142 -0
  82. package/src/generated/lexicon-aws.json +13206 -1237
  83. package/src/health.ts +1 -1
  84. package/src/importable.test.ts +86 -0
  85. package/src/importable.ts +83 -0
  86. package/src/index-identity.test.ts +134 -0
  87. package/src/index-identity.ts +98 -0
  88. package/src/index-import.test.ts +257 -0
  89. package/src/index-import.ts +158 -0
  90. package/src/index-search.test.ts +87 -0
  91. package/src/index.ts +1 -1
  92. package/src/listed-types.test.ts +97 -0
  93. package/src/listed-types.ts +56 -0
  94. package/src/plugin.ts +13 -3
  95. package/src/reference-catalog.ts +63 -20
  96. package/src/skills/chant-aws-carve-terraform.md +21 -14
  97. package/src/spec/fetch.ts +5 -0
  98. package/src/spec/parse.test.ts +15 -0
  99. package/src/spec/parse.ts +12 -0
  100. package/src/testdata/indexed/identity.listing.json +65 -0
  101. package/src/testdata/indexed/import.listing.json +126 -0
  102. package/src/testdata/indexed/listing.json +69 -0
  103. package/src/testdata/indexed/topology.listing.json +350 -0
  104. package/src/testdata/three-cloud/dns.graph.json +336 -0
  105. package/src/three-cloud-parity.test.ts +49 -0
  106. package/dist/api/sigv4.d.ts.map +0 -1
  107. package/dist/api/sigv4.js +0 -185
  108. package/src/api/sigv4.ts +0 -243
@@ -0,0 +1,56 @@
1
+ /**
2
+ * Cloud Control's type names as aws lexicon kinds (#4521).
3
+ *
4
+ * behold#1029 lists AWS through Cloud Control `ListResources`, which names
5
+ * each object by its CloudFormation type (`AWS::S3::Bucket`), and the aws
6
+ * lexicon's kinds are those same names. So the mapping is the identity, kept
7
+ * to the types the lexicon generated: a type outside `lexicon-aws.json` (one
8
+ * newer than the pinned registry, or a third-party type) has no kind here and
9
+ * stays an unknown-kind node. Cloud Control returns the CloudFormation
10
+ * resource model, which is the tree the deep reader returns too
11
+ * (./deep-observe.ts), so no reshaping.
12
+ */
13
+ import { createRequire } from "module";
14
+ import { moduleSourceUrl } from "@intentius/chant/module-source";
15
+ import type { ListedTypeMapping } from "@intentius/chant/lifecycle/type-listing";
16
+
17
+ const require = createRequire(moduleSourceUrl(import.meta.url));
18
+
19
+ // A CloudFormation type name: `<Organization>::<Service>::<Resource>`. The
20
+ // organization is not always AWS (`Alexa::ASK::Skill`), so it is not pinned.
21
+ const CFN_TYPE = /^[A-Za-z0-9]+::[A-Za-z0-9]+::[A-Za-z0-9]+$/;
22
+
23
+ let cachedKinds: ReadonlySet<string> | null | undefined;
24
+
25
+ /** The resource kinds `chant generate` wrote, or null in a checkout that has not generated. */
26
+ function generatedKinds(): ReadonlySet<string> | null {
27
+ if (cachedKinds !== undefined) return cachedKinds;
28
+ try {
29
+ const manifest = require("./generated/lexicon-aws.json") as Record<string, { resourceType: string; kind: string }>;
30
+ cachedKinds = new Set(Object.values(manifest).filter((e) => e.kind === "resource").map((e) => e.resourceType));
31
+ } catch {
32
+ cachedKinds = null;
33
+ }
34
+ return cachedKinds;
35
+ }
36
+
37
+ /**
38
+ * The aws kind for a Cloud Control type, or undefined. With no kind set (no
39
+ * generated registry) every well-formed CloudFormation type maps, which is
40
+ * what the rest of the lexicon assumes before `chant generate` has run.
41
+ */
42
+ export function awsKindForListedType(listedType: string, kinds: ReadonlySet<string> | null = generatedKinds()): string | undefined {
43
+ if (!CFN_TYPE.test(listedType)) return undefined;
44
+ if (kinds && !kinds.has(listedType)) return undefined;
45
+ return listedType;
46
+ }
47
+
48
+ /** The inverse, for tests and for a reader naming what to list: the same name. */
49
+ export function awsListedTypeForKind(kind: string): string {
50
+ return kind;
51
+ }
52
+
53
+ export const awsListedTypes: ListedTypeMapping = {
54
+ substrate: "aws",
55
+ kindFor: (listedType) => awsKindForListedType(listedType),
56
+ };
package/src/plugin.ts CHANGED
@@ -3,6 +3,9 @@ import { createRequire } from "module";
3
3
  import { awsBehaviourKinds } from "./behaviour-kinds";
4
4
  import { detectTemplate } from "./detect";
5
5
  import { awsCapabilityPack } from "./capabilities/pack";
6
+ import { awsListedTypes } from "./listed-types";
7
+ import { awsIndexIdentity } from "./index-identity";
8
+ import { awsIndexImport } from "./index-import";
6
9
  import type { LexiconPlugin, IntrinsicDef, ObservationResult, DeepObservationResult, DependencyObservation, DescribeIdentityOptions, DescribeIdentityResult, DisruptionQuery, DisruptionVerdict, ResourceMetadata, ExportedTemplate, ResourceSelector, InitTemplateSet, StackStatusObservation } from "@intentius/chant/lexicon";
7
10
  const require = createRequire(moduleSourceUrl(import.meta.url));
8
11
  import type { LintRule } from "@intentius/chant/lint/rule";
@@ -98,6 +101,13 @@ export const awsPlugin: LexiconPlugin = {
98
101
  referenceCatalog: awsReferenceCatalog,
99
102
  capabilityPack: awsCapabilityPack,
100
103
 
104
+ // Cloud inventory type names to kinds, for an indexed resource (#4521).
105
+ listedTypes: awsListedTypes,
106
+ // Declared entities to indexed resources by primaryIdentifier (#4523).
107
+ indexIdentity: awsIndexIdentity,
108
+ // Indexed resources as CloudFormation import IR, for `chant import --index` (#4524).
109
+ indexImport: awsIndexImport,
110
+
101
111
  lintRules(): LintRule[] {
102
112
  const rulesDir = join(dirname(fileURLToPath(import.meta.url)), "lint", "rules");
103
113
  return discoverLintRules(rulesDir, import.meta.url);
@@ -586,7 +596,7 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
586
596
  {
587
597
  file: "chant-aws-carve-terraform.md",
588
598
  name: "chant-aws-carve-terraform",
589
- description: "Demo carving a resource out of Terraform into native chant — advise, emit, audit, bridge, apply — fully offline",
599
+ description: "Demo moving one Terraform resource to native CloudFormation, fully offline (advise, emit, audit, bridge, apply); Terraform keeps the rest",
590
600
  triggers: [
591
601
  { type: "context", value: "terraform" },
592
602
  { type: "context", value: "carve" },
@@ -610,12 +620,12 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
610
620
  {
611
621
  title: "Run the offline demo",
612
622
  description: "Demo the full advise → emit → bridge → apply loop with no cloud",
613
- input: "Show me how chant carves a resource out of Terraform",
623
+ input: "Show me how chant moves one resource from Terraform to CloudFormation",
614
624
  output: "cd examples/terraform-carve-out && ./demo.sh",
615
625
  },
616
626
  {
617
627
  title: "Adopt a resource from state",
618
- description: "Emit native chant source for a Terraform-managed resource, offline",
628
+ description: "Emit chant source for the AWS lexicon from a Terraform-managed resource, offline",
619
629
  input: "Adopt aws_s3_bucket.assets into chant",
620
630
  output: "chant carve emit --from ./terraform --select aws_s3_bucket.assets --state ./terraform/terraform.tfstate",
621
631
  },
@@ -28,6 +28,22 @@ export const awsReferenceCatalog: ReferenceCatalog = {
28
28
  { kind: "AWS::ECS::Service", ids: ["ServiceArn"] },
29
29
  { kind: "AWS::ECS::TaskDefinition", ids: ["TaskDefinitionArn"] },
30
30
  { kind: "AWS::RDS::DBInstance", ids: ["DBInstanceArn", "Endpoint.Address"] },
31
+ // Targets of the CloudFormation-shape rules an index needs (#4522, the
32
+ // missing rules counted on INTENTIUS/behold#1023). Over an index each
33
+ // node is also matched by its Cloud Control identifier and its cloud ids,
34
+ // so a role's ARN joins even though the deep hooks prune `Arn`.
35
+ { kind: "AWS::RDS::DBSubnetGroup", ids: ["DBSubnetGroupName"] },
36
+ { kind: "AWS::IAM::Role", ids: ["Arn", "RoleName"] },
37
+ { kind: "AWS::EC2::EIP", ids: ["AllocationId", "PublicIp"] },
38
+ { kind: "AWS::Logs::LogGroup", ids: ["LogGroupName", "Arn"] },
39
+ { kind: "AWS::Route53::HostedZone", ids: ["Id"] },
40
+ { kind: "AWS::EKS::Cluster", ids: ["Name", "Arn"] },
41
+ { kind: "AWS::CloudFormation::Stack", ids: ["StackId"] },
42
+ // #4535: a record set is named by its record name, which is what a CNAME
43
+ // in the same zone points at; a bucket by its name, which is what a
44
+ // workload's env var carries (behold#166, ../../k8s/src/reference-catalog.ts).
45
+ { kind: "AWS::Route53::RecordSet", ids: ["Name"] },
46
+ { kind: "AWS::S3::Bucket", ids: ["BucketName"] },
31
47
  ],
32
48
  refs: [
33
49
  // ── containment (→ boundary boxes, #779) ──
@@ -86,25 +102,52 @@ export const awsReferenceCatalog: ReferenceCatalog = {
86
102
  // intrinsics to bare logical ids (= node ids), so these match by node id; the
87
103
  // property names are the CFN template shape (SecurityGroupIds, Cluster, …),
88
104
  // which differs from the describe/SDK shape above. No targetKind needed —
89
- // logical ids are unique.
90
- { from: "AWS::EC2::Subnet", path: "VpcId", relation: "containment", label: "in VPC" },
91
- { from: "AWS::EC2::SecurityGroup", path: "VpcId", relation: "containment", label: "in VPC" },
92
- { from: "AWS::EC2::RouteTable", path: "VpcId", relation: "containment", label: "in VPC" },
93
- { from: "AWS::EC2::Instance", path: "SubnetId", relation: "containment", label: "in subnet" },
94
- { from: "AWS::EC2::Instance", path: "SecurityGroupIds[]", relation: "reference", label: "sg" },
95
- { from: "AWS::EC2::NatGateway", path: "SubnetId", relation: "containment", label: "in subnet" },
96
- { from: "AWS::EC2::Route", path: "RouteTableId", relation: "reference", label: "in" },
97
- { from: "AWS::EC2::Route", path: "GatewayId", relation: "reference", label: "via" },
98
- { from: "AWS::EC2::Route", path: "NatGatewayId", relation: "reference", label: "via" },
99
- { from: "AWS::ElasticLoadBalancingV2::LoadBalancer", path: "Subnets[]", relation: "containment", label: "in subnet" },
100
- { from: "AWS::ElasticLoadBalancingV2::LoadBalancer", path: "SecurityGroups[]", relation: "reference", label: "sg" },
101
- { from: "AWS::ElasticLoadBalancingV2::TargetGroup", path: "VpcId", relation: "containment", label: "in VPC" },
102
- { from: "AWS::ElasticLoadBalancingV2::Listener", path: "LoadBalancerArn", relation: "reference", label: "on" },
103
- { from: "AWS::ElasticLoadBalancingV2::Listener", path: "DefaultActions[].TargetGroupArn", relation: "reference", label: "forwards to" },
104
- { from: "AWS::ECS::Service", path: "Cluster", relation: "reference", label: "in cluster" },
105
- { from: "AWS::ECS::Service", path: "TaskDefinition", relation: "reference", label: "runs" },
106
- { from: "AWS::ECS::Service", path: "LoadBalancers[].TargetGroupArn", relation: "reference", label: "registered in" },
107
- { from: "AWS::RDS::DBInstance", path: "DBSubnetGroupName", relation: "reference", label: "subnets" },
108
- { from: "AWS::RDS::DBInstance", path: "VPCSecurityGroups[]", relation: "reference", label: "sg" },
105
+ // logical ids are unique. Over an index (#4522) the same paths hold physical
106
+ // values, some of them names, so each carries the `indexedTargetKind` it
107
+ // takes there (ruled on INTENTIUS/behold#1023 Q4).
108
+ { from: "AWS::EC2::Subnet", path: "VpcId", indexedTargetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
109
+ { from: "AWS::EC2::SecurityGroup", path: "VpcId", indexedTargetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
110
+ { from: "AWS::EC2::RouteTable", path: "VpcId", indexedTargetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
111
+ { from: "AWS::EC2::Instance", path: "SubnetId", indexedTargetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
112
+ { from: "AWS::EC2::Instance", path: "SecurityGroupIds[]", indexedTargetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg" },
113
+ { from: "AWS::EC2::NatGateway", path: "SubnetId", indexedTargetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
114
+ { from: "AWS::EC2::Route", path: "RouteTableId", indexedTargetKind: "AWS::EC2::RouteTable", relation: "reference", label: "in" },
115
+ { from: "AWS::EC2::Route", path: "GatewayId", indexedTargetKind: "AWS::EC2::InternetGateway", relation: "reference", label: "via" },
116
+ { from: "AWS::EC2::Route", path: "NatGatewayId", indexedTargetKind: "AWS::EC2::NatGateway", relation: "reference", label: "via" },
117
+ { from: "AWS::ElasticLoadBalancingV2::LoadBalancer", path: "Subnets[]", indexedTargetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
118
+ { from: "AWS::ElasticLoadBalancingV2::LoadBalancer", path: "SecurityGroups[]", indexedTargetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg" },
119
+ { from: "AWS::ElasticLoadBalancingV2::TargetGroup", path: "VpcId", indexedTargetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
120
+ { from: "AWS::ElasticLoadBalancingV2::Listener", path: "LoadBalancerArn", indexedTargetKind: "AWS::ElasticLoadBalancingV2::LoadBalancer", relation: "reference", label: "on" },
121
+ { from: "AWS::ElasticLoadBalancingV2::Listener", path: "DefaultActions[].TargetGroupArn", indexedTargetKind: "AWS::ElasticLoadBalancingV2::TargetGroup", relation: "reference", label: "forwards to" },
122
+ { from: "AWS::ECS::Service", path: "Cluster", indexedTargetKind: "AWS::ECS::Cluster", relation: "reference", label: "in cluster" },
123
+ { from: "AWS::ECS::Service", path: "TaskDefinition", indexedTargetKind: "AWS::ECS::TaskDefinition", relation: "reference", label: "runs" },
124
+ { from: "AWS::ECS::Service", path: "LoadBalancers[].TargetGroupArn", indexedTargetKind: "AWS::ElasticLoadBalancingV2::TargetGroup", relation: "reference", label: "registered in" },
125
+ { from: "AWS::RDS::DBInstance", path: "DBSubnetGroupName", indexedTargetKind: "AWS::RDS::DBSubnetGroup", relation: "reference", label: "subnets" },
126
+ { from: "AWS::RDS::DBInstance", path: "VPCSecurityGroups[]", indexedTargetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg" },
127
+
128
+ // ── CloudFormation property shape, as Cloud Control returns it (#4522) ──
129
+ // The rules INTENTIUS/behold#1023's count found missing for an index of
130
+ // example-three-cloud. Targeted, so they hold over physical values and over
131
+ // logical ids alike.
132
+ { from: "AWS::EC2::VPCGatewayAttachment", path: "VpcId", targetKind: "AWS::EC2::VPC", relation: "reference", label: "attaches to" },
133
+ { from: "AWS::EC2::VPCGatewayAttachment", path: "InternetGatewayId", targetKind: "AWS::EC2::InternetGateway", relation: "reference", label: "attaches" },
134
+ { from: "AWS::EC2::NatGateway", path: "AllocationId", targetKind: "AWS::EC2::EIP", relation: "reference", label: "address" },
135
+ { from: "AWS::ECS::TaskDefinition", path: "ExecutionRoleArn", targetKind: "AWS::IAM::Role", relation: "reference", label: "execution role" },
136
+ { from: "AWS::ECS::TaskDefinition", path: "TaskRoleArn", targetKind: "AWS::IAM::Role", relation: "reference", label: "task role" },
137
+ { from: "AWS::ECS::TaskDefinition", path: "ContainerDefinitions[].LogConfiguration.Options.awslogs-group", targetKind: "AWS::Logs::LogGroup", relation: "reference", label: "logs to" },
138
+ { from: "AWS::EC2::SecurityGroup", path: "SecurityGroupIngress[].SourceSecurityGroupId", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "allows" },
139
+ { from: "AWS::Route53::RecordSet", path: "HostedZoneId", targetKind: "AWS::Route53::HostedZone", relation: "containment", label: "in zone" },
140
+ // A CNAME to another record of the estate (#4535: example-three-cloud's
141
+ // latency record for gcp points at gcp.three-cloud.example.). Optional,
142
+ // since most record values are addresses or hostnames outside it.
143
+ { from: "AWS::Route53::RecordSet", path: "ResourceRecords[]", targetKind: "AWS::Route53::RecordSet", relation: "reference", label: "aliases", optional: true },
144
+ ],
145
+ // Tags that name a cloud id in their key or value (behold#1023 Q5). Used
146
+ // over indexed nodes only. No rule matches equal tag values in general.
147
+ tagRefs: [
148
+ { key: "aws:cloudformation:stack-id", read: "value", targetKind: "AWS::CloudFormation::Stack", label: "in stack" },
149
+ { key: "aws:eks:cluster-name", read: "value", targetKind: "AWS::EKS::Cluster", label: "cluster" },
150
+ { key: "eks:cluster-name", read: "value", targetKind: "AWS::EKS::Cluster", label: "cluster" },
151
+ { key: "kubernetes.io/cluster/", read: "key-suffix", targetKind: "AWS::EKS::Cluster", label: "cluster" },
109
152
  ],
110
153
  };
@@ -1,20 +1,26 @@
1
1
  ---
2
2
  skill: chant-aws-carve-terraform
3
- description: Demo carving a resource out of Terraform into native chant — advise, emit, audit, bridge, apply — fully offline
3
+ description: Demo moving one Terraform resource to native CloudFormation, fully offline (advise, emit, audit, bridge, apply); Terraform keeps the rest
4
4
  user-invocable: true
5
5
  ---
6
6
 
7
- # Carve a resource out of Terraform (demo)
7
+ # Move one Terraform resource to CloudFormation (demo)
8
8
 
9
- Use this skill to cleanly demonstrate chant's Terraform carve-out flow for
10
- someone. The whole demo runs **offline** — no cloud account, no Terraform
11
- binary, no state backend. It carves an AWS S3 bucket out of a small Terraform
12
- estate into native chant source, patches the survivors, and plans the
13
- graduation.
9
+ Use this skill to demonstrate chant's carve flow, which moves one resource
10
+ from a Terraform estate to chant source for the AWS lexicon. The whole demo
11
+ runs **offline**, with no cloud account, Terraform binary or state backend. It
12
+ moves an S3 bucket from a small Terraform estate to chant source, patches the
13
+ resources that stay in Terraform, and plans the graduation.
14
14
 
15
15
  ## When to use
16
16
 
17
- - Someone asks "how does chant move things off Terraform?"
17
+ - Someone asks how chant can manage one resource from a Terraform root as
18
+ native CloudFormation.
19
+ - Someone on Terraform or OpenTofu asks how to get chant's ownership markers
20
+ on their resources. Point them at choudoufu instead
21
+ (`terraform.binary: "choudoufu"`, see
22
+ https://intentius.io/chant/lexicons/terraform/ops/#choudoufu). Their roots
23
+ stay in OpenTofu.
18
24
  - You want to show the advise → emit → audit → bridge → apply loop end to end.
19
25
  - You are evaluating whether a Terraform estate is worth carving.
20
26
 
@@ -40,12 +46,12 @@ Walk the person through the output. That is the whole demo.
40
46
 
41
47
  From `examples/terraform-carve-out`, with `TF=./terraform`:
42
48
 
43
- 1. **Advise — what is cheap to carve.**
49
+ 1. **Advise: rank the resources.**
44
50
  ```bash
45
51
  chant carve advise --from ./terraform
46
52
  ```
47
53
  Point out the three bands: clean leaves (carve now), carvable with edits,
48
- and leave-in-Terraform. `aws_s3_bucket.assets` is a clean leaf held back one
54
+ and stays in Terraform (`leave in Terraform` in the JSON). `aws_s3_bucket.assets` is a clean leaf held back one
49
55
  notch by the Lambda that reads it; `random_pet` has no native mapping.
50
56
 
51
57
  2. **Emit — adopt the bucket into chant source, offline, from state.**
@@ -68,9 +74,9 @@ From `examples/terraform-carve-out`, with `TF=./terraform`:
68
74
  chant build ./carveout/src --lexicon aws
69
75
  ```
70
76
  The first build fails, deliberately: the post-synth audit refuses the
71
- adopted bucket because Terraform managed it without a public-access block or
72
- a TLS-only policy. This is a feature of carving: chant immediately tells the
73
- person what is wrong with what they adopted. Show the fix (add
77
+ adopted bucket because it has no public-access block or TLS-only policy.
78
+ This is a feature of carving: chant tells the person which settings the
79
+ adopted resource is missing. Show the fix (add
74
80
  `PublicAccessBlockConfiguration` and a companion `S3BucketPolicy` with an
75
81
  `aws:SecureTransport = false` Deny — the tutorial page has the exact code),
76
82
  then re-run the build and show the valid CloudFormation template.
@@ -96,7 +102,8 @@ From `examples/terraform-carve-out`, with `TF=./terraform`:
96
102
 
97
103
  - Nothing is destroyed or applied; every step before graduation is reversible
98
104
  with `terraform import`.
99
- - You carve one resource at a time. The gnarly long tail stays in Terraform.
105
+ - You carve one resource at a time. Everything else stays in Terraform, where
106
+ it already works.
100
107
  - `advise` and `bridge` work against **any** Terraform tree — offer to point
101
108
  them at the person's own estate.
102
109
 
package/src/spec/fetch.ts CHANGED
@@ -33,6 +33,11 @@ export interface CFNSchema {
33
33
  cloudFormationSystemTags?: boolean;
34
34
  tagProperty?: string;
35
35
  };
36
+ /**
37
+ * The resource provider's handlers (`create`, `read`, `update`, `delete`,
38
+ * `list`), each with its IAM permissions. A legacy type has none (#4536).
39
+ */
40
+ handlers?: Record<string, unknown>;
36
41
  additionalProperties?: boolean;
37
42
  }
38
43
 
@@ -283,6 +283,21 @@ describe("parseCFNSchema", () => {
283
283
  });
284
284
  });
285
285
 
286
+ test("keeps the handlers section as its sorted operation names (#4536)", () => {
287
+ const schema = JSON.stringify({
288
+ typeName: "AWS::Test::Handled",
289
+ properties: { Name: { type: "string" } },
290
+ handlers: { read: { permissions: ["test:Get"] }, create: { permissions: ["test:Create"] }, delete: { permissions: [] } },
291
+ additionalProperties: false,
292
+ });
293
+ expect(parseCFNSchema(schema).resource.handlers).toEqual(["create", "delete", "read"]);
294
+ });
295
+
296
+ test("omits handlers when the schema has none, as a legacy type does (#4536)", () => {
297
+ const schema = JSON.stringify({ typeName: "AWS::Test::Legacy", properties: { Name: { type: "string" } }, additionalProperties: false });
298
+ expect(parseCFNSchema(schema).resource.handlers).toBeUndefined();
299
+ });
300
+
286
301
  test("omits tagging when not taggable", () => {
287
302
  const schema = JSON.stringify({
288
303
  typeName: "AWS::Test::NotTaggable",
package/src/spec/parse.ts CHANGED
@@ -80,6 +80,14 @@ export interface ParsedResource {
80
80
  conditionalCreateOnly: string[];
81
81
  replacementStrategy?: "delete_then_create" | "create_then_delete";
82
82
  tagging?: ResourceTagging;
83
+ /**
84
+ * The schema's `handlers` section as its operation names, sorted
85
+ * (`["create", "delete", "list", "read", "update"]`). The permissions each
86
+ * handler lists are left out. Absent when the schema has no handlers, as a
87
+ * legacy type does. CloudFormation can import a type with `create` and
88
+ * `read` (../importable.ts, #4536).
89
+ */
90
+ handlers?: string[];
83
91
  }
84
92
 
85
93
  /** How a type's tags are written: a `[{Key, Value}]` list or a key-to-value map. */
@@ -223,6 +231,9 @@ export function parseCFNSchema(data: string | Buffer): SchemaParseResult {
223
231
  };
224
232
  }
225
233
 
234
+ // --- Handlers (#4536): which operations the resource provider implements ---
235
+ const handlers = schema.handlers && typeof schema.handlers === "object" ? Object.keys(schema.handlers).sort() : [];
236
+
226
237
  // --- Replacement strategy ---
227
238
  let replacementStrategy: ParsedResource["replacementStrategy"];
228
239
  if (schema.replacementStrategy === "delete_then_create" || schema.replacementStrategy === "create_then_delete") {
@@ -252,6 +263,7 @@ export function parseCFNSchema(data: string | Buffer): SchemaParseResult {
252
263
  conditionalCreateOnly: stripPointerPaths(schema.conditionalCreateOnlyProperties ?? [], schema),
253
264
  ...(replacementStrategy && { replacementStrategy }),
254
265
  ...(tagging && { tagging }),
266
+ ...(handlers.length > 0 && { handlers }),
255
267
  },
256
268
  propertyTypes: boundedPropertyTypes,
257
269
  enums,
@@ -0,0 +1,65 @@
1
+ {
2
+ "listing": "v1",
3
+ "source": { "name": "behold-lister", "version": "0.0.0-fixture" },
4
+ "scope": {
5
+ "substrate": "aws",
6
+ "scopeId": "000000000000",
7
+ "locations": ["us-east-1"],
8
+ "types": ["AWS::EC2::Instance", "AWS::IAM::Role", "AWS::S3::Bucket", "AWS::SQS::Queue"]
9
+ },
10
+ "startedAt": "2026-10-26T09:00:00.000Z",
11
+ "completedAt": "2026-10-26T09:00:03.000Z",
12
+ "resources": [
13
+ {
14
+ "listedType": "AWS::S3::Bucket",
15
+ "location": "us-east-1",
16
+ "nativeId": "cli-made-assets",
17
+ "cloudIds": [{ "kind": "arn", "value": "arn:aws:s3:::cli-made-assets" }, { "kind": "import-id", "value": "cli-made-assets" }],
18
+ "tags": {},
19
+ "properties": { "BucketName": "cli-made-assets", "Arn": "arn:aws:s3:::cli-made-assets" },
20
+ "observedAt": "2026-10-26T09:00:01.000Z"
21
+ },
22
+ {
23
+ "listedType": "AWS::IAM::Role",
24
+ "location": "global",
25
+ "nativeId": "cli-made-role",
26
+ "cloudIds": [{ "kind": "arn", "value": "arn:aws:iam::000000000000:role/cli-made-role" }, { "kind": "import-id", "value": "cli-made-role" }],
27
+ "tags": {},
28
+ "properties": {
29
+ "RoleName": "cli-made-role",
30
+ "Arn": "arn:aws:iam::000000000000:role/cli-made-role",
31
+ "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": { "Service": "lambda.amazonaws.com" }, "Action": "sts:AssumeRole" }] }
32
+ },
33
+ "observedAt": "2026-10-26T09:00:01.000Z"
34
+ },
35
+ {
36
+ "listedType": "AWS::SQS::Queue",
37
+ "location": "us-east-1",
38
+ "nativeId": "http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/cli-made-queue",
39
+ "cloudIds": [{ "kind": "arn", "value": "arn:aws:sqs:us-east-1:000000000000:cli-made-queue" }],
40
+ "tags": {},
41
+ "properties": {
42
+ "QueueName": "cli-made-queue",
43
+ "QueueUrl": "http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/cli-made-queue",
44
+ "Arn": "arn:aws:sqs:us-east-1:000000000000:cli-made-queue"
45
+ },
46
+ "observedAt": "2026-10-26T09:00:02.000Z"
47
+ },
48
+ {
49
+ "listedType": "AWS::EC2::Instance",
50
+ "location": "us-east-1",
51
+ "nativeId": "i-0a1b2c3d4e5f60718",
52
+ "cloudIds": [{ "kind": "import-id", "value": "i-0a1b2c3d4e5f60718" }],
53
+ "tags": {},
54
+ "properties": { "InstanceId": "i-0a1b2c3d4e5f60718", "InstanceType": "t3.micro", "ImageId": "ami-0abcdef1234567890" },
55
+ "observedAt": "2026-10-26T09:00:02.000Z"
56
+ }
57
+ ],
58
+ "coverage": [
59
+ { "listedType": "AWS::EC2::Instance", "location": "us-east-1", "verdict": "listed" },
60
+ { "listedType": "AWS::IAM::Role", "location": "global", "verdict": "listed" },
61
+ { "listedType": "AWS::S3::Bucket", "location": "us-east-1", "verdict": "listed" },
62
+ { "listedType": "AWS::SQS::Queue", "location": "us-east-1", "verdict": "listed" }
63
+ ],
64
+ "notes": []
65
+ }
@@ -0,0 +1,126 @@
1
+ {
2
+ "listing": "v1",
3
+ "source": { "name": "behold-lister", "version": "0.0.0-fixture" },
4
+ "scope": {
5
+ "substrate": "aws",
6
+ "scopeId": "000000000000",
7
+ "locations": ["us-east-1"],
8
+ "types": "*"
9
+ },
10
+ "startedAt": "2026-10-26T10:00:00.000Z",
11
+ "completedAt": "2026-10-26T10:00:04.000Z",
12
+ "resources": [
13
+ {
14
+ "listedType": "AWS::EC2::VPC",
15
+ "location": "us-east-1",
16
+ "nativeId": "vpc-0imp",
17
+ "cloudIds": [{ "kind": "arn", "value": "arn:aws:ec2:us-east-1:000000000000:vpc/vpc-0imp" }, { "kind": "import-id", "value": "vpc-0imp" }],
18
+ "tags": { "Name": "shop", "aws:cloudformation:stack-name": "old-stack" },
19
+ "properties": {
20
+ "VpcId": "vpc-0imp",
21
+ "CidrBlock": "10.40.0.0/16",
22
+ "EnableDnsSupport": true,
23
+ "Tags": [{ "Key": "Name", "Value": "shop" }, { "Key": "aws:cloudformation:stack-name", "Value": "old-stack" }]
24
+ },
25
+ "observedAt": "2026-10-26T10:00:01.000Z"
26
+ },
27
+ {
28
+ "listedType": "AWS::EC2::Subnet",
29
+ "location": "us-east-1",
30
+ "nativeId": "subnet-0imp",
31
+ "cloudIds": [{ "kind": "arn", "value": "arn:aws:ec2:us-east-1:000000000000:subnet/subnet-0imp" }, { "kind": "import-id", "value": "subnet-0imp" }],
32
+ "tags": { "Name": "shop-a" },
33
+ "properties": {
34
+ "SubnetId": "subnet-0imp",
35
+ "VpcId": "vpc-0imp",
36
+ "CidrBlock": "10.40.1.0/24",
37
+ "AvailabilityZone": "us-east-1a",
38
+ "Tags": [{ "Key": "Name", "Value": "shop-a" }]
39
+ },
40
+ "observedAt": "2026-10-26T10:00:01.000Z"
41
+ },
42
+ {
43
+ "listedType": "AWS::EC2::SecurityGroup",
44
+ "location": "us-east-1",
45
+ "nativeId": "sg-0imp",
46
+ "cloudIds": [{ "kind": "arn", "value": "arn:aws:ec2:us-east-1:000000000000:security-group/sg-0imp" }, { "kind": "import-id", "value": "sg-0imp" }],
47
+ "tags": {},
48
+ "properties": {
49
+ "GroupId": "sg-0imp",
50
+ "GroupDescription": "shop web",
51
+ "VpcId": "vpc-0imp"
52
+ },
53
+ "observedAt": "2026-10-26T10:00:01.000Z"
54
+ },
55
+ {
56
+ "listedType": "AWS::IAM::Role",
57
+ "location": "global",
58
+ "nativeId": "imp-task-role",
59
+ "cloudIds": [{ "kind": "arn", "value": "arn:aws:iam::000000000000:role/imp-task-role" }, { "kind": "import-id", "value": "imp-task-role" }],
60
+ "tags": {},
61
+ "properties": {
62
+ "RoleName": "imp-task-role",
63
+ "Arn": "arn:aws:iam::000000000000:role/imp-task-role",
64
+ "RoleId": "AROAIMPTASKROLE00000",
65
+ "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": { "Service": "ecs-tasks.amazonaws.com" }, "Action": "sts:AssumeRole" }] }
66
+ },
67
+ "observedAt": "2026-10-26T10:00:02.000Z"
68
+ },
69
+ {
70
+ "listedType": "AWS::ECS::TaskDefinition",
71
+ "location": "us-east-1",
72
+ "nativeId": "arn:aws:ecs:us-east-1:000000000000:task-definition/imp:1",
73
+ "cloudIds": [{ "kind": "arn", "value": "arn:aws:ecs:us-east-1:000000000000:task-definition/imp:1" }],
74
+ "tags": {},
75
+ "properties": {
76
+ "TaskDefinitionArn": "arn:aws:ecs:us-east-1:000000000000:task-definition/imp:1",
77
+ "Family": "imp",
78
+ "Cpu": "256",
79
+ "Memory": "512",
80
+ "TaskRoleArn": "arn:aws:iam::000000000000:role/imp-task-role"
81
+ },
82
+ "observedAt": "2026-10-26T10:00:02.000Z"
83
+ },
84
+ {
85
+ "listedType": "AWS::RDS::DBInstance",
86
+ "location": "us-east-1",
87
+ "nativeId": "imp-db",
88
+ "cloudIds": [{ "kind": "arn", "value": "arn:aws:rds:us-east-1:000000000000:db:imp-db" }, { "kind": "import-id", "value": "imp-db" }],
89
+ "tags": {},
90
+ "properties": {
91
+ "DBInstanceIdentifier": "imp-db",
92
+ "DBInstanceArn": "arn:aws:rds:us-east-1:000000000000:db:imp-db",
93
+ "DBInstanceClass": "db.t3.micro",
94
+ "Engine": "postgres",
95
+ "MasterUsername": "app",
96
+ "MasterUserPassword": "[REDACTED]",
97
+ "Endpoint": { "Address": "imp-db.local", "Port": "5432" }
98
+ },
99
+ "observedAt": "2026-10-26T10:00:03.000Z"
100
+ },
101
+ {
102
+ "listedType": "AWS::S3::Bucket",
103
+ "location": "us-east-1",
104
+ "nativeId": "imp-assets",
105
+ "cloudIds": [{ "kind": "arn", "value": "arn:aws:s3:::imp-assets" }, { "kind": "import-id", "value": "imp-assets" }],
106
+ "tags": { "team": "shop" },
107
+ "properties": {
108
+ "BucketName": "imp-assets",
109
+ "Arn": "arn:aws:s3:::imp-assets",
110
+ "Tags": [{ "Key": "team", "Value": "shop" }]
111
+ },
112
+ "observedAt": "2026-10-26T10:00:03.000Z"
113
+ },
114
+ {
115
+ "listedType": "AWS::Example::NotGenerated",
116
+ "location": "us-east-1",
117
+ "nativeId": "x-1",
118
+ "cloudIds": [],
119
+ "tags": {},
120
+ "properties": { "Name": "x-1" },
121
+ "observedAt": "2026-10-26T10:00:03.000Z"
122
+ }
123
+ ],
124
+ "coverage": [{ "listedType": "*", "location": "*", "verdict": "listed" }],
125
+ "notes": []
126
+ }
@@ -0,0 +1,69 @@
1
+ {
2
+ "listing": "v1",
3
+ "source": { "name": "behold-lister", "version": "0.0.0-fixture" },
4
+ "scope": { "substrate": "aws", "scopeId": "000000000000", "locations": ["us-east-1"], "types": ["AWS::EC2::Volume", "AWS::IoTFleetHub::Application", "AWS::RDS::DBInstance", "AWS::S3::Bucket"] },
5
+ "startedAt": "2026-10-26T09:00:00.000Z",
6
+ "completedAt": "2026-10-26T09:00:04.000Z",
7
+ "resources": [
8
+ {
9
+ "listedType": "AWS::RDS::DBInstance",
10
+ "location": "us-east-1",
11
+ "nativeId": "orders-db",
12
+ "cloudIds": [{ "kind": "arn", "value": "arn:aws:rds:us-east-1:000000000000:db:orders-db" }, { "kind": "import-id", "value": "orders-db" }],
13
+ "tags": { "tofu-estate": "shop" },
14
+ "properties": {
15
+ "DBInstanceIdentifier": "orders-db",
16
+ "DBInstanceArn": "arn:aws:rds:us-east-1:000000000000:db:orders-db",
17
+ "Engine": "postgres",
18
+ "StorageEncrypted": true,
19
+ "MasterUserPassword": "<masked>",
20
+ "Tags": [{ "Key": "tofu-estate", "Value": "shop" }]
21
+ },
22
+ "observedAt": "2026-10-26T09:00:01.000Z",
23
+ "facts": { "markers": { "owner": "shop", "encoding": "escaped", "source": "live" }, "cloudIds": [{ "kind": "arn", "value": "arn:aws:rds:us-east-1:000000000000:db:orders-db" }, { "kind": "import-id", "value": "orders-db" }], "observedAt": "2026-10-26T09:00:01.000Z" }
24
+ },
25
+ {
26
+ "listedType": "AWS::RDS::DBInstance",
27
+ "location": "us-east-1",
28
+ "nativeId": "reports-db",
29
+ "cloudIds": [{ "kind": "import-id", "value": "reports-db" }],
30
+ "tags": {},
31
+ "properties": { "DBInstanceIdentifier": "reports-db", "Engine": "postgres", "StorageEncrypted": false },
32
+ "observedAt": "2026-10-26T09:00:01.000Z"
33
+ },
34
+ {
35
+ "listedType": "AWS::EC2::Volume",
36
+ "location": "us-east-1",
37
+ "nativeId": "vol-0a1b2c3d4e5f60718",
38
+ "cloudIds": [{ "kind": "import-id", "value": "vol-0a1b2c3d4e5f60718" }],
39
+ "tags": {},
40
+ "properties": { "VolumeId": "vol-0a1b2c3d4e5f60718", "AvailabilityZone": "us-east-1a", "Size": 20, "Encrypted": true },
41
+ "observedAt": "2026-10-26T09:00:02.000Z"
42
+ },
43
+ {
44
+ "listedType": "AWS::S3::Bucket",
45
+ "location": "us-east-1",
46
+ "nativeId": "shop-assets",
47
+ "cloudIds": [{ "kind": "arn", "value": "arn:aws:s3:::shop-assets" }, { "kind": "import-id", "value": "shop-assets" }],
48
+ "tags": {},
49
+ "properties": { "BucketName": "shop-assets", "Arn": "arn:aws:s3:::shop-assets" },
50
+ "observedAt": "2026-10-26T09:00:03.000Z"
51
+ },
52
+ {
53
+ "listedType": "AWS::IoTFleetHub::Application",
54
+ "location": "us-east-1",
55
+ "nativeId": "fleet-console",
56
+ "cloudIds": [{ "kind": "import-id", "value": "fleet-console" }],
57
+ "tags": {},
58
+ "properties": { "ApplicationName": "fleet-console", "RoleArn": "arn:aws:iam::000000000000:role/fleet" },
59
+ "observedAt": "2026-10-26T09:00:03.000Z"
60
+ }
61
+ ],
62
+ "coverage": [
63
+ { "listedType": "AWS::EC2::Volume", "location": "us-east-1", "verdict": "listed" },
64
+ { "listedType": "AWS::IoTFleetHub::Application", "location": "us-east-1", "verdict": "listed" },
65
+ { "listedType": "AWS::RDS::DBInstance", "location": "us-east-1", "verdict": "listed" },
66
+ { "listedType": "AWS::S3::Bucket", "location": "us-east-1", "verdict": "listed" }
67
+ ],
68
+ "notes": []
69
+ }