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

package/src/inject/gitignore.ts

@@ -21,6 +21,7 @@ export async function updateGitignore(
   root: string,
   shared: boolean,
   dryRun: boolean,
+  quiet = false,
 ): Promise<void> {
   const gitignorePath = path.join(root, '.gitignore')
   let content = (await readFile(gitignorePath)) ?? ''
@@ -34,7 +35,9 @@ export async function updateGitignore(
     if (!dryRun) {
       await writeFile(gitignorePath, content)
     }
-    log.success('Updated .gitignore: .inspecto/ is no longer fully ignored')
+    if (!quiet) {
+      log.success('Updated .gitignore: .inspecto/ is no longer fully ignored')
+    }
     return
   }
 
@@ -49,10 +52,14 @@ export async function updateGitignore(
   content = content.trimEnd() + '\n' + section
 
   if (dryRun) {
-    log.dryRun(`Would update .gitignore with: ${missingRules.join(', ')}`)
+    if (!quiet) {
+      log.dryRun(`Would update .gitignore with: ${missingRules.join(', ')}`)
+    }
   } else {
     await writeFile(gitignorePath, content)
-    log.success('Updated .gitignore')
+    if (!quiet) {
+      log.success('Updated .gitignore')
+    }
   }
 }
 

package/src/onboarding/apply.ts

@@ -61,6 +61,32 @@ export interface ApplyOnboardingResult {
   }
 }
 
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`
+}
+
+function resolveRuntimePackages(): {
+  installSpec: string
+  installedDependencyNames: string[]
+} {
+  const devRepo = process.env.INSPECTO_DEV_REPO
+  if (!devRepo) {
+    return {
+      installSpec: '@inspecto-dev/plugin @inspecto-dev/core',
+      installedDependencyNames: ['@inspecto-dev/plugin', '@inspecto-dev/core'],
+    }
+  }
+
+  const normalizedRepo = path.resolve(devRepo)
+  return {
+    installSpec: [
+      shellQuote(path.join(normalizedRepo, 'packages/plugin')),
+      shellQuote(path.join(normalizedRepo, 'packages/core')),
+    ].join(' '),
+    installedDependencyNames: ['@inspecto-dev/plugin', '@inspecto-dev/core'],
+  }
+}
+
 function resultStatus(nextSteps: string[]): CommandStatus {
   return nextSteps.length > 0 ? 'warning' : 'ok'
 }
@@ -157,10 +183,8 @@ 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 installCmd = getInstallCommand(
-    input.packageManager,
-    '@inspecto-dev/plugin @inspecto-dev/core',
-  )
+  const runtimePackages = resolveRuntimePackages()
+  const installCmd = getInstallCommand(input.packageManager, runtimePackages.installSpec)
   const nextSteps: string[] = []
 
   let installFailed = false
@@ -178,8 +202,9 @@ async function applyOnboardingPlanInternal(
       await shell(installCmd, input.projectRoot)
       spinner.succeed('Dependencies installed successfully')
       reporter.success('Installed @inspecto-dev/plugin and @inspecto-dev/core as devDependencies')
-      mutations.push({ type: 'dependency_added', name: '@inspecto-dev/plugin', dev: true })
-      mutations.push({ type: 'dependency_added', name: '@inspecto-dev/core', dev: true })
+      for (const name of runtimePackages.installedDependencyNames) {
+        mutations.push({ type: 'dependency_added', name, dev: true })
+      }
     } catch (error: any) {
       spinner.fail('Dependency installation failed')
       installFailed = true
@@ -193,7 +218,12 @@ async function applyOnboardingPlanInternal(
 
   let injectionFailed = Boolean(input.injectionSkippedRequiresManualConfig)
   for (const target of input.supportedBuildTargets) {
-    const result = await injectPlugin(input.repoRoot, target, input.options.dryRun)
+    const result = await injectPlugin(
+      input.repoRoot,
+      target,
+      input.options.dryRun,
+      input.options.quiet ?? false,
+    )
     if (result.success) {
       mutations.push(...result.mutations)
     } else {
@@ -244,7 +274,12 @@ async function applyOnboardingPlanInternal(
   }
 
   if (!input.options.dryRun) {
-    await updateGitignore(input.projectRoot, input.options.shared, input.options.dryRun)
+    await updateGitignore(
+      input.projectRoot,
+      input.options.shared,
+      input.options.dryRun,
+      input.options.quiet ?? false,
+    )
     mutations.push({
       type: 'file_modified',
       path: '.gitignore',
@@ -270,7 +305,11 @@ async function applyOnboardingPlanInternal(
   if (input.options.noExtension) {
     reporter.warn('Skipping IDE extension (--no-extension)')
   } else if (shouldInstallExt) {
-    const extMutation = await installExtension(input.options.dryRun, input.selectedIDE?.ide)
+    const extMutation = await installExtension(
+      input.options.dryRun,
+      input.selectedIDE?.ide,
+      input.options.quiet ?? false,
+    )
     if (extMutation && !input.options.dryRun) {
       mutations.push(extMutation)
 

package/src/onboarding/planner.ts

@@ -276,3 +276,9 @@ export function createPlanResult(context: OnboardingContext): PlanResult {
     defaults,
   }
 }
+
+export function planManualFollowUp(result: PlanResult): string[] {
+  return result.actions
+    .filter(action => action.type === 'manual_step')
+    .map(action => action.description)
+}

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.`,
+  }
+}