@inspecto-dev/cli 0.3.7 → 0.3.9

package/src/commands/mcp.ts

@@ -0,0 +1,386 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { INSPECTO_API_PATHS } from '@inspecto-dev/types'
+import { z } from 'zod'
+
+const DEFAULT_MCP_SERVER_VERSION = '0.0.0'
+
+export interface McpCommandOptions {
+  serverUrl?: string
+  version?: string
+}
+
+interface McpToolResult<T extends Record<string, unknown>> {
+  [key: string]: unknown
+  content: Array<{ type: 'text'; text: string }>
+  structuredContent: T
+  isError?: boolean
+}
+
+export interface InspectoMcpRuntime {
+  getSession(args: { sessionId: string }): Promise<Record<string, unknown>>
+  claimNext(args?: { timeoutMs?: number }): Promise<{
+    success: boolean
+    timedOut: boolean
+    matchedExisting: boolean
+    session?: Record<string, unknown>
+    event?: string
+  }>
+  reply(args: { sessionId: string; text: string }): Promise<Record<string, unknown>>
+  resolve(args: { sessionId: string; message?: string }): Promise<Record<string, unknown>>
+  dismiss(args: { sessionId: string; message?: string }): Promise<Record<string, unknown>>
+}
+
+export interface InspectoMcpToolDefinition {
+  name:
+    | 'inspecto_get_session'
+    | 'inspecto_claim_next'
+    | 'inspecto_reply'
+    | 'inspecto_resolve'
+    | 'inspecto_dismiss'
+  description: string
+}
+
+export const INSPECTO_MCP_TOOLS: InspectoMcpToolDefinition[] = [
+  {
+    name: 'inspecto_get_session',
+    description: 'Return one Inspecto annotation session by sessionId.',
+  },
+  {
+    name: 'inspecto_claim_next',
+    description:
+      'Wait for the next unclaimed Inspecto annotation session, mark it acknowledged, and return full context.',
+  },
+  {
+    name: 'inspecto_reply',
+    description: 'Append an agent reply to an Inspecto annotation session.',
+  },
+  {
+    name: 'inspecto_resolve',
+    description: 'Resolve an Inspecto annotation session with an optional final message.',
+  },
+  {
+    name: 'inspecto_dismiss',
+    description: 'Dismiss an Inspecto annotation session with an optional final message.',
+  },
+]
+
+export async function startMcpServer(options: McpCommandOptions = {}): Promise<void> {
+  const baseUrl = options.serverUrl ?? resolveInspectoServerBaseUrl(process.cwd())
+  if (!baseUrl) {
+    throw new Error(
+      'Could not find a running Inspecto dev server. Start your local dev server or pass --server-url <url>.',
+    )
+  }
+
+  const server = createInspectoMcpServer({
+    baseUrl,
+    ...(options.version ? { version: options.version } : {}),
+  })
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+}
+
+export function createInspectoMcpServer(options: { baseUrl: string; version?: string }): McpServer {
+  const runtime = createInspectoMcpRuntime(options.baseUrl)
+  const server = new McpServer({
+    name: 'inspecto-mcp',
+    version: options.version ?? DEFAULT_MCP_SERVER_VERSION,
+  })
+
+  server.registerTool(
+    'inspecto_get_session',
+    {
+      description: getToolDescription('inspecto_get_session'),
+      inputSchema: {
+        sessionId: z.string().min(1),
+      },
+    },
+    async ({ sessionId }) => {
+      try {
+        const result = await runtime.getSession({ sessionId })
+        return toolSuccess(result)
+      } catch (error) {
+        return toolError(error)
+      }
+    },
+  )
+
+  server.registerTool(
+    'inspecto_claim_next',
+    {
+      description: getToolDescription('inspecto_claim_next'),
+      inputSchema: {
+        timeoutMs: z.number().int().nonnegative().optional(),
+      },
+    },
+    async ({ timeoutMs }) => {
+      try {
+        const result = await runtime.claimNext({
+          ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        })
+        return toolSuccess(result)
+      } catch (error) {
+        return toolError(error)
+      }
+    },
+  )
+
+  server.registerTool(
+    'inspecto_reply',
+    {
+      description: getToolDescription('inspecto_reply'),
+      inputSchema: {
+        sessionId: z.string().min(1),
+        text: z.string().min(1),
+      },
+    },
+    async ({ sessionId, text }) => {
+      try {
+        const result = await runtime.reply({ sessionId, text })
+        return toolSuccess(result)
+      } catch (error) {
+        return toolError(error)
+      }
+    },
+  )
+
+  server.registerTool(
+    'inspecto_resolve',
+    {
+      description: getToolDescription('inspecto_resolve'),
+      inputSchema: {
+        sessionId: z.string().min(1),
+        message: z.string().optional(),
+      },
+    },
+    async ({ sessionId, message }) => {
+      try {
+        const result = await runtime.resolve({ sessionId, ...(message ? { message } : {}) })
+        return toolSuccess(result)
+      } catch (error) {
+        return toolError(error)
+      }
+    },
+  )
+
+  server.registerTool(
+    'inspecto_dismiss',
+    {
+      description: getToolDescription('inspecto_dismiss'),
+      inputSchema: {
+        sessionId: z.string().min(1),
+        message: z.string().optional(),
+      },
+    },
+    async ({ sessionId, message }) => {
+      try {
+        const result = await runtime.dismiss({ sessionId, ...(message ? { message } : {}) })
+        return toolSuccess(result)
+      } catch (error) {
+        return toolError(error)
+      }
+    },
+  )
+
+  return server
+}
+
+export function getToolDescription(name: InspectoMcpToolDefinition['name']): string {
+  return INSPECTO_MCP_TOOLS.find(tool => tool.name === name)?.description ?? name
+}
+
+export function createInspectoMcpRuntime(baseUrl: string): InspectoMcpRuntime {
+  return {
+    async getSession(args) {
+      return getSession(baseUrl, args.sessionId)
+    },
+
+    async claimNext(args = {}) {
+      return (await postJson(`${baseUrl}${INSPECTO_API_PATHS.SESSION_CLAIM_NEXT}`, {
+        ...(args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {}),
+      })) as {
+        success: boolean
+        timedOut: boolean
+        matchedExisting: boolean
+        session?: Record<string, unknown>
+        event?: string
+      }
+    },
+
+    async reply(args) {
+      return postJson(
+        `${baseUrl}${INSPECTO_API_PATHS.SESSIONS}/${args.sessionId}${INSPECTO_API_PATHS.SESSION_REPLY_SUFFIX}`,
+        {
+          role: 'agent',
+          text: args.text.trim(),
+        },
+      ) as Promise<Record<string, unknown>>
+    },
+
+    async resolve(args) {
+      return postJson(
+        `${baseUrl}${INSPECTO_API_PATHS.SESSIONS}/${args.sessionId}${INSPECTO_API_PATHS.SESSION_RESOLVE_SUFFIX}`,
+        args.message?.trim() ? { message: args.message.trim() } : {},
+      ) as Promise<Record<string, unknown>>
+    },
+
+    async dismiss(args) {
+      return postJson(
+        `${baseUrl}${INSPECTO_API_PATHS.SESSIONS}/${args.sessionId}${INSPECTO_API_PATHS.SESSION_DISMISS_SUFFIX}`,
+        args.message?.trim() ? { message: args.message.trim() } : {},
+      ) as Promise<Record<string, unknown>>
+    },
+  }
+}
+
+export function resolveInspectoServerBaseUrl(cwd: string): string | null {
+  const ports = resolveServerPorts(cwd)
+  const port = ports[0]
+  return port ? `http://0.0.0.0:${port}` : null
+}
+
+export function resolveServerPorts(cwd: string): number[] {
+  const prioritized = readProjectScopedPorts(cwd)
+  if (prioritized.length > 0) return prioritized
+
+  const legacyPortFile = path.join(os.tmpdir(), 'inspecto.port')
+  try {
+    const raw = fs.readFileSync(legacyPortFile, 'utf-8').trim()
+    const port = parseInt(raw, 10)
+    if (Number.isInteger(port) && port > 0 && port < 65536) {
+      return [port]
+    }
+  } catch {
+    // ignore
+  }
+
+  return Array.from({ length: 23 }, (_, index) => 5678 + index)
+}
+
+function toolSuccess<T extends Record<string, unknown>>(value: T): McpToolResult<T> {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(value, null, 2),
+      },
+    ],
+    structuredContent: value,
+  }
+}
+
+function toolError(error: unknown): McpToolResult<{ success: false; error: string }> {
+  const message = error instanceof Error ? error.message : String(error)
+  return {
+    content: [
+      {
+        type: 'text',
+        text: message,
+      },
+    ],
+    structuredContent: {
+      success: false,
+      error: message,
+    },
+    isError: true,
+  }
+}
+
+async function getJson(url: string): Promise<unknown> {
+  const response = await fetch(url)
+  const payload = (await response.json().catch(() => ({}))) as Record<string, unknown>
+  if (!response.ok) {
+    throw new Error(String(payload['error'] ?? `Request failed with status ${response.status}.`))
+  }
+  return payload
+}
+
+async function getSession(baseUrl: string, sessionId: string): Promise<Record<string, unknown>> {
+  const trimmed = sessionId.trim()
+  if (!trimmed) {
+    throw new Error('Session id is required.')
+  }
+
+  const payload = (await getJson(
+    `${baseUrl}${INSPECTO_API_PATHS.SESSIONS}/${encodeURIComponent(trimmed)}`,
+  )) as {
+    success?: boolean
+    session?: Record<string, unknown>
+    error?: string
+  }
+
+  if (!payload.success || !payload.session) {
+    throw new Error(payload.error ?? 'Session not found.')
+  }
+
+  return {
+    success: true,
+    session: payload.session,
+  }
+}
+
+async function postJson(url: string, body: Record<string, unknown>): Promise<unknown> {
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+  const payload = (await response.json().catch(() => ({}))) as Record<string, unknown>
+  if (!response.ok || payload['success'] === false) {
+    throw new Error(String(payload['error'] ?? `Request failed with status ${response.status}.`))
+  }
+  return payload
+}
+
+function readProjectScopedPorts(cwd: string): number[] {
+  const portFile = path.join(os.tmpdir(), 'inspecto.port.json')
+  try {
+    const raw = fs.readFileSync(portFile, 'utf-8').trim()
+    const portData = JSON.parse(raw) as Record<string, number>
+    const currentRootHashes = resolveCandidateRootHashes(cwd)
+
+    const prioritized: number[] = []
+    const seen = new Set<number>()
+
+    for (const rootHash of currentRootHashes) {
+      const currentPort = portData[rootHash]
+      if (currentPort && !seen.has(currentPort)) {
+        prioritized.push(currentPort)
+        seen.add(currentPort)
+      }
+    }
+
+    for (const port of Object.values(portData)) {
+      if (!seen.has(port)) {
+        prioritized.push(port)
+        seen.add(port)
+      }
+    }
+
+    return prioritized
+  } catch {
+    return []
+  }
+}
+
+function resolveCandidateRootHashes(cwd: string): string[] {
+  const normalized = path.resolve(cwd)
+  const candidates = new Set<string>()
+  let currentDir = normalized
+
+  while (true) {
+    candidates.add(crypto.createHash('md5').update(currentDir).digest('hex'))
+    const parentDir = path.dirname(currentDir)
+    if (parentDir === currentDir) {
+      break
+    }
+    currentDir = parentDir
+  }
+
+  return [...candidates]
+}

package/src/commands/onboard.ts

@@ -57,6 +57,7 @@ function buildAssistantHandoff(
     ...(result.pendingSteps ? { pendingSteps: result.pendingSteps } : {}),
     ...(result.assistantPrompt ? { assistantPrompt: result.assistantPrompt } : {}),
     ...(result.patches ? { patches: result.patches } : {}),
+    ...(result.dailyUsage ? { dailyUsage: result.dailyUsage } : {}),
   }
 }
 
@@ -110,6 +111,9 @@ function printOnboardResult(result: OnboardCommandResult): void {
   if (normalized.handoff?.assistantPrompt) {
     log.hint(normalized.handoff.assistantPrompt)
   }
+  if (normalized.handoff?.dailyUsage?.prompt) {
+    log.hint(normalized.handoff.dailyUsage.prompt)
+  }
   if (normalized.confirmation.required && normalized.confirmation.question) {
     log.warn(normalized.confirmation.question)
   }
@@ -139,7 +143,7 @@ export async function onboard(options: OnboardCommandOptions = {}): Promise<Onbo
     session.status === 'needs_confirmation'
   ) {
     return writeCommandOutput(
-      normalizeOnboardResult(buildDeferredOnboardResult(session)),
+      normalizeOnboardResult(await buildDeferredOnboardResult(session)),
       options.json ?? false,
       printOnboardResult,
     )

package/src/detect/framework.ts

@@ -1,14 +1,14 @@
 // ============================================================
 // src/detect/framework.ts — Frontend framework detection
 //
-// v1 supported: React / Vue
-// Recognized but unsupported: Solid, Svelte, Angular, Preact, Lit
+// v1 supported: React / Vue / Svelte / Solid / Astro
+// Recognized but unsupported: Angular, Preact, Lit
 // ============================================================
 import path from 'node:path'
 import { createRequire } from 'node:module'
 import { readJSON } from '../utils/fs.js'
 
-export type Framework = 'react' | 'vue'
+export type Framework = 'react' | 'vue' | 'svelte' | 'solid' | 'astro'
 
 export interface FrameworkDetection {
   supported: Framework[]
@@ -25,11 +25,14 @@ interface PackageJSON {
 const META_FRAMEWORK_MAP: Record<string, Framework> = {
   next: 'react',
   nuxt: 'vue',
+  '@sveltejs/kit': 'svelte',
   '@remix-run/react': 'react',
   '@remix-run/dev': 'react',
   '@vue/nuxt': 'vue',
   'vite-plugin-vue': 'vue',
   '@vitejs/plugin-vue': 'vue',
+  '@sveltejs/vite-plugin-svelte': 'svelte',
+  'vite-plugin-solid': 'solid',
   '@vitejs/plugin-react': 'react',
   '@vitejs/plugin-react-swc': 'react',
 }
@@ -38,13 +41,13 @@ const META_FRAMEWORK_MAP: Record<string, Framework> = {
 const SUPPORTED_FRAMEWORKS: { framework: Framework; deps: string[] }[] = [
   { framework: 'react', deps: ['react', 'react-dom'] },
   { framework: 'vue', deps: ['vue'] },
+  { framework: 'svelte', deps: ['svelte'] },
+  { framework: 'solid', deps: ['solid-js'] },
+  { framework: 'astro', deps: ['astro'] },
 ]
 
 /** Recognized but not supported in v1 — detect and warn */
 const UNSUPPORTED_FRAMEWORKS: { name: string; dep: string }[] = [
-  { name: 'Solid', dep: 'solid-js' },
-  { name: 'Svelte', dep: 'svelte' },
-  { name: 'SvelteKit', dep: '@sveltejs/kit' },
   { name: 'Angular', dep: '@angular/core' },
   { name: 'Preact', dep: 'preact' },
   { name: 'Lit', dep: 'lit' },

package/src/detect/ide.ts

@@ -51,7 +51,8 @@ export async function detectIDE(root: string): Promise<IDEProbeResult> {
   if (
     process.env.__CFBundleIdentifier === 'ai.codebuddy.mac.cn' ||
     process.env.COCO_IDE_PLUGIN_TYPE === 'CodeBuddyCN' ||
-    (process.env.npm_config_user_agent && process.env.npm_config_user_agent.includes('codebuddy-cn'))
+    (process.env.npm_config_user_agent &&
+      process.env.npm_config_user_agent.includes('codebuddy-cn'))
   ) {
     detected.set('CodeBuddy CN', { ide: 'codebuddy-cn', supported: true })
   } else if (
@@ -83,15 +84,16 @@ export async function detectIDE(root: string): Promise<IDEProbeResult> {
   // if (process.env.TERM_PROGRAM === 'vscode') { ... }
 
   // 2. Check Directory Artifacts (Indicates project has been opened in these IDEs)
-  const [hasTrae, hasTraeCn, hasCursor, hasVscode, hasIdea, hasCodeBuddy, hasCodeBuddyCn] = await Promise.all([
-    exists(path.join(root, '.trae')),
-    exists(path.join(root, '.trae-cn')),
-    exists(path.join(root, '.cursor')),
-    exists(path.join(root, '.vscode')),
-    exists(path.join(root, '.idea')),
-    exists(path.join(root, '.codebuddy')),
-    exists(path.join(root, '.codebuddy-cn')),
-  ])
+  const [hasTrae, hasTraeCn, hasCursor, hasVscode, hasIdea, hasCodeBuddy, hasCodeBuddyCn] =
+    await Promise.all([
+      exists(path.join(root, '.trae')),
+      exists(path.join(root, '.trae-cn')),
+      exists(path.join(root, '.cursor')),
+      exists(path.join(root, '.vscode')),
+      exists(path.join(root, '.idea')),
+      exists(path.join(root, '.codebuddy')),
+      exists(path.join(root, '.codebuddy-cn')),
+    ])
 
   // If a directory artifact exists, add it to the detection list.
   // This allows us to surface multiple options (e.g. if you are in Cursor but also have a .vscode folder).

package/src/detect/provider.ts

@@ -6,7 +6,7 @@
 import path from 'node:path'
 import { exists, readJSON } from '../utils/fs.js'
 import { which } from '../utils/exec.js'
-import type { Provider, ProviderMode } from '@inspecto-dev/types'
+import type { Provider } from '@inspecto-dev/types'
 
 export interface ProviderDetection {
   id: Provider

package/src/index.ts

@@ -4,6 +4,12 @@ export { devLink, devStatus, devUnlink } from './commands/dev-config.js'
 export { init } from './commands/init.js'
 export { collectDoctorResult, doctor } from './commands/doctor.js'
 export { integrationDoctor } from './commands/integration-doctor.js'
+export {
+  startMcpServer,
+  createInspectoMcpRuntime,
+  createInspectoMcpServer,
+  resolveInspectoServerBaseUrl,
+} from './commands/mcp.js'
 export { onboard } from './commands/onboard.js'
 export { plan } from './commands/plan.js'
 export { teardown } from './commands/teardown.js'

package/src/inject/strategies/esbuild.ts

@@ -8,11 +8,11 @@ export class EsbuildStrategy implements InjectStrategy {
     return tool === 'esbuild'
   }
 
-  inject(options: InjectOptions): void {
+  inject(_options: InjectOptions): void {
     throw new Error('Esbuild requires manual plugin configuration')
   }
 
-  getManualInstructions(detection: BuildToolDetection, reason: string): string[] {
+  getManualInstructions(detection: BuildToolDetection, _reason: string): string[] {
     return [
       `1. Update your esbuild config (${detection.configPath}):`,
       `import { esbuildPlugin as inspecto } from '@inspecto-dev/plugin'`,

package/src/inject/strategies/rollup.ts

@@ -8,11 +8,11 @@ export class RollupStrategy implements InjectStrategy {
     return tool === 'rollup'
   }
 
-  inject(options: InjectOptions): void {
+  inject(_options: InjectOptions): void {
     throw new Error('Rollup requires manual plugin configuration')
   }
 
-  getManualInstructions(detection: BuildToolDetection, reason: string): string[] {
+  getManualInstructions(detection: BuildToolDetection, _reason: string): string[] {
     return [
       `1. Update your rollup config (${detection.configPath}):`,
       `import { rollupPlugin as inspecto } from '@inspecto-dev/plugin'`,

package/src/inject/strategies/rsbuild.ts

@@ -8,11 +8,11 @@ export class RsbuildStrategy implements InjectStrategy {
     return tool === 'rsbuild'
   }
 
-  inject(options: InjectOptions): void {
+  inject(_options: InjectOptions): void {
     throw new Error('Rsbuild requires manual plugin configuration due to nested structure')
   }
 
-  getManualInstructions(detection: BuildToolDetection, reason: string): string[] {
+  getManualInstructions(_detection: BuildToolDetection, _reason: string): string[] {
     return [
       `import { rspackPlugin as inspecto } from '@inspecto-dev/plugin'`,
       '',

package/src/inject/strategies/rspack.ts

@@ -8,11 +8,11 @@ export class RspackStrategy implements InjectStrategy {
     return tool === 'rspack'
   }
 
-  inject(options: InjectOptions): void {
+  inject(_options: InjectOptions): void {
     throw new Error('Rspack requires manual plugin configuration')
   }
 
-  getManualInstructions(detection: BuildToolDetection, reason: string): string[] {
+  getManualInstructions(detection: BuildToolDetection, _reason: string): string[] {
     const importPkg = detection.isLegacyRspack
       ? '@inspecto-dev/plugin/legacy/rspack'
       : '@inspecto-dev/plugin'

package/src/inject/strategies/vite.ts

@@ -9,7 +9,7 @@ export class ViteStrategy implements InjectStrategy {
     return tool === 'vite'
   }
 
-  inject({ mod, detection }: InjectOptions): void {
+  inject({ mod, detection: _detection }: InjectOptions): void {
     addVitePlugin(mod, {
       from: '@inspecto-dev/plugin',
       constructor: 'inspecto',
@@ -17,7 +17,7 @@ export class ViteStrategy implements InjectStrategy {
     })
   }
 
-  getManualInstructions(detection: BuildToolDetection, reason: string): string[] {
+  getManualInstructions(_detection: BuildToolDetection, _reason: string): string[] {
     return [
       `import { vitePlugin as inspecto } from '@inspecto-dev/plugin'`,
       '',

package/src/inject/strategies/webpack.ts

@@ -8,12 +8,12 @@ export class WebpackStrategy implements InjectStrategy {
     return tool === 'webpack'
   }
 
-  inject(options: InjectOptions): void {
+  inject(_options: InjectOptions): void {
     // AST manipulation for Webpack configs (often CommonJS or complex objects) is brittle in v1
     throw new Error('Webpack requires manual plugin configuration')
   }
 
-  getManualInstructions(detection: BuildToolDetection, reason: string): string[] {
+  getManualInstructions(detection: BuildToolDetection, _reason: string): string[] {
     const importPkg = detection.isLegacyWebpack
       ? '@inspecto-dev/plugin/legacy/webpack4'
       : '@inspecto-dev/plugin'

package/src/instructions.ts

@@ -83,7 +83,7 @@ export function printNextJsManualInstructions() {
     '  useEffect(() => {',
     "    if (process.env.NODE_ENV !== 'production') {",
     "      import('@inspecto-dev/core').then(({ mountInspector }) => {",
-    "        mountInspector({ serverUrl: 'http://127.0.0.1:5678' })",
+    "        mountInspector({ serverUrl: 'http://0.0.0.0:5678' })",
     '      })',
     '    }',
     '  }, [])',