cozyclay 1.3.0 → 1.6.0

package/bin/cozyclay.mjs

@@ -8,24 +8,49 @@
  * `dist/`, so this launcher only has to
  *
  *   - serve those files over loopback,
- *   - forward /ardy to the sidecar on 5181 (the job Vite's dev proxy does),
+ *   - forward /ardy to its dynamically selected sidecar port (the job Vite's dev proxy does),
  *   - keep the sidecar's lifetime tied to this process.
  *
  * It has no dependencies on purpose. A launcher that needs an install step
  * before it can serve a prebuilt app is a launcher that will break.
  */
 import { spawn } from "node:child_process";
-import { createReadStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { startBridge, terminateOwned } from "../tools/process-supervisor.mjs";
+import { createReadStream, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { createServer, request as httpRequest } from "node:http";
 import { homedir } from "node:os";
 import { extname, join, normalize, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
+import { runMcp } from "./mcp-runtime.mjs";
+import { openBrowser } from "./open-browser.mjs";
+import { checkForUpdate, runUpdate } from "./update-check.mjs";
+import { verifyPackageMarker } from "./package-signature.mjs";
+import {
+	markTelemetryNoticeShown,
+	markTelemetryFirstLaunch,
+	effectiveTelemetryEnabled,
+	readTelemetryState,
+	setTelemetryEnabled,
+	takeRuntimeTelemetryConfig,
+	TELEMETRY_NOTICE_VERSION,
+} from "./telemetry-state.mjs";
 
 const PKG_ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)));
+let packageMetadata = {};
+try {
+	packageMetadata = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8"));
+} catch {
+	// An unreadable package is handled by the existing missing-build checks.
+}
 const DIST = join(PKG_ROOT, "dist");
 const BRIDGE = join(PKG_ROOT, "tools", "ardy", "bridge.mjs");
-const BRIDGE_PORT = Number(process.env.COZYCLAY_BRIDGE_PORT ?? 5181);
+const OFFICIAL_PACKAGE = (
+	packageMetadata.name === "cozyclay"
+	&& !existsSync(join(PKG_ROOT, ".git"))
+	&& verifyPackageMarker(join(DIST, "cozyclay-package.json"), PKG_ROOT, packageMetadata)
+);
+let bridgePort = 5181;
 
 const TYPES = {
 	".html": "text/html; charset=utf-8",
@@ -45,7 +70,7 @@ const TYPES = {
 };
 
 function parseArgs(argv) {
-	const opts = { port: 5180, host: "127.0.0.1", ardy: true, open: true, star: true };
+	const opts = { port: 5180, host: "127.0.0.1", ardy: true, open: true, star: true, updateCheck: true };
 	for (let i = 0; i < argv.length; i += 1) {
 		const arg = argv[i];
 		if (arg === "--port" || arg === "-p") opts.port = Number(argv[++i]);
@@ -55,21 +80,29 @@ function parseArgs(argv) {
 		else if (arg === "--no-ardy") opts.ardy = false;
 		else if (arg === "--no-open") opts.open = false;
 		else if (arg === "--no-star") opts.star = false;
+		else if (arg === "--no-update-check") opts.updateCheck = false;
 		else if (arg === "--help" || arg === "-h") opts.help = true;
 		else if (arg === "--version" || arg === "-v") opts.version = true;
 		else {
 			console.error(`cozyclay: unknown option ${arg}`);
 			opts.help = true;
+			opts.invalid = true;
 		}
 	}
-	if (!Number.isInteger(opts.port) || opts.port < 1 || opts.port > 65535) {
-		console.error("cozyclay: --port must be a port number");
+	if (!Number.isInteger(opts.port) || opts.port < 1 || opts.port > 65534) {
+		console.error("cozyclay: --port must be an integer in 1..65534");
+		opts.help = true;
+		opts.invalid = true;
+	}
+	if (opts.host !== "127.0.0.1") {
+		console.error("cozyclay: --host is restricted to 127.0.0.1");
 		opts.help = true;
+		opts.invalid = true;
 	}
 	return opts;
 }
 
-const REPO_URL = "https://github.com/HaD0Yun/CozyClay";
+const REPO_URL = "https://github.com/NomaDamas/CozyClay";
 const STATE_DIR = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "cozyclay");
 const STATE_FILE = join(STATE_DIR, "state.json");
 // Only worth asking someone who actually used the thing. A prompt three
@@ -80,10 +113,18 @@ const HELP = `cozyclay - browser-based 3D staging studio
 
   npx cozyclay              start the studio and open it
   npx cozyclay mcp          run the MCP server (for Claude, Cursor, any MCP client)
+  cclay update              install the latest cozyclay globally (npm install -g)
   npx cozyclay --port 5200  serve on another port
   npx cozyclay --no-ardy    skip the optional motion-generation sidecar
   npx cozyclay --no-open    do not open a browser
   npx cozyclay --no-star    never ask about starring the repo
+  npx cozyclay --no-update-check
+                            do not look for a newer release
+  cclay telemetry status   show anonymous telemetry status
+  cclay telemetry off      disable anonymous telemetry
+  cclay telemetry on       enable anonymous telemetry
+
+cclay is the same command, shorter: a global install gives you both.
 
 Motion generation needs an SSH-reachable NVIDIA machine running ARDY; point
 the sidecar at it with CCLAY_ARDY_HOST. Everything else - staging, posing,
@@ -105,7 +146,7 @@ function serveFile(res, path) {
 // browser code needs no build-time knowledge of how it was launched.
 function proxyToBridge(req, res) {
 	const upstream = httpRequest(
-		{ host: "127.0.0.1", port: BRIDGE_PORT, path: req.url, method: req.method, headers: req.headers },
+		{ host: "127.0.0.1", port: bridgePort, path: req.url, method: req.method, headers: req.headers },
 		(upstreamRes) => {
 			res.writeHead(upstreamRes.statusCode ?? 502, upstreamRes.headers);
 			upstreamRes.pipe(res);
@@ -131,7 +172,9 @@ function readState() {
 function writeState(patch) {
 	try {
 		mkdirSync(STATE_DIR, { recursive: true });
-		writeFileSync(STATE_FILE, JSON.stringify({ ...readState(), ...patch }, null, "\t"));
+		const temporary = `${STATE_FILE}.${process.pid}.tmp`;
+		writeFileSync(temporary, JSON.stringify({ ...readState(), ...patch }, null, "\t"), { mode: 0o600 });
+		renameSync(temporary, STATE_FILE);
 	} catch {
 		/* a read-only home is not a reason to fail a local dev server */
 	}
@@ -139,7 +182,7 @@ function writeState(patch) {
 
 async function starCount() {
 	try {
-		const res = await fetch("https://api.github.com/repos/HaD0Yun/CozyClay", {
+		const res = await fetch("https://api.github.com/repos/NomaDamas/CozyClay", {
 			headers: { accept: "application/vnd.github+json" },
 			signal: AbortSignal.timeout(2500),
 		});
@@ -180,69 +223,70 @@ async function maybeAskForStar(startedAt, opts) {
 	}
 }
 
-function openBrowser(url) {
-	const cmd =
-		process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-	const child = spawn(cmd, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" });
-	child.on("error", () => {
-		/* headless box, no browser: the URL is printed anyway */
-	});
-	child.unref();
+// Read on every launch now, so it must not be able to take the launcher down:
+// the version is cosmetic here, and "0.0.0" just suppresses a bogus notice.
+function readVersion() {
+	return typeof packageMetadata.version === "string" ? packageMetadata.version : "0.0.0";
 }
 
-/**
- * `cozyclay mcp` hands over to the MCP server.
- *
- * Its dependencies are NOT the launcher's: the studio path stays dependency
- * free on purpose, and the MCP SDK is a 95-package tree nobody who only wants
- * a viewport should download. So the server ships with the package, its deps
- * are installed on demand, and a missing one produces an exact instruction
- * rather than a stack trace.
- */
-async function runMcp(rest) {
-	const server = join(PKG_ROOT, "mcp", "server.mjs");
-	if (!existsSync(server)) {
-		console.error("cozyclay: this build does not include the MCP server.");
+const argv = process.argv.slice(2);
+if (argv[0] === "mcp") {
+	await runMcp(argv.slice(1));
+} else if (argv[0] === "update") {
+	// This branch bypasses parseArgs, so anything trailing would be swallowed
+	// and `cclay update --help` would perform an unrequested global install.
+	if (argv.length > 1) {
+		console.error(`cozyclay: update takes no arguments (got ${argv.slice(1).join(" ")})`);
 		process.exit(1);
 	}
-	// The deps must land in the PACKAGE root, not in mcp/: server.mjs imports
-	// ../src/*.js, and those files resolve `three` from cozyclay/ itself.
-	try {
-		await import("@modelcontextprotocol/sdk/server/mcp.js");
-		await import("three");
-	} catch {
-		console.error(
-			[
-				"cozyclay: the MCP server needs four packages the studio does not.",
-				"",
-				`  npm install --prefix ${JSON.stringify(PKG_ROOT)} \\`,
-				"    @modelcontextprotocol/sdk ws zod three",
-				"",
-				"Then run `npx cozyclay mcp` again. They are kept out of the default",
-				"install so opening the studio never waits on a 95-package tree.",
-			].join("\n"),
-		);
+	runUpdate();
+} else if (argv[0] === "telemetry") {
+	const action = argv[1] ?? "status";
+	if (argv.length > 2 || !["status", "on", "off"].includes(action)) {
+		console.error("cozyclay: telemetry accepts status, on, or off");
 		process.exit(1);
 	}
-	const child = spawn(process.execPath, [server, ...rest], { stdio: "inherit" });
-	child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
-}
-
-const argv = process.argv.slice(2);
-if (argv[0] === "mcp") {
-	await runMcp(argv.slice(1));
+	if (action === "on") setTelemetryEnabled(STATE_FILE, true);
+	if (action === "off") setTelemetryEnabled(STATE_FILE, false);
+	const state = readTelemetryState(STATE_FILE);
+	const effective = OFFICIAL_PACKAGE && effectiveTelemetryEnabled(state);
+	const reason = !OFFICIAL_PACKAGE
+		? " (source checkout)"
+		: state.telemetryEnabled && !effective
+			? " (environment override)"
+			: "";
+	console.log(`Telemetry: ${effective ? "on" : "off"}${reason}`);
+	if (action !== "status") console.log("Reload any open CozyClay studio tab to apply this setting.");
 } else {
 
 const opts = parseArgs(argv);
-if (opts.help) {
-	console.log(HELP);
-	process.exit(0);
+	if (opts.help) {
+		console.log(HELP);
+		process.exit(opts.invalid ? 1 : 0);
 }
+const version = readVersion();
 if (opts.version) {
-	const pkg = JSON.parse(await import("node:fs").then((fs) => fs.promises.readFile(join(PKG_ROOT, "package.json"), "utf8")));
-	console.log(pkg.version);
+	console.log(version);
 	process.exit(0);
 }
+let runtimeTelemetry = takeRuntimeTelemetryConfig(STATE_FILE, {
+	appVersion: version,
+	officialPackage: OFFICIAL_PACKAGE,
+});
+const telemetryState = readTelemetryState(STATE_FILE);
+if (
+	runtimeTelemetry.telemetryEnabled
+	&& telemetryState.noticeVersion < TELEMETRY_NOTICE_VERSION
+) {
+	console.log(
+		"Anonymous usage metrics are on (no prompts, project content, filenames, or account information).\n" +
+			"Disable anytime: cclay telemetry off",
+	);
+	markTelemetryNoticeShown(STATE_FILE);
+}
+// Fired before anything blocking and never awaited on the launch path: the
+// notice is worth a line of output, never a second of startup.
+const updatePending = opts.updateCheck && !process.env.CI && !process.env.COZYCLAY_NO_UPDATE_CHECK ? checkForUpdate(version, STATE_DIR) : null;
 if (!existsSync(join(DIST, "app", "index.html"))) {
 	console.error("cozyclay: this package is missing its build (dist/app/index.html).");
 	console.error("cozyclay: from a clone, run `npm install && npm run build` first.");
@@ -254,15 +298,98 @@ if (!existsSync(join(DIST, "app", "index.html"))) {
 // cannot act on. An unset CCLAY_ARDY_HOST is the normal case, not a fault.
 const ardyHost = process.env.CCLAY_ARDY_HOST?.trim();
 let bridge = null;
+let server = null;
+const startedAt = Date.now();
+let shuttingDown = false;
+async function shutdown(exitCode = 0) {
+	if (shuttingDown) return;
+	shuttingDown = true;
+	if (bridge) await terminateOwned(bridge);
+	if (server?.listening) await new Promise((resolvePromise) => server.close(() => resolvePromise()));
+	try {
+		await maybeAskForStar(startedAt, opts);
+	} catch {
+		/* never let the goodbye prompt hold the process hostage */
+	}
+	process.exit(exitCode);
+}
+process.on("SIGINT", () => shutdown(130));
+process.on("SIGTERM", () => shutdown(143));
+
 if (opts.ardy && ardyHost && existsSync(BRIDGE)) {
-	bridge = spawn(process.execPath, [BRIDGE], { cwd: PKG_ROOT, stdio: "inherit" });
-	bridge.on("error", () => {
-		bridge = null;
-	});
+	try {
+		({ child: bridge, port: bridgePort } = await startBridge({
+			command: process.execPath,
+			args: [BRIDGE],
+			cwd: PKG_ROOT,
+			env: process.env,
+			mainPort: opts.port,
+			onSpawn: (child) => {
+				bridge = child;
+			},
+			onReady: (child) => {
+				child.once("exit", (code, signal) => {
+					if (shuttingDown) return;
+					console.error(`cozyclay: motion generation sidecar exited ${signal ? `from ${signal}` : `with code ${code ?? 0}`}.`);
+					void shutdown(1);
+				});
+				child.once("error", (err) => {
+					if (shuttingDown) return;
+					console.error(`cozyclay: motion generation sidecar failed: ${err.message}`);
+					void shutdown(1);
+				});
+			},
+		}));
+	} catch (err) {
+		console.error(`cozyclay: motion generation sidecar failed: ${err.message}`);
+		console.error("cozyclay: studio did not start; set COZYCLAY_BRIDGE_PORT to an available port or use --no-ardy.");
+		if (bridge) await terminateOwned(bridge);
+		process.exit(1);
+	}
 }
 
-const server = createServer((req, res) => {
+server = createServer((req, res) => {
 	const url = new URL(req.url ?? "/", "http://localhost");
+	if (url.pathname === "/__cozyclay/telemetry") {
+		if (req.method === "POST") {
+			const origin = req.headers.origin;
+			const expectedOrigin = `http://127.0.0.1:${opts.port}`;
+			if (origin !== expectedOrigin) {
+				res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
+				res.end(JSON.stringify({ error: "forbidden origin" }));
+				return;
+			}
+			let body = "";
+			req.setEncoding("utf8");
+			req.on("data", (chunk) => {
+				body += chunk;
+				if (body.length > 1024) req.destroy();
+			});
+			req.on("end", () => {
+				try {
+					const value = JSON.parse(body);
+					if (typeof value.enabled !== "boolean") throw new TypeError("enabled must be boolean");
+					setTelemetryEnabled(STATE_FILE, value.enabled);
+					runtimeTelemetry = takeRuntimeTelemetryConfig(STATE_FILE, {
+						appVersion: version,
+						officialPackage: OFFICIAL_PACKAGE,
+					});
+					res.writeHead(200, {
+						"content-type": "application/json; charset=utf-8",
+						"cache-control": "no-store",
+					});
+					res.end(JSON.stringify(runtimeTelemetry));
+				} catch {
+					res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+					res.end(JSON.stringify({ error: "invalid telemetry setting" }));
+				}
+			});
+			return;
+		}
+		res.writeHead(405, { allow: "POST", "content-type": "application/json; charset=utf-8" });
+		res.end(JSON.stringify({ error: "method not allowed" }));
+		return;
+	}
 	// Only the routes the bridge actually owns: /ardy/ is ALSO a public asset
 	// directory (cskel27-rest.json), and those files live in dist/, not behind
 	// the sidecar. Same rule as the Vite dev proxy bypass.
@@ -270,7 +397,14 @@ const server = createServer((req, res) => {
 		proxyToBridge(req, res);
 		return;
 	}
-	const rel = decodeURIComponent(url.pathname);
+	let rel;
+	try {
+		rel = decodeURIComponent(url.pathname);
+	} catch {
+		res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+		res.end("invalid URL encoding");
+		return;
+	}
 	// normalize + prefix check: a request must not escape dist/.
 	let target = join(DIST, normalize(rel));
 	if (!target.startsWith(DIST)) {
@@ -289,41 +423,44 @@ const server = createServer((req, res) => {
 		res.end("not found");
 		return;
 	}
+	if (target === join(DIST, "app", "index.html")) {
+		runtimeTelemetry = takeRuntimeTelemetryConfig(STATE_FILE, {
+			appVersion: version,
+			officialPackage: OFFICIAL_PACKAGE,
+		});
+		const runtime = runtimeTelemetry;
+		if (runtime.firstLaunch) {
+			markTelemetryFirstLaunch(STATE_FILE);
+		}
+		const script = `<script>window.__COZYCLAY_RUNTIME__ = ${JSON.stringify(runtime).replaceAll("<", "\\u003c")};</script>`;
+		const html = readFileSync(target, "utf8").replace("</head>", `${script}\n</head>`);
+		res.writeHead(200, {
+			"content-type": "text/html; charset=utf-8",
+			"content-length": Buffer.byteLength(html),
+			"cache-control": "no-store",
+		});
+		res.end(html);
+		return;
+	}
 	serveFile(res, target);
 });
 
-const startedAt = Date.now();
-let shuttingDown = false;
-async function shutdown() {
-	if (shuttingDown) process.exit(0);
-	shuttingDown = true;
-	if (bridge) bridge.kill("SIGTERM");
-	server.close();
-	try {
-		await maybeAskForStar(startedAt, opts);
-	} catch {
-		/* never let the goodbye prompt hold the process hostage */
-	}
-	process.exit(0);
-}
-process.on("SIGINT", shutdown);
-process.on("SIGTERM", shutdown);
-
 server.on("error", (err) => {
 	if (err && err.code === "EADDRINUSE") {
-		console.error(`cozyclay: port ${opts.port} is taken. Try --port ${opts.port + 1}.`);
-		if (bridge) bridge.kill("SIGTERM");
-		process.exit(1);
+		console.error(`cozyclay: port ${opts.port} is taken. Try --port 5200.`);
+		void shutdown(1);
+		return;
 	}
 	throw err;
 });
 
-server.listen(opts.port, opts.host, () => {
+server.listen({ port: opts.port, host: "127.0.0.1", ipv6Only: false }, () => {
 	// The package exists to open the studio, which the site serves from /app/.
 	// Landing on "/" would greet someone who just typed `npx cozyclay` with a
 	// marketing page.
-	const url = `http://${opts.host}:${opts.port}/app/`;
+	const url = `http://127.0.0.1:${opts.port}/app/`;
 	console.log(`CozyClay is running at ${url}`);
+	console.log("Use a Chromium-based browser — Safari and Firefox are not supported.");
 	if (!opts.ardy) console.log("Motion generation: off (--no-ardy).");
 	else if (bridge) console.log(`Motion generation: sidecar running against ${ardyHost}.`);
 	else
@@ -332,6 +469,11 @@ server.listen(opts.port, opts.host, () => {
 				"set CCLAY_ARDY_HOST=user@host to turn it on. Everything else works without it.",
 		);
 	if (opts.open) openBrowser(url);
+	void updatePending?.then((latest) => {
+		// `cclay` only exists after a global install, so name the command that
+		// works from an npx run too.
+		if (latest) console.log(`cozyclay ${latest} is available (you have ${version}). Run: npm install -g cozyclay@latest`);
+	});
 });
 
 }

package/bin/mcp-runtime.mjs

@@ -0,0 +1,115 @@
+import { spawn } from "node:child_process";
+import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, renameSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const PKG_ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const PACKAGE_VERSION = JSON.parse(await import("node:fs/promises").then((fs) => fs.readFile(join(PKG_ROOT, "package.json"), "utf8"))).version;
+const MCP_RUNTIME_SOURCE = join(PKG_ROOT, "mcp", "runtime");
+const MCP_RUNTIME = process.env.COZYCLAY_MCP_RUNTIME_DIR || join(
+	process.env.XDG_CACHE_HOME || process.env.LOCALAPPDATA || join(homedir(), ".cache"),
+	"cozyclay",
+	"mcp-runtime",
+	PACKAGE_VERSION,
+);
+
+function probeMcpRuntime(runtime = MCP_RUNTIME) {
+	const server = join(runtime, "mcp", "server.mjs");
+	if (!existsSync(server)) throw new Error("MCP server is missing");
+	const runtimeRequire = createRequire(join(runtime, "package.json"));
+	for (const dependency of ["@modelcontextprotocol/sdk/server/mcp.js", "three", "ws", "zod"]) runtimeRequire.resolve(dependency);
+	return server;
+}
+
+function installMcpRuntime() {
+	return new Promise((done) => {
+		const parent = dirname(MCP_RUNTIME);
+		mkdirSync(parent, { recursive: true });
+		try {
+			probeMcpRuntime();
+			done({ code: 0 });
+			return;
+		} catch {
+			// A killed older install can leave an incomplete final directory.
+			// Only complete stagings are ever renamed here, so an invalid final
+			// cache is safe to discard before this attempt begins.
+			rmSync(MCP_RUNTIME, { recursive: true, force: true });
+		}
+		const staging = mkdtempSync(join(parent, `${basename(MCP_RUNTIME)}.install-`));
+		copyFileSync(join(MCP_RUNTIME_SOURCE, "package.json"), join(staging, "package.json"));
+		copyFileSync(join(MCP_RUNTIME_SOURCE, "package-lock.json"), join(staging, "package-lock.json"));
+		cpSync(join(PKG_ROOT, "mcp"), join(staging, "mcp"), { recursive: true });
+		cpSync(join(PKG_ROOT, "src"), join(staging, "src"), { recursive: true });
+
+		const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+		const child = spawn(npm, ["ci", "--no-audit", "--no-fund"], {
+			cwd: staging,
+			stdio: ["ignore", "pipe", "pipe"],
+			shell: process.platform === "win32",
+		});
+		child.stdout.pipe(process.stderr);
+		child.stderr.pipe(process.stderr);
+		child.on("error", (error) => {
+			rmSync(staging, { recursive: true, force: true });
+			done({ code: 1, error });
+		});
+		child.on("exit", (code) => {
+			if (code !== 0) {
+				rmSync(staging, { recursive: true, force: true });
+				done({ code: code ?? 1 });
+				return;
+			}
+			try {
+				probeMcpRuntime(staging);
+				try {
+					probeMcpRuntime();
+					rmSync(staging, { recursive: true, force: true });
+				} catch {
+					try {
+						renameSync(staging, MCP_RUNTIME);
+					} catch (error) {
+						// Another first run can publish its complete staging
+						// directory first. Accept that winner only after the
+						// same full probe; never execute a partial cache.
+						probeMcpRuntime();
+						rmSync(staging, { recursive: true, force: true });
+					}
+				}
+				done({ code: 0 });
+			} catch (error) {
+				rmSync(staging, { recursive: true, force: true });
+				done({ code: 1, error });
+			}
+		});
+	});
+}
+
+export async function runMcp(rest) {
+	if (!existsSync(join(PKG_ROOT, "mcp", "server.mjs")) || !existsSync(join(MCP_RUNTIME_SOURCE, "package-lock.json"))) {
+		console.error("cozyclay: this build does not include the MCP server runtime.");
+		process.exit(1);
+	}
+
+	let server;
+	try {
+		server = probeMcpRuntime();
+	} catch {
+		console.error("cozyclay: installing MCP server dependencies (one-time per CozyClay version)...");
+		const result = await installMcpRuntime();
+		if (result.code !== 0) {
+			console.error(`cozyclay: npm ci failed${result.error ? `: ${result.error.message}` : ` (exit ${result.code})`}. Check your network connection and retry.`);
+			console.error(`cozyclay: the published package was not changed; remove ${JSON.stringify(MCP_RUNTIME)} before retrying a damaged cache.`);
+			process.exit(1);
+		}
+		try {
+			server = probeMcpRuntime();
+		} catch (error) {
+			console.error(`cozyclay: MCP runtime is incomplete after npm ci: ${error.message}`);
+			process.exit(1);
+		}
+	}
+	const child = spawn(process.execPath, [server, ...rest], { stdio: "inherit" });
+	child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+}

package/bin/open-browser.mjs

@@ -0,0 +1,10 @@
+import { spawn } from "node:child_process";
+
+export function openBrowser(url) {
+	const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+	const child = spawn(command, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" });
+	child.on("error", () => {
+		/* headless box, no browser: the URL is printed anyway */
+	});
+	child.unref();
+}

package/bin/package-signature.mjs

@@ -0,0 +1,95 @@
+import { createHash, createPublicKey, verify } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+
+export const PACKAGE_SIGNATURE_PUBLIC_KEY = "MCowBQYDK2VwAyEAiDLutMZ8CX/NzpuQF/juhT8v9QwPBUvIOHFRqEZoG3U=";
+
+const CONTENT_ROOTS = [
+	"bin",
+	"dist",
+	"src",
+	"tools",
+	"mcp/runtime",
+	"mcp/server.mjs",
+	"mcp/live-hub.mjs",
+	"mcp/ardy-prompts.mjs",
+	"mcp/package.json",
+	"mcp/README.md",
+	"mcp/LIVE-PROTOCOL.md",
+	"package.json",
+	"README.md",
+	"CHANGELOG.md",
+	"LICENSE",
+	"LICENSES",
+	"LICENSING.md",
+	"THIRD_PARTY_NOTICES.md",
+];
+
+function ignored(relativePath) {
+	return relativePath === "dist/cozyclay-package.json"
+		|| (/^dist\/media\/[^/]+\.mp4$/i.test(relativePath))
+		|| relativePath.startsWith("tools/ardy/out/")
+		|| /^tools\/qa-[^/]+\.mjs$/i.test(relativePath);
+}
+
+function collectFiles(path, packageRoot, output) {
+	let entries;
+	try {
+		entries = readdirSync(path, { withFileTypes: true });
+	} catch (error) {
+		if (error?.code === "ENOTDIR") {
+			const relativePath = relative(packageRoot, path).split(sep).join("/");
+			if (!ignored(relativePath)) output.push({ path, relativePath });
+			return;
+		}
+		if (error?.code === "ENOENT") return;
+		throw error;
+	}
+	for (const entry of entries) {
+		const child = join(path, entry.name);
+		const relativePath = relative(packageRoot, child).split(sep).join("/");
+		if (ignored(relativePath)) continue;
+		if (entry.isDirectory()) collectFiles(child, packageRoot, output);
+		if (entry.isFile()) output.push({ path: child, relativePath });
+	}
+}
+
+export function computePackageDigest(packageRoot) {
+	const absoluteRoot = resolve(packageRoot);
+	const files = [];
+	for (const entry of CONTENT_ROOTS) collectFiles(join(absoluteRoot, entry), absoluteRoot, files);
+	files.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+	const hash = createHash("sha256");
+	for (const file of files) {
+		hash.update(file.relativePath);
+		hash.update("\0");
+		hash.update(readFileSync(file.path));
+		hash.update("\0");
+	}
+	return hash.digest("hex");
+}
+
+export function verifyPackageMarker(
+	markerFile,
+	packageRoot,
+	packageMetadata,
+	publicKeyBase64 = PACKAGE_SIGNATURE_PUBLIC_KEY,
+) {
+	try {
+		const marker = JSON.parse(readFileSync(markerFile, "utf8"));
+		const payload = JSON.parse(marker.payload);
+		if (payload.distribution !== "npm") return false;
+		if (payload.package !== "cozyclay") return false;
+		if (payload.version !== packageMetadata.version) return false;
+		if (payload.repository !== "NomaDamas/CozyClay") return false;
+		if (payload.content_sha256 !== computePackageDigest(packageRoot)) return false;
+		const publicKey = createPublicKey({
+			key: Buffer.from(publicKeyBase64, "base64"),
+			format: "der",
+			type: "spki",
+		});
+		return verify(null, Buffer.from(marker.payload), publicKey, Buffer.from(marker.signature, "base64"));
+	} catch {
+		return false;
+	}
+}