syncorejs 0.2.1 → 0.2.3

package/README.md

@@ -18,7 +18,7 @@ npx syncorejs dev
 ## Imports
 
 ```ts
-import { defineSchema, defineTable, query, mutation, v } from "syncorejs";
+import { defineSchema, defineTable, query, mutation, s } from "syncorejs";
 import { useQuery, useMutation } from "syncorejs/react";
 import { createBrowserWorkerClient } from "syncorejs/browser";
 import { SyncoreNextProvider } from "syncorejs/next";
@@ -28,3 +28,4 @@ import { SyncoreNextProvider } from "syncorejs/next";
 
 - Repository: https://github.com/JPSAUD501/Syncore
 - Quickstarts: https://github.com/JPSAUD501/Syncore/tree/main/docs/quickstarts
+

package/dist/_vendor/cli/app.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.mts","names":[],"sources":["../src/app.ts"],"mappings":";;;iBAqIsB,aAAA,CAAc,IAAA,cAAsB,OAAA"}
+{"version":3,"file":"app.d.mts","names":[],"sources":["../src/app.ts"],"mappings":";;;iBAgJsB,aAAA,CAAc,IAAA,cAAsB,OAAO"}

package/dist/_vendor/cli/app.mjs

@@ -1,16 +1,17 @@
 import { CliContext, openTarget } from "./context.mjs";
 import { printCompactDevPhase, printDevSessionIntro, runShellCommand, withConsoleCapture } from "./dev-session.mjs";
-import { buildRuntimeLookup, connectToProjectHub, createManagedProjectClient, createPublicRuntimeId, exportProjectData, importProjectData, isKnownTemplate, listAvailableTargets, listConnectedClientTargets, listProjectTables, loadImportDocumentBatches, readProjectTable, resolveDashboardUrl, resolveDevtoolsUrl, resolveDocsTarget, resolveProjectFunction, targetSupportsCapability, writeExportData } from "./project.mjs";
-import { buildDevBootstrapNextSteps, buildHubUnavailableNextSteps, buildInitNextSteps, buildTargetCommandNextSteps, templateUsesConnectedClients } from "./messages.mjs";
-import { buildDoctorReport } from "./doctor.mjs";
+import { buildRuntimeLookup, connectToProjectHub, createManagedProjectClient, createPublicRuntimeId, exportProjectData, importProjectData, isKnownTemplate, listAvailableTargets, listConnectedClientTargets, listProjectTables, loadImportDocumentBatches, readProjectTable, resolveActiveDashboardUrl, resolveDashboardUrl, resolveDevtoolsUrl, resolveDocsTarget, resolveProjectFunction, targetSupportsCapability, writeExportData } from "./project.mjs";
+import { buildDevBootstrapNextSteps, buildHubUnavailableNextSteps, buildInitNextSteps, buildTargetCommandNextSteps, templateUsesConnectedClients as templateUsesConnectedClients$1 } from "./messages.mjs";
+import { applyDoctorFixes, buildDoctorReport } from "./doctor.mjs";
 import { applyRootHelp } from "./help.mjs";
-import { printDevReadySummary, printDoctorReport, printTargetsTable, renderOutput } from "./render.mjs";
+import { formatPersistedLogEntry, printDevReadySummary, printDoctorReport, printTargetsTable, renderOutput } from "./render.mjs";
 import { resolveClientRuntime, resolveOperationalTarget } from "./targets.mjs";
 import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { spawn } from "node:child_process";
 import { Command } from "commander";
 import { createSchemaSnapshot, diffSchemaSnapshots, renderMigrationSql } from "../core/index.mjs";
-import { VALID_SYNCORE_TEMPLATES, applyProjectMigrations, detectProjectTemplate, formatError, getNextMigrationNumber, hasSyncoreProject, isLocalPortInUse, loadProjectSchema, readStoredSnapshot, resolveRequestedTemplate, runCodegen, runDevProjectBootstrap, scaffoldProject, slugify, startDevHub, writeStoredSnapshot } from "../core/cli.mjs";
+import { VALID_SYNCORE_TEMPLATES, applyProjectMigrations, detectProjectTemplate, fileExists, formatError, getNextMigrationNumber, hasSyncoreProject, isLocalPortInUse, loadProjectSchema, readStoredSnapshot, resolveRequestedTemplate, runCodegen, runDevProjectBootstrap, scaffoldProject, slugify, startDevHub, writeStoredSnapshot } from "../core/cli.mjs";
 //#region src/app.ts
 async function runSyncoreCli(argv = process.argv) {
 	const program = buildProgram();
@@ -91,26 +92,37 @@ function addCodegenCommand(program) {
 	});
 }
 function addDoctorCommand(program) {
-	program.command("doctor").summary("Inspect the current Syncore project state").description("Check project structure, template capabilities, hub state, and available targets.").addHelpText("after", [
+	program.command("doctor").summary("Inspect the current Syncore project state").description("Check project structure, template capabilities, hub state, and available targets.").option("--fix", "Apply safe low-risk fixes like codegen and snapshot refresh").addHelpText("after", [
 		"",
 		"Examples:",
 		"  npx syncorejs doctor",
-		"  npx syncorejs doctor --json"
-	].join("\n")).action(async (_options, command) => {
+		"  npx syncorejs doctor --json",
+		"  npx syncorejs doctor --fix"
+	].join("\n")).action(async (options, command) => {
 		const ctx = createContext(command);
 		await executeCommand(ctx, async () => {
-			const report = await buildDoctorReport(ctx.cwd);
+			let report = await buildDoctorReport(ctx.cwd);
+			let appliedFixes = [];
+			if (options.fix) {
+				appliedFixes = await applyDoctorFixes(ctx.cwd, report);
+				report = await buildDoctorReport(ctx.cwd);
+			}
 			if (ctx.json) {
 				ctx.printResult({
 					command: "doctor",
-					data: report
+					...options.fix && appliedFixes.length > 0 ? { summary: `Applied ${appliedFixes.length} safe fix(es).` } : {},
+					data: {
+						...report,
+						...options.fix ? { appliedFixes } : {}
+					}
 				});
 				return;
 			}
-			ctx.info(`Detected template: ${report.template}`);
-			ctx.info(`Project status: ${report.status}`);
-			ctx.info(`Project target: ${report.projectTarget ? report.projectTarget.databasePath : "not configured"}`);
-			ctx.info(`Devtools hub: ${report.hub.running ? report.hub.url : "not running"}`);
+			ctx.info(report.primaryIssue.summary);
+			if (options.fix) if (appliedFixes.length > 0) {
+				ctx.success(`Applied ${appliedFixes.length} safe fix(es).`);
+				for (const fix of appliedFixes) ctx.info(fix);
+			} else ctx.info("No safe fixes were applied.");
 			printDoctorReport(report, { verbose: ctx.verbose });
 			if (report.workspaceMatches.length > 0) {
 				ctx.warn("You appear to be at a workspace root instead of inside an app package.");
@@ -147,26 +159,31 @@ function addTargetsCommand(program) {
 	});
 }
 function addDevCommand(program) {
-	program.command("dev").summary("Run the Syncore development loop").description("Bootstrap the local Syncore project, start the hub, discover targets, and keep the local workflow in sync.").option("--template <template>", `Template to scaffold when Syncore is missing (${VALID_SYNCORE_TEMPLATES.join(", ")}, or auto)`, "auto").option("--once", "Run bootstrap once and exit").option("--until-success", "Retry bootstrap until it succeeds").option("--run <function>", "Run a Syncore function after bootstrap succeeds").option("--run-sh <command>", "Run a shell command after bootstrap succeeds").option("--open-dashboard", "Open the dashboard URL even in non-interactive mode").addHelpText("after", [
+	program.command("dev").summary("Run the Syncore development loop").description("Bootstrap the local Syncore project, start the hub, discover targets, and keep the local workflow in sync.").option("--template <template>", `Template to scaffold when Syncore is missing (${VALID_SYNCORE_TEMPLATES.join(", ")}, or auto)`, "auto").option("--once", "Run bootstrap once and exit").option("--until-success", "Retry bootstrap until it succeeds").option("--run <function>", "Run a Syncore function after bootstrap succeeds").option("--run-sh <command>", "Run a shell command after bootstrap succeeds").option("--typecheck <mode>", "Run TypeScript typecheck before entering the local dev loop: enable, try, or disable", "try").option("--tail-logs <mode>", "Control whether runtime logs appear in this terminal: always, errors, or disable", "errors").option("--no-open-dashboard", "Do not open the dashboard automatically after the hub is ready").addHelpText("after", [
 		"",
 		"Examples:",
 		"  npx syncorejs dev",
 		"  npx syncorejs dev --once",
 		"  npx syncorejs dev --until-success",
 		"  npx syncorejs dev --run tasks/list",
-		"  npx syncorejs dev --open-dashboard",
-		"  npx syncorejs dev --run-sh \"npm run dev\""
+		"  npx syncorejs dev --no-open-dashboard",
+		"  npx syncorejs dev --run-sh \"npm run dev\"",
+		"  npx syncorejs dev --typecheck enable",
+		"  npx syncorejs dev --tail-logs always"
 	].join("\n")).action(async (options, command) => {
 		const ctx = createContext(command);
 		await executeCommand(ctx, async () => {
 			if (options.run && options.runSh) ctx.fail("`syncorejs dev` accepts either --run or --run-sh, not both.");
-			const shouldOpenDashboard = Boolean(options.openDashboard) || isRealInteractiveTerminal(ctx);
+			const shouldOpenDashboard = options.openDashboard ?? true;
 			await ensureLocalPortConfiguration(ctx);
 			const template = await resolveRequestedTemplate(ctx.cwd, options.template);
+			validateDevModes(ctx, options);
 			printDevSessionIntro(ctx);
 			await ensureDevProjectExists(ctx, template);
+			printDevPreflight(ctx, await buildDoctorReport(ctx.cwd));
+			const typecheckResult = await runDevTypecheck(ctx, options.typecheck);
 			if (options.once) {
-				await runDevBootstrapLoop(ctx, template, options.untilSuccess ?? false);
+				const bootstrapReport = await runDevBootstrapLoop(ctx, template, options.untilSuccess ?? false, options.tailLogs);
 				await runDevFollowup(ctx, options);
 				const targets = await listAvailableTargets(ctx.cwd);
 				ctx.printResult({
@@ -179,32 +196,39 @@ function addDevCommand(program) {
 					projectTargetConfigured: targets.some((target) => target.kind === "project"),
 					dashboardUrl: resolveDashboardUrl(),
 					devtoolsUrl: resolveDevtoolsUrl(),
-					targets
+					targets,
+					codegenStatus: "refreshed",
+					driftStatus: describeDevDriftStatus(bootstrapReport),
+					typecheckStatus: describeTypecheckStatus(typecheckResult)
 				});
 				return;
 			}
-			await runDevBootstrapLoop(ctx, template, options.untilSuccess ?? false);
+			const bootstrapReport = await runDevBootstrapLoop(ctx, template, options.untilSuccess ?? false, options.tailLogs);
 			const targets = await listAvailableTargets(ctx.cwd);
 			printDevReadySummary(ctx, {
 				template,
 				projectTargetConfigured: targets.some((target) => target.kind === "project"),
 				dashboardUrl: resolveDashboardUrl(),
 				devtoolsUrl: resolveDevtoolsUrl(),
-				targets
+				targets,
+				codegenStatus: "refreshed",
+				driftStatus: describeDevDriftStatus(bootstrapReport),
+				typecheckStatus: describeTypecheckStatus(typecheckResult)
 			});
-			await startManagedDevHub(ctx, template);
-			await maybeOpenDashboard(ctx, shouldOpenDashboard);
-			await monitorLiveDevSession(ctx, template);
+			await maybeOpenDashboard(ctx, shouldOpenDashboard, await startManagedDevHub(ctx, template));
+			await monitorLiveDevSession(ctx, template, options.tailLogs);
 		});
 	});
 }
-function isRealInteractiveTerminal(context) {
-	return context.interactive && Boolean(process.stdin.isTTY && process.stdout.isTTY);
-}
-async function maybeOpenDashboard(context, shouldOpenDashboard) {
+async function maybeOpenDashboard(context, shouldOpenDashboard, hubSession) {
 	if (!shouldOpenDashboard) return;
-	if (await openTarget(resolveDashboardUrl())) {
-		context.info(`Opened dashboard at ${resolveDashboardUrl()}.`);
+	const targetUrl = hubSession?.authenticatedDashboardUrl ?? await resolveActiveDashboardUrl(context.cwd);
+	if (!await waitForDashboardReady(targetUrl)) {
+		context.warn("Dashboard did not become ready in time, so it was not opened.");
+		return;
+	}
+	if (await openTarget(targetUrl)) {
+		context.info(`Opened dashboard at ${targetUrl}`);
 		return;
 	}
 	context.warn("Unable to open the dashboard automatically.");
@@ -291,18 +315,18 @@ function addRunCommand(program) {
 		const ctx = createContext(command);
 		await executeCommand(ctx, async () => {
 			if (options.runtime && !options.target) ctx.fail("`syncorejs run --runtime` requires --target.");
-			const resolved = await resolveProjectFunction(ctx.cwd, functionName);
 			const args = parseJsonObject(argsText, "Function arguments");
-			if (options.watch && resolved.definition.kind !== "query") ctx.fail("`syncorejs run --watch` only supports query functions.");
 			const target = await resolveOperationalTarget(ctx, options.target, {
 				command: "run",
 				capability: "run"
 			});
 			const runtime = resolveClientRuntime(target, options.runtime, { command: "run" });
-			ctx.info(options.watch ? `Watching ${resolved.name} on ${target.id}${runtime ? ` (${runtime.id} ${runtime.label})` : ""}.` : `Running ${resolved.name} on ${target.id}${runtime ? ` (${runtime.id} ${runtime.label})` : ""}.`);
 			if (target.kind === "project") {
 				const managed = await createManagedProjectClient(ctx.cwd);
 				try {
+					const resolved = await resolveProjectFunction(ctx.cwd, functionName, managed.functions);
+					if (options.watch && resolved.definition.kind !== "query") ctx.fail("`syncorejs run --watch` only supports query functions.");
+					ctx.info(options.watch ? `Watching ${resolved.name} on ${target.id}.` : `Running ${resolved.name} on ${target.id}.`);
 					if (options.watch) {
 						const watch = managed.client.watchQuery(resolved.reference, args);
 						const render = () => {
@@ -326,6 +350,9 @@ function addRunCommand(program) {
 					await managed.dispose();
 				}
 			}
+			const resolved = await resolveProjectFunction(ctx.cwd, functionName);
+			if (options.watch && resolved.definition.kind !== "query") ctx.fail("`syncorejs run --watch` only supports query functions.");
+			ctx.info(options.watch ? `Watching ${resolved.name} on ${target.id}${runtime ? ` (${runtime.id} ${runtime.label})` : ""}.` : `Running ${resolved.name} on ${target.id}${runtime ? ` (${runtime.id} ${runtime.label})` : ""}.`);
 			const hub = await requireHubConnection(ctx);
 			try {
 				if (options.watch) {
@@ -395,7 +422,12 @@ function addDataCommand(program) {
 					data: tables,
 					target: target.id
 				});
-				if (!ctx.json) for (const entry of tables) process.stdout.write(`  ${entry.name} (${entry.documentCount} document(s))\n`);
+				if (!ctx.json) for (const entry of tables) {
+					const tableEntry = entry;
+					const label = typeof tableEntry.displayName === "string" && tableEntry.displayName.length > 0 && tableEntry.displayName !== tableEntry.name ? `${tableEntry.displayName} -> ${tableEntry.name}` : tableEntry.name;
+					const owner = tableEntry.owner === "component" ? `  component:${String(tableEntry.componentPath ?? "unknown")}` : "";
+					process.stdout.write(`  ${label} (${tableEntry.documentCount} document(s))${owner}\n`);
+				}
 				return;
 			}
 			if (target.kind === "project") {
@@ -506,14 +538,18 @@ function addDashboardCommand(program) {
 		const ctx = createContext(command);
 		await executeCommand(ctx, async () => {
 			const url = resolveDashboardUrl();
+			const activeUrl = await resolveActiveDashboardUrl(ctx.cwd);
 			if (options.open) {
-				if (!await openTarget(url)) ctx.warn("Unable to open the dashboard automatically.");
+				if (!(await waitForDashboardReady(activeUrl) ? await openTarget(activeUrl) : false)) ctx.warn("Unable to open the dashboard automatically.");
 			}
 			ctx.printResult({
 				summary: "Dashboard URL resolved.",
 				command: "dashboard",
-				data: { url },
-				nextSteps: [`Open ${url}`]
+				data: {
+					url: activeUrl,
+					baseUrl: url
+				},
+				nextSteps: [`Open ${activeUrl}`]
 			});
 		});
 	});
@@ -559,13 +595,15 @@ async function ensureLocalPortConfiguration(context) {
 	if (Number.isFinite(dashboardPort) && Number.isFinite(devtoolsPort) && dashboardPort === devtoolsPort) context.fail([`Dashboard and devtools cannot share the same port (${dashboardPort}).`, "Set different values for SYNCORE_DASHBOARD_PORT and SYNCORE_DEVTOOLS_PORT, then rerun `npx syncorejs dev`."].join(" "));
 	if (Number.isFinite(dashboardPort) && dashboardPort > 0 && Number.isFinite(devtoolsPort) && devtoolsPort > 0 && await isLocalPortInUse(dashboardPort) && !await isLocalPortInUse(devtoolsPort)) context.warn(`Dashboard port ${dashboardPort} is already in use. If Syncore does not start cleanly, set SYNCORE_DASHBOARD_PORT to a different value.`);
 }
-async function runDevBootstrapLoop(context, template, untilSuccess) {
+async function runDevBootstrapLoop(context, template, untilSuccess, tailLogs) {
 	while (true) try {
+		let sawBootstrapFailure = false;
 		printCompactDevPhase(context, "Project");
 		printCompactDevPhase(context, "Codegen");
 		printCompactDevPhase(context, "Schema");
 		await withConsoleCapture((method, message) => {
 			if (/destructive schema changes/i.test(message)) {
+				sawBootstrapFailure = true;
 				context.error("Syncore dev blocked by destructive schema changes.");
 				return;
 			}
@@ -573,9 +611,20 @@ async function runDevBootstrapLoop(context, template, untilSuccess) {
 				context.warn(message.replace(/^Syncore dev warning:\s*/i, ""));
 				return;
 			}
-			if (/bootstrap failed/i.test(message) || method === "error") context.error(message);
+			if (/bootstrap failed/i.test(message) || method === "error") {
+				sawBootstrapFailure = true;
+				context.error(message);
+			}
 		}, async () => runDevProjectBootstrap(context.cwd, template));
-		return;
+		const report = await buildDoctorReport(context.cwd);
+		if (sawBootstrapFailure || report.status === "schema-destructive-drift") {
+			if (tailLogs === "errors") await printRecentRuntimeSignals(context, context.cwd);
+			context.fail(report.primaryIssue.summary, 1, report, {
+				category: "runtime",
+				nextSteps: report.suggestions
+			});
+		}
+		return report;
 	} catch (error) {
 		if (!untilSuccess) throw error;
 		context.warn(`Syncore dev bootstrap failed, retrying: ${formatError(error)}`);
@@ -585,7 +634,7 @@ async function runDevBootstrapLoop(context, template, untilSuccess) {
 async function startManagedDevHub(context, template) {
 	printCompactDevPhase(context, "Hub");
 	printCompactDevPhase(context, "Targets");
-	await withConsoleCapture((method, message) => {
+	return await withConsoleCapture((method, message) => {
 		if (/already running/i.test(message)) {
 			context.info(message.replaceAll("127.0.0.1", "localhost"));
 			return;
@@ -609,6 +658,28 @@ async function startManagedDevHub(context, template) {
 		template
 	}));
 }
+async function waitForDashboardReady(url, options = {}) {
+	const timeoutMs = options.timeoutMs ?? 15e3;
+	const intervalMs = options.intervalMs ?? 250;
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		try {
+			const controller = new AbortController();
+			const timeout = setTimeout(() => controller.abort(), intervalMs);
+			try {
+				const response = await fetch(url, {
+					signal: controller.signal,
+					redirect: "manual"
+				});
+				if (response.ok || response.status === 304) return true;
+			} finally {
+				clearTimeout(timeout);
+			}
+		} catch {}
+		await new Promise((resolve) => setTimeout(resolve, intervalMs));
+	}
+	return false;
+}
 async function runDevFollowup(context, options) {
 	if (options.run) {
 		const target = await resolveOperationalTarget(context, void 0, {
@@ -642,10 +713,13 @@ async function runDevFollowup(context, options) {
 	}
 	if (options.runSh) await runShellCommand(context, options.runSh);
 }
-async function monitorLiveDevSession(context, template) {
-	if (!templateUsesConnectedClients(template)) {
+async function monitorLiveDevSession(context, template, tailLogs) {
+	const stopTailing = tailLogs === "always" ? startRuntimeLogTail(context, context.cwd) : void 0;
+	if (!templateUsesConnectedClients$1(template)) try {
 		await waitForSignal();
 		return;
+	} finally {
+		stopTailing?.();
 	}
 	let knownTargets = /* @__PURE__ */ new Set();
 	let waitingNoticeVisible = false;
@@ -653,7 +727,10 @@ async function monitorLiveDevSession(context, template) {
 		const nextTargets = await listConnectedClientTargets();
 		const nextIds = new Set(nextTargets.map((target) => target.id));
 		for (const target of nextTargets) if (!knownTargets.has(target.id)) context.info(`Client target connected: ${target.id}`);
-		for (const targetId of knownTargets) if (!nextIds.has(targetId)) context.warn(`Client target disconnected: ${targetId}`);
+		for (const targetId of knownTargets) if (!nextIds.has(targetId)) {
+			context.warn(`Client target disconnected: ${targetId}`);
+			if (tailLogs === "errors") await printRecentRuntimeSignals(context, context.cwd);
+		}
 		if (nextTargets.length === 0 && !waitingNoticeVisible) {
 			context.info("Hub ready. Start your app to connect a client target.");
 			waitingNoticeVisible = true;
@@ -668,6 +745,157 @@ async function monitorLiveDevSession(context, template) {
 		await waitForSignal();
 	} finally {
 		clearInterval(interval);
+		stopTailing?.();
+	}
+}
+function validateDevModes(context, options) {
+	if (![
+		"enable",
+		"try",
+		"disable"
+	].includes(options.typecheck)) context.fail(`Unknown typecheck mode ${JSON.stringify(options.typecheck)}. Expected enable, try, or disable.`);
+	if (![
+		"always",
+		"errors",
+		"disable"
+	].includes(options.tailLogs)) context.fail(`Unknown tail log mode ${JSON.stringify(options.tailLogs)}. Expected always, errors, or disable.`);
+}
+function printDevPreflight(context, report) {
+	if (report.status === "missing-generated") {
+		context.info("Preflight: generated Syncore files are missing; dev will refresh them.");
+		return;
+	}
+	if (report.status === "schema-drift") {
+		context.info("Preflight: schema drift detected; dev will refresh local Syncore state where safe.");
+		return;
+	}
+	if (report.status === "waiting-for-client") {
+		context.info("Preflight: this template uses client-managed runtimes; connect the app to unlock live targets.");
+		return;
+	}
+	context.info("Preflight: Syncore project structure and local runtime prerequisites were inspected.");
+}
+async function runDevTypecheck(context, mode) {
+	if (mode === "disable") return {
+		mode,
+		attempted: false,
+		ok: true,
+		summary: "disabled"
+	};
+	const tsconfigPath = await findTypecheckConfig(context.cwd);
+	if (!tsconfigPath) {
+		if (mode === "enable") context.fail("Typecheck was enabled but no tsconfig.json was found in this project.");
+		context.warn("Typecheck skipped because no tsconfig.json was found.");
+		return {
+			mode,
+			attempted: false,
+			ok: true,
+			summary: "skipped (no tsconfig)"
+		};
+	}
+	const tscPath = await findTypeScriptCompiler(context.cwd);
+	if (!tscPath) {
+		if (mode === "enable") context.fail("Typecheck was enabled but no local TypeScript compiler was found.");
+		context.warn("Typecheck skipped because TypeScript is not available in this workspace.");
+		return {
+			mode,
+			attempted: false,
+			ok: true,
+			summary: "skipped (tsc unavailable)"
+		};
+	}
+	context.info(`Typecheck: running tsc --noEmit -p ${path.basename(tsconfigPath)}.`);
+	const result = await runTypeScriptCompiler(context.cwd, tscPath, tsconfigPath);
+	if (result.ok) {
+		context.success("Typecheck passed.");
+		return {
+			mode,
+			attempted: true,
+			ok: true,
+			summary: "passed"
+		};
+	}
+	const detail = summarizeCompilerOutput(result.output);
+	if (mode === "enable") context.fail(`Typecheck failed.${detail ? ` ${detail}` : ""}`, 1, result.output, { category: "validation" });
+	context.warn(`Typecheck reported issues but dev will continue.${detail ? ` ${detail}` : ""}`);
+	return {
+		mode,
+		attempted: true,
+		ok: false,
+		summary: "warning",
+		...detail ? { details: detail } : {}
+	};
+}
+async function findTypecheckConfig(cwd) {
+	for (const candidate of [
+		"tsconfig.json",
+		"tsconfig.app.json",
+		"tsconfig.main.json",
+		"tsconfig.build.json"
+	]) {
+		const resolved = path.join(cwd, candidate);
+		if (await fileExists(resolved)) return resolved;
+	}
+	return null;
+}
+async function findTypeScriptCompiler(cwd) {
+	const executableName = process.platform === "win32" ? "tsc.cmd" : "tsc";
+	let current = cwd;
+	while (true) {
+		const candidate = path.join(current, "node_modules", ".bin", executableName);
+		if (await fileExists(candidate)) return candidate;
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	return null;
+}
+async function runTypeScriptCompiler(cwd, compilerPath, tsconfigPath) {
+	return await new Promise((resolve, reject) => {
+		const isWindowsCmd = process.platform === "win32" && /\.(cmd|bat)$/i.test(compilerPath);
+		const child = spawn(compilerPath, [
+			"--noEmit",
+			"-p",
+			tsconfigPath
+		], {
+			cwd,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			...isWindowsCmd ? { shell: true } : {}
+		});
+		let output = "";
+		child.stdout.on("data", (chunk) => {
+			output += chunk.toString();
+		});
+		child.stderr.on("data", (chunk) => {
+			output += chunk.toString();
+		});
+		child.once("error", reject);
+		child.once("exit", (code) => {
+			resolve({
+				ok: (code ?? 1) === 0,
+				output: output.trim()
+			});
+		});
+	});
+}
+function summarizeCompilerOutput(output) {
+	return output.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+}
+function describeTypecheckStatus(result) {
+	return result.details ? `${result.summary} (${result.details})` : result.summary;
+}
+function describeDevDriftStatus(report) {
+	switch (report.drift.state) {
+		case "clean": return "clean";
+		case "missing-snapshot": return "snapshot refreshed";
+		case "snapshot-outdated": return "snapshot refreshed";
+		case "migration-pending": return "migration review pending";
+		case "destructive": return "blocked";
+		default: return "unavailable";
 	}
 }
 async function requireHubConnection(context) {
@@ -777,8 +1005,41 @@ async function readPersistedLogs(cwd) {
 	}
 	return (await readFile(logPath, "utf8")).split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => JSON.parse(line)).filter((entry) => entry.version === 2).filter((entry) => !shouldSuppressLogEntry(entry));
 }
+async function printRecentRuntimeSignals(context, cwd, limit = 5) {
+	const recent = (await readPersistedLogs(cwd)).slice(-limit);
+	if (recent.length === 0) return;
+	context.info("Recent runtime signals:");
+	for (const entry of recent) process.stdout.write(`  ${formatPersistedLogEntry(entry)}\n`);
+}
+function startRuntimeLogTail(context, cwd) {
+	let seenCount = 0;
+	let disposed = false;
+	const poll = async () => {
+		if (disposed) return;
+		const entries = await readPersistedLogs(cwd);
+		const next = entries.slice(seenCount);
+		for (const entry of next) process.stdout.write(`${formatPersistedLogEntry(entry)}\n`);
+		seenCount = entries.length;
+	};
+	const interval = setInterval(() => {
+		poll();
+	}, 1200);
+	poll();
+	return () => {
+		disposed = true;
+		clearInterval(interval);
+	};
+}
 function normalizeRuntimeEvent(event, runtimeEntry) {
 	const functionName = typeof event.functionName === "string" ? event.functionName : "unknown";
+	const functionComponent = resolveComponentInfoFromFunctionName(functionName);
+	const queryComponent = typeof event.queryId === "string" ? resolveComponentInfoFromFunctionName(formatInvalidatedQueryId(event.queryId)) : void 0;
+	const storageComponent = typeof event.storageId === "string" ? resolveComponentInfoFromScopedValue(event.storageId) : void 0;
+	const componentInfo = typeof event.componentPath === "string" ? {
+		owner: "component",
+		componentPath: event.componentPath,
+		...typeof event.componentName === "string" ? { componentName: event.componentName } : {}
+	} : functionComponent ?? queryComponent ?? storageComponent;
 	const logMessage = typeof event.message === "string" ? event.message : "Syncore log";
 	const resolvedTargetId = event.runtimeId === "syncore-dev-hub" ? "all" : runtimeEntry?.targetId ?? event.runtimeId;
 	const runtimeLabel = event.runtimeId === "syncore-dev-hub" ? "dashboard" : runtimeEntry?.label ?? "runtime";
@@ -798,6 +1059,7 @@ function normalizeRuntimeEvent(event, runtimeEntry) {
 		...entryBase,
 		eventType: event.type,
 		category: "system",
+		...componentInfo ?? {},
 		message: logMessage,
 		event
 	})) return null;
@@ -806,6 +1068,7 @@ function normalizeRuntimeEvent(event, runtimeEntry) {
 			...entryBase,
 			eventType: event.type,
 			category: "query",
+			...componentInfo ?? {},
 			message: `${functionName} executed`,
 			event
 		};
@@ -813,6 +1076,7 @@ function normalizeRuntimeEvent(event, runtimeEntry) {
 			...entryBase,
 			eventType: event.type,
 			category: "system",
+			...componentInfo ?? {},
 			message: `${formatInvalidatedQueryId(event.queryId)} invalidated${typeof event.reason === "string" ? ` (${event.reason})` : ""}`,
 			event
 		};
@@ -820,6 +1084,7 @@ function normalizeRuntimeEvent(event, runtimeEntry) {
 			...entryBase,
 			eventType: event.type,
 			category: "mutation",
+			...componentInfo ?? {},
 			message: Array.isArray(event.changedTables) && event.changedTables.length > 0 ? `${functionName} committed (${event.changedTables.join(", ")})` : `${functionName} committed`,
 			event
 		};
@@ -827,6 +1092,7 @@ function normalizeRuntimeEvent(event, runtimeEntry) {
 			...entryBase,
 			eventType: event.type,
 			category: "action",
+			...componentInfo ?? {},
 			message: typeof event.error === "string" && event.error.length > 0 ? `${functionName} failed: ${event.error}` : `${functionName} completed`,
 			event
 		};
@@ -848,6 +1114,7 @@ function normalizeRuntimeEvent(event, runtimeEntry) {
 			...entryBase,
 			eventType: event.type,
 			category: "system",
+			...componentInfo ?? {},
 			message: `${typeof event.operation === "string" ? event.operation : "update"} ${typeof event.storageId === "string" ? event.storageId : "storage"}`,
 			event
 		};
@@ -855,6 +1122,7 @@ function normalizeRuntimeEvent(event, runtimeEntry) {
 			...entryBase,
 			eventType: event.type,
 			category: "system",
+			...componentInfo ?? {},
 			message: event.type === "log" ? logMessage : humanizeRuntimeEvent(event),
 			event
 		};
@@ -880,6 +1148,22 @@ function formatInvalidatedQueryId(queryId) {
 	if (separatorIndex === -1) return queryId;
 	return queryId.slice(0, separatorIndex);
 }
+function resolveComponentInfoFromFunctionName(functionName) {
+	const match = /^components\/(.+)\/(public|internal)\/(.+)$/.exec(functionName);
+	if (!match) return;
+	return {
+		owner: "component",
+		componentPath: match[1] ?? ""
+	};
+}
+function resolveComponentInfoFromScopedValue(value) {
+	const match = /^component:([^:]+):(.+)$/.exec(value);
+	if (!match) return;
+	return {
+		owner: "component",
+		componentPath: match[1] ?? ""
+	};
+}
 function humanizeRuntimeEvent(event) {
 	if (event.type === "scheduler.tick" && Array.isArray(event.executedJobIds)) return `scheduler tick (${event.executedJobIds.length} job(s))`;
 	return event.type.replaceAll(".", " ");
@@ -949,7 +1233,7 @@ function parseJsonObject(input, label) {
 	try {
 		parsed = JSON.parse(input);
 	} catch (error) {
-		throw new Error(`${label} must be valid JSON: ${formatError(error)}`);
+		throw new Error(`${label} must be valid JSON: ${formatError(error)}`, { cause: error });
 	}
 	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${label} must be a JSON object.`);
 	return parsed;