pk-annotator 0.6.2 → 0.8.0

package/dist/vite.mjs

@@ -1,7 +1,8 @@
-import { A as createStore, B as Id, C as agentsDir, D as MissingAnnotationError, H as State, I as resolveInside, L as AnnotationDraft, M as isErrno, N as listIds, O as PkaError, R as ErrorGroup, T as AgentPresence, U as ThreadEntry, V as RelativePath, b as upsertErrorGroups, d as checkCaptureFiles, f as create, g as loadAnnotationUpdates, k as checkStoreSize, r as RecordingManifestDraft, t as RecordingErrors, w as liveAgents, z as ID_PATTERN } from "./recording-CpEDddkZ.mjs";
+import { A as createStore, B as Id, C as agentsDir, D as MissingAnnotationError, H as State, I as resolveInside, L as AnnotationDraft, M as isErrno, N as listIds, O as PkaError, R as ErrorGroup, T as AgentPresence, U as ThreadEntry, V as RelativePath, b as upsertErrorGroups, d as checkCaptureFiles, f as create, g as loadAnnotationUpdates, k as checkStoreSize, r as RecordingManifestDraft, t as RecordingErrors, w as liveAgents, z as ID_PATTERN } from "./recording-D_Qkyq0N.mjs";
+import { createRequire } from "node:module";
 import { execFile } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { constants, watch } from "node:fs";
+import { constants, readFileSync, watch } from "node:fs";
 import { lstat, mkdir, open, readFile, readdir, realpath, rm, stat } from "node:fs/promises";
 import path, { posix } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -14,6 +15,9 @@ import { TraceMap, originalPositionFor } from "@jridgewell/trace-mapping";
 const CHANNEL = {
 	create: "pka:create",
 	file: "pka:file",
+	uploadReady: "pka:upload-ready",
+	fileWritten: "pka:file-written",
+	cancelUpload: "pka:cancel-upload",
 	errors: "pka:errors",
 	created: "pka:created",
 	createFailed: "pka:create-failed",
@@ -27,7 +31,10 @@ const CHANNEL = {
 	presence: "pka:presence",
 	agent: "pka:agent",
 	setup: "pka:setup",
-	setupInfo: "pka:setup-info"
+	setupInfo: "pka:setup-info",
+	update: "pka:update",
+	installUpdate: "pka:install-update",
+	updateResult: "pka:update-result"
 };
 const MAX_CHUNK_BYTES = 524288;
 const CreateMessage = z.strictObject({
@@ -44,6 +51,7 @@ const FileChunkMessage = z.strictObject({
 	offset: z.number().int().nonnegative(),
 	data: z.base64().max(Math.ceil(MAX_CHUNK_BYTES / 3) * 4)
 });
+const CancelUploadMessage = z.strictObject({ requestId: Id });
 const ErrorsMessage = z.strictObject({ groups: z.array(ErrorGroup).min(1).max(50) });
 const SyncMessage = z.strictObject({ ids: z.array(Id).max(200) });
 const SymbolicateMessage = z.strictObject({
@@ -52,6 +60,17 @@ const SymbolicateMessage = z.strictObject({
 });
 const PresenceMessage = z.strictObject({});
 const SetupMessage = z.strictObject({ requestId: Id });
+const Version = z.string().regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/);
+const InstallUpdateMessage = z.strictObject({
+	requestId: Id,
+	version: Version
+});
+z.strictObject({ requestId: Id });
+z.strictObject({
+	requestId: Id,
+	path: RelativePath,
+	offset: z.number().int().nonnegative()
+});
 z.strictObject({
 	requestId: Id,
 	id: Id,
@@ -97,6 +116,18 @@ z.strictObject({
 	}).nullable(),
 	cause: z.enum(["presence", "change"])
 });
+z.strictObject({
+	current: Version,
+	latest: Version
+});
+z.discriminatedUnion("outcome", [z.strictObject({
+	requestId: Id,
+	outcome: z.enum(["restart", "restart-manually"])
+}), z.strictObject({
+	requestId: Id,
+	outcome: z.literal("failed"),
+	message: z.string()
+})]);
 //#endregion
 //#region src/vite/source.ts
 const ATTRIBUTE = "data-pka-src";
@@ -226,6 +257,213 @@ async function symbolicate(environment, workspaceRoot, stack) {
 	};
 }
 //#endregion
+//#region src/vite/update.ts
+const execFileAsync$1 = promisify(execFile);
+const REGISTRY_LATEST = "https://registry.npmjs.org/pk-annotator/latest";
+const CHECK_TTL_MS = 36e5;
+const INSTALL_TIMEOUT_MS = 3e5;
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+const REGISTRY_SPEC = /^([~^]?)\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const LOCKFILES = [
+	["pnpm-lock.yaml", "pnpm"],
+	["bun.lock", "bun"],
+	["bun.lockb", "bun"],
+	["yarn.lock", "yarn"],
+	["package-lock.json", "npm"]
+];
+const Manifest = z.object({
+	dependencies: z.record(z.string(), z.string()).optional(),
+	devDependencies: z.record(z.string(), z.string()).optional(),
+	packageManager: z.string().optional()
+});
+const Published = z.object({ version: z.string().regex(SEMVER) });
+/** This module's own package.json; a self-reference resolves through its real path. */
+const OWN_MANIFEST = createRequire(import.meta.url).resolve("pk-annotator/package.json");
+const RUNNING = Published.parse(JSON.parse(readFileSync(OWN_MANIFEST, "utf8"))).version;
+function parseVersion(version) {
+	const match = SEMVER.exec(version);
+	if (match === null) throw new Error(`Not a semantic version: ${version}`);
+	return {
+		core: [
+			Number(match[1]),
+			Number(match[2]),
+			Number(match[3])
+		],
+		pre: match[4]
+	};
+}
+/** Whether `candidate` is a later release than `current`; a prerelease never outranks its release. */
+function isNewer(candidate, current) {
+	const next = parseVersion(candidate);
+	const now = parseVersion(current);
+	for (const [index, part] of next.core.entries()) {
+		const other = now.core[index];
+		if (part !== other) return part > other;
+	}
+	return next.pre === void 0 && now.pre !== void 0;
+}
+function installCommand(install, version) {
+	const dev = {
+		pnpm: "--save-dev",
+		npm: "--save-dev",
+		yarn: "--dev",
+		bun: "--dev"
+	}[install.manager];
+	const exact = {
+		pnpm: "--save-exact",
+		npm: "--save-exact",
+		yarn: "--exact",
+		bun: "--exact"
+	}[install.manager];
+	return [
+		install.manager,
+		install.manager === "npm" ? "install" : "add",
+		...install.dev ? [dev] : [],
+		...install.exact ? [exact] : [],
+		`pk-annotator@${version}`
+	];
+}
+async function readManifest(dir) {
+	const file = path.join(dir, "package.json");
+	const text = await readFile(file, "utf8").catch((cause) => {
+		if (isErrno(cause, "ENOENT")) return void 0;
+		throw cause;
+	});
+	if (text === void 0) return void 0;
+	const parsed = Manifest.safeParse(JSON.parse(text));
+	if (!parsed.success) throw new Error(`${file} is not a valid package.json: ${parsed.error.message}`);
+	return parsed.data;
+}
+async function exists(file) {
+	return stat(file).then(() => true, (cause) => {
+		if (isErrno(cause, "ENOENT")) return false;
+		throw cause;
+	});
+}
+/**
+* The manifest that declares pk-annotator, from the Vite root up to the workspace root, and
+* the workspace's package manager. Null when the dependency is not a registry version, for
+* example this repository's fixture or a workspace link.
+*/
+async function findInstall(viteRoot, workspaceRoot) {
+	if (!OWN_MANIFEST.split(path.sep).includes("node_modules")) return null;
+	let declared;
+	for (let dir = path.resolve(viteRoot);; dir = path.dirname(dir)) {
+		const manifest = await readManifest(dir);
+		const dev = manifest?.devDependencies?.["pk-annotator"];
+		const spec = dev ?? manifest?.dependencies?.["pk-annotator"];
+		if (spec !== void 0) {
+			const match = REGISTRY_SPEC.exec(spec);
+			if (match === null) return null;
+			declared = {
+				dir,
+				dev: dev !== void 0,
+				exact: match[1] === ""
+			};
+			break;
+		}
+		if (dir === path.resolve(workspaceRoot) || dir === path.dirname(dir)) return null;
+	}
+	const field = (await readManifest(workspaceRoot))?.packageManager?.split("@")[0];
+	if (field === "pnpm" || field === "npm" || field === "yarn" || field === "bun") return {
+		...declared,
+		manager: field
+	};
+	for (const [lockfile, manager] of LOCKFILES) if (await exists(path.join(workspaceRoot, lockfile))) return {
+		...declared,
+		manager
+	};
+	return null;
+}
+/** The real path of the pk-annotator manifest that `dir` resolves, read fresh from disk. */
+async function resolveInstalled(dir) {
+	for (let from = dir;; from = path.dirname(from)) {
+		const found = await realpath(path.join(from, "node_modules/pk-annotator/package.json")).catch((cause) => {
+			if (isErrno(cause, "ENOENT")) return void 0;
+			throw cause;
+		});
+		if (found !== void 0) return found;
+		if (from === path.dirname(from)) throw new Error(`${dir} resolves no pk-annotator`);
+	}
+}
+/**
+* Checks npm for a newer pk-annotator when a page mounts, at most once an hour, and installs
+* it on request with the workspace's package manager. Nothing runs between those events.
+*/
+function createUpdater(viteRoot, workspaceRoot, warn) {
+	let install;
+	let checked;
+	let installing = false;
+	let staleWarned = false;
+	async function latest() {
+		if (checked === void 0 || Date.now() - checked.at > CHECK_TTL_MS) {
+			const request = fetch(REGISTRY_LATEST, { signal: AbortSignal.timeout(1e4) }).then(async (response) => {
+				if (!response.ok) throw new Error(`${REGISTRY_LATEST} answered ${response.status}`);
+				return Published.parse(await response.json()).version;
+			}).catch((cause) => {
+				warn(`update check failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+				return null;
+			});
+			checked = {
+				at: Date.now(),
+				latest: request
+			};
+		}
+		return checked.latest;
+	}
+	return {
+		/** The update to offer, or null when the installed version is current or not managed by version. */
+		async check() {
+			install ??= findInstall(viteRoot, workspaceRoot);
+			if (await install === null) return null;
+			const onDisk = Published.parse(JSON.parse(await readFile(OWN_MANIFEST, "utf8"))).version;
+			if (onDisk !== RUNNING) {
+				if (!staleWarned) {
+					staleWarned = true;
+					warn(`${onDisk} is installed but ${RUNNING} is running; restart the dev server`);
+				}
+				return null;
+			}
+			const version = await latest();
+			return version !== null && isNewer(version, RUNNING) ? {
+				current: RUNNING,
+				latest: version
+			} : null;
+		},
+		/**
+		* Installs `version`, which must be the release the last check offered. "restart" means a
+		* dev server restart loads it; "restart-manually" means the package was replaced in place,
+		* where Node keeps the old plugin module until the process restarts.
+		*/
+		async install(version) {
+			const target = await install;
+			if (target === void 0 || target === null) throw new Error("This workspace does not install pk-annotator from the npm registry");
+			if (checked === void 0 || await checked.latest !== version) throw new Error(`${version} is not the release last offered`);
+			if (installing) throw new Error("An update is already installing");
+			installing = true;
+			try {
+				const [command, ...args] = installCommand(target, version);
+				try {
+					await execFileAsync$1(command, args, {
+						cwd: target.dir,
+						timeout: INSTALL_TIMEOUT_MS
+					});
+				} catch (cause) {
+					const stderr = cause instanceof Error && "stderr" in cause ? String(cause.stderr).trim() : "";
+					const detail = stderr === "" ? String(cause) : stderr.slice(-600);
+					throw new Error(`${[command, ...args].join(" ")} failed in ${target.dir}: ${detail}`, { cause });
+				}
+				const resolved = await resolveInstalled(target.dir);
+				const installed = Published.parse(JSON.parse(await readFile(resolved, "utf8"))).version;
+				if (installed !== version) throw new Error(`Installed ${version}, but ${target.dir} resolves pk-annotator ${installed}`);
+				return resolved === OWN_MANIFEST ? "restart-manually" : "restart";
+			} finally {
+				installing = false;
+			}
+		}
+	};
+}
+//#endregion
 //#region src/vite/index.ts
 const AnnotatorOptions = z.strictObject({
 	bodies: z.array(z.string().startsWith("/")).optional(),
@@ -240,6 +478,7 @@ const BODIES_GLOBAL = "__PKA_BODIES__";
 const STAGING_DIR = ".staging";
 const MB = 1048576;
 const MAX_RECORDING_JSON_BYTES = 4 * MB;
+const MAX_UPLOADS = 8;
 const execFileAsync = promisify(execFile);
 /** A staging directory named <pid>-<hex> belongs to a running process unless that pid is gone. */
 function ownerAlive(name) {
@@ -369,10 +608,17 @@ async function serve(server, maxStoreBytes, storeRoot) {
 			try {
 				await step();
 			} catch (thrown) {
-				await abort(upload, thrown);
+				if (!upload.done) await abort(upload, thrown);
 			}
 		}).catch((cause) => error(`cleaning up ${upload.requestId} failed: ${describeError(cause)}`));
 	}
+	function cancel(upload, reason) {
+		if (upload.done) return;
+		upload.done = true;
+		upload.queue = upload.queue.then(async () => {
+			if (uploads.get(upload.requestId) === upload) await abort(upload, reason);
+		}).catch((cause) => error(`upload cleanup failed: ${describeError(cause)}`));
+	}
 	/** Replaces the page's raw stack and top frame with source positions. */
 	async function symbolicateGroup(group) {
 		const { topFrame: _pageTopFrame, ...rest } = group;
@@ -419,7 +665,11 @@ async function serve(server, maxStoreBytes, storeRoot) {
 	}
 	async function finish(upload) {
 		const recordingDirectories = new Set(upload.draft.attachments.filter((attachment) => attachment.kind === "recording").map((attachment) => path.posix.dirname(attachment.path)));
-		for (const directory of recordingDirectories) await completeRecording(upload, directory);
+		for (const directory of recordingDirectories) {
+			await completeRecording(upload, directory);
+			if (upload.done) return;
+		}
+		if (upload.done) return;
 		const { id } = await create(store, upload.draft, {
 			dir: upload.dir,
 			paths: [...upload.files.keys()]
@@ -468,6 +718,10 @@ async function serve(server, maxStoreBytes, storeRoot) {
 			refuse(`Request ${requestId} is already in progress`);
 			return;
 		}
+		if (uploads.size >= MAX_UPLOADS || [...uploads.values()].some((upload) => upload.client === client)) {
+			refuse("Another upload is in progress; wait for it to finish and retry");
+			return;
+		}
 		try {
 			checkCaptureFiles(message.draft, message.files.map((file) => file.path));
 		} catch (thrown) {
@@ -487,11 +741,19 @@ async function serve(server, maxStoreBytes, storeRoot) {
 			}])),
 			remaining: declaredBytes,
 			done: false,
+			busy: true,
 			queue: Promise.resolve()
 		};
 		uploads.set(requestId, upload);
-		enqueue(upload, () => prepare(upload, declaredBytes));
-		if (declaredBytes === 0) enqueue(upload, () => finish(upload));
+		enqueue(upload, async () => {
+			await prepare(upload, declaredBytes);
+			if (upload.done) return;
+			if (declaredBytes === 0) await finish(upload);
+			else {
+				upload.busy = false;
+				client.send(CHANNEL.uploadReady, { requestId });
+			}
+		});
 	});
 	listen(CHANNEL.file, FileChunkMessage, async (message, client) => {
 		const upload = uploads.get(message.requestId);
@@ -499,18 +761,36 @@ async function serve(server, maxStoreBytes, storeRoot) {
 			warn(`dropped ${CHANNEL.file}: no upload ${message.requestId} in progress for this page`);
 			return;
 		}
+		if (upload.done) return;
+		if (upload.busy) {
+			cancel(upload, new PkaError("Wait for the upload acknowledgement before sending another chunk; reload the page and retry"));
+			return;
+		}
 		const file = upload.files.get(message.path);
 		const data = Buffer.from(message.data, "base64");
-		if (file === void 0 || message.offset !== file.received || file.received + data.length > file.bytes) {
-			const reason = new PkaError(file === void 0 ? `Chunk for ${message.path}, which the request did not declare` : `Chunk for ${message.path} at offset ${message.offset} does not continue the ${file.received} of ${file.bytes} bytes received`);
-			enqueue(upload, () => Promise.reject(reason));
+		if (file === void 0 || data.length === 0 || message.offset !== file.received || file.received + data.length > file.bytes) {
+			cancel(upload, new PkaError(file === void 0 ? `Chunk for ${message.path}, which the request did not declare` : `Chunk for ${message.path} at offset ${message.offset} does not continue the ${file.received} of ${file.bytes} bytes received`));
 			return;
 		}
 		file.received += data.length;
 		upload.remaining -= data.length;
+		upload.busy = true;
 		const target = resolveInside(upload.dir, message.path);
-		enqueue(upload, () => writeChunk(target, message.offset, data));
-		if (upload.remaining === 0) enqueue(upload, () => finish(upload));
+		enqueue(upload, async () => {
+			await writeChunk(target, message.offset, data);
+			if (upload.done) return;
+			if (upload.remaining !== 0) upload.busy = false;
+			client.send(CHANNEL.fileWritten, {
+				requestId: upload.requestId,
+				path: message.path,
+				offset: file.received
+			});
+			if (upload.remaining === 0) await finish(upload);
+		});
+	});
+	listen(CHANNEL.cancelUpload, CancelUploadMessage, async (message, client) => {
+		const upload = uploads.get(message.requestId);
+		if (upload?.client === client) cancel(upload, new PkaError("The page cancelled the upload"));
 	});
 	listen(CHANNEL.errors, ErrorsMessage, async (message, client) => {
 		const groups = await Promise.all(message.groups.map(symbolicateGroup));
@@ -544,6 +824,27 @@ async function serve(server, maxStoreBytes, storeRoot) {
 		};
 		client.send(CHANNEL.setupInfo, reply);
 	});
+	const updater = createUpdater(server.config.root, workspaceRoot, warn);
+	listen(CHANNEL.installUpdate, InstallUpdateMessage, async (message, client) => {
+		let result;
+		try {
+			const outcome = await updater.install(message.version);
+			result = {
+				requestId: message.requestId,
+				outcome
+			};
+		} catch (cause) {
+			error(`update to ${message.version} failed: ${describeError(cause)}`);
+			result = {
+				requestId: message.requestId,
+				outcome: "failed",
+				message: describeError(cause)
+			};
+		}
+		client.send(CHANNEL.updateResult, result);
+		if (result.outcome === "restart-manually") warn(`updated to ${message.version}; restart the dev server to load it`);
+		if (result.outcome === "restart") await server.restart();
+	});
 	listen(CHANNEL.sync, SyncMessage, async (message, client) => {
 		const synced = { annotations: [] };
 		for (const id of message.ids) try {
@@ -559,7 +860,7 @@ async function serve(server, maxStoreBytes, storeRoot) {
 		client.send(CHANNEL.synced, synced);
 	});
 	const onDisconnect = (_data, client) => {
-		for (const upload of uploads.values()) if (upload.client === client) enqueue(upload, () => Promise.reject(new PkaError("The page disconnected before the upload finished")));
+		for (const upload of uploads.values()) if (upload.client === client) cancel(upload, new PkaError("The page disconnected before the upload finished"));
 	};
 	hot.on("vite:client:disconnect", onDisconnect);
 	listeners.push(["vite:client:disconnect", onDisconnect]);
@@ -592,6 +893,9 @@ async function serve(server, maxStoreBytes, storeRoot) {
 		agentQueue = agentQueue.then(async () => pushAgent(await readAgent())).catch((cause) => error(`reading agent presence failed: ${describeError(cause)}`));
 	}
 	listen(CHANNEL.presence, PresenceMessage, async (_message, client) => {
+		updater.check().then((offer) => {
+			if (offer !== null) client.send(CHANNEL.update, offer);
+		}, (cause) => error(`update check failed: ${describeError(cause)}`));
 		const answered = agentQueue.then(async () => {
 			const agent = await readAgent();
 			pushAgent(agent);
@@ -694,6 +998,7 @@ async function serve(server, maxStoreBytes, storeRoot) {
 		annotationWatchers.clear();
 		for (const [event, listener] of listeners) hot.off(event, listener);
 		for (const upload of uploads.values()) upload.done = true;
+		await Promise.all([...uploads.values()].map((upload) => upload.queue));
 		uploads.clear();
 		await rm(serverStaging, {
 			recursive: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pk-annotator",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "Dev-only browser annotation overlay for Vite apps that sends picked elements, captures, and prompts to Claude Code and Codex through an MCP server.",
   "keywords": [
     "annotation",