@dorsk/yubisashi 0.1.0

package/src/cli.ts

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+import { type ChildProcess, execFileSync, spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import {
+	appendFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { formatAnnotation } from './format.ts';
+import { PREFIX, startServer } from './server.ts';
+import { type Annotation, Store } from './store.ts';
+import { Transcript } from './transcript.ts';
+
+const DIR = '.yubisashi';
+
+type ServerInfo = { url: string; shellUrl: string; token: string; pid: number; cwd: string };
+
+const HELP = `yubi — point at your running app, comment, and hand it to your coding agent
+
+  yubi up [--target URL] [--port N] [--host H] [--session ID] [-- <dev command>]
+      Start <dev command> (optional), proxy --target (default http://localhost:5173) and serve
+      the review shell at /__yubi/. Binds 127.0.0.1:4780 by default.
+  yubi wait [--timeout SECONDS]      Block until the user sends messages, print them, exit 0.
+  yubi reply <id> <text>             Answer in the comment thread.
+  yubi resolve <id> [text]           Close a comment with a summary of the change.
+  yubi dismiss <id> <reason>         Close a comment without acting on it.
+  yubi list [--all]                  Show open (or all) comments.
+  yubi url                           Print the shell URL.
+
+Agent loop: run \`yubi up\` and \`yubi wait\` as background commands. When wait exits the user has
+commented; act, answer with reply/resolve, then start \`yubi wait\` in the background again.`;
+
+function fail(message: string, code = 1): never {
+	process.stderr.write(`yubi: ${message}\n`);
+	process.exit(code);
+}
+
+function findInfo(): ServerInfo {
+	const explicit = process.env.YUBI_DIR;
+	let dir = resolve(process.cwd());
+	for (;;) {
+		const file = explicit ? join(explicit, 'server.json') : join(dir, DIR, 'server.json');
+		if (existsSync(file)) return JSON.parse(readFileSync(file, 'utf8'));
+		const parent = dirname(dir);
+		if (explicit || parent === dir) fail('no running server found; start one with `yubi up`');
+		dir = parent;
+	}
+}
+
+async function call<T>(
+	info: ServerInfo,
+	path: string,
+	init: RequestInit = {},
+): Promise<Response & { data?: T }> {
+	let res: Response;
+	try {
+		res = await fetch(`${info.url}${PREFIX}/api${path}`, {
+			...init,
+			headers: { 'content-type': 'application/json', 'x-yubi-token': info.token },
+		});
+	} catch {
+		fail(`server at ${info.url} is not responding; is \`yubi up\` still running?`);
+	}
+	if (res.status >= 400) fail(`${path}: ${res.status} ${await res.text()}`);
+	return res;
+}
+
+function excludeFromGit(cwd: string) {
+	try {
+		const exclude = execFileSync('git', ['rev-parse', '--git-path', 'info/exclude'], {
+			cwd,
+			encoding: 'utf8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		}).trim();
+		const path = resolve(cwd, exclude);
+		const current = existsSync(path) ? readFileSync(path, 'utf8') : '';
+		if (!current.split('\n').includes(`${DIR}/`)) {
+			mkdirSync(dirname(path), { recursive: true });
+			appendFileSync(path, `${current && !current.endsWith('\n') ? '\n' : ''}${DIR}/\n`);
+		}
+	} catch {
+		// not a git checkout
+	}
+}
+
+async function reachable(url: URL): Promise<boolean> {
+	try {
+		await fetch(url, { signal: AbortSignal.timeout(2000) });
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function up(argv: string[]) {
+	const split = argv.indexOf('--');
+	const command = split >= 0 ? argv.slice(split + 1) : [];
+	const { values } = parseArgs({
+		args: split >= 0 ? argv.slice(0, split) : argv,
+		options: {
+			target: { type: 'string', default: 'http://localhost:5173' },
+			port: { type: 'string', default: '4780' },
+			host: { type: 'string', default: '127.0.0.1' },
+			session: { type: 'string' },
+		},
+	});
+	const cwd = process.cwd();
+	const dir = join(cwd, DIR);
+	mkdirSync(dir, { recursive: true });
+	excludeFromGit(cwd);
+
+	const tokenFile = join(dir, 'token');
+	if (!existsSync(tokenFile))
+		writeFileSync(tokenFile, randomBytes(18).toString('base64url'), { mode: 0o600 });
+	const token = readFileSync(tokenFile, 'utf8').trim();
+
+	const sessionId = values.session ?? process.env.CLAUDE_CODE_SESSION_ID;
+	const transcript = sessionId && sessionId !== 'none' ? new Transcript(sessionId) : undefined;
+	const target = new URL(values.target);
+
+	let child: ChildProcess | undefined;
+	if (command.length) {
+		const [cmd, ...args] = command as [string, ...string[]];
+		child = spawn(cmd, args, { cwd, stdio: ['ignore', 'inherit', 'inherit'], detached: true });
+		child.on('exit', (code) => shutdown(code ?? 1));
+	}
+
+	const running = await startServer({
+		target,
+		store: new Store(join(dir, 'annotations.json')),
+		token,
+		transcript,
+		host: values.host,
+		port: Number(values.port),
+	}).catch((err: Error) => {
+		child?.pid && process.kill(-child.pid, 'SIGTERM');
+		fail(`cannot listen on ${values.host}:${values.port}: ${err.message}`);
+	});
+
+	const infoFile = join(dir, 'server.json');
+	const info: ServerInfo = {
+		url: running.url,
+		shellUrl: running.shellUrl,
+		token,
+		pid: process.pid,
+		cwd,
+	};
+	writeFileSync(infoFile, JSON.stringify(info, null, '\t'), { mode: 0o600 });
+
+	let stopping = false;
+	async function shutdown(code: number) {
+		if (stopping) return;
+		stopping = true;
+		if (child?.pid && child.exitCode === null) {
+			try {
+				process.kill(-child.pid, 'SIGTERM');
+			} catch {
+				// already gone
+			}
+		}
+		transcript?.close();
+		rmSync(infoFile, { force: true });
+		await running.close();
+		process.exit(code);
+	}
+	process.on('SIGINT', () => shutdown(130));
+	process.on('SIGTERM', () => shutdown(143));
+
+	for (let i = 0; i < 240 && !(await reachable(target)); i++) {
+		if (i === 0) console.log(`yubi: waiting for ${target.origin}…`);
+		await new Promise((r) => setTimeout(r, 500));
+	}
+	console.log(
+		[
+			'',
+			`yubi: open ${running.shellUrl}`,
+			`      proxying ${target.origin}${transcript ? `, following Claude session ${transcript.sessionId}` : ''}`,
+			'      agent: run `yubi wait` in the background to receive comments',
+			'',
+		].join('\n'),
+	);
+}
+
+async function wait(argv: string[]) {
+	const { values } = parseArgs({
+		args: argv,
+		options: { timeout: { type: 'string', default: '0' } },
+	});
+	const info = findInfo();
+	const limit = Number(values.timeout) * 1000;
+	const start = Date.now();
+	while (!limit || Date.now() - start < limit) {
+		const left = limit ? Math.ceil((limit - (Date.now() - start)) / 1000) : 240;
+		const res = await call(info, `/wait?timeout=${Math.max(1, Math.min(240, left))}`);
+		if (res.status === 200) {
+			const body = (await res.json()) as { text: string };
+			console.log(body.text);
+			return;
+		}
+	}
+	fail('no messages before --timeout', 2);
+}
+
+async function post(id: string | undefined, text: string, status?: string) {
+	if (!id || !/^\d+$/.test(id)) fail('expected a comment id');
+	const info = findInfo();
+	const res = await call(info, `/annotations/${id}/messages`, {
+		method: 'POST',
+		body: JSON.stringify({ from: 'agent', text, status }),
+	});
+	const a = (await res.json()) as Annotation;
+	console.log(`#${a.id} ${a.status}`);
+}
+
+async function list(argv: string[]) {
+	const { values } = parseArgs({
+		args: argv,
+		options: { all: { type: 'boolean', default: false } },
+	});
+	const info = findInfo();
+	const res = await call(info, '/state');
+	const { annotations } = (await res.json()) as { annotations: Annotation[] };
+	const shown = annotations.filter((a) => values.all || a.status === 'open');
+	if (!shown.length) return console.log(values.all ? 'no comments yet' : 'no open comments');
+	for (const a of shown) console.log(`[${a.status}] ${formatAnnotation({ ...a, delivered: 0 })}\n`);
+}
+
+const [command, ...rest] = process.argv.slice(2);
+switch (command) {
+	case 'up':
+		await up(rest);
+		break;
+	case 'wait':
+		await wait(rest);
+		break;
+	case 'reply':
+		await post(rest[0], rest.slice(1).join(' ') || fail('reply needs text'));
+		break;
+	case 'resolve':
+		await post(rest[0], rest.slice(1).join(' '), 'resolved');
+		break;
+	case 'dismiss':
+		await post(rest[0], rest.slice(1).join(' ') || fail('dismiss needs a reason'), 'dismissed');
+		break;
+	case 'list':
+		await list(rest);
+		break;
+	case 'url':
+		console.log(findInfo().shellUrl);
+		break;
+	default:
+		console.log(HELP);
+		if (command && command !== 'help' && command !== '--help') process.exit(1);
+}

package/src/format.ts

@@ -0,0 +1,43 @@
+import type { Annotation, Frame, Target } from './store.ts';
+
+const loc = (f: { file?: string; line?: number; column?: number }) =>
+	f.file ? `${f.file}${f.line ? `:${f.line}` : ''}${f.column ? `:${f.column}` : ''}` : '';
+
+const frame = (f: Frame) => [f.name ?? f.type, loc(f)].filter(Boolean).join(' ');
+
+function target(t: Target, i: number): string {
+	const label = `<${t.tag}>${t.text ? ` "${t.text}"` : ''}`;
+	const lines = [`- target ${i + 1}: ${label}`];
+	if (t.source) lines.push(`  source: ${loc(t.source)}`);
+	if (t.stack.length) lines.push(`  rendered by: ${t.stack.map(frame).join(' ← ')}`);
+	lines.push(`  selector: ${t.selector}`);
+	lines.push(`  html: ${t.html.replace(/\s+/g, ' ')}`);
+	return lines.join('\n');
+}
+
+export function formatAnnotation(a: Annotation): string {
+	const fresh = a.thread.slice(a.delivered);
+	const earlier = a.thread.slice(0, a.delivered);
+	const head = `## #${a.id} on ${a.route} (viewport ${a.viewport.width}x${a.viewport.height})`;
+	const out = [head];
+	if (earlier.length) {
+		out.push('Earlier in this thread:');
+		for (const m of earlier) out.push(`  ${m.from}: ${m.text}`);
+	}
+	for (const m of fresh) {
+		out.push(m.from === 'user' ? `> ${m.text.split('\n').join('\n> ')}` : `  agent: ${m.text}`);
+	}
+	out.push(a.targets.length ? a.targets.map(target).join('\n') : '(general message, no element)');
+	return out.join('\n');
+}
+
+export function formatDelivery(items: Annotation[], shellUrl: string): string {
+	return [
+		`yubisashi: ${items.length} new message${items.length === 1 ? '' : 's'} from ${shellUrl}`,
+		'',
+		items.map(formatAnnotation).join('\n\n'),
+		'',
+		'Answer in the browser: yubi reply <id> "…"   close it: yubi resolve <id> "what changed"',
+		'Then run `yubi wait` in the background again to keep listening.',
+	].join('\n');
+}

package/src/proxy.ts

@@ -0,0 +1,89 @@
+import { type IncomingMessage, request, type ServerResponse } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { connect, type Socket } from 'node:net';
+import type { Duplex } from 'node:stream';
+import { connect as tlsConnect } from 'node:tls';
+
+/** Makes the proxied app look same-origin to itself and embeddable in the shell iframe. */
+function rewriteRequestHeaders(req: IncomingMessage, target: URL, self: string) {
+	const headers = { ...req.headers, host: target.host };
+	if (headers.origin === self) headers.origin = target.origin;
+	if (typeof headers.referer === 'string' && headers.referer.startsWith(self)) {
+		headers.referer = target.origin + headers.referer.slice(self.length);
+	}
+	return headers;
+}
+
+function rewriteResponseHeaders(headers: IncomingMessage['headers'], target: URL, self: string) {
+	const out = { ...headers };
+	delete out['x-frame-options'];
+	const csp = out['content-security-policy'];
+	if (typeof csp === 'string') {
+		out['content-security-policy'] = csp
+			.split(';')
+			.filter((d) => !d.trim().startsWith('frame-ancestors'))
+			.join(';');
+	}
+	if (typeof out.location === 'string' && out.location.startsWith(target.origin)) {
+		out.location = self + out.location.slice(target.origin.length);
+	}
+	return out;
+}
+
+export function proxyHttp(req: IncomingMessage, res: ServerResponse, target: URL, self: string) {
+	const send = target.protocol === 'https:' ? httpsRequest : request;
+	const upstream = send(
+		{
+			protocol: target.protocol,
+			hostname: target.hostname,
+			port: target.port,
+			method: req.method,
+			path: req.url,
+			headers: rewriteRequestHeaders(req, target, self),
+			rejectUnauthorized: false,
+		},
+		(up) => {
+			res.writeHead(up.statusCode ?? 502, rewriteResponseHeaders(up.headers, target, self));
+			up.pipe(res);
+		},
+	);
+	upstream.on('error', (err) => {
+		if (!res.headersSent) res.writeHead(502, { 'content-type': 'text/plain' });
+		res.end(`yubisashi: ${target.origin} is not reachable (${err.message})`);
+	});
+	req.pipe(upstream);
+}
+
+export function proxyUpgrade(
+	req: IncomingMessage,
+	client: Duplex,
+	head: Buffer,
+	target: URL,
+	self: string,
+) {
+	const port = Number(target.port || (target.protocol === 'https:' ? 443 : 80));
+	const upstream: Socket =
+		target.protocol === 'https:'
+			? tlsConnect({ host: target.hostname, port, rejectUnauthorized: false })
+			: connect(port, target.hostname);
+	const ready = target.protocol === 'https:' ? 'secureConnect' : 'connect';
+	upstream.once(ready, () => {
+		const headers = rewriteRequestHeaders(req, target, self);
+		const lines = [`${req.method} ${req.url} HTTP/1.1`];
+		for (const [key, value] of Object.entries(headers)) {
+			for (const v of Array.isArray(value) ? value : [value])
+				if (v !== undefined) lines.push(`${key}: ${v}`);
+		}
+		upstream.write(`${lines.join('\r\n')}\r\n\r\n`);
+		if (head.length) upstream.write(head);
+		upstream.pipe(client).pipe(upstream);
+	});
+	const close = () => {
+		upstream.destroy();
+		client.destroy();
+	};
+	for (const socket of [upstream, client]) {
+		socket.on('error', close);
+		socket.on('close', close);
+	}
+}

package/src/server.ts

@@ -0,0 +1,245 @@
+import { timingSafeEqual } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { extname } from 'node:path';
+import type { Duplex } from 'node:stream';
+import { formatDelivery } from './format.ts';
+import { proxyHttp, proxyUpgrade } from './proxy.ts';
+import type { Annotation, NewAnnotation, Status, Store } from './store.ts';
+import type { Transcript } from './transcript.ts';
+
+export const PREFIX = '/__yubi';
+
+export type Options = {
+	target: URL;
+	store: Store;
+	token: string;
+	transcript?: Transcript;
+	host?: string;
+	port?: number;
+	/** How long to keep collecting messages after the first one before waking the agent. */
+	batchMs?: number;
+};
+
+export type Running = { server: Server; url: string; shellUrl: string; close: () => Promise<void> };
+
+const SHELL = new URL('../shell/', import.meta.url);
+const MIME: Record<string, string> = {
+	'.html': 'text/html; charset=utf-8',
+	'.js': 'text/javascript; charset=utf-8',
+	'.css': 'text/css; charset=utf-8',
+};
+const STATUSES: Status[] = ['open', 'resolved', 'dismissed'];
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+function json(res: ServerResponse, status: number, body: unknown) {
+	res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+	res.end(JSON.stringify(body));
+}
+
+async function readJson<T>(req: IncomingMessage): Promise<T> {
+	let size = 0;
+	const chunks: Buffer[] = [];
+	for await (const chunk of req) {
+		size += chunk.length;
+		if (size > 2_000_000) throw new Error('body too large');
+		chunks.push(chunk);
+	}
+	return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+
+export async function startServer(opts: Options): Promise<Running> {
+	const { store, target, transcript } = opts;
+	const batchMs = opts.batchMs ?? 1500;
+	const expected = Buffer.from(opts.token);
+	const streams = new Set<ServerResponse>();
+	let waiters = 0;
+	let shellBase = '';
+
+	const authorized = (req: IncomingMessage, url: URL) => {
+		const given = Buffer.from(
+			String(req.headers['x-yubi-token'] ?? url.searchParams.get('token') ?? ''),
+		);
+		return given.length === expected.length && timingSafeEqual(given, expected);
+	};
+
+	const broadcast = (event: string, data: unknown) => {
+		const frame = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+		for (const res of streams) res.write(frame);
+	};
+	const setWaiters = (delta: number) => {
+		waiters += delta;
+		broadcast('listening', waiters > 0);
+	};
+	store.subscribe((items) => broadcast('annotations', items));
+	transcript?.subscribe((entries) => broadcast('transcript', entries));
+
+	async function waitForMessages(
+		res: ServerResponse,
+		timeoutMs: number,
+	): Promise<{ items: Annotation[]; text: string } | undefined> {
+		let gone = false;
+		res.once('close', () => {
+			gone = true;
+		});
+		const deadline = Date.now() + timeoutMs;
+		while (!gone && Date.now() < deadline) {
+			if (store.undelivered().length) {
+				await sleep(batchMs);
+				const items = store.undelivered();
+				if (gone || !items.length) continue;
+				const text = formatDelivery(items, shellBase);
+				store.markDelivered(items);
+				return { items, text };
+			}
+			await new Promise<void>((resolve) => {
+				const done = () => {
+					off();
+					clearTimeout(timer);
+					res.off('close', done);
+					resolve();
+				};
+				const off = store.subscribe(() => store.undelivered().length && done());
+				const timer = setTimeout(done, Math.max(0, deadline - Date.now()));
+				res.once('close', done);
+			});
+		}
+		return undefined;
+	}
+
+	async function api(req: IncomingMessage, res: ServerResponse, url: URL, path: string) {
+		if (!authorized(req, url)) return json(res, 401, { error: 'bad or missing token' });
+
+		if (req.method === 'GET' && path === '/state') {
+			return json(res, 200, {
+				target: target.origin,
+				session: transcript ? { id: transcript.sessionId, file: transcript.file } : null,
+				listening: waiters > 0,
+				annotations: store.all(),
+				transcript: transcript?.entries() ?? [],
+			});
+		}
+
+		if (req.method === 'GET' && path === '/events') {
+			res.writeHead(200, {
+				'content-type': 'text/event-stream',
+				'cache-control': 'no-store',
+				connection: 'keep-alive',
+			});
+			res.write(`event: listening\ndata: ${waiters > 0}\n\n`);
+			streams.add(res);
+			const ping = setInterval(() => res.write(': ping\n\n'), 20_000);
+			req.once('close', () => {
+				clearInterval(ping);
+				streams.delete(res);
+			});
+			return;
+		}
+
+		if (req.method === 'GET' && path === '/wait') {
+			const timeoutMs = Math.min(Number(url.searchParams.get('timeout') ?? 240), 280) * 1000;
+			setWaiters(1);
+			try {
+				const delivery = await waitForMessages(res, timeoutMs);
+				if (!delivery) {
+					res.writeHead(204).end();
+					return;
+				}
+				return json(res, 200, delivery);
+			} finally {
+				setWaiters(-1);
+			}
+		}
+
+		if (req.method === 'POST' && path === '/annotations') {
+			const body = await readJson<NewAnnotation>(req);
+			if (!body.comment?.trim()) return json(res, 400, { error: 'comment is required' });
+			return json(
+				res,
+				201,
+				store.add({
+					comment: body.comment.trim(),
+					route: body.route ?? '/',
+					viewport: body.viewport ?? { width: 0, height: 0 },
+					targets: body.targets ?? [],
+				}),
+			);
+		}
+
+		const reply = path.match(/^\/annotations\/(\d+)\/messages$/);
+		if (req.method === 'POST' && reply) {
+			const body = await readJson<{ text?: string; from?: 'user' | 'agent'; status?: Status }>(req);
+			if (body.status && !STATUSES.includes(body.status)) {
+				return json(res, 400, { error: `status must be one of ${STATUSES.join(', ')}` });
+			}
+			try {
+				const from = body.from === 'agent' ? 'agent' : 'user';
+				return json(
+					res,
+					200,
+					store.post(Number(reply[1]), from, body.text?.trim() ?? '', body.status),
+				);
+			} catch (err) {
+				return json(res, 404, { error: (err as Error).message });
+			}
+		}
+
+		return json(res, 404, { error: `no route ${req.method} ${path}` });
+	}
+
+	async function shell(res: ServerResponse, path: string) {
+		const name = path === '/' || path === '' ? 'index.html' : path.slice(1);
+		if (!/^[\w.-]+$/.test(name)) return json(res, 404, { error: 'not found' });
+		try {
+			const body = await readFile(new URL(name, SHELL));
+			res.writeHead(200, {
+				'content-type': MIME[extname(name)] ?? 'application/octet-stream',
+				'cache-control': 'no-store',
+			});
+			res.end(body);
+		} catch {
+			json(res, 404, { error: 'not found' });
+		}
+	}
+
+	const server = createServer((req, res) => {
+		const url = new URL(req.url ?? '/', 'http://local');
+		const self = `http://${req.headers.host}`;
+		if (!url.pathname.startsWith(PREFIX)) return proxyHttp(req, res, target, self);
+		const rest = url.pathname.slice(PREFIX.length);
+		const handle = rest.startsWith('/api/') ? api(req, res, url, rest.slice(4)) : shell(res, rest);
+		handle.catch((err: Error) => {
+			if (!res.headersSent) json(res, 500, { error: err.message });
+			else res.end();
+		});
+	});
+	const sockets = new Set<Duplex>();
+	server.on('connection', (socket) => {
+		sockets.add(socket);
+		socket.once('close', () => sockets.delete(socket));
+	});
+	server.on('upgrade', (req, socket, head) =>
+		proxyUpgrade(req, socket, head, target, `http://${req.headers.host}`),
+	);
+
+	await new Promise<void>((resolve, reject) => {
+		server.once('error', reject);
+		server.listen(opts.port ?? 0, opts.host ?? '127.0.0.1', resolve);
+	});
+	const { port } = server.address() as AddressInfo;
+	const host = opts.host && opts.host !== '0.0.0.0' && opts.host !== '::' ? opts.host : '127.0.0.1';
+	const url = `http://${host.includes(':') ? `[${host}]` : host}:${port}`;
+	shellBase = `${url}${PREFIX}/`;
+
+	return {
+		server,
+		url,
+		shellUrl: `${shellBase}#token=${opts.token}`,
+		close: () =>
+			new Promise<void>((resolve) => {
+				server.close(() => resolve());
+				for (const socket of sockets) socket.destroy();
+			}),
+	};
+}