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

package/dist/index.d.ts

@@ -2,6 +2,94 @@
 type PackageManager = 'bun' | 'pnpm' | 'yarn' | 'npm';
 /** Supported build tools (v1) */
 type BuildTool = 'vite' | 'webpack' | 'rspack' | 'rsbuild' | 'esbuild' | 'rollup';
+/** Machine-readable status for onboarding commands */
+type CommandStatus = 'ok' | 'warning' | 'blocked' | 'error';
+/** Structured message emitted by onboarding commands */
+interface CommandMessage {
+    code: string;
+    message: string;
+}
+interface OnboardingProvider {
+    id: string;
+    label: string;
+    supported: boolean;
+    preferredMode: 'cli' | 'extension';
+}
+/** Detected build tool with its config path */
+interface BuildToolDetection {
+    tool: BuildTool;
+    configPath: string;
+    /** Human-readable label like "Vite (vite.config.ts)" */
+    label: string;
+    /** Whether this is a legacy rspack version (< 0.4.0) */
+    isLegacyRspack?: boolean;
+    /** Whether this is Webpack 4.x */
+    isLegacyWebpack?: boolean;
+    /** Relative package path when using --packages */
+    packagePath?: string;
+}
+/** Machine-readable detection output for skill-first onboarding */
+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 */
+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 */
+interface DoctorDiagnostic {
+    code: string;
+    status: 'ok' | 'warning' | 'error';
+    message: string;
+    hints: string[];
+    details?: Record<string, unknown>;
+}
+/** Machine-readable diagnostics output for `inspecto doctor` */
+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` */
 interface InitOptions {
     shared: boolean;
@@ -30,12 +118,50 @@ interface InstallLock {
     mutations: Mutation[];
 }
 
+interface ApplyOnboardingResult {
+    status: CommandStatus;
+    mutations: Mutation[];
+    postInstall: {
+        installFailed: boolean;
+        injectionFailed: boolean;
+        manualExtensionInstallNeeded: boolean;
+        nextSteps: string[];
+    };
+}
+
+interface ApplyCommandOptions {
+    json?: boolean;
+    shared?: boolean;
+    skipInstall?: boolean;
+    dryRun?: boolean;
+    noExtension?: boolean;
+}
+interface ApplyCommandResult extends ApplyOnboardingResult {
+    plan: PlanResult;
+}
+declare function apply(options?: ApplyCommandOptions): Promise<ApplyCommandResult>;
+
+declare function detect(json?: boolean): Promise<DetectionResult>;
+
 declare function init(options: InitOptions): Promise<void>;
 
-declare function doctor(): Promise<void>;
+interface DoctorCommandOptions {
+    json?: boolean;
+}
+declare function collectDoctorResult(root?: string): Promise<DoctorResult>;
+declare function doctor(options?: DoctorCommandOptions | boolean): Promise<DoctorResult>;
+
+declare function plan(json?: boolean): Promise<PlanResult>;
 
 declare function teardown(): Promise<void>;
 
+interface ReportCommandErrorOptions {
+    debug?: boolean;
+    json?: boolean;
+}
+declare function writeCommandOutput<T>(result: T, json: boolean, renderText: (value: T) => void): T;
+declare function reportCommandError(error: unknown, options?: ReportCommandErrorOptions): void;
+
 type Framework = 'react' | 'vue';
 
-export { type BuildTool, type Framework, type InitOptions, type InstallLock, type PackageManager, doctor, init, teardown };
+export { type BuildTool, type DoctorDiagnostic, type DoctorResult, type Framework, type InitOptions, type InstallLock, type PackageManager, apply, collectDoctorResult, detect, doctor, init, plan, reportCommandError, teardown, writeCommandOutput };

package/dist/index.js

@@ -1,10 +1,22 @@
 import {
+  apply,
+  collectDoctorResult,
+  detect,
   doctor,
   init,
-  teardown
-} from "./chunk-EUCQCD3Y.js";
+  plan,
+  reportCommandError,
+  teardown,
+  writeCommandOutput
+} from "./chunk-PDDFPQJS.js";
 export {
+  apply,
+  collectDoctorResult,
+  detect,
   doctor,
   init,
-  teardown
+  plan,
+  reportCommandError,
+  teardown,
+  writeCommandOutput
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inspecto-dev/cli",
-  "version": "0.2.0-alpha.4",
+  "version": "0.2.0-alpha.6",
   "description": "CLI tools for Inspecto onboarding and lifecycle management",
   "keywords": [
     "inspecto",
@@ -17,6 +17,7 @@
   "dependencies": {
     "cac": "^6.7.14",
     "magicast": "^0.5.2",
+    "ora": "^9.3.0",
     "picocolors": "^1.0.0",
     "prompts": "^2.4.2",
     "@inspecto-dev/types": "0.2.0-alpha.4"

package/src/bin.ts

@@ -4,22 +4,27 @@
 // v1 scope: VS Code | React + Vue | Vite + Webpack + Rspack + esbuild + Rollup
 // ============================================================
 import { cac, type CAC } from 'cac'
+import { fileURLToPath } from 'node:url'
 import { createRequire } from 'node:module'
+import { apply } from './commands/apply.js'
+import { detect } from './commands/detect.js'
 import { init } from './commands/init.js'
 import { doctor } from './commands/doctor.js'
+import { plan } from './commands/plan.js'
 import { teardown } from './commands/teardown.js'
-import { log } from './utils/logger.js'
+import { reportCommandError } from './utils/output.js'
 
 const require = createRequire(import.meta.url)
 const { version } = require('../package.json')
 
-// cac object
-const cli: CAC = cac('inspecto')
-
 interface GlobalOptions {
   debug?: boolean
 }
 
+interface JsonCommandOptions extends GlobalOptions {
+  json?: boolean
+}
+
 interface InitCommandOptions extends GlobalOptions {
   shared?: boolean
   skipInstall?: boolean
@@ -30,74 +35,141 @@ interface InitCommandOptions extends GlobalOptions {
   force?: boolean
 }
 
-cli
-  .command('init', 'Set up Inspecto in your project')
-  .option('--shared', 'Share .inspecto/settings.json with your team via Git', { default: false })
-  .option('--skip-install', 'Skip npm dependency installation', { default: false })
-  .option('--dry-run', 'Preview changes without modifying files', { default: false })
-  .option('--provider <provider>', 'Set default provider (e.g. copilot, claude-code)')
-  .option('--no-extension', 'Skip VS Code extension installation', { default: false })
-  .option('--packages <names>', '(Monorepo) Comma-separated list of packages to inject')
-  .option('--force', 'Force initialization even if environment is unsupported', { default: false })
-  .option('--debug', 'Enable debug mode to show full error traces', { default: false })
-  .action(async (options: InitCommandOptions) => {
-    try {
-      await init({
-        shared: options.shared ?? false,
-        skipInstall: options.skipInstall ?? false,
-        dryRun: options.dryRun ?? false,
-        ...(options.provider && { provider: options.provider }), // Changed from prefer to provider
-        noExtension: options.noExtension ?? false,
-        ...(options.packages && {
-          packages: options.packages.split(',').map((s: string) => s.trim()),
-        }),
-        force: options.force ?? false,
-      })
-    } catch (err) {
-      log.error(err instanceof Error ? err.message : String(err))
-      if (options.debug && err instanceof Error && err.stack) {
-        console.error(err.stack)
-      }
-      process.exit(1)
-    }
+interface ApplyCommandOptions extends JsonCommandOptions {
+  shared?: boolean
+  skipInstall?: boolean
+  dryRun?: boolean
+  extension?: boolean
+}
+
+function exitWithError(error: unknown, options: JsonCommandOptions = {}): never {
+  reportCommandError(error, {
+    debug: options.debug ?? false,
+    json: options.json ?? false,
   })
+  process.exit(1)
+}
 
-cli
-  .command('doctor', 'Diagnose your Inspecto installation')
-  .option('--debug', 'Enable debug mode to show full error traces', { default: false })
-  .action(async (options: GlobalOptions) => {
-    try {
-      await doctor()
-    } catch (err) {
-      log.error(err instanceof Error ? err.message : String(err))
-      if (options.debug && err instanceof Error && err.stack) {
-        console.error(err.stack)
+export function createCli(_argv: readonly string[] = process.argv): CAC {
+  const cli: CAC = cac('inspecto')
+
+  cli
+    .command('init', 'Set up Inspecto in your project')
+    .option('--shared', 'Share .inspecto/settings.json with your team via Git', { default: false })
+    .option('--skip-install', 'Skip npm dependency installation', { default: false })
+    .option('--dry-run', 'Preview changes without modifying files', { default: false })
+    .option('--provider <provider>', 'Set default provider (e.g. copilot, claude-code)')
+    .option('--no-extension', 'Skip VS Code extension installation', { default: false })
+    .option('--packages <names>', '(Monorepo) Comma-separated list of packages to inject')
+    .option('--force', 'Force initialization even if environment is unsupported', {
+      default: false,
+    })
+    .option('--debug', 'Enable debug mode to show full error traces', { default: false })
+    .action(async (options: InitCommandOptions) => {
+      try {
+        await init({
+          shared: options.shared ?? false,
+          skipInstall: options.skipInstall ?? false,
+          dryRun: options.dryRun ?? false,
+          ...(options.provider && { provider: options.provider }),
+          noExtension: options.noExtension ?? false,
+          ...(options.packages && {
+            packages: options.packages.split(',').map((s: string) => s.trim()),
+          }),
+          force: options.force ?? false,
+        })
+      } catch (error) {
+        exitWithError(error, options)
       }
-      process.exit(1)
-    }
-  })
+    })
 
-cli
-  .command('teardown', 'Remove Inspecto from your project')
-  .option('--debug', 'Enable debug mode to show full error traces', { default: false })
-  .action(async (options: GlobalOptions) => {
-    try {
-      await teardown()
-    } catch (err) {
-      log.error(err instanceof Error ? err.message : String(err))
-      if (options.debug && err instanceof Error && err.stack) {
-        console.error(err.stack)
+  cli
+    .command('doctor', 'Diagnose your Inspecto installation')
+    .option('--json', 'Print machine-readable JSON output', { default: false })
+    .option('--debug', 'Enable debug mode to show full error traces', { default: false })
+    .action(async (options: JsonCommandOptions) => {
+      try {
+        await doctor({ json: options.json ?? false })
+      } catch (error) {
+        exitWithError(error, options)
       }
-      process.exit(1)
-    }
-  })
+    })
 
-cli.help()
-cli.version(version)
+  cli
+    .command('detect', 'Detect whether the current project can be onboarded automatically')
+    .option('--json', 'Print machine-readable JSON output', { default: false })
+    .option('--debug', 'Enable debug mode to show full error traces', { default: false })
+    .action(async (options: JsonCommandOptions) => {
+      try {
+        await detect(options.json ?? false)
+      } catch (error) {
+        exitWithError(error, options)
+      }
+    })
 
-try {
-  cli.parse()
-} catch (err) {
-  log.error(err instanceof Error ? err.message : String(err))
-  process.exit(1)
+  cli
+    .command('plan', 'Preview the onboarding plan for the current project')
+    .option('--json', 'Print machine-readable JSON output', { default: false })
+    .option('--debug', 'Enable debug mode to show full error traces', { default: false })
+    .action(async (options: JsonCommandOptions) => {
+      try {
+        await plan(options.json ?? false)
+      } catch (error) {
+        exitWithError(error, options)
+      }
+    })
+
+  cli
+    .command('apply', 'Apply the onboarding plan to the current project')
+    .option('--json', 'Print machine-readable JSON output', { default: false })
+    .option('--shared', 'Write shared Inspecto settings instead of local-only settings')
+    .option('--skip-install', 'Skip npm dependency installation')
+    .option('--dry-run', 'Preview changes without modifying files')
+    .option('--no-extension', 'Skip IDE extension installation')
+    .option('--debug', 'Enable debug mode to show full error traces', { default: false })
+    .action(async (options: ApplyCommandOptions) => {
+      try {
+        await apply({
+          json: options.json ?? false,
+          ...(options.shared !== undefined && { shared: options.shared }),
+          ...(options.skipInstall !== undefined && { skipInstall: options.skipInstall }),
+          ...(options.dryRun !== undefined && { dryRun: options.dryRun }),
+          ...(options.extension === false && { noExtension: true }),
+        })
+      } catch (error) {
+        exitWithError(error, options)
+      }
+    })
+
+  cli
+    .command('teardown', 'Remove Inspecto from your project')
+    .option('--debug', 'Enable debug mode to show full error traces', { default: false })
+    .action(async (options: GlobalOptions) => {
+      try {
+        await teardown()
+      } catch (error) {
+        exitWithError(error, options)
+      }
+    })
+
+  cli.help()
+  cli.version(version)
+
+  return cli
+}
+
+export async function runCli(argv: readonly string[] = process.argv): Promise<void> {
+  const cli = createCli(argv)
+  const parsedArgv = [...argv]
+
+  try {
+    await cli.parse(parsedArgv)
+  } catch (error) {
+    exitWithError(error, { json: argv.includes('--json') })
+  }
+}
+
+const entryPath = process.argv[1]
+if (entryPath && fileURLToPath(import.meta.url) === entryPath) {
+  void runCli()
 }

package/src/commands/apply.ts

@@ -0,0 +1,114 @@
+import { applyOnboardingPlan, type ApplyOnboardingResult } from '../onboarding/apply.js'
+import { buildOnboardingContext } from '../onboarding/context.js'
+import { createPlanResult } from '../onboarding/planner.js'
+import { log } from '../utils/logger.js'
+import { writeCommandOutput } from '../utils/output.js'
+import type { PlanResult } from '../types.js'
+
+export interface ApplyCommandOptions {
+  json?: boolean
+  shared?: boolean
+  skipInstall?: boolean
+  dryRun?: boolean
+  noExtension?: boolean
+}
+
+export interface ApplyCommandResult extends ApplyOnboardingResult {
+  plan: PlanResult
+}
+
+function getProviderDefault(
+  providerId?: string,
+  preferredMode?: 'cli' | 'extension',
+): string | undefined {
+  if (!providerId) return undefined
+  const mode = preferredMode ?? (providerId === 'coco' ? 'cli' : 'extension')
+  return `${providerId}.${mode}`
+}
+
+function statusRank(status: ApplyCommandResult['status']): number {
+  switch (status) {
+    case 'error':
+      return 3
+    case 'blocked':
+      return 2
+    case 'warning':
+      return 1
+    case 'ok':
+    default:
+      return 0
+  }
+}
+
+function mergeStatus(
+  planStatus: PlanResult['status'],
+  applyStatus: ApplyOnboardingResult['status'],
+): ApplyCommandResult['status'] {
+  return statusRank(planStatus) >= statusRank(applyStatus) ? planStatus : applyStatus
+}
+
+function printApplyResult(result: ApplyCommandResult): void {
+  const manualSteps = result.postInstall.nextSteps.filter(
+    step => !result.plan.blockers.some(blocker => blocker.message === step),
+  )
+
+  log.header('Inspecto Apply')
+  log.info(`Status: ${result.status}`)
+  log.info(`Strategy: ${result.plan.strategy}`)
+
+  for (const blocker of result.plan.blockers) {
+    log.error(blocker.message)
+  }
+  for (const warning of result.plan.warnings) {
+    log.warn(warning.message)
+  }
+
+  if (manualSteps.length > 0 || result.plan.blockers.length > 0) {
+    log.blank()
+    log.warn('──────── Manual Steps Required ────────')
+    manualSteps.forEach(step => log.error(step))
+    return
+  }
+
+  if (result.plan.warnings.length > 0) {
+    return
+  }
+
+  log.ready('Ready! Hold Alt + Click any element to inspect.')
+}
+
+export async function apply(options: ApplyCommandOptions = {}): Promise<ApplyCommandResult> {
+  const root = process.cwd()
+  const context = await buildOnboardingContext(root)
+  const plan = createPlanResult(context)
+  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
+
+  const applyResult = await applyOnboardingPlan({
+    repoRoot: root,
+    projectRoot: root,
+    packageManager: context.packageManager,
+    supportedBuildTargets: context.buildTools.supported,
+    options: {
+      shared: options.shared ?? plan.defaults.shared,
+      skipInstall: options.skipInstall ?? false,
+      dryRun: options.dryRun ?? false,
+      noExtension: options.noExtension ?? !plan.defaults.extension,
+      quiet: options.json ?? false,
+    },
+    selectedIDE,
+    providerDefault: getProviderDefault(plan.defaults.provider, selectedProvider?.preferredMode),
+    plan,
+  })
+
+  const result: ApplyCommandResult = {
+    ...applyResult,
+    status: mergeStatus(plan.status, applyResult.status),
+    plan,
+  }
+  return writeCommandOutput(result, options.json ?? false, printApplyResult)
+}

package/src/commands/detect.ts

@@ -0,0 +1,59 @@
+import { log } from '../utils/logger.js'
+import { writeCommandOutput } from '../utils/output.js'
+import { createDetectionResult } from '../onboarding/planner.js'
+import type { DetectionResult } from '../types.js'
+
+function printDetectionResult(result: DetectionResult): void {
+  const suppressedCodes = new Set([
+    'unsupported-build-tool',
+    'unsupported-build-tool-present',
+    'unsupported-framework',
+    'unsupported-framework-present',
+  ])
+
+  log.header('Inspecto Detect')
+  log.info(`Status: ${result.status}`)
+  log.info(`Root: ${result.project.root}`)
+  log.info(`Package manager: ${result.project.packageManager}`)
+
+  if (result.environment.frameworks.length > 0) {
+    log.success(`Supported frameworks: ${result.environment.frameworks.join(', ')}`)
+  }
+  if (result.environment.unsupportedFrameworks.length > 0) {
+    log.warn(`Unsupported frameworks: ${result.environment.unsupportedFrameworks.join(', ')}`)
+  }
+  if (result.environment.buildTools.length > 0) {
+    log.success(
+      `Supported build tools: ${result.environment.buildTools.map(tool => tool.label).join(', ')}`,
+    )
+  }
+  if (result.environment.unsupportedBuildTools.length > 0) {
+    log.warn(`Unsupported build tools: ${result.environment.unsupportedBuildTools.join(', ')}`)
+  }
+
+  const supportedIdes = result.environment.ides.filter(ide => ide.supported).map(ide => ide.ide)
+  if (supportedIdes.length > 0) {
+    log.success(`Supported IDEs: ${supportedIdes.join(', ')}`)
+  }
+
+  const supportedProviders = result.environment.providers
+    .filter(provider => provider.supported)
+    .map(provider => provider.label)
+  if (supportedProviders.length > 0) {
+    log.success(`Supported providers: ${supportedProviders.join(', ')}`)
+  }
+
+  for (const blocker of result.blockers) {
+    if (suppressedCodes.has(blocker.code)) continue
+    log.error(blocker.message)
+  }
+  for (const warning of result.warnings) {
+    if (suppressedCodes.has(warning.code)) continue
+    log.warn(warning.message)
+  }
+}
+
+export async function detect(json = false): Promise<DetectionResult> {
+  const result = await createDetectionResult(process.cwd())
+  return writeCommandOutput(result, json, printDetectionResult)
+}