react-hcl 0.1.0

package/dist/components/data-source.d.ts

@@ -0,0 +1,21 @@
+/**
+ * DataSource component — produces a DataSourceBlock for the Block[] IR pipeline.
+ *
+ * Extracts `type` and `name` as block labels, passes remaining props as HCL attributes.
+ * Special props `ref` and `children` are excluded from attributes:
+ *   - `ref`: reserved for useRef (Step 8)
+ *   - `children`: if string, stored as `innerText`
+ *
+ * Usage in TSX:
+ *   <DataSource type="aws_ami" name="latest" most_recent={true} />
+ *   → data "aws_ami" "latest" { most_recent = true }
+ */
+import type { DataSourceBlock } from "../blocks";
+export declare function DataSource(props: {
+    type: string;
+    name: string;
+    ref?: any;
+    children?: string | string[];
+    attributes?: Record<string, any>;
+    [key: string]: any;
+}): DataSourceBlock;

package/dist/components/index.d.ts

@@ -0,0 +1,8 @@
+export { DataSource } from "./data-source";
+export { Locals } from "./locals";
+export { Module } from "./module";
+export { Output } from "./output";
+export { Provider } from "./provider";
+export { Resource } from "./resource";
+export { Terraform } from "./terraform";
+export { Variable } from "./variable";

package/dist/components/locals.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Locals component — produces a LocalsBlock for the Block[] IR pipeline.
+ *
+ * All props become HCL attributes (there is no name label for locals blocks).
+ * The `children` prop is excluded as it's a JSX-internal prop.
+ *
+ * Usage in TSX:
+ *   <Locals environment="prod" project_name="my-app" />
+ *   → locals { environment = "prod"\n  project_name = "my-app" }
+ */
+import type { LocalsBlock } from "../blocks";
+export declare function Locals(props: Record<string, any>): LocalsBlock;

package/dist/components/module.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Module component — produces a ModuleBlock for the Block[] IR pipeline.
+ *
+ * Extracts `name` as the block label, passes remaining props as HCL attributes.
+ * Reserved props `ref` and `children` are excluded from attributes:
+ *   - `ref`: reserved for useRef — resolves to module.<name>.<output>
+ *   - `children`: if string, stored as `innerText` for raw HCL body output
+ *
+ * Special handling for `depends_on` and `providers`:
+ *   - `depends_on`: ref proxies are resolved to raw("module.name") / raw("type.name")
+ *   - `providers`: ref proxies are resolved to raw("type.alias") with attribute() wrapper
+ *
+ * Usage in TSX:
+ *   <Module name="vpc" source="terraform-aws-modules/vpc/aws" version="~> 5.0" cidr="10.0.0.0/16" />
+ *   → module "vpc" { source = "terraform-aws-modules/vpc/aws" version = "~> 5.0" cidr = "10.0.0.0/16" }
+ */
+import type { ModuleBlock } from "../blocks";
+export declare function Module(props: {
+    name: string;
+    ref?: any;
+    children?: string | string[];
+    attributes?: Record<string, any>;
+    [key: string]: any;
+}): ModuleBlock;

package/dist/components/output.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Output component — produces an OutputBlock for the Block[] IR pipeline.
+ *
+ * Extracts `name` as the block label, passes remaining props (value, description, sensitive, etc.)
+ * as HCL attributes.
+ *
+ * Usage in TSX:
+ *   <Output name="vpc_id" value="aws_vpc.main.id" />
+ *   → output "vpc_id" { value = "aws_vpc.main.id" }
+ */
+import type { OutputBlock } from "../blocks";
+export declare function Output(props: {
+    name: string;
+    value: any;
+    description?: string;
+    sensitive?: boolean;
+    [key: string]: any;
+}): OutputBlock;

package/dist/components/provider.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Provider component — produces a ProviderBlock for the Block[] IR pipeline.
+ *
+ * Extracts `type` as the block label, passes remaining props as HCL attributes.
+ * Special props `ref` is excluded from attributes (reserved for useRef).
+ * If both `ref` and `alias` are provided, the alias is stored on the ref metadata
+ * so that references resolve to `<type>.<alias>`.
+ *
+ * Usage in TSX:
+ *   <Provider type="aws" region="ap-northeast-1" />
+ *   → provider "aws" { region = "ap-northeast-1" }
+ */
+import type { ProviderBlock } from "../blocks";
+export declare function Provider(props: {
+    type: string;
+    ref?: any;
+    alias?: string;
+    [key: string]: any;
+}): ProviderBlock;

package/dist/components/resource.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Resource component — produces a ResourceBlock for the Block[] IR pipeline.
+ *
+ * Extracts `type` and `name` as block labels, passes remaining props as HCL attributes.
+ * Special props `ref` and `children` are excluded from attributes:
+ *   - `ref`: reserved for useRef (Step 8)
+ *   - `children`: if string, stored as `innerText` for raw HCL body output (Step 10)
+ *
+ * Usage in TSX:
+ *   <Resource type="aws_vpc" name="main" cidr_block="10.0.0.0/16" />
+ *   → resource "aws_vpc" "main" { cidr_block = "10.0.0.0/16" }
+ */
+import type { ResourceBlock } from "../blocks";
+export declare function Resource(props: {
+    type: string;
+    name: string;
+    ref?: any;
+    children?: string | string[];
+    attributes?: Record<string, any>;
+    [key: string]: any;
+}): ResourceBlock;

package/dist/components/terraform.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Terraform component — produces a TerraformBlock for the Block[] IR pipeline.
+ *
+ * All props become HCL attributes. Supports `children` as raw HCL text (innerText)
+ * for nested blocks like `backend "s3" { ... }` that need verbatim HCL.
+ *
+ * Usage in TSX:
+ *   <Terraform required_version=">= 1.0" />
+ *   → terraform { required_version = ">= 1.0" }
+ */
+import type { TerraformBlock } from "../blocks";
+export declare function Terraform(props: {
+    children?: string | string[];
+    [key: string]: any;
+}): TerraformBlock;

package/dist/components/variable.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Variable component — produces a VariableBlock for the Block[] IR pipeline.
+ *
+ * Extracts `name` as the block label.
+ * The `type` prop is automatically wrapped with raw() so that HCL outputs `type = string`
+ * (unquoted) rather than `type = "string"` (quoted). This lets users write naturally:
+ *   <Variable name="env" type="string" />
+ *
+ * Usage in TSX:
+ *   <Variable name="environment" type="string" default="dev" />
+ *   → variable "environment" { type = string\n  default = "dev" }
+ */
+import type { VariableBlock } from "../blocks";
+export declare function Variable(props: {
+    name: string;
+    type?: string;
+    default?: any;
+    description?: string;
+    sensitive?: boolean;
+    [key: string]: any;
+}): VariableBlock;

package/dist/conflict.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Conflict detection for Terraform blocks.
+ *
+ * Validates that the collected Block[] does not contain duplicates that would
+ * produce invalid Terraform configuration. This runs after render() and before
+ * generate() in the CLI pipeline.
+ *
+ * Conflict rules (from design doc §5.2):
+ *   - Resource: duplicate type + name → error
+ *   - DataSource: duplicate type + name → error
+ *   - Resource vs DataSource with same type + name → allowed
+ *   - Variable: duplicate name → error
+ *   - Output: duplicate name → error
+ *   - Locals: multiple blocks → allowed
+ *   - Provider: same type with different alias → allowed; same type + alias → error
+ *   - Terraform: more than one block → error
+ *   - Module: duplicate name → error
+ */
+import type { Block } from "./blocks";
+export declare class ConflictError extends Error {
+    constructor(message: string);
+}
+/**
+ * Detect conflicts in a list of blocks and throw ConflictError if any are found.
+ *
+ * Checks each block type independently. For provider blocks, alias is extracted
+ * from attributes (absence of alias is treated as empty string for grouping).
+ */
+export declare function detectConflicts(blocks: Block[]): void;

package/dist/generator.d.ts

@@ -0,0 +1,36 @@
+/**
+ * HCL code generator — converts Block[] intermediate representation into a Terraform .tf file string.
+ *
+ * This module is the final stage of the pipeline:
+ *   JSX components → Block[] (IR) → generate() → HCL string
+ *
+ * Output formatting rules:
+ *   - Each block is rendered as: <header> {\n<body>\n}
+ *   - Blocks are separated by a single blank line (\n\n)
+ *   - The output always ends with a trailing newline
+ *   - If a block has `innerText`, it is used as-is as the body (no attribute serialization)
+ *   - Otherwise, attributes are serialized via serializeHCLAttributes() from hcl-serializer.ts
+ *   - Empty attribute blocks produce: <header> {\n}
+ */
+import type { Block } from "./blocks";
+/**
+ * Generates a complete Terraform .tf file string from an array of Block objects.
+ *
+ * @param blocks - Array of Block IR objects to render
+ * @returns A string of valid HCL with blocks separated by blank lines, ending with a newline
+ *
+ * Example:
+ *   generate([
+ *     { blockType: "resource", type: "aws_vpc", name: "main", attributes: { cidr_block: "10.0.0.0/16" } },
+ *     { blockType: "resource", type: "aws_subnet", name: "public", attributes: { cidr_block: "10.0.1.0/24" } },
+ *   ])
+ *   →
+ *   resource "aws_vpc" "main" {
+ *     cidr_block = "10.0.0.0/16"
+ *   }
+ *
+ *   resource "aws_subnet" "public" {
+ *     cidr_block = "10.0.1.0/24"
+ *   }
+ */
+export declare function generate(blocks: Block[]): string;

package/dist/hcl-serializer.d.ts

@@ -0,0 +1,144 @@
+/**
+ * HCL attribute serializer — converts JavaScript objects into HCL attribute syntax.
+ *
+ * This module handles the serialization of key-value attribute pairs inside HCL blocks.
+ * It distinguishes between two HCL syntactic forms:
+ *
+ *   1. Attribute syntax:  key = value     (uses `=` sign)
+ *   2. Block syntax:      key { ... }     (no `=` sign, used for nested blocks)
+ *
+ * The serializer automatically determines which syntax to use based on:
+ *   - Explicit BlockHCL marker → always block syntax
+ *   - Key name in BLOCK_WHITELIST + plain object value → block syntax
+ *   - Plain object value (not in whitelist) → attribute syntax with `=` (e.g. tags = { ... })
+ *   - Array of plain objects → repeated block syntax (e.g. multiple ingress { } blocks)
+ *   - Primitive values (string, number, boolean) and arrays of primitives → attribute syntax
+ *
+ * Three marker types represent the HCL value categories:
+ *   - RawHCL: outputs a string value without quotes (for Terraform references like var.foo)
+ *   - BlockHCL: block syntax for a nested object (key { ... }, no `=`)
+ *   - AttributeHCL: attribute syntax for a nested object (key = { ... }, with `=`)
+ *
+ * All three are user-facing — users can explicitly wrap values with raw(), block(), or attribute().
+ * When no marker is specified, the serializer auto-classifies plain objects:
+ *   - Key in BLOCK_WHITELIST → auto block()
+ *   - Otherwise              → auto attribute()
+ * Explicit markers always take precedence over auto-classification.
+ *
+ * Formatting:
+ *   - Simple attributes are aligned by padding key names to the same width
+ *   - Block entries are separated from simple attributes by a blank line
+ *   - Indentation increases by 2 spaces per nesting level (default starts at 2)
+ */
+/**
+ * RawHCL — marker type for unquoted HCL expressions.
+ *
+ * In HCL, some values must not be quoted (e.g. variable references, function calls):
+ *   vpc_id = aws_vpc.main.id       ← raw (no quotes)
+ *   name   = "my-vpc"              ← string (quoted)
+ *
+ * Usage: raw("aws_vpc.main.id") produces a RawHCL value that serializes without quotes.
+ * Also implements toString() so it can be used in template literals.
+ *
+ * Identified at runtime via a global Symbol key (Symbol.for).
+ * Global symbols are used because esbuild bundles inline this module, creating separate
+ * copies in the bundle and the CLI process. Symbol.for() ensures both copies share the
+ * same Symbol identity, so isRawHCL() works across the bundle boundary.
+ */
+declare const RAW_HCL_SYMBOL: unique symbol;
+export type RawHCL = {
+    [RAW_HCL_SYMBOL]: true;
+    value: string;
+    toString(): string;
+};
+/** Creates a RawHCL marker. The value string is emitted as-is (no quoting). */
+export declare function raw(value: string): RawHCL;
+/** Type guard for RawHCL values. Checks for the private Symbol key. */
+export declare function isRawHCL(v: unknown): v is RawHCL;
+/**
+ * BlockHCL — marker type to force block syntax for a nested object.
+ *
+ * By default, a plain object value is rendered as attribute syntax: key = { ... }
+ * Wrapping it with block() forces block syntax: key { ... } (no `=`)
+ *
+ * This is needed when the key name is not in BLOCK_WHITELIST but should still
+ * use block syntax (e.g. custom nested blocks in provider-specific resources).
+ *
+ * Identified at runtime via a global Symbol key (Symbol.for).
+ * See RAW_HCL_SYMBOL for why global symbols are necessary.
+ */
+declare const BLOCK_HCL_SYMBOL: unique symbol;
+export type BlockHCL = {
+    [BLOCK_HCL_SYMBOL]: true;
+    value: Record<string, any>;
+};
+/** Creates a BlockHCL marker wrapping a plain object to force block syntax. */
+export declare function block(value: Record<string, any>): BlockHCL;
+/** Type guard for BlockHCL values. Checks for the private Symbol key. */
+export declare function isBlockHCL(v: unknown): v is BlockHCL;
+/**
+ * AttributeHCL — marker type for attribute syntax with nested objects.
+ *
+ * Represents `key = { ... }` syntax (with `=`), as opposed to BlockHCL's `key { ... }`.
+ *
+ * Can be used explicitly to force attribute syntax even for BLOCK_WHITELIST keys:
+ *   { lifecycle: attribute({ prevent_destroy: true }) }
+ *   → lifecycle = { prevent_destroy = true }   (attribute syntax forced)
+ *
+ * When no marker is specified, plain objects not in the whitelist are auto-wrapped
+ * as AttributeHCL during the classification phase.
+ *
+ * Identified at runtime via a global Symbol key (Symbol.for).
+ * See RAW_HCL_SYMBOL for why global symbols are necessary.
+ */
+declare const ATTRIBUTE_HCL_SYMBOL: unique symbol;
+export type AttributeHCL = {
+    [ATTRIBUTE_HCL_SYMBOL]: true;
+    value: Record<string, any>;
+};
+/** Creates an AttributeHCL marker wrapping a plain object to force attribute syntax (key = { ... }). */
+export declare function attribute(value: Record<string, any>): AttributeHCL;
+/** Type guard for AttributeHCL values. Checks for the private Symbol key. */
+export declare function isAttributeHCL(v: unknown): v is AttributeHCL;
+/**
+ * Serializes a Record of attributes into indented HCL lines.
+ *
+ * @param attrs - Key-value pairs to serialize
+ * @param indent - Current indentation level in spaces (default: 2)
+ * @returns Multi-line string of HCL attributes (without enclosing braces)
+ *
+ * Processing order:
+ *   1. Entries are partitioned into simple attributes and block entries
+ *   2. Simple attributes are rendered first, with keys aligned (padded to max key length)
+ *   3. Block entries follow, separated from simple attrs by a blank line
+ *
+ * Entry classification (explicit markers take precedence over auto-classification):
+ *   - AttributeHCL (explicit)              → attribute syntax (key = { ... }), overrides whitelist
+ *   - BlockHCL (explicit)                  → block syntax (key { ... })
+ *   - Whitelisted key + plain object       → auto block() (key { ... })
+ *   - Plain object (not whitelisted)       → auto attribute() (key = { ... })
+ *   - Array of objects                     → repeated blocks (key { } key { })
+ *   - Everything else                      → simple attribute (key = value)
+ *
+ * Example output (indent=2):
+ *   cidr_block           = "10.0.0.0/16"
+ *   enable_dns_hostnames = true
+ *
+ *   lifecycle {
+ *     create_before_destroy = true
+ *   }
+ */
+export declare function serializeHCLAttributes(attrs: Record<string, any>, indent?: number): string;
+/**
+ * Adjusts indentation of a multi-line HCL string.
+ *
+ * 1. Strips leading and trailing blank lines
+ * 2. Computes the minimum indentation across non-empty lines
+ * 3. Re-indents all lines to the target indentation level
+ *
+ * @param text - Raw multi-line string (e.g. from JSX children)
+ * @param targetIndent - Desired indentation in number of spaces (default: 2)
+ * @returns Re-indented string
+ */
+export declare function adjustIndent(text: string, targetIndent?: number): string;
+export {};

package/dist/hcl-validator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * HCL validator for innerText content.
+ *
+ * Wraps the raw HCL body in a dummy resource block and parses it with hcl2-parser
+ * to detect syntax errors before emitting invalid Terraform.
+ */
+/**
+ * Validates an innerText HCL string by wrapping it in a dummy resource block
+ * and parsing with hcl2-parser.
+ *
+ * @param hclText - The raw HCL body text (already indented)
+ * @throws Error if the HCL is syntactically invalid
+ */
+export declare function validateInnerTextHCL(hclText: string): void;

package/dist/helpers/tf.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Terraform expression helpers — provides shorthand functions for referencing
+ * Terraform variables and locals inside JSX attributes.
+ *
+ * These helpers return RawHCL values, which the HCL serializer outputs without
+ * quotes. This allows JSX attributes to contain Terraform expressions like
+ * `var.environment` or `local.common_tags` directly.
+ *
+ * Usage in TSX:
+ *   <Resource type="aws_instance" name="web"
+ *     instance_type={tf.var("instance_type")}
+ *     tags={tf.local("common_tags")}
+ *   />
+ *
+ * Output:
+ *   resource "aws_instance" "web" {
+ *     instance_type = var.instance_type
+ *     tags          = local.common_tags
+ *   }
+ */
+import { type RawHCL } from "../hcl-serializer";
+export declare const tf: {
+    /** tf.var("name") → var.name */
+    var(name: string): RawHCL;
+    /** tf.local("name") → local.name */
+    local(name: string): RawHCL;
+};

package/dist/hooks/use-ref.d.ts

@@ -0,0 +1,79 @@
+/**
+ * useRef hook — creates a Proxy-based reference object for cross-resource references.
+ *
+ * In Terraform, resources often reference each other:
+ *   vpc_id = aws_vpc.main.id
+ *
+ * useRef() returns a Proxy that:
+ *   1. Stores metadata (__refMeta) set by Resource/DataSource/Provider/Module components
+ *   2. Returns RawHCL values on property access (e.g. ref.id → raw("aws_vpc.main.id"))
+ *   3. Supports nested access (ref.outputs.vpc_id → raw("data.terraform_remote_state.x.outputs.vpc_id"))
+ *   4. Provides special __dependsOnValue (type.name format for depends_on)
+ *   5. Provides special __providerValue (type.alias format for provider references)
+ *
+ * Stateful hook store:
+ *   useRef() uses a global hookStore to return the same proxy across multiple render passes.
+ *   resetHookState(clear?) resets the hook index (and optionally clears the store).
+ *   This enables 2-pass rendering: pass 1 collects ref metadata, pass 2 resolves references.
+ *
+ * The ref lifecycle (inside a component):
+ *   function App() {
+ *     const vpcRef = useRef();
+ *     return (
+ *       <>
+ *         <Resource ref={vpcRef} type="aws_vpc" name="main" />  // registers metadata
+ *         <Resource vpc_id={vpcRef.id} />  // lazy RawHCL, resolved at serialization
+ *       </>
+ *     );
+ *   }
+ */
+import type { RawHCL } from "../hcl-serializer";
+/**
+ * Metadata stored on a ref after a component registers it.
+ * Set by Resource, DataSource, Provider, or Module when they receive a `ref` prop.
+ */
+export type RefMeta = {
+    blockType: "resource" | "data" | "provider" | "module";
+    type: string;
+    name: string;
+    alias?: string;
+};
+/**
+ * The Proxy-based ref object returned by useRef().
+ * Property access returns RawHCL or nested RefProxy for chained access.
+ */
+export type RefProxy = {
+    __refMeta?: RefMeta;
+    __dependsOnValue: RawHCL;
+    __providerValue: RawHCL;
+    [key: string]: any;
+};
+/**
+ * Resets the hook state between render passes.
+ * @param clear If true, clears the store entirely (used before pass 1).
+ *              If false/omitted, only resets the index (used before pass 2).
+ */
+export declare function resetHookState(clear?: boolean): void;
+/**
+ * Returns the current hook store (for validation after rendering).
+ */
+export declare function getHookStore(): RefProxy[];
+/**
+ * Creates a ref Proxy object for tracking Terraform resource references.
+ *
+ * Stateful: returns the same proxy on repeated calls within a render cycle
+ * (identified by hookIndex). This enables 2-pass rendering where pass 1
+ * collects metadata and pass 2 resolves references using the same proxies.
+ *
+ * Usage (inside a component function):
+ *   function App() {
+ *     const vpcRef = useRef();
+ *     return (
+ *       <>
+ *         <Resource type="aws_vpc" name="main" ref={vpcRef} cidr_block="10.0.0.0/16" />
+ *         <Resource type="aws_subnet" name="sub" vpc_id={vpcRef.id} />
+ *       </>
+ *     );
+ *   }
+ */
+export declare function useRef(): RefProxy;

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Public API entry point for the react-hcl package.
+ *
+ * This module re-exports all user-facing components and utilities.
+ * Users import from "react-hcl" in their TSX files:
+ *
+ *   import { Resource, Fragment } from "react-hcl";
+ *
+ * As more components are added (Data, Variable, Output, Provider, etc.),
+ * they should be exported from here.
+ */
+export { DataSource } from "./components/data-source";
+export { Locals } from "./components/locals";
+export { Module } from "./components/module";
+export { Output } from "./components/output";
+export { Provider } from "./components/provider";
+export { Resource } from "./components/resource";
+export { Terraform } from "./components/terraform";
+export { Variable } from "./components/variable";
+export { block, raw } from "./hcl-serializer";
+export { tf } from "./helpers/tf";
+export { useRef } from "./hooks/use-ref";
+export { Fragment } from "./jsx-runtime";