clivly 0.9.4 → 0.9.5

package/README.md

@@ -87,7 +87,10 @@ Detects your framework, ORM, auth adapter and app layout, then scaffolds:
 | The auth-verify route for your framework | Yes — `--force` to overwrite |
 
 Plus `CLIVLY_SECRET_KEY`, `CLIVLY_SYNC_TRIGGER_URL` and
-`CLIVLY_SYNC_TRIGGER_SECRET` placeholders in your env file.
+`CLIVLY_SYNC_TRIGGER_SECRET` in your env file. The two secrets are written
+empty, for you or `clivly login` to fill; the trigger URL gets a visible
+`https://<yourDomain.com>/api/clivly/tick` template, because there the shape is
+the documentation.
 
 | Flag | Purpose |
 | --- | --- |
@@ -233,7 +236,7 @@ the CLI requires pairing.
 | --- | --- | --- |
 | `CLIVLY_SECRET_KEY` | Dashboard → **Connect app**, or **Settings → API keys** | **Shown once.** Copy it immediately; you cannot retrieve it later, only regenerate. Regenerating **revokes the previous key**, so redeploy after rotating. The legacy name `CLIVLY_API_KEY` is still accepted as a fallback |
 | `CLIVLY_SYNC_TRIGGER_SECRET` | Dashboard → **Integrations → Remote sync** | Must match the value in your app's env exactly. A mismatch surfaces as a `401` on the signed trigger |
-| `CLIVLY_SYNC_TRIGGER_URL` | Your own deployment | The public URL of your mounted tick route, e.g. `https://app.example.com/api/clivly/tick`. Optional until you deploy — push-only setups can leave it unset |
+| `CLIVLY_SYNC_TRIGGER_URL` | Your own deployment | The public URL of your mounted tick route. `init` and `login` both scaffold it as `https://<yourDomain.com>/api/clivly/tick` — the angle brackets mark it unedited, and the SDK ignores it until you replace them, so leaving it alone costs nothing. Optional until you deploy — push-only setups can leave it as the template |
 | `CLIVLY_PUBLISHABLE_KEY` | Same place as the secret key | Only needed for the chat widget. Safe to expose in client code |
 
 Write them into the env file of the package that imports `clivly`, then re-run
@@ -265,7 +268,7 @@ It answers two questions under two headings:
   scope; `clivly doctor` is local by definition and omits it.
 - **This project** — the local ladder, run here on your machine: credential →
   Clivly reachable → `clivly.config` loads → `clivly.config` is edge-safe →
-  setup checks → sync trigger URL.
+  boot hook wired → setup checks → sync trigger URL.
 
 ```text
 Clivly status
@@ -278,11 +281,23 @@ Workspace
   🔒 Let Clivly start a sync
 
 This project
-  ✅ Step 1 of 6 · API key present
-  ✅ Step 2 of 6 · Clivly reachable — Acme
+  ✅ Step 1 of 7 · API key present
+  ✅ Step 2 of 7 · Clivly reachable — Acme
   ...
 ```
 
+**Boot hook wired** is the rung to know about. It finds the boot site for your
+framework and confirms something there actually starts Clivly — and on Next.js
+below 15, that `experimental.instrumentationHook` is set in `next.config`,
+without which `instrumentation.ts` is ignored outright and your app never checks
+in. That failure is otherwise completely silent: the file is present, the config
+loads, the credentials work, and the dashboard stays empty.
+
+It is the one rung with no prerequisites, so it still reports when the config
+above it fails to load. A framework the CLI does not recognise shows it as
+skipped rather than passed — there is nowhere known to look, and a green step
+for an unasked question is what made this worth adding.
+
 If the Workspace section reads
 `⚠️ This Clivly server does not report setup progress`, or names a rejected key
 or an unreachable host, that means the question could not be asked — not that
@@ -406,7 +421,7 @@ work, and are kept because output and docs have recommended them — but prefer
 | --- | --- |
 | `clivly ping` | Credential + reachability |
 | `clivly connect` | The above, plus config and trigger URL |
-| `clivly doctor` | Config, setup checks and edge safety |
+| `clivly doctor` | Config, edge safety, boot hook and setup checks |
 
 Each prints a deprecation notice, then the steps it covers, renumbered to its own
 scope:
@@ -478,6 +493,8 @@ socket reconnect. The CLI does not enable this setting on your behalf.
 | `init` cannot find your schema | Pass `--schema <path\|package>` |
 | `init` scaffolded a `db` import that doesn't resolve | The probe cannot evaluate a db module that throws without `DATABASE_URL`. Fix the `TODO(clivly)` import path it left, or pass `--db-import` |
 | `clivly login` exits non-zero, pairing unavailable | The backend has `CLIVLY_CLI_PAIRING_ENABLED` off. Use the manual credential path above |
+| App runs, no errors, dashboard stays silent | Run `clivly status` — the **Boot hook wired** step names the cause. On Next.js below 15 it is almost always the missing `experimental: { instrumentationHook: true }` in `next.config` |
+| `Clivly reachable` fails with `invalid_api_key` (401) | The key is not one this org accepts. Re-run `npx clivly login` to re-pair, and check the key belongs to the org whose dashboard you are watching |
 | `clivly dev` cannot start | Install `cloudflared`, or set `CLIVLY_SYNC_TRIGGER_URL` to a tunnel you run yourself |
 | Credentials written but the app never loads them | Wrong env file for your framework — see the table under `clivly login` |
 

package/index.cjs

@@ -974,7 +974,7 @@ function isKeySet(contents, key) {
 function appendEnvKeys(existing, entries) {
 	const missing = entries.filter((e) => !hasKey$1(existing, e.key));
 	if (missing.length === 0) return existing;
-	const block = missing.map((e) => `${e.comment ? `# ${e.comment}\n` : ""}${e.key}=`).join("\n");
+	const block = missing.map((e) => `${e.comment ? `# ${e.comment}\n` : ""}${e.key}=${e.value ?? ""}`).join("\n");
 	return `${existing}${existing.length > 0 && !existing.endsWith("\n") ? "\n" : ""}${existing.length > 0 ? "\n" : ""}# Clivly\n${block}\n`;
 }
 /**
@@ -1810,7 +1810,8 @@ const CLIVLY_ENV_KEYS = [
 	},
 	{
 		key: "CLIVLY_SYNC_TRIGGER_URL",
-		comment: "Public URL of your mounted tick route (e.g. https://app.example.com/api/clivly/tick)"
+		value: TRIGGER_URL_PLACEHOLDER,
+		comment: "Public URL of your tick route — replace <yourDomain.com> once deployed. Local dev: run `clivly dev` instead."
 	},
 	{
 		key: "CLIVLY_SYNC_TRIGGER_SECRET",
@@ -2741,6 +2742,103 @@ function ladderExitCode(results) {
 	return results.every((result) => result.state !== "fail" && result.state !== "pending") ? 0 : 1;
 }
 //#endregion
+//#region src/boot-hook-check.ts
+const REMIX_ENTRY_CANDIDATES = [
+	"app/entry.server.tsx",
+	"app/entry.server.ts",
+	"app/entry.server.jsx",
+	"app/entry.server.js"
+];
+const NEXT_CONFIG_CANDIDATES = [
+	"next.config.ts",
+	"next.config.mjs",
+	"next.config.js",
+	"next.config.cjs",
+	"next.config.mts"
+];
+const CLIVLY_MENTION = /clivly/i;
+const INSTRUMENTATION_HOOK_ENABLED = /instrumentationHook\s*:\s*true/;
+/**
+* Where this framework's boot hook lives, most likely location first.
+*
+* The file-owning frameworks are asked of `boot-hook.ts` rather than restated,
+* so a path change there cannot leave this check hunting for a file `init` no
+* longer writes. The other two are patched into a file the app already owns.
+*/
+function bootSiteCandidates(framework) {
+	const owned = [bootHookPath(framework, "app"), bootHookPath(framework, "src/app")].filter((path) => path !== null);
+	if (owned.length > 0) return [...new Set(owned)];
+	if (framework === "tanstack-start") return [...VITE_CONFIG_CANDIDATES];
+	if (framework === "remix") return REMIX_ENTRY_CANDIDATES;
+	return [];
+}
+function declaredDeps(readFile) {
+	const raw = readFile("package.json");
+	if (raw === null) return null;
+	try {
+		const pkg = JSON.parse(raw);
+		return {
+			...pkg.dependencies,
+			...pkg.devDependencies
+		};
+	} catch {
+		return null;
+	}
+}
+function findBootSite(readFile, framework) {
+	for (const candidate of bootSiteCandidates(framework)) {
+		const source = readFile(candidate);
+		if (source !== null && CLIVLY_MENTION.test(source)) return candidate;
+	}
+	return null;
+}
+/**
+* On Next.js below 15 the hook file is ignored unless the flag is on, so a
+* present-and-correct instrumentation.ts is not evidence of anything. A missing
+* next.config is the same failure as one without the flag: either way nothing
+* switches the hook on.
+*/
+function nextFlagVerdict(readFile, version, site) {
+	if (!nextNeedsInstrumentationFlag(version)) return null;
+	for (const candidate of NEXT_CONFIG_CANDIDATES) {
+		const source = readFile(candidate);
+		if (source !== null && INSTRUMENTATION_HOOK_ENABLED.test(source)) return null;
+	}
+	return {
+		state: "broken",
+		detail: `${site} exists, but Next.js ${version} ignores it — experimental.instrumentationHook is not enabled in next.config.`,
+		hint: NEXT_INSTRUMENTATION_FLAG_STEP
+	};
+}
+function checkBootHook(readFile) {
+	const deps = declaredDeps(readFile);
+	if (deps === null) return {
+		state: "unknown",
+		detail: "package.json not readable — cannot tell how this app boots."
+	};
+	const framework = detectFramework(deps);
+	if (framework === "unknown") return {
+		state: "unknown",
+		detail: "No supported framework detected, so there is no known place to check."
+	};
+	const label = FRAMEWORK_LABELS[framework];
+	const site = findBootSite(readFile, framework);
+	if (site === null) return {
+		state: "broken",
+		detail: `No Clivly boot hook found in this ${label} app.`,
+		hint: `Nothing starts the SDK, so your app never tells Clivly it is running — the dashboard stays silent with no error anywhere. Run \`clivly init\` to scaffold it, or call \`clivly.start()\` where your server boots (${bootSiteCandidates(framework)[0]}).`
+	};
+	const nextVersion = deps.next;
+	if (framework === "nextjs" && nextVersion) {
+		const broken = nextFlagVerdict(readFile, nextVersion, site);
+		if (broken) return broken;
+	}
+	return {
+		state: "ok",
+		detail: site
+	};
+}
+//#endregion
 //#region src/edge-safety.ts
 const NODE_BUILTINS = /* @__PURE__ */ new Set([
 	"assert",
@@ -2927,7 +3025,7 @@ function pingOnce(ctx) {
 }
 const REASON_HINT = {
 	ok: "",
-	invalid_api_key: "The key was rejected (401). Check CLIVLY_SECRET_KEY (or legacy CLIVLY_API_KEY).",
+	invalid_api_key: "The key was rejected (401). Run `clivly login` to re-pair and rewrite the credentials, and check CLIVLY_SECRET_KEY (or legacy CLIVLY_API_KEY) belongs to the org whose dashboard you are watching.",
 	forbidden: "The key is valid but lacks access to this org (403).",
 	rate_limited: "Rate limited (429). Wait a moment and retry.",
 	server_error: "Clivly returned a server error (5xx). Retry shortly.",
@@ -3083,6 +3181,24 @@ const STATUS_STAGES = [
 			});
 		}
 	},
+	{
+		id: "boot-hook",
+		label: "Boot hook wired",
+		run(ctx) {
+			const read = ctx.readConfigSource ?? defaultReadConfigSource;
+			const root = (0, node_path.dirname)(ctx.configPath);
+			const verdict = checkBootHook((relative) => read((0, node_path.resolve)(root, relative)));
+			if (verdict.state === "ok") return Promise.resolve({
+				state: "pass",
+				detail: `starts Clivly from ${verdict.detail}`
+			});
+			return Promise.resolve({
+				state: verdict.state === "unknown" ? "skip" : "fail",
+				detail: verdict.detail,
+				hint: verdict.hint
+			});
+		}
+	},
 	sdkChecksStage,
 	triggerUrlStage
 ];
@@ -3136,6 +3252,7 @@ const ALIAS_STAGE_IDS = {
 	doctor: [
 		"config",
 		"runtime",
+		"boot-hook",
 		"setup-checks"
 	],
 	connect: [

package/index.mjs

@@ -973,7 +973,7 @@ function isKeySet(contents, key) {
 function appendEnvKeys(existing, entries) {
 	const missing = entries.filter((e) => !hasKey$1(existing, e.key));
 	if (missing.length === 0) return existing;
-	const block = missing.map((e) => `${e.comment ? `# ${e.comment}\n` : ""}${e.key}=`).join("\n");
+	const block = missing.map((e) => `${e.comment ? `# ${e.comment}\n` : ""}${e.key}=${e.value ?? ""}`).join("\n");
 	return `${existing}${existing.length > 0 && !existing.endsWith("\n") ? "\n" : ""}${existing.length > 0 ? "\n" : ""}# Clivly\n${block}\n`;
 }
 /**
@@ -1809,7 +1809,8 @@ const CLIVLY_ENV_KEYS = [
 	},
 	{
 		key: "CLIVLY_SYNC_TRIGGER_URL",
-		comment: "Public URL of your mounted tick route (e.g. https://app.example.com/api/clivly/tick)"
+		value: TRIGGER_URL_PLACEHOLDER,
+		comment: "Public URL of your tick route — replace <yourDomain.com> once deployed. Local dev: run `clivly dev` instead."
 	},
 	{
 		key: "CLIVLY_SYNC_TRIGGER_SECRET",
@@ -2740,6 +2741,103 @@ function ladderExitCode(results) {
 	return results.every((result) => result.state !== "fail" && result.state !== "pending") ? 0 : 1;
 }
 //#endregion
+//#region src/boot-hook-check.ts
+const REMIX_ENTRY_CANDIDATES = [
+	"app/entry.server.tsx",
+	"app/entry.server.ts",
+	"app/entry.server.jsx",
+	"app/entry.server.js"
+];
+const NEXT_CONFIG_CANDIDATES = [
+	"next.config.ts",
+	"next.config.mjs",
+	"next.config.js",
+	"next.config.cjs",
+	"next.config.mts"
+];
+const CLIVLY_MENTION = /clivly/i;
+const INSTRUMENTATION_HOOK_ENABLED = /instrumentationHook\s*:\s*true/;
+/**
+* Where this framework's boot hook lives, most likely location first.
+*
+* The file-owning frameworks are asked of `boot-hook.ts` rather than restated,
+* so a path change there cannot leave this check hunting for a file `init` no
+* longer writes. The other two are patched into a file the app already owns.
+*/
+function bootSiteCandidates(framework) {
+	const owned = [bootHookPath(framework, "app"), bootHookPath(framework, "src/app")].filter((path) => path !== null);
+	if (owned.length > 0) return [...new Set(owned)];
+	if (framework === "tanstack-start") return [...VITE_CONFIG_CANDIDATES];
+	if (framework === "remix") return REMIX_ENTRY_CANDIDATES;
+	return [];
+}
+function declaredDeps(readFile) {
+	const raw = readFile("package.json");
+	if (raw === null) return null;
+	try {
+		const pkg = JSON.parse(raw);
+		return {
+			...pkg.dependencies,
+			...pkg.devDependencies
+		};
+	} catch {
+		return null;
+	}
+}
+function findBootSite(readFile, framework) {
+	for (const candidate of bootSiteCandidates(framework)) {
+		const source = readFile(candidate);
+		if (source !== null && CLIVLY_MENTION.test(source)) return candidate;
+	}
+	return null;
+}
+/**
+* On Next.js below 15 the hook file is ignored unless the flag is on, so a
+* present-and-correct instrumentation.ts is not evidence of anything. A missing
+* next.config is the same failure as one without the flag: either way nothing
+* switches the hook on.
+*/
+function nextFlagVerdict(readFile, version, site) {
+	if (!nextNeedsInstrumentationFlag(version)) return null;
+	for (const candidate of NEXT_CONFIG_CANDIDATES) {
+		const source = readFile(candidate);
+		if (source !== null && INSTRUMENTATION_HOOK_ENABLED.test(source)) return null;
+	}
+	return {
+		state: "broken",
+		detail: `${site} exists, but Next.js ${version} ignores it — experimental.instrumentationHook is not enabled in next.config.`,
+		hint: NEXT_INSTRUMENTATION_FLAG_STEP
+	};
+}
+function checkBootHook(readFile) {
+	const deps = declaredDeps(readFile);
+	if (deps === null) return {
+		state: "unknown",
+		detail: "package.json not readable — cannot tell how this app boots."
+	};
+	const framework = detectFramework(deps);
+	if (framework === "unknown") return {
+		state: "unknown",
+		detail: "No supported framework detected, so there is no known place to check."
+	};
+	const label = FRAMEWORK_LABELS[framework];
+	const site = findBootSite(readFile, framework);
+	if (site === null) return {
+		state: "broken",
+		detail: `No Clivly boot hook found in this ${label} app.`,
+		hint: `Nothing starts the SDK, so your app never tells Clivly it is running — the dashboard stays silent with no error anywhere. Run \`clivly init\` to scaffold it, or call \`clivly.start()\` where your server boots (${bootSiteCandidates(framework)[0]}).`
+	};
+	const nextVersion = deps.next;
+	if (framework === "nextjs" && nextVersion) {
+		const broken = nextFlagVerdict(readFile, nextVersion, site);
+		if (broken) return broken;
+	}
+	return {
+		state: "ok",
+		detail: site
+	};
+}
+//#endregion
 //#region src/edge-safety.ts
 const NODE_BUILTINS = /* @__PURE__ */ new Set([
 	"assert",
@@ -2926,7 +3024,7 @@ function pingOnce(ctx) {
 }
 const REASON_HINT = {
 	ok: "",
-	invalid_api_key: "The key was rejected (401). Check CLIVLY_SECRET_KEY (or legacy CLIVLY_API_KEY).",
+	invalid_api_key: "The key was rejected (401). Run `clivly login` to re-pair and rewrite the credentials, and check CLIVLY_SECRET_KEY (or legacy CLIVLY_API_KEY) belongs to the org whose dashboard you are watching.",
 	forbidden: "The key is valid but lacks access to this org (403).",
 	rate_limited: "Rate limited (429). Wait a moment and retry.",
 	server_error: "Clivly returned a server error (5xx). Retry shortly.",
@@ -3082,6 +3180,24 @@ const STATUS_STAGES = [
 			});
 		}
 	},
+	{
+		id: "boot-hook",
+		label: "Boot hook wired",
+		run(ctx) {
+			const read = ctx.readConfigSource ?? defaultReadConfigSource;
+			const root = dirname(ctx.configPath);
+			const verdict = checkBootHook((relative) => read(resolve(root, relative)));
+			if (verdict.state === "ok") return Promise.resolve({
+				state: "pass",
+				detail: `starts Clivly from ${verdict.detail}`
+			});
+			return Promise.resolve({
+				state: verdict.state === "unknown" ? "skip" : "fail",
+				detail: verdict.detail,
+				hint: verdict.hint
+			});
+		}
+	},
 	sdkChecksStage,
 	triggerUrlStage
 ];
@@ -3135,6 +3251,7 @@ const ALIAS_STAGE_IDS = {
 	doctor: [
 		"config",
 		"runtime",
+		"boot-hook",
 		"setup-checks"
 	],
 	connect: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clivly",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "private": false,
   "type": "module",
   "description": "Clivly CLI — scaffold a CRM into your app (clivly init).",