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

package/dist/index.d.ts

@@ -4,6 +4,8 @@ type PackageManager = 'bun' | 'pnpm' | 'yarn' | 'npm';
 type BuildTool = 'vite' | 'webpack' | 'rspack' | 'rsbuild' | 'esbuild' | 'rollup';
 /** Machine-readable status for onboarding commands */
 type CommandStatus = 'ok' | 'warning' | 'blocked' | 'error';
+/** Assistant-facing status for single-entry onboarding */
+type OnboardStatus = 'success' | 'partial_success' | 'needs_target_selection' | 'needs_confirmation' | 'error';
 /** Structured message emitted by onboarding commands */
 interface CommandMessage {
     code: string;
@@ -28,6 +30,98 @@ interface BuildToolDetection {
     /** Relative package path when using --packages */
     packagePath?: string;
 }
+/** Normalized onboarding context shared by detection/planning */
+interface OnboardingContext {
+    root: string;
+    packageManager: PackageManager;
+    buildTools: {
+        supported: BuildToolDetection[];
+        unsupported: string[];
+    };
+    frameworks: {
+        supported: string[];
+        unsupported: string[];
+    };
+    ides: Array<{
+        ide: string;
+        supported: boolean;
+    }>;
+    providers: OnboardingProvider[];
+}
+interface OnboardingTargetCandidate {
+    packagePath: string;
+    configPath: string;
+    buildTool: BuildTool;
+    frameworks: string[];
+    automaticInjection: boolean;
+}
+interface OnboardingTargetResolution {
+    status: 'resolved' | 'needs_selection';
+    selected?: OnboardingTargetCandidate;
+    candidates: OnboardingTargetCandidate[];
+    reason: string;
+}
+interface OnboardingSummary {
+    headline: string;
+    changes: string[];
+    risks: string[];
+    manualFollowUp: string[];
+}
+interface OnboardingConfirmation {
+    required: boolean;
+    reason?: string;
+    question?: string;
+}
+interface OnboardingExecutionResult {
+    changedFiles: string[];
+    installedDependencies: string[];
+    selectedProviderDefault?: string;
+    selectedIDE?: string;
+    mutations: Mutation[];
+}
+interface OnboardingDiagnostics {
+    warnings: string[];
+    errors: string[];
+    nextSteps: string[];
+}
+interface OnboardingIdeExtensionStatus {
+    required: boolean;
+    installed: boolean;
+    manualRequired: boolean;
+    installCommand?: string;
+    marketplaceUrl?: string;
+    openVsxUrl?: string;
+}
+interface OnboardingVerification {
+    available: boolean;
+    devCommand?: string;
+    message: string;
+}
+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;
+}
+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 */
 interface DetectionResult {
     status: CommandStatus;
@@ -151,6 +245,17 @@ interface DoctorCommandOptions {
 declare function collectDoctorResult(root?: string): Promise<DoctorResult>;
 declare function doctor(options?: DoctorCommandOptions | boolean): Promise<DoctorResult>;
 
+interface OnboardCommandOptions {
+    json?: boolean;
+    target?: string;
+    yes?: boolean;
+    shared?: boolean;
+    skipInstall?: boolean;
+    dryRun?: boolean;
+    noExtension?: boolean;
+}
+declare function onboard(options?: OnboardCommandOptions): Promise<OnboardCommandResult>;
+
 declare function plan(json?: boolean): Promise<PlanResult>;
 
 declare function teardown(): Promise<void>;
@@ -164,4 +269,4 @@ declare function reportCommandError(error: unknown, options?: ReportCommandError
 
 type Framework = 'react' | 'vue';
 
-export { type BuildTool, type DoctorDiagnostic, type DoctorResult, type Framework, type InitOptions, type InstallLock, type PackageManager, apply, collectDoctorResult, detect, doctor, init, plan, reportCommandError, teardown, writeCommandOutput };
+export { type BuildTool, type DoctorDiagnostic, type DoctorResult, type Framework, type InitOptions, type InstallLock, type OnboardCommandResult, type OnboardStatus, type PackageManager, type ResolvedOnboardingSession, apply, collectDoctorResult, detect, doctor, init, onboard, plan, reportCommandError, teardown, writeCommandOutput };

package/dist/index.js

@@ -4,17 +4,19 @@ import {
   detect,
   doctor,
   init,
+  onboard,
   plan,
   reportCommandError,
   teardown,
   writeCommandOutput
-} from "./chunk-PDDFPQJS.js";
+} from "./chunk-IBYH7QZM.js";
 export {
   apply,
   collectDoctorResult,
   detect,
   doctor,
   init,
+  onboard,
   plan,
   reportCommandError,
   teardown,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inspecto-dev/cli",
-  "version": "0.2.0-alpha.6",
+  "version": "0.3.0",
   "description": "CLI tools for Inspecto onboarding and lifecycle management",
   "keywords": [
     "inspecto",
@@ -20,7 +20,7 @@
     "ora": "^9.3.0",
     "picocolors": "^1.0.0",
     "prompts": "^2.4.2",
-    "@inspecto-dev/types": "0.2.0-alpha.4"
+    "@inspecto-dev/types": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/bin.ts

@@ -10,8 +10,15 @@ 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 { onboard } from './commands/onboard.js'
 import { plan } from './commands/plan.js'
 import { teardown } from './commands/teardown.js'
+import {
+  type InstallIntegrationOptions,
+  installIntegration,
+  printIntegrationList,
+  printIntegrationPath,
+} from './commands/integration-install.js'
 import { reportCommandError } from './utils/output.js'
 
 const require = createRequire(import.meta.url)
@@ -42,6 +49,24 @@ interface ApplyCommandOptions extends JsonCommandOptions {
   extension?: boolean
 }
 
+interface OnboardCliOptions extends JsonCommandOptions {
+  target?: string
+  yes?: boolean
+  shared?: boolean
+  skipInstall?: boolean
+  dryRun?: boolean
+  extension?: boolean
+}
+
+interface IntegrationCommandOptions extends GlobalOptions {
+  scope?: string
+  mode?: string
+  force?: boolean
+}
+
+const integrationScopes = ['project', 'user'] as const
+const integrationModes = ['instructions', 'agents', 'rules'] as const
+
 function exitWithError(error: unknown, options: JsonCommandOptions = {}): never {
   reportCommandError(error, {
     debug: options.debug ?? false,
@@ -95,6 +120,32 @@ export function createCli(_argv: readonly string[] = process.argv): CAC {
       }
     })
 
+  cli
+    .command('onboard', 'Run assistant-oriented Inspecto onboarding in one structured flow')
+    .option('--json', 'Print machine-readable JSON output', { default: false })
+    .option('--target <packagePath>', 'Select a monorepo target package explicitly')
+    .option('--yes', 'Accept a lightweight confirmation gate automatically', { 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: OnboardCliOptions) => {
+      try {
+        await onboard({
+          json: options.json ?? false,
+          ...(options.target && { target: options.target }),
+          yes: options.yes ?? 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('detect', 'Detect whether the current project can be onboarded automatically')
     .option('--json', 'Print machine-readable JSON output', { default: false })
@@ -152,12 +203,109 @@ export function createCli(_argv: readonly string[] = process.argv): CAC {
       }
     })
 
+  cli
+    .command('integrations [...args]', 'Manage assistant integration assets')
+    .option(
+      '--scope <scope>',
+      'Set install scope for supported assistants (e.g. claude-code: project|user)',
+    )
+    .option(
+      '--mode <mode>',
+      'Set install mode for supported assistants (e.g. copilot: instructions|agents)',
+    )
+    .option('--force', 'Overwrite existing integration files', { default: false })
+    .option('--debug', 'Enable debug mode to show full error traces', { default: false })
+    .action(async (args: string[], options: IntegrationCommandOptions) => {
+      try {
+        const [subcommand, assistant, ...rest] = args
+        const integrationOptions = buildIntegrationOptions(options)
+
+        if (subcommand === 'list') {
+          if (assistant || rest.length > 0 || options.scope || options.mode || options.force) {
+            throw new Error(
+              'The `list` subcommand does not accept assistant names, --scope, --mode, or --force.',
+            )
+          }
+
+          printIntegrationList()
+          return
+        }
+
+        if (subcommand === 'path' && assistant) {
+          if (rest.length > 0) {
+            throw new Error('The `path` subcommand accepts exactly one assistant argument.')
+          }
+
+          if (options.force) {
+            throw new Error('The `path` subcommand does not support `--force`.')
+          }
+
+          printIntegrationPath(assistant, integrationOptions)
+          return
+        }
+
+        if (subcommand !== 'install' || !assistant) {
+          throw new Error(
+            [
+              'Usage:',
+              '  inspecto integrations list',
+              '  inspecto integrations path <assistant> [--scope <scope>] [--mode <mode>]',
+              '  inspecto integrations install <assistant> [--scope <scope>] [--mode <mode>] [--force]',
+            ].join('\n'),
+          )
+        }
+
+        if (rest.length > 0) {
+          throw new Error('The `install` subcommand accepts exactly one assistant argument.')
+        }
+
+        await installIntegration(assistant, {
+          ...integrationOptions,
+          force: options.force ?? false,
+        })
+      } catch (error) {
+        exitWithError(error, options)
+      }
+    })
+
   cli.help()
   cli.version(version)
 
   return cli
 }
 
+function buildIntegrationOptions(options: IntegrationCommandOptions): InstallIntegrationOptions {
+  const resolved: InstallIntegrationOptions = {}
+
+  if (options.scope) {
+    if (isIntegrationScope(options.scope)) {
+      resolved.scope = options.scope
+    } else {
+      throw new Error(`Unknown integration scope: ${options.scope}`)
+    }
+  }
+
+  if (options.mode) {
+    if (isIntegrationMode(options.mode)) {
+      resolved.mode = options.mode
+    } else {
+      throw new Error(`Unknown integration mode: ${options.mode}`)
+    }
+  }
+
+  return resolved
+}
+
+function isIntegrationScope(
+  value: string,
+): value is NonNullable<InstallIntegrationOptions['scope']> {
+  return (integrationScopes as readonly string[]).includes(value)
+}
+
+function isIntegrationMode(value: string): value is NonNullable<InstallIntegrationOptions['mode']> {
+  return (integrationModes as readonly string[]).includes(value)
+}
+
 export async function runCli(argv: readonly string[] = process.argv): Promise<void> {
   const cli = createCli(argv)
   const parsedArgv = [...argv]

package/src/commands/apply.ts

@@ -74,7 +74,11 @@ function printApplyResult(result: ApplyCommandResult): void {
     return
   }
 
-  log.ready('Ready! Hold Alt + Click any element to inspect.')
+  log.ready('Ready! Inspecto is set up.')
+  log.info('Next:')
+  log.hint('1. Start or restart your dev server.')
+  log.hint('2. Open your app in the browser.')
+  log.hint('3. Hold Alt + Click any element to inspect.')
 }
 
 export async function apply(options: ApplyCommandOptions = {}): Promise<ApplyCommandResult> {

package/src/commands/init.ts

@@ -16,6 +16,7 @@ import { detectIDE } from '../detect/ide.js'
 import { detectProviders, type ProviderDetection } from '../detect/provider.js'
 import { applyOnboardingPlan } from '../onboarding/apply.js'
 import type { InitOptions, Mutation, BuildToolDetection } from '../types.js'
+import { resolveOnboardingTarget } from '../onboarding/target-resolution.js'
 import {
   promptIDEChoice,
   promptProviderChoice,
@@ -70,29 +71,42 @@ export async function init(options: InitOptions): Promise<void> {
   )
 
   if (verifiedPackages.length === 0) {
-    const monorepoTargets = Array.from(
-      new Set(
-        buildResult.supported.map(d => d.packagePath).filter((value): value is string => !!value),
-      ),
-    )
-
-    if (monorepoTargets.length > 1) {
-      log.warn('Monorepo root detected with multiple candidate apps.')
-      const selectedPackage = await promptMonorepoPackageChoice(buildResult.supported)
-      if (!selectedPackage) {
-        log.hint('Run `inspecto init` inside the target app, or pass --packages <app-path>.')
-        return
+    const monorepoCandidates = buildResult.supported.filter(detection => !!detection.packagePath)
+    if (monorepoCandidates.length > 0) {
+      const frameworkSupportByPackage = await detectFrameworkSupportByPackage(
+        repoRoot,
+        monorepoCandidates,
+      )
+      const targetResolution = resolveOnboardingTarget({
+        repoRoot,
+        buildTools: monorepoCandidates,
+        frameworkSupportByPackage,
+      })
+
+      if (targetResolution.status === 'needs_selection') {
+        log.warn('Monorepo root detected with multiple candidate apps.')
+        const selectedPackage = await promptMonorepoPackageChoice(
+          monorepoCandidates.filter(detection =>
+            targetResolution.candidates.some(
+              candidate => candidate.packagePath === (detection.packagePath ?? ''),
+            ),
+          ),
+        )
+        if (!selectedPackage) {
+          log.hint('Run `inspecto init` inside the target app, or pass --packages <app-path>.')
+          return
+        }
+
+        projectRoot = path.join(repoRoot, selectedPackage)
+        buildResult = await detectBuildTools(repoRoot, [selectedPackage])
+        log.info(`Continuing initialization in ${selectedPackage}`)
+      } else if (targetResolution.selected?.packagePath) {
+        const selectedPackage = targetResolution.selected.packagePath
+        projectRoot = path.join(repoRoot, selectedPackage)
+        buildResult = await detectBuildTools(repoRoot, [selectedPackage])
+        log.warn(`Monorepo root detected. Using the only candidate app: ${selectedPackage}`)
+        log.hint('Run `inspecto init` inside that app next time to skip this prompt.')
       }
-
-      projectRoot = path.join(repoRoot, selectedPackage)
-      buildResult = await detectBuildTools(repoRoot, [selectedPackage])
-      log.info(`Continuing initialization in ${selectedPackage}`)
-    } else if (monorepoTargets.length === 1) {
-      const [selectedPackage] = monorepoTargets
-      projectRoot = path.join(repoRoot, selectedPackage!)
-      buildResult = await detectBuildTools(repoRoot, [selectedPackage!])
-      log.warn(`Monorepo root detected. Using the only candidate app: ${selectedPackage}`)
-      log.hint('Run `inspecto init` inside that app next time to skip this prompt.')
     }
   }
 
@@ -310,7 +324,11 @@ export async function init(options: InitOptions): Promise<void> {
       log.hint('Complete the items above.')
       log.blank()
     } else {
-      log.ready('Ready! Hold Alt + Click any element to inspect.')
+      log.ready('Ready! Inspecto is set up.')
+      log.info('Next:')
+      log.hint('1. Start or restart your dev server.')
+      log.hint('2. Open your app in the browser.')
+      log.hint('3. Hold Alt + Click any element to inspect.')
     }
   }
 }
@@ -344,3 +362,22 @@ function matchesAnyPackage(detection: BuildToolDetection, packages: string[]): b
   if (packages.length === 0) return true
   return packages.some(pkg => matchesPackage(detection, pkg))
 }
+
+async function detectFrameworkSupportByPackage(
+  repoRoot: string,
+  buildTools: BuildToolDetection[],
+): Promise<Record<string, string[]>> {
+  const packagePaths = Array.from(
+    new Set(buildTools.map(buildTool => buildTool.packagePath).filter((value): value is string => !!value)),
+  )
+  const supportByPackage: Record<string, string[]> = {}
+
+  await Promise.all(
+    packagePaths.map(async packagePath => {
+      const result = await detectFrameworks(path.join(repoRoot, packagePath))
+      supportByPackage[packagePath] = result.supported
+    }),
+  )
+
+  return supportByPackage
+}