feat(engine): support structured delegated output (#184)

## What

`maySpawn` currently forces human mode and rejects `--json`. That means
`create-prisma` has to capture Composer's decorated output and regex a
`.prisma.build` URL out of it.

This change lets delegated commands use the engine's normal
structured-output contract:

- human/TTY mode is unchanged: the child inherits the terminal
- JSON or non-TTY mode keeps stdin inherited but pipes both child output
streams to diagnostic stderr
- stdout remains framed NDJSON with exactly one terminal result
- a non-zero child status keeps its verbatim process exit code and emits
`CLI.CHILD_PROCESS_FAILED` with `{ exitCode, signal }` in `error.meta`
- signal-killed children still drop reproduce guidance

The pinned Composer family already presents deploy success as:

```json
{
  "summary": {
    "app": "...",
    "nodes": [
      { "address": "https://....prisma.build", "entities": [] }
    ]
  }
}
```

With this change that result reaches a piped caller directly. A
follow-up in `create-prisma` can parse the terminal frame and stop
regexing human logs; it can also keep captured diagnostic logs hidden
behind its deployment spinner and reveal them only on failure.

## Verification

- `pnpm lint`
- `pnpm -r --if-present typecheck`
- `pnpm --filter @prisma/cli-engine exec vitest run --exclude
tests/clack-prompts.test.ts` — 795 passed
- `pnpm --filter @prisma/cli test` — 942 passed, 1 skipped
- focused fake-child, real-child, shipped spawn-adapter, telemetry, and
bin tests — 93 passed, 1 skipped
- built CLI smoke test: `prisma composer deploy module.ts --json`
accepts structured mode and emits a `composer.deploy` result frame

`packages/cli-engine/tests/clack-prompts.test.ts` has one unrelated
interactive prompt test that times out locally on current main as well;
none of the changed code is in that path.

---------

Signed-off-by: Aman Varshney <amanvarshney.work@gmail.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
Co-authored-by: willbot <w.a.madden+machine@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

.drive/projects/prisma-cli-v8/assets/engine/engine-interface-draft.ts

@@ -33,11 +33,13 @@
  * Amended 2026-08-11 for S3 (the TERMINAL HANDOFF, contract
  * s3-composer.md): §4 gains ctx.spawn and §4c its shapes +
  * exitWithChildStatus; §6 gains the SpawnDeclarations (maySpawn) and
- * the two kind amendments (a maySpawn command rejects --json as soon
- * as the command is known — after routing, before the needs check and
- * before anything runs; a session settles non-zero through
+ * the two kind amendments (a maySpawn command owns structured stdout
+ * while routing child output to diagnostics in json mode; a session settles non-zero through
  * exitWithChildStatus and no other way); §10 gains Runtime.spawn. D1
  * rulings: abort-ladder grace 5s; near-expiry refusal threshold 5min.
+ * Amended 2026-08-14: maySpawn commands now support json. Human mode
+ * still delegates the terminal; json mode routes child output to
+ * diagnostic stderr and preserves framed stdout through settlement.
  * Re-amended after the PR-136 review round: handing credentials to the
  * child is a PRECONDITION, `needs: { credentials: 'child' }` — the
  * separate credentialsForSpawn declaration is gone, and the entailment
@@ -1117,19 +1119,14 @@ export type Handler<
  * S3: the terminal-handoff declaration, accepted by defineCommand and
  * defineSessionCommand and normalized onto every definition (server
  * commands normalize maySpawn to false: they own stdio already).
- * `maySpawn` unlocks ctx.spawn and makes the command reject `--json`
- * as soon as the command is known — after routing, before the needs
- * check and before anything runs (the rule depends on which command
- * was selected, so "parse time" was loose wording) — exit 2, stated
- * in help (delegated terminal output cannot be framed). Handing
+ * `maySpawn` unlocks ctx.spawn. Human mode hands over the terminal;
+ * json mode routes the child's stdout and stderr to diagnostics while
+ * the engine retains framed stdout and emits a terminal result. Handing
  * credentials to the child is a PRECONDITION, not a declaration:
  * `needs: { credentials: 'child' }` (see NeedsSpec).
- * Naming note (PR-136 review, considered and rejected): renaming
- * maySpawn to delegatesTerminal would state the --json rule's premise
- * directly, but the identifier is already woven through the S3 stack
- * (D2/D3 handlers, tests, this draft) and the rename's churn was
- * judged to outweigh the clarity gain. Do not re-open without new
- * evidence.
+ * Naming note (PR-136 review): `maySpawn` remains the capability name;
+ * structured mode no longer delegates stdout, so `delegatesTerminal`
+ * would now be actively misleading.
  */
 export interface SpawnDeclarations {
   readonly maySpawn?: boolean

.drive/projects/prisma-cli-v8/assets/s2/parity-divergences-s3.md

@@ -95,24 +95,18 @@ instead. Three things change for the user:
   handler asked for. Legacy collapsed a signalled child's status
   (`run-alchemy.ts:61`) and printed the hint anyway.
 
-## `--json` is refused on `deploy`, `destroy` and `dev`; `log` gains it
-
-No composer command had a json mode at all. The engine gives every
-command one, and these three give it back: they hand the terminal to a
-child process whose output cannot be framed, so `--json` (and
-`--format json`) is rejected **at parse time**, before the command does
-any work — `CLI.JSON_UNSUPPORTED`, exit 2, with the reason stated in the
-command's own help ("This command hands the terminal to another program
-and does not support --json.").
-
-`log` never spawns and keeps json: its lines are its payload. So a
-composer user gains a machine-readable `log` and gains an explicit,
-early refusal on the other three, where before there was no flag to
-pass.
-
-Note the interaction with format auto-selection: a piped
-`prisma composer deploy <entry>` does not silently become a json run —
-it stays human, because json is refused rather than auto-selected.
+## `deploy`, `destroy`, `dev`, and `log` support structured output
+
+Amended 2026-08-14: `maySpawn` no longer disables JSON. In human mode the
+child still inherits the terminal. In JSON mode its stdout and stderr are
+routed to diagnostic stderr while the engine retains framed NDJSON stdout and
+emits the command family's terminal result. A failed child keeps its verbatim
+process exit code and emits `CLI.CHILD_PROCESS_FAILED` with the child status in
+`error.meta`.
+
+This also restores normal format auto-selection: a piped
+`prisma composer deploy <entry>` produces structured output, including
+Composer's deployment summary, without requiring an explicit flag.
 
 ## Usage, parse errors and bare invocation
 

.drive/projects/prisma-cli-v8/specs/s3-composer.md

@@ -100,8 +100,9 @@ const child = await ctx.spawn({ command, args, cwd, env });
   through this path (it used to hard-code 0, and now also settles
   130/143 on its own — below),
   and the session-kind "always supports json" guarantee is amended:
-  a command that may spawn rejects `--json` at PARSE time
-  (delegated terminal output cannot be framed; stated in help).
+  a command that may spawn keeps stdout framed in JSON mode by routing the
+  child's output to diagnostic stderr; the session then emits its normal
+  terminal result frame.
 - **Exit codes are the engine's** (operator ruling, 2026-08-11): a
   run a delivered signal terminated settles 128+signal from the
   ENGINE's own record of that signal, for both command kinds and

docs/product/output-conventions.md

@@ -29,6 +29,23 @@ Rules:
 - never write decorative or human-only output to stdout
 - when `--json` is active, stdout must contain only structured output
 
+### Delegated child processes
+
+Commands that declare `maySpawn` use the same format rules as every other
+command:
+
+- in human mode, the child inherits stdin, stdout, and stderr
+- in JSON mode, stdin remains inherited while the child's stdout and stderr
+  are routed to the CLI's diagnostic stderr stream
+- JSON stdout remains an NDJSON event stream with exactly one terminal result
+  frame
+- a non-zero child status is preserved as the process exit code and is
+  represented by `CLI.CHILD_PROCESS_FAILED`, with `exitCode` and `signal` in
+  `error.meta`
+
+This lets automation consume a command family's structured result without
+having to parse the delegated tool's human output.
+
 ## TTY and Piped Behavior
 
 Interactive TTY behavior:

packages/cli-engine/src/commands.ts

@@ -123,10 +123,9 @@ function normalizeArgs<
  * The terminal-handoff declaration, normalized onto every definition
  * (server commands normalize to false: they own stdio already).
  *
- * `maySpawn` unlocks ctx.spawn and makes the command reject `--json`
- * as soon as the command is known, before anything runs: output
- * delegated to a child process cannot be framed. Handing credentials
- * to the child is a precondition, declared as
+ * `maySpawn` unlocks ctx.spawn. In human mode the child inherits the
+ * terminal; in json mode its output is routed to diagnostics so stdout
+ * remains framed. Handing credentials to the child is a precondition, declared as
  * `needs: { credentials: "child" }`.
  */
 export interface SpawnDeclarations {
@@ -297,10 +296,9 @@ export function defineCommand<
  * speaks entirely through events, returns Result<void>. No
  * presentation, no exit-code set.
  *
- * A session supports json mode — the event stream is its json surface —
- * UNLESS it declares `maySpawn`, in which case it rejects --json as soon
- * as the command is known, before anything runs (S3): output delegated
- * to a child process cannot be framed. A session that returns
+ * A session supports json mode — the event stream is its json surface.
+ * When it declares `maySpawn`, child output is routed to diagnostics while
+ * the engine retains ownership of structured stdout. A session that returns
  * ok(undefined) exits 0 — or 130/143 when a signal ended the run, which
  * the engine settles from its own record of that signal, not from
  * anything the handler returns; one that returns

packages/cli-engine/src/execution/engine.ts

@@ -15,7 +15,7 @@ import type { ActiveCredential } from "../credential-manager";
 import type { EngineEvent, Severity, StreamEvent } from "../events";
 import type { ManagementApiClient } from "../management-api";
 import type { Format, PresentedResult } from "../presentation";
-import { CliStructuredError, type Result } from "../protocol";
+import type { CliStructuredError, Result } from "../protocol";
 import type { EngineCommandSnapshot, RunSummary } from "../run-summary";
 import type { InputStream, Runtime } from "../runtime";
 import {
@@ -45,11 +45,7 @@ import {
   renderHelp,
 } from "./help";
 import { checkNeeds, type NeedsOutcome } from "./needs";
-import {
-  configFlagGivenNoValue,
-  formatFlagGiven,
-  versionFlagGiven,
-} from "./pre-parse-argv";
+import { configFlagGivenNoValue, versionFlagGiven } from "./pre-parse-argv";
 import {
   commandSegments,
   settleBug,
@@ -520,10 +516,8 @@ export class EngineImpl implements Engine {
     }
   }
 
-  /** The refusals a maySpawn command can hit before anything runs: a
-   *  child's terminal output cannot be framed as a json stream, and a
-   *  host that mounts the command without a spawn adapter is
-   *  misconfigured. Returns whether the run was settled here. */
+  /** A host that mounts a maySpawn command without a spawn adapter is
+   *  misconfigured. Refuse before needs or handler side effects. */
   private refuseUnspawnable(
     invocation: Invocation,
     entry: CommandTreeEntry,
@@ -532,11 +526,6 @@ export class EngineImpl implements Engine {
     if (!entry.def.maySpawn) {
       return false;
     }
-    if (formatFlagGiven(state.argv) === "json") {
-      state.format = "human";
-      settleErrored(invocation, jsonUnsupportedError(entry.id));
-      return true;
-    }
     if (invocation.runtime.spawn === undefined) {
       // The run is doomed, and refuses here, before the needs check,
       // rather than mid-handler after side effects.
@@ -632,9 +621,6 @@ export class EngineImpl implements Engine {
     let needsOutcome: NeedsOutcome;
     try {
       applySharedFlags(state, rawFlags as SharedFlags, invocation.runtime);
-      if (entry.def.maySpawn) {
-        state.format = "human";
-      }
       needsOutcome = await checkNeeds(entry.def, invocation);
     } catch (cause) {
       // The child preflight can be awaiting the token endpoint when the
@@ -794,25 +780,6 @@ function declaredConfigSections(spec: EngineSpec): readonly string[] {
   ];
 }
 
-/** A command that may hand the terminal to a child cannot frame its
- *  output, so json is refused as soon as the command is known — before
- *  the needs check and before anything runs. */
-function jsonUnsupportedError(commandId: string): CliStructuredError {
-  return new CliStructuredError(
-    "CLI.JSON_UNSUPPORTED",
-    `The '${commandId.replaceAll(".", " ")}' command does not support json output.`,
-    {
-      why: "It hands the terminal to another program, whose output cannot be framed as a json stream.",
-      nextActions: [
-        {
-          kind: "user-choice",
-          label: "Run it without --json or --format json.",
-        },
-      ],
-    },
-  );
-}
-
 function declaredCapabilities(def: AnyCommand): CommandCapabilities {
   if (def.kind !== "result-command") {
     return { managesCredentials: false, installsPackages: false };

packages/cli-engine/src/execution/help.ts

@@ -17,7 +17,7 @@ import type { CommandTreeEntry, CommandTreeNode } from "./command-tree";
 import type { EngineSpec } from "./engine";
 import { makePaint, type Paint, textWidth } from "./palette";
 import { SHARED_ALIASES, SHARED_FLAG_PARAMETERS } from "./shared-flags";
-import { NO_JSON_NOTE, resolveExample } from "./stricli-adapter";
+import { resolveExample } from "./stricli-adapter";
 
 const RAIL = "│";
 const GAP = "  ";
@@ -487,13 +487,6 @@ function renderLeafHelp(
     lines.push(rail(paint));
     proseLines(def.help.description, paint, lines);
   }
-  if (def.maySpawn) {
-    lines.push(rail(paint));
-    // One line on purpose: the sentence is the contract several tests
-    // and consumers grep for, so it never wraps.
-    lines.push(rail(paint, paint("muted", NO_JSON_NOTE)));
-  }
-
   const positionalEntries = Object.values<PositionalSpec<unknown>>(
     def.args.positionals,
   ).map((spec) => positionalRuntime(spec));

packages/cli-engine/src/execution/reporting.ts

@@ -44,10 +44,12 @@ export function reportEvent(invocation: Invocation, event: EngineEvent): void {
     reportAfterResolution(invocation);
     return;
   }
-  // No engine write may interleave with a delegated terminal's child
-  // output; the buffer is flushed in order when the child ends.
+  // In human mode the child owns the terminal, so no engine write may
+  // interleave with its output; the buffer is flushed in order when the
+  // child ends. In json mode the engine keeps stdout (the child is
+  // routed to diagnostic stderr), so frames stream live.
   const terminal = state.delegatedTerminal;
-  if (terminal !== undefined) {
+  if (terminal !== undefined && state.format !== "json") {
     if (terminal.buffered.length >= SPAWN_COMMENTARY_BUFFER_CAP) {
       terminal.dropped += 1;
       return;

packages/cli-engine/src/execution/settlement.ts

@@ -211,9 +211,8 @@ export function settleVerbatimExitCode(
  * The status comes from the engine's own record of the child, never
  * from the handler, so there is nothing here for a handler to state.
  * Two conditions fence it, both construction errors: the command must
- * hand the terminal to another program — reachable from a
- * non-declaring handler this would also end a json stream without its
- * terminal result frame — and a child must actually have run.
+ * declare that it can hand execution to another program, and a child must
+ * actually have run.
  *
  * A signal-killed child overrules whatever the handler asked for. The
  * user stopped the run: it settles 128 + the signal number, with no
@@ -235,15 +234,63 @@ export function settleChildStatus(
       `@prisma/cli-engine: command '${invocation.state.commandId}' returned exitWithChildStatus without a child having run — that settlement reports the status of a child ctx.spawn started, and this run started none`,
     );
   }
-  // Only human format is reachable here: maySpawn forces it.
+  const exitCode = childExitCode(child);
+  if (invocation.state.format === "json") {
+    settleStructuredChildStatus(invocation, settlement, child, exitCode);
+    return;
+  }
   if (child.signal === null) {
     for (const action of settlement.nextActions) {
       invocation.runtime.stderr.write(
         `${renderNextAction(action, makePaint(invocation.state.colorEnabled))}\n`,
       );
     }
   }
-  settleVerbatimExitCode(invocation, childExitCode(child));
+  settleVerbatimExitCode(invocation, exitCode);
+}
+
+function settleStructuredChildStatus(
+  invocation: Invocation,
+  settlement: ChildStatusSettlement,
+  child: { readonly exitCode: number | null; readonly signal: string | null },
+  exitCode: number,
+): void {
+  settleVerbatimExitCode(invocation, exitCode);
+  const nextActions = child.signal === null ? settlement.nextActions : [];
+  if (exitCode === 0) {
+    const envelope: CompletedEnvelope = {
+      ok: true,
+      commandId: invocation.state.commandId,
+      result: null,
+      exitCode,
+      diagnostics: [],
+      nextActions,
+    };
+    emitFrame(invocation, {
+      kind: "result",
+      envelope,
+      commandId: invocation.state.commandId,
+      timestamp: invocation.now().toISOString(),
+    });
+    return;
+  }
+  const how =
+    child.signal === null
+      ? `exited with code ${String(child.exitCode ?? "unknown")}`
+      : `was terminated by ${child.signal}`;
+  emitErrored(invocation, {
+    ok: false,
+    commandId: invocation.state.commandId,
+    error: {
+      code: "CLI.CHILD_PROCESS_FAILED",
+      severity: "error",
+      summary: `The delegated process ${how}.`,
+      nextActions,
+      meta: { exitCode: child.exitCode, signal: child.signal },
+    },
+    diagnostics: [],
+    nextActions,
+  });
 }
 
 /** A session command that returned ok shut down cleanly: no

packages/cli-engine/src/execution/spawn.ts

@@ -138,6 +138,7 @@ async function runDelegated(
       args: options.args ?? [],
       cwd: options.cwd ?? invocation.runtime.cwd,
       env: await composeChildEnv(invocation, def, options.env),
+      output: state.format === "json" ? "diagnostic" : "inherit",
     };
     debug(
       `spawn: ${request.command} ${request.args.join(" ")} (cwd ${request.cwd})`,