@inspecto-dev/cli 0.3.0-alpha.1 → 0.3.1

package/.turbo/turbo-build.log

@@ -1,19 +1,20 @@
-
-> @inspecto-dev/cli@0.3.0-alpha.1 build /Users/tangjie/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/tangjie/hugo.felix/inspecto/packages/cli/tsup.config.ts
-CLI Target: node18
-CLI Cleaning output folder
-ESM Build start
-ESM dist/index.js          319.00 B
-ESM dist/bin.js            20.37 KB
-ESM dist/chunk-FZS2TLXQ.js 103.35 KB
-ESM ⚡️ Build success in 61ms
-DTS Build start
-DTS ⚡️ Build success in 5204ms
-DTS dist/bin.d.ts   185.00 B
-DTS dist/index.d.ts 7.79 KB
+
+
+> @inspecto-dev/cli@0.3.1 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/bin.js            20.39 KB
+ESM dist/chunk-PSYZB5GI.js 103.68 KB
+ESM dist/index.js          319.00 B
+ESM ⚡️ Build success in 162ms
+DTS Build start
+DTS ⚡️ Build success in 1954ms
+DTS dist/bin.d.ts   185.00 B
+DTS dist/index.d.ts 7.79 KB

package/.turbo/turbo-test.log

@@ -0,0 +1,92 @@
+
+> @inspecto-dev/cli@0.3.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/instructions.test.ts  (2 tests) 5ms
+ ✓ tests/ide.test.ts  (6 tests) 3ms
+ ✓ tests/detect.test.ts  (1 test) 3ms
+ ✓ tests/doctor.test.ts  (4 tests) 6ms
+ ✓ tests/logger.test.ts  (5 tests) 9ms
+ ✓ tests/onboard.test.ts  (5 tests) 5ms
+- Installing devDependencies via: pnpm add -D @inspecto-dev/plugin @inspecto-dev/core
+stdout | tests/apply.test.ts > apply onboarding flow > applies the supported setup path and returns structured mutations and post-install state
+  ✔ Installed @inspecto-dev/plugin and @inspecto-dev/core as devDependencies
+  ✔ Created .inspecto/settings.local.json
+  ✔ Created .inspecto/prompts.local.json
+
+ ✓ tests/apply.test.ts  (9 tests) 16ms
+✔ Dependencies installed successfully
+- Installing devDependencies via: pnpm add -D @inspecto-dev/plugin @inspecto-dev/core
+✔ Dependencies installed successfully
+- Installing devDependencies via: pnpm add -D @inspecto-dev/plugin @inspecto-dev/core
+✔ Dependencies installed successfully
+ ✓ tests/framework.test.ts  (5 tests) 3ms
+ ✓ tests/build-tool.test.ts  (2 tests) 59ms
+ ✓ tests/workspace-build-tool.test.ts  (1 test) 73ms
+ ✓ tests/init.test.ts  (5 tests) 9ms
+stdout | tests/init.test.ts > init in monorepo roots > routes installation and config generation into the selected app instead of the monorepo root
+
+  ✦ Inspecto Setup
+
+  ⚠ Monorepo root detected with multiple candidate apps.
+  ℹ Continuing initialization in apps/web
+  ✔ Detected package manager: pnpm
+  ✔ Detected framework: react
+  ✔ Detected: Vite (apps/web/vite.config.ts)
+  ✔ Selected IDE: vscode
+  ⚠ No supported AI tools detected
+    → Inspecto works best with Claude Code, Trae CLI, or GitHub Copilot
+
+
+  ⚡ Ready! Inspecto is set up.
+
+  ℹ Next:
+    → 1. Start or restart your dev server.
+    → 2. Open your app in the browser.
+    → 3. Hold Alt + Click any element to inspect.
+
+stdout | tests/init.test.ts > init in monorepo roots > prints detailed Next.js manual instructions when Next.js is detected
+
+  ✦ Inspecto Setup
+
+  ✔ Detected package manager: pnpm
+  ✔ Detected framework: react
+  ⚠ Detected Next.js — automatic plugin injection is not supported in current version
+    → You can still manually configure it by modifying your configuration file
+  ✔ Selected IDE: vscode
+  ⚠ No supported AI tools detected
+    → Inspecto works best with Claude Code, Trae CLI, or GitHub Copilot
+
+  ⚠ Dry run complete. No files were modified.
+
+stdout | tests/init.test.ts > init in monorepo roots > preserves detected preferred mode for an explicit provider override
+
+  ✦ Inspecto Setup
+
+  ✔ Detected package manager: pnpm
+  ✔ Detected framework: react
+  ✔ Detected: Vite (vite.config.ts)
+  ✔ Selected IDE: vscode
+
+
+  ⚡ Ready! Inspecto is set up.
+
+  ℹ Next:
+    → 1. Start or restart your dev server.
+    → 2. Open your app in the browser.
+    → 3. Hold Alt + Click any element to inspect.
+
+ ✓ tests/ast-injector.test.ts  (1 test) 3ms
+ ✓ tests/integration-install.test.ts  (12 tests) 824ms
+ ✓ tests/plan.test.ts  (15 tests) 718ms
+ ✓ tests/install-wrapper.test.ts  (1 test) 1276ms
+ ✓ tests/runner-script.test.ts  (3 tests) 2378ms
+
+ Test Files  16 passed (16)
+      Tests  77 passed (77)
+   Start at  12:27:25
+   Duration  3.02s (transform 2.20s, setup 0ms, collect 4.55s, tests 5.39s, environment 3ms, prepare 2.95s)
+

package/CHANGELOG.md

@@ -1,10 +1,18 @@
 # @inspecto-dev/cli
 
-## 0.3.0-alpha.1
+## 0.3.1
+
+### Patch Changes
+
+- fix: polish onboarding and architecture visualization
+- Updated dependencies
+  - @inspecto-dev/types@0.3.1
+
+## 0.3.0
 
 ### Minor Changes
 
-- Prepare the first `0.3.0-alpha.1` release line for Inspecto's browser-first workflow.
+- First stable release for Inspecto's browser-first workflow.
   - unify onboarding around assistant-first setup and the single-entry `inspecto onboard --json` contract
   - stabilize the browser UX across `Inspect`, `Annotate`, and `Alt + Click` quick jump
   - tighten prompt and settings schema boundaries and keep evidence toggles built-in
@@ -14,7 +22,7 @@
 ### Patch Changes
 
 - Updated dependencies
-  - @inspecto-dev/types@0.3.0-alpha.1
+  - @inspecto-dev/types@0.3.0
 
 ## 0.2.0-alpha.6
 

package/dist/bin.js

@@ -10,7 +10,7 @@ import {
   reportCommandError,
   teardown,
   writeFile
-} from "./chunk-FZS2TLXQ.js";
+} from "./chunk-PSYZB5GI.js";
 
 // src/bin.ts
 import { cac } from "cac";
@@ -352,7 +352,9 @@ async function downloadAsset(source) {
     response = await fetch(source);
   } catch (error) {
     const reason = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to download ${source}: ${reason}`);
+    throw new Error(`Failed to download ${source}: ${reason}`, {
+      cause: error
+    });
   }
   if (!response.ok) {
     throw new Error(`Failed to download ${source}: ${response.status} ${response.statusText}`);

package/dist/{chunk-FZS2TLXQ.js → chunk-PSYZB5GI.js}

@@ -2373,7 +2373,9 @@ function matchesAnyPackage(detection, packages) {
 }
 async function detectFrameworkSupportByPackage(repoRoot, buildTools) {
   const packagePaths = Array.from(
-    new Set(buildTools.map((buildTool) => buildTool.packagePath).filter((value) => !!value))
+    new Set(
+      buildTools.map((buildTool) => buildTool.packagePath).filter((value) => !!value)
+    )
   );
   const supportByPackage = {};
   await Promise.all(
@@ -2800,7 +2802,8 @@ function buildConfirmation(plan2, summary, session, options) {
   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 (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");
   }
@@ -2837,7 +2840,9 @@ function buildPreApplyResult(status, session) {
 function buildExecutionResult(session, applyResult) {
   return {
     changedFiles: Array.from(
-      new Set(applyResult.mutations.map((item) => item.path).filter((value) => !!value))
+      new Set(
+        applyResult.mutations.map((item) => item.path).filter((value) => !!value)
+      )
     ),
     installedDependencies: applyResult.mutations.map((item) => item.name).filter((value) => !!value),
     selectedProviderDefault: session.providerDefault,
@@ -2999,6 +3004,10 @@ function printOnboardResult(result) {
   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();

package/dist/index.js

@@ -9,7 +9,7 @@ import {
   reportCommandError,
   teardown,
   writeCommandOutput
-} from "./chunk-FZS2TLXQ.js";
+} from "./chunk-PSYZB5GI.js";
 export {
   apply,
   collectDoctorResult,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inspecto-dev/cli",
-  "version": "0.3.0-alpha.1",
+  "version": "0.3.1",
   "description": "CLI tools for Inspecto onboarding and lifecycle management",
   "keywords": [
     "inspecto",
@@ -20,7 +20,7 @@
     "ora": "^9.3.0",
     "picocolors": "^1.0.0",
     "prompts": "^2.4.2",
-    "@inspecto-dev/types": "0.3.0-alpha.1"
+    "@inspecto-dev/types": "0.3.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/commands/init.ts

@@ -368,7 +368,11 @@ async function detectFrameworkSupportByPackage(
   buildTools: BuildToolDetection[],
 ): Promise<Record<string, string[]>> {
   const packagePaths = Array.from(
-    new Set(buildTools.map(buildTool => buildTool.packagePath).filter((value): value is string => !!value)),
+    new Set(
+      buildTools
+        .map(buildTool => buildTool.packagePath)
+        .filter((value): value is string => !!value),
+    ),
   )
   const supportByPackage: Record<string, string[]> = {}
 

package/src/commands/integration-install.ts

@@ -441,7 +441,9 @@ async function downloadAsset(source: string): Promise<string> {
     response = await fetch(source)
   } catch (error) {
     const reason = error instanceof Error ? error.message : String(error)
-    throw new Error(`Failed to download ${source}: ${reason}`)
+    throw new Error(`Failed to download ${source}: ${reason}`, {
+      cause: error,
+    })
   }
 
   if (!response.ok) {

package/src/commands/onboard.ts

@@ -1,4 +1,8 @@
-import { resolveOnboardingSession, applyResolvedOnboardingSession, buildDeferredOnboardResult } from '../onboarding/session.js'
+import {
+  resolveOnboardingSession,
+  applyResolvedOnboardingSession,
+  buildDeferredOnboardResult,
+} from '../onboarding/session.js'
 import { log } from '../utils/logger.js'
 import { writeCommandOutput } from '../utils/output.js'
 import type { OnboardCommandResult } from '../types.js'
@@ -27,6 +31,18 @@ function printOnboardResult(result: OnboardCommandResult): void {
   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)
+  }
 }
 
 export async function onboard(options: OnboardCommandOptions = {}): Promise<OnboardCommandResult> {

package/src/onboarding/session.ts

@@ -197,7 +197,8 @@ function buildConfirmation(
   const reasons: string[] = []
   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 (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')
   }
@@ -219,7 +220,9 @@ function buildPreApplyResult(
   session: ResolvedOnboardingSession,
 ): OnboardCommandResult {
   const diagnostics: OnboardingDiagnostics | undefined =
-    session.summary.risks.length > 0 || session.summary.manualFollowUp.length > 0 || session.plan.blockers.length > 0
+    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),
@@ -248,7 +251,9 @@ function buildExecutionResult(
 ): OnboardingExecutionResult {
   return {
     changedFiles: Array.from(
-      new Set(applyResult.mutations.map(item => item.path).filter((value): value is string => !!value)),
+      new Set(
+        applyResult.mutations.map(item => item.path).filter((value): value is string => !!value),
+      ),
     ),
     installedDependencies: applyResult.mutations
       .map(item => item.name)
@@ -276,7 +281,11 @@ function buildExecutionDiagnostics(
     warnings.push('IDE extension installation still needs manual completion.')
   }
 
-  if (warnings.length === 0 && errors.length === 0 && applyResult.postInstall.nextSteps.length === 0) {
+  if (
+    warnings.length === 0 &&
+    errors.length === 0 &&
+    applyResult.postInstall.nextSteps.length === 0
+  ) {
     return undefined
   }
 

package/tests/apply.test.ts

@@ -121,7 +121,12 @@ describe('apply onboarding flow', () => {
       'pnpm add -D @inspecto-dev/plugin @inspecto-dev/core',
       '/repo',
     )
-    expect(astInjectorUtils.injectPlugin).toHaveBeenCalledWith('/repo', supportedBuild, false, false)
+    expect(astInjectorUtils.injectPlugin).toHaveBeenCalledWith(
+      '/repo',
+      supportedBuild,
+      false,
+      false,
+    )
     expect(fsUtils.writeJSON).toHaveBeenCalledWith('/repo/.inspecto/settings.local.json', {
       ide: 'vscode',
       'provider.default': 'codex.extension',

package/tests/install-wrapper.test.ts

@@ -54,10 +54,7 @@ describe('assistant integration bootstrap wrapper', () => {
     )
     await fs.chmod(path.join(fakeBin, 'curl'), 0o755)
 
-    const scriptPath = path.resolve(
-      __dirname,
-      '../../../assistant-integrations/scripts/install.sh',
-    )
+    const scriptPath = path.resolve(__dirname, '../../../assistant-integrations/scripts/install.sh')
 
     await execFileAsync('bash', [scriptPath, 'copilot', '--force'], {
       cwd: tempRoot,

package/tests/onboard.test.ts

@@ -255,4 +255,102 @@ describe('onboard command', () => {
     expect(applyResolvedOnboardingSession).not.toHaveBeenCalled()
     expect(result.ideExtension?.required).toBe(true)
   })
+
+  it('prints verification guidance in text mode after successful onboarding', async () => {
+    const session: ResolvedOnboardingSession = {
+      status: 'success',
+      target: {
+        status: 'resolved',
+        selected: {
+          packagePath: '',
+          configPath: 'vite.config.ts',
+          buildTool: 'vite',
+          frameworks: ['react'],
+          automaticInjection: true,
+        },
+        candidates: [
+          {
+            packagePath: '',
+            configPath: 'vite.config.ts',
+            buildTool: 'vite',
+            frameworks: ['react'],
+            automaticInjection: true,
+          },
+        ],
+        reason: 'Only one supported target was detected.',
+      },
+      summary: {
+        headline: 'Inspecto is ready to onboard /repo.',
+        changes: ['Install dependencies.'],
+        risks: [],
+        manualFollowUp: [],
+      },
+      confirmation: { required: false },
+      verification: {
+        available: true,
+        devCommand: 'pnpm dev',
+        message: 'Start the local dev server with `pnpm dev` to verify Inspecto in the browser.',
+      },
+      context: {
+        root: '/repo',
+        packageManager: 'pnpm',
+        buildTools: { supported: [], unsupported: [] },
+        frameworks: { supported: ['react'], unsupported: [] },
+        ides: [{ ide: 'vscode', supported: true }],
+        providers: [{ id: 'codex', label: 'Codex CLI', supported: true, preferredMode: 'cli' }],
+      },
+      plan: {
+        status: 'ok',
+        warnings: [],
+        blockers: [],
+        strategy: 'supported',
+        actions: [],
+        defaults: {
+          provider: 'codex',
+          ide: 'vscode',
+          shared: false,
+          extension: true,
+        },
+      },
+      projectRoot: '/repo',
+      selectedIDE: { ide: 'vscode', supported: true },
+      providerDefault: 'codex.cli',
+    }
+
+    const applied: OnboardCommandResult = {
+      status: 'success',
+      target: session.target,
+      summary: session.summary,
+      confirmation: session.confirmation,
+      ideExtension: {
+        required: true,
+        installed: true,
+        manualRequired: false,
+        installCommand: 'code --install-extension inspecto.inspecto',
+        marketplaceUrl: 'https://marketplace.visualstudio.com/items?itemName=inspecto.inspecto',
+        openVsxUrl: 'https://open-vsx.org/extension/inspecto/inspecto',
+      },
+      verification: session.verification,
+      result: {
+        changedFiles: ['vite.config.ts'],
+        installedDependencies: ['@inspecto-dev/plugin', '@inspecto-dev/core'],
+        selectedProviderDefault: 'codex.cli',
+        selectedIDE: 'vscode',
+        mutations: [],
+      },
+    }
+
+    vi.mocked(resolveOnboardingSession).mockResolvedValue(session)
+    vi.mocked(applyResolvedOnboardingSession).mockResolvedValue(applied)
+
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const result = await onboard({ json: false })
+
+    expect(result.status).toBe('success')
+    expect(
+      consoleSpy.mock.calls.some(call =>
+        String(call[0]).includes('Start the local dev server with `pnpm dev`'),
+      ),
+    ).toBe(true)
+  })
 })

package/tests/runner-script.test.ts

@@ -0,0 +1,72 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { afterEach, describe, expect, it } from 'vitest'
+
+const TEMP_DIRS: string[] = []
+
+async function makeTempDir(): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'inspecto-runner-test-'))
+  TEMP_DIRS.push(dir)
+  return dir
+}
+
+async function writeExecutable(filePath: string, content: string): Promise<void> {
+  await fs.mkdir(path.dirname(filePath), { recursive: true })
+  await fs.writeFile(filePath, content, 'utf8')
+  await fs.chmod(filePath, 0o755)
+}
+
+function runRunner(scriptPath: string, cwd: string, pathEnv: string): string {
+  const result = spawnSync(scriptPath, ['onboard', '--json'], {
+    cwd,
+    env: {
+      ...process.env,
+      PATH: pathEnv,
+    },
+    encoding: 'utf8',
+  })
+
+  expect(result.status).toBe(0)
+  return (result.stdout + result.stderr).trim()
+}
+
+describe('skill runner scripts', () => {
+  afterEach(async () => {
+    await Promise.all(TEMP_DIRS.splice(0).map(dir => fs.rm(dir, { recursive: true, force: true })))
+  })
+
+  it.each([
+    'skills/inspecto-onboarding-codex/scripts/run-inspecto.sh',
+    'skills/inspecto-onboarding-claude-code/scripts/run-inspecto.sh',
+    'skills/inspecto-onboarding-core/scripts/run-inspecto.sh',
+  ])(
+    'prefers an installed inspecto executable before package-manager download paths: %s',
+    async scriptRelativePath => {
+      const workspaceRoot = path.resolve(__dirname, '../../..')
+      const scriptPath = path.join(workspaceRoot, scriptRelativePath)
+      const tempDir = await makeTempDir()
+      const fakeBin = path.join(tempDir, 'bin')
+
+      await writeExecutable(
+        path.join(fakeBin, 'inspecto'),
+        `#!/usr/bin/env bash
+echo "installed-inspecto:$*"
+`,
+      )
+
+      await writeExecutable(
+        path.join(fakeBin, 'pnpm'),
+        `#!/usr/bin/env bash
+echo "pnpm-should-not-run:$*" >&2
+exit 99
+`,
+      )
+
+      const output = runRunner(scriptPath, tempDir, `${fakeBin}:${process.env.PATH ?? ''}`)
+      expect(output).toContain('installed-inspecto:onboard --json')
+      expect(output).not.toContain('pnpm-should-not-run')
+    },
+  )
+})