@clivly/core 0.7.2 → 0.7.4

package/README.md

@@ -1,77 +1,111 @@
 # @clivly/core
 
-Contracts and shared helpers for Clivly adapters, config validation, discovery,
-and sync logic.
+ORM- and auth-agnostic contracts and shared domain types for
+[Clivly](https://clivly.com) — the CRM that lives inside your app.
 
-## Who this package is for
+This package defines the interfaces that ORM and auth adapters implement, the
+entity-config schema shared by the SDK and the dashboard's mapping table, and
+the view compiler that turns a mapping into SQL. Its only runtime dependency is
+`zod`.
 
-Most application integrators should install `clivly` and import from
-`clivly/sdk`.
+> **Most integrators never install this directly.** `defineClivlyConfig` is
+> re-exported from `clivly/sdk`, which is where the
+> [integration guide](../../docs/guides/connecting-to-clivly-cloud.md) tells you
+> to import it from. Reach for `@clivly/core` when you are building an adapter
+> or working with the entity config outside an SDK instance.
 
-`@clivly/core` is the lower-level public package for:
+## Prerequisites
 
-- adapter authors
-- tooling authors
-- consumers who intentionally want the contract and utility layer directly
-
-It has a small runtime surface centered on `zod`. `drizzle-orm` is only needed
-when you use the Drizzle discovery subpath.
+| Requirement | Version / note |
+| --- | --- |
+| Node.js | **≥ 22** |
+| `drizzle-orm` | **Optional peer** — only needed for the `/drizzle` subpath |
 
-## Install
+## Installation
 
 ```bash
 npm install @clivly/core
 ```
 
-Optional Drizzle integration:
-
-```bash
-npm install @clivly/core drizzle-orm
-```
-
 ## Exports
 
+Every subpath below is importable independently, so you pull in only what you
+use. The root (`.`) re-exports the contracts, entity config, mapping form, sync
+engine and view compiler — but **not** `/drizzle` (which needs the optional
+peer), `/entity-heuristics`, `/mapping-score`, `/integration-state` or
+`/env-file`.
+
 | Entry | Contents |
 | --- | --- |
-| `@clivly/core` | Re-exports the package surface |
-| `@clivly/core/adapter` | `CRMAdapter` |
-| `@clivly/core/auth-adapter` | `ClivlyAuthAdapter`, `authCustom()`, `MembershipResolver` |
-| `@clivly/core/types` | Shared CRM types and inputs |
-| `@clivly/core/drizzle` | `discoverFromDrizzle(schema)` |
-| `@clivly/core/entity-config` | `defineClivlyConfig`, validators, canonical field metadata |
-| `@clivly/core/view-compiler` | Entity-view compilation helpers |
-| `@clivly/core/sync-engine` | `runSync`, `previewSync`, `reconcile`, `computeSampleWarnings` |
-| `@clivly/core/entity-heuristics` | Concept and mapping inference helpers |
-| `@clivly/core/mapping-score` | Scoring tiers and ambiguity helpers |
-| `@clivly/core/mapping-form` | UI-to-config assembly helpers |
-| `@clivly/core/mappings-config` | Persisted-mapping to entity-config conversion |
-
-## Drizzle schema discovery
+| `@clivly/core` | The re-exported surface: contracts, entity config, mapping form, sync engine, view compiler, shared types |
+| `@clivly/core/adapter` | `CRMAdapter` — the interface every ORM implementation fulfils (org-scoped; contacts, companies, deals, tasks, activities) |
+| `@clivly/core/auth-adapter` | `ClivlyAuthAdapter`, `ClivlyUser`, `authCustom()`, `MembershipResolver`, `CrmMembership` — pluggable host-app identity + the `crm_members` authorization layer |
+| `@clivly/core/entity-config` | `defineClivlyConfig`, `validateEntitiesConfig`, `entitiesConfigSchema`, `CANONICAL_FIELDS`, `CRM_CONCEPTS`, `ClivlyConfigError`, and the config types |
+| `@clivly/core/types` | Shared domain types (`Contact`, `Company`, `Deal`, `Task`, `Note`, `Activity`, inputs, filters, `CrmRole`) |
+| `@clivly/core/drizzle` | `discoverFromDrizzle(schema)` — derive the discovery shape from a Drizzle schema object. Requires the optional `drizzle-orm` peer |
+| `@clivly/core/view-compiler` | `compileEntityView`, `compileEntityViews`, `explainEntitiesConfig`, `DEFAULT_VIEW_PREFIX` |
+| `@clivly/core/mappings-config` | `mappingsToEntitiesConfig`, `EntityMappingRow` — turn `crm_entity_mappings` rows into an entities config |
+| `@clivly/core/mapping-form` | `buildFilterFromDiscriminator`, `buildRelationships`, `relationshipViaSignature` — mapping-UI helpers |
+| `@clivly/core/mapping-score` | Scoring helpers for ranking candidate mappings |
+| `@clivly/core/entity-heuristics` | Table-name heuristics that guess which table holds contacts/companies |
+| `@clivly/core/sync-engine` | `reconcile`, `runSync`, `SyncStore` and friends — the mirror reconciliation engine |
+| `@clivly/core/integration-state` | `INSTALL_COMMAND` and the shared onboarding state machine |
+| `@clivly/core/env-file` | `envFileFor(framework)` — the conventional env filename per framework |
+
+## Five-minute quick start
+
+### Schema discovery (Drizzle)
+
+`discoverFromDrizzle` turns your Drizzle schema into Clivly's discovery shape,
+so you don't hand-author table/column arrays:
 
 ```ts
 import { discoverFromDrizzle } from "@clivly/core/drizzle";
 import * as schema from "./db/schema";
 
 const tables = discoverFromDrizzle(schema);
+// → [{ name: "participants", columns: ["id", "full_name", "email", …] }, …]
+```
+
+Column names are the **real DB names** (`full_name`), not the Drizzle property
+keys (`fullName`).
+
+### Defining an entity config
+
+```ts
+import { defineClivlyConfig } from "@clivly/core/entity-config";
+
+const entities = defineClivlyConfig({
+  entities: {
+    participants: {
+      concept: "contact",
+      source: "participants",                        // the host table name
+      fields: { name: "full_name", email: "email" }, // canonical key → source column
+    },
+  },
+});
 ```
 
-This returns real database column names such as `full_name`, not Drizzle
-property keys such as `fullName`.
+`defineClivlyConfig` validates at load and warns on any non-canonical field key
+that would mirror as empty. `CANONICAL_FIELDS` lists the accepted keys per
+concept; `CRM_CONCEPTS` lists the concepts.
 
-## Example: adapter contract
+### Implementing an adapter
 
 ```ts
-import type { CRMAdapter } from "@clivly/core/adapter";
+import type { CRMAdapter } from "@clivly/core";
 
+// packages/drizzle implements this; Prisma/Kysely can follow.
 function useAdapter(crm: CRMAdapter) {
-  return crm.getContacts("org_1");
+  return crm.getContacts(orgId);
 }
 ```
 
-## `$raw` escape hatch
+## Advanced: the `$raw` escape hatch
 
-Entity `filter`s and relationship `via`s accept a `$raw` SQL fragment for cases
-the structured operators cannot express:
+Entity `filter`s and relationship `via`s accept a `$raw` form — an opaque SQL
+fragment for predicates the operators can't express (e.g. a cross-table
+condition):
 
 ```ts
 defineClivlyConfig({
@@ -86,19 +120,47 @@ defineClivlyConfig({
 });
 ```
 
-`$raw` is intentionally unchecked:
+**`$raw` is unchecked.** `validateEntitiesConfig` deliberately **skips** `$raw`
+filters and joins — it can't know your columns are real or your SQL is valid.
+Two consequences:
 
-- never interpolate untrusted input into it
-- mistakes surface when the query is exercised, not at config-parse time
+- **Injection safety is on you.** Never interpolate untrusted input into a
+  `$raw` string; treat it like handwritten SQL. Everything else in the config is
+  escaped for you; `$raw` is not.
+- **Mistakes surface at sync time, not config time** — unless you dry-run it.
+
+### Dry-run with `explainEntitiesConfig`
+
+`explainEntitiesConfig(config, run, options?)` compiles each entity's view and
+executes it via a runner you provide, so a broken `$raw` fragment fails
+**before** the first sync. It never throws — it returns one `ExplainResult` per
+entity:
+
+```ts
+import { explainEntitiesConfig } from "@clivly/core";
+
+const results = await explainEntitiesConfig(config, (sql) =>
+  // Run somewhere side-effect-free — e.g. a transaction you roll back.
+  db.transaction(async (tx) => {
+    await tx.execute(sql);
+    throw new Rollback();
+  }).catch(swallowRollback)
+);
+
+for (const r of results) {
+  if (!r.ok) console.error(`${r.entityKey}: ${r.error}`);
+}
+```
 
-Use `explainEntitiesConfig()` to dry-run compiled views before your first sync.
+`clivly status` runs the same mapping dry-run as one of its setup checks, so you
+get this during normal verification without wiring it up yourself.
 
-## More docs
+## Related documentation
 
-- Stability policy:
-  [STABILITY.md](https://github.com/amani-joseph/clivly.com/blob/master/STABILITY.md)
-- SDK docs:
-  [packages/sdk/README.md](https://github.com/amani-joseph/clivly.com/blob/master/packages/sdk/README.md)
+- **[Connecting to Clivly Cloud](../../docs/guides/connecting-to-clivly-cloud.md)** — the canonical end-to-end guide
+- [`@clivly/sdk` README](../sdk/README.md) — the runtime that consumes this config
+- [`clivly` CLI README](../cli/README.md) — every command and flag
+- [`STABILITY.md`](../../STABILITY.md) — import tiers before 1.0
 
 ## License
 

package/dist/entity-heuristics.cjs

@@ -101,7 +101,10 @@ const CONCEPT_FIELDS = {
 			"name",
 			"full_name",
 			"fullname",
-			"display_name"
+			"display_name",
+			"first_name",
+			"firstname",
+			"given_name"
 		],
 		required: false
 	}, {
@@ -224,12 +227,28 @@ function suggestCursorField(columnKeys) {
 	return null;
 }
 const MATERIALIZING = new Set(require_entity_config.MATERIALIZING_CONCEPTS);
+const ENDS_IN_CONSONANT_Y = /[^aeiou]y$/;
+const NEEDS_ES = /(s|x|z|ch|sh)$/;
+const IRREGULAR_PLURALS = {
+	person: "people",
+	child: "children",
+	man: "men",
+	woman: "women"
+};
+function pluralize(name) {
+	const irregular = IRREGULAR_PLURALS[name];
+	if (irregular) return irregular;
+	if (ENDS_IN_CONSONANT_Y.test(name)) return `${name.slice(0, -1)}ies`;
+	if (NEEDS_ES.test(name)) return `${name}es`;
+	return `${name}s`;
+}
 function matchesConcept(tableName, concept) {
 	const normalized = tableName.toLowerCase();
 	const entry = TABLE_PATTERNS.find((p) => p.concept === concept);
 	if (!entry) return null;
-	if (entry.names.includes(normalized)) return { exact: true };
-	if (entry.names.some((name) => normalized.includes(name))) return { exact: false };
+	const candidates = [normalized, pluralize(normalized)];
+	if (candidates.some((candidate) => entry.names.includes(candidate))) return { exact: true };
+	if (entry.names.some((name) => candidates.some((candidate) => candidate.includes(name)))) return { exact: false };
 	return null;
 }
 function metaFor(table, column) {
@@ -245,17 +264,18 @@ function scoreConcepts(table) {
 	for (const concept of TARGET_CONCEPTS) {
 		if (!MATERIALIZING.has(concept)) continue;
 		const nameMatch = matchesConcept(table.name, concept);
-		if (!nameMatch) continue;
+		const definingColumns = hasDefiningColumn(concept, table.columns);
+		if (!(nameMatch || definingColumns)) continue;
 		let score = 0;
 		const reasons = [];
-		if (nameMatch.exact) {
+		if (nameMatch?.exact) {
 			score += require_mapping_score.W.nameExact;
 			reasons.push(`name matches "${table.name}"`);
-		} else {
+		} else if (nameMatch) {
 			score += require_mapping_score.W.nameSubstring;
 			reasons.push(`name looks like ${concept}`);
 		}
-		if (hasDefiningColumn(concept, table.columns)) {
+		if (definingColumns) {
 			score += require_mapping_score.W.definingColumn;
 			reasons.push(`has the columns a ${concept} needs`);
 		}

package/dist/entity-heuristics.mjs

@@ -100,7 +100,10 @@ const CONCEPT_FIELDS = {
 			"name",
 			"full_name",
 			"fullname",
-			"display_name"
+			"display_name",
+			"first_name",
+			"firstname",
+			"given_name"
 		],
 		required: false
 	}, {
@@ -223,12 +226,28 @@ function suggestCursorField(columnKeys) {
 	return null;
 }
 const MATERIALIZING = new Set(MATERIALIZING_CONCEPTS);
+const ENDS_IN_CONSONANT_Y = /[^aeiou]y$/;
+const NEEDS_ES = /(s|x|z|ch|sh)$/;
+const IRREGULAR_PLURALS = {
+	person: "people",
+	child: "children",
+	man: "men",
+	woman: "women"
+};
+function pluralize(name) {
+	const irregular = IRREGULAR_PLURALS[name];
+	if (irregular) return irregular;
+	if (ENDS_IN_CONSONANT_Y.test(name)) return `${name.slice(0, -1)}ies`;
+	if (NEEDS_ES.test(name)) return `${name}es`;
+	return `${name}s`;
+}
 function matchesConcept(tableName, concept) {
 	const normalized = tableName.toLowerCase();
 	const entry = TABLE_PATTERNS.find((p) => p.concept === concept);
 	if (!entry) return null;
-	if (entry.names.includes(normalized)) return { exact: true };
-	if (entry.names.some((name) => normalized.includes(name))) return { exact: false };
+	const candidates = [normalized, pluralize(normalized)];
+	if (candidates.some((candidate) => entry.names.includes(candidate))) return { exact: true };
+	if (entry.names.some((name) => candidates.some((candidate) => candidate.includes(name)))) return { exact: false };
 	return null;
 }
 function metaFor(table, column) {
@@ -244,17 +263,18 @@ function scoreConcepts(table) {
 	for (const concept of TARGET_CONCEPTS) {
 		if (!MATERIALIZING.has(concept)) continue;
 		const nameMatch = matchesConcept(table.name, concept);
-		if (!nameMatch) continue;
+		const definingColumns = hasDefiningColumn(concept, table.columns);
+		if (!(nameMatch || definingColumns)) continue;
 		let score = 0;
 		const reasons = [];
-		if (nameMatch.exact) {
+		if (nameMatch?.exact) {
 			score += W.nameExact;
 			reasons.push(`name matches "${table.name}"`);
-		} else {
+		} else if (nameMatch) {
 			score += W.nameSubstring;
 			reasons.push(`name looks like ${concept}`);
 		}
-		if (hasDefiningColumn(concept, table.columns)) {
+		if (definingColumns) {
 			score += W.definingColumn;
 			reasons.push(`has the columns a ${concept} needs`);
 		}

package/dist/env-file.cjs

@@ -0,0 +1,59 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/env-file.ts
+const ENV_FRAMEWORKS = [
+	"next",
+	"tanstack-start",
+	"sveltekit",
+	"remix",
+	"nuxt",
+	"hono-workers"
+];
+const ENV_FILES = {
+	next: ".env.local",
+	"tanstack-start": ".env",
+	sveltekit: ".env",
+	remix: ".env",
+	nuxt: ".env",
+	"hono-workers": ".dev.vars"
+};
+/** The conventional env file for a framework. `.env` when we do not know. */
+function envFileFor(framework) {
+	return ENV_FILES[normalizeFramework(framework)] ?? ".env";
+}
+const ALIASES = {
+	next: "next",
+	nextjs: "next",
+	"next.js": "next",
+	"tanstack-start": "tanstack-start",
+	tanstack: "tanstack-start",
+	sveltekit: "sveltekit",
+	remix: "remix",
+	nuxt: "nuxt",
+	"hono-workers": "hono-workers",
+	hono: "hono-workers",
+	workers: "hono-workers"
+};
+/** The canonical id for a framework name, or null when unrecognised. */
+function normalizeFramework(framework) {
+	if (!framework) return null;
+	return ALIASES[framework.toLowerCase()] ?? null;
+}
+/**
+* Which env file to actually write to.
+*
+* Prefers a file that already holds the key over the conventional one: a
+* project that has been running with credentials in `.env` must not suddenly
+* get a second copy in `.env.local`, leaving two files disagreeing and the
+* stale one still loading. Convention applies to new setups, not to a working
+* one someone already has.
+*/
+function resolveEnvFile(input) {
+	const conventional = envFileFor(input.framework);
+	if (input.existing.includes(conventional)) return conventional;
+	return input.existing[0] ?? conventional;
+}
+//#endregion
+exports.ENV_FRAMEWORKS = ENV_FRAMEWORKS;
+exports.envFileFor = envFileFor;
+exports.normalizeFramework = normalizeFramework;
+exports.resolveEnvFile = resolveEnvFile;

package/dist/env-file.d.cts

@@ -0,0 +1,23 @@
+//#region src/env-file.d.ts
+declare const ENV_FRAMEWORKS: readonly ["next", "tanstack-start", "sveltekit", "remix", "nuxt", "hono-workers"];
+type EnvFramework = (typeof ENV_FRAMEWORKS)[number];
+/** The conventional env file for a framework. `.env` when we do not know. */
+declare function envFileFor(framework: string | null | undefined): string;
+/** The canonical id for a framework name, or null when unrecognised. */
+declare function normalizeFramework(framework: string | null | undefined): EnvFramework | null;
+/**
+ * Which env file to actually write to.
+ *
+ * Prefers a file that already holds the key over the conventional one: a
+ * project that has been running with credentials in `.env` must not suddenly
+ * get a second copy in `.env.local`, leaving two files disagreeing and the
+ * stale one still loading. Convention applies to new setups, not to a working
+ * one someone already has.
+ */
+declare function resolveEnvFile(input: {
+  /** Candidate filenames that already contain the credential, if any. */
+  existing: string[];
+  framework: string | null | undefined;
+}): string;
+//#endregion
+export { ENV_FRAMEWORKS, EnvFramework, envFileFor, normalizeFramework, resolveEnvFile };

package/dist/env-file.d.mts

@@ -0,0 +1,23 @@
+//#region src/env-file.d.ts
+declare const ENV_FRAMEWORKS: readonly ["next", "tanstack-start", "sveltekit", "remix", "nuxt", "hono-workers"];
+type EnvFramework = (typeof ENV_FRAMEWORKS)[number];
+/** The conventional env file for a framework. `.env` when we do not know. */
+declare function envFileFor(framework: string | null | undefined): string;
+/** The canonical id for a framework name, or null when unrecognised. */
+declare function normalizeFramework(framework: string | null | undefined): EnvFramework | null;
+/**
+ * Which env file to actually write to.
+ *
+ * Prefers a file that already holds the key over the conventional one: a
+ * project that has been running with credentials in `.env` must not suddenly
+ * get a second copy in `.env.local`, leaving two files disagreeing and the
+ * stale one still loading. Convention applies to new setups, not to a working
+ * one someone already has.
+ */
+declare function resolveEnvFile(input: {
+  /** Candidate filenames that already contain the credential, if any. */
+  existing: string[];
+  framework: string | null | undefined;
+}): string;
+//#endregion
+export { ENV_FRAMEWORKS, EnvFramework, envFileFor, normalizeFramework, resolveEnvFile };

package/dist/env-file.mjs

@@ -0,0 +1,55 @@
+//#region src/env-file.ts
+const ENV_FRAMEWORKS = [
+	"next",
+	"tanstack-start",
+	"sveltekit",
+	"remix",
+	"nuxt",
+	"hono-workers"
+];
+const ENV_FILES = {
+	next: ".env.local",
+	"tanstack-start": ".env",
+	sveltekit: ".env",
+	remix: ".env",
+	nuxt: ".env",
+	"hono-workers": ".dev.vars"
+};
+/** The conventional env file for a framework. `.env` when we do not know. */
+function envFileFor(framework) {
+	return ENV_FILES[normalizeFramework(framework)] ?? ".env";
+}
+const ALIASES = {
+	next: "next",
+	nextjs: "next",
+	"next.js": "next",
+	"tanstack-start": "tanstack-start",
+	tanstack: "tanstack-start",
+	sveltekit: "sveltekit",
+	remix: "remix",
+	nuxt: "nuxt",
+	"hono-workers": "hono-workers",
+	hono: "hono-workers",
+	workers: "hono-workers"
+};
+/** The canonical id for a framework name, or null when unrecognised. */
+function normalizeFramework(framework) {
+	if (!framework) return null;
+	return ALIASES[framework.toLowerCase()] ?? null;
+}
+/**
+* Which env file to actually write to.
+*
+* Prefers a file that already holds the key over the conventional one: a
+* project that has been running with credentials in `.env` must not suddenly
+* get a second copy in `.env.local`, leaving two files disagreeing and the
+* stale one still loading. Convention applies to new setups, not to a working
+* one someone already has.
+*/
+function resolveEnvFile(input) {
+	const conventional = envFileFor(input.framework);
+	if (input.existing.includes(conventional)) return conventional;
+	return input.existing[0] ?? conventional;
+}
+//#endregion
+export { ENV_FRAMEWORKS, envFileFor, normalizeFramework, resolveEnvFile };

package/dist/integration-state.cjs

@@ -0,0 +1,242 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/integration-state.ts
+const INTEGRATION_STEPS = [
+	"credential",
+	"application",
+	"schema",
+	"mapping",
+	"trigger",
+	"sync",
+	"widget"
+];
+const INTEGRATION_STEP_LABELS = {
+	credential: "Secure credential",
+	application: "Application connected",
+	schema: "Schema discovered",
+	mapping: "Entities mapped",
+	trigger: "Clivly can start a sync",
+	sync: "First sync observed",
+	widget: "Chat widget installed"
+};
+/** Each step's prerequisites. Ordering is enforced by a test, not convention. */
+const STEP_PREREQUISITES = {
+	credential: [],
+	application: ["credential"],
+	schema: ["application"],
+	mapping: ["schema"],
+	trigger: ["application"],
+	sync: ["mapping", "trigger"],
+	widget: ["application"]
+};
+function stepIndex(id) {
+	return INTEGRATION_STEPS.indexOf(id);
+}
+/** A heartbeat older than this means the app stopped checking in. */
+const HEARTBEAT_STALE_MS = 600 * 1e3;
+function formatAge(ms) {
+	if (ms < 6e4) return `${Math.max(1, Math.round(ms / 1e3))}s ago`;
+	if (ms < 36e5) return `${Math.round(ms / 6e4)}m ago`;
+	return `${Math.round(ms / 36e5)}h ago`;
+}
+function heartbeatAge(facts) {
+	return facts.lastHeartbeatAt === null ? null : facts.now - facts.lastHeartbeatAt;
+}
+/** Is the raw condition behind each step met, ignoring prerequisites? */
+function isSatisfied(id, facts) {
+	const age = heartbeatAge(facts);
+	switch (id) {
+		case "credential": return facts.hasCredential;
+		case "application": return age !== null && age < HEARTBEAT_STALE_MS;
+		case "schema": return facts.discoveredTableCount > 0;
+		case "mapping": return facts.mappedEntityCount > 0;
+		case "trigger": return facts.triggerConfigured;
+		case "sync": return facts.lastRun?.ok === true;
+		default: return facts.widgetInstalled;
+	}
+}
+function evidenceFor(id, facts) {
+	const age = heartbeatAge(facts);
+	if (id === "application" && age !== null) return `heartbeat ${formatAge(age)}`;
+	if (id === "schema" && facts.discoveredTableCount > 0) return `found ${facts.discoveredTableCount} tables`;
+	if (id === "mapping" && facts.mappedEntityCount > 0) return `${facts.mappedEntityCount} entity mapped`;
+	if (id === "trigger" && facts.triggerConfigured) return "trigger URL and secret set";
+	if (id === "sync" && facts.lastRun) return `last run ${formatAge(facts.now - facts.lastRun.at)}`;
+	return null;
+}
+function problemFor(id, facts) {
+	if (id === "sync" && facts.lastRun && !facts.lastRun.ok) return {
+		code: "sync_failed",
+		message: facts.lastRun.message ?? "The last sync run failed.",
+		fix: "Open the run log to see the host response."
+	};
+	if (id === "application") {
+		const age = heartbeatAge(facts);
+		if (age !== null && age >= HEARTBEAT_STALE_MS) return {
+			code: "heartbeat_stale",
+			message: `Your app stopped checking in ${formatAge(age)}.`,
+			fix: "Start your app, then run `npx clivly status`."
+		};
+		if (age === null && facts.everConnected) return {
+			code: "heartbeat_stale",
+			message: "Your application stopped checking in.",
+			fix: "Start your app, then run `npx clivly status`."
+		};
+	}
+	return null;
+}
+/**
+* Walk the ladder once. A step is `blocked` when an earlier step it needs has
+* not been satisfied — a prerequisite statement, not a verdict about this step
+* — and only the first unsatisfied step is `active`, so exactly one root cause
+* ever surfaces.
+*/
+function resolveSteps(facts) {
+	const satisfied = /* @__PURE__ */ new Set();
+	const steps = [];
+	let activeTaken = false;
+	for (const id of INTEGRATION_STEPS) {
+		const unmet = STEP_PREREQUISITES[id].find((need) => !satisfied.has(need));
+		const label = INTEGRATION_STEP_LABELS[id];
+		if (isSatisfied(id, facts)) {
+			satisfied.add(id);
+			steps.push({
+				id,
+				label,
+				state: "done",
+				blockedBy: null,
+				evidence: evidenceFor(id, facts),
+				problem: null
+			});
+			continue;
+		}
+		if (unmet !== void 0) {
+			steps.push({
+				id,
+				label,
+				state: "blocked",
+				blockedBy: unmet,
+				evidence: null,
+				problem: null
+			});
+			continue;
+		}
+		const problem = problemFor(id, facts);
+		let state = "active";
+		if (problem) state = "failed";
+		else if (id === "widget") state = "skipped";
+		const claimsAttention = state === "active" || state === "failed";
+		steps.push({
+			id,
+			label,
+			state: activeTaken && state === "active" ? "blocked" : state,
+			blockedBy: null,
+			evidence: evidenceFor(id, facts),
+			problem: activeTaken ? null : problem
+		});
+		if (claimsAttention) activeTaken = true;
+	}
+	return steps;
+}
+const STEP_STATUS_WHEN_ACTIVE = {
+	credential: "not_configured",
+	application: "awaiting_connection",
+	schema: "connected",
+	mapping: "mapping_required",
+	trigger: "trigger_required",
+	sync: "ready_to_sync",
+	widget: "healthy"
+};
+/**
+* Collapse the ladder to the single status the surfaces switch on. Live
+* conditions — a run in flight, a failure, a heartbeat gone quiet — win over
+* ladder position, because they describe the integration as it is now rather
+* than how far setup once got.
+*/
+function deriveStatus(steps, facts) {
+	if (facts.syncInFlight) return "syncing";
+	if (steps.find((step) => step.id === "application")?.problem?.code === "heartbeat_stale") return "disconnected";
+	if (steps.some((step) => step.state === "failed")) return "error";
+	const blocking = steps.find((step) => step.state === "active" || step.state === "blocked");
+	if (blocking) return STEP_STATUS_WHEN_ACTIVE[blocking.id];
+	return facts.warnings.length > 0 ? "warning" : "healthy";
+}
+/**
+* The command that installs Clivly into a host app. Exported because the connect
+* dialog prints it too, and it must be the same string as the one the ladder
+* recommends — that pairing is what C-05 broke.
+*/
+const INSTALL_COMMAND = "npx clivly init";
+const NEXT_BY_STEP = {
+	credential: {
+		label: "Create a credential",
+		command: null,
+		envFile: null
+	},
+	application: {
+		label: "Install Clivly in your app",
+		command: INSTALL_COMMAND,
+		envFile: ".env.local"
+	},
+	schema: {
+		label: "Check what the SDK reported",
+		command: "npx clivly status",
+		envFile: null
+	},
+	mapping: {
+		label: "Choose the table holding your people",
+		command: null,
+		envFile: null
+	},
+	trigger: {
+		label: "Let Clivly start a sync",
+		command: null,
+		envFile: null
+	},
+	sync: {
+		label: "Run the first sync",
+		command: "npx clivly sync",
+		envFile: null
+	},
+	widget: {
+		label: "Install the chat widget",
+		command: null,
+		envFile: null
+	}
+};
+/**
+* THE one producer of `next.command`. Six surfaces previously each invented
+* their own "run this next" string, and one of them named a read-only command
+* as the fix for a write problem (C-05). If you need a command for the
+* next-action slot, call this — do not write another one.
+*/
+function nextAction(steps, status) {
+	if (status === "healthy" || status === "syncing") return null;
+	const blocking = steps.find((step) => step.state === "failed") ?? steps.find((step) => step.state === "active");
+	if (!blocking) return null;
+	if (blocking.problem?.code === "heartbeat_stale") return {
+		label: "Reconnect your app",
+		command: "npx clivly status",
+		envFile: null
+	};
+	return NEXT_BY_STEP[blocking.id];
+}
+function computeIntegrationState(facts) {
+	const steps = resolveSteps(facts);
+	const status = deriveStatus(steps, facts);
+	return {
+		status,
+		steps,
+		next: nextAction(steps, status)
+	};
+}
+//#endregion
+exports.INSTALL_COMMAND = INSTALL_COMMAND;
+exports.INTEGRATION_STEPS = INTEGRATION_STEPS;
+exports.INTEGRATION_STEP_LABELS = INTEGRATION_STEP_LABELS;
+exports.STEP_PREREQUISITES = STEP_PREREQUISITES;
+exports.computeIntegrationState = computeIntegrationState;
+exports.deriveStatus = deriveStatus;
+exports.formatAge = formatAge;
+exports.nextAction = nextAction;
+exports.resolveSteps = resolveSteps;
+exports.stepIndex = stepIndex;

package/dist/integration-state.d.cts

@@ -0,0 +1,88 @@
+//#region src/integration-state.d.ts
+declare const INTEGRATION_STEPS: readonly ["credential", "application", "schema", "mapping", "trigger", "sync", "widget"];
+type StepId = (typeof INTEGRATION_STEPS)[number];
+/** `blocked` means "prerequisite unmet", never "broken" — see C-19. */
+type StepState = "done" | "active" | "blocked" | "failed" | "skipped";
+type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" | "disconnected";
+declare const INTEGRATION_STEP_LABELS: Record<StepId, string>;
+/** Each step's prerequisites. Ordering is enforced by a test, not convention. */
+declare const STEP_PREREQUISITES: Record<StepId, readonly StepId[]>;
+declare function stepIndex(id: StepId): number;
+interface RunFact {
+  at: number;
+  message?: string;
+  ok: boolean;
+}
+interface IntegrationFacts {
+  discoveredTableCount: number;
+  /**
+   * Has this app ever checked in? Distinguishes "never installed" from "was
+   * working, now silent" — the same absent heartbeat means different things,
+   * and only one of them is diagnosed rather than set up.
+   */
+  everConnected: boolean;
+  hasCredential: boolean;
+  lastHeartbeatAt: number | null;
+  lastRun: RunFact | null;
+  mappedEntityCount: number;
+  now: number;
+  syncInFlight: boolean;
+  /** A trigger URL and secret both exist, so Clivly can ask the app to sync. */
+  triggerConfigured: boolean;
+  warnings: string[];
+  widgetInstalled: boolean;
+}
+interface StepProblem {
+  code: string;
+  fix: string;
+  message: string;
+}
+interface IntegrationStep {
+  blockedBy: StepId | null;
+  evidence: string | null;
+  id: StepId;
+  label: string;
+  problem: StepProblem | null;
+  state: StepState;
+}
+declare function formatAge(ms: number): string;
+/**
+ * Walk the ladder once. A step is `blocked` when an earlier step it needs has
+ * not been satisfied — a prerequisite statement, not a verdict about this step
+ * — and only the first unsatisfied step is `active`, so exactly one root cause
+ * ever surfaces.
+ */
+declare function resolveSteps(facts: IntegrationFacts): IntegrationStep[];
+/**
+ * Collapse the ladder to the single status the surfaces switch on. Live
+ * conditions — a run in flight, a failure, a heartbeat gone quiet — win over
+ * ladder position, because they describe the integration as it is now rather
+ * than how far setup once got.
+ */
+declare function deriveStatus(steps: IntegrationStep[], facts: IntegrationFacts): IntegrationStatus;
+interface NextAction {
+  command: string | null;
+  envFile: string | null;
+  label: string;
+}
+interface IntegrationState {
+  next: NextAction | null;
+  status: IntegrationStatus;
+  steps: IntegrationStep[];
+}
+/**
+ * The command that installs Clivly into a host app. Exported because the connect
+ * dialog prints it too, and it must be the same string as the one the ladder
+ * recommends — that pairing is what C-05 broke.
+ */
+declare const INSTALL_COMMAND = "npx clivly init";
+/**
+ * THE one producer of `next.command`. Six surfaces previously each invented
+ * their own "run this next" string, and one of them named a read-only command
+ * as the fix for a write problem (C-05). If you need a command for the
+ * next-action slot, call this — do not write another one.
+ */
+declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus): NextAction | null;
+declare function computeIntegrationState(facts: IntegrationFacts): IntegrationState;
+//#endregion
+export { INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, RunFact, STEP_PREREQUISITES, StepId, StepProblem, StepState, computeIntegrationState, deriveStatus, formatAge, nextAction, resolveSteps, stepIndex };

package/dist/integration-state.d.mts

@@ -0,0 +1,88 @@
+//#region src/integration-state.d.ts
+declare const INTEGRATION_STEPS: readonly ["credential", "application", "schema", "mapping", "trigger", "sync", "widget"];
+type StepId = (typeof INTEGRATION_STEPS)[number];
+/** `blocked` means "prerequisite unmet", never "broken" — see C-19. */
+type StepState = "done" | "active" | "blocked" | "failed" | "skipped";
+type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" | "disconnected";
+declare const INTEGRATION_STEP_LABELS: Record<StepId, string>;
+/** Each step's prerequisites. Ordering is enforced by a test, not convention. */
+declare const STEP_PREREQUISITES: Record<StepId, readonly StepId[]>;
+declare function stepIndex(id: StepId): number;
+interface RunFact {
+  at: number;
+  message?: string;
+  ok: boolean;
+}
+interface IntegrationFacts {
+  discoveredTableCount: number;
+  /**
+   * Has this app ever checked in? Distinguishes "never installed" from "was
+   * working, now silent" — the same absent heartbeat means different things,
+   * and only one of them is diagnosed rather than set up.
+   */
+  everConnected: boolean;
+  hasCredential: boolean;
+  lastHeartbeatAt: number | null;
+  lastRun: RunFact | null;
+  mappedEntityCount: number;
+  now: number;
+  syncInFlight: boolean;
+  /** A trigger URL and secret both exist, so Clivly can ask the app to sync. */
+  triggerConfigured: boolean;
+  warnings: string[];
+  widgetInstalled: boolean;
+}
+interface StepProblem {
+  code: string;
+  fix: string;
+  message: string;
+}
+interface IntegrationStep {
+  blockedBy: StepId | null;
+  evidence: string | null;
+  id: StepId;
+  label: string;
+  problem: StepProblem | null;
+  state: StepState;
+}
+declare function formatAge(ms: number): string;
+/**
+ * Walk the ladder once. A step is `blocked` when an earlier step it needs has
+ * not been satisfied — a prerequisite statement, not a verdict about this step
+ * — and only the first unsatisfied step is `active`, so exactly one root cause
+ * ever surfaces.
+ */
+declare function resolveSteps(facts: IntegrationFacts): IntegrationStep[];
+/**
+ * Collapse the ladder to the single status the surfaces switch on. Live
+ * conditions — a run in flight, a failure, a heartbeat gone quiet — win over
+ * ladder position, because they describe the integration as it is now rather
+ * than how far setup once got.
+ */
+declare function deriveStatus(steps: IntegrationStep[], facts: IntegrationFacts): IntegrationStatus;
+interface NextAction {
+  command: string | null;
+  envFile: string | null;
+  label: string;
+}
+interface IntegrationState {
+  next: NextAction | null;
+  status: IntegrationStatus;
+  steps: IntegrationStep[];
+}
+/**
+ * The command that installs Clivly into a host app. Exported because the connect
+ * dialog prints it too, and it must be the same string as the one the ladder
+ * recommends — that pairing is what C-05 broke.
+ */
+declare const INSTALL_COMMAND = "npx clivly init";
+/**
+ * THE one producer of `next.command`. Six surfaces previously each invented
+ * their own "run this next" string, and one of them named a read-only command
+ * as the fix for a write problem (C-05). If you need a command for the
+ * next-action slot, call this — do not write another one.
+ */
+declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus): NextAction | null;
+declare function computeIntegrationState(facts: IntegrationFacts): IntegrationState;
+//#endregion
+export { INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, RunFact, STEP_PREREQUISITES, StepId, StepProblem, StepState, computeIntegrationState, deriveStatus, formatAge, nextAction, resolveSteps, stepIndex };

package/dist/integration-state.mjs

@@ -0,0 +1,232 @@
+//#region src/integration-state.ts
+const INTEGRATION_STEPS = [
+	"credential",
+	"application",
+	"schema",
+	"mapping",
+	"trigger",
+	"sync",
+	"widget"
+];
+const INTEGRATION_STEP_LABELS = {
+	credential: "Secure credential",
+	application: "Application connected",
+	schema: "Schema discovered",
+	mapping: "Entities mapped",
+	trigger: "Clivly can start a sync",
+	sync: "First sync observed",
+	widget: "Chat widget installed"
+};
+/** Each step's prerequisites. Ordering is enforced by a test, not convention. */
+const STEP_PREREQUISITES = {
+	credential: [],
+	application: ["credential"],
+	schema: ["application"],
+	mapping: ["schema"],
+	trigger: ["application"],
+	sync: ["mapping", "trigger"],
+	widget: ["application"]
+};
+function stepIndex(id) {
+	return INTEGRATION_STEPS.indexOf(id);
+}
+/** A heartbeat older than this means the app stopped checking in. */
+const HEARTBEAT_STALE_MS = 600 * 1e3;
+function formatAge(ms) {
+	if (ms < 6e4) return `${Math.max(1, Math.round(ms / 1e3))}s ago`;
+	if (ms < 36e5) return `${Math.round(ms / 6e4)}m ago`;
+	return `${Math.round(ms / 36e5)}h ago`;
+}
+function heartbeatAge(facts) {
+	return facts.lastHeartbeatAt === null ? null : facts.now - facts.lastHeartbeatAt;
+}
+/** Is the raw condition behind each step met, ignoring prerequisites? */
+function isSatisfied(id, facts) {
+	const age = heartbeatAge(facts);
+	switch (id) {
+		case "credential": return facts.hasCredential;
+		case "application": return age !== null && age < HEARTBEAT_STALE_MS;
+		case "schema": return facts.discoveredTableCount > 0;
+		case "mapping": return facts.mappedEntityCount > 0;
+		case "trigger": return facts.triggerConfigured;
+		case "sync": return facts.lastRun?.ok === true;
+		default: return facts.widgetInstalled;
+	}
+}
+function evidenceFor(id, facts) {
+	const age = heartbeatAge(facts);
+	if (id === "application" && age !== null) return `heartbeat ${formatAge(age)}`;
+	if (id === "schema" && facts.discoveredTableCount > 0) return `found ${facts.discoveredTableCount} tables`;
+	if (id === "mapping" && facts.mappedEntityCount > 0) return `${facts.mappedEntityCount} entity mapped`;
+	if (id === "trigger" && facts.triggerConfigured) return "trigger URL and secret set";
+	if (id === "sync" && facts.lastRun) return `last run ${formatAge(facts.now - facts.lastRun.at)}`;
+	return null;
+}
+function problemFor(id, facts) {
+	if (id === "sync" && facts.lastRun && !facts.lastRun.ok) return {
+		code: "sync_failed",
+		message: facts.lastRun.message ?? "The last sync run failed.",
+		fix: "Open the run log to see the host response."
+	};
+	if (id === "application") {
+		const age = heartbeatAge(facts);
+		if (age !== null && age >= HEARTBEAT_STALE_MS) return {
+			code: "heartbeat_stale",
+			message: `Your app stopped checking in ${formatAge(age)}.`,
+			fix: "Start your app, then run `npx clivly status`."
+		};
+		if (age === null && facts.everConnected) return {
+			code: "heartbeat_stale",
+			message: "Your application stopped checking in.",
+			fix: "Start your app, then run `npx clivly status`."
+		};
+	}
+	return null;
+}
+/**
+* Walk the ladder once. A step is `blocked` when an earlier step it needs has
+* not been satisfied — a prerequisite statement, not a verdict about this step
+* — and only the first unsatisfied step is `active`, so exactly one root cause
+* ever surfaces.
+*/
+function resolveSteps(facts) {
+	const satisfied = /* @__PURE__ */ new Set();
+	const steps = [];
+	let activeTaken = false;
+	for (const id of INTEGRATION_STEPS) {
+		const unmet = STEP_PREREQUISITES[id].find((need) => !satisfied.has(need));
+		const label = INTEGRATION_STEP_LABELS[id];
+		if (isSatisfied(id, facts)) {
+			satisfied.add(id);
+			steps.push({
+				id,
+				label,
+				state: "done",
+				blockedBy: null,
+				evidence: evidenceFor(id, facts),
+				problem: null
+			});
+			continue;
+		}
+		if (unmet !== void 0) {
+			steps.push({
+				id,
+				label,
+				state: "blocked",
+				blockedBy: unmet,
+				evidence: null,
+				problem: null
+			});
+			continue;
+		}
+		const problem = problemFor(id, facts);
+		let state = "active";
+		if (problem) state = "failed";
+		else if (id === "widget") state = "skipped";
+		const claimsAttention = state === "active" || state === "failed";
+		steps.push({
+			id,
+			label,
+			state: activeTaken && state === "active" ? "blocked" : state,
+			blockedBy: null,
+			evidence: evidenceFor(id, facts),
+			problem: activeTaken ? null : problem
+		});
+		if (claimsAttention) activeTaken = true;
+	}
+	return steps;
+}
+const STEP_STATUS_WHEN_ACTIVE = {
+	credential: "not_configured",
+	application: "awaiting_connection",
+	schema: "connected",
+	mapping: "mapping_required",
+	trigger: "trigger_required",
+	sync: "ready_to_sync",
+	widget: "healthy"
+};
+/**
+* Collapse the ladder to the single status the surfaces switch on. Live
+* conditions — a run in flight, a failure, a heartbeat gone quiet — win over
+* ladder position, because they describe the integration as it is now rather
+* than how far setup once got.
+*/
+function deriveStatus(steps, facts) {
+	if (facts.syncInFlight) return "syncing";
+	if (steps.find((step) => step.id === "application")?.problem?.code === "heartbeat_stale") return "disconnected";
+	if (steps.some((step) => step.state === "failed")) return "error";
+	const blocking = steps.find((step) => step.state === "active" || step.state === "blocked");
+	if (blocking) return STEP_STATUS_WHEN_ACTIVE[blocking.id];
+	return facts.warnings.length > 0 ? "warning" : "healthy";
+}
+/**
+* The command that installs Clivly into a host app. Exported because the connect
+* dialog prints it too, and it must be the same string as the one the ladder
+* recommends — that pairing is what C-05 broke.
+*/
+const INSTALL_COMMAND = "npx clivly init";
+const NEXT_BY_STEP = {
+	credential: {
+		label: "Create a credential",
+		command: null,
+		envFile: null
+	},
+	application: {
+		label: "Install Clivly in your app",
+		command: INSTALL_COMMAND,
+		envFile: ".env.local"
+	},
+	schema: {
+		label: "Check what the SDK reported",
+		command: "npx clivly status",
+		envFile: null
+	},
+	mapping: {
+		label: "Choose the table holding your people",
+		command: null,
+		envFile: null
+	},
+	trigger: {
+		label: "Let Clivly start a sync",
+		command: null,
+		envFile: null
+	},
+	sync: {
+		label: "Run the first sync",
+		command: "npx clivly sync",
+		envFile: null
+	},
+	widget: {
+		label: "Install the chat widget",
+		command: null,
+		envFile: null
+	}
+};
+/**
+* THE one producer of `next.command`. Six surfaces previously each invented
+* their own "run this next" string, and one of them named a read-only command
+* as the fix for a write problem (C-05). If you need a command for the
+* next-action slot, call this — do not write another one.
+*/
+function nextAction(steps, status) {
+	if (status === "healthy" || status === "syncing") return null;
+	const blocking = steps.find((step) => step.state === "failed") ?? steps.find((step) => step.state === "active");
+	if (!blocking) return null;
+	if (blocking.problem?.code === "heartbeat_stale") return {
+		label: "Reconnect your app",
+		command: "npx clivly status",
+		envFile: null
+	};
+	return NEXT_BY_STEP[blocking.id];
+}
+function computeIntegrationState(facts) {
+	const steps = resolveSteps(facts);
+	const status = deriveStatus(steps, facts);
+	return {
+		status,
+		steps,
+		next: nextAction(steps, status)
+	};
+}
+//#endregion
+export { INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, STEP_PREREQUISITES, computeIntegrationState, deriveStatus, formatAge, nextAction, resolveSteps, stepIndex };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/core",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "private": false,
   "type": "module",
   "description": "ORM/auth-agnostic CRM adapter contracts and shared domain types for Clivly.",
@@ -47,6 +47,26 @@
         "default": "./dist/mapping-score.cjs"
       }
     },
+    "./integration-state": {
+      "import": {
+        "types": "./dist/integration-state.d.mts",
+        "default": "./dist/integration-state.mjs"
+      },
+      "require": {
+        "types": "./dist/integration-state.d.cts",
+        "default": "./dist/integration-state.cjs"
+      }
+    },
+    "./env-file": {
+      "import": {
+        "types": "./dist/env-file.d.mts",
+        "default": "./dist/env-file.mjs"
+      },
+      "require": {
+        "types": "./dist/env-file.d.cts",
+        "default": "./dist/env-file.cjs"
+      }
+    },
     "./auth-adapter": {
       "import": {
         "types": "./dist/auth-adapter.d.mts",