ubitofu 0.1.0__py3-none-any.whl

ubitofu/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 James Braid
+# placeholder — package code lands via the implementation plan

ubitofu/cleaner.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 James Braid
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class VarRef:
+    expr: str
+
+
+# Value-pattern secret safety net (the WireGuard lesson): the provider can
+# return secret material in PLAINTEXT with no schema `sensitive` flag (live
+# WG server private keys did exactly that). Detect secret-shaped content in
+# already-cleaned attrs so it never reaches emitted HCL.
+_SECRET_NAME_RE = re.compile(r"private_key|passphrase|secret|token|password", re.IGNORECASE)
+_PUBLIC_NAME_RE = re.compile(r"public", re.IGNORECASE)
+# curve25519/WireGuard key shape: 44 chars of base64 ending in '='.
+_B64_KEY_RE = re.compile(r"^[A-Za-z0-9+/]{43}=$")
+
+
+def _is_secret_shaped(name: str, value: object) -> bool:
+    if not isinstance(value, str) or not value:
+        return False
+    if _PUBLIC_NAME_RE.search(name):
+        # WG PUBLIC keys share the b64 shape but are not secrets (and may be
+        # required attrs, e.g. unifi_wireguard_peer.public_key).
+        return False
+    return bool(_SECRET_NAME_RE.search(name) or _B64_KEY_RE.match(value))
+
+
+def strip_secret_shaped(attrs: dict, _prefix: str = "") -> list[str]:  # type: ignore[type-arg]
+    """Remove secret-shaped string values from cleaned attrs (mutating).
+
+    A hit is (a) a string value whose attr NAME looks secret-bearing
+    (private_key/passphrase/secret/token/password, case-insensitive), or
+    (b) any string value shaped like a curve25519/WireGuard key. VarRef
+    values are already var-sourced and never match; attr names containing
+    "public" are exempt. Containers emptied by stripping are dropped too.
+
+    Returns the dotted paths of removed values, for reporting and for
+    adding their top-level attrs to lifecycle ignore_changes.
+    """
+    hits: list[str] = []
+    for name in list(attrs):
+        value = attrs[name]
+        path = f"{_prefix}{name}"
+        if isinstance(value, VarRef):
+            continue
+        if isinstance(value, dict):
+            hits.extend(strip_secret_shaped(value, f"{path}."))
+            if not value:
+                del attrs[name]
+        elif isinstance(value, list):
+            if any(isinstance(e, str) and _is_secret_shaped(name, e) for e in value):
+                hits.append(path)
+                del attrs[name]
+                continue
+            for i, entry in enumerate(value):
+                if isinstance(entry, dict):
+                    hits.extend(strip_secret_shaped(entry, f"{path}[{i}]."))
+            remaining = [e for e in value if not (isinstance(e, dict) and not e)]
+            if remaining:
+                attrs[name] = remaining
+            else:
+                del attrs[name]
+        elif _is_secret_shaped(name, value):
+            hits.append(path)
+            del attrs[name]
+    return hits
+
+
+def is_settable(attr_schema: dict) -> bool:  # type: ignore[type-arg]
+    required = bool(attr_schema.get("required"))
+    optional = bool(attr_schema.get("optional"))
+    return required or optional
+
+
+def is_empty(value: object) -> bool:
+    return value is None or value == "" or value == [] or value == {}
+
+
+def normalize_emitted(resource_type: str, attrs: dict) -> dict:  # type: ignore[type-arg]
+    """Fix up specific attribute values the provider rejects verbatim.
+
+    Small, explicit per-resource/attr normalizations applied to already-cleaned
+    attrs before rendering — NOT a blanket string replace.
+
+    - unifi_port_forward.wan.interface: the controller reports "all" for a
+      forward that applies to every WAN, but the provider validator accepts
+      only wan/wan2/both. With 2 WANs, "both" is the equivalent.
+    """
+    if resource_type == "unifi_port_forward":
+        wan = attrs.get("wan")
+        if isinstance(wan, dict) and wan.get("interface") == "all":
+            wan["interface"] = "both"
+    return attrs
+
+
+def clean_resource(
+    values: dict,  # type: ignore[type-arg]
+    resource_schema: dict,  # type: ignore[type-arg]
+    sensitive: dict[str, VarRef] | None = None,
+) -> dict:  # type: ignore[type-arg]
+    sensitive = sensitive or {}
+    block = resource_schema["block"]
+    attrs = block.get("attributes", {})
+    out: dict[str, object] = {}
+
+    for name, schema in attrs.items():
+        if name in sensitive:
+            out[name] = sensitive[name]
+            continue
+        if not is_settable(schema):
+            continue
+        value = values.get(name)
+        if is_empty(value):
+            continue
+        # Single/collection nested-object ATTRIBUTES live under `nested_type`
+        # (not block_types). generate-config-out emits every child verbatim,
+        # including null/empty and computed-only fields (e.g. firewall_policy
+        # source/destination) — recurse so the settable/drop-empty rules apply
+        # inside them too, else read-only children leak and break the plan.
+        nested = schema.get("nested_type")
+        if nested:
+            assert value is not None  # is_empty guards None; narrows for mypy
+            sub_schema = {"block": {"attributes": nested["attributes"]}}
+            if nested.get("nesting_mode") == "single":
+                single = clean_resource(value, sub_schema)
+                if single:
+                    out[name] = single
+            else:  # list/set nesting -> a list of object entries
+                nested_entries: list[dict[str, object]] = (
+                    value if isinstance(value, list) else [value])
+                nested_cleaned = [c for e in nested_entries
+                                  if (c := clean_resource(e, sub_schema))]
+                if nested_cleaned:
+                    out[name] = nested_cleaned
+            continue
+        out[name] = value
+
+    # Repeated/nested config blocks live under block_types (not attributes).
+    # Previously these were silently dropped, making 0-change plans unreachable.
+    for name, bt in block.get("block_types", {}).items():
+        raw = values.get(name)
+        if is_empty(raw):
+            continue
+        assert raw is not None  # is_empty guards None; assert narrows for mypy
+        entries: list[dict[str, object]] = raw if isinstance(raw, list) else [raw]
+        cleaned = [clean_resource(e, {"block": bt["block"]}) for e in entries]
+        cleaned = [c for c in cleaned if c]  # drop wholly-empty entries
+        if cleaned:
+            out[name] = cleaned
+
+    return out

ubitofu/cli.py

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 James Braid
+import argparse
+import os
+import sys
+from typing import IO
+
+from .config import Config, load_config, resolve_api_key
+from .controller import Controller
+from .enumerator import enumerate_controller
+from .import_emitter import emit_import_blocks
+from .reporter import format_gaps
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="ubitofu",
+        description="Plan-only UniFi -> OpenTofu importer.",
+    )
+    sub = p.add_subparsers(dest="command", required=True)
+    for name in ("enumerate", "generate", "verify"):
+        sp = sub.add_parser(name)
+        sp.add_argument("--config", required=True)
+        sp.add_argument("--controller-url")
+        sp.add_argument("--site")
+        sp.add_argument("--api-key-source", choices=["op", "env"])
+        if name != "verify":
+            sp.add_argument("--mode", choices=["bulk", "incremental"], default="bulk")
+    return p
+
+
+def _controller(cfg: Config) -> Controller:
+    key = resolve_api_key(cfg, environ=os.environ)
+    return Controller(base_url=cfg.controller_url, site=cfg.site, api_key=key)
+
+
+def cmd_enumerate(cfg: Config, mode: str, out: IO[str]) -> int:
+    res = enumerate_controller(_controller(cfg))
+    print(emit_import_blocks(res.targets), file=out)
+    print(format_gaps(res.gaps), file=out)
+    return 0
+
+
+def cmd_generate(cfg: Config, mode: str, out: IO[str]) -> int:
+    # pipeline.run_generate wires Tasks 1-9 end-to-end (implemented in Task 12).
+    # Lazy import so cli is importable before Task 12 exists.
+    from .pipeline import run_generate  # noqa: PLC0415
+
+    return run_generate(cfg, mode, out)
+
+
+def cmd_verify(cfg: Config, out: IO[str]) -> int:
+    from .pipeline import run_verify  # noqa: PLC0415
+
+    return run_verify(cfg, out)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    cfg = load_config(args.config)
+    # CLI flags override config-file values.
+    if args.controller_url:
+        cfg.controller_url = args.controller_url
+    if args.site:
+        cfg.site = args.site
+    if args.api_key_source:
+        cfg.api_key_source = args.api_key_source
+    if args.command == "enumerate":
+        return cmd_enumerate(cfg, args.mode, sys.stdout)
+    if args.command == "generate":
+        return cmd_generate(cfg, args.mode, sys.stdout)
+    return cmd_verify(cfg, sys.stdout)

ubitofu/config.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 James Braid
+import subprocess
+import tomllib
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+
+
+@dataclass
+class Config:
+    controller_url: str
+    site: str
+    api_key_source: str
+    api_key_ref: str
+    op_vault: str  # required: the operator's secret-manager vault, from config
+    workdir: str = "."
+
+
+def load_config(path: str) -> Config:
+    with open(path, "rb") as fh:
+        data = tomllib.load(fh)
+    return Config(**data)
+
+
+def _op_read(ref: str) -> str:
+    result = subprocess.run(["op", "read", ref], capture_output=True, text=True, check=True)
+    return result.stdout.strip()
+
+
+def resolve_api_key(
+    cfg: Config,
+    environ: Mapping[str, str],
+    op_reader: Callable[[str], str] = _op_read,
+) -> str:
+    if cfg.api_key_source == "env":
+        return environ[cfg.api_key_ref]
+    if cfg.api_key_source == "op":
+        return op_reader(cfg.api_key_ref)
+    raise ValueError(f"unknown api_key_source: {cfg.api_key_source!r}")

ubitofu/controller.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 James Braid
+from dataclasses import dataclass, field
+
+import httpx
+
+
+@dataclass
+class Controller:
+    base_url: str
+    site: str
+    api_key: str
+    verify_tls: bool = False
+    _http: httpx.Client = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._http = httpx.Client(base_url=self.base_url, verify=self.verify_tls)
+
+    def _resolve(self, endpoint: str) -> str:
+        endpoint = endpoint.replace("{site}", self.site)
+        if endpoint.startswith("v2/") or endpoint.startswith("api/self"):
+            return f"/proxy/network/{endpoint}"
+        return f"/proxy/network/api/s/{self.site}/{endpoint}"
+
+    def get(self, path: str) -> object:
+        resp = self._http.get(
+            self._resolve(path),
+            headers={"X-API-KEY": self.api_key, "Accept": "application/json"},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def collection(self, endpoint: str) -> list[dict]:  # type: ignore[type-arg]
+        body = self.get(endpoint)
+        if isinstance(body, dict) and "data" in body:
+            return list(body["data"])
+        if isinstance(body, list):
+            return list(body)
+        return [body] if isinstance(body, dict) else []

ubitofu/enumerator.py

@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 James Braid
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+from .controller import Controller
+from .manifest import MANIFEST, UNMAPPED_ENDPOINTS, ResourceSpec
+
+
+@dataclass(frozen=True)
+class ImportTarget:
+    resource_type: str
+    name_hint: str
+    import_id: str
+
+
+@dataclass
+class EnumerationResult:
+    targets: list[ImportTarget] = field(default_factory=list)
+    gaps: list[str] = field(default_factory=list)
+
+
+_ALIAS_SKIP = {"unifi_account"}  # rest/account alias — unifi_radius_user wins
+
+# Per-object skips: objects the provider cannot represent. Each maps to a
+# coverage-gap label (rendered with the skipped count) instead of being emitted
+# as invalid config. Keyed by the reason so counts aggregate across a run.
+_SKIP_LABELS: dict[str, str] = {
+    "app_policy": "app-based firewall policy(ies) — unsupported matching_target=APP",
+    "radius_default": "default radius profile(s) — required auth_server.secret is "
+                      "not sourceable; skipped",
+    "usergroup_default": "default client-QoS usergroup(s) — unmanageable default "
+                         "(-1 sentinel rates); skipped",
+}
+
+
+def _is_app_policy(obj: dict[str, object]) -> bool:
+    """A firewall policy is app-based when source/destination match on APP.
+
+    The provider's matching_target validator accepts ANY/NETWORK/CLIENT/IP/
+    DEVICE/MAC/WEB but not APP (DPI / app_ids), so such policies cannot be
+    represented and must be skipped.
+    """
+    for side in ("source", "destination"):
+        sub = obj.get(side)
+        if isinstance(sub, dict) and str(sub.get("matching_target")).upper() == "APP":
+            return True
+    return False
+
+
+def _skip_reason(spec: ResourceSpec, obj: dict[str, object]) -> str | None:
+    rt = spec.resource_type
+    if rt == "unifi_firewall_policy" and _is_app_policy(obj):
+        return "app_policy"
+    # attr_no_delete marks a built-in/default object (like firewall `predefined`).
+    # The lone default radius profile / QoS usergroup carry unsourceable secrets
+    # or -1 sentinel rates the provider rejects — skip rather than emit invalid.
+    if rt == "unifi_radius_profile" and obj.get("attr_no_delete"):
+        return "radius_default"
+    if rt == "unifi_client_qos_rate" and obj.get("attr_no_delete"):
+        return "usergroup_default"
+    return None
+
+
+def matches(obj: dict[str, object], spec: ResourceSpec) -> bool:
+    if spec.discriminator:
+        for key, allowed in spec.discriminator.items():
+            if str(obj.get(key)) not in allowed.split("|"):
+                return False
+    if spec.include:
+        for key, want in spec.include.items():
+            if want == "__present__":
+                if not obj.get(key):
+                    return False
+            elif obj.get(key) != want:
+                return False
+    return True
+
+
+def extract_id(obj: dict[str, object], spec: ResourceSpec, site: str) -> str:
+    if spec.id_rule == "site":
+        return site
+    if spec.id_rule == "mac":
+        return str(obj["mac"])
+    if spec.id_rule == "mac_or_id":
+        return str(obj.get("mac") or obj["_id"])
+    if spec.id_rule == "site:_id":
+        return f"{site}:{obj['_id']}"
+    return str(obj["_id"])
+
+
+def _name_hint(obj: dict[str, object], spec: ResourceSpec, site: str) -> str:
+    if spec.id_rule == "site":
+        return spec.resource_type.removeprefix("unifi_")
+    # `key`/`host_name` cover records that leave `name` null: unifi_dns_record
+    # (static-dns keys the hostname under `key`) and unifi_dynamic_dns
+    # (host_name) — so `to =` labels read as the hostname, not n_<hex>.
+    return str(obj.get("name") or obj.get("hostname") or obj.get("host_name")
+               or obj.get("key") or obj.get("_id") or site)
+
+
+def enumerate_controller(
+    ctl: Controller, manifest: Iterable[ResourceSpec] = MANIFEST
+) -> EnumerationResult:
+    result = EnumerationResult()
+    specs = list(manifest)
+    skipped: dict[str, int] = {}
+    for spec in specs:
+        if spec.resource_type in _ALIAS_SKIP:
+            continue
+        if spec.id_rule == "site":  # singleton — import by site, not enumerated
+            if spec.skip_if_empty and not ctl.collection(spec.endpoint):
+                result.gaps.append(
+                    f"{spec.resource_type} skipped — not configured "
+                    "(no remote object to import)")
+                continue
+            result.targets.append(
+                ImportTarget(spec.resource_type, _name_hint({}, spec, ctl.site), ctl.site))
+            continue
+        if spec.id_rule == "wg_two_level":
+            result.targets.extend(_enumerate_wireguard(ctl, spec))
+            continue
+        for obj in ctl.collection(spec.endpoint):
+            if not matches(obj, spec):
+                continue
+            reason = _skip_reason(spec, obj)
+            if reason is not None:
+                skipped[reason] = skipped.get(reason, 0) + 1
+                continue
+            result.targets.append(ImportTarget(
+                spec.resource_type,
+                _name_hint(obj, spec, ctl.site),
+                extract_id(obj, spec, ctl.site)))
+    for reason, count in skipped.items():
+        result.gaps.append(f"{count} {_SKIP_LABELS[reason]}")
+    result.gaps.extend(_guest_network_gaps(ctl, specs))
+    result.gaps.extend(_coverage_gaps(ctl))
+    return result
+
+
+def _guest_network_gaps(
+    ctl: Controller, specs: list[ResourceSpec]
+) -> list[str]:
+    """Report guest networks (purpose="guest") — no provider resource exists.
+
+    They are already excluded by the unifi_network discriminator; this counts
+    and reports them so the coverage gap is explicit rather than silent.
+    """
+    if not any(s.endpoint == "rest/networkconf" for s in specs):
+        return []
+    n = sum(1 for net in ctl.collection("rest/networkconf")
+            if net.get("purpose") == "guest")
+    if not n:
+        return []
+    return [f"{n} guest network(s) — no provider resource; not imported"]
+
+
+def _enumerate_wireguard(ctl: Controller, spec: ResourceSpec) -> list[ImportTarget]:
+    """First list WG-server networks, then GET each server's users.
+
+    Import id is "network_id:peer_id" (two-level enumeration).
+    """
+    targets: list[ImportTarget] = []
+    nets = [n for n in ctl.collection("rest/networkconf")
+            if n.get("vpn_type") == "wireguard-server"]
+    for net in nets:
+        nid = str(net["_id"])
+        for peer in ctl.collection(f"v2/api/site/{{site}}/wireguard/{nid}/users"):
+            targets.append(ImportTarget(
+                "unifi_wireguard_peer",
+                str(peer.get("name") or peer["_id"]),
+                f"{nid}:{peer['_id']}"))
+    return targets
+
+
+def _coverage_gaps(ctl: Controller) -> list[str]:
+    """Flag any UNMAPPED_ENDPOINTS collection that is non-empty."""
+    gaps: list[str] = []
+    for endpoint, label in UNMAPPED_ENDPOINTS.items():
+        n = len(ctl.collection(endpoint))
+        if n:
+            gaps.append(
+                f"{n} objects found at {endpoint} ({label})"
+                " with no provider resource — not imported")
+    return gaps

ubitofu/hcl_writer.py

@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 James Braid
+import json
+import subprocess
+
+import hcl2  # type: ignore[import-untyped]
+from hcl2 import Builder
+
+from .cleaner import VarRef
+
+
+def _q(s: str) -> str:
+    """Pre-quote a string literal for python-hcl2.
+
+    python-hcl2 treats bare Python strings as raw HCL expressions.  String
+    LITERALS must therefore arrive already surrounded by HCL double-quotes, with
+    internal special characters escaped:
+      - backslash first (avoid double-escaping later additions)
+      - double-quote
+      - HCL interpolation opener ${…} → $${…}
+      - HCL template opener %{…} → %%{…}
+    """
+    s = (s.replace("\\", "\\\\")
+           .replace('"', '\\"')
+           .replace("\n", "\\n")
+           .replace("\r", "\\r")
+           .replace("\t", "\\t")
+           .replace("${", "$${")
+           .replace("%{", "%%{"))
+    return f'"{s}"'
+
+
+def hcl_literal(value: object) -> object:
+    """Prepare a Python value for hcl2.dumps.
+
+    python-hcl2 treats bare strings as raw HCL expressions, so string
+    LITERALS must be pre-quoted, while VarRef expressions pass through raw.
+    Dicts become nested object attrs; lists become HCL lists.
+    """
+    if isinstance(value, VarRef):
+        return value.expr
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return _q(value)
+    if isinstance(value, dict):
+        return {k: hcl_literal(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [hcl_literal(v) for v in value]
+    return value  # int/float/None — hcl2.dumps handles directly
+
+
+def tofu_fmt(text: str, binary: str = "tofu") -> str:
+    """Run `tofu fmt -` on *text* and return the formatted result."""
+    proc = subprocess.run(
+        [binary, "fmt", "-"],
+        input=text,
+        capture_output=True,
+        text=True,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(proc.stderr.strip())
+    return proc.stdout
+
+
+def _render_lifecycle_raw(lifecycle: dict[str, object]) -> str:
+    """Render a lifecycle block as a raw indented text block.
+
+    python-hcl2 expands list values to multi-line, but the test requires
+    ``ignore_changes = [attr_ref]`` on a single line (attr refs, not strings).
+    We therefore bypass Builder/dumps for this block and write it directly;
+    tofu fmt keeps single-line lists intact.
+    """
+    lines = ["  lifecycle {"]
+    for k, v in lifecycle.items():
+        if isinstance(v, list):
+            refs = ", ".join(str(r) for r in v)
+            lines.append(f"    {k} = [{refs}]")
+    lines.append("  }")
+    return "\n".join(lines)
+
+
+def render_resource(
+    resource_type: str,
+    slug: str,
+    attrs: dict[str, object],
+    lifecycle: dict[str, object] | None = None,
+    block_attrs: tuple[str, ...] = (),
+) -> str:
+    """Render a single Terraform/OpenTofu resource block to formatted HCL.
+
+    Constructs handled:
+    - Scalar / string attributes (string literals pre-quoted via ``_q``).
+    - Nested object attribute: dict value → ``name = { … }`` HCL object.
+    - List-of-object attribute: list-of-dict → ``name = [ { … }, … ]``.
+    - Repeated nested blocks (``block_attrs``): each list entry → a separate
+      ``name { … }`` block rather than an ``= […]`` assignment.
+    - VarRef: rendered as a bare ``var.<name>`` traversal expression.
+    - lifecycle: rendered as raw text so ``ignore_changes`` refs stay unquoted.
+    """
+    builder = Builder()
+
+    # Scalar attrs and plain list/object attrs (everything except block_attrs).
+    scalar_attrs = {
+        k: hcl_literal(v)
+        for k, v in attrs.items()
+        if k not in block_attrs
+    }
+    block = builder.block("resource", [_q(resource_type), _q(slug)], **scalar_attrs)
+
+    # Repeated nested blocks (nesting_mode=set/list in provider schema).
+    for name in block_attrs:
+        entries = attrs.get(name)
+        if isinstance(entries, list):
+            for entry in entries:
+                if isinstance(entry, dict):
+                    block.block(name, **{k: hcl_literal(v) for k, v in entry.items()})
+
+    # Convert to HCL text and apply tofu fmt.
+    hcl_text = tofu_fmt(hcl2.dumps(builder.build()))
+
+    if lifecycle:
+        # Splice the lifecycle block in before the closing `}` of the resource,
+        # then re-format.  We build it as raw text to preserve bare identifier
+        # refs inside ignore_changes (python-hcl2 would expand the list and
+        # wrap refs in quotes, which is wrong).
+        body = hcl_text.rstrip()          # strip trailing newline(s)
+        if not body.endswith("}"):
+            raise ValueError(f"unexpected hcl2.dumps tail: {body[-20:]!r}")
+        body = body[:-1].rstrip()         # strip the closing "}"
+        lifecycle_txt = _render_lifecycle_raw(lifecycle)
+        combined = body + "\n\n" + lifecycle_txt + "\n}\n"
+        hcl_text = tofu_fmt(combined)
+
+    return hcl_text
+
+
+def render_variables(var_names: list[str]) -> str:
+    """Render sensitive string variable declarations, sorted by name.
+
+    Only declarations — values come from the operator's secret manager
+    (TF_VAR_* / -var-file); no secret value is ever written to a file.
+    """
+    blocks = [
+        f'variable "{name}" {{\n  type      = string\n  sensitive = true\n}}\n'
+        for name in sorted(set(var_names))
+    ]
+    return "\n".join(blocks)
+
+
+def render_json_fallback(
+    resource_type: str,
+    slug: str,
+    attrs: dict[str, object],
+) -> str:
+    """Emit a ``.tf.json`` resource block as a fallback.
+
+    Used when python-hcl2 cannot render a construct correctly (e.g. for a
+    resource type whose schema requires a construct that Builder/dumps
+    mis-renders despite best efforts).  VarRef values become ``${var.name}``
+    interpolation expressions, which are valid in .tf.json.
+    """
+    def _plain(v: object) -> object:
+        if isinstance(v, VarRef):
+            return f"${{{v.expr}}}"
+        if isinstance(v, dict):
+            return {k: _plain(x) for k, x in v.items()}
+        if isinstance(v, list):
+            return [_plain(x) for x in v]
+        return v
+
+    payload = {
+        "resource": {
+            resource_type: {
+                slug: {k: _plain(v) for k, v in attrs.items()}
+            }
+        }
+    }
+    return json.dumps(payload, indent=2) + "\n"