@clivly/core 0.8.0 → 0.9.0

package/dist/entity-config.mjs

@@ -1,339 +1,2 @@
-import { z } from "zod";
-//#region src/entity-config.ts
-/**
-* Entity Config v2 — the declarative contract that turns Clivly's "schema-aware"
-* promise into a real capability.
-*
-* A CRM entity is no longer a flat table name. It is a *derived entity*: a
-* filtered slice of a host table (`source` + `filter`), a column allowlist
-* (`fields` + `readOnly`), and declared `relationships` to other entities. The
-* same host table can back several entities (e.g. `users` → owners + members)
-* distinguished by `role`.
-*
-* This module is the Phase 1 slice: types, schema, `defineClivlyConfig` (a
-* structural helper) and `validateEntitiesConfig` (semantic validation against
-* the host's discovered schema). It performs NO DB access and generates no SQL —
-* the view compiler (Phase 2) and sync engine (Phase 3) consume this contract.
-*/
-/** Canonical CRM concepts a host entity can map onto. */
-const CRM_CONCEPTS = [
-	"contact",
-	"company",
-	"deal",
-	"activity",
-	"conversation",
-	"note"
-];
-/**
-* The canonical `fields` keys the mirror actually persists, per concept — the
-* crm_* columns the sync store writes. An entity's `fields` map keys must be one
-* of these: a non-canonical key (e.g. `fullName` instead of `name`) validates
-* structurally but has no destination column, so the store silently writes an
-* empty value. `validateEntitiesConfig` flags those.
-*
-* This is the single source of truth — the Drizzle store imports it, so the
-* two can't drift (the drift is what made the silent-data-loss trap possible).
-* Concepts absent here aren't materialized yet, so their field keys are
-* unconstrained.
-*/
-const CANONICAL_FIELDS = {
-	contact: [
-		"name",
-		"email",
-		"title",
-		"status"
-	],
-	company: [
-		"name",
-		"domain",
-		"industry",
-		"size"
-	],
-	deal: [
-		"name",
-		"value",
-		"stage"
-	]
-};
-/**
-* The concepts the mapping→sync pipeline can actually materialize into `crm_*`
-* tables. These are exactly the CANONICAL_FIELDS keys — the Drizzle sync store's
-* `persist()` throws for any other concept, so offering one (in the mapping
-* editor, in suggestions, or via the upsert API) is a broken affordance.
-*
-* The broader CRM_CONCEPTS set still validates structurally, so previously
-* stored rows for not-yet-materialized concepts keep rendering. When a concept
-* gains a sync-store path, add its canonical fields above and it joins this set
-* automatically (guarded by the MATERIALIZING_CONCEPTS drift test).
-*/
-const MATERIALIZING_CONCEPTS = [
-	"contact",
-	"company",
-	"deal"
-];
-/**
-* The org-defined custom-object target. Deliberately NOT a member of
-* CRM_CONCEPTS / CANONICAL_FIELDS / MATERIALIZING_CONCEPTS — a custom object has
-* no fixed canonical columns; its mapping's fieldMap keys ARE its properties.
-* Handled as an explicit branch wherever concepts are switched on, so the
-* canonical-concept invariants (and their drift test) stay intact.
-*/
-const CUSTOM_CONCEPT = "custom";
-/**
-* Operator forms for a single column predicate. All predicates on an entity are
-* AND-ed together. `$raw` (see FilterExpr) is the escape hatch for anything the
-* operators can't express.
-*/
-const filterOperatorsSchema = z.union([
-	z.strictObject({ eq: z.union([
-		z.string(),
-		z.number(),
-		z.boolean()
-	]) }),
-	z.strictObject({ ne: z.union([
-		z.string(),
-		z.number(),
-		z.boolean()
-	]) }),
-	z.strictObject({ in: z.array(z.union([
-		z.string(),
-		z.number(),
-		z.boolean()
-	])).min(1) }),
-	z.strictObject({ notIn: z.array(z.union([
-		z.string(),
-		z.number(),
-		z.boolean()
-	])).min(1) }),
-	z.strictObject({ isNull: z.literal(true) }),
-	z.strictObject({ isNotNull: z.literal(true) })
-]);
-const filterValueSchema = z.union([
-	z.string(),
-	z.number(),
-	z.boolean(),
-	filterOperatorsSchema
-]);
-/**
-* A raw SQL predicate fragment. Kept as a *string* (not a query-builder callback)
-* so the whole config stays JSON-serializable — it can be persisted into
-* `crm_entity_mappings` and shipped to the cloud unchanged. Embedded-only in
-* practice; not validated against the schema.
-*/
-const rawFilterSchema = z.strictObject({ $raw: z.string().min(1) });
-const columnFilterSchema = z.record(z.string(), filterValueSchema);
-/** `$raw` is a reserved key; a column literally named `$raw` is not addressable. */
-const filterSchema = z.union([rawFilterSchema, columnFilterSchema]);
-/**
-* How the link between two entities is expressed in the host schema:
-* - `fkOn: "company"` — FK lives on the company table (e.g. organizations.owner_id)
-* - `fkOn: "contact"` — FK lives on the contact table (e.g. users.organization_id)
-* - `through`         — a join table sits between them (many-to-many, role often here)
-* - `$raw`            — opaque SQL join fragment (escape hatch; not schema-validated)
-*
-* `column` and the join-table keys are `table.column` or bare `column` strings.
-*/
-const relationshipViaSchema = z.union([
-	z.strictObject({
-		fkOn: z.enum(["company", "contact"]),
-		column: z.string().min(1)
-	}),
-	z.strictObject({
-		through: z.string().min(1),
-		localKey: z.string().min(1),
-		foreignKey: z.string().min(1)
-	}),
-	z.strictObject({ $raw: z.string().min(1) })
-]);
-const relationshipSchema = z.strictObject({
-	/** Key of the related entity in the `entities` map. */
-	entity: z.string().min(1),
-	via: relationshipViaSchema
-});
-/** A named map of relationships, as stored on an entity / in the mappings row. */
-const relationshipsSchema = z.record(z.string(), relationshipSchema);
-const entitySchema = z.strictObject({
-	/** Which CRM concept this entity maps onto — a canonical concept or "custom". */
-	concept: z.union([z.enum(CRM_CONCEPTS), z.literal(CUSTOM_CONCEPT)]),
-	/** Host table (or view) this entity is derived from. */
-	source: z.string().min(1),
-	/**
-	* Distinguishes multiple entities backed by the same table (e.g. "primary"
-	* for owners, "secondary" for members). Free text; defaults to "primary".
-	*/
-	role: z.string().min(1).optional(),
-	/** Predicate that narrows `source` into this entity's rows. Omit = whole table. */
-	filter: filterSchema.optional(),
-	/** clivlyField → sourceColumn. At least one field is required. */
-	fields: z.record(z.string(), z.string()).refine((f) => Object.keys(f).length > 0, { message: "at least one field must be mapped" }),
-	/**
-	* Host-owned identity fields. Sync overwrites them; the CRM UI cannot edit
-	* them. Must be a subset of `fields` keys.
-	*/
-	readOnly: z.array(z.string()).optional(),
-	/** Named relationships to other entities in this config. */
-	relationships: z.record(z.string(), relationshipSchema).optional(),
-	/**
-	* For a "custom" entity, the crm_object_types row this materializes into.
-	* Required for custom (enforced at the API layer), unused for standard concepts.
-	*/
-	targetObjectTypeId: z.string().min(1).optional()
-});
-const entitiesConfigSchema = z.strictObject({ entities: z.record(z.string(), entitySchema).refine((e) => Object.keys(e).length > 0, { message: "at least one entity must be defined" }) });
-/** Thrown by `defineClivlyConfig({ strict: true })` on non-canonical field keys. */
-var ClivlyConfigError = class extends Error {
-	issues;
-	constructor(issues) {
-		super(`Clivly config has ${issues.length} non-canonical field mapping(s) that would write empty values at sync time:\n${issues.map((issue) => `  - ${issue.path}: ${issue.message}`).join("\n")}`);
-		this.name = "ClivlyConfigError";
-		this.issues = issues;
-	}
-};
-function nonCanonicalFieldKeys(entity) {
-	const canonical = CANONICAL_FIELDS[entity.concept];
-	if (!canonical) return [];
-	return Object.keys(entity.fields).filter((key) => !canonical.includes(key));
-}
-function nonCanonicalMessage(entity, field) {
-	const canonical = CANONICAL_FIELDS[entity.concept] ?? [];
-	return `"${field}" is not a canonical ${entity.concept} field (expected one of: ${canonical.join(", ")})`;
-}
-function canonicalFieldIssues(config) {
-	const issues = [];
-	for (const [key, entity] of Object.entries(config.entities)) for (const field of nonCanonicalFieldKeys(entity)) issues.push({
-		path: `entities.${key}.fields.${field}`,
-		message: nonCanonicalMessage(entity, field)
-	});
-	return issues;
-}
-function defaultWarn(message) {
-	console.warn(message);
-}
-/**
-* Structural helper for `clivly.config.ts`. Gives full type inference on the
-* literal you pass and eagerly parses it, so shape errors surface at config
-* load rather than at sync time.
-*
-* It also catches the silent-data-loss footgun: a non-canonical field key for a
-* materialised concept (e.g. `fullName` instead of `name` on a `contact`) has no
-* destination column, so the store would write an empty value. By default these
-* are reported via `onWarn` (a `console.warn`); pass `{ strict: true }` to throw
-* a `ClivlyConfigError` instead. Does NOT validate against the host schema — that
-* needs the discovered schema; see `validateEntitiesConfig`.
-*/
-function defineClivlyConfig(config, options) {
-	const parsed = entitiesConfigSchema.parse(config);
-	const issues = canonicalFieldIssues(parsed);
-	if (issues.length > 0) {
-		if (options?.strict) throw new ClivlyConfigError(issues);
-		const warn = options?.onWarn ?? defaultWarn;
-		for (const issue of issues) warn(`⚠ Clivly config: ${issue.message} (${issue.path}) — this field would write an empty value at sync time. Pass { strict: true } to make this throw.`);
-	}
-	return parsed;
-}
-/** Split a `table.column` / bare `column` ref into its parts. */
-function parseColumnRef(ref) {
-	const dot = ref.indexOf(".");
-	if (dot === -1) return { column: ref };
-	return {
-		table: ref.slice(0, dot),
-		column: ref.slice(dot + 1)
-	};
-}
-/** Shared lookup + error-collection state threaded through the validators. */
-var SchemaValidator = class {
-	errors = [];
-	columnsByTable = /* @__PURE__ */ new Map();
-	constructor(schema) {
-		for (const table of schema) this.columnsByTable.set(table.name, new Set(table.columns));
-	}
-	tableExists(name) {
-		return this.columnsByTable.has(name);
-	}
-	columnExists(table, column) {
-		return this.columnsByTable.get(table)?.has(column) ?? false;
-	}
-	report(path, message) {
-		this.errors.push({
-			path,
-			message
-		});
-	}
-	/** Report if `column` is absent from `table`. Returns whether it existed. */
-	requireColumn(path, table, column) {
-		if (this.columnExists(table, column)) return true;
-		this.report(path, `column "${column}" does not exist on "${table}"`);
-		return false;
-	}
-};
-function validateFields(v, base, entity) {
-	for (const [field, column] of Object.entries(entity.fields)) v.requireColumn(`${base}.fields.${field}`, entity.source, column);
-	for (const field of nonCanonicalFieldKeys(entity)) v.report(`${base}.fields.${field}`, nonCanonicalMessage(entity, field));
-}
-function validateReadOnly(v, base, entity) {
-	for (const field of entity.readOnly ?? []) if (!(field in entity.fields)) v.report(`${base}.readOnly`, `"${field}" is not one of this entity's fields`);
-}
-function validateFilter(v, base, entity) {
-	if (!entity.filter || "$raw" in entity.filter) return;
-	for (const column of Object.keys(entity.filter)) v.requireColumn(`${base}.filter.${column}`, entity.source, column);
-}
-function validateFkVia(v, relBase, via, entity, related) {
-	const { table, column } = parseColumnRef(via.column);
-	const fkTable = table ?? (via.fkOn === "contact" ? entity.source : related?.source);
-	const path = `${relBase}.via.column`;
-	if (!fkTable) {
-		v.report(path, `cannot resolve table for FK column "${via.column}"`);
-		return;
-	}
-	if (!v.tableExists(fkTable)) {
-		v.report(path, `table "${fkTable}" is not in the discovered schema`);
-		return;
-	}
-	v.requireColumn(path, fkTable, column);
-}
-function validateThroughVia(v, relBase, via) {
-	if (!v.tableExists(via.through)) {
-		v.report(`${relBase}.via.through`, `join table "${via.through}" is not in the discovered schema`);
-		return;
-	}
-	v.requireColumn(`${relBase}.via.localKey`, via.through, via.localKey);
-	v.requireColumn(`${relBase}.via.foreignKey`, via.through, via.foreignKey);
-}
-function validateRelationship(v, base, config, entity, relName, rel) {
-	const relBase = `${base}.relationships.${relName}`;
-	const related = config.entities[rel.entity];
-	if (!related) v.report(`${relBase}.entity`, `"${rel.entity}" is not a defined entity`);
-	const { via } = rel;
-	if ("fkOn" in via) validateFkVia(v, relBase, via, entity, related);
-	else if ("through" in via) validateThroughVia(v, relBase, via);
-}
-function validateEntity(v, config, key, entity) {
-	const base = `entities.${key}`;
-	if (!v.tableExists(entity.source)) {
-		v.report(`${base}.source`, `table "${entity.source}" is not in the discovered schema`);
-		return;
-	}
-	validateFields(v, base, entity);
-	validateReadOnly(v, base, entity);
-	validateFilter(v, base, entity);
-	for (const [relName, rel] of Object.entries(entity.relationships ?? {})) validateRelationship(v, base, config, entity, relName, rel);
-}
-/**
-* Validate a (structurally valid) config against the host's discovered schema:
-* source tables exist, mapped columns exist, `readOnly` ⊆ `fields`, filter
-* columns exist, and relationships point at real entities/tables/columns.
-*
-* `$raw` filters and `$raw` relationship joins are opaque and skipped. Returns
-* every error found (not just the first) so a mapping UI or CLI can show them
-* all at once.
-*/
-function validateEntitiesConfig(config, schema) {
-	const validator = new SchemaValidator(schema);
-	for (const [key, entity] of Object.entries(config.entities)) validateEntity(validator, config, key, entity);
-	return {
-		valid: validator.errors.length === 0,
-		errors: validator.errors
-	};
-}
-//#endregion
+import { a as MATERIALIZING_CONCEPTS, c as filterSchema, d as validateEntitiesConfig, i as ClivlyConfigError, l as relationshipSchema, n as CRM_CONCEPTS, o as defineClivlyConfig, r as CUSTOM_CONCEPT, s as entitiesConfigSchema, t as CANONICAL_FIELDS, u as relationshipsSchema } from "./entity-config-Tb5bbKLj.mjs";
 export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, MATERIALIZING_CONCEPTS, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/dist/entity-heuristics.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config.cjs");
+const require_entity_config = require("./entity-config-PoOGzvpN.cjs");
 const require_mapping_score = require("./mapping-score.cjs");
 //#region src/entity-heuristics.ts
 const TARGET_CONCEPTS = [
@@ -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.d.cts

@@ -1,3 +1,4 @@
+import { DiscoveredColumnMeta } from "./entity-config.cjs";
 import { Scored } from "./mapping-score.cjs";
 //#region src/entity-heuristics.d.ts
 declare const TARGET_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
@@ -6,17 +7,6 @@ declare function suggestCursorField(columnKeys: string[]): string | null;
 declare function matchesConcept(tableName: string, concept: TargetConcept): {
   exact: boolean;
 } | null;
-interface DiscoveredColumnMeta {
-  isForeignKey?: boolean;
-  isPrimaryKey?: boolean;
-  name: string;
-  nullable?: boolean;
-  references?: {
-    table: string;
-    column: string;
-  };
-  type?: string;
-}
 interface ScoredTable {
   columns: string[];
   columnsMeta?: DiscoveredColumnMeta[];
@@ -64,4 +54,4 @@ interface FieldSuggestion {
 declare function scoreFieldMap(concept: TargetConcept, table: ScoredTable): Scored<FieldSuggestion>[];
 declare function toFieldMap(scored: Scored<FieldSuggestion>[]): Record<string, string>;
 //#endregion
-export { DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };
+export { type DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };

package/dist/entity-heuristics.d.mts

@@ -1,3 +1,4 @@
+import { DiscoveredColumnMeta } from "./entity-config.mjs";
 import { Scored } from "./mapping-score.mjs";
 //#region src/entity-heuristics.d.ts
 declare const TARGET_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
@@ -6,17 +7,6 @@ declare function suggestCursorField(columnKeys: string[]): string | null;
 declare function matchesConcept(tableName: string, concept: TargetConcept): {
   exact: boolean;
 } | null;
-interface DiscoveredColumnMeta {
-  isForeignKey?: boolean;
-  isPrimaryKey?: boolean;
-  name: string;
-  nullable?: boolean;
-  references?: {
-    table: string;
-    column: string;
-  };
-  type?: string;
-}
 interface ScoredTable {
   columns: string[];
   columnsMeta?: DiscoveredColumnMeta[];
@@ -64,4 +54,4 @@ interface FieldSuggestion {
 declare function scoreFieldMap(concept: TargetConcept, table: ScoredTable): Scored<FieldSuggestion>[];
 declare function toFieldMap(scored: Scored<FieldSuggestion>[]): Record<string, string>;
 //#endregion
-export { DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };
+export { type DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };

package/dist/entity-heuristics.mjs

@@ -1,4 +1,4 @@
-import { MATERIALIZING_CONCEPTS } from "./entity-config.mjs";
+import { a as MATERIALIZING_CONCEPTS } from "./entity-config-Tb5bbKLj.mjs";
 import { CONCEPT_TIERS, FIELD_TIERS, RELATIONSHIP_TIERS, W, isAmbiguous, isNumericLike, isTextLike, isTimestampLike, tierFor } from "./mapping-score.mjs";
 //#region src/entity-heuristics.ts
 const TARGET_CONCEPTS = [
@@ -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 };