@inspecto-dev/cli 0.3.3 → 0.3.4

package/src/onboarding/apply.ts

@@ -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,16 @@ 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 => action.type === 'manual_step')
+    .map(action => action.description)
+
+  if (!includeBlockers) {
+    return steps
+  }
+
+  return [...plan.blockers.map(blocker => blocker.message), ...steps]
 }
 
 export async function applyOnboardingPlan(
@@ -163,6 +206,10 @@ async function applyOnboardingPlanInternal(
   input: ApplyOnboardingInput,
 ): Promise<ApplyOnboardingResult> {
   const reporter = createReporter(input.options.quiet)
+  const additiveManualPlan =
+    input.plan?.strategy === 'manual' &&
+    input.allowManualPlanApply &&
+    input.plan.blockers.length === 0
 
   if (input.plan && input.plan.strategy !== 'supported' && !input.allowManualPlanApply) {
     return {
@@ -172,7 +219,7 @@ async function applyOnboardingPlanInternal(
         installFailed: false,
         injectionFailed: false,
         manualExtensionInstallNeeded: false,
-        nextSteps: manualPlanSteps(input.plan),
+        nextSteps: manualPlanSteps(input.plan, true),
       },
     }
   }
@@ -183,6 +230,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[] = []
@@ -217,17 +269,19 @@ 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
+      }
     }
   }
 
@@ -238,20 +292,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 +430,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.',

package/src/onboarding/planner.ts

@@ -71,6 +71,31 @@ function buildToolBlockers(context: OnboardingContext): CommandMessage[] {
   return [message('missing-build-tool', 'No supported build tool detected')]
 }
 
+function buildToolWarnings(context: OnboardingContext): CommandMessage[] {
+  const warnings: CommandMessage[] = []
+
+  if (context.buildTools.supported.length === 1) {
+    const buildTool = context.buildTools.supported[0]!
+    if (buildTool.tool === 'rspack' && buildTool.isLegacyRspack) {
+      warnings.push(
+        message(
+          'legacy-rspack-requires-manual-config',
+          `Legacy Rspack detected at ${buildTool.configPath}. Inspecto must use the legacy Rspack plugin entry and manual config steps.`,
+        ),
+      )
+    } else if (buildTool.tool === 'webpack' && buildTool.isLegacyWebpack) {
+      warnings.push(
+        message(
+          'legacy-webpack4-requires-manual-config',
+          `Webpack 4 detected at ${buildTool.configPath}. Inspecto must use the legacy Webpack 4 plugin entry and manual config steps.`,
+        ),
+      )
+    }
+  }
+
+  return warnings
+}
+
 function frameworkBlockers(context: OnboardingContext): CommandMessage[] {
   if (context.frameworks.supported.length > 0) {
     return []
@@ -149,6 +174,36 @@ function manualBuildToolActions(context: OnboardingContext): PlanResult['actions
     ]
   }
 
+  const buildTool = context.buildTools.supported[0]
+  if (buildTool?.tool === 'rspack' && buildTool.isLegacyRspack) {
+    return [
+      {
+        type: 'install_dependency',
+        target: '@inspecto-dev/plugin @inspecto-dev/core',
+        description: `Install the Inspecto runtime packages with ${context.packageManager}.`,
+      },
+      {
+        type: 'manual_step',
+        target: buildTool.configPath,
+        description: `Update ${buildTool.configPath} to import \`rspackPlugin\` from \`@inspecto-dev/plugin/legacy/rspack\` and add it to the Rspack plugins array.`,
+      },
+    ]
+  }
+  if (buildTool?.tool === 'webpack' && buildTool.isLegacyWebpack) {
+    return [
+      {
+        type: 'install_dependency',
+        target: '@inspecto-dev/plugin @inspecto-dev/core',
+        description: `Install the Inspecto runtime packages with ${context.packageManager}.`,
+      },
+      {
+        type: 'manual_step',
+        target: buildTool.configPath,
+        description: `Update ${buildTool.configPath} to import \`webpackPlugin\` from \`@inspecto-dev/plugin/legacy/webpack4\` and add it to the Webpack plugins array.`,
+      },
+    ]
+  }
+
   return [
     {
       type: 'manual_step',
@@ -183,7 +238,10 @@ function manualFrameworkActions(context: OnboardingContext): PlanResult['actions
 
 export async function createDetectionResult(root: string): Promise<DetectionResult> {
   const context = await buildOnboardingContext(root)
-  const warnings = uniqueMessages([...unsupportedEnvironmentWarnings(context)])
+  const warnings = uniqueMessages([
+    ...unsupportedEnvironmentWarnings(context),
+    ...buildToolWarnings(context),
+  ])
 
   const buildToolResult = buildToolBlockers(context)
   const frameworkResult = frameworkBlockers(context)
@@ -209,18 +267,36 @@ export async function createDetectionResult(root: string): Promise<DetectionResu
 }
 
 export function createPlanResult(context: OnboardingContext): PlanResult {
-  const warnings = uniqueMessages(unsupportedEnvironmentWarnings(context))
+  const warnings = uniqueMessages([
+    ...unsupportedEnvironmentWarnings(context),
+    ...buildToolWarnings(context),
+  ])
   const blockers = uniqueMessages([...buildToolBlockers(context), ...frameworkBlockers(context)])
   const actions: PlanResult['actions'] = []
 
   let strategy: PlanResult['strategy'] = 'supported'
 
-  if (blockers.length > 0) {
+  const hasLegacyRspackManualPlan =
+    context.buildTools.supported.length === 1 &&
+    context.buildTools.supported[0]?.tool === 'rspack' &&
+    context.buildTools.supported[0]?.isLegacyRspack
+  const hasLegacyWebpackManualPlan =
+    context.buildTools.supported.length === 1 &&
+    context.buildTools.supported[0]?.tool === 'webpack' &&
+    context.buildTools.supported[0]?.isLegacyWebpack
+
+  if (blockers.length > 0 || hasLegacyRspackManualPlan || hasLegacyWebpackManualPlan) {
     strategy = 'manual'
     if (
       context.buildTools.unsupported.length > 0 ||
       context.buildTools.supported.length === 0 ||
-      context.buildTools.supported.length > 1
+      context.buildTools.supported.length > 1 ||
+      context.buildTools.supported.some(
+        buildTool => buildTool.tool === 'rspack' && buildTool.isLegacyRspack,
+      ) ||
+      context.buildTools.supported.some(
+        buildTool => buildTool.tool === 'webpack' && buildTool.isLegacyWebpack,
+      )
     ) {
       actions.push(...manualBuildToolActions(context))
     }

package/src/onboarding/session.ts

@@ -126,8 +126,9 @@ async function detectFrameworkSupportByPackage(
 
 async function buildTargetedContext(
   rootContext: OnboardingContext,
-  packagePath: string,
+  target: { id?: string; packagePath: string },
 ): Promise<OnboardingContext> {
+  const packagePath = normalizePackagePath(target.packagePath)
   const projectRoot = packagePath ? path.join(rootContext.root, packagePath) : rootContext.root
   const [frameworks, ides, providers] = await Promise.all([
     detectFrameworks(projectRoot),
@@ -140,7 +141,11 @@ async function buildTargetedContext(
     packageManager: rootContext.packageManager,
     buildTools: {
       supported: rootContext.buildTools.supported.filter(item => {
-        return normalizePackagePath(item.packagePath) === packagePath
+        const itemPackagePath = normalizePackagePath(item.packagePath)
+        if (target.id) {
+          return `${itemPackagePath || '.'}:${item.tool}:${item.configPath}` === target.id
+        }
+        return itemPackagePath === packagePath
       }),
       unsupported: [],
     },
@@ -327,7 +332,8 @@ export async function resolveOnboardingSession(
   if (target.status === 'needs_selection') {
     const plan = createPlanResult(rootContext)
     const summary: OnboardingSummary = {
-      headline: 'Inspecto found multiple plausible app targets and needs one selection.',
+      headline:
+        'Inspecto needs one build target selection before setup so it knows which local dev build should receive the plugin and settings.',
       changes: [],
       risks: [],
       manualFollowUp: [],
@@ -344,8 +350,7 @@ export async function resolveOnboardingSession(
     }
   }
 
-  const packagePath = normalizePackagePath(target.selected?.packagePath)
-  const context = await buildTargetedContext(rootContext, packagePath)
+  const context = await buildTargetedContext(rootContext, target.selected!)
   const verification = await buildVerification(context.root, context.packageManager)
   const plan = createPlanResult(context)
   const summary = buildOnboardingSummary(plan, context.root)
@@ -409,6 +414,7 @@ export async function applyResolvedOnboardingSession(
     selectedIDE: session.selectedIDE,
     providerDefault: session.providerDefault,
     plan: session.plan,
+    allowManualPlanApply: session.plan.strategy === 'manual' && session.plan.blockers.length === 0,
   })
 
   const diagnostics = buildExecutionDiagnostics(session, applyResult)

package/src/onboarding/target-resolution.ts

@@ -16,11 +16,36 @@ interface RankedCandidate {
   score: number
 }
 
+function buildCandidateId(candidate: {
+  packagePath: string
+  buildTool: string
+  configPath: string
+}): string {
+  return [candidate.packagePath || '.', candidate.buildTool, candidate.configPath].join(':')
+}
+
 function normalizePackagePath(packagePath?: string): string {
   if (!packagePath || packagePath === '.') return ''
   return packagePath.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, '')
 }
 
+function normalizeTargetValue(target?: string): string {
+  if (!target) return ''
+  return target.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, '')
+}
+
+function buildSelectionPurpose(): string {
+  return 'Choose the build target that runs your local development build so Inspecto can attach the right plugin and settings.'
+}
+
+function buildSelectionInstructions(hasCandidates: boolean): string {
+  if (!hasCandidates) {
+    return 'If auto-detection missed your build entrypoint, rerun with --target <configPath> using the config file or wrapper script your dev command actually starts.'
+  }
+
+  return 'Rerun with --target <candidateId> using one returned candidateId. The CLI also accepts an exact configPath from the candidate list as a compatibility fallback.'
+}
+
 function looksLikeAppPackage(packagePath: string): boolean {
   if (!packagePath) return true
   return /(^|\/)(app|apps|web|client|frontend|site)(\/|$)/i.test(packagePath)
@@ -33,13 +58,19 @@ function looksLikeAuxiliaryPackage(packagePath: string): boolean {
 function buildCandidates(input: ResolveOnboardingTargetInput): OnboardingTargetCandidate[] {
   return input.buildTools.map(buildTool => {
     const packagePath = normalizePackagePath(buildTool.packagePath)
-    return {
+    const candidate: OnboardingTargetCandidate = {
       packagePath,
       configPath: buildTool.configPath,
+      label: buildTool.label,
       buildTool: buildTool.tool,
+      isLegacyRspack: buildTool.isLegacyRspack,
+      isLegacyWebpack: buildTool.isLegacyWebpack,
       frameworks: input.frameworkSupportByPackage[packagePath] ?? [],
       automaticInjection: true,
     }
+    candidate.id = buildCandidateId(candidate)
+    candidate.candidateId = candidate.id
+    return candidate
   })
 }
 
@@ -73,18 +104,57 @@ export function resolveOnboardingTarget(
       status: 'needs_selection',
       candidates,
       reason: 'No supported targets were detected.',
+      selectionPurpose: buildSelectionPurpose(),
+      selectionInstructions: buildSelectionInstructions(false),
     }
   }
 
   const explicitlySelected = normalizePackagePath(input.selectedPackagePath)
+  const explicitlySelectedValue = normalizeTargetValue(input.selectedPackagePath)
   if (input.selectedPackagePath !== undefined) {
-    const selected = candidates.find(candidate => candidate.packagePath === explicitlySelected)
+    const selectedById = candidates.find(
+      candidate =>
+        candidate.id === input.selectedPackagePath ||
+        candidate.candidateId === input.selectedPackagePath,
+    )
+    if (selectedById) {
+      return {
+        status: 'resolved',
+        selected: selectedById,
+        candidates,
+        reason: `Using the explicitly selected target: ${selectedById.configPath}.`,
+        selectionPurpose: buildSelectionPurpose(),
+        selectionInstructions: buildSelectionInstructions(true),
+      }
+    }
+
+    const selectedByConfigPath = candidates.find(
+      candidate => normalizeTargetValue(candidate.configPath) === explicitlySelectedValue,
+    )
+    if (selectedByConfigPath) {
+      return {
+        status: 'resolved',
+        selected: selectedByConfigPath,
+        candidates,
+        reason: `Using the explicitly selected config path: ${selectedByConfigPath.configPath}.`,
+        selectionPurpose: buildSelectionPurpose(),
+        selectionInstructions: buildSelectionInstructions(true),
+      }
+    }
+
+    const matchingPackageCandidates = candidates.filter(
+      candidate => candidate.packagePath === explicitlySelected,
+    )
+    const selected =
+      matchingPackageCandidates.length === 1 ? matchingPackageCandidates[0] : undefined
     if (selected) {
       return {
         status: 'resolved',
         selected,
         candidates,
         reason: `Using the explicitly selected target: ${selected.packagePath || '.'}.`,
+        selectionPurpose: buildSelectionPurpose(),
+        selectionInstructions: buildSelectionInstructions(true),
       }
     }
   }
@@ -95,6 +165,8 @@ export function resolveOnboardingTarget(
       selected: candidates[0],
       candidates,
       reason: 'Only one supported target was detected.',
+      selectionPurpose: buildSelectionPurpose(),
+      selectionInstructions: buildSelectionInstructions(true),
     }
   }
 
@@ -104,6 +176,8 @@ export function resolveOnboardingTarget(
       status: 'needs_selection',
       candidates,
       reason: 'Multiple supported targets look equally plausible.',
+      selectionPurpose: buildSelectionPurpose(),
+      selectionInstructions: buildSelectionInstructions(true),
     }
   }
 
@@ -112,5 +186,7 @@ export function resolveOnboardingTarget(
     selected: ranked[0]!.candidate,
     candidates,
     reason: `Preselected ${ranked[0]!.candidate.packagePath || '.'} because it has the strongest supported app signal.`,
+    selectionPurpose: buildSelectionPurpose(),
+    selectionInstructions: buildSelectionInstructions(true),
   }
 }

package/src/types.ts

@@ -63,9 +63,14 @@ export interface OnboardingContext {
 }
 
 export interface OnboardingTargetCandidate {
+  id?: string
+  candidateId?: string
   packagePath: string
   configPath: string
+  label?: string
   buildTool: BuildTool
+  isLegacyRspack?: boolean
+  isLegacyWebpack?: boolean
   frameworks: string[]
   automaticInjection: boolean
 }
@@ -75,6 +80,8 @@ export interface OnboardingTargetResolution {
   selected?: OnboardingTargetCandidate
   candidates: OnboardingTargetCandidate[]
   reason: string
+  selectionPurpose?: string
+  selectionInstructions?: string
 }
 
 export interface OnboardingSummary {