buncargo 3.0.0 → 3.2.0

package/src/core/quick-tunnel/constants.ts

@@ -0,0 +1,31 @@
+/**
+ * Paths and release metadata for the cloudflared binary.
+ * Derived from unjs/untun (MIT), originally forked from node-cloudflared.
+ */
+
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+export const CLOUDFLARED_VERSION =
+	process.env.CLOUDFLARED_VERSION || "2023.10.0";
+
+export const RELEASE_BASE =
+	"https://github.com/cloudflare/cloudflared/releases/";
+
+/** Directory for buncargo-managed cloudflared (avoid clashing with untun's node-untun). */
+export const cloudflaredBinPath = path.join(
+	tmpdir(),
+	"buncargo-cloudflared",
+	process.platform === "win32"
+		? `cloudflared.${CLOUDFLARED_VERSION}.exe`
+		: `cloudflared.${CLOUDFLARED_VERSION}`,
+);
+
+export const cloudflaredNotice = `
+🔥 Your installation of cloudflared software constitutes a symbol of your signature
+ indicating that you accept the terms of the Cloudflare License, Terms and Privacy Policy.
+
+❯ License: \`https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/license/\`
+❯ Terms: \`https://www.cloudflare.com/terms/\`
+❯ Privacy Policy: \`https://www.cloudflare.com/privacypolicy/\`
+`;

package/src/core/quick-tunnel/index.ts

@@ -0,0 +1,96 @@
+/**
+ * Cloudflare Quick Tunnel via the cloudflared CLI (same approach as unjs/untun).
+ * License / download flow adapted from unjs/untun (MIT).
+ */
+import { existsSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { startCloudflaredTunnel } from "./cloudflared-process";
+import { cloudflaredBinPath, cloudflaredNotice } from "./constants";
+import { installCloudflared } from "./install";
+
+export interface QuickTunnelOptions {
+	url?: string;
+	port?: number | string;
+	hostname?: string;
+	protocol?: "http" | "https";
+	verifyTLS?: boolean;
+	acceptCloudflareNotice?: boolean;
+}
+
+export interface QuickTunnel {
+	getURL: () => Promise<string>;
+	close: () => Promise<void>;
+}
+
+function resolvedLocalUrl(opts: QuickTunnelOptions): string {
+	return (
+		opts.url ??
+		`${opts.protocol || "http"}://${opts.hostname ?? "localhost"}:${opts.port ?? 3000}`
+	);
+}
+
+function envAcceptsCloudflareNotice(): boolean {
+	const v = process.env.BUNCARGO_ACCEPT_CLOUDFLARE_NOTICE;
+	const u = process.env.UNTUN_ACCEPT_CLOUDFLARE_NOTICE;
+	return v === "1" || v === "true" || u === "1" || u === "true";
+}
+
+async function promptInstallCloudflared(): Promise<boolean> {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		return false;
+	}
+	return new Promise((resolve) => {
+		const rl = createInterface({
+			input: process.stdin,
+			output: process.stdout,
+		});
+		rl.question(
+			"Do you agree with the above terms and wish to install the binary from GitHub? (y/N) ",
+			(answer) => {
+				rl.close();
+				resolve(/^y(es)?$/i.test(answer.trim()));
+			},
+		);
+	});
+}
+
+/**
+ * Start a Cloudflare quick tunnel to a local HTTP(S) URL.
+ * Returns undefined if the user declines the cloudflared install (when binary is missing).
+ */
+export async function startQuickTunnel(
+	opts: QuickTunnelOptions,
+): Promise<QuickTunnel | undefined> {
+	const url = resolvedLocalUrl(opts);
+
+	console.log(`Starting cloudflared tunnel to ${url}`);
+
+	if (!existsSync(cloudflaredBinPath)) {
+		console.log(cloudflaredNotice);
+		const canInstall =
+			opts.acceptCloudflareNotice ||
+			envAcceptsCloudflareNotice() ||
+			(await promptInstallCloudflared());
+		if (!canInstall) {
+			console.error("Skipping tunnel setup.");
+			return;
+		}
+		await installCloudflared();
+	}
+
+	const cfArgs: Record<string, string | number | null> = { "--url": url };
+	// Boolean flag: use `null` value so spawn does not pass a stray empty argv (see cloudflared-process).
+	if (!opts.verifyTLS) {
+		cfArgs["--no-tls-verify"] = null;
+	}
+	const tunnel = startCloudflaredTunnel(cfArgs);
+
+	const cleanup = async () => {
+		tunnel.stop();
+	};
+
+	return {
+		getURL: async () => await tunnel.url,
+		close: cleanup,
+	};
+}

package/src/core/quick-tunnel/install.ts

@@ -0,0 +1,160 @@
+/**
+ * Download cloudflared from GitHub releases.
+ * Derived from unjs/untun (MIT), originally forked from node-cloudflared.
+ */
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import https from "node:https";
+import path from "node:path";
+import {
+	CLOUDFLARED_VERSION,
+	cloudflaredBinPath,
+	RELEASE_BASE,
+} from "./constants";
+
+const LINUX_URL: Partial<Record<NodeJS.Architecture, string>> = {
+	arm64: "cloudflared-linux-arm64",
+	arm: "cloudflared-linux-arm",
+	x64: "cloudflared-linux-amd64",
+	ia32: "cloudflared-linux-386",
+};
+
+const MACOS_URL: Partial<Record<NodeJS.Architecture, string>> = {
+	arm64: "cloudflared-darwin-amd64.tgz",
+	x64: "cloudflared-darwin-amd64.tgz",
+};
+
+const WINDOWS_URL: Partial<Record<NodeJS.Architecture, string>> = {
+	x64: "cloudflared-windows-amd64.exe",
+	ia32: "cloudflared-windows-386.exe",
+};
+
+function resolveBase(version: string): string {
+	if (version === "latest") {
+		return `${RELEASE_BASE}latest/download/`;
+	}
+	return `${RELEASE_BASE}download/${version}/`;
+}
+
+export function installCloudflared(
+	to: string = cloudflaredBinPath,
+	version = CLOUDFLARED_VERSION,
+): Promise<string> {
+	switch (process.platform) {
+		case "linux": {
+			return installLinux(to, version);
+		}
+		case "darwin": {
+			return installMacos(to, version);
+		}
+		case "win32": {
+			return installWindows(to, version);
+		}
+		default: {
+			throw new Error(`Unsupported platform: ${process.platform}`);
+		}
+	}
+}
+
+async function installLinux(
+	to: string,
+	version = CLOUDFLARED_VERSION,
+): Promise<string> {
+	const file = LINUX_URL[process.arch];
+
+	if (file === undefined) {
+		throw new Error(`Unsupported architecture: ${process.arch}`);
+	}
+
+	await download(resolveBase(version) + file, to);
+	fs.chmodSync(to, 0o755);
+	return to;
+}
+
+async function installMacos(
+	to: string,
+	version = CLOUDFLARED_VERSION,
+): Promise<string> {
+	const file = MACOS_URL[process.arch];
+
+	if (file === undefined) {
+		throw new Error(`Unsupported architecture: ${process.arch}`);
+	}
+
+	await download(resolveBase(version) + file, `${to}.tgz`);
+	if (process.env.DEBUG) {
+		console.log(`Extracting to ${to}`);
+	}
+	execSync(`tar -xzf ${path.basename(`${to}.tgz`)}`, {
+		cwd: path.dirname(to),
+	});
+	fs.unlinkSync(`${to}.tgz`);
+	fs.renameSync(`${path.dirname(to)}/cloudflared`, to);
+	return to;
+}
+
+async function installWindows(
+	to: string,
+	version = CLOUDFLARED_VERSION,
+): Promise<string> {
+	const file = WINDOWS_URL[process.arch];
+
+	if (file === undefined) {
+		throw new Error(`Unsupported architecture: ${process.arch}`);
+	}
+
+	await download(resolveBase(version) + file, to);
+	return to;
+}
+
+function download(url: string, to: string, redirect = 0): Promise<string> {
+	if (redirect === 0) {
+		if (process.env.DEBUG) {
+			console.log(`Downloading ${url} to ${to}`);
+		}
+	} else if (process.env.DEBUG) {
+		console.log(`Redirecting to ${url}`);
+	}
+
+	return new Promise((resolve, reject) => {
+		if (!fs.existsSync(path.dirname(to))) {
+			fs.mkdirSync(path.dirname(to), { recursive: true });
+		}
+
+		let done = true;
+		const file = fs.createWriteStream(to);
+		const request = https.get(url, (res) => {
+			if (res.statusCode === 302 && res.headers.location !== undefined) {
+				const redirection = res.headers.location;
+				done = false;
+				file.close(() => {
+					void download(redirection, to, redirect + 1).then(resolve, reject);
+				});
+				return;
+			}
+			res.pipe(file);
+		});
+
+		file.on("finish", () => {
+			if (done) {
+				file.close(() => {
+					resolve(to);
+				});
+			}
+		});
+
+		request.on("error", (err) => {
+			fs.unlink(to, () => {
+				reject(err);
+			});
+		});
+
+		file.on("error", (err) => {
+			fs.unlink(to, () => {
+				reject(err);
+			});
+		});
+
+		request.end();
+	});
+}

package/src/core/tunnel.ts

@@ -1,5 +1,5 @@
-import { startTunnel } from "untun";
 import type { AppConfig, DevEnvironment, ServiceConfig } from "../types";
+import { startQuickTunnel } from "./quick-tunnel";
 
 export interface PublicExposeTarget {
 	kind: "service" | "app";
@@ -15,7 +15,8 @@ export interface PublicTunnel {
 	close: () => Promise<void>;
 }
 
-interface UntunTunnelLike {
+interface TunnelBackendResult {
+	getURL?: () => Promise<string>;
 	url?: string;
 	publicUrl?: string;
 	tunnelUrl?: string;
@@ -33,11 +34,17 @@ function parseExposeNames(exposeValue?: string): Set<string> | null {
 	return new Set(names);
 }
 
-function asPublicUrl(tunnel: UntunTunnelLike): string | null {
+/** Resolves public origin from tunnel backends (sync fields or untun-style async getURL). */
+async function resolvePublicUrl(
+	tunnel: TunnelBackendResult,
+): Promise<string | null> {
+	if (typeof tunnel.getURL === "function") {
+		return await tunnel.getURL();
+	}
 	return tunnel.url ?? tunnel.publicUrl ?? tunnel.tunnelUrl ?? null;
 }
 
-function toCloseFn(tunnel: UntunTunnelLike): () => Promise<void> {
+function toCloseFn(tunnel: TunnelBackendResult): () => Promise<void> {
 	const close = tunnel.close ?? tunnel.stop ?? tunnel.destroy;
 	if (!close) return async () => {};
 	return async () => {
@@ -111,10 +118,12 @@ export function resolveExposeTargets<
 export async function startPublicTunnels(
 	targets: PublicExposeTarget[],
 	options: {
-		start?: (input: { url: string }) => Promise<UntunTunnelLike>;
+		start?: (input: {
+			url: string;
+		}) => Promise<TunnelBackendResult | undefined>;
 	} = {},
 ): Promise<PublicTunnel[]> {
-	const start = options.start ?? ((input) => startTunnel(input));
+	const start = options.start ?? ((input) => startQuickTunnel(input));
 	const tunnels: PublicTunnel[] = [];
 
 	try {
@@ -122,8 +131,13 @@ export async function startPublicTunnels(
 			const localUrl = `http://localhost:${target.port}`;
 			const tunnel = (await start({
 				url: localUrl,
-			})) as UntunTunnelLike;
-			const publicUrl = asPublicUrl(tunnel);
+			})) as TunnelBackendResult | undefined;
+			if (tunnel === undefined) {
+				throw new Error(
+					`Tunnel for "${target.name}" could not be started (cloudflared missing or install declined)`,
+				);
+			}
+			const publicUrl = await resolvePublicUrl(tunnel);
 			if (!publicUrl) {
 				throw new Error(
 					`Tunnel for "${target.name}" did not provide a public URL`,

package/src/environment/create-dev-environment.ts

@@ -12,6 +12,12 @@ import {
 	startDevServers,
 	stopProcess as stopProcessFn,
 } from "../core/process";
+import {
+	type PublicTunnel,
+	resolveExposeTargets,
+	startPublicTunnels,
+	stopPublicTunnels,
+} from "../core/tunnel";
 import { isCI as isCIEnv, logExpoApiUrl, logFrontendPort } from "../core/utils";
 import {
 	spawnWatchdog as spawnWatchdogFn,
@@ -36,15 +42,19 @@ import type {
 	ComputedUrls,
 	DevConfig,
 	DevEnvironment,
+	DevEnvironmentTunnelLog,
 	DevServerPids,
 	ExecOptions,
 	HookContext,
+	OpenPublicTunnelsOptions,
+	OpenPublicTunnelsResult,
 	PrismaRunner,
 	ServiceConfig,
 	StartOptions,
 	StopOptions,
 } from "../types";
 import { logEnvironmentInfo } from "./logging";
+import { assertOnlyAppNames, pickApps } from "./only-apps";
 import { createCheckTableHelper, createSeedCheckContext } from "./seeding";
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -213,13 +223,18 @@ export function createDevEnvironment<
 			startServers: shouldStartServers = true,
 			productionBuild = isCI,
 			skipSeed = false,
+			skipEnvironmentLog = false,
+			onlyApps,
 		} = startOptions;
 
+		assertOnlyAppNames(Object.keys(apps), onlyApps);
+		const appsToStart = pickApps(apps, onlyApps);
+
 		const envVars = buildEnvVars(productionBuild);
 		ensureComposeFile();
 
 		// Log environment info
-		if (verbose) {
+		if (verbose && !skipEnvironmentLog) {
 			logInfo(productionBuild ? "Production Environment" : "Dev Environment");
 		}
 
@@ -330,7 +345,7 @@ export function createDevEnvironment<
 		}
 
 		// Start servers if requested
-		if (shouldStartServers && Object.keys(apps).length > 0) {
+		if (shouldStartServers && Object.keys(appsToStart).length > 0) {
 			// Run beforeServers hook
 			if (config.hooks?.beforeServers) {
 				await config.hooks.beforeServers(getHookContext());
@@ -338,11 +353,11 @@ export function createDevEnvironment<
 
 			// Build if production
 			if (productionBuild) {
-				buildApps(apps, root, envVars, { verbose });
+				buildApps(appsToStart, root, envVars, { verbose });
 			}
 
 			// Start servers
-			const pids = await startDevServers(apps, root, envVars, ports, {
+			const pids = await startDevServers(appsToStart, root, envVars, ports, {
 				verbose,
 				productionBuild,
 				isCI,
@@ -350,7 +365,7 @@ export function createDevEnvironment<
 
 			// Wait for servers to be ready
 			if (verbose) console.log("⏳ Waiting for servers to be ready...");
-			await waitForDevServers(apps, ports, {
+			await waitForDevServers(appsToStart, ports, {
 				timeout: isCI ? 120000 : 60000,
 				verbose,
 				productionBuild,
@@ -400,36 +415,129 @@ export function createDevEnvironment<
 	// ─────────────────────────────────────────────────────────────────────────
 
 	async function startServersOnly(
-		options: { productionBuild?: boolean; verbose?: boolean } = {},
+		options: {
+			productionBuild?: boolean;
+			verbose?: boolean;
+			onlyApps?: string[];
+		} = {},
 	): Promise<DevServerPids> {
-		const { productionBuild = false, verbose = true } = options;
+		const { productionBuild = false, verbose = true, onlyApps } = options;
+		assertOnlyAppNames(Object.keys(apps), onlyApps);
+		const appsToStart = pickApps(apps, onlyApps);
 		const envVars = buildEnvVars(productionBuild);
 		const isCI = process.env.CI === "true";
 
+		if (Object.keys(appsToStart).length === 0) {
+			return {};
+		}
+
 		// Build if production
 		if (productionBuild) {
-			buildApps(apps, root, envVars, { verbose });
+			buildApps(appsToStart, root, envVars, { verbose });
 		}
 
-		return startDevServers(apps, root, envVars, ports, {
+		const pids = await startDevServers(appsToStart, root, envVars, ports, {
 			verbose,
 			productionBuild,
 			isCI,
 		});
+
+		if (verbose) console.log("⏳ Waiting for servers to be ready...");
+		await waitForDevServers(appsToStart, ports, {
+			timeout: isCI ? 120000 : 60000,
+			verbose,
+			productionBuild,
+		});
+
+		return pids;
 	}
 
 	async function waitForServersReady(
-		options: { timeout?: number; productionBuild?: boolean } = {},
+		options: {
+			timeout?: number;
+			productionBuild?: boolean;
+			onlyApps?: string[];
+		} = {},
 	): Promise<void> {
-		const { timeout = 60000, productionBuild = false } = options;
-		await waitForDevServers(apps, ports, { timeout, productionBuild });
+		const { timeout = 60000, productionBuild = false, onlyApps } = options;
+		assertOnlyAppNames(Object.keys(apps), onlyApps);
+		const appsToWait = pickApps(apps, onlyApps);
+		await waitForDevServers(appsToWait, ports, { timeout, productionBuild });
+	}
+
+	async function openPublicTunnels(
+		options: OpenPublicTunnelsOptions = {},
+	): Promise<OpenPublicTunnelsResult<TServices, TApps>> {
+		const { names, waitForHealthy } = options;
+		const exposeList = names?.length ? names.join(",") : undefined;
+
+		if (waitForHealthy?.length) {
+			assertOnlyAppNames(Object.keys(apps), waitForHealthy);
+			const appsWait = pickApps(apps, waitForHealthy);
+			const isCI = process.env.CI === "true";
+			await waitForDevServers(appsWait, ports, {
+				timeout: isCI ? 120000 : 60000,
+				verbose: config.options?.verbose ?? true,
+				productionBuild: false,
+			});
+		}
+
+		const { targets, unknownNames, notEnabledNames } = resolveExposeTargets(
+			{
+				services,
+				apps,
+				ports,
+			} as DevEnvironment<TServices, TApps>,
+			exposeList,
+		);
+
+		if (unknownNames.length > 0) {
+			throw new Error(`Unknown expose target(s): ${unknownNames.join(", ")}`);
+		}
+		if (notEnabledNames.length > 0) {
+			throw new Error(
+				`Target(s) missing expose: true: ${notEnabledNames.join(", ")}`,
+			);
+		}
+		if (targets.length === 0) {
+			throw new Error(
+				"No expose targets selected. Add expose: true to services/apps or pass names that have expose: true.",
+			);
+		}
+
+		const tunnels = await startPublicTunnels(targets);
+		setPublicUrls(
+			Object.fromEntries(tunnels.map((t) => [t.name, t.publicUrl])),
+		);
+
+		let closed = false;
+		async function close(): Promise<void> {
+			if (closed) return;
+			closed = true;
+			await stopPublicTunnels(tunnels);
+			clearPublicUrls();
+		}
+
+		return {
+			publicUrls: { ...publicUrls } as ComputedPublicUrls<TServices, TApps>,
+			tunnels,
+			close,
+		};
 	}
 
 	// ─────────────────────────────────────────────────────────────────────────
 	// Utilities
 	// ─────────────────────────────────────────────────────────────────────────
 
-	function logInfo(label = "Docker Dev"): void {
+	function logInfo(label = "Docker Dev", tunnels?: PublicTunnel[]): void {
+		const tunnelRows: DevEnvironmentTunnelLog[] | undefined = tunnels?.map(
+			({ kind, name, localUrl, publicUrl }) => ({
+				kind,
+				name,
+				localUrl,
+				publicUrl,
+			}),
+		);
 		logEnvironmentInfo({
 			label,
 			projectName,
@@ -440,6 +548,7 @@ export function createDevEnvironment<
 			worktree,
 			portOffset,
 			projectSuffix,
+			tunnels: tunnelRows,
 		});
 	}
 
@@ -539,6 +648,7 @@ export function createDevEnvironment<
 		exec,
 		waitForServer: waitForServerUrl,
 		logInfo,
+		openPublicTunnels,
 
 		// Vibe Kanban Integration
 		getExpoApiUrl,

package/src/environment/logging.ts

@@ -14,6 +14,21 @@ function formatDimLabel(label: string, value: string): string {
 	return `  ${pc.dim("•")}  ${pc.dim(label.padEnd(10))} ${pc.dim(value)}`;
 }
 
+function tunnelFor(
+	tunnels:
+		| Array<{
+				kind: "service" | "app";
+				name: string;
+				publicUrl: string;
+				localUrl: string;
+		  }>
+		| undefined,
+	name: string,
+	kind: "service" | "app",
+) {
+	return tunnels?.find((t) => t.name === name && t.kind === kind);
+}
+
 export function logEnvironmentInfo(input: {
 	label: string;
 	projectName: string;
@@ -24,6 +39,12 @@ export function logEnvironmentInfo(input: {
 	worktree: boolean;
 	portOffset: number;
 	projectSuffix?: string;
+	tunnels?: Array<{
+		kind: "service" | "app";
+		name: string;
+		publicUrl: string;
+		localUrl: string;
+	}>;
 }): void {
 	const {
 		label,
@@ -35,6 +56,7 @@ export function logEnvironmentInfo(input: {
 		worktree,
 		portOffset,
 		projectSuffix,
+		tunnels,
 	} = input;
 	const serviceNames = Object.keys(services);
 	const appNames = Object.keys(apps);
@@ -50,6 +72,12 @@ export function logEnvironmentInfo(input: {
 			const port = ports[name];
 			const url = `localhost:${port}`;
 			console.log(formatLabel(`${name}:`, formatUrl(`http://${url}`)));
+			const t = tunnelFor(tunnels, name, "service");
+			if (t) {
+				console.log(
+					`       ${pc.dim("Public:")}  ${formatUrl(t.publicUrl)} ${pc.dim("(tunnel)")}`,
+				);
+			}
 		}
 	}
 
@@ -64,6 +92,12 @@ export function logEnvironmentInfo(input: {
 			console.log(`  ${pc.green("➜")}  ${pc.bold(pc.cyan(name))}`);
 			console.log(`       ${pc.dim("Local:")}   ${formatUrl(localUrl)}`);
 			console.log(`       ${pc.dim("Network:")} ${formatUrl(networkUrl)}`);
+			const t = tunnelFor(tunnels, name, "app");
+			if (t) {
+				console.log(
+					`       ${pc.dim("Public:")}  ${formatUrl(t.publicUrl)} ${pc.dim("(tunnel)")}`,
+				);
+			}
 		}
 	}
 
@@ -79,23 +113,3 @@ export function logEnvironmentInfo(input: {
 	console.log(formatDimLabel("Local IP:", localIp));
 	console.log("");
 }
-
-export function logPublicUrls(
-	tunnels: Array<{
-		kind: "service" | "app";
-		name: string;
-		publicUrl: string;
-		localUrl: string;
-	}>,
-): void {
-	if (tunnels.length === 0) return;
-
-	console.log("");
-	console.log(`  ${pc.dim("─── Public URLs (Quick Tunnel) ───")}`);
-	for (const tunnel of tunnels) {
-		const label = `${tunnel.name} (${tunnel.kind})`;
-		console.log(formatLabel(`${label}:`, formatUrl(tunnel.publicUrl), "🌐"));
-		console.log(formatDimLabel("Local target:", tunnel.localUrl));
-	}
-	console.log("");
-}