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

package/dist/index.d.ts

@@ -2,6 +2,188 @@
 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';
+/** 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;
+    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;
+}
+/** 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;
+    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 +212,61 @@ 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>;
+
+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>;
 
+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 OnboardCommandResult, type OnboardStatus, type PackageManager, type ResolvedOnboardingSession, apply, collectDoctorResult, detect, doctor, init, onboard, plan, reportCommandError, teardown, writeCommandOutput };

package/dist/index.js

@@ -1,10 +1,24 @@
 import {
+  apply,
+  collectDoctorResult,
+  detect,
   doctor,
   init,
-  teardown
-} from "./chunk-MIHQGC3L.js";
+  onboard,
+  plan,
+  reportCommandError,
+  teardown,
+  writeCommandOutput
+} from "./chunk-FZS2TLXQ.js";
 export {
+  apply,
+  collectDoctorResult,
+  detect,
   doctor,
   init,
-  teardown
+  onboard,
+  plan,
+  reportCommandError,
+  teardown,
+  writeCommandOutput
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inspecto-dev/cli",
-  "version": "0.2.0-alpha.5",
+  "version": "0.3.0-alpha.1",
   "description": "CLI tools for Inspecto onboarding and lifecycle management",
   "keywords": [
     "inspecto",
@@ -17,9 +17,10 @@
   "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"
+    "@inspecto-dev/types": "0.3.0-alpha.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/bin.ts

@@ -4,22 +4,34 @@
 // 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 { onboard } from './commands/onboard.js'
+import { plan } from './commands/plan.js'
 import { teardown } from './commands/teardown.js'
-import { log } from './utils/logger.js'
+import {
+  type InstallIntegrationOptions,
+  installIntegration,
+  printIntegrationList,
+  printIntegrationPath,
+} from './commands/integration-install.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 +42,282 @@ 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
+}
+
+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,
+    json: options.json ?? false,
   })
+  process.exit(1)
+}
+
+export function createCli(_argv: readonly string[] = process.argv): CAC {
+  const cli: CAC = cac('inspecto')
 
-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)
+  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
+    .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 })
+    .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)
+      }
+    })
+
+  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
+    .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}`)
     }
-  })
+  }
 
-cli.help()
-cli.version(version)
+  if (options.mode) {
+    if (isIntegrationMode(options.mode)) {
+      resolved.mode = options.mode
+    } else {
+      throw new Error(`Unknown integration mode: ${options.mode}`)
+    }
+  }
 
-try {
-  cli.parse()
-} catch (err) {
-  log.error(err instanceof Error ? err.message : String(err))
-  process.exit(1)
+  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]
+
+  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()
 }