@inspecto-dev/cli 0.2.0-alpha.0

package/src/inject/extension.ts

@@ -0,0 +1,140 @@
+// ============================================================
+// src/inject/extension.ts — VS Code extension auto-installer
+// ============================================================
+//
+// Waterfall degradation strategy:
+//   Level 1: `code --install-extension` (code in PATH)
+//   Level 2: Find VS Code binary at known paths
+//   Level 3: Open `vscode:extension/` URI scheme
+//   Level 4: Print manual installation instructions
+// ============================================================
+
+import path from 'node:path'
+import { which, run, shell } from '../utils/exec.js'
+import { exists } from '../utils/fs.js'
+import { log } from '../utils/logger.js'
+import type { Mutation } from '../types.js'
+
+const EXTENSION_ID = 'inspecto.inspecto'
+
+/** Known VS Code binary locations by platform */
+const VSCODE_PATHS: Record<string, string[]> = {
+  darwin: [
+    '/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code',
+    '/Applications/Visual Studio Code - Insiders.app/Contents/Resources/app/bin/code-insiders',
+    `${process.env.HOME}/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code`,
+  ],
+  linux: ['/usr/bin/code', '/usr/share/code/bin/code', '/snap/bin/code', '/usr/bin/code-insiders'],
+  win32: [
+    `${process.env.LOCALAPPDATA}\\Programs\\Microsoft VS Code\\bin\\code.cmd`,
+    `${process.env.LOCALAPPDATA}\\Programs\\Microsoft VS Code Insiders\\bin\\code-insiders.cmd`,
+    `${process.env.PROGRAMFILES}\\Microsoft VS Code\\bin\\code.cmd`,
+  ],
+}
+
+/** Try to find the VS Code binary at known filesystem paths */
+async function findVSCodeBinary(): Promise<string | null> {
+  const platform = process.platform
+  const candidates = VSCODE_PATHS[platform] || []
+
+  for (const candidate of candidates) {
+    if (await exists(candidate)) {
+      return candidate
+    }
+  }
+
+  // Also check for code-insiders in PATH
+  if (await which('code-insiders')) {
+    return 'code-insiders'
+  }
+
+  return null
+}
+
+/** Try to open a URI using the system default handler */
+async function tryOpenURI(uri: string): Promise<boolean> {
+  try {
+    const platform = process.platform
+    const openCmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start' : 'xdg-open'
+
+    await shell(`${openCmd} "${uri}"`)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Attempt to install the VS Code extension using waterfall degradation.
+ */
+export async function installExtension(dryRun: boolean): Promise<Mutation | null> {
+  if (dryRun) {
+    log.dryRun('Would attempt to install VS Code extension')
+    return null
+  }
+
+  // Level 1: Direct `code` command
+  if (await which('code')) {
+    try {
+      await run('code', ['--install-extension', EXTENSION_ID])
+      log.success('VS Code extension installed via CLI')
+      return { type: 'extension_installed', id: EXTENSION_ID }
+    } catch {
+      // Fall through to next level
+    }
+  }
+
+  // Level 2: Find VS Code binary at known paths
+  const codePath = await findVSCodeBinary()
+  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')
+      return { type: 'extension_installed', id: EXTENSION_ID }
+    } catch {
+      // Fall through to next level
+    }
+  }
+
+  // Level 3: URI scheme
+  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.')
+    return { type: 'extension_installed', id: EXTENSION_ID, manual_action_required: true }
+  }
+
+  // Level 4: Manual fallback
+  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
+}
+
+/**
+ * Check if the extension is already installed.
+ */
+export async function isExtensionInstalled(): Promise<boolean> {
+  try {
+    // Try `code --list-extensions` first
+    if (await which('code')) {
+      const { stdout } = await run('code', ['--list-extensions'])
+      return stdout.toLowerCase().includes(EXTENSION_ID)
+    }
+
+    // Try known binary path
+    const codePath = await findVSCodeBinary()
+    if (codePath) {
+      const { stdout } = await run(codePath, ['--list-extensions'])
+      return stdout.toLowerCase().includes(EXTENSION_ID)
+    }
+
+    return false
+  } catch {
+    return false
+  }
+}

package/src/inject/gitignore.ts

@@ -0,0 +1,76 @@
+// ============================================================
+// src/inject/gitignore.ts — .gitignore management
+// ============================================================
+import path from 'node:path'
+import { readFile, writeFile } from '../utils/fs.js'
+import { log } from '../utils/logger.js'
+
+/** Rules for default mode: fine-grained rules only */
+const DEFAULT_RULES = ['.inspecto/install.lock', '.inspecto/cache.json', '.inspecto/*.local.json']
+
+/** Rules for shared mode: same as default in current design to allow settings.json */
+const SHARED_RULES = ['.inspecto/install.lock', '.inspecto/cache.json', '.inspecto/*.local.json']
+
+/**
+ * Update .gitignore based on the init mode.
+ *
+ * Handles mode switching: if switching from default → shared,
+ * replaces the broad `.inspecto/` rule with fine-grained rules.
+ */
+export async function updateGitignore(
+  root: string,
+  shared: boolean,
+  dryRun: boolean,
+): Promise<void> {
+  const gitignorePath = path.join(root, '.gitignore')
+  let content = (await readFile(gitignorePath)) ?? ''
+
+  const desiredRules = shared ? SHARED_RULES : DEFAULT_RULES
+  const hasGlobalRule = content.match(/^\.inspecto\/\s*$/m) !== null
+
+  // Mode switch: If the user previously had the broad `.inspecto/` rule, replace it
+  if (hasGlobalRule) {
+    content = content.replace(/^\.inspecto\/\s*$/gm, SHARED_RULES.join('\n'))
+    if (!dryRun) {
+      await writeFile(gitignorePath, content)
+    }
+    log.success('Updated .gitignore: .inspecto/settings.json is now trackable')
+    return
+  }
+
+  // Check if rules already exist
+  const missingRules = desiredRules.filter(rule => !content.includes(rule))
+  if (missingRules.length === 0) {
+    return // Already configured
+  }
+
+  // Append rules
+  const section = '\n# Inspecto\n' + missingRules.join('\n') + '\n'
+  content = content.trimEnd() + '\n' + section
+
+  if (dryRun) {
+    log.dryRun(`Would update .gitignore with: ${missingRules.join(', ')}`)
+  } else {
+    await writeFile(gitignorePath, content)
+    log.success('Updated .gitignore')
+  }
+}
+
+/**
+ * Remove all Inspecto-related entries from .gitignore.
+ */
+export async function cleanGitignore(root: string): Promise<void> {
+  const gitignorePath = path.join(root, '.gitignore')
+  const content = await readFile(gitignorePath)
+  if (!content) return
+
+  const cleaned = content
+    .replace(/^# Inspecto\s*$/m, '')
+    .replace(/^\.inspecto\/?\s*$/gm, '')
+    .replace(/^\.inspecto\/install\.lock\s*$/gm, '')
+    .replace(/^\.inspecto\/cache\.json\s*$/gm, '')
+    .replace(/^\.inspecto\/\*\.local\.json\s*$/gm, '')
+    .replace(/\n{3,}/g, '\n\n') // Collapse excess blank lines
+
+  await writeFile(gitignorePath, cleaned)
+}

package/src/types.ts

@@ -0,0 +1,48 @@
+// ============================================================
+// src/types.ts — Shared type definitions
+// ============================================================
+
+/** Package manager detection result */
+export type PackageManager = 'bun' | 'pnpm' | 'yarn' | 'npm'
+
+/** Supported build tools (v1) */
+export type BuildTool = 'vite' | 'webpack' | 'rspack' | 'rsbuild' | 'esbuild' | 'rollup'
+
+/** Detected build tool with its config path */
+export interface BuildToolDetection {
+  tool: BuildTool
+  configPath: string
+  /** Human-readable label like "Vite (vite.config.ts)" */
+  label: string
+  /** Whether this is a legacy rspack version (< 0.4.0) */
+  isLegacyRspack?: boolean
+}
+
+/** Options passed to `inspecto init` */
+export interface InitOptions {
+  shared: boolean
+  skipInstall: boolean
+  dryRun: boolean
+  prefer?: string
+  noExtension: boolean
+  packages?: string[]
+}
+
+/** A single mutation recorded in install.lock */
+export interface Mutation {
+  type: 'file_modified' | 'file_created' | 'dependency_added' | 'extension_installed'
+  path?: string
+  backup?: string
+  name?: string
+  id?: string
+  dev?: boolean
+  description?: string
+  manual_action_required?: boolean
+}
+
+/** Structure of .inspecto/install.lock */
+export interface InstallLock {
+  version: string
+  created_at: string
+  mutations: Mutation[]
+}

package/src/utils/exec.ts

@@ -0,0 +1,44 @@
+// ============================================================
+// src/utils/exec.ts — Shell execution helpers
+// ============================================================
+import { execFile, exec as execCb } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+const execAsync = promisify(execCb)
+
+export interface ExecResult {
+  stdout: string
+  stderr: string
+}
+
+/** Run a command and return stdout/stderr. Throws on non-zero exit. */
+export async function run(command: string, args: string[], cwd?: string): Promise<ExecResult> {
+  const result = await execFileAsync(command, args, {
+    cwd,
+    timeout: 60_000,
+    env: { ...process.env },
+  })
+  return { stdout: result.stdout ?? '', stderr: result.stderr ?? '' }
+}
+
+/** Run a shell command string. Throws on non-zero exit. */
+export async function shell(command: string, cwd?: string): Promise<ExecResult> {
+  const result = await execAsync(command, {
+    cwd,
+    timeout: 60_000,
+    env: { ...process.env },
+  })
+  return { stdout: result.stdout ?? '', stderr: result.stderr ?? '' }
+}
+
+/** Check if a binary exists in PATH */
+export async function which(bin: string): Promise<boolean> {
+  try {
+    const cmd = process.platform === 'win32' ? 'where' : 'which'
+    await run(cmd, [bin])
+    return true
+  } catch {
+    return false
+  }
+}

package/src/utils/fs.ts

@@ -0,0 +1,69 @@
+// ============================================================
+// src/utils/fs.ts — File system helpers
+// ============================================================
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+/** Check if a file or directory exists */
+export async function exists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Read file as UTF-8 text, return null if not found */
+export async function readFile(filePath: string): Promise<string | null> {
+  try {
+    return await fs.readFile(filePath, 'utf-8')
+  } catch {
+    return null
+  }
+}
+
+/** Write file with auto-created parent directories */
+export async function writeFile(filePath: string, content: string): Promise<void> {
+  await fs.mkdir(path.dirname(filePath), { recursive: true })
+  await fs.writeFile(filePath, content, 'utf-8')
+}
+
+/** Copy file (for backup) */
+export async function copyFile(src: string, dest: string): Promise<void> {
+  await fs.copyFile(src, dest)
+}
+
+/** Delete file, no error if missing */
+export async function removeFile(filePath: string): Promise<void> {
+  try {
+    await fs.unlink(filePath)
+  } catch {
+    // ignore
+  }
+}
+
+/** Delete directory recursively, no error if missing */
+export async function removeDir(dirPath: string): Promise<void> {
+  try {
+    await fs.rm(dirPath, { recursive: true, force: true })
+  } catch {
+    // ignore
+  }
+}
+
+/** Read and parse JSON file */
+export async function readJSON<T = unknown>(filePath: string): Promise<T | null> {
+  const text = await readFile(filePath)
+  if (!text) return null
+  try {
+    return JSON.parse(text) as T
+  } catch {
+    return null
+  }
+}
+
+/** Write JSON file with 2-space indent */
+export async function writeJSON(filePath: string, data: unknown): Promise<void> {
+  await writeFile(filePath, JSON.stringify(data, null, 2) + '\n')
+}

package/src/utils/logger.ts

@@ -0,0 +1,64 @@
+// ============================================================
+// src/utils/logger.ts — Colored terminal output
+// ============================================================
+import pc from 'picocolors'
+
+export const log = {
+  /** Section header */
+  header(text: string) {
+    console.log()
+    console.log(`  ${pc.bold(pc.cyan('✦'))} ${pc.bold(text)}`)
+    console.log()
+  },
+
+  /** Info item (used for actionable but not fully successful states) */
+  info(text: string) {
+    console.log(`  ${pc.blue('ℹ')} ${text}`)
+  },
+  success(text: string) {
+    console.log(`  ${pc.green('✔')} ${text}`)
+  },
+
+  /** Warning item */
+  warn(text: string) {
+    console.log(`  ${pc.yellow('⚠')} ${text}`)
+  },
+
+  /** Error item */
+  error(text: string) {
+    console.log(`  ${pc.red('✘')} ${text}`)
+  },
+
+  /** Indented hint line */
+  hint(text: string) {
+    console.log(`    ${pc.dim('→')} ${text}`)
+  },
+
+  /** Blank line */
+  blank() {
+    console.log()
+  },
+
+  /** Final ready message */
+  ready(text: string) {
+    console.log()
+    console.log(`  ${pc.bold(pc.green('⚡'))} ${pc.bold(text)}`)
+    console.log()
+  },
+
+  /** Code block for manual instructions */
+  codeBlock(lines: string[]) {
+    console.log()
+    console.log(`  ${pc.dim('┌─────────────────────────────────────────────────┐')}`)
+    for (const line of lines) {
+      console.log(`  ${pc.dim('│')} ${line.padEnd(48)}${pc.dim('│')}`)
+    }
+    console.log(`  ${pc.dim('└─────────────────────────────────────────────────┘')}`)
+    console.log()
+  },
+
+  /** Dry-run prefix */
+  dryRun(text: string) {
+    console.log(`  ${pc.blue('[dry-run]')} ${text}`)
+  },
+}

package/tests/framework.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect, vi } from 'vitest'
+import { detectFrameworks } from '../src/detect/framework.js'
+import * as fsUtils from '../src/utils/fs.js'
+
+vi.mock('../src/utils/fs.js', () => ({
+  readJSON: vi.fn(),
+}))
+
+describe('detectFrameworks', () => {
+  it('detects React based on dependencies', async () => {
+    vi.mocked(fsUtils.readJSON).mockResolvedValue({
+      dependencies: {
+        react: '^18.0.0',
+      },
+    })
+
+    const result = await detectFrameworks('/mock/root')
+    expect(result.supported).toContain('react')
+    expect(result.unsupported).toHaveLength(0)
+  })
+
+  it('detects Vue based on dependencies', async () => {
+    vi.mocked(fsUtils.readJSON).mockResolvedValue({
+      devDependencies: {
+        vue: '^3.0.0',
+      },
+    })
+
+    const result = await detectFrameworks('/mock/root')
+    expect(result.supported).toContain('vue')
+    expect(result.unsupported).toHaveLength(0)
+  })
+
+  it('detects Svelte as unsupported framework', async () => {
+    vi.mocked(fsUtils.readJSON).mockResolvedValue({
+      devDependencies: {
+        svelte: '^4.0.0',
+      },
+    })
+
+    const result = await detectFrameworks('/mock/root')
+    expect(result.supported).toHaveLength(0)
+    expect(result.unsupported).toContainEqual({ name: 'Svelte', dep: 'svelte' })
+  })
+
+  it('returns empty if no framework is matched', async () => {
+    vi.mocked(fsUtils.readJSON).mockResolvedValue({
+      dependencies: {
+        lodash: '^4.0.0',
+      },
+    })
+
+    const result = await detectFrameworks('/mock/root')
+    expect(result.supported).toHaveLength(0)
+    expect(result.unsupported).toHaveLength(0)
+  })
+
+  it('returns empty if package.json does not exist', async () => {
+    vi.mocked(fsUtils.readJSON).mockResolvedValue(null)
+
+    const result = await detectFrameworks('/mock/root')
+    expect(result.supported).toHaveLength(0)
+    expect(result.unsupported).toHaveLength(0)
+  })
+})

package/tests/ide.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { detectIDE } from '../src/detect/ide.js'
+import * as fsUtils from '../src/utils/fs.js'
+
+vi.mock('../src/utils/fs.js', () => ({
+  exists: vi.fn(),
+}))
+
+describe('detectIDE', () => {
+  const originalEnv = process.env
+
+  beforeEach(() => {
+    vi.resetAllMocks()
+    process.env = { ...originalEnv } // Make a copy
+  })
+
+  afterEach(() => {
+    process.env = originalEnv
+  })
+
+  it('detects Trae from environment variables', async () => {
+    process.env.TRAE_APP_DIR = '/Applications/Trae.app'
+    vi.mocked(fsUtils.exists).mockResolvedValue(false)
+
+    const result = await detectIDE('/mock/root')
+    expect(result.detected).toEqual([{ ide: 'Trae', supported: false }])
+  })
+
+  it('detects Cursor from environment variables', async () => {
+    process.env.CURSOR_CHANNEL = 'stable'
+    vi.mocked(fsUtils.exists).mockResolvedValue(false)
+
+    const result = await detectIDE('/mock/root')
+    expect(result.detected).toEqual([{ ide: 'Cursor', supported: false }])
+  })
+
+  it('detects VS Code from environment variables without false positives', async () => {
+    process.env.TERM_PROGRAM = 'vscode'
+    // Ensure it's not Trae
+    delete process.env.TRAE_APP_DIR
+    delete process.env.CURSOR_CHANNEL
+    delete process.env.__CFBundleIdentifier
+    delete process.env.COCO_IDE_PLUGIN_TYPE
+    process.env.npm_config_user_agent = 'npm'
+
+    vi.mocked(fsUtils.exists).mockResolvedValue(false)
+
+    const result = await detectIDE('/mock/root')
+    expect(result.detected).toEqual([{ ide: 'vscode', supported: true }])
+  })
+
+  it('detects VS Code from directory when environment is clean', async () => {
+    // Clear all related env vars
+    delete process.env.TERM_PROGRAM
+    delete process.env.TRAE_APP_DIR
+    delete process.env.CURSOR_CHANNEL
+    delete process.env.__CFBundleIdentifier
+    delete process.env.COCO_IDE_PLUGIN_TYPE
+    delete process.env.npm_config_user_agent
+
+    vi.mocked(fsUtils.exists).mockImplementation(async path => {
+      return path.endsWith('.vscode')
+    })
+
+    const result = await detectIDE('/mock/root')
+    expect(result.detected).toEqual([{ ide: 'vscode', supported: true }])
+  })
+
+  it('detects JetBrains from directory', async () => {
+    delete process.env.TERM_PROGRAM
+    delete process.env.TRAE_APP_DIR
+    delete process.env.CURSOR_CHANNEL
+    delete process.env.__CFBundleIdentifier
+    delete process.env.COCO_IDE_PLUGIN_TYPE
+
+    vi.mocked(fsUtils.exists).mockImplementation(async path => {
+      return path.endsWith('.idea')
+    })
+
+    const result = await detectIDE('/mock/root')
+    expect(result.detected).toEqual([{ ide: 'JetBrains IDE', supported: false }])
+  })
+
+  it('favors Trae if both VS Code TERM_PROGRAM and Trae env are present', async () => {
+    process.env.TERM_PROGRAM = 'vscode'
+    process.env.TRAE_APP_DIR = '/Applications/Trae.app'
+
+    vi.mocked(fsUtils.exists).mockResolvedValue(false)
+
+    const result = await detectIDE('/mock/root')
+    // VS Code shouldn't be added since it shares TERM_PROGRAM with Trae
+    expect(result.detected).toEqual([{ ide: 'Trae', supported: false }])
+  })
+})

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "strict": true
+  },
+  "include": ["src/**/*", "bin/**/*"]
+}

package/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts', 'src/bin.ts'],
+  format: ['esm'],
+  target: 'node18',
+  dts: true,
+  clean: true,
+  minify: false,
+})