@react-grab/cli 0.1.38 → 0.1.40

package/dist/cli.cjs

@@ -393,6 +393,45 @@ const handleError = (error) => {
 	process.exit(1);
 };
 //#endregion
+//#region src/utils/detect-agents.ts
+const PATH_BINARIES = {
+	"claude-code": ["claude"],
+	codex: ["codex"],
+	cursor: ["cursor", "cursor-agent"],
+	droid: ["droid"],
+	"gemini-cli": ["gemini"],
+	"github-copilot": ["copilot"],
+	opencode: ["opencode"],
+	pi: ["pi", "omegon"]
+};
+const isCommandAvailable = (command) => {
+	const pathDirectories = (process.env.PATH ?? "").split(node_path.delimiter).filter(Boolean);
+	for (const directory of pathDirectories) {
+		const binaryPath = (0, node_path.join)(directory, command);
+		try {
+			if ((0, node_fs.statSync)(binaryPath).isFile()) {
+				(0, node_fs.accessSync)(binaryPath, node_fs.constants.X_OK);
+				return true;
+			}
+		} catch {}
+	}
+	return false;
+};
+const detectAvailableAgents = async () => {
+	const installedAgents = new Set(await (0, agent_install_skill.detectInstalledSkillAgents)());
+	return (0, agent_install_skill.getSkillAgentTypes)().filter((agent) => {
+		if (agent === "universal") return false;
+		if (installedAgents.has(agent)) return true;
+		return PATH_BINARIES[agent]?.some(isCommandAvailable) ?? false;
+	});
+};
+//#endregion
+//#region src/utils/unref-stdin.ts
+const unrefStdin = () => {
+	if (process.stdin.isTTY) return;
+	process.stdin.unref?.();
+};
+//#endregion
 //#region src/utils/prompts.ts
 const onCancel = () => {
 	logger.break();
@@ -401,7 +440,7 @@ const onCancel = () => {
 	process.exit(0);
 };
 const prompts$1 = (questions) => {
-	return (0, prompts.default)(questions, { onCancel });
+	return (0, prompts.default)(questions, { onCancel }).finally(unrefStdin);
 };
 //#endregion
 //#region src/utils/spinner.ts
@@ -413,24 +452,32 @@ const SKILL_SOURCE = (0, node_url.fileURLToPath)(new URL("../skills/react-grab",
 const agentLabel = (agent) => (0, agent_install_skill.getSkillAgentConfig)(agent).displayName;
 const installedSkillDir = (agent) => (0, node_path.join)((0, agent_install_skill.isUniversalSkillAgent)(agent) ? (0, agent_install_skill.getCanonicalSkillsDir)(true) : (0, agent_install_skill.getSkillAgentDir)(agent, { global: true }), SKILL_NAME);
 const promptSkillInstall = async ({ yes = false } = {}) => {
-	const agents = await (0, agent_install_skill.detectInstalledSkillAgents)();
-	if (agents.length === 0) {
+	const detectedAgents = await detectAvailableAgents();
+	if (detectedAgents.length === 0) {
 		logger.warn("No supported agents detected.");
 		return false;
 	}
+	let selectedAgents = detectedAgents;
 	if (!yes) {
-		const { confirmed } = await prompts$1({
-			type: "confirm",
-			name: "confirmed",
-			message: `Install the React Grab skill for ${highlighter.info(agents.map(agentLabel).join(", "))}?`,
-			initial: true
+		const { agents } = await prompts$1({
+			type: "multiselect",
+			name: "agents",
+			message: "Install the React Grab skill for:",
+			choices: detectedAgents.map((agent) => ({
+				title: agentLabel(agent),
+				value: agent,
+				selected: true
+			})),
+			instructions: false,
+			min: 1
 		});
-		if (!confirmed) return false;
+		selectedAgents = agents ?? [];
+		if (selectedAgents.length === 0) return false;
 	}
 	const installSpinner = spinner("Installing React Grab skill.").start();
 	const { installed, failed } = await (0, agent_install_skill.add)({
 		source: SKILL_SOURCE,
-		agents,
+		agents: selectedAgents,
 		global: true,
 		mode: "copy"
 	});
@@ -443,7 +490,7 @@ const promptSkillInstall = async ({ yes = false } = {}) => {
 	return true;
 };
 const removeSkill = async () => {
-	const agentsWithSkill = (await (0, agent_install_skill.detectInstalledSkillAgents)()).filter((agent) => (0, node_fs.existsSync)(installedSkillDir(agent)));
+	const agentsWithSkill = (await detectAvailableAgents()).filter((agent) => (0, node_fs.existsSync)(installedSkillDir(agent)));
 	for (const skillDir of new Set(agentsWithSkill.map(installedSkillDir))) (0, node_fs.rmSync)(skillDir, {
 		recursive: true,
 		force: true
@@ -453,7 +500,7 @@ const removeSkill = async () => {
 };
 //#endregion
 //#region src/commands/add.ts
-const VERSION$5 = "0.1.38";
+const VERSION$5 = "0.1.40";
 const add = new commander.Command().name("add").alias("install").description("install the React Grab skill for your agent").option("-y, --yes", "skip confirmation prompts", false).option("-c, --cwd <cwd>", "working directory (defaults to current directory)", process.cwd()).action(async (opts) => {
 	console.log(`${picocolors.default.magenta("✿")} ${picocolors.default.bold("React Grab")} ${picocolors.default.gray(VERSION$5)}`);
 	console.log();
@@ -856,6 +903,15 @@ const transformTanStack = (projectRoot, reactGrabAlreadyConfigured, force = fals
 		newContent
 	};
 };
+const hasFrameworkEntryPoint = (projectRoot, framework, nextRouterType) => {
+	switch (framework) {
+		case "next": return nextRouterType === "app" ? findLayoutFile(projectRoot) !== null : findDocumentFile(projectRoot) !== null;
+		case "vite":
+		case "webpack": return findEntryFile(projectRoot) !== null;
+		case "tanstack": return findTanStackRootFile(projectRoot) !== null;
+		default: return false;
+	}
+};
 const previewTransform = (projectRoot, framework, nextRouterType, reactGrabAlreadyConfigured = false, force = false) => {
 	switch (framework) {
 		case "next":
@@ -1038,6 +1094,7 @@ const previewCdnTransform = (projectRoot, framework, nextRouterType, targetCdnDo
 //#endregion
 //#region src/utils/constants.ts
 const MAX_KEY_HOLD_DURATION_MS = 2e3;
+const DEFAULT_WATCH_DIR = ".react-grab";
 //#endregion
 //#region src/utils/format-activation-key.ts
 const formatActivationKeyDisplay = (activationKey) => {
@@ -1055,7 +1112,7 @@ const formatActivationKeyDisplay = (activationKey) => {
 };
 //#endregion
 //#region src/commands/configure.ts
-const VERSION$4 = "0.1.38";
+const VERSION$4 = "0.1.40";
 const isMac = process.platform === "darwin";
 const META_LABEL = isMac ? "Cmd" : "Win";
 const ALT_LABEL = isMac ? "Option" : "Alt";
@@ -1674,7 +1731,7 @@ const installPackagesWithFeedback = async (packages, packageManager, projectRoot
 };
 //#endregion
 //#region src/commands/init.ts
-const VERSION$3 = "0.1.38";
+const VERSION$3 = "0.1.40";
 const REPORT_URL = "https://react-grab.com/api/report-cli";
 const DOCS_URL = "https://github.com/aidenybai/react-grab";
 const reportToCli = (type, config, error) => {
@@ -1732,6 +1789,15 @@ const printSubprojects = (searchRoot, sortedProjects) => {
 	logger.log(`  ${highlighter.dim("$")} npx grab@latest init -c ${(0, node_path.relative)(searchRoot, sortedProjects[0].path)}`);
 	logger.break();
 };
+const SUPPORTED_FRAMEWORKS_LINE = "React Grab supports Next.js, Vite, TanStack Start, and Webpack projects.";
+const failWithManualSetup = (failingSpinner, message, { listSupportedFrameworks = false } = {}) => {
+	failingSpinner.fail(message);
+	logger.break();
+	if (listSupportedFrameworks) logger.log(SUPPORTED_FRAMEWORKS_LINE);
+	logger.log(`Visit ${highlighter.info(DOCS_URL)} for manual setup.`);
+	logger.break();
+	process.exit(1);
+};
 const init = new commander.Command().name("init").alias("setup").description("initialize React Grab in your project").option("-y, --yes", "skip confirmation prompts", false).option("-f, --force", "force overwrite existing config", false).option("-k, --key <key>", "activation key (e.g., Meta+K, Ctrl+Shift+G, Space)").option("--skip-install", "skip package installation", false).option("--pkg <pkg>", "custom package URL for CLI (e.g., grab)").option("-c, --cwd <cwd>", "working directory (defaults to current directory)", process.cwd()).action(async (opts) => {
 	console.log(`${picocolors.default.magenta("✿")} ${picocolors.default.bold("React Grab")} ${picocolors.default.gray(VERSION$3)}`);
 	console.log();
@@ -1905,7 +1971,7 @@ const init = new commander.Command().name("init").alias("setup").description("in
 			logger.break();
 			process.exit(1);
 		}
-		if (projectInfo.framework === "unknown") {
+		if (projectInfo.framework === "unknown" || projectInfo.isMonorepo && !hasFrameworkEntryPoint(projectInfo.projectRoot, projectInfo.framework, projectInfo.nextRouterType)) {
 			let searchRoot = cwd;
 			let reactProjects = findReactProjects(searchRoot);
 			if (reactProjects.length === 0 && cwd !== process.cwd()) {
@@ -1943,23 +2009,10 @@ const init = new commander.Command().name("init").alias("setup").description("in
 				const newProjectInfo = await detectProject(selectedProject);
 				Object.assign(projectInfo, newProjectInfo);
 				const newFrameworkSpinner = spinner("Verifying framework.").start();
-				if (newProjectInfo.framework === "unknown") {
-					newFrameworkSpinner.fail("Could not detect a supported framework in this project.");
-					logger.break();
-					logger.log("React Grab supports Next.js, Vite, TanStack Start, and Webpack projects.");
-					logger.log(`Visit ${highlighter.info(DOCS_URL)} for manual setup.`);
-					logger.break();
-					process.exit(1);
-				}
+				if (newProjectInfo.framework === "unknown") failWithManualSetup(newFrameworkSpinner, "Could not detect a supported framework in this project.", { listSupportedFrameworks: true });
 				newFrameworkSpinner.succeed(`Verifying framework. Found ${highlighter.info(FRAMEWORK_NAMES[newProjectInfo.framework])}.`);
-			} else {
-				frameworkSpinner.fail("Could not detect a supported framework.");
-				logger.break();
-				logger.log("React Grab supports Next.js, Vite, TanStack Start, and Webpack projects.");
-				logger.log(`Visit ${highlighter.info(DOCS_URL)} for manual setup.`);
-				logger.break();
-				process.exit(1);
-			}
+			} else if (projectInfo.framework !== "unknown") failWithManualSetup(frameworkSpinner, `Verifying framework. Found ${highlighter.info(FRAMEWORK_NAMES[projectInfo.framework])}, but could not find an entry file.`);
+			else failWithManualSetup(frameworkSpinner, "Could not detect a supported framework.", { listSupportedFrameworks: true });
 		} else frameworkSpinner.succeed(`Verifying framework. Found ${highlighter.info(FRAMEWORK_NAMES[projectInfo.framework])}.`);
 		if (projectInfo.framework === "next") spinner("Detecting router type.").start().succeed(`Detecting router type. Found ${highlighter.info(projectInfo.nextRouterType === "app" ? "App Router" : "Pages Router")}.`);
 		spinner("Detecting package manager.").start().succeed(`Detecting package manager. Found ${highlighter.info(PACKAGE_MANAGER_NAMES[projectInfo.packageManager])}.`);
@@ -2022,99 +2075,11 @@ const init = new commander.Command().name("init").alias("setup").description("in
 	}
 });
 //#endregion
-//#region src/commands/remove.ts
-const VERSION$2 = "0.1.38";
-const remove = new commander.Command().name("remove").description("uninstall the React Grab skill from your agent").action(async () => {
-	console.log(`${picocolors.default.magenta("✿")} ${picocolors.default.bold("React Grab")} ${picocolors.default.gray(VERSION$2)}`);
-	console.log();
-	try {
-		logger.break();
-		const removedCount = await removeSkill();
-		logger.break();
-		if (removedCount === 0) logger.log("React Grab skill is not installed in any detected agent.");
-		else logger.log(`${highlighter.success("Removed")} the React Grab skill from ${removedCount} agent${removedCount === 1 ? "" : "s"}.`);
-		logger.break();
-	} catch (error) {
-		handleError(error);
-	}
-});
-//#endregion
-//#region src/commands/upgrade.ts
-const VERSION$1 = "0.1.38";
-const NPM_REGISTRY_URL = "https://registry.npmjs.org/react-grab/latest";
-const fetchLatestVersion = async () => {
-	try {
-		return (await (await fetch(NPM_REGISTRY_URL)).json()).version ?? null;
-	} catch {
-		return null;
-	}
-};
-const isDevDependency = (projectRoot) => {
-	const packageJsonPath = (0, node_path.join)(projectRoot, "package.json");
-	if (!(0, node_fs.existsSync)(packageJsonPath)) return true;
-	try {
-		const packageJson = JSON.parse((0, node_fs.readFileSync)(packageJsonPath, "utf-8"));
-		if (packageJson.devDependencies?.["react-grab"]) return true;
-		if (packageJson.dependencies?.["react-grab"]) return false;
-	} catch {}
-	return true;
-};
-const upgrade = new commander.Command().name("upgrade").alias("update").description("upgrade react-grab to the latest version").option("-c, --cwd <cwd>", "working directory (defaults to current directory)", process.cwd()).action(async (opts) => {
-	console.log(`${picocolors.default.magenta("✿")} ${picocolors.default.bold("React Grab")} ${picocolors.default.gray(VERSION$1)}`);
-	console.log();
-	try {
-		const cwd = (0, node_path.resolve)(opts.cwd);
-		const detectSpinner = spinner("Detecting project.").start();
-		const projectInfo = await detectProject(cwd);
-		if (!projectInfo.hasReactGrab) {
-			detectSpinner.fail("React Grab is not installed.");
-			logger.break();
-			logger.error(`Run ${highlighter.info("npx grab@latest init")} first to install React Grab.`);
-			logger.break();
-			process.exit(1);
-		}
-		detectSpinner.succeed();
-		const versionSpinner = spinner("Checking for updates.").start();
-		const latestVersion = await fetchLatestVersion();
-		if (!latestVersion) {
-			versionSpinner.fail("Could not check for updates.");
-			logger.break();
-			logger.error("Failed to reach the npm registry. Check your network connection.");
-			logger.break();
-			process.exit(1);
-		}
-		const installedVersion = projectInfo.reactGrabVersion;
-		if (installedVersion && installedVersion === latestVersion) {
-			versionSpinner.succeed(`Already on the latest version ${highlighter.info(`v${latestVersion}`)}.`);
-			logger.break();
-			process.exit(0);
-		}
-		const fromLabel = installedVersion ? `v${installedVersion}` : "unknown";
-		versionSpinner.succeed(`Update available: ${highlighter.dim(fromLabel)} → ${highlighter.info(`v${latestVersion}`)}.`);
-		const upgradeSpinner = spinner("Upgrading react-grab.").start();
-		try {
-			await installPackages(["react-grab@latest"], {
-				packageManager: projectInfo.packageManager,
-				cwd: projectInfo.projectRoot,
-				isDev: isDevDependency(projectInfo.projectRoot)
-			});
-			upgradeSpinner.succeed();
-		} catch {
-			upgradeSpinner.fail();
-			logger.break();
-			logger.error("Failed to upgrade. Check your network connection and try again.");
-			logger.break();
-			process.exit(1);
-		}
-		logger.break();
-		logger.log(`${highlighter.success("Success!")} React Grab has been upgraded to ${highlighter.info(`v${latestVersion}`)}.`);
-		logger.break();
-	} catch (error) {
-		handleError(error);
-	}
-});
+//#region src/utils/sleep.ts
+const sleep = (durationMs) => new Promise((resolve) => setTimeout(resolve, durationMs));
 //#endregion
 //#region src/utils/clipboard.ts
+const HISTORY_FILE_NAME = "history.jsonl";
 const READ_TIMEOUT_MS = 2500;
 const MAX_CLIPBOARD_BYTES = 64 * 1024 * 1024;
 const ID_RADIX = 36;
@@ -2125,7 +2090,6 @@ const SIGNATURE_SCAN_CHARS = 32 * 1024;
 const GRAB_MIME = "application/x-react-grab";
 const CHROMIUM_CUSTOM_FORMAT = "chromium/x-web-custom-data";
 const GRAB_TEXT_SIGNATURE = /\bin\s+\S+\s+\(at\s+[^\n]{1,400}?:\d+:\d+\)/;
-const sleep = (durationMs) => new Promise((resolve) => setTimeout(resolve, durationMs));
 const shortHash = (text) => (0, node_crypto.createHash)("sha1").update(text).digest("hex").slice(0, HASH_LENGTH);
 const alignUp = (value) => value + PICKLE_ALIGN_BYTES - 1 & ~(PICKLE_ALIGN_BYTES - 1);
 const parseChromiumPickle = (buffer) => {
@@ -2357,9 +2321,9 @@ const prepareWorkDir = (dir) => {
 	const gitignore = node_path.default.join(dir, ".gitignore");
 	if (!node_fs.default.existsSync(gitignore)) node_fs.default.writeFileSync(gitignore, "*\n");
 };
-const watchForNextGrab = async (options) => {
-	const { reader, dir, intervalMs, replayLast, onWarn, signal } = options;
-	const logPath = node_path.default.join(dir, "history.jsonl");
+const runWatchLoop = async (options) => {
+	const { reader, dir, intervalMs, replayLast, onWarn } = options;
+	const logPath = node_path.default.join(dir, HISTORY_FILE_NAME);
 	const { read } = reader;
 	let lastChangeCount = null;
 	let lastTimestamp = 0;
@@ -2374,9 +2338,8 @@ const watchForNextGrab = async (options) => {
 			lastTimestamp = JSON.parse(initial.grab).timestamp ?? 0;
 		} catch {}
 	}
-	while (!signal?.aborted) {
+	while (true) {
 		await sleep(intervalMs);
-		if (signal?.aborted) return null;
 		try {
 			const snapshot = read();
 			if (!snapshot) continue;
@@ -2422,7 +2385,6 @@ const watchForNextGrab = async (options) => {
 			lastChangeCount = snapshot.changeCount;
 			lastTextHash = textHash;
 			lastTimestamp = nextTimestamp;
-			return captured;
 		} catch (error) {
 			const message = String(error?.message ?? error);
 			if (message !== lastErrorMessage) {
@@ -2431,51 +2393,315 @@ const watchForNextGrab = async (options) => {
 			}
 		}
 	}
-	return null;
 };
 //#endregion
-//#region src/commands/watch.ts
-const DEFAULT_INTERVAL_MS = 800;
-const DEFAULT_DIR = ".react-grab";
-const readersDir = () => node_path.default.dirname((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href));
-const watch = new commander.Command().name("watch").description("watch the clipboard for the next React Grab selection, print it, then exit").option("-d, --dir <dir>", "work dir for history.jsonl + cursor.txt", DEFAULT_DIR).option("-i, --interval <ms>", "clipboard poll interval in ms", String(DEFAULT_INTERVAL_MS)).option("--text-only", "skip the native reader and use the plain-text fallback").option("--replay-last", "also capture the grab already on the clipboard at startup").action((options) => {
+//#region src/utils/grab-log.ts
+const CURSOR_FILE_NAME = "cursor.txt";
+const cursorFilePath = (dir) => node_path.default.join(dir, CURSOR_FILE_NAME);
+const readCompleteGrabLines = (dir) => {
+	let raw;
+	try {
+		raw = node_fs.default.readFileSync(node_path.default.join(dir, HISTORY_FILE_NAME), "utf8");
+	} catch {
+		return [];
+	}
+	const lastNewline = raw.lastIndexOf("\n");
+	if (lastNewline < 0) return [];
+	return raw.slice(0, lastNewline).split("\n").filter(Boolean);
+};
+const readGrabCursor = (dir) => {
+	try {
+		const value = Number.parseInt(node_fs.default.readFileSync(cursorFilePath(dir), "utf8").trim(), 10);
+		return Number.isInteger(value) && value >= 0 ? value : 0;
+	} catch {
+		return 0;
+	}
+};
+const consumeGrabs = (dir, options) => {
+	const lines = readCompleteGrabLines(dir);
+	if (options.all) return lines;
+	const cursor = readGrabCursor(dir);
+	const start = Math.min(cursor, lines.length);
+	const end = options.limit > 0 ? Math.min(start + options.limit, lines.length) : lines.length;
+	if (end !== cursor) node_fs.default.writeFileSync(cursorFilePath(dir), String(end));
+	return lines.slice(start, end);
+};
+//#endregion
+//#region src/commands/read.ts
+const read = new commander.Command().name("read").description("print React Grab selections captured since the last read, then advance the cursor").option("-d, --dir <dir>", "work dir holding history.jsonl + cursor.txt", DEFAULT_WATCH_DIR).option("-w, --wait <ms>", "block up to <ms> for at least one new grab (default: no wait)").option("-n, --limit <count>", "max grabs to print per call (0 = no limit); the cursor only advances past what is printed", String(50)).option("--all", "print the entire history without advancing the cursor").action(async (options) => {
 	const dir = node_path.default.resolve(options.dir);
-	const intervalMs = Number(options.interval);
-	const textOnly = Boolean(options.textOnly);
 	try {
 		prepareWorkDir(dir);
 	} catch (error) {
-		process.stderr.write(`react-grab watch: ${String(error?.message ?? error)}\n`);
+		process.stderr.write(`react-grab read: ${String(error?.message ?? error)}\n`);
 		process.exit(1);
 	}
+	unrefStdin();
+	const limitRaw = Number(options.limit);
+	const limit = Number.isInteger(limitRaw) && limitRaw >= 0 ? limitRaw : 50;
+	const all = Boolean(options.all);
+	const drain = () => {
+		const fresh = consumeGrabs(dir, {
+			limit,
+			all
+		});
+		if (fresh.length > 0) process.stdout.write(`${fresh.join("\n")}\n`);
+		return fresh.length;
+	};
+	const waitRaw = options.wait ? Number(options.wait) : 0;
+	const deadline = Date.now() + (Number.isFinite(waitRaw) && waitRaw > 0 ? waitRaw : 0);
+	if (drain() > 0) process.exit(0);
+	while (Date.now() < deadline) {
+		await sleep(200);
+		if (drain() > 0) break;
+	}
+	process.exit(0);
+});
+//#endregion
+//#region src/commands/remove.ts
+const VERSION$2 = "0.1.40";
+const remove = new commander.Command().name("remove").description("uninstall the React Grab skill from your agent").action(async () => {
+	console.log(`${picocolors.default.magenta("✿")} ${picocolors.default.bold("React Grab")} ${picocolors.default.gray(VERSION$2)}`);
+	console.log();
+	try {
+		logger.break();
+		const removedCount = await removeSkill();
+		logger.break();
+		if (removedCount === 0) logger.log("React Grab skill is not installed in any detected agent.");
+		else logger.log(`${highlighter.success("Removed")} the React Grab skill from ${removedCount} agent${removedCount === 1 ? "" : "s"}.`);
+		logger.break();
+	} catch (error) {
+		handleError(error);
+	}
+});
+//#endregion
+//#region src/commands/upgrade.ts
+const VERSION$1 = "0.1.40";
+const NPM_REGISTRY_URL = "https://registry.npmjs.org/react-grab/latest";
+const fetchLatestVersion = async () => {
+	try {
+		return (await (await fetch(NPM_REGISTRY_URL)).json()).version ?? null;
+	} catch {
+		return null;
+	}
+};
+const isDevDependency = (projectRoot) => {
+	const packageJsonPath = (0, node_path.join)(projectRoot, "package.json");
+	if (!(0, node_fs.existsSync)(packageJsonPath)) return true;
+	try {
+		const packageJson = JSON.parse((0, node_fs.readFileSync)(packageJsonPath, "utf-8"));
+		if (packageJson.devDependencies?.["react-grab"]) return true;
+		if (packageJson.dependencies?.["react-grab"]) return false;
+	} catch {}
+	return true;
+};
+const upgrade = new commander.Command().name("upgrade").alias("update").description("upgrade react-grab to the latest version").option("-c, --cwd <cwd>", "working directory (defaults to current directory)", process.cwd()).action(async (opts) => {
+	console.log(`${picocolors.default.magenta("✿")} ${picocolors.default.bold("React Grab")} ${picocolors.default.gray(VERSION$1)}`);
+	console.log();
+	try {
+		const cwd = (0, node_path.resolve)(opts.cwd);
+		const detectSpinner = spinner("Detecting project.").start();
+		const projectInfo = await detectProject(cwd);
+		if (!projectInfo.hasReactGrab) {
+			detectSpinner.fail("React Grab is not installed.");
+			logger.break();
+			logger.error(`Run ${highlighter.info("npx grab@latest init")} first to install React Grab.`);
+			logger.break();
+			process.exit(1);
+		}
+		detectSpinner.succeed();
+		const versionSpinner = spinner("Checking for updates.").start();
+		const latestVersion = await fetchLatestVersion();
+		if (!latestVersion) {
+			versionSpinner.fail("Could not check for updates.");
+			logger.break();
+			logger.error("Failed to reach the npm registry. Check your network connection.");
+			logger.break();
+			process.exit(1);
+		}
+		const installedVersion = projectInfo.reactGrabVersion;
+		if (installedVersion && installedVersion === latestVersion) {
+			versionSpinner.succeed(`Already on the latest version ${highlighter.info(`v${latestVersion}`)}.`);
+			logger.break();
+			process.exit(0);
+		}
+		const fromLabel = installedVersion ? `v${installedVersion}` : "unknown";
+		versionSpinner.succeed(`Update available: ${highlighter.dim(fromLabel)} → ${highlighter.info(`v${latestVersion}`)}.`);
+		const upgradeSpinner = spinner("Upgrading react-grab.").start();
+		try {
+			await installPackages(["react-grab@latest"], {
+				packageManager: projectInfo.packageManager,
+				cwd: projectInfo.projectRoot,
+				isDev: isDevDependency(projectInfo.projectRoot)
+			});
+			upgradeSpinner.succeed();
+		} catch {
+			upgradeSpinner.fail();
+			logger.break();
+			logger.error("Failed to upgrade. Check your network connection and try again.");
+			logger.break();
+			process.exit(1);
+		}
+		logger.break();
+		logger.log(`${highlighter.success("Success!")} React Grab has been upgraded to ${highlighter.info(`v${latestVersion}`)}.`);
+		logger.break();
+	} catch (error) {
+		handleError(error);
+	}
+});
+//#endregion
+//#region src/utils/daemon.ts
+const PID_FILE_NAME = "watch.pid";
+const pidFilePath = (dir) => node_path.default.join(dir, PID_FILE_NAME);
+const cliEntryPath = () => process.argv[1] ?? (0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href);
+const isProcessAlive = (pid) => {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+};
+const readDaemonPid = (dir) => {
+	try {
+		const pid = Number.parseInt(node_fs.default.readFileSync(pidFilePath(dir), "utf8").trim(), 10);
+		return Number.isInteger(pid) && pid > 0 ? pid : null;
+	} catch {
+		return null;
+	}
+};
+const isDaemonRunning = (dir) => {
+	const pid = readDaemonPid(dir);
+	return pid !== null && isProcessAlive(pid);
+};
+const claimDaemon = (dir) => {
+	const file = pidFilePath(dir);
+	for (let attempt = 0; attempt < 50; attempt += 1) try {
+		const handle = node_fs.default.openSync(file, "wx");
+		node_fs.default.writeFileSync(handle, String(process.pid));
+		node_fs.default.closeSync(handle);
+		return readDaemonPid(dir) === process.pid;
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+		if (isDaemonRunning(dir)) return false;
+		try {
+			node_fs.default.rmSync(file, { force: true });
+		} catch {}
+	}
+	return false;
+};
+const releaseDaemon = (dir) => {
+	if (readDaemonPid(dir) === process.pid) try {
+		node_fs.default.rmSync(pidFilePath(dir), { force: true });
+	} catch {}
+};
+const stopDaemon = (dir) => {
+	const pid = readDaemonPid(dir);
+	if (pid === null) return null;
+	const wasAlive = isProcessAlive(pid);
+	if (wasAlive) try {
+		process.kill(pid, "SIGTERM");
+	} catch {}
+	if (readDaemonPid(dir) === pid) try {
+		node_fs.default.rmSync(pidFilePath(dir), { force: true });
+	} catch {}
+	return wasAlive ? pid : null;
+};
+const spawnDaemon = (options) => {
+	const args = [
+		cliEntryPath(),
+		"watch",
+		"--foreground",
+		"--dir",
+		options.dir,
+		"--interval",
+		String(options.intervalMs)
+	];
+	if (options.textOnly) args.push("--text-only");
+	if (options.replayLast) args.push("--replay-last");
+	(0, node_child_process.spawn)(process.execPath, args, {
+		detached: true,
+		stdio: "ignore",
+		windowsHide: true
+	}).unref();
+};
+//#endregion
+//#region src/commands/watch.ts
+const readersDir = () => node_path.default.dirname((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href));
+const NO_READER_MESSAGE = "no clipboard reader available. Linux: install xclip or wl-clipboard. macOS: install Xcode CLI tools (swiftc) or rely on pbpaste. Windows: ensure PowerShell is on PATH.";
+const writeStatus = (message) => {
+	process.stderr.write(`react-grab watch: ${message}\n`);
+};
+const runForeground = (dir, intervalMs, textOnly, replayLast) => {
+	if (!claimDaemon(dir)) process.exit(0);
+	process.on("exit", () => releaseDaemon(dir));
 	const reader = createReader({
 		textOnly,
 		readersDir: readersDir(),
 		workDir: dir
 	});
 	if (!reader) {
-		process.stderr.write("react-grab watch: no clipboard reader available. Linux: install xclip or wl-clipboard. macOS: install Xcode CLI tools (swiftc) or rely on pbpaste. Windows: ensure PowerShell is on PATH.\n");
+		writeStatus(NO_READER_MESSAGE);
 		process.exit(1);
 	}
-	process.stderr.write(`react-grab watch: watching clipboard via ${reader.mode}; history → ${node_path.default.join(dir, "history.jsonl")} (Ctrl+C to stop)\n`);
-	watchForNextGrab({
+	writeStatus(`watching clipboard via ${reader.mode}; history → ${node_path.default.join(dir, HISTORY_FILE_NAME)}`);
+	runWatchLoop({
 		reader,
 		dir,
-		intervalMs: Number.isFinite(intervalMs) && intervalMs > 0 ? intervalMs : DEFAULT_INTERVAL_MS,
-		replayLast: Boolean(options.replayLast),
-		onWarn: (message) => process.stderr.write(`react-grab watch: ${message}\n`)
-	}).then((grab) => {
-		if (!grab) process.exit(0);
-		process.stdout.write(`${JSON.stringify(grab)}\n`);
-		process.exit(0);
+		intervalMs,
+		replayLast,
+		onWarn: writeStatus
 	}).catch((error) => {
-		process.stderr.write(`react-grab watch: ${String(error?.message ?? error)}\n`);
+		writeStatus(String(error?.message ?? error));
 		process.exit(1);
 	});
+};
+const watch = new commander.Command().name("watch").description("start a background daemon that captures React Grab selections to history.jsonl").option("-d, --dir <dir>", "work dir for history.jsonl + watch.pid", DEFAULT_WATCH_DIR).option("-i, --interval <ms>", "clipboard poll interval in ms", String(800)).option("--text-only", "skip the native reader and use the plain-text fallback").option("--replay-last", "also capture the grab already on the clipboard at startup").option("--foreground", "run the capture loop in this process instead of detaching a daemon").option("--stop", "stop the daemon watching this dir").action((options) => {
+	const dir = node_path.default.resolve(options.dir);
+	const intervalRaw = Number(options.interval);
+	const intervalMs = Number.isFinite(intervalRaw) && intervalRaw > 0 ? intervalRaw : 800;
+	const textOnly = Boolean(options.textOnly);
+	const replayLast = Boolean(options.replayLast);
+	try {
+		prepareWorkDir(dir);
+	} catch (error) {
+		writeStatus(String(error?.message ?? error));
+		process.exit(1);
+	}
+	if (options.stop) {
+		const stoppedPid = stopDaemon(dir);
+		writeStatus(stoppedPid ? `stopped daemon (pid ${stoppedPid})` : `no daemon running for ${dir}`);
+		process.exit(0);
+	}
+	if (options.foreground) {
+		runForeground(dir, intervalMs, textOnly, replayLast);
+		return;
+	}
+	if (isDaemonRunning(dir)) {
+		writeStatus(`already watching ${dir} (pid ${readDaemonPid(dir)})`);
+		process.exit(0);
+	}
+	if (!createReader({
+		textOnly,
+		readersDir: readersDir(),
+		workDir: dir
+	})) {
+		writeStatus(NO_READER_MESSAGE);
+		process.exit(1);
+	}
+	spawnDaemon({
+		dir,
+		intervalMs,
+		textOnly,
+		replayLast
+	});
+	writeStatus(`started; capturing grabs → ${node_path.default.join(dir, HISTORY_FILE_NAME)} (run \`grab read\` to consume, \`grab watch --stop\` to stop)`);
+	process.exit(0);
 });
 //#endregion
 //#region src/cli.ts
-const VERSION = "0.1.38";
+const VERSION = "0.1.40";
 const VERSION_API_URL = "https://www.react-grab.com/api/version";
 process.on("SIGINT", () => process.exit(0));
 process.on("SIGTERM", () => process.exit(0));
@@ -2489,6 +2715,7 @@ program.addCommand(remove);
 program.addCommand(configure);
 program.addCommand(upgrade);
 program.addCommand(watch);
+program.addCommand(read);
 const main = async () => {
 	await program.parseAsync();
 };