tippa 0.1.0

package/dist/index.mjs

@@ -0,0 +1,457 @@
+import { a as MAX_HTML_CHARS, c as pickRequestSchema, d as STATUS_EVENT, f as STATUS_REQUEST_EVENT, h as isAlive, i as sendJson, l as MAX_BODY_BYTES, m as discoverySchema, n as isClientAbort, p as discoveryPath, r as readBody, s as pickReplySchema, t as hasSecretHeader, u as REPLY_EVENT } from "./http-BcWR4_RM.mjs";
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { z } from "zod";
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+//#region src/agent.ts
+/** what `send` rejects with when no agent is reachable; the endpoint answers 503 */
+var AgentNotConnectedError = class extends Error {
+	constructor(label) {
+		super(`${label} isn't connected`);
+		this.name = "AgentNotConnectedError";
+	}
+};
+//#endregion
+//#region src/claude-session.ts
+const LABEL = "Claude";
+const POLL_MS = 2e3;
+const SEND_TIMEOUT_MS = 1e4;
+const healthSchema = z.object({ ok: z.literal(true) });
+/**
+* sends picks to the claude code session running the `tippa-channel` helper.
+* finds the helper through the nearest `.tippa/channel.json` at or above vite's root.
+*/
+function claudeSession() {
+	return {
+		label: LABEL,
+		connect: ({ root, logger }) => connectToHelper(root, logger)
+	};
+}
+/** why a check found no helper; logged once per distinct text */
+var NoHelper = class {
+	reason;
+	constructor(reason) {
+		this.reason = reason;
+	}
+};
+function connectToHelper(root, logger) {
+	const statusListeners = /* @__PURE__ */ new Set();
+	const replyListeners = /* @__PURE__ */ new Set();
+	let status = "waiting";
+	let announced = false;
+	let helper;
+	let inFlight;
+	let timer;
+	let closed = false;
+	function setStatus(next) {
+		if (announced && next === status) return;
+		announced = true;
+		status = next;
+		for (const listener of statusListeners) listener(next);
+	}
+	function wait() {
+		helper = void 0;
+		inFlight = void 0;
+		setStatus("waiting");
+		timer = setTimeout(check, POLL_MS).unref();
+	}
+	async function check() {
+		const controller = new AbortController();
+		inFlight = controller;
+		const result = await findDiscovery(root).then((found) => found instanceof NoHelper ? found : open(found, controller.signal)).catch((error) => controller.signal.aborted ? new NoHelper() : new NoHelper(`helper request failed: ${error}`));
+		if (closed) {
+			controller.abort();
+			return;
+		}
+		if (result instanceof NoHelper) {
+			if (result.reason) logger.warnOnce(`tippa: ${result.reason}`);
+			return wait();
+		}
+		helper = result.discovery;
+		setStatus("connected");
+		readReplies(result.stream, emitReply).then(() => {
+			if (!closed) wait();
+		});
+	}
+	function emitReply(reply) {
+		for (const listener of replyListeners) listener(reply);
+	}
+	check();
+	return {
+		get status() {
+			return status;
+		},
+		onStatus(listener) {
+			statusListeners.add(listener);
+		},
+		onReply(listener) {
+			replyListeners.add(listener);
+		},
+		async send(pick) {
+			const target = helper;
+			if (!target) throw new AgentNotConnectedError(LABEL);
+			const res = await fetch(helperUrl(target, "/pick"), {
+				method: "POST",
+				headers: {
+					...auth(target),
+					"content-type": "application/json"
+				},
+				body: JSON.stringify(pick),
+				signal: AbortSignal.timeout(SEND_TIMEOUT_MS)
+			}).catch((error) => {
+				if (isHelperGone(error)) throw new AgentNotConnectedError(LABEL);
+				throw error;
+			});
+			const body = await res.text();
+			if (res.status !== 202) throw new Error(`helper refused the pick (${res.status}): ${body}`);
+		},
+		async close() {
+			closed = true;
+			clearTimeout(timer);
+			inFlight?.abort();
+		}
+	};
+}
+/**
+* checks the port answers as the helper, then opens its reply stream.
+* `signal` aborts both, and stays attached to the stream for close()
+*/
+async function open(found, signal) {
+	const health = await fetch(helperUrl(found, "/health"), {
+		headers: auth(found),
+		signal: AbortSignal.any([signal, AbortSignal.timeout(POLL_MS)])
+	});
+	const healthBody = await health.text();
+	if (health.status === 401) return new NoHelper("the helper refused channel.json's secret; is another project's helper on that port?");
+	if (health.status === 503) return new NoHelper();
+	if (!health.ok || !isHealthy(healthBody)) return new NoHelper(`port ${found.port} from channel.json doesn't answer as the helper; waiting for a fresh one`);
+	const headers = new AbortController();
+	const headerTimer = setTimeout(() => headers.abort(), POLL_MS);
+	const events = await fetch(helperUrl(found, "/events"), {
+		headers: auth(found),
+		signal: AbortSignal.any([signal, headers.signal])
+	}).finally(() => clearTimeout(headerTimer));
+	const isStream = events.headers.get("content-type")?.startsWith("text/event-stream");
+	if (!events.ok || !isStream || !events.body) {
+		await events.body?.cancel();
+		return new NoHelper(`port ${found.port} from channel.json doesn't stream as the helper; waiting for a fresh one`);
+	}
+	return {
+		discovery: found,
+		stream: events.body
+	};
+}
+/** the nearest discovery file wins; one whose helper process is gone is skipped */
+async function findDiscovery(root) {
+	for (let dir = root;; dir = dirname(dir)) {
+		const path = discoveryPath(dir);
+		let text;
+		try {
+			text = await readFile(path, "utf8");
+		} catch (error) {
+			const { code } = error;
+			if (code !== "ENOENT") return new NoHelper(`can't read ${path}: ${code}`);
+			if (dirname(dir) === dir) return new NoHelper();
+			continue;
+		}
+		let parsed;
+		try {
+			parsed = discoverySchema.parse(JSON.parse(text));
+		} catch {
+			return new NoHelper(`${path} is not a valid channel.json`);
+		}
+		if (isAlive(parsed.pid)) return parsed;
+		if (dirname(dir) === dir) return new NoHelper();
+	}
+}
+function isHelperGone(error) {
+	const code = error?.cause?.code;
+	return code === "ECONNREFUSED" || code === "ECONNRESET";
+}
+function isHealthy(body) {
+	try {
+		return healthSchema.safeParse(JSON.parse(body)).success;
+	} catch {
+		return false;
+	}
+}
+function helperUrl({ port }, path) {
+	return `http://127.0.0.1:${port}${path}`;
+}
+function auth({ secret }) {
+	return { "x-tippa-secret": secret };
+}
+/** reads the helper's `data: <json>` events until the stream ends or is aborted */
+async function readReplies(stream, emit) {
+	let buffer = "";
+	try {
+		for await (const chunk of stream.pipeThrough(new TextDecoderStream())) {
+			buffer += chunk;
+			const events = buffer.split("\n\n");
+			buffer = events.pop() ?? "";
+			for (const event of events) {
+				const reply = parseReply(event.split("\n").filter((line) => line.startsWith("data: ")).map((line) => line.slice(6)).join("\n"));
+				if (reply) emit(reply);
+			}
+		}
+	} catch {}
+}
+function parseReply(data) {
+	try {
+		return pickReplySchema.parse(JSON.parse(data));
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/plugin.ts
+const NAME = "tippa";
+const ENDPOINT = "/__tippa/pick";
+const FS_PREFIX = "/@fs/";
+const LOADER_ID = "virtual:tippa/client";
+const RESOLVED_LOADER_ID = `\0${LOADER_ID}`;
+const CLIENT_ENTRY = fileURLToPath(new URL("./client/index", import.meta.url));
+function tippa(options) {
+	const sessions = /* @__PURE__ */ new WeakMap();
+	return {
+		name: NAME,
+		apply: (_, env) => env.command === "serve" && env.mode !== "test" && !process.env.VITEST,
+		applyToEnvironment: (environment) => environment.name === "client",
+		configResolved(config) {
+			validate(options);
+			if (config.experimental.bundledDev) config.logger.warnOnce(`[${NAME}] experimental.bundledDev is on; the tippa client only loads in the default dev mode`);
+		},
+		configureServer(server) {
+			const token = randomBytes(32).toString("hex");
+			const { agent } = options;
+			const { logger, root } = server.config;
+			const client = server.environments.client;
+			const hot = client.hot;
+			if (isNetworkExposed(server.config.server.host)) logger.warnOnce(`[${NAME}] the dev server is exposed on the network; tippa only accepts picks from this machine`);
+			const agentConnection = agent.connect({
+				root,
+				logger
+			});
+			sessions.set(client, {
+				token,
+				connection: agentConnection
+			});
+			agentConnection.onStatus((status) => {
+				logger.info(status === "connected" ? `tippa → connected to ${agent.label}` : `tippa → waiting for ${agent.label}`);
+				hot.send(STATUS_EVENT, { status });
+			});
+			agentConnection.onReply((reply) => hot.send(REPLY_EVENT, reply));
+			hot.on(STATUS_REQUEST_EVENT, (_, client) => client.send(STATUS_EVENT, { status: agentConnection.status }));
+			server.middlewares.use(pickEndpoint({
+				token,
+				root,
+				environment: client,
+				agent: agentConnection,
+				logger
+			}));
+		},
+		async buildEnd() {
+			await sessions.get(this.environment)?.connection.close();
+			sessions.delete(this.environment);
+		},
+		transform: {
+			filter: { id: /\/vite\/dist\/client\/client\.mjs$/ },
+			handler(code) {
+				return {
+					code: `${code}\nimport(${JSON.stringify(LOADER_ID)});\n`,
+					map: null
+				};
+			}
+		},
+		resolveId: {
+			filter: { id: new RegExp(`^${LOADER_ID}$`) },
+			handler: () => RESOLVED_LOADER_ID
+		},
+		load: {
+			filter: { id: new RegExp(`^\0${LOADER_ID}$`) },
+			handler() {
+				const session = sessions.get(this.environment);
+				if (!session) return null;
+				const config = {
+					token: session.token,
+					endpoint: ENDPOINT,
+					...options.key !== void 0 && { key: options.key }
+				};
+				return [
+					`import { start } from ${JSON.stringify(CLIENT_ENTRY)};`,
+					`start(${JSON.stringify(config)});`,
+					`import.meta.hot?.send(${JSON.stringify(STATUS_REQUEST_EVENT)});`
+				].join("\n");
+			}
+		}
+	};
+}
+/** vite binds `localhost` when `server.host` is unset or false */
+function isNetworkExposed(host) {
+	if (host === void 0 || host === false) return false;
+	return host === true || !(host === "localhost" || isLoopback(host));
+}
+function validate(options) {
+	const { agent, key } = options ?? {};
+	if (typeof agent?.connect !== "function") throw new Error(`[${NAME}] options.agent must be an agent adapter, e.g. tippa({ agent: claudeSession() })`);
+	if (key !== void 0 && (typeof key !== "string" || key.length === 0)) throw new Error(`[${NAME}] options.key must be a non-empty string, or omitted for react-grab's default`);
+}
+/**
+* `POST /__tippa/pick` → 202 `{ pickId, status: "sent" }`, or `{ error }` with
+* 403 `forbidden_address`, 403 `forbidden_forwarded`, 403 `forbidden_origin`, 401 `unauthorized`, 405 `method_not_allowed`, 413 `too_large`, 400 `invalid_pick`,
+* 503 `not_connected`, 502 `send_failed`
+*/
+function pickEndpoint({ token, root, environment, agent, logger }) {
+	async function handle(req, res) {
+		if (!isLoopback(req.socket.remoteAddress)) {
+			req.resume();
+			return sendJson(res, 403, { error: "forbidden_address" });
+		}
+		if (FORWARDING_HEADERS.some((header) => header in req.headers)) {
+			req.resume();
+			return sendJson(res, 403, { error: "forbidden_forwarded" });
+		}
+		if (!isSameOrigin(req)) {
+			req.resume();
+			return sendJson(res, 403, { error: "forbidden_origin" });
+		}
+		if (!hasSecretHeader(req, "x-tippa-token", token)) {
+			req.resume();
+			return sendJson(res, 401, { error: "unauthorized" });
+		}
+		if (req.method !== "POST") {
+			req.resume();
+			return sendJson(res, 405, { error: "method_not_allowed" });
+		}
+		const body = await readBody(req, MAX_BODY_BYTES);
+		if (body === void 0) return sendJson(res, 413, { error: "too_large" });
+		let json;
+		try {
+			json = JSON.parse(body);
+		} catch {
+			return sendJson(res, 400, {
+				error: "invalid_pick",
+				message: "body is not valid json"
+			});
+		}
+		const parsed = pickRequestSchema.safeParse(json);
+		if (!parsed.success) return sendJson(res, 400, {
+			error: "invalid_pick",
+			message: z.prettifyError(parsed.error)
+		});
+		const elements = [];
+		for (const [index, { moduleUrl, ...element }] of parsed.data.elements.entries()) {
+			const file = await sourceFilePath(element.file, moduleUrl, {
+				host: req.headers.host,
+				root,
+				environment
+			});
+			if (file === void 0) return sendJson(res, 400, {
+				error: "invalid_pick",
+				message: `elements[${index}].moduleUrl is not a module of this dev server`
+			});
+			elements.push({
+				...element,
+				file,
+				html: element.html.slice(0, MAX_HTML_CHARS)
+			});
+		}
+		if (agent.status !== "connected") return sendJson(res, 503, { error: "not_connected" });
+		try {
+			await agent.send({
+				...parsed.data,
+				elements
+			});
+		} catch (error) {
+			if (error instanceof AgentNotConnectedError) return sendJson(res, 503, { error: "not_connected" });
+			logger.error(`[${NAME}] sending pick ${parsed.data.pickId} failed: ${error}`);
+			return sendJson(res, 502, { error: "send_failed" });
+		}
+		sendJson(res, 202, {
+			pickId: parsed.data.pickId,
+			status: "sent"
+		});
+	}
+	return (req, res, next) => {
+		if (req.url?.split("?")[0] !== ENDPOINT) return next();
+		handle(req, res).catch((error) => {
+			if (!isClientAbort(req)) next(error);
+		});
+	};
+}
+/**
+* the absolute path of an element's source: `file` read against the module the page loaded,
+* or as a vite url without one; undefined when `moduleUrl` isn't a module of this dev server
+*/
+async function sourceFilePath(file, moduleUrl, context) {
+	if (moduleUrl === void 0) return viteUrlPath(file, context.root);
+	const moduleFile = await moduleFilePath(moduleUrl, context);
+	return moduleFile && mapSourcePath(file, moduleFile);
+}
+/**
+* a vite url as a file path: root-relative, or `/@fs/<absolute>` outside the root.
+* whoever reads the pick runs elsewhere, so it gets the file's absolute path
+*/
+function viteUrlPath(url, root) {
+	const [path = url] = url.split(/[?#]/);
+	return servedPathFile(path, root);
+}
+function servedPathFile(path, root) {
+	return path.startsWith(FS_PREFIX) ? path.slice(4) : join(root, path);
+}
+/**
+* the file behind a module url the page loaded, or undefined for another origin,
+* an undecodable path or one climbing out through an encoded `..`
+*/
+async function moduleFilePath(moduleUrl, { host, root, environment }) {
+	let path;
+	try {
+		const url = new URL(moduleUrl, `http://${host}`);
+		if (!(url.host === host && (url.protocol === "http:" || url.protocol === "https:"))) return void 0;
+		path = decodeURIComponent(url.pathname);
+	} catch {
+		return;
+	}
+	if (path.split("/").includes("..")) return void 0;
+	return (await environment.moduleGraph.getModuleByUrl(path).catch(() => void 0))?.file ?? servedPathFile(path, root);
+}
+/** react-grab passes the map's raw `sources` entry, which vite writes relative to the module's dir */
+function mapSourcePath(source, moduleFile) {
+	let path = source;
+	try {
+		path = decodeURIComponent(source);
+	} catch {}
+	return isAbsolute(path) ? path : resolve(dirname(moduleFile), path);
+}
+const LOOPBACK_ADDRESSES = /* @__PURE__ */ new Set([
+	"127.0.0.1",
+	"::1",
+	"::ffff:127.0.0.1"
+]);
+const FORWARDING_HEADERS = [
+	"forwarded",
+	"x-forwarded-for",
+	"x-real-ip",
+	"cf-connecting-ip"
+];
+function isLoopback(address) {
+	return address !== void 0 && LOOPBACK_ADDRESSES.has(address);
+}
+/**
+* vite's default cors admits every localhost origin, so another local page could read
+* the token from the loader; only the page's own origin may post
+*/
+function isSameOrigin(req) {
+	const site = req.headers["sec-fetch-site"];
+	if (site !== void 0) return site === "same-origin";
+	const { origin, host } = req.headers;
+	if (origin === void 0 || host === void 0) return false;
+	try {
+		return new URL(origin).host === host;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { AgentNotConnectedError, claudeSession, tippa };