@inspecto-dev/cli 0.3.3 → 0.3.5

package/src/inject/gitignore.ts

@@ -6,10 +6,20 @@ import { readFile, writeFile } from '../utils/fs.js'
 import { log } from '../utils/logger.js'
 
 /** Rules for default mode: fine-grained rules only */
-const DEFAULT_RULES = ['.inspecto/install.lock', '.inspecto/cache.json', '.inspecto/*.local.json']
+const DEFAULT_RULES = [
+  '.inspecto/install.lock',
+  '.inspecto/cache.json',
+  '.inspecto/*.local.json',
+  '.inspecto/dev.json',
+]
 
 /** Rules for shared mode: same as default in current design to allow settings.json */
-const SHARED_RULES = ['.inspecto/install.lock', '.inspecto/cache.json', '.inspecto/*.local.json']
+const SHARED_RULES = [
+  '.inspecto/install.lock',
+  '.inspecto/cache.json',
+  '.inspecto/*.local.json',
+  '.inspecto/dev.json',
+]
 
 /**
  * Update .gitignore based on the init mode.
@@ -77,6 +87,7 @@ export async function cleanGitignore(root: string): Promise<void> {
     .replace(/^\.inspecto\/install\.lock\s*$/gm, '')
     .replace(/^\.inspecto\/cache\.json\s*$/gm, '')
     .replace(/^\.inspecto\/\*\.local\.json\s*$/gm, '')
+    .replace(/^\.inspecto\/dev\.json\s*$/gm, '')
     .replace(/\n{3,}/g, '\n\n') // Collapse excess blank lines
 
   await writeFile(gitignorePath, cleaned)

package/src/instructions.ts

@@ -2,7 +2,9 @@ import { log } from './utils/logger.js'
 
 export function printNuxtManualInstructions() {
   log.blank()
-  log.hint('Nuxt requires manual setup in the current version.')
+  log.hint(
+    'Nuxt supports guided setup in the current version. Inspecto can prepare the config patch, but the client plugin mount step still needs review.',
+  )
   log.hint('1. Update `nuxt.config.ts` to register the Inspecto Vite plugin:')
   log.copyableCodeBlock([
     "import { vitePlugin as inspecto } from '@inspecto-dev/plugin'",
@@ -13,7 +15,7 @@ export function printNuxtManualInstructions() {
     '  },',
     '})',
   ])
-  log.hint('2. Create `plugins/inspecto.client.ts` to mount `@inspecto-dev/core` in development:')
+  log.hint('2. Complete the remaining client plugin mount step in `plugins/inspecto.client.ts`:')
   log.copyableCodeBlock([
     'export default defineNuxtPlugin(() => {',
     '  if (import.meta.dev) {',
@@ -23,12 +25,33 @@ export function printNuxtManualInstructions() {
     '  }',
     '})',
   ])
-  log.hint('3. Restart your Nuxt dev server after updating the config.')
+  log.hint('3. Restart your Nuxt dev server after applying the guided patches.')
+}
+
+export function printUmiManualInstructions() {
+  log.blank()
+  log.hint('Umi supports guided setup in the current version.')
+  log.hint('1. Update `config/config.ts` or `.umirc.ts` to register the Inspecto webpack plugin:')
+  log.copyableCodeBlock([
+    "import { defineConfig } from 'umi'",
+    "import { webpack4Plugin } from '@inspecto-dev/plugin/legacy/webpack4'",
+    '',
+    'export default defineConfig({',
+    '  chainWebpack(memo) {',
+    "    if (process.env.NODE_ENV === 'development') {",
+    "      memo.plugin('inspecto').use(webpack4Plugin())",
+    '    }',
+    '  },',
+    '})',
+  ])
+  log.hint('2. Restart your Umi dev server after applying the guided patches.')
 }
 
 export function printNextJsManualInstructions() {
   log.blank()
-  log.hint('Next.js requires manual setup in the current version.')
+  log.hint(
+    'Next.js supports guided setup in the current version. Inspecto can prepare the config patch, but the client-side mount step still needs review.',
+  )
   log.hint('1. Update `next.config.mjs` to register the Inspecto webpack plugin:')
   log.copyableCodeBlock([
     "import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'",
@@ -36,7 +59,7 @@ export function printNextJsManualInstructions() {
     "/** @type {import('next').NextConfig} */",
     'const nextConfig = {',
     '  webpack: (config, { dev, isServer }) => {',
-    '    if (dev && !isServer) {',
+    '    if (dev) {',
     '      config.plugins.push(inspecto())',
     '    }',
     '    return config',
@@ -46,7 +69,10 @@ export function printNextJsManualInstructions() {
     'export default nextConfig',
   ])
   log.hint(
-    '2. Initialize `@inspecto-dev/core` from a client component such as `app/layout.tsx` or `pages/_app.tsx`:',
+    'Keep the plugin enabled for both server and client development compilers so App Router server components also receive Inspecto transforms.',
+  )
+  log.hint(
+    '2. Complete the remaining client-side mount step in `app/layout.tsx` or `pages/_app.tsx`:',
   )
   log.copyableCodeBlock([
     "'use client'",
@@ -65,5 +91,5 @@ export function printNextJsManualInstructions() {
     '  return <html><body>{children}</body></html>',
     '}',
   ])
-  log.hint('3. Restart your Next.js dev server after updating the config.')
+  log.hint('3. Restart your Next.js dev server after applying the guided patches.')
 }

package/src/onboarding/apply.ts

@@ -5,7 +5,7 @@ import { injectPlugin } from '../inject/ast-injector.js'
 import { installExtension } from '../inject/extension.js'
 import { updateGitignore } from '../inject/gitignore.js'
 import { shell } from '../utils/exec.js'
-import { exists, readJSON, writeJSON } from '../utils/fs.js'
+import { exists, readFile, readJSON, writeFile, writeJSON } from '../utils/fs.js'
 import { log } from '../utils/logger.js'
 import type {
   BuildToolDetection,
@@ -50,6 +50,46 @@ interface ApplySpinner {
   fail(text: string): void
 }
 
+function normalizeSupportedIde(ide?: string): string | undefined {
+  if (!ide) return undefined
+  return ide.toLowerCase() === 'vscode' ? 'vscode' : ide.toLowerCase()
+}
+
+async function readInheritedSettingsDefaults(
+  repoRoot: string,
+  projectRoot: string,
+  settingsFileName: string,
+): Promise<{ ide?: string; providerDefault?: string }> {
+  if (path.resolve(repoRoot) === path.resolve(projectRoot)) {
+    return {}
+  }
+
+  const inheritedSettingsPath = path.join(repoRoot, '.inspecto', settingsFileName)
+  if (!(await exists(inheritedSettingsPath))) {
+    return {}
+  }
+
+  const inheritedSettings = await readJSON<Record<string, unknown>>(inheritedSettingsPath)
+  if (!inheritedSettings || typeof inheritedSettings !== 'object') {
+    return {}
+  }
+
+  const inheritedDefaults: { ide?: string; providerDefault?: string } = {}
+
+  if (typeof inheritedSettings.ide === 'string') {
+    const normalizedIde = normalizeSupportedIde(inheritedSettings.ide)
+    if (normalizedIde) {
+      inheritedDefaults.ide = normalizedIde
+    }
+  }
+
+  if (typeof inheritedSettings['provider.default'] === 'string') {
+    inheritedDefaults.providerDefault = inheritedSettings['provider.default']
+  }
+
+  return inheritedDefaults
+}
+
 export interface ApplyOnboardingResult {
   status: CommandStatus
   mutations: Mutation[]
@@ -91,13 +131,141 @@ function resultStatus(nextSteps: string[]): CommandStatus {
   return nextSteps.length > 0 ? 'warning' : 'ok'
 }
 
-function manualPlanSteps(plan: PlanResult): string[] {
-  return [
-    ...plan.blockers.map(blocker => blocker.message),
-    ...plan.actions
-      .filter(action => action.type === 'manual_step')
-      .map(action => action.description),
-  ]
+function manualPlanSteps(plan: PlanResult, includeBlockers = true): string[] {
+  const steps = plan.actions
+    .filter(action =>
+      ['manual_step', 'generate_patch_plan', 'generate_file', 'manual_confirmation'].includes(
+        action.type,
+      ),
+    )
+    .map(action => action.description)
+
+  if (!includeBlockers) {
+    return steps
+  }
+
+  return [...plan.blockers.map(blocker => blocker.message), ...steps]
+}
+
+function applyGuidedPatchContent(source: string, snippet: string): string {
+  if (source.includes("import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'")) {
+    return source
+  }
+  if (source.includes("import { vitePlugin as inspecto } from '@inspecto-dev/plugin'")) {
+    return source
+  }
+
+  const trimmedSource = source.trimEnd()
+  if (/export\s+default\s*\{/m.test(source)) {
+    const nextSource = trimmedSource.replace(
+      /export\s+default\s*\{/m,
+      "import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'\n\nexport default {\n  webpack(config, { dev, isServer }) {\n    if (dev) {\n      config.plugins.push(inspecto())\n    }\n    return config\n  },",
+    )
+    return `${nextSource}\n`
+  }
+
+  if (/module\.exports\s*=\s*\{/m.test(source)) {
+    const nextSource = trimmedSource.replace(
+      /module\.exports\s*=\s*\{/m,
+      "const { webpackPlugin: inspecto } = require('@inspecto-dev/plugin')\n\nmodule.exports = {\n  webpack(config, { dev, isServer }) {\n    if (dev) {\n      config.plugins.push(inspecto())\n    }\n    return config\n  },",
+    )
+    return `${nextSource}\n`
+  }
+
+  const objectExportVariableMatch = source.match(
+    /(const\s+([A-Za-z0-9_$]+)\s*(?::[^=]+)?=\s*\{[\s\S]*?\}\s*;?\s*)export\s+default\s+\2\s*;?/m,
+  )
+  const variableDeclaration = objectExportVariableMatch?.[1]
+  const variableName = objectExportVariableMatch?.[2]
+  if (variableDeclaration && variableName) {
+    const nextDeclaration = variableDeclaration.replace(
+      /=\s*\{/m,
+      '= {\n  webpack(config, { dev, isServer }) {\n    if (dev) {\n      config.plugins.push(inspecto())\n    }\n    return config\n  },',
+    )
+    const nextSource = source.replace(
+      objectExportVariableMatch[0],
+      `import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'\n\n${nextDeclaration}export default ${variableName}`,
+    )
+    return `${nextSource.trimEnd()}\n`
+  }
+
+  if (/defineNuxtConfig\s*\(\s*\{/m.test(source)) {
+    const trimmedSource = source.trimEnd()
+    const nextSource = trimmedSource.replace(
+      /defineNuxtConfig\s*\(\s*\{/m,
+      'defineNuxtConfig({\n  vite: {\n    plugins: [inspecto()],\n  },',
+    )
+    return `import { vitePlugin as inspecto } from '@inspecto-dev/plugin'\n\n${nextSource}\n`
+  }
+
+  const jsdocMatch = source.match(
+    /\/\*\*[\s\S]*?@type\s*\{import\('next'\)\.NextConfig\}[\s\S]*?\*\/[\s\S]*?(export\s+default|module\.exports)\s*=?\s*\{/m,
+  )
+  if (jsdocMatch) {
+    const isEsm = jsdocMatch[1] === 'export default'
+    const importStatement = isEsm
+      ? "import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'\n\n"
+      : "const { webpackPlugin: inspecto } = require('@inspecto-dev/plugin')\n\n"
+
+    const replacementPattern = isEsm ? /export\s+default\s*\{/m : /module\.exports\s*=\s*\{/m
+
+    const injectConfig = isEsm
+      ? 'export default {\n  webpack(config, { dev, isServer }) {\n    if (dev) {\n      config.plugins.push(inspecto())\n    }\n    return config\n  },'
+      : 'module.exports = {\n  webpack(config, { dev, isServer }) {\n    if (dev) {\n      config.plugins.push(inspecto())\n    }\n    return config\n  },'
+
+    const nextSource = source.replace(replacementPattern, injectConfig)
+    return `${importStatement}${nextSource.trimEnd()}\n`
+  }
+
+  return `${trimmedSource}\n\n${snippet}\n`
+}
+
+async function applyGuidedPlanPatches(
+  input: ApplyOnboardingInput,
+  mutations: Mutation[],
+  reporter: ApplyReporter,
+): Promise<string[]> {
+  const nextSteps: string[] = []
+
+  if (!input.plan || input.plan.strategy !== 'guided' || !input.plan.patches?.length) {
+    return nextSteps
+  }
+
+  for (const patch of input.plan.patches) {
+    if (
+      patch.status !== 'planned' ||
+      (!patch.reason.startsWith('next_config_') && !patch.reason.startsWith('nuxt_config_'))
+    ) {
+      continue
+    }
+
+    const patchPath = path.join(input.projectRoot, patch.path)
+    const existingContent = await readFile(patchPath)
+    if (existingContent === null) {
+      nextSteps.push(`Could not auto-apply the guided patch for ${patch.path}.`)
+      continue
+    }
+
+    const nextContent = applyGuidedPatchContent(existingContent, patch.snippet)
+    if (nextContent === existingContent) {
+      continue
+    }
+
+    if (input.options.dryRun) {
+      reporter.dryRun(`Would apply guided patch to ${patch.path}`)
+      continue
+    }
+
+    await writeFile(patchPath, nextContent)
+    mutations.push({
+      type: 'file_modified',
+      path: patch.path,
+      description: 'Automatically configured Inspecto guided Next.js patch',
+    })
+    reporter.success(`Applied guided patch to ${patch.path}`)
+  }
+
+  return nextSteps
 }
 
 export async function applyOnboardingPlan(
@@ -163,6 +331,10 @@ async function applyOnboardingPlanInternal(
   input: ApplyOnboardingInput,
 ): Promise<ApplyOnboardingResult> {
   const reporter = createReporter(input.options.quiet)
+  const additiveManualPlan =
+    (input.plan?.strategy === 'manual' || input.plan?.strategy === 'guided') &&
+    input.allowManualPlanApply &&
+    input.plan.blockers.length === 0
 
   if (input.plan && input.plan.strategy !== 'supported' && !input.allowManualPlanApply) {
     return {
@@ -172,7 +344,7 @@ async function applyOnboardingPlanInternal(
         installFailed: false,
         injectionFailed: false,
         manualExtensionInstallNeeded: false,
-        nextSteps: manualPlanSteps(input.plan),
+        nextSteps: manualPlanSteps(input.plan, true),
       },
     }
   }
@@ -183,6 +355,11 @@ async function applyOnboardingPlanInternal(
   const promptsFileName = input.options.shared ? 'prompts.json' : 'prompts.local.json'
   const settingsPath = path.join(settingsDir, settingsFileName)
   const promptsPath = path.join(settingsDir, promptsFileName)
+  const inheritedDefaults = await readInheritedSettingsDefaults(
+    input.repoRoot,
+    input.projectRoot,
+    settingsFileName,
+  )
   const runtimePackages = resolveRuntimePackages()
   const installCmd = getInstallCommand(input.packageManager, runtimePackages.installSpec)
   const nextSteps: string[] = []
@@ -209,6 +386,11 @@ async function applyOnboardingPlanInternal(
       spinner.fail('Dependency installation failed')
       installFailed = true
       reporter.error(`Failed to install dependency: ${error?.message || 'Unknown error'}`)
+      if (error?.stderr) {
+        reporter.error(`Details: ${error.stderr}`)
+      } else if (error?.stdout) {
+        reporter.error(`Details: ${error.stdout}`)
+      }
       reporter.hint(`Run manually in ${input.projectRoot}: ${installCmd}`)
       reporter.hint(
         'Setup will continue without dependencies, but Inspecto may not run until installation succeeds.',
@@ -217,20 +399,26 @@ async function applyOnboardingPlanInternal(
   }
 
   let injectionFailed = Boolean(input.injectionSkippedRequiresManualConfig)
-  for (const target of input.supportedBuildTargets) {
-    const result = await injectPlugin(
-      input.repoRoot,
-      target,
-      input.options.dryRun,
-      input.options.quiet ?? false,
-    )
-    if (result.success) {
-      mutations.push(...result.mutations)
-    } else {
-      injectionFailed = true
+  if (!additiveManualPlan) {
+    for (const target of input.supportedBuildTargets) {
+      const result = await injectPlugin(
+        input.repoRoot,
+        target,
+        input.options.dryRun,
+        input.options.quiet ?? false,
+      )
+      if (result.success) {
+        mutations.push(...result.mutations)
+      } else {
+        injectionFailed = true
+      }
     }
   }
 
+  if (additiveManualPlan) {
+    nextSteps.push(...(await applyGuidedPlanPatches(input, mutations, reporter)))
+  }
+
   if (await exists(settingsPath)) {
     const existingSettings = await readJSON(settingsPath)
     if (existingSettings === null) {
@@ -238,20 +426,56 @@ async function applyOnboardingPlanInternal(
       reporter.hint('Please fix the syntax errors manually, or delete it and re-run init')
       nextSteps.push(`Fix .inspecto/${settingsFileName} or delete it and rerun Inspecto setup.`)
     } else {
-      reporter.success(`.inspecto/${settingsFileName} already exists (skipped)`)
+      const mergedSettings =
+        existingSettings && typeof existingSettings === 'object'
+          ? { ...(existingSettings as Record<string, unknown>) }
+          : {}
+      let settingsChanged = false
+
+      const desiredIde =
+        inheritedDefaults.ide ??
+        (input.selectedIDE?.supported ? normalizeSupportedIde(input.selectedIDE.ide) : undefined)
+
+      if (desiredIde && !mergedSettings.ide) {
+        mergedSettings.ide = desiredIde
+        settingsChanged = true
+      }
+
+      const desiredProviderDefault = inheritedDefaults.providerDefault ?? input.providerDefault
+      if (desiredProviderDefault && !mergedSettings['provider.default']) {
+        mergedSettings['provider.default'] = desiredProviderDefault
+        settingsChanged = true
+      }
+
+      if (settingsChanged) {
+        if (input.options.dryRun) {
+          reporter.dryRun(`Would update .inspecto/${settingsFileName}`)
+        } else {
+          await writeJSON(settingsPath, mergedSettings)
+          reporter.success(`Updated .inspecto/${settingsFileName} with missing defaults`)
+          mutations.push({
+            type: 'file_modified',
+            path: `.inspecto/${settingsFileName}`,
+            description: 'Merged missing Inspecto defaults into existing settings',
+          })
+        }
+      } else {
+        reporter.success(`.inspecto/${settingsFileName} already exists (skipped)`)
+      }
     }
   } else {
     const defaultSettings: Record<string, unknown> = {}
+    const desiredIde =
+      inheritedDefaults.ide ??
+      (input.selectedIDE?.supported ? normalizeSupportedIde(input.selectedIDE.ide) : undefined)
+    const desiredProviderDefault = inheritedDefaults.providerDefault ?? input.providerDefault
 
-    if (input.selectedIDE?.supported) {
-      defaultSettings.ide =
-        input.selectedIDE.ide.toLowerCase() === 'vscode'
-          ? 'vscode'
-          : input.selectedIDE.ide.toLowerCase()
+    if (desiredIde) {
+      defaultSettings.ide = desiredIde
     }
 
-    if (input.providerDefault) {
-      defaultSettings['provider.default'] = input.providerDefault
+    if (desiredProviderDefault) {
+      defaultSettings['provider.default'] = desiredProviderDefault
     }
 
     if (input.options.dryRun) {
@@ -340,6 +564,9 @@ async function applyOnboardingPlanInternal(
     if (manualExtensionInstallNeeded) {
       nextSteps.push('Install the Inspecto IDE extension manually')
     }
+    if (additiveManualPlan && input.plan) {
+      nextSteps.push(...manualPlanSteps(input.plan, false))
+    }
     if (input.manualConfigRequiredFor === 'Nuxt') {
       nextSteps.push(
         'Nuxt detected—please follow the Nuxt instructions printed above to finish setup.',