@inspecto-dev/cli 0.2.0-alpha.5 → 0.3.0-alpha.1

package/src/commands/apply.ts

@@ -0,0 +1,118 @@
+import { applyOnboardingPlan, type ApplyOnboardingResult } from '../onboarding/apply.js'
+import { buildOnboardingContext } from '../onboarding/context.js'
+import { createPlanResult } from '../onboarding/planner.js'
+import { log } from '../utils/logger.js'
+import { writeCommandOutput } from '../utils/output.js'
+import type { PlanResult } from '../types.js'
+
+export interface ApplyCommandOptions {
+  json?: boolean
+  shared?: boolean
+  skipInstall?: boolean
+  dryRun?: boolean
+  noExtension?: boolean
+}
+
+export interface ApplyCommandResult extends ApplyOnboardingResult {
+  plan: PlanResult
+}
+
+function getProviderDefault(
+  providerId?: string,
+  preferredMode?: 'cli' | 'extension',
+): string | undefined {
+  if (!providerId) return undefined
+  const mode = preferredMode ?? (providerId === 'coco' ? 'cli' : 'extension')
+  return `${providerId}.${mode}`
+}
+
+function statusRank(status: ApplyCommandResult['status']): number {
+  switch (status) {
+    case 'error':
+      return 3
+    case 'blocked':
+      return 2
+    case 'warning':
+      return 1
+    case 'ok':
+    default:
+      return 0
+  }
+}
+
+function mergeStatus(
+  planStatus: PlanResult['status'],
+  applyStatus: ApplyOnboardingResult['status'],
+): ApplyCommandResult['status'] {
+  return statusRank(planStatus) >= statusRank(applyStatus) ? planStatus : applyStatus
+}
+
+function printApplyResult(result: ApplyCommandResult): void {
+  const manualSteps = result.postInstall.nextSteps.filter(
+    step => !result.plan.blockers.some(blocker => blocker.message === step),
+  )
+
+  log.header('Inspecto Apply')
+  log.info(`Status: ${result.status}`)
+  log.info(`Strategy: ${result.plan.strategy}`)
+
+  for (const blocker of result.plan.blockers) {
+    log.error(blocker.message)
+  }
+  for (const warning of result.plan.warnings) {
+    log.warn(warning.message)
+  }
+
+  if (manualSteps.length > 0 || result.plan.blockers.length > 0) {
+    log.blank()
+    log.warn('──────── Manual Steps Required ────────')
+    manualSteps.forEach(step => log.error(step))
+    return
+  }
+
+  if (result.plan.warnings.length > 0) {
+    return
+  }
+
+  log.ready('Ready! Inspecto is set up.')
+  log.info('Next:')
+  log.hint('1. Start or restart your dev server.')
+  log.hint('2. Open your app in the browser.')
+  log.hint('3. Hold Alt + Click any element to inspect.')
+}
+
+export async function apply(options: ApplyCommandOptions = {}): Promise<ApplyCommandResult> {
+  const root = process.cwd()
+  const context = await buildOnboardingContext(root)
+  const plan = createPlanResult(context)
+  const selectedProvider =
+    context.providers.find(provider => provider.id === plan.defaults.provider) ?? null
+  const selectedIDE =
+    context.ides.find(ide => ide.ide === plan.defaults.ide) ??
+    context.ides.find(ide => ide.supported) ??
+    null
+
+  const applyResult = await applyOnboardingPlan({
+    repoRoot: root,
+    projectRoot: root,
+    packageManager: context.packageManager,
+    supportedBuildTargets: context.buildTools.supported,
+    options: {
+      shared: options.shared ?? plan.defaults.shared,
+      skipInstall: options.skipInstall ?? false,
+      dryRun: options.dryRun ?? false,
+      noExtension: options.noExtension ?? !plan.defaults.extension,
+      quiet: options.json ?? false,
+    },
+    selectedIDE,
+    providerDefault: getProviderDefault(plan.defaults.provider, selectedProvider?.preferredMode),
+    plan,
+  })
+
+  const result: ApplyCommandResult = {
+    ...applyResult,
+    status: mergeStatus(plan.status, applyResult.status),
+    plan,
+  }
+  return writeCommandOutput(result, options.json ?? false, printApplyResult)
+}

package/src/commands/detect.ts

@@ -0,0 +1,59 @@
+import { log } from '../utils/logger.js'
+import { writeCommandOutput } from '../utils/output.js'
+import { createDetectionResult } from '../onboarding/planner.js'
+import type { DetectionResult } from '../types.js'
+
+function printDetectionResult(result: DetectionResult): void {
+  const suppressedCodes = new Set([
+    'unsupported-build-tool',
+    'unsupported-build-tool-present',
+    'unsupported-framework',
+    'unsupported-framework-present',
+  ])
+
+  log.header('Inspecto Detect')
+  log.info(`Status: ${result.status}`)
+  log.info(`Root: ${result.project.root}`)
+  log.info(`Package manager: ${result.project.packageManager}`)
+
+  if (result.environment.frameworks.length > 0) {
+    log.success(`Supported frameworks: ${result.environment.frameworks.join(', ')}`)
+  }
+  if (result.environment.unsupportedFrameworks.length > 0) {
+    log.warn(`Unsupported frameworks: ${result.environment.unsupportedFrameworks.join(', ')}`)
+  }
+  if (result.environment.buildTools.length > 0) {
+    log.success(
+      `Supported build tools: ${result.environment.buildTools.map(tool => tool.label).join(', ')}`,
+    )
+  }
+  if (result.environment.unsupportedBuildTools.length > 0) {
+    log.warn(`Unsupported build tools: ${result.environment.unsupportedBuildTools.join(', ')}`)
+  }
+
+  const supportedIdes = result.environment.ides.filter(ide => ide.supported).map(ide => ide.ide)
+  if (supportedIdes.length > 0) {
+    log.success(`Supported IDEs: ${supportedIdes.join(', ')}`)
+  }
+
+  const supportedProviders = result.environment.providers
+    .filter(provider => provider.supported)
+    .map(provider => provider.label)
+  if (supportedProviders.length > 0) {
+    log.success(`Supported providers: ${supportedProviders.join(', ')}`)
+  }
+
+  for (const blocker of result.blockers) {
+    if (suppressedCodes.has(blocker.code)) continue
+    log.error(blocker.message)
+  }
+  for (const warning of result.warnings) {
+    if (suppressedCodes.has(warning.code)) continue
+    log.warn(warning.message)
+  }
+}
+
+export async function detect(json = false): Promise<DetectionResult> {
+  const result = await createDetectionResult(process.cwd())
+  return writeCommandOutput(result, json, printDetectionResult)
+}

package/src/commands/doctor.ts

@@ -10,23 +10,83 @@ import { detectFrameworks } from '../detect/framework.js'
 import { detectIDE } from '../detect/ide.js'
 import { detectProviders } from '../detect/provider.js'
 import { isExtensionInstalled } from '../inject/extension.js'
+import { writeCommandOutput } from '../utils/output.js'
+import type { CommandStatus, DoctorDiagnostic, DoctorResult } from '../types.js'
 
-interface DiagResult {
-  errors: number
-  warnings: number
+export interface DoctorCommandOptions {
+  json?: boolean
 }
 
-export async function doctor(): Promise<void> {
-  const root = process.cwd()
-  const result: DiagResult = { errors: 0, warnings: 0 }
+function createDiagnostic(
+  code: string,
+  status: DoctorDiagnostic['status'],
+  message: string,
+  hints: string[] = [],
+  details?: Record<string, unknown>,
+): DoctorDiagnostic {
+  return {
+    code,
+    status,
+    message,
+    hints,
+    ...(details ? { details } : {}),
+  }
+}
+
+function doctorStatus(errors: number, warnings: number): CommandStatus {
+  if (errors > 0) return 'blocked'
+  if (warnings > 0) return 'warning'
+  return 'ok'
+}
 
+function printDoctorResult(result: DoctorResult): void {
   log.header('Inspecto Doctor')
 
+  for (const check of result.checks) {
+    if (check.status === 'ok') {
+      log.success(check.message)
+    } else if (check.status === 'warning') {
+      log.warn(check.message)
+    } else {
+      log.error(check.message)
+    }
+
+    for (const hint of check.hints) {
+      log.hint(hint)
+    }
+  }
+
+  log.blank()
+  if (result.summary.errors === 0 && result.summary.warnings === 0) {
+    log.success('All checks passed. Hold Alt + Click to start!')
+  } else {
+    const parts: string[] = []
+    if (result.summary.errors > 0) parts.push(`${result.summary.errors} error(s)`)
+    if (result.summary.warnings > 0) parts.push(`${result.summary.warnings} warning(s)`)
+    console.log(
+      `  ${parts.join(', ')}. ${result.summary.errors > 0 ? 'Fix the errors above to get started.' : ''}`,
+    )
+  }
+  log.blank()
+}
+
+export async function collectDoctorResult(root = process.cwd()): Promise<DoctorResult> {
+  const checks: DoctorDiagnostic[] = []
+
   // Check 1: package.json exists
   if (!(await exists(path.join(root, 'package.json')))) {
-    log.error('No package.json found')
-    log.hint('Run this command from your project root')
-    return
+    const diagnostic = createDiagnostic('missing-package-json', 'error', 'No package.json found', [
+      'Run this command from your project root',
+    ])
+    checks.push(diagnostic)
+    return {
+      status: 'blocked',
+      summary: { errors: 1, warnings: 0 },
+      project: { root },
+      errors: [diagnostic],
+      warnings: [],
+      checks,
+    }
   }
 
   // Run detections concurrently
@@ -42,42 +102,76 @@ export async function doctor(): Promise<void> {
 
   // Check 2: IDE
   if (ideProbe.detected.length === 0) {
-    log.warn('IDE: not detected')
-    result.warnings++
+    checks.push(createDiagnostic('ide-not-detected', 'warning', 'IDE: not detected'))
   } else {
     // If we have at least one supported IDE, it's a pass
     const hasSupported = ideProbe.detected.some(d => d.supported)
     if (hasSupported) {
-      log.success(
-        `IDE: ${ideProbe.detected
-          .filter(d => d.supported)
-          .map(d => d.ide)
-          .join(', ')}`,
+      checks.push(
+        createDiagnostic(
+          'ide-supported',
+          'ok',
+          `IDE: ${ideProbe.detected
+            .filter(d => d.supported)
+            .map(d => d.ide)
+            .join(', ')}`,
+          [],
+          {
+            detected: ideProbe.detected,
+          },
+        ),
       )
     } else {
       const names = ideProbe.detected.map(d => d.ide).join(', ')
-      log.warn(`IDE: ${names} (not supported in v1, VS Code, Cursor, Trae only)`)
-      result.warnings++
+      checks.push(
+        createDiagnostic(
+          'ide-unsupported',
+          'warning',
+          `IDE: ${names} (not supported in v1, VS Code, Cursor, Trae only)`,
+          [],
+          {
+            detected: ideProbe.detected,
+          },
+        ),
+      )
     }
   }
 
   // Check 3: Supported framework
   if (frameworkResult.supported.length > 0) {
-    log.success(`Framework: ${frameworkResult.supported.join(', ')}`)
+    checks.push(
+      createDiagnostic(
+        'framework-supported',
+        'ok',
+        `Framework: ${frameworkResult.supported.join(', ')}`,
+      ),
+    )
   } else if (frameworkResult.unsupported.length > 0) {
     const names = frameworkResult.unsupported.map(f => f.name).join(', ')
-    log.warn(`Framework: ${names} (not supported in v1, React/Vue only)`)
-    result.warnings++
+    checks.push(
+      createDiagnostic(
+        'framework-unsupported',
+        'warning',
+        `Framework: ${names} (not supported in v1, React/Vue only)`,
+      ),
+    )
   } else {
-    log.warn('Framework: not detected (React / Vue expected)')
-    result.warnings++
+    checks.push(
+      createDiagnostic(
+        'framework-not-detected',
+        'warning',
+        'Framework: not detected (React / Vue expected)',
+      ),
+    )
   }
 
   // Check 3.5: Providers
   if (providerProbe.detected.length === 0) {
-    log.warn('Provider: none detected')
-    log.hint('Inspecto works best with Claude Code, Trae CLI, or GitHub Copilot')
-    result.warnings++
+    checks.push(
+      createDiagnostic('provider-missing', 'warning', 'Provider: none detected', [
+        'Inspecto works best with Claude Code, Trae CLI, or GitHub Copilot',
+      ]),
+    )
   } else {
     const aiNames = providerProbe.detected
       .map(d => {
@@ -87,7 +181,7 @@ export async function doctor(): Promise<void> {
         return `${d.label} (${modeLabels.join(' & ')})`
       })
       .join(', ')
-    log.success(`Provider: ${aiNames}`)
+    checks.push(createDiagnostic('provider-detected', 'ok', `Provider: ${aiNames}`))
   }
 
   // Check 4: @inspecto-dev/plugin installed
@@ -95,12 +189,17 @@ export async function doctor(): Promise<void> {
   if (await exists(pluginPath)) {
     const pkgJson = await readJSON<{ version?: string }>(path.join(pluginPath, 'package.json'))
     const version = pkgJson?.version ?? 'unknown'
-    log.success(`@inspecto-dev/plugin@${version} installed`)
+    checks.push(
+      createDiagnostic('plugin-installed', 'ok', `@inspecto-dev/plugin@${version} installed`, [], {
+        version,
+      }),
+    )
   } else {
-    log.error('@inspecto-dev/plugin not installed')
-    const pm = await detectPackageManager(root)
-    log.hint(`Fix: ${getInstallCommand(pm, '@inspecto-dev/plugin')}`)
-    result.errors++
+    checks.push(
+      createDiagnostic('plugin-missing', 'error', '@inspecto-dev/plugin not installed', [
+        `Fix: ${getInstallCommand(pm, '@inspecto-dev/plugin')}`,
+      ]),
+    )
   }
 
   // Check 5: Plugin injected in build config
@@ -109,38 +208,64 @@ export async function doctor(): Promise<void> {
     for (const bt of buildResult.supported) {
       const content = await readFile(path.join(root, bt.configPath))
       if (content && content.includes('@inspecto-dev/plugin')) {
-        log.success(`Plugin configured in ${bt.configPath}`)
+        checks.push(
+          createDiagnostic('plugin-configured', 'ok', `Plugin configured in ${bt.configPath}`, [], {
+            configPath: bt.configPath,
+            buildTool: bt.tool,
+          }),
+        )
         injected = true
         break
       }
     }
     if (!injected) {
-      log.error('Plugin not configured in any build config')
-      log.hint('Fix: npx @inspecto-dev/cli init')
-      result.errors++
+      checks.push(
+        createDiagnostic(
+          'plugin-not-configured',
+          'error',
+          'Plugin not configured in any build config',
+          ['Fix: npx @inspecto-dev/cli init'],
+        ),
+      )
     }
   } else if (buildResult.unsupported.length > 0) {
     const names = buildResult.unsupported.join(', ')
-    log.warn(`Build tool: ${names} (not supported in v1)`)
-    log.hint('current version supports: Vite, Webpack, Rspack, esbuild, Rollup')
-    result.warnings++
+    checks.push(
+      createDiagnostic(
+        `build-tool-unsupported`,
+        'warning',
+        `Build tool: ${names} (not supported in v1)`,
+        ['current version supports: Vite, Webpack, Rspack, esbuild, Rollup'],
+      ),
+    )
   } else {
-    log.warn('No recognized build config found')
-    result.warnings++
+    checks.push(
+      createDiagnostic('build-tool-missing', 'warning', 'No recognized build config found'),
+    )
   }
 
   // Check 6: VS Code extension
   if (extInstalled) {
-    log.success('VS Code extension detected')
+    checks.push(createDiagnostic('extension-installed', 'ok', 'VS Code extension detected'))
   } else {
-    const hasSupported = ideProbe.detected.some(d => d.supported)
-    if (ideProbe.detected.length > 0 && !hasSupported) {
-      log.warn('VS Code extension not applicable (non-VS Code IDE)')
+    const hasVSCode = ideProbe.detected.some(d => d.supported && d.ide === 'vscode')
+    const hasSupportedNonVSCode = ideProbe.detected.some(d => d.supported && d.ide !== 'vscode')
+
+    if (hasSupportedNonVSCode && !hasVSCode) {
+      checks.push(
+        createDiagnostic(
+          'extension-not-applicable',
+          'warning',
+          'VS Code extension not applicable (non-VS Code IDE)',
+        ),
+      )
     } else {
-      log.error('VS Code extension not found')
-      log.hint('Fix: code --install-extension inspecto.inspecto')
-      log.hint('Or: https://marketplace.visualstudio.com/items?itemName=inspecto.inspecto')
-      result.errors++
+      checks.push(
+        createDiagnostic('extension-missing', 'error', 'VS Code extension not found', [
+          'Fix: code --install-extension inspecto.inspecto',
+          'Or: https://marketplace.visualstudio.com/items?itemName=inspecto.inspecto',
+        ]),
+      )
     }
   }
 
@@ -156,18 +281,31 @@ export async function doctor(): Promise<void> {
     const fileName = hasSettingsLocal ? 'settings.local.json' : 'settings.json'
     const settings = await readJSON(targetPath)
     if (settings) {
-      log.success(`.inspecto/${fileName} valid`)
+      checks.push(createDiagnostic('settings-valid', 'ok', `.inspecto/${fileName} valid`))
     } else {
-      log.error(`.inspecto/${fileName} has invalid JSON`)
-      log.hint(
-        'Fix: Manually correct the syntax errors, or delete the file and re-run npx @inspecto-dev/cli init',
+      checks.push(
+        createDiagnostic(
+          'settings-invalid-json',
+          'error',
+          `.inspecto/${fileName} has invalid JSON`,
+          [
+            'Fix: Manually correct the syntax errors, or delete the file and re-run npx @inspecto-dev/cli init',
+          ],
+          {
+            fileName,
+          },
+        ),
       )
-      result.errors++
     }
   } else {
-    log.warn('No .inspecto/settings.json or settings.local.json found (using defaults)')
-    log.hint('Optional: npx @inspecto-dev/cli init')
-    result.warnings++
+    checks.push(
+      createDiagnostic(
+        'settings-missing',
+        'warning',
+        'No .inspecto/settings.json or settings.local.json found (using defaults)',
+        ['Optional: npx @inspecto-dev/cli init'],
+      ),
+    )
   }
 
   // Check 8: .gitignore status
@@ -176,23 +314,38 @@ export async function doctor(): Promise<void> {
     const hasLockIgnore =
       gitignoreContent.includes('.inspecto/install.lock') || gitignoreContent.includes('.inspecto/')
     if (!hasLockIgnore) {
-      log.warn('.inspecto/install.lock not in .gitignore')
-      log.hint('install.lock contains local machine state and should not be committed')
-      result.warnings++
+      checks.push(
+        createDiagnostic(
+          'gitignore-missing-install-lock',
+          'warning',
+          '.inspecto/install.lock not in .gitignore',
+          ['install.lock contains local machine state and should not be committed'],
+        ),
+      )
     }
   }
 
-  // Summary
-  log.blank()
-  if (result.errors === 0 && result.warnings === 0) {
-    log.success('All checks passed. Hold Alt + Click to start!')
-  } else {
-    const parts: string[] = []
-    if (result.errors > 0) parts.push(`${result.errors} error(s)`)
-    if (result.warnings > 0) parts.push(`${result.warnings} warning(s)`)
-    console.log(
-      `  ${parts.join(', ')}. ${result.errors > 0 ? 'Fix the errors above to get started.' : ''}`,
-    )
+  const errors = checks.filter(check => check.status === 'error')
+  const warnings = checks.filter(check => check.status === 'warning')
+
+  return {
+    status: doctorStatus(errors.length, warnings.length),
+    summary: {
+      errors: errors.length,
+      warnings: warnings.length,
+    },
+    project: {
+      root,
+      packageManager: pm,
+    },
+    errors,
+    warnings,
+    checks,
   }
-  log.blank()
+}
+
+export async function doctor(options: DoctorCommandOptions | boolean = {}): Promise<DoctorResult> {
+  const json = typeof options === 'boolean' ? options : (options.json ?? false)
+  const result = await collectDoctorResult(process.cwd())
+  return writeCommandOutput(result, json, printDoctorResult)
 }