clivly 0.10.8 → 0.10.9

package/README.md

@@ -530,7 +530,11 @@ subpaths:
 
 ```ts
 import { createClivlySDK, defineClivlyConfig } from "clivly/sdk";
-import { fromDrizzle, discoverFromDrizzle } from "clivly/drizzle";
+import {
+  fromDrizzle,
+  fromDrizzleProjection,
+  discoverFromDrizzle,
+} from "clivly/drizzle";
 import { clivlyVite } from "clivly/vite";
 import { createClerkAuthAdapter } from "clivly/auth/clerk";
 import { createWorkOSAuthAdapter } from "clivly/auth/workos";
@@ -542,6 +546,32 @@ import { createBetterAuthAdapter } from "clivly/auth/better-auth";
 > importing it from app code drags the whole CLI into your bundle and throws at
 > import time on Workers and other edge runtimes.
 
+### Projection entities need `fromDrizzleProjection`
+
+An entity with a `projection` spans several tables. `fromDrizzle` emits a
+single-table select, so pairing it with a projection pushes bare base-table rows
+and every joined field mirrors empty. Use the projection builder instead:
+
+```ts
+source: {
+  custom: [
+    fromDrizzleProjection(db, clientAccountsProjection, {
+      entity: "client_accounts",
+      objectType: "client-accounts",
+      cursorField: "base.updated_at",
+    }),
+  ],
+},
+```
+
+The builder also labels the push with the projection's `baseTable`, which is
+what the mapping is filed under. A hand-built source (`fromDrizzle` with an
+overridden `fetchPage`) is still supported — the SDK derives the same label from
+your config — but the builder performs the joins for you.
+
+> Authoring a derived object in the dashboard? Its **Connect** panel generates
+> this snippet for you, projection literal included.
+
 Provider and framework integrations use **optional peer dependencies**. Install
 only what your app actually uses:
 

package/index.cjs

@@ -3,7 +3,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 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-BAHcnhm7.cjs");
+const require_sdk = require("./sdk-BIYu0N3V.cjs");
 let node_child_process = require("node:child_process");
 let node_fs = require("node:fs");
 let node_module = require("node:module");
@@ -293,6 +293,124 @@ function addCommand(pm, packages) {
 	};
 }
 //#endregion
+//#region src/detect-workspace.ts
+const SELECTABLE_FRAMEWORKS = [
+	"nextjs",
+	"tanstack-start",
+	"sveltekit",
+	"remix",
+	"nuxt"
+];
+/**
+* Validate a `--framework` value.
+*
+* Rejecting a typo matters more than accepting one leniently: an unrecognised
+* value silently falling back to detection would scaffold route files in the
+* wrong shape, and a route in the wrong shape is not a build error — the
+* generator simply skips it and the endpoint 404s at runtime.
+*/
+function parseFrameworkFlag(value) {
+	if (value === void 0) return;
+	if (SELECTABLE_FRAMEWORKS.includes(value)) return value;
+	throw new Error(`"${value}" is not a supported framework. Accepted: ${SELECTABLE_FRAMEWORKS.join(", ")}.`);
+}
+/**
+* A caution for when the framework came from a sibling package, or null.
+*
+* Borrowing the ORM or auth is unambiguous — one database and one auth instance
+* serve the whole workspace. Borrowing the *framework* is not: route files are
+* generated in that framework's shape and written into the directory `init` ran
+* in, so if the framework lives next door the routes probably belong next door
+* too. Writing TanStack `src/routes/` files into a Hono app is not a build
+* error — the route generator simply never sees them and the endpoints 404.
+*/
+function borrowedFrameworkWarning(framework, source) {
+	if (!source) return null;
+	return `  ⚠️  ${FRAMEWORK_LABELS[framework]} was detected in "${source}", not here.\n      Route files are generated in that framework's shape. If this app
+      does not serve them, run init inside "${source}" instead, or pass\n      --framework to say what this app actually is.
+`;
+}
+/**
+* Extra guidance for a detection failure inside a workspace, or "" outside one.
+*
+* Detection has already scanned every sibling by the time either failure fires,
+* so the marker really is absent everywhere — which is worth saying, because
+* the bare message sends a developer looking for a dependency that was never
+* missing. Returning "" for the single-package case keeps the caller
+* branch-free.
+*/
+function workspaceHint(kind, packageCount) {
+	if (packageCount === 0) return "";
+	const scanned = `\nScanned ${packageCount} workspace package(s) and found no ${kind === "orm" ? "ORM" : "framework"} marker`;
+	return kind === "orm" ? `${scanned}.\nIf your schema is Drizzle, point at it and init will take your word:\n\n  clivly init --schema <path-or-package>\n` : `${scanned}\nin any of them. If this app is served by one of the frameworks above,\nname it outright:\n\n  clivly init --framework tanstack-start\n`;
+}
+/**
+* Resolve one signal, preferring the app's own dependencies.
+*
+* The app's package.json is authoritative: a sibling on a different framework
+* must never redefine what this app is. Only when the app itself is silent do
+* we look outward, and then the first package by name wins.
+*
+* Sorting here rather than trusting the caller matters: the real package list
+* comes from glob expansion, whose order is not guaranteed, so an unsorted scan
+* would let the same repo detect differently between runs and report a
+* different package as the source.
+*/
+function resolveSignal(appDeps, packages, detect, unknown) {
+	const own = detect(appDeps);
+	if (own !== unknown) return {
+		source: null,
+		value: own
+	};
+	const ordered = [...packages].sort((a, b) => a.name.localeCompare(b.name));
+	for (const pkg of ordered) {
+		const found = detect(pkg.deps);
+		if (found !== unknown) return {
+			source: pkg.name,
+			value: found
+		};
+	}
+	return {
+		source: null,
+		value: unknown
+	};
+}
+/**
+* Detect framework, ORM and auth across a whole workspace.
+*
+* A monorepo routinely splits these across packages — framework in the frontend
+* app, ORM in a `db` package, auth in an `auth` package — so reading only the
+* directory `init` was run from finds at most one of the three and fails
+* whichever way the developer turns. Widening the search to sibling packages is
+* what makes those layouts installable.
+*
+* Detection is deliberately a union rather than a per-package view: `init`
+* generates one config for one app, and that app reaches its database and auth
+* through workspace dependencies whether or not they are named in its own
+* manifest.
+*
+* `packages` may include the app itself; that is harmless, since the app's own
+* deps are consulted first anyway. Pass `[]` outside a workspace, which reduces
+* this to a plain single-package read.
+*/
+function detectAcrossWorkspace(appDeps, packages) {
+	const framework = resolveSignal(appDeps, packages, detectFramework, "unknown");
+	const orm = resolveSignal(appDeps, packages, detectOrm, "unknown");
+	const auth = resolveSignal(appDeps, packages, detectAuth, "unknown");
+	const sources = {
+		auth: auth.source,
+		framework: framework.source,
+		orm: orm.source
+	};
+	return {
+		auth: auth.value,
+		borrowed: Object.values(sources).some((source) => source !== null),
+		framework: framework.value,
+		orm: orm.value,
+		sources
+	};
+}
+//#endregion
 //#region src/tick-route.ts
 /**
 * The tick route's public URL path, and the template `clivly login` writes for
@@ -1258,10 +1376,12 @@ Usage:
   clivly init [--force] [--dry-run] [--diff] [--yes] [--no-login] [--no-browser]
               [--schema <path|package>] [--db-import <specifier>]
               [--auth-import <specifier>] [--contact-table <table>]
-              [--company-table <table>]
+              [--company-table <table>] [--framework <name>]
 
 Scaffolds clivly.config.ts, the Clivly route files, and .env placeholders.
 Detects your framework, ORM, auth adapter and app layout from the project.
+In a workspace the whole package graph is scanned, so a monorepo that keeps
+its framework, ORM and auth in separate packages is detected from any app.
 
 Options:
   --dry-run            Show what would be written; write nothing
@@ -1269,7 +1389,8 @@ Options:
   --force              Overwrite files Clivly owns
   --yes                Skip prompts
   --no-login           Skip browser pairing
-  --schema <p>         Path or package holding your ORM schema
+  --framework <n>      nextjs | tanstack-start | sveltekit | remix | nuxt
+  --schema <p>         Path or package holding your ORM schema (implies Drizzle)
   --db-import <s>      Module specifier exporting your database instance
   --auth-import <s>    Module specifier exporting your auth instance
   --contact-table <t>  Table to map as contacts
@@ -1701,13 +1822,52 @@ function toScoredTable(table) {
 function columnNames(table) {
 	return table.columns.map((column) => column.dbName);
 }
-function rankCandidates$1(tables, concept) {
+/**
+* Company candidates the vocabulary cannot name, promoted on foreign-key
+* evidence.
+*
+* The company vocabulary is seven generic business words (companies,
+* organizations, teams, accounts…). A domain word for the same idea —
+* `campuses`, `branches`, `sites`, `practices`, `chapters` — matches none of
+* them, so such a table was never a candidate at all and no amount of ranking
+* could reach it. On `vue-academy` that left Better Auth's `organization` as
+* the only company candidate, and init duly scaffolded the auth table while
+* `campuses`, which every student row references, was invisible.
+*
+* Guessing more words does not fix this; the next unlisted word fails
+* identically. The schema already states the answer: when the CONTACT table
+* holds a real foreign key to some table, that target is what a contact
+* belongs to. `references` is reflected metadata, so this is a fact rather
+* than a name guess.
+*
+* Two guards keep it honest. The target must pass `hasDefiningColumn`, the
+* same "can this table BE a company" test every other candidate passes — a
+* join table with no `name` is not promoted. And framework tables are skipped,
+* because `contacts.organization_id → organization` is exactly the auth
+* plumbing this is meant to see past.
+*/
+function fkPromotedCompanies(tables, contact) {
+	if (!contact) return [];
+	const targets = /* @__PURE__ */ new Set();
+	for (const column of contact.columns) {
+		const table = column.references?.table;
+		if (table && !require_internal_entity_heuristics.isFrameworkTable(table)) targets.add(table.toLowerCase());
+	}
+	return tables.filter((t) => targets.has(t.tableName.toLowerCase()) && t.tableName !== contact.tableName && require_internal_entity_heuristics.hasDefiningColumn("company", columnNames(t)));
+}
+function rankCandidates$1(tables, concept, contact = null) {
+	const promoted = concept === "company" ? fkPromotedCompanies(tables, contact) : [];
+	const promotedNames = new Set(promoted.map((t) => t.tableName));
 	return tables.map((t) => ({
 		t,
-		m: require_internal_entity_heuristics.matchesConcept(t.tableName, concept)
+		m: require_internal_entity_heuristics.matchesConcept(t.tableName, concept) ?? (promotedNames.has(t.tableName) ? { exact: false } : null)
 	})).filter((c) => Boolean(c.m)).sort((a, b) => {
 		const usable = Number(require_internal_entity_heuristics.hasDefiningColumn(concept, columnNames(b.t))) - Number(require_internal_entity_heuristics.hasDefiningColumn(concept, columnNames(a.t)));
 		if (usable !== 0) return usable;
+		const aPromoted = promotedNames.has(a.t.tableName);
+		if (aPromoted !== promotedNames.has(b.t.tableName)) {
+			if (require_internal_entity_heuristics.isFrameworkTable((aPromoted ? b.t : a.t).tableName)) return aPromoted ? -1 : 1;
+		}
 		const exact = Number(b.m.exact) - Number(a.m.exact);
 		if (exact !== 0) return exact;
 		return Number(require_internal_entity_heuristics.isFrameworkTable(a.t.tableName)) - Number(require_internal_entity_heuristics.isFrameworkTable(b.t.tableName));
@@ -1715,7 +1875,7 @@ function rankCandidates$1(tables, concept) {
 }
 function selectEntities(tables) {
 	const contactCands = rankCandidates$1(tables, "contact");
-	const companyCands = rankCandidates$1(tables, "company");
+	const companyCands = rankCandidates$1(tables, "company", contactCands[0] ?? null);
 	const contactNames = new Set(contactCands.map((t) => t.tableName));
 	const companyNames = new Set(companyCands.map((t) => t.tableName));
 	const contactExclusive = contactCands.filter((t) => !companyNames.has(t.tableName));
@@ -3962,6 +4122,18 @@ function resolveInitDeps(options) {
 		authWiring: renderAuthWiring("unknown")
 	};
 }
+/**
+* The three detection lines, annotating any signal borrowed from a sibling.
+*
+* Naming the source package is what makes a workspace detection auditable:
+* without it the banner claims an ORM the developer cannot find in the
+* directory they are standing in.
+*/
+function renderDetectionLines(detection) {
+	const from = (source) => source ? ` (from ${source})` : "";
+	const frameworkNote = detection.frameworkForced ? " (--framework)" : from(detection.sources.framework);
+	return `  Framework: ${FRAMEWORK_LABELS[detection.framework]}${frameworkNote}\n  ORM:       ${detection.orm}${from(detection.sources.orm)}\n  Auth:      ${detection.auth}${from(detection.sources.auth)}${detection.authWired ? " (wired)" : ""}\n`;
+}
 async function acquireSchema(options, deps) {
 	const { out } = deps;
 	const appDeps = deps.readDepsFn(options.cwd);
@@ -3969,26 +4141,39 @@ async function acquireSchema(options, deps) {
 		out(`No package.json found in ${options.cwd}. Run \`clivly init\` from inside an existing app — cd into your project first.\n`);
 		return { code: 1 };
 	}
-	const framework = detectFramework(appDeps);
-	const orm = detectOrm(appDeps);
-	const auth = detectAuth(appDeps);
+	const workspacePackages = (deps.graphFor(options.cwd)?.packages ?? []).map((pkg) => ({
+		deps: deps.readDepsFn(pkg.dir),
+		name: pkg.name
+	}));
+	const detected = detectAcrossWorkspace(appDeps, workspacePackages);
+	const framework = options.frameworkFlag ?? detected.framework;
+	const { auth, orm, sources } = detected;
 	deps.framework = framework;
 	const layout = deps.resolveAppLayout(options.cwd, deps.fileExists);
 	deps.layout = layout;
 	out("\nClivly init\n");
 	deps.authWiring = renderAuthWiring(auth, auth === "better-auth" ? authInstanceFromFlag(options.authImportFlag) ?? await deps.probeAuth(options.cwd) : null);
-	out(`  Framework: ${FRAMEWORK_LABELS[framework]}\n`);
-	out(`  ORM:       ${orm}\n`);
-	out(`  Auth:      ${auth}${deps.authWiring.complete ? " (wired)" : ""}\n`);
+	out(renderDetectionLines({
+		auth,
+		authWired: deps.authWiring.complete,
+		framework,
+		frameworkForced: options.frameworkFlag !== void 0,
+		orm,
+		sources
+	}));
 	if (framework === "nextjs") out(`  Layout:    ${layout}\n`);
+	const frameworkCaution = options.frameworkFlag ? null : borrowedFrameworkWarning(framework, sources.framework);
+	if (frameworkCaution) out(`\n${frameworkCaution}`);
 	if (auth === "better-auth" && !deps.authWiring.complete) out("\n  ⚠️  Could not locate your better-auth instance.\n      The verify route will import a placeholder path that does not\n      resolve. Point it at the real module with:\n\n        clivly init --force --auth-import <specifier>\n\n      Accepts an alias ($lib/server/auth, @/lib/auth), a package name,\n      or a project-relative path (src/lib/server/auth).\n");
 	out("\n");
-	if (orm !== "drizzle") {
+	if (orm !== "drizzle" && !options.schemaFlag) {
 		out(`clivly init currently generates config for Drizzle only. Detected ORM: ${orm}\n`);
+		out(workspaceHint("orm", workspacePackages.length));
 		return { code: 1 };
 	}
 	if (framework === "unknown") {
 		out("clivly init doesn't recognise your framework yet (looked for Next.js, TanStack Start, SvelteKit, Remix, Nuxt). Route file generation needs one of these.\n");
+		out(workspaceHint("framework", workspacePackages.length));
 		if ("vue" in appDeps) out("\nUsing Vue? Clivly supports Vue through Nuxt. A Vite SPA has no server\nto mount the sync route on, so the route files need Nuxt's server\ndirectory (or any of the frameworks above).\n");
 		return { code: 1 };
 	}
@@ -4416,6 +4601,13 @@ function defaultLoginDeps() {
 	};
 }
 function runInitFromArgv(argv, cwd) {
+	let frameworkFlag;
+	try {
+		frameworkFlag = parseFrameworkFlag(flagValue(argv, "--framework"));
+	} catch (error) {
+		process.stdout.write(`${error.message}\n`);
+		return Promise.resolve(1);
+	}
 	return runInit({
 		cwd,
 		force: argv.includes("--force"),
@@ -4425,6 +4617,7 @@ function runInitFromArgv(argv, cwd) {
 		noLogin: argv.includes("--no-login"),
 		openBrowser: !argv.includes("--no-browser"),
 		schemaFlag: flagValue(argv, "--schema"),
+		frameworkFlag,
 		dbImportFlag: flagValue(argv, "--db-import"),
 		authImportFlag: flagValue(argv, "--auth-import"),
 		contactTableFlag: flagValue(argv, "--contact-table"),

package/index.d.cts

@@ -1,4 +1,5 @@
 //#region src/detect.d.ts
+type Framework = "nextjs" | "tanstack-start" | "sveltekit" | "remix" | "nuxt" | "unknown";
 type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
 //#endregion
 //#region src/app-layout.d.ts
@@ -84,6 +85,7 @@ interface RunInitOptions {
   dryRun?: boolean;
   fileExists?: (path: string) => boolean;
   force: boolean;
+  frameworkFlag?: Framework;
   installPackages?: (options: {
     cwd: string;
     packages: string[];

package/index.d.mts

@@ -1,4 +1,5 @@
 //#region src/detect.d.ts
+type Framework = "nextjs" | "tanstack-start" | "sveltekit" | "remix" | "nuxt" | "unknown";
 type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
 //#endregion
 //#region src/app-layout.d.ts
@@ -84,6 +85,7 @@ interface RunInitOptions {
   dryRun?: boolean;
   fileExists?: (path: string) => boolean;
   force: boolean;
+  frameworkFlag?: Framework;
   installPackages?: (options: {
     cwd: string;
     packages: string[];

package/index.mjs

@@ -2,7 +2,7 @@
 import { t as CANONICAL_FIELDS } from "./entity-config-bC3DX9f1.mjs";
 import "./mapping-score-C68uAqGB.mjs";
 import { hasDefiningColumn, isFrameworkTable, matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./internal-entity-heuristics.mjs";
-import { s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-C0DU5KDS.mjs";
+import { s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-DofHordq.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";
@@ -292,6 +292,124 @@ function addCommand(pm, packages) {
 	};
 }
 //#endregion
+//#region src/detect-workspace.ts
+const SELECTABLE_FRAMEWORKS = [
+	"nextjs",
+	"tanstack-start",
+	"sveltekit",
+	"remix",
+	"nuxt"
+];
+/**
+* Validate a `--framework` value.
+*
+* Rejecting a typo matters more than accepting one leniently: an unrecognised
+* value silently falling back to detection would scaffold route files in the
+* wrong shape, and a route in the wrong shape is not a build error — the
+* generator simply skips it and the endpoint 404s at runtime.
+*/
+function parseFrameworkFlag(value) {
+	if (value === void 0) return;
+	if (SELECTABLE_FRAMEWORKS.includes(value)) return value;
+	throw new Error(`"${value}" is not a supported framework. Accepted: ${SELECTABLE_FRAMEWORKS.join(", ")}.`);
+}
+/**
+* A caution for when the framework came from a sibling package, or null.
+*
+* Borrowing the ORM or auth is unambiguous — one database and one auth instance
+* serve the whole workspace. Borrowing the *framework* is not: route files are
+* generated in that framework's shape and written into the directory `init` ran
+* in, so if the framework lives next door the routes probably belong next door
+* too. Writing TanStack `src/routes/` files into a Hono app is not a build
+* error — the route generator simply never sees them and the endpoints 404.
+*/
+function borrowedFrameworkWarning(framework, source) {
+	if (!source) return null;
+	return `  ⚠️  ${FRAMEWORK_LABELS[framework]} was detected in "${source}", not here.\n      Route files are generated in that framework's shape. If this app
+      does not serve them, run init inside "${source}" instead, or pass\n      --framework to say what this app actually is.
+`;
+}
+/**
+* Extra guidance for a detection failure inside a workspace, or "" outside one.
+*
+* Detection has already scanned every sibling by the time either failure fires,
+* so the marker really is absent everywhere — which is worth saying, because
+* the bare message sends a developer looking for a dependency that was never
+* missing. Returning "" for the single-package case keeps the caller
+* branch-free.
+*/
+function workspaceHint(kind, packageCount) {
+	if (packageCount === 0) return "";
+	const scanned = `\nScanned ${packageCount} workspace package(s) and found no ${kind === "orm" ? "ORM" : "framework"} marker`;
+	return kind === "orm" ? `${scanned}.\nIf your schema is Drizzle, point at it and init will take your word:\n\n  clivly init --schema <path-or-package>\n` : `${scanned}\nin any of them. If this app is served by one of the frameworks above,\nname it outright:\n\n  clivly init --framework tanstack-start\n`;
+}
+/**
+* Resolve one signal, preferring the app's own dependencies.
+*
+* The app's package.json is authoritative: a sibling on a different framework
+* must never redefine what this app is. Only when the app itself is silent do
+* we look outward, and then the first package by name wins.
+*
+* Sorting here rather than trusting the caller matters: the real package list
+* comes from glob expansion, whose order is not guaranteed, so an unsorted scan
+* would let the same repo detect differently between runs and report a
+* different package as the source.
+*/
+function resolveSignal(appDeps, packages, detect, unknown) {
+	const own = detect(appDeps);
+	if (own !== unknown) return {
+		source: null,
+		value: own
+	};
+	const ordered = [...packages].sort((a, b) => a.name.localeCompare(b.name));
+	for (const pkg of ordered) {
+		const found = detect(pkg.deps);
+		if (found !== unknown) return {
+			source: pkg.name,
+			value: found
+		};
+	}
+	return {
+		source: null,
+		value: unknown
+	};
+}
+/**
+* Detect framework, ORM and auth across a whole workspace.
+*
+* A monorepo routinely splits these across packages — framework in the frontend
+* app, ORM in a `db` package, auth in an `auth` package — so reading only the
+* directory `init` was run from finds at most one of the three and fails
+* whichever way the developer turns. Widening the search to sibling packages is
+* what makes those layouts installable.
+*
+* Detection is deliberately a union rather than a per-package view: `init`
+* generates one config for one app, and that app reaches its database and auth
+* through workspace dependencies whether or not they are named in its own
+* manifest.
+*
+* `packages` may include the app itself; that is harmless, since the app's own
+* deps are consulted first anyway. Pass `[]` outside a workspace, which reduces
+* this to a plain single-package read.
+*/
+function detectAcrossWorkspace(appDeps, packages) {
+	const framework = resolveSignal(appDeps, packages, detectFramework, "unknown");
+	const orm = resolveSignal(appDeps, packages, detectOrm, "unknown");
+	const auth = resolveSignal(appDeps, packages, detectAuth, "unknown");
+	const sources = {
+		auth: auth.source,
+		framework: framework.source,
+		orm: orm.source
+	};
+	return {
+		auth: auth.value,
+		borrowed: Object.values(sources).some((source) => source !== null),
+		framework: framework.value,
+		orm: orm.value,
+		sources
+	};
+}
+//#endregion
 //#region src/tick-route.ts
 /**
 * The tick route's public URL path, and the template `clivly login` writes for
@@ -1257,10 +1375,12 @@ Usage:
   clivly init [--force] [--dry-run] [--diff] [--yes] [--no-login] [--no-browser]
               [--schema <path|package>] [--db-import <specifier>]
               [--auth-import <specifier>] [--contact-table <table>]
-              [--company-table <table>]
+              [--company-table <table>] [--framework <name>]
 
 Scaffolds clivly.config.ts, the Clivly route files, and .env placeholders.
 Detects your framework, ORM, auth adapter and app layout from the project.
+In a workspace the whole package graph is scanned, so a monorepo that keeps
+its framework, ORM and auth in separate packages is detected from any app.
 
 Options:
   --dry-run            Show what would be written; write nothing
@@ -1268,7 +1388,8 @@ Options:
   --force              Overwrite files Clivly owns
   --yes                Skip prompts
   --no-login           Skip browser pairing
-  --schema <p>         Path or package holding your ORM schema
+  --framework <n>      nextjs | tanstack-start | sveltekit | remix | nuxt
+  --schema <p>         Path or package holding your ORM schema (implies Drizzle)
   --db-import <s>      Module specifier exporting your database instance
   --auth-import <s>    Module specifier exporting your auth instance
   --contact-table <t>  Table to map as contacts
@@ -1700,13 +1821,52 @@ function toScoredTable(table) {
 function columnNames(table) {
 	return table.columns.map((column) => column.dbName);
 }
-function rankCandidates$1(tables, concept) {
+/**
+* Company candidates the vocabulary cannot name, promoted on foreign-key
+* evidence.
+*
+* The company vocabulary is seven generic business words (companies,
+* organizations, teams, accounts…). A domain word for the same idea —
+* `campuses`, `branches`, `sites`, `practices`, `chapters` — matches none of
+* them, so such a table was never a candidate at all and no amount of ranking
+* could reach it. On `vue-academy` that left Better Auth's `organization` as
+* the only company candidate, and init duly scaffolded the auth table while
+* `campuses`, which every student row references, was invisible.
+*
+* Guessing more words does not fix this; the next unlisted word fails
+* identically. The schema already states the answer: when the CONTACT table
+* holds a real foreign key to some table, that target is what a contact
+* belongs to. `references` is reflected metadata, so this is a fact rather
+* than a name guess.
+*
+* Two guards keep it honest. The target must pass `hasDefiningColumn`, the
+* same "can this table BE a company" test every other candidate passes — a
+* join table with no `name` is not promoted. And framework tables are skipped,
+* because `contacts.organization_id → organization` is exactly the auth
+* plumbing this is meant to see past.
+*/
+function fkPromotedCompanies(tables, contact) {
+	if (!contact) return [];
+	const targets = /* @__PURE__ */ new Set();
+	for (const column of contact.columns) {
+		const table = column.references?.table;
+		if (table && !isFrameworkTable(table)) targets.add(table.toLowerCase());
+	}
+	return tables.filter((t) => targets.has(t.tableName.toLowerCase()) && t.tableName !== contact.tableName && hasDefiningColumn("company", columnNames(t)));
+}
+function rankCandidates$1(tables, concept, contact = null) {
+	const promoted = concept === "company" ? fkPromotedCompanies(tables, contact) : [];
+	const promotedNames = new Set(promoted.map((t) => t.tableName));
 	return tables.map((t) => ({
 		t,
-		m: matchesConcept(t.tableName, concept)
+		m: matchesConcept(t.tableName, concept) ?? (promotedNames.has(t.tableName) ? { exact: false } : null)
 	})).filter((c) => Boolean(c.m)).sort((a, b) => {
 		const usable = Number(hasDefiningColumn(concept, columnNames(b.t))) - Number(hasDefiningColumn(concept, columnNames(a.t)));
 		if (usable !== 0) return usable;
+		const aPromoted = promotedNames.has(a.t.tableName);
+		if (aPromoted !== promotedNames.has(b.t.tableName)) {
+			if (isFrameworkTable((aPromoted ? b.t : a.t).tableName)) return aPromoted ? -1 : 1;
+		}
 		const exact = Number(b.m.exact) - Number(a.m.exact);
 		if (exact !== 0) return exact;
 		return Number(isFrameworkTable(a.t.tableName)) - Number(isFrameworkTable(b.t.tableName));
@@ -1714,7 +1874,7 @@ function rankCandidates$1(tables, concept) {
 }
 function selectEntities(tables) {
 	const contactCands = rankCandidates$1(tables, "contact");
-	const companyCands = rankCandidates$1(tables, "company");
+	const companyCands = rankCandidates$1(tables, "company", contactCands[0] ?? null);
 	const contactNames = new Set(contactCands.map((t) => t.tableName));
 	const companyNames = new Set(companyCands.map((t) => t.tableName));
 	const contactExclusive = contactCands.filter((t) => !companyNames.has(t.tableName));
@@ -3961,6 +4121,18 @@ function resolveInitDeps(options) {
 		authWiring: renderAuthWiring("unknown")
 	};
 }
+/**
+* The three detection lines, annotating any signal borrowed from a sibling.
+*
+* Naming the source package is what makes a workspace detection auditable:
+* without it the banner claims an ORM the developer cannot find in the
+* directory they are standing in.
+*/
+function renderDetectionLines(detection) {
+	const from = (source) => source ? ` (from ${source})` : "";
+	const frameworkNote = detection.frameworkForced ? " (--framework)" : from(detection.sources.framework);
+	return `  Framework: ${FRAMEWORK_LABELS[detection.framework]}${frameworkNote}\n  ORM:       ${detection.orm}${from(detection.sources.orm)}\n  Auth:      ${detection.auth}${from(detection.sources.auth)}${detection.authWired ? " (wired)" : ""}\n`;
+}
 async function acquireSchema(options, deps) {
 	const { out } = deps;
 	const appDeps = deps.readDepsFn(options.cwd);
@@ -3968,26 +4140,39 @@ async function acquireSchema(options, deps) {
 		out(`No package.json found in ${options.cwd}. Run \`clivly init\` from inside an existing app — cd into your project first.\n`);
 		return { code: 1 };
 	}
-	const framework = detectFramework(appDeps);
-	const orm = detectOrm(appDeps);
-	const auth = detectAuth(appDeps);
+	const workspacePackages = (deps.graphFor(options.cwd)?.packages ?? []).map((pkg) => ({
+		deps: deps.readDepsFn(pkg.dir),
+		name: pkg.name
+	}));
+	const detected = detectAcrossWorkspace(appDeps, workspacePackages);
+	const framework = options.frameworkFlag ?? detected.framework;
+	const { auth, orm, sources } = detected;
 	deps.framework = framework;
 	const layout = deps.resolveAppLayout(options.cwd, deps.fileExists);
 	deps.layout = layout;
 	out("\nClivly init\n");
 	deps.authWiring = renderAuthWiring(auth, auth === "better-auth" ? authInstanceFromFlag(options.authImportFlag) ?? await deps.probeAuth(options.cwd) : null);
-	out(`  Framework: ${FRAMEWORK_LABELS[framework]}\n`);
-	out(`  ORM:       ${orm}\n`);
-	out(`  Auth:      ${auth}${deps.authWiring.complete ? " (wired)" : ""}\n`);
+	out(renderDetectionLines({
+		auth,
+		authWired: deps.authWiring.complete,
+		framework,
+		frameworkForced: options.frameworkFlag !== void 0,
+		orm,
+		sources
+	}));
 	if (framework === "nextjs") out(`  Layout:    ${layout}\n`);
+	const frameworkCaution = options.frameworkFlag ? null : borrowedFrameworkWarning(framework, sources.framework);
+	if (frameworkCaution) out(`\n${frameworkCaution}`);
 	if (auth === "better-auth" && !deps.authWiring.complete) out("\n  ⚠️  Could not locate your better-auth instance.\n      The verify route will import a placeholder path that does not\n      resolve. Point it at the real module with:\n\n        clivly init --force --auth-import <specifier>\n\n      Accepts an alias ($lib/server/auth, @/lib/auth), a package name,\n      or a project-relative path (src/lib/server/auth).\n");
 	out("\n");
-	if (orm !== "drizzle") {
+	if (orm !== "drizzle" && !options.schemaFlag) {
 		out(`clivly init currently generates config for Drizzle only. Detected ORM: ${orm}\n`);
+		out(workspaceHint("orm", workspacePackages.length));
 		return { code: 1 };
 	}
 	if (framework === "unknown") {
 		out("clivly init doesn't recognise your framework yet (looked for Next.js, TanStack Start, SvelteKit, Remix, Nuxt). Route file generation needs one of these.\n");
+		out(workspaceHint("framework", workspacePackages.length));
 		if ("vue" in appDeps) out("\nUsing Vue? Clivly supports Vue through Nuxt. A Vite SPA has no server\nto mount the sync route on, so the route files need Nuxt's server\ndirectory (or any of the frameworks above).\n");
 		return { code: 1 };
 	}
@@ -4415,6 +4600,13 @@ function defaultLoginDeps() {
 	};
 }
 function runInitFromArgv(argv, cwd) {
+	let frameworkFlag;
+	try {
+		frameworkFlag = parseFrameworkFlag(flagValue(argv, "--framework"));
+	} catch (error) {
+		process.stdout.write(`${error.message}\n`);
+		return Promise.resolve(1);
+	}
 	return runInit({
 		cwd,
 		force: argv.includes("--force"),
@@ -4424,6 +4616,7 @@ function runInitFromArgv(argv, cwd) {
 		noLogin: argv.includes("--no-login"),
 		openBrowser: !argv.includes("--no-browser"),
 		schemaFlag: flagValue(argv, "--schema"),
+		frameworkFlag,
 		dbImportFlag: flagValue(argv, "--db-import"),
 		authImportFlag: flagValue(argv, "--auth-import"),
 		contactTableFlag: flagValue(argv, "--contact-table"),

package/package.json

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

package/{sdk-BAHcnhm7.cjs → sdk-BIYu0N3V.cjs}

@@ -392,11 +392,15 @@ function errorMessage(error) {
 /**
 * The entities to ask about, in the exact terms the sync pushes them.
 *
-* `source` is the resolved `SyncSource.entity` — the value that arrives at
+* `source` is whatever the push will actually send — the value that arrives at
 * `ingestPush` as `input.source` and is compared against `mapping.sourceTable`.
+* Usually that is `SyncSource.entity`, but a projection pushes under its base
+* table, so this asks `customPushSource` rather than reading `entity` directly.
+*
 * It is NOT the entity config's own `source` field, which names a host table;
-* the two are routinely conflated, and using the wrong one would report every
-* correctly mapped workspace as unmapped.
+* the two are routinely conflated, and using the wrong one reports a correctly
+* mapped workspace as unmapped — which is exactly what happened to every
+* projection until this used the push label.
 */
 function readinessEntitiesFromConfig(config) {
 	const entities = [];
@@ -405,7 +409,7 @@ function readinessEntitiesFromConfig(config) {
 		if (!resolved) continue;
 		const objectTypeSlug = resolved.source.objectType;
 		entities.push({
-			source: resolved.source.entity,
+			source: customPushSource(config, resolved.source),
 			concept: resolved.concept,
 			...resolved.concept === "custom" && objectTypeSlug ? { objectTypeSlug } : {}
 		});
@@ -1468,8 +1472,18 @@ function jsonResponse$1(body, status) {
 function normalizeApiUrl(apiUrl) {
 	return apiUrl.replace(TRAILING_SLASH$1, "");
 }
-function resolveOrigin(req) {
-	const headerOrigin = req.headers.get("origin");
+/**
+* The origin *claimed* by the request, for reporting upstream.
+*
+* Falls back to the request URL so Clivly still receives an origin for a
+* non-browser caller. This value is reported, never trusted: only a real
+* `Origin` header is evidence of where a request came from, so the access
+* decision uses {@link trustedOrigin} instead. Keeping the two apart is the
+* point — conflating them let a caller that simply omitted the header be
+* judged against the server's own origin, which is usually in the allowlist.
+*/
+function reportedOrigin(req) {
+	const headerOrigin = trustedOrigin(req);
 	if (headerOrigin) return headerOrigin;
 	try {
 		return new URL(req.url).origin;
@@ -1477,6 +1491,15 @@ function resolveOrigin(req) {
 		return null;
 	}
 }
+/**
+* The only origin worth an access decision: one the browser set itself.
+*
+* A missing header means "not a browser request we can vouch for", which is
+* untrusted — never the server's own origin.
+*/
+function trustedOrigin(req) {
+	return req.headers.get("origin");
+}
 function isChatSessionRequestBody(value) {
 	if (typeof value !== "object" || value === null) return false;
 	const body = value;
@@ -1487,6 +1510,17 @@ function isChatSessionRequestBody(value) {
 	if (typeof visitor.email !== "string" || visitor.email.trim().length === 0) return false;
 	return body.visitorToken === void 0 || body.visitorToken === null || typeof body.visitorToken === "string";
 }
+/**
+* Judge a request against the configured allowlist.
+*
+* `origin` must be a *trusted* origin (see {@link trustedOrigin}) — passing
+* the reported one would reinstate the bypass this guards against.
+*
+* An unset allowlist still admits every origin, because requiring it would
+* break every existing deployment on upgrade. The unset case is instead
+* warned about once at construction, so the permissive default is loud
+* rather than silent.
+*/
 function originAllowed(origin, allowedOrigins) {
 	if (!allowedOrigins || allowedOrigins.length === 0) return true;
 	if (!origin) return false;
@@ -1494,6 +1528,7 @@ function originAllowed(origin, allowedOrigins) {
 }
 function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API_URL$1, fetchImpl = fetch, resolveUser }) {
 	const sessionUrl = `${normalizeApiUrl(apiUrl)}/clivly/widget/session`;
+	if (!allowedOrigins || allowedOrigins.length === 0) console.warn("[clivly] createChatSessionHandler has no allowedOrigins; every origin can open a chat session against this workspace. Pass allowedOrigins to restrict it.");
 	return async (request) => {
 		if (request.method !== "POST") return new Response(JSON.stringify({ error: "method_not_allowed" }), {
 			status: 405,
@@ -1502,8 +1537,8 @@ function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API
 				allow: "POST"
 			}
 		});
-		const origin = resolveOrigin(request);
-		if (!originAllowed(origin, allowedOrigins)) return jsonResponse$1({ error: "origin_not_allowed" }, 403);
+		if (!originAllowed(trustedOrigin(request), allowedOrigins)) return jsonResponse$1({ error: "origin_not_allowed" }, 403);
+		const origin = reportedOrigin(request);
 		let body;
 		try {
 			body = await request.json();
@@ -1701,6 +1736,18 @@ var TriggerRequestError = class extends Error {
 function triggerErrorStatus(error) {
 	return error instanceof TriggerRequestError ? error.status : 500;
 }
+const SENTENCE_END_RE = /[.!?]$/;
+async function readPushFailureMessage(response) {
+	if (!response || typeof response.json !== "function") return null;
+	try {
+		const body = await response.json();
+		if (typeof body !== "object" || body === null) return null;
+		const { message } = body;
+		return typeof message === "string" && message.trim().length > 0 ? message : null;
+	} catch {
+		return null;
+	}
+}
 const SIGNATURE_TOLERANCE_SECONDS = 300;
 const SIGNATURE_HEADER_RE = /^t=(\d+),v1=([0-9a-f]+)$/;
 const SECONDS_PER_MS = 1e3;
@@ -1923,17 +1970,27 @@ function createClivlySDK(config) {
 			}, response);
 			return true;
 		}
-		lastPushFailure ??= { status: response?.status ?? null };
+		lastPushFailure ??= {
+			status: response?.status ?? null,
+			message: await readPushFailureMessage(response)
+		};
 		return false;
 	};
 	const describePushFailure = (entities) => {
 		const base = `Clivly sync: push failed for ${entities.join(", ")}`;
 		const status = lastPushFailure?.status ?? null;
+		const serverMessage = lastPushFailure?.message ?? null;
 		let cause;
 		if (status === 401 || status === 403) cause = "the API key was rejected — check CLIVLY_API_KEY is set to a valid key for this org";
 		else if (status === null) cause = `couldn't reach Clivly at ${apiUrl} — check network access and CLIVLY_API_URL`;
+		else if (serverMessage) cause = `Clivly returned HTTP ${status}: ${serverMessage}`;
 		else cause = `Clivly returned HTTP ${status}`;
-		return `${base}: ${cause}. Run \`clivly doctor\` to diagnose.`;
+		const separator = SENTENCE_END_RE.test(cause) ? "" : ".";
+		return `${base}: ${cause}${separator} Run \`clivly doctor\` to diagnose.`;
+	};
+	const pushFailureError = (message) => {
+		const status = lastPushFailure?.status ?? null;
+		return status !== null && status >= CLIENT_ERROR_FLOOR && status < RETRYABLE_STATUS_FLOOR ? new TriggerRequestError(status, message) : new Error(message);
 	};
 	const syncOne = async (source, path, mode, objectType, runId, batchSizeOverride, maxRowsOverride, persistCursor = true) => {
 		const since = mode === "full" ? null : await cursorStore.get(source.entity) ?? null;
@@ -2023,7 +2080,7 @@ function createClivlySDK(config) {
 				failed: true,
 				error: message
 			};
-			throw new Error(message);
+			throw pushFailureError(message);
 		}
 		lastPush = { failed: false };
 	};
@@ -2031,7 +2088,7 @@ function createClivlySDK(config) {
 		const resolved = resolveSampleSource(config, entityKey);
 		if (!resolved) throw new TriggerRequestError(400, `Clivly sync: no source is configured for entity "${entityKey}". The dashboard maps this table, but clivly.config declares no matching entity — add it to \`entities\`, or remove the mapping in Integrations → Mapping.`);
 		lastPushFailure = null;
-		if (!await syncOne(resolved.source, resolved.path, "delta", resolved.objectType, runId, SAMPLE_BATCH_SIZE, SAMPLE_BATCH_SIZE, false)) throw new Error(describePushFailure([resolved.source.entity]));
+		if (!await syncOne(resolved.source, resolved.path, "delta", resolved.objectType, runId, SAMPLE_BATCH_SIZE, SAMPLE_BATCH_SIZE, false)) throw pushFailureError(describePushFailure([resolved.source.entity]));
 	};
 	const describeSyncTrigger = () => ({
 		configured: config.syncTrigger?.url,

package/{sdk-C0DU5KDS.mjs → sdk-DofHordq.mjs}

@@ -392,11 +392,15 @@ function errorMessage(error) {
 /**
 * The entities to ask about, in the exact terms the sync pushes them.
 *
-* `source` is the resolved `SyncSource.entity` — the value that arrives at
+* `source` is whatever the push will actually send — the value that arrives at
 * `ingestPush` as `input.source` and is compared against `mapping.sourceTable`.
+* Usually that is `SyncSource.entity`, but a projection pushes under its base
+* table, so this asks `customPushSource` rather than reading `entity` directly.
+*
 * It is NOT the entity config's own `source` field, which names a host table;
-* the two are routinely conflated, and using the wrong one would report every
-* correctly mapped workspace as unmapped.
+* the two are routinely conflated, and using the wrong one reports a correctly
+* mapped workspace as unmapped — which is exactly what happened to every
+* projection until this used the push label.
 */
 function readinessEntitiesFromConfig(config) {
 	const entities = [];
@@ -405,7 +409,7 @@ function readinessEntitiesFromConfig(config) {
 		if (!resolved) continue;
 		const objectTypeSlug = resolved.source.objectType;
 		entities.push({
-			source: resolved.source.entity,
+			source: customPushSource(config, resolved.source),
 			concept: resolved.concept,
 			...resolved.concept === "custom" && objectTypeSlug ? { objectTypeSlug } : {}
 		});
@@ -1468,8 +1472,18 @@ function jsonResponse$1(body, status) {
 function normalizeApiUrl(apiUrl) {
 	return apiUrl.replace(TRAILING_SLASH$1, "");
 }
-function resolveOrigin(req) {
-	const headerOrigin = req.headers.get("origin");
+/**
+* The origin *claimed* by the request, for reporting upstream.
+*
+* Falls back to the request URL so Clivly still receives an origin for a
+* non-browser caller. This value is reported, never trusted: only a real
+* `Origin` header is evidence of where a request came from, so the access
+* decision uses {@link trustedOrigin} instead. Keeping the two apart is the
+* point — conflating them let a caller that simply omitted the header be
+* judged against the server's own origin, which is usually in the allowlist.
+*/
+function reportedOrigin(req) {
+	const headerOrigin = trustedOrigin(req);
 	if (headerOrigin) return headerOrigin;
 	try {
 		return new URL(req.url).origin;
@@ -1477,6 +1491,15 @@ function resolveOrigin(req) {
 		return null;
 	}
 }
+/**
+* The only origin worth an access decision: one the browser set itself.
+*
+* A missing header means "not a browser request we can vouch for", which is
+* untrusted — never the server's own origin.
+*/
+function trustedOrigin(req) {
+	return req.headers.get("origin");
+}
 function isChatSessionRequestBody(value) {
 	if (typeof value !== "object" || value === null) return false;
 	const body = value;
@@ -1487,6 +1510,17 @@ function isChatSessionRequestBody(value) {
 	if (typeof visitor.email !== "string" || visitor.email.trim().length === 0) return false;
 	return body.visitorToken === void 0 || body.visitorToken === null || typeof body.visitorToken === "string";
 }
+/**
+* Judge a request against the configured allowlist.
+*
+* `origin` must be a *trusted* origin (see {@link trustedOrigin}) — passing
+* the reported one would reinstate the bypass this guards against.
+*
+* An unset allowlist still admits every origin, because requiring it would
+* break every existing deployment on upgrade. The unset case is instead
+* warned about once at construction, so the permissive default is loud
+* rather than silent.
+*/
 function originAllowed(origin, allowedOrigins) {
 	if (!allowedOrigins || allowedOrigins.length === 0) return true;
 	if (!origin) return false;
@@ -1494,6 +1528,7 @@ function originAllowed(origin, allowedOrigins) {
 }
 function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API_URL$1, fetchImpl = fetch, resolveUser }) {
 	const sessionUrl = `${normalizeApiUrl(apiUrl)}/clivly/widget/session`;
+	if (!allowedOrigins || allowedOrigins.length === 0) console.warn("[clivly] createChatSessionHandler has no allowedOrigins; every origin can open a chat session against this workspace. Pass allowedOrigins to restrict it.");
 	return async (request) => {
 		if (request.method !== "POST") return new Response(JSON.stringify({ error: "method_not_allowed" }), {
 			status: 405,
@@ -1502,8 +1537,8 @@ function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API
 				allow: "POST"
 			}
 		});
-		const origin = resolveOrigin(request);
-		if (!originAllowed(origin, allowedOrigins)) return jsonResponse$1({ error: "origin_not_allowed" }, 403);
+		if (!originAllowed(trustedOrigin(request), allowedOrigins)) return jsonResponse$1({ error: "origin_not_allowed" }, 403);
+		const origin = reportedOrigin(request);
 		let body;
 		try {
 			body = await request.json();
@@ -1701,6 +1736,18 @@ var TriggerRequestError = class extends Error {
 function triggerErrorStatus(error) {
 	return error instanceof TriggerRequestError ? error.status : 500;
 }
+const SENTENCE_END_RE = /[.!?]$/;
+async function readPushFailureMessage(response) {
+	if (!response || typeof response.json !== "function") return null;
+	try {
+		const body = await response.json();
+		if (typeof body !== "object" || body === null) return null;
+		const { message } = body;
+		return typeof message === "string" && message.trim().length > 0 ? message : null;
+	} catch {
+		return null;
+	}
+}
 const SIGNATURE_TOLERANCE_SECONDS = 300;
 const SIGNATURE_HEADER_RE = /^t=(\d+),v1=([0-9a-f]+)$/;
 const SECONDS_PER_MS = 1e3;
@@ -1923,17 +1970,27 @@ function createClivlySDK(config) {
 			}, response);
 			return true;
 		}
-		lastPushFailure ??= { status: response?.status ?? null };
+		lastPushFailure ??= {
+			status: response?.status ?? null,
+			message: await readPushFailureMessage(response)
+		};
 		return false;
 	};
 	const describePushFailure = (entities) => {
 		const base = `Clivly sync: push failed for ${entities.join(", ")}`;
 		const status = lastPushFailure?.status ?? null;
+		const serverMessage = lastPushFailure?.message ?? null;
 		let cause;
 		if (status === 401 || status === 403) cause = "the API key was rejected — check CLIVLY_API_KEY is set to a valid key for this org";
 		else if (status === null) cause = `couldn't reach Clivly at ${apiUrl} — check network access and CLIVLY_API_URL`;
+		else if (serverMessage) cause = `Clivly returned HTTP ${status}: ${serverMessage}`;
 		else cause = `Clivly returned HTTP ${status}`;
-		return `${base}: ${cause}. Run \`clivly doctor\` to diagnose.`;
+		const separator = SENTENCE_END_RE.test(cause) ? "" : ".";
+		return `${base}: ${cause}${separator} Run \`clivly doctor\` to diagnose.`;
+	};
+	const pushFailureError = (message) => {
+		const status = lastPushFailure?.status ?? null;
+		return status !== null && status >= CLIENT_ERROR_FLOOR && status < RETRYABLE_STATUS_FLOOR ? new TriggerRequestError(status, message) : new Error(message);
 	};
 	const syncOne = async (source, path, mode, objectType, runId, batchSizeOverride, maxRowsOverride, persistCursor = true) => {
 		const since = mode === "full" ? null : await cursorStore.get(source.entity) ?? null;
@@ -2023,7 +2080,7 @@ function createClivlySDK(config) {
 				failed: true,
 				error: message
 			};
-			throw new Error(message);
+			throw pushFailureError(message);
 		}
 		lastPush = { failed: false };
 	};
@@ -2031,7 +2088,7 @@ function createClivlySDK(config) {
 		const resolved = resolveSampleSource(config, entityKey);
 		if (!resolved) throw new TriggerRequestError(400, `Clivly sync: no source is configured for entity "${entityKey}". The dashboard maps this table, but clivly.config declares no matching entity — add it to \`entities\`, or remove the mapping in Integrations → Mapping.`);
 		lastPushFailure = null;
-		if (!await syncOne(resolved.source, resolved.path, "delta", resolved.objectType, runId, SAMPLE_BATCH_SIZE, SAMPLE_BATCH_SIZE, false)) throw new Error(describePushFailure([resolved.source.entity]));
+		if (!await syncOne(resolved.source, resolved.path, "delta", resolved.objectType, runId, SAMPLE_BATCH_SIZE, SAMPLE_BATCH_SIZE, false)) throw pushFailureError(describePushFailure([resolved.source.entity]));
 	};
 	const describeSyncTrigger = () => ({
 		configured: config.syncTrigger?.url,

package/sdk.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_entity_config = require("./entity-config-C2MfIDL2.cjs");
-const require_sdk = require("./sdk-BAHcnhm7.cjs");
+const require_sdk = require("./sdk-BIYu0N3V.cjs");
 exports.ClivlyAuthError = require_sdk.ClivlyAuthError;
 exports.ClivlyError = require_sdk.ClivlyError;
 exports.ClivlyNetworkError = require_sdk.ClivlyNetworkError;

package/sdk.mjs

@@ -1,3 +1,3 @@
 import { c as defineClivlyConfig, g as validateEntitiesConfig, s as customObjectDeclarations } from "./entity-config-bC3DX9f1.mjs";
-import { a as ClivlyRateLimitError, i as ClivlyNetworkError, n as ClivlyAuthError, o as createChatSessionHandler, r as ClivlyError, s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-C0DU5KDS.mjs";
+import { a as ClivlyRateLimitError, i as ClivlyNetworkError, n as ClivlyAuthError, o as createChatSessionHandler, r as ClivlyError, s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-DofHordq.mjs";
 export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, isPlaceholderUrl, validateEntitiesConfig };