@react-grab/cli 0.1.43 → 0.1.44-dev.099016d

package/dist/cli.js

@@ -25,6 +25,71 @@ const AGENT_ENVIRONMENT_VARIABLES = [
 const isEnvironmentVariableSet = (variable) => Boolean(process.env[variable]);
 const detectNonInteractive = (yesFlag) => yesFlag || AGENT_ENVIRONMENT_VARIABLES.some(isEnvironmentVariableSet) || !process.stdin.isTTY;
 //#endregion
+//#region src/utils/react-grab-code.ts
+const REACT_GRAB_SPECIFIER_PATTERN = String.raw`react-grab(?:\/[^"']+)?`;
+const stripComments = (content) => content.replace(/<!--[\s\S]*?-->/g, "").replace(/\{\/\*[\s\S]*?\*\/\}/g, "").replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|\s)\/\/.*$/gm, "$1");
+const stripTypeOnlyReactGrabImports = (content) => {
+	return content.replace(new RegExp(String.raw`import\s+type\s+[^;]+from\s+["']${REACT_GRAB_SPECIFIER_PATTERN}["'];?`, "g"), "").replace(new RegExp(String.raw`import\s*\{\s*type\s+[^,}]+(?:\s*,\s*type\s+[^,}]+)*\s*,?\s*\}\s*from\s+["']${REACT_GRAB_SPECIFIER_PATTERN}["'];?`, "g"), "");
+};
+const hasReactGrabSetupCode = (content) => {
+	const setupCandidateContent = stripTypeOnlyReactGrabImports(stripComments(content));
+	return [
+		new RegExp(String.raw`import\s*\(\s*["']${REACT_GRAB_SPECIFIER_PATTERN}["']\s*\)`),
+		new RegExp(String.raw`import\s+(?!type\b)(?:[^"';]+from\s+)?["']${REACT_GRAB_SPECIFIER_PATTERN}["']`),
+		new RegExp(String.raw`require\s*\(\s*["']${REACT_GRAB_SPECIFIER_PATTERN}["']\s*\)`),
+		/<Script[\s\S]*?src\s*=\s*(?:["'][^"']*react-grab[^"']*["']|\{(?:["'][^"']*react-grab[^"']*["']|`[^`]*react-grab[^`]*`)\})/i,
+		/<script[\s\S]*?src\s*=\s*["'][^"']*react-grab[^"']*["']/i
+	].some((pattern) => pattern.test(setupCandidateContent));
+};
+//#endregion
+//#region src/utils/react-grab-setup-files.ts
+const COMPONENT_EXTENSIONS = [
+	"tsx",
+	"jsx",
+	"ts",
+	"js"
+];
+const INSTRUMENTATION_EXTENSIONS = [
+	"ts",
+	"tsx",
+	"js",
+	"jsx",
+	"mts",
+	"cts",
+	"mjs",
+	"cjs"
+];
+const ROUTE_EXTENSIONS = ["tsx", "jsx"];
+const createFileCandidates = (projectRoot, directories, baseName, extensions) => {
+	const fileCandidates = [];
+	for (const directory of directories) for (const extension of extensions) fileCandidates.push(join(projectRoot, directory, `${baseName}.${extension}`));
+	return fileCandidates;
+};
+const findExistingFile = (fileCandidates) => {
+	for (const filePath of fileCandidates) if (existsSync(filePath)) return filePath;
+	return null;
+};
+const getLayoutFileCandidates = (projectRoot) => createFileCandidates(projectRoot, ["app", "src/app"], "layout", COMPONENT_EXTENSIONS);
+const getDocumentFileCandidates = (projectRoot) => createFileCandidates(projectRoot, ["pages", "src/pages"], "_document", COMPONENT_EXTENSIONS);
+const getInstrumentationFileCandidates = (projectRoot) => createFileCandidates(projectRoot, ["", "src"], "instrumentation-client", INSTRUMENTATION_EXTENSIONS);
+const getIndexHtmlCandidates = (projectRoot) => [join(projectRoot, "index.html"), join(projectRoot, "public", "index.html")];
+const getEntryFileCandidates = (projectRoot) => [...createFileCandidates(projectRoot, ["src"], "index", COMPONENT_EXTENSIONS), ...createFileCandidates(projectRoot, ["src"], "main", COMPONENT_EXTENSIONS)];
+const getTanStackRootFileCandidates = (projectRoot) => createFileCandidates(projectRoot, ["src/routes", "app/routes"], "__root", ROUTE_EXTENSIONS);
+const getReactGrabSetupFileCandidates = (projectRoot) => [
+	...getLayoutFileCandidates(projectRoot),
+	...getDocumentFileCandidates(projectRoot),
+	...getInstrumentationFileCandidates(projectRoot),
+	...getIndexHtmlCandidates(projectRoot),
+	...getEntryFileCandidates(projectRoot),
+	...getTanStackRootFileCandidates(projectRoot)
+];
+const findLayoutFile = (projectRoot) => findExistingFile(getLayoutFileCandidates(projectRoot));
+const findDocumentFile = (projectRoot) => findExistingFile(getDocumentFileCandidates(projectRoot));
+const findIndexHtml = (projectRoot) => findExistingFile(getIndexHtmlCandidates(projectRoot));
+const findEntryFile = (projectRoot) => findExistingFile(getEntryFileCandidates(projectRoot));
+const findTanStackRootFile = (projectRoot) => findExistingFile(getTanStackRootFileCandidates(projectRoot));
+const isInstrumentationFile = (filePath) => /(?:^|[/\\])instrumentation-client\.[cm]?[jt]sx?$/.test(filePath);
+//#endregion
 //#region src/utils/detect.ts
 const VALID_PACKAGE_MANAGERS = new Set([
 	"npm",
@@ -238,10 +303,14 @@ const scanDirectoryForProjects = (rootDirectory, ignorer, maxDepth, currentDepth
 	return projects;
 };
 const MAX_SCAN_DEPTH = 2;
+const normalizePathForComparison = (filePath) => filePath.replace(/\\/g, "/");
 const findReactProjects = (projectRoot) => {
-	if (detectMonorepo(projectRoot)) {
-		const workspaceProjects = findWorkspaceProjects(projectRoot);
-		if (workspaceProjects.length > 0) return workspaceProjects;
+	const monorepoRoot = detectMonorepo(projectRoot) ? projectRoot : findEnclosingMonorepoRoot(projectRoot);
+	if (monorepoRoot) {
+		const workspaceProjects = findWorkspaceProjects(monorepoRoot);
+		const localProject = projectRoot === monorepoRoot ? null : buildReactProject(projectRoot);
+		const projects = localProject ? [localProject, ...workspaceProjects.filter((project) => normalizePathForComparison(project.path) !== normalizePathForComparison(localProject.path))] : workspaceProjects;
+		if (projects.length > 0) return projects;
 	}
 	const scannedProjects = scanDirectoryForProjects(projectRoot, loadGitignore(projectRoot), MAX_SCAN_DEPTH);
 	if (scannedProjects.length > 0) return scannedProjects;
@@ -253,47 +322,20 @@ const findReactProjects = (projectRoot) => {
 	}
 	return [];
 };
-const hasReactGrabInFile = (filePath) => {
+const hasReactGrabSetupInFile = (filePath) => {
 	if (!existsSync(filePath)) return false;
 	try {
-		const content = readFileSync(filePath, "utf-8");
-		return [
-			/["'`][^"'`]*react-grab/,
-			/react-grab[^"'`]*["'`]/,
-			/<[^>]*react-grab/i,
-			/import[^;]*react-grab/i,
-			/require[^)]*react-grab/i,
-			/from\s+[^;]*react-grab/i,
-			/src[^>]*react-grab/i
-		].some((pattern) => pattern.test(content));
+		return hasReactGrabSetupCode(readFileSync(filePath, "utf-8"));
 	} catch {
 		return false;
 	}
 };
-const detectReactGrab = (projectRoot) => {
-	if (readMergedDependencies(projectRoot)?.["react-grab"]) return true;
-	return [
-		join(projectRoot, "app", "layout.tsx"),
-		join(projectRoot, "app", "layout.jsx"),
-		join(projectRoot, "src", "app", "layout.tsx"),
-		join(projectRoot, "src", "app", "layout.jsx"),
-		join(projectRoot, "pages", "_document.tsx"),
-		join(projectRoot, "pages", "_document.jsx"),
-		join(projectRoot, "instrumentation-client.ts"),
-		join(projectRoot, "instrumentation-client.js"),
-		join(projectRoot, "src", "instrumentation-client.ts"),
-		join(projectRoot, "src", "instrumentation-client.js"),
-		join(projectRoot, "index.html"),
-		join(projectRoot, "public", "index.html"),
-		join(projectRoot, "src", "index.tsx"),
-		join(projectRoot, "src", "index.ts"),
-		join(projectRoot, "src", "main.tsx"),
-		join(projectRoot, "src", "main.ts"),
-		join(projectRoot, "src", "routes", "__root.tsx"),
-		join(projectRoot, "src", "routes", "__root.jsx"),
-		join(projectRoot, "app", "routes", "__root.tsx"),
-		join(projectRoot, "app", "routes", "__root.jsx")
-	].some(hasReactGrabInFile);
+const detectReactGrabDependency = (projectRoot) => {
+	const dependencies = readMergedDependencies(projectRoot);
+	return Boolean(dependencies?.["react-grab"]);
+};
+const detectReactGrabConfigured = (projectRoot) => {
+	return getReactGrabSetupFileCandidates(projectRoot).some(hasReactGrabSetupInFile);
 };
 const detectUnsupportedFramework = (projectRoot) => {
 	const dependencies = readMergedDependencies(projectRoot);
@@ -314,13 +356,17 @@ const detectReactGrabVersion = (projectRoot) => {
 const detectProject = async (projectRoot = process.cwd()) => {
 	const localFramework = detectFramework(projectRoot);
 	const framework = localFramework === "unknown" ? detectFrameworkFromMonorepoRoot(projectRoot) : localFramework;
+	const packageManager = await detectPackageManager(projectRoot);
+	const isMonorepo = detectMonorepo(projectRoot) || findEnclosingMonorepoRoot(projectRoot) !== null;
+	const isReactGrabConfigured = detectReactGrabConfigured(projectRoot);
 	return {
-		packageManager: await detectPackageManager(projectRoot),
+		packageManager,
 		framework,
 		nextRouterType: framework === "next" ? detectNextRouterType(projectRoot) : "unknown",
-		isMonorepo: detectMonorepo(projectRoot),
+		isMonorepo,
 		projectRoot,
-		hasReactGrab: detectReactGrab(projectRoot),
+		hasReactGrab: detectReactGrabDependency(projectRoot) || isReactGrabConfigured,
+		isReactGrabConfigured,
 		reactGrabVersion: detectReactGrabVersion(projectRoot),
 		unsupportedFramework: detectUnsupportedFramework(projectRoot)
 	};
@@ -434,6 +480,13 @@ const promptSkillInstall = async ({ yes = false, global = false, cwd = process.c
 	}
 	let selectedAgents = detectedAgents;
 	if (!yes) {
+		const { confirmed } = await prompts({
+			type: "confirm",
+			name: "confirmed",
+			message: `Install the React Grab skill (${global ? "global" : "this project"})?`,
+			initial: true
+		});
+		if (!confirmed) return false;
 		const { agents } = await prompts({
 			type: "multiselect",
 			name: "agents",
@@ -484,7 +537,7 @@ const removeSkill = async ({ cwd = process.cwd(), global = false } = {}) => {
 };
 //#endregion
 //#region src/commands/add.ts
-const VERSION$5 = "0.1.43";
+const VERSION$5 = "0.1.44-dev.099016d";
 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();
@@ -639,80 +692,14 @@ const TANSTACK_EFFECT = `useEffect(() => {
 const SCRIPT_IMPORT = "import Script from \"next/script\";";
 //#endregion
 //#region src/utils/transform.ts
-const hasReactGrabCode = (content) => {
-	return [
-		/["'`][^"'`]*react-grab/,
-		/react-grab[^"'`]*["'`]/,
-		/<[^>]*react-grab/i,
-		/import[^;]*react-grab/i,
-		/require[^)]*react-grab/i,
-		/from\s+[^;]*react-grab/i,
-		/src[^>]*react-grab/i,
-		/href[^>]*react-grab/i
-	].some((pattern) => pattern.test(content));
-};
-const findLayoutFile = (projectRoot) => {
-	const possiblePaths = [
-		join(projectRoot, "app", "layout.tsx"),
-		join(projectRoot, "app", "layout.jsx"),
-		join(projectRoot, "src", "app", "layout.tsx"),
-		join(projectRoot, "src", "app", "layout.jsx")
-	];
-	for (const filePath of possiblePaths) if (existsSync(filePath)) return filePath;
-	return null;
-};
-const findInstrumentationFile = (projectRoot) => {
-	const possiblePaths = [
-		join(projectRoot, "instrumentation-client.ts"),
-		join(projectRoot, "instrumentation-client.js"),
-		join(projectRoot, "src", "instrumentation-client.ts"),
-		join(projectRoot, "src", "instrumentation-client.js")
-	];
-	for (const filePath of possiblePaths) if (existsSync(filePath)) return filePath;
-	return null;
-};
 const hasReactGrabInInstrumentation = (projectRoot) => {
-	const instrumentationPath = findInstrumentationFile(projectRoot);
-	if (!instrumentationPath) return false;
-	return hasReactGrabCode(readFileSync(instrumentationPath, "utf-8"));
-};
-const findDocumentFile = (projectRoot) => {
-	const possiblePaths = [
-		join(projectRoot, "pages", "_document.tsx"),
-		join(projectRoot, "pages", "_document.jsx"),
-		join(projectRoot, "src", "pages", "_document.tsx"),
-		join(projectRoot, "src", "pages", "_document.jsx")
-	];
-	for (const filePath of possiblePaths) if (existsSync(filePath)) return filePath;
-	return null;
+	return findFileWithReactGrabSetup(getInstrumentationFileCandidates(projectRoot)) !== null;
 };
-const findIndexHtml = (projectRoot) => {
-	const possiblePaths = [join(projectRoot, "index.html"), join(projectRoot, "public", "index.html")];
-	for (const filePath of possiblePaths) if (existsSync(filePath)) return filePath;
-	return null;
-};
-const findEntryFile = (projectRoot) => {
-	const possiblePaths = [
-		join(projectRoot, "src", "index.tsx"),
-		join(projectRoot, "src", "index.jsx"),
-		join(projectRoot, "src", "index.ts"),
-		join(projectRoot, "src", "index.js"),
-		join(projectRoot, "src", "main.tsx"),
-		join(projectRoot, "src", "main.jsx"),
-		join(projectRoot, "src", "main.ts"),
-		join(projectRoot, "src", "main.js")
-	];
-	for (const filePath of possiblePaths) if (existsSync(filePath)) return filePath;
-	return null;
-};
-const findTanStackRootFile = (projectRoot) => {
-	const possiblePaths = [
-		join(projectRoot, "src", "routes", "__root.tsx"),
-		join(projectRoot, "src", "routes", "__root.jsx"),
-		join(projectRoot, "app", "routes", "__root.tsx"),
-		join(projectRoot, "app", "routes", "__root.jsx")
-	];
-	for (const filePath of possiblePaths) if (existsSync(filePath)) return filePath;
+const findFileWithReactGrabSetup = (fileCandidates) => {
+	for (const filePath of fileCandidates) {
+		if (!existsSync(filePath)) continue;
+		if (hasReactGrabSetupCode(readFileSync(filePath, "utf-8"))) return filePath;
+	}
 	return null;
 };
 const alreadyConfiguredResult = (filePath) => ({
@@ -721,19 +708,19 @@ const alreadyConfiguredResult = (filePath) => ({
 	message: "React Grab is already configured",
 	noChanges: true
 });
-const transformNextAppRouter = (projectRoot, reactGrabAlreadyConfigured, force = false) => {
+const transformNextAppRouter = (projectRoot, reactGrabAlreadyConfigured) => {
 	const layoutPath = findLayoutFile(projectRoot);
 	if (!layoutPath) return {
 		success: false,
 		filePath: "",
-		message: "Could not find app/layout.tsx or app/layout.jsx"
+		message: "Could not find app/layout.tsx, app/layout.jsx, app/layout.ts, or app/layout.js"
 	};
 	const originalContent = readFileSync(layoutPath, "utf-8");
 	let newContent = originalContent;
-	const hasReactGrabInFile = hasReactGrabCode(originalContent);
+	const hasReactGrabInFile = hasReactGrabSetupCode(originalContent);
 	const hasReactGrabInInstrumentationFile = hasReactGrabInInstrumentation(projectRoot);
-	if (!force && hasReactGrabInFile && reactGrabAlreadyConfigured) return alreadyConfiguredResult(layoutPath);
-	if (!force && (hasReactGrabInFile || hasReactGrabInInstrumentationFile)) return {
+	if (hasReactGrabInFile && reactGrabAlreadyConfigured) return alreadyConfiguredResult(layoutPath);
+	if (hasReactGrabInFile || hasReactGrabInInstrumentationFile) return {
 		success: true,
 		filePath: layoutPath,
 		message: "React Grab is already installed" + (hasReactGrabInInstrumentationFile ? " in instrumentation-client" : " in this file"),
@@ -758,19 +745,19 @@ const transformNextAppRouter = (projectRoot, reactGrabAlreadyConfigured, force =
 		newContent
 	};
 };
-const transformNextPagesRouter = (projectRoot, reactGrabAlreadyConfigured, force = false) => {
+const transformNextPagesRouter = (projectRoot, reactGrabAlreadyConfigured) => {
 	const documentPath = findDocumentFile(projectRoot);
 	if (!documentPath) return {
 		success: false,
 		filePath: "",
-		message: "Could not find pages/_document.tsx or pages/_document.jsx.\n\nTo set up React Grab with Pages Router, create pages/_document.tsx with:\n\n  import { Html, Head, Main, NextScript } from \"next/document\";\n  import Script from \"next/script\";\n\n  export default function Document() {\n    return (\n      <Html>\n        <Head>\n          {process.env.NODE_ENV === \"development\" && (\n            <Script src=\"//unpkg.com/react-grab/dist/index.global.js\" strategy=\"beforeInteractive\" />\n          )}\n        </Head>\n        <body>\n          <Main />\n          <NextScript />\n        </body>\n      </Html>\n    );\n  }"
+		message: "Could not find pages/_document.tsx, pages/_document.jsx, pages/_document.ts, or pages/_document.js.\n\nTo set up React Grab with Pages Router, create pages/_document.tsx with:\n\n  import { Html, Head, Main, NextScript } from \"next/document\";\n  import Script from \"next/script\";\n\n  export default function Document() {\n    return (\n      <Html>\n        <Head>\n          {process.env.NODE_ENV === \"development\" && (\n            <Script src=\"//unpkg.com/react-grab/dist/index.global.js\" strategy=\"beforeInteractive\" />\n          )}\n        </Head>\n        <body>\n          <Main />\n          <NextScript />\n        </body>\n      </Html>\n    );\n  }"
 	};
 	const originalContent = readFileSync(documentPath, "utf-8");
 	let newContent = originalContent;
-	const hasReactGrabInFile = hasReactGrabCode(originalContent);
+	const hasReactGrabInFile = hasReactGrabSetupCode(originalContent);
 	const hasReactGrabInInstrumentationFile = hasReactGrabInInstrumentation(projectRoot);
-	if (!force && hasReactGrabInFile && reactGrabAlreadyConfigured) return alreadyConfiguredResult(documentPath);
-	if (!force && (hasReactGrabInFile || hasReactGrabInInstrumentationFile)) return {
+	if (hasReactGrabInFile && reactGrabAlreadyConfigured) return alreadyConfiguredResult(documentPath);
+	if (hasReactGrabInFile || hasReactGrabInInstrumentationFile) return {
 		success: true,
 		filePath: documentPath,
 		message: "React Grab is already installed" + (hasReactGrabInInstrumentationFile ? " in instrumentation-client" : " in this file"),
@@ -791,7 +778,7 @@ const transformNextPagesRouter = (projectRoot, reactGrabAlreadyConfigured, force
 	};
 };
 const checkExistingInstallation = (filePath, reactGrabAlreadyConfigured) => {
-	if (!hasReactGrabCode(readFileSync(filePath, "utf-8"))) return null;
+	if (!hasReactGrabSetupCode(readFileSync(filePath, "utf-8"))) return null;
 	return {
 		success: true,
 		filePath,
@@ -799,24 +786,20 @@ const checkExistingInstallation = (filePath, reactGrabAlreadyConfigured) => {
 		noChanges: true
 	};
 };
-const transformVite = (projectRoot, reactGrabAlreadyConfigured, force = false) => {
+const transformVite = (projectRoot, reactGrabAlreadyConfigured) => {
 	const entryPath = findEntryFile(projectRoot);
-	if (!force) {
-		const indexPath = findIndexHtml(projectRoot);
-		if (indexPath) {
-			const existingResult = checkExistingInstallation(indexPath, reactGrabAlreadyConfigured);
-			if (existingResult) return existingResult;
-		}
+	const indexPath = findIndexHtml(projectRoot);
+	if (indexPath) {
+		const existingResult = checkExistingInstallation(indexPath, reactGrabAlreadyConfigured);
+		if (existingResult) return existingResult;
 	}
 	if (!entryPath) return {
 		success: false,
 		filePath: "",
 		message: "Could not find entry file (src/index.tsx, src/main.tsx, etc.)"
 	};
-	if (!force) {
-		const existingResult = checkExistingInstallation(entryPath, reactGrabAlreadyConfigured);
-		if (existingResult) return existingResult;
-	}
+	const existingResult = checkExistingInstallation(entryPath, reactGrabAlreadyConfigured);
+	if (existingResult) return existingResult;
 	const originalContent = readFileSync(entryPath, "utf-8");
 	return {
 		success: true,
@@ -826,17 +809,15 @@ const transformVite = (projectRoot, reactGrabAlreadyConfigured, force = false) =
 		newContent: `${VITE_IMPORT}\n\n${originalContent}`
 	};
 };
-const transformWebpack = (projectRoot, reactGrabAlreadyConfigured, force = false) => {
+const transformWebpack = (projectRoot, reactGrabAlreadyConfigured) => {
 	const entryPath = findEntryFile(projectRoot);
 	if (!entryPath) return {
 		success: false,
 		filePath: "",
 		message: "Could not find entry file (src/index.tsx, src/main.tsx, etc.)"
 	};
-	if (!force) {
-		const existingResult = checkExistingInstallation(entryPath, reactGrabAlreadyConfigured);
-		if (existingResult) return existingResult;
-	}
+	const existingResult = checkExistingInstallation(entryPath, reactGrabAlreadyConfigured);
+	if (existingResult) return existingResult;
 	const originalContent = readFileSync(entryPath, "utf-8");
 	return {
 		success: true,
@@ -846,7 +827,7 @@ const transformWebpack = (projectRoot, reactGrabAlreadyConfigured, force = false
 		newContent: `${WEBPACK_IMPORT}\n\n${originalContent}`
 	};
 };
-const transformTanStack = (projectRoot, reactGrabAlreadyConfigured, force = false) => {
+const transformTanStack = (projectRoot, reactGrabAlreadyConfigured) => {
 	const rootPath = findTanStackRootFile(projectRoot);
 	if (!rootPath) return {
 		success: false,
@@ -855,9 +836,9 @@ const transformTanStack = (projectRoot, reactGrabAlreadyConfigured, force = fals
 	};
 	const originalContent = readFileSync(rootPath, "utf-8");
 	let newContent = originalContent;
-	const hasReactGrabInFile = hasReactGrabCode(originalContent);
-	if (!force && hasReactGrabInFile && reactGrabAlreadyConfigured) return alreadyConfiguredResult(rootPath);
-	if (!force && hasReactGrabInFile) return {
+	const hasReactGrabInFile = hasReactGrabSetupCode(originalContent);
+	if (hasReactGrabInFile && reactGrabAlreadyConfigured) return alreadyConfiguredResult(rootPath);
+	if (hasReactGrabInFile) return {
 		success: true,
 		filePath: rootPath,
 		message: "React Grab is already installed in this file",
@@ -900,14 +881,14 @@ const hasFrameworkEntryPoint = (projectRoot, framework, nextRouterType) => {
 		default: return false;
 	}
 };
-const previewTransform = (projectRoot, framework, nextRouterType, reactGrabAlreadyConfigured = false, force = false) => {
+const previewTransform = (projectRoot, framework, nextRouterType, reactGrabAlreadyConfigured = false) => {
 	switch (framework) {
 		case "next":
-			if (nextRouterType === "app") return transformNextAppRouter(projectRoot, reactGrabAlreadyConfigured, force);
-			return transformNextPagesRouter(projectRoot, reactGrabAlreadyConfigured, force);
-		case "vite": return transformVite(projectRoot, reactGrabAlreadyConfigured, force);
-		case "tanstack": return transformTanStack(projectRoot, reactGrabAlreadyConfigured, force);
-		case "webpack": return transformWebpack(projectRoot, reactGrabAlreadyConfigured, force);
+			if (nextRouterType === "app") return transformNextAppRouter(projectRoot, reactGrabAlreadyConfigured);
+			return transformNextPagesRouter(projectRoot, reactGrabAlreadyConfigured);
+		case "vite": return transformVite(projectRoot, reactGrabAlreadyConfigured);
+		case "tanstack": return transformTanStack(projectRoot, reactGrabAlreadyConfigured);
+		case "webpack": return transformWebpack(projectRoot, reactGrabAlreadyConfigured);
 		default: return {
 			success: false,
 			filePath: "",
@@ -961,18 +942,24 @@ const formatOptionsAsJson = (options) => {
 };
 const findReactGrabFile = (projectRoot, framework, nextRouterType) => {
 	switch (framework) {
-		case "next":
-			if (nextRouterType === "app") return findLayoutFile(projectRoot);
-			return findDocumentFile(projectRoot);
+		case "next": {
+			const primaryFile = nextRouterType === "app" ? findLayoutFile(projectRoot) : findDocumentFile(projectRoot);
+			const primarySetupFile = findFileWithReactGrabSetup(nextRouterType === "app" ? getLayoutFileCandidates(projectRoot) : getDocumentFileCandidates(projectRoot));
+			if (primarySetupFile) return primarySetupFile;
+			const instrumentationFile = findFileWithReactGrabSetup(getInstrumentationFileCandidates(projectRoot));
+			if (instrumentationFile) return instrumentationFile;
+			return primaryFile;
+		}
 		case "vite": {
 			const entryFile = findEntryFile(projectRoot);
-			if (entryFile && hasReactGrabCode(readFileSync(entryFile, "utf-8"))) return entryFile;
-			const indexHtml = findIndexHtml(projectRoot);
-			if (indexHtml && hasReactGrabCode(readFileSync(indexHtml, "utf-8"))) return indexHtml;
+			const entrySetupFile = findFileWithReactGrabSetup(getEntryFileCandidates(projectRoot));
+			if (entrySetupFile) return entrySetupFile;
+			const indexHtml = findFileWithReactGrabSetup(getIndexHtmlCandidates(projectRoot));
+			if (indexHtml) return indexHtml;
 			return entryFile;
 		}
-		case "tanstack": return findTanStackRootFile(projectRoot);
-		case "webpack": return findEntryFile(projectRoot);
+		case "tanstack": return findFileWithReactGrabSetup(getTanStackRootFileCandidates(projectRoot)) ?? findTanStackRootFile(projectRoot);
+		case "webpack": return findFileWithReactGrabSetup(getEntryFileCandidates(projectRoot)) ?? findEntryFile(projectRoot);
 		default: return null;
 	}
 };
@@ -1000,13 +987,14 @@ const addOptionsToNextScript = (originalContent, options, filePath) => {
 	};
 };
 const addOptionsToDynamicImport = (originalContent, options, filePath) => {
-	const reactGrabImportWithInitMatch = originalContent.match(/import\s*\(\s*["']react-grab["']\s*\)(?:\.then\s*\(\s*\(m\)\s*=>\s*m\.init\s*\([^)]*\)\s*\))?/);
+	const reactGrabImportWithInitMatch = originalContent.match(/(void\s+)?import\s*\(\s*["']react-grab(?:\/[^"']+)?["']\s*\)(?:\.then\s*\(\s*(?:\(m\)\s*=>\s*m\.init\s*\([^)]*\)|\(\{\s*init\s*\}\)\s*=>\s*init\s*\([^)]*\))\s*\))?/);
 	if (!reactGrabImportWithInitMatch) return {
 		success: false,
 		filePath,
 		message: "Could not find React Grab import"
 	};
-	const newImport = `import("react-grab").then((m) => m.init(${formatOptionsAsJson(options)}))`;
+	const optionsJson = formatOptionsAsJson(options);
+	const newImport = `${reactGrabImportWithInitMatch[1] ?? ""}import("react-grab").then((m) => m.init(${optionsJson}))`;
 	return {
 		success: true,
 		filePath,
@@ -1016,13 +1004,14 @@ const addOptionsToDynamicImport = (originalContent, options, filePath) => {
 	};
 };
 const addOptionsToTanStackImport = (originalContent, options, filePath) => {
-	const reactGrabImportWithInitMatch = originalContent.match(/(?:void\s+import\s*\(\s*["']react-grab["']\s*\)|import\s*\(\s*["']react-grab\/core["']\s*\)\.then\s*\(\s*\(\s*\{\s*init\s*\}\s*\)\s*=>\s*init\s*\([^)]*\)\s*\))/);
+	const reactGrabImportWithInitMatch = originalContent.match(/(?:(void\s+)?import\s*\(\s*["']react-grab\/core["']\s*\)\.then\s*\(\s*(?:\(\s*\{\s*init\s*\}\s*\)\s*=>\s*init\s*\([^)]*\)|\(m\)\s*=>\s*m\.init\s*\([^)]*\))\s*\)|(void\s+)?import\s*\(\s*["']react-grab(?!\/core)(?:\/[^"']+)?["']\s*\))/);
 	if (!reactGrabImportWithInitMatch) return {
 		success: false,
 		filePath,
 		message: "Could not find React Grab import"
 	};
-	const newImport = `import("react-grab/core").then(({ init }) => init(${formatOptionsAsJson(options)}))`;
+	const optionsJson = formatOptionsAsJson(options);
+	const newImport = `${reactGrabImportWithInitMatch[1] ?? reactGrabImportWithInitMatch[2] ?? ""}import("react-grab/core").then(({ init }) => init(${optionsJson}))`;
 	return {
 		success: true,
 		filePath,
@@ -1031,6 +1020,11 @@ const addOptionsToTanStackImport = (originalContent, options, filePath) => {
 		newContent: originalContent.replace(reactGrabImportWithInitMatch[0], newImport)
 	};
 };
+const addOptionsToAnyImport = (originalContent, options, filePath) => {
+	const dynamicImportResult = addOptionsToDynamicImport(originalContent, options, filePath);
+	if (dynamicImportResult.success) return dynamicImportResult;
+	return addOptionsToTanStackImport(originalContent, options, filePath);
+};
 const previewOptionsTransform = (projectRoot, framework, nextRouterType, options) => {
 	const filePath = findReactGrabFile(projectRoot, framework, nextRouterType);
 	if (!filePath) return {
@@ -1039,13 +1033,15 @@ const previewOptionsTransform = (projectRoot, framework, nextRouterType, options
 		message: "Could not find file containing React Grab configuration"
 	};
 	const originalContent = readFileSync(filePath, "utf-8");
-	if (!hasReactGrabCode(originalContent)) return {
+	if (!hasReactGrabSetupCode(originalContent)) return {
 		success: false,
 		filePath,
 		message: "Could not find React Grab code in the file"
 	};
 	switch (framework) {
-		case "next": return addOptionsToNextScript(originalContent, options, filePath);
+		case "next":
+			if (isInstrumentationFile(filePath)) return addOptionsToAnyImport(originalContent, options, filePath);
+			return addOptionsToNextScript(originalContent, options, filePath);
 		case "vite": return addOptionsToDynamicImport(originalContent, options, filePath);
 		case "tanstack": return addOptionsToTanStackImport(originalContent, options, filePath);
 		case "webpack": return addOptionsToDynamicImport(originalContent, options, filePath);
@@ -1103,7 +1099,7 @@ const formatActivationKeyDisplay = (activationKey) => {
 };
 //#endregion
 //#region src/commands/configure.ts
-const VERSION$4 = "0.1.43";
+const VERSION$4 = "0.1.44-dev.099016d";
 const isMac = process.platform === "darwin";
 const META_LABEL = isMac ? "Cmd" : "Win";
 const ALT_LABEL = isMac ? "Option" : "Alt";
@@ -1373,8 +1369,8 @@ const generateSuggestions = (input) => {
 const CONFIG_OPTIONS = [
 	{
 		id: "activationKey",
-		title: "Activation Key",
-		description: "The key used to activate React Grab (e.g., g, k, space)"
+		title: "Shortcut",
+		description: "The shortcut used to activate React Grab (e.g., g, k, space)"
 	},
 	{
 		id: "activationMode",
@@ -1409,7 +1405,7 @@ const comboToString = (combo) => {
 	}
 	return parts.join("+");
 };
-const configure = new Command().name("configure").alias("config").description("configure React Grab options").option("-y, --yes", "skip confirmation prompts", false).option("-k, --key <key>", "activation key (e.g., Meta+K, Ctrl+Shift+G, Space)").option("-m, --mode <mode>", "activation mode (toggle, hold)").option("--hold-duration <ms>", "key hold duration in milliseconds (for hold mode)").option("--allow-input <boolean>", "allow activation inside input fields (true/false)").option("--context-lines <lines>", "max context lines to include").option("--cdn <domain>", "CDN domain (e.g., unpkg.com, custom.react-grab.com)").option("-c, --cwd <cwd>", "working directory (defaults to current directory)", process.cwd()).action(async (opts) => {
+const configure = new Command().name("configure").alias("config").description("configure React Grab options").option("-y, --yes", "skip confirmation prompts", false).option("-k, --key <key>", "shortcut (e.g., Meta+K, Ctrl+Shift+G, Space)").option("-m, --mode <mode>", "activation mode (toggle, hold)").option("--hold-duration <ms>", "key hold duration in milliseconds (for hold mode)").option("--allow-input <boolean>", "allow activation inside input fields (true/false)").option("--context-lines <lines>", "max context lines to include").option("--cdn <domain>", "CDN domain (e.g., unpkg.com, custom.react-grab.com)").option("-c, --cwd <cwd>", "working directory (defaults to current directory)", process.cwd()).action(async (opts) => {
 	console.log(`${pc.magenta("✿")} ${pc.bold("React Grab")} ${pc.gray(VERSION$4)}`);
 	console.log();
 	try {
@@ -1423,6 +1419,13 @@ const configure = new Command().name("configure").alias("config").description("c
 			logger.break();
 			process.exit(1);
 		}
+		if (!projectInfo.isReactGrabConfigured) {
+			preflightSpinner.fail("React Grab is installed, but setup is missing.");
+			logger.break();
+			logger.error(`Run ${highlighter.info("react-grab init")} to add the setup script/import before configuring options.`);
+			logger.break();
+			process.exit(1);
+		}
 		preflightSpinner.succeed();
 		if (opts.cdn) {
 			const result = previewCdnTransform(projectInfo.projectRoot, projectInfo.framework, projectInfo.nextRouterType, opts.cdn);
@@ -1478,7 +1481,7 @@ const configure = new Command().name("configure").alias("config").description("c
 		if (hasFlags) {
 			if (opts.key) {
 				collectedOptions.activationKey = opts.key;
-				logger.log(`  Activation key: ${highlighter.info(formatActivationKeyDisplay(collectedOptions.activationKey))}`);
+				logger.log(`  Shortcut: ${highlighter.info(formatActivationKeyDisplay(collectedOptions.activationKey))}`);
 			}
 			if (opts.mode) {
 				if (opts.mode !== "toggle" && opts.mode !== "hold") {
@@ -1543,7 +1546,7 @@ const configure = new Command().name("configure").alias("config").description("c
 					process.exit(1);
 				}
 				collectedOptions.activationKey = comboToString(selectedCombo);
-				logger.log(`  Activation key: ${highlighter.info(formatActivationKeyDisplay(collectedOptions.activationKey))}`);
+				logger.log(`  Shortcut: ${highlighter.info(formatActivationKeyDisplay(collectedOptions.activationKey))}`);
 			}
 			if (selectedOption === "activationMode") {
 				const { activationMode } = await prompts({
@@ -1728,7 +1731,7 @@ const isTelemetryEnabled = () => {
 };
 //#endregion
 //#region src/commands/init.ts
-const VERSION$3 = "0.1.43";
+const VERSION$3 = "0.1.44-dev.099016d";
 const REPORT_URL = "https://react-grab.com/api/report-cli";
 const DOCS_URL = "https://github.com/aidenybai/react-grab";
 const reportToCli = (type, config, error) => {
@@ -1796,7 +1799,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()).option("-g, --global", "install the skill globally instead of in the project", false).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", "re-run setup checks even when React Grab is already configured", false).option("-k, --key <key>", "shortcut (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 {
@@ -1810,12 +1813,12 @@ const init = new Command().name("init").alias("setup").description("initialize R
 		}
 		const preflightSpinner = spinner("Preflight checks.").start();
 		const projectInfo = await detectProject(cwd);
-		if (projectInfo.hasReactGrab && !opts.force) {
+		if (projectInfo.isReactGrabConfigured && !opts.force) {
 			preflightSpinner.succeed();
 			if (isNonInteractive) {
 				logger.break();
 				logger.warn("React Grab is already installed.");
-				logger.log(`Use ${highlighter.info("--force")} to reconfigure, or remove ${highlighter.info("--yes")} for interactive mode.`);
+				logger.log(`Use ${highlighter.info("--force")} to re-run setup checks, or remove ${highlighter.info("--yes")} for interactive mode.`);
 				logger.break();
 				process.exit(0);
 			}
@@ -1839,12 +1842,12 @@ const init = new Command().name("init").alias("setup").description("initialize R
 				const collectedOptions = {};
 				if (opts.key) {
 					collectedOptions.activationKey = opts.key;
-					logger.log(`  Activation key: ${highlighter.info(formatActivationKeyDisplay(collectedOptions.activationKey))}`);
+					logger.log(`  Shortcut: ${highlighter.info(formatActivationKeyDisplay(collectedOptions.activationKey))}`);
 				} else {
 					const { wantActivationKey } = await prompts({
 						type: "confirm",
 						name: "wantActivationKey",
-						message: `Configure ${highlighter.info("activation key")}?`,
+						message: `Configure ${highlighter.info("shortcut")}?`,
 						initial: false
 					});
 					if (wantActivationKey === void 0) {
@@ -1855,7 +1858,7 @@ const init = new Command().name("init").alias("setup").description("initialize R
 						const { key } = await prompts({
 							type: "text",
 							name: "key",
-							message: "Enter the activation key (e.g., g, k, space):",
+							message: "Enter the shortcut (e.g., g, k, space):",
 							initial: ""
 						});
 						if (key === void 0) {
@@ -1863,7 +1866,7 @@ const init = new Command().name("init").alias("setup").description("initialize R
 							process.exit(1);
 						}
 						collectedOptions.activationKey = key ? key.toLowerCase() : void 0;
-						logger.log(`  Activation key: ${highlighter.info(formatActivationKeyDisplay(collectedOptions.activationKey))}`);
+						logger.log(`  Shortcut: ${highlighter.info(formatActivationKeyDisplay(collectedOptions.activationKey))}`);
 					}
 				}
 				const { activationMode } = await prompts({
@@ -2030,7 +2033,7 @@ const init = new Command().name("init").alias("setup").description("initialize R
 				cwd
 			});
 		}
-		const result = previewTransform(projectInfo.projectRoot, finalFramework, finalNextRouterType, false, opts.force);
+		const result = previewTransform(projectInfo.projectRoot, finalFramework, finalNextRouterType, projectInfo.isReactGrabConfigured);
 		if (!result.success) {
 			logger.break();
 			logger.error(result.message);
@@ -2065,7 +2068,8 @@ const init = new Command().name("init").alias("setup").description("initialize R
 		if (!opts.skipInstall && shouldInstallReactGrab) await installPackagesWithFeedback(getPackagesToInstall(shouldInstallReactGrab), finalPackageManager, projectInfo.projectRoot);
 		if (hasLayoutChanges) applyTransformWithFeedback(result);
 		logger.break();
-		logger.log(`${highlighter.success("Success!")} React Grab has been installed.`);
+		if (hasLayoutChanges) logger.log(`${highlighter.success("Success!")} React Grab has been installed.`);
+		else logger.log(`${highlighter.success("Success!")} ${result.message}.`);
 		logger.log("You may now start your development server.");
 		logger.break();
 		reportToCli("completed", {
@@ -2678,7 +2682,7 @@ const pull = new Command().name("pull").description("start the watcher if needed
 });
 //#endregion
 //#region src/commands/remove.ts
-const VERSION$2 = "0.1.43";
+const VERSION$2 = "0.1.44-dev.099016d";
 const remove = new Command().name("remove").description("uninstall the React Grab skill from your agent").option("-c, --cwd <cwd>", "working directory (defaults to current directory)", process.cwd()).option("-g, --global", "remove the globally-installed skill instead of the project's", false).action(async (opts) => {
 	console.log(`${pc.magenta("✿")} ${pc.bold("React Grab")} ${pc.gray(VERSION$2)}`);
 	console.log();
@@ -2706,7 +2710,7 @@ const stop = new Command().name("stop").description("stop the React Grab watcher
 });
 //#endregion
 //#region src/commands/upgrade.ts
-const VERSION$1 = "0.1.43";
+const VERSION$1 = "0.1.44-dev.099016d";
 const NPM_REGISTRY_URL = "https://registry.npmjs.org/react-grab/latest";
 const fetchLatestVersion = async () => {
 	try {
@@ -2818,7 +2822,7 @@ const watch = new Command().name("watch").description("run the React Grab captur
 });
 //#endregion
 //#region src/cli.ts
-const VERSION = "0.1.43";
+const VERSION = "0.1.44-dev.099016d";
 const VERSION_API_URL = "https://www.react-grab.com/api/version";
 process.on("SIGINT", () => process.exit(0));
 process.on("SIGTERM", () => process.exit(0));