@react-grab/cli 0.1.40 → 0.1.41

package/dist/cli.cjs

@@ -22,12 +22,12 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 //#endregion
 let commander = require("commander");
+let node_path = require("node:path");
+node_path = __toESM(node_path, 1);
 let picocolors = require("picocolors");
 picocolors = __toESM(picocolors, 1);
 let node_fs = require("node:fs");
 node_fs = __toESM(node_fs, 1);
-let node_path = require("node:path");
-node_path = __toESM(node_path, 1);
 let package_manager_detector_detect = require("package-manager-detector/detect");
 let ignore = require("ignore");
 ignore = __toESM(ignore, 1);
@@ -450,8 +450,11 @@ const spinner = (text) => (0, ora.default)({ text });
 const SKILL_NAME = "react-grab";
 const SKILL_SOURCE = (0, node_url.fileURLToPath)(new URL("../skills/react-grab", require("url").pathToFileURL(__filename).href));
 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 installedSkillDir = (agent, global, cwd) => (0, node_path.join)((0, agent_install_skill.isUniversalSkillAgent)(agent) ? (0, agent_install_skill.getCanonicalSkillsDir)(global, cwd) : (0, agent_install_skill.getSkillAgentDir)(agent, {
+	global,
+	cwd
+}), SKILL_NAME);
+const promptSkillInstall = async ({ yes = false, global = false, cwd = process.cwd() } = {}) => {
 	const detectedAgents = await detectAvailableAgents();
 	if (detectedAgents.length === 0) {
 		logger.warn("No supported agents detected.");
@@ -462,7 +465,7 @@ const promptSkillInstall = async ({ yes = false } = {}) => {
 		const { agents } = await prompts$1({
 			type: "multiselect",
 			name: "agents",
-			message: "Install the React Grab skill for:",
+			message: `Install the React Grab skill (${global ? "global" : "this project"}) for:`,
 			choices: detectedAgents.map((agent) => ({
 				title: agentLabel(agent),
 				value: agent,
@@ -478,7 +481,8 @@ const promptSkillInstall = async ({ yes = false } = {}) => {
 	const { installed, failed } = await (0, agent_install_skill.add)({
 		source: SKILL_SOURCE,
 		agents: selectedAgents,
-		global: true,
+		global,
+		cwd,
 		mode: "copy"
 	});
 	if (installed.length === 0) {
@@ -489,19 +493,27 @@ const promptSkillInstall = async ({ yes = false } = {}) => {
 	for (const record of failed) logger.log(`  ${highlighter.error("✗")} ${agentLabel(record.agent)} ${record.error}`);
 	return true;
 };
-const removeSkill = async () => {
-	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, {
+const removeSkill = async (cwd = process.cwd()) => {
+	const agents = await detectAvailableAgents();
+	const removedAgents = [];
+	const dirsToRemove = /* @__PURE__ */ new Set();
+	for (const agent of agents) {
+		const present = [installedSkillDir(agent, false, cwd), installedSkillDir(agent, true, cwd)].filter((dir) => (0, node_fs.existsSync)(dir));
+		if (present.length === 0) continue;
+		removedAgents.push(agent);
+		for (const dir of present) dirsToRemove.add(dir);
+	}
+	for (const skillDir of dirsToRemove) (0, node_fs.rmSync)(skillDir, {
 		recursive: true,
 		force: true
 	});
-	for (const agent of agentsWithSkill) logger.log(`  ${highlighter.success("✓")} ${agentLabel(agent)}`);
-	return agentsWithSkill.length;
+	for (const agent of removedAgents) logger.log(`  ${highlighter.success("✓")} ${agentLabel(agent)}`);
+	return removedAgents.length;
 };
 //#endregion
 //#region src/commands/add.ts
-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) => {
+const VERSION$5 = "0.1.41";
+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()).option("-g, --global", "install the skill globally instead of in the project", false).action(async (opts) => {
 	console.log(`${picocolors.default.magenta("✿")} ${picocolors.default.bold("React Grab")} ${picocolors.default.gray(VERSION$5)}`);
 	console.log();
 	try {
@@ -516,7 +528,11 @@ const add = new commander.Command().name("add").alias("install").description("in
 		}
 		preflightSpinner.succeed();
 		logger.break();
-		if (!await promptSkillInstall({ yes: isNonInteractive }) && isNonInteractive) {
+		if (!await promptSkillInstall({
+			yes: isNonInteractive,
+			global: opts.global,
+			cwd: (0, node_path.resolve)(opts.cwd)
+		}) && isNonInteractive) {
 			logger.break();
 			process.exit(1);
 		}
@@ -1095,6 +1111,7 @@ const previewCdnTransform = (projectRoot, framework, nextRouterType, targetCdnDo
 //#region src/utils/constants.ts
 const MAX_KEY_HOLD_DURATION_MS = 2e3;
 const DEFAULT_WATCH_DIR = ".react-grab";
+const MAX_GRAB_AGE_MS = 300 * 1e3;
 //#endregion
 //#region src/utils/format-activation-key.ts
 const formatActivationKeyDisplay = (activationKey) => {
@@ -1112,7 +1129,7 @@ const formatActivationKeyDisplay = (activationKey) => {
 };
 //#endregion
 //#region src/commands/configure.ts
-const VERSION$4 = "0.1.40";
+const VERSION$4 = "0.1.41";
 const isMac = process.platform === "darwin";
 const META_LABEL = isMac ? "Cmd" : "Win";
 const ALT_LABEL = isMac ? "Option" : "Alt";
@@ -1731,7 +1748,7 @@ const installPackagesWithFeedback = async (packages, packageManager, projectRoot
 };
 //#endregion
 //#region src/commands/init.ts
-const VERSION$3 = "0.1.40";
+const VERSION$3 = "0.1.41";
 const REPORT_URL = "https://react-grab.com/api/report-cli";
 const DOCS_URL = "https://github.com/aidenybai/react-grab";
 const reportToCli = (type, config, error) => {
@@ -1798,7 +1815,7 @@ const failWithManualSetup = (failingSpinner, message, { listSupportedFrameworks
 	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) => {
+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()).option("-g, --global", "install the skill globally instead of in the project", false).action(async (opts) => {
 	console.log(`${picocolors.default.magenta("✿")} ${picocolors.default.bold("React Grab")} ${picocolors.default.gray(VERSION$3)}`);
 	console.log();
 	try {
@@ -1956,7 +1973,11 @@ const init = new commander.Command().name("init").alias("setup").description("in
 				}
 			}
 			logger.break();
-			await promptSkillInstall({ yes: isNonInteractive });
+			await promptSkillInstall({
+				yes: isNonInteractive,
+				global: opts.global,
+				cwd
+			});
 			logger.break();
 			process.exit(0);
 		}
@@ -2022,7 +2043,11 @@ const init = new commander.Command().name("init").alias("setup").description("in
 		let didInstallSkill = false;
 		if (!isNonInteractive) {
 			logger.break();
-			didInstallSkill = await promptSkillInstall({ yes: isNonInteractive });
+			didInstallSkill = await promptSkillInstall({
+				yes: isNonInteractive,
+				global: opts.global,
+				cwd
+			});
 		}
 		const result = previewTransform(projectInfo.projectRoot, finalFramework, finalNextRouterType, false, opts.force);
 		if (!result.success) {
@@ -2417,18 +2442,48 @@ const readGrabCursor = (dir) => {
 		return 0;
 	}
 };
+const grabReceivedAt = (line) => {
+	try {
+		const value = JSON.parse(line).receivedAt;
+		return typeof value === "number" ? value : null;
+	} catch {
+		return null;
+	}
+};
 const consumeGrabs = (dir, options) => {
 	const lines = readCompleteGrabLines(dir);
 	if (options.all) return lines;
+	const maxAgeMs = options.maxAgeMs ?? 0;
 	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);
+	const total = lines.length;
+	const now = Date.now();
+	const fresh = [];
+	let index = Math.min(cursor, total);
+	while (index < total && (options.limit <= 0 || fresh.length < options.limit)) {
+		const line = lines[index];
+		index += 1;
+		if (maxAgeMs > 0) {
+			const receivedAt = grabReceivedAt(line);
+			if (receivedAt !== null && now - receivedAt > maxAgeMs) continue;
+		}
+		fresh.push(line);
+	}
+	if (index !== cursor) node_fs.default.writeFileSync(cursorFilePath(dir), String(index));
+	return fresh;
 };
 //#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 parseWaitMs = (raw) => {
+	if (!raw) return 0;
+	if (/^(inf|infinite|forever)$/i.test(raw.trim())) return Number.POSITIVE_INFINITY;
+	const ms = Number(raw);
+	return Number.isFinite(ms) && ms > 0 ? ms : 0;
+};
+const parseNonNegativeInt = (raw, fallback) => {
+	const value = Number(raw);
+	return Number.isInteger(value) && value >= 0 ? value : fallback;
+};
+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> (or 'infinite') for a 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("--max-age <ms>", "skip grabs captured longer ago than <ms> (0 = never evict)", String(MAX_GRAB_AGE_MS)).option("--all", "print the entire history without advancing the cursor").action(async (options) => {
 	const dir = node_path.default.resolve(options.dir);
 	try {
 		prepareWorkDir(dir);
@@ -2437,19 +2492,20 @@ const read = new commander.Command().name("read").description("print React Grab
 		process.exit(1);
 	}
 	unrefStdin();
-	const limitRaw = Number(options.limit);
-	const limit = Number.isInteger(limitRaw) && limitRaw >= 0 ? limitRaw : 50;
+	const limit = parseNonNegativeInt(options.limit, 50);
+	const maxAgeMs = parseNonNegativeInt(options.maxAge, MAX_GRAB_AGE_MS);
 	const all = Boolean(options.all);
 	const drain = () => {
 		const fresh = consumeGrabs(dir, {
 			limit,
-			all
+			all,
+			maxAgeMs
 		});
 		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);
+	const waitMs = parseWaitMs(options.wait);
+	const deadline = waitMs === Number.POSITIVE_INFINITY ? Number.POSITIVE_INFINITY : Date.now() + waitMs;
 	if (drain() > 0) process.exit(0);
 	while (Date.now() < deadline) {
 		await sleep(200);
@@ -2459,7 +2515,7 @@ const read = new commander.Command().name("read").description("print React Grab
 });
 //#endregion
 //#region src/commands/remove.ts
-const VERSION$2 = "0.1.40";
+const VERSION$2 = "0.1.41";
 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();
@@ -2476,7 +2532,7 @@ const remove = new commander.Command().name("remove").description("uninstall the
 });
 //#endregion
 //#region src/commands/upgrade.ts
-const VERSION$1 = "0.1.40";
+const VERSION$1 = "0.1.41";
 const NPM_REGISTRY_URL = "https://registry.npmjs.org/react-grab/latest";
 const fetchLatestVersion = async () => {
 	try {
@@ -2701,7 +2757,7 @@ const watch = new commander.Command().name("watch").description("start a backgro
 });
 //#endregion
 //#region src/cli.ts
-const VERSION = "0.1.40";
+const VERSION = "0.1.41";
 const VERSION_API_URL = "https://www.react-grab.com/api/version";
 process.on("SIGINT", () => process.exit(0));
 process.on("SIGTERM", () => process.exit(0));

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { Command } from "commander";
+import path, { basename, delimiter, dirname, join, relative, resolve } from "node:path";
 import pc from "picocolors";
 import fs, { accessSync, constants, existsSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
-import path, { basename, delimiter, dirname, join, relative, resolve } from "node:path";
 import { detect } from "package-manager-detector/detect";
 import ignore from "ignore";
 import { fileURLToPath } from "node:url";
@@ -422,8 +422,11 @@ const spinner = (text) => ora({ text });
 const SKILL_NAME = "react-grab";
 const SKILL_SOURCE = fileURLToPath(new URL("../skills/react-grab", import.meta.url));
 const agentLabel = (agent) => getSkillAgentConfig(agent).displayName;
-const installedSkillDir = (agent) => join(isUniversalSkillAgent(agent) ? getCanonicalSkillsDir(true) : getSkillAgentDir(agent, { global: true }), SKILL_NAME);
-const promptSkillInstall = async ({ yes = false } = {}) => {
+const installedSkillDir = (agent, global, cwd) => join(isUniversalSkillAgent(agent) ? getCanonicalSkillsDir(global, cwd) : getSkillAgentDir(agent, {
+	global,
+	cwd
+}), SKILL_NAME);
+const promptSkillInstall = async ({ yes = false, global = false, cwd = process.cwd() } = {}) => {
 	const detectedAgents = await detectAvailableAgents();
 	if (detectedAgents.length === 0) {
 		logger.warn("No supported agents detected.");
@@ -434,7 +437,7 @@ const promptSkillInstall = async ({ yes = false } = {}) => {
 		const { agents } = await prompts({
 			type: "multiselect",
 			name: "agents",
-			message: "Install the React Grab skill for:",
+			message: `Install the React Grab skill (${global ? "global" : "this project"}) for:`,
 			choices: detectedAgents.map((agent) => ({
 				title: agentLabel(agent),
 				value: agent,
@@ -450,7 +453,8 @@ const promptSkillInstall = async ({ yes = false } = {}) => {
 	const { installed, failed } = await add({
 		source: SKILL_SOURCE,
 		agents: selectedAgents,
-		global: true,
+		global,
+		cwd,
 		mode: "copy"
 	});
 	if (installed.length === 0) {
@@ -461,19 +465,27 @@ const promptSkillInstall = async ({ yes = false } = {}) => {
 	for (const record of failed) logger.log(`  ${highlighter.error("✗")} ${agentLabel(record.agent)} ${record.error}`);
 	return true;
 };
-const removeSkill = async () => {
-	const agentsWithSkill = (await detectAvailableAgents()).filter((agent) => existsSync(installedSkillDir(agent)));
-	for (const skillDir of new Set(agentsWithSkill.map(installedSkillDir))) rmSync(skillDir, {
+const removeSkill = async (cwd = process.cwd()) => {
+	const agents = await detectAvailableAgents();
+	const removedAgents = [];
+	const dirsToRemove = /* @__PURE__ */ new Set();
+	for (const agent of agents) {
+		const present = [installedSkillDir(agent, false, cwd), installedSkillDir(agent, true, cwd)].filter((dir) => existsSync(dir));
+		if (present.length === 0) continue;
+		removedAgents.push(agent);
+		for (const dir of present) dirsToRemove.add(dir);
+	}
+	for (const skillDir of dirsToRemove) rmSync(skillDir, {
 		recursive: true,
 		force: true
 	});
-	for (const agent of agentsWithSkill) logger.log(`  ${highlighter.success("✓")} ${agentLabel(agent)}`);
-	return agentsWithSkill.length;
+	for (const agent of removedAgents) logger.log(`  ${highlighter.success("✓")} ${agentLabel(agent)}`);
+	return removedAgents.length;
 };
 //#endregion
 //#region src/commands/add.ts
-const VERSION$5 = "0.1.40";
-const add$1 = new 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) => {
+const VERSION$5 = "0.1.41";
+const add$1 = new 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()).option("-g, --global", "install the skill globally instead of in the project", false).action(async (opts) => {
 	console.log(`${pc.magenta("✿")} ${pc.bold("React Grab")} ${pc.gray(VERSION$5)}`);
 	console.log();
 	try {
@@ -488,7 +500,11 @@ const add$1 = new Command().name("add").alias("install").description("install th
 		}
 		preflightSpinner.succeed();
 		logger.break();
-		if (!await promptSkillInstall({ yes: isNonInteractive }) && isNonInteractive) {
+		if (!await promptSkillInstall({
+			yes: isNonInteractive,
+			global: opts.global,
+			cwd: resolve(opts.cwd)
+		}) && isNonInteractive) {
 			logger.break();
 			process.exit(1);
 		}
@@ -1067,6 +1083,7 @@ const previewCdnTransform = (projectRoot, framework, nextRouterType, targetCdnDo
 //#region src/utils/constants.ts
 const MAX_KEY_HOLD_DURATION_MS = 2e3;
 const DEFAULT_WATCH_DIR = ".react-grab";
+const MAX_GRAB_AGE_MS = 300 * 1e3;
 //#endregion
 //#region src/utils/format-activation-key.ts
 const formatActivationKeyDisplay = (activationKey) => {
@@ -1084,7 +1101,7 @@ const formatActivationKeyDisplay = (activationKey) => {
 };
 //#endregion
 //#region src/commands/configure.ts
-const VERSION$4 = "0.1.40";
+const VERSION$4 = "0.1.41";
 const isMac = process.platform === "darwin";
 const META_LABEL = isMac ? "Cmd" : "Win";
 const ALT_LABEL = isMac ? "Option" : "Alt";
@@ -1703,7 +1720,7 @@ const installPackagesWithFeedback = async (packages, packageManager, projectRoot
 };
 //#endregion
 //#region src/commands/init.ts
-const VERSION$3 = "0.1.40";
+const VERSION$3 = "0.1.41";
 const REPORT_URL = "https://react-grab.com/api/report-cli";
 const DOCS_URL = "https://github.com/aidenybai/react-grab";
 const reportToCli = (type, config, error) => {
@@ -1770,7 +1787,7 @@ const failWithManualSetup = (failingSpinner, message, { listSupportedFrameworks
 	logger.break();
 	process.exit(1);
 };
-const init = new 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) => {
+const init = new 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()).option("-g, --global", "install the skill globally instead of in the project", false).action(async (opts) => {
 	console.log(`${pc.magenta("✿")} ${pc.bold("React Grab")} ${pc.gray(VERSION$3)}`);
 	console.log();
 	try {
@@ -1928,7 +1945,11 @@ const init = new Command().name("init").alias("setup").description("initialize R
 				}
 			}
 			logger.break();
-			await promptSkillInstall({ yes: isNonInteractive });
+			await promptSkillInstall({
+				yes: isNonInteractive,
+				global: opts.global,
+				cwd
+			});
 			logger.break();
 			process.exit(0);
 		}
@@ -1994,7 +2015,11 @@ const init = new Command().name("init").alias("setup").description("initialize R
 		let didInstallSkill = false;
 		if (!isNonInteractive) {
 			logger.break();
-			didInstallSkill = await promptSkillInstall({ yes: isNonInteractive });
+			didInstallSkill = await promptSkillInstall({
+				yes: isNonInteractive,
+				global: opts.global,
+				cwd
+			});
 		}
 		const result = previewTransform(projectInfo.projectRoot, finalFramework, finalNextRouterType, false, opts.force);
 		if (!result.success) {
@@ -2389,18 +2414,48 @@ const readGrabCursor = (dir) => {
 		return 0;
 	}
 };
+const grabReceivedAt = (line) => {
+	try {
+		const value = JSON.parse(line).receivedAt;
+		return typeof value === "number" ? value : null;
+	} catch {
+		return null;
+	}
+};
 const consumeGrabs = (dir, options) => {
 	const lines = readCompleteGrabLines(dir);
 	if (options.all) return lines;
+	const maxAgeMs = options.maxAgeMs ?? 0;
 	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) fs.writeFileSync(cursorFilePath(dir), String(end));
-	return lines.slice(start, end);
+	const total = lines.length;
+	const now = Date.now();
+	const fresh = [];
+	let index = Math.min(cursor, total);
+	while (index < total && (options.limit <= 0 || fresh.length < options.limit)) {
+		const line = lines[index];
+		index += 1;
+		if (maxAgeMs > 0) {
+			const receivedAt = grabReceivedAt(line);
+			if (receivedAt !== null && now - receivedAt > maxAgeMs) continue;
+		}
+		fresh.push(line);
+	}
+	if (index !== cursor) fs.writeFileSync(cursorFilePath(dir), String(index));
+	return fresh;
 };
 //#endregion
 //#region src/commands/read.ts
-const read = new 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 parseWaitMs = (raw) => {
+	if (!raw) return 0;
+	if (/^(inf|infinite|forever)$/i.test(raw.trim())) return Number.POSITIVE_INFINITY;
+	const ms = Number(raw);
+	return Number.isFinite(ms) && ms > 0 ? ms : 0;
+};
+const parseNonNegativeInt = (raw, fallback) => {
+	const value = Number(raw);
+	return Number.isInteger(value) && value >= 0 ? value : fallback;
+};
+const read = new 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> (or 'infinite') for a 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("--max-age <ms>", "skip grabs captured longer ago than <ms> (0 = never evict)", String(MAX_GRAB_AGE_MS)).option("--all", "print the entire history without advancing the cursor").action(async (options) => {
 	const dir = path.resolve(options.dir);
 	try {
 		prepareWorkDir(dir);
@@ -2409,19 +2464,20 @@ const read = new Command().name("read").description("print React Grab selections
 		process.exit(1);
 	}
 	unrefStdin();
-	const limitRaw = Number(options.limit);
-	const limit = Number.isInteger(limitRaw) && limitRaw >= 0 ? limitRaw : 50;
+	const limit = parseNonNegativeInt(options.limit, 50);
+	const maxAgeMs = parseNonNegativeInt(options.maxAge, MAX_GRAB_AGE_MS);
 	const all = Boolean(options.all);
 	const drain = () => {
 		const fresh = consumeGrabs(dir, {
 			limit,
-			all
+			all,
+			maxAgeMs
 		});
 		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);
+	const waitMs = parseWaitMs(options.wait);
+	const deadline = waitMs === Number.POSITIVE_INFINITY ? Number.POSITIVE_INFINITY : Date.now() + waitMs;
 	if (drain() > 0) process.exit(0);
 	while (Date.now() < deadline) {
 		await sleep(200);
@@ -2431,7 +2487,7 @@ const read = new Command().name("read").description("print React Grab selections
 });
 //#endregion
 //#region src/commands/remove.ts
-const VERSION$2 = "0.1.40";
+const VERSION$2 = "0.1.41";
 const remove = new Command().name("remove").description("uninstall the React Grab skill from your agent").action(async () => {
 	console.log(`${pc.magenta("✿")} ${pc.bold("React Grab")} ${pc.gray(VERSION$2)}`);
 	console.log();
@@ -2448,7 +2504,7 @@ const remove = new Command().name("remove").description("uninstall the React Gra
 });
 //#endregion
 //#region src/commands/upgrade.ts
-const VERSION$1 = "0.1.40";
+const VERSION$1 = "0.1.41";
 const NPM_REGISTRY_URL = "https://registry.npmjs.org/react-grab/latest";
 const fetchLatestVersion = async () => {
 	try {
@@ -2673,7 +2729,7 @@ const watch = new Command().name("watch").description("start a background daemon
 });
 //#endregion
 //#region src/cli.ts
-const VERSION = "0.1.40";
+const VERSION = "0.1.41";
 const VERSION_API_URL = "https://www.react-grab.com/api/version";
 process.on("SIGINT", () => process.exit(0));
 process.on("SIGTERM", () => process.exit(0));