docs: document Automation API previewDestroy/previewRefresh

[workprentice]

What this does

Adds a "Preview a destroy or refresh without applying it" section to the Automation API guide (content/docs/iac/guides/building-extending/automation-api.md), documenting previewDestroy/previewRefresh (and their language-specific equivalents), which exist across all supported Automation API SDKs but were previously undocumented.

Why

This is a proactive freshness-audit fix continuing the Automation API coverage-gap rotation: tag management was covered in #20729, and this PR picks up the next naturally-paired slice (preview-only destroy/refresh) rather than trying to cover the whole remaining gap (Rename, ImportResources) in one PR.

Verification

Method signatures were verified directly against SDK source rather than paraphrased:

• TypeScript: sdk/nodejs/automation/stack.ts — previewDestroy(opts?: DestroyOptions): Promise<PreviewResult>, previewRefresh(opts?: RefreshOptions): Promise<PreviewResult>
• Python: sdk/python/lib/pulumi/automation/_stack.py — preview_destroy(...) -> PreviewResult, preview_refresh(...) -> PreviewResult
• Go: sdk/go/auto/stack.go — PreviewDestroy/PreviewRefresh, both gated behind Pulumi CLI >= 3.105.0 by the SDK's own version check (documented in the new section)
• .NET (pulumi/pulumi-dotnet): no standalone preview method; DestroyOptions.PreviewOnly / RefreshOptions.PreviewOnly on the regular DestroyAsync/RefreshAsync calls, confirmed against sdk/Pulumi.Automation/{DestroyOptions,RefreshOptions}.cs and the existing PreviewDestroy xUnit test in LocalWorkspaceTests.cs
• Java (pulumi/pulumi-java): same previewOnly builder-option pattern, confirmed against sdk/java/pulumi/.../{DestroyOptions,RefreshOptions}.java

make lint (markdown-lint + prettier) passes clean. Ran Vale against the changed file; findings present are all pre-existing, outside the new section.

---

🧠 This PR was created by workprentice on behalf of the Pulumi docs team.

[github-actions]

Pre-merge Review — Last updated 2026-08-06T15:03:58Z

Tip

Summary: This PR adds one new section — "Preview a destroy or refresh without applying it" — to the Automation API guide (content/docs/iac/guides/building-extending/automation-api.md), documenting previewDestroy/previewRefresh in TypeScript, Python, and Go and the equivalent PreviewOnly / previewOnly options in C# and Java. The wrongness that would block a reader here is an API that doesn't exist in the SDK they have installed: a wrong method name, a wrong options property, or a stated minimum version that doesn't actually cover the API being shown. All 11 method-, option-, and version-level claims were checked against the pulumi/pulumi, pulumi-dotnet, and pulumi-java SDK sources and release notes and all came back verified; the section's chooser/choosable structure matches the eight existing chooser blocks on the page byte-for-byte, and both sibling guides in building-extending/ were read for conflicting guidance. One low-confidence note below concerns the version floor, not a method name.

Review confidence:

Dimension	Level	Notes
mechanics	HIGH
facts	HIGH
cross-sibling consistency	HIGH
code correctness	MEDIUM	Snippets were read and checked against SDK signatures, but not compiled — the section lives in a guide, not under static/programs/, so no execution pass ran.

Investigation log

• Cross-sibling reads: 2 of 2 siblings
• External claim verification: 11 of 11 claims verified (0 unverifiable, 0 contradicted) · 4 specialists (numerical, cross-reference, capability, framing); 0 cross-specialist corroborations · routed: 0 inline, 11 Pass 1, 0 Pass 2, 0 Pass 3.
• Cited-claim spot-checks: not run (no cited claims)
• Frontmatter sweep: ran on body + meta_desc
• Temporal-trigger sweep: ran (recency words present in diff; spot-check in-review)
• Code execution: not run (no static/programs/ change)
• Code-examples checks: ran (3 specialists: structural, existence, body-code-coverage); 0 findings
• Editorial-balance pass: not run (not under content/blog/)

🚨 Outstanding	⚠️ Low-confidence	💡 Pre-existing	✅ Resolved
0	1	0	0

🔍 Verification trail

11 claims extracted · 11 verified · 0 unverifiable · 0 contradicted

• L981 in content/docs/iac/guides/building-extending/automation-api.md "Previewing a destroy or refresh without applying it (via the dedicated preview methods or PreviewOnly option) requires Pulumi CLI 3.105.0 or later." → ✅ verified (evidence: The pulumi/pulumi v3.105.0 release notes (2024-02-07) list: "[cli] Adds a preview-only flag to pulumi refresh." and "[cli] Adds preview-only flag for pulumi destroy and pulumi import" — exactly matching the claim that PreviewOnly…; source: gh release view v3.105.0 -R pulumi/pulumi)
• L983 in content/docs/iac/guides/building-extending/automation-api.md "In TypeScript, Python, and Go, there is a dedicated method that returns the same PreviewResult shape as the regular preview method, without ever calling the de…" → ✅ verified (evidence: Pulumi SDK source confirms dedicated methods returning PreviewResult in Go, Node/TS, and Python: sdk/go/auto/stack.go: "func (s *Stack) PreviewDestroy(ctx context.Context, opts ...optdestroy.Option) (PreviewResult, error)"; `sdk/nodejs/a…; source: gh search code --owner pulumi "previewDestroy" (pulumi/pulumi: sdk/go/auto/stack.go, sdk/nodejs/automation/stack.ts, changelog/v3.192.0.md))
• L985 in content/docs/iac/guides/building-extending/automation-api.md "The preview-without-applying feature for destroy and refresh is documented for the languages TypeScript, Python, Go, C#, and Java via language choosers." → ✅ verified (evidence: The chooser block at line 985 is {{< chooser language \"typescript,python,go,csharp,java\" >}} with {{% choosable language ... %}} sections for each of typescript, python, go, csharp, and java, each documenting the preview-without-appl…; source: repo:content/docs/iac/guides/building-extending/automation-api.md (lines 979-1044))
• L989-990 in content/docs/iac/guides/building-extending/automation-api.md "In TypeScript, calling stack.previewDestroy({ onOutput: console.info }) previews a destroy operation without applying it." → ✅ verified (evidence: Release notes for pulumi/pulumi v3.192.0 confirm: "[sdk/nodejs] Add previewDestroy to allow dry-runs of destroy commands" (PR add blog post for automatic logging #20371). The doc's own surrounding text states this method "returns the same PreviewResult shape as preview,…; source: gh release view v3.192.0 -R pulumi/pulumi; repo:content/docs/iac/guides/building-extending/automation-api.md)
• L998-999 in content/docs/iac/guides/building-extending/automation-api.md "In Python, calling stack.preview_destroy(on_output=print) previews a destroy operation without applying it." → ✅ verified (evidence: pulumi/pulumi sdk/python/lib/pulumi/automation/_stack.py defines def preview_destroy( on the Stack class, and its test suite calls stack.preview_destroy(run_program=True) and asserts on preview_destroy_res.change_summary — confirming…; source: gh search code --owner pulumi "def preview_destroy" (pulumi/pulumi:sdk/python/lib/pulumi/automation/_stack.py); pulumi/pulumi:sdk/python/lib/test/automation/test_local_workspace.py)
• L1007-1011 in content/docs/iac/guides/building-extending/automation-api.md "In Go, calling s.PreviewDestroy(ctx, optdestroy.ProgressStreams(os.Stdout)) previews a destroy operation without applying it, returning an error value on failu…" → ✅ verified (evidence: Go SDK source confirms: func (s *Stack) PreviewDestroy(ctx context.Context, opts ...optdestroy.Option) (PreviewResult, error) in sdk/go/auto/stack.go, and func ProgressStreams(writers ...io.Writer) Option in sdk/go/auto/optdestroy/optd…; source: gh search code --owner pulumi "PreviewDestroy" --repo pulumi/pulumi; gh search code --owner pulumi "ProgressStreams" "optdestroy" --repo pulumi/pulumi)
• L1013-1017 in content/docs/iac/guides/building-extending/automation-api.md "In Go, calling s.PreviewRefresh(ctx, optrefresh.ProgressStreams(os.Stdout)) previews a refresh operation without applying it, returning an error value on failu…" → ✅ verified (framing: Claim mentions only the error return; source shows the full (PreviewResult, error) signature, which the claim's error-focused description is a narrower but acc…; evidence: Go SDK source confirms the signature: func (s *Stack) PreviewRefresh(ctx context.Context, opts ...optrefresh.Option) (PreviewResult, error). The doc's own example matches: `refreshPreview, err := s.PreviewRefresh(ctx, optrefresh.Progress…; source: gh search code --owner pulumi "PreviewRefresh" --repo pulumi/pulumi (sdk/go/auto/stack.go))
• L1024 in content/docs/iac/guides/building-extending/automation-api.md "In C#, setting PreviewOnly on the corresponding options object and calling the regular destroy or refresh method causes the Pulumi CLI to run the operation in…" → ✅ verified (evidence: pulumi/pulumi-dotnet's DestroyOptions.cs and RefreshOptions.cs both define public bool? PreviewOnly { get; set; } with doc comments "Only show a preview of the destroy [refresh], but don't perform the destroy [refresh] itself." This matc…; source: gh api repos/pulumi/pulumi-dotnet/contents/sdk/Pulumi.Automation/DestroyOptions.cs and RefreshOptions.cs (ref main))
• L1027-1028 in content/docs/iac/guides/building-extending/automation-api.md "In C#, calling stack.DestroyAsync(new DestroyOptions { PreviewOnly = true }) returns a destroy preview without changing the stack's state." → ✅ verified (evidence: In pulumi/pulumi-dotnet's sdk/Pulumi.Automation/DestroyOptions.cs, the PreviewOnly property is documented: "Only show a preview of the destroy, but don't perform the destroy itself." DestroyOptions extends UpdateOptions and is pass…; source: gh api repos/pulumi/pulumi-dotnet/contents/sdk/Pulumi.Automation/DestroyOptions.cs?ref=main)
• L1035 in content/docs/iac/guides/building-extending/automation-api.md "Java follows the same pattern as C# for previewing destroy and refresh operations: setting previewOnly on the options builder and calling the regular method." → ✅ verified (evidence: pulumi-java SDK's DestroyOptions.java and RefreshOptions.java expose a Builder.previewOnly(boolean) method (e.g. "public Builder previewOnly(boolean previewOnly) { this.previewOnly = previewOnly; ... }"), matching the doc's code sample `…; source: gh search code --owner pulumi previewOnly (pulumi/pulumi-java: sdk/java/pulumi/src/main/java/com/pulumi/automation/DestroyOptions.java, RefreshOptions.java))
• L1038-1039 in content/docs/iac/guides/building-extending/automation-api.md "In Java, calling stack.destroy(DestroyOptions.builder().previewOnly(true).build()) previews a destroy operation without applying it." → ✅ verified (evidence: pulumi-java's automation SDK defines DestroyOptions with a previewOnly builder method, and WorkspaceStack checks options.previewOnly() before applying the destroy; the exact call `stack.destroy(DestroyOptions.builder().previewOnly(true).bu…; source: gh search code --owner pulumi previewOnly language:java (pulumi/pulumi-java: DestroyOptions.java, WorkspaceStack.java, LocalWorkspaceTest.java))

🚨 Outstanding in this PR

No outstanding findings in this PR.

⚠️ Low-confidence

Review each and resolve as appropriate — these don't block the PR.

• [L981] content/docs/iac/guides/building-extending/automation-api.md — "Requires Pulumi CLI 3.105.0 or later." The version floor is correct for the CLI, but it may under-state what a reader needs for the dedicated methods this section leads with. Pulumi CLI 3.105.0 (2024-02-07) is where pulumi destroy/pulumi refresh gained --preview-only, which is what the C# and Java PreviewOnly/previewOnly samples ride on. The TypeScript, Python, and Go previewDestroy/previewRefresh methods, however, are language-SDK additions that landed much later — the Node.js one shipped in v3.192.0 ("[sdk/nodejs] Add previewDestroy to allow dry-runs of destroy commands"). A reader on CLI 3.105.0 with a pre-3.192 @pulumi/pulumi will hit stack.previewDestroy is not a function and have no way to tell from this page why. Consider naming the SDK floor alongside the CLI floor, e.g.:

  Sometimes you want to know what a `destroy` or `refresh` would do before committing to it, for example to gate an automated teardown behind a manual approval step, or to inspect drift without writing it back to the stack's state. Requires Pulumi CLI 3.105.0 or later; the dedicated `previewDestroy`/`previewRefresh` methods also require a recent language SDK (3.192.0 or later for TypeScript, Python, and Go).
  

  Worth confirming the exact per-language SDK versions before merging — the Node.js number is the one the release notes pin down directly.

💡 Pre-existing issues in touched files (optional)

No pre-existing issues in touched files.

✅ Resolved since last review

No items resolved since the last review.

📜 Review history

• 2026-08-06T15:03:58Z — All 11 API and version claims in the new "Preview a destroy or refresh without applying it" section verified against the SDK sources; no blockers, one low-confidence note on whether the stated 3.105.0 CLI floor also covers the TypeScript/Python/Go SDK methods. (16354be)

---

• Refresh this review — comment @claude #update-review. Say what you fixed, or which finding you dispute and why; both work in the same mention.
• Ask for anything else — comment @claude with no hashtag (questions, one-off fixes). Leaves this review untouched.

Important

Please don't hide, resolve, or delete this comment! It breaks things!

📖 How pre-merge review works — the full lifecycle, short-circuits, and escape hatches.

[pulumi-bot]

Your site preview for commit 16354be is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-20734-16354be9.s3-website.us-west-2.amazonaws.com

Changed pages:

• /docs/iac/guides/building-extending/automation-api/