@inspecto-dev/cli 0.2.0-alpha.0

package/src/detect/build-tool.ts

@@ -0,0 +1,123 @@
+// ============================================================
+// src/detect/build-tool.ts — Build tool detection (v1)
+//
+// v1 supported: Vite / Webpack / Rspack / esbuild / Rollup
+// Recognized but unsupported: Next.js / Nuxt / Remix / Astro / SvelteKit
+// ============================================================
+import path from 'node:path'
+import { exists, readJSON } from '../utils/fs.js'
+import type { BuildTool, BuildToolDetection } from '../types.js'
+
+interface PackageJSON {
+  dependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+}
+
+/** Supported build tools in v1 */
+const SUPPORTED_PATTERNS: { tool: BuildTool; files: string[]; label: string }[] = [
+  {
+    tool: 'vite',
+    files: ['vite.config.ts', 'vite.config.js', 'vite.config.mts', 'vite.config.mjs'],
+    label: 'Vite',
+  },
+  {
+    tool: 'rspack',
+    files: ['rspack.config.js', 'rspack.config.ts', 'rspack.config.mjs'],
+    label: 'Rspack',
+  },
+  {
+    tool: 'rsbuild',
+    files: ['rsbuild.config.js', 'rsbuild.config.ts', 'rsbuild.config.mjs'],
+    label: 'Rsbuild',
+  },
+  {
+    tool: 'webpack',
+    files: ['webpack.config.js', 'webpack.config.ts', 'webpack.config.mjs', 'webpack.config.cjs'],
+    label: 'Webpack',
+  },
+  {
+    tool: 'esbuild',
+    files: ['esbuild.config.js', 'esbuild.config.ts', 'esbuild.config.mjs'],
+    label: 'esbuild',
+  },
+  {
+    tool: 'rollup',
+    files: ['rollup.config.js', 'rollup.config.ts', 'rollup.config.mjs'],
+    label: 'Rollup',
+  },
+]
+
+/** Recognized but unsupported meta-frameworks — detect via dep + config file */
+const UNSUPPORTED_META: { name: string; dep: string; files: string[] }[] = [
+  { name: 'Next.js', dep: 'next', files: ['next.config.mjs', 'next.config.js', 'next.config.ts'] },
+  { name: 'Nuxt', dep: 'nuxt', files: ['nuxt.config.ts', 'nuxt.config.js'] },
+  { name: 'Remix', dep: '@remix-run/dev', files: ['remix.config.js', 'remix.config.ts'] },
+  { name: 'Astro', dep: 'astro', files: ['astro.config.mjs', 'astro.config.ts'] },
+  { name: 'SvelteKit', dep: '@sveltejs/kit', files: ['svelte.config.js', 'svelte.config.ts'] },
+]
+
+export interface BuildToolResult {
+  supported: BuildToolDetection[]
+  unsupported: string[]
+}
+
+/**
+ * Detect all build tools / meta-frameworks.
+ * Returns supported tools and recognized-but-unsupported meta-frameworks.
+ */
+export async function detectBuildTools(root: string): Promise<BuildToolResult> {
+  const supported: BuildToolDetection[] = []
+  const unsupported: string[] = []
+
+  // Detect supported build tools (by config file)
+  const pkg = await readJSON<PackageJSON>(path.join(root, 'package.json'))
+  const allDeps = { ...pkg?.dependencies, ...pkg?.devDependencies }
+
+  for (const pattern of SUPPORTED_PATTERNS) {
+    for (const file of pattern.files) {
+      if (await exists(path.join(root, file))) {
+        let isLegacyRspack = false
+        if (pattern.tool === 'rspack') {
+          const version = allDeps['@rspack/cli'] || allDeps['@rspack/core']
+          if (
+            version &&
+            (version.includes('0.3.') || version.includes('0.2.') || version.includes('0.1.'))
+          ) {
+            isLegacyRspack = true
+          }
+        }
+
+        supported.push({
+          tool: pattern.tool,
+          configPath: file,
+          label: `${pattern.label} (${file})${isLegacyRspack ? ' [Legacy]' : ''}`,
+          isLegacyRspack,
+        })
+        break // One match per tool
+      }
+    }
+  }
+
+  for (const meta of UNSUPPORTED_META) {
+    if (!(meta.dep in allDeps)) continue
+    for (const file of meta.files) {
+      if (await exists(path.join(root, file))) {
+        unsupported.push(meta.name)
+        break
+      }
+    }
+  }
+
+  return { supported, unsupported }
+}
+
+/**
+ * Determine which detection to use for injection.
+ */
+export function resolveInjectionTarget(
+  detections: BuildToolDetection[],
+): BuildToolDetection | null | 'ambiguous' {
+  if (detections.length === 0) return null
+  if (detections.length === 1) return detections[0]!
+  return 'ambiguous'
+}

package/src/detect/framework.ts

@@ -0,0 +1,65 @@
+// ============================================================
+// src/detect/framework.ts — Frontend framework detection
+//
+// v1 supported: React / Vue
+// Recognized but unsupported: Solid, Svelte, Angular, Preact, Lit
+// ============================================================
+import path from 'node:path'
+import { readJSON } from '../utils/fs.js'
+
+export type Framework = 'react' | 'vue'
+
+export interface FrameworkDetection {
+  supported: Framework[]
+  unsupported: { name: string; dep: string }[]
+}
+
+interface PackageJSON {
+  dependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+}
+
+/** Supported frameworks in v1 */
+const SUPPORTED_FRAMEWORKS: { framework: Framework; deps: string[] }[] = [
+  { framework: 'react', deps: ['react', 'react-dom'] },
+  { framework: 'vue', deps: ['vue'] },
+]
+
+/** Recognized but not supported in v1 — detect and warn */
+const UNSUPPORTED_FRAMEWORKS: { name: string; dep: string }[] = [
+  { name: 'Solid', dep: 'solid-js' },
+  { name: 'Svelte', dep: 'svelte' },
+  { name: 'Angular', dep: '@angular/core' },
+  { name: 'Preact', dep: 'preact' },
+  { name: 'Lit', dep: 'lit' },
+]
+
+/**
+ * Detect frontend frameworks.
+ * Returns both supported and recognized-but-unsupported frameworks.
+ */
+export async function detectFrameworks(root: string): Promise<FrameworkDetection> {
+  const pkg = await readJSON<PackageJSON>(path.join(root, 'package.json'))
+  if (!pkg) return { supported: [], unsupported: [] }
+
+  const allDeps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+  }
+
+  const supported: Framework[] = []
+  for (const { framework, deps } of SUPPORTED_FRAMEWORKS) {
+    if (deps.some(dep => dep in allDeps)) {
+      supported.push(framework)
+    }
+  }
+
+  const unsupported: { name: string; dep: string }[] = []
+  for (const fw of UNSUPPORTED_FRAMEWORKS) {
+    if (fw.dep in allDeps) {
+      unsupported.push(fw)
+    }
+  }
+
+  return { supported, unsupported }
+}

package/src/detect/ide.ts

@@ -0,0 +1,78 @@
+// ============================================================
+// src/detect/ide.ts — IDE detection (v1: VS Code only)
+//
+// Detects ALL known IDEs, but only VS Code is fully supported.
+// Others are recognized and surfaced as unsupported.
+// ============================================================
+import path from 'node:path'
+import { exists } from '../utils/fs.js'
+
+export type IDEDetection = {
+  ide: string
+  supported: boolean
+}
+
+export type IDEProbeResult = {
+  detected: IDEDetection[]
+}
+
+const SUPPORTED_IDE = 'vscode'
+
+/**
+ * Detect all installed IDEs based on directory artifacts and environment.
+ */
+export async function detectIDE(root: string): Promise<IDEProbeResult> {
+  const detected: Map<string, IDEDetection> = new Map()
+
+  // 1. Check Terminal Environment (Highest confidence for current session)
+
+  // Cursor
+  if (process.env.CURSOR_TRACE_DIR || process.env.CURSOR_CHANNEL) {
+    detected.set('Cursor', { ide: 'Cursor', supported: false })
+  }
+
+  // Trae
+  if (
+    process.env.TRAE_APP_DIR ||
+    process.env.__CFBundleIdentifier === 'com.byteocean.trae' ||
+    process.env.COCO_IDE_PLUGIN_TYPE === 'Trae' ||
+    (process.env.npm_config_user_agent && process.env.npm_config_user_agent.includes('trae'))
+  ) {
+    detected.set('Trae', { ide: 'Trae', supported: false })
+  }
+
+  // Zed
+  if (process.env.ZED_TERM) {
+    detected.set('Zed', { ide: 'Zed', supported: false })
+  }
+
+  // VS Code
+  // Must ensure we haven't already flagged it as Trae/Cursor since they share this variable
+  if (process.env.TERM_PROGRAM === 'vscode') {
+    if (!detected.has('Trae') && !detected.has('Cursor')) {
+      detected.set('vscode', { ide: SUPPORTED_IDE, supported: true })
+    }
+  }
+
+  // 2. Check Directory Artifacts (Indicates project has been opened in these IDEs)
+  if (await exists(path.join(root, '.trae'))) {
+    detected.set('Trae', { ide: 'Trae', supported: false })
+  }
+  if (await exists(path.join(root, '.cursor'))) {
+    detected.set('Cursor', { ide: 'Cursor', supported: false })
+  }
+  if (await exists(path.join(root, '.vscode'))) {
+    // Only add vscode if it wasn't already caught by terminal,
+    // or if the terminal is something else but .vscode exists.
+    if (!detected.has('vscode')) {
+      detected.set('vscode', { ide: SUPPORTED_IDE, supported: true })
+    }
+  }
+  if (await exists(path.join(root, '.idea'))) {
+    detected.set('JetBrains IDE', { ide: 'JetBrains IDE', supported: false })
+  }
+
+  return {
+    detected: Array.from(detected.values()),
+  }
+}

package/src/detect/package-manager.ts

@@ -0,0 +1,56 @@
+// ============================================================
+// src/detect/package-manager.ts — Lockfile-based PM detection
+// ============================================================
+import path from 'node:path'
+import { exists } from '../utils/fs.js'
+import type { PackageManager } from '../types.js'
+
+/**
+ * Detect the package manager by checking lockfile presence.
+ * Priority: bun > pnpm > yarn > npm (fallback)
+ */
+export async function detectPackageManager(root: string): Promise<PackageManager> {
+  const checks: [string, PackageManager][] = [
+    ['bun.lockb', 'bun'],
+    ['bun.lock', 'bun'],
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['yarn.lock', 'yarn'],
+    ['package-lock.json', 'npm'],
+  ]
+
+  for (const [file, pm] of checks) {
+    if (await exists(path.join(root, file))) {
+      return pm
+    }
+  }
+
+  return 'npm' // fallback
+}
+
+/** Get the install command for a package manager */
+export function getInstallCommand(pm: PackageManager, pkg: string): string {
+  switch (pm) {
+    case 'bun':
+      return `bun add -D ${pkg}`
+    case 'pnpm':
+      return `pnpm add -D ${pkg}`
+    case 'yarn':
+      return `yarn add -D ${pkg}`
+    case 'npm':
+      return `npm install -D ${pkg}`
+  }
+}
+
+/** Get the uninstall command for a package manager */
+export function getUninstallCommand(pm: PackageManager, pkg: string): string {
+  switch (pm) {
+    case 'bun':
+      return `bun remove ${pkg}`
+    case 'pnpm':
+      return `pnpm remove ${pkg}`
+    case 'yarn':
+      return `yarn remove ${pkg}`
+    case 'npm':
+      return `npm uninstall ${pkg}`
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { init } from './commands/init.js'
+export { doctor } from './commands/doctor.js'
+export { teardown } from './commands/teardown.js'
+export type { InitOptions, BuildTool, PackageManager, InstallLock } from './types.js'
+export type { Framework } from './detect/framework.js'

package/src/inject/ast-injector.ts

@@ -0,0 +1,300 @@
+// ============================================================
+// src/inject/ast-injector.ts — Safe plugin injection (v1)
+//
+// v1 scope: Standard `plugins: [...]` array injection.
+// Covers Vite / Webpack / Rspack / esbuild / Rollup configs.
+// Meta-framework special strategies (Next.js, Nuxt) deferred.
+//
+// Safety protocol:
+//   1. Backup original file (.bak)
+//   2. Idempotency check (skip if already injected)
+//   3. Attempt regex-based injection
+//   4. Basic syntax validation
+//   5. Graceful degradation on any failure
+// ============================================================
+
+import path from 'node:path'
+import { exists, readFile, writeFile, copyFile } from '../utils/fs.js'
+import { log } from '../utils/logger.js'
+import type { BuildTool, BuildToolDetection, Mutation } from '../types.js'
+
+// ---- Import & plugin expression per build tool ----
+
+const IMPORT_MAP: Record<BuildTool, string> = {
+  vite: `import { vitePlugin as inspecto } from '@inspecto-dev/plugin'`,
+  webpack: `import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'`,
+  rspack: `import { rspackPlugin as inspecto } from '@inspecto-dev/plugin'`,
+  rsbuild: `import { rspackPlugin as inspecto } from '@inspecto-dev/plugin'`,
+  esbuild: `import { esbuildPlugin as inspecto } from '@inspecto-dev/plugin'`,
+  rollup: `import { rollupPlugin as inspecto } from '@inspecto-dev/plugin'`,
+}
+
+function getImportStatement(tool: BuildTool, isLegacyRspack?: boolean): string {
+  if (tool === 'rspack' && isLegacyRspack) {
+    return `import { rspackPlugin as inspecto } from '@inspecto-dev/plugin/legacy/rspack'`
+  }
+  return IMPORT_MAP[tool]
+}
+
+function getPluginExpression(isLegacyRspack?: boolean): string {
+  if (isLegacyRspack) {
+    return `process.env.NODE_ENV !== 'production' && inspecto({
+      pathType: 'absolute',
+      escapeTags: ['Transition', 'AnimatePresence'],
+    }) as any`
+  }
+  return `process.env.NODE_ENV !== 'production' && inspecto()`
+}
+
+// ---- Manual fallback instructions ----
+
+function printManualInstructions(
+  tool: BuildTool,
+  configPath: string,
+  reason: string,
+  isLegacyRspack?: boolean,
+) {
+  const isRsbuild = tool === 'rsbuild'
+
+  log.warn(`Could not safely auto-inject into ${configPath}`)
+  log.hint(`(reason: ${reason})`)
+  log.blank()
+  log.hint('Please add the following manually:')
+
+  if (isRsbuild) {
+    log.codeBlock([
+      getImportStatement(tool, isLegacyRspack),
+      '',
+      '// Add to tools.rspack:',
+      `tools: {`,
+      `  rspack: {`,
+      `    plugins: [`,
+      `      ${getPluginExpression(isLegacyRspack)},`,
+      `    ]`,
+      `  }`,
+      `}`,
+    ])
+  } else {
+    log.codeBlock([
+      getImportStatement(tool, isLegacyRspack),
+      '',
+      '// Add to your plugins array:',
+      `plugins: [`,
+      `  ${getPluginExpression(isLegacyRspack)},`,
+      `  ...otherPlugins`,
+      `].filter(Boolean)`,
+    ])
+  }
+}
+
+// ---- Injection helpers ----
+
+/** Check if inspecto is already injected (idempotency). */
+function isAlreadyInjected(content: string): boolean {
+  return (
+    content.includes('@inspecto-dev/plugin') ||
+    content.includes('inspecto()') ||
+    content.includes('aiDevInspector')
+  ) // Legacy support
+}
+
+/** Inject import statement after the last existing import. */
+function injectImport(content: string, importStmt: string): string {
+  const importRegex = /^import\s.+$/gm
+  let lastImportEnd = 0
+  let match: RegExpExecArray | null
+
+  while ((match = importRegex.exec(content)) !== null) {
+    const lineEnd = content.indexOf('\n', match.index)
+    if (lineEnd > lastImportEnd) {
+      lastImportEnd = lineEnd
+    }
+  }
+
+  // Also handle CJS require patterns
+  if (lastImportEnd === 0) {
+    const requireRegex = /^(?:const|let|var)\s.+=\s*require\(.+\).*$/gm
+    while ((match = requireRegex.exec(content)) !== null) {
+      const lineEnd = content.indexOf('\n', match.index)
+      if (lineEnd > lastImportEnd) {
+        lastImportEnd = lineEnd
+      }
+    }
+  }
+
+  if (lastImportEnd > 0) {
+    return content.slice(0, lastImportEnd) + '\n' + importStmt + content.slice(lastImportEnd)
+  }
+
+  // No imports found, add at the beginning
+  return importStmt + '\n\n' + content
+}
+
+/**
+ * Core injection strategy.
+ * For most tools: find `plugins: [` and insert after `[`.
+ * For rsbuild: find `tools: { rspack: { plugins: [` or try to add it.
+ */
+function injectIntoPluginsArray(content: string, detection: BuildToolDetection): string | null {
+  const tool = detection.tool
+  if (tool === 'rsbuild') {
+    // rsbuild needs to inject into tools.rspack.plugins or tools.rspack(config, { appendPlugins })
+    // Due to the complexity of rsbuild config, we'll try a simple regex for `tools: { rspack: { plugins: [`
+    // If that fails, we fallback to manual instructions which are explicitly for rsbuild.
+
+    // Check if tools.rspack exists
+    if (!content.includes('tools:') && !content.includes('rspack:')) {
+      // Very basic config, we can try to inject before the closing brace of defineConfig
+      const exportRegex = /(export default defineConfig\(\{)/
+      const match = exportRegex.exec(content)
+      if (match) {
+        const insertPos = match.index + match[0].length
+        const pluginExpr = `\n  tools: {\n    rspack: {\n      plugins: [\n        ${getPluginExpression(detection.isLegacyRspack)}\n      ]\n    }\n  },`
+        return content.slice(0, insertPos) + pluginExpr + content.slice(insertPos)
+      }
+    }
+
+    // Otherwise it's too complex for simple regex, force manual degradation
+    return null
+  }
+
+  const pluginsRegex = /(plugins\s*:\s*\[)/
+  const match = pluginsRegex.exec(content)
+  if (!match) return null
+
+  const insertPos = match.index + match[0].length
+  const pluginExpr = `\n    ${getPluginExpression(detection.isLegacyRspack)},`
+
+  return content.slice(0, insertPos) + pluginExpr + content.slice(insertPos)
+}
+
+/** Basic bracket-balance validation. */
+function validateBrackets(content: string): boolean {
+  const openBraces = (content.match(/\{/g) || []).length
+  const closeBraces = (content.match(/\}/g) || []).length
+  const openBrackets = (content.match(/\[/g) || []).length
+  const closeBrackets = (content.match(/\]/g) || []).length
+
+  return Math.abs(openBraces - closeBraces) <= 1 && Math.abs(openBrackets - closeBrackets) <= 1
+}
+
+// ---- Main injection orchestrator ----
+
+export interface InjectionResult {
+  success: boolean
+  mutations: Mutation[]
+  failureReason?: string
+}
+
+export async function injectPlugin(
+  root: string,
+  detection: BuildToolDetection,
+  dryRun: boolean,
+): Promise<InjectionResult> {
+  const configPath = path.join(root, detection.configPath)
+  const backupPath = configPath + '.bak'
+  const mutations: Mutation[] = []
+
+  // Step 1: Read config file
+  const content = await readFile(configPath)
+  if (!content) {
+    printManualInstructions(
+      detection.tool,
+      detection.configPath,
+      'config file not readable',
+      detection.isLegacyRspack,
+    )
+    return { success: false, mutations, failureReason: 'config file not readable' }
+  }
+
+  // Step 2: Idempotency check
+  if (isAlreadyInjected(content)) {
+    log.success(`Plugin already injected in ${detection.configPath} (skipped)`)
+
+    // We still want to record the mutation so teardown knows how to clean it up
+    // However, if the user manually added it, we shouldn't overwrite their code with a .bak on teardown.
+    // To handle this, we register a special 'plugin_injected' mutation instead of 'file_modified',
+    // which tells teardown to use AST-removal instead of .bak restoration (if we implement it)
+    // For now, we will assume if it's already there and a .bak exists, we track it for restoration.
+    if (await exists(backupPath)) {
+      mutations.push({
+        type: 'file_modified',
+        path: detection.configPath,
+        backup: detection.configPath + '.bak',
+        description: 'Previously injected inspecto() plugin',
+      })
+    } else {
+      // If no backup exists, we just mark it as modified but without backup
+      // This tells teardown it was touched but cannot be safely rolled back
+      mutations.push({
+        type: 'file_modified',
+        path: detection.configPath,
+        description: 'Previously injected inspecto() plugin (no backup)',
+      })
+    }
+
+    return { success: true, mutations }
+  }
+
+  // Step 3: Backup
+  if (!dryRun) {
+    await copyFile(configPath, backupPath)
+    mutations.push({
+      type: 'file_modified',
+      path: detection.configPath,
+      backup: detection.configPath + '.bak',
+      description: 'Injected inspecto() plugin',
+    })
+  }
+  log.success(`Backed up ${detection.configPath} → ${detection.configPath}.bak`)
+
+  // Step 4: Inject into plugins array
+  const injected = injectIntoPluginsArray(content, detection)
+  if (!injected) {
+    printManualInstructions(
+      detection.tool,
+      detection.configPath,
+      'could not locate plugins array — file may use dynamic config, function wrapper, or non-standard export',
+      detection.isLegacyRspack,
+    )
+    return {
+      success: false,
+      mutations,
+      failureReason: 'could not locate plugins array',
+    }
+  }
+
+  // Step 5: Inject import statement
+  const importStmt = getImportStatement(detection.tool, detection.isLegacyRspack)
+  const modifiedContent = injectImport(injected, importStmt)
+
+  // Step 6: Bracket-balance validation
+  if (!validateBrackets(modifiedContent)) {
+    log.error('Syntax validation failed after injection')
+    if (!dryRun) {
+      await copyFile(backupPath, configPath)
+      log.success(`Restored ${detection.configPath} from backup`)
+    }
+    printManualInstructions(
+      detection.tool,
+      detection.configPath,
+      'injection produced unbalanced brackets',
+      detection.isLegacyRspack,
+    )
+    return {
+      success: false,
+      mutations: [], // Rolled back
+      failureReason: 'injection produced invalid syntax',
+    }
+  }
+
+  // Step 7: Write
+  if (dryRun) {
+    log.dryRun(`Would inject plugin into ${detection.configPath}`)
+  } else {
+    await writeFile(configPath, modifiedContent)
+    log.success(`Injected plugin into ${detection.configPath}`)
+  }
+
+  return { success: true, mutations }
+}