@maudecode/kanvil 0.3.0 → 0.4.0

package/apps/server/dist/client.mjs

@@ -0,0 +1,884 @@
+import { B as notificationIdsInput, G as okSchema, H as notificationPreferencesSchema, U as notificationReadInput, V as notificationPreferencesInput, W as notificationsSchema, X as parsePublicOutput, Y as parseOutput, _t as snapshotSchema, a as checkpointSchema, q as operations, rt as publicOperations, t as ApiError, w as eventSchema, x as errorSchema, xt as streamErrorSchema } from "./src-tQ82UI8k.mjs";
+import { z } from "zod";
+import { parseArgs } from "node:util";
+import { constants } from "node:fs";
+import { mkdir, open, rename, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+//#region ../../node_modules/.pnpm/eventsource-parser@4.1.2/node_modules/eventsource-parser/dist/errors.js
+/**
+* Error thrown when encountering an issue during parsing.
+*
+* @public
+*/
+var ParseError = class extends Error {
+	constructor(message, options) {
+		super(message);
+		this.name = "ParseError";
+		this.type = options.type;
+		this.field = options.field;
+		this.value = options.value;
+		this.line = options.line;
+	}
+};
+//#endregion
+//#region ../../node_modules/.pnpm/eventsource-parser@4.1.2/node_modules/eventsource-parser/dist/parse.js
+/**
+* EventSource/Server-Sent Events parser
+* @see https://html.spec.whatwg.org/multipage/server-sent-events.html
+*/
+const LF = 10;
+const CR = 13;
+const SPACE = 32;
+const MAX_FIELD_PREFIX_LENGTH = 6;
+/**
+* Creates a new EventSource parser.
+*
+* @param config - Parser configuration. Accepts callbacks (see {@link ParserCallbacks})
+*   and options like `maxBufferSize` (see {@link ParserConfig}).
+*
+* @returns A new EventSource parser, with `feed` and `reset` methods.
+* @public
+*/
+function createParser(config) {
+	if (typeof config === "function") throw new TypeError("`config` must be an object, got a function instead. Did you mean `createParser({onEvent: fn})`?");
+	const { maxBufferSize, onComment, onError, onEvent, onId, onRetry } = config;
+	const pendingFragments = [];
+	let pendingFragmentsLength = 0;
+	let bomPrefix = "";
+	let id;
+	let data = "";
+	let dataLines = 0;
+	let eventType;
+	let terminated = false;
+	let skippingLine = false;
+	let skipNextLineFeed = false;
+	/**
+	* Feeds a chunk of the SSE stream to the parser. Any trailing bytes that do
+	* not yet form a complete line are held back and prepended to the next chunk,
+	* so callers can pass arbitrary slices of the stream without worrying about
+	* line boundaries.
+	*
+	* Per the SSE spec, one leading UTF-8 BOM is stripped before parsing,
+	* even when split across chunks. This handles both the raw 3-byte form (0xEF 0xBB
+	* 0xBF) and a single decoded U+FEFF, so a leading BOM is ignored regardless of
+	* how the caller decoded the bytes.
+	*
+	* @see https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream
+	*/
+	function feed(chunk) {
+		if (terminated) throw new Error("Cannot feed parser: it was terminated after exceeding the configured max buffer size. Call `reset()` to resume parsing.");
+		if (bomPrefix !== void 0) {
+			chunk = bomPrefix + chunk;
+			if (chunk === "" || chunk === "ï" || chunk === "ï»") {
+				bomPrefix = chunk;
+				return;
+			}
+			bomPrefix = void 0;
+			chunk = chunk.replace(/^(?:\uFEFF|\xEF\xBB\xBF)/, "");
+		}
+		if (skippingLine || skipNextLineFeed) {
+			chunk = resumeAfterSkip(chunk);
+			if (!chunk) return;
+		}
+		if (!pendingFragments.length) {
+			const trailing = processLines(chunk);
+			if (trailing !== "") storeTrailing(trailing);
+			checkForBufferOverflow();
+			return;
+		}
+		if (chunk.indexOf("\n") === -1 && chunk.indexOf("\r") === -1) {
+			if (pendingFragmentsLength < MAX_FIELD_PREFIX_LENGTH) {
+				if (!shouldBufferTrailing(pendingFragments.join("") + chunk.slice(0, MAX_FIELD_PREFIX_LENGTH - pendingFragmentsLength))) {
+					pendingFragments.length = 0;
+					pendingFragmentsLength = 0;
+					skippingLine = true;
+					return;
+				}
+			}
+			pendingFragments.push(chunk);
+			pendingFragmentsLength += chunk.length;
+			checkForBufferOverflow();
+			return;
+		}
+		pendingFragments.push(chunk);
+		const input = pendingFragments.join("");
+		pendingFragments.length = 0;
+		pendingFragmentsLength = 0;
+		storeTrailing(processLines(input));
+		checkForBufferOverflow();
+	}
+	function resumeAfterSkip(chunk) {
+		if (chunk.length === 0) return chunk;
+		if (skipNextLineFeed) {
+			skipNextLineFeed = false;
+			return chunk.charCodeAt(0) === LF ? chunk.slice(1) : chunk;
+		}
+		const crIndex = chunk.indexOf("\r");
+		const lfIndex = chunk.indexOf("\n");
+		const lineEnd = crIndex === -1 ? lfIndex : lfIndex === -1 ? crIndex : crIndex < lfIndex ? crIndex : lfIndex;
+		if (lineEnd === -1) return "";
+		if (lineEnd === chunk.length - 1 && chunk.charCodeAt(lineEnd) === CR) {
+			skippingLine = false;
+			skipNextLineFeed = true;
+			return "";
+		}
+		skippingLine = false;
+		return chunk.slice(lineEnd + (chunk.charCodeAt(lineEnd) === CR && chunk.charCodeAt(lineEnd + 1) === LF ? 2 : 1));
+	}
+	function storeTrailing(trailing) {
+		if (!trailing) return;
+		if (trailing.charCodeAt(trailing.length - 1) === CR) {
+			parseLine(trailing, 0, trailing.length - 1);
+			if (checkForBufferOverflow()) return;
+			skipNextLineFeed = true;
+			return;
+		}
+		if (shouldBufferTrailing(trailing)) {
+			pendingFragments.push(trailing);
+			pendingFragmentsLength = trailing.length;
+			return;
+		}
+		skippingLine = true;
+	}
+	function shouldBufferTrailing(trailing) {
+		const firstCharCode = trailing.charCodeAt(0);
+		return firstCharCode === 58 && !!onComment || firstCharCode === 100 && isPotentialField(trailing, "data") || firstCharCode === 101 && isPotentialField(trailing, "event") || firstCharCode === 105 && isPotentialField(trailing, "id") || firstCharCode === 114 && isPotentialField(trailing, "retry");
+	}
+	function checkForBufferOverflow() {
+		if (terminated) return true;
+		if (maxBufferSize === void 0) return false;
+		if (pendingFragmentsLength + data.length <= maxBufferSize) return false;
+		terminated = true;
+		pendingFragments.length = 0;
+		pendingFragmentsLength = 0;
+		id = void 0;
+		data = "";
+		dataLines = 0;
+		eventType = void 0;
+		skippingLine = false;
+		skipNextLineFeed = false;
+		onError === null || onError === void 0 || onError(new ParseError(`Buffered data exceeded max buffer size of ${maxBufferSize} characters`, { type: "max-buffer-size-exceeded" }));
+		return true;
+	}
+	/**
+	* Splits `chunk` into SSE lines and dispatches each to the appropriate handler.
+	* Returns any trailing bytes that did not terminate with a line break, so the
+	* caller can prepend them to the next chunk.
+	*
+	* The SSE spec permits three line terminators: `\n`, `\r`, and `\r\n`. Real-world
+	* streams almost always use plain `\n`, so we take a fast path when no `\r` is
+	* present in the chunk. The slow path is spec-correct but does more work per line.
+	*/
+	function processLines(chunk) {
+		let searchIndex = 0;
+		if (chunk.indexOf("\r") === -1) {
+			let lfIndex = chunk.indexOf("\n", searchIndex);
+			while (lfIndex !== -1) {
+				if (searchIndex === lfIndex) {
+					if (id !== void 0) onId === null || onId === void 0 || onId(id);
+					if (dataLines > 0) onEvent === null || onEvent === void 0 || onEvent({
+						id,
+						event: eventType,
+						data
+					});
+					id = void 0;
+					data = "";
+					dataLines = 0;
+					eventType = void 0;
+					searchIndex = lfIndex + 1;
+					lfIndex = chunk.indexOf("\n", searchIndex);
+					continue;
+				}
+				const firstCharCode = chunk.charCodeAt(searchIndex);
+				if (isDataPrefix(chunk, searchIndex, firstCharCode)) {
+					const valueStart = chunk.charCodeAt(searchIndex + 5) === SPACE ? searchIndex + 6 : searchIndex + 5;
+					const value = chunk.slice(valueStart, lfIndex);
+					if (dataLines === 0 && chunk.charCodeAt(lfIndex + 1) === LF) {
+						if (id !== void 0) onId === null || onId === void 0 || onId(id);
+						onEvent === null || onEvent === void 0 || onEvent({
+							id,
+							event: eventType,
+							data: value
+						});
+						id = void 0;
+						data = "";
+						eventType = void 0;
+						searchIndex = lfIndex + 2;
+						lfIndex = chunk.indexOf("\n", searchIndex);
+						continue;
+					}
+					data = dataLines === 0 ? value : `${data}\n${value}`;
+					dataLines++;
+				} else if (isEventPrefix(chunk, searchIndex, firstCharCode)) eventType = chunk.slice(chunk.charCodeAt(searchIndex + 6) === SPACE ? searchIndex + 7 : searchIndex + 6, lfIndex) || void 0;
+				else parseLine(chunk, searchIndex, lfIndex);
+				if (checkForBufferOverflow()) return "";
+				searchIndex = lfIndex + 1;
+				lfIndex = chunk.indexOf("\n", searchIndex);
+			}
+			return chunk.slice(searchIndex);
+		}
+		while (searchIndex < chunk.length) {
+			const crIndex = chunk.indexOf("\r", searchIndex);
+			const lfIndex = chunk.indexOf("\n", searchIndex);
+			let lineEnd = -1;
+			if (crIndex !== -1 && lfIndex !== -1) lineEnd = crIndex < lfIndex ? crIndex : lfIndex;
+			else if (crIndex !== -1) {
+				if (crIndex === chunk.length - 1) lineEnd = -1;
+				else lineEnd = crIndex;
+			} else if (lfIndex !== -1) lineEnd = lfIndex;
+			if (lineEnd === -1) break;
+			parseLine(chunk, searchIndex, lineEnd);
+			if (checkForBufferOverflow()) return "";
+			searchIndex = lineEnd + 1;
+			if (chunk.charCodeAt(searchIndex - 1) === CR && chunk.charCodeAt(searchIndex) === LF) searchIndex++;
+		}
+		return chunk.slice(searchIndex);
+	}
+	function parseLine(chunk, start, end) {
+		if (start === end) {
+			dispatchEvent();
+			return;
+		}
+		const firstCharCode = chunk.charCodeAt(start);
+		if (isDataPrefix(chunk, start, firstCharCode)) {
+			const valueStart = chunk.charCodeAt(start + 5) === SPACE ? start + 6 : start + 5;
+			const value = chunk.slice(valueStart, end);
+			data = dataLines === 0 ? value : `${data}\n${value}`;
+			dataLines++;
+			return;
+		}
+		if (isEventPrefix(chunk, start, firstCharCode)) {
+			eventType = chunk.slice(chunk.charCodeAt(start + 6) === SPACE ? start + 7 : start + 6, end) || void 0;
+			return;
+		}
+		if (firstCharCode === 105 && chunk.charCodeAt(start + 1) === 100 && chunk.charCodeAt(start + 2) === 58) {
+			const value = chunk.slice(chunk.charCodeAt(start + 3) === SPACE ? start + 4 : start + 3, end);
+			if (!value.includes("\0")) id = value;
+			return;
+		}
+		if (firstCharCode === 58) {
+			if (onComment) {
+				const line = chunk.slice(start, end);
+				onComment(line.slice(chunk.charCodeAt(start + 1) === SPACE ? 2 : 1));
+			}
+			return;
+		}
+		const line = chunk.slice(start, end);
+		const fieldSeparatorIndex = line.indexOf(":");
+		if (fieldSeparatorIndex === -1) {
+			processField(line, "", line);
+			return;
+		}
+		const field = line.slice(0, fieldSeparatorIndex);
+		const offset = line.charCodeAt(fieldSeparatorIndex + 1) === SPACE ? 2 : 1;
+		processField(field, line.slice(fieldSeparatorIndex + offset), line);
+	}
+	function processField(field, value, line) {
+		switch (field) {
+			case "event":
+				eventType = value || void 0;
+				break;
+			case "data":
+				data = dataLines === 0 ? value : `${data}\n${value}`;
+				dataLines++;
+				break;
+			case "id":
+				if (!value.includes("\0")) id = value;
+				break;
+			case "retry":
+				if (/^\d+$/.test(value)) onRetry === null || onRetry === void 0 || onRetry(parseInt(value, 10));
+				else onError === null || onError === void 0 || onError(new ParseError(`Invalid \`retry\` value: "${value}"`, {
+					type: "invalid-retry",
+					value,
+					line
+				}));
+				break;
+			default: onError === null || onError === void 0 || onError(new ParseError(`Unknown field "${field.length > 20 ? `${field.slice(0, 20)}…` : field}"`, {
+				type: "unknown-field",
+				field,
+				value,
+				line
+			}));
+		}
+	}
+	function dispatchEvent() {
+		if (id !== void 0) onId === null || onId === void 0 || onId(id);
+		if (dataLines > 0) onEvent === null || onEvent === void 0 || onEvent({
+			id,
+			event: eventType,
+			data
+		});
+		id = void 0;
+		data = "";
+		dataLines = 0;
+		eventType = void 0;
+	}
+	function reset(options = {}) {
+		if (options.consume && pendingFragments.length > 0) {
+			const incompleteLine = pendingFragments.join("");
+			parseLine(incompleteLine, 0, incompleteLine.length);
+		}
+		bomPrefix = "";
+		id = void 0;
+		data = "";
+		dataLines = 0;
+		eventType = void 0;
+		pendingFragments.length = 0;
+		pendingFragmentsLength = 0;
+		terminated = false;
+		skippingLine = false;
+		skipNextLineFeed = false;
+	}
+	return {
+		feed,
+		reset
+	};
+}
+/**
+* Checks if `chunk` starts with the literal `data:` at index `i`.
+*
+* Equivalent to `chunk.startsWith('data:', i)`, but benchmarks show this
+* hand-unrolled char-code comparison is ~20% faster on common event types.
+* The caller passes `firstCharCode` (the code at `i`) so it can be reused
+* across prefix checks.
+*
+* ASCII: 'd' = 100, 'a' = 97, 't' = 116, 'a' = 97, ':' = 58
+*/
+function isDataPrefix(chunk, i, firstCharCode) {
+	return firstCharCode === 100 && chunk.charCodeAt(i + 1) === 97 && chunk.charCodeAt(i + 2) === 116 && chunk.charCodeAt(i + 3) === 97 && chunk.charCodeAt(i + 4) === 58;
+}
+/**
+* Checks if `chunk` starts with the literal `event:` at index `i`.
+*
+* See {@link isDataPrefix} for why this is hand-unrolled rather than using
+* `String.prototype.startsWith`.
+*
+* ASCII: 'e' = 101, 'v' = 118, 'e' = 101, 'n' = 110, 't' = 116, ':' = 58
+*/
+function isEventPrefix(chunk, i, firstCharCode) {
+	return firstCharCode === 101 && chunk.charCodeAt(i + 1) === 118 && chunk.charCodeAt(i + 2) === 101 && chunk.charCodeAt(i + 3) === 110 && chunk.charCodeAt(i + 4) === 116 && chunk.charCodeAt(i + 5) === 58;
+}
+function isPotentialField(line, field) {
+	let i = 1;
+	while (i < line.length && i < field.length) {
+		if (line.charCodeAt(i) !== field.charCodeAt(i)) return false;
+		i++;
+	}
+	return line.length <= field.length || line.charCodeAt(field.length) === 58;
+}
+//#endregion
+//#region ../../packages/client/src/index.ts
+function randomRequestId() {
+	if (typeof crypto.randomUUID === "function") return crypto.randomUUID();
+	const bytes = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16));
+	bytes[6] = (bytes[6] ?? 0) & 15 | 64;
+	bytes[8] = (bytes[8] ?? 0) & 63 | 128;
+	const hex = Array.from(bytes, (value) => value.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+async function decode(response) {
+	const data = await response.json().catch(() => {
+		throw new ApiError(response.status, "invalid_response", "Kanvil returned an invalid response");
+	});
+	if (!response.ok) {
+		const error = errorSchema.safeParse(data);
+		throw new ApiError(response.status, error.success ? error.data.error.code : "request_failed", error.success ? error.data.error.message : `Request failed (${response.status})`, error.success ? error.data.error.details : void 0);
+	}
+	return data;
+}
+function createClient(options) {
+	const request = options.fetch ?? fetch;
+	const endpoint = (path) => {
+		if (!path.startsWith("/") || path.startsWith("//")) throw new ApiError(400, "invalid_path", "Use a relative Kanvil endpoint");
+		const url = new URL(`${options.baseUrl.replace(/\/$/, "")}${path}`);
+		if (url.origin !== new URL(options.baseUrl).origin) throw new ApiError(400, "invalid_path", "Credentials cannot be sent to another origin");
+		return url;
+	};
+	const retry = async (url, init) => {
+		try {
+			return await request(url, init);
+		} catch (error) {
+			if (init.signal?.aborted) throw error;
+			return request(url, init);
+		}
+	};
+	const send = async (spec, input, base) => {
+		const values = { ...spec.input.parse(input) };
+		const path = spec.path.replace(/\{(\w+)\}/g, (_, key) => {
+			const value = values[key];
+			delete values[key];
+			if (typeof value !== "string") throw new ApiError(400, "invalid_path", `Missing path parameter ${key}`);
+			return encodeURIComponent(value);
+		});
+		const url = new URL(`${options.baseUrl.replace(/\/$/, "")}${base}${path}`);
+		const headers = new Headers(await options.headers?.());
+		const init = {
+			method: spec.method,
+			credentials: options.credentials ?? "include",
+			headers
+		};
+		if (spec.method === "GET") {
+			for (const [key, value] of Object.entries(values)) for (const item of Array.isArray(value) ? value : [value]) if (typeof item === "string" || typeof item === "number" || typeof item === "boolean") url.searchParams.append(key, String(item));
+		} else {
+			headers.set("Content-Type", "application/json");
+			if ("requestId" in spec.input.shape) values.requestId ??= (options.requestId ?? randomRequestId)();
+			init.body = JSON.stringify(values);
+		}
+		return decode(await (spec.method === "GET" || "requestId" in values ? retry(url, init) : request(url, init)));
+	};
+	const api = {
+		async request(path, schema, init = {}) {
+			const headers = new Headers(await options.headers?.());
+			new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+			return schema.parse(await decode(await request(endpoint(path), {
+				...init,
+				headers,
+				credentials: options.credentials ?? "include"
+			})));
+		},
+		async call(name, input) {
+			return parseOutput(name, await send(operations[name], input, "/api/v1"));
+		},
+		async callPublic(name, input) {
+			return parsePublicOutput(name, await send(publicOperations[name], input, "/api/public"));
+		},
+		async subscribe(subscription) {
+			let cursor = subscription.cursor, backoff = 1e3;
+			try {
+				while (!subscription.signal.aborted) {
+					subscription.onState?.("connecting");
+					const url = endpoint("/api/v1/events");
+					if (cursor) url.searchParams.set("cursor", cursor);
+					if (subscription.projectId) url.searchParams.set("projectId", subscription.projectId);
+					let reader;
+					const cancel = () => {
+						reader?.cancel().catch(() => {});
+					};
+					subscription.signal.addEventListener("abort", cancel, { once: true });
+					try {
+						const response = await request(url, {
+							headers: new Headers(await options.headers?.()),
+							credentials: options.credentials ?? "include",
+							signal: subscription.signal
+						});
+						if (response.status === 410 && subscription.onReset) {
+							cursor = await subscription.onReset();
+							continue;
+						}
+						if (!response.ok) await decode(response);
+						if (!response.body) throw new ApiError(502, "invalid_stream", "The event stream has no body");
+						reader = response.body.getReader();
+						const messages = [];
+						const parser = createParser({
+							maxBufferSize: 1e6,
+							onEvent: (event) => messages.push(event),
+							onError: (error) => {
+								throw new ApiError(502, "invalid_stream", error.message);
+							}
+						});
+						const decoder = new TextDecoder();
+						while (!subscription.signal.aborted) {
+							const chunk = await reader.read();
+							if (chunk.done) break;
+							parser.feed(decoder.decode(chunk.value, { stream: true }));
+							for (const message of messages.splice(0)) {
+								if (message.event === "error") {
+									const error = streamErrorSchema.parse(JSON.parse(message.data));
+									throw new ApiError(error.status, error.code, error.message);
+								}
+								if (message.event === "change") await subscription.onEvent(eventSchema.parse(JSON.parse(message.data)));
+								if (message.event === "checkpoint" || message.event === "change") {
+									subscription.onState?.("connected");
+									backoff = 1e3;
+									if (message.id) {
+										await subscription.onCursor?.(message.id);
+										cursor = message.id;
+									}
+								}
+							}
+						}
+					} catch (error) {
+						if (subscription.signal.aborted) return;
+						if (error instanceof ApiError && error.status === 410 && subscription.onReset) {
+							cursor = await subscription.onReset();
+							continue;
+						}
+						if (error instanceof ApiError && error.status < 500) throw error;
+					} finally {
+						subscription.signal.removeEventListener("abort", cancel);
+						await reader?.cancel().catch(() => {});
+					}
+					if (subscription.signal.aborted) return;
+					subscription.onState?.("offline");
+					await new Promise((resolve) => {
+						const finish = () => {
+							clearTimeout(timer);
+							subscription.signal.removeEventListener("abort", finish);
+							resolve();
+						};
+						const timer = setTimeout(finish, backoff);
+						subscription.signal.addEventListener("abort", finish, { once: true });
+						if (subscription.signal.aborted) finish();
+					});
+					backoff = Math.min(backoff * 2, 3e4);
+				}
+			} finally {
+				subscription.onState?.("closed");
+			}
+		}
+	};
+	return {
+		...api,
+		notifications() {
+			return {
+				queryKey: [
+					"kanvil",
+					options.baseUrl,
+					"notifications"
+				],
+				queryFn: () => api.request("/api/v1/notifications", notificationsSchema)
+			};
+		},
+		markNotifications(input) {
+			return api.request("/api/v1/notifications/read", okSchema, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(notificationReadInput.parse(input))
+			});
+		},
+		dismissNotifications(input) {
+			return api.request("/api/v1/notifications/dismiss", okSchema, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(notificationIdsInput.parse(input))
+			});
+		},
+		notificationPreferences() {
+			return {
+				queryKey: [
+					"kanvil",
+					options.baseUrl,
+					"notification-preferences"
+				],
+				queryFn: () => api.request("/api/v1/notifications/preferences", notificationPreferencesSchema)
+			};
+		},
+		setNotificationPreferences(input) {
+			return api.request("/api/v1/notifications/preferences", notificationPreferencesSchema, {
+				method: "PUT",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(notificationPreferencesInput.parse(input))
+			});
+		},
+		watch(observer) {
+			let initial = true;
+			return api.subscribe({
+				...observer.projectId ? { projectId: observer.projectId } : {},
+				signal: observer.signal,
+				...observer.onState ? { onState: observer.onState } : {},
+				onEvent: (event) => observer.invalidate(event),
+				onCursor: async () => {
+					if (initial) {
+						initial = false;
+						await observer.invalidate();
+					}
+				},
+				onReset: async () => {
+					const snapshot = observer.projectId ? await api.request(`/api/v1/snapshot?projectId=${encodeURIComponent(observer.projectId)}`, snapshotSchema) : await api.request("/api/v1/checkpoint", checkpointSchema);
+					await observer.invalidate();
+					return snapshot.cursor;
+				}
+			});
+		},
+		query(name, input) {
+			return {
+				queryKey: [
+					"kanvil",
+					options.baseUrl,
+					name,
+					input
+				],
+				queryFn: () => api.call(name, input)
+			};
+		},
+		publicQuery(name, input) {
+			return {
+				queryKey: [
+					"kanvil-public",
+					options.baseUrl,
+					name,
+					input
+				],
+				queryFn: () => api.callPublic(name, input)
+			};
+		},
+		action(name) {
+			return {
+				mutationFn: (input) => api.call(name, input),
+				networkMode: "always",
+				retry: false
+			};
+		}
+	};
+}
+//#endregion
+//#region src/cli/client.ts
+const commands = {
+	"workspace list": "list_workspaces",
+	"project list": "list_projects",
+	"project get": "get_project",
+	"project create": "create_project",
+	"task list": "list_tickets",
+	"task get": "get_ticket",
+	"task create": "create_ticket",
+	"task update": "update_ticket",
+	"task delete": "delete_ticket",
+	"task ready": "list_eligible_tickets",
+	"comment list": "list_comments",
+	"comment add": "add_comment",
+	"claim acquire": "claim_ticket",
+	"claim renew": "renew_claim",
+	"claim release": "release_claim"
+};
+const clientHelp = `Usage: kanvil <namespace> <action> [ticket-key] [options]
+${Object.keys(commands).join("\n")}
+profile set <name> --server <url> [--project <id>] --token-stdin
+profile list | profile remove <name> --yes
+
+--profile <name>       Named server/project credential (default: default)
+--config <path>        Private configuration (default: ~/.config/kanvil/client.json)
+--input <json|->       Operation input as a JSON object; - reads stdin
+--title <text>         Ticket title
+--body <markdown>      Comment body
+--expected-version <n> Required version for update, delete and acquire
+--changes <json>       Ticket update changes as a JSON object
+--request-id <uuid>    Reuse for a deliberate retry across invocations
+--json                Compact JSON output (default: indented JSON)
+--yes                 Confirm task deletion or profile removal
+--help                Show commands and input conventions
+
+All operation fields also accept --input. A profile's project cannot be overridden.
+Writes never refresh versions or retry conflicts. Credentials are never command arguments.
+`;
+const profileSchema = z.object({
+	server: z.string().transform((value, context) => {
+		try {
+			const url = new URL(value);
+			if (url.username || url.password || url.search || url.hash || url.pathname !== "/" || url.protocol !== "https:" && !(url.protocol === "http:" && [
+				"localhost",
+				"127.0.0.1",
+				"[::1]"
+			].includes(url.hostname))) throw new Error();
+			return url.origin;
+		} catch {
+			context.addIssue({
+				code: "custom",
+				message: "Use an HTTPS server origin (HTTP only on loopback)."
+			});
+			return z.NEVER;
+		}
+	}),
+	projectId: z.string().min(1).optional(),
+	token: z.string().trim().min(1).max(8192).regex(/^[^\s]+$/)
+});
+const configSchema = z.object({
+	version: z.literal(1),
+	profiles: z.record(z.string(), profileSchema)
+}).strict();
+const objectSchema = z.record(z.string(), z.unknown());
+var UsageError = class extends ApiError {
+	constructor(message) {
+		super(400, "invalid_arguments", message);
+	}
+};
+function usage(message) {
+	throw new UsageError(message);
+}
+function jsonObject(value) {
+	try {
+		return objectSchema.parse(JSON.parse(value));
+	} catch {
+		return usage("Input must be a JSON object.");
+	}
+}
+async function readConfig(path) {
+	let file;
+	try {
+		file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return {
+			version: 1,
+			profiles: {}
+		};
+		throw new ApiError(400, "invalid_config", "Cannot open private CLI configuration.");
+	}
+	try {
+		const info = await file.stat();
+		if (!info.isFile() || (info.mode & 63) !== 0) usage("CLI configuration must be a private file (chmod 600).");
+		return configSchema.parse(JSON.parse(await file.readFile("utf8")));
+	} catch {
+		throw new ApiError(400, "invalid_config", "Invalid CLI configuration; require a private file (chmod 600).");
+	} finally {
+		await file.close();
+	}
+}
+async function saveConfig(path, config) {
+	await mkdir(dirname(path), {
+		recursive: true,
+		mode: 448
+	});
+	const temporary = `${path}.${crypto.randomUUID()}.tmp`;
+	try {
+		const file = await open(temporary, "wx", 384);
+		try {
+			await file.writeFile(JSON.stringify(config) + "\n");
+		} finally {
+			await file.close();
+		}
+		await rename(temporary, path);
+	} finally {
+		await rm(temporary, { force: true });
+	}
+}
+async function runClient(args, io) {
+	let secret = "";
+	let compact = args.includes("--json");
+	const serialize = (value, pretty = false) => JSON.stringify(value, (_key, item) => typeof item === "string" && secret ? item.replaceAll(secret, "[redacted]") : item, pretty ? 2 : void 0);
+	const output = (value) => io.stdout(serialize(value, !compact) + "\n");
+	try {
+		const { values, positionals } = parseArgs({
+			args,
+			allowPositionals: true,
+			options: {
+				help: { type: "boolean" },
+				json: { type: "boolean" },
+				yes: { type: "boolean" },
+				profile: {
+					type: "string",
+					default: "default"
+				},
+				config: { type: "string" },
+				input: { type: "string" },
+				server: { type: "string" },
+				project: { type: "string" },
+				"token-stdin": { type: "boolean" },
+				title: { type: "string" },
+				body: { type: "string" },
+				"expected-version": { type: "string" },
+				changes: { type: "string" },
+				"request-id": { type: "string" }
+			}
+		});
+		compact = values.json ?? false;
+		if (values.help) {
+			io.stdout(clientHelp);
+			return 0;
+		}
+		const [namespace, action, identifier, ...extra] = positionals;
+		if (extra.length) usage("Too many command arguments.");
+		const path = values.config ?? io.configPath ?? join(homedir(), ".config", "kanvil", "client.json");
+		const config = await readConfig(path);
+		if (namespace === "profile") {
+			if (action === "list" && !identifier) output(Object.entries(config.profiles).map(([name, { server, projectId }]) => ({
+				name,
+				server,
+				projectId
+			})));
+			else if (action === "set" && identifier) {
+				if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/.test(identifier)) usage("Use a profile name containing letters, digits, hyphens or underscores.");
+				if (!values["token-stdin"] || values.input) usage("Pass the credential privately with --token-stdin; do not use --input.");
+				secret = (await io.stdin()).trim();
+				const profile = profileSchema.parse({
+					server: values.server,
+					projectId: values.project,
+					token: secret
+				});
+				if (Object.hasOwn(config.profiles, identifier) && !values.yes) usage("Replacing a profile requires --yes.");
+				Object.defineProperty(config.profiles, identifier, {
+					value: profile,
+					enumerable: true,
+					configurable: true,
+					writable: true
+				});
+				await saveConfig(path, config);
+				output({
+					name: identifier,
+					server: profile.server,
+					projectId: profile.projectId
+				});
+			} else if (action === "remove" && identifier) {
+				if (!values.yes) usage("Removing a profile requires --yes.");
+				if (!Object.hasOwn(config.profiles, identifier)) usage("Unknown profile.");
+				delete config.profiles[identifier];
+				await saveConfig(path, config);
+				output({ ok: true });
+			} else usage("Unknown profile command. Use --help.");
+			return 0;
+		}
+		if (values.server || values.project || values["token-stdin"]) usage("Server, project and token options belong to profile set.");
+		const command = Object.entries(commands).find(([name]) => name === `${namespace} ${action}`)?.[1];
+		if (!command) usage("Unknown client command. Use --help.");
+		const profile = Object.hasOwn(config.profiles, values.profile) ? config.profiles[values.profile] : void 0;
+		if (!profile) usage("Unknown profile. Use profile set first.");
+		secret = profile.token;
+		const input = values.input ? jsonObject(values.input === "-" ? await io.stdin() : values.input) : {};
+		if (profile.projectId) {
+			if (input.projectId !== void 0 && input.projectId !== profile.projectId) usage("Input project differs from the selected profile.");
+			if ("projectId" in operations[command].input.shape) input.projectId = profile.projectId;
+		}
+		if (identifier) {
+			if (!("ticketId" in operations[command].input.shape)) usage("This command takes no ticket argument.");
+			if (input.ticketId !== void 0 && input.ticketId !== identifier) usage("Conflicting ticket identifiers.");
+			input.ticketId = identifier;
+		}
+		for (const key of ["title", "body"]) if (values[key] !== void 0) input[key] = values[key];
+		if (values["expected-version"] !== void 0) input.expectedVersion = Number(values["expected-version"]);
+		if (values["request-id"] !== void 0) input.requestId = values["request-id"];
+		if (values.changes !== void 0) input.changes = jsonObject(values.changes);
+		if (command === "delete_ticket" && !values.yes) usage("Deleting a task requires --yes and --expected-version.");
+		const spec = operations[command];
+		if (Object.keys(input).some((key) => !Object.hasOwn(spec.input.shape, key))) usage("Unknown operation input field. See the API operation schema.");
+		const parsed = spec.input.parse(input);
+		output(await createClient({
+			baseUrl: profile.server,
+			headers: () => ({ Authorization: `Bearer ${profile.token}` }),
+			credentials: "omit",
+			fetch: (url, init) => (io.fetch ?? fetch)(url, {
+				...init,
+				redirect: "error",
+				signal: AbortSignal.timeout(3e4)
+			})
+		}).call(command, parsed).catch((error) => {
+			if (error instanceof z.ZodError) throw new ApiError(502, "invalid_response", "Invalid server response.");
+			throw error;
+		}));
+		return 0;
+	} catch (error) {
+		const status = error instanceof ApiError ? error.status : 0;
+		const code = error instanceof ApiError ? error.code : error instanceof z.ZodError ? "invalid_arguments" : "client_error";
+		const message = error instanceof UsageError ? error.message : error instanceof z.ZodError ? "Invalid input. Check the operation schema and required fields." : "Command failed. Check the error code, profile, permissions and server connection.";
+		io.stderr(serialize({ error: {
+			code,
+			message
+		} }) + "\n");
+		return status === 401 || status === 403 ? 3 : status === 404 ? 4 : status === 409 ? 5 : status === 400 || error instanceof z.ZodError || error instanceof SyntaxError || error instanceof TypeError && "code" in error ? 2 : error instanceof TypeError || error instanceof Error && error.name === "TimeoutError" ? 6 : 1;
+	}
+}
+//#endregion
+//#region src/cli/client-main.ts
+process.exitCode = await runClient(process.argv.slice(2), {
+	stdin: async () => {
+		process.stdin.setEncoding("utf8");
+		let text = "";
+		for await (const chunk of process.stdin) {
+			text += String(chunk);
+			if (Buffer.byteLength(text) > 1e6) throw new Error("Input exceeds the CLI limit.");
+		}
+		return text;
+	},
+	stdout: (text) => process.stdout.write(text),
+	stderr: (text) => process.stderr.write(text)
+});
+//#endregion
+export {};