@inspecto-dev/cli 0.2.0-alpha.6 → 0.3.0-alpha.1

package/src/types.ts

@@ -11,6 +11,14 @@ export type BuildTool = 'vite' | 'webpack' | 'rspack' | 'rsbuild' | 'esbuild' |
 /** Machine-readable status for onboarding commands */
 export type CommandStatus = 'ok' | 'warning' | 'blocked' | 'error'
 
+/** Assistant-facing status for single-entry onboarding */
+export type OnboardStatus =
+  | 'success'
+  | 'partial_success'
+  | 'needs_target_selection'
+  | 'needs_confirmation'
+  | 'error'
+
 /** Structured message emitted by onboarding commands */
 export interface CommandMessage {
   code: string
@@ -54,6 +62,87 @@ export interface OnboardingContext {
   providers: OnboardingProvider[]
 }
 
+export interface OnboardingTargetCandidate {
+  packagePath: string
+  configPath: string
+  buildTool: BuildTool
+  frameworks: string[]
+  automaticInjection: boolean
+}
+
+export interface OnboardingTargetResolution {
+  status: 'resolved' | 'needs_selection'
+  selected?: OnboardingTargetCandidate
+  candidates: OnboardingTargetCandidate[]
+  reason: string
+}
+
+export interface OnboardingSummary {
+  headline: string
+  changes: string[]
+  risks: string[]
+  manualFollowUp: string[]
+}
+
+export interface OnboardingConfirmation {
+  required: boolean
+  reason?: string
+  question?: string
+}
+
+export interface OnboardingExecutionResult {
+  changedFiles: string[]
+  installedDependencies: string[]
+  selectedProviderDefault?: string
+  selectedIDE?: string
+  mutations: Mutation[]
+}
+
+export interface OnboardingDiagnostics {
+  warnings: string[]
+  errors: string[]
+  nextSteps: string[]
+}
+
+export interface OnboardingIdeExtensionStatus {
+  required: boolean
+  installed: boolean
+  manualRequired: boolean
+  installCommand?: string
+  marketplaceUrl?: string
+  openVsxUrl?: string
+}
+
+export interface OnboardingVerification {
+  available: boolean
+  devCommand?: string
+  message: string
+}
+
+export interface ResolvedOnboardingSession {
+  status: OnboardStatus
+  target: OnboardingTargetResolution
+  summary: OnboardingSummary
+  confirmation: OnboardingConfirmation
+  verification: OnboardingVerification
+  context: OnboardingContext
+  plan: PlanResult
+  projectRoot: string
+  selectedIDE?: { ide: string; supported: boolean } | null
+  providerDefault?: string
+}
+
+export interface OnboardCommandResult {
+  status: OnboardStatus
+  target: OnboardingTargetResolution
+  summary: OnboardingSummary
+  confirmation: OnboardingConfirmation
+  ideExtension?: OnboardingIdeExtensionStatus
+  verification?: OnboardingVerification
+  result?: OnboardingExecutionResult
+  diagnostics?: OnboardingDiagnostics
+}
+
 /** Machine-readable detection output for skill-first onboarding */
 export interface DetectionResult {
   status: CommandStatus

package/tests/apply.test.ts

@@ -121,7 +121,7 @@ describe('apply onboarding flow', () => {
       'pnpm add -D @inspecto-dev/plugin @inspecto-dev/core',
       '/repo',
     )
-    expect(astInjectorUtils.injectPlugin).toHaveBeenCalledWith('/repo', supportedBuild, false)
+    expect(astInjectorUtils.injectPlugin).toHaveBeenCalledWith('/repo', supportedBuild, false, false)
     expect(fsUtils.writeJSON).toHaveBeenCalledWith('/repo/.inspecto/settings.local.json', {
       ide: 'vscode',
       'provider.default': 'codex.extension',
@@ -534,4 +534,50 @@ describe('apply onboarding flow', () => {
     )
     expect(fsUtils.writeJSON).toHaveBeenCalledWith('/repo/.inspecto/prompts.local.json', [])
   })
+
+  it('prints the same short 3-step success guide when apply finishes cleanly', async () => {
+    const context: OnboardingContext = {
+      root: '/repo',
+      packageManager: 'pnpm',
+      buildTools: {
+        supported: [supportedBuild],
+        unsupported: [],
+      },
+      frameworks: {
+        supported: ['react'],
+        unsupported: [],
+      },
+      ides: [{ ide: 'vscode', supported: true }],
+      providers: [{ id: 'codex', label: 'Codex CLI', supported: true, preferredMode: 'cli' }],
+    }
+
+    const planResult: PlanResult = {
+      status: 'ok',
+      warnings: [],
+      blockers: [],
+      strategy: 'supported',
+      actions: [],
+      defaults: {
+        provider: 'codex',
+        ide: 'vscode',
+        shared: false,
+        extension: true,
+      },
+    }
+
+    vi.mocked(onboardingContext.buildOnboardingContext).mockResolvedValue(context)
+    vi.mocked(planner.createPlanResult).mockReturnValue(planResult)
+
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await apply()
+
+    const output = consoleSpy.mock.calls.flatMap(call => call.map(value => String(value)))
+    expect(output.some(line => line.includes('Ready! Inspecto is set up.'))).toBe(true)
+    expect(output.some(line => line.includes('1. Start or restart your dev server.'))).toBe(true)
+    expect(output.some(line => line.includes('2. Open your app in the browser.'))).toBe(true)
+    expect(output.some(line => line.includes('3. Hold Alt + Click any element to inspect.'))).toBe(
+      true,
+    )
+  })
 })

package/tests/init.test.ts

@@ -330,4 +330,35 @@ describe('init in monorepo roots', () => {
       output.some(line => line.includes('Ready! Hold Alt + Click any element to inspect.')),
     ).toBe(false)
   })
+
+  it('prints a short 3-step success guide after automatic setup succeeds', async () => {
+    vi.mocked(buildToolUtils.detectBuildTools).mockResolvedValue({
+      supported: [
+        {
+          tool: 'vite',
+          configPath: 'vite.config.ts',
+          label: 'Vite (vite.config.ts)',
+        },
+      ],
+      unsupported: [],
+    })
+
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await init({
+      shared: false,
+      skipInstall: false,
+      dryRun: false,
+      noExtension: false,
+      force: false,
+    })
+
+    const output = consoleSpy.mock.calls.flatMap(call => call.map(value => String(value)))
+    expect(output.some(line => line.includes('Ready! Inspecto is set up.'))).toBe(true)
+    expect(output.some(line => line.includes('1. Start or restart your dev server.'))).toBe(true)
+    expect(output.some(line => line.includes('2. Open your app in the browser.'))).toBe(true)
+    expect(output.some(line => line.includes('3. Hold Alt + Click any element to inspect.'))).toBe(
+      true,
+    )
+  })
 })

package/tests/install-wrapper.test.ts

@@ -0,0 +1,76 @@
+import { execFile } from 'node:child_process'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { promisify } from 'node:util'
+import { afterEach, describe, expect, it } from 'vitest'
+
+const execFileAsync = promisify(execFile)
+
+describe('assistant integration bootstrap wrapper', () => {
+  const tempDirs: string[] = []
+
+  afterEach(async () => {
+    await Promise.all(tempDirs.map(dir => fs.rm(dir, { recursive: true, force: true })))
+    tempDirs.length = 0
+  })
+
+  it('falls back to raw asset download and still honors --force', async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'inspecto-wrapper-'))
+    tempDirs.push(tempRoot)
+
+    const fakeBin = path.join(tempRoot, 'bin')
+    await fs.mkdir(fakeBin, { recursive: true })
+    await fs.mkdir(path.join(tempRoot, '.github'), { recursive: true })
+    await fs.writeFile(
+      path.join(tempRoot, '.github/copilot-instructions.md'),
+      'old content\n',
+      'utf8',
+    )
+
+    await fs.writeFile(path.join(fakeBin, 'npx'), '#!/usr/bin/env bash\nexit 127\n', 'utf8')
+    await fs.chmod(path.join(fakeBin, 'npx'), 0o755)
+
+    await fs.writeFile(
+      path.join(fakeBin, 'curl'),
+      [
+        '#!/usr/bin/env bash',
+        'set -euo pipefail',
+        'out=""',
+        'while [[ $# -gt 0 ]]; do',
+        '  case "$1" in',
+        '    -o)',
+        '      out="$2"',
+        '      shift 2',
+        '      ;;',
+        '    *)',
+        '      shift',
+        '      ;;',
+        '  esac',
+        'done',
+        'printf "downloaded from wrapper\n" > "$out"',
+      ].join('\n'),
+      'utf8',
+    )
+    await fs.chmod(path.join(fakeBin, 'curl'), 0o755)
+
+    const scriptPath = path.resolve(
+      __dirname,
+      '../../../assistant-integrations/scripts/install.sh',
+    )
+
+    await execFileAsync('bash', [scriptPath, 'copilot', '--force'], {
+      cwd: tempRoot,
+      env: {
+        ...process.env,
+        PATH: `${fakeBin}:${process.env.PATH ?? ''}`,
+      },
+    })
+
+    const installed = await fs.readFile(
+      path.join(tempRoot, '.github/copilot-instructions.md'),
+      'utf8',
+    )
+    expect(installed).toBe('downloaded from wrapper\n')
+  })
+})

package/tests/integration-install.test.ts

@@ -0,0 +1,294 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const writeFileMock = vi.fn()
+const existsMock = vi.fn()
+const chmodMock = vi.fn()
+const logMock = {
+  header: vi.fn(),
+  info: vi.fn(),
+  success: vi.fn(),
+  warn: vi.fn(),
+  hint: vi.fn(),
+  ready: vi.fn(),
+  error: vi.fn(),
+  blank: vi.fn(),
+}
+
+vi.mock('../src/utils/fs.js', () => ({
+  writeFile: writeFileMock,
+  exists: existsMock,
+}))
+
+vi.mock('node:fs/promises', () => ({
+  default: {
+    chmod: chmodMock,
+  },
+}))
+
+vi.mock('node:os', () => ({
+  homedir: () => '/Users/tester',
+}))
+
+vi.mock('../src/utils/logger.js', () => ({
+  log: logMock,
+}))
+
+describe('integration install', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.clearAllMocks()
+    existsMock.mockResolvedValue(false)
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        ok: true,
+        text: async () => '# mock asset',
+        status: 200,
+        statusText: 'OK',
+      }),
+    )
+  })
+
+  it('installs the Claude Code skill into the user skill directory', async () => {
+    const { installIntegration } = await import('../src/commands/integration-install.js')
+
+    await installIntegration('claude-code', { scope: 'user' })
+
+    expect(writeFileMock).toHaveBeenCalledWith(
+      '/Users/tester/.claude/skills/inspecto-onboarding-claude-code/SKILL.md',
+      '# mock asset',
+    )
+    expect(writeFileMock).toHaveBeenCalledWith(
+      '/Users/tester/.claude/skills/inspecto-onboarding-claude-code/agents/openai.yaml',
+      '# mock asset',
+    )
+    expect(writeFileMock).toHaveBeenCalledWith(
+      '/Users/tester/.claude/skills/inspecto-onboarding-claude-code/scripts/run-inspecto.sh',
+      '# mock asset',
+    )
+    expect(chmodMock).toHaveBeenCalledWith(
+      '/Users/tester/.claude/skills/inspecto-onboarding-claude-code/scripts/run-inspecto.sh',
+      0o755,
+    )
+  })
+
+  it('installs the Codex skill into the Codex skill directory', async () => {
+    const { installIntegration } = await import('../src/commands/integration-install.js')
+
+    await installIntegration('codex')
+
+    expect(writeFileMock).toHaveBeenCalledWith(
+      '/Users/tester/.codex/skills/inspecto-onboarding-codex/SKILL.md',
+      '# mock asset',
+    )
+    expect(writeFileMock).toHaveBeenCalledWith(
+      '/Users/tester/.codex/skills/inspecto-onboarding-codex/agents/openai.yaml',
+      '# mock asset',
+    )
+    expect(writeFileMock).toHaveBeenCalledWith(
+      '/Users/tester/.codex/skills/inspecto-onboarding-codex/scripts/run-inspecto.sh',
+      '# mock asset',
+    )
+    expect(chmodMock).toHaveBeenCalledWith(
+      '/Users/tester/.codex/skills/inspecto-onboarding-codex/scripts/run-inspecto.sh',
+      0o755,
+    )
+  })
+
+  it('installs the Cursor AGENTS fallback when agents mode is selected', 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')
+  })
+
+  it('refuses a multi-file Claude install before writing anything when one target already exists', async () => {
+    const { installIntegration } = await import('../src/commands/integration-install.js')
+
+    existsMock.mockImplementation(async filePath => {
+      return (
+        filePath ===
+        '/Users/tester/.claude/skills/inspecto-onboarding-claude-code/agents/openai.yaml'
+      )
+    })
+
+    await expect(installIntegration('claude-code', { scope: 'user' })).rejects.toThrow(
+      'Refusing to overwrite existing file',
+    )
+
+    expect(writeFileMock).not.toHaveBeenCalled()
+    expect(chmodMock).not.toHaveBeenCalled()
+  })
+
+  it('downloads all Claude assets before writing any file', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        text: async () => '# skill',
+        status: 200,
+        statusText: 'OK',
+      })
+      .mockResolvedValueOnce({
+        ok: false,
+        text: async () => '',
+        status: 503,
+        statusText: 'Unavailable',
+      })
+
+    vi.stubGlobal('fetch', fetchMock)
+
+    const { installIntegration } = await import('../src/commands/integration-install.js')
+
+    await expect(installIntegration('claude-code', { scope: 'user' })).rejects.toThrow(
+      'Failed to download',
+    )
+
+    expect(writeFileMock).not.toHaveBeenCalled()
+    expect(chmodMock).not.toHaveBeenCalled()
+  })
+
+  it('surfaces the asset URL when fetch itself fails', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('fetch failed')))
+
+    const { installIntegration } = await import('../src/commands/integration-install.js')
+
+    await expect(installIntegration('codex')).rejects.toThrow(
+      'Failed to download https://raw.githubusercontent.com/inspecto-dev/inspecto/main/skills/inspecto-onboarding-codex/SKILL.md: fetch failed',
+    )
+
+    expect(writeFileMock).not.toHaveBeenCalled()
+    expect(chmodMock).not.toHaveBeenCalled()
+  })
+
+  it('lists supported integrations with their preferred install targets', async () => {
+    const { listIntegrationManifests } = await import('../src/commands/integration-install.js')
+
+    expect(listIntegrationManifests()).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          assistant: 'codex',
+          type: 'native-skill',
+          installTarget: '~/.codex/skills/',
+          cliSupported: true,
+        }),
+        expect.objectContaining({
+          assistant: 'claude-code',
+          type: 'native-skill',
+          installTarget: '.claude/skills/ or ~/.claude/skills/',
+        }),
+        expect.objectContaining({
+          assistant: 'copilot',
+          type: 'instruction-template',
+          installTarget: '.github/copilot-instructions.md or AGENTS.md',
+        }),
+      ]),
+    )
+  })
+
+  it('describes the resolved install targets for a selected assistant variant', async () => {
+    const { describeIntegration } = await import('../src/commands/integration-install.js')
+
+    expect(describeIntegration('claude-code', { scope: 'user' })).toMatchObject({
+      assistant: 'claude-code',
+      targets: [
+        '/Users/tester/.claude/skills/inspecto-onboarding-claude-code/SKILL.md',
+        '/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',
+    })
+  })
+
+  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({
+      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',
+      ],
+      preferredInstall: 'npx @inspecto-dev/cli integrations install codex',
+    })
+  })
+
+  it('prints integration paths without using post-install hints', async () => {
+    const { printIntegrationPath } = await import('../src/commands/integration-install.js')
+
+    printIntegrationPath('claude-code', { scope: 'user' })
+
+    expect(logMock.info).toHaveBeenCalledWith(
+      '/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',
+    )
+    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)
+
+    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() }))
+
+    const { runCli } = await import('../src/bin.js')
+
+    await runCli(['node', 'inspecto', 'integrations', 'list', 'extra'])
+    await runCli(['node', 'inspecto', 'integrations', 'path', 'claude-code', '--force'])
+
+    expect(logMock.error).toHaveBeenCalledWith(
+      'The `list` subcommand does not accept assistant names, --scope, --mode, or --force.',
+    )
+    expect(logMock.error).toHaveBeenCalledWith('The `path` subcommand does not support `--force`.')
+    expect(exitSpy).toHaveBeenCalledWith(1)
+
+    exitSpy.mockRestore()
+  })
+
+  it('wires the nested CLI command to the integration installer', async () => {
+    const installCommand = vi.fn().mockResolvedValue(undefined)
+    const listCommand = vi.fn().mockResolvedValue(undefined)
+    const pathCommand = vi.fn().mockResolvedValue(undefined)
+
+    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-install.js', () => ({
+      installIntegration: installCommand,
+      printIntegrationList: listCommand,
+      printIntegrationPath: pathCommand,
+    }))
+
+    const { runCli } = await import('../src/bin.js')
+
+    await runCli([
+      'node',
+      'inspecto',
+      'integrations',
+      'install',
+      'copilot',
+      '--mode',
+      'agents',
+      '--force',
+    ])
+
+    await runCli(['node', 'inspecto', 'integrations', 'list'])
+    await runCli(['node', 'inspecto', 'integrations', 'path', 'claude-code', '--scope', 'user'])
+
+    expect(installCommand).toHaveBeenCalledWith('copilot', { mode: 'agents', force: true })
+    expect(listCommand).toHaveBeenCalledWith()
+    expect(pathCommand).toHaveBeenCalledWith('claude-code', { scope: 'user' })
+  })
+})