fix(cli): a failed D1 introspection named a warning as its cause

`wrangler d1 execute --json` writes its error to STDOUT and warnings to stderr.
The runner read stderr alone, so an estate whose wrangler.toml carries an `unsafe`
field was told its production schema gate failed because "unsafe fields are
experimental and may change or break at any time" — a WARNING, reported as the
cause of a failure — while the real cause, "In a non-interactive environment, it's
necessary to set a CLOUDFLARE_API_TOKEN…", was discarded unread.

`wranglerFailureReason` picks the reason: wrangler's structured error first
({error:{text}}, {error}, and the [{success:false,error}] execute envelope), then
stderr, then raw stdout, then the process message. Stderr stays in the chain — a
genuine failure that never reaches stdout must not be swallowed to fix the opposite
mistake. Verified end to end against the live D1 that produced the wrong message.

Found by running an adopter estate's own verify:prod-schema against production for
the first time: the one declared gate no estate pass had exercised, wrong on its
first run.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NTcEKXTQMYt84fAjuw5A2M

Author: dmealing

CHANGELOG.md

@@ -7,6 +7,27 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Fixed — a failed D1 introspection named a WARNING as its cause
+
+`meta verify --db` / `meta migrate` against a live D1 shell out to
+`wrangler d1 execute … --json`, and **`--json` puts wrangler's error on STDOUT** while
+stderr carries only warnings. The runner reported stderr alone, so an estate whose
+`wrangler.toml` uses an `unsafe` field was told its production schema gate failed
+because *"`unsafe` fields are experimental and may change or break at any time"* — a
+warning, printed as the cause of a failure, with the real one (`In a non-interactive
+environment, it's necessary to set a CLOUDFLARE_API_TOKEN…`) discarded unread.
+
+The reason is now chosen by `wranglerFailureReason`: wrangler's structured error
+(`{error:{text}}`, `{error}`, or the `[{success:false,error}]` execute envelope) first,
+then stderr, then raw stdout, then the process's own message. Stderr is still consulted —
+a genuine wrangler failure that never reaches stdout must not be swallowed to fix the
+opposite mistake.
+
+Found by running an adopter estate's own `verify:prod-schema` script against production
+for the first time. It is the one declared gate no estate pass had ever exercised, and it
+was wrong on its first run.
+
+
 ### `meta gen --baseline=adopt` — the first run a pre-manifest project can actually perform
 
 The no-manifest refusal LED with *"ONE-TIME FIX: commit

server/typescript/packages/cli/src/lib/wrangler.ts

@@ -24,8 +24,56 @@ export function buildWranglerExecuteArgs(opts: WranglerExecuteOptions): string[]
 }
 
 /**
- * Run wrangler with the given args; return stdout. Stderr is included in the
- * error message when wrangler exits non-zero. `cwd` is the directory wrangler
+ * The reason to report when wrangler exits non-zero.
+ *
+ * **`--json` puts wrangler's error on STDOUT, and warnings on stderr.** This function
+ * exists because the runner used to report stderr alone, so a live D1 gate failing for
+ * want of a `CLOUDFLARE_API_TOKEN` told the adopter its cause was
+ * `▲ [WARNING] … "unsafe" fields are experimental` — a warning, named as the reason a
+ * schema gate failed, with the real cause discarded. Found by running an estate's own
+ * `verify:prod-schema` against production for the first time.
+ *
+ * Order: the structured error wrangler wrote, then stderr, then raw stdout, then the
+ * process's own message. Stderr is still consulted — a genuine wrangler failure that
+ * never reaches stdout must not be swallowed to fix the opposite mistake.
+ */
+export function wranglerFailureReason(
+  stdout: string,
+  stderr: string,
+  fallback: string,
+): string {
+  const structured = structuredWranglerError(stdout);
+  if (structured !== undefined) return structured;
+  const err = stderr.trim();
+  if (err.length > 0) return err;
+  const out = stdout.trim();
+  if (out.length > 0) return out;
+  return fallback;
+}
+
+/** wrangler's two `--json` error shapes: `{error:{text}}` / `{error}` and the
+ *  `[{success:false,error}]` execute envelope. Anything else reads as absent. */
+function structuredWranglerError(stdout: string): string | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+  const node = Array.isArray(parsed) ? parsed[0] : parsed;
+  if (node === null || typeof node !== "object") return undefined;
+  const { error } = node as { error?: unknown };
+  if (typeof error === "string" && error.trim().length > 0) return error.trim();
+  if (error !== null && typeof error === "object") {
+    const { text } = error as { text?: unknown };
+    if (typeof text === "string" && text.trim().length > 0) return text.trim();
+  }
+  return undefined;
+}
+
+/**
+ * Run wrangler with the given args; return stdout. The failure REASON is chosen by
+ * `wranglerFailureReason` when wrangler exits non-zero. `cwd` is the directory wrangler
  * runs in (defaults to process.cwd() — caller should pass the project root).
  */
 export type WranglerRunner = (args: string[], cwd: string) => Promise<{ stdout: string; stderr: string }>;
@@ -39,8 +87,8 @@ export const defaultWranglerRunner: WranglerRunner = async (args, cwd) => {
     if (e.code === "ENOENT") {
       throw new Error(`wrangler not found on PATH; install it: 'npm i -D wrangler'`);
     }
-    const stderr = e.stderr ?? "";
-    throw new Error(`wrangler ${args.join(" ")} failed: ${stderr || e.message}`);
+    const reason = wranglerFailureReason(e.stdout ?? "", e.stderr ?? "", e.message);
+    throw new Error(`wrangler ${args.join(" ")} failed: ${reason}`);
   }
 };
 

server/typescript/packages/cli/test/unit/wrangler.test.ts

@@ -1,5 +1,5 @@
 import { test, expect, describe } from "bun:test";
-import { buildWranglerExecuteArgs } from "../../src/lib/wrangler.js";
+import { buildWranglerExecuteArgs, wranglerFailureReason } from "../../src/lib/wrangler.js";
 
 describe("buildWranglerExecuteArgs", () => {
   test("local execution with command", () => {
@@ -39,3 +39,63 @@ describe("buildWranglerExecuteArgs", () => {
   });
 });
 
+
+// ── the failure REASON: wrangler --json puts its error on STDOUT ──────────────
+//
+// Found by running an estate's own `verify:prod-schema` gate against a live D1 for
+// the first time. It failed, and the reason MetaObjects printed was:
+//
+//   failed to introspect D1 binding 'DB': wrangler d1 execute … failed:
+//     ▲ [WARNING] Processing wrangler.toml configuration:
+//       - "unsafe" fields are experimental and may change or break at any time.
+//
+// A WARNING, reported as the cause of a failure. The actual cause was on stdout,
+// where `--json` puts it: "In a non-interactive environment, it's necessary to set a
+// CLOUDFLARE_API_TOKEN environment variable". The runner read stderr and discarded
+// stdout, so every adopter whose wrangler.toml warns about anything gets that warning
+// named as the reason their schema gate failed.
+describe("wranglerFailureReason", () => {
+  const TOKEN_ERROR =
+    "In a non-interactive environment, it's necessary to set a CLOUDFLARE_API_TOKEN environment variable";
+
+  test("prefers the structured error wrangler --json writes to stdout", () => {
+    const reason = wranglerFailureReason(
+      JSON.stringify({ error: { text: TOKEN_ERROR } }),
+      '▲ [WARNING] Processing wrangler.toml configuration:\n  - "unsafe" fields are experimental.\n',
+      "Command failed with exit code 1",
+    );
+    expect(reason).toContain("CLOUDFLARE_API_TOKEN");
+    // The warning must not be presented as the cause.
+    expect(reason).not.toContain("experimental");
+  });
+
+  test("reads the array envelope shape too", () => {
+    const reason = wranglerFailureReason(
+      JSON.stringify([{ success: false, error: "no such table: Member" }]),
+      "",
+      "exit 1",
+    );
+    expect(reason).toBe("no such table: Member");
+  });
+
+  test("falls back to stderr when stdout carries no structured error", () => {
+    const reason = wranglerFailureReason("", "Authentication error [code: 10000]\n", "exit 1");
+    expect(reason).toBe("Authentication error [code: 10000]");
+  });
+
+  test("falls back to the process message when both streams are empty", () => {
+    expect(wranglerFailureReason("", "", "Command failed with exit code 1"))
+      .toBe("Command failed with exit code 1");
+  });
+
+  test("unparseable stdout does not swallow stderr", () => {
+    const reason = wranglerFailureReason("not json at all", "real stderr cause\n", "exit 1");
+    expect(reason).toBe("real stderr cause");
+  });
+
+  test("keeps stdout when it is the only thing that said anything", () => {
+    // No structured error, no stderr — the raw stdout is still better than "exit 1".
+    const reason = wranglerFailureReason("something went wrong upstream", "", "exit 1");
+    expect(reason).toContain("something went wrong upstream");
+  });
+});