@inspecto-dev/cli 0.2.0-alpha.0

package/.turbo/turbo-build.log

@@ -0,0 +1,19 @@
+
+> @inspecto-dev/cli@0.2.0-alpha.0 build /Users/bytedance/Works/hugo.felix/inspecto/packages/cli
+> tsup
+
+CLI Building entry: src/bin.ts, src/index.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Using tsup config: /Users/bytedance/Works/hugo.felix/inspecto/packages/cli/tsup.config.ts
+CLI Target: node18
+CLI Cleaning output folder
+ESM Build start
+ESM dist/index.js          109.00 B
+ESM dist/chunk-4RR7PTRN.js 44.32 KB
+ESM dist/bin.js            2.47 KB
+ESM ⚡️ Build success in 25ms
+DTS Build start
+DTS ⚡️ Build success in 1355ms
+DTS dist/bin.d.ts   13.00 B
+DTS dist/index.d.ts 1.16 KB

package/.turbo/turbo-test.log

@@ -0,0 +1,15 @@
+
+> @inspecto/cli@0.1.0 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) 3ms
+ ✓ tests/ide.test.ts  (6 tests) 3ms
+
+ Test Files  2 passed (2)
+      Tests  11 passed (11)
+   Start at  11:28:38
+   Duration  783ms (transform 117ms, setup 0ms, collect 167ms, tests 6ms, environment 0ms, prepare 810ms)
+

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @inspecto-dev/cli
+
+## 0.2.0-alpha.0
+
+### Minor Changes
+
+- b3cd76b: Initial release of Inspecto
+
+### Patch Changes
+
+- release first internal alpha version
+- Updated dependencies
+- Updated dependencies [b3cd76b]
+  - @inspecto-dev/types@0.2.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Inspecto Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @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.
+
+## Installation
+
+You can use the CLI without installing it globally by using `npx`:
+
+```bash
+npx inspecto <command>
+```
+
+Alternatively, you can install it as a dev dependency in your project:
+
+```bash
+npm install -D @inspecto-dev/cli
+```
+
+## Commands
+
+### `inspecto init`
+
+The primary command to scaffold Inspecto into a project. It performs a comprehensive environmental analysis and automatically configures Inspecto.
+
+**Features:**
+
+- **Package Manager Detection:** Auto-detects `npm`, `pnpm`, `yarn`, or `bun`.
+- **Build Tool / Framework Detection:** Detects Vite, Webpack, Rspack, Rsbuild, and Next.js. 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 build configuration file (`vite.config.ts`, `rspack.config.js`, etc.) using AST transformation, preventing duplicate injections.
+- **IDE Extension Installation:** Uses a robust 4-level waterfall strategy to install the necessary IDE extension.
+- **Configuration Scaffolding:** Generates the `.inspecto/settings.json` file tailored to your detected or selected AI tools, and updates `.gitignore` to prevent committing local settings.
+
+### `inspecto doctor`
+
+A diagnostic command to verify your current environment.
+
+**Features:**
+
+- Checks if the current project is a recognized framework/build tool.
+- Verifies if the IDE is supported.
+- Scans for available AI tools (both CLI and Plugin modes).
+- Validates the current Inspecto installation and configuration.
+
+### `inspecto teardown`
+
+A clean-up command to remove Inspecto from your project.
+
+**Features:**
+
+- Uninstalls `@inspecto-dev/plugin` and `@inspecto-dev/cli`.
+- Uses AST transformation to carefully remove the plugin injection from your build configuration file.
+- Deletes the `.inspecto` directory and its contents.
+- Restores `.gitignore` by removing Inspecto-specific rules.
+
+## Technical Details
+
+### Waterfall Degradation Strategy
+
+The CLI employs a resilient fallback strategy for certain operations, such as installing IDE extensions.
+
+**IDE Extension Installation Levels:**
+
+1. **PATH Command:** Attempts to use the IDE's CLI command (e.g., `code --install-extension`).
+2. **Binary Path:** Searches known default installation paths for the IDE binary across different operating systems (macOS, Linux, Windows).
+3. **URI Scheme:** Uses the IDE's deep-link URI scheme (e.g., `vscode:extension/inspecto...`).
+4. **Manual:** If all else fails, provides explicit instructions for the user to install the extension manually.
+
+### AI Tool Detection
+
+The CLI intelligently detects AI tools across two modes:
+
+- **CLI Mode:** Checks the system `PATH` for known executables (e.g., `claude`, `coco`).
+- **Plugin Mode:** Checks the IDE's extension directories (e.g., `~/.vscode/extensions`) for known plugin IDs.
+
+When a tool supports both modes, the CLI merges the detections and presents a unified option to the user, configuring the `settings.json` accordingly.

package/TESTING.md

@@ -0,0 +1,109 @@
+# Inspecto CLI Manual Testing Checklist
+
+The Inspecto CLI relies on detecting various project states (package managers, frameworks, build tools, and IDEs) and safely mutating user files via AST parsing. While we have automated tests, the complexity of real-world project configurations means manual end-to-end (E2E) testing is critical before a release.
+
+Use this checklist to perform a comprehensive regression test of the CLI.
+
+---
+
+## Preparation
+
+Create a fresh testing environment using a supported toolchain (e.g., Rsbuild + React) in the `playground/` directory:
+
+```bash
+cd playground
+npx create-rsbuild@latest test-cli-rspack --template react-ts
+cd test-cli-rspack
+npm install
+```
+
+All the following tests assume you are running the commands from inside `playground/test-cli-rspack`.
+
+---
+
+## Core Scenarios
+
+### Case 1: Initial Setup (The Happy Path)
+
+1. **Action:** Run `node ../../packages/cli/bin/inspecto.js init`
+2. **Expectations:**
+   - Detects `npm`, `react`, and `Rsbuild (rsbuild.config.ts)`.
+   - Detects the current IDE accurately (e.g., VS Code or Trae). If it's not VS Code, it should warn about lack of support.
+   - If `@inspecto-dev/plugin` cannot be installed (e.g., registry not ready), it logs the failure but does not crash.
+   - Backs up `rsbuild.config.ts` to `rsbuild.config.ts.bak`.
+   - Injects the `inspecto()` plugin code safely into `rsbuild.config.ts` without ruining the formatting.
+   - Creates a valid `.inspecto/settings.json`.
+   - Updates `.gitignore` with fine-grained rules (`install.lock`, `cache.json`, `*.local.json`).
+   - If an error occurred during dependency installation or AST injection, the final message should be a yellow warning `⚠ Setup completed with some manual steps required`, **not** the green success `⚡ Ready!`.
+
+### Case 2: Idempotency (Running Init Again)
+
+1. **Action:** Run `node ../../packages/cli/bin/inspecto.js init` again in the exact same directory.
+2. **Expectations:**
+   - Logs `Plugin already injected in rsbuild.config.ts (skipped)`.
+   - Logs `.inspecto/settings.json already exists (skipped)`.
+   - The `.gitignore` file is not duplicated.
+   - The `.inspecto/install.lock` remains valid and tracks the fact that the file was modified previously.
+
+### Case 3: Doctor Diagnostics
+
+1. **Action:** Run `node ../../packages/cli/bin/inspecto.js doctor`
+2. **Expectations:**
+   - Prints a clean checklist of the environment.
+   - Successfully finds `rsbuild.config.ts` with the plugin injected.
+   - Accurately reports whether the VS Code extension is installed (if applicable).
+   - Accurately reports missing npm dependencies (if the install failed in Case 1).
+
+### Case 4: Fault Tolerance Diagnostics
+
+1. **Action:**
+   - Open `.inspecto/settings.json` and purposely ruin the JSON syntax (e.g., delete a curly brace or add random text).
+   - Run `node ../../packages/cli/bin/inspecto.js doctor` again.
+2. **Expectations:**
+   - Does not crash.
+   - Safely catches the JSON parse error and logs `✘ .inspecto/settings.json has invalid JSON`.
+
+### Case 5: Precise Teardown (Rollback)
+
+1. **Action:** Fix the JSON file from Case 4, then run `node ../../packages/cli/bin/inspecto.js teardown`
+2. **Expectations:**
+   - Reads `.inspecto/install.lock`.
+   - Completely restores `rsbuild.config.ts` back to its original state using the `.bak` file, and deletes the `.bak` file.
+   - Removes `@inspecto-dev/plugin` from `package.json` `devDependencies` (if it was installed).
+   - Cleans up the `# Inspecto` block from `.gitignore`.
+   - Deletes the entire `.inspecto/` directory.
+   - Leaves no trace behind.
+
+### Case 6: Best-Effort Teardown (Missing Lock File)
+
+1. **Action:**
+   - Run `init` again to generate the files.
+   - Manually delete the `.inspecto/` folder (which contains `install.lock`).
+   - Run `node ../../packages/cli/bin/inspecto.js teardown`
+2. **Expectations:**
+   - Logs `⚠ No .inspecto/install.lock found. Running in best-effort mode.`
+   - Still manages to uninstall the npm dependency.
+   - Still manages to clean the `.gitignore` entries.
+   - Instructs the user to manually remove the AST injection since there is no backup to restore from.
+
+### Case 7: Ambiguous Config Resolution
+
+1. **Action:**
+   - Create an empty dummy file named `vite.config.ts` in the project root to simulate a mixed/conflicting configuration.
+   - Run `node ../../packages/cli/bin/inspecto.js init`
+2. **Expectations:**
+   - The CLI stops and presents an interactive prompt `? Detected multiple build tool configs:`.
+   - Allows the user to select either Rsbuild or Vite via arrow keys, or choose "Skip".
+   - If the user selects one, it attempts injection on the selected file only.
+
+### Case 8: Interactive IDE Prompt
+
+1. **Action:**
+   - Simulate opening the project in multiple IDEs by creating empty directories: `mkdir .vscode && mkdir .idea`.
+   - Open your terminal in a different IDE (e.g., Trae or Cursor).
+   - Run `node ../../packages/cli/bin/inspecto.js init`
+2. **Expectations:**
+   - Detects the current terminal IDE **and** the directory artifacts.
+   - Pauses and asks `? Detected multiple IDEs:`.
+   - Shows which ones are `(supported)` vs `(unsupported)`.
+   - Updates `settings.json` with the chosen IDE if it is supported.

package/bin/inspecto.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/bin.js'

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/bin.js

@@ -0,0 +1,83 @@
+import {
+  doctor,
+  init,
+  log,
+  teardown
+} from "./chunk-4RR7PTRN.js";
+
+// src/bin.ts
+import { parseArgs } from "util";
+var HELP = `
+  \u2726 Inspecto CLI (v1)
+
+  Supported: VS Code | React + Vue | Vite + Webpack + Rspack + esbuild + Rollup
+
+  Usage:
+    inspecto init       Set up Inspecto in your project
+    inspecto doctor     Diagnose your Inspecto installation
+    inspecto teardown   Remove Inspecto from your project
+
+  Init Options:
+    --shared            Share .inspecto/settings.json with your team via Git
+    --skip-install      Skip npm dependency installation
+    --dry-run           Preview changes without modifying files
+    --prefer <tool>     Set default AI tool (e.g. github-copilot, claude-code)
+    --no-extension      Skip VS Code extension installation
+    --packages <names>  (Monorepo) Comma-separated list of packages to inject
+
+  Examples:
+    npx inspecto init
+    npx inspecto init --shared --prefer github-copilot
+    npx inspecto init --dry-run
+    npx inspecto doctor
+    npx inspecto teardown
+`;
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  if (!command || command === "--help" || command === "-h") {
+    console.log(HELP);
+    process.exit(0);
+  }
+  try {
+    switch (command) {
+      case "init": {
+        const { values } = parseArgs({
+          args: args.slice(1),
+          options: {
+            shared: { type: "boolean", default: false },
+            "skip-install": { type: "boolean", default: false },
+            "dry-run": { type: "boolean", default: false },
+            prefer: { type: "string" },
+            "no-extension": { type: "boolean", default: false },
+            packages: { type: "string" }
+          },
+          strict: true
+        });
+        await init({
+          shared: values.shared ?? false,
+          skipInstall: values["skip-install"] ?? false,
+          dryRun: values["dry-run"] ?? false,
+          ...values.prefer && { prefer: values.prefer },
+          noExtension: values["no-extension"] ?? false,
+          ...values.packages && { packages: values.packages.split(",").map((s) => s.trim()) }
+        });
+        break;
+      }
+      case "doctor":
+        await doctor();
+        break;
+      case "teardown":
+        await teardown();
+        break;
+      default:
+        log.error(`Unknown command: ${command}`);
+        console.log(HELP);
+        process.exit(1);
+    }
+  } catch (err) {
+    log.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+main();