clivly 0.3.0-next.4 → 0.3.0-next.5

package/index.cjs

@@ -3,7 +3,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_entity_config = require("./entity-config-DMuZpchz.cjs");
 require("./mapping-score-i3p8LWDF.cjs");
 const require_core_entity_heuristics = require("./core-entity-heuristics.cjs");
-const require_sdk = require("./sdk-r4khXzoH.cjs");
+const require_sdk = require("./sdk-Cc51uMdl.cjs");
 let node_child_process = require("node:child_process");
 let node_fs = require("node:fs");
 let node_module = require("node:module");
@@ -533,6 +533,71 @@ function isEntrypoint(argv1, moduleUrl, realpath = node_fs.realpathSync) {
 	return resolve(argv1) === resolve(modulePath);
 }
 //#endregion
+//#region src/load-env.ts
+const LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/;
+const NEWLINE = /\r?\n/;
+const ESCAPED_NEWLINE = /\\n/g;
+const ESCAPED_CARRIAGE = /\\r/g;
+const TRAILING_COMMENT = /\s#/;
+/**
+* Parse `.env` file text into a flat key→value map. Understands `#` comments
+* (whole-line and trailing on unquoted values), single/double quotes,
+* `export KEY=`, and `\n` escapes inside double quotes. Later duplicate keys
+* win, matching how a shell would source the file top-to-bottom.
+*/
+function parseEnv(content) {
+	const out = {};
+	for (const rawLine of content.split(NEWLINE)) {
+		const line = rawLine.trimStart();
+		if (line === "" || line.startsWith("#")) continue;
+		const match = LINE.exec(line);
+		const key = match?.[1];
+		if (!key) continue;
+		out[key] = parseValue(match[2] ?? "");
+	}
+	return out;
+}
+function parseValue(raw) {
+	const value = raw.trim();
+	if (value === "") return "";
+	const quote = value[0];
+	if (quote === "\"" || quote === "'") {
+		const end = value.indexOf(quote, 1);
+		const inner = end === -1 ? value.slice(1) : value.slice(1, end);
+		return quote === "\"" ? inner.replace(ESCAPED_NEWLINE, "\n").replace(ESCAPED_CARRIAGE, "\r") : inner;
+	}
+	const commentAt = value.search(TRAILING_COMMENT);
+	return (commentAt === -1 ? value : value.slice(0, commentAt)).trim();
+}
+/**
+* Load `.env` then `.env.local` from `cwd` into `env` (default `process.env`),
+* WITHOUT overriding anything already set. Precedence, strongest first:
+* real environment (shell) > `.env.local` > `.env`. This mirrors the framework
+* convention developers already expect (Next.js, Vite), so pointing
+* `CLIVLY_API_URL` at a staging host from the shell still wins over the file.
+*/
+function loadEnv(cwd, env = process.env) {
+	const files = [];
+	const merged = {};
+	for (const name of [".env", ".env.local"]) {
+		const path = (0, node_path.join)(cwd, name);
+		if (!(0, node_fs.existsSync)(path)) continue;
+		files.push(name);
+		try {
+			Object.assign(merged, parseEnv((0, node_fs.readFileSync)(path, "utf8")));
+		} catch {}
+	}
+	const applied = [];
+	for (const [key, value] of Object.entries(merged)) if (env[key] === void 0) {
+		env[key] = value;
+		applied.push(key);
+	}
+	return {
+		applied,
+		files
+	};
+}
+//#endregion
 //#region src/login.ts
 const POLL_INTERVAL_MS = 2e3;
 const POLL_BACKOFF_MULTIPLIER = 1.5;
@@ -752,15 +817,25 @@ function placeholderContact(todos) {
 		idField: null
 	};
 }
+function hasMappedFields(entity) {
+	return Object.keys(entity.fields).length > 0;
+}
 function planInit(schema) {
 	const todos = [];
 	const { contact: contactTable, company: companyTable } = selectEntities(schema.tables);
-	const contactDetected = contactTable !== null;
-	const contact = contactTable ? buildEntity(contactTable, "contact", todos) : placeholderContact(todos);
+	let contact = contactTable ? buildEntity(contactTable, "contact", todos) : placeholderContact(todos);
+	let contactDetected = contactTable !== null;
+	if (!hasMappedFields(contact)) {
+		contact = placeholderContact(todos);
+		contactDetected = false;
+	}
 	let company = null;
 	if (companyTable) {
-		company = buildEntity(companyTable, "company", todos);
-		if (require_core_entity_heuristics.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.`);
+		const candidate = buildEntity(companyTable, "company", todos);
+		if (hasMappedFields(candidate)) {
+			company = candidate;
+			if (require_core_entity_heuristics.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.`);
+		} else todos.push(`"${companyTable.tableName}" looked like a company but no fields could be mapped — left it out. Add it to \`entities\` once you know which columns map to name/domain.`);
 	}
 	if (contactTable) {
 		const scored = require_core_entity_heuristics.scoreRelationships(toScoredTable(contactTable), schema.tables.map(toScoredTable));
@@ -1165,13 +1240,33 @@ function resolveConfigPath(cwd, configPath) {
 function firstLine(message) {
 	return message.split("\n")[0]?.trim() ?? "";
 }
+/**
+* Describe why the config failed to load, in one line the developer can act on.
+*
+* A config that fails its own schema validation throws a zod error carrying
+* structured `issues`, but whose `message` is a multi-line JSON dump — its
+* first line is a bare "[", so `firstLine` alone reduced the entire diagnosis
+* to a single bracket. Render the issues as `path: message` instead, which is
+* what actually names the entity to fix. Anything else keeps the require-stack
+* trimming `firstLine` exists for.
+*/
+function describeLoadError(error) {
+	const issues = error.issues;
+	if (Array.isArray(issues) && issues.length > 0) return issues.map((raw) => {
+		const issue = raw;
+		const path = Array.isArray(issue.path) ? issue.path.join(".") : "";
+		const message = typeof issue.message === "string" ? issue.message : "invalid value";
+		return path ? `${path}: ${message}` : message;
+	}).join("; ");
+	return firstLine(error?.message ?? String(error));
+}
 async function loadConfigSdk(path, requiredMethod) {
 	const jiti$1 = (0, jiti.createJiti)(require("url").pathToFileURL(__filename).href);
 	let mod;
 	try {
 		mod = await jiti$1.import(path);
 	} catch (error) {
-		throw new Error(firstLine(error.message));
+		throw new Error(describeLoadError(error));
 	}
 	const sdk = mod.default ?? mod;
 	if (typeof sdk?.[requiredMethod] !== "function") throw new Error("default export is not a Clivly SDK instance");
@@ -1654,7 +1749,7 @@ function previewMutations(deps, mutations) {
 }
 function printNextSteps(out, authComplete, loginRan) {
 	out("\nNext steps:\n");
-	out(loginRan ? "  1. Credentials written by `clivly login`\n" : "  1. Set the CLIVLY_* values in .env\n");
+	out(loginRan ? "  1. Credentials written by `clivly login`\n" : "  1. Add CLIVLY_API_KEY to .env — create one in the Clivly dashboard\n     under Integrations → Create API Key (or Settings → API keys)\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");
 	const step = authComplete ? 3 : 4;
@@ -1872,6 +1967,7 @@ function runInitFromArgv(argv, cwd) {
 }
 async function main(argv) {
 	const [command, ...rest] = argv;
+	loadEnv(process.cwd());
 	switch (command) {
 		case "init": return await runInitFromArgv(rest, process.cwd());
 		case "push-schema": return await runPushSchema({

package/index.mjs

@@ -2,7 +2,7 @@
 import { t as CANONICAL_FIELDS } from "./entity-config-D3YpQB0z.mjs";
 import "./mapping-score-CPPvwoZC.mjs";
 import { matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./core-entity-heuristics.mjs";
-import { t as createClivlySDK } from "./sdk-DtFmeuwl.mjs";
+import { t as createClivlySDK } from "./sdk-BLgY8K0U.mjs";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
@@ -532,6 +532,71 @@ function isEntrypoint(argv1, moduleUrl, realpath = realpathSync) {
 	return resolve(argv1) === resolve(modulePath);
 }
 //#endregion
+//#region src/load-env.ts
+const LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/;
+const NEWLINE = /\r?\n/;
+const ESCAPED_NEWLINE = /\\n/g;
+const ESCAPED_CARRIAGE = /\\r/g;
+const TRAILING_COMMENT = /\s#/;
+/**
+* Parse `.env` file text into a flat key→value map. Understands `#` comments
+* (whole-line and trailing on unquoted values), single/double quotes,
+* `export KEY=`, and `\n` escapes inside double quotes. Later duplicate keys
+* win, matching how a shell would source the file top-to-bottom.
+*/
+function parseEnv(content) {
+	const out = {};
+	for (const rawLine of content.split(NEWLINE)) {
+		const line = rawLine.trimStart();
+		if (line === "" || line.startsWith("#")) continue;
+		const match = LINE.exec(line);
+		const key = match?.[1];
+		if (!key) continue;
+		out[key] = parseValue(match[2] ?? "");
+	}
+	return out;
+}
+function parseValue(raw) {
+	const value = raw.trim();
+	if (value === "") return "";
+	const quote = value[0];
+	if (quote === "\"" || quote === "'") {
+		const end = value.indexOf(quote, 1);
+		const inner = end === -1 ? value.slice(1) : value.slice(1, end);
+		return quote === "\"" ? inner.replace(ESCAPED_NEWLINE, "\n").replace(ESCAPED_CARRIAGE, "\r") : inner;
+	}
+	const commentAt = value.search(TRAILING_COMMENT);
+	return (commentAt === -1 ? value : value.slice(0, commentAt)).trim();
+}
+/**
+* Load `.env` then `.env.local` from `cwd` into `env` (default `process.env`),
+* WITHOUT overriding anything already set. Precedence, strongest first:
+* real environment (shell) > `.env.local` > `.env`. This mirrors the framework
+* convention developers already expect (Next.js, Vite), so pointing
+* `CLIVLY_API_URL` at a staging host from the shell still wins over the file.
+*/
+function loadEnv(cwd, env = process.env) {
+	const files = [];
+	const merged = {};
+	for (const name of [".env", ".env.local"]) {
+		const path = join(cwd, name);
+		if (!existsSync(path)) continue;
+		files.push(name);
+		try {
+			Object.assign(merged, parseEnv(readFileSync(path, "utf8")));
+		} catch {}
+	}
+	const applied = [];
+	for (const [key, value] of Object.entries(merged)) if (env[key] === void 0) {
+		env[key] = value;
+		applied.push(key);
+	}
+	return {
+		applied,
+		files
+	};
+}
+//#endregion
 //#region src/login.ts
 const POLL_INTERVAL_MS = 2e3;
 const POLL_BACKOFF_MULTIPLIER = 1.5;
@@ -751,15 +816,25 @@ function placeholderContact(todos) {
 		idField: null
 	};
 }
+function hasMappedFields(entity) {
+	return Object.keys(entity.fields).length > 0;
+}
 function planInit(schema) {
 	const todos = [];
 	const { contact: contactTable, company: companyTable } = selectEntities(schema.tables);
-	const contactDetected = contactTable !== null;
-	const contact = contactTable ? buildEntity(contactTable, "contact", todos) : placeholderContact(todos);
+	let contact = contactTable ? buildEntity(contactTable, "contact", todos) : placeholderContact(todos);
+	let contactDetected = contactTable !== null;
+	if (!hasMappedFields(contact)) {
+		contact = placeholderContact(todos);
+		contactDetected = false;
+	}
 	let company = null;
 	if (companyTable) {
-		company = buildEntity(companyTable, "company", todos);
-		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.`);
+		const candidate = buildEntity(companyTable, "company", todos);
+		if (hasMappedFields(candidate)) {
+			company = candidate;
+			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.`);
+		} else todos.push(`"${companyTable.tableName}" looked like a company but no fields could be mapped — left it out. Add it to \`entities\` once you know which columns map to name/domain.`);
 	}
 	if (contactTable) {
 		const scored = scoreRelationships(toScoredTable(contactTable), schema.tables.map(toScoredTable));
@@ -1164,13 +1239,33 @@ function resolveConfigPath(cwd, configPath) {
 function firstLine(message) {
 	return message.split("\n")[0]?.trim() ?? "";
 }
+/**
+* Describe why the config failed to load, in one line the developer can act on.
+*
+* A config that fails its own schema validation throws a zod error carrying
+* structured `issues`, but whose `message` is a multi-line JSON dump — its
+* first line is a bare "[", so `firstLine` alone reduced the entire diagnosis
+* to a single bracket. Render the issues as `path: message` instead, which is
+* what actually names the entity to fix. Anything else keeps the require-stack
+* trimming `firstLine` exists for.
+*/
+function describeLoadError(error) {
+	const issues = error.issues;
+	if (Array.isArray(issues) && issues.length > 0) return issues.map((raw) => {
+		const issue = raw;
+		const path = Array.isArray(issue.path) ? issue.path.join(".") : "";
+		const message = typeof issue.message === "string" ? issue.message : "invalid value";
+		return path ? `${path}: ${message}` : message;
+	}).join("; ");
+	return firstLine(error?.message ?? String(error));
+}
 async function loadConfigSdk(path, requiredMethod) {
 	const jiti = createJiti(import.meta.url);
 	let mod;
 	try {
 		mod = await jiti.import(path);
 	} catch (error) {
-		throw new Error(firstLine(error.message));
+		throw new Error(describeLoadError(error));
 	}
 	const sdk = mod.default ?? mod;
 	if (typeof sdk?.[requiredMethod] !== "function") throw new Error("default export is not a Clivly SDK instance");
@@ -1653,7 +1748,7 @@ function previewMutations(deps, mutations) {
 }
 function printNextSteps(out, authComplete, loginRan) {
 	out("\nNext steps:\n");
-	out(loginRan ? "  1. Credentials written by `clivly login`\n" : "  1. Set the CLIVLY_* values in .env\n");
+	out(loginRan ? "  1. Credentials written by `clivly login`\n" : "  1. Add CLIVLY_API_KEY to .env — create one in the Clivly dashboard\n     under Integrations → Create API Key (or Settings → API keys)\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");
 	const step = authComplete ? 3 : 4;
@@ -1871,6 +1966,7 @@ function runInitFromArgv(argv, cwd) {
 }
 async function main(argv) {
 	const [command, ...rest] = argv;
+	loadEnv(process.cwd());
 	switch (command) {
 		case "init": return await runInitFromArgv(rest, process.cwd());
 		case "push-schema": return await runPushSchema({

package/package.json

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

package/{sdk-DtFmeuwl.mjs → sdk-BLgY8K0U.mjs}

@@ -11,7 +11,7 @@ function checkCustomObjectSlugs(config) {
 		name: "Custom object slugs",
 		ok: false,
 		skipped: true,
-		detail: "No custom objects configured."
+		detail: "No custom objects in clivly.config. Objects added in the dashboard need a matching source.custom entry here to sync."
 	};
 	const problems = [];
 	const seen = /* @__PURE__ */ new Map();
@@ -36,6 +36,49 @@ function checkCustomObjectSlugs(config) {
 	};
 }
 //#endregion
+//#region ../sdk/src/fetch-error.ts
+/** Deepest `Error` reachable through the `.cause` chain (the original error if none). */
+function rootError(error) {
+	let current = error;
+	const seen = /* @__PURE__ */ new Set();
+	while (current instanceof Error && current.cause !== void 0 && !seen.has(current)) {
+		seen.add(current);
+		current = current.cause;
+	}
+	return current;
+}
+function codeOf(error) {
+	const code = error?.code;
+	return typeof code === "string" ? code : void 0;
+}
+const CODE_HINTS = {
+	ECONNREFUSED: "the database refused the connection — is Postgres running and is your database URL (e.g. DATABASE_URL) pointing at it?",
+	ENOTFOUND: "the database host couldn't be resolved — check the host in your connection string.",
+	ETIMEDOUT: "the database connection timed out — check the host, port, and firewall.",
+	"28P01": "password authentication failed — check the credentials in your connection string.",
+	"28000": "the database rejected the connection role — check the user in your connection string.",
+	"3D000": "that database does not exist — check the database name in your connection string.",
+	"08006": "the database connection was lost — check that Postgres is reachable."
+};
+const NEWLINE = /\r?\n/;
+/** One-line, single-spaced version of an error message (drops the SQL/params blob). */
+function firstLine(message) {
+	const line = message.split(NEWLINE)[0]?.trim() ?? "";
+	return line === "" ? message.trim() : line;
+}
+/**
+* Build the `detail` string for a failed sample fetch of `entity`.
+* Recognised connection errors get a plain-English hint; everything else
+* surfaces the root cause's first line rather than the wrapper's SQL dump.
+*/
+function describeFetchError(entity, error) {
+	const root = rootError(error);
+	const code = codeOf(root) ?? codeOf(error);
+	const hint = code ? CODE_HINTS[code] : void 0;
+	if (hint) return `Couldn't read "${entity}": ${hint}`;
+	return `Couldn't read "${entity}": ${firstLine(root instanceof Error ? root.message : String(root?.message ?? root ?? "unknown error"))}`;
+}
+//#endregion
 //#region ../sdk/src/namespace-probe.ts
 /**
 * Verify the tables the integration depends on are genuinely reachable:
@@ -187,7 +230,7 @@ async function runDoctor(args) {
 		checks.push({
 			name: `Sample fetch (${source.entity})`,
 			ok: false,
-			detail: `"${source.entity}" fetchPage threw: ${error.message}`
+			detail: describeFetchError(source.entity, error)
 		});
 	}
 	const result = await connect();

package/{sdk-r4khXzoH.cjs → sdk-Cc51uMdl.cjs}

@@ -11,7 +11,7 @@ function checkCustomObjectSlugs(config) {
 		name: "Custom object slugs",
 		ok: false,
 		skipped: true,
-		detail: "No custom objects configured."
+		detail: "No custom objects in clivly.config. Objects added in the dashboard need a matching source.custom entry here to sync."
 	};
 	const problems = [];
 	const seen = /* @__PURE__ */ new Map();
@@ -36,6 +36,49 @@ function checkCustomObjectSlugs(config) {
 	};
 }
 //#endregion
+//#region ../sdk/src/fetch-error.ts
+/** Deepest `Error` reachable through the `.cause` chain (the original error if none). */
+function rootError(error) {
+	let current = error;
+	const seen = /* @__PURE__ */ new Set();
+	while (current instanceof Error && current.cause !== void 0 && !seen.has(current)) {
+		seen.add(current);
+		current = current.cause;
+	}
+	return current;
+}
+function codeOf(error) {
+	const code = error?.code;
+	return typeof code === "string" ? code : void 0;
+}
+const CODE_HINTS = {
+	ECONNREFUSED: "the database refused the connection — is Postgres running and is your database URL (e.g. DATABASE_URL) pointing at it?",
+	ENOTFOUND: "the database host couldn't be resolved — check the host in your connection string.",
+	ETIMEDOUT: "the database connection timed out — check the host, port, and firewall.",
+	"28P01": "password authentication failed — check the credentials in your connection string.",
+	"28000": "the database rejected the connection role — check the user in your connection string.",
+	"3D000": "that database does not exist — check the database name in your connection string.",
+	"08006": "the database connection was lost — check that Postgres is reachable."
+};
+const NEWLINE = /\r?\n/;
+/** One-line, single-spaced version of an error message (drops the SQL/params blob). */
+function firstLine(message) {
+	const line = message.split(NEWLINE)[0]?.trim() ?? "";
+	return line === "" ? message.trim() : line;
+}
+/**
+* Build the `detail` string for a failed sample fetch of `entity`.
+* Recognised connection errors get a plain-English hint; everything else
+* surfaces the root cause's first line rather than the wrapper's SQL dump.
+*/
+function describeFetchError(entity, error) {
+	const root = rootError(error);
+	const code = codeOf(root) ?? codeOf(error);
+	const hint = code ? CODE_HINTS[code] : void 0;
+	if (hint) return `Couldn't read "${entity}": ${hint}`;
+	return `Couldn't read "${entity}": ${firstLine(root instanceof Error ? root.message : String(root?.message ?? root ?? "unknown error"))}`;
+}
+//#endregion
 //#region ../sdk/src/namespace-probe.ts
 /**
 * Verify the tables the integration depends on are genuinely reachable:
@@ -187,7 +230,7 @@ async function runDoctor(args) {
 		checks.push({
 			name: `Sample fetch (${source.entity})`,
 			ok: false,
-			detail: `"${source.entity}" fetchPage threw: ${error.message}`
+			detail: describeFetchError(source.entity, error)
 		});
 	}
 	const result = await connect();

package/sdk.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sdk = require("./sdk-r4khXzoH.cjs");
+const require_sdk = require("./sdk-Cc51uMdl.cjs");
 exports.ClivlyAuthError = require_sdk.ClivlyAuthError;
 exports.ClivlyError = require_sdk.ClivlyError;
 exports.ClivlyNetworkError = require_sdk.ClivlyNetworkError;

package/sdk.mjs

@@ -1,2 +1,2 @@
-import { a as ClivlyRateLimitError, i as ClivlyNetworkError, n as ClivlyAuthError, r as ClivlyError, t as createClivlySDK } from "./sdk-DtFmeuwl.mjs";
+import { a as ClivlyRateLimitError, i as ClivlyNetworkError, n as ClivlyAuthError, r as ClivlyError, t as createClivlySDK } from "./sdk-BLgY8K0U.mjs";
 export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createClivlySDK };