@inspecto-dev/cli 0.3.8 → 0.3.10

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/onboarding/session.ts

@@ -14,6 +14,7 @@ import { resolveOnboardingTarget } from './target-resolution.js'
 import { readJSON } from '../utils/fs.js'
 import type {
   OnboardCommandResult,
+  OnboardingDailyUsageHandoff,
   OnboardingContext,
   OnboardingDiagnostics,
   OnboardingExecutionResult,
@@ -256,9 +257,37 @@ function buildConfirmation(
   }
 }
 
+async function buildDailyUsageHandoff(
+  projectRoot: string,
+): Promise<OnboardingDailyUsageHandoff | undefined> {
+  const localSettings =
+    (await readJSON<Record<string, unknown>>(
+      path.join(projectRoot, '.inspecto', 'settings.local.json'),
+    )) ?? {}
+  const sharedSettings =
+    (await readJSON<Record<string, unknown>>(
+      path.join(projectRoot, '.inspecto', 'settings.json'),
+    )) ?? {}
+  const annotateDeliveryMode =
+    (localSettings['annotate.deliveryMode'] as string | undefined) ??
+    (sharedSettings['annotate.deliveryMode'] as string | undefined)
+
+  if (annotateDeliveryMode !== 'agent') {
+    return undefined
+  }
+
+  return {
+    mode: 'agent',
+    skill: 'inspecto-agent',
+    prompt: 'Use $inspecto-agent to claim Inspecto tasks continuously',
+    requiresMcp: true,
+  }
+}
+
 function buildPreApplyResult(
   status: ResolvedOnboardingSession['status'],
   session: ResolvedOnboardingSession,
+  dailyUsage?: OnboardingDailyUsageHandoff,
 ): OnboardCommandResult {
   const diagnostics: OnboardingDiagnostics | undefined =
     session.summary.risks.length > 0 ||
@@ -292,6 +321,7 @@ function buildPreApplyResult(
     ...(session.pendingSteps ? { pendingSteps: session.pendingSteps } : {}),
     ...(session.assistantPrompt ? { assistantPrompt: session.assistantPrompt } : {}),
     ...(session.patches ? { patches: session.patches } : {}),
+    ...(dailyUsage ? { dailyUsage } : {}),
     ...(diagnostics ? { diagnostics } : {}),
   }
 }
@@ -353,6 +383,7 @@ export async function resolveOnboardingSession(
 ): Promise<ResolvedOnboardingSession> {
   const rootContext = await buildOnboardingContext(root)
   const rootVerification = await buildVerification(root, rootContext.packageManager)
+  const rootDailyUsage = await buildDailyUsageHandoff(root)
   const frameworkSupportByPackage = await detectFrameworkSupportByPackage(root, rootContext)
   const target = resolveOnboardingTarget({
     repoRoot: root,
@@ -392,6 +423,7 @@ export async function resolveOnboardingSession(
       ...(plan.pendingSteps ? { pendingSteps: plan.pendingSteps } : {}),
       ...(plan.assistantPrompt ? { assistantPrompt: plan.assistantPrompt } : {}),
       ...(plan.patches ? { patches: plan.patches } : {}),
+      ...(rootDailyUsage ? { dailyUsage: rootDailyUsage } : {}),
     }
   }
 
@@ -418,6 +450,7 @@ export async function resolveOnboardingSession(
 
   const context = await buildTargetedContext(rootContext, target.selected!)
   const verification = await buildVerification(context.root, context.packageManager)
+  const dailyUsage = await buildDailyUsageHandoff(context.root)
   const plan = createPlanResult(context)
   const summary = buildOnboardingSummary(plan, context.root)
   const confirmation = buildConfirmation(
@@ -469,6 +502,7 @@ export async function resolveOnboardingSession(
     ...(plan.pendingSteps ? { pendingSteps: plan.pendingSteps } : {}),
     ...(plan.assistantPrompt ? { assistantPrompt: plan.assistantPrompt } : {}),
     ...(plan.patches ? { patches: plan.patches } : {}),
+    ...(dailyUsage ? { dailyUsage } : {}),
   }
 }
 
@@ -477,6 +511,7 @@ export async function applyResolvedOnboardingSession(
   options: ResolveOnboardingSessionOptions = {},
 ): Promise<OnboardCommandResult> {
   const verification = await buildVerification(session.projectRoot, session.context.packageManager)
+  const dailyUsage = await buildDailyUsageHandoff(session.projectRoot)
   const applyResult = await applyOnboardingPlan({
     repoRoot: process.cwd(),
     projectRoot: session.projectRoot,
@@ -528,12 +563,17 @@ export async function applyResolvedOnboardingSession(
     ...(session.pendingSteps ? { pendingSteps: session.pendingSteps } : {}),
     ...(session.assistantPrompt ? { assistantPrompt: session.assistantPrompt } : {}),
     ...(session.patches ? { patches: session.patches } : {}),
+    ...(dailyUsage ? { dailyUsage } : {}),
     ...(diagnostics ? { diagnostics } : {}),
   }
 }
 
-export function buildDeferredOnboardResult(
+export async function buildDeferredOnboardResult(
   session: ResolvedOnboardingSession,
-): OnboardCommandResult {
-  return buildPreApplyResult(session.status, session)
+): Promise<OnboardCommandResult> {
+  return buildPreApplyResult(
+    session.status,
+    session,
+    await buildDailyUsageHandoff(session.projectRoot),
+  )
 }

package/src/onboarding/umi-guidance.ts

@@ -93,7 +93,7 @@ function buildUmiMountSnippet(): string {
     "    if (process.env.NODE_ENV !== 'production') {",
     "      import('@inspecto-dev/core').then(({ mountInspector }) => {",
     '        mountInspector({',
-    "          serverUrl: 'http://127.0.0.1:' + ((window as any).__AI_INSPECTOR_PORT__ || 5678),",
+    "          serverUrl: 'http://127.0.0.1:' + ((window as { __AI_INSPECTOR_PORT__?: number }).__AI_INSPECTOR_PORT__ || 5678),",
     '        })',
     '      })',
     '    }',

package/src/prompts.ts

@@ -10,23 +10,33 @@ export async function promptIDEChoice(
   detections: { ide: string; supported: boolean }[],
 ): Promise<{ ide: string; supported: boolean } | null> {
   if (!process.stdin.isTTY) {
-    log.warn('Multiple IDEs detected but stdin is not interactive')
-    log.hint(`Using: ${detections[0]!.ide} (first match)`)
-    return detections[0]!
+    if (detections.length > 0) {
+      log.warn('Multiple IDEs detected but stdin is not interactive')
+      log.hint(`Using: ${detections[0]!.ide} (first match)`)
+      return detections[0]!
+    }
+    return { ide: 'none', supported: true }
   }
 
+  const choices = detections.map(d => ({
+    title: `${d.ide} ${d.supported ? '(supported)' : '(unsupported/limited)'}`,
+    value: d,
+  }))
+
+  choices.push({
+    title: 'none (Standalone / MCP / Browser-only)',
+    value: { ide: 'none', supported: true },
+  })
+
   const { choice } = await prompts({
     type: 'select',
     name: 'choice',
-    message: 'Detected multiple IDEs, please choose one:',
-    choices: detections.map((d, i) => ({
-      title: `${d.ide} ${d.supported ? '(supported)' : '(unsupported/limited)'}`,
-      value: i,
-    })),
+    message: 'Detected multiple IDEs, please choose one (or select none for standalone use):',
+    choices,
   })
 
   if (choice === undefined) return null
-  return detections[choice]!
+  return choice
 }
 
 /**

package/src/types.ts

@@ -134,6 +134,13 @@ export interface OnboardingVerification {
   message: string
 }
 
+export interface OnboardingDailyUsageHandoff {
+  mode: 'agent'
+  skill: string
+  prompt: string
+  requiresMcp: boolean
+}
+
 export interface OnboardingAssistantHandoff {
   framework?: string
   metaFramework?: string
@@ -142,6 +149,7 @@ export interface OnboardingAssistantHandoff {
   pendingSteps?: string[]
   assistantPrompt?: string
   patches?: OnboardingPatchPlan[]
+  dailyUsage?: OnboardingDailyUsageHandoff
 }
 
 export interface ResolvedOnboardingSession {
@@ -162,6 +170,7 @@ export interface ResolvedOnboardingSession {
   pendingSteps?: string[]
   assistantPrompt?: string
   patches?: OnboardingPatchPlan[]
+  dailyUsage?: OnboardingDailyUsageHandoff
   handoff?: OnboardingAssistantHandoff
 }
 
@@ -181,6 +190,7 @@ export interface OnboardCommandResult {
   pendingSteps?: string[]
   assistantPrompt?: string
   patches?: OnboardingPatchPlan[]
+  dailyUsage?: OnboardingDailyUsageHandoff
   handoff?: OnboardingAssistantHandoff
 }
 

package/tests/integration-install.test.ts

@@ -126,6 +126,14 @@ describe('integration install', () => {
       '/Users/tester/.agents/skills/inspecto-onboarding-codex/scripts/run-inspecto.sh',
       '# mock asset',
     )
+    expect(writeFileMock).toHaveBeenCalledWith(
+      '/Users/tester/.agents/skills/inspecto-agent-codex/SKILL.md',
+      '# mock asset',
+    )
+    expect(writeFileMock).toHaveBeenCalledWith(
+      '/Users/tester/.agents/skills/inspecto-agent-codex/agents/openai.yaml',
+      '# mock asset',
+    )
     expect(chmodMock).toHaveBeenCalledWith(
       '/Users/tester/.agents/skills/inspecto-onboarding-codex/scripts/run-inspecto.sh',
       0o755,
@@ -134,6 +142,9 @@ describe('integration install', () => {
     expect(logMock.hint).toHaveBeenCalledWith(
       '/Users/tester/.agents/skills/inspecto-onboarding-codex/SKILL.md',
     )
+    expect(logMock.hint).toHaveBeenCalledWith(
+      '/Users/tester/.agents/skills/inspecto-agent-codex/SKILL.md',
+    )
     expect(runIntegrationAutomationMock).not.toHaveBeenCalled()
     expect(logMock.ready).toHaveBeenCalledWith(
       'Installed Codex integration assets. User-level installs only write integration assets and do not launch onboarding automatically.',
@@ -199,6 +210,7 @@ describe('integration install', () => {
     expect(writeJSONMock).toHaveBeenCalledWith('/repo/.inspecto/settings.local.json', {
       ide: 'trae-cn',
       'provider.default': 'gemini.extension',
+      'annotate.deliveryMode': 'both',
     })
   })
 
@@ -216,6 +228,7 @@ describe('integration install', () => {
     expect(writeJSONMock).toHaveBeenCalledWith('/repo/.inspecto/settings.local.json', {
       ide: 'trae-cn',
       'provider.default': 'gemini.extension',
+      'annotate.deliveryMode': 'both',
       'prompt.autoSend': true,
     })
   })
@@ -228,6 +241,7 @@ describe('integration install', () => {
     expect(writeJSONMock).toHaveBeenCalledWith('/repo/.inspecto/settings.local.json', {
       ide: 'cursor',
       'provider.default': 'codex.extension',
+      'annotate.deliveryMode': 'both',
     })
   })
 
@@ -540,6 +554,8 @@ describe('integration install', () => {
         '/Users/tester/.agents/skills/inspecto-onboarding-codex/SKILL.md',
         '/Users/tester/.agents/skills/inspecto-onboarding-codex/agents/openai.yaml',
         '/Users/tester/.agents/skills/inspecto-onboarding-codex/scripts/run-inspecto.sh',
+        '/Users/tester/.agents/skills/inspecto-agent-codex/SKILL.md',
+        '/Users/tester/.agents/skills/inspecto-agent-codex/agents/openai.yaml',
       ],
       preferredInstall:
         'npx @inspecto-dev/cli integrations install codex --host-ide <vscode|cursor|trae|trae-cn|codebuddy|codebuddy-cn>',

package/tests/mcp.test.ts

@@ -0,0 +1,197 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import {
+  INSPECTO_MCP_TOOLS,
+  createInspectoMcpRuntime,
+  resolveInspectoServerBaseUrl,
+} from '../src/commands/mcp.js'
+
+describe('inspecto mcp command', () => {
+  const portFile = path.join(os.tmpdir(), 'inspecto.port.json')
+  let originalPortFile: string | null = null
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+    try {
+      fs.unlinkSync(portFile)
+    } catch {
+      // ignore
+    }
+    if (originalPortFile !== null) {
+      fs.writeFileSync(portFile, originalPortFile, 'utf-8')
+      originalPortFile = null
+    }
+  })
+
+  it('resolves the current project server URL from inspecto.port.json', () => {
+    originalPortFile = fs.existsSync(portFile) ? fs.readFileSync(portFile, 'utf-8') : null
+    const cwd = '/repo/current'
+    const currentHash = crypto.createHash('md5').update(cwd).digest('hex')
+    const otherHash = crypto.createHash('md5').update('/repo/other').digest('hex')
+
+    fs.writeFileSync(
+      portFile,
+      JSON.stringify(
+        {
+          [otherHash]: 5679,
+          [currentHash]: 5680,
+        },
+        null,
+        2,
+      ),
+      'utf-8',
+    )
+
+    expect(resolveInspectoServerBaseUrl(cwd)).toBe('http://127.0.0.1:5680')
+  })
+
+  it('resolves the project server URL when Codex runs from a nested working directory', () => {
+    originalPortFile = fs.existsSync(portFile) ? fs.readFileSync(portFile, 'utf-8') : null
+    const projectRoot = '/repo/current'
+    const nestedCwd = '/repo/current/packages/app'
+    const projectRootHash = crypto.createHash('md5').update(projectRoot).digest('hex')
+
+    fs.writeFileSync(
+      portFile,
+      JSON.stringify(
+        {
+          [projectRootHash]: 5681,
+        },
+        null,
+        2,
+      ),
+      'utf-8',
+    )
+
+    expect(resolveInspectoServerBaseUrl(nestedCwd)).toBe('http://127.0.0.1:5681')
+  })
+
+  it('exposes the expected MCP tool definitions', () => {
+    expect(INSPECTO_MCP_TOOLS.map(tool => tool.name)).toEqual([
+      'inspecto_get_session',
+      'inspecto_claim_next',
+      'inspecto_reply',
+      'inspecto_resolve',
+      'inspecto_dismiss',
+    ])
+  })
+
+  it('maps getSession and claimNext to the HTTP session endpoints', async () => {
+    const fetchMock = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true, session: { id: 'session-1' } }),
+      } as Response)
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          success: true,
+          timedOut: false,
+          matchedExisting: true,
+          session: { id: 'session-claim', status: 'acknowledged' },
+        }),
+      } as Response)
+    const runtime = createInspectoMcpRuntime('http://0.0.0.0:5678')
+
+    const session = await runtime.getSession({ sessionId: 'session-1' })
+
+    expect(fetchMock).toHaveBeenCalledWith('http://0.0.0.0:5678/inspecto/api/v1/sessions/session-1')
+    expect(session).toEqual({ success: true, session: { id: 'session-1' } })
+
+    const claim = await runtime.claimNext()
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'http://0.0.0.0:5678/inspecto/api/v1/sessions/claim',
+      expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({}),
+      }),
+    )
+    expect(claim).toEqual({
+      success: true,
+      timedOut: false,
+      matchedExisting: true,
+      session: { id: 'session-claim', status: 'acknowledged' },
+    })
+  })
+
+  it('maps reply, resolve, and dismiss to session mutation endpoints', async () => {
+    const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+      ok: true,
+      json: async () => ({ success: true, session: { id: 'session-1' } }),
+    } as Response)
+    const runtime = createInspectoMcpRuntime('http://0.0.0.0:5678')
+
+    const reply = await runtime.reply({
+      sessionId: 'session-1',
+      text: 'Working on it.',
+    })
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'http://0.0.0.0:5678/inspecto/api/v1/sessions/session-1/reply',
+      expect.objectContaining({
+        method: 'POST',
+      }),
+    )
+    expect(reply).toEqual({ success: true, session: { id: 'session-1' } })
+
+    const resolve = await runtime.resolve({
+      sessionId: 'session-1',
+      message: 'Done.',
+    })
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'http://0.0.0.0:5678/inspecto/api/v1/sessions/session-1/resolve',
+      expect.objectContaining({
+        method: 'POST',
+      }),
+    )
+    expect(resolve).toEqual({ success: true, session: { id: 'session-1' } })
+
+    const dismiss = await runtime.dismiss({
+      sessionId: 'session-1',
+      message: 'No action needed.',
+    })
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'http://0.0.0.0:5678/inspecto/api/v1/sessions/session-1/dismiss',
+      expect.objectContaining({
+        method: 'POST',
+      }),
+    )
+    expect(dismiss).toEqual({ success: true, session: { id: 'session-1' } })
+  })
+
+  it('surfaces failed session mutations as rejected runtime calls', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+      ok: false,
+      status: 404,
+      json: async () => ({ success: false, error: 'Session not found' }),
+    } as Response)
+    const runtime = createInspectoMcpRuntime('http://0.0.0.0:5678')
+
+    await expect(
+      runtime.reply({
+        sessionId: 'missing-session',
+        text: 'Working on it.',
+      }),
+    ).rejects.toThrow('Session not found')
+  })
+
+  it('surfaces direct session lookup failures as rejected runtime calls', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+      ok: false,
+      status: 404,
+      json: async () => ({ success: false, error: 'Session not found' }),
+    } as Response)
+    const runtime = createInspectoMcpRuntime('http://0.0.0.0:5678')
+
+    await expect(runtime.getSession({ sessionId: 'missing-session' })).rejects.toThrow(
+      'Session not found',
+    )
+  })
+})

package/tests/onboard.test.ts

@@ -352,6 +352,12 @@ describe('onboard command', () => {
         'Complete the remaining client-side mount step for your App Router entry.',
       ],
       assistantPrompt: 'Complete the remaining Inspecto onboarding for this Next.js project.',
+      dailyUsage: {
+        mode: 'agent',
+        skill: 'inspecto-agent',
+        prompt: 'Use $inspecto-agent to claim Inspecto tasks continuously',
+        requiresMcp: true,
+      },
       patches: [
         {
           path: 'next.config.mjs',
@@ -393,6 +399,12 @@ describe('onboard command', () => {
         'Complete the remaining client-side mount step for your App Router entry.',
       ],
       assistantPrompt: 'Complete the remaining Inspecto onboarding for this Next.js project.',
+      dailyUsage: {
+        mode: 'agent',
+        skill: 'inspecto-agent',
+        prompt: 'Use $inspecto-agent to claim Inspecto tasks continuously',
+        requiresMcp: true,
+      },
       patches: [
         {
           path: 'next.config.mjs',
@@ -425,6 +437,9 @@ describe('onboard command', () => {
         'Complete the remaining client-side mount step for your App Router entry.',
       ]),
     )
+    expect(result.handoff?.dailyUsage?.prompt).toBe(
+      'Use $inspecto-agent to claim Inspecto tasks continuously',
+    )
     expect(result.assistantPrompt).toContain('Complete the remaining Inspecto onboarding')
     expect(result.patches).toEqual(
       expect.arrayContaining([