@marver-design/marver 0.3.1 → 0.5.0

package/dist/collab-CXy8gqoz.mjs

@@ -0,0 +1,297 @@
+import { i as readLog, r as listBoards, t as appendEvents } from "./comments-Ba8mU600.mjs";
+import { claimInvite, createInvite, inviteInfo, ownerName, publicUser, revokeUser, sessionUser, signIn, signOut, updateProfile } from "./auth-B36fMCM3.mjs";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+//#region src/server/collab.ts
+const MONTH = 2592e3;
+const MAX_BODY = 262144;
+/** The permission seam (SPEC-M3 §3): v1 derives from publish policy + membership;
+*  a per-user ACL can replace the internals without touching a single route. */
+function can(user, rights, board, action) {
+	if (action === "read") return board in rights;
+	if (action === "admin") return user?.role === "owner";
+	return !!user && rights[board] === "comment";
+}
+const EVENT_TYPES = /* @__PURE__ */ new Set([
+	"create",
+	"reply",
+	"edit",
+	"resolve",
+	"reopen",
+	"react",
+	"profile"
+]);
+const ID_RE = /^[\w-]{8,64}$/;
+const MAX_BODY_TEXT = 1e4;
+/** An avatar the server will store: a raster data-URI whose ACTUAL decoded bytes
+*  match the declared type. The declared MIME alone is a lie an attacker controls
+*  (base64 SVG labelled image/png); the magic bytes are the truth. Capped small -
+*  the client downscales to a 128px jpeg (~15KB), 64KB is generous headroom. */
+function validAvatar(s) {
+	if (typeof s !== "string" || s.length > 65536) return false;
+	const m = /^data:image\/(jpeg|png|webp|gif);base64,([A-Za-z0-9+/]+={0,2})$/.exec(s);
+	if (!m) return false;
+	let head;
+	try {
+		head = Buffer.from(m[2].slice(0, 24), "base64");
+	} catch {
+		return false;
+	}
+	return {
+		jpeg: (b) => b[0] === 255 && b[1] === 216 && b[2] === 255,
+		png: (b) => b[0] === 137 && b[1] === 80 && b[2] === 78 && b[3] === 71,
+		gif: (b) => b.toString("latin1", 0, 4) === "GIF8",
+		webp: (b) => b.toString("latin1", 0, 4) === "RIFF" && b.toString("latin1", 8, 12) === "WEBP"
+	}[m[1]]?.(head) ?? false;
+}
+/** Reject anything the log must not absorb. Returns an error string or null.
+*  Events are append-only and synced by id, so acceptance is forever - validate hard. */
+function validateEvents(incoming, log, u, board) {
+	const now = Date.now();
+	const creates = /* @__PURE__ */ new Map();
+	const authors = /* @__PURE__ */ new Map();
+	for (const ev of log) {
+		if (ev.type === "create" && ev.commentId && !creates.has(ev.commentId)) creates.set(ev.commentId, ev);
+		if ((ev.type === "create" || ev.type === "reply") && ev.commentId && ev.author?.email && !authors.has(ev.commentId)) authors.set(ev.commentId, ev.author.email.toLowerCase());
+	}
+	const me = u.email.toLowerCase();
+	for (const ev of incoming) {
+		if (!ev || typeof ev !== "object") return "malformed event";
+		if (typeof ev.id !== "string" || !ID_RE.test(ev.id)) return "event id must be an 8-64 char token";
+		if (!EVENT_TYPES.has(ev.type)) return `unknown event type "${ev.type}"`;
+		if (typeof ev.ts !== "number" || ev.ts < 15778368e5 || ev.ts > now + 6e4) return "event timestamp out of bounds";
+		if (ev.board !== void 0 && ev.board !== board) return "event board does not match the endpoint";
+		if (ev.body !== void 0 && (typeof ev.body !== "string" || ev.body.length > MAX_BODY_TEXT)) return "body too long";
+		if ((ev.type === "create" || ev.type === "reply" || ev.type === "react" || ev.type === "edit") && ev.author?.email?.toLowerCase() !== me) return "event author must be the signed-in account";
+		if (typeof ev.commentId !== "string" || !ID_RE.test(ev.commentId)) {
+			if (ev.type !== "profile") return "event needs a commentId";
+		}
+		switch (ev.type) {
+			case "create":
+				if (creates.has(ev.commentId)) return "a thread with that id already exists";
+				creates.set(ev.commentId, ev);
+				if (ev.author?.email) authors.set(ev.commentId, ev.author.email.toLowerCase());
+				break;
+			case "reply":
+				if (typeof ev.parentId !== "string" || !creates.has(ev.parentId) && !incoming.some((x) => x.type === "create" && x.commentId === ev.parentId)) return "reply parent does not exist";
+				if (ev.author?.email) authors.set(ev.commentId, ev.author.email.toLowerCase());
+				break;
+			case "edit": {
+				const owner = authors.get(ev.commentId);
+				if (!owner) return "cannot edit a comment that does not exist";
+				if (owner !== me) return "only the author can edit a comment";
+				break;
+			}
+			case "resolve":
+			case "reopen": if (!creates.has(ev.commentId) && !incoming.some((x) => x.type === "create" && x.commentId === ev.commentId)) return "cannot resolve a thread that does not exist";
+		}
+	}
+	return null;
+}
+function collabHandler(dataDir, distDir) {
+	let rights = {};
+	try {
+		rights = JSON.parse(readFileSync(join(distDir, "meta.json"), "utf8")).rights ?? {};
+	} catch {}
+	const commentsDir = join(dataDir, "comments");
+	const bootEpoch = randomBytes(4).toString("hex");
+	let seq = 0;
+	const ring = [];
+	const clients = /* @__PURE__ */ new Set();
+	const broadcast = (board, events) => {
+		for (const ev of events) {
+			const frame = `id: ${bootEpoch}-${++seq}\nevent: comment\ndata: ${JSON.stringify({
+				board,
+				ev
+			})}\n\n`;
+			ring.push({
+				seq,
+				data: frame
+			});
+			if (ring.length > 500) ring.shift();
+			for (const res of clients) res.write(frame);
+		}
+	};
+	setInterval(() => {
+		for (const res of clients) res.write(": keepalive\n\n");
+	}, 24e4).unref();
+	const attempts = /* @__PURE__ */ new Map();
+	const limited = (...keys) => {
+		const now = Date.now();
+		if (attempts.size > 1e4) {
+			for (const [k, a] of attempts) if (a.reset < now) attempts.delete(k);
+		}
+		if (attempts.size > 2e4) return true;
+		let hit = false;
+		for (const key of keys) {
+			const a = attempts.get(key);
+			if (!a || a.reset < now) attempts.set(key, {
+				n: 1,
+				reset: now + 6e4
+			});
+			else if (++a.n > 10) hit = true;
+		}
+		return hit;
+	};
+	const cookie = (req, name) => new RegExp(`(?:^|;\\s*)${name}=([\\w-]+)`).exec(String(req.headers.cookie ?? ""))?.[1];
+	const currentUser = (req) => {
+		const tok = /^Bearer ([\w-]+)$/.exec(String(req.headers.authorization ?? ""))?.[1] ?? cookie(req, "mv_s");
+		return tok ? sessionUser(dataDir, tok) : null;
+	};
+	const json = (res, code, body) => {
+		res.statusCode = code;
+		res.setHeader("content-type", "application/json");
+		res.setHeader("cache-control", "no-store");
+		res.end(JSON.stringify(body));
+	};
+	const readBody = (req) => new Promise((resolve, reject) => {
+		if (!/^application\/json\b/.test(String(req.headers["content-type"] ?? ""))) return reject(/* @__PURE__ */ new Error("content-type must be application/json"));
+		let body = "";
+		req.on("data", (c) => {
+			body += c;
+			if (body.length > MAX_BODY) {
+				reject(/* @__PURE__ */ new Error("body too large"));
+				req.destroy();
+			}
+		});
+		req.on("end", () => {
+			try {
+				resolve(body ? JSON.parse(body) : {});
+			} catch {
+				reject(/* @__PURE__ */ new Error("bad json"));
+			}
+		});
+	});
+	const setSession = (req, res, token) => {
+		const secure = req.headers["x-forwarded-proto"] === "https" ? "; Secure" : "";
+		res.setHeader("set-cookie", [`mv_s=${token}; Path=/; Max-Age=${MONTH}; HttpOnly; SameSite=Lax${secure}`, `mv_c=${randomBytes(16).toString("base64url")}; Path=/; Max-Age=${MONTH}; SameSite=Lax${secure}`]);
+	};
+	const csrfOk = (req) => !!/^Bearer /.test(String(req.headers.authorization ?? "")) || !cookie(req, "mv_s") || !!cookie(req, "mv_c") && req.headers["x-mv-c"] === cookie(req, "mv_c");
+	/** Returns true when the request was handled. Mounted behind the gate by serve. */
+	return async (req, res, url) => {
+		if (!url.pathname.startsWith("/__mv/api/")) return false;
+		const path = url.pathname.slice(10);
+		const ip = process.env.MARVER_TRUSTED_PROXY ? String(req.headers["x-forwarded-for"] ?? req.socket.remoteAddress ?? "?").split(",")[0].trim() : String(req.socket.remoteAddress ?? "?");
+		try {
+			if (req.method === "GET") {
+				if (path === "me") {
+					const u = currentUser(req);
+					return json(res, u ? 200 : 401, u ? {
+						user: publicUser(u),
+						role: u.role
+					} : { error: "signed out" }), true;
+				}
+				if (path === "boards") {
+					const name = ownerName(dataDir);
+					return json(res, 200, {
+						rights,
+						stored: listBoards(commentsDir),
+						...name ? { owner: { name } } : {}
+					}), true;
+				}
+				const m = /^comments\/([a-z0-9][a-z0-9-]*)$/.exec(path);
+				if (m) {
+					if (!can(currentUser(req), rights, m[1], "read")) return json(res, 404, { error: "no such board" }), true;
+					return json(res, 200, { events: readLog(commentsDir, m[1]) }), true;
+				}
+				if (path === "invite-info") {
+					if (limited(`ip:${ip}`)) return json(res, 429, { error: "too many attempts - wait a minute" }), true;
+					const info = inviteInfo(dataDir, String(url.searchParams.get("token") ?? ""));
+					return json(res, info ? 200 : 404, info ?? { error: "this invite link is invalid, expired, or already used" }), true;
+				}
+				if (path === "events") {
+					res.statusCode = 200;
+					res.setHeader("content-type", "text/event-stream");
+					res.setHeader("cache-control", "no-store");
+					res.setHeader("x-accel-buffering", "no");
+					res.write(": connected\n\n");
+					const lastRaw = String(req.headers["last-event-id"] ?? "");
+					const lm = /^([0-9a-f]{8})-(\d+)$/.exec(lastRaw);
+					if (lastRaw) {
+						const last = lm && lm[1] === bootEpoch ? Number(lm[2]) : NaN;
+						if (!Number.isFinite(last)) res.write("event: resync\ndata: {}\n\n");
+						else {
+							const missed = ring.filter((r) => r.seq > last);
+							if (missed.length && missed[0].seq !== last + 1) res.write("event: resync\ndata: {}\n\n");
+							else for (const r of missed) res.write(r.data);
+						}
+					}
+					clients.add(res);
+					req.on("close", () => clients.delete(res));
+					return true;
+				}
+				return false;
+			}
+			if (req.method !== "POST") return false;
+			if (path !== "auth/claim" && path !== "auth/signin" && !csrfOk(req)) return json(res, 403, { error: "missing or stale request token - reload the page" }), true;
+			if (path === "auth/claim") {
+				if (limited(`ip:${ip}`)) return json(res, 429, { error: "too many attempts - wait a minute" }), true;
+				const b = await readBody(req);
+				const { user, session } = claimInvite(dataDir, String(b.token ?? ""), {
+					password: String(b.password ?? ""),
+					name: String(b.name ?? ""),
+					avatar: validAvatar(b.avatar) ? b.avatar : void 0
+				});
+				setSession(req, res, session);
+				return json(res, 200, { user: publicUser(user) }), true;
+			}
+			if (path === "auth/signin") {
+				const b = await readBody(req);
+				const email = String(b.email ?? "").trim().toLowerCase();
+				if (limited(`ip:${ip}`, `em:${email}`)) return json(res, 429, { error: "too many attempts - wait a minute" }), true;
+				const hit = signIn(dataDir, email, String(b.password ?? ""));
+				if (!hit) return json(res, 401, { error: "wrong email or password" }), true;
+				setSession(req, res, hit.session);
+				return json(res, 200, { user: publicUser(hit.user) }), true;
+			}
+			if (path === "auth/signout") {
+				const tok = cookie(req, "mv_s");
+				if (tok) signOut(dataDir, tok);
+				res.setHeader("set-cookie", ["mv_s=; Path=/; Max-Age=0; HttpOnly", "mv_c=; Path=/; Max-Age=0"]);
+				return json(res, 200, {}), true;
+			}
+			if (path === "profile") {
+				const u = currentUser(req);
+				if (!u) return json(res, 401, { error: "sign in first" }), true;
+				const b = await readBody(req);
+				const next = updateProfile(dataDir, u.email, {
+					name: typeof b.name === "string" ? b.name : void 0,
+					avatar: b.avatar === "" ? "" : validAvatar(b.avatar) ? b.avatar : void 0
+				});
+				return json(res, 200, { user: publicUser(next) }), true;
+			}
+			if (path === "invite") {
+				if (!can(currentUser(req), rights, "", "admin")) return json(res, 403, { error: "owner only" }), true;
+				const b = await readBody(req);
+				const email = String(b.email ?? "");
+				if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) return json(res, 400, { error: "a valid email is required" }), true;
+				return json(res, 200, createInvite(dataDir, email)), true;
+			}
+			if (path === "revoke") {
+				if (!can(currentUser(req), rights, "", "admin")) return json(res, 403, { error: "owner only" }), true;
+				const b = await readBody(req);
+				revokeUser(dataDir, String(b.email ?? ""));
+				return json(res, 200, {}), true;
+			}
+			const m = /^comments\/([a-z0-9][a-z0-9-]*)$/.exec(path);
+			if (m) {
+				const u = currentUser(req);
+				if (!can(u, rights, m[1], "comment")) return json(res, u ? 403 : 401, { error: u ? `this board is read-only - ask ${ownerName(dataDir) ?? "the canvas owner"} for commenting access` : "sign in to comment" }), true;
+				const b = await readBody(req);
+				const incoming = Array.isArray(b.events) ? b.events : [];
+				if (incoming.length > 100) return json(res, 400, { error: "too many events in one push" }), true;
+				const bad = validateEvents(incoming, readLog(commentsDir, m[1]), u, m[1]);
+				if (bad) return json(res, 400, { error: bad }), true;
+				const fresh = appendEvents(commentsDir, m[1], incoming);
+				broadcast(m[1], fresh);
+				return json(res, 200, { accepted: fresh.length }), true;
+			}
+			return false;
+		} catch (err) {
+			return json(res, 400, { error: err.message }), true;
+		}
+	};
+}
+//#endregion
+export { collabHandler };

package/dist/comments-Ba8mU600.mjs

@@ -0,0 +1,90 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, statSync, writeSync } from "node:fs";
+import { join } from "node:path";
+//#region src/server/comments.ts
+/**
+* The comment event store (SPEC-M3 §1) - an append-only JSONL log, one file per board.
+*
+* Events are immutable and identified by client-generated UUIDs; two logs merge by SET
+* UNION on id. That single rule is the entire sync protocol: idempotent, order-
+* independent, retry-safe, tolerant of a deploy-overlap double-writer. Current thread
+* state is derived by replaying events (ordered by ts then id, last writer wins per
+* field). Files, not a database - tens to low hundreds of events per board.
+*/
+var comments_exports = /* @__PURE__ */ __exportAll({
+	appendEvents: () => appendEvents,
+	dataDir: () => dataDir,
+	listBoards: () => listBoards,
+	readLog: () => readLog
+});
+const BOARD_RE = /^[a-z0-9][a-z0-9-]*$/;
+const boardFile = (dir, board) => {
+	if (!BOARD_RE.test(board)) throw new Error(`bad board name: ${board}`);
+	return join(dir, `${board}.jsonl`);
+};
+/** Read one board's log. Unparseable lines are skipped, never fatal - an interrupted
+*  append must not take the whole board down. Duplicate ids keep the first occurrence. */
+function readLog(dir, board) {
+	const file = boardFile(dir, board);
+	if (!existsSync(file)) return [];
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const line of readFileSync(file, "utf8").split("\n")) {
+		if (!line.trim()) continue;
+		let ev;
+		try {
+			ev = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		if (typeof ev?.id !== "string" || !ev.id || seen.has(ev.id)) continue;
+		seen.add(ev.id);
+		out.push(ev);
+	}
+	return out;
+}
+/** Append events the log does not already hold; returns the ones actually written.
+*  This IS the merge rule - callers never need another. */
+function appendEvents(dir, board, events) {
+	mkdirSync(dir, { recursive: true });
+	const have = new Set(readLog(dir, board).map((e) => e.id));
+	const fresh = events.filter((e) => typeof e?.id === "string" && e.id && !have.has(e.id) && (have.add(e.id), true));
+	if (fresh.length) {
+		const file = boardFile(dir, board);
+		let lead = "";
+		if (existsSync(file)) {
+			const size = statSync(file).size;
+			if (size > 0) {
+				const fd = openSync(file, "r");
+				const last = Buffer.alloc(1);
+				readSync(fd, last, 0, 1, size - 1);
+				closeSync(fd);
+				if (last[0] !== 10) lead = "\n";
+			}
+		}
+		const fd = openSync(file, "a");
+		try {
+			writeSync(fd, lead + fresh.map((e) => JSON.stringify(e)).join("\n") + "\n");
+			fsyncSync(fd);
+		} finally {
+			closeSync(fd);
+		}
+	}
+	return fresh;
+}
+/** Board names present in a log directory. */
+function listBoards(dir) {
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir).filter((f) => f.endsWith(".jsonl")).map((f) => f.slice(0, -6)).filter((n) => BOARD_RE.test(n)).sort();
+}
+/** Where serve keeps its live store: MARVER_DATA_DIR is REQUIRED when collaboration is
+*  on - failing loudly beats silently writing into an ephemeral working directory that a
+*  redeploy wipes (SPEC-M3 §2). */
+function dataDir() {
+	const dir = process.env.MARVER_DATA_DIR;
+	if (!dir) throw new Error("collaboration needs a durable home: set MARVER_DATA_DIR to a directory on a persistent volume (comments written anywhere else would vanish on redeploy)");
+	mkdirSync(join(dir, "comments"), { recursive: true });
+	return dir;
+}
+//#endregion
+export { readLog as i, comments_exports as n, listBoards as r, appendEvents as t };

package/dist/comments-odHzYdO3.mjs

@@ -0,0 +1,179 @@
+import { n as NAME } from "./cli.mjs";
+import { i as syncOnce, n as connectClaim, o as replay, r as loadCollab, t as connect } from "./sync-CkBk-tUk.mjs";
+import { i as readLog, r as listBoards, t as appendEvents } from "./comments-Ba8mU600.mjs";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { randomUUID } from "node:crypto";
+//#region src/cli/comments.ts
+/**
+* `marver comments <action>` (SPEC-M3 §2, §9) - the collaboration CLI.
+*
+* connect <url>   sign in (or --invite <token> to claim) against a published canvas;
+*                 stores the device credential in design/.local/collab.json
+* sync            one full exchange with the publish target (agent/CI path)
+* list            threads from design/comments/ (--open, --board, --json)
+* reply <thread>  append a reply (--body) - the agent's voice in the loop
+* resolve <thread>  mark addressed (--addressed-in <frame> records WHICH variant)
+* invite <email>  mint a single-use invite link (owner only, needs connect first)
+* revoke <email>  revoke an account and its sessions (owner only)
+*/
+const ask = (q, hide = false) => new Promise((done) => {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	if (hide) {
+		const out = process.stdout;
+		const orig = rl._writeToOutput?.bind(rl);
+		rl._writeToOutput = (s) => {
+			if (s.includes("\n")) orig?.(s);
+			else {
+				out.clearLine?.(0);
+				out.cursorTo?.(0);
+				out.write(q);
+			}
+		};
+	}
+	rl.question(q, (a) => {
+		rl.close();
+		if (hide) process.stdout.write("\n");
+		done(a.trim());
+	});
+});
+const allThreads = (root, board) => {
+	const dir = join(root, "design", "comments");
+	return (board ? [board] : listBoards(dir)).flatMap((b) => replay(readLog(dir, b)).map((t) => ({
+		...t,
+		board: b
+	})));
+};
+async function commentsCommand(root, action, value, opts) {
+	switch (action) {
+		case "connect": {
+			if (!value) throw new Error("usage: comments connect <published-url>");
+			const canvasPassword = opts.canvasPassword ?? process.env.MARVER_PASSWORD ?? await ask("canvas password (blank if the canvas is ungated): ", true);
+			if (opts.invite) {
+				const name = opts.name ?? await ask("display name: ");
+				const password = opts.password ?? await ask("choose a password: ", true);
+				await connectClaim(root, value, String(opts.invite), {
+					password,
+					name
+				}, canvasPassword || void 0);
+			} else {
+				const email = opts.email ?? await ask("email: ");
+				const password = opts.password ?? await ask("password: ", true);
+				await connect(root, value, email, password, canvasPassword || void 0);
+			}
+			console.log(`[${NAME}] connected - design/.local/collab.json holds the device credential (gitignored)`);
+			console.log(`[${NAME}] \`${NAME} dev\` now syncs comments every 30s; \`${NAME} comments sync\` does one exchange`);
+			return;
+		}
+		case "sync": {
+			const collab = loadCollab(root);
+			if (!collab) throw new Error(`not connected - run \`${NAME} comments connect <url>\` first`);
+			const out = await syncOnce(root, collab);
+			for (const [b, n] of Object.entries(out)) console.log(`  ${b}: pulled ${n.pulled}, pushed ${n.pushed}`);
+			if (!Object.keys(out).length) console.log("  nothing to sync");
+			return;
+		}
+		case "list": {
+			let threads = allThreads(root, opts.board);
+			if (opts.open) threads = threads.filter((t) => !t.resolved);
+			if (opts.json) return void console.log(JSON.stringify(threads, null, 2));
+			if (!threads.length) return void console.log(`  no ${opts.open ? "open " : ""}comments`);
+			for (const t of threads) {
+				const anchor = t.frame ? ` on ${t.frame}` : "";
+				console.log(`  ${t.resolved ? "✓" : "○"} ${t.id}${anchor} - ${t.author?.name ?? "?"}: ${t.body ?? ""}${t.replies.length ? ` (+${t.replies.length})` : ""}${t.addressedIn ? ` → ${t.addressedIn}` : ""}`);
+			}
+			return;
+		}
+		case "reply": {
+			if (!value || !opts.body) throw new Error("usage: comments reply <thread-id> --body \"...\"");
+			const t = allThreads(root).find((t) => t.id === value);
+			if (!t) throw new Error(`no thread ${value} in design/comments/`);
+			appendEvents(join(root, "design", "comments"), t.board, [{
+				id: randomUUID(),
+				ts: Date.now(),
+				type: "reply",
+				commentId: randomUUID(),
+				parentId: t.id,
+				author: localAuthor(root),
+				body: String(opts.body)
+			}]);
+			await pushIfConnected(root);
+			console.log(`  replied to ${t.id}`);
+			return;
+		}
+		case "resolve": {
+			if (!value) throw new Error("usage: comments resolve <thread-id> [--addressed-in <frame>]");
+			const t = allThreads(root).find((t) => t.id === value);
+			if (!t) throw new Error(`no thread ${value} in design/comments/`);
+			appendEvents(join(root, "design", "comments"), t.board, [{
+				id: randomUUID(),
+				ts: Date.now(),
+				type: "resolve",
+				commentId: t.id,
+				...opts.addressedIn ? { addressedIn: String(opts.addressedIn) } : {}
+			}]);
+			await pushIfConnected(root);
+			console.log(`  resolved ${t.id}${opts.addressedIn ? ` - addressed in ${opts.addressedIn}` : ""}`);
+			return;
+		}
+		case "invite": {
+			if (!value || !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(value)) throw new Error("usage: comments invite <email>");
+			const { token } = await ownerApi(root, "invite", { email: value });
+			const url = loadCollab(root).url.replace(/\/+$/, "");
+			console.log(`  invite for ${value} (single-use, 7 days):`);
+			console.log(`    ${url}/#/i/${token}`);
+			console.log(`  send them that link (plus the canvas password) - it opens straight into`);
+			console.log(`  "pick your name and password".`);
+			return;
+		}
+		case "revoke":
+			if (!value) throw new Error("usage: comments revoke <email>");
+			await ownerApi(root, "revoke", { email: value });
+			console.log(`  revoked ${value} - their sessions are dead`);
+			return;
+		default: throw new Error(`unknown action "${action}" - connect | sync | list | reply | resolve | invite | revoke`);
+	}
+}
+/** Owner-only account call against the connected canvas, via the device credential. */
+const ownerApi = async (root, path, body) => {
+	const collab = loadCollab(root);
+	if (!collab) throw new Error(`not connected - run \`${NAME} comments connect <url>\` first`);
+	const res = await fetch(`${collab.url.replace(/\/+$/, "")}/__mv/api/${path}`, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${collab.token}`,
+			"content-type": "application/json"
+		},
+		body: JSON.stringify(body)
+	});
+	const data = await res.json().catch(() => ({}));
+	if (!res.ok) throw new Error(data.error ?? `canvas answered ${res.status}`);
+	return data;
+};
+const pushIfConnected = async (root) => {
+	const collab = loadCollab(root);
+	if (collab) await syncOnce(root, collab).catch((e) => console.log(`  (push deferred: ${e.message})`));
+};
+/** Author snapshot for CLI-born events: the connected account (the server validates
+*  authors against the session - an authorless push would be rejected), else the
+*  local dev profile. */
+const localAuthor = (root) => {
+	const collab = loadCollab(root);
+	if (collab?.email) return {
+		email: collab.email,
+		name: collab.name
+	};
+	try {
+		const p = JSON.parse(readFileSync(join(root, "design", ".local", "profile.json"), "utf8"));
+		if (p?.email) return {
+			email: p.email,
+			name: p.name
+		};
+	} catch {}
+};
+//#endregion
+export { commentsCommand };