@inspecto-dev/cli 0.3.4 → 0.3.5

package/src/commands/onboard.ts

@@ -5,7 +5,7 @@ import {
 } from '../onboarding/session.js'
 import { log } from '../utils/logger.js'
 import { writeCommandOutput } from '../utils/output.js'
-import type { OnboardCommandResult } from '../types.js'
+import type { OnboardCommandResult, OnboardingAssistantHandoff } from '../types.js'
 
 export interface OnboardCommandOptions {
   json?: boolean
@@ -34,47 +34,98 @@ function printManualExtensionGuidance(result: OnboardCommandResult): void {
   }
 }
 
+function buildAssistantHandoff(
+  result: OnboardCommandResult,
+): OnboardingAssistantHandoff | undefined {
+  if (
+    !result.framework &&
+    !result.metaFramework &&
+    !result.routerMode &&
+    !result.autoApplied &&
+    !result.pendingSteps &&
+    !result.assistantPrompt &&
+    !result.patches
+  ) {
+    return result.handoff
+  }
+
+  return {
+    ...(result.framework ? { framework: result.framework } : {}),
+    ...(result.metaFramework ? { metaFramework: result.metaFramework } : {}),
+    ...(result.routerMode ? { routerMode: result.routerMode } : {}),
+    ...(result.autoApplied ? { autoApplied: result.autoApplied } : {}),
+    ...(result.pendingSteps ? { pendingSteps: result.pendingSteps } : {}),
+    ...(result.assistantPrompt ? { assistantPrompt: result.assistantPrompt } : {}),
+    ...(result.patches ? { patches: result.patches } : {}),
+  }
+}
+
+function normalizeOnboardResult(result: OnboardCommandResult): OnboardCommandResult {
+  const handoff = buildAssistantHandoff(result)
+  if (!handoff) {
+    return result
+  }
+
+  return {
+    ...result,
+    handoff,
+  }
+}
+
+function collectDisplayNextSteps(result: OnboardCommandResult): string[] {
+  return Array.from(
+    new Set([...(result.diagnostics?.nextSteps ?? []), ...(result.handoff?.pendingSteps ?? [])]),
+  )
+}
+
 function printOnboardResult(result: OnboardCommandResult): void {
+  const normalized = normalizeOnboardResult(result)
   log.header('Inspecto Onboard')
-  log.info(`Status: ${result.status}`)
-  log.info(result.summary.headline)
+  log.info(`Status: ${normalized.status}`)
+  log.info(normalized.summary.headline)
 
-  if (result.status === 'needs_target_selection') {
-    if (result.target.selectionPurpose) {
-      log.warn(result.target.selectionPurpose)
+  if (normalized.status === 'needs_target_selection') {
+    if (normalized.target.selectionPurpose) {
+      log.warn(normalized.target.selectionPurpose)
     }
-    for (const candidate of result.target.candidates) {
+    for (const candidate of normalized.target.candidates) {
       const identifier = candidate.candidateId ?? candidate.id ?? candidate.configPath
       const label = candidate.label ?? candidate.configPath
       log.hint(`${identifier}: ${label}`)
     }
-    if (result.target.selectionInstructions) {
-      log.hint(result.target.selectionInstructions)
+    if (normalized.target.selectionInstructions) {
+      log.hint(normalized.target.selectionInstructions)
     }
   }
 
-  for (const change of result.summary.changes) {
+  for (const change of normalized.summary.changes) {
     log.hint(change)
   }
-  for (const step of result.diagnostics?.nextSteps ?? []) {
+  for (const step of collectDisplayNextSteps(normalized)) {
     log.warn(step)
   }
-  if (result.confirmation.required && result.confirmation.question) {
-    log.warn(result.confirmation.question)
+  for (const patch of normalized.handoff?.patches ?? []) {
+    log.hint(`Patch target: ${patch.path} (${patch.reason})`)
+  }
+  if (normalized.handoff?.assistantPrompt) {
+    log.hint(normalized.handoff.assistantPrompt)
+  }
+  if (normalized.confirmation.required && normalized.confirmation.question) {
+    log.warn(normalized.confirmation.question)
   }
 
-  printManualExtensionGuidance(result)
+  printManualExtensionGuidance(normalized)
 
   const extensionReady =
-    !result.ideExtension?.required ||
-    (result.ideExtension.installed && !result.ideExtension.manualRequired)
+    !normalized.ideExtension?.required ||
+    (normalized.ideExtension.installed && !normalized.ideExtension.manualRequired)
 
   if (
     extensionReady &&
-    (result.status === 'success' || result.status === 'partial_success') &&
-    result.verification?.message
+    (normalized.status === 'success' || normalized.status === 'partial_success') &&
+    normalized.verification?.message
   ) {
-    log.info(result.verification.message)
+    log.info(normalized.verification.message)
   }
 }
 
@@ -88,12 +139,12 @@ export async function onboard(options: OnboardCommandOptions = {}): Promise<Onbo
     session.status === 'needs_confirmation'
   ) {
     return writeCommandOutput(
-      buildDeferredOnboardResult(session),
+      normalizeOnboardResult(buildDeferredOnboardResult(session)),
       options.json ?? false,
       printOnboardResult,
     )
   }
 
-  const result = await applyResolvedOnboardingSession(session, options)
+  const result = normalizeOnboardResult(await applyResolvedOnboardingSession(session, options))
   return writeCommandOutput(result, options.json ?? false, printOnboardResult)
 }

package/src/detect/build-tool.ts

@@ -139,6 +139,11 @@ const SUPPORTED_PATTERNS: { tool: BuildTool; files: string[]; label: string }[]
 
 /** Recognized but unsupported meta-frameworks — detect via dep + config file */
 const UNSUPPORTED_META: { name: string; dep: string; files: string[] }[] = [
+  {
+    name: 'Umi',
+    dep: 'umi',
+    files: ['.umirc.ts', '.umirc.js', 'config/config.ts', 'config/config.js'],
+  },
   { name: 'Next.js', dep: 'next', files: ['next.config.mjs', 'next.config.js', 'next.config.ts'] },
   { name: 'Nuxt', dep: 'nuxt', files: ['nuxt.config.ts', 'nuxt.config.js'] },
   { name: 'Remix', dep: '@remix-run/dev', files: ['remix.config.js', 'remix.config.ts'] },
@@ -297,7 +302,9 @@ export async function detectBuildTools(
     }
 
     const unsupportedChecks = UNSUPPORTED_META.map(async meta => {
-      if (!(meta.dep in allDeps)) return null
+      // Check if any dependency matches (supports exact match or scoped packages if necessary, but here we do exact match)
+      const hasDep = meta.dep in allDeps || Object.keys(allDeps).some(dep => dep.includes(meta.dep))
+      if (!hasDep) return null
       for (const file of meta.files) {
         if (await exists(path.join(target.absolutePath, file))) {
           return meta.name
@@ -471,6 +478,8 @@ async function detectPattern({
     }
   } else if (pattern.tool === 'rsbuild') {
     hasDep = !!allDeps['@rsbuild/core'] || isPackageResolvable('@rsbuild/core', targetRoot)
+  } else if (pattern.tool === 'vite') {
+    hasDep = !!allDeps['vite'] || isPackageResolvable('vite', targetRoot)
   } else {
     hasDep = !!allDeps[pattern.tool] || isPackageResolvable(pattern.tool, targetRoot)
   }
@@ -576,7 +585,7 @@ async function detectPattern({
         tool: pattern.tool,
         configPath: 'package.json (dependency)',
         label: `${pattern.label} (detected via dependency)`,
-        packagePath: packagePath || undefined,
+        ...(packagePath ? { packagePath } : {}),
       }
     }
     return null
@@ -604,9 +613,9 @@ async function detectPattern({
     label: `${pattern.label} (${relativeConfig})${isLegacyRspack ? ' [Legacy]' : ''}${
       isLegacyWebpack ? ' [Webpack 4]' : ''
     }${inferredFromScripts ? ' [Scripts Detected]' : ''}`,
-    isLegacyRspack,
-    isLegacyWebpack,
-    packagePath: packagePath || undefined,
+    ...(isLegacyRspack ? { isLegacyRspack: true } : {}),
+    ...(isLegacyWebpack ? { isLegacyWebpack: true } : {}),
+    ...(packagePath ? { packagePath } : {}),
   }
 }
 

package/src/detect/framework.ts

@@ -44,9 +44,12 @@ const SUPPORTED_FRAMEWORKS: { framework: Framework; deps: string[] }[] = [
 const UNSUPPORTED_FRAMEWORKS: { name: string; dep: string }[] = [
   { name: 'Solid', dep: 'solid-js' },
   { name: 'Svelte', dep: 'svelte' },
+  { name: 'SvelteKit', dep: '@sveltejs/kit' },
   { name: 'Angular', dep: '@angular/core' },
   { name: 'Preact', dep: 'preact' },
   { name: 'Lit', dep: 'lit' },
+  { name: 'Qwik', dep: 'qwik' },
+  { name: 'Alpine', dep: 'lit-html' },
 ]
 
 /**

package/src/detect/package-manager.ts

@@ -14,8 +14,8 @@ export async function detectPackageManager(root: string): Promise<PackageManager
     ['bun.lockb', 'bun'],
     ['bun.lock', 'bun'],
     ['pnpm-lock.yaml', 'pnpm'],
-    ['yarn.lock', 'yarn'],
     ['package-lock.json', 'npm'],
+    ['yarn.lock', 'yarn'],
   ]
 
   const results = await Promise.all(

package/src/index.ts

@@ -1,5 +1,6 @@
 export { apply } from './commands/apply.js'
 export { detect } from './commands/detect.js'
+export { devLink, devStatus, devUnlink } from './commands/dev-config.js'
 export { init } from './commands/init.js'
 export { collectDoctorResult, doctor } from './commands/doctor.js'
 export { integrationDoctor } from './commands/integration-doctor.js'

package/src/inject/gitignore.ts

@@ -6,10 +6,20 @@ import { readFile, writeFile } from '../utils/fs.js'
 import { log } from '../utils/logger.js'
 
 /** Rules for default mode: fine-grained rules only */
-const DEFAULT_RULES = ['.inspecto/install.lock', '.inspecto/cache.json', '.inspecto/*.local.json']
+const DEFAULT_RULES = [
+  '.inspecto/install.lock',
+  '.inspecto/cache.json',
+  '.inspecto/*.local.json',
+  '.inspecto/dev.json',
+]
 
 /** Rules for shared mode: same as default in current design to allow settings.json */
-const SHARED_RULES = ['.inspecto/install.lock', '.inspecto/cache.json', '.inspecto/*.local.json']
+const SHARED_RULES = [
+  '.inspecto/install.lock',
+  '.inspecto/cache.json',
+  '.inspecto/*.local.json',
+  '.inspecto/dev.json',
+]
 
 /**
  * Update .gitignore based on the init mode.
@@ -77,6 +87,7 @@ export async function cleanGitignore(root: string): Promise<void> {
     .replace(/^\.inspecto\/install\.lock\s*$/gm, '')
     .replace(/^\.inspecto\/cache\.json\s*$/gm, '')
     .replace(/^\.inspecto\/\*\.local\.json\s*$/gm, '')
+    .replace(/^\.inspecto\/dev\.json\s*$/gm, '')
     .replace(/\n{3,}/g, '\n\n') // Collapse excess blank lines
 
   await writeFile(gitignorePath, cleaned)

package/src/instructions.ts

@@ -2,7 +2,9 @@ import { log } from './utils/logger.js'
 
 export function printNuxtManualInstructions() {
   log.blank()
-  log.hint('Nuxt requires manual setup in the current version.')
+  log.hint(
+    'Nuxt supports guided setup in the current version. Inspecto can prepare the config patch, but the client plugin mount step still needs review.',
+  )
   log.hint('1. Update `nuxt.config.ts` to register the Inspecto Vite plugin:')
   log.copyableCodeBlock([
     "import { vitePlugin as inspecto } from '@inspecto-dev/plugin'",
@@ -13,7 +15,7 @@ export function printNuxtManualInstructions() {
     '  },',
     '})',
   ])
-  log.hint('2. Create `plugins/inspecto.client.ts` to mount `@inspecto-dev/core` in development:')
+  log.hint('2. Complete the remaining client plugin mount step in `plugins/inspecto.client.ts`:')
   log.copyableCodeBlock([
     'export default defineNuxtPlugin(() => {',
     '  if (import.meta.dev) {',
@@ -23,12 +25,33 @@ export function printNuxtManualInstructions() {
     '  }',
     '})',
   ])
-  log.hint('3. Restart your Nuxt dev server after updating the config.')
+  log.hint('3. Restart your Nuxt dev server after applying the guided patches.')
+}
+
+export function printUmiManualInstructions() {
+  log.blank()
+  log.hint('Umi supports guided setup in the current version.')
+  log.hint('1. Update `config/config.ts` or `.umirc.ts` to register the Inspecto webpack plugin:')
+  log.copyableCodeBlock([
+    "import { defineConfig } from 'umi'",
+    "import { webpack4Plugin } from '@inspecto-dev/plugin/legacy/webpack4'",
+    '',
+    'export default defineConfig({',
+    '  chainWebpack(memo) {',
+    "    if (process.env.NODE_ENV === 'development') {",
+    "      memo.plugin('inspecto').use(webpack4Plugin())",
+    '    }',
+    '  },',
+    '})',
+  ])
+  log.hint('2. Restart your Umi dev server after applying the guided patches.')
 }
 
 export function printNextJsManualInstructions() {
   log.blank()
-  log.hint('Next.js requires manual setup in the current version.')
+  log.hint(
+    'Next.js supports guided setup in the current version. Inspecto can prepare the config patch, but the client-side mount step still needs review.',
+  )
   log.hint('1. Update `next.config.mjs` to register the Inspecto webpack plugin:')
   log.copyableCodeBlock([
     "import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'",
@@ -36,7 +59,7 @@ export function printNextJsManualInstructions() {
     "/** @type {import('next').NextConfig} */",
     'const nextConfig = {',
     '  webpack: (config, { dev, isServer }) => {',
-    '    if (dev && !isServer) {',
+    '    if (dev) {',
     '      config.plugins.push(inspecto())',
     '    }',
     '    return config',
@@ -46,7 +69,10 @@ export function printNextJsManualInstructions() {
     'export default nextConfig',
   ])
   log.hint(
-    '2. Initialize `@inspecto-dev/core` from a client component such as `app/layout.tsx` or `pages/_app.tsx`:',
+    'Keep the plugin enabled for both server and client development compilers so App Router server components also receive Inspecto transforms.',
+  )
+  log.hint(
+    '2. Complete the remaining client-side mount step in `app/layout.tsx` or `pages/_app.tsx`:',
   )
   log.copyableCodeBlock([
     "'use client'",
@@ -65,5 +91,5 @@ export function printNextJsManualInstructions() {
     '  return <html><body>{children}</body></html>',
     '}',
   ])
-  log.hint('3. Restart your Next.js dev server after updating the config.')
+  log.hint('3. Restart your Next.js dev server after applying the guided patches.')
 }

package/src/onboarding/apply.ts

@@ -5,7 +5,7 @@ import { injectPlugin } from '../inject/ast-injector.js'
 import { installExtension } from '../inject/extension.js'
 import { updateGitignore } from '../inject/gitignore.js'
 import { shell } from '../utils/exec.js'
-import { exists, readJSON, writeJSON } from '../utils/fs.js'
+import { exists, readFile, readJSON, writeFile, writeJSON } from '../utils/fs.js'
 import { log } from '../utils/logger.js'
 import type {
   BuildToolDetection,
@@ -133,7 +133,11 @@ function resultStatus(nextSteps: string[]): CommandStatus {
 
 function manualPlanSteps(plan: PlanResult, includeBlockers = true): string[] {
   const steps = plan.actions
-    .filter(action => action.type === 'manual_step')
+    .filter(action =>
+      ['manual_step', 'generate_patch_plan', 'generate_file', 'manual_confirmation'].includes(
+        action.type,
+      ),
+    )
     .map(action => action.description)
 
   if (!includeBlockers) {
@@ -143,6 +147,127 @@ function manualPlanSteps(plan: PlanResult, includeBlockers = true): string[] {
   return [...plan.blockers.map(blocker => blocker.message), ...steps]
 }
 
+function applyGuidedPatchContent(source: string, snippet: string): string {
+  if (source.includes("import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'")) {
+    return source
+  }
+  if (source.includes("import { vitePlugin as inspecto } from '@inspecto-dev/plugin'")) {
+    return source
+  }
+
+  const trimmedSource = source.trimEnd()
+  if (/export\s+default\s*\{/m.test(source)) {
+    const nextSource = trimmedSource.replace(
+      /export\s+default\s*\{/m,
+      "import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'\n\nexport default {\n  webpack(config, { dev, isServer }) {\n    if (dev) {\n      config.plugins.push(inspecto())\n    }\n    return config\n  },",
+    )
+    return `${nextSource}\n`
+  }
+
+  if (/module\.exports\s*=\s*\{/m.test(source)) {
+    const nextSource = trimmedSource.replace(
+      /module\.exports\s*=\s*\{/m,
+      "const { webpackPlugin: inspecto } = require('@inspecto-dev/plugin')\n\nmodule.exports = {\n  webpack(config, { dev, isServer }) {\n    if (dev) {\n      config.plugins.push(inspecto())\n    }\n    return config\n  },",
+    )
+    return `${nextSource}\n`
+  }
+
+  const objectExportVariableMatch = source.match(
+    /(const\s+([A-Za-z0-9_$]+)\s*(?::[^=]+)?=\s*\{[\s\S]*?\}\s*;?\s*)export\s+default\s+\2\s*;?/m,
+  )
+  const variableDeclaration = objectExportVariableMatch?.[1]
+  const variableName = objectExportVariableMatch?.[2]
+  if (variableDeclaration && variableName) {
+    const nextDeclaration = variableDeclaration.replace(
+      /=\s*\{/m,
+      '= {\n  webpack(config, { dev, isServer }) {\n    if (dev) {\n      config.plugins.push(inspecto())\n    }\n    return config\n  },',
+    )
+    const nextSource = source.replace(
+      objectExportVariableMatch[0],
+      `import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'\n\n${nextDeclaration}export default ${variableName}`,
+    )
+    return `${nextSource.trimEnd()}\n`
+  }
+
+  if (/defineNuxtConfig\s*\(\s*\{/m.test(source)) {
+    const trimmedSource = source.trimEnd()
+    const nextSource = trimmedSource.replace(
+      /defineNuxtConfig\s*\(\s*\{/m,
+      'defineNuxtConfig({\n  vite: {\n    plugins: [inspecto()],\n  },',
+    )
+    return `import { vitePlugin as inspecto } from '@inspecto-dev/plugin'\n\n${nextSource}\n`
+  }
+
+  const jsdocMatch = source.match(
+    /\/\*\*[\s\S]*?@type\s*\{import\('next'\)\.NextConfig\}[\s\S]*?\*\/[\s\S]*?(export\s+default|module\.exports)\s*=?\s*\{/m,
+  )
+  if (jsdocMatch) {
+    const isEsm = jsdocMatch[1] === 'export default'
+    const importStatement = isEsm
+      ? "import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'\n\n"
+      : "const { webpackPlugin: inspecto } = require('@inspecto-dev/plugin')\n\n"
+
+    const replacementPattern = isEsm ? /export\s+default\s*\{/m : /module\.exports\s*=\s*\{/m
+
+    const injectConfig = isEsm
+      ? 'export default {\n  webpack(config, { dev, isServer }) {\n    if (dev) {\n      config.plugins.push(inspecto())\n    }\n    return config\n  },'
+      : 'module.exports = {\n  webpack(config, { dev, isServer }) {\n    if (dev) {\n      config.plugins.push(inspecto())\n    }\n    return config\n  },'
+
+    const nextSource = source.replace(replacementPattern, injectConfig)
+    return `${importStatement}${nextSource.trimEnd()}\n`
+  }
+
+  return `${trimmedSource}\n\n${snippet}\n`
+}
+
+async function applyGuidedPlanPatches(
+  input: ApplyOnboardingInput,
+  mutations: Mutation[],
+  reporter: ApplyReporter,
+): Promise<string[]> {
+  const nextSteps: string[] = []
+
+  if (!input.plan || input.plan.strategy !== 'guided' || !input.plan.patches?.length) {
+    return nextSteps
+  }
+
+  for (const patch of input.plan.patches) {
+    if (
+      patch.status !== 'planned' ||
+      (!patch.reason.startsWith('next_config_') && !patch.reason.startsWith('nuxt_config_'))
+    ) {
+      continue
+    }
+
+    const patchPath = path.join(input.projectRoot, patch.path)
+    const existingContent = await readFile(patchPath)
+    if (existingContent === null) {
+      nextSteps.push(`Could not auto-apply the guided patch for ${patch.path}.`)
+      continue
+    }
+
+    const nextContent = applyGuidedPatchContent(existingContent, patch.snippet)
+    if (nextContent === existingContent) {
+      continue
+    }
+
+    if (input.options.dryRun) {
+      reporter.dryRun(`Would apply guided patch to ${patch.path}`)
+      continue
+    }
+
+    await writeFile(patchPath, nextContent)
+    mutations.push({
+      type: 'file_modified',
+      path: patch.path,
+      description: 'Automatically configured Inspecto guided Next.js patch',
+    })
+    reporter.success(`Applied guided patch to ${patch.path}`)
+  }
+
+  return nextSteps
+}
+
 export async function applyOnboardingPlan(
   input: ApplyOnboardingInput,
 ): Promise<ApplyOnboardingResult> {
@@ -207,7 +332,7 @@ async function applyOnboardingPlanInternal(
 ): Promise<ApplyOnboardingResult> {
   const reporter = createReporter(input.options.quiet)
   const additiveManualPlan =
-    input.plan?.strategy === 'manual' &&
+    (input.plan?.strategy === 'manual' || input.plan?.strategy === 'guided') &&
     input.allowManualPlanApply &&
     input.plan.blockers.length === 0
 
@@ -261,6 +386,11 @@ async function applyOnboardingPlanInternal(
       spinner.fail('Dependency installation failed')
       installFailed = true
       reporter.error(`Failed to install dependency: ${error?.message || 'Unknown error'}`)
+      if (error?.stderr) {
+        reporter.error(`Details: ${error.stderr}`)
+      } else if (error?.stdout) {
+        reporter.error(`Details: ${error.stdout}`)
+      }
       reporter.hint(`Run manually in ${input.projectRoot}: ${installCmd}`)
       reporter.hint(
         'Setup will continue without dependencies, but Inspecto may not run until installation succeeds.',
@@ -285,6 +415,10 @@ async function applyOnboardingPlanInternal(
     }
   }
 
+  if (additiveManualPlan) {
+    nextSteps.push(...(await applyGuidedPlanPatches(input, mutations, reporter)))
+  }
+
   if (await exists(settingsPath)) {
     const existingSettings = await readJSON(settingsPath)
     if (existingSettings === null) {