@inspecto-dev/cli 0.2.0-alpha.4 → 0.2.0-alpha.6

package/src/onboarding/planner.ts

@@ -0,0 +1,278 @@
+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,
+  }
+}

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.
  */

package/src/types.ts

@@ -8,6 +8,22 @@ export type PackageManager = 'bun' | 'pnpm' | 'yarn' | 'npm'
 /** Supported build tools (v1) */
 export type BuildTool = 'vite' | 'webpack' | 'rspack' | 'rsbuild' | 'esbuild' | 'rollup'
 
+/** Machine-readable status for onboarding commands */
+export type CommandStatus = 'ok' | 'warning' | 'blocked' | 'error'
+
+/** Structured message emitted by onboarding commands */
+export interface CommandMessage {
+  code: string
+  message: string
+}
+
+export interface OnboardingProvider {
+  id: string
+  label: string
+  supported: boolean
+  preferredMode: 'cli' | 'extension'
+}
+
 /** Detected build tool with its config path */
 export interface BuildToolDetection {
   tool: BuildTool
@@ -22,6 +38,85 @@ export interface BuildToolDetection {
   packagePath?: string
 }
 
+/** Normalized onboarding context shared by detection/planning */
+export interface OnboardingContext {
+  root: string
+  packageManager: PackageManager
+  buildTools: {
+    supported: BuildToolDetection[]
+    unsupported: string[]
+  }
+  frameworks: {
+    supported: string[]
+    unsupported: string[]
+  }
+  ides: Array<{ ide: string; supported: boolean }>
+  providers: OnboardingProvider[]
+}
+
+/** Machine-readable detection output for skill-first onboarding */
+export interface DetectionResult {
+  status: CommandStatus
+  warnings: CommandMessage[]
+  blockers: CommandMessage[]
+  project: {
+    root: string
+    packageManager: PackageManager
+  }
+  environment: {
+    frameworks: string[]
+    unsupportedFrameworks: string[]
+    buildTools: BuildToolDetection[]
+    unsupportedBuildTools: string[]
+    ides: Array<{ ide: string; supported: boolean }>
+    providers: OnboardingProvider[]
+  }
+}
+
+/** Machine-readable onboarding plan output */
+export interface PlanResult {
+  status: CommandStatus
+  warnings: CommandMessage[]
+  blockers: CommandMessage[]
+  strategy: 'supported' | 'manual' | 'unsupported'
+  actions: Array<{
+    type: 'install_dependency' | 'modify_file' | 'install_extension' | 'manual_step'
+    target: string
+    description: string
+  }>
+  defaults: {
+    provider?: string
+    ide?: string
+    shared: boolean
+    extension: boolean
+  }
+}
+
+/** A single doctor diagnostic check/result */
+export interface DoctorDiagnostic {
+  code: string
+  status: 'ok' | 'warning' | 'error'
+  message: string
+  hints: string[]
+  details?: Record<string, unknown>
+}
+
+/** Machine-readable diagnostics output for `inspecto doctor` */
+export interface DoctorResult {
+  status: CommandStatus
+  summary: {
+    errors: number
+    warnings: number
+  }
+  project: {
+    root: string
+    packageManager?: PackageManager
+  }
+  errors: DoctorDiagnostic[]
+  warnings: DoctorDiagnostic[]
+  checks: DoctorDiagnostic[]
+}
+
 /** Options passed to `inspecto init` */
 export interface InitOptions {
   shared: boolean

package/src/utils/fs.ts

@@ -55,7 +55,8 @@ export async function removeDir(dirPath: string): Promise<void> {
 /** Read and parse JSON file */
 export async function readJSON<T = unknown>(filePath: string): Promise<T | null> {
   const text = await readFile(filePath)
-  if (!text) return null
+  if (text === null) return null
+  if (text.trim() === '') return {} as T
   try {
     return JSON.parse(text) as T
   } catch {

package/src/utils/logger.ts

@@ -57,6 +57,15 @@ export const log = {
     console.log()
   },
 
+  /** Copy-friendly code block without box characters */
+  copyableCodeBlock(lines: string[]) {
+    console.log()
+    for (const line of lines) {
+      console.log(`      ${line}`)
+    }
+    console.log()
+  },
+
   /** Dry-run prefix */
   dryRun(text: string) {
     console.log(`  ${pc.blue('[dry-run]')} ${text}`)

package/src/utils/output.ts

@@ -0,0 +1,40 @@
+import { log } from './logger.js'
+
+interface ReportCommandErrorOptions {
+  debug?: boolean
+  json?: boolean
+}
+
+export function writeCommandOutput<T>(result: T, json: boolean, renderText: (value: T) => void): T {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2))
+    return result
+  }
+
+  renderText(result)
+  return result
+}
+
+export function reportCommandError(error: unknown, options: ReportCommandErrorOptions = {}): void {
+  const message = error instanceof Error ? error.message : String(error)
+  const stack = error instanceof Error ? error.stack : undefined
+
+  if (options.json) {
+    const payload = {
+      status: 'error' as const,
+      error: {
+        message,
+        ...(options.debug && stack ? { stack } : {}),
+      },
+    }
+
+    console.error(JSON.stringify(payload, null, 2))
+    return
+  }
+
+  log.error(message)
+
+  if (options.debug && stack) {
+    console.error(stack)
+  }
+}