clivly 0.9.0 → 0.9.2

package/index.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { t as CANONICAL_FIELDS } from "./entity-config-D3LmzgLb.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-kUHri9yA.mjs";
 import "./mapping-score-C68uAqGB.mjs";
 import { matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./internal-entity-heuristics.mjs";
-import { t as createClivlySDK } from "./sdk-BvRD2jAp.mjs";
+import { t as createClivlySDK } from "./sdk-DXV8M_Io.mjs";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, watch, writeFileSync } from "node:fs";
@@ -477,7 +477,7 @@ async function probeModule(opts) {
 }
 //#endregion
 //#region src/workspace-graph.ts
-const WINDOWS_SEP$2 = /\\/g;
+const WINDOWS_SEP$3 = /\\/g;
 const MODULE_EXT$1 = /\.(ts|tsx|js|jsx|mjs|cjs|cts|mts)$/;
 const BRACE_GROUP = /\{([^{}]*)\}/;
 const MAX_GLOB_DEPTH = 8;
@@ -708,13 +708,13 @@ function exportsAllowSubpath(packageDir, subpath) {
 function toPackageSpecifier(pkg, absPath) {
 	const target = resolve(absPath);
 	if (resolvePackageEntry(pkg.dir) === target) return pkg.name;
-	const subpath = relative(pkg.dir, target).replace(WINDOWS_SEP$2, "/").replace(MODULE_EXT$1, "");
+	const subpath = relative(pkg.dir, target).replace(WINDOWS_SEP$3, "/").replace(MODULE_EXT$1, "");
 	if (subpath.length === 0) return pkg.name;
 	return exportsAllowSubpath(pkg.dir, subpath) ? `${pkg.name}/${subpath}` : null;
 }
 //#endregion
 //#region src/discover-schema.ts
-const WINDOWS_SEP$1 = /\\/g;
+const WINDOWS_SEP$2 = /\\/g;
 const MODULE_EXT = /\.(ts|js|mjs|cts|mts)$/;
 /**
 * Turn an absolute module path into the specifier the generated config imports
@@ -739,7 +739,7 @@ function toImportPath(schemaPath, cwd, graph) {
 		const specifier = toPackageSpecifier(owner, schemaPath);
 		if (specifier) return specifier;
 	}
-	const rel = relative(cwd, schemaPath).replace(WINDOWS_SEP$1, "/").replace(MODULE_EXT, "");
+	const rel = relative(cwd, schemaPath).replace(WINDOWS_SEP$2, "/").replace(MODULE_EXT, "");
 	return rel.startsWith(".") ? rel : `./${rel}`;
 }
 function isDirectory(path) {
@@ -1153,6 +1153,46 @@ async function installPackages(options) {
 	}
 }
 //#endregion
+//#region src/install-needed.ts
+/** Exact `name@version` only. Anything else is left for the package manager. */
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+/**
+* Split `name@version`, tolerating scoped names where the leading `@` is part
+* of the name rather than a separator. Returns a null version for a bare name.
+*/
+function parseSpec(spec) {
+	const at = spec.lastIndexOf("@");
+	if (at <= 0) return {
+		name: spec,
+		version: null
+	};
+	return {
+		name: spec.slice(0, at),
+		version: spec.slice(at + 1)
+	};
+}
+/**
+* Which of `packages` still need installing.
+*
+* Deliberately conservative — a spec is only dropped when it is provably
+* satisfied. Tarball paths, `file:` specs and semver ranges are always kept:
+* the first two name no version to compare, and resolving the third needs a
+* semver implementation the CLI does not ship. Erring toward installing costs
+* a redundant install; erring the other way silently skips one the developer
+* asked for.
+*/
+function packagesNeedingInstall(packages, installedVersion) {
+	return packages.filter((spec) => {
+		if (spec.startsWith(".") || spec.startsWith("/") || spec.includes(":") || spec.includes("/") && !spec.startsWith("@")) return true;
+		const { name, version } = parseSpec(spec);
+		const present = installedVersion(name);
+		if (present === null) return true;
+		if (version === null) return false;
+		if (!EXACT_VERSION.test(version)) return true;
+		return present !== version;
+	});
+}
+//#endregion
 //#region src/is-entry.ts
 function isEntrypoint(argv1, moduleUrl, realpath = realpathSync) {
 	if (!argv1) return false;
@@ -1502,8 +1542,10 @@ function planInit(schema, overrides = {}) {
 	if (built && !contact) todos.push(`"${built.tableName}" was chosen as the contact entity but none of its columns could be mapped to name/email.`);
 	let company = null;
 	if (companyTable) {
-		const candidate = buildEntity(companyTable, "company", todos);
+		const candidateTodos = [];
+		const candidate = buildEntity(companyTable, "company", candidateTodos);
 		if (hasMappedFields(candidate)) {
+			todos.push(...candidateTodos);
 			company = candidate;
 			if (matchesConcept(companyTable.tableName, "contact")) todos.push(`"${companyTable.tableName}" matches both contact and company naming — assigned to company. Swap it to your contact entity if that's wrong.`);
 		} else todos.push(`"${companyTable.tableName}" looked like a company but no fields could be mapped — left it out. Add it to \`entities\` once you know which columns map to name/domain.`);
@@ -1612,6 +1654,106 @@ function rankContactCandidates(tables) {
 	}));
 }
 //#endregion
+//#region src/config-import.ts
+const WINDOWS_SEP$1 = /\\/g;
+function configImport(generatedFilePath) {
+	const rel = relative(dirname(generatedFilePath), "clivly.config").replace(WINDOWS_SEP$1, "/");
+	return rel.startsWith(".") ? rel : `./${rel}`;
+}
+//#endregion
+//#region src/boot-hook.ts
+const BOOT_HOOK_PATHS = {
+	nextjs: "instrumentation.ts",
+	nuxt: "server/plugins/clivly.ts",
+	sveltekit: "src/hooks.server.ts",
+	"tanstack-start": null,
+	remix: null,
+	unknown: null
+};
+function bootHookPath(framework, layout) {
+	const path = BOOT_HOOK_PATHS[framework];
+	if (path === null) return null;
+	if (framework === "nextjs" && layout === "src/app") return `src/${path}`;
+	return path;
+}
+const FAILURE_NOTE = "Clivly never blocks your app from starting: a failed check-in is logged and retried on the next tick.";
+function nextjsHook(importPath) {
+	return `// Clivly boot hook. Next.js calls register() once when the server starts.
+// ${FAILURE_NOTE}
+export async function register() {
+	// The keep-alive loop is a setInterval, which does not survive on the edge
+	// runtime — it would stop ticking after the first response and the dashboard
+	// would show an app that checked in once and then went stale forever.
+	if (process.env.NEXT_RUNTIME !== "nodejs") {
+		return;
+	}
+	try {
+		const { default: clivly } = await import("${importPath}");
+		await clivly.start();
+	} catch (error) {
+		console.warn("[clivly] could not check in:", error);
+	}
+}
+`;
+}
+function nuxtHook(importPath) {
+	return `import clivly from "${importPath}";
+
+// Clivly boot hook. Nitro runs this once when the server starts.
+// ${FAILURE_NOTE}
+export default defineNitroPlugin(() => {
+	clivly.start().catch((error: unknown) => {
+		console.warn("[clivly] could not check in:", error);
+	});
+});
+`;
+}
+function sveltekitHook(importPath) {
+	return `import clivly from "${importPath}";
+
+// Clivly boot hook. This module is evaluated once when the server starts.
+// ${FAILURE_NOTE}
+clivly.start().catch((error: unknown) => {
+	console.warn("[clivly] could not check in:", error);
+});
+`;
+}
+const RENDERERS = {
+	nextjs: nextjsHook,
+	nuxt: nuxtHook,
+	sveltekit: sveltekitHook
+};
+function renderBootHook(framework, layout) {
+	const path = bootHookPath(framework, layout);
+	const render = RENDERERS[framework];
+	if (!(path && render)) throw new Error(`No standalone boot hook for framework: ${framework}`);
+	return render(configImport(path));
+}
+const NEXT_INSTRUMENTATION_STABLE_MAJOR = 15;
+const LEADING_MAJOR = /(\d+)/;
+/** Does this Next.js version range need the experimental flag to run our hook? */
+function nextNeedsInstrumentationFlag(versionRange) {
+	if (!versionRange) return false;
+	const major = LEADING_MAJOR.exec(versionRange);
+	if (!major?.[1]) return false;
+	return Number(major[1]) < NEXT_INSTRUMENTATION_STABLE_MAJOR;
+}
+const NEXT_INSTRUMENTATION_FLAG_STEP = `Your Next.js version reads instrumentation.ts only when it is switched on. Add this to next.config, or Clivly will never be told your app started:
+      experimental: { instrumentationHook: true }`;
+const REMIX_BOOT_STEP = `Start Clivly when your app boots. Add this near the top of app/entry.server.tsx:
+      import clivly from "./clivly.config";
+      clivly.start().catch((error) => console.warn("[clivly] could not check in:", error));`;
+/** The boot hook as a scaffold entry, or null when this framework is patched. */
+function planBootHook(framework, layout) {
+	const path = bootHookPath(framework, layout);
+	if (!path) return null;
+	return {
+		path,
+		description: "Clivly boot hook — starts check-in when your app runs",
+		owned: true
+	};
+}
+//#endregion
 //#region src/render-config.ts
 const CLIVLY_ENV_KEYS = [
 	{
@@ -1922,10 +2064,6 @@ function routePath(framework, kind, layout = "app") {
 }
 const WINDOWS_SEP = /\\/g;
 const LEADING_DOT_SLASH = /^\.\//;
-function configImport(routeFilePath) {
-	const rel = relative(dirname(routeFilePath), "clivly.config").replace(WINDOWS_SEP, "/");
-	return rel.startsWith(".") ? rel : `./${rel}`;
-}
 function hostImportPath(routeFilePath, appRelative, paths) {
 	const fromRoot = appRelative.replace(LEADING_DOT_SLASH, "");
 	const alias = aliasFor({
@@ -2013,6 +2151,7 @@ const COMMON_FILES = [{
 function planScaffold(framework, layout = "app") {
 	const paths = ROUTE_PATHS[framework];
 	if (!paths) return [];
+	const boot = planBootHook(framework, layout);
 	return [
 		{
 			path: applyLayout(framework, paths.tick, layout),
@@ -2024,6 +2163,7 @@ function planScaffold(framework, layout = "app") {
 			description: "Clivly auth-verify route (createAuthVerifyHandler) — finish resolveUser",
 			owned: true
 		},
+		...boot ? [boot] : [],
 		...COMMON_FILES
 	];
 }
@@ -2037,6 +2177,45 @@ function planWidgetScaffold(framework, layout = "app") {
 	}];
 }
 //#endregion
+//#region src/vite-boot-patch.ts
+/** Config filenames to look for, in precedence order. */
+const VITE_CONFIG_CANDIDATES = [
+	"vite.config.ts",
+	"vite.config.mts",
+	"vite.config.js",
+	"vite.config.mjs"
+];
+const PLUGIN_IMPORT = "import { clivlyVite } from \"clivly/vite\";";
+const CONFIG_IMPORT = "import clivly from \"./clivly.config\";";
+const PLUGIN_CALL = "clivlyVite(clivly)";
+const PLUGINS_ARRAY = /(^|[\s{,])plugins\s*:\s*\[/g;
+/** The last import line's end offset, so new imports land after the existing ones. */
+const IMPORT_LINE = /^\s*import\s.+?from\s+["'].+?["'];?\s*$/gm;
+function insertImports(source) {
+	const last = [...source.matchAll(IMPORT_LINE)].at(-1);
+	const block = `${PLUGIN_IMPORT}\n${CONFIG_IMPORT}`;
+	if (!last) return `${block}\n\n${source}`;
+	const at = (last.index ?? 0) + last[0].length;
+	return `${source.slice(0, at)}\n${block}${source.slice(at)}`;
+}
+/**
+* Add the Clivly Vite plugin to an existing config.
+*
+* Returns the patched source, or `null` when the config is already patched or
+* is not a shape we can edit safely.
+*/
+function patchViteConfig(source) {
+	if (source.includes(PLUGIN_CALL)) return null;
+	const matches = [...source.matchAll(PLUGINS_ARRAY)];
+	if (matches.length !== 1) return null;
+	const match = matches[0];
+	if (!match) return null;
+	const openBracketEnd = (match.index ?? 0) + match[0].length;
+	const rest = source.slice(openBracketEnd);
+	const separator = rest.startsWith("\n") ? "" : " ";
+	return insertImports(`${source.slice(0, openBracketEnd)}${PLUGIN_CALL},${separator}${rest}`);
+}
+//#endregion
 //#region src/plan-mutations.ts
 function fileAction(existing, next, force) {
 	if (existing === null) return "create";
@@ -2048,8 +2227,10 @@ function hasKey(content, key) {
 }
 function planFiles(args) {
 	const mutations = [];
+	const bootPath = bootHookPath(args.framework, args.layout);
 	const render = (path) => {
 		if (path === "clivly.config.ts") return renderInitConfig(args.plan);
+		if (bootPath !== null && path === bootPath) return renderBootHook(args.framework, args.layout);
 		const kind = path.includes("verify") ? "verify" : "tick";
 		return renderRouteFile(args.framework, kind, args.authWiring, args.layout, parseTsconfig(args.readFile(join(args.cwd, "tsconfig.json")) ?? "")?.paths);
 	};
@@ -2077,10 +2258,67 @@ function planEnv(args) {
 		action: envAction(addedKeys.length, existing.length)
 	};
 }
+function declaredNextVersion(args) {
+	const raw = args.readFile(join(args.cwd, "package.json"));
+	if (!raw) return;
+	let pkg = {};
+	try {
+		pkg = JSON.parse(raw);
+	} catch {
+		pkg = {};
+	}
+	return pkg.dependencies?.next ?? pkg.devDependencies?.next;
+}
+function planBootPatch(args) {
+	if (bootHookPath(args.framework, args.layout) !== null) return {
+		file: null,
+		manual: args.framework === "nextjs" && nextNeedsInstrumentationFlag(declaredNextVersion(args)) ? NEXT_INSTRUMENTATION_FLAG_STEP : null
+	};
+	if (args.framework === "remix") return {
+		file: null,
+		manual: REMIX_BOOT_STEP
+	};
+	if (args.framework !== "tanstack-start") return {
+		file: null,
+		manual: null
+	};
+	for (const candidate of VITE_CONFIG_CANDIDATES) {
+		const existing = args.readFile(join(args.cwd, candidate));
+		if (existing === null) continue;
+		const patched = patchViteConfig(existing);
+		if (patched === null) return existing.includes("clivlyVite(clivly)") ? {
+			file: {
+				path: candidate,
+				contents: existing,
+				action: "unchanged"
+			},
+			manual: null
+		} : {
+			file: null,
+			manual: `Add the Clivly plugin to ${candidate} so your app checks in when it runs:\n      import { clivlyVite } from "clivly/vite";\n      import clivly from "./clivly.config";\n      // then, inside defineConfig: plugins: [clivlyVite(clivly), …]`
+		};
+		return {
+			file: {
+				path: candidate,
+				contents: patched,
+				action: "patch"
+			},
+			manual: null
+		};
+	}
+	return {
+		file: null,
+		manual: null
+	};
+}
 function planMutations(args) {
+	const files = planFiles(args);
+	const boot = planBootPatch(args);
+	if (boot.file) files.push(boot.file);
 	return {
-		files: planFiles(args),
-		env: planEnv(args)
+		files,
+		env: planEnv(args),
+		manualSteps: boot.manual ? [boot.manual] : []
 	};
 }
 function planWidgetMutations(args) {
@@ -2094,6 +2332,49 @@ function planWidgetMutations(args) {
 	});
 }
 //#endregion
+//#region src/quiet-host-output.ts
+/**
+* Run `fn` with the process's stdout/stderr captured. Always restores the
+* original writers, including when `fn` throws — a leaked patch would silence
+* the whole CLI for the rest of the run.
+*/
+async function captureHostOutput(fn) {
+	const originals = {
+		stdout: process.stdout.write,
+		stderr: process.stderr.write
+	};
+	let output = "";
+	const capture = (chunk, encoding, callback) => {
+		output += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+		const done = typeof encoding === "function" ? encoding : callback;
+		if (typeof done === "function") done();
+		return true;
+	};
+	process.stdout.write = capture;
+	process.stderr.write = capture;
+	try {
+		return {
+			result: await fn(),
+			output
+		};
+	} catch (error) {
+		if (output.trim().length > 0 && error instanceof Error) error.message = `${error.message}\n${output.trim()}`;
+		throw error;
+	} finally {
+		process.stdout.write = originals.stdout;
+		process.stderr.write = originals.stderr;
+	}
+}
+/**
+* Run `fn` quietly, discarding whatever the host printed on success. On failure
+* the captured output is attached to the error's message, so the host's own
+* explanation is not lost.
+*/
+async function quietly(fn) {
+	const { result } = await captureHostOutput(fn);
+	return result;
+}
+//#endregion
 //#region src/probe-auth.ts
 const AUTH_MODULE_PATHS = [
 	"auth",
@@ -2116,15 +2397,32 @@ function defaultLoader(cwd) {
 	return (specifier) => jiti.import(specifier);
 }
 function probeAuthInstance(cwd, load) {
-	return probeModule({
+	return quietly(() => probeModule({
 		candidates: authInstanceCandidates(cwd),
 		cwd,
 		load: load ?? defaultLoader(cwd),
 		match: isBetterAuthInstance
-	});
+	}));
 }
 //#endregion
 //#region src/push-schema.ts
+/**
+* "1 mapping" / "3 mappings" — a count nobody has to decode. The plural is
+* explicit because appending "s" turns "entity" into "entitys".
+*/
+function countOf(n, singular, plural = `${singular}s`) {
+	return `${n} ${n === 1 ? singular : plural}`;
+}
+function reportSchema(report, out) {
+	const createdObjects = report.objectTypes.filter((o) => o.created);
+	if (createdObjects.length > 0) out(`  ✅ Created ${countOf(createdObjects.length, "custom object")}: ${createdObjects.map((o) => o.slug).join(", ")}.\n`);
+	else if (report.objectTypes.length > 0) out(`  ✅ ${countOf(report.objectTypes.length, "custom object")} already present.\n`);
+	const created = report.mappings.filter((m) => m.created);
+	const updated = report.mappings.filter((m) => m.updated);
+	if (created.length > 0) out(`  ✅ Mapped ${countOf(created.length, "entity", "entities")}: ${created.map((m) => m.entityKey).join(", ")}.\n`);
+	if (updated.length > 0) out(`  ✅ Updated ${countOf(updated.length, "mapping")}: ${updated.map((m) => m.entityKey).join(", ")}.\n`);
+	if (report.mappings.length > 0 && created.length === 0 && updated.length === 0) out(`  ✅ ${countOf(report.mappings.length, "mapping")} already match your config.\n`);
+}
 async function runPushSchema(options) {
 	const out = options.out ?? ((line) => process.stdout.write(line));
 	const path = resolveConfigPath(options.cwd, options.configPath);
@@ -2152,6 +2450,29 @@ async function runPushSchema(options) {
 	}
 	out("  ✅ Schema reported to Clivly.\n");
 	out("     Integration liveness and trigger URL were refreshed too.\n");
+	if (sdk.ensureSchema) {
+		let report;
+		try {
+			report = await sdk.ensureSchema();
+		} catch (error) {
+			out(`  ❌ Clivly refused your schema — ${error.message}\n`);
+			return 1;
+		}
+		if (report === null) {
+			out("  ⚠️  Could not declare the objects and mappings in your config.\n");
+			out("     Run `clivly status`, then `clivly push-schema` again.\n");
+		} else reportSchema(report, out);
+		out("     Open Integrations → Mapping to review them.\n");
+		return 0;
+	}
+	const ensured = await sdk.ensureCustomObjects?.();
+	if (ensured === null) {
+		out("  ⚠️  Could not create the custom objects your config declares.\n");
+		out("     Run `clivly status`, then `clivly push-schema` again.\n");
+	} else if (ensured && ensured.length > 0) {
+		const created = ensured.filter((o) => o.created);
+		out(created.length > 0 ? `  ✅ Created ${created.length} custom object(s): ${created.map((o) => o.slug).join(", ")}.\n` : `  ✅ ${ensured.length} custom object(s) already present.\n`);
+	}
 	out("     Open Integrations → Mapping to map your tables.\n");
 	return 0;
 }
@@ -2732,8 +3053,19 @@ const defaultConnect = (apiKey, apiUrl) => createClivlySDK({
 	apiUrl,
 	retry: { maxAttempts: 1 }
 }).ping();
+/**
+* Exported for tests only — the rule it encodes is the point.
+*
+* A skipped check was never evaluated (nothing to check yet), which is not the
+* same as a warning: a warning is a working setup carrying real risk. Marking
+* "not applicable" with ⚠️ put a warning on every fresh install for something
+* the developer had not done wrong, which is exactly how people are trained to
+* stop reading warnings — the same reasoning `status-stages.ts` gives for
+* refusing to turn a stage red on a setup that works.
+*/
 function subMark(sub) {
-	if (sub.skipped || sub.warn) return "⚠️ ";
+	if (sub.skipped) return "⏭️ ";
+	if (sub.warn) return "⚠️ ";
 	return sub.ok ? "✅" : "❌";
 }
 function renderStage(result, verbose, out) {
@@ -2896,6 +3228,14 @@ function runAdd(argv, cwd, deps = defaultAddDeps) {
 	}
 	return 0;
 }
+function readInstalledVersion(cwd, name) {
+	try {
+		const manifest = join(cwd, "node_modules", ...name.split("/"), "package.json");
+		return JSON.parse(readFileSync(manifest, "utf8")).version ?? null;
+	} catch {
+		return null;
+	}
+}
 function readOwnVersion() {
 	const req = createRequire(import.meta.url);
 	for (const rel of ["./package.json", "../package.json"]) try {
@@ -2993,6 +3333,7 @@ function resolveInitDeps(options) {
 		install: options.installPackages ?? installPackages,
 		probeAuth: options.probeAuthInstance ?? probeAuthInstance,
 		readEnv: options.readEnv ?? defaultReadEnv,
+		readInstalledVersion: options.readInstalledVersion ?? readInstalledVersion,
 		readOwnVersion: options.readOwnVersion ?? readOwnVersion,
 		writeEnv: options.writeEnv ?? defaultWriteEnv,
 		isInteractive: options.yes ? () => false : options.isInteractive ?? defaultIsInteractive,
@@ -3022,8 +3363,8 @@ async function acquireSchema(options, deps) {
 	deps.framework = framework;
 	const layout = deps.resolveAppLayout(options.cwd, deps.fileExists);
 	deps.layout = layout;
-	deps.authWiring = renderAuthWiring(auth, auth === "better-auth" ? authInstanceFromFlag(options.authImportFlag) ?? await deps.probeAuth(options.cwd) : null);
 	out("\nClivly init\n");
+	deps.authWiring = renderAuthWiring(auth, auth === "better-auth" ? authInstanceFromFlag(options.authImportFlag) ?? await deps.probeAuth(options.cwd) : null);
 	out(`  Framework: ${FRAMEWORK_LABELS[framework]}\n`);
 	out(`  ORM:       ${orm}\n`);
 	out(`  Auth:      ${auth}${deps.authWiring.complete ? " (wired)" : ""}\n`);
@@ -3092,12 +3433,12 @@ function applyMutations(options, deps, mutations) {
 		deps.writeConfig(join(options.cwd, file.path), file.contents);
 		deps.out(`  ✓ ${file.path}\n`);
 	}
-	if (mutations.env.action === "skip") {
-		deps.out("  • .env already has every CLIVLY_* key — skipped\n");
-		return;
+	if (mutations.env.action === "skip") deps.out("  • .env already has every CLIVLY_* key — skipped\n");
+	else {
+		deps.writeEnv(options.cwd, mutations.env.contents);
+		deps.out("  ✓ .env placeholders\n");
 	}
-	deps.writeEnv(options.cwd, mutations.env.contents);
-	deps.out("  ✓ .env placeholders\n");
+	for (const step of mutations.manualSteps) deps.out(`\n  ! ${step}\n`);
 }
 const DIFF_CONTEXT_LIMIT = 40;
 function renderDiff(existing, next) {
@@ -3117,6 +3458,7 @@ function previewMutations(deps, mutations, options) {
 			conflict: " (differs — --diff to see, --force to overwrite)",
 			create: ` (${lines} lines)`,
 			overwrite: ` (${lines} lines)`,
+			patch: " (your file, plus the Clivly plugin)",
 			unchanged: " (already up to date)"
 		}[file.action];
 		out(`  ${file.action.padEnd(9)} ${file.path}${suffix}\n`);
@@ -3174,13 +3516,17 @@ async function scaffold(options, deps, plan) {
 		});
 		return 0;
 	}
-	const result = await deps.install({
-		cwd: options.cwd,
-		pm,
-		packages
-	});
-	if (result.ok) out(`Installed clivly (${pm})\n`);
-	else out(`Could not install automatically — run:\n  ${result.command}\n`);
+	const missing = packagesNeedingInstall(packages, (name) => deps.readInstalledVersion(options.cwd, name));
+	if (missing.length === 0) out(`Already installed (${pm}) — nothing to fetch\n`);
+	else {
+		const result = await deps.install({
+			cwd: options.cwd,
+			pm,
+			packages: missing
+		});
+		if (result.ok) out(`Installed clivly (${pm})\n`);
+		else out(`Could not install automatically — run:\n  ${result.command}\n`);
+	}
 	applyMutations(options, deps, mutations);
 	let loginRan = false;
 	if (credentialsMissing(mutations.env.contents)) {

package/{internal-MBkNo3bw.d.mts → internal-CDY8g9Ic.d.mts}

@@ -1,5 +1,4 @@
-import { d as DiscoveredSchemaTable, s as ConfigValidationError, u as DiscoveredColumnMeta } from "./entity-config-C4Yf_fPj.mjs";
-import { a as ProjectionIdentity, i as ProjectionFieldBinding, o as ProjectionJoin, s as ProjectionMapping } from "./mappings-config-BpcR8bBo.mjs";
+import { M as ProjectionIdentity, N as ProjectionJoin, P as ProjectionMapping, j as ProjectionFieldBinding, l as ConfigValidationError, m as DiscoveredSchemaTable, p as DiscoveredColumnMeta } from "./entity-config-B2RA53nw.mjs";
 //#region ../core/src/projection-cardinality.d.ts
 declare function joinFansOut(join: ProjectionJoin, joinTable: DiscoveredSchemaTable): boolean;
 /** Every join in the projection that can multiply rows. */

package/{internal-BARjyN4n.cjs → internal-CwnEG6Wl.cjs}

@@ -1,5 +1,5 @@
 const require_projection = require("./projection-C5244vGa.cjs");
-const require_entity_config = require("./entity-config-CsLl-ftC.cjs");
+const require_entity_config = require("./entity-config-DtBsl2MQ.cjs");
 //#region ../core/src/projection-draft.ts
 function emptyProjectionDraft(baseTable) {
 	return {

package/{internal-B8ydhsKd.d.cts → internal-Da_dlcQ_.d.cts}

@@ -1,5 +1,4 @@
-import { d as DiscoveredSchemaTable, s as ConfigValidationError, u as DiscoveredColumnMeta } from "./entity-config-C4Yf_fPj.cjs";
-import { a as ProjectionIdentity, i as ProjectionFieldBinding, o as ProjectionJoin, s as ProjectionMapping } from "./mappings-config-xsLMn3I-.cjs";
+import { M as ProjectionIdentity, N as ProjectionJoin, P as ProjectionMapping, j as ProjectionFieldBinding, l as ConfigValidationError, m as DiscoveredSchemaTable, p as DiscoveredColumnMeta } from "./entity-config-B2RA53nw.cjs";
 //#region ../core/src/projection-cardinality.d.ts
 declare function joinFansOut(join: ProjectionJoin, joinTable: DiscoveredSchemaTable): boolean;
 /** Every join in the projection that can multiply rows. */

package/{internal-DMySVbM0.mjs → internal-Df-PtOH_.mjs}

@@ -1,5 +1,5 @@
 import { n as PROJECTION_KEY_PATTERN, t as BASE_REF } from "./projection-D7xmQP4S.mjs";
-import { f as validateProjection, p as fanOutJoins } from "./entity-config-D3LmzgLb.mjs";
+import { h as fanOutJoins, m as validateProjection } from "./entity-config-kUHri9yA.mjs";
 //#region ../core/src/projection-draft.ts
 function emptyProjectionDraft(baseTable) {
 	return {

package/internal-drizzle.d.cts

@@ -1,2 +1,2 @@
-import { n as buildUniqueConstraints, r as discoverFromDrizzle, t as buildColumnsMeta } from "./drizzle-BhN5M9zt.cjs";
+import { n as buildUniqueConstraints, r as discoverFromDrizzle, t as buildColumnsMeta } from "./drizzle-DEtRrqtc.cjs";
 export { buildColumnsMeta, buildUniqueConstraints, discoverFromDrizzle };

package/internal-drizzle.d.mts

@@ -1,2 +1,2 @@
-import { n as buildUniqueConstraints, r as discoverFromDrizzle, t as buildColumnsMeta } from "./drizzle-kBULBAOa.mjs";
+import { n as buildUniqueConstraints, r as discoverFromDrizzle, t as buildColumnsMeta } from "./drizzle-CiK8MMEZ.mjs";
 export { buildColumnsMeta, buildUniqueConstraints, discoverFromDrizzle };

package/internal-entity-config.cjs

@@ -1,13 +1,15 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-CsLl-ftC.cjs");
+const require_entity_config = require("./entity-config-DtBsl2MQ.cjs");
 exports.CANONICAL_FIELDS = require_entity_config.CANONICAL_FIELDS;
 exports.CRM_CONCEPTS = require_entity_config.CRM_CONCEPTS;
 exports.CUSTOM_CONCEPT = require_entity_config.CUSTOM_CONCEPT;
 exports.ClivlyConfigError = require_entity_config.ClivlyConfigError;
 exports.MATERIALIZING_CONCEPTS = require_entity_config.MATERIALIZING_CONCEPTS;
+exports.customObjectDeclarations = require_entity_config.customObjectDeclarations;
 exports.defineClivlyConfig = require_entity_config.defineClivlyConfig;
 exports.entitiesConfigSchema = require_entity_config.entitiesConfigSchema;
 exports.filterSchema = require_entity_config.filterSchema;
+exports.projectionFields = require_entity_config.projectionFields;
 exports.relationshipSchema = require_entity_config.relationshipSchema;
 exports.relationshipsSchema = require_entity_config.relationshipsSchema;
 exports.validateEntitiesConfig = require_entity_config.validateEntitiesConfig;

package/internal-entity-config.d.cts

@@ -1,2 +1,2 @@
-import { C as relationshipsSchema, S as relationshipSchema, _ as RelationshipVia, a as ClivlyEntitiesConfig, b as entitiesConfigSchema, c as ConfigValidationResult, d as DiscoveredSchemaTable, f as FilterExpr, g as RelationshipSpec, h as MaterializingConcept, i as ClivlyConfigError, l as CrmConcept, m as MATERIALIZING_CONCEPTS, n as CRM_CONCEPTS, o as ClivlyEntityConfig, p as FilterValue, r as CUSTOM_CONCEPT, s as ConfigValidationError, t as CANONICAL_FIELDS, u as DiscoveredColumnMeta, v as RelationshipsMap, w as validateEntitiesConfig, x as filterSchema, y as defineClivlyConfig } from "./entity-config-C4Yf_fPj.cjs";
-export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredColumnMeta, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };
+import { C as defineClivlyConfig, D as relationshipSchema, E as projectionFields, O as relationshipsSchema, S as customObjectDeclarations, T as filterSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipVia, c as ClivlyEntityConfigInput, d as CrmConcept, f as CustomObjectDeclaration, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, k as validateEntitiesConfig, l as ConfigValidationError, m as DiscoveredSchemaTable, n as CRM_CONCEPTS, o as ClivlyEntitiesConfigInput, p as DiscoveredColumnMeta, r as CUSTOM_CONCEPT, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as MaterializingConcept, w as entitiesConfigSchema, x as RelationshipsMap, y as RelationshipSpec } from "./entity-config-B2RA53nw.cjs";
+export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntitiesConfigInput, ClivlyEntityConfig, ClivlyEntityConfigInput, ConfigValidationError, ConfigValidationResult, CrmConcept, CustomObjectDeclaration, DiscoveredColumnMeta, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, customObjectDeclarations, defineClivlyConfig, entitiesConfigSchema, filterSchema, projectionFields, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/internal-entity-config.d.mts

@@ -1,2 +1,2 @@
-import { C as relationshipsSchema, S as relationshipSchema, _ as RelationshipVia, a as ClivlyEntitiesConfig, b as entitiesConfigSchema, c as ConfigValidationResult, d as DiscoveredSchemaTable, f as FilterExpr, g as RelationshipSpec, h as MaterializingConcept, i as ClivlyConfigError, l as CrmConcept, m as MATERIALIZING_CONCEPTS, n as CRM_CONCEPTS, o as ClivlyEntityConfig, p as FilterValue, r as CUSTOM_CONCEPT, s as ConfigValidationError, t as CANONICAL_FIELDS, u as DiscoveredColumnMeta, v as RelationshipsMap, w as validateEntitiesConfig, x as filterSchema, y as defineClivlyConfig } from "./entity-config-C4Yf_fPj.mjs";
-export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredColumnMeta, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };
+import { C as defineClivlyConfig, D as relationshipSchema, E as projectionFields, O as relationshipsSchema, S as customObjectDeclarations, T as filterSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipVia, c as ClivlyEntityConfigInput, d as CrmConcept, f as CustomObjectDeclaration, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, k as validateEntitiesConfig, l as ConfigValidationError, m as DiscoveredSchemaTable, n as CRM_CONCEPTS, o as ClivlyEntitiesConfigInput, p as DiscoveredColumnMeta, r as CUSTOM_CONCEPT, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as MaterializingConcept, w as entitiesConfigSchema, x as RelationshipsMap, y as RelationshipSpec } from "./entity-config-B2RA53nw.mjs";
+export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntitiesConfigInput, ClivlyEntityConfig, ClivlyEntityConfigInput, ConfigValidationError, ConfigValidationResult, CrmConcept, CustomObjectDeclaration, DiscoveredColumnMeta, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, customObjectDeclarations, defineClivlyConfig, entitiesConfigSchema, filterSchema, projectionFields, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/internal-entity-config.mjs

@@ -1,2 +1,2 @@
-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-D3LmzgLb.mjs";
-export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, MATERIALIZING_CONCEPTS, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };
+import { a as MATERIALIZING_CONCEPTS, c as entitiesConfigSchema, d as relationshipSchema, f as relationshipsSchema, i as ClivlyConfigError, l as filterSchema, n as CRM_CONCEPTS, o as customObjectDeclarations, p as validateEntitiesConfig, r as CUSTOM_CONCEPT, s as defineClivlyConfig, t as CANONICAL_FIELDS, u as projectionFields } from "./entity-config-kUHri9yA.mjs";
+export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, MATERIALIZING_CONCEPTS, customObjectDeclarations, defineClivlyConfig, entitiesConfigSchema, filterSchema, projectionFields, relationshipSchema, relationshipsSchema, validateEntitiesConfig };