@santi020k/eslint-config-basic 1.5.0 → 2.0.0-beta.0

package/dist/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { analyzeEslintConfig, handleGenerateSkill } from "./agent-skill-generator.js";
 import { detectProjectOptions } from "./index.js";
 const getDefaultConfigFilename = (cwd) => {
   const packageJsonPath = join(cwd, "package.json");
@@ -17,48 +19,303 @@ const resolveConfigPath = (cwd) => {
   const existingConfigPath = [
     "eslint.config.js",
     "eslint.config.mjs"
-  ].map((filename) => join(cwd, filename)).find(existsSync);
+  ].map((filename) => join(cwd, filename)).find((p) => existsSync(p));
   return existingConfigPath ?? join(cwd, getDefaultConfigFilename(cwd));
 };
 const getFrameworkKeys = (detectedFrameworks) => {
   const frameworkKeys = new Set(detectedFrameworks ?? []);
-  if (frameworkKeys.has("next") || frameworkKeys.has("expo")) {
+  if (frameworkKeys.has("next") || frameworkKeys.has("expo") || frameworkKeys.has("remix") || frameworkKeys.has("react-router") || frameworkKeys.has("tanstack-start") && !frameworkKeys.has("solid")) {
     frameworkKeys.add("react");
   }
   return [...frameworkKeys].sort();
 };
+const toPropertyKey = (key) => /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : `'${key}'`;
+const FRAMEWORK_PACKAGE_TO_KEY = {
+  "@santi020k/eslint-config-angular": "angular",
+  "@santi020k/eslint-config-astro": "astro",
+  "@santi020k/eslint-config-expo": "expo",
+  "@santi020k/eslint-config-hono": "hono",
+  "@santi020k/eslint-config-lit": "lit",
+  "@santi020k/eslint-config-nest": "nest",
+  "@santi020k/eslint-config-next": "next",
+  "@santi020k/eslint-config-nuxt": "nuxt",
+  "@santi020k/eslint-config-preact": "preact",
+  "@santi020k/eslint-config-qwik": "qwik",
+  "@santi020k/eslint-config-react": "react",
+  "@santi020k/eslint-config-react-router": "react-router",
+  "@santi020k/eslint-config-remix": "remix",
+  "@santi020k/eslint-config-slidev": "slidev",
+  "@santi020k/eslint-config-solid": "solid",
+  "@santi020k/eslint-config-svelte": "svelte",
+  "@santi020k/eslint-config-tanstack-start": "tanstack-start",
+  "@santi020k/eslint-config-vite": "vite",
+  "@santi020k/eslint-config-vue": "vue"
+};
+const FRAMEWORK_KEY_TO_PACKAGE = Object.fromEntries(
+  Object.entries(FRAMEWORK_PACKAGE_TO_KEY).map(([packageName, framework]) => [framework, packageName])
+);
+const LITE_PACKAGE_NAME = "@santi020k/eslint-config-lite";
+const INTEGRATIONS_PACKAGE_NAME = "@santi020k/eslint-config-integrations";
+const TYPESCRIPT_PACKAGE_NAME = "typescript";
+const getConfigPathIfPresent = (cwd) => {
+  const configPath = [
+    "eslint.config.js",
+    "eslint.config.mjs",
+    "eslint.config.cjs"
+  ].map((filename) => join(cwd, filename)).find((p) => existsSync(p));
+  return configPath ?? null;
+};
+const readPackageJson = (cwd) => {
+  const packageJsonPath = join(cwd, "package.json");
+  if (!existsSync(packageJsonPath)) return null;
+  try {
+    return JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+  } catch {
+    return null;
+  }
+};
+const getDeclaredDependencyNames = (packageJson) => {
+  const dependencyFields = [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies"
+  ];
+  const names = /* @__PURE__ */ new Set();
+  for (const field of dependencyFields) {
+    const dependencies = packageJson?.[field];
+    if (!dependencies || typeof dependencies !== "object" || Array.isArray(dependencies)) continue;
+    for (const name of Object.keys(dependencies)) {
+      names.add(name);
+    }
+  }
+  return names;
+};
+const needsIntegrationPackage = (summary) => summary.libraries.length > 0 || summary.testing.length > 0 || summary.formats.length > 0 || summary.tools.length > 0 || summary.extensions.some((extension) => extension !== "boundaries");
+const hasPresetAll = (configContent) => Boolean(
+  configContent && (/\bPreset\.All\b/.test(configContent) || /preset\s*:\s*['"]all['"]/.test(configContent))
+);
+const getLiteInstallPackages = (summary, declaredDependencies) => {
+  const packages = /* @__PURE__ */ new Set([
+    "eslint",
+    LITE_PACKAGE_NAME
+  ]);
+  for (const framework of summary.frameworks) {
+    const packageName = FRAMEWORK_KEY_TO_PACKAGE[framework];
+    if (packageName) packages.add(packageName);
+  }
+  if (needsIntegrationPackage(summary)) {
+    packages.add(INTEGRATIONS_PACKAGE_NAME);
+  }
+  if (summary.typescript && !declaredDependencies.has(TYPESCRIPT_PACKAGE_NAME)) {
+    packages.add(TYPESCRIPT_PACKAGE_NAME);
+  }
+  return [...packages];
+};
+const createInstallCommand = (packageManager, packages) => {
+  const packageList = packages.join(" ");
+  switch (packageManager) {
+    case "bun":
+      return `bun add -d ${packageList}`;
+    case "npm":
+      return `npm install -D ${packageList}`;
+    case "yarn":
+      return `yarn add -D ${packageList}`;
+    default:
+      return `pnpm add -D ${packageList}`;
+  }
+};
+const detectPackageManager = (cwd) => {
+  if (existsSync(join(cwd, "pnpm-lock.yaml")) || existsSync(join(cwd, "pnpm-workspace.yaml"))) return "pnpm";
+  if (existsSync(join(cwd, "yarn.lock"))) return "yarn";
+  if (existsSync(join(cwd, "bun.lockb")) || existsSync(join(cwd, "bun.lock"))) return "bun";
+  return "npm";
+};
+const hasLintScript = (cwd) => {
+  const packageJson = readPackageJson(cwd);
+  return Boolean(packageJson?.scripts?.lint);
+};
+const getWorkspacePatternsFromPackageJson = (packageJson) => {
+  const workspaces = packageJson?.workspaces;
+  if (Array.isArray(workspaces)) {
+    return workspaces.filter((value) => typeof value === "string");
+  }
+  if (workspaces && typeof workspaces === "object" && Array.isArray(workspaces.packages)) {
+    return workspaces.packages.filter((value) => typeof value === "string");
+  }
+  return [];
+};
+const getWorkspacePatternsFromPnpm = (cwd) => {
+  const workspacePath = join(cwd, "pnpm-workspace.yaml");
+  if (!existsSync(workspacePath)) return [];
+  const content = readFileSync(workspacePath, "utf8");
+  const patterns = [];
+  let inPackages = false;
+  for (const line of content.split(/\r?\n/)) {
+    if (/^packages:\s*$/.test(line)) {
+      inPackages = true;
+      continue;
+    }
+    if (inPackages && /^\S/.test(line)) break;
+    const match = inPackages ? /^\s*-\s*['"]?([^'"]+)['"]?\s*$/.exec(line) : null;
+    if (match?.[1] && !match[1].startsWith("!")) patterns.push(match[1]);
+  }
+  return patterns;
+};
+const expandWorkspacePattern = (cwd, pattern) => {
+  const normalized = pattern.replace(/\/$/, "");
+  if (!normalized.endsWith("/*")) return [];
+  const base = normalized.slice(0, -2);
+  const basePath = join(cwd, base);
+  if (!existsSync(basePath)) return [];
+  return readdirSync(basePath, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => `${base}/${entry.name}`).filter((projectPath) => existsSync(join(cwd, projectPath, "package.json")));
+};
+const detectWorkspaceProjects = (cwd) => {
+  const patterns = [
+    ...getWorkspacePatternsFromPackageJson(readPackageJson(cwd)),
+    ...getWorkspacePatternsFromPnpm(cwd)
+  ];
+  return [...new Set(patterns.flatMap((pattern) => expandWorkspacePattern(cwd, pattern)))].sort();
+};
+const getDetectionValues = (options) => ({
+  extensions: options.extensions ?? [],
+  formats: options.formats ?? [],
+  libraries: options.libraries ?? [],
+  runtime: options.runtime ?? "universal",
+  settings: options.settings ?? [],
+  testing: options.testing ?? [],
+  tools: options.tools ?? [],
+  typescript: options.typescript ?? false
+});
 const createConfigContent = (cwd) => {
   const options = detectProjectOptions(cwd);
+  const values = getDetectionValues(options);
   const frameworkKeys = getFrameworkKeys(options.detectedFrameworks);
   const imports = ["import { eslintConfig } from '@santi020k/eslint-config-basic'"];
-  frameworkKeys.forEach((key) => {
-    imports.push(`import ${key} from '@santi020k/eslint-config-${key}'`);
-  });
+  const presetLine = options.preset && options.preset !== "basic" ? `  preset: ${JSON.stringify(options.preset)},
+` : "";
   const configContent = `${imports.join("\n")}
 
-export default eslintConfig({
-  typescript: ${JSON.stringify(options.typescript ?? false)},
+export default await eslintConfig({
+${presetLine}  typescript: ${JSON.stringify(values.typescript)},
   frameworks: {
-    ${frameworkKeys.map((key) => `${key}: ${key}`).join(",\n    ")}
+    ${frameworkKeys.map((key) => `${toPropertyKey(key)}: true`).join(",\n    ")}
   },
-  libraries: ${JSON.stringify(options.libraries ?? [], null, 2)},
-  testing: ${JSON.stringify(options.testing ?? [], null, 2)},
-  formats: ${JSON.stringify(options.formats ?? [], null, 2)},
-  tools: ${JSON.stringify(options.tools ?? [], null, 2)},
-  extensions: ${JSON.stringify(options.extensions ?? [], null, 2)},
-  runtime: ${JSON.stringify(options.runtime ?? "universal")},
-  settings: ${JSON.stringify(options.settings ?? [], null, 2)}
+  libraries: ${JSON.stringify(values.libraries, null, 2)},
+  testing: ${JSON.stringify(values.testing, null, 2)},
+  formats: ${JSON.stringify(values.formats, null, 2)},
+  tools: ${JSON.stringify(values.tools, null, 2)},
+  extensions: ${JSON.stringify(values.extensions, null, 2)},
+  runtime: ${JSON.stringify(values.runtime)},
+  settings: ${JSON.stringify(values.settings, null, 2)}
 })
 `;
   return {
-    configPath: resolveConfigPath(cwd),
-    configContent
+    configContent,
+    configPath: resolveConfigPath(cwd)
   };
 };
-const handleInit = (cwd = process.cwd()) => {
+const formatList = (values) => {
+  if (!values?.length) return "none";
+  return values.join(", ");
+};
+const getProjectSummary = (cwd) => {
+  const options = detectProjectOptions(cwd);
+  const workspaceProjects = detectWorkspaceProjects(cwd);
+  return {
+    extensions: options.extensions ?? [],
+    formats: options.formats ?? [],
+    frameworks: getFrameworkKeys(options.detectedFrameworks),
+    libraries: options.libraries ?? [],
+    nextMode: options.nextMode ?? "n/a",
+    preset: options.preset ?? "basic",
+    runtime: options.runtime ?? "universal",
+    testing: options.testing ?? [],
+    tools: options.tools ?? [],
+    typescript: Boolean(options.typescript),
+    workspaceProjects
+  };
+};
+const createStandardsContent = (cwd) => {
+  const summary = getProjectSummary(cwd);
+  return [
+    "# ESLint Standards",
+    "",
+    "This document was generated from the active project dependencies detected by `@santi020k/eslint-config-basic`.",
+    "",
+    "## Active Profile",
+    "",
+    `- TypeScript: ${summary.typescript ? "enabled" : "disabled"}`,
+    `- Preset: ${summary.preset}`,
+    `- Runtime: ${summary.runtime}`,
+    `- Next.js mode: ${summary.nextMode}`,
+    `- Frameworks: ${formatList(summary.frameworks)}`,
+    `- Libraries: ${formatList(summary.libraries)}`,
+    `- Testing: ${formatList(summary.testing)}`,
+    `- Formats: ${formatList(summary.formats)}`,
+    `- Tools: ${formatList(summary.tools)}`,
+    `- Extensions: ${formatList(summary.extensions)}`,
+    "",
+    "## Recommended Config",
+    "",
+    "```js",
+    "import { eslintConfig } from '@santi020k/eslint-config-basic'",
+    "",
+    "export default await eslintConfig()",
+    "```",
+    "",
+    "Use `basic-eslint explain` when you want to inspect what the zero-config setup detects."
+  ].join("\n");
+};
+const getCliVersion = () => {
+  const cliDir = dirname(fileURLToPath(import.meta.url));
+  const packageJsonPath = join(cliDir, "..", "package.json");
+  try {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    return packageJson.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+};
+const printUsage = () => {
+  console.log([
+    "Usage: basic-eslint <command> [options]",
+    "",
+    "Commands:",
+    "  init            Create eslint.config.js/mjs if missing",
+    "  update          Regenerate eslint.config.js/mjs from detection",
+    "  explain         Print detected v2 config inputs",
+    "  inspect         Print detected inputs and active config features",
+    "  doctor          Check project setup for common v2 adoption issues",
+    "  docs            Generate ESLINT_STANDARDS.md from detection",
+    "  migrate         Report v1-to-v2 migration suggestions",
+    "  generate-skill  Generate AI agent standards files",
+    "",
+    "Options:",
+    "  --force         Overwrite existing generated skill sections/files",
+    "  --check         init: verify config exists; generate-skill: verify files are up to date",
+    "  --create        generate-skill: scaffold a root AGENTS.md when missing",
+    "  --json          Print JSON for commands that support it",
+    "  --lite-install  doctor: print the detected lite install command",
+    "  --write         Apply safe migrations for commands that support it",
+    "  --help, -h      Show this help message",
+    "  --version, -v   Show CLI version"
+  ].join("\n"));
+};
+const handleInit = (cwd = process.cwd(), check = false) => {
   const configPath = resolveConfigPath(cwd);
+  if (check) {
+    const exists = existsSync(configPath);
+    console.log(JSON.stringify({
+      configFile: exists ? basename(configPath) : null,
+      exists,
+      ok: exists
+    }, null, 2));
+    if (!exists) process.exitCode = 1;
+    return;
+  }
   if (existsSync(configPath)) {
-    console.warn(`\u26A0\uFE0F  ${basename(configPath)} already exists. Skipping...`);
+    console.error(`\u26A0\uFE0F  ${basename(configPath)} already exists. Skipping...`);
     return;
   }
   console.log("\u{1F50D} Detecting project settings...");
@@ -69,25 +326,340 @@ const handleInit = (cwd = process.cwd()) => {
 };
 const handleUpdate = (cwd = process.cwd()) => {
   console.log("\u{1F50D} Detecting project settings...");
-  const { configPath, configContent } = createConfigContent(cwd);
+  const { configContent, configPath } = createConfigContent(cwd);
+  if (existsSync(configPath)) {
+    const backupPath = `${configPath}.bak`;
+    const existing = readFileSync(configPath, "utf8");
+    writeFileSync(backupPath, existing);
+    console.log(`\u{1F4E6} Backed up existing config to ${basename(backupPath)}`);
+  }
   writeFileSync(configPath, configContent);
   console.log(`\u2705 Updated ${basename(configPath)} with auto-detected settings!`);
   console.log("\u{1F680} Ready to lint!");
 };
-const run = () => {
-  const command = process.argv[2];
-  if (command === "init") {
-    handleInit();
-  } else if (command === "update") {
-    handleUpdate();
+const handleExplain = (cwd = process.cwd(), json = false) => {
+  const summary = getProjectSummary(cwd);
+  if (json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  console.log([
+    "ESLint Basic detected configuration:",
+    `- TypeScript: ${summary.typescript ? "enabled" : "disabled"}`,
+    `- Preset: ${summary.preset}`,
+    `- Runtime: ${summary.runtime}`,
+    `- Next.js mode: ${summary.nextMode}`,
+    `- Frameworks: ${formatList(summary.frameworks)}`,
+    `- Libraries: ${formatList(summary.libraries)}`,
+    `- Testing: ${formatList(summary.testing)}`,
+    `- Formats: ${formatList(summary.formats)}`,
+    `- Tools: ${formatList(summary.tools)}`,
+    `- Extensions: ${formatList(summary.extensions)}`
+  ].join("\n"));
+};
+const handleInspect = async (cwd = process.cwd(), json = false) => {
+  const summary = getProjectSummary(cwd);
+  const activeConfig = await analyzeEslintConfig(cwd);
+  const payload = {
+    activeConfig,
+    detected: summary,
+    packageManager: detectPackageManager(cwd)
+  };
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log([
+    "ESLint Basic inspection:",
+    `- Package manager: ${payload.packageManager}`,
+    `- Config source: ${activeConfig?.source ?? "not found"}`,
+    `- Config file: ${activeConfig?.configFile ?? "none"}`,
+    `- TypeScript: ${summary.typescript ? "enabled" : "disabled"}`,
+    `- Preset: ${summary.preset}`,
+    `- Runtime: ${summary.runtime}`,
+    `- Frameworks: ${formatList(summary.frameworks)}`,
+    `- Libraries: ${formatList(summary.libraries)}`,
+    `- Testing: ${formatList(summary.testing)}`,
+    `- Formats: ${formatList(summary.formats)}`,
+    `- Tools: ${formatList(summary.tools)}`,
+    `- Extensions: ${formatList(summary.extensions)}`,
+    `- Workspace projects: ${formatList(summary.workspaceProjects)}`
+  ].join("\n"));
+};
+const findDuplicateEslint = (cwd = process.cwd()) => {
+  try {
+    const projectRequire = createRequire(join(cwd, "package.json"));
+    const projectEslintPkgPath = projectRequire.resolve("eslint/package.json");
+    const coreMainPath = projectRequire.resolve("@santi020k/eslint-config-core");
+    const coreRequire = createRequire(coreMainPath);
+    const coreEslintPkgPath = coreRequire.resolve("eslint/package.json");
+    if (projectEslintPkgPath === coreEslintPkgPath) return null;
+    const projectVersion = JSON.parse(readFileSync(projectEslintPkgPath, "utf8")).version ?? "unknown";
+    const configVersion = JSON.parse(readFileSync(coreEslintPkgPath, "utf8")).version ?? "unknown";
+    if (projectVersion === configVersion) return null;
+    return { configVersion, projectVersion };
+  } catch {
+    return null;
+  }
+};
+const validateConfigContent = (configContent, hasV1FrameworkImports, declaredDependencies, summary) => {
+  const warnings = [];
+  if (hasV1FrameworkImports) {
+    warnings.push("Config still imports v1 framework packages. Run `basic-eslint migrate --write` or switch to framework booleans.");
+  }
+  if (summary.workspaceProjects.length > 0 && !configContent.includes("projects:")) {
+    warnings.push("Workspace packages were detected, but the root config does not use `projects` scoping.");
+  }
+  if (configContent.includes(LITE_PACKAGE_NAME)) {
+    const missingFrameworkPackages = summary.frameworks.map((framework) => FRAMEWORK_KEY_TO_PACKAGE[framework]).filter((packageName) => Boolean(packageName)).filter((packageName) => !declaredDependencies.has(packageName));
+    if (missingFrameworkPackages.length > 0) {
+      warnings.push(
+        `Lite config detected ${formatList(summary.frameworks)}, but these framework config packages are not declared: ${missingFrameworkPackages.join(", ")}. Install them or disable those frameworks.`
+      );
+    }
+    if (needsIntegrationPackage(summary) && !declaredDependencies.has(INTEGRATIONS_PACKAGE_NAME)) {
+      warnings.push(
+        `Lite config detected optional integrations, but ${INTEGRATIONS_PACKAGE_NAME} is not declared. Install it or remove the selected libraries, testing tools, formats, tools, and extension integrations.`
+      );
+    }
+    if (hasPresetAll(configContent)) {
+      warnings.push(
+        "Lite config uses Preset.All, which enables every optional integration and reduces the dependency benefits of lite. Prefer enabling only the integrations this project uses."
+      );
+    }
+  }
+  return warnings;
+};
+const buildDoctorDiagnosis = (cwd, configPath, configContent, hasV1FrameworkImports, activeConfig, declaredDependencies, summary) => {
+  const issues = [];
+  const warnings = [];
+  if (!readPackageJson(cwd)) {
+    issues.push("package.json is missing or invalid.");
+  }
+  if (!configPath) {
+    warnings.push("No eslint.config.js/mjs/cjs file found. Run `basic-eslint init` to create one.");
+  } else if (!activeConfig && !hasV1FrameworkImports) {
+    issues.push(`${basename(configPath)} could not be loaded. Run ESLint directly to see the import error.`);
+  }
+  if (!hasLintScript(cwd)) {
+    warnings.push("No `lint` script found in package.json.");
+  }
+  if (configContent) {
+    warnings.push(...validateConfigContent(configContent, hasV1FrameworkImports, declaredDependencies, summary));
+  }
+  const duplicateEslint = findDuplicateEslint(cwd);
+  if (duplicateEslint) {
+    warnings.push(
+      `Two ESLint copies are installed: the project resolves ${duplicateEslint.projectVersion} while the config packages resolve ${duplicateEslint.configVersion}. Only ESLint 10 is supported, and parallel copies can apply different rule behavior between your editor and CLI. Align the project's eslint version with the config's (or dedupe via your package manager).`
+    );
+  }
+  return { issues, warnings };
+};
+const outputDoctorResult = (json, configPath, packageManager, summary, liteInstallCommand, issues, warnings) => {
+  let status = "passed";
+  if (issues.length > 0) {
+    status = "failed";
+  } else if (warnings.length > 0) {
+    status = "passed with warnings";
+  }
+  const payload = {
+    configFile: configPath ? basename(configPath) : null,
+    issues,
+    liteInstallCommand,
+    packageManager,
+    status,
+    warnings,
+    workspaceProjects: summary.workspaceProjects
+  };
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+    if (issues.length > 0) process.exitCode = 1;
+    return;
+  }
+  console.log([
+    `ESLint Basic doctor: ${status}`,
+    `- Package manager: ${payload.packageManager}`,
+    `- Config file: ${payload.configFile ?? "none"}`,
+    `- Workspace projects: ${formatList(summary.workspaceProjects)}`,
+    ...issues.length > 0 ? ["", "Issues:", ...issues.map((issue) => `- ${issue}`)] : [],
+    ...warnings.length > 0 ? ["", "Warnings:", ...warnings.map((warning) => `- ${warning}`)] : []
+  ].join("\n"));
+  if (issues.length > 0) process.exitCode = 1;
+};
+const handleDoctor = async (cwd = process.cwd(), json = false, liteInstall = false) => {
+  const configPath = getConfigPathIfPresent(cwd);
+  const packageJson = readPackageJson(cwd);
+  const declaredDependencies = getDeclaredDependencyNames(packageJson);
+  const summary = getProjectSummary(cwd);
+  const activeConfig = await analyzeEslintConfig(cwd);
+  const configContent = configPath ? readFileSync(configPath, "utf8") : null;
+  const packageManager = detectPackageManager(cwd);
+  const liteInstallPackages = getLiteInstallPackages(summary, declaredDependencies);
+  const liteInstallCommand = createInstallCommand(packageManager, liteInstallPackages);
+  const hasV1FrameworkImports = configContent ? Object.keys(FRAMEWORK_PACKAGE_TO_KEY).some((packageName) => configContent.includes(packageName)) : false;
+  if (liteInstall) {
+    if (json) {
+      console.log(JSON.stringify({ command: liteInstallCommand, packageManager, packages: liteInstallPackages }, null, 2));
+    } else {
+      console.log(liteInstallCommand);
+    }
+    return;
+  }
+  const { issues, warnings } = buildDoctorDiagnosis(cwd, configPath, configContent, hasV1FrameworkImports, activeConfig, declaredDependencies, summary);
+  outputDoctorResult(json, configPath, packageManager, summary, liteInstallCommand, issues, warnings);
+};
+const handleDocs = (cwd = process.cwd()) => {
+  const outputPath = join(cwd, "ESLINT_STANDARDS.md");
+  writeFileSync(outputPath, createStandardsContent(cwd));
+  console.log("\u2705 Generated ESLINT_STANDARDS.md");
+};
+const migrateConfigContent = (content) => {
+  const importedFrameworks = Object.entries(FRAMEWORK_PACKAGE_TO_KEY).filter(([packageName]) => content.includes(packageName)).map(([, framework]) => framework);
+  if (importedFrameworks.length === 0) {
+    return { changed: false, content, frameworks: [] };
+  }
+  const frameworks = getFrameworkKeys(importedFrameworks);
+  const migrated = [
+    "import { eslintConfig } from '@santi020k/eslint-config-basic'",
+    "",
+    "export default await eslintConfig({",
+    "  frameworks: {",
+    `    ${frameworks.map((key) => `${toPropertyKey(key)}: true`).join(",\n    ")}`,
+    "  }",
+    "})",
+    ""
+  ].join("\n");
+  return { changed: true, content: migrated, frameworks };
+};
+const processConfigMigration = (configPath, write, suggestions) => {
+  const applied = [];
+  if (!existsSync(configPath)) {
+    if (write) suggestions.push("- No ESLint config file was found to rewrite.");
+    return applied;
+  }
+  const configContent = readFileSync(configPath, "utf8");
+  if (configContent.includes("@santi020k/eslint-config-") && !configContent.includes("frameworks:")) {
+    suggestions.push("- This config appears to import v1 framework packages; replace those imports with framework booleans.");
+  }
+  if (!write) return applied;
+  const result = migrateConfigContent(configContent);
+  if (result.changed) {
+    const backupPath = `${configPath}.bak`;
+    writeFileSync(backupPath, configContent);
+    writeFileSync(configPath, result.content);
+    const message = `Rewrote ${basename(configPath)} with v2 framework booleans: ${result.frameworks.join(", ")}. Original backed up to ${basename(backupPath)}.`;
+    applied.push(message);
+    suggestions.push(`- ${message}`);
   } else {
-    console.log("Usage: basic-eslint <init|update>");
+    suggestions.push("- No v1 framework imports were found to rewrite.");
   }
+  return applied;
+};
+const handleMigrate = (cwd = process.cwd(), write = false, json = false) => {
+  const configPath = getConfigPathIfPresent(cwd) ?? join(cwd, getDefaultConfigFilename(cwd));
+  const suggestions = [
+    "v1 to v2 migration suggestions:",
+    "- Install only @santi020k/eslint-config-basic for the public config API.",
+    "- Replace framework imports with bundled booleans such as frameworks: { react: true, next: true }.",
+    "- Remove app-level @santi020k/eslint-config-react/next/vue/etc. config package imports.",
+    "- Try eslintConfig() first; v2 auto-detects supported frameworks and integrations.",
+    "- Use basic-eslint explain to review what v2 detects before committing the migration."
+  ];
+  const applied = processConfigMigration(configPath, write, suggestions);
+  if (json) {
+    console.log(JSON.stringify({
+      applied,
+      configFile: existsSync(configPath) ? basename(configPath) : null,
+      suggestions: suggestions.slice(1),
+      title: suggestions[0],
+      write
+    }, null, 2));
+    return;
+  }
+  console.log(suggestions.join("\n"));
+};
+const dispatchCommand = (command, cwd, flags) => {
+  switch (command) {
+    case "docs": {
+      handleDocs(cwd);
+      break;
+    }
+    case "doctor": {
+      handleDoctor(cwd, flags.hasJson, flags.hasLiteInstall).catch((error) => {
+        console.error(`\u274C Failed to run doctor: ${String(error)}`);
+        process.exitCode = 1;
+      });
+      break;
+    }
+    case "explain": {
+      handleExplain(cwd, flags.hasJson);
+      break;
+    }
+    case "generate-skill": {
+      handleGenerateSkill(cwd, flags.hasForce, { check: flags.hasCheck, createAgentsMd: flags.hasCreate }).catch((error) => {
+        console.error(`\u274C Failed to generate skill files: ${String(error)}`);
+        process.exitCode = 1;
+      });
+      break;
+    }
+    case "init": {
+      handleInit(cwd, flags.hasCheck);
+      break;
+    }
+    case "inspect": {
+      handleInspect(cwd, flags.hasJson).catch((error) => {
+        console.error(`\u274C Failed to inspect project: ${String(error)}`);
+        process.exitCode = 1;
+      });
+      break;
+    }
+    case "migrate": {
+      handleMigrate(cwd, flags.hasWrite, flags.hasJson);
+      break;
+    }
+    case "update": {
+      handleUpdate(cwd);
+      break;
+    }
+    default: {
+      console.error(`Unknown command: ${command}`);
+      printUsage();
+      process.exitCode = 1;
+    }
+  }
+};
+const runCli = (argv = process.argv, cwd = process.cwd()) => {
+  const command = argv[2];
+  const isHelp = command === "--help" || command === "-h";
+  const isVersion = command === "--version" || command === "-v";
+  if (!command || isHelp) {
+    printUsage();
+    return;
+  }
+  if (isVersion) {
+    console.log(getCliVersion());
+    return;
+  }
+  dispatchCommand(command, cwd, {
+    hasCheck: argv.includes("--check"),
+    hasCreate: argv.includes("--create"),
+    hasForce: argv.includes("--force"),
+    hasJson: argv.includes("--json"),
+    hasLiteInstall: argv.includes("--lite-install"),
+    hasWrite: argv.includes("--write")
+  });
 };
 if (process.argv[1] && (process.argv[1] === fileURLToPath(import.meta.url) || process.argv[1].endsWith("cli.js") || process.argv[1].endsWith("cli.ts"))) {
-  run();
+  runCli();
 }
 export {
+  findDuplicateEslint,
+  handleDocs,
+  handleDoctor,
+  handleExplain,
   handleInit,
-  handleUpdate
+  handleInspect,
+  handleMigrate,
+  handleUpdate,
+  runCli
 };