@inspecto-dev/cli 0.3.3 → 0.3.5

package/dist/index.d.ts

@@ -49,17 +49,24 @@ interface OnboardingContext {
     providers: OnboardingProvider[];
 }
 interface OnboardingTargetCandidate {
+    id?: string;
+    candidateId?: string;
     packagePath: string;
     configPath: string;
+    label?: string;
     buildTool: BuildTool;
+    isLegacyRspack?: boolean;
+    isLegacyWebpack?: boolean;
     frameworks: string[];
     automaticInjection: boolean;
 }
 interface OnboardingTargetResolution {
-    status: 'resolved' | 'needs_selection';
+    status: 'resolved' | 'needs_selection' | 'guided';
     selected?: OnboardingTargetCandidate;
     candidates: OnboardingTargetCandidate[];
     reason: string;
+    selectionPurpose?: string;
+    selectionInstructions?: string;
 }
 interface OnboardingSummary {
     headline: string;
@@ -67,6 +74,13 @@ interface OnboardingSummary {
     risks: string[];
     manualFollowUp: string[];
 }
+interface OnboardingPatchPlan {
+    path: string;
+    status: 'planned' | 'manual_patch_required';
+    reason: string;
+    snippet: string;
+    confidence: 'high' | 'medium' | 'low';
+}
 interface OnboardingConfirmation {
     required: boolean;
     reason?: string;
@@ -97,6 +111,15 @@ interface OnboardingVerification {
     devCommand?: string;
     message: string;
 }
+interface OnboardingAssistantHandoff {
+    framework?: string;
+    metaFramework?: string;
+    routerMode?: 'app' | 'pages' | 'mixed' | 'unknown';
+    autoApplied?: string[];
+    pendingSteps?: string[];
+    assistantPrompt?: string;
+    patches?: OnboardingPatchPlan[];
+}
 interface ResolvedOnboardingSession {
     status: OnboardStatus;
     target: OnboardingTargetResolution;
@@ -111,6 +134,14 @@ interface ResolvedOnboardingSession {
         supported: boolean;
     } | null;
     providerDefault?: string;
+    framework?: string;
+    metaFramework?: string;
+    routerMode?: 'app' | 'pages' | 'mixed' | 'unknown';
+    autoApplied?: string[];
+    pendingSteps?: string[];
+    assistantPrompt?: string;
+    patches?: OnboardingPatchPlan[];
+    handoff?: OnboardingAssistantHandoff;
 }
 interface OnboardCommandResult {
     status: OnboardStatus;
@@ -121,6 +152,14 @@ interface OnboardCommandResult {
     verification?: OnboardingVerification;
     result?: OnboardingExecutionResult;
     diagnostics?: OnboardingDiagnostics;
+    framework?: string;
+    metaFramework?: string;
+    routerMode?: 'app' | 'pages' | 'mixed' | 'unknown';
+    autoApplied?: string[];
+    pendingSteps?: string[];
+    assistantPrompt?: string;
+    patches?: OnboardingPatchPlan[];
+    handoff?: OnboardingAssistantHandoff;
 }
 /** Machine-readable detection output for skill-first onboarding */
 interface DetectionResult {
@@ -148,9 +187,9 @@ interface PlanResult {
     status: CommandStatus;
     warnings: CommandMessage[];
     blockers: CommandMessage[];
-    strategy: 'supported' | 'manual' | 'unsupported';
+    strategy: 'supported' | 'guided' | 'manual' | 'unsupported';
     actions: Array<{
-        type: 'install_dependency' | 'modify_file' | 'install_extension' | 'manual_step';
+        type: 'install_dependency' | 'modify_file' | 'install_extension' | 'manual_step' | 'generate_patch_plan' | 'generate_file' | 'manual_confirmation';
         target: string;
         description: string;
     }>;
@@ -160,6 +199,13 @@ interface PlanResult {
         shared: boolean;
         extension: boolean;
     };
+    framework?: string;
+    metaFramework?: string;
+    routerMode?: 'app' | 'pages' | 'mixed' | 'unknown';
+    autoApplied?: string[];
+    pendingSteps?: string[];
+    assistantPrompt?: string;
+    patches?: OnboardingPatchPlan[];
 }
 /** A single doctor diagnostic check/result */
 interface DoctorDiagnostic {
@@ -237,6 +283,24 @@ declare function apply(options?: ApplyCommandOptions): Promise<ApplyCommandResul
 
 declare function detect(json?: boolean): Promise<DetectionResult>;
 
+interface InspectoDevConfig {
+    cliBin?: string;
+    devRepo?: string;
+}
+interface DevConfigCommandResult {
+    status: 'ok';
+    configPath: string;
+    config: InspectoDevConfig;
+}
+interface DevLinkOptions {
+    cliBin?: string;
+    devRepo?: string;
+    json?: boolean;
+}
+declare function devLink(options: DevLinkOptions): Promise<DevConfigCommandResult>;
+declare function devStatus(json?: boolean): Promise<DevConfigCommandResult>;
+declare function devUnlink(json?: boolean): Promise<DevConfigCommandResult>;
+
 declare function init(options: InitOptions): Promise<void>;
 
 interface DoctorCommandOptions {
@@ -250,6 +314,7 @@ interface IntegrationAutomationOptions {
     inspectoVsix?: string;
     preview?: boolean;
     silent?: boolean;
+    ignoreProjectArtifacts?: boolean;
 }
 interface IntegrationAutomationDetails {
     hostIde?: {
@@ -342,4 +407,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 OnboardCommandResult, type OnboardStatus, type PackageManager, type ResolvedOnboardingSession, apply, collectDoctorResult, detect, doctor, init, integrationDoctor, onboard, 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, devLink, devStatus, devUnlink, doctor, init, integrationDoctor, onboard, plan, reportCommandError, teardown, writeCommandOutput };

package/dist/index.js

@@ -2,6 +2,9 @@ import {
   apply,
   collectDoctorResult,
   detect,
+  devLink,
+  devStatus,
+  devUnlink,
   doctor,
   init,
   integrationDoctor,
@@ -10,11 +13,14 @@ import {
   reportCommandError,
   teardown,
   writeCommandOutput
-} from "./chunk-LJOKPCPD.js";
+} from "./chunk-7ABJRH3F.js";
 export {
   apply,
   collectDoctorResult,
   detect,
+  devLink,
+  devStatus,
+  devUnlink,
   doctor,
   init,
   integrationDoctor,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inspecto-dev/cli",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "CLI tools for Inspecto onboarding and lifecycle management",
   "keywords": [
     "inspecto",
@@ -20,10 +20,10 @@
     "ora": "^9.3.0",
     "picocolors": "^1.0.0",
     "prompts": "^2.4.2",
-    "@inspecto-dev/types": "0.3.3"
+    "@inspecto-dev/types": "0.3.5"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^20.19.39",
     "@types/prompts": "^2.4.9",
     "tsup": "^8.0.2",
     "typescript": "^5.4.5",

package/src/bin.ts

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url'
 import { createRequire } from 'node:module'
 import { apply } from './commands/apply.js'
 import { detect } from './commands/detect.js'
+import { devLink, devStatus, devUnlink } from './commands/dev-config.js'
 import { init } from './commands/init.js'
 import { doctor } from './commands/doctor.js'
 import { onboard } from './commands/onboard.js'
@@ -69,6 +70,11 @@ interface IntegrationCommandOptions extends JsonCommandOptions {
   force?: boolean
 }
 
+interface DevCommandOptions extends JsonCommandOptions {
+  cliBin?: string
+  repo?: string
+}
+
 const integrationScopes = ['project', 'user'] as const
 const integrationModes = ['skills', 'instructions', 'agents', 'rules'] as const
 
@@ -83,6 +89,45 @@ function exitWithError(error: unknown, options: JsonCommandOptions = {}): never
 export function createCli(_argv: readonly string[] = process.argv): CAC {
   const cli: CAC = cac('inspecto')
 
+  cli
+    .command('dev <subcommand>', 'Manage project-local Inspecto development overrides')
+    .option('--cli-bin <path>', 'Point this project at a local CLI dist/bin.js')
+    .option('--repo <path>', 'Point this project at a local Inspecto repository root')
+    .option('--json', 'Print machine-readable JSON output', { default: false })
+    .option('--debug', 'Enable debug mode to show full error traces', { default: false })
+    .action(async (subcommand: string, options: DevCommandOptions) => {
+      try {
+        if (subcommand === 'link') {
+          if (!options.cliBin && !options.repo) {
+            throw new Error('The `dev link` subcommand requires --cli-bin <path> or --repo <path>.')
+          }
+
+          await devLink({
+            ...(options.cliBin ? { cliBin: options.cliBin } : {}),
+            ...(options.repo ? { devRepo: options.repo } : {}),
+            json: options.json ?? false,
+          })
+          return
+        }
+
+        if (subcommand === 'status') {
+          await devStatus(options.json ?? false)
+          return
+        }
+
+        if (subcommand === 'unlink') {
+          await devUnlink(options.json ?? false)
+          return
+        }
+
+        throw new Error(
+          'Usage:\n  inspecto dev link [--cli-bin <path>] [--repo <path>]\n  inspecto dev status [--json]\n  inspecto dev unlink [--json]',
+        )
+      } catch (error) {
+        exitWithError(error, options)
+      }
+    })
+
   cli
     .command('init', 'Set up Inspecto in your project')
     .option('--shared', 'Share .inspecto/settings.json with your team via Git', { default: false })
@@ -128,7 +173,10 @@ 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(
+      '--target <candidateIdOrPath>',
+      'Select the build target to onboard using a returned candidateId or compatible config path',
+    )
     .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')

package/src/commands/dev-config.ts

@@ -0,0 +1,109 @@
+import path from 'node:path'
+import { readJSON, removeFile, writeJSON } from '../utils/fs.js'
+import { updateGitignore } from '../inject/gitignore.js'
+import { log } from '../utils/logger.js'
+import { writeCommandOutput } from '../utils/output.js'
+
+export interface InspectoDevConfig {
+  cliBin?: string
+  devRepo?: string
+}
+
+export interface DevConfigCommandResult {
+  status: 'ok'
+  configPath: string
+  config: InspectoDevConfig
+}
+
+interface DevLinkOptions {
+  cliBin?: string
+  devRepo?: string
+  json?: boolean
+}
+
+const DEV_CONFIG_PATH = path.join('.inspecto', 'dev.json')
+
+function absoluteDevConfigPath(root: string): string {
+  return path.join(root, DEV_CONFIG_PATH)
+}
+
+function printDevConfigResult(result: DevConfigCommandResult): void {
+  log.header('Inspecto Dev')
+  log.info(`Config: ${result.configPath}`)
+  if (result.config.cliBin) {
+    log.hint(`cliBin: ${result.config.cliBin}`)
+  }
+  if (result.config.devRepo) {
+    log.hint(`devRepo: ${result.config.devRepo}`)
+  }
+  if (!result.config.cliBin && !result.config.devRepo) {
+    log.hint('No local dev overrides are configured.')
+  }
+}
+
+async function readExistingConfig(root: string): Promise<InspectoDevConfig> {
+  const configPath = absoluteDevConfigPath(root)
+  const config = await readJSON<InspectoDevConfig>(configPath)
+  if (!config || typeof config !== 'object') {
+    return {}
+  }
+
+  return config
+}
+
+export async function devLink(options: DevLinkOptions): Promise<DevConfigCommandResult> {
+  const root = process.cwd()
+  const configPath = absoluteDevConfigPath(root)
+  const existing = await readExistingConfig(root)
+  const nextConfig: InspectoDevConfig = {
+    ...existing,
+    ...(options.cliBin ? { cliBin: options.cliBin } : {}),
+    ...(options.devRepo ? { devRepo: options.devRepo } : {}),
+  }
+
+  await writeJSON(configPath, nextConfig)
+  await updateGitignore(root, false, false, true)
+
+  return writeCommandOutput(
+    {
+      status: 'ok',
+      configPath,
+      config: nextConfig,
+    },
+    options.json ?? false,
+    printDevConfigResult,
+  )
+}
+
+export async function devStatus(json = false): Promise<DevConfigCommandResult> {
+  const root = process.cwd()
+  const configPath = absoluteDevConfigPath(root)
+  const config = await readExistingConfig(root)
+
+  return writeCommandOutput(
+    {
+      status: 'ok',
+      configPath,
+      config,
+    },
+    json,
+    printDevConfigResult,
+  )
+}
+
+export async function devUnlink(json = false): Promise<DevConfigCommandResult> {
+  const root = process.cwd()
+  const configPath = absoluteDevConfigPath(root)
+
+  await removeFile(configPath)
+
+  return writeCommandOutput(
+    {
+      status: 'ok',
+      configPath,
+      config: {},
+    },
+    json,
+    printDevConfigResult,
+  )
+}

package/src/commands/doctor.ts

@@ -10,8 +10,15 @@ import { detectFrameworks } from '../detect/framework.js'
 import { detectIDE } from '../detect/ide.js'
 import { detectProviders } from '../detect/provider.js'
 import { isExtensionInstalled } from '../inject/extension.js'
+import { createPlanResult } from '../onboarding/planner.js'
 import { writeCommandOutput } from '../utils/output.js'
-import type { CommandStatus, DoctorDiagnostic, DoctorResult } from '../types.js'
+import type {
+  CommandStatus,
+  DoctorDiagnostic,
+  DoctorResult,
+  OnboardingContext,
+  PlanResult,
+} from '../types.js'
 
 export interface DoctorCommandOptions {
   json?: boolean
@@ -39,6 +46,113 @@ function doctorStatus(errors: number, warnings: number): CommandStatus {
   return 'ok'
 }
 
+function isGuidedMetaFramework(buildTool: string): boolean {
+  return buildTool === 'Next.js' || buildTool === 'Nuxt'
+}
+
+function buildDoctorOnboardingContext(input: {
+  root: string
+  packageManager: NonNullable<DoctorResult['project']['packageManager']>
+  buildTools: Awaited<ReturnType<typeof detectBuildTools>>
+  frameworks: Awaited<ReturnType<typeof detectFrameworks>>
+  ides: Awaited<ReturnType<typeof detectIDE>>
+  providers: Awaited<ReturnType<typeof detectProviders>>
+}): OnboardingContext {
+  return {
+    root: input.root,
+    packageManager: input.packageManager,
+    buildTools: input.buildTools,
+    frameworks: {
+      supported: input.frameworks.supported,
+      unsupported: input.frameworks.unsupported.map(item => item.name),
+    },
+    ides: input.ides.detected.map(({ ide, supported }) => ({ ide, supported })),
+    providers: input.providers.detected.map(({ id, label, supported, preferredMode }) => ({
+      id,
+      label,
+      supported,
+      preferredMode,
+    })),
+  }
+}
+
+function isConfigPatchReason(reason: string): boolean {
+  return reason.startsWith('next_config_') || reason.startsWith('nuxt_config_')
+}
+
+function isNextWebpackDevPatchReason(reason: string): boolean {
+  return reason === 'next_dev_script_requires_webpack'
+}
+
+async function collectGuidedPatchDiagnostics(
+  root: string,
+  plan: PlanResult,
+): Promise<DoctorDiagnostic[]> {
+  if (plan.strategy !== 'guided' || !plan.patches?.length) {
+    return []
+  }
+
+  const diagnostics: DoctorDiagnostic[] = []
+
+  for (const patch of plan.patches) {
+    if (isConfigPatchReason(patch.reason)) {
+      const content = await readFile(path.join(root, patch.path))
+      if (content?.includes('@inspecto-dev/plugin')) {
+        diagnostics.push(
+          createDiagnostic(
+            'guided-config-patch-detected',
+            'ok',
+            `Guided config patch appears to be applied in ${patch.path}`,
+            [],
+            { path: patch.path, reason: patch.reason },
+          ),
+        )
+      } else {
+        diagnostics.push(
+          createDiagnostic(
+            'guided-config-patch-pending',
+            'warning',
+            `Guided config patch still needs review in ${patch.path}`,
+            ['Run `inspecto onboard --json` to review the generated patch details.'],
+            { path: patch.path, reason: patch.reason },
+          ),
+        )
+      }
+      continue
+    }
+
+    if (isNextWebpackDevPatchReason(patch.reason)) {
+      const packageJson = await readJSON<{ scripts?: Record<string, string> }>(
+        path.join(root, 'package.json'),
+      )
+      const devScript = packageJson?.scripts?.dev ?? ''
+      if (/next\s+dev\b/.test(devScript) && /--webpack\b/.test(devScript)) {
+        diagnostics.push(
+          createDiagnostic(
+            'guided-dev-script-configured',
+            'ok',
+            'Next.js dev script is configured for webpack mode',
+            [],
+            { script: devScript },
+          ),
+        )
+      } else {
+        diagnostics.push(
+          createDiagnostic(
+            'guided-dev-script-pending',
+            'warning',
+            'Next.js dev script still needs webpack mode for Inspecto validation',
+            ['Update the `dev` script to `next dev --webpack` before browser validation.'],
+            { script: devScript },
+          ),
+        )
+      }
+    }
+  }
+
+  return diagnostics
+}
+
 function printDoctorResult(result: DoctorResult): void {
   log.header('Inspecto Doctor')
 
@@ -99,6 +213,15 @@ export async function collectDoctorResult(root = process.cwd()): Promise<DoctorR
       detectBuildTools(root),
       isExtensionInstalled(),
     ])
+  const onboardingContext = buildDoctorOnboardingContext({
+    root,
+    packageManager: pm,
+    buildTools: buildResult,
+    frameworks: frameworkResult,
+    ides: ideProbe,
+    providers: providerProbe,
+  })
+  const onboardingPlan = createPlanResult(onboardingContext)
 
   // Check 2: IDE
   if (ideProbe.detected.length === 0) {
@@ -229,15 +352,45 @@ export async function collectDoctorResult(root = process.cwd()): Promise<DoctorR
       )
     }
   } else if (buildResult.unsupported.length > 0) {
-    const names = buildResult.unsupported.join(', ')
-    checks.push(
-      createDiagnostic(
-        `build-tool-unsupported`,
-        'warning',
-        `Build tool: ${names} (not supported in v1)`,
-        ['current version supports: Vite, Webpack, Rspack, esbuild, Rollup'],
-      ),
+    const guidedBuildTools = buildResult.unsupported.filter(isGuidedMetaFramework)
+    const trulyUnsupportedBuildTools = buildResult.unsupported.filter(
+      buildTool => !isGuidedMetaFramework(buildTool),
     )
+
+    if (guidedBuildTools.length > 0) {
+      checks.push(
+        createDiagnostic(
+          'build-tool-guided',
+          'warning',
+          `Build tool: ${guidedBuildTools.join(', ')} (guided onboarding available)`,
+          [
+            'Run `inspecto onboard --json` to generate the remaining patch plan and assistant handoff.',
+            ...(onboardingPlan.pendingSteps ?? []),
+          ],
+          {
+            metaFrameworks: guidedBuildTools,
+            ...(onboardingPlan.pendingSteps ? { pendingSteps: onboardingPlan.pendingSteps } : {}),
+            ...(onboardingPlan.assistantPrompt
+              ? { assistantPrompt: onboardingPlan.assistantPrompt }
+              : {}),
+            ...(onboardingPlan.patches ? { patchCount: onboardingPlan.patches.length } : {}),
+          },
+        ),
+      )
+    }
+
+    checks.push(...(await collectGuidedPatchDiagnostics(root, onboardingPlan)))
+
+    if (trulyUnsupportedBuildTools.length > 0) {
+      checks.push(
+        createDiagnostic(
+          'build-tool-unsupported',
+          'warning',
+          `Build tool: ${trulyUnsupportedBuildTools.join(', ')} (not supported in v1)`,
+          ['current version supports: Vite, Webpack, Rspack, esbuild, Rollup'],
+        ),
+      )
+    }
   } else {
     checks.push(
       createDiagnostic('build-tool-missing', 'warning', 'No recognized build config found'),
@@ -282,6 +435,33 @@ export async function collectDoctorResult(root = process.cwd()): Promise<DoctorR
     const settings = await readJSON(targetPath)
     if (settings) {
       checks.push(createDiagnostic('settings-valid', 'ok', `.inspecto/${fileName} valid`))
+
+      const configuredIde =
+        typeof (settings as Record<string, unknown>).ide === 'string'
+          ? ((settings as Record<string, unknown>).ide as string)
+          : undefined
+      const detectedIdeCandidates = ideProbe.detected.map(item => item.ide)
+      if (
+        configuredIde &&
+        detectedIdeCandidates.length > 0 &&
+        !detectedIdeCandidates.includes(configuredIde)
+      ) {
+        checks.push(
+          createDiagnostic(
+            'settings-ide-mismatch',
+            'warning',
+            `.inspecto/${fileName} sets ide=${configuredIde}, but the current environment looks like ${detectedIdeCandidates.join(', ')}. Inspecto will use the configured IDE from ${fileName}.`,
+            [
+              `Update .inspecto/${fileName} if you want Inspecto to target the currently detected IDE instead.`,
+            ],
+            {
+              configuredIde,
+              detectedIdeCandidates,
+              precedence: `configured ide from ${fileName}`,
+            },
+          ),
+        )
+      }
     } else {
       checks.push(
         createDiagnostic(

package/src/commands/init.ts

@@ -24,7 +24,11 @@ import {
   promptMonorepoPackageChoice,
   promptUnsupportedFrameworkContinue,
 } from '../prompts.js'
-import { printNextJsManualInstructions, printNuxtManualInstructions } from '../instructions.js'
+import {
+  printNextJsManualInstructions,
+  printNuxtManualInstructions,
+  printUmiManualInstructions,
+} from '../instructions.js'
 
 export async function init(options: InitOptions): Promise<void> {
   const repoRoot = process.cwd()
@@ -175,8 +179,8 @@ export async function init(options: InitOptions): Promise<void> {
   if (buildResult.unsupported.length > 0) {
     const names = buildResult.unsupported.join(', ')
     manualConfigRequiredFor = buildResult.unsupported[0] || ''
-    log.warn(`Detected ${names} — automatic plugin injection is not supported in current version`)
-    log.hint('You can still manually configure it by modifying your configuration file')
+    log.warn(`Detected ${names} — guided onboarding is available in the current version`)
+    log.hint('Inspecto can prepare the remaining patch plan and assistant handoff for this stack.')
 
     if (buildResult.unsupported.includes('Next.js')) {
       printNextJsManualInstructions()
@@ -184,6 +188,9 @@ export async function init(options: InitOptions): Promise<void> {
     if (buildResult.unsupported.includes('Nuxt')) {
       printNuxtManualInstructions()
     }
+    if (buildResult.unsupported.includes('Umi')) {
+      printUmiManualInstructions()
+    }
   }
   if (buildResult.supported.length === 0 && buildResult.unsupported.length === 0) {
     log.warn('No recognized build tool detected')

package/src/commands/integration-automation.ts

@@ -24,6 +24,7 @@ interface IntegrationAutomationOptions {
   inspectoVsix?: string
   preview?: boolean
   silent?: boolean
+  ignoreProjectArtifacts?: boolean
 }
 
 interface IntegrationAutomationDetails {
@@ -93,6 +94,7 @@ export async function runIntegrationAutomation(
   const resolvedHostIde = await resolveIntegrationHostIde({
     ...(options.ide ? { explicitIde: options.ide } : {}),
     ...(cwd ? { cwd } : {}),
+    ...(options.ignoreProjectArtifacts ? { ignoreProjectArtifacts: true } : {}),
   })
 
   const details: IntegrationAutomationDetails = {