feat(project): scaffold shared Terraform root with iac selection

[jariy17]

Description

Add an experimental Terraform deployment backend for the refactor branch. agentcore create --name MyProject --iac terraform immediately scaffolds editable HCL root files under agentcore/terraform/, referencing the application module maintained in the L3 constructs repository. --iac accepts CDK and Terraform case-insensitively; CDK remains the default.

The root passes a spec object to the module, initially using jsondecode(file(...)) to read agentcore.json. Customers can edit supported JSON settings and run Terraform directly, or pass inline HCL with references to their own resources. Named outputs expose runtime roles and resource identifiers for additional permissions and infrastructure. Build packages Python code and preserves root HCL edits. Every deployment target uses this same root; target inputs, plans, provider initialization data, and local state are isolated under .targets/<target>/. Customer edits apply to whichever target is planned next, without copying configuration. The module source is pinned to an immutable Git commit; upgrading it is an explicit root HCL change. During this draft PoC the pin points to the contributor fork for the companion L3 PR.

The connected example covers memory, a Python CodeZip runtime, policy engine/policy, an IAM MCP gateway with Python Lambda targets, and builtin online evaluation. AWSCC 1.106.0 manages the AgentCore primitives except GatewayTarget, which that release does not expose. AWS 6.69.0 manages gateway targets and supporting IAM, S3 and Lambda. Like the L3 construct, the module leaves runtime, Lambda and evaluation log groups to the services. Terraform references establish resource dependencies; resources use logical-name keys to preserve addresses when lists are reordered.

The CLI supports separate local state per target for one operator. Target binding rejects account/region reassignment, legacy state layouts, missing current state with a populated backup, remote backends and custom state paths. A shared-root lock serializes CLI operations that update artifacts and the provider lockfile. The CLI selects the target backend and variables file explicitly and applies the saved plan. Backend checks also detect custom state configured by standalone Terraform, and legacy-layout checks preserve existing target roots while allowing customer modules. Removing all project resources requests teardown confirmation and preserves resources customers declared outside the application module.

This remains a draft PoC with bounded feature coverage. CDK migration, remote state, other runtime packaging/authentication/networking modes, other gateway target types and custom evaluators are outside scope. Gateway JSON Schemas are validated to an explicit eight-level limit. The typed object contract rejects known unsupported settings, but Terraform object conversion is not general typo detection for arbitrary attributes.

Live testing (manual, one test account, Terraform 1.16.6, via the packaged CLI):

Area	Result
Fresh project from empty state	create → build → deploy succeeded on first apply; status lists every resource; repeat plan: no changes
Runtime	ping and a model-backed Strands prompt returned 200
Memory	event written/listed; semantic strategy extracted "The user prefers green tea." into /users/{actorId}/facts
Gateway + Lambda target	tools/list returned the tool; tools/call returned the Lambda result through IAM SigV4
Policy	permit allows the call; forbid filters tools/list and denies the call naming the policy; a lone LOG_ONLY policy leaves default-deny in force; restoring permit restores access
Online evaluation	every model session received a Builtin.Helpfulness score (3 of 3, 0.83); probe sessions without model spans are logged as evaluation errors
Updates	runtime and Lambda code changes deployed in place (runtime version bumped) and were observed in responses
Teardown	remove all + deploy tore down the fresh project; no runtime, memory, gateway, policy engine, evaluation, Lambda, role or bucket remained

Defects found live and fixed: an over-broad shared trust condition, an unscoped sample Cedar policy, module-owned log groups and evaluation output configuration that the L3 does not create, an empty-tags perpetual diff, and first-apply failures from IAM propagation (memory trust, gateway policy, evaluation policy), now handled by per-resource time_sleep waits. The gateway trust policy now reproduces the CDK L2 role exactly, including its unconditioned statement. Policy names are unique per account and Region, as with CDK.

These are manual live runs, not automated end-to-end tests; the repository e2e suite was not run. CloudWatch Transaction Search follows the existing CLI account-level setup and is outside Terraform state.

Related Issue

Related to #1919.

Companion module PR: aws/agentcore-l3-cdk-constructs#424.
Pinned module commit: 39b824c1cdbc4926bea745616610e516344537f4 in the contributor fork. Replace the PoC source with an upstream release when available.

Documentation PR

Included here: the connected example and standalone Terraform root in examples/terraform-poc/, and regenerated command.md. Module implementation, tests, and API documentation belong to the companion L3 PR.

Type of Change

• New feature
• Documentation update
• Other: experimental backend / proof of concept

Testing

• Full CLI unit suite: 4,658 passed, zero failures. Regression coverage includes shared root edits across targets, isolated state/inputs/plans, source locking, legacy layout preservation, standalone backend checks, and preflight handler-suffix and reserved-variable rules.

• Companion L3 module: 36 mock-provider tests passed, including runtime/memory, gateway/policy and online-evaluation parity with the L3 construct.

• Live: see the table above.

• Typecheck, lint, formatting, bundle build and secret scanning passed.

• I ran bun test

• I ran the relevant end-to-end tests with bun run test:e2e, or explained why they are not applicable

• I ran bun run typecheck

• I ran bun run lint:check

• I ran bun run format:check

• I ran bun run build

• If I modified src/assets/, I updated affected snapshots with bun test <test-file> --update-snapshots and committed them

Scaffolding is covered by command and backend tests; the companion L3 PR owns the Terraform mock-provider tests. Existing snapshots remain unchanged. Live behavior was verified manually as described above; automated e2e coverage for the Terraform backend is outstanding.

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

This is a well-scoped, deliberately bounded experimental Terraform backend. The implementation hangs together:

• Strict preflight() validation (src/core/project/backends/terraform/compiler.ts) rejects every unsupported field before any I/O, with good test coverage via test.each in compiler.test.ts.
• Customer strings are consistently sent through literal() to escape ${...} and %{...} so Terraform never interpolates untrusted input, while resource references are preserved.
• Resource addresses use key() (name + stable 10-char sha256 suffix), so reordering resources in agentcore.json does not force replacement — covered by the "reordering resources preserves addresses" test.
• The custom .agentcore-operation.lock covers package → generate → init → plan → apply as one unit, independent of Terraform's own state lock; the error message tells the user how to recover from a stuck lock.
• Credentials are resolved per operation, re-materialized for apply, and AWS_PROFILE / AWS_WEB_IDENTITY_TOKEN_FILE / AWS_ROLE_ARN / etc. are stripped from the env so Terraform cannot bypass the resolved credentials. Account mismatch is checked before Terraform runs.
• TerraformAssetPackager produces deterministic ZIPs (fixed mtime, sorted entries, excluded .env* / .venv / node_modules / terraform, symlink rejection, 250 MiB cap), and the aws-opentelemetry-distro dependency check prevents silently shipping an uninstrumented runtime.
• Tests prefer real temp directories and only stub the process runner / credential resolver — no excessive mocking at non-I/O boundaries. terraform.test.ts also covers the credential-account mismatch, failed-step state preservation, teardown confirmation, and CDK-adoption refusal.

The README is explicit that live deployment, updates and teardown are unverified, and the backend hard-fails if a CDK deployment already exists, so there is no risk of this silently taking over real projects.

Non-blocking observation

No CLI telemetry was added for --managed-by Terraform, the Terraform deploy path, or the preflight rejections (see src/cli/telemetry/README.md). Given this is a bounded PoC that users opt into, that is defensible, but adding a counter for Terraform create/deploy/validate-reject outcomes would make it much easier to tell whether anyone exercises the PoC and which preflight rules bite them. Worth doing in a follow-up if this backend graduates.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[codecov-commenter]

Codecov Report

❌ Patch coverage is 96.30563% with 44 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.56%. Comparing base (6c45032) to head (9983b14).
⚠️ Report is 2 commits behind head on refactor.

Files with missing lines	Patch %	Lines
src/core/project/backends/terraform.ts	88.11%	34 Missing ⚠️
src/core/project/backends/terraform/preflight.ts	96.07%	10 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2602      +/-   ##
============================================
- Coverage     96.57%   96.56%   -0.01%     
============================================
  Files           699      704       +5     
  Lines         57427    58595    +1168     
============================================
+ Hits          55462    56585    +1123     
- Misses         1965     2010      +45     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)