@aetherwing/fcp-terraform 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Scott Meyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,252 @@
+# fcp-terraform
+
+MCP server for Terraform HCL generation through intent-level commands.
+
+## What It Does
+
+fcp-terraform lets LLMs build Terraform configurations by describing infrastructure intent -- resources, data sources, variables, outputs -- and renders them into valid HCL. Instead of writing raw HCL syntax, the LLM sends operations like `add resource aws_instance web ami:"ami-0c55b159" instance_type:t2.micro` and fcp-terraform manages the semantic model, dependency graph, and serialization. Built on the [FCP](https://github.com/aetherwing-io/fcp) framework.
+
+## Quick Example
+
+```
+terraform_session('new "Main Infrastructure"')
+
+terraform([
+  'add resource aws_instance web ami:"ami-0c55b159" instance_type:t2.micro',
+  'add resource aws_s3_bucket assets bucket:"my-assets"',
+  'add variable region default:"us-east-1" type:string',
+  'add output instance_ip value:"aws_instance.web.public_ip"',
+])
+
+terraform_query('plan')
+```
+
+The `plan` query produces:
+
+```hcl
+variable "region" {
+  type    = string
+  default = "us-east-1"
+}
+
+resource "aws_instance" "web" {
+  ami           = "ami-0c55b159"
+  instance_type = "t2.micro"
+}
+
+resource "aws_s3_bucket" "assets" {
+  bucket = "my-assets"
+}
+
+output "instance_ip" {
+  value = aws_instance.web.public_ip
+}
+```
+
+### Available MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `terraform(ops)` | Batch mutations -- add, set, remove, connect, nest, label, style |
+| `terraform_query(q)` | Inspect the config -- map, list, describe, plan, graph, validate, find |
+| `terraform_session(action)` | Lifecycle -- new, open, save, checkpoint, undo, redo |
+| `terraform_help()` | Full reference card |
+
+### Supported Block Types
+
+| Verb | Syntax |
+|------|--------|
+| `add resource` | `add resource TYPE LABEL [key:value...]` |
+| `add provider` | `add provider PROVIDER [region:R] [key:value...]` |
+| `add variable` | `add variable NAME [type:T] [default:V] [description:D]` |
+| `add output` | `add output NAME value:EXPR [description:D]` |
+| `add data` | `add data TYPE LABEL [key:value...]` |
+| `add module` | `add module LABEL source:PATH [key:value...]` |
+| `connect` | `connect SRC -> TGT [label:TEXT]` |
+| `set` | `set LABEL key:value [key:value...]` |
+| `nest` | `nest LABEL BLOCK_TYPE [key:value...]` |
+| `remove` | `remove LABEL` or `remove @SELECTOR` |
+
+### Selectors
+
+```
+@type:aws_instance      All resources of a given type
+@provider:aws            All blocks from a given provider
+@kind:resource           All blocks of kind (resource, variable, output, data)
+@tag:KEY or @tag:KEY=VAL Blocks matching a tag
+@all                     All blocks
+```
+
+## Installation
+
+Requires Node >= 18.
+
+```bash
+npm install @aetherwing/fcp-terraform
+```
+
+### MCP Client Configuration
+
+```json
+{
+  "mcpServers": {
+    "terraform": {
+      "command": "node",
+      "args": ["node_modules/@aetherwing/fcp-terraform/dist/index.js"]
+    }
+  }
+}
+```
+
+## Architecture
+
+3-layer architecture:
+
+```
+MCP Server (Intent Layer)
+  src/server/ -- Parses op strings, resolves refs, dispatches
+        |
+Semantic Model (Domain)
+  src/model/ -- In-memory Terraform graph (resources, data, variables, outputs)
+  src/types/ -- Core TypeScript interfaces
+        |
+Serialization (HCL)
+  src/hcl.ts -- Semantic model -> HCL text output
+```
+
+Supporting modules:
+
+- `src/ops.ts` -- Operation string parser
+- `src/verbs.ts` -- Verb specs and reference card
+- `src/queries.ts` -- Query dispatcher (map, plan, graph, validate, etc.)
+- `src/adapter.ts` -- FCP core adapter
+
+Provider is auto-detected from resource type prefixes (`aws_`, `google_`, `azurerm_`).
+
+## Worked Example: AWS Production Web Stack
+
+A realistic deployment showing how operations compose. This example creates a VPC with subnets, EC2, RDS, S3, IAM, and security groups -- 13 resources total.
+
+```
+terraform_session('new "Acme Corp Web Stack"')
+
+# Provider + Variables
+terraform([
+  'add provider aws region:us-east-1',
+  'add variable environment type:string default:"production" description:"Deployment environment"',
+  'add variable project_name type:string default:"acme-web" description:"Project name"',
+  'add variable vpc_cidr type:string default:"10.0.0.0/16" description:"VPC CIDR block"',
+  'add variable instance_type type:string default:"t3.medium" description:"EC2 instance type"',
+  'add variable db_instance_class type:string default:"db.t3.medium" description:"RDS instance class"',
+])
+
+# Networking
+terraform([
+  'add resource aws_vpc main cidr_block:var.vpc_cidr enable_dns_support:true enable_dns_hostnames:true',
+  'add resource aws_subnet public_a vpc_id:aws_vpc.main.id cidr_block:"10.0.1.0/24" map_public_ip_on_launch:true',
+  'add resource aws_subnet public_b vpc_id:aws_vpc.main.id cidr_block:"10.0.2.0/24" map_public_ip_on_launch:true',
+  'add resource aws_internet_gateway igw vpc_id:aws_vpc.main.id',
+  'add resource aws_route_table public vpc_id:aws_vpc.main.id',
+])
+
+# Nested blocks for route table and security groups
+terraform([
+  'nest public route cidr_block:"0.0.0.0/0" gateway_id:aws_internet_gateway.igw.id',
+  'add resource aws_security_group web name:"${var.project_name}-web-sg" vpc_id:aws_vpc.main.id',
+  'nest web ingress from_port:80 to_port:80 protocol:"tcp"',
+  'nest web ingress from_port:443 to_port:443 protocol:"tcp"',
+  'nest web egress from_port:0 to_port:0 protocol:"-1"',
+])
+
+# Compute + Database
+terraform([
+  'add resource aws_instance webserver ami:"ami-0c55b159" instance_type:var.instance_type subnet_id:aws_subnet.public_a.id',
+  'nest webserver root_block_device volume_size:20 volume_type:"gp3"',
+  'add resource aws_db_subnet_group dbsubnet name:"${var.project_name}-db-subnet"',
+  'set dbsubnet subnet_ids:"[aws_subnet.public_a.id,aws_subnet.public_b.id]"',
+  'add resource aws_db_instance rds engine:"postgresql" instance_class:var.db_instance_class allocated_storage:20',
+  'add resource aws_s3_bucket assets bucket:"${var.project_name}-assets-${var.environment}"',
+])
+
+# Outputs
+terraform([
+  'add output vpc_id value:aws_vpc.main.id',
+  'add output web_ip value:aws_instance.webserver.public_ip',
+  'add output db_endpoint value:aws_db_instance.rds.endpoint',
+])
+
+# Tags (all resources at once)
+terraform([
+  'style main tags:"Name=${var.project_name}-vpc,Environment=${var.environment}"',
+  'style public_a tags:"Name=${var.project_name}-public-a,Environment=${var.environment}"',
+  'style public_b tags:"Name=${var.project_name}-public-b,Environment=${var.environment}"',
+  'style igw tags:"Name=${var.project_name}-igw,Environment=${var.environment}"',
+  'style webserver tags:"Name=${var.project_name}-web,Environment=${var.environment}"',
+  'style rds tags:"Name=${var.project_name}-db,Environment=${var.environment}"',
+  'style assets tags:"Name=${var.project_name}-assets,Environment=${var.environment}"',
+])
+
+# Day-2 modifications
+terraform([
+  'label webserver app_server',                         # Rename
+  'set instance_type default:"t3.large"',               # Change default
+  'remove assets',                                       # Replace S3 bucket
+  'add resource aws_s3_bucket static_assets bucket:"${var.project_name}-static-${var.environment}"',
+])
+
+terraform_query('plan')  # Export final HCL
+```
+
+## Capability Matrix
+
+| Capability | Status | Notes |
+|------------|--------|-------|
+| Resources, data sources, modules | Supported | All Terraform block types |
+| Variables with types and defaults | Supported | string, number, bool, list, map, object |
+| Outputs | Supported | Simple value expressions |
+| Nested blocks (ingress, egress, route, filter) | Supported | Via `nest` verb |
+| Tags | Supported | Via `style` verb with `tags:"K=V,K2=V2"` |
+| Rename blocks | Partial | `label` renames but does not cascade references |
+| Selectors for bulk operations | Partial | `remove @selector` works; `style @selector` not yet supported |
+| `jsonencode()` / HCL functions | Not supported | Complex expressions containing colons conflict with the DSL tokenizer |
+| Nested block removal/editing | Not supported | Nested blocks are append-only |
+| `count` / `for_each` meta-arguments | Not supported | `set` cannot modify meta-arguments |
+
+## Known Limitations
+
+The following issues were identified through competitive validation against raw HCL writing. They are tracked for resolution.
+
+**HCL Serialization**
+
+- **List values in nested blocks render without quotes.** Attributes like `cidr_blocks`, `security_groups`, and `values` in filter/ingress/egress blocks output `[0.0.0.0/0]` instead of `["0.0.0.0/0"]`. This produces invalid HCL. Workaround: post-process the output or use `terraform_query('plan')` output as a starting point for manual fixes.
+
+- **String values may lose their type.** Setting `engine_version:"15"` renders as `engine_version = 15` (number). The serializer does not preserve explicit string quoting for numeric-looking values.
+
+- **Output values with interpolation render unquoted.** An output `value:"VPC: ${aws_vpc.main.id}"` renders without surrounding quotes.
+
+**Labels**
+
+- **Labels are globally unique.** You cannot use `main` for both `aws_vpc.main` and `aws_internet_gateway.main` even though Terraform allows this (labels are scoped per type). Use distinct labels like `igw`, `rds`, `dbsubnet`.
+
+- **`label` rename breaks the lookup index.** After renaming a block with `label old new`, subsequent `style new` or `set new` calls may return "block not found". The internal index is not rebuilt after rename.
+
+**Nested Blocks**
+
+- **Cannot remove or edit specific nested blocks.** Once added via `nest`, a nested block (ingress rule, route, filter) cannot be individually removed or modified. If a `nest` call produces an error but partially succeeds, the ghost block persists.
+
+**Expressions**
+
+- **JSON with colons conflicts with the DSL tokenizer.** IAM `assume_role_policy` or similar JSON-containing attributes are parsed as key:value pairs by the FCP tokenizer, producing bare JSON objects instead of quoted strings or `jsonencode()` calls.
+
+## Development
+
+```bash
+npm install
+npm run build     # tsc
+npm test          # vitest, 138 tests
+```
+
+## License
+
+MIT
+

package/dist/adapter.d.ts

@@ -0,0 +1,14 @@
+import type { FcpDomainAdapter, OpResult, ParsedOp } from "@aetherwing/fcp-core";
+import type { EventLog } from "@aetherwing/fcp-core";
+import type { TerraformConfig, TerraformEvent } from "./types.js";
+export declare class TerraformAdapter implements FcpDomainAdapter<TerraformConfig, TerraformEvent> {
+    createEmpty(title: string, params: Record<string, string>): TerraformConfig;
+    serialize(model: TerraformConfig): string;
+    deserialize(data: Buffer | string): TerraformConfig;
+    rebuildIndices(model: TerraformConfig): void;
+    getDigest(model: TerraformConfig): string;
+    dispatchOp(op: ParsedOp, model: TerraformConfig, log: EventLog<TerraformEvent>): OpResult;
+    dispatchQuery(query: string, model: TerraformConfig): string | Promise<string>;
+    reverseEvent(event: TerraformEvent, model: TerraformConfig): void;
+    replayEvent(event: TerraformEvent, model: TerraformConfig): void;
+}

package/dist/adapter.js

@@ -0,0 +1,266 @@
+import { createEmptyConfig, rebuildLabelIndex, findByKind, addBlock, removeBlock, addConnection, removeConnection, createBlock, } from "./model.js";
+import { dispatchOp } from "./ops.js";
+import { dispatchQuery } from "./queries.js";
+// Keep a reference to the event log for queries that need it
+let currentEventLog;
+export class TerraformAdapter {
+    createEmpty(title, params) {
+        const config = createEmptyConfig(title);
+        // Auto-add provider if specified
+        if (params["provider"]) {
+            const providerName = params["provider"];
+            const providerParams = {};
+            if (params["region"])
+                providerParams["region"] = params["region"];
+            const block = createBlock("provider", providerName, providerName, providerParams);
+            block.provider = providerName;
+            addBlock(config, block);
+        }
+        rebuildLabelIndex(config);
+        return config;
+    }
+    serialize(model) {
+        return JSON.stringify(configToJson(model), null, 2);
+    }
+    deserialize(data) {
+        const json = JSON.parse(typeof data === "string" ? data : data.toString());
+        return jsonToConfig(json);
+    }
+    rebuildIndices(model) {
+        rebuildLabelIndex(model);
+    }
+    getDigest(model) {
+        const resources = findByKind(model, "resource").length;
+        const variables = findByKind(model, "variable").length;
+        const outputs = findByKind(model, "output").length;
+        const providers = findByKind(model, "provider").map((p) => p.label);
+        const provStr = providers.length > 0 ? ` | ${providers.join(",")}` : "";
+        return `[${resources}r ${variables}v ${outputs}o ${model.connections.size}c${provStr}]`;
+    }
+    dispatchOp(op, model, log) {
+        currentEventLog = log;
+        return dispatchOp(op, model, log);
+    }
+    dispatchQuery(query, model) {
+        return dispatchQuery(query, model, currentEventLog);
+    }
+    reverseEvent(event, model) {
+        switch (event.type) {
+            case "block_added":
+                removeBlock(model, event.block.id);
+                break;
+            case "block_removed": {
+                const restored = restoreBlock(event.block);
+                addBlock(model, restored);
+                break;
+            }
+            case "attribute_set": {
+                const block = model.blocks.get(event.blockId);
+                if (!block)
+                    return;
+                if (event.before === null) {
+                    block.attributes.delete(event.key);
+                }
+                else {
+                    block.attributes.set(event.key, structuredClone(event.before));
+                }
+                break;
+            }
+            case "attribute_removed": {
+                const block = model.blocks.get(event.blockId);
+                if (!block)
+                    return;
+                block.attributes.set(event.key, structuredClone(event.before));
+                break;
+            }
+            case "connection_added":
+                removeConnection(model, event.connection.id);
+                break;
+            case "connection_removed":
+                addConnection(model, structuredClone(event.connection));
+                break;
+            case "tag_set": {
+                const block = model.blocks.get(event.blockId);
+                if (!block)
+                    return;
+                if (event.before === null) {
+                    block.tags.delete(event.key);
+                }
+                else {
+                    block.tags.set(event.key, event.before);
+                }
+                break;
+            }
+            case "tag_removed": {
+                const block = model.blocks.get(event.blockId);
+                if (!block)
+                    return;
+                block.tags.set(event.key, event.before);
+                break;
+            }
+            case "nested_block_added": {
+                const block = model.blocks.get(event.blockId);
+                if (!block)
+                    return;
+                block.nestedBlocks = block.nestedBlocks.filter((nb) => nb.id !== event.nestedBlock.id);
+                break;
+            }
+            case "nested_block_removed": {
+                const block = model.blocks.get(event.blockId);
+                if (!block)
+                    return;
+                block.nestedBlocks.push(restoreNestedBlock(event.nestedBlock));
+                break;
+            }
+            case "block_renamed": {
+                const block = model.blocks.get(event.blockId);
+                if (block)
+                    block.label = event.before;
+                break;
+            }
+            case "title_changed":
+                model.title = event.before;
+                break;
+        }
+        rebuildLabelIndex(model);
+    }
+    replayEvent(event, model) {
+        switch (event.type) {
+            case "block_added": {
+                const restored = restoreBlock(event.block);
+                addBlock(model, restored);
+                break;
+            }
+            case "block_removed":
+                removeBlock(model, event.block.id);
+                break;
+            case "attribute_set": {
+                const block = model.blocks.get(event.blockId);
+                if (!block)
+                    return;
+                block.attributes.set(event.key, structuredClone(event.after));
+                break;
+            }
+            case "attribute_removed": {
+                const block = model.blocks.get(event.blockId);
+                if (!block)
+                    return;
+                block.attributes.delete(event.key);
+                break;
+            }
+            case "connection_added":
+                addConnection(model, structuredClone(event.connection));
+                break;
+            case "connection_removed":
+                removeConnection(model, event.connection.id);
+                break;
+            case "tag_set": {
+                const block = model.blocks.get(event.blockId);
+                if (!block)
+                    return;
+                block.tags.set(event.key, event.after);
+                break;
+            }
+            case "tag_removed": {
+                const block = model.blocks.get(event.blockId);
+                if (!block)
+                    return;
+                block.tags.delete(event.key);
+                break;
+            }
+            case "nested_block_added": {
+                const block = model.blocks.get(event.blockId);
+                if (!block)
+                    return;
+                block.nestedBlocks.push(restoreNestedBlock(event.nestedBlock));
+                break;
+            }
+            case "nested_block_removed": {
+                const block = model.blocks.get(event.blockId);
+                if (!block)
+                    return;
+                block.nestedBlocks = block.nestedBlocks.filter((nb) => nb.id !== event.nestedBlock.id);
+                break;
+            }
+            case "block_renamed": {
+                const block = model.blocks.get(event.blockId);
+                if (block)
+                    block.label = event.after;
+                break;
+            }
+            case "title_changed":
+                model.title = event.after;
+                break;
+        }
+        rebuildLabelIndex(model);
+    }
+}
+// ── Serialization helpers ─────────────────────────────
+function configToJson(config) {
+    return {
+        id: config.id,
+        title: config.title,
+        filePath: config.filePath,
+        blockOrder: config.blockOrder,
+        blocks: Object.fromEntries([...config.blocks.entries()].map(([id, block]) => [id, blockToJson(block)])),
+        connections: Object.fromEntries([...config.connections.entries()].map(([id, conn]) => [id, conn])),
+    };
+}
+function blockToJson(block) {
+    return {
+        ...block,
+        attributes: Object.fromEntries(block.attributes),
+        tags: Object.fromEntries(block.tags),
+        nestedBlocks: block.nestedBlocks.map((nb) => ({
+            id: nb.id,
+            type: nb.type,
+            attributes: Object.fromEntries(nb.attributes),
+        })),
+    };
+}
+function jsonToConfig(json) {
+    const blocks = new Map();
+    const jsonBlocks = json["blocks"];
+    for (const [id, jb] of Object.entries(jsonBlocks)) {
+        blocks.set(id, restoreBlock(jb));
+    }
+    const connections = new Map();
+    const jsonConns = json["connections"];
+    for (const [id, conn] of Object.entries(jsonConns)) {
+        connections.set(id, conn);
+    }
+    return {
+        id: json["id"],
+        title: json["title"],
+        filePath: json["filePath"],
+        blocks,
+        connections,
+        blockOrder: json["blockOrder"],
+    };
+}
+function restoreBlock(data) {
+    const attrs = data.attributes instanceof Map
+        ? data.attributes
+        : new Map(Object.entries(data.attributes));
+    const tags = data.tags instanceof Map
+        ? data.tags
+        : new Map(Object.entries(data.tags));
+    const nestedBlocks = (data.nestedBlocks ?? []).map(restoreNestedBlock);
+    return {
+        id: data.id,
+        kind: data.kind,
+        label: data.label,
+        fullType: data.fullType,
+        provider: data.provider,
+        attributes: attrs,
+        nestedBlocks,
+        tags,
+        meta: data.meta ?? { dependsOn: [] },
+    };
+}
+function restoreNestedBlock(data) {
+    const attrs = data.attributes instanceof Map
+        ? data.attributes
+        : new Map(Object.entries(data.attributes));
+    return { id: data.id, type: data.type, attributes: attrs };
+}

package/dist/hcl.d.ts

@@ -0,0 +1,5 @@
+import type { TerraformConfig } from "./types.js";
+/**
+ * Serialize a TerraformConfig to valid HCL.
+ */
+export declare function serializeToHcl(config: TerraformConfig): string;