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

package/src/types.ts

@@ -8,6 +8,30 @@ 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'
+
+/** Assistant-facing status for single-entry onboarding */
+export type OnboardStatus =
+  | 'success'
+  | 'partial_success'
+  | 'needs_target_selection'
+  | 'needs_confirmation'
+  | '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 +46,166 @@ 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[]
+}
+
+export interface OnboardingTargetCandidate {
+  packagePath: string
+  configPath: string
+  buildTool: BuildTool
+  frameworks: string[]
+  automaticInjection: boolean
+}
+
+export interface OnboardingTargetResolution {
+  status: 'resolved' | 'needs_selection'
+  selected?: OnboardingTargetCandidate
+  candidates: OnboardingTargetCandidate[]
+  reason: string
+}
+
+export interface OnboardingSummary {
+  headline: string
+  changes: string[]
+  risks: string[]
+  manualFollowUp: string[]
+}
+
+export interface OnboardingConfirmation {
+  required: boolean
+  reason?: string
+  question?: string
+}
+
+export interface OnboardingExecutionResult {
+  changedFiles: string[]
+  installedDependencies: string[]
+  selectedProviderDefault?: string
+  selectedIDE?: string
+  mutations: Mutation[]
+}
+
+export interface OnboardingDiagnostics {
+  warnings: string[]
+  errors: string[]
+  nextSteps: string[]
+}
+
+export interface OnboardingIdeExtensionStatus {
+  required: boolean
+  installed: boolean
+  manualRequired: boolean
+  installCommand?: string
+  marketplaceUrl?: string
+  openVsxUrl?: string
+}
+
+export interface OnboardingVerification {
+  available: boolean
+  devCommand?: string
+  message: string
+}
+
+export interface ResolvedOnboardingSession {
+  status: OnboardStatus
+  target: OnboardingTargetResolution
+  summary: OnboardingSummary
+  confirmation: OnboardingConfirmation
+  verification: OnboardingVerification
+  context: OnboardingContext
+  plan: PlanResult
+  projectRoot: string
+  selectedIDE?: { ide: string; supported: boolean } | null
+  providerDefault?: string
+}
+
+export interface OnboardCommandResult {
+  status: OnboardStatus
+  target: OnboardingTargetResolution
+  summary: OnboardingSummary
+  confirmation: OnboardingConfirmation
+  ideExtension?: OnboardingIdeExtensionStatus
+  verification?: OnboardingVerification
+  result?: OnboardingExecutionResult
+  diagnostics?: OnboardingDiagnostics
+}
+
+/** 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)
+  }
+}