fix(deploy): explain "parent must exist" with actionable hint

internal/commands/deploy.go

@@ -113,6 +113,55 @@ func resolveStartRevision(server *sdk.Server, group *sdk.ServerGroup, flagStart
 	return ""
 }
 
+// translateParentMustExistError detects the API's 422 "parent must exist"
+// validation failure and rewrites it as a UserError that explains the
+// situation and what to do.
+//
+// The API rejects a deployment when its start_revision doesn't trace to a
+// prior deployment's end_revision on the same target. Two real-world causes:
+//   - the SHA was force-pushed/rebased out of the repo while the server's
+//     LastRevision still points at it
+//   - the user passed --start-revision <sha> with a SHA that was never the
+//     end of a prior deploy on this target
+//
+// Without translation the user sees "deployhq api: 422 parent must exist",
+// which is opaque. The replacement names the SHA, explains the cause, and
+// offers --full as an escape hatch.
+func translateParentMustExistError(err error, startRevision string) error {
+	if err == nil {
+		return nil
+	}
+	var apiErr *sdk.APIError
+	if !errors.As(err, &apiErr) || apiErr.StatusCode != http.StatusUnprocessableEntity {
+		return err
+	}
+	if !mentionsParentMustExist(apiErr) {
+		return err
+	}
+	sha := startRevision
+	if sha == "" {
+		sha = "(none)"
+	}
+	return &output.UserError{
+		Message: fmt.Sprintf("No prior deployment matches start_revision %s on this target", sha),
+		Hint: "Incremental deploys need a prior deployment whose end_revision equals this SHA. Likely the SHA was force-pushed away or was never deployed here.\n" +
+			"  --full                          deploy the entire branch from the first commit\n" +
+			"  --start-revision <sha>          use a SHA that ended a prior deploy (see 'dhq deployments list')",
+	}
+}
+
+func mentionsParentMustExist(e *sdk.APIError) bool {
+	if strings.Contains(e.Message, "parent must exist") {
+		return true
+	}
+	for _, msg := range e.Errors {
+		if strings.Contains(msg, "parent must exist") {
+			return true
+		}
+	}
+	return false
+}
+
 // resolveDeployProject returns the project identifier for a deploy.
 //
 // When the user did not pass --project (or set DEPLOYHQ_PROJECT / a
@@ -493,7 +542,7 @@ func newDeployCmd() *cobra.Command {
 			if dryRun {
 				preview, err := client.PreviewDeployment(cliCtx.Background(), projectID, req)
 				if err != nil {
-					return err
+					return translateParentMustExistError(err, req.StartRevision)
 				}
 
 				if env.WantsJSON() {
@@ -514,7 +563,7 @@ func newDeployCmd() *cobra.Command {
 
 			dep, err := client.CreateDeployment(cliCtx.Background(), projectID, req)
 			if err != nil {
-				return err
+				return translateParentMustExistError(err, req.StartRevision)
 			}
 
 			if env.WantsJSON() {

internal/commands/deploy_test.go

@@ -508,6 +508,54 @@ func TestResolveBranchAndRevision_ServerPreferredBranchBeatsGroup(t *testing.T)
 	assert.Equal(t, "sha-of-server", revision)
 }
 
+func TestTranslateParentMustExistError_RewritesMessageField(t *testing.T) {
+	in := &sdk.APIError{StatusCode: 422, Message: "parent must exist"}
+	out := translateParentMustExistError(in, "abc123de")
+	require.Error(t, out)
+	// Sha must be in Message (telemetry preserves first line).
+	firstLine := strings.SplitN(out.Error(), "\n", 2)[0]
+	assert.Contains(t, firstLine, "No prior deployment matches start_revision abc123de")
+	assert.Contains(t, out.Error(), "--full")
+	assert.Contains(t, out.Error(), "--start-revision <sha>")
+}
+
+func TestTranslateParentMustExistError_RewritesErrorsArray(t *testing.T) {
+	// The Rails validator usually returns the message in the "errors" array,
+	// not the "error" field. The translation must catch both shapes.
+	in := &sdk.APIError{StatusCode: 422, Errors: []string{"parent must exist", "something else"}}
+	out := translateParentMustExistError(in, "deadbeef")
+	require.Error(t, out)
+	assert.Contains(t, out.Error(), "deadbeef")
+	assert.Contains(t, out.Error(), "--full")
+}
+
+func TestTranslateParentMustExistError_EmptyStartRevisionShownExplicitly(t *testing.T) {
+	in := &sdk.APIError{StatusCode: 422, Message: "parent must exist"}
+	out := translateParentMustExistError(in, "")
+	require.Error(t, out)
+	assert.Contains(t, out.Error(), "(none)",
+		"empty start_revision should be rendered as (none) so the user can tell")
+}
+
+func TestTranslateParentMustExistError_PassesThroughUnrelatedErrors(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+	}{
+		{"nil", nil},
+		{"non-API error", assert.AnError},
+		{"422 but different validation", &sdk.APIError{StatusCode: 422, Message: "branch can't be blank"}},
+		{"parent-must-exist text on a non-422", &sdk.APIError{StatusCode: 500, Message: "parent must exist"}},
+	}
+	for _, tc := range tests {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			out := translateParentMustExistError(tc.err, "abc123")
+			// Untouched: same value (including nil).
+			assert.Equal(t, tc.err, out)
+		})
+	}
+}
 // testEnvelope returns an Envelope wired to a bytes.Buffer so Status messages
 // are captured for assertion.
 func testEnvelope() (*output.Envelope, *bytes.Buffer) {