[sowju-hashicorp]

Summary

PR 5 of 6 in the Terraform Search stack.

Branch: sowju/search-05-prepare-import
Base: sowju/search-04-results

Adds read-only prepare_import on both MCP SDKs to prepare explicitly selected Search results for a separately confirmed import destination.

Changes

• Accepts explicit query_result_marker selections, caller-proposed managed resource types, and exact target provider versions reported from the local lockfile.
• Resolves and confirms the import target independently from the Search source.
• Validates source provenance, same-organization destination ownership, target execution mode, and known Terraform-version incompatibilities.
• Reuses streaming evidence validation while retaining full observations and generated HCL only for selected markers.
• Structurally validates available selected resource HCL before returning resource/import drafts.
• Returns generation availability, selected observations, and stateless import_context for later Plan verification.
• Includes optional historical schema evidence from the target state's producing Run.
• Adds adapter, registration, scope, preflight, collector, logging, and documentation coverage.

Security and data handling

• Never uses TF_MCP_QUERY_WORKSPACE as an import-target default. Target resolution uses explicit arguments, then TF_MCP_IMPORT_WORKSPACE, then TF_WORKSPACE.
• Validates the entire QueryRun before returning prepared results; selected-only retention does not bypass checks on unselected records or late completion failures.
• Returns full generated resource/import HCL only for explicitly selected results.
• Does not materialize or expose provider resource_object data.
• Preserves caller-proposed managed types and unchanged identity/version/provider evidence in import_context.
• Treats generated HCL as potentially sensitive, untrusted, incomplete, and review-required.
• Uses markers and the context digest for continuity checks—not authentication, authorization, or tamper-proof attestation.
• Preserves the existing 256 MiB decoded-log safety ceiling.

The server does not read local files or attest the caller-reported lockfile. Historical schema evidence does not prove compatibility with the locally locked provider release or validate final authored HCL.

Read-only boundary

prepare_import does not:

• Initialize providers or select provider versions.
• Modify local configuration or workspaces.
• Upload configuration or create a Terraform Run.
• Execute terraform import, write state, or apply changes.

Local inspection and configuration authoring remain separate agent/user activities. Any speculative Plan requires separate approval.

Validation

• Focused tests passed for Search logic, client middleware, both SDK integrations, registration, toolsets, instructions, and CLI.
• Coverage includes independent target confirmation, provider-source/version validation, target eligibility, selected-only evidence retention, and preparation preflight failures.
• Cross-SDK structured and JSON-text result coverage passed.
• Server build and diff checks passed.
• No live HCP Terraform operations were performed.

Reviewer focus

• Separation of Search source and import destination.
• Explicit selection and complete evidence validation before disclosure.
• Exact locked-provider handling and historical-schema qualifications.
• Preservation of managed types and identity evidence in stateless context.
• Selected generated-HCL output and the no-upload/no-Run/no-apply boundary.

Stack scope

Depends on PR 4 for validated summaries, markers, streaming evidence processing, and generated-HCL parsing. Set this PR's base to sowju/search-04-results so the diff shows only import preparation.

Exact speculative Run and Plan verification remains deferred to PR 6. This layer ends at prepared evidence and reviewed local changes; it does not establish import or apply safety.

Next branch: sowju/search-06-verify-plan, based on this branch.

Rollback

Revert this PR before PR 6 merges. If PR 6 has merged, coordinate its rollback first.

Reverting removes preparation support but leaves the Search-only workflow intact. The tool performs no remote mutations, so no infrastructure rollback is required. Any separately authored local configuration must be reviewed and reverted independently if needed.

PCI review checklist

• I have documented a clear reason for, and description of, the change I am making.

• If applicable, I've documented a plan to revert these changes if they require more than reverting the pull request.

• If applicable, I've documented the impact of any changes to security controls.

  Examples of changes to security controls include using new access control methods, adding or removing logging pipelines, etc.

[Copilot]

🟡 Changes recommended

Managed-type prefix inference rejects valid provider/resource combinations despite matching selection and locked-provider evidence.

2 open issues

• Rejects providers whose resource prefix differs from source name · New
• Fixture ignores provider namespace and name in stored query · New

What changed in this PR

Adds read-only prepare_import to both MCP SDKs, extending Terraform Search from result summaries to explicitly selected import evidence. Plan verification remains deferred to PR 6.

Changes:

• Adds independent target confirmation, exact locked-provider validation, and destination eligibility checks.
• Validates complete QueryRun evidence while returning only selected observations, HCL drafts, and stateless import context.
• Registers the tool across both SDKs and adds workflow documentation, logging checks, and integration coverage.

File	Description
README.md	Documents selected-only preparation and its boundaries.
pkg/​toolsets/​search.go	Adds credential-gated preparation metadata.
pkg/​toolsets/​search_test.go	Updates toolset and credential-gating expectations.
pkg/​tools/​search/​scope.go	Adds independent import-target scope resolution.
pkg/​tools/​search/​scope_test.go	Covers target defaults and confirmation guidance.
pkg/​tools/​search/​prepare_import.go	Implements preparation, evidence selection, and import context.
pkg/​tools/​search/​prepare_collector_test.go	Checks selected-only evidence retention.
pkg/​tools/​search/​import_tools.go	Adds the legacy SDK adapter and tool contract.
pkg/​tools/​search/​import_tools_test.go	Covers preparation inputs, results, and legacy transport.
pkg/​tools/​search/​import_preflight_test.go	Tests validation and blocked-state guidance.
pkg/​tools/​search/​diagnostic_codes.go	Defines preparation diagnostic codes.
pkg/​tools/​search/​descriptions_test.go	Checks preparation contract wording.
pkg/​tools/​factories.go	Registers the legacy preparation tool.
pkg/​tools/​factories_test.go	Tests credential-aware registration.
pkg/​mcp-official/​tools/​tools.go	Registers the official SDK preparation tool.
pkg/​mcp-official/​tools/​tools_test.go	Updates registration and credential tests.
pkg/​mcp-official/​tools/​search/​search.go	Adds the official SDK schema and handler.
pkg/​mcp-official/​tools/​search/​search_test.go	Tests official schemas, validation, and scope interaction.
pkg/​mcp-official/​tools/​prepare_test.go	Tests cross-SDK parity, preflight, and disclosure boundaries.
pkg/​mcp-official/​tools/​middleware/​tool_logging_test.go	Checks preparation argument and error logging protections.
pkg/​instructions/​instructions.md	Adds import preparation workflow guidance.
pkg/​instructions/​instructions_test.go	Checks preparation instructions and stopping boundaries.
pkg/​client/​tool_logging_middleware_test.go	Checks legacy preparation argument logging protections.
CHANGELOG.md	Records preparation support and remaining limitations.

_{Review effort: Balanced}