clivly 0.2.0 → 0.2.1

package/view-compiler-B4UYTvRM.d.cts

@@ -0,0 +1,71 @@
+import { a as ClivlyEntitiesConfig } from "./entity-config-GczjD3y8.cjs";
+
+//#region ../core/src/view-compiler.d.ts
+interface CompileOptions {
+  /**
+   * Optional tenant-scoping predicate ANDed into every view's WHERE, e.g.
+   * `{ column: "workspace_id", value: "ws_123" }`. Column must exist on the
+   * entity's source table (the compiler does not verify that — validate first).
+   */
+  orgScope?: {
+    column: string;
+    value: string | number;
+  };
+  /**
+   * Restrict `runSync` to a single entity's view, for a "test with one
+   * record" dry run. See `runSync`'s `sample` option in `sync-engine.ts`.
+   */
+  sample?: {
+    entityKey: string;
+  };
+  /**
+   * Emit views `WITH (security_invoker = true)` so they run with the querying
+   * role's privileges instead of the (owner's) definer privileges — the
+   * default Postgres behaviour, which bypasses the caller's RLS. Defaults to
+   * `true`: the security boundary the product promises. Set `false` only for
+   * hosts on Postgres < 15, which lacks the option.
+   */
+  securityInvoker?: boolean;
+  /** View name prefix. Defaults to `crm_src_`. */
+  viewPrefix?: string;
+}
+interface CompiledView {
+  /** Output column names in SELECT order (`id`, mapped fields, then `<rel>_ref`s). */
+  columns: string[];
+  concept: string;
+  /** `DROP VIEW IF EXISTS …` statement (for teardown / reconfiguration). */
+  dropSql: string;
+  entityKey: string;
+  /** Resolved role — the entity's `role` or `"primary"`. */
+  role: string;
+  sourceTable: string;
+  /** `CREATE OR REPLACE VIEW … AS …` statement. */
+  sql: string;
+  viewName: string;
+}
+declare function compileEntityView(config: ClivlyEntitiesConfig, entityKey: string, options?: CompileOptions): CompiledView;
+/** Compile every entity in the config into its view, in declaration order. */
+declare function compileEntityViews(config: ClivlyEntitiesConfig, options?: CompileOptions): CompiledView[];
+/** The outcome of dry-running one entity's compiled view against the host. */
+interface ExplainResult {
+  entityKey: string;
+  /** The runner's error message when `ok` is false. */
+  error?: string;
+  ok: boolean;
+  /** The compiled view SQL that was run. */
+  sql: string;
+}
+/**
+ * Dry-run each entity's compiled view against the host DB via a caller-provided
+ * `run` function, so `$raw` filter/join fragments — which skip schema validation
+ * (see `validateEntitiesConfig`) — fail loudly *before* the first sync instead of
+ * at sync time. Never throws: each view's outcome is collected into an
+ * `ExplainResult`, so a mapping UI or CLI can show every problem at once.
+ *
+ * `run` should execute the SQL somewhere side-effect-free — e.g. inside a
+ * transaction it rolls back, or by `EXPLAIN`-ing the statement — since the
+ * compiled SQL is a `CREATE OR REPLACE VIEW`.
+ */
+declare function explainEntitiesConfig(config: ClivlyEntitiesConfig, run: (sql: string) => Promise<unknown>, options?: CompileOptions): Promise<ExplainResult[]>;
+//#endregion
+export { compileEntityViews as a, compileEntityView as i, CompiledView as n, explainEntitiesConfig as o, ExplainResult as r, CompileOptions as t };

package/view-compiler-BHzbI9b7.cjs

@@ -0,0 +1,202 @@
+//#region ../core/src/view-compiler.ts
+/**
+* View compiler (Phase 2) — turns a validated entity config into read-only
+* Postgres view DDL.
+*
+* Each entity compiles to `crm_src_<entity>`: a projection over the host table
+* that (a) selects the source primary key as `id` (the sync engine's
+* `source_ref`), (b) aliases mapped columns to their Clivly field names,
+* (c) resolves each relationship to a `<relationship>_ref` column carrying the
+* host-side key, and (d) applies the entity's filter as a WHERE clause.
+*
+* The view is the security boundary: it exposes only allow-listed columns, and
+* the sync engine (Phase 3) reads exclusively from it — never the raw table.
+* Relationship refs stay host-side keys here; Phase 3 maps `<rel>_ref` onto the
+* corresponding `crm_companies.id` mirror row.
+*
+* Pure string generation — no DB access. Config is developer-authored, but all
+* identifiers and literals are still escaped so output is deterministic and
+* injection-safe.
+*/
+/** The source primary-key column. Assumed `id`; the sync engine reads it as `source_ref`. */
+const SOURCE_KEY = "id";
+const DEFAULT_VIEW_PREFIX = "crm_src_";
+const DEFAULT_ROLE = "primary";
+/** Quote a single identifier part, escaping embedded double-quotes. */
+function quoteIdent(name) {
+	return `"${name.replace(/"/g, "\"\"")}"`;
+}
+/** Emit a SQL literal for a scalar filter value. */
+function quoteLiteral(value) {
+	if (typeof value === "number") return String(value);
+	if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+	return `'${value.replace(/'/g, "''")}'`;
+}
+function quoteList(values) {
+	return `(${values.map((v) => quoteLiteral(v)).join(", ")})`;
+}
+/** Compile one column predicate into a SQL boolean expression. */
+function compilePredicate(table, column, value) {
+	const col = `${quoteIdent(table)}.${quoteIdent(column)}`;
+	if (value === null || typeof value !== "object") return `${col} = ${quoteLiteral(value)}`;
+	if ("eq" in value) return `${col} = ${quoteLiteral(value.eq)}`;
+	if ("ne" in value) return `${col} <> ${quoteLiteral(value.ne)}`;
+	if ("in" in value) return `${col} IN ${quoteList(value.in)}`;
+	if ("notIn" in value) return `${col} NOT IN ${quoteList(value.notIn)}`;
+	if ("isNull" in value) return `${col} IS NULL`;
+	if ("isNotNull" in value) return `${col} IS NOT NULL`;
+	throw new Error(`unsupported filter predicate on ${table}.${column}`);
+}
+/**
+* Build the WHERE conditions for an entity. Returns an array of SQL fragments
+* (ANDed by the caller). `$raw` filters pass through verbatim.
+*/
+function compileFilterConditions(table, filter) {
+	if (!filter) return [];
+	if ("$raw" in filter) return [`(${filter.$raw})`];
+	return Object.entries(filter).map(([column, value]) => compilePredicate(table, column, value));
+}
+/** Split a `table.column` ref, defaulting the table when unqualified. */
+function refParts(ref, defaultTable) {
+	const dot = ref.indexOf(".");
+	if (dot === -1) return {
+		table: defaultTable,
+		column: ref
+	};
+	return {
+		table: ref.slice(0, dot),
+		column: ref.slice(dot + 1)
+	};
+}
+function compileRelationship(relName, rel, source, related) {
+	const refCol = `${relName}_ref`;
+	const refAlias = quoteIdent(refCol);
+	const { via } = rel;
+	if ("fkOn" in via) {
+		const relatedTable = related?.source ?? "";
+		if (via.fkOn === "company") {
+			const { table, column } = refParts(via.column, relatedTable);
+			const relatedFilter = compileFilterConditions(table, related?.filter);
+			const on = [`${quoteIdent(table)}.${quoteIdent(column)} = ${quoteIdent(source.source)}.${quoteIdent(SOURCE_KEY)}`, ...relatedFilter].join(" AND ");
+			return {
+				clause: `LEFT JOIN ${quoteIdent(table)} ON ${on}`,
+				refSelect: `${quoteIdent(table)}.${quoteIdent(SOURCE_KEY)} AS ${refAlias}`,
+				refColumn: refCol
+			};
+		}
+		const { table, column } = refParts(via.column, source.source);
+		const on = [`${quoteIdent(relatedTable)}.${quoteIdent(SOURCE_KEY)} = ${quoteIdent(table)}.${quoteIdent(column)}`, ...compileFilterConditions(relatedTable, related?.filter)].join(" AND ");
+		return {
+			clause: `LEFT JOIN ${quoteIdent(relatedTable)} ON ${on}`,
+			refSelect: `${quoteIdent(relatedTable)}.${quoteIdent(SOURCE_KEY)} AS ${refAlias}`,
+			refColumn: refCol
+		};
+	}
+	if ("through" in via) {
+		const on = `${quoteIdent(via.through)}.${quoteIdent(via.localKey)} = ${quoteIdent(source.source)}.${quoteIdent(SOURCE_KEY)}`;
+		return {
+			clause: `LEFT JOIN ${quoteIdent(via.through)} ON ${on}`,
+			refSelect: `${quoteIdent(via.through)}.${quoteIdent(via.foreignKey)} AS ${refAlias}`,
+			refColumn: refCol
+		};
+	}
+	return {
+		clause: via.$raw,
+		refSelect: null,
+		refColumn: refCol
+	};
+}
+function compileEntityView(config, entityKey, options = {}) {
+	const entity = config.entities[entityKey];
+	if (!entity) throw new Error(`entity "${entityKey}" is not defined`);
+	const viewName = `${options.viewPrefix ?? DEFAULT_VIEW_PREFIX}${entityKey}`;
+	const src = entity.source;
+	const selectItems = [`${quoteIdent(src)}.${quoteIdent(SOURCE_KEY)} AS ${quoteIdent("id")}`];
+	const columns = ["id"];
+	for (const [field, column] of Object.entries(entity.fields)) {
+		selectItems.push(`${quoteIdent(src)}.${quoteIdent(column)} AS ${quoteIdent(field)}`);
+		columns.push(field);
+	}
+	const joins = [];
+	for (const [relName, rel] of Object.entries(entity.relationships ?? {})) {
+		const compiled = compileRelationship(relName, rel, entity, config.entities[rel.entity]);
+		joins.push(compiled.clause);
+		if (compiled.refSelect) {
+			selectItems.push(compiled.refSelect);
+			columns.push(compiled.refColumn);
+		}
+	}
+	const conditions = compileFilterConditions(src, entity.filter);
+	if (options.orgScope) conditions.push(`${quoteIdent(src)}.${quoteIdent(options.orgScope.column)} = ${quoteLiteral(options.orgScope.value)}`);
+	const lines = [
+		options.securityInvoker ?? true ? `CREATE OR REPLACE VIEW ${quoteIdent(viewName)} WITH (security_invoker = true) AS` : `CREATE OR REPLACE VIEW ${quoteIdent(viewName)} AS`,
+		`SELECT ${selectItems.join(", ")}`,
+		`FROM ${quoteIdent(src)}`,
+		...joins
+	];
+	if (conditions.length > 0) lines.push(`WHERE ${conditions.join(" AND ")}`);
+	const sql = `${lines.join("\n")};`;
+	return {
+		entityKey,
+		viewName,
+		concept: entity.concept,
+		role: entity.role ?? DEFAULT_ROLE,
+		sourceTable: src,
+		columns,
+		sql,
+		dropSql: `DROP VIEW IF EXISTS ${quoteIdent(viewName)};`
+	};
+}
+/** Compile every entity in the config into its view, in declaration order. */
+function compileEntityViews(config, options = {}) {
+	return Object.keys(config.entities).map((key) => compileEntityView(config, key, options));
+}
+/**
+* Dry-run each entity's compiled view against the host DB via a caller-provided
+* `run` function, so `$raw` filter/join fragments — which skip schema validation
+* (see `validateEntitiesConfig`) — fail loudly *before* the first sync instead of
+* at sync time. Never throws: each view's outcome is collected into an
+* `ExplainResult`, so a mapping UI or CLI can show every problem at once.
+*
+* `run` should execute the SQL somewhere side-effect-free — e.g. inside a
+* transaction it rolls back, or by `EXPLAIN`-ing the statement — since the
+* compiled SQL is a `CREATE OR REPLACE VIEW`.
+*/
+async function explainEntitiesConfig(config, run, options = {}) {
+	const results = [];
+	for (const view of compileEntityViews(config, options)) try {
+		await run(view.sql);
+		results.push({
+			entityKey: view.entityKey,
+			ok: true,
+			sql: view.sql
+		});
+	} catch (error) {
+		results.push({
+			entityKey: view.entityKey,
+			ok: false,
+			sql: view.sql,
+			error: error instanceof Error ? error.message : String(error)
+		});
+	}
+	return results;
+}
+//#endregion
+Object.defineProperty(exports, "compileEntityView", {
+	enumerable: true,
+	get: function() {
+		return compileEntityView;
+	}
+});
+Object.defineProperty(exports, "compileEntityViews", {
+	enumerable: true,
+	get: function() {
+		return compileEntityViews;
+	}
+});
+Object.defineProperty(exports, "explainEntitiesConfig", {
+	enumerable: true,
+	get: function() {
+		return explainEntitiesConfig;
+	}
+});

package/view-compiler-CosFGar8.mjs

@@ -0,0 +1,185 @@
+//#region ../core/src/view-compiler.ts
+/**
+* View compiler (Phase 2) — turns a validated entity config into read-only
+* Postgres view DDL.
+*
+* Each entity compiles to `crm_src_<entity>`: a projection over the host table
+* that (a) selects the source primary key as `id` (the sync engine's
+* `source_ref`), (b) aliases mapped columns to their Clivly field names,
+* (c) resolves each relationship to a `<relationship>_ref` column carrying the
+* host-side key, and (d) applies the entity's filter as a WHERE clause.
+*
+* The view is the security boundary: it exposes only allow-listed columns, and
+* the sync engine (Phase 3) reads exclusively from it — never the raw table.
+* Relationship refs stay host-side keys here; Phase 3 maps `<rel>_ref` onto the
+* corresponding `crm_companies.id` mirror row.
+*
+* Pure string generation — no DB access. Config is developer-authored, but all
+* identifiers and literals are still escaped so output is deterministic and
+* injection-safe.
+*/
+/** The source primary-key column. Assumed `id`; the sync engine reads it as `source_ref`. */
+const SOURCE_KEY = "id";
+const DEFAULT_VIEW_PREFIX = "crm_src_";
+const DEFAULT_ROLE = "primary";
+/** Quote a single identifier part, escaping embedded double-quotes. */
+function quoteIdent(name) {
+	return `"${name.replace(/"/g, "\"\"")}"`;
+}
+/** Emit a SQL literal for a scalar filter value. */
+function quoteLiteral(value) {
+	if (typeof value === "number") return String(value);
+	if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+	return `'${value.replace(/'/g, "''")}'`;
+}
+function quoteList(values) {
+	return `(${values.map((v) => quoteLiteral(v)).join(", ")})`;
+}
+/** Compile one column predicate into a SQL boolean expression. */
+function compilePredicate(table, column, value) {
+	const col = `${quoteIdent(table)}.${quoteIdent(column)}`;
+	if (value === null || typeof value !== "object") return `${col} = ${quoteLiteral(value)}`;
+	if ("eq" in value) return `${col} = ${quoteLiteral(value.eq)}`;
+	if ("ne" in value) return `${col} <> ${quoteLiteral(value.ne)}`;
+	if ("in" in value) return `${col} IN ${quoteList(value.in)}`;
+	if ("notIn" in value) return `${col} NOT IN ${quoteList(value.notIn)}`;
+	if ("isNull" in value) return `${col} IS NULL`;
+	if ("isNotNull" in value) return `${col} IS NOT NULL`;
+	throw new Error(`unsupported filter predicate on ${table}.${column}`);
+}
+/**
+* Build the WHERE conditions for an entity. Returns an array of SQL fragments
+* (ANDed by the caller). `$raw` filters pass through verbatim.
+*/
+function compileFilterConditions(table, filter) {
+	if (!filter) return [];
+	if ("$raw" in filter) return [`(${filter.$raw})`];
+	return Object.entries(filter).map(([column, value]) => compilePredicate(table, column, value));
+}
+/** Split a `table.column` ref, defaulting the table when unqualified. */
+function refParts(ref, defaultTable) {
+	const dot = ref.indexOf(".");
+	if (dot === -1) return {
+		table: defaultTable,
+		column: ref
+	};
+	return {
+		table: ref.slice(0, dot),
+		column: ref.slice(dot + 1)
+	};
+}
+function compileRelationship(relName, rel, source, related) {
+	const refCol = `${relName}_ref`;
+	const refAlias = quoteIdent(refCol);
+	const { via } = rel;
+	if ("fkOn" in via) {
+		const relatedTable = related?.source ?? "";
+		if (via.fkOn === "company") {
+			const { table, column } = refParts(via.column, relatedTable);
+			const relatedFilter = compileFilterConditions(table, related?.filter);
+			const on = [`${quoteIdent(table)}.${quoteIdent(column)} = ${quoteIdent(source.source)}.${quoteIdent(SOURCE_KEY)}`, ...relatedFilter].join(" AND ");
+			return {
+				clause: `LEFT JOIN ${quoteIdent(table)} ON ${on}`,
+				refSelect: `${quoteIdent(table)}.${quoteIdent(SOURCE_KEY)} AS ${refAlias}`,
+				refColumn: refCol
+			};
+		}
+		const { table, column } = refParts(via.column, source.source);
+		const on = [`${quoteIdent(relatedTable)}.${quoteIdent(SOURCE_KEY)} = ${quoteIdent(table)}.${quoteIdent(column)}`, ...compileFilterConditions(relatedTable, related?.filter)].join(" AND ");
+		return {
+			clause: `LEFT JOIN ${quoteIdent(relatedTable)} ON ${on}`,
+			refSelect: `${quoteIdent(relatedTable)}.${quoteIdent(SOURCE_KEY)} AS ${refAlias}`,
+			refColumn: refCol
+		};
+	}
+	if ("through" in via) {
+		const on = `${quoteIdent(via.through)}.${quoteIdent(via.localKey)} = ${quoteIdent(source.source)}.${quoteIdent(SOURCE_KEY)}`;
+		return {
+			clause: `LEFT JOIN ${quoteIdent(via.through)} ON ${on}`,
+			refSelect: `${quoteIdent(via.through)}.${quoteIdent(via.foreignKey)} AS ${refAlias}`,
+			refColumn: refCol
+		};
+	}
+	return {
+		clause: via.$raw,
+		refSelect: null,
+		refColumn: refCol
+	};
+}
+function compileEntityView(config, entityKey, options = {}) {
+	const entity = config.entities[entityKey];
+	if (!entity) throw new Error(`entity "${entityKey}" is not defined`);
+	const viewName = `${options.viewPrefix ?? DEFAULT_VIEW_PREFIX}${entityKey}`;
+	const src = entity.source;
+	const selectItems = [`${quoteIdent(src)}.${quoteIdent(SOURCE_KEY)} AS ${quoteIdent("id")}`];
+	const columns = ["id"];
+	for (const [field, column] of Object.entries(entity.fields)) {
+		selectItems.push(`${quoteIdent(src)}.${quoteIdent(column)} AS ${quoteIdent(field)}`);
+		columns.push(field);
+	}
+	const joins = [];
+	for (const [relName, rel] of Object.entries(entity.relationships ?? {})) {
+		const compiled = compileRelationship(relName, rel, entity, config.entities[rel.entity]);
+		joins.push(compiled.clause);
+		if (compiled.refSelect) {
+			selectItems.push(compiled.refSelect);
+			columns.push(compiled.refColumn);
+		}
+	}
+	const conditions = compileFilterConditions(src, entity.filter);
+	if (options.orgScope) conditions.push(`${quoteIdent(src)}.${quoteIdent(options.orgScope.column)} = ${quoteLiteral(options.orgScope.value)}`);
+	const lines = [
+		options.securityInvoker ?? true ? `CREATE OR REPLACE VIEW ${quoteIdent(viewName)} WITH (security_invoker = true) AS` : `CREATE OR REPLACE VIEW ${quoteIdent(viewName)} AS`,
+		`SELECT ${selectItems.join(", ")}`,
+		`FROM ${quoteIdent(src)}`,
+		...joins
+	];
+	if (conditions.length > 0) lines.push(`WHERE ${conditions.join(" AND ")}`);
+	const sql = `${lines.join("\n")};`;
+	return {
+		entityKey,
+		viewName,
+		concept: entity.concept,
+		role: entity.role ?? DEFAULT_ROLE,
+		sourceTable: src,
+		columns,
+		sql,
+		dropSql: `DROP VIEW IF EXISTS ${quoteIdent(viewName)};`
+	};
+}
+/** Compile every entity in the config into its view, in declaration order. */
+function compileEntityViews(config, options = {}) {
+	return Object.keys(config.entities).map((key) => compileEntityView(config, key, options));
+}
+/**
+* Dry-run each entity's compiled view against the host DB via a caller-provided
+* `run` function, so `$raw` filter/join fragments — which skip schema validation
+* (see `validateEntitiesConfig`) — fail loudly *before* the first sync instead of
+* at sync time. Never throws: each view's outcome is collected into an
+* `ExplainResult`, so a mapping UI or CLI can show every problem at once.
+*
+* `run` should execute the SQL somewhere side-effect-free — e.g. inside a
+* transaction it rolls back, or by `EXPLAIN`-ing the statement — since the
+* compiled SQL is a `CREATE OR REPLACE VIEW`.
+*/
+async function explainEntitiesConfig(config, run, options = {}) {
+	const results = [];
+	for (const view of compileEntityViews(config, options)) try {
+		await run(view.sql);
+		results.push({
+			entityKey: view.entityKey,
+			ok: true,
+			sql: view.sql
+		});
+	} catch (error) {
+		results.push({
+			entityKey: view.entityKey,
+			ok: false,
+			sql: view.sql,
+			error: error instanceof Error ? error.message : String(error)
+		});
+	}
+	return results;
+}
+//#endregion
+export { compileEntityViews as n, explainEntitiesConfig as r, compileEntityView as t };

package/view-compiler-i_xFf-L0.d.mts

@@ -0,0 +1,71 @@
+import { a as ClivlyEntitiesConfig } from "./entity-config-D1DFyeUp.mjs";
+
+//#region ../core/src/view-compiler.d.ts
+interface CompileOptions {
+  /**
+   * Optional tenant-scoping predicate ANDed into every view's WHERE, e.g.
+   * `{ column: "workspace_id", value: "ws_123" }`. Column must exist on the
+   * entity's source table (the compiler does not verify that — validate first).
+   */
+  orgScope?: {
+    column: string;
+    value: string | number;
+  };
+  /**
+   * Restrict `runSync` to a single entity's view, for a "test with one
+   * record" dry run. See `runSync`'s `sample` option in `sync-engine.ts`.
+   */
+  sample?: {
+    entityKey: string;
+  };
+  /**
+   * Emit views `WITH (security_invoker = true)` so they run with the querying
+   * role's privileges instead of the (owner's) definer privileges — the
+   * default Postgres behaviour, which bypasses the caller's RLS. Defaults to
+   * `true`: the security boundary the product promises. Set `false` only for
+   * hosts on Postgres < 15, which lacks the option.
+   */
+  securityInvoker?: boolean;
+  /** View name prefix. Defaults to `crm_src_`. */
+  viewPrefix?: string;
+}
+interface CompiledView {
+  /** Output column names in SELECT order (`id`, mapped fields, then `<rel>_ref`s). */
+  columns: string[];
+  concept: string;
+  /** `DROP VIEW IF EXISTS …` statement (for teardown / reconfiguration). */
+  dropSql: string;
+  entityKey: string;
+  /** Resolved role — the entity's `role` or `"primary"`. */
+  role: string;
+  sourceTable: string;
+  /** `CREATE OR REPLACE VIEW … AS …` statement. */
+  sql: string;
+  viewName: string;
+}
+declare function compileEntityView(config: ClivlyEntitiesConfig, entityKey: string, options?: CompileOptions): CompiledView;
+/** Compile every entity in the config into its view, in declaration order. */
+declare function compileEntityViews(config: ClivlyEntitiesConfig, options?: CompileOptions): CompiledView[];
+/** The outcome of dry-running one entity's compiled view against the host. */
+interface ExplainResult {
+  entityKey: string;
+  /** The runner's error message when `ok` is false. */
+  error?: string;
+  ok: boolean;
+  /** The compiled view SQL that was run. */
+  sql: string;
+}
+/**
+ * Dry-run each entity's compiled view against the host DB via a caller-provided
+ * `run` function, so `$raw` filter/join fragments — which skip schema validation
+ * (see `validateEntitiesConfig`) — fail loudly *before* the first sync instead of
+ * at sync time. Never throws: each view's outcome is collected into an
+ * `ExplainResult`, so a mapping UI or CLI can show every problem at once.
+ *
+ * `run` should execute the SQL somewhere side-effect-free — e.g. inside a
+ * transaction it rolls back, or by `EXPLAIN`-ing the statement — since the
+ * compiled SQL is a `CREATE OR REPLACE VIEW`.
+ */
+declare function explainEntitiesConfig(config: ClivlyEntitiesConfig, run: (sql: string) => Promise<unknown>, options?: CompileOptions): Promise<ExplainResult[]>;
+//#endregion
+export { compileEntityViews as a, compileEntityView as i, CompiledView as n, explainEntitiesConfig as o, ExplainResult as r, CompileOptions as t };

package/vite.cjs

@@ -0,0 +1,38 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region ../sdk/src/vite.ts
+/**
+* Vite dev-server plugin that runs the Clivly SDK lifecycle for you: on server
+* boot it calls `sdk.connect()` (for a clear status line) then `sdk.start()`
+* (the heartbeat + sync keep-alive loop), and calls `sdk.stop()` when the dev
+* server closes. Dev-only (`apply: "serve"`) — `start()`'s setInterval loop
+* does not persist on serverless/edge builds, so production on Workers/Lambda
+* should mount `sdk.createClivlyHandler()` and drive it from a cron trigger
+* instead. See docs/guides/connecting-to-clivly-cloud.md.
+*
+* Vite is an optional peer dependency imported type-only (`import type`), so
+* the built bundle carries no runtime dependency on Vite.
+*/
+function clivlyVite(sdk, options = {}) {
+	const label = options.name ?? "clivly";
+	return {
+		name: "clivly",
+		apply: "serve",
+		configureServer(server) {
+			const { logger } = server.config;
+			const boot = async () => {
+				const result = await sdk.connect();
+				if (result.ok) {
+					const org = result.org?.name ?? result.org?.id;
+					logger.info(`${label}: connected${org ? ` to ${org}` : ""}`);
+				} else logger.warn(`${label}: not connected (${result.reason})`);
+				await sdk.start();
+			};
+			boot().catch((error) => {
+				logger.error(`${label}: startup failed — ${error instanceof Error ? error.message : String(error)}`);
+			});
+			server.httpServer?.once("close", () => sdk.stop());
+		}
+	};
+}
+//#endregion
+exports.clivlyVite = clivlyVite;

package/vite.d.cts

@@ -0,0 +1,23 @@
+import { i as ClivlySDK } from "./namespace-probe-BtS0nXcr.cjs";
+import { Plugin } from "vite";
+
+//#region ../sdk/src/vite.d.ts
+interface ClivlyViteOptions {
+  /** Log prefix for Clivly's boot lines. Defaults to "clivly". */
+  name?: string;
+}
+/**
+ * Vite dev-server plugin that runs the Clivly SDK lifecycle for you: on server
+ * boot it calls `sdk.connect()` (for a clear status line) then `sdk.start()`
+ * (the heartbeat + sync keep-alive loop), and calls `sdk.stop()` when the dev
+ * server closes. Dev-only (`apply: "serve"`) — `start()`'s setInterval loop
+ * does not persist on serverless/edge builds, so production on Workers/Lambda
+ * should mount `sdk.createClivlyHandler()` and drive it from a cron trigger
+ * instead. See docs/guides/connecting-to-clivly-cloud.md.
+ *
+ * Vite is an optional peer dependency imported type-only (`import type`), so
+ * the built bundle carries no runtime dependency on Vite.
+ */
+declare function clivlyVite(sdk: ClivlySDK, options?: ClivlyViteOptions): Plugin;
+//#endregion
+export { ClivlyViteOptions, clivlyVite };

package/vite.d.mts

@@ -0,0 +1,23 @@
+import { i as ClivlySDK } from "./namespace-probe-CYMie-BI.mjs";
+import { Plugin } from "vite";
+
+//#region ../sdk/src/vite.d.ts
+interface ClivlyViteOptions {
+  /** Log prefix for Clivly's boot lines. Defaults to "clivly". */
+  name?: string;
+}
+/**
+ * Vite dev-server plugin that runs the Clivly SDK lifecycle for you: on server
+ * boot it calls `sdk.connect()` (for a clear status line) then `sdk.start()`
+ * (the heartbeat + sync keep-alive loop), and calls `sdk.stop()` when the dev
+ * server closes. Dev-only (`apply: "serve"`) — `start()`'s setInterval loop
+ * does not persist on serverless/edge builds, so production on Workers/Lambda
+ * should mount `sdk.createClivlyHandler()` and drive it from a cron trigger
+ * instead. See docs/guides/connecting-to-clivly-cloud.md.
+ *
+ * Vite is an optional peer dependency imported type-only (`import type`), so
+ * the built bundle carries no runtime dependency on Vite.
+ */
+declare function clivlyVite(sdk: ClivlySDK, options?: ClivlyViteOptions): Plugin;
+//#endregion
+export { ClivlyViteOptions, clivlyVite };

package/vite.mjs

@@ -0,0 +1,37 @@
+//#region ../sdk/src/vite.ts
+/**
+* Vite dev-server plugin that runs the Clivly SDK lifecycle for you: on server
+* boot it calls `sdk.connect()` (for a clear status line) then `sdk.start()`
+* (the heartbeat + sync keep-alive loop), and calls `sdk.stop()` when the dev
+* server closes. Dev-only (`apply: "serve"`) — `start()`'s setInterval loop
+* does not persist on serverless/edge builds, so production on Workers/Lambda
+* should mount `sdk.createClivlyHandler()` and drive it from a cron trigger
+* instead. See docs/guides/connecting-to-clivly-cloud.md.
+*
+* Vite is an optional peer dependency imported type-only (`import type`), so
+* the built bundle carries no runtime dependency on Vite.
+*/
+function clivlyVite(sdk, options = {}) {
+	const label = options.name ?? "clivly";
+	return {
+		name: "clivly",
+		apply: "serve",
+		configureServer(server) {
+			const { logger } = server.config;
+			const boot = async () => {
+				const result = await sdk.connect();
+				if (result.ok) {
+					const org = result.org?.name ?? result.org?.id;
+					logger.info(`${label}: connected${org ? ` to ${org}` : ""}`);
+				} else logger.warn(`${label}: not connected (${result.reason})`);
+				await sdk.start();
+			};
+			boot().catch((error) => {
+				logger.error(`${label}: startup failed — ${error instanceof Error ? error.message : String(error)}`);
+			});
+			server.httpServer?.once("close", () => sdk.stop());
+		}
+	};
+}
+//#endregion
+export { clivlyVite };