@inspecto-dev/cli 0.3.3 → 0.3.4

package/dist/{chunk-LJOKPCPD.js → chunk-2MOEVONN.js}

@@ -869,6 +869,34 @@ async function cleanGitignore(root) {
 }
 
 // src/onboarding/apply.ts
+function normalizeSupportedIde(ide) {
+  if (!ide) return void 0;
+  return ide.toLowerCase() === "vscode" ? "vscode" : ide.toLowerCase();
+}
+async function readInheritedSettingsDefaults(repoRoot, projectRoot, settingsFileName) {
+  if (path6.resolve(repoRoot) === path6.resolve(projectRoot)) {
+    return {};
+  }
+  const inheritedSettingsPath = path6.join(repoRoot, ".inspecto", settingsFileName);
+  if (!await exists(inheritedSettingsPath)) {
+    return {};
+  }
+  const inheritedSettings = await readJSON(inheritedSettingsPath);
+  if (!inheritedSettings || typeof inheritedSettings !== "object") {
+    return {};
+  }
+  const inheritedDefaults = {};
+  if (typeof inheritedSettings.ide === "string") {
+    const normalizedIde = normalizeSupportedIde(inheritedSettings.ide);
+    if (normalizedIde) {
+      inheritedDefaults.ide = normalizedIde;
+    }
+  }
+  if (typeof inheritedSettings["provider.default"] === "string") {
+    inheritedDefaults.providerDefault = inheritedSettings["provider.default"];
+  }
+  return inheritedDefaults;
+}
 function shellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -892,11 +920,12 @@ function resolveRuntimePackages() {
 function resultStatus(nextSteps) {
   return nextSteps.length > 0 ? "warning" : "ok";
 }
-function manualPlanSteps(plan2) {
-  return [
-    ...plan2.blockers.map((blocker) => blocker.message),
-    ...plan2.actions.filter((action) => action.type === "manual_step").map((action) => action.description)
-  ];
+function manualPlanSteps(plan2, includeBlockers = true) {
+  const steps = plan2.actions.filter((action) => action.type === "manual_step").map((action) => action.description);
+  if (!includeBlockers) {
+    return steps;
+  }
+  return [...plan2.blockers.map((blocker) => blocker.message), ...steps];
 }
 async function applyOnboardingPlan(input) {
   return applyOnboardingPlanInternal(input);
@@ -960,6 +989,7 @@ function createSpinner(text, quiet = false) {
 }
 async function applyOnboardingPlanInternal(input) {
   const reporter = createReporter(input.options.quiet);
+  const additiveManualPlan = input.plan?.strategy === "manual" && input.allowManualPlanApply && input.plan.blockers.length === 0;
   if (input.plan && input.plan.strategy !== "supported" && !input.allowManualPlanApply) {
     return {
       status: input.plan.status,
@@ -968,7 +998,7 @@ async function applyOnboardingPlanInternal(input) {
         installFailed: false,
         injectionFailed: false,
         manualExtensionInstallNeeded: false,
-        nextSteps: manualPlanSteps(input.plan)
+        nextSteps: manualPlanSteps(input.plan, true)
       }
     };
   }
@@ -978,6 +1008,11 @@ async function applyOnboardingPlanInternal(input) {
   const promptsFileName = input.options.shared ? "prompts.json" : "prompts.local.json";
   const settingsPath = path6.join(settingsDir, settingsFileName);
   const promptsPath = path6.join(settingsDir, promptsFileName);
+  const inheritedDefaults = await readInheritedSettingsDefaults(
+    input.repoRoot,
+    input.projectRoot,
+    settingsFileName
+  );
   const runtimePackages = resolveRuntimePackages();
   const installCmd = getInstallCommand(input.packageManager, runtimePackages.installSpec);
   const nextSteps = [];
@@ -1010,17 +1045,19 @@ async function applyOnboardingPlanInternal(input) {
     }
   }
   let injectionFailed = Boolean(input.injectionSkippedRequiresManualConfig);
-  for (const target of input.supportedBuildTargets) {
-    const result = await injectPlugin(
-      input.repoRoot,
-      target,
-      input.options.dryRun,
-      input.options.quiet ?? false
-    );
-    if (result.success) {
-      mutations.push(...result.mutations);
-    } else {
-      injectionFailed = true;
+  if (!additiveManualPlan) {
+    for (const target of input.supportedBuildTargets) {
+      const result = await injectPlugin(
+        input.repoRoot,
+        target,
+        input.options.dryRun,
+        input.options.quiet ?? false
+      );
+      if (result.success) {
+        mutations.push(...result.mutations);
+      } else {
+        injectionFailed = true;
+      }
     }
   }
   if (await exists(settingsPath)) {
@@ -1030,15 +1067,43 @@ async function applyOnboardingPlanInternal(input) {
       reporter.hint("Please fix the syntax errors manually, or delete it and re-run init");
       nextSteps.push(`Fix .inspecto/${settingsFileName} or delete it and rerun Inspecto setup.`);
     } else {
-      reporter.success(`.inspecto/${settingsFileName} already exists (skipped)`);
+      const mergedSettings = existingSettings && typeof existingSettings === "object" ? { ...existingSettings } : {};
+      let settingsChanged = false;
+      const desiredIde = inheritedDefaults.ide ?? (input.selectedIDE?.supported ? normalizeSupportedIde(input.selectedIDE.ide) : void 0);
+      if (desiredIde && !mergedSettings.ide) {
+        mergedSettings.ide = desiredIde;
+        settingsChanged = true;
+      }
+      const desiredProviderDefault = inheritedDefaults.providerDefault ?? input.providerDefault;
+      if (desiredProviderDefault && !mergedSettings["provider.default"]) {
+        mergedSettings["provider.default"] = desiredProviderDefault;
+        settingsChanged = true;
+      }
+      if (settingsChanged) {
+        if (input.options.dryRun) {
+          reporter.dryRun(`Would update .inspecto/${settingsFileName}`);
+        } else {
+          await writeJSON(settingsPath, mergedSettings);
+          reporter.success(`Updated .inspecto/${settingsFileName} with missing defaults`);
+          mutations.push({
+            type: "file_modified",
+            path: `.inspecto/${settingsFileName}`,
+            description: "Merged missing Inspecto defaults into existing settings"
+          });
+        }
+      } else {
+        reporter.success(`.inspecto/${settingsFileName} already exists (skipped)`);
+      }
     }
   } else {
     const defaultSettings = {};
-    if (input.selectedIDE?.supported) {
-      defaultSettings.ide = input.selectedIDE.ide.toLowerCase() === "vscode" ? "vscode" : input.selectedIDE.ide.toLowerCase();
+    const desiredIde = inheritedDefaults.ide ?? (input.selectedIDE?.supported ? normalizeSupportedIde(input.selectedIDE.ide) : void 0);
+    const desiredProviderDefault = inheritedDefaults.providerDefault ?? input.providerDefault;
+    if (desiredIde) {
+      defaultSettings.ide = desiredIde;
     }
-    if (input.providerDefault) {
-      defaultSettings["provider.default"] = input.providerDefault;
+    if (desiredProviderDefault) {
+      defaultSettings["provider.default"] = desiredProviderDefault;
     }
     if (input.options.dryRun) {
       reporter.dryRun(`Would create .inspecto/${settingsFileName}`);
@@ -1117,6 +1182,9 @@ async function applyOnboardingPlanInternal(input) {
     if (manualExtensionInstallNeeded) {
       nextSteps.push("Install the Inspecto IDE extension manually");
     }
+    if (additiveManualPlan && input.plan) {
+      nextSteps.push(...manualPlanSteps(input.plan, false));
+    }
     if (input.manualConfigRequiredFor === "Nuxt") {
       nextSteps.push(
         "Nuxt detected\u2014please follow the Nuxt instructions printed above to finish setup."
@@ -1167,6 +1235,28 @@ async function getResolvedPackageVersion(pkgName, root) {
     return null;
   }
 }
+function parseFirstSemver(version) {
+  if (!version) return null;
+  const match = version.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!match) {
+    return null;
+  }
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3])
+  };
+}
+function isLegacyRspackVersion(version) {
+  const parsed = parseFirstSemver(version);
+  if (!parsed) return false;
+  return parsed.major === 0 && parsed.minor < 4;
+}
+function isLegacyWebpackVersion(version) {
+  const parsed = parseFirstSemver(version);
+  if (!parsed) return false;
+  return parsed.major === 4;
+}
 var SUPPORTED_PATTERNS = [
   {
     tool: "vite",
@@ -1192,7 +1282,22 @@ var SUPPORTED_PATTERNS = [
   },
   {
     tool: "webpack",
-    files: ["webpack.config.js", "webpack.config.ts", "webpack.config.mjs", "webpack.config.cjs"],
+    files: [
+      "webpack.config.js",
+      "webpack.config.ts",
+      "webpack.config.mjs",
+      "webpack.config.cjs",
+      "webpack.config.common.js",
+      "webpack.config.common.ts",
+      "webpack.config.dev.js",
+      "webpack.config.dev.ts",
+      "webpack.config.prod.js",
+      "webpack.config.prod.ts",
+      "webpack.config.esbuild.js",
+      "webpack.config.esbuild.ts",
+      "webpack.config.build-pre.js",
+      "webpack.config.build-pre.ts"
+    ],
     label: "Webpack"
   },
   {
@@ -1337,6 +1442,89 @@ async function detectBuildTools(root, packagePaths) {
   }
   return { supported, unsupported: Array.from(unsupported) };
 }
+function rankScriptCommand(name, command) {
+  const haystack = `${name} ${command}`.toLowerCase();
+  let score = 0;
+  if (/(^|[\s:_-])(start|dev|serve|watch)([\s:_-]|$)/.test(haystack)) score += 8;
+  if (/(^|[\s:_-])(prod|build|release|stats)([\s:_-]|$)/.test(haystack)) score -= 3;
+  if (/(^|[\s:_-])(dll|vendor)([\s:_-]|$)/.test(haystack)) score -= 6;
+  if (haystack.includes("webpack-dev-server")) score += 3;
+  if (haystack.includes("webpack")) score += 1;
+  if (haystack.includes("rspack")) score += 1;
+  return score;
+}
+function extractConfigArgs(scriptContent) {
+  return Array.from(scriptContent.matchAll(/(?:-c|--config)\s+([^\s'"`;]+)/g)).map((match) => match[1]).filter((value) => Boolean(value));
+}
+async function resolveScriptRelativeCandidate(targetRoot, scriptPath, candidate) {
+  const normalizedCandidate = candidate.replace(/^['"`]|['"`]$/g, "");
+  const normalizedRelativeCandidate = path7.normalize(normalizedCandidate);
+  const possiblePaths = [];
+  if (normalizedRelativeCandidate.startsWith("..")) {
+    possiblePaths.push(
+      path7.normalize(path7.join(path7.dirname(scriptPath), normalizedRelativeCandidate))
+    );
+  } else {
+    possiblePaths.push(normalizedRelativeCandidate);
+    possiblePaths.push(
+      path7.normalize(path7.join(path7.dirname(scriptPath), normalizedRelativeCandidate))
+    );
+  }
+  for (const possiblePath of possiblePaths) {
+    if (await exists(path7.join(targetRoot, possiblePath))) {
+      return possiblePath.split(path7.sep).join("/");
+    }
+  }
+  return null;
+}
+async function resolveRspackConfigFromScript(targetRoot, scriptPath) {
+  const scriptContent = await readFile(path7.join(targetRoot, scriptPath));
+  if (!scriptContent) {
+    return null;
+  }
+  for (const candidate of extractConfigArgs(scriptContent)) {
+    const resolved = await resolveScriptRelativeCandidate(targetRoot, scriptPath, candidate);
+    if (resolved) {
+      return resolved;
+    }
+  }
+  const matches = scriptContent.matchAll(
+    /['"`]([^'"`\n]*rspack[^'"`\n]*config[^'"`\n]*\.(?:js|ts|mjs|cjs))['"`]/g
+  );
+  for (const match of matches) {
+    const candidate = match[1];
+    if (!candidate) continue;
+    const resolved = await resolveScriptRelativeCandidate(targetRoot, scriptPath, candidate);
+    if (resolved) {
+      return resolved;
+    }
+  }
+  return null;
+}
+async function resolveWebpackBaseConfigFromFile(targetRoot, configPath) {
+  const configContent = await readFile(path7.join(targetRoot, configPath));
+  if (!configContent) {
+    return null;
+  }
+  for (const candidate of extractConfigArgs(configContent)) {
+    const resolved = await resolveScriptRelativeCandidate(targetRoot, configPath, candidate);
+    if (resolved) {
+      return resolved;
+    }
+  }
+  const matches = configContent.matchAll(
+    /(?:configPath\s*=\s*|require\()\s*['"`]([^'"`\n]*webpack[^'"`\n]*config[^'"`\n]*\.(?:js|ts|mjs|cjs))['"`]/g
+  );
+  for (const match of matches) {
+    const candidate = match[1];
+    if (!candidate) continue;
+    const resolved = await resolveScriptRelativeCandidate(targetRoot, configPath, candidate);
+    if (resolved) {
+      return resolved;
+    }
+  }
+  return null;
+}
 async function detectPattern({
   pattern,
   workspaceRoot,
@@ -1376,13 +1564,38 @@ async function detectPattern({
     }
   }
   if (hasDep && !detectedFile && (pattern.tool === "esbuild" || pattern.tool === "rollup" || pattern.tool === "webpack" || pattern.tool === "rspack" || pattern.tool === "rsbuild")) {
-    for (const cmd of Object.values(scripts)) {
+    const rankedScripts = Object.entries(scripts).sort(
+      ([leftName, leftCommand], [rightName, rightCommand]) => rankScriptCommand(rightName, rightCommand) - rankScriptCommand(leftName, leftCommand)
+    );
+    for (const [, cmd] of rankedScripts) {
+      if (pattern.tool === "webpack" || pattern.tool === "rspack") {
+        for (const configArg of extractConfigArgs(cmd)) {
+          const resolvedConfig = await resolveScriptRelativeCandidate(targetRoot, "", configArg);
+          if (resolvedConfig && (cmd.includes(pattern.tool) || cmd.includes(`${pattern.tool}-`))) {
+            if (pattern.tool === "webpack") {
+              detectedFile = await resolveWebpackBaseConfigFromFile(targetRoot, resolvedConfig) ?? resolvedConfig;
+            } else {
+              detectedFile = await resolveRspackConfigFromScript(targetRoot, resolvedConfig) ?? resolvedConfig;
+            }
+            break;
+          }
+        }
+        if (detectedFile) {
+          break;
+        }
+      }
       if (cmd.includes("node ")) {
         const match = cmd.match(/node\s+([^\s]+\.(js|mjs|cjs|ts))/);
         if (match && match[1]) {
           if (await exists(path7.join(targetRoot, match[1]))) {
             if (cmd.includes(pattern.tool) || match[1].includes(pattern.tool)) {
-              detectedFile = match[1];
+              if (pattern.tool === "rspack") {
+                detectedFile = await resolveRspackConfigFromScript(targetRoot, match[1]) ?? match[1];
+              } else if (pattern.tool === "webpack") {
+                detectedFile = await resolveWebpackBaseConfigFromFile(targetRoot, match[1]) ?? match[1];
+              } else {
+                detectedFile = match[1];
+              }
               break;
             }
           }
@@ -1419,13 +1632,11 @@ async function detectPattern({
   let isLegacyRspack = false;
   let isLegacyWebpack = false;
   if (pattern.tool === "rspack") {
-    const version = resolvedVersion;
-    if (version && (version.includes("0.3.") || version.includes("0.2.") || version.includes("0.1."))) {
+    if (isLegacyRspackVersion(resolvedVersion)) {
       isLegacyRspack = true;
     }
   } else if (pattern.tool === "webpack") {
-    const version = resolvedVersion;
-    if (version && version.includes("^4") || version?.startsWith("4.")) {
+    if (isLegacyWebpackVersion(resolvedVersion)) {
       isLegacyWebpack = true;
     }
   }
@@ -1737,6 +1948,28 @@ function buildToolBlockers(context) {
   }
   return [message("missing-build-tool", "No supported build tool detected")];
 }
+function buildToolWarnings(context) {
+  const warnings = [];
+  if (context.buildTools.supported.length === 1) {
+    const buildTool = context.buildTools.supported[0];
+    if (buildTool.tool === "rspack" && buildTool.isLegacyRspack) {
+      warnings.push(
+        message(
+          "legacy-rspack-requires-manual-config",
+          `Legacy Rspack detected at ${buildTool.configPath}. Inspecto must use the legacy Rspack plugin entry and manual config steps.`
+        )
+      );
+    } else if (buildTool.tool === "webpack" && buildTool.isLegacyWebpack) {
+      warnings.push(
+        message(
+          "legacy-webpack4-requires-manual-config",
+          `Webpack 4 detected at ${buildTool.configPath}. Inspecto must use the legacy Webpack 4 plugin entry and manual config steps.`
+        )
+      );
+    }
+  }
+  return warnings;
+}
 function frameworkBlockers(context) {
   if (context.frameworks.supported.length > 0) {
     return [];
@@ -1798,6 +2031,35 @@ function manualBuildToolActions(context) {
       }
     ];
   }
+  const buildTool = context.buildTools.supported[0];
+  if (buildTool?.tool === "rspack" && buildTool.isLegacyRspack) {
+    return [
+      {
+        type: "install_dependency",
+        target: "@inspecto-dev/plugin @inspecto-dev/core",
+        description: `Install the Inspecto runtime packages with ${context.packageManager}.`
+      },
+      {
+        type: "manual_step",
+        target: buildTool.configPath,
+        description: `Update ${buildTool.configPath} to import \`rspackPlugin\` from \`@inspecto-dev/plugin/legacy/rspack\` and add it to the Rspack plugins array.`
+      }
+    ];
+  }
+  if (buildTool?.tool === "webpack" && buildTool.isLegacyWebpack) {
+    return [
+      {
+        type: "install_dependency",
+        target: "@inspecto-dev/plugin @inspecto-dev/core",
+        description: `Install the Inspecto runtime packages with ${context.packageManager}.`
+      },
+      {
+        type: "manual_step",
+        target: buildTool.configPath,
+        description: `Update ${buildTool.configPath} to import \`webpackPlugin\` from \`@inspecto-dev/plugin/legacy/webpack4\` and add it to the Webpack plugins array.`
+      }
+    ];
+  }
   return [
     {
       type: "manual_step",
@@ -1826,7 +2088,10 @@ function manualFrameworkActions(context) {
 }
 async function createDetectionResult(root) {
   const context = await buildOnboardingContext(root);
-  const warnings = uniqueMessages([...unsupportedEnvironmentWarnings(context)]);
+  const warnings = uniqueMessages([
+    ...unsupportedEnvironmentWarnings(context),
+    ...buildToolWarnings(context)
+  ]);
   const buildToolResult = buildToolBlockers(context);
   const frameworkResult = frameworkBlockers(context);
   const blockers = uniqueMessages([...buildToolResult, ...frameworkResult]);
@@ -1849,13 +2114,22 @@ async function createDetectionResult(root) {
   };
 }
 function createPlanResult(context) {
-  const warnings = uniqueMessages(unsupportedEnvironmentWarnings(context));
+  const warnings = uniqueMessages([
+    ...unsupportedEnvironmentWarnings(context),
+    ...buildToolWarnings(context)
+  ]);
   const blockers = uniqueMessages([...buildToolBlockers(context), ...frameworkBlockers(context)]);
   const actions = [];
   let strategy = "supported";
-  if (blockers.length > 0) {
+  const hasLegacyRspackManualPlan = context.buildTools.supported.length === 1 && context.buildTools.supported[0]?.tool === "rspack" && context.buildTools.supported[0]?.isLegacyRspack;
+  const hasLegacyWebpackManualPlan = context.buildTools.supported.length === 1 && context.buildTools.supported[0]?.tool === "webpack" && context.buildTools.supported[0]?.isLegacyWebpack;
+  if (blockers.length > 0 || hasLegacyRspackManualPlan || hasLegacyWebpackManualPlan) {
     strategy = "manual";
-    if (context.buildTools.unsupported.length > 0 || context.buildTools.supported.length === 0 || context.buildTools.supported.length > 1) {
+    if (context.buildTools.unsupported.length > 0 || context.buildTools.supported.length === 0 || context.buildTools.supported.length > 1 || context.buildTools.supported.some(
+      (buildTool) => buildTool.tool === "rspack" && buildTool.isLegacyRspack
+    ) || context.buildTools.supported.some(
+      (buildTool) => buildTool.tool === "webpack" && buildTool.isLegacyWebpack
+    )) {
       actions.push(...manualBuildToolActions(context));
     }
     if (frameworkBlockers(context).length > 0) {
@@ -2040,10 +2314,26 @@ async function detect(json = false) {
 import path11 from "path";
 
 // src/onboarding/target-resolution.ts
+function buildCandidateId(candidate) {
+  return [candidate.packagePath || ".", candidate.buildTool, candidate.configPath].join(":");
+}
 function normalizePackagePath(packagePath) {
   if (!packagePath || packagePath === ".") return "";
   return packagePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
 }
+function normalizeTargetValue(target) {
+  if (!target) return "";
+  return target.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+}
+function buildSelectionPurpose() {
+  return "Choose the build target that runs your local development build so Inspecto can attach the right plugin and settings.";
+}
+function buildSelectionInstructions(hasCandidates) {
+  if (!hasCandidates) {
+    return "If auto-detection missed your build entrypoint, rerun with --target <configPath> using the config file or wrapper script your dev command actually starts.";
+  }
+  return "Rerun with --target <candidateId> using one returned candidateId. The CLI also accepts an exact configPath from the candidate list as a compatibility fallback.";
+}
 function looksLikeAppPackage(packagePath) {
   if (!packagePath) return true;
   return /(^|\/)(app|apps|web|client|frontend|site)(\/|$)/i.test(packagePath);
@@ -2054,13 +2344,19 @@ function looksLikeAuxiliaryPackage(packagePath) {
 function buildCandidates(input) {
   return input.buildTools.map((buildTool) => {
     const packagePath = normalizePackagePath(buildTool.packagePath);
-    return {
+    const candidate = {
       packagePath,
       configPath: buildTool.configPath,
+      label: buildTool.label,
       buildTool: buildTool.tool,
+      isLegacyRspack: buildTool.isLegacyRspack,
+      isLegacyWebpack: buildTool.isLegacyWebpack,
       frameworks: input.frameworkSupportByPackage[packagePath] ?? [],
       automaticInjection: true
     };
+    candidate.id = buildCandidateId(candidate);
+    candidate.candidateId = candidate.id;
+    return candidate;
   });
 }
 function rankCandidate(candidate) {
@@ -2083,18 +2379,52 @@ function resolveOnboardingTarget(input) {
     return {
       status: "needs_selection",
       candidates,
-      reason: "No supported targets were detected."
+      reason: "No supported targets were detected.",
+      selectionPurpose: buildSelectionPurpose(),
+      selectionInstructions: buildSelectionInstructions(false)
     };
   }
   const explicitlySelected = normalizePackagePath(input.selectedPackagePath);
+  const explicitlySelectedValue = normalizeTargetValue(input.selectedPackagePath);
   if (input.selectedPackagePath !== void 0) {
-    const selected = candidates.find((candidate) => candidate.packagePath === explicitlySelected);
+    const selectedById = candidates.find(
+      (candidate) => candidate.id === input.selectedPackagePath || candidate.candidateId === input.selectedPackagePath
+    );
+    if (selectedById) {
+      return {
+        status: "resolved",
+        selected: selectedById,
+        candidates,
+        reason: `Using the explicitly selected target: ${selectedById.configPath}.`,
+        selectionPurpose: buildSelectionPurpose(),
+        selectionInstructions: buildSelectionInstructions(true)
+      };
+    }
+    const selectedByConfigPath = candidates.find(
+      (candidate) => normalizeTargetValue(candidate.configPath) === explicitlySelectedValue
+    );
+    if (selectedByConfigPath) {
+      return {
+        status: "resolved",
+        selected: selectedByConfigPath,
+        candidates,
+        reason: `Using the explicitly selected config path: ${selectedByConfigPath.configPath}.`,
+        selectionPurpose: buildSelectionPurpose(),
+        selectionInstructions: buildSelectionInstructions(true)
+      };
+    }
+    const matchingPackageCandidates = candidates.filter(
+      (candidate) => candidate.packagePath === explicitlySelected
+    );
+    const selected = matchingPackageCandidates.length === 1 ? matchingPackageCandidates[0] : void 0;
     if (selected) {
       return {
         status: "resolved",
         selected,
         candidates,
-        reason: `Using the explicitly selected target: ${selected.packagePath || "."}.`
+        reason: `Using the explicitly selected target: ${selected.packagePath || "."}.`,
+        selectionPurpose: buildSelectionPurpose(),
+        selectionInstructions: buildSelectionInstructions(true)
       };
     }
   }
@@ -2103,7 +2433,9 @@ function resolveOnboardingTarget(input) {
       status: "resolved",
       selected: candidates[0],
       candidates,
-      reason: "Only one supported target was detected."
+      reason: "Only one supported target was detected.",
+      selectionPurpose: buildSelectionPurpose(),
+      selectionInstructions: buildSelectionInstructions(true)
     };
   }
   const ranked = rankCandidates(candidates);
@@ -2111,14 +2443,18 @@ function resolveOnboardingTarget(input) {
     return {
       status: "needs_selection",
       candidates,
-      reason: "Multiple supported targets look equally plausible."
+      reason: "Multiple supported targets look equally plausible.",
+      selectionPurpose: buildSelectionPurpose(),
+      selectionInstructions: buildSelectionInstructions(true)
     };
   }
   return {
     status: "resolved",
     selected: ranked[0].candidate,
     candidates,
-    reason: `Preselected ${ranked[0].candidate.packagePath || "."} because it has the strongest supported app signal.`
+    reason: `Preselected ${ranked[0].candidate.packagePath || "."} because it has the strongest supported app signal.`,
+    selectionPurpose: buildSelectionPurpose(),
+    selectionInstructions: buildSelectionInstructions(true)
   };
 }
 
@@ -2819,6 +3155,25 @@ async function collectDoctorResult(root = process.cwd()) {
     const settings = await readJSON(targetPath);
     if (settings) {
       checks.push(createDiagnostic("settings-valid", "ok", `.inspecto/${fileName} valid`));
+      const configuredIde = typeof settings.ide === "string" ? settings.ide : void 0;
+      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(
@@ -2954,7 +3309,8 @@ async function detectFrameworkSupportByPackage2(repoRoot, context) {
   );
   return supportByPackage;
 }
-async function buildTargetedContext(rootContext, packagePath) {
+async function buildTargetedContext(rootContext, target) {
+  const packagePath = normalizePackagePath2(target.packagePath);
   const projectRoot = packagePath ? path13.join(rootContext.root, packagePath) : rootContext.root;
   const [frameworks, ides, providers] = await Promise.all([
     detectFrameworks(projectRoot),
@@ -2966,7 +3322,11 @@ async function buildTargetedContext(rootContext, packagePath) {
     packageManager: rootContext.packageManager,
     buildTools: {
       supported: rootContext.buildTools.supported.filter((item) => {
-        return normalizePackagePath2(item.packagePath) === packagePath;
+        const itemPackagePath = normalizePackagePath2(item.packagePath);
+        if (target.id) {
+          return `${itemPackagePath || "."}:${item.tool}:${item.configPath}` === target.id;
+        }
+        return itemPackagePath === packagePath;
       }),
       unsupported: []
     },
@@ -3102,7 +3462,7 @@ async function resolveOnboardingSession(root, options = {}) {
   if (target.status === "needs_selection") {
     const plan3 = createPlanResult(rootContext);
     const summary2 = {
-      headline: "Inspecto found multiple plausible app targets and needs one selection.",
+      headline: "Inspecto needs one build target selection before setup so it knows which local dev build should receive the plugin and settings.",
       changes: [],
       risks: [],
       manualFollowUp: []
@@ -3118,8 +3478,7 @@ async function resolveOnboardingSession(root, options = {}) {
       projectRoot: root
     };
   }
-  const packagePath = normalizePackagePath2(target.selected?.packagePath);
-  const context = await buildTargetedContext(rootContext, packagePath);
+  const context = await buildTargetedContext(rootContext, target.selected);
   const verification = await buildVerification(context.root, context.packageManager);
   const plan2 = createPlanResult(context);
   const summary = buildOnboardingSummary(plan2, context.root);
@@ -3172,7 +3531,8 @@ async function applyResolvedOnboardingSession(session, options = {}) {
     },
     selectedIDE: session.selectedIDE,
     providerDefault: session.providerDefault,
-    plan: session.plan
+    plan: session.plan,
+    allowManualPlanApply: session.plan.strategy === "manual" && session.plan.blockers.length === 0
   });
   const diagnostics = buildExecutionDiagnostics(session, applyResult);
   const status = applyResult.postInstall.installFailed && session.context.buildTools.supported.length === 0 ? "error" : diagnostics?.nextSteps.length || diagnostics?.errors.length || diagnostics?.warnings.length ? "partial_success" : "success";
@@ -3215,6 +3575,19 @@ function printOnboardResult(result) {
   log.header("Inspecto Onboard");
   log.info(`Status: ${result.status}`);
   log.info(result.summary.headline);
+  if (result.status === "needs_target_selection") {
+    if (result.target.selectionPurpose) {
+      log.warn(result.target.selectionPurpose);
+    }
+    for (const candidate of result.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);
+    }
+  }
   for (const change of result.summary.changes) {
     log.hint(change);
   }
@@ -3889,6 +4262,10 @@ function getDispatchModeLabel(assistant, ide, mode) {
 }
 
 // src/commands/integration-install.ts
+import {
+  DEFAULT_PROVIDER_MODE,
+  VALID_MODES
+} from "@inspecto-dev/types";
 var REPO_RAW_BASE = "https://raw.githubusercontent.com/inspecto-dev/inspecto/main";
 var TOTAL_STEPS2 = 6;
 var INTEGRATION_MANIFESTS = [
@@ -3937,7 +4314,7 @@ var INTEGRATION_MANIFESTS = [
   {
     assistant: "coco",
     type: "native-skill",
-    installTarget: ".traecli/skills/inspecto-onboarding/",
+    installTarget: ".trae/skills/inspecto-onboarding/",
     preferredInstall: "npx @inspecto-dev/cli integrations install coco --host-ide <vscode|cursor|trae|trae-cn>",
     cliSupported: true
   }
@@ -3996,6 +4373,9 @@ ${content}`;
       }
     }
   }
+  if (shouldPersistProjectOnboardingDefaults(options)) {
+    await persistProjectOnboardingDefaults(assistant, options);
+  }
   const stepOneMessage = options.preview ? formatIntegrationStep2(1, `Previewing ${getAssistantLabel2(assistant)} integration assets`) : formatIntegrationStep2(1, `Installed ${getAssistantLabel2(assistant)} integration assets`);
   if (!silent) {
     if (options.preview) {
@@ -4081,6 +4461,46 @@ ${content}`;
   }
   return result;
 }
+function shouldPersistProjectOnboardingDefaults(options) {
+  return !options.preview && !shouldSkipAutomationForInstall(options) && isSupportedHostIde(options.ide);
+}
+function isProviderAssistant(value) {
+  return Object.prototype.hasOwnProperty.call(VALID_MODES, value);
+}
+async function resolveProviderDefaultForAssistant(assistant, ide) {
+  if (!isProviderAssistant(assistant)) {
+    return void 0;
+  }
+  let mode;
+  if (assistant === "codex" || assistant === "claude-code" || assistant === "gemini") {
+    const dispatchMode = await resolveIntegrationDispatchMode({ assistant, hostIde: ide });
+    mode = dispatchMode.mode ?? DEFAULT_PROVIDER_MODE[assistant];
+  } else {
+    mode = DEFAULT_PROVIDER_MODE[assistant];
+  }
+  if (!mode || !VALID_MODES[assistant].includes(mode)) {
+    return void 0;
+  }
+  return `${assistant}.${mode}`;
+}
+async function persistProjectOnboardingDefaults(assistant, options) {
+  const settingsPath = path17.join(process.cwd(), ".inspecto", "settings.local.json");
+  const existingSettings = await readJSON(settingsPath);
+  const resolvedHostIde = await resolveIntegrationHostIde({
+    explicitIde: options.ide,
+    cwd: process.cwd()
+  });
+  const providerDefault = resolvedHostIde.ide && resolvedHostIde.confidence !== "low" ? await resolveProviderDefaultForAssistant(assistant, resolvedHostIde.ide) : void 0;
+  const mergedSettings = existingSettings && typeof existingSettings === "object" ? {
+    ...existingSettings,
+    ide: options.ide,
+    ...providerDefault ? { "provider.default": providerDefault } : {}
+  } : {
+    ide: options.ide,
+    ...providerDefault ? { "provider.default": providerDefault } : {}
+  };
+  await writeJSON(settingsPath, mergedSettings);
+}
 function shouldSkipAutomationForInstall(options) {
   return options.scope === "user" && !options.preview;
 }
@@ -4143,6 +4563,12 @@ function resolveInstallPlan(assistant, options) {
             source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-trae/SKILL.md`,
             target: ".trae/skills/inspecto-onboarding/SKILL.md",
             localSource: "skills/inspecto-onboarding-trae/SKILL.md"
+          },
+          {
+            source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-trae/scripts/run-inspecto.sh`,
+            target: ".trae/skills/inspecto-onboarding/scripts/run-inspecto.sh",
+            localSource: "skills/inspecto-onboarding-trae/scripts/run-inspecto.sh",
+            executable: true
           }
         ],
         successMessage: "Installed Trae skill to .trae/skills/inspecto-onboarding/SKILL.md",
@@ -4153,11 +4579,17 @@ function resolveInstallPlan(assistant, options) {
         assets: [
           {
             source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-trae/SKILL.md`,
-            target: ".traecli/skills/inspecto-onboarding/SKILL.md",
+            target: ".trae/skills/inspecto-onboarding/SKILL.md",
             localSource: "skills/inspecto-onboarding-trae/SKILL.md"
+          },
+          {
+            source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-trae/scripts/run-inspecto.sh`,
+            target: ".trae/skills/inspecto-onboarding/scripts/run-inspecto.sh",
+            localSource: "skills/inspecto-onboarding-trae/scripts/run-inspecto.sh",
+            executable: true
           }
         ],
-        successMessage: "Installed Coco skill to .traecli/skills/inspecto-onboarding/SKILL.md",
+        successMessage: "Installed Coco skill to .trae/skills/inspecto-onboarding/SKILL.md",
         nextStep: "Start a new Coco session."
       };
     default: