@santi020k/eslint-config-basic 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # @santi020k/eslint-config-basic
 
+## 3.2.0
+
+### Minor Changes
+
+- [#104](https://github.com/santi020k/eslint-config-basic/pull/104) [`522aed9`](https://github.com/santi020k/eslint-config-basic/commit/522aed93495faebff095f6e48dc731b7730e8f7a) Thanks [@santi020k](https://github.com/santi020k)! - Add `explain-preset` adoption reports and optional temporary compatibility
+  overrides grouped by formatting, correctness, security, framework, and domain
+  rules.
+
+  Make generated configs safer for real ESLint 10 monorepos by attaching referenced plugins locally, inheriting shared project detection and Tailwind options, composing untyped TypeScript overrides after framework parsers, and making doctor/install planning aware of workspace projects and modern feature selections.
+
+  Improve the CLI for pnpm workspaces by detecting the workspace root from nested
+  projects, preserving default and named catalogs during installation, and
+  requesting companion config packages with a version range compatible with the
+  installed Basic release. Command parsing is now strict, subcommand help is
+  side-effect free, minimum-release-age blocks are diagnosed, and safe v3 config
+  syntax is modernized during migration. Optional framework and feature-pack load
+  errors distinguish missing packages from evaluation failures while retaining the
+  original cause. Packed modular monorepo and peer-health release checks now verify
+  doctor, ESLint, TypeScript, frozen pnpm installs, and owned exceptions against
+  published-package boundaries.
+
+### Patch Changes
+
+- Updated dependencies [[`a93a940`](https://github.com/santi020k/eslint-config-basic/commit/a93a9406d4e69d53f0e177c65b9aceeeec6ae1ba)]:
+  - @santi020k/eslint-config-typescript@3.1.1
+
+## 3.1.0
+
+### Minor Changes
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Add an opt-in, lazily loaded Astro Doctor ESLint integration through `Extension.AstroDoctor` or `features: { "astro-doctor": true }`, including the recommended proprietary and official Astro rules, configuration validation, and `basic-eslint doctor` compatibility guidance.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Add a `basic-eslint install` command that detects missing framework, feature
+  category, ESLint, and TypeScript dependencies and installs them with the
+  project's package manager. Document the command in the v3 setup flow.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Complete the v3 lean dependency boundary and one-line recommended entry point. Framework and feature-pack packages are now optional, dynamically loaded peers with actionable installation errors. Feature factories move from the basic root export to granular extensions, formats, libraries, testing, and tools packages; `@santi020k/eslint-config-integrations` remains as a compatibility aggregate, while the new `@santi020k/eslint-config-full` package provides the batteries-included installation path. Core no longer owns JSX accessibility rules, the CLI writes the one-line configuration, and release checks enforce dependency budgets, packed-consumer compatibility, and lean production-audit boundaries.
+
+  Remove the v1 compatibility exports (`*Config`, `jsConfig`, `tsConfig`,
+  `astroConfig`, `rules`, `loadModule`, and `eslintConfig`) from the aggregate
+  v3 API. Remove the deprecated Remix package and `frameworks.remix` option;
+  Remix dependencies now resolve through the React Router v7 configuration.
+  The Lite package is now a thin compatibility re-export of Basic.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Complete the v3 modular dependency boundary with five category feature packs.
+  Each pack owns its plugin dependencies and exposes a self-describing feature
+  registry through the shared `ConfigFeature` contract. The lean Basic composer
+  loads only registries for selected categories, Full installs every pack, and
+  Integrations remains as a compatibility aggregate.
+
+  Move agent-skill generation from the Basic root export to
+  `@santi020k/eslint-config-basic/agent`, keeping Node-oriented tooling out of the
+  configuration runtime entry point.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Polish real-world consumer configuration: add one `root` option for detection,
+  TypeScript, Tailwind, projects, and `.gitignore`; auto-detect and scope workspace
+  packages without leaking root framework dependencies; accept native project
+  service options; and syntax-lint TypeScript config files plus explicit
+  `untypedFiles` without consumer-side `typescript-eslint` imports.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Drop Node.js 20 support and require Node.js 22.19.0 or newer across the package
+  suite. This aligns the published engine contract with the current ESLint,
+  Lighthouse, GraphQL, and Unicorn toolchain.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Add v3 lifecycle tooling to the `basic-eslint` CLI: an automated v2-to-v3
+  migration planner and writer, incremental strict-mode baselines backed by ESLint
+  bulk suppressions, rule-performance profiling with concurrency comparison,
+  effective-rule snapshots and diffs, and optional official ESLint MCP
+  scaffolding for generated agent standards.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Add v3 project-assistance workflows: safe doctor repairs, explicit init output,
+  effective rule/source explanations, package compatibility reporting, lint
+  warning and performance budgets, real v2 migration fixtures, and a reusable
+  GitHub Action for consumer checks.
+
+### Patch Changes
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Resolve package-scoped Tailwind and Astro configuration roots, keep lazy framework imports anchored to their declaring package, add shared `projectDefaults` inheritance for monorepos, and move integration host libraries to optional peers.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Deprecate the Lite and Integrations compatibility packages during v3 and
+  schedule their removal for v4. Add TypeScript deprecation annotations,
+  migration guidance, and post-publish npm registry warnings. Also deprecate the
+  `integrations` option alias and `doctor --lite-install` compatibility workflow.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Include explicit feature, preset, and strict config selections in CLI install
+  and doctor repair planning, preserve runtime dependency fields and peer metadata
+  during v3 migrations, analyze TypeScript ESLint config files during doctor
+  checks, and honor dot-prefixed workspace exclusion patterns during project
+  detection.
+- Updated dependencies [[`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967), [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967), [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967), [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967), [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967), [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967), [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967)]:
+  - @santi020k/eslint-config-core@3.1.0
+  - @santi020k/eslint-config-typescript@3.1.0
+
 ## 3.0.0
 
 ### Major Changes

package/IMPROVEMENTS.md

@@ -0,0 +1,270 @@
+# Consumer-driven improvements
+
+These opportunities came from migrating a real ESLint 10, pnpm, TypeScript,
+Astro, Tailwind, and Vitest monorepo to the modular v3 packages. They are
+ordered by how directly they affect whether a consumer can install and lint
+successfully.
+
+## Implemented for the next release
+
+- Every generated rule block now receives the plugin objects it references,
+  with a contract test covering the complete optional-feature registry.
+- Doctor and install planning now inspect every pnpm workspace project and
+  explicit `features` selection.
+- Normal doctor output reports modular v3 packages and no longer recommends
+  deprecated Lite packages unless `--lite-install` is requested.
+- Scoped projects inherit root detection and Tailwind defaults, while
+  `projectDefaults` and project options remain the more specific layers.
+- TypeScript `untypedFiles` overrides are composed after framework parser
+  configs, including Astro projects.
+- `init --explicit` now generates the v3 `features` map.
+- Preset adoption reports compare effective rules by category and can write a
+  temporary compatibility override.
+- CLI subcommands now have strict, side-effect-free help and flag validation.
+- Minimum-release-age failures receive a dedicated compatible-range diagnostic.
+- Release checks enforce peer health with owned, conditional exceptions.
+- Safe migration rewrites prefer `features` and `root`, while dynamic cases
+  receive explicit manual-action guidance.
+- The release check now installs a packed pnpm monorepo consumer with Astro,
+  Tailwind, TypeScript, Vitest, format, tool, and extension packs; it runs
+  doctor, ESLint 10, config typechecking, and a frozen-lockfile reinstall.
+
+## Completed — Make every emitted config independently valid in ESLint 10
+
+The Tailwind settings config can reference
+`better-tailwindcss/no-unknown-classes` while the
+`better-tailwindcss` plugin is registered on another config object. ESLint 10
+then reports that it cannot find the plugin, especially when a consumer adds a
+later file-scoped override for the rule.
+
+Improve the composer so every emitted config object that references a plugin
+rule also carries that plugin registration. This should be guaranteed for all
+framework and feature-pack configs, not only Tailwind.
+
+Acceptance criteria:
+
+- `defineConfig()` output can be passed directly to ESLint 10 without a
+  consumer-side plugin-copying workaround.
+- A later `{ files, rules }` override can disable a feature-pack rule without
+  manually importing or locating the plugin.
+- A contract test checks every emitted `plugin/rule` entry against the plugins
+  available to that config object.
+
+## Completed — Make the install planner project-aware
+
+A monorepo can disable root-level library detection and still enable a
+library-backed feature inside a scoped project. For example, an Astro docs
+project can detect Tailwind and require
+`@santi020k/eslint-config-libraries`, even when the root has
+`detection: { libraries: false }`.
+
+The doctor and install commands should resolve the same project scopes,
+detection controls, and feature graph as `defineConfig()`. They should report
+all required category packages before ESLint is started.
+
+Acceptance criteria:
+
+- `basic-eslint doctor` reports a missing category package required by any
+  configured project.
+- `basic-eslint install --dry-run` returns the exact modular packages required
+  by root and project-scoped features.
+- Detection disabled at one scope does not suppress requirements discovered in
+  another scope.
+
+## Completed — Replace deprecated Lite advice in normal doctor output
+
+The JSON doctor result currently includes a `liteInstallCommand` that recommends
+`@santi020k/eslint-config-lite` and
+`@santi020k/eslint-config-integrations`, even when the consumer uses the v3
+basic package and did not request `--lite-install`.
+
+Normal doctor output should recommend the lean v3 package set. Deprecated Lite
+advice should only be produced when `--lite-install` is explicitly requested
+and should be labeled as a compatibility workflow.
+
+Acceptance criteria:
+
+- Default JSON output exposes a modular `installCommand` or structured
+  `requiredPackages` result.
+- `liteInstallCommand` is omitted unless `--lite-install` is present.
+- The suggested command uses the detected framework and category packages.
+
+## Completed — Clarify root versus project option inheritance
+
+Settings such as `tailwind.noUnknownClasses` may need to be repeated inside a
+project scope to affect that project's generated config. Consumers need a clear
+way to express shared defaults without learning this through lint failures.
+
+Prefer one of these approaches:
+
+1. inherit safe root options into projects consistently; or
+2. require `projectDefaults`, document it prominently, and have doctor suggest
+   moving misplaced root options there.
+
+Acceptance criteria:
+
+- The monorepo guide shows how root options, `projectDefaults`, and project
+  overrides compose.
+- Doctor warns when a root option has no effect on scoped projects.
+- Tests cover Tailwind, TypeScript, detection controls, and runtime defaults.
+
+## Completed — Add a realistic modular-consumer release fixture
+
+Add a packed-package fixture matching a production monorepo:
+
+- pnpm workspace with multiple package projects;
+- Astro and Tailwind in one app only;
+- TypeScript project service;
+- Vitest, JSONC, Markdown, YAML, pnpm, CSpell, boundaries, and Unicorn;
+- explicit `features` configuration;
+- ESLint 10 with `--max-warnings=0`.
+
+The fixture should install from packed tarballs, run doctor, lint, typecheck,
+and verify that the lockfile is frozen-installable. This catches package
+boundary and resolver errors that workspace symlinks can hide.
+
+## Completed — Preserve pnpm workspace catalogs during installation
+
+`basic-eslint install` currently writes a direct semver range into the nearest
+`package.json`. In catalog-managed workspaces this immediately violates
+`pnpm/json-enforce-catalog` and forces the consumer to move every dependency by
+hand.
+
+The installer should discover `pnpm-workspace.yaml`, update the appropriate
+catalog entry, and write `catalog:` in the package manifest. It should also
+detect the workspace package manager from the root instead of falling back to
+npm when invoked from a nested package.
+
+Acceptance criteria:
+
+- Existing `catalog:`, `catalog:default`, and named-catalog conventions are
+  preserved.
+- `--dry-run` shows both manifest and workspace-catalog changes.
+- Running from a nested workspace package still uses the root package manager.
+- A second installation is idempotent.
+
+The installer now resolves the pnpm workspace root even when invoked from a
+nested package and asks pnpm to save new dependencies into the existing
+default or named catalog. Dry runs print the exact catalog-aware command.
+Idempotency is delegated to pnpm's catalog-aware `add` operation.
+
+## Completed — Keep `untypedFiles` last enough to be effective
+
+In Astro consumers, the generated `eslint-config-typescript/untyped-files`
+entry can appear before a later framework entry re-enables typed parser
+options. Consumers then receive a parser error saying that `project` and
+`projectService` are enabled together, and must find and append the generated
+entry manually.
+
+Compose untyped-file overrides after framework and project configs, or merge
+parser options with a deterministic precedence model.
+
+Acceptance criteria:
+
+- `typescript.untypedFiles: ['**/*.astro']` works with the Astro framework.
+- The same behavior works inside a scoped monorepo project.
+- Consumers never need to inspect config names and reorder generated entries.
+
+## Completed — Preserve nested import failures
+
+When an optional framework package exists but fails while importing one of its
+own dependencies, the current error can say only that the optional framework
+could not be loaded. During migration, a React integration failure caused by a
+Zod compatibility mismatch looked like a missing React package.
+
+Error handling should distinguish:
+
+- package not installed;
+- installed package failed to evaluate;
+- incompatible peer or transitive dependency.
+
+Always retain the original error as `cause`, show the failing package path, and
+include the one-command remediation only when the package is genuinely absent.
+
+## Completed — Make preset expansion visible and adoption-friendly
+
+`Preset.App`, `Preset.Worker`, and `Preset.Library` can activate substantially
+more rules than an existing default config. That is useful for new projects,
+but a migration can unexpectedly introduce hundreds of formatting or
+domain-specific findings.
+
+Add `basic-eslint explain-preset <preset>` and a migration mode that compares
+the current effective config with the selected preset. Group the output into
+formatting, correctness, security, framework, and domain rules, and generate a
+temporary compatibility override when requested.
+
+## Completed — Make CLI help side-effect free
+
+`basic-eslint install --help` should print subcommand help and exit without
+installing packages. Add command-level parsing tests for `--help`, `--dry-run`,
+and invalid flags so documentation discovery can never mutate a workspace.
+
+Help flags are intercepted before command dispatch, dedicated subcommand help
+lists only supported flags, and strict parsing rejects unknown or incomplete
+options before any handler can mutate the workspace.
+
+## Completed — Respect release compatibility under minimum-age policies
+
+With pnpm's `minimumReleaseAge`, requesting an unversioned companion package can
+resolve an older major while Basic itself is already pinned to 3.1. The install
+planner should derive companion ranges from the installed Basic major/minor
+instead of asking the package manager for an unconstrained latest version.
+
+For Basic 3.1, generated install requests should use a compatible 3.1 range and
+produce a clear message when workspace supply-chain policy temporarily blocks
+that release.
+
+Install and doctor commands derive a compatible caret range from the installed
+Basic dependency, including catalog-backed versions, and use that range for
+modular companion packages. Install also recognizes pnpm minimum-release-age
+failures and explains the wait-or-exclude policy without suggesting an
+incompatible release.
+
+## Completed — Treat peer health as a release signal
+
+The modular consumer installed and linted successfully but `pnpm peers check`
+still reported stale ESLint and TypeScript peer ranges from transitive plugins.
+These warnings make genuine missing-peer failures harder to notice.
+
+Add a release report that:
+
+- runs the package manager's peer checker in packed consumer fixtures;
+- identifies which direct package introduces each warning;
+- fails for newly introduced actionable warnings;
+- records explicitly accepted upstream range gaps with an owner and removal
+  condition.
+
+## Completed — Generate modern configuration during migration
+
+Migration output should prefer the v3 `features` map and `root` option over
+legacy category arrays and root-directory aliases. When custom classes are
+detected, it should offer the supported project-scoped Tailwind option instead
+of generating a raw rule override.
+
+`init --explicit` emits `features`. The v3 migration rewrites literal category
+arrays, the deprecated `integrations` alias, and unambiguous root aliases.
+Expressions, spreads, comments inside dynamic selections, conflicting root
+aliases, and raw Tailwind rule overrides are preserved and reported as manual
+actions so migration never changes behavior it cannot prove safe.
+
+An ideal generated result is concise and self-explanatory:
+
+```js
+export default await defineConfig({
+  features: {
+    boundaries: true,
+    jsonc: true,
+    markdown: true,
+    pnpm: true,
+    unicorn: true,
+    vitest: true,
+    yaml: true
+  },
+  projects: {
+    'apps/docs': {
+      tailwind: { noUnknownClasses: false }
+    }
+  },
+  root: import.meta.dirname
+})
+```

package/README.md

@@ -1,19 +1,11 @@
 # @santi020k/eslint-config-basic
 
-The lean v3 default for ESLint 10 flat config.
+The primary entry point that composes all feature-specific configurations.
 
-```sh
-npm install -D eslint @santi020k/eslint-config-basic
-```
+This package is part of the [`@santi020k/eslint-config-basic`](https://github.com/santi020k/eslint-config-basic) monorepo.
 
-```js
-export { default } from '@santi020k/eslint-config-basic/recommended'
-```
+- Docs: [Main package](https://eslint.santi020k.com/packages/basic)
+- Repository: [santi020k/eslint-config-basic](https://github.com/santi020k/eslint-config-basic)
+- Author: [santi020k](https://santi020k.com)
 
-Add only the framework packages and `@santi020k/eslint-config-integrations`
-that the project uses. Choose `@santi020k/eslint-config-full` for the
-batteries-included dependency model.
-
-- [Documentation](https://eslint.santi020k.com/)
-- [Migration from v2](https://eslint.santi020k.com/guide/migration-v2-to-v3/)
-- [Repository](https://github.com/santi020k/eslint-config-basic)
+The canonical documentation lives on the Starlight site, so this README intentionally stays short to avoid duplication.

package/dist/agent-skill-generator.d.ts

@@ -1,3 +1,4 @@
+declare const ESLINT_CONFIG_FILENAMES: readonly ["eslint.config.js", "eslint.config.mjs", "eslint.config.cjs", "eslint.config.ts", "eslint.config.mts", "eslint.config.cts"];
 interface AgentTarget {
     /** Format variant used when generating content */
     format: 'cursor' | 'frontmatter' | 'kiro' | 'plain';
@@ -50,6 +51,12 @@ interface GenerateSkillOptions {
      * @default false
      */
     force?: boolean;
+    /**
+     * Add the official `eslint --mcp` server to the project root `.mcp.json`.
+     * Existing unrelated MCP server entries are preserved.
+     * @default false
+     */
+    withEslintMcp?: boolean;
 }
 interface GenerateSkillResult {
     skipped: string[];
@@ -90,7 +97,7 @@ declare const generateSkillContent: (features: EslintConfigFeatures, format: Age
  *
  * @example
  * ```ts
- * import { generateAgentSkills } from '@santi020k/eslint-config-basic'
+ * import { generateAgentSkills } from '@santi020k/eslint-config-basic/agent'
  *
  * const result = await generateAgentSkills({ cwd: process.cwd() })
  * process.stdout.write(`Written to: ${result.written}\n`)
@@ -102,7 +109,9 @@ interface HandleGenerateSkillFlags {
     check?: boolean;
     /** Create a root `AGENTS.md` when it does not exist */
     createAgentsMd?: boolean;
+    /** Add the official ESLint MCP server to `.mcp.json` */
+    withEslintMcp?: boolean;
 }
 declare const handleGenerateSkill: (cwd?: string, force?: boolean, flags?: HandleGenerateSkillFlags) => Promise<void>;
 
-export { AGENT_TARGETS, type AgentTarget, type EslintConfigFeatures, type GenerateSkillOptions, type GenerateSkillResult, type HandleGenerateSkillFlags, analyzeEslintConfig, generateAgentSkills, generateSkillContent, handleGenerateSkill };
+export { AGENT_TARGETS, type AgentTarget, ESLINT_CONFIG_FILENAMES, type EslintConfigFeatures, type GenerateSkillOptions, type GenerateSkillResult, type HandleGenerateSkillFlags, analyzeEslintConfig, generateAgentSkills, generateSkillContent, handleGenerateSkill };

package/dist/agent-skill-generator.js

@@ -2,6 +2,14 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { detectProjectOptions } from "./index.js";
+const ESLINT_CONFIG_FILENAMES = [
+  "eslint.config.js",
+  "eslint.config.mjs",
+  "eslint.config.cjs",
+  "eslint.config.ts",
+  "eslint.config.mts",
+  "eslint.config.cts"
+];
 const AGENT_TARGETS = [
   {
     format: "frontmatter",
@@ -97,7 +105,6 @@ const FEATURE_MAP = [
   ["eslint-config-expo/", "frameworks", "Expo"],
   ["eslint-config-qwik/", "frameworks", "Qwik"],
   ["eslint-config-react-router/", "frameworks", "React Router"],
-  ["eslint-config-remix/", "frameworks", "Remix"],
   ["eslint-config-solid/", "frameworks", "SolidJS"],
   ["eslint-config-nuxt/", "frameworks", "Nuxt"],
   ["eslint-config-lit/", "frameworks", "Lit"],
@@ -187,7 +194,6 @@ const DETECTED_FRAMEWORK_LABELS = /* @__PURE__ */ new Map([
   ["qwik", "Qwik"],
   ["react", "React"],
   ["react-router", "React Router"],
-  ["remix", "Remix"],
   ["slidev", "Slidev"],
   ["solid", "SolidJS"],
   ["svelte", "Svelte"],
@@ -302,7 +308,7 @@ const extractFeatures = (configs, lintCommand, configFile) => {
   return features;
 };
 const findEslintConfig = (cwd) => {
-  for (const name of ["eslint.config.js", "eslint.config.mjs", "eslint.config.cjs"]) {
+  for (const name of ESLINT_CONFIG_FILENAMES) {
     const p = join(cwd, name);
     if (existsSync(p)) return p;
   }
@@ -594,10 +600,46 @@ const resolveSkillOptions = (opts) => ({
   check: opts.check ?? false,
   createAgentsMd: opts.createAgentsMd ?? false,
   cwd: opts.cwd ?? process.cwd(),
-  force: opts.force ?? false
+  force: opts.force ?? false,
+  withEslintMcp: opts.withEslintMcp ?? false
 });
+const createEslintMcpServer = (cwd) => {
+  if (existsSync(join(cwd, "pnpm-lock.yaml")) || existsSync(join(cwd, "pnpm-workspace.yaml"))) {
+    return { args: ["exec", "eslint", "--mcp"], command: "pnpm" };
+  }
+  if (existsSync(join(cwd, "yarn.lock"))) {
+    return { args: ["exec", "eslint", "--mcp"], command: "yarn" };
+  }
+  if (existsSync(join(cwd, "bun.lockb")) || existsSync(join(cwd, "bun.lock"))) {
+    return { args: ["eslint", "--mcp"], command: "bunx" };
+  }
+  return { args: ["eslint", "--mcp"], command: "npx" };
+};
+const handleEslintMcpConfig = (cwd, force, check) => {
+  const configPath = join(cwd, ".mcp.json");
+  const server = createEslintMcpServer(cwd);
+  let config = {};
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf8"));
+    } catch {
+      throw new Error(".mcp.json is invalid JSON; fix it before adding the ESLint MCP server.");
+    }
+  }
+  const current = config.mcpServers?.eslint;
+  const isCurrent = JSON.stringify(current) === JSON.stringify(server);
+  if (check) return isCurrent ? "skipped" : "stale";
+  if (current && !force) return "skipped";
+  config.mcpServers = {
+    ...config.mcpServers,
+    eslint: server
+  };
+  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}
+`);
+  return "written";
+};
 const generateAgentSkills = async (opts = {}) => {
-  const { check, createAgentsMd, cwd, force } = resolveSkillOptions(opts);
+  const { check, createAgentsMd, cwd, force, withEslintMcp } = resolveSkillOptions(opts);
   const written = [];
   const skipped = [];
   const stale = [];
@@ -620,6 +662,10 @@ const generateAgentSkills = async (opts = {}) => {
   recordGuardedResult(copilotPath, handleGuardedSectionFile(copilotPath, plainBody, force, check));
   const agentsMdPath = join(cwd, AGENTS_MD_PATH);
   recordGuardedResult(agentsMdPath, handleGuardedSectionFile(agentsMdPath, plainBody, force, check, createAgentsMd));
+  if (withEslintMcp) {
+    const eslintMcpPath = join(cwd, ".mcp.json");
+    recordGuardedResult(eslintMcpPath, handleEslintMcpConfig(cwd, force, check));
+  }
   for (const target of AGENT_TARGETS) {
     const agentFolder = join(cwd, target.markerFolder);
     if (!existsSync(agentFolder)) continue;
@@ -640,7 +686,8 @@ const generateAgentSkills = async (opts = {}) => {
 };
 const resolveGenerateSkillFlags = (flags) => ({
   check: flags.check ?? false,
-  createAgentsMd: flags.createAgentsMd ?? false
+  createAgentsMd: flags.createAgentsMd ?? false,
+  withEslintMcp: flags.withEslintMcp ?? false
 });
 const outputGenerateSkillResults = (check, result, cwd) => {
   if (check) {
@@ -675,7 +722,7 @@ const outputGenerateSkillResults = (check, result, cwd) => {
   }
 };
 const handleGenerateSkill = async (cwd = process.cwd(), force = false, flags = {}) => {
-  const { check, createAgentsMd } = resolveGenerateSkillFlags(flags);
+  const { check, createAgentsMd, withEslintMcp } = resolveGenerateSkillFlags(flags);
   console.log(check ? "\u{1F50D} Checking AI agent skill files..." : "\u{1F50D} Scanning for AI agent folders...");
   const configFile = findEslintConfig(cwd);
   if (configFile) {
@@ -683,7 +730,7 @@ const handleGenerateSkill = async (cwd = process.cwd(), force = false, flags = {
   } else {
     console.log("\u26A0\uFE0F  No eslint.config.js found \u2014 falling back to package.json detection.");
   }
-  const result = await generateAgentSkills({ check, createAgentsMd, cwd, force });
+  const result = await generateAgentSkills({ check, createAgentsMd, cwd, force, withEslintMcp });
   if (result.written.length === 0 && result.skipped.length === 0 && result.stale.length === 0) {
     console.log("\n\u26A0\uFE0F  No agent folders found (.agent, .agents, .claude, .cursor, .windsurf, .copilot, .aider, .gemini, .clinerules, .roo, .kiro) and no AGENTS.md.");
     console.log("   Create one of those folders first (or re-run with --create to scaffold AGENTS.md).");
@@ -693,6 +740,7 @@ const handleGenerateSkill = async (cwd = process.cwd(), force = false, flags = {
 };
 export {
   AGENT_TARGETS,
+  ESLINT_CONFIG_FILENAMES,
   analyzeEslintConfig,
   generateAgentSkills,
   generateSkillContent,

package/dist/cli-advanced.d.ts

@@ -0,0 +1,23 @@
+interface ExplainRuleOptions {
+    file?: string;
+    json?: boolean;
+    rule: string;
+}
+declare const handleExplainRule: (cwd: string | undefined, options: ExplainRuleOptions) => Promise<void>;
+declare const createCompatibilityReport: (cwd?: string) => {
+    compatible: boolean;
+    packages: {
+        declared: string;
+        issues: string[];
+        name: string;
+        resolved: string | null;
+    }[];
+    runtime: {
+        eslint: string | null;
+        node: string;
+        typescript: string | null;
+    };
+};
+declare const handleCompatibility: (cwd?: string, json?: boolean) => void;
+
+export { type ExplainRuleOptions, createCompatibilityReport, handleCompatibility, handleExplainRule };