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

package/src/onboarding/apply.ts

@@ -0,0 +1,364 @@
+import path from 'node:path'
+import ora from 'ora'
+import { getInstallCommand } from '../detect/package-manager.js'
+import { injectPlugin } from '../inject/ast-injector.js'
+import { installExtension } from '../inject/extension.js'
+import { updateGitignore } from '../inject/gitignore.js'
+import { shell } from '../utils/exec.js'
+import { exists, readJSON, writeJSON } from '../utils/fs.js'
+import { log } from '../utils/logger.js'
+import type {
+  BuildToolDetection,
+  CommandStatus,
+  InstallLock,
+  Mutation,
+  PackageManager,
+  PlanResult,
+} from '../types.js'
+
+export interface ApplyOnboardingInput {
+  repoRoot: string
+  projectRoot: string
+  packageManager: PackageManager
+  supportedBuildTargets: BuildToolDetection[]
+  options: {
+    shared: boolean
+    skipInstall: boolean
+    dryRun: boolean
+    noExtension: boolean
+    quiet?: boolean | undefined
+  }
+  selectedIDE?: { ide: string; supported: boolean } | null | undefined
+  providerDefault?: string | undefined
+  manualConfigRequiredFor?: string | undefined
+  injectionSkippedRequiresManualConfig?: boolean | undefined
+  plan?: PlanResult | undefined
+  allowManualPlanApply?: boolean | undefined
+}
+
+interface ApplyReporter {
+  warn(text: string): void
+  success(text: string): void
+  error(text: string): void
+  hint(text: string): void
+  dryRun(text: string): void
+}
+
+interface ApplySpinner {
+  start(): void
+  succeed(text: string): void
+  fail(text: string): void
+}
+
+export interface ApplyOnboardingResult {
+  status: CommandStatus
+  mutations: Mutation[]
+  postInstall: {
+    installFailed: boolean
+    injectionFailed: boolean
+    manualExtensionInstallNeeded: boolean
+    nextSteps: string[]
+  }
+}
+
+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'
+}
+
+function manualPlanSteps(plan: PlanResult): string[] {
+  return [
+    ...plan.blockers.map(blocker => blocker.message),
+    ...plan.actions
+      .filter(action => action.type === 'manual_step')
+      .map(action => action.description),
+  ]
+}
+
+export async function applyOnboardingPlan(
+  input: ApplyOnboardingInput,
+): Promise<ApplyOnboardingResult> {
+  return applyOnboardingPlanInternal(input)
+}
+
+function createReporter(quiet = false): ApplyReporter {
+  if (quiet) {
+    return {
+      warn() {},
+      success() {},
+      error() {},
+      hint() {},
+      dryRun() {},
+    }
+  }
+
+  return {
+    warn(text: string) {
+      log.warn(text)
+    },
+    success(text: string) {
+      log.success(text)
+    },
+    error(text: string) {
+      log.error(text)
+    },
+    hint(text: string) {
+      log.hint(text)
+    },
+    dryRun(text: string) {
+      log.dryRun(text)
+    },
+  }
+}
+
+function createSpinner(text: string, quiet = false): ApplySpinner {
+  if (quiet) {
+    return {
+      start() {},
+      succeed() {},
+      fail() {},
+    }
+  }
+
+  const spinner = ora(text)
+  return {
+    start() {
+      spinner.start()
+    },
+    succeed(successText: string) {
+      spinner.succeed(successText)
+    },
+    fail(failureText: string) {
+      spinner.fail(failureText)
+    },
+  }
+}
+
+async function applyOnboardingPlanInternal(
+  input: ApplyOnboardingInput,
+): Promise<ApplyOnboardingResult> {
+  const reporter = createReporter(input.options.quiet)
+
+  if (input.plan && input.plan.strategy !== 'supported' && !input.allowManualPlanApply) {
+    return {
+      status: input.plan.status,
+      mutations: [],
+      postInstall: {
+        installFailed: false,
+        injectionFailed: false,
+        manualExtensionInstallNeeded: false,
+        nextSteps: manualPlanSteps(input.plan),
+      },
+    }
+  }
+
+  const mutations: Mutation[] = []
+  const settingsDir = path.join(input.projectRoot, '.inspecto')
+  const settingsFileName = input.options.shared ? 'settings.json' : 'settings.local.json'
+  const promptsFileName = input.options.shared ? 'prompts.json' : 'prompts.local.json'
+  const settingsPath = path.join(settingsDir, settingsFileName)
+  const promptsPath = path.join(settingsDir, promptsFileName)
+  const runtimePackages = resolveRuntimePackages()
+  const installCmd = getInstallCommand(input.packageManager, runtimePackages.installSpec)
+  const nextSteps: string[] = []
+
+  let installFailed = false
+  if (input.options.skipInstall) {
+    reporter.warn('Skipping dependency installation (--skip-install)')
+  } else if (input.options.dryRun) {
+    reporter.dryRun(`Would run: ${installCmd}`)
+  } else {
+    const spinner = createSpinner(
+      `Installing devDependencies via: ${installCmd}`,
+      input.options.quiet,
+    )
+    try {
+      spinner.start()
+      await shell(installCmd, input.projectRoot)
+      spinner.succeed('Dependencies installed successfully')
+      reporter.success('Installed @inspecto-dev/plugin and @inspecto-dev/core as devDependencies')
+      for (const name of runtimePackages.installedDependencyNames) {
+        mutations.push({ type: 'dependency_added', name, dev: true })
+      }
+    } catch (error: any) {
+      spinner.fail('Dependency installation failed')
+      installFailed = true
+      reporter.error(`Failed to install dependency: ${error?.message || 'Unknown error'}`)
+      reporter.hint(`Run manually in ${input.projectRoot}: ${installCmd}`)
+      reporter.hint(
+        'Setup will continue without dependencies, but Inspecto may not run until installation succeeds.',
+      )
+    }
+  }
+
+  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 (await exists(settingsPath)) {
+    const existingSettings = await readJSON(settingsPath)
+    if (existingSettings === null) {
+      reporter.warn(`.inspecto/${settingsFileName} exists but contains invalid JSON`)
+      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)`)
+    }
+  } else {
+    const defaultSettings: Record<string, unknown> = {}
+
+    if (input.selectedIDE?.supported) {
+      defaultSettings.ide =
+        input.selectedIDE.ide.toLowerCase() === 'vscode'
+          ? 'vscode'
+          : input.selectedIDE.ide.toLowerCase()
+    }
+
+    if (input.providerDefault) {
+      defaultSettings['provider.default'] = input.providerDefault
+    }
+
+    if (input.options.dryRun) {
+      reporter.dryRun(`Would create .inspecto/${settingsFileName}`)
+    } else {
+      await writeJSON(settingsPath, defaultSettings)
+      reporter.success(`Created .inspecto/${settingsFileName}`)
+      mutations.push({ type: 'file_created', path: `.inspecto/${settingsFileName}` })
+    }
+  }
+
+  if (await exists(promptsPath)) {
+    reporter.success(`.inspecto/${promptsFileName} already exists (skipped)`)
+  } else if (input.options.dryRun) {
+    reporter.dryRun(`Would create .inspecto/${promptsFileName}`)
+  } else {
+    await writeJSON(promptsPath, [])
+    reporter.success(`Created .inspecto/${promptsFileName}`)
+    mutations.push({ type: 'file_created', path: `.inspecto/${promptsFileName}` })
+  }
+
+  if (!input.options.dryRun) {
+    await updateGitignore(
+      input.projectRoot,
+      input.options.shared,
+      input.options.dryRun,
+      input.options.quiet ?? false,
+    )
+    mutations.push({
+      type: 'file_modified',
+      path: '.gitignore',
+      description: 'Appended .inspecto/ ignore rules',
+    })
+  } else {
+    reporter.dryRun('Would update .gitignore')
+  }
+
+  if (!input.options.dryRun && mutations.length > 0) {
+    const lock: InstallLock = {
+      version: '1.0.0',
+      created_at: new Date().toISOString(),
+      mutations,
+    }
+    await writeJSON(path.join(settingsDir, 'install.lock'), lock)
+  }
+
+  const shouldInstallExt =
+    !input.options.noExtension && (!input.selectedIDE || input.selectedIDE.supported)
+  let manualExtensionInstallNeeded = false
+
+  if (input.options.noExtension) {
+    reporter.warn('Skipping IDE extension (--no-extension)')
+  } else if (shouldInstallExt) {
+    const extMutation = await installExtension(
+      input.options.dryRun,
+      input.selectedIDE?.ide,
+      input.options.quiet ?? false,
+    )
+    if (extMutation && !input.options.dryRun) {
+      mutations.push(extMutation)
+
+      if (extMutation.manual_action_required) {
+        manualExtensionInstallNeeded = true
+      }
+
+      const lockPath = path.join(settingsDir, 'install.lock')
+      const lock = await readJSON<InstallLock>(lockPath)
+      if (lock) {
+        lock.mutations = mutations
+        await writeJSON(lockPath, lock)
+      }
+    } else if (extMutation === null && !input.options.dryRun) {
+      manualExtensionInstallNeeded = true
+    }
+  }
+
+  if (!input.options.dryRun) {
+    if (installFailed) {
+      nextSteps.push(`Install dependencies manually in ${input.projectRoot}: ${installCmd}`)
+    }
+    if (injectionFailed) {
+      nextSteps.push(
+        'Plugin injection skipped. Follow manual instructions printed above to update your config.',
+      )
+    }
+    if (manualExtensionInstallNeeded) {
+      nextSteps.push('Install the Inspecto IDE extension manually')
+    }
+    if (input.manualConfigRequiredFor === 'Nuxt') {
+      nextSteps.push(
+        'Nuxt detected—please follow the Nuxt instructions printed above to finish setup.',
+      )
+    } else if (input.manualConfigRequiredFor === 'Next.js') {
+      nextSteps.push(
+        'Next.js detected—please follow the Next.js instructions printed above to finish setup.',
+      )
+    }
+  }
+
+  return {
+    status: resultStatus(nextSteps),
+    mutations,
+    postInstall: {
+      installFailed,
+      injectionFailed,
+      manualExtensionInstallNeeded,
+      nextSteps,
+    },
+  }
+}

package/src/onboarding/context.ts

@@ -0,0 +1,36 @@
+import { detectBuildTools } from '../detect/build-tool.js'
+import { detectFrameworks } from '../detect/framework.js'
+import { detectIDE } from '../detect/ide.js'
+import { detectPackageManager } from '../detect/package-manager.js'
+import { detectProviders } from '../detect/provider.js'
+import type { OnboardingContext } from '../types.js'
+
+export async function buildOnboardingContext(root: string): Promise<OnboardingContext> {
+  const [packageManager, buildTools, frameworks, ides, providers] = await Promise.all([
+    detectPackageManager(root),
+    detectBuildTools(root),
+    detectFrameworks(root),
+    detectIDE(root),
+    detectProviders(root),
+  ])
+
+  return {
+    root,
+    packageManager,
+    buildTools: {
+      supported: buildTools.supported,
+      unsupported: buildTools.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,
+    })),
+  }
+}

package/src/onboarding/planner.ts

@@ -0,0 +1,284 @@
+import { buildOnboardingContext } from './context.js'
+import type {
+  CommandMessage,
+  CommandStatus,
+  DetectionResult,
+  OnboardingContext,
+  PlanResult,
+} from '../types.js'
+
+function message(code: string, message: string): CommandMessage {
+  return { code, message }
+}
+
+function uniqueMessages(messages: CommandMessage[]): CommandMessage[] {
+  const seen = new Set<string>()
+  return messages.filter(item => {
+    const key = `${item.code}:${item.message}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}
+
+function detectionStatus(warnings: CommandMessage[], blockers: CommandMessage[]): CommandStatus {
+  if (blockers.length > 0) return 'blocked'
+  if (warnings.length > 0) return 'warning'
+  return 'ok'
+}
+
+function planStatus(warnings: CommandMessage[], blockers: CommandMessage[]): CommandStatus {
+  if (blockers.length > 0) return 'blocked'
+  if (warnings.length > 0) return 'warning'
+  return 'ok'
+}
+
+function supportedIde(context: OnboardingContext): string | undefined {
+  return context.ides.find(ide => ide.supported)?.ide
+}
+
+function supportedProvider(context: OnboardingContext): string | undefined {
+  return context.providers.find(provider => provider.supported)?.id
+}
+
+function buildToolBlockers(context: OnboardingContext): CommandMessage[] {
+  if (context.buildTools.unsupported.length > 0) {
+    return [
+      message(
+        'unsupported-build-tool',
+        `Detected unsupported build tool(s): ${context.buildTools.unsupported.join(', ')}`,
+      ),
+    ]
+  }
+
+  if (context.buildTools.supported.length > 0) {
+    if (context.buildTools.supported.length === 1) {
+      return []
+    }
+
+    const targets = context.buildTools.supported
+      .map(target => target.packagePath ?? target.configPath)
+      .join(', ')
+
+    return [
+      message(
+        'multiple-supported-build-targets',
+        `Multiple supported build targets detected: ${targets}. Run inspecto apply from a single app/package root until explicit target selection is available.`,
+      ),
+    ]
+  }
+
+  return [message('missing-build-tool', 'No supported build tool detected')]
+}
+
+function frameworkBlockers(context: OnboardingContext): CommandMessage[] {
+  if (context.frameworks.supported.length > 0) {
+    return []
+  }
+
+  if (context.frameworks.unsupported.length > 0) {
+    return [
+      message(
+        'unsupported-framework',
+        `Detected unsupported framework(s): ${context.frameworks.unsupported.join(', ')}`,
+      ),
+    ]
+  }
+
+  return [message('missing-framework', 'No supported frontend framework detected')]
+}
+
+function unsupportedEnvironmentWarnings(context: OnboardingContext): CommandMessage[] {
+  const warnings: CommandMessage[] = []
+
+  if (context.frameworks.unsupported.length > 0 && context.frameworks.supported.length > 0) {
+    warnings.push(
+      message(
+        'unsupported-framework-present',
+        `Unsupported framework(s) also detected: ${context.frameworks.unsupported.join(', ')}`,
+      ),
+    )
+  }
+
+  const unsupportedIdes = context.ides.filter(ide => !ide.supported).map(ide => ide.ide)
+  if (unsupportedIdes.length > 0) {
+    warnings.push(
+      message('unsupported-ide', `Unsupported IDE(s) detected: ${unsupportedIdes.join(', ')}`),
+    )
+  }
+
+  const unsupportedProviders = context.providers
+    .filter(provider => !provider.supported)
+    .map(provider => provider.label)
+  if (unsupportedProviders.length > 0) {
+    warnings.push(
+      message(
+        'unsupported-provider',
+        `Unsupported provider(s) detected: ${unsupportedProviders.join(', ')}`,
+      ),
+    )
+  }
+
+  return warnings
+}
+
+function manualBuildToolActions(context: OnboardingContext): PlanResult['actions'] {
+  if (context.buildTools.unsupported.length > 0) {
+    return [
+      {
+        type: 'manual_step',
+        target: context.buildTools.unsupported.join(', '),
+        description:
+          'Inspecto cannot auto-configure this build stack yet. Follow the manual setup guide for the detected framework or build tool.',
+      },
+    ]
+  }
+
+  if (context.buildTools.supported.length > 1) {
+    const targets = context.buildTools.supported
+      .map(target => target.packagePath ?? target.configPath)
+      .join(', ')
+
+    return [
+      {
+        type: 'manual_step',
+        target: targets,
+        description:
+          'Run inspecto apply from the target app/package root. Root-level apply is blocked when multiple supported targets are detected.',
+      },
+    ]
+  }
+
+  return [
+    {
+      type: 'manual_step',
+      target: context.root,
+      description:
+        'No supported build tool was detected. Add a supported build config before trying Inspecto again.',
+    },
+  ]
+}
+
+function manualFrameworkActions(context: OnboardingContext): PlanResult['actions'] {
+  if (context.frameworks.unsupported.length > 0) {
+    return [
+      {
+        type: 'manual_step',
+        target: context.frameworks.unsupported.join(', '),
+        description:
+          'Inspecto cannot auto-configure this framework yet. Follow the manual setup guide for the detected framework.',
+      },
+    ]
+  }
+
+  return [
+    {
+      type: 'manual_step',
+      target: context.root,
+      description:
+        'No supported frontend framework was detected. Add a supported React or Vue app before trying Inspecto again.',
+    },
+  ]
+}
+
+export async function createDetectionResult(root: string): Promise<DetectionResult> {
+  const context = await buildOnboardingContext(root)
+  const warnings = uniqueMessages([...unsupportedEnvironmentWarnings(context)])
+
+  const buildToolResult = buildToolBlockers(context)
+  const frameworkResult = frameworkBlockers(context)
+  const blockers = uniqueMessages([...buildToolResult, ...frameworkResult])
+
+  return {
+    status: detectionStatus(warnings, blockers),
+    warnings,
+    blockers,
+    project: {
+      root: context.root,
+      packageManager: context.packageManager,
+    },
+    environment: {
+      frameworks: context.frameworks.supported,
+      unsupportedFrameworks: context.frameworks.unsupported,
+      buildTools: context.buildTools.supported,
+      unsupportedBuildTools: context.buildTools.unsupported,
+      ides: context.ides,
+      providers: context.providers,
+    },
+  }
+}
+
+export function createPlanResult(context: OnboardingContext): PlanResult {
+  const warnings = uniqueMessages(unsupportedEnvironmentWarnings(context))
+  const blockers = uniqueMessages([...buildToolBlockers(context), ...frameworkBlockers(context)])
+  const actions: PlanResult['actions'] = []
+
+  let strategy: PlanResult['strategy'] = 'supported'
+
+  if (blockers.length > 0) {
+    strategy = 'manual'
+    if (
+      context.buildTools.unsupported.length > 0 ||
+      context.buildTools.supported.length === 0 ||
+      context.buildTools.supported.length > 1
+    ) {
+      actions.push(...manualBuildToolActions(context))
+    }
+    if (frameworkBlockers(context).length > 0) {
+      actions.push(...manualFrameworkActions(context))
+    }
+  } else {
+    actions.push({
+      type: 'install_dependency',
+      target: '@inspecto-dev/plugin @inspecto-dev/core',
+      description: `Install the Inspecto runtime packages with ${context.packageManager}.`,
+    })
+
+    for (const buildTool of context.buildTools.supported) {
+      actions.push({
+        type: 'modify_file',
+        target: buildTool.configPath,
+        description: `Inject the Inspecto plugin into ${buildTool.label}.`,
+      })
+    }
+
+    const ide = supportedIde(context)
+    if (ide === 'vscode') {
+      actions.push({
+        type: 'install_extension',
+        target: 'vscode',
+        description: 'Install the Inspecto VS Code extension.',
+      })
+    }
+  }
+
+  const defaults: PlanResult['defaults'] = {
+    shared: false,
+    extension: supportedIde(context) === 'vscode',
+  }
+
+  const provider = supportedProvider(context)
+  if (provider) {
+    defaults.provider = provider
+  }
+
+  const ide = supportedIde(context)
+  if (ide) {
+    defaults.ide = ide
+  }
+
+  return {
+    status: planStatus(warnings, blockers),
+    warnings,
+    blockers,
+    strategy,
+    actions,
+    defaults,
+  }
+}
+
+export function planManualFollowUp(result: PlanResult): string[] {
+  return result.actions
+    .filter(action => action.type === 'manual_step')
+    .map(action => action.description)
+}