cozyclay 3.1.3 → 3.1.5

package/CHANGELOG.md

@@ -2,6 +2,104 @@
 
 ## Unreleased
 
+## 3.1.5 - 2026-10-25
+
+The Studio tells you when a new release is out and installs it in one click, Claude models work in the agent panel again, IK edits stay on their own character, turns and walks look more natural, and anonymous analytics show where the Studio gets in the way.
+
+Agent
+
+- Agent turns on Claude models no longer fail with a 400 error about a
+  deferred placeholder tool.
+- When a turn is already running, the failure chip reads `busy` instead of
+  `upstream`. The message text is unchanged.
+
+Motion
+
+- The head turns first and leads the body into a turn, by about 5 frames at
+  24 fps, the way a person's does. `flow.headLead` sets the frames (0 to
+  12), and `false` turns it off. A keyed head look still wins.
+- Takes that walk report `observations.gait`: cadence, step length, speed,
+  stance and pelvis motion, with warnings outside a person's range. It is a
+  reading only and never changes the QA result.
+- Grasp QA reads each finger: `FINGER_ROM` (a joint past its range),
+  `FINGER_SELF` (two fingers inside each other) and `THUMB_OFF` (a held
+  object without the thumb on it).
+- A carried ball keeps the thumb on it. A finger that misses a held object
+  turns toward it at the knuckle, and the ring and little fingers curl
+  together. Stacked hand presets no longer over-curl.
+
+Studio
+
+- An npm studio shows a small **Update** chip in the top bar when a newer
+  release is out, once per version. A global install whose folder npm can
+  write gets **Update now**, which installs the release and then asks you
+  to restart `cclay`. Other installs get the command to copy, and npx gets
+  "run `npx cozyclay` again". **Update now** waits while an agent turn,
+  an export or a recording runs. A failed install names the cause
+  (permissions, network, Node version, npm missing) and keeps the command.
+- An IK edit stays with its own character. Selecting another character
+  mid-drag no longer poses it, and undo no longer reverts or deletes the
+  other character. Switching characters applies a pending IK edit and shows
+  a notice.
+- Ctrl+Z after an IK drag puts the pose back, with or without a take
+  loaded.
+- On a browser without WebGL, the unavailable notice appears one frame
+  after the Studio first draws instead of during it.
+
+CLI
+
+- `cclay update --check` prints the current and latest version without
+  installing, and exits 0 (up to date), 10 (update available) or 11
+  (unknown). `cclay update` now refuses a release your Node.js cannot run.
+- A source checkout reports itself as `clone`, and a Windows global install
+  is no longer mistaken for npx.
+
+Site
+
+- A redesigned cozyclay.org: a black first screen with a greybox-to-video
+  reel, how-it-works clips from the tutorial, and Try it opens the Studio.
+
+Analytics
+
+- The anonymous usage analytics now cover where the Studio gets in the way:
+  - the agent loop: refused commands, a summary per agent turn, each motion
+    draft and its QA result, and each prompt sent, so retry loops and
+    hesitation show
+  - model connect: the sign-in steps and where they stop, and model changes
+  - exports: retries, the stage a failed or stopped export reached, and
+    saved files. Storyboard PNG, render pass and OTIO exports are now
+    counted.
+  - clicks, shortcuts and search: repeated or dead clicks on the main
+    controls, shortcuts that did nothing, searches with no result, and
+    switching panels or orbiting the camera back and forth
+  - playback, boot and crashes: time to the first frame, playback runs and
+    late frames, the first-success guide, render crashes and lost WebGL
+  - the update notice: when it shows, which button was pressed, and whether
+    the install worked
+  - one friction summary per session
+- Every value is a closed bucket or a fixed id. No text, names, paths,
+  object ids, click coordinates or npm output are sent. Prompt text never
+  leaves the browser; only a length bucket and a similarity grade to the
+  last prompt do.
+- First-edit events count only your own edits, not the agent's, and report
+  `definition_version` 2.
+- Events that nothing sent any more are removed: the old motion-generation
+  events and `sample:played`.
+- The privacy page lists every event and property. `cclay telemetry off`
+  still turns it all off.
+
+## 3.1.4 - 2026-10-24
+
+Starring CozyClay from the terminal takes one key when the GitHub CLI is signed in.
+
+CLI
+
+- The one-time star question on exit stars NomaDamas/CozyClay through `gh`
+  when `gh` is installed and signed in: answer `y` and it is done, with no
+  browser. An account that already starred the repo is not asked. Without
+  `gh` the question opens the repo page as before, and `--no-star`,
+  `COZYCLAY_NO_STAR` and CI still turn it off.
+
 ## 3.1.3 - 2026-10-24
 
 More ways to connect a model (Claude Pro/Max, OpenAI-compatible servers, MiniMax M3.1 Flash), a Simplified Chinese UI, and easier project opening.

package/INSTALL_FOR_AGENTS.md

@@ -32,6 +32,9 @@ npx -y cozyclay --no-star
 
 For a permanent install, run `npm install -g cozyclay`. Then `cclay` and `cozyclay` are the same
 command. `cclay update` installs the latest release.
+`cclay update --check` installs nothing. It prints the current version, the latest version and
+the install kind, then exits `0` when up to date, `10` when an update is available, and `11` when
+it cannot tell (offline, or checks turned off).
 
 Tell the user:
 

package/README.md

@@ -58,6 +58,11 @@ npx cozyclay
 That is the whole install. You need Node.js 22.19 or newer and a Chromium browser. You do not need
 a GPU, Python or a model download. The studio opens at `http://127.0.0.1:5180/app/`.
 
+**Updating.** `npx cozyclay` fetches the newest release each time you run it. After
+`npm install -g cozyclay`, the studio shows a small **Update** chip in the top bar when a newer
+release is out. **Update now** installs it, and then you restart `cclay`. `cclay update` does the
+same from the terminal. `--no-update-check` or `COZYCLAY_NO_UPDATE_CHECK=1` turns the check off.
+
 > **Asking an AI agent to set it up?** Give it this repository link. Its instructions are in
 > [`INSTALL_FOR_AGENTS.md`](INSTALL_FOR_AGENTS.md).
 

package/bin/agent/agent-failure-codes.mjs

@@ -0,0 +1,31 @@
+// The closed `agent:turn_failed.failure_code` vocabulary, sidecar side. Kept
+// self-contained (minimal sidecar installs omit src/); it gives the same answers
+// as src/workflow/agent-failure-codes.js, whose header defines each code, and
+// test/verify-agent-execution.mjs holds the two tables to that. Only the
+// structured code and HTTP status are read, never a message.
+const BY_CODE = {
+	unauthorized: "key_refused", auth: "auth", AUTH_REQUIRED: "auth", rate_limit: "rate_limited", RATE_LIMITED: "rate_limited",
+	STALE_SCENE: "stale_scene", STALE_TARGET: "stale_scene", STALE_ENVIRONMENT: "stale_scene",
+	CAPABILITY_MISSING: "capability_missing", LIVE_HUB_UNAVAILABLE: "capability_missing",
+	busy: "busy", TARGET_BUSY: "busy", SCOPE_BUSY: "busy", TARGET_NOT_READY: "busy",
+};
+
+/** `{ code, status }` (a thrown error or a runner `error` frame) -> failure code.
+ * The runner's `overloaded`/`upstream`/`truncated` and every 5xx read as upstream. */
+export function failureCodeOf(error, fallback = "upstream") {
+	try {
+		const code = typeof error?.code === "string" ? error.code : "";
+		const status = error?.status;
+		if (Object.hasOwn(BY_CODE, code)) return BY_CODE[code];
+		if (code.startsWith("INVALID_")) return "invalid_request";
+		if (status === 401 || status === 403) return "auth";
+		if (status === 429) return "rate_limited";
+		return Number.isInteger(status) && status >= 400 && status < 500 ? "invalid_request" : fallback;
+	} catch { return fallback; }
+}
+
+/** A turn that threw: an abort wins, then the error's own code, then a tool failure. */
+export const agentFailureCode = (error, signal, tool = false) => {
+	try { if (signal.aborted || error?.name === "AbortError") return "aborted"; } catch { /* foreign getter */ }
+	return failureCodeOf(error, tool ? "tool_failed" : "upstream");
+};

package/bin/agent/agent-routes.mjs

@@ -13,6 +13,7 @@ import { createAgentRunner } from "./agent-runner.mjs";
 import { createProviderRoutes } from "./provider-routes.mjs";
 import { STUDIO_SYSTEM_PROMPT_STORYBOARD } from "./studio-prompt.mjs";
 import { studioTransaction } from "./studio-turn-transaction.mjs";
+import { agentFailureCode, failureCodeOf } from "./agent-failure-codes.mjs";
 
 // Values the codex backend accepts for reasoning.effort (its own 400 lists them).
 export const REASONING_EFFORTS = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
@@ -77,12 +78,6 @@ const agentToolCategory = (name) => {
 	if (name === "place_image_in_scene" || name === "add_reference_node") return "scene_write";
 	return "other";
 };
-const agentFailureCode = (error, signal, tool = false) => advisory(() => {
-	if (signal.aborted || error?.name === "AbortError") return "aborted";
-	if (error?.status === 401 || error?.code === "unauthorized") return "auth";
-	if (error?.status === 429) return "rate_limited";
-	return tool ? "tool_failed" : "upstream";
-}, tool ? "tool_failed" : "upstream");
 // These existing canvas commands only return a node/edge after publishing a
 // new insertion. Read/focus, generic accepted responses, update no-ops and run
 // outputs (which can echo old values) are deliberately not application proof.
@@ -579,7 +574,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			}
 			if (frame.type === "error") {
 			turnOutcome = controller.signal.aborted || frame.code === "aborted" ? "cancelled" : "failed";
-			turnFailureCode = controller.signal.aborted ? "aborted" : frame.code;
+			turnFailureCode = controller.signal.aborted || frame.code === "aborted" ? "aborted" : failureCodeOf(frame);
 			return send(frame);
 			}
 			if (frame.type === "done") {
@@ -822,7 +817,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		const send = (event) => { if (!res.writableEnded && !res.destroyed) res.write(`data: ${JSON.stringify(event)}\n\n`); };
 		let session = sessions.get(value.sessionId);
 		if (session?.running) {
-			send({ type: "error", code: "upstream", message: "busy" }); send({ type: "done" }); res.end(); return true;
+			send({ type: "error", code: "busy", message: "busy" }); send({ type: "done" }); res.end(); return true;
 		}
 		session ||= { images: new Map(), history: [] };
 		sessions.set(value.sessionId, session);
@@ -870,7 +865,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 					return;
 				}
 				turnOutcome = signal.aborted || frame.code === "aborted" ? "cancelled" : "failed";
-				turnFailureCode = signal.aborted ? "aborted" : frame.code;
+				turnFailureCode = signal.aborted || frame.code === "aborted" ? "aborted" : failureCodeOf(frame);
 				return send(frame);
 			}
 			if (frame.type === "done") {
@@ -903,7 +898,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		catch (error) {
 			turnOutcome = signal.aborted ? "cancelled" : "failed";
 			turnFailureCode = signal.aborted ? "aborted" : agentFailureCode(error, signal, toolFailed);
-			if (!signal.aborted) emitFrame({ type: "error", ...errorInfo(error, quota) });
+			if (!signal.aborted) send({ type: "error", ...errorInfo(error, quota) });
 			if (!res.writableEnded) emitFrame({ type: "done" });
 		}
 		finally {

package/bin/agent/agent-runner.mjs

@@ -220,8 +220,10 @@ export function withAnthropicCacheBreakpoints(payload, model) {
 		next = { ...next, system: [...system.slice(0, -1), { ...system.at(-1), cache_control: cacheControl }] };
 		count += 1;
 	}
-	if (tools.length && !marked(tools.at(-1)) && model?.compat?.supportsCacheControlOnTools !== false && count < 4) {
-		next = { ...next, tools: [...tools.slice(0, -1), { ...tools.at(-1), cache_control: cacheControl }] };
+	// pi-ai 1.4 appends a defer_loading placeholder tool; the API rejects cache_control on deferred tools.
+	const lastTool = tools.findLastIndex((tool) => !tool?.defer_loading);
+	if (lastTool !== -1 && !marked(tools[lastTool]) && model?.compat?.supportsCacheControlOnTools !== false && count < 4) {
+		next = { ...next, tools: tools.map((tool, index) => index === lastTool ? { ...tool, cache_control: cacheControl } : tool) };
 	}
 	return next === payload ? undefined : next;
 }
@@ -511,7 +513,7 @@ export function createAgentRunner({ models: suppliedModels, sessionStore, tools
 
 		const start = async function* (input = {}) {
 			if (state.active) {
-				yield { type: "error", code: "upstream", message: "busy" };
+				yield { type: "error", code: "busy", message: "busy" };
 				yield { type: "done" };
 				return;
 			}

package/bin/cozyclay.mjs

@@ -14,7 +14,6 @@
  * 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, renameSync, statSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { homedir } from "node:os";
@@ -23,7 +22,9 @@ import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { ensureMcpRuntime, runMcp } from "./mcp-runtime.mjs";
 import { openBrowser } from "./open-browser.mjs";
-import { checkForUpdate, readUpdateStatus, runUpdate } from "./update-check.mjs";
+import { maybeAskForStar } from "./star-prompt.mjs";
+import { checkForUpdate, readUpdateStatus, runUpdate, runUpdateCheck, updateChecksOn } from "./update-check.mjs";
+import { createStudioRoutes } from "./studio-routes.mjs";
 import { handleOAuthRequest } from "./codex-auth.mjs";
 import { createAgentHandler } from "./agent/agent-routes.mjs";
 import { liveHubPort } from "./live-endpoint.mjs";
@@ -55,8 +56,8 @@ const OFFICIAL_PACKAGE = (
 	&& !SOURCE_CHECKOUT
 	&& verifyPackageMarker(join(DIST, "cozyclay-package.json"), PKG_ROOT, packageMetadata)
 );
-const INSTALL_KIND = process.env.npm_config_global === "true"
-	|| (PKG_ROOT.includes("/node_modules/") && !PKG_ROOT.includes("/_npx/"))
+const INSTALL_KIND = SOURCE_CHECKOUT ? "clone" : process.env.npm_config_global === "true"
+	|| (/[\\/]node_modules[\\/]/.test(PKG_ROOT) && !/[\\/]_npx[\\/]/.test(PKG_ROOT))
 	? "global"
 	: "npx";
 
@@ -120,12 +121,8 @@ function parseArgs(argv) {
 	return opts;
 }
 
-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
-// seconds in is a popup; a prompt after a real session is a question.
-const STAR_AFTER_MS = Number(process.env.COZYCLAY_STAR_AFTER_MS ?? 60_000);
 
 async function askFirstLaunchSource() {
 	if (!process.stdin.isTTY || !process.stdout.isTTY) return null;
@@ -146,6 +143,7 @@ const HELP = `cozyclay - browser-based 3D staging studio
   cclay live status         drive a running studio from the terminal
                             (cclay live --help lists every verb)
   cclay update              install the latest cozyclay globally (npm install -g)
+  cclay update --check      only compare: exit 0 latest, 10 newer exists, 11 unknown
   npx cozyclay --port 5200  serve on another port
   npx cozyclay --no-open    do not open a browser
   npx cozyclay --scene <id> open the studio on a bundled starter scene
@@ -197,49 +195,6 @@ function writeState(patch) {
 	}
 }
 
-async function starCount() {
-	try {
-		const res = await fetch("https://api.github.com/repos/NomaDamas/CozyClay", {
-			headers: { accept: "application/vnd.github+json" },
-			signal: AbortSignal.timeout(2500),
-		});
-		if (!res.ok) return null;
-		const body = await res.json();
-		return Number.isInteger(body?.stargazers_count) ? body.stargazers_count : null;
-	} catch {
-		return null;
-	}
-}
-
-// Asked once, on the way out, and never again on this machine. A CLI that
-// nags on every run is worse than one that never asks.
-async function maybeAskForStar(startedAt, opts) {
-	if (!opts.star) return;
-	if (process.env.CI || process.env.COZYCLAY_NO_STAR) return;
-	if (!process.stdin.isTTY || !process.stdout.isTTY) return;
-	if (Date.now() - startedAt < STAR_AFTER_MS) return;
-	if (readState().starPromptedAt) return;
-
-	writeState({ starPromptedAt: new Date().toISOString() });
-	const stars = await starCount();
-	const tally = stars === null ? "" : ` (${stars} so far)`;
-	const rl = createInterface({ input: process.stdin, output: process.stdout });
-	const answer = await new Promise((done) => {
-		const timer = setTimeout(() => done(""), 12_000);
-		rl.question(`\nWas CozyClay any good? A star helps people find it${tally}. Open GitHub? [Y/n] `, (a) => {
-			clearTimeout(timer);
-			done(a);
-		});
-	});
-	rl.close();
-	if (/^(y|yes|)$/i.test(answer.trim())) {
-		openBrowser(REPO_URL);
-		console.log("Thanks. Opening the repo.");
-	} else {
-		console.log(`Fair enough. ${REPO_URL} if you change your mind.`);
-	}
-}
-
 // 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() {
@@ -257,11 +212,12 @@ if (argv[0] === "mcp") {
 } 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(" ")})`);
+	if (argv.length > 1 && !(argv.length === 2 && argv[1] === "--check")) {
+		console.error(`cozyclay: update takes no arguments except --check (got ${argv.slice(1).join(" ")})`);
 		process.exit(1);
 	}
-	runUpdate();
+	if (argv[1] === "--check") process.exit(await runUpdateCheck({ currentVersion: readVersion(), kind: INSTALL_KIND, stateDir: STATE_DIR }));
+	else runUpdate();
 } else if (argv[0] === "telemetry") {
 	const action = argv[1] ?? "status";
 	const internalAction = action === "internal" ? argv[2] : null;
@@ -297,21 +253,14 @@ if (opts.version) {
 	console.log(version);
 	process.exit(0);
 }
-let runtimeTelemetry = takeRuntimeTelemetryConfig(STATE_FILE, {
-	appVersion: version,
-	officialPackage: OFFICIAL_PACKAGE,
-	installKind: INSTALL_KIND,
-});
+const takeRuntime = () => takeRuntimeTelemetryConfig(STATE_FILE, { appVersion: version, officialPackage: OFFICIAL_PACKAGE, installKind: INSTALL_KIND });
+let runtimeTelemetry = takeRuntime();
 if (runtimeTelemetry.firstLaunch && !readTelemetryState(STATE_FILE).firstLaunchHeardFrom) {
 	// A copied `--via` command already says where the install came from.
 	const heardFrom = opts.via || await askFirstLaunchSource();
 	if (heardFrom) {
 		setTelemetryFirstLaunchSource(STATE_FILE, heardFrom);
-	runtimeTelemetry = takeRuntimeTelemetryConfig(STATE_FILE, {
-		appVersion: version,
-		officialPackage: OFFICIAL_PACKAGE,
-		installKind: INSTALL_KIND,
-	});
+	runtimeTelemetry = takeRuntime();
 	}
 }
 const telemetryState = readTelemetryState(STATE_FILE);
@@ -327,7 +276,7 @@ if (
 }
 // 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 updateChecksEnabled = Boolean(opts.updateCheck && !process.env.CI && !process.env.COZYCLAY_NO_UPDATE_CHECK);
+const updateChecksEnabled = updateChecksOn(opts.updateCheck);
 const updatePending = updateChecksEnabled ? 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).");
@@ -343,7 +292,7 @@ async function shutdown(exitCode = 0) {
 	shuttingDown = true;
 	if (server?.listening) await new Promise((resolvePromise) => server.close(() => resolvePromise()));
 	try {
-		await maybeAskForStar(startedAt, opts);
+		await maybeAskForStar(startedAt, opts, { readState, writeState });
 	} catch {
 		/* never let the goodbye prompt hold the process hostage */
 	}
@@ -355,6 +304,7 @@ process.on("SIGTERM", () => shutdown(143));
 // A source checkout has mcp/node_modules; the package loads the Studio's live
 // tools from the staged MCP runtime that `cclay mcp` also uses (#576).
 const agentHandler = createAgentHandler({ port: () => opts.port, ...(SOURCE_CHECKOUT ? {} : { mcpRuntime: { ensure: ensureMcpRuntime } }) });
+const studioRoutes = createStudioRoutes({ port: opts.port, stateFile: STATE_FILE, takeRuntime, update: { currentVersion: version, stateDir: STATE_DIR, kind: INSTALL_KIND, enabled: updateChecksEnabled, pkgRoot: PKG_ROOT } });
 server = createServer((req, res) => {
 	const url = new URL(req.url ?? "/", "http://127.0.0.1");
 	if (/^\/oauth\/(start|status|logout)$/.test(url.pathname)) {
@@ -374,47 +324,7 @@ server = createServer((req, res) => {
 		});
 		return;
 	}
-	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,
-						installKind: INSTALL_KIND,
-					});
-					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;
-	}
+	if (studioRoutes(req, res, url)) return;
 	let rel;
 	try {
 		rel = decodeURIComponent(url.pathname);
@@ -442,11 +352,7 @@ server = createServer((req, res) => {
 		return;
 	}
 	if (target === join(DIST, "app", "index.html")) {
-		runtimeTelemetry = takeRuntimeTelemetryConfig(STATE_FILE, {
-			appVersion: version,
-			officialPackage: OFFICIAL_PACKAGE,
-			installKind: INSTALL_KIND,
-		});
+		runtimeTelemetry = takeRuntime();
 		// Whether this launch is the newest release, from the registry answer the
 		// update check already cached (#466). Never a request of its own.
 		const runtime = { ...runtimeTelemetry, updateStatus: updateChecksEnabled ? readUpdateStatus(version, STATE_DIR) : "unknown" };

package/bin/star-prompt.mjs

@@ -0,0 +1,123 @@
+/**
+ * The one-time "star the repo" question on the way out of `npx cozyclay` (#900).
+ *
+ * With the GitHub CLI installed and signed in, a "y" stars the repo through `gh` on
+ * the spot: no browser hop, which is where most people who meant to star it got lost.
+ * Without gh, a "yes" opens the repo page as before. Asked once per machine, after a
+ * real session, never in CI or without a terminal, and never to an account that has
+ * already starred it. Every failure here is silent: this runs while the launcher exits.
+ */
+import { execFile } from "node:child_process";
+import { createInterface } from "node:readline";
+import { openBrowser } from "./open-browser.mjs";
+
+const REPO = "NomaDamas/CozyClay";
+const REPO_URL = `https://github.com/${REPO}`;
+const STARRED_PATH = `/user/starred/${REPO}`;
+const ANSWER_TIMEOUT_MS = 12_000;
+// Only worth asking someone who actually used the thing. A prompt three
+// seconds in is a popup; a prompt after a real session is a question.
+const STAR_AFTER_MS = Number(process.env.COZYCLAY_STAR_AFTER_MS ?? 60_000);
+
+/** Runs gh and resolves true on exit 0. No gh on PATH, a timeout or an error status is false. */
+function runGh(args) {
+	return new Promise((resolve) => {
+		try {
+			execFile("gh", args, {
+				timeout: 4000,
+				windowsHide: true,
+				env: { ...process.env, GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1" },
+			}, (error) => resolve(!error));
+		} catch {
+			resolve(false);
+		}
+	});
+}
+
+async function starCount() {
+	try {
+		const res = await fetch(`https://api.github.com/repos/${REPO}`, {
+			headers: { accept: "application/vnd.github+json" },
+			signal: AbortSignal.timeout(2500),
+		});
+		if (!res.ok) return null;
+		const body = await res.json();
+		return Number.isInteger(body?.stargazers_count) ? body.stargazers_count : null;
+	} catch {
+		return null;
+	}
+}
+
+function askLine(question) {
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	return new Promise((done) => {
+		const timer = setTimeout(() => {
+			rl.close();
+			done("");
+		}, ANSWER_TIMEOUT_MS);
+		rl.question(question, (answer) => {
+			clearTimeout(timer);
+			rl.close();
+			done(answer);
+		});
+	});
+}
+
+/**
+ * Asked once, on the way out, and never again on this machine. A CLI that nags on
+ * every run is worse than one that never asks. Everything after `state` is injectable
+ * so the test can drive it without a terminal, gh, or the network.
+ */
+export async function maybeAskForStar(startedAt, opts, {
+	readState,
+	writeState,
+	env = process.env,
+	interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY),
+	now = Date.now,
+	minSessionMs = STAR_AFTER_MS,
+	gh = runGh,
+	ask = askLine,
+	stars = starCount,
+	open = openBrowser,
+	log = console.log,
+}) {
+	if (!opts.star) return;
+	if (env.CI || env.COZYCLAY_NO_STAR) return;
+	if (!interactive) return;
+	if (now() - startedAt < minSessionMs) return;
+	if (readState().starPromptedAt) return;
+
+	const promptedAt = new Date(now()).toISOString();
+	const viaGh = await gh(["auth", "status"]);
+	// GET /user/starred/<repo> answers 204 for a starred repo and 404 otherwise.
+	if (viaGh && await gh(["api", STARRED_PATH, "--silent"])) {
+		writeState({ starPromptedAt: promptedAt });
+		return;
+	}
+	writeState({ starPromptedAt: promptedAt });
+	const count = await stars();
+	const tally = count === null ? "" : ` (${count} so far)`;
+
+	if (viaGh) {
+		const answer = await ask(`\nWas CozyClay any good? A star helps people find it${tally}. Star ${REPO} with your gh account? [y/N] `);
+		if (!/^y(es)?$/i.test(answer.trim())) {
+			log(`No problem. ${REPO_URL} if you change your mind.`);
+			return;
+		}
+		if (await gh(["api", "--method", "PUT", STARRED_PATH, "--silent"])) {
+			log(`Starred ${REPO}. Thank you!`);
+			return;
+		}
+		log("gh could not star it, so opening the repo instead.");
+		open(REPO_URL);
+		return;
+	}
+
+	const answer = await ask(`\nWas CozyClay any good? A star helps people find it${tally}. Open GitHub? [Y/n] `);
+	if (/^(y|yes|)$/i.test(answer.trim())) {
+		open(REPO_URL);
+		log("Thanks. Opening the repo.");
+	} else {
+		log(`Fair enough. ${REPO_URL} if you change your mind.`);
+	}
+}

package/bin/studio-routes.mjs

@@ -0,0 +1,69 @@
+/**
+ * The launcher's own /__cozyclay/* routes, kept out of bin/cozyclay.mjs:
+ * the telemetry toggle the Studio's privacy setting posts to, and the update
+ * routes behind the Studio's update chip.
+ */
+import { setTelemetryEnabled } from "./telemetry-state.mjs";
+import { lookupLatest } from "./update-check.mjs";
+import { canSelfUpdate, createInstaller } from "./update-install.mjs";
+import { createUpdateRoutes } from "./update-routes.mjs";
+
+/**
+ * Returns a handler that answers a /__cozyclay/* request and returns true, or
+ * returns false for any other path. `takeRuntime` re-reads the runtime
+ * telemetry config after a change; `update` names this launch's version,
+ * state dir, install kind, package root and whether update checks are on.
+ */
+export function createStudioRoutes({ port, stateFile, takeRuntime, update: { currentVersion, stateDir, kind, enabled, pkgRoot } }) {
+	const updateRoute = createUpdateRoutes({
+		currentVersion,
+		kind,
+		enabled,
+		port,
+		checkLatest: () => lookupLatest(currentVersion, stateDir),
+		canSelfUpdate: () => canSelfUpdate({ pkgRoot }),
+		installer: createInstaller(),
+	});
+	return function handleStudioRoute(req, res, url) {
+		if (url.pathname === "/__cozyclay/update") {
+			void updateRoute(req, res);
+			return true;
+		}
+		if (url.pathname !== "/__cozyclay/telemetry") return false;
+		if (req.method === "POST") {
+			const origin = req.headers.origin;
+			const expectedOrigin = `http://127.0.0.1:${port}`;
+			if (origin !== expectedOrigin) {
+				res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
+				res.end(JSON.stringify({ error: "forbidden origin" }));
+				return true;
+			}
+			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(stateFile, value.enabled);
+					const runtimeTelemetry = takeRuntime();
+					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 true;
+		}
+		res.writeHead(405, { allow: "POST", "content-type": "application/json; charset=utf-8" });
+		res.end(JSON.stringify({ error: "method not allowed" }));
+		return true;
+	};
+}