clivly 0.9.0 → 0.9.2

package/index.cjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 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");
 require("./mapping-score-CaB3F4Uu.cjs");
 const require_internal_entity_heuristics = require("./internal-entity-heuristics.cjs");
-const require_sdk = require("./sdk-Bj-ZDf4u.cjs");
+const require_sdk = require("./sdk-D4Wp_uxb.cjs");
 let node_child_process = require("node:child_process");
 let node_fs = require("node:fs");
 let node_module = require("node:module");
@@ -478,7 +478,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;
@@ -709,13 +709,13 @@ function exportsAllowSubpath(packageDir, subpath) {
 function toPackageSpecifier(pkg, absPath) {
 	const target = (0, node_path.resolve)(absPath);
 	if (resolvePackageEntry(pkg.dir) === target) return pkg.name;
-	const subpath = (0, node_path.relative)(pkg.dir, target).replace(WINDOWS_SEP$2, "/").replace(MODULE_EXT$1, "");
+	const subpath = (0, node_path.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
@@ -740,7 +740,7 @@ function toImportPath(schemaPath, cwd, graph) {
 		const specifier = toPackageSpecifier(owner, schemaPath);
 		if (specifier) return specifier;
 	}
-	const rel = (0, node_path.relative)(cwd, schemaPath).replace(WINDOWS_SEP$1, "/").replace(MODULE_EXT, "");
+	const rel = (0, node_path.relative)(cwd, schemaPath).replace(WINDOWS_SEP$2, "/").replace(MODULE_EXT, "");
 	return rel.startsWith(".") ? rel : `./${rel}`;
 }
 function isDirectory(path) {
@@ -1154,6 +1154,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 = node_fs.realpathSync) {
 	if (!argv1) return false;
@@ -1503,8 +1543,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 (require_internal_entity_heuristics.matchesConcept(companyTable.tableName, "contact")) todos.push(`"${companyTable.tableName}" matches both contact and company naming — assigned to company. Swap it to your contact entity if that's wrong.`);
 		} else todos.push(`"${companyTable.tableName}" looked like a company but no fields could be mapped — left it out. Add it to \`entities\` once you know which columns map to name/domain.`);
@@ -1613,6 +1655,106 @@ function rankContactCandidates(tables) {
 	}));
 }
 //#endregion
+//#region src/config-import.ts
+const WINDOWS_SEP$1 = /\\/g;
+function configImport(generatedFilePath) {
+	const rel = (0, node_path.relative)((0, node_path.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 = [
 	{
@@ -1923,10 +2065,6 @@ function routePath(framework, kind, layout = "app") {
 }
 const WINDOWS_SEP = /\\/g;
 const LEADING_DOT_SLASH = /^\.\//;
-function configImport(routeFilePath) {
-	const rel = (0, node_path.relative)((0, node_path.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({
@@ -2014,6 +2152,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),
@@ -2025,6 +2164,7 @@ function planScaffold(framework, layout = "app") {
 			description: "Clivly auth-verify route (createAuthVerifyHandler) — finish resolveUser",
 			owned: true
 		},
+		...boot ? [boot] : [],
 		...COMMON_FILES
 	];
 }
@@ -2038,6 +2178,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";
@@ -2049,8 +2228,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((0, node_path.join)(args.cwd, "tsconfig.json")) ?? "")?.paths);
 	};
@@ -2078,10 +2259,67 @@ function planEnv(args) {
 		action: envAction(addedKeys.length, existing.length)
 	};
 }
+function declaredNextVersion(args) {
+	const raw = args.readFile((0, node_path.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((0, node_path.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) {
@@ -2095,6 +2333,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",
@@ -2117,15 +2398,32 @@ function defaultLoader(cwd) {
 	return (specifier) => jiti$1.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);
@@ -2153,6 +2451,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;
 }
@@ -2733,8 +3054,19 @@ const defaultConnect = (apiKey, apiUrl) => require_sdk.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) {
@@ -2897,6 +3229,14 @@ function runAdd(argv, cwd, deps = defaultAddDeps) {
 	}
 	return 0;
 }
+function readInstalledVersion(cwd, name) {
+	try {
+		const manifest = (0, node_path.join)(cwd, "node_modules", ...name.split("/"), "package.json");
+		return JSON.parse((0, node_fs.readFileSync)(manifest, "utf8")).version ?? null;
+	} catch {
+		return null;
+	}
+}
 function readOwnVersion() {
 	const req = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
 	for (const rel of ["./package.json", "../package.json"]) try {
@@ -2994,6 +3334,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,
@@ -3023,8 +3364,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`);
@@ -3093,12 +3434,12 @@ function applyMutations(options, deps, mutations) {
 		deps.writeConfig((0, node_path.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) {
@@ -3118,6 +3459,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`);
@@ -3175,13 +3517,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/index.d.cts

@@ -98,6 +98,7 @@ interface RunInitOptions {
   readDeps?: (cwd: string) => Record<string, string>;
   readEnv?: (cwd: string) => string;
   readFile?: (path: string) => string | null;
+  readInstalledVersion?: (cwd: string, name: string) => string | null;
   readOwnVersion?: () => string | undefined;
   resolveAppLayout?: (cwd: string, fileExists: (path: string) => boolean) => AppLayout;
   resolveSchemaPath?: (cwd: string) => string | null;

package/index.d.mts

@@ -98,6 +98,7 @@ interface RunInitOptions {
   readDeps?: (cwd: string) => Record<string, string>;
   readEnv?: (cwd: string) => string;
   readFile?: (path: string) => string | null;
+  readInstalledVersion?: (cwd: string, name: string) => string | null;
   readOwnVersion?: () => string | undefined;
   resolveAppLayout?: (cwd: string, fileExists: (path: string) => boolean) => AppLayout;
   resolveSchemaPath?: (cwd: string) => string | null;