From 8eef862a80eef6f8b7aefb6038ec04b60ac17b55 Mon Sep 17 00:00:00 2001
From: Felix Kotschenreuther <felix.kotschenreuther@gmail.com>
Date: Wed, 16 Sep 2026 11:53:59 +0200
Subject: [PATCH 1/2] feat(export): render managed state as OpenTofu HCL and
 import blocks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`ct export tf` turns ct-state.<env>.json into .tf files plus import
blocks, so a migration to the OpenTofu provider needs no re-adoption:
curated keys and comments carry across and ids come from state.

Rendering is pure (no fs, no network), matching src/coverage/report.ts —
the golden test has to run against fixtures without touching disk.

Resource types are churchtools_-prefixed: Terraform resolves a
resource's provider from the segment before the first underscore, so a
bare `campus` type would resolve to a provider named `campus`.

Ids are stringified explicitly with no truthiness path anywhere. The
Mainz campus is id 0, and dropping it would silently fail to import
exactly one resource.
---
 src/application/contracts.ts            |  2 +-
 src/application/operations/export-tf.ts | 67 ++++++++++++++++++++++
 src/commands/export-tf.ts               | 34 +++++++++++
 src/export/hcl.ts                       | 75 +++++++++++++++++++++++++
 src/export/imports.ts                   | 23 ++++++++
 src/export/layout.ts                    | 16 ++++++
 src/index.ts                            |  2 +
 tests/export/hcl.test.ts                | 70 +++++++++++++++++++++++
 8 files changed, 288 insertions(+), 1 deletion(-)
 create mode 100644 src/application/operations/export-tf.ts
 create mode 100644 src/commands/export-tf.ts
 create mode 100644 src/export/hcl.ts
 create mode 100644 src/export/imports.ts
 create mode 100644 src/export/layout.ts
 create mode 100644 tests/export/hcl.test.ts

diff --git a/src/application/contracts.ts b/src/application/contracts.ts
index 38904ca..508c5a0 100644
--- a/src/application/contracts.ts
+++ b/src/application/contracts.ts
@@ -3,7 +3,7 @@ export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
 
 export type OperationName =
-  "plan" | "apply" | "coverage" | "adopt" | "state" | "refresh" | "destroy" | "auth";
+  "plan" | "apply" | "coverage" | "adopt" | "state" | "refresh" | "destroy" | "auth" | "export-tf";
 
 /** Common project selection accepted by CLI and, later, HTTP adapters. */
 export interface ProjectRequest {
diff --git a/src/application/operations/export-tf.ts b/src/application/operations/export-tf.ts
new file mode 100644
index 0000000..47d0792
--- /dev/null
+++ b/src/application/operations/export-tf.ts
@@ -0,0 +1,67 @@
+/** Orchestration for `ct export tf`: state in, .tf files out. */
+import { mkdir, writeFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { renderResource } from "../../export/hcl.js";
+import { renderImports, type ImportTarget } from "../../export/imports.js";
+import { EXPORTABLE_TYPES, fileForType } from "../../export/layout.js";
+import { loadState } from "../../state/state.js";
+import type { OperationResult, ProjectRequest } from "../contracts.js";
+import { resolveProject } from "../project.js";
+
+export interface ExportTfRequest extends ProjectRequest {
+  only?: string[];
+  outDir: string;
+}
+
+export interface ExportTfValue {
+  files: string[];
+  imported: number;
+  /** Keys that could not be used verbatim as an HCL identifier. */
+  relabelled: { key: string; label: string }[];
+}
+
+export type ExportTfResult = OperationResult<ExportTfValue>;
+
+export async function runExportTf(request: ExportTfRequest): Promise<ExportTfResult> {
+  // resolveProject gives the env profile's state path AND the host the state
+  // must belong to; loadState asserts that pairing, so an export can never
+  // silently mix instances. No network and no auth: this reads state only.
+  const project = await resolveProject(request);
+  const state = await loadState(project.statePath, project.host);
+  const types = request.only?.length ? request.only : EXPORTABLE_TYPES;
+
+  const byFile = new Map<string, string[]>();
+  const imports: ImportTarget[] = [];
+  const relabelled: { key: string; label: string }[] = [];
+
+  for (const resource of Object.values(state.resources)) {
+    if (!types.includes(resource.type)) continue;
+    const block = renderResource(resource.type, resource.key, resource.fields);
+    const file = fileForType(resource.type);
+    byFile.set(file, [...(byFile.get(file) ?? []), block]);
+    imports.push({ type: resource.type, key: resource.key, id: resource.id });
+
+    // The label the renderer actually produced, read back out of the block so
+    // the report cannot drift from what was written.
+    const label = block.split('"')[3];
+    if (label !== undefined && label !== resource.key) relabelled.push({ key: resource.key, label });
+  }
+
+  const outDir = isAbsolute(request.outDir) ? request.outDir : join(project.cwd, request.outDir);
+  await mkdir(outDir, { recursive: true });
+
+  const written: string[] = [];
+  for (const [file, blocks] of [...byFile].sort(([a], [b]) => a.localeCompare(b))) {
+    await writeFile(join(outDir, file), blocks.sort().join("\n"), "utf8");
+    written.push(file);
+  }
+  await writeFile(join(outDir, "imports.tf"), renderImports(imports), "utf8");
+  written.push("imports.tf");
+
+  return {
+    operation: "export-tf",
+    project,
+    value: { files: written, imported: imports.length, relabelled },
+    warnings: [],
+  };
+}
diff --git a/src/commands/export-tf.ts b/src/commands/export-tf.ts
new file mode 100644
index 0000000..a31d982
--- /dev/null
+++ b/src/commands/export-tf.ts
@@ -0,0 +1,34 @@
+import { Command } from "commander";
+import { runExportTf } from "../application/operations/export-tf.js";
+import { info } from "../ui.js";
+
+interface ExportTfOptions {
+  state?: string;
+  env?: string;
+  only?: string[];
+  out: string;
+}
+
+export function exportCommand(): Command {
+  const tf = new Command("tf")
+    .description("Render the managed state as OpenTofu HCL plus import blocks")
+    .option("-s, --state <path>", "state file (or set CT_STATE)")
+    .option("-e, --env <name>", "environment profile from ct.envs.json (host + state + token)")
+    .option("--only <types...>", "restrict to these resource types (e.g. campus group-type)")
+    .option("-o, --out <dir>", "output directory", "tofu")
+    .action(async (opts: ExportTfOptions) => {
+      const { value } = await runExportTf({
+        statePath: opts.state,
+        environment: opts.env,
+        only: opts.only,
+        outDir: opts.out,
+      });
+      for (const file of value.files) info(`wrote ${opts.out}/${file}`);
+      for (const r of value.relabelled) {
+        info(`relabelled "${r.key}" -> "${r.label}" (HCL references must be identifiers)`);
+      }
+      info(`${value.imported} resources exported`);
+    });
+
+  return new Command("export").description("Export managed state to other formats").addCommand(tf);
+}
diff --git a/src/export/hcl.ts b/src/export/hcl.ts
new file mode 100644
index 0000000..009292d
--- /dev/null
+++ b/src/export/hcl.ts
@@ -0,0 +1,75 @@
+/**
+ * HCL rendering — PURE. No filesystem, no network, no state loading.
+ *
+ * Kept pure for the same reason `src/coverage/report.ts` is: the golden export
+ * test has to run without touching disk, and a renderer that reads files
+ * cannot be property-tested against committed fixtures.
+ */
+
+/**
+ * ct-cli resource type -> Terraform resource type.
+ *
+ * The `churchtools_` prefix is not decoration: Terraform resolves a resource's
+ * provider from the segment before the first underscore, so a bare `campus`
+ * type would send it looking for a provider named `campus`. (HCL also has no
+ * top-level custom blocks — every resource is `resource "<type>" "<label>"`.)
+ */
+const HCL_TYPE: Record<string, string> = {
+  campus: "churchtools_campus",
+  "group-type": "churchtools_group_type",
+  department: "churchtools_department",
+  "person-status": "churchtools_person_status",
+  "comment-viewer": "churchtools_comment_viewer",
+};
+
+export function hclType(ctType: string): string {
+  const mapped = HCL_TYPE[ctType];
+  if (!mapped) throw new Error(`export: no Terraform resource type mapped for "${ctType}"`);
+  return mapped;
+}
+
+/**
+ * CT field name -> HCL attribute name. The provider exposes snake_case
+ * attributes (Terraform convention); ct-cli's state carries CT's camelCase.
+ */
+const HCL_ATTR: Record<string, string> = {
+  nameTranslated: "name_translated",
+  isMember: "is_member",
+  isSearchable: "is_searchable",
+  sortKey: "sort_key",
+  securityLevelId: "security_level_id",
+};
+
+export function hclAttr(field: string): string {
+  return HCL_ATTR[field] ?? field;
+}
+
+/**
+ * Make a ct-cli key referenceable in HCL.
+ *
+ * ct keys are already slugs, but a REFERENCE (`churchtools_group.3_groupactive`)
+ * must be a valid identifier, and `!3 GroupActive` derives a key starting with a
+ * digit. Such keys get a `g_` prefix; the mapping is reported by the export
+ * command so nothing renames silently.
+ */
+export function hclLabel(key: string): string {
+  const safe = key.replace(/[^A-Za-z0-9_-]/g, "_");
+  return /^[0-9-]/.test(safe) ? `g_${safe}` : safe;
+}
+
+function renderValue(value: unknown): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return JSON.stringify(value);
+}
+
+/** Render one resource block. Null/undefined fields are omitted, never emitted as `null`. */
+export function renderResource(ctType: string, key: string, fields: Record<string, unknown>): string {
+  const type = hclType(ctType);
+  const entries = Object.entries(fields)
+    .filter(([, v]) => v !== null && v !== undefined)
+    .map(([k, v]) => [hclAttr(k), v] as const);
+  const width = Math.max(0, ...entries.map(([k]) => k.length));
+  const lines = entries.map(([k, v]) => `  ${k.padEnd(width)} = ${renderValue(v)}`);
+  return [`resource "${type}" "${hclLabel(key)}" {`, ...lines, "}", ""].join("\n");
+}
diff --git a/src/export/imports.ts b/src/export/imports.ts
new file mode 100644
index 0000000..b9deea3
--- /dev/null
+++ b/src/export/imports.ts
@@ -0,0 +1,23 @@
+/** Import-block rendering — PURE. */
+import { hclLabel, hclType } from "./hcl.js";
+
+export interface ImportTarget {
+  type: string;
+  key: string;
+  id: number;
+}
+
+/**
+ * `id` is stringified explicitly rather than passed through any truthiness
+ * path: the Mainz campus is id 0, and dropping it would silently fail to
+ * import exactly one resource.
+ */
+export function renderImports(targets: readonly ImportTarget[]): string {
+  return targets
+    .map((t) =>
+      ["import {", `  to = ${hclType(t.type)}.${hclLabel(t.key)}`, `  id = "${String(t.id)}"`, "}", ""].join(
+        "\n",
+      ),
+    )
+    .join("\n");
+}
diff --git a/src/export/layout.ts b/src/export/layout.ts
new file mode 100644
index 0000000..91a2f1f
--- /dev/null
+++ b/src/export/layout.ts
@@ -0,0 +1,16 @@
+/** Which generated file each resource type lands in — PURE. */
+const FILE_BY_TYPE: Record<string, string> = {
+  campus: "campuses.tf",
+  "group-type": "group-types.tf",
+  department: "departments.tf",
+  "person-status": "person-statuses.tf",
+  "comment-viewer": "comment-viewers.tf",
+};
+
+export function fileForType(ctType: string): string {
+  const file = FILE_BY_TYPE[ctType];
+  if (!file) throw new Error(`export: no output file mapped for resource type "${ctType}"`);
+  return file;
+}
+
+export const EXPORTABLE_TYPES = Object.keys(FILE_BY_TYPE);
diff --git a/src/index.ts b/src/index.ts
index 3fa5b90..4c911d7 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -4,6 +4,7 @@ import { authCommand } from "./commands/auth.js";
 import { getCommand } from "./commands/get.js";
 import { adoptCommand } from "./commands/adopt.js";
 import { stateCommand } from "./commands/state.js";
+import { exportCommand } from "./commands/export-tf.js";
 import { coverageCommand } from "./commands/coverage.js";
 import { permissionsCommand } from "./commands/permissions.js";
 import { reportCommand } from "./commands/report.js";
@@ -34,6 +35,7 @@ export function buildProgram(): Command {
   program.addCommand(getCommand());
   program.addCommand(adoptCommand());
   program.addCommand(stateCommand());
+  program.addCommand(exportCommand());
   program.addCommand(coverageCommand());
   program.addCommand(permissionsCommand());
   program.addCommand(reportCommand());
diff --git a/tests/export/hcl.test.ts b/tests/export/hcl.test.ts
new file mode 100644
index 0000000..feb7ce3
--- /dev/null
+++ b/tests/export/hcl.test.ts
@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import { hclLabel, renderResource } from "../../src/export/hcl.js";
+import { renderImports } from "../../src/export/imports.js";
+
+describe("hclLabel", () => {
+  it("passes through identifier-safe keys", () => {
+    expect(hclLabel("team_kidsdienst")).toBe("team_kidsdienst");
+  });
+
+  it("prefixes keys starting with a digit", () => {
+    expect(hclLabel("3_groupactive")).toBe("g_3_groupactive");
+  });
+
+  it("replaces characters HCL cannot reference", () => {
+    expect(hclLabel("mainz.kids")).toBe("mainz_kids");
+  });
+});
+
+describe("renderResource", () => {
+  it("renders a campus block with quoted strings", () => {
+    expect(renderResource("campus", "mainz", { name: "Mainz", shorty: "MZ" })).toBe(
+      ['resource "churchtools_campus" "mainz" {', '  name   = "Mainz"', '  shorty = "MZ"', "}", ""].join(
+        "\n",
+      ),
+    );
+  });
+
+  it("omits null and undefined fields rather than emitting null", () => {
+    expect(renderResource("campus", "x", { name: "X", shorty: null })).toBe(
+      ['resource "churchtools_campus" "x" {', '  name = "X"', "}", ""].join("\n"),
+    );
+  });
+
+  it("snake_cases the CT field names the provider exposes", () => {
+    expect(
+      renderResource("person-status", "mitglied", {
+        name: "Mitglied",
+        shorty: "M",
+        isMember: true,
+        isSearchable: true,
+        sortKey: 10,
+        securityLevelId: 1,
+      }),
+    ).toContain("is_member         = true");
+  });
+
+  it("renders group-type as churchtools_group_type", () => {
+    expect(renderResource("group-type", "team", { name: "Team", nameTranslated: "Team" })).toContain(
+      'resource "churchtools_group_type" "team" {',
+    );
+  });
+
+  it("refuses a resource type it has no Terraform mapping for", () => {
+    expect(() => renderResource("group-role", "x", { name: "X" })).toThrow(/no Terraform resource type/);
+  });
+});
+
+describe("renderImports", () => {
+  it("keeps id 0 — the Mainz campus", () => {
+    expect(renderImports([{ type: "campus", key: "mainz", id: 0 }])).toBe(
+      ["import {", "  to = churchtools_campus.mainz", '  id = "0"', "}", ""].join("\n"),
+    );
+  });
+
+  it("uses the relabelled identifier in the import address", () => {
+    expect(renderImports([{ type: "group-type", key: "3_groupactive", id: 12 }])).toContain(
+      "to = churchtools_group_type.g_3_groupactive",
+    );
+  });
+});

From 4bb4ca9bda0621f3812116875da94cc4d8061748 Mon Sep 17 00:00:00 2001
From: Felix Kotschenreuther <felix.kotschenreuther@gmail.com>
Date: Thu, 17 Sep 2026 15:57:24 +0200
Subject: [PATCH 2/2] fix(export): make the generated root module honest and
 stable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review of #173 turned up six ways `ct export tf` produced output that looked
right and planned wrong. Each is now a failing-then-passing test in
tests/export/export-tf.test.ts, which drives runExportTf end to end instead of
re-implementing its loop.

- Six managed types (group, group-role, security-level, age-group,
  target-group, relationship-type) were skipped in silence. They are counted,
  reported as EXPORT_TYPE_UNSUPPORTED warnings and printed after the success
  line. Warn, not fail: the export is still useful for the five mapped types,
  and a hard error would make the command unusable on every real estate.
- imports.tf was written in raw state order while the .tf files were sorted, so
  re-keying one resource reshuffled the file. Both now sort on the same HCL
  address, by bytes — localeCompare disagrees with byte order on `-` vs `_`.
- Stale files were never pruned: `--only campus` truncated imports.tf but left
  group-types.tf managing resources no longer in the exported set. The export
  now prunes exactly the files it owns and nothing else.
- An unknown --only value filtered everything out, overwrote imports.tf with an
  empty string and exited 0. It is now refused up front.
- Two keys could collapse onto one HCL label (`a.b` and `a_b`), producing a
  duplicate address; assertLabelsUnique names both keys instead.
- `${` and `%{` in a CT name were emitted unescaped into a quoted template.

Also carries preventDestroy across as `lifecycle { prevent_destroy = true }` —
destroy protection lives in state, not in managedFields, so the export dropped
it and would have migrated a protected resource into an unprotected one — and
emits versions.tf, without which `tofu init` resolves churchtools_* to
registry.opentofu.org/hashicorp/churchtools and fails.

Comments no longer name a real campus; this repo is public.
---
 src/application/operations/export-tf.ts |  86 +++++++++++--
 src/commands/export-tf.ts               |   7 +-
 src/export/hcl.ts                       |  66 +++++++++-
 src/export/imports.ts                   |   4 +-
 src/export/layout.ts                    |  10 ++
 src/export/provider.ts                  |  23 ++++
 tests/export/export-tf.test.ts          | 159 ++++++++++++++++++++++++
 tests/export/hcl.test.ts                |  74 +++++++++--
 8 files changed, 400 insertions(+), 29 deletions(-)
 create mode 100644 src/export/provider.ts
 create mode 100644 tests/export/export-tf.test.ts

diff --git a/src/application/operations/export-tf.ts b/src/application/operations/export-tf.ts
index 47d0792..514c4df 100644
--- a/src/application/operations/export-tf.ts
+++ b/src/application/operations/export-tf.ts
@@ -1,11 +1,12 @@
 /** Orchestration for `ct export tf`: state in, .tf files out. */
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, rm, writeFile } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
-import { renderResource } from "../../export/hcl.js";
+import { assertLabelsUnique, hclLabel, hclType, renderResource } from "../../export/hcl.js";
 import { renderImports, type ImportTarget } from "../../export/imports.js";
-import { EXPORTABLE_TYPES, fileForType } from "../../export/layout.js";
+import { EXPORTABLE_TYPES, fileForType, OWNED_FILES } from "../../export/layout.js";
+import { renderVersions } from "../../export/provider.js";
 import { loadState } from "../../state/state.js";
-import type { OperationResult, ProjectRequest } from "../contracts.js";
+import type { CtWarning, OperationResult, ProjectRequest } from "../contracts.js";
 import { resolveProject } from "../project.js";
 
 export interface ExportTfRequest extends ProjectRequest {
@@ -18,25 +19,72 @@ export interface ExportTfValue {
   imported: number;
   /** Keys that could not be used verbatim as an HCL identifier. */
   relabelled: { key: string; label: string }[];
+  /** Managed types the provider has no mapping for yet, with how many were skipped. */
+  skipped: { type: string; count: number }[];
 }
 
 export type ExportTfResult = OperationResult<ExportTfValue>;
 
+/**
+ * Sort key for both the resource blocks and the import blocks.
+ *
+ * The two files MUST agree, and both must be byte-stable across runs: state is
+ * a JSON object, so its iteration order shifts when a resource is re-keyed
+ * (`upsert` re-inserts at the end) and integer-like keys sort ahead of the rest
+ * regardless of insertion order. Plain byte order, never `localeCompare` —
+ * locale collation puts "a-b" after "a_b" while bytes put it before, so a
+ * locale-sorted golden cannot pin what is written.
+ */
+function address(type: string, key: string): string {
+  return `${hclType(type)}.${hclLabel(key)}`;
+}
+
 export async function runExportTf(request: ExportTfRequest): Promise<ExportTfResult> {
   // resolveProject gives the env profile's state path AND the host the state
   // must belong to; loadState asserts that pairing, so an export can never
   // silently mix instances. No network and no auth: this reads state only.
   const project = await resolveProject(request);
   const state = await loadState(project.statePath, project.host);
+
+  // An unknown --only value used to filter everything out, write an empty
+  // imports.tf over a good one and exit 0 saying "0 resources exported".
+  const unknown = (request.only ?? []).filter((type) => !EXPORTABLE_TYPES.includes(type));
+  if (unknown.length > 0) {
+    throw new Error(
+      `export: unknown resource type(s) ${unknown.map((t) => `"${t}"`).join(", ")}. ` +
+        `Exportable types: ${EXPORTABLE_TYPES.join(", ")}.`,
+    );
+  }
   const types = request.only?.length ? request.only : EXPORTABLE_TYPES;
 
+  const rows = Object.values(state.resources);
+  const selected = rows.filter((r) => types.includes(r.type));
+  assertLabelsUnique(selected);
+
+  // Types the export has no provider mapping for are NOT the same as types the
+  // user filtered out with --only: the first is a gap the user has to be told
+  // about, because their `tofu plan` would propose creating every one of them.
+  const skippedCounts = new Map<string, number>();
+  for (const resource of rows) {
+    if (EXPORTABLE_TYPES.includes(resource.type)) continue;
+    skippedCounts.set(resource.type, (skippedCounts.get(resource.type) ?? 0) + 1);
+  }
+  const skipped = [...skippedCounts]
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([type, count]) => ({ type, count }));
+
   const byFile = new Map<string, string[]>();
   const imports: ImportTarget[] = [];
   const relabelled: { key: string; label: string }[] = [];
 
-  for (const resource of Object.values(state.resources)) {
-    if (!types.includes(resource.type)) continue;
-    const block = renderResource(resource.type, resource.key, resource.fields);
+  for (const resource of [...selected].sort((a, b) => {
+    const left = address(a.type, a.key);
+    const right = address(b.type, b.key);
+    return left < right ? -1 : left > right ? 1 : 0;
+  })) {
+    const block = renderResource(resource.type, resource.key, resource.fields, {
+      preventDestroy: resource.preventDestroy,
+    });
     const file = fileForType(resource.type);
     byFile.set(file, [...(byFile.get(file) ?? []), block]);
     imports.push({ type: resource.type, key: resource.key, id: resource.id });
@@ -51,17 +99,33 @@ export async function runExportTf(request: ExportTfRequest): Promise<ExportTfRes
   await mkdir(outDir, { recursive: true });
 
   const written: string[] = [];
-  for (const [file, blocks] of [...byFile].sort(([a], [b]) => a.localeCompare(b))) {
-    await writeFile(join(outDir, file), blocks.sort().join("\n"), "utf8");
+  for (const [file, blocks] of [...byFile].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+    await writeFile(join(outDir, file), blocks.join("\n"), "utf8");
     written.push(file);
   }
   await writeFile(join(outDir, "imports.tf"), renderImports(imports), "utf8");
   written.push("imports.tf");
+  await writeFile(join(outDir, "versions.tf"), renderVersions(), "utf8");
+  written.push("versions.tf");
+
+  // Prune only what this command owns, and only what it did not just write.
+  for (const file of OWNED_FILES) {
+    if (written.includes(file)) continue;
+    await rm(join(outDir, file), { force: true });
+  }
+
+  const warnings: CtWarning[] = skipped.map(({ type, count }) => ({
+    code: "EXPORT_TYPE_UNSUPPORTED",
+    message:
+      `${count} ${type} resource(s) were NOT exported: terraform-provider-churchtools has no ` +
+      `${type} resource yet. \`tofu plan\` will propose creating them — keep managing them with ct until then.`,
+    details: { type, count },
+  }));
 
   return {
     operation: "export-tf",
     project,
-    value: { files: written, imported: imports.length, relabelled },
-    warnings: [],
+    value: { files: written, imported: imports.length, relabelled, skipped },
+    warnings,
   };
 }
diff --git a/src/commands/export-tf.ts b/src/commands/export-tf.ts
index a31d982..42ee9ed 100644
--- a/src/commands/export-tf.ts
+++ b/src/commands/export-tf.ts
@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { runExportTf } from "../application/operations/export-tf.js";
-import { info } from "../ui.js";
+import { info, warn } from "../ui.js";
 
 interface ExportTfOptions {
   state?: string;
@@ -17,7 +17,7 @@ export function exportCommand(): Command {
     .option("--only <types...>", "restrict to these resource types (e.g. campus group-type)")
     .option("-o, --out <dir>", "output directory", "tofu")
     .action(async (opts: ExportTfOptions) => {
-      const { value } = await runExportTf({
+      const { value, warnings } = await runExportTf({
         statePath: opts.state,
         environment: opts.env,
         only: opts.only,
@@ -28,6 +28,9 @@ export function exportCommand(): Command {
         info(`relabelled "${r.key}" -> "${r.label}" (HCL references must be identifiers)`);
       }
       info(`${value.imported} resources exported`);
+      // Printed last, after the success line, so the gap is the final thing on
+      // screen rather than scrolled off above a list of written files.
+      for (const w of warnings) warn(w.message);
     });
 
   return new Command("export").description("Export managed state to other formats").addCommand(tf);
diff --git a/src/export/hcl.ts b/src/export/hcl.ts
index 009292d..542e49f 100644
--- a/src/export/hcl.ts
+++ b/src/export/hcl.ts
@@ -51,25 +51,83 @@ export function hclAttr(field: string): string {
  * must be a valid identifier, and `!3 GroupActive` derives a key starting with a
  * digit. Such keys get a `g_` prefix; the mapping is reported by the export
  * command so nothing renames silently.
+ *
+ * The mapping is MANY-TO-ONE (`a.b` and `a_b` both label `a_b`), and keys are
+ * user-settable via `--key`, so callers that render more than one resource of a
+ * type must run `assertLabelsUnique` over them — two blocks sharing an address
+ * is a `tofu` parse error, and the second import silently targets the first.
  */
 export function hclLabel(key: string): string {
   const safe = key.replace(/[^A-Za-z0-9_-]/g, "_");
   return /^[0-9-]/.test(safe) ? `g_${safe}` : safe;
 }
 
+/**
+ * Throw if two keys of the same type collapse onto one HCL label.
+ *
+ * Detected here rather than left to `tofu`: the export knows both keys and can
+ * say which two to rename, while `tofu` only reports a duplicate address.
+ */
+export function assertLabelsUnique(rows: readonly { type: string; key: string }[]): void {
+  const seen = new Map<string, string>();
+  for (const row of rows) {
+    const address = `${hclType(row.type)}.${hclLabel(row.key)}`;
+    const first = seen.get(address);
+    if (first !== undefined && first !== row.key) {
+      throw new Error(
+        `export: keys "${first}" and "${row.key}" both render as ${address}. ` +
+          `Re-key one of them (ct adopt --key) before exporting.`,
+      );
+    }
+    seen.set(address, row.key);
+  }
+}
+
+/**
+ * Quote a string as an HCL template literal.
+ *
+ * `JSON.stringify` escapes JSON metacharacters, not HCL's interpolation
+ * markers: a CT name containing `${` or `%{` would otherwise be parsed as an
+ * interpolation — a plan-time error, or silently the wrong value. HCL escapes
+ * those by doubling the sigil.
+ */
+export function hclString(value: string): string {
+  // Function replacers, not replacement strings: "$${" in a replacement string
+  // means an escaped `$` followed by `{` — i.e. exactly the input, a silent no-op.
+  return JSON.stringify(value)
+    .replace(/\$\{/g, () => "$${")
+    .replace(/%\{/g, () => "%%{");
+}
+
 function renderValue(value: unknown): string {
-  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "string") return hclString(value);
   if (typeof value === "number" || typeof value === "boolean") return String(value);
-  return JSON.stringify(value);
+  return hclString(JSON.stringify(value));
+}
+
+export interface RenderOptions {
+  /**
+   * Mirror of the state's `preventDestroy`. Destroy protection is the one piece
+   * of state that is not a managed field, and dropping it in the export would
+   * migrate a protected resource into an unprotected one — `ct destroy` refuses
+   * it, `tofu destroy` would not.
+   */
+  preventDestroy?: boolean;
 }
 
 /** Render one resource block. Null/undefined fields are omitted, never emitted as `null`. */
-export function renderResource(ctType: string, key: string, fields: Record<string, unknown>): string {
+export function renderResource(
+  ctType: string,
+  key: string,
+  fields: Record<string, unknown>,
+  options: RenderOptions = {},
+): string {
   const type = hclType(ctType);
   const entries = Object.entries(fields)
     .filter(([, v]) => v !== null && v !== undefined)
     .map(([k, v]) => [hclAttr(k), v] as const);
   const width = Math.max(0, ...entries.map(([k]) => k.length));
   const lines = entries.map(([k, v]) => `  ${k.padEnd(width)} = ${renderValue(v)}`);
-  return [`resource "${type}" "${hclLabel(key)}" {`, ...lines, "}", ""].join("\n");
+  const lifecycle = options.preventDestroy ? ["", "  lifecycle {", "    prevent_destroy = true", "  }"] : [];
+  return [`resource "${type}" "${hclLabel(key)}" {`, ...lines, ...lifecycle, "}", ""].join("\n");
 }
diff --git a/src/export/imports.ts b/src/export/imports.ts
index b9deea3..bad94a0 100644
--- a/src/export/imports.ts
+++ b/src/export/imports.ts
@@ -9,8 +9,8 @@ export interface ImportTarget {
 
 /**
  * `id` is stringified explicitly rather than passed through any truthiness
- * path: the Mainz campus is id 0, and dropping it would silently fail to
- * import exactly one resource.
+ * path: a campus can legitimately carry id 0, and a truthiness test would
+ * silently fail to import exactly that one resource.
  */
 export function renderImports(targets: readonly ImportTarget[]): string {
   return targets
diff --git a/src/export/layout.ts b/src/export/layout.ts
index 91a2f1f..04bf6de 100644
--- a/src/export/layout.ts
+++ b/src/export/layout.ts
@@ -14,3 +14,13 @@ export function fileForType(ctType: string): string {
 }
 
 export const EXPORTABLE_TYPES = Object.keys(FILE_BY_TYPE);
+
+/**
+ * Every file the export owns and may therefore overwrite or delete.
+ *
+ * The export prunes the ones it did not write this run: a `campuses.tf` left
+ * over from an earlier export (or from `--only`) keeps managing resources that
+ * are no longer in the exported set, and `tofu plan` then proposes creating
+ * what already exists. Nothing outside this list is ever touched.
+ */
+export const OWNED_FILES = [...Object.values(FILE_BY_TYPE), "imports.tf", "versions.tf"];
diff --git a/src/export/provider.ts b/src/export/provider.ts
new file mode 100644
index 0000000..df232a8
--- /dev/null
+++ b/src/export/provider.ts
@@ -0,0 +1,23 @@
+/** The generated root module's provider requirement — PURE. */
+
+/**
+ * Registry address of the successor provider. Emitted so the output directory
+ * is a runnable root module: without a `required_providers` block `tofu init`
+ * resolves `churchtools_*` to `registry.opentofu.org/hashicorp/churchtools` and
+ * fails, which is the first thing a migrating user would hit.
+ */
+export const PROVIDER_SOURCE = "eqrm/churchtools";
+
+/** No version constraint: the provider is pre-1.0 and pinning belongs in the user's repo. */
+export function renderVersions(): string {
+  return [
+    "terraform {",
+    "  required_providers {",
+    "    churchtools = {",
+    `      source = "${PROVIDER_SOURCE}"`,
+    "    }",
+    "  }",
+    "}",
+    "",
+  ].join("\n");
+}
diff --git a/tests/export/export-tf.test.ts b/tests/export/export-tf.test.ts
new file mode 100644
index 0000000..a3ca1bc
--- /dev/null
+++ b/tests/export/export-tf.test.ts
@@ -0,0 +1,159 @@
+import { mkdtemp, readdir, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { runExportTf } from "../../src/application/operations/export-tf.js";
+
+const HOST = "https://example.church.tools";
+
+interface Row {
+  type: string;
+  key: string;
+  id: number;
+  fields: Record<string, unknown>;
+  preventDestroy?: boolean;
+}
+
+let dir: string;
+
+async function stateWith(rows: Record<string, Row>): Promise<string> {
+  const path = join(dir, "ct-state.json");
+  await writeFile(
+    path,
+    JSON.stringify({ version: 1, host: HOST, resources: rows, permissions: {} }, null, 2),
+    "utf8",
+  );
+  return path;
+}
+
+function row(type: string, key: string, id: number, fields: Record<string, unknown> = {}): Row {
+  return { type, key, id, fields: { name: key, ...fields } };
+}
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), "ct-export-"));
+  vi.stubEnv("CT_HOST", HOST);
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+async function exportInto(rows: Record<string, Row>, only?: string[]) {
+  await stateWith(rows);
+  return runExportTf({ cwd: dir, statePath: "ct-state.json", outDir: "tofu", only });
+}
+
+describe("runExportTf", () => {
+  it("warns about managed types the provider cannot represent yet", async () => {
+    const result = await exportInto({
+      a: row("campus", "a", 1),
+      jugend: row("group", "jugend", 99),
+      leitung: row("group-role", "leitung", 5),
+      musik: row("group", "musik", 100),
+    });
+
+    expect(result.value.skipped).toEqual([
+      { type: "group", count: 2 },
+      { type: "group-role", count: 1 },
+    ]);
+    const message = result.warnings.map((w) => w.message).join("\n");
+    expect(result.warnings.map((w) => w.code)).toEqual([
+      "EXPORT_TYPE_UNSUPPORTED",
+      "EXPORT_TYPE_UNSUPPORTED",
+    ]);
+    expect(message).toContain("2 group resource(s) were NOT exported");
+    expect(message).toContain("1 group-role resource(s) were NOT exported");
+    // The export still runs: the mapped types are exported, not held hostage.
+    expect(result.value.imported).toBe(1);
+  });
+
+  it("says nothing about types the user filtered out on purpose", async () => {
+    const result = await exportInto({ a: row("campus", "a", 1), t: row("group-type", "t", 2) }, ["campus"]);
+    expect(result.warnings).toEqual([]);
+    expect(result.value.skipped).toEqual([]);
+    expect(result.value.imported).toBe(1);
+  });
+
+  it("refuses an --only type it cannot export instead of writing an empty imports.tf", async () => {
+    await expect(exportInto({ a: row("campus", "a", 1) }, ["campuses"])).rejects.toThrow(
+      /unknown resource type\(s\) "campuses"/,
+    );
+  });
+
+  it("orders imports.tf exactly like the resource blocks, whatever order state is in", async () => {
+    const forwards = await exportInto({
+      b: row("campus", "b", 7),
+      a: row("campus", "a", 0),
+      t: row("group-type", "t", 11),
+    });
+    const first = await readFile(join(dir, "tofu", "imports.tf"), "utf8");
+    const firstCampuses = await readFile(join(dir, "tofu", "campuses.tf"), "utf8");
+    expect(forwards.value.imported).toBe(3);
+
+    // Same resources, state object in a different (re-keyed) order.
+    const again = await exportInto({
+      t: row("group-type", "t", 11),
+      a: row("campus", "a", 0),
+      b: row("campus", "b", 7),
+    });
+    expect(again.value.imported).toBe(3);
+    expect(await readFile(join(dir, "tofu", "imports.tf"), "utf8")).toBe(first);
+    expect(await readFile(join(dir, "tofu", "campuses.tf"), "utf8")).toBe(firstCampuses);
+
+    expect(first.indexOf("churchtools_campus.a")).toBeLessThan(first.indexOf("churchtools_campus.b"));
+    expect(first.indexOf("churchtools_campus.b")).toBeLessThan(first.indexOf("churchtools_group_type.t"));
+  });
+
+  it("keeps id 0 importable", async () => {
+    await exportInto({ a: row("campus", "a", 0) });
+    expect(await readFile(join(dir, "tofu", "imports.tf"), "utf8")).toContain('id = "0"');
+  });
+
+  it("prunes the files it owns but did not write this run", async () => {
+    await exportInto({ a: row("campus", "a", 1), t: row("group-type", "t", 2) });
+    expect(await readdir(join(dir, "tofu"))).toContain("group-types.tf");
+
+    const narrowed = await exportInto({ a: row("campus", "a", 1), t: row("group-type", "t", 2) }, ["campus"]);
+    const left = await readdir(join(dir, "tofu"));
+    expect(left).not.toContain("group-types.tf");
+    expect(left.sort()).toEqual(["campuses.tf", "imports.tf", "versions.tf"]);
+    expect(narrowed.value.files).not.toContain("group-types.tf");
+  });
+
+  it("never touches a file it does not own", async () => {
+    await exportInto({ a: row("campus", "a", 1) });
+    await writeFile(join(dir, "tofu", "main.tf"), "# hand written\n", "utf8");
+    await exportInto({ a: row("campus", "a", 1) });
+    expect(await readFile(join(dir, "tofu", "main.tf"), "utf8")).toBe("# hand written\n");
+  });
+
+  it("writes a provider requirement so the output directory is a runnable root module", async () => {
+    const result = await exportInto({ a: row("campus", "a", 1) });
+    expect(result.value.files).toContain("versions.tf");
+    const versions = await readFile(join(dir, "tofu", "versions.tf"), "utf8");
+    expect(versions).toContain("required_providers");
+    expect(versions).toContain('source = "eqrm/churchtools"');
+  });
+
+  it("carries destroy protection across instead of silently dropping it", async () => {
+    await exportInto({
+      a: { ...row("campus", "a", 1), preventDestroy: true },
+      b: row("campus", "b", 2),
+    });
+    const campuses = await readFile(join(dir, "tofu", "campuses.tf"), "utf8");
+    expect(campuses).toContain("prevent_destroy = true");
+    expect(campuses.split("prevent_destroy").length - 1).toBe(1);
+  });
+
+  it("refuses two keys that would share one HCL address", async () => {
+    await expect(
+      exportInto({ x: row("campus", "mainz.kids", 1), y: row("campus", "mainz_kids", 2) }),
+    ).rejects.toThrow(/both render as churchtools_campus\.mainz_kids/);
+  });
+
+  it("escapes HCL interpolation markers in exported names", async () => {
+    await exportInto({ a: row("campus", "a", 1, { name: "Campus ${var.x}" }) });
+    expect(await readFile(join(dir, "tofu", "campuses.tf"), "utf8")).toContain('"Campus $${var.x}"');
+  });
+});
diff --git a/tests/export/hcl.test.ts b/tests/export/hcl.test.ts
index feb7ce3..65e6d01 100644
--- a/tests/export/hcl.test.ts
+++ b/tests/export/hcl.test.ts
@@ -1,10 +1,10 @@
 import { describe, expect, it } from "vitest";
-import { hclLabel, renderResource } from "../../src/export/hcl.js";
+import { assertLabelsUnique, hclLabel, hclString, renderResource } from "../../src/export/hcl.js";
 import { renderImports } from "../../src/export/imports.js";
 
 describe("hclLabel", () => {
   it("passes through identifier-safe keys", () => {
-    expect(hclLabel("team_kidsdienst")).toBe("team_kidsdienst");
+    expect(hclLabel("team_musik")).toBe("team_musik");
   });
 
   it("prefixes keys starting with a digit", () => {
@@ -12,16 +12,20 @@ describe("hclLabel", () => {
   });
 
   it("replaces characters HCL cannot reference", () => {
-    expect(hclLabel("mainz.kids")).toBe("mainz_kids");
+    expect(hclLabel("standort.kids")).toBe("standort_kids");
   });
 });
 
 describe("renderResource", () => {
   it("renders a campus block with quoted strings", () => {
-    expect(renderResource("campus", "mainz", { name: "Mainz", shorty: "MZ" })).toBe(
-      ['resource "churchtools_campus" "mainz" {', '  name   = "Mainz"', '  shorty = "MZ"', "}", ""].join(
-        "\n",
-      ),
+    expect(renderResource("campus", "hauptstandort", { name: "Hauptstandort", shorty: "HS" })).toBe(
+      [
+        'resource "churchtools_campus" "hauptstandort" {',
+        '  name   = "Hauptstandort"',
+        '  shorty = "HS"',
+        "}",
+        "",
+      ].join("\n"),
     );
   });
 
@@ -56,9 +60,9 @@ describe("renderResource", () => {
 });
 
 describe("renderImports", () => {
-  it("keeps id 0 — the Mainz campus", () => {
-    expect(renderImports([{ type: "campus", key: "mainz", id: 0 }])).toBe(
-      ["import {", "  to = churchtools_campus.mainz", '  id = "0"', "}", ""].join("\n"),
+  it("keeps id 0 — a real, importable campus id", () => {
+    expect(renderImports([{ type: "campus", key: "hauptstandort", id: 0 }])).toBe(
+      ["import {", "  to = churchtools_campus.hauptstandort", '  id = "0"', "}", ""].join("\n"),
     );
   });
 
@@ -68,3 +72,53 @@ describe("renderImports", () => {
     );
   });
 });
+
+describe("hclString", () => {
+  it("doubles the HCL interpolation sigils a JSON escape leaves alone", () => {
+    // `${` would otherwise be parsed as a template interpolation, not a name.
+    expect(hclString("Campus ${var.x}")).toBe('"Campus $${var.x}"');
+    expect(hclString("100%{if}")).toBe('"100%%{if}"');
+    expect(hclString('a "quoted" name')).toBe('"a \\"quoted\\" name"');
+  });
+});
+
+describe("assertLabelsUnique", () => {
+  it("names both keys when two collapse onto one address", () => {
+    expect(() =>
+      assertLabelsUnique([
+        { type: "campus", key: "standort.kids" },
+        { type: "campus", key: "standort_kids" },
+      ]),
+    ).toThrow(/"standort.kids" and "standort_kids" both render as churchtools_campus.standort_kids/);
+  });
+
+  it("allows the same label under different resource types", () => {
+    expect(() =>
+      assertLabelsUnique([
+        { type: "campus", key: "team" },
+        { type: "group-type", key: "team" },
+      ]),
+    ).not.toThrow();
+  });
+});
+
+describe("renderResource lifecycle", () => {
+  it("mirrors destroy protection into the generated block", () => {
+    expect(renderResource("campus", "a", { name: "A" }, { preventDestroy: true })).toBe(
+      [
+        'resource "churchtools_campus" "a" {',
+        '  name = "A"',
+        "",
+        "  lifecycle {",
+        "    prevent_destroy = true",
+        "  }",
+        "}",
+        "",
+      ].join("\n"),
+    );
+  });
+
+  it("emits no lifecycle block for an unprotected resource", () => {
+    expect(renderResource("campus", "a", { name: "A" })).not.toContain("lifecycle");
+  });
+});