[APPS-2792] Add: dev:verify mode-aware routing for local execution (build-plugins half)

[tyffical]

Motivation

• Part of APPS-2792 — local Node execution for App Builder backend functions. Milestone 3 in the Kickoff doc, build-plugins half. Stacked on the Sandboxing runtime guard ([APPS-2792] Add: runtime network/subprocess guard for local execution #484), which is itself stacked on Wiring into the dev server ([APPS-2792] Add: wire local execution into the real dev server #481) — needs the dual-endpoint split (/__dd/executeAction local, /__dd/executeActionViaCloud cloud) that [APPS-2792] Add: wire local execution into the real dev server #481 introduced.
• Today, npm run dev:verify doesn't exist — pre-publish parity checking against the real cloud/Deno round trip requires a manual curl to /__dd/executeActionViaCloud. This PR makes the dev server itself mode-aware so a real dev:verify command (added to the scaffold template in a separate web-ui PR) can route through the same /__dd/executeAction URL the frontend already calls, without the frontend needing to know which mode it's in.
• Considered and rejected: making the injected client-side transport (dev-server-transport.ts) mode-aware via import.meta.env.MODE. Verified directly against this repo's actual Jest setup (ts-jest, "module": "preserve") that import.meta has no CommonJS equivalent — introducing it breaks ts-jest's transform with SyntaxError: Cannot use 'import.meta' outside a module for any file that imports it, including the existing execute-backend-function.test.ts. Routing server-side, keyed off Vite's own resolved --mode, avoids this entirely and keeps the client transport unchanged.

Architecture

npm run dev              (--mode development, default)     npm run dev:verify        (--mode dev-verify)
         │                                                            │
         └──────────────────────┬─────────────────────────────────────┘
                                 ▼
                  Browser: executeBackendFunction()
                  → devServerTransport → POST /__dd/executeAction
                  (unchanged either way — the client never knows the mode)
                                 │
                                 ▼
                  createDevServerMiddleware's /__dd/executeAction branch
                  checks `mode` (threaded from `server.config.mode`,
                  Vite's own resolved --mode, read in configureServer)
                                 │
                  ┌──────────────┴───────────────┐
                  ▼ mode !== 'dev-verify'          ▼ mode === 'dev-verify'
          handleExecuteAction                handleExecuteActionViaCloud
          (local, in-process,                (bundle + real preview-async
           no bundling — #479/#480/#481)       round trip — unchanged, #481)

/__dd/executeActionViaCloud itself is untouched and still directly reachable — this PR only adds a second way to reach the same cloud behavior, gated by mode, at the URL the client already calls by default.

Changes

What changed	File
New DEV_VERIFY_MODE constant ('dev-verify') — the Vite --mode value dev:verify will use.	constants.ts
createDevServerMiddleware takes a new optional mode?: string parameter. When req.url === '/__dd/executeAction' and mode === DEV_VERIFY_MODE, delegates to the same cloud-execution logic /__dd/executeActionViaCloud uses (including the existing "auth not configured" 400 guard) instead of running locally.	dev-server.ts
configureServer(server) now passes server.config.mode (Vite's own resolved mode, read via the plugin API — no import.meta.env involved) through to createDevServerMiddleware.	vite/index.ts
New test: starting the middleware with mode: DEV_VERIFY_MODE and POSTing to /__dd/executeAction hits the real preview-async round trip (via nock) and never calls loadModule — confirming it takes the cloud path, not the local one, for the exact same URL the client always calls.	dev-server.test.ts

QA Instructions

yarn install

yarn test:unit packages/plugins/apps/src/vite/dev-server.test.ts
# Expected: Test Suites: 1 passed / Tests: 28 passed ✅ VERIFIED

yarn test:unit packages/plugins/apps
# Expected: Test Suites: 25 passed / Tests: 343 passed ✅ VERIFIED

yarn workspace @dd/apps-plugin run typecheck
# Expected: no output, clean exit ✅ VERIFIED

npx eslint 'packages/plugins/apps/**/*.ts' --quiet
# Expected: no output, clean exit ✅ VERIFIED

Manual QA against a real scaffolded app (invoking vite dev --mode dev-verify directly, ahead of the web-ui half's dev:verify script landing), per the Testing and QA Guide:

npx vite dev --mode dev-verify --port 5185 --strictPort
# VITE v7.3.6  dev-verify  ready in 185 ms ✅ VERIFIED (mode banner confirms it's active)
curl -X POST http://localhost:5185/__dd/executeAction -d '{"functionName":"...example","args":[99]}'
# {"success":true,"result":{"data":{"doubled":198,"tripled":297}}} ✅ VERIFIED

Confirmed it's genuinely routing to the cloud, not local in-process execution: the customer function's own console.log did not print in the local terminal (unlike the same call under default npm run dev, where it does), and the server log shows the real round trip — Bundling backend function... → Executing action via cloud... → Calling Datadog API: https://api.datad0g.com/api/v2/app-builder/queries/preview-async → Query execution started with receipt: ... → Long-poll attempt 1/10... → Long-poll response, done: true.

Blast Radius

• No behavior change for npm run dev (default mode) — mode defaults to undefined/'development', which never equals DEV_VERIFY_MODE, so the existing local-execution branch is unchanged.
• /__dd/executeActionViaCloud is untouched.
• Risk: low. Purely additive branch in the middleware; no new dependency, no client-side change, no new config surface exposed to customers (the mode comes from Vite's own --mode flag, which the web-ui template's dev:verify script will set — nothing customer-authored).

Out of Scope / Follow-ups

Item	Status	Next step
web-ui: add the dev:verify script (vite dev --mode dev-verify) and a minimal example backend function to the create-apps template	Not started	Separate PR, web-ui repo
Update onboarding docs to reference the real dev:verify command	Not started	After both halves land
Nudge/enforce dev:verify in the publish flow before datadog-apps publish	Not started	Separate follow-up, likely in the datadog-apps CLI

Documentation

• RFC: Confluence page 7012712651
• Kickoff doc: Confluence page 7025394455 — Milestone 3

[Copilot]

Pull request overview

Friend, this PR adds mode-aware cloud verification routing to the Vite development server.

Changes:

• Adds the dev-verify mode constant.
• Routes the standard execution endpoint through cloud execution in verification mode.
• Adds coverage for the new routing behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
constants.ts	Defines the verification mode.
dev-server.ts	Implements mode-aware routing.
dev-server.test.ts	Tests cloud routing in verification mode.
index.ts	Passes Vite’s resolved mode to the middleware.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[datadog-prod-us1-4]

🎉 All green!

❄️ No new flaky tests detected

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 5e15df7 | Docs | View more details | Give us feedback!}