@inspecto-dev/cli 0.3.0 → 0.3.2

package/tests/integration-install.test.ts

@@ -13,6 +13,7 @@ const logMock = {
   error: vi.fn(),
   blank: vi.fn(),
 }
+const runIntegrationAutomationMock = vi.fn()
 
 vi.mock('../src/utils/fs.js', () => ({
   writeFile: writeFileMock,
@@ -33,6 +34,10 @@ vi.mock('../src/utils/logger.js', () => ({
   log: logMock,
 }))
 
+vi.mock('../src/commands/integration-automation.js', () => ({
+  runIntegrationAutomation: runIntegrationAutomationMock,
+}))
+
 describe('integration install', () => {
   beforeEach(() => {
     vi.resetModules()
@@ -47,6 +52,10 @@ describe('integration install', () => {
         statusText: 'OK',
       }),
     )
+    runIntegrationAutomationMock.mockResolvedValue({
+      status: 'launched',
+      message: 'Onboarding launched in Cursor for Codex.',
+    })
   })
 
   it('installs the Claude Code skill into the user skill directory', async () => {
@@ -70,38 +79,209 @@ describe('integration install', () => {
       '/Users/tester/.claude/skills/inspecto-onboarding-claude-code/scripts/run-inspecto.sh',
       0o755,
     )
+    expect(runIntegrationAutomationMock).not.toHaveBeenCalled()
   })
 
-  it('installs the Codex skill into the Codex skill directory', async () => {
+  it('installs the Codex skill into the user skill directory when scoped to user', async () => {
     const { installIntegration } = await import('../src/commands/integration-install.js')
 
-    await installIntegration('codex')
+    await installIntegration('codex', { scope: 'user' })
 
     expect(writeFileMock).toHaveBeenCalledWith(
-      '/Users/tester/.codex/skills/inspecto-onboarding-codex/SKILL.md',
+      '/Users/tester/.agents/skills/inspecto-onboarding-codex/SKILL.md',
       '# mock asset',
     )
     expect(writeFileMock).toHaveBeenCalledWith(
-      '/Users/tester/.codex/skills/inspecto-onboarding-codex/agents/openai.yaml',
+      '/Users/tester/.agents/skills/inspecto-onboarding-codex/agents/openai.yaml',
       '# mock asset',
     )
     expect(writeFileMock).toHaveBeenCalledWith(
-      '/Users/tester/.codex/skills/inspecto-onboarding-codex/scripts/run-inspecto.sh',
+      '/Users/tester/.agents/skills/inspecto-onboarding-codex/scripts/run-inspecto.sh',
       '# mock asset',
     )
     expect(chmodMock).toHaveBeenCalledWith(
-      '/Users/tester/.codex/skills/inspecto-onboarding-codex/scripts/run-inspecto.sh',
+      '/Users/tester/.agents/skills/inspecto-onboarding-codex/scripts/run-inspecto.sh',
       0o755,
     )
+    expect(logMock.success).toHaveBeenCalledWith('Step 1/6: Installed Codex integration assets')
+    expect(logMock.hint).toHaveBeenCalledWith(
+      '/Users/tester/.agents/skills/inspecto-onboarding-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.',
+    )
+    expect(logMock.hint).toHaveBeenCalledWith(
+      'Run the install command again from your target project root with --host-ide <vscode|cursor|trae|trae-cn> when you want to launch onboarding automatically.',
+    )
+  })
+
+  it('clarifies that --host-ide does not launch onboarding for user-level installs', async () => {
+    const { installIntegration } = await import('../src/commands/integration-install.js')
+
+    await installIntegration('codex', { scope: 'user', ide: 'cursor' })
+
+    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.',
+    )
+    expect(logMock.hint).toHaveBeenCalledWith(
+      'The provided --host-ide value is saved only as a rerun hint for later; this command does not open Cursor for user-level installs.',
+    )
+    expect(logMock.hint).toHaveBeenCalledWith(
+      'Run the install command again from your target project root with --host-ide cursor when you want to launch onboarding automatically.',
+    )
   })
 
-  it('installs the Cursor AGENTS fallback when agents mode is selected', async () => {
+  it('installs the Cursor agents fallback gracefully acting as skills mode', async () => {
     const { installIntegration } = await import('../src/commands/integration-install.js')
 
     await installIntegration('cursor', { mode: 'agents' })
 
     expect(writeFileMock).toHaveBeenCalledTimes(1)
-    expect(writeFileMock).toHaveBeenCalledWith('AGENTS.md', '# mock asset')
+    expect(writeFileMock).toHaveBeenCalledWith(
+      '.cursor/skills/inspecto-onboarding/SKILL.md',
+      '# mock asset',
+    )
+  })
+
+  it('surfaces a blocked automation outcome as a warning with next-step guidance', async () => {
+    runIntegrationAutomationMock.mockResolvedValue({
+      status: 'blocked',
+      message:
+        'Automatic setup stopped: Inspecto could not find a runnable Gemini target in Trae CN.',
+      nextStep:
+        'Install the Gemini plugin in Trae CN or install the `gemini` CLI, then rerun the command.',
+    })
+
+    const { installIntegration } = await import('../src/commands/integration-install.js')
+
+    await installIntegration('gemini', { ide: 'trae-cn' })
+
+    expect(logMock.warn).toHaveBeenCalledWith(
+      'Automatic setup stopped: Inspecto could not find a runnable Gemini target in Trae CN.',
+    )
+    expect(logMock.hint).toHaveBeenCalledWith(
+      'Install the Gemini plugin in Trae CN or install the `gemini` CLI, then rerun the command.',
+    )
+  })
+
+  it('surfaces a partial automation outcome as a warning with follow-up guidance', async () => {
+    runIntegrationAutomationMock.mockResolvedValue({
+      status: 'partial',
+      message:
+        'Onboarding opened in Trae CN for Gemini, but the Inspecto extension may still need manual setup.',
+      nextStep: 'Install the Inspecto extension in Trae CN if IDE-side features are missing.',
+    })
+
+    const { installIntegration } = await import('../src/commands/integration-install.js')
+
+    await installIntegration('gemini', { ide: 'trae-cn' })
+
+    expect(logMock.warn).toHaveBeenCalledWith(
+      'Onboarding opened in Trae CN for Gemini, but the Inspecto extension may still need manual setup.',
+    )
+    expect(logMock.hint).toHaveBeenCalledWith(
+      'Install the Inspecto extension in Trae CN if IDE-side features are missing.',
+    )
+  })
+
+  it('does not write files in preview mode and surfaces the preview summary', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      text: async () => '# mock asset',
+      status: 200,
+      statusText: 'OK',
+    })
+    vi.stubGlobal('fetch', fetchMock)
+    runIntegrationAutomationMock.mockResolvedValue({
+      status: 'preview',
+      message:
+        'Preview complete. Inspecto did not write files or open IDE windows. Review the resolved setup below, then rerun without --preview to apply it.',
+      nextStep:
+        'Run the same command again without --preview to apply the integration and launch onboarding.',
+    })
+
+    const { installIntegration } = await import('../src/commands/integration-install.js')
+
+    await installIntegration('codex', { preview: true, ide: 'cursor' })
+
+    expect(writeFileMock).not.toHaveBeenCalled()
+    expect(chmodMock).not.toHaveBeenCalled()
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(logMock.info).toHaveBeenCalledWith('Step 1/6: Previewing Codex integration assets')
+    expect(logMock.ready).toHaveBeenCalledWith(
+      'Preview complete. Inspecto did not write files or open IDE windows. Review the resolved setup below, then rerun without --preview to apply it.',
+    )
+    expect(logMock.hint).toHaveBeenCalledWith(
+      'Run the same command again without --preview to apply the integration and launch onboarding.',
+    )
+  })
+
+  it('prints structured JSON output for preview mode when requested', async () => {
+    const fetchMock = vi.fn()
+    const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    vi.stubGlobal('fetch', fetchMock)
+    runIntegrationAutomationMock.mockResolvedValue({
+      status: 'preview',
+      message:
+        'Preview complete. Inspecto did not write files or open IDE windows. Review the resolved setup below, then rerun without --preview to apply it.',
+      nextStep:
+        'Run the same command again without --preview to apply the integration and launch onboarding.',
+      details: {
+        hostIde: {
+          id: 'cursor',
+          label: 'Cursor',
+          source: 'explicit --host-ide',
+          confidence: 'high',
+          candidates: ['cursor'],
+        },
+      },
+    })
+
+    const { installIntegration } = await import('../src/commands/integration-install.js')
+
+    await installIntegration('codex', { preview: true, ide: 'cursor', json: true })
+
+    expect(writeFileMock).not.toHaveBeenCalled()
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(logMock.header).not.toHaveBeenCalled()
+    expect(logMock.info).not.toHaveBeenCalled()
+    expect(logMock.ready).not.toHaveBeenCalled()
+    const payload = JSON.parse(String(consoleLogSpy.mock.calls.at(-1)?.[0] ?? '{}'))
+    expect(payload).toMatchObject({
+      status: 'preview',
+      assistant: 'codex',
+      preview: true,
+      message:
+        'Preview complete. Inspecto did not write files or open IDE windows. Review the resolved setup below, then rerun without --preview to apply it.',
+    })
+    expect(payload.assets).toEqual(
+      expect.arrayContaining(['.agents/skills/inspecto-onboarding-codex/SKILL.md']),
+    )
+
+    consoleLogSpy.mockRestore()
+  })
+
+  it('surfaces a blocked preview outcome as a warning with follow-up guidance', async () => {
+    runIntegrationAutomationMock.mockResolvedValue({
+      status: 'preview_blocked',
+      message:
+        'Preview blocked. Inspecto did not write files or open IDE windows because setup cannot continue until the blocking issue below is resolved.',
+      nextStep:
+        'Install the Trae CN CLI binary or rerun the command from a shell where it is available, then rerun the command.',
+    })
+
+    const { installIntegration } = await import('../src/commands/integration-install.js')
+
+    await installIntegration('gemini', { preview: true, ide: 'trae-cn' })
+
+    expect(logMock.warn).toHaveBeenCalledWith(
+      'Preview blocked. Inspecto did not write files or open IDE windows because setup cannot continue until the blocking issue below is resolved.',
+    )
+    expect(logMock.hint).toHaveBeenCalledWith(
+      'Install the Trae CN CLI binary or rerun the command from a shell where it is available, then rerun the command.',
+    )
   })
 
   it('refuses a multi-file Claude install before writing anything when one target already exists', async () => {
@@ -171,7 +351,7 @@ describe('integration install', () => {
         expect.objectContaining({
           assistant: 'codex',
           type: 'native-skill',
-          installTarget: '~/.codex/skills/',
+          installTarget: '.agents/skills/',
           cliSupported: true,
         }),
         expect.objectContaining({
@@ -181,8 +361,8 @@ describe('integration install', () => {
         }),
         expect.objectContaining({
           assistant: 'copilot',
-          type: 'instruction-template',
-          installTarget: '.github/copilot-instructions.md or AGENTS.md',
+          type: 'native-skill',
+          installTarget: '.github/skills/inspecto-onboarding/',
         }),
       ]),
     )
@@ -198,21 +378,23 @@ describe('integration install', () => {
         '/Users/tester/.claude/skills/inspecto-onboarding-claude-code/agents/openai.yaml',
         '/Users/tester/.claude/skills/inspecto-onboarding-claude-code/scripts/run-inspecto.sh',
       ],
-      preferredInstall: 'npx @inspecto-dev/cli integrations install claude-code --scope project',
+      preferredInstall:
+        'npx @inspecto-dev/cli integrations install claude-code --scope project --host-ide <vscode|cursor|trae|trae-cn>',
     })
   })
 
   it('describes codex using the same CLI-managed install target model', async () => {
     const { describeIntegration } = await import('../src/commands/integration-install.js')
 
-    expect(describeIntegration('codex')).toMatchObject({
+    expect(describeIntegration('codex', { scope: 'user' })).toMatchObject({
       assistant: 'codex',
       targets: [
-        '/Users/tester/.codex/skills/inspecto-onboarding-codex/SKILL.md',
-        '/Users/tester/.codex/skills/inspecto-onboarding-codex/agents/openai.yaml',
-        '/Users/tester/.codex/skills/inspecto-onboarding-codex/scripts/run-inspecto.sh',
+        '/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',
       ],
-      preferredInstall: 'npx @inspecto-dev/cli integrations install codex',
+      preferredInstall:
+        'npx @inspecto-dev/cli integrations install codex --host-ide <vscode|cursor|trae|trae-cn>',
     })
   })
 
@@ -225,13 +407,14 @@ describe('integration install', () => {
       '/Users/tester/.claude/skills/inspecto-onboarding-claude-code/SKILL.md',
     )
     expect(logMock.hint).toHaveBeenCalledWith(
-      'Preferred install: npx @inspecto-dev/cli integrations install claude-code --scope project',
+      'Preferred install: npx @inspecto-dev/cli integrations install claude-code --scope project --host-ide <vscode|cursor|trae|trae-cn>',
     )
     expect(logMock.hint).not.toHaveBeenCalledWith('Restart Claude Code to load the new skill.')
   })
 
   it('rejects unsupported extra args and options for list/path', async () => {
     const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as never)
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
 
     vi.doMock('../src/commands/init.js', () => ({ init: vi.fn() }))
     vi.doMock('../src/commands/doctor.js', () => ({ doctor: vi.fn() }))
@@ -244,18 +427,44 @@ describe('integration install', () => {
 
     await runCli(['node', 'inspecto', 'integrations', 'list', 'extra'])
     await runCli(['node', 'inspecto', 'integrations', 'path', 'claude-code', '--force'])
+    await runCli(['node', 'inspecto', 'integrations', 'list', '--host-ide', 'cursor'])
+    await runCli([
+      'node',
+      'inspecto',
+      'integrations',
+      'path',
+      'claude-code',
+      '--inspecto-vsix',
+      '/tmp/inspecto.vsix',
+    ])
+    await runCli(['node', 'inspecto', 'integrations', 'path', 'claude-code', '--preview'])
+    await runCli(['node', 'inspecto', 'integrations', 'path', 'claude-code', '--json'])
 
     expect(logMock.error).toHaveBeenCalledWith(
-      'The `list` subcommand does not accept assistant names, --scope, --mode, or --force.',
+      'The `list` subcommand does not accept assistant names, --scope, --mode, --host-ide, --inspecto-vsix, --compact, --json, --preview, or --force.',
     )
     expect(logMock.error).toHaveBeenCalledWith('The `path` subcommand does not support `--force`.')
+    expect(logMock.error).toHaveBeenCalledWith(
+      'The `path` subcommand does not support `--inspecto-vsix`.',
+    )
+    expect(logMock.error).toHaveBeenCalledWith(
+      'The `path` subcommand does not support `--preview`.',
+    )
+    expect(JSON.parse(String(consoleErrorSpy.mock.calls.at(-1)?.[0] ?? '{}'))).toMatchObject({
+      status: 'error',
+      error: {
+        message: 'The `path` subcommand does not support `--json`.',
+      },
+    })
     expect(exitSpy).toHaveBeenCalledWith(1)
 
+    consoleErrorSpy.mockRestore()
     exitSpy.mockRestore()
   })
 
   it('wires the nested CLI command to the integration installer', async () => {
     const installCommand = vi.fn().mockResolvedValue(undefined)
+    const doctorCommand = vi.fn().mockResolvedValue({ status: 'ok' })
     const listCommand = vi.fn().mockResolvedValue(undefined)
     const pathCommand = vi.fn().mockResolvedValue(undefined)
 
@@ -270,6 +479,9 @@ describe('integration install', () => {
       printIntegrationList: listCommand,
       printIntegrationPath: pathCommand,
     }))
+    vi.doMock('../src/commands/integration-doctor.js', () => ({
+      integrationDoctor: doctorCommand,
+    }))
 
     const { runCli } = await import('../src/bin.js')
 
@@ -279,6 +491,12 @@ describe('integration install', () => {
       'integrations',
       'install',
       'copilot',
+      '--host-ide',
+      'cursor',
+      '--inspecto-vsix',
+      '/tmp/inspecto.vsix',
+      '--preview',
+      '--json',
       '--mode',
       'agents',
       '--force',
@@ -286,9 +504,53 @@ describe('integration install', () => {
 
     await runCli(['node', 'inspecto', 'integrations', 'list'])
     await runCli(['node', 'inspecto', 'integrations', 'path', 'claude-code', '--scope', 'user'])
+    await runCli([
+      'node',
+      'inspecto',
+      'integrations',
+      'doctor',
+      'codex',
+      '--host-ide',
+      'cursor',
+      '--compact',
+      '--json',
+    ])
 
-    expect(installCommand).toHaveBeenCalledWith('copilot', { mode: 'agents', force: true })
+    expect(installCommand).toHaveBeenCalledWith('copilot', {
+      ide: 'cursor',
+      inspectoVsix: '/tmp/inspecto.vsix',
+      preview: true,
+      json: true,
+      mode: 'agents',
+      force: true,
+    })
     expect(listCommand).toHaveBeenCalledWith()
     expect(pathCommand).toHaveBeenCalledWith('claude-code', { scope: 'user' })
+    expect(doctorCommand).toHaveBeenCalledWith('codex', {
+      ide: 'cursor',
+      compact: true,
+      failOnBlocked: true,
+      json: true,
+    })
+  })
+
+  it('sets a non-zero exit code when integrations doctor reports a blocked result', async () => {
+    const doctorCommand = vi.fn().mockResolvedValue({ status: 'blocked' })
+
+    vi.doMock('../src/commands/init.js', () => ({ init: vi.fn() }))
+    vi.doMock('../src/commands/doctor.js', () => ({ doctor: vi.fn() }))
+    vi.doMock('../src/commands/teardown.js', () => ({ teardown: vi.fn() }))
+    vi.doMock('../src/commands/detect.js', () => ({ detect: vi.fn() }))
+    vi.doMock('../src/commands/plan.js', () => ({ plan: vi.fn() }))
+    vi.doMock('../src/commands/apply.js', () => ({ apply: vi.fn() }))
+    vi.doMock('../src/commands/integration-doctor.js', () => ({
+      integrationDoctor: doctorCommand,
+    }))
+
+    const { runCli } = await import('../src/bin.js')
+
+    await runCli(['node', 'inspecto', 'integrations', 'doctor', 'codex', '--json'])
+
+    expect(doctorCommand).toHaveBeenCalledWith('codex', { json: true, failOnBlocked: true })
   })
 })

package/tests/onboard.test.ts

@@ -347,6 +347,128 @@ describe('onboard command', () => {
     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)
+    expect(
+      consoleSpy.mock.calls.some(call =>
+        String(call[0]).includes('Start the local dev server with `pnpm dev`'),
+      ),
+    ).toBe(true)
+    expect(
+      consoleSpy.mock.calls.some(call =>
+        String(call[0]).includes('code --install-extension inspecto.inspecto'),
+      ),
+    ).toBe(false)
+  })
+
+  it('prints manual extension guidance only when the IDE extension still needs manual completion', 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: 'partial_success',
+      target: session.target,
+      summary: session.summary,
+      confirmation: session.confirmation,
+      ideExtension: {
+        required: true,
+        installed: false,
+        manualRequired: true,
+        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: [],
+      },
+      diagnostics: {
+        warnings: ['IDE extension installation still needs manual completion.'],
+        errors: [],
+        nextSteps: [],
+      },
+    }
+
+    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('partial_success')
+    expect(
+      consoleSpy.mock.calls.some(call =>
+        String(call[0]).includes('Complete the IDE extension install before verification'),
+      ),
+    ).toBe(true)
+    expect(
+      consoleSpy.mock.calls.some(call =>
+        String(call[0]).includes('code --install-extension inspecto.inspecto'),
+      ),
+    ).toBe(true)
+    expect(
+      consoleSpy.mock.calls.some(call =>
+        String(call[0]).includes('Start the local dev server with `pnpm dev`'),
+      ),
+    ).toBe(false)
   })
 })

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')
+    },
+  )
+})

package/tests/shared-capabilities.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest'
+import {
+  getDualModeProviderCapability,
+  getHostIdeLabel,
+  isSupportedHostIde,
+} from '@inspecto-dev/types'
+
+describe('shared capabilities', () => {
+  it('exposes shared host IDE labels', () => {
+    expect(getHostIdeLabel('vscode')).toBe('VS Code')
+    expect(getHostIdeLabel('cursor')).toBe('Cursor')
+    expect(getHostIdeLabel('trae')).toBe('Trae')
+    expect(getHostIdeLabel('trae-cn')).toBe('Trae CN')
+  })
+
+  it('exposes supported host IDE guards', () => {
+    expect(isSupportedHostIde('vscode')).toBe(true)
+    expect(isSupportedHostIde('cursor')).toBe(true)
+    expect(isSupportedHostIde('trae')).toBe(true)
+    expect(isSupportedHostIde('trae-cn')).toBe(true)
+    expect(isSupportedHostIde('unknown')).toBe(false)
+  })
+
+  it('exposes dual-mode provider metadata', () => {
+    expect(getDualModeProviderCapability('codex')).toEqual({
+      label: 'Codex',
+      extensionId: 'openai.chatgpt',
+      cliBin: 'codex',
+    })
+
+    expect(getDualModeProviderCapability('claude-code')).toEqual({
+      label: 'Claude Code',
+      extensionId: 'anthropic.claude-code',
+      cliBin: 'claude',
+    })
+
+    expect(getDualModeProviderCapability('gemini')).toEqual({
+      label: 'Gemini',
+      extensionId: 'google.geminicodeassist',
+      cliBin: 'gemini',
+    })
+
+    expect(getDualModeProviderCapability('copilot')).toBeUndefined()
+  })
+})