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

package/src/commands/integration-install.ts

@@ -0,0 +1,452 @@
+import fs from 'node:fs/promises'
+import { homedir } from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { exists, writeFile } from '../utils/fs.js'
+import { log } from '../utils/logger.js'
+
+const REPO_RAW_BASE = 'https://raw.githubusercontent.com/inspecto-dev/inspecto/main'
+
+type AssistantId = 'codex' | 'claude-code' | 'copilot' | 'cursor' | 'gemini' | 'trae' | 'coco'
+type ClaudeScope = 'project' | 'user'
+type CopilotMode = 'instructions' | 'agents'
+type CursorMode = 'rules' | 'agents'
+
+interface DownloadAsset {
+  source: string
+  target: string
+  executable?: boolean
+  localSource?: string
+}
+
+export interface IntegrationManifest {
+  assistant: string
+  type:
+    | 'native-skill'
+    | 'instruction-template'
+    | 'rule-template'
+    | 'context-template'
+    | 'compatibility-template'
+  installTarget: string
+  preferredInstall: string
+  cliSupported: boolean
+}
+
+export interface IntegrationDescription {
+  assistant: string
+  type: IntegrationManifest['type']
+  targets: string[]
+  preferredInstall: string
+  cliSupported: boolean
+}
+
+export interface InstallIntegrationOptions {
+  scope?: ClaudeScope
+  mode?: CopilotMode | CursorMode
+  force?: boolean
+}
+
+interface InstallPlan {
+  assets: DownloadAsset[]
+  successMessage: string
+  nextStep: string
+}
+
+const INTEGRATION_MANIFESTS: IntegrationManifest[] = [
+  {
+    assistant: 'codex',
+    type: 'native-skill',
+    installTarget: '~/.codex/skills/',
+    preferredInstall: 'npx @inspecto-dev/cli integrations install codex',
+    cliSupported: true,
+  },
+  {
+    assistant: 'claude-code',
+    type: 'native-skill',
+    installTarget: '.claude/skills/ or ~/.claude/skills/',
+    preferredInstall: 'npx @inspecto-dev/cli integrations install claude-code --scope project',
+    cliSupported: true,
+  },
+  {
+    assistant: 'copilot',
+    type: 'instruction-template',
+    installTarget: '.github/copilot-instructions.md or AGENTS.md',
+    preferredInstall: 'npx @inspecto-dev/cli integrations install copilot',
+    cliSupported: true,
+  },
+  {
+    assistant: 'cursor',
+    type: 'rule-template',
+    installTarget: '.cursor/rules/inspecto-onboarding.mdc or AGENTS.md',
+    preferredInstall: 'npx @inspecto-dev/cli integrations install cursor --mode rules',
+    cliSupported: true,
+  },
+  {
+    assistant: 'gemini',
+    type: 'context-template',
+    installTarget: 'GEMINI.md',
+    preferredInstall: 'npx @inspecto-dev/cli integrations install gemini',
+    cliSupported: true,
+  },
+  {
+    assistant: 'trae',
+    type: 'compatibility-template',
+    installTarget: 'AGENTS.md',
+    preferredInstall: 'npx @inspecto-dev/cli integrations install trae',
+    cliSupported: true,
+  },
+  {
+    assistant: 'coco',
+    type: 'compatibility-template',
+    installTarget: 'AGENTS.md',
+    preferredInstall: 'npx @inspecto-dev/cli integrations install coco',
+    cliSupported: true,
+  },
+]
+
+export async function installIntegration(
+  assistant: string,
+  options: InstallIntegrationOptions = {},
+): Promise<void> {
+  const plan = resolveInstallPlan(assistant, options)
+
+  log.header('Inspecto Integration Install')
+
+  for (const asset of plan.assets) {
+    if ((await exists(asset.target)) && !options.force) {
+      throw new Error(
+        `Refusing to overwrite existing file: ${asset.target}. Re-run with --force if you want to replace it.`,
+      )
+    }
+  }
+
+  const downloadedAssets = [] as Array<{ asset: DownloadAsset; content: string }>
+
+  for (const asset of plan.assets) {
+    const content = await loadAsset(asset)
+    downloadedAssets.push({ asset, content })
+  }
+
+  for (const { asset, content } of downloadedAssets) {
+    await writeFile(asset.target, content)
+
+    if (asset.executable) {
+      await fs.chmod(asset.target, 0o755)
+    }
+  }
+
+  log.success(plan.successMessage)
+  log.hint(plan.nextStep)
+}
+
+export function listIntegrationManifests(): IntegrationManifest[] {
+  return INTEGRATION_MANIFESTS.map(manifest => ({ ...manifest }))
+}
+
+export function describeIntegration(
+  assistant: string,
+  options: InstallIntegrationOptions = {},
+): IntegrationDescription {
+  const manifest = getIntegrationManifest(assistant)
+
+  const targets = manifest.cliSupported
+    ? resolveInstallPlan(assistant, options).assets.map(asset => asset.target)
+    : [manifest.installTarget]
+
+  return {
+    assistant: manifest.assistant,
+    type: manifest.type,
+    targets,
+    preferredInstall: manifest.preferredInstall,
+    cliSupported: manifest.cliSupported,
+  }
+}
+
+export function printIntegrationList(): void {
+  log.header('Inspecto Integrations')
+  for (const manifest of INTEGRATION_MANIFESTS) {
+    const support = manifest.cliSupported ? 'CLI' : 'native installer'
+    log.info(`${manifest.assistant} — ${manifest.type} — ${manifest.installTarget} — ${support}`)
+  }
+}
+
+export function printIntegrationPath(
+  assistant: string,
+  options: InstallIntegrationOptions = {},
+): void {
+  const description = describeIntegration(assistant, options)
+
+  log.header(`Inspecto Integration Paths: ${description.assistant}`)
+  for (const target of description.targets) {
+    log.info(target)
+  }
+
+  if (description.cliSupported) {
+    log.hint(`Preferred install: ${description.preferredInstall}`)
+  } else {
+    log.hint(`Native install required: ${description.preferredInstall}`)
+  }
+}
+
+function resolveInstallPlan(assistant: string, options: InstallIntegrationOptions): InstallPlan {
+  switch (assistant as AssistantId) {
+    case 'codex':
+      return resolveCodexPlan(options)
+    case 'claude-code':
+      return resolveClaudeCodePlan(options)
+    case 'copilot':
+      return resolveCopilotPlan(options)
+    case 'cursor':
+      return resolveCursorPlan(options)
+    case 'gemini':
+      return {
+        assets: [
+          {
+            source: `${REPO_RAW_BASE}/assistant-integrations/gemini/GEMINI.md`,
+            target: 'GEMINI.md',
+            localSource: 'assistant-integrations/gemini/GEMINI.md',
+          },
+        ],
+        successMessage: 'Installed Gemini context to GEMINI.md',
+        nextStep: 'Start a new Gemini CLI session.',
+      }
+    case 'trae':
+      return {
+        assets: [
+          {
+            source: `${REPO_RAW_BASE}/assistant-integrations/trae/AGENTS.md`,
+            target: 'AGENTS.md',
+            localSource: 'assistant-integrations/trae/AGENTS.md',
+          },
+        ],
+        successMessage: 'Installed Trae compatibility instructions to AGENTS.md',
+        nextStep: 'Open a new Trae chat.',
+      }
+    case 'coco':
+      return {
+        assets: [
+          {
+            source: `${REPO_RAW_BASE}/assistant-integrations/coco/AGENTS.md`,
+            target: 'AGENTS.md',
+            localSource: 'assistant-integrations/coco/AGENTS.md',
+          },
+        ],
+        successMessage: 'Installed Coco compatibility instructions to AGENTS.md',
+        nextStep: 'Start a new Coco session.',
+      }
+    default:
+      throw new Error(`Unknown assistant: ${assistant}`)
+  }
+}
+
+function getIntegrationManifest(assistant: string): IntegrationManifest {
+  const manifest = INTEGRATION_MANIFESTS.find(item => item.assistant === assistant)
+
+  if (!manifest) {
+    throw new Error(
+      `Unknown assistant: ${assistant}. Run 'inspecto integrations list' to see available targets.`,
+    )
+  }
+
+  return manifest
+}
+
+function resolveCodexPlan(options: InstallIntegrationOptions): InstallPlan {
+  if (options.scope !== undefined) {
+    throw new Error('`--scope` is not supported for codex.')
+  }
+
+  if (options.mode !== undefined) {
+    throw new Error('`--mode` is not supported for codex.')
+  }
+
+  const baseDir = path.join(homedir(), '.codex/skills/inspecto-onboarding-codex')
+
+  return {
+    assets: [
+      {
+        source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-codex/SKILL.md`,
+        target: path.join(baseDir, 'SKILL.md'),
+        localSource: 'skills/inspecto-onboarding-codex/SKILL.md',
+      },
+      {
+        source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-codex/agents/openai.yaml`,
+        target: path.join(baseDir, 'agents/openai.yaml'),
+        localSource: 'skills/inspecto-onboarding-codex/agents/openai.yaml',
+      },
+      {
+        source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-codex/scripts/run-inspecto.sh`,
+        target: path.join(baseDir, 'scripts/run-inspecto.sh'),
+        executable: true,
+        localSource: 'skills/inspecto-onboarding-codex/scripts/run-inspecto.sh',
+      },
+    ],
+    successMessage: `Installed Codex skill to ${baseDir}`,
+    nextStep: 'Restart Codex or start a new Codex session to load the skill.',
+  }
+}
+
+function resolveClaudeCodePlan(options: InstallIntegrationOptions): InstallPlan {
+  const scope = options.scope ?? 'project'
+  const unsupportedMode = options.mode !== undefined
+
+  if (unsupportedMode) {
+    throw new Error(
+      '`--mode` is not supported for claude-code. Use `--scope project|user` instead.',
+    )
+  }
+
+  if (scope !== 'project' && scope !== 'user') {
+    throw new Error(`Unknown Claude Code scope: ${scope}`)
+  }
+
+  const baseDir =
+    scope === 'user'
+      ? path.join(homedir(), '.claude/skills/inspecto-onboarding-claude-code')
+      : '.claude/skills/inspecto-onboarding-claude-code'
+
+  return {
+    assets: [
+      {
+        source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-claude-code/SKILL.md`,
+        target: path.join(baseDir, 'SKILL.md'),
+        localSource: 'skills/inspecto-onboarding-claude-code/SKILL.md',
+      },
+      {
+        source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-claude-code/agents/openai.yaml`,
+        target: path.join(baseDir, 'agents/openai.yaml'),
+        localSource: 'skills/inspecto-onboarding-claude-code/agents/openai.yaml',
+      },
+      {
+        source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-claude-code/scripts/run-inspecto.sh`,
+        target: path.join(baseDir, 'scripts/run-inspecto.sh'),
+        executable: true,
+        localSource: 'skills/inspecto-onboarding-claude-code/scripts/run-inspecto.sh',
+      },
+    ],
+    successMessage: `Installed Claude Code skill to ${baseDir}`,
+    nextStep: 'Restart Claude Code to load the new skill.',
+  }
+}
+
+function resolveCopilotPlan(options: InstallIntegrationOptions): InstallPlan {
+  const mode = options.mode ?? 'instructions'
+
+  if (options.scope !== undefined) {
+    throw new Error(
+      '`--scope` is not supported for copilot. Use `--mode instructions|agents` instead.',
+    )
+  }
+
+  switch (mode) {
+    case 'instructions':
+      return {
+        assets: [
+          {
+            source: `${REPO_RAW_BASE}/assistant-integrations/copilot/.github/copilot-instructions.md`,
+            target: '.github/copilot-instructions.md',
+            localSource: 'assistant-integrations/copilot/.github/copilot-instructions.md',
+          },
+        ],
+        successMessage: 'Installed Copilot instructions to .github/copilot-instructions.md',
+        nextStep: 'Open a new Copilot chat or agent session.',
+      }
+    case 'agents':
+      return {
+        assets: [
+          {
+            source: `${REPO_RAW_BASE}/assistant-integrations/copilot/AGENTS.md`,
+            target: 'AGENTS.md',
+            localSource: 'assistant-integrations/copilot/AGENTS.md',
+          },
+        ],
+        successMessage: 'Installed Copilot compatibility instructions to AGENTS.md',
+        nextStep: 'Open a new Copilot chat or agent session.',
+      }
+    default:
+      throw new Error(`Unknown Copilot mode: ${mode}`)
+  }
+}
+
+function resolveCursorPlan(options: InstallIntegrationOptions): InstallPlan {
+  const mode = options.mode ?? 'rules'
+
+  if (options.scope !== undefined) {
+    throw new Error('`--scope` is not supported for cursor. Use `--mode rules|agents` instead.')
+  }
+
+  switch (mode) {
+    case 'rules':
+      return {
+        assets: [
+          {
+            source: `${REPO_RAW_BASE}/assistant-integrations/cursor/.cursor/rules/inspecto-onboarding.mdc`,
+            target: '.cursor/rules/inspecto-onboarding.mdc',
+            localSource: 'assistant-integrations/cursor/.cursor/rules/inspecto-onboarding.mdc',
+          },
+        ],
+        successMessage: 'Installed Cursor rule to .cursor/rules/inspecto-onboarding.mdc',
+        nextStep: 'Open a new Cursor chat.',
+      }
+    case 'agents':
+      return {
+        assets: [
+          {
+            source: `${REPO_RAW_BASE}/assistant-integrations/cursor/AGENTS.md`,
+            target: 'AGENTS.md',
+            localSource: 'assistant-integrations/cursor/AGENTS.md',
+          },
+        ],
+        successMessage: 'Installed Cursor compatibility instructions to AGENTS.md',
+        nextStep: 'Open a new Cursor chat.',
+      }
+    default:
+      throw new Error(`Unknown Cursor mode: ${mode}`)
+  }
+}
+
+async function loadAsset(asset: DownloadAsset): Promise<string> {
+  if (asset.localSource) {
+    const localPath = await resolveBundledAssetPath(asset.localSource)
+    if (localPath) {
+      return await fs.readFile(localPath, 'utf-8')
+    }
+  }
+
+  return await downloadAsset(asset.source)
+}
+
+async function resolveBundledAssetPath(relativePath: string): Promise<string | null> {
+  const startDir = path.dirname(fileURLToPath(import.meta.url))
+  let currentDir = startDir
+
+  for (let depth = 0; depth < 8; depth += 1) {
+    const candidate = path.join(currentDir, relativePath)
+    if (await exists(candidate)) {
+      return candidate
+    }
+
+    const parent = path.dirname(currentDir)
+    if (parent === currentDir) break
+    currentDir = parent
+  }
+
+  return null
+}
+
+async function downloadAsset(source: string): Promise<string> {
+  let response: Response
+
+  try {
+    response = await fetch(source)
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new Error(`Failed to download ${source}: ${reason}`)
+  }
+
+  if (!response.ok) {
+    throw new Error(`Failed to download ${source}: ${response.status} ${response.statusText}`)
+  }
+
+  return await response.text()
+}

package/src/commands/onboard.ts

@@ -0,0 +1,62 @@
+import { resolveOnboardingSession, applyResolvedOnboardingSession, buildDeferredOnboardResult } from '../onboarding/session.js'
+import { log } from '../utils/logger.js'
+import { writeCommandOutput } from '../utils/output.js'
+import type { OnboardCommandResult } from '../types.js'
+
+export interface OnboardCommandOptions {
+  json?: boolean
+  target?: string
+  yes?: boolean
+  shared?: boolean
+  skipInstall?: boolean
+  dryRun?: boolean
+  noExtension?: boolean
+}
+
+function printOnboardResult(result: OnboardCommandResult): void {
+  log.header('Inspecto Onboard')
+  log.info(`Status: ${result.status}`)
+  log.info(result.summary.headline)
+
+  for (const change of result.summary.changes) {
+    log.hint(change)
+  }
+  for (const step of result.diagnostics?.nextSteps ?? []) {
+    log.warn(step)
+  }
+  if (result.confirmation.required && result.confirmation.question) {
+    log.warn(result.confirmation.question)
+  }
+
+  const extensionReady =
+    !result.ideExtension?.required ||
+    (result.ideExtension.installed && !result.ideExtension.manualRequired)
+
+  if (
+    extensionReady &&
+    (result.status === 'success' || result.status === 'partial_success') &&
+    result.verification?.message
+  ) {
+    log.info(result.verification.message)
+  }
+}
+
+export async function onboard(options: OnboardCommandOptions = {}): Promise<OnboardCommandResult> {
+  const root = process.cwd()
+  const session = await resolveOnboardingSession(root, options)
+
+  if (
+    session.status === 'error' ||
+    session.status === 'needs_target_selection' ||
+    session.status === 'needs_confirmation'
+  ) {
+    return writeCommandOutput(
+      buildDeferredOnboardResult(session),
+      options.json ?? false,
+      printOnboardResult,
+    )
+  }
+
+  const result = await applyResolvedOnboardingSession(session, options)
+  return writeCommandOutput(result, options.json ?? false, printOnboardResult)
+}

package/src/index.ts

@@ -2,6 +2,7 @@ export { apply } from './commands/apply.js'
 export { detect } from './commands/detect.js'
 export { init } from './commands/init.js'
 export { collectDoctorResult, doctor } from './commands/doctor.js'
+export { onboard } from './commands/onboard.js'
 export { plan } from './commands/plan.js'
 export { teardown } from './commands/teardown.js'
 export { writeCommandOutput, reportCommandError } from './utils/output.js'
@@ -12,5 +13,8 @@ export type {
   InstallLock,
   DoctorDiagnostic,
   DoctorResult,
+  OnboardStatus,
+  OnboardCommandResult,
+  ResolvedOnboardingSession,
 } from './types.js'
 export type { Framework } from './detect/framework.js'

package/src/inject/ast-injector.ts

@@ -25,7 +25,9 @@ function printManualInstructions(
   strategy: InjectStrategy | undefined,
   detection: BuildToolDetection,
   reason: string,
+  quiet = false,
 ) {
+  if (quiet) return
   log.warn(`Could not automatically configure ${detection.configPath}`)
   log.hint(`(reason: ${reason})`)
   log.blank()
@@ -73,6 +75,7 @@ export async function injectPlugin(
   root: string,
   detection: BuildToolDetection,
   dryRun: boolean,
+  quiet = false,
 ): Promise<InjectionResult> {
   const configPath = path.join(root, detection.configPath)
   const mutations: Mutation[] = []
@@ -82,13 +85,15 @@ export async function injectPlugin(
   // Step 1: Read config file to check existence and idempotency
   const content = await readFile(configPath)
   if (!content) {
-    printManualInstructions(strategy, detection, 'config file not readable')
+    printManualInstructions(strategy, detection, 'config file not readable', quiet)
     return { success: false, mutations, failureReason: 'config file not readable' }
   }
 
   // Step 2: Idempotency check
   if (isAlreadyInjected(content)) {
-    log.success(`Plugin already configured in ${detection.configPath} (skipped)`)
+    if (!quiet) {
+      log.success(`Plugin already configured in ${detection.configPath} (skipped)`)
+    }
 
     mutations.push({
       type: 'file_modified',
@@ -104,13 +109,16 @@ export async function injectPlugin(
       strategy,
       detection,
       `No injection strategy found for ${detection.tool}`,
+      quiet,
     )
     return { success: false, mutations, failureReason: 'No strategy found' }
   }
 
   // Step 3: Automatic configuration
   if (dryRun) {
-    log.dryRun(`Would automatically configure plugin in ${detection.configPath}`)
+    if (!quiet) {
+      log.dryRun(`Would automatically configure plugin in ${detection.configPath}`)
+    }
     return { success: true, mutations: [] }
   }
 
@@ -132,7 +140,9 @@ export async function injectPlugin(
       description: 'Automatically configured inspecto() plugin',
     })
 
-    log.success(`Configured plugin in ${detection.configPath}`)
+    if (!quiet) {
+      log.success(`Configured plugin in ${detection.configPath}`)
+    }
     return { success: true, mutations }
   } catch (err) {
     // Graceback degradation
@@ -140,6 +150,7 @@ export async function injectPlugin(
       strategy,
       detection,
       `Automatic configuration unavailable: ${err instanceof Error ? err.message : String(err)}`,
+      quiet,
     )
     return {
       success: false,