@inspecto-dev/cli 0.2.0-alpha.1 → 0.2.0-alpha.3

package/src/inject/ast-injector.ts

@@ -1,181 +1,53 @@
 // ============================================================
 // 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.
+// Implements the Strategy Pattern to delegate AST manipulation
+// and manual instruction generation to specific build tool strategies.
 //
 // Safety protocol:
-//   1. Backup original file (.bak)
+//   1. Parse config file safely
 //   2. Idempotency check (skip if already injected)
-//   3. Attempt regex-based injection
-//   4. Basic syntax validation
-//   5. Graceful degradation on any failure
+//   3. Find matching strategy
+//   4. Delegate injection to strategy
+//   5. Write modified configuration back to file
+//   6. Fallback to manual instructions if automatic modification fails
 // ============================================================
 
 import path from 'node:path'
-import { exists, readFile, writeFile, copyFile } from '../utils/fs.js'
+import { loadFile, writeFile as writeAstFile } from 'magicast'
+import { exists, readFile } 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 ----
+import type { BuildToolDetection, Mutation } from '../types.js'
+import { STRATEGIES } from './strategies/index.js'
+import type { InjectStrategy } from './strategies/types.js'
 
 function printManualInstructions(
-  tool: BuildTool,
-  configPath: string,
+  strategy: InjectStrategy | undefined,
+  detection: BuildToolDetection,
   reason: string,
-  isLegacyRspack?: boolean,
 ) {
-  const isRsbuild = tool === 'rsbuild'
-
-  log.warn(`Could not safely auto-inject into ${configPath}`)
+  log.warn(`Could not automatically configure ${detection.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)},`,
-      `    ]`,
-      `  }`,
-      `}`,
-    ])
+  if (strategy) {
+    const instructions = strategy.getManualInstructions(detection, reason)
+    log.codeBlock(instructions)
   } else {
-    log.codeBlock([
-      getImportStatement(tool, isLegacyRspack),
-      '',
-      '// Add to your plugins array:',
-      `plugins: [`,
-      `  ${getPluginExpression(isLegacyRspack)},`,
-      `  ...otherPlugins`,
-      `].filter(Boolean)`,
-    ])
+    log.error(`Unsupported build tool: ${detection.tool}`)
   }
 }
 
-// ---- Injection helpers ----
-
 /** Check if inspecto is already injected (idempotency). */
 function isAlreadyInjected(content: string): boolean {
+  // Use regex to avoid false positives in comments or variables
   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
+    /import\s+.*@inspecto-dev\/plugin/.test(content) ||
+    /require\(['"]@inspecto-dev\/plugin['"]\)/.test(content) ||
+    /import\s+.*ai-dev-inspector/.test(content) || // Legacy support
+    /require\(['"]ai-dev-inspector['"]\)/.test(content)
+  )
 }
 
 // ---- Main injection orchestrator ----
@@ -192,109 +64,76 @@ export async function injectPlugin(
   dryRun: boolean,
 ): Promise<InjectionResult> {
   const configPath = path.join(root, detection.configPath)
-  const backupPath = configPath + '.bak'
   const mutations: Mutation[] = []
 
-  // Step 1: Read config file
+  const strategy = STRATEGIES.find(s => s.supports(detection.tool))
+
+  // Step 1: Read config file to check existence and idempotency
   const content = await readFile(configPath)
   if (!content) {
-    printManualInstructions(
-      detection.tool,
-      detection.configPath,
-      'config file not readable',
-      detection.isLegacyRspack,
-    )
+    printManualInstructions(strategy, detection, 'config file not readable')
     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 }
-  }
+    log.success(`Plugin already configured in ${detection.configPath} (skipped)`)
 
-  // 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',
+      description: 'Previously configured inspecto() plugin',
     })
+
+    return { success: true, mutations }
   }
-  log.success(`Backed up ${detection.configPath} → ${detection.configPath}.bak`)
 
-  // Step 4: Inject into plugins array
-  const injected = injectIntoPluginsArray(content, detection)
-  if (!injected) {
+  if (!strategy) {
     printManualInstructions(
-      detection.tool,
-      detection.configPath,
-      'could not locate plugins array — file may use dynamic config, function wrapper, or non-standard export',
-      detection.isLegacyRspack,
+      strategy,
+      detection,
+      `No injection strategy found for ${detection.tool}`,
     )
-    return {
-      success: false,
-      mutations,
-      failureReason: 'could not locate plugins array',
-    }
+    return { success: false, mutations, failureReason: 'No strategy found' }
+  }
+
+  // Step 3: Automatic configuration
+  if (dryRun) {
+    log.dryRun(`Would automatically configure plugin in ${detection.configPath}`)
+    return { success: true, mutations: [] }
   }
 
-  // Step 5: Inject import statement
-  const importStmt = getImportStatement(detection.tool, detection.isLegacyRspack)
-  const modifiedContent = injectImport(injected, importStmt)
+  try {
+    const mod = await loadFile(configPath)
 
-  // 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`)
-    }
+    // Delegate to strategy
+    strategy.inject({
+      mod,
+      detection,
+    })
+
+    // Step 4: Write modified config back to file
+    await writeAstFile(mod, configPath)
+
+    mutations.push({
+      type: 'file_modified',
+      path: detection.configPath,
+      description: 'Automatically configured inspecto() plugin',
+    })
+
+    log.success(`Configured plugin in ${detection.configPath}`)
+    return { success: true, mutations }
+  } catch (err) {
+    // Graceback degradation
     printManualInstructions(
-      detection.tool,
-      detection.configPath,
-      'injection produced unbalanced brackets',
-      detection.isLegacyRspack,
+      strategy,
+      detection,
+      `Automatic configuration unavailable: ${err instanceof Error ? err.message : String(err)}`,
     )
     return {
       success: false,
-      mutations: [], // Rolled back
-      failureReason: 'injection produced invalid syntax',
+      mutations,
+      failureReason: 'Automatic configuration unavailable',
     }
   }
-
-  // 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 }
 }

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[]
+}