@getjack/jack 0.1.12 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@getjack/jack",
-	"version": "0.1.12",
+	"version": "0.1.13",
 	"description": "Ship before you forget why you started. The vibecoder's deployment CLI.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/commands/down.ts

@@ -88,13 +88,10 @@ export default async function down(projectName?: string, flags: DownFlags = {}):
 			info(`Found "${name}" on jack cloud, linking locally...`);
 		}
 
-
 		// Guard against mismatched resolutions when an explicit name is provided
 		if (hasExplicitName && resolved) {
 			const matches =
-				name === resolved.slug ||
-				name === resolved.name ||
-				name === resolved.remote?.projectId;
+				name === resolved.slug || name === resolved.name || name === resolved.remote?.projectId;
 			if (!matches) {
 				error(`Refusing to undeploy '${name}' because it resolves to '${resolved.slug}'.`);
 				info("Use the exact slug/name shown by 'jack info' and try again.");

package/src/commands/login.ts

@@ -1,13 +1,4 @@
-import { input } from "@inquirer/prompts";
-import { type DeviceAuthResponse, pollDeviceToken, startDeviceAuth } from "../lib/auth/client.ts";
-import { type AuthCredentials, saveCredentials } from "../lib/auth/store.ts";
-import {
-	checkUsernameAvailable,
-	getCurrentUserProfile,
-	setUsername,
-} from "../lib/control-plane.ts";
-import { celebrate, error, info, spinner, success, warn } from "../lib/output.ts";
-import { identifyUser } from "../lib/telemetry.ts";
+import { type LoginFlowOptions, runLoginFlow } from "../lib/auth/login-flow.ts";
 
 interface LoginOptions {
 	/** Skip the initial "Logging in..." message (used when called from auto-login) */
@@ -15,197 +6,13 @@ interface LoginOptions {
 }
 
 export default async function login(options: LoginOptions = {}): Promise<void> {
-	if (!options.silent) {
-		info("Logging in to jack cloud...");
-		console.error("");
-	}
+	const flowOptions: LoginFlowOptions = {
+		silent: options.silent,
+	};
 
-	const spin = spinner("Starting login...");
-	let deviceAuth: DeviceAuthResponse;
+	const result = await runLoginFlow(flowOptions);
 
-	try {
-		deviceAuth = await startDeviceAuth();
-		spin.stop();
-	} catch (err) {
-		spin.stop();
-		error(err instanceof Error ? err.message : "Failed to start login");
+	if (!result.success) {
 		process.exit(1);
 	}
-
-	celebrate("Your code:", [deviceAuth.user_code]);
-	info(`Opening ${deviceAuth.verification_uri} in your browser...`);
-	console.error("");
-
-	// Open browser - use Bun.spawn for cross-platform
-	try {
-		const platform = process.platform;
-		const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
-		Bun.spawn([cmd, deviceAuth.verification_uri_complete]);
-	} catch {
-		info(`If the browser didn't open, go to: ${deviceAuth.verification_uri_complete}`);
-	}
-
-	const pollSpin = spinner("Waiting for you to complete login in browser...");
-	const interval = (deviceAuth.interval || 5) * 1000;
-	const expiresAt = Date.now() + deviceAuth.expires_in * 1000;
-
-	while (Date.now() < expiresAt) {
-		await sleep(interval);
-
-		try {
-			const tokens = await pollDeviceToken(deviceAuth.device_code);
-
-			if (tokens) {
-				pollSpin.stop();
-
-				// Default to 5 minutes if expires_in not provided
-				const expiresIn = tokens.expires_in ?? 300;
-				const creds: AuthCredentials = {
-					access_token: tokens.access_token,
-					refresh_token: tokens.refresh_token,
-					expires_at: Math.floor(Date.now() / 1000) + expiresIn,
-					user: tokens.user,
-				};
-				await saveCredentials(creds);
-
-				// Link user identity for cross-platform analytics
-				await identifyUser(tokens.user.id, { email: tokens.user.email });
-
-				console.error("");
-				const displayName = tokens.user.first_name || "Logged in";
-				success(tokens.user.first_name ? `Welcome back, ${displayName}` : displayName);
-
-				// Prompt for username if not set
-				await promptForUsername(tokens.user.email);
-				return;
-			}
-		} catch (err) {
-			pollSpin.stop();
-			error(err instanceof Error ? err.message : "Login failed");
-			process.exit(1);
-		}
-	}
-
-	pollSpin.stop();
-	error("Login timed out. Please try again.");
-	process.exit(1);
-}
-
-function sleep(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms));
 }
-
-async function promptForUsername(email: string): Promise<void> {
-	// Skip in non-TTY environments
-	if (!process.stdout.isTTY) {
-		return;
-	}
-
-	const spin = spinner("Checking account...");
-
-	try {
-		const profile = await getCurrentUserProfile();
-		spin.stop();
-
-		// If user already has a username, skip
-		if (profile?.username) {
-			return;
-		}
-
-		console.error("");
-		info("Choose a username for your jack cloud account.");
-		info("URLs will look like: alice-vibes.runjack.xyz");
-		console.error("");
-
-		// Generate suggestions from $USER env var and email
-		const suggestions = generateUsernameSuggestions(email);
-
-		let username: string | null = null;
-
-		while (!username) {
-			// Show suggestions if available
-			if (suggestions.length > 0) {
-				info(`Suggestions: ${suggestions.join(", ")}`);
-			}
-
-			const inputUsername = await input({
-				message: "Username:",
-				default: suggestions[0],
-				validate: (value) => {
-					if (!value || value.length < 3) {
-						return "Username must be at least 3 characters";
-					}
-					if (value.length > 39) {
-						return "Username must be 39 characters or less";
-					}
-					if (value !== value.toLowerCase()) {
-						return "Username must be lowercase";
-					}
-					if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]{1,2}$/.test(value)) {
-						return "Use only lowercase letters, numbers, and hyphens";
-					}
-					return true;
-				},
-			});
-
-			// Check availability
-			const checkSpin = spinner("Checking availability...");
-			const availability = await checkUsernameAvailable(inputUsername);
-			checkSpin.stop();
-
-			if (!availability.available) {
-				warn(availability.error || `Username "${inputUsername}" is already taken. Try another.`);
-				continue;
-			}
-
-			// Try to set the username
-			const setSpin = spinner("Setting username...");
-			try {
-				await setUsername(inputUsername);
-				setSpin.stop();
-				username = inputUsername;
-				success(`Username set to "${username}"`);
-			} catch (err) {
-				setSpin.stop();
-				warn(err instanceof Error ? err.message : "Failed to set username");
-			}
-		}
-	} catch (err) {
-		spin.stop();
-		// Non-fatal - user can set username later
-		warn("Could not set username. You can set it later.");
-	}
-}
-
-function generateUsernameSuggestions(email: string): string[] {
-	const suggestions: string[] = [];
-
-	// Try $USER environment variable first
-	const envUser = process.env.USER || process.env.USERNAME;
-	if (envUser) {
-		const normalized = normalizeToUsername(envUser);
-		if (normalized && normalized.length >= 3) {
-			suggestions.push(normalized);
-		}
-	}
-
-	// Try email local part
-	const emailLocal = email.split("@")[0];
-	if (emailLocal) {
-		const normalized = normalizeToUsername(emailLocal);
-		if (normalized && normalized.length >= 3 && !suggestions.includes(normalized)) {
-			suggestions.push(normalized);
-		}
-	}
-
-	return suggestions.slice(0, 3); // Max 3 suggestions
-}
-
-function normalizeToUsername(input: string): string {
-	return input
-		.toLowerCase()
-		.replace(/[^a-z0-9]+/g, "-")
-		.replace(/^-+|-+$/g, "")
-		.slice(0, 39);
-}
-

package/src/lib/auth/ensure-auth.test.ts

@@ -0,0 +1,285 @@
+/**
+ * Unit tests for ensure-auth.ts
+ *
+ * Tests the auth gate decision tree for project creation.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock, spyOn } from "bun:test";
+
+// Mock modules before importing the module under test
+const mockIsLoggedIn = mock(() => Promise.resolve(false));
+const mockHasWrangler = mock(() => Promise.resolve(false));
+const mockIsAuthenticated = mock(() => Promise.resolve(false));
+const mockRunLoginFlow = mock(() => Promise.resolve({ success: true }));
+const mockPromptSelect = mock(() => Promise.resolve(0));
+const mockTrack = mock(() => {});
+
+mock.module("./store.ts", () => ({
+	isLoggedIn: mockIsLoggedIn,
+}));
+
+mock.module("../wrangler.ts", () => ({
+	hasWrangler: mockHasWrangler,
+	isAuthenticated: mockIsAuthenticated,
+}));
+
+mock.module("./login-flow.ts", () => ({
+	runLoginFlow: mockRunLoginFlow,
+}));
+
+mock.module("../hooks.ts", () => ({
+	promptSelect: mockPromptSelect,
+}));
+
+mock.module("../telemetry.ts", () => ({
+	Events: { AUTH_GATE_RESOLVED: "auth_gate_resolved" },
+	track: mockTrack,
+}));
+
+// Import after mocking
+import { ensureAuthForCreate } from "./ensure-auth.ts";
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe("ensureAuthForCreate", () => {
+	beforeEach(() => {
+		// Reset all mocks to default state
+		mockIsLoggedIn.mockReset();
+		mockHasWrangler.mockReset();
+		mockIsAuthenticated.mockReset();
+		mockRunLoginFlow.mockReset();
+		mockPromptSelect.mockReset();
+		mockTrack.mockReset();
+
+		// Set default return values
+		mockIsLoggedIn.mockResolvedValue(false);
+		mockHasWrangler.mockResolvedValue(false);
+		mockIsAuthenticated.mockResolvedValue(false);
+		mockRunLoginFlow.mockResolvedValue({ success: true });
+		mockPromptSelect.mockResolvedValue(0);
+
+		// Suppress console.error during tests
+		spyOn(console, "error").mockImplementation(() => {});
+	});
+
+	afterEach(() => {
+		mock.restore();
+	});
+
+	// ==========================================================================
+	// PRD Test Scenarios
+	// ==========================================================================
+
+	describe("PRD Decision Tree", () => {
+		it("proceeds immediately if already logged into jack cloud", async () => {
+			// Scenario: Existing jack cloud user
+			mockIsLoggedIn.mockResolvedValue(true);
+
+			const result = await ensureAuthForCreate();
+
+			expect(result.mode).toBe("managed");
+			expect(result.didLogin).toBe(false);
+			expect(mockRunLoginFlow).not.toHaveBeenCalled();
+			expect(mockPromptSelect).not.toHaveBeenCalled();
+			expect(mockTrack).toHaveBeenCalledWith("auth_gate_resolved", {
+				mode: "managed",
+				reason: "already_logged_in",
+			});
+		});
+
+		it("proceeds with managed mode if logged in, even with wrangler available", async () => {
+			// Scenario: Existing jack cloud user + wrangler
+			mockIsLoggedIn.mockResolvedValue(true);
+			mockHasWrangler.mockResolvedValue(true);
+			mockIsAuthenticated.mockResolvedValue(true);
+
+			const result = await ensureAuthForCreate();
+
+			expect(result.mode).toBe("managed");
+			expect(result.didLogin).toBe(false);
+			expect(mockPromptSelect).not.toHaveBeenCalled();
+		});
+
+		it("prompts for choice when wrangler + CF auth available", async () => {
+			// Scenario: Fresh user, wrangler + CF auth
+			mockIsLoggedIn.mockResolvedValue(false);
+			mockHasWrangler.mockResolvedValue(true);
+			mockIsAuthenticated.mockResolvedValue(true);
+			mockPromptSelect.mockResolvedValue(0); // User chooses jack cloud
+
+			const result = await ensureAuthForCreate({ interactive: true });
+
+			expect(mockPromptSelect).toHaveBeenCalled();
+			expect(result.mode).toBe("managed");
+			expect(result.didLogin).toBe(true);
+			expect(mockRunLoginFlow).toHaveBeenCalled();
+		});
+
+		it("returns BYO mode when user chooses their Cloudflare account", async () => {
+			// Scenario: Fresh user with wrangler + CF auth, chooses BYO
+			mockIsLoggedIn.mockResolvedValue(false);
+			mockHasWrangler.mockResolvedValue(true);
+			mockIsAuthenticated.mockResolvedValue(true);
+			mockPromptSelect.mockResolvedValue(1); // User chooses BYO
+
+			const result = await ensureAuthForCreate({ interactive: true });
+
+			expect(result.mode).toBe("byo");
+			expect(result.didLogin).toBe(false);
+			expect(mockRunLoginFlow).not.toHaveBeenCalled();
+			expect(mockTrack).toHaveBeenCalledWith("auth_gate_resolved", {
+				mode: "byo",
+				reason: "user_chose_byo",
+			});
+		});
+
+		it("auto-starts jack cloud login when no wrangler installed", async () => {
+			// Scenario: Fresh user, no wrangler
+			mockIsLoggedIn.mockResolvedValue(false);
+			mockHasWrangler.mockResolvedValue(false);
+
+			const result = await ensureAuthForCreate({ interactive: true });
+
+			expect(result.mode).toBe("managed");
+			expect(result.didLogin).toBe(true);
+			expect(mockRunLoginFlow).toHaveBeenCalled();
+			expect(mockPromptSelect).not.toHaveBeenCalled();
+			expect(mockTrack).toHaveBeenCalledWith("auth_gate_resolved", {
+				mode: "managed",
+				reason: "auto_login_no_wrangler",
+			});
+		});
+
+		it("auto-starts jack cloud login when wrangler installed but not authenticated", async () => {
+			// Scenario: Fresh user, wrangler installed but not logged in
+			mockIsLoggedIn.mockResolvedValue(false);
+			mockHasWrangler.mockResolvedValue(true);
+			mockIsAuthenticated.mockResolvedValue(false);
+
+			const result = await ensureAuthForCreate({ interactive: true });
+
+			expect(result.mode).toBe("managed");
+			expect(result.didLogin).toBe(true);
+			expect(mockRunLoginFlow).toHaveBeenCalled();
+			expect(mockPromptSelect).not.toHaveBeenCalled();
+			expect(mockTrack).toHaveBeenCalledWith("auth_gate_resolved", {
+				mode: "managed",
+				reason: "auto_login_no_cf_auth",
+			});
+		});
+	});
+
+	// ==========================================================================
+	// Force Flags
+	// ==========================================================================
+
+	describe("Force flags", () => {
+		it("respects forceByo flag without checking auth", async () => {
+			mockIsLoggedIn.mockResolvedValue(true); // Even if logged in
+
+			const result = await ensureAuthForCreate({ forceByo: true });
+
+			expect(result.mode).toBe("byo");
+			expect(result.didLogin).toBe(false);
+			expect(mockTrack).toHaveBeenCalledWith("auth_gate_resolved", {
+				mode: "byo",
+				reason: "forced_byo",
+			});
+		});
+
+		it("respects forceManaged flag and triggers login if needed", async () => {
+			mockIsLoggedIn.mockResolvedValue(false);
+
+			const result = await ensureAuthForCreate({ forceManaged: true });
+
+			expect(result.mode).toBe("managed");
+			expect(result.didLogin).toBe(true);
+			expect(mockRunLoginFlow).toHaveBeenCalled();
+		});
+
+		it("respects forceManaged flag without login if already logged in", async () => {
+			mockIsLoggedIn.mockResolvedValue(true);
+
+			const result = await ensureAuthForCreate({ forceManaged: true });
+
+			expect(result.mode).toBe("managed");
+			expect(result.didLogin).toBe(false);
+			expect(mockRunLoginFlow).not.toHaveBeenCalled();
+		});
+
+		it("throws error when both forceManaged and forceByo are set", async () => {
+			await expect(
+				ensureAuthForCreate({ forceManaged: true, forceByo: true }),
+			).rejects.toThrow("Cannot use both --managed and --byo flags");
+		});
+	});
+
+	// ==========================================================================
+	// Non-interactive mode
+	// ==========================================================================
+
+	describe("Non-interactive mode", () => {
+		it("uses BYO mode when wrangler + CF auth available in non-interactive mode", async () => {
+			mockIsLoggedIn.mockResolvedValue(false);
+			mockHasWrangler.mockResolvedValue(true);
+			mockIsAuthenticated.mockResolvedValue(true);
+
+			const result = await ensureAuthForCreate({ interactive: false });
+
+			expect(result.mode).toBe("byo");
+			expect(result.didLogin).toBe(false);
+			expect(mockPromptSelect).not.toHaveBeenCalled();
+			expect(mockTrack).toHaveBeenCalledWith("auth_gate_resolved", {
+				mode: "byo",
+				reason: "non_interactive_fallback",
+			});
+		});
+
+		it("throws error in non-interactive mode when no auth available", async () => {
+			mockIsLoggedIn.mockResolvedValue(false);
+			mockHasWrangler.mockResolvedValue(false);
+
+			await expect(ensureAuthForCreate({ interactive: false })).rejects.toThrow(
+				"Not logged in and wrangler not authenticated",
+			);
+		});
+
+		it("proceeds with managed mode in non-interactive if already logged in", async () => {
+			mockIsLoggedIn.mockResolvedValue(true);
+
+			const result = await ensureAuthForCreate({ interactive: false });
+
+			expect(result.mode).toBe("managed");
+			expect(result.didLogin).toBe(false);
+		});
+	});
+
+	// ==========================================================================
+	// Edge cases
+	// ==========================================================================
+
+	describe("Edge cases", () => {
+		it("handles Esc key during prompt (defaults to jack cloud login)", async () => {
+			mockIsLoggedIn.mockResolvedValue(false);
+			mockHasWrangler.mockResolvedValue(true);
+			mockIsAuthenticated.mockResolvedValue(true);
+			mockPromptSelect.mockResolvedValue(-1); // Esc key
+
+			const result = await ensureAuthForCreate({ interactive: true });
+
+			expect(result.mode).toBe("managed");
+			expect(result.didLogin).toBe(true);
+			expect(mockRunLoginFlow).toHaveBeenCalled();
+		});
+
+		it("throws error when login flow fails", async () => {
+			mockIsLoggedIn.mockResolvedValue(false);
+			mockHasWrangler.mockResolvedValue(false);
+			mockRunLoginFlow.mockResolvedValue({ success: false });
+
+			await expect(ensureAuthForCreate({ interactive: true })).rejects.toThrow("Login failed");
+		});
+	});
+});

package/src/lib/auth/ensure-auth.ts

@@ -0,0 +1,165 @@
+/**
+ * Auth gate for project creation
+ *
+ * Implements the decision tree from PRD-LOGIN-PROMPT-ON-NEW.md:
+ * 1. Jack cloud logged in -> return 'managed', no prompt
+ * 2. Wrangler installed + CF authenticated -> offer choice via promptSelect
+ * 3. Otherwise -> auto-start jack cloud login
+ */
+
+import type { DeployMode } from "../project-link.ts";
+import { Events, track } from "../telemetry.ts";
+import { hasWrangler, isAuthenticated } from "../wrangler.ts";
+import { isLoggedIn } from "./store.ts";
+
+export interface EnsureAuthResult {
+	mode: DeployMode;
+	didLogin: boolean;
+}
+
+export interface EnsureAuthOptions {
+	interactive?: boolean;
+	forceManaged?: boolean;
+	forceByo?: boolean;
+}
+
+type AuthGateReason =
+	| "already_logged_in"
+	| "forced_managed"
+	| "forced_byo"
+	| "user_chose_managed"
+	| "user_chose_byo"
+	| "auto_login_no_wrangler"
+	| "auto_login_no_cf_auth"
+	| "non_interactive_fallback";
+
+/**
+ * Ensure authentication is in place before project creation.
+ *
+ * Decision tree:
+ * 1. If forceManaged or forceByo flags are set, respect them
+ * 2. If already logged into jack cloud -> return 'managed'
+ * 3. If wrangler installed AND authenticated to Cloudflare -> offer choice
+ * 4. Otherwise -> auto-start jack cloud login
+ */
+export async function ensureAuthForCreate(
+	options: EnsureAuthOptions = {},
+): Promise<EnsureAuthResult> {
+	const { interactive = true, forceManaged, forceByo } = options;
+
+	// Handle explicit flags first
+	if (forceManaged && forceByo) {
+		throw new Error("Cannot use both --managed and --byo flags. Choose one.");
+	}
+
+	if (forceByo) {
+		track(Events.AUTH_GATE_RESOLVED, { mode: "byo", reason: "forced_byo" as AuthGateReason });
+		return { mode: "byo", didLogin: false };
+	}
+
+	if (forceManaged) {
+		// Need to ensure logged in for managed mode
+		const loggedIn = await isLoggedIn();
+		if (loggedIn) {
+			track(Events.AUTH_GATE_RESOLVED, {
+				mode: "managed",
+				reason: "forced_managed" as AuthGateReason,
+			});
+			return { mode: "managed", didLogin: false };
+		}
+		// Force managed but not logged in - run login flow
+		await runLoginFlow();
+		track(Events.AUTH_GATE_RESOLVED, {
+			mode: "managed",
+			reason: "forced_managed" as AuthGateReason,
+		});
+		return { mode: "managed", didLogin: true };
+	}
+
+	// Step 1: Check if already logged into jack cloud
+	const loggedIn = await isLoggedIn();
+	if (loggedIn) {
+		track(Events.AUTH_GATE_RESOLVED, {
+			mode: "managed",
+			reason: "already_logged_in" as AuthGateReason,
+		});
+		return { mode: "managed", didLogin: false };
+	}
+
+	// Step 2: Check if wrangler is installed AND authenticated to Cloudflare
+	const wranglerInstalled = await hasWrangler();
+	const cfAuthenticated = wranglerInstalled && (await isAuthenticated());
+
+	if (cfAuthenticated && interactive) {
+		// Offer choice between jack cloud and BYO
+		const { promptSelect } = await import("../hooks.ts");
+
+		console.error("");
+		console.error("  How do you want to deploy?");
+		console.error("");
+
+		const choice = await promptSelect([
+			"Jack Cloud (recommended) - instant deploys, no setup",
+			"My Cloudflare account - use existing wrangler auth",
+		]);
+
+		if (choice === 0) {
+			// User chose jack cloud - start login
+			await runLoginFlow();
+			track(Events.AUTH_GATE_RESOLVED, {
+				mode: "managed",
+				reason: "user_chose_managed" as AuthGateReason,
+			});
+			return { mode: "managed", didLogin: true };
+		}
+		if (choice === 1) {
+			// User chose BYO
+			track(Events.AUTH_GATE_RESOLVED, { mode: "byo", reason: "user_chose_byo" as AuthGateReason });
+			return { mode: "byo", didLogin: false };
+		}
+		// User pressed Esc - default to jack cloud login
+		await runLoginFlow();
+		track(Events.AUTH_GATE_RESOLVED, {
+			mode: "managed",
+			reason: "user_chose_managed" as AuthGateReason,
+		});
+		return { mode: "managed", didLogin: true };
+	}
+
+	// Non-interactive mode with wrangler available - use BYO
+	if (cfAuthenticated && !interactive) {
+		track(Events.AUTH_GATE_RESOLVED, {
+			mode: "byo",
+			reason: "non_interactive_fallback" as AuthGateReason,
+		});
+		return { mode: "byo", didLogin: false };
+	}
+
+	// Step 3: No viable BYO path - auto-start jack cloud login
+	const reason: AuthGateReason = !wranglerInstalled
+		? "auto_login_no_wrangler"
+		: "auto_login_no_cf_auth";
+
+	if (!interactive) {
+		// Non-interactive and no auth available - this is an error condition
+		throw new Error(
+			"Not logged in and wrangler not authenticated. Run 'jack login' or 'wrangler login' first.",
+		);
+	}
+
+	// Auto-start login (no prompt - there's only one viable path)
+	await runLoginFlow();
+	track(Events.AUTH_GATE_RESOLVED, { mode: "managed", reason });
+	return { mode: "managed", didLogin: true };
+}
+
+/**
+ * Run the login flow (dynamic import to avoid circular dependency)
+ */
+async function runLoginFlow(): Promise<void> {
+	const { runLoginFlow: doLogin } = await import("./login-flow.ts");
+	const result = await doLogin({ silent: false });
+	if (!result.success) {
+		throw new Error("Login failed");
+	}
+}

package/src/lib/auth/index.ts

@@ -6,7 +6,17 @@ export {
 	refreshToken,
 	startDeviceAuth,
 } from "./client.ts";
+export {
+	ensureAuthForCreate,
+	type EnsureAuthOptions,
+	type EnsureAuthResult,
+} from "./ensure-auth.ts";
 export { requireAuth, requireAuthOrLogin, getCurrentUser } from "./guard.ts";
+export {
+	runLoginFlow,
+	type LoginFlowOptions,
+	type LoginFlowResult,
+} from "./login-flow.ts";
 export {
 	deleteCredentials,
 	getAuthState,

package/src/lib/auth/login-flow.ts

@@ -0,0 +1,287 @@
+/**
+ * Shared login flow for CLI and programmatic use
+ */
+import { input } from "@inquirer/prompts";
+import {
+	checkUsernameAvailable,
+	getCurrentUserProfile,
+	registerUser,
+	setUsername,
+} from "../control-plane.ts";
+import { promptSelect } from "../hooks.ts";
+import { celebrate, error, info, spinner, success, warn } from "../output.ts";
+import { identifyUser } from "../telemetry.ts";
+import { type DeviceAuthResponse, pollDeviceToken, startDeviceAuth } from "./client.ts";
+import { type AuthCredentials, saveCredentials } from "./store.ts";
+
+export interface LoginFlowOptions {
+	/** Skip the initial "Logging in..." message (used when called from auto-login) */
+	silent?: boolean;
+	/** Skip the username prompt after login */
+	skipUsernamePrompt?: boolean;
+}
+
+export interface LoginFlowResult {
+	success: boolean;
+	user?: {
+		id: string;
+		email: string;
+		first_name: string | null;
+		last_name: string | null;
+	};
+}
+
+/**
+ * Run the complete login flow including device auth, token polling, and user registration.
+ * Returns a result object instead of calling process.exit().
+ */
+export async function runLoginFlow(options?: LoginFlowOptions): Promise<LoginFlowResult> {
+	if (!options?.silent) {
+		info("Logging in to jack cloud...");
+		console.error("");
+	}
+
+	const spin = spinner("Starting login...");
+	let deviceAuth: DeviceAuthResponse;
+
+	try {
+		deviceAuth = await startDeviceAuth();
+		spin.stop();
+	} catch (err) {
+		spin.stop();
+		error(err instanceof Error ? err.message : "Failed to start login");
+		return { success: false };
+	}
+
+	celebrate("Your code:", [deviceAuth.user_code]);
+	info(`Opening ${deviceAuth.verification_uri} in your browser...`);
+	console.error("");
+
+	// Open browser - use Bun.spawn for cross-platform
+	try {
+		const platform = process.platform;
+		const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
+		Bun.spawn([cmd, deviceAuth.verification_uri_complete]);
+	} catch {
+		info(`If the browser didn't open, go to: ${deviceAuth.verification_uri_complete}`);
+	}
+
+	const pollSpin = spinner("Waiting for you to complete login in browser...");
+	const interval = (deviceAuth.interval || 5) * 1000;
+	const expiresAt = Date.now() + deviceAuth.expires_in * 1000;
+
+	while (Date.now() < expiresAt) {
+		await sleep(interval);
+
+		try {
+			const tokens = await pollDeviceToken(deviceAuth.device_code);
+
+			if (tokens) {
+				pollSpin.stop();
+
+				// Default to 5 minutes if expires_in not provided
+				const expiresIn = tokens.expires_in ?? 300;
+				const creds: AuthCredentials = {
+					access_token: tokens.access_token,
+					refresh_token: tokens.refresh_token,
+					expires_at: Math.floor(Date.now() / 1000) + expiresIn,
+					user: tokens.user,
+				};
+				await saveCredentials(creds);
+
+				// Register user in control plane database (required for subsequent API calls)
+				try {
+					await registerUser({
+						email: tokens.user.email,
+						first_name: tokens.user.first_name,
+						last_name: tokens.user.last_name,
+					});
+				} catch (_regError) {
+					// Registration is required - without it, all API calls will fail
+					error("Failed to complete login - could not reach jack cloud.");
+					error("Please check your internet connection and try again.");
+					return { success: false };
+				}
+
+				// Link user identity for cross-platform analytics
+				await identifyUser(tokens.user.id, { email: tokens.user.email });
+
+				// Prompt for username if not set (unless explicitly skipped)
+				// Do this before welcome message so we know if user is new or returning
+				let isNewUser = false;
+				if (!options?.skipUsernamePrompt) {
+					isNewUser = await promptForUsername(tokens.user.email, tokens.user.first_name);
+				}
+
+				console.error("");
+				const displayName = tokens.user.first_name || "you";
+				if (isNewUser) {
+					success(`Welcome, ${displayName}!`);
+				} else {
+					success(`Welcome back, ${displayName}`);
+				}
+
+				return {
+					success: true,
+					user: tokens.user,
+				};
+			}
+		} catch (err) {
+			pollSpin.stop();
+			error(err instanceof Error ? err.message : "Login failed");
+			return { success: false };
+		}
+	}
+
+	pollSpin.stop();
+	error("Login timed out. Please try again.");
+	return { success: false };
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Prompt user to set their username if not already set.
+ * Returns true if this was a new user (username was set), false if returning user.
+ */
+async function promptForUsername(email: string, firstName: string | null): Promise<boolean> {
+	// Skip in non-TTY environments
+	if (!process.stdout.isTTY) {
+		return false;
+	}
+
+	const spin = spinner("Checking account...");
+
+	try {
+		const profile = await getCurrentUserProfile();
+		spin.stop();
+
+		// If user already has a username, they're a returning user
+		if (profile?.username) {
+			return false;
+		}
+
+		console.error("");
+		info("Choose a username for your jack cloud account.");
+		info("URLs will look like: alice-vibes.runjack.xyz");
+		console.error("");
+
+		// Generate suggestions from first name, $USER env var, and email
+		const suggestions = generateUsernameSuggestions(email, firstName);
+
+		let username: string | null = null;
+
+		while (!username) {
+			// Build options for promptSelect
+			const options = [...suggestions, "Type custom username"];
+			info("Pick a username:");
+			const choice = await promptSelect(options);
+
+			let inputUsername: string;
+
+			if (choice === -1) {
+				// User pressed Esc - skip username setup
+				warn("Skipped username setup. You can set it later.");
+				return true; // Still a new user, just skipped
+			}
+
+			if (choice === options.length - 1) {
+				// User chose to type custom username
+				inputUsername = await input({
+					message: "Username:",
+					validate: validateUsername,
+				});
+			} else {
+				// User picked a suggestion (choice is guaranteed to be valid index)
+				inputUsername = suggestions[choice] as string;
+			}
+
+			// Check availability
+			const checkSpin = spinner("Checking availability...");
+			const availability = await checkUsernameAvailable(inputUsername);
+			checkSpin.stop();
+
+			if (!availability.available) {
+				warn(availability.error || `Username "${inputUsername}" is already taken. Try another.`);
+				continue;
+			}
+
+			// Try to set the username
+			const setSpin = spinner("Setting username...");
+			try {
+				await setUsername(inputUsername);
+				setSpin.stop();
+				username = inputUsername;
+				success(`Username set to "${username}"`);
+			} catch (err) {
+				setSpin.stop();
+				warn(err instanceof Error ? err.message : "Failed to set username");
+			}
+		}
+
+		return true; // New user - username was set
+	} catch (_err) {
+		spin.stop();
+		// Non-fatal - user can set username later
+		warn("Could not set username. You can set it later.");
+		return true; // Assume new user if we couldn't check
+	}
+}
+
+function validateUsername(value: string): string | true {
+	if (!value || value.length < 3) {
+		return "Username must be at least 3 characters";
+	}
+	if (value.length > 39) {
+		return "Username must be 39 characters or less";
+	}
+	if (value !== value.toLowerCase()) {
+		return "Username must be lowercase";
+	}
+	if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]{1,2}$/.test(value)) {
+		return "Use only lowercase letters, numbers, and hyphens";
+	}
+	return true;
+}
+
+function generateUsernameSuggestions(email: string, firstName: string | null): string[] {
+	const suggestions: string[] = [];
+
+	// Try first name first (most personal)
+	if (firstName) {
+		const normalized = normalizeToUsername(firstName);
+		if (normalized && normalized.length >= 3) {
+			suggestions.push(normalized);
+		}
+	}
+
+	// Try $USER environment variable
+	const envUser = process.env.USER || process.env.USERNAME;
+	if (envUser) {
+		const normalized = normalizeToUsername(envUser);
+		if (normalized && normalized.length >= 3 && !suggestions.includes(normalized)) {
+			suggestions.push(normalized);
+		}
+	}
+
+	// Try email local part
+	const emailLocal = email.split("@")[0];
+	if (emailLocal) {
+		const normalized = normalizeToUsername(emailLocal);
+		if (normalized && normalized.length >= 3 && !suggestions.includes(normalized)) {
+			suggestions.push(normalized);
+		}
+	}
+
+	return suggestions.slice(0, 3); // Max 3 suggestions
+}
+
+function normalizeToUsername(input: string): string {
+	return input
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, 39);
+}

package/src/lib/control-plane.ts

@@ -370,6 +370,48 @@ export async function fetchProjectTags(projectId: string): Promise<string[]> {
 	}
 }
 
+export interface RegisterUserRequest {
+	email: string;
+	first_name?: string | null;
+	last_name?: string | null;
+}
+
+export interface RegisterUserResponse {
+	user: {
+		id: string;
+		email: string;
+		first_name?: string;
+		last_name?: string;
+	};
+	org: {
+		id: string;
+		workos_org_id: string;
+	};
+}
+
+/**
+ * Register or update user in the control plane after login.
+ * This must be called after device auth to create/sync the user in the database.
+ */
+export async function registerUser(userInfo: RegisterUserRequest): Promise<RegisterUserResponse> {
+	const { authFetch } = await import("./auth/index.ts");
+
+	const response = await authFetch(`${getControlApiUrl()}/v1/register`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(userInfo),
+	});
+
+	if (!response.ok) {
+		const err = (await response.json().catch(() => ({ message: "Unknown error" }))) as {
+			message?: string;
+		};
+		throw new Error(err.message || `Failed to register user: ${response.status}`);
+	}
+
+	return response.json() as Promise<RegisterUserResponse>;
+}
+
 /**
  * Check if a username is available on jack cloud.
  * Does not require authentication.

package/src/lib/hooks.ts

@@ -185,13 +185,21 @@ function isAccountAssociation(value: unknown): boolean {
 	if (!value || typeof value !== "object") return false;
 	// Check direct format: { header, payload, signature }
 	const obj = value as Record<string, unknown>;
-	if (typeof obj.header === "string" && typeof obj.payload === "string" && typeof obj.signature === "string") {
+	if (
+		typeof obj.header === "string" &&
+		typeof obj.payload === "string" &&
+		typeof obj.signature === "string"
+	) {
 		return true;
 	}
 	// Check nested format from Farcaster: { accountAssociation: { header, payload, signature } }
 	if (obj.accountAssociation && typeof obj.accountAssociation === "object") {
 		const inner = obj.accountAssociation as Record<string, unknown>;
-		return typeof inner.header === "string" && typeof inner.payload === "string" && typeof inner.signature === "string";
+		return (
+			typeof inner.header === "string" &&
+			typeof inner.payload === "string" &&
+			typeof inner.signature === "string"
+		);
 	}
 	return false;
 }
@@ -199,17 +207,27 @@ function isAccountAssociation(value: unknown): boolean {
 /**
  * Extract the accountAssociation object (handles both nested and flat formats)
  */
-function extractAccountAssociation(value: unknown): { header: string; payload: string; signature: string } | null {
+function extractAccountAssociation(
+	value: unknown,
+): { header: string; payload: string; signature: string } | null {
 	if (!value || typeof value !== "object") return null;
 	const obj = value as Record<string, unknown>;
 	// Direct format
-	if (typeof obj.header === "string" && typeof obj.payload === "string" && typeof obj.signature === "string") {
+	if (
+		typeof obj.header === "string" &&
+		typeof obj.payload === "string" &&
+		typeof obj.signature === "string"
+	) {
 		return { header: obj.header, payload: obj.payload, signature: obj.signature };
 	}
 	// Nested format from Farcaster
 	if (obj.accountAssociation && typeof obj.accountAssociation === "object") {
 		const inner = obj.accountAssociation as Record<string, unknown>;
-		if (typeof inner.header === "string" && typeof inner.payload === "string" && typeof inner.signature === "string") {
+		if (
+			typeof inner.header === "string" &&
+			typeof inner.payload === "string" &&
+			typeof inner.signature === "string"
+		) {
 			return { header: inner.header, payload: inner.payload, signature: inner.signature };
 		}
 	}
@@ -490,10 +508,8 @@ const actionHandlers: {
 	writeJson: async (action, context, options) => {
 		const ui = options.output ?? noopOutput;
 		const targetPath = resolveHookPath(action.path, context);
-		const ok = await applyJsonWrite(
-			targetPath,
-			action.set,
-			(value) => substituteVars(value, context),
+		const ok = await applyJsonWrite(targetPath, action.set, (value) =>
+			substituteVars(value, context),
 		);
 		if (!ok) {
 			ui.error(`Invalid JSON file: ${targetPath}`);

package/src/lib/json-edit.ts

@@ -1,10 +1,6 @@
 import { existsSync } from "node:fs";
 
-export function setJsonPath(
-	target: Record<string, unknown>,
-	path: string,
-	value: unknown,
-): void {
+export function setJsonPath(target: Record<string, unknown>, path: string, value: unknown): void {
 	const keys = path.split(".").filter(Boolean);
 	let current: Record<string, unknown> = target;
 

package/src/lib/project-operations.ts

@@ -42,7 +42,7 @@ import {
 import { getSyncConfig } from "./config.ts";
 import { deleteManagedProject } from "./control-plane.ts";
 import { debug, isDebug } from "./debug.ts";
-import { resolveDeployMode, validateModeAvailability } from "./deploy-mode.ts";
+import { validateModeAvailability } from "./deploy-mode.ts";
 import { detectSecrets, generateEnvFile, generateSecretsJson } from "./env-parser.ts";
 import { JackError, JackErrorCode } from "./errors.ts";
 import { type HookOutput, runHook } from "./hooks.ts";
@@ -587,15 +587,16 @@ export async function createProject(
 		throw new JackError(JackErrorCode.VALIDATION_ERROR, "jack is not set up yet", "Run: jack init");
 	}
 
-	// Resolve deploy mode (omakase: logged in => managed, logged out => BYO)
-	const deployMode = await resolveDeployMode({
-		managed: options.managed,
-		byo: options.byo,
+	// Auth gate - check/prompt for authentication before any work
+	const { ensureAuthForCreate } = await import("./auth/ensure-auth.ts");
+	const authResult = await ensureAuthForCreate({
+		interactive,
+		forceManaged: options.managed,
+		forceByo: options.byo,
 	});
-	const modeError = await validateModeAvailability(deployMode);
-	if (modeError) {
-		throw new JackError(JackErrorCode.VALIDATION_ERROR, modeError);
-	}
+
+	// Use authResult.mode (auth gate handles mode resolution)
+	const deployMode = authResult.mode;
 
 	// Close the "Starting..." spinner from new.ts
 	reporter.stop();

package/src/lib/telemetry.ts

@@ -12,6 +12,7 @@ const SESSION_ID = crypto.randomUUID();
 // EVENT REGISTRY
 // ============================================
 export const Events = {
+	AUTH_GATE_RESOLVED: "auth_gate_resolved",
 	COMMAND_INVOKED: "command_invoked",
 	COMMAND_COMPLETED: "command_completed",
 	COMMAND_FAILED: "command_failed",

package/templates/miniapp/public/.well-known/farcaster.json

@@ -1,17 +1,17 @@
 {
-  "accountAssociation": {
-    "header": "",
-    "payload": "",
-    "signature": ""
-  },
-  "miniapp": {
-    "version": "1",
-    "name": "jack-template",
-    "iconUrl": "https://example.com/icon.png",
-    "homeUrl": "https://example.com",
-    "imageUrl": "https://example.com/og.png",
-    "buttonTitle": "Open App",
-    "splashImageUrl": "https://example.com/icon.png",
-    "splashBackgroundColor": "#0a0a0a"
-  }
+	"accountAssociation": {
+		"header": "",
+		"payload": "",
+		"signature": ""
+	},
+	"miniapp": {
+		"version": "1",
+		"name": "jack-template",
+		"iconUrl": "https://example.com/icon.png",
+		"homeUrl": "https://example.com",
+		"imageUrl": "https://example.com/og.png",
+		"buttonTitle": "Open App",
+		"splashImageUrl": "https://example.com/icon.png",
+		"splashBackgroundColor": "#0a0a0a"
+	}
 }

package/templates/miniapp/src/worker.ts

@@ -53,11 +53,7 @@ function getBaseUrl(
 		}
 
 		// Reject localhost or IPs - embeds won't work in local dev or IP domains
-		if (
-			hostname === "localhost" ||
-			hostname === "127.0.0.1" ||
-			isIpAddress(hostname)
-		) {
+		if (hostname === "localhost" || hostname === "127.0.0.1" || isIpAddress(hostname)) {
 			return null; // Signal that we can't generate valid embed URLs
 		}