react-doctor 0.0.34 → 0.0.36

package/dist/cli.js

@@ -1,19 +1,281 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import fs, { existsSync, mkdirSync, mkdtempSync, readdirSync, writeFileSync } from "node:fs";
+import fs, { accessSync, constants, cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import os, { tmpdir } from "node:os";
 import path, { join } from "node:path";
 import { Command } from "commander";
+import { fileURLToPath } from "node:url";
+import pc from "picocolors";
+import basePrompts from "prompts";
+import ora from "ora";
 import { randomUUID } from "node:crypto";
 import { performance } from "node:perf_hooks";
 import { execSync, spawn, spawnSync } from "node:child_process";
-import pc from "picocolors";
-import basePrompts from "prompts";
 import { main } from "knip";
 import { createOptions } from "knip/session";
-import { fileURLToPath } from "node:url";
-import ora from "ora";
 
+//#region src/utils/detect-agents.ts
+const SUPPORTED_AGENTS = {
+	claude: {
+		binaries: ["claude"],
+		displayName: "Claude Code",
+		skillDir: ".claude/skills"
+	},
+	codex: {
+		binaries: ["codex"],
+		displayName: "Codex",
+		skillDir: ".codex/skills"
+	},
+	copilot: {
+		binaries: ["copilot"],
+		displayName: "GitHub Copilot",
+		skillDir: ".github/copilot/skills"
+	},
+	gemini: {
+		binaries: ["gemini"],
+		displayName: "Gemini CLI",
+		skillDir: ".gemini/skills"
+	},
+	cursor: {
+		binaries: ["cursor", "agent"],
+		displayName: "Cursor",
+		skillDir: ".cursor/skills"
+	},
+	opencode: {
+		binaries: ["opencode"],
+		displayName: "OpenCode",
+		skillDir: ".opencode/skills"
+	},
+	droid: {
+		binaries: ["droid"],
+		displayName: "Factory Droid",
+		skillDir: ".droid/skills"
+	},
+	pi: {
+		binaries: ["pi", "omegon"],
+		displayName: "Pi",
+		skillDir: ".pi/skills"
+	}
+};
+const ALL_SUPPORTED_AGENTS = Object.keys(SUPPORTED_AGENTS);
+const isCommandAvailable = (command) => {
+	const pathDirectories = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+	for (const directory of pathDirectories) {
+		const binaryPath = path.join(directory, command);
+		try {
+			if (statSync(binaryPath).isFile()) {
+				accessSync(binaryPath, constants.X_OK);
+				return true;
+			}
+		} catch {}
+	}
+	return false;
+};
+const detectAvailableAgents = () => ALL_SUPPORTED_AGENTS.filter((agent) => SUPPORTED_AGENTS[agent].binaries.some(isCommandAvailable));
+const toDisplayName = (agent) => SUPPORTED_AGENTS[agent].displayName;
+const toSkillDir = (agent) => SUPPORTED_AGENTS[agent].skillDir;
+
+//#endregion
+//#region src/utils/highlighter.ts
+const highlighter = {
+	error: pc.red,
+	warn: pc.yellow,
+	info: pc.cyan,
+	success: pc.green,
+	dim: pc.dim
+};
+
+//#endregion
+//#region src/utils/install-skill-for-agent.ts
+const installSkillForAgent = (projectRoot, agent, skillSourceDirectory, skillName) => {
+	const installedSkillDirectory = path.join(projectRoot, toSkillDir(agent), skillName);
+	rmSync(installedSkillDirectory, {
+		recursive: true,
+		force: true
+	});
+	mkdirSync(path.dirname(installedSkillDirectory), { recursive: true });
+	cpSync(skillSourceDirectory, installedSkillDirectory, { recursive: true });
+	return installedSkillDirectory;
+};
+
+//#endregion
+//#region src/utils/logger.ts
+const logger = {
+	error(...args) {
+		console.log(highlighter.error(args.join(" ")));
+	},
+	warn(...args) {
+		console.log(highlighter.warn(args.join(" ")));
+	},
+	info(...args) {
+		console.log(highlighter.info(args.join(" ")));
+	},
+	success(...args) {
+		console.log(highlighter.success(args.join(" ")));
+	},
+	dim(...args) {
+		console.log(highlighter.dim(args.join(" ")));
+	},
+	log(...args) {
+		console.log(args.join(" "));
+	},
+	break() {
+		console.log("");
+	}
+};
+
+//#endregion
+//#region src/utils/should-auto-select-current-choice.ts
+const shouldAutoSelectCurrentChoice = (choiceStates, cursor) => {
+	if (choiceStates.some((choiceState) => choiceState.selected)) return false;
+	const currentChoice = choiceStates[cursor];
+	return Boolean(currentChoice) && !currentChoice.disabled;
+};
+
+//#endregion
+//#region src/utils/should-select-all-choices.ts
+const shouldSelectAllChoices = (choiceStates) => {
+	return choiceStates.filter((choiceState) => !choiceState.disabled).some((choiceState) => choiceState.selected !== true);
+};
+
+//#endregion
+//#region src/utils/prompts.ts
+const require = createRequire(import.meta.url);
+const PROMPTS_MULTISELECT_MODULE_PATH = "prompts/lib/elements/multiselect";
+const PROMPTS_SELECT_MODULE_PATH = "prompts/lib/elements/select";
+let didPatchMultiselectToggleAll = false;
+let didPatchMultiselectSubmit = false;
+let didPatchSelectBanner = false;
+const selectBannerMap = /* @__PURE__ */ new Map();
+const onCancel = () => {
+	logger.break();
+	logger.log("Cancelled.");
+	logger.dim("Run `npx react-doctor@latest --fix` to fix issues.");
+	logger.break();
+	process.exit(0);
+};
+const patchMultiselectToggleAll = () => {
+	if (didPatchMultiselectToggleAll) return;
+	didPatchMultiselectToggleAll = true;
+	const multiselectPromptConstructor = require(PROMPTS_MULTISELECT_MODULE_PATH);
+	multiselectPromptConstructor.prototype.toggleAll = function() {
+		const isCurrentChoiceDisabled = Boolean(this.value[this.cursor]?.disabled);
+		if (this.maxChoices !== void 0 || isCurrentChoiceDisabled) {
+			this.bell();
+			return;
+		}
+		const shouldSelectAllEnabledChoices = shouldSelectAllChoices(this.value);
+		for (const choiceState of this.value) {
+			if (choiceState.disabled) continue;
+			choiceState.selected = shouldSelectAllEnabledChoices;
+		}
+		this.render();
+	};
+};
+const patchMultiselectSubmit = () => {
+	if (didPatchMultiselectSubmit) return;
+	didPatchMultiselectSubmit = true;
+	const multiselectPromptConstructor = require(PROMPTS_MULTISELECT_MODULE_PATH);
+	const originalSubmit = multiselectPromptConstructor.prototype.submit;
+	multiselectPromptConstructor.prototype.submit = function() {
+		if (shouldAutoSelectCurrentChoice(this.value, this.cursor)) this.value[this.cursor].selected = true;
+		originalSubmit.call(this);
+	};
+};
+const patchSelectBanner = () => {
+	if (didPatchSelectBanner) return;
+	didPatchSelectBanner = true;
+	const selectConstructor = require(PROMPTS_SELECT_MODULE_PATH);
+	const promptsClear = require("prompts/lib/util/clear");
+	const originalRender = selectConstructor.prototype.render;
+	selectConstructor.prototype.render = function() {
+		originalRender.call(this);
+		const banner = selectBannerMap.get(this.cursor);
+		if (!banner || this.closed || this.done) return;
+		this.out.write(promptsClear(this.outputText, this.out.columns));
+		this.outputText = `${banner}\n\n${this.outputText}`;
+		this.out.write(this.outputText);
+	};
+};
+const prompts = (questions) => {
+	patchMultiselectToggleAll();
+	patchMultiselectSubmit();
+	patchSelectBanner();
+	return basePrompts(questions, { onCancel });
+};
+
+//#endregion
+//#region src/utils/spinner.ts
+let sharedInstance = null;
+let activeCount = 0;
+const pendingTexts = /* @__PURE__ */ new Set();
+const finalize = (method, originalText, displayText) => {
+	pendingTexts.delete(originalText);
+	activeCount--;
+	if (activeCount <= 0 || !sharedInstance) {
+		sharedInstance?.[method](displayText);
+		sharedInstance = null;
+		activeCount = 0;
+		return;
+	}
+	sharedInstance.stop();
+	ora(displayText).start()[method](displayText);
+	const [remainingText] = pendingTexts;
+	if (remainingText) sharedInstance.text = remainingText;
+	sharedInstance.start();
+};
+const spinner = (text) => ({ start() {
+	activeCount++;
+	pendingTexts.add(text);
+	if (!sharedInstance) sharedInstance = ora({ text }).start();
+	else sharedInstance.text = text;
+	return {
+		succeed: (displayText) => finalize("succeed", text, displayText),
+		fail: (displayText) => finalize("fail", text, displayText)
+	};
+} });
+
+//#endregion
+//#region src/install-skill.ts
+const SKILL_NAME = "react-doctor";
+const getSkillSourceDirectory = () => {
+	const distDirectory = path.dirname(fileURLToPath(import.meta.url));
+	return path.join(distDirectory, "skills", SKILL_NAME);
+};
+const runInstallSkill = async (options = {}) => {
+	const projectRoot = process.cwd();
+	const sourceDir = getSkillSourceDirectory();
+	if (!existsSync(path.join(sourceDir, "SKILL.md"))) {
+		logger.error(`Could not locate the ${SKILL_NAME} skill bundled with this package.`);
+		process.exitCode = 1;
+		return;
+	}
+	const detectedAgents = detectAvailableAgents();
+	if (detectedAgents.length === 0) {
+		logger.error("No supported coding agents detected on your PATH.");
+		logger.dim("  Supported: Claude Code, Codex, GitHub Copilot, Gemini CLI, Cursor, OpenCode, Factory Droid, Pi.");
+		process.exitCode = 1;
+		return;
+	}
+	const selectedAgents = Boolean(options.yes) || !process.stdin.isTTY ? detectedAgents : (await prompts({
+		type: "multiselect",
+		name: "agents",
+		message: `Install the ${highlighter.info(SKILL_NAME)} skill for:`,
+		choices: detectedAgents.map((agent) => ({
+			title: toDisplayName(agent),
+			value: agent,
+			selected: true
+		})),
+		instructions: false,
+		min: 1
+	})).agents ?? [];
+	if (selectedAgents.length === 0) return;
+	const installSpinner = spinner(`Installing ${SKILL_NAME} skill...`).start();
+	for (const agent of selectedAgents) installSkillForAgent(projectRoot, agent, sourceDir, SKILL_NAME);
+	installSpinner.succeed(`${SKILL_NAME} skill installed for ${selectedAgents.map(toDisplayName).join(", ")}.`);
+};
+
+//#endregion
 //#region src/constants.ts
 const SOURCE_FILE_PATTERN = /\.(tsx?|jsx?)$/;
 const JSX_FILE_PATTERN = /\.(tsx|jsx)$/;
@@ -140,16 +402,6 @@ const calculateScore = async (diagnostics) => {
 	}
 };
 
-//#endregion
-//#region src/utils/highlighter.ts
-const highlighter = {
-	error: pc.red,
-	warn: pc.yellow,
-	info: pc.cyan,
-	success: pc.green,
-	dim: pc.dim
-};
-
 //#endregion
 //#region src/utils/colorize-by-score.ts
 const colorizeByScore = (text, score) => {
@@ -414,9 +666,11 @@ const EXPO_APP_CONFIG_FILENAMES = [
 	"app.config.js",
 	"app.config.ts"
 ];
-const REACT_COMPILER_CONFIG_PATTERN = /react-compiler|reactCompiler/;
+const REACT_COMPILER_PACKAGE_REFERENCE_PATTERN = /babel-plugin-react-compiler|react-compiler-runtime|eslint-plugin-react-compiler|["']react-compiler["']/;
+const REACT_COMPILER_ENABLED_FLAG_PATTERN = /["']?reactCompiler["']?\s*:\s*true\b/;
 const FRAMEWORK_PACKAGES = {
 	next: "nextjs",
+	"@tanstack/react-start": "tanstack-start",
 	vite: "vite",
 	"react-scripts": "cra",
 	"@remix-run/react": "remix",
@@ -426,6 +680,7 @@ const FRAMEWORK_PACKAGES = {
 };
 const FRAMEWORK_DISPLAY_NAMES = {
 	nextjs: "Next.js",
+	"tanstack-start": "TanStack Start",
 	vite: "Vite",
 	cra: "Create React App",
 	remix: "Remix",
@@ -740,12 +995,12 @@ const hasCompilerPackage = (packageJson) => {
 	const allDependencies = collectAllDependencies(packageJson);
 	return Object.keys(allDependencies).some((packageName) => REACT_COMPILER_PACKAGES.has(packageName));
 };
-const fileContainsPattern = (filePath, pattern) => {
+const hasCompilerInConfigFile = (filePath) => {
 	if (!isFile(filePath)) return false;
 	const content = fs.readFileSync(filePath, "utf-8");
-	return pattern.test(content);
+	return REACT_COMPILER_ENABLED_FLAG_PATTERN.test(content) || REACT_COMPILER_PACKAGE_REFERENCE_PATTERN.test(content);
 };
-const hasCompilerInConfigFiles = (directory, filenames) => filenames.some((filename) => fileContainsPattern(path.join(directory, filename), REACT_COMPILER_CONFIG_PATTERN));
+const hasCompilerInConfigFiles = (directory, filenames) => filenames.some((filename) => hasCompilerInConfigFile(path.join(directory, filename)));
 const detectReactCompiler = (directory, packageJson) => {
 	if (hasCompilerPackage(packageJson)) return true;
 	if (hasCompilerInConfigFiles(directory, NEXT_CONFIG_FILENAMES)) return true;
@@ -800,32 +1055,6 @@ const discoverProject = (directory) => {
 	};
 };
 
-//#endregion
-//#region src/utils/logger.ts
-const logger = {
-	error(...args) {
-		console.log(highlighter.error(args.join(" ")));
-	},
-	warn(...args) {
-		console.log(highlighter.warn(args.join(" ")));
-	},
-	info(...args) {
-		console.log(highlighter.info(args.join(" ")));
-	},
-	success(...args) {
-		console.log(highlighter.success(args.join(" ")));
-	},
-	dim(...args) {
-		console.log(highlighter.dim(args.join(" ")));
-	},
-	log(...args) {
-		console.log(args.join(" "));
-	},
-	break() {
-		console.log("");
-	}
-};
-
 //#endregion
 //#region src/utils/framed-box.ts
 const createFramedLine = (plainText, renderedText = plainText) => ({
@@ -906,86 +1135,6 @@ const loadConfig = (rootDirectory) => {
 	return null;
 };
 
-//#endregion
-//#region src/utils/should-auto-select-current-choice.ts
-const shouldAutoSelectCurrentChoice = (choiceStates, cursor) => {
-	if (choiceStates.some((choiceState) => choiceState.selected)) return false;
-	const currentChoice = choiceStates[cursor];
-	return Boolean(currentChoice) && !currentChoice.disabled;
-};
-
-//#endregion
-//#region src/utils/should-select-all-choices.ts
-const shouldSelectAllChoices = (choiceStates) => {
-	return choiceStates.filter((choiceState) => !choiceState.disabled).some((choiceState) => choiceState.selected !== true);
-};
-
-//#endregion
-//#region src/utils/prompts.ts
-const require = createRequire(import.meta.url);
-const PROMPTS_MULTISELECT_MODULE_PATH = "prompts/lib/elements/multiselect";
-const PROMPTS_SELECT_MODULE_PATH = "prompts/lib/elements/select";
-let didPatchMultiselectToggleAll = false;
-let didPatchMultiselectSubmit = false;
-let didPatchSelectBanner = false;
-const selectBannerMap = /* @__PURE__ */ new Map();
-const onCancel = () => {
-	logger.break();
-	logger.log("Cancelled.");
-	logger.dim("Run `npx react-doctor@latest --fix` to fix issues.");
-	logger.break();
-	process.exit(0);
-};
-const patchMultiselectToggleAll = () => {
-	if (didPatchMultiselectToggleAll) return;
-	didPatchMultiselectToggleAll = true;
-	const multiselectPromptConstructor = require(PROMPTS_MULTISELECT_MODULE_PATH);
-	multiselectPromptConstructor.prototype.toggleAll = function() {
-		const isCurrentChoiceDisabled = Boolean(this.value[this.cursor]?.disabled);
-		if (this.maxChoices !== void 0 || isCurrentChoiceDisabled) {
-			this.bell();
-			return;
-		}
-		const shouldSelectAllEnabledChoices = shouldSelectAllChoices(this.value);
-		for (const choiceState of this.value) {
-			if (choiceState.disabled) continue;
-			choiceState.selected = shouldSelectAllEnabledChoices;
-		}
-		this.render();
-	};
-};
-const patchMultiselectSubmit = () => {
-	if (didPatchMultiselectSubmit) return;
-	didPatchMultiselectSubmit = true;
-	const multiselectPromptConstructor = require(PROMPTS_MULTISELECT_MODULE_PATH);
-	const originalSubmit = multiselectPromptConstructor.prototype.submit;
-	multiselectPromptConstructor.prototype.submit = function() {
-		if (shouldAutoSelectCurrentChoice(this.value, this.cursor)) this.value[this.cursor].selected = true;
-		originalSubmit.call(this);
-	};
-};
-const patchSelectBanner = () => {
-	if (didPatchSelectBanner) return;
-	didPatchSelectBanner = true;
-	const selectConstructor = require(PROMPTS_SELECT_MODULE_PATH);
-	const promptsClear = require("prompts/lib/util/clear");
-	const originalRender = selectConstructor.prototype.render;
-	selectConstructor.prototype.render = function() {
-		originalRender.call(this);
-		const banner = selectBannerMap.get(this.cursor);
-		if (!banner || this.closed || this.done) return;
-		this.out.write(promptsClear(this.outputText, this.out.columns));
-		this.outputText = `${banner}\n\n${this.outputText}`;
-		this.out.write(this.outputText);
-	};
-};
-const prompts = (questions) => {
-	patchMultiselectToggleAll();
-	patchMultiselectSubmit();
-	patchSelectBanner();
-	return basePrompts(questions, { onCancel });
-};
-
 //#endregion
 //#region src/utils/resolve-compatible-node.ts
 const parseNodeVersion = (versionString) => {
@@ -1252,6 +1401,22 @@ const REACT_NATIVE_RULES = {
 	"react-doctor/rn-prefer-reanimated": "warn",
 	"react-doctor/rn-no-single-element-style-array": "warn"
 };
+const TANSTACK_START_RULES = {
+	"react-doctor/tanstack-start-route-property-order": "error",
+	"react-doctor/tanstack-start-no-direct-fetch-in-loader": "warn",
+	"react-doctor/tanstack-start-server-fn-validate-input": "warn",
+	"react-doctor/tanstack-start-no-useeffect-fetch": "warn",
+	"react-doctor/tanstack-start-missing-head-content": "warn",
+	"react-doctor/tanstack-start-no-anchor-element": "warn",
+	"react-doctor/tanstack-start-server-fn-method-order": "error",
+	"react-doctor/tanstack-start-no-navigate-in-render": "warn",
+	"react-doctor/tanstack-start-no-dynamic-server-fn-import": "error",
+	"react-doctor/tanstack-start-no-use-server-in-handler": "error",
+	"react-doctor/tanstack-start-no-secrets-in-loader": "error",
+	"react-doctor/tanstack-start-get-mutation": "warn",
+	"react-doctor/tanstack-start-redirect-in-try-catch": "warn",
+	"react-doctor/tanstack-start-loader-parallel-fetch": "warn"
+};
 const REACT_COMPILER_RULES = {
 	"react-hooks-js/set-state-in-render": "error",
 	"react-hooks-js/immutability": "error",
@@ -1341,12 +1506,14 @@ const createOxlintConfig = ({ pluginPath, framework, hasReactCompiler, customRul
 		"react-doctor/rendering-animate-svg-wrapper": "warn",
 		"react-doctor/no-inline-prop-on-memo-component": "warn",
 		"react-doctor/rendering-hydration-no-flicker": "warn",
+		"react-doctor/rendering-script-defer-async": "warn",
 		"react-doctor/no-transition-all": "warn",
 		"react-doctor/no-global-css-variable-animation": "error",
 		"react-doctor/no-large-animated-blur": "warn",
 		"react-doctor/no-scale-from-zero": "warn",
 		"react-doctor/no-permanent-will-change": "warn",
 		"react-doctor/no-secrets-in-client-code": "error",
+		"react-doctor/js-flatmap-filter": "warn",
 		"react-doctor/no-barrel-import": "warn",
 		"react-doctor/no-full-lodash-import": "warn",
 		"react-doctor/no-moment": "warn",
@@ -1359,9 +1526,31 @@ const createOxlintConfig = ({ pluginPath, framework, hasReactCompiler, customRul
 		"react-doctor/server-auth-actions": "error",
 		"react-doctor/server-after-nonblocking": "warn",
 		"react-doctor/client-passive-event-listeners": "warn",
+		"react-doctor/query-stable-query-client": "error",
+		"react-doctor/query-no-rest-destructuring": "warn",
+		"react-doctor/query-no-void-query-fn": "warn",
+		"react-doctor/query-no-query-in-effect": "warn",
+		"react-doctor/query-mutation-missing-invalidation": "warn",
+		"react-doctor/query-no-usequery-for-mutation": "warn",
+		"react-doctor/no-inline-bounce-easing": "warn",
+		"react-doctor/no-z-index-9999": "warn",
+		"react-doctor/no-inline-exhaustive-style": "warn",
+		"react-doctor/no-side-tab-border": "warn",
+		"react-doctor/no-pure-black-background": "warn",
+		"react-doctor/no-gradient-text": "warn",
+		"react-doctor/no-dark-mode-glow": "warn",
+		"react-doctor/no-justified-text": "warn",
+		"react-doctor/no-tiny-text": "warn",
+		"react-doctor/no-wide-letter-spacing": "warn",
+		"react-doctor/no-gray-on-colored-background": "warn",
+		"react-doctor/no-layout-transition-inline": "warn",
+		"react-doctor/no-disabled-zoom": "error",
+		"react-doctor/no-outline-none": "warn",
+		"react-doctor/no-long-transition-duration": "warn",
 		"react-doctor/async-parallel": "warn",
 		...framework === "nextjs" ? NEXTJS_RULES : {},
-		...framework === "expo" || framework === "react-native" ? REACT_NATIVE_RULES : {}
+		...framework === "expo" || framework === "react-native" ? REACT_NATIVE_RULES : {},
+		...framework === "tanstack-start" ? TANSTACK_START_RULES : {}
 	}
 });
 
@@ -1438,6 +1627,7 @@ const RULE_CATEGORY_MAP = {
 	"react-doctor/rendering-animate-svg-wrapper": "Performance",
 	"react-doctor/rendering-usetransition-loading": "Performance",
 	"react-doctor/rendering-hydration-no-flicker": "Performance",
+	"react-doctor/rendering-script-defer-async": "Performance",
 	"react-doctor/no-transition-all": "Performance",
 	"react-doctor/no-global-css-variable-animation": "Performance",
 	"react-doctor/no-large-animated-blur": "Performance",
@@ -1472,6 +1662,28 @@ const RULE_CATEGORY_MAP = {
 	"react-doctor/server-auth-actions": "Server",
 	"react-doctor/server-after-nonblocking": "Server",
 	"react-doctor/client-passive-event-listeners": "Performance",
+	"react-doctor/query-stable-query-client": "TanStack Query",
+	"react-doctor/query-no-rest-destructuring": "TanStack Query",
+	"react-doctor/query-no-void-query-fn": "TanStack Query",
+	"react-doctor/query-no-query-in-effect": "TanStack Query",
+	"react-doctor/query-mutation-missing-invalidation": "TanStack Query",
+	"react-doctor/query-no-usequery-for-mutation": "TanStack Query",
+	"react-doctor/no-inline-bounce-easing": "Performance",
+	"react-doctor/no-z-index-9999": "Architecture",
+	"react-doctor/no-inline-exhaustive-style": "Architecture",
+	"react-doctor/no-side-tab-border": "Architecture",
+	"react-doctor/no-pure-black-background": "Architecture",
+	"react-doctor/no-gradient-text": "Architecture",
+	"react-doctor/no-dark-mode-glow": "Architecture",
+	"react-doctor/no-justified-text": "Accessibility",
+	"react-doctor/no-tiny-text": "Accessibility",
+	"react-doctor/no-wide-letter-spacing": "Architecture",
+	"react-doctor/no-gray-on-colored-background": "Accessibility",
+	"react-doctor/no-layout-transition-inline": "Performance",
+	"react-doctor/no-disabled-zoom": "Accessibility",
+	"react-doctor/no-outline-none": "Accessibility",
+	"react-doctor/no-long-transition-duration": "Performance",
+	"react-doctor/js-flatmap-filter": "Performance",
 	"react-doctor/async-parallel": "Performance",
 	"react-doctor/rn-no-raw-text": "React Native",
 	"react-doctor/rn-no-deprecated-modules": "React Native",
@@ -1480,7 +1692,21 @@ const RULE_CATEGORY_MAP = {
 	"react-doctor/rn-no-inline-flatlist-renderitem": "React Native",
 	"react-doctor/rn-no-legacy-shadow-styles": "React Native",
 	"react-doctor/rn-prefer-reanimated": "React Native",
-	"react-doctor/rn-no-single-element-style-array": "React Native"
+	"react-doctor/rn-no-single-element-style-array": "React Native",
+	"react-doctor/tanstack-start-route-property-order": "TanStack Start",
+	"react-doctor/tanstack-start-no-direct-fetch-in-loader": "TanStack Start",
+	"react-doctor/tanstack-start-server-fn-validate-input": "TanStack Start",
+	"react-doctor/tanstack-start-no-useeffect-fetch": "TanStack Start",
+	"react-doctor/tanstack-start-missing-head-content": "TanStack Start",
+	"react-doctor/tanstack-start-no-anchor-element": "TanStack Start",
+	"react-doctor/tanstack-start-server-fn-method-order": "TanStack Start",
+	"react-doctor/tanstack-start-no-navigate-in-render": "TanStack Start",
+	"react-doctor/tanstack-start-no-dynamic-server-fn-import": "TanStack Start",
+	"react-doctor/tanstack-start-no-use-server-in-handler": "TanStack Start",
+	"react-doctor/tanstack-start-no-secrets-in-loader": "Security",
+	"react-doctor/tanstack-start-get-mutation": "Security",
+	"react-doctor/tanstack-start-redirect-in-try-catch": "TanStack Start",
+	"react-doctor/tanstack-start-loader-parallel-fetch": "Performance"
 };
 const RULE_HELP_MAP = {
 	"no-derived-state-effect": "For derived state, compute inline: `const x = fn(dep)`. For state resets on prop change, use a key prop: `<Component key={prop} />`. See https://react.dev/learn/you-might-not-need-an-effect",
@@ -1502,6 +1728,7 @@ const RULE_HELP_MAP = {
 	"rendering-animate-svg-wrapper": "Wrap the SVG: `<motion.div animate={...}><svg>...</svg></motion.div>`",
 	"rendering-usetransition-loading": "Replace with `const [isPending, startTransition] = useTransition()` — avoids a re-render for the loading state",
 	"rendering-hydration-no-flicker": "Use `useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)` or add `suppressHydrationWarning` to the element",
+	"rendering-script-defer-async": "Add `defer` for DOM-dependent scripts or `async` for independent ones (analytics). In Next.js, use `<Script strategy=\"afterInteractive\" />` instead",
 	"no-transition-all": "List specific properties: `transition: \"opacity 200ms, transform 200ms\"` — or in Tailwind use `transition-colors`, `transition-opacity`, or `transition-transform`",
 	"no-global-css-variable-animation": "Set the variable on the nearest element instead of a parent, or use `@property` with `inherits: false` to prevent cascade. Better yet, use targeted `element.style.transform` updates",
 	"no-large-animated-blur": "Keep blur radius under 10px, or apply blur to a smaller element. Large blurs multiply GPU memory usage with layer size",
@@ -1514,6 +1741,21 @@ const RULE_HELP_MAP = {
 	"prefer-dynamic-import": "Use `const Component = dynamic(() => import('library'), { ssr: false })` from next/dynamic or React.lazy()",
 	"use-lazy-motion": "Use `import { LazyMotion, m } from \"framer-motion\"` with `domAnimation` features — saves ~30kb",
 	"no-undeferred-third-party": "Use `next/script` with `strategy=\"lazyOnload\"` or add the `defer` attribute",
+	"no-inline-bounce-easing": "Use `cubic-bezier(0.16, 1, 0.3, 1)` (ease-out-expo) for natural deceleration — objects in the real world don't bounce",
+	"no-z-index-9999": "Define a z-index scale in your design tokens (e.g. dropdown: 10, modal: 20, toast: 30). Create a new stacking context with `isolation: isolate` instead of escalating values",
+	"no-inline-exhaustive-style": "Move styles to a CSS class, CSS module, Tailwind utilities, or a styled component — inline objects with many properties hurt readability and create new references every render",
+	"no-side-tab-border": "Use a subtler accent (box-shadow inset, background gradient, or border-bottom) instead of a thick one-sided border",
+	"no-pure-black-background": "Tint the background slightly toward your brand hue — e.g. `#0a0a0f` or Tailwind's `bg-gray-950`. Pure black looks harsh on modern displays",
+	"no-gradient-text": "Use solid text colors for readability. If you need emphasis, use font weight, size, or a distinct color instead of gradients",
+	"no-dark-mode-glow": "Use a subtle `box-shadow` with neutral colors for depth, or `border` with low opacity. Colored glows on dark backgrounds are the default AI-generated aesthetic",
+	"no-justified-text": "Use `text-align: left` for body text, or add `hyphens: auto` and `overflow-wrap: break-word` if you must justify",
+	"no-tiny-text": "Use at least 12px for body content, 16px is ideal. Small text is hard to read, especially on high-DPI mobile screens",
+	"no-wide-letter-spacing": "Reserve wide tracking (letter-spacing > 0.05em) for short uppercase labels, navigation items, and buttons — not body text",
+	"no-gray-on-colored-background": "Use a darker shade of the background color for text, or white/near-white for contrast. Gray text on colored backgrounds looks washed out",
+	"no-layout-transition-inline": "Use `transform` and `opacity` for transitions — they run on the compositor thread. For height animations, use `grid-template-rows: 0fr → 1fr`",
+	"no-disabled-zoom": "Remove `user-scalable=no` and `maximum-scale` from the viewport meta tag. If your layout breaks at 200% zoom, fix the layout — don't punish users with disabilities",
+	"no-outline-none": "Use `:focus-visible { outline: 2px solid var(--color-accent); outline-offset: 2px }` to show focus only for keyboard users while hiding it for mouse clicks",
+	"no-long-transition-duration": "Keep UI transitions under 1s — 100-150ms for instant feedback, 200-300ms for state changes, 300-500ms for layout changes. Use longer durations only for page-load hero animations",
 	"no-array-index-as-key": "Use a stable unique identifier: `key={item.id}` or `key={item.slug}` — index keys break on reorder/filter",
 	"rendering-conditional-render": "Change to `{items.length > 0 && <List />}` or use a ternary: `{items.length ? <List /> : null}`",
 	"no-prevent-default": "Use `<form action={serverAction}>` (works without JS) or `<button>` instead of `<a>` with preventDefault",
@@ -1523,7 +1765,7 @@ const RULE_HELP_MAP = {
 	"nextjs-no-use-search-params-without-suspense": "Wrap the component using useSearchParams: `<Suspense fallback={<Skeleton />}><SearchComponent /></Suspense>`",
 	"nextjs-no-client-fetch-for-server-data": "Remove 'use client' and fetch directly in the Server Component — no API round-trip, secrets stay on server",
 	"nextjs-missing-metadata": "Add `export const metadata = { title: '...', description: '...' }` or `export async function generateMetadata()`",
-	"nextjs-no-client-side-redirect": "Use `redirect('/path')` from 'next/navigation' directly (works in both server and client components), or handle in middleware",
+	"nextjs-no-client-side-redirect": "Avoid redirects inside useEffect. Use an event handler, middleware, or server-side redirect (App Router: redirect() from next/navigation; Pages Router: getServerSideProps redirect)",
 	"nextjs-no-redirect-in-try-catch": "Move the redirect/notFound call outside the try block, or add `unstable_rethrow(error)` in the catch",
 	"nextjs-image-missing-sizes": "Add sizes for responsive behavior: `sizes=\"(max-width: 768px) 100vw, 50vw\"` matching your layout breakpoints",
 	"nextjs-no-native-script": "`import Script from \"next/script\"` — use `strategy=\"afterInteractive\"` for analytics or `\"lazyOnload\"` for widgets",
@@ -1536,6 +1778,13 @@ const RULE_HELP_MAP = {
 	"server-auth-actions": "Add `const session = await auth()` at the top and throw/redirect if unauthorized before any data access",
 	"server-after-nonblocking": "`import { after } from 'next/server'` then wrap: `after(() => analytics.track(...))` — response isn't blocked",
 	"client-passive-event-listeners": "Add `{ passive: true }` as the third argument: `addEventListener('scroll', handler, { passive: true })`",
+	"query-stable-query-client": "Move `new QueryClient()` to module scope or wrap in `useState(() => new QueryClient())` — recreating it on every render resets the entire cache",
+	"query-no-rest-destructuring": "Destructure only the fields you need: `const { data, isLoading } = useQuery(...)` — rest destructuring subscribes to all fields and causes extra re-renders",
+	"query-no-void-query-fn": "queryFn must return a value for the cache. Use the `enabled` option to conditionally disable the query instead of returning undefined",
+	"query-no-query-in-effect": "React Query manages refetching automatically via queryKey dependencies and the `enabled` option — manual refetch() in useEffect is usually unnecessary",
+	"query-mutation-missing-invalidation": "Add `onSuccess: () => queryClient.invalidateQueries({ queryKey: ['...'] })` so cached data stays in sync after the mutation",
+	"query-no-usequery-for-mutation": "Use `useMutation()` for POST/PUT/DELETE — it provides onSuccess/onError callbacks, doesn't auto-refetch, and correctly models write operations",
+	"js-flatmap-filter": "Use `.flatMap(item => condition ? [value] : [])` — transforms and filters in a single pass instead of creating an intermediate array",
 	"async-parallel": "Use `const [a, b] = await Promise.all([fetchA(), fetchB()])` to run independent operations concurrently",
 	"rn-no-raw-text": "Wrap text in a `<Text>` component: `<Text>{value}</Text>` — raw strings outside `<Text>` crash on React Native",
 	"rn-no-deprecated-modules": "Import from the community package instead — deprecated modules were removed from the react-native core",
@@ -1544,7 +1793,21 @@ const RULE_HELP_MAP = {
 	"rn-no-inline-flatlist-renderitem": "Extract renderItem to a named function or wrap in useCallback to avoid re-creating on every render",
 	"rn-no-legacy-shadow-styles": "Use `boxShadow` for cross-platform shadows on the new architecture instead of platform-specific shadow properties",
 	"rn-prefer-reanimated": "Use `import Animated from 'react-native-reanimated'` — animations run on the UI thread instead of the JS thread",
-	"rn-no-single-element-style-array": "Use `style={value}` instead of `style={[value]}` — single-element arrays add unnecessary allocation"
+	"rn-no-single-element-style-array": "Use `style={value}` instead of `style={[value]}` — single-element arrays add unnecessary allocation",
+	"tanstack-start-route-property-order": "Follow the order: params/validateSearch → loaderDeps → context → beforeLoad → loader → head. See https://tanstack.com/router/latest/docs/eslint/create-route-property-order",
+	"tanstack-start-no-direct-fetch-in-loader": "Use `createServerFn()` from @tanstack/react-start — provides type-safe RPC, input validation, and proper server/client code splitting",
+	"tanstack-start-server-fn-validate-input": "Add `.inputValidator(schema)` before `.handler()` — data crosses a network boundary and must be validated at runtime",
+	"tanstack-start-no-useeffect-fetch": "Fetch data in the route `loader` instead — the router coordinates loading before rendering to avoid waterfalls",
+	"tanstack-start-missing-head-content": "Add `<HeadContent />` inside `<head>` in your __root route — without it, route `head()` meta tags are silently dropped",
+	"tanstack-start-no-anchor-element": "`import { Link } from '@tanstack/react-router'` — enables type-safe routes, preloading via `preload=\"intent\"`, and client-side navigation",
+	"tanstack-start-server-fn-method-order": "Chain methods in order: .middleware() → .inputValidator() → .client() → .server() → .handler() — types depend on this sequence",
+	"tanstack-start-no-navigate-in-render": "Use `throw redirect({ to: '/path' })` in `beforeLoad` or `loader` instead — navigate() during render causes hydration issues",
+	"tanstack-start-no-dynamic-server-fn-import": "Use `import { myFn } from '~/utils/my.functions'` — the bundler replaces server code with RPC stubs only for static imports",
+	"tanstack-start-no-use-server-in-handler": "TanStack Start handles server boundaries automatically via the Vite plugin — \"use server\" inside createServerFn causes compilation errors",
+	"tanstack-start-no-secrets-in-loader": "Loaders are isomorphic (run on both server and client). Wrap secret access in `createServerFn()` so it stays server-only",
+	"tanstack-start-get-mutation": "Use `createServerFn({ method: 'POST' })` for data modifications — GET requests can be triggered by prefetching and are vulnerable to CSRF",
+	"tanstack-start-redirect-in-try-catch": "TanStack Router's `redirect()` and `notFound()` throw special errors caught by the router. Move them outside the try block or re-throw in the catch",
+	"tanstack-start-loader-parallel-fetch": "Use `const [a, b] = await Promise.all([fetchA(), fetchB()])` to avoid request waterfalls in route loaders"
 };
 const FILEPATH_WITH_LOCATION_PATTERN = /\S+\.\w+:\d+:\d+[\s\S]*$/;
 const REACT_COMPILER_MESSAGE = "React Compiler can't optimize this code";
@@ -1690,37 +1953,6 @@ const runOxlint = async (rootDirectory, hasTypeScript, framework, hasReactCompil
 	}
 };
 
-//#endregion
-//#region src/utils/spinner.ts
-let sharedInstance = null;
-let activeCount = 0;
-const pendingTexts = /* @__PURE__ */ new Set();
-const finalize = (method, originalText, displayText) => {
-	pendingTexts.delete(originalText);
-	activeCount--;
-	if (activeCount <= 0 || !sharedInstance) {
-		sharedInstance?.[method](displayText);
-		sharedInstance = null;
-		activeCount = 0;
-		return;
-	}
-	sharedInstance.stop();
-	ora(displayText).start()[method](displayText);
-	const [remainingText] = pendingTexts;
-	if (remainingText) sharedInstance.text = remainingText;
-	sharedInstance.start();
-};
-const spinner = (text) => ({ start() {
-	activeCount++;
-	pendingTexts.add(text);
-	if (!sharedInstance) sharedInstance = ora({ text }).start();
-	else sharedInstance.text = text;
-	return {
-		succeed: (displayText) => finalize("succeed", text, displayText),
-		fail: (displayText) => finalize("fail", text, displayText)
-	};
-} });
-
 //#endregion
 //#region src/scan.ts
 const SEVERITY_ORDER = {
@@ -2280,7 +2512,7 @@ const promptProjectSelection = async (workspacePackages, rootDirectory) => {
 
 //#endregion
 //#region src/cli.ts
-const VERSION = "0.0.34";
+const VERSION = "0.0.36";
 const VALID_FAIL_ON_LEVELS = new Set([
 	"error",
 	"warning",
@@ -2438,6 +2670,13 @@ const program = new Command().name("react-doctor").description("Diagnose React c
 ${highlighter.dim("Learn more:")}
   ${highlighter.info("https://github.com/millionco/react-doctor")}
 `);
+program.command("install").description("Install the react-doctor skill into your coding agents").option("-y, --yes", "skip prompts, install for all detected agents").action(async (options) => {
+	try {
+		await runInstallSkill({ yes: options.yes });
+	} catch (error) {
+		handleError(error);
+	}
+});
 const main$1 = async () => {
 	await program.parseAsync();
 };