Skip to content

Commit c9a8790

Browse files
kramhuberVenelinMartinovclaude
authored
Add pulumi neo debug command (#23499)
Adds `pulumi neo --debug-update` and `pulumi neo --debug-preview` flags that open an interactive Neo session seeded to investigate a failed update or preview, and updates the `pulumi up` / `pulumi preview` failure output to suggest the matching command. Run bare (e.g. `pulumi neo --debug-update`), each flag targets the stack's most recent operation of that kind; pass `=<id>` (e.g. `--debug-update=42`) to target a specific update version or preview id. Updates and previews are resolved separately since previews never appear in update history. **Part of a cross-repo series.** The seed prompt routes to the `pulumi-debug-failed-operation` skill (pulumi/agent-skills#35), which reaches Neo via pulumi/pulumi-service#44486. Works without the skill, but the guided procedure needs it deployed. Independent of the console-prompt PR (pulumi/pulumi-service#44487). --------- Co-authored-by: Venelin Martinov <[email protected]> Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
1 parent 4a79549 commit c9a8790

12 files changed

Lines changed: 596 additions & 106 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
kind: chore
2+
body: Add `pulumi neo --debug-update` and `pulumi neo --debug-preview` flags to investigate a failed update or preview, suggested in the failure output
3+
component: cli
4+
custom:
5+
PR: "23499"

‎pkg/backend/display/ai.go‎

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,11 @@ func neoDelimiterEmoji() string {
4545
return cmdutil.EmojiOr(" ✨", ":")
4646
}
4747

48-
// RenderNeoErrorSummary renders a Neo error summary to the console.
49-
func RenderNeoErrorSummary(summary *NeoErrorSummaryMetadata, err error, opts Options, permalink string) {
48+
// RenderNeoErrorSummary renders a Neo error summary to the console. isPreview selects the debug
49+
// command suggested in the link (`--debug-preview` vs `--debug-update`).
50+
func RenderNeoErrorSummary(
51+
summary *NeoErrorSummaryMetadata, err error, opts Options, permalink string, isPreview bool,
52+
) {
5053
out := opts.Stdout
5154
if out == nil {
5255
out = os.Stdout
@@ -77,17 +80,27 @@ func RenderNeoErrorSummary(summary *NeoErrorSummaryMetadata, err error, opts Opt
7780

7881
fmt.Fprintln(out)
7982

80-
PrintNeoLink(out, opts, permalink)
83+
PrintNeoLink(out, opts, permalink, isPreview)
8184
}
8285

83-
func PrintNeoLink(out io.Writer, opts Options, permalink string) {
86+
// PrintNeoLink prints the "would you like help" link plus the terminal command to debug the
87+
// failure. isPreview picks `--debug-preview` for a failed preview, `--debug-update` otherwise.
88+
func PrintNeoLink(out io.Writer, opts Options, permalink string, isPreview bool) {
8489
fmt.Fprintln(out, " "+"Would you like additional help with this update?")
8590
fmt.Fprintln(out, " "+
8691
opts.Color.Colorize(colors.Underline+colors.BrightBlue+ExplainFailureLink(permalink)+colors.Reset))
87-
fmt.Fprintln(out, " "+"Or run `pulumi neo` for an interactive agent in your terminal.")
92+
fmt.Fprintln(out, " "+"Or run `"+neoDebugCommand(isPreview)+"` in your terminal.")
8893
fmt.Fprintln(out)
8994
}
9095

96+
// neoDebugCommand returns the `pulumi neo` debug invocation that targets the failed operation kind.
97+
func neoDebugCommand(isPreview bool) string {
98+
if isPreview {
99+
return "pulumi neo --debug-preview"
100+
}
101+
return "pulumi neo --debug-update"
102+
}
103+
91104
// RenderNeoThinking displays a "Thinking..." message.
92105
func RenderNeoThinking(opts Options) {
93106
stdout := opts.Stdout

‎pkg/backend/display/ai_test.go‎

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -36,22 +36,40 @@ func TestRenderCopilotErrorSummary(t *testing.T) {
3636
ShowLinkToNeo: true,
3737
}
3838

39-
// Render to buffer
39+
// isPreview=false, so the suggestion targets a failed update.
4040
RenderNeoErrorSummary(&NeoErrorSummaryMetadata{
4141
Summary: summary,
42-
}, nil, opts, "http://foo.bar/baz")
42+
}, nil, opts, "http://foo.bar/baz", false)
4343

4444
expectedCopilotSummary := fmt.Sprintf(`Neo Diagnostics%s
4545
This is a test summary
4646
4747
Would you like additional help with this update?
4848
http://foo.bar/baz?explainFailure
49-
Or run `+"`pulumi neo`"+` for an interactive agent in your terminal.
49+
Or run `+"`pulumi neo --debug-update`"+` in your terminal.
5050
5151
`, neoDelimiterEmoji())
5252
assert.Equal(t, expectedCopilotSummary, buf.String())
5353
}
5454

55+
func TestRenderCopilotErrorSummaryPreview(t *testing.T) {
56+
t.Parallel()
57+
58+
// For a failed preview the suggestion targets --debug-preview instead of --debug-update.
59+
buf := new(bytes.Buffer)
60+
opts := Options{
61+
Stdout: buf,
62+
Color: colors.Never,
63+
ShowLinkToNeo: true,
64+
}
65+
66+
RenderNeoErrorSummary(&NeoErrorSummaryMetadata{
67+
Summary: "This is a test summary",
68+
}, nil, opts, "http://foo.bar/baz", true)
69+
70+
assert.Contains(t, buf.String(), "Or run `pulumi neo --debug-preview` in your terminal.")
71+
}
72+
5573
func TestRenderCopilotErrorSummaryError(t *testing.T) {
5674
t.Parallel()
5775

@@ -61,7 +79,7 @@ func TestRenderCopilotErrorSummaryError(t *testing.T) {
6179
Color: colors.Never,
6280
}
6381

64-
RenderNeoErrorSummary(nil, errors.New("test error"), opts, "http://foo.bar/baz")
82+
RenderNeoErrorSummary(nil, errors.New("test error"), opts, "http://foo.bar/baz", false)
6583

6684
expectedCopilotSummaryWithError := fmt.Sprintf(`Neo Diagnostics%s
6785
error summarizing update output: test error
@@ -79,7 +97,7 @@ func TestRenderCopilotErrorSummaryNoSummaryOrError(t *testing.T) {
7997
Color: colors.Never,
8098
}
8199

82-
RenderNeoErrorSummary(nil, nil, opts, "http://foo.bar/baz")
100+
RenderNeoErrorSummary(nil, nil, opts, "http://foo.bar/baz", false)
83101

84102
assert.Equal(t, "", buf.String())
85103
}
@@ -97,7 +115,7 @@ func TestRenderCopilotErrorSummaryWithError(t *testing.T) {
97115

98116
RenderNeoErrorSummary(&NeoErrorSummaryMetadata{
99117
Summary: summary,
100-
}, errors.New("test error"), opts, "http://foo.bar/baz")
118+
}, errors.New("test error"), opts, "http://foo.bar/baz", false)
101119

102120
expectedCopilotSummaryWithErrorAndSummary := fmt.Sprintf(`Neo Diagnostics%s
103121
error summarizing update output: test error

‎pkg/backend/httpstate/backend.go‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -241,6 +241,10 @@ type Backend interface {
241241
PromptAI(ctx context.Context, requestBody AIPromptRequestBody) (*http.Response, error)
242242
// Capabilities returns the capabilities of the backend indicating what features are available.
243243
Capabilities(ctx context.Context) apitype.Capabilities
244+
245+
// GetLatestStackPreview returns the stack's most recent preview operation, or nil if the
246+
// stack has no previews. Previews are tracked separately from update history (GetHistory).
247+
GetLatestStackPreview(ctx context.Context, stackRef backend.StackReference) (*apitype.StackPreview, error)
244248
}
245249

246250
// userInfo holds the user account details fetched from the backend.
@@ -1762,7 +1766,7 @@ func (b *cloudBackend) renderAndSummarizeOutput(
17621766
summary, err := b.summarizeErrorWithNeo(ctx, renderer.Output(), stack.Ref(), op.Opts.Display)
17631767
// Pass the error into the renderer to ensure it's displayed. We don't want to fail the update/preview
17641768
// if we can't generate a summary.
1765-
display.RenderNeoErrorSummary(summary, err, op.Opts.Display, permalink)
1769+
display.RenderNeoErrorSummary(summary, err, op.Opts.Display, permalink, dryRun)
17661770
}
17671771
}
17681772
}
@@ -2266,6 +2270,26 @@ func (b *cloudBackend) GetHistory(
22662270
return beUpdates, nil
22672271
}
22682272

2273+
// GetLatestStackPreview returns the stack's most recent preview operation, or nil if it has none.
2274+
func (b *cloudBackend) GetLatestStackPreview(
2275+
ctx context.Context,
2276+
stackRef backend.StackReference,
2277+
) (*apitype.StackPreview, error) {
2278+
stack, err := b.getCloudStackIdentifier(stackRef)
2279+
if err != nil {
2280+
return nil, err
2281+
}
2282+
2283+
previews, err := b.client.GetLatestStackPreviews(ctx, stack)
2284+
if err != nil {
2285+
return nil, fmt.Errorf("failed to get stack previews: %w", err)
2286+
}
2287+
if len(previews) == 0 {
2288+
return nil, nil
2289+
}
2290+
return &previews[0], nil
2291+
}
2292+
22692293
func (b *cloudBackend) GetLatestConfiguration(ctx context.Context,
22702294
stack backend.Stack,
22712295
) (backend.LatestConfiguration, error) {

‎pkg/backend/httpstate/client/client.go‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1423,6 +1423,22 @@ func (pc *Client) GetStackUpdates(
14231423
return response.Updates, nil
14241424
}
14251425

1426+
// GetLatestStackPreviews returns the stack's most recent preview operations, newest-first.
1427+
// Previews are tracked separately from update history (see GetStackUpdates).
1428+
func (pc *Client) GetLatestStackPreviews(
1429+
ctx context.Context,
1430+
stack StackIdentifier,
1431+
) ([]apitype.StackPreview, error) {
1432+
var response apitype.GetLatestStackPreviewsResponse
1433+
// asc=false requests newest-first; the endpoint otherwise defaults to oldest-first.
1434+
path := getStackPath(stack, "updates", "latest", "previews") + "?asc=false&pageSize=1&page=1"
1435+
if err := pc.restCall(ctx, "GET", path, nil, nil, &response); err != nil {
1436+
return nil, err
1437+
}
1438+
1439+
return response.Updates, nil
1440+
}
1441+
14261442
// ExportStackDeployment exports the indicated stack's deployment as a raw JSON message.
14271443
// If version is nil, will export the latest version of the stack.
14281444
func (pc *Client) ExportStackDeployment(

‎pkg/backend/httpstate/mock.go‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,8 @@ type MockHTTPBackend struct {
4343
deploymentInitiator string,
4444
suppressStreamLogs bool,
4545
) error
46-
FGetCloudRegistry func() (backend.CloudRegistry, error)
46+
FGetCloudRegistry func() (backend.CloudRegistry, error)
47+
FGetLatestStackPreview func(ctx context.Context, stackRef backend.StackReference) (*apitype.StackPreview, error)
4748
}
4849

4950
func (b *MockHTTPBackend) Client() *client.Client {
@@ -95,4 +96,10 @@ func (b *MockHTTPBackend) GetCloudRegistry() (backend.CloudRegistry, error) {
9596
return b.FGetCloudRegistry()
9697
}
9798

99+
func (b *MockHTTPBackend) GetLatestStackPreview(
100+
ctx context.Context, stackRef backend.StackReference,
101+
) (*apitype.StackPreview, error) {
102+
return b.FGetLatestStackPreview(ctx, stackRef)
103+
}
104+
98105
var _ Backend = (*MockHTTPBackend)(nil)

‎pkg/cmd/pulumi/neo/debug.go‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
// Copyright 2026, Pulumi Corporation.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package neo
16+
17+
import (
18+
"context"
19+
"fmt"
20+
"strconv"
21+
"strings"
22+
23+
"github.com/pulumi/pulumi/pkg/v3/backend"
24+
"github.com/pulumi/pulumi/pkg/v3/backend/httpstate"
25+
)
26+
27+
// debugKind identifies which failed operation a debug session targets. The values double as the
28+
// noun used in the seed prompt, so callers can format a debugKind directly.
29+
type debugKind string
30+
31+
const (
32+
debugNone debugKind = ""
33+
debugUpdate debugKind = "update"
34+
debugPreview debugKind = "preview"
35+
)
36+
37+
// latestID returns the id of the stack's most recent operation of this kind, or "" when none is
38+
// available. Updates and previews are looked up separately (previews never appear in GetHistory):
39+
// an update resolves to its history version, a preview to its opaque UpdateID. Best-effort.
40+
func (k debugKind) latestID(ctx context.Context, be httpstate.Backend, stackRef backend.StackReference) string {
41+
if stackRef == nil {
42+
return ""
43+
}
44+
switch k {
45+
case debugUpdate:
46+
if updates, err := be.GetHistory(ctx, stackRef, 1, 1); err == nil && len(updates) > 0 {
47+
return strconv.Itoa(updates[0].Version)
48+
}
49+
case debugPreview:
50+
if p, err := be.GetLatestStackPreview(ctx, stackRef); err == nil && p != nil {
51+
return p.UpdateID
52+
}
53+
case debugNone:
54+
// Not a debug session; nothing to look up.
55+
}
56+
return ""
57+
}
58+
59+
// buildDebugPrompt assembles the full initial prompt for a debug session: the seed trigger line
60+
// (so Neo's skill evaluator loads the debugging skill) followed by the stack context. An empty id
61+
// is resolved to the latest operation of kind; any userPrompt sits between the two as extra
62+
// guidance. Every lookup is best-effort, so the prompt is always well-formed.
63+
func buildDebugPrompt(
64+
ctx context.Context, be httpstate.Backend,
65+
target taskTarget, kind debugKind, id, userPrompt string,
66+
) string {
67+
if id == "" {
68+
id = kind.latestID(ctx, be, target.ref)
69+
}
70+
seed := debugSeedPrompt(kind, id)
71+
if userPrompt != "" {
72+
seed += "\n\n" + userPrompt
73+
}
74+
return seed + "\n\n" + debugStackContext(be, target, kind, id)
75+
}
76+
77+
// debugSeedPrompt builds Neo's initial prompt for a debug session. It is a short trigger line, not
78+
// a procedure: Neo's skill evaluator matches it and loads the debugging skill. With no id it targets
79+
// the most recent operation of that kind; with an id, that specific run.
80+
func debugSeedPrompt(kind debugKind, id string) string {
81+
if id == "" {
82+
return fmt.Sprintf(
83+
"Debug my most recent Pulumi %s on this stack and fix it directly in this working directory.\n",
84+
kind)
85+
}
86+
return fmt.Sprintf(
87+
"Debug the failed Pulumi %s %s of this stack and fix it directly in this working directory.\n",
88+
kind, id)
89+
}
90+
91+
// debugStackContext builds a block describing the debug session's org, user, project, stack, and
92+
// resolved operation, appended to the seed prompt so Neo starts with the failure in context. Every
93+
// field is best-effort: anything empty or unavailable is omitted.
94+
func debugStackContext(be httpstate.Backend, target taskTarget, kind debugKind, id string) string {
95+
var b strings.Builder
96+
b.WriteString("Context for this debug session:\n")
97+
if target.org != "" {
98+
fmt.Fprintf(&b, "- Organization: %s\n", target.org)
99+
}
100+
if user, _, _, err := be.CurrentUser(); err == nil && user != "" {
101+
fmt.Fprintf(&b, "- User: %s\n", user)
102+
}
103+
if target.project != "" {
104+
fmt.Fprintf(&b, "- Project: %s\n", target.project)
105+
}
106+
if name := target.stackName(); name != "" {
107+
fmt.Fprintf(&b, "- Stack: %s\n", name)
108+
}
109+
if id != "" {
110+
fmt.Fprintf(&b, "- Debugging: %s %s\n", kind, id)
111+
}
112+
return b.String()
113+
}

0 commit comments

Comments
 (0)