@inspecto-dev/cli 0.2.0-alpha.0 → 0.2.0-alpha.2

package/src/inject/extension.ts

@@ -9,7 +9,6 @@
 //   Level 4: Print manual installation instructions
 // ============================================================
 
-import path from 'node:path'
 import { which, run, shell } from '../utils/exec.js'
 import { exists } from '../utils/fs.js'
 import { log } from '../utils/logger.js'
@@ -67,51 +66,67 @@ async function tryOpenURI(uri: string): Promise<boolean> {
 /**
  * Attempt to install the VS Code extension using waterfall degradation.
  */
-export async function installExtension(dryRun: boolean): Promise<Mutation | null> {
+export async function installExtension(dryRun: boolean, ide?: string): Promise<Mutation | null> {
   if (dryRun) {
     log.dryRun('Would attempt to install VS Code extension')
     return null
   }
 
-  // Level 1: Direct `code` command
-  if (await which('code')) {
-    try {
-      await run('code', ['--install-extension', EXTENSION_ID])
-      log.success('VS Code extension installed via CLI')
-      return { type: 'extension_installed', id: EXTENSION_ID }
-    } catch {
-      // Fall through to next level
+  const isVSCode = !ide || ide === 'vscode'
+
+  if (isVSCode) {
+    // Level 1: Direct `code` command
+    if (await which('code')) {
+      try {
+        await run('code', ['--install-extension', EXTENSION_ID])
+        log.success('VS Code extension installed via CLI')
+        return { type: 'extension_installed', id: EXTENSION_ID }
+      } catch {
+        // Fall through to next level
+      }
     }
-  }
 
-  // Level 2: Find VS Code binary at known paths
-  const codePath = await findVSCodeBinary()
-  if (codePath) {
-    try {
-      await run(codePath, ['--install-extension', EXTENSION_ID])
-      log.success('VS Code extension installed via binary path')
-      log.info('Tip: Add "code" to your PATH to help Inspecto detect other AI tools in the future')
-      return { type: 'extension_installed', id: EXTENSION_ID }
-    } catch {
-      // Fall through to next level
+    // Level 2: Find VS Code binary at known paths
+    const codePath = await findVSCodeBinary()
+    if (codePath) {
+      try {
+        await run(codePath, ['--install-extension', EXTENSION_ID])
+        log.success('VS Code extension installed via binary path')
+        log.info(
+          'Tip: Add "code" to your PATH to help Inspecto detect other AI tools in the future',
+        )
+        return { type: 'extension_installed', id: EXTENSION_ID }
+      } catch {
+        // Fall through to next level
+      }
+    }
+
+    // Level 3: URI scheme
+    const uri = `vscode:extension/${EXTENSION_ID}`
+    if (await tryOpenURI(uri)) {
+      log.warn('Opened extension page in VS Code')
+      log.hint('Please click "Install" in the opened VS Code window to complete setup.')
+      return { type: 'extension_installed', id: EXTENSION_ID, manual_action_required: true }
     }
-  }
 
-  // Level 3: URI scheme
-  const uri = `vscode:extension/${EXTENSION_ID}`
-  if (await tryOpenURI(uri)) {
-    log.warn('Opened extension page in VS Code')
-    log.hint('Please click "Install" in the opened VS Code window to complete setup.')
-    return { type: 'extension_installed', id: EXTENSION_ID, manual_action_required: true }
+    // Level 4: Manual fallback
+    log.warn('Could not auto-install VS Code extension')
+    log.hint('Please install it manually to enable Inspector features:')
+    log.hint('  1. Open VS Code')
+    log.hint('  2. Press Ctrl+Shift+X (or Cmd+Shift+X)')
+    log.hint('  3. Search for "Inspecto"')
+    log.hint(`  Or visit: https://marketplace.visualstudio.com/items?itemName=${EXTENSION_ID}`)
+    return null
   }
 
-  // Level 4: Manual fallback
-  log.warn('Could not auto-install VS Code extension')
+  // Other IDEs: Prompt to install via VSIX
+  log.warn(`Could not auto-install extension for ${ide}`)
   log.hint('Please install it manually to enable Inspector features:')
-  log.hint('  1. Open VS Code')
-  log.hint('  2. Press Ctrl+Shift+X (or Cmd+Shift+X)')
-  log.hint('  3. Search for "Inspecto"')
-  log.hint(`  Or visit: https://marketplace.visualstudio.com/items?itemName=${EXTENSION_ID}`)
+  log.hint('  1. Download the latest .vsix file from Inspecto releases')
+  log.hint(`  2. Open ${ide}`)
+  log.hint('  3. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P)')
+  log.hint('  4. Type and select "Extensions: Install from VSIX..."')
+  log.hint('  5. Select the downloaded .vsix file')
   return null
 }
 

package/src/inject/gitignore.ts

@@ -34,7 +34,7 @@ export async function updateGitignore(
     if (!dryRun) {
       await writeFile(gitignorePath, content)
     }
-    log.success('Updated .gitignore: .inspecto/settings.json is now trackable')
+    log.success('Updated .gitignore: .inspecto/ is no longer fully ignored')
     return
   }
 

package/src/inject/strategies/esbuild.ts

@@ -0,0 +1,35 @@
+import type { InjectStrategy, InjectOptions } from './types.js'
+import type { BuildTool, BuildToolDetection } from '../../types.js'
+
+export class EsbuildStrategy implements InjectStrategy {
+  name = 'esbuild'
+
+  supports(tool: BuildTool): boolean {
+    return tool === 'esbuild'
+  }
+
+  inject(options: InjectOptions): void {
+    throw new Error('Esbuild requires manual plugin configuration')
+  }
+
+  getManualInstructions(detection: BuildToolDetection, reason: string): string[] {
+    return [
+      `1. Update your esbuild config (${detection.configPath}):`,
+      `import { esbuildPlugin as inspecto } from '@inspecto-dev/plugin'`,
+      '',
+      '// Add to your plugins array:',
+      `plugins: [`,
+      `  process.env.NODE_ENV !== 'production' && inspecto(),`,
+      `  ...otherPlugins`,
+      `].filter(Boolean)`,
+      '',
+      '2. Initialize the client in your app entry (e.g., main.js / index.js):',
+      `import { mountInspector } from '@inspecto-dev/core'`,
+      '',
+      '// Call this before your app renders',
+      `if (process.env.NODE_ENV !== 'production') {`,
+      `  mountInspector()`,
+      `}`,
+    ]
+  }
+}

package/src/inject/strategies/index.ts

@@ -0,0 +1,16 @@
+import { ViteStrategy } from './vite.js'
+import { WebpackStrategy } from './webpack.js'
+import { RspackStrategy } from './rspack.js'
+import { RsbuildStrategy } from './rsbuild.js'
+import { EsbuildStrategy } from './esbuild.js'
+import { RollupStrategy } from './rollup.js'
+import type { InjectStrategy } from './types.js'
+
+export const STRATEGIES: InjectStrategy[] = [
+  new ViteStrategy(),
+  new WebpackStrategy(),
+  new RspackStrategy(),
+  new RsbuildStrategy(),
+  new EsbuildStrategy(),
+  new RollupStrategy(),
+]

package/src/inject/strategies/rollup.ts

@@ -0,0 +1,35 @@
+import type { InjectStrategy, InjectOptions } from './types.js'
+import type { BuildTool, BuildToolDetection } from '../../types.js'
+
+export class RollupStrategy implements InjectStrategy {
+  name = 'Rollup'
+
+  supports(tool: BuildTool): boolean {
+    return tool === 'rollup'
+  }
+
+  inject(options: InjectOptions): void {
+    throw new Error('Rollup requires manual plugin configuration')
+  }
+
+  getManualInstructions(detection: BuildToolDetection, reason: string): string[] {
+    return [
+      `1. Update your rollup config (${detection.configPath}):`,
+      `import { rollupPlugin as inspecto } from '@inspecto-dev/plugin'`,
+      '',
+      '// Add to your plugins array:',
+      `plugins: [`,
+      `  process.env.NODE_ENV !== 'production' && inspecto(),`,
+      `  ...otherPlugins`,
+      `].filter(Boolean)`,
+      '',
+      '2. Initialize the client in your app entry (e.g., main.js / index.js):',
+      `import { mountInspector } from '@inspecto-dev/core'`,
+      '',
+      '// Call this before your app renders',
+      `if (process.env.NODE_ENV !== 'production') {`,
+      `  mountInspector()`,
+      `}`,
+    ]
+  }
+}

package/src/inject/strategies/rsbuild.ts

@@ -0,0 +1,29 @@
+import type { InjectStrategy, InjectOptions } from './types.js'
+import type { BuildTool, BuildToolDetection } from '../../types.js'
+
+export class RsbuildStrategy implements InjectStrategy {
+  name = 'Rsbuild'
+
+  supports(tool: BuildTool): boolean {
+    return tool === 'rsbuild'
+  }
+
+  inject(options: InjectOptions): void {
+    throw new Error('Rsbuild requires manual plugin configuration due to nested structure')
+  }
+
+  getManualInstructions(detection: BuildToolDetection, reason: string): string[] {
+    return [
+      `import { rspackPlugin as inspecto } from '@inspecto-dev/plugin'`,
+      '',
+      '// Add to tools.rspack:',
+      `tools: {`,
+      `  rspack: {`,
+      `    plugins: [`,
+      `      process.env.NODE_ENV !== 'production' && inspecto(),`,
+      `    ]`,
+      `  }`,
+      `}`,
+    ]
+  }
+}

package/src/inject/strategies/rspack.ts

@@ -0,0 +1,34 @@
+import type { InjectStrategy, InjectOptions } from './types.js'
+import type { BuildTool, BuildToolDetection } from '../../types.js'
+
+export class RspackStrategy implements InjectStrategy {
+  name = 'Rspack'
+
+  supports(tool: BuildTool): boolean {
+    return tool === 'rspack'
+  }
+
+  inject(options: InjectOptions): void {
+    throw new Error('Rspack requires manual plugin configuration')
+  }
+
+  getManualInstructions(detection: BuildToolDetection, reason: string): string[] {
+    const importPkg = detection.isLegacyRspack
+      ? '@inspecto-dev/plugin/legacy/rspack'
+      : '@inspecto-dev/plugin'
+
+    const pluginCall = detection.isLegacyRspack
+      ? `process.env.NODE_ENV !== 'production' && inspecto({\n      pathType: 'absolute',\n      escapeTags: ['Transition', 'AnimatePresence'],\n    })`
+      : `process.env.NODE_ENV !== 'production' && inspecto()`
+
+    return [
+      `import { rspackPlugin as inspecto } from '${importPkg}'`,
+      '',
+      '// Add to your plugins array:',
+      `plugins: [`,
+      `  ${pluginCall},`,
+      `  ...otherPlugins`,
+      `].filter(Boolean)`,
+    ]
+  }
+}

package/src/inject/strategies/types.ts

@@ -0,0 +1,35 @@
+import type { ProxifiedModule } from 'magicast'
+import type { BuildTool, BuildToolDetection } from '../../types.js'
+
+export interface InjectOptions {
+  /** The magicast proxified module */
+  mod: ProxifiedModule<any>
+  /** The build tool detection result */
+  detection: BuildToolDetection
+}
+
+export interface InjectStrategy {
+  /** Name of the strategy for logging */
+  name: string
+
+  /** Check if this strategy can handle the given build tool */
+  supports(tool: BuildTool): boolean
+
+  /**
+   * Perform the AST injection.
+   * Note: Some tools (like webpack) might throw an error here to trigger manual fallback
+   * because AST manipulation for them is too complex/brittle in v1.
+   */
+  inject(options: InjectOptions): void
+
+  /**
+   * Perform the AST removal (for teardown).
+   * Returns true if successful, false if it couldn't be removed automatically.
+   */
+  remove?(options: InjectOptions): boolean
+
+  /**
+   * Return manual fallback instructions if automatic injection fails or is unsupported.
+   */
+  getManualInstructions(detection: BuildToolDetection, reason: string): string[]
+}

package/src/inject/strategies/vite.ts

@@ -0,0 +1,30 @@
+import { addVitePlugin } from 'magicast/helpers'
+import type { InjectStrategy, InjectOptions } from './types.js'
+import type { BuildTool, BuildToolDetection } from '../../types.js'
+
+export class ViteStrategy implements InjectStrategy {
+  name = 'Vite'
+
+  supports(tool: BuildTool): boolean {
+    return tool === 'vite'
+  }
+
+  inject({ mod, detection }: InjectOptions): void {
+    addVitePlugin(mod, {
+      from: '@inspecto-dev/plugin',
+      constructor: 'vitePlugin',
+    })
+  }
+
+  getManualInstructions(detection: BuildToolDetection, reason: string): string[] {
+    return [
+      `import { vitePlugin as inspecto } from '@inspecto-dev/plugin'`,
+      '',
+      '// Add to your plugins array:',
+      `plugins: [`,
+      `  process.env.NODE_ENV !== 'production' && inspecto(),`,
+      `  ...otherPlugins`,
+      `].filter(Boolean)`,
+    ]
+  }
+}

package/src/inject/strategies/webpack.ts

@@ -0,0 +1,36 @@
+import type { InjectStrategy, InjectOptions } from './types.js'
+import type { BuildTool, BuildToolDetection } from '../../types.js'
+
+export class WebpackStrategy implements InjectStrategy {
+  name = 'Webpack'
+
+  supports(tool: BuildTool): boolean {
+    return tool === 'webpack'
+  }
+
+  inject(options: InjectOptions): void {
+    // AST manipulation for Webpack configs (often CommonJS or complex objects) is brittle in v1
+    throw new Error('Webpack requires manual plugin configuration')
+  }
+
+  getManualInstructions(detection: BuildToolDetection, reason: string): string[] {
+    const importPkg = detection.isLegacyWebpack
+      ? '@inspecto-dev/plugin/legacy/webpack4'
+      : '@inspecto-dev/plugin'
+    const pluginName = detection.isLegacyWebpack ? 'webpack4Plugin' : 'webpackPlugin'
+
+    const pluginCall = detection.isLegacyWebpack
+      ? `process.env.NODE_ENV !== 'production' && inspecto({\n      pathType: 'absolute',\n      escapeTags: ['Transition', 'AnimatePresence'],\n    })`
+      : `process.env.NODE_ENV !== 'production' && inspecto()`
+
+    return [
+      `import { ${pluginName} as inspecto } from '${importPkg}'`,
+      '',
+      '// Add to your plugins array:',
+      `plugins: [`,
+      `  ${pluginCall},`,
+      `  ...otherPlugins`,
+      `].filter(Boolean)`,
+    ]
+  }
+}

package/src/instructions.ts

@@ -0,0 +1,55 @@
+import { log } from './utils/logger.js'
+
+export function printNuxtManualInstructions() {
+  log.blank()
+  log.hint('To enable Inspecto in Nuxt, update your nuxt.config.ts:')
+  console.log(`\x1b[36m
+  import { vitePlugin as inspecto } from '@inspecto-dev/plugin'
+  export default defineNuxtConfig({
+    vite: {
+      plugins: [inspecto()]
+    }
+  })
+\x1b[0m`)
+  log.hint('And create a Nuxt plugin at plugins/inspecto.client.ts:')
+  console.log(`\x1b[36m
+  export default defineNuxtPlugin(() => {
+    if (import.meta.dev) {
+      import('@inspecto-dev/core').then(({ mountInspector }) => {
+        mountInspector()
+      })
+    }
+  })
+\x1b[0m`)
+}
+
+export function printNextJsManualInstructions() {
+  log.blank()
+  log.hint('To enable Inspecto in Next.js, update your next.config.mjs:')
+  console.log(`\x1b[36m
+  import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'
+  const nextConfig = {
+    webpack: (config, { dev, isServer }) => {
+      if (dev && !isServer) config.plugins.push(inspecto())
+      return config
+    }
+  }
+  export default nextConfig
+\x1b[0m`)
+  log.hint('And initialize the client dynamically in your app/layout.tsx (or pages/_app.tsx):')
+  console.log(`\x1b[36m
+  'use client'
+  import { useEffect } from 'react'
+
+  export default function RootLayout({ children }) {
+    useEffect(() => {
+      if (process.env.NODE_ENV !== 'production') {
+        import('@inspecto-dev/core').then(({ mountInspector }) => {
+          mountInspector({ serverUrl: 'http://127.0.0.1:5678' })
+        })
+      }
+    }, [])
+    return <html><body>{children}</body></html>
+  }
+\x1b[0m`)
+}

package/src/prompts.ts

@@ -0,0 +1,115 @@
+import prompts from 'prompts'
+import { log } from './utils/logger.js'
+import type { ProviderDetection } from './detect/provider.js'
+import type { BuildToolDetection } from './types.js'
+
+/**
+ * Interactive prompt for IDE choice.
+ */
+export async function promptIDEChoice(
+  detections: { ide: string; supported: boolean }[],
+): Promise<{ ide: string; supported: boolean } | null> {
+  if (!process.stdin.isTTY) {
+    log.warn('Multiple IDEs detected but stdin is not interactive')
+    log.hint(`Using: ${detections[0]!.ide} (first match)`)
+    return detections[0]!
+  }
+
+  const { choice } = await prompts({
+    type: 'select',
+    name: 'choice',
+    message: 'Detected multiple IDEs, please choose one:',
+    choices: detections.map((d, i) => ({
+      title: `${d.ide} ${d.supported ? '(supported)' : '(unsupported/limited)'}`,
+      value: i,
+    })),
+  })
+
+  if (choice === undefined) return null
+  return detections[choice]!
+}
+
+/**
+ * Interactive prompt for AI tool choice.
+ */
+export async function promptProviderChoice(
+  detections: ProviderDetection[],
+): Promise<ProviderDetection | null> {
+  if (!process.stdin.isTTY) {
+    log.warn('Multiple AI tools detected but stdin is not interactive')
+    log.hint(`Using: ${detections[0]!.label} (first match)`)
+    return detections[0]!
+  }
+
+  const { choice } = await prompts({
+    type: 'select',
+    name: 'choice',
+    message: 'Detected multiple providers, please choose one:',
+    choices: detections.map((d, i) => {
+      const modeLabels = d.providerModes.map(mode =>
+        mode === 'extension' ? 'VS Code Extension' : 'Terminal CLI',
+      )
+      const modeStr = modeLabels.join(' & ')
+      return {
+        title: `${d.label} ${d.supported ? `(supported ${modeStr})` : '(unsupported/limited)'}`,
+        value: i,
+      }
+    }),
+  })
+
+  if (choice === undefined) return null
+  return detections[choice]!
+}
+
+/**
+ * Interactive prompt for Build Tool Config choice.
+ */
+export async function promptConfigChoice(
+  detections: BuildToolDetection[],
+): Promise<BuildToolDetection | null> {
+  if (!process.stdin.isTTY) {
+    log.warn('Multiple config files detected but stdin is not interactive')
+    log.hint(`Using: ${detections[0]!.label} (first match)`)
+    return detections[0]!
+  }
+
+  const choices = detections.map((d, i) => ({
+    title: d.label,
+    value: i,
+  }))
+
+  choices.push({
+    title: "Skip (I'll configure manually)",
+    value: -1,
+  })
+
+  const { choice } = await prompts({
+    type: 'select',
+    name: 'choice',
+    message: 'Detected multiple build tool configs, please choose one to inject:',
+    choices,
+  })
+
+  if (choice === undefined || choice === -1) return null
+  return detections[choice]!
+}
+
+/**
+ * Interactive prompt for continuing with unsupported frameworks.
+ */
+export async function promptUnsupportedFrameworkContinue(): Promise<boolean> {
+  if (!process.stdin.isTTY) {
+    log.error('Unsupported framework detected in non-interactive environment.')
+    log.hint('Use --force to skip this check and continue anyway.')
+    return false
+  }
+
+  const { confirm } = await prompts({
+    type: 'confirm',
+    name: 'confirm',
+    message: 'Inspecto may not work properly. Do you want to continue anyway?',
+    initial: false,
+  })
+
+  return !!confirm
+}

package/src/types.ts

@@ -16,6 +16,8 @@ export interface BuildToolDetection {
   label: string
   /** Whether this is a legacy rspack version (< 0.4.0) */
   isLegacyRspack?: boolean
+  /** Whether this is Webpack 4.x */
+  isLegacyWebpack?: boolean
 }
 
 /** Options passed to `inspecto init` */
@@ -23,9 +25,10 @@ export interface InitOptions {
   shared: boolean
   skipInstall: boolean
   dryRun: boolean
-  prefer?: string
+  provider?: string
   noExtension: boolean
   packages?: string[]
+  force: boolean
 }
 
 /** A single mutation recorded in install.lock */

package/tests/ide.test.ts

@@ -23,7 +23,7 @@ describe('detectIDE', () => {
     vi.mocked(fsUtils.exists).mockResolvedValue(false)
 
     const result = await detectIDE('/mock/root')
-    expect(result.detected).toEqual([{ ide: 'Trae', supported: false }])
+    expect(result.detected).toEqual([{ ide: 'trae', supported: true }])
   })
 
   it('detects Cursor from environment variables', async () => {
@@ -31,7 +31,7 @@ describe('detectIDE', () => {
     vi.mocked(fsUtils.exists).mockResolvedValue(false)
 
     const result = await detectIDE('/mock/root')
-    expect(result.detected).toEqual([{ ide: 'Cursor', supported: false }])
+    expect(result.detected).toEqual([{ ide: 'cursor', supported: true }])
   })
 
   it('detects VS Code from environment variables without false positives', async () => {
@@ -89,6 +89,6 @@ describe('detectIDE', () => {
 
     const result = await detectIDE('/mock/root')
     // VS Code shouldn't be added since it shares TERM_PROGRAM with Trae
-    expect(result.detected).toEqual([{ ide: 'Trae', supported: false }])
+    expect(result.detected).toEqual([{ ide: 'trae', supported: true }])
   })
 })