devflare 1.0.0-next.7 → 1.0.0-next.71

package/dist/_chunks/workspace-CbollZBv.js

@@ -0,0 +1,518 @@
+import { i as resolveAppDirectSocketPort, r as loadWorkspaceManifest, t as assertSharedBindingIds } from "./workspace-Ds3xMjOE.js";
+import { d as resolveConfigEnvVars } from "./preview-j9Kbx4-G.js";
+import { r as loadConfig } from "./loader-BC0skbnH.js";
+import { g as normalizeR2Binding, n as getLocalKVNamespaceIdentifier, r as getSingleBrowserBindingName, t as getLocalD1DatabaseIdentifier } from "./schema-normalization-CTdiY17P.js";
+import { t as applyLocalDevVarsToConfig } from "./local-dev-vars-BFLS-HoI.js";
+import { a as cyanBold, f as logLine, g as yellow, o as dim, r as createCliTheme } from "./ui-BhCdDC2N.js";
+import { setLocalSendEmailBindings } from "../utils/send-email.js";
+import { s as resolveServiceBindings, t as discoverRoutes } from "./routes-CRXB3-iw.js";
+import { l as prepareComposedWorkerEntrypoint } from "./vite-DTz2Pbtm.js";
+import { t as bundleWorkerEntry } from "./worker-bundler-CeMqQtBQ.js";
+import { _ as createMiniflareLog, c as resolveViteIntegration, d as createRuntimeStdioForwarder, f as buildMiniflareDevConfig, g as runD1Migrations, h as resolveMainWorkerSurfacePaths, p as resolveR2PresignOrigin, t as startViteProcess, u as createBrowserShim, v as createDOBundler } from "./vite-process-BhGXJ764.js";
+import { n as bundleWorkflowEntrypointScript } from "./r2-presign-runtime-DlgH_FY8.js";
+import { t as generatedDir } from "./generated-dir-DC2kM-mt.js";
+import { dirname, resolve } from "pathe";
+import { createConsola } from "consola";
+//#region src/dev-server/workspace/merge-config.ts
+const NAMESPACE_SEPARATOR = "-";
+/** Join an app namespace to one of its worker names for the merged instance. */
+function namespacedWorkerName(appName, workerName) {
+	return `${appName}${NAMESPACE_SEPARATOR}${workerName}`;
+}
+/**
+* Prefix `name` with `${appName}/` — but only when it is one of this app's own
+* worker names. External/cross-app targets are left untouched.
+*/
+function namespaceIfLocal(name, appName, localNames) {
+	return localNames.has(name) ? namespacedWorkerName(appName, name) : name;
+}
+/** Rewrite an intra-app worker reference on a service-binding value (object or string form). */
+function rewriteServiceBindingTarget(value, appName, localNames) {
+	if (typeof value === "string") return namespaceIfLocal(value, appName, localNames);
+	if (value && typeof value === "object" && typeof value.name === "string") value.name = namespaceIfLocal(value.name, appName, localNames);
+	return value;
+}
+/**
+* Namespace one app's workers in place: rename each worker `${appName}/<name>`,
+* rewrite every intra-app reference (service bindings, `durableObjects`
+* scriptName, `outboundService`) to the new names, drop `routes`, and attach the
+* app's direct socket to its gateway (entry) worker.
+*
+* @param appName - The app namespace (must be unique across the workspace).
+* @param workers - The app's worker array (mutated). The gateway is `workers[0]`.
+* @param options - `host`/`directSocketPort` for the gateway's direct socket.
+* @returns The (same) workers plus the namespaced gateway worker name — the key
+*   for `miniflare.unsafeGetDirectURL(...)`.
+*/
+function namespaceAppWorkers(appName, workers, options) {
+	const localNames = new Set(workers.map((worker) => String(worker.name)));
+	for (const worker of workers) {
+		delete worker.routes;
+		if (worker.serviceBindings && typeof worker.serviceBindings === "object") for (const [bindingName, target] of Object.entries(worker.serviceBindings)) worker.serviceBindings[bindingName] = rewriteServiceBindingTarget(target, appName, localNames);
+		if (worker.durableObjects && typeof worker.durableObjects === "object") {
+			for (const value of Object.values(worker.durableObjects)) if (value && typeof value === "object" && typeof value.scriptName === "string") value.scriptName = namespaceIfLocal(value.scriptName, appName, localNames);
+		}
+		if (worker.outboundService !== void 0) worker.outboundService = rewriteServiceBindingTarget(worker.outboundService, appName, localNames);
+		worker.name = namespacedWorkerName(appName, String(worker.name));
+	}
+	const gatewayWorkerName = namespacedWorkerName(appName, "gateway");
+	const gatewayWorker = workers.find((worker) => worker.name === gatewayWorkerName) ?? workers[0];
+	gatewayWorker.unsafeDirectSockets = [{
+		host: options.host,
+		port: options.directSocketPort,
+		entrypoint: "default"
+	}];
+	return {
+		workers,
+		gatewayWorkerName: gatewayWorker.name
+	};
+}
+/** Compute the one persist block for the whole workspace, or `undefined` when off. */
+function resolveWorkspacePersistPaths(persist, persistDir) {
+	if (!persist) return;
+	return {
+		kvPersist: resolve(persistDir, "kv"),
+		r2Persist: resolve(persistDir, "r2"),
+		d1Persist: resolve(persistDir, "d1"),
+		cachePersist: resolve(persistDir, "cache"),
+		durableObjectsPersist: resolve(persistDir, "do"),
+		workflowsPersist: resolve(persistDir, "workflows"),
+		imagesPersist: resolve(persistDir, "images"),
+		streamPersist: resolve(persistDir, "stream")
+	};
+}
+/**
+* Assemble the final single-instance Miniflare config: one entry socket, one
+* persist dir, and the union of every app's namespaced workers (each with its
+* own direct socket).
+*
+* @param input - Apps, host, persist settings, and entry port.
+* @returns `{ config, directSockets }` where `config` is the Miniflare options
+*   object and `directSockets` maps each app name to its gateway worker name
+*   and port (for `unsafeGetDirectURL` + logging).
+* @throws When two apps share a namespace or a direct-socket port (which would
+*   collide inside the one instance).
+*/
+function buildMergedWorkspaceConfig(input) {
+	const seenAppNames = /* @__PURE__ */ new Set();
+	const seenPorts = /* @__PURE__ */ new Map();
+	const mergedWorkers = [];
+	const directSockets = [];
+	for (const app of input.apps) {
+		if (seenAppNames.has(app.appName)) throw new Error(`Duplicate workspace app namespace "${app.appName}". Give each app a unique name.`);
+		seenAppNames.add(app.appName);
+		const portOwner = seenPorts.get(app.directSocketPort);
+		if (portOwner !== void 0) throw new Error(`Workspace apps "${portOwner}" and "${app.appName}" both use port ${app.directSocketPort}. Each app needs a distinct direct-socket port.`);
+		seenPorts.set(app.directSocketPort, app.appName);
+		const { workers, gatewayWorkerName } = namespaceAppWorkers(app.appName, app.workers, {
+			host: input.host,
+			directSocketPort: app.directSocketPort
+		});
+		mergedWorkers.push(...workers);
+		directSockets.push({
+			appName: app.appName,
+			gatewayWorkerName,
+			port: app.directSocketPort
+		});
+	}
+	const seenWorkerNames = /* @__PURE__ */ new Set();
+	for (const worker of mergedWorkers) {
+		const workerName = String(worker.name);
+		if (seenWorkerNames.has(workerName)) throw new Error(`Workspace produced two workers named "${workerName}" after namespacing. Rename one of the conflicting apps so their namespaced worker names stay distinct.`);
+		seenWorkerNames.add(workerName);
+	}
+	const persistPaths = resolveWorkspacePersistPaths(input.persist, input.persistDir);
+	return {
+		config: {
+			host: input.host,
+			port: input.entryPort ?? 0,
+			...persistPaths ?? {},
+			workers: mergedWorkers
+		},
+		directSockets
+	};
+}
+//#endregion
+//#region src/dev-server/workspace/prepare-app.ts
+/**
+* Load an app's config and build its Miniflare worker set, mirroring the
+* single-app dev startup up to (but not including) `new Miniflare(...)`.
+*
+* Side effects: bundles the worker/workflow/DO entrypoints under the app's
+* `.devflare/`, and starts a browser-rendering shim when the app binds one. The
+* returned `doBundler`/`browserShim` are disposed by the coordinator.
+*
+* @param input - App identity, ports, and shared instance settings.
+* @returns The prepared app (see {@link PreparedWorkspaceApp}).
+*/
+async function prepareWorkspaceApp(input) {
+	const { appCwd, configPath, directSocketPort, host, logger } = input;
+	const config = await applyLocalDevVarsToConfig(await resolveConfigEnvVars(await loadConfig({
+		cwd: appCwd,
+		configFile: configPath
+	}), {
+		cwd: appCwd,
+		configPath,
+		mode: "dev"
+	}), {
+		cwd: appCwd,
+		configPath
+	});
+	const appName = input.appName ?? config.name;
+	const serviceBindingResolution = config.bindings?.services ? await resolveServiceBindings(config, appCwd) : null;
+	let enableVite = false;
+	let generatedViteConfigPath = null;
+	if (input.vite) {
+		const viteIntegration = await resolveViteIntegration({
+			cwd: appCwd,
+			configPath,
+			miniflarePort: directSocketPort,
+			enableViteRequested: true,
+			logger
+		});
+		enableVite = viteIntegration.enableVite;
+		generatedViteConfigPath = viteIntegration.generatedViteConfigPath;
+		if (!enableVite) logger?.warn(`Workspace app "${appName}" set vite: true but no Vite config was found; running it worker-only.`);
+	}
+	const workflowEntrypointScript = await bundleWorkflowEntrypointScript(config, appCwd, { logger });
+	const mainWorkerSurfacePaths = await resolveMainWorkerSurfacePaths(appCwd, config);
+	const mainWorkerRoutes = await discoverRoutes(appCwd, config);
+	const mainWorkerScriptPath = await prepareComposedWorkerEntrypoint(appCwd, config, void 0, { devInternalEmail: true }) ?? null;
+	let bundledMainWorkerScriptPath = null;
+	if (mainWorkerScriptPath && !enableVite) bundledMainWorkerScriptPath = await bundleWorkerEntry({
+		cwd: appCwd,
+		inputFile: mainWorkerScriptPath,
+		outFile: generatedDir(appCwd, "worker-entrypoints", "main.js"),
+		rolldownOptions: config.rolldown?.options,
+		sourcemap: config.rolldown?.sourcemap,
+		minify: config.rolldown?.minify,
+		logger
+	});
+	let doResult = null;
+	let doBundler = null;
+	const doPattern = config.files?.durableObjects;
+	if (typeof doPattern === "string" && doPattern) {
+		doBundler = createDOBundler({
+			cwd: appCwd,
+			pattern: doPattern,
+			outDir: resolve(appCwd, ".devflare", "do-bundles"),
+			rolldownOptions: config.rolldown?.options,
+			sourcemap: config.rolldown?.sourcemap,
+			minify: config.rolldown?.minify,
+			logger,
+			onRebuild: async () => {}
+		});
+		doResult = await doBundler.build();
+	}
+	let browserShim = null;
+	if (getSingleBrowserBindingName(config.bindings?.browser)) {
+		browserShim = createBrowserShim({
+			port: input.browserShimPort,
+			host: "127.0.0.1",
+			logger,
+			verbose: input.verbose
+		});
+		await browserShim.start();
+	}
+	const workers = buildMiniflareDevConfig({
+		config,
+		cwd: appCwd,
+		miniflarePort: directSocketPort,
+		miniflareHost: host,
+		persist: input.persist,
+		enableVite,
+		debug: input.debug,
+		mainWorkerSurfacePaths,
+		mainWorkerRoutes,
+		mainWorkerScriptPath,
+		bundledMainWorkerScriptPath,
+		workflowEntrypointScript,
+		browserShimPort: input.browserShimPort,
+		doResult,
+		serviceBindingResolution,
+		r2PresignSecret: input.r2PresignSecret,
+		additionalInjectedVars: input.env,
+		logger
+	}).workers;
+	const sharedIds = {
+		d1: {},
+		r2: {},
+		kv: {}
+	};
+	for (const [name, cfg] of Object.entries(config.bindings?.d1 ?? {})) sharedIds.d1[name] = getLocalD1DatabaseIdentifier(cfg);
+	for (const [name, cfg] of Object.entries(config.bindings?.r2 ?? {})) sharedIds.r2[name] = normalizeR2Binding(cfg).bucketName;
+	for (const [name, cfg] of Object.entries(config.bindings?.kv ?? {})) sharedIds.kv[name] = getLocalKVNamespaceIdentifier(cfg);
+	return {
+		appName,
+		appCwd,
+		configPath,
+		config,
+		workers,
+		directSocketPort,
+		vitePort: input.vitePort,
+		enableVite,
+		generatedViteConfigPath,
+		doBundler,
+		browserShim,
+		sendEmailBindings: config.bindings?.sendEmail ?? {},
+		sharedIds
+	};
+}
+//#endregion
+//#region src/dev-server/workspace/server.ts
+/** The first browser-shim port; each app that binds browser rendering gets `+index`. */
+const BROWSER_SHIM_BASE_PORT = 9700;
+/** Delay before running migrations, matching the single-app path's stabilization wait. */
+const MIGRATION_STABILIZE_DELAY_MS = 1e3;
+/**
+* Create a workspace dev server that co-hosts every manifest app in one
+* Miniflare instance with live-shared bindings.
+*
+* @param options - The manifest, its directory, and logging/persist settings.
+* @returns A {@link WorkspaceDevServer} handle.
+*/
+function createWorkspaceDevServer(options) {
+	const { manifest, manifestDir, logger } = options;
+	const persist = options.persist ?? true;
+	const verbose = options.verbose ?? false;
+	const debug = options.debug ?? process.env.DEVFLARE_DEBUG === "true";
+	const host = manifest.host ?? "127.0.0.1";
+	const persistDir = resolve(manifestDir, manifest.persist ?? ".devflare/workspace-data");
+	const r2PresignSecret = `${crypto.randomUUID()}${crypto.randomUUID()}`;
+	let miniflare = null;
+	let preparedApps = [];
+	const viteChildren = [];
+	const appOrigins = [];
+	/**
+	* Prepare each manifest app (sequentially — config load + bundling mutate
+	* app-local `.devflare/` dirs and we want deterministic, non-interleaved
+	* work).
+	*/
+	async function prepareAllApps() {
+		const prepared = [];
+		for (let index = 0; index < manifest.apps.length; index++) {
+			const app = manifest.apps[index];
+			const label = app.name ?? app.config;
+			const directSocketPort = resolveAppDirectSocketPort(app, label);
+			const configPath = resolve(manifestDir, app.config);
+			logger?.info(`Preparing workspace app "${label}" (port ${directSocketPort})…`);
+			prepared.push(await prepareWorkspaceApp({
+				appName: app.name,
+				configPath,
+				appCwd: dirname(configPath),
+				directSocketPort,
+				vite: app.vite ?? false,
+				vitePort: app.vitePort ?? 5173,
+				env: app.env,
+				persist,
+				debug,
+				verbose,
+				browserShimPort: BROWSER_SHIM_BASE_PORT + index,
+				r2PresignSecret,
+				host,
+				logger
+			}));
+		}
+		return prepared;
+	}
+	/** Merge sendEmail bindings from all apps and register them once (global registry). */
+	function registerSharedSendEmailBindings(apps) {
+		const merged = {};
+		for (const app of apps) Object.assign(merged, app.sendEmailBindings);
+		setLocalSendEmailBindings(merged);
+	}
+	async function startMiniflare(apps) {
+		const { Miniflare, Log, LogLevel } = await import("miniflare");
+		const { config, directSockets } = buildMergedWorkspaceConfig({
+			apps: apps.map((app) => ({
+				appName: app.appName,
+				workers: app.workers,
+				directSocketPort: app.directSocketPort
+			})),
+			host,
+			persist,
+			persistDir,
+			entryPort: manifest.entryPort
+		});
+		const log = createMiniflareLog(Log, LogLevel, "DEBUG", logger);
+		if (log) config.log = log;
+		config.handleRuntimeStdio = createRuntimeStdioForwarder(logger);
+		miniflare = new Miniflare(config);
+		await miniflare.ready;
+		for (const socket of directSockets) {
+			const url = await miniflare.unsafeGetDirectURL(socket.gatewayWorkerName);
+			const app = apps.find((candidate) => candidate.appName === socket.appName);
+			const isVite = app?.enableVite ?? false;
+			const origin = isVite ? `http://${host}:${app?.vitePort ?? socket.port}` : url.href;
+			appOrigins.push({
+				appName: socket.appName,
+				url: origin,
+				vite: isVite
+			});
+			logger?.success(isVite ? `App "${socket.appName}" → Vite ${origin} (bridge ${url.href})` : `App "${socket.appName}" → ${url.href}`);
+		}
+	}
+	/** Run each app's D1 migrations once against the shared store (ledger dedupes). */
+	async function runMigrations(apps) {
+		await new Promise((r) => setTimeout(r, MIGRATION_STABILIZE_DELAY_MS));
+		for (const app of apps) {
+			if (!app.config.bindings?.d1) continue;
+			await runD1Migrations({
+				cwd: app.appCwd,
+				config: app.config,
+				miniflarePort: app.directSocketPort,
+				logger
+			});
+		}
+	}
+	/** Spawn a Vite child per Vite app, pointed at its gateway's direct socket (bridge). */
+	async function startViteChildren(apps) {
+		for (const app of apps) {
+			if (!app.enableVite) continue;
+			const child = await startViteProcess({
+				cwd: app.appCwd,
+				configPath: app.configPath,
+				vitePort: app.vitePort,
+				miniflarePort: app.directSocketPort,
+				generatedViteConfigPath: app.generatedViteConfigPath,
+				r2Presign: app.config.bindings?.r2 ? {
+					secret: r2PresignSecret,
+					origin: resolveR2PresignOrigin(app.config.server, host, app.directSocketPort)
+				} : null,
+				logger
+			});
+			viteChildren.push(child);
+		}
+	}
+	async function start() {
+		logger?.info("Starting workspace dev server…");
+		preparedApps = await prepareAllApps();
+		if (manifest.shared) assertSharedBindingIds(manifest.shared, preparedApps.map((app) => ({
+			appLabel: app.appName,
+			d1: app.sharedIds.d1,
+			r2: app.sharedIds.r2,
+			kv: app.sharedIds.kv
+		})));
+		registerSharedSendEmailBindings(preparedApps);
+		await startMiniflare(preparedApps);
+		await startViteChildren(preparedApps);
+		await runMigrations(preparedApps);
+		logger?.success(`Workspace ready — ${preparedApps.length} app(s) sharing one instance`);
+	}
+	async function stop() {
+		for (const child of viteChildren) child.kill();
+		viteChildren.length = 0;
+		for (const app of preparedApps) {
+			try {
+				await app.doBundler?.close();
+			} catch (error) {
+				logger?.debug(`DO bundler close failed for ${app.appName}: ${String(error)}`);
+			}
+			try {
+				await app.browserShim?.stop();
+			} catch (error) {
+				logger?.debug(`Browser shim stop failed for ${app.appName}: ${String(error)}`);
+			}
+		}
+		if (miniflare) {
+			await miniflare.dispose();
+			miniflare = null;
+		}
+	}
+	return {
+		start,
+		stop,
+		getMiniflare: () => miniflare,
+		getAppOrigins: () => appOrigins
+	};
+}
+//#endregion
+//#region src/cli/commands/workspace.ts
+/**
+* Run the `workspace` command. Only the `dev` subcommand exists today; any
+* other (or missing) subcommand prints guidance and exits non-zero.
+*/
+async function runWorkspaceCommand(parsed, logger, options) {
+	const subcommand = parsed.args[0] ?? "dev";
+	if (subcommand !== "dev") {
+		logger.error(`Unknown workspace subcommand: ${subcommand}`);
+		logger.info("Usage: devflare workspace dev");
+		return { exitCode: 1 };
+	}
+	const cwd = options.cwd || parsed.options.cwd || process.cwd();
+	const configFile = parsed.options.config;
+	const persist = parsed.options["no-persist"] !== true;
+	const debugEnabled = parsed.options.debug === true || process.env.DEVFLARE_DEBUG === "true";
+	const verbose = parsed.options.verbose === true || debugEnabled;
+	const theme = createCliTheme(parsed.options);
+	const devLogger = createConsola({ level: verbose ? 4 : 3 });
+	let loaded;
+	try {
+		loaded = await loadWorkspaceManifest({
+			cwd,
+			configFile
+		});
+	} catch (error) {
+		logger.error(error instanceof Error ? error.message : String(error));
+		return { exitCode: 1 };
+	}
+	logLine(logger);
+	logLine(logger, `${cyanBold("workspace", theme)} ${dim("Shared Dev Runtime", theme)}`);
+	logLine(logger, "   ├─ One Miniflare: live-shared D1/KV/R2/Durable Objects");
+	logLine(logger, "   ├─ Per-app direct sockets: cross-origin preserved");
+	logLine(logger, `   └─ ${loaded.manifest.apps.length} app(s) from the workspace manifest`);
+	logLine(logger);
+	const devServer = createWorkspaceDevServer({
+		manifest: loaded.manifest,
+		manifestDir: loaded.manifestDir,
+		persist,
+		logger: devLogger,
+		verbose,
+		debug: debugEnabled
+	});
+	let isCleaningUp = false;
+	const cleanupHandlers = /* @__PURE__ */ new Map();
+	const removeCleanupHandlers = () => {
+		for (const [event, handler] of cleanupHandlers) process.off(event, handler);
+		cleanupHandlers.clear();
+	};
+	const cleanup = async (exitCode, reason) => {
+		if (isCleaningUp) return;
+		isCleaningUp = true;
+		removeCleanupHandlers();
+		if (reason) {
+			const message = reason instanceof Error ? reason.stack ?? reason.message : String(reason);
+			logger.error(message);
+		}
+		logLine(logger);
+		logLine(logger, `${yellow("workspace", theme)} ${dim("Shutting down…", theme)}`);
+		try {
+			await devServer.stop();
+		} finally {
+			process.exit(exitCode);
+		}
+	};
+	const registerCleanupHandler = (event, handler) => {
+		cleanupHandlers.set(event, handler);
+		process.on(event, handler);
+	};
+	registerCleanupHandler("SIGINT", () => void cleanup(0));
+	registerCleanupHandler("SIGTERM", () => void cleanup(0));
+	registerCleanupHandler("SIGHUP", () => void cleanup(0));
+	registerCleanupHandler("uncaughtException", (error) => void cleanup(1, error));
+	registerCleanupHandler("unhandledRejection", (reason) => void cleanup(1, reason));
+	try {
+		await devServer.start();
+		await new Promise(() => {});
+		return { exitCode: 0 };
+	} catch (error) {
+		if (error instanceof Error) {
+			logger.error("Workspace dev server failed:", error.message);
+			if (verbose) logger.error(error.stack);
+		}
+		await devServer.stop().catch(() => {});
+		return { exitCode: 1 };
+	}
+}
+//#endregion
+export { runWorkspaceCommand };

package/dist/_chunks/workspace-Ds3xMjOE.js

@@ -0,0 +1,175 @@
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "pathe";
+import { z } from "zod";
+//#region src/config/workspace.ts
+/**
+* Per-app entry in a workspace manifest.
+*
+* A pure worker app is reached directly on {@link WorkspaceApp.port}; a Vite app
+* is served by Vite on {@link WorkspaceApp.vitePort} and reaches its bindings
+* through the gateway bridge on {@link WorkspaceApp.bridgePort}.
+*/
+const workspaceAppSchema = z.object({
+	config: z.string().min(1),
+	name: z.string().min(1).optional(),
+	port: z.number().int().positive().max(65535).optional(),
+	vite: z.boolean().optional(),
+	vitePort: z.number().int().positive().max(65535).optional(),
+	bridgePort: z.number().int().positive().max(65535).optional(),
+	env: z.record(z.string()).optional()
+}).strict();
+const workspaceManifestSchema = z.object({
+	apps: z.array(workspaceAppSchema).min(1),
+	shared: z.object({
+		d1: z.array(z.string()).optional(),
+		r2: z.array(z.string()).optional(),
+		kv: z.array(z.string()).optional()
+	}).strict().optional(),
+	persist: z.string().min(1).optional(),
+	host: z.string().min(1).optional(),
+	entryPort: z.number().int().nonnegative().max(65535).optional()
+}).strict();
+/**
+* Type-safe helper for defining a devflare workspace manifest. Mirrors
+* {@link defineConfig}: it only attaches types and returns the value unchanged.
+*
+* @param manifest - The workspace manifest.
+* @returns The same manifest, typed.
+*
+* @example
+* // devflare.workspace.ts (repo root)
+* export default defineWorkspace({
+*   apps: [
+*     { config: './apps/api/devflare.config.ts', port: 8789, env: { DOC_API_DEV_SEED: '1' } },
+*     { config: './apps/web/devflare.config.ts', vite: true, vitePort: 5173, bridgePort: 8788 }
+*   ],
+*   shared: { d1: ['PLATFORM_DB'], r2: ['MEDIA'] }
+* })
+*/
+function defineWorkspace(manifest) {
+	return manifest;
+}
+/** Manifest file names searched at the workspace root, in priority order. */
+const WORKSPACE_MANIFEST_FILES = [
+	"devflare.workspace.ts",
+	"devflare.workspace.mts",
+	"devflare.workspace.js",
+	"devflare.workspace.mjs"
+];
+/**
+* The browser/direct-socket port a given app is reached on inside the shared
+* instance: `bridgePort` for a Vite app, `port` for a pure worker. Throws a
+* descriptive error when the required port is missing.
+*
+* @param app - A validated workspace app entry.
+* @param label - Human-readable app label for error messages.
+* @returns The direct-socket port for the app's gateway worker.
+* @throws When a Vite app omits `bridgePort` or a worker app omits `port`.
+*/
+function resolveAppDirectSocketPort(app, label) {
+	if (app.vite) {
+		if (app.bridgePort === void 0) throw new Error(`Workspace app "${label}" sets vite: true but is missing "bridgePort".`);
+		return app.bridgePort;
+	}
+	if (app.port === void 0) throw new Error(`Workspace app "${label}" is a pure worker but is missing "port".`);
+	return app.port;
+}
+/**
+* c12 resolves TypeScript/ESM manifests via jiti. Prefer the target project's
+* own `c12` install (mirrors {@link loadConfig}) so a monorepo that vendors
+* devflare per-app still transpiles the manifest; fall back to devflare's own.
+*/
+function resolveC12LoadConfig(cwd) {
+	const requireFromCwd = createRequire(join(cwd, "__devflare_workspace__.cjs"));
+	try {
+		return requireFromCwd("c12").loadConfig;
+	} catch {
+		return createRequire(import.meta.url)("c12").loadConfig;
+	}
+}
+/**
+* Load, transpile, and validate a workspace manifest.
+*
+* @param options - Search directory and optional explicit file.
+* @returns The validated manifest plus its resolved path/dir.
+* @throws {WorkspaceManifestNotFoundError} When no manifest file is found.
+* @throws {WorkspaceManifestValidationError} When the manifest fails schema validation.
+*/
+async function loadWorkspaceManifest(options = {}) {
+	const cwd = resolve(options.cwd ?? process.cwd());
+	const configFile = options.configFile ?? "devflare.workspace";
+	const explicitManifestPath = options.configFile ? resolve(cwd, options.configFile) : void 0;
+	if (!(explicitManifestPath !== void 0 && existsSync(explicitManifestPath) || WORKSPACE_MANIFEST_FILES.some((name) => existsSync(join(cwd, name))))) throw new WorkspaceManifestNotFoundError(cwd);
+	const { config, configFile: loadedFile } = await resolveC12LoadConfig(cwd)({
+		name: "devflare",
+		cwd,
+		configFile,
+		rcFile: false,
+		globalRc: false,
+		dotenv: false
+	});
+	if (!config || !loadedFile) throw new WorkspaceManifestNotFoundError(cwd);
+	const result = workspaceManifestSchema.safeParse(config);
+	if (!result.success) throw new WorkspaceManifestValidationError(result.error.issues, loadedFile);
+	return {
+		manifest: result.data,
+		manifestPath: loadedFile,
+		manifestDir: dirname(loadedFile)
+	};
+}
+/** Error thrown when no workspace manifest file is found. */
+var WorkspaceManifestNotFoundError = class extends Error {
+	code = "WORKSPACE_MANIFEST_NOT_FOUND";
+	constructor(cwd) {
+		super(`No workspace manifest found in ${cwd}.\nExpected one of: ${WORKSPACE_MANIFEST_FILES.join(", ")}\nCreate one that exports \`defineWorkspace({ apps: [...] })\`.`);
+		this.cwd = cwd;
+		this.name = "WorkspaceManifestNotFoundError";
+	}
+};
+/** Error thrown when a workspace manifest fails schema validation. */
+var WorkspaceManifestValidationError = class extends Error {
+	code = "WORKSPACE_MANIFEST_VALIDATION_ERROR";
+	constructor(issues, manifestPath) {
+		const issueMessages = issues.map((issue) => `  - ${issue.path.join(".")}: ${issue.message}`);
+		super(`Invalid workspace manifest in ${manifestPath}:\n${issueMessages.join("\n")}`);
+		this.issues = issues;
+		this.manifestPath = manifestPath;
+		this.name = "WorkspaceManifestValidationError";
+	}
+};
+/**
+* Assert that every binding name listed in `manifest.shared` resolves to the
+* SAME local identifier across the apps that declare it — otherwise the apps
+* would silently get SEPARATE stores. Sharing is by id, so a mismatch is a real
+* bug in the configs, surfaced here as a loud error rather than a subtle
+* "writes don't appear" symptom.
+*
+* @param assertions - The `shared` block from the manifest.
+* @param resolved - Per-app resolved identifiers: `{ appLabel, d1, r2, kv }`
+*   where each map is `bindingName -> localIdentifier` for that app.
+* @throws When a shared binding resolves to differing ids (or is absent everywhere).
+*/
+function assertSharedBindingIds(assertions, resolved) {
+	for (const kind of [
+		"d1",
+		"r2",
+		"kv"
+	]) for (const bindingName of assertions[kind] ?? []) {
+		const seen = [];
+		for (const app of resolved) {
+			const id = app[kind][bindingName];
+			if (id !== void 0) seen.push({
+				appLabel: app.appLabel,
+				id
+			});
+		}
+		if (seen.length === 0) throw new Error(`Workspace "shared.${kind}" lists "${bindingName}", but no app declares that ${kind.toUpperCase()} binding.`);
+		if (new Set(seen.map((entry) => entry.id)).size > 1) {
+			const detail = seen.map((entry) => `${entry.appLabel} → ${entry.id}`).join(", ");
+			throw new Error(`Workspace "shared.${kind}" binding "${bindingName}" resolves to different ids across apps (${detail}); they would NOT share a store. Align the ${kind.toUpperCase()} id in the app configs.`);
+		}
+	}
+}
+//#endregion
+export { resolveAppDirectSocketPort as i, defineWorkspace as n, loadWorkspaceManifest as r, assertSharedBindingIds as t };