clivly 0.3.0-next.2 → 0.3.0-next.3

package/index.mjs

@@ -2,13 +2,15 @@
 import { t as CANONICAL_FIELDS } from "./entity-config-D3YpQB0z.mjs";
 import "./mapping-score-CPPvwoZC.mjs";
 import { matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./core-entity-heuristics.mjs";
-import { t as createClivlySDK } from "./sdk-vu_uej2q.mjs";
+import { t as createClivlySDK } from "./sdk-DtFmeuwl.mjs";
 import { createRequire } from "node:module";
-import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { delimiter, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJiti } from "jiti";
-import { spawn } from "node:child_process";
 //#region src/detect.ts
 const FRAMEWORK_MARKERS = [
 	{
@@ -113,6 +115,154 @@ function addCommand(pm, packages) {
 	};
 }
 //#endregion
+//#region src/dev-tunnel.ts
+const CLOUDFLARE_QUICK_TUNNEL_REGEX = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+const DEFAULT_PORT = "3000";
+const DEFAULT_ROUTE_PATH = "/api/clivly/tick";
+function parseTunnelUrl(chunk) {
+	const match = chunk.match(CLOUDFLARE_QUICK_TUNNEL_REGEX);
+	return match ? match[0] : null;
+}
+function buildTriggerUrl(origin, path) {
+	return `${origin.endsWith("/") ? origin.slice(0, -1) : origin}${path.startsWith("/") ? path : `/${path}`}`;
+}
+function resolveDevTarget(flags) {
+	return {
+		target: flags.url ?? `http://localhost:${flags.port ?? DEFAULT_PORT}`,
+		triggerPath: flags.routePath ?? DEFAULT_ROUTE_PATH
+	};
+}
+function detectDevCommand(scripts, explicit) {
+	if (explicit && explicit.length > 0) return explicit;
+	if (scripts.dev) return [
+		"npm",
+		"run",
+		"dev"
+	];
+	if (scripts.start) return [
+		"npm",
+		"run",
+		"start"
+	];
+	return null;
+}
+const OVERRIDE_FAILURE_CAUSES = {
+	unauthorized: "CLIVLY_API_KEY is invalid for this workspace/backend.",
+	not_enabled: "The target backend does not have the feature-flagged trigger-url endpoint enabled (likely the wrong backend, or the flag is off).",
+	unreachable: "Could not reach Clivly at the selected API base URL."
+};
+function overrideFailureMessage(kind) {
+	return `Warning: could not register the tunnel URL — ${OVERRIDE_FAILURE_CAUSES[kind]} Dashboard-triggered sync is unavailable this session. Your app is still running.`;
+}
+function cloudflaredMissingMessage() {
+	return [
+		"cloudflared is not installed, so clivly dev cannot open a tunnel.",
+		"Remote sync is deploy-only until you install it:",
+		"  brew install cloudflared   (or see https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)",
+		"Your app will still run locally; only dashboard-triggered sync is unavailable."
+	].join("\n");
+}
+//#endregion
+//#region src/dev.ts
+const UNREACHABLE_RESULT = {
+	ok: false,
+	kind: "unreachable"
+};
+function flagValue$1(argv, flag) {
+	const i = argv.indexOf(flag);
+	return i >= 0 ? argv[i + 1] : void 0;
+}
+function explicitCommand(argv) {
+	const sep = argv.indexOf("--");
+	return sep >= 0 ? argv.slice(sep + 1) : null;
+}
+async function runDev(options) {
+	const { deps } = options;
+	const { target, triggerPath } = resolveDevTarget({
+		url: flagValue$1(options.argv, "--url"),
+		port: flagValue$1(options.argv, "--port"),
+		routePath: flagValue$1(options.argv, "--route-path")
+	});
+	const command = detectDevCommand(deps.readScripts(options.cwd), explicitCommand(options.argv));
+	if (!deps.hasCloudflared()) {
+		deps.out(cloudflaredMissingMessage());
+		if (command) {
+			const app = deps.spawnApp(command);
+			deps.onSignal(() => {
+				app?.kill();
+			});
+		}
+		return 0;
+	}
+	if (!options.apiKey) {
+		deps.out("CLIVLY_API_KEY is not set — cannot register the tunnel URL. Set it and re-run.");
+		return 1;
+	}
+	const app = command ? deps.spawnApp(command) : null;
+	const tunnel = deps.spawnTunnel(target);
+	let shuttingDown = false;
+	tunnel.onUrl(async (origin) => {
+		if (shuttingDown) return;
+		const triggerUrl = buildTriggerUrl(origin, triggerPath);
+		deps.out(`Tunnel: ${triggerUrl}`);
+		const result = await deps.register(triggerUrl).catch(() => UNREACHABLE_RESULT);
+		if (result.ok) deps.out("Dashboard-triggered sync now points at this local session.");
+		else deps.out(overrideFailureMessage(result.kind));
+	});
+	return await new Promise((resolve) => {
+		const shutdown = async (code) => {
+			if (shuttingDown) return;
+			shuttingDown = true;
+			tunnel.kill();
+			app?.kill();
+			if (!(await deps.clear().catch(() => UNREACHABLE_RESULT)).ok) deps.out("Warning: could not clear the tunnel override on exit.");
+			resolve(code);
+		};
+		deps.onSignal(() => {
+			shutdown(0);
+		});
+		tunnel.onExit((code) => {
+			shutdown(code);
+		});
+	});
+}
+//#endregion
+//#region src/dev-override.ts
+const TRIGGER_URL_PATH = "/clivly/sdk/trigger-url";
+const HTTP_UNAUTHORIZED = 401;
+const HTTP_NOT_FOUND = 404;
+function kindForStatus(status) {
+	if (status === HTTP_UNAUTHORIZED) return "unauthorized";
+	if (status === HTTP_NOT_FOUND) return "not_enabled";
+	return "unreachable";
+}
+async function registerTunnelOverride(deps) {
+	const res = await (deps.fetchImpl ?? globalThis.fetch)(`${deps.apiUrl}${TRIGGER_URL_PATH}`, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${deps.apiKey}`,
+			"content-type": "application/json"
+		},
+		body: JSON.stringify({ url: deps.triggerUrl })
+	});
+	if (res.ok) return { ok: true };
+	return {
+		ok: false,
+		kind: kindForStatus(res.status)
+	};
+}
+async function clearTunnelOverride(deps) {
+	const res = await (deps.fetchImpl ?? globalThis.fetch)(`${deps.apiUrl}${TRIGGER_URL_PATH}`, {
+		method: "DELETE",
+		headers: { authorization: `Bearer ${deps.apiKey}` }
+	});
+	if (res.ok) return { ok: true };
+	return {
+		ok: false,
+		kind: kindForStatus(res.status)
+	};
+}
+//#endregion
 //#region src/probe-module.ts
 async function probeModule(opts) {
 	for (const candidate of opts.candidates) {
@@ -242,6 +392,90 @@ async function discoverSchema(opts) {
 	};
 }
 //#endregion
+//#region src/env-file.ts
+const REGEX_METACHARACTERS = /[.*+?^${}()|[\]\\]/g;
+function escapeForRegExp(key) {
+	return key.replace(REGEX_METACHARACTERS, "\\$&");
+}
+function keyLinePattern(key, suffix) {
+	return new RegExp(`^[ \\t]*${escapeForRegExp(key)}=${suffix}`, "m");
+}
+function hasKey$1(content, key) {
+	return keyLinePattern(key, "").test(content);
+}
+function findKeyLine(content, key) {
+	const match = keyLinePattern(key, "(.*)$").exec(content);
+	if (!match) return null;
+	return {
+		start: match.index,
+		end: match.index + match[0].length,
+		trimmedValue: (match[1] ?? "").trim()
+	};
+}
+/**
+* Whether `key` carries a real value in `contents`. The `KEY=` placeholder
+* `appendEnvKeys` scaffolds on `clivly init` counts as NOT set — the same rule
+* `upsertEnvValues` applies, shared so there is only one notion of it.
+*/
+function isKeySet(contents, key) {
+	const found = findKeyLine(contents, key);
+	return found !== null && found.trimmedValue !== "";
+}
+/**
+* Append only the `entries` whose key is absent, each preceded by its comment.
+* Existing keys/values are left exactly as-is. Returns the full new content.
+*/
+function appendEnvKeys(existing, entries) {
+	const missing = entries.filter((e) => !hasKey$1(existing, e.key));
+	if (missing.length === 0) return existing;
+	const block = missing.map((e) => `${e.comment ? `# ${e.comment}\n` : ""}${e.key}=`).join("\n");
+	return `${existing}${existing.length > 0 && !existing.endsWith("\n") ? "\n" : ""}${existing.length > 0 ? "\n" : ""}# Clivly\n${block}\n`;
+}
+/**
+* Write each entry's value into the file: in place when the key already has
+* a line, appended (with its comment) when it doesn't.
+*
+* A key whose existing line already has a real value is left untouched
+* unless `force` is set — that's a deliberate choice the developer made.
+* A key whose existing line is empty (e.g. `KEY=`, the placeholder
+* `appendEnvKeys` scaffolds on `clivly init`) counts as ABSENT and is always
+* filled in, `force` or not: `clivly login` run right after `clivly init` —
+* the single most common sequence — must not be a silent no-op just because
+* init already declared the key with nothing in it.
+*/
+function upsertEnvValues(existing, entries, options = {}) {
+	const force = options.force ?? false;
+	let contents = existing;
+	const written = [];
+	const skipped = [];
+	const toAppend = [];
+	for (const entry of entries) {
+		const found = findKeyLine(contents, entry.key);
+		if (!found) {
+			toAppend.push(entry);
+			continue;
+		}
+		if (found.trimmedValue !== "" && !force) {
+			skipped.push(entry.key);
+			continue;
+		}
+		contents = contents.slice(0, found.start) + `${entry.key}=${entry.value}` + contents.slice(found.end);
+		written.push(entry.key);
+	}
+	if (toAppend.length > 0) {
+		const block = toAppend.map((e) => `${e.comment ? `# ${e.comment}\n` : ""}${e.key}=${e.value}`).join("\n");
+		const prefix = contents.length > 0 && !contents.endsWith("\n") ? "\n" : "";
+		const lead = contents.length > 0 ? "\n" : "";
+		contents = `${contents}${prefix}${lead}# Clivly\n${block}\n`;
+		written.push(...toAppend.map((e) => e.key));
+	}
+	return {
+		contents,
+		skipped,
+		written
+	};
+}
+//#endregion
 //#region src/install.ts
 const defaultRun = (command, args, cwd) => new Promise((resolvePromise, reject) => {
 	const child = spawn(command, args, {
@@ -298,6 +532,141 @@ function isEntrypoint(argv1, moduleUrl, realpath = realpathSync) {
 	return resolve(argv1) === resolve(modulePath);
 }
 //#endregion
+//#region src/login.ts
+const POLL_INTERVAL_MS = 2e3;
+const POLL_BACKOFF_MULTIPLIER = 1.5;
+const POLL_INTERVAL_MAX_MS = 1e4;
+const POLL_SERVER_ERROR_MIN = 500;
+const MAX_POLL_ATTEMPTS = 1e3;
+const PAIRING_CODE_HEADER = "x-clivly-pairing-code";
+const MASK_VISIBLE_CHARS = 4;
+const MASK_PREFIX = "••••";
+function maskSecret(value) {
+	if (value.length <= MASK_VISIBLE_CHARS) return MASK_PREFIX;
+	return `${MASK_PREFIX}${value.slice(-MASK_VISIBLE_CHARS)}`;
+}
+async function createPairingSession(apiUrl, deps, rotate) {
+	const res = await deps.fetchImpl(`${apiUrl}/clivly/cli/pair`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({
+			machineName: deps.machineName(),
+			rotate
+		})
+	});
+	if (res.status === 404) {
+		deps.out("clivly login isn't available yet on this server — CLI pairing is not enabled. Ask whoever runs your Clivly backend to enable it, or set CLIVLY_API_KEY / CLIVLY_SYNC_TRIGGER_SECRET manually.");
+		return { exitCode: 1 };
+	}
+	if (!res.ok) {
+		deps.out(`Could not start login: server returned ${res.status}.`);
+		return { exitCode: 1 };
+	}
+	return await res.json();
+}
+function pollErrorMessage(status, message) {
+	if (status === 404) return "Pairing session not found. Run `clivly login` again.";
+	if (status === 401) return "Pairing code was rejected. Run `clivly login` again.";
+	if (status === 400) return message ? `Pairing session can't be used: ${message}` : "Pairing session can't be used. Run `clivly login` again.";
+	return `Could not check login status: server returned ${status}.`;
+}
+async function pollForApproval(apiUrl, deps, session) {
+	const deadline = Date.parse(session.expiresAt);
+	let interval = POLL_INTERVAL_MS;
+	let warnedTransient = false;
+	for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt++) {
+		if (Number.isFinite(deadline) && Date.now() >= deadline) {
+			deps.out("Pairing session expired before it was approved. Run `clivly login` again.");
+			return { exitCode: 1 };
+		}
+		const res = await deps.fetchImpl(`${apiUrl}/clivly/cli/pair/${session.sessionId}`, { headers: { [PAIRING_CODE_HEADER]: session.code } });
+		if (!res.ok) {
+			if (res.status >= POLL_SERVER_ERROR_MIN) {
+				if (!warnedTransient) {
+					deps.out("Server hit an error finishing login — retrying (your approval is still valid)…");
+					warnedTransient = true;
+				}
+				await deps.sleep(interval);
+				interval = Math.min(interval * POLL_BACKOFF_MULTIPLIER, POLL_INTERVAL_MAX_MS);
+				continue;
+			}
+			const body = await res.json().catch(() => ({}));
+			deps.out(pollErrorMessage(res.status, body.message));
+			return { exitCode: 1 };
+		}
+		const body = await res.json();
+		if (body.status === "approved") return {
+			apiKey: body.apiKey,
+			organizationName: body.organizationName,
+			organizationSlug: body.organizationSlug,
+			triggerSecret: body.triggerSecret
+		};
+		await deps.sleep(interval);
+		interval = Math.min(interval * POLL_BACKOFF_MULTIPLIER, POLL_INTERVAL_MAX_MS);
+	}
+	deps.out("Timed out waiting for approval. Run `clivly login` again.");
+	return { exitCode: 1 };
+}
+/**
+* Say which workspace approved this pairing, and get the developer's
+* agreement before writing anything.
+*
+* Approving is not bound to the requester: whoever holds a pending session id
+* and integration-manager in *some* workspace can approve it into that
+* workspace, and the polling CLI only verifies the pairing code — which it
+* holds — so it would happily write a stranger's API key and trigger secret
+* into this project's `.env`, and the host app would then sync its customer
+* data there. Naming the workspace is what makes that visible.
+*
+* A non-interactive run (CI, piped stdin) still gets the name printed but is
+* not prompted: a scripted `clivly login` must not hang waiting for a key.
+*/
+async function confirmWorkspace(deps, credentials) {
+	deps.out(`\nPaired with workspace ${credentials.organizationName} (${credentials.organizationSlug}).`);
+	if (!deps.isInteractive()) return true;
+	return await deps.confirm("Write this workspace's credentials to .env? [y/N] ");
+}
+function credentialEntries(credentials) {
+	return [{
+		key: "CLIVLY_API_KEY",
+		value: credentials.apiKey,
+		comment: "Org API key — Settings → API keys"
+	}, {
+		key: "CLIVLY_SYNC_TRIGGER_SECRET",
+		value: credentials.triggerSecret,
+		comment: "Signing secret — Integrations → Remote sync"
+	}];
+}
+function writeCredentials(options, credentials) {
+	const { deps } = options;
+	const entries = credentialEntries(credentials);
+	const result = upsertEnvValues(deps.readEnv(options.cwd), entries, { force: options.force });
+	deps.writeEnv(options.cwd, result.contents);
+	deps.out("\nLogin successful.\n");
+	const valuesByKey = {
+		CLIVLY_API_KEY: credentials.apiKey,
+		CLIVLY_SYNC_TRIGGER_SECRET: credentials.triggerSecret
+	};
+	for (const entry of entries) if (result.skipped.includes(entry.key)) deps.out(`  • ${entry.key} already set — skipped (pass --force to overwrite)`);
+	else deps.out(`  ✓ ${entry.key}=${maskSecret(valuesByKey[entry.key] ?? "")} written to .env`);
+}
+async function runLogin(options) {
+	const { deps } = options;
+	const session = await createPairingSession(options.apiUrl, deps, options.rotate);
+	if ("exitCode" in session) return session.exitCode;
+	deps.out(`\nApprove this login in your browser:\n  ${session.approveUrl}\n`);
+	if (options.openBrowser) deps.open(session.approveUrl);
+	deps.out("Waiting for approval…");
+	const outcome = await pollForApproval(options.apiUrl, deps, session);
+	if ("exitCode" in outcome) return outcome.exitCode;
+	if (!await confirmWorkspace(deps, outcome)) {
+		deps.out("Login cancelled — nothing was written to .env.");
+		return 1;
+	}
+	writeCredentials(options, outcome);
+	return 0;
+}
+//#endregion
 //#region src/plan-init.ts
 function toScoredTable(table) {
 	return {
@@ -412,21 +781,6 @@ function planInit(schema) {
 	};
 }
 //#endregion
-//#region src/env-file.ts
-function hasKey$1(content, key) {
-	return new RegExp(`^\\s*${key}=`, "m").test(content);
-}
-/**
-* Append only the `entries` whose key is absent, each preceded by its comment.
-* Existing keys/values are left exactly as-is. Returns the full new content.
-*/
-function appendEnvKeys(existing, entries) {
-	const missing = entries.filter((e) => !hasKey$1(existing, e.key));
-	if (missing.length === 0) return existing;
-	const block = missing.map((e) => `${e.comment ? `# ${e.comment}\n` : ""}${e.key}=`).join("\n");
-	return `${existing}${existing.length > 0 && !existing.endsWith("\n") ? "\n" : ""}${existing.length > 0 ? "\n" : ""}# Clivly\n${block}\n`;
-}
-//#endregion
 //#region src/render-config.ts
 const CLIVLY_ENV_KEYS = [
 	{
@@ -1018,6 +1372,7 @@ const configStage = {
 		}
 	}
 };
+const LADDER_OWNED_CHECKS = new Set(["API key present", "Heartbeat"]);
 /** The full ladder, in the order a developer completes setup. */
 const STATUS_STAGES = [
 	apiKeyStage,
@@ -1028,13 +1383,13 @@ const STATUS_STAGES = [
 		label: "Setup checks",
 		needs: [configStage.id],
 		async run(ctx) {
-			const report = await ctx.sdk.doctor();
-			const counted = report.checks.filter((check) => !check.skipped);
+			const owned = (await ctx.sdk.doctor()).checks.filter((check) => !LADDER_OWNED_CHECKS.has(check.name));
+			const counted = owned.filter((check) => !check.skipped);
 			const passed = counted.filter((check) => check.ok).length;
 			return {
-				state: report.ok ? "pass" : "fail",
+				state: counted.every((check) => check.ok) ? "pass" : "fail",
 				detail: `${passed} of ${counted.length} passed`,
-				sub: report.checks.map((check) => ({
+				sub: owned.map((check) => ({
 					label: check.name,
 					ok: check.ok,
 					skipped: check.skipped,
@@ -1156,6 +1511,9 @@ function defaultReadEnv(cwd) {
 function defaultWriteEnv(cwd, contents) {
 	writeFileSync(join(cwd, ".env"), contents, "utf8");
 }
+function defaultIsInteractive() {
+	return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY) && !process.env.CI;
+}
 function resolveInitDeps(options) {
 	return {
 		out: options.out ?? ((line) => process.stdout.write(line)),
@@ -1179,6 +1537,15 @@ function resolveInitDeps(options) {
 		readEnv: options.readEnv ?? defaultReadEnv,
 		readOwnVersion: options.readOwnVersion ?? readOwnVersion,
 		writeEnv: options.writeEnv ?? defaultWriteEnv,
+		isInteractive: options.isInteractive ?? defaultIsInteractive,
+		login: options.login ?? ((cwd) => runLogin({
+			apiUrl: process.env.CLIVLY_API_URL ?? "https://api.clivly.com",
+			cwd,
+			deps: defaultLoginDeps(),
+			force: false,
+			openBrowser: options.openBrowser ?? true,
+			rotate: false
+		})),
 		framework: "unknown",
 		authWiring: renderAuthWiring("unknown")
 	};
@@ -1284,14 +1651,23 @@ function previewMutations(deps, mutations) {
 	}
 	out("\nRe-run without --dry-run to apply.\n");
 }
-function printNextSteps(out, authComplete) {
+function printNextSteps(out, authComplete, loginRan) {
 	out("\nNext steps:\n");
-	out("  1. Set the CLIVLY_* values in .env\n");
+	out(loginRan ? "  1. Credentials written by `clivly login`\n" : "  1. Set the CLIVLY_* values in .env\n");
 	out("  2. Set CLIVLY_SYNC_TRIGGER_URL to your public tick route\n");
+	out("     Local dev? Run `clivly dev` to open a tunnel, or skip this step until you deploy (remote sync is deploy-only locally).\n");
 	const step = authComplete ? 3 : 4;
 	if (!authComplete) out("  3. Finish resolveUser in the auth/verify route\n");
 	out(`  ${step}. Run \`clivly status\` to see where you are\n`);
 }
+function credentialsMissing(envContents) {
+	return !isKeySet(envContents, "CLIVLY_API_KEY");
+}
+function pairingSkipReason(options, deps) {
+	if (options.noLogin) return "--no-login";
+	if (!deps.isInteractive()) return "non-interactive shell";
+	return null;
+}
 async function scaffold(options, deps, plan) {
 	const { out } = deps;
 	const pm = deps.detectPackageManager(options.cwd);
@@ -1311,7 +1687,15 @@ async function scaffold(options, deps, plan) {
 	if (result.ok) out(`Installed clivly (${pm})\n`);
 	else out(`Could not install automatically — run:\n  ${result.command}\n`);
 	applyMutations(options, deps, mutations);
-	printNextSteps(out, deps.authWiring.complete);
+	let loginRan = false;
+	if (credentialsMissing(mutations.env.contents)) {
+		const skipReason = pairingSkipReason(options, deps);
+		if (skipReason) {
+			out(`\nSkipped browser pairing (${skipReason}).\n`);
+			out("  Run `clivly login` from a terminal to write CLIVLY_API_KEY and CLIVLY_SYNC_TRIGGER_SECRET.\n");
+		} else loginRan = await deps.login(options.cwd) === 0;
+	}
+	printNextSteps(out, deps.authWiring.complete, loginRan);
 	return plan.contactDetected ? 0 : 1;
 }
 async function runInit(options) {
@@ -1322,15 +1706,173 @@ async function runInit(options) {
 	printPlan(deps.out, plan);
 	return scaffold(options, deps, plan);
 }
+function hasCloudflaredOnPath() {
+	const pathEnv = process.env.PATH ?? "";
+	const exeName = process.platform === "win32" ? "cloudflared.exe" : "cloudflared";
+	return pathEnv.split(delimiter).some((dir) => {
+		if (!dir) return false;
+		try {
+			accessSync(join(dir, exeName), constants.X_OK);
+			return true;
+		} catch {
+			return false;
+		}
+	});
+}
+function readPackageScripts(cwd) {
+	const pkgPath = join(cwd, "package.json");
+	if (!existsSync(pkgPath)) return {};
+	try {
+		return JSON.parse(readFileSync(pkgPath, "utf8")).scripts ?? {};
+	} catch {
+		return {};
+	}
+}
+function spawnAppProcess(command) {
+	const [cmd, ...args] = command;
+	if (!cmd) return null;
+	const child = spawn(cmd, args, { stdio: "inherit" });
+	child.on("error", (err) => {
+		process.stderr.write(`Could not start "${command.join(" ")}": ${err.message}\n`);
+	});
+	return { kill: () => child.kill() };
+}
+function spawnCloudflaredTunnel(target) {
+	const child = spawn("cloudflared", [
+		"tunnel",
+		"--url",
+		target
+	], { stdio: [
+		"ignore",
+		"pipe",
+		"pipe"
+	] });
+	let urlCb = () => {};
+	let exitCb = () => {};
+	let urlFound = false;
+	const onChunk = (chunk) => {
+		if (urlFound) return;
+		const url = parseTunnelUrl(chunk.toString("utf8"));
+		if (url) {
+			urlFound = true;
+			urlCb(url);
+		}
+	};
+	child.stdout?.on("data", onChunk);
+	child.stderr?.on("data", onChunk);
+	child.on("exit", (code) => {
+		exitCb(code ?? 0);
+	});
+	child.on("error", (err) => {
+		process.stderr.write(`Could not start cloudflared: ${err.message}\n`);
+	});
+	return {
+		onUrl: (cb) => {
+			urlCb = cb;
+		},
+		onExit: (cb) => {
+			exitCb = cb;
+		},
+		kill: () => {
+			child.kill();
+		}
+	};
+}
+function defaultDevDeps(options) {
+	return {
+		hasCloudflared: hasCloudflaredOnPath,
+		spawnTunnel: spawnCloudflaredTunnel,
+		spawnApp: spawnAppProcess,
+		readScripts: readPackageScripts,
+		register: (triggerUrl) => registerTunnelOverride({
+			apiKey: options.apiKey ?? "",
+			apiUrl: options.apiUrl,
+			triggerUrl
+		}),
+		clear: () => clearTunnelOverride({
+			apiKey: options.apiKey ?? "",
+			apiUrl: options.apiUrl
+		}),
+		onSignal: (handler) => {
+			process.on("SIGINT", handler);
+			process.on("SIGTERM", handler);
+		},
+		out: (line) => {
+			process.stdout.write(`${line}\n`);
+		}
+	};
+}
+function openerCommand() {
+	if (process.platform === "darwin") return {
+		command: "open",
+		args: []
+	};
+	if (process.platform === "win32") return {
+		command: "cmd",
+		args: [
+			"/c",
+			"start",
+			""
+		]
+	};
+	return {
+		command: "xdg-open",
+		args: []
+	};
+}
+function openInBrowser(url) {
+	const { command, args } = openerCommand();
+	try {
+		const child = spawn(command, [...args, url], {
+			stdio: "ignore",
+			detached: true
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+}
+function promptYesNo(question) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	return rl.question(question).then((answer) => {
+		rl.close();
+		const normalized = answer.trim().toLowerCase();
+		return normalized === "y" || normalized === "yes";
+	});
+}
+function defaultLoginDeps() {
+	return {
+		confirm: promptYesNo,
+		fetchImpl: globalThis.fetch,
+		isInteractive: defaultIsInteractive,
+		machineName: hostname,
+		open: openInBrowser,
+		out: (line) => {
+			process.stdout.write(`${line}\n`);
+		},
+		readEnv: defaultReadEnv,
+		sleep: (ms) => new Promise((resolve) => {
+			setTimeout(resolve, ms);
+		}),
+		writeEnv: defaultWriteEnv
+	};
+}
+function runInitFromArgv(argv, cwd) {
+	return runInit({
+		cwd,
+		force: argv.includes("--force"),
+		dryRun: argv.includes("--dry-run"),
+		noLogin: argv.includes("--no-login"),
+		openBrowser: !argv.includes("--no-browser"),
+		schemaFlag: flagValue(argv, "--schema")
+	});
+}
 async function main(argv) {
 	const [command, ...rest] = argv;
 	switch (command) {
-		case "init": return await runInit({
-			cwd: process.cwd(),
-			force: rest.includes("--force"),
-			dryRun: rest.includes("--dry-run"),
-			schemaFlag: flagValue(rest, "--schema")
-		});
+		case "init": return await runInitFromArgv(rest, process.cwd());
 		case "push-schema": return await runPushSchema({
 			cwd: process.cwd(),
 			configPath: flagValue(rest, "--config")
@@ -1346,10 +1888,32 @@ async function main(argv) {
 			only: ALIAS_STAGE_IDS[command],
 			verbose: rest.includes("--verbose")
 		});
+		case "dev": {
+			const apiKey = process.env.CLIVLY_API_KEY;
+			const apiUrl = flagValue(rest, "--api-url") ?? process.env.CLIVLY_API_URL ?? "https://api.clivly.com";
+			return await runDev({
+				cwd: process.cwd(),
+				argv: rest,
+				apiKey,
+				apiUrl,
+				deps: defaultDevDeps({
+					apiKey,
+					apiUrl
+				})
+			});
+		}
+		case "login": return await runLogin({
+			cwd: process.cwd(),
+			apiUrl: flagValue(rest, "--api-url") ?? process.env.CLIVLY_API_URL ?? "https://api.clivly.com",
+			force: rest.includes("--force"),
+			rotate: rest.includes("--rotate"),
+			openBrowser: !rest.includes("--no-browser"),
+			deps: defaultLoginDeps()
+		});
 		case void 0:
 		case "help":
 		case "--help":
-			process.stdout.write("clivly — embed a CRM in your app\n\nUsage:\n  clivly init [--force] [--dry-run] [--schema <path>]   Scaffold Clivly (config, routes, .env) for your app\n  clivly status [--verbose] [--config <path>]   Check your setup, step by step\n  clivly push-schema [--config <path>]   Report your schema to Clivly without deploying\n");
+			process.stdout.write("clivly — embed a CRM in your app\n\nUsage:\n  clivly init [--force] [--dry-run] [--schema <path>] [--no-login] [--no-browser]   Scaffold Clivly (config, routes, .env) for your app\n  clivly status [--verbose] [--config <path>]   Check your setup, step by step\n  clivly push-schema [--config <path>]   Report your schema to Clivly without deploying\n  clivly dev [--port <n>] [--api-url <url>] [--route-path <path>] [-- <cmd>]   Tunnel localhost for remote sync\n  clivly login [--force] [--rotate] [--api-url <url>] [--no-browser]   Pair this machine and write CLIVLY_API_KEY / CLIVLY_SYNC_TRIGGER_SECRET to .env\n");
 			return 0;
 		default:
 			process.stdout.write(`Unknown command: ${command}\n`);
@@ -1360,4 +1924,4 @@ if (isEntrypoint(process.argv[1], import.meta.url)) main(process.argv.slice(2)).
 	process.exitCode = code;
 });
 //#endregion
-export { runInit };
+export { runInit, runInitFromArgv };