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

package/dist/{chunk-PDDFPQJS.js → chunk-IBYH7QZM.js}

@@ -369,7 +369,8 @@ var STRATEGIES = [
 ];
 
 // src/inject/ast-injector.ts
-function printManualInstructions(strategy, detection, reason) {
+function printManualInstructions(strategy, detection, reason, quiet = false) {
+  if (quiet) return;
   log.warn(`Could not automatically configure ${detection.configPath}`);
   log.hint(`(reason: ${reason})`);
   log.blank();
@@ -398,17 +399,19 @@ function isAlreadyInjected(content) {
   }
   return false;
 }
-async function injectPlugin(root, detection, dryRun) {
+async function injectPlugin(root, detection, dryRun, quiet = false) {
   const configPath = path3.join(root, detection.configPath);
   const mutations = [];
   const strategy = STRATEGIES.find((s) => s.supports(detection.tool));
   const content = await readFile(configPath);
   if (!content) {
-    printManualInstructions(strategy, detection, "config file not readable");
+    printManualInstructions(strategy, detection, "config file not readable", quiet);
     return { success: false, mutations, failureReason: "config file not readable" };
   }
   if (isAlreadyInjected(content)) {
-    log.success(`Plugin already configured in ${detection.configPath} (skipped)`);
+    if (!quiet) {
+      log.success(`Plugin already configured in ${detection.configPath} (skipped)`);
+    }
     mutations.push({
       type: "file_modified",
       path: detection.configPath,
@@ -420,12 +423,15 @@ async function injectPlugin(root, detection, dryRun) {
     printManualInstructions(
       strategy,
       detection,
-      `No injection strategy found for ${detection.tool}`
+      `No injection strategy found for ${detection.tool}`,
+      quiet
     );
     return { success: false, mutations, failureReason: "No strategy found" };
   }
   if (dryRun) {
-    log.dryRun(`Would automatically configure plugin in ${detection.configPath}`);
+    if (!quiet) {
+      log.dryRun(`Would automatically configure plugin in ${detection.configPath}`);
+    }
     return { success: true, mutations: [] };
   }
   try {
@@ -440,13 +446,16 @@ async function injectPlugin(root, detection, dryRun) {
       path: detection.configPath,
       description: "Automatically configured inspecto() plugin"
     });
-    log.success(`Configured plugin in ${detection.configPath}`);
+    if (!quiet) {
+      log.success(`Configured plugin in ${detection.configPath}`);
+    }
     return { success: true, mutations };
   } catch (err) {
     printManualInstructions(
       strategy,
       detection,
-      `Automatic configuration unavailable: ${err instanceof Error ? err.message : String(err)}`
+      `Automatic configuration unavailable: ${err instanceof Error ? err.message : String(err)}`,
+      quiet
     );
     return {
       success: false,
@@ -529,9 +538,11 @@ async function tryOpenURI(uri) {
     return false;
   }
 }
-async function installExtension(dryRun, ide) {
+async function installExtension(dryRun, ide, quiet = false) {
   if (dryRun) {
-    log.dryRun("Would attempt to install VS Code extension");
+    if (!quiet) {
+      log.dryRun("Would attempt to install VS Code extension");
+    }
     return null;
   }
   const isVSCode = !ide || ide === "vscode";
@@ -539,7 +550,9 @@ async function installExtension(dryRun, ide) {
     if (await which("code")) {
       try {
         await run("code", ["--install-extension", EXTENSION_ID]);
-        log.success("VS Code extension installed via CLI");
+        if (!quiet) {
+          log.success("VS Code extension installed via CLI");
+        }
         return { type: "extension_installed", id: EXTENSION_ID };
       } catch {
       }
@@ -548,35 +561,45 @@ async function installExtension(dryRun, ide) {
     if (codePath) {
       try {
         await run(codePath, ["--install-extension", EXTENSION_ID]);
-        log.success("VS Code extension installed via binary path");
-        log.info(
-          'Tip: Add "code" to your PATH to help Inspecto detect other AI tools in the future'
-        );
+        if (!quiet) {
+          log.success("VS Code extension installed via binary path");
+          log.info(
+            'Tip: Add "code" to your PATH to help Inspecto detect other AI tools in the future'
+          );
+        }
         return { type: "extension_installed", id: EXTENSION_ID };
       } catch {
       }
     }
     const uri = `vscode:extension/${EXTENSION_ID}`;
     if (await tryOpenURI(uri)) {
-      log.warn("Opened extension page in VS Code");
-      log.hint('Please click "Install" in the opened VS Code window to complete setup.');
+      if (!quiet) {
+        log.warn("Opened extension page in VS Code");
+        log.hint('Please click "Install" in the opened VS Code window to complete setup.');
+      }
       return { type: "extension_installed", id: EXTENSION_ID, manual_action_required: true };
     }
-    log.warn("Could not auto-install VS Code extension");
-    log.hint("Please install it manually to enable Inspector features:");
-    log.hint("  1. Open VS Code");
-    log.hint("  2. Press Ctrl+Shift+X (or Cmd+Shift+X)");
-    log.hint('  3. Search for "Inspecto"');
-    log.hint(`  Or visit: https://marketplace.visualstudio.com/items?itemName=${EXTENSION_ID}`);
+    if (!quiet) {
+      log.warn("Could not auto-install VS Code extension");
+      log.hint("Please install it manually to enable Inspector features:");
+      log.hint("  1. Open VS Code");
+      log.hint("  2. Press Ctrl+Shift+X (or Cmd+Shift+X)");
+      log.hint('  3. Search for "Inspecto"');
+      log.hint(`  Or visit: https://marketplace.visualstudio.com/items?itemName=${EXTENSION_ID}`);
+    }
     return null;
   }
-  log.warn(`Could not auto-install extension for ${ide}`);
-  log.hint("Please install it manually to enable Inspector features:");
-  log.hint("  1. Download the latest .vsix file (Open VSX: https://open-vsx.org/extension/inspecto/inspecto)");
-  log.hint(`  2. Open ${ide}`);
-  log.hint("  3. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P)");
-  log.hint('  4. Type and select "Extensions: Install from VSIX..."');
-  log.hint("  5. Select the downloaded .vsix file");
+  if (!quiet) {
+    log.warn(`Could not auto-install extension for ${ide}`);
+    log.hint("Please install it manually to enable Inspector features:");
+    log.hint(
+      "  1. Download the latest .vsix file (Open VSX: https://open-vsx.org/extension/inspecto/inspecto)"
+    );
+    log.hint(`  2. Open ${ide}`);
+    log.hint("  3. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P)");
+    log.hint('  4. Type and select "Extensions: Install from VSIX..."');
+    log.hint("  5. Select the downloaded .vsix file");
+  }
   return null;
 }
 async function isExtensionInstalled() {
@@ -600,7 +623,7 @@ async function isExtensionInstalled() {
 import path4 from "path";
 var DEFAULT_RULES = [".inspecto/install.lock", ".inspecto/cache.json", ".inspecto/*.local.json"];
 var SHARED_RULES = [".inspecto/install.lock", ".inspecto/cache.json", ".inspecto/*.local.json"];
-async function updateGitignore(root, shared, dryRun) {
+async function updateGitignore(root, shared, dryRun, quiet = false) {
   const gitignorePath = path4.join(root, ".gitignore");
   let content = await readFile(gitignorePath) ?? "";
   const desiredRules = shared ? SHARED_RULES : DEFAULT_RULES;
@@ -610,7 +633,9 @@ async function updateGitignore(root, shared, dryRun) {
     if (!dryRun) {
       await writeFile(gitignorePath, content);
     }
-    log.success("Updated .gitignore: .inspecto/ is no longer fully ignored");
+    if (!quiet) {
+      log.success("Updated .gitignore: .inspecto/ is no longer fully ignored");
+    }
     return;
   }
   const missingRules = desiredRules.filter((rule) => !content.includes(rule));
@@ -620,10 +645,14 @@ async function updateGitignore(root, shared, dryRun) {
   const section = "\n# Inspecto\n" + missingRules.join("\n") + "\n";
   content = content.trimEnd() + "\n" + section;
   if (dryRun) {
-    log.dryRun(`Would update .gitignore with: ${missingRules.join(", ")}`);
+    if (!quiet) {
+      log.dryRun(`Would update .gitignore with: ${missingRules.join(", ")}`);
+    }
   } else {
     await writeFile(gitignorePath, content);
-    log.success("Updated .gitignore");
+    if (!quiet) {
+      log.success("Updated .gitignore");
+    }
   }
 }
 async function cleanGitignore(root) {
@@ -635,6 +664,26 @@ async function cleanGitignore(root) {
 }
 
 // src/onboarding/apply.ts
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function resolveRuntimePackages() {
+  const devRepo = process.env.INSPECTO_DEV_REPO;
+  if (!devRepo) {
+    return {
+      installSpec: "@inspecto-dev/plugin @inspecto-dev/core",
+      installedDependencyNames: ["@inspecto-dev/plugin", "@inspecto-dev/core"]
+    };
+  }
+  const normalizedRepo = path5.resolve(devRepo);
+  return {
+    installSpec: [
+      shellQuote(path5.join(normalizedRepo, "packages/plugin")),
+      shellQuote(path5.join(normalizedRepo, "packages/core"))
+    ].join(" "),
+    installedDependencyNames: ["@inspecto-dev/plugin", "@inspecto-dev/core"]
+  };
+}
 function resultStatus(nextSteps) {
   return nextSteps.length > 0 ? "warning" : "ok";
 }
@@ -724,10 +773,8 @@ async function applyOnboardingPlanInternal(input) {
   const promptsFileName = input.options.shared ? "prompts.json" : "prompts.local.json";
   const settingsPath = path5.join(settingsDir, settingsFileName);
   const promptsPath = path5.join(settingsDir, promptsFileName);
-  const installCmd = getInstallCommand(
-    input.packageManager,
-    "@inspecto-dev/plugin @inspecto-dev/core"
-  );
+  const runtimePackages = resolveRuntimePackages();
+  const installCmd = getInstallCommand(input.packageManager, runtimePackages.installSpec);
   const nextSteps = [];
   let installFailed = false;
   if (input.options.skipInstall) {
@@ -744,8 +791,9 @@ async function applyOnboardingPlanInternal(input) {
       await shell(installCmd, input.projectRoot);
       spinner.succeed("Dependencies installed successfully");
       reporter.success("Installed @inspecto-dev/plugin and @inspecto-dev/core as devDependencies");
-      mutations.push({ type: "dependency_added", name: "@inspecto-dev/plugin", dev: true });
-      mutations.push({ type: "dependency_added", name: "@inspecto-dev/core", dev: true });
+      for (const name of runtimePackages.installedDependencyNames) {
+        mutations.push({ type: "dependency_added", name, dev: true });
+      }
     } catch (error) {
       spinner.fail("Dependency installation failed");
       installFailed = true;
@@ -758,7 +806,12 @@ 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);
+    const result = await injectPlugin(
+      input.repoRoot,
+      target,
+      input.options.dryRun,
+      input.options.quiet ?? false
+    );
     if (result.success) {
       mutations.push(...result.mutations);
     } else {
@@ -800,7 +853,12 @@ async function applyOnboardingPlanInternal(input) {
     mutations.push({ type: "file_created", path: `.inspecto/${promptsFileName}` });
   }
   if (!input.options.dryRun) {
-    await updateGitignore(input.projectRoot, input.options.shared, input.options.dryRun);
+    await updateGitignore(
+      input.projectRoot,
+      input.options.shared,
+      input.options.dryRun,
+      input.options.quiet ?? false
+    );
     mutations.push({
       type: "file_modified",
       path: ".gitignore",
@@ -822,7 +880,11 @@ async function applyOnboardingPlanInternal(input) {
   if (input.options.noExtension) {
     reporter.warn("Skipping IDE extension (--no-extension)");
   } else if (shouldInstallExt) {
-    const extMutation = await installExtension(input.options.dryRun, input.selectedIDE?.ide);
+    const extMutation = await installExtension(
+      input.options.dryRun,
+      input.selectedIDE?.ide,
+      input.options.quiet ?? false
+    );
     if (extMutation && !input.options.dryRun) {
       mutations.push(extMutation);
       if (extMutation.manual_action_required) {
@@ -1496,7 +1558,9 @@ function unsupportedEnvironmentWarnings(context) {
   }
   const unsupportedIdes = context.ides.filter((ide) => !ide.supported).map((ide) => ide.ide);
   if (unsupportedIdes.length > 0) {
-    warnings.push(message("unsupported-ide", `Unsupported IDE(s) detected: ${unsupportedIdes.join(", ")}`));
+    warnings.push(
+      message("unsupported-ide", `Unsupported IDE(s) detected: ${unsupportedIdes.join(", ")}`)
+    );
   }
   const unsupportedProviders = context.providers.filter((provider) => !provider.supported).map((provider) => provider.label);
   if (unsupportedProviders.length > 0) {
@@ -1635,6 +1699,9 @@ function createPlanResult(context) {
     defaults
   };
 }
+function planManualFollowUp(result) {
+  return result.actions.filter((action) => action.type === "manual_step").map((action) => action.description);
+}
 
 // src/commands/apply.ts
 function getProviderDefault(providerId, preferredMode) {
@@ -1680,7 +1747,11 @@ function printApplyResult(result) {
   if (result.plan.warnings.length > 0) {
     return;
   }
-  log.ready("Ready! Hold Alt + Click any element to inspect.");
+  log.ready("Ready! Inspecto is set up.");
+  log.info("Next:");
+  log.hint("1. Start or restart your dev server.");
+  log.hint("2. Open your app in the browser.");
+  log.hint("3. Hold Alt + Click any element to inspect.");
 }
 async function apply(options = {}) {
   const root = process.cwd();
@@ -1763,6 +1834,89 @@ async function detect(json = false) {
 // src/commands/init.ts
 import path10 from "path";
 
+// src/onboarding/target-resolution.ts
+function normalizePackagePath(packagePath) {
+  if (!packagePath || packagePath === ".") return "";
+  return packagePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+}
+function looksLikeAppPackage(packagePath) {
+  if (!packagePath) return true;
+  return /(^|\/)(app|apps|web|client|frontend|site)(\/|$)/i.test(packagePath);
+}
+function looksLikeAuxiliaryPackage(packagePath) {
+  return /(^|\/)(docs?|example|examples|playground|storybook|demo)(\/|$)/i.test(packagePath);
+}
+function buildCandidates(input) {
+  return input.buildTools.map((buildTool) => {
+    const packagePath = normalizePackagePath(buildTool.packagePath);
+    return {
+      packagePath,
+      configPath: buildTool.configPath,
+      buildTool: buildTool.tool,
+      frameworks: input.frameworkSupportByPackage[packagePath] ?? [],
+      automaticInjection: true
+    };
+  });
+}
+function rankCandidate(candidate) {
+  let score = 0;
+  if (candidate.frameworks.length > 0) score += 4;
+  if (candidate.automaticInjection) score += 2;
+  if (looksLikeAppPackage(candidate.packagePath)) score += 1;
+  if (looksLikeAuxiliaryPackage(candidate.packagePath)) score -= 2;
+  return score;
+}
+function rankCandidates(candidates) {
+  return candidates.map((candidate) => ({
+    candidate,
+    score: rankCandidate(candidate)
+  })).sort((left, right) => right.score - left.score);
+}
+function resolveOnboardingTarget(input) {
+  const candidates = buildCandidates(input);
+  if (candidates.length === 0) {
+    return {
+      status: "needs_selection",
+      candidates,
+      reason: "No supported targets were detected."
+    };
+  }
+  const explicitlySelected = normalizePackagePath(input.selectedPackagePath);
+  if (input.selectedPackagePath !== void 0) {
+    const selected = candidates.find((candidate) => candidate.packagePath === explicitlySelected);
+    if (selected) {
+      return {
+        status: "resolved",
+        selected,
+        candidates,
+        reason: `Using the explicitly selected target: ${selected.packagePath || "."}.`
+      };
+    }
+  }
+  if (candidates.length === 1) {
+    return {
+      status: "resolved",
+      selected: candidates[0],
+      candidates,
+      reason: "Only one supported target was detected."
+    };
+  }
+  const ranked = rankCandidates(candidates);
+  if (ranked.length > 1 && ranked[0].score === ranked[1].score) {
+    return {
+      status: "needs_selection",
+      candidates,
+      reason: "Multiple supported targets look equally plausible."
+    };
+  }
+  return {
+    status: "resolved",
+    selected: ranked[0].candidate,
+    candidates,
+    reason: `Preselected ${ranked[0].candidate.packagePath || "."} because it has the strongest supported app signal.`
+  };
+}
+
 // src/prompts.ts
 import prompts from "prompts";
 async function promptIDEChoice(detections) {
@@ -1841,7 +1995,9 @@ async function promptMonorepoPackageChoice(detections) {
   }
   if (!process.stdin.isTTY) {
     log.error("Monorepo root detected, but stdin is not interactive.");
-    log.hint("Re-run `inspecto init` inside a specific app directory, or pass --packages <app-path>.");
+    log.hint(
+      "Re-run `inspecto init` inside a specific app directory, or pass --packages <app-path>."
+    );
     return null;
   }
   const { choice } = await prompts({
@@ -1976,27 +2132,40 @@ async function init(options) {
     verifiedPackages.length > 0 ? verifiedPackages : void 0
   );
   if (verifiedPackages.length === 0) {
-    const monorepoTargets = Array.from(
-      new Set(
-        buildResult.supported.map((d) => d.packagePath).filter((value) => !!value)
-      )
-    );
-    if (monorepoTargets.length > 1) {
-      log.warn("Monorepo root detected with multiple candidate apps.");
-      const selectedPackage = await promptMonorepoPackageChoice(buildResult.supported);
-      if (!selectedPackage) {
-        log.hint("Run `inspecto init` inside the target app, or pass --packages <app-path>.");
-        return;
+    const monorepoCandidates = buildResult.supported.filter((detection) => !!detection.packagePath);
+    if (monorepoCandidates.length > 0) {
+      const frameworkSupportByPackage = await detectFrameworkSupportByPackage(
+        repoRoot,
+        monorepoCandidates
+      );
+      const targetResolution = resolveOnboardingTarget({
+        repoRoot,
+        buildTools: monorepoCandidates,
+        frameworkSupportByPackage
+      });
+      if (targetResolution.status === "needs_selection") {
+        log.warn("Monorepo root detected with multiple candidate apps.");
+        const selectedPackage = await promptMonorepoPackageChoice(
+          monorepoCandidates.filter(
+            (detection) => targetResolution.candidates.some(
+              (candidate) => candidate.packagePath === (detection.packagePath ?? "")
+            )
+          )
+        );
+        if (!selectedPackage) {
+          log.hint("Run `inspecto init` inside the target app, or pass --packages <app-path>.");
+          return;
+        }
+        projectRoot = path10.join(repoRoot, selectedPackage);
+        buildResult = await detectBuildTools(repoRoot, [selectedPackage]);
+        log.info(`Continuing initialization in ${selectedPackage}`);
+      } else if (targetResolution.selected?.packagePath) {
+        const selectedPackage = targetResolution.selected.packagePath;
+        projectRoot = path10.join(repoRoot, selectedPackage);
+        buildResult = await detectBuildTools(repoRoot, [selectedPackage]);
+        log.warn(`Monorepo root detected. Using the only candidate app: ${selectedPackage}`);
+        log.hint("Run `inspecto init` inside that app next time to skip this prompt.");
       }
-      projectRoot = path10.join(repoRoot, selectedPackage);
-      buildResult = await detectBuildTools(repoRoot, [selectedPackage]);
-      log.info(`Continuing initialization in ${selectedPackage}`);
-    } else if (monorepoTargets.length === 1) {
-      const [selectedPackage] = monorepoTargets;
-      projectRoot = path10.join(repoRoot, selectedPackage);
-      buildResult = await detectBuildTools(repoRoot, [selectedPackage]);
-      log.warn(`Monorepo root detected. Using the only candidate app: ${selectedPackage}`);
-      log.hint("Run `inspecto init` inside that app next time to skip this prompt.");
     }
   }
   const [frameworkResult, ideProbe, providerProbe] = await Promise.all([
@@ -2173,7 +2342,11 @@ async function init(options) {
       log.hint("Complete the items above.");
       log.blank();
     } else {
-      log.ready("Ready! Hold Alt + Click any element to inspect.");
+      log.ready("Ready! Inspecto is set up.");
+      log.info("Next:");
+      log.hint("1. Start or restart your dev server.");
+      log.hint("2. Open your app in the browser.");
+      log.hint("3. Hold Alt + Click any element to inspect.");
     }
   }
 }
@@ -2198,6 +2371,19 @@ function matchesAnyPackage(detection, packages) {
   if (packages.length === 0) return true;
   return packages.some((pkg) => matchesPackage(detection, pkg));
 }
+async function detectFrameworkSupportByPackage(repoRoot, buildTools) {
+  const packagePaths = Array.from(
+    new Set(buildTools.map((buildTool) => buildTool.packagePath).filter((value) => !!value))
+  );
+  const supportByPackage = {};
+  await Promise.all(
+    packagePaths.map(async (packagePath) => {
+      const result = await detectFrameworks(path10.join(repoRoot, packagePath));
+      supportByPackage[packagePath] = result.supported;
+    })
+  );
+  return supportByPackage;
+}
 
 // src/commands/doctor.ts
 import path11 from "path";
@@ -2245,12 +2431,9 @@ function printDoctorResult(result) {
 async function collectDoctorResult(root = process.cwd()) {
   const checks = [];
   if (!await exists(path11.join(root, "package.json"))) {
-    const diagnostic = createDiagnostic(
-      "missing-package-json",
-      "error",
-      "No package.json found",
-      ["Run this command from your project root"]
-    );
+    const diagnostic = createDiagnostic("missing-package-json", "error", "No package.json found", [
+      "Run this command from your project root"
+    ]);
     checks.push(diagnostic);
     return {
       status: "blocked",
@@ -2374,20 +2557,28 @@ async function collectDoctorResult(root = process.cwd()) {
     }
     if (!injected) {
       checks.push(
-        createDiagnostic("plugin-not-configured", "error", "Plugin not configured in any build config", [
-          "Fix: npx @inspecto-dev/cli init"
-        ])
+        createDiagnostic(
+          "plugin-not-configured",
+          "error",
+          "Plugin not configured in any build config",
+          ["Fix: npx @inspecto-dev/cli init"]
+        )
       );
     }
   } 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"
-      ])
+      createDiagnostic(
+        `build-tool-unsupported`,
+        "warning",
+        `Build tool: ${names} (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"));
+    checks.push(
+      createDiagnostic("build-tool-missing", "warning", "No recognized build config found")
+    );
   }
   if (extInstalled) {
     checks.push(createDiagnostic("extension-installed", "ok", "VS Code extension detected"));
@@ -2483,6 +2674,350 @@ async function doctor(options = {}) {
   return writeCommandOutput(result, json, printDoctorResult);
 }
 
+// src/onboarding/session.ts
+import path12 from "path";
+function normalizePackagePath2(packagePath) {
+  if (!packagePath || packagePath === ".") return "";
+  return packagePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+}
+function getProviderDefault2(providerId, preferredMode) {
+  if (!providerId) return void 0;
+  const mode = preferredMode ?? (providerId === "coco" ? "cli" : "extension");
+  return `${providerId}.${mode}`;
+}
+function getVerificationCommand(packageManager) {
+  switch (packageManager) {
+    case "pnpm":
+      return "pnpm dev";
+    case "yarn":
+      return "yarn dev";
+    case "bun":
+      return "bun run dev";
+    case "npm":
+    default:
+      return "npm run dev";
+  }
+}
+async function buildVerification(projectRoot, packageManager) {
+  const packageJson = await readJSON(
+    path12.join(projectRoot, "package.json")
+  );
+  if (packageJson?.scripts?.dev) {
+    const devCommand = getVerificationCommand(packageManager);
+    return {
+      available: true,
+      devCommand,
+      message: `Start the local dev server with \`${devCommand}\` to verify Inspecto in the browser.`
+    };
+  }
+  return {
+    available: false,
+    message: "Start your normal local dev server command to verify Inspecto in the browser."
+  };
+}
+function buildIdeExtensionStatus(input) {
+  if (!input.required) {
+    return {
+      required: false,
+      installed: false,
+      manualRequired: false
+    };
+  }
+  return {
+    required: true,
+    installed: input.installed,
+    manualRequired: input.manualRequired,
+    installCommand: "code --install-extension inspecto.inspecto",
+    marketplaceUrl: "https://marketplace.visualstudio.com/items?itemName=inspecto.inspecto",
+    openVsxUrl: "https://open-vsx.org/extension/inspecto/inspecto"
+  };
+}
+async function detectFrameworkSupportByPackage2(repoRoot, context) {
+  const packagePaths = new Set(
+    context.buildTools.supported.map((item) => normalizePackagePath2(item.packagePath))
+  );
+  const supportByPackage = {};
+  await Promise.all(
+    Array.from(packagePaths).map(async (packagePath) => {
+      const frameworkResult = await detectFrameworks(
+        packagePath ? path12.join(repoRoot, packagePath) : repoRoot
+      );
+      supportByPackage[packagePath] = frameworkResult.supported;
+    })
+  );
+  return supportByPackage;
+}
+async function buildTargetedContext(rootContext, packagePath) {
+  const projectRoot = packagePath ? path12.join(rootContext.root, packagePath) : rootContext.root;
+  const [frameworks, ides, providers] = await Promise.all([
+    detectFrameworks(projectRoot),
+    detectIDE(projectRoot),
+    detectProviders(projectRoot)
+  ]);
+  return {
+    root: projectRoot,
+    packageManager: rootContext.packageManager,
+    buildTools: {
+      supported: rootContext.buildTools.supported.filter((item) => {
+        return normalizePackagePath2(item.packagePath) === packagePath;
+      }),
+      unsupported: []
+    },
+    frameworks: {
+      supported: frameworks.supported,
+      unsupported: frameworks.unsupported.map((item) => item.name)
+    },
+    ides: ides.detected.map(({ ide, supported }) => ({ ide, supported })),
+    providers: providers.detected.map(({ id, label, supported, preferredMode }) => ({
+      id,
+      label,
+      supported,
+      preferredMode
+    }))
+  };
+}
+function buildOnboardingSummary(plan2, projectRoot) {
+  const changes = plan2.actions.filter((action) => action.type !== "manual_step").map((action) => action.description);
+  const risks = [...plan2.warnings.map((item) => item.message)];
+  const manualFollowUp = planManualFollowUp(plan2);
+  let headline = `Inspecto is ready to onboard ${projectRoot}.`;
+  if (manualFollowUp.length > 0) {
+    headline = `Inspecto can partially onboard ${projectRoot}, but manual follow-up remains.`;
+  } else if (plan2.status === "blocked") {
+    headline = `Inspecto could not build an automatic onboarding path for ${projectRoot}.`;
+  }
+  return {
+    headline,
+    changes,
+    risks,
+    manualFollowUp
+  };
+}
+function buildConfirmation(plan2, summary, session, options) {
+  if (options.yes) {
+    return { required: false };
+  }
+  const reasons = [];
+  if (session.targetWasHeuristic) reasons.push("a monorepo target was preselected");
+  if (summary.manualFollowUp.length > 0) reasons.push("manual follow-up will remain after setup");
+  if (options.noExtension || options.skipInstall) reasons.push("non-core setup steps are being skipped");
+  if (session.supportedIdeCount > 1 || session.supportedProviderCount > 1) {
+    reasons.push("multiple IDE or provider choices are still relevant");
+  }
+  if (plan2.warnings.length > 0) reasons.push("the CLI detected non-blocking risk");
+  if (reasons.length === 0) {
+    return { required: false };
+  }
+  return {
+    required: true,
+    reason: reasons.join("; "),
+    question: "Proceed with Inspecto onboarding using the proposed default target and settings?"
+  };
+}
+function buildPreApplyResult(status, session) {
+  const diagnostics = session.summary.risks.length > 0 || session.summary.manualFollowUp.length > 0 || session.plan.blockers.length > 0 ? {
+    warnings: session.summary.risks,
+    errors: session.plan.blockers.map((item) => item.message),
+    nextSteps: session.summary.manualFollowUp
+  } : void 0;
+  return {
+    status,
+    target: session.target,
+    summary: session.summary,
+    confirmation: session.confirmation,
+    ideExtension: buildIdeExtensionStatus({
+      required: session.plan.defaults.extension,
+      installed: false,
+      manualRequired: session.plan.defaults.extension
+    }),
+    verification: session.verification,
+    diagnostics
+  };
+}
+function buildExecutionResult(session, applyResult) {
+  return {
+    changedFiles: Array.from(
+      new Set(applyResult.mutations.map((item) => item.path).filter((value) => !!value))
+    ),
+    installedDependencies: applyResult.mutations.map((item) => item.name).filter((value) => !!value),
+    selectedProviderDefault: session.providerDefault,
+    selectedIDE: session.selectedIDE?.ide,
+    mutations: applyResult.mutations
+  };
+}
+function buildExecutionDiagnostics(session, applyResult) {
+  const warnings = [...session.plan.warnings.map((item) => item.message)];
+  const errors = [];
+  if (applyResult.postInstall.installFailed) {
+    errors.push("Dependency installation failed during onboarding.");
+  }
+  if (applyResult.postInstall.injectionFailed) {
+    warnings.push("Automatic plugin injection did not finish cleanly.");
+  }
+  if (applyResult.postInstall.manualExtensionInstallNeeded) {
+    warnings.push("IDE extension installation still needs manual completion.");
+  }
+  if (warnings.length === 0 && errors.length === 0 && applyResult.postInstall.nextSteps.length === 0) {
+    return void 0;
+  }
+  return {
+    warnings,
+    errors,
+    nextSteps: applyResult.postInstall.nextSteps
+  };
+}
+async function resolveOnboardingSession(root, options = {}) {
+  const rootContext = await buildOnboardingContext(root);
+  const rootVerification = await buildVerification(root, rootContext.packageManager);
+  const frameworkSupportByPackage = await detectFrameworkSupportByPackage2(root, rootContext);
+  const target = resolveOnboardingTarget({
+    repoRoot: root,
+    buildTools: rootContext.buildTools.supported,
+    frameworkSupportByPackage,
+    selectedPackagePath: options.target
+  });
+  if (target.candidates.length === 0) {
+    const plan3 = createPlanResult(rootContext);
+    return {
+      status: "error",
+      target,
+      summary: buildOnboardingSummary(plan3, root),
+      confirmation: { required: false },
+      verification: rootVerification,
+      context: rootContext,
+      plan: plan3,
+      projectRoot: root
+    };
+  }
+  if (target.status === "needs_selection") {
+    const plan3 = createPlanResult(rootContext);
+    const summary2 = {
+      headline: "Inspecto found multiple plausible app targets and needs one selection.",
+      changes: [],
+      risks: [],
+      manualFollowUp: []
+    };
+    return {
+      status: "needs_target_selection",
+      target,
+      summary: summary2,
+      confirmation: { required: false },
+      verification: rootVerification,
+      context: rootContext,
+      plan: plan3,
+      projectRoot: root
+    };
+  }
+  const packagePath = normalizePackagePath2(target.selected?.packagePath);
+  const context = await buildTargetedContext(rootContext, packagePath);
+  const verification = await buildVerification(context.root, context.packageManager);
+  const plan2 = createPlanResult(context);
+  const summary = buildOnboardingSummary(plan2, context.root);
+  const confirmation = buildConfirmation(
+    plan2,
+    summary,
+    {
+      targetWasHeuristic: target.candidates.length > 1 && options.target === void 0,
+      supportedIdeCount: context.ides.filter((item) => item.supported).length,
+      supportedProviderCount: context.providers.filter((item) => item.supported).length
+    },
+    options
+  );
+  const selectedProvider = context.providers.find((provider) => provider.id === plan2.defaults.provider) ?? null;
+  const selectedIDE = context.ides.find((ide) => ide.ide === plan2.defaults.ide) ?? context.ides.find((ide) => ide.supported) ?? null;
+  let status = "success";
+  if (plan2.status === "blocked") {
+    status = "error";
+  } else if (confirmation.required) {
+    status = "needs_confirmation";
+  } else if (summary.manualFollowUp.length > 0 || plan2.warnings.length > 0) {
+    status = "partial_success";
+  }
+  return {
+    status,
+    target,
+    summary,
+    confirmation,
+    verification,
+    context,
+    plan: plan2,
+    projectRoot: context.root,
+    selectedIDE,
+    providerDefault: getProviderDefault2(plan2.defaults.provider, selectedProvider?.preferredMode)
+  };
+}
+async function applyResolvedOnboardingSession(session, options = {}) {
+  const verification = await buildVerification(session.projectRoot, session.context.packageManager);
+  const applyResult = await applyOnboardingPlan({
+    repoRoot: process.cwd(),
+    projectRoot: session.projectRoot,
+    packageManager: session.context.packageManager,
+    supportedBuildTargets: session.context.buildTools.supported,
+    options: {
+      shared: options.shared ?? session.plan.defaults.shared,
+      skipInstall: options.skipInstall ?? false,
+      dryRun: options.dryRun ?? false,
+      noExtension: options.noExtension ?? !session.plan.defaults.extension,
+      quiet: options.json ?? false
+    },
+    selectedIDE: session.selectedIDE,
+    providerDefault: session.providerDefault,
+    plan: session.plan
+  });
+  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";
+  return {
+    status,
+    target: session.target,
+    summary: session.summary,
+    confirmation: session.confirmation,
+    ideExtension: buildIdeExtensionStatus({
+      required: session.plan.defaults.extension,
+      installed: session.plan.defaults.extension && !applyResult.postInstall.manualExtensionInstallNeeded,
+      manualRequired: applyResult.postInstall.manualExtensionInstallNeeded
+    }),
+    verification,
+    result: buildExecutionResult(session, applyResult),
+    diagnostics
+  };
+}
+function buildDeferredOnboardResult(session) {
+  return buildPreApplyResult(session.status, session);
+}
+
+// src/commands/onboard.ts
+function printOnboardResult(result) {
+  log.header("Inspecto Onboard");
+  log.info(`Status: ${result.status}`);
+  log.info(result.summary.headline);
+  for (const change of result.summary.changes) {
+    log.hint(change);
+  }
+  for (const step of result.diagnostics?.nextSteps ?? []) {
+    log.warn(step);
+  }
+  if (result.confirmation.required && result.confirmation.question) {
+    log.warn(result.confirmation.question);
+  }
+  const extensionReady = !result.ideExtension?.required || result.ideExtension.installed && !result.ideExtension.manualRequired;
+  if (extensionReady && (result.status === "success" || result.status === "partial_success") && result.verification?.message) {
+    log.info(result.verification.message);
+  }
+}
+async function onboard(options = {}) {
+  const root = process.cwd();
+  const session = await resolveOnboardingSession(root, options);
+  if (session.status === "error" || session.status === "needs_target_selection" || session.status === "needs_confirmation") {
+    return writeCommandOutput(
+      buildDeferredOnboardResult(session),
+      options.json ?? false,
+      printOnboardResult
+    );
+  }
+  const result = await applyResolvedOnboardingSession(session, options);
+  return writeCommandOutput(result, options.json ?? false, printOnboardResult);
+}
+
 // src/commands/plan.ts
 function printPlanResult(result) {
   log.header("Inspecto Plan");
@@ -2517,11 +3052,11 @@ async function plan(json = false) {
 }
 
 // src/commands/teardown.ts
-import path12 from "path";
+import path13 from "path";
 async function teardown() {
   const root = process.cwd();
   log.header("Inspecto Teardown");
-  const lockPath = path12.join(root, ".inspecto", "install.lock");
+  const lockPath = path13.join(root, ".inspecto", "install.lock");
   const lock = await readJSON(lockPath);
   if (!lock) {
     log.warn("No .inspecto/install.lock found. Running in best-effort mode.");
@@ -2534,8 +3069,8 @@ async function teardown() {
     } catch {
       log.warn("Could not remove @inspecto-dev/plugin (may not be installed)");
     }
-    if (await exists(path12.join(root, ".inspecto"))) {
-      await removeDir(path12.join(root, ".inspecto"));
+    if (await exists(path13.join(root, ".inspecto"))) {
+      await removeDir(path13.join(root, ".inspecto"));
       log.success("Deleted .inspecto/ directory");
     }
     await cleanGitignore(root);
@@ -2584,7 +3119,7 @@ async function teardown() {
       }
     }
   }
-  await removeDir(path12.join(root, ".inspecto"));
+  await removeDir(path13.join(root, ".inspecto"));
   log.success("Deleted .inspecto/ directory");
   await cleanGitignore(root);
   log.blank();
@@ -2593,6 +3128,9 @@ async function teardown() {
 }
 
 export {
+  exists,
+  writeFile,
+  log,
   writeCommandOutput,
   reportCommandError,
   apply,
@@ -2600,6 +3138,7 @@ export {
   init,
   collectDoctorResult,
   doctor,
+  onboard,
   plan,
   teardown
 };