tippa 0.1.0

package/dist/http-BcWR4_RM.mjs

@@ -0,0 +1,159 @@
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { readFileSync, readdirSync, rmSync } from "node:fs";
+import { createHash, timingSafeEqual } from "node:crypto";
+//#region src/channel/discovery.ts
+/** `.tippa/channel.json`: where the plugin finds the helper */
+const discoverySchema = z.object({
+	port: z.number().int().positive(),
+	secret: z.string().min(1),
+	pid: z.number().int().positive()
+});
+/** `<cwd>/.tippa`, the helper's state: discovery file and screenshots */
+function stateDir(cwd) {
+	return join(cwd, ".tippa");
+}
+function discoveryPath(cwd) {
+	return join(stateDir(cwd), "channel.json");
+}
+/** creates the state dir if it's gone, ignored by the app's git: it holds a live secret */
+async function prepareStateDir(cwd) {
+	await mkdir(stateDir(cwd), { recursive: true });
+	await writeFile(join(stateDir(cwd), ".gitignore"), "*\n");
+}
+async function writeDiscovery(cwd, discovery) {
+	const path = discoveryPath(cwd);
+	await prepareStateDir(cwd);
+	const tmp = `${path}.${discovery.pid}.tmp`;
+	await writeFile(tmp, JSON.stringify(discovery), { mode: 384 });
+	await rename(tmp, path);
+}
+/**
+* removes the file only while it still holds `secret`: a second helper started
+* in the same project overwrites it, and its file must outlive this one.
+*/
+function removeDiscovery(cwd, secret) {
+	const path = discoveryPath(cwd);
+	try {
+		if (JSON.parse(readFileSync(path, "utf8"))?.secret === secret) rmSync(path, { force: true });
+	} catch {}
+}
+function isAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+}
+/** `shots-<pid>-<random>`: the pid lets a later helper remove what a killed one left */
+function screenshotDirName(pid, random) {
+	return `shots-${pid}-${random}`;
+}
+/** removes screenshot dirs whose helper is gone without cleaning up (SIGKILL, crash) */
+function removeOrphanedScreenshots(cwd) {
+	let entries;
+	try {
+		entries = readdirSync(stateDir(cwd));
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		const pid = Number(/^shots-(\d+)-/.exec(entry)?.[1]);
+		if (pid > 0 && !isAlive(pid)) rmSync(join(stateDir(cwd), entry), {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+//#region src/protocol.ts
+/** the dev server and the channel helper refuse a pick body past this */
+const MAX_BODY_BYTES = 10485760;
+/**
+* base64 chars each element's screenshot may take: a full pick's screenshots together
+* leave room in the body for the html and the json around them
+*/
+const MAX_SCREENSHOT_CHARS = Math.floor(8388608 / 5);
+/** base64 of the 8-byte png signature and the ihdr length's leading zero bits */
+const PNG_BASE64_PREFIX = "iVBORw0KGgo";
+const REPLY_EVENT = "tippa:reply";
+const STATUS_EVENT = "tippa:status";
+/** sent by the loader right after `start` returns; answered with `tippa:status` to that client only */
+const STATUS_REQUEST_EVENT = "tippa:status-request";
+//#endregion
+//#region src/schema.ts
+/** the dev server keeps this many leading chars of a pick's html */
+const MAX_HTML_CHARS = 4e3;
+const MAX_MODULE_URL_CHARS = 2048;
+const pickIdSchema = z.string().regex(/^[A-Za-z0-9_-]{1,64}$/);
+/** base64 png; checked by prefix, so it holds in the browser as well as node */
+const pngBase64Schema = z.base64().max(MAX_SCREENSHOT_CHARS).refine((value) => value.startsWith(PNG_BASE64_PREFIX), "not a png");
+/** one picked element of a pick */
+const pickElementSchema = z.object({
+	component: z.string(),
+	/**
+	* as the client posts it, react-grab's source: the sourcemap's `sources` entry, relative to
+	* {@link moduleUrl}'s directory; as an agent receives it, an absolute path
+	*/
+	file: z.string(),
+	line: z.number().int().positive(),
+	column: z.number().int().positive().optional(),
+	/**
+	* the served module the component came from, as the browser loaded it: an absolute
+	* same-origin url or a root-relative path, e.g. `http://localhost:5173/src/ui/Button.tsx?t=1`
+	* or `/@fs/abs/Button.tsx`; without it, `file` is read as a vite url
+	*/
+	moduleUrl: z.string().max(MAX_MODULE_URL_CHARS).optional(),
+	/** the dev server keeps the first {@link MAX_HTML_CHARS} */
+	html: z.string(),
+	/** base64 png of the picked element */
+	screenshot: pngBase64Schema.optional()
+});
+/** what the browser client posts to the dev server for one pick */
+const pickRequestSchema = z.object({
+	pickId: pickIdSchema,
+	/** refers to `elements[i]` by the literal marker `[i + 1]` */
+	note: z.string(),
+	elements: z.array(pickElementSchema).min(1).max(5)
+});
+/** what an agent reports back about a pick, sent to the page as the `tippa:reply` hmr event */
+const pickReplySchema = z.object({
+	pickId: z.string(),
+	status: z.enum([
+		"working",
+		"done",
+		"question"
+	]),
+	message: z.string()
+});
+//#endregion
+//#region src/http.ts
+/** constant-time check of a shared-secret request header */
+function hasSecretHeader(req, header, secret) {
+	const given = req.headers[header];
+	if (typeof given !== "string") return false;
+	const digest = (value) => createHash("sha256").update(value).digest();
+	return timingSafeEqual(digest(given), digest(secret));
+}
+function sendJson(res, status, body) {
+	res.writeHead(status, { "content-type": "application/json" });
+	res.end(JSON.stringify(body));
+}
+/** resolves undefined once the body passes `limit`, after draining the rest */
+async function readBody(req, limit) {
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of req) {
+		size += chunk.length;
+		if (size <= limit) chunks.push(chunk);
+	}
+	return size > limit ? void 0 : Buffer.concat(chunks).toString("utf8");
+}
+/** the browser went away mid-request: nothing to answer and nothing to report */
+function isClientAbort(req) {
+	return req.destroyed && !req.complete;
+}
+//#endregion
+export { removeDiscovery as _, MAX_HTML_CHARS as a, stateDir as b, pickRequestSchema as c, STATUS_EVENT as d, STATUS_REQUEST_EVENT as f, prepareStateDir as g, isAlive as h, sendJson as i, MAX_BODY_BYTES as l, discoverySchema as m, isClientAbort as n, pickIdSchema as o, discoveryPath as p, readBody as r, pickReplySchema as s, hasSecretHeader as t, REPLY_EVENT as u, removeOrphanedScreenshots as v, writeDiscovery as x, screenshotDirName as y };

package/dist/index.d.mts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { Logger, Plugin } from "vite";
+//#region src/schema.d.ts
+/** one picked element of a pick */
+declare const pickElementSchema: z.ZodObject<{
+  component: z.ZodString;
+  file: z.ZodString;
+  line: z.ZodNumber;
+  column: z.ZodOptional<z.ZodNumber>;
+  moduleUrl: z.ZodOptional<z.ZodString>;
+  html: z.ZodString;
+  screenshot: z.ZodOptional<z.ZodBase64>;
+}, z.core.$strip>;
+/** what the browser client posts to the dev server for one pick */
+declare const pickRequestSchema: z.ZodObject<{
+  pickId: z.ZodString;
+  note: z.ZodString;
+  elements: z.ZodArray<z.ZodObject<{
+    component: z.ZodString;
+    file: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodOptional<z.ZodNumber>;
+    moduleUrl: z.ZodOptional<z.ZodString>;
+    html: z.ZodString;
+    screenshot: z.ZodOptional<z.ZodBase64>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/** what an agent reports back about a pick, sent to the page as the `tippa:reply` hmr event */
+declare const pickReplySchema: z.ZodObject<{
+  pickId: z.ZodString;
+  status: z.ZodEnum<{
+    done: "done";
+    question: "question";
+    working: "working";
+  }>;
+  message: z.ZodString;
+}, z.core.$strip>;
+//#endregion
+//#region src/protocol.d.ts
+/** see `pickRequestSchema` */
+type PickRequest = z.output<typeof pickRequestSchema>;
+/** see `pickElementSchema` */
+type PickElement = z.output<typeof pickElementSchema>;
+/** payload of the `tippa:reply` hmr event */
+type PickReply = z.output<typeof pickReplySchema>;
+type AgentStatus = "connected" | "waiting";
+/** payload of the `tippa:status` hmr event */
+interface StatusEvent {
+  status: AgentStatus;
+}
+//#endregion
+//#region src/agent.d.ts
+/** how tippa reaches a coding agent; `claudeSession()` is one */
+interface AgentAdapter {
+  /** shown in the status line: `tippa → connected to <label>` */
+  label: string;
+  connect(context: AgentContext): AgentConnection;
+}
+interface AgentContext {
+  /** vite's resolved root */
+  root: string;
+  logger: Logger;
+}
+interface AgentConnection {
+  readonly status: AgentStatus;
+  /** called after the first connection check, then once per change */
+  onStatus(listener: (status: AgentStatus) => void): void;
+  onReply(listener: (reply: PickReply) => void): void;
+  /** rejects with `AgentNotConnectedError` when disconnected, any other error when the agent refuses */
+  send(pick: PickRequest): Promise<void>;
+  close(): Promise<void>;
+}
+/** what `send` rejects with when no agent is reachable; the endpoint answers 503 */
+export declare class AgentNotConnectedError extends Error {
+  constructor(label: string);
+}
+//#endregion
+//#region src/claude-session.d.ts
+/**
+ * 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.
+ */
+export declare function claudeSession(): AgentAdapter;
+//#endregion
+//#region src/plugin.d.ts
+interface TippaOptions {
+  /** the agent picks are sent to, e.g. `claudeSession()` */
+  agent: AgentAdapter;
+  /** pick hotkey passed to the browser client; defaults to react-grab's */
+  key?: string;
+}
+export declare function tippa(options: TippaOptions): Plugin;
+//#endregion
+export type { AgentAdapter, AgentConnection, AgentContext, AgentStatus, PickElement, PickReply, PickRequest, StatusEvent, TippaOptions };