clivly 0.9.3 → 0.9.5

package/drizzle.mjs

@@ -1,6 +1,77 @@
+import { t as BASE_REF } from "./projection-CSGJbZlZ.mjs";
 import { t as DRIZZLE_META } from "./drizzle-meta-D-5k3n0i.mjs";
+import { a as quoteIdent, n as compileProjectionIdentity, r as compileProjectionJoins, t as compileProjectionFrom } from "./projection-sql-BgnfiGqF.mjs";
 import { n as buildUniqueConstraints, r as discoverFromDrizzle, t as buildColumnsMeta } from "./drizzle-3kvhkwO7.mjs";
 import { asc, getTableColumns, getTableName, sql } from "drizzle-orm";
+//#region ../sdk/src/drizzle-projection.ts
+/** `<ref>.<column>` — the token `fields` carries and cloud-ingest reads. */
+function refToken(ref) {
+	return `${ref.table}.${ref.column}`;
+}
+function refSql(ref) {
+	return `${quoteIdent(ref.table)}.${quoteIdent(ref.column)}`;
+}
+function parseRef(value) {
+	if (typeof value !== "string") return value;
+	const dot = value.indexOf(".");
+	if (dot <= 0 || dot === value.length - 1) throw new Error(`fromDrizzleProjection: cursorField "${value}" must be a ref token like "base.updated_at".`);
+	return {
+		table: value.slice(0, dot),
+		column: value.slice(dot + 1)
+	};
+}
+/**
+* Refs address tables symbolically — `base` or a join key — never by table name,
+* which is what stops a projection reaching a table it did not declare. An
+* unresolvable ref would otherwise compile to SQL referencing a missing alias
+* and fail at the database with a message that never mentions the config.
+*/
+function assertKnownRef(ref, known, context) {
+	if (!known.has(ref.table)) throw new Error(`fromDrizzleProjection: ${context} names unknown ref "${ref.table}" — expected "${[...known].join("\", \"")}".`);
+}
+function normalizeRows(result) {
+	if (Array.isArray(result)) return result;
+	const rows = result.rows;
+	if (Array.isArray(rows)) return rows;
+	throw new Error("fromDrizzleProjection: db.execute() returned neither an array of rows nor { rows }.");
+}
+function fromDrizzleProjection(db, projection, opts) {
+	const client = db;
+	const known = /* @__PURE__ */ new Set([BASE_REF, ...projection.joins.map((j) => j.key)]);
+	if (projection.identity.kind === "base_pk" && projection.identity.column === void 0 && opts.basePkColumn === void 0) throw new Error(`fromDrizzleProjection: projection "${projection.entityKey}" has a base_pk identity with no column — pass { basePkColumn }.`);
+	const cursorRef = parseRef(opts.cursorField);
+	assertKnownRef(cursorRef, known, "cursorField");
+	for (const [field, binding] of Object.entries(projection.fieldBindings)) assertKnownRef(binding.from, known, `field "${field}"`);
+	const identityExpr = compileProjectionIdentity(projection, opts.basePkColumn ?? "");
+	const cursorToken = refToken(cursorRef);
+	const cursorExpr = `CAST(${refSql(cursorRef)} AS timestamptz)`;
+	const cursorRead = `to_char(${cursorExpr} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`;
+	const selectItems = [`${identityExpr} AS ${quoteIdent("id")}`, `${cursorRead} AS ${quoteIdent(cursorToken)}`];
+	const emitted = /* @__PURE__ */ new Set([cursorToken]);
+	for (const binding of Object.values(projection.fieldBindings)) {
+		const token = refToken(binding.from);
+		if (emitted.has(token)) continue;
+		emitted.add(token);
+		selectItems.push(`${refSql(binding.from)} AS ${quoteIdent(token)}`);
+	}
+	const head = [
+		`select ${selectItems.join(", ")}`,
+		compileProjectionFrom(projection),
+		...compileProjectionJoins(projection)
+	].join(" ");
+	return {
+		entity: opts.entity,
+		cursorField: cursorToken,
+		idField: "id",
+		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },
+		fetchPage: async ({ since, limit }) => {
+			const where = since ? sql` where (${sql.raw(cursorExpr)}, ${sql.raw(identityExpr)}) > (${since.time.toISOString()}::timestamptz, ${since.id})` : sql``;
+			const query = sql`${sql.raw(head)}${where} order by ${sql.raw(cursorExpr)} asc, ${sql.raw(identityExpr)} asc limit ${limit}`;
+			return normalizeRows(await client.execute(query));
+		}
+	};
+}
+//#endregion
 //#region ../sdk/src/drizzle.ts
 function inferIdField(table) {
 	const columns = getTableColumns(table);
@@ -13,14 +84,6 @@ function inferIdField(table) {
 	const kind = primaryKeys.length === 0 ? "no" : "a composite";
 	throw new Error(`fromDrizzle: table "${getTableName(table)}" has ${kind} single-column primary key — pass { idField } explicitly.`);
 }
-/**
-* Build a `SyncSource` from a Drizzle table, generating the keyset-paginated
-* `fetchPage` the SDK needs. `cursorField`/`idField` are drizzle property keys;
-* `idField` defaults to the table's single-column primary key.
-*
-* `drizzle-orm` is an optional peer dependency — installed only when you import
-* `@clivly/sdk/drizzle`.
-*/
 function fromDrizzle(db, table, opts) {
 	const drizzleDb = db;
 	const idField = opts.idField ?? inferIdField(table);
@@ -37,7 +100,8 @@ function fromDrizzle(db, table, opts) {
 		entity: opts.entity,
 		cursorField: cursorColumnName,
 		idField: idColumnName,
-		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy(asc(cursorColumn), asc(idColumn)).limit(limit)
+		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy(asc(cursorColumn), asc(idColumn)).limit(limit),
+		...opts.objectType === void 0 ? {} : { objectType: opts.objectType }
 	};
 	const uniqueConstraints = buildUniqueConstraints(table);
 	const meta = {
@@ -74,4 +138,4 @@ function drizzleIntrospector(db) {
 	};
 }
 //#endregion
-export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle };
+export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle, fromDrizzleProjection };

package/{entity-config-DtBsl2MQ.cjs → entity-config-7sGCk_nw.cjs}

@@ -1,4 +1,4 @@
-const require_projection = require("./projection-C5244vGa.cjs");
+const require_projection = require("./projection-Dz6_i1-w.cjs");
 //#region ../core/src/schema-meta.ts
 /**
 * Accessors over a discovered table's schema-v2 metadata.

package/{entity-config-kUHri9yA.mjs → entity-config-B74SPOUZ.mjs}

@@ -1,4 +1,4 @@
-import { a as _enum, c as literal, d as strictObject, f as string, i as projectionSchema, l as number, o as array, p as union, r as identityRefs, s as boolean, t as BASE_REF, u as record } from "./projection-D7xmQP4S.mjs";
+import { a as _enum, c as literal, d as strictObject, f as string, i as projectionSchema, l as number, o as array, p as union, r as identityRefs, s as boolean, t as BASE_REF, u as record } from "./projection-CSGJbZlZ.mjs";
 //#region ../core/src/schema-meta.ts
 /**
 * Accessors over a discovered table's schema-v2 metadata.

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-DtBsl2MQ.cjs");
+const require_entity_config = require("./entity-config-7sGCk_nw.cjs");
 require("./mapping-score-CaB3F4Uu.cjs");
 const require_internal_entity_heuristics = require("./internal-entity-heuristics.cjs");
-const require_sdk = require("./sdk-COLUHhJq.cjs");
+const require_sdk = require("./sdk-CM1UO-I7.cjs");
 let node_child_process = require("node:child_process");
 let node_fs = require("node:fs");
 let node_module = require("node:module");
@@ -292,10 +292,37 @@ function addCommand(pm, packages) {
 	};
 }
 //#endregion
+//#region src/tick-route.ts
+/**
+* The tick route's public URL path, and the template `clivly login` writes for
+* it.
+*
+* Every framework the CLI scaffolds mounts the tick handler at the same URL —
+* the *files* differ (`app/api/clivly/tick/route.ts`,
+* `src/routes/api/clivly/tick.ts`, `app/routes/api.clivly.tick.ts`, …) but each
+* one resolves to `/api/clivly/tick`. So this is a constant, not a per-framework
+* lookup, and `clivly dev`, the generated config and the `.env` template can all
+* read from one place instead of repeating the string and drifting.
+*/
+const CLIVLY_TICK_PATH = "/api/clivly/tick";
+/**
+* What `clivly login` writes into `.env` for `CLIVLY_SYNC_TRIGGER_URL`.
+*
+* A visible template beats an empty line: the developer sees the shape they
+* eventually need — a public origin plus the tick path — instead of an unhelpful
+* `CLIVLY_SYNC_TRIGGER_URL=` they have to go and look up.
+*
+* It is safe to ship a truthy non-address here only because the SDK refuses to
+* treat a bracketed value as configured (`isPlaceholderUrl` in
+* `@clivly/sdk/trigger-url`). Change the brackets here and that guard stops
+* matching, so the two must stay in step.
+*/
+const TRIGGER_URL_PLACEHOLDER = `https://<yourDomain.com>${CLIVLY_TICK_PATH}`;
+//#endregion
 //#region src/dev-tunnel.ts
 const CLOUDFLARE_QUICK_TUNNEL_REGEX = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
 const DEFAULT_PORT = "3000";
-const DEFAULT_ROUTE_PATH = "/api/clivly/tick";
+const DEFAULT_ROUTE_PATH = CLIVLY_TICK_PATH;
 function parseTunnelUrl(chunk) {
 	const match = chunk.match(CLOUDFLARE_QUICK_TUNNEL_REGEX);
 	return match ? match[0] : null;
@@ -947,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`;
 }
 /**
@@ -1400,15 +1427,23 @@ async function confirmWorkspace(deps, credentials) {
 	return await deps.confirm("Write this workspace's credentials to .env? [y/N] ");
 }
 function credentialEntries(credentials) {
-	return [{
-		key: SECRET_KEY_ENV,
-		value: credentials.apiKey,
-		comment: `Org secret key — ${CREDENTIALS_LOCATION}`
-	}, {
-		key: "CLIVLY_SYNC_TRIGGER_SECRET",
-		value: credentials.triggerSecret,
-		comment: `Signing secret — ${SYNC_SECRET_LOCATION}`
-	}];
+	return [
+		{
+			key: SECRET_KEY_ENV,
+			value: credentials.apiKey,
+			comment: `Org secret key — ${CREDENTIALS_LOCATION}`
+		},
+		{
+			key: "CLIVLY_SYNC_TRIGGER_SECRET",
+			value: credentials.triggerSecret,
+			comment: `Signing secret — ${SYNC_SECRET_LOCATION}`
+		},
+		{
+			key: "CLIVLY_SYNC_TRIGGER_URL",
+			value: TRIGGER_URL_PLACEHOLDER,
+			comment: "Public URL of your tick route — replace <yourDomain.com> once deployed. Local dev: run `clivly dev` instead."
+		}
+	];
 }
 function writeCredentials(options, credentials) {
 	const { deps } = options;
@@ -1775,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",
@@ -1873,7 +1909,13 @@ export default createClivlySDK({
 ${sources.join(",\n")},
   },
   syncTrigger: {
-    // The public URL Clivly Cloud calls to trigger a sync — your mounted tick route.
+    // Where Clivly Cloud calls to start a sync — your mounted tick route.
+    //
+    // \`path\` lets the SDK build its own public URL from the hosting platform's
+    // environment (VERCEL_URL, CF_PAGES_URL, RAILWAY_PUBLIC_DOMAIN,
+    // RENDER_EXTERNAL_URL, FLY_APP_NAME), so on those platforms you never have
+    // to set the URL by hand. \`url\` overrides that when you do.
+    path: "${CLIVLY_TICK_PATH}",
     url: process.env.CLIVLY_SYNC_TRIGGER_URL,
     secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET,
   },
@@ -2700,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",
@@ -2886,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.",
@@ -2986,14 +3125,15 @@ const triggerUrlStage = {
 	needs: [configStage.id],
 	run(ctx) {
 		const url = ctx.sdk?.syncTrigger?.url;
-		if (url) return Promise.resolve({
+		if (url && !require_sdk.isPlaceholderUrl(url)) return Promise.resolve({
 			state: "pass",
 			detail: url
 		});
+		const isPlaceholder = url !== void 0;
 		return Promise.resolve({
 			state: "warn",
-			detail: "Not set — remote sync cannot call back into this app.",
-			hint: "Set CLIVLY_SYNC_TRIGGER_URL once the app is deployed. For local development run `clivly dev` — it opens a tunnel and registers the URL for you. Push-only setups can ignore this."
+			detail: isPlaceholder ? `Still the placeholder (${url}) — remote sync cannot call back into this app.` : "Not set — remote sync cannot call back into this app.",
+			hint: "Replace <yourDomain.com> with your deployed origin, or delete the line — on Vercel, Cloudflare Pages, Railway, Render and Fly the SDK derives the URL from the platform. For local development run `clivly dev`: it opens a tunnel and registers the URL for you, outranking whatever is in .env. Push-only setups can ignore this."
 		});
 	}
 };
@@ -3041,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
 ];
@@ -3094,6 +3252,7 @@ const ALIAS_STAGE_IDS = {
 	doctor: [
 		"config",
 		"runtime",
+		"boot-hook",
 		"setup-checks"
 	],
 	connect: [
@@ -3547,8 +3706,8 @@ function previewMutations(deps, mutations, options) {
 function printNextSteps(out, authComplete, loginRan, envFile) {
 	out("\nNext steps:\n");
 	out(loginRan ? "  1. Credentials written by `clivly login`\n" : `  1. Add CLIVLY_SECRET_KEY to ${envFile} — create one at\n     ${CREDENTIALS_LOCATION}\n     (the legacy CLIVLY_API_KEY is still accepted)\n`);
-	out("  2. Set CLIVLY_SYNC_TRIGGER_URL to your public tick route\n");
-	out("     Local dev? Run `clivly dev` to open a tunnel, or skip this step until you deploy (remote sync is deploy-only locally).\n");
+	out("  2. Local dev: run `clivly dev` for dashboard-triggered sync\n");
+	out("     It tunnels your app and registers the URL for you — remote sync is\n     deploy-only otherwise, so nothing is broken if you skip it. Once deployed\n     to Vercel/Cloudflare/Railway/Render/Fly the URL is detected automatically;\n     set CLIVLY_SYNC_TRIGGER_URL by hand only for a custom domain.\n");
 	const step = authComplete ? 3 : 4;
 	if (!authComplete) out("  3. Finish resolveUser in the auth/verify route\n");
 	out(`  ${step}. Run \`clivly status\` to see where you are\n`);