[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, the npm run dev:verify CLI milestone described in the Kickoff doc.
• Gap this PR closes:
  • npm run dev:verify doesn't exist yet — pre-publish parity checking against the real cloud round trip currently requires manually curling /__dd/executeActionViaCloud.
  • This PR makes the dev server mode-aware so dev:verify (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.
• Rejected alternative: making the client-side transport (dev-server-transport.ts) mode-aware via import.meta.env.MODE.
  • Rejected because this repo's Jest setup (ts-jest) has no CommonJS equivalent for import.meta — introducing it breaks the transform for any file that imports it.
  • Routing server-side, keyed off Vite's own resolved --mode, avoids this 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, no bundling)    (bundle + real preview-async
                                                round trip — unchanged)

• /__dd/executeActionViaCloud remains directly reachable — this only adds a second way to reach the same cloud behavior, gated by mode, at the URL the client already calls by default.

Changes

9 changes across 6 files

What changed	File
New DEV_VERIFY_MODE constant ('dev-verify'), the Vite --mode value dev:verify will use.	constants.ts
createDevServerMiddleware takes a new required mode: string parameter (no default — index.ts always passes server.config.mode), computing isDevVerifyMode once above the returned request handler instead of re-comparing mode on every request.	dev-server.ts
Extracted routeToCloudHandler so both cloud-bound routes share one auth/error path.	dev-server.ts
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) 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: mode: DEV_VERIFY_MODE routes /__dd/executeAction through the real preview-async round trip (via nock) and never calls loadModule.	dev-server.test.ts
New configureServer-level test: confirms the cloud path is taken through the real plugin wiring, not just the middleware in isolation, when config.mode is DEV_VERIFY_MODE.	index.test.ts
Collapsed 17 near-identical createDevServerMiddleware(...) call sites into one createTestMiddleware() factory taking only the overrides each test actually varies.	dev-server.test.ts
The 6 real-end-to-end createDevServerMiddleware call sites now pass an explicit 'development' mode, since it's the one test file that exercises the plugin through real Vite build config rather than the createTestMiddleware factory above.	dev-server.integration.test.ts

QA Instructions

yarn install

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

yarn test:unit
# Expected: Test Suites: 88 passed / Tests: 2163 passed, 2 skipped ✅ 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).
• 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 is required with no code-level default, but index.ts always passes server.config.mode, Vite's own resolved mode, which itself defaults to 'development' when Vite doesn't otherwise set it. Either way it 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.

Out of Scope / Follow-ups

3 items deferred

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	In progress	ddoghq/web-ui#4501
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 — npm run dev:verify CLI
• QA guide: Confluence page 7100498075 — exact local/staging QA commands for this repo

[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 CI checks and tests passed.

🎉 All green!

🧪 All tests passed
❄️ No new flaky tests detected

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

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-03T23:47:19.200591Z	62610ab	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[tyffical]

@codex review
@copilot review

[Copilot]

🟢 Approval recommended

The routing is correctly wired, existing behavior is preserved, and both middleware and integration paths are covered.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 👍

Reviewed commit: ec1d455425

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[tyffical]

@codex review
@copilot review

[Copilot]

🔵 Needs a closer look

The middleware’s mode remains optional, allowing callers to silently bypass mode-aware routing.

Review details

Suppressed comments (1)

packages/plugins/apps/src/vite/dev-server.ts:589

• The default initializer still makes mode optional at TypeScript call sites, so an omitted value silently selects local execution even though routing now depends on this argument. Make mode required as described and have the test helper pass an explicit 'development' value when no override is supplied.

    mode: string = 'development',

• Files reviewed: 6/6 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: 62610ab477

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[tyffical]

/merge

[gh-worker-devflow-routing-ef8351]

View all feedbacks in Devflow UI.

2026-09-09 13:04:43 UTC ℹ️ Start processing command /merge

---

2026-09-09 13:04:48 UTC ℹ️ MergeQueue: pull request added to the queue

The expected merge time in master is approximately 2m (p90).

---

2026-09-09 13:06:24 UTC ℹ️ MergeQueue: This merge request was merged