clivly 0.2.0 → 0.2.1

package/{dist/index.mjs → index.mjs}

@@ -1,11 +1,83 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { isAbsolute, join, relative, resolve } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { t as createClivlySDK } from "./sdk-BZUn6wzs.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-DoR0khce.mjs";
+import "./mapping-score-BJNe0lFn.mjs";
+import { matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./core-entity-heuristics.mjs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { createJiti } from "jiti";
-import { createClivlySDK } from "@clivly/sdk";
-import { CANONICAL_FIELDS } from "@clivly/core/entity-config";
-import { matchesConcept, requiredFieldsFor, suggestCursorField, suggestFieldMap, suggestRelationships } from "@clivly/core/entity-heuristics";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawn } from "node:child_process";
+//#region src/render.ts
+function checkLine(ok, label, detail) {
+	return `  ${ok ? "✅" : "❌"} ${label}${detail ? ` — ${detail}` : ""}\n`;
+}
+//#endregion
+//#region src/connect.ts
+const REASON_HINT$1 = {
+	ok: "",
+	invalid_api_key: "The key was rejected (401). Check CLIVLY_API_KEY.",
+	forbidden: "The key lacks access (403).",
+	rate_limited: "Rate limited (429) — retry shortly.",
+	server_error: "Clivly returned a 5xx — retry shortly.",
+	client_error: "The request was rejected (4xx).",
+	network_error: "No response — check the network / apiUrl."
+};
+const defaultConnect$1 = (apiKey, apiUrl) => createClivlySDK({
+	apiKey,
+	apiUrl,
+	retry: { maxAttempts: 1 }
+}).connect();
+const defaultLoadConfig = async (path) => {
+	const mod = await createJiti(import.meta.url).import(path);
+	return mod.default ?? mod;
+};
+/**
+* `clivly connect` — a read-only pass/fail report: API key present → heartbeat
+* (real SDK connect, proving the cloud saw it) → config schema loadable →
+* trigger-URL note. Exit 0 iff the first three pass; a missing trigger URL warns
+* but does not fail (push-only setups are valid). Deps injectable for tests.
+*/
+async function runConnect(options) {
+	const out = options.out ?? ((line) => process.stdout.write(line));
+	out("\nClivly connect\n");
+	if (!options.apiKey) {
+		out(checkLine(false, "CLIVLY_API_KEY is not set."));
+		out("     Set it to your sk_live_… key from Settings → API keys.\n");
+		return 1;
+	}
+	const result = await (options.connectFn ?? defaultConnect$1)(options.apiKey, options.apiUrl);
+	if (result.ok) out(checkLine(true, `Heartbeat reached Clivly — org: ${result.org?.name ?? "(unnamed org)"}${result.org?.id ? ` (${result.org.id})` : ""}`));
+	else {
+		const status = result.status === null ? "no response" : `HTTP ${result.status}`;
+		out(checkLine(false, `Heartbeat failed (${result.reason}, ${status})`));
+		out(`     ${REASON_HINT$1[result.reason]}\n`);
+		return 1;
+	}
+	const path = resolve(options.cwd, options.configPath ?? "clivly.config.ts");
+	const loadConfig = options.loadConfigFn ?? defaultLoadConfig;
+	let config;
+	try {
+		config = await loadConfig(path);
+	} catch (error) {
+		out(checkLine(false, "Load clivly.config", error.message));
+		return 1;
+	}
+	const tables = Object.values(config.entities?.entities ?? {}).map((e) => e.source).filter((s) => Boolean(s));
+	if (tables.length === 0) {
+		out(checkLine(false, "No entities configured in clivly.config"));
+		return 1;
+	}
+	out(checkLine(true, `Schema: ${tables.length} entity table(s) — ${tables.join(", ")}`));
+	const triggerUrl = config.syncTrigger?.url;
+	if (triggerUrl) out(checkLine(true, `Trigger route configured — ${triggerUrl}`));
+	else {
+		out(checkLine(false, "No trigger URL — dashboard-triggered sync is not wired"));
+		out("     Set syncTrigger.url (CLIVLY_SYNC_TRIGGER_URL) to your public tick route.\n");
+	}
+	return 0;
+}
+//#endregion
 //#region src/detect.ts
 const FRAMEWORK_MARKERS = [
 	{
@@ -59,6 +131,34 @@ function detectOrm(deps) {
 	for (const { orm, deps: markers } of ORM_MARKERS) if (markers.some((dep) => dep in deps)) return orm;
 	return "unknown";
 }
+const LOCKFILES = [
+	{
+		file: "pnpm-lock.yaml",
+		pm: "pnpm"
+	},
+	{
+		file: "bun.lockb",
+		pm: "bun"
+	},
+	{
+		file: "yarn.lock",
+		pm: "yarn"
+	},
+	{
+		file: "package-lock.json",
+		pm: "npm"
+	}
+];
+function detectPackageManager(cwd, fileExists = existsSync) {
+	for (const { file, pm } of LOCKFILES) if (fileExists(join(cwd, file))) return pm;
+	return "npm";
+}
+function addCommand(pm, packages) {
+	return {
+		command: pm,
+		args: [pm === "npm" ? "install" : "add", ...packages]
+	};
+}
 //#endregion
 //#region src/discover-schema.ts
 const WINDOWS_SEP = /\\/g;
@@ -81,20 +181,60 @@ function defaultLoader(cwd) {
 	const jiti = createJiti(pathToFileURL(join(cwd, "clivly.config.ts")).href);
 	return (specifier) => jiti.import(specifier);
 }
+async function loadPgCoreRuntime(load) {
+	try {
+		return await load("drizzle-orm/pg-core");
+	} catch {
+		return null;
+	}
+}
+function buildFkByColumn(pgCore, drizzle, table) {
+	const fkByColumn = /* @__PURE__ */ new Map();
+	if (!pgCore) return fkByColumn;
+	try {
+		for (const fk of pgCore.getTableConfig(table).foreignKeys) {
+			const ref = fk.reference();
+			const foreignTable = drizzle.getTableName(ref.foreignTable);
+			ref.columns.forEach((col, i) => {
+				const foreignCol = ref.foreignColumns[i];
+				if (foreignCol) fkByColumn.set(col.name, {
+					table: foreignTable,
+					column: foreignCol.name
+				});
+			});
+		}
+	} catch {}
+	return fkByColumn;
+}
+function toDiscoveredColumn(key, col, fkByColumn) {
+	let type;
+	try {
+		type = col.getSQLType?.();
+	} catch {
+		type = void 0;
+	}
+	const references = fkByColumn.get(col.name);
+	return {
+		key,
+		dbName: col.name,
+		isPrimary: Boolean(col.primary),
+		type,
+		nullable: !col.notNull,
+		...references ? { references } : {}
+	};
+}
 async function discoverSchema(opts) {
 	const load = opts.load ?? defaultLoader(opts.cwd);
 	const mod = await loadSchemaModule(opts.schemaPath, load);
 	const drizzle = await load("drizzle-orm");
+	const pgCore = await loadPgCoreRuntime(load);
 	const importPath = toImportPath(opts.schemaPath, opts.cwd);
 	const tables = [];
 	let db = null;
 	for (const [moduleKey, value] of Object.entries(mod)) {
 		if (drizzle.is(value, drizzle.Table)) {
-			const columns = Object.entries(drizzle.getTableColumns(value)).map(([key, col]) => ({
-				key,
-				dbName: col.name,
-				isPrimary: Boolean(col.primary)
-			}));
+			const fkByColumn = buildFkByColumn(pgCore, drizzle, value);
+			const columns = Object.entries(drizzle.getTableColumns(value)).map(([key, col]) => toDiscoveredColumn(key, col, fkByColumn));
 			tables.push({
 				moduleKey,
 				tableName: drizzle.getTableName(value),
@@ -114,11 +254,6 @@ async function discoverSchema(opts) {
 	};
 }
 //#endregion
-//#region src/render.ts
-function checkLine(ok, label, detail) {
-	return `  ${ok ? "✅" : "❌"} ${label}${detail ? ` — ${detail}` : ""}\n`;
-}
-//#endregion
 //#region src/doctor.ts
 async function loadSdkFromConfig(path) {
 	const mod = await createJiti(import.meta.url).import(path);
@@ -155,6 +290,66 @@ async function runDoctor(options) {
 	return report.ok ? 0 : 1;
 }
 //#endregion
+//#region src/env-file.ts
+function hasKey(content, key) {
+	return new RegExp(`^\\s*${key}=`, "m").test(content);
+}
+/**
+* Append only the `entries` whose key is absent, each preceded by its comment.
+* Existing keys/values are left exactly as-is. Returns the full new content.
+*/
+function appendEnvKeys(existing, entries) {
+	const missing = entries.filter((e) => !hasKey(existing, e.key));
+	if (missing.length === 0) return existing;
+	const block = missing.map((e) => `${e.comment ? `# ${e.comment}\n` : ""}${e.key}=`).join("\n");
+	return `${existing}${existing.length > 0 && !existing.endsWith("\n") ? "\n" : ""}${existing.length > 0 ? "\n" : ""}# Clivly\n${block}\n`;
+}
+//#endregion
+//#region src/install.ts
+const defaultRun = (command, args, cwd) => new Promise((resolvePromise, reject) => {
+	const child = spawn(command, args, {
+		cwd,
+		stdio: "inherit"
+	});
+	child.on("error", reject);
+	child.on("close", (code) => resolvePromise(code ?? 0));
+});
+/**
+* Best-effort install: run `<pm> add <packages>`. Never throws — returns
+* `{ ok, command }` so the caller can print the exact command on failure and
+* continue scaffolding.
+*/
+async function installPackages(options) {
+	const { command, args } = addCommand(options.pm, options.packages);
+	const printable = `${command} ${args.join(" ")}`;
+	const run = options.run ?? defaultRun;
+	try {
+		return {
+			ok: await run(command, args, options.cwd) === 0,
+			command: printable
+		};
+	} catch {
+		return {
+			ok: false,
+			command: printable
+		};
+	}
+}
+//#endregion
+//#region src/is-entry.ts
+function isEntrypoint(argv1, moduleUrl, realpath = realpathSync) {
+	if (!argv1) return false;
+	const modulePath = fileURLToPath(moduleUrl);
+	const resolve = (path) => {
+		try {
+			return realpath(path);
+		} catch {
+			return path;
+		}
+	};
+	return resolve(argv1) === resolve(modulePath);
+}
+//#endregion
 //#region src/ping.ts
 const REASON_HINT = {
 	ok: "",
@@ -202,6 +397,20 @@ async function runPing(options) {
 }
 //#endregion
 //#region src/plan-init.ts
+function toScoredTable(table) {
+	return {
+		name: table.tableName,
+		columns: table.columns.map((c) => c.dbName),
+		columnsMeta: table.columns.map((c) => ({
+			name: c.dbName,
+			type: c.type,
+			nullable: c.nullable,
+			isPrimaryKey: c.isPrimary,
+			isForeignKey: c.references !== void 0,
+			...c.references ? { references: c.references } : {}
+		}))
+	};
+}
 function rankCandidates(tables, concept) {
 	return tables.map((t) => ({
 		t,
@@ -243,7 +452,7 @@ function chooseSyncFields(table, todos) {
 }
 function buildEntity(table, concept, todos) {
 	const canonical = CANONICAL_FIELDS[concept];
-	const suggested = suggestFieldMap(concept, table.columns.map((c) => c.dbName));
+	const suggested = toFieldMap(scoreFieldMap(concept, toScoredTable(table)));
 	const fields = {};
 	for (const [key, column] of Object.entries(suggested)) if (canonical.includes(key)) fields[key] = column;
 	for (const required of requiredFieldsFor(concept)) if (!fields[required]) todos.push(`Could not map required ${concept} field "${required}" on "${table.tableName}" — add it manually.`);
@@ -282,17 +491,13 @@ function planInit(schema) {
 		if (matchesConcept(companyTable.tableName, "contact")) todos.push(`"${companyTable.tableName}" matches both contact and company naming — assigned to company. Swap it to your contact entity if that's wrong.`);
 	}
 	if (contactTable) {
-		const suggestions = suggestRelationships({
-			name: contactTable.tableName,
-			columns: contactTable.columns.map((c) => c.dbName)
-		}, schema.tables.map((t) => ({
-			name: t.tableName,
-			columns: t.columns.map((c) => c.dbName)
-		})));
-		const only = suggestions[0];
-		if (suggestions.length === 1 && only) contact.relationship = {
-			name: only.name,
-			via: only.via
+		const scored = scoreRelationships(toScoredTable(contactTable), schema.tables.map(toScoredTable));
+		const top = scored[0];
+		const runnerUp = scored[1];
+		const isClearWinner = top !== void 0 && (runnerUp === void 0 || top.score - runnerUp.score >= 15);
+		if (top && isClearWinner) contact.relationship = {
+			name: top.value.name,
+			via: top.value.via
 		};
 	}
 	return {
@@ -306,6 +511,24 @@ function planInit(schema) {
 }
 //#endregion
 //#region src/render-config.ts
+const CLIVLY_ENV_KEYS = [
+	{
+		key: "CLIVLY_API_KEY",
+		comment: "Org API key — Settings → API keys"
+	},
+	{
+		key: "CLIVLY_SYNC_TRIGGER_URL",
+		comment: "Public URL of your mounted tick route (e.g. https://app.example.com/api/clivly/tick)"
+	},
+	{
+		key: "CLIVLY_SYNC_TRIGGER_SECRET",
+		comment: "Signing secret — Integrations → Remote sync"
+	},
+	{
+		key: "CLIVLY_VERIFY_TOKEN",
+		comment: "Bearer token Clivly presents to /clivly/auth/verify"
+	}
+];
 function renderFields(fields) {
 	return `{ ${Object.entries(fields).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(", ")} }`;
 }
@@ -357,6 +580,12 @@ export default createClivlySDK({
   source: {
 ${sources.join(",\n")},
   },
+  syncTrigger: {
+    // The public URL Clivly Cloud calls to trigger a sync — your mounted tick route.
+    url: process.env.CLIVLY_SYNC_TRIGGER_URL,
+    secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET,
+  },
+  verifyToken: process.env.CLIVLY_VERIFY_TOKEN,
 });
 `;
 }
@@ -403,6 +632,108 @@ function resolveSchemaPath(opts) {
 	return null;
 }
 //#endregion
+//#region src/scaffold.ts
+const TANSTACK_ROUTE_PREFIX = /^src\/routes\//;
+const TS_EXTENSION = /\.ts$/;
+const ROUTE_PATHS = {
+	nextjs: {
+		tick: "app/api/clivly/tick/route.ts",
+		verify: "app/api/clivly/auth/verify/route.ts"
+	},
+	"tanstack-start": {
+		tick: "src/routes/api/clivly/tick.ts",
+		verify: "src/routes/api/clivly/auth/verify.ts"
+	},
+	sveltekit: {
+		tick: "src/routes/api/clivly/tick/+server.ts",
+		verify: "src/routes/api/clivly/auth/verify/+server.ts"
+	},
+	remix: {
+		tick: "app/routes/api.clivly.tick.ts",
+		verify: "app/routes/api.clivly.auth.verify.ts"
+	},
+	nuxt: {
+		tick: "server/api/clivly/tick.ts",
+		verify: "server/api/clivly/auth/verify.ts"
+	},
+	unknown: null
+};
+function routePath(framework, kind) {
+	const paths = ROUTE_PATHS[framework];
+	if (!paths) throw new Error(`No route path for framework: ${framework}`);
+	return paths[kind];
+}
+function configImport(routeFilePath) {
+	const rel = relative(dirname(routeFilePath), "clivly.config").replace(/\\/g, "/");
+	return rel.startsWith(".") ? rel : `./${rel}`;
+}
+function renderBody(framework, importPath, verify) {
+	const preamble = verify ? `import clivly from "${importPath}";
+
+// TODO(clivly): resolve the signed-in host user from the request (your auth stack).
+const resolveUser = (_req: Request) => null;
+const handler = clivly.createAuthVerifyHandler(resolveUser);
+` : `import clivly from "${importPath}";
+
+const handler = clivly.createClivlyHandler();
+`;
+	switch (framework) {
+		case "nextjs": return `${preamble}
+export const POST = (request: Request) => handler(request);
+`;
+		case "tanstack-start": return `import { createAPIFileRoute } from "@tanstack/react-start/api";
+${preamble}
+export const APIRoute = createAPIFileRoute("__ROUTE__")({
+  POST: ({ request }) => handler(request),
+});
+`;
+		case "sveltekit": return `import type { RequestHandler } from "./$types";
+${preamble}
+export const POST: RequestHandler = ({ request }) => handler(request);
+`;
+		case "remix": return `import type { ActionFunctionArgs } from "@remix-run/node";
+${preamble}
+export const action = ({ request }: ActionFunctionArgs) => handler(request);
+`;
+		case "nuxt": return `import { toWebRequest } from "h3";
+${preamble}
+export default defineEventHandler((event) => handler(toWebRequest(event)));
+`;
+		default: throw new Error(`No route template for framework: ${framework}`);
+	}
+}
+function renderRouteFile(framework, kind) {
+	const path = routePath(framework, kind);
+	let body = renderBody(framework, configImport(path), kind === "verify");
+	if (framework === "tanstack-start") {
+		const url = `/${path.replace(TANSTACK_ROUTE_PREFIX, "").replace(TS_EXTENSION, "")}`;
+		body = body.replace("__ROUTE__", url);
+	}
+	return body;
+}
+const COMMON_FILES = [{
+	path: "clivly.config.ts",
+	description: "Your Clivly configuration",
+	owned: false
+}];
+function planScaffold(framework) {
+	const paths = ROUTE_PATHS[framework];
+	if (!paths) return [];
+	return [
+		{
+			path: paths.tick,
+			description: "Clivly sync-trigger route (createClivlyHandler)",
+			owned: true
+		},
+		{
+			path: paths.verify,
+			description: "Clivly auth-verify route (createAuthVerifyHandler) — finish resolveUser",
+			owned: true
+		},
+		...COMMON_FILES
+	];
+}
+//#endregion
 //#region src/index.ts
 function flagValue(argv, flag) {
 	const index = argv.indexOf(flag);
@@ -421,6 +752,13 @@ function readDeps(cwd) {
 		return {};
 	}
 }
+function defaultReadEnv(cwd) {
+	const path = join(cwd, ".env");
+	return existsSync(path) ? readFileSync(path, "utf8") : "";
+}
+function defaultWriteEnv(cwd, contents) {
+	writeFileSync(join(cwd, ".env"), contents, "utf8");
+}
 function resolveInitDeps(options) {
 	return {
 		out: options.out ?? ((line) => process.stdout.write(line)),
@@ -434,7 +772,15 @@ function resolveInitDeps(options) {
 			cwd
 		})),
 		configExists: options.configExists ?? existsSync,
-		writeConfig: options.writeConfig ?? ((path, contents) => writeFileSync(path, contents, "utf8"))
+		writeConfig: options.writeConfig ?? ((path, contents) => {
+			mkdirSync(dirname(path), { recursive: true });
+			writeFileSync(path, contents, "utf8");
+		}),
+		detectPackageManager: options.detectPackageManager ?? detectPackageManager,
+		install: options.installPackages ?? installPackages,
+		readEnv: options.readEnv ?? defaultReadEnv,
+		writeEnv: options.writeEnv ?? defaultWriteEnv,
+		framework: "unknown"
 	};
 }
 async function acquireSchema(options, deps) {
@@ -446,6 +792,7 @@ async function acquireSchema(options, deps) {
 	}
 	const framework = detectFramework(appDeps);
 	const orm = detectOrm(appDeps);
+	deps.framework = framework;
 	out("\nClivly init\n");
 	out(`  Framework: ${FRAMEWORK_LABELS[framework]}\n`);
 	out(`  ORM:       ${orm}\n\n`);
@@ -453,6 +800,10 @@ async function acquireSchema(options, deps) {
 		out(`clivly init currently generates config for Drizzle only. Detected ORM: ${orm}\n`);
 		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");
+		return { code: 1 };
+	}
 	const schemaPath = deps.resolvePath(options.cwd);
 	if (!schemaPath) {
 		out("Could not locate your Drizzle schema. Pass --schema <path>, or add a `schema` field to drizzle.config.ts.\n");
@@ -483,20 +834,48 @@ function printPlan(out, plan) {
 		out("\n");
 	}
 }
-function writePlan(options, deps, plan) {
+function writeOwnedFile(options, deps, path, contents) {
+	const full = join(options.cwd, path);
+	if (deps.configExists(full) && !options.force) {
+		deps.out(`  • ${path} exists — skipped (pass --force to overwrite)\n`);
+		return;
+	}
+	deps.writeConfig(full, contents);
+	deps.out(`  ✓ ${path}\n`);
+}
+function writeScaffoldFiles(options, deps, plan) {
+	writeOwnedFile(options, deps, "clivly.config.ts", renderInitConfig(plan));
+	for (const file of planScaffold(deps.framework)) {
+		if (file.path === "clivly.config.ts") continue;
+		const kind = file.path.includes("verify") ? "verify" : "tick";
+		writeOwnedFile(options, deps, file.path, renderRouteFile(deps.framework, kind));
+	}
+}
+function writeEnvFile(options, deps) {
+	const nextEnv = appendEnvKeys(deps.readEnv(options.cwd), CLIVLY_ENV_KEYS);
+	deps.writeEnv(options.cwd, nextEnv);
+	deps.out("  ✓ .env placeholders\n");
+}
+function printNextSteps(out) {
+	out("\nNext steps:\n");
+	out("  1. Set the CLIVLY_* values in .env\n");
+	out("  2. Set CLIVLY_SYNC_TRIGGER_URL to your public tick route\n");
+	out("  3. Finish resolveUser in the auth/verify route\n");
+	out("  4. Run `clivly connect` to verify\n");
+}
+async function scaffold(options, deps, plan) {
 	const { out } = deps;
-	const configPath = join(options.cwd, "clivly.config.ts");
-	if (!options.write) {
-		out("Dry run. Re-run with --write to scaffold clivly.config.ts.\n");
-		return plan.contactDetected ? 0 : 1;
-	}
-	if (deps.configExists(configPath) && !options.force) {
-		out("clivly.config.ts already exists — pass --force to overwrite.\n");
-		return 0;
-	}
-	deps.writeConfig(configPath, renderInitConfig(plan));
-	out("Created clivly.config.ts\n");
-	out("Next: set CLIVLY_API_KEY, address any TODOs above, then run `clivly doctor`.\n");
+	const pm = deps.detectPackageManager(options.cwd);
+	const result = await deps.install({
+		cwd: options.cwd,
+		pm,
+		packages: ["@clivly/sdk", "@clivly/core"]
+	});
+	if (result.ok) out(`Installed @clivly/sdk @clivly/core (${pm})\n`);
+	else out(`Could not install automatically — run:\n  ${result.command}\n`);
+	writeScaffoldFiles(options, deps, plan);
+	writeEnvFile(options, deps);
+	printNextSteps(out);
 	return plan.contactDetected ? 0 : 1;
 }
 async function runInit(options) {
@@ -505,15 +884,13 @@ async function runInit(options) {
 	if ("code" in acquired) return acquired.code;
 	const plan = planInit(acquired);
 	printPlan(deps.out, plan);
-	return writePlan(options, deps, plan);
+	return scaffold(options, deps, plan);
 }
 async function main(argv) {
 	const [command, ...rest] = argv;
-	const write = rest.includes("--write");
 	switch (command) {
 		case "init": return await runInit({
 			cwd: process.cwd(),
-			write,
 			force: rest.includes("--force"),
 			schemaFlag: flagValue(rest, "--schema")
 		});
@@ -525,17 +902,23 @@ async function main(argv) {
 			cwd: process.cwd(),
 			configPath: flagValue(rest, "--config")
 		});
+		case "connect": return await runConnect({
+			cwd: process.cwd(),
+			apiKey: process.env.CLIVLY_API_KEY,
+			apiUrl: flagValue(rest, "--api-url") ?? process.env.CLIVLY_API_URL,
+			configPath: flagValue(rest, "--config")
+		});
 		case void 0:
 		case "help":
 		case "--help":
-			process.stdout.write("clivly — embed a CRM in your app\n\nUsage:\n  clivly init [--write] [--force] [--schema <path>]   Detect your Drizzle schema and generate clivly.config.ts\n  clivly ping [--api-url <url>]   Verify CLIVLY_API_KEY + reachability\n  clivly doctor [--config <path>]   Verify your clivly.config setup end-to-end\n");
+			process.stdout.write("clivly — embed a CRM in your app\n\nUsage:\n  clivly init [--force] [--schema <path>]   Scaffold Clivly (config, routes, .env) for your app\n  clivly ping [--api-url <url>]   Verify CLIVLY_API_KEY + reachability\n  clivly doctor [--config <path>]   Verify your clivly.config setup end-to-end\n  clivly connect [--config <path>]   One pass/fail check that setup is wired\n");
 			return 0;
 		default:
 			process.stdout.write(`Unknown command: ${command}\n`);
 			return 1;
 	}
 }
-if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(2)).then((code) => {
+if (isEntrypoint(process.argv[1], import.meta.url)) main(process.argv.slice(2)).then((code) => {
 	process.exitCode = code;
 });
 //#endregion

package/mapping-form-BHtPexzI.mjs

@@ -0,0 +1,47 @@
+//#region ../core/src/mapping-form.ts
+/**
+* Build the filter for a discriminated entity: rows where `column` equals
+* `value` belong to this entity (e.g. `role = "owner"`). Returns `undefined`
+* when either side is blank so the caller can omit the filter entirely.
+*/
+function buildFilterFromDiscriminator(column, value) {
+	const col = column?.trim();
+	const val = value.trim();
+	if (!col || val === "") return;
+	return { [col]: { eq: val } };
+}
+/**
+* A stable identity string for a relationship's `via`. Two candidates on the
+* same source table always differ in their join (`fkOn`+column, join-table
+* keys, or raw SQL), so this disambiguates candidates the heuristic gives the
+* same `name` (every contact→company candidate is named "company").
+*/
+function relationshipViaSignature(via) {
+	if ("fkOn" in via) return `fk:${via.fkOn}:${via.column}`;
+	if ("through" in via) return `through:${via.through}:${via.localKey}:${via.foreignKey}`;
+	return `raw:${via.$raw}`;
+}
+/**
+* Compile the selected relationship candidates into the persisted
+* `RelationshipsMap`. Returns `undefined` for an empty selection so the caller
+* omits the field.
+*/
+function buildRelationships(candidates) {
+	if (candidates.length === 0) return;
+	const map = {};
+	for (const candidate of candidates) {
+		let key = candidate.name;
+		let suffix = 2;
+		while (key in map) {
+			key = `${candidate.name}_${suffix}`;
+			suffix++;
+		}
+		map[key] = {
+			entity: candidate.entityTable,
+			via: candidate.via
+		};
+	}
+	return map;
+}
+//#endregion
+export { buildRelationships as n, relationshipViaSignature as r, buildFilterFromDiscriminator as t };