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

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,50 @@
+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)
+  }
+}
+
+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/commands/plan.ts

@@ -0,0 +1,41 @@
+import { log } from '../utils/logger.js'
+import { writeCommandOutput } from '../utils/output.js'
+import { buildOnboardingContext } from '../onboarding/context.js'
+import { createPlanResult } from '../onboarding/planner.js'
+import type { PlanResult } from '../types.js'
+
+function printPlanResult(result: PlanResult): void {
+  log.header('Inspecto Plan')
+  log.info(`Status: ${result.status}`)
+  log.info(`Strategy: ${result.strategy}`)
+
+  if (result.defaults.provider) {
+    log.info(`Default provider: ${result.defaults.provider}`)
+  }
+  if (result.defaults.ide) {
+    log.info(`Default IDE: ${result.defaults.ide}`)
+  }
+  log.info(`Shared mode: ${result.defaults.shared ? 'enabled' : 'disabled'}`)
+  log.info(`Extension mode: ${result.defaults.extension ? 'enabled' : 'disabled'}`)
+
+  if (result.actions.length > 0) {
+    log.blank()
+    log.info('Actions:')
+    for (const action of result.actions) {
+      log.hint(`${action.type}: ${action.target} — ${action.description}`)
+    }
+  }
+
+  for (const blocker of result.blockers) {
+    log.error(blocker.message)
+  }
+  for (const warning of result.warnings) {
+    log.warn(warning.message)
+  }
+}
+
+export async function plan(json = false): Promise<PlanResult> {
+  const context = await buildOnboardingContext(process.cwd())
+  const result = createPlanResult(context)
+  return writeCommandOutput(result, json, printPlanResult)
+}

package/src/detect/build-tool.ts

@@ -5,8 +5,9 @@
 // Recognized but unsupported: Next.js / Nuxt / Remix / Astro / SvelteKit
 // ============================================================
 import path from 'node:path'
+import fs from 'node:fs/promises'
 import { createRequire } from 'node:module'
-import { exists, readJSON } from '../utils/fs.js'
+import { exists, readFile, readJSON } from '../utils/fs.js'
 import type { BuildTool, BuildToolDetection } from '../types.js'
 
 interface PackageJSON {
@@ -128,6 +129,89 @@ function createTargets(root: string, packagePaths?: string[]): DetectionTarget[]
   }))
 }
 
+async function getWorkspacePackagePatterns(root: string): Promise<string[]> {
+  const pkg = await readJSON<{ workspaces?: string[] | { packages?: string[] } }>(
+    path.join(root, 'package.json'),
+  )
+
+  const workspaces = pkg?.workspaces
+  if (Array.isArray(workspaces)) {
+    return workspaces
+  }
+
+  if (workspaces && Array.isArray(workspaces.packages)) {
+    return workspaces.packages
+  }
+
+  const pnpmWorkspace = await readFile(path.join(root, 'pnpm-workspace.yaml'))
+  if (!pnpmWorkspace) {
+    return []
+  }
+
+  const patterns: string[] = []
+  for (const line of pnpmWorkspace.split('\n')) {
+    const match = line.match(/^\s*-\s*['"]?([^'"]+)['"]?\s*$/)
+    if (match?.[1]) {
+      patterns.push(match[1])
+    }
+  }
+
+  return patterns
+}
+
+async function expandWorkspacePattern(root: string, pattern: string): Promise<string[]> {
+  const normalized = pattern.replace(/\\/g, '/').replace(/\/$/, '')
+  if (!normalized || normalized.startsWith('!')) {
+    return []
+  }
+
+  if (!normalized.includes('*')) {
+    return (await exists(path.join(root, normalized))) ? [normalized] : []
+  }
+
+  const starIndex = normalized.indexOf('*')
+  const baseDir = normalized.slice(0, starIndex).replace(/\/$/, '')
+  const suffix = normalized.slice(starIndex + 1)
+
+  if (suffix && suffix !== '') {
+    return []
+  }
+
+  const absoluteBaseDir = path.join(root, baseDir)
+  if (!(await exists(absoluteBaseDir))) {
+    return []
+  }
+
+  try {
+    const entries = await fs.readdir(absoluteBaseDir, { withFileTypes: true })
+    return entries
+      .filter(entry => entry.isDirectory())
+      .map(entry => path.posix.join(baseDir, entry.name))
+  } catch {
+    return []
+  }
+}
+
+async function detectWorkspaceTargets(root: string): Promise<DetectionTarget[]> {
+  const patterns = await getWorkspacePackagePatterns(root)
+  if (patterns.length === 0) {
+    return []
+  }
+
+  const packagePaths = new Set<string>()
+  for (const pattern of patterns) {
+    const expanded = await expandWorkspacePattern(root, pattern)
+    for (const packagePath of expanded) {
+      packagePaths.add(packagePath)
+    }
+  }
+
+  return Array.from(packagePaths).map(packagePath => ({
+    packagePath,
+    absolutePath: path.join(root, packagePath),
+  }))
+}
+
 /**
  * Detect all build tools / meta-frameworks.
  * Returns supported tools and recognized-but-unsupported meta-frameworks.
@@ -138,7 +222,10 @@ export async function detectBuildTools(
 ): Promise<BuildToolResult> {
   const supported: BuildToolDetection[] = []
   const unsupported = new Set<string>()
-  const targets = createTargets(root, packagePaths)
+  const explicitTargets = createTargets(root, packagePaths)
+  const workspaceTargets =
+    !packagePaths || packagePaths.length === 0 ? await detectWorkspaceTargets(root) : []
+  const targets = workspaceTargets.length > 0 ? workspaceTargets : explicitTargets
 
   for (const target of targets) {
     const pkg = await readJSON<PackageJSON>(path.join(target.absolutePath, 'package.json'))
@@ -230,6 +317,7 @@ async function detectPattern({
   }
 
   let detectedFile = ''
+  let inferredFromScripts = false
 
   if (pattern.tool === 'esbuild' && !hasDep) {
     return null
@@ -274,6 +362,7 @@ async function detectPattern({
         }
 
         if (!detectedFile) {
+          inferredFromScripts = true
           detectedFile = 'package.json (scripts)'
           break
         }
@@ -282,6 +371,21 @@ async function detectPattern({
   }
 
   if (!detectedFile) {
+    if (
+      hasDep &&
+      (pattern.tool === 'rollup' ||
+        pattern.tool === 'webpack' ||
+        pattern.tool === 'rspack' ||
+        pattern.tool === 'esbuild')
+    ) {
+      // dependency present but no config/scripting evidence; provide low-confidence detection
+      return {
+        tool: pattern.tool,
+        configPath: 'package.json (dependency)',
+        label: `${pattern.label} (detected via dependency)`,
+        packagePath: packagePath || undefined,
+      }
+    }
     return null
   }
 
@@ -311,7 +415,7 @@ async function detectPattern({
     configPath: relativeConfig,
     label: `${pattern.label} (${relativeConfig})${isLegacyRspack ? ' [Legacy]' : ''}${
       isLegacyWebpack ? ' [Webpack 4]' : ''
-    }`,
+    }${inferredFromScripts ? ' [Scripts Detected]' : ''}`,
     isLegacyRspack,
     isLegacyWebpack,
     packagePath: packagePath || undefined,