Refactor app process metadata

cloudflare · sjoerd2025 · Aug 1, 2026 · Aug 1, 2026 · Aug 1, 2026 · Aug 1, 2026
commit ad672f333fbb7c6bb801889801d934abb85e3b61
diff --git a/apps/dev-dashboard/src/apps.mjs b/apps/dev-dashboard/src/apps.mjs
@@ -1,5 +1,10 @@
 import net from 'node:net'
 
+const WRANGLER_DEV_PROCESS = {
+	appendPort: true,
+	supportsLocalWranglerDev: true,
+}
+
 export const REQUIRED_ENV_VARS = [
 	'CLOUDFLARE_ACCOUNT_ID',
 	'CLOUDFLARE_API_TOKEN',
@@ -36,28 +41,31 @@ export const APPS = [
 		description: 'Get up-to-date reference information on Cloudflare',
 		features: ['Cloudflare docs search', 'Reference lookups'],
 		command: ['pnpm', ['--dir', 'apps/docs-ai-search', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8801,
 	},
 	{
 		name: 'workers-bindings',
 		description: 'Build Workers applications with storage, AI, and compute primitives',
 		features: ['Workers bindings guidance', 'Storage + AI primitives'],
 		command: ['pnpm', ['--dir', 'apps/workers-bindings', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8802,
 	},
 	{
 		name: 'workers-builds',
 		description: 'Get insights and manage your Cloudflare Workers Builds',
 		features: ['Build history', 'Build status and diagnostics'],
 		command: ['pnpm', ['--dir', 'apps/workers-builds', 'dev', '--']],
+		processOptions: [{ appendPort: true, strictPort: true }],
 		defaultPort: 8803,
-		portFlag: '--port',
 	},
 	{
 		name: 'workers-observability',
 		description: "Debug and inspect your application's logs and analytics",
 		features: ['Logs analytics', 'Application observability'],
 		command: ['pnpm', ['--dir', 'apps/workers-observability', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8804,
 	},
 	{
@@ -68,97 +76,111 @@ export const APPS = [
 			['pnpm', ['--dir', 'apps/sandbox-container', 'exec', 'tsx', 'container/sandbox.container.app.ts']],
 			['pnpm', ['--dir', 'apps/sandbox-container', 'exec', 'wrangler', 'dev', '--var', 'ENVIRONMENT:dev']],
 		],
+		processOptions: [{}, WRANGLER_DEV_PROCESS],
 		defaultPort: 8805,
 	},
 	{
 		name: 'browser-rendering',
 		description: 'Fetch web pages, convert to markdown, and take screenshots',
 		features: ['Web fetch', 'Screenshots and rendering'],
 		command: ['pnpm', ['--dir', 'apps/browser-rendering', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8806,
 	},
 	{
 		name: 'logpush',
 		description: 'Get quick summaries for Logpush job health',
 		features: ['Logpush health checks', 'Job summaries'],
 		command: ['pnpm', ['--dir', 'apps/logpush', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8807,
 	},
 	{
 		name: 'ai-gateway',
 		description: 'Search logs and inspect prompts/responses',
 		features: ['Prompt analytics', 'Gateway usage inspection'],
 		command: ['pnpm', ['--dir', 'apps/ai-gateway', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8808,
 	},
 	{
 		name: 'autorag',
 		description: 'Search and query account AutoRAG instances',
 		features: ['AutoRAG discovery', 'AutoRAG query tools'],
 		command: ['pnpm', ['--dir', 'apps/autorag', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8809,
 	},
 	{
 		name: 'auditlogs',
 		description: 'Query audit logs and generate review reports',
 		features: ['Audit log queries', 'Compliance report support'],
 		command: ['pnpm', ['--dir', 'apps/auditlogs', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8810,
 	},
 	{
 		name: 'dns-analytics',
 		description: 'Optimize DNS performance and debug setup issues',
 		features: ['DNS analytics', 'Performance diagnostics'],
 		command: ['pnpm', ['--dir', 'apps/dns-analytics', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8811,
 	},
 	{
 		name: 'dex-analysis',
 		description: 'Insights on critical application user experience',
 		features: ['Digital experience insights', 'Application health trends'],
 		command: ['pnpm', ['--dir', 'apps/dex-analysis', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8812,
 	},
 	{
 		name: 'cloudflare-one-casb',
 		description: 'Identify SaaS security misconfigurations',
 		features: ['CASB posture checks', 'SaaS security insights'],
 		command: ['pnpm', ['--dir', 'apps/cloudflare-one-casb', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8813,
 	},
 	{
 		name: 'radar',
 		description: 'Explore Cloudflare Radar internet insights',
 		features: ['Internet trend data', 'Radar analytics'],
 		command: ['pnpm', ['--dir', 'apps/radar', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8814,
 	},
 	{
 		name: 'cloudflare-blog',
 		description: 'Search and read Cloudflare Blog posts',
 		features: ['Blog search', 'Article retrieval'],
 		command: ['pnpm', ['--dir', 'apps/cloudflare-blog', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8815,
 	},
 	{
 		name: 'demo-day',
 		description: 'Demonstrate a minimal Cloudflare MCP server',
 		features: ['Minimal MCP example', 'Local demo workflows'],
 		command: ['pnpm', ['--dir', 'apps/demo-day', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8816,
 	},
 	{
 		name: 'graphql',
 		description: 'Cloudflare GraphQL analytics access',
 		features: ['GraphQL analytics tools', 'Query assistance'],
 		command: ['pnpm', ['--dir', 'apps/graphql', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8817,
 	},
 	{
 		name: 'stack-mcp',
 		description: 'Unified tool access across Cloudflare product domains',
 		features: ['Unified MCP surface', 'Cross-domain tools'],
 		command: ['pnpm', ['--dir', 'apps/stack-mcp', 'exec', 'wrangler', 'dev']],
+		processOptions: [WRANGLER_DEV_PROCESS],
 		defaultPort: 8818,
 	},
 ]
@@ -180,19 +202,31 @@ export function parseDotEnv(content) {
 	return output
 }
 
-export function createAppProcesses(app, port) {
+function normalizeCreateAppProcessOptions(options = {}) {
+	const { wranglerDevMode = 'default', ...unexpected } = options
+	const unexpectedKeys = Object.keys(unexpected)
+	if (unexpectedKeys.length > 0) {
+		throw new TypeError(`Unsupported createAppProcesses options: ${unexpectedKeys.join(', ')}`)
+	}
+	if (!['default', 'local'].includes(wranglerDevMode)) {
+		throw new TypeError(`Unsupported wranglerDevMode: ${wranglerDevMode}`)
+	}
+	return { wranglerDevMode }
+}
+
+export function createAppProcesses(app, port, options = {}) {
+	const { wranglerDevMode } = normalizeCreateAppProcessOptions(options)
 	const commands = app.multiCommand ?? [app.command]
 	return commands.map((entry, index) => {
 		const [command, args] = entry
 		const baseArgs = [...args]
-		if (command === 'pnpm') {
-			if (app.name === 'workers-builds') {
-				baseArgs.push('--port', String(port), '--strictPort')
-			} else if (app.name === 'sandbox-container') {
-				if (index === 1) baseArgs.push('--port', String(port))
-			} else {
-				baseArgs.push('--port', String(port))
-			}
+		const processOptions = app.processOptions?.[index] ?? {}
+		if (command === 'pnpm' && processOptions.appendPort) {
+			baseArgs.push('--port', String(port))
+			if (processOptions.strictPort) baseArgs.push('--strictPort')
+		}
+		if (processOptions.supportsLocalWranglerDev && wranglerDevMode === 'local') {
+			baseArgs.push('--local')
 		}
 		return [command, baseArgs]
 	})

diff --git a/apps/dev-dashboard/src/apps.test.mjs b/apps/dev-dashboard/src/apps.test.mjs
@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict'
 import { describe, it } from 'node:test'
 
-import { assignPorts, parseDotEnv } from './apps.mjs'
+import { assignPorts, createAppProcesses, parseDotEnv } from './apps.mjs'
 
 describe('assignPorts', () => {
 	it('allocates unique ports and bumps occupied ports', async () => {
@@ -25,3 +25,40 @@ describe('parseDotEnv', () => {
 		assert.deepEqual(env, { A: '1', B: 'two', C: 'three' })
 	})
 })
+
+describe('createAppProcesses', () => {
+	it('uses per-process metadata for port and local wrangler args', () => {
+		const app = {
+			name: 'sandbox-container',
+			multiCommand: [
+				['pnpm', ['--dir', 'apps/sandbox-container', 'exec', 'tsx', 'container/sandbox.container.app.ts']],
+				['pnpm', ['--dir', 'apps/sandbox-container', 'exec', 'wrangler', 'dev', '--var', 'ENVIRONMENT:dev']],
+			],
+			processOptions: [{}, { appendPort: true, supportsLocalWranglerDev: true }],
+		}
+
+		assert.deepEqual(createAppProcesses(app, 8805, { wranglerDevMode: 'local' }), [
+			['pnpm', ['--dir', 'apps/sandbox-container', 'exec', 'tsx', 'container/sandbox.container.app.ts']],
+			['pnpm', ['--dir', 'apps/sandbox-container', 'exec', 'wrangler', 'dev', '--var', 'ENVIRONMENT:dev', '--port', '8805', '--local']],
+		])
+	})
+
+	it('supports strict port injection without wrangler-local args', () => {
+		const app = {
+			name: 'workers-builds',
+			command: ['pnpm', ['--dir', 'apps/workers-builds', 'dev', '--']],
+			processOptions: [{ appendPort: true, strictPort: true }],
+		}
+
+		assert.deepEqual(createAppProcesses(app, 8803, { wranglerDevMode: 'local' }), [
+			['pnpm', ['--dir', 'apps/workers-builds', 'dev', '--', '--port', '8803', '--strictPort']],
+		])
+	})
+
+	it('rejects unsupported options', () => {
+		assert.throws(() => createAppProcesses({ command: ['pnpm', []] }, 8801, { useMiniflare: true }), {
+			name: 'TypeError',
+			message: 'Unsupported createAppProcesses options: useMiniflare',
+		})
+	})
+})
diff --git a/scripts/dev-manager.mjs b/scripts/dev-manager.mjs
@@ -284,7 +284,7 @@ async function startApp(app) {
 	const state = states.get(app.name)
 	if (state) states.set(app.name, { ...state, status: 'starting' })
 
-	const commands = createAppProcesses(app, app.port)
+	const commands = createAppProcesses(app, app.port, { wranglerDevMode: 'local' })
 	const children = commands.map(([command, commandArgs], index) => spawnProcess(app.name, command, commandArgs, index))
 	appChildren.set(app.name, children)
 }