clivly 0.10.3 → 0.10.5

package/index.cjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-DgAe0_YD.cjs");
+const require_entity_config = require("./entity-config-C2MfIDL2.cjs");
 require("./mapping-score-CaB3F4Uu.cjs");
 const require_internal_entity_heuristics = require("./internal-entity-heuristics.cjs");
-const require_sdk = require("./sdk-B1vX4kUJ.cjs");
+const require_sdk = require("./sdk-DbvqXNSh.cjs");
 let node_child_process = require("node:child_process");
 let node_fs = require("node:fs");
 let node_module = require("node:module");
@@ -12,6 +12,7 @@ let node_path = require("node:path");
 let node_readline_promises = require("node:readline/promises");
 let jiti = require("jiti");
 let node_url = require("node:url");
+let node_net = require("node:net");
 //#region ../core/src/env-file.ts
 const ENV_FILES = {
 	next: ".env.local",
@@ -333,6 +334,28 @@ const TRIGGER_URL_PLACEHOLDER = `https://<yourDomain.com>${CLIVLY_TICK_PATH}`;
 //#region src/dev-tunnel.ts
 const CLOUDFLARE_QUICK_TUNNEL_REGEX = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
 const DEFAULT_PORT = "3000";
+/**
+* The port each framework's dev server actually listens on out of the box.
+*
+* `clivly dev` used to tunnel to 3000 for everyone. Vite-based frameworks start
+* on 5173, so the tunnel pointed at whatever else happened to hold 3000 — in one
+* smoke run, a *different app entirely*, which answered, which made the tunnel
+* look healthy while syncing the wrong project. Every symptom pointed away from
+* the cause.
+*
+* These are defaults, not detections: a project that sets its own port must
+* still pass `--port`. Guessing right for the untouched case is the win.
+*/
+const FRAMEWORK_DEFAULT_PORTS = {
+	remix: "5173",
+	sveltekit: "5173",
+	"tanstack-start": "5173",
+	nextjs: "3000",
+	nuxt: "3000"
+};
+function defaultPortFor(framework) {
+	return (framework && FRAMEWORK_DEFAULT_PORTS[framework]) ?? DEFAULT_PORT;
+}
 const DEFAULT_ROUTE_PATH = CLIVLY_TICK_PATH;
 function parseTunnelUrl(chunk) {
 	const match = chunk.match(CLOUDFLARE_QUICK_TUNNEL_REGEX);
@@ -342,11 +365,50 @@ function buildTriggerUrl(origin, path) {
 	return `${origin.endsWith("/") ? origin.slice(0, -1) : origin}${path.startsWith("/") ? path : `/${path}`}`;
 }
 function resolveDevTarget(flags) {
+	const port = flags.port ?? defaultPortFor(flags.framework);
 	return {
-		target: flags.url ?? `http://localhost:${flags.port ?? DEFAULT_PORT}`,
-		triggerPath: flags.routePath ?? DEFAULT_ROUTE_PATH
+		target: flags.url ?? `http://localhost:${port}`,
+		triggerPath: flags.routePath ?? DEFAULT_ROUTE_PATH,
+		port
 	};
 }
+const VITE_FRAMEWORKS = /* @__PURE__ */ new Set([
+	"nuxt",
+	"remix",
+	"sveltekit",
+	"tanstack-start"
+]);
+function isViteFramework(framework) {
+	return framework ? VITE_FRAMEWORKS.has(framework) : false;
+}
+/**
+* The one config line that makes a Vite dev server answer the tunnel.
+*
+* Without it every sync fails with a bare "The host app returned 403" and the
+* explanation — Vite's own, naming this exact setting — is buried in a
+* diagnostics column. This affects four of the five supported frameworks, so
+* `clivly dev` says it up front rather than letting each developer rediscover
+* it. Printed unconditionally for Vite apps: reading the app's vite config well
+* enough to know whether it is already set means parsing arbitrary TypeScript,
+* and a redundant hint is far cheaper than a silent 403.
+*/
+function viteAllowedHostsHint() {
+	return [
+		"Vite blocks unknown hosts, so the tunnel needs one line in your Vite config:",
+		"  server: { allowedHosts: [\".trycloudflare.com\"] }",
+		"Without it, sync fails with 403 before it reaches your app."
+	].join("\n");
+}
+/**
+* Warns that nothing is listening on the port about to be tunnelled.
+*
+* A quick tunnel to a dead port still resolves and still answers, so the failure
+* surfaces later as an HTTP error attributed to the host app. Naming it here —
+* while the developer is still looking at `clivly dev` output — costs one line.
+*/
+function deadPortMessage(port, framework) {
+	return [`Warning: nothing is listening on port ${port} yet, but the tunnel points there.${framework ? ` ${FRAMEWORK_LABELS[framework]} usually serves on ${defaultPortFor(framework)}.` : ""}`, "If your dev server uses a different port, restart with:  clivly dev --port <port>"].join("\n");
+}
 function detectDevCommand(scripts, explicit) {
 	if (explicit && explicit.length > 0) return explicit;
 	if (scripts.dev) return [
@@ -389,6 +451,76 @@ function cloudflaredMissingMessage() {
 	].join("\n");
 }
 //#endregion
+//#region src/tunnel-identity.ts
+/**
+* Whether the published tunnel actually reaches *this* app's Clivly route.
+*
+* `isLocalPortListening` answers a different question — "is anything accepting
+* connections on this port?" — and that is exactly the gap this closes. On a
+* machine running more than one project (which is what `clivly dev` is for),
+* a framework that finds its default port taken silently moves to the next one:
+*
+*     ⚠ Port 3000 is in use by process 92495, using available port 3001 instead
+*
+* The tunnel is still pointed at 3000, where a *different application* is
+* listening. The port probe sees a healthy socket and says nothing, and the CLI
+* goes on to promise "Dashboard-triggered sync now points at this local
+* session" — which is false. Signed triggers for this workspace are delivered
+* to somebody else's app, and the resulting failure is reported against the
+* innocent one. Liveness is not identity.
+*
+* The check: POST to the trigger path with no signature. A Clivly-mounted route
+* rejects that with **401** — it read the request, found no valid signature and
+* refused. Anything else on that port answers some other way (a framework's
+* 500 error page, a 404, an unrelated 200). We are not testing authentication
+* here; the 401 *is* the fingerprint, and it is one no unrelated service
+* produces at this exact path by accident.
+*
+* Deliberately tolerant: a network hiccup returns `unknown`, never `mismatch`.
+* Warning someone away from a tunnel that was fine is worse than staying quiet,
+* for the same reason the port probe defaults to assuming the port is alive.
+*/
+/** How long to wait before giving up and returning `unknown`. */
+const IDENTITY_PROBE_TIMEOUT_MS = 8e3;
+/**
+* Probe the published tunnel URL and report who is on the other end.
+*
+* `fetchImpl` is injectable so tests do not need a network or a live tunnel.
+*/
+async function probeTunnelIdentity(triggerUrl, fetchImpl = fetch) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), IDENTITY_PROBE_TIMEOUT_MS);
+	try {
+		return (await fetchImpl(triggerUrl, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: "{}",
+			signal: controller.signal
+		})).status === 401 ? "clivly" : "mismatch";
+	} catch {
+		return "unknown";
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* What to tell someone whose tunnel reaches the wrong process.
+*
+* Names the likely cause rather than only the symptom: the overwhelmingly
+* common reason is the port fallback above, and the remedy is to say which
+* port the app really bound.
+*/
+function tunnelMismatchMessage(port) {
+	return [
+		`Warning: the tunnel reaches something on port ${port}, but it is not this app's Clivly route.`,
+		`  The usual cause is a port fallback. If your dev server printed "Port ${port} is in use,`,
+		`  using available port …", it moved and the tunnel stayed on ${port} — where another`,
+		"  project is still listening.",
+		"  Re-run with the port it actually bound: npx clivly dev --port <port>",
+		"  Until then, dashboard-triggered syncs will not reach this app."
+	].join("\n");
+}
+//#endregion
 //#region src/dev.ts
 const UNREACHABLE_RESULT = {
 	ok: false,
@@ -404,10 +536,12 @@ function explicitCommand(argv) {
 }
 async function runDev(options) {
 	const { deps } = options;
-	const { target, triggerPath } = resolveDevTarget({
+	const framework = deps.detectFramework?.(options.cwd);
+	const { target, triggerPath, port } = resolveDevTarget({
 		url: flagValue$1(options.argv, "--url"),
 		port: flagValue$1(options.argv, "--port"),
-		routePath: flagValue$1(options.argv, "--route-path")
+		routePath: flagValue$1(options.argv, "--route-path"),
+		framework
 	});
 	const command = detectDevCommand(deps.readScripts(options.cwd), explicitCommand(options.argv));
 	if (!deps.hasCloudflared()) {
@@ -424,6 +558,7 @@ async function runDev(options) {
 		deps.out("CLIVLY_SECRET_KEY is not set — cannot register the tunnel URL. Set it and re-run.");
 		return 1;
 	}
+	if (isViteFramework(framework)) deps.out(viteAllowedHostsHint());
 	const app = command ? deps.spawnApp(command) : null;
 	const tunnel = deps.spawnTunnel(target);
 	let shuttingDown = false;
@@ -431,8 +566,13 @@ async function runDev(options) {
 		if (shuttingDown) return;
 		const triggerUrl = buildTriggerUrl(origin, triggerPath);
 		deps.out(`Tunnel: ${triggerUrl}`);
+		if (deps.isPortListening && !flagValue$1(options.argv, "--url")) {
+			if (!await deps.isPortListening(port).catch(() => true)) deps.out(deadPortMessage(port, framework));
+		}
+		const identity = deps.probeTunnel && !flagValue$1(options.argv, "--url") ? await deps.probeTunnel(triggerUrl).catch(() => "unknown") : "unknown";
+		if (identity === "mismatch") deps.out(tunnelMismatchMessage(port));
 		const result = await deps.register(triggerUrl).catch(() => UNREACHABLE_RESULT);
-		if (result.ok) deps.out("Dashboard-triggered sync now points at this local session.");
+		if (result.ok) deps.out(identity === "mismatch" ? "Trigger URL registered, but see the warning above before relying on it." : "Dashboard-triggered sync now points at this local session.");
 		else deps.out(overrideFailureMessage(result.kind, result.status));
 	});
 	const stopWatching = deps.watchConfig?.(options.cwd, () => {
@@ -1809,6 +1949,10 @@ const NEXT_INSTRUMENTATION_FLAG_STEP = `Your Next.js version reads instrumentati
 const REMIX_BOOT_STEP = `Start Clivly when your app boots. Add this near the top of app/entry.server.tsx:
       import clivly from "./clivly.config";
       clivly.start().catch((error) => console.warn("[clivly] could not check in:", error));`;
+const MISSING_VITE_CONFIG_STEP = `Could not find a vite config, so nothing starts Clivly when your app boots. Add the plugin to your Vite config:
+      import { clivlyVite } from "clivly/vite";
+      import clivly from "./clivly.config";
+      // then, inside defineConfig: plugins: [clivlyVite(clivly), …]`;
 /** The boot hook as a scaffold entry, or null when this framework is patched. */
 function planBootHook(framework, layout) {
 	const path = bootHookPath(framework, layout);
@@ -2402,7 +2546,7 @@ function planBootPatch(args) {
 	}
 	return {
 		file: null,
-		manual: null
+		manual: MISSING_VITE_CONFIG_STEP
 	};
 }
 function planMutations(args) {
@@ -2426,6 +2570,43 @@ function planWidgetMutations(args) {
 	});
 }
 //#endregion
+//#region src/port-probe.ts
+const PORT_PROBE_TIMEOUT_MS = 1500;
+/** One connect attempt against a single address family. */
+function connectsOn(port, host) {
+	return new Promise((resolve) => {
+		const socket = new node_net.Socket();
+		let settled = false;
+		const finish = (listening) => {
+			if (settled) return;
+			settled = true;
+			socket.destroy();
+			resolve(listening);
+		};
+		socket.setTimeout(PORT_PROBE_TIMEOUT_MS);
+		socket.once("connect", () => finish(true));
+		socket.once("timeout", () => finish(false));
+		socket.once("error", () => finish(false));
+		socket.connect(Number(port), host);
+	});
+}
+/**
+* Whether anything is accepting TCP connections on a local port.
+*
+* Deliberately a bare socket connect rather than an HTTP request: the dev
+* server may legitimately answer 404/403/500 on `/`, and any of those still
+* proves something is listening. Only a refused or timed-out connection means
+* the tunnel is pointed at nothing.
+*
+* Both address families are tried, because Vite binds `::1` ONLY by default —
+* so an IPv4-only probe reports "nothing is listening" while the dev server is
+* running perfectly. A false warning here is worse than none: it sends the
+* developer to fix a port that was already correct.
+*/
+function isLocalPortListening(port) {
+	return Promise.all([connectsOn(port, "127.0.0.1"), connectsOn(port, "::1")]).then((results) => results.some(Boolean));
+}
+//#endregion
 //#region src/quiet-host-output.ts
 /**
 * Run `fn` with the process's stdout/stderr captured. Always restores the
@@ -4005,6 +4186,9 @@ function defaultDevDeps(options) {
 		spawnTunnel: spawnCloudflaredTunnel,
 		spawnApp: spawnAppProcess,
 		readScripts: readPackageScripts,
+		detectFramework: (cwd) => detectFramework(readDeps(cwd)),
+		isPortListening: isLocalPortListening,
+		probeTunnel: (triggerUrl) => probeTunnelIdentity(triggerUrl),
 		register: (triggerUrl) => registerTunnelOverride({
 			apiKey: options.apiKey ?? "",
 			apiUrl: options.apiUrl,

package/index.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { t as CANONICAL_FIELDS } from "./entity-config-C4d3K9CP.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-bC3DX9f1.mjs";
 import "./mapping-score-C68uAqGB.mjs";
 import { hasDefiningColumn, matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./internal-entity-heuristics.mjs";
-import { s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-D6gX0TXS.mjs";
+import { s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-BTzaM8bF.mjs";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, watch, writeFileSync } from "node:fs";
@@ -11,6 +11,7 @@ import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "no
 import { createInterface } from "node:readline/promises";
 import { createJiti } from "jiti";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { Socket } from "node:net";
 //#region ../core/src/env-file.ts
 const ENV_FILES = {
 	next: ".env.local",
@@ -332,6 +333,28 @@ const TRIGGER_URL_PLACEHOLDER = `https://<yourDomain.com>${CLIVLY_TICK_PATH}`;
 //#region src/dev-tunnel.ts
 const CLOUDFLARE_QUICK_TUNNEL_REGEX = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
 const DEFAULT_PORT = "3000";
+/**
+* The port each framework's dev server actually listens on out of the box.
+*
+* `clivly dev` used to tunnel to 3000 for everyone. Vite-based frameworks start
+* on 5173, so the tunnel pointed at whatever else happened to hold 3000 — in one
+* smoke run, a *different app entirely*, which answered, which made the tunnel
+* look healthy while syncing the wrong project. Every symptom pointed away from
+* the cause.
+*
+* These are defaults, not detections: a project that sets its own port must
+* still pass `--port`. Guessing right for the untouched case is the win.
+*/
+const FRAMEWORK_DEFAULT_PORTS = {
+	remix: "5173",
+	sveltekit: "5173",
+	"tanstack-start": "5173",
+	nextjs: "3000",
+	nuxt: "3000"
+};
+function defaultPortFor(framework) {
+	return (framework && FRAMEWORK_DEFAULT_PORTS[framework]) ?? DEFAULT_PORT;
+}
 const DEFAULT_ROUTE_PATH = CLIVLY_TICK_PATH;
 function parseTunnelUrl(chunk) {
 	const match = chunk.match(CLOUDFLARE_QUICK_TUNNEL_REGEX);
@@ -341,11 +364,50 @@ function buildTriggerUrl(origin, path) {
 	return `${origin.endsWith("/") ? origin.slice(0, -1) : origin}${path.startsWith("/") ? path : `/${path}`}`;
 }
 function resolveDevTarget(flags) {
+	const port = flags.port ?? defaultPortFor(flags.framework);
 	return {
-		target: flags.url ?? `http://localhost:${flags.port ?? DEFAULT_PORT}`,
-		triggerPath: flags.routePath ?? DEFAULT_ROUTE_PATH
+		target: flags.url ?? `http://localhost:${port}`,
+		triggerPath: flags.routePath ?? DEFAULT_ROUTE_PATH,
+		port
 	};
 }
+const VITE_FRAMEWORKS = /* @__PURE__ */ new Set([
+	"nuxt",
+	"remix",
+	"sveltekit",
+	"tanstack-start"
+]);
+function isViteFramework(framework) {
+	return framework ? VITE_FRAMEWORKS.has(framework) : false;
+}
+/**
+* The one config line that makes a Vite dev server answer the tunnel.
+*
+* Without it every sync fails with a bare "The host app returned 403" and the
+* explanation — Vite's own, naming this exact setting — is buried in a
+* diagnostics column. This affects four of the five supported frameworks, so
+* `clivly dev` says it up front rather than letting each developer rediscover
+* it. Printed unconditionally for Vite apps: reading the app's vite config well
+* enough to know whether it is already set means parsing arbitrary TypeScript,
+* and a redundant hint is far cheaper than a silent 403.
+*/
+function viteAllowedHostsHint() {
+	return [
+		"Vite blocks unknown hosts, so the tunnel needs one line in your Vite config:",
+		"  server: { allowedHosts: [\".trycloudflare.com\"] }",
+		"Without it, sync fails with 403 before it reaches your app."
+	].join("\n");
+}
+/**
+* Warns that nothing is listening on the port about to be tunnelled.
+*
+* A quick tunnel to a dead port still resolves and still answers, so the failure
+* surfaces later as an HTTP error attributed to the host app. Naming it here —
+* while the developer is still looking at `clivly dev` output — costs one line.
+*/
+function deadPortMessage(port, framework) {
+	return [`Warning: nothing is listening on port ${port} yet, but the tunnel points there.${framework ? ` ${FRAMEWORK_LABELS[framework]} usually serves on ${defaultPortFor(framework)}.` : ""}`, "If your dev server uses a different port, restart with:  clivly dev --port <port>"].join("\n");
+}
 function detectDevCommand(scripts, explicit) {
 	if (explicit && explicit.length > 0) return explicit;
 	if (scripts.dev) return [
@@ -388,6 +450,76 @@ function cloudflaredMissingMessage() {
 	].join("\n");
 }
 //#endregion
+//#region src/tunnel-identity.ts
+/**
+* Whether the published tunnel actually reaches *this* app's Clivly route.
+*
+* `isLocalPortListening` answers a different question — "is anything accepting
+* connections on this port?" — and that is exactly the gap this closes. On a
+* machine running more than one project (which is what `clivly dev` is for),
+* a framework that finds its default port taken silently moves to the next one:
+*
+*     ⚠ Port 3000 is in use by process 92495, using available port 3001 instead
+*
+* The tunnel is still pointed at 3000, where a *different application* is
+* listening. The port probe sees a healthy socket and says nothing, and the CLI
+* goes on to promise "Dashboard-triggered sync now points at this local
+* session" — which is false. Signed triggers for this workspace are delivered
+* to somebody else's app, and the resulting failure is reported against the
+* innocent one. Liveness is not identity.
+*
+* The check: POST to the trigger path with no signature. A Clivly-mounted route
+* rejects that with **401** — it read the request, found no valid signature and
+* refused. Anything else on that port answers some other way (a framework's
+* 500 error page, a 404, an unrelated 200). We are not testing authentication
+* here; the 401 *is* the fingerprint, and it is one no unrelated service
+* produces at this exact path by accident.
+*
+* Deliberately tolerant: a network hiccup returns `unknown`, never `mismatch`.
+* Warning someone away from a tunnel that was fine is worse than staying quiet,
+* for the same reason the port probe defaults to assuming the port is alive.
+*/
+/** How long to wait before giving up and returning `unknown`. */
+const IDENTITY_PROBE_TIMEOUT_MS = 8e3;
+/**
+* Probe the published tunnel URL and report who is on the other end.
+*
+* `fetchImpl` is injectable so tests do not need a network or a live tunnel.
+*/
+async function probeTunnelIdentity(triggerUrl, fetchImpl = fetch) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), IDENTITY_PROBE_TIMEOUT_MS);
+	try {
+		return (await fetchImpl(triggerUrl, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: "{}",
+			signal: controller.signal
+		})).status === 401 ? "clivly" : "mismatch";
+	} catch {
+		return "unknown";
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* What to tell someone whose tunnel reaches the wrong process.
+*
+* Names the likely cause rather than only the symptom: the overwhelmingly
+* common reason is the port fallback above, and the remedy is to say which
+* port the app really bound.
+*/
+function tunnelMismatchMessage(port) {
+	return [
+		`Warning: the tunnel reaches something on port ${port}, but it is not this app's Clivly route.`,
+		`  The usual cause is a port fallback. If your dev server printed "Port ${port} is in use,`,
+		`  using available port …", it moved and the tunnel stayed on ${port} — where another`,
+		"  project is still listening.",
+		"  Re-run with the port it actually bound: npx clivly dev --port <port>",
+		"  Until then, dashboard-triggered syncs will not reach this app."
+	].join("\n");
+}
+//#endregion
 //#region src/dev.ts
 const UNREACHABLE_RESULT = {
 	ok: false,
@@ -403,10 +535,12 @@ function explicitCommand(argv) {
 }
 async function runDev(options) {
 	const { deps } = options;
-	const { target, triggerPath } = resolveDevTarget({
+	const framework = deps.detectFramework?.(options.cwd);
+	const { target, triggerPath, port } = resolveDevTarget({
 		url: flagValue$1(options.argv, "--url"),
 		port: flagValue$1(options.argv, "--port"),
-		routePath: flagValue$1(options.argv, "--route-path")
+		routePath: flagValue$1(options.argv, "--route-path"),
+		framework
 	});
 	const command = detectDevCommand(deps.readScripts(options.cwd), explicitCommand(options.argv));
 	if (!deps.hasCloudflared()) {
@@ -423,6 +557,7 @@ async function runDev(options) {
 		deps.out("CLIVLY_SECRET_KEY is not set — cannot register the tunnel URL. Set it and re-run.");
 		return 1;
 	}
+	if (isViteFramework(framework)) deps.out(viteAllowedHostsHint());
 	const app = command ? deps.spawnApp(command) : null;
 	const tunnel = deps.spawnTunnel(target);
 	let shuttingDown = false;
@@ -430,8 +565,13 @@ async function runDev(options) {
 		if (shuttingDown) return;
 		const triggerUrl = buildTriggerUrl(origin, triggerPath);
 		deps.out(`Tunnel: ${triggerUrl}`);
+		if (deps.isPortListening && !flagValue$1(options.argv, "--url")) {
+			if (!await deps.isPortListening(port).catch(() => true)) deps.out(deadPortMessage(port, framework));
+		}
+		const identity = deps.probeTunnel && !flagValue$1(options.argv, "--url") ? await deps.probeTunnel(triggerUrl).catch(() => "unknown") : "unknown";
+		if (identity === "mismatch") deps.out(tunnelMismatchMessage(port));
 		const result = await deps.register(triggerUrl).catch(() => UNREACHABLE_RESULT);
-		if (result.ok) deps.out("Dashboard-triggered sync now points at this local session.");
+		if (result.ok) deps.out(identity === "mismatch" ? "Trigger URL registered, but see the warning above before relying on it." : "Dashboard-triggered sync now points at this local session.");
 		else deps.out(overrideFailureMessage(result.kind, result.status));
 	});
 	const stopWatching = deps.watchConfig?.(options.cwd, () => {
@@ -1808,6 +1948,10 @@ const NEXT_INSTRUMENTATION_FLAG_STEP = `Your Next.js version reads instrumentati
 const REMIX_BOOT_STEP = `Start Clivly when your app boots. Add this near the top of app/entry.server.tsx:
       import clivly from "./clivly.config";
       clivly.start().catch((error) => console.warn("[clivly] could not check in:", error));`;
+const MISSING_VITE_CONFIG_STEP = `Could not find a vite config, so nothing starts Clivly when your app boots. Add the plugin to your Vite config:
+      import { clivlyVite } from "clivly/vite";
+      import clivly from "./clivly.config";
+      // then, inside defineConfig: plugins: [clivlyVite(clivly), …]`;
 /** The boot hook as a scaffold entry, or null when this framework is patched. */
 function planBootHook(framework, layout) {
 	const path = bootHookPath(framework, layout);
@@ -2401,7 +2545,7 @@ function planBootPatch(args) {
 	}
 	return {
 		file: null,
-		manual: null
+		manual: MISSING_VITE_CONFIG_STEP
 	};
 }
 function planMutations(args) {
@@ -2425,6 +2569,43 @@ function planWidgetMutations(args) {
 	});
 }
 //#endregion
+//#region src/port-probe.ts
+const PORT_PROBE_TIMEOUT_MS = 1500;
+/** One connect attempt against a single address family. */
+function connectsOn(port, host) {
+	return new Promise((resolve) => {
+		const socket = new Socket();
+		let settled = false;
+		const finish = (listening) => {
+			if (settled) return;
+			settled = true;
+			socket.destroy();
+			resolve(listening);
+		};
+		socket.setTimeout(PORT_PROBE_TIMEOUT_MS);
+		socket.once("connect", () => finish(true));
+		socket.once("timeout", () => finish(false));
+		socket.once("error", () => finish(false));
+		socket.connect(Number(port), host);
+	});
+}
+/**
+* Whether anything is accepting TCP connections on a local port.
+*
+* Deliberately a bare socket connect rather than an HTTP request: the dev
+* server may legitimately answer 404/403/500 on `/`, and any of those still
+* proves something is listening. Only a refused or timed-out connection means
+* the tunnel is pointed at nothing.
+*
+* Both address families are tried, because Vite binds `::1` ONLY by default —
+* so an IPv4-only probe reports "nothing is listening" while the dev server is
+* running perfectly. A false warning here is worse than none: it sends the
+* developer to fix a port that was already correct.
+*/
+function isLocalPortListening(port) {
+	return Promise.all([connectsOn(port, "127.0.0.1"), connectsOn(port, "::1")]).then((results) => results.some(Boolean));
+}
+//#endregion
 //#region src/quiet-host-output.ts
 /**
 * Run `fn` with the process's stdout/stderr captured. Always restores the
@@ -4004,6 +4185,9 @@ function defaultDevDeps(options) {
 		spawnTunnel: spawnCloudflaredTunnel,
 		spawnApp: spawnAppProcess,
 		readScripts: readPackageScripts,
+		detectFramework: (cwd) => detectFramework(readDeps(cwd)),
+		isPortListening: isLocalPortListening,
+		probeTunnel: (triggerUrl) => probeTunnelIdentity(triggerUrl),
 		register: (triggerUrl) => registerTunnelOverride({
 			apiKey: options.apiKey ?? "",
 			apiUrl: options.apiUrl,

package/{integration-state-D8SLu228.d.cts → integration-state-BA4c0RbD.d.cts}

@@ -14,6 +14,14 @@ interface RunFact {
   at: number;
   message?: string;
   ok: boolean;
+  /**
+   * The HTTP status the host answered with, when there was one.
+   *
+   * Absent for a run that failed before any response existed, and for callers
+   * that do not track it — so every read must treat `undefined` as "unknown",
+   * never as "fine".
+   */
+  status?: number;
 }
 /**
  * Where the reporting app is running, as the app itself understands it.
@@ -44,6 +52,13 @@ interface IntegrationFacts {
   heartbeatIntervalMs?: number | null;
   lastHeartbeatAt: number | null;
   lastRun: RunFact | null;
+  /**
+   * Whether any entity is mapped, expressed as a number for historical
+   * reasons — every producer sets it to 0 or 1, never a real total. Read it as
+   * a flag (`> 0`) and never render it as a quantity: doing so reported "1
+   * entity mapped" to a workspace with three. The true count lives on the
+   * mappings list, which the What syncs tab reads directly.
+   */
   mappedEntityCount: number;
   now: number;
   /**

package/{integration-state-D8SLu228.d.mts → integration-state-BA4c0RbD.d.mts}

@@ -14,6 +14,14 @@ interface RunFact {
   at: number;
   message?: string;
   ok: boolean;
+  /**
+   * The HTTP status the host answered with, when there was one.
+   *
+   * Absent for a run that failed before any response existed, and for callers
+   * that do not track it — so every read must treat `undefined` as "unknown",
+   * never as "fine".
+   */
+  status?: number;
 }
 /**
  * Where the reporting app is running, as the app itself understands it.
@@ -44,6 +52,13 @@ interface IntegrationFacts {
   heartbeatIntervalMs?: number | null;
   lastHeartbeatAt: number | null;
   lastRun: RunFact | null;
+  /**
+   * Whether any entity is mapped, expressed as a number for historical
+   * reasons — every producer sets it to 0 or 1, never a real total. Read it as
+   * a flag (`> 0`) and never render it as a quantity: doing so reported "1
+   * entity mapped" to a workspace with three. The true count lives on the
+   * mappings list, which the What syncs tab reads directly.
+   */
   mappedEntityCount: number;
   now: number;
   /**

package/{internal-BAOG5eE4.d.mts → internal-CHvZMvxC.d.cts}

@@ -1,4 +1,4 @@
-import { F as ProjectionMapping, P as ProjectionJoin, h as FilterExpr, l as ConfigValidationError, m as DiscoveredSchemaTable, p as DiscoveredColumnMeta } from "./entity-config-DNQAMbMS.mjs";
+import { L as ProjectionJoin, R as ProjectionMapping, h as FilterExpr, l as ConfigValidationError, m as DiscoveredSchemaTable, p as DiscoveredColumnMeta } from "./entity-config-w8oMBWf8.cjs";
 //#region ../core/src/projection-cardinality.d.ts
 declare function joinFansOut(join: ProjectionJoin, joinTable: DiscoveredSchemaTable): boolean;
 /** Every join in the projection that can multiply rows. */

package/{internal-BHJ0X3fC.d.cts → internal-WximMGmH.d.mts}

@@ -1,4 +1,4 @@
-import { F as ProjectionMapping, P as ProjectionJoin, h as FilterExpr, l as ConfigValidationError, m as DiscoveredSchemaTable, p as DiscoveredColumnMeta } from "./entity-config-DNQAMbMS.cjs";
+import { L as ProjectionJoin, R as ProjectionMapping, h as FilterExpr, l as ConfigValidationError, m as DiscoveredSchemaTable, p as DiscoveredColumnMeta } from "./entity-config-w8oMBWf8.mjs";
 //#region ../core/src/projection-cardinality.d.ts
 declare function joinFansOut(join: ProjectionJoin, joinTable: DiscoveredSchemaTable): boolean;
 /** Every join in the projection that can multiply rows. */

package/internal-drizzle.d.cts

@@ -1,2 +1,2 @@
-import { n as buildUniqueConstraints, r as discoverFromDrizzle, t as buildColumnsMeta } from "./drizzle-DTOuGXEn.cjs";
+import { n as buildUniqueConstraints, r as discoverFromDrizzle, t as buildColumnsMeta } from "./drizzle-SD8WCvYj.cjs";
 export { buildColumnsMeta, buildUniqueConstraints, discoverFromDrizzle };

package/internal-drizzle.d.mts

@@ -1,2 +1,2 @@
-import { n as buildUniqueConstraints, r as discoverFromDrizzle, t as buildColumnsMeta } from "./drizzle-SGapoly2.mjs";
+import { n as buildUniqueConstraints, r as discoverFromDrizzle, t as buildColumnsMeta } from "./drizzle-axugRJ0u.mjs";
 export { buildColumnsMeta, buildUniqueConstraints, discoverFromDrizzle };