clivly 0.10.7 → 0.10.9

package/README.md

@@ -530,7 +530,11 @@ subpaths:
 
 ```ts
 import { createClivlySDK, defineClivlyConfig } from "clivly/sdk";
-import { fromDrizzle, discoverFromDrizzle } from "clivly/drizzle";
+import {
+  fromDrizzle,
+  fromDrizzleProjection,
+  discoverFromDrizzle,
+} from "clivly/drizzle";
 import { clivlyVite } from "clivly/vite";
 import { createClerkAuthAdapter } from "clivly/auth/clerk";
 import { createWorkOSAuthAdapter } from "clivly/auth/workos";
@@ -542,6 +546,32 @@ import { createBetterAuthAdapter } from "clivly/auth/better-auth";
 > importing it from app code drags the whole CLI into your bundle and throws at
 > import time on Workers and other edge runtimes.
 
+### Projection entities need `fromDrizzleProjection`
+
+An entity with a `projection` spans several tables. `fromDrizzle` emits a
+single-table select, so pairing it with a projection pushes bare base-table rows
+and every joined field mirrors empty. Use the projection builder instead:
+
+```ts
+source: {
+  custom: [
+    fromDrizzleProjection(db, clientAccountsProjection, {
+      entity: "client_accounts",
+      objectType: "client-accounts",
+      cursorField: "base.updated_at",
+    }),
+  ],
+},
+```
+
+The builder also labels the push with the projection's `baseTable`, which is
+what the mapping is filed under. A hand-built source (`fromDrizzle` with an
+overridden `fetchPage`) is still supported — the SDK derives the same label from
+your config — but the builder performs the joins for you.
+
+> Authoring a derived object in the dashboard? Its **Connect** panel generates
+> this snippet for you, projection literal included.
+
 Provider and framework integrations use **optional peer dependencies**. Install
 only what your app actually uses:
 

package/drizzle.cjs

@@ -60,6 +60,7 @@ function fromDrizzleProjection(db, projection, opts) {
 	const head = [`select ${selectItems.join(", ")}`, fromClause].join(" ");
 	return {
 		entity: opts.entity,
+		pushSource: projection.baseTable,
 		cursorField: cursorToken,
 		idField: "id",
 		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },
@@ -89,6 +90,7 @@ function fromDrizzleProjectionByIdentity(client, projection, identityExpr, fromC
 	const head = [`select ${selectItems.join(", ")}`, fromClause].join(" ");
 	return {
 		entity: opts.entity,
+		pushSource: projection.baseTable,
 		cursorField: "id",
 		idField: "id",
 		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },

package/drizzle.d.cts

@@ -1,6 +1,6 @@
 import { R as ProjectionMapping, z as ProjectionRef } from "./entity-config-w8oMBWf8.cjs";
 import { n as buildUniqueConstraints, r as discoverFromDrizzle } from "./drizzle-SD8WCvYj.cjs";
-import { t as NamespaceIntrospector, v as SyncSource } from "./namespace-probe-lj_0bJrc.cjs";
+import { t as NamespaceIntrospector, v as SyncSource } from "./namespace-probe-C3xMOqWE.cjs";
 import { Table } from "drizzle-orm";
 //#region ../sdk/src/drizzle-projection.d.ts
 /**

package/drizzle.d.mts

@@ -1,6 +1,6 @@
 import { R as ProjectionMapping, z as ProjectionRef } from "./entity-config-w8oMBWf8.mjs";
 import { n as buildUniqueConstraints, r as discoverFromDrizzle } from "./drizzle-axugRJ0u.mjs";
-import { t as NamespaceIntrospector, v as SyncSource } from "./namespace-probe-ouHKZas2.mjs";
+import { t as NamespaceIntrospector, v as SyncSource } from "./namespace-probe-BmxtnOfc.mjs";
 import { Table } from "drizzle-orm";
 //#region ../sdk/src/drizzle-projection.d.ts
 /**

package/drizzle.mjs

@@ -59,6 +59,7 @@ function fromDrizzleProjection(db, projection, opts) {
 	const head = [`select ${selectItems.join(", ")}`, fromClause].join(" ");
 	return {
 		entity: opts.entity,
+		pushSource: projection.baseTable,
 		cursorField: cursorToken,
 		idField: "id",
 		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },
@@ -88,6 +89,7 @@ function fromDrizzleProjectionByIdentity(client, projection, identityExpr, fromC
 	const head = [`select ${selectItems.join(", ")}`, fromClause].join(" ");
 	return {
 		entity: opts.entity,
+		pushSource: projection.baseTable,
 		cursorField: "id",
 		idField: "id",
 		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },

package/index.cjs

@@ -3,7 +3,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_entity_config = require("./entity-config-C2MfIDL2.cjs");
 require("./mapping-score-CaB3F4Uu.cjs");
 const require_internal_entity_heuristics = require("./internal-entity-heuristics.cjs");
-const require_sdk = require("./sdk-DbvqXNSh.cjs");
+const require_sdk = require("./sdk-BIYu0N3V.cjs");
 let node_child_process = require("node:child_process");
 let node_fs = require("node:fs");
 let node_module = require("node:module");
@@ -293,6 +293,124 @@ function addCommand(pm, packages) {
 	};
 }
 //#endregion
+//#region src/detect-workspace.ts
+const SELECTABLE_FRAMEWORKS = [
+	"nextjs",
+	"tanstack-start",
+	"sveltekit",
+	"remix",
+	"nuxt"
+];
+/**
+* Validate a `--framework` value.
+*
+* Rejecting a typo matters more than accepting one leniently: an unrecognised
+* value silently falling back to detection would scaffold route files in the
+* wrong shape, and a route in the wrong shape is not a build error — the
+* generator simply skips it and the endpoint 404s at runtime.
+*/
+function parseFrameworkFlag(value) {
+	if (value === void 0) return;
+	if (SELECTABLE_FRAMEWORKS.includes(value)) return value;
+	throw new Error(`"${value}" is not a supported framework. Accepted: ${SELECTABLE_FRAMEWORKS.join(", ")}.`);
+}
+/**
+* A caution for when the framework came from a sibling package, or null.
+*
+* Borrowing the ORM or auth is unambiguous — one database and one auth instance
+* serve the whole workspace. Borrowing the *framework* is not: route files are
+* generated in that framework's shape and written into the directory `init` ran
+* in, so if the framework lives next door the routes probably belong next door
+* too. Writing TanStack `src/routes/` files into a Hono app is not a build
+* error — the route generator simply never sees them and the endpoints 404.
+*/
+function borrowedFrameworkWarning(framework, source) {
+	if (!source) return null;
+	return `  ⚠️  ${FRAMEWORK_LABELS[framework]} was detected in "${source}", not here.\n      Route files are generated in that framework's shape. If this app
+      does not serve them, run init inside "${source}" instead, or pass\n      --framework to say what this app actually is.
+`;
+}
+/**
+* Extra guidance for a detection failure inside a workspace, or "" outside one.
+*
+* Detection has already scanned every sibling by the time either failure fires,
+* so the marker really is absent everywhere — which is worth saying, because
+* the bare message sends a developer looking for a dependency that was never
+* missing. Returning "" for the single-package case keeps the caller
+* branch-free.
+*/
+function workspaceHint(kind, packageCount) {
+	if (packageCount === 0) return "";
+	const scanned = `\nScanned ${packageCount} workspace package(s) and found no ${kind === "orm" ? "ORM" : "framework"} marker`;
+	return kind === "orm" ? `${scanned}.\nIf your schema is Drizzle, point at it and init will take your word:\n\n  clivly init --schema <path-or-package>\n` : `${scanned}\nin any of them. If this app is served by one of the frameworks above,\nname it outright:\n\n  clivly init --framework tanstack-start\n`;
+}
+/**
+* Resolve one signal, preferring the app's own dependencies.
+*
+* The app's package.json is authoritative: a sibling on a different framework
+* must never redefine what this app is. Only when the app itself is silent do
+* we look outward, and then the first package by name wins.
+*
+* Sorting here rather than trusting the caller matters: the real package list
+* comes from glob expansion, whose order is not guaranteed, so an unsorted scan
+* would let the same repo detect differently between runs and report a
+* different package as the source.
+*/
+function resolveSignal(appDeps, packages, detect, unknown) {
+	const own = detect(appDeps);
+	if (own !== unknown) return {
+		source: null,
+		value: own
+	};
+	const ordered = [...packages].sort((a, b) => a.name.localeCompare(b.name));
+	for (const pkg of ordered) {
+		const found = detect(pkg.deps);
+		if (found !== unknown) return {
+			source: pkg.name,
+			value: found
+		};
+	}
+	return {
+		source: null,
+		value: unknown
+	};
+}
+/**
+* Detect framework, ORM and auth across a whole workspace.
+*
+* A monorepo routinely splits these across packages — framework in the frontend
+* app, ORM in a `db` package, auth in an `auth` package — so reading only the
+* directory `init` was run from finds at most one of the three and fails
+* whichever way the developer turns. Widening the search to sibling packages is
+* what makes those layouts installable.
+*
+* Detection is deliberately a union rather than a per-package view: `init`
+* generates one config for one app, and that app reaches its database and auth
+* through workspace dependencies whether or not they are named in its own
+* manifest.
+*
+* `packages` may include the app itself; that is harmless, since the app's own
+* deps are consulted first anyway. Pass `[]` outside a workspace, which reduces
+* this to a plain single-package read.
+*/
+function detectAcrossWorkspace(appDeps, packages) {
+	const framework = resolveSignal(appDeps, packages, detectFramework, "unknown");
+	const orm = resolveSignal(appDeps, packages, detectOrm, "unknown");
+	const auth = resolveSignal(appDeps, packages, detectAuth, "unknown");
+	const sources = {
+		auth: auth.source,
+		framework: framework.source,
+		orm: orm.source
+	};
+	return {
+		auth: auth.value,
+		borrowed: Object.values(sources).some((source) => source !== null),
+		framework: framework.value,
+		orm: orm.value,
+		sources
+	};
+}
+//#endregion
 //#region src/tick-route.ts
 /**
 * The tick route's public URL path, and the template `clivly login` writes for
@@ -1258,10 +1376,12 @@ Usage:
   clivly init [--force] [--dry-run] [--diff] [--yes] [--no-login] [--no-browser]
               [--schema <path|package>] [--db-import <specifier>]
               [--auth-import <specifier>] [--contact-table <table>]
-              [--company-table <table>]
+              [--company-table <table>] [--framework <name>]
 
 Scaffolds clivly.config.ts, the Clivly route files, and .env placeholders.
 Detects your framework, ORM, auth adapter and app layout from the project.
+In a workspace the whole package graph is scanned, so a monorepo that keeps
+its framework, ORM and auth in separate packages is detected from any app.
 
 Options:
   --dry-run            Show what would be written; write nothing
@@ -1269,7 +1389,8 @@ Options:
   --force              Overwrite files Clivly owns
   --yes                Skip prompts
   --no-login           Skip browser pairing
-  --schema <p>         Path or package holding your ORM schema
+  --framework <n>      nextjs | tanstack-start | sveltekit | remix | nuxt
+  --schema <p>         Path or package holding your ORM schema (implies Drizzle)
   --db-import <s>      Module specifier exporting your database instance
   --auth-import <s>    Module specifier exporting your auth instance
   --contact-table <t>  Table to map as contacts
@@ -1701,13 +1822,52 @@ function toScoredTable(table) {
 function columnNames(table) {
 	return table.columns.map((column) => column.dbName);
 }
-function rankCandidates$1(tables, concept) {
+/**
+* Company candidates the vocabulary cannot name, promoted on foreign-key
+* evidence.
+*
+* The company vocabulary is seven generic business words (companies,
+* organizations, teams, accounts…). A domain word for the same idea —
+* `campuses`, `branches`, `sites`, `practices`, `chapters` — matches none of
+* them, so such a table was never a candidate at all and no amount of ranking
+* could reach it. On `vue-academy` that left Better Auth's `organization` as
+* the only company candidate, and init duly scaffolded the auth table while
+* `campuses`, which every student row references, was invisible.
+*
+* Guessing more words does not fix this; the next unlisted word fails
+* identically. The schema already states the answer: when the CONTACT table
+* holds a real foreign key to some table, that target is what a contact
+* belongs to. `references` is reflected metadata, so this is a fact rather
+* than a name guess.
+*
+* Two guards keep it honest. The target must pass `hasDefiningColumn`, the
+* same "can this table BE a company" test every other candidate passes — a
+* join table with no `name` is not promoted. And framework tables are skipped,
+* because `contacts.organization_id → organization` is exactly the auth
+* plumbing this is meant to see past.
+*/
+function fkPromotedCompanies(tables, contact) {
+	if (!contact) return [];
+	const targets = /* @__PURE__ */ new Set();
+	for (const column of contact.columns) {
+		const table = column.references?.table;
+		if (table && !require_internal_entity_heuristics.isFrameworkTable(table)) targets.add(table.toLowerCase());
+	}
+	return tables.filter((t) => targets.has(t.tableName.toLowerCase()) && t.tableName !== contact.tableName && require_internal_entity_heuristics.hasDefiningColumn("company", columnNames(t)));
+}
+function rankCandidates$1(tables, concept, contact = null) {
+	const promoted = concept === "company" ? fkPromotedCompanies(tables, contact) : [];
+	const promotedNames = new Set(promoted.map((t) => t.tableName));
 	return tables.map((t) => ({
 		t,
-		m: require_internal_entity_heuristics.matchesConcept(t.tableName, concept)
+		m: require_internal_entity_heuristics.matchesConcept(t.tableName, concept) ?? (promotedNames.has(t.tableName) ? { exact: false } : null)
 	})).filter((c) => Boolean(c.m)).sort((a, b) => {
 		const usable = Number(require_internal_entity_heuristics.hasDefiningColumn(concept, columnNames(b.t))) - Number(require_internal_entity_heuristics.hasDefiningColumn(concept, columnNames(a.t)));
 		if (usable !== 0) return usable;
+		const aPromoted = promotedNames.has(a.t.tableName);
+		if (aPromoted !== promotedNames.has(b.t.tableName)) {
+			if (require_internal_entity_heuristics.isFrameworkTable((aPromoted ? b.t : a.t).tableName)) return aPromoted ? -1 : 1;
+		}
 		const exact = Number(b.m.exact) - Number(a.m.exact);
 		if (exact !== 0) return exact;
 		return Number(require_internal_entity_heuristics.isFrameworkTable(a.t.tableName)) - Number(require_internal_entity_heuristics.isFrameworkTable(b.t.tableName));
@@ -1715,7 +1875,7 @@ function rankCandidates$1(tables, concept) {
 }
 function selectEntities(tables) {
 	const contactCands = rankCandidates$1(tables, "contact");
-	const companyCands = rankCandidates$1(tables, "company");
+	const companyCands = rankCandidates$1(tables, "company", contactCands[0] ?? null);
 	const contactNames = new Set(contactCands.map((t) => t.tableName));
 	const companyNames = new Set(companyCands.map((t) => t.tableName));
 	const contactExclusive = contactCands.filter((t) => !companyNames.has(t.tableName));
@@ -1953,14 +2113,19 @@ export async function register() {
 		return;
 	}
 	try {
-		// Built at runtime so the bundler cannot statically trace it. Next
-		// compiles this file for BOTH runtimes, and the guard above only runs on
-		// the edge — it does not stop the edge BUILD from following a literal
-		// import into your config, and from there into your database driver. A
-		// node-postgres app fails that pass on \`require('path')\` and every route
-		// 500s before Clivly is ever reached.
-		const specifier = "${importPath}";
-		const { default: clivly } = await import(/* webpackIgnore: true */ specifier);
+		// A plain import, deliberately. Next compiles this file for BOTH runtimes
+		// and follows this into your config and on into your database driver, so a
+		// Node-only driver breaks the EDGE build — the guard above is a runtime
+		// check and cannot prevent that. The fix belongs in next.config, where
+		// \`clivly init\` writes an edge-only \`config.externals\` entry; nothing here
+		// ever executes on the edge, so the driver only has to resolve.
+		//
+		// Do NOT make this untraceable (a variable specifier, webpackIgnore).
+		// That silences the build error and breaks the app in a worse way:
+		// clivly.config is TypeScript, so an unbundled import cannot load it, and
+		// the catch below turns that into a warning — the app boots, serves
+		// traffic, and never checks in.
+		const { default: clivly } = await import("${importPath}");
 		await clivly.start();
 	} catch (error) {
 		console.warn("[clivly] could not check in:", error);
@@ -2013,6 +2178,46 @@ function nextNeedsInstrumentationFlag(versionRange) {
 }
 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 NODE_ONLY_DRIVERS = /* @__PURE__ */ new Set([
+	"pg",
+	"mysql",
+	"mysql2",
+	"better-sqlite3",
+	"sqlite3",
+	"tedious",
+	"oracledb",
+	"ioredis"
+]);
+/**
+* The Node-only database drivers a config's dependency list contains.
+*
+* Next compiles instrumentation.ts for the edge runtime whether or not the app
+* uses it, and follows the boot hook's config import into the driver. `pg`
+* pulls in `pgpass` → `split2` → `stream`, none of which resolve there, so the
+* build fails and every route 500s — before any Clivly code runs.
+*
+* `serverExternalPackages` does NOT fix this. It applies to the Node server
+* bundle only; the edge pass ignores it entirely, which is why adding package
+* after package to it never terminates. An edge-only `config.externals` is what
+* works, and it is safe precisely because nothing in that bundle ever executes
+* — the boot hook returns early unless NEXT_RUNTIME is "nodejs".
+*/
+function nodeOnlyDrivers(dependencies) {
+	if (!dependencies) return [];
+	return Object.keys(dependencies).filter((name) => NODE_ONLY_DRIVERS.has(name)).sort();
+}
+/** The next.config step an app needs when its config reaches a Node driver. */
+function nextEdgeExternalsStep(drivers) {
+	const list = drivers.map((d) => `"${d}"`).join(", ");
+	return `Your database driver (${drivers.join(", ")}) cannot be bundled for Next's edge runtime, which compiles instrumentation.ts whether or not you use it. Without this, every route fails to build. Add to next.config:
+      webpack: (config, { nextRuntime }) => {
+        if (nextRuntime === "edge") {
+          config.externals = [...(config.externals ?? []), ${list}];
+        }
+        return config;
+      }
+    Nothing runs on the edge — the boot hook exits early there — so the driver only has to resolve.`;
+}
 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));`;
@@ -2563,21 +2768,32 @@ function planEnv(args) {
 		action: envAction(addedKeys.length, existing.length)
 	};
 }
-function declaredNextVersion(args) {
+function hostManifest(args) {
 	const raw = args.readFile((0, node_path.join)(args.cwd, "package.json"));
-	if (!raw) return;
-	let pkg = {};
+	if (!raw) return {};
 	try {
-		pkg = JSON.parse(raw);
+		return JSON.parse(raw);
 	} catch {
-		pkg = {};
+		return {};
 	}
+}
+function declaredNextVersion(args) {
+	const pkg = hostManifest(args);
 	return pkg.dependencies?.next ?? pkg.devDependencies?.next;
 }
+function declaredDependencies(args) {
+	return hostManifest(args).dependencies;
+}
+/** The edge-externals step, or null when no Node-only driver is declared. */
+function edgeExternalsStepFor(dependencies) {
+	const drivers = nodeOnlyDrivers(dependencies);
+	return drivers.length > 0 ? nextEdgeExternalsStep(drivers) : null;
+}
 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
+		manual: args.framework === "nextjs" && nextNeedsInstrumentationFlag(declaredNextVersion(args)) ? NEXT_INSTRUMENTATION_FLAG_STEP : null,
+		extra: args.framework === "nextjs" ? edgeExternalsStepFor(declaredDependencies(args)) : null
 	};
 	if (args.framework === "remix") return {
 		file: null,
@@ -2623,7 +2839,7 @@ function planMutations(args) {
 	return {
 		files,
 		env: planEnv(args),
-		manualSteps: boot.manual ? [boot.manual] : []
+		manualSteps: [boot.manual, boot.extra ?? null].filter((step) => step !== null)
 	};
 }
 function planWidgetMutations(args) {
@@ -3906,6 +4122,18 @@ function resolveInitDeps(options) {
 		authWiring: renderAuthWiring("unknown")
 	};
 }
+/**
+* The three detection lines, annotating any signal borrowed from a sibling.
+*
+* Naming the source package is what makes a workspace detection auditable:
+* without it the banner claims an ORM the developer cannot find in the
+* directory they are standing in.
+*/
+function renderDetectionLines(detection) {
+	const from = (source) => source ? ` (from ${source})` : "";
+	const frameworkNote = detection.frameworkForced ? " (--framework)" : from(detection.sources.framework);
+	return `  Framework: ${FRAMEWORK_LABELS[detection.framework]}${frameworkNote}\n  ORM:       ${detection.orm}${from(detection.sources.orm)}\n  Auth:      ${detection.auth}${from(detection.sources.auth)}${detection.authWired ? " (wired)" : ""}\n`;
+}
 async function acquireSchema(options, deps) {
 	const { out } = deps;
 	const appDeps = deps.readDepsFn(options.cwd);
@@ -3913,26 +4141,39 @@ async function acquireSchema(options, deps) {
 		out(`No package.json found in ${options.cwd}. Run \`clivly init\` from inside an existing app — cd into your project first.\n`);
 		return { code: 1 };
 	}
-	const framework = detectFramework(appDeps);
-	const orm = detectOrm(appDeps);
-	const auth = detectAuth(appDeps);
+	const workspacePackages = (deps.graphFor(options.cwd)?.packages ?? []).map((pkg) => ({
+		deps: deps.readDepsFn(pkg.dir),
+		name: pkg.name
+	}));
+	const detected = detectAcrossWorkspace(appDeps, workspacePackages);
+	const framework = options.frameworkFlag ?? detected.framework;
+	const { auth, orm, sources } = detected;
 	deps.framework = framework;
 	const layout = deps.resolveAppLayout(options.cwd, deps.fileExists);
 	deps.layout = layout;
 	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`);
+	out(renderDetectionLines({
+		auth,
+		authWired: deps.authWiring.complete,
+		framework,
+		frameworkForced: options.frameworkFlag !== void 0,
+		orm,
+		sources
+	}));
 	if (framework === "nextjs") out(`  Layout:    ${layout}\n`);
+	const frameworkCaution = options.frameworkFlag ? null : borrowedFrameworkWarning(framework, sources.framework);
+	if (frameworkCaution) out(`\n${frameworkCaution}`);
 	if (auth === "better-auth" && !deps.authWiring.complete) out("\n  ⚠️  Could not locate your better-auth instance.\n      The verify route will import a placeholder path that does not\n      resolve. Point it at the real module with:\n\n        clivly init --force --auth-import <specifier>\n\n      Accepts an alias ($lib/server/auth, @/lib/auth), a package name,\n      or a project-relative path (src/lib/server/auth).\n");
 	out("\n");
-	if (orm !== "drizzle") {
+	if (orm !== "drizzle" && !options.schemaFlag) {
 		out(`clivly init currently generates config for Drizzle only. Detected ORM: ${orm}\n`);
+		out(workspaceHint("orm", workspacePackages.length));
 		return { code: 1 };
 	}
 	if (framework === "unknown") {
 		out("clivly init doesn't recognise your framework yet (looked for Next.js, TanStack Start, SvelteKit, Remix, Nuxt). Route file generation needs one of these.\n");
+		out(workspaceHint("framework", workspacePackages.length));
 		if ("vue" in appDeps) out("\nUsing Vue? Clivly supports Vue through Nuxt. A Vite SPA has no server\nto mount the sync route on, so the route files need Nuxt's server\ndirectory (or any of the frameworks above).\n");
 		return { code: 1 };
 	}
@@ -4030,6 +4271,10 @@ function previewMutations(deps, mutations, options) {
 		out(`  ${mutations.env.action.padEnd(9)} .env\n`);
 		for (const key of mutations.env.addedKeys) out(`              + ${key}=\n`);
 	}
+	if (mutations.manualSteps.length > 0) {
+		out("\nYou will also need to:\n");
+		for (const step of mutations.manualSteps) out(`\n  ! ${step}\n`);
+	}
 	out(options.diff ? "\nRe-run without --diff to apply; --force to overwrite the files marked conflict.\n" : "\nRe-run without --dry-run to apply.\n");
 }
 function printNextSteps(out, authComplete, loginRan, envFile, needsViteDotenv = false) {
@@ -4356,6 +4601,13 @@ function defaultLoginDeps() {
 	};
 }
 function runInitFromArgv(argv, cwd) {
+	let frameworkFlag;
+	try {
+		frameworkFlag = parseFrameworkFlag(flagValue(argv, "--framework"));
+	} catch (error) {
+		process.stdout.write(`${error.message}\n`);
+		return Promise.resolve(1);
+	}
 	return runInit({
 		cwd,
 		force: argv.includes("--force"),
@@ -4365,6 +4617,7 @@ function runInitFromArgv(argv, cwd) {
 		noLogin: argv.includes("--no-login"),
 		openBrowser: !argv.includes("--no-browser"),
 		schemaFlag: flagValue(argv, "--schema"),
+		frameworkFlag,
 		dbImportFlag: flagValue(argv, "--db-import"),
 		authImportFlag: flagValue(argv, "--auth-import"),
 		contactTableFlag: flagValue(argv, "--contact-table"),

package/index.d.cts

@@ -1,4 +1,5 @@
 //#region src/detect.d.ts
+type Framework = "nextjs" | "tanstack-start" | "sveltekit" | "remix" | "nuxt" | "unknown";
 type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
 //#endregion
 //#region src/app-layout.d.ts
@@ -84,6 +85,7 @@ interface RunInitOptions {
   dryRun?: boolean;
   fileExists?: (path: string) => boolean;
   force: boolean;
+  frameworkFlag?: Framework;
   installPackages?: (options: {
     cwd: string;
     packages: string[];

package/index.d.mts

@@ -1,4 +1,5 @@
 //#region src/detect.d.ts
+type Framework = "nextjs" | "tanstack-start" | "sveltekit" | "remix" | "nuxt" | "unknown";
 type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
 //#endregion
 //#region src/app-layout.d.ts
@@ -84,6 +85,7 @@ interface RunInitOptions {
   dryRun?: boolean;
   fileExists?: (path: string) => boolean;
   force: boolean;
+  frameworkFlag?: Framework;
   installPackages?: (options: {
     cwd: string;
     packages: string[];