fix(cli): wave 3 — BugHunt 2026-05-20 T16 P2/P3 fixes

T16 P2-1 — parse the structured error envelope from the api instead of
dumping the raw JSON body at the user. New apierror.go translates
{error, error_code, message, agent_action, upgrade_url, retry_after_seconds}
into a human-readable single-line error, with status-specific framing for
402 (tier wall), 429 (rate limited + retry hint), and 5xx (server error).
Wired into provisionResource, discover/resources, fetchExistingResources,
and provisionForUp — every code path that surfaced a raw body before.

T16 P2-2 — HTTPClient timeout raised from 10s to 60s (configurable via
INSTANT_TIMEOUT_SECONDS env var). Synchronous provisioning on the api can
legitimately exceed 10s under load; the previous timeout aborted slow-but-
successful requests AFTER the server created the resource, leaving an
orphan the user was billed for. 60s matches the api's documented
provisioning budget.

T16 P2-3 — `up`'s env default changes from "production" to "development"
to match the platform default (CLAUDE.md rule 11 / migration 026). New
upDefaultEnv constant. The auth gate now applies to any non-default env:
`--env=production` anonymously fails fast with ExitAuthRequired instead
of silently shipping live. New env resolution order:
--env > manifest.env > $INSTANT_ENV > "development".

T16 P2-4 — webhook REUSE preserves --emit-env output. Previously the
credentials endpoint returned 404 for webhooks (no connection_url) and
the REUSE path printed "credentials hidden" + dropped the export line,
breaking idempotent .env regeneration. Now the CLI reconstructs the
webhook receive URL deterministically from APIBaseURL + token, matching
the api's `receiveURL()` shape.

T16 P2-5 — fetchCredentials parameter renamed id → token with a load-
bearing doc comment pinning the contract: the api's
/api/v1/resources/:id/credentials path parameter is the resource's
TOKEN (UUID), not its database row id. Added mock idDifferentFromToken
mode + a regression test that drives the CLI through PROVISION → REUSE
when id and token are distinct values.

T16 P3 — --json output mode added to `resources`, `status`, and `whoami`.
Stable JSON schemas for agent consumption. The whoami JSON output NEVER
includes the bearer token (T16 P1-1 still holds for the machine-readable
surface) — only the truncated key_display + secret_backend name.

Tests (cmd/bughunt_p2_test.go, 11 new regression tests, hermetic):
  TestBugHunt_T16_P2_1_402_TierWallSurfacesAgentAction
  TestBugHunt_T16_P2_1_429_RateLimitedShowsRetry
  TestBugHunt_T16_P2_1_5xxFallsBackToRawBodyOnNonJSON
  TestBugHunt_T16_P2_2_ProvisionTimeoutAtLeast60s
  TestBugHunt_T16_P2_3_UpDefaultsToDevelopmentNotProd
  TestBugHunt_T16_P2_3_UpExplicitProductionStillNeedsAuth
  TestBugHunt_T16_P2_4_WebhookReuseEmitsExportLine
  TestBugHunt_T16_P2_5_CredentialsKeyedByTokenNotID
  TestBugHunt_T16_P3_ResourcesJSONOutput
  TestBugHunt_T16_P3_StatusJSONOutput
  TestBugHunt_T16_P3_WhoamiJSONOutputNeverLeaksToken

Existing test fixtures updated env: production → env: development to
match the new platform default (the explicit auth-required-for-non-prod
test still uses --env=staging).

Build + vet + test (race) all green: 55 PASS, 0 FAIL.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mastermanas805

cmd/apierror.go

@@ -0,0 +1,153 @@
+package cmd
+
+// apierror.go — parse the standardised API error envelope and surface its
+// fields cleanly to the user.
+//
+// T16 P2-1: every 4xx/5xx response from api.instanode.dev follows the W7G
+// envelope:
+//
+//   {
+//     "ok": false,
+//     "error": "quota_exceeded",      // machine-readable code
+//     "error_code": "quota_exceeded", // alternate spelling (server may emit either)
+//     "message": "You've hit your hobby-tier postgres limit (1 / 1).",
+//     "agent_action": "Run `instant upgrade` to raise the limit, …",
+//     "upgrade_url": "https://instanode.dev/billing",
+//     "request_id": "req_abc123",
+//     "retry_after_seconds": 30
+//   }
+//
+// Before this fix the CLI dumped the entire raw JSON body to the user,
+// which is non-actionable noise (and may leak server-internal strings).
+// parseAPIError() turns the envelope into a stable, human-readable error
+// message that always carries the most useful field for the status code:
+//
+//   402 → message + agent_action + upgrade_url
+//   429 → "rate limited, retry in N seconds" + agent_action
+//   5xx → message + agent_action ("server error, retry later")
+//   4xx → message + agent_action
+//   other → fall back to truncated raw body (defensive)
+//
+// The helper never returns nil — even if parsing fails (non-JSON body),
+// it returns a truncated raw-body error so the caller still gets *some*
+// message.
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+)
+
+// apiErrorEnvelope mirrors the W7G error shape served by api.instanode.dev.
+// Optional fields are pointers/empty-zero so we can detect "field absent"
+// vs "field present but empty".
+type apiErrorEnvelope struct {
+	OK                bool   `json:"ok"`
+	Error             string `json:"error"`
+	ErrorCode         string `json:"error_code"`
+	Message           string `json:"message"`
+	AgentAction       string `json:"agent_action"`
+	UpgradeURL        string `json:"upgrade_url"`
+	Upgrade           string `json:"upgrade"`              // legacy shape
+	RequestID         string `json:"request_id"`
+	RetryAfterSeconds int    `json:"retry_after_seconds"`
+}
+
+// code returns the most-specific error code the envelope carries.
+func (e *apiErrorEnvelope) code() string {
+	if e.ErrorCode != "" {
+		return e.ErrorCode
+	}
+	return e.Error
+}
+
+// humanMessage returns the most descriptive single-line message available.
+// Preference: message > agent_action > error code > "".
+func (e *apiErrorEnvelope) humanMessage() string {
+	if e.Message != "" {
+		return e.Message
+	}
+	if e.AgentAction != "" {
+		return e.AgentAction
+	}
+	return e.code()
+}
+
+// parseAPIError takes an HTTP status code and a raw response body, and
+// produces a single error whose message is the cleanest representation
+// the envelope contents allow. The status is part of the message so an
+// agent script can grep on it; the body is only echoed (truncated) when
+// parsing fails entirely.
+//
+// Never returns nil.
+func parseAPIError(status int, raw []byte) error {
+	body := strings.TrimSpace(string(raw))
+	if body == "" {
+		return fmt.Errorf("server returned %d (no body)", status)
+	}
+
+	var env apiErrorEnvelope
+	if err := json.Unmarshal(raw, &env); err != nil {
+		// Body wasn't JSON, or wasn't the envelope shape. Fall back to the
+		// raw body, truncated so we don't dump megabytes of HTML / stack
+		// traces into the user's terminal.
+		return fmt.Errorf("server returned %d: %s", status, truncate(body, 200))
+	}
+
+	// If we got an envelope but every interesting field is empty, fall back
+	// to the truncated raw body so we still surface *something*.
+	if env.code() == "" && env.Message == "" && env.AgentAction == "" {
+		return fmt.Errorf("server returned %d: %s", status, truncate(body, 200))
+	}
+
+	// Build the human message. Status-specific framing first, then the
+	// envelope's own message, then agent_action, then upgrade_url.
+	var parts []string
+
+	switch {
+	case status == 402:
+		// Tier wall — the most actionable status.
+		parts = append(parts, fmt.Sprintf("%d %s", status, codeOrDefault(env.code(), "tier limit reached")))
+	case status == 429:
+		// Rate limited. Include retry hint when the server provides one.
+		if env.RetryAfterSeconds > 0 {
+			parts = append(parts,
+				fmt.Sprintf("%d rate limited (retry in %ds)",
+					status, env.RetryAfterSeconds))
+		} else {
+			parts = append(parts, fmt.Sprintf("%d rate limited", status))
+		}
+	case status >= 500:
+		// Transient server error — agent should retry.
+		parts = append(parts, fmt.Sprintf("%d %s", status, codeOrDefault(env.code(), "server error, retry later")))
+	default:
+		parts = append(parts, fmt.Sprintf("%d %s", status, codeOrDefault(env.code(), "request rejected")))
+	}
+
+	if env.Message != "" {
+		parts = append(parts, env.Message)
+	}
+	if env.AgentAction != "" && env.AgentAction != env.Message {
+		parts = append(parts, "→ "+env.AgentAction)
+	}
+	upgrade := env.UpgradeURL
+	if upgrade == "" {
+		upgrade = env.Upgrade
+	}
+	if upgrade != "" {
+		parts = append(parts, "upgrade: "+upgrade)
+	}
+	if env.RequestID != "" {
+		parts = append(parts, "(request_id="+env.RequestID+")")
+	}
+
+	return fmt.Errorf("%s", strings.Join(parts, " — "))
+}
+
+// codeOrDefault returns code when non-empty, otherwise the fallback.
+func codeOrDefault(code, fallback string) string {
+	if code == "" {
+		return fallback
+	}
+	return code
+}

cmd/bughunt_p1_test.go

@@ -48,7 +48,7 @@ func p1_4_fixture(t *testing.T, listStatus int, expectedExitCode int) {
 	c.mock.mu.Unlock()
 
 	manifest := writeManifest(t, `
-env: production
+env: development
 resources:
   - type: postgres
     name: dont-double-up
@@ -114,7 +114,7 @@ func TestBugHunt_T16_P1_4_UpAbortsOnListFetch_401_AuthenticatedSession(t *testin
 	c.mock.mu.Unlock()
 
 	manifest := writeManifest(t, `
-env: production
+env: development
 resources:
   - type: postgres
     name: dont-double-up-401
@@ -164,7 +164,7 @@ func TestBugHunt_T16_P1_3_ExitCodes_UpResourceFailed(t *testing.T) {
 	c.mock.mu.Unlock()
 
 	manifest := writeManifest(t, `
-env: production
+env: development
 resources:
   - type: postgres
     name: doomed
@@ -216,7 +216,7 @@ func TestBugHunt_T16_P1_5_EmitEnvShellQuotesHostileValues(t *testing.T) {
 	c.mock.mu.Unlock()
 
 	manifest := writeManifest(t, `
-env: production
+env: development
 resources:
   - type: postgres
     name: hostile-url
@@ -260,7 +260,7 @@ resources:
 func TestBugHunt_T16_P1_5_EmitEnvSanitizesExportName(t *testing.T) {
 	c := newITContext(t)
 	manifest := writeManifest(t, `
-env: production
+env: development
 resources:
   - type: postgres
     name: My App DB
@@ -420,7 +420,7 @@ func TestBugHunt_T16_P1_2_UniformExitCodeFor401(t *testing.T) {
 
 	// (c) `up`
 	manifest := writeManifest(t, `
-env: production
+env: development
 resources:
   - type: postgres
     name: stale-up