@inspecto-dev/cli 0.3.4 → 0.3.6

package/src/onboarding/session.ts

@@ -2,6 +2,11 @@ import path from 'node:path'
 import { detectFrameworks } from '../detect/framework.js'
 import { detectIDE } from '../detect/ide.js'
 import { detectProviders } from '../detect/provider.js'
+import {
+  getHostIdeBinaryName,
+  isSupportedHostIde,
+  type SupportedHostIde,
+} from '../integrations/capabilities.js'
 import { applyOnboardingPlan, type ApplyOnboardingResult } from './apply.js'
 import { buildOnboardingContext } from './context.js'
 import { createPlanResult, planManualFollowUp } from './planner.js'
@@ -61,9 +66,10 @@ async function buildVerification(
   projectRoot: string,
   packageManager: OnboardingContext['packageManager'],
 ): Promise<OnboardingVerification> {
-  const packageJson = await readJSON<{ scripts?: Record<string, string> }>(
-    path.join(projectRoot, 'package.json'),
-  )
+  const packageJson = await readJSON<{
+    scripts?: Record<string, string>
+    dependencies?: Record<string, string>
+  }>(path.join(projectRoot, 'package.json'))
 
   if (packageJson?.scripts?.dev) {
     const devCommand = getVerificationCommand(packageManager)
@@ -74,13 +80,34 @@ async function buildVerification(
     }
   }
 
+  if (packageJson?.scripts?.start && packageJson?.dependencies?.next) {
+    const devCommand = packageManager === 'bun' ? 'bunx next dev' : 'npx next dev'
+    return {
+      available: true,
+      devCommand,
+      message: `Start the local dev server with \`${devCommand}\` to verify Inspecto in the browser.`,
+    }
+  }
+
   return {
     available: false,
     message: 'Start your normal local dev server command to verify Inspecto in the browser.',
   }
 }
 
+function buildExtensionInstallCommand(ide?: string): string {
+  if (ide && isSupportedHostIde(ide)) {
+    const binaryName = getHostIdeBinaryName(ide as SupportedHostIde)
+    if (binaryName) {
+      return `${binaryName} --install-extension inspecto.inspecto`
+    }
+  }
+
+  return 'code --install-extension inspecto.inspecto'
+}
+
 function buildIdeExtensionStatus(input: {
+  ide?: string
   required: boolean
   installed: boolean
   manualRequired: boolean
@@ -97,8 +124,12 @@ function buildIdeExtensionStatus(input: {
     required: true,
     installed: input.installed,
     manualRequired: input.manualRequired,
-    installCommand: 'code --install-extension inspecto.inspecto',
-    marketplaceUrl: 'https://marketplace.visualstudio.com/items?itemName=inspecto.inspecto',
+    installCommand: buildExtensionInstallCommand(input.ide),
+    ...(input.ide === 'vscode'
+      ? {
+          marketplaceUrl: 'https://marketplace.visualstudio.com/items?itemName=inspecto.inspecto',
+        }
+      : {}),
     openVsxUrl: 'https://open-vsx.org/extension/inspecto/inspecto',
   }
 }
@@ -165,7 +196,12 @@ async function buildTargetedContext(
 
 function buildOnboardingSummary(plan: PlanResult, projectRoot: string): OnboardingSummary {
   const changes = plan.actions
-    .filter(action => action.type !== 'manual_step')
+    .filter(
+      action =>
+        !['manual_step', 'generate_patch_plan', 'generate_file', 'manual_confirmation'].includes(
+          action.type,
+        ),
+    )
     .map(action => action.description)
   const risks = [...plan.warnings.map(item => item.message)]
   const manualFollowUp = planManualFollowUp(plan)
@@ -235,18 +271,28 @@ function buildPreApplyResult(
         }
       : undefined
 
+  const ideExtension = buildIdeExtensionStatus({
+    ...(session.selectedIDE?.ide ? { ide: session.selectedIDE.ide } : {}),
+    required: session.plan.defaults.extension,
+    installed: false,
+    manualRequired: session.plan.defaults.extension,
+  })
+
   return {
     status,
     target: session.target,
     summary: session.summary,
     confirmation: session.confirmation,
-    ideExtension: buildIdeExtensionStatus({
-      required: session.plan.defaults.extension,
-      installed: false,
-      manualRequired: session.plan.defaults.extension,
-    }),
+    ideExtension,
     verification: session.verification,
-    diagnostics,
+    ...(session.framework ? { framework: session.framework } : {}),
+    ...(session.metaFramework ? { metaFramework: session.metaFramework } : {}),
+    ...(session.routerMode ? { routerMode: session.routerMode } : {}),
+    ...(session.autoApplied ? { autoApplied: session.autoApplied } : {}),
+    ...(session.pendingSteps ? { pendingSteps: session.pendingSteps } : {}),
+    ...(session.assistantPrompt ? { assistantPrompt: session.assistantPrompt } : {}),
+    ...(session.patches ? { patches: session.patches } : {}),
+    ...(diagnostics ? { diagnostics } : {}),
   }
 }
 
@@ -263,8 +309,8 @@ function buildExecutionResult(
     installedDependencies: applyResult.mutations
       .map(item => item.name)
       .filter((value): value is string => !!value),
-    selectedProviderDefault: session.providerDefault,
-    selectedIDE: session.selectedIDE?.ide,
+    ...(session.providerDefault ? { selectedProviderDefault: session.providerDefault } : {}),
+    ...(session.selectedIDE?.ide ? { selectedIDE: session.selectedIDE.ide } : {}),
     mutations: applyResult.mutations,
   }
 }
@@ -312,20 +358,40 @@ export async function resolveOnboardingSession(
     repoRoot: root,
     buildTools: rootContext.buildTools.supported,
     frameworkSupportByPackage,
-    selectedPackagePath: options.target,
+    ...(options.target ? { selectedPackagePath: options.target } : {}),
   })
 
-  if (target.candidates.length === 0) {
+  const isGuided = rootContext.buildTools.unsupported.some(t =>
+    ['Next.js', 'Nuxt', 'Umi'].includes(t),
+  )
+
+  if (target.candidates.length === 0 || isGuided) {
     const plan = createPlanResult(rootContext)
+    const guidedStatus = plan.strategy === 'guided' ? 'partial_success' : 'error'
+    const resolvedTarget =
+      plan.strategy === 'guided'
+        ? {
+            status: 'guided' as const,
+            candidates: [],
+            reason: `Guided onboarding is available for ${plan.metaFramework ?? 'this project'}.`,
+          }
+        : target
     return {
-      status: 'error',
-      target,
+      status: guidedStatus,
+      target: resolvedTarget,
       summary: buildOnboardingSummary(plan, root),
       confirmation: { required: false },
       verification: rootVerification,
       context: rootContext,
       plan,
       projectRoot: root,
+      ...(plan.framework ? { framework: plan.framework } : {}),
+      ...(plan.metaFramework ? { metaFramework: plan.metaFramework } : {}),
+      ...(plan.routerMode ? { routerMode: plan.routerMode } : {}),
+      ...(plan.autoApplied ? { autoApplied: plan.autoApplied } : {}),
+      ...(plan.pendingSteps ? { pendingSteps: plan.pendingSteps } : {}),
+      ...(plan.assistantPrompt ? { assistantPrompt: plan.assistantPrompt } : {}),
+      ...(plan.patches ? { patches: plan.patches } : {}),
     }
   }
 
@@ -380,6 +446,11 @@ export async function resolveOnboardingSession(
     status = 'partial_success'
   }
 
+  const providerDefault = getProviderDefault(
+    plan.defaults.provider,
+    selectedProvider?.preferredMode,
+  )
+
   return {
     status,
     target,
@@ -390,7 +461,14 @@ export async function resolveOnboardingSession(
     plan,
     projectRoot: context.root,
     selectedIDE,
-    providerDefault: getProviderDefault(plan.defaults.provider, selectedProvider?.preferredMode),
+    ...(providerDefault ? { providerDefault } : {}),
+    ...(plan.framework ? { framework: plan.framework } : {}),
+    ...(plan.metaFramework ? { metaFramework: plan.metaFramework } : {}),
+    ...(plan.routerMode ? { routerMode: plan.routerMode } : {}),
+    ...(plan.autoApplied ? { autoApplied: plan.autoApplied } : {}),
+    ...(plan.pendingSteps ? { pendingSteps: plan.pendingSteps } : {}),
+    ...(plan.assistantPrompt ? { assistantPrompt: plan.assistantPrompt } : {}),
+    ...(plan.patches ? { patches: plan.patches } : {}),
   }
 }
 
@@ -414,7 +492,9 @@ export async function applyResolvedOnboardingSession(
     selectedIDE: session.selectedIDE,
     providerDefault: session.providerDefault,
     plan: session.plan,
-    allowManualPlanApply: session.plan.strategy === 'manual' && session.plan.blockers.length === 0,
+    allowManualPlanApply:
+      (session.plan.strategy === 'manual' || session.plan.strategy === 'guided') &&
+      session.plan.blockers.length === 0,
   })
 
   const diagnostics = buildExecutionDiagnostics(session, applyResult)
@@ -425,20 +505,30 @@ export async function applyResolvedOnboardingSession(
         ? 'partial_success'
         : 'success'
 
+  const ideExtension = buildIdeExtensionStatus({
+    ...(session.selectedIDE?.ide ? { ide: session.selectedIDE.ide } : {}),
+    required: session.plan.defaults.extension,
+    installed:
+      session.plan.defaults.extension && !applyResult.postInstall.manualExtensionInstallNeeded,
+    manualRequired: applyResult.postInstall.manualExtensionInstallNeeded,
+  })
+
   return {
     status,
     target: session.target,
     summary: session.summary,
     confirmation: session.confirmation,
-    ideExtension: buildIdeExtensionStatus({
-      required: session.plan.defaults.extension,
-      installed:
-        session.plan.defaults.extension && !applyResult.postInstall.manualExtensionInstallNeeded,
-      manualRequired: applyResult.postInstall.manualExtensionInstallNeeded,
-    }),
+    ideExtension,
     verification,
     result: buildExecutionResult(session, applyResult),
-    diagnostics,
+    ...(session.framework ? { framework: session.framework } : {}),
+    ...(session.metaFramework ? { metaFramework: session.metaFramework } : {}),
+    ...(session.routerMode ? { routerMode: session.routerMode } : {}),
+    ...(session.autoApplied ? { autoApplied: session.autoApplied } : {}),
+    ...(session.pendingSteps ? { pendingSteps: session.pendingSteps } : {}),
+    ...(session.assistantPrompt ? { assistantPrompt: session.assistantPrompt } : {}),
+    ...(session.patches ? { patches: session.patches } : {}),
+    ...(diagnostics ? { diagnostics } : {}),
   }
 }
 

package/src/onboarding/target-resolution.ts

@@ -63,8 +63,8 @@ function buildCandidates(input: ResolveOnboardingTargetInput): OnboardingTargetC
       configPath: buildTool.configPath,
       label: buildTool.label,
       buildTool: buildTool.tool,
-      isLegacyRspack: buildTool.isLegacyRspack,
-      isLegacyWebpack: buildTool.isLegacyWebpack,
+      ...(buildTool.isLegacyRspack ? { isLegacyRspack: true } : {}),
+      ...(buildTool.isLegacyWebpack ? { isLegacyWebpack: true } : {}),
       frameworks: input.frameworkSupportByPackage[packagePath] ?? [],
       automaticInjection: true,
     }
@@ -162,7 +162,7 @@ export function resolveOnboardingTarget(
   if (candidates.length === 1) {
     return {
       status: 'resolved',
-      selected: candidates[0],
+      selected: candidates[0]!,
       candidates,
       reason: 'Only one supported target was detected.',
       selectionPurpose: buildSelectionPurpose(),

package/src/onboarding/umi-guidance.ts

@@ -0,0 +1,139 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { OnboardingPatchPlan } from '../types.js'
+
+export interface UmiGuidance {
+  framework: 'react'
+  metaFramework: 'Umi'
+  autoApplied: string[]
+  pendingSteps: string[]
+  assistantPrompt: string
+  patches: OnboardingPatchPlan[]
+}
+
+const UMI_CONFIG_CANDIDATES = [
+  '.umirc.ts',
+  '.umirc.js',
+  'config/config.ts',
+  'config/config.js',
+] as const
+
+function findFirstExisting(root: string, candidates: readonly string[]): string | undefined {
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(root, candidate))) {
+      return candidate
+    }
+  }
+
+  return undefined
+}
+
+function readConfig(root: string, relativePath?: string): string {
+  if (!relativePath) return ''
+  const filePath = path.join(root, relativePath)
+  if (!fs.existsSync(filePath)) return ''
+  return fs.readFileSync(filePath, 'utf8')
+}
+
+function detectPatchShape(source: string): {
+  status: OnboardingPatchPlan['status']
+  reason: OnboardingPatchPlan['reason']
+  confidence: OnboardingPatchPlan['confidence']
+} {
+  if (/defineConfig\s*\(\s*\{[\s\S]*\}\s*\)/m.test(source)) {
+    return {
+      status: 'planned',
+      reason: 'umi_config_object_export',
+      confidence: 'high',
+    }
+  }
+
+  if (source.trim().length === 0) {
+    return {
+      status: 'manual_patch_required',
+      reason: 'umi_config_missing',
+      confidence: 'low',
+    }
+  }
+
+  return {
+    status: 'manual_patch_required',
+    reason: 'umi_config_complex_shape',
+    confidence: 'medium',
+  }
+}
+
+function buildUmiConfigSnippet(): string {
+  return [
+    "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())",
+    '    }',
+    '  },',
+    '})',
+  ].join('\n')
+}
+
+function buildUmiMountSnippet(): string {
+  return [
+    "import { useEffect } from 'react'",
+    '',
+    'export function rootContainer(container: React.ReactNode) {',
+    '  return (',
+    '    <InspectoWrapper>{container}</InspectoWrapper>',
+    '  )',
+    '}',
+    '',
+    'function InspectoWrapper({ children }: { children: React.ReactNode }) {',
+    '  useEffect(() => {',
+    "    if (process.env.NODE_ENV !== 'production') {",
+    "      import('@inspecto-dev/core').then(({ mountInspector }) => {",
+    '        mountInspector({',
+    "          serverUrl: 'http://127.0.0.1:' + ((window as any).__AI_INSPECTOR_PORT__ || 5678),",
+    '        })',
+    '      })',
+    '    }',
+    '  }, [])',
+    '',
+    '  return <>{children}</>',
+    '}',
+  ].join('\n')
+}
+
+export function createUmiGuidance(root: string): UmiGuidance {
+  const configPath = findFirstExisting(root, UMI_CONFIG_CANDIDATES) ?? '.umirc.ts'
+  const configSource = readConfig(root, findFirstExisting(root, UMI_CONFIG_CANDIDATES))
+  const patchShape = detectPatchShape(configSource)
+
+  return {
+    framework: 'react',
+    metaFramework: 'Umi',
+    autoApplied: ['dependencies', 'inspecto_settings'],
+    pendingSteps: [
+      `Review the generated Umi patch plan for ${configPath}.`,
+      'Complete the remaining client-side mount step in src/app.tsx.',
+    ],
+    assistantPrompt:
+      'Complete the remaining Inspecto onboarding for this Umi project. Review the generated patch plan, keep existing app behavior unchanged, and finish the client-side mount step safely.',
+    patches: [
+      {
+        path: configPath,
+        status: patchShape.status,
+        reason: patchShape.reason,
+        confidence: patchShape.confidence,
+        snippet: buildUmiConfigSnippet(),
+      },
+      {
+        path: 'src/app.tsx',
+        status: 'manual_patch_required',
+        reason: 'umi_app_mount',
+        confidence: 'medium',
+        snippet: buildUmiMountSnippet(),
+      },
+    ],
+  }
+}

package/src/types.ts

@@ -76,7 +76,7 @@ export interface OnboardingTargetCandidate {
 }
 
 export interface OnboardingTargetResolution {
-  status: 'resolved' | 'needs_selection'
+  status: 'resolved' | 'needs_selection' | 'guided'
   selected?: OnboardingTargetCandidate
   candidates: OnboardingTargetCandidate[]
   reason: string
@@ -91,6 +91,14 @@ export interface OnboardingSummary {
   manualFollowUp: string[]
 }
 
+export interface OnboardingPatchPlan {
+  path: string
+  status: 'planned' | 'manual_patch_required'
+  reason: string
+  snippet: string
+  confidence: 'high' | 'medium' | 'low'
+}
+
 export interface OnboardingConfirmation {
   required: boolean
   reason?: string
@@ -126,6 +134,16 @@ export interface OnboardingVerification {
   message: string
 }
 
+export interface OnboardingAssistantHandoff {
+  framework?: string
+  metaFramework?: string
+  routerMode?: 'app' | 'pages' | 'mixed' | 'unknown'
+  autoApplied?: string[]
+  pendingSteps?: string[]
+  assistantPrompt?: string
+  patches?: OnboardingPatchPlan[]
+}
+
 export interface ResolvedOnboardingSession {
   status: OnboardStatus
   target: OnboardingTargetResolution
@@ -137,6 +155,14 @@ export interface ResolvedOnboardingSession {
   projectRoot: string
   selectedIDE?: { ide: string; supported: boolean } | null
   providerDefault?: string
+  framework?: string
+  metaFramework?: string
+  routerMode?: 'app' | 'pages' | 'mixed' | 'unknown'
+  autoApplied?: string[]
+  pendingSteps?: string[]
+  assistantPrompt?: string
+  patches?: OnboardingPatchPlan[]
+  handoff?: OnboardingAssistantHandoff
 }
 
 export interface OnboardCommandResult {
@@ -148,6 +174,14 @@ export interface OnboardCommandResult {
   verification?: OnboardingVerification
   result?: OnboardingExecutionResult
   diagnostics?: OnboardingDiagnostics
+  framework?: string
+  metaFramework?: string
+  routerMode?: 'app' | 'pages' | 'mixed' | 'unknown'
+  autoApplied?: string[]
+  pendingSteps?: string[]
+  assistantPrompt?: string
+  patches?: OnboardingPatchPlan[]
+  handoff?: OnboardingAssistantHandoff
 }
 
 /** Machine-readable detection output for skill-first onboarding */
@@ -174,9 +208,16 @@ export interface PlanResult {
   status: CommandStatus
   warnings: CommandMessage[]
   blockers: CommandMessage[]
-  strategy: 'supported' | 'manual' | 'unsupported'
+  strategy: 'supported' | 'guided' | 'manual' | 'unsupported'
   actions: Array<{
-    type: 'install_dependency' | 'modify_file' | 'install_extension' | 'manual_step'
+    type:
+      | 'install_dependency'
+      | 'modify_file'
+      | 'install_extension'
+      | 'manual_step'
+      | 'generate_patch_plan'
+      | 'generate_file'
+      | 'manual_confirmation'
     target: string
     description: string
   }>
@@ -186,6 +227,13 @@ export interface PlanResult {
     shared: boolean
     extension: boolean
   }
+  framework?: string
+  metaFramework?: string
+  routerMode?: 'app' | 'pages' | 'mixed' | 'unknown'
+  autoApplied?: string[]
+  pendingSteps?: string[]
+  assistantPrompt?: string
+  patches?: OnboardingPatchPlan[]
 }
 
 /** A single doctor diagnostic check/result */