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

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @inspecto-dev/cli@0.2.0-alpha.3 build /Users/bytedance/Works/hugo.felix/inspecto/packages/cli
+> @inspecto-dev/cli@0.2.0-alpha.5 build /Users/bytedance/Works/hugo.felix/inspecto/packages/cli
 > tsup
 
 CLI Building entry: src/bin.ts, src/index.ts
@@ -10,11 +10,11 @@
 CLI Target: node18
 CLI Cleaning output folder
 ESM Build start
-ESM dist/index.js          109.00 B
-ESM dist/chunk-EUCQCD3Y.js 57.56 KB
-ESM dist/bin.js            2.64 KB
-ESM ⚡️ Build success in 136ms
+ESM dist/bin.js            4.61 KB
+ESM dist/chunk-PDDFPQJS.js 85.74 KB
+ESM dist/index.js          297.00 B
+ESM ⚡️ Build success in 43ms
 DTS Build start
-DTS ⚡️ Build success in 1464ms
-DTS dist/bin.d.ts   13.00 B
-DTS dist/index.d.ts 1.18 KB
+DTS ⚡️ Build success in 1330ms
+DTS dist/bin.d.ts   184.00 B
+DTS dist/index.d.ts 4.90 KB

package/.turbo/turbo-test.log

@@ -1,21 +1,16 @@
-
-
-> @inspecto-dev/cli@0.2.0-alpha.3 test /Users/bytedance/Works/hugo.felix/inspecto/packages/cli
-> vitest run --passWithNoTests
-
-
- RUN  v1.6.1 /Users/bytedance/Works/hugo.felix/inspecto/packages/cli
-
-[?25l ✓ tests/framework.test.ts (5)
- ✓ tests/build-tool.test.ts (2)
- ✓ tests/ide.test.ts (6)
- ✓ tests/framework.test.ts (5)
- ✓ tests/build-tool.test.ts (2)
- ✓ tests/ide.test.ts (6)
-
- Test Files  3 passed (3)
-      Tests  13 passed (13)
-   Start at  11:27:40
-   Duration  548ms (transform 85ms, setup 0ms, collect 131ms, tests 15ms, environment 0ms, prepare 374ms)
-
-[?25h[?25h
+
+> @inspecto-dev/cli@0.2.0-alpha.4 test /Users/bytedance/Works/hugo.felix/inspecto/packages/cli
+> vitest run --passWithNoTests
+
+
+ RUN  v1.6.1 /Users/bytedance/Works/hugo.felix/inspecto/packages/cli
+
+ ✓ tests/framework.test.ts  (5 tests) 4ms
+ ✓ tests/build-tool.test.ts  (2 tests) 9ms
+ ✓ tests/ide.test.ts  (6 tests) 8ms
+
+ Test Files  3 passed (3)
+      Tests  13 passed (13)
+   Start at  15:41:01
+   Duration  771ms (transform 133ms, setup 1ms, collect 221ms, tests 21ms, environment 0ms, prepare 367ms)
+

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @inspecto-dev/cli
 
+## 0.2.0-alpha.6
+
+### Minor Changes
+
+- release alpha test version
+
+## 0.2.0-alpha.5
+
+### Minor Changes
+
+- release alpha test version
+
 ## 0.2.0-alpha.4
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,23 @@
 # @inspecto-dev/cli
 
-The official command-line interface for Inspecto. This tool automates the process of scaffolding, configuring, and maintaining the Inspecto setup within your project.
+The official command-line interface for Inspecto. This tool automates the process of detecting, planning, applying, and maintaining the Inspecto setup within your project.
+
+## Onboarding Flow
+
+For agent-capable environments, the preferred setup path is structured and machine-readable:
+
+1. `inspecto detect --json`
+2. `inspecto plan --json`
+3. `inspecto apply`
+4. `inspecto doctor --json`
+
+See the public onboarding contract for response shapes and field semantics:
+`packages/docs/integrations/onboarding-contract.md`
+
+Assistant-specific onboarding entrypoints are documented in:
+`packages/docs/integrations/onboarding-skills.md`
+
+Use `inspecto init` when you want a guided manual setup in the terminal, or when the structured flow is not available.
 
 ## Installation
 
@@ -18,20 +35,34 @@ npm install -D @inspecto-dev/cli
 
 ## Commands
 
-### `inspecto init`
+### `inspecto detect`
 
-The primary command to scaffold Inspecto into a project. It performs a comprehensive environmental analysis and automatically configures Inspecto.
+Detects whether the current project can be onboarded automatically.
 
 **Features:**
 
-- **Package Manager Detection:** Auto-detects `npm`, `pnpm`, `yarn`, or `bun`.
-- **Build Tool / Framework Detection:** Detects Vite, Webpack, Rspack, Rsbuild, and others. Supports legacy versions (e.g., `@rspack/cli < 0.4.0`).
-- **IDE Detection:** Prioritizes environment variables, then falls back to directory structures to accurately detect VS Code, Cursor, Trae, Windsurf, or WebStorm.
-- **AI Tool Detection:** Scans for both CLI-based tools (Claude, Coco, CodeX, Gemini) and IDE Plugins (GitHub Copilot, Claude Code, Gemini, CodeX).
-- **Interactive Prompts:** If multiple build configurations or AI tools are detected, it presents an interactive prompt for you to select your preferred configuration.
-- **AST Injection:** Safely injects the `@inspecto-dev/plugin` into your Vite configuration file (`vite.config.ts`, etc.) using AST transformation, preventing duplicate injections. Manual setup is required for other build tools.
-- **IDE Extension Installation:** Uses a robust 4-level waterfall strategy to install the necessary IDE extension.
-- **Configuration Scaffolding:** Generates the `.inspecto/settings.local.json` file tailored to your detected or selected AI tools, and updates `.gitignore` to prevent committing local settings.
+- Detects the package manager, build tool/framework, IDE, and available AI tools.
+- Produces structured output for agent-driven setup flows.
+
+### `inspecto plan`
+
+Previews the onboarding plan for the current project.
+
+**Features:**
+
+- Summarizes the proposed setup strategy and actions.
+- Produces structured output that agents can inspect before applying changes.
+
+### `inspecto apply`
+
+Applies the onboarding plan to the current project.
+
+**Features:**
+
+- Installs the required `@inspecto-dev/plugin` dependencies.
+- Injects the plugin into supported build configurations.
+- Installs or configures the selected IDE extension when needed.
+- Writes `.inspecto/settings.local.json` and updates `.gitignore` when appropriate.
 
 ### `inspecto doctor`
 
@@ -43,6 +74,22 @@ A diagnostic command to verify your current environment.
 - Verifies if the IDE is supported.
 - Scans for available AI tools (both CLI and Plugin modes).
 - Validates the current Inspecto installation and configuration.
+- Supports `--json` for agent-friendly diagnostics.
+
+### `inspecto init`
+
+The guided/manual fallback for scaffolding Inspecto into a project. It performs a comprehensive environmental analysis and automatically configures Inspecto in one step.
+
+**Features:**
+
+- **Package Manager Detection:** Auto-detects `npm`, `pnpm`, `yarn`, or `bun`.
+- **Build Tool / Framework Detection:** Detects Vite, Webpack, Rspack, Rsbuild, and others. Supports legacy versions (e.g., `@rspack/cli < 0.4.0`).
+- **IDE Detection:** Prioritizes environment variables, then falls back to directory structures to accurately detect VS Code, Cursor, Trae, Windsurf, or WebStorm.
+- **AI Tool Detection:** Scans for both CLI-based tools (Claude, Coco, CodeX, Gemini) and IDE Plugins (GitHub Copilot, Claude Code, Gemini, CodeX).
+- **Interactive Prompts:** If multiple build configurations or AI tools are detected, it presents an interactive prompt for you to select your preferred configuration.
+- **AST Injection:** Safely injects the `@inspecto-dev/plugin` into your Vite configuration file (`vite.config.ts`, etc.) using AST transformation, preventing duplicate injections. Manual setup is required for other build tools.
+- **IDE Extension Installation:** Uses a robust 4-level waterfall strategy to install the necessary IDE extension.
+- **Configuration Scaffolding:** Generates the `.inspecto/settings.local.json` file tailored to your detected or selected AI tools, and updates `.gitignore` to prevent committing local settings.
 
 ### `inspecto teardown`
 

package/bin/inspecto.js

@@ -1,3 +1,7 @@
 #!/usr/bin/env node
 
-import '../dist/bin.js'
+/* global process */
+
+import { runCli } from '../dist/bin.js'
+
+void runCli(process.argv)

package/dist/bin.d.ts

@@ -1,2 +1,6 @@
+import { CAC } from 'cac';
 
-export {  }
+declare function createCli(argv?: readonly string[]): CAC;
+declare function runCli(argv?: readonly string[]): Promise<void>;
+
+export { createCli, runCli };

package/dist/bin.js

@@ -1,65 +1,104 @@
 import {
+  apply,
+  detect,
   doctor,
   init,
-  log,
+  plan,
+  reportCommandError,
   teardown
-} from "./chunk-EUCQCD3Y.js";
+} from "./chunk-PDDFPQJS.js";
 
 // src/bin.ts
 import { cac } from "cac";
+import { fileURLToPath } from "url";
 import { createRequire } from "module";
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
-var cli = cac("inspecto");
-cli.command("init", "Set up Inspecto in your project").option("--shared", "Share .inspecto/settings.json with your team via Git", { default: false }).option("--skip-install", "Skip npm dependency installation", { default: false }).option("--dry-run", "Preview changes without modifying files", { default: false }).option("--provider <provider>", "Set default provider (e.g. copilot, claude-code)").option("--no-extension", "Skip VS Code extension installation", { default: false }).option("--packages <names>", "(Monorepo) Comma-separated list of packages to inject").option("--force", "Force initialization even if environment is unsupported", { default: false }).option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
-  try {
-    await init({
-      shared: options.shared ?? false,
-      skipInstall: options.skipInstall ?? false,
-      dryRun: options.dryRun ?? false,
-      ...options.provider && { provider: options.provider },
-      // Changed from prefer to provider
-      noExtension: options.noExtension ?? false,
-      ...options.packages && {
-        packages: options.packages.split(",").map((s) => s.trim())
-      },
-      force: options.force ?? false
-    });
-  } catch (err) {
-    log.error(err instanceof Error ? err.message : String(err));
-    if (options.debug && err instanceof Error && err.stack) {
-      console.error(err.stack);
+function exitWithError(error, options = {}) {
+  reportCommandError(error, {
+    debug: options.debug ?? false,
+    json: options.json ?? false
+  });
+  process.exit(1);
+}
+function createCli(argv = process.argv) {
+  const cli = cac("inspecto");
+  cli.command("init", "Set up Inspecto in your project").option("--shared", "Share .inspecto/settings.json with your team via Git", { default: false }).option("--skip-install", "Skip npm dependency installation", { default: false }).option("--dry-run", "Preview changes without modifying files", { default: false }).option("--provider <provider>", "Set default provider (e.g. copilot, claude-code)").option("--no-extension", "Skip VS Code extension installation", { default: false }).option("--packages <names>", "(Monorepo) Comma-separated list of packages to inject").option("--force", "Force initialization even if environment is unsupported", { default: false }).option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
+    try {
+      await init({
+        shared: options.shared ?? false,
+        skipInstall: options.skipInstall ?? false,
+        dryRun: options.dryRun ?? false,
+        ...options.provider && { provider: options.provider },
+        noExtension: options.noExtension ?? false,
+        ...options.packages && {
+          packages: options.packages.split(",").map((s) => s.trim())
+        },
+        force: options.force ?? false
+      });
+    } catch (error) {
+      exitWithError(error, options);
     }
-    process.exit(1);
-  }
-});
-cli.command("doctor", "Diagnose your Inspecto installation").option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
-  try {
-    await doctor();
-  } catch (err) {
-    log.error(err instanceof Error ? err.message : String(err));
-    if (options.debug && err instanceof Error && err.stack) {
-      console.error(err.stack);
+  });
+  cli.command("doctor", "Diagnose your Inspecto installation").option("--json", "Print machine-readable JSON output", { default: false }).option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
+    try {
+      await doctor({ json: options.json ?? false });
+    } catch (error) {
+      exitWithError(error, options);
     }
-    process.exit(1);
-  }
-});
-cli.command("teardown", "Remove Inspecto from your project").option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
-  try {
-    await teardown();
-  } catch (err) {
-    log.error(err instanceof Error ? err.message : String(err));
-    if (options.debug && err instanceof Error && err.stack) {
-      console.error(err.stack);
+  });
+  cli.command("detect", "Detect whether the current project can be onboarded automatically").option("--json", "Print machine-readable JSON output", { default: false }).option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
+    try {
+      await detect(options.json ?? false);
+    } catch (error) {
+      exitWithError(error, options);
     }
-    process.exit(1);
+  });
+  cli.command("plan", "Preview the onboarding plan for the current project").option("--json", "Print machine-readable JSON output", { default: false }).option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
+    try {
+      await plan(options.json ?? false);
+    } catch (error) {
+      exitWithError(error, options);
+    }
+  });
+  cli.command("apply", "Apply the onboarding plan to the current project").option("--json", "Print machine-readable JSON output", { default: false }).option("--shared", "Write shared Inspecto settings instead of local-only settings").option("--skip-install", "Skip npm dependency installation").option("--dry-run", "Preview changes without modifying files").option("--no-extension", "Skip IDE extension installation").option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
+    try {
+      await apply({
+        json: options.json ?? false,
+        ...options.shared !== void 0 && { shared: options.shared },
+        ...options.skipInstall !== void 0 && { skipInstall: options.skipInstall },
+        ...options.dryRun !== void 0 && { dryRun: options.dryRun },
+        ...options.extension === false && { noExtension: true }
+      });
+    } catch (error) {
+      exitWithError(error, options);
+    }
+  });
+  cli.command("teardown", "Remove Inspecto from your project").option("--debug", "Enable debug mode to show full error traces", { default: false }).action(async (options) => {
+    try {
+      await teardown();
+    } catch (error) {
+      exitWithError(error, options);
+    }
+  });
+  cli.help();
+  cli.version(version);
+  return cli;
+}
+async function runCli(argv = process.argv) {
+  const cli = createCli(argv);
+  const parsedArgv = [...argv];
+  try {
+    await cli.parse(parsedArgv);
+  } catch (error) {
+    exitWithError(error, { json: argv.includes("--json") });
   }
-});
-cli.help();
-cli.version(version);
-try {
-  cli.parse();
-} catch (err) {
-  log.error(err instanceof Error ? err.message : String(err));
-  process.exit(1);
 }
+var entryPath = process.argv[1];
+if (entryPath && fileURLToPath(import.meta.url) === entryPath) {
+  void runCli();
+}
+export {
+  createCli,
+  runCli
+};