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

package/src/onboarding/session.ts

@@ -0,0 +1,434 @@
+import path from 'node:path'
+import { detectFrameworks } from '../detect/framework.js'
+import { detectIDE } from '../detect/ide.js'
+import { detectProviders } from '../detect/provider.js'
+import { applyOnboardingPlan, type ApplyOnboardingResult } from './apply.js'
+import { buildOnboardingContext } from './context.js'
+import { createPlanResult, planManualFollowUp } from './planner.js'
+import { resolveOnboardingTarget } from './target-resolution.js'
+import { readJSON } from '../utils/fs.js'
+import type {
+  OnboardCommandResult,
+  OnboardingContext,
+  OnboardingDiagnostics,
+  OnboardingExecutionResult,
+  OnboardingIdeExtensionStatus,
+  OnboardingSummary,
+  OnboardingVerification,
+  PlanResult,
+  ResolvedOnboardingSession,
+} from '../types.js'
+
+export interface ResolveOnboardingSessionOptions {
+  json?: boolean
+  target?: string
+  yes?: boolean
+  shared?: boolean
+  skipInstall?: boolean
+  dryRun?: boolean
+  noExtension?: boolean
+}
+
+function normalizePackagePath(packagePath?: string): string {
+  if (!packagePath || packagePath === '.') return ''
+  return packagePath.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, '')
+}
+
+function getProviderDefault(
+  providerId?: string,
+  preferredMode?: 'cli' | 'extension',
+): string | undefined {
+  if (!providerId) return undefined
+  const mode = preferredMode ?? (providerId === 'coco' ? 'cli' : 'extension')
+  return `${providerId}.${mode}`
+}
+
+function getVerificationCommand(packageManager: OnboardingContext['packageManager']): string {
+  switch (packageManager) {
+    case 'pnpm':
+      return 'pnpm dev'
+    case 'yarn':
+      return 'yarn dev'
+    case 'bun':
+      return 'bun run dev'
+    case 'npm':
+    default:
+      return 'npm run dev'
+  }
+}
+
+async function buildVerification(
+  projectRoot: string,
+  packageManager: OnboardingContext['packageManager'],
+): Promise<OnboardingVerification> {
+  const packageJson = await readJSON<{ scripts?: Record<string, string> }>(
+    path.join(projectRoot, 'package.json'),
+  )
+
+  if (packageJson?.scripts?.dev) {
+    const devCommand = getVerificationCommand(packageManager)
+    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 buildIdeExtensionStatus(input: {
+  required: boolean
+  installed: boolean
+  manualRequired: boolean
+}): OnboardingIdeExtensionStatus {
+  if (!input.required) {
+    return {
+      required: false,
+      installed: false,
+      manualRequired: false,
+    }
+  }
+
+  return {
+    required: true,
+    installed: input.installed,
+    manualRequired: input.manualRequired,
+    installCommand: 'code --install-extension inspecto.inspecto',
+    marketplaceUrl: 'https://marketplace.visualstudio.com/items?itemName=inspecto.inspecto',
+    openVsxUrl: 'https://open-vsx.org/extension/inspecto/inspecto',
+  }
+}
+
+async function detectFrameworkSupportByPackage(
+  repoRoot: string,
+  context: OnboardingContext,
+): Promise<Record<string, string[]>> {
+  const packagePaths = new Set(
+    context.buildTools.supported.map(item => normalizePackagePath(item.packagePath)),
+  )
+  const supportByPackage: Record<string, string[]> = {}
+
+  await Promise.all(
+    Array.from(packagePaths).map(async packagePath => {
+      const frameworkResult = await detectFrameworks(
+        packagePath ? path.join(repoRoot, packagePath) : repoRoot,
+      )
+      supportByPackage[packagePath] = frameworkResult.supported
+    }),
+  )
+
+  return supportByPackage
+}
+
+async function buildTargetedContext(
+  rootContext: OnboardingContext,
+  packagePath: string,
+): Promise<OnboardingContext> {
+  const projectRoot = packagePath ? path.join(rootContext.root, packagePath) : rootContext.root
+  const [frameworks, ides, providers] = await Promise.all([
+    detectFrameworks(projectRoot),
+    detectIDE(projectRoot),
+    detectProviders(projectRoot),
+  ])
+
+  return {
+    root: projectRoot,
+    packageManager: rootContext.packageManager,
+    buildTools: {
+      supported: rootContext.buildTools.supported.filter(item => {
+        return normalizePackagePath(item.packagePath) === packagePath
+      }),
+      unsupported: [],
+    },
+    frameworks: {
+      supported: frameworks.supported,
+      unsupported: frameworks.unsupported.map(item => item.name),
+    },
+    ides: ides.detected.map(({ ide, supported }) => ({ ide, supported })),
+    providers: providers.detected.map(({ id, label, supported, preferredMode }) => ({
+      id,
+      label,
+      supported,
+      preferredMode,
+    })),
+  }
+}
+
+function buildOnboardingSummary(plan: PlanResult, projectRoot: string): OnboardingSummary {
+  const changes = plan.actions
+    .filter(action => action.type !== 'manual_step')
+    .map(action => action.description)
+  const risks = [...plan.warnings.map(item => item.message)]
+  const manualFollowUp = planManualFollowUp(plan)
+
+  let headline = `Inspecto is ready to onboard ${projectRoot}.`
+  if (manualFollowUp.length > 0) {
+    headline = `Inspecto can partially onboard ${projectRoot}, but manual follow-up remains.`
+  } else if (plan.status === 'blocked') {
+    headline = `Inspecto could not build an automatic onboarding path for ${projectRoot}.`
+  }
+
+  return {
+    headline,
+    changes,
+    risks,
+    manualFollowUp,
+  }
+}
+
+function buildConfirmation(
+  plan: PlanResult,
+  summary: OnboardingSummary,
+  session: {
+    targetWasHeuristic: boolean
+    supportedIdeCount: number
+    supportedProviderCount: number
+  },
+  options: ResolveOnboardingSessionOptions,
+): { required: boolean; reason?: string; question?: string } {
+  if (options.yes) {
+    return { required: false }
+  }
+
+  const reasons: string[] = []
+  if (session.targetWasHeuristic) reasons.push('a monorepo target was preselected')
+  if (summary.manualFollowUp.length > 0) reasons.push('manual follow-up will remain after setup')
+  if (options.noExtension || options.skipInstall) reasons.push('non-core setup steps are being skipped')
+  if (session.supportedIdeCount > 1 || session.supportedProviderCount > 1) {
+    reasons.push('multiple IDE or provider choices are still relevant')
+  }
+  if (plan.warnings.length > 0) reasons.push('the CLI detected non-blocking risk')
+
+  if (reasons.length === 0) {
+    return { required: false }
+  }
+
+  return {
+    required: true,
+    reason: reasons.join('; '),
+    question: 'Proceed with Inspecto onboarding using the proposed default target and settings?',
+  }
+}
+
+function buildPreApplyResult(
+  status: ResolvedOnboardingSession['status'],
+  session: ResolvedOnboardingSession,
+): OnboardCommandResult {
+  const diagnostics: OnboardingDiagnostics | undefined =
+    session.summary.risks.length > 0 || session.summary.manualFollowUp.length > 0 || session.plan.blockers.length > 0
+      ? {
+          warnings: session.summary.risks,
+          errors: session.plan.blockers.map(item => item.message),
+          nextSteps: session.summary.manualFollowUp,
+        }
+      : undefined
+
+  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,
+    }),
+    verification: session.verification,
+    diagnostics,
+  }
+}
+
+function buildExecutionResult(
+  session: ResolvedOnboardingSession,
+  applyResult: ApplyOnboardingResult,
+): OnboardingExecutionResult {
+  return {
+    changedFiles: Array.from(
+      new Set(applyResult.mutations.map(item => item.path).filter((value): value is string => !!value)),
+    ),
+    installedDependencies: applyResult.mutations
+      .map(item => item.name)
+      .filter((value): value is string => !!value),
+    selectedProviderDefault: session.providerDefault,
+    selectedIDE: session.selectedIDE?.ide,
+    mutations: applyResult.mutations,
+  }
+}
+
+function buildExecutionDiagnostics(
+  session: ResolvedOnboardingSession,
+  applyResult: ApplyOnboardingResult,
+): OnboardingDiagnostics | undefined {
+  const warnings = [...session.plan.warnings.map(item => item.message)]
+  const errors: string[] = []
+
+  if (applyResult.postInstall.installFailed) {
+    errors.push('Dependency installation failed during onboarding.')
+  }
+  if (applyResult.postInstall.injectionFailed) {
+    warnings.push('Automatic plugin injection did not finish cleanly.')
+  }
+  if (applyResult.postInstall.manualExtensionInstallNeeded) {
+    warnings.push('IDE extension installation still needs manual completion.')
+  }
+
+  if (warnings.length === 0 && errors.length === 0 && applyResult.postInstall.nextSteps.length === 0) {
+    return undefined
+  }
+
+  return {
+    warnings,
+    errors,
+    nextSteps: applyResult.postInstall.nextSteps,
+  }
+}
+
+export async function resolveOnboardingSession(
+  root: string,
+  options: ResolveOnboardingSessionOptions = {},
+): Promise<ResolvedOnboardingSession> {
+  const rootContext = await buildOnboardingContext(root)
+  const rootVerification = await buildVerification(root, rootContext.packageManager)
+  const frameworkSupportByPackage = await detectFrameworkSupportByPackage(root, rootContext)
+  const target = resolveOnboardingTarget({
+    repoRoot: root,
+    buildTools: rootContext.buildTools.supported,
+    frameworkSupportByPackage,
+    selectedPackagePath: options.target,
+  })
+
+  if (target.candidates.length === 0) {
+    const plan = createPlanResult(rootContext)
+    return {
+      status: 'error',
+      target,
+      summary: buildOnboardingSummary(plan, root),
+      confirmation: { required: false },
+      verification: rootVerification,
+      context: rootContext,
+      plan,
+      projectRoot: root,
+    }
+  }
+
+  if (target.status === 'needs_selection') {
+    const plan = createPlanResult(rootContext)
+    const summary: OnboardingSummary = {
+      headline: 'Inspecto found multiple plausible app targets and needs one selection.',
+      changes: [],
+      risks: [],
+      manualFollowUp: [],
+    }
+    return {
+      status: 'needs_target_selection',
+      target,
+      summary,
+      confirmation: { required: false },
+      verification: rootVerification,
+      context: rootContext,
+      plan,
+      projectRoot: root,
+    }
+  }
+
+  const packagePath = normalizePackagePath(target.selected?.packagePath)
+  const context = await buildTargetedContext(rootContext, packagePath)
+  const verification = await buildVerification(context.root, context.packageManager)
+  const plan = createPlanResult(context)
+  const summary = buildOnboardingSummary(plan, context.root)
+  const confirmation = buildConfirmation(
+    plan,
+    summary,
+    {
+      targetWasHeuristic: target.candidates.length > 1 && options.target === undefined,
+      supportedIdeCount: context.ides.filter(item => item.supported).length,
+      supportedProviderCount: context.providers.filter(item => item.supported).length,
+    },
+    options,
+  )
+  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
+
+  let status: ResolvedOnboardingSession['status'] = 'success'
+  if (plan.status === 'blocked') {
+    status = 'error'
+  } else if (confirmation.required) {
+    status = 'needs_confirmation'
+  } else if (summary.manualFollowUp.length > 0 || plan.warnings.length > 0) {
+    status = 'partial_success'
+  }
+
+  return {
+    status,
+    target,
+    summary,
+    confirmation,
+    verification,
+    context,
+    plan,
+    projectRoot: context.root,
+    selectedIDE,
+    providerDefault: getProviderDefault(plan.defaults.provider, selectedProvider?.preferredMode),
+  }
+}
+
+export async function applyResolvedOnboardingSession(
+  session: ResolvedOnboardingSession,
+  options: ResolveOnboardingSessionOptions = {},
+): Promise<OnboardCommandResult> {
+  const verification = await buildVerification(session.projectRoot, session.context.packageManager)
+  const applyResult = await applyOnboardingPlan({
+    repoRoot: process.cwd(),
+    projectRoot: session.projectRoot,
+    packageManager: session.context.packageManager,
+    supportedBuildTargets: session.context.buildTools.supported,
+    options: {
+      shared: options.shared ?? session.plan.defaults.shared,
+      skipInstall: options.skipInstall ?? false,
+      dryRun: options.dryRun ?? false,
+      noExtension: options.noExtension ?? !session.plan.defaults.extension,
+      quiet: options.json ?? false,
+    },
+    selectedIDE: session.selectedIDE,
+    providerDefault: session.providerDefault,
+    plan: session.plan,
+  })
+
+  const diagnostics = buildExecutionDiagnostics(session, applyResult)
+  const status =
+    applyResult.postInstall.installFailed && session.context.buildTools.supported.length === 0
+      ? 'error'
+      : diagnostics?.nextSteps.length || diagnostics?.errors.length || diagnostics?.warnings.length
+        ? 'partial_success'
+        : 'success'
+
+  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,
+    }),
+    verification,
+    result: buildExecutionResult(session, applyResult),
+    diagnostics,
+  }
+}
+
+export function buildDeferredOnboardResult(
+  session: ResolvedOnboardingSession,
+): OnboardCommandResult {
+  return buildPreApplyResult(session.status, session)
+}

package/src/onboarding/target-resolution.ts

@@ -0,0 +1,116 @@
+import type {
+  BuildToolDetection,
+  OnboardingTargetCandidate,
+  OnboardingTargetResolution,
+} from '../types.js'
+
+export interface ResolveOnboardingTargetInput {
+  repoRoot: string
+  buildTools: BuildToolDetection[]
+  frameworkSupportByPackage: Record<string, string[]>
+  selectedPackagePath?: string
+}
+
+interface RankedCandidate {
+  candidate: OnboardingTargetCandidate
+  score: number
+}
+
+function normalizePackagePath(packagePath?: string): string {
+  if (!packagePath || packagePath === '.') return ''
+  return packagePath.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, '')
+}
+
+function looksLikeAppPackage(packagePath: string): boolean {
+  if (!packagePath) return true
+  return /(^|\/)(app|apps|web|client|frontend|site)(\/|$)/i.test(packagePath)
+}
+
+function looksLikeAuxiliaryPackage(packagePath: string): boolean {
+  return /(^|\/)(docs?|example|examples|playground|storybook|demo)(\/|$)/i.test(packagePath)
+}
+
+function buildCandidates(input: ResolveOnboardingTargetInput): OnboardingTargetCandidate[] {
+  return input.buildTools.map(buildTool => {
+    const packagePath = normalizePackagePath(buildTool.packagePath)
+    return {
+      packagePath,
+      configPath: buildTool.configPath,
+      buildTool: buildTool.tool,
+      frameworks: input.frameworkSupportByPackage[packagePath] ?? [],
+      automaticInjection: true,
+    }
+  })
+}
+
+function rankCandidate(candidate: OnboardingTargetCandidate): number {
+  let score = 0
+
+  if (candidate.frameworks.length > 0) score += 4
+  if (candidate.automaticInjection) score += 2
+  if (looksLikeAppPackage(candidate.packagePath)) score += 1
+  if (looksLikeAuxiliaryPackage(candidate.packagePath)) score -= 2
+
+  return score
+}
+
+function rankCandidates(candidates: OnboardingTargetCandidate[]): RankedCandidate[] {
+  return candidates
+    .map(candidate => ({
+      candidate,
+      score: rankCandidate(candidate),
+    }))
+    .sort((left, right) => right.score - left.score)
+}
+
+export function resolveOnboardingTarget(
+  input: ResolveOnboardingTargetInput,
+): OnboardingTargetResolution {
+  const candidates = buildCandidates(input)
+
+  if (candidates.length === 0) {
+    return {
+      status: 'needs_selection',
+      candidates,
+      reason: 'No supported targets were detected.',
+    }
+  }
+
+  const explicitlySelected = normalizePackagePath(input.selectedPackagePath)
+  if (input.selectedPackagePath !== undefined) {
+    const selected = candidates.find(candidate => candidate.packagePath === explicitlySelected)
+    if (selected) {
+      return {
+        status: 'resolved',
+        selected,
+        candidates,
+        reason: `Using the explicitly selected target: ${selected.packagePath || '.'}.`,
+      }
+    }
+  }
+
+  if (candidates.length === 1) {
+    return {
+      status: 'resolved',
+      selected: candidates[0],
+      candidates,
+      reason: 'Only one supported target was detected.',
+    }
+  }
+
+  const ranked = rankCandidates(candidates)
+  if (ranked.length > 1 && ranked[0]!.score === ranked[1]!.score) {
+    return {
+      status: 'needs_selection',
+      candidates,
+      reason: 'Multiple supported targets look equally plausible.',
+    }
+  }
+
+  return {
+    status: 'resolved',
+    selected: ranked[0]!.candidate,
+    candidates,
+    reason: `Preselected ${ranked[0]!.candidate.packagePath || '.'} because it has the strongest supported app signal.`,
+  }
+}

package/src/prompts.ts

@@ -45,19 +45,21 @@ export async function promptProviderChoice(
     type: 'select',
     name: 'choice',
     message: 'Detected multiple providers, please choose one:',
-    choices: detections.map((d, i) => {
-      const modeLabels = d.providerModes.map(mode =>
-        mode === 'extension' ? 'VS Code Extension' : 'Terminal CLI',
-      )
-      const modeStr = modeLabels.join(' & ')
-      return {
-        title: `${d.label} ${d.supported ? `(supported ${modeStr})` : '(unsupported/limited)'}`,
-        value: i,
-      }
-    }),
+    choices: detections
+      .map((d, i) => {
+        const modeLabels = d.providerModes.map(mode =>
+          mode === 'extension' ? 'VS Code Extension' : 'Terminal CLI',
+        )
+        const modeStr = modeLabels.join(' & ')
+        return {
+          title: `${d.label} ${d.supported ? `(supported ${modeStr})` : '(unsupported/limited)'}`,
+          value: i,
+        }
+      })
+      .concat({ title: 'Skip (configure later)', value: -1 }),
   })
 
-  if (choice === undefined) return null
+  if (choice === undefined || choice === -1) return null
   return detections[choice]!
 }
 
@@ -94,6 +96,47 @@ export async function promptConfigChoice(
   return detections[choice]!
 }
 
+/**
+ * Interactive prompt for choosing the target app when init is run from a monorepo root.
+ */
+export async function promptMonorepoPackageChoice(
+  detections: BuildToolDetection[],
+): Promise<string | null> {
+  const uniquePackages = Array.from(
+    new Map(
+      detections
+        .filter((d): d is BuildToolDetection & { packagePath: string } => !!d.packagePath)
+        .map(d => [d.packagePath, d]),
+    ).values(),
+  )
+
+  if (uniquePackages.length === 0) {
+    return null
+  }
+
+  if (!process.stdin.isTTY) {
+    log.error('Monorepo root detected, but stdin is not interactive.')
+    log.hint(
+      'Re-run `inspecto init` inside a specific app directory, or pass --packages <app-path>.',
+    )
+    return null
+  }
+
+  const { choice } = await prompts({
+    type: 'select',
+    name: 'choice',
+    message: 'Monorepo root detected. Choose the app to initialize:',
+    choices: uniquePackages.map((d, i) => ({
+      title: `${d.packagePath} (${d.tool})`,
+      description: d.configPath,
+      value: i,
+    })),
+  })
+
+  if (choice === undefined) return null
+  return uniquePackages[choice]!.packagePath
+}
+
 /**
  * Interactive prompt for continuing with unsupported frameworks.
  */