syncorejs 0.2.2 → 0.2.4

package/dist/_vendor/core/cli.mjs

@@ -4,7 +4,8 @@ import { SyncoreRuntime } from "./runtime/runtime.mjs";
 import { createDevtoolsCommandHandler, createDevtoolsSubscriptionHost } from "./runtime/devtools.mjs";
 import { src_exports } from "./index.mjs";
 import { generateDevtoolsToken, isAllowedDashboardOrigin, isAuthorizedDashboardRequest, sanitizeDevtoolsToken } from "./devtools-auth.mjs";
-import { appendFile, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, open, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { createServer } from "node:http";
 import { connect } from "node:net";
 import path from "node:path";
@@ -16,9 +17,10 @@ import WebSocket, { WebSocketServer } from "ws";
 import { SYNCORE_DEVTOOLS_MAX_SUPPORTED_PROTOCOL_VERSION, SYNCORE_DEVTOOLS_MIN_SUPPORTED_PROTOCOL_VERSION, SYNCORE_DEVTOOLS_PROTOCOL_VERSION, createPublicRuntimeId, createPublicTargetId } from "../devtools-protocol/index.js";
 //#region src/cli.ts
 function templateUsesConnectedClients(template) {
-	return template === "react-web" || template === "expo" || template === "next";
+	return template === "react-web" || template === "svelte" || template === "expo" || template === "next";
 }
-const COMBINED_DEV_COMMAND = "concurrently --kill-others-on-fail --names syncore,app --prefix-colors yellow,cyan \"bun run syncorejs:dev\" \"bun run dev:app\"";
+const loadedTypeScriptModules = /* @__PURE__ */ new Map();
+const COMBINED_DEV_COMMAND = "concurrently --kill-others-on-fail --names syncore,app --prefix-colors yellow,cyan \"npm run syncorejs:dev\" \"npm run dev:app\"";
 const program = new Command();
 const CORE_PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const DEVTOOLS_SESSION_FILE = path.join(".syncore", "devtools-session.json");
@@ -27,6 +29,7 @@ const VALID_SYNCORE_TEMPLATES = [
 	"minimal",
 	"node",
 	"react-web",
+	"svelte",
 	"expo",
 	"electron",
 	"next"
@@ -34,6 +37,9 @@ const VALID_SYNCORE_TEMPLATES = [
 let pendingDevBootstrap;
 let devBootstrapInFlight = false;
 const PROJECT_TARGET_RUNTIME_ID = "syncore-project-target";
+const STORAGE_ACCESS_TICKET_TTL_MS = 300 * 1e3;
+const STORAGE_ACCESS_CHUNK_BYTES = 1024 * 1024;
+const STORAGE_ACCESS_MAX_PREVIEW_BYTES = 8e4;
 program.name("syncorejs").description("Syncore local-first toolkit CLI").version("0.1.0");
 program.command("init").description("Scaffold Syncore in the current directory").option("--template <template>", `Template to scaffold (${VALID_SYNCORE_TEMPLATES.join(", ")}, or auto)`, "auto").option("--force", "Overwrite Syncore-managed files when they already exist").action(async (options) => {
 	const cwd = process.cwd();
@@ -131,7 +137,7 @@ async function runCodegen(cwd) {
 	const componentsManifestPath = path.join(cwd, "syncore", "components.ts");
 	await mkdir(generatedDir, { recursive: true });
 	const functionImportExtension = await resolveFunctionImportExtension(cwd);
-	const hasComponentsManifest = await fileExists(componentsManifestPath);
+	const hasComponentsManifest = await hasNonEmptyComponentsManifest(componentsManifestPath);
 	const files = await listTypeScriptFiles(functionsDir);
 	const functionEntries = [];
 	for (const file of files) {
@@ -246,6 +252,24 @@ async function runCodegen(cwd) {
 		`export default resolvedComponents;`,
 		``
 	].join("\n");
+	const runtimeSource = [
+		`/**`,
+		` * Generated local runtime bundle for Syncore CLI and Node adapters.`,
+		` *`,
+		` * THIS CODE IS AUTOMATICALLY GENERATED.`,
+		` *`,
+		` * To regenerate, run \`npx syncorejs dev\` or \`npx syncorejs codegen\`.`,
+		` * @module`,
+		` */`,
+		``,
+		`import schema from "./schema${functionImportExtension}";`,
+		`import { functions } from "./functions${functionImportExtension}";`,
+		...hasComponentsManifest ? [`import { resolvedComponents } from "./components${functionImportExtension}";`] : [`const resolvedComponents = [] as const;`],
+		``,
+		`export { functions, schema };`,
+		`export const components = resolvedComponents;`,
+		``
+	].join("\n");
 	const serverSource = [
 		`/**`,
 		` * Generated utilities for implementing Syncore query, mutation, and action functions.`,
@@ -341,11 +365,18 @@ async function runCodegen(cwd) {
 		`};`,
 		``
 	].join("\n");
-	await writeFile(path.join(generatedDir, "api.ts"), apiSource);
-	await writeFile(path.join(generatedDir, "components.ts"), componentsSource);
-	await writeFile(path.join(generatedDir, "functions.ts"), functionsSource);
-	await writeFile(path.join(generatedDir, "schema.ts"), schemaSource);
-	await writeFile(path.join(generatedDir, "server.ts"), serverSource);
+	await writeGeneratedFile(path.join(generatedDir, "api.ts"), apiSource);
+	await writeGeneratedFile(path.join(generatedDir, "components.ts"), componentsSource);
+	await writeGeneratedFile(path.join(generatedDir, "functions.ts"), functionsSource);
+	await writeGeneratedFile(path.join(generatedDir, "runtime.ts"), runtimeSource);
+	await writeGeneratedFile(path.join(generatedDir, "schema.ts"), schemaSource);
+	await writeGeneratedFile(path.join(generatedDir, "server.ts"), serverSource);
+}
+async function writeGeneratedFile(filePath, source) {
+	try {
+		if (await readFile(filePath, "utf8") === source) return;
+	} catch {}
+	await writeFile(filePath, source);
 }
 async function scaffoldProject(cwd, options) {
 	const files = buildTemplateFiles(options.template);
@@ -423,16 +454,12 @@ export const create = mutation({
 
 import { createBrowserWorkerRuntime } from "syncorejs/browser";
 import schema from "../syncore/_generated/schema";
-import { resolvedComponents } from "../syncore/_generated/components";
 import { functions } from "../syncore/_generated/functions";
 
 void createBrowserWorkerRuntime({
   endpoint: self,
   schema,
-  functions,
-  components: resolvedComponents,
-  databaseName: "syncore-app",
-  persistenceMode: "opfs"
+  functions
 });
 `
 			}, {
@@ -455,15 +482,11 @@ export function AppSyncoreProvider({ children }: { children: ReactNode }) {
 				path: path.join("lib", "syncore.ts"),
 				content: `import { createExpoSyncoreBootstrap } from "syncorejs/expo";
 import schema from "../syncore/_generated/schema";
-import { resolvedComponents } from "../syncore/_generated/components";
 import { functions } from "../syncore/_generated/functions";
 
 export const syncore = createExpoSyncoreBootstrap({
   schema,
-  functions,
-  components: resolvedComponents,
-  databaseName: "syncore-app.db",
-  storageDirectoryName: "syncore-app-storage"
+  functions
 });
 `
 			});
@@ -475,18 +498,12 @@ export const syncore = createExpoSyncoreBootstrap({
 
 import { createBrowserWorkerRuntime } from "syncorejs/browser";
 import schema from "../syncore/_generated/schema";
-import { resolvedComponents } from "../syncore/_generated/components";
 import { functions } from "../syncore/_generated/functions";
 
 void createBrowserWorkerRuntime({
   endpoint: self,
   schema,
-  functions,
-  components: resolvedComponents,
-  databaseName: "syncore-app",
-  persistenceDatabaseName: "syncore-app",
-  locateFile: () => "/sql-wasm.wasm",
-  platform: "browser-worker"
+  functions
 });
 `
 			}, {
@@ -518,7 +535,6 @@ export function AppSyncoreProvider({ children }: { children: ReactNode }) {
 import { withNodeSyncoreClient } from "syncorejs/node";
 import { api } from "./syncore/_generated/api.ts";
 import schema from "./syncore/_generated/schema.ts";
-import { resolvedComponents } from "./syncore/_generated/components.ts";
 import { functions } from "./syncore/_generated/functions.ts";
 
 await withNodeSyncoreClient(
@@ -526,8 +542,7 @@ await withNodeSyncoreClient(
     databasePath: path.join(process.cwd(), ".syncore", "syncore.db"),
     storageDirectory: path.join(process.cwd(), ".syncore", "storage"),
     schema,
-    functions,
-    components: resolvedComponents
+    functions
   },
   async (client) => {
     await client.mutation(api.tasks.create, { text: "Run locally" });
@@ -544,7 +559,6 @@ await withNodeSyncoreClient(
 import { app } from "electron";
 import { createNodeSyncoreRuntime } from "syncorejs/node";
 import schema from "../syncore/_generated/schema.js";
-import { resolvedComponents } from "../syncore/_generated/components.js";
 import { functions } from "../syncore/_generated/functions.js";
 
 export function createAppSyncoreRuntime() {
@@ -554,10 +568,53 @@ export function createAppSyncoreRuntime() {
     storageDirectory: path.join(userDataDirectory, "storage"),
     schema,
     functions,
-    components: resolvedComponents,
     platform: "electron-main"
   });
 }
+`
+			});
+			break;
+		case "svelte":
+			files.push({
+				path: path.join("src", "syncore.worker.ts"),
+				content: `/// <reference lib="webworker" />
+
+import { createBrowserWorkerRuntime } from "syncorejs/browser";
+import schema from "../syncore/_generated/schema";
+import { functions } from "../syncore/_generated/functions";
+
+void createBrowserWorkerRuntime({
+  endpoint: self,
+  schema,
+  functions
+});
+`
+			}, {
+				path: path.join("src", "SyncoreProvider.svelte"),
+				content: `<script lang="ts">
+  import { onDestroy } from "svelte";
+  import type { Snippet } from "svelte";
+  import { createBrowserWorkerClient } from "syncorejs/browser";
+  import { setSyncoreClient } from "syncorejs/svelte";
+
+  interface Props {
+    children?: Snippet;
+  }
+
+  const { children }: Props = $props();
+
+  const managed = createBrowserWorkerClient({
+    workerUrl: new URL("./syncore.worker.ts", import.meta.url)
+  });
+
+  setSyncoreClient(managed.client);
+
+  onDestroy(() => {
+    void managed.dispose();
+  });
+<\/script>
+
+{@render children?.()}
 `
 			});
 			break;
@@ -606,7 +663,8 @@ async function detectProjectTemplate(cwd) {
 	if ("expo" in dependencies || "react-native" in dependencies) return "expo";
 	if ("electron" in dependencies) return "electron";
 	if ("next" in dependencies) return "next";
-	if ("vite" in dependencies || "@vitejs/plugin-react" in dependencies || await fileExists(path.join(cwd, "src", "main.tsx")) && "react" in dependencies) return "react-web";
+	if ("svelte" in dependencies || "@sveltejs/vite-plugin-svelte" in dependencies || "@sveltejs/kit" in dependencies || await fileExists(path.join(cwd, "src", "SyncoreProvider.svelte"))) return "svelte";
+	if ("vite" in dependencies || "@vitejs/plugin-react" in dependencies || await fileExists(path.join(cwd, "src", "syncore.worker.ts")) || await fileExists(path.join(cwd, "src", "syncore-provider.tsx")) || await fileExists(path.join(cwd, "src", "main.tsx")) && "react" in dependencies) return "react-web";
 	if (packageJson) return "node";
 	return "minimal";
 }
@@ -621,7 +679,16 @@ async function readPackageJson(cwd) {
 }
 async function ensurePackageScripts(cwd, template) {
 	const packageJsonPath = path.join(cwd, "package.json");
-	if (!await fileExists(packageJsonPath)) return;
+	if (!await fileExists(packageJsonPath)) {
+		await writeFile(packageJsonPath, `${JSON.stringify({
+			type: "module",
+			scripts: {
+				"syncorejs:dev": "syncorejs dev",
+				"syncorejs:codegen": "syncorejs codegen"
+			}
+		}, null, 2)}\n`);
+		return;
+	}
 	const packageJson = await readPackageJson(cwd);
 	if (!packageJson) return;
 	const nextPackageJson = {
@@ -654,7 +721,7 @@ function maybeAddManagedDevScripts(packageJson, template) {
 	scripts.dev = combinedDevCommand();
 }
 function supportsManagedCombinedDev(template) {
-	return template === "next" || template === "react-web" || template === "electron";
+	return template === "next" || template === "react-web" || template === "svelte" || template === "electron";
 }
 function combinedDevCommand() {
 	return COMBINED_DEV_COMMAND;
@@ -703,7 +770,7 @@ async function importJsonlIntoProject(cwd, tableName, sourcePath) {
 			try {
 				parsed = JSON.parse(line);
 			} catch (error) {
-				throw new Error(`Invalid JSON on line ${lineNumber} of ${sourcePath}: ${formatError(error)}`);
+				throw new Error(`Invalid JSON on line ${lineNumber} of ${sourcePath}: ${formatError(error)}`, { cause: error });
 			}
 			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`Line ${lineNumber} of ${sourcePath} must contain a JSON object.`);
 			const payload = { ...parsed };
@@ -911,8 +978,7 @@ async function loadProjectSchema(cwd) {
 }
 async function loadDefaultExport(filePath) {
 	if (!await fileExists(filePath)) throw new Error(`Missing file: ${path.relative(process.cwd(), filePath)}`);
-	const moduleUrl = pathToFileURL(filePath).href;
-	const loaded = await tsImport(moduleUrl, { parentURL: import.meta.url });
+	const loaded = await loadTypeScriptModule(filePath);
 	if (!("default" in loaded)) throw new Error(`File ${path.relative(process.cwd(), filePath)} must have a default export.`);
 	const resolvedDefault = unwrapDefaultExport(loaded.default);
 	if (resolvedDefault === void 0) throw new Error(`File ${path.relative(process.cwd(), filePath)} exported undefined.`);
@@ -920,14 +986,30 @@ async function loadDefaultExport(filePath) {
 }
 async function loadNamedExport(filePath, exportName) {
 	if (!await fileExists(filePath)) throw new Error(`Missing file: ${path.relative(process.cwd(), filePath)}`);
-	const moduleUrl = pathToFileURL(filePath).href;
-	const loaded = await tsImport(moduleUrl, { parentURL: import.meta.url });
+	const loaded = await loadTypeScriptModule(filePath);
 	const defaultExport = loaded.default && typeof loaded.default === "object" && exportName in loaded.default ? loaded.default[exportName] : void 0;
 	if (!(exportName in loaded) && defaultExport === void 0) throw new Error(`File ${path.relative(process.cwd(), filePath)} must export ${exportName}.`);
 	const resolvedValue = unwrapDefaultExport(loaded[exportName] ?? defaultExport);
 	if (resolvedValue === void 0) throw new Error(`File ${path.relative(process.cwd(), filePath)} exported undefined for ${exportName}.`);
 	return resolvedValue;
 }
+async function hasNonEmptyComponentsManifest(filePath) {
+	if (!await fileExists(filePath)) return false;
+	const source = await readFile(filePath, "utf8");
+	return !/defineComponents\s*\(\s*\{\s*\}\s*\)/.test(source);
+}
+async function loadTypeScriptModule(filePath) {
+	const fileStat = await stat(filePath);
+	const cached = loadedTypeScriptModules.get(filePath);
+	if (cached && cached.mtimeMs === fileStat.mtimeMs) return await cached.loaded;
+	const moduleUrl = pathToFileURL(filePath).href;
+	const loaded = tsImport(moduleUrl, { parentURL: import.meta.url });
+	loadedTypeScriptModules.set(filePath, {
+		mtimeMs: fileStat.mtimeMs,
+		loaded
+	});
+	return await loaded;
+}
 async function loadProjectFunctions(cwd) {
 	const filePath = path.join(cwd, "syncore", "_generated", "functions.ts");
 	if (!await fileExists(filePath)) await runCodegen(cwd);
@@ -936,17 +1018,62 @@ async function loadProjectFunctions(cwd) {
 	return functions;
 }
 async function loadProjectResolvedComponents(cwd) {
+	const componentsManifestPath = path.join(cwd, "syncore", "components.ts");
+	if (await fileExists(componentsManifestPath)) {
+		const source = await readFile(componentsManifestPath, "utf8");
+		if (/defineComponents\s*\(\s*\{\s*\}\s*\)/.test(source)) return [];
+	}
 	const filePath = path.join(cwd, "syncore", "_generated", "components.ts");
 	if (!await fileExists(filePath)) await runCodegen(cwd);
 	const components = await loadNamedExport(filePath, "resolvedComponents");
 	if (!Array.isArray(components)) throw new Error("syncore/_generated/components.ts must export resolvedComponents.");
 	return components;
 }
+async function loadProjectRuntime(cwd) {
+	const filePath = path.join(cwd, "syncore", "_generated", "runtime.ts");
+	if (!await fileExists(filePath)) await runCodegen(cwd);
+	const loaded = await loadTypeScriptModule(filePath);
+	const schema = unwrapDefaultExport(loaded.schema);
+	const functions = unwrapDefaultExport(loaded.functions);
+	const components = unwrapDefaultExport(loaded.components);
+	if (!schema || typeof schema !== "object" || typeof schema.tableNames !== "function") throw new Error("syncore/_generated/runtime.ts must export a composed Syncore schema.");
+	if (!functions || typeof functions !== "object") throw new Error("syncore/_generated/runtime.ts must export a functions registry.");
+	if (!Array.isArray(components)) throw new Error("syncore/_generated/runtime.ts must export resolved components.");
+	return {
+		schema,
+		functions,
+		components
+	};
+}
+var HubExternalChangeSignal = class {
+	publishToHub;
+	listeners = /* @__PURE__ */ new Set();
+	constructor(publishToHub) {
+		this.publishToHub = publishToHub;
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	publish(event) {
+		return this.publishToHub(event);
+	}
+	receive(event) {
+		for (const listener of this.listeners) listener(event);
+	}
+	close() {
+		this.listeners.clear();
+	}
+};
 var HubSqliteDriver = class {
+	databasePath;
 	database;
 	transactionDepth = 0;
-	constructor(filename) {
-		this.database = new DatabaseSync(filename);
+	constructor(databasePath) {
+		this.databasePath = databasePath;
+		this.database = new DatabaseSync(databasePath);
 		this.database.exec("PRAGMA foreign_keys = ON;");
 		this.database.exec("PRAGMA journal_mode = WAL;");
 	}
@@ -999,6 +1126,7 @@ var HubSqliteDriver = class {
 	}
 };
 var HubFileStorageAdapter = class {
+	directory;
 	constructor(directory) {
 		this.directory = directory;
 	}
@@ -1037,6 +1165,19 @@ var HubFileStorageAdapter = class {
 			return null;
 		}
 	}
+	async readRange(id, offset, length) {
+		let handle;
+		try {
+			handle = await open(this.filePath(id), "r");
+			const buffer = Buffer.alloc(Math.max(length, 0));
+			const result = await handle.read(buffer, 0, buffer.byteLength, Math.max(offset, 0));
+			return buffer.subarray(0, result.bytesRead);
+		} catch {
+			return null;
+		} finally {
+			await handle?.close();
+		}
+	}
 	async delete(id) {
 		await rm(this.filePath(id), { force: true });
 	}
@@ -1112,14 +1253,10 @@ const hubDevtoolsSqlSupport = {
 		}
 	}
 };
-async function createProjectTargetBackend(cwd) {
+async function createProjectTargetBackend(cwd, externalChangeSignal) {
 	const projectTarget = resolveProjectTargetConfig(await loadProjectConfig(cwd));
 	if (!projectTarget) return null;
-	const [schema, functions, components] = await Promise.all([
-		loadProjectSchema(cwd),
-		loadProjectFunctions(cwd),
-		loadProjectResolvedComponents(cwd)
-	]);
+	const { schema, functions, components } = await loadProjectRuntime(cwd);
 	const databasePath = path.resolve(cwd, projectTarget.databasePath);
 	const storageDirectory = path.resolve(cwd, projectTarget.storageDirectory);
 	await mkdir(path.dirname(databasePath), { recursive: true });
@@ -1131,9 +1268,15 @@ async function createProjectTargetBackend(cwd) {
 		components,
 		driver,
 		storage: new HubFileStorageAdapter(storageDirectory),
-		platform: "project"
+		platform: "project",
+		runtimeCapabilities: { storage: {
+			available: true,
+			protocol: "file",
+			supportsRange: true
+		} },
+		...externalChangeSignal ? { externalChangeSignal } : {}
 	});
-	await runtime.prepareForDirectAccess();
+	await runtime.start();
 	const commandHandler = createDevtoolsCommandHandler({
 		driver,
 		schema,
@@ -1158,9 +1301,11 @@ async function createProjectTargetBackend(cwd) {
 			platform: "project",
 			sessionLabel: "Project Target",
 			targetKind: "project",
+			runtimeRole: "project-target",
 			storageProtocol: "file",
 			databaseLabel: path.basename(databasePath),
-			storageIdentity: `file::${databasePath}`
+			storageIdentity: `file::${databasePath}`,
+			capabilities: createProjectDevtoolsCapabilities()
 		},
 		handleCommand: commandHandler,
 		subscribe(subscriptionId, payload, listener) {
@@ -1175,6 +1320,31 @@ async function createProjectTargetBackend(cwd) {
 		}
 	};
 }
+function createProjectDevtoolsCapabilities() {
+	return {
+		sql: {
+			read: true,
+			write: true,
+			live: true
+		},
+		data: {
+			browse: true,
+			mutate: true,
+			importExport: true
+		},
+		storage: {
+			browse: true,
+			download: true,
+			readRange: true,
+			delete: true,
+			maxPreviewBytes: 8e4
+		},
+		scheduler: {
+			read: true,
+			edit: true
+		}
+	};
+}
 function normalizeStorageInput(input) {
 	if (typeof input === "string") return Buffer.from(input);
 	if (input instanceof Uint8Array) return input;
@@ -1297,16 +1467,24 @@ function formatError(error) {
 }
 async function isLocalPortInUse(port) {
 	return await new Promise((resolve) => {
+		let settled = false;
 		const socket = connect({
 			host: "127.0.0.1",
 			port
 		});
+		const finish = (inUse) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			socket.destroy();
+			resolve(inUse);
+		};
+		const timeout = setTimeout(() => finish(false), 100);
 		socket.once("connect", () => {
-			socket.end();
-			resolve(true);
+			finish(true);
 		});
 		socket.once("error", () => {
-			resolve(false);
+			finish(false);
 		});
 	});
 }
@@ -1348,26 +1526,29 @@ async function startDevHub(options) {
 		return await readDevtoolsSessionState(options.cwd) ?? sessionState;
 	}
 	await writeDevtoolsSessionState(options.cwd, sessionState);
-	let projectTargetBackend = null;
-	try {
-		projectTargetBackend = await createProjectTargetBackend(options.cwd);
-	} catch (error) {
-		console.warn(`Project target fallback unavailable: ${formatError(error)}`);
-	}
-	const httpServer = createServer((_request, response) => {
-		response.writeHead(200, { "content-type": "application/json" });
-		response.end(JSON.stringify({
-			ok: true,
-			wsPort: devtoolsPort
-		}));
+	const httpServer = createServer((request, response) => {
+		handleStorageAccessHttpRequest(request, response).catch((error) => {
+			if (!response.headersSent) writeJsonResponse(response, 500, { error: formatError(error) });
+			else response.destroy(error instanceof Error ? error : void 0);
+		});
 	});
 	const websocketServer = new WebSocketServer({ server: httpServer });
+	const storageAccessTickets = /* @__PURE__ */ new Map();
+	const pendingHubCommands = /* @__PURE__ */ new Map();
 	const runtimeSockets = /* @__PURE__ */ new Map();
 	const runtimeHellos = /* @__PURE__ */ new Map();
 	const runtimeEvents = /* @__PURE__ */ new Map();
 	const socketRuntimeIds = /* @__PURE__ */ new Map();
 	const dashboardSockets = /* @__PURE__ */ new Set();
 	const dashboardSubscriptions = /* @__PURE__ */ new Map();
+	let relayExternalChange = () => {};
+	const projectTargetExternalChangeSignal = new HubExternalChangeSignal((event) => relayExternalChange(PROJECT_TARGET_RUNTIME_ID, runtimeHellos.get(PROJECT_TARGET_RUNTIME_ID)?.storageIdentity ?? "", event));
+	let projectTargetBackend = null;
+	try {
+		projectTargetBackend = await createProjectTargetBackend(options.cwd, projectTargetExternalChangeSignal);
+	} catch (error) {
+		console.warn(`Project target fallback unavailable: ${formatError(error)}`);
+	}
 	const hello = {
 		type: "hello",
 		protocolVersion: SYNCORE_DEVTOOLS_PROTOCOL_VERSION,
@@ -1380,12 +1561,30 @@ async function startDevHub(options) {
 		runtimeHellos.set(PROJECT_TARGET_RUNTIME_ID, projectTargetBackend.hello);
 		runtimeEvents.set(PROJECT_TARGET_RUNTIME_ID, []);
 	}
+	relayExternalChange = (sourceRuntimeId, storageIdentity, event) => {
+		if (!storageIdentity) return;
+		const message = {
+			type: "external.change",
+			runtimeId: sourceRuntimeId,
+			storageIdentity,
+			event
+		};
+		for (const [runtimeId, runtimeHello] of runtimeHellos) {
+			if (runtimeId === sourceRuntimeId || runtimeHello.storageIdentity !== storageIdentity) continue;
+			if (runtimeId === PROJECT_TARGET_RUNTIME_ID) {
+				projectTargetExternalChangeSignal.receive(event);
+				continue;
+			}
+			const targetSocket = runtimeSockets.get(runtimeId);
+			if (targetSocket?.readyState === WebSocket.OPEN) targetSocket.send(JSON.stringify(message));
+		}
+	};
 	const appendHubLog = async (event) => {
 		const runtimeHello = runtimeHellos.get(event.runtimeId);
-		const clientRuntimeIds = [...runtimeHellos.values()].filter((hello) => hello.runtimeId !== "syncore-dev-hub" && hello.targetKind !== "project").map((hello) => hello.runtimeId).sort();
-		const clientTargetKeys = [...runtimeHellos.values()].filter((hello) => hello.runtimeId !== "syncore-dev-hub" && hello.targetKind !== "project").map((hello) => hello.storageIdentity ?? `runtime::${hello.runtimeId}`).sort();
+		const clientRuntimeIds = [...runtimeHellos.values()].filter((hello) => hello.runtimeId !== "syncore-dev-hub").map((hello) => hello.runtimeId).sort();
+		const clientTargetKeys = [...runtimeHellos.values()].filter((hello) => hello.runtimeId !== "syncore-dev-hub").map((hello) => hello.storageIdentity ?? `runtime::${hello.runtimeId}`).sort();
 		const targetIdentity = runtimeHello?.storageIdentity ?? `runtime::${event.runtimeId}`;
-		const targetId = event.runtimeId === "syncore-dev-hub" ? "all" : runtimeHello?.targetKind === "project" ? "project" : createPublicTargetId(targetIdentity, clientTargetKeys);
+		const targetId = event.runtimeId === "syncore-dev-hub" ? "all" : createPublicTargetId(targetIdentity, clientTargetKeys);
 		const publicRuntimeId = event.runtimeId === "syncore-dev-hub" ? void 0 : createPublicRuntimeId(event.runtimeId, clientRuntimeIds);
 		const category = event.type === "query.executed" ? "query" : event.type === "mutation.committed" ? "mutation" : event.type === "action.completed" ? "action" : "system";
 		const message = event.type === "log" ? event.message : event.type === "query.executed" || event.type === "mutation.committed" || event.type === "action.completed" ? event.functionName : event.type;
@@ -1402,6 +1601,135 @@ async function startDevHub(options) {
 			event
 		})}\n`);
 	};
+	const requestRuntimeCommand = async (targetRuntimeId, payload, timeoutMs = 3e4) => {
+		if (targetRuntimeId === PROJECT_TARGET_RUNTIME_ID && projectTargetBackend) return projectTargetBackend.handleCommand(payload);
+		const target = runtimeSockets.get(targetRuntimeId);
+		if (!target || target.readyState !== WebSocket.OPEN) throw new Error(`Runtime ${targetRuntimeId} is not connected.`);
+		const commandId = `hub:${randomUUID()}`;
+		return await new Promise((resolve, reject) => {
+			const timeout = setTimeout(() => {
+				pendingHubCommands.delete(commandId);
+				reject(/* @__PURE__ */ new Error(`Runtime command ${payload.kind} timed out.`));
+			}, timeoutMs);
+			pendingHubCommands.set(commandId, {
+				resolve,
+				reject,
+				timeout
+			});
+			target.send(JSON.stringify({
+				type: "command",
+				commandId,
+				targetRuntimeId,
+				payload
+			}));
+		});
+	};
+	const createStorageAccessTicket = async (targetRuntimeId, id, purpose) => {
+		const metadata = await requestRuntimeCommand(targetRuntimeId, {
+			kind: "storage.readRange",
+			id,
+			offset: 0,
+			length: 0
+		});
+		if (metadata.kind !== "storage.readRange.result") return {
+			kind: "storage.access.create.result",
+			error: "Runtime returned an unexpected storage access response."
+		};
+		if (metadata.error || !metadata.entry) return {
+			kind: "storage.access.create.result",
+			error: metadata.error ?? "Storage object could not be accessed."
+		};
+		const ticket = randomUUID();
+		const expiresAt = Date.now() + STORAGE_ACCESS_TICKET_TTL_MS;
+		storageAccessTickets.set(ticket, {
+			id: ticket,
+			runtimeId: targetRuntimeId,
+			storageId: id,
+			purpose,
+			entry: metadata.entry,
+			supportsRange: metadata.supportsRange,
+			expiresAt
+		});
+		cleanupExpiredStorageTickets();
+		return {
+			kind: "storage.access.create.result",
+			entry: metadata.entry,
+			url: `http://127.0.0.1:${devtoolsPort}/storage/access/${ticket}`,
+			expiresAt,
+			supportsRange: metadata.supportsRange,
+			maxPreviewBytes: STORAGE_ACCESS_MAX_PREVIEW_BYTES
+		};
+	};
+	const cleanupExpiredStorageTickets = () => {
+		const now = Date.now();
+		for (const [ticket, access] of storageAccessTickets) if (access.expiresAt <= now) storageAccessTickets.delete(ticket);
+	};
+	const handleStorageAccessHttpRequest = async (request, response) => {
+		setStorageCorsHeaders(response);
+		if (request.method === "OPTIONS") {
+			response.writeHead(204);
+			response.end();
+			return;
+		}
+		const requestUrl = new URL(request.url ?? "/", `http://127.0.0.1:${devtoolsPort}`);
+		const match = /^\/storage\/access\/([^/]+)$/.exec(requestUrl.pathname);
+		if (!match) {
+			writeJsonResponse(response, 200, {
+				ok: true,
+				wsPort: devtoolsPort
+			});
+			return;
+		}
+		if (request.method !== "GET" && request.method !== "HEAD") {
+			writeTextResponse(response, 405, "Method not allowed.");
+			return;
+		}
+		cleanupExpiredStorageTickets();
+		const ticket = storageAccessTickets.get(match[1]);
+		if (!ticket || ticket.expiresAt <= Date.now()) {
+			writeTextResponse(response, 401, "Storage access ticket is invalid or expired.");
+			return;
+		}
+		const range = parseStorageRangeHeader(request.headers.range, ticket.entry.size);
+		if ("error" in range) {
+			writeTextResponse(response, range.status, range.error);
+			return;
+		}
+		const start = range.start;
+		const end = range.end;
+		const byteLength = end >= start ? end - start + 1 : 0;
+		if (!ticket.supportsRange && ticket.entry.size > STORAGE_ACCESS_CHUNK_BYTES) {
+			writeTextResponse(response, 409, "This storage backend does not support streaming large files.");
+			return;
+		}
+		writeStorageAccessHeaders(response, ticket, {
+			status: range.partial ? 206 : 200,
+			start,
+			end,
+			byteLength
+		});
+		if (request.method === "HEAD") {
+			response.end();
+			return;
+		}
+		let offset = start;
+		while (offset <= end) {
+			const chunkLength = Math.min(STORAGE_ACCESS_CHUNK_BYTES, end - offset + 1);
+			const chunk = await requestRuntimeCommand(ticket.runtimeId, {
+				kind: "storage.readRange",
+				id: ticket.storageId,
+				offset,
+				length: chunkLength
+			}, 6e4);
+			if (chunk.kind !== "storage.readRange.result") throw new Error("Runtime returned an unexpected storage chunk response.");
+			if (chunk.error || !chunk.base64) throw new Error(chunk.error ?? "Storage chunk could not be read.");
+			const bytes = Buffer.from(chunk.base64, "base64");
+			if (bytes.byteLength === 0) break;
+			await writeResponseChunk(response, bytes);
+			offset += bytes.byteLength;
+		}
+		response.end();
+	};
 	websocketServer.on("connection", (socket, request) => {
 		const isBrowserDashboardClient = isAllowedDashboardOrigin(request.headers.origin, dashboardPort);
 		const isAuthorizedDashboardClient = !isBrowserDashboardClient || isAuthorizedDashboardRequest({
@@ -1438,10 +1766,38 @@ async function startDevHub(options) {
 				socket.send(JSON.stringify({ type: "pong" }));
 				return;
 			}
+			if (message.type === "external.change") {
+				const storageIdentity = runtimeHellos.get(message.runtimeId)?.storageIdentity ?? message.storageIdentity;
+				if (storageIdentity && storageIdentity === message.storageIdentity) relayExternalChange(message.runtimeId, storageIdentity, message.event);
+				return;
+			}
 			if (message.type === "command") {
 				if (!isAuthorizedDashboardClient) return;
 				const targetRuntimeId = message.targetRuntimeId;
 				if (!targetRuntimeId) return;
+				if (message.payload.kind === "storage.access.create") {
+					createStorageAccessTicket(targetRuntimeId, message.payload.id, message.payload.purpose).then((payload) => {
+						if (socket.readyState !== WebSocket.OPEN) return;
+						socket.send(JSON.stringify({
+							type: "command.result",
+							commandId: message.commandId,
+							runtimeId: targetRuntimeId,
+							payload
+						}));
+					}).catch((error) => {
+						if (socket.readyState !== WebSocket.OPEN) return;
+						socket.send(JSON.stringify({
+							type: "command.result",
+							commandId: message.commandId,
+							runtimeId: targetRuntimeId,
+							payload: {
+								kind: "storage.access.create.result",
+								error: formatError(error)
+							}
+						}));
+					});
+					return;
+				}
 				if (targetRuntimeId === PROJECT_TARGET_RUNTIME_ID && projectTargetBackend) {
 					(async () => {
 						const payload = await projectTargetBackend.handleCommand(message.payload);
@@ -1539,12 +1895,21 @@ async function startDevHub(options) {
 			if (message.type === "event" && message.event.type === "runtime.disconnected") runtimeHellos.delete(message.event.runtimeId);
 			if (message.type === "event" && message.event.runtimeId !== "syncore-dev-hub") {
 				const history = runtimeEvents.get(message.event.runtimeId) ?? [];
-				history.unshift(message.event);
-				runtimeEvents.set(message.event.runtimeId, history.slice(0, 200));
+				history.push(message.event);
+				runtimeEvents.set(message.event.runtimeId, history.slice(-200));
 				if (message.event.type === "runtime.disconnected") runtimeEvents.delete(message.event.runtimeId);
 				appendHubLog(message.event);
 			} else if (message.type === "event") appendHubLog(message.event);
 			if (message.type === "command.result" || message.type === "subscription.data" || message.type === "subscription.error") {
+				if (message.type === "command.result") {
+					const pending = pendingHubCommands.get(message.commandId);
+					if (pending) {
+						clearTimeout(pending.timeout);
+						pendingHubCommands.delete(message.commandId);
+						pending.resolve(message.payload);
+						return;
+					}
+				}
 				for (const client of dashboardSockets) if (client.readyState === WebSocket.OPEN) client.send(encoded);
 				return;
 			}
@@ -1634,6 +1999,80 @@ async function startDevHub(options) {
 	process.on("SIGTERM", close);
 	return sessionState;
 }
+function setStorageCorsHeaders(response) {
+	response.setHeader("Access-Control-Allow-Origin", "*");
+	response.setHeader("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS");
+	response.setHeader("Access-Control-Allow-Headers", "Range");
+	response.setHeader("Access-Control-Expose-Headers", "Accept-Ranges, Content-Disposition, Content-Length, Content-Range, Content-Type");
+}
+function writeJsonResponse(response, status, payload) {
+	response.writeHead(status, { "content-type": "application/json" });
+	response.end(JSON.stringify(payload));
+}
+function writeTextResponse(response, status, message) {
+	response.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
+	response.end(message);
+}
+function parseStorageRangeHeader(header, size) {
+	if (size === 0) {
+		if (!header) return {
+			start: 0,
+			end: -1,
+			partial: false
+		};
+		return {
+			error: "Requested range is not satisfiable.",
+			status: 416
+		};
+	}
+	if (!header) return {
+		start: 0,
+		end: size - 1,
+		partial: false
+	};
+	if (header.includes(",")) return {
+		error: "Multi-range requests are not supported.",
+		status: 416
+	};
+	const match = /^bytes=(\d+)-(\d*)$/.exec(header);
+	if (!match) return {
+		error: "Only simple byte ranges are supported.",
+		status: 416
+	};
+	const start = Number(match[1]);
+	const end = match[2] ? Number(match[2]) : size - 1;
+	if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start || start >= size) return {
+		error: "Requested range is not satisfiable.",
+		status: 416
+	};
+	return {
+		start,
+		end: Math.min(end, size - 1),
+		partial: true
+	};
+}
+function writeStorageAccessHeaders(response, ticket, range) {
+	const headers = {
+		"content-type": ticket.entry.contentType ?? "application/octet-stream",
+		"content-length": range.byteLength,
+		"accept-ranges": ticket.supportsRange ? "bytes" : "none",
+		"content-disposition": renderStorageContentDisposition(ticket)
+	};
+	if (range.status === 206) headers["content-range"] = `bytes ${range.start}-${range.end}/${ticket.entry.size}`;
+	response.writeHead(range.status, headers);
+}
+function renderStorageContentDisposition(ticket) {
+	return `${ticket.purpose === "download" ? "attachment" : "inline"}; filename="${sanitizeHeaderFilename(ticket.entry.fileName ?? ticket.entry.id)}"; filename*=UTF-8''${encodeURIComponent(ticket.entry.fileName ?? `${ticket.entry.id}.bin`)}`;
+}
+function sanitizeHeaderFilename(value) {
+	return value.replaceAll(/["\\\r\n]/g, "_");
+}
+async function writeResponseChunk(response, chunk) {
+	if (response.write(chunk)) return;
+	await new Promise((resolve) => {
+		response.once("drain", resolve);
+	});
+}
 async function writeDevtoolsSessionState(cwd, state) {
 	const sessionPath = path.join(cwd, DEVTOOLS_SESSION_FILE);
 	await mkdir(path.dirname(sessionPath), { recursive: true });
@@ -1795,6 +2234,6 @@ function toSearchValue(value) {
 	return stableStringify(value);
 }
 //#endregion
-export { SYNCORE_MIGRATION_SNAPSHOT_FILE_NAME, VALID_SYNCORE_TEMPLATES, applyProjectMigrations, detectProjectTemplate, fileExists, formatError, getNextMigrationNumber, hasSyncoreProject, importJsonlIntoProject, isLocalPortInUse, loadProjectComponentsManifest, loadProjectConfig, loadProjectFunctions, loadProjectResolvedComponents, loadProjectRootSchema, loadProjectSchema, logScaffoldResult, readPackageJson, readStoredSnapshot, resolveDefaultSeedFile, resolvePortFromEnv, resolveProjectTargetConfig, resolveRequestedTemplate, runCodegen, runDevProjectBootstrap, runSyncoreCli, scaffoldProject, slugify, startDevHub, templateUsesConnectedClients, writeStoredSnapshot };
+export { SYNCORE_MIGRATION_SNAPSHOT_FILE_NAME, VALID_SYNCORE_TEMPLATES, applyProjectMigrations, detectProjectTemplate, fileExists, formatError, getNextMigrationNumber, hasSyncoreProject, importJsonlIntoProject, isLocalPortInUse, loadProjectComponentsManifest, loadProjectConfig, loadProjectFunctions, loadProjectResolvedComponents, loadProjectRootSchema, loadProjectRuntime, loadProjectSchema, logScaffoldResult, readPackageJson, readStoredSnapshot, resolveDefaultSeedFile, resolvePortFromEnv, resolveProjectTargetConfig, resolveRequestedTemplate, runCodegen, runDevProjectBootstrap, runSyncoreCli, scaffoldProject, slugify, startDevHub, templateUsesConnectedClients, writeStoredSnapshot };
 
 //# sourceMappingURL=cli.mjs.map